magus-cli 7.2.0 → 7.3.0

package/src/__tests__/useStaleLoadModal.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildStaleLoadModal,
+	staleLoadRepairSummary,
+} from "../ui/hooks/useStaleLoadModal";
+
+/**
+ * The startup popup for a broken plugin.
+ *
+ * Same shape as buildGitignoreModal beside it, with one difference that is the
+ * whole point of the popup: FIXING is the default. A plugin the loader resolves
+ * at the wrong version means every session in this directory runs code nobody
+ * installed, so Enter must repair it rather than dismiss.
+ */
+describe("buildStaleLoadModal", () => {
+	const args = (
+		over: Partial<Parameters<typeof buildStaleLoadModal>[0]> = {},
+	) => ({
+		brokenCount: 2,
+		onFix: () => {},
+		onOpenTab: () => {},
+		onDismiss: () => {},
+		...over,
+	});
+
+	it("offers fix, review and dismiss, with FIX first", () => {
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options.map((o) => o.value)).toEqual([
+			"fix",
+			"open-tab",
+			"dismiss",
+		]);
+	});
+
+	it("defaults to FIX explicitly, not by accident of ordering", () => {
+		// Stated in the data so a future reordering cannot quietly make "leave it
+		// broken" the thing Enter does.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.defaultIndex).toBe(0);
+		expect(modal.options[modal.defaultIndex ?? -1]?.value).toBe("fix");
+	});
+
+	it("blames the Claude Code bug, not magus's own state", () => {
+		// The title is the whole message for anyone who reads one line. It has to
+		// say what is wrong — a defect in Claude Code's loader — rather than
+		// report that two of magus's stores disagree, which is not actionable and
+		// reads as though the user misconfigured something.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.title).toContain("Claude Code");
+		expect(modal.message).toContain("stale cached version");
+		expect(modal.options[0].label).toBe("Fix it (3 plugins)");
+		expect(modal.message).toContain("3 plugins are on an older version");
+	});
+
+	it("says the reach is every worktree, not just this directory", () => {
+		// Relevance is decided by repository root, so every worktree and the main
+		// checkout resolve identically and break together. A reader told only
+		// about "this directory" would fix one worktree and expect the others to
+		// differ — they cannot.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain("every worktree");
+		expect(modal.message).toContain("main checkout");
+	});
+
+	it("states the effect plainly, without overstating it", () => {
+		// A draft claimed "your sessions run code you did not install". Nothing
+		// happens to the user's code; an old cached plugin version is used. The
+		// overstatement is pinned here so it cannot come back on the next edit.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).not.toContain("run code");
+		expect(modal.message).not.toContain("did not install");
+	});
+
+	it("reads correctly for a single plugin", () => {
+		const modal = buildStaleLoadModal(args({ brokenCount: 1 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options[0].label).toBe("Fix it (1 plugin)");
+		expect(modal.message).toContain("1 plugin is on an older version");
+	});
+
+	it("promises the backup and promises not to delete or downgrade", () => {
+		// The popup is asking permission to edit Claude Code-owned state. What it
+		// will and will not do has to be on the screen, not only in a code comment.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain(
+			"installed_plugins.json is backed up first",
+		);
+		// Case-insensitive: the promise has to be on screen, but whether it opens a
+		// sentence or trails one is a wording choice, and pinning the capital made
+		// an ordinary copy edit fail for nothing.
+		expect(modal.message.toLowerCase()).toContain(
+			"nothing is deleted or downgraded",
+		);
+	});
+
+	it("routes each choice to its callback, and cancel to dismiss", () => {
+		let fixed = 0;
+		let opened = 0;
+		let dismissed = 0;
+		const modal = buildStaleLoadModal(
+			args({
+				onFix: () => {
+					fixed++;
+				},
+				onOpenTab: () => {
+					opened++;
+				},
+				onDismiss: () => {
+					dismissed++;
+				},
+			}),
+		);
+		if (modal.type !== "select") throw new Error("type guard");
+
+		modal.onSelect("fix");
+		modal.onSelect("open-tab");
+		modal.onSelect("dismiss");
+		modal.onCancel();
+
+		expect({ fixed, opened, dismissed }).toEqual({
+			fixed: 1,
+			opened: 1,
+			dismissed: 2,
+		});
+	});
+});
+
+describe("staleLoadRepairSummary", () => {
+	it("says what loads NOW for each repaired plugin", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "madbench@magus", target: "0.5.0", ok: true },
+				{ pluginId: "dev@magus", target: "7.4.0", ok: true },
+			]),
+		).toBe("✓ madbench@magus now loads v0.5.0\n✓ dev@magus now loads v7.4.0");
+	});
+
+	it("reports a failed repair with its own reason, never as a success", () => {
+		expect(
+			staleLoadRepairSummary([
+				{
+					pluginId: "madbench@magus",
+					target: "0.5.0",
+					ok: false,
+					error: "the loader still resolves v0.3.0 here, not v0.5.0",
+				},
+			]),
+		).toBe(
+			"✗ madbench@magus — the loader still resolves v0.3.0 here, not v0.5.0",
+		);
+	});
+
+	it("falls back to a plain reason rather than an empty line", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "a@magus", target: "1.0.0", ok: false },
+			]),
+		).toBe("✗ a@magus — repair did not take effect");
+	});
+
+	it("says so when there was nothing to repair", () => {
+		expect(staleLoadRepairSummary([])).toBe("Nothing to repair.");
+	});
+});

package/src/cli/doctor.ts

@@ -7,10 +7,16 @@
  *   2. Profile symlink integrity — the active profile's links resolve.
  *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
  *   4. Model routing — config validity, hook registration, and drift.
+ *   5. Plugin loads — what Claude Code will load here vs what is installed.
  */
 
 import path from "node:path";
 import fs from "fs-extra";
+import {
+	getProjectInstalledPluginVersions,
+	readInstalledPluginsRegistry,
+	readSettings,
+} from "../services/claude-settings.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import {
@@ -22,6 +28,11 @@ import {
 	readModelsConfig,
 	readModelsStatus,
 } from "../services/models-manager.js";
+import { isBehind } from "../services/plugin-manager.js";
+import {
+	type RepoRootCache,
+	pickLoadedEntry,
+} from "../services/plugin-resolution.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
 import { resolveExecutable } from "../utils/command-utils.js";
@@ -111,8 +122,123 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	// 4. Model routing.
 	problems += await checkModels(projectPath, fix);
 
-	if (problems === 0) console.log("\n✓ No problems found.");
-	return problems > 0 && !fix ? 1 : 0;
+	// 5. Stale plugin loads. Counted SEPARATELY, because `--fix` does not repair
+	// them — see doctorExitCode.
+	const staleLoads = await checkPluginLoads(projectPath);
+
+	if (problems === 0 && staleLoads === 0) console.log("\n✓ No problems found.");
+	return doctorExitCode({ fixable: problems, unfixable: staleLoads, fix });
+}
+
+/**
+ * Doctor's exit code.
+ *
+ * `--fix` suppresses the exit code for what it repaired — that is the point of
+ * the flag, and a caller that asked for repairs does not want a red exit over
+ * problems that are now gone. It must NOT suppress a class it never touches.
+ *
+ * Stale plugin loads are exactly that class: `checkPluginLoads` prints them and
+ * says so, and the repair lives in `repairStaleLoad`, reached by `magus update`
+ * and the Plugins screen. Folding them into the same counter meant `magus doctor
+ * --fix` printed red lines and exited 0 — so a CI or pre-flight step went green
+ * over a plugin whose sessions run a version nobody installed, which is the same
+ * deception the stale-load work exists to end.
+ *
+ * Pure and exported so the decision is pinned by a test rather than inferred from
+ * a command that needs a real `~/.claude` to run.
+ */
+export function doctorExitCode(args: {
+	/** Problems `--fix` can act on. */
+	fixable: number;
+	/** Problems it cannot — reported either way, and never silenced by `--fix`. */
+	unfixable: number;
+	fix: boolean;
+}): number {
+	if (args.unfixable > 0) return 1;
+	return args.fixable > 0 && !args.fix ? 1 : 0;
+}
+
+/**
+ * Plugins whose installed version is NOT the version that will load here.
+ *
+ * Reported, never repaired — `--fix` deliberately does nothing about it, and
+ * that is a division of labour rather than a dead end. A reinstall does not
+ * clear this (measured): it writes another `installed_plugins.json` row for THIS
+ * project, while the row the loader picks belongs to a different one — usually a
+ * worktree that has since been deleted, whose entry nothing prunes. Moving those
+ * rows forward is what fixes it, and that lives in `repairStaleLoad`, reached by
+ * `magus update` and by the Plugins screen's `a` key. Doctor's job is to name
+ * the winner, which is the one thing neither of those prints.
+ *
+ * Both halves come from the registry rather than the catalog, so this section
+ * makes no network call and holds even when GitHub is unreachable:
+ *   installed — magus's own resolution, `pickRegistryEntry` via settings overlay
+ *   loads     — the loader's, `pickLoadedEntry`
+ */
+async function checkPluginLoads(projectPath: string): Promise<number> {
+	const registry = await readInstalledPluginsRegistry();
+	const settings = await readSettings(projectPath);
+	const installed = await getProjectInstalledPluginVersions(
+		settings.installedPluginVersions || {},
+		projectPath,
+	);
+	const ids = Object.keys(installed);
+	if (ids.length === 0) return 0;
+
+	// One cache across every plugin: the same handful of project paths repeat in
+	// hundreds of rows, and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const stale: Array<{
+		pluginId: string;
+		loaded: string;
+		recorded: string;
+		winner: string;
+	}> = [];
+
+	for (const pluginId of ids.sort()) {
+		const recorded = installed[pluginId];
+		if (!recorded) continue;
+		const pick = pickLoadedEntry(
+			registry.plugins?.[pluginId],
+			projectPath,
+			cache,
+		);
+		if (!pick?.version) continue;
+		// The same predicate the classifier uses, so doctor and the plugin screen
+		// cannot disagree about which pairs count. Unorderable pairs answer null
+		// and are left alone — "cannot tell" is not a finding.
+		if (isBehind(recorded, pick.version) !== true) continue;
+		stale.push({
+			pluginId,
+			loaded: pick.version,
+			recorded,
+			winner:
+				pick.projectPath ??
+				(pick.scope === "user" ? "user scope (no project)" : "unknown project"),
+		});
+	}
+
+	console.log("\nPlugin loads:");
+	if (stale.length === 0) {
+		console.log(
+			`  ✓ All ${ids.length} installed plugins load at their installed version.`,
+		);
+		return 0;
+	}
+
+	for (const row of stale) {
+		console.log(
+			`  ✗ ${row.pluginId} — loads v${row.loaded}, installed v${row.recorded}`,
+		);
+		console.log(`      the entry that wins belongs to ${row.winner}`);
+	}
+	console.log(
+		"    Reinstalling does not fix this. Run `magus update` — it moves those",
+	);
+	console.log(
+		"    install records forward, backing up installed_plugins.json first.",
+	);
+	return stale.length;
 }
 
 /**

package/src/cli/update-view.ts

@@ -81,6 +81,7 @@ type ActionKey =
 	| "upgrade"
 	| "repair"
 	| "refresh"
+	| "stale-load"
 	| "unknown";
 
 const ACTIONS: Record<ActionKey, ActionStyle> = {
@@ -93,6 +94,11 @@ const ACTIONS: Record<ActionKey, ActionStyle> = {
 	upgrade: { glyph: "↑", label: "UPGRADE", color: brand.success },
 	repair: { glyph: "⟳", label: "REPAIR", color: brand.info },
 	refresh: { glyph: "⟳", label: "REFRESH", color: brand.info },
+	// The installed version is right and an older one loads, so this session runs
+	// a version nobody installed. Danger, and the word is BROKEN: "STALE" read as
+	// a mild version of `repair`, and this is not that. Six characters, one under
+	// UNKNOWN, so CHIP_WIDTH is unchanged and no other section pays for it.
+	"stale-load": { glyph: "✗", label: "BROKEN", color: brand.danger },
 	// 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 },
@@ -249,8 +255,12 @@ function pluginDetail(item: PluginUpdateItem): string {
 	// The note stays on the item. The TUI has no heading to lean on and renders
 	// it as that row's only explanation — this is a rendering decision about a
 	// table that carries the fact twice, not a change to what is known.
+	// `older-version-loads` is excluded for the same reason: its note says
+	// "loads v0.3.0, installed v0.5.0" and the two columns beside it already do.
 	const note =
-		item.note && item.reason !== "not-offered"
+		item.note &&
+		item.reason !== "not-offered" &&
+		item.reason !== "older-version-loads"
 			? `  ${dim(`(${item.note})`)}`
 			: "";
 	switch (item.action) {
@@ -268,6 +278,16 @@ function pluginDetail(item: PluginUpdateItem): string {
 		case "repair":
 		case "unknown":
 			return `${item.installed ?? "—"}${note}`;
+		case "stale-load":
+			// Both versions, in the order the reader needs them: what runs, then
+			// what is installed. This is a report, not a one-line picker row — the
+			// TUI's row deliberately shows neither, because there the verdict and
+			// the key are all that fit. The note says the same thing in words; the
+			// columns are what makes a table of these scannable.
+			return `${fg(
+				groupStyle("Broken").text,
+				item.loaded ?? "?",
+			)} ${dim("≠")} ${item.installed ?? "—"}${note}`;
 		case "current":
 			return `${item.installed ?? "—"}${note}`;
 	}
@@ -347,6 +367,10 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 function pluginGroup(item: PluginUpdateItem): string {
 	if (item.action === "update" || item.action === "repair") return "Update";
 	if (item.action === "install") return "Fix required";
+	// Never "Current". The installed version matching is exactly what makes this
+	// state deceptive, and a row that reads as up to date under a CURRENT
+	// heading is the defect this state was added to end.
+	if (item.action === "stale-load") return "Broken";
 	if (item.action === "unknown") {
 		return item.reason === "not-offered" ? "Deprecated" : "Unverified";
 	}
@@ -354,6 +378,7 @@ function pluginGroup(item: PluginUpdateItem): string {
 }
 
 const GROUP_ORDER = [
+	"Broken",
 	"Update",
 	"Deprecated",
 	"Fix required",
@@ -373,6 +398,11 @@ const GROUP_KIND: Record<string, ReportBadgeKind> = {
 	Update: "update",
 	Deprecated: "deprecated",
 	"Fix required": "fix",
+	// Red earth, borrowed from `deprecated`. The kinds are measured contrast
+	// pairs, not meanings — "Hue, not meaning; the badge says the word", as
+	// theme-mode.ts puts it — so an unmeasured fourth palette would be the only
+	// thing here nobody had checked against both pages.
+	Broken: "deprecated",
 };
 
 interface GroupStyle {

package/src/services/active-closure.ts

@@ -115,3 +115,26 @@ export async function loadActiveClosure(
 		return null;
 	}
 }
+
+/**
+ * The active profile's plugin pins — `pluginId -> exact version | "latest"` — and
+ * `{}` when no profile resolves.
+ *
+ * The one shape every surface that judges a plugin needs: `classifyPlugin`'s
+ * `pin`, the Plugins screen's `pins`, and the ceiling `findStaleLoads` caps its
+ * repair target at. Reading it through one helper is what keeps the startup popup
+ * and the Plugins header from capping differently — a pinned plugin read as
+ * BROKEN in one and current in the other is exactly the drift the classifier was
+ * centralised to end.
+ *
+ * `{}` means "latest for everything", which is what `pinForRow` assumes for an
+ * installed plugin no profile declares. `resolveBins: false` because no caller of
+ * this needs a plugin's binary requirements, and the default resolver reads every
+ * declared plugin's `plugin.json` to build them.
+ */
+export async function activePluginPins(
+	projectPath: string,
+): Promise<Readonly<Record<string, string>>> {
+	const active = await loadActiveClosure(projectPath, { resolveBins: false });
+	return active?.closure.plugins ?? {};
+}