magus-cli 7.3.1 → 7.4.1

package/src/__tests__/blind/c18-hook-shape.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Blind tests — contract C18 (requirement R2.8.6), with C2 / C13 for the
+ * SettingsParseError class.
+ *
+ * Written from requirements.md and architecture.md only.
+ *
+ * R2.8.6: registering the agent-model hook refuses a user settings file whose
+ * `hooks` is present but not a JSON object, or whose `hooks.PreToolUse` is
+ * present but not an array — with a `SettingsParseError`-class error naming
+ * the file — and leaves it byte-identical. It never replaces them with empty
+ * ones (the user's own hooks live there). Well-shaped `hooks` keep every
+ * existing entry and gain the magus one.
+ *
+ * C18: `registerAgentModelHook({ configDir })` writes `<configDir>/settings.json`
+ * and resolves "registered" | "already". It adds
+ * `{ matcher: "Agent", hooks: [{ type: "command", command: AGENT_MODEL_HOOK_COMMAND, … }] }`
+ * under `hooks.PreToolUse`. AGENT_MODEL_HOOK_COMMAND is "magus hook agent-model".
+ *
+ * Isolation: the function's default target is user scope (under HOME), and a
+ * black-box test cannot rule out a fallback to it despite `configDir`. So every
+ * call runs in a child `bun` with a temp HOME and a temp cwd (architecture.md
+ * C2 correction; see ./child-run.ts), and one control checks that nothing
+ * appears under that HOME. The child reports booleans, class names and the
+ * contract's own return value — never an error message or a value read from a
+ * file. The settings files read back here are this test's own temp testdata.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	existsSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { type ChildResult, runInChild } from "./child-run.js";
+
+const SERVICES = path.resolve(import.meta.dir, "../../services");
+const HOOK_REGISTRATION = path.join(SERVICES, "hook-registration.ts");
+const SETTINGS_FILE = path.join(SERVICES, "settings-file.ts");
+const CLAUDE_SETTINGS = path.join(SERVICES, "claude-settings.ts");
+const T = 30_000; // per-test timeout: each child bun spawn gets up to 25s
+
+const AGENT_MODEL_HOOK_COMMAND = "magus hook agent-model";
+
+const dirs: string[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0))
+		rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(tag: string): string {
+	// realpath: on macOS tmpdir is /var/… → /private/var/…; one spelling only.
+	const dir = realpathSync(
+		mkdtempSync(path.join(os.tmpdir(), `magus-blind-c18-${tag}-`)),
+	);
+	dirs.push(dir);
+	return dir;
+}
+
+interface Case {
+	home: string;
+	cwd: string;
+	configDir: string;
+	/** <configDir>/settings.json — the only file the call may touch. */
+	file: string;
+}
+
+/** A fresh temp HOME, cwd and configDir; `content` null means no settings.json. */
+function newCase(content: string | null): Case {
+	const home = tempDir("home");
+	const cwd = tempDir("cwd");
+	const configDir = tempDir("cfg");
+	const file = path.join(configDir, "settings.json");
+	if (content !== null) writeFileSync(file, content);
+	return { home, cwd, configDir, file };
+}
+
+// ── the child call ──────────────────────────────────────────────────────────
+
+/**
+ * Child body: `await mod.registerAgentModelHook({ configDir: job.configDir })`.
+ * Success → `{ ok: true, result }`, where `result` is reported only when it is
+ * one of the contract's two strings. Failure → whether the error is a
+ * SettingsParseError (by name, by a constructor named SettingsParseError on
+ * its prototype chain — i.e. a subclass — or by instanceof an exported
+ * class), and whether its message names the settings file. The message itself
+ * is never reported.
+ */
+const REGISTER_BODY = `
+const fs = await import("node:fs");
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+const classes = [];
+for (const m of job.errorModules || []) {
+	try {
+		const x = await import(m);
+		if (typeof x.SettingsParseError === "function") classes.push(x.SettingsParseError);
+	} catch {}
+}
+const k = mod.AGENT_MODEL_HOOK_COMMAND;
+const commandConst = typeof k === "string" && k.length < 200 ? k : "<" + typeof k + ">";
+if (typeof mod.registerAgentModelHook !== "function") {
+	await out({ stage: "missing-export", commandConst });
+	return;
+}
+try {
+	const r = await mod.registerAgentModelHook({ configDir: job.configDir });
+	await out({
+		stage: "done",
+		ok: true,
+		result: r === "registered" || r === "already" ? r : "<" + typeof r + ">",
+		commandConst,
+	});
+} catch (e) {
+	const isErr = e instanceof Error;
+	const chain = [];
+	for (let p = e !== null && typeof e === "object" ? Object.getPrototypeOf(e) : null; p; p = Object.getPrototypeOf(p)) {
+		const c = Object.prototype.hasOwnProperty.call(p, "constructor") ? p.constructor : null;
+		if (c && typeof c.name === "string") chain.push(c.name);
+	}
+	const msg = isErr && typeof e.message === "string" ? e.message : "";
+	const want = real(job.file);
+	await out({
+		stage: "done",
+		ok: false,
+		isError: isErr,
+		errorName: isErr ? String(e.name) : typeof e,
+		nameIsSettingsParseError: isErr && e.name === "SettingsParseError",
+		chainHasSettingsParseError: chain.includes("SettingsParseError"),
+		instanceOfSettingsParseError: classes.some((C) => e instanceof C),
+		messageNamesFile: msg.includes(job.file) || (!!want && msg.includes(want)),
+		commandConst,
+	});
+}
+`;
+
+function register(c: Case): ChildResult {
+	return runInChild({
+		home: c.home,
+		cwd: c.cwd,
+		module: HOOK_REGISTRATION,
+		job: {
+			configDir: c.configDir,
+			file: c.file,
+			errorModules: [SETTINGS_FILE, CLAUDE_SETTINGS, HOOK_REGISTRATION],
+		},
+		body: REGISTER_BODY,
+	});
+}
+
+/** The refusal R2.8.6 asks for, reduced to what the tests assert on. */
+function refusal(r: ChildResult) {
+	return {
+		stage: r.stage,
+		ok: r.ok,
+		settingsParseError:
+			r.nameIsSettingsParseError === true ||
+			r.chainHasSettingsParseError === true ||
+			r.instanceOfSettingsParseError === true,
+		messageNamesFile: r.messageNamesFile,
+		// Diagnostic only (e.g. a raw TypeError, R2.8.4). Not asserted.
+		errorName: r.errorName,
+		result: r.result,
+	};
+}
+
+// ── wrong shapes: refused ───────────────────────────────────────────────────
+
+const USER_BASH_BLOCK = {
+	matcher: "Bash",
+	hooks: [{ type: "command", command: "my-guard.sh" }],
+};
+
+/** R2.8.6: `hooks` not an object, or `hooks.PreToolUse` not an array. */
+const WRONG_SHAPES: Record<string, string> = {
+	'hooks is an array {"hooks": []}': '{"hooks": []}\n',
+	'hooks is a string {"hooks": "x"}': '{"hooks": "x"}\n',
+	'hooks is a number {"hooks": 5}': '{"hooks": 5}\n',
+	"hooks.PreToolUse is one block object, not an array": `${JSON.stringify({
+		hooks: { PreToolUse: USER_BASH_BLOCK },
+	})}\n`,
+	'hooks.PreToolUse is a string {"hooks": {"PreToolUse": "x"}}':
+		'{"hooks": {"PreToolUse": "x"}}\n',
+};
+
+describe("C18 — registerAgentModelHook refuses a wrong-shape hooks in <configDir>/settings.json", () => {
+	for (const [shape, content] of Object.entries(WRONG_SHAPES)) {
+		test(
+			`R2.8.6 ${shape}: rejects with a SettingsParseError-class error and never resolves`,
+			() => {
+				const c = newCase(content);
+				expect(refusal(register(c))).toMatchObject({
+					stage: "done",
+					ok: false,
+					settingsParseError: true,
+				});
+			},
+			T,
+		);
+
+		test(
+			`R2.8.6 ${shape}: the error message names <configDir>/settings.json`,
+			() => {
+				const c = newCase(content);
+				expect(refusal(register(c))).toMatchObject({
+					stage: "done",
+					ok: false,
+					messageNamesFile: true,
+				});
+			},
+			T,
+		);
+
+		test(
+			`R2.8.6 ${shape}: settings.json stays byte-identical`,
+			() => {
+				const c = newCase(content);
+				const before = readFileSync(c.file);
+				const r = register(c);
+				expect(r.stage).toBe("done");
+				expect(readFileSync(c.file).equals(before)).toBe(true);
+			},
+			T,
+		);
+	}
+});
+
+// ── controls: absent or well-shaped hooks gain the magus Agent block ────────
+
+const CONTROLS: Record<string, string | null> = {
+	"no settings.json": null,
+	"{}": "{}\n",
+	'{"hooks": {}}': '{"hooks": {}}\n',
+	"a user Bash hook in PreToolUse and other: 1": `${JSON.stringify({
+		hooks: { PreToolUse: [USER_BASH_BLOCK] },
+		other: 1,
+	})}\n`,
+};
+
+function readBack(c: Case): Record<string, unknown> {
+	// This test's own temp testdata — safe to read.
+	return JSON.parse(readFileSync(c.file, "utf8")) as Record<string, unknown>;
+}
+
+function preToolUse(settings: Record<string, unknown>): unknown[] | null {
+	const hooks = settings.hooks as Record<string, unknown> | undefined;
+	const pre = hooks?.PreToolUse;
+	return Array.isArray(pre) ? pre : null;
+}
+
+/** Every hook entry of type "command" running the magus command in an Agent block. */
+function magusAgentHooks(settings: Record<string, unknown>): unknown[] {
+	const found: unknown[] = [];
+	for (const block of preToolUse(settings) ?? []) {
+		const b = block as { matcher?: unknown; hooks?: unknown };
+		if (b?.matcher !== "Agent" || !Array.isArray(b.hooks)) continue;
+		for (const h of b.hooks as { type?: unknown; command?: unknown }[]) {
+			if (h?.type === "command" && h.command === AGENT_MODEL_HOOK_COMMAND)
+				found.push(h);
+		}
+	}
+	return found;
+}
+
+describe("C18 — registerAgentModelHook controls (absent or well-shaped hooks)", () => {
+	test(
+		`R2.8.6 AGENT_MODEL_HOOK_COMMAND is "${AGENT_MODEL_HOOK_COMMAND}"`,
+		() => {
+			const c = newCase("{}\n");
+			expect(register(c).commandConst).toBe(AGENT_MODEL_HOOK_COMMAND);
+		},
+		T,
+	);
+
+	for (const [label, content] of Object.entries(CONTROLS)) {
+		test(
+			`R2.8.6 control (${label}): resolves "registered"`,
+			() => {
+				const c = newCase(content);
+				expect(refusal(register(c))).toMatchObject({
+					stage: "done",
+					ok: true,
+					result: "registered",
+				});
+			},
+			T,
+		);
+
+		test(
+			`R2.8.6 control (${label}): hooks.PreToolUse gains one Agent block running "${AGENT_MODEL_HOOK_COMMAND}"`,
+			() => {
+				const c = newCase(content);
+				expect(register(c)).toMatchObject({ stage: "done", ok: true });
+				const after = readBack(c);
+				expect(Array.isArray(preToolUse(after))).toBe(true);
+				expect(magusAgentHooks(after).length).toBe(1);
+			},
+			T,
+		);
+
+		test(
+			`R2.8.6 control (${label}): a second call resolves "already" and leaves settings.json byte-identical`,
+			() => {
+				const c = newCase(content);
+				expect(register(c)).toMatchObject({
+					stage: "done",
+					ok: true,
+					result: "registered",
+				});
+				const afterFirst = readFileSync(c.file);
+				// A fresh process: "already" must come from the file, not memory.
+				expect(refusal(register(c))).toMatchObject({
+					stage: "done",
+					ok: true,
+					result: "already",
+				});
+				expect(readFileSync(c.file).equals(afterFirst)).toBe(true);
+			},
+			2 * T,
+		);
+	}
+
+	test(
+		"R2.8.6 control (a user Bash hook in PreToolUse and other: 1): the user's my-guard.sh block and other: 1 are kept",
+		() => {
+			const c = newCase(
+				CONTROLS["a user Bash hook in PreToolUse and other: 1"] as string,
+			);
+			expect(register(c)).toMatchObject({ stage: "done", ok: true });
+			const after = readBack(c);
+			expect(after.other).toBe(1);
+			const pre = preToolUse(after) ?? [];
+			const bash = pre.filter(
+				(b) => (b as { matcher?: unknown })?.matcher === "Bash",
+			);
+			expect(bash).toEqual([USER_BASH_BLOCK]);
+			expect(magusAgentHooks(after).length).toBe(1);
+		},
+		T,
+	);
+
+	test(
+		"R2.8.6 control (no settings.json): configDir is the only target — nothing appears under HOME/.claude",
+		() => {
+			const c = newCase(null);
+			expect(register(c)).toMatchObject({ stage: "done", ok: true });
+			expect(existsSync(c.file)).toBe(true);
+			expect(existsSync(path.join(c.home, ".claude"))).toBe(false);
+		},
+		T,
+	);
+});

package/src/__tests__/blind/c19-paste-routing.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Blind tests — contract C19 (requirement R4.9).
+ *
+ * Written from requirements.md and architecture.md only. A terminal delivers a
+ * paste as ONE event, not as keys, and C19 routes that event through the same
+ * layer order as a keypress. The layers here are stubs that record every
+ * handlePaste() call and the exact text each one received, so "a lower layer
+ * never sees the text" and "the text is passed through unchanged" are observed
+ * directly rather than inferred.
+ */
+import { describe, expect, test } from "bun:test";
+
+const load = () => import("../../ui/input/key-dispatch.js");
+
+type LayerId = "system" | "modal" | "input" | "screen" | "scroll" | "global";
+
+const ORDER: LayerId[] = [
+	"system",
+	"modal",
+	"input",
+	"screen",
+	"scroll",
+	"global",
+];
+
+interface Recorder {
+	/** Layer ids in the order their handlePaste() was called. */
+	calls: LayerId[];
+	/** Every (layer, text) pair a handler actually received. */
+	seen: { id: LayerId; text: string }[];
+	layers: {
+		id: LayerId;
+		active: boolean;
+		handlePaste(text: string): boolean;
+	}[];
+}
+
+/** Build one paste layer per id. `consumes[id]` decides; absent means "never consumes". */
+function stack(
+	consumes: Partial<Record<LayerId, (text: string) => boolean>>,
+	active: Partial<Record<LayerId, boolean>> = {},
+	order: LayerId[] = ORDER,
+): Recorder {
+	const calls: LayerId[] = [];
+	const seen: { id: LayerId; text: string }[] = [];
+	const layers = order.map((id) => ({
+		id,
+		active: active[id] ?? true,
+		handlePaste(text: string): boolean {
+			calls.push(id);
+			seen.push({ id, text });
+			return consumes[id]?.(text) ?? false;
+		},
+	}));
+	return { calls, seen, layers };
+}
+
+const all = () => true;
+const TEXT = "pasted search term";
+
+describe("C19 — dispatchPaste: layer order", () => {
+	test("R4.9 a paste is offered to layers in LAYER_ORDER regardless of array order", async () => {
+		const { dispatchPaste, LAYER_ORDER } = await load();
+		expect([...LAYER_ORDER]).toEqual(ORDER);
+
+		const shuffled: LayerId[] = [
+			"global",
+			"screen",
+			"system",
+			"scroll",
+			"input",
+			"modal",
+		];
+		const r = stack({}, {}, shuffled);
+		expect(dispatchPaste(r.layers, TEXT)).toBeNull();
+		expect(r.calls).toEqual(ORDER);
+	});
+
+	test("R4.9 with every layer consuming in reversed array order, the topmost layer wins alone", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack(
+			{
+				system: all,
+				modal: all,
+				input: all,
+				screen: all,
+				scroll: all,
+				global: all,
+			},
+			{},
+			[...ORDER].reverse(),
+		);
+		expect(dispatchPaste(r.layers, TEXT)).toBe("system");
+		expect(r.calls).toEqual(["system"]);
+	});
+
+	for (const [i, consumer] of ORDER.entries()) {
+		test(`R4.9 when ${consumer} consumes, dispatchPaste returns "${consumer}" and no lower layer sees the text`, async () => {
+			const { dispatchPaste } = await load();
+			// Every layer from the consumer down would also consume — only order decides.
+			const consumes: Partial<Record<LayerId, (text: string) => boolean>> = {};
+			for (const id of ORDER.slice(i)) consumes[id] = all;
+			const r = stack(consumes);
+			expect(dispatchPaste(r.layers, TEXT)).toBe(consumer);
+			expect(r.calls).toEqual(ORDER.slice(0, i + 1));
+			expect(r.seen.map((s) => s.id)).toEqual(ORDER.slice(0, i + 1));
+		});
+	}
+
+	test("R4.9 inactive layers are skipped: their handlePaste() is never called", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack(
+			{ modal: all, input: all, global: all },
+			{ modal: false, input: false },
+		);
+		expect(dispatchPaste(r.layers, TEXT)).toBe("global");
+		expect(r.calls).toEqual(["system", "screen", "scroll", "global"]);
+	});
+
+	test("R4.9 an inactive consumer does not stop the paste: the next active consumer wins", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({ input: all, screen: all }, { input: false });
+		expect(dispatchPaste(r.layers, TEXT)).toBe("screen");
+		expect(r.calls).toEqual(["system", "modal", "screen"]);
+	});
+
+	test("R4.9 dispatchPaste returns null when no layer consumes, calling each active layer once", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({});
+		expect(dispatchPaste(r.layers, TEXT)).toBeNull();
+		expect(r.calls).toEqual(ORDER);
+	});
+
+	test("R4.9 missing layers are fine: a stack of only screen and global", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({ global: all }, {}, ["global", "screen"]);
+		expect(dispatchPaste(r.layers, TEXT)).toBe("global");
+		expect(r.calls).toEqual(["screen", "global"]);
+	});
+
+	test("R4.9 an empty layer list consumes nothing", async () => {
+		const { dispatchPaste } = await load();
+		expect(dispatchPaste([], TEXT)).toBeNull();
+	});
+});
+
+describe("C19 — dispatchPaste: a focused search box takes the paste", () => {
+	test("R4.9 a focused input consumes the paste and the screen below never sees the text", async () => {
+		const { dispatchPaste } = await load();
+		const typed: string[] = [];
+		const r = stack({
+			input: (text) => {
+				typed.push(text);
+				return true;
+			},
+			screen: all,
+			global: all,
+		});
+		expect(dispatchPaste(r.layers, TEXT)).toBe("input");
+		expect(typed).toEqual([TEXT]);
+		expect(r.calls).toEqual(["system", "modal", "input"]);
+		expect(r.seen.some((s) => s.id === "screen")).toBe(false);
+		expect(r.seen.some((s) => s.id === "global")).toBe(false);
+	});
+
+	test("R4.9 with no active input layer, the paste reaches the lower layers in order", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({ input: all }, { input: false });
+		expect(dispatchPaste(r.layers, TEXT)).toBeNull();
+		expect(r.calls).toEqual(["system", "modal", "screen", "scroll", "global"]);
+		expect(r.seen.every((s) => s.text === TEXT)).toBe(true);
+	});
+
+	test("R4.9 with no input layer in the stack at all, nothing consumes the paste", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({}, {}, ["system", "modal", "screen", "scroll", "global"]);
+		expect(dispatchPaste(r.layers, TEXT)).toBeNull();
+		expect(r.calls).toEqual(["system", "modal", "screen", "scroll", "global"]);
+	});
+
+	test("R4.9 a modal above the input takes the paste first", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({ modal: all, input: all });
+		expect(dispatchPaste(r.layers, TEXT)).toBe("modal");
+		expect(r.calls).toEqual(["system", "modal"]);
+	});
+});
+
+describe("C19 — dispatchPaste: empty text", () => {
+	test("R4.9 empty text consumes nothing and returns null", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({
+			system: all,
+			modal: all,
+			input: all,
+			screen: all,
+			scroll: all,
+			global: all,
+		});
+		expect(dispatchPaste(r.layers, "")).toBeNull();
+	});
+
+	test("R4.9 empty text calls no handler, not even a focused input", async () => {
+		const { dispatchPaste } = await load();
+		const r = stack({ input: all });
+		dispatchPaste(r.layers, "");
+		expect(r.calls).toEqual([]);
+		expect(r.seen).toEqual([]);
+	});
+});
+
+describe("C19 — dispatchPaste: the text passes through unchanged", () => {
+	const PAYLOADS: [string, string][] = [
+		["a plain term", "node_modules"],
+		["leading and trailing spaces", "  spaced term  "],
+		["a single newline", "first line\nsecond line"],
+		["a trailing newline", "term\n"],
+		["CRLF line endings", "one\r\ntwo\r\n"],
+		["several lines", "a\nb\nc\nd"],
+		["a tab", "left\tright"],
+		["unicode accents", "café naïve"],
+		["CJK", "日本語のテキスト"],
+		["emoji", "🚀 ship it 🎉"],
+		["combining marks", "égalité"],
+		["a path with spaces", "/tmp/some dir/file.json"],
+		["JSON-ish punctuation", '{"key": "value", "n": 1}'],
+		["a single space", " "],
+		["a lone newline", "\n"],
+	];
+
+	for (const [label, text] of PAYLOADS) {
+		test(`R4.9 ${label} reaches the consuming layer byte-for-byte`, async () => {
+			const { dispatchPaste } = await load();
+			const got: string[] = [];
+			const r = stack({
+				input: (t) => {
+					got.push(t);
+					return true;
+				},
+			});
+			expect(dispatchPaste(r.layers, text)).toBe("input");
+			expect(got).toEqual([text]);
+		});
+
+		test(`R4.9 ${label} reaches every layer it is offered to unchanged`, async () => {
+			const { dispatchPaste } = await load();
+			const r = stack({});
+			expect(dispatchPaste(r.layers, text)).toBeNull();
+			expect(r.seen).toEqual(ORDER.map((id) => ({ id, text })));
+		});
+	}
+});