argsbarg 6.0.1 → 6.1.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.0] - 2026-07-22
+
+### Added
+
+- **`CliOptionKind.Json`** and **`pipable`** — JSON object options with CLI `--name '<json>'` or piped stdin when the flag is omitted (flag wins if set). MCP/API values merge from `toolArgs`.
+- **`ctx.readLeafInputsAsync()`** — resolves Json options (flag, stdin, or `toolArgs`) and validates against `leaf.inputSchema` when set.
+
+### Changed
+
+- **Schemagen discovery** — role exports (`configType` / `inputType` / `outputType`) live in `src/**/types.ts` instead of thin `schema.ts` manifests.
+
+## [6.0.2] - 2026-07-22
+
+### Added
+
+- **`argsbarg schemagen`** — centralized JSON Schema generation from thin `src/**/schema.ts` manifests into colocated `__generated__/` directories. Follows role aliases (`configType` / `inputType` / `outputType`) to types in sibling modules (typically `types.ts`).
+- **`argsbarg/schemagen`** export — `runSchemagen`, `discoverSchemaRoots`, and naming helpers (`src/cli-tool/schemagen/`).
+
+### Changed
+
+- **Schemagen convention** — replace per-repo `scripts/schemagen*` copies and `schema-types.ts` bindings with `schema.ts` + gitignored `__generated__/`. Run via `just schemagen` (`argsbarg schemagen` with `node_modules/.bin` on `PATH`).
+
 ## [6.0.1] - 2026-07-22
 
 ### Added
@@ -15,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Schemagen discovery contract** — `examples/full-example` and docs now use `src/**/schema-types.ts` with `export type configType` / `outputType` / `inputType` instead of JSDoc markers (`Config schema`, `JSON payload`, `Tool input`) on `types.ts`.
+- **Colocated schemagen** — `*.schema.json` beside each `schema-types.ts`; exports `configSchema` / `inputSchema` / `outputSchema` (replaces central `*Schemas.ts` bridges).
 - **HTTP tool errors** — return a plain `{ "error": "..." }` JSON body without ANSI color codes or appended CLI help text.
 - **`cliErrWithHelp`** — on `api` / `mcp` invocations, throws a plain error instead of printing contextual help.
 - **`GET /openapi-browser`** — Scalar config preserves schema property order from the OpenAPI document (`orderSchemaPropertiesBy: "preserve"`).
@@ -728,7 +750,9 @@ 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/v6.0.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.0...HEAD
+[6.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.0
+[6.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.2
 [6.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.1
 [6.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.0
 [5.1.16]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.16

package/README.md

@@ -208,6 +208,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.commaListOpt("services")` — comma-list options as `string[] | undefined`.
 - `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
 - `ctx.readLeafInputs()` — coerced option and positional values for the current leaf (schema-driven).
+- `ctx.readLeafInputsAsync()` — like `readLeafInputs()`, plus Json options (flag, piped stdin, MCP `toolArgs`) and `inputSchema` validation.
 - `ctx.typedOpt<T>("custom", parseFn)` — custom parsing for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
@@ -267,9 +268,9 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 | Area                  | Files / wiring                                                                         |
 | --------------------- | -------------------------------------------------------------------------------------- |
 | All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `api`, `configure get`/`set`      |
-| `program.appConfig`   | `src/config/schema-types.ts` (`AppConfig`) → `schemas/configSchemas.ts`              |
-| `outputSchema`        | `src/commands/status/schema-types.ts` → `schemas/outputSchemas.ts`                   |
-| Schemagen             | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts`                  |
+| `program.appConfig`   | `src/config/types.ts` → `configSchema` from `__generated__/`                         |
+| `outputSchema`        | `src/commands/status/types.ts` → `outputSchema` from `__generated__/`                  |
+| Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
 | Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                     |
 | MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import        | `from "argsbarg"` (not relative to argsbarg `src/`)                                    |

package/docs/api-server.md

@@ -138,4 +138,4 @@ Call `generateOpenApi(program)` or `openApiJson(program)` from the package, fetc
 
 ## Complex tool inputs
 
-For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf and read `ctx.toolArgs` in the handler — it contains the original flat JSON body from `POST /tools/:name`.
+For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf, declare a matching `kind: Json` option (optionally `pipable: true` for CLI stdin), and read inputs with `await ctx.readLeafInputsAsync()` — it merges flag values, piped stdin, and the original flat JSON body from `POST /tools/:name`.

package/docs/cli-program.md

@@ -223,9 +223,37 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 | `format: date-time` | `string` (normalized UTC ISO) |
 | Single positional | `string` or `undefined` |
 | Varargs positional | `string[]` or `undefined` |
+| `kind: json` | parsed object/array or `undefined` (use `readLeafInputsAsync()` for pipable stdin and MCP merge) |
 
 Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `readLeafInputs()` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `readLeafInputs()` for coerced values.
 
+### Json options and piped stdin
+
+For nested tool bodies (e.g. invoice template data), declare a matching property in schemagen `inputType`, wire `inputSchema` on the leaf, and add a **`kind: Json`** option with the same name:
+
+```typescript
+{
+  name: "invoice",
+  description: "Invoice template data. Pass JSON via --invoice or pipe to stdin.",
+  kind: CliOptionKind.Json,
+  pipable: true,
+  required: true,
+}
+```
+
+| Surface | How `invoice` is supplied |
+| --- | --- |
+| CLI | `--invoice '<json>'` **or** omit the flag and pipe JSON to stdin |
+| MCP / HTTP | `invoice` object in the tool JSON body (`ctx.toolArgs`) |
+
+**Precedence:** if `--invoice` is set, the flag value wins and stdin is not read.
+
+Use **`await ctx.readLeafInputsAsync()`** (not sync `readLeafInputs()`) so Json options resolve from flags, piped stdin, or `toolArgs`. When `leaf.inputSchema` is set, argsbarg validates the merged inputs (same JSON Schema subset as `program.appConfig`).
+
+At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
+
+See [output-schema.md](output-schema.md) for schemagen `inputType` and [api-server.md](api-server.md) for HTTP tool bodies.
+
 `CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.
 
 See [examples/formats.ts](../examples/formats.ts) for a runnable demo.

package/docs/config-schema.md

@@ -136,42 +136,42 @@ Interactive `configure` does not persist values supplied only by env or `resolve
 | **Omit `jsonSchema`** | Simple apps; all values stored as strings; use `entry.default` |
 | **Codegen from TypeScript** | Typed config, nested objects, shared with JSON Schema CI |
 
-## Recommended pipeline (copy per repo)
+## Recommended pipeline (argsbarg schemagen)
 
 Mirror the [output-schema.md](output-schema.md) pattern for config:
 
 ```mermaid
 flowchart LR
-  subgraph types [schema-types.ts]
+  subgraph types [types.ts]
     Marker["export type configType = AppConfig"]
   end
-  subgraph gen [just schemagen]
-    Script["scripts/schemagen.ts"]
+  subgraph gen [argsbarg schemagen]
+    Script["argsbarg schemagen"]
     Gen["ts-json-schema-generator"]
   end
-  subgraph artifacts [Committed]
-    Json["schemas/generated/app-config.json"]
-    Bridge["schemas/configSchemas.ts"]
+  subgraph artifacts [Gitignored __generated__]
+    Json["configSchema.json"]
+    Index["index.ts"]
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
     Validate["argsbarg runtime subset validator"]
   end
   types --> Script --> Gen --> Json
-  Script --> Bridge --> Program --> Validate
+  Gen --> Index --> Program --> Validate
 ```
 
 | Piece | Convention |
 | --- | --- |
-| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) |
-| Discovery | `export type configType = …` in `src/config/schema-types.ts` (type defined in same file) |
-| Artifacts | Commit `app-config.json` and `configSchemas.ts` bridge exporting `APP_CONFIG_JSON_SCHEMA` |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled with argsbarg) |
+| Discovery | `export type configType = …` in `src/config/types.ts` |
+| Artifacts | `src/config/__generated__/` — gitignored; run `just schemagen` after clone |
 | Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
 
 Example:
 
 ```typescript
-// src/config/schema-types.ts
+// src/config/types.ts
 export interface AppConfig {
   apiToken: string;
 }
@@ -179,6 +179,8 @@ export interface AppConfig {
 export type configType = AppConfig;
 ```
 
+Wire on the program root: `import { configSchema } from "./config/__generated__/index.ts"`.
+
 ### Supported AppConfig shapes (argsbarg runtime validator)
 
 | Supported (v1) | Deferred |
@@ -220,7 +222,7 @@ Object/array/`$ref` properties require `--json` on `configure set` when comma-se
 
 | Example | Role |
 | --- | --- |
-| [`examples/full-example/`](../examples/full-example/) | **Copy template** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge, `program.appConfig`, built-in `configure get`/`set` |
+| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `argsbarg schemagen`, `program.appConfig`, built-in `configure get`/`set` |
 
 ```bash
 cd examples/full-example && just setup && just schemagen

package/docs/output-schema.md

@@ -1,18 +1,18 @@
 # Output schemas (`outputSchema`)
 
-How to describe JSON stdout on leaf commands — and a **recommended codegen pipeline** used in production argsbarg apps.
+How to describe JSON stdout on leaf commands — and the **argsbarg schemagen** pipeline used in production 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_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.js";
+import { outputSchema } from "./__generated__/index.ts";
 
 export const status = {
   key: "status",
   description: "Show environment status.",
-  outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
+  outputSchema,
   handler: async (ctx) => { /* writes JSON to stdout */ },
 } satisfies CliLeaf;
 ```
@@ -42,58 +42,52 @@ See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for
 
 Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
 
-## Recommended pipeline (copy per repo)
+## Schemagen pipeline (built into argsbarg)
 
-No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-i18n-tools-poc**, **pdf-gen** (see each repo’s `docs/architecture.md` for which commands use which schema root).
+No per-repo scripts to copy — run **`argsbarg schemagen`** (or `import { runSchemagen } from "argsbarg/schemagen"`).
+
+Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-i18n-tools-poc**, **pdf-gen** (see each repo’s `docs/architecture.md` for which commands use which schema root).
 
 ```mermaid
 flowchart LR
-  subgraph types [schema-types.ts]
+  subgraph types [types.ts]
     Config["export type configType = AppConfig"]
     Output["export type outputType = StatusJsonOutput"]
     Input["export type inputType = ToolInput (optional)"]
   end
-  subgraph gen [just schemagen]
-    Discover["discover-schema-roots.ts"]
-    Script["schemagen.ts / generate-output-schemas.ts"]
+  subgraph gen [argsbarg schemagen]
+    Discover["discover types.ts roots"]
     Gen["ts-json-schema-generator"]
   end
-  subgraph artifacts [Committed]
-    Json["schemas/generated/*.json"]
-    Bridge["outputSchemas.ts / inputSchemas.ts"]
+  subgraph artifacts [Gitignored __generated__]
+    Json["configSchema.json / inputSchema.json / outputSchema.json"]
+    Index["index.ts re-exports"]
   end
   subgraph runtime [Runtime]
-    Leaves["leaf outputSchema / inputSchema"]
+    Leaves["import { outputSchema } from ./__generated__/index.ts"]
     Docgen["just docgen"]
   end
-  types --> Discover --> Script --> Gen --> Json
-  Script --> Bridge --> Leaves --> Docgen
+  types --> Discover --> Gen --> Json
+  Gen --> Index --> Leaves --> Docgen
 ```
 
 | Piece | Convention |
 | --- | --- |
-| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (`createGenerator` with `jsDoc: "extended"`) |
-| Config | `tsconfig: "tsconfig.json"`, `topRef: false`, `skipTypeCheck: false` |
-| Discovery | Walk `src/**/schema-types.ts`; generate from `export type outputType = …` / `inputType` / `configType` when the target type is **defined in that file** |
-| Artifacts | Commit `schemas/generated/*.json` **and** auto-generated bridge modules |
+| 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 |
+| Invocation | `just schemagen` — justfile exports `node_modules/.bin` on `PATH` for local `argsbarg` |
 | tsconfig | `"resolveJsonModule": true` |
-| CI | `just check`: `schemagen` → `git diff --exit-code schemas/` → typecheck |
+| 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 |
 
-Copy these scripts into each consumer repo (they are intentionally duplicated, not published):
-
-- `scripts/schemagen.ts` or `scripts/generate-output-schemas.ts` — generate JSON + rewrite bridges
-- `scripts/schemagen/discover-schema-roots.ts` — find roots and map names → filenames / export constants
-- `scripts/schemagen/discover-schema-roots.test.ts` — lock discovery and naming per app
-
 ### Declaring a schema root
 
-Put schema-facing interfaces in **`schema-types.ts`** next to the command (or in a shared module when several commands reuse one shape). Export a role alias:
+Put schema-facing interfaces and role exports in **`types.ts`** (or `core/types.ts` for shared shapes):
 
 ```typescript
-// src/commands/status/schema-types.ts
-import type { WorkspaceStatus } from "./types.ts";
-
+// src/commands/status/types.ts
 /** JSON stdout for `myapp status --json`. */
 export interface StatusJsonOutput {
   workspaces: WorkspaceStatus[];
@@ -103,10 +97,10 @@ export interface StatusJsonOutput {
 export type outputType = StatusJsonOutput;
 ```
 
-```typescript
-// src/ui/runHeadless/schema-types.ts — shared by many mutating commands
-import type { HeadlessTaskResult } from "./types.ts";
+Handlers and other modules import from the same **`types.ts`** module.
 
+```typescript
+// src/ui/runHeadless/types.ts — shared by many mutating commands
 export interface HeadlessOpResult {
   command: string;
   exitCode: number;
@@ -117,70 +111,80 @@ export type outputType = HeadlessOpResult;
 ```
 
 ```typescript
-// src/commands/render-invoice/schema-types.ts — custom HTTP/MCP body (pdf-gen)
-export interface RenderInvoiceToolInput {
+// src/commands/render-invoice/types.ts — custom HTTP/MCP body (pdf-gen)
+export interface RenderInvoiceInput {
   format: "pdf" | "html";
   invoice: InvoiceData;
 }
 
-export type inputType = RenderInvoiceToolInput;
-export type outputType = RenderInvoiceWrittenOutput;
+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/schema-types.ts`) |
+| `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) |
 
-**Domain helpers** stay in `types.ts` (or `core/types.ts`). Discovery scans only `schema-types.ts`. Re-export-only files (`export type outputType = HeadlessOpResult` pointing at another module) are **not** generation roots — generate once from the canonical definition file.
+**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`.
 
-Commands without structured JSON omit `schema-types.ts` and import a shared bridge constant (e.g. `HEADLESS_OP_RESULT_OUTPUT_SCHEMA`).
+For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `await ctx.readLeafInputsAsync()` — 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`.
 
-### Stable naming (outfile + bridge export)
+### Generated artifacts
 
-Discovery maps each root type name to a generated filename and bridge constant. Suffix conventions (implemented in `outfileForOutputType` / `outputSchemaExportName`):
+Schemagen writes under `__generated__/` beside each `types.ts` with role exports:
 
-| Type suffix | Example type | Generated file | Bridge export |
-| --- | --- | --- | --- |
-| `JsonOutput` | `StatusJsonOutput` | `status.json` | `STATUS_JSON_OUTPUT_SCHEMA` |
-| `OpResult` | `HeadlessOpResult` | `headless-op-result.json` | `HEADLESS_OP_RESULT_OUTPUT_SCHEMA` |
-| `Output` | `OpenUrlOutput` | `open-url.json` | `OPEN_URL_OUTPUT_SCHEMA` |
-| `Result` | `PrResult` | `pr.json` | `PR_RESULT_OUTPUT_SCHEMA` |
-| `ToolInput` | `RenderInvoiceToolInput` | `render-invoice-tool-input.json` | `RENDER_INVOICE_TOOL_INPUT_SCHEMA` |
+| Kind | Generated file | Exported const (from `__generated__/index.ts`) |
+| --- | --- | --- |
+| config | `configSchema.json` | `configSchema` |
+| output | `outputSchema.json` | `outputSchema` |
+| input | `inputSchema.json` | `inputSchema` |
 
-Prefer these suffixes for new roots so filenames and import constants stay predictable across repos.
+Wire on the leaf:
 
-### Generated bridge
+```typescript
+import { outputSchema } from "./__generated__/index.ts";
 
-`scripts/schemagen.ts` rewrites `schemas/outputSchemas.ts` on every run:
+export const statusCommand = {
+  outputSchema,
+  // …
+} satisfies CliLeaf;
+```
+
+Shared mutators:
 
 ```typescript
-// Auto-generated by scripts/schemagen.ts — do not edit by hand.
+import { outputSchema } from "../../../ui/runHeadless/__generated__/index.ts";
+```
 
-import status from "./generated/status.json";
+App config:
 
-/** JSON Schema for leaf outputSchema from `StatusJsonOutput`. */
-export const STATUS_JSON_OUTPUT_SCHEMA = status as Record<string, unknown>;
-```
+```typescript
+import { configSchema } from "./config/__generated__/index.ts";
 
-Wire the constant on each leaf that emits that shape (several commands may share one schema, e.g. mutating ops sharing `HeadlessOpResult`).
+appConfig: { jsonSchema: configSchema, entries: { … } },
+```
 
 ## Schema-facing types
 
 **Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
 
-1. **Schema roots** — `export interface` in `schema-types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
+1. **Schema roots** — `export interface` in `types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
 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** `schemas/generated/` or bridge modules — change types/JSDoc, run `just schemagen`, commit both.
+5. **Do not hand-edit** `__generated__/` — change types/JSDoc in `types.ts`, run `just schemagen`.
 
 ### Narrowing when runtime ≠ stdout
 
-When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `schema-types.ts`:
+When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `types.ts`:
 
 ```typescript
 /** JSON stdout for `myapp pr` and `myapp file`. */
@@ -201,27 +205,26 @@ Handlers keep using runtime types; only discovered roots (and their type graph)
 
 ## Tests
 
-Per repo:
+In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example/`.
+
+Per consumer repo (optional):
 
-- **`scripts/schemagen/discover-schema-roots.test.ts`** — asserts which roots are discovered and stable outfile / export-name mapping.
-- **`schemas/outputSchemas.test.ts`** (optional) — schema shape smoke tests: object root, key `description` fields, enums, `@format date-time`.
+- **`src/generated-schemas.test.ts`** — smoke-test that key `outputSchema` objects have expected shape.
 
 ## Contributor workflow
 
-1. Add or edit schema roots in `src/**/schema-types.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
-2. `just schemagen` — refresh `schemas/generated/` and bridge modules.
-3. Import the bridge constant on the relevant leaf `outputSchema` / `inputSchema` fields.
-4. Commit generated JSON and bridges with the type changes.
-5. `just docgen` / `myapp docs api --save` — refresh consumer docs.
-6. Document which commands use which roots in **your** `docs/architecture.md` (argsbarg does not maintain per-app tables).
+1. Add or edit schema roots in `src/**/types.ts` with `outputType` / `inputType` / `configType` and 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.
+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` and your `schemas/` layout.
+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 (shipped in npm as `node_modules/argsbarg/examples/full-example/`) — discovery script, bridges, and `status` leaf with `outputSchema`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `types.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
 
 ## 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
 

package/examples/full-example/README.md

@@ -9,7 +9,7 @@ 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/**/schema-types.ts
+just schemagen   # after changing src/**/types.ts
 just run status --json
 just run docs readme
 ```
@@ -62,13 +62,13 @@ Undo a local dev install: `just uninstall` (formula + agent artifacts; app confi
 
 ## Schemagen roots
 
-| Export in `schema-types.ts` | Artifact |
-| --- | --- |
-| `export type configType = …` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
-| `export type outputType = …` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
-| `export type inputType = …` | `schemas/inputSchemas.ts` + `schemas/generated/*-tool-input.json` |
+| 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` |
 
-Discovery walks `src/**/schema-types.ts` only. Domain helpers stay in sibling `types.ts`.
+Type definitions and schemagen role exports live in `types.ts`. Run `argsbarg schemagen` (via `just schemagen` or `just setup`).
 
 ## Consumer docs
 

package/examples/full-example/bun.lock

@@ -10,7 +10,6 @@
       "devDependencies": {
         "@biomejs/biome": "^2.5.0",
         "@types/bun": "^1.3.12",
-        "ts-json-schema-generator": "^2.3.0",
         "typescript": "^5.9.3",
       },
     },
@@ -36,40 +35,12 @@
 
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
-    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
-
     "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
 
     "argsbarg": ["argsbarg@file:../..", { "devDependencies": { "@biomejs/biome": "^2.5.0", "@types/bun": "^1.3.12", "typescript": "^5.9.3" }, "bin": { "argsbarg": "src/index.ts" } }],
 
-    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
-
-    "brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="],
-
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
-    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
-
-    "glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
-
-    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
-
-    "lru-cache": ["lru-cache@11.5.1", "", {}, "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A=="],
-
-    "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="],
-
-    "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
-
-    "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
-
-    "path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
-
-    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
-
-    "ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
-
-    "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
-
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],

package/examples/full-example/justfile

@@ -1,5 +1,7 @@
 set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
 
+export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
+
 cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
 tap_repo := `bun scripts/print-identity.ts tapRepo`
@@ -19,9 +21,8 @@ build:
     bun build ./src/index.ts --compile --outfile=dist/{{cli_key}}
     @rm -f .*.bun-build
 
-# Run schemagen, git diff check, typecheck, and format
+# Run schemagen, typecheck, and format
 check: schemagen format typecheck
-    git diff --exit-code schemas/
 
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
@@ -84,11 +85,13 @@ run *ARGS:
 
 # Generate JSON Schema artifacts from TypeScript types
 schemagen:
-    bun run schemagen
+    argsbarg schemagen
 
 # Install bun/npm dependencies
+# Install bun/npm dependencies and generate schemas
 setup:
     bun install
+    just schemagen
 
 # Run unit tests (after check)
 test: check

package/examples/full-example/package.json

@@ -9,7 +9,6 @@
   },
   "scripts": {
     "biome": "biome",
-    "schemagen": "bun run scripts/schemagen.ts",
     "start": "bun run src/index.ts"
   },
   "dependencies": {
@@ -18,7 +17,6 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
     "@types/bun": "^1.3.12",
-    "ts-json-schema-generator": "^2.3.0",
     "typescript": "^5.9.3"
   }
 }

package/examples/full-example/src/commands/status/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import outputSchemaJson from "./outputSchema.json";
+
+export const outputSchema = outputSchemaJson as Record<string, unknown>;

package/examples/full-example/src/commands/status/command.ts

@@ -3,7 +3,7 @@ Status leaf — demonstrates outputSchema and ctx.appConfig.
 */
 
 import { type CliLeaf, CliOptionKind } from "argsbarg";
-import { STATUS_JSON_OUTPUT_SCHEMA } from "../../../schemas/outputSchemas.ts";
+import { outputSchema } from "./__generated__/index.ts";
 import type { StatusJsonOutput } from "./types.ts";
 
 export const statusCommand = {
@@ -16,7 +16,7 @@ export const statusCommand = {
       kind: CliOptionKind.Presence,
     },
   ],
-  outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
+  outputSchema,
   handler: (ctx) => {
     const out: StatusJsonOutput = {
       defaultRegion: ctx.appConfig.get("defaultRegion") as string | undefined,