argsbarg 1.4.3 → 2.0.0

package/src/skill/install.ts

@@ -1,24 +1,21 @@
-/*
-This module installs generated Agent Skills to Cursor or Claude Code skill directories.
-*/
-
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+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 {
   global?: boolean;
-  force?: boolean;
+  /** When true, remove an existing skill directory before writing. */
+  rimraf?: boolean;
+  /** When true, skip writes but return paths that would change. */
+  dry?: boolean;
 }
 
-/** Resolves the user home directory (`$HOME` when set). */
 function userHome(): string {
   return process.env.HOME ?? homedir();
 }
 
-/** Resolves the install directory for a skill target. */
 function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
   const base = global
     ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")
@@ -26,20 +23,25 @@ function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean):
   return join(base, dirName);
 }
 
-/** Writes SKILL.md and reference.md to the target skills directory. */
-export function cliSkillInstall(root: CliCommand, target: SkillTarget, opts: SkillInstallOpts): string {
+/** Writes SKILL.md and reference.md; returns changed file paths. */
+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[] = [];
 
-  if (existsSync(dir) && !opts.force) {
-    process.stderr.write(`Skill directory already exists: ${dir}\nUse --force to overwrite.\n`);
-    process.exit(1);
+  if (opts.rimraf && existsSync(dir) && !opts.dry) {
+    rmSync(dir, { recursive: true, force: true });
   }
 
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "SKILL.md"), bundle.skillMd, "utf8");
-  writeFileSync(join(dir, "reference.md"), bundle.referenceMd, "utf8");
+  const skillPath = join(dir, "SKILL.md");
+  const refPath = join(dir, "reference.md");
+
+  if (!opts.dry) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(skillPath, bundle.skillMd, "utf8");
+    writeFileSync(refPath, bundle.referenceMd, "utf8");
+  }
 
-  const label = target === "cursor" ? "Cursor" : "Claude Code";
-  return `Installed ${label} skill to ${dir}/`;
+  changed.push(skillPath, refPath);
+  return changed;
 }

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 ai 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,19 +152,19 @@ export interface CliMcpToolConfig {
 }
 
 /**
- * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ * Opt-out and defaults for the `install` built-in (compiled binaries only; program root only).
  */
-export interface CliAiSkillConfig {
-  /** When `false`, disable `ai skill *` install commands (default: enabled). */
+export interface CliInstallConfig {
+  /** When `false`, hide/disable `install` (default: enabled). */
   enabled?: boolean;
-  /** Skill directory name (default: sanitized root `key`). */
-  name?: string;
+  /** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
+  prefix?: string;
 }
 
 /**
- * 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 `ai mcp` built-in subcommand. */
-  mcpServer?: CliMcpServerConfig;
-  /** Root-only. Opt out of `ai skill` install with `{ enabled: false }`. */
-  aiSkill?: CliAiSkillConfig;
-  /** Leaf-only. Per-tool MCP exposure and metadata. */
-  mcpTool?: CliMcpToolConfig;
 }
 
 /**
- * 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;
-    });
+ * 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;
+  /** Opt-out and defaults for `install` (compiled binaries only). */
+  install?: CliInstallConfig;
+};
+
+/** 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";
+}
+
+/** 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

@@ -1,65 +1,69 @@
 /*
 This module validates CLI schemas before execution.
-It checks reserved command names, handler placement, fallback rules, duplicate names,
-and positional ordering before the runtime starts.
-
-It fails early on structural problems so invalid trees never reach parsing or dispatch.
 */
 
+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";
 
-const reservedCommandNames = ["completion", "ai"];
-
-/**
- * Validates the static CliCommand tree against ArgBarg rules.
- * Throws CliSchemaValidationError if rules are violated.
- */
-export function cliValidateRoot(root: CliCommand): void {
+/** Validates a program schema. */
+export function cliValidateProgram(program: CliProgram): void {
+  const caps = resolveCapabilities(program);
+  const reserved = reservedCommandNames(caps);
 
-  // Check for reserved command names at root
-  for (const child of root.commands ?? []) {
-    if (reservedCommandNames.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}`);
+      }
     }
   }
 
-  // Recursively validate
-  walkCommand(root, true);
+  walkNode(program, program, true);
 }
 
-/** Recursively validates a command node: handlers vs children, options, and positionals. */
-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.aiSkill !== undefined) {
-    throw new CliSchemaValidationError(
-      "aiSkill 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`,
@@ -70,55 +74,64 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // Check for duplicate child names
-  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);
+    }
   }
 
-  // Validate options (short name uniqueness, reserved -h, required presence)
+  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);
@@ -127,70 +140,63 @@ 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`,
       );
     }
   }
+}
 
-  // Validate positionals
-  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}`,
       );
     }
   }
 
-  // Check positional ordering: required before optional
   let sawOptional = false;
   for (const p of positionals) {
     const { argMin = 1 } = p;
     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}`);
     }
   }
 
-  // Check unlimited positional must be last
   for (let idx = 0; idx < positionals.length; idx++) {
     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}`,
       );
     }
   }
-
-  // Recurse into nested commands
-  for (const child of cmd.commands ?? []) {
-    walkCommand(child, false);
-  }
 }

package/src/ai.ts

@@ -1,7 +0,0 @@
-/*
-This module re-exports AI agent integration entry points (skill install).
-MCP stdio serving remains in mcp.ts.
-*/
-
-export { cliSkillInstall, type SkillInstallOpts } from "./skill/install.ts";
-export { generateSkillBundle, type SkillBundle, type SkillTarget } from "./skill/generate.ts";