argsbarg 6.0.2 → 6.1.1

package/src/leaf-inputs.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, test } from "bun:test";
+import { Cli, CliContext, CliOptionKind } from "./index.ts";
+import { LeafInputError, readLeafInputs } from "./leaf-inputs.ts";
+import type { CliProgram } from "./types.ts";
+
+const invoiceSchema = {
+  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 renderProgram(): CliProgram {
+  return {
+    key: "json-pipe-test",
+    version: "1.0.0",
+    description: "Json pipable option tests",
+    commands: [
+      {
+        key: "render",
+        description: "Render with pipable invoice JSON",
+        inputSchema: invoiceSchema,
+        options: [
+          {
+            name: "format",
+            description: "Output format",
+            kind: CliOptionKind.Enum,
+            choices: ["pdf", "html"],
+            required: true,
+          },
+          {
+            name: "invoice",
+            description: "Invoice JSON (flag or stdin)",
+            kind: CliOptionKind.Json,
+            pipable: true,
+            required: true,
+          },
+        ],
+        handler: (ctx) => ctx.readLeafInputs(),
+      },
+    ],
+  } satisfies CliProgram;
+}
+
+describe("readLeafInputs / jsonOpt", () => {
+  test("reads Json option from MCP toolArgs", async () => {
+    const cli = new Cli(renderProgram());
+    const result = await cli.invoke(["render", "--format", "pdf"], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.exitCode).toBe(0);
+    expect(result.response?.body).toEqual({
+      format: "pdf",
+      invoice: { id: "INV-1" },
+    });
+  });
+
+  test("flag wins over toolArgs for Json option", async () => {
+    const cli = new Cli(renderProgram());
+    const result = await cli.invoke(["render", "--format", "pdf", "--invoice", '{"id":"from-flag"}'], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: "from-tool-args" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({
+      format: "pdf",
+      invoice: { id: "from-flag" },
+    });
+  });
+
+  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"], {
+      invocation: "mcp",
+      toolArgs: {},
+    });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Invalid JSON");
+  });
+
+  test("validates merged inputs against inputSchema", async () => {
+    const cli = new Cli(renderProgram());
+    const result = await cli.invoke(["render", "--format", "pdf"], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: 123 } },
+    });
+    expect(result.kind).toBe("error");
+    expect(result.stderr).toContain("invoice.id");
+  });
+
+  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, {});
+    expect(() => readLeafInputs(ctx)).toThrow(LeafInputError);
+  });
+
+  test("omits undefined optional properties before inputSchema validation", async () => {
+    const schemaWithOptional = {
+      type: "object",
+      properties: {
+        format: { type: "string", enum: ["pdf", "html"] },
+        template: { type: "string" },
+        invoice: {
+          type: "object",
+          properties: { id: { type: "string" } },
+          required: ["id"],
+          additionalProperties: false,
+        },
+      },
+      required: ["format", "invoice"],
+      additionalProperties: false,
+    };
+    const program = {
+      key: "json-pipe-test",
+      version: "1.0.0",
+      description: "optional template",
+      commands: [
+        {
+          key: "render",
+          description: "Render",
+          inputSchema: schemaWithOptional,
+          options: [
+            {
+              name: "format",
+              description: "Output format",
+              kind: CliOptionKind.Enum,
+              choices: ["pdf", "html"],
+              required: true,
+            },
+            {
+              name: "template",
+              description: "Template name",
+              kind: CliOptionKind.String,
+            },
+            {
+              name: "invoice",
+              description: "Invoice JSON",
+              kind: CliOptionKind.Json,
+              pipable: true,
+              required: true,
+            },
+          ],
+          handler: (ctx) => ctx.readLeafInputs(),
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["render", "--format", "pdf"], {
+      invocation: "mcp",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
+  });
+});

package/src/leaf-inputs.ts

@@ -0,0 +1,195 @@
+/*
+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 { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
+import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import { isInteractiveTty } from "./utils.ts";
+
+/** Thrown when leaf input resolution or validation fails. */
+export class LeafInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LeafInputError";
+  }
+}
+
+function leafNode(ctx: CliContext): CliLeaf | undefined {
+  let node: CliNode = ctx.program;
+  for (const seg of ctx.commandPath) {
+    if (!isCliRouter(node)) return undefined;
+    const child = node.commands.find((c) => c.key === seg);
+    if (!child) return undefined;
+    node = child;
+  }
+  return isCliLeaf(node) ? node : undefined;
+}
+
+/** 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`);
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    throw new LeafInputError(`${label}: invalid JSON`);
+  }
+}
+
+async function readPipedJsonStdin(): Promise<unknown> {
+  const raw = await new Response(Bun.stdin).text();
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new LeafInputError("stdin is empty; pass JSON via the option flag or pipe a JSON document to stdin");
+  }
+  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`;
+}
+
+function omitUndefinedInputs(out: CliLeafInputs): Record<string, unknown> {
+  const stripped: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(out)) {
+    if (value !== undefined) {
+      stripped[key] = value;
+    }
+  }
+  return stripped;
+}
+
+function validateAgainstInputSchema(out: CliLeafInputs, inputSchema: Record<string, unknown>): void {
+  const result = validateConfigDocument(omitUndefinedInputs(out), inputSchema);
+  if (!result.valid) {
+    throw new LeafInputError(result.errors.join("; "));
+  }
+}
+
+/** 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);
+}
+
+/**
+ * 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 {};
+
+  const out: CliLeafInputs = {};
+  const options = collectOptionDefs(ctx.program, ctx.commandPath);
+
+  for (const opt of options) {
+    out[opt.name] = readSyncOptionValue(ctx, opt);
+  }
+
+  for (const p of leaf.positionals ?? []) {
+    const val = ctx.positional(p.name);
+    if (val === undefined) {
+      out[p.name] = undefined;
+    } else if (Array.isArray(val)) {
+      out[p.name] = val;
+    } else {
+      out[p.name] = val;
+    }
+  }
+
+  for (const opt of options) {
+    if (opt.required && out[opt.name] === undefined) {
+      if (opt.kind === CliOptionKind.Json && opt.pipable && ctx.invocation === "cli" && isInteractiveTty) {
+        throw new LeafInputError(pipableJsonHelp(opt));
+      }
+      throw new LeafInputError(`Missing required option: --${opt.name}`);
+    }
+  }
+
+  if (leaf.inputSchema !== undefined) {
+    validateAgainstInputSchema(out, leaf.inputSchema);
+  }
+
+  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

@@ -116,6 +116,8 @@ function optionProperty(opt: CliOption): Record<string, unknown> {
       return { type: "number", ...base };
     case CliOptionKind.Enum:
       return { type: "string", enum: opt.choices, ...base };
+    case CliOptionKind.Json:
+      return { type: "object", ...base };
   }
 }
 
@@ -287,6 +289,9 @@ export function mcpToolCallToArgv(
   const argv = [...tool.path];
 
   for (const opt of collectOptionDefs(root, tool.path)) {
+    if (opt.kind === CliOptionKind.Json) {
+      continue;
+    }
     const val = args[opt.name];
     if (val === undefined) {
       continue;

package/src/parse.ts

@@ -583,6 +583,9 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
 
   for (const d of defs) {
     if (d.required && !(d.name in opts)) {
+      if (d.kind === CliOptionKind.Json) {
+        continue;
+      }
       return errorResult(`Missing required option: --${d.name}`, pr.path);
     }
   }
@@ -592,6 +595,14 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
     if (!d) {
       return errorResult(`Unknown option key: ${k}`, pr.path);
     }
+    if (d.kind === CliOptionKind.Json) {
+      try {
+        JSON.parse(v);
+      } catch {
+        return errorResult(`Invalid JSON for option --${k}`, pr.path);
+      }
+      continue;
+    }
     if (d.kind === CliOptionKind.Number) {
       if (!fullStringIsDouble(v)) {
         return errorResult(`Invalid number for option --${k}: ${v}`, pr.path);

package/src/types.ts

@@ -12,7 +12,7 @@ import type { CliContext } from "./context.ts";
 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 enum CliOptionKind {
   /** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -23,6 +23,8 @@ export enum CliOptionKind {
   Number = "number",
   /** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
   Enum = "enum",
+  /** JSON object or array (parsed from `--name '<json>'`, piped stdin when `pipable`, or MCP/API tool body). */
+  Json = "json",
 }
 
 /**
@@ -89,6 +91,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;
 }
 
 /**

package/src/validate.ts

@@ -247,6 +247,31 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (resolved !== undefined && (typeof resolved !== "object" || resolved === null || Array.isArray(resolved))) {
       throw new CliSchemaValidationError("outputSchema must be a JSON Schema object (not null or an array)");
     }
+    const inputSchema = node.inputSchema;
+    if (
+      inputSchema !== undefined &&
+      (typeof inputSchema !== "object" || inputSchema === null || Array.isArray(inputSchema))
+    ) {
+      throw new CliSchemaValidationError("inputSchema must be a JSON Schema object (not null or an array)");
+    }
+    if (inputSchema !== undefined) {
+      const properties = inputSchema.properties;
+      if (
+        properties !== undefined &&
+        (typeof properties !== "object" || properties === null || Array.isArray(properties))
+      ) {
+        throw new CliSchemaValidationError(`inputSchema.properties must be an object on ${node.key}`);
+      }
+      if (properties) {
+        for (const opt of node.options ?? []) {
+          if (opt.kind === CliOptionKind.Json && !(opt.name in properties)) {
+            throw new CliSchemaValidationError(
+              `Json option '${opt.name}' is missing from inputSchema.properties on ${node.key}`,
+            );
+          }
+        }
+      }
+    }
   } else {
     const rogue = node as unknown as CliLeaf;
     if (rogue.mcpTool !== undefined) {
@@ -301,7 +326,22 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
 
 function validateOptions(scopeKey: string, options: import("./types.ts").CliOption[]): void {
   const seenShorts = new Set<string>();
+  let pipableCount = 0;
   for (const opt of options) {
+    if (opt.pipable) {
+      pipableCount++;
+      if (opt.kind !== CliOptionKind.Json) {
+        throw new CliSchemaValidationError(`pipable is only valid on Json kind: ${scopeKey}/${opt.name}`);
+      }
+    }
+    if (opt.kind === CliOptionKind.Json) {
+      if (opt.format !== undefined || opt.pattern !== undefined || opt.default !== undefined) {
+        throw new CliSchemaValidationError(
+          `Json option cannot use format, pattern, or default: ${scopeKey}/${opt.name}`,
+        );
+      }
+    }
+
     if (opt.required && opt.kind === CliOptionKind.Presence) {
       throw new CliSchemaValidationError(`Presence option cannot be required: ${scopeKey}/${opt.name}`);
     }
@@ -340,6 +380,9 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
       validateOptionValueMetadata(scopeKey, opt);
     }
   }
+  if (pipableCount > 1) {
+    throw new CliSchemaValidationError(`At most one pipable Json option per command: ${scopeKey}`);
+  }
 }
 
 function validateOptionValueMetadata(scopeKey: string, opt: import("./types.ts").CliOption): void {

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

@@ -1,14 +0,0 @@
-/** 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;
-}
-
-/** Schemagen root for leaf outputSchema. */
-export type outputType = StatusJsonOutput;