docs(cli): proposal — command-descriptor registry for help + stash manifest --json#558
Conversation
…anifest --json` Proposes replacing the hand-written HELP string in packages/cli/src/bin/main.ts with a per-command descriptor registry that renders the top-level help, consistent per-command `--help`, and a `stash manifest --json`. Fixes help/impl drift and inconsistent per-command help (auth has it, db/eql don't), and gives the docs generator (cipherstash/docs#45) and agents a structured, versioned command surface. Includes the manifest JSON contract, an `auth` worked example, GitHub-CLI prior art, and an incremental migration plan. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
|
📝 WalkthroughWalkthroughAdds a new documentation file proposing a command-descriptor registry for the stash CLI, replacing hand-written help text with structured descriptors, and introducing a ChangesProposal Document
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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.
Inline comments:
In `@docs/plans/cli-help-and-manifest.md`:
- Around line 83-85: Add a shell language tag to the markdown code fence in the
manifest example so it satisfies markdownlint MD040 and reads as a Bash snippet.
Update the fenced block around the `npx stash@<latest> manifest --json` example
in the docs file to use `bash` for the code fence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f2cebd28-7fcc-4323-a7da-b3bcc03e7bc6
📒 Files selected for processing (1)
docs/plans/cli-help-and-manifest.md
| ``` | ||
| npx stash@<latest> manifest --json | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language tag to this code fence.
Markdownlint flags this block (MD040), and marking it as shell improves readability.
Suggested fix
-```
+```bash
npx stash@<latest> manifest --json
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 83-83: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@docs/plans/cli-help-and-manifest.md` around lines 83 - 85, Add a shell
language tag to the markdown code fence in the manifest example so it satisfies
markdownlint MD040 and reads as a Bash snippet. Update the fenced block around
the `npx stash@<latest> manifest --json` example in the docs file to use `bash`
for the code fence.
Source: Linters/SAST tools
2 participants
Proposal / for discussion (a plan doc under
docs/plans/, no code yet).Why
The docs V2 CLI reference is generated from the
stashCLI (cipherstash/docs#45). Building it surfaced two problems worth fixing at the source:HELPstring inpackages/cli/src/bin/main.ts, separate from the command modules — so it lags real behaviour. (The publishedstash@0.16.0 --helpstill listsdb installwhilemain.tshas already moved it toeql install; docs generated from the published--helpwere a whole command surface behind.)authimplements its own--help;eql/db/most commands fall through to the top-level help. And there's no machine-readable output for docs/agents.What the proposal covers
A command-descriptor registry (one descriptor per command: summary,
long,examples, flags → points at the existing handler) that renders:--help(replacing the hand-written string),stash <command> --helpfor every command,stash manifest --json— the structured, versioned surface the docs generator and agents consume.Includes: the manifest JSON contract (exactly what cipherstash/docs#45 already targets — swapping to it deletes the docs-side
--helpparser), anauthworked example, the GitHub-CLI/cobra prior art and content split (per-command reference in the CLI; cross-command concepts in docs), and an incremental, non-breaking migration (add registry +manifest --jsonfirst → unblocks docs → migrate help rendering group by group).Full doc:
docs/plans/cli-help-and-manifest.md.Ask
Sanity-check the approach and the manifest schema. Once the additive step (registry +
manifest --json) lands, the docs flip from--help-scraping to the manifest with no format change.Related: cipherstash/docs#45 (the generator + hybrid supplement model).
https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
Summary by CodeRabbit
stashCLI help system.