argsbarg 1.4.3 → 1.5.0

package/.private/scratch.md

@@ -1,2 +1,2 @@
 - [x] --schema feature for ai agents
-- [ ] auto-generate/install a cursor skill  format for ~/.cursor/skills?
+- [x] opt-out install feature?

package/CHANGELOG.md

@@ -7,6 +7,20 @@ 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
@@ -135,7 +149,8 @@ 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.3...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

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 ai mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Install Cursor/Claude skills with `myapp ai skill cursor|claude` — see [docs/ai-skills.md](docs/ai-skills.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,30 +95,32 @@ 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`).
-- **`ai`** — AI agent integration: `ai mcp` (when `mcpServer` is set), `ai skill cursor`, `ai skill claude` (install agent skills; opt out with `aiSkill: { enabled: false }`).
+- **`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 **`ai`** — it is reserved for this built-in.
+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`.
 
 
 ### MCP (AI agents)
 
-Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp ai mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
-### Agent skills
+### Install (compiled binaries)
 
-Install Cursor or Claude Code skills (command catalog + schema reference) with:
+After `bun build --compile`, ship a self-contained binary and let users run:
 
 ```bash
-myapp ai skill cursor          # .cursor/skills/<name>/
-myapp ai skill claude --global # ~/.claude/skills/<name>/
+myapp install --all --yes
 ```
 
-See **[docs/ai-skills.md](docs/ai-skills.md)** for opt-out, flags, and file layout.
+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
@@ -130,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
 ```
 
 
@@ -218,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

@@ -1,75 +1,47 @@
-# Agent skills install
+# Agent skills
 
-ArgsBarg can install [Agent Skills](https://code.claude.com/docs/en/skills) content for **Cursor** and **Claude Code** from your CLI schema. Each install writes two files:
+ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
 
-| File | Purpose |
-| --- | --- |
-| `SKILL.md` | Frontmatter + command catalog, execution notes, pitfalls |
-| `reference.md` | Full `--schema` JSON export |
-
-Skills are **install-only** — there is no print-to-stdout mode, because the artifact is always a two-file directory.
+## Install via `install` (recommended)
 
-## Quick start
+In a **compiled binary**, install skills to the user environment:
 
 ```bash
-# Project skill (commit .cursor/skills/ with your repo)
-myapp ai skill cursor
-
-# User-wide Claude Code skill
-myapp ai skill claude --global
+myapp install --skill --yes
+# or
+myapp install --all --yes
 ```
 
-On success, one line is printed to **stderr** with the install path (not the skill body).
+Skills are written when the agent home exists:
 
-## Opt-out
+- Cursor: `~/.cursor/skills/<dir>/` when `~/.cursor` exists
+- Claude Code: `~/.claude/skills/<dir>/` when `~/.claude` exists
 
-Skill install is **enabled by default**. Opt out on the program root:
+The skill directory name defaults to the sanitized program `key` (e.g. `minimal.ts` → `minimal_ts`).
 
-```typescript
-const cli: CliCommand = {
-  key: "myapp",
-  description: "My app.",
-  aiSkill: { enabled: false },
-  commands: [/* ... */],
-};
-```
+Existing skill directories are removed and rewritten on each install.
 
-Optional custom skill directory name:
+## Programmatic install
 
 ```typescript
-aiSkill: { name: "my-custom-skill" },
+import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
 ```
 
-## Flags
+For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true, rimraf: true })` — it returns changed file paths.
 
-Available on `ai skill cursor` and `ai skill claude`:
+## Generated content
 
-| Flag | Effect |
-| --- | --- |
-| `--global` | Install under the user skills directory instead of the project |
-| `--force` | Overwrite an existing skill directory |
-
-## Install locations
-
-| Target | Project (default) | `--global` |
-| --- | --- | --- |
-| Cursor | `.cursor/skills/<name>/` | `~/.cursor/skills/<name>/` |
-| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
-
-`<name>` defaults to the sanitized program root `key` (same rules as MCP tool name segments).
-
-Do **not** install under `~/.cursor/skills-cursor/` — that path is reserved for Cursor built-ins.
+- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, command catalog, MCP setup hints
+- **`reference.md`** — full `--schema` JSON export
 
 ## MCP vs skills
 
-| Mechanism | Purpose |
+| Mechanism | Role |
 | --- | --- |
-| **`myapp ai mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp ai skill cursor\|claude`** | Static discovery and conventions for agents |
-
-Generated `SKILL.md` recommends MCP when `mcpServer` is configured, and documents shell invocation as a fallback.
+| **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
+| **`myapp install --skill`** | Static discovery files for agents |
 
-## Related
+See also:
 
-- [MCP server](mcp.md) — `mcpServer` config and `ai mcp` protocol
-- [README built-ins](../README.md#built-ins) — reserved command `ai`
+- [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

@@ -22,7 +22,7 @@ const cli: CliCommand = {
 2. Run the MCP server:
 
 ```bash
-myapp ai mcp
+myapp mcp
 ```
 
 The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
@@ -34,7 +34,7 @@ Optionally install an agent skill for discovery without MCP: see [docs/ai-skills
 The `examples/nested.ts` demo enables MCP — try:
 
 ```bash
-bun run examples/nested.ts ai mcp
+bun run examples/nested.ts mcp
 ```
 
 ## Client setup
@@ -58,7 +58,7 @@ Use your real binary or script path. For a compiled CLI, `command` can be the in
 
 ### Other MCP hosts
 
-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.
+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
 
@@ -277,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 ai mcp
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
 ```
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
@@ -290,7 +290,7 @@ When MCP is enabled:
 - 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 ai mcp` without `mcpServer` on the root fails with an error (exit 1).
+Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
 
 ## Design notes
 

package/index.d.ts

@@ -105,7 +105,7 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * 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`). */
@@ -166,13 +166,13 @@ export interface CliMcpToolConfig {
 	requiresEnv?: string[];
 }
 /**
- * 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;
 }
 /**
  * Base properties shared by all command nodes.
@@ -186,10 +186,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;
 }
@@ -254,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.3",
+  "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");
+  });
+});