magus-cli 7.3.1 → 7.4.0

package/src/__tests__/blind/c15-probe-ownership.test.ts

@@ -0,0 +1,533 @@
+/**
+ * Blind tests — contract C15 (requirements R9.7, R9.8).
+ *
+ * Written from requirements.md and architecture.md only. Every fact reaches
+ * `probeTools` through a scripted fake `ToolProbeIO`: a small in-memory file
+ * system (files, symlinks, realpaths), a PATH table, an `npm root -g` answer
+ * and an npm registry that answers dist-tags. Nothing touches the real disk,
+ * network or PATH.
+ *
+ * Fake-IO conventions come from C15's "Observable facts for a fake IO":
+ *  - `npm root -g` is asked via exec({ cmd: "npm", args: ["root", "-g"] });
+ *  - the registry is fetchJson(<registry>/-/package/<url-encoded pkg>/dist-tags)
+ *    answering { latest }; registry https://registry.npmjs.org by default;
+ *  - a package's version is readJson(<package dir>/package.json);
+ *  - an exec nobody scripted returns { code: 1, …, missing: true }.
+ */
+import { describe, expect, test } from "bun:test";
+import { posix } from "node:path";
+import {
+	type ToolFacts,
+	type ToolProbeIO,
+	classifyTool,
+	probeTools,
+} from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+
+const NPM_REGISTRY = "https://registry.npmjs.org";
+
+const CRUSH: BinRequirement = {
+	name: "crush",
+	via: "npm",
+	package: "@charmland/crush",
+};
+const CLAUDE: BinRequirement = {
+	name: "claude",
+	via: "npm",
+	package: "@anthropic-ai/claude-code",
+};
+
+// ── fake IO ─────────────────────────────────────────────────────────────────
+
+interface World {
+	homedir: string;
+	env: Record<string, string | undefined>;
+	/** name → first executable on PATH, AS FOUND (unresolved). */
+	onPath: Record<string, string>;
+	/** readlink table (the literal link target, may be relative). */
+	links?: Record<string, string>;
+	/** realpath table for symlinks. Any other existing path is its own realpath. */
+	real?: Record<string, string>;
+	/** Existing regular files and their text. */
+	files?: Record<string, string>;
+	/** Existing directories with no listed file inside. */
+	dirs?: string[];
+	/** "cmd arg1 arg2" → stdout, exit 0. */
+	exec?: Record<string, string>;
+	/** Tool basename → stdout for a lone version flag (`--version`, `-v`, …). */
+	versionOutput?: Record<string, string>;
+	/** package → dist-tags body. */
+	distTags?: Record<string, Record<string, string>>;
+}
+
+const VERSION_FLAGS = new Set(["--version", "-v", "-V", "version"]);
+
+const MISSING = {
+	code: 1,
+	stdout: "",
+	stderr: "",
+	timedOut: false,
+	missing: true,
+} as const;
+
+interface Log {
+	execs: string[];
+	fetches: string[];
+}
+
+function fakeIO(world: World): ToolProbeIO & { log: Log } {
+	const log: Log = { execs: [], fetches: [] };
+	const norm = (p: string): string | null =>
+		p.startsWith("/") ? posix.resolve(p) : null;
+
+	const existing = new Set<string>();
+	const addWithAncestors = (p: string) => {
+		for (let d = posix.resolve(p); ; d = posix.dirname(d)) {
+			existing.add(d);
+			if (d === "/") break;
+		}
+	};
+	for (const f of Object.keys(world.files ?? {})) addWithAncestors(f);
+	for (const d of world.dirs ?? []) addWithAncestors(d);
+	for (const t of Object.values(world.real ?? {})) addWithAncestors(t);
+	for (const p of Object.values(world.onPath)) addWithAncestors(p);
+
+	return {
+		log,
+		env: world.env,
+		homedir: world.homedir,
+		async exec(command) {
+			const key = [command.cmd, ...command.args].join(" ");
+			log.execs.push(key);
+			const scripted = world.exec?.[key];
+			if (scripted !== undefined) {
+				return {
+					code: 0,
+					stdout: scripted,
+					stderr: "",
+					timedOut: false,
+					missing: false,
+				};
+			}
+			const version = world.versionOutput?.[posix.basename(command.cmd)];
+			if (
+				version !== undefined &&
+				command.args.length === 1 &&
+				VERSION_FLAGS.has(command.args[0] as string)
+			) {
+				return {
+					code: 0,
+					stdout: version,
+					stderr: "",
+					timedOut: false,
+					missing: false,
+				};
+			}
+			return { ...MISSING };
+		},
+		async fetchJson(url) {
+			log.fetches.push(url);
+			const base = (world.env.npm_config_registry ?? NPM_REGISTRY).replace(
+				/\/+$/,
+				"",
+			);
+			if (!url.startsWith(`${base}/`)) return { ok: false, reason: "no host" };
+			const m = url
+				.slice(base.length)
+				.match(/^\/-\/package\/(.+)\/dist-tags\/?$/);
+			if (!m) return { ok: false, reason: "404" };
+			let pkg: string;
+			try {
+				pkg = decodeURIComponent(m[1] as string);
+			} catch {
+				return { ok: false, reason: "bad name" };
+			}
+			const body = world.distTags?.[pkg];
+			return body ? { ok: true, body } : { ok: false, reason: "404" };
+		},
+		async readJson(file) {
+			const n = norm(file);
+			const text = n === null ? undefined : world.files?.[n];
+			if (text === undefined) return null;
+			try {
+				return JSON.parse(text);
+			} catch {
+				return null;
+			}
+		},
+		async readText(file) {
+			const n = norm(file);
+			return n === null ? null : (world.files?.[n] ?? null);
+		},
+		async readlink(file) {
+			const n = norm(file);
+			return n === null ? null : (world.links?.[n] ?? null);
+		},
+		async realpath(file) {
+			const n = norm(file);
+			if (n === null) return null;
+			const r = world.real?.[n];
+			if (r !== undefined) return r;
+			return existing.has(n) ? n : null;
+		},
+		async resolveExecutable(name) {
+			return world.onPath[name] ?? null;
+		},
+	};
+}
+
+async function probe(
+	spec: BinRequirement,
+	world: World,
+): Promise<{ facts: ToolFacts; log: Log }> {
+	const io = fakeIO(world);
+	const all = await probeTools([spec], io);
+	const facts = all.find((f) => f.name === spec.name) ?? all[0];
+	if (!facts) throw new Error("probeTools returned no facts");
+	return { facts, log: io.log };
+}
+
+const pkgJson = (name: string, version: string) =>
+	JSON.stringify({ name, version, bin: { crush: "run-crush.js" } });
+
+// ── worlds ──────────────────────────────────────────────────────────────────
+
+const NVM = "/fake/nvm";
+const NVM_CRUSH_PKG = `${NVM}/lib/node_modules/@charmland/crush`;
+
+/**
+ * (a)/(b): crush installed by an nvm node's npm. PATH finds /fake/nvm/bin/crush,
+ * a symlink into /fake/nvm/lib/node_modules/@charmland/crush/run-crush.js.
+ * `npmRoot` is what `npm root -g` answers (the npm first on PATH).
+ */
+function nvmCrush(npmRoot: string, latest = "0.60.0"): World {
+	const npmPrefix = posix.dirname(posix.dirname(npmRoot));
+	return {
+		homedir: "/fake/home",
+		env: {
+			HOME: "/fake/home",
+			PATH: `${NVM}/bin:${npmPrefix}/bin:/usr/bin:/bin`,
+		},
+		onPath: {
+			crush: `${NVM}/bin/crush`,
+			npm: `${npmPrefix}/bin/npm`,
+		},
+		links: {
+			[`${NVM}/bin/crush`]: "../lib/node_modules/@charmland/crush/run-crush.js",
+		},
+		real: {
+			[`${NVM}/bin/crush`]: `${NVM_CRUSH_PKG}/run-crush.js`,
+		},
+		files: {
+			[`${NVM_CRUSH_PKG}/package.json`]: pkgJson("@charmland/crush", "0.55.0"),
+			[`${NVM_CRUSH_PKG}/run-crush.js`]: "#!/usr/bin/env node\n",
+			[`${npmPrefix}/bin/npm`]: "#!/usr/bin/env node\n",
+		},
+		dirs: [npmRoot],
+		exec: {
+			"npm root -g": `${npmRoot}\n`,
+			"npm prefix -g": `${npmPrefix}\n`,
+		},
+		distTags: { "@charmland/crush": { latest } },
+	};
+}
+
+/** (a): npm on PATH is a DIFFERENT node install than the one crush lives in. */
+const OTHER_NPM_ROOT = "/fake/local/lib/node_modules";
+
+/** The value that follows `--prefix` in an argv, or undefined. */
+function prefixOf(args: readonly string[]): string | undefined {
+	const i = args.indexOf("--prefix");
+	return i >= 0 ? args[i + 1] : undefined;
+}
+
+// ── R9.7 (a): binary inside a DIFFERENT prefix than `npm root -g` ───────────
+
+describe("C15 (a) — npm package in a prefix other than `npm root -g`", () => {
+	test("R9.7 the tool is npm-managed", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		expect(facts.managed).toBe(true);
+	});
+
+	test("R9.7 the installed version comes from that package's package.json", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		expect(facts.installed).toBe("0.55.0");
+	});
+
+	test("R9.7 the latest version comes from the npm registry", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		expect(facts.latest).toBe("0.60.0");
+	});
+
+	test("R9.7 the upgrade command is npm install -g --prefix <that prefix> <package>@latest", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		const uc = facts.upgradeCommand;
+		expect(uc).toBeDefined();
+		expect(posix.basename(uc?.cmd ?? "")).toBe("npm");
+		const args = uc?.args ?? [];
+		for (const a of [
+			"install",
+			"-g",
+			"--prefix",
+			NVM,
+			"@charmland/crush@latest",
+		])
+			expect(args).toContain(a);
+		// npm reads the prefix from the argument right after --prefix.
+		expect(prefixOf(args)).toBe(NVM);
+	});
+
+	test("R9.7 classifyTool says upgrade, never the not-managed veto", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		const status = classifyTool(CRUSH, facts);
+		expect(status.state).toBe("upgrade");
+		expect(status.reason).not.toBe("not-managed");
+	});
+
+	test("R9.7 control: at the registry's latest, classifyTool says current (still managed)", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT, "0.55.0"));
+		expect(facts.managed).toBe(true);
+		expect(classifyTool(CRUSH, facts).state).toBe("current");
+	});
+
+	test("R9.7 probing only reads: it never runs an install", async () => {
+		const { log } = await probe(CRUSH, nvmCrush(OTHER_NPM_ROOT));
+		expect(log.execs.filter((c) => /\b(install|add|update)\b/.test(c))).toEqual(
+			[],
+		);
+	});
+});
+
+// ── R9.7 (b): binary inside the prefix `npm root -g` reports ────────────────
+
+describe("C15 (b) — npm package in the prefix `npm root -g` reports", () => {
+	const SAME_ROOT = `${NVM}/lib/node_modules`;
+
+	test("R9.7 the tool is npm-managed", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(SAME_ROOT));
+		expect(facts.managed).toBe(true);
+	});
+
+	test("R9.7 the upgrade command carries no --prefix", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(SAME_ROOT));
+		const args = facts.upgradeCommand?.args ?? [];
+		expect(
+			args.some((a) => a === "--prefix" || a.startsWith("--prefix=")),
+		).toBe(false);
+	});
+
+	test("R9.7 version from package.json, latest from the registry, classified upgrade", async () => {
+		const { facts } = await probe(CRUSH, nvmCrush(SAME_ROOT));
+		expect({ installed: facts.installed, latest: facts.latest }).toEqual({
+			installed: "0.55.0",
+			latest: "0.60.0",
+		});
+		const status = classifyTool(CRUSH, facts);
+		expect(status.state).toBe("upgrade");
+		expect(status.reason).not.toBe("not-managed");
+	});
+});
+
+// ── R9.7 (c): negatives — the binary is not inside lib/node_modules/<package> ─
+
+describe("C15 (c) — a crush binary that npm does not own", () => {
+	/** PATH crush is a plain file elsewhere; npm's own copy sits at npm root -g. */
+	function elsewhere(): World {
+		const npmPkg = `${OTHER_NPM_ROOT}/@charmland/crush`;
+		return {
+			homedir: "/fake/home",
+			env: {
+				HOME: "/fake/home",
+				PATH: "/fake/elsewhere:/fake/local/bin:/usr/bin:/bin",
+			},
+			onPath: { crush: "/fake/elsewhere/crush", npm: "/fake/local/bin/npm" },
+			files: {
+				"/fake/elsewhere/crush": "ELF binary\n",
+				[`${npmPkg}/package.json`]: pkgJson("@charmland/crush", "0.55.0"),
+				[`${npmPkg}/run-crush.js`]: "#!/usr/bin/env node\n",
+				"/fake/local/bin/npm": "#!/usr/bin/env node\n",
+			},
+			exec: {
+				"npm root -g": `${OTHER_NPM_ROOT}\n`,
+				"npm prefix -g": "/fake/local\n",
+			},
+			versionOutput: { crush: "crush version 0.55.0\n" },
+			distTags: { "@charmland/crush": { latest: "0.60.0" } },
+		};
+	}
+
+	test("R9.7 a binary outside any lib/node_modules/<package> is not npm-managed", async () => {
+		const { facts } = await probe(CRUSH, elsewhere());
+		expect(facts.managed).not.toBe(true);
+	});
+
+	test("R9.7 classifyTool keeps the not-managed veto for it (unknown / not-managed)", async () => {
+		const { facts } = await probe(CRUSH, elsewhere());
+		const status = classifyTool(CRUSH, facts);
+		expect({ state: status.state, reason: status.reason }).toEqual({
+			state: "unknown",
+			reason: "not-managed",
+		});
+	});
+
+	test("R9.7 a binary inside lib/node_modules of a DIFFERENT package is not managed as this one", async () => {
+		const otherPkg = `${NVM}/lib/node_modules/some-other-tool`;
+		const world = nvmCrush(OTHER_NPM_ROOT);
+		world.links = {
+			[`${NVM}/bin/crush`]: "../lib/node_modules/some-other-tool/cli.js",
+		};
+		world.real = { [`${NVM}/bin/crush`]: `${otherPkg}/cli.js` };
+		world.files = {
+			[`${otherPkg}/package.json`]: JSON.stringify({
+				name: "some-other-tool",
+				version: "3.0.0",
+			}),
+			[`${otherPkg}/cli.js`]: "#!/usr/bin/env node\n",
+			"/fake/local/bin/npm": "#!/usr/bin/env node\n",
+		};
+		const { facts } = await probe(CRUSH, world);
+		expect(facts.managed).not.toBe(true);
+		expect(prefixOf(facts.upgradeCommand?.args ?? [])).toBeUndefined();
+	});
+});
+
+// ── R9.8 (d): Claude Code's native installer layout ─────────────────────────
+
+const HOME = "/fake/home";
+const NATIVE_BIN = `${HOME}/.local/bin/claude`;
+const NATIVE_TARGET = `${HOME}/.local/share/claude/versions/2.1.276`;
+
+function nativeClaude(opts: { latest?: string; npmCopy?: string } = {}): World {
+	const files: Record<string, string> = {
+		[NATIVE_TARGET]: "ELF claude native binary\n",
+		"/fake/local/bin/npm": "#!/usr/bin/env node\n",
+	};
+	if (opts.npmCopy) {
+		const pkg = `${OTHER_NPM_ROOT}/@anthropic-ai/claude-code`;
+		files[`${pkg}/package.json`] = JSON.stringify({
+			name: "@anthropic-ai/claude-code",
+			version: opts.npmCopy,
+		});
+		files[`${pkg}/cli.js`] = "#!/usr/bin/env node\n";
+	}
+	return {
+		homedir: HOME,
+		env: { HOME, PATH: `${HOME}/.local/bin:/fake/local/bin:/usr/bin:/bin` },
+		onPath: { claude: NATIVE_BIN, npm: "/fake/local/bin/npm" },
+		links: { [NATIVE_BIN]: NATIVE_TARGET },
+		real: { [NATIVE_BIN]: NATIVE_TARGET },
+		files,
+		dirs: [OTHER_NPM_ROOT],
+		exec: {
+			"npm root -g": `${OTHER_NPM_ROOT}\n`,
+			"npm prefix -g": "/fake/local\n",
+		},
+		distTags: {
+			"@anthropic-ai/claude-code": { latest: opts.latest ?? "2.1.280" },
+		},
+	};
+}
+
+describe("C15 (d) — claude resolving into <home>/.local/share/claude/versions/<version>", () => {
+	test("R9.8 the installed version is the <version> directory name", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude());
+		expect(facts.installed).toBe("2.1.276");
+	});
+
+	test("R9.8 the latest comes from the npm registry for @anthropic-ai/claude-code", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude());
+		expect(facts.latest).toBe("2.1.280");
+	});
+
+	test("R9.8 it is managed (by Claude Code's own updater)", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude());
+		expect(facts.managed).toBe(true);
+	});
+
+	test("R9.8 the upgrade command is `claude update`", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude());
+		expect(facts.upgradeCommand).toEqual({ cmd: "claude", args: ["update"] });
+	});
+
+	test("R9.8 classifyTool says upgrade, never the not-managed veto", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude());
+		const status = classifyTool(CLAUDE, facts);
+		expect(status.state).toBe("upgrade");
+		expect(status.reason).not.toBe("not-managed");
+	});
+
+	test("R9.8 an npm copy of claude-code at `npm root -g` does not trigger the second-copy veto", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude({ npmCopy: "2.0.1" }));
+		expect({
+			installed: facts.installed,
+			managed: facts.managed,
+			upgradeCommand: facts.upgradeCommand,
+		}).toEqual({
+			installed: "2.1.276",
+			managed: true,
+			upgradeCommand: { cmd: "claude", args: ["update"] },
+		});
+		const status = classifyTool(CLAUDE, facts);
+		expect(status.state).toBe("upgrade");
+		expect(status.reason).not.toBe("not-managed");
+	});
+
+	test("R9.8 control: at the registry's latest, classifyTool says current", async () => {
+		const { facts } = await probe(CLAUDE, nativeClaude({ latest: "2.1.276" }));
+		expect(classifyTool(CLAUDE, facts).state).toBe("current");
+	});
+
+	test("R9.8 probing only reads: it never runs `claude update` or an install", async () => {
+		const { log } = await probe(CLAUDE, nativeClaude());
+		expect(log.execs.filter((c) => /\b(install|add|update)\b/.test(c))).toEqual(
+			[],
+		);
+	});
+});
+
+// ── R9.8 (e): negative — a claude that is not the native layout ─────────────
+
+describe("C15 (e) — a claude binary outside the native layout and outside node_modules", () => {
+	function strayClaude(): World {
+		return {
+			homedir: HOME,
+			env: { HOME, PATH: "/fake/opt/claude/bin:/fake/local/bin:/usr/bin:/bin" },
+			onPath: {
+				claude: "/fake/opt/claude/bin/claude",
+				npm: "/fake/local/bin/npm",
+			},
+			files: {
+				"/fake/opt/claude/bin/claude": "ELF claude\n",
+				"/fake/local/bin/npm": "#!/usr/bin/env node\n",
+			},
+			dirs: [OTHER_NPM_ROOT],
+			exec: {
+				"npm root -g": `${OTHER_NPM_ROOT}\n`,
+				"npm prefix -g": "/fake/local\n",
+			},
+			versionOutput: { claude: "2.1.276 (Claude Code)\n" },
+			distTags: { "@anthropic-ai/claude-code": { latest: "2.1.280" } },
+		};
+	}
+
+	test("R9.8 its upgrade command is not `claude update`", async () => {
+		const { facts } = await probe(CLAUDE, strayClaude());
+		const uc = facts.upgradeCommand;
+		const isClaudeUpdate =
+			uc !== undefined &&
+			posix.basename(uc.cmd) === "claude" &&
+			uc.args.length === 1 &&
+			uc.args[0] === "update";
+		expect(isClaudeUpdate).toBe(false);
+	});
+
+	test("R9.8 it is not managed, and classifyTool keeps the not-managed veto", async () => {
+		const { facts } = await probe(CLAUDE, strayClaude());
+		expect(facts.managed).not.toBe(true);
+		const status = classifyTool(CLAUDE, facts);
+		expect({ state: status.state, reason: status.reason }).toEqual({
+			state: "unknown",
+			reason: "not-managed",
+		});
+	});
+});