argsbarg 1.5.0 → 2.0.1

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);
@@ -112,6 +121,6 @@ export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(line + "\n");
-  process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.schema), ctx.commandPath, true));
+  process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.program), ctx.commandPath, true));
   process.exit(1);
 }

package/src/schema.ts

@@ -2,12 +2,12 @@
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
 */
 
-import { CliCommand } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 
 const RESERVED = new Set(["completion", "install", "mcp"]);
 
-function exportCommand(cmd: CliCommand): CliSchemaExport {
+function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -21,11 +21,11 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     out.options = cmd.options;
   }
 
-  if ("handler" in cmd && cmd.handler) {
+  if (isCliLeaf(cmd)) {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
-    out.commands = exportPresentationBuiltins(cmd);
+    out.commands = exportPresentationBuiltins(cmd as CliProgram);
     return out;
   }
 
@@ -36,7 +36,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     out.fallbackMode = cmd.fallbackMode;
   }
 
-  const children = (cmd.commands ?? []).filter((ch) => !RESERVED.has(ch.key));
+  const children = isCliRouter(cmd) ? cmd.commands.filter((ch) => !RESERVED.has(ch.key)) : [];
   if (children.length > 0) {
     out.commands = children.map(exportCommand);
   }
@@ -44,7 +44,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
   return out;
 }
 
-export function cliSchemaJson(root: CliCommand): string {
+export function cliSchemaJson(root: CliProgram): string {
   return JSON.stringify(exportCommand(root), null, 2) + "\n";
 }
 

package/src/skill/generate.ts

@@ -5,7 +5,7 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
-import { CliCommand, CliOptionKind } from "../types.ts";
+import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -22,7 +22,7 @@ function truncate(text: string, maxLen: number): string {
 }
 
 /** Builds third-person skill description for YAML frontmatter. */
-function skillDescription(root: CliCommand): string {
+function skillDescription(root: CliProgram): string {
   const tools = collectMcpTools(root);
   const paths = tools.map((t) => (t.path.length > 0 ? t.path.join(" ") : root.key));
   const sample = paths.slice(0, 5).join(", ");
@@ -32,7 +32,7 @@ function skillDescription(root: CliCommand): string {
 }
 
 /** Formats one command line for the catalog section. */
-function formatCommandEntry(root: CliCommand, tool: ReturnType<typeof collectMcpTools>[number]): string {
+function formatCommandEntry(root: CliProgram, tool: ReturnType<typeof collectMcpTools>[number]): string {
   const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
   let line = `- **\`${cliPath}\`** — ${tool.description}`;
   const opts = collectOptionDefs(root, tool.path);
@@ -52,7 +52,7 @@ function formatCommandEntry(root: CliCommand, tool: ReturnType<typeof collectMcp
 }
 
 /** Builds SKILL.md body for the given target. */
-function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): string {
+function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
   const name = sanitizeToolSegment(root.key);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
@@ -159,7 +159,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
 }
 
 /** Builds reference.md with pretty-printed schema JSON. */
-function buildReferenceMd(root: CliCommand): string {
+function buildReferenceMd(root: CliProgram): string {
   return [
     `# ${root.key} — CLI reference`,
     "",
@@ -173,7 +173,7 @@ function buildReferenceMd(root: CliCommand): string {
 }
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
-export function generateSkillBundle(root: CliCommand, target: SkillTarget): SkillBundle {
+export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
   const dirName = sanitizeToolSegment(root.key);
   return {
     dirName,

package/src/skill/install.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 
 export interface SkillInstallOpts {
@@ -24,7 +24,7 @@ function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean):
 }
 
 /** Writes SKILL.md and reference.md; returns changed file paths. */
-export function cliSkillInstall(root: CliCommand, target: SkillTarget, opts: SkillInstallOpts): string[] {
+export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: SkillInstallOpts): string[] {
   const bundle = generateSkillBundle(root, target);
   const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);
   const changed: string[] = [];

package/src/types.test.ts

@@ -0,0 +1,40 @@
+/*
+Compile-only checks that invalid schema shapes fail type-checking.
+*/
+
+import type { CliLeaf, CliNode, CliProgram, CliRouter } from "./types.ts";
+
+const _routerOnly: CliRouter = {
+  key: "app",
+  description: "",
+  commands: [],
+};
+
+const _leafOnly: CliLeaf = {
+  key: "run",
+  description: "",
+  handler: () => {},
+};
+
+const _program: CliProgram = {
+  key: "app",
+  description: "",
+  mcpServer: {},
+  commands: [],
+};
+
+const _badMcpOnNode = {
+  key: "x",
+  description: "",
+  // @ts-expect-error mcpServer is program-root only
+  mcpServer: {},
+  commands: [],
+} satisfies CliNode;
+
+const _badInstallOnNode = {
+  key: "x",
+  description: "",
+  // @ts-expect-error install is program-root only
+  install: { enabled: false },
+  handler: () => {},
+} satisfies CliNode;

package/src/types.ts

@@ -2,8 +2,6 @@
 This module defines the CLI schema, option kinds, and fallback modes.
 It is the shared declarative model that parsing, validation, help, and completion all
 read from, so the package has one source of truth.
-
-It gives the package one shared model for both library users and internal modules.
 */
 
 import type { CliContext } from "./context.ts";
@@ -47,7 +45,7 @@ export enum CliFallbackMode {
 }
 
 /**
- * A named flag or value option (`--long`, `-short`), listed on `CliCommand.options`.
+ * A named flag or value option (`--long`, `-short`), listed on command `options`.
  */
 export interface CliOption {
   /** Option name (e.g., "name", "verbose"). */
@@ -68,7 +66,7 @@ export interface CliOption {
 }
 
 /**
- * An ordered positional argument slot, listed on `CliCommand.positionals`.
+ * An ordered positional argument slot, listed on leaf `positionals`.
  */
 export interface CliPositional {
   /** Positional name (used in help and error messages). */
@@ -90,7 +88,7 @@ export interface CliPositional {
 }
 
 /**
- * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  */
 export interface CliMcpServerConfig {
   /** `initialize` serverInfo.name (default: root `key`). */
@@ -154,7 +152,7 @@ export interface CliMcpToolConfig {
 }
 
 /**
- * Root-only. Opt-out and defaults for the `install` built-in (compiled binaries only).
+ * Opt-out and defaults for the `install` built-in (compiled binaries only; program root only).
  */
 export interface CliInstallConfig {
   /** When `false`, hide/disable `install` (default: enabled). */
@@ -164,9 +162,9 @@ export interface CliInstallConfig {
 }
 
 /**
- * Base properties shared by all command nodes.
+ * Base properties shared by all nodes in the user command tree.
  */
-export interface CliCommandBase {
+export interface CliNodeBase {
   /** Program or command key (e.g., "myapp", "stat", "owner"). */
   key: string;
   /** Short description shown in help. */
@@ -175,45 +173,57 @@ export interface CliCommandBase {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
-  /** Root-only. When set, enables the `mcp` built-in subcommand. */
+}
+
+/**
+ * A leaf command node with a handler and optional positionals.
+ */
+export type CliLeaf = CliNodeBase & {
+  /** Handler function for leaf commands. */
+  handler: CliHandler;
+  /** Positional argument definitions. */
+  positionals?: CliPositional[];
+  /** Per-tool MCP exposure and metadata. */
+  mcpTool?: CliMcpToolConfig;
+};
+
+/**
+ * A routing command node with nested subcommands.
+ */
+export type CliRouter = CliNodeBase & {
+  /** Nested subcommands. */
+  commands: CliNode[];
+  /** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
+  fallbackCommand?: string;
+  /** How fallbackCommand is applied at this routing node. */
+  fallbackMode?: CliFallbackMode;
+};
+
+/**
+ * A node in the user-defined command tree (router or leaf).
+ */
+export type CliNode = CliLeaf | CliRouter;
+
+/**
+ * Program root passed to `cliRun` / `cliInvoke`.
+ * May be a leaf or router, plus optional program-level MCP and install config.
+ */
+export type CliProgram = CliNode & {
+  /** When set, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
-  /** Root-only. Opt-out and defaults for `install` (compiled binaries only). */
+  /** Opt-out and defaults for `install` (compiled binaries only). */
   install?: CliInstallConfig;
-  /** Leaf-only. Per-tool MCP exposure and metadata. */
-  mcpTool?: CliMcpToolConfig;
+};
+
+/** True when the node is a leaf (has a handler). */
+export function isCliLeaf(node: CliNode): node is CliLeaf {
+  return "handler" in node && typeof node.handler === "function";
 }
 
-/**
- * A command node: either a routing group (has commands) or a leaf (has handler).
- *
- * The value passed to cliRun is the program root: name is the app/binary name.
- * The root may be a routing group or a leaf command.
- */
-export type CliCommand =
-  | (CliCommandBase & {
-      /** Handler function for leaf commands. */
-      handler: CliHandler;
-      /** Positional argument definitions. */
-      positionals?: CliPositional[];
-      /** Nested subcommands (empty for leaf commands). */
-      commands?: never;
-      /** Default subcommand (routing commands only). */
-      fallbackCommand?: never;
-      /** How fallbackCommand is applied at this routing node (routing commands only). */
-      fallbackMode?: never;
-    })
-  | (CliCommandBase & {
-      /** Nested subcommands. */
-      commands: CliCommand[];
-      /** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
-      fallbackCommand?: string;
-      /** How fallbackCommand is applied at this routing node (not root-only). */
-      fallbackMode?: CliFallbackMode;
-      /** Handler function (leaf commands only). */
-      handler?: never;
-      /** Positional argument definitions (leaf commands only). */
-      positionals?: never;
-    });
+/** True when the node is a router (has subcommands). */
+export function isCliRouter(node: CliNode): node is CliRouter {
+  return "commands" in node && Array.isArray(node.commands);
+}
 
 /**
  * Handler closure type for leaf commands.
@@ -222,7 +232,7 @@ export type CliCommand =
 export type CliHandler = (ctx: CliContext) => void | Promise<void>;
 
 /**
- * Error thrown when the static CliCommand tree violates ArgsBarg rules.
+ * Error thrown when the static CLI tree violates ArgsBarg rules.
  */
 export class CliSchemaValidationError extends Error {
   /** Creates a schema validation error with a human-readable rule violation. */