fix(cli): per-command --help from the registry + slim global banner

[coderdan]

What

stash <command> --help displayed the global banner instead of help for that command. Reported from testing the 0.17 CLI:

$ npx stash eql --help
CipherStash CLI v0.17.0
Usage: npx stash <command> [options]
... (the entire global banner) ...

Root cause: run() in bin/main.ts checked flags.help before dispatching, so --help always rendered the global HELP string — shadowing even the auth command's own existing help.

Changes

• Per-command help, rendered from the registry. New src/cli/help.ts renders stash <command> --help from the command-descriptor registry (src/cli/registry.ts) — the same source stash manifest uses, so they can't drift.
  • Leaf command (eql install, auth login, init) → usage, summary, long description, an Options: table (with <value> placeholders, (default: …) and Also settable via ENV. annotations), and Examples:.
  • Command group (eql, auth, db, encrypt, schema) → a subcommand listing that points at each subcommand's own --help.
  • Unknown path → falls back to the global banner.
• -h works after a command too. parseArgs only recognised the long --help; stash eql install -h silently fell through and tried to run the command. Short -h/-v are now normalised to flags.help/flags.version.
• Slimmed the global banner. Dropped the six hand-maintained per-command flag sections (~65 lines, now redundant with per-command help) and trimmed the examples. The banner (stash --help) went from ~120 to ~45 lines: command list + a pointer to <command> --help.
• Doc fix. Updated the registry.ts header comment — the registry now feeds both stash manifest and per-command --help; the only hand-maintained surface left is the banner's command list.

This is the documented follow-on to the manifest/registry work (docs/plans/cli-help-and-manifest.md), which noted --help would later render from the descriptors.

Before / after

# before
$ npx stash eql --help
<entire global banner>

# after
$ npx stash eql --help
Usage: npx stash eql <command> [options]

Commands:
  eql install   Scaffold stash.config.ts (if missing) and install EQL extensions
  eql upgrade   Upgrade EQL extensions to the latest version
  eql status    Show EQL installation status

Run `npx stash eql <command> --help` for details on a command.

Tests

• src/cli/__tests__/help.test.ts (new, 8) — renderer unit tests.
• tests/e2e/command-help.e2e.test.ts (new, 5) — e2e routing against the built binary: group listing, full command help, the -h short flag, and both fallback paths.
• Repointed the auth/impl banner assertions at the per-command help that now owns that detail.

All 390 unit + 49 e2e tests pass; Biome clean. Pre-existing unrelated tsc errors (auth WASM types, backfill, etc.) are untouched.

Changeset: stash patch.

Closes #577.

Summary by CodeRabbit

• New Features

  • stash <command> --help now shows help specific to that command, including usage, options, examples, and subcommand lists where relevant.
  • -h now works after a command path, such as stash eql install -h.

• Bug Fixes

  • The top-level stash --help screen now points users to command-specific help instead of listing every flag inline.
  • Help output now correctly falls back to the global banner for unknown command paths.

[changeset-bot]

🦋 Changeset detected

Latest commit: cbece82

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
stash	Patch
@cipherstash/e2e	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces registry-driven per-command --help rendering for the CLI via a new help.ts module exporting renderCommandHelp. main.ts is updated to recognize -h/-v short flags, route --help through command-specific rendering with fallback to a trimmed global banner, and the registry comment and tests (unit and e2e) are updated accordingly.

Changes

Per-command help rendering

Layer / File(s)	Summary
Command help rendering module packages/cli/src/cli/help.ts, packages/cli/src/cli/__tests__/help.test.ts	New module formats flags, options, examples, and renders leaf-command or group help via exported renderCommandHelp(path, runner), with unit tests covering all branches.
CLI entrypoint wiring and flag parsing packages/cli/src/bin/main.ts, packages/cli/src/cli/registry.ts, .changeset/stash-cli-per-command-help.md	main.ts recognizes -h/-v, dispatches to renderCommandHelp with fallback to a trimmed global HELP banner; registry comment and changeset updated to describe the new behavior.
E2E test updates for per-command help packages/cli/tests/e2e/command-help.e2e.test.ts, packages/cli/tests/e2e/auth-non-interactive.e2e.test.ts, packages/cli/tests/e2e/impl-non-tty.e2e.test.ts	New and updated e2e tests validate group/leaf help output, -h after a command, unknown-command fallback, and updated auth/impl help expectations.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant mainTs as main.ts run()
  participant renderCommandHelp
  participant registry

  User->>mainTs: stash <command> --help / -h
  mainTs->>mainTs: parseArgs sets flags.help
  mainTs->>mainTs: build command path from command/subcommand
  mainTs->>renderCommandHelp: renderCommandHelp(path, STASH)
  renderCommandHelp->>registry: lookup exact or prefix match
  registry-->>renderCommandHelp: descriptor(s) or none
  renderCommandHelp-->>mainTs: rendered help text or null
  mainTs-->>User: print command help or fallback global HELP banner

Loading

Possibly related PRs

• cipherstash/stack#516: Both PRs modify help/-h/--help parsing and dispatch logic in packages/cli/src/bin/main.ts.
• cipherstash/stack#543: Per-command help routing added here is validated against the stash eql command group introduced in that PR.
• cipherstash/stack#558: Implements the registry-driven help/manifest design proposed in that PR.

Suggested reviewers: calvinbrewer, auxesis

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: per-command help sourced from the registry and a slimmer global banner.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/cli-per-command-help

---

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

[Copilot]

Pull request overview

This PR fixes stash <command> --help so it renders command-specific help (from the CLI command-descriptor registry) instead of always showing the global banner, and trims the global stash --help output accordingly.

Changes:

• Add a registry-driven per-command help renderer (renderCommandHelp) and route --help/-h to it after command dispatch is known.
• Normalize short flags -h / -v into flags.help / flags.version so help/version work after a command path.
• Add unit + E2E coverage for per-command help routing and update existing E2E assertions to match the slimmer global banner.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/cli/src/bin/main.ts	Routes --help to per-command renderer post-dispatch; normalizes -h/-v; slims global HELP banner content.
packages/cli/src/cli/help.ts	New registry-driven renderer for leaf-command help and command-group listings.
packages/cli/src/cli/registry.ts	Updates header comment to reflect registry now drives both manifest and per-command help.
packages/cli/src/cli/tests/help.test.ts	New unit tests for help rendering behavior (leaf, group, env/default annotations, fallback).
packages/cli/tests/e2e/command-help.e2e.test.ts	New E2E tests validating routing behavior and fallback to global help.
packages/cli/tests/e2e/auth-non-interactive.e2e.test.ts	Updates assertions to reflect slim global banner + per-command help ownership.
packages/cli/tests/e2e/impl-non-tty.e2e.test.ts	Updates assertion to check impl --help output for --target docs.
.changeset/stash-cli-per-command-help.md	Changeset describing the help behavior change and global banner slimming.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderdan]

Low-risk, help/docs focused. Thoroughly AI reviewed and checked by author.