Skip to content

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

Open
coderdan wants to merge 5 commits into
v2from
docs/v2-cli-generator
Open

docs(v2): generate the CLI reference from stash manifest --json#45
coderdan wants to merge 5 commits into
v2from
docs/v2-cli-generator

Conversation

@coderdan

@coderdan coderdan commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

  1. Reference vs guide split — deferred per your call (lifecycle narratives fold into Getting started / Migration guides later).
  2. 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).
  3. 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

vercel Bot commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
public-docs Ready Ready Preview, 💬 2 unresolved Jul 8, 2026 7:37am

Request Review

This was referenced Jul 5, 2026
Merged
Closed
Open
@coderdan coderdan force-pushed the docs/v2-cli-generator branch from db331b9 to f29a71a Compare July 6, 2026 13:52
coderdan added a commit to cipherstash/stack that referenced this pull request Jul 8, 2026
@coderdan
feat(cli): command-descriptor registry + stash manifest --json (CIP…
715e489 
…-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.
coderdan added a commit to cipherstash/stack that referenced this pull request Jul 8, 2026
@coderdan
feat(cli): command-descriptor registry + stash manifest --json (CIP…
5e23384 
…-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.
@coderdan 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
@coderdan coderdan mentioned this pull request Jul 8, 2026
Merged
coderdan added 4 commits July 8, 2026 17:04
@coderdan
docs(v2): prototype — generate the CLI reference from stash --help
ccca2e5 
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
@coderdan
docs(v2): CLI generator tracks latest published stash + wire into pre…
7371257 
…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
@coderdan
docs(v2): hybrid CLI reference — merge hand-authored supplements + ex…
22dd036 
…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
@coderdan
docs(cli): generate the CLI reference from stash manifest --json
6a7ac7b 
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).
@coderdan coderdan force-pushed the docs/v2-cli-generator branch from f6797a7 to 6a7ac7b Compare July 8, 2026 07:05
@coderdan
fix(cli-docs): escape MDX braces in manifest-derived prose
40ee221 
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.
@coderdan coderdan marked this pull request as ready for review July 8, 2026 07:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@coderdan