magus-cli 7.8.0 → 7.9.1

package/src/__tests__/requires-probe.test.ts

@@ -0,0 +1,858 @@
+/**
+ * requires-probe — the one reader of plugin.json `requires`.
+ *
+ * Host inputs are pinned: every probe runs against a PATH and HOME built in a
+ * temp dir from fake executables, and the platform is passed in, so nothing
+ * here reports what this machine happens to have installed.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+	chmodSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	type InstallOption,
+	type ProbeEnv,
+	REQUIRES_SCHEMA,
+	type Requirement,
+	USER_PREFIXES,
+	dedupeKey,
+	describeStep,
+	doctorFixCommand,
+	parseRequires,
+	probe,
+	rcFile,
+	releaseAsset,
+	releaseFormat,
+	renderFix,
+	renderInstall,
+	selectOption,
+	whyUnselectable,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+
+const BUN: Requirement = {
+	name: "bun",
+	check: ["bun", "--version"],
+	install: [{ via: "bootstrap", tool: "bun" }],
+};
+const UV: Requirement = {
+	name: "uv",
+	check: ["uv", "--version"],
+	install: [{ via: "bootstrap", tool: "uv" }],
+};
+const TMUX: Requirement = {
+	name: "tmux",
+	check: ["tmux", "-V"],
+	install: [
+		{ via: "brew", os: ["darwin"], formula: "tmux" },
+		{ via: "apt", os: ["linux"], packages: ["tmux"] },
+	],
+};
+const DIGEST = "a".repeat(64);
+const TMUX_MCP: Requirement = {
+	name: "tmux-mcp",
+	check: ["tmux-mcp", "--version"],
+	install: [
+		{
+			via: "release",
+			repo: "MadAppGang/tmux-mcp",
+			tag: "v2.0.0",
+			asset: "tmux-mcp_{os}_{arch}.tar.gz",
+			binary: "tmux-mcp",
+			sha256: {
+				darwin_amd64: DIGEST,
+				darwin_arm64: DIGEST,
+				linux_amd64: DIGEST,
+				linux_arm64: DIGEST,
+			},
+		},
+	],
+};
+
+const manifest = (bin: unknown[], extra: Record<string, unknown> = {}) => ({
+	name: "p",
+	requires: { schema: REQUIRES_SCHEMA, bin, ...extra },
+});
+
+function errorsOf(json: unknown): string[] {
+	const r = parseRequires(json);
+	return r.ok ? [] : r.errors;
+}
+
+describe("parseRequires", () => {
+	test("a full declaration parses to the same requirements", () => {
+		const r = parseRequires(manifest([BUN, TMUX, TMUX_MCP]));
+		expect(r).toEqual({ ok: true, requirements: [BUN, TMUX, TMUX_MCP] });
+	});
+
+	test("no requires declares nothing", () => {
+		expect(parseRequires({ name: "p" })).toEqual({
+			ok: true,
+			requirements: [],
+		});
+	});
+
+	test("reads only the requires key: other manifest keys are not its concern", () => {
+		expect(parseRequires({ name: "p", anything: 1 }).ok).toBe(true);
+	});
+
+	test("an unknown key anywhere inside requires is an error naming it", () => {
+		expect(errorsOf(manifest([BUN], { extra: 1 }))).toEqual([
+			'requires: unknown key "extra"',
+		]);
+		expect(errorsOf(manifest([{ ...BUN, via: "bun" }]))[0]).toContain(
+			'unknown key "via"',
+		);
+		expect(
+			errorsOf(
+				manifest([
+					{ ...BUN, install: [{ via: "bootstrap", tool: "bun", url: "x" }] },
+				]),
+			)[0],
+		).toContain('unknown key "url"');
+	});
+
+	test("an unknown via is an error, never a silent null", () => {
+		expect(
+			errorsOf(
+				manifest([{ name: "x", check: ["x"], install: [{ via: "cargo" }] }]),
+			),
+		).toEqual(['requires.bin[0] (x).install[0]: unknown via "cargo"']);
+	});
+
+	test("npm, pip and go are refused inside a manifest", () => {
+		for (const via of ["npm", "pip", "go"]) {
+			expect(
+				errorsOf(
+					manifest([
+						{ name: "x", check: ["x"], install: [{ via, package: "x" }] },
+					]),
+				),
+			).toEqual([
+				`requires.bin[0] (x).install[0]: via ${via} is not allowed in plugin.json`,
+			]);
+		}
+	});
+
+	test("a missing check is an error: there is no default", () => {
+		expect(
+			errorsOf(
+				manifest([{ name: "x", install: [{ via: "brew", formula: "x" }] }]),
+			),
+		).toContain("requires.bin[0] (x).check: missing check (a non-empty argv)");
+	});
+
+	test("only ${CLAUDE_PLUGIN_ROOT} is expanded in a check", () => {
+		expect(
+			errorsOf(manifest([{ ...TMUX, check: ["${HOME}/bin/tmux", "-V"] }]))[0],
+		).toContain("only ${CLAUDE_PLUGIN_ROOT} is expanded");
+	});
+
+	test("schema: newer asks for a newer magus-cli, older for a newer plugin", () => {
+		const newer = parseRequires({ requires: { schema: 2, bin: [] } });
+		expect(newer.ok ? null : newer.kind).toBe("newer-schema");
+		expect(newer.ok ? "" : newer.errors[0]).toContain("update magus-cli");
+		const older = parseRequires({ requires: { schema: 0, bin: [] } });
+		expect(older.ok ? null : older.kind).toBe("older-schema");
+		expect(older.ok ? "" : older.errors[0]).toContain("update the plugin");
+		const none = parseRequires({ requires: { bin: [] } });
+		expect(none.ok ? null : none.kind).toBe("invalid");
+	});
+
+	test("a bootstrap names a magus table entry equal to its requirement", () => {
+		expect(
+			errorsOf(
+				manifest([
+					{
+						name: "bun",
+						check: ["bun"],
+						install: [{ via: "bootstrap", tool: "rustup" }],
+					},
+				]),
+			)[0],
+		).toContain(".tool: must be one of bun, uv");
+		expect(
+			errorsOf(
+				manifest([
+					{
+						name: "node",
+						check: ["node"],
+						install: [{ via: "bootstrap", tool: "bun" }],
+					},
+				]),
+			)[0],
+		).toContain('bootstraps "bun" for a requirement named "node"');
+	});
+
+	test("bun, uv-script and uv-module options need their toolchain declared beside them", () => {
+		expect(
+			errorsOf(
+				manifest([
+					{ name: "c", check: ["c"], install: [{ via: "bun", package: "c" }] },
+				]),
+			),
+		).toEqual([
+			'requires.bin (c): via bun needs "bun" declared in the same plugin',
+		]);
+		expect(
+			errorsOf(
+				manifest([
+					{
+						name: "e",
+						check: ["e"],
+						install: [{ via: "uv-script", script: "s.py", args: [] }],
+					},
+				]),
+			),
+		).toEqual([
+			'requires.bin (e): via uv-script needs "uv" declared in the same plugin',
+		]);
+	});
+
+	test("nothing in a manifest can become a shell word or leave the plugin root", () => {
+		const bad: [InstallOption | Record<string, unknown>, string][] = [
+			[{ via: "apt", packages: ["-o", "tmux"] }, ".packages"],
+			[{ via: "brew", formula: "tmux; rm -rf ~" }, ".formula"],
+			[{ via: "uv-script", script: "../evil.py", args: [] }, ".script"],
+			[{ via: "uv-script", script: "/abs.py", args: [] }, ".script"],
+			[
+				{ via: "uv-module", script: "s.py", module: "os;x", args: [] },
+				".module",
+			],
+			[
+				{
+					via: "uv-module",
+					script: "s.py",
+					module: "m",
+					args: [],
+					root: "yes",
+				},
+				".root",
+			],
+			[
+				{ ...(TMUX_MCP.install[0] as object), asset: "x_{os}_{secret}.tgz" },
+				".asset",
+			],
+			[{ ...(TMUX_MCP.install[0] as object), repo: "a/b/c" }, ".repo"],
+			[
+				{
+					...(TMUX_MCP.install[0] as object),
+					sha256: { linux_amd64: "short" },
+				},
+				".sha256.linux_amd64",
+			],
+		];
+		for (const [option, field] of bad) {
+			const errors = errorsOf(
+				manifest([BUN, UV, { name: "x", check: ["x"], install: [option] }]),
+			);
+			expect(errors.join("\n")).toContain(field);
+		}
+	});
+
+	test("the same name twice in one plugin is an error", () => {
+		expect(errorsOf(manifest([BUN, BUN]))).toEqual([
+			'requires.bin: "bun" twice',
+		]);
+	});
+});
+
+describe("dedupeKey", () => {
+	test("identical declarations share a key, whatever the key order", () => {
+		const reordered = JSON.parse(
+			'{"install":[{"tool":"bun","via":"bootstrap"}],"check":["bun","--version"],"name":"bun"}',
+		) as Requirement;
+		expect(dedupeKey(reordered)).toBe(dedupeKey(BUN));
+		expect(dedupeKey(BUN)).toMatch(/^bun-[0-9a-f]{12}$/);
+	});
+
+	test("different declarations of one name never hide each other", () => {
+		expect(dedupeKey({ ...BUN, check: ["bun", "-v"] })).not.toBe(
+			dedupeKey(BUN),
+		);
+	});
+});
+
+// ─── probe ──────────────────────────────────────────────────────────────────────
+
+let root: string;
+let bin: string;
+let home: string;
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "requires-probe-"));
+	bin = join(root, "bin");
+	home = join(root, "home");
+	mkdirSync(bin);
+	mkdirSync(home);
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+function tool(dir: string, name: string, body: string): void {
+	mkdirSync(dir, { recursive: true });
+	const file = join(dir, name);
+	writeFileSync(file, `#!/bin/sh\n${body}\n`);
+	chmodSync(file, 0o755);
+}
+
+const envFor = (over: Partial<ProbeEnv> = {}): ProbeEnv => ({
+	pluginRoot: root,
+	os: "linux",
+	arch: "amd64",
+	home,
+	path: bin,
+	capMs: 2_000,
+	depth: "full",
+	userShell: "/bin/zsh",
+	...over,
+});
+
+const req = (
+	name: string,
+	check: string[],
+	os?: ("darwin" | "linux")[],
+): Requirement => ({
+	name,
+	check,
+	...(os ? { os } : {}),
+	install: [{ via: "brew", formula: name }],
+});
+
+describe("probe", () => {
+	test("exit 0 is present, non-zero and absent are missing", async () => {
+		tool(bin, "ok", "exit 0");
+		tool(bin, "broken", "exit 3");
+		const result = await probe(
+			[req("ok", ["ok"]), req("broken", ["broken"]), req("gone", ["gone"])],
+			envFor(),
+		);
+		expect(result).toEqual([
+			{ name: "ok", status: "present" },
+			{ name: "broken", status: "missing" },
+			{ name: "gone", status: "missing" },
+		]);
+	});
+
+	test("a check over its cap is unknown (slow), never missing", async () => {
+		tool(bin, "slow", "exec /bin/sleep 5");
+		const [result] = await probe(
+			[req("slow", ["slow"])],
+			envFor({ capMs: 200 }),
+		);
+		expect(result?.status).toBe("unknown");
+		expect(result?.status === "unknown" ? result.reason : "").toContain("slow");
+	});
+
+	test("found only under a user prefix is off-path, with the prefix", async () => {
+		tool(join(home, ".bun", "bin"), "claudish", "exit 0");
+		tool(join(home, ".local", "bin"), "tmux-mcp", "exit 0");
+		const result = await probe(
+			[
+				req("claudish", ["claudish", "--version"]),
+				req("tmux-mcp", ["tmux-mcp"]),
+			],
+			envFor(),
+		);
+		expect(result).toEqual([
+			{ name: "claudish", status: "off-path", prefix: "~/.bun/bin" },
+			{ name: "tmux-mcp", status: "off-path", prefix: "~/.local/bin" },
+		]);
+	});
+
+	test("a check run through another missing declared dep is blocked by it", async () => {
+		const env = req("browser-use-env", ["uv", "run", "--script", "x.py"]);
+		const result = await probe([UV, env], envFor());
+		expect(result).toEqual([
+			{ name: "uv", status: "missing" },
+			{ name: "browser-use-env", status: "missing", blockedBy: "uv" },
+		]);
+	});
+
+	test("the blocked check runs once its dep is present", async () => {
+		tool(
+			bin,
+			"uv",
+			'test "$1" = --version && exit 0; test "$1" = run && exit 0; exit 1',
+		);
+		const env = req("browser-use-env", ["uv", "run", "--script", "x.py"]);
+		expect(await probe([UV, env], envFor())).toEqual([
+			{ name: "uv", status: "present" },
+			{ name: "browser-use-env", status: "present" },
+		]);
+	});
+
+	test("${CLAUDE_PLUGIN_ROOT} expands to the plugin root; nothing else does", async () => {
+		tool(root, "marker.sh", "exit 0");
+		const result = await probe(
+			[req("rooted", ["${CLAUDE_PLUGIN_ROOT}/marker.sh"])],
+			envFor(),
+		);
+		expect(result).toEqual([{ name: "rooted", status: "present" }]);
+	});
+
+	test("presence depth decides a self-named check by PATH lookup, without running it", async () => {
+		// Would fail if run, and would take 5 s: presence depth must do neither.
+		tool(bin, "mnemex", "exec /bin/sleep 5");
+		const started = Date.now();
+		const result = await probe(
+			[req("mnemex", ["mnemex", "--version"])],
+			envFor({ depth: "presence" }),
+		);
+		expect(result).toEqual([{ name: "mnemex", status: "present" }]);
+		expect(Date.now() - started).toBeLessThan(1_000);
+	});
+
+	test("presence depth reads a dangling symlink as missing, and a user prefix as off-path", async () => {
+		symlinkSync(join(root, "nowhere"), join(bin, "tmux-mcp"));
+		tool(join(home, ".bun", "bin"), "claudish", "exit 3");
+		const result = await probe(
+			[
+				req("tmux-mcp", ["tmux-mcp", "--version"]),
+				req("claudish", ["claudish"]),
+			],
+			envFor({ depth: "presence" }),
+		);
+		expect(result).toEqual([
+			{ name: "tmux-mcp", status: "missing" },
+			{ name: "claudish", status: "off-path", prefix: "~/.bun/bin" },
+		]);
+	});
+
+	test("presence depth still runs a check that is not the requirement's own binary", async () => {
+		tool(bin, "uv", 'test "$1" = --version && exit 0; exit 4');
+		const env = req("browser-use-env", ["uv", "run", "--script", "x.py"]);
+		expect(await probe([UV, env], envFor({ depth: "presence" }))).toEqual([
+			{ name: "uv", status: "present" },
+			{ name: "browser-use-env", status: "missing" },
+		]);
+	});
+
+	test("full depth runs a self-named check: present on PATH but failing is missing", async () => {
+		tool(bin, "mnemex", "exit 1");
+		expect(
+			await probe([req("mnemex", ["mnemex", "--version"])], envFor()),
+		).toEqual([{ name: "mnemex", status: "missing" }]);
+	});
+
+	test("a requirement for another OS is not probed", async () => {
+		expect(
+			await probe([req("libs", ["libs"], ["linux"])], envFor({ os: "darwin" })),
+		).toEqual([]);
+	});
+});
+
+// ─── selecting and rendering ────────────────────────────────────────────────────
+
+const none = () => false;
+const only =
+	(...tools: string[]) =>
+	(t: string) =>
+		tools.includes(t);
+
+describe("selectOption", () => {
+	const UV_DECL: Requirement = {
+		name: "uv",
+		check: ["uv", "--version"],
+		install: [
+			{ via: "brew", os: ["darwin"], formula: "uv" },
+			{ via: "bootstrap", tool: "uv" },
+		],
+	};
+
+	test("the first usable option in declaration order wins", () => {
+		const env = { os: "darwin" as const, arch: "arm64" as const };
+		expect(selectOption(UV_DECL, env, only("brew", "curl"))?.via).toBe("brew");
+		expect(selectOption(UV_DECL, env, only("curl"))?.via).toBe("bootstrap");
+		expect(
+			selectOption(UV_DECL, { ...env, os: "linux" }, only("curl", "brew"))?.via,
+		).toBe("bootstrap");
+	});
+
+	test("nothing usable is null, and why says what to do", () => {
+		const env = { os: "darwin" as const, arch: "arm64" as const };
+		expect(selectOption(TMUX, env, none)).toBeNull();
+		expect(whyUnselectable(TMUX, env, none)).toBe(
+			"Homebrew is missing — install it from https://brew.sh first",
+		);
+		expect(whyUnselectable(UV_DECL, { ...env, os: "linux" }, none)).toBe(
+			"its installer needs curl: sudo apt-get install -y curl",
+		);
+	});
+
+	test("a release with no digest for this platform is unusable", () => {
+		const unpinned: Requirement = {
+			...TMUX_MCP,
+			install: [
+				{
+					...(TMUX_MCP.install[0] as InstallOption & { via: "release" }),
+					sha256: {},
+				},
+			],
+		};
+		const env = { os: "linux" as const, arch: "arm64" as const };
+		expect(selectOption(unpinned, env, none)).toBeNull();
+		expect(whyUnselectable(unpinned, env, none)).toBe(
+			"no pinned build for linux_arm64",
+		);
+	});
+});
+
+describe("renderInstall + describeStep", () => {
+	const env = {
+		os: "linux" as const,
+		arch: "arm64" as const,
+		pluginRoot: "/p",
+	};
+
+	test("bun keeps the version pin in one argv word", () => {
+		const step = renderInstall(
+			{ name: "c", check: ["c"], install: [] },
+			{ via: "bun", package: "claudish", version: "1.2.3" },
+			env,
+		);
+		expect(step).toEqual({
+			kind: "argv",
+			name: "c",
+			escalation: "none",
+			argv: ["bun", "add", "-g", "claudish@1.2.3"],
+		});
+	});
+
+	test("apt is escalated, and only apt and root uv-module are", () => {
+		const apt = renderInstall(TMUX, TMUX.install[1] as InstallOption, env);
+		expect(describeStep(apt, "linux")).toBe(
+			"sudo apt-get install -y --no-install-recommends tmux",
+		);
+		const brew = renderInstall(TMUX, TMUX.install[0] as InstallOption, env);
+		expect(describeStep(brew, "darwin")).toBe("brew install tmux");
+	});
+
+	test("release: the fixed GitHub host, the platform's digest, verified before install", () => {
+		const step = renderInstall(
+			TMUX_MCP,
+			TMUX_MCP.install[0] as InstallOption,
+			env,
+		);
+		expect(step).toMatchObject({
+			kind: "release",
+			url: "https://github.com/MadAppGang/tmux-mcp/releases/download/v2.0.0/tmux-mcp_linux_arm64.tar.gz",
+			sha256: DIGEST,
+			dest: "~/.local/bin",
+		});
+		expect(describeStep(step, "linux")).toContain(
+			`echo '${DIGEST}  tmux-mcp_linux_arm64.tar.gz' | sha256sum -c`,
+		);
+		expect(describeStep(step, "darwin")).toContain("shasum -a 256 -c");
+	});
+
+	test("uv-module runs the module with the script env's interpreter, sudo only when root", () => {
+		const libs = renderInstall(
+			{ name: "chromium-libs", check: ["x"], install: [] },
+			{
+				via: "uv-module",
+				script: "scripts/mcp-server.py",
+				module: "playwright",
+				args: ["install-deps", "chromium"],
+				root: true,
+			},
+			env,
+		);
+		expect(libs).toMatchObject({
+			kind: "uv-module",
+			escalation: "sudo",
+			script: "/p/scripts/mcp-server.py",
+		});
+		expect(describeStep(libs, "linux")).toBe(
+			'uv sync --no-config --script /p/scripts/mcp-server.py && sudo "$(uv python find --no-config --script /p/scripts/mcp-server.py)" -B -m playwright install-deps chromium',
+		);
+	});
+
+	test("uv-script builds the env with no config from the directory it runs in", () => {
+		const step = renderInstall(
+			{ name: "browser-use-env", check: ["x"], install: [] },
+			{
+				via: "uv-script",
+				script: "scripts/mcp-server.py",
+				args: ["--check-env"],
+			},
+			env,
+		);
+		expect(step).toMatchObject({
+			kind: "argv",
+			argv: [
+				"uv",
+				"run",
+				"--no-config",
+				"--script",
+				"/p/scripts/mcp-server.py",
+				"--check-env",
+			],
+		});
+	});
+
+	test("bootstrap renders the upstream installer from magus's table", () => {
+		const step = renderInstall(BUN, BUN.install[0] as InstallOption, env);
+		expect(describeStep(step, "linux")).toBe(
+			"curl -fsSL https://bun.sh/install | bash",
+		);
+	});
+
+	test("a brew cask installs with --cask; a formula without", () => {
+		const parsed = parseRequires({
+			requires: {
+				schema: REQUIRES_SCHEMA,
+				bin: [
+					{
+						name: "madbench",
+						check: ["madbench", "--version"],
+						install: [{ via: "brew", cask: "madappgang/tap/madbench" }],
+					},
+				],
+			},
+		});
+		expect(parsed.ok).toBe(true);
+		if (!parsed.ok) return;
+		const r = parsed.requirements[0] as Requirement;
+		const step = renderInstall(r, r.install[0] as InstallOption, env);
+		expect(step).toMatchObject({
+			argv: ["brew", "install", "--cask", "madappgang/tap/madbench"],
+		});
+		expect(describeStep(step, "darwin")).toBe(
+			"brew install --cask madappgang/tap/madbench",
+		);
+	});
+
+	test("a brew option takes exactly one of formula and cask", () => {
+		for (const option of [
+			{ via: "brew" },
+			{ via: "brew", formula: "a", cask: "b" },
+		]) {
+			const parsed = parseRequires({
+				requires: {
+					schema: REQUIRES_SCHEMA,
+					bin: [{ name: "x", check: ["x"], install: [option] }],
+				},
+			});
+			expect(parsed).toMatchObject({ ok: false, kind: "invalid" });
+			if (parsed.ok) continue;
+			expect(parsed.errors.join("\n")).toContain(
+				"brew takes exactly one of formula and cask",
+			);
+		}
+	});
+
+	test("a bare-binary release: {arch} in the release's own spelling, verified, installed as the binary — no tar", () => {
+		const claudish: InstallOption = {
+			via: "release",
+			repo: "MadAppGang/claudish",
+			tag: "v10.3.0",
+			asset: "claudish-{os}-{arch}",
+			binary: "claudish",
+			arch: { amd64: "x64" },
+			sha256: { linux_amd64: DIGEST, linux_arm64: DIGEST },
+		};
+		const req = { name: "claudish", check: ["claudish"], install: [claudish] };
+		const amd = renderInstall(req, claudish, { ...env, arch: "amd64" });
+		expect(amd).toMatchObject({
+			kind: "release",
+			format: "binary",
+			url: "https://github.com/MadAppGang/claudish/releases/download/v10.3.0/claudish-linux-x64",
+		});
+		const arm = renderInstall(req, claudish, env);
+		expect(arm).toMatchObject({
+			url: "https://github.com/MadAppGang/claudish/releases/download/v10.3.0/claudish-linux-arm64",
+		});
+		expect(describeStep(amd, "linux")).toBe(
+			`cd $(mktemp -d) && curl -fsSLO https://github.com/MadAppGang/claudish/releases/download/v10.3.0/claudish-linux-x64 && echo '${DIGEST}  claudish-linux-x64' | sha256sum -c && mkdir -p ~/.local/bin && install -m 755 claudish-linux-x64 ~/.local/bin/claudish`,
+		);
+		expect(releaseFormat("tmux-mcp_linux_arm64.tar.gz")).toBe("tar.gz");
+		expect(releaseAsset(claudish, "darwin", "amd64")).toBe(
+			"claudish-darwin-x64",
+		);
+	});
+
+	test("a release asset is a .tar.gz archive or the binary itself, never another archive", () => {
+		for (const [asset, arch, error] of [
+			["x_{os}_{arch}.zip", undefined, "an archive must be .tar.gz or .tgz"],
+			["x_{os}_{arch}.tar.xz", undefined, "an archive must be .tar.gz or .tgz"],
+			["x-{os}-{arch}", { i386: "x86" }, 'unknown arch "i386"'],
+		] as const) {
+			const parsed = parseRequires({
+				requires: {
+					schema: REQUIRES_SCHEMA,
+					bin: [
+						{
+							name: "x",
+							check: ["x"],
+							install: [
+								{
+									via: "release",
+									repo: "a/b",
+									tag: "v1.0.0",
+									asset,
+									binary: "x",
+									...(arch ? { arch } : {}),
+									sha256: {},
+								},
+							],
+						},
+					],
+				},
+			});
+			expect(parsed.ok).toBe(false);
+			if (parsed.ok) continue;
+			expect(parsed.errors.join("\n")).toContain(error);
+		}
+	});
+});
+
+describe("renderFix", () => {
+	const reqs = [BUN, TMUX, TMUX_MCP];
+	const linuxEnv = (): ProbeEnv => {
+		tool(bin, "apt-get", "exit 0");
+		return envFor({ os: "linux", arch: "amd64" });
+	};
+
+	test("healthy is silent", () => {
+		expect(
+			renderFix(
+				"terminal",
+				[{ name: "tmux", status: "present" }],
+				reqs,
+				envFor(),
+				true,
+			),
+		).toBeNull();
+	});
+
+	test("unknown alone is silent: a slow check is not a finding", () => {
+		expect(
+			renderFix(
+				"terminal",
+				[{ name: "tmux", status: "unknown", reason: "slow" }],
+				reqs,
+				envFor(),
+				true,
+			),
+		).toBeNull();
+	});
+
+	test("missing deps: marker, names, the fix, and each by-hand line", () => {
+		const message = renderFix(
+			"terminal",
+			[
+				{ name: "tmux", status: "missing" },
+				{ name: "tmux-mcp", status: "missing" },
+				{ name: "bun", status: "unknown", reason: "slow" },
+			],
+			reqs,
+			linuxEnv(),
+			false,
+		) as string;
+		expect(message.split("\n")[0]).toBe(
+			"magus-deps · terminal: missing tmux, tmux-mcp; unknown (slow) bun.",
+		);
+		expect(message).toContain(
+			"Fix all: bun add -g magus-cli, then magus doctor --fix",
+		);
+		expect(message).toContain(
+			"tmux: sudo apt-get install -y --no-install-recommends tmux",
+		);
+		expect(message).toContain(
+			"releases/download/v2.0.0/tmux-mcp_linux_amd64.tar.gz",
+		);
+		expect(message).not.toContain("bun: ");
+	});
+
+	test("with magus on PATH the fix is magus alone", () => {
+		const message = renderFix(
+			"terminal",
+			[{ name: "tmux", status: "missing" }],
+			reqs,
+			linuxEnv(),
+			true,
+		) as string;
+		expect(message).toContain("Fix all: magus doctor --fix");
+		expect(message).not.toContain("magus-cli");
+	});
+
+	test("the fix names the session's project, quoted for a shell", () => {
+		expect(doctorFixCommand(null)).toBe("magus doctor --fix");
+		expect(doctorFixCommand("/srv/app")).toBe(
+			"magus doctor --fix --project /srv/app",
+		);
+		expect(doctorFixCommand("/srv/it's here")).toBe(
+			"magus doctor --fix --project '/srv/it'\\''s here'",
+		);
+		const message = renderFix(
+			"terminal",
+			[{ name: "tmux", status: "missing" }],
+			reqs,
+			linuxEnv(),
+			false,
+			"/srv/app",
+		) as string;
+		expect(message).toContain(
+			"Fix all: bun add -g magus-cli, then magus doctor --fix --project /srv/app\n",
+		);
+	});
+
+	test("the encoded banner has no quote before the lines a regex reads", () => {
+		const message = renderFix(
+			"terminal",
+			[
+				{ name: "tmux", status: "missing" },
+				{ name: "tmux-mcp", status: "missing" },
+			],
+			reqs,
+			linuxEnv(),
+			false,
+		) as string;
+		const encoded = JSON.stringify(message);
+		const url = encoded.indexOf("releases/download");
+		expect(url).toBeGreaterThan(0);
+		expect(encoded.slice(1, url)).not.toContain('\\"');
+	});
+
+	test("off-path names the prefix, the rc line and the rc file for the user's shell", () => {
+		const message = renderFix(
+			"claudish",
+			[{ name: "claudish", status: "off-path", prefix: "~/.bun/bin" }],
+			[
+				BUN,
+				{
+					name: "claudish",
+					check: ["claudish"],
+					install: [{ via: "bun", package: "claudish" }],
+				},
+			],
+			envFor({ userShell: "/bin/zsh" }),
+			true,
+		) as string;
+		expect(message).toContain("not on PATH claudish");
+		expect(message).toContain(
+			'add export PATH="$HOME/.bun/bin:$PATH" to ~/.zshrc',
+		);
+		expect(message).toContain("restart Claude Code from a new terminal");
+	});
+});
+
+describe("USER_PREFIXES", () => {
+	test("fish gets fish_add_path; every other shell an export line", () => {
+		const local = USER_PREFIXES.find((p) => p.dir === "~/.local/bin");
+		expect(local?.rcLine("/usr/bin/fish")).toBe(
+			"fish_add_path $HOME/.local/bin",
+		);
+		expect(local?.rcLine("/bin/bash")).toBe(
+			'export PATH="$HOME/.local/bin:$PATH"',
+		);
+		expect(rcFile("/bin/bash")).toBe("~/.bashrc");
+		expect(rcFile("/opt/homebrew/bin/fish")).toBe("~/.config/fish/config.fish");
+	});
+});