argsbarg 6.1.0 → 6.1.2

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 {
@@ -44,6 +51,7 @@ export type {
   CliDocsTopic,
   CliHandler,
   CliInvocation,
+  CliLeafKind,
   CliMcpBundleConfig,
   CliMcpResource,
   CliMcpServerConfig,
@@ -62,5 +70,6 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isJsonLeaf,
 } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/json-leaf.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+import { Cli } from "./index.ts";
+import { ParseKind, parse } from "./parse.ts";
+import { CliOptionKind, type CliProgram, CliSchemaValidationError } from "./types.ts";
+import { cliValidateProgram } from "./validate.ts";
+
+const bodySchema = {
+  type: "object",
+  properties: {
+    format: { type: "string", enum: ["pdf", "html"] },
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  required: ["format", "invoice"],
+  additionalProperties: false,
+} as const;
+
+function jsonLeafProgram() {
+  return {
+    key: "json-leaf-test",
+    version: "1.0.0",
+    description: "json leaf tests",
+    commands: [
+      {
+        key: "render",
+        description: "Render from JSON body",
+        kind: "json",
+        inputSchema: bodySchema,
+        handler: (ctx) => ctx.inputsAs<{ format: string; invoice: { id: string } }>(),
+      },
+    ],
+  } satisfies CliProgram;
+}
+
+describe("kind: json leaf", () => {
+  test("validate requires inputSchema and forbids options/positionals", () => {
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [{ key: "x", description: "x", kind: "json", handler: () => {} }],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            options: [{ name: "f", description: "f", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            positionals: [{ name: "file", description: "file", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+  });
+
+  test("parse rejects CLI flags on json leaf", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", "--format", "pdf"]);
+    expect(pr.kind).toBe(ParseKind.Error);
+    expect(pr.errorMsg).toContain("JSON commands do not accept options");
+  });
+
+  test("parse accepts JSON positional", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", '{"format":"pdf","invoice":{"id":"1"}}']);
+    expect(pr.kind).toBe(ParseKind.Ok);
+    expect(pr.args).toEqual(['{"format":"pdf","invoice":{"id":"1"}}']);
+  });
+
+  test("invoke reads body from toolArgs", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], {
+      invocation: "api",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
+  });
+
+  test("invoke reads body from JSON positional argv", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '{"format":"html","invoice":{"id":"2"}}'], {
+      invocation: "mcp",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "html", invoice: { id: "2" } });
+  });
+
+  test("invoke errors when body missing", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], { invocation: "api" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Missing JSON input");
+  });
+
+  test("invoke validates inputSchema before handler", async () => {
+    let called = false;
+    const base = jsonLeafProgram();
+    const program = {
+      ...base,
+      commands: [
+        {
+          ...base.commands[0],
+          handler: () => {
+            called = true;
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["render"], {
+      invocation: "api",
+      toolArgs: { format: "pdf", invoice: { id: 123 } },
+    });
+    expect(result.kind).toBe("error");
+    expect(called).toBe(false);
+  });
+
+  test("non-object JSON body returns error", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '"not-an-object"'], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("JSON input must be a JSON object");
+  });
+});

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 { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
+import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter, isJsonLeaf } 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);
@@ -17,9 +17,12 @@ export class LeafInputError extends Error {
   }
 }
 
-function leafNode(ctx: CliContext): CliLeaf | undefined {
-  let node: CliNode = ctx.program;
-  for (const seg of ctx.commandPath) {
+/** Internal key for piped stdin on `kind: "json"` leaves. */
+export const JSON_LEAF_BODY_KEY = "__jsonLeafBody";
+
+function resolveLeaf(program: CliProgram, commandPath: string[]): CliLeaf | undefined {
+  let node: CliNode = program;
+  for (const seg of commandPath) {
     if (!isCliRouter(node)) return undefined;
     const child = node.commands.find((c) => c.key === seg);
     if (!child) return undefined;
@@ -28,40 +31,12 @@ 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 leafNode(ctx: CliContext): CliLeaf | undefined {
+  return resolveLeaf(ctx.program, ctx.commandPath);
 }
 
-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`);
@@ -86,6 +61,23 @@ async function readPipedJsonStdin(): Promise<unknown> {
   }
 }
 
+function jsonLeafBodyHelp(): string {
+  return "Missing JSON input: pass a JSON document as an argument or pipe to stdin";
+}
+
+async function readPipedJsonStdinForJsonLeaf(): Promise<unknown> {
+  const raw = await new Response(Bun.stdin).text();
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new LeafInputError(jsonLeafBodyHelp());
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    throw new LeafInputError("stdin is not valid JSON");
+  }
+}
+
 function pipableJsonHelp(opt: CliOption): string {
   return `Missing required option --${opt.name}: pass JSON via --${opt.name} '<json>' or pipe a JSON document to stdin`;
 }
@@ -107,46 +99,117 @@ 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 coerced leaf inputs, resolving Json options from flags, piped stdin, or toolArgs,
- * and validates against `leaf.inputSchema` when set.
+ * 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 readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs> {
+export async function preloadPipableJson(
+  program: CliProgram,
+  commandPath: string[],
+  opts: Record<string, string>,
+  invocation: CliInvocation,
+  args: string[] = [],
+): Promise<Record<string, unknown>> {
+  if (invocation !== "cli" || isInteractiveTty) {
+    return {};
+  }
+
+  const leaf = resolveLeaf(program, commandPath);
+  if (leaf && isJsonLeaf(leaf) && args.length === 0) {
+    return { [JSON_LEAF_BODY_KEY]: await readPipedJsonStdinForJsonLeaf() };
+  }
+
+  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);
+}
+
+/**
+ * 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 function loadLeafInputs(ctx: CliContext): CliLeafInputs {
   const leaf = leafNode(ctx);
   if (!leaf) return {};
 
+  if (isJsonLeaf(leaf)) {
+    let body: unknown;
+    if (ctx.toolArgs !== undefined) {
+      body = ctx.toolArgs;
+    } else if (ctx.args.length > 0) {
+      const [arg0] = ctx.args;
+      if (arg0 === undefined) {
+        throw new LeafInputError(jsonLeafBodyHelp());
+      }
+      body = parseJsonText(arg0, "JSON argument");
+    } else if (JSON_LEAF_BODY_KEY in ctx.preloadedJson) {
+      body = ctx.preloadedJson[JSON_LEAF_BODY_KEY];
+    } else {
+      throw new LeafInputError(jsonLeafBodyHelp());
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      throw new LeafInputError("JSON input must be a JSON object");
+    }
+    const out = body as CliLeafInputs;
+    if (leaf.inputSchema !== undefined) {
+      validateAgainstInputSchema(out, leaf.inputSchema);
+    }
+    return omitUndefinedInputs(out);
+  }
+
   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 +239,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));
+}

package/src/mcp/tools.ts

@@ -17,6 +17,7 @@ import {
   type CliProgram,
   CliValueFormat,
   isCliLeaf,
+  isJsonLeaf,
   leafOutputSchema,
 } from "../types.ts";
 
@@ -150,6 +151,10 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 
 /** Builds inputSchema for a leaf command. */
 function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Record<string, unknown> {
+  if (isJsonLeaf(leaf) && leaf.inputSchema !== undefined) {
+    return leaf.inputSchema;
+  }
+
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
@@ -286,6 +291,10 @@ export function mcpToolCallToArgv(
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {
+  if (isJsonLeaf(tool.leaf)) {
+    return [...tool.path];
+  }
+
   const argv = [...tool.path];
 
   for (const opt of collectOptionDefs(root, tool.path)) {