claudeup 5.0.1 → 6.1.0

package/src/data/cli-tools.ts

@@ -1,12 +1,30 @@
+import type { BinInstaller } from "../types/index.js";
+
+/**
+ * A CLI tool claudeup can install, check and update.
+ *
+ * There is deliberately NO `installCommand` field. Entries used to carry one
+ * alongside `packageManager` + `packageName`, which describe the same thing —
+ * so the two could disagree, and did: `aider` declared
+ * `packageName: "aider-chat"` while its `installCommand` installed
+ * `aider-install`, and the version check queried the former. The command is
+ * derived by `services/cli-tool-commands.ts` instead, which also means a
+ * catalogue entry can no longer smuggle shell syntax (that same entry's command
+ * was a `&&` chain) into something that gets executed.
+ */
 export interface CliTool {
 	name: string;
 	displayName: string;
 	description: string;
-	installCommand: string;
 	checkCommand: string;
 	website: string;
 	category: "ai-coding" | "utility";
-	packageManager: "bun" | "npm" | "pip" | "brew" | "go";
+	/**
+	 * Reuses `BinInstaller` rather than restating its members, so the
+	 * correspondence with the resolver in `services/toolchain.ts` — which is
+	 * what turns this field into an actual command — is a compile-time fact.
+	 */
+	packageManager: BinInstaller;
 	packageName: string;
 }
 
@@ -16,7 +34,6 @@ export const cliTools: CliTool[] = [
 		displayName: "claudeup",
 		description:
 			"TUI tool for managing Claude Code plugins, MCPs, and configuration",
-		installCommand: "bun install -g claudeup",
 		checkCommand: "claudeup --version",
 		website: "https://github.com/MadAppGang/magus/tree/main/tools/claudeup",
 		category: "ai-coding",
@@ -28,7 +45,6 @@ export const cliTools: CliTool[] = [
 		displayName: "Mnemex",
 		description:
 			"AST-aware code search with PageRank, callers/callees, and semantic embeddings",
-		installCommand: "bun install -g mnemex",
 		checkCommand: "mnemex --version",
 		website: "https://github.com/MadAppGang/mnemex",
 		category: "ai-coding",
@@ -39,7 +55,6 @@ export const cliTools: CliTool[] = [
 		name: "claudish",
 		displayName: "Claudish",
 		description: "Run Claude Code with OpenRouter models (Grok, GPT-5, Gemini)",
-		installCommand: "bun install -g claudish",
 		checkCommand: "claudish --version",
 		website: "https://github.com/MadAppGang/claudish",
 		category: "ai-coding",
@@ -50,7 +65,6 @@ export const cliTools: CliTool[] = [
 		name: "claude",
 		displayName: "Claude Code",
 		description: "Anthropic official agentic coding tool",
-		installCommand: "npm install -g @anthropic-ai/claude-code",
 		checkCommand: "claude --version",
 		website: "https://claude.ai/code",
 		category: "ai-coding",
@@ -62,7 +76,6 @@ export const cliTools: CliTool[] = [
 		displayName: "OpenAI Codex",
 		description:
 			"Lightweight coding agent from OpenAI that runs in your terminal",
-		installCommand: "npm install -g @openai/codex",
 		checkCommand: "codex --version",
 		website: "https://github.com/openai/codex",
 		category: "ai-coding",
@@ -73,7 +86,6 @@ export const cliTools: CliTool[] = [
 		name: "gemini",
 		displayName: "Gemini CLI",
 		description: "Google AI agent with 1M token context, free tier available",
-		installCommand: "npm install -g @google/gemini-cli",
 		checkCommand: "gemini --version",
 		website: "https://github.com/google-gemini/gemini-cli",
 		category: "ai-coding",
@@ -84,7 +96,6 @@ export const cliTools: CliTool[] = [
 		name: "qwen",
 		displayName: "Qwen Code",
 		description: "Alibaba coding agent optimized for Qwen3-Coder models",
-		installCommand: "npm install -g @qwen-code/qwen-code",
 		checkCommand: "qwen --version",
 		website: "https://github.com/QwenLM/qwen-code",
 		category: "ai-coding",
@@ -96,7 +107,6 @@ export const cliTools: CliTool[] = [
 		displayName: "Cline",
 		description:
 			"Autonomous coding agent with plan & act, checkpoints, browser use",
-		installCommand: "npm install -g cline",
 		checkCommand: "cline --version",
 		website: "https://cline.bot",
 		category: "ai-coding",
@@ -107,7 +117,6 @@ export const cliTools: CliTool[] = [
 		name: "opencode",
 		displayName: "OpenCode",
 		description: "Open source AI coding agent trusted by 400k+ developers",
-		installCommand: "npm install -g opencode-ai",
 		checkCommand: "opencode --version",
 		website: "https://opencode.ai",
 		category: "ai-coding",
@@ -118,7 +127,6 @@ export const cliTools: CliTool[] = [
 		name: "aider",
 		displayName: "Aider",
 		description: "AI pair programming - works with Claude, GPT-4, local models",
-		installCommand: "pip install aider-install && aider-install",
 		checkCommand: "aider --version",
 		website: "https://aider.chat",
 		category: "ai-coding",
@@ -129,7 +137,6 @@ export const cliTools: CliTool[] = [
 		name: "crush",
 		displayName: "Crush",
 		description: "AI coding assistant from Charm with terminal-native UX",
-		installCommand: "npm install -g @charmland/crush",
 		checkCommand: "crush --version",
 		website: "https://github.com/charmbracelet/crush",
 		category: "ai-coding",

package/src/services/cli-tool-commands.ts

@@ -0,0 +1,133 @@
+/**
+ * The three commands the CLI-tools screen can run against a catalogue entry:
+ * install, update, uninstall.
+ *
+ * A module rather than helpers inside the screen, for two reasons:
+ *
+ *  - **The duplicate.** Uninstall existed twice — once in `CliToolsScreen.tsx`
+ *    and once in `cliToolRenderers.tsx` (as `getUninstallHint`) — because the
+ *    renderer needs to SHOW it and the screen needs to RUN it. The two copies
+ *    had already drifted: one emitted `pip uninstall`, the other
+ *    `pip uninstall -y`. Both were wrong in the same way, which is the point —
+ *    a bug in a duplicated builder has to be found twice.
+ *  - **Testability.** As `.tsx` helpers these were unreachable from a suite that
+ *    cannot render React. As pure functions over data they are pinned by
+ *    `cli-tool-commands.test.ts`, which is what proves no arm emits a bare
+ *    `pip` — the defect that shipped.
+ *
+ * Import direction stays acyclic: renderer → service, screen → service +
+ * renderer.
+ */
+
+import type { CliTool } from "../data/cli-tools.js";
+import type { Command } from "../utils/command-utils.js";
+import {
+	binInstallCommand,
+	binUninstallCommand,
+	binUpgradeCommand,
+} from "./toolchain.js";
+
+/**
+ * How a tool turned out to be installed, as detected from its path on disk.
+ *
+ * NOT the same question as `CliTool.packageManager`, and deliberately not the
+ * same type. `packageManager` is how claudeup WOULD install the tool; this is
+ * how it IS installed — which may be neither, since a user can `pnpm add -g` or
+ * `yarn global add` something the catalogue calls an npm package. Updating has
+ * to follow what is actually on the machine, or it installs a second copy
+ * beside the first and the screen then reports a conflict it created itself.
+ *
+ * `pnpm`, `yarn` and `unknown` have no `BinInstaller` counterpart, which is why
+ * the two unions stay separate rather than one being widened into the other.
+ */
+export type InstallMethod =
+	| "npm"
+	| "bun"
+	| "pnpm"
+	| "yarn"
+	| "brew"
+	| "pip"
+	| "unknown";
+
+/**
+ * Install a catalogue tool, derived from the entry's own fields.
+ *
+ * Entries used to carry a literal `installCommand` string beside the
+ * `packageManager` and `packageName` that describe the same thing, so the two
+ * could disagree — and did. `aider` declared `packageName: "aider-chat"` and
+ * `checkCommand: "aider --version"`, and its `installCommand` installed
+ * `aider-install`: a bootstrapper whose version nothing in this screen ever
+ * looked at, while the version check queried `aider-chat`. Deriving makes that
+ * disagreement unrepresentable rather than merely fixed.
+ */
+export function cliToolInstall(tool: CliTool): Command {
+	return binInstallCommand({
+		name: tool.name,
+		via: tool.packageManager,
+		package: tool.packageName,
+	});
+}
+
+/**
+ * Update a tool, following the method it was ACTUALLY installed with.
+ *
+ * Returns null when there is nothing sound to run — an `unknown` method means
+ * the detector could not attribute the binary on PATH to any package manager,
+ * and guessing there would install a second copy alongside the one already
+ * there. Callers fall back to installing.
+ */
+export function cliToolUpdate(
+	tool: CliTool,
+	method: InstallMethod,
+	brewFormula?: string,
+): Command | null {
+	switch (method) {
+		// The three the resolver does not model. `pnpm`/`yarn` are not
+		// BinInstallers because claudeup never chooses them — it only finds them.
+		case "pnpm":
+			return { cmd: "pnpm", args: ["install", "-g", tool.packageName] };
+		case "yarn":
+			return { cmd: "yarn", args: ["global", "add", tool.packageName] };
+		case "unknown":
+			return null;
+		default:
+			// TS has narrowed to "npm" | "bun" | "brew" | "pip" here, which is
+			// assignable to BinInstaller — so the four real installers delegate,
+			// and `pip` in particular gets the uv/pipx/python3 resolution instead
+			// of the bare `pip` this switch used to fall through to.
+			return binUpgradeCommand({
+				name: tool.name,
+				via: method,
+				package: tool.packageName,
+				formula: brewFormula,
+			});
+	}
+}
+
+/**
+ * Remove a tool, following the method it was actually installed with.
+ *
+ * Null means "no command to offer": `unknown` for the reason above, and `go`
+ * because a `go install` binary has no uninstaller to call.
+ */
+export function cliToolUninstall(
+	tool: CliTool,
+	method: InstallMethod,
+	brewFormula?: string,
+): Command | null {
+	switch (method) {
+		case "pnpm":
+			return { cmd: "pnpm", args: ["remove", "-g", tool.packageName] };
+		case "yarn":
+			return { cmd: "yarn", args: ["global", "remove", tool.packageName] };
+		case "unknown":
+			return null;
+		default:
+			return binUninstallCommand({
+				name: tool.name,
+				via: method,
+				package: tool.packageName,
+				formula: brewFormula,
+			});
+	}
+}

package/src/services/doctor-bins.ts

@@ -8,13 +8,19 @@
  */
 
 import type { ResolvedBin } from "../types/index.js";
-import { resolveExecutable } from "../utils/command-utils.js";
+import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
 import { binInstallCommand } from "./toolchain.js";
 
 export interface BinCheckResult {
 	name: string;
 	present: boolean;
-	/** The command that would install it, shown when missing. */
+	/**
+	 * The command that would install it, shown when missing.
+	 *
+	 * A rendered string, not a {@link Command}: this is advisory text printed
+	 * after "run:" for a human to copy. Nothing executes it — doctor diagnoses
+	 * and never installs — so there is nothing here for a shell to re-parse.
+	 */
 	installCommand: string;
 	/** Where the requirement came from (profile cliTools / plugin ids). */
 	sources: string[];
@@ -23,6 +29,12 @@ export interface BinCheckResult {
 /**
  * Check each resolved binary for presence on PATH. `isPresent` is injectable
  * for tests; it defaults to a real PATH lookup.
+ *
+ * The probes are deliberately SERIAL — a PATH walk per binary, each resolving
+ * symlinks — so a profile declaring a dozen tools spends real time here. That
+ * is what `onProbe` is for: it fires with the name about to be checked, before
+ * the await, so a caller can name the binary it is currently blocked on rather
+ * than showing a bare spinner.
  */
 export async function checkBinaries(
 	bins: ResolvedBin[],
@@ -30,13 +42,15 @@ export async function checkBinaries(
 	// (the tmux-mcp / npx-cache failure mode) reads as MISSING, not present.
 	isPresent: (name: string) => Promise<boolean> = async (name) =>
 		(await resolveExecutable(name)) !== null,
+	onProbe?: (name: string, index: number, total: number) => void,
 ): Promise<BinCheckResult[]> {
 	const results: BinCheckResult[] = [];
-	for (const bin of bins) {
+	for (const [index, bin] of bins.entries()) {
+		onProbe?.(bin.name, index, bins.length);
 		results.push({
 			name: bin.name,
 			present: await isPresent(bin.name),
-			installCommand: binInstallCommand(bin),
+			installCommand: formatCommand(binInstallCommand(bin)),
 			sources: bin.sources,
 		});
 	}

package/src/services/marketplace-refresh.ts

@@ -130,12 +130,44 @@ export async function fastForwardCloneIfPresent(
 	}
 }
 
+/**
+ * Progress taps, so a caller can show what is happening during the pulls.
+ *
+ * This is the slowest thing on the update path — a git fetch per marketplace,
+ * over the network, with a 30s timeout each — and it used to report only after
+ * every clone had settled.
+ *
+ * Both callbacks are purely observational and CANNOT affect the refresh: each
+ * is invoked inside a try/catch that discards whatever it throws. `onSettled`
+ * in particular runs inside the `Promise.all` fan-out, so an unguarded throw
+ * there would reject the batch and turn a display error into a failed refresh —
+ * exactly the coupling this function's "never throws" contract exists to
+ * prevent.
+ */
+export interface RefreshProgress {
+	/** The eligible set, once selection is done and before any pull starts. */
+	onStart?: (names: string[]) => void;
+	/** One clone settled. Fires in completion order, not in `names` order. */
+	onSettled?: (name: string, status: CloneRefresh) => void;
+}
+
+/** Invoke an observer without letting it affect the caller. */
+function tap(fn: (() => void) | undefined): void {
+	if (!fn) return;
+	try {
+		fn();
+	} catch {
+		// A progress display is never worth failing a refresh over.
+	}
+}
+
 /**
  * Non-destructively fast-forward the on-disk clone of every registered,
  * auto-update-enabled, github-sourced marketplace.
  *
  * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
  *   so they aren't pulled twice.
+ * @param progress optional taps for a live progress display.
  * @returns which marketplaces were refreshed, which failed (clone left intact),
  *   and which were skipped. Failures and skips are collected rather than thrown —
  *   one unreachable marketplace must not block launching Claude. Pulls run
@@ -143,6 +175,7 @@ export async function fastForwardCloneIfPresent(
  */
 export async function refreshRegisteredMarketplaces(
 	skip: Iterable<string> = [],
+	progress: RefreshProgress = {},
 ): Promise<RefreshResult> {
 	const refreshed: string[] = [];
 	const failed: string[] = [];
@@ -170,8 +203,13 @@ export async function refreshRegisteredMarketplaces(
 	// Fast-forward every eligible clone in parallel so a slow one doesn't
 	// serialize the rest onto the launch path. fastForwardCloneIfPresent never
 	// throws, so the batch always resolves.
+	tap(() => progress.onStart?.([...eligible]));
 	const statuses = await Promise.all(
-		eligible.map((name) => fastForwardCloneIfPresent(name)),
+		eligible.map(async (name) => {
+			const status = await fastForwardCloneIfPresent(name);
+			tap(() => progress.onSettled?.(name, status));
+			return status;
+		}),
 	);
 
 	statuses.forEach((status, i) => {

package/src/services/toolchain.ts

@@ -9,17 +9,157 @@
  */
 
 import type { BinInstaller, ResolvedBin } from "../types/index.js";
-import { which } from "../utils/command-utils.js";
+import type { Command } from "../utils/command-utils.js";
+import { which, whichSync } from "../utils/command-utils.js";
 
-/** The executable that proves a toolchain is installed. */
-const TOOLCHAIN_PROBE: Record<BinInstaller, string> = {
+// -- Python CLI applications -------------------------------------------------
+
+/**
+ * How to install a Python COMMAND-LINE APPLICATION on this machine.
+ *
+ * `via: "pip"` used to emit the literal string `pip install <pkg>`, which is
+ * wrong on a modern macOS in two independent ways, both measured:
+ *
+ *  1. **`pip` frequently does not exist.** Homebrew installs `pip3`, and many
+ *     people reach it through a shell alias — which lives only in interactive
+ *     zsh. Commands were spawned through `/bin/sh`, which never sources a
+ *     profile, so this died with `/bin/sh: pip: command not found` on a machine
+ *     where typing `pip` at a prompt works perfectly. Commands are argv now
+ *     (`utils/run.ts`), so `cmd` is looked up on PATH with no shell at all —
+ *     which makes "resolve a real executable" the only option rather than the
+ *     careful one.
+ *  2. **`pip install` into a Homebrew interpreter is refused outright.** PEP
+ *     668 marks it externally-managed; `python3 -m pip install --upgrade x`
+ *     fails with `externally-managed-environment` no matter how it is spelled.
+ *
+ * So the fix is not "spell pip correctly". For a CLI application — which is
+ * what every `via: "pip"` requirement in this repo is, a package whose point is
+ * the executable it puts on PATH — installing into the system interpreter is
+ * the wrong mechanism. `uv tool` and `pipx` each give the package its own
+ * virtualenv and link the executable onto PATH, which is both what was wanted
+ * and immune to PEP 668.
+ *
+ * Ordered best-first. `python3 -m pip --user` is last because it is the one
+ * that PEP 668 can still reject; it stays because it is correct on Linux, in CI
+ * and under pyenv, and because emitting it names `python3` in the failure —
+ * which is a true and actionable error — rather than a `pip` that never existed.
+ */
+export interface PythonCliInstaller {
+	/** Executable that must be on PATH for this option to be usable. */
+	probe: string;
+	install(pkg: string, version?: string): Command;
+	upgrade(pkg: string): Command;
+	/**
+	 * Remove the tool again.
+	 *
+	 * Installer-specific for the same reason install is: a package installed
+	 * with `uv tool install` lives in uv's own virtualenv and `pip uninstall`
+	 * cannot see it. The one form that is always wrong is a bare `pip`, which
+	 * frequently is not an executable at all.
+	 */
+	uninstall(pkg: string): Command;
+}
+
+export const PYTHON_CLI_INSTALLERS: readonly PythonCliInstaller[] = [
+	{
+		probe: "uv",
+		install: (pkg, version) => ({
+			cmd: "uv",
+			// `pkg==version` is ONE argv token. Splitting on the `==` would ask uv
+			// to install two packages, one of which is a version number.
+			args: ["tool", "install", version ? `${pkg}==${version}` : pkg],
+		}),
+		// `uv tool install --force --upgrade`, NOT `uv tool upgrade`. The latter
+		// only knows tools uv itself installed and errors otherwise —
+		// `browser-use is not installed; run uv tool install` on a machine where
+		// the executable was plainly on PATH, put there by a pip that predates
+		// uv. Since `claudeup update` reaches here for anything already present,
+		// that is the common case, not the edge case. `--force` adopts the
+		// existing shim; `--upgrade` moves it to the newest version.
+		upgrade: (pkg) => ({
+			cmd: "uv",
+			args: ["tool", "install", "--force", "--upgrade", pkg],
+		}),
+		uninstall: (pkg) => ({ cmd: "uv", args: ["tool", "uninstall", pkg] }),
+	},
+	{
+		probe: "pipx",
+		install: (pkg, version) => ({
+			cmd: "pipx",
+			args: ["install", version ? `${pkg}==${version}` : pkg],
+		}),
+		// Same reasoning as uv: `pipx upgrade` fails when pipx does not already
+		// manage the package.
+		upgrade: (pkg) => ({ cmd: "pipx", args: ["install", "--force", pkg] }),
+		uninstall: (pkg) => ({ cmd: "pipx", args: ["uninstall", pkg] }),
+	},
+	{
+		probe: "python3",
+		install: (pkg, version) => ({
+			cmd: "python3",
+			args: [
+				"-m",
+				"pip",
+				"install",
+				"--user",
+				version ? `${pkg}==${version}` : pkg,
+			],
+		}),
+		upgrade: (pkg) => ({
+			cmd: "python3",
+			args: ["-m", "pip", "install", "--user", "--upgrade", pkg],
+		}),
+		// `-y`: nothing here is attached to a TTY that could answer a prompt.
+		uninstall: (pkg) => ({
+			cmd: "python3",
+			args: ["-m", "pip", "uninstall", "-y", pkg],
+		}),
+	},
+];
+
+/** Memoised: PATH does not change within one claudeup run. */
+let pythonCliMemo: PythonCliInstaller | undefined;
+
+/**
+ * The best Python CLI installer available here. Never null — the `python3`
+ * entry is returned when nothing better is found, so callers always get a
+ * command whose failure names something real.
+ */
+export function resolvePythonCliInstaller(): PythonCliInstaller {
+	if (pythonCliMemo) return pythonCliMemo;
+	pythonCliMemo =
+		PYTHON_CLI_INSTALLERS.find((i) => whichSync(i.probe) !== null) ??
+		PYTHON_CLI_INSTALLERS.at(-1)!;
+	return pythonCliMemo;
+}
+
+/** Test seam — PATH is stable within a run, so production never needs this. */
+export function resetPythonCliInstallerMemo(): void {
+	pythonCliMemo = undefined;
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * The executable that proves a toolchain is installed.
+ *
+ * `pip` is deliberately absent: which executable proves it depends on the
+ * machine, so it is resolved by {@link resolvePythonCliInstaller} instead.
+ */
+const TOOLCHAIN_PROBE: Record<Exclude<BinInstaller, "pip">, string> = {
 	bun: "bun",
 	brew: "brew",
 	npm: "npm",
-	pip: "pip",
 	go: "go",
 };
 
+/** The executable whose presence proves `name` is usable. */
+function toolchainProbe(name: BinInstaller): string {
+	return name === "pip"
+		? resolvePythonCliInstaller().probe
+		: TOOLCHAIN_PROBE[name];
+}
+
 /** Official one-line bootstrap for the toolchains claudeup will install. */
 export const TOOLCHAIN_BOOTSTRAP: Partial<Record<BinInstaller, string>> = {
 	bun: "curl -fsSL https://bun.sh/install | bash",
@@ -37,7 +177,7 @@ export interface ToolchainStatus {
 
 /** Is a given toolchain available on PATH? */
 export async function isToolchainPresent(name: BinInstaller): Promise<boolean> {
-	return (await which(TOOLCHAIN_PROBE[name])) !== null;
+	return (await which(toolchainProbe(name))) !== null;
 }
 
 /**
@@ -69,30 +209,48 @@ export async function detectToolchains(
 	return statuses;
 }
 
-/** The install command for a single binary requirement. */
-export function binInstallCommand(bin: {
-	name: string;
-	via: BinInstaller;
-	package?: string;
-	formula?: string;
-	module?: string;
-	version?: string;
-}): string {
+/**
+ * The install command for a single binary requirement.
+ *
+ * `python` is injectable so tests can pin one and stay machine-independent —
+ * the default depends on what is on PATH, so an assertion against a literal
+ * `uv tool …` would pass here and fail on a runner without uv.
+ *
+ * `pkg@version` and `pkg==version` are each ONE argv token. That join is
+ * precisely where a string was dangerous: `bin.package` is hand-authored
+ * profile/marketplace data, and under a shell a space or a `;` in it would have
+ * become extra words. Here it cannot.
+ */
+export function binInstallCommand(
+	bin: {
+		name: string;
+		via: BinInstaller;
+		package?: string;
+		formula?: string;
+		module?: string;
+		version?: string;
+	},
+	python: PythonCliInstaller = resolvePythonCliInstaller(),
+): Command {
 	const pkg = bin.package ?? bin.name;
 	const at = bin.version ? `@${bin.version}` : "";
 	switch (bin.via) {
 		case "bun":
-			return `bun install -g ${pkg}${at}`;
+			return { cmd: "bun", args: ["install", "-g", `${pkg}${at}`] };
 		case "npm":
-			return `npm install -g ${pkg}${at}`;
+			return { cmd: "npm", args: ["install", "-g", `${pkg}${at}`] };
 		case "pip":
-			return bin.version
-				? `pip install ${pkg}==${bin.version}`
-				: `pip install ${pkg}`;
+			return python.install(pkg, bin.version);
 		case "brew":
-			return `brew install ${bin.formula ?? bin.name}`;
+			return { cmd: "brew", args: ["install", bin.formula ?? bin.name] };
 		case "go":
-			return `go install ${bin.module ?? bin.name}@${bin.version ?? "latest"}`;
+			return {
+				cmd: "go",
+				args: [
+					"install",
+					`${bin.module ?? bin.name}@${bin.version ?? "latest"}`,
+				],
+			};
 	}
 }
 
@@ -109,24 +267,68 @@ export function binInstallCommand(bin: {
  * for unpinned requirements; `@latest` is stated explicitly where the installer
  * accepts it, so the intent survives in the printed command.
  */
-export function binUpgradeCommand(bin: {
-	name: string;
-	via: BinInstaller;
-	package?: string;
-	formula?: string;
-	module?: string;
-}): string {
+export function binUpgradeCommand(
+	bin: {
+		name: string;
+		via: BinInstaller;
+		package?: string;
+		formula?: string;
+		module?: string;
+	},
+	python: PythonCliInstaller = resolvePythonCliInstaller(),
+): Command {
+	const pkg = bin.package ?? bin.name;
+	switch (bin.via) {
+		case "bun":
+			return { cmd: "bun", args: ["install", "-g", `${pkg}@latest`] };
+		case "npm":
+			return { cmd: "npm", args: ["install", "-g", `${pkg}@latest`] };
+		case "pip":
+			return python.upgrade(pkg);
+		case "brew":
+			return { cmd: "brew", args: ["upgrade", bin.formula ?? bin.name] };
+		case "go":
+			return {
+				cmd: "go",
+				args: ["install", `${bin.module ?? bin.name}@latest`],
+			};
+	}
+}
+
+/**
+ * The command that REMOVES an installed binary.
+ *
+ * Third of the trio, and it needs the resolver for exactly the reason the other
+ * two do: which executable can remove a Python CLI application depends on which
+ * one installed it, and a bare `pip uninstall` is wrong on the same machines
+ * where a bare `pip install` was. The CLI-tools screen carried that bare form in
+ * two separate copies before this existed.
+ *
+ * `brew` and `go` have no catalogue entries today, so those arms ship
+ * unexercised by real data — they are pinned by unit test instead. `go` has no
+ * uninstall at all (`go install` writes a binary into GOBIN and records
+ * nothing), so it returns null rather than inventing an `rm`.
+ */
+export function binUninstallCommand(
+	bin: {
+		name: string;
+		via: BinInstaller;
+		package?: string;
+		formula?: string;
+	},
+	python: PythonCliInstaller = resolvePythonCliInstaller(),
+): Command | null {
 	const pkg = bin.package ?? bin.name;
 	switch (bin.via) {
 		case "bun":
-			return `bun install -g ${pkg}@latest`;
+			return { cmd: "bun", args: ["remove", "-g", pkg] };
 		case "npm":
-			return `npm install -g ${pkg}@latest`;
+			return { cmd: "npm", args: ["uninstall", "-g", pkg] };
 		case "pip":
-			return `pip install --upgrade ${pkg}`;
+			return python.uninstall(pkg);
 		case "brew":
-			return `brew upgrade ${bin.formula ?? bin.name}`;
+			return { cmd: "brew", args: ["uninstall", bin.formula ?? bin.name] };
 		case "go":
-			return `go install ${bin.module ?? bin.name}@latest`;
+			return null;
 	}
 }