argsbarg 3.3.0 → 3.3.2

package/CHANGELOG.md

@@ -7,14 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.3.0] - 2026-06-21
+## [3.3.2] - 2026-06-21
+
+
+## [3.3.2] - 2026-06-21
+
+### Changed
+
+- **`install --uninstall`** — symmetric with install: requires `--all` or scoped flags; `--uninstall --all` removes everything argsbarg installed; empty scope succeeds without error.
+
+## [3.3.1] - 2026-06-21
 
+### Added
+
+- **`docs/cli-program.md`** — authoring guide for `CliProgram` and leaves (MCP-free defaults); **headless-capable handlers** and **inline schema by default**.
+- **`docs/templates/cursor/rules/cli-program.mdc`** — concise copy-paste Cursor rule for consumer apps.
+
+### Removed
 
-## [3.3.0] - 2026-06-20
+- **`mcpToolSchemaHints`** — redundant with MCP `inputSchema` option descriptions.
+- **`wantsDryRun`** — use `ctx.hasFlag("dry-run")` instead.
+
+## [3.3.0] - 2026-06-21
 
 ### Added
 
-- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsDryRun`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
+- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
 - **`ghReleaseUpdateGetLatest`** — optional `install.updateGetLatest` factory for GitHub releases via `gh`.
 - **`createGhVersionCheck`** — version-check cache, update notices, and background refresh helpers.
 
@@ -234,8 +252,10 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - 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/v3.3.0...HEAD
-[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.2...HEAD
+[3.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.2
+[3.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.2
+[3.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.1
 [3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
 [3.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.2.0
 [3.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.1.0

package/README.md

@@ -110,7 +110,7 @@ When **`docs.enabled`** is `true`, do not declare a top-level command named **`d
 
 Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs 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.
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: copy **`docs/templates/cursor/rules/cli-program.mdc`** to **`.cursor/rules/cli-program.mdc`**).
 
 ### Install
 

package/docs/ai-skills.md

@@ -44,6 +44,8 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | **`myapp install --skill`** | Static shell command catalog for agents |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
+Command catalog lines reuse MCP tool descriptions. See [cli-program.md](cli-program.md).
+
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports

package/docs/cli-program.md

@@ -0,0 +1,209 @@
+# Writing `CliProgram` and leaf commands
+
+ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
+
+## Minimal app (MCP is free)
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "One-line summary of what the CLI does.",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "greet",
+      description: "Greet someone by name.",
+      positionals: [
+        { name: "name", description: "Who to greet.", kind: CliOptionKind.String },
+      ],
+      handler: async (ctx) => { /* ... */ },
+    },
+  ],
+} satisfies CliProgram;
+```
+
+No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` comes from options and positionals.
+
+## Inline schema by default
+
+ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.
+
+**Inline by default:**
+
+```typescript
+{
+  key: "reserve",
+  description: "Reserve a QA environment.",
+  options: [
+    { name: "yes", description: "Skip confirmation; use for non-interactive runs.", kind: CliOptionKind.Presence },
+    { name: "dry-run", description: "Preview without mutating.", kind: CliOptionKind.Presence },
+  ],
+  positionals: [
+    { name: "env", description: "Environment name.", kind: CliOptionKind.String, argMin: 0, argMax: 1 },
+  ],
+  handler: async (ctx) => { /* … */ },
+}
+```
+
+**Extract only when well justified:**
+
+| Extract | When |
+| --- | --- |
+| Shared option objects (`DRY_RUN_OPTION`, `JSON_OPTION`) | Identical flag reused on many leaves |
+| Shared spreads (`...MCP_TOOL_MUTATOR`) | Same `mcpTool` metadata on a family of commands |
+| `commands/<name>/command.tsx` module | Entry file is large; handler/body is substantial (Ink page, headless dispatch) |
+| `docs.topics` text imports | Compile-time markdown bundling — not schema shape |
+
+**Avoid extracting** thin indirection: a file that only re-exports `{ key, description, options }` with no logic, or splitting every leaf into its own module when the handler is a few lines. If extraction does not reduce duplication or file size materially, keep it inline.
+
+When you extract a leaf or router, prefer a **plain exported object** — not a zero-arg wrapper function:
+
+```typescript
+// commands/reserve/command.tsx
+export const reserveCommand = {
+  key: "reserve",
+  description: "Reserve a QA environment.",
+  options: [YES_OPTION, DRY_RUN_OPTION],
+  positionals: [/* … */],
+  handler: async (ctx) => { /* … */ },
+} satisfies CliLeaf;
+```
+
+Use a **parameterized factory** only when the schema truly depends on inputs (e.g. `createUpsertCommand(deps)` for tests or injected config). A `reserveCommand()` that returns a static literal adds indirection without benefit.
+
+**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not.
+
+## Descriptions
+
+Write for **what the command does**, not how the UI works:
+
+- **Good:** `Reserve a QA environment.`
+- **Weak:** `Opens the reservation wizard.`
+
+Option and positional `description` strings appear in `-h`, MCP `inputSchema`, and generated skills — keep them concrete (`Environment name (e.g. qa2).`).
+
+Use root **`notes`** for cross-cutting hints shown in help (install commands, docs topics, VPN requirements).
+
+## Well-known option names
+
+Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h`, MCP `inputSchema`, and generated skills — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
+
+## When to use `mcpTool` (escape hatches only)
+
+**Omit `mcpTool` unless you have a specific reason.**
+
+### Fix the CLI first
+
+Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches:
+
+| Problem | Fix (not `mcpTool`) |
+| --- | --- |
+| Agents don't know which flags to pass | Use standard option names (`yes`, `dry-run`, `json`); improve option `description` strings |
+| MCP calls hang on prompts | Add `--yes` and a headless code path; use `shouldRunHeadlessWithYes` |
+| Help text describes Ink UI | Rewrite leaf `description` as the action ("Reserve an environment.") |
+| MCP needs different args than humans | Expose the same flags; resolve defaults in the handler for both `cli` and `mcp` |
+| Command "doesn't work" over MCP | Branch on `ctx.invocation === "mcp"` in the handler (stdio is the wire) |
+
+### When escape hatches are appropriate
+
+| Field | Use when |
+| --- | --- |
+| `enabled: false` | Command is **genuinely** CLI-only (open browser, Ink-only flow with no scriptable equivalent) |
+| `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
+| `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
+
+Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
+
+If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
+
+## Headless-capable handlers
+
+Simple leaves (read args, print stdout) are already headless — no extra work. **Any handler that might mount Ink, prompt, or open a browser should also implement a scriptable fast path** for:
+
+- **MCP** (`ctx.invocation === "mcp"` — always non-interactive)
+- **Non-TTY CLI** (pipes, CI, `myapp cmd --yes` in a script)
+- **Explicit flags** (`--json`, `--dry-run`)
+
+Use **one headless implementation** for all three; do not fork separate "MCP handlers."
+
+### When to branch
+
+| Command kind | Headless trigger | Helpers |
+| --- | --- | --- |
+| Read / query | MCP, `--json`, or non-TTY | `shouldRunHeadless`, `wantsExplicitJson` |
+| Mutate | MCP with args + `yes`/`dry-run`, or non-TTY with `--yes` | `shouldRunHeadlessWithYes`, `requireYesInNonTty` |
+| Mutate with positionals | Same, but avoid auto-headless on empty argv | `shouldRunHeadlessWithPositionals` |
+
+### Recommended handler shape
+
+**Mutating command** (wizard optional, script path required):
+
+```typescript
+import {
+  requireYesInNonTty,
+  shouldRunHeadlessWithYes,
+} from "argsbarg";
+
+handler: async (ctx) => {
+  const dryRun = ctx.hasFlag("dry-run");
+  const yes = ctx.hasFlag("yes");
+  const env = ctx.args[0];
+
+  requireYesInNonTty(yes, "Example: myapp reserve qa2 --yes", dryRun);
+
+  if (shouldRunHeadlessWithYes(ctx, { yes, hasRequiredArgs: !!env, dryRun })) {
+    const result = await executeReserve({ dryRun, env, yes });
+    process.stdout.write(`${result.message}\n`);
+    return;
+  }
+
+  await renderInteractiveWizard({ env, yes, dryRun });
+};
+```
+
+**Read / query command** (optional `--json`):
+
+```typescript
+import { shouldRunHeadless, wantsExplicitJson } from "argsbarg";
+
+handler: async (ctx) => {
+  const json = ctx.hasFlag("json");
+
+  if (shouldRunHeadless(ctx, json)) {
+    const data = await fetchStatus(ctx.args[0]);
+    if (wantsExplicitJson(ctx, json)) {
+      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatStatusHuman(data));
+    }
+    return;
+  }
+
+  await renderPage(<StatusPage env={ctx.args[0]} />);
+};
+```
+
+### Rules of thumb
+
+1. **Resolvable from flags** — if a human can complete the action with flags, an agent can too (`--env qa2 --yes`). Wizards are optional sugar on TTY.
+2. **`--yes` on mutators** — required for non-TTY CLI scripts; MCP should pass `yes: true` in tool arguments when the schema exposes `yes`.
+3. **Stdout is the contract** — headless paths write results to stdout (or JSON with `--json`); stderr for errors. No Ink on the MCP wire.
+4. **`ctx.invocation === "mcp"`** — use only for wire-specific behavior (pipe child stdout, reject `--watch`, etc.), not to duplicate business logic.
+5. **Hide only when impossible** — `mcpTool.enabled: false` after confirming no headless path exists (browser-only, irreducible streaming).
+
+Basic synchronous handlers do not need this structure — only commands with an interactive branch.
+
+## Reserved names
+
+Do not declare user commands named `completion`, `install`, `mcp`, `version`, `docs`, or `update` at the root — ArgsBarg injects these when configured.
+
+## Cursor rule for consumer repos
+
+Copy `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` to `.cursor/rules/cli-program.mdc` so agents editing your CLI schema follow these conventions.
+
+## See also
+
+- [MCP server](mcp.md) — tools, schema resource, env bootstrapping
+- [Agent skills](ai-skills.md) — `install --skill`
+- [Bundled docs](bundled-docs.md) — `docs` topics and `docs mcp`

package/docs/install.md

@@ -17,8 +17,8 @@ myapp update
 # See what is installed
 myapp install --status
 
-# Remove everything detected
-myapp install --uninstall --yes
+# Remove everything installed with --all
+myapp install --uninstall --all --yes
 ```
 
 ## What gets installed
@@ -33,7 +33,9 @@ myapp install --uninstall --yes
 | 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.enabled` is `true`).
+`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`) for both install and uninstall. Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist).
+
+`install --uninstall` requires the same target flags as install (`--all`, `--bin`, etc.) — bare `--uninstall` alone is an error.
 
 Shells not on PATH are skipped silently (no warnings).
 
@@ -105,7 +107,7 @@ Environment:
 | `--reinstall` | Reinstall artifacts already on disk (implies `--bin` + `--yes`) |
 | `--from <path>` | Binary to copy with `--reinstall` (default: running executable) |
 | `--status` | Read-only inventory |
-| `--uninstall` | Remove detected artifacts (scope with `--bin`, `--completions`, `--skill`, `--mcp`) |
+| `--uninstall` | Remove artifacts in scope (`--all`, `--bin`, `--completions`, `--skill`, `--mcp`); skips targets not installed |
 
 `--update` is accepted as a deprecated alias for `--reinstall`.
 

package/docs/mcp.md

@@ -103,9 +103,9 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash:
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]`.
 
-| CLI path | MCP `description` |
+| CLI path | MCP `description` (example) |
 | --- | --- |
 | `stat owner lookup` | `stat owner lookup — Resolve owner info.` |
 | `read` | `read — Print the first line of each file.` |
@@ -126,6 +126,8 @@ Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/l
 
 Omitted or `enabled: true` exposes the command (default). `mcpTool` is only valid on leaves — not on the program root or routing groups.
 
+**Prefer fixing schema and handlers over `mcpTool` overrides** — standard option names (`yes`, `dry-run`, `json`), headless paths, and clear descriptions usually make MCP work without per-leaf config. See [cli-program.md](cli-program.md).
+
 ### Per-leaf tool metadata
 
 ```typescript
@@ -207,7 +209,9 @@ URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchr
 
 Handlers receive `ctx.invocation`: `"cli"` for normal `cliRun` dispatch, `"mcp"` for MCP `tools/call`.
 
-Use this to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
+MCP is always non-interactive. Commands that can mount Ink or prompts should implement a **headless fast path** (same path as non-TTY CLI with `--yes` / `--json`) — see [cli-program.md — Headless-capable handlers](cli-program.md#headless-capable-handlers).
+
+Use `ctx.invocation` to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
 
 ```typescript
 handler: async (ctx) => {

package/docs/templates/cursor/rules/cli-program.mdc

@@ -0,0 +1,29 @@
+---
+description: Argsbarg CliProgram authoring; copy to .cursor/rules/cli-program.mdc
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+**argsbarg** — `CliProgram` drives help, MCP, and skills. Full guide: `node_modules/argsbarg/docs/cli-program.md`.
+
+## Defaults
+- `mcpServer: { enabled: true }` for MCP; **omit `mcpTool`** unless an escape hatch is required
+- `description` on root, commands, options, and positionals (→ `-h`, MCP `inputSchema`, skills)
+- `satisfies CliProgram`; root: `key`, `version`, `description`
+- Reserved root commands (do not declare): `completion`, `install`, `mcp`, `version`, `docs`, `update`
+
+## Schema
+- **Inline** options, positionals, and handler schema; extract to `export const …Command = { … } satisfies CliLeaf` (or router type) when shared flags, `mcpTool` spreads, or large handlers justify a module — not zero-arg wrapper functions
+- Leaf descriptions: action-oriented, not UI jargon
+- Prefer option names `yes`, `dry-run`, `json` when semantics match; describe non-interactive use on the option
+
+## `mcpTool` (rare)
+Fix schema/handler first — not for missing `--yes`, wrong flag names, or unfinished headless paths.
+Only: `enabled: false` (CLI-only), `requiresEnv`, or irreducible limits (e.g. streaming `--watch`). Comment why if used.
+
+## Headless
+Interactive commands need one fast path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json`.
+- Mutators: `requireYesInNonTty`, `shouldRunHeadlessWithYes`
+- Queries: `shouldRunHeadless`, `wantsExplicitJson`
+- Varargs/positionals: `shouldRunHeadlessWithPositionals`
+- `ctx.invocation === "mcp"` only for subprocess/TTY wire behavior; use argsbarg headless helpers, not raw `isTTY`

package/index.d.ts

@@ -307,8 +307,6 @@ export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 export declare const isInteractiveTty: boolean;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
-/** True when `--dry-run` was passed. */
-export declare function wantsDryRun(hasDryRunFlag: boolean): boolean;
 /** True when `--json` was passed or the handler was invoked via MCP. */
 export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/install.ts

@@ -42,7 +42,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "uninstall",
-      description: "Remove installed artifacts (all detected, or limit with other flags).",
+      description: "Remove installed artifacts (use --all or scoped flags; skips targets not on disk).",
       kind: CliOptionKind.Presence,
     },
     {
@@ -96,8 +96,8 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
       `  {app} update\n\n` +
       "See what is installed:\n" +
       `  {app} install --status\n\n` +
-      "Remove everything:\n" +
-      `  {app} install --uninstall --yes\n\n` +
+      "Remove everything installed with --all:\n" +
+      `  {app} install --uninstall --all --yes\n\n` +
       "Use --dry to preview changes, --json for machine-readable output.",
     options: installBuiltinOptions(root),
     handler: () => {},

package/src/headless.test.ts

@@ -5,15 +5,9 @@ import {
   shouldRunHeadless,
   shouldRunHeadlessWithPositionals,
   shouldRunHeadlessWithYes,
-  wantsDryRun,
   wantsExplicitJson,
 } from "./headless.ts";
 
-test("wantsDryRun detects flag", () => {
-  expect(wantsDryRun(true)).toBe(true);
-  expect(wantsDryRun(false)).toBe(false);
-});
-
 test("wantsExplicitJson includes MCP invocation", () => {
   expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
   expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);

package/src/headless.ts

@@ -4,11 +4,6 @@ import { isInteractiveTty } from "./utils.ts";
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 
-/** True when `--dry-run` was passed. */
-export function wantsDryRun(hasDryRunFlag: boolean): boolean {
-  return hasDryRunFlag;
-}
-
 /** True when `--json` was passed or the handler was invoked via MCP. */
 export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
   return hasJsonFlag || ctx.invocation === "mcp";

package/src/index.ts

@@ -34,7 +34,6 @@ export {
   shouldRunHeadless,
   shouldRunHeadlessWithPositionals,
   shouldRunHeadlessWithYes,
-  wantsDryRun,
   wantsExplicitJson,
 } from "./headless.ts";
 export type { HeadlessContext } from "./headless.ts";

package/src/install/detect-installed.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from "node:fs";
-import { CliProgram } from "../types.ts";
 import { InstallPaths } from "./paths.ts";
 
 export interface InstalledArtifacts {

package/src/install/index.ts

@@ -13,7 +13,7 @@ import { resolveInstallPaths } from "./paths.ts";
 import { installErr, installInfo, installOut, printInstallStatus } from "./status.ts";
 import { buildUninstallPlan, uninstallSkillDir, type UninstallAction } from "./uninstall.ts";
 
-function parseInstallOpts(raw: Record<string, string>): InstallOpts {
+export function parseInstallOpts(raw: Record<string, string>): InstallOpts {
   const flag = (name: string) => raw[name] === "1";
   const reinstall = flag("reinstall") || flag("update");
   return {
@@ -34,7 +34,7 @@ function parseInstallOpts(raw: Record<string, string>): InstallOpts {
   };
 }
 
-function validateOpts(opts: InstallOpts): string | null {
+export function validateInstallOpts(opts: InstallOpts): string | null {
   if (opts.quiet && opts.dry) {
     return "--quiet cannot be combined with --dry.";
   }
@@ -60,10 +60,10 @@ function validateOpts(opts: InstallOpts): string | null {
   ) {
     return "--reinstall cannot be combined with other target flags.";
   }
-  if (opts.uninstall && (opts.all || opts.reinstall || opts.status)) {
-    return "--uninstall cannot be combined with --all, --reinstall, or --status.";
+  if (opts.uninstall && (opts.reinstall || opts.status)) {
+    return "--uninstall cannot be combined with --reinstall or --status.";
   }
-  if (!opts.status && !opts.reinstall && !opts.uninstall) {
+  if (!opts.status && !opts.reinstall) {
     const hasTarget = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp;
     if (!hasTarget) {
       return "Specify at least one target: --all, --bin, --completions, --skill, or --mcp.";
@@ -126,7 +126,7 @@ export async function runInstallMutation(
   rawOpts: Record<string, string>,
 ): Promise<{ changed: string[]; opts: InstallOpts; paths: ReturnType<typeof resolveInstallPaths> }> {
   const opts = parseInstallOpts(rawOpts);
-  const err = validateOpts(opts);
+  const err = validateInstallOpts(opts);
   if (err) {
     throw new Error(err);
   }
@@ -159,7 +159,7 @@ export async function runInstallMutation(
   }
 
   if (actions.length === 0) {
-    throw new Error("Nothing to do.");
+    return { changed: [], opts, paths };
   }
 
   if (!opts.quiet && !opts.json) {
@@ -218,5 +218,3 @@ export async function cliInstall(root: CliProgram, rawOpts: Record<string, strin
 
   process.exit(0);
 }
-
-export { parseInstallOpts };

package/src/install/install.test.ts

@@ -6,8 +6,9 @@ import { CliProgram } from "../types.ts";
 import { detectInstalledArtifacts } from "./detect-installed.ts";
 import { resolveInstallPaths } from "./paths.ts";
 import { buildInstallPlan } from "./plan.ts";
+import { buildUninstallPlan } from "./uninstall.ts";
 import { printInstallStatus } from "./status.ts";
-import { parseInstallOpts } from "./index.ts";
+import { parseInstallOpts, runInstallMutation, validateInstallOpts } from "./index.ts";
 
 const fixture: CliProgram = {
   key: "testapp",
@@ -123,3 +124,65 @@ describe("parseInstallOpts", () => {
     expect(opts.all).toBe(true);
   });
 });
+
+describe("validateInstallOpts", () => {
+  test("uninstall requires a target flag", () => {
+    const opts = parseInstallOpts({ uninstall: "1", yes: "1" });
+    expect(validateInstallOpts(opts)).toContain("Specify at least one target");
+  });
+
+  test("uninstall allows --all", () => {
+    const opts = parseInstallOpts({ uninstall: "1", all: "1", yes: "1" });
+    expect(validateInstallOpts(opts)).toBeNull();
+  });
+
+  test("uninstall rejects --reinstall", () => {
+    const opts = parseInstallOpts({ uninstall: "1", reinstall: "1", all: "1" });
+    expect(validateInstallOpts(opts)).toContain("--reinstall");
+  });
+});
+
+describe("install mutation", () => {
+  test("uninstall --all with nothing installed succeeds", async () => {
+    const result = await runInstallMutation(fixture, { uninstall: "1", all: "1", yes: "1" });
+    expect(result.changed).toEqual([]);
+  });
+
+  test("install --skill with no agent dirs succeeds", async () => {
+    const result = await runInstallMutation(fixture, { skill: "1", yes: "1", dry: "1" });
+    expect(result.changed).toEqual([]);
+  });
+
+  test("uninstall --all removes detected binary", async () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(paths.bindir, { recursive: true });
+    writeFileSync(paths.binaryPath, "fake", "utf8");
+
+    const result = await runInstallMutation(fixture, { uninstall: "1", all: "1", yes: "1" });
+    expect(result.changed).toContain(paths.binaryPath);
+    expect(existsSync(paths.binaryPath)).toBe(false);
+  });
+});
+
+describe("uninstall plan", () => {
+  test("buildUninstallPlan --all scopes like install --all", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(paths.bindir, { recursive: true });
+    writeFileSync(paths.binaryPath, "fake", "utf8");
+
+    const plan = buildUninstallPlan(fixture, paths, parseInstallOpts({ uninstall: "1", all: "1" }));
+    expect(plan.some((a) => a.summary.startsWith("binary:"))).toBe(true);
+  });
+
+  test("buildUninstallPlan --bin ignores completions", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(paths.bindir, { recursive: true });
+    writeFileSync(paths.binaryPath, "fake", "utf8");
+    mkdirSync(join(home, ".bash_completion.d"), { recursive: true });
+    writeFileSync(paths.bashCompletion, "# bash", "utf8");
+
+    const plan = buildUninstallPlan(fixture, paths, parseInstallOpts({ uninstall: "1", bin: "1" }));
+    expect(plan).toHaveLength(1);
+    expect(plan[0]!.summary.startsWith("binary:")).toBe(true);
+  });
+});

package/src/install/mcp-config.ts

@@ -1,7 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { CliProgram } from "../types.ts";
-import { InstallPaths } from "./paths.ts";
 
 export interface McpServerEntry {
   command: string;

package/src/install/plan.ts

@@ -35,19 +35,19 @@ export interface InstallAction {
   run: () => string[];
 }
 
-function wantsBin(opts: InstallOpts): boolean {
+export function wantsInstallBin(opts: InstallOpts): boolean {
   return !!(opts.all || opts.bin || opts.reinstall);
 }
 
-function wantsCompletions(opts: InstallOpts): boolean {
+export function wantsInstallCompletions(opts: InstallOpts): boolean {
   return !!(opts.all || opts.completions);
 }
 
-function wantsSkill(opts: InstallOpts): boolean {
+export function wantsInstallSkill(opts: InstallOpts): boolean {
   return !!(opts.all || opts.skill);
 }
 
-function wantsMcp(opts: InstallOpts, root: CliProgram): boolean {
+export function wantsInstallMcp(opts: InstallOpts, root: CliProgram): boolean {
   return !!(opts.mcp || opts.all) && resolveCapabilities(root).mcp;
 }
 
@@ -56,7 +56,7 @@ export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: In
   const actions: InstallAction[] = [];
   const dry = !!opts.dry;
 
-  if (wantsBin(opts)) {
+  if (wantsInstallBin(opts)) {
     const sourcePath = opts.from ?? process.execPath;
     actions.push({
       kind: "binary",
@@ -66,7 +66,7 @@ export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: In
     });
   }
 
-  if (wantsCompletions(opts)) {
+  if (wantsInstallCompletions(opts)) {
     const shells = detectShells();
     if (shells.bash) {
       actions.push({
@@ -103,7 +103,7 @@ export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: In
     }
   }
 
-  if (wantsSkill(opts)) {
+  if (wantsInstallSkill(opts)) {
     const home = userHome();
     if (existsSync(join(home, ".cursor"))) {
       actions.push({
@@ -123,7 +123,7 @@ export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: In
     }
   }
 
-  if (wantsMcp(opts, root)) {
+  if (wantsInstallMcp(opts, root)) {
     const entry = expectedMcpEntry(root);
     if (existsSync(join(userHome(), ".cursor"))) {
       actions.push({

package/src/install/uninstall.ts

@@ -1,13 +1,17 @@
 import { existsSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { uninstallBinary } from "./binary.ts";
 import { uninstallCompletions } from "./completions.ts";
 import { detectInstalledArtifacts } from "./detect-installed.ts";
 import { removeMcpConfig } from "./mcp-config.ts";
-import { InstallPaths, userHome } from "./paths.ts";
-import type { InstallOpts } from "./plan.ts";
+import { InstallPaths } from "./paths.ts";
+import {
+  wantsInstallBin,
+  wantsInstallCompletions,
+  wantsInstallMcp,
+  wantsInstallSkill,
+  type InstallOpts,
+} from "./plan.ts";
 
 export interface UninstallAction {
   summary: string;
@@ -15,22 +19,17 @@ export interface UninstallAction {
   run: () => string[];
 }
 
-function scopeAll(opts: InstallOpts): boolean {
-  return !opts.bin && !opts.completions && !opts.skill && !opts.mcp;
-}
-
-/** Builds uninstall actions from detected artifacts. */
+/** Builds uninstall actions for scoped targets (--all mirrors install --all). */
 export function buildUninstallPlan(
   root: CliProgram,
   paths: InstallPaths,
   opts: InstallOpts,
 ): UninstallAction[] {
   const detected = detectInstalledArtifacts(paths);
-  const all = scopeAll(opts);
   const dry = !!opts.dry;
   const actions: UninstallAction[] = [];
 
-  if ((all || opts.bin) && detected.binary) {
+  if (wantsInstallBin(opts) && detected.binary) {
     actions.push({
       summary: `binary: ${paths.binaryPath}`,
       message: `Removing binary ${paths.binaryPath}`,
@@ -38,7 +37,10 @@ export function buildUninstallPlan(
     });
   }
 
-  if ((all || opts.completions) && (detected.bashCompletion || detected.zshCompletion || detected.fishCompletion)) {
+  if (
+    wantsInstallCompletions(opts) &&
+    (detected.bashCompletion || detected.zshCompletion || detected.fishCompletion)
+  ) {
     if (detected.bashCompletion) {
       actions.push({
         summary: `bash completion: ${paths.bashCompletion}`,
@@ -62,7 +64,7 @@ export function buildUninstallPlan(
     }
   }
 
-  if ((all || opts.skill) && detected.cursorSkill) {
+  if (wantsInstallSkill(opts) && detected.cursorSkill) {
     actions.push({
       summary: `cursor skill: ${paths.cursorSkillDir}/`,
       message: `Removing Cursor skill ${paths.cursorSkillDir}/`,
@@ -70,7 +72,7 @@ export function buildUninstallPlan(
     });
   }
 
-  if ((all || opts.skill) && detected.claudeSkill) {
+  if (wantsInstallSkill(opts) && detected.claudeSkill) {
     actions.push({
       summary: `claude skill: ${paths.claudeSkillDir}/`,
       message: `Removing Claude Code skill ${paths.claudeSkillDir}/`,
@@ -78,7 +80,7 @@ export function buildUninstallPlan(
     });
   }
 
-  if ((all || opts.mcp) && resolveCapabilities(root).mcp) {
+  if (wantsInstallMcp(opts, root)) {
     if (detected.cursorMcp) {
       actions.push({
         summary: `cursor mcp: ${paths.cursorMcpPath}`,