feat(cli): add shell completion generated from the argument declarations

[oekazuma]

gunshi adoption item 1 (per the approved utilization plan): shell completion for bash/zsh/fish/PowerShell via @gunshi/plugin-completion (0.37.1, exact pin), surfaced as a new svelte-vitals complete <shell> command.

Design (probe-driven)

The Phase-A compatibility probe found that wiring the plugin into an existing surface silently breaks behavior — on docs, the plugin's auto-added complete sub-command shadowed the "unknown docs subcommand" exit-2 path with a bare directive on stdout, exit 0. So the integration is a dedicated sixth entry: a completion-only define() tree mirroring all five real surfaces, dispatched by an exact-match complete branch in runCli (lazy-loaded; the analyzer hot path pays nothing), with no-op runners the plugin never executes. docs complete still errors exactly as before — verified.

No second flag declaration anywhere: the tree is built from the same exported *_ARGS consts that drive parsing and --help, and enum value completion (--reporter, --fail-on, --category, --treat-dynamic-as) reuses newly single-sourced value arrays (REPORTER_NAMES etc. — isReporterName now derives from the same array). Two plugin gotchas found and fixed: it reads raw object keys with no toKebab/hidden awareness, which would have leaked --noSuppressions and the hidden --scope — a forCompletion() transform normalizes both.

What completes

Sub-command names (incl. nested list/show/install/upgrade), every flag per surface (context-correct: ci upgrade excludes --force), and enum values. Setup verified end-to-end in real bash and zsh shells against the built dist; fish/PowerShell instructions come from the plugin's README and are marked as such in the docs (en/ja).

Honest dependency footprint (declared in the changeset + design-doc addendum)

Not one package: @gunshi/plugin-completion brings @gunshi/plugin, @bomb.sh/tab, and a non-optional peer dependency on @gunshi/plugin-i18n that installs even though this integration never uses it. All 0.37.1 lockstep, exact-pinned.

Verification

Characterization suite: zero behavioral churn — the only golden change is one new Usage line in root --help. 20 new tests (tree shape, kebab/hidden normalization, value completion, dispatch precedence, spawn-based dist checks). Full gates green: 2,701 tests, e2e 10/10, smoke 8/8, check:publish 0. Rebased onto #455 (both touched reporter-resolve.ts; the delegation and the REPORTER_NAMES single-sourcing compose — full suite re-run post-rebase).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added the complete command for Bash, Zsh, Fish, and PowerShell.
  • Added completion for commands, flags, subcommands, and supported option values.
  • Added shell-specific installation guidance and regeneration instructions.

• Documentation

  • Documented shell completion in English and Japanese CLI guides.
  • Updated command-line help to include the new completion command.

• Tests

  • Added coverage for completion scripts, command dispatch, invalid shells, nested options, and packaged execution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c6a3deb2-9ddf-45bb-b02b-977feed6ea81

📥 Commits

Reviewing files that changed from the base of the PR and between 04df077 and 7e1991c.

⛔ Files ignored due to path filters (2)

• packages/cli/test/__snapshots__/help-golden.test.ts.snap is excluded by !**/*.snap
• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (16)

• .changeset/shell-completion.md
• docs/src/content/docs/guides/(setup)/cli.md
• docs/src/content/docs/ja/guides/(setup)/cli.md
• docs/superpowers/specs/2026-08-10-gunshi-cli-migration-design.md
• packages/cli/package.json
• packages/cli/src/cli.ts
• packages/cli/src/gunshi/analyze.ts
• packages/cli/src/gunshi/ci.ts
• packages/cli/src/gunshi/complete.ts
• packages/cli/src/gunshi/docs.ts
• packages/cli/src/gunshi/explain.ts
• packages/cli/src/gunshi/install.ts
• packages/cli/src/reporter-resolve.ts
• packages/cli/src/resolve-args.ts
• packages/cli/test/gunshi-complete.test.ts
• pnpm-workspace.yaml

---

📝 Walkthrough

Walkthrough

The CLI adds a lazily loaded complete subcommand for Bash, Zsh, Fish, and PowerShell. It reuses exported argument schemas and shared enum values, validates shell requests, generates completion scripts and candidates, and documents installation.

Changes

Shell completion

Layer / File(s)	Summary
Shared completion contracts packages/cli/src/gunshi/analyze.ts, packages/cli/src/gunshi/ci.ts, packages/cli/src/gunshi/docs.ts, packages/cli/src/gunshi/explain.ts, packages/cli/src/gunshi/install.ts, packages/cli/src/reporter-resolve.ts, packages/cli/src/resolve-args.ts	CLI commands now expose reusable argument definitions and shared completion value sets.
Completion command and dispatch packages/cli/src/gunshi/complete.ts, packages/cli/src/cli.ts, packages/cli/package.json, pnpm-workspace.yaml, docs/superpowers/specs/2026-08-10-gunshi-cli-migration-design.md, packages/cli/src/gunshi/analyze.ts	A separate Gunshi completion tree supports shell setup and callback requests. runCli lazily dispatches the command, and the completion dependency is registered.
Completion validation and integration tests packages/cli/test/gunshi-complete.test.ts	Tests cover shell validation, generated scripts, candidates, dispatch, reserved-token handling, and packaged binaries.
Completion documentation and release note docs/src/content/docs/guides/(setup)/cli.md, docs/src/content/docs/ja/guides/(setup)/cli.md, .changeset/shell-completion.md	The CLI guides describe supported shells, installation, regeneration, completed values, and directory handling. The changeset records the command.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant runCli
  participant runCompleteCliGunshi
  participant GunshiCompletionPlugin
  User->>runCli: invoke complete with arguments
  runCli->>runCompleteCliGunshi: pass full argument vector
  runCompleteCliGunshi->>GunshiCompletionPlugin: process shell setup or callback
  GunshiCompletionPlugin-->>User: output completion script or candidates

Loading

Possibly related PRs

• oekazuma/svelte-vitals#448: Defines the Gunshi CLI architecture extended by this completion command.
• oekazuma/svelte-vitals#449: Introduces the dispatcher and exit handling used by complete.
• oekazuma/svelte-vitals#452: Introduces the shared Gunshi command schemas reused for completion.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding shell completion generated from CLI argument declarations.
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.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[oekazuma]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.