magus-cli 7.8.0 → 7.9.0

package/src/__tests__/blind/plugin-deps/helpers.ts

@@ -0,0 +1,340 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import {
+	access,
+	chmod,
+	cp,
+	mkdir,
+	mkdtemp,
+	readFile,
+	realpath,
+	rm,
+	symlink,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const TOOLS_ROOT = join(import.meta.dir, "..", "..", "..", "..");
+export const REPO_ROOT = join(TOOLS_ROOT, "..", "..");
+export const MAGUS_MAIN = join(TOOLS_ROOT, "src", "main.tsx");
+export const HOOK_REFERENCE = join(TOOLS_ROOT, "src", "shared", "plugin");
+
+export interface World {
+	root: string;
+	home: string;
+	project: string;
+	bin: string;
+	tmp: string;
+	cache: string;
+}
+
+export interface ChildResult {
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+}
+
+export interface PluginEntry {
+	key: string;
+	root: string;
+	scope?: "user" | "project" | "local";
+}
+
+export async function makeWorld(): Promise<World> {
+	const root = await mkdtemp(join(tmpdir(), "magus-blind-"));
+	const world = {
+		root,
+		home: join(root, "home"),
+		project: join(root, "project"),
+		bin: join(root, "bin"),
+		tmp: join(root, "tmp"),
+		cache: join(root, "home", "cache"),
+	};
+	await Promise.all([
+		mkdir(world.home, { recursive: true }),
+		mkdir(world.project, { recursive: true }),
+		mkdir(world.bin, { recursive: true }),
+		mkdir(world.tmp, { recursive: true }),
+		mkdir(world.cache, { recursive: true }),
+	]);
+	return world;
+}
+
+export async function removeWorld(world: World): Promise<void> {
+	await rm(world.root, { recursive: true, force: true });
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function writeExecutable(
+	path: string,
+	body: string,
+): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `#!/bin/sh\n${body}\n`);
+	await chmod(path, 0o755);
+}
+
+export async function linkExecutable(
+	dir: string,
+	name: string,
+	target: string,
+): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	await symlink(target, join(dir, name));
+}
+
+export function pinnedEnv(
+	world: World,
+	pathDirs: string[],
+	extra: Record<string, string> = {},
+): NodeJS.ProcessEnv {
+	return {
+		HOME: world.home,
+		LANG: "C",
+		LC_ALL: "C",
+		MAGUS_NO_BINARY: "1",
+		NO_COLOR: "1",
+		PATH: pathDirs.join(":"),
+		SHELL: "/bin/zsh",
+		TMPDIR: world.tmp,
+		XDG_CACHE_HOME: world.cache,
+		...extra,
+	};
+}
+
+export async function runChild(
+	command: string,
+	args: string[],
+	options: {
+		cwd: string;
+		env: NodeJS.ProcessEnv;
+		input?: string;
+		timeoutMs?: number;
+	},
+): Promise<ChildResult> {
+	const child = spawn(command, args, {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+	const stdout: Buffer[] = [];
+	const stderr: Buffer[] = [];
+	child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+	child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+	child.stdin.end(options.input);
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		child.kill("SIGKILL");
+	}, options.timeoutMs ?? 15_000);
+	const exitCode = await new Promise<number | null>((resolve, reject) => {
+		child.on("error", reject);
+		child.on("close", resolve);
+	});
+	clearTimeout(timer);
+	return {
+		exitCode,
+		stdout: Buffer.concat(stdout).toString("utf8"),
+		stderr: Buffer.concat(stderr).toString("utf8"),
+		timedOut,
+	};
+}
+
+export async function runDoctor(
+	world: World,
+	args: string[],
+	options: {
+		pathDirs?: string[];
+		input?: string;
+		extraEnv?: Record<string, string>;
+		timeoutMs?: number;
+	} = {},
+): Promise<ChildResult> {
+	return runChild(
+		process.execPath,
+		["--no-env-file", MAGUS_MAIN, "doctor", ...args],
+		{
+			cwd: world.project,
+			env: pinnedEnv(world, options.pathDirs ?? [world.bin], options.extraEnv),
+			input: options.input,
+			timeoutMs: options.timeoutMs ?? 20_000,
+		},
+	);
+}
+
+export async function makePlugin(
+	world: World,
+	name: string,
+	requires: unknown,
+	parent = join(world.root, "plugins"),
+): Promise<string> {
+	const root = join(parent, name);
+	await writeJson(join(root, ".claude-plugin", "plugin.json"), {
+		name,
+		version: "1.0.0",
+		description: `${name} black-box testdata`,
+		requires,
+	});
+	return root;
+}
+
+export async function configureClaude(
+	world: World,
+	entries: PluginEntry[],
+): Promise<void> {
+	const claude = join(world.home, ".claude");
+	const clone = join(claude, "plugins", "marketplaces", "test");
+	const enabled = (scope: "user" | "project" | "local") =>
+		Object.fromEntries(
+			entries
+				.filter((entry) => (entry.scope ?? "user") === scope)
+				.map((entry) => [entry.key, true]),
+		);
+	await writeJson(join(claude, "settings.json"), {
+		enabledPlugins: enabled("user"),
+	});
+	await writeJson(join(world.project, ".claude", "settings.json"), {
+		enabledPlugins: enabled("project"),
+	});
+	await writeJson(join(world.project, ".claude", "settings.local.json"), {
+		enabledPlugins: enabled("local"),
+	});
+	await writeJson(join(claude, "plugins", "installed_plugins.json"), {
+		version: 2,
+		plugins: Object.fromEntries(
+			entries.map((entry) => [
+				entry.key,
+				[
+					{
+						installPath: entry.root,
+						installedAt: "2026-01-01T00:00:00.000Z",
+						lastUpdated: "2026-01-01T00:00:00.000Z",
+						projectPath: entry.scope === "project" ? world.project : undefined,
+						scope: entry.scope === "project" ? "project" : "user",
+						version: "1.0.0",
+					},
+				],
+			]),
+		),
+	});
+	await writeJson(join(claude, "plugins", "known_marketplaces.json"), {
+		test: {
+			installLocation: clone,
+			lastUpdated: "2026-01-01T00:00:00.000Z",
+			source: { repo: "Example/test", source: "github" },
+		},
+	});
+	await writeJson(join(clone, ".claude-plugin", "marketplace.json"), {
+		name: "test",
+		plugins: entries.map((entry) => ({
+			name: entry.key.split("@")[0],
+			source: `./plugins/${entry.key.split("@")[0]}`,
+			version: "1.0.0",
+		})),
+	});
+}
+
+export async function makeHookPlugin(
+	world: World,
+	name: string,
+	requires: unknown,
+): Promise<string> {
+	const root = await makePlugin(world, name, requires);
+	await mkdir(join(root, "hooks", "lib"), { recursive: true });
+	await Promise.all([
+		cp(
+			join(HOOK_REFERENCE, "hooks", "deps-check.ts"),
+			join(root, "hooks", "deps-check.ts"),
+		),
+		cp(
+			join(HOOK_REFERENCE, "hooks", "lib", "requires-probe.ts"),
+			join(root, "hooks", "lib", "requires-probe.ts"),
+		),
+		cp(
+			join(HOOK_REFERENCE, "hooks", "bun-missing.sh"),
+			join(root, "hooks", "bun-missing.sh"),
+		),
+	]);
+	return root;
+}
+
+export function hookCommand(label: string): string {
+	return [
+		"command -v bun >/dev/null 2>&1 && exec bun",
+		"--env-file=/dev/null --config=/dev/null",
+		`"\${CLAUDE_PLUGIN_ROOT}/hooks/deps-check.ts" ${label} || exec sh`,
+		`"\${CLAUDE_PLUGIN_ROOT}/hooks/bun-missing.sh" ${label}`,
+	].join(" ");
+}
+
+export async function runHook(
+	world: World,
+	pluginRoot: string,
+	label: string,
+	pathDirs: string[],
+	input: string,
+	shell = "/bin/zsh",
+): Promise<ChildResult> {
+	return runChild("/bin/sh", ["-c", hookCommand(label)], {
+		cwd: world.project,
+		env: pinnedEnv(world, pathDirs, {
+			CLAUDE_PLUGIN_ROOT: pluginRoot,
+			SHELL: shell,
+		}),
+		input,
+		timeoutMs: 9_500,
+	});
+}
+
+const SYSTEM_CANDIDATES: Record<string, string[]> = {
+	cat: ["/bin/cat", "/usr/bin/cat"],
+	find: ["/usr/bin/find", "/bin/find"],
+	mkdir: ["/bin/mkdir", "/usr/bin/mkdir"],
+	printf: ["/usr/bin/printf", "/bin/printf"],
+	rm: ["/bin/rm", "/usr/bin/rm"],
+	sed: ["/usr/bin/sed", "/bin/sed"],
+	sh: ["/bin/sh", "/usr/bin/sh"],
+	tar: ["/usr/bin/tar", "/bin/tar"],
+	tr: ["/usr/bin/tr", "/bin/tr"],
+};
+
+async function systemTool(name: string): Promise<string> {
+	for (const candidate of SYSTEM_CANDIDATES[name] ?? []) {
+		try {
+			await access(candidate, constants.X_OK);
+			return await realpath(candidate);
+		} catch {
+			// Try the next explicit system location.
+		}
+	}
+	throw new Error(`No system ${name} executable at a pinned location`);
+}
+
+export async function makeShellPath(world: World): Promise<string> {
+	const dir = join(world.root, "shell-bin");
+	await mkdir(dir, { recursive: true });
+	for (const name of Object.keys(SYSTEM_CANDIDATES)) {
+		await linkExecutable(dir, name, await systemTool(name));
+	}
+	return dir;
+}
+
+export async function readUtf8(path: string): Promise<string> {
+	return readFile(path, "utf8");
+}
+
+export function sessionInput(sessionId = "session-1"): string {
+	return JSON.stringify({
+		cwd: "/testdata",
+		hook_event_name: "SessionStart",
+		session_id: sessionId,
+		source: "startup",
+		transcript_path: "/testdata/transcript.jsonl",
+	});
+}

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

@@ -0,0 +1,328 @@
+import { describe, expect, test } from "bun:test";
+import { access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	type Requirement,
+	dedupeKey,
+} from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import {
+	linkExecutable,
+	makeHookPlugin,
+	makeShellPath,
+	makeWorld,
+	readUtf8,
+	removeWorld,
+	runHook,
+	sessionInput,
+	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 };
+}
+
+describe("registered SessionStart dependency hook", () => {
+	// Spec: AS-BUILT.md §3, the TypeScript hook writes seen/<label>=ts first,
+	// prints nothing when healthy, exits 0, and runs within the 10 s timeout.
+	test("is silent when healthy but records TypeScript branch observation", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(
+				world,
+				"healthy",
+				requires([
+					requirement("healthy-tool", [
+						{ formula: "healthy-tool", via: "brew" },
+					]),
+				]),
+			);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "healthy-tool"), "exit 0");
+			const result = await runHook(
+				world,
+				plugin,
+				"healthy",
+				[world.bin],
+				sessionInput("healthy-session"),
+			);
+			expect(result.timedOut).toBe(false);
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout).toBe("");
+			expect(
+				await readUtf8(
+					join(world.tmp, "magus-deps-healthy-session", "seen", "healthy"),
+				),
+			).toBe("ts");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3, a missing dependency produces one JSON line with
+	// systemMessage and SessionStart additionalContext naming sorted findings.
+	test("emits the documented magus-deps JSON banner for a missing tool", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(
+				world,
+				"missing",
+				requires([
+					requirement("widget", [{ packages: ["widget"], via: "apt" }]),
+				]),
+			);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "apt-get"), "exit 0");
+			const result = await runHook(
+				world,
+				plugin,
+				"missing",
+				[world.bin],
+				sessionInput("missing-session"),
+			);
+			expect(result.timedOut).toBe(false);
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout.trim().split("\n")).toHaveLength(1);
+			const banner = JSON.parse(result.stdout);
+			expect(banner.systemMessage).toContain(
+				"magus-deps · missing: missing widget.",
+			);
+			expect(banner.hookSpecificOutput).toEqual({
+				additionalContext: [
+					"missing's MCP servers and hooks will fail until these are ",
+					"installed: widget",
+				].join(""),
+				hookEventName: "SessionStart",
+			});
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3, per-session mkdir claims dedupe identical
+	// declarations across plugin copies so only the first reports.
+	test("deduplicates an identical declaration across two plugin copies", async () => {
+		const world = await makeWorld();
+		try {
+			const declaration = requires([
+				requirement("shared", [{ packages: ["shared"], via: "apt" }]),
+			]);
+			const first = await makeHookPlugin(world, "first", declaration);
+			const second = await makeHookPlugin(world, "second", declaration);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "apt-get"), "exit 0");
+			const input = sessionInput("dedupe-session");
+			const one = await runHook(world, first, "first", [world.bin], input);
+			const two = await runHook(world, second, "second", [world.bin], input);
+			expect(one.stdout).toContain("magus-deps");
+			expect(two.stdout).toBe("");
+			const ledger = join(world.tmp, "magus-deps-dedupe-session");
+			expect(await readUtf8(join(ledger, "seen", "first"))).toBe("ts");
+			expect(await readUtf8(join(ledger, "seen", "second"))).toBe("ts");
+			expect(await readdir(join(ledger, "claimed"))).toHaveLength(1);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3 and D11, different declarations with the same
+	// name get different keys and therefore are both reported.
+	test("reports both non-identical declarations of one dependency name", async () => {
+		const world = await makeWorld();
+		try {
+			const first = await makeHookPlugin(
+				world,
+				"first",
+				requires([
+					requirement("shared", [{ packages: ["shared-one"], via: "apt" }]),
+				]),
+			);
+			const second = await makeHookPlugin(
+				world,
+				"second",
+				requires([
+					requirement("shared", [{ packages: ["shared-two"], via: "apt" }]),
+				]),
+			);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "apt-get"), "exit 0");
+			const input = sessionInput("distinct-session");
+			const one = await runHook(world, first, "first", [world.bin], input);
+			const two = await runHook(world, second, "second", [world.bin], input);
+			expect(one.stdout).toContain("magus-deps");
+			expect(two.stdout).toContain("magus-deps");
+			expect(
+				await readdir(
+					join(world.tmp, "magus-deps-distinct-session", "claimed"),
+				),
+			).toHaveLength(2);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3, an invalid/unreadable session_id creates no
+	// ledger or claims, so every copy reports rather than suppressing findings.
+	test("stays loud across copies when the session id is unusable", async () => {
+		const world = await makeWorld();
+		try {
+			const declaration = requires([
+				requirement("shared", [{ packages: ["shared"], via: "apt" }]),
+			]);
+			const first = await makeHookPlugin(world, "first", declaration);
+			const second = await makeHookPlugin(world, "second", declaration);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "apt-get"), "exit 0");
+			const input = sessionInput("bad session id");
+			const one = await runHook(world, first, "first", [world.bin], input);
+			const two = await runHook(world, second, "second", [world.bin], input);
+			expect(one.stdout).toContain("magus-deps");
+			expect(two.stdout).toContain("magus-deps");
+			await expect(
+				access(join(world.tmp, "magus-deps-bad session id")),
+			).rejects.toThrow();
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3 sh branch gives the exact missing-Bun message,
+	// writes seen=sh, and claims bun-3182ab42b0f1 once across copies.
+	test("falls back without Bun and claims the canonical Bun key once", async () => {
+		const world = await makeWorld();
+		try {
+			const first = await makeHookPlugin(world, "first", requires([]));
+			const second = await makeHookPlugin(world, "second", requires([]));
+			const shellPath = await makeShellPath(world);
+			const input = sessionInput("no-bun-session");
+			const one = await runHook(world, first, "first", [shellPath], input);
+			const two = await runHook(world, second, "second", [shellPath], input);
+			expect(one.exitCode).toBe(0);
+			expect(one.timedOut).toBe(false);
+			expect(two.exitCode).toBe(0);
+			expect(two.stdout).toBe("");
+			const message = JSON.parse(one.stdout).systemMessage;
+			expect(message).toBe(
+				[
+					"magus-deps: Bun is missing — magus hooks and MCP servers need it ",
+					"(noticed by first).\n  Install: curl -fsSL https://bun.sh/install ",
+					"| bash, then restart Claude Code from a new terminal.",
+				].join(""),
+			);
+			const bunRequirement: Requirement = {
+				check: ["bun", "--version"],
+				install: [{ tool: "bun", via: "bootstrap" }],
+				name: "bun",
+			};
+			const key = dedupeKey(bunRequirement);
+			expect(key).toBe("bun-3182ab42b0f1");
+			const ledger = join(world.tmp, "magus-deps-no-bun-session");
+			expect(await readUtf8(join(ledger, "seen", "first"))).toBe("sh");
+			expect(await readUtf8(join(ledger, "seen", "second"))).toBe("sh");
+			expect(await readdir(join(ledger, "claimed"))).toEqual([key]);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3 sh branch reports off-PATH ~/.bun/bin/bun with
+	// zsh/bash/fish-specific rc line and file.
+	test("gives exact shell-specific advice for Bun installed off PATH", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(world, "offpath", requires([]));
+			const shellPath = await makeShellPath(world);
+			await writeExecutable(join(world.home, ".bun", "bin", "bun"), "exit 0");
+			const cases = [
+				{
+					file: "~/.zshrc",
+					line: 'export PATH="$HOME/.bun/bin:$PATH"',
+					shell: "/bin/zsh",
+				},
+				{
+					file: "~/.bashrc",
+					line: 'export PATH="$HOME/.bun/bin:$PATH"',
+					shell: "/bin/bash",
+				},
+				{
+					file: "~/.config/fish/config.fish",
+					line: "fish_add_path $HOME/.bun/bin",
+					shell: "/usr/bin/fish",
+				},
+			];
+			for (const [index, item] of cases.entries()) {
+				const result = await runHook(
+					world,
+					plugin,
+					"offpath",
+					[shellPath],
+					sessionInput(`offpath-${index}`),
+					item.shell,
+				);
+				expect(result.exitCode).toBe(0);
+				const message = JSON.parse(result.stdout).systemMessage;
+				expect(message).toBe(
+					[
+						"magus-deps: Bun is installed at ~/.bun/bin but is not on the ",
+						"PATH Claude Code started with, so magus hooks and MCP servers ",
+						"cannot run (noticed by offpath).\n  Add ",
+						`${item.line} to ${item.file}, then restart Claude Code from a `,
+						"new terminal.",
+					].join(""),
+				);
+			}
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// Spec: AS-BUILT.md §3, invalid requires says “please report” under an
+	// invalid-label claim; a bad label is silent; both branches always exit 0.
+	test("reports invalid requires but ignores an invalid label", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(world, "invalid", {
+				bin: [],
+				mystery: true,
+				schema: 1,
+			});
+			await linkExecutable(world.bin, "bun", process.execPath);
+			const input = sessionInput("invalid-session");
+			const invalid = await runHook(
+				world,
+				plugin,
+				"invalid",
+				[world.bin],
+				input,
+			);
+			expect(invalid.exitCode).toBe(0);
+			const message = JSON.parse(invalid.stdout).systemMessage;
+			expect(message).toContain("magus-deps · invalid: requires is invalid (");
+			expect(message).toContain("mystery");
+			expect(message).toEndWith("— please report");
+			expect(
+				await readdir(join(world.tmp, "magus-deps-invalid-session", "claimed")),
+			).toEqual(["invalid-invalid"]);
+			const badLabel = await runHook(
+				world,
+				plugin,
+				"Bad!",
+				[world.bin],
+				sessionInput("bad-label-session"),
+			);
+			expect(badLabel.exitCode).toBe(0);
+			expect(badLabel.stdout).toBe("");
+			expect(badLabel.timedOut).toBe(false);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});