magus-cli 7.4.0 → 7.4.1

package/src/__tests__/blind/c20-registry-and-file-safety.test.ts

@@ -0,0 +1,560 @@
+/**
+ * Blind tests — contract C20 (requirements R2.8.7, R2.8.8).
+ *
+ * Written from requirements.md and architecture.md only.
+ *
+ * NOTHING under test runs in this process: both modules can resolve
+ * `~/.claude`, and under Bun a runtime HOME change does not move
+ * `os.homedir()` (architecture.md C2 correction). Every call therefore runs in
+ * a child `bun` spawned with a temp HOME (see ./child-run.ts). The child
+ * reports only booleans and class names — never a value read from a file and
+ * never an error message — so no failure can print a real user file. The files
+ * this test compares byte-for-byte are its own temp testdata.
+ *
+ * Two things C20 leaves open, and how they are handled here rather than guessed:
+ *
+ *  - `readInstalledPluginsRegistry(root)` / `writeInstalledPluginsRegistry(…, root, …)`
+ *    do not say where `root` points. Each case therefore seeds IDENTICAL bytes
+ *    at every plausible location (`<root>/installed_plugins.json`,
+ *    `<root>/plugins/…`, `<root>/.claude/plugins/…`), so the assertions hold
+ *    whichever one the contract means: a corrupt file is corrupt either way,
+ *    and `expectBytes` is the same string either way. Byte-identity is checked
+ *    on all of them.
+ *  - C20 gives `applyTemplate(/* existing signature *\/)`. The call shape used
+ *    here — `applyTemplate(projectDir, templateId)` with the id "common-dev" —
+ *    is taken from the existing test `src/__tests__/gitignore-service.test.ts`
+ *    (a test file, the only source consulted besides the two documents). The
+ *    "healthy file still applies" case is the control that catches it if that
+ *    id ever stops being a real template.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { type ChildResult, runInChild } from "./child-run.js";
+
+const SETTINGS_MODULE = path.resolve(
+	import.meta.dir,
+	"../../services/claude-settings.ts",
+);
+const GITIGNORE_MODULE = path.resolve(
+	import.meta.dir,
+	"../../services/gitignore-service.ts",
+);
+/** Modules that may export the SettingsParseError class (C2, C13). */
+const CLASS_MODULES = [
+	SETTINGS_MODULE,
+	path.resolve(import.meta.dir, "../../services/settings-file.ts"),
+];
+
+const T = 30_000; // per-test timeout: each test spawns one child bun
+
+const dirs: string[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0))
+		rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(tag: string): string {
+	const dir = mkdtempSync(path.join(os.tmpdir(), `magus-blind-c20-${tag}-`));
+	dirs.push(dir);
+	return dir;
+}
+
+function write(file: string, content: string): void {
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, content);
+}
+
+/** Three distinct ways a file can exist and not be JSON. */
+const INVALID: Record<string, string> = {
+	truncated: '{\n  "version": 2,\n  "plugins": {\n',
+	"plain text": "this is not json at all\n",
+	"trailing comma": '{ "version": 2, "plugins": { }, }\n',
+};
+
+/** Three ways a file can parse and not be a JSON object (R2.8.1). */
+const NOT_AN_OBJECT: Record<string, string> = {
+	"an array": "[]\n",
+	null: "null\n",
+	"a number": "5\n",
+};
+
+/**
+ * Child body: call `mod[job.call](...job.args)` and report a summary.
+ * On success, reports only whether the value is an object — never the value.
+ * On a throw, reports the error's class and whether it names one of
+ * `job.files` — never its message.
+ */
+const CALL_BODY = `
+const fs = await import("node:fs");
+const nodePath = await import("node:path");
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+
+const ctors = [];
+for (const m of (job.classModules || [])) {
+	try {
+		const mm = await import(m);
+		if (typeof mm.SettingsParseError === "function") ctors.push(mm.SettingsParseError);
+	} catch {}
+}
+if (mod && typeof mod.SettingsParseError === "function") ctors.push(mod.SettingsParseError);
+/** A subclass counts: walk the constructor chain by name as well as instanceof. */
+const namedChain = (e) => {
+	let c = e && e.constructor;
+	while (typeof c === "function") {
+		if (c.name === "SettingsParseError") return true;
+		c = Object.getPrototypeOf(c);
+	}
+	return false;
+};
+
+try {
+	const value = await mod[job.call](...job.args);
+	await out({
+		stage: "done",
+		ok: true,
+		isObject: value !== null && typeof value === "object" && !Array.isArray(value),
+	});
+} catch (e) {
+	const isErr = e instanceof Error;
+	const msg = isErr && typeof e.message === "string" ? e.message : "";
+	const p = e && typeof e.path === "string" ? e.path : null;
+	const files = job.files || [];
+	const names = (f) => {
+		const r = real(f);
+		return msg.includes(f) || (!!r && msg.includes(r)) || msg.includes(nodePath.basename(f));
+	};
+	await out({
+		stage: "done",
+		ok: false,
+		isError: isErr,
+		name: isErr ? e.name : typeof e,
+		isSettingsParseError: ctors.some((C) => e instanceof C) || namedChain(e),
+		pathMatchesAFile: p !== null && files.some((f) => { const r = real(f); return !!r && real(p) === r; }),
+		messageNamesFile: files.length > 0 && files.some(names),
+	});
+}
+`;
+
+interface CallOpts {
+	files?: string[];
+}
+
+function callIn(
+	home: string,
+	cwd: string,
+	module: string,
+	fn: string,
+	args: unknown[],
+	opts: CallOpts = {},
+): ChildResult {
+	return runInChild({
+		home,
+		cwd,
+		module,
+		job: {
+			call: fn,
+			args,
+			classModules: CLASS_MODULES,
+			files: opts.files ?? [],
+		},
+		body: CALL_BODY,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// installed_plugins.json  (R2.8.8)
+// ---------------------------------------------------------------------------
+
+interface RegistryCase {
+	home: string;
+	cwd: string;
+	root: string;
+	/** Every plausible location of installed_plugins.json under `root`. */
+	files: string[];
+}
+
+function newRegistryCase(): RegistryCase {
+	const root = tempDir("root");
+	return {
+		home: tempDir("home"),
+		cwd: tempDir("cwd"),
+		root,
+		files: [
+			path.join(root, "installed_plugins.json"),
+			path.join(root, "plugins", "installed_plugins.json"),
+			path.join(root, ".claude", "plugins", "installed_plugins.json"),
+		],
+	};
+}
+
+/** Seed identical bytes at every candidate location. */
+function seedRegistry(c: RegistryCase, content: string): void {
+	for (const f of c.files) write(f, content);
+}
+
+/** Snapshot the bytes of every candidate that exists. */
+function snapshot(files: string[]): Map<string, Buffer> {
+	const m = new Map<string, Buffer>();
+	for (const f of files) if (existsSync(f)) m.set(f, readFileSync(f));
+	return m;
+}
+
+function expectUnchanged(before: Map<string, Buffer>): void {
+	expect(before.size).toBeGreaterThan(0);
+	for (const [f, bytes] of before) {
+		expect(existsSync(f)).toBe(true);
+		expect(readFileSync(f).equals(bytes)).toBe(true);
+	}
+}
+
+const healthyRegistry = () =>
+	JSON.stringify({ version: 2, plugins: {} }, null, 2);
+
+describe("C20 — readInstalledPluginsRegistry", () => {
+	test(
+		"R2.8.8 a missing installed_plugins.json reads without throwing (unchanged behaviour)",
+		() => {
+			const c = newRegistryCase();
+			expect(
+				callIn(c.home, c.cwd, SETTINGS_MODULE, "readInstalledPluginsRegistry", [
+					c.root,
+				]),
+			).toMatchObject({ stage: "done", ok: true, isObject: true });
+		},
+		T,
+	);
+
+	test(
+		"R2.8.8 control: a healthy installed_plugins.json reads without throwing (unchanged behaviour)",
+		() => {
+			const c = newRegistryCase();
+			seedRegistry(c, healthyRegistry());
+			expect(
+				callIn(c.home, c.cwd, SETTINGS_MODULE, "readInstalledPluginsRegistry", [
+					c.root,
+				]),
+			).toMatchObject({ stage: "done", ok: true, isObject: true });
+		},
+		T,
+	);
+
+	for (const [kind, content] of Object.entries(INVALID)) {
+		test(
+			`R2.8.8 an installed_plugins.json that does not parse (${kind}) is refused, names the file, and stays byte-identical`,
+			() => {
+				const c = newRegistryCase();
+				seedRegistry(c, content);
+				const before = snapshot(c.files);
+				const r = callIn(
+					c.home,
+					c.cwd,
+					SETTINGS_MODULE,
+					"readInstalledPluginsRegistry",
+					[c.root],
+					{ files: c.files },
+				);
+				expect(r).toMatchObject({
+					stage: "done",
+					ok: false,
+					isError: true,
+					isSettingsParseError: true,
+					messageNamesFile: true,
+				});
+				expectUnchanged(before);
+			},
+			T,
+		);
+	}
+
+	for (const [kind, content] of Object.entries(NOT_AN_OBJECT)) {
+		test(
+			`R2.8.8 an installed_plugins.json that parses to ${kind} is refused, names the file, and stays byte-identical`,
+			() => {
+				const c = newRegistryCase();
+				seedRegistry(c, content);
+				const before = snapshot(c.files);
+				const r = callIn(
+					c.home,
+					c.cwd,
+					SETTINGS_MODULE,
+					"readInstalledPluginsRegistry",
+					[c.root],
+					{ files: c.files },
+				);
+				expect(r).toMatchObject({
+					stage: "done",
+					ok: false,
+					isError: true,
+					isSettingsParseError: true,
+					messageNamesFile: true,
+				});
+				expectUnchanged(before);
+			},
+			T,
+		);
+	}
+
+	test(
+		"R2.8.8 a corrupt registry never reads as an empty registry",
+		() => {
+			const c = newRegistryCase();
+			seedRegistry(c, INVALID["plain text"] as string);
+			const r = callIn(
+				c.home,
+				c.cwd,
+				SETTINGS_MODULE,
+				"readInstalledPluginsRegistry",
+				[c.root],
+			);
+			expect(r.stage).toBe("done");
+			expect(r.ok).toBe(false);
+		},
+		T,
+	);
+});
+
+describe("C20 — writeInstalledPluginsRegistry", () => {
+	const TOKEN = () => `blind-${randomUUID()}@magus`;
+
+	test(
+		"R2.8.8 control: with expectBytes equal to the bytes on disk the write succeeds and lands",
+		() => {
+			const c = newRegistryCase();
+			seedRegistry(c, healthyRegistry());
+			const current = healthyRegistry();
+			const id = TOKEN();
+			const r = callIn(
+				c.home,
+				c.cwd,
+				SETTINGS_MODULE,
+				"writeInstalledPluginsRegistry",
+				[{ version: 2, plugins: { [id]: [] } }, c.root, current],
+			);
+			expect(r).toMatchObject({ stage: "done", ok: true });
+			// The file is this test's own temp testdata, so reading it here is safe.
+			const landed = c.files
+				.filter((f) => existsSync(f))
+				.some((f) => {
+					const parsed = JSON.parse(readFileSync(f, "utf8"));
+					return (
+						parsed !== null &&
+						typeof parsed === "object" &&
+						Object.keys(parsed.plugins ?? {}).includes(id)
+					);
+				});
+			expect(landed).toBe(true);
+		},
+		T,
+	);
+
+	test(
+		"R2.8.8 a write whose expectBytes no longer match the file is refused and leaves it byte-identical",
+		() => {
+			const c = newRegistryCase();
+			// Read … then someone else rewrites the file … then we write.
+			const asRead = healthyRegistry();
+			seedRegistry(c, asRead);
+			const concurrent = JSON.stringify(
+				{ version: 2, plugins: {}, note: "written by someone else" },
+				null,
+				2,
+			);
+			seedRegistry(c, concurrent);
+			const before = snapshot(c.files);
+
+			const r = callIn(
+				c.home,
+				c.cwd,
+				SETTINGS_MODULE,
+				"writeInstalledPluginsRegistry",
+				[{ version: 2, plugins: { [TOKEN()]: [] } }, c.root, asRead],
+				{ files: c.files },
+			);
+			expect(r).toMatchObject({ stage: "done", ok: false, isError: true });
+			expectUnchanged(before);
+		},
+		T,
+	);
+
+	for (const [kind, content] of Object.entries(INVALID)) {
+		test(
+			`R2.8.8 a write is refused when the registry on disk does not parse (${kind}), even with matching expectBytes, and leaves it byte-identical`,
+			() => {
+				const c = newRegistryCase();
+				seedRegistry(c, content);
+				const before = snapshot(c.files);
+				const r = callIn(
+					c.home,
+					c.cwd,
+					SETTINGS_MODULE,
+					"writeInstalledPluginsRegistry",
+					[{ version: 2, plugins: { [TOKEN()]: [] } }, c.root, content],
+					{ files: c.files },
+				);
+				expect(r).toMatchObject({ stage: "done", ok: false, isError: true });
+				// Never replaced by a fresh file holding only the plugin being written.
+				expectUnchanged(before);
+			},
+			T,
+		);
+	}
+
+	test(
+		"R2.8.8 a write against a corrupt registry is refused when no expectBytes is passed at all",
+		() => {
+			const c = newRegistryCase();
+			seedRegistry(c, INVALID.truncated as string);
+			const before = snapshot(c.files);
+			const r = callIn(
+				c.home,
+				c.cwd,
+				SETTINGS_MODULE,
+				"writeInstalledPluginsRegistry",
+				[{ version: 2, plugins: { [TOKEN()]: [] } }, c.root],
+				{ files: c.files },
+			);
+			expect(r).toMatchObject({ stage: "done", ok: false, isError: true });
+			expectUnchanged(before);
+		},
+		T,
+	);
+
+	for (const [kind, content] of Object.entries(NOT_AN_OBJECT)) {
+		test(
+			`R2.8.8 a write is refused when the registry on disk parses to ${kind}, and leaves it byte-identical`,
+			() => {
+				const c = newRegistryCase();
+				seedRegistry(c, content);
+				const before = snapshot(c.files);
+				const r = callIn(
+					c.home,
+					c.cwd,
+					SETTINGS_MODULE,
+					"writeInstalledPluginsRegistry",
+					[{ version: 2, plugins: { [TOKEN()]: [] } }, c.root, content],
+					{ files: c.files },
+				);
+				expect(r).toMatchObject({ stage: "done", ok: false, isError: true });
+				expectUnchanged(before);
+			},
+			T,
+		);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// .claude/gitignore.json  (R2.8.7)
+// ---------------------------------------------------------------------------
+
+/**
+ * A template id the Gitignore tab offers. C20 does not name one; this is taken
+ * from the existing test `src/__tests__/gitignore-service.test.ts`. The control
+ * below fails loudly if it stops being a real template.
+ */
+const TEMPLATE = "common-dev";
+
+interface TemplateCase {
+	home: string;
+	project: string;
+	file: string;
+}
+
+function newTemplateCase(): TemplateCase {
+	const project = tempDir("proj");
+	mkdirSync(path.join(project, ".claude"), { recursive: true });
+	return {
+		home: tempDir("home"),
+		project,
+		file: path.join(project, ".claude", "gitignore.json"),
+	};
+}
+
+describe("C20 — applyTemplate refuses a damaged .claude/gitignore.json", () => {
+	test(
+		"R2.8.7 control: a healthy .claude/gitignore.json still applies",
+		() => {
+			const c = newTemplateCase();
+			const own = `blind-${randomUUID()}/`;
+			write(c.file, JSON.stringify({ ignore: [own], track: [] }, null, 2));
+			const r = callIn(c.home, c.project, GITIGNORE_MODULE, "applyTemplate", [
+				c.project,
+				TEMPLATE,
+			]);
+			expect(r).toMatchObject({ stage: "done", ok: true });
+			// The file is this test's own temp testdata, so reading it here is safe.
+			const after = JSON.parse(readFileSync(c.file, "utf8"));
+			expect(after !== null && typeof after === "object").toBe(true);
+			// R2.8.7's whole point: the user's own rules survive an apply.
+			expect(after.ignore).toContain(own);
+		},
+		T,
+	);
+
+	for (const [kind, content] of Object.entries(INVALID)) {
+		test(
+			`R2.8.7 a .claude/gitignore.json that does not parse (${kind}) is refused, names the file, and stays byte-identical`,
+			() => {
+				const c = newTemplateCase();
+				write(c.file, content);
+				const before = readFileSync(c.file);
+				const r = callIn(
+					c.home,
+					c.project,
+					GITIGNORE_MODULE,
+					"applyTemplate",
+					[c.project, TEMPLATE],
+					{ files: [c.file] },
+				);
+				expect(r).toMatchObject({
+					stage: "done",
+					ok: false,
+					isError: true,
+					isSettingsParseError: true,
+					messageNamesFile: true,
+				});
+				// Never read as "no entries" and rewritten — that drops the user's
+				// own ignore rules, which is how a secret later reaches a commit.
+				expect(readFileSync(c.file).equals(before)).toBe(true);
+			},
+			T,
+		);
+	}
+
+	for (const [kind, content] of Object.entries(NOT_AN_OBJECT)) {
+		test(
+			`R2.8.7 a .claude/gitignore.json that parses to ${kind} is refused, names the file, and stays byte-identical`,
+			() => {
+				const c = newTemplateCase();
+				write(c.file, content);
+				const before = readFileSync(c.file);
+				const r = callIn(
+					c.home,
+					c.project,
+					GITIGNORE_MODULE,
+					"applyTemplate",
+					[c.project, TEMPLATE],
+					{ files: [c.file] },
+				);
+				expect(r).toMatchObject({
+					stage: "done",
+					ok: false,
+					isError: true,
+					isSettingsParseError: true,
+					messageNamesFile: true,
+				});
+				expect(readFileSync(c.file).equals(before)).toBe(true);
+			},
+			T,
+		);
+	}
+});

package/src/__tests__/stale-load-repair.test.ts

@@ -344,10 +344,11 @@ describe("repairStaleLoad — refusals", () => {
 	});
 
 	test("an unreadable registry is refused rather than replaced", async () => {
-		// `readInstalledPluginsRegistry` answers an EMPTY registry for a corrupt
-		// file, and writing that back would erase every project's installs on the
-		// machine. The repair reads and parses the same bytes it will check before
-		// writing, so a document it cannot parse stops it here.
+		// Writing over a corrupt registry would erase every project's installs on
+		// the machine. The repair reads and parses the same bytes it will check
+		// before writing, so a document it cannot parse stops it here — and it
+		// reports that as a result rather than throwing, because one item in a
+		// plan of repairs must not end the plan.
 		await fs.outputFile(registryFile, "{ not json");
 
 		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);

package/src/cli/doctor.ts

@@ -11,10 +11,10 @@
  *   5. Plugin loads — what Claude Code will load here vs what is installed.
  *
  * A file that exists and does not parse — the global settings, the project's
- * `.claude/profiles.json` or its `.claude/settings.json` — is a finding in the
- * section that meets it, never an abort: the rest of the report is still worth
- * having. `--fix` repairs none of them, because magus never rewrites a file it
- * cannot parse.
+ * `.claude/profiles.json` or its `.claude/settings.json`, Claude Code's
+ * `installed_plugins.json` — is a finding in the section that meets it, never an
+ * abort: the rest of the report is still worth having. `--fix` repairs none of
+ * them, because magus never rewrites a file it cannot parse.
  */
 
 import path from "node:path";
@@ -44,7 +44,11 @@ import {
 } from "../services/plugin-resolution.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
-import type { ClaudeSettings, ProfileManifest } from "../types/index.js";
+import type {
+	ClaudeSettings,
+	InstalledPluginsRegistry,
+	ProfileManifest,
+} from "../types/index.js";
 import { resolveExecutable } from "../utils/command-utils.js";
 
 export async function runDoctorCommand(args: string[]): Promise<number> {
@@ -232,7 +236,17 @@ export function doctorExitCode(args: {
  *   loads     — the loader's, `pickLoadedEntry`
  */
 async function checkPluginLoads(projectPath: string): Promise<number> {
-	const registry = await readInstalledPluginsRegistry();
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = await readInstalledPluginsRegistry();
+	} catch (error) {
+		// A registry nothing can read is a finding, not an abort: doctor is the
+		// command someone runs BECAUSE something is wrong, and it has to reach its
+		// remaining sections and its exit code.
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Plugin loads", error);
+		return 1;
+	}
 	let settings: ClaudeSettings;
 	try {
 		settings = await readSettings(projectPath);

package/src/cli/install.ts

@@ -32,7 +32,7 @@ import { reportDisplaced } from "../services/profile-activate.js";
 import { materializeProfile } from "../services/profile-materializer.js";
 import { detectProfileDrift } from "../services/profile-sync.js";
 import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
-import { writableMap } from "../services/settings-file.js";
+import { SettingsParseError, writableMap } from "../services/settings-file.js";
 import { installSkill } from "../services/skills-manager.js";
 import {
 	PROFILE_GITIGNORE_ENTRIES,
@@ -230,17 +230,42 @@ async function collectEnv(
 		return;
 	}
 
-	const local = await readLocalSettings(projectPath);
-	// Checked before the first prompt, so a malformed `env` is refused before the
-	// user types anything, not after — and never replaced.
-	const env =
-		writableMap(local, "env", getLocalSettingsPath(projectPath)) ?? {};
-	local.env = env;
+	// EVERY answer first, then one read-modify-write.
+	//
+	// The read has to happen AFTER the last prompt. Claude Code writes
+	// settings.local.json while these prompts are on screen — it is where a
+	// "don't ask again" permission rule lands — and this used to read the file
+	// before the first question and write that copy back at the end, so every
+	// rule the user granted in between was erased. The prompts are the slow part,
+	// and a read from before them describes a file that no longer exists.
+	const answers: Array<[string, string]> = [];
 	for (const name of status.missingRequired) {
 		const value = await promptValue(`  ${name} = `);
-		if (value) env[name] = value;
+		if (value) answers.push([name, value]);
+	}
+
+	const localPath = getLocalSettingsPath(projectPath);
+	try {
+		// Refuses a file that stopped parsing while the prompts were up, and a
+		// malformed `env` map, before anything is written. Either way the file is
+		// left exactly as it is.
+		const local = await readLocalSettings(projectPath);
+		const env = writableMap(local, "env", localPath) ?? {};
+		local.env = env;
+		for (const [name, value] of answers) env[name] = value;
+		await writeLocalSettings(local, projectPath);
+	} catch (error) {
+		// Which variables went unsaved, by NAME — never the values. They are
+		// tokens, and a refusal is not a reason to print one to a terminal.
+		if (error instanceof SettingsParseError && answers.length > 0) {
+			console.error(
+				`Not saved: ${answers
+					.map(([name]) => name)
+					.join(", ")} — set them again once the file is fixed.`,
+			);
+		}
+		throw error;
 	}
-	await writeLocalSettings(local, projectPath);
 	console.log("Saved to .claude/settings.local.json (personal, gitignored).");
 }