feat(cli): command-descriptor registry + stash manifest --json

.changeset/stash-cli-manifest.md

@@ -0,0 +1,18 @@
+---
+"stash": minor
+---
+
+Add a command-descriptor registry and `stash manifest --json` — a structured,
+versioned command surface for the docs generator and agents to consume instead
+of scraping `--help`.
+
+- `stash manifest --json` emits `{ name, version, groups[] }`, where each command
+  carries its summary, optional long description, examples, and flags. `version`
+  comes from the CLI's own `package.json`, so a page generated from the manifest
+  is always stamped with the version it describes.
+- `stash manifest` (no flag) prints a grouped, human-readable command list.
+- The registry (`src/cli/registry.ts`) is intended to become the single source of
+  truth for command metadata. This is phase 1 of
+  `docs/plans/cli-help-and-manifest.md`; it is additive — `bin/main.ts` still
+  hand-maintains the `HELP` string that renders `--help`, so until the documented
+  follow-on renders `--help` from the registry the two are kept in sync by hand.

packages/cli/src/bin/main.ts

@@ -27,6 +27,7 @@ import {
   implCommand,
   initCommand,
   installCommand,
+  manifestCommand,
   planCommand,
   statusCommand,
   testConnectionCommand,
@@ -89,6 +90,7 @@ Commands:
   auth <subcommand>    Authenticate with CipherStash
   wizard               AI-guided encryption setup (reads your codebase)
   doctor               Diagnose install problems (native binaries, runtime)
+  manifest             Print the structured, versioned command surface (--json for docs/agents)
 
   eql install          Scaffold stash.config.ts (if missing) and install EQL extensions
   eql upgrade          Upgrade EQL extensions to the latest version
@@ -195,6 +197,7 @@ Examples:
   ${STASH} db push
   ${STASH} schema build
   ${STASH} doctor
+  ${STASH} manifest --json                        # structured command surface for docs / agents
 `.trim()
 
 interface ParsedArgs {
@@ -519,6 +522,11 @@ export async function run() {
     case 'env':
       await envCommand({ write: flags.write })
       break
+    case 'manifest':
+      // Pure metadata (no native code) — safe to run anywhere, including when
+      // the native binary is missing.
+      manifestCommand({ json: flags.json, version: pkg.version })
+      break
     case 'wizard': {
       // Forward everything after `stash wizard` verbatim. The wizard package
       // owns its own flag parsing; we don't try to interpret its surface

packages/cli/src/cli/__tests__/manifest.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import { buildManifest } from '../manifest.js'
+import { type CommandGroup, registry } from '../registry.js'
+
+describe('buildManifest', () => {
+  it('stamps the name and the passed-in version', () => {
+    const m = buildManifest('9.9.9')
+    expect(m.name).toBe('stash')
+    expect(m.version).toBe('9.9.9')
+  })
+
+  it('emits every non-hidden command across all groups', () => {
+    const m = buildManifest('0.0.0')
+    const registryCount = registry
+      .flatMap((g) => g.commands)
+      .filter((c) => !c.hidden).length
+    const manifestCount = m.groups.flatMap((g) => g.commands).length
+    expect(manifestCount).toBe(registryCount)
+    expect(m.groups.length).toBe(registry.length)
+  })
+
+  it('drops commands marked hidden', () => {
+    // Drive the hidden filter with a stub so coverage doesn't depend on the
+    // live registry happening to contain a hidden command (it currently
+    // contains none — a real-registry assertion would be vacuously green).
+    const groups: CommandGroup[] = [
+      {
+        title: 'T',
+        commands: [
+          { name: 'shown', summary: 's' },
+          { name: 'gone', summary: 'g', hidden: true },
+        ],
+      },
+    ]
+    const names = buildManifest('0.0.0', groups)
+      .groups.flatMap((g) => g.commands)
+      .map((c) => c.name)
+    expect(names).toEqual(['shown'])
+  })
+
+  it('carries examples through into the manifest', () => {
+    // The one optional-field passthrough not covered by the auth-login (long +
+    // flags) or wizard (all-undefined) cases.
+    const init = buildManifest('0.0.0')
+      .groups.flatMap((g) => g.commands)
+      .find((c) => c.name === 'init')
+    expect(init?.examples).toContain('init --supabase')
+  })
+
+  it('defensively copies flags so a consumer cannot corrupt the registry', () => {
+    const dbUrlOf = (m: ReturnType<typeof buildManifest>) =>
+      m.groups
+        .flatMap((g) => g.commands)
+        .flatMap((c) => c.flags ?? [])
+        .find((f) => f.name === '--database-url')
+
+    const first = dbUrlOf(buildManifest('0.0.0'))
+    expect(first).toBeDefined()
+    // Mutate a manifest flag; the shared registry singleton must be untouched.
+    ;(first as { description: string }).description = 'MUTATED'
+    expect(dbUrlOf(buildManifest('0.0.0'))?.description).not.toBe('MUTATED')
+  })
+
+  it('gives every command a non-empty name and summary', () => {
+    for (const group of buildManifest('0.0.0').groups) {
+      expect(group.title.length).toBeGreaterThan(0)
+      for (const cmd of group.commands) {
+        expect(cmd.name.length).toBeGreaterThan(0)
+        expect(cmd.summary.length).toBeGreaterThan(0)
+      }
+    }
+  })
+
+  it('includes the worked-example auth login descriptor with its flags', () => {
+    const cmds = buildManifest('0.0.0').groups.flatMap((g) => g.commands)
+    const authLogin = cmds.find((c) => c.name === 'auth login')
+    expect(authLogin).toBeDefined()
+    expect(authLogin?.long).toContain('device authorization flow')
+    const flagNames = authLogin?.flags?.map((f) => f.name) ?? []
+    expect(flagNames).toContain('--region')
+    expect(flagNames).toContain('--json')
+    expect(flagNames).toContain('--no-open')
+  })
+
+  it('surfaces the shared --database-url flag with its env var', () => {
+    const eqlInstall = buildManifest('0.0.0')
+      .groups.flatMap((g) => g.commands)
+      .find((c) => c.name === 'eql install')
+    const dbUrl = eqlInstall?.flags?.find((f) => f.name === '--database-url')
+    expect(dbUrl?.env).toBe('DATABASE_URL')
+    expect(dbUrl?.value).toBe('<url>')
+  })
+
+  it('drops undefined optionals so the JSON round-trips cleanly', () => {
+    const m = buildManifest('1.2.3')
+    const json = JSON.stringify(m)
+    expect(JSON.parse(json)).toEqual(m)
+    // A summary-only command must not carry empty long/examples/flags keys.
+    const wizard = m.groups
+      .flatMap((g) => g.commands)
+      .find((c) => c.name === 'wizard')
+    expect(wizard).toEqual({
+      name: 'wizard',
+      summary: 'AI-guided encryption setup (reads your codebase)',
+    })
+  })
+})

packages/cli/src/cli/manifest.ts

@@ -0,0 +1,71 @@
+/**
+ * `stash manifest --json` — the structured, versioned command surface the docs
+ * generator (cipherstash/docs#45) and agents consume instead of scraping
+ * `--help`. Built from the command-descriptor registry so it can't drift from
+ * the real command set. See `docs/plans/cli-help-and-manifest.md`.
+ */
+import {
+  type CommandDescriptor,
+  type CommandGroup,
+  type Flag,
+  registry,
+} from './registry.js'
+
+/** A command as it appears in the manifest — the descriptor minus `hidden`. */
+export interface ManifestCommand {
+  name: string
+  summary: string
+  long?: string
+  examples?: string[]
+  flags?: Flag[]
+}
+
+export interface ManifestGroup {
+  title: string
+  commands: ManifestCommand[]
+}
+
+export interface Manifest {
+  name: string
+  version: string
+  groups: ManifestGroup[]
+}
+
+/**
+ * Drop `hidden` and undefined optionals, and defensively copy `examples` /
+ * `flags` so the manifest never aliases the registry's arrays or its shared
+ * flag singletons (`DATABASE_URL_FLAG`, …) — a consumer that mutates a manifest
+ * entry must not corrupt the registry or other commands sharing that object.
+ */
+function toManifestCommand(cmd: CommandDescriptor): ManifestCommand {
+  const out: ManifestCommand = { name: cmd.name, summary: cmd.summary }
+  if (cmd.long !== undefined) out.long = cmd.long
+  if (cmd.examples !== undefined) out.examples = [...cmd.examples]
+  if (cmd.flags !== undefined) out.flags = cmd.flags.map((f) => ({ ...f }))
+  return out
+}
+
+/**
+ * Build the manifest for a given CLI version. `version` is threaded in from the
+ * CLI's own `package.json`, so a page generated from the manifest is always
+ * stamped with the exact version it describes. Hidden commands are excluded.
+ *
+ * `groups` defaults to the real `registry`; it's an injection seam so tests can
+ * drive the hidden-command filter with a stub instead of depending on whether
+ * the live registry happens to contain a hidden command.
+ */
+export function buildManifest(
+  version: string,
+  groups: CommandGroup[] = registry,
+): Manifest {
+  return {
+    name: 'stash',
+    version,
+    groups: groups.map((group) => ({
+      title: group.title,
+      commands: group.commands
+        .filter((cmd) => !cmd.hidden)
+        .map(toManifestCommand),
+    })),
+  }
+}