argsbarg 3.3.1 → 3.3.2

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -243,7 +252,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.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

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