argsbarg 6.1.2 → 6.1.3

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",

package/src/{parse.ts → core/parse.ts}

@@ -7,6 +7,8 @@ It keeps handler dispatch and help on one parser so the CLI behavior stays consi
 across every entry path.
 */
 
+import { isCliCallable } from "~/runtime/exposure.ts";
+import { fullStringIsDouble } from "~/utils.ts";
 import { formatValidationError, validateFormatValue } from "./formats.ts";
 import {
   CliFallbackMode,
@@ -14,11 +16,11 @@ import {
   type CliNode,
   type CliOption,
   CliOptionKind,
+  type CliRouter,
   isCliLeaf,
   isCliRouter,
   isJsonLeaf,
 } from "./types.ts";
-import { fullStringIsDouble } from "./utils.ts";
 
 // ── Parse Result ──────────────────────────────────────────────────────────────
 
@@ -48,6 +50,8 @@ export interface ParseResult {
   helpExplicit: boolean;
   /** Path segments for scoped help (empty for root help). */
   helpPath: string[];
+  /** Path parameter values from `:param` router descent (e.g. `{ id: "qa2" }`). */
+  pathParams: Record<string, string>;
   /** User-facing error message when `kind === Error`. */
   errorMsg: string;
   /** Help path to render next to an error (for contextual help). */
@@ -69,6 +73,24 @@ function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
 }
 
+function isParamRouterKey(key: string): boolean {
+  return key.startsWith(":");
+}
+
+/** Static (non-`:param`) child by key. */
+function findStaticChild(cmds: CliNode[], name: string): CliNode | undefined {
+  const ch = cmds.find((c) => c.key === name);
+  if (!ch || isParamRouterKey(ch.key)) {
+    return undefined;
+  }
+  return ch;
+}
+
+/** The single `:param` router child at this level, if any. */
+function findParamChild(cmds: CliNode[]): CliNode | undefined {
+  return cmds.find((c) => isParamRouterKey(c.key));
+}
+
 /** Resolves a long-option definition by name (without leading `--`). */
 function findOptionByName(defs: CliOption[], name: string): CliOption | undefined {
   return defs.find((o) => o.name === name);
@@ -245,6 +267,7 @@ function finishJsonLeaf(
   argv: string[],
   path: string[],
   opts: Record<string, string>,
+  pathParams: Record<string, string>,
 ): ParseResult {
   let idx = startIdx;
   const args: string[] = [];
@@ -252,20 +275,20 @@ function finishJsonLeaf(
   if (idx < argv.length) {
     const tok = argv[idx];
     if (isHelpTok(tok)) {
-      return helpResult(path, true);
+      return helpResult(path, true, pathParams);
     }
     if (tok === "--") {
-      return errorResult("Unexpected extra arguments", path, []);
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
     if (tok.startsWith("-")) {
-      return errorResult(`JSON commands do not accept options: ${tok}`, path, []);
+      return errorResult(`JSON commands do not accept options: ${tok}`, path, [], pathParams);
     }
     args.push(tok);
     idx += 1;
   }
 
   if (idx < argv.length) {
-    return errorResult("Unexpected extra arguments", path, []);
+    return errorResult("Unexpected extra arguments", path, [], pathParams);
   }
 
   return {
@@ -273,6 +296,7 @@ function finishJsonLeaf(
     path,
     opts,
     args,
+    pathParams,
     helpExplicit: false,
     helpPath: [],
     errorMsg: "",
@@ -289,6 +313,7 @@ function finishLeaf(
   opts: Record<string, string>,
   optionDefs: CliOption[],
   forcePositionalsIn: boolean,
+  pathParams: Record<string, string>,
 ): ParseResult {
   let idx = startIdx;
   const args: string[] = [];
@@ -299,7 +324,7 @@ function finishLeaf(
     if (argMax === 1) {
       if (argMin >= 1) {
         if (idx >= argv.length) {
-          return errorResult(`Missing positional argument: ${p.name}`, path, []);
+          return errorResult(`Missing positional argument: ${p.name}`, path, [], pathParams);
         }
         args.push(argv[idx]);
         idx += 1;
@@ -327,14 +352,14 @@ function finishLeaf(
         }
 
         if (!forcePositionals && isHelpTok(tok)) {
-          return helpResult(path, true);
+          return helpResult(path, true, pathParams);
         }
 
         if (!forcePositionals && tok.startsWith("-")) {
           // MUST be false — lenient mode swallows unknown flags as positionals silently
           const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
           if (tailRep.report.err) {
-            return errorResult(tailRep.report.err, path, []);
+            return errorResult(tailRep.report.err, path, [], pathParams);
           }
           if (tailRep.report.sawDoubleDash) {
             forcePositionals = true;
@@ -343,7 +368,7 @@ function finishLeaf(
             idx = tailRep.nextIndex;
             continue;
           }
-          return errorResult(`Unexpected option token: ${tok}`, path, []);
+          return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
         }
 
         args.push(tok);
@@ -358,27 +383,27 @@ function finishLeaf(
       }
     }
     if (count < argMin) {
-      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`, path, []);
+      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`, path, [], pathParams);
     }
   }
 
   if (idx < argv.length) {
     if (forcePositionals) {
-      return errorResult("Unexpected extra arguments", path, []);
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
 
     if (isHelpTok(argv[idx])) {
-      return helpResult(path, true);
+      return helpResult(path, true, pathParams);
     }
 
     const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
     if (tailRep.report.err) {
-      return errorResult(tailRep.report.err, path, []);
+      return errorResult(tailRep.report.err, path, [], pathParams);
     }
     idx = tailRep.nextIndex;
 
     if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments", path, []);
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
   }
 
@@ -387,6 +412,7 @@ function finishLeaf(
     path,
     opts,
     args,
+    pathParams,
     helpExplicit: false,
     helpPath: [],
     errorMsg: "",
@@ -397,12 +423,18 @@ function finishLeaf(
 // ── Main Parser ───────────────────────────────────────────────────────────────
 
 /** Builds a user-error parse result; `path` defaults to `errorHelpPath`. */
-function errorResult(errorMsg: string, errorHelpPath: string[] = [], path: string[] = errorHelpPath): ParseResult {
+function errorResult(
+  errorMsg: string,
+  errorHelpPath: string[] = [],
+  path: string[] = errorHelpPath,
+  pathParams: Record<string, string> = {},
+): ParseResult {
   return {
     kind: ParseKind.Error,
     path,
     opts: {},
     args: [],
+    pathParams,
     helpExplicit: false,
     helpPath: [],
     errorMsg,
@@ -411,12 +443,13 @@ function errorResult(errorMsg: string, errorHelpPath: string[] = [], path: strin
 }
 
 /** Builds a help-request result for the current routing path. */
-function helpResult(p: string[], explicit: boolean): ParseResult {
+function helpResult(p: string[], explicit: boolean, pathParams: Record<string, string> = {}): ParseResult {
   return {
     kind: ParseKind.Help,
     path: [],
     opts: {},
     args: [],
+    pathParams,
     helpExplicit: explicit,
     helpPath: p,
     errorMsg: "",
@@ -424,13 +457,45 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
+type DescendResult = { ok: true; node: CliNode; cliEnabled: boolean } | { ok: false; error: ParseResult };
+
+/** Descends into a static or `:param` child, updating path and pathParams. */
+function descendChild(
+  parent: CliRouter,
+  tok: string,
+  path: string[],
+  pathParams: Record<string, string>,
+  cliEnabled: boolean,
+): DescendResult {
+  const staticChild = findStaticChild(parent.commands, tok);
+  if (staticChild) {
+    if (!isCliCallable(staticChild, cliEnabled)) {
+      return { ok: false, error: errorResult(`Unknown subcommand: ${tok}`, path, [], pathParams) };
+    }
+    path.push(tok);
+    return { ok: true, node: staticChild, cliEnabled: isCliCallable(staticChild, cliEnabled) };
+  }
+
+  const paramChild = findParamChild(parent.commands);
+  if (paramChild && isCliCallable(paramChild, cliEnabled)) {
+    const paramName = paramChild.key.slice(1);
+    path.push(paramChild.key);
+    pathParams[paramName] = tok;
+    return { ok: true, node: paramChild, cliEnabled: isCliCallable(paramChild, cliEnabled) };
+  }
+
+  return { ok: false, error: errorResult(`Unknown subcommand: ${tok}`, path, [], pathParams) };
+}
+
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
 export function parse(root: CliNode, argv: string[]): ParseResult {
   let i = 0;
   const path: string[] = [];
+  const pathParams: Record<string, string> = {};
   const opts: Record<string, string> = {};
+  let cliEnabled = true;
 
   const rootLenient =
     isCliRouter(root) &&
@@ -456,9 +521,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   if (isCliLeaf(root)) {
     if (isJsonLeaf(root)) {
-      return finishJsonLeaf(root, i, argv, path, opts);
+      return finishJsonLeaf(root, i, argv, path, opts, pathParams);
     }
-    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals);
+    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals, pathParams);
   }
 
   if (i >= argv.length) {
@@ -477,12 +542,41 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     }
   } else {
     const peek = argv[i];
-    const childPick = !forcePositionals ? findChild(root.commands, peek) : undefined;
+    const childPick = !forcePositionals ? findStaticChild(root.commands, peek) : undefined;
 
     if (childPick !== undefined) {
+      if (!isCliCallable(childPick, cliEnabled)) {
+        return errorResult(`Unknown command: ${peek}`, path, [], pathParams);
+      }
       cmdName = peek;
       i += 1;
       node = childPick;
+      cliEnabled = isCliCallable(childPick, cliEnabled);
+    } else if (!forcePositionals && isCliRouter(root)) {
+      const paramChild = findParamChild(root.commands);
+      if (paramChild && isCliCallable(paramChild, cliEnabled)) {
+        cmdName = paramChild.key;
+        pathParams[paramChild.key.slice(1)] = peek;
+        i += 1;
+        node = paramChild;
+        cliEnabled = isCliCallable(paramChild, cliEnabled);
+      } else {
+        const fallbackCommand = root.fallbackCommand;
+        const canRouteUnknown =
+          fallbackCommand !== undefined &&
+          ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
+            (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+
+        if (canRouteUnknown) {
+          cmdName = fallbackCommand;
+          node = findChild(root.commands, cmdName);
+          if (!node) {
+            return errorResult(`Unknown command: ${cmdName}`, path, [], pathParams);
+          }
+        } else {
+          return errorResult(`Unknown command: ${peek}`, path, [], pathParams);
+        }
+      }
     } else {
       const fallbackCommand = root.fallbackCommand;
       const canRouteUnknown =
@@ -520,7 +614,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   // Walk the command tree
   while (true) {
     if (isCliLeaf(current) && isJsonLeaf(current)) {
-      return finishJsonLeaf(current, i, argv, path, opts);
+      return finishJsonLeaf(current, i, argv, path, opts, pathParams);
     }
 
     if (!forcePositionals) {
@@ -535,7 +629,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     }
 
     if (i < argv.length && !forcePositionals && isHelpTok(argv[i])) {
-      return helpResult(path, true);
+      return helpResult(path, true, pathParams);
     }
 
     if (i >= argv.length) {
@@ -547,28 +641,29 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
           if (fbNode) {
             path.push(fb);
             current = fbNode;
+            cliEnabled = isCliCallable(fbNode, cliEnabled);
             continue;
           }
         }
-        return helpResult(path, false);
+        return helpResult(path, false, pathParams);
       }
       if (!isCliLeaf(current)) {
-        return helpResult(path, false);
+        return helpResult(path, false, pathParams);
       }
-      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
     }
 
     const tok = argv[i];
     if (!forcePositionals && tok.startsWith("-")) {
-      return errorResult(`Unexpected option token: ${tok}`, path);
+      return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
     }
 
     if (!forcePositionals && isCliRouter(current)) {
-      const childOpt = findChild(current.commands, tok);
-      if (childOpt !== undefined) {
+      const descended = descendChild(current, tok, path, pathParams, cliEnabled);
+      if (descended.ok) {
         i += 1;
-        path.push(tok);
-        current = childOpt;
+        current = descended.node;
+        cliEnabled = descended.cliEnabled;
         continue;
       }
     }
@@ -584,6 +679,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         if (fbNode) {
           path.push(fb);
           current = fbNode;
+          cliEnabled = isCliCallable(fbNode, cliEnabled);
           continue;
         }
       }
@@ -591,13 +687,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       return errorResult(
         forcePositionals ? `Expected subcommand but got positional: ${tok}` : `Unknown subcommand: ${tok}`,
         path,
+        [],
+        pathParams,
       );
     }
 
     if (!isCliLeaf(current)) {
-      return helpResult(path, false);
+      return helpResult(path, false, pathParams);
     }
-    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
   }
 }