argsbarg 7.0.9 → 7.0.11

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/help.test.ts

@@ -12,6 +12,7 @@ import {
   cliPositionalLabel,
   cliResolveNotes,
   schemaToYamlLines,
+  visibleWidth,
 } from "./help.ts";
 import { testProgram } from "./test/fixtures.ts";
 
@@ -214,6 +215,41 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("Output Schema");
   });
 
+  /** Tests that TTY help table boxes constrain line lengths to terminal width without wrapping border characters. */
+  test("TTY help table boxes fit terminal width without overflow", () => {
+    const origColumns = process.stdout.columns;
+    try {
+      process.stdout.columns = 120;
+      const root = testProgram({
+        key: "doc",
+        version: "1.0.0",
+        description: "Test application.",
+        commands: [
+          {
+            key: "query",
+            description:
+              "Query the body tape. Prints apply-shaped YAML `{ documentId, tabs: [{ tabId, ops: [], nodes }] }` (or JSON with --json). Fill ops and pipe to apply.",
+            handler: () => {},
+          },
+          {
+            key: "markdown-insert",
+            description:
+              "Insert markdown into a Google Doc tab as native DOM elements (headings, lists, code, tables).",
+            handler: () => {},
+          },
+        ],
+      });
+      const help = cliHelpRender(cliPresentationRoot(root), [], false, { isTTY: true });
+      const boxLines = help.split("\n").filter((l) => l.includes("╭") || l.includes("│") || l.includes("╰"));
+      expect(boxLines.length).toBeGreaterThan(0);
+      for (const line of boxLines) {
+        expect(visibleWidth(line)).toBe(120);
+      }
+    } finally {
+      process.stdout.columns = origColumns;
+    }
+  });
+
   /** Tests that non-TTY help automatically includes output schema in YAML by default. */
   test("non-TTY help automatically includes output schema in YAML by default", () => {
     const root = testProgram({

package/src/help.ts

@@ -82,7 +82,7 @@ function isOutputTTY(useStderr: boolean): boolean {
 // ── Width Helpers ─────────────────────────────────────────────────────────────
 
 /** Counts display columns, skipping ANSI SGR sequences. */
-function visibleWidth(s: string): number {
+export function visibleWidth(s: string): number {
   let w = 0;
   let i = 0;
   while (i < s.length) {
@@ -230,19 +230,26 @@ interface HelpRow {
 }
 
 /** Renders a free-text or notes box with a Unicode border and `title` header. */
-function renderTextBox(title: string, lines: string[], hw: number, color: boolean): string[] {
+function renderTextBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Lines of text to display inside the box. */
+  lines: string[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (lines.length === 0) return [];
 
   const titleLead = color
     ? style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ")
     : `${kBoxH} ${title} `;
 
-  let contentWidth = visibleWidth(titleLead) + 1;
+  let contentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
   for (const line of lines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.max(hw - 2, contentWidth);
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));
@@ -265,7 +272,16 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
 }
 
 /** Renders a two-column label/description table in a box (options, subcommands, positionals). */
-function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boolean): string[] {
+function renderTableBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Table rows containing labels and descriptions to format. */
+  rows: HelpRow[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (rows.length === 0) return [];
 
   let labelWidth = 0;
@@ -273,10 +289,15 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     labelWidth = Math.max(labelWidth, visibleWidth(row.label));
   }
 
-  const titleChunk = `${kBoxH} ${title} `;
-  const minimumContentWidth = Math.max(visibleWidth(titleChunk) + 1, labelWidth + 2 + 18);
-  let contentWidth = Math.max(hw - 2, minimumContentWidth);
-  const descWidth = Math.max(1, contentWidth - labelWidth - 2);
+  let titleLead: string;
+  if (color) {
+    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
+  } else {
+    titleLead = `${kBoxH} ${title} `;
+  }
+
+  const targetContentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
+  const descWidth = Math.max(1, targetContentWidth - labelWidth - 2);
 
   const bodyLines: string[] = [];
   for (const row of rows) {
@@ -289,18 +310,10 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     }
   }
 
-  let titleLead: string;
-  if (color) {
-    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
-  } else {
-    titleLead = `${kBoxH} ${title} `;
-  }
-
-  contentWidth = Math.max(contentWidth, visibleWidth(titleLead) + 1);
+  let contentWidth = targetContentWidth;
   for (const line of bodyLines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));

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,