magus-cli 7.8.0 → 7.9.0

package/src/__tests__/blind/plugin-deps/probe.test.ts

@@ -0,0 +1,694 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { access, mkdir, symlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	type InstallOption,
+	type InstallStep,
+	type ProbeEnv,
+	type Requirement,
+	TOOLCHAIN_BOOTSTRAP,
+	USER_PREFIXES,
+	dedupeKey,
+	describeStep,
+	optionBlocker,
+	pathRcLine,
+	probe,
+	rcFile,
+	releaseAsset,
+	releaseFormat,
+	renderFix,
+	renderInstall,
+	selectOption,
+	whyUnselectable,
+} from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import { type World, makeWorld, removeWorld, writeExecutable } from "./helpers";
+
+const digest = "b".repeat(64);
+
+function req(
+	name: string,
+	install: InstallOption[],
+	check = [name, "--version"],
+): Requirement {
+	return { check, install, name };
+}
+
+function env(world: World, patch: Partial<ProbeEnv> = {}): ProbeEnv {
+	return {
+		arch: "amd64",
+		capMs: 500,
+		depth: "full",
+		home: world.home,
+		os: "linux",
+		path: world.bin,
+		pluginRoot: join(world.root, "plugin"),
+		userShell: "/bin/zsh",
+		...patch,
+	};
+}
+
+describe("probe contract", () => {
+	// Spec: contract/requires-probe.d.ts dedupeKey, “object keys sorted” and
+	// “different ones never hide each other.”
+	test("dedupeKey ignores object key order and changes with declarations", () => {
+		const first = {
+			check: ["tool", "--version"],
+			install: [{ formula: "tool", via: "brew" as const }],
+			name: "tool",
+		};
+		const reordered = {
+			name: "tool",
+			install: [{ via: "brew" as const, formula: "tool" }],
+			check: ["tool", "--version"],
+		};
+		const key = dedupeKey(first);
+		expect(key).toBe(dedupeKey(reordered));
+		expect(key).toMatch(/^tool-[0-9a-f]{12}$/);
+		for (const changed of [
+			{ ...first, name: "other" },
+			{ ...first, check: ["tool", "-V"] },
+			{
+				...first,
+				install: [{ formula: "other", via: "brew" as const }],
+			},
+		]) {
+			expect(dedupeKey(changed)).not.toBe(key);
+		}
+	});
+
+	// Spec: AS-BUILT.md §2, presence skips only self-named checks, full runs
+	// all checks, cwd/HOME are pinned, and only ${CLAUDE_PLUGIN_ROOT} expands.
+	test("presence skips a self-named check while full executes it", async () => {
+		const world = await makeWorld();
+		try {
+			await mkdir(join(world.root, "plugin"), { recursive: true });
+			await writeExecutable(
+				join(world.bin, "self-check"),
+				": > full-check-ran\nexit 7",
+			);
+			await writeExecutable(
+				join(world.bin, "runner"),
+				[
+					`[ "$1" = "${join(world.root, "plugin")}" ] || exit 2`,
+					"[ \"$2\" = '$HOME' ] || exit 3",
+					`[ "$HOME" = "${world.home}" ] || exit 4`,
+					": > presence-check-ran",
+					"exit 0",
+				].join("\n"),
+			);
+			const selfNamed = req("self-check", [
+				{ formula: "self-check", via: "brew" },
+			]);
+			const otherNamed = req(
+				"marker-check",
+				[{ formula: "marker-check", via: "brew" }],
+				["runner", "${CLAUDE_PLUGIN_ROOT}", "$HOME"],
+			);
+			const started = performance.now();
+			const presence = await probe(
+				[selfNamed, otherNamed],
+				env(world, { depth: "presence" }),
+			);
+			expect(performance.now() - started).toBeLessThan(1_000);
+			expect(presence).toEqual([
+				{ name: "self-check", status: "present" },
+				{ name: "marker-check", status: "present" },
+			]);
+			await expect(
+				access(join(world.root, "plugin", "full-check-ran")),
+			).rejects.toThrow();
+			expect(existsSync(join(world.root, "plugin", "presence-check-ran"))).toBe(
+				true,
+			);
+			const full = await probe(
+				[selfNamed, otherNamed],
+				env(world, { depth: "full" }),
+			);
+			expect(full).toEqual([
+				{ name: "self-check", status: "missing" },
+				{ name: "marker-check", status: "present" },
+			]);
+			expect(existsSync(join(world.root, "plugin", "full-check-ran"))).toBe(
+				true,
+			);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §2, a dangling symlink on PATH is missing and an
+	// executable under ~/.local/bin but off PATH is off-path with that prefix.
+	test("distinguishes dangling PATH entries from off-path user installs", async () => {
+		const world = await makeWorld();
+		try {
+			await mkdir(join(world.root, "plugin"), { recursive: true });
+			await symlink(
+				join(world.root, "does-not-exist"),
+				join(world.bin, "dangling"),
+			);
+			await writeExecutable(
+				join(world.home, ".local", "bin", "local-tool"),
+				"exit 0",
+			);
+			const result = await probe(
+				[
+					req("dangling", [{ formula: "dangling", via: "brew" }]),
+					req("local-tool", [{ formula: "local-tool", via: "brew" }]),
+				],
+				env(world, { depth: "presence" }),
+			);
+			expect(result).toEqual([
+				{ name: "dangling", status: "missing" },
+				{
+					name: "local-tool",
+					prefix: "~/.local/bin",
+					status: "off-path",
+				},
+			]);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §2, over capMs becomes unknown with reason “slow:
+	// no answer within Ns”.
+	test("caps slow checks as unknown rather than missing", async () => {
+		const world = await makeWorld();
+		try {
+			await mkdir(join(world.root, "plugin"), { recursive: true });
+			await writeExecutable(join(world.bin, "slow"), "/bin/sleep 2");
+			const result = await probe(
+				[req("slow", [{ formula: "slow", via: "brew" }])],
+				env(world, { capMs: 100 }),
+			);
+			expect(result).toEqual([
+				expect.objectContaining({
+					name: "slow",
+					reason: expect.stringMatching(/^slow: no answer within [0-9.]+s$/),
+					status: "unknown",
+				}),
+			]);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §2, a check using another declared requirement waits
+	// and becomes blockedBy without running when that requirement is absent.
+	test("blocks dependent checks behind a missing declared tool", async () => {
+		const world = await makeWorld();
+		try {
+			await mkdir(join(world.root, "plugin"), { recursive: true });
+			const result = await probe(
+				[
+					req("uv", [{ tool: "uv", via: "bootstrap" }]),
+					req(
+						"script-env",
+						[
+							{
+								args: ["--check"],
+								script: "scripts/tool.py",
+								via: "uv-script",
+							},
+						],
+						["uv", "run", "--script", "tool.py"],
+					),
+				],
+				env(world, { depth: "presence" }),
+			);
+			expect(result).toEqual([
+				{ name: "uv", status: "missing" },
+				{ blockedBy: "uv", name: "script-env", status: "missing" },
+			]);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §2, requirements whose os excludes env.os are
+	// skipped and absent from the ordered result.
+	test("filters requirements by operating system", async () => {
+		const world = await makeWorld();
+		try {
+			await mkdir(join(world.root, "plugin"), { recursive: true });
+			const darwinOnly = {
+				...req("mac-tool", [
+					{ formula: "mac-tool", os: ["darwin"], via: "brew" },
+				]),
+				os: ["darwin" as const],
+			};
+			const result = await probe(
+				[
+					darwinOnly,
+					req("linux-tool", [{ packages: ["linux-tool"], via: "apt" }]),
+				],
+				env(world, { depth: "presence", os: "linux" }),
+			);
+			expect(result).toEqual([{ name: "linux-tool", status: "missing" }]);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});
+
+describe("selection and rendering contract", () => {
+	// Spec: contract/requires-probe.d.ts selectOption/optionBlocker say the
+	// first OS-applicable option whose tools are present or planned wins.
+	test("selects the first usable option and explains blockers", () => {
+		const requirement = req("tool", [
+			{ formula: "tool", os: ["darwin"], via: "brew" },
+			{ os: ["linux"], packages: ["tool"], via: "apt" },
+		]);
+		const linux = { arch: "amd64" as const, os: "linux" as const };
+		const selected = selectOption(
+			requirement,
+			linux,
+			(tool) => tool === "apt-get",
+		);
+		expect(selected).toEqual({
+			os: ["linux"],
+			packages: ["tool"],
+			via: "apt",
+		});
+		expect(
+			optionBlocker({ formula: "tool", via: "brew" }, linux, () => false),
+		).toContain("Homebrew");
+		expect(
+			optionBlocker(
+				{
+					asset: "tool-{os}-{arch}",
+					binary: "tool",
+					repo: "Owner/repo",
+					sha256: {},
+					tag: "v1",
+					via: "release",
+				},
+				linux,
+				() => true,
+			),
+		).toBe("no pinned build for linux_amd64");
+		expect(whyUnselectable(requirement, linux, () => false)).toContain(
+			"apt-get",
+		);
+	});
+
+	// Spec: AS-BUILT.md §1 and §9.1 define every renderInstall via,
+	// including versions, escalation, and plugin-root scripts.
+	test("renderInstall maps every via to its structured step", () => {
+		const e = {
+			arch: "amd64" as const,
+			os: "linux" as const,
+			pluginRoot: "/tmp/plugin",
+		};
+		const cases: Array<[Requirement, InstallOption, InstallStep]> = [
+			[
+				req("bun-tool", []),
+				{ package: "pkg", version: "2", via: "bun" },
+				{
+					argv: ["bun", "add", "-g", "pkg@2"],
+					escalation: "none",
+					kind: "argv",
+					name: "bun-tool",
+				},
+			],
+			[
+				req("formula", []),
+				{ formula: "tool", via: "brew" },
+				{
+					argv: ["brew", "install", "tool"],
+					escalation: "none",
+					kind: "argv",
+					name: "formula",
+				},
+			],
+			[
+				req("cask", []),
+				{ cask: "visual", via: "brew" },
+				{
+					argv: ["brew", "install", "--cask", "visual"],
+					escalation: "none",
+					kind: "argv",
+					name: "cask",
+				},
+			],
+			[
+				req("apt", []),
+				{ packages: ["one", "two"], via: "apt" },
+				{
+					argv: [
+						"apt-get",
+						"install",
+						"-y",
+						"--no-install-recommends",
+						"one",
+						"two",
+					],
+					escalation: "sudo",
+					kind: "argv",
+					name: "apt",
+				},
+			],
+			[
+				req("release", []),
+				{
+					asset: "tool-{os}-{arch}.tgz",
+					binary: "tool",
+					repo: "Owner/repo",
+					sha256: { linux_amd64: digest },
+					tag: "v1",
+					via: "release",
+				},
+				{
+					binary: "tool",
+					dest: "~/.local/bin",
+					format: "tar.gz",
+					kind: "release",
+					name: "release",
+					sha256: digest,
+					url: "https://github.com/Owner/repo/releases/download/v1/tool-linux-amd64.tgz",
+				},
+			],
+			[
+				req("bun", []),
+				{ tool: "bun", via: "bootstrap" },
+				{
+					interpreter: "bash",
+					kind: "bootstrap",
+					name: "bun",
+					prefix: "~/.bun/bin",
+					url: "https://bun.sh/install",
+				},
+			],
+			[
+				req("script", []),
+				{ args: ["--check"], script: "scripts/a.py", via: "uv-script" },
+				{
+					argv: [
+						"uv",
+						"run",
+						"--no-config",
+						"--script",
+						"/tmp/plugin/scripts/a.py",
+						"--check",
+					],
+					escalation: "none",
+					kind: "argv",
+					name: "script",
+				},
+			],
+			[
+				req("module", []),
+				{
+					args: ["install"],
+					module: "playwright",
+					root: true,
+					script: "scripts/a.py",
+					via: "uv-module",
+				},
+				{
+					args: ["install"],
+					escalation: "sudo",
+					kind: "uv-module",
+					module: "playwright",
+					name: "module",
+					script: "/tmp/plugin/scripts/a.py",
+				},
+			],
+			[
+				req("npm", []),
+				{ package: "pkg", version: "3", via: "npm" },
+				{
+					argv: ["npm", "install", "-g", "pkg@3"],
+					escalation: "none",
+					kind: "argv",
+					name: "npm",
+				},
+			],
+			[
+				req("pip", []),
+				{ package: "pkg", version: "3", via: "pip" },
+				{
+					argv: ["uv", "tool", "install", "pkg==3"],
+					escalation: "none",
+					kind: "argv",
+					name: "pip",
+				},
+			],
+			[
+				req("go", []),
+				{ package: "example/tool", via: "go" },
+				{
+					argv: ["go", "install", "example/tool@latest"],
+					escalation: "none",
+					kind: "argv",
+					name: "go",
+				},
+			],
+		];
+		for (const [requirement, option, expected] of cases) {
+			expect(renderInstall(requirement, option, e)).toEqual(expected);
+		}
+	});
+
+	// Spec: AS-BUILT.md §1 describeStep joins argv, prefixes sudo,
+	// renders bootstrap, and uses the OS verifier and archive/bare commands.
+	test("describeStep renders argv, sudo, bootstrap, and both release forms", () => {
+		expect(
+			describeStep(
+				{
+					argv: ["tool", "argument"],
+					escalation: "none",
+					kind: "argv",
+					name: "tool",
+				},
+				"linux",
+			),
+		).toBe("tool argument");
+		expect(
+			describeStep(
+				{
+					argv: ["apt-get", "install", "thing"],
+					escalation: "sudo",
+					kind: "argv",
+					name: "thing",
+				},
+				"linux",
+			),
+		).toBe("sudo apt-get install thing");
+		expect(
+			describeStep(
+				{
+					interpreter: "bash",
+					kind: "bootstrap",
+					name: "bun",
+					prefix: "~/.bun/bin",
+					url: TOOLCHAIN_BOOTSTRAP.bun.url,
+				},
+				"linux",
+			),
+		).toBe("curl -fsSL https://bun.sh/install | bash");
+		const archive: InstallStep = {
+			binary: "tool",
+			dest: "~/.local/bin",
+			format: "tar.gz",
+			kind: "release",
+			name: "tool",
+			sha256: digest,
+			url: "https://github.com/Owner/repo/releases/download/v1/tool.tgz",
+		};
+		const linux = describeStep(archive, "linux");
+		const darwin = describeStep(archive, "darwin");
+		expect(linux).toContain("sha256sum -c");
+		expect(linux).toContain("tar -xzf tool.tgz tool");
+		expect(darwin).toContain("shasum -a 256 -c");
+		const bare = describeStep(
+			{ ...archive, format: "binary", url: archive.url.replace(".tgz", "") },
+			"linux",
+		);
+		expect(bare).not.toContain("tar -xzf");
+		expect(bare).toContain("install -m 755 tool ~/.local/bin/tool");
+	});
+
+	// Spec: contract/requires-probe.d.ts releaseAsset/releaseFormat define
+	// substitutions, release-specific arch spellings, and archive detection.
+	test("releaseAsset and releaseFormat share the release naming rules", () => {
+		expect(
+			releaseAsset(
+				{
+					arch: { amd64: "x64" },
+					asset: "tool-{os}-{arch}.tar.gz",
+				},
+				"linux",
+				"amd64",
+			),
+		).toBe("tool-linux-x64.tar.gz");
+		expect(releaseFormat("tool.tgz")).toBe("tar.gz");
+		expect(releaseFormat("tool.tar.gz")).toBe("tar.gz");
+		expect(releaseFormat("tool-linux-amd64")).toBe("binary");
+	});
+
+	// Spec: AS-BUILT.md §2 and contract requires-probe.d.ts define the two
+	// user prefixes, shell-specific rc lines, and rc file choices.
+	test("renders user prefix PATH advice for zsh, bash, and fish", () => {
+		expect(USER_PREFIXES.map(({ dir }) => dir)).toEqual([
+			"~/.bun/bin",
+			"~/.local/bin",
+		]);
+		expect(pathRcLine("~/.local/bin", "/bin/zsh")).toBe(
+			'export PATH="$HOME/.local/bin:$PATH"',
+		);
+		expect(pathRcLine("/opt/tools", "/bin/fish")).toBe(
+			"fish_add_path /opt/tools",
+		);
+		expect(rcFile("/bin/zsh")).toBe("~/.zshrc");
+		expect(rcFile("/usr/bin/fish")).toBe("~/.config/fish/config.fish");
+		expect(rcFile("/bin/bash")).toBe("~/.bashrc");
+	});
+
+	// Spec: AS-BUILT.md §3, renderFix returns null when healthy and an
+	// unknown-only result is silent.
+	test("renderFix is silent for healthy and unknown-only probes", async () => {
+		const world = await makeWorld();
+		try {
+			const requirement = req("tool", [{ formula: "tool", via: "brew" }]);
+			const e = env(world);
+			expect(
+				renderFix(
+					"plugin",
+					[{ name: "tool", status: "present" }],
+					[requirement],
+					e,
+					false,
+				),
+			).toBeNull();
+			expect(
+				renderFix(
+					"plugin",
+					[
+						{
+							name: "tool",
+							reason: "slow: no answer within 3s",
+							status: "unknown",
+						},
+					],
+					[requirement],
+					e,
+					false,
+				),
+			).toBeNull();
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3 specifies Fix all with magus on/off PATH,
+	// apt merging first, blocked/off-path/unknown lines, and the closing line.
+	test("renderFix builds the complete actionable banner", async () => {
+		const world = await makeWorld();
+		try {
+			await writeExecutable(join(world.bin, "apt-get"), "exit 0");
+			const released = (name: string): InstallOption => ({
+				asset: `${name}-{os}-{arch}`,
+				binary: name,
+				repo: "Owner/repo",
+				sha256: { linux_amd64: digest },
+				tag: "v1",
+				via: "release",
+			});
+			const requirements = [
+				req("one", [{ packages: ["pkg-one"], via: "apt" }]),
+				req("two", [{ packages: ["pkg-two"], via: "apt" }]),
+				req("blocked", [released("blocked")]),
+				req("local", [released("local")]),
+				req("slow", [released("slow")]),
+			];
+			const presences = [
+				{ name: "one", status: "missing" as const },
+				{ name: "two", status: "missing" as const },
+				{
+					blockedBy: "foundation",
+					name: "blocked",
+					status: "missing" as const,
+				},
+				{
+					name: "local",
+					prefix: "~/.local/bin" as const,
+					status: "off-path" as const,
+				},
+				{
+					name: "slow",
+					reason: "slow: no answer within 3s",
+					status: "unknown" as const,
+				},
+			];
+			const withoutMagus = renderFix(
+				"plugin",
+				presences,
+				requirements,
+				env(world),
+				false,
+			);
+			expect(withoutMagus).not.toBeNull();
+			if (withoutMagus === null) {
+				throw new Error("a real finding must render a banner");
+			}
+			expect(withoutMagus).toContain(
+				"Fix all: bun add -g magus-cli, then magus doctor --fix",
+			);
+			const aptLine = [
+				"one, two: sudo apt-get install -y --no-install-recommends ",
+				"pkg-one pkg-two",
+			].join("");
+			expect(withoutMagus).toContain(aptLine);
+			expect(withoutMagus).toContain("blocked (after foundation):");
+			expect(withoutMagus.indexOf(aptLine)).toBeLessThan(
+				withoutMagus.indexOf("blocked (after foundation):"),
+			);
+			expect(withoutMagus.match(/sudo apt-get/g)).toHaveLength(1);
+			expect(withoutMagus).toContain("unknown (slow) slow");
+			expect(withoutMagus).toContain(
+				"local is in ~/.local/bin, which is not on the PATH",
+			);
+			expect(withoutMagus).toContain(
+				'add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc',
+			);
+			expect(withoutMagus).toEndWith(
+				"Then restart Claude Code from a new terminal.",
+			);
+			const withMagus = renderFix(
+				"plugin",
+				presences,
+				requirements,
+				env(world),
+				true,
+			);
+			expect(withMagus).toContain("Fix all: magus doctor --fix");
+			expect(withMagus).not.toContain("bun add -g magus-cli");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3, a brew dependency with brew absent names
+	// Homebrew and https://brew.sh before any install can be selected.
+	test("renderFix explains a missing Homebrew prerequisite", async () => {
+		const world = await makeWorld();
+		try {
+			const requirement = req("tool", [{ formula: "tool", via: "brew" }]);
+			const banner = renderFix(
+				"plugin",
+				[{ name: "tool", status: "missing" }],
+				[requirement],
+				env(world),
+				false,
+			);
+			expect(banner).toContain(
+				"tool: Homebrew is missing — install it from https://brew.sh first",
+			);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});