docs(v2): generate the CLI reference from `stash manifest --json` by coderdan · Pull Request #45 · cipherstash/docs

coderdan · 2026-07-05T13:04:36Z

Generates /reference/cli from the shipped stash CLI so the reference can't drift from the real command surface.

Update (stash CLI 0.17): the CLI now ships stash manifest --json — the structured, versioned command surface it builds from its own command registry. This PR now consumes that directly, which was the stated target. The --help text parser is deleted.

Pipeline

scripts/generate-cli-docs.ts (bun run generate-docs:cli, wired into prebuild):

Data source: loadManifest() runs npx stash@<version> manifest --json and projects it onto the renderer's model. Nav groups and their order come straight from the CLI (no hardcoded group map). Offline → cached scripts/fixtures/stash-manifest.json.
Always tracks the latest published version — resolves npm view stash version, runs that version's manifest --json, stamps every page (verifiedAgainst.cli + banner). A new stash release refreshes the docs on the next build.
Richer per-command detail now available from the manifest: each command's flags carry default and env (folded into the flag description), and curated examples come straight from the CLI. Pipes in flag values (--eql-version <2|3>) are escaped so the GFM table renders.
One page per top-level command; [cli] / [cli, eql] by the content-model rule.

Generated against 0.17.0

New EQL group → eql.mdx (eql install / eql upgrade / eql status), and db.mdx no longer lists install/upgrade (they moved to the eql group in the CLI).
New doctor and manifest pages; env under Experimental.
13 command pages + index + meta, all stamped cli: "0.17.0".

Hybrid content (rich prose)

The per-command supplement hook (scripts/cli-supplements/<command>.md, merged after the generated skeleton) is retained and still demonstrated on auth (device-code flow + keyset binding). The manifest also now carries long (multi-paragraph help) for some commands (init, auth login, manifest) — rendering that into the pages is a natural follow-up, deferred here to keep the page format stable.

Validation

bun run types:check passes (fumadocs-mdx + next typegen + tsc).
Generator lints clean apart from pre-existing noNonNullAssertion style warnings shared with the original. (The branch's other Biome errors are pre-existing SVG-a11y issues fixed later on v2; they clear on rebase.)

Open for review

Reference vs guide split — deferred per your call (lifecycle narratives fold into Getting started / Migration guides later).
Reconcile with docs(v2): rename db→eql CLI commands and move the CLI reference into /reference/cli #41's hand-moved CLI pages (these supersede them).
Minor: some CLI flag descriptions contain em-dashes (e.g. --database-url "…for this run only — never written to disk"), emitted verbatim from the CLI registry. If we want those out of the docs (per the em-dash preference), the clean fix is in the CLI's registry text upstream, not a generator-side rewrite — flagging for a call.

vercel · 2026-07-05T13:04:40Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, ✅ 2 resolved	Jul 8, 2026 8:10am

…-3431) Phase 1 of docs/plans/cli-help-and-manifest.md: a single source of truth for command metadata so help/docs can't drift from the real command set. - src/cli/registry.ts: Flag/CommandDescriptor/CommandGroup types + the full command surface (groups, summaries, flags; long/examples for key commands), populated from the existing HELP surface and per-command flag parsing. - src/cli/manifest.ts: buildManifest(version) → { name, version, groups[] }, the exact contract the docs generator (cipherstash/docs#45) targets. version comes from the CLI's package.json. - `stash manifest --json` emits the structured surface; `stash manifest` prints a grouped human-readable list. Pure metadata — no native binary required. Additive and non-breaking; the top-level HELP string is untouched. Rendering help from the registry (phases 2–4) is the documented follow-on. Tests: unit coverage for buildManifest shape/version/hidden-exclusion; e2e for `manifest --json`, `manifest`, and `--help` listing the command.

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

…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

stash CLI 0.17 ships the `manifest` command (structured, versioned command surface), so swap the generator off `--help` scraping onto `stash manifest --json` and delete the text parser — the realization of this PR's stated target. - loadManifest() now runs `npx stash@<version> manifest --json` and projects it onto the renderer's model; nav groups + order come straight from the CLI. - Per-command flags carry their `default` and `env` (folded into the flag description); examples come from the manifest. Pipes in flag values (`--eql-version <2|3>`) are escaped so the GFM table renders. - Fixture swapped from stash-help.txt to stash-manifest.json. - Regenerated against 0.17.0: new `eql` group (eql install/upgrade/status), new `doctor` + `manifest` pages, `db` no longer lists install/upgrade. types:check passes; generator lints clean (bar pre-existing noNonNullAssertion style warnings shared with the original).

The `auth regions --json` flag description is "Emit machine-readable [{ slug, label }] ...". MDX parsed `{ slug, label }` as a JS expression, so prerendering /reference/cli/auth threw `ReferenceError: slug is not defined` and failed the build. (The earlier `<tt>` failure masked this; it surfaced once #52 landed via rebase.) Escape `{`/`}` (and stray `<`) in manifest-derived prose — flag descriptions and summaries. Flag names/values stay in code spans, which are literal, so they're untouched. Verified: `next build` prerenders all 355 pages, including /reference/cli/auth.

Copilot

Pull request overview

This PR adds a generator that produces the v2 /reference/cli docs directly from the shipped stash CLI’s structured stash manifest --json output, aiming to prevent the CLI reference from drifting from the actual command surface.

Changes:

Add scripts/generate-cli-docs.ts to fetch the latest published stash version, read manifest --json, and render MDX pages + meta.json for /content/docs/reference/cli.
Wire the generator into prebuild and add a generate-docs:cli package script.
Add a cached fixture (scripts/fixtures/stash-manifest.json) and a supplements mechanism (scripts/cli-supplements/<command>.md) to merge hand-authored prose after generated content.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/generate-cli-docs.ts	New CLI-doc generator consuming `stash manifest --json`, rendering reference pages + meta.
scripts/fixtures/stash-manifest.json	Cached manifest fixture for offline/failed CLI execution scenarios.
scripts/cli-supplements/auth.md	Hand-authored supplemental prose merged into the generated `auth` page.
package.json	Adds `generate-docs:cli` and runs it during `prebuild`.
content/docs/reference/cli/index.mdx	Generated CLI reference index page listing commands by manifest group.
content/docs/reference/cli/meta.json	Generated nav/meta describing CLI pages grouped by manifest order.
content/docs/reference/cli/auth.mdx	Generated `auth` group page + merged supplement content.
content/docs/reference/cli/db.mdx	Generated `db` group page from manifest.
content/docs/reference/cli/doctor.mdx	Generated `doctor` command page from manifest.
content/docs/reference/cli/encrypt.mdx	Generated `encrypt` group page from manifest.
content/docs/reference/cli/env.mdx	Generated `env` command page from manifest.
content/docs/reference/cli/eql.mdx	Generated `eql` group page from manifest.
content/docs/reference/cli/impl.mdx	Generated `impl` command page from manifest.
content/docs/reference/cli/init.mdx	Generated `init` command page from manifest.
content/docs/reference/cli/manifest.mdx	Generated `manifest` command page from manifest.
content/docs/reference/cli/plan.mdx	Generated `plan` command page from manifest.
content/docs/reference/cli/schema.mdx	Generated `schema` group page from manifest.
content/docs/reference/cli/status.mdx	Generated `status` command page from manifest.
content/docs/reference/cli/wizard.mdx	Generated `wizard` command page from manifest.

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

Vercel preview feedback on /reference/cli/auth: - Remove the "--supabase / --drizzle flags only tag the referrer" paragraph. - Convert the "Good to know" blockquote into a proper <Callout title=...>. Edited the auth supplement (the page is generated from it) and recast the em-dashes in the touched prose. Verified: next build prerenders all 355 pages.

- loadRawManifest: validate the JSON delimiters before slicing, throwing a clear error (which falls back to the fixture) instead of feeding garbage to JSON.parse. - Reconcile CLI_VERSION to the loaded manifest's version after loading, so pages are stamped with the version of the data actually used — including the fixture-fallback path, where npm-latest and the cached manifest can differ.

vercel Bot deployed to Preview July 5, 2026 13:04 View deployment

vercel Bot deployed to Preview July 5, 2026 13:24 View deployment

vercel Bot deployed to Preview July 5, 2026 13:31 View deployment

coderdan force-pushed the docs/v2-cli-generator branch from db331b9 to f29a71a Compare July 6, 2026 13:52

vercel Bot deployed to Preview July 6, 2026 13:53 View deployment

coderdan changed the title ~~docs(v2): PROTOTYPE — generate the CLI reference from the stash CLI~~ docs(v2): generate the CLI reference from stash manifest --json Jul 8, 2026

vercel Bot had a problem deploying to Preview July 8, 2026 06:34 Failure

coderdan mentioned this pull request Jul 8, 2026

fix(eql-docs): strip Doxygen <tt> tags so a stray one can't break the build #52

Merged

coderdan added 4 commits July 8, 2026 17:04

coderdan force-pushed the docs/v2-cli-generator branch from f6797a7 to 6a7ac7b Compare July 8, 2026 07:05

vercel Bot had a problem deploying to Preview July 8, 2026 07:06 Failure

vercel Bot deployed to Preview July 8, 2026 07:32 View deployment

coderdan marked this pull request as ready for review July 8, 2026 07:33

coderdan requested a review from Copilot July 8, 2026 07:55

Copilot started reviewing on behalf of coderdan July 8, 2026 07:55 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread content/docs/reference/cli/encrypt.mdx

Comment thread scripts/generate-cli-docs.ts

vercel Bot deployed to Preview July 8, 2026 08:04 View deployment

vercel Bot deployed to Preview July 8, 2026 08:10 View deployment

coderdan merged commit f736ffa into v2 Jul 8, 2026
2 checks passed

coderdan mentioned this pull request Jul 8, 2026

chore(cli-docs): drop the internal tracker ref from the generator header #53

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(v2): generate the CLI reference from `stash manifest --json`#45

docs(v2): generate the CLI reference from `stash manifest --json`#45
coderdan merged 7 commits into
v2from
docs/v2-cli-generator

coderdan commented Jul 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

coderdan commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pipeline

Generated against 0.17.0

Hybrid content (rich prose)

Validation

Open for review

Uh oh!

vercel Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderdan commented Jul 5, 2026 •

edited

Loading

vercel Bot commented Jul 5, 2026 •

edited

Loading