magus-cli 7.3.1 → 7.4.0

package/src/__tests__/blind/c5-keymap.test.ts

@@ -0,0 +1,461 @@
+/**
+ * Blind tests — contract C5 (requirements R5.1–R5.8, R4.6, R9.4, R10.6).
+ *
+ * Written from requirements.md and architecture.md only. The Screen list and
+ * the width set are taken from the contract, not from the module, so the
+ * generated test names exist even while the module does not.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const loadKeymap = () => import("../../ui/keymap.js");
+const loadTabBar = () => import("../../ui/components/TabBar.js");
+
+const SCREENS = [
+	"plugins",
+	"mcp",
+	"mcp-registry",
+	"settings",
+	"cli-tools",
+	"profiles",
+	"skills",
+	"styles",
+	"gitignore",
+	"alias",
+	"models",
+] as const;
+type Screen = (typeof SCREENS)[number];
+const TAB_SCREENS = SCREENS.filter((s) => s !== "mcp-registry");
+const WIDTHS = [40, 60, 80, 100, 200] as const;
+/** Wide enough that nothing is dropped for lack of room. */
+const UNLIMITED = 10_000;
+
+interface Binding {
+	id: string;
+	keys: readonly string[];
+	label: string;
+	description: string;
+	priority: number;
+}
+type Keymap = Awaited<ReturnType<typeof loadKeymap>>;
+
+const sig = (b: Binding) => JSON.stringify([b.id, [...b.keys], b.label]);
+const show = (b: Binding) => `${b.keys.join("/")} ${b.label} (p${b.priority})`;
+
+function helpBinding(km: Keymap): Binding {
+	const help = (km.GLOBAL_BINDINGS as readonly Binding[]).find((b) =>
+		b.keys.includes("?"),
+	);
+	if (!help) throw new Error('GLOBAL_BINDINGS has no binding with key "?"');
+	return help;
+}
+
+/** Normalise a displayed key so "PgUp", "PageUp", "Ctrl+U" and "^U" compare. */
+function normKey(k: string): string {
+	const s = k.trim().toLowerCase().replace(/\s+/g, "");
+	const ctrl = s.replace(/^(ctrl\+|ctrl-|c-)/, "^");
+	if (ctrl === "pageup") return "pgup";
+	if (ctrl === "pagedown") return "pgdn";
+	return ctrl;
+}
+const splitKeys = (keys: readonly string[]) =>
+	keys.flatMap((k) => (k.length > 1 ? k.split("/") : [k])).map(normKey);
+const SCROLL_KEY_NAMES = new Set(["pgup", "pgdn", "^u", "^d"]);
+
+describe("C5 — the keymap lists every binding (R5.1)", () => {
+	test("R5.1 SCREEN_BINDINGS has exactly one entry per Screen (10 tabs + mcp-registry)", async () => {
+		const km = await loadKeymap();
+		expect(Object.keys(km.SCREEN_BINDINGS).sort()).toEqual([...SCREENS].sort());
+		for (const s of SCREENS) {
+			expect(Array.isArray(km.SCREEN_BINDINGS[s as Screen])).toBe(true);
+		}
+	});
+
+	test("R5.1 every binding is well-formed: id, displayed keys, label, description, finite priority", async () => {
+		const km = await loadKeymap();
+		const groups: [string, readonly Binding[]][] = [
+			["GLOBAL", km.GLOBAL_BINDINGS],
+			["SCROLL", km.SCROLL_BINDINGS],
+			...SCREENS.map(
+				(s) =>
+					[
+						s,
+						(km.SCREEN_BINDINGS[s as Screen] ?? []) as readonly Binding[],
+					] as [string, readonly Binding[]],
+			),
+		];
+		const bad: string[] = [];
+		for (const [group, bindings] of groups) {
+			for (const b of bindings) {
+				const ok =
+					typeof b.id === "string" &&
+					b.id.length > 0 &&
+					Array.isArray(b.keys) &&
+					b.keys.length > 0 &&
+					b.keys.every((k) => typeof k === "string" && k.length > 0) &&
+					typeof b.label === "string" &&
+					b.label.length > 0 &&
+					typeof b.description === "string" &&
+					b.description.length > 0 &&
+					Number.isFinite(b.priority);
+				if (!ok) bad.push(`${group}: ${JSON.stringify(b)}`);
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+
+	test('R5.1 GLOBAL_BINDINGS includes a "?" binding and a "q" binding', async () => {
+		const km = await loadKeymap();
+		const all = (km.GLOBAL_BINDINGS as readonly Binding[]).flatMap((b) => [
+			...b.keys,
+		]);
+		expect(all).toContain("?");
+		expect(all).toContain("q");
+	});
+
+	test("R5.4 the global ? binding is the `help` hint", async () => {
+		const km = await loadKeymap();
+		expect(helpBinding(km).label.toLowerCase()).toContain("help");
+	});
+
+	test("R5.1 SCROLL_BINDINGS cover PgUp, PgDn, ^U and ^D", async () => {
+		const km = await loadKeymap();
+		const keys = new Set(
+			(km.SCROLL_BINDINGS as readonly Binding[]).flatMap((b) =>
+				splitKeys(b.keys),
+			),
+		);
+		for (const k of SCROLL_KEY_NAMES) expect(keys.has(k)).toBe(true);
+	});
+
+	test("R5.1 binding ids are unique within GLOBAL_BINDINGS and within SCROLL_BINDINGS", async () => {
+		const km = await loadKeymap();
+		for (const group of [km.GLOBAL_BINDINGS, km.SCROLL_BINDINGS]) {
+			const ids = (group as readonly Binding[]).map((b) => b.id);
+			expect(new Set(ids).size).toBe(ids.length);
+		}
+	});
+});
+
+describe("C5 — tab keys come from TABS (R5.7)", () => {
+	test("R5.7 TABS lists the 10 tab screens exactly once each (mcp-registry has no tab)", async () => {
+		const { TABS } = await loadTabBar();
+		const screens = TABS.map((t: { screen: string }) => t.screen);
+		expect([...screens].sort()).toEqual([...TAB_SCREENS].sort());
+	});
+
+	test("R5.7 every tab key is a single digit, and no two tabs share one", async () => {
+		const { TABS } = await loadTabBar();
+		const keys = TABS.map((t: { key: string }) => t.key);
+		for (const k of keys) expect(k).toMatch(/^[0-9]$/);
+		expect(new Set(keys).size).toBe(keys.length);
+	});
+
+	for (const screen of TAB_SCREENS) {
+		test(`R5.7 tabKey("${screen}") is that screen's key from TABS`, async () => {
+			const km = await loadKeymap();
+			const { TABS } = await loadTabBar();
+			const tab = TABS.find((t: { screen: string }) => t.screen === screen);
+			expect(tab).toBeDefined();
+			expect(km.tabKey(screen)).toBe(tab?.key);
+		});
+	}
+
+	test('R5.7 tabKey("mcp-registry") is null (a sub-screen with no tab)', async () => {
+		const km = await loadKeymap();
+		expect(km.tabKey("mcp-registry")).toBeNull();
+	});
+
+	test("R5.7/R9.4 no UI text under src/ui types a tab number (e.g. `Press 5`)", () => {
+		// Static scan of source text. Comment lines are skipped; a template such
+		// as `Press ${tabKey("profiles")}` does not match.
+		const uiDir = path.resolve(import.meta.dir, "../../ui");
+		const offenders: string[] = [];
+		const pattern = /\b(press|hit|type)\s+[0-9]\b/i;
+		for (const file of walk(uiDir)) {
+			const lines = readFileSync(file, "utf8").split("\n");
+			lines.forEach((line, i) => {
+				if (isCommentLine(line)) return;
+				if (pattern.test(line)) {
+					offenders.push(
+						`${path.relative(uiDir, file)}:${i + 1}: ${line.trim()}`,
+					);
+				}
+			});
+		}
+		expect(offenders).toEqual([]);
+	});
+});
+
+for (const screen of SCREENS) {
+	describe(`C5 — ${screen} bindings (R5.3, R4.6)`, () => {
+		test(`R5.3 ${screen}: no two bindings claim the same key`, async () => {
+			const km = await loadKeymap();
+			const keys = (km.SCREEN_BINDINGS[screen] as readonly Binding[]).flatMap(
+				(b) => [...b.keys],
+			);
+			const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
+			expect(dupes).toEqual([]);
+		});
+
+		test(`R5.3 ${screen}: binding ids are unique`, async () => {
+			const km = await loadKeymap();
+			const ids = (km.SCREEN_BINDINGS[screen] as readonly Binding[]).map(
+				(b) => b.id,
+			);
+			expect(new Set(ids).size).toBe(ids.length);
+		});
+
+		test(`R5.3 ${screen}: no binding claims a digit, q or ?`, async () => {
+			const km = await loadKeymap();
+			const claimed = (
+				km.SCREEN_BINDINGS[screen] as readonly Binding[]
+			).flatMap((b) =>
+				b.keys
+					.filter((k) => /^[0-9]$/.test(k) || k === "q" || k === "?")
+					.map((k) => `${b.id}: ${k}`),
+			);
+			expect(claimed).toEqual([]);
+		});
+
+		test(`R4.6 ${screen}: no binding claims a scroll key (PgUp, PgDn, ^U, ^D)`, async () => {
+			// The screen layer sits above scroll; a screen binding on a scroll key
+			// would stop the panel scrolling on this screen.
+			const km = await loadKeymap();
+			const claimed = (
+				km.SCREEN_BINDINGS[screen] as readonly Binding[]
+			).flatMap((b) =>
+				splitKeys(b.keys)
+					.filter((k) => SCROLL_KEY_NAMES.has(k))
+					.map((k) => `${b.id}: ${k}`),
+			);
+			expect(claimed).toEqual([]);
+		});
+	});
+
+	describe(`C5 — footerHints("${screen}", width) (R5.2, R5.4, R5.5)`, () => {
+		for (const width of WIDTHS) {
+			test(`R5.5 ${screen} @${width}: footerWidth(hints) <= ${width}`, async () => {
+				const km = await loadKeymap();
+				const hints = km.footerHints(screen, width);
+				expect(km.footerWidth(hints)).toBeLessThanOrEqual(width);
+			});
+
+			test(`R5.4 ${screen} @${width}: the footer shows the "? help" hint`, async () => {
+				const km = await loadKeymap();
+				const help = helpBinding(km);
+				// The contract keeps "?" whenever the width allows it.
+				expect(km.footerWidth([help])).toBeLessThanOrEqual(width);
+				const hints = km.footerHints(screen, width) as Binding[];
+				expect(hints.map(sig)).toContain(sig(help));
+			});
+
+			test(`R5.2 ${screen} @${width}: every hint comes from the keymap (screen ∪ scroll ∪ global), once`, async () => {
+				const km = await loadKeymap();
+				const allowed = new Set(
+					[
+						...(km.SCREEN_BINDINGS[screen] as readonly Binding[]),
+						...(km.SCROLL_BINDINGS as readonly Binding[]),
+						...(km.GLOBAL_BINDINGS as readonly Binding[]),
+					].map(sig),
+				);
+				const hints = (km.footerHints(screen, width) as Binding[]).map(sig);
+				expect(hints.filter((h) => !allowed.has(h))).toEqual([]);
+				expect(new Set(hints).size).toBe(hints.length);
+			});
+
+			test(`R5.5 ${screen} @${width}: never keeps a lower-priority hint while dropping a higher one`, async () => {
+				const km = await loadKeymap();
+				const help = sig(helpBinding(km));
+				const pool = km.footerHints(screen, UNLIMITED) as Binding[];
+				const kept = km.footerHints(screen, width) as Binding[];
+				const keptSigs = new Set(kept.map(sig));
+				const dropped = pool.filter((b) => !keptSigs.has(sig(b)));
+				// "?" is pinned by R5.4, so it is exempt from the ordering.
+				const ranked = kept.filter((b) => sig(b) !== help);
+				const violations: string[] = [];
+				for (const d of dropped) {
+					for (const k of ranked) {
+						if (k.priority < d.priority) {
+							violations.push(`kept ${show(k)} but dropped ${show(d)}`);
+						}
+					}
+				}
+				expect(violations).toEqual([]);
+			});
+
+			test(`R5.5 ${screen} @${width}: shows as many hints as fit (the next-priority hint does not fit)`, async () => {
+				const km = await loadKeymap();
+				const pool = km.footerHints(screen, UNLIMITED) as Binding[];
+				const kept = km.footerHints(screen, width) as Binding[];
+				const keptSigs = new Set(kept.map(sig));
+				const dropped = pool.filter((b) => !keptSigs.has(sig(b)));
+				if (dropped.length === 0) return; // everything fits — nothing to check
+				const top = Math.max(...dropped.map((b) => b.priority));
+				const next = dropped.filter((b) => b.priority === top);
+				const fitting = next.filter(
+					(d) => km.footerWidth([...kept, d]) <= width,
+				);
+				// At least one of the next-highest candidates must be too wide,
+				// otherwise the footer dropped a hint it had room for.
+				expect(fitting.length).toBeLessThan(next.length);
+			});
+		}
+
+		test(`R5.5 ${screen}: a narrower footer keeps a subset of a wider one`, async () => {
+			const km = await loadKeymap();
+			const sets = WIDTHS.map(
+				(w) => new Set((km.footerHints(screen, w) as Binding[]).map(sig)),
+			);
+			const leaks: string[] = [];
+			for (let i = 0; i + 1 < sets.length; i++) {
+				for (const s of sets[i] as Set<string>) {
+					if (!(sets[i + 1] as Set<string>).has(s)) {
+						leaks.push(`@${WIDTHS[i]} has ${s}, @${WIDTHS[i + 1]} does not`);
+					}
+				}
+			}
+			expect(leaks).toEqual([]);
+		});
+	});
+
+	describe(`C5 — helpSections("${screen}") (R5.2, R5.6)`, () => {
+		test(`R5.6 helpSections("${screen}"): the first section is ${screen}`, async () => {
+			const km = await loadKeymap();
+			const sections = km.helpSections(screen);
+			expect(sections.length).toBeGreaterThan(0);
+			expect(sections[0]?.screen).toBe(screen);
+		});
+
+		test(`R5.6 helpSections("${screen}"): every Screen appears in exactly one section`, async () => {
+			const km = await loadKeymap();
+			const sections = km.helpSections(screen);
+			const counts = Object.fromEntries(
+				SCREENS.map((s) => [s, sections.filter((x) => x.screen === s).length]),
+			);
+			expect(counts).toEqual(Object.fromEntries(SCREENS.map((s) => [s, 1])));
+		});
+
+		test(`R5.6 helpSections("${screen}"): global and scroll keys have their own sections, after the screens`, async () => {
+			const km = await loadKeymap();
+			const sections = km.helpSections(screen);
+			const has = (
+				s: { bindings: readonly Binding[] },
+				group: readonly Binding[],
+			) => {
+				const sigs = new Set(s.bindings.map(sig));
+				return group.length > 0 && group.every((b) => sigs.has(sig(b)));
+			};
+			const g = sections.findIndex(
+				(s) =>
+					s.screen === undefined &&
+					has(s, km.GLOBAL_BINDINGS as readonly Binding[]),
+			);
+			const sc = sections.findIndex(
+				(s) =>
+					s.screen === undefined &&
+					has(s, km.SCROLL_BINDINGS as readonly Binding[]),
+			);
+			expect(g).toBeGreaterThanOrEqual(0);
+			expect(sc).toBeGreaterThanOrEqual(0);
+			expect(g).not.toBe(sc);
+			const lastScreen = Math.max(
+				...sections.map((s, i) => (s.screen !== undefined ? i : -1)),
+			);
+			expect(lastScreen).toBeLessThan(Math.min(g, sc));
+		});
+
+		test(`R5.2 helpSections("${screen}"): each screen section lists exactly that screen's keymap bindings`, async () => {
+			const km = await loadKeymap();
+			const mismatched: string[] = [];
+			for (const s of km.helpSections(screen)) {
+				if (s.screen === undefined) continue;
+				const want = (
+					km.SCREEN_BINDINGS[s.screen as Screen] as readonly Binding[]
+				)
+					.map(sig)
+					.sort();
+				const got = (s.bindings as readonly Binding[]).map(sig).sort();
+				if (JSON.stringify(want) !== JSON.stringify(got))
+					mismatched.push(s.screen);
+			}
+			expect(mismatched).toEqual([]);
+		});
+
+		test(`R5.6 helpSections("${screen}"): every section has a title`, async () => {
+			const km = await loadKeymap();
+			const untitled = km
+				.helpSections(screen)
+				.filter((s) => typeof s.title !== "string" || s.title.trim() === "");
+			expect(untitled).toEqual([]);
+		});
+	});
+}
+
+describe("C5 — help legend (R5.8, R10.6)", () => {
+	// Requirement R10.6 lists these symbols; each must be explained by the
+	// legend of whichever screen uses it.
+	const SYMBOLS = ["■", "□", "⚙", "[↓]", "[–]", "★", "☆", "●", "○"];
+
+	for (const symbol of SYMBOLS) {
+		test(`R10.6 the help legend explains ${symbol}`, async () => {
+			const km = await loadKeymap();
+			const entries = km
+				.helpSections("plugins")
+				.flatMap((s) => [...(s.legend ?? [])]);
+			const match = entries.find((e) => e.symbol.includes(symbol));
+			expect(match).toBeDefined();
+			expect(match?.meaning.trim().length ?? 0).toBeGreaterThan(0);
+		});
+	}
+
+	test("R5.8 legends are attached to screen sections, not to the global or scroll sections", async () => {
+		const km = await loadKeymap();
+		const stray = km
+			.helpSections("plugins")
+			.filter((s) => s.screen === undefined && (s.legend?.length ?? 0) > 0)
+			.map((s) => s.title);
+		expect(stray).toEqual([]);
+	});
+});
+
+describe("C5 — footerWidth", () => {
+	test("R5.5 footerWidth of one hint covers at least its key and label", async () => {
+		const km = await loadKeymap();
+		const help = helpBinding(km);
+		expect(km.footerWidth([help])).toBeGreaterThanOrEqual(
+			(help.keys[0] as string).length + 1 + help.label.length,
+		);
+	});
+
+	test("R5.5 footerWidth grows when a hint is added", async () => {
+		const km = await loadKeymap();
+		const [a, b] = km.GLOBAL_BINDINGS as readonly Binding[];
+		expect(a).toBeDefined();
+		expect(b).toBeDefined();
+		const both = km.footerWidth([a as Binding, b as Binding]);
+		expect(both).toBeGreaterThan(km.footerWidth([a as Binding]));
+		expect(both).toBeGreaterThan(km.footerWidth([b as Binding]));
+	});
+});
+
+function walk(dir: string): string[] {
+	const out: string[] = [];
+	for (const name of readdirSync(dir)) {
+		const full = path.join(dir, name);
+		if (statSync(full).isDirectory()) out.push(...walk(full));
+		else if (/\.(ts|tsx)$/.test(name)) out.push(full);
+	}
+	return out;
+}
+
+function isCommentLine(line: string): boolean {
+	const t = line.trim();
+	return (
+		t.startsWith("//") ||
+		t.startsWith("*") ||
+		t.startsWith("/*") ||
+		t.startsWith("{/*")
+	);
+}

package/src/__tests__/blind/c6-request-gate.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Blind tests — contract C6 (requirement R6.1).
+ *
+ * Written from requirements.md and architecture.md only. The race scenarios
+ * use hand-resolved promises, not timers, so the finishing order is exact.
+ */
+import { describe, expect, test } from "bun:test";
+
+const load = () => import("../../utils/request-gate.js");
+
+function deferred<T>() {
+	let resolve!: (v: T) => void;
+	const promise = new Promise<T>((r) => {
+		resolve = r;
+	});
+	return { promise, resolve };
+}
+
+describe("C6 — createRequestGate tokens", () => {
+	test("R6.1 a load that is the only one started is current", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const t = gate.begin();
+		expect(gate.isCurrent(t)).toBe(true);
+	});
+
+	test("R6.1 starting a second load makes the first one not current", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const first = gate.begin();
+		const second = gate.begin();
+		expect(gate.isCurrent(first)).toBe(false);
+		expect(gate.isCurrent(second)).toBe(true);
+	});
+
+	test("R6.1 each begin() returns a new token", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const tokens = Array.from({ length: 50 }, () => gate.begin());
+		expect(new Set(tokens).size).toBe(tokens.length);
+	});
+
+	test("R6.1 after many loads start, only the most recent one is current", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const tokens = Array.from({ length: 20 }, () => gate.begin());
+		const current = tokens.filter((t) => gate.isCurrent(t));
+		expect(current).toEqual([tokens[tokens.length - 1] as number]);
+	});
+
+	test("R6.1 asking isCurrent does not change which token is current", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const a = gate.begin();
+		const b = gate.begin();
+		for (let i = 0; i < 3; i++) {
+			expect(gate.isCurrent(a)).toBe(false);
+			expect(gate.isCurrent(b)).toBe(true);
+		}
+	});
+
+	test("R6.1 two gates are independent", async () => {
+		const { createRequestGate } = await load();
+		const plugins = createRequestGate();
+		const other = createRequestGate();
+		const p = plugins.begin();
+		other.begin();
+		other.begin();
+		expect(plugins.isCurrent(p)).toBe(true);
+	});
+});
+
+describe("C6 — the latest Plugins load wins, whichever finishes last", () => {
+	/** A screen that applies a load's result only if its token is still current. */
+	async function race(order: "older-finishes-last" | "older-finishes-first") {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const applied: string[] = [];
+
+		const older = deferred<string>();
+		const newer = deferred<string>();
+
+		const start = (result: Promise<string>) => {
+			const token = gate.begin();
+			return result.then((value) => {
+				if (gate.isCurrent(token)) applied.push(value);
+			});
+		};
+
+		const olderDone = start(older.promise);
+		const newerDone = start(newer.promise);
+
+		if (order === "older-finishes-last") {
+			newer.resolve("newer");
+			await newerDone;
+			older.resolve("older");
+			await olderDone;
+		} else {
+			older.resolve("older");
+			await olderDone;
+			newer.resolve("newer");
+			await newerDone;
+		}
+		return applied;
+	}
+
+	test("R6.1 an earlier load that finishes AFTER the later one is discarded", async () => {
+		expect(await race("older-finishes-last")).toEqual(["newer"]);
+	});
+
+	test("R6.1 an earlier load that finishes BEFORE the later one is discarded too", async () => {
+		expect(await race("older-finishes-first")).toEqual(["newer"]);
+	});
+
+	test("R6.1 three overlapping loads: only the last started updates the screen", async () => {
+		const { createRequestGate } = await load();
+		const gate = createRequestGate();
+		const applied: number[] = [];
+		const ds = [deferred<number>(), deferred<number>(), deferred<number>()];
+		const done = ds.map((d) => {
+			const token = gate.begin();
+			return d.promise.then((v) => {
+				if (gate.isCurrent(token)) applied.push(v);
+			});
+		});
+		// Finish in a scrambled order: middle, last, first.
+		for (const i of [1, 2, 0]) {
+			ds[i]?.resolve(i);
+			await done[i];
+		}
+		expect(applied).toEqual([2]);
+	});
+});