magus-cli 7.1.0 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.1.0",
-    "magus-cli-darwin-x64": "7.1.0",
-    "magus-cli-linux-x64": "7.1.0"
+    "magus-cli-darwin-arm64": "7.3.0",
+    "magus-cli-darwin-x64": "7.3.0",
+    "magus-cli-linux-x64": "7.3.0"
   }
 }

package/src/__tests__/blackbox-plugin-state.test.ts

@@ -51,6 +51,7 @@ function item(over: Partial<PluginUpdateItem>): PluginUpdateItem {
 		pluginId: "x@magus",
 		pinned: "latest",
 		installed: "1.0.0",
+		loaded: "1.0.0",
 		available: "1.0.0",
 		target: null,
 		action: "current",
@@ -318,6 +319,7 @@ describe("countPluginStates", () => {
 			update: 2,
 			repair: 1,
 			current: 1,
+			"stale-load": 0,
 			unknown: 1,
 		});
 	});
@@ -328,6 +330,7 @@ describe("countPluginStates", () => {
 			update: 0,
 			repair: 0,
 			current: 0,
+			"stale-load": 0,
 			unknown: 0,
 		});
 	});

package/src/__tests__/doctor.test.ts

@@ -15,6 +15,7 @@ import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { doctorExitCode } from "../cli/doctor.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import type { DoctorResult } from "../services/doctor.js";
 
@@ -461,3 +462,33 @@ describe("doctor", () => {
 		});
 	});
 });
+
+/**
+ * `magus doctor`'s exit code, and the one thing `--fix` must not silence.
+ *
+ * Stale plugin loads are printed by doctor and repaired by nothing it runs — the
+ * section says so itself. They used to be added to the same counter as the
+ * fixable problems, and the code was `problems > 0 && !fix ? 1 : 0`, so
+ * `magus doctor --fix` printed its red lines and exited 0. A CI or pre-flight
+ * step reading that exit code went green over a plugin whose sessions load a
+ * version nobody installed.
+ */
+describe("doctorExitCode", () => {
+	it("exits 0 when nothing is wrong, with or without --fix", () => {
+		expect(doctorExitCode({ fixable: 0, unfixable: 0, fix: false })).toBe(0);
+		expect(doctorExitCode({ fixable: 0, unfixable: 0, fix: true })).toBe(0);
+	});
+
+	it("exits 1 for fixable problems only when --fix was NOT asked for", () => {
+		expect(doctorExitCode({ fixable: 3, unfixable: 0, fix: false })).toBe(1);
+		expect(doctorExitCode({ fixable: 3, unfixable: 0, fix: true })).toBe(0);
+	});
+
+	it("exits 1 for a stale plugin load EVEN WITH --fix", () => {
+		// The regression: --fix does not repair these, so suppressing the exit code
+		// reports success over output that says the opposite.
+		expect(doctorExitCode({ fixable: 0, unfixable: 1, fix: true })).toBe(1);
+		expect(doctorExitCode({ fixable: 0, unfixable: 1, fix: false })).toBe(1);
+		expect(doctorExitCode({ fixable: 2, unfixable: 1, fix: true })).toBe(1);
+	});
+});

package/src/__tests__/plugin-resolution.test.ts

@@ -0,0 +1,431 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import {
+	isRelevantInstallation,
+	pickLoadedEntry,
+	repoRootForPath,
+	resolveLoadedVersions,
+} from "../services/plugin-resolution.js";
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+} from "../types/index.js";
+
+/**
+ * The loader's own resolution, not magus's.
+ *
+ * `pickRegistryEntry` (registry-version-resolution.test.ts) answers "what does
+ * magus consider installed here". These cases answer the other question — what
+ * Claude Code will LOAD here — and the two disagree in ways that are invisible
+ * from the settings file: a row belonging to a worktree that no longer exists
+ * still decides the answer, and array order beats version order.
+ *
+ * Exercised against real repositories rather than a hand-written `.git` file,
+ * because the point of `repoRootForPath` is agreeing with git about what a
+ * linked worktree is. A stub would confirm whatever parse it was written from.
+ */
+
+// Isolate from the operator's git config: a global `core.excludesFile`,
+// `init.defaultBranch`, or commit signing would otherwise leak into these repos.
+const GIT_CFG = [
+	"-c",
+	"user.name=test",
+	"-c",
+	"user.email=test@example.com",
+	"-c",
+	"commit.gpgsign=false",
+	"-c",
+	"init.defaultBranch=main",
+];
+
+const git = (cwd: string, ...args: string[]) =>
+	execFileSync("git", [...GIT_CFG, ...args], { cwd, encoding: "utf8" }).trim();
+
+let base: string;
+/** The repository under test, standing in for magus-src. */
+let mainTree: string;
+/** A live linked worktree of it. */
+let linked: string;
+/** A worktree that was created, registered, and then REMOVED. */
+let deletedTree: string;
+/** A repository that has nothing to do with the one under test. */
+let otherRepo: string;
+/** Cache directories, as `~/.claude/plugins/cache/magus/madbench/<version>`. */
+let cache030: string;
+let cache050: string;
+
+const entry = (
+	over: Partial<InstalledPluginEntry> & { version: string },
+): InstalledPluginEntry => ({
+	scope: "project",
+	installPath: `/cache/${over.version}`,
+	installedAt: "2026-01-01T00:00:00.000Z",
+	lastUpdated: "2026-01-01T00:00:00.000Z",
+	...over,
+});
+
+beforeAll(async () => {
+	// realpath: on macOS os.tmpdir() is a symlink, and git reports real paths.
+	base = await fs.realpath(
+		await fs.mkdtemp(path.join(os.tmpdir(), "magus-loader-")),
+	);
+	mainTree = path.join(base, "magus-src");
+	linked = path.join(mainTree, ".claude", "worktrees", "madbench");
+	deletedTree = path.join(mainTree, ".claude", "worktrees", "gone");
+	otherRepo = path.join(base, "unrelated");
+
+	await fs.ensureDir(mainTree);
+	git(mainTree, "init", "-q");
+	await fs.writeFile(path.join(mainTree, "README.md"), "hello\n");
+	git(mainTree, "add", "-A");
+	git(mainTree, "commit", "-qm", "initial");
+	git(mainTree, "worktree", "add", "-q", "-b", "madbench", linked);
+
+	// Created, then removed — its registry rows are what survive it.
+	git(mainTree, "worktree", "add", "-q", "-b", "gone", deletedTree);
+	await fs.remove(deletedTree);
+
+	await fs.ensureDir(otherRepo);
+	git(otherRepo, "init", "-q");
+
+	cache030 = path.join(base, "cache", "magus", "madbench", "0.3.0");
+	cache050 = path.join(base, "cache", "magus", "madbench", "0.5.0");
+	await fs.ensureDir(cache030);
+	await fs.ensureDir(cache050);
+});
+
+afterAll(async () => {
+	if (base) await fs.remove(base);
+});
+
+describe("repoRootForPath", () => {
+	test("a linked worktree and its main checkout resolve to the SAME root", () => {
+		expect(repoRootForPath(linked)).toBe(mainTree);
+		expect(repoRootForPath(mainTree)).toBe(mainTree);
+	});
+
+	test("a path inside the main checkout resolves to the checkout", () => {
+		expect(repoRootForPath(path.join(mainTree, "tools", "magus"))).toBe(
+			mainTree,
+		);
+	});
+
+	test("a DELETED worktree's path still resolves, to the repository that held it", () => {
+		// The directory is gone; the walk finds the nearest surviving ancestor's
+		// `.git`. This is why the implementation may not shell out to git — every
+		// git command fails here, and "no root" is the one answer that would make
+		// the entry below stop counting.
+		expect(fs.existsSync(deletedTree)).toBe(false);
+		expect(repoRootForPath(deletedTree)).toBe(mainTree);
+	});
+
+	test("a path that never existed resolves through its surviving ancestors", () => {
+		expect(repoRootForPath(path.join(mainTree, "no", "such", "dir"))).toBe(
+			mainTree,
+		);
+	});
+
+	test("a path in no repository is null, and two of them are not equal-by-null", () => {
+		expect(repoRootForPath(path.join(base, "loose", "file"))).toBeNull();
+		expect(repoRootForPath(otherRepo)).toBe(otherRepo);
+	});
+
+	test("an empty path is null rather than the process's own root", () => {
+		expect(repoRootForPath("")).toBeNull();
+	});
+});
+
+describe("isRelevantInstallation", () => {
+	const root = () => repoRootForPath(mainTree);
+
+	test("a user-scope entry is always relevant, wherever it was installed", () => {
+		expect(
+			isRelevantInstallation(
+				entry({ scope: "user", version: "1.0.0", projectPath: undefined }),
+				linked,
+				repoRootForPath(linked),
+			),
+		).toBe(true);
+	});
+
+	test("an entry from an UNRELATED repository is never relevant", () => {
+		expect(
+			isRelevantInstallation(
+				entry({ version: "9.9.9", projectPath: otherRepo }),
+				mainTree,
+				root(),
+			),
+		).toBe(false);
+	});
+
+	test("an entry pinned to this exact directory is relevant", () => {
+		expect(
+			isRelevantInstallation(
+				entry({ version: "1.0.0", projectPath: linked }),
+				linked,
+				repoRootForPath(linked),
+			),
+		).toBe(true);
+	});
+
+	test("a sibling worktree of the same repository is relevant", () => {
+		expect(
+			isRelevantInstallation(
+				entry({ version: "1.0.0", projectPath: deletedTree }),
+				linked,
+				repoRootForPath(linked),
+			),
+		).toBe(true);
+	});
+
+	test("a project-scope entry with no projectPath is not relevant", () => {
+		expect(
+			isRelevantInstallation(
+				entry({ version: "1.0.0", projectPath: undefined }),
+				mainTree,
+				root(),
+			),
+		).toBe(false);
+	});
+
+	test("two rootless paths DO match each other, as the original's compare does", () => {
+		// `repoRoot(entry.projectPath) === repoRoot(originalCwd)` with both sides
+		// null is true in the decompiled filter, so a row from any directory in no
+		// repository competes when Claude Code runs from another such directory —
+		// a scratch dir, a home directory, a plain non-git project.
+		//
+		// The port used to answer false here, which made magus name a
+		// `loadedVersion` the loader would not pick in any non-git directory. It is
+		// the loader's answer this module owes, not the more cautious one; what
+		// magus may WRITE is a separate question, pinned in stale-load-repair.test.ts
+		// ("a rootless row from another directory is relevant but NOT rewritten").
+		const loose = path.join(base, "loose");
+		expect(
+			isRelevantInstallation(
+				entry({
+					version: "1.0.0",
+					projectPath: path.join(base, "other-loose"),
+				}),
+				loose,
+				repoRootForPath(loose),
+			),
+		).toBe(true);
+	});
+
+	test("a rootless row is still irrelevant to a directory inside a repository", () => {
+		// The null-matches-null rule must not leak the other way: `cwdRoot` is a
+		// real root here, so a rootless row's null root does not equal it.
+		expect(
+			isRelevantInstallation(
+				entry({ version: "1.0.0", projectPath: path.join(base, "loose") }),
+				mainTree,
+				root(),
+			),
+		).toBe(false);
+	});
+});
+
+describe("pickLoadedEntry — madbench 0.3.0", () => {
+	test("a DELETED sibling worktree's row beats this project's own newer row", () => {
+		// The measured defect. madbench was installed into a worktree that has
+		// since been removed; that row is still in installed_plugins.json, still
+		// points at a cache directory that still exists, and was written FIRST.
+		// This project then installed 0.5.0. magus reported 0.5.0 and every
+		// session in this directory loaded 0.3.0.
+		const entries = [
+			entry({
+				version: "0.3.0",
+				projectPath: deletedTree,
+				installPath: cache030,
+			}),
+			entry({ version: "0.5.0", projectPath: linked, installPath: cache050 }),
+		];
+
+		expect(pickLoadedEntry(entries, linked)?.version).toBe("0.3.0");
+	});
+
+	test("with the stale row gone, this project's own row loads", () => {
+		const entries = [
+			entry({ version: "0.5.0", projectPath: linked, installPath: cache050 }),
+		];
+		expect(pickLoadedEntry(entries, linked)?.version).toBe("0.5.0");
+	});
+
+	test("install ORDER decides, not the version: reversing the rows changes the answer", () => {
+		// Stated as its own case because it is the part that reads as a bug and
+		// is not one: nothing sorts these, so the same two installs in the other
+		// order load the newer plugin.
+		const stale = entry({
+			version: "0.3.0",
+			projectPath: deletedTree,
+			installPath: cache030,
+		});
+		const own = entry({
+			version: "0.5.0",
+			projectPath: linked,
+			installPath: cache050,
+		});
+
+		expect(pickLoadedEntry([stale, own], linked)?.version).toBe("0.3.0");
+		expect(pickLoadedEntry([own, stale], linked)?.version).toBe("0.5.0");
+	});
+
+	test("a row whose cache directory is gone is skipped for one that exists", () => {
+		const entries = [
+			entry({
+				version: "0.3.0",
+				projectPath: deletedTree,
+				installPath: path.join(base, "cache", "magus", "madbench", "evicted"),
+			}),
+			entry({ version: "0.5.0", projectPath: linked, installPath: cache050 }),
+		];
+
+		expect(pickLoadedEntry(entries, linked)?.version).toBe("0.5.0");
+	});
+});
+
+describe("pickLoadedEntry — the selection rules", () => {
+	test("no relevant entry at all yields undefined", () => {
+		const entries = [entry({ version: "9.9.9", projectPath: otherRepo })];
+		expect(pickLoadedEntry(entries, mainTree)).toBeUndefined();
+	});
+
+	test("empty and missing entry lists are handled", () => {
+		expect(pickLoadedEntry([], mainTree)).toBeUndefined();
+		expect(pickLoadedEntry(undefined, mainTree)).toBeUndefined();
+	});
+
+	test("ONE relevant entry loads even though its installPath does not exist", () => {
+		// The single-candidate branch carries no existence check. That is the
+		// binary's behaviour, not an oversight of the port: one relevant row means
+		// that row is what the loader resolves, and it fails at load rather than
+		// falling through to anything else.
+		const missing = path.join(base, "cache", "magus", "madbench", "not-here");
+		expect(fs.existsSync(missing)).toBe(false);
+
+		const only = entry({
+			version: "0.4.0",
+			projectPath: linked,
+			installPath: missing,
+		});
+		expect(pickLoadedEntry([only], linked)).toBe(only);
+	});
+
+	test("with no existing installPath anywhere, the FIRST one with a path wins", () => {
+		// `firstValid` is captured before the existence test, so the fallback is
+		// the first entry that has an installPath at all — not the first existing
+		// one, of which there are none here.
+		const first = entry({
+			version: "0.3.0",
+			projectPath: deletedTree,
+			installPath: path.join(base, "gone-a"),
+		});
+		const second = entry({
+			version: "0.5.0",
+			projectPath: linked,
+			installPath: path.join(base, "gone-b"),
+		});
+
+		expect(pickLoadedEntry([first, second], linked)).toBe(first);
+	});
+
+	test("an entry with an empty installPath is passed over for the fallback", () => {
+		const blank = entry({
+			version: "0.3.0",
+			projectPath: deletedTree,
+			installPath: "",
+		});
+		const pathed = entry({
+			version: "0.5.0",
+			projectPath: linked,
+			installPath: path.join(base, "gone-b"),
+		});
+
+		expect(pickLoadedEntry([blank, pathed], linked)).toBe(pathed);
+	});
+
+	test("every relevant entry lacking an installPath falls back to the first of them", () => {
+		const a = entry({
+			version: "0.3.0",
+			projectPath: deletedTree,
+			installPath: "",
+		});
+		const b = entry({ version: "0.5.0", projectPath: linked, installPath: "" });
+
+		expect(pickLoadedEntry([a, b], linked)).toBe(a);
+	});
+
+	test("a user-scope row competes with this project's rows on install order", () => {
+		const user = entry({
+			scope: "user",
+			version: "0.3.0",
+			projectPath: undefined,
+			installPath: cache030,
+		});
+		const own = entry({
+			version: "0.5.0",
+			projectPath: linked,
+			installPath: cache050,
+		});
+
+		expect(pickLoadedEntry([user, own], linked)?.version).toBe("0.3.0");
+		expect(pickLoadedEntry([own, user], linked)?.version).toBe("0.5.0");
+	});
+});
+
+describe("resolveLoadedVersions", () => {
+	const registry = (
+		plugins: Record<string, InstalledPluginEntry[]>,
+	): InstalledPluginsRegistry => ({ version: 2, plugins });
+
+	test("maps each plugin id to the version that will actually load", () => {
+		const loaded = resolveLoadedVersions(
+			registry({
+				"madbench@magus": [
+					entry({
+						version: "0.3.0",
+						projectPath: deletedTree,
+						installPath: cache030,
+					}),
+					entry({
+						version: "0.5.0",
+						projectPath: linked,
+						installPath: cache050,
+					}),
+				],
+				"dev@magus": [
+					entry({
+						scope: "user",
+						version: "7.4.0",
+						projectPath: undefined,
+						installPath: cache050,
+					}),
+				],
+			}),
+			linked,
+		);
+
+		expect(loaded).toEqual({ "madbench@magus": "0.3.0", "dev@magus": "7.4.0" });
+	});
+
+	test("a plugin with no relevant entry is absent from the map, not null in it", () => {
+		const loaded = resolveLoadedVersions(
+			registry({
+				"elsewhere@magus": [
+					entry({ version: "9.9.9", projectPath: otherRepo }),
+				],
+			}),
+			mainTree,
+		);
+
+		expect(loaded).toEqual({});
+		expect(Object.hasOwn(loaded, "elsewhere@magus")).toBe(false);
+	});
+
+	test("an empty registry resolves to an empty map", () => {
+		expect(resolveLoadedVersions(registry({}), mainTree)).toEqual({});
+	});
+});

package/src/__tests__/plugin-row-text.test.ts

@@ -268,6 +268,7 @@ describe("pluginStatusText — absent is not enabled-not-installed (LOW 6)", ()
 		pluginId: "x@magus",
 		pinned: "latest",
 		installed: null,
+		loaded: null,
 		available: "1.0.0",
 		target: "1.0.0",
 		action: "install",
@@ -343,3 +344,68 @@ describe("pluginStatusText — absent is not enabled-not-installed (LOW 6)", ()
 		).toBe(" stale — reinstall (files changed without a version bump)");
 	});
 });
+
+describe("pluginRowText — a broken plugin says so, and names the key", () => {
+	/**
+	 * The measured madbench case: 0.5.0 installed in this worktree, 0.3.0 still
+	 * registered against a sibling worktree that was deleted, and that older row
+	 * is what Claude Code resolves. Every version magus records says 0.5.0, so
+	 * without this the row reads as up to date — which was the bug.
+	 */
+	const MADBENCH = info({
+		id: "madbench@magus",
+		version: "0.5.0",
+		installedVersion: "0.5.0",
+		loadedVersion: "0.3.0",
+		projectScope: { enabled: true, version: "0.5.0" },
+		author: { name: "MadAppGang" },
+	});
+
+	test("the row states the verdict and the key — NO version archaeology", () => {
+		const row = rows([MADBENCH]).get("madbench@magus");
+		if (!row) throw new Error("row missing");
+
+		expect(row.status?.action).toBe("stale-load");
+		expect(row.status?.loaded).toBe("0.3.0");
+		expect(pluginRowText(row).text).toBe(" v0.5.0 BROKEN — press a to fix");
+	});
+
+	test("the row does NOT carry the classifier's note", () => {
+		// It used to print it verbatim — "≠ loads v0.3.0, installed v0.5.0" — which
+		// is this codebase's internal vocabulary: it tells a reader neither what is
+		// wrong nor what to do, because the loads/installed distinction is one only
+		// magus draws. The note itself is unchanged and still reaches the CLI report
+		// and the TUI detail panel, which is where the mechanism belongs.
+		const row = rows([MADBENCH]).get("madbench@magus");
+		if (!row) throw new Error("row missing");
+
+		const note = cliNote([MADBENCH], "madbench@magus");
+		expect(note).toBe("loads v0.3.0, installed v0.5.0");
+		expect(pluginRowText(row).text).not.toContain(note ?? "<missing note>");
+		expect(pluginRowText(row).text).not.toContain("loads v");
+	});
+
+	test("the row is RED — broken, not the amber of a routine update", () => {
+		// Amber is this file's tone for "cannot tell" and for ordinary work. A
+		// session running a version nobody installed is broken, and `a` fixes it.
+		const row = rows([MADBENCH]).get("madbench@magus");
+		if (!row) throw new Error("row missing");
+		expect(pluginStatusText(row.status).tone).toBe("danger");
+	});
+
+	test("the same plugin loading its installed version says nothing extra", () => {
+		const healthy = info({
+			id: "madbench@magus",
+			version: "0.5.0",
+			installedVersion: "0.5.0",
+			loadedVersion: "0.5.0",
+			projectScope: { enabled: true, version: "0.5.0" },
+			author: { name: "MadAppGang" },
+		});
+		const row = rows([healthy]).get("madbench@magus");
+		if (!row) throw new Error("row missing");
+
+		expect(row.status?.action).toBe("current");
+		expect(pluginRowText(row).text).toBe(" v0.5.0");
+	});
+});