argsbarg 1.4.1 → 1.4.3

package/src/runtime.ts

@@ -7,9 +7,10 @@ It keeps execution flow out of the public barrel so the exported API stays small
 the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinCompletionGroup, cliBuiltinMcpCommand, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
+import { cliBuiltinAiGroup, cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.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";
@@ -44,29 +45,27 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  let parseRoot = root;
-  let isLeafCompletionIntercept = false;
-
-  if (root.handler && argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
-    process.stderr.write("Unknown command: mcp\n");
+  if (argv.length >= 2 && argv[0] === "ai" && argv[1] === "mcp" && !root.mcpServer) {
+    process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\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;
+  let parseRoot = root;
+  let isLeafCompletionIntercept = false;
+
+  if (root.handler && argv.length >= 1 && argv[0] === "ai") {
     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) {
+      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: [cliBuiltinMcpCommand()],
-    } as CliCommand;
+      commands: [cliBuiltinCompletionGroup(root.key)],
+    } as any;
   } else {
     parseRoot = cliRootMergedWithBuiltins(root);
   }
@@ -109,16 +108,36 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     }
   }
 
-  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");
+  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);
     }
-    await cliMcpServeStdio(root);
   }
 
   let current = parseRoot;

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 = root.aiSkill?.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} ai mcp`,
+      "```",
+      "",
+      "Example Cursor `mcp.json` entry:",
+      "",
+      "```json",
+      JSON.stringify(
+        {
+          mcpServers: {
+            [root.mcpServer.name ?? root.key]: {
+              command: root.key,
+              args: ["ai", "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 = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+  return {
+    dirName,
+    skillMd: buildSkillMd(root, target, dirName),
+    referenceMd: buildReferenceMd(root),
+  };
+}

package/src/skill/install.ts

@@ -0,0 +1,45 @@
+/*
+This module installs generated Agent Skills to Cursor or Claude Code skill directories.
+*/
+
+import { existsSync, mkdirSync, 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;
+  force?: 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")
+    : join(process.cwd(), target === "cursor" ? ".cursor" : ".claude", "skills");
+  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 {
+  const bundle = generateSkillBundle(root, target);
+  const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);
+
+  if (existsSync(dir) && !opts.force) {
+    process.stderr.write(`Skill directory already exists: ${dir}\nUse --force to overwrite.\n`);
+    process.exit(1);
+  }
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), bundle.skillMd, "utf8");
+  writeFileSync(join(dir, "reference.md"), bundle.referenceMd, "utf8");
+
+  const label = target === "cursor" ? "Cursor" : "Claude Code";
+  return `Installed ${label} skill to ${dir}/`;
+}

package/src/types.ts

@@ -28,21 +28,20 @@ export enum CliOptionKind {
 }
 
 /**
- * When fallbackCommand is used for missing or unknown top-level tokens.
- * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
 export enum CliFallbackMode {
   /**
-   * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+   * If argv has no next subcommand, route to `fallbackCommand`; if the token is unknown, error.
    */
   MissingOnly = "missingOnly",
   /**
-   * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+   * If argv has no next subcommand or the token is not a known child, route to `fallbackCommand`.
    */
   MissingOrUnknown = "missingOrUnknown",
   /**
-   * If the first token is present but not a known child, route to `fallbackCommand`.
-   * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+   * If the next token is present but not a known child, route to `fallbackCommand`.
+   * When the subcommand token is missing (exhausted argv), do not use fallback (implicit scoped help).
    */
   UnknownOnly = "unknownOnly",
 }
@@ -91,7 +90,7 @@ export interface CliPositional {
 }
 
 /**
- * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ * Root-only. Enables `myapp ai mcp` and MCP stdio server metadata.
  */
 export interface CliMcpServerConfig {
   /** `initialize` serverInfo.name (default: root `key`). */
@@ -154,6 +153,16 @@ export interface CliMcpToolConfig {
   requiresEnv?: string[];
 }
 
+/**
+ * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ */
+export interface CliAiSkillConfig {
+  /** When `false`, disable `ai skill *` install commands (default: enabled). */
+  enabled?: boolean;
+  /** Skill directory name (default: sanitized root `key`). */
+  name?: string;
+}
+
 /**
  * Base properties shared by all command nodes.
  */
@@ -166,8 +175,10 @@ export interface CliCommandBase {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
-  /** Root-only. When set, enables the `mcp` built-in subcommand. */
+  /** 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;
 }
@@ -186,17 +197,17 @@ export type CliCommand =
       positionals?: CliPositional[];
       /** Nested subcommands (empty for leaf commands). */
       commands?: never;
-      /** Default top-level subcommand (routing commands only). */
+      /** Default subcommand (routing commands only). */
       fallbackCommand?: never;
-      /** How fallbackCommand is applied (routing commands only). */
+      /** How fallbackCommand is applied at this routing node (routing commands only). */
       fallbackMode?: never;
     })
   | (CliCommandBase & {
       /** Nested subcommands. */
       commands: CliCommand[];
-      /** Default top-level subcommand when argv omits a command or uses an unknown first token. */
+      /** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
       fallbackCommand?: string;
-      /** How fallbackCommand is applied. */
+      /** How fallbackCommand is applied at this routing node (not root-only). */
       fallbackMode?: CliFallbackMode;
       /** Handler function (leaf commands only). */
       handler?: never;

package/src/validate.ts

@@ -14,7 +14,7 @@ import {
 } from "./types.ts";
 import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
-const reservedCommandNames = ["completion", "mcp"];
+const reservedCommandNames = ["completion", "ai"];
 
 /**
  * Validates the static CliCommand tree against ArgBarg rules.
@@ -35,25 +35,15 @@ export function cliValidateRoot(root: CliCommand): void {
 
 /** Recursively validates a command node: handlers vs children, options, and positionals. */
 function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
-  // Fallback only on root
-  if (!isRoot && cmd.fallbackCommand !== undefined) {
-    throw new CliSchemaValidationError(
-      "Fallback is only supported on the program root (not on " + cmd.key + ")",
-    );
-  }
-  if (
-    !isRoot &&
-    cmd.fallbackMode !== undefined &&
-    cmd.fallbackMode !== CliFallbackMode.MissingOnly
-  ) {
+  if (!isRoot && cmd.mcpServer !== undefined) {
     throw new CliSchemaValidationError(
-      "fallbackMode may only be set on the program root (not on " + cmd.key + ")",
+      "mcpServer is only supported on the program root (not on " + cmd.key + ")",
     );
   }
 
-  if (!isRoot && cmd.mcpServer !== undefined) {
+  if (!isRoot && cmd.aiSkill !== undefined) {
     throw new CliSchemaValidationError(
-      "mcpServer is only supported on the program root (not on " + cmd.key + ")",
+      "aiSkill is only supported on the program root (not on " + cmd.key + ")",
     );
   }
 
@@ -89,6 +79,22 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     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) {
+      throw new CliSchemaValidationError(
+        `fallbackCommand '${cmd.fallbackCommand}' is not a child of '${cmd.key}'`,
+      );
+    }
+  }
+
   // Validate options (short name uniqueness, reserved -h, required presence)
   const seenShorts = new Set<string>();
   for (const opt of cmd.options ?? []) {