fix(cli): emit one completion candidate per flag — collapse multi-line descriptions and restore --no-* text

[oekazuma]

Two protocol-level bugs in the new shell completion (#456), both reproduced end to end on the built binary:

1. Multi-line arg descriptions (e.g. `install --client`) were passed through verbatim; every continuation line became its own bogus candidate — `install --` offered ~33 prose fragments alongside 7 real flags. `forCompletion` now collapses descriptions to a single line (completion only; `--help` output is byte-identical, verified by diff).
2. `--no-color`/`--no-animation`/`--no-suppressions` showed a bare stripped key ("color") instead of their real descriptions: the completion plugin resolves a `no-*` key's description by looking up the stripped base key in the same args record. `forCompletion` now injects a phantom `type: 'positional'` entry under the stripped name carrying the real description — the completion engine lists only non-positional entries as flag candidates, so the phantom never surfaces (pinned by test: no `--color`/`--animation`/`--suppressions` candidates leak, and first-word candidates are unchanged). Descriptions remain sourced from `ROOT_ARGS` — no second copy. This deliberately relies on `@gunshi/plugin-completion@0.37.1` internals; the family is exact-pinned and its bumps are design-review events, and the new tests fail loudly if the behavior shifts.

Tests: two new in-process candidate-protocol tests (TDD-red proven via stash). Changeset: `svelte-vitals` patch. Plan: `plans/049-completion-candidate-stream.md` (advisor session 2026-08-12).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved shell completion candidates by excluding hidden and invalid entries.
  • Preserved descriptions for negated options such as --no-*.
  • Normalized multiline descriptions for clearer completion output.
  • Preserved positional arguments and correctly handled option names incompatible with shell completion.

• Tests

  • Added coverage to verify valid completion candidates, trailing directives, and negated-option descriptions.

• Chores

  • Prepared a patch release for svelte-vitals.

[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: ccd6a325-71e5-4af5-bef5-11d42ddb98d3

📥 Commits

Reviewing files that changed from the base of the PR and between f4b33ba and 2fedb4c.

📒 Files selected for processing (3)

• .changeset/curly-plums-drum.md
• packages/cli/src/gunshi/complete.ts
• packages/cli/test/gunshi-complete.test.ts

---

📝 Walkthrough

Walkthrough

The CLI completion adapter now produces normalized, valid candidates for positional and option arguments. It handles hidden entries and negated flags without exposing phantom candidates. Tests verify install completion output and a patch changeset documents the fixes.

Changes

CLI completion metadata corrections

Layer / File(s)	Summary
Normalize completion candidates packages/cli/src/gunshi/complete.ts, .changeset/curly-plums-drum.md	The adapter collapses multiline descriptions, preserves positional keys, converts option keys, filters hidden entries, and adds hidden phantom entries for missing no-* base keys. The changeset records a patch release.
Validate install completion output packages/cli/test/gunshi-complete.test.ts	Tests verify valid install candidates, candidate counts, directive formatting, normalized descriptions, and correct --no-* descriptions without phantom base-key candidates.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• oekazuma/svelte-vitals#454: Modifies Gunshi CLI completion and help metadata, including no-* option handling.
• oekazuma/svelte-vitals#456: Introduces related completion implementation and test changes.
• oekazuma/svelte-vitals#458: Processes shared CLI argument declarations, hidden flags, kebab-casing, and descriptions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 both primary completion fixes: single candidates per flag and restored descriptions for --no-* options.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 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.