argsbarg 7.0.8 → 7.0.10

package/src/core/wire-schema.test.ts

@@ -0,0 +1,256 @@
+/*
+Tests for canonical wire input schema generation and wire option filtering.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { type CliLeaf, CliOptionKind, CliValueFormat } from "./types.ts";
+import { buildLeafInputSchema, leafWireOptions } from "./wire-schema.ts";
+
+/** Tests for leafWireOptions. */
+describe("leafWireOptions", () => {
+  /** Tests filtering of framework-handled presence flags. */
+  test("omits json, yes, and verbose presence flags", () => {
+    const leaf: CliLeaf = {
+      key: "test",
+      description: "Test command",
+      options: [
+        { name: "message", description: "Message text", kind: CliOptionKind.String },
+        { name: "json", description: "Output JSON", kind: CliOptionKind.Presence },
+        { name: "yes", description: "Auto-confirm", kind: CliOptionKind.Presence },
+        { name: "verbose", description: "Verbose logging", kind: CliOptionKind.Presence },
+        { name: "dry-run", description: "Dry run mode", kind: CliOptionKind.Presence },
+      ],
+      handler: () => {},
+    };
+
+    const wire = leafWireOptions(leaf);
+    const names = wire.map((o) => o.name);
+    expect(names).toEqual(["message", "dry-run"]);
+  });
+
+  /** Tests that hidden options are excluded from wire schemas. */
+  test("omits hidden options", () => {
+    const leaf: CliLeaf = {
+      key: "test",
+      description: "Test command",
+      options: [
+        { name: "visible", description: "Visible option", kind: CliOptionKind.String },
+        { name: "secret", description: "Secret option", kind: CliOptionKind.String, cli: { hidden: true } },
+      ],
+      handler: () => {},
+    };
+
+    const wire = leafWireOptions(leaf);
+    expect(wire.map((o) => o.name)).toEqual(["visible"]);
+  });
+});
+
+/** Tests for buildLeafInputSchema. */
+describe("buildLeafInputSchema", () => {
+  /** Tests that explicitly set inputSchema is returned as-is. */
+  test("returns explicit inputSchema unchanged", () => {
+    const customSchema = {
+      type: "object",
+      properties: { custom: { type: "integer" } },
+      required: ["custom"],
+    };
+    const leaf: CliLeaf = {
+      key: "doc",
+      description: "Document command",
+      kind: "document",
+      inputSchema: customSchema,
+      handler: () => {},
+    };
+
+    expect(buildLeafInputSchema(leaf)).toBe(customSchema);
+  });
+
+  /** Tests synthesizing inputSchema for flag-based commands. */
+  test("synthesizes inputSchema from wire options and positionals", () => {
+    const leaf: CliLeaf = {
+      key: "create",
+      description: "Create resource",
+      options: [
+        {
+          name: "name",
+          description: "Resource name",
+          kind: CliOptionKind.String,
+          required: true,
+        },
+        {
+          name: "count",
+          description: "Item count",
+          kind: CliOptionKind.Number,
+          default: "1",
+        },
+        {
+          name: "force",
+          description: "Force creation",
+          kind: CliOptionKind.Presence,
+        },
+        {
+          name: "tier",
+          description: "Account tier",
+          kind: CliOptionKind.Enum,
+          choices: ["free", "pro", "enterprise"],
+        },
+        {
+          name: "metadata",
+          description: "Raw metadata",
+          kind: CliOptionKind.Json,
+        },
+        {
+          name: "json",
+          description: "Omitted presence flag",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      positionals: [
+        {
+          name: "target",
+          description: "Deployment target",
+          kind: CliOptionKind.String,
+          argMin: 1,
+          argMax: 1,
+        },
+      ],
+      handler: () => {},
+    };
+
+    const schema = buildLeafInputSchema(leaf);
+    expect(schema).toEqual({
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Resource name",
+        },
+        count: {
+          type: "number",
+          description: "Item count",
+          default: "1",
+        },
+        force: {
+          type: "boolean",
+          description: "Force creation",
+        },
+        tier: {
+          type: "string",
+          enum: ["free", "pro", "enterprise"],
+          description: "Account tier",
+        },
+        metadata: {
+          type: "object",
+          description: "Raw metadata",
+        },
+        target: {
+          type: "string",
+          description: "Deployment target",
+        },
+      },
+      additionalProperties: false,
+      required: ["name", "target"],
+    });
+  });
+
+  /** Tests string format constraints in synthesized inputSchema. */
+  test("synthesizes formatted string options and varargs positionals", () => {
+    const leaf: CliLeaf = {
+      key: "query",
+      description: "Query resources",
+      options: [
+        {
+          name: "tags",
+          description: "Comma-separated tag list",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.CommaList,
+        },
+        {
+          name: "timeout",
+          description: "Timeout duration",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Duration,
+        },
+        {
+          name: "since",
+          description: "Start date",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Date,
+        },
+        {
+          name: "timestamp",
+          description: "ISO timestamp",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.DateTime,
+        },
+        {
+          name: "code",
+          description: "Custom code format",
+          kind: CliOptionKind.String,
+          pattern: "^[A-Z]{3}$",
+        },
+      ],
+      positionals: [
+        {
+          name: "files",
+          description: "Files to process",
+          kind: CliOptionKind.String,
+          argMin: 0,
+          argMax: 0,
+        },
+      ],
+      handler: () => {},
+    };
+
+    const schema = buildLeafInputSchema(leaf) as {
+      type: string;
+      properties: Record<string, unknown>;
+      required?: string[];
+    };
+    expect(schema.type).toBe("object");
+    expect(schema.required).toBeUndefined();
+
+    // CommaList
+    expect(schema.properties.tags).toEqual({
+      oneOf: [
+        { type: "string", description: "Comma-separated tag list" },
+        { type: "array", items: { type: "string" }, description: "Comma-separated tag list" },
+      ],
+    });
+
+    // Duration
+    expect(schema.properties.timeout).toEqual({
+      type: "string",
+      description: "Timeout duration",
+      pattern: "^\\d+[hdms]?$",
+    });
+
+    // Date
+    expect(schema.properties.since).toEqual({
+      type: "string",
+      description: "Start date",
+      format: "date",
+    });
+
+    // DateTime
+    expect(schema.properties.timestamp).toEqual({
+      type: "string",
+      description: "ISO timestamp",
+      format: "date-time",
+    });
+
+    // Regex pattern
+    expect(schema.properties.code).toEqual({
+      type: "string",
+      description: "Custom code format",
+      pattern: "^[A-Z]{3}$",
+    });
+
+    // Varargs positional
+    expect(schema.properties.files).toEqual({
+      type: "array",
+      items: { type: "string" },
+      description: "Files to process",
+    });
+  });
+});

package/src/core/wire-schema.ts

@@ -0,0 +1,131 @@
+/*
+Canonical wire input schema generation for MCP tools, OpenAPI parameters, and CLI schema export.
+Synthesizes a JSON Schema object from leaf-local options and positionals when inputSchema is not explicitly set.
+*/
+
+import { visibleOptions } from "../runtime/exposure.ts";
+import { type CliLeaf, type CliOption, CliOptionKind, type CliPositional, CliValueFormat } from "./types.ts";
+
+/** Regular expression pattern for duration option format (e.g. 5m, 1h, 30s). */
+const DURATION_PATTERN = "^\\d+[hdms]?$";
+
+/** Presence flags omitted from wire schemas because they are handled by the framework runtime. */
+const MCP_WIRE_OMIT_PRESENCE = new Set(["json", "yes", "verbose"]);
+
+/** JSON Schema property for one leaf option in wire schemas. */
+function optionProperty(
+  /** Option definition to format as a schema property. */
+  opt: CliOption,
+): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    description: opt.description,
+  };
+  if (opt.default !== undefined) {
+    base.default = opt.default;
+  }
+  switch (opt.kind) {
+    case CliOptionKind.Presence:
+      return { type: "boolean", ...base };
+    case CliOptionKind.String: {
+      if (opt.format === CliValueFormat.CommaList) {
+        return {
+          oneOf: [
+            { type: "string", ...base },
+            { type: "array", items: { type: "string" }, ...base },
+          ],
+        };
+      }
+      const stringBase = { type: "string", ...base };
+      if (opt.format === CliValueFormat.Duration) {
+        return { ...stringBase, pattern: DURATION_PATTERN };
+      }
+      if (opt.format === CliValueFormat.Date) {
+        return { ...stringBase, format: "date" };
+      }
+      if (opt.format === CliValueFormat.DateTime) {
+        return { ...stringBase, format: "date-time" };
+      }
+      if (opt.pattern !== undefined) {
+        return { ...stringBase, pattern: opt.pattern };
+      }
+      return stringBase;
+    }
+    case CliOptionKind.Number:
+      return { type: "number", ...base };
+    case CliOptionKind.Enum:
+      return { type: "string", enum: opt.choices, ...base };
+    case CliOptionKind.Json:
+      return { type: "object", ...base };
+  }
+}
+
+/** JSON Schema property for one positional argument slot in wire schemas. */
+function positionalProperty(
+  /** Positional argument definition to format as a schema property. */
+  p: CliPositional,
+): Record<string, unknown> {
+  const base = { description: p.description };
+  const { argMax = 1 } = p;
+  if (argMax === 0) {
+    return { type: "array", items: { type: "string" }, ...base };
+  }
+  return { type: "string", ...base };
+}
+
+/**
+ * Filters leaf-local options to only those exposed over wire protocols (MCP, OpenAPI, CLI schema export).
+ * Omits hidden options and framework-handled presence flags (`--json`, `--yes`, `--verbose`).
+ */
+export function leafWireOptions(
+  /** Leaf command node to extract wire options from. */
+  leaf: CliLeaf,
+): CliOption[] {
+  return visibleOptions(leaf.options).filter((o) => {
+    if (o.kind === CliOptionKind.Presence && MCP_WIRE_OMIT_PRESENCE.has(o.name)) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Builds the canonical input JSON Schema for a leaf command.
+ * Returns `leaf.inputSchema` when explicitly defined (e.g. on document leaves or schemagen leaves);
+ * otherwise synthesizes a flat object schema from leaf-local wire options and positionals.
+ */
+export function buildLeafInputSchema(
+  /** Leaf command node to build the input schema for. */
+  leaf: CliLeaf,
+): Record<string, unknown> {
+  if (leaf.inputSchema !== undefined) {
+    return leaf.inputSchema;
+  }
+
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const opt of leafWireOptions(leaf)) {
+    properties[opt.name] = optionProperty(opt);
+    if (opt.required) {
+      required.push(opt.name);
+    }
+  }
+
+  for (const p of leaf.positionals ?? []) {
+    properties[p.name] = positionalProperty(p);
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax === 1 && argMin >= 1) {
+      required.push(p.name);
+    }
+  }
+
+  const schema: Record<string, unknown> = {
+    type: "object",
+    properties,
+    additionalProperties: false,
+  };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}

package/src/docs/cli-guide.test.ts

@@ -141,3 +141,56 @@ test("generateCliGuide and cliSchemaExport include leaf outputSchema", () => {
   expect(md).toContain('"id"');
   expect(md).toContain('"type": "string"');
 });
+
+/** Tests that cliSchemaExport includes synthesized and custom inputSchema on leaf commands. */
+test("cliSchemaExport includes leaf inputSchema", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    commands: [
+      {
+        key: "greet",
+        description: "Greet user.",
+        options: [
+          { name: "name", description: "User name", kind: CliOptionKind.String, required: true },
+          { name: "json", description: "JSON flag", kind: CliOptionKind.Presence },
+        ],
+        handler: () => {},
+      },
+      {
+        key: "deploy",
+        description: "Deploy resource.",
+        kind: "document",
+        inputSchema: {
+          type: "object",
+          properties: { target: { type: "string" } },
+          required: ["target"],
+        },
+        handler: () => {},
+      },
+    ],
+  };
+
+  const schema = cliSchemaExport(fixture);
+  const greet = schema.commands?.[0];
+  const deploy = schema.commands?.[1];
+
+  expect(greet?.inputSchema).toEqual({
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "User name",
+      },
+    },
+    additionalProperties: false,
+    required: ["name"],
+  });
+
+  expect(deploy?.inputSchema).toEqual({
+    type: "object",
+    properties: { target: { type: "string" } },
+    required: ["target"],
+  });
+});

package/src/exports/cli.ts

@@ -40,8 +40,10 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isDocumentLeaf,
   isJsonLeaf,
 } from "../core/types.ts";
+export { buildLeafInputSchema, leafWireOptions } from "../core/wire-schema.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "../runtime/cli.ts";
 export { cliErrWithHelp } from "../runtime/cli-errors.ts";
 export { isInteractiveTty } from "../utils.ts";

package/src/help.test.ts

@@ -278,6 +278,46 @@ describe("cliHelpRender", () => {
     expect(help).toContain("# Generated ID.");
     expect(help).toContain("id: string");
   });
+
+  /** Tests that document leaf commands render [DOCUMENT] usage and schema sections. */
+  test("document leaf renders [DOCUMENT] usage and schemas in non-TTY mode", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "deploy",
+          kind: "document",
+          description: "Deploy from document.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              target: { type: "string", description: "Deployment target." },
+            },
+            required: ["target"],
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              url: { type: "string", description: "Deployment URL." },
+            },
+            required: ["url"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["deploy"], false, { isTTY: false });
+    expect(help).toContain("myapp deploy [DOCUMENT]");
+    expect(help).toContain("Pass a JSON or YAML document as an argument or pipe to stdin.");
+    expect(help).toContain("Input Schema:");
+    expect(help).toContain("# Deployment target.");
+    expect(help).toContain("target: string");
+    expect(help).toContain("Output Schema (JSON):");
+    expect(help).toContain("# Deployment URL.");
+    expect(help).toContain("url: string");
+  });
 });
 
 /** Tests for converting JSON Schema to human- and agent-friendly YAML lines. */

package/src/help.ts

@@ -16,7 +16,7 @@ import {
   type CliRouter,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./core/types.ts";
 import { visibleOptions, visibleSubcommands } from "./runtime/exposure.ts";
 
@@ -376,8 +376,9 @@ function usageLines(
   helpPath: string[],
   hasCommands: boolean,
   hasArgs: boolean,
-  jsonLeaf: boolean,
+  documentLeaf: boolean,
   color: boolean,
+  leafKind?: string,
 ): string[] {
   let fullPath = appName;
   for (const seg of helpPath) {
@@ -386,7 +387,8 @@ function usageLines(
   const usageOpts = color ? style.aquaBold("[OPTIONS]") : "[OPTIONS]";
   const usageCmd = color ? style.aquaBold("COMMAND") : "COMMAND";
   const usageArgs = color ? style.aquaBold("[ARGS]...") : "[ARGS]...";
-  const usageJson = color ? style.aquaBold("[JSON]") : "[JSON]";
+  const docTag = leafKind === "document" ? "[DOCUMENT]" : "[JSON]";
+  const usageDoc = color ? style.aquaBold(docTag) : docTag;
 
   const out: string[] = [];
   if (helpPath.length === 0) {
@@ -397,8 +399,8 @@ function usageLines(
     }
     return out;
   }
-  if (jsonLeaf) {
-    out.push(`${fullPath} ${usageJson}`);
+  if (documentLeaf) {
+    out.push(`${fullPath} ${usageDoc}`);
     return out;
   }
   out.push(`${fullPath} ${usageOpts}${hasArgs ? ` ${usageArgs}` : ""}`);
@@ -408,10 +410,11 @@ function usageLines(
   return out;
 }
 
-/** Table rows for `kind: "json"` leaf input (schema properties + stdin hint). */
-function rowsForJsonInput(inputSchema: Record<string, unknown> | undefined): HelpRow[] {
-  const hint = "Pass a JSON document as an argument or pipe to stdin.";
-  const rows: HelpRow[] = [{ label: "JSON", description: hint }];
+/** Table rows for `kind: "document"` / `kind: "json"` leaf input (schema properties + stdin hint). */
+function rowsForJsonInput(inputSchema: Record<string, unknown> | undefined, kind?: string): HelpRow[] {
+  const hint = "Pass a JSON or YAML document as an argument or pipe to stdin.";
+  const label = kind === "document" ? "DOCUMENT" : "JSON";
+  const rows: HelpRow[] = [{ label, description: hint }];
   const props = inputSchema?.properties;
   if (!props || typeof props !== "object" || Array.isArray(props)) {
     return rows;
@@ -763,7 +766,7 @@ export function cliHelpRender(
     if (isCliLeaf(schema as unknown as CliNode) && showSchema) {
       const leaf = schema as unknown as CliLeaf;
       if (leaf.outputSchema !== undefined) {
-        const title = isJsonLeaf(leaf) ? "Output Schema (JSON)" : "Output Schema (with --json)";
+        const title = isDocumentLeaf(leaf) ? "Output Schema (JSON)" : "Output Schema (with --json)";
         const yamlLines = schemaToYamlLines(leaf.outputSchema, 0);
         if (yamlLines.length > 0) {
           lines.push("");
@@ -800,14 +803,15 @@ export function cliHelpRender(
     lines.push(color ? style.white(node.description) : node.description);
     lines.push("");
   }
-  const nodeIsJsonLeaf = isCliLeaf(node) && isJsonLeaf(node);
+  const nodeIsDocumentLeaf = isCliLeaf(node) && isDocumentLeaf(node);
   const usage = usageLines(
     schema.key,
     helpPath,
     isCliRouter(node) && node.commands.length > 0,
     isCliLeaf(node) && (node.positionals ?? []).length > 0,
-    nodeIsJsonLeaf,
+    nodeIsDocumentLeaf,
     color,
+    isCliLeaf(node) ? node.kind : undefined,
   );
   if (isTTY) {
     lines.push(renderTextBox("Usage", usage, hw, color).join("\n"));
@@ -815,8 +819,8 @@ export function cliHelpRender(
     lines.push(renderPlainSection("Usage", usage).join("\n"));
   }
 
-  if (nodeIsJsonLeaf && isCliLeaf(node)) {
-    const inputRows = rowsForJsonInput(node.inputSchema);
+  if (nodeIsDocumentLeaf && isCliLeaf(node)) {
+    const inputRows = rowsForJsonInput(node.inputSchema, node.kind);
     const inputBox = isTTY ? renderTableBox("Input", inputRows, hw, color) : renderPlainTable("Input", inputRows, hw);
     if (inputBox.length > 0) {
       lines.push("");
@@ -860,7 +864,7 @@ export function cliHelpRender(
   }
 
   if (isCliLeaf(node) && node.outputSchema !== undefined && showSchema) {
-    const title = nodeIsJsonLeaf ? "Output Schema (JSON)" : "Output Schema (with --json)";
+    const title = nodeIsDocumentLeaf ? "Output Schema (JSON)" : "Output Schema (with --json)";
     const yamlLines = schemaToYamlLines(node.outputSchema, 0);
     if (yamlLines.length > 0) {
       lines.push("");

package/src/http/openapi.ts

@@ -3,8 +3,8 @@ Hand-built OpenAPI 3.1 document from exposed HTTP REST routes.
 */
 
 import type { CliHttpMethod, CliNode, CliProgram } from "../core/types.ts";
-import { CliOptionKind, isCliLeaf, isJsonLeaf } from "../core/types.ts";
-import { leafWireOptions } from "../mcp/tools.ts";
+import { isCliLeaf, isDocumentLeaf } from "../core/types.ts";
+import { buildLeafInputSchema, leafWireOptions } from "../core/wire-schema.ts";
 import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
 import { dereferenceJsonSchema } from "./schema-deref.ts";
 
@@ -34,42 +34,6 @@ function errorResponseEntry(program: CliProgram, description: string): Record<st
   };
 }
 
-function buildInputSchema(
-  _program: CliProgram,
-  route: ReturnType<typeof collectHttpRoutes>[number],
-): Record<string, unknown> {
-  const leaf = route.leaf;
-  if (leaf.inputSchema) {
-    return leaf.inputSchema;
-  }
-  const properties: Record<string, unknown> = {};
-  const required: string[] = [];
-  for (const p of route.paramNames) {
-    properties[p] = { type: "string" };
-    required.push(p);
-  }
-  for (const opt of leafWireOptions(leaf)) {
-    if (opt.kind === CliOptionKind.Json) {
-      continue;
-    }
-    properties[opt.name] = { type: "string", description: opt.description };
-    if (opt.required) {
-      required.push(opt.name);
-    }
-  }
-  for (const p of leaf.positionals ?? []) {
-    properties[p.name] = { type: "string", description: p.description };
-    if ((p.argMin ?? 1) >= 1) {
-      required.push(p.name);
-    }
-  }
-  return {
-    type: "object",
-    properties,
-    ...(required.length > 0 ? { required } : {}),
-  };
-}
-
 /** Builds success response entries for OpenAPI (status → response object). */
 function buildSuccessResponses(route: ReturnType<typeof collectHttpRoutes>[number]): Record<string, unknown> {
   const contentType = route.leaf.http?.successContentType ?? "application/json";
@@ -253,10 +217,10 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
       ];
     } else {
       op.requestBody = {
-        required: isJsonLeaf(route.leaf),
+        required: isDocumentLeaf(route.leaf),
         content: {
           [JSON_CONTENT_TYPE]: {
-            schema: dereferenceJsonSchema(buildInputSchema(program, route)),
+            schema: dereferenceJsonSchema(buildLeafInputSchema(route.leaf)),
           },
         },
       };

package/src/http/routes.ts

@@ -8,7 +8,7 @@ import {
   type CliNode,
   type CliProgram,
   isCliLeaf,
-  isJsonLeaf,
+  isDocumentLeaf,
   CliOptionKind as OptKind,
 } from "../core/types.ts";
 import { formatMcpOptionValue, leafHasYesOption, leafWireOptions } from "../mcp/tools.ts";
@@ -252,7 +252,7 @@ export function httpRequestToArgv(
   }
 
   const leaf = route.leaf;
-  if (isJsonLeaf(leaf)) {
+  if (isDocumentLeaf(leaf)) {
     return argv;
   }