magus-cli 7.8.0 → 7.9.1

package/src/services/toolchain.ts

@@ -1,16 +1,28 @@
 /**
- * Toolchain detection + bootstrap for the package managers a profile's binary
- * deps need (bun, brew, npm, pip, go).
+ * The commands that install, upgrade, pin and remove a version-managed tool
+ * (bun, brew, npm, pip, go), and the bridge between a requirement and that
+ * version-managed view.
  *
- * `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.
+ * Installing a requirement goes through requires-probe's `renderInstall` and
+ * the deps executor (`services/deps-plan.ts`); this module builds only what
+ * `magus update` and the CLI Tools screen run beyond a first install.
  */
 
-import type { BinInstaller, ResolvedBin } from "../types/index.js";
+import {
+	type InstallOption,
+	assertNever,
+	currentPlatform,
+	renderInstall,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type {
+	BinInstaller,
+	ManagedBin,
+	ManagedTool,
+	ResolvedBin,
+	SelectedBin,
+} from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
-import { which, whichSync } from "../utils/command-utils.js";
+import { whichSync } from "../utils/command-utils.js";
 
 // -- Python CLI applications -------------------------------------------------
 
@@ -160,125 +172,119 @@ export function resetPythonCliInstallerMemo(): void {
 }
 
 // ----------------------------------------------------------------------------
+//
+// The version-managed view of a requirement.
+//
+// A requirement (plugin `requires`, or a profile cliTool mapped onto the
+// profile-only kinds) is installed by requires-probe's `renderInstall` and the
+// deps executor. `magus update` and the CLI Tools screen additionally track
+// the installed VERSION of the kinds that have one — bun, brew, npm, pip, go —
+// and they work in the {@link ManagedTool} shape. These functions are the one
+// bridge between the two, in both directions.
 
-/**
- * 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;
-}
+const pinned = (version: string | undefined) => (version ? { version } : {});
 
 /**
- * Determine which toolchains a resolved closure's binary deps require, and
- * whether each is present. Only toolchains actually needed are returned.
+ * The version-managed view of a selected requirement, or null when its chosen
+ * option is not one of the {@link BinInstaller} kinds (apt, release,
+ * bootstrap, uv-script, uv-module: their version is the declaration's, and
+ * `magus doctor --fix` installs them).
  */
-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);
+export function managedTool(bin: SelectedBin): ManagedTool | null {
+	const option = bin.chosen;
+	if (!option) return null;
+	const check = bin.check.join(" ");
+	switch (option.via) {
+		case "bun":
+		case "npm":
+		case "pip":
+			return {
+				name: bin.name,
+				via: option.via,
+				package: option.package,
+				check,
+				...pinned(option.version),
+			};
+		case "go":
+			return {
+				name: bin.name,
+				via: "go",
+				module: option.package,
+				check,
+				...pinned(option.version),
+			};
+		case "brew":
+			// A cask is installed, upgraded and removed with `--cask`, which the
+			// version-managed view does not speak: its declaration manages it.
+			return option.cask !== undefined
+				? null
+				: { name: bin.name, via: "brew", formula: option.formula, check };
+		case "apt":
+		case "release":
+		case "bootstrap":
+		case "uv-script":
+		case "uv-module":
+			return null;
+		default:
+			return assertNever(option);
 	}
+}
 
-	const statuses: ToolchainStatus[] = [];
-	for (const [name, names] of requiredBy) {
-		statuses.push({
-			name,
-			present: await isToolchainPresent(name),
-			requiredBy: names,
-			bootstrap: TOOLCHAIN_BOOTSTRAP[name],
-		});
+/** {@link managedTool} over a closure's bins, keeping each one's provenance. */
+export function managedBins(bins: readonly ResolvedBin[]): ManagedBin[] {
+	const out: ManagedBin[] = [];
+	for (const bin of bins) {
+		const tool = managedTool(bin);
+		if (tool) out.push({ ...tool, sources: [...bin.sources] });
 	}
-	// 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;
+	return out;
 }
 
-/**
- * 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) {
+/** The install option a {@link ManagedTool} stands for. */
+export function managedOption(t: ManagedTool): InstallOption {
+	switch (t.via) {
+		case "brew":
+			return { via: "brew", formula: t.formula ?? t.name };
+		case "go":
+			return { via: "go", package: t.module ?? t.name, ...pinned(t.version) };
 		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"}`,
-				],
+				via: t.via,
+				package: t.package ?? t.name,
+				...pinned(t.version),
 			};
+		default:
+			return assertNever(t.via);
+	}
+}
+
+/**
+ * The command that installs a {@link ManagedTool}, rendered by requires-probe's
+ * `renderInstall` — the one renderer every install goes through — so the pin
+ * travels in the same token (`pkg@version`, `pkg==version`) it does there.
+ */
+export function managedInstallCommand(t: ManagedTool): Command {
+	const step = renderInstall(
+		{ name: t.name, check: [], install: [] },
+		managedOption(t),
+		{
+			...(currentPlatform() ?? { os: "linux", arch: "amd64" }),
+			pluginRoot: "",
+		},
+	);
+	if (step.kind !== "argv") {
+		throw new Error(`${t.via} renders a ${step.kind} step, not a command`);
 	}
+	const [cmd = "", ...args] = step.argv;
+	return { cmd, args };
 }
 
 /**
  * The command that advances an ALREADY-INSTALLED binary to the newest version.
  *
- * Distinct from {@link binInstallCommand} because two of the five installers
+ * Distinct from {@link managedInstallCommand} 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
@@ -363,7 +369,7 @@ export function claudeNativeUpgradeCommand(pin?: string): Command {
  * {@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
+ * bun, npm and go take the version in the same token `managedInstallCommand` 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
@@ -387,7 +393,7 @@ export function binPinCommand(
 		case "bun":
 		case "npm":
 		case "go":
-			return binInstallCommand(bin, python);
+			return managedInstallCommand(bin);
 		case "pip":
 			return python.pin(bin.package ?? bin.name, bin.version);
 		case "brew":
@@ -405,7 +411,7 @@ export function binPinCommand(
  * `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
+ * `install` → {@link managedInstallCommand} (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.
@@ -426,7 +432,7 @@ export function binCommandForState(
 	},
 	python: PythonCliInstaller = resolvePythonCliInstaller(),
 ): Command | null {
-	if (state === "install") return binInstallCommand(bin, python);
+	if (state === "install") return managedInstallCommand(bin);
 	if (bin.version && target === bin.version) return binPinCommand(bin, python);
 	return binUpgradeCommand(bin, python);
 }

package/src/services/update-engine.ts

@@ -20,7 +20,7 @@
  * So the engine lives here, in `services/`, and both front ends drive it.
  * `cli/` and `ui/` are sibling presentation layers: they own how progress looks
  * and nothing else. Everything IO-shaped is injected — `PluginApplyDeps` for
- * the five Claude Code calls, `ApplyReporter` for progress, `runCommand` for
+ * the five Claude Code calls, `ApplyReporter` for progress, `runArgv` for
  * installers — so the same code drives an animated terminal meter, a TUI modal,
  * and a test that wants silence.
  *
@@ -32,13 +32,13 @@
 import path from "node:path";
 import type {
 	InstalledPluginEntry,
+	ManagedBin,
 	ProfileSkillRef,
-	ResolvedBin,
 	SkillInfo,
 } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import { formatCommand } from "../utils/command-utils.js";
-import { runCommand } from "../utils/run.js";
+import { runArgv, succeeded } from "../utils/run.js";
 import type { PluginScope } from "./claude-cli.js";
 import {
 	installPlugin,
@@ -158,10 +158,10 @@ export interface ApplyReporter {
 	/**
 	 * Run `work` with the terminal released.
 	 *
-	 * A binary upgrade spawns `brew`/`uv` with inherited stdio: it writes and
-	 * moves the cursor itself, so any animated block must be erased first or the
-	 * two interleave into garbage. A TUI implementation suspends its renderer;
-	 * a silent one just awaits.
+	 * The installer's output is captured (`runArgv`), so nothing a child
+	 * prints reaches the terminal; an implementation pauses its animation for
+	 * the duration only so the meter does not tick over a step that has no
+	 * progress of its own to show. A silent one just awaits.
 	 */
 	detach<T>(work: () => Promise<T>): Promise<T>;
 }
@@ -1128,7 +1128,7 @@ export async function updatePluginInScope(
  */
 export function binCommandFor(
 	item: BinUpdateItem,
-	spec: ResolvedBin,
+	spec: ManagedBin,
 ): Command | null {
 	if (!binNeedsWork(item)) return null;
 	if (item.action === "upgrade" && item.upgradeCommand)
@@ -1185,7 +1185,14 @@ function binNoMove(item: BinUpdateItem, after: ToolFacts): string | null {
  * which R6 counts as changed — the safe answer, but never "no change — still
  * 3.7c", the one the user needs.
  */
-const REAL_READ_BACK = (spec: ResolvedBin): Promise<ToolFacts> =>
+/** How long one `magus update` installer may run before it is stopped. */
+const INSTALLER_TIMEOUT_MS = 15 * 60_000;
+
+/** The default installer runner: argv, output captured, true on success. */
+const runInstaller = async (command: Command): Promise<boolean> =>
+	succeeded(await runArgv(command, { timeoutMs: INSTALLER_TIMEOUT_MS }));
+
+const REAL_READ_BACK = (spec: ManagedBin): Promise<ToolFacts> =>
 	probeTool(spec, undefined, { allowCheckCommand: true });
 
 export async function applyBins(
@@ -1195,9 +1202,9 @@ export async function applyBins(
 	// profile-supplied package name reach `/bin/sh`: a seam called "shell" reads
 	// as an invitation to hand it a string. It takes argv, and nothing here
 	// builds a shell line.
-	run: (command: Command) => Promise<boolean> = runCommand,
+	run: (command: Command) => Promise<boolean> = runInstaller,
 	/** Read-back seam: re-probe ONE tool after its installer ran. */
-	probe: (spec: ResolvedBin) => Promise<ToolFacts> = REAL_READ_BACK,
+	probe: (spec: ManagedBin) => Promise<ToolFacts> = REAL_READ_BACK,
 ): Promise<ApplyResult> {
 	const result: ApplyResult = { ok: 0, failed: [], unchanged: [] };
 	for (const item of plan.bins) {
@@ -1222,8 +1229,6 @@ export async function applyBins(
 			result.failed.push(item.name);
 			continue;
 		}
-		// The installer owns the terminal for the duration: it streams its own
-		// output through inherited stdio.
 		const succeeded = await report.detach(() => run(cmd));
 		if (!succeeded) {
 			report.finish(
@@ -1315,7 +1320,7 @@ export interface ApplyPlanOptions {
 	/** Installer execution seam — see the note on {@link applyBins}. */
 	run?: (command: Command) => Promise<boolean>;
 	/** Read-back seam — see {@link applyBins}. Default: `probeTool(spec)`. */
-	probe?: (spec: ResolvedBin) => Promise<ToolFacts>;
+	probe?: (spec: ManagedBin) => Promise<ToolFacts>;
 }
 
 /**

package/src/services/update-plan.ts

@@ -28,7 +28,7 @@
  * (`unknown`) rather than folding into `current`.
  */
 
-import type { ProfileSkillRef, ResolvedBin } from "../types/index.js";
+import type { ManagedBin, ProfileSkillRef } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import type { PluginScope } from "./claude-cli.js";
 import {
@@ -1061,7 +1061,7 @@ export interface BinUpdateItem {
  * that is `unknown` too — "not checked" is not "fine".
  */
 export function planBinUpdates(
-	bins: ResolvedBin[],
+	bins: ManagedBin[],
 	facts: readonly ToolFacts[],
 ): BinUpdateItem[] {
 	const byName = new Map(facts.map((f) => [f.name, f]));
@@ -1147,7 +1147,7 @@ export interface UpdatePlan {
 	 * only the decision; the installer command needs `via`/`package`/`formula`,
 	 * and re-deriving those from a name would guess.
 	 */
-	binSpecs: Map<string, ResolvedBin>;
+	binSpecs: Map<string, ManagedBin>;
 }
 
 /**

package/src/shared/plugin/hooks/bun-missing.sh

@@ -0,0 +1,64 @@
+#!/bin/sh
+# SessionStart (matcher `startup`) fallback for deps-check.ts. The registration
+# runs this only when Bun is not on the PATH Claude Code started with, which is
+# the one dependency the TypeScript check cannot report itself. $1 is the label.
+#
+# Writes the same ledger as deps-check.ts, 0700: seen/<label> = sh, then claims
+# the Bun requirement's dedupe key, so a session prints one Bun line however
+# many plugins carry this file. A bun in a place an installer or Homebrew puts
+# one is reported as off the PATH, naming that place; only when there is none
+# is Bun called missing. scripts/check-hook-copies.ts recomputes the key, the
+# install line, the Bun prefix and the PATH line formats from
+# lib/requires-probe.ts and fails when this file disagrees. Exit 0 always.
+
+label=$1
+case $label in
+'' | *[!a-z0-9._-]*) exit 0 ;;
+esac
+key=bun-3182ab42b0f1
+
+sid=$(cat 2>/dev/null | tr -d '\n' | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([A-Za-z0-9_-]*\)".*/\1/p')
+if [ -n "$sid" ]; then
+	umask 077
+	base=${TMPDIR:-/tmp}
+	dir=$base/magus-deps-$sid
+	if mkdir -p "$dir/seen" "$dir/claimed" 2>/dev/null; then
+		printf sh >"$dir/seen/$label" 2>/dev/null
+		find "$base" -maxdepth 1 -type d -name 'magus-deps-*' -mtime +0 -exec rm -rf {} + 2>/dev/null
+		mkdir "$dir/claimed/$key" 2>/dev/null || exit 0
+	fi
+fi
+
+# The first bun where an installer or Homebrew leaves one. A path that would
+# break the JSON line is skipped.
+found=
+for d in ${BUN_INSTALL:+"$BUN_INSTALL/bin"} "$HOME/.bun/bin" /opt/homebrew/bin /usr/local/bin /home/linuxbrew/.linuxbrew/bin; do
+	case $d in
+	*\"* | *\\* | *[[:cntrl:]]*) continue ;;
+	esac
+	if [ -f "$d/bun" ] && [ -x "$d/bun" ]; then
+		found=$d
+		break
+	fi
+done
+
+if [ -n "$found" ]; then
+	# Under $HOME: shown as ~/…, and $HOME in the PATH line.
+	rel=${found#"$HOME"/}
+	if [ -n "$HOME" ] && [ "$HOME" != / ] && [ "$rel" != "$found" ]; then
+		shown="~/$rel" pathdir="\$HOME/$rel"
+	else
+		shown=$found pathdir=$found
+	fi
+	case ${SHELL:-} in
+	*zsh) rc='~/.zshrc' fmt='export PATH="%s:$PATH"' ;;
+	*fish) rc='~/.config/fish/config.fish' fmt='fish_add_path %s' ;;
+	*) rc='~/.bashrc' fmt='export PATH="%s:$PATH"' ;;
+	esac
+	# shellcheck disable=SC2059 # fmt is one of the three fixed formats above
+	line=$(printf "$fmt" "$pathdir" | sed 's/["\\]/\\&/g')
+	printf '{"systemMessage":"magus-deps: Bun is installed at %s but is not on the PATH Claude Code started with, so magus hooks and MCP servers cannot run (noticed by %s).\\n  Add %s to %s, then restart Claude Code from a new terminal."}\n' "$shown" "$label" "$line" "$rc"
+else
+	printf '{"systemMessage":"magus-deps: Bun is missing — magus hooks and MCP servers need it (noticed by %s).\\n  Install: curl -fsSL https://bun.sh/install | bash, then restart Claude Code from a new terminal."}\n' "$label"
+fi
+exit 0