argsbarg 6.0.2 → 6.1.0

package/CHANGELOG.md

@@ -7,11 +7,22 @@ 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 `src/**/schema.ts` into colocated `__generated__/` directories (`configSchema.json`, `inputSchema.json`, `outputSchema.json`, plus `index.ts` re-exports). Removes orphan `__generated__/` trees and stale JSON when schema roots or kinds are removed.
+- **`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
@@ -739,7 +750,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/v6.0.2...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

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,8 +268,8 @@ 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.ts` → `configSchema` from `__generated__/`                         |
-| `outputSchema`        | `src/commands/status/schema.ts` → `outputSchema` from `__generated__/`                  |
+| `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/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

@@ -142,7 +142,7 @@ Mirror the [output-schema.md](output-schema.md) pattern for config:
 
 ```mermaid
 flowchart LR
-  subgraph types [schema.ts]
+  subgraph types [types.ts]
     Marker["export type configType = AppConfig"]
   end
   subgraph gen [argsbarg schemagen]
@@ -164,14 +164,14 @@ flowchart LR
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled with argsbarg) |
-| Discovery | `export type configType = …` in `src/config/schema.ts` (type defined in same file) |
+| 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.ts
+// src/config/types.ts
 export interface AppConfig {
   apiToken: string;
 }

package/docs/output-schema.md

@@ -50,13 +50,13 @@ Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-
 
 ```mermaid
 flowchart LR
-  subgraph types [schema.ts]
+  subgraph types [types.ts]
     Config["export type configType = AppConfig"]
     Output["export type outputType = StatusJsonOutput"]
     Input["export type inputType = ToolInput (optional)"]
   end
   subgraph gen [argsbarg schemagen]
-    Discover["discover schema.ts roots"]
+    Discover["discover types.ts roots"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Gitignored __generated__]
@@ -74,8 +74,8 @@ flowchart LR
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled as an argsbarg dependency) |
-| Discovery | Walk `src/**/schema.ts`; generate from `export type outputType = …` / `inputType` / `configType` when the target type is **defined in that file** |
-| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `schema.ts` changes |
+| 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` → typecheck (no git diff on generated files) |
@@ -84,12 +84,10 @@ flowchart LR
 
 ### Declaring a schema root
 
-Put schema-facing interfaces in **`schema.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.ts
-import type { WorkspaceStatus } from "./types.ts";
-
+// src/commands/status/types.ts
 /** JSON stdout for `myapp status --json`. */
 export interface StatusJsonOutput {
   workspaces: WorkspaceStatus[];
@@ -99,10 +97,10 @@ export interface StatusJsonOutput {
 export type outputType = StatusJsonOutput;
 ```
 
-```typescript
-// src/ui/runHeadless/schema.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;
@@ -113,31 +111,35 @@ export type outputType = HeadlessOpResult;
 ```
 
 ```typescript
-// src/commands/render-invoice/schema.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.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.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.ts`. Shared shapes (e.g. `HeadlessOpResult`) live in one canonical `schema.ts`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
+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`.
 
 ### Generated artifacts
 
-Schemagen writes under `__generated__/` beside each `schema.ts`:
+Schemagen writes under `__generated__/` beside each `types.ts` with role exports:
 
 | Kind | Generated file | Exported const (from `__generated__/index.ts`) |
 | --- | --- | --- |
@@ -174,15 +176,15 @@ appConfig: { jsonSchema: configSchema, entries: { … } },
 
 **Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
 
-1. **Schema roots** — `export interface` in `schema.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** `__generated__/` — change types/JSDoc in `schema.ts`, run `just schemagen`.
+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.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`. */
@@ -211,7 +213,7 @@ Per consumer repo (optional):
 
 ## Contributor workflow
 
-1. Add or edit schema roots in `src/**/schema.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+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.
@@ -219,7 +221,7 @@ Per consumer repo (optional):
 
 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 — `schema.ts` roots, `__generated__/`, 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
 

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.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.ts` | Generated artifact | Import on leaf / program |
+| Export in `types.ts` | Generated artifact | Import on leaf / program |
 | --- | --- | --- |
-| `export type configType = …` | `__generated__/configSchema.json` | `{ configSchema }` from `config/__generated__/index.ts` → `program.appConfig.jsonSchema` |
-| `export type outputType = …` | `__generated__/outputSchema.json` | `{ outputSchema }` from `__generated__/index.ts` → `leaf.outputSchema` |
-| `export type inputType = …` | `__generated__/inputSchema.json` | `{ inputSchema }` from `__generated__/index.ts` → `leaf.inputSchema` |
+| `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.ts` only. Domain helpers stay in sibling `types.ts`. `__generated__/` is gitignored — 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`).
 
 ## Consumer docs
 

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

@@ -1 +1,19 @@
-export type { StatusJsonOutput } from "./schema.ts";
+/** JSON stdout for `full-example status --json`. */
+export interface StatusJsonOutput {
+  /** Resolved AWS region. */
+  defaultRegion?: string;
+  /** Resolved retry count. */
+  maxRetries?: number;
+  /** Whether apiToken is set (value never included). */
+  apiTokenSet: boolean;
+  /** App version from program root. */
+  version: string;
+}
+
+/** Returns status JSON (identity helper for schema generation). */
+export function buildStatusJson(output: StatusJsonOutput): StatusJsonOutput {
+  return output;
+}
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;

package/examples/full-example/src/program.ts

@@ -4,10 +4,10 @@ Kitchen-sink CliProgram — every argsbarg builtin enabled; command registration
 
 import type { CliAppConfig, CliAppConfigEntry, CliProgram } from "argsbarg";
 import readmeText from "../README.md" with { type: "text" };
-import { configSchema } from "./config/__generated__/index.ts";
 import { createIdentity } from "../scripts/create-identity.ts";
 import { echoCommand } from "./commands/echo/command.ts";
 import { statusCommand } from "./commands/status/command.ts";
+import { configSchema } from "./config/__generated__/index.ts";
 
 const configEntries = {
   apiToken: {

package/index.d.ts

@@ -45,7 +45,7 @@ declare class AppConfigSnapshot {
 }
 export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
 /** Coerced leaf inputs keyed by option and positional names. */
-export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | unknown | undefined>;
 /**
  * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
@@ -92,6 +92,11 @@ export declare class CliContext {
 	positional(name: string): string | string[] | undefined;
 	/** Reads coerced option and positional values for the current leaf from schema metadata. */
 	readLeafInputs(): CliLeafInputs;
+	/**
+	 * Reads coerced leaf inputs, resolving Json options from flags, piped stdin (when `pipable`),
+	 * or MCP/API toolArgs, and validates against `leaf.inputSchema` when set.
+	 */
+	readLeafInputsAsync(): Promise<CliLeafInputs>;
 	private _readOptionValue;
 	private _leafNode;
 	private _posMap;
@@ -102,7 +107,7 @@ export declare class CliContext {
  */
 export type CliInvocation = "cli" | "mcp" | "api";
 /**
- * Option kinds: presence (boolean flag), string (free-form text), number (strict double), or enum (fixed choices).
+ * Option kinds: presence (boolean flag), string (free-form text), number (strict double), enum (fixed choices), or json (parsed JSON object/array).
  */
 export declare enum CliOptionKind {
 	/** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -112,7 +117,9 @@ export declare enum CliOptionKind {
 	/** Strict floating-point value (parsed at validation time). */
 	Number = "number",
 	/** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
-	Enum = "enum"
+	Enum = "enum",
+	/** JSON object or array (parsed from `--name '<json>'`, piped stdin when `pipable`, or MCP/API tool body). */
+	Json = "json"
 }
 /**
  * Named validation/coercion for string options (`format` on `CliOption`).
@@ -176,6 +183,11 @@ export interface CliOption {
 	default?: string;
 	/** Regex pattern for string options. Mutually exclusive with `format`. */
 	pattern?: string;
+	/**
+	 * When `true` on a `Json` option, CLI may omit `--name` and supply JSON via stdin instead.
+	 * If `--name` is set, the flag value wins and stdin is not read.
+	 */
+	pipable?: boolean;
 }
 /**
  * An ordered positional argument slot, listed on leaf `positionals`.
@@ -631,6 +643,15 @@ dryRun?: boolean,
 interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
+/** Thrown when {@link CliContext.readLeafInputsAsync} cannot resolve or validate inputs. */
+export declare class LeafInputError extends Error {
+	constructor(message: string);
+}
+/**
+ * Reads coerced leaf inputs, resolving Json options from flags, piped stdin, or toolArgs,
+ * and validates against `leaf.inputSchema` when set.
+ */
+export declare function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.0.2",
+  "version": "6.1.0",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/cli-tool/program.ts

@@ -95,7 +95,8 @@ export const program = {
     },
     {
       key: "schemagen",
-      description: "Generate JSON Schema artifacts from src/**/schema.ts into colocated __generated__/ directories.",
+      description:
+        "Generate JSON Schema artifacts from src/**/types.ts role exports into colocated __generated__/ directories.",
       options: [
         {
           name: "root",

package/src/cli-tool/schemagen/cleanup.ts

@@ -5,7 +5,7 @@ Remove stale __generated__/ directories and files after schemagen runs.
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import type { SchemaRoot } from "./discover-schema-roots.ts";
-import { GENERATED_DIR, SCHEMA_FILE, schemaJsonBasename } from "./names.ts";
+import { GENERATED_DIR, schemaJsonBasename, TYPES_FILE } from "./names.ts";
 
 function listGeneratedDirs(srcDir: string, projectRoot: string, out: string[]): void {
   for (const ent of readdirSync(srcDir)) {
@@ -38,8 +38,8 @@ export function cleanStaleGenerated(
 
   for (const relGeneratedDir of generatedDirs) {
     const generatedDir = join(projectRoot, relGeneratedDir);
-    const relSchemaPath = relative(projectRoot, join(dirname(generatedDir), SCHEMA_FILE));
-    const roots = existsSync(join(projectRoot, relSchemaPath)) ? (activeBySchemaFile.get(relSchemaPath) ?? []) : [];
+    const relTypesPath = relative(projectRoot, join(dirname(generatedDir), TYPES_FILE));
+    const roots = existsSync(join(projectRoot, relTypesPath)) ? (activeBySchemaFile.get(relTypesPath) ?? []) : [];
 
     if (roots.length === 0) {
       rmSync(generatedDir, { recursive: true, force: true });

package/src/cli-tool/schemagen/discover-schema-roots.ts

@@ -1,10 +1,10 @@
 /*
-Discovers schema roots in schema.ts files via configType / inputType / outputType exports.
+Discovers schema roots in types.ts files via configType / inputType / outputType exports.
 */
 
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-import { SCHEMA_FILE } from "./names.ts";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { TYPES_FILE } from "./names.ts";
 
 export type SchemaRootKind = "config" | "input" | "output";
 
@@ -13,11 +13,15 @@ export type SchemaRole = "configType" | "inputType" | "outputType";
 export interface SchemaRoot {
   kind: SchemaRootKind;
   typeName: string;
-  /** Path relative to project root (e.g. src/config/schema.ts). */
+  /** Path to types.ts relative to project root (anchors __generated__/ output). */
   path: string;
+  /** Path to the file that defines `typeName` (defaults to `path`). */
+  sourcePath: string;
 }
 
 const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
+const HAS_ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=/;
+const IMPORT_RE = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
 
 const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
   configType: "config",
@@ -25,21 +29,25 @@ const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
   outputType: "output",
 };
 
-function listSchemaFiles(srcDir: string, baseDir: string, out: string[]): void {
+function listTypesManifestFiles(srcDir: string, baseDir: string, out: string[]): void {
   for (const ent of readdirSync(srcDir)) {
     const full = join(srcDir, ent);
     const st = statSync(full);
     if (st.isDirectory()) {
-      listSchemaFiles(full, baseDir, out);
+      listTypesManifestFiles(full, baseDir, out);
       continue;
     }
-    if (ent === SCHEMA_FILE) {
+    if (ent !== TYPES_FILE) {
+      continue;
+    }
+    const text = readFileSync(full, "utf8");
+    if (HAS_ROLE_EXPORT_RE.test(text)) {
       out.push(relative(baseDir, full));
     }
   }
 }
 
-/** True when `typeName` is declared in this file (not a re-export alias to another module). */
+/** True when `typeName` is declared in this file (not a schemagen role alias). */
 function isTypeDefinedInFile(text: string, typeName: string): boolean {
   if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
     return true;
@@ -50,7 +58,62 @@ function isTypeDefinedInFile(text: string, typeName: string): boolean {
   return false;
 }
 
-function discoverFromFile(path: string, text: string): SchemaRoot[] {
+function parseLocalTypeImports(text: string): Map<string, string> {
+  const imports = new Map<string, string>();
+  for (const match of text.matchAll(IMPORT_RE)) {
+    const names = match[1];
+    const from = match[2];
+    if (!names || !from?.startsWith(".")) {
+      continue;
+    }
+    for (const part of names.split(",")) {
+      const trimmed = part.trim();
+      const nameMatch = trimmed.match(/^(?:type\s+)?(\w+)(?:\s+as\s+(\w+))?$/);
+      if (!nameMatch?.[1]) {
+        continue;
+      }
+      const localName = nameMatch[2] ?? nameMatch[1];
+      imports.set(localName, from);
+    }
+  }
+  return imports;
+}
+
+function resolveModuleFile(manifestFile: string, specifier: string): string | null {
+  const base = join(dirname(manifestFile), specifier);
+  const candidates = [base, `${base}.ts`, join(base, "index.ts")];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** Resolve a role alias to the module that defines `typeName`, when imported from a relative path. */
+function resolveAliasedTypeSource(
+  projectRoot: string,
+  manifestRelPath: string,
+  manifestText: string,
+  typeName: string,
+): string | null {
+  const manifestFile = join(projectRoot, manifestRelPath);
+  const specifier = parseLocalTypeImports(manifestText).get(typeName);
+  if (!specifier) {
+    return null;
+  }
+  const moduleFile = resolveModuleFile(manifestFile, specifier);
+  if (!moduleFile) {
+    return null;
+  }
+  const moduleText = readFileSync(moduleFile, "utf8");
+  if (!isTypeDefinedInFile(moduleText, typeName)) {
+    return null;
+  }
+  return relative(projectRoot, moduleFile);
+}
+
+function discoverFromFile(projectRoot: string, path: string, text: string): SchemaRoot[] {
   const rolesSeen = new Set<SchemaRole>();
   const roots: SchemaRoot[] = [];
 
@@ -64,27 +127,34 @@ function discoverFromFile(path: string, text: string): SchemaRoot[] {
       throw new Error(`${path}: duplicate export type ${role}`);
     }
     rolesSeen.add(role);
+
+    let sourcePath = path;
     if (!isTypeDefinedInFile(text, typeName)) {
-      continue;
+      const resolved = resolveAliasedTypeSource(projectRoot, path, text, typeName);
+      if (!resolved) {
+        continue;
+      }
+      sourcePath = resolved;
     }
-    roots.push({ kind: ROLE_TO_KIND[role], typeName, path });
+
+    roots.push({ kind: ROLE_TO_KIND[role], typeName, path, sourcePath });
   }
 
   return roots;
 }
 
-/** Find all schema roots under `srcDir` in files named `schema.ts`. */
+/** Find all schema roots under `srcDir` in `types.ts` files with role exports. */
 export function discoverSchemaRoots(projectRoot: string, srcDir = "src"): SchemaRoot[] {
   const srcPath = join(projectRoot, srcDir);
   const files: string[] = [];
-  listSchemaFiles(srcPath, projectRoot, files);
+  listTypesManifestFiles(srcPath, projectRoot, files);
 
   const roots: SchemaRoot[] = [];
   const typeOwners = new Map<string, string>();
 
   for (const relPath of files.sort()) {
     const text = readFileSync(join(projectRoot, relPath), "utf8");
-    for (const root of discoverFromFile(relPath, text)) {
+    for (const root of discoverFromFile(projectRoot, relPath, text)) {
       const prev = typeOwners.get(root.typeName);
       if (prev) {
         throw new Error(`${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`);

package/src/cli-tool/schemagen/index.ts

@@ -1,3 +1,3 @@
 export { discoverSchemaRoots, type SchemaRoot, type SchemaRootKind } from "./discover-schema-roots.ts";
-export { GENERATED_DIR, SCHEMA_FILE, schemaExportName, schemaJsonBasename } from "./names.ts";
+export { GENERATED_DIR, schemaExportName, schemaJsonBasename, TYPES_FILE } from "./names.ts";
 export { type RunSchemagenOptions, type RunSchemagenResult, runSchemagen } from "./run.ts";

package/src/cli-tool/schemagen/names.ts

@@ -1,10 +1,10 @@
 import type { SchemaRootKind } from "./discover-schema-roots.ts";
 
-/** Directory name for generated schema artifacts (next to `schema.ts`). */
+/** Directory name for generated schema artifacts (next to `types.ts`). */
 export const GENERATED_DIR = "__generated__";
 
-/** TypeScript schema root filename under `src/`. */
-export const SCHEMA_FILE = "schema.ts";
+/** TypeScript schemagen manifest filename under `src/`. */
+export const TYPES_FILE = "types.ts";
 
 /** JSON basename for a schema root kind (`outputSchema.json`, etc.). */
 export function schemaJsonBasename(kind: SchemaRootKind): string {

package/src/cli-tool/schemagen/run.ts

@@ -36,8 +36,9 @@ function resolveTsconfig(projectRoot: string, tsconfig: string): string {
 }
 
 function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoot): Record<string, unknown> {
+  const typeFile = join(projectRoot, root.sourcePath);
   const generator = createGenerator({
-    path: join(projectRoot, root.path),
+    path: typeFile,
     type: root.typeName,
     tsconfig: tsconfigPath,
     topRef: false,