claudeup 6.0.0 → 6.2.0

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[];
@@ -44,7 +50,7 @@ export async function checkBinaries(
 		results.push({
 			name: bin.name,
 			present: await isPresent(bin.name),
-			installCommand: binInstallCommand(bin),
+			installCommand: formatCommand(binInstallCommand(bin)),
 			sources: bin.sources,
 		});
 	}

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;
 	}
 }