magus-cli 7.3.0 → 7.4.0

package/src/__tests__/blind/c17-enter-label.test.ts

@@ -0,0 +1,625 @@
+/**
+ * Blind tests — contract C17 (requirement R5.9), with C14 (CliToolRow) and
+ * C5 (keymap) as the surrounding contracts.
+ *
+ * Written from requirements.md and architecture.md only.
+ *
+ * R5.9: a key whose action depends on the selected row names that action in
+ * the footer, and the footer, the detail pane and the handler all take it from
+ * one function. CLI Tools, Enter:
+ *   not installed        → "install"
+ *   update available     → "update"  (detail "Update to vX" when a target is known)
+ *   cannot tell (unknown)→ "update anyway"
+ *   current              → "reinstall"
+ *   still being checked  → Enter does nothing; the footer does not advertise it.
+ * The footer label is the detail pane's action words, lowercased. Help keeps
+ * the binding's general description.
+ *
+ * AMENDED 2026-09-19: a row whose reason is `ahead-of-pin` (installed newer
+ * than its pin) has NO Enter action — cliToolEnterAction returns null and the
+ * footer does not advertise Enter (the screen passes no Enter label /
+ * `hide: ["install"]`). Every command there is wrong: the pin's command would
+ * downgrade, and latest moves further past the pin. Every other `unknown`
+ * reason keeps "update anyway".
+ *
+ * Pure: rows are built by hand to the CliToolRow contract. No IO. Modules are
+ * loaded dynamically so a missing export fails each test, not the whole file.
+ */
+import { describe, expect, test } from "bun:test";
+import { type CliTool, cliTools } from "../../data/cli-tools.js";
+import type { ToolStatus } from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+import type { CliToolRow } from "../../ui/adapters/cliToolsAdapter.js";
+
+const loadAdapter = () => import("../../ui/adapters/cliToolsAdapter.js");
+const loadKeymap = () => import("../../ui/keymap.js");
+
+type Command = { cmd: string; args: string[] };
+interface EnterAction {
+	kind: "install" | "update" | "update-anyway" | "reinstall";
+	label: string;
+	detail: string;
+	progress: string;
+	command: Command;
+}
+interface Binding {
+	id: string;
+	keys: readonly string[];
+	label: string;
+	description: string;
+	priority: number;
+}
+interface FooterOptions {
+	owner?: "screen" | "input" | "none";
+	hide?: readonly string[];
+	labels?: Readonly<Record<string, string>>;
+}
+
+/** Calls cliToolEnterAction through the module, failing clearly if it is absent. */
+async function enterAction(row: CliToolRow): Promise<EnterAction | null> {
+	const mod = (await loadAdapter()) as unknown as {
+		cliToolEnterAction?: (r: CliToolRow) => EnterAction | null;
+	};
+	if (typeof mod.cliToolEnterAction !== "function") {
+		throw new Error("cliToolsAdapter does not export cliToolEnterAction");
+	}
+	return mod.cliToolEnterAction(row);
+}
+
+/** Calls footerHints with the C17 options argument. */
+async function hintsFor(
+	width: number,
+	options?: FooterOptions,
+): Promise<Binding[]> {
+	const km = await loadKeymap();
+	const fn = km.footerHints as unknown as (
+		screen: string,
+		width: number,
+		options?: FooterOptions,
+	) => Binding[];
+	return options === undefined
+		? fn("cli-tools", width)
+		: fn("cli-tools", width, options);
+}
+
+const SCREEN = "cli-tools";
+const ENTER_ID = "install";
+const isEnter = (b: Binding) => b.keys.includes("Enter");
+const sig = (b: Binding) => JSON.stringify([b.id, [...b.keys], b.label]);
+const show = (hints: readonly Binding[]) =>
+	hints.map((b) => `${b.keys.join("/")} ${b.label}`);
+
+/** The keymap's own CLI Tools Enter binding (id "install", keys ["Enter"]). */
+async function keymapEnter(): Promise<Binding> {
+	const km = await loadKeymap();
+	const found = (km.SCREEN_BINDINGS[SCREEN] as readonly Binding[]).find(
+		(b) => b.id === ENTER_ID,
+	);
+	if (!found) throw new Error('SCREEN_BINDINGS["cli-tools"] has no "install"');
+	return found;
+}
+
+/**
+ * The detail pane's leading action words, lowercased: the words before the
+ * first "to", the first version-looking token, or the first token that does
+ * not start with a letter. "Update to v1.2.3" → "update";
+ * "Update anyway" → "update anyway"; "Reinstall v2.0.0" → "reinstall".
+ */
+function actionWords(detail: string): string {
+	const words: string[] = [];
+	for (const token of detail.trim().split(/\s+/)) {
+		if (token.toLowerCase() === "to") break;
+		if (/^v?\d/i.test(token)) break;
+		if (!/^\p{L}/u.test(token)) break;
+		words.push(token);
+	}
+	return words.join(" ").toLowerCase();
+}
+
+describe("C17 — the test's own action-word reader", () => {
+	test("R5.9 control: action words stop at `to`, at a version, and at punctuation", () => {
+		expect(actionWords("Update to v1.2.3")).toBe("update");
+		expect(actionWords("Update anyway")).toBe("update anyway");
+		expect(actionWords("Install")).toBe("install");
+		expect(actionWords("Reinstall v2.0.0")).toBe("reinstall");
+		expect(actionWords("Reinstall (2.0.0)")).toBe("reinstall");
+	});
+});
+
+// ── rows ────────────────────────────────────────────────────────────────────
+
+const TOOL: CliTool = cliTools[0] as CliTool;
+const SPEC: BinRequirement = {
+	name: TOOL.name,
+	via: "npm",
+	package: "@example/x",
+};
+const INSTALL_CMD: Command = {
+	cmd: "npm",
+	args: ["install", "-g", "@example/x"],
+};
+const UPDATE_CMD: Command = {
+	cmd: "npm",
+	args: ["update", "-g", "@example/x"],
+};
+
+type StatusFields = Pick<
+	ToolStatus,
+	"state" | "reason" | "installed" | "latest" | "target"
+> & { pin?: string };
+
+function status(fields: StatusFields): ToolStatus {
+	return {
+		name: TOOL.name,
+		state: fields.state,
+		reason: fields.reason,
+		installed: fields.installed,
+		latest: fields.latest,
+		target: fields.target,
+		...(fields.pin ? { pin: fields.pin } : {}),
+	};
+}
+
+function row(
+	st: ToolStatus | null,
+	opts: { checking?: boolean; withUpdate?: boolean } = {},
+): CliToolRow {
+	return {
+		tool: TOOL,
+		spec: SPEC,
+		checking: opts.checking ?? false,
+		status: st,
+		installCommand: INSTALL_CMD,
+		...(opts.withUpdate === false ? {} : { updateCommand: UPDATE_CMD }),
+	};
+}
+
+interface Case {
+	name: string;
+	fields: StatusFields;
+	kind: EnterAction["kind"];
+	label: string;
+}
+
+/** Every state, each reason that can produce it, with realistic versions. */
+const CASES: Case[] = [
+	{
+		name: "install / absent",
+		fields: {
+			state: "install",
+			reason: "absent",
+			installed: null,
+			latest: "2.0.0",
+			target: "2.0.0",
+		},
+		kind: "install",
+		label: "install",
+	},
+	{
+		name: "upgrade / behind",
+		fields: {
+			state: "upgrade",
+			reason: "behind",
+			installed: "1.0.0",
+			latest: "1.2.3",
+			target: "1.2.3",
+		},
+		kind: "update",
+		label: "update",
+	},
+	{
+		name: "upgrade / behind-pin",
+		fields: {
+			state: "upgrade",
+			reason: "behind-pin",
+			installed: "1.0.0",
+			latest: "3.0.0",
+			target: "1.5.0",
+			pin: "1.5.0",
+		},
+		kind: "update",
+		label: "update",
+	},
+	{
+		name: "current / up-to-date",
+		fields: {
+			state: "current",
+			reason: "up-to-date",
+			installed: "2.0.0",
+			latest: "2.0.0",
+			target: null,
+		},
+		kind: "reinstall",
+		label: "reinstall",
+	},
+	{
+		name: "current / at-pin",
+		fields: {
+			state: "current",
+			reason: "at-pin",
+			installed: "1.5.0",
+			latest: "3.0.0",
+			target: null,
+			pin: "1.5.0",
+		},
+		kind: "reinstall",
+		label: "reinstall",
+	},
+	// Every `unknown` reason except `ahead-of-pin`, which has no Enter action
+	// (R5.9 AMENDED) and is covered in its own block below.
+	...(
+		[
+			["version-unreadable", null, "2.0.0", undefined],
+			["unorderable", "nightly-2026-09-01", "2.0.0", undefined],
+			["not-managed", "1.2.3", "2.0.0", undefined],
+			["held-back", "1.2.3", "2.0.0", "1.2.3"],
+			["pin-not-installable", "1.2.3", "2.0.0", "9.9.9"],
+			["latest-unavailable", "1.2.3", null, undefined],
+			["not-probed", null, null, undefined],
+		] as const
+	).map(
+		([reason, installed, latest, pin]): Case => ({
+			name: `unknown / ${reason}`,
+			fields: {
+				state: "unknown",
+				reason,
+				installed,
+				latest,
+				target: null,
+				...(pin ? { pin } : {}),
+			},
+			kind: "update-anyway",
+			label: "update anyway",
+		}),
+	),
+];
+
+/** Fails with the row's name rather than a bare "expected object, got null". */
+async function mustAct(
+	c: Case,
+	opts?: { withUpdate?: boolean },
+): Promise<EnterAction> {
+	const action = await enterAction(row(status(c.fields), opts));
+	if (action === null) throw new Error(`${c.name}: cliToolEnterAction → null`);
+	return action;
+}
+
+// ── cliToolEnterAction ──────────────────────────────────────────────────────
+
+describe("C17 — cliToolEnterAction while the row is being checked", () => {
+	test("R5.9 a checking row with no status yet → null (Enter does nothing)", async () => {
+		expect(await enterAction(row(null, { checking: true }))).toBeNull();
+	});
+
+	test("R5.9 a checking row that still carries an earlier status → null", async () => {
+		const earlier = status({
+			state: "upgrade",
+			reason: "behind",
+			installed: "1.0.0",
+			latest: "1.2.3",
+			target: "1.2.3",
+		});
+		expect(await enterAction(row(earlier, { checking: true }))).toBeNull();
+	});
+
+	test("R5.9 a row that is not checking but has no status → null", async () => {
+		expect(await enterAction(row(null, { checking: false }))).toBeNull();
+	});
+});
+
+describe("C17 — cliToolEnterAction per state", () => {
+	for (const c of CASES) {
+		test(`R5.9 ${c.name}: kind "${c.kind}", footer label "${c.label}"`, async () => {
+			const a = await mustAct(c);
+			expect({ kind: a.kind, label: a.label }).toEqual({
+				kind: c.kind,
+				label: c.label,
+			});
+		});
+
+		test(`R5.9 ${c.name}: the label is the detail's action words, lowercased`, async () => {
+			const a = await mustAct(c);
+			// The detail rides along so a failure shows what the pane printed.
+			expect({ detail: a.detail, words: actionWords(a.detail) }).toEqual({
+				detail: a.detail,
+				words: a.label,
+			});
+		});
+
+		test(`R5.9 ${c.name}: detail and progress are real text (no null/undefined leaks)`, async () => {
+			const a = await mustAct(c);
+			for (const text of [a.detail, a.progress]) {
+				expect(typeof text).toBe("string");
+				expect(text.trim().length).toBeGreaterThan(0);
+				expect(text).not.toMatch(/null|undefined|NaN/);
+			}
+		});
+
+		const want = c.kind === "install" ? "installCommand" : "updateCommand";
+		test(`R5.9 ${c.name}: with both commands, the command is the ${want}`, async () => {
+			const a = await mustAct(c, { withUpdate: true });
+			expect(a.command).toEqual(
+				c.kind === "install" ? INSTALL_CMD : UPDATE_CMD,
+			);
+		});
+
+		test(`R5.9 ${c.name}: with no updateCommand, the command falls back to the installCommand`, async () => {
+			const a = await mustAct(c, { withUpdate: false });
+			expect(a.command).toEqual(INSTALL_CMD);
+		});
+	}
+});
+
+// ── ahead-of-pin: no Enter action (R5.9 AMENDED 2026-09-19) ─────────────────
+
+/** Installed 2.1.0, pinned at 2.0.0 — the installed copy is newer than its pin. */
+const PIN = "2.0.0";
+const PINNED_SPEC: BinRequirement = { ...SPEC, version: PIN };
+/** What an updater aimed at the pin would run: a downgrade to an older version. */
+const DOWNGRADE_CMD: Command = {
+	cmd: "npm",
+	args: ["install", "-g", `@example/x@${PIN}`],
+};
+
+const AHEAD_VARIANTS = [
+	{ name: "latest equals installed", installed: "2.1.0", latest: "2.1.0" },
+	{ name: "latest past installed", installed: "2.1.0", latest: "3.0.0" },
+] as const;
+
+function aheadRow(
+	v: (typeof AHEAD_VARIANTS)[number],
+	commands: { update?: Command; install: Command },
+): CliToolRow {
+	return {
+		tool: TOOL,
+		spec: PINNED_SPEC,
+		checking: false,
+		status: status({
+			state: "unknown",
+			reason: "ahead-of-pin",
+			installed: v.installed,
+			latest: v.latest,
+			target: null,
+			pin: PIN,
+		}),
+		installCommand: commands.install,
+		...(commands.update ? { updateCommand: commands.update } : {}),
+	};
+}
+
+describe("C17 — cliToolEnterAction for ahead-of-pin rows (R5.9 AMENDED)", () => {
+	for (const v of AHEAD_VARIANTS) {
+		test(`R5.9 unknown / ahead-of-pin (${v.name}): no Enter action → null`, async () => {
+			const a = await enterAction(
+				aheadRow(v, { update: UPDATE_CMD, install: INSTALL_CMD }),
+			);
+			expect(a).toBeNull();
+		});
+
+		test(`R5.9 unknown / ahead-of-pin (${v.name}): an updateCommand aimed at the older pin AND an installCommand still yield null (no command can run)`, async () => {
+			const a = await enterAction(
+				aheadRow(v, { update: DOWNGRADE_CMD, install: INSTALL_CMD }),
+			);
+			// Surface the command that would have run, if any, on failure.
+			expect(
+				a === null ? null : { kind: a.kind, command: a.command },
+			).toBeNull();
+		});
+
+		test(`R5.9 unknown / ahead-of-pin (${v.name}): with only an installCommand → null`, async () => {
+			const a = await enterAction(aheadRow(v, { install: INSTALL_CMD }));
+			expect(a).toBeNull();
+		});
+	}
+
+	test('R5.9 unknown / ahead-of-pin: the null action is shown as hide ["install"], and the footer advertises no Enter', async () => {
+		const a = await enterAction(
+			aheadRow(AHEAD_VARIANTS[0], {
+				update: DOWNGRADE_CMD,
+				install: INSTALL_CMD,
+			}),
+		);
+		expect(a).toBeNull();
+		// A null action: the screen passes no Enter label and hides the binding.
+		const hints = await hintsFor(200, { hide: [ENTER_ID] });
+		expect(show(hints.filter(isEnter))).toEqual([]);
+		expect(hints.filter((b) => b.id === ENTER_ID)).toEqual([]);
+	});
+
+	test("R5.9 control: the other unknown reasons still offer update anyway (ahead-of-pin is the only exception)", async () => {
+		const others = CASES.filter((c) => c.fields.state === "unknown");
+		expect(others.map((c) => c.fields.reason).sort()).toEqual(
+			[
+				"held-back",
+				"latest-unavailable",
+				"not-managed",
+				"not-probed",
+				"pin-not-installable",
+				"unorderable",
+				"version-unreadable",
+			].sort(),
+		);
+		for (const c of others) {
+			const a = await mustAct(c);
+			expect({ reason: c.fields.reason, kind: a.kind, label: a.label }).toEqual(
+				{
+					reason: c.fields.reason,
+					kind: "update-anyway",
+					label: "update anyway",
+				},
+			);
+		}
+	});
+});
+
+describe("C17 — the update detail names its target", () => {
+	const behind = (target: string | null): Case => ({
+		name: `upgrade / behind → ${target}`,
+		fields: {
+			state: "upgrade",
+			reason: "behind",
+			installed: "1.0.0",
+			latest: "1.2.3",
+			target,
+		},
+		kind: "update",
+		label: "update",
+	});
+
+	test('R5.9 upgrade with target 1.2.3: detail is "Update to v1.2.3"', async () => {
+		const a = await mustAct(behind("1.2.3"));
+		expect(a.detail).toBe("Update to v1.2.3");
+	});
+
+	test("R5.9 upgrade with target 1.2.3: detail carries the version with one leading v", async () => {
+		const a = await mustAct(behind("1.2.3"));
+		expect(a.detail).toContain("v1.2.3");
+		expect(a.detail).not.toMatch(/vv\d/i);
+	});
+
+	test("R5.9 upgrade with a target already written v1.2.3: still one leading v", async () => {
+		const a = await mustAct(behind("v1.2.3"));
+		expect(a.detail).toContain("v1.2.3");
+		expect(a.detail).not.toMatch(/vv\d/i);
+	});
+
+	test("R5.9 upgrade with no known target: the label stays update and the detail names no version", async () => {
+		const a = await mustAct(behind(null));
+		expect(a.kind).toBe("update");
+		expect(a.label).toBe("update");
+		expect(actionWords(a.detail)).toBe("update");
+		expect(a.detail).not.toMatch(/null|undefined|\bv\b|to\s*$/);
+	});
+});
+
+// ── footerHints with labels / hide ──────────────────────────────────────────
+
+describe("C17 — the CLI Tools Enter binding in the keymap", () => {
+	test('R5.9 SCREEN_BINDINGS["cli-tools"] has an Enter binding with id "install"', async () => {
+		const b = await keymapEnter();
+		expect([...b.keys]).toEqual(["Enter"]);
+		expect(b.label.trim().length).toBeGreaterThan(0);
+		expect(b.description.trim().length).toBeGreaterThan(0);
+	});
+});
+
+describe("C17 — footerHints(cli-tools) with a row label", () => {
+	test('R5.9 labels { install: "update" } @200: an Enter hint labelled "update", none labelled "install"', async () => {
+		const hints = await hintsFor(200, { labels: { install: "update" } });
+		const enter = hints.filter(isEnter);
+		expect(show(enter)).toEqual(["Enter update"]);
+		expect(enter[0]?.id).toBe(ENTER_ID);
+		expect(show(hints.filter((b) => b.label === "install"))).toEqual([]);
+	});
+
+	test("R5.9 no options @200: the Enter hint keeps the keymap's default label", async () => {
+		const def = await keymapEnter();
+		const hints = await hintsFor(200);
+		expect(show(hints.filter(isEnter))).toEqual([`Enter ${def.label}`]);
+	});
+
+	test('R5.9 hide ["install"] @200: no Enter hint (a row being checked)', async () => {
+		const hints = await hintsFor(200, { hide: [ENTER_ID] });
+		expect(show(hints.filter(isEnter))).toEqual([]);
+		expect(hints.filter((b) => b.id === ENTER_ID)).toEqual([]);
+	});
+
+	test('R5.9 hide ["install"] wins over a label for the same binding', async () => {
+		const hints = await hintsFor(200, {
+			hide: [ENTER_ID],
+			labels: { install: "update" },
+		});
+		expect(show(hints.filter(isEnter))).toEqual([]);
+		expect(show(hints.filter((b) => b.label === "update"))).toEqual([]);
+	});
+
+	test("R5.9 a label only renames the Enter hint; every other hint is unchanged", async () => {
+		const plain = await hintsFor(10_000);
+		const named = await hintsFor(10_000, { labels: { install: "update" } });
+		const others = (hs: Binding[]) =>
+			hs
+				.filter((b) => b.id !== ENTER_ID)
+				.map(sig)
+				.sort();
+		expect(others(named)).toEqual(others(plain));
+	});
+
+	test("R5.9 a label for an id the screen does not have changes nothing", async () => {
+		const plain = await hintsFor(200);
+		const named = await hintsFor(200, {
+			labels: { "no-such-binding": "zzz" },
+		});
+		expect(named.map(sig)).toEqual(plain.map(sig));
+	});
+
+	test("R5.9 an override does not leak into the keymap or into later calls", async () => {
+		const before = await keymapEnter();
+		const beforeLabel = before.label;
+		await hintsFor(200, { labels: { install: "update anyway" } });
+		const after = await keymapEnter();
+		expect(after.label).toBe(beforeLabel);
+		const later = await hintsFor(200);
+		expect(show(later.filter(isEnter))).toEqual([`Enter ${beforeLabel}`]);
+	});
+
+	for (const width of [40, 60, 80, 100] as const) {
+		test(`R5.9 labels { install: "update anyway" } @${width}: footerWidth(hints) <= ${width}`, async () => {
+			const km = await loadKeymap();
+			const hints = await hintsFor(width, {
+				labels: { install: "update anyway" },
+			});
+			expect(km.footerWidth(hints)).toBeLessThanOrEqual(width);
+		});
+
+		test(`R5.9 labels { install: "update anyway" } @${width}: any Enter hint shown carries the override`, async () => {
+			const hints = await hintsFor(width, {
+				labels: { install: "update anyway" },
+			});
+			for (const b of hints.filter(isEnter)) {
+				expect(b.label).toBe("update anyway");
+			}
+		});
+
+		test(`R5.9 a label too long for any footer @${width}: budget uses the replaced label, so it still fits`, async () => {
+			const km = await loadKeymap();
+			const huge = "update anyway ".repeat(12).trim();
+			const hints = await hintsFor(width, { labels: { install: huge } });
+			expect(km.footerWidth(hints)).toBeLessThanOrEqual(width);
+			expect(show(hints.filter(isEnter))).toEqual([]);
+		});
+	}
+});
+
+describe("C17 — one function feeds the footer (R5.9)", () => {
+	for (const c of CASES) {
+		test(`R5.9 ${c.name}: passing the action's label to footerHints shows "Enter ${c.label}"`, async () => {
+			const a = await mustAct(c);
+			const hints = await hintsFor(200, { labels: { install: a.label } });
+			expect(show(hints.filter(isEnter))).toEqual([`Enter ${a.label}`]);
+		});
+	}
+});
+
+// ── help ────────────────────────────────────────────────────────────────────
+
+describe("C17 — help keeps the general description", () => {
+	for (const current of ["cli-tools", "plugins"] as const) {
+		test(`R5.9 helpSections("${current}") lists the Enter binding with its default label and general description, after footer overrides`, async () => {
+			const km = await loadKeymap();
+			const def = await keymapEnter();
+			// Footer options passed elsewhere must not reach help.
+			await hintsFor(200, { labels: { install: "update anyway" } });
+			await hintsFor(200, { hide: [ENTER_ID] });
+			const section = km.helpSections(current).find((s) => s.screen === SCREEN);
+			expect(section).toBeDefined();
+			const enter = (section?.bindings as readonly Binding[] | undefined)?.find(
+				(b) => b.id === ENTER_ID,
+			);
+			expect(enter).toBeDefined();
+			expect([...(enter?.keys ?? [])]).toEqual(["Enter"]);
+			expect(enter?.label).toBe(def.label);
+			expect(enter?.description).toBe(def.description);
+			expect(enter?.description.toLowerCase()).not.toBe("update anyway");
+		});
+	}
+});