argsbarg 7.0.9 → 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

@@ -43,6 +43,7 @@ export {
   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/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, isDocumentLeaf } 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";
@@ -256,7 +220,7 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
         required: isDocumentLeaf(route.leaf),
         content: {
           [JSON_CONTENT_TYPE]: {
-            schema: dereferenceJsonSchema(buildInputSchema(program, route)),
+            schema: dereferenceJsonSchema(buildLeafInputSchema(route.leaf)),
           },
         },
       };

package/src/index.ts

@@ -72,6 +72,7 @@ export {
   isDocumentLeaf,
   isJsonLeaf,
 } from "./core/types.ts";
+export { buildLeafInputSchema, leafWireOptions } from "./core/wire-schema.ts";
 export type { HeadlessContext } from "./headless/routing.ts";
 export {
   formatDryRunMessage,

package/src/mcp/tools.ts

@@ -9,29 +9,25 @@ import {
   type CliNode,
   type CliOption,
   CliOptionKind,
-  type CliPositional,
   type CliProgram,
   CliValueFormat,
   isCliLeaf,
   isDocumentLeaf,
   leafOutputSchema,
 } from "../core/types.ts";
+import { buildLeafInputSchema, leafWireOptions } from "../core/wire-schema.ts";
 import { docsMcpResources } from "../docs/mcp-resources.ts";
 import { cliResolveNotes } from "../help.ts";
 import { isMcpHidden, visibleOptions } from "../runtime/exposure.ts";
 
-const DURATION_PATTERN = "^\\d+[hdms]?$";
-
-/** Presence flags omitted from MCP wire schemas (handled by the framework on invoke). */
-const MCP_WIRE_OMIT_PRESENCE = new Set(["json", "yes", "verbose"]);
+export { buildLeafInputSchema, leafWireOptions } from "../core/wire-schema.ts";
+export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
 
 /** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
 export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
 }
 
-export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
-
 /** Sanitizes a command key segment for MCP tool names and server identity. */
 export function sanitizeToolSegment(key: string): string {
   return key.replace(/[^a-zA-Z0-9]/g, "_");
@@ -72,61 +68,21 @@ export function mcpToolName(root: CliProgram, path: string[]): string {
   return path.map(sanitizeToolSegment).join("_");
 }
 
-/** Leaf options exposed on MCP/HTTP wire schemas (omits framework-handled presence flags). */
-export function leafWireOptions(leaf: CliLeaf): CliOption[] {
-  return visibleOptions(leaf.options).filter(
-    (opt) => !(opt.kind === CliOptionKind.Presence && MCP_WIRE_OMIT_PRESENCE.has(opt.name)),
-  );
-}
-
 /** True when the leaf declares a `yes` presence option (auto-injected on MCP invoke). */
-export function leafHasYesOption(leaf: CliLeaf): boolean {
+export function leafHasYesOption(
+  /** Leaf command node to inspect. */
+  leaf: CliLeaf,
+): boolean {
   return visibleOptions(leaf.options).some((opt) => opt.name === "yes" && opt.kind === CliOptionKind.Presence);
 }
 
-/** JSON Schema property for one option. */
-function optionProperty(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 };
-  }
-}
-
-export function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
+/** Formats an incoming MCP option value to an argv string. */
+export function formatMcpOptionValue(
+  /** Option definition to format the value for. */
+  opt: CliOption,
+  /** Incoming raw value from the MCP tool call. */
+  val: unknown,
+): string | { error: string } {
   if (opt.format === CliValueFormat.CommaList) {
     if (Array.isArray(val)) {
       const items = val.map(String).filter(Boolean);
@@ -143,51 +99,6 @@ export function formatMcpOptionValue(opt: CliOption, val: unknown): string | { e
   return String(val);
 }
 
-/** JSON Schema property for one positional slot. */
-function positionalProperty(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 };
-}
-
-/** Builds inputSchema for a leaf command. */
-function buildInputSchema(leaf: CliLeaf): Record<string, unknown> {
-  if (isDocumentLeaf(leaf) && 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;
-}
-
 /** Resolves MCP tool description with optional override and leaf notes. */
 function resolveToolDescription(root: CliProgram, path: string[], leaf: CliLeaf): string {
   let desc: string;
@@ -251,7 +162,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
-        inputSchema: cmd.inputSchema ?? buildInputSchema(cmd),
+        inputSchema: buildLeafInputSchema(cmd),
         ...(outputSchema === undefined ? {} : { outputSchema }),
       });
       return;