argsbarg 1.5.0 → 2.0.1

package/src/index.ts

@@ -13,7 +13,7 @@ export { CliContext } from "./context.ts";
 export { cliErrWithHelp, cliRun } from "./runtime";
 export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
 export type {
-  CliCommand,
+  CliProgram,
   CliHandler,
   CliInvocation,
   CliMcpResource,

package/src/install/binary.ts

@@ -1,6 +1,6 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { InstallPaths } from "./paths.ts";
 import {
   buildPathRcBlock,
@@ -17,7 +17,7 @@ export interface BinaryInstallResult {
 }
 
 /** Copies the running binary to the install path and patches rc files when shells are detected. */
-export function installBinary(root: CliCommand, paths: InstallPaths, dry: boolean): BinaryInstallResult {
+export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolean): BinaryInstallResult {
   const changed: string[] = [];
   const shells = detectShells();
   let patchedBashRc = false;
@@ -58,7 +58,7 @@ export function installBinary(root: CliCommand, paths: InstallPaths, dry: boolea
 }
 
 /** Removes binary and rc marker blocks. */
-export function uninstallBinary(root: CliCommand, paths: InstallPaths, dry: boolean): string[] {
+export function uninstallBinary(root: CliProgram, paths: InstallPaths, dry: boolean): string[] {
   const changed: string[] = [];
   if (existsSync(paths.binaryPath)) {
     if (!dry) unlinkSync(paths.binaryPath);

package/src/install/completions.ts

@@ -1,13 +1,13 @@
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { completionBashScript, completionFishScript, completionZshScript } from "../builtins/index.ts";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
 import { InstallPaths } from "./paths.ts";
 import { detectShells } from "./shell.ts";
 
 /** Writes shell completion scripts for detected shells. */
-export function installCompletions(root: CliCommand, paths: InstallPaths, dry: boolean): string[] {
+export function installCompletions(root: CliProgram, paths: InstallPaths, dry: boolean): string[] {
   const changed: string[] = [];
   const shells = detectShells();
   const schema = cliPresentationRoot(root);

package/src/install/detect-installed.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { InstallPaths } from "./paths.ts";
 
 export interface InstalledArtifacts {

package/src/install/index.ts

@@ -1,5 +1,5 @@
 import { readSync } from "node:fs";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { cliSkillInstall } from "../skill/install.ts";
 import { checkMcpConflict, expectedMcpEntry } from "./mcp-config.ts";
 import {
@@ -74,7 +74,7 @@ function promptConfirm(): boolean {
 }
 
 function runSkillAction(
-  root: CliCommand,
+  root: CliProgram,
   kind: "cursor-skill" | "claude-skill",
   opts: InstallOpts,
 ): string[] {
@@ -87,7 +87,7 @@ function runSkillAction(
 }
 
 function executePlan(
-  root: CliCommand,
+  root: CliProgram,
   actions: Array<InstallAction | UninstallAction>,
   opts: InstallOpts,
 ): string[] {
@@ -114,7 +114,7 @@ function executePlan(
 }
 
 /** Main install command orchestrator. */
-export async function cliInstall(root: CliCommand, rawOpts: Record<string, string>): Promise<never> {
+export async function cliInstall(root: CliProgram, rawOpts: Record<string, string>): Promise<never> {
   const opts = parseInstallOpts(rawOpts);
   const err = validateOpts(opts);
   if (err) {

package/src/install/install.test.ts

@@ -2,14 +2,14 @@ import { describe, expect, test, beforeEach, afterEach } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { detectInstalledArtifacts } from "./detect-installed.ts";
 import { resolveInstallPaths } from "./paths.ts";
 import { buildInstallPlan } from "./plan.ts";
 import { printInstallStatus } from "./status.ts";
 import { parseInstallOpts } from "./index.ts";
 
-const fixture: CliCommand = {
+const fixture: CliProgram = {
   key: "testapp",
   description: "Test",
   mcpServer: { name: "testapp" },

package/src/install/mcp-config.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { InstallPaths } from "./paths.ts";
 
 export interface McpServerEntry {
@@ -8,7 +8,7 @@ export interface McpServerEntry {
   args: string[];
 }
 
-export function expectedMcpEntry(root: CliCommand): McpServerEntry {
+export function expectedMcpEntry(root: CliProgram): McpServerEntry {
   return { command: root.key, args: ["mcp"] };
 }
 

package/src/install/paths.ts

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { sanitizeToolSegment } from "../mcp/tools.ts";
 
 export interface InstallPaths {
@@ -35,7 +35,7 @@ function expandTilde(path: string): string {
 }
 
 /** Resolves the binary install directory from CLI flag, env, or config. */
-export function resolveBindir(root: CliCommand, prefix?: string): string {
+export function resolveBindir(root: CliProgram, prefix?: string): string {
   const raw = prefix ?? process.env.INSTALL_PREFIX ?? root.install?.prefix;
   if (raw) {
     return expandTilde(raw);
@@ -44,7 +44,7 @@ export function resolveBindir(root: CliCommand, prefix?: string): string {
 }
 
 /** Resolves all install artifact paths for a program root. */
-export function resolveInstallPaths(root: CliCommand, opts: { prefix?: string }): InstallPaths {
+export function resolveInstallPaths(root: CliProgram, opts: { prefix?: string }): InstallPaths {
   const home = userHome();
   const bindir = resolveBindir(root, opts.prefix);
   const key = root.key;

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) {