argsbarg 1.5.0 → 2.0.0

package/src/install/plan.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { installBinary } from "./binary.ts";
 import { installCompletions } from "./completions.ts";
 import { detectInstalledArtifacts } from "./detect-installed.ts";
@@ -45,12 +45,12 @@ function wantsSkill(opts: InstallOpts): boolean {
   return !!(opts.all || opts.skill);
 }
 
-function wantsMcp(opts: InstallOpts, root: CliCommand): boolean {
+function wantsMcp(opts: InstallOpts, root: CliProgram): boolean {
   return !!(opts.all || opts.mcp) && root.mcpServer !== undefined;
 }
 
 /** Builds install actions for normal mode (--all / scoped targets). */
-export function buildInstallPlan(root: CliCommand, paths: InstallPaths, opts: InstallOpts): InstallAction[] {
+export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: InstallOpts): InstallAction[] {
   const actions: InstallAction[] = [];
   const dry = !!opts.dry;
 
@@ -148,7 +148,7 @@ export function buildInstallPlan(root: CliCommand, paths: InstallPaths, opts: In
 }
 
 /** Builds update actions for artifacts already installed. */
-export function buildUpdatePlan(root: CliCommand, paths: InstallPaths, opts: InstallOpts): InstallAction[] {
+export function buildUpdatePlan(root: CliProgram, paths: InstallPaths, opts: InstallOpts): InstallAction[] {
   const detected = detectInstalledArtifacts(paths);
   const scoped: InstallOpts = {
     bin: true,

package/src/install/status.ts

@@ -1,4 +1,4 @@
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { buildInstallStatus, detectInstalledArtifacts } from "./detect-installed.ts";
 import type { InstallOpts } from "./plan.ts";
 import { resolveInstallPaths } from "./paths.ts";
@@ -20,7 +20,7 @@ export function installErr(msg: string): void {
 }
 
 /** Prints install status to stdout (human or JSON). */
-export function printInstallStatus(root: CliCommand, opts: InstallOpts): void {
+export function printInstallStatus(root: CliProgram, opts: InstallOpts): void {
   const paths = resolveInstallPaths(root, opts);
   const detected = detectInstalledArtifacts(paths);
   const status = buildInstallStatus(paths, detected);

package/src/install/uninstall.ts

@@ -1,6 +1,6 @@
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { uninstallBinary } from "./binary.ts";
 import { uninstallCompletions } from "./completions.ts";
 import { detectInstalledArtifacts } from "./detect-installed.ts";
@@ -20,7 +20,7 @@ function scopeAll(opts: InstallOpts): boolean {
 
 /** Builds uninstall actions from detected artifacts. */
 export function buildUninstallPlan(
-  root: CliCommand,
+  root: CliProgram,
   paths: InstallPaths,
   opts: InstallOpts,
 ): UninstallAction[] {

package/src/invoke.ts

@@ -6,7 +6,7 @@ process.exit so MCP tool calls can run handlers repeatedly.
 
 import { CliContext } from "./context.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
-import { CliCommand } from "./types.ts";
+import { type CliNode, type CliProgram, isCliRouter } from "./types.ts";
 import { format } from "node:util";
 
 /** Outcome of a non-exiting CLI invocation. */
@@ -40,7 +40,7 @@ class CliInvokeExit extends Error {
 }
 
 /** Looks up a subcommand or routing node by `key`. */
-function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
+function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
 }
 
@@ -48,7 +48,7 @@ function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
  * Parses argv against the user root, runs the leaf handler, and returns captured output.
  * Never calls process.exit.
  */
-export async function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult> {
+export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult> {
   let pr = parse(root, argv);
   pr = postParseValidate(root, pr);
 
@@ -82,9 +82,18 @@ export async function cliInvoke(root: CliCommand, argv: string[]): Promise<CliIn
     };
   }
 
-  let current: CliCommand = root;
+  let current: CliProgram = root;
   for (const seg of pr.path) {
-    const ch = findChild(current.commands ?? [], seg);
+    if (!isCliRouter(current)) {
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout: "",
+        stderr: "Internal error: missing handler for path.",
+        errorMsg: "Internal error: missing handler for path.",
+      };
+    }
+    const ch = findChild(current.commands, seg);
     if (!ch) {
       return {
         kind: "error",

package/src/mcp/server.ts

@@ -4,7 +4,7 @@ resources, and ping. Responses are newline-delimited JSON on stdout only.
 */
 
 import { cliInvoke } from "../invoke.ts";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { buildToolCallSuccess } from "./result.ts";
 import {
   allMcpResources,
@@ -41,7 +41,7 @@ function writeError(id: string | number | null | undefined, code: number, messag
 }
 
 /** Handles one NDJSON request line. */
-async function handleRequestLine(root: CliCommand, line: string): Promise<void> {
+async function handleRequestLine(root: CliProgram, line: string): Promise<void> {
   let req: JsonRpcRequest;
   try {
     req = JSON.parse(line) as JsonRpcRequest;
@@ -217,7 +217,7 @@ async function handleRequestLine(root: CliCommand, line: string): Promise<void>
 }
 
 /** Runs the MCP NDJSON read loop on stdin until EOF. */
-export async function mcpServeStdioLoop(root: CliCommand): Promise<void> {
+export async function mcpServeStdioLoop(root: CliProgram): Promise<void> {
   let buffer = "";
   for await (const chunk of Bun.stdin.stream()) {
     buffer += new TextDecoder().decode(chunk);

package/src/mcp/tools.ts

@@ -1,5 +1,5 @@
 /*
-This module maps CliCommand leaf nodes to MCP tool definitions and converts
+This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for cliInvoke.
 */
 
@@ -7,7 +7,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
-import { CliCommand, CliOption, CliOptionKind, CliPositional } from "../types.ts";
+import { CliProgram, CliLeaf, CliNode, CliOption, CliOptionKind, CliPositional, isCliLeaf, isCliRouter } from "../types.ts";
 
 /** Default URI for the CLI schema MCP resource. */
 export const MCP_SCHEMA_URI_DEFAULT = "argsbarg://schema";
@@ -21,7 +21,7 @@ export interface McpToolDef {
   /** Command path segments from the program root. */
   path: string[];
   /** Leaf command node. */
-  leaf: CliCommand;
+  leaf: CliLeaf;
   /** JSON Schema for tools/call arguments. */
   inputSchema: Record<string, unknown>;
 }
@@ -38,7 +38,7 @@ export function sanitizeToolSegment(key: string): string {
 }
 
 /** Builds the MCP tool name for a leaf at the given path. */
-export function mcpToolName(root: CliCommand, path: string[]): string {
+export function mcpToolName(root: CliProgram, path: string[]): string {
   if (path.length === 0) {
     return sanitizeToolSegment(root.key);
   }
@@ -71,7 +71,7 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 }
 
 /** Builds inputSchema for a leaf command. */
-function buildInputSchema(root: CliCommand, path: string[], leaf: CliCommand): Record<string, unknown> {
+function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Record<string, unknown> {
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
@@ -102,7 +102,7 @@ function buildInputSchema(root: CliCommand, path: string[], leaf: CliCommand): R
 }
 
 /** Resolves MCP tool description with optional override and requiresEnv suffix. */
-function resolveToolDescription(root: CliCommand, path: string[], leaf: CliCommand): string {
+function resolveToolDescription(root: CliProgram, path: string[], leaf: CliLeaf): string {
   if (leaf.mcpTool?.description) {
     return leaf.mcpTool.description;
   }
@@ -124,7 +124,7 @@ export interface McpResourceEntry {
 }
 
 /** Returns built-in schema resource plus user mcpServer.resources. */
-export function allMcpResources(root: CliCommand): McpResourceEntry[] {
+export function allMcpResources(root: CliProgram): McpResourceEntry[] {
   const schemaUri = resolveMcpSchemaUri(root);
   const builtIn: McpResourceEntry = {
     uri: schemaUri,
@@ -144,12 +144,12 @@ export function allMcpResources(root: CliCommand): McpResourceEntry[] {
 }
 
 /** Recursively collects MCP tool definitions from user leaf commands. */
-export function collectMcpTools(root: CliCommand): McpToolDef[] {
+export function collectMcpTools(root: CliProgram): McpToolDef[] {
   const out: McpToolDef[] = [];
 
   /** Walks the command tree and appends leaf tools. */
-  function walk(cmd: CliCommand, path: string[]): void {
-    if ("handler" in cmd && cmd.handler) {
+  function walk(cmd: CliNode, path: string[]): void {
+    if (isCliLeaf(cmd)) {
       if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp") {
         return;
       }
@@ -165,15 +165,15 @@ export function collectMcpTools(root: CliCommand): McpToolDef[] {
       });
       return;
     }
-    for (const ch of cmd.commands ?? []) {
+    for (const ch of cmd.commands) {
       walk(ch, [...path, ch.key]);
     }
   }
 
-  if ("handler" in root && root.handler) {
+  if (isCliLeaf(root)) {
     walk(root, []);
   } else {
-    for (const ch of root.commands ?? []) {
+    for (const ch of root.commands) {
       walk(ch, [ch.key]);
     }
   }
@@ -193,7 +193,7 @@ function resolveMcpVersionFromPackageJson(): string | undefined {
 }
 
 /** Resolves MCP server name and version for initialize. */
-export function resolveMcpServerInfo(root: CliCommand): { name: string; version: string } {
+export function resolveMcpServerInfo(root: CliProgram): { name: string; version: string } {
   return {
     name: root.mcpServer?.name ?? root.key,
     version: root.mcpServer?.version ?? resolveMcpVersionFromPackageJson() ?? "0.0.0",
@@ -201,13 +201,13 @@ export function resolveMcpServerInfo(root: CliCommand): { name: string; version:
 }
 
 /** Resolves the schema resource URI for this app. */
-export function resolveMcpSchemaUri(root: CliCommand): string {
+export function resolveMcpSchemaUri(root: CliProgram): string {
   return root.mcpServer?.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
 }
 
 /** Converts flat MCP tool arguments to argv for cliInvoke. */
 export function mcpToolCallToArgv(
-  root: CliCommand,
+  root: CliProgram,
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {

package/src/mcp.ts

@@ -4,13 +4,13 @@ This module starts the ArgsBarg MCP stdio server for opt-in program roots.
 
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
-import { CliCommand } from "./types.ts";
+import { CliProgram } from "./types.ts";
 
 /**
  * Runs the MCP JSON-RPC server on stdin/stdout until stdin closes, then exits.
  * Caller must ensure `root.mcpServer` is set.
  */
-export async function cliMcpServeStdio(root: CliCommand): Promise<never> {
+export async function cliMcpServeStdio(root: CliProgram): Promise<never> {
   try {
     if (root.mcpServer) {
       bootstrapMcpEnv(root.mcpServer);

package/src/parse.ts

@@ -9,10 +9,13 @@ across every entry path.
 
 import { CliContext } from "./context.ts";
 import {
-  CliCommand,
+  type CliLeaf,
+  CliNode,
   CliFallbackMode,
   CliOption,
   CliOptionKind,
+  isCliLeaf,
+  isCliRouter,
 } from "./types.ts";
 import { fullStringIsDouble } from "./utils.ts";
 
@@ -69,7 +72,7 @@ function isSchemaTok(tok: string): boolean {
 }
 
 /** Looks up a subcommand or routing node by `key`. */
-function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
+function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
 }
 
@@ -217,15 +220,16 @@ function consumeOptions(
 // ── Positional Collection ─────────────────────────────────────────────────────
 
 /** Merges option defs from the program root along the routed command path. */
-export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   let defs = [...(root.options ?? [])];
-  let cmds = root.commands ?? [];
+  let node: CliNode = root;
 
   for (const seg of path) {
-    const ch = findChild(cmds, seg);
+    if (!isCliRouter(node)) break;
+    const ch = findChild(node.commands, seg);
     if (!ch) break;
     defs.push(...(ch.options ?? []));
-    cmds = ch.commands ?? [];
+    node = ch;
   }
 
   return defs;
@@ -233,7 +237,7 @@ export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[]
 
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
-  node: CliCommand,
+  node: CliLeaf,
   startIdx: number,
   argv: string[],
   path: string[],
@@ -384,14 +388,16 @@ function schemaResult(): ParseResult {
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
-export function parse(root: CliCommand, argv: string[]): ParseResult {
+export function parse(root: CliNode, argv: string[]): ParseResult {
   let i = 0;
   const path: string[] = [];
   const opts: Record<string, string> = {};
 
   const rootLenient =
+    isCliRouter(root) &&
     root.fallbackCommand !== undefined &&
-    ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+    ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
+      (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
 
   // Consume root-level options first
   const rootRep = consumeOptions(root.options ?? [], rootLenient, argv, i, opts);
@@ -420,16 +426,20 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
   // Determine which subcommand to route to
   let cmdName: string;
-  let node: CliCommand | undefined;
+  let node: CliNode | undefined;
 
-  if (root.handler) {
-    return finishLeaf(root as CliCommand, i, argv, path, opts, root.options ?? [], forcePositionals);
+  if (isCliLeaf(root)) {
+    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals);
   }
 
   if (i >= argv.length) {
-    if (root.fallbackCommand !== undefined && ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)) {
+    if (
+      root.fallbackCommand !== undefined &&
+      ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly ||
+        (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)
+    ) {
       cmdName = root.fallbackCommand;
-      node = findChild(root.commands ?? [], cmdName);
+      node = findChild(root.commands, cmdName);
       if (!node) {
         return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
       }
@@ -438,7 +448,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
   } else {
     const peek = argv[i];
-    const childPick = !forcePositionals ? findChild(root.commands ?? [], peek) : undefined;
+    const childPick = !forcePositionals ? findChild(root.commands, peek) : undefined;
 
     if (childPick !== undefined) {
       cmdName = peek;
@@ -452,14 +462,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
       if (canRouteUnknown) {
         cmdName = root.fallbackCommand!;
-        node = findChild(root.commands ?? [], cmdName);
+        node = findChild(root.commands, cmdName);
         if (!node) {
           return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
         }
       } else {
         cmdName = peek;
         if (!forcePositionals) i += 1;
-        node = findChild(root.commands ?? [], cmdName);
+        node = findChild(root.commands, cmdName);
         if (!node) {
           return {
             kind: ParseKind.Error,
@@ -506,14 +516,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if (i >= argv.length) {
-      if ((current.commands ?? []).length > 0) {
+      if (isCliRouter(current) && current.commands.length > 0) {
         const fb = current.fallbackCommand;
         const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
         if (
           fb !== undefined &&
           (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
         ) {
-          const fbNode = findChild(current.commands ?? [], fb);
+          const fbNode = findChild(current.commands, fb);
           if (fbNode) {
             path.push(fb);
             current = fbNode;
@@ -522,6 +532,9 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
         }
         return helpResult(path, false);
       }
+      if (!isCliLeaf(current)) {
+        return helpResult(path, false);
+      }
       return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
     }
 
@@ -539,8 +552,8 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
-    if (!forcePositionals) {
-      const childOpt = findChild(current.commands ?? [], tok);
+    if (!forcePositionals && isCliRouter(current)) {
+      const childOpt = findChild(current.commands, tok);
       if (childOpt !== undefined) {
         i += 1;
         path.push(tok);
@@ -549,7 +562,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       }
     }
 
-    if ((current.commands ?? []).length > 0) {
+    if (isCliRouter(current) && current.commands.length > 0) {
       const fb = current.fallbackCommand;
       const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
       const canRouteUnknown =
@@ -557,7 +570,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
         (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
 
       if (canRouteUnknown) {
-        const fbNode = findChild(current.commands ?? [], fb!);
+        const fbNode = findChild(current.commands, fb!);
         if (fbNode) {
           path.push(fb!);
           current = fbNode;
@@ -577,6 +590,9 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
+    if (!isCliLeaf(current)) {
+      return helpResult(path, false);
+    }
     return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
   }
 }
@@ -586,14 +602,26 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 /**
  * Validates option keys and numeric values for an Ok parse, merging in-scope options along `pr.path`.
  */
-export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResult {
+export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
   let defs = [...(root.options ?? [])];
-  let cmds = root.commands ?? [];
+  let node: CliNode = root;
 
   for (const seg of pr.path) {
-    const ch = findChild(cmds, seg);
+    if (!isCliRouter(node)) {
+      return {
+        kind: ParseKind.Error,
+        path: pr.path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: "Internal path error",
+        errorHelpPath: pr.path,
+      };
+    }
+    const ch = findChild(node.commands, seg);
     if (!ch) {
       return {
         kind: ParseKind.Error,
@@ -607,7 +635,7 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
       };
     }
     defs.push(...(ch.options ?? []));
-    cmds = ch.commands ?? [];
+    node = ch;
   }
 
   for (const d of defs) {

package/src/runtime.ts

@@ -2,26 +2,25 @@
 This module runs parsed commands, help, errors, completion, and leaf handlers.
 */
 
+import { resolveCapabilities } from "./capabilities.ts";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
 import { cliPresentationRoot } from "./builtins/presentation.ts";
+import type { CliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { isCompiledExecutable } from "./install/compiled.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
-import { CliCommand } from "./types.ts";
-import { cliValidateRoot } from "./validate.ts";
+import { cliValidateProgram } from "./validate.ts";
 
-function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
-  if (root.handler) {
-    return root;
-  }
-  return cliPresentationRoot(root);
+function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
+  return cliPresentationRoot(program);
 }
 
-export async function cliRun(root: CliCommand, argv: string[] = process.argv.slice(2)): Promise<never> {
+export async function cliRun(program: CliProgram, argv: string[] = process.argv.slice(2)): Promise<never> {
   try {
-    cliValidateRoot(root);
+    cliValidateProgram(program);
   } catch (err) {
     if (err instanceof Error) {
       process.stderr.write(err.message + "\n");
@@ -31,7 +30,9 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  if (argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
+  const caps = resolveCapabilities(program);
+
+  if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
     process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
     process.exit(1);
   }
@@ -41,31 +42,35 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  let parseRoot: CliCommand;
+  let parseRoot: CliNode;
+  let completionParseRoot: CliRouter = cliRootMergedWithBuiltins(program);
   let isLeafCompletionIntercept = false;
 
-  if (root.handler) {
-    const intercept = builtinInterceptRoot(root, argv);
-    if (intercept.isLeafCompletionIntercept || intercept.parseRoot !== root) {
+  if (isCliLeaf(program)) {
+    const intercept = builtinInterceptRoot(program, argv);
+    if (intercept.isLeafCompletionIntercept || intercept.parseRoot !== program) {
       parseRoot = intercept.parseRoot;
+      completionParseRoot = isCliRouter(intercept.parseRoot)
+        ? intercept.parseRoot
+        : cliRootMergedWithBuiltins(program);
       isLeafCompletionIntercept = intercept.isLeafCompletionIntercept;
     } else {
-      parseRoot = root;
+      parseRoot = program;
     }
   } else {
-    parseRoot = cliRootMergedWithBuiltins(root);
+    parseRoot = cliRootMergedWithBuiltins(program);
   }
 
   let pr = parse(parseRoot, argv);
   pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
-    process.stdout.write(cliHelpRender(cliPresentationRoot(root), pr.helpPath, false));
+    process.stdout.write(cliHelpRender(cliPresentationRoot(program), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
   if (pr.kind === ParseKind.Schema) {
-    process.stdout.write(cliSchemaJson(root));
+    process.stdout.write(cliSchemaJson(program));
     process.exit(0);
   }
 
@@ -73,17 +78,21 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
     process.stderr.write(msg + "\n");
-    process.stderr.write(cliHelpRender(cliPresentationRoot(root), pr.errorHelpPath, true));
+    process.stderr.write(cliHelpRender(cliPresentationRoot(program), pr.errorHelpPath, true));
     process.exit(1);
   }
 
   if (pr.kind === ParseKind.Ok) {
-    await dispatchBuiltin(root, pr, { isLeafCompletionIntercept, parseRoot });
+    await dispatchBuiltin(program, pr, { isLeafCompletionIntercept, parseRoot: completionParseRoot });
   }
 
-  let current = parseRoot;
+  let current: CliNode = parseRoot;
   for (const seg of pr.path) {
-    const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
+    if (!isCliRouter(current)) {
+      process.stderr.write("Internal error: missing handler for path.\n");
+      process.exit(1);
+    }
+    const ch = current.commands.find((candidate) => candidate.key === seg);
     if (!ch) {
       process.stderr.write("Internal error: missing handler for path.\n");
       process.exit(1);
@@ -91,12 +100,12 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     current = ch;
   }
 
-  if (!current.handler) {
+  if (!isCliLeaf(current) || !current.handler) {
     process.stderr.write("Internal error: missing handler for path.\n");
     process.exit(1);
   }
 
-  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot, "cli");
+  const ctx = new CliContext(program.key, pr.path, pr.args, pr.opts, program, "cli");
   try {
     await Promise.resolve(current.handler(ctx));
     process.exit(0);