argsbarg 1.5.0 → 2.0.1

package/src/index.test.ts

@@ -7,9 +7,12 @@ It keeps the CLI contract stable by catching routing, option handling, and gener
 shell output regressions.
 */
 
+import { cliPresentationRoot } from "./builtins/presentation.ts";
 import { completionBashScript, completionZshScript } from "./completion.ts";
 import { cliHelpRender } from "./help.ts";
-import { CliCommand, CliFallbackMode, CliOptionKind, cliInvoke } from "./index.ts";
+import { CliProgram, CliFallbackMode, CliOptionKind, cliInvoke } from "./index.ts";
+import type { CliLeaf } from "./types.ts";
+import { isCliRouter } from "./types.ts";
 import {
   allMcpResources,
   collectMcpTools,
@@ -23,7 +26,7 @@ import { generateSkillBundle } from "./skill/generate.ts";
 import { cliSkillInstall } from "./skill/install.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
-import { cliValidateRoot } from "./validate.ts";
+import { cliValidateProgram } from "./validate.ts";
 import { expect, test } from "bun:test";
 import { $ } from "bun";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -31,7 +34,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 test("bundled short presence flags", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -56,7 +59,7 @@ test("bundled short presence flags", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "-ab"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.opts["a"]).toBe("1");
@@ -64,7 +67,7 @@ test("bundled short presence flags", () => {
 });
 
 test("long option equals", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -82,14 +85,14 @@ test("long option equals", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "--name=pat"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.opts["name"]).toBe("pat");
 });
 
 test("fallback missing or unknown root flags", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -109,7 +112,7 @@ test("fallback missing or unknown root flags", () => {
     fallbackCommand: "hello",
     fallbackMode: CliFallbackMode.MissingOrUnknown,
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["--name", "bob"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.path).toEqual(["hello"]);
@@ -117,31 +120,31 @@ test("fallback missing or unknown root flags", () => {
 });
 
 test("unknown command", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [{ key: "hello", description: "", handler: () => {} }],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, ["nope"]);
   expect(pr.kind).toBe(ParseKind.Error);
   expect(pr.errorMsg).toContain("Unknown command");
 });
 
 test("implicit help empty", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [{ key: "x", description: "", handler: () => {} }],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, []);
   expect(pr.kind).toBe(ParseKind.Help);
   expect(pr.helpExplicit).toBe(false);
 });
 
 test("invalid number post validate", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -159,7 +162,7 @@ test("invalid number post validate", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   let pr = parse(root, ["x", "--n", "notnum"]);
   pr = postParseValidate(root, pr);
   expect(pr.kind).toBe(ParseKind.Error);
@@ -167,7 +170,7 @@ test("invalid number post validate", () => {
 });
 
 test("supports scientific notation in numbers", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -185,7 +188,7 @@ test("supports scientific notation in numbers", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   let pr = parse(root, ["x", "--n", "1.23e4"]);
   pr = postParseValidate(root, pr);
   expect(pr.kind).toBe(ParseKind.Ok);
@@ -195,12 +198,12 @@ test("supports scientific notation in numbers", () => {
 
 
 test("completion scripts contain app name", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "myapp",
     description: "Test",
     commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const bash = completionBashScript(root);
   expect(bash).toContain("bash completion for myapp");
   expect(bash).toContain("complete -F _myapp myapp");
@@ -212,18 +215,18 @@ test("completion scripts contain app name", () => {
 });
 
 test("completion scripts do not emit invalid bash substitutions", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "Test",
     commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const bash = completionBashScript(root);
   expect(bash).not.toContain("${${");
 });
 
 test("completion scripts escape shell-sensitive command text in zsh", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "Test",
     commands: [
@@ -234,18 +237,18 @@ test("completion scripts escape shell-sensitive command text in zsh", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const zsh = completionZshScript(root);
   expect(zsh).toContain("quote'\\''cmd:Say '\\''hello'\\'' and keep going.");
 });
 
 test("completion scripts keep dotted app names in registration names", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "minimal.ts",
     description: "Test",
     commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
 
   const bash = completionBashScript(root);
   expect(bash).toContain("complete -F _minimal_ts minimal.ts");
@@ -255,7 +258,7 @@ test("completion scripts keep dotted app names in registration names", () => {
 });
 
 test("trailing options after bounded positionals", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -280,7 +283,7 @@ test("trailing options after bounded positionals", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "./file", "--verbose"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["./file"]);
@@ -288,7 +291,7 @@ test("trailing options after bounded positionals", () => {
 });
 
 test("trailing options include parent-scoped flags", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -327,7 +330,7 @@ test("trailing options include parent-scoped flags", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["group", "leaf", "-u", "alice", "./file", "--json"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.path).toEqual(["group", "leaf"]);
@@ -337,7 +340,7 @@ test("trailing options include parent-scoped flags", () => {
 });
 
 test("varargs tail parses trailing options", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -364,7 +367,7 @@ test("varargs tail parses trailing options", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "./file", "--json"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["./file"]);
@@ -372,7 +375,7 @@ test("varargs tail parses trailing options", () => {
 });
 
 test("stops parsing options at --", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -399,7 +402,7 @@ test("stops parsing options at --", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "--name", "pat", "--", "--name", "bob", "-x"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.opts["name"]).toBe("pat");
@@ -407,7 +410,7 @@ test("stops parsing options at --", () => {
 });
 
 test("missing required option returns error", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     options: [
@@ -426,14 +429,14 @@ test("missing required option returns error", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x"]));
   expect(pr.kind).toBe(ParseKind.Error);
   expect(pr.errorMsg).toContain("Missing required option: --req");
 });
 
 test("provided required option parses ok", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -452,14 +455,14 @@ test("provided required option parses ok", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["x", "--req", "val"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.opts["req"]).toBe("val");
 });
 
 test("presence option cannot be required", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     options: [
@@ -478,7 +481,7 @@ test("presence option cannot be required", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/Presence option cannot be required/);
+  expect(() => cliValidateProgram(root)).toThrow(/Presence option cannot be required/);
 });
 
 test("leaf completion help prints correctly", async () => {
@@ -527,7 +530,7 @@ test("leaf root help lists completion built-in", async () => {
 });
 
 test("parse recognizes --schema at the program root", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "demo",
     commands: [
@@ -538,13 +541,13 @@ test("parse recognizes --schema at the program root", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, ["--schema"]);
   expect(pr.kind).toBe(ParseKind.Schema);
 });
 
 test("cliSchemaJson omits handlers and completion built-ins", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "demo",
     commands: [
@@ -574,7 +577,7 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
 });
 
 test("reserved option name schema is rejected", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -592,11 +595,11 @@ test("reserved option name schema is rejected", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/reserved for --schema/);
+  expect(() => cliValidateProgram(root)).toThrow(/reserved for --schema/);
 });
 
 test("root help lists --schema built-in", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "demo",
     commands: [
@@ -607,13 +610,13 @@ test("root help lists --schema built-in", () => {
       },
     ],
   };
-  const help = cliHelpRender(root, [], false);
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
   expect(help).toContain("--schema");
   expect(help).toContain("Print the full command tree as JSON.");
 });
 
 test("nested help omits --schema built-in", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "demo",
     commands: [
@@ -624,12 +627,12 @@ test("nested help omits --schema built-in", () => {
       },
     ],
   };
-  const help = cliHelpRender(root, ["x"], false);
+  const help = cliHelpRender(cliPresentationRoot(root), ["x"], false);
   expect(help).not.toContain("--schema");
 });
 
 test("completion scripts offer --schema at the program root only", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "myapp",
     description: "",
     commands: [
@@ -655,7 +658,7 @@ test("completion scripts offer --schema at the program root only", () => {
   expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
 });
 
-const nestedMcpFixture: CliCommand = {
+const nestedMcpFixture: CliProgram = {
   key: "nested.ts",
   description: "Nested groups demo.",
   mcpServer: { name: "nested-demo", version: "1.0.0" },
@@ -811,7 +814,7 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
 });
 
 test("reserved command name install is rejected", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -822,11 +825,11 @@ test("reserved command name install is rejected", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: install/);
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: install/);
 });
 
 test("top-level command name mcp is allowed without mcpServer", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -837,11 +840,11 @@ test("top-level command name mcp is allowed without mcpServer", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).not.toThrow();
+  expect(() => cliValidateProgram(root)).not.toThrow();
 });
 
 test("top-level command name mcp is rejected when mcpServer is set", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {},
@@ -853,11 +856,11 @@ test("top-level command name mcp is rejected when mcpServer is set", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: mcp/);
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: mcp/);
 });
 
 test("mcpServer on non-root node is rejected", () => {
-  const root: CliCommand = {
+  const root = {
     key: "app",
     description: "",
     commands: [
@@ -868,22 +871,22 @@ test("mcpServer on non-root node is rejected", () => {
         handler: () => {},
       },
     ],
-  };
-  expect(() => cliValidateRoot(root)).toThrow(/mcpServer is only supported on the program root/);
+  } as unknown as CliProgram;
+  expect(() => cliValidateProgram(root)).toThrow(/mcpServer is only supported on the program root/);
 });
 
 test("mcpTool on root is rejected", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpTool: { enabled: false },
     handler: () => {},
   };
-  expect(() => cliValidateRoot(root)).toThrow(/mcpTool is only supported on leaf commands/);
+  expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
 test("mcpTool on routing node is rejected", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -901,7 +904,7 @@ test("mcpTool on routing node is rejected", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/mcpTool is only supported on leaf commands/);
+  expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
 test("buildToolCallSuccess returns stdout only", () => {
@@ -1040,7 +1043,7 @@ test("minimal.ts mcp without opt-in fails", async () => {
 test("ctx.invocation is cli via cliRun", async () => {
   const indexPath = join(import.meta.dir, "index.ts");
   const { stdout } = await $`bun -e ${`
-import { cliRun, CliCommand } from ${JSON.stringify(indexPath)};
+import { cliRun, CliProgram } from ${JSON.stringify(indexPath)};
 const cli = { key: "t", description: "d", handler: (ctx) => console.log(ctx.invocation) };
 await cliRun(cli, []);
   `}`.quiet();
@@ -1049,20 +1052,20 @@ await cliRun(cli, []);
 
 test("ctx.invocation is mcp via cliInvoke", async () => {
   let seen = "";
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     handler: (ctx) => {
       seen = ctx.invocation;
     },
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const result = await cliInvoke(root, []);
   expect(result.kind).toBe("ok");
   expect(seen).toBe("mcp");
 });
 
-const enumMcpFixture: CliCommand = {
+const enumMcpFixture: CliProgram = {
   key: "app",
   description: "",
   mcpServer: {},
@@ -1092,7 +1095,7 @@ test("Enum option inputSchema includes enum array", () => {
 });
 
 test("cliInvoke rejects invalid Enum value", async () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     handler: () => {},
@@ -1106,14 +1109,14 @@ test("cliInvoke rejects invalid Enum value", async () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const result = await cliInvoke(root, ["--mode", "staging"]);
   expect(result.kind).toBe("error");
   expect(result.errorMsg).toContain("not one of");
 });
 
 test("cliInvoke accepts valid Enum value", async () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     handler: (ctx) => {
@@ -1129,34 +1132,34 @@ test("cliInvoke accepts valid Enum value", async () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const result = await cliInvoke(root, ["--mode", "dev"]);
   expect(result.kind).toBe("ok");
   expect(result.stdout.trim()).toBe("dev");
 });
 
-test("cliValidateRoot rejects Enum with no choices", () => {
-  const root: CliCommand = {
+test("cliValidateProgram rejects Enum with no choices", () => {
+  const root: CliProgram = {
     key: "app",
     description: "",
     handler: () => {},
     options: [{ name: "mode", description: "", kind: CliOptionKind.Enum, choices: [] }],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/requires non-empty choices/);
+  expect(() => cliValidateProgram(root)).toThrow(/requires non-empty choices/);
 });
 
-test("cliValidateRoot rejects Enum with duplicate choices", () => {
-  const root: CliCommand = {
+test("cliValidateProgram rejects Enum with duplicate choices", () => {
+  const root: CliProgram = {
     key: "app",
     description: "",
     handler: () => {},
     options: [{ name: "mode", description: "", kind: CliOptionKind.Enum, choices: ["a", "a"] }],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/choices must be distinct/);
+  expect(() => cliValidateProgram(root)).toThrow(/choices must be distinct/);
 });
 
 test("mcpTool.description override wins without requiresEnv suffix", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {},
@@ -1174,7 +1177,7 @@ test("mcpTool.description override wins without requiresEnv suffix", () => {
 });
 
 test("mcpTool.requiresEnv appended to auto description", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {},
@@ -1191,8 +1194,8 @@ test("mcpTool.requiresEnv appended to auto description", () => {
   expect(tools[0]!.description).toContain("[requires env: TOKEN]");
 });
 
-test("cliValidateRoot rejects duplicate mcpResources URIs", () => {
-  const root: CliCommand = {
+test("cliValidateProgram rejects duplicate mcpResources URIs", () => {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {
@@ -1203,11 +1206,11 @@ test("cliValidateRoot rejects duplicate mcpResources URIs", () => {
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/URIs must be unique/);
+  expect(() => cliValidateProgram(root)).toThrow(/URIs must be unique/);
 });
 
-test("cliValidateRoot rejects resource URI matching schemaResourceUri", () => {
-  const root: CliCommand = {
+test("cliValidateProgram rejects resource URI matching schemaResourceUri", () => {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {
@@ -1216,11 +1219,11 @@ test("cliValidateRoot rejects resource URI matching schemaResourceUri", () => {
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/conflicts with the built-in schema resource/);
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with the built-in schema resource/);
 });
 
 test("allMcpResources includes custom resources", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     mcpServer: {
@@ -1263,7 +1266,7 @@ test("loadEnvFile overwrites existing keys", () => {
 });
 
 test("Enum completions list choices in bash script", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -1368,7 +1371,7 @@ test("MCP envFile loads vars for tool handlers", async () => {
 
 // ── v1.3 parser ergonomics ────────────────────────────────────────────────────
 
-function varargsReadFixture(): CliCommand {
+function varargsReadFixture(): CliProgram {
   return {
     key: "app",
     description: "",
@@ -1398,7 +1401,7 @@ function varargsReadFixture(): CliCommand {
   };
 }
 
-function nestedDocsFallbackFixture(): CliCommand {
+function nestedDocsFallbackFixture(): CliProgram {
   return {
     key: "app",
     description: "",
@@ -1427,14 +1430,14 @@ function nestedDocsFallbackFixture(): CliCommand {
 
 test("nested fallback routes to default when argv exhausted at router", () => {
   const root = nestedDocsFallbackFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["docs"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.path).toEqual(["docs", "guide"]);
 });
 
 test("nested fallback MissingOrUnknown routes unknown token to default", () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -1467,7 +1470,7 @@ test("nested fallback MissingOrUnknown routes unknown token to default", () => {
       },
     ],
   };
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["docs", "extra-topic"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.path).toEqual(["docs", "guide"]);
@@ -1476,14 +1479,14 @@ test("nested fallback MissingOrUnknown routes unknown token to default", () => {
 
 test("nested fallback MissingOnly errors on unknown subcommand", () => {
   const root = nestedDocsFallbackFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, ["docs", "nope"]);
   expect(pr.kind).toBe(ParseKind.Error);
   expect(pr.errorMsg).toContain("Unknown subcommand");
 });
 
-test("cliValidateRoot rejects invalid nested fallbackCommand", () => {
-  const root: CliCommand = {
+test("cliValidateProgram rejects invalid nested fallbackCommand", () => {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -1501,29 +1504,29 @@ test("cliValidateRoot rejects invalid nested fallbackCommand", () => {
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/fallbackCommand 'missing' is not a child of 'docs'/);
+  expect(() => cliValidateProgram(root)).toThrow(/fallbackCommand 'missing' is not a child of 'docs'/);
 });
 
-test("cliValidateRoot accepts nested fallbackCommand when child exists", () => {
+test("cliValidateProgram accepts nested fallbackCommand when child exists", () => {
   const root = nestedDocsFallbackFixture();
-  expect(() => cliValidateRoot(root)).not.toThrow();
+  expect(() => cliValidateProgram(root)).not.toThrow();
 });
 
 test("nested router scoped help does not route to fallback", () => {
   const root = nestedDocsFallbackFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, ["docs", "--help"]);
   expect(pr.kind).toBe(ParseKind.Help);
   expect(pr.helpPath).toEqual(["docs"]);
   expect(pr.helpExplicit).toBe(true);
-  const help = cliHelpRender(root, pr.helpPath, false);
+  const help = cliHelpRender(cliPresentationRoot(root), pr.helpPath, false);
   expect(help).toContain("api");
   expect(help).toContain("guide");
 });
 
 test("varargs trailing option after positionals via cliInvoke", async () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["read", "file.txt", "--json"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["file.txt"]);
@@ -1532,7 +1535,7 @@ test("varargs trailing option after positionals via cliInvoke", async () => {
 
 test("varargs option before positionals", () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["read", "--json", "file.txt"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["file.txt"]);
@@ -1541,7 +1544,7 @@ test("varargs option before positionals", () => {
 
 test("varargs multiple files then trailing option", () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["read", "a.txt", "b.txt", "--json"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["a.txt", "b.txt"]);
@@ -1550,7 +1553,7 @@ test("varargs multiple files then trailing option", () => {
 
 test("varargs double dash forces positional", () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = postParseValidate(root, parse(root, ["read", "file.txt", "--", "--json"]));
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.args).toEqual(["file.txt", "--json"]);
@@ -1559,7 +1562,7 @@ test("varargs double dash forces positional", () => {
 
 test("varargs unknown flag errors", async () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const result = await cliInvoke(root, ["read", "--unknown"]);
   expect(result.kind).toBe("error");
   expect(result.stderr).toContain("--unknown");
@@ -1567,7 +1570,7 @@ test("varargs unknown flag errors", async () => {
 
 test("varargs scoped help in tail", () => {
   const root = varargsReadFixture();
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   const pr = parse(root, ["read", "file.txt", "--help"]);
   expect(pr.kind).toBe(ParseKind.Help);
   expect(pr.helpPath).toContain("read");
@@ -1575,7 +1578,7 @@ test("varargs scoped help in tail", () => {
 });
 
 test("ctx.positional returns single slot value", async () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -1590,7 +1593,7 @@ test("ctx.positional returns single slot value", async () => {
     ],
   };
   let captured: string | string[] | undefined;
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   await cliInvoke(root, ["x", "./file"]);
   expect(captured).toBe("./file");
 });
@@ -1598,16 +1601,18 @@ test("ctx.positional returns single slot value", async () => {
 test("ctx.positional returns varargs array", async () => {
   const root = varargsReadFixture();
   let captured: string | string[] | undefined;
-  root.commands![0]!.handler = (ctx) => {
-    captured = ctx.positional("files");
-  };
-  cliValidateRoot(root);
+  if (isCliRouter(root)) {
+    (root.commands[0] as CliLeaf).handler = (ctx) => {
+      captured = ctx.positional("files");
+    };
+  }
+  cliValidateProgram(root);
   await cliInvoke(root, ["read", "a.txt", "b.txt"]);
   expect(captured).toEqual(["a.txt", "b.txt"]);
 });
 
 test("ctx.positional returns undefined for absent optional slot", async () => {
-  const root: CliCommand = {
+  const root: CliProgram = {
     key: "app",
     description: "",
     commands: [
@@ -1624,7 +1629,7 @@ test("ctx.positional returns undefined for absent optional slot", async () => {
     ],
   };
   let captured: string | string[] | undefined;
-  cliValidateRoot(root);
+  cliValidateProgram(root);
   await cliInvoke(root, ["x"]);
   expect(captured).toBeUndefined();
 });
@@ -1633,11 +1638,13 @@ test("ctx.positional varargs matches ctx.args", async () => {
   const root = varargsReadFixture();
   let positional: string | string[] | undefined;
   let args: string[] = [];
-  root.commands![0]!.handler = (ctx) => {
-    positional = ctx.positional("files");
-    args = ctx.args;
-  };
-  cliValidateRoot(root);
+  if (isCliRouter(root)) {
+    (root.commands[0] as CliLeaf).handler = (ctx) => {
+      positional = ctx.positional("files");
+      args = ctx.args;
+    };
+  }
+  cliValidateProgram(root);
   await cliInvoke(root, ["read", "a.txt", "b.txt"]);
   expect(positional).toEqual(args);
 });
@@ -1673,7 +1680,7 @@ test("mcpToolCallToArgv empty string varargs appends nothing", () => {
 // ── Skills ────────────────────────────────────────────────────────────────────
 
 test("install config on non-root node is rejected", () => {
-  const root: CliCommand = {
+  const root = {
     key: "app",
     description: "",
     commands: [
@@ -1684,8 +1691,8 @@ test("install config on non-root node is rejected", () => {
         handler: () => {},
       },
     ],
-  };
-  expect(() => cliValidateRoot(root)).toThrow(/install is only supported on the program root/);
+  } as unknown as CliProgram;
+  expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
 test("generateSkillBundle includes frontmatter and command catalog", () => {