argsbarg 1.5.0 → 2.0.1

package/src/builtins/completion-bash.ts

@@ -1,4 +1,4 @@
-import { CliCommand, CliOptionKind } from "../types.ts";
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
 import {
   escShellSingleQuoted,
@@ -161,7 +161,7 @@ function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
-function emitMainBodyBash(schema: CliCommand, ident: string): string {
+function emitMainBodyBash(schema: CliRouter, ident: string): string {
   const main = mainName(schema.key);
   let o = "_${main}() {\n".replace("${main}", main);
   o += "  local cur=\"${COMP_WORDS[COMP_CWORD]}\"\n";
@@ -196,7 +196,7 @@ function emitMainBodyBash(schema: CliCommand, ident: string): string {
 }
 
 /** Returns a self-contained bash `complete` script for the given program schema. */
-export function completionBashScript(schema: CliCommand): string {
+export function completionBashScript(schema: CliRouter): string {
   const ident = identToken(schema.key);
   const scopes = collectScopes(schema);
   const pathIndex: Record<string, number> = {};

package/src/builtins/completion-fish.ts

@@ -1,4 +1,4 @@
-import { CliCommand, CliOptionKind } from "../types.ts";
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
 import { collectScopes } from "./scopes.ts";
 import {
   escFishSingleQuoted,
@@ -27,7 +27,7 @@ function scopeCondition(ident: string, scopeIndex: number, path: string): string
 }
 
 /** Returns a self-contained fish completion script for the given program schema. */
-export function completionFishScript(schema: CliCommand): string {
+export function completionFishScript(schema: CliRouter): string {
   const ident = identToken(schema.key);
   const app = schema.key;
   const scopes = collectScopes(schema);

package/src/builtins/completion-group.ts

@@ -1,9 +1,9 @@
-import { CliCommand } from "../types.ts";
+import { type CliLeaf, type CliNode, type CliRouter } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
  */
-export function cliBuiltinCompletionGroup(appName: string): CliCommand {
+export function cliBuiltinCompletionGroup(appName: string): CliRouter {
   return {
     key: "completion",
     description: "Generate the autocompletion script for shells.",

package/src/builtins/completion-zsh.ts

@@ -1,4 +1,4 @@
-import { CliCommand, CliOptionKind } from "../types.ts";
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
 import {
   escShellSingleQuoted,
@@ -191,7 +191,7 @@ function emitEnumReplyZsh(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
-function emitMainBodyZsh(schema: CliCommand, ident: string): string {
+function emitMainBodyZsh(schema: CliRouter, ident: string): string {
   const main = mainName(schema.key);
   let o = "_${main}() {\n".replace("${main}", main);
   o += "  local curcontext=\"$curcontext\" ret=1\n";
@@ -224,7 +224,7 @@ function emitMainBodyZsh(schema: CliCommand, ident: string): string {
 }
 
 /** Returns a self-contained zsh completion script for the given program schema. */
-export function completionZshScript(schema: CliCommand): string {
+export function completionZshScript(schema: CliRouter): string {
   const ident = identToken(schema.key);
   const scopes = collectScopes(schema);
   const pathIndex: Record<string, number> = {};

package/src/builtins/dispatch.ts

@@ -1,10 +1,13 @@
-import { CliCommand } from "../types.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import type { CliNode, CliProgram, CliRouter } from "../types.ts";
+import { isCliLeaf, isCliRouter } from "../types.ts";
 import { completionBashScript } from "./completion-bash.ts";
 import { completionFishScript } from "./completion-fish.ts";
 import { completionZshScript } from "./completion-zsh.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
+import { cliPresentationRoot } from "./presentation.ts";
 import { cliMcpServeStdio } from "../mcp.ts";
 import { cliInstall } from "../install/index.ts";
 import { isCompiledExecutable } from "../install/compiled.ts";
@@ -13,22 +16,32 @@ import { ParseKind } from "../parse.ts";
 
 export interface DispatchBuiltinOpts {
   isLeafCompletionIntercept: boolean;
-  parseRoot: CliCommand;
+  parseRoot: CliRouter;
+}
+
+function completionSchema(program: CliProgram, opts: DispatchBuiltinOpts): CliRouter {
+  if (opts.isLeafCompletionIntercept) {
+    return cliPresentationRoot(program);
+  }
+  return opts.parseRoot;
 }
 
 /**
  * Handles built-in commands after parse.
  */
 export async function dispatchBuiltin(
-  root: CliCommand,
+  program: CliProgram,
   pr: ParseResult,
   opts: DispatchBuiltinOpts,
 ): Promise<void> {
   if (pr.kind !== ParseKind.Ok) {
     return;
   }
+
+  const caps = resolveCapabilities(program);
+
   if (pr.path[0] === "completion") {
-    const schemaForCompletion = opts.isLeafCompletionIntercept ? root : opts.parseRoot;
+    const schemaForCompletion = completionSchema(program, opts);
     if (pr.path[1] === "bash") {
       process.stdout.write(completionBashScript(schemaForCompletion));
       process.exit(0);
@@ -45,7 +58,7 @@ export async function dispatchBuiltin(
   }
 
   if (pr.path[0] === "mcp") {
-    if (!root.mcpServer) {
+    if (!caps.mcp) {
       process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
       process.exit(1);
     }
@@ -53,7 +66,7 @@ export async function dispatchBuiltin(
       process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
       process.exit(1);
     }
-    await cliMcpServeStdio(root);
+    await cliMcpServeStdio(program);
     process.exit(0);
   }
 
@@ -64,7 +77,7 @@ export async function dispatchBuiltin(
       );
       process.exit(1);
     }
-    if (root.install?.enabled === false) {
+    if (!caps.install) {
       process.stderr.write("install is disabled. Remove install.enabled: false from the program root.\n");
       process.exit(1);
     }
@@ -72,52 +85,54 @@ export async function dispatchBuiltin(
       process.stderr.write("Unknown subcommand: install " + pr.path.slice(1).join(" ") + "\n");
       process.exit(1);
     }
-    await cliInstall(root, pr.opts);
+    await cliInstall(program, pr.opts);
   }
 }
 
 /** Built-in intercept roots for leaf programs. */
 export function builtinInterceptRoot(
-  root: CliCommand,
+  program: CliProgram,
   argv: string[],
-): { parseRoot: CliCommand; isLeafCompletionIntercept: boolean } {
-  if (!root.handler || argv.length < 1) {
-    return { parseRoot: root, isLeafCompletionIntercept: false };
+): { parseRoot: CliNode; isLeafCompletionIntercept: boolean } {
+  if (!isCliLeaf(program) || argv.length < 1) {
+    return { parseRoot: program, isLeafCompletionIntercept: false };
   }
 
+  const caps = resolveCapabilities(program);
   const first = argv[0];
+
   if (first === "completion") {
     return {
       parseRoot: {
-        key: root.key,
-        description: root.description,
-        commands: [completionGroup(root.key)],
-      } as CliCommand,
+        key: program.key,
+        description: program.description,
+        commands: [completionGroup(program.key)],
+      },
       isLeafCompletionIntercept: true,
     };
   }
 
-  if (first === "install" && isCompiledExecutable() && root.install?.enabled !== false) {
+  if (first === "install" && caps.install) {
     return {
       parseRoot: {
-        key: root.key,
-        description: root.description,
-        commands: [cliBuiltinInstallCommand(root)],
-      } as CliCommand,
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinInstallCommand(program)],
+      },
       isLeafCompletionIntercept: false,
     };
   }
 
-  if (first === "mcp" && root.mcpServer !== undefined) {
+  if (first === "mcp" && caps.mcp) {
     return {
       parseRoot: {
-        key: root.key,
-        description: root.description,
+        key: program.key,
+        description: program.description,
         commands: [cliBuiltinMcpCommand()],
-      } as CliCommand,
+      },
       isLeafCompletionIntercept: false,
     };
   }
 
-  return { parseRoot: root, isLeafCompletionIntercept: false };
+  return { parseRoot: program, isLeafCompletionIntercept: false };
 }

package/src/builtins/export.ts

@@ -1,8 +1,8 @@
-import { CliCommand, CliFallbackMode, CliOption, CliPositional } from "../types.ts";
+import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
+import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
-import { isCompiledExecutable } from "../install/compiled.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -16,7 +16,13 @@ export interface CliSchemaExport {
   positionals?: CliPositional[];
 }
 
-function exportBuiltinNode(cmd: CliCommand): CliSchemaExport {
+function exportBuiltinNode(cmd: {
+  key: string;
+  description: string;
+  notes?: string;
+  options?: CliOption[];
+  commands?: CliSchemaExport[];
+}): CliSchemaExport {
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -34,12 +40,13 @@ function exportBuiltinNode(cmd: CliCommand): CliSchemaExport {
 }
 
 /** Built-in subtrees matching help visibility for `--schema` export. */
-export function exportPresentationBuiltins(root: CliCommand): CliSchemaExport[] {
-  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(root.key))];
-  if (isCompiledExecutable() && root.install?.enabled !== false) {
-    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(root)));
+export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
+  const resolved = caps ?? resolveCapabilities(program);
+  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(program.key))];
+  if (resolved.install) {
+    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
   }
-  if (root.mcpServer !== undefined) {
+  if (resolved.mcp) {
     builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
   }
   return builtins;

package/src/builtins/install.ts

@@ -1,7 +1,7 @@
-import { CliCommand, CliOption, CliOptionKind } from "../types.ts";
+import { CliProgram, CliOption, CliOptionKind, type CliLeaf } from "../types.ts";
 
 /** Install command options (dynamic: `--mcp` only when MCP is enabled). */
-export function installBuiltinOptions(root: CliCommand): CliOption[] {
+export function installBuiltinOptions(root: CliProgram): CliOption[] {
   const opts: CliOption[] = [
     {
       name: "all",
@@ -78,7 +78,7 @@ export function installBuiltinOptions(root: CliCommand): CliOption[] {
 }
 
 /** Builds the `install` built-in command (compiled binaries only). */
-export function cliBuiltinInstallCommand(root: CliCommand): CliCommand {
+export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
   return {
     key: "install",
     description: "Install the binary, shell completions, agent skills, and MCP config to your user environment.",

package/src/builtins/mcp.ts

@@ -1,7 +1,7 @@
-import { CliCommand, CliOption, CliOptionKind } from "../types.ts";
+import { type CliLeaf } from "../types.ts";
 
 /** Presence options for the top-level `mcp` built-in (leaf). */
-export function cliBuiltinMcpCommand(): CliCommand {
+export function cliBuiltinMcpCommand(): CliLeaf {
   return {
     key: "mcp",
     description: "Run as an MCP server over stdio for AI agents.",

package/src/builtins/presentation.ts

@@ -1,39 +1,50 @@
-import { CliCommand } from "../types.ts";
-import { isCompiledExecutable } from "../install/compiled.ts";
+import type { CliCapabilities } from "../capabilities.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
+import { isCliLeaf, isCliRouter } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 
-/** Built-in commands shown in help and merged for routing CLIs. */
-export function presentationBuiltins(root: CliCommand): CliCommand[] {
-  const builtins: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
-  if (isCompiledExecutable() && root.install?.enabled !== false) {
-    builtins.push(cliBuiltinInstallCommand(root));
+/** Built-in command nodes injected for help, schema, and completions. */
+export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program.key)];
+  if (caps.install) {
+    builtins.push(cliBuiltinInstallCommand(program));
   }
-  if (root.mcpServer !== undefined) {
+  if (caps.mcp) {
     builtins.push(cliBuiltinMcpCommand());
   }
   return builtins;
 }
 
 /**
- * Returns a schema suitable for help display, including reserved built-in subtrees.
- * Routing roots get builtins merged; leaf roots are wrapped as a tiny router.
+ * Returns a schema suitable for help display, including capability-built-in subtrees.
+ * Routing programs get builtins merged; leaf programs are wrapped as a tiny router.
  */
-export function cliPresentationRoot(root: CliCommand): CliCommand {
-  if ((root.commands ?? []).some((c) => c.key === "completion")) {
-    return root;
-  }
-  if ("handler" in root && root.handler) {
+export function cliPresentationRoot(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const builtins = presentationBuiltins(program, caps);
+
+  if (isCliLeaf(program)) {
     return {
-      key: root.key,
-      description: root.description,
-      options: root.options,
-      commands: presentationBuiltins(root),
-    } as CliCommand;
+      key: program.key,
+      description: program.description,
+      options: program.options,
+      commands: builtins,
+    };
   }
+
   return {
-    ...root,
-    commands: [...(root.commands ?? []), ...presentationBuiltins(root)],
-  } as CliCommand;
+    key: program.key,
+    description: program.description,
+    notes: program.notes,
+    options: program.options,
+    fallbackCommand: program.fallbackCommand,
+    fallbackMode: program.fallbackMode,
+    commands: [...program.commands, ...builtins],
+  };
 }
+
+/** Presentation tree may include builtin leaf stubs. */
+export type CliPresentationNode = CliNode | CliLeaf;

package/src/builtins/scopes.ts

@@ -2,35 +2,36 @@
 Shared completion scope walk used by bash, zsh, and fish emitters.
 */
 
-import { CliCommand } from "../types.ts";
+import { type CliNode, type CliRouter, isCliLeaf, isCliRouter } from "../types.ts";
 
 /** One tab-completion scope: child commands, options, and path key for the schema walk. */
 export interface ScopeRec {
-  kids: CliCommand[];
+  kids: CliNode[];
   opts: import("../types.ts").CliOption[];
   path: string;
   wantsFiles: boolean;
 }
 
-function hasPositionalArguments(cmd: CliCommand): boolean {
-  return (cmd.positionals ?? []).length > 0;
+function hasPositionalArguments(cmd: CliNode): boolean {
+  return isCliLeaf(cmd) && (cmd.positionals ?? []).length > 0;
 }
 
-function walkScopes(cmdPath: string, cmd: CliCommand, acc: ScopeRec[]): void {
+function walkScopes(cmdPath: string, cmd: CliNode, acc: ScopeRec[]): void {
+  const kids = isCliRouter(cmd) ? cmd.commands : [];
   acc.push({
-    kids: cmd.commands ?? [],
+    kids,
     opts: cmd.options ?? [],
     path: cmdPath,
     wantsFiles: hasPositionalArguments(cmd),
   });
-  for (const ch of cmd.commands ?? []) {
+  for (const ch of kids) {
     const nextPath = cmdPath === "" ? ch.key : cmdPath + "/" + ch.key;
     walkScopes(nextPath, ch, acc);
   }
 }
 
 /** Flattens the schema into a list of completion scopes (root + every command path). */
-export function collectScopes(schema: CliCommand): ScopeRec[] {
+export function collectScopes(schema: CliRouter): ScopeRec[] {
   const acc: ScopeRec[] = [];
   acc.push({
     kids: schema.commands ?? [],

package/src/capabilities.ts

@@ -0,0 +1,32 @@
+/*
+Internal capability resolver — decides which platform builtins are active for a program.
+Not exported from the public package barrel.
+*/
+
+import type { CliProgram } from "./types.ts";
+import { isCompiledExecutable } from "./install/compiled.ts";
+
+/** Platform builtins derived from program config and runtime. */
+export interface CliCapabilities {
+  completion: true;
+  mcp: boolean;
+  install: boolean;
+}
+
+/** Resolves which capabilities are enabled for a program. */
+export function resolveCapabilities(program: CliProgram): CliCapabilities {
+  return {
+    completion: true,
+    mcp: program.mcpServer !== undefined,
+    install: isCompiledExecutable() && program.install?.enabled !== false,
+  };
+}
+
+/** Reserved top-level command names for the given capabilities. */
+export function reservedCommandNames(caps: CliCapabilities): string[] {
+  const names = ["completion", "install"];
+  if (caps.mcp) {
+    names.push("mcp");
+  }
+  return names;
+}

package/src/context.ts

@@ -7,7 +7,8 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
-import type { CliCommand, CliInvocation } from "./types.ts";
+import type { CliInvocation, CliNode, CliProgram } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /**
@@ -17,24 +18,24 @@ export class CliContext {
   readonly appName: string;
   readonly commandPath: string[];
   readonly args: string[];
-  readonly schema: CliCommand;
+  readonly program: CliProgram;
   readonly opts: Record<string, string>;
   readonly invocation: CliInvocation;
 
-  /** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
+  /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
     appName: string,
     commandPath: string[],
     args: string[],
     opts: Record<string, string>,
-    schema: CliCommand,
+    program: CliProgram,
     invocation: CliInvocation = "cli",
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
     this.args = args;
     this.opts = opts;
-    this.schema = schema;
+    this.program = program;
     this.invocation = invocation;
   }
 
@@ -79,9 +80,13 @@ export class CliContext {
   private _positionalMap(): Record<string, string | string[]> {
     if (this._posMap) return this._posMap;
 
-    let node: CliCommand = this.schema;
+    let node: CliNode = this.program;
     for (const seg of this.commandPath) {
-      const child = (node.commands ?? []).find((c) => c.key === seg);
+      if (!isCliRouter(node)) {
+        this._posMap = {};
+        return {};
+      }
+      const child = node.commands.find((c) => c.key === seg);
       if (!child) {
         this._posMap = {};
         return {};
@@ -89,6 +94,11 @@ export class CliContext {
       node = child;
     }
 
+    if (!isCliLeaf(node)) {
+      this._posMap = {};
+      return {};
+    }
+
     const map: Record<string, string | string[]> = {};
     let argIdx = 0;
     for (const p of node.positionals ?? []) {

package/src/help.ts

@@ -7,7 +7,7 @@ It keeps help formatting shared across help and error paths so users see one con
 style no matter how help is reached.
 */
 
-import { CliCommand, CliOption, CliOptionKind, CliPositional } from "./types.ts";
+import { CliNode, CliOption, CliOptionKind, CliPositional, CliRouter, isCliLeaf, isCliRouter } from "./types.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
@@ -369,7 +369,7 @@ function rowsForPositionals(defs: CliPositional[], color: boolean): HelpRow[] {
 }
 
 /** Table rows for subcommands, sorted by key. */
-function rowsForSubcommands(cmds: CliCommand[]): HelpRow[] {
+function rowsForSubcommands(cmds: CliNode[]): HelpRow[] {
   return cmds
     .sort((a, b) => a.key.localeCompare(b.key))
     .map((c) => ({ label: c.key, description: c.description }));
@@ -381,7 +381,7 @@ function rowsForSubcommands(cmds: CliCommand[]): HelpRow[] {
  * Renders full help for the app root or a nested command, following `helpPath` from the root key.
  * `useStderr` is reserved for call-site consistency; width and color use stdout TTY.
  */
-export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr: boolean): string {
+export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr: boolean): string {
   const hw = getHelpWidth();
   const color = isStdoutTTY();
 
@@ -416,14 +416,14 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
   }
 
   let layer = schema.commands ?? [];
-  let node: CliCommand | undefined;
+  let node: CliNode | undefined;
   for (const seg of helpPath) {
-    const ch = layer.find((c) => c.key === seg);
+    const ch = layer.find((c: CliNode) => c.key === seg);
     if (!ch) {
       return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
     }
     node = ch;
-    layer = ch.commands ?? [];
+    layer = isCliRouter(ch) ? ch.commands : [];
   }
   if (!node) {
     return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
@@ -438,7 +438,13 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
   lines.push(
     renderTextBox(
       "Usage",
-      usageLines(schema.key, helpPath, (node.commands ?? []).length > 0, (node.positionals ?? []).length > 0, color),
+      usageLines(
+        schema.key,
+        helpPath,
+        isCliRouter(node) && node.commands.length > 0,
+        isCliLeaf(node) && (node.positionals ?? []).length > 0,
+        color,
+      ),
       hw,
       color,
     ).join("\n"),
@@ -450,13 +456,19 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
     lines.push(optBox.join("\n"));
   }
 
-  const posBox = renderTableBox("Arguments", rowsForPositionals(node.positionals ?? [], color), hw, color);
+  const posBox = renderTableBox(
+    "Arguments",
+    rowsForPositionals(isCliLeaf(node) ? (node.positionals ?? []) : [], color),
+    hw,
+    color,
+  );
   if (posBox.length > 0) {
     lines.push("");
     lines.push(posBox.join("\n"));
   }
 
-  const subBox = renderTableBox("Subcommands", rowsForSubcommands(node.commands ?? []), hw, color);
+  const subcmds = isCliRouter(node) ? node.commands : [];
+  const subBox = renderTableBox("Subcommands", rowsForSubcommands(subcmds), hw, color);
   if (subBox.length > 0) {
     lines.push("");
     lines.push(subBox.join("\n"));