Add eager --completions flag and .help() config builder

[kjanat]

Summary

This PR introduces two major features to enhance CLI customization:

1. Eager --completions <shell> flag — An alternative to the completions subcommand that exposes shell completion as a root-level flag, ideal for single-command CLIs. The planner intercepts the flag before dispatch, auto-detects the shell from the environment if needed, and prints the completion script.

2. .help() builder method — Allows configuration of root-help rendering behavior through inlineDefault, showDefaultInCommands, and footer options, merged under runtime options.help.

3. Shell normalization and detection helpers — Exported normalizeShell() and detectShell() functions that parse shell tokens (bare names, $SHELL paths, Windows executables) and auto-detect from environment variables.

Key Changes

• .completions({ as: 'flag' }) — New option to register completion as an eager flag instead of a subcommand. When active, the planner intercepts --completions [shell] before dispatch and generates the script. Root help advertises the flag in its Flags: section.

• Shell auto-detection — --completions without a value resolves the target shell from the environment: $SHELL (parsed as an interpreter path) wins when it names a supported shell; otherwise $PSModulePath presence selects PowerShell (the reliable signal for pwsh).

• .help(config) builder — New method to configure root-help defaults. Accepts inlineDefault (render default command's args/flags inline), showDefaultInCommands (list default in Commands table), footer (show help hint), plus existing width/hyperlinks. Builder config merges under runtime options.help (runtime wins).

• Default command as root surface — BREAKING: .default(cmd) now registers the command only as the default, not as a named subcommand. It is the CLI's root surface (its args/flags render inline in help) and is omitted from the Commands: list by default. This change allows a single-command CLI with .completions({ as: 'flag' }) to keep the root clean.

• Root help refactoring — formatRootHelp() now handles inline default rendering, completions flag advertisement, and configurable footer/command listing. Helper functions resolveSurfaceCommand() and completionsFlagSchema() build the synthetic flag schema for help display.

• Planner enhancements — New planCompletionsFlag() function detects and validates the eager flag before dispatch, with proper error handling for unknown shells and support for --completions=<shell> syntax.

• Root surface normalization — RootSurface interface now distinguishes visibleSubcommands (real commands, excluding default) from visibleCommands (all declared commands), with boolean flags hasVisibleSubcommands and hasVisibleDefault.

Implementation Details

• The eager completions flag is stored in CLISchema.completionsFlag and passed to the planner for interception.
• Help configuration is stored in CLISchema.helpConfig and merged with runtime options in formatRootHelp().
• Shell normalization handles pwsh ↔ powershell aliasing and strips Windows executable extensions.
• The synthetic completions flag schema is built on-demand in resolveSurfaceCommand() so it only appears in help when configured.
• Comprehensive test coverage added in cli-completions-flag.test.ts covering registration, interception, auto-detection, and help rendering.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• cr:review

🚫 Excluded labels (none allowed) (2)

• wip
• cr:skip

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: f1490264-d3f3-4e61-b7a2-50aa3cc04176

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds an eager root --completions <shell> mode with shell normalisation and environment-based detection. It also changes .default() so the default command is treated as the root surface rather than a named route, and updates root help rendering to support inline default behaviour and configurable help options. Tests and release docs were updated to match the new routing, help, and completion behaviour.

Sequence Diagram(s)

sequenceDiagram
  participant CLIBuilder
  participant planInvocation
  participant execute
  participant detectShell
  CLIBuilder->>planInvocation: argv + schema
  planInvocation->>planInvocation: intercept --completions
  planInvocation-->>execute: root-completions outcome
  execute->>detectShell: detect shell from env if needed
  detectShell-->>execute: resolved shell
  execute->>execute: emit script or JSON

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• kjanat/dreamcli#1: Shares the completion-generation path and shell handling that this PR extends with eager root-flag support.
• kjanat/dreamcli#7: Touches the same planner.ts, root-help.ts, and default-command dispatch areas now reshaped here.
• kjanat/dreamcli#37: Also changes default-command routing and root dispatch behaviour in the CLI planner.

Suggested labels

kind: feature, kind: breaking, area: cli, area: completion

Arrr, the root be speaking now.
--completions boards first, before the -- tide.
The default sails as the surface, not a hidden berth.
Help curls tight and tidy, like a well-kept map.
And shell names? Aye, they be sorted properly.

🚥 Pre-merge checks | ✅ 10 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title matches the change, but it misses the required conventional commit style: it should start with a lowercase prefix like add:.	Rename it to something like add: eager --completions flag and .help() config builder.

✅ Passed checks (10 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly matches the CLI completions and help builder changes in the patch.
Docstring Coverage	✅ Passed	Docstring coverage is 73.91% which is sufficient. The required threshold is 30.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Release Metadata Sync	✅ Passed	package.json and deno.json both declare 3.0.0; CHANGELOG.md has a 3.0.0 heading and matching [Unreleased]/[3.0.0] compare links.
Runtime Support Sync	✅ Passed	No runtime support minima/claims changed; Node 22.22.2, Bun 1.3, and Deno 2.6.0 stay aligned across package.json, support.ts, README, and docs.
No Generated Docs Artifacts	✅ Passed	No changed files fall under docs/.vitepress/dist/ or docs/.vitepress/cache/; the diff only touches source/docs files elsewhere.
Changelog Update	✅ Passed	package.json and deno.json are bumped to 3.0.0, and CHANGELOG.md has ## [3.0.0] - 2026-06-29 with Added/Changed sections.
Semver Version Bump Validation	✅ Passed	PASS: package.json and deno.json are bumped to 3.0.0, and the diff includes breaking CLI API changes (.default() no longer a named subcommand), so a MAJOR bump fits.
Agents.Md Documentation Updated	✅ Passed	PASS: the PR updates AGENTS.md for every affected area, including src/core/cli, completion, help and json-schema, plus the repo root.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

bun add https://pkg.pr.new/@kjanat/dreamcli@43

npm i https://pkg.pr.new/@kjanat/dreamcli@43

commit: 703a0ae

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
🚫 Deployment cancelled View logs	dreamcli	703a0ae	Jun 30 2026, 11:05 AM