magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/toolchain.ts

@@ -0,0 +1,431 @@
+/**
+ * Toolchain detection + bootstrap for the package managers a profile's binary
+ * deps need (bun, brew, npm, pip, go).
+ *
+ * `magus install` requires whatever installers the resolved closure uses. In
+ * source form bun is already guaranteed (bin/magus.js hard-exits without it),
+ * but once magus ships as a compiled binary an end user may lack bun — so bun
+ * is treated as a bootstrappable toolchain exactly like brew.
+ */
+
+import type { BinInstaller, ResolvedBin } from "../types/index.js";
+import type { Command } from "../utils/command-utils.js";
+import { which, whichSync } from "../utils/command-utils.js";
+
+// -- 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;
+	/**
+	 * Move an ALREADY-INSTALLED package to exactly `version`.
+	 *
+	 * Distinct from `install(pkg, version)`, which each of these treats as a
+	 * no-op once the package is present — `uv tool install pkg==v` answers
+	 * "already installed" when any version is there. `--force` is what makes
+	 * the pin land.
+	 */
+	pin(pkg: string, version: 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 `magus 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] }),
+		pin: (pkg, version) => ({
+			cmd: "uv",
+			args: ["tool", "install", "--force", `${pkg}==${version}`],
+		}),
+	},
+	{
+		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] }),
+		pin: (pkg, version) => ({
+			cmd: "pipx",
+			args: ["install", "--force", `${pkg}==${version}`],
+		}),
+	},
+	{
+		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],
+		}),
+		pin: (pkg, version) => ({
+			cmd: "python3",
+			args: ["-m", "pip", "install", "--user", `${pkg}==${version}`],
+		}),
+	},
+];
+
+/** Memoised: PATH does not change within one magus 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;
+	const found = PYTHON_CLI_INSTALLERS.find((i) => whichSync(i.probe) !== null);
+	const fallback = PYTHON_CLI_INSTALLERS[PYTHON_CLI_INSTALLERS.length - 1];
+	pythonCliMemo = found ?? fallback;
+	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",
+	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 magus will install. */
+export const TOOLCHAIN_BOOTSTRAP: Partial<Record<BinInstaller, string>> = {
+	bun: "curl -fsSL https://bun.sh/install | bash",
+	brew: '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+};
+
+export interface ToolchainStatus {
+	name: BinInstaller;
+	present: boolean;
+	/** Binary names in the closure that need this toolchain. */
+	requiredBy: string[];
+	/** Bootstrap command, when magus can install this toolchain itself. */
+	bootstrap?: string;
+}
+
+/** Is a given toolchain available on PATH? */
+export async function isToolchainPresent(name: BinInstaller): Promise<boolean> {
+	return (await which(toolchainProbe(name))) !== null;
+}
+
+/**
+ * Determine which toolchains a resolved closure's binary deps require, and
+ * whether each is present. Only toolchains actually needed are returned.
+ */
+export async function detectToolchains(
+	bins: ResolvedBin[],
+): Promise<ToolchainStatus[]> {
+	const requiredBy = new Map<BinInstaller, string[]>();
+	for (const bin of bins) {
+		const list = requiredBy.get(bin.via) ?? [];
+		list.push(bin.name);
+		requiredBy.set(bin.via, list);
+	}
+
+	const statuses: ToolchainStatus[] = [];
+	for (const [name, names] of requiredBy) {
+		statuses.push({
+			name,
+			present: await isToolchainPresent(name),
+			requiredBy: names,
+			bootstrap: TOOLCHAIN_BOOTSTRAP[name],
+		});
+	}
+	// Stable order: bun, brew, npm, pip, go.
+	const order: BinInstaller[] = ["bun", "brew", "npm", "pip", "go"];
+	statuses.sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
+	return statuses;
+}
+
+/**
+ * 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 { cmd: "bun", args: ["install", "-g", `${pkg}${at}`] };
+		case "npm":
+			return { cmd: "npm", args: ["install", "-g", `${pkg}${at}`] };
+		case "pip":
+			return python.install(pkg, bin.version);
+		case "brew":
+			return { cmd: "brew", args: ["install", bin.formula ?? bin.name] };
+		case "go":
+			return {
+				cmd: "go",
+				args: [
+					"install",
+					`${bin.module ?? bin.name}@${bin.version ?? "latest"}`,
+				],
+			};
+	}
+}
+
+/**
+ * The command that advances an ALREADY-INSTALLED binary to the newest version.
+ *
+ * Distinct from {@link binInstallCommand} because two of the five installers
+ * treat "install" as a no-op once the package is present: `brew install` on an
+ * installed formula prints "already installed" and changes nothing, and `pip
+ * install` without `--upgrade` does the same. Reusing the install command for
+ * `magus update` would therefore report success while advancing nothing.
+ *
+ * A pinned version has nothing to advance to, so callers must only reach this
+ * 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;
+	},
+	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 moves an ALREADY-INSTALLED binary to exactly its pin.
+ *
+ * `magus update` plans a pinned tool that sits below its pin as an upgrade
+ * TO the pin, and neither of the other two builders delivers that:
+ * {@link binUpgradeCommand} goes to the newest version, past the pin, and a
+ * plain `uv tool install pkg==v` is a no-op once any version is installed.
+ *
+ * bun, npm and go take the version in the same token `binInstallCommand` builds
+ * (`pkg@v`), and each replaces an installed version with it. pip goes through
+ * the resolved installer's own `pin`. brew installs only its newest version, so
+ * there is nothing to return — the planner never asks for it (a brew pin below
+ * the installed version is reported, not planned).
+ *
+ * Null also when the requirement carries no pin.
+ */
+export function binPinCommand(
+	bin: {
+		name: string;
+		via: BinInstaller;
+		package?: string;
+		formula?: string;
+		module?: string;
+		version?: string;
+	},
+	python: PythonCliInstaller = resolvePythonCliInstaller(),
+): Command | null {
+	if (!bin.version) return null;
+	switch (bin.via) {
+		case "bun":
+		case "npm":
+		case "go":
+			return binInstallCommand(bin, python);
+		case "pip":
+			return python.pin(bin.package ?? bin.name, bin.version);
+		case "brew":
+			return null;
+	}
+}
+
+/**
+ * Which of the three builders a requirement in a given state needs.
+ *
+ * THE one rule that turns a state into a command, so a front end cannot show
+ * one target and run another. It was written twice before: `binCommandFor`
+ * (`update-engine.ts`) for `magus update`, and the CLI Tools screen's row,
+ * which always built `@latest` — so a row reading `→ v9.0.0` (the pin) ran
+ * `bun install -g pkg@latest` and left the tool permanently ahead of its pin,
+ * a state magus cannot leave. Both now come through here.
+ *
+ * `install` → {@link binInstallCommand} (which appends the pin, when there is
+ * one). An upgrade whose target IS the pin → {@link binPinCommand}, because
+ * {@link binUpgradeCommand} would overshoot it. Any other upgrade → the newest
+ * version.
+ *
+ * Null only when no sound command exists: a pinned brew formula, where brew
+ * installs its newest version and nothing else (the pin is advisory).
+ */
+export function binCommandForState(
+	state: "install" | "upgrade",
+	target: string | null,
+	bin: {
+		name: string;
+		via: BinInstaller;
+		package?: string;
+		formula?: string;
+		module?: string;
+		version?: string;
+	},
+	python: PythonCliInstaller = resolvePythonCliInstaller(),
+): Command | null {
+	if (state === "install") return binInstallCommand(bin, python);
+	if (bin.version && target === bin.version) return binPinCommand(bin, python);
+	return binUpgradeCommand(bin, python);
+}
+
+/**
+ * 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 { cmd: "bun", args: ["remove", "-g", pkg] };
+		case "npm":
+			return { cmd: "npm", args: ["uninstall", "-g", pkg] };
+		case "pip":
+			return python.uninstall(pkg);
+		case "brew":
+			return { cmd: "brew", args: ["uninstall", bin.formula ?? bin.name] };
+		case "go":
+			return null;
+	}
+}