argsbarg 3.3.1 → 3.3.3

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.3] - 2026-06-21
+
+### Added
+
+- **`docs --save`** — write bundled docs to `./docs/`; `docs all --save` writes one file per topic instead of combined stdout output. Argsbarg-generated markdown (`mcp`, `api`, `skill`) is prefixed with a `Generated by … docs … --save` HTML comment.
+
+## [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
@@ -243,7 +255,9 @@ 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.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.3...HEAD
+[3.3.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.3
+[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

package/docs/bundled-docs.md

@@ -32,6 +32,8 @@ myapp docs api          # command tree as markdown
 myapp docs skill        # generated Cursor SKILL.md
 myapp docs all          # all user topics; includes auto mcp when MCP enabled
 myapp docs mcp          # auto-generated when mcpServer.enabled
+myapp docs readme --save   # write ./docs/readme.md
+myapp docs all --save      # write ./docs/<topic>.md for each bundled topic
 ```
 
 ## Configuration
@@ -89,3 +91,19 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 | `mcp` | Callable tools + schema resource |
 
 Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.
+
+## Save to disk (`--save`)
+
+Pass **`--save`** on `docs` or any docs subcommand to write files under **`./docs/`** (relative to the current working directory). Each saved path is printed on stdout.
+
+| Command | Output |
+| --- | --- |
+| `docs readme --save` | `./docs/readme.md` |
+| `docs schema --save` | `./docs/schema.json` |
+| `docs api --save` | `./docs/api.md` |
+| `docs skill --save` | `./docs/skill.md` |
+| `docs all --save` | one file per bundled topic (`readme.md`, `mcp.md`, …) — not a combined file |
+
+`docs all --save` uses the same topic set as stdout `docs all` (user topics plus auto `mcp` when enabled). It does not include `schema`, `api`, or `skill` unless you invoke those subcommands separately.
+
+Argsbarg-generated markdown (`mcp`, `api`, `skill`) is prefixed with an HTML comment: `<!-- Generated by myapp docs api --save; do not edit. -->`. Consumer topic files and `schema.json` are written as-is.

package/docs/cli-program.md

@@ -52,12 +52,27 @@ ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliPro
 | --- | --- |
 | 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 |
-| `somethingCommand()` factory | Entry file is large; handler/body is substantial (Ink page, headless dispatch) |
+| `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.
 
-**`satisfies CliProgram`** on the root (or on extracted command factories) preserves type-checking whether inline or not.
+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
 

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/templates/cursor/rules/cli-program.mdc

@@ -13,7 +13,7 @@ alwaysApply: false
 - Reserved root commands (do not declare): `completion`, `install`, `mcp`, `version`, `docs`, `update`
 
 ## Schema
-- **Inline** options, positionals, and handler schema; extract only for shared flags, `mcpTool` spreads, or large handlers (Ink/dispatch)
+- **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "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/docs/builtin.ts

@@ -1,4 +1,4 @@
-import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+import { CliFallbackMode, CliOptionKind, type CliLeaf, type CliOption, type CliProgram, type CliRouter } from "../types.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
   docsEffectiveDefaultTopic,
@@ -8,14 +8,32 @@ import {
   docsUserTopicKeys,
   printDocsTopic,
 } from "./resolve.ts";
+import { saveDocsTopics } from "./save.ts";
+
+const DOCS_SAVE_OPTION: CliOption = {
+  name: "save",
+  description: "Write documentation to ./docs/ (`docs all` writes one file per topic).",
+  kind: CliOptionKind.Presence,
+};
+
+function runDocsTopic(program: CliProgram, topic: string, ctx: { hasFlag(name: string): boolean }): void {
+  if (ctx.hasFlag("save")) {
+    for (const path of saveDocsTopics(program, topic)) {
+      process.stdout.write(`${path}\n`);
+    }
+    return;
+  }
+  printDocsTopic(program, topic);
+}
 
 function docsLeaf(program: CliProgram, key: string, description: string): CliLeaf {
   return {
     key,
     description,
+    options: [DOCS_SAVE_OPTION],
     mcpTool: { enabled: false },
-    handler: () => {
-      printDocsTopic(program, key);
+    handler: (ctx) => {
+      runDocsTopic(program, key, ctx);
     },
   };
 }
@@ -46,6 +64,7 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   return {
     key: "docs",
     description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    options: [DOCS_SAVE_OPTION],
     fallbackCommand: docsEffectiveDefaultTopic(docs),
     fallbackMode: CliFallbackMode.MissingOnly,
     commands: leaves,

package/src/docs/docs.test.ts

@@ -1,4 +1,7 @@
-import { expect, test } from "bun:test";
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
 import { completionBashScript } from "../completion.ts";
 import { cliInvoke } from "../index.ts";
@@ -6,6 +9,21 @@ import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
 import { combineAllDocs, docsEffectiveDefaultTopic } from "./resolve.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
+import { docsTopicsToSave, saveDocsTopics } from "./save.ts";
+
+let workDir: string;
+let prevCwd: string;
+
+beforeEach(() => {
+  workDir = mkdtempSync(join(tmpdir(), "argsbarg-docs-save-"));
+  prevCwd = process.cwd();
+  process.chdir(workDir);
+});
+
+afterEach(() => {
+  process.chdir(prevCwd);
+  rmSync(workDir, { recursive: true, force: true });
+});
 
 function docsFixture(mcp = true): CliProgram {
   return {
@@ -165,3 +183,52 @@ test("generateMcpGuide includes schema URI", () => {
   const guide = generateMcpGuide(docsFixture(true));
   expect(guide).toContain("myapp://schema");
 });
+
+test("docs --save writes topic file", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "readme", "--save"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout.trim()).toBe("docs/readme.md");
+  const text = readFileSync(join(workDir, "docs/readme.md"), "utf8");
+  expect(text).toContain("Hello README");
+  expect(text).not.toContain("Generated by");
+});
+
+test("docs api --save prepends generated hint", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "api", "--save"]);
+  expect(result.exitCode).toBe(0);
+  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
+  expect(text.startsWith("<!-- Generated by myapp docs api --save; do not edit. -->\n\n")).toBe(
+    true,
+  );
+  expect(text).toContain("CLI API reference");
+});
+
+test("docs schema --save writes JSON file", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "schema", "--save"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout.trim()).toBe("docs/schema.json");
+  const text = readFileSync(join(workDir, "docs/schema.json"), "utf8");
+  expect(text).not.toContain("Generated by");
+  const schema = JSON.parse(text);
+  expect(schema.key).toBe("myapp");
+});
+
+test("docs all --save writes separate topic files", async () => {
+  const program = docsFixture(true);
+  const result = await cliInvoke(program, ["docs", "all", "--save"]);
+  expect(result.exitCode).toBe(0);
+  const lines = result.stdout.trim().split("\n");
+  expect(lines).toEqual(docsTopicsToSave(program, "all").map((key) => `docs/${key}.md`));
+  expect(readFileSync(join(workDir, "docs/readme.md"), "utf8")).not.toContain("Generated by");
+  expect(readFileSync(join(workDir, "docs/mcp.md"), "utf8")).toContain(
+    "<!-- Generated by myapp docs mcp --save; do not edit. -->",
+  );
+});
+
+test("saveDocsTopics returns relative paths", () => {
+  const paths = saveDocsTopics(docsFixture(), "api");
+  expect(paths).toEqual(["docs/api.md"]);
+  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
+  expect(text).toContain("<!-- Generated by myapp docs api --save; do not edit. -->");
+  expect(text).toContain("CLI API reference");
+});

package/src/docs/resolve.ts

@@ -77,6 +77,24 @@ export function docsTopicText(program: CliProgram, topic: string): string {
   return entry.text;
 }
 
+/** Full file body for a docs topic (stdout or `--save`). */
+export function docsTopicContent(program: CliProgram, topic: string): string {
+  if (topic === "schema") {
+    return cliSchemaJson(program);
+  }
+  if (topic === "api") {
+    return generateApiGuide(program);
+  }
+  if (topic === "skill") {
+    return `${generateSkillBundle(program, "cursor").skillMd}\n`;
+  }
+  if (topic === "all") {
+    return `${combineAllDocs(program)}\n`;
+  }
+  const text = docsTopicText(program, topic);
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
 /** All bundled docs concatenated with horizontal rules. */
 export function combineAllDocs(program: CliProgram): string {
   return docsPrintOrder(program)
@@ -84,36 +102,7 @@ export function combineAllDocs(program: CliProgram): string {
     .join("\n\n---\n\n");
 }
 
-/** Writes CLI schema JSON to stdout (`docs schema`). */
-export function printDocsSchema(program: CliProgram): void {
-  process.stdout.write(cliSchemaJson(program));
-}
-
-/** Writes markdown API reference to stdout (`docs api`). */
-export function printDocsApi(program: CliProgram): void {
-  process.stdout.write(generateApiGuide(program));
-}
-
-/** Writes generated Cursor SKILL.md to stdout (`docs skill`). */
-export function printDocsSkill(program: CliProgram): void {
-  const bundle = generateSkillBundle(program, "cursor");
-  process.stdout.write(`${bundle.skillMd}\n`);
-}
-
 /** Writes one docs topic (or `all`) to stdout. */
 export function printDocsTopic(program: CliProgram, topic: string): void {
-  if (topic === "schema") {
-    printDocsSchema(program);
-    return;
-  }
-  if (topic === "api") {
-    printDocsApi(program);
-    return;
-  }
-  if (topic === "skill") {
-    printDocsSkill(program);
-    return;
-  }
-  const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
-  process.stdout.write(`${content}\n`);
+  process.stdout.write(docsTopicContent(program, topic));
 }

package/src/docs/save.ts

@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CliProgram } from "../types.ts";
+import { docsPrintOrder, docsTopicContent } from "./resolve.ts";
+
+/** Relative output directory for `docs --save`. */
+export const DOCS_SAVE_DIR = "docs";
+
+/** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "api", "skill"] as const;
+
+/** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
+export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
+  return (DOCS_GENERATED_SAVE_TOPICS as readonly string[]).includes(topic);
+}
+
+/** HTML comment prepended to generated markdown saved with `--save`. */
+export function docsSaveGeneratedHint(program: CliProgram, topic: string): string {
+  return `<!-- Generated by ${program.key} docs ${topic} --save; do not edit. -->\n\n`;
+}
+
+/** File body for `--save` (hint on argsbarg-generated markdown only). */
+export function docsTopicContentForSave(program: CliProgram, topic: string): string {
+  const content = docsTopicContent(program, topic);
+  if (!docsTopicIsGeneratedByArgsbarg(topic)) {
+    return content;
+  }
+  return `${docsSaveGeneratedHint(program, topic)}${content}`;
+}
+
+/** Filename for a saved docs topic. */
+export function docsSaveFilename(topic: string): string {
+  if (topic === "schema") {
+    return "schema.json";
+  }
+  return `${topic}.md`;
+}
+
+/** Topic keys to write for one `docs` invocation (`all` expands to bundled topics). */
+export function docsTopicsToSave(program: CliProgram, topic: string): string[] {
+  if (topic === "all") {
+    return docsPrintOrder(program);
+  }
+  return [topic];
+}
+
+/** Writes docs topic(s) under `./docs/`; returns relative paths written. */
+export function saveDocsTopics(program: CliProgram, topic: string): string[] {
+  const dir = join(process.cwd(), DOCS_SAVE_DIR);
+  mkdirSync(dir, { recursive: true });
+
+  const saved: string[] = [];
+  for (const key of docsTopicsToSave(program, topic)) {
+    const rel = join(DOCS_SAVE_DIR, docsSaveFilename(key));
+    const abs = join(process.cwd(), rel);
+    writeFileSync(abs, docsTopicContentForSave(program, key), "utf8");
+    saved.push(rel);
+  }
+  return saved;
+}

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}`,