argsbarg 3.6.3 → 3.6.4

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.4] - 2026-06-23
+
+### Added
+
+- **`docs/output-schema.md`** — recommended TypeScript → JSON Schema codegen pipeline for leaf `outputSchema` (manifest, bridge, JSDoc, narrowing, CI).
+
+### Changed
+
+- **`docs/README.md`**, **`cli-program.md`**, **`bundled-docs.md`**, Cursor rule template — cross-links to output-schema guide.
+
 ## [3.6.3] - 2026-06-23
 
 ### Added
@@ -20,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`cli-program.md`** — `CliLeafInputs` / `readLeafInputs()` semantics, upgrading to 3.6+, read-once-resolve-once cross-links.
 - **`bundled-docs.md`** — framework docs vs consumer docgen.
 - **`docs/mcp.md`** — varargs JSON array only (fixes stale comma-string guidance).
+- **`consumers-dev` / `consumers-sync`** — refresh consumer `.cursor/rules/cli-program.mdc` from template via `scripts/merge-cli-program-rule.ts`.
 
 ## [3.6.2] - 2026-06-23
 
@@ -413,7 +424,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.4...HEAD
+[3.6.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.4
 [3.6.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.3
 [3.6.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.2
 [3.6.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.1

package/README.md

@@ -155,7 +155,7 @@ mkdir -p .cursor/rules
 cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
 ```
 
-Add app-specific conventions in a second rule if needed. Documentation map: **[docs/README.md](docs/README.md)**. Authoring guide: **[docs/cli-program.md](docs/cli-program.md)**.
+Add app-specific conventions in a second rule if needed. Copy the rule from the template, then add a `**<your-app> conventions:**` block at the bottom (see **Cursor rule** in [docs/cli-program.md](docs/cli-program.md)). Documentation map: **[docs/README.md](docs/README.md)**.
 
 
 ## How it works

package/docs/README.md

@@ -6,6 +6,7 @@ Start here to pick the right guide.
 | --- | --- |
 | **New to argsbarg** | [../README.md](../README.md) — install, minimal usage, public API |
 | **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
+| **JSON stdout / `outputSchema`** | [output-schema.md](output-schema.md) — codegen pipeline, JSDoc, narrowing |
 | **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `install --mcp` |
 | **Shipping install / completions / skills** | [install.md](install.md) — `myapp install`, shell completions |
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |

package/docs/bundled-docs.md

@@ -11,6 +11,8 @@ Two documentation layers often coexist in a consumer repo:
 | **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [Cursor rule](templates/cursor/rules/cli-program.mdc) or `AGENTS.md` |
 | **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs schema`, `docs mcp` — save with `--save` to `./docs/` |
 
+`docs api` and `docs schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.
+
 Do not confuse them: editing `./docs/api.md` after docgen updates **your** app reference; it does not change argsbarg's framework guides. When MCP behavior changes (e.g. varargs arrays in 3.6+), update consumer `docs/mcp.md` via **`myapp docs mcp --save`** and bump the `argsbarg` dependency.
 
 See [docs/README.md](README.md) for the full documentation map.

package/docs/cli-program.md

@@ -134,6 +134,8 @@ On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when
 
 Exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
 
+For a **outputSchema codegen guidelines** (TypeScript types → JSON Schema → `outputSchema` constants), see [output-schema.md](output-schema.md).
+
 Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
@@ -388,15 +390,27 @@ mkdir -p .cursor/rules
 cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
 ```
 
-The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide — re-copy after upgrading argsbarg when the template changes.
+The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide.
+
+2. **Add an app-specific block at the bottom** (recommended). Replace the template placeholder with a heading like `**myapp conventions:**` and short bullets — shared flag modules, `read*Flags` / `resolve*` paths, Ink vs JSON-only, etc. Example:
+
+```markdown
+**sqsp-qa conventions:**
+
+- Shared mutator flags: `readQaMutatingFlags(ctx)` in `src/cli/shared.ts`.
+- Per command: `read*Flags` + `resolve*Input` in `commands/<name>/resolve.ts`.
+```
+
+If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just consumers-sync` refresh the shared template and **keep** this footer (matched by the `**… conventions:**` heading). Commit `.cursor/rules/cli-program.mdc` in your repo.
 
-2. **Optional:** a second rule for app-only conventions (e.g. `src/cli/shared.ts` flag names, JSON-only handlers, Ink patterns).
+3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
 
-3. **Optional:** `.cursor/argsbarg.mdc` or `AGENTS.md` pointing at `node_modules/argsbarg/docs/cli-program.md` for broader context.
+**Not this file:** `myapp install --skill` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
 
 ## See also
 
 - [Documentation map](README.md) — which doc to read when
+- [Output schemas](output-schema.md) — codegen pipeline for leaf `outputSchema`
 - [Developing argsbarg](developing.md) — release, consumer sync, npm `files`
 - [MCP server](mcp.md) — tools, schema resource, env bootstrapping
 - [Agent skills](ai-skills.md) — `install --skill`

package/docs/developing.md

@@ -32,12 +32,16 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>` in each consumer |
-| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, `just build`, `just docgen`, `just install` |
+| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install` (consumer app binary, completions, and **app** skill) |
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
 
-Re-copy `docs/templates/cursor/rules/cli-program.mdc` into consumer repos when the template changes (append app-specific conventions; do not fork the whole guide).
+**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `docs/templates/cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
+
+**Recommended in each consumer:** replace the template placeholder with `**<app> conventions:**` bullets (paths to `read*Flags`, shared flags, Ink vs JSON-only). Commit that file; merges refresh the shared top, not your footer.
+
+**Consumer app skill** — `just install` in each consumer (part of `consumers-sync`) runs `myapp install --skill`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
 
 ## npm package contents
 

package/docs/output-schema.md

@@ -0,0 +1,181 @@
+# Output schemas (`outputSchema`)
+
+How to describe JSON stdout on leaf commands — and a **recommended codegen pipeline** used in production argsbarg apps.
+
+## Argsbarg contract
+
+On **leaf commands**, set `outputSchema` to a JSON Schema object when the handler emits JSON (typically with `--json`, always for JSON-only commands, or on the MCP headless path).
+
+```typescript
+import { STATUS_OUTPUT_SCHEMA } from "../schemas/outputSchemas.js";
+
+export const status = {
+  key: "status",
+  description: "Show environment status.",
+  outputSchema: STATUS_OUTPUT_SCHEMA,
+  handler: async (ctx) => { /* writes JSON to stdout */ },
+} satisfies CliLeaf;
+```
+
+| Where argsbarg uses it | Purpose |
+| --- | --- |
+| `myapp docs schema` | Full command tree JSON export |
+| `myapp docs api` | Markdown per-command **Output** section |
+| `myapp docs skill` | `reference.md` for agent skills |
+| MCP `tools/list` | Optional `outputSchema` on each tool |
+
+**Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP metadata.
+
+**Set on the leaf only** — not under `mcpTool` (legacy `mcpTool.outputSchema` still resolves but is deprecated).
+
+**Draft version** — argsbarg accepts any JSON Schema object (`type`, `properties`, `definitions`, etc.). Generators may emit draft-07 or draft 2020-12; docgen embeds the object as-is.
+
+See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for when to use `outputSchema` vs `notes`, and [mcp.md](mcp.md) for how MCP returns parsed JSON as `structuredContent`.
+
+## Hand-written vs generated
+
+| Approach | When |
+| --- | --- |
+| **Inline object** on the leaf | One-off commands, spikes, very small shapes |
+| **Codegen from TypeScript** | Multiple commands share a shape, nested objects, or you want rich `description` fields in `docs api` / skills |
+
+Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
+
+## Recommended pipeline (copy per repo)
+
+No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-tools**, **idp-trees**, **sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for manifest tables).
+
+```mermaid
+flowchart LR
+  subgraph types [Schema-facing TS + JSDoc]
+    Roots["Manifest root interfaces"]
+    Narrow["Narrowed types where needed"]
+  end
+  subgraph gen [just schemagen]
+    Script["scripts/generate-output-schemas.ts"]
+    Gen["ts-json-schema-generator"]
+  end
+  subgraph artifacts [Committed]
+    Json["src/schemas/generated/*.json"]
+  end
+  subgraph runtime [Runtime]
+    Bridge["src/schemas/outputSchemas.ts"]
+    Leaves["leaf outputSchema"]
+    Docgen["just docgen"]
+  end
+  Roots --> Script
+  Narrow --> Script
+  Script --> Gen --> Json --> Bridge --> Leaves --> Docgen
+```
+
+| Piece | Convention |
+| --- | --- |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (e.g. `createGenerator` with `jsDoc: "extended"`) |
+| Config | `tsconfig: "tsconfig.json"`, `topRef: false`, `skipTypeCheck: false` |
+| Manifest | Explicit `{ typeName, path, outfile }[]` — only **roots** become schema files |
+| Artifacts | Commit `src/schemas/generated/*.json` |
+| Bridge | `src/schemas/outputSchemas.ts` imports JSON → `*_OUTPUT_SCHEMA` constants |
+| tsconfig | `"resolveJsonModule": true` |
+| CI | `just check`: run `schemagen` → `git diff --exit-code src/schemas/generated/` → typecheck |
+| Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/schema.json` are fresh |
+
+Type files can live anywhere the manifest points (`commands/<cmd>/types.ts`, `resolve.ts`, `core/types.ts`, `ui/runHeadless.ts`).
+
+### Example manifest + generator
+
+```typescript
+const MANIFEST = [
+  { typeName: "StatusJsonOutput", path: "src/commands/status/resolve.ts", outfile: "status.json" },
+  { typeName: "HeadlessOpResult", path: "src/ui/runHeadless.ts", outfile: "headless-op-result.json" },
+];
+
+for (const entry of MANIFEST) {
+  const generator = createGenerator({
+    path: path.join(ROOT, entry.path),
+    type: entry.typeName,
+    tsconfig: path.join(ROOT, "tsconfig.json"),
+    topRef: false,
+    skipTypeCheck: false,
+    jsDoc: "extended",
+  });
+  fs.writeFileSync(
+    path.join(OUT_DIR, entry.outfile),
+    `${JSON.stringify(generator.createSchema(entry.typeName), null, 2)}\n`,
+  );
+}
+```
+
+### Example bridge
+
+```typescript
+import statusJson from "./generated/status.json";
+
+export const STATUS_JSON_OUTPUT_SCHEMA = statusJson as Record<string, unknown>;
+```
+
+Wire the constant on each leaf that emits that shape (several commands may share one schema, e.g. mutating ops sharing `HeadlessOpResult`).
+
+## Schema-facing types
+
+**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
+
+1. **Manifest roots** — `export interface` (preferred) or documented type alias; top-level JSDoc names which command(s) emit it.
+2. **Per property** — `/** … */` on every field that should appear in JSON Schema `properties` (including nested named types).
+3. **Unions / enums** — document the alias; generator emits `enum` / `anyOf` with type-level description.
+4. **Formats** — property JSDoc can include `@format date-time` for ISO timestamps; add a smoke test that the generated property has `format: "date-time"`.
+5. **Do not hand-edit** `src/schemas/generated/` — change types/JSDoc, run `just schemagen`, commit JSON.
+
+### Narrowing when runtime ≠ stdout
+
+When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** type:
+
+```typescript
+/** Runtime union across commands. */
+export type ResultSource = TranslationReadinessSource | { kind: "uids"; uids: string[] };
+
+/** JSON for `pr` and `file` only — no `uids` variant. */
+export interface TranslationReadinessResult {
+  source: TranslationReadinessSource;
+  evaluatedAt: string;
+  // ...
+}
+```
+
+Patterns:
+
+- **Shallow dashboard types** — separate interfaces from fat API types so generated schema stays readable.
+- **Assignability tests** — `expectTypeOf<RuntimeRow>().toMatchTypeOf<SchemaFacingRow>()` or equivalent so refactors cannot drift.
+
+Handlers keep using runtime types; only the manifest root (and its graph) feed codegen.
+
+## Tests
+
+After wiring, add `src/schemas/outputSchemas.test.ts` (or similar):
+
+- Each exported schema has `type: "object"` (or expected root).
+- Key `properties` / `definitions` have non-empty `description` from JSDoc.
+- Spot-check enums, required fields, and `@format date-time` where it matters.
+
+## Contributor workflow
+
+1. Edit schema-facing interfaces and JSDoc.
+2. `just schemagen` — refresh `src/schemas/generated/`.
+3. Commit generated JSON with the type changes.
+4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
+5. Document app-specific manifest roots in **your** `docs/architecture.md` (not in argsbarg).
+
+Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md` and your `src/schemas/` layout.
+
+## Out of scope
+
+- Shared codegen package or monorepo tooling
+- Runtime Zod / `.parse()` on stdout in argsbarg
+- `outputSchema` for plain-text, streaming, or Ink-only commands
+- Forcing identical file layout across repos — the **manifest** is authoritative
+
+## See also
+
+- [cli-program.md](cli-program.md) — structured stdout, headless JSON, `read*Flags`
+- [mcp.md](mcp.md) — `tools/list`, `structuredContent`
+- [bundled-docs.md](bundled-docs.md) — `docs api` / `docs schema` docgen
+- [docs/README.md](README.md) — documentation map

package/docs/templates/cursor/rules/cli-program.mdc

@@ -8,8 +8,9 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 
 1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
 2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
-3. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
-4. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
+4. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
+5. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
 
 **Hard rules** (details and examples are in the docs above — do not contradict them):
 
@@ -20,5 +21,6 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 - String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
 - Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
 - Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
+- JSON stdout: `outputSchema` on the leaf from generated constants — see `output-schema.md`; do not hand-edit `src/schemas/generated/`.
 
-**App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).
+**App-specific conventions:** replace this line with a `**<your-app> conventions:**` section (bullets only). Keep it at the bottom of this file — `just consumer-dev` / `just consumers-sync` in the argsbarg repo refresh the template above and preserve this block. Do not duplicate `cli-program.md` here; link paths and patterns only. For a second rule file (e.g. `.cursor/argsbarg.mdc`), that is fine too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.6.3",
+  "version": "3.6.4",
   "type": "module",
   "engines": {
     "bun": ">=1.3"