magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/plugin-setup.ts

@@ -0,0 +1,965 @@
+/**
+ * Plugin system dependency installer
+ *
+ * Auto-detects available package managers and installs plugin dependencies
+ * declared in plugin.json's "setup" section.
+ *
+ * Supported managers:
+ * - pip: Python packages (auto-detects uv > pip3 > pip)
+ * - brew: Homebrew formulae (macOS/Linux)
+ * - npm: Global npm packages
+ * - cargo: Rust crates
+ * - go: Go modules (via go install)
+ *
+ * Special keys:
+ * - required: System binaries that must exist in PATH (not auto-installed)
+ *
+ * Example plugin.json:
+ * {
+ *   "setup": {
+ *     "pip": ["browser-use", "mcp"],
+ *     "brew": ["memextech/tap/ht-mcp"],
+ *     "go": ["github.com/MadAppGang/tmux-mcp@latest"],
+ *     "required": ["tmux"]
+ *   }
+ * }
+ */
+
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import fs from "fs-extra";
+import { which } from "../utils/command-utils.js";
+import { goBinaryName } from "../utils/go-module.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface SetupConfig {
+	pip?: string[];
+	brew?: string[];
+	npm?: string[];
+	cargo?: string[];
+	go?: string[];
+	required?: string[];
+}
+
+export interface SetupResult {
+	installed: string[];
+	skipped: string[];
+	failed: Array<{ pkg: string; error: string }>;
+}
+
+/**
+ * Run a command and return success/failure
+ */
+async function run(
+	cmd: string,
+	args: string[],
+	timeoutMs = 120000,
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+	try {
+		const { stdout, stderr } = await execFileAsync(cmd, args, {
+			timeout: timeoutMs,
+		});
+		return { ok: true, stdout: stdout.trim(), stderr: stderr.trim() };
+	} catch (error: unknown) {
+		const e = error as { stdout?: string; stderr?: string; message?: string };
+		return {
+			ok: false,
+			stdout: e.stdout?.trim() || "",
+			stderr: e.stderr?.trim() || e.message || "unknown error",
+		};
+	}
+}
+
+/**
+ * Detect the best available Python package installer
+ * Prefers: uv > pip3 > pip
+ */
+async function detectPipCommand(): Promise<{
+	cmd: string;
+	args: string[];
+} | null> {
+	// Prefer uv (fast, modern)
+	if (await which("uv")) {
+		return {
+			cmd: "uv",
+			args: ["pip", "install", "--system", "--break-system-packages"],
+		};
+	}
+	// Fall back to pip3
+	if (await which("pip3")) {
+		return {
+			cmd: "pip3",
+			args: ["install", "--break-system-packages"],
+		};
+	}
+	// Fall back to pip
+	if (await which("pip")) {
+		return {
+			cmd: "pip",
+			args: ["install", "--break-system-packages"],
+		};
+	}
+	return null;
+}
+
+/**
+ * Check if a binary is available in PATH
+ */
+async function isBinaryAvailable(name: string): Promise<boolean> {
+	return (await which(name)) !== null;
+}
+
+/** Last path segment, e.g. "memextech/tap/ht-mcp" → "ht-mcp". */
+function lastSegment(s: string): string {
+	return s.split("/").pop() || s;
+}
+
+/**
+ * Extract binary name from a brew formula.
+ *
+ * Brew's `@` is part of the FORMULA NAME, not a version pin — `node@18` is a
+ * distinct formula, not "node pinned to 18" — so the spec is installed verbatim
+ * while the binary it provides drops the suffix.
+ */
+export function extractBinaryName(pkg: string): string {
+	return lastSegment(pkg).replace(/@[^@/]*$/, "") || lastSegment(pkg);
+}
+
+/** A dependency spec split into what to install and what to verify. */
+export interface ParsedSpec {
+	/** The spec as declared, handed to the installer verbatim. */
+	spec: string;
+	/** Name used to locate the installed artifact. */
+	name: string;
+	/** Exact pinned version, or null when unpinned or a moving target. */
+	version: string | null;
+}
+
+/**
+ * Parse an `name@version` spec — the shared syntax of go, npm and cargo.
+ *
+ * A leading `@` is an npm SCOPE, not a version separator, so `@babel/cli` is
+ * unpinned while `@babel/cli@7.0.0` pins 7.0.0.
+ */
+export function parseAtSpec(spec: string): ParsedSpec {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return { spec, name: lastSegment(spec), version: null };
+
+	const version = spec.slice(at + 1).trim();
+	const name = lastSegment(spec.slice(0, at));
+	if (!version || version === "latest") return { spec, name, version: null };
+	return { spec, name, version };
+}
+
+/**
+ * Parse a pip requirement. Only `==` is an exact, verifiable pin; `>=`, `~=`
+ * and friends describe a range, so there is no single version to check against.
+ */
+export function parsePipSpec(spec: string): ParsedSpec {
+	const exact = spec.match(/^\s*([A-Za-z0-9._-]+)\s*==\s*([^\s;]+)/);
+	if (exact) return { spec, name: exact[1], version: exact[2] };
+	const name = spec.split(/[<>=!~[;\s]/)[0].trim();
+	return { spec, name: name || spec, version: null };
+}
+
+/**
+ * The installed version of a pip distribution, or null when absent/unreadable.
+ * Uses importlib.metadata rather than an import probe: it reports the VERSION,
+ * and it works for distributions whose import name differs from their package
+ * name (browser-use → browser_use).
+ */
+async function getPipInstalledVersion(name: string): Promise<string | null> {
+	const { ok, stdout } = await run("python3", [
+		"-c",
+		`import importlib.metadata as m; print(m.version(${JSON.stringify(name)}))`,
+	]);
+	if (!ok || !stdout) return null;
+	return normalizeVersion(stdout.split("\n")[0]);
+}
+
+/**
+ * Does this pip requirement still need installing? Present-but-wrong-version
+ * counts: without that, bumping a pin in plugin.json is inert.
+ */
+async function pipDepNeedsInstall(pkg: string): Promise<boolean> {
+	const { name, version } = parsePipSpec(pkg);
+	const installed = await getPipInstalledVersion(name);
+	if (installed === null) return true;
+	if (!version) return false;
+	return normalizeVersion(version) !== installed;
+}
+
+/**
+ * Install pip packages
+ */
+async function installPipPackages(
+	packages: string[],
+	result: SetupResult,
+): Promise<void> {
+	const pip = await detectPipCommand();
+	if (!pip) {
+		for (const pkg of packages) {
+			result.failed.push({ pkg: `pip:${pkg}`, error: "No pip/uv found" });
+		}
+		return;
+	}
+
+	// Filter out those already at the pinned version
+	const toInstall: string[] = [];
+	for (const pkg of packages) {
+		if (await pipDepNeedsInstall(pkg)) {
+			toInstall.push(pkg);
+		} else {
+			result.skipped.push(`pip:${pkg}`);
+		}
+	}
+
+	if (toInstall.length === 0) return;
+
+	// Install all at once
+	const { ok, stderr } = await run(pip.cmd, [...pip.args, ...toInstall]);
+	if (ok) {
+		for (const pkg of toInstall) {
+			result.installed.push(`pip:${pkg}`);
+		}
+	} else {
+		for (const pkg of toInstall) {
+			result.failed.push({ pkg: `pip:${pkg}`, error: stderr });
+		}
+	}
+}
+
+/**
+ * Install brew packages
+ */
+async function installBrewPackages(
+	packages: string[],
+	result: SetupResult,
+): Promise<void> {
+	const brewPath = await which("brew");
+	if (!brewPath) {
+		for (const pkg of packages) {
+			result.failed.push({
+				pkg: `brew:${pkg}`,
+				error: "Homebrew not installed",
+			});
+		}
+		return;
+	}
+
+	for (const pkg of packages) {
+		const decision = await brewDepDecision(pkg);
+		if (decision.action === "skip") {
+			result.skipped.push(`brew:${pkg}`);
+			continue;
+		}
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `brew:${pkg}`, error: decision.detail });
+			continue;
+		}
+
+		const { ok, stderr } = await run(brewPath, ["install", pkg]);
+		if (ok) {
+			result.installed.push(`brew:${pkg}`);
+		} else {
+			result.failed.push({ pkg: `brew:${pkg}`, error: stderr });
+		}
+	}
+}
+
+/**
+ * Detect the best available Node.js package installer for globals
+ * Prefers: bun > npm
+ */
+async function detectNpmCommand(): Promise<{
+	cmd: string;
+	args: string[];
+	label: string;
+} | null> {
+	const bunPath = await which("bun");
+	if (bunPath) {
+		return { cmd: bunPath, args: ["install", "-g"], label: "bun" };
+	}
+	const npmPath = await which("npm");
+	if (npmPath) {
+		return { cmd: npmPath, args: ["install", "-g"], label: "npm" };
+	}
+	return null;
+}
+
+/**
+ * Global bin dir for the detected Node installer. Best effort: bun and npm
+ * report it differently, and null simply disables the reach check rather than
+ * blocking an install we can't reason about.
+ */
+async function getNpmInstallDir(installer: {
+	cmd: string;
+	label: string;
+}): Promise<string | null> {
+	if (installer.label === "bun") {
+		const { ok, stdout } = await run(installer.cmd, ["pm", "bin", "-g"], 10000);
+		return ok && stdout ? stdout.split("\n")[0].trim() : null;
+	}
+	const { ok, stdout } = await run(installer.cmd, ["prefix", "-g"], 10000);
+	if (!ok || !stdout) return null;
+	return path.join(stdout.split("\n")[0].trim(), "bin");
+}
+
+/**
+ * Install global Node.js packages (prefers bun > npm)
+ */
+async function installNpmPackages(
+	packages: string[],
+	result: SetupResult,
+): Promise<void> {
+	const installer = await detectNpmCommand();
+	if (!installer) {
+		for (const pkg of packages) {
+			result.failed.push({ pkg: `npm:${pkg}`, error: "No bun or npm found" });
+		}
+		return;
+	}
+
+	const installDir = () => getNpmInstallDir(installer);
+
+	for (const pkg of packages) {
+		// Parsed, not raw: `isBinaryAvailable("foo@1.2.3")` looks for a binary
+		// literally named "foo@1.2.3", never finds one, and reinstalls forever.
+		const decision = await binaryDepDecision(parseAtSpec(pkg), installDir);
+		if (decision.action === "skip") {
+			result.skipped.push(`npm:${pkg}`);
+			continue;
+		}
+		if (decision.action === "blocked") {
+			result.failed.push({
+				pkg: `${installer.label}:${pkg}`,
+				error: decision.detail,
+			});
+			continue;
+		}
+
+		const { ok, stderr } = await run(installer.cmd, [...installer.args, pkg]);
+		if (ok) {
+			result.installed.push(`${installer.label}:${pkg}`);
+		} else {
+			result.failed.push({ pkg: `${installer.label}:${pkg}`, error: stderr });
+		}
+	}
+}
+
+/**
+ * Install cargo packages
+ */
+async function installCargoPackages(
+	packages: string[],
+	result: SetupResult,
+): Promise<void> {
+	const cargoPath = await which("cargo");
+	if (!cargoPath) {
+		for (const pkg of packages) {
+			result.failed.push({ pkg: `cargo:${pkg}`, error: "cargo not found" });
+		}
+		return;
+	}
+
+	for (const pkg of packages) {
+		const parsed = parseAtSpec(pkg);
+		const decision = await binaryDepDecision(parsed, getCargoInstallDir);
+		if (decision.action === "skip") {
+			result.skipped.push(`cargo:${pkg}`);
+			continue;
+		}
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `cargo:${pkg}`, error: decision.detail });
+			continue;
+		}
+
+		// `--version` rather than `crate@ver`: the explicit flag works on every
+		// cargo, the @ form only on recent ones.
+		const args = parsed.version
+			? ["install", parsed.name, "--version", parsed.version]
+			: ["install", parsed.spec];
+		const { ok, stderr } = await run(cargoPath, args, 300000);
+		if (ok) {
+			result.installed.push(`cargo:${pkg}`);
+		} else {
+			result.failed.push({ pkg: `cargo:${pkg}`, error: stderr });
+		}
+	}
+}
+
+/**
+ * {@link parseAtSpec} for a Go module spec.
+ *
+ * Same split, but the name comes from {@link goBinaryName}: Go's `/vN`
+ * major-version suffix is part of the module path, not the binary, so
+ * "github.com/MadAppGang/tmux-mcp/v2@v2.0.0" installs `tmux-mcp`, not `v2`.
+ * The generic parser cannot do this — an npm scope may legitimately be `v2`.
+ */
+export function parseGoSpec(spec: string): ParsedSpec {
+	const parsed = parseAtSpec(spec);
+	// Same separator rule as parseAtSpec: a leading `@` is never a version.
+	const at = spec.lastIndexOf("@");
+	const modulePath = at > 0 ? spec.slice(0, at) : spec;
+	return { ...parsed, name: goBinaryName(modulePath) };
+}
+
+/**
+ * Extract binary name from a Go module path.
+ * The binary name is the last path segment before @version, minus any /vN
+ * major-version suffix.
+ * e.g., "github.com/MadAppGang/tmux-mcp@latest"    → "tmux-mcp"
+ *       "github.com/MadAppGang/tmux-mcp/v2@v2.0.0" → "tmux-mcp"
+ *       "github.com/user/tool"                      → "tool"
+ */
+export function extractGoBinaryName(pkg: string): string {
+	return parseGoSpec(pkg).name;
+}
+
+/**
+ * Extract the pinned version from a Go module path, or null when unpinned.
+ * e.g., "github.com/MadAppGang/tmux-mcp@v1.6.2" → "v1.6.2"
+ *       "github.com/MadAppGang/tmux-mcp@latest" → null (a moving target)
+ *       "github.com/user/tool"                  → null
+ */
+export function extractGoVersion(pkg: string): string | null {
+	return parseGoSpec(pkg).version;
+}
+
+/** Normalize a semver-ish string for comparison: trim and drop a leading "v". */
+function normalizeVersion(v: string): string {
+	return v.trim().replace(/^v/, "");
+}
+
+/**
+ * Read a binary's version via `<path> --version`, normalized, or null when it
+ * produced no usable version string.
+ *
+ * Takes a RESOLVED path, never a bare name. Probing by name would re-run PATH
+ * resolution and can read a different binary than the one whose presence was
+ * checked — which is how a version check ends up passing judgement on one file
+ * while `go install` fixes another.
+ */
+async function getInstalledBinaryVersion(
+	binaryPath: string,
+): Promise<string | null> {
+	const { ok, stdout } = await run(binaryPath, ["--version"], 10000);
+	if (!ok || !stdout) return null;
+	const match = stdout.split("\n")[0].match(/v?\d+\.\d+\.\d+[^\s]*/);
+	return match ? normalizeVersion(match[0]) : null;
+}
+
+/** PATH split into ordered, non-empty entries. */
+function pathEntries(): string[] {
+	return (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+}
+
+/**
+ * Parse `go env -json GOBIN GOPATH`.
+ *
+ * JSON rather than the line-oriented form deliberately: `go env GOBIN GOPATH`
+ * prints an empty FIRST line when GOBIN is unset, so any trimming of the output
+ * (which {@link run} does) silently promotes GOPATH into GOBIN's slot and points
+ * the install dir one level too high.
+ */
+export function parseGoEnv(stdout: string): { gobin: string; gopath: string } {
+	try {
+		const parsed = JSON.parse(stdout) as Record<string, unknown>;
+		const str = (v: unknown) => (typeof v === "string" ? v.trim() : "");
+		return { gobin: str(parsed.GOBIN), gopath: str(parsed.GOPATH) };
+	} catch {
+		return { gobin: "", gopath: "" };
+	}
+}
+
+/**
+ * The directory `go install` writes into: GOBIN when set, else GOPATH/bin.
+ * Null when go can't be asked — callers must then draw no conclusions about
+ * where an install would land.
+ */
+async function getGoInstallDir(): Promise<string | null> {
+	const goPath = await which("go");
+	if (!goPath) return null;
+	const { ok, stdout } = await run(
+		goPath,
+		["env", "-json", "GOBIN", "GOPATH"],
+		10000,
+	);
+	if (!ok) return null;
+	const { gobin, gopath } = parseGoEnv(stdout);
+	if (gobin) return gobin;
+	if (gopath) return path.join(gopath, "bin");
+	return null;
+}
+
+/** Directories in `entries` (PATH order) holding an executable `binaryName`. */
+async function findOccurrenceDirs(
+	binaryName: string,
+	entries: string[],
+): Promise<string[]> {
+	const dirs: string[] = [];
+	for (const entry of entries) {
+		try {
+			await access(path.join(entry, binaryName), fsConstants.X_OK);
+			dirs.push(entry);
+		} catch {
+			// absent here, or not executable
+		}
+	}
+	return dirs;
+}
+
+export type InstallReach =
+	| { reach: "wins" }
+	| { reach: "shadowed"; byDir: string }
+	| { reach: "off-path" };
+
+/**
+ * Whether writing a binary into `installDir` would change what PATH resolves —
+ * the question `go install` on its own cannot answer.
+ *
+ * Walks PATH in order; the first entry that either IS the install dir or
+ * already holds the binary decides. Running off the end without meeting the
+ * install dir means a binary placed there can never be executed.
+ *
+ * Pure by design: the caller supplies `occurrenceDirs` and `installDir`, so the
+ * ordering rules are testable without touching a filesystem or a PATH.
+ */
+export function classifyInstallReach(
+	entries: string[],
+	occurrenceDirs: string[],
+	installDir: string,
+): InstallReach {
+	const target = path.resolve(installDir);
+	const occupied = new Set(occurrenceDirs.map((d) => path.resolve(d)));
+
+	for (const entry of entries) {
+		const dir = path.resolve(entry);
+		if (dir === target) return { reach: "wins" };
+		if (occupied.has(dir)) return { reach: "shadowed", byDir: entry };
+	}
+	return { reach: "off-path" };
+}
+
+export type GoDepDecision =
+	| {
+			action: "install";
+			reason: "absent" | "version-mismatch" | "version-unreadable";
+	  }
+	| { action: "skip"; reason: "up-to-date" | "unpinned-present" }
+	| {
+			action: "blocked";
+			reason: "shadowed" | "install-dir-off-path";
+			detail: string;
+	  };
+
+/**
+ * Why an install into the go bin dir would not take effect, or null when it
+ * would — or when we cannot tell, in which case we don't stand in the way.
+ */
+async function findInstallBlocker(
+	binaryName: string,
+	installedVersion: string | null,
+	getInstallDir: () => Promise<string | null>,
+): Promise<GoDepDecision | null> {
+	const installDir = await getInstallDir();
+	if (!installDir) return null;
+
+	const entries = pathEntries();
+	const reach = classifyInstallReach(
+		entries,
+		await findOccurrenceDirs(binaryName, entries),
+		installDir,
+	);
+
+	if (reach.reach === "wins") return null;
+
+	if (reach.reach === "off-path") {
+		return {
+			action: "blocked",
+			reason: "install-dir-off-path",
+			detail: [
+				`go install writes ${binaryName} to ${installDir}, which is not in`,
+				"PATH, so the installed binary would never run.",
+				`Add ${installDir} to PATH.`,
+			].join(" "),
+		};
+	}
+
+	const shadowPath = path.join(reach.byDir, binaryName);
+	const reports =
+		installedVersion === null
+			? "which cannot report a version"
+			: `which reports ${installedVersion}`;
+	return {
+		action: "blocked",
+		reason: "shadowed",
+		detail: [
+			`go install would write ${binaryName} to ${installDir}, but PATH resolves`,
+			`${binaryName} to ${shadowPath} first (${reports}), so installing cannot`,
+			`change what runs. Remove ${shadowPath}, or move ${installDir} ahead of`,
+			`${reach.byDir} in PATH.`,
+		].join(" "),
+	};
+}
+
+/**
+ * Decide what to do about a Go dependency. This is what makes a plugin *update*
+ * actually update its binary: without a version check an already-present binary
+ * is skipped forever, so a bumped plugin never pulls the new one.
+ *
+ * The binary is resolved ONCE and that exact path is probed. Resolving per step
+ * is how a version check judges one file while `go install` fixes another, then
+ * repeats forever — reporting success every time.
+ *
+ *  - binary absent                                      → install
+ *  - pinned version, resolved binary reports the same   → skip
+ *  - pinned version, resolved binary reports another     → install
+ *  - pinned version, version can't be read              → install (can't
+ *    confirm the pin, so reinstall to be safe)
+ *  - unpinned (@latest) and present                     → skip (a moving target
+ *    can't be verified without a network round-trip)
+ *  - an install PATH would ignore                       → blocked, naming the
+ *    binary that shadows it
+ */
+export async function binaryDepDecision(
+	parsed: ParsedSpec,
+	getInstallDir: () => Promise<string | null>,
+): Promise<GoDepDecision> {
+	const { name, version: pinned } = parsed;
+	const resolved = await which(name);
+
+	if (!resolved) {
+		return (
+			(await findInstallBlocker(name, null, getInstallDir)) ?? {
+				action: "install",
+				reason: "absent",
+			}
+		);
+	}
+
+	if (!pinned) return { action: "skip", reason: "unpinned-present" };
+
+	const installed = await getInstalledBinaryVersion(resolved);
+	if (installed !== null && installed === normalizeVersion(pinned)) {
+		return { action: "skip", reason: "up-to-date" };
+	}
+
+	return (
+		(await findInstallBlocker(name, installed, getInstallDir)) ?? {
+			action: "install",
+			reason: installed === null ? "version-unreadable" : "version-mismatch",
+		}
+	);
+}
+
+/** {@link binaryDepDecision} for a Go module path. */
+export async function goDepDecision(pkg: string): Promise<GoDepDecision> {
+	return binaryDepDecision(parseGoSpec(pkg), getGoInstallDir);
+}
+
+/**
+ * Where `cargo install` puts binaries: CARGO_INSTALL_ROOT, else CARGO_HOME/bin,
+ * else ~/.cargo/bin.
+ */
+async function getCargoInstallDir(): Promise<string | null> {
+	const root = process.env.CARGO_INSTALL_ROOT;
+	if (root) return path.join(root, "bin");
+	const home = process.env.CARGO_HOME;
+	if (home) return path.join(home, "bin");
+	return path.join(os.homedir(), ".cargo", "bin");
+}
+
+/** Where brew links binaries: `brew --prefix`/bin. */
+async function getBrewInstallDir(): Promise<string | null> {
+	const brewPath = await which("brew");
+	if (!brewPath) return null;
+	const { ok, stdout } = await run(brewPath, ["--prefix"], 10000);
+	if (!ok || !stdout) return null;
+	return path.join(stdout.split("\n")[0].trim(), "bin");
+}
+
+/** {@link binaryDepDecision} for a cargo crate. */
+export async function cargoDepDecision(pkg: string): Promise<GoDepDecision> {
+	return binaryDepDecision(parseAtSpec(pkg), getCargoInstallDir);
+}
+
+/**
+ * Decision for a brew formula. Brew has no exact-pin syntax, so `version` is
+ * always null and this reduces to presence plus a reach check — which is the
+ * case that actually bit us: a Homebrew copy sitting behind another PATH entry.
+ */
+export async function brewDepDecision(pkg: string): Promise<GoDepDecision> {
+	const name = extractBinaryName(pkg);
+	return binaryDepDecision(
+		{ spec: pkg, name, version: null },
+		getBrewInstallDir,
+	);
+}
+
+/**
+ * Boolean view of {@link goDepDecision}: does this dependency still need
+ * attention? A blocked dep counts — it is not satisfied, and the install path
+ * reports why rather than silently succeeding.
+ */
+export async function goDepNeedsInstall(pkg: string): Promise<boolean> {
+	return (await goDepDecision(pkg)).action !== "skip";
+}
+
+/**
+ * Install Go packages via `go install`
+ */
+async function installGoPackages(
+	packages: string[],
+	result: SetupResult,
+): Promise<void> {
+	const goPath = await which("go");
+	if (!goPath) {
+		for (const pkg of packages) {
+			result.failed.push({ pkg: `go:${pkg}`, error: "go not found" });
+		}
+		return;
+	}
+
+	for (const pkg of packages) {
+		const decision = await goDepDecision(pkg);
+
+		if (decision.action === "skip") {
+			result.skipped.push(`go:${pkg}`);
+			continue;
+		}
+
+		// Installing would leave what actually runs untouched. Reporting success
+		// here is what turned a broken PATH into an endless reinstall loop that
+		// looked healthy every round, so say what's wrong instead.
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `go:${pkg}`, error: decision.detail });
+			continue;
+		}
+
+		const { ok, stderr } = await run(goPath, ["install", pkg], 300000);
+		if (ok) {
+			result.installed.push(`go:${pkg}`);
+		} else {
+			result.failed.push({ pkg: `go:${pkg}`, error: stderr });
+		}
+	}
+}
+
+/**
+ * Check required system binaries and report missing ones.
+ * These are NOT installed by magus — the user must install them manually.
+ */
+async function checkRequiredBinaries(
+	binaries: string[],
+	result: SetupResult,
+): Promise<void> {
+	for (const name of binaries) {
+		if (await isBinaryAvailable(name)) {
+			result.skipped.push(`required:${name}`);
+		} else {
+			result.failed.push({
+				pkg: `required:${name}`,
+				error: `Required binary '${name}' not found in PATH. Please install it manually.`,
+			});
+		}
+	}
+}
+
+/**
+ * Read the setup config from a plugin's cached manifest
+ */
+export async function getPluginSetupConfig(
+	marketplace: string,
+	pluginName: string,
+): Promise<SetupConfig | null> {
+	const cacheDir = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"cache",
+		marketplace,
+	);
+
+	// Find the plugin directory (versioned)
+	if (!(await fs.pathExists(cacheDir))) return null;
+
+	const entries = await fs.readdir(cacheDir);
+	// Look for the plugin name directory
+	const pluginDir = entries.find((e) => e === pluginName);
+	if (!pluginDir) return null;
+
+	const pluginPath = path.join(cacheDir, pluginDir);
+	const stat = await fs.stat(pluginPath);
+	if (!stat.isDirectory()) return null;
+
+	// Find the version directory
+	const versions = await fs.readdir(pluginPath);
+
+	// Use the latest version directory
+	const latestVersion = versions.sort().pop();
+	if (latestVersion === undefined) return null;
+	const manifestPath = path.join(pluginPath, latestVersion, "plugin.json");
+
+	if (!(await fs.pathExists(manifestPath))) return null;
+
+	try {
+		const manifest = await fs.readJson(manifestPath);
+		return manifest.setup || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Read setup config from a local plugin directory (marketplace source)
+ */
+export async function getPluginSetupFromSource(
+	marketplace: string,
+	pluginName: string,
+): Promise<SetupConfig | null> {
+	const marketplaceDir = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"marketplaces",
+		marketplace,
+	);
+
+	if (!(await fs.pathExists(marketplaceDir))) return null;
+
+	// Try common plugin locations
+	for (const subdir of ["plugins", ""]) {
+		const pluginJson = subdir
+			? path.join(marketplaceDir, subdir, pluginName, "plugin.json")
+			: path.join(marketplaceDir, pluginName, "plugin.json");
+
+		if (await fs.pathExists(pluginJson)) {
+			try {
+				const manifest = await fs.readJson(pluginJson);
+				return manifest.setup || null;
+			} catch {}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Install all dependencies declared in a plugin's setup config.
+ * Auto-detects available package managers.
+ */
+export async function installPluginDeps(
+	setup: SetupConfig,
+): Promise<SetupResult> {
+	const result: SetupResult = {
+		installed: [],
+		skipped: [],
+		failed: [],
+	};
+
+	if (setup.pip?.length) {
+		await installPipPackages(setup.pip, result);
+	}
+	if (setup.brew?.length) {
+		await installBrewPackages(setup.brew, result);
+	}
+	if (setup.npm?.length) {
+		await installNpmPackages(setup.npm, result);
+	}
+	if (setup.cargo?.length) {
+		await installCargoPackages(setup.cargo, result);
+	}
+	if (setup.go?.length) {
+		await installGoPackages(setup.go, result);
+	}
+	if (setup.required?.length) {
+		await checkRequiredBinaries(setup.required, result);
+	}
+
+	return result;
+}
+
+/**
+ * Check which dependencies from a setup config are missing.
+ * Returns a filtered SetupConfig with only missing deps.
+ */
+export async function checkMissingDeps(
+	setup: SetupConfig,
+): Promise<SetupConfig> {
+	const missing: SetupConfig = {};
+
+	// Each of these mirrors its installer's decision function. When the two
+	// disagree the UI reports one thing and the install does another.
+	if (setup.pip?.length) {
+		const missingPip: string[] = [];
+		for (const pkg of setup.pip) {
+			if (await pipDepNeedsInstall(pkg)) {
+				missingPip.push(pkg);
+			}
+		}
+		if (missingPip.length > 0) missing.pip = missingPip;
+	}
+
+	if (setup.brew?.length) {
+		const missingBrew: string[] = [];
+		for (const pkg of setup.brew) {
+			if ((await brewDepDecision(pkg)).action !== "skip") {
+				missingBrew.push(pkg);
+			}
+		}
+		if (missingBrew.length > 0) missing.brew = missingBrew;
+	}
+
+	if (setup.npm?.length) {
+		const installer = await detectNpmCommand();
+		const installDir = installer
+			? () => getNpmInstallDir(installer)
+			: async () => null;
+		const missingNpm: string[] = [];
+		for (const pkg of setup.npm) {
+			const decision = await binaryDepDecision(parseAtSpec(pkg), installDir);
+			if (decision.action !== "skip") {
+				missingNpm.push(pkg);
+			}
+		}
+		if (missingNpm.length > 0) missing.npm = missingNpm;
+	}
+
+	if (setup.cargo?.length) {
+		const missingCargo: string[] = [];
+		for (const pkg of setup.cargo) {
+			if ((await cargoDepDecision(pkg)).action !== "skip") {
+				missingCargo.push(pkg);
+			}
+		}
+		if (missingCargo.length > 0) missing.cargo = missingCargo;
+	}
+
+	if (setup.go?.length) {
+		const missingGo: string[] = [];
+		for (const pkg of setup.go) {
+			if (await goDepNeedsInstall(pkg)) {
+				missingGo.push(pkg);
+			}
+		}
+		if (missingGo.length > 0) missing.go = missingGo;
+	}
+
+	if (setup.required?.length) {
+		const missingRequired: string[] = [];
+		for (const name of setup.required) {
+			if (!(await isBinaryAvailable(name))) {
+				missingRequired.push(name);
+			}
+		}
+		if (missingRequired.length > 0) missing.required = missingRequired;
+	}
+
+	return missing;
+}