feat(cli): add "testsprite completion" for bash/zsh/fish

[Andy00L]

Reopens #184, which was closed by the July 9 release incident (see the
maintainer's comment there). Same branch, same commits (head df8b6766).

Adds testsprite completion [bash|zsh|fish]: prints a shell completion script.

Command names, per-group subcommands, and global flags are NOT hardcoded:
index.ts walks the fully-assembled Commander program (buildCompletionSpec) and
passes a CompletionSpec in, so the generated script can never drift from the
real command tree. renderCompletion is a pure function of the spec
(unit-testable without a live program). The shell auto-detects from $SHELL
when omitted.

Enable it:

eval "$(testsprite completion bash)"        # bash
testsprite completion zsh > ~/.zsh/_testsprite
testsprite completion fish | source         # fish

• New command: src/commands/completion.ts (pure renderers + $SHELL detect)
• 11 unit tests, fully offline

Fixes #74

Summary by CodeRabbit

• New Features

  • Added a new completion command to generate shell completion scripts.
  • Supports bash, zsh, and fish, with automatic shell detection when possible.
  • Completion output now includes available commands, subcommands, and global flags.

• Bug Fixes

  • Improves validation for unsupported or missing shells, returning a clear error when completion cannot be generated.

• Tests

  • Added coverage for shell detection, script rendering, and command behavior.

[coderabbitai]

Walkthrough

This PR adds a testsprite completion command supporting bash, zsh, and fish shell completion script generation. It introduces a CompletionSpec data model, shell detection/rendering utilities, Commander command wiring with validation, unit tests, and registration in the CLI entrypoint with a runtime spec builder.

Changes

Shell Completion Command

Layer / File(s)	Summary
Completion data model and shell utilities src/commands/completion.ts	Defines SUPPORTED_SHELLS, Shell type, CompletionSpec/CompletionDeps interfaces, and isShell/detectShell helpers.
Shell-specific script renderers src/commands/completion.ts	Implements renderCompletion dispatcher plus bash, zsh, and fish renderers producing completion script strings from a CompletionSpec.
Commander command wiring and validation src/commands/completion.ts	Adds createCompletionCommand, resolving shell from argument or $SHELL, throwing localValidationError on failure, and writing the rendered script to stdout.
CLI registration and spec builder src/index.ts	Registers the completion command and adds buildCompletionSpec() to derive commands, subcommands, and global flags from the assembled program.
Completion command tests src/commands/completion.test.ts	Adds tests for shell detection, script rendering per shell, and command behavior including validation error cases.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant createCompletionCommand
  participant renderCompletion

  User->>CLI: testsprite completion [shell]
  CLI->>createCompletionCommand: invoke with args
  createCompletionCommand->>createCompletionCommand: resolve shell (arg or detectShell(env))
  alt shell missing or unsupported
    createCompletionCommand-->>CLI: throw VALIDATION_ERROR
  else shell resolved
    createCompletionCommand->>renderCompletion: renderCompletion(shell, getSpec())
    renderCompletion-->>createCompletionCommand: script string
    createCompletionCommand->>CLI: write script to stdout
  end

Loading

Suggested reviewers: ruili-testsprite, zeshi-du

🚥 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 matches the main change: adding testsprite completion support for bash, zsh, and fish.
Linked Issues check	✅ Passed	The PR implements shell completion in completion.ts, auto-detects $SHELL, registers it in index.ts, and adds unit tests as required.
Out of Scope Changes check	✅ Passed	The changes stay focused on shell completion, its tests, and command registration with no obvious unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (2)

src/commands/completion.test.ts (2)

75-75: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider asserting stdout is never invoked on validation-error paths.

Both error-path tests pass stdout: () => undefined, discarding any calls. Asserting that stdout was not called before the rejection (e.g. via a spy) would strengthen the "machine output only goes to stdout on success" guarantee called out in the path instructions' output-discipline rule.

Also applies to: 82-82

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/completion.test.ts` at line 75, Strengthen the validation-error
tests in createCompletionCommand by asserting that the provided stdout handler
is never called on rejection paths, rather than using a no-op function. Update
the error-path cases in completion.test.ts to use a spy/mock for stdout and
verify it has zero calls when the command fails validation, keeping the
success-path behavior in createCompletionCommand and stdout output-discipline
explicitly covered.

Source: Path instructions

---

74-86: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Test titles claim exit code 5 but only assert the ApiError.code field, not the numeric exit code.

Both tests title-comment "(exit 5)" but only check code: 'VALIDATION_ERROR' on the rejected error. The path instructions require that error paths map to the documented exit code (5 for validation errors). Since this test never asserts the numeric exit code, the actual mapping from VALIDATION_ERROR → exit code 5 is unverified at this layer — a regression in the exit-code-mapping utility (e.g., in src/index.ts or an error-handling layer) wouldn't be caught here.

Consider either renaming the test titles to drop the misleading "(exit 5)" claim, or asserting the mapping directly if a helper (e.g. codeToExitCode) is exposed/testable.

As per path instructions, "Exit-code mapping: error paths must map to the documented exit code (see DOCUMENTATION.md / the exit-code table); don't introduce ad-hoc codes."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/completion.test.ts` around lines 74 - 86, The completion tests
currently mention “exit 5” in the titles but only assert ApiError.code, so they
do not verify the documented validation exit code mapping. Update the tests in
completion.test to either remove the exit-code claim from the titles or add an
assertion against the numeric exit-code mapping for VALIDATION_ERROR using the
relevant helper or error-handling path. Use the existing createCompletionCommand
and parseAsync cases to keep the checks aligned with the command’s validation
failure behavior.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/completion.test.ts`:
- Line 75: Strengthen the validation-error tests in createCompletionCommand by
asserting that the provided stdout handler is never called on rejection paths,
rather than using a no-op function. Update the error-path cases in
completion.test.ts to use a spy/mock for stdout and verify it has zero calls
when the command fails validation, keeping the success-path behavior in
createCompletionCommand and stdout output-discipline explicitly covered.
- Around line 74-86: The completion tests currently mention “exit 5” in the
titles but only assert ApiError.code, so they do not verify the documented
validation exit code mapping. Update the tests in completion.test to either
remove the exit-code claim from the titles or add an assertion against the
numeric exit-code mapping for VALIDATION_ERROR using the relevant helper or
error-handling path. Use the existing createCompletionCommand and parseAsync
cases to keep the checks aligned with the command’s validation failure behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3bdcef1b-59de-4a11-b63e-d4de4eade15b

📥 Commits

Reviewing files that changed from the base of the PR and between 3305dfa and df8b676.

⛔ Files ignored due to path filters (1)

• test/__snapshots__/help.snapshot.test.ts.snap is excluded by !**/*.snap, !**/*.snap

📒 Files selected for processing (3)

• src/commands/completion.test.ts
• src/commands/completion.ts
• src/index.ts