argsbarg 1.4.3 → 1.5.0

package/src/runtime.ts

@@ -1,25 +1,17 @@
 /*
 This module runs parsed commands, help, errors, completion, and leaf handlers.
-It owns the top-level control flow after parsing, including validation failures,
-shell completion dispatch, and leaf handler invocation.
-
-It keeps execution flow out of the public barrel so the exported API stays small and
-the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinAiGroup, cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
+import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
+import { cliPresentationRoot } from "./builtins/presentation.ts";
+import { isCompiledExecutable } from "./install/compiled.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { cliSkillInstall } from "./skill/install.ts";
-import { cliMcpServeStdio } from "./mcp.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { CliCommand } from "./types.ts";
 import { cliValidateRoot } from "./validate.ts";
 
-/**
- * Merges the caller's program root with the reserved `completion` subtree.
- */
 function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
   if (root.handler) {
     return root;
@@ -27,12 +19,6 @@ function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
   return cliPresentationRoot(root);
 }
 
-/**
- * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
- *
- * @param root The root CliCommand.
- * @param argv Override the default argv (process.argv.slice(2)).
- */
 export async function cliRun(root: CliCommand, argv: string[] = process.argv.slice(2)): Promise<never> {
   try {
     cliValidateRoot(root);
@@ -45,27 +31,27 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  if (argv.length >= 2 && argv[0] === "ai" && argv[1] === "mcp" && !root.mcpServer) {
+  if (argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
     process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
     process.exit(1);
   }
 
-  let parseRoot = root;
+  if (argv.length >= 1 && argv[0] === "install" && !isCompiledExecutable()) {
+    process.stderr.write("install is only available in compiled binaries (bun build --compile).\n");
+    process.exit(1);
+  }
+
+  let parseRoot: CliCommand;
   let isLeafCompletionIntercept = false;
 
-  if (root.handler && argv.length >= 1 && argv[0] === "ai") {
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinAiGroup(root)],
-    } as CliCommand;
-  } else if (root.handler && argv.length >= 1 && argv[0] === "completion") {
-    isLeafCompletionIntercept = true;
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinCompletionGroup(root.key)],
-    } as any;
+  if (root.handler) {
+    const intercept = builtinInterceptRoot(root, argv);
+    if (intercept.isLeafCompletionIntercept || intercept.parseRoot !== root) {
+      parseRoot = intercept.parseRoot;
+      isLeafCompletionIntercept = intercept.isLeafCompletionIntercept;
+    } else {
+      parseRoot = root;
+    }
   } else {
     parseRoot = cliRootMergedWithBuiltins(root);
   }
@@ -91,53 +77,8 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  // Leaf roots have an empty path; that's normal.
-
-  if (pr.path[0] === "completion") {
-    // If we intercepted a leaf, we MUST pass the original `root` to generate completions
-    // because `parseRoot` is just a dummy router!
-    const schemaForCompletion = isLeafCompletionIntercept ? root : parseRoot;
-
-    if (pr.path[1] === "bash") {
-      process.stdout.write(completionBashScript(schemaForCompletion));
-      process.exit(0);
-    }
-    if (pr.path[1] === "zsh") {
-      process.stdout.write(completionZshScript(schemaForCompletion));
-      process.exit(0);
-    }
-  }
-
-  if (pr.path[0] === "ai") {
-    if (pr.path[1] === "mcp") {
-      if (!root.mcpServer) {
-        process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
-        process.exit(1);
-      }
-      if (pr.path.length !== 2) {
-        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
-        process.exit(1);
-      }
-      await cliMcpServeStdio(root);
-    } else if (pr.path[1] === "skill" && (pr.path[2] === "cursor" || pr.path[2] === "claude")) {
-      if (root.aiSkill?.enabled === false) {
-        process.stderr.write("AI skills are disabled. Remove aiSkill.enabled: false from the program root.\n");
-        process.exit(1);
-      }
-      if (pr.path.length !== 3) {
-        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
-        process.exit(1);
-      }
-      const msg = cliSkillInstall(root, pr.path[2], {
-        global: pr.opts.global === "1",
-        force: pr.opts.force === "1",
-      });
-      process.stderr.write(msg + "\n");
-      process.exit(0);
-    } else {
-      process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
-      process.exit(1);
-    }
+  if (pr.kind === ParseKind.Ok) {
+    await dispatchBuiltin(root, pr, { isLeafCompletionIntercept, parseRoot });
   }
 
   let current = parseRoot;
@@ -167,13 +108,10 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   }
 }
 
-/**
- * Prints a red error line and contextual help on stderr, then exits with status 1.
- */
 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.exit(1);
-}
+}

package/src/schema.ts

@@ -1,55 +1,12 @@
 /*
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
-It strips handlers and runtime-only nodes so agents can discover commands, options,
-and positionals in one shot.
-
-It keeps schema export aligned with the declarative CliCommand model that drives help
-and completion.
 */
 
-import {
-  CliCommand,
-  CliFallbackMode,
-  CliOption,
-  CliPositional,
-} from "./types.ts";
-import { cliBuiltinCompletionGroup } from "./completion.ts";
-
-/** JSON-safe command node (no handlers). */
-export interface CliSchemaExport {
-  /** Program or command key. */
-  key: string;
-  /** Short description shown in help. */
-  description: string;
-  /** Additional notes shown in help (supports {app} placeholder). */
-  notes?: string;
-  /** Global or command-level flags/options. */
-  options?: CliOption[];
-  /** Default top-level subcommand (program root only). */
-  fallbackCommand?: string;
-  /** How fallbackCommand is applied (program root only). */
-  fallbackMode?: CliFallbackMode;
-  /** Nested subcommands (routing nodes only). */
-  commands?: CliSchemaExport[];
-  /** Positional argument definitions (leaf nodes only). */
-  positionals?: CliPositional[];
-}
+import { CliCommand } from "./types.ts";
+import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 
-/** JSON-safe export of the reserved `completion` subtree (no handler recursion). */
-function exportBuiltinCompletionGroup(appName: string): CliSchemaExport {
-  const group = cliBuiltinCompletionGroup(appName);
-  return {
-    key: group.key,
-    description: group.description,
-    commands: (group.commands ?? []).map((ch) => ({
-      key: ch.key,
-      description: ch.description,
-      ...((ch.notes ?? "").length > 0 ? { notes: ch.notes } : {}),
-    })),
-  };
-}
+const RESERVED = new Set(["completion", "install", "mcp"]);
 
-/** Converts one `CliCommand` node into a JSON-safe export (handlers omitted). */
 function exportCommand(cmd: CliCommand): CliSchemaExport {
   const out: CliSchemaExport = {
     key: cmd.key,
@@ -68,7 +25,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
-    out.commands = [exportBuiltinCompletionGroup(cmd.key)];
+    out.commands = exportPresentationBuiltins(cmd);
     return out;
   }
 
@@ -79,7 +36,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     out.fallbackMode = cmd.fallbackMode;
   }
 
-  const children = (cmd.commands ?? []).filter((ch) => ch.key !== "completion");
+  const children = (cmd.commands ?? []).filter((ch) => !RESERVED.has(ch.key));
   if (children.length > 0) {
     out.commands = children.map(exportCommand);
   }
@@ -87,7 +44,8 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
   return out;
 }
 
-/** Returns pretty-printed JSON for the full program schema (trailing newline). */
 export function cliSchemaJson(root: CliCommand): string {
   return JSON.stringify(exportCommand(root), null, 2) + "\n";
 }
+
+export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -53,7 +53,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 {
-  const name = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+  const name = sanitizeToolSegment(root.key);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
@@ -80,7 +80,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
       "**Prefer MCP** when a host has the server connected:",
       "",
       "```bash",
-      `${root.key} ai mcp`,
+      `${root.key} mcp`,
       "```",
       "",
       "Example Cursor `mcp.json` entry:",
@@ -91,7 +91,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
           mcpServers: {
             [root.mcpServer.name ?? root.key]: {
               command: root.key,
-              args: ["ai", "mcp"],
+              args: ["mcp"],
             },
           },
         },
@@ -174,7 +174,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 {
-  const dirName = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+  const dirName = sanitizeToolSegment(root.key);
   return {
     dirName,
     skillMd: buildSkillMd(root, target, dirName),

package/src/skill/install.ts

@@ -1,8 +1,4 @@
-/*
-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";
@@ -10,15 +6,16 @@ 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: CliCommand, 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.ts

@@ -90,7 +90,7 @@ export interface CliPositional {
 }
 
 /**
- * Root-only. Enables `myapp ai mcp` and MCP stdio server metadata.
+ * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
  */
 export interface CliMcpServerConfig {
   /** `initialize` serverInfo.name (default: root `key`). */
@@ -154,13 +154,13 @@ export interface CliMcpToolConfig {
 }
 
 /**
- * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ * Root-only. Opt-out and defaults for the `install` built-in (compiled binaries 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;
 }
 
 /**
@@ -175,10 +175,10 @@ export interface CliCommandBase {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
-  /** Root-only. When set, enables the `ai mcp` built-in subcommand. */
+  /** Root-only. When set, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
-  /** Root-only. Opt out of `ai skill` install with `{ enabled: false }`. */
-  aiSkill?: CliAiSkillConfig;
+  /** Root-only. Opt-out and defaults for `install` (compiled binaries only). */
+  install?: CliInstallConfig;
   /** Leaf-only. Per-tool MCP exposure and metadata. */
   mcpTool?: CliMcpToolConfig;
 }

package/src/validate.ts

@@ -1,9 +1,5 @@
 /*
 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 {
@@ -14,26 +10,24 @@ import {
 } from "./types.ts";
 import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
-const reservedCommandNames = ["completion", "ai"];
+function reservedCommandNames(root: CliCommand): string[] {
+  const names = ["completion", "install"];
+  if (root.mcpServer !== undefined) {
+    names.push("mcp");
+  }
+  return names;
+}
 
-/**
- * Validates the static CliCommand tree against ArgBarg rules.
- * Throws CliSchemaValidationError if rules are violated.
- */
 export function cliValidateRoot(root: CliCommand): void {
-
-  // Check for reserved command names at root
   for (const child of root.commands ?? []) {
-    if (reservedCommandNames.includes(child.key)) {
+    if (reservedCommandNames(root).includes(child.key)) {
       throw new CliSchemaValidationError(`Reserved command name: ${child.key}`);
     }
   }
 
-  // Recursively validate
   walkCommand(root, 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(
@@ -41,9 +35,9 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
-  if (!isRoot && cmd.aiSkill !== undefined) {
+  if (!isRoot && cmd.install !== undefined) {
     throw new CliSchemaValidationError(
-      "aiSkill is only supported on the program root (not on " + cmd.key + ")",
+      "install is only supported on the program root (not on " + cmd.key + ")",
     );
   }
 
@@ -70,7 +64,6 @@ 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)) {
@@ -95,7 +88,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // Validate options (short name uniqueness, reserved -h, required presence)
   const seenShorts = new Set<string>();
   for (const opt of cmd.options ?? []) {
     if (opt.required && opt.kind === CliOptionKind.Presence) {
@@ -149,7 +141,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // Validate positionals
   const positionals = cmd.positionals ?? [];
   for (const p of positionals) {
     if (p.argMin !== undefined && p.argMin < 0) {
@@ -168,7 +159,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // Check positional ordering: required before optional
   let sawOptional = false;
   for (const p of positionals) {
     const { argMin = 1 } = p;
@@ -179,7 +169,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // 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) {
@@ -189,7 +178,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // 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";