claudeup 6.0.0 → 6.1.0

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