magus-cli 7.8.0 → 7.9.0

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

@@ -0,0 +1,622 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	REPO_ROOT,
+	type World,
+	configureClaude,
+	makePlugin,
+	makeShellPath,
+	makeWorld,
+	removeWorld,
+	runChild,
+	runDoctor,
+	writeExecutable,
+} from "./helpers";
+
+function requirement(
+	name: string,
+	install: Record<string, unknown>[],
+	check = [name, "--version"],
+): Record<string, unknown> {
+	return { check, install, name };
+}
+
+function requires(bin: Record<string, unknown>[]): Record<string, unknown> {
+	return { bin, schema: 1 };
+}
+
+async function installPlugin(
+	world: World,
+	name: string,
+	requiresValue: unknown,
+	scope: "user" | "project" | "local" = "user",
+): Promise<string> {
+	const root = await makePlugin(world, name, requiresValue);
+	await configureClaude(world, [{ key: `${name}@test`, root, scope }]);
+	return root;
+}
+
+async function installPlugins(
+	world: World,
+	plugins: Array<{
+		name: string;
+		requires: unknown;
+		scope: "user" | "project" | "local";
+	}>,
+): Promise<void> {
+	const entries = [];
+	for (const plugin of plugins) {
+		const root = await makePlugin(world, plugin.name, plugin.requires);
+		entries.push({ key: `${plugin.name}@test`, root, scope: plugin.scope });
+	}
+	await configureClaude(world, entries);
+}
+
+async function fakeBun(world: World, body: string): Promise<void> {
+	await writeExecutable(
+		join(world.bin, "bun"),
+		`if [ "$1" = "--version" ]; then echo 1.4.0; exit 0; fi\n${body}`,
+	);
+}
+
+function bunAndWidget(): Record<string, unknown> {
+	return requires([
+		requirement("bun", [{ tool: "bun", via: "bootstrap" }]),
+		requirement("widget", [{ package: "widget", via: "bun" }]),
+	]);
+}
+
+function shellLines(...lines: string[]): string {
+	return lines.join("\n");
+}
+
+interface AppliedJson {
+	argv: string[];
+	dir?: string;
+	durationMs: number;
+	exitCode: number | null;
+	name: string;
+	outputTail: string;
+	remedy?: string;
+	status: string;
+}
+
+interface DepJson {
+	key: string;
+	name: string;
+	requiredBy: string[];
+	status: string;
+}
+
+interface ReportJson {
+	applied: AppliedJson[];
+	deps: DepJson[];
+	invalid: unknown[];
+	magusOnPath: boolean;
+	pathAdvice: Array<Record<string, unknown>>;
+	platform: { arch: string; os: string };
+	plugins: string[];
+	plugins_needing_update: unknown[];
+	schema: number;
+	unfixable: unknown[];
+}
+
+interface RawReleaseOption extends Record<string, unknown> {
+	sha256: Record<string, string>;
+}
+
+interface RawReleaseRequirement extends Record<string, unknown> {
+	install: RawReleaseOption[];
+	name: string;
+}
+
+function parsed(result: { stdout: string }): ReportJson {
+	return JSON.parse(result.stdout) as ReportJson;
+}
+
+describe("magus doctor black-box contract", () => {
+	// Spec: AS-BUILT.md §4, plugin set is enabledPlugins across user,
+	// project, and local settings, merges identical declarations, works with
+	// no profiles.json, and --json is exactly one dependency document.
+	test("discovers all enabled scopes without profiles and reports JSON shape", async () => {
+		const world = await makeWorld();
+		try {
+			const plugins = [
+				{ name: "user-tool", scope: "user" as const },
+				{ name: "project-tool", scope: "project" as const },
+				{ name: "local-tool", scope: "local" as const },
+			];
+			for (const plugin of plugins) {
+				await writeExecutable(join(world.bin, plugin.name), "exit 0");
+			}
+			await writeExecutable(join(world.bin, "shared-tool"), "exit 0");
+			await installPlugins(
+				world,
+				plugins.map((plugin) => ({
+					...plugin,
+					requires: requires([
+						requirement(plugin.name, [{ formula: plugin.name, via: "brew" }]),
+						requirement("shared-tool", [
+							{ formula: "shared-tool", via: "brew" },
+						]),
+					]),
+				})),
+			);
+			await expect(
+				access(join(world.home, ".claude", "profiles.json")),
+			).rejects.toThrow();
+			const result = await runDoctor(world, ["--json"]);
+			expect(result.timedOut).toBe(false);
+			expect(result.exitCode).toBe(0);
+			const report = parsed(result);
+			expect(report).toMatchObject({
+				invalid: [],
+				magusOnPath: false,
+				pathAdvice: [],
+				plugins_needing_update: [],
+				schema: 1,
+				unfixable: [],
+			});
+			expect(report.platform).toEqual({
+				arch: expect.any(String),
+				os: expect.stringMatching(/^(darwin|linux)$/),
+			});
+			expect(Object.keys(report).sort()).toEqual([
+				"deps",
+				"invalid",
+				"magusOnPath",
+				"pathAdvice",
+				"platform",
+				"plugins",
+				"plugins_needing_update",
+				"schema",
+				"unfixable",
+			]);
+			expect(new Set(report.plugins)).toEqual(
+				new Set(["user-tool@test", "project-tool@test", "local-tool@test"]),
+			);
+			expect(
+				Object.fromEntries(report.deps.map((dep) => [dep.name, dep.status])),
+			).toEqual({
+				"local-tool": "present",
+				"project-tool": "present",
+				"shared-tool": "present",
+				"user-tool": "present",
+			});
+			for (const dep of report.deps) {
+				expect(dep.key).toMatch(new RegExp(`^${dep.name}-[0-9a-f]{12}$`));
+				if (dep.name === "shared-tool") {
+					expect(new Set(dep.requiredBy)).toEqual(
+						new Set(["user-tool@test", "project-tool@test", "local-tool@test"]),
+					);
+				} else {
+					expect(dep.requiredBy).toEqual([`${dep.name}@test`]);
+				}
+			}
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §8.4, --json remains exactly one document under
+	// --fix; installer stdout and stderr appear only inside outputTail.
+	test("captures installer output without corrupting fix JSON stdout", async () => {
+		const world = await makeWorld();
+		try {
+			await installPlugin(world, "testdata", bunAndWidget());
+			await fakeBun(
+				world,
+				shellLines(
+					"echo installer-stdout",
+					"echo installer-stderr >&2",
+					': > "$INSTALL_MARKER"',
+					"printf '#!/bin/sh\\nexit 0\\n' > \"$INSTALL_DEST/widget\"",
+					'/bin/chmod 755 "$INSTALL_DEST/widget"',
+					"exit 0",
+				),
+			);
+			const marker = join(world.root, "installer-ran");
+			const result = await runDoctor(world, ["--fix", "--yes", "--json"], {
+				extraEnv: { INSTALL_DEST: world.bin, INSTALL_MARKER: marker },
+			});
+			expect(result.exitCode).toBe(0);
+			expect(result.stderr).not.toContain("installer-stderr");
+			const report = parsed(result);
+			expect(report.applied).toHaveLength(1);
+			expect(report.applied[0]).toMatchObject({
+				exitCode: 0,
+				name: "widget",
+				status: "installed",
+			});
+			expect(report.applied[0].argv.slice(-3)).toEqual(["add", "-g", "widget"]);
+			expect(report.applied[0].durationMs).toBeGreaterThanOrEqual(0);
+			expect(report.applied[0].outputTail).toContain("installer-stdout");
+			expect(report.applied[0].outputTail).toContain("installer-stderr");
+			expect(existsSync(marker)).toBe(true);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §4 and §8.1, --fix asks once; n and EOF install
+	// nothing, EOF exits 130, and --yes installs without asking.
+	test("honors decline, EOF cancellation, and --yes consent", async () => {
+		const world = await makeWorld();
+		try {
+			await installPlugin(world, "testdata", bunAndWidget());
+			const marker = join(world.root, "installer-ran");
+			await fakeBun(
+				world,
+				shellLines(
+					': > "$INSTALL_MARKER"',
+					"printf '#!/bin/sh\\nexit 0\\n' > \"$INSTALL_DEST/widget\"",
+					'/bin/chmod 755 "$INSTALL_DEST/widget"',
+					"exit 0",
+				),
+			);
+			const options = {
+				extraEnv: { INSTALL_DEST: world.bin, INSTALL_MARKER: marker },
+			};
+			const declined = await runDoctor(world, ["--fix"], {
+				...options,
+				input: "n\n",
+			});
+			expect(declined.exitCode).toBe(1);
+			expect(
+				`${declined.stdout}${declined.stderr}`.match(/Install them now\?/g),
+			).toHaveLength(1);
+			await expect(access(marker)).rejects.toThrow();
+			const eof = await runDoctor(world, ["--fix"], options);
+			expect(eof.exitCode).toBe(130);
+			expect(
+				`${eof.stdout}${eof.stderr}`.match(/Install them now\?/g),
+			).toHaveLength(1);
+			await expect(access(marker)).rejects.toThrow();
+			const accepted = await runDoctor(world, ["--fix", "--yes"], options);
+			expect(accepted.exitCode).toBe(0);
+			expect(`${accepted.stdout}${accepted.stderr}`).not.toContain(
+				"Install them now?",
+			);
+			expect(existsSync(marker)).toBe(true);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §8.2, --fix --json without --yes is refused before
+	// probing with exit 2, empty stdout, and the fixed explanation on stderr.
+	test("refuses interactive JSON fix with exit code 2", async () => {
+		const world = await makeWorld();
+		try {
+			await installPlugin(world, "testdata", bunAndWidget());
+			const marker = join(world.root, "bun-ran");
+			await writeExecutable(join(world.bin, "bun"), `: > "${marker}"\nexit 0`);
+			const result = await runDoctor(world, ["--fix", "--json"]);
+			expect(result.exitCode).toBe(2);
+			expect(result.stdout).toBe("");
+			expect(result.stderr.trim()).toBe(
+				[
+					"magus doctor --fix --json needs --yes: nothing can be asked while",
+					"stdout carries the report",
+				].join(" "),
+			);
+			await expect(access(marker)).rejects.toThrow();
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §4, installation into ~/.local/bin off the original
+	// PATH is off-path, exit 1, and includes the shell rc remedy.
+	test("reports a successful install off PATH instead of claiming health", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await installPlugin(
+				world,
+				"testdata",
+				requires([
+					requirement("uv", [{ tool: "uv", via: "bootstrap" }]),
+					requirement("widget", [
+						{
+							args: ["--install"],
+							script: "scripts/install.py",
+							via: "uv-script",
+						},
+					]),
+				]),
+			);
+			await mkdir(join(plugin, "scripts"), { recursive: true });
+			await writeFile(join(plugin, "scripts", "install.py"), "testdata\n");
+			await writeExecutable(
+				join(world.bin, "uv"),
+				shellLines(
+					'if [ "$1" = "--version" ]; then exit 0; fi',
+					'/bin/mkdir -p "$HOME/.local/bin"',
+					"printf '#!/bin/sh\\nexit 0\\n' > \"$HOME/.local/bin/widget\"",
+					'/bin/chmod 755 "$HOME/.local/bin/widget"',
+					"exit 0",
+				),
+			);
+			const result = await runDoctor(world, ["--fix", "--yes", "--json"]);
+			expect(result.exitCode).toBe(1);
+			const report = parsed(result);
+			expect(report.applied).toEqual([
+				expect.objectContaining({
+					dir: "~/.local/bin",
+					name: "widget",
+					status: "off-path",
+				}),
+			]);
+			expect(report.applied[0].remedy).toContain(
+				'export PATH="$HOME/.local/bin:$PATH"',
+			);
+			expect(report.applied[0].remedy).toContain(
+				"restart Claude Code from a new terminal",
+			);
+			expect(report.pathAdvice).toContainEqual({
+				prefix: "~/.local/bin",
+				rcFile: "~/.zshrc",
+				rcLine: 'export PATH="$HOME/.local/bin:$PATH"',
+			});
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §8.3, a failed post-install re-probe keeps the
+	// by-hand command in remedy and appends the failure reason to outputTail.
+	test("fails an exit-zero installer that leaves the requirement absent", async () => {
+		const world = await makeWorld();
+		try {
+			await installPlugin(world, "testdata", bunAndWidget());
+			await fakeBun(world, "echo did-nothing\nexit 0");
+			const result = await runDoctor(world, ["--fix", "--yes", "--json"]);
+			expect(result.exitCode).toBe(1);
+			const report = parsed(result);
+			expect(report.applied).toHaveLength(1);
+			expect(report.applied[0]).toMatchObject({
+				exitCode: 0,
+				name: "widget",
+				status: "failed",
+			});
+			expect(report.applied[0].remedy).toBe("bun add -g widget");
+			expect(report.applied[0].outputTail).toContain("did-nothing");
+			expect(report.applied[0].outputTail.trimEnd().split("\n").at(-1)).toBe(
+				"widget: the installer exited 0, but `widget --version` still fails",
+			);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	const nonRootTest =
+		typeof process.getuid === "function" && process.getuid() !== 0
+			? test
+			: test.skip;
+
+	// Spec: AS-BUILT.md §4, failed sudo -n true makes every root step
+	// needs-password before any runs; absent sudo makes it needs-root.
+	nonRootTest("preflights sudo and never partly runs root work", async () => {
+		const passwordWorld = await makeWorld();
+		try {
+			await installPlugin(
+				passwordWorld,
+				"testdata",
+				requires([
+					requirement("root-tool", [{ packages: ["root-tool"], via: "apt" }]),
+				]),
+			);
+			const aptMarker = join(passwordWorld.root, "apt-ran");
+			const sudoMarker = join(passwordWorld.root, "sudo-argv");
+			await writeExecutable(
+				join(passwordWorld.bin, "apt-get"),
+				`: > "${aptMarker}"\nexit 0`,
+			);
+			await writeExecutable(
+				join(passwordWorld.bin, "sudo"),
+				[
+					`printf '%s\\n' "$*" > "${sudoMarker}"`,
+					'[ "$1" = "-n" ] && [ "$2" = "true" ] && exit 1',
+					"exit 99",
+				].join("\n"),
+			);
+			const password = await runDoctor(passwordWorld, [
+				"--fix",
+				"--yes",
+				"--json",
+			]);
+			expect(password.exitCode).toBe(1);
+			expect(parsed(password).applied).toEqual([
+				expect.objectContaining({
+					name: "root-tool",
+					status: "needs-password",
+				}),
+			]);
+			expect(await readFile(sudoMarker, "utf8")).toBe("-n true\n");
+			await expect(access(aptMarker)).rejects.toThrow();
+		} finally {
+			await removeWorld(passwordWorld);
+		}
+
+		const noSudoWorld = await makeWorld();
+		try {
+			await installPlugin(
+				noSudoWorld,
+				"testdata",
+				requires([
+					requirement("root-tool", [{ packages: ["root-tool"], via: "apt" }]),
+				]),
+			);
+			const aptMarker = join(noSudoWorld.root, "apt-ran");
+			await writeExecutable(
+				join(noSudoWorld.bin, "apt-get"),
+				`: > "${aptMarker}"\nexit 0`,
+			);
+			const noSudo = await runDoctor(noSudoWorld, ["--fix", "--yes", "--json"]);
+			expect(noSudo.exitCode).toBe(1);
+			expect(parsed(noSudo).applied).toEqual([
+				expect.objectContaining({
+					name: "root-tool",
+					status: "needs-root",
+				}),
+			]);
+			await expect(access(aptMarker)).rejects.toThrow();
+		} finally {
+			await removeWorld(noSudoWorld);
+		}
+	});
+
+	// Spec: AS-BUILT.md §4, a live-pid doctor-fix lock refuses work while a
+	// dead-pid lock is taken over.
+	test("refuses a live install lock and takes over a stale lock", async () => {
+		const world = await makeWorld();
+		try {
+			await installPlugin(world, "testdata", bunAndWidget());
+			const marker = join(world.root, "installer-ran");
+			await fakeBun(
+				world,
+				shellLines(
+					`: > "${marker}"`,
+					"printf '#!/bin/sh\\nexit 0\\n' > \"$INSTALL_DEST/widget\"",
+					'/bin/chmod 755 "$INSTALL_DEST/widget"',
+					"exit 0",
+				),
+			);
+			const lock = join(world.cache, "magus", "doctor-fix.lock");
+			await mkdir(join(world.cache, "magus"), { recursive: true });
+			await writeFile(lock, `${process.pid}\n`);
+			const options = { extraEnv: { INSTALL_DEST: world.bin } };
+			const live = await runDoctor(
+				world,
+				["--fix", "--yes", "--json"],
+				options,
+			);
+			expect(live.exitCode).toBe(1);
+			expect(`${live.stdout}${live.stderr}`).toContain(
+				`another magus dependency install (pid ${process.pid}) is running`,
+			);
+			await expect(access(marker)).rejects.toThrow();
+			await writeFile(lock, "2147483647\n");
+			const stale = await runDoctor(
+				world,
+				["--fix", "--yes", "--json"],
+				options,
+			);
+			expect(stale.exitCode).toBe(0);
+			expect(parsed(stale).applied[0]).toMatchObject({
+				name: "widget",
+				status: "installed",
+			});
+			expect(existsSync(marker)).toBe(true);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});
+
+const supportedPlatform =
+	(process.platform === "darwin" || process.platform === "linux") &&
+	(process.arch === "x64" || process.arch === "arm64");
+const networkTest =
+	process.env.MAGUS_BLACKBOX_NETWORK === "1" && supportedPlatform
+		? test
+		: test.skip;
+
+async function realReleaseRequirement(): Promise<RawReleaseRequirement> {
+	const path = join(
+		REPO_ROOT,
+		"plugins",
+		"terminal",
+		".claude-plugin",
+		"plugin.json",
+	);
+	const manifest = JSON.parse(await readFile(path, "utf8")) as {
+		requires: { bin: RawReleaseRequirement[] };
+	};
+	const requirement = manifest.requires.bin.find(
+		(item) => item.name === "tmux-mcp",
+	);
+	if (!requirement) {
+		throw new Error("terminal manifest does not declare tmux-mcp");
+	}
+	return requirement;
+}
+
+describe("real pinned release", () => {
+	// Spec: AS-BUILT.md §4 observed release and §6 permit reading terminal's
+	// pinned v2.0.0 digests; real downloads require MAGUS_BLACKBOX_NETWORK=1.
+	networkTest(
+		"installs and verifies the pinned tmux-mcp v2.0.0 release",
+		async () => {
+			const world = await makeWorld();
+			try {
+				const requirement = await realReleaseRequirement();
+				await installPlugin(world, "testdata", requires([requirement]));
+				const shellPath = await makeShellPath(world);
+				const localBin = join(world.home, ".local", "bin");
+				await mkdir(localBin, { recursive: true });
+				const result = await runDoctor(world, ["--fix", "--yes", "--json"], {
+					pathDirs: [localBin, shellPath],
+					timeoutMs: 120_000,
+				});
+				expect(result.exitCode).toBe(0);
+				expect(parsed(result).applied[0]).toMatchObject({
+					name: "tmux-mcp",
+					status: "installed",
+				});
+				const version = await runChild(
+					join(localBin, "tmux-mcp"),
+					["--version"],
+					{
+						cwd: world.project,
+						env: { HOME: world.home, PATH: localBin },
+						timeoutMs: 5_000,
+					},
+				);
+				expect(version.exitCode).toBe(0);
+				expect(`${version.stdout}${version.stderr}`).toContain("2.0.0");
+			} finally {
+				await removeWorld(world);
+			}
+		},
+	);
+
+	// Spec: AS-BUILT.md §4, a release digest mismatch fails closed and writes
+	// nothing to ~/.local/bin; real downloads are opt-in.
+	networkTest(
+		"rejects altered release digest without writing the binary",
+		async () => {
+			const world = await makeWorld();
+			try {
+				const requirement = await realReleaseRequirement();
+				const option = requirement.install[0];
+				const os = process.platform;
+				const arch = process.arch === "x64" ? "amd64" : "arm64";
+				const platform = `${os}_${arch}`;
+				const original = option.sha256[platform];
+				option.sha256[platform] =
+					`${original[0] === "0" ? "1" : "0"}${original.slice(1)}`;
+				await installPlugin(world, "testdata", requires([requirement]));
+				const shellPath = await makeShellPath(world);
+				const localBin = join(world.home, ".local", "bin");
+				await mkdir(localBin, { recursive: true });
+				const result = await runDoctor(world, ["--fix", "--yes", "--json"], {
+					pathDirs: [localBin, shellPath],
+					timeoutMs: 120_000,
+				});
+				expect(result.exitCode).toBe(1);
+				expect(parsed(result).applied[0]).toMatchObject({
+					name: "tmux-mcp",
+					status: "failed",
+				});
+				await expect(access(join(localBin, "tmux-mcp"))).rejects.toThrow();
+				expect(await readdir(localBin)).toEqual([]);
+			} finally {
+				await removeWorld(world);
+			}
+		},
+	);
+});