argsbarg 1.4.2 → 1.5.0

package/src/runtime.ts

@@ -1,24 +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 { cliBuiltinCompletionGroup, cliBuiltinMcpCommand, 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 { 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;
@@ -26,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);
@@ -44,29 +31,27 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  let parseRoot = root;
-  let isLeafCompletionIntercept = false;
+  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);
+  }
 
-  if (root.handler && argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
-    process.stderr.write("Unknown command: mcp\n");
+  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);
   }
 
-  // Intercept completion for Leaf roots (since they can't natively have a completion subcommand)
-  // but wrap them in a dummy router so that the parser handles `-h` and errors correctly.
-  if (root.handler && argv.length >= 1 && argv[0] === "completion") {
-    isLeafCompletionIntercept = true;
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinCompletionGroup(root.key)],
-    } as any;
-  } else if (root.handler && argv.length >= 1 && argv[0] === "mcp" && root.mcpServer) {
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinMcpCommand()],
-    } as CliCommand;
+  let parseRoot: CliCommand;
+  let isLeafCompletionIntercept = false;
+
+  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);
   }
@@ -92,33 +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] === "mcp") {
-    if (!root.mcpServer) {
-      process.stderr.write("Internal error: mcp not enabled.\n");
-      process.exit(1);
-    }
-    if (pr.path.length !== 1) {
-      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
-      process.exit(1);
-    }
-    await cliMcpServeStdio(root);
+  if (pr.kind === ParseKind.Ok) {
+    await dispatchBuiltin(root, pr, { isLeafCompletionIntercept, parseRoot });
   }
 
   let current = parseRoot;
@@ -148,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

@@ -0,0 +1,183 @@
+/*
+This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
+*/
+
+import { collectOptionDefs } from "../parse.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
+import { CliCommand, CliOptionKind } from "../types.ts";
+
+export type SkillTarget = "cursor" | "claude";
+
+export interface SkillBundle {
+  dirName: string;
+  skillMd: string;
+  referenceMd: string;
+}
+
+/** Truncates text to maxLen with ellipsis. */
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "…";
+}
+
+/** Builds third-person skill description for YAML frontmatter. */
+function skillDescription(root: CliCommand): 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(", ");
+  const more = paths.length > 5 ? `, and ${paths.length - 5} more` : "";
+  const desc = `Operates the ${root.key} CLI (${sample}${more}). Use when the user mentions ${root.key}${paths.length > 0 ? `, ${paths.slice(0, 3).join(", ")}` : ""}, or related tasks.`;
+  return truncate(desc, 1024);
+}
+
+/** Formats one command line for the catalog section. */
+function formatCommandEntry(root: CliCommand, 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);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
+  for (const e of enums) {
+    line += ` (\`--${e.name}\`: ${e.choices!.join(" | ")})`;
+  }
+  const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
+  if (varargs.length > 0) {
+    line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
+  }
+  return line;
+}
+
+/** Builds SKILL.md body for the given target. */
+function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): string {
+  const name = sanitizeToolSegment(root.key);
+  const description = skillDescription(root);
+  const tools = collectMcpTools(root);
+
+  const lines: string[] = [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "---",
+    "",
+    `# ${root.key}`,
+    "",
+    root.description,
+    "",
+    "## When to use",
+    "",
+    `Use this skill when working with **${root.key}** — shell commands, automation, or agent tool calls for this application.`,
+    "",
+    "## Execution",
+    "",
+  ];
+
+  if (root.mcpServer !== undefined) {
+    lines.push(
+      "**Prefer MCP** when a host has the server connected:",
+      "",
+      "```bash",
+      `${root.key} mcp`,
+      "```",
+      "",
+      "Example Cursor `mcp.json` entry:",
+      "",
+      "```json",
+      JSON.stringify(
+        {
+          mcpServers: {
+            [root.mcpServer.name ?? root.key]: {
+              command: root.key,
+              args: ["mcp"],
+            },
+          },
+        },
+        null,
+        2,
+      ),
+      "```",
+      "",
+      "When MCP tools are available, use `tools/call` with flat JSON arguments. Read the schema resource for full shapes.",
+      "",
+      "Otherwise invoke via shell:",
+      "",
+    );
+  } else {
+    lines.push("Invoke via shell:", "");
+  }
+
+  lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## Commands", "");
+
+  if (tools.length === 0) {
+    lines.push("(No leaf commands in schema.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatCommandEntry(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Pitfalls",
+    "",
+    "- Use `--` before tokens that look like flags when they are positional arguments.",
+    "- Under MCP (`ctx.invocation === \"mcp\"`), child processes must not inherit stdout — use piped stdout.",
+    "- Required environment variables are listed per command in descriptions (`requires env`).",
+    "",
+    "## Reference",
+    "",
+    "See `reference.md` in this skill directory for the full `--schema` JSON export.",
+    "",
+  );
+
+  if (target === "cursor") {
+    lines.push(
+      "## Cursor install location",
+      "",
+      `- Project: \`.cursor/skills/${dirName}/\``,
+      `- Global: \`~/.cursor/skills/${dirName}/\``,
+      "",
+      "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
+      "",
+    );
+  } else {
+    lines.push(
+      "## Claude Code",
+      "",
+      `- Invoke with \`/${dirName}\` or let Claude auto-match from the description.`,
+      `- Project skills: \`.claude/skills/${dirName}/\``,
+      `- Global skills: \`~/.claude/skills/${dirName}/\``,
+      `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
+      "",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Builds reference.md with pretty-printed schema JSON. */
+function buildReferenceMd(root: CliCommand): string {
+  return [
+    `# ${root.key} — CLI reference`,
+    "",
+    "Generated from the program `--schema` export. Handlers and runtime-only nodes are omitted.",
+    "",
+    "```json",
+    cliSchemaJson(root).trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+/** Generates SKILL.md and reference.md for Cursor or Claude Code. */
+export function generateSkillBundle(root: CliCommand, target: SkillTarget): SkillBundle {
+  const dirName = sanitizeToolSegment(root.key);
+  return {
+    dirName,
+    skillMd: buildSkillMd(root, target, dirName),
+    referenceMd: buildReferenceMd(root),
+  };
+}

package/src/skill/install.ts

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliCommand } from "../types.ts";
+import { generateSkillBundle, type SkillTarget } from "./generate.ts";
+
+export interface SkillInstallOpts {
+  global?: boolean;
+  /** When true, remove an existing skill directory before writing. */
+  rimraf?: boolean;
+  /** When true, skip writes but return paths that would change. */
+  dry?: boolean;
+}
+
+function userHome(): string {
+  return process.env.HOME ?? homedir();
+}
+
+function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
+  const base = global
+    ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")
+    : join(process.cwd(), target === "cursor" ? ".cursor" : ".claude", "skills");
+  return join(base, dirName);
+}
+
+/** 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 (opts.rimraf && existsSync(dir) && !opts.dry) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  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");
+  }
+
+  changed.push(skillPath, refPath);
+  return changed;
+}

package/src/types.ts

@@ -153,6 +153,16 @@ export interface CliMcpToolConfig {
   requiresEnv?: string[];
 }
 
+/**
+ * Root-only. Opt-out and defaults for the `install` built-in (compiled binaries only).
+ */
+export interface CliInstallConfig {
+  /** When `false`, hide/disable `install` (default: enabled). */
+  enabled?: boolean;
+  /** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
+  prefix?: string;
+}
+
 /**
  * Base properties shared by all command nodes.
  */
@@ -167,6 +177,8 @@ export interface CliCommandBase {
   options?: CliOption[];
   /** Root-only. When set, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
+  /** 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", "mcp"];
+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,6 +35,12 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
+  if (!isRoot && cmd.install !== undefined) {
+    throw new CliSchemaValidationError(
+      "install is only supported on the program root (not on " + cmd.key + ")",
+    );
+  }
+
   const isLeaf = "handler" in cmd && !!cmd.handler;
   if (!isLeaf && cmd.mcpTool !== undefined) {
     throw new CliSchemaValidationError(
@@ -64,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)) {
@@ -89,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) {
@@ -143,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) {
@@ -162,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;
@@ -173,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) {
@@ -183,7 +178,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     }
   }
 
-  // Recurse into nested commands
   for (const child of cmd.commands ?? []) {
     walkCommand(child, false);
   }