magus-cli 7.10.0 → 7.10.2

package/src/__tests__/blind/c18-probe-adopts-homebrew-keg.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Blind tests, contract C18: Homebrew owns an installed tool whose file lies
+ * in `<brew prefix>/Cellar/<short name>/<version>/...`, whatever installer the
+ * spec declares. A pinned spec is not adopted (brew takes no version).
+ *
+ * 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>;
+	env?: Record<string, string>;
+}
+
+function fakeIO(setup: FakeSetup): ToolProbeIO & { calls: string[] } {
+	const calls: string[] = [];
+	return {
+		calls,
+		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) => {
+			const r = setup.fetch?.[url];
+			return r ?? { ok: false, reason: "returned 404" };
+		},
+		readJson: async (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: "/Users/j",
+	};
+}
+
+const PREFIX = "/opt/homebrew";
+const CELLAR = { "/opt/homebrew/Cellar": "/opt/homebrew/Cellar" };
+const BREW_PREFIX_OK: Record<string, Partial<ExecResult>> = {
+	"brew --prefix": { stdout: `${PREFIX}\n` },
+};
+
+const OUTDATED_NONE = JSON.stringify({ formulae: [], casks: [] });
+const outdatedBehind = (name: string, installed: string, current: string) =>
+	JSON.stringify({
+		formulae: [
+			{
+				name,
+				installed_versions: [installed],
+				current_version: current,
+				pinned: false,
+			},
+		],
+		casks: [],
+	});
+
+/** A tool whose PATH entry resolves into a Homebrew keg. */
+function kegWorld(
+	bin: string,
+	short: string,
+	version: string,
+	outdatedKey: string,
+	outdatedStdout: string,
+	extraExec: Record<string, Partial<ExecResult>> = BREW_PREFIX_OK,
+): FakeSetup {
+	const file = `${PREFIX}/Cellar/${short}/${version}/bin/${bin}`;
+	const onPath = `${PREFIX}/bin/${bin}`;
+	return {
+		onPath: { [bin]: onPath },
+		real: { [onPath]: file, [file]: file, ...CELLAR },
+		exec: {
+			...extraExec,
+			[`brew outdated --json=v2 ${outdatedKey}`]: { stdout: outdatedStdout },
+		},
+	};
+}
+
+const MNEMEX: BinRequirement = {
+	name: "mnemex",
+	via: "brew",
+	formula: "madappgang/tap/mnemex",
+};
+
+describe("C18 case 1: tap formula, brew spec, current", () => {
+	test("managed, version from the keg, state current", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(
+				kegWorld(
+					"mnemex",
+					"mnemex",
+					"0.36.2",
+					"madappgang/tap/mnemex",
+					OUTDATED_NONE,
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("0.36.2");
+		expect(classifyTool(MNEMEX, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 2: tap formula behind", () => {
+	test("state upgrade, latest from brew", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(
+				kegWorld(
+					"mnemex",
+					"mnemex",
+					"0.36.2",
+					"madappgang/tap/mnemex",
+					outdatedBehind("madappgang/tap/mnemex", "0.36.2", "0.37.0"),
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.latest).toBe("0.37.0");
+		expect(classifyTool(MNEMEX, f).state).toBe("upgrade");
+	});
+});
+
+describe("C18 case 3: bun spec, file in a Homebrew keg", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	test("adopted by brew: brew upgrade command, never bun", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld(
+					"claudish",
+					"claudish",
+					"10.5.0",
+					"claudish",
+					outdatedBehind("claudish", "10.5.0", "10.6.0"),
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("10.5.0");
+		expect(f.latest).toBe("10.6.0");
+		expect(f.upgradeCommand).toEqual({
+			cmd: "brew",
+			args: ["upgrade", "claudish"],
+		});
+		expect(f.upgradeCommand?.cmd).not.toBe("bun");
+		expect(classifyTool(spec, f).state).toBe("upgrade");
+	});
+});
+
+describe("C18 case 4: npm spec, file in a Homebrew keg", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "npm",
+		package: "claudish",
+	};
+	test("current, upgrade command is brew", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld("claudish", "claudish", "10.5.0", "claudish", OUTDATED_NONE),
+			),
+		);
+		expect(f.upgradeCommand?.cmd).toBe("brew");
+		expect(classifyTool(spec, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 5: a pinned spec is not adopted by Homebrew", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+		version: "10.4.0",
+	};
+	test("unknown, no brew command, note mentions the pin", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld(
+					"claudish",
+					"claudish",
+					"10.5.0",
+					"claudish",
+					outdatedBehind("claudish", "10.5.0", "10.6.0"),
+				),
+			),
+		);
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("unknown");
+		expect(s.note ?? "").toContain("10.4.0");
+	});
+});
+
+describe("C18 case 6: a directory merely named Cellar is not Homebrew's", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	test("not adopted: external, no upgrade command", async () => {
+		const file = "/Users/u/projects/Cellar/claudish/1.0.0/bin/claudish";
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				onPath: { claudish: file },
+				real: { [file]: file, ...CELLAR },
+				exec: BREW_PREFIX_OK,
+			}),
+		);
+		expect(f.managed).not.toBe(true);
+		expect(f.upgradeCommand).toBeUndefined();
+		expect(classifyTool(spec, f).state).toBe("external");
+	});
+});
+
+describe("C18 case 7: Homebrew unavailable", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	const world = (exec: Record<string, Partial<ExecResult>>): FakeSetup =>
+		kegWorld(
+			"claudish",
+			"claudish",
+			"10.5.0",
+			"claudish",
+			outdatedBehind("claudish", "10.5.0", "10.6.0"),
+			exec,
+		);
+	test("brew --prefix missing: not adopted", async () => {
+		const f = await probeTool(spec, fakeIO(world({})));
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		expect(classifyTool(spec, f).state).not.toBe("upgrade");
+	});
+	test("brew --prefix exits non-zero: not adopted", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(world({ "brew --prefix": { code: 1, stderr: "boom" } })),
+		);
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		expect(classifyTool(spec, f).state).not.toBe("upgrade");
+	});
+});
+
+describe("C18 case 8: a non-tap brew spec still works", () => {
+	test("tmux current, installed 3.8", async () => {
+		const spec: BinRequirement = {
+			name: "tmux",
+			via: "brew",
+			formula: "tmux",
+			check: "tmux -V",
+		};
+		const f = await probeTool(
+			spec,
+			fakeIO(kegWorld("tmux", "tmux", "3.8", "tmux", OUTDATED_NONE)),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("3.8");
+		expect(classifyTool(spec, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 9: bun ownership still wins over a brew spec", () => {
+	test("file in bun's global tree: bun command, current", async () => {
+		const root = "/Users/j/.bun/install/global/node_modules";
+		const pkgDir = `${root}/mnemex`;
+		const file = `${pkgDir}/dist/index.js`;
+		const onPath = "/Users/j/.bun/bin/mnemex";
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO({
+				env: { HOMEBREW_PREFIX: PREFIX },
+				onPath: { mnemex: onPath },
+				real: {
+					[onPath]: file,
+					[file]: file,
+					[pkgDir]: pkgDir,
+					[root]: root,
+					...CELLAR,
+				},
+				files: {
+					[`${pkgDir}/package.json`]: JSON.stringify({
+						name: "mnemex",
+						version: "0.36.2",
+					}),
+				},
+				exec: BREW_PREFIX_OK,
+				fetch: {
+					"https://registry.npmjs.org/-/package/mnemex/dist-tags": {
+						ok: true,
+						body: { latest: "0.36.2" },
+					},
+				},
+			}),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.upgradeCommand?.cmd).toBe("bun");
+		expect(classifyTool(MNEMEX, f).state).toBe("current");
+	});
+});

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

@@ -197,7 +197,7 @@ describe("buildToolRow — which installer a catalogue row is judged through", (
 		expect(row.installCommand).toEqual(cliToolInstall(codex));
 	});
 
-	test("detected pnpm → the catalogue's via, and a not-managed row naming the real path", () => {
+	test("detected pnpm → the catalogue's via, and a not-managed row in the user's terms", () => {
 		const opencode = catalogue("opencode");
 		const install = { primary: "pnpm" as const, all: ["pnpm" as const] };
 		const spec = specForCatalogTool(opencode, null, install);
@@ -210,8 +210,11 @@ describe("buildToolRow — which installer a catalogue row is judged through", (
 			owner: "npm (root /Users/j/.local/lib/node_modules)",
 		});
 		const row = buildToolRow(opencode, spec, f, install);
+		expect(row.status?.state).toBe("external");
 		expect(row.status?.reason).toBe("not-managed");
-		expect(row.status?.note).toContain("/Users/j/.local/share/pnpm/");
+		// No path and no installer directory: the user acts on neither.
+		expect(row.status?.note).toBe("installed outside npm");
+		expect(row.status?.note).not.toContain("/");
 		// Enter still follows how it IS installed (pnpm).
 		expect(row.updateCommand?.cmd).toBe("pnpm");
 	});
@@ -249,16 +252,28 @@ describe("cliToolStatusText — the row's words", () => {
 			primary: "npm",
 			all: ["npm"],
 		});
-		const f = facts("crush", { managed: false, owner: "npm (root /l)" });
+		const f = facts("crush", { managed: null });
 		const row = buildToolRow(tool, spec, f);
 		const text = cliToolStatusText(row);
 		expect(text.tone).toBe("warning");
-		expect(text.suffix).toBe(" ? not managed by npm");
-		// The note (with its path) is for the detail pane's "Why", not the row.
+		expect(text.suffix).toBe(" ? owner not known");
+		// The note is for the detail pane's "Why", not the row.
 		expect(row.status?.note).toBe(classifyTool(spec, f).note);
 		expect(text.suffix).not.toContain("/");
 	});
 
+	test("external renders muted, naming the installer it is outside of", () => {
+		const tool = catalogue("crush");
+		const spec = specForCatalogTool(tool, null, {
+			primary: "npm",
+			all: ["npm"],
+		});
+		const row = buildToolRow(tool, spec, facts("crush", { managed: false }));
+		const text = cliToolStatusText(row);
+		expect(text.tone).toBe("muted");
+		expect(text.suffix).toBe(" · outside npm");
+	});
+
 	test("upgrade names the target once, with one v", () => {
 		const tool = catalogue("mnemex");
 		const spec = specForCatalogTool(tool, null, {
@@ -287,12 +302,14 @@ describe("countToolRows — header counts from states", () => {
 		const rows = [
 			buildToolRow(tool, spec, facts("mnemex", { behind: false })),
 			buildToolRow(tool, spec, facts("mnemex", { behind: true })),
+			buildToolRow(tool, spec, facts("mnemex", { managed: null })),
+			// Another installer's: installed, and not "unverified".
 			buildToolRow(tool, spec, facts("mnemex", { managed: false })),
 			buildToolRow(tool, spec, facts("mnemex", { present: false })),
 			buildToolRow(tool, spec, undefined),
 		];
 		expect(countToolRows(rows)).toEqual({
-			installed: 3,
+			installed: 4,
 			updates: 1,
 			unverified: 1,
 		});

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

@@ -226,7 +226,7 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 		);
 	});
 
-	test("6. not managed → unknown, naming both paths", () => {
+	test("6. not managed → external, in the user's terms", () => {
 		const s = classifyTool(
 			spec({ name: "crush" }),
 			facts({
@@ -237,16 +237,24 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 				owner: "npm (root /Users/j/.local/lib/node_modules)",
 			}),
 		);
-		expect(s).toMatchObject({ state: "unknown", reason: "not-managed" });
-		expect(s.note).toContain("/Users/j/.nvm/versions/node/v24.14.0");
-		expect(s.note).toContain("npm (root /Users/j/.local/lib/node_modules)");
-		expect(s.note).toContain("second copy");
+		expect(s).toMatchObject({ state: "external", reason: "not-managed" });
+		expect(s.note).toBe("installed outside npm");
+		expect(s.note).not.toContain("/");
 	});
 
-	test("6. managed === null (owner undeterminable) is also a veto", () => {
+	test("6. managed === null (owner undeterminable) is also a veto, as unknown", () => {
 		expect(
-			classifyTool(spec(), facts({ managed: null, behind: true })).reason,
-		).toBe("not-managed");
+			classifyTool(spec(), facts({ managed: null, behind: true })),
+		).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");
 	});
 
 	test("7. held back → unknown, with the hold as the note", () => {
@@ -364,7 +372,7 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 		];
 		for (const [s, f] of cases) {
 			const status = classifyTool(spec(s), facts(f));
-			expect(["unknown", "upgrade"]).toContain(status.state);
+			expect(["unknown", "upgrade", "external"]).toContain(status.state);
 			expect(status.note?.length ?? 0).toBeGreaterThan(0);
 		}
 	});
@@ -866,11 +874,11 @@ describe("probeTool — ownership decides managed", () => {
 		const [f] = await probeTools([hostile], io);
 		expect(io.calls).toEqual(["npm root -g"]);
 		expect(f?.installed).toBeNull();
-		// Cannot tell ⇒ unknown, so it is reported and never applied. The file
-		// is outside npm's tree, so the reason is ownership (R9.9), not the
-		// unread version that follows from it.
+		// Another installer's file ⇒ external, so it is reported and never
+		// applied. The reason is ownership (R9.9), not the unread version that
+		// follows from it.
 		expect(classifyTool(hostile, f!)).toMatchObject({
-			state: "unknown",
+			state: "external",
 			reason: "not-managed",
 		});
 

package/src/__tests__/update-plan.test.ts

@@ -502,7 +502,7 @@ describe("planIsBehind — the --check gate", () => {
 		const p = plan({
 			bins: planBinUpdates(
 				[{ name: "crush", via: "npm", sources: [] }],
-				[toolFacts("crush", { managed: false })],
+				[toolFacts("crush", { managed: null })],
 			),
 		});
 		expect(p.bins[0]!.action).toBe("unknown");
@@ -510,6 +510,19 @@ describe("planIsBehind — the --check gate", () => {
 		expect(planIsBehind(p)).toBe(false);
 	});
 
+	test("an EXTERNAL tool (another installer's) is no work, and not unknown", () => {
+		const p = plan({
+			bins: planBinUpdates(
+				[{ name: "crush", via: "npm", sources: [] }],
+				[toolFacts("crush", { managed: false, behind: true })],
+			),
+		});
+		expect(p.bins[0]!.action).toBe("external");
+		expect(planHasWork(p)).toBe(false);
+		expect(planIsBehind(p)).toBe(false);
+		expect(summarizePlan(p)).toMatchObject({ unknownTools: 0, kept: 1 });
+	});
+
 	test("a MISSING binary does fail the gate", () => {
 		const p = plan({
 			bins: planBinUpdates(
@@ -946,11 +959,13 @@ describe("planHasWork / summarizePlan", () => {
 					{ name: "crush", via: "npm", sources: [] },
 					{ name: "claude", via: "npm", sources: [] },
 					{ name: "tmux", via: "brew", sources: [] },
+					{ name: "zsh", via: "brew", sources: [] },
 				],
 				[
-					toolFacts("crush", { managed: false }),
-					toolFacts("claude", { managed: false }),
+					toolFacts("crush", { managed: null }),
+					toolFacts("claude", { managed: null }),
 					toolFacts("tmux", { behind: false }),
+					toolFacts("zsh", { managed: false }),
 				],
 			),
 		});
@@ -959,6 +974,7 @@ describe("planHasWork / summarizePlan", () => {
 			unknownTools: 2,
 			unknown: 3,
 			current: 1,
+			kept: 1,
 		});
 	});
 });

package/src/cli/update-view.ts

@@ -90,6 +90,7 @@ type ActionKey =
 	| "refresh"
 	| "stale-load"
 	| "remove"
+	| "external"
 	| "unknown";
 
 const ACTIONS: Record<ActionKey, ActionStyle> = {
@@ -111,6 +112,9 @@ const ACTIONS: Record<ActionKey, ActionStyle> = {
 	// dead weight Claude Code refuses to load, and the row is work, not a shrug.
 	// The plugin table shows the group's DEPRECATED chip, not this label.
 	remove: { glyph: "✗", label: "REMOVE", color: brand.danger },
+	// A tool another installer put on PATH. Settled, so chrome like CURRENT,
+	// and the same word the summary already prints for settled rows.
+	external: { glyph: "=", label: "KEPT", color: brand.muted, chrome: true },
 	// Warning, not danger: "cannot tell" is not a failure, and red UNKNOWN read
 	// as "broken". The summary line and the TUI already use warning for it.
 	unknown: { glyph: "?", label: "UNKNOWN", color: brand.warning },
@@ -453,6 +457,11 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 				// plain one reads identically to before.
 				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})`)}` : ""
@@ -927,15 +936,18 @@ function worktreeLabel(names: readonly string[]): string {
  * The worktree rows: after a setup (`results`), one `✓` line for every
  * worktree set up and a `✗` line for each failure; on a read-only run
  * (`results` null), one `⚠` line for the ones `magus update` would set up.
- * A worktree that needs a choice gets its own `⚠` line either way. Empty for
- * an empty list: a repository with nothing to say prints nothing.
+ *
+ * A worktree that needs a choice gets no line. magus cannot set it up from
+ * here, and a line per worktree on every run is noise about folders the user
+ * may never open: old branches, agent and bench worktrees. The `setup`
+ * plugin says so when Claude Code starts in one, and magus run there asks.
+ * Empty when there is nothing to say, blank line included.
  */
 export function worktreeLines(
 	worktrees: readonly UnsetWorktree[],
 	results: readonly WorktreeSetupResult[] | null,
 ): string[] {
-	if (worktrees.length === 0) return [];
-	const lines = [""];
+	const lines: string[] = [];
 	if (results === null) {
 		const auto = worktrees.filter((w) => w.autoActivate).map((w) => w.name);
 		if (auto.length > 0) {
@@ -965,14 +977,5 @@ export function worktreeLines(
 			}
 		}
 	}
-	for (const w of worktrees) {
-		if (!w.autoActivate) {
-			lines.push(
-				warn(
-					`Worktree ${bold(w.name)} is missing this project's plugins. Run magus update there to choose a profile.`,
-				),
-			);
-		}
-	}
-	return lines;
+	return lines.length > 0 ? ["", ...lines] : [];
 }