claudeup 6.0.0 → 6.2.0

package/src/ui/screens/CliToolsScreen.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useCallback, useState, useRef } from "react";
-import { exec } from "child_process";
+import { exec, execFile } from "child_process";
 import { promisify } from "util";
 import { useApp, useModal } from "../state/AppContext.js";
 import { useDimensions } from "../state/DimensionsContext.js";
@@ -7,16 +7,24 @@ import { useKeyboard } from "../hooks/useKeyboard.js";
 import { ScreenLayout } from "../components/layout/index.js";
 
 import { cliTools } from "../../data/cli-tools.js";
+import {
+	type InstallMethod,
+	cliToolInstall,
+	cliToolUninstall,
+	cliToolUpdate,
+} from "../../services/cli-tool-commands.js";
+import type { Command } from "../../utils/command-utils.js";
+import { formatCommand } from "../../utils/command-utils.js";
 import {
 	renderCliToolRow,
 	renderCliToolDetail,
 	type CliToolStatus,
-	type InstallMethod,
 } from "../renderers/cliToolRenderers.js";
 import { ScrollableList } from "../components/ScrollableList.js";
 import { theme } from "../theme.js";
 
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 // ─── Version helpers ───────────────────────────────────────────────────────────
 
@@ -123,52 +131,6 @@ async function detectInstallMethods(
 	}
 }
 
-function getUninstallCommand(
-	tool: import("../../data/cli-tools.js").CliTool,
-	method: InstallMethod,
-	brewFormula?: string,
-): string {
-	switch (method) {
-		case "bun":
-			return `bun remove -g ${tool.packageName}`;
-		case "npm":
-			return `npm uninstall -g ${tool.packageName}`;
-		case "pnpm":
-			return `pnpm remove -g ${tool.packageName}`;
-		case "yarn":
-			return `yarn global remove ${tool.packageName}`;
-		case "brew":
-			return `brew uninstall ${brewFormula || tool.name}`;
-		case "pip":
-			return `pip uninstall -y ${tool.packageName}`;
-		default:
-			return "";
-	}
-}
-
-function getUpdateCommand(
-	tool: import("../../data/cli-tools.js").CliTool,
-	method: InstallMethod,
-	brewFormula?: string,
-): string {
-	switch (method) {
-		case "bun":
-			return `bun install -g ${tool.packageName}`;
-		case "npm":
-			return `npm install -g ${tool.packageName}`;
-		case "pnpm":
-			return `pnpm install -g ${tool.packageName}`;
-		case "yarn":
-			return `yarn global add ${tool.packageName}`;
-		case "brew":
-			return `brew upgrade ${brewFormula || tool.name}`;
-		case "pip":
-			return tool.installCommand;
-		default:
-			return tool.installCommand;
-	}
-}
-
 async function getInstalledVersion(
 	tool: import("../../data/cli-tools.js").CliTool,
 ): Promise<string | undefined> {
@@ -194,16 +156,40 @@ async function getLatestNpmVersion(
 	}
 }
 
+/**
+ * Pick the version out of a PyPI JSON API body.
+ *
+ * Split out from the fetch so it is testable without a network: the parsing is
+ * the part that can be wrong, and the part that must not throw.
+ */
+export function versionFromPypiJson(body: unknown): string | undefined {
+	const info = (body as { info?: { version?: unknown } } | null)?.info;
+	return typeof info?.version === "string" ? info.version : undefined;
+}
+
+/**
+ * Latest published version of a Python package, straight from PyPI.
+ *
+ * Was `pip index versions <pkg> | head -1` through a shell, which had three
+ * independent problems and only needed one to fail: `pip` is often not an
+ * executable at all (the bug this whole change exists for), `pip index` is an
+ * experimental subcommand upstream reserves the right to change, and a machine
+ * managing its Python tools with uv or pipx may carry no `pip` whatsoever.
+ *
+ * An HTTP GET needs none of them. Failure mode is unchanged — undefined, so the
+ * row simply shows no update badge — because a version check is advisory and
+ * must never take the screen down with it.
+ */
 async function getLatestPipVersion(
 	packageName: string,
 ): Promise<string | undefined> {
 	try {
-		const { stdout } = await execAsync(
-			`pip index versions ${packageName} 2>/dev/null | head -1`,
-			{ timeout: 10000, shell: "/bin/bash" },
+		const res = await fetch(
+			`https://pypi.org/pypi/${encodeURIComponent(packageName)}/json`,
+			{ signal: AbortSignal.timeout(10000) },
 		);
-		const match = stdout.trim().match(/\(([^)]+)\)/);
-		return match ? match[1] : undefined;
+		if (!res.ok) return undefined;
+		return versionFromPypiJson(await res.json());
 	} catch {
 		return undefined;
 	}
@@ -292,7 +278,7 @@ export function CliToolsScreen() {
 					installMethod: version ? info.primary : undefined,
 					allMethods: version && info.all.length > 1 ? info.all : undefined,
 					updateCommand: version
-						? getUpdateCommand(tool, info.primary, info.brewFormula)
+						? (cliToolUpdate(tool, info.primary, info.brewFormula) ?? undefined)
 						: undefined,
 					brewFormula: info.brewFormula,
 				});
@@ -345,14 +331,20 @@ export function CliToolsScreen() {
 		fetchVersionInfo();
 	};
 
+	/**
+	 * Run one installer command and report success.
+	 *
+	 * `execFile`, so there is no shell to re-parse a package name — the same
+	 * reason `utils/run.ts` exists. It does NOT call that shared `runCommand`:
+	 * that one inherits stdio, and a TUI must never hand the terminal to a
+	 * child. Output is captured and discarded here; the modal is the progress
+	 * indicator.
+	 */
 	const runCommand = async (
-		command: string,
+		command: Command,
 	): Promise<{ ok: boolean; error?: string }> => {
 		try {
-			await execAsync(command, {
-				shell: "/bin/bash",
-				timeout: 60000,
-			});
+			await execFileAsync(command.cmd, [...command.args], { timeout: 60000 });
 			return { ok: true };
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
@@ -371,7 +363,7 @@ export function CliToolsScreen() {
 				? "Updating"
 				: "Reinstalling";
 		const command =
-			installed && updateCommand ? updateCommand : tool.installCommand;
+			installed && updateCommand ? updateCommand : cliToolInstall(tool);
 
 		modal.loading(`${action} ${tool.displayName}...`);
 		const result = await runCommand(command);
@@ -382,7 +374,7 @@ export function CliToolsScreen() {
 		} else {
 			await modal.message(
 				"Error",
-				`Failed to ${action.toLowerCase()} ${tool.displayName}.\n\nTry running manually:\n${command}`,
+				`Failed to ${action.toLowerCase()} ${tool.displayName}.\n\nTry running manually:\n${formatCommand(command)}`,
 				"error",
 			);
 		}
@@ -412,10 +404,10 @@ export function CliToolsScreen() {
 
 		const errors: string[] = [];
 		for (const method of toRemove) {
-			const cmd = getUninstallCommand(tool, method, brewFormula);
+			const cmd = cliToolUninstall(tool, method, brewFormula);
 			if (!cmd) continue;
 			const result = await runCommand(cmd);
-			if (!result.ok) errors.push(`${method}: ${cmd}`);
+			if (!result.ok) errors.push(`${method}: ${formatCommand(cmd)}`);
 		}
 
 		modal.hideModal();
@@ -445,7 +437,7 @@ export function CliToolsScreen() {
 		modal.loading(`Updating ${updatable.length} tool(s)...`);
 
 		for (const status of updatable) {
-			const command = status.updateCommand || status.tool.installCommand;
+			const command = status.updateCommand || cliToolInstall(status.tool);
 			await runCommand(command);
 		}
 

package/src/ui/screens/PluginsScreen.tsx

@@ -7,19 +7,26 @@ import {
 import {
 	type PluginScope,
 	addMarketplace as cliAddMarketplace,
-	installPlugin as cliInstallPlugin,
 	repairPlugin as cliRepairPlugin,
 	uninstallPlugin as cliUninstallPlugin,
-	updatePlugin as cliUpdatePlugin,
 } from "../../services/claude-cli.js";
 import {
 	getMcpEnvVars,
 	readSettings,
-	saveGlobalInstalledPluginVersion,
-	saveLocalInstalledPluginVersion,
 	setMcpEnvVar,
 } from "../../services/claude-settings.js";
 import { clearContentDriftCache } from "../../services/content-drift.js";
+// The one update implementation, shared with `claudeup update`. See the header
+// of update-engine.ts for what drifted while the TUI had its own loop.
+import {
+	type ApplyReporter,
+	REAL_PLUGIN_DEPS,
+	applyPlugins,
+	pluginNeedsWork,
+	installPluginInScope,
+	updatePluginInScope,
+} from "../../services/update-engine.js";
+import { planPluginUpdates } from "../../services/update-plan.js";
 import {
 	type MarketplaceFetchFailure,
 	type PluginInfo,
@@ -31,7 +38,6 @@ import {
 	isInstalledInScope,
 	refreshAllMarketplaces,
 	resolveScopeAction,
-	saveInstalledPluginVersion,
 } from "../../services/plugin-manager.js";
 import {
 	getPluginEnvRequirements,
@@ -516,29 +522,6 @@ export function PluginsScreen() {
 
 	// ── Helpers ───────────────────────────────────────────────────────────────
 
-	/**
-	 * Save the installed plugin version to the correct settings file for the scope.
-	 * The Claude CLI's `plugin install` does NOT update installedPluginVersions,
-	 * so claudeup must do it after a successful CLI install/update.
-	 */
-	const saveVersionForScope = async (
-		pluginId: string,
-		version: string,
-		scope: PluginScope,
-	): Promise<void> => {
-		if (scope === "user") {
-			await saveGlobalInstalledPluginVersion(pluginId, version);
-		} else if (scope === "local") {
-			await saveLocalInstalledPluginVersion(
-				pluginId,
-				version,
-				state.projectPath,
-			);
-		} else {
-			await saveInstalledPluginVersion(pluginId, version, state.projectPath);
-		}
-	};
-
 	/**
 	 * Check for version mismatch after a plugin update and show the
 	 * interactive mismatch modal with a "Fix all projects" button.
@@ -947,14 +930,29 @@ export function PluginsScreen() {
 					modal.loading(
 						`Updating ${plugin.name} in ${scopeLabel}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 					);
-					await cliUpdatePlugin(plugin.id, scope);
-					await saveVersionForScope(plugin.id, latestVersion, scope);
+					// Scope is the user's explicit choice here, so this does NOT go
+					// through applyPlugins (which advances every scope behind). It
+					// still records the version READ BACK, not `latestVersion`.
+					await updatePluginInScope(
+						plugin.id,
+						scope,
+						state.projectPath || process.cwd(),
+					);
 				} else {
 					modal.loading(
 						`Installing ${plugin.name} to ${scopeLabel}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 					);
-					await cliInstallPlugin(plugin.id, scope);
-					await saveVersionForScope(plugin.id, latestVersion, scope);
+					// Same read-back as the update branch above. A fresh install is
+					// no more able to guarantee it got `latestVersion` than an
+					// update is — the marketplace serves whatever it publishes at
+					// the moment of the call — so recording the version we asked
+					// for made `install --check` compare that number against a copy
+					// of itself and report clean forever.
+					await installPluginInScope(
+						plugin.id,
+						scope,
+						state.projectPath || process.cwd(),
+					);
 					modal.hideModal();
 					await collectPluginEnvVars(plugin.name, plugin.marketplace);
 					await installPluginSystemDeps(plugin.name, plugin.marketplace);
@@ -993,15 +991,30 @@ export function PluginsScreen() {
 				: `Updating ${plugin.name}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 		);
 		try {
-			if (repairing) {
-				await cliRepairPlugin(plugin.id, scope, state.projectPath);
-			} else {
-				await cliUpdatePlugin(plugin.id, scope);
-			}
-			if (plugin.version) {
-				await saveVersionForScope(plugin.id, plugin.version, scope);
-			}
+			// One plugin, but the SAME engine — so a single update records the
+			// version that landed and touches every scope that is behind, exactly
+			// as `claudeup update` does. `repairing` is not re-derived here: the
+			// planner already encodes it as the `repair` action.
+			const catalog = new Map(
+				pluginsState.plugins.status === "success"
+					? pluginsState.plugins.data.map((p) => [p.id, p] as const)
+					: [[plugin.id, plugin] as const],
+			);
+			const items = planPluginUpdates({ [plugin.id]: "latest" }, catalog);
+			const result = await applyPlugins(
+				items,
+				state.projectPath || process.cwd(),
+				REAL_PLUGIN_DEPS,
+			);
 			modal.hideModal();
+			if (result.failed.length > 0) {
+				await modal.message(
+					"Error",
+					`Failed to update ${plugin.name}`,
+					"error",
+				);
+				return;
+			}
 			await warnIfVersionMismatch(plugin.id);
 			fetchData();
 		} catch (error) {
@@ -1010,6 +1023,18 @@ export function PluginsScreen() {
 		}
 	};
 
+	/**
+	 * "Update all" — the SAME planner and the SAME apply engine `claudeup
+	 * update` runs. Only the selection differs, and only because a screen and a
+	 * profile genuinely mean different sets: here it is "everything listed with
+	 * an update", there it is "what the profile declares".
+	 *
+	 * This used to be a hand-rolled loop, and it had drifted from the CLI in
+	 * three ways that were bugs, not choices — it touched one scope derived from
+	 * the open tab, it recorded the version it EXPECTED rather than the one that
+	 * landed, and it never reported a pin the installer could not honour. All
+	 * three are fixed by not having a second implementation.
+	 */
 	const handleUpdateAll = async () => {
 		if (pluginsState.plugins.status !== "success") return;
 
@@ -1020,30 +1045,45 @@ export function PluginsScreen() {
 		);
 		if (updatable.length === 0) return;
 
-		const scope: PluginScope =
-			pluginsState.scope === "global" ? "user" : "project";
-		const updatedPluginIds: string[] = [];
+		const projectPath = state.projectPath || process.cwd();
+		// The screen's own list IS the catalog the planner needs.
+		const catalog = new Map(pluginsState.plugins.data.map((p) => [p.id, p]));
+		const items = planPluginUpdates(
+			Object.fromEntries(updatable.map((p) => [p.id, "latest"])),
+			catalog,
+		);
+		const total = items.filter(pluginNeedsWork).length;
+
+		let done = 0;
+		const reporter: ApplyReporter = {
+			begin: (name) => {
+				done++;
+				modal.loading(`Updating ${name} (${done}/${total})…`);
+			},
+			finish: () => {},
+			detach: (work) => work(),
+		};
 
 		try {
-			for (let i = 0; i < updatable.length; i++) {
-				const plugin = updatable[i];
-				const repairing = !plugin.hasUpdate && plugin.contentStale;
-				modal.loading(
-					`${repairing ? "Repairing" : "Updating"} ${plugin.name} (${i + 1}/${updatable.length})…\nclaude plugin install ${plugin.id} --scope ${scope}`,
+			const result = await applyPlugins(
+				items,
+				projectPath,
+				REAL_PLUGIN_DEPS,
+				reporter,
+			);
+			const updatedPluginIds = items
+				.filter(pluginNeedsWork)
+				.map((i) => i.pluginId)
+				.filter((id) => !result.failed.includes(id));
+			modal.hideModal();
+			if (result.failed.length > 0) {
+				await modal.message(
+					"Some updates failed",
+					result.failed.join(", "),
+					"error",
 				);
-				if (repairing) {
-					await cliRepairPlugin(plugin.id, scope, state.projectPath);
-				} else {
-					await cliUpdatePlugin(plugin.id, scope);
-				}
-				if (plugin.version) {
-					await saveVersionForScope(plugin.id, plugin.version, scope);
-				}
-				updatedPluginIds.push(plugin.id);
 			}
-			modal.hideModal();
 			// Batch mismatch checks into a single modal
-			const projectPath = state.projectPath || process.cwd();
 			const allMismatches: VersionMismatchInfo[] = [];
 			for (const pluginId of updatedPluginIds) {
 				try {
@@ -1122,14 +1162,22 @@ export function PluginsScreen() {
 				modal.loading(
 					`Updating ${plugin.name} in ${scopeLabel}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 				);
-				await cliUpdatePlugin(plugin.id, scope);
-				await saveVersionForScope(plugin.id, latestVersion, scope);
+				// Explicit scope, read-back version — see the note above.
+				await updatePluginInScope(
+					plugin.id,
+					scope,
+					state.projectPath || process.cwd(),
+				);
 			} else {
 				modal.loading(
 					`Installing ${plugin.name} to ${scopeLabel}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 				);
-				await cliInstallPlugin(plugin.id, scope);
-				await saveVersionForScope(plugin.id, latestVersion, scope);
+				// Read-back on install too — see the note on the same branch above.
+				await installPluginInScope(
+					plugin.id,
+					scope,
+					state.projectPath || process.cwd(),
+				);
 				modal.hideModal();
 				await collectPluginEnvVars(plugin.name, plugin.marketplace);
 				await installPluginSystemDeps(plugin.name, plugin.marketplace);
@@ -1206,7 +1254,15 @@ export function PluginsScreen() {
 					modal.loading(
 						`Installing ${newId} (${scope})…\nclaude plugin install ${newId} --scope ${scope}`,
 					);
-					await cliInstallPlugin(newId, scope);
+					// The migrated id is a plugin claudeup has never recorded a
+					// version for, so going through the read-back is what stops the
+					// rename leaving it permanently version-less — a plugin with no
+					// recorded version never reports an available update.
+					await installPluginInScope(
+						newId,
+						scope,
+						state.projectPath || process.cwd(),
+					);
 				}
 			}
 

package/src/utils/command-utils.ts

@@ -1,10 +1,74 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { access, realpath } from "node:fs/promises";
-import { constants } from "node:fs";
+import { accessSync, constants, statSync } from "node:fs";
+import { join } from "node:path";
 
 const execFileAsync = promisify(execFile);
 
+/**
+ * A command as an executable plus its already-separated arguments.
+ *
+ * The alternative — a single string handed to `/bin/sh` — has cost this
+ * codebase twice, in two different ways, and both were shipped rather than
+ * hypothetical:
+ *
+ *  1. **A word the shell could not resolve.** `pip install <pkg>` died with
+ *     `/bin/sh: pip: command not found` on machines where `pip` is only an
+ *     interactive-zsh alias. `services/toolchain.ts` fixed *which word* gets
+ *     emitted; it could not fix that the words are re-parsed at spawn time.
+ *  2. **Package names are re-parsed as shell syntax.** The builders are fed
+ *     `bin.package` / `bin.formula` / `bin.module`, which come from
+ *     `.claude/profiles.json` and from plugin `requires.bin` — hand-authored,
+ *     committed by teammates, fetched from marketplaces. Under `shell: true`
+ *     those go through word-splitting and `$(…)` expansion. Today's catalogue is
+ *     benign; the surface is not, and nothing checks it.
+ *
+ * As argv there is no shell, so a package name is one token no matter what
+ * characters it contains, and `cmd` must name a real executable rather than
+ * anything PATH-plus-a-profile might have meant.
+ *
+ * `services/plugin-setup.ts` arrived at this same shape independently for the
+ * MCP dependency installer. This is the codebase agreeing with itself.
+ */
+export interface Command {
+	readonly cmd: string;
+	readonly args: readonly string[];
+}
+
+/**
+ * Characters that need no quoting in any POSIX shell.
+ *
+ * Deliberately conservative, and the reason {@link formatCommand} is display-
+ * neutral: every token claudeup actually builds — `@anthropic-ai/claude-code`,
+ * `claudish@1.2.0`, `aider==0.1`, `github.com/x/t@latest`, `--upgrade` — is
+ * made only of these, so quoting never fires for real input and the rendered
+ * string is byte-identical to the one this codebase printed before commands
+ * became argv. `doctor-bins.test.ts` is the gate on that claim.
+ */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+/**
+ * Render a {@link Command} as the shell line a human would type.
+ *
+ * FOR DISPLAY ONLY. Nothing may feed this back to a shell — that would undo the
+ * whole point of carrying argv. It exists so `doctor` can print "run: brew
+ * install tmux" and the updater can show what it is about to do.
+ *
+ * A token outside {@link SHELL_SAFE} is single-quoted, with `'` closed,
+ * escaped and reopened (`'\''`) — the only POSIX-portable escape, since single
+ * quotes have no escape character inside them. An empty token quotes too:
+ * unquoted it would vanish, which would misrepresent the argv it came from.
+ */
+export function formatCommand(c: Command): string {
+	return [c.cmd, ...c.args].map(quoteToken).join(" ");
+}
+
+function quoteToken(token: string): string {
+	if (SHELL_SAFE.test(token)) return token;
+	return `'${token.replaceAll("'", `'\\''`)}'`;
+}
+
 /**
  * Check if a command exists in PATH
  * Uses execFile (not exec) to avoid shell injection vulnerabilities
@@ -21,6 +85,43 @@ export async function which(command: string): Promise<string | null> {
 	}
 }
 
+/**
+ * Synchronous PATH lookup — walks `$PATH` rather than spawning `which(1)`.
+ *
+ * Synchronous on purpose. The installer-command builders in
+ * `services/toolchain.ts` are sync and used by printers; making them async just
+ * to answer "does this machine have uv?" would ripple through every caller.
+ *
+ * Node's `fs` is used rather than `Bun.which` so this needs no `@types/bun`,
+ * whose globals collide with `@types/node` in this project.
+ *
+ * Unlike {@link resolveExecutable} this does NOT follow symlinks to prove the
+ * target still exists — use it to pick between candidates, not to prove a
+ * binary works.
+ */
+export function whichSync(command: string): string | null {
+	// An explicit path is not a PATH lookup; honour it as given.
+	if (command.includes("/")) {
+		return isExecutableFile(command) ? command : null;
+	}
+	for (const dir of (process.env.PATH ?? "").split(":")) {
+		if (!dir) continue;
+		const candidate = join(dir, command);
+		if (isExecutableFile(candidate)) return candidate;
+	}
+	return null;
+}
+
+function isExecutableFile(p: string): boolean {
+	try {
+		if (!statSync(p).isFile()) return false;
+		accessSync(p, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Like {@link which}, but verifies the command actually RESOLVES and is
  * executable — a dangling symlink (e.g. a stale npx-cache link) returns null.

package/src/utils/run.ts

@@ -0,0 +1,67 @@
+/**
+ * Running an installer, with the shell split out from the argv.
+ *
+ * Lives in `utils/` rather than `cli/prompt.ts` because the update engine needs
+ * it and a service must not import from the CLI layer — `cli/` and `ui/` are
+ * sibling front ends over `services/`, and an arrow from a service back up into
+ * one of them is how the two front ends ended up with different update logic in
+ * the first place.
+ *
+ * Both functions live in ONE file on purpose: {@link runShellScript}'s doc only
+ * makes sense next to {@link runCommand}, because most of what it has to say is
+ * "you almost certainly want the other one".
+ */
+
+import { spawn } from "node:child_process";
+import type { Command } from "./command-utils.js";
+
+/**
+ * Run a built command as argv, streaming its output; true on exit 0.
+ *
+ * **This is the one every installer uses.** No `shell` option, so:
+ *
+ *  - `cmd` is resolved on PATH as an executable. There is no profile to source
+ *    and therefore no way for a shell alias to appear to work — the reason the
+ *    shipped `pip install` bug could exist at all was that `/bin/sh` was asked
+ *    to resolve a word that only interactive zsh knew.
+ *  - Every argument stays exactly one argument. Package names reach here from
+ *    `.claude/profiles.json` and plugin `requires.bin` — hand-authored data
+ *    committed by teammates and fetched from marketplaces — and under a shell a
+ *    space or a `$(…)` in one of them would have been executed. Nothing
+ *    validates those names, and after this nothing has to.
+ *
+ * stdio is inherited: the installer owns the terminal while it runs, which is
+ * what makes brew's and bun's own progress output visible. A caller painting an
+ * animated region must pause it around this (see `ApplyReporter.detach`).
+ */
+export async function runCommand(c: Command): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(c.cmd, [...c.args], { stdio: "inherit" });
+		child.on("exit", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}
+
+/**
+ * Run a shell SCRIPT through `/bin/sh`, streaming its output; true on exit 0.
+ *
+ * **Not for installer commands — use {@link runCommand}.** This exists for
+ * exactly one input: the values of `TOOLCHAIN_BOOTSTRAP`, which are the
+ * upstream-published one-liners for bun and Homebrew. Those genuinely are shell
+ * text — one contains a pipe, the other a command substitution — so they cannot
+ * be expressed as argv without wrapping them in a fake `/bin/sh -c` at the one
+ * place where a shell is actually correct.
+ *
+ * The distinction is who wrote the string. A bootstrap line is a constant in
+ * this repo, copied from bun.sh and brew.sh. An installer command is assembled
+ * from names that arrive with a profile. Passing the second kind here is the
+ * defect that motivated splitting the two, so
+ * `src/__tests__/shell-script-callers.test.ts` pins the caller set to one file.
+ */
+export async function runShellScript(script: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(script, { stdio: "inherit", shell: true });
+		child.on("exit", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}