argsbarg 6.1.0 → 6.1.1

package/CHANGELOG.md

@@ -7,12 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.1] - 2026-07-23
+
+### Added
+
+- **`ctx.inputs`** — coerced, pre-validated leaf inputs (getter; preferred over `readLeafInputs()`).
+- **`ctx.inputsAs<T>()`** — `ctx.inputs` cast to a schemagen or app input type (`T` unconstrained; consumer-asserted).
+
+### Changed
+
+- **`leaf.inputSchema` validation** — runs before the leaf handler in `Cli.run()` and `Cli.invoke()` (same JSON Schema subset as `program.appConfig`). `LeafInputError` prints contextual help on CLI. `ctx.inputs` returns the cached, pre-validated result.
+- **`ctx.readLeafInputs()`** — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+
 ## [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.
+- **`ctx.jsonOpt(name)`** — parsed Json option from flag, preloaded stdin, or MCP/API `toolArgs`.
+- **`ctx.readLeafInputs()`** — all coerced inputs; validates against `leaf.inputSchema` when set (stdin preloaded before handler).
+- **`ctx.readLeafInputsAsync()`** — deprecated alias for sync `readLeafInputs()`.
 
 ### Changed
 
@@ -750,7 +764,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.1.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.1...HEAD
+[6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1
 [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

package/README.md

@@ -207,8 +207,11 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.durationOpt("timeout")` — duration options (`format: CliValueFormat.Duration`) as milliseconds.
 - `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.inputs` — coerced option and positional values for the current leaf; when `inputSchema` is set, validated before the handler runs and cached on `ctx`.
+- `ctx.inputsAs<T>()` — `ctx.inputs` cast to a schemagen or app input type.
+- `ctx.readLeafInputs()` — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+- `ctx.jsonOpt(name)` — parsed Json option (flag, preloaded stdin, or MCP/API `toolArgs`).
+- `ctx.readLeafInputsAsync()` — deprecated alias for `readLeafInputs()`.
 - `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`.

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, 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`.
+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 `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — piped stdin is loaded before the handler runs.

package/docs/cli-program.md

@@ -203,14 +203,17 @@ handler: async (ctx) => {
 
 Read varargs with `ctx.positional("uids")` (returns `string[]`) or `ctx.args`. Do not comma-split argv tokens or use `format` on positionals.
 
-**`readLeafInputs()`** — for leaves with several flags, one schema-driven read instead of hand-rolled `hasFlag` / `stringOpt` lines:
+**`ctx.inputs`** — coerced option and positional values for the current leaf. When `leaf.inputSchema` is set, argsbarg validates **before the handler runs** and caches the result on `ctx`:
 
 ```typescript
-const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs();
-// duration → number (ms); comma-list → string[]; presence → boolean; number → number
+const { limit, "skip-readiness": skipReadiness, timeout } = ctx.inputs;
+// or, with a schemagen type:
+const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
 ```
 
-**`CliLeafInputs`** — return type of `readLeafInputs()` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
+**`readLeafInputs()`** — deprecated alias for `ctx.inputs`.
+
+**`CliLeafInputs`** — return type of `ctx.inputs` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
 
 | Schema | Value in `CliLeafInputs` |
 | --- | --- |
@@ -223,9 +226,9 @@ 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) |
+| `kind: json` | parsed object/array or `undefined` (`ctx.jsonOpt(name)`; piped stdin preloaded before handler) |
 
-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.
+Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `ctx.inputs` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `ctx.inputs` for coerced values.
 
 ### Json options and piped stdin
 
@@ -243,12 +246,12 @@ For nested tool bodies (e.g. invoice template data), declare a matching property
 
 | Surface | How `invoice` is supplied |
 | --- | --- |
-| CLI | `--invoice '<json>'` **or** omit the flag and pipe JSON to stdin |
+| CLI | `--invoice '<json>'` **or** omit the flag and pipe JSON to stdin (preloaded before the handler) |
 | 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`).
+Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same JSON Schema subset as `program.appConfig`); `ctx.inputs` returns the cached result.
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 

package/docs/output-schema.md

@@ -133,7 +133,7 @@ export type outputType = RenderInvoiceOutput;
 
 **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`.
 
-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).
+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).
 
 When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 

package/index.d.ts

@@ -59,9 +59,12 @@ export declare class CliContext {
 	readonly appConfig: AnyAppConfigSnapshot;
 	/** Original flat tool arguments for API/MCP invocations (when provided). */
 	readonly toolArgs?: Record<string, unknown>;
+	/** Pipable Json option values read from stdin before the handler (CLI only). */
+	readonly preloadedJson: Record<string, unknown>;
 	private response?;
+	private leafInputsCache?;
 	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>);
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>, preloadedJson?: Record<string, unknown>);
 	/**
 	 * Sets the machine-readable response for API/MCP invocations, or writes to stdout in CLI mode.
 	 * May only be called once per invocation.
@@ -88,16 +91,30 @@ export declare class CliContext {
 	dateOpt(name: string): string | undefined;
 	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
 	dateTimeOpt(name: string): string | undefined;
+	/**
+	 * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+	 * Flag wins over stdin and toolArgs.
+	 */
+	jsonOpt(name: string): unknown | undefined;
 	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
 	positional(name: string): string | string[] | undefined;
-	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	/**
+	 * Coerced option and positional values for the current leaf.
+	 * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+	 */
+	get inputs(): CliLeafInputs;
+	/**
+	 * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
+	 */
+	inputsAs<T = CliLeafInputs>(): T;
+	/**
+	 * @deprecated Use {@link inputs} or {@link inputsAs}.
+	 */
 	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.
+	 * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
 	 */
 	readLeafInputsAsync(): Promise<CliLeafInputs>;
-	private _readOptionValue;
 	private _leafNode;
 	private _posMap;
 	private _positionalMap;
@@ -596,6 +613,8 @@ export declare class Cli {
 	}): Promise<CliInvokeResult>;
 	serveMcp(): Promise<never>;
 	serveApi(): Promise<never>;
+	private ensureValidatedLeafInputs;
+	private exitLeafInputError;
 	private prepareDispatch;
 	private buildAppConfigSnapshot;
 }
@@ -643,14 +662,25 @@ 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. */
+/** Thrown when leaf input resolution or validation fails. */
 export declare class LeafInputError extends Error {
 	constructor(message: string);
 }
+/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
+export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
+/**
+ * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
+ * Call from {@link Cli.run} before constructing the handler context.
+ */
+export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation): Promise<Record<string, unknown>>;
 /**
- * Reads coerced leaf inputs, resolving Json options from flags, piped stdin, or toolArgs,
- * and validates against `leaf.inputSchema` when set.
+ * Loads coerced leaf inputs and validates against `leaf.inputSchema` when set.
+ * Used by {@link CliContext.inputs}; prefer `ctx.inputs` or `ctx.inputsAs()` in handlers.
  */
+export declare function loadLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use {@link CliContext.inputs} or {@link loadLeafInputs} via `ctx.inputs`. */
+export declare function readLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs. */
 export declare function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {

package/package.json

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

package/src/cli.ts

@@ -18,6 +18,7 @@ import { readAppConfigFileRaw, resolveAppConfigPath } from "./config/file.ts";
 import { effectiveJsonSchema } from "./config/schema.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { LeafInputError, preloadPipableJson } from "./leaf-inputs.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
@@ -124,14 +125,41 @@ export class Cli {
       exitOnMissing: !skipRequiredConfig,
     });
 
-    const ctx = new CliContext(this.program.key, pr.path, pr.args, pr.opts, this.program, "cli", snapshot);
+    let preloadedJson: Record<string, unknown> = {};
     try {
+      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli");
+    } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      const color = process.stderr.isTTY;
+      process.stderr.write(color ? `\u001B[31m${msg}\u001B[0m\n` : `${msg}\n`);
+      process.exit(1);
+    }
+
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      "cli",
+      snapshot,
+      undefined,
+      preloadedJson,
+    );
+    try {
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
       }
       process.exit(0);
     } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
       if (err instanceof Error) {
         process.stderr.write(`${err.message}\n`);
       }
@@ -232,6 +260,7 @@ export class Cli {
         });
       }
 
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
@@ -260,6 +289,15 @@ export class Cli {
         const msg = stderr.trim() || `Exit code ${err.code}`;
         return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
       }
+      if (err instanceof LeafInputError) {
+        return {
+          kind: "error",
+          exitCode: 1,
+          stdout,
+          stderr: `${err.message}\n`,
+          errorMsg: err.message,
+        };
+      }
       if (err instanceof Error) {
         return {
           kind: "error",
@@ -320,6 +358,21 @@ export class Cli {
     }
   }
 
+  private ensureValidatedLeafInputs(ctx: CliContext, leaf: CliLeaf): void {
+    if (leaf.inputSchema === undefined) {
+      return;
+    }
+    ctx.inputs;
+  }
+
+  private exitLeafInputError(err: LeafInputError, helpPath: string[]): never {
+    const color = process.stderr.isTTY;
+    const msg = color ? `\u001B[31m${err.message}\u001B[0m` : err.message;
+    process.stderr.write(`${msg}\n`);
+    process.stderr.write(cliHelpRender(this.presentationRoot, helpPath, true));
+    process.exit(1);
+  }
+
   private prepareDispatch(
     argv: string[],
     opts?: { presentationFallback?: boolean },

package/src/context.ts

@@ -10,11 +10,10 @@ parsed values.
 import type { AnyAppConfigSnapshot } from "./config/context.ts";
 import { EmptyAppConfigSnapshot } from "./config/context.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
-import { readLeafInputsAsync as loadLeafInputsAsync } from "./leaf-inputs.ts";
-import { collectOptionDefs } from "./parse.ts";
+import { loadLeafInputs, readJsonOptionValue } from "./leaf-inputs.ts";
 import { normalizeRespondOptions, writeRespondBodyToStdout } from "./respond.ts";
-import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram, CliRespondOptions } from "./types.ts";
-import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /** Coerced leaf inputs keyed by option and positional names. */
@@ -33,8 +32,11 @@ export class CliContext {
   readonly appConfig: AnyAppConfigSnapshot;
   /** Original flat tool arguments for API/MCP invocations (when provided). */
   readonly toolArgs?: Record<string, unknown>;
+  /** Pipable Json option values read from stdin before the handler (CLI only). */
+  readonly preloadedJson: Record<string, unknown>;
 
   private response?: CliRespondOptions;
+  private leafInputsCache?: CliLeafInputs;
 
   /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -46,6 +48,7 @@ export class CliContext {
     invocation: CliInvocation = "cli",
     appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
     toolArgs?: Record<string, unknown>,
+    preloadedJson: Record<string, unknown> = {},
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -55,6 +58,7 @@ export class CliContext {
     this.invocation = invocation;
     this.appConfig = appConfig;
     this.toolArgs = toolArgs;
+    this.preloadedJson = preloadedJson;
   }
 
   /**
@@ -137,71 +141,50 @@ export class CliContext {
     return parseDateTime(s);
   }
 
+  /**
+   * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+   * Flag wins over stdin and toolArgs.
+   */
+  jsonOpt(name: string): unknown | undefined {
+    return readJsonOptionValue(this, name);
+  }
+
   /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
   positional(name: string): string | string[] | undefined {
     return this._positionalMap()[name];
   }
 
-  /** Reads coerced option and positional values for the current leaf from schema metadata. */
-  readLeafInputs(): CliLeafInputs {
-    const leaf = this._leafNode();
-    if (!leaf) return {};
-
-    const out: CliLeafInputs = {};
-    for (const opt of collectOptionDefs(this.program, this.commandPath)) {
-      out[opt.name] = this._readOptionValue(opt);
-    }
-    for (const p of leaf.positionals ?? []) {
-      const val = this.positional(p.name);
-      if (val === undefined) {
-        out[p.name] = undefined;
-      } else if (Array.isArray(val)) {
-        out[p.name] = val;
-      } else {
-        out[p.name] = val;
-      }
+  /**
+   * Coerced option and positional values for the current leaf.
+   * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+   */
+  get inputs(): CliLeafInputs {
+    if (this.leafInputsCache !== undefined) {
+      return this.leafInputsCache;
     }
-    return out;
+    this.leafInputsCache = loadLeafInputs(this);
+    return this.leafInputsCache;
   }
 
   /**
-   * Reads coerced leaf inputs, resolving Json options from flags, piped stdin (when `pipable`),
-   * or MCP/API toolArgs, and validates against `leaf.inputSchema` when set.
+   * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
    */
-  async readLeafInputsAsync(): Promise<CliLeafInputs> {
-    return loadLeafInputsAsync(this);
+  inputsAs<T = CliLeafInputs>(): T {
+    return this.inputs as T;
   }
 
-  private _readOptionValue(opt: CliOption): boolean | number | string | string[] | unknown | undefined {
-    if (opt.kind === CliOptionKind.Presence) {
-      return this.hasFlag(opt.name);
-    }
-    if (opt.kind === CliOptionKind.Number) {
-      const n = this.numberOpt(opt.name);
-      return n === null ? undefined : n;
-    }
-    if (opt.kind === CliOptionKind.Json) {
-      const raw = this.stringOpt(opt.name);
-      if (raw === undefined) return undefined;
-      try {
-        return JSON.parse(raw) as unknown;
-      } catch {
-        return undefined;
-      }
-    }
-    if (opt.format === CliValueFormat.Duration) {
-      return this.durationOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.CommaList) {
-      return this.commaListOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.Date) {
-      return this.dateOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.DateTime) {
-      return this.dateTimeOpt(opt.name);
-    }
-    return this.stringOpt(opt.name);
+  /**
+   * @deprecated Use {@link inputs} or {@link inputsAs}.
+   */
+  readLeafInputs(): CliLeafInputs {
+    return this.inputs;
+  }
+
+  /**
+   * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
+   */
+  readLeafInputsAsync(): Promise<CliLeafInputs> {
+    return Promise.resolve(this.readLeafInputs());
   }
 
   private _leafNode(): CliLeaf | undefined {

package/src/index.ts

@@ -28,7 +28,14 @@ export {
   shouldRunHeadlessWithYes,
   wantsExplicitJson,
 } from "./headless.ts";
-export { LeafInputError, readLeafInputsAsync } from "./leaf-inputs.ts";
+export {
+  LeafInputError,
+  loadLeafInputs,
+  preloadPipableJson,
+  readJsonOptionValue,
+  readLeafInputs,
+  readLeafInputsAsync,
+} from "./leaf-inputs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export type {

package/src/leaf-inputs.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { Cli, CliContext, CliOptionKind } from "./index.ts";
-import { LeafInputError, readLeafInputsAsync } from "./leaf-inputs.ts";
+import { LeafInputError, readLeafInputs } from "./leaf-inputs.ts";
 import type { CliProgram } from "./types.ts";
 
 const invoiceSchema = {
@@ -46,16 +46,13 @@ function renderProgram(): CliProgram {
             required: true,
           },
         ],
-        handler: async (ctx) => {
-          const inputs = await ctx.readLeafInputsAsync();
-          return inputs;
-        },
+        handler: (ctx) => ctx.readLeafInputs(),
       },
     ],
   } satisfies CliProgram;
 }
 
-describe("readLeafInputsAsync", () => {
+describe("readLeafInputs / jsonOpt", () => {
   test("reads Json option from MCP toolArgs", async () => {
     const cli = new Cli(renderProgram());
     const result = await cli.invoke(["render", "--format", "pdf"], {
@@ -83,6 +80,33 @@ describe("readLeafInputsAsync", () => {
     });
   });
 
+  test("jsonOpt reads from preloadedJson", () => {
+    const program = renderProgram();
+    const ctx = new CliContext(
+      "json-pipe-test",
+      ["render"],
+      [],
+      { format: "pdf" },
+      program,
+      "cli",
+      undefined,
+      undefined,
+      { invoice: { id: "piped" } },
+    );
+    expect(ctx.jsonOpt("invoice")).toEqual({ id: "piped" });
+    expect(ctx.inputs).toEqual({ format: "pdf", invoice: { id: "piped" } });
+  });
+
+  test("inputsAs returns schemagen-shaped inputs", () => {
+    type RenderInput = { format: "pdf" | "html"; invoice: { id: string } };
+    const program = renderProgram();
+    const ctx = new CliContext("json-pipe-test", ["render"], [], { format: "pdf" }, program, "mcp", undefined, {
+      format: "pdf",
+      invoice: { id: "INV-1" },
+    });
+    expect(ctx.inputsAs<RenderInput>()).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
+  });
+
   test("rejects invalid Json flag at parse time", async () => {
     const cli = new Cli(renderProgram());
     const result = await cli.invoke(["render", "--format", "pdf", "--invoice", "not-json"], {
@@ -103,10 +127,95 @@ describe("readLeafInputsAsync", () => {
     expect(result.stderr).toContain("invoice.id");
   });
 
-  test("readLeafInputsAsync throws LeafInputError when required Json is missing", async () => {
+  test("validates inputSchema before handler runs", async () => {
+    let handlerCalled = false;
+    const program = {
+      key: "json-pipe-test",
+      version: "1.0.0",
+      description: "pre-handler validation",
+      commands: [
+        {
+          key: "render",
+          description: "Render",
+          inputSchema: invoiceSchema,
+          options: [
+            {
+              name: "format",
+              description: "Output format",
+              kind: CliOptionKind.Enum,
+              choices: ["pdf", "html"],
+              required: true,
+            },
+            {
+              name: "invoice",
+              description: "Invoice JSON",
+              kind: CliOptionKind.Json,
+              pipable: true,
+              required: true,
+            },
+          ],
+          handler: () => {
+            handlerCalled = true;
+            return { ok: true };
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["render", "--format", "pdf"], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: 123 } },
+    });
+    expect(result.kind).toBe("error");
+    expect(handlerCalled).toBe(false);
+  });
+
+  test("inputs returns cached inputs after pre-handler validation", async () => {
+    const inputs: unknown[] = [];
+    const program = {
+      key: "json-pipe-test",
+      version: "1.0.0",
+      description: "cached inputs",
+      commands: [
+        {
+          key: "render",
+          description: "Render",
+          inputSchema: invoiceSchema,
+          options: [
+            {
+              name: "format",
+              description: "Output format",
+              kind: CliOptionKind.Enum,
+              choices: ["pdf", "html"],
+              required: true,
+            },
+            {
+              name: "invoice",
+              description: "Invoice JSON",
+              kind: CliOptionKind.Json,
+              required: true,
+            },
+          ],
+          handler: (ctx) => {
+            inputs.push(ctx.inputs);
+            inputs.push(ctx.inputs);
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    await cli.invoke(["render", "--format", "pdf"], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(inputs).toHaveLength(2);
+    expect(inputs[0]).toEqual(inputs[1]);
+  });
+
+  test("readLeafInputs throws LeafInputError when required Json is missing", () => {
     const program = renderProgram();
     const ctx = new CliContext("json-pipe-test", ["render"], [], { format: "pdf" }, program, "mcp", undefined, {});
-    await expect(readLeafInputsAsync(ctx)).rejects.toThrow(LeafInputError);
+    expect(() => readLeafInputs(ctx)).toThrow(LeafInputError);
   });
 
   test("omits undefined optional properties before inputSchema validation", async () => {
@@ -155,7 +264,7 @@ describe("readLeafInputsAsync", () => {
               required: true,
             },
           ],
-          handler: async (ctx) => ctx.readLeafInputsAsync(),
+          handler: (ctx) => ctx.readLeafInputs(),
         },
       ],
     } satisfies CliProgram;

package/src/leaf-inputs.ts

@@ -1,15 +1,15 @@
 /*
-Async leaf input reads: Json options (flag, piped stdin, or toolArgs), optional inputSchema validation.
+Leaf input reads: Json options (flag, preloaded stdin, or toolArgs), optional inputSchema validation.
 */
 
 import { validateConfigDocument } from "./config/validate.ts";
 import type { CliContext, CliLeafInputs } from "./context.ts";
 import { collectOptionDefs } from "./parse.ts";
-import type { CliLeaf, CliNode, CliOption } from "./types.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
 import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
 import { isInteractiveTty } from "./utils.ts";
 
-/** Thrown when {@link CliContext.readLeafInputsAsync} cannot resolve or validate inputs. */
+/** Thrown when leaf input resolution or validation fails. */
 export class LeafInputError extends Error {
   constructor(message: string) {
     super(message);
@@ -28,40 +28,8 @@ function leafNode(ctx: CliContext): CliLeaf | undefined {
   return isCliLeaf(node) ? node : undefined;
 }
 
-function readSyncOptionValue(
-  ctx: CliContext,
-  opt: CliOption,
-): boolean | number | string | string[] | unknown | undefined {
-  if (opt.kind === CliOptionKind.Presence) {
-    return ctx.hasFlag(opt.name);
-  }
-  if (opt.kind === CliOptionKind.Number) {
-    const n = ctx.numberOpt(opt.name);
-    return n === null ? undefined : n;
-  }
-  if (opt.kind === CliOptionKind.Json) {
-    const raw = ctx.stringOpt(opt.name);
-    if (raw === undefined) return undefined;
-    return parseJsonText(raw, `--${opt.name}`);
-  }
-  if (opt.format !== undefined) {
-    if (opt.format === CliValueFormat.Duration) {
-      return ctx.durationOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.CommaList) {
-      return ctx.commaListOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.Date) {
-      return ctx.dateOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.DateTime) {
-      return ctx.dateTimeOpt(opt.name);
-    }
-  }
-  return ctx.stringOpt(opt.name);
-}
-
-function parseJsonText(raw: string, label: string): unknown {
+/** Parses a JSON string from a `--name` flag value. */
+export function parseJsonText(raw: string, label: string): unknown {
   const trimmed = raw.trim();
   if (trimmed.length === 0) {
     throw new LeafInputError(`${label}: JSON value is empty`);
@@ -107,46 +75,85 @@ function validateAgainstInputSchema(out: CliLeafInputs, inputSchema: Record<stri
   }
 }
 
+/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
+export function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined {
+  const flagValue = ctx.stringOpt(name);
+  if (flagValue !== undefined) {
+    return parseJsonText(flagValue, `--${name}`);
+  }
+  if (name in ctx.preloadedJson) {
+    return ctx.preloadedJson[name];
+  }
+  if (ctx.toolArgs !== undefined && name in ctx.toolArgs) {
+    return ctx.toolArgs[name];
+  }
+  return undefined;
+}
+
+/**
+ * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
+ * Call from {@link Cli.run} before constructing the handler context.
+ */
+export async function preloadPipableJson(
+  program: CliProgram,
+  commandPath: string[],
+  opts: Record<string, string>,
+  invocation: CliInvocation,
+): Promise<Record<string, unknown>> {
+  if (invocation !== "cli" || isInteractiveTty) {
+    return {};
+  }
+  for (const opt of collectOptionDefs(program, commandPath)) {
+    if (opt.kind === CliOptionKind.Json && opt.pipable && !(opt.name in opts)) {
+      return { [opt.name]: await readPipedJsonStdin() };
+    }
+  }
+  return {};
+}
+
+function readSyncOptionValue(
+  ctx: CliContext,
+  opt: CliOption,
+): boolean | number | string | string[] | unknown | undefined {
+  if (opt.kind === CliOptionKind.Presence) {
+    return ctx.hasFlag(opt.name);
+  }
+  if (opt.kind === CliOptionKind.Number) {
+    const n = ctx.numberOpt(opt.name);
+    return n === null ? undefined : n;
+  }
+  if (opt.kind === CliOptionKind.Json) {
+    return readJsonOptionValue(ctx, opt.name);
+  }
+  if (opt.format !== undefined) {
+    if (opt.format === CliValueFormat.Duration) {
+      return ctx.durationOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.CommaList) {
+      return ctx.commaListOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.Date) {
+      return ctx.dateOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.DateTime) {
+      return ctx.dateTimeOpt(opt.name);
+    }
+  }
+  return ctx.stringOpt(opt.name);
+}
+
 /**
- * Reads coerced leaf inputs, resolving Json options from flags, piped stdin, or toolArgs,
- * and validates against `leaf.inputSchema` when set.
+ * Loads coerced leaf inputs and validates against `leaf.inputSchema` when set.
+ * Used by {@link CliContext.inputs}; prefer `ctx.inputs` or `ctx.inputsAs()` in handlers.
  */
-export async function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs> {
+export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
   const leaf = leafNode(ctx);
   if (!leaf) return {};
 
   const out: CliLeafInputs = {};
   const options = collectOptionDefs(ctx.program, ctx.commandPath);
-  let pipedJson: unknown | undefined;
-  let pipedJsonRead = false;
 
   for (const opt of options) {
-    if (opt.kind === CliOptionKind.Json) {
-      const flagValue = ctx.stringOpt(opt.name);
-      if (flagValue !== undefined) {
-        out[opt.name] = parseJsonText(flagValue, `--${opt.name}`);
-        continue;
-      }
-      if (ctx.toolArgs !== undefined && opt.name in ctx.toolArgs) {
-        out[opt.name] = ctx.toolArgs[opt.name];
-        continue;
-      }
-      if (opt.pipable && ctx.invocation === "cli") {
-        if (isInteractiveTty) {
-          out[opt.name] = undefined;
-          continue;
-        }
-        if (!pipedJsonRead) {
-          pipedJson = await readPipedJsonStdin();
-          pipedJsonRead = true;
-        }
-        out[opt.name] = pipedJson;
-        continue;
-      }
-      out[opt.name] = undefined;
-      continue;
-    }
-
     out[opt.name] = readSyncOptionValue(ctx, opt);
   }
 
@@ -176,3 +183,13 @@ export async function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInput
 
   return omitUndefinedInputs(out);
 }
+
+/** @deprecated Use {@link CliContext.inputs} or {@link loadLeafInputs} via `ctx.inputs`. */
+export function readLeafInputs(ctx: CliContext): CliLeafInputs {
+  return ctx.inputs;
+}
+
+/** @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs. */
+export function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs> {
+  return Promise.resolve(readLeafInputs(ctx));
+}