argsbarg 7.0.7 → 7.0.9

package/src/core/parse.ts

@@ -19,7 +19,7 @@ import {
   type CliRouter,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./types.ts";
 
 // ── Parse Result ──────────────────────────────────────────────────────────────
@@ -292,9 +292,9 @@ export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   return [...(node.options ?? [])];
 }
 
-/** Fills `args` for a json leaf from `startIdx` (0 or 1 JSON string positional). */
+/** Fills `args` for a document / json leaf from `startIdx` (0 or 1 JSON or YAML string positional). */
 function finishJsonLeaf(
-  _node: CliLeaf,
+  node: CliLeaf,
   startIdx: number,
   argv: string[],
   path: string[],
@@ -313,7 +313,8 @@ function finishJsonLeaf(
       return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
     if (tok.startsWith("-")) {
-      return errorResult(`JSON commands do not accept options: ${tok}`, path, [], pathParams);
+      const kindLabel = node.kind === "document" ? "Document" : "JSON";
+      return errorResult(`${kindLabel} commands do not accept options: ${tok}`, path, [], pathParams);
     }
     args.push(tok);
     idx += 1;
@@ -552,7 +553,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   let node: CliNode | undefined;
 
   if (isCliLeaf(root)) {
-    if (isJsonLeaf(root)) {
+    if (isDocumentLeaf(root)) {
       return finishJsonLeaf(root, i, argv, path, opts, pathParams);
     }
     return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals, pathParams);
@@ -645,7 +646,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   // Walk the command tree
   while (true) {
-    if (isCliLeaf(current) && isJsonLeaf(current)) {
+    if (isCliLeaf(current) && isDocumentLeaf(current)) {
       return finishJsonLeaf(current, i, argv, path, opts, pathParams);
     }
 

package/src/core/types.ts

@@ -500,16 +500,17 @@ export interface CliNodeBase {
   options?: CliOption[];
 }
 
-/** Leaf input mode: `json` = pure JSON body (no CLI flags). */
-export type CliLeafKind = "json";
+/** Leaf input mode: `document` (or legacy `json`) = structured JSON or YAML document body (no CLI flags). */
+export type CliLeafKind = "document" | "json";
 
 /**
  * A leaf command node with a handler and optional positionals.
  */
 export type CliLeaf = CliNodeBase & {
   /**
-   * When `"json"`, the leaf accepts a single JSON document (CLI positional or piped stdin;
-   * MCP/HTTP tool args = body). Requires `inputSchema`; forbids `options` and `positionals`.
+   * When `"document"` (or legacy `"json"`), the leaf accepts a single JSON or YAML document
+   * (CLI positional or piped stdin; MCP/HTTP tool args = body). Requires `inputSchema`;
+   * forbids `options` and `positionals`.
    */
   kind?: CliLeafKind;
   /** Handler function for leaf commands. */
@@ -691,9 +692,20 @@ export function isCliLeaf(node: CliNode): node is CliLeaf {
   return "handler" in node && typeof node.handler === "function";
 }
 
-/** True when the leaf accepts a pure JSON body (no CLI flags). */
-export function isJsonLeaf(leaf: CliLeaf): boolean {
-  return leaf.kind === "json";
+/** True when the leaf accepts a structured JSON or YAML document body (no CLI flags). */
+export function isDocumentLeaf(
+  /** Leaf command node to inspect. */
+  leaf: CliLeaf,
+): boolean {
+  return leaf.kind === "document" || leaf.kind === "json";
+}
+
+/** True when the leaf accepts a structured document body (backward-compatible alias for `isDocumentLeaf`). */
+export function isJsonLeaf(
+  /** Leaf command node to inspect. */
+  leaf: CliLeaf,
+): boolean {
+  return isDocumentLeaf(leaf);
 }
 
 /** True when the node is a router (has subcommands). */

package/src/core/validate.ts

@@ -17,7 +17,7 @@ import {
   CliValueFormat,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./types.ts";
 
 /** Validates `docs` configuration on the program root. */
@@ -264,15 +264,16 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (isRoot && node.mcpTool !== undefined) {
       throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
     }
-    if (isJsonLeaf(node)) {
+    if (isDocumentLeaf(node)) {
+      const kindStr = `kind: "${node.kind ?? "document"}"`;
       if (node.inputSchema === undefined) {
-        throw new CliSchemaValidationError(`kind: "json" requires inputSchema on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} requires inputSchema on ${node.key}`);
       }
       if ((node.options ?? []).length > 0) {
-        throw new CliSchemaValidationError(`kind: "json" forbids options on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} forbids options on ${node.key}`);
       }
       if ((node.positionals ?? []).length > 0) {
-        throw new CliSchemaValidationError(`kind: "json" forbids positionals on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} forbids positionals on ${node.key}`);
       }
     }
     const outputSchema = node.outputSchema;

package/src/exports/cli.ts

@@ -40,6 +40,7 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isDocumentLeaf,
   isJsonLeaf,
 } from "../core/types.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "../runtime/cli.ts";

package/src/help.test.ts

@@ -5,7 +5,14 @@ Help rendering and label formatting tests.
 import { describe, expect, test } from "bun:test";
 import { cliPresentationRoot } from "./builtins/presentation.ts";
 import { type CliOption, CliOptionKind, type CliPositional } from "./core/types.ts";
-import { CLI_NOTES_PROGRAM, cliHelpRender, cliOptionLabel, cliPositionalLabel, cliResolveNotes } from "./help.ts";
+import {
+  CLI_NOTES_PROGRAM,
+  cliHelpRender,
+  cliOptionLabel,
+  cliPositionalLabel,
+  cliResolveNotes,
+  schemaToYamlLines,
+} from "./help.ts";
 import { testProgram } from "./test/fixtures.ts";
 
 describe("cliOptionLabel", () => {
@@ -148,4 +155,280 @@ describe("cliHelpRender", () => {
     expect(help).toContain("See `myapp docs readme` for the user guide.");
     expect(help).not.toContain("docs skill");
   });
+
+  /** Tests that non-TTY help strips box characters and renders plain text. */
+  test("non-TTY help strips boxes and renders clean plain text", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          options: [
+            {
+              name: "verbose",
+              shortName: "v",
+              description: "Verbose output.",
+              kind: CliOptionKind.Presence,
+            },
+          ],
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: false });
+    expect(help).not.toContain("╭─");
+    expect(help).not.toContain("╰─");
+    expect(help).not.toContain("│");
+    expect(help).toContain("Usage:\n  myapp status [OPTIONS]");
+    expect(help).toContain("Options:\n  --help, -h     Show help for this command.\n  --verbose, -v  Verbose output.");
+  });
+
+  /** Tests that TTY help renders rounded UTF-8 boxes. */
+  test("TTY help renders rounded UTF-8 boxes and omits output schema by default", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          outputSchema: {
+            type: "object",
+            properties: {
+              version: { type: "string", description: "App version." },
+            },
+            required: ["version"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: true });
+    expect(help).toContain("╭");
+    expect(help).toContain("╰");
+    expect(help).toContain("│");
+    expect(help).not.toContain("Output Schema");
+  });
+
+  /** 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({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          outputSchema: {
+            type: "object",
+            properties: {
+              version: { type: "string", description: "App version." },
+            },
+            required: ["version"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: false });
+    expect(help).toContain("Output Schema (with --json):");
+    expect(help).toContain("# App version.");
+    expect(help).toContain("version: string");
+  });
+
+  /** Tests that json leaf commands render Output Schema (JSON) and Input Schema. */
+  test("json leaf renders Output Schema (JSON) and Input Schema in non-TTY mode", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "create",
+          kind: "json",
+          description: "Create resource.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Resource name." },
+            },
+            required: ["name"],
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Generated ID." },
+            },
+            required: ["id"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["create"], false, { isTTY: false });
+    expect(help).toContain("Input Schema:");
+    expect(help).toContain("# Resource name.");
+    expect(help).toContain("name: string");
+    expect(help).toContain("Output Schema (JSON):");
+    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. */
+describe("schemaToYamlLines", () => {
+  /** Tests primitive properties with required and optional keys and comments. */
+  test("formats primitive properties with descriptions and optionality", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        documentId: {
+          type: "string",
+          description: "Unique document identifier.",
+        },
+        index: {
+          type: "integer",
+        },
+      },
+      required: ["documentId"],
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(["# Unique document identifier.", "documentId: string", "index?: integer"]);
+  });
+
+  /** Tests enums, string formats, and union types. */
+  test("formats enums, string formats, and union types", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        format: {
+          type: "string",
+          enum: ["pdf", "html"],
+        },
+        createdAt: {
+          type: "string",
+          format: "date-time",
+        },
+        status: {
+          anyOf: [{ type: "string" }, { type: "number" }],
+        },
+      },
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(['format?: "pdf" | "html"', "createdAt?: string (date-time)", "status?: string | number"]);
+  });
+
+  /** Tests nested objects and arrays of objects with definitions. */
+  test("formats nested objects and arrays of objects with definition resolution", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        tab: {
+          type: "object",
+          description: "Active tab metadata.",
+          properties: {
+            tabId: { type: "string" },
+            title: { type: "string" },
+          },
+          required: ["tabId", "title"],
+        },
+        tabs: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/TabItem",
+          },
+        },
+      },
+      definitions: {
+        TabItem: {
+          type: "object",
+          properties: {
+            tabId: { type: "string" },
+            title: { type: "string" },
+            index: { type: "integer" },
+          },
+          required: ["tabId", "title", "index"],
+        },
+      },
+      required: ["tab"],
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual([
+      "# Active tab metadata.",
+      "tab:",
+      "  tabId: string",
+      "  title: string",
+      "tabs?:",
+      "  - tabId: string",
+      "    title: string",
+      "    index: integer",
+    ]);
+  });
+
+  /** Tests recursive references handle cycles gracefully without infinite loop. */
+  test("handles recursive definition references without infinite loop", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        parent: { $ref: "#/definitions/TreeNode" },
+      },
+      definitions: {
+        TreeNode: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            parent: { $ref: "#/definitions/TreeNode" },
+          },
+        },
+      },
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(["name?: string", "parent?:", "  name?: string", "  parent?: TreeNode"]);
+  });
 });