argsbarg 1.5.0 → 2.0.0

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. */

package/src/validate.ts

@@ -2,58 +2,68 @@
 This module validates CLI schemas before execution.
 */
 
+import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
 import {
-  CliCommand,
-  CliFallbackMode,
+  type CliLeaf,
+  type CliNode,
+  type CliProgram,
   CliOptionKind,
   CliSchemaValidationError,
+  isCliLeaf,
+  isCliRouter,
 } from "./types.ts";
 import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
-function reservedCommandNames(root: CliCommand): string[] {
-  const names = ["completion", "install"];
-  if (root.mcpServer !== undefined) {
-    names.push("mcp");
-  }
-  return names;
-}
+/** Validates a program schema. */
+export function cliValidateProgram(program: CliProgram): void {
+  const caps = resolveCapabilities(program);
+  const reserved = reservedCommandNames(caps);
 
-export function cliValidateRoot(root: CliCommand): void {
-  for (const child of root.commands ?? []) {
-    if (reservedCommandNames(root).includes(child.key)) {
-      throw new CliSchemaValidationError(`Reserved command name: ${child.key}`);
+  if (isCliRouter(program)) {
+    for (const child of program.commands) {
+      if (reserved.includes(child.key)) {
+        throw new CliSchemaValidationError(`Reserved command name: ${child.key}`);
+      }
     }
   }
 
-  walkCommand(root, true);
+  walkNode(program, program, true);
 }
 
-function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
-  if (!isRoot && cmd.mcpServer !== undefined) {
-    throw new CliSchemaValidationError(
-      "mcpServer is only supported on the program root (not on " + cmd.key + ")",
-    );
-  }
+/** @deprecated Internal alias — use cliValidateProgram */
+export const cliValidateRoot = cliValidateProgram;
 
-  if (!isRoot && cmd.install !== undefined) {
-    throw new CliSchemaValidationError(
-      "install is only supported on the program root (not on " + cmd.key + ")",
-    );
+function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
+  if (!isRoot) {
+    const rogue = node as CliProgram;
+    if (rogue.mcpServer !== undefined) {
+      throw new CliSchemaValidationError(
+        "mcpServer is only supported on the program root (not on " + node.key + ")",
+      );
+    }
+    if (rogue.install !== undefined) {
+      throw new CliSchemaValidationError(
+        "install is only supported on the program root (not on " + node.key + ")",
+      );
+    }
   }
 
-  const isLeaf = "handler" in cmd && !!cmd.handler;
-  if (!isLeaf && cmd.mcpTool !== undefined) {
-    throw new CliSchemaValidationError(
-      "mcpTool is only supported on leaf commands (not on " + cmd.key + ")",
-    );
-  }
-  if (isRoot && cmd.mcpTool !== undefined) {
-    throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
+  if (isCliLeaf(node)) {
+    if (isRoot && node.mcpTool !== undefined) {
+      throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
+    }
+  } else {
+    const rogue = node as unknown as CliLeaf;
+    if (rogue.mcpTool !== undefined) {
+      throw new CliSchemaValidationError(
+        "mcpTool is only supported on leaf commands (not on " + node.key + ")",
+      );
+    }
   }
 
-  if (isRoot && cmd.mcpServer?.resources) {
-    const schemaUri = cmd.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
-    const uris = cmd.mcpServer.resources.map((r) => r.uri);
+  if (isRoot && program.mcpServer?.resources) {
+    const schemaUri = program.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+    const uris = program.mcpServer.resources.map((r) => r.uri);
     if (uris.includes(schemaUri)) {
       throw new CliSchemaValidationError(
         `mcpServer.resources URI '${schemaUri}' conflicts with the built-in schema resource`,
@@ -64,53 +74,64 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  const seenNames = new Set<string>();
-  for (const child of cmd.commands ?? []) {
-    if (seenNames.has(child.key)) {
-      throw new CliSchemaValidationError(`Duplicate command name: ${child.key}`);
+  if (isCliRouter(node)) {
+    const seenNames = new Set<string>();
+    for (const child of node.commands) {
+      if (seenNames.has(child.key)) {
+        throw new CliSchemaValidationError(`Duplicate command name: ${child.key}`);
+      }
+      seenNames.add(child.key);
     }
-    seenNames.add(child.key);
-  }
-
-  if (cmd.fallbackMode !== undefined && cmd.fallbackCommand === undefined) {
-    throw new CliSchemaValidationError(
-      `fallbackMode requires fallbackCommand on '${cmd.key}'`,
-    );
-  }
 
-  if (cmd.fallbackCommand !== undefined) {
-    const children = cmd.commands ?? [];
-    const valid = children.find((c) => c.key === cmd.fallbackCommand);
-    if (!valid) {
+    if (node.fallbackMode !== undefined && node.fallbackCommand === undefined) {
       throw new CliSchemaValidationError(
-        `fallbackCommand '${cmd.fallbackCommand}' is not a child of '${cmd.key}'`,
+        `fallbackMode requires fallbackCommand on '${node.key}'`,
       );
     }
+
+    if (node.fallbackCommand !== undefined) {
+      const valid = node.commands.find((c) => c.key === node.fallbackCommand);
+      if (!valid) {
+        throw new CliSchemaValidationError(
+          `fallbackCommand '${node.fallbackCommand}' is not a child of '${node.key}'`,
+        );
+      }
+    }
+
+    for (const child of node.commands) {
+      walkNode(child, program, false);
+    }
   }
 
+  const positionals = isCliLeaf(node) ? (node.positionals ?? []) : [];
+  validateOptions(node.key, node.options ?? []);
+  validatePositionals(node.key, positionals);
+}
+
+function validateOptions(scopeKey: string, options: import("./types.ts").CliOption[]): void {
   const seenShorts = new Set<string>();
-  for (const opt of cmd.options ?? []) {
+  for (const opt of options) {
     if (opt.required && opt.kind === CliOptionKind.Presence) {
       throw new CliSchemaValidationError(
-        `Presence option cannot be required: ${cmd.key}/${opt.name}`,
+        `Presence option cannot be required: ${scopeKey}/${opt.name}`,
       );
     }
 
     if (opt.name === "schema") {
       throw new CliSchemaValidationError(
-        `Option name "schema" is reserved for --schema: ${cmd.key}/${opt.name}`,
+        `Option name "schema" is reserved for --schema: ${scopeKey}/${opt.name}`,
       );
     }
 
     if (opt.shortName !== undefined) {
       if (opt.shortName === "h") {
         throw new CliSchemaValidationError(
-          `Short alias -h is reserved for help: ${cmd.key}/${opt.name}`,
+          `Short alias -h is reserved for help: ${scopeKey}/${opt.name}`,
         );
       }
       if (seenShorts.has(opt.shortName)) {
         throw new CliSchemaValidationError(
-          `Duplicate short alias -${opt.shortName} in scope ${cmd.key}`,
+          `Duplicate short alias -${opt.shortName} in scope ${scopeKey}`,
         );
       }
       seenShorts.add(opt.shortName);
@@ -119,42 +140,43 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     if (opt.kind === CliOptionKind.Enum) {
       if (!opt.choices || opt.choices.length === 0) {
         throw new CliSchemaValidationError(
-          `Option '${opt.name}' on '${cmd.key}': Enum kind requires non-empty choices`,
+          `Option '${opt.name}' on '${scopeKey}': Enum kind requires non-empty choices`,
         );
       }
       if (new Set(opt.choices).size !== opt.choices.length) {
         throw new CliSchemaValidationError(
-          `Option '${opt.name}' on '${cmd.key}': Enum choices must be distinct`,
+          `Option '${opt.name}' on '${scopeKey}': Enum choices must be distinct`,
         );
       }
       for (const choice of opt.choices) {
         if (choice.length === 0) {
           throw new CliSchemaValidationError(
-            `Option '${opt.name}' on '${cmd.key}': Enum choices must be non-empty strings`,
+            `Option '${opt.name}' on '${scopeKey}': Enum choices must be non-empty strings`,
           );
         }
       }
     } else if (opt.choices !== undefined) {
       throw new CliSchemaValidationError(
-        `Option '${opt.name}' on '${cmd.key}': choices is only valid for Enum kind`,
+        `Option '${opt.name}' on '${scopeKey}': choices is only valid for Enum kind`,
       );
     }
   }
+}
 
-  const positionals = cmd.positionals ?? [];
+function validatePositionals(scopeKey: string, positionals: import("./types.ts").CliPositional[]): void {
   for (const p of positionals) {
     if (p.argMin !== undefined && p.argMin < 0) {
-      throw new CliSchemaValidationError(`argMin must be >= 0 for positional ${cmd.key}/${p.name}`);
+      throw new CliSchemaValidationError(`argMin must be >= 0 for positional ${scopeKey}/${p.name}`);
     }
     if (p.argMax !== undefined && p.argMax < 0) {
       throw new CliSchemaValidationError(
-        `argMax must be >= 0 (use 0 for unlimited) for positional ${cmd.key}/${p.name}`,
+        `argMax must be >= 0 (use 0 for unlimited) for positional ${scopeKey}/${p.name}`,
       );
     }
     const { argMin = 1, argMax = 1 } = p;
     if (argMax > 0 && argMin > argMax) {
       throw new CliSchemaValidationError(
-        `argMin must not exceed argMax for positional ${cmd.key}/${p.name}`,
+        `argMin must not exceed argMax for positional ${scopeKey}/${p.name}`,
       );
     }
   }
@@ -165,7 +187,7 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     if (argMin === 0) {
       sawOptional = true;
     } else if (sawOptional) {
-      throw new CliSchemaValidationError(`Required positional after optional in scope ${cmd.key}`);
+      throw new CliSchemaValidationError(`Required positional after optional in scope ${scopeKey}`);
     }
   }
 
@@ -173,12 +195,8 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     const { argMax = 1 } = positionals[idx]!;
     if (argMax === 0 && idx + 1 < positionals.length) {
       throw new CliSchemaValidationError(
-        `Unlimited positional (argMax == 0) must be last in scope ${cmd.key}`,
+        `Unlimited positional (argMax == 0) must be last in scope ${scopeKey}`,
       );
     }
   }
-
-  for (const child of cmd.commands ?? []) {
-    walkCommand(child, false);
-  }
 }