argsbarg 6.1.1 → 6.1.3

package/src/{leaf-inputs.test.ts → core/leaf-inputs.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { Cli, CliContext, CliOptionKind } from "./index.ts";
-import { LeafInputError, readLeafInputs } from "./leaf-inputs.ts";
+import { Cli, CliContext, CliOptionKind } from "~/index";
+import { LeafInputError, loadLeafInputs } from "./leaf-inputs.ts";
 import type { CliProgram } from "./types.ts";
 
 const invoiceSchema = {
@@ -46,13 +46,13 @@ function renderProgram(): CliProgram {
             required: true,
           },
         ],
-        handler: (ctx) => ctx.readLeafInputs(),
+        handler: (ctx) => ctx.inputs,
       },
     ],
   } satisfies CliProgram;
 }
 
-describe("readLeafInputs / jsonOpt", () => {
+describe("loadLeafInputs / jsonOpt", () => {
   test("reads Json option from MCP toolArgs", async () => {
     const cli = new Cli(renderProgram());
     const result = await cli.invoke(["render", "--format", "pdf"], {
@@ -212,10 +212,10 @@ describe("readLeafInputs / jsonOpt", () => {
     expect(inputs[0]).toEqual(inputs[1]);
   });
 
-  test("readLeafInputs throws LeafInputError when required Json is missing", () => {
+  test("loadLeafInputs 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);
+    expect(() => loadLeafInputs(ctx)).toThrow(LeafInputError);
   });
 
   test("omits undefined optional properties before inputSchema validation", async () => {
@@ -264,7 +264,7 @@ describe("readLeafInputs / jsonOpt", () => {
               required: true,
             },
           ],
-          handler: (ctx) => ctx.readLeafInputs(),
+          handler: (ctx) => ctx.inputs,
         },
       ],
     } satisfies CliProgram;

package/src/{leaf-inputs.ts → core/leaf-inputs.ts}

@@ -2,12 +2,12 @@
 Leaf input reads: Json options (flag, preloaded stdin, or toolArgs), optional inputSchema validation.
 */
 
-import { validateConfigDocument } from "./config/validate.ts";
+import { validateConfigDocument } from "~/config/validate.ts";
+import { isInteractiveTty } from "~/utils.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";
+import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter, isJsonLeaf } from "./types.ts";
 
 /** Thrown when leaf input resolution or validation fails. */
 export class LeafInputError extends Error {
@@ -17,9 +17,12 @@ export class LeafInputError extends Error {
   }
 }
 
-function leafNode(ctx: CliContext): CliLeaf | undefined {
-  let node: CliNode = ctx.program;
-  for (const seg of ctx.commandPath) {
+/** Internal key for piped stdin on `kind: "json"` leaves. */
+export const JSON_LEAF_BODY_KEY = "__jsonLeafBody";
+
+function resolveLeaf(program: CliProgram, commandPath: string[]): CliLeaf | undefined {
+  let node: CliNode = program;
+  for (const seg of commandPath) {
     if (!isCliRouter(node)) return undefined;
     const child = node.commands.find((c) => c.key === seg);
     if (!child) return undefined;
@@ -28,6 +31,10 @@ function leafNode(ctx: CliContext): CliLeaf | undefined {
   return isCliLeaf(node) ? node : undefined;
 }
 
+function leafNode(ctx: CliContext): CliLeaf | undefined {
+  return resolveLeaf(ctx.program, ctx.commandPath);
+}
+
 /** Parses a JSON string from a `--name` flag value. */
 export function parseJsonText(raw: string, label: string): unknown {
   const trimmed = raw.trim();
@@ -54,6 +61,23 @@ async function readPipedJsonStdin(): Promise<unknown> {
   }
 }
 
+function jsonLeafBodyHelp(): string {
+  return "Missing JSON input: pass a JSON document as an argument or pipe to stdin";
+}
+
+async function readPipedJsonStdinForJsonLeaf(): Promise<unknown> {
+  const raw = await new Response(Bun.stdin).text();
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new LeafInputError(jsonLeafBodyHelp());
+  }
+  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`;
 }
@@ -99,10 +123,17 @@ export async function preloadPipableJson(
   commandPath: string[],
   opts: Record<string, string>,
   invocation: CliInvocation,
+  args: string[] = [],
 ): Promise<Record<string, unknown>> {
   if (invocation !== "cli" || isInteractiveTty) {
     return {};
   }
+
+  const leaf = resolveLeaf(program, commandPath);
+  if (leaf && isJsonLeaf(leaf) && args.length === 0) {
+    return { [JSON_LEAF_BODY_KEY]: await readPipedJsonStdinForJsonLeaf() };
+  }
+
   for (const opt of collectOptionDefs(program, commandPath)) {
     if (opt.kind === CliOptionKind.Json && opt.pipable && !(opt.name in opts)) {
       return { [opt.name]: await readPipedJsonStdin() };
@@ -150,6 +181,31 @@ export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
   const leaf = leafNode(ctx);
   if (!leaf) return {};
 
+  if (isJsonLeaf(leaf)) {
+    let body: unknown;
+    if (ctx.toolArgs !== undefined) {
+      body = ctx.toolArgs;
+    } else if (ctx.args.length > 0) {
+      const [arg0] = ctx.args;
+      if (arg0 === undefined) {
+        throw new LeafInputError(jsonLeafBodyHelp());
+      }
+      body = parseJsonText(arg0, "JSON argument");
+    } else if (JSON_LEAF_BODY_KEY in ctx.preloadedJson) {
+      body = ctx.preloadedJson[JSON_LEAF_BODY_KEY];
+    } else {
+      throw new LeafInputError(jsonLeafBodyHelp());
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      throw new LeafInputError("JSON input must be a JSON object");
+    }
+    const out = body as CliLeafInputs;
+    if (leaf.inputSchema !== undefined) {
+      validateAgainstInputSchema(out, leaf.inputSchema);
+    }
+    return omitUndefinedInputs(out);
+  }
+
   const out: CliLeafInputs = {};
   const options = collectOptionDefs(ctx.program, ctx.commandPath);
 
@@ -168,6 +224,20 @@ export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
     }
   }
 
+  for (const [name, value] of Object.entries(ctx.pathParams)) {
+    if (out[name] === undefined) {
+      out[name] = value;
+    }
+  }
+
+  if (ctx.toolArgs !== undefined) {
+    for (const [key, value] of Object.entries(ctx.toolArgs)) {
+      if (out[key] === undefined) {
+        out[key] = value;
+      }
+    }
+  }
+
   for (const opt of options) {
     if (opt.required && out[opt.name] === undefined) {
       if (opt.kind === CliOptionKind.Json && opt.pipable && ctx.invocation === "cli" && isInteractiveTty) {
@@ -183,13 +253,3 @@ export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
 
   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/{parse.test.ts → core/parse.test.ts}

@@ -7,23 +7,23 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { $ } from "bun";
-import { completionBashScript, completionZshScript } from "./builtins/index.ts";
-import { cliPresentationRoot } from "./builtins/presentation.ts";
-import { cliHelpRender } from "./help.ts";
-import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "./index.ts";
-import { applyShellEnv } from "./mcp/env.ts";
-import { allMcpResources, collectMcpTools, mcpToolCallToArgv, resolveMcpSchemaUri } from "./mcp/tools.ts";
-import { ParseKind, parse, postParseValidate } from "./parse.ts";
-import { cliSchemaJson } from "./schema.ts";
-import { generatePluginSkillBundle, generateSkillBundle } from "./skill/generate.ts";
-import { cliSkillInstall } from "./skill/install.ts";
+import { completionBashScript, completionZshScript } from "~/builtins";
+import { cliPresentationRoot } from "~/builtins/presentation.ts";
+import { cliHelpRender } from "~/help.ts";
+import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "~/index";
+import { applyShellEnv } from "~/mcp/env.ts";
+import { allMcpResources, collectMcpTools, mcpToolCallToArgv, resolveMcpSchemaUri } from "~/mcp/tools.ts";
+import { generatePluginSkillBundle, generateSkillBundle } from "~/skill/generate.ts";
+import { cliSkillInstall } from "~/skill/install.ts";
 import {
   enumMcpFixture,
   nestedDocsFallbackFixture,
   nestedMcpFixture,
   testProgram,
   varargsReadFixture,
-} from "./test-fixtures.ts";
+} from "~/test/fixtures.ts";
+import { ParseKind, parse, postParseValidate } from "./parse.ts";
+import { cliSchemaJson } from "./schema.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 /** Tests that bundled short presence flags. */
@@ -115,6 +115,85 @@ test("fallback missing or unknown root flags", () => {
   expect(pr.opts.name).toBe("bob");
 });
 
+test("param router descent captures pathParams", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "workspaces",
+        description: "Workspaces.",
+        commands: [
+          {
+            key: ":id",
+            description: "One workspace.",
+            commands: [
+              {
+                key: "get",
+                description: "Get workspace.",
+                handler: () => {},
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+  cliValidateProgram(root);
+  const pr = postParseValidate(root, parse(root, ["workspaces", "qa2", "get"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.path).toEqual(["workspaces", ":id", "get"]);
+  expect(pr.pathParams).toEqual({ id: "qa2" });
+});
+
+test("cli.enabled cascade blocks disabled router", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "workspaces",
+        description: "Disabled.",
+        cli: { enabled: false },
+        commands: [
+          {
+            key: "list",
+            description: "List.",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  });
+  cliValidateProgram(root);
+  const pr = parse(root, ["workspaces", "list"]);
+  expect(pr.kind).toBe(ParseKind.Error);
+  expect(pr.errorMsg).toContain("Unknown command");
+});
+
+test("completion match child emits param router fallback", () => {
+  const root = testProgram({
+    key: "app",
+    description: "Test",
+    commands: [
+      {
+        key: "workspaces",
+        description: "Workspaces.",
+        commands: [
+          {
+            key: ":id",
+            description: "One workspace.",
+            commands: [{ key: "get", description: "Get.", handler: () => {} }],
+          },
+        ],
+      },
+    ],
+  });
+  cliValidateProgram(root);
+  const bash = completionBashScript(cliPresentationRoot(root));
+  expect(bash).toContain("*) echo");
+});
+
 test("unknown command", () => {
   const root = testProgram({
     key: "app",
@@ -551,7 +630,6 @@ test("root --schema is no longer a flag", () => {
     version: "1.0.0",
     description: "demo",
     docs: {
-      enabled: true,
       topics: { readme: { text: "# readme\n" } },
     },
     commands: [
@@ -639,98 +717,6 @@ test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
   expect(schema.commands[0].notes).toBe("Run `myapp run` to start.");
 });
 
-/** Docs help lists schema, api, and skill subcommands. */
-test("docs help lists schema, api, and skill subcommands", () => {
-  const root = testProgram({
-    key: "app",
-    version: "1.0.0",
-    description: "demo",
-    docs: {
-      enabled: true,
-      topics: { readme: { text: "# readme\n" } },
-    },
-    commands: [
-      {
-        key: "x",
-        description: "cmd",
-        handler: () => {},
-      },
-    ],
-  });
-  const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
-  expect(help).toContain("cli-schema");
-  expect(help).toContain("Print the full CLI command tree as JSON.");
-  expect(help).toContain("api");
-  expect(help).toContain("markdown");
-  expect(help).toContain("skill");
-  expect(help).toContain("reference agent SKILL");
-});
-
-/** Root help omits legacy --schema flag. */
-test("root help omits legacy --schema flag", () => {
-  const root = testProgram({
-    key: "app",
-    version: "1.0.0",
-    description: "demo",
-    commands: [
-      {
-        key: "x",
-        description: "cmd",
-        handler: () => {},
-      },
-    ],
-  });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).not.toContain("--schema");
-});
-
-/** Root help shows agent docs hint when docs enabled. */
-test("root help shows agent docs hint when docs enabled", () => {
-  const root = testProgram({
-    key: "myapp",
-    version: "1.0.0",
-    description: "demo",
-    docs: {
-      enabled: true,
-      topics: { readme: { text: "# readme\n" } },
-    },
-    commands: [{ key: "run", description: "Run.", handler: () => {} }],
-  });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("For AI agents: `myapp docs skill`.");
-  expect(help).not.toContain("install --skill");
-});
-
-test("root help omits agent hint when docs disabled", () => {
-  const root = testProgram({
-    key: "myapp",
-    version: "1.0.0",
-    description: "demo",
-    commands: [{ key: "run", description: "Run.", handler: () => {} }],
-  });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).not.toContain("Agents:");
-  expect(help).not.toContain("docs skill");
-});
-
-/** Root help includes program notes and agent hint. */
-test("root help includes program notes and agent hint", () => {
-  const root = testProgram({
-    key: "myapp",
-    version: "1.0.0",
-    description: "demo",
-    notes: "See `{argsbarg:program} docs readme` for the user guide.",
-    docs: {
-      enabled: true,
-      topics: { readme: { text: "# readme\n" } },
-    },
-    commands: [{ key: "run", description: "Run.", handler: () => {} }],
-  });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("See `myapp docs readme` for the user guide.");
-  expect(help).toContain("myapp docs skill");
-});
-
 test("Enum option inputSchema includes enum array", () => {
   const tools = collectMcpTools(enumMcpFixture);
   const run = tools.find((t) => t.name === "run")!;
@@ -814,14 +800,14 @@ test("cliValidateProgram rejects empty mcpServer", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpServer requires enabled: true/);
 });
 
-test("cliValidateProgram rejects empty apiServer", () => {
+test("cliValidateProgram rejects empty httpServer", () => {
   const root = testProgram({
     key: "app",
     description: "",
-    apiServer: {} as { enabled: boolean },
+    httpServer: {} as { enabled: boolean },
     handler: () => {},
   });
-  expect(() => cliValidateProgram(root)).toThrow(/apiServer requires enabled: true/);
+  expect(() => cliValidateProgram(root)).toThrow(/httpServer requires enabled: true/);
 });
 
 test("resolveMcpSchemaUri uses sanitized root key", () => {
@@ -877,7 +863,7 @@ test("cliValidateProgram rejects resource URI matching auto docs topic", () => {
   const root = testProgram({
     key: "app",
     description: "",
-    docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    docs: { topics: { readme: { text: "# r\n" } } },
     mcpServer: {
       enabled: true,
       resources: [{ uri: "app://docs/readme", name: "dup", load: () => "" }],
@@ -908,7 +894,7 @@ test("allMcpResources includes docs topic resources", () => {
   const root = testProgram({
     key: "app",
     description: "",
-    docs: { enabled: true, topics: { readme: { text: "# hi\n" } } },
+    docs: { topics: { readme: { text: "# hi\n" } } },
     mcpServer: { enabled: true },
     commands: [{ key: "leaf", description: "", handler: () => {} }],
   });
@@ -971,6 +957,7 @@ test("nested fallback MissingOrUnknown routes unknown token to default", () => {
   const root = testProgram({
     key: "app",
     description: "",
+    docs: { enabled: false },
     commands: [
       {
         key: "docs",
@@ -1021,6 +1008,7 @@ test("cliValidateProgram rejects invalid nested fallbackCommand", () => {
   const root = testProgram({
     key: "app",
     description: "",
+    docs: { enabled: false },
     commands: [
       {
         key: "docs",