argsbarg 1.4.1 → 1.4.3

package/docs/mcp.md

@@ -22,17 +22,19 @@ const cli: CliCommand = {
 2. Run the MCP server:
 
 ```bash
-myapp mcp
+myapp ai mcp
 ```
 
 The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
 
 3. Point your MCP client at that command. See [Client setup](#client-setup).
 
+Optionally install an agent skill for discovery without MCP: see [docs/ai-skills.md](ai-skills.md).
+
 The `examples/nested.ts` demo enables MCP — try:
 
 ```bash
-bun run examples/nested.ts mcp
+bun run examples/nested.ts ai mcp
 ```
 
 ## Client setup
@@ -46,17 +48,17 @@ Add a server entry under `mcpServers` in your Cursor MCP config:
   "mcpServers": {
     "myapp": {
       "command": "bun",
-      "args": ["run", "myapp.ts", "mcp"]
+      "args": ["run", "myapp.ts", "ai", "mcp"]
     }
   }
 }
 ```
 
-Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]` only.
+Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["ai", "mcp"]`.
 
 ### Other MCP hosts
 
-Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** is the subcommand that starts the server.
+Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`ai mcp`** starts the server.
 
 ## Configuration
 
@@ -83,7 +85,7 @@ mcpServer: {
 
 ## Tools
 
-Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `mcp`) are not exposed as tools.
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `ai`) are not exposed as tools.
 
 ### Tool names
 
@@ -138,7 +140,7 @@ mcpTool: {
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
 - **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
-- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. For varargs, agents may also pass a comma-separated string (`"a,b"`) or a single string (`"a"`) — both are coerced to separate argv tokens at dispatch time.
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
 
@@ -275,7 +277,7 @@ Requests without an `id` are treated as notifications and do not receive a respo
 ### Manual smoke test
 
 ```bash
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts ai mcp
 ```
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
@@ -284,11 +286,11 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 When MCP is enabled:
 
-- Do not declare a top-level command named **`mcp`** — it is reserved for the built-in subcommand.
+- Do not declare a top-level command named **`ai`** — it is reserved for the built-in AI integration group.
 - Do not declare a top-level command named **`completion`** — reserved for shell completions.
 - Do not declare an option named **`schema`** — reserved for `--schema`.
 
-Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
+Running `myapp ai mcp` without `mcpServer` on the root fails with an error (exit 1).
 
 ## Design notes
 

package/index.d.ts

@@ -23,6 +23,10 @@ export declare class CliContext {
 	 * This is the TypeScript-native advantage over the Swift version.
 	 */
 	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	private _posMap;
+	private _positionalMap;
 }
 /**
  * How a leaf handler was dispatched.
@@ -42,21 +46,20 @@ export declare enum CliOptionKind {
 	Enum = "enum"
 }
 /**
- * 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 declare 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"
 }
@@ -102,7 +105,7 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * 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`). */
@@ -162,6 +165,15 @@ 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.
  */
@@ -174,8 +186,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;
 }
@@ -192,16 +206,16 @@ export type CliCommand = (CliCommandBase & {
 	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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/ai.ts

@@ -0,0 +1,7 @@
+/*
+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";

package/src/completion.ts

@@ -597,21 +597,62 @@ export function cliPresentationRoot(root: CliCommand): CliCommand {
   } as CliCommand;
 }
 
+/** Presence options for skill install leaves (`--global`, `--force`). */
+function skillInstallOptions(): CliOption[] {
+  return [
+    {
+      name: "global",
+      description: "Install to the user skills directory (~/.cursor/skills or ~/.claude/skills).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "force",
+      description: "Overwrite an existing skill directory.",
+      kind: CliOptionKind.Presence,
+    },
+  ];
+}
+
 /** Built-in commands shown in help and merged for routing CLIs. */
 function presentationBuiltins(root: CliCommand): CliCommand[] {
-  const cmds: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
+  return [cliBuiltinCompletionGroup(root.key), cliBuiltinAiGroup(root)];
+}
+
+/** Builds the `ai` built-in command group (MCP + skill install). */
+export function cliBuiltinAiGroup(root: CliCommand): CliCommand {
+  const aiChildren: CliCommand[] = [
+    {
+      key: "skill",
+      description: "Install agent skill files for Cursor or Claude Code.",
+      commands: [
+        {
+          key: "cursor",
+          description: "Install Cursor skill (SKILL.md + reference.md).",
+          options: skillInstallOptions(),
+          handler: () => {},
+        },
+        {
+          key: "claude",
+          description: "Install Claude Code skill (SKILL.md + reference.md).",
+          options: skillInstallOptions(),
+          handler: () => {},
+        },
+      ],
+    },
+  ];
+
   if (root.mcpServer !== undefined) {
-    cmds.push(cliBuiltinMcpCommand());
+    aiChildren.unshift({
+      key: "mcp",
+      description: "Run as an MCP server over stdio (for AI agents).",
+      handler: () => {},
+    });
   }
-  return cmds;
-}
 
-/** Builds the static `mcp` leaf command (merged when `root.mcpServer` is set). */
-export function cliBuiltinMcpCommand(): CliCommand {
   return {
-    key: "mcp",
-    description: "Run as an MCP server over stdio (for AI agents).",
-    handler: () => {},
+    key: "ai",
+    description: "AI agent integration (MCP server and skill install).",
+    commands: aiChildren,
   };
 }
 

package/src/context.ts

@@ -68,4 +68,42 @@ export class CliContext {
       return null;
     }
   }
+
+  /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+  positional(name: string): string | string[] | undefined {
+    return this._positionalMap()[name];
+  }
+
+  private _posMap: Record<string, string | string[]> | undefined;
+
+  private _positionalMap(): Record<string, string | string[]> {
+    if (this._posMap) return this._posMap;
+
+    let node: CliCommand = this.schema;
+    for (const seg of this.commandPath) {
+      const child = (node.commands ?? []).find((c) => c.key === seg);
+      if (!child) {
+        this._posMap = {};
+        return {};
+      }
+      node = child;
+    }
+
+    const map: Record<string, string | string[]> = {};
+    let argIdx = 0;
+    for (const p of node.positionals ?? []) {
+      const { argMax = 1 } = p;
+      if (argMax === 0) {
+        map[p.name] = this.args.slice(argIdx);
+        argIdx = this.args.length;
+      } else {
+        const val = this.args[argIdx];
+        if (val !== undefined) map[p.name] = val;
+        argIdx++;
+      }
+    }
+
+    this._posMap = map;
+    return map;
+  }
 }