argsbarg 6.1.1 → 6.1.3

package/docs/output-schema.md

@@ -7,12 +7,12 @@ How to describe JSON stdout on leaf commands — and the **argsbarg schemagen**
 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 { outputSchema } from "./__generated__/index.ts";
+import { StatusJsonOutputSchema } from "./__generated__";
 
 export const status = {
   key: "status",
   description: "Show environment status.",
-  outputSchema,
+  outputSchema: StatusJsonOutputSchema,
   handler: async (ctx) => { /* writes JSON to stdout */ },
 } satisfies CliLeaf;
 ```
@@ -20,14 +20,14 @@ export const status = {
 | Where argsbarg uses it | Purpose |
 | --- | --- |
 | `myapp docs cli-schema` | Full command tree JSON export |
-| `myapp docs api` | Markdown per-command **Output** section |
+| `myapp docs cli` | Markdown per-command **Output** section |
 | `myapp docs skill` | `reference.md` for agent skills |
 | MCP `tools/list` | Optional `outputSchema` on each tool |
 | HTTP `GET /openapi.json` | Response schema per tool |
 
 **Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP/HTTP metadata.
 
-**Set on the leaf only** — not under `mcpTool` (legacy `mcpTool.outputSchema` still resolves but is deprecated).
+**Set on the leaf only** — not under `mcpTool`.
 
 **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.
 
@@ -38,7 +38,7 @@ See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for
 | 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 |
+| **Codegen from TypeScript** | Multiple commands share a shape, nested objects, or you want rich `description` fields in `docs cli` / skills |
 
 Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
 
@@ -50,137 +50,129 @@ Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-
 
 ```mermaid
 flowchart LR
-  subgraph types [types.ts]
-    Config["export type configType = AppConfig"]
-    Output["export type outputType = StatusJsonOutput"]
-    Input["export type inputType = ToolInput (optional)"]
+  subgraph src [src/**/*.ts]
+    Sg["/** @sg */ export interface TypeName"]
   end
   subgraph gen [argsbarg schemagen]
-    Discover["discover types.ts roots"]
+    Walk["walk src/ minus tests and __generated__"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Gitignored __generated__]
-    Json["configSchema.json / inputSchema.json / outputSchema.json"]
+    Json["TypeNameSchema.json"]
     Index["index.ts re-exports"]
   end
   subgraph runtime [Runtime]
-    Leaves["import { outputSchema } from ./__generated__/index.ts"]
+    Leaves["import { TypeNameSchema } from ./__generated__"]
     Docgen["just docgen"]
   end
-  types --> Discover --> Gen --> Json
+  src --> Walk --> Gen --> Json
   Gen --> Index --> Leaves --> Docgen
 ```
 
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled as an argsbarg dependency) |
-| Discovery | Walk `src/**/types.ts` for `export type outputType` / `inputType` / `configType`; generate from the aliased type in the same file |
-| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `types.ts` changes |
+| Discovery | Walk `src/**/*.ts` (exclude `*.test.ts`, `__generated__/`); find `/** @sg */` JSDoc immediately followed by `export interface` or `export type` |
+| Artifacts | One `__generated__/` per source directory; `{TypeName}Schema.json` + `export const {TypeName}Schema` in `index.ts` |
 | Invocation | `just schemagen` — justfile exports `node_modules/.bin` on `PATH` for local `argsbarg` |
 | tsconfig | `"resolveJsonModule": true` |
 | CI | `just check`: `schemagen` → typecheck (no git diff on generated files) |
-| Cleanup | Schemagen removes orphan `__generated__/` dirs and stale JSON when roots or kinds are removed |
-| Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/cli-schema.json` are fresh |
+| Cleanup | Schemagen removes orphan `__generated__/` dirs and stale JSON when roots are removed |
+| Docgen | `docgen` depends on `schemagen` so saved `./docs/cli.md` and `./docs/cli-schema.json` are fresh |
 
 ### Declaring a schema root
 
-Put schema-facing interfaces and role exports in **`types.ts`** (or `core/types.ts` for shared shapes):
+Mark any exported interface or type with `/** @sg */` on the line immediately above the declaration (no blank line):
 
 ```typescript
 // src/commands/status/types.ts
-/** JSON stdout for `myapp status --json`. */
+/** @sg */
 export interface StatusJsonOutput {
-  workspaces: WorkspaceStatus[];
+  version: string;
 }
+```
+
+Handlers import types from the same module; leaves import schemas from `./__generated__`:
 
-/** Schemagen root for leaf outputSchema. */
-export type outputType = StatusJsonOutput;
+```typescript
+import { StatusJsonOutputSchema } from "./__generated__";
 ```
 
-Handlers and other modules import from the same **`types.ts`** module.
+Shared shapes in one directory share one `__generated__/index.ts`:
 
 ```typescript
-// src/ui/runHeadless/types.ts — shared by many mutating commands
+// src/ui/runHeadless/types.ts
+/** @sg */
 export interface HeadlessOpResult {
   command: string;
   exitCode: number;
   tasks: HeadlessTaskResult[];
 }
-
-export type outputType = HeadlessOpResult;
 ```
 
 ```typescript
-// src/commands/render-invoice/types.ts — custom HTTP/MCP body (pdf-gen)
+// src/commands/render-invoice/types.ts
+/** @sg */
 export interface RenderInvoiceInput {
   format: "pdf" | "html";
   invoice: InvoiceData;
 }
 
+/** @sg */
 export interface RenderInvoiceOutput {
   bytes: number;
 }
-
-export type inputType = RenderInvoiceInput;
-export type outputType = RenderInvoiceOutput;
 ```
 
-| Export | Role |
-| --- | --- |
-| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/types.ts`) |
-| `export type outputType = …` | `leaf.outputSchema` |
-| `export type inputType = …` | `leaf.inputSchema` (only when the tool body is not flat CLI flags) |
+Wire on the leaf or `program.appConfig`:
 
-**Domain helpers** and **role exports** live in `types.ts`. Commands without structured JSON omit role exports. Shared shapes (e.g. `HeadlessOpResult`) are defined once in `types.ts` with a single `outputType`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
+| Generated export | Typical use |
+| --- | --- |
+| `AppConfigSchema` | `program.appConfig.jsonSchema` (optional — `src/config/types.ts`) |
+| `StatusJsonOutputSchema` | `leaf.outputSchema` |
+| `RenderInvoiceInputSchema` | `leaf.inputSchema` |
 
-For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
+For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the schema property) and use `ctx.jsonOpt(...)`, `ctx.inputs`, or `ctx.inputsAs<T>()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
 
 When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 
 ### Generated artifacts
 
-Schemagen writes under `__generated__/` beside each `types.ts` with role exports:
+Schemagen writes under `__generated__/` beside the `@sg` source files in each directory:
 
-| Kind | Generated file | Exported const (from `__generated__/index.ts`) |
+| Type name | Generated file | Exported const |
 | --- | --- | --- |
-| config | `configSchema.json` | `configSchema` |
-| output | `outputSchema.json` | `outputSchema` |
-| input | `inputSchema.json` | `inputSchema` |
+| `StatusJsonOutput` | `StatusJsonOutputSchema.json` | `StatusJsonOutputSchema` |
+| `RenderInvoiceInput` | `RenderInvoiceInputSchema.json` | `RenderInvoiceInputSchema` |
 
 Wire on the leaf:
 
 ```typescript
-import { outputSchema } from "./__generated__/index.ts";
+import { StatusJsonOutputSchema } from "./__generated__";
 
 export const statusCommand = {
-  outputSchema,
+  outputSchema: StatusJsonOutputSchema,
   // …
 } satisfies CliLeaf;
 ```
 
-Shared mutators:
-
-```typescript
-import { outputSchema } from "../../../ui/runHeadless/__generated__/index.ts";
-```
-
-App config:
+App config (when used):
 
 ```typescript
-import { configSchema } from "./config/__generated__/index.ts";
+import { AppConfigSchema } from "./config/__generated__";
 
-appConfig: { jsonSchema: configSchema, entries: { … } },
+appConfig: { jsonSchema: AppConfigSchema, entries: { … } },
 ```
 
 ## Schema-facing types
 
-**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
+**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs cli`.
 
-1. **Schema roots** — `export interface` in `types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
+1. **Schema roots** — `/** @sg */` immediately above `export interface` or `export type`, with per-field JSDoc.
 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** `__generated__/` — change types/JSDoc in `types.ts`, run `just schemagen`.
+5. **Do not hand-edit** `__generated__/` — change types/JSDoc in source files, run `just schemagen`.
 
 ### Narrowing when runtime ≠ stdout
 
@@ -193,7 +185,8 @@ export interface TranslationReadinessResult {
   evaluatedAt: string;
 }
 
-export type outputType = TranslationReadinessResult;
+/** @sg */
+export interface TranslationReadinessResult {
 ```
 
 Patterns:
@@ -213,15 +206,15 @@ Per consumer repo (optional):
 
 ## Contributor workflow
 
-1. Add or edit schema roots in `src/**/types.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+1. Add or edit `/** @sg */` roots in `src/**/*.ts` with per-field JSDoc.
 2. `just schemagen` — refresh `src/**/__generated__/`.
-3. Import `{ outputSchema }` / `{ inputSchema }` / `{ configSchema }` from the relevant `__generated__/index.ts`.
-4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
+3. Import `{ TypeNameSchema }` from the relevant `./__generated__` barrel.
+4. `just docgen` / `myapp docs cli --save` — refresh consumer docs.
 5. Document which commands use which roots in **your** `docs/architecture.md` (argsbarg does not maintain per-app tables).
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md`.
 
-**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `types.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
 
 ## Out of scope
 
@@ -233,5 +226,5 @@ Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/c
 - [config-schema.md](config-schema.md) — `configType` / `program.appConfig`
 - [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 cli-schema` docgen
+- [bundled-docs.md](bundled-docs.md) — `docs cli` / `docs cli-schema` docgen
 - [docs/README.md](README.md) — documentation map

package/examples/formats.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /*
- * Value formats demo: duration, comma-list, date, default, and readLeafInputs().
+ * Value formats demo: duration, comma-list, date, default, and ctx.inputs.
  * Run: bun ./examples/formats.ts run --tags alpha,beta --on 2026-06-22
  * MCP: pass comma-list as string or array; varargs N/A on this leaf.
  */
@@ -12,19 +12,19 @@ import {
   CliOptionKind,
   type CliProgram,
   CliValueFormat,
-} from "../src/index.ts";
+} from "../src/index";
 
 const program = {
   key: "formats.ts",
   version: pkg.version,
-  description: "Value formats and readLeafInputs demo.",
+  description: "Value formats and ctx.inputs demo.",
   fallbackCommand: "run",
   fallbackMode: CliFallbackMode.MissingOnly,
   mcpServer: { enabled: true },
   commands: [
     {
       key: "run",
-      description: "Print coerced option values from readLeafInputs().",
+      description: "Print coerced option values from ctx.inputs.",
       options: [
         {
           name: "timeout",
@@ -53,9 +53,9 @@ const program = {
         },
       ],
       handler: (ctx) => {
-        const inputs = ctx.readLeafInputs();
+        const inputs = ctx.inputs;
         const out = {
-          readLeafInputs: inputs,
+          inputs,
           durationMs: ctx.durationOpt("timeout"),
           tags: ctx.commaListOpt("tags"),
           on: ctx.dateOpt("on"),

package/examples/full-example/Formula/full-example.rb

@@ -0,0 +1,35 @@
+class FullExample < Formula
+  desc "Argsbarg full example reference app"
+  homepage "https://github.com/bdombro/bun-argsbarg"
+  version "1.0.0"
+  sha256 "d6dbe3233152d2f51feca068b23e6fd133940232fb4bb7c3f08c2d1024c10c30"
+
+  def install
+    bin.install "full-example"
+    chmod 0755, bin/"full-example"
+    generate_completions_from_executable(bin/"full-example", "completion", base_name: "full-example")
+  end
+
+  def post_install
+    system bin/"full-example", "configure", "--sync", "--yes"
+  end
+
+  def uninstall
+    system bin/"full-example", "configure", "--remove-all", "--yes"
+  end
+
+  def caveats
+    <<~EOS
+      Run `full-example configure` to set up agent artifacts and app config (interactive).
+      Restart MCP chat apps (Cursor, Claude Desktop, etc.) after install or upgrade so they load the updated server.
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/full-example version")
+    assert_predicate bash_completion/"full-example", :exist?
+    assert_predicate zsh_completion/"_full-example", :exist?
+    assert_predicate fish_completion/"full-example.fish", :exist?
+  end
+url "file:///Users/briandombrowski/dev/bdombro/bun-argsbarg/examples/full-example/Formula/.staging/full-example"
+end

package/examples/full-example/README.md

@@ -1,6 +1,16 @@
 # full-example
 
-Argsbarg full example reference app
+Argsbarg copy template / reference app (not a kitchen-sink product).
+
+## What's in this app
+
+- **Builtins enabled:** CLI, shell completion, `docs`, MCP, HTTP API, `configure` (wizard available; no default `appConfig` in the template)
+- **Commands:**
+  - `echo` — simple flags/positionals
+  - `render-json` — `kind: "json"` leaf, schemagen `inputSchema`, `ctx.inputsAs`
+  - `status` — schemagen `outputSchema`, `--json`
+  - `workspaces` — REST CRUD, `:id` param routers, verb leaves, schemagen input schemas
+- **Tooling:** `@sg` schemagen, `just docgen`, Homebrew/just dev workflow
 
 ## Quick start
 
@@ -9,13 +19,11 @@ From a git checkout at this directory (requires [Homebrew](https://brew.sh), [ju
 ```bash
 brew install just bun
 just setup
-just schemagen   # after changing src/**/types.ts
+just schemagen   # after changing @sg types in src/
 just run status --json
 just run docs readme
 ```
 
-Run `full-example configure` when the app needs secrets or other app config (interactive wizard).
-
 ## Install
 
 Requires [Homebrew](https://brew.sh).
@@ -34,7 +42,6 @@ Install:
 ```bash
 brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
 brew install bdombro/bun-argsbarg/full-example
-full-example configure
 ```
 
 Upgrade:
@@ -58,17 +65,17 @@ just install-production   # remote tap install (requires gh auth login)
 just test-release
 ```
 
-Undo a local dev install: `just uninstall` (formula + agent artifacts; app config removed by formula `uninstall`), `just uninstall-config` (app config only, without uninstalling the formula).
+Undo a local dev install: `just uninstall` (formula + agent artifacts), `just uninstall-config` (app config only, without uninstalling the formula).
 
-## Schemagen roots
+## Schemagen (`@sg`)
 
-| Export in `types.ts` | Generated artifact | Import on leaf / program |
-| --- | --- | --- |
-| `export type configType = …` | `config/__generated__/configSchema.json` | `{ configSchema }` from `config/__generated__/index.ts` |
-| `export type outputType = …` | `__generated__/outputSchema.json` | `{ outputSchema }` from `__generated__/index.ts` |
-| `export type inputType = …` | `__generated__/inputSchema.json` | `{ inputSchema }` from `__generated__/index.ts` |
+Mark schema-facing types with `/** @sg */` immediately above the declaration (no blank line). Run `argsbarg schemagen` (via `just schemagen` or `just setup`).
 
-Type definitions and schemagen role exports live in `types.ts`. Run `argsbarg schemagen` (via `just schemagen` or `just setup`).
+| Type | Generated artifact | Import |
+| --- | --- | --- |
+| `RenderJsonInput` | `RenderJsonInputSchema.json` | `RenderJsonInputSchema` from `./__generated__` |
+| `StatusJsonOutput` | `StatusJsonOutputSchema.json` | `StatusJsonOutputSchema` from `./__generated__` |
+| `WorkspaceNameInput` | `WorkspaceNameInputSchema.json` | `WorkspaceNameInputSchema` from `./__generated__` |
 
 ## Consumer docs
 
@@ -77,11 +84,3 @@ Regenerate committed reference docs under `docs/` (see [docs/README.md](docs/REA
 ```bash
 just docgen
 ```
-
-## Environment
-
-Optional overrides for `program.appConfig` (the configure wizard is the usual path):
-
-| Variable | Purpose |
-| --- | --- |
-| `FULL_EXAMPLE_API_TOKEN` | Overrides `apiToken` when set in the shell |

package/examples/full-example/docs/README.md

@@ -8,7 +8,7 @@ Reference template for argsbarg consumer docgen. Every builtin is enabled in `sr
 | **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see `.cursor/rules/cli-program.mdc` |
 | **HTTP API / curl** | [http.md](http.md) — generated; or run `full-example docs http` |
 | **MCP tools** | [mcp.md](mcp.md) — generated; or run `full-example docs mcp` |
-| **Full command tree (markdown)** | [api.md](api.md) — generated |
+| **Full command tree (markdown)** | [cli.md](cli.md) — generated |
 | **Full command tree (JSON)** | [cli-schema.json](cli-schema.json) — generated |
 | **OpenAPI 3.1** | [openapi.json](openapi.json) — generated |
 | **Agent skill index** | [skill.md](skill.md) — generated |