magus-cli 7.10.1 → 7.10.3

package/src/__tests__/blind/c19-probe-owner-version-shadow.test.ts

@@ -0,0 +1,389 @@
+/**
+ * Blind tests, contract C19: a KEPT row names who installed the file, shows its
+ * version whenever it can be read, drives a self-updating standalone installer
+ * (uv's receipt), and reports a newer copy hidden later on PATH.
+ *
+ * Written from the spec only, through a scripted fake `ToolProbeIO`.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	type ExecResult,
+	type FetchJsonResult,
+	type ToolProbeIO,
+	classifyTool,
+	probeTool,
+} from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+
+interface FakeSetup {
+	exec?: Record<string, Partial<ExecResult>>;
+	fetch?: Record<string, FetchJsonResult>;
+	files?: Record<string, string>;
+	real?: Record<string, string>;
+	onPath?: Record<string, string>;
+	allOnPath?: Record<string, string[]>;
+	env?: Record<string, string>;
+	noAll?: boolean;
+}
+
+const HOME = "/home/u";
+
+function fakeIO(
+	setup: FakeSetup,
+): ToolProbeIO & { calls: string[]; reads: string[] } {
+	const calls: string[] = [];
+	const reads: string[] = [];
+	const io: ToolProbeIO & { calls: string[]; reads: string[] } = {
+		calls,
+		reads,
+		exec: async (command) => {
+			const key = [command.cmd, ...command.args].join(" ");
+			calls.push(key);
+			const h = setup.exec?.[key];
+			if (h === undefined) {
+				return {
+					code: null,
+					stdout: "",
+					stderr: "",
+					timedOut: false,
+					missing: true,
+				};
+			}
+			return {
+				code: 0,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				missing: false,
+				...h,
+			};
+		},
+		fetchJson: async (url) =>
+			setup.fetch?.[url] ?? { ok: false, reason: "returned 404" },
+		readJson: async (file) => {
+			reads.push(file);
+			const t = setup.files?.[file];
+			if (t === undefined) return null;
+			try {
+				return JSON.parse(t);
+			} catch {
+				return null;
+			}
+		},
+		readText: async (file) => setup.files?.[file] ?? null,
+		readlink: async () => null,
+		realpath: async (file) => setup.real?.[file] ?? null,
+		resolveExecutable: async (name) => setup.onPath?.[name] ?? null,
+		env: setup.env ?? {},
+		homedir: HOME,
+	};
+	if (!setup.noAll) {
+		io.resolveAllExecutables = async (name: string) =>
+			setup.allOnPath?.[name] ??
+			(setup.onPath?.[name] !== undefined
+				? [setup.onPath[name] as string]
+				: []);
+	}
+	return io;
+}
+
+const PREFIX = "/opt/homebrew";
+const BREW_PREFIX_OK: Record<string, Partial<ExecResult>> = {
+	"brew --prefix": { stdout: `${PREFIX}\n` },
+};
+const CELLAR = { "/opt/homebrew/Cellar": "/opt/homebrew/Cellar" };
+
+const UV: BinRequirement = { name: "uv", via: "brew", formula: "uv" };
+const UV_FILE = "/home/u/.local/bin/uv";
+const UV_RECEIPT_PATH = "/home/u/.config/uv/uv-receipt.json";
+const uvReceipt = (prefix = "/home/u/.local/bin", version = "0.11.15") =>
+	JSON.stringify({
+		binaries: ["uv", "uvx"],
+		install_prefix: prefix,
+		source: { app_name: "uv", name: "uv", owner: "astral-sh" },
+		version,
+	});
+const pypi = (v: string): Record<string, FetchJsonResult> => ({
+	"https://pypi.org/pypi/uv/json": { ok: true, body: { info: { version: v } } },
+});
+
+function uvWorld(opts: {
+	latest?: string;
+	receiptPrefix?: string;
+	receiptAt?: string;
+	env?: Record<string, string>;
+	extra?: Partial<FakeSetup>;
+}): FakeSetup {
+	return {
+		onPath: { uv: UV_FILE },
+		real: { [UV_FILE]: UV_FILE },
+		files: {
+			[opts.receiptAt ?? UV_RECEIPT_PATH]: uvReceipt(opts.receiptPrefix),
+		},
+		fetch: pypi(opts.latest ?? "0.13.0"),
+		env: opts.env ?? {},
+		...opts.extra,
+	};
+}
+
+describe("C19 A: uv's own installer is a driven owner", () => {
+	test("1. receipt, PyPI newer: managed, upgrade, uv self update", async () => {
+		const f = await probeTool(UV, fakeIO(uvWorld({})));
+		expect(f.installed).toBe("0.11.15");
+		expect(f.managed).toBe(true);
+		expect(f.latest).toBe("0.13.0");
+		expect(f.upgradeCommand).toEqual({ cmd: "uv", args: ["self", "update"] });
+		const s = classifyTool(UV, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("0.13.0");
+	});
+
+	test("2. PyPI equals installed: current", async () => {
+		const f = await probeTool(UV, fakeIO(uvWorld({ latest: "0.11.15" })));
+		expect(classifyTool(UV, f).state).toBe("current");
+	});
+
+	test("3. pinned spec: upgrade to the pin with a versioned command", async () => {
+		const spec: BinRequirement = { ...UV, version: "0.12.0" };
+		const f = await probeTool(spec, fakeIO(uvWorld({})));
+		expect(f.upgradeCommand).toEqual({
+			cmd: "uv",
+			args: ["self", "update", "0.12.0"],
+		});
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("0.12.0");
+	});
+
+	test("4. receipt for a different install_prefix is ignored", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(uvWorld({ receiptPrefix: "/somewhere/else" })),
+		);
+		expect(f.managed).not.toBe(true);
+		expect(f.upgradeCommand).toBeUndefined();
+		expect(classifyTool(UV, f).state).not.toBe("upgrade");
+	});
+
+	test("5. XDG_CONFIG_HOME relocates the receipt", async () => {
+		const io = fakeIO(
+			uvWorld({
+				env: { XDG_CONFIG_HOME: "/xdg" },
+				extra: {
+					// a decoy at the default place must not be the one used
+					files: {
+						"/xdg/uv/uv-receipt.json": uvReceipt(),
+						[UV_RECEIPT_PATH]: uvReceipt("/home/u/.local/bin", "9.9.9"),
+					},
+				},
+			}),
+		);
+		const f = await probeTool(UV, io);
+		expect(f.installed).toBe("0.11.15");
+		expect(f.managed).toBe(true);
+		expect(io.reads).toContain("/xdg/uv/uv-receipt.json");
+		expect(io.reads).not.toContain(UV_RECEIPT_PATH);
+	});
+
+	test("6. receipt of an installer magus cannot update: external, versioned, named", async () => {
+		const spec: BinRequirement = { name: "ruff", via: "brew", formula: "ruff" };
+		const file = "/home/u/.local/bin/ruff";
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				onPath: { ruff: file },
+				real: { [file]: file },
+				files: {
+					"/home/u/.config/ruff/ruff-receipt.json": JSON.stringify({
+						binaries: ["ruff"],
+						install_prefix: "/home/u/.local/bin",
+						source: { app_name: "ruff", name: "ruff", owner: "astral-sh" },
+						version: "0.9.1",
+					}),
+				},
+				exec: BREW_PREFIX_OK,
+			}),
+		);
+		expect(f.installed).toBe("0.9.1");
+		expect(f.upgradeCommand).toBeUndefined();
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by ruff's own installer");
+	});
+});
+
+describe("C19 B: KEPT notes name who installed it", () => {
+	const spec = (
+		name: string,
+		extra: Partial<BinRequirement> = {},
+	): BinRequirement => ({
+		name,
+		via: "brew",
+		formula: name,
+		...extra,
+	});
+	const world = (
+		name: string,
+		file: string,
+		env: Record<string, string> = {},
+	): FakeSetup => ({
+		onPath: { [name]: file },
+		real: { [file]: file, ...CELLAR },
+		exec: BREW_PREFIX_OK,
+		env,
+	});
+
+	test("7. Homebrew cask", async () => {
+		const sp = spec("madbench");
+		const file = "/opt/homebrew/Caskroom/madbench/0.43.2/madbench";
+		const f = await probeTool(sp, fakeIO(world("madbench", file)));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by a Homebrew cask");
+	});
+
+	test("8a. cargo bin under the home directory", async () => {
+		const sp = spec("rg");
+		const f = await probeTool(sp, fakeIO(world("rg", "/home/u/.cargo/bin/rg")));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by cargo");
+	});
+
+	test("8b. cargo bin under CARGO_HOME", async () => {
+		const sp = spec("rg");
+		const f = await probeTool(
+			sp,
+			fakeIO(world("rg", "/opt/cargo/bin/rg", { CARGO_HOME: "/opt/cargo" })),
+		);
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by cargo");
+	});
+
+	test("9. unrecognised place, never says 'outside'", async () => {
+		const sp = spec("foo");
+		const f = await probeTool(
+			sp,
+			fakeIO(world("foo", "/home/u/tools/bin/foo")),
+		);
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by an installer magus does not update");
+		expect(s.note ?? "").not.toContain("outside");
+	});
+
+	test("10. pinned spec with a cargo file", async () => {
+		const sp = spec("rg", { version: "1.0.0" });
+		const f = await probeTool(sp, fakeIO(world("rg", "/home/u/.cargo/bin/rg")));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("unknown");
+		expect(s.note).toBe(
+			"installed by cargo, so magus cannot move it to the pin 1.0.0",
+		);
+	});
+});
+
+describe("C19 C: operating-system programs show their version", () => {
+	const zsh: BinRequirement = { name: "zsh", via: "brew", formula: "zsh" };
+	const world = (zshExec?: Partial<ExecResult>): FakeSetup => ({
+		onPath: { zsh: "/bin/zsh" },
+		real: { "/bin/zsh": "/bin/zsh", ...CELLAR },
+		exec: {
+			...BREW_PREFIX_OK,
+			...(zshExec ? { "/bin/zsh --version": zshExec } : {}),
+		},
+	});
+
+	test("11. version read from --version", async () => {
+		const f = await probeTool(
+			zsh,
+			fakeIO(world({ stdout: "zsh 5.9 (arm64-apple-darwin25.0)\n" })),
+		);
+		expect(f.installed).toBe("5.9");
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+
+	test("12a. --version exits non-zero: still external, installed null", async () => {
+		const f = await probeTool(
+			zsh,
+			fakeIO(world({ code: 1, stdout: "", stderr: "" })),
+		);
+		expect(f.installed).toBeNull();
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+
+	test("12b. --version missing: still external, installed null", async () => {
+		const f = await probeTool(zsh, fakeIO(world()));
+		expect(f.installed).toBeNull();
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+});
+
+describe("C19 D: a newer copy later on PATH is reported", () => {
+	const BREW_BIN = "/opt/homebrew/bin/uv";
+	const cellarFile = (v: string) => `/opt/homebrew/Cellar/uv/${v}/bin/uv`;
+	const world = (second: string, secondReal: string): FakeSetup =>
+		uvWorld({
+			extra: {
+				allOnPath: { uv: [UV_FILE, second] },
+				real: { [UV_FILE]: UV_FILE, [second]: secondReal, ...CELLAR },
+				exec: BREW_PREFIX_OK,
+				env: { HOMEBREW_PREFIX: PREFIX },
+			},
+		});
+	const NOTE =
+		"Homebrew also has 0.13.0, unused: ~/.local/bin comes first on PATH";
+
+	test("13. newer Homebrew copy: pathDir, otherCopies, shadowed", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(world(BREW_BIN, cellarFile("0.13.0"))),
+		);
+		expect(f.pathDir).toBe("~/.local/bin");
+		expect(f.otherCopies).toEqual([
+			{ owner: "Homebrew", version: "0.13.0", dir: "/opt/homebrew/bin" },
+		]);
+		expect(classifyTool(UV, f).shadowed).toBe(NOTE);
+	});
+
+	test("14. older later copy: listed, not shadowed", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(world(BREW_BIN, cellarFile("0.10.0"))),
+		);
+		expect(f.otherCopies).toEqual([
+			{ owner: "Homebrew", version: "0.10.0", dir: "/opt/homebrew/bin" },
+		]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("15. a symlink to the running file is not another copy", async () => {
+		const f = await probeTool(UV, fakeIO(world("/usr/local/bin/uv", UV_FILE)));
+		expect(f.otherCopies ?? []).toEqual([]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("16. IO without resolveAllExecutables: nothing reported, nothing throws", async () => {
+		const w = world(BREW_BIN, cellarFile("0.13.0"));
+		w.noAll = true;
+		const f = await probeTool(UV, fakeIO(w));
+		expect(f.otherCopies ?? []).toEqual([]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("17. shadowed is set on a current row too", async () => {
+		const w = world(BREW_BIN, cellarFile("0.13.0"));
+		w.fetch = pypi("0.11.15");
+		const f = await probeTool(UV, fakeIO(w));
+		const s = classifyTool(UV, f);
+		expect(s.state).toBe("current");
+		expect(s.shadowed).toBe(NOTE);
+	});
+});

package/src/__tests__/cli-tools-adapter.test.ts

@@ -214,7 +214,7 @@ describe("buildToolRow — which installer a catalogue row is judged through", (
 		expect(row.status?.reason).toBe("not-managed");
 		// No path and no installer directory: the user acts on neither.
 		expect(row.status?.note).toBe(
-			"installed outside npm, so magus leaves it as is",
+			"installed by an installer magus does not update",
 		);
 		expect(row.status?.note).not.toContain("/");
 		// Enter still follows how it IS installed (pnpm).

package/src/__tests__/tool-probe.test.ts

@@ -238,7 +238,7 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 			}),
 		);
 		expect(s).toMatchObject({ state: "external", reason: "not-managed" });
-		expect(s.note).toBe("installed outside npm, so magus leaves it as is");
+		expect(s.note).toBe("installed by an installer magus does not update");
 		expect(s.note).not.toContain("/");
 	});
 
@@ -248,13 +248,13 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 		).toMatchObject({ state: "unknown", reason: "not-managed" });
 	});
 
-	test("6. brew is named as the user knows it", () => {
-		expect(
-			classifyTool(
-				spec({ via: "brew" }),
-				facts({ managed: false, behind: true }),
-			).note,
-		).toBe("installed outside Homebrew, so magus leaves it as is");
+	test("6. the note names who DID install it, never the spec's installer", () => {
+		const note = classifyTool(
+			spec({ via: "brew" }),
+			facts({ managed: false, behind: true, ownerName: "cargo" }),
+		).note;
+		expect(note).toBe("installed by cargo");
+		expect(note).not.toContain("Homebrew");
 	});
 
 	test("7. held back → unknown, with the hold as the note", () => {

package/src/cli/update-view.ts

@@ -435,6 +435,16 @@ function pluginDetail(item: PluginUpdateItem): string {
  * pin is shown only when there is one.
  */
 function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
+	const detail = binStateDetail(item, plan);
+	// A newer copy later on PATH is the one thing here only the user can settle.
+	return item.shadowed
+		? [detail, fg(brand.warning, `⚠ ${item.shadowed}`)]
+				.filter(Boolean)
+				.join("  ")
+		: detail;
+}
+
+function binStateDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 	const spec = plan.binSpecs.get(item.name);
 	// Rendered for the reader's eyes only — this row says what WILL run, while
 	// applyBins runs the argv itself. Same builder, so they cannot differ.
@@ -458,6 +468,10 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 				item.adopted ? `  ${dim(`(${item.adopted})`)}` : ""
 			}`;
 		case "external":
+			// Kept as is: a missing version is not a finding, so no "—" stands in.
+			return [item.installed, item.note ? dim(`(${item.note})`) : ""]
+				.filter(Boolean)
+				.join("  ");
 		case "unknown":
 			return `${item.installed ?? "—"}${
 				item.note ? `  ${dim(`(${item.note})`)}` : ""