docs(v2): PROTOTYPE — generate the CLI reference from the stash CLI#45
Draft
coderdan wants to merge 3 commits into
Draft
docs(v2): PROTOTYPE — generate the CLI reference from the stash CLI#45coderdan wants to merge 3 commits into
coderdan wants to merge 3 commits into
Conversation
PROTOTYPE for review. Generates /reference/cli from the shipped `stash` CLI so the reference can't drift from the actual command surface, and stamps every page with the CLI version it was generated from. - scripts/generate-cli-docs.ts — parses `stash --help` (captured to a fixture) into a manifest, then renders one page per top-level command (grouped Setup/Auth/Database/Schema/Encrypt/Deployment) with a "Generated from stash v0.16.0" banner, a verifiedAgainst.cli facet, and [cli] / [cli, eql] components per the content-model tagging rule. - `bun run generate-docs:cli` (package.json). - scripts/fixtures/stash-help-0.16.0.txt — captured input. - content/docs/reference/cli/* — generated output (10 command pages + index). Bootstrap note: `stash` 0.16.0 is a hand-rolled TS CLI with no machine-readable output and no per-command --help, so we parse the single top-level --help. Target: add `stash manifest --json` to the CLI, then swap loadManifest() to read it and delete the parser — the page format stays identical. Today's --help is thin (no args, no per-command examples, auth/encrypt subcommands undetailed); those gaps are exactly what the JSON manifest fills. Surfaces the drift too: 0.16.0 uses `db install` (not `eql install`) and has ~15 commands the hand-written pages never documented. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…build - Resolve the latest published version via `npm view stash version` and run that exact version live, so a new `stash` release refreshes the docs the next time the script runs (offline: falls back to the cached fixture). Removes the pinned CLI_VERSION constant. - Wire `generate-docs:cli` into `prebuild`, next to the EQL/TypeDoc generators, so every production build regenerates the CLI reference from the latest CLI. - Rename the fixture to a version-agnostic cache (scripts/fixtures/stash-help.txt). Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
…amples Adds a supplement hook to the CLI generator: an optional scripts/cli-supplements/<command>.md is merged after the generated reference (synopsis + flags), so the rich per-command narrative and curated examples the thin `stash --help` can't provide can be authored now, without waiting on the CLI. Supplements live outside content/ so they're never treated as pages or wiped by the clean step. Demonstrated on `auth` (device-code flow + keyset binding, grounded in the CLI source). Content-model direction: per-command reference detail (examples, flag help) should migrate into the CLI itself (long-help + examples, GitHub-CLI/cobra style) and be generated from there; cross-command conceptual narrative (the profile / workspace model) belongs in a linked CLI concept page. The supplement hook is the interim bridge and the seam for both. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
This was referenced Jul 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generates
/reference/clifrom the shippedstashCLI so the reference can't drift, per our discussion. Draft — approach review, not final content.Pipeline
scripts/generate-cli-docs.ts(bun run generate-docs:cli, wired intoprebuild):npm view stash version, runs that version's--helplive, stamps every page (verifiedAgainst.cli+ banner). Offline → cached fixture. A newstashrelease refreshes the docs on the next build.[cli]/[cli, eql]by the content-model rule; db flags resolved per-subcommand.Hybrid content (rich prose + examples)
The bare
--helpis thin. So the generator merges an optional hand-authored supplement (scripts/cli-supplements/<command>.md) after the generated skeleton — rich narrative + curated examples authored now, without waiting on the CLI. Demonstrated onauth(device-code flow + keyset binding). Supplements live outsidecontent/(never wiped/routed).Data source: bootstrap → target
Today we parse
stash --help(hand-written string in the CLI, the drift source; per-command--helpis inconsistent —authhas it,dbdoesn't). Target: addstash manifest --json+ proper per-command long-help/examples to the CLI (GitHub-CLI/cobra model), then swaploadManifest()to read it and delete the parser — page format unchanged. TheManifesttype here is the contract for that command. (Tracked separately for the stack repo.)Notes surfaced
eqlgroup (db install→eql install, withdbpush/validate/etc. remaining, and a--eql-version <2|3>flag). So docs(v2): renamedb→eqlCLI commands and move the CLI reference into /reference/cli #41's rename is ahead of the published 0.16.0; "always latest" picks it up when it ships.Open for review
db→eqlCLI commands and move the CLI reference into /reference/cli #41's hand-moved CLI pages (these supersede them).manifest --json— scope TBD.https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA