magus-cli 7.3.1 → 7.4.1

package/src/__tests__/blind/c7-tab-tiers.test.ts

@@ -0,0 +1,320 @@
+/**
+ * Blind tests — contract C7 (requirements R7.1–R7.4).
+ *
+ * Written from requirements.md and architecture.md only.
+ *
+ * Widths are computed with a reference formula taken from the contract:
+ *   barWidth(texts, padded) = Σ (cells(text) + (padded ? 2 : 0)) + (n - 1)
+ * so a wrong barWidth in the module cannot make a wrong layout look right.
+ * barWidth itself is checked against the same formula below.
+ *
+ * For every tab screen the tests sweep every available width from 0 to a
+ * little past the full padded bar, classify the returned layout into tiers
+ * 1–4, and assert the tier is the first one that fits, that the tier changes
+ * at exactly the three computed boundaries, and that R7.2/R7.3 hold at every
+ * width.
+ */
+import { describe, expect, test } from "bun:test";
+
+const load = () => import("../../ui/components/TabBar.js");
+
+const TAB_SCREENS = [
+	"plugins",
+	"mcp",
+	"settings",
+	"cli-tools",
+	"profiles",
+	"skills",
+	"styles",
+	"gitignore",
+	"alias",
+	"models",
+] as const;
+
+interface Tab {
+	key: string;
+	label: string;
+	screen: string;
+}
+interface Layout {
+	texts: string[];
+	padded: boolean;
+}
+type Tier = 1 | 2 | 3 | 4;
+
+const cells = (s: string) => [...s].length; // tab labels are single-width text
+function refBar(texts: readonly string[], padded = true): number {
+	if (texts.length === 0) return 0;
+	return (
+		texts.reduce((sum, t) => sum + cells(t) + (padded ? 2 : 0), 0) +
+		(texts.length - 1)
+	);
+}
+const full = (t: Tab) => `${t.key}:${t.label}`;
+
+/** Narrowest form of each tier for `screen`. */
+function tierForms(tabs: readonly Tab[], screen: string) {
+	const fullTexts = tabs.map(full);
+	const min3 = tabs.map((t) =>
+		t.screen === screen ? full(t) : `${t.key}:${t.label.slice(0, 3)}`,
+	);
+	const min4 = tabs.map((t) => (t.screen === screen ? full(t) : t.key));
+	return {
+		fullTexts,
+		min4,
+		W1: refBar(fullTexts, true),
+		W2: refBar(fullTexts, false),
+		W3: refBar(min3, false),
+	};
+}
+
+/** R7.1: the first tier that fits `available`. */
+function expectedTier(
+	tabs: readonly Tab[],
+	screen: string,
+	available: number,
+): Tier {
+	const { W1, W2, W3 } = tierForms(tabs, screen);
+	if (W1 <= available) return 1;
+	if (W2 <= available) return 2;
+	if (W3 <= available) return 3;
+	return 4;
+}
+
+async function layoutAt(screen: string, available: number): Promise<Layout> {
+	const { TABS, layoutTabs } = await load();
+	const out = layoutTabs(TABS, screen as never, available) as unknown;
+	const o = out as Partial<Layout> | null;
+	if (!o || !Array.isArray(o.texts) || typeof o.padded !== "boolean") {
+		throw new Error(
+			`layoutTabs(TABS, "${screen}", ${available}) did not return { texts: string[]; padded: boolean }; got ${JSON.stringify(out)}`,
+		);
+	}
+	return o as Layout;
+}
+
+/** Classify a layout into a tier, or explain why it matches none. */
+function classify(
+	tabs: readonly Tab[],
+	screen: string,
+	layout: Layout,
+): Tier | string {
+	const { texts, padded } = layout;
+	if (texts.length !== tabs.length) {
+		return `has ${texts.length} texts for ${tabs.length} tabs`;
+	}
+	const fullTexts = tabs.map(full);
+	if (texts.every((t, i) => t === fullTexts[i])) return padded ? 1 : 2;
+	const active = tabs.findIndex((t) => t.screen === screen);
+	if (texts[active] !== fullTexts[active]) {
+		return `active tab shows ${JSON.stringify(texts[active])}, not ${JSON.stringify(fullTexts[active])}`;
+	}
+	const inactive = tabs.map((_, i) => i).filter((i) => i !== active);
+	if (inactive.every((i) => texts[i] === (tabs[i] as Tab).key)) return 4;
+	const bad = inactive.filter(
+		(i) => !hasLabelPrefix(tabs[i] as Tab, texts[i] as string, 3),
+	);
+	if (bad.length === 0) return 3;
+	return `mixed or invalid inactive texts: ${bad.map((i) => JSON.stringify(texts[i])).join(", ")}`;
+}
+
+/** `key:` followed by a prefix of the label at least `min` chars long (or the whole label). */
+function hasLabelPrefix(tab: Tab, text: string, min: number): boolean {
+	const head = `${tab.key}:`;
+	if (!text.startsWith(head)) return false;
+	let prefix = text.slice(head.length);
+	if (prefix.endsWith("…")) prefix = prefix.slice(0, -1);
+	return (
+		tab.label.startsWith(prefix) &&
+		prefix.length >= Math.min(min, tab.label.length)
+	);
+}
+
+describe("C7 — barWidth follows the contract formula", () => {
+	test("R7.3 barWidth pads each cell by one space each side and joins cells with one column (default padded)", async () => {
+		const { barWidth } = await load();
+		expect(barWidth(["ab", "c"])).toBe(8);
+		expect(barWidth(["ab", "c"], true)).toBe(8);
+		expect(barWidth(["abc"])).toBe(5);
+	});
+
+	test("R7.3 barWidth unpadded is the text widths plus one separator between cells", async () => {
+		const { barWidth } = await load();
+		expect(barWidth(["ab", "c"], false)).toBe(4);
+		expect(barWidth(["abc"], false)).toBe(3);
+	});
+
+	test("R7.3 barWidth of the full tab bar matches the reference formula, both modes", async () => {
+		const { TABS, barWidth } = await load();
+		const texts = (TABS as readonly Tab[]).map(full);
+		expect(barWidth(texts)).toBe(refBar(texts, true));
+		expect(barWidth(texts, false)).toBe(refBar(texts, false));
+	});
+});
+
+for (const screen of TAB_SCREENS) {
+	describe(`C7 — layoutTabs with "${screen}" active`, () => {
+		test(`R7.1 ${screen}: tier boundaries are ordered (tier3 min < unpadded full < padded full)`, async () => {
+			const { TABS } = await load();
+			const { W1, W2, W3 } = tierForms(TABS as readonly Tab[], screen);
+			expect(W3).toBeLessThan(W2);
+			expect(W2).toBeLessThan(W1);
+		});
+
+		test(`R7.1 ${screen}: at every width 0..full+5 the chosen tier is the first that fits`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1 } = tierForms(tabs, screen);
+			const wrong: string[] = [];
+			for (let w = 0; w <= W1 + 5; w++) {
+				const layout = await layoutAt(screen, w);
+				const got = classify(tabs, screen, layout);
+				const want = expectedTier(tabs, screen, w);
+				if (got !== want) {
+					wrong.push(
+						`available=${w}: want tier ${want}, got ${typeof got === "number" ? `tier ${got}` : got} ${JSON.stringify(layout)}`,
+					);
+				}
+			}
+			expect(wrong.slice(0, 5)).toEqual([]);
+		});
+
+		test(`R7.1 ${screen}: the tier changes at exactly the three boundaries`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1, W2, W3 } = tierForms(tabs, screen);
+			const changes: number[] = [];
+			let prev = classify(tabs, screen, await layoutAt(screen, 0));
+			for (let w = 1; w <= W1 + 5; w++) {
+				const cur = classify(tabs, screen, await layoutAt(screen, w));
+				if (cur !== prev) changes.push(w);
+				prev = cur;
+			}
+			expect(changes).toEqual([W3, W2, W1]);
+		});
+
+		test(`R7.1 ${screen}: at available = padded full width, tier 1 (every tab key:label, padded)`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1, fullTexts } = tierForms(tabs, screen);
+			expect(await layoutAt(screen, W1)).toEqual({
+				texts: fullTexts,
+				padded: true,
+			});
+		});
+
+		test(`R7.1 ${screen}: one column below padded full width, tier 2 (every tab key:label, unpadded)`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1, fullTexts } = tierForms(tabs, screen);
+			expect(await layoutAt(screen, W1 - 1)).toEqual({
+				texts: fullTexts,
+				padded: false,
+			});
+		});
+
+		test(`R7.1 ${screen}: at available = unpadded full width, still tier 2`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W2, fullTexts } = tierForms(tabs, screen);
+			expect(await layoutAt(screen, W2)).toEqual({
+				texts: fullTexts,
+				padded: false,
+			});
+		});
+
+		test(`R7.1 ${screen}: one column below unpadded full width, tier 3 (inactive tabs keep a >=3-char label prefix)`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W2 } = tierForms(tabs, screen);
+			expect(classify(tabs, screen, await layoutAt(screen, W2 - 1))).toBe(3);
+		});
+
+		test(`R7.1 ${screen}: at the narrowest tier-3 width, still tier 3`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W3 } = tierForms(tabs, screen);
+			expect(classify(tabs, screen, await layoutAt(screen, W3))).toBe(3);
+		});
+
+		test(`R7.1 ${screen}: one column below the narrowest tier-3 width, tier 4 (inactive tabs show key only)`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W3, min4 } = tierForms(tabs, screen);
+			const layout = await layoutAt(screen, W3 - 1);
+			expect(classify(tabs, screen, layout)).toBe(4);
+			expect(layout.texts).toEqual(min4);
+		});
+
+		test(`R7.1 ${screen}: at available = 0, tier 4`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			expect(classify(tabs, screen, await layoutAt(screen, 0))).toBe(4);
+		});
+
+		test(`R7.2 ${screen}: at every width the active tab shows its full key:label and every tab shows its key, in TABS order`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1 } = tierForms(tabs, screen);
+			const active = tabs.findIndex((t) => t.screen === screen);
+			const wrong: string[] = [];
+			for (let w = 0; w <= W1 + 5; w++) {
+				const { texts } = await layoutAt(screen, w);
+				if (texts.length !== tabs.length) {
+					wrong.push(`available=${w}: ${texts.length} texts`);
+					continue;
+				}
+				if (texts[active] !== full(tabs[active] as Tab)) {
+					wrong.push(
+						`available=${w}: active shows ${JSON.stringify(texts[active])}`,
+					);
+				}
+				tabs.forEach((t, i) => {
+					const s = texts[i] as string;
+					if (s !== t.key && !s.startsWith(`${t.key}:`)) {
+						wrong.push(
+							`available=${w}: tab ${t.key} shows ${JSON.stringify(s)}`,
+						);
+					}
+				});
+			}
+			expect(wrong.slice(0, 5)).toEqual([]);
+		});
+
+		test(`R7.3 ${screen}: at every width the rendered bar fits, unless even tier 4 cannot`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const { W1, min4 } = tierForms(tabs, screen);
+			const tier4Floor = refBar(min4, false);
+			const over: string[] = [];
+			for (let w = 0; w <= W1 + 5; w++) {
+				const layout = await layoutAt(screen, w);
+				const width = refBar(layout.texts, layout.padded);
+				if (width <= w) continue;
+				const tier = classify(tabs, screen, layout);
+				if (tier === 4 && tier4Floor > w) continue; // nothing can fit
+				over.push(
+					`available=${w}: rendered ${width} (tier ${tier}) ${JSON.stringify(layout)}`,
+				);
+			}
+			expect(over.slice(0, 5)).toEqual([]);
+		});
+
+		test(`R7.4 ${screen}: at available = 96 (100-column terminal minus 4) every inactive tab shows at least 3 label characters`, async () => {
+			const { TABS } = await load();
+			const tabs = TABS as readonly Tab[];
+			const layout = await layoutAt(screen, 96);
+			const short = tabs
+				.map((t, i) => ({ t, text: layout.texts[i] as string }))
+				.filter(({ t }) => t.screen !== screen)
+				.filter(({ t, text }) => !hasLabelPrefix(t, text ?? "", 3))
+				.map(({ text }) => text);
+			expect(short).toEqual([]);
+		});
+
+		test(`R7.4 ${screen}: at available = 96 the bar fits`, async () => {
+			const layout = await layoutAt(screen, 96);
+			expect(refBar(layout.texts, layout.padded)).toBeLessThanOrEqual(96);
+		});
+	});
+}

package/src/__tests__/blind/c8-text-width.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Blind tests — contract C8 (requirements R8.1, R8.2 as far as the contract
+ * reaches: measuring, truncating and padding in terminal cells).
+ *
+ * Written from requirements.md and architecture.md only.
+ */
+import { describe, expect, test } from "bun:test";
+
+const load = () => import("../../ui/text-width.js");
+
+const E_ACUTE = "é"; // e + COMBINING ACUTE ACCENT
+
+describe("C8 — displayWidth counts terminal cells", () => {
+	const cases: [string, string, number][] = [
+		["empty string", "", 0],
+		["ASCII", "hello", 5],
+		["ASCII with spaces and punctuation", "a b-c:d", 7],
+		["CJK (Japanese)", "日本語", 6],
+		["CJK (Chinese)", "中文", 4],
+		["Hangul", "한글", 4],
+		["emoji", "🎉", 2],
+		["emoji (U+2705)", "✅", 2],
+		["emoji in text", "a🔌b", 4],
+		["combining mark adds 0", E_ACUTE, 1],
+		["two combining marks add 0", "à́", 1],
+		["mixed row", `Plugins 🔌 日本 ${E_ACUTE}`, 7 + 1 + 2 + 1 + 4 + 1 + 1],
+	];
+
+	for (const [name, input, want] of cases) {
+		test(`R8.2 displayWidth(${name}) is ${want}`, async () => {
+			const { displayWidth } = await load();
+			expect(displayWidth(input)).toBe(want);
+		});
+	}
+});
+
+describe("C8 — truncate", () => {
+	test("R8.1 a string that fits is returned unchanged, with no ellipsis", async () => {
+		const { truncate } = await load();
+		expect(truncate("abc", 5)).toBe("abc");
+		expect(truncate("abcde", 5)).toBe("abcde");
+		expect(truncate("日本", 4)).toBe("日本");
+	});
+
+	const cuts: [string, string, number][] = [
+		["ASCII", "Enable auto-update checks", 10],
+		["CJK", "日本語テキスト", 5],
+		["CJK even width", "日本語テキスト", 6],
+		["emoji", "🎉🎉🎉🎉", 5],
+		["combining marks", `${E_ACUTE}${E_ACUTE}${E_ACUTE}${E_ACUTE}`, 3],
+		["mixed", "Plugins 🔌 日本語", 9],
+	];
+
+	for (const [name, input, width] of cuts) {
+		test(`R8.1 truncate(${name}, ${width}) fits the width and ends with …`, async () => {
+			const { truncate, displayWidth } = await load();
+			const out = truncate(input, width);
+			expect(displayWidth(out)).toBeLessThanOrEqual(width);
+			expect(out.endsWith("…")).toBe(true);
+		});
+
+		test(`R8.1 truncate(${name}, ${width}) keeps a prefix of the original before the …`, async () => {
+			const { truncate } = await load();
+			const out = truncate(input, width);
+			expect(input.startsWith(out.slice(0, -1))).toBe(true);
+		});
+
+		test(`R8.1 truncate(${name}, ${width}) does not over-cut (uses at least width-1 cells)`, async () => {
+			// A wide glyph may leave one cell unused; more than that throws text away.
+			const { truncate, displayWidth } = await load();
+			expect(displayWidth(truncate(input, width))).toBeGreaterThanOrEqual(
+				width - 1,
+			);
+		});
+	}
+
+	test("R8.1 truncate to width 1 leaves just the ellipsis", async () => {
+		const { truncate } = await load();
+		expect(truncate("abcdef", 1)).toBe("…");
+	});
+
+	test("R8.1 truncate of an ASCII string one cell too long ends in …, width exact", async () => {
+		const { truncate } = await load();
+		expect(truncate("abcdef", 5)).toBe("abcd…");
+	});
+});
+
+describe("C8 — padTo pads to exactly width cells", () => {
+	const pads: [string, string, number][] = [
+		["ASCII", "ab", 5],
+		["empty", "", 3],
+		["exact", "abc", 3],
+		["CJK", "日本", 6],
+		["emoji", "🎉", 4],
+		["combining", E_ACUTE, 4],
+		["too wide ASCII", "abcdefgh", 5],
+		["too wide CJK at an odd width", "日本語", 5],
+		["too wide emoji at an odd width", "🎉🎉🎉", 5],
+	];
+
+	for (const [name, input, width] of pads) {
+		test(`R8.2 padTo(${name}, ${width}) is exactly ${width} cells`, async () => {
+			const { padTo, displayWidth } = await load();
+			expect(displayWidth(padTo(input, width))).toBe(width);
+		});
+	}
+
+	test("R8.2 padTo pads with spaces on the right", async () => {
+		const { padTo } = await load();
+		expect(padTo("ab", 5)).toBe("ab   ");
+		expect(padTo("", 3)).toBe("   ");
+		expect(padTo("日本", 6)).toBe("日本  ");
+		expect(padTo("🎉", 4)).toBe("🎉  ");
+	});
+
+	test("R8.2 padTo leaves an exact-width string unchanged", async () => {
+		const { padTo } = await load();
+		expect(padTo("abc", 3)).toBe("abc");
+	});
+
+	test("R8.2 rows with emoji, CJK and combining marks padded to one width put a divider in one column", async () => {
+		const { padTo, displayWidth } = await load();
+		const rows = [
+			"plain row",
+			"Plugins 🔌",
+			"日本語の行",
+			`${E_ACUTE}clair`,
+			"✅ installed",
+			"a much longer row that must be cut to fit",
+		];
+		const lines = rows.map((r) => `${padTo(r, 20)}│value`);
+		const dividerCol = lines.map((l) =>
+			displayWidth(l.slice(0, l.indexOf("│"))),
+		);
+		expect(dividerCol).toEqual(rows.map(() => 20));
+	});
+});

package/src/__tests__/blind/c9-cli-tool-version.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Blind tests — contract C9 (requirement R9.3).
+ *
+ * Written from requirements.md and architecture.md only. Each test builds the
+ * on-disk shape a package manager leaves behind (a bin symlink into a global
+ * node_modules package) inside its own temp dir.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	chmodSync,
+	mkdirSync,
+	mkdtempSync,
+	realpathSync,
+	rmSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const load = () => import("../../services/cli-tool-version.js");
+
+const dirs: string[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0))
+		rmSync(dir, { recursive: true, force: true });
+});
+
+function temp(): string {
+	// realpath so relative symlinks are computed against the real location.
+	const dir = realpathSync(
+		mkdtempSync(path.join(os.tmpdir(), "magus-blind-c9-")),
+	);
+	dirs.push(dir);
+	return dir;
+}
+
+function writeJson(file: string, value: unknown): void {
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify(value, null, 2));
+}
+
+function writeBin(file: string): void {
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, "#!/usr/bin/env node\nconsole.log('hi');\n");
+	chmodSync(file, 0o755);
+}
+
+function link(target: string, at: string, relative = false): void {
+	mkdirSync(path.dirname(at), { recursive: true });
+	symlinkSync(relative ? path.relative(path.dirname(at), target) : target, at);
+}
+
+describe("C9 — readPackageVersionForBin", () => {
+	test("R9.3 npm global layout: bin/magus -> ../lib/node_modules/magus-cli/bin/magus.js reads magus-cli's version", async () => {
+		const { readPackageVersionForBin } = await load();
+		const prefix = temp();
+		const pkg = path.join(prefix, "lib", "node_modules", "magus-cli");
+		writeJson(path.join(pkg, "package.json"), {
+			name: "magus-cli",
+			version: "7.3.0",
+		});
+		writeBin(path.join(pkg, "bin", "magus.js"));
+		link(
+			path.join(pkg, "bin", "magus.js"),
+			path.join(prefix, "bin", "magus"),
+			true,
+		);
+		expect(readPackageVersionForBin(path.join(prefix, "bin", "magus"))).toBe(
+			"7.3.0",
+		);
+	});
+
+	test("R9.3 bun global layout with a scoped package (Claude Code) reads its version", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		const pkg = path.join(
+			root,
+			".bun",
+			"install",
+			"global",
+			"node_modules",
+			"@anthropic-ai",
+			"claude-code",
+		);
+		writeJson(path.join(pkg, "package.json"), {
+			name: "@anthropic-ai/claude-code",
+			version: "2.1.300",
+		});
+		writeBin(path.join(pkg, "cli.js"));
+		link(path.join(pkg, "cli.js"), path.join(root, ".bun", "bin", "claude"));
+		expect(
+			readPackageVersionForBin(path.join(root, ".bun", "bin", "claude")),
+		).toBe("2.1.300");
+	});
+
+	test("R9.3 resolves a two-hop symlink chain before walking up", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		const pkg = path.join(root, "store", "node_modules", "@charmland", "crush");
+		writeJson(path.join(pkg, "package.json"), {
+			name: "@charmland/crush",
+			version: "0.9.1",
+		});
+		writeBin(path.join(pkg, "bin", "crush"));
+		link(path.join(pkg, "bin", "crush"), path.join(root, "hop", "crush"));
+		link(
+			path.join(root, "hop", "crush"),
+			path.join(root, "bin", "crush"),
+			true,
+		);
+		expect(readPackageVersionForBin(path.join(root, "bin", "crush"))).toBe(
+			"0.9.1",
+		);
+	});
+
+	test("R9.3 walks up from the binary's REAL location, not from where the symlink sits", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		// The symlink lives inside an unrelated package; that package must not answer.
+		writeJson(path.join(root, "host", "package.json"), {
+			name: "host",
+			version: "0.0.1",
+		});
+		const pkg = path.join(
+			root,
+			"global",
+			"node_modules",
+			"@charmland",
+			"crush",
+		);
+		writeJson(path.join(pkg, "package.json"), {
+			name: "@charmland/crush",
+			version: "0.9.1",
+		});
+		writeBin(path.join(pkg, "bin", "crush"));
+		link(
+			path.join(pkg, "bin", "crush"),
+			path.join(root, "host", "bin", "crush"),
+		);
+		expect(
+			readPackageVersionForBin(path.join(root, "host", "bin", "crush")),
+		).toBe("0.9.1");
+	});
+
+	test("R9.3 a binary given by its real path (no symlink) reads its package's version", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		const pkg = path.join(root, "node_modules", "tool");
+		writeJson(path.join(pkg, "package.json"), {
+			name: "tool",
+			version: "1.2.3",
+		});
+		writeBin(path.join(pkg, "dist", "bin", "tool.js"));
+		expect(
+			readPackageVersionForBin(path.join(pkg, "dist", "bin", "tool.js")),
+		).toBe("1.2.3");
+	});
+
+	test("R9.3 skips package.json files missing name or version and keeps walking up", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		const pkg = path.join(root, "node_modules", "tool");
+		writeJson(path.join(pkg, "package.json"), {
+			name: "tool",
+			version: "4.5.6",
+		});
+		// Nearer package.json files that do not qualify:
+		writeJson(path.join(pkg, "dist", "package.json"), { type: "module" });
+		writeJson(path.join(pkg, "dist", "esm", "package.json"), {
+			name: "tool-esm",
+		});
+		writeJson(path.join(pkg, "dist", "esm", "bin", "package.json"), {
+			version: "0.0.0",
+		});
+		writeBin(path.join(pkg, "dist", "esm", "bin", "tool.js"));
+		link(
+			path.join(pkg, "dist", "esm", "bin", "tool.js"),
+			path.join(root, "bin", "tool"),
+		);
+		expect(readPackageVersionForBin(path.join(root, "bin", "tool"))).toBe(
+			"4.5.6",
+		);
+	});
+
+	test("R9.3 the nearest qualifying package.json wins over an enclosing project's", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		writeJson(path.join(root, "package.json"), {
+			name: "workspace",
+			version: "9.9.9",
+		});
+		const pkg = path.join(root, "node_modules", "tool");
+		writeJson(path.join(pkg, "package.json"), {
+			name: "tool",
+			version: "1.0.0",
+		});
+		writeBin(path.join(pkg, "bin", "tool.js"));
+		expect(readPackageVersionForBin(path.join(pkg, "bin", "tool.js"))).toBe(
+			"1.0.0",
+		);
+	});
+
+	test("R9.3 returns null when no package.json with name and version is found", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		writeBin(path.join(root, "bin", "lonely"));
+		expect(
+			readPackageVersionForBin(path.join(root, "bin", "lonely")),
+		).toBeNull();
+	});
+
+	test("R9.3 returns null (does not throw) for a path that does not exist", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		expect(
+			readPackageVersionForBin(path.join(root, "bin", "missing")),
+		).toBeNull();
+	});
+
+	test("R9.3 returns null (does not throw) for a dangling symlink", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		link(path.join(root, "gone", "tool.js"), path.join(root, "bin", "tool"));
+		expect(readPackageVersionForBin(path.join(root, "bin", "tool"))).toBeNull();
+	});
+
+	test("R9.3 returns null (does not throw) when the only package.json is unreadable JSON", async () => {
+		const { readPackageVersionForBin } = await load();
+		const root = temp();
+		const pkg = path.join(root, "node_modules", "broken");
+		mkdirSync(pkg, { recursive: true });
+		writeFileSync(path.join(pkg, "package.json"), "{ not json");
+		writeBin(path.join(pkg, "bin", "broken.js"));
+		expect(
+			readPackageVersionForBin(path.join(pkg, "bin", "broken.js")),
+		).toBeNull();
+	});
+});