argsbarg 1.4.2 → 1.5.0

package/.private/scratch.md

@@ -1 +1,2 @@
-- [x] --schema feature for ai agents
+- [x] --schema feature for ai agents
+- [x] opt-out install feature?

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-20
+
+### Added
+
+- **`install` built-in** (compiled binaries only) — install binary, bash/zsh/fish completions, Cursor/Claude skills, and MCP config (`install --all --yes`, `--update`, `--status`, `--uninstall`).
+- **`completion fish`** — fish tab-completion script generation.
+- Root **`install`** config (`{ enabled?: boolean, prefix?: string }`).
+
+### Changed (breaking)
+
+- **Removed `ai` command group** — no more `ai mcp` or `ai skill`.
+- **Restored top-level `mcp`** — `myapp mcp` (reserved only when `mcpServer` is set).
+- **Removed `aiSkill` config** — skill directory name defaults to sanitized root `key`; use `install --skill` instead of `ai skill`.
+
+## [1.4.3] - 2026-06-19
+
+### Added
+
+- **`ai` built-in group** — `myapp ai skill cursor` and `myapp ai skill claude` install Agent Skills (`SKILL.md` + `reference.md`) to project or global skill directories.
+- **`aiSkill`** root config to opt out of skill install (`{ enabled: false }`).
+
+### Changed (breaking)
+
+- **`myapp mcp`** → **`myapp ai mcp`**
+- Reserved top-level command **`mcp`** → **`ai`** (user commands may now be named `mcp`)
+
 ## [1.4.2] - 2026-06-19
 
 ### Added
@@ -123,7 +149,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.5.0
+[1.4.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.3
 [1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2
 [1.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.1
 [1.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.0

package/README.md

@@ -14,9 +14,9 @@ Why another CLI parser?
 
 *Beautiful `-h` screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
 
-*Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
+*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
 
-*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md).
+*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Compiled binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -95,11 +95,12 @@ Every app gets:
 
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
-- **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`mcp`** — when `mcpServer: {}` is set on the program root, run an MCP server over stdio (`myapp mcp`).
+- **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `cliRun`).
+- **`mcp`** — when `mcpServer` is set on the program root, run as an MCP stdio server (`myapp mcp`).
+- **`install`** — when running as a compiled binary (`bun build --compile`), install the binary, completions, skills, and MCP config to the user environment (`myapp install --all --yes`). See [docs/install.md](docs/install.md).
 
-Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
-Do not declare a top-level command named **`mcp`** — it is reserved when MCP is enabled.
+Do not declare a top-level command named **`completion`** or **`install`** — they are reserved.
+When **`mcpServer`** is set, do not declare a top-level command named **`mcp`** — it is reserved for the MCP built-in.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
@@ -109,6 +110,18 @@ Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), t
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
+### Install (compiled binaries)
+
+After `bun build --compile`, ship a self-contained binary and let users run:
+
+```bash
+myapp install --all --yes
+```
+
+This copies the binary to `~/.local/bin`, installs shell completions (bash/zsh/fish when each shell is on PATH), writes Cursor/Claude skills when agent directories exist, and merges MCP server entries into Cursor and Claude config files.
+
+See **[docs/install.md](docs/install.md)** for `--update`, `--status`, `--uninstall`, and flags.
+
 
 ### Shell completions
 
@@ -119,6 +132,8 @@ myapp completion bash > ~/.bash_completion.d/myapp
 myapp completion zsh > ~/.zsh/completions/_myapp   
 # then: fpath+=(~/.zsh/completions); autoload -Uz compinit && compinit
 # or, for a one-off test in the current shell: eval "$(myapp completion zsh)"
+
+myapp completion fish > ~/.config/fish/completions/myapp.fish
 ```
 
 
@@ -207,7 +222,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 
-Reserved identifier (validated at startup): root command **`completion`**.
+Reserved identifiers (validated at startup): root commands **`completion`**, **`install`**, and **`mcp`** (only when `mcpServer` is set).
 
 ---
 

package/docs/ai-skills.md

@@ -0,0 +1,47 @@
+# Agent skills
+
+ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
+
+## Install via `install` (recommended)
+
+In a **compiled binary**, install skills to the user environment:
+
+```bash
+myapp install --skill --yes
+# or
+myapp install --all --yes
+```
+
+Skills are written when the agent home exists:
+
+- Cursor: `~/.cursor/skills/<dir>/` when `~/.cursor` exists
+- Claude Code: `~/.claude/skills/<dir>/` when `~/.claude` exists
+
+The skill directory name defaults to the sanitized program `key` (e.g. `minimal.ts` → `minimal_ts`).
+
+Existing skill directories are removed and rewritten on each install.
+
+## Programmatic install
+
+```typescript
+import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
+```
+
+For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true, rimraf: true })` — it returns changed file paths.
+
+## Generated content
+
+- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, command catalog, MCP setup hints
+- **`reference.md`** — full `--schema` JSON export
+
+## MCP vs skills
+
+| Mechanism | Role |
+| --- | --- |
+| **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
+| **`myapp install --skill`** | Static discovery files for agents |
+
+See also:
+
+- [MCP server](mcp.md) — `mcpServer` config and `mcp` protocol
+- [Install](install.md) — binary, completions, skills, and MCP config

package/docs/install.md

@@ -0,0 +1,84 @@
+# Install command
+
+The `install` built-in is available only in **compiled binaries** (`bun build --compile`). It is hidden from help, `--schema`, and shell completions when running via `bun run`.
+
+## Quick start
+
+```bash
+# First-time setup
+myapp install --all --yes
+
+# Refresh after upgrading
+myapp install --update
+
+# See what is installed
+myapp install --status
+
+# Remove everything detected
+myapp install --uninstall --yes
+```
+
+## What gets installed
+
+| Target | Flag | Destination |
+| --- | --- | --- |
+| Binary | `--bin` | `~/.local/bin/<key>` (or `--prefix`) |
+| Bash completion | `--completions` | `~/.bash_completion.d/<key>` + `.bashrc` PATH snippet |
+| Zsh completion | `--completions` | `~/.zsh/completions/_<key>` + `.zshrc` fpath snippet |
+| Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
+| Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
+| Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
+| MCP config | `--mcp` | `~/.cursor/mcp.json` and `~/.claude.json` when MCP is enabled |
+
+`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer` is set).
+
+Shells not on PATH are skipped silently (no warnings).
+
+## Configuration
+
+On the program root:
+
+```typescript
+install: {
+  enabled: false,       // opt out of the install built-in
+  prefix: "~/.local/bin", // default bin directory
+}
+```
+
+Environment:
+
+- `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Skip confirmation (required for non-TTY unless `--json` / `--update`) |
+| `--dry` | Preview changes; per-step messages on stderr with `[dry run]` |
+| `--json` | Machine-readable output on stdout (implies `--yes`) |
+| `--quiet` | Suppress summaries and per-step messages (requires `--yes`) |
+| `--prefix <dir>` | Override binary install directory |
+| `--update` | Update only artifacts already installed (implies `--bin` + `--yes`) |
+| `--status` | Read-only inventory |
+| `--uninstall` | Remove detected artifacts (scope with `--bin`, `--completions`, `--skill`, `--mcp`) |
+
+## MCP merge behavior
+
+When `--mcp` runs, entries are merged into `mcpServers[<name>]` with:
+
+```json
+{ "command": "<root.key>", "args": ["mcp"] }
+```
+
+If an existing entry differs, the command exits with an error unless `--yes` is passed (then it overwrites).
+
+## Opt out
+
+```typescript
+const cli: CliCommand = {
+  key: "myapp",
+  description: "...",
+  install: { enabled: false },
+  // ...
+};
+```

package/docs/mcp.md

@@ -29,6 +29,8 @@ The process reads NDJSON requests from stdin and writes NDJSON responses to stdo
 
 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
@@ -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 **`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
 
@@ -284,7 +286,7 @@ 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`.
 

package/index.d.ts

@@ -165,6 +165,15 @@ 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.
  */
@@ -179,6 +188,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;
 }
@@ -243,16 +254,7 @@ export interface CliInvokeResult {
  * Never calls process.exit.
  */
 export declare function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult>;
-/**
- * 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 declare function cliRun(root: CliCommand, argv?: string[]): Promise<never>;
-/**
- * Prints a red error line and contextual help on stderr, then exits with status 1.
- */
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliPresentationRoot } from "./presentation.ts";
+import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
+import { exportPresentationBuiltins } from "./export.ts";
+import { CliCommand } from "../types.ts";
+import { setCompiledExecutableOverride } from "../install/compiled.ts";
+
+const fixture: CliCommand = {
+  key: "myapp",
+  description: "Demo app.",
+  mcpServer: { name: "myapp" },
+  commands: [
+    {
+      key: "hello",
+      description: "Say hello.",
+      handler: () => {},
+    },
+  ],
+};
+
+afterEach(() => {
+  setCompiledExecutableOverride(null);
+});
+
+describe("builtins help copy", () => {
+  test("install command includes description and option text when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const install = cliBuiltinInstallCommand(fixture);
+    expect(install.description).toContain("Install the binary");
+    expect(install.notes).toContain("bun build --compile");
+    const names = installBuiltinOptions(fixture).map((o) => o.name);
+    expect(names).toContain("all");
+    expect(names).toContain("mcp");
+    expect(names).toContain("prefix");
+  });
+
+  test("install omits --mcp option when mcpServer unset", () => {
+    setCompiledExecutableOverride(true);
+    const noMcp: CliCommand = { key: "x", description: "x", handler: () => {} };
+    const names = installBuiltinOptions(noMcp).map((o) => o.name);
+    expect(names).not.toContain("mcp");
+  });
+
+  test("mcp builtin description is user-facing", () => {
+    const mcp = cliBuiltinMcpCommand();
+    expect(mcp.description).toContain("MCP server");
+    expect(mcp.notes).toContain('["mcp"]');
+  });
+});
+
+describe("presentation root", () => {
+  test("includes mcp when mcpServer set", () => {
+    setCompiledExecutableOverride(false);
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("mcp");
+    expect(root.commands?.map((c) => c.key)).not.toContain("install");
+  });
+
+  test("includes install when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("install");
+  });
+});
+
+describe("completion emitters", () => {
+  test("fish script references app key and subcommands", () => {
+    setCompiledExecutableOverride(true);
+    const schema = cliPresentationRoot(fixture);
+    const fish = completionFishScript(schema);
+    expect(fish).toContain("complete -c myapp");
+    expect(fish).toContain("hello");
+    expect(fish).toContain("install");
+  });
+
+  test("bash script includes install flags when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const schema = cliPresentationRoot(fixture);
+    const bash = completionBashScript(schema);
+    expect(bash).toContain("--all");
+    expect(bash).toContain("install");
+  });
+
+  test("zsh script registers compdef", () => {
+    const schema = cliPresentationRoot({ key: "zapp", description: "z", handler: () => {} });
+    const zsh = completionZshScript(schema);
+    expect(zsh).toContain("#compdef zapp");
+    expect(zsh).toContain("compdef _zapp zapp");
+  });
+});
+
+describe("schema export builtins", () => {
+  test("exportPresentationBuiltins includes install options when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const builtins = exportPresentationBuiltins(fixture);
+    const install = builtins.find((b) => b.key === "install");
+    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("binary");
+  });
+});