magus-cli 7.5.3 → 7.5.4

package/src/__tests__/update-null-readback.test.ts

@@ -0,0 +1,300 @@
+/**
+ * Spec 7.5.4 re-review — REQ-11: an update that records no version is "no change",
+ * never "moved".
+ *
+ * Written blind: from the spec and the exported signatures of `applyPlugins`,
+ * `PluginApplyDeps`, `ApplyReporter`, `PluginApplyResult` and `PluginUpdateItem` only.
+ *
+ * magus judges an update by READ-BACK: after the installer runs it reads the version
+ * recorded at each scope it touched, and only a changed version counts as moved. These
+ * tests drive `applyPlugins` with a deps double whose installer always "succeeds" and whose
+ * `readInstalled` answers per case, and assert on the result and on what the reporter was
+ * told.
+ *
+ * `applyPlugins` runs in a CHILD process that starts with HOME, CLAUDE_CONFIG_DIR and XDG_*
+ * pointing at temp dirs (Bun's `os.homedir()` ignores a HOME changed at runtime), colours
+ * off, and a PATH holding only `bun` and `git` — so anything it might reach outside the
+ * injected deps cannot touch the real `~/.claude` or a real `claude` CLI. The deps double
+ * and the reporter live in the child, record every call, and the child writes the result,
+ * the `finish` records and the call log as JSON. The optional deps `loadedVersion`,
+ * `registryRows` and `inThisRepository` are left unset, as the spec requires.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+	mkdir,
+	mkdtemp,
+	readFile,
+	realpath,
+	rm,
+	symlink,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PluginApplyResult } from "../services/update-engine.js";
+import type { PluginUpdateItem } from "../services/update-plan.js";
+
+const SRC = join(import.meta.dir, "..");
+const MODULES = {
+	ansi: join(SRC, "cli", "ansi.ts"),
+	engine: join(SRC, "services", "update-engine.ts"),
+};
+
+const CHILD_TIMEOUT_MS = 45_000;
+const CHILD_TEST_TIMEOUT_MS = 60_000;
+
+/** The one item every REQ-11 case applies, exactly as the spec states it. */
+const ITEM: PluginUpdateItem = {
+	pluginId: "p@m",
+	pinned: "latest",
+	installed: "1.0.0",
+	loaded: null,
+	available: "2.0.0",
+	target: "2.0.0",
+	action: "update",
+	reason: "behind",
+	scopes: ["project"],
+	beforeVersions: { project: "1.0.0" },
+};
+
+/**
+ * What the double's `readInstalled` resolves, for every call:
+ * - `null`: always `null` — the installer exited 0 and recorded nothing (REQ-11a).
+ * - `moves`: `"1.0.0"` until `deps.update` or `deps.install` has been called, `"2.0.0"`
+ *   after — a real move (REQ-11b).
+ * - `stays`: always `"1.0.0"` — the installer left the old version (REQ-11c).
+ */
+type Readback = "null" | "moves" | "stays";
+
+const APPLY_CHILD = `
+import { readFileSync, writeFileSync } from "node:fs";
+
+const [readback, itemPath, project, resultPath] = process.argv.slice(2);
+const ansi = await import(${JSON.stringify(MODULES.ansi)});
+const engine = await import(${JSON.stringify(MODULES.engine)});
+
+if (typeof ansi.setColorEnabled === "function") ansi.setColorEnabled(false);
+for (const stream of [process.stdin, process.stdout, process.stderr]) {
+	Object.defineProperty(stream, "isTTY", { value: false, configurable: true });
+}
+
+const item = JSON.parse(readFileSync(itemPath, "utf8"));
+const calls = [];
+const begins = [];
+const finishes = [];
+let installerRan = false;
+
+const deps = {
+	install: async (pluginId, scope) => {
+		calls.push(["install", pluginId, scope]);
+		installerRan = true;
+	},
+	update: async (pluginId, scope) => {
+		calls.push(["update", pluginId, scope]);
+		installerRan = true;
+	},
+	repair: async (pluginId, scope, projectPath) => {
+		calls.push(["repair", pluginId, scope, projectPath]);
+	},
+	readInstalled: async (pluginId, scope, projectPath) => {
+		let version;
+		if (readback === "null") version = null;
+		else if (readback === "stays") version = "1.0.0";
+		else version = installerRan ? "2.0.0" : "1.0.0";
+		calls.push(["readInstalled", pluginId, scope, projectPath, version]);
+		return version;
+	},
+	saveInstalled: async (pluginId, version, scope, projectPath) => {
+		calls.push(["saveInstalled", pluginId, version, scope, projectPath]);
+	},
+	repairStaleLoad: async (pluginId, target, projectPath) => {
+		calls.push(["repairStaleLoad", pluginId, target, projectPath]);
+		return { pluginId, target, rewritten: 0, backup: null, loaded: target, ok: true };
+	},
+};
+
+const report = {
+	begin: (name) => {
+		begins.push(name);
+	},
+	finish: (ok, name, detail, ms) => {
+		finishes.push({ ok, name, detail, ms });
+	},
+	detach: async (work) => work(),
+};
+
+const out = { result: null, begins, finishes, calls, error: null };
+try {
+	out.result = await engine.applyPlugins([item], project, deps, report);
+} catch (e) {
+	out.error = e instanceof Error ? (e.stack ?? e.message) : String(e);
+}
+writeFileSync(resultPath, JSON.stringify(out));
+process.exit(0);
+`;
+
+interface FinishRecord {
+	ok: boolean;
+	name: string;
+	detail: string;
+	ms: number;
+}
+
+interface ApplyRun {
+	result: PluginApplyResult | null;
+	begins: string[];
+	finishes: FinishRecord[];
+	calls: unknown[][];
+	error: string | null;
+}
+
+const scratch: string[] = [];
+let helperDir = "";
+let binDir = "";
+
+async function tempRoot(prefix: string): Promise<string> {
+	const dir = await realpath(await mkdtemp(join(tmpdir(), prefix)));
+	scratch.push(dir);
+	return dir;
+}
+
+beforeAll(async () => {
+	helperDir = await tempRoot("unrb-helpers-");
+	binDir = join(helperDir, "bin");
+	await mkdir(binDir);
+	await symlink(process.execPath, join(binDir, "bun"));
+	const git = Bun.which("git");
+	if (git) await symlink(git, join(binDir, "git"));
+	await writeFile(join(helperDir, "apply-child.ts"), APPLY_CHILD);
+});
+
+afterAll(async () => {
+	for (const dir of scratch) await rm(dir, { recursive: true, force: true });
+});
+
+/**
+ * Apply ITEM in a child with the given read-back behaviour. `projectPath` is a fresh
+ * temp dir; HOME, CLAUDE_CONFIG_DIR (`<HOME>/.claude`) and XDG_* are temp dirs beside it.
+ */
+async function runApply(readback: Readback): Promise<ApplyRun> {
+	const base = await tempRoot("unrb-");
+	const home = join(base, "home");
+	const xdg = join(base, "xdg");
+	await mkdir(join(home, ".claude"), { recursive: true });
+	for (const kind of ["config", "cache", "data", "state"]) {
+		await mkdir(join(xdg, kind), { recursive: true });
+	}
+	const project = join(base, "proj");
+	await mkdir(project, { recursive: true });
+	const itemPath = join(base, "item.json");
+	await writeFile(itemPath, JSON.stringify(ITEM));
+	const resultPath = join(base, `result-${readback}.json`);
+	const env = {
+		PATH: `${binDir}:/usr/bin:/bin`,
+		HOME: home,
+		CLAUDE_CONFIG_DIR: join(home, ".claude"),
+		XDG_CONFIG_HOME: join(xdg, "config"),
+		XDG_CACHE_HOME: join(xdg, "cache"),
+		XDG_DATA_HOME: join(xdg, "data"),
+		XDG_STATE_HOME: join(xdg, "state"),
+		TMPDIR: tmpdir(),
+		NO_COLOR: "1",
+		TERM: "dumb",
+		GIT_CONFIG_NOSYSTEM: "1",
+		GIT_CONFIG_GLOBAL: "/dev/null",
+	};
+	const proc = Bun.spawn({
+		cmd: [
+			process.execPath,
+			"--no-env-file",
+			join(helperDir, "apply-child.ts"),
+			readback,
+			itemPath,
+			project,
+			resultPath,
+		],
+		cwd: project,
+		env,
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const timer = setTimeout(() => proc.kill(), CHILD_TIMEOUT_MS);
+	const [stdout, stderr, code] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	clearTimeout(timer);
+	let raw: string;
+	try {
+		raw = await readFile(resultPath, "utf8");
+	} catch {
+		throw new Error(
+			`apply child wrote no result (exit ${code}).\nstdout:\n${stdout}\nstderr:\n${stderr}`,
+		);
+	}
+	return JSON.parse(raw) as ApplyRun;
+}
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+/**
+ * Every `finish` detail reported for `pluginId`, colour codes stripped, joined by
+ * newlines. Fails the test when nothing was reported for it.
+ */
+function finishDetail(run: ApplyRun, pluginId: string): string {
+	const mine = run.finishes.filter((f) => f.name.includes(pluginId));
+	expect(mine.length).toBeGreaterThan(0);
+	return mine.map((f) => f.detail.replace(ANSI, "")).join("\n");
+}
+
+describe("REQ-11 an update that records no version is no change, never moved", () => {
+	test(
+		"REQ-11a when read-back resolves null after the installer exits 0, the item is unchanged, not counted, and not reported as 2.0.0",
+		async () => {
+			const run = await runApply("null");
+
+			expect(run.error).toBeNull();
+			expect(run.result).not.toBeNull();
+			expect(run.result?.ok).toBe(0);
+			expect(run.result?.unchanged).toContain("p@m");
+			expect(run.result?.failed).toEqual([]);
+			const detail = finishDetail(run, "p@m");
+			expect(detail).toContain("no change");
+			expect(detail).not.toContain("2.0.0");
+		},
+		CHILD_TEST_TIMEOUT_MS,
+	);
+
+	test(
+		"REQ-11b negative control: when read-back moves from 1.0.0 to 2.0.0 after the installer, the item counts as changed and reports 2.0.0",
+		async () => {
+			const run = await runApply("moves");
+
+			expect(run.error).toBeNull();
+			expect(run.result).not.toBeNull();
+			expect(run.result?.ok).toBe(1);
+			expect(run.result?.unchanged).toEqual([]);
+			const detail = finishDetail(run, "p@m");
+			expect(detail).toContain("2.0.0");
+		},
+		CHILD_TEST_TIMEOUT_MS,
+	);
+
+	test(
+		"REQ-11c when the installer leaves 1.0.0 in place, the item is unchanged, not counted, and reported as no change at 1.0.0",
+		async () => {
+			const run = await runApply("stays");
+
+			expect(run.error).toBeNull();
+			expect(run.result).not.toBeNull();
+			expect(run.result?.ok).toBe(0);
+			expect(run.result?.unchanged).toContain("p@m");
+			const detail = finishDetail(run, "p@m");
+			expect(detail).toContain("no change");
+			expect(detail).toContain("1.0.0");
+		},
+		CHILD_TEST_TIMEOUT_MS,
+	);
+});

package/src/__tests__/update-plan-parity.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Spec 7.5.4 v3 — REQ-7: the CLI and the Plugins screen plan updates with ONE list.
+ * REQ-10: a plugin whose files are missing is repaired in the scope where they are
+ * missing, never at project scope.
+ *
+ * Written blind: from the spec and the exported signatures and interfaces only.
+ * `planPluginUpdates` is what the CLI plans with and `classifyPluginRows` is what the
+ * Plugins screen classifies its rows with; for the same pins and catalog they must say
+ * the same thing about every plugin.
+ *
+ * Both are pure, so everything here runs in-process on hand-built `PluginInfo`s.
+ */
+import { describe, expect, test } from "bun:test";
+import type { PluginInfo, ScopeStatus } from "../services/plugin-manager.js";
+import {
+	type PluginUpdateItem,
+	classifyPluginRows,
+	planPluginUpdates,
+} from "../services/update-plan.js";
+
+interface Spec {
+	name: string;
+	/** What the marketplace offers. */
+	offered: string;
+	installedVersion?: string;
+	userScope?: ScopeStatus;
+	projectScope?: ScopeStatus;
+	localScope?: ScopeStatus;
+}
+
+function pluginInfo(spec: Spec): PluginInfo {
+	return {
+		id: `${spec.name}@magus`,
+		name: spec.name,
+		version: spec.offered,
+		description: "",
+		marketplace: "magus",
+		marketplaceDisplay: "magus",
+		installedVersion: spec.installedVersion,
+		userScope: spec.userScope,
+		projectScope: spec.projectScope,
+		localScope: spec.localScope,
+	};
+}
+
+const PINNED_INSTALLED = "alpha@magus";
+const PINNED_NOWHERE = "bravo@magus";
+const UNPINNED_USER_BEHIND = "charlie@magus";
+const UNPINNED_NOWHERE = "delta@magus";
+
+/**
+ * The REQ-7a mix, built fresh for every test so no call can see another's objects.
+ * Deliberately NOT in id order: the spec compares the plan against the classified rows
+ * sorted by `pluginId`, so an id-ordered catalog would hide the plan's own ordering.
+ */
+function mixedCatalog(): PluginInfo[] {
+	return [
+		// An UNPINNED plugin installed nowhere.
+		pluginInfo({
+			name: "delta",
+			offered: "4.0.0",
+			userScope: { installed: false },
+			projectScope: { installed: false },
+			localScope: { installed: false },
+		}),
+		// An UNPINNED plugin installed at USER scope only, behind the offered version.
+		pluginInfo({
+			name: "charlie",
+			offered: "3.1.0",
+			installedVersion: "3.0.0",
+			userScope: { installed: true, version: "3.0.0" },
+			projectScope: { installed: false },
+			localScope: { installed: false },
+		}),
+		// A pinned plugin installed at project scope.
+		pluginInfo({
+			name: "alpha",
+			offered: "2.0.0",
+			installedVersion: "2.0.0",
+			projectScope: { installed: true, version: "2.0.0" },
+		}),
+		// A pinned plugin installed nowhere.
+		pluginInfo({ name: "bravo", offered: "1.5.0" }),
+	];
+}
+
+function pins(): Record<string, string> {
+	return { [PINNED_INSTALLED]: "2.0.0", [PINNED_NOWHERE]: "latest" };
+}
+
+function byPluginId(a: PluginUpdateItem, b: PluginUpdateItem): number {
+	return a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0;
+}
+
+function planItem(
+	plan: PluginUpdateItem[],
+	pluginId: string,
+): PluginUpdateItem | undefined {
+	return plan.find((item) => item.pluginId === pluginId);
+}
+
+describe("REQ-7 one update list for the CLI and the Plugins screen", () => {
+	test("REQ-7a the Plugins screen's classified rows, sorted by pluginId, deep-equal the CLI's plan", () => {
+		const plugins = mixedCatalog();
+
+		const plan = planPluginUpdates(pins(), plugins);
+		const rows = [...classifyPluginRows(mixedCatalog(), pins()).values()].sort(
+			byPluginId,
+		);
+
+		// Not vacuous: two of the four plugins are required in the plan (REQ-7b, REQ-7d).
+		expect(plan.length).toBeGreaterThanOrEqual(2);
+		expect(rows).toEqual(plan);
+	});
+
+	test("REQ-7b the unpinned USER-scope plugin that is behind appears, with action update", () => {
+		const plan = planPluginUpdates(pins(), mixedCatalog());
+
+		const item = planItem(plan, UNPINNED_USER_BEHIND);
+
+		expect(item).toBeDefined();
+		expect(item?.action).toBe("update");
+	});
+
+	test("REQ-7c the unpinned plugin installed nowhere does not appear in the plan", () => {
+		const plan = planPluginUpdates(pins(), mixedCatalog());
+
+		expect(plan.map((item) => item.pluginId)).not.toContain(UNPINNED_NOWHERE);
+	});
+
+	test("REQ-7d the pinned plugin installed nowhere appears with action install", () => {
+		const plan = planPluginUpdates(pins(), mixedCatalog());
+
+		const item = planItem(plan, PINNED_NOWHERE);
+
+		expect(item).toBeDefined();
+		expect(item?.action).toBe("install");
+	});
+
+	test("REQ-7e the catalog as a Map keyed by id gives the same plan as the array", () => {
+		const asArray = planPluginUpdates(pins(), mixedCatalog());
+		const asMap = planPluginUpdates(
+			pins(),
+			new Map(mixedCatalog().map((plugin) => [plugin.id, plugin])),
+		);
+
+		expect(asArray.length).toBeGreaterThanOrEqual(2);
+		expect(asMap).toEqual(asArray);
+	});
+});
+
+describe("REQ-10 missing files are repaired where they are missing, never at project scope", () => {
+	test("REQ-10a an unpinned plugin installed at USER scope with no version is reinstalled at user: install / files-missing / [user]", () => {
+		const catalog = [
+			pluginInfo({
+				name: "echo",
+				offered: "1.2.0",
+				userScope: { installed: true },
+				projectScope: { installed: false },
+				localScope: { installed: false },
+			}),
+		];
+
+		const item = planItem(planPluginUpdates({}, catalog), "echo@magus");
+
+		expect(item).toBeDefined();
+		expect({
+			action: item?.action,
+			reason: item?.reason,
+			scopes: item?.scopes,
+		}).toEqual({
+			action: "install",
+			reason: "files-missing",
+			scopes: ["user"],
+		});
+	});
+
+	test("REQ-10b an unpinned plugin installed at LOCAL scope with no version is reinstalled at local: install / files-missing / [local]", () => {
+		const catalog = [
+			pluginInfo({
+				name: "foxtrot",
+				offered: "1.2.0",
+				userScope: { installed: false },
+				projectScope: { installed: false },
+				localScope: { installed: true },
+			}),
+		];
+
+		const item = planItem(planPluginUpdates({}, catalog), "foxtrot@magus");
+
+		expect(item).toBeDefined();
+		expect({
+			action: item?.action,
+			reason: item?.reason,
+			scopes: item?.scopes,
+		}).toEqual({
+			action: "install",
+			reason: "files-missing",
+			scopes: ["local"],
+		});
+	});
+
+	test("REQ-10c a pinned plugin installed nowhere is installed: install / absent", () => {
+		const catalog = [pluginInfo({ name: "golf", offered: "2.0.0" })];
+
+		const item = planItem(
+			planPluginUpdates({ "golf@magus": "latest" }, catalog),
+			"golf@magus",
+		);
+
+		expect(item).toBeDefined();
+		expect({ action: item?.action, reason: item?.reason }).toEqual({
+			action: "install",
+			reason: "absent",
+		});
+	});
+
+	/** Installed at USER 0.9.0, catalog 0.9.0, plus an inherited PROJECT row that is not turned on. */
+	function currentWithInheritedRow(): PluginInfo[] {
+		return [
+			pluginInfo({
+				name: "hotel",
+				offered: "0.9.0",
+				installedVersion: "0.9.0",
+				userScope: { installed: true, version: "0.9.0" },
+				projectScope: { installed: false, version: "0.8.1" },
+			}),
+		];
+	}
+
+	// The spec does not say whether this plugin is pinned, so both are checked: the
+	// not-installed scope's version must not change the answer either way.
+	const PIN_CASES: Array<[label: string, pins: Record<string, string>]> = [
+		["unpinned", {}],
+		["pinned to latest", { "hotel@magus": "latest" }],
+	];
+
+	for (const [label, pinSet] of PIN_CASES) {
+		test(`REQ-10d (${label}) a not-installed PROJECT row at 0.8.1 does not make a current USER install look behind: current`, () => {
+			const item = planItem(
+				planPluginUpdates(pinSet, currentWithInheritedRow()),
+				"hotel@magus",
+			);
+
+			expect(item).toBeDefined();
+			expect(item?.action).toBe("current");
+		});
+	}
+});