magus-cli 7.2.0 → 7.3.0

package/src/services/plugin-manager.ts

@@ -45,6 +45,7 @@ import {
 	isAuthoritative,
 	resolveMarketplacePlugins,
 } from "./marketplace-fetcher.js";
+import { resolveLoadedVersions } from "./plugin-resolution.js";
 export {
 	fetchMarketplacePlugins,
 	getMarketplaceFetchFailures,
@@ -72,6 +73,17 @@ export interface PluginInfo {
 	marketplaceDisplay: string;
 	enabled: boolean;
 	installedVersion?: string;
+	/**
+	 * The version Claude Code's loader will ACTUALLY load in this project, or
+	 * null when it will load nothing here.
+	 *
+	 * An INDEPENDENT column from `installedVersion`, not a correction of it. The
+	 * two answer different questions — what magus records as installed here,
+	 * versus what the loader resolves (services/plugin-resolution.ts) — and when
+	 * they disagree the session runs code that no version magus records names.
+	 * That disagreement is the finding; averaging the two would hide it.
+	 */
+	loadedVersion?: string | null;
 	/**
 	 * Provably behind the catalog, on ONE version pair.
 	 *
@@ -277,6 +289,18 @@ export async function getAvailablePlugins(
 	const enabledPlugins = await getEnabledPlugins(projectPath);
 	const installedVersions = await getInstalledPluginVersions(projectPath);
 
+	// What Claude Code will LOAD here, which is a different question from what is
+	// installed here and is answered by a different algorithm — the loader's own,
+	// ported in services/plugin-resolution.ts. Resolved once for the whole
+	// registry and carried alongside `installedVersion` on every row below; where
+	// the two disagree, the classifier calls it `stale-load`.
+	const loadedVersions = resolveLoadedVersions(
+		await readInstalledPluginsRegistry(),
+		projectPath ?? process.cwd(),
+	);
+	const loadedVersionOf = (pluginId: string): string | null =>
+		loadedVersions[pluginId] ?? null;
+
 	// Fetch all scopes for per-scope status
 	const userEnabledPlugins = await getGlobalEnabledPlugins();
 	const userInstalledVersions = await getGlobalInstalledPluginVersions();
@@ -384,6 +408,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: marketplace.displayName,
 				enabled: isEnabled,
 				installedVersion: installedVersion,
+				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(plugin.version, installedVersion) === true,
 				catalogSource: resolution.source,
 				updateCheckFailed: unverified,
@@ -423,6 +448,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
 				enabled: isEnabled,
 				installedVersion: installedVersion,
+				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(localPlugin.version, installedVersion) === true,
 				...scopeStatus,
 				category: localPlugin.category,
@@ -472,6 +498,7 @@ export async function getAvailablePlugins(
 			marketplaceDisplay: localMp?.name || formatMarketplaceName(mpName),
 			enabled: isEnabled,
 			installedVersion: installedVersion,
+			loadedVersion: loadedVersionOf(pluginId),
 			hasUpdate,
 			isOrphaned: true,
 			...scopeStatus,
@@ -652,6 +679,40 @@ export function isBehind(
 	return bothOpaque ? true : null;
 }
 
+/**
+ * Is `loaded` behind `target` in a way that MOVING FORWARD would actually fix?
+ *
+ * THE predicate behind the `stale-load` state. Both the classifier (which counts
+ * broken plugins in the Plugins header) and `findStaleLoads` (which counts them
+ * for the startup popup) ask this and nothing else, so the two surfaces cannot
+ * report different numbers for the same directory. They did: the popup said 8
+ * where the header said 6, because it asked {@link isBehind} instead.
+ *
+ * Stricter than `isBehind` in exactly one place, and deliberately: `isBehind`
+ * answers TRUE for two differing opaque ids, because for its question — "is this
+ * what the marketplace publishes now" — a different commit sha means no. That
+ * reasoning does not carry here. "Move the rows forward from sha A to sha B" is
+ * not a repair, it is a coin toss: the two carry no ordering, so nothing
+ * establishes which is later. Measured on the reporting machine, that alone put
+ * `skill-creator@claude-plugins-official` (two differing shas) and
+ * `plugin-dev@claude-plugins-official` (version literally `"unknown"`) into the
+ * popup's count, and neither could be repaired — `repairStaleLoad` rejects them
+ * at its cache-directory check.
+ *
+ * So this requires an ORDERED pair: `compareVersions` must return a number, and
+ * that number must be positive. A version against `null`, a semver against an
+ * opaque id, `"unknown"` against anything, and two differing shas all answer
+ * false — "cannot rank these" is never grounds for rewriting a registry row.
+ */
+export function isRepairablyBehind(
+	target: string | null | undefined,
+	loaded: string | null | undefined,
+): boolean {
+	if (!target || !loaded) return false;
+	const cmp = compareVersions(target, loaded);
+	return cmp !== null && cmp > 0;
+}
+
 // Get installed plugin versions from settings.json (shared, not secret)
 async function getInstalledPluginVersions(
 	projectPath?: string,

package/src/services/plugin-resolution.ts

@@ -0,0 +1,280 @@
+/**
+ * What Claude Code's loader will ACTUALLY load in this directory.
+ *
+ * Ported from Claude Code 2.1.274, decompiled: the relevance filter `SF`
+ * (byte 178070986) and the selection function `Bls` (byte 178140984). The port
+ * was validated against the real loader over 123/123 plugin resolutions across
+ * 12 repositories and worktrees. RE-VALIDATE IT WHEN CLAUDE CODE UPDATES —
+ * this file describes someone else's algorithm, so a new release can move it
+ * without anything here failing.
+ *
+ * Why it exists: magus reported versions from `settings.installedPluginVersions`
+ * overlaid with this project's `installed_plugins.json` rows (see
+ * `pickRegistryEntry` in claude-settings.ts). The loader consults neither of
+ * those orderings, so magus could report "up to date" while the session in that
+ * same directory loaded a two-versions-old plugin. The two answers are
+ * genuinely different questions and both are kept:
+ *
+ *   pickRegistryEntry  — "what does magus consider installed for this scope"
+ *   pickLoadedEntry    — "what will Claude Code load here"
+ *
+ * This module holds NO magus policy. It answers the second question only, so
+ * that a disagreement between the two is visible rather than averaged away.
+ *
+ * KNOWN DIVERGENCES from the decompiled original, both of which only ever REMOVE
+ * candidates — so each can make this module name an entry the loader does not
+ * use, and neither can make it miss one the loader does use:
+ *
+ *  1. The binary additionally rejects an entry whose `installPath` fails a
+ *     path-safety check (`suspect(installPath)`). Not ported — every
+ *     `installPath` is treated as non-suspect here.
+ *  2. The binary's relevance filter reads `entry.projectPath === originalCwd ||
+ *     repoRoot(entry.projectPath) === repoRoot(originalCwd)` with no guard on
+ *     `projectPath` being absent at all. A project-scope row carrying no
+ *     `projectPath` is rejected outright here (`isRelevantInstallation`), because
+ *     what `repoRoot(undefined)` answers inside the binary was not measured and
+ *     guessing it would put a row into the selection on a guess. Claude Code
+ *     writes `projectPath` for every project-scope install, so the case is
+ *     theoretical rather than observed.
+ *
+ * A THIRD divergence was removed rather than documented: two rootless paths used
+ * to compare unequal here, so in a directory belonging to no repository every
+ * rootless row was irrelevant to magus while the loader still counted it. See
+ * {@link isRelevantInstallation}.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+} from "../types/index.js";
+
+/**
+ * Memo for {@link repoRootForPath}. A registry holds one row per project path
+ * and a well-used machine has hundreds of them, most repeated across plugins;
+ * each miss walks the tree to the filesystem root with a `stat` per level.
+ *
+ * Deliberately passed in rather than held at module scope: a git root can come
+ * into existence while the TUI is open, and a process-lifetime cache would
+ * answer from before it did.
+ */
+export type RepoRootCache = Map<string, string | null>;
+
+/**
+ * Claude Code writes a `managed` scope for policy-installed plugins. The
+ * registry type in `types/index.ts` names only the three scopes magus itself
+ * writes, so the extra one is widened here instead of loosening a type that
+ * dozens of call sites narrow on.
+ */
+type LoaderScope = InstalledPluginEntry["scope"] | "managed";
+
+/**
+ * Scopes the loader treats as relevant to EVERY project, whatever its path:
+ * `user` (the machine-wide install) and `managed` (administrator policy).
+ *
+ * Exported because a writer has to ask the same question the filter does. A row
+ * in one of these scopes is not this repository's record — moving it forward
+ * changes what every project on the machine loads — so `repairStaleLoad` refuses
+ * to rewrite one instead of quietly reaching that far.
+ */
+export function isMachineWideScope(
+	scope: LoaderScope | string | undefined,
+): boolean {
+	return scope === "user" || scope === "managed";
+}
+
+/** `.git` as an entry of `dir`: a directory (real checkout), a file (pointer), or absent. */
+function gitEntryKind(dir: string): "dir" | "file" | null {
+	try {
+		const stat = fs.statSync(path.join(dir, ".git"));
+		if (stat.isDirectory()) return "dir";
+		if (stat.isFile()) return "file";
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The main repository root behind a linked worktree's `.git` FILE, which holds
+ * `gitdir: <main>/.git/worktrees/<name>`.
+ *
+ * The `.git` component is searched for first and the `worktrees` component only
+ * as a fallback, because the former sits ABOVE the latter in the usual layout
+ * and matching `worktrees` first would answer `<main>/.git`. The fallback is
+ * for a common directory kept outside a `.git` directory (a bare
+ * `/srv/repo.git/worktrees/<name>`), where the repository itself is the closest
+ * thing to a root. The same walk maps a submodule's
+ * `<super>/.git/modules/<name>` onto the superproject root.
+ */
+function mainRootFromGitFile(gitFile: string, dir: string): string | null {
+	let gitdir: string;
+	try {
+		const match = /^\s*gitdir:\s*(.+?)\s*$/m.exec(
+			fs.readFileSync(gitFile, "utf8"),
+		);
+		// A `.git` file we cannot parse still marks a working tree, and `dir` is
+		// the only root it could name.
+		if (!match?.[1]) return dir;
+		gitdir = path.resolve(dir, match[1]);
+	} catch {
+		return dir;
+	}
+
+	for (const component of [".git", "worktrees"]) {
+		let cur = gitdir;
+		for (;;) {
+			const parent = path.dirname(cur);
+			if (path.basename(cur) === component) return parent;
+			if (parent === cur) break;
+			cur = parent;
+		}
+	}
+	return gitdir;
+}
+
+/**
+ * The repository root containing `p`, or null when it is in no repository.
+ *
+ * PATH-BASED, never a `git` subprocess, and that is the whole point: registry
+ * rows for DELETED worktrees still take part in the selection below, and every
+ * git command fails on a directory that is not there — so a subprocess
+ * implementation returns "no root" for exactly the entries that decide the
+ * answer. Walking up works on a path that does not exist: the nearest surviving
+ * ancestor still carries the `.git` entry.
+ */
+export function repoRootForPath(
+	p: string,
+	cache?: RepoRootCache,
+): string | null {
+	if (!p) return null;
+	const start = path.resolve(p);
+	const memo = cache?.get(start);
+	if (memo !== undefined) return memo;
+
+	let dir = start;
+	let root: string | null = null;
+	for (;;) {
+		const kind = gitEntryKind(dir);
+		if (kind === "dir") {
+			root = dir;
+			break;
+		}
+		if (kind === "file") {
+			root = mainRootFromGitFile(path.join(dir, ".git"), dir);
+			break;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	cache?.set(start, root);
+	return root;
+}
+
+/**
+ * `SF` — is this installation relevant to the current project?
+ *
+ * Three ways to be relevant, and the third is the one that surprises people: a
+ * row installed ANYWHERE in the same repository counts, including a worktree
+ * that has since been deleted. Nothing prunes those rows, so they keep voting.
+ *
+ * @param cwdRoot {@link repoRootForPath} of `cwd`, resolved once by the caller
+ *                because it is the same answer for every entry.
+ */
+export function isRelevantInstallation(
+	entry: InstalledPluginEntry,
+	cwd: string,
+	cwdRoot: string | null,
+	cache?: RepoRootCache,
+): boolean {
+	if (isMachineWideScope(entry.scope)) return true;
+	if (!entry.projectPath) return false;
+
+	// The binary compares the two paths as raw strings. They are normalised here
+	// first, which can only turn a spelling difference of the same directory
+	// ("/p/a/" vs "/p/a") into a match — and that same pair already matches on
+	// the repository-root comparison below, which normalises on the way through.
+	if (path.resolve(entry.projectPath) === path.resolve(cwd)) return true;
+
+	// NULL MATCHES NULL, because the original's `repoRoot(entry.projectPath) ===
+	// repoRoot(originalCwd)` does: two directories in no repository at all compare
+	// equal there, so every rootless row competes when Claude Code runs from a
+	// scratch directory, a home directory, or any plain non-git folder.
+	//
+	// This used to `return false` on a null `cwdRoot`, on the reasoning that two
+	// unrelated rootless directories are not the same project. That reasoning is
+	// magus policy, and this module holds none: with it, magus could name a
+	// `loadedVersion` the loader would not pick, and a repair would skip the very
+	// rows the loader treats as relevant — the same class of wrong answer the port
+	// exists to eliminate.
+	//
+	// The policy did not disappear, it moved to where it belongs: `repairStaleLoad`
+	// rewrites a row only when it belongs to THIS repository, which requires either
+	// the exact same directory or a non-null shared root. So a rootless row from an
+	// unrelated directory is reported as relevant (true) and never written (correct).
+	return repoRootForPath(entry.projectPath, cache) === cwdRoot;
+}
+
+/**
+ * `Bls` — the entry the loader will use, or undefined when it loads nothing.
+ *
+ * Faithful to the decompiled original, including the two parts that look like
+ * bugs and are load-bearing:
+ *
+ *  - The single-candidate branch returns WITHOUT checking that `installPath`
+ *    exists. One relevant row means that row loads (or fails to), whatever is
+ *    on disk.
+ *  - `firstValid` is captured BEFORE the existence test, so the fallback is the
+ *    first entry that merely HAS an `installPath` — not the first existing one.
+ *
+ * ARRAY ORDER decides ties, and array order is install order. It is not sorted
+ * by version, by scope, or by recency, so an older install made earlier beats a
+ * newer one made later. That is the madbench 0.3.0 defect in one sentence.
+ */
+export function pickLoadedEntry(
+	entries: readonly InstalledPluginEntry[] | undefined,
+	cwd: string,
+	cache?: RepoRootCache,
+): InstalledPluginEntry | undefined {
+	if (!Array.isArray(entries) || entries.length === 0) return undefined;
+
+	const cwdRoot = repoRootForPath(cwd, cache);
+	const relevant = entries.filter((e) =>
+		isRelevantInstallation(e, cwd, cwdRoot, cache),
+	);
+	if (relevant.length === 0) return undefined;
+	if (relevant.length === 1) return relevant[0];
+
+	let firstValid: InstalledPluginEntry | undefined;
+	for (const entry of relevant) {
+		if (!entry.installPath) continue;
+		if (firstValid === undefined) firstValid = entry;
+		if (fs.existsSync(entry.installPath)) return entry;
+	}
+	return firstValid ?? relevant[0];
+}
+
+/**
+ * pluginId → the version that will actually load in `cwd`.
+ *
+ * Plugins whose winning entry carries no version are absent from the map rather
+ * than present with a placeholder: "no version recorded" is not "loads nothing",
+ * and a caller comparing against it must be able to tell.
+ */
+export function resolveLoadedVersions(
+	registry: InstalledPluginsRegistry,
+	cwd: string,
+): Record<string, string> {
+	// One cache for the whole pass: the same few hundred project paths repeat
+	// across every plugin in the registry.
+	const cache: RepoRootCache = new Map();
+	const out: Record<string, string> = {};
+	for (const [pluginId, entries] of Object.entries(registry.plugins ?? {})) {
+		const pick = pickLoadedEntry(entries, cwd, cache);
+		if (pick?.version) out[pluginId] = pick.version;
+	}
+	return out;
+}

package/src/services/update-engine.ts

@@ -40,6 +40,10 @@ import { formatCommand } from "../utils/command-utils.js";
 import { runCommand } from "../utils/run.js";
 import type { PluginScope } from "./claude-cli.js";
 import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
+import {
+	type StaleLoadRepairResult,
+	repairStaleLoad,
+} from "./claude-settings.js";
 import {
 	readInstalledVersionForScope,
 	saveInstalledPluginVersionForScope,
@@ -165,6 +169,18 @@ export interface PluginApplyDeps {
 		scope: PluginScope,
 		projectPath: string,
 	) => Promise<void>;
+	/**
+	 * The `stale-load` repair — NOT a Claude Code command, and the only dep here
+	 * that is not. No `claude plugin` invocation can reach the registry rows that
+	 * cause a stale load, so this one edits `installed_plugins.json` directly;
+	 * `repairStaleLoad`'s own doc comment carries the full reasoning and the
+	 * user's approval of the exception.
+	 */
+	repairStaleLoad: (
+		pluginId: string,
+		target: string,
+		projectPath: string,
+	) => Promise<StaleLoadRepairResult>;
 }
 
 export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
@@ -173,6 +189,7 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
 	repair: repairPlugin,
 	readInstalled: readInstalledVersionForScope,
 	saveInstalled: saveInstalledPluginVersionForScope,
+	repairStaleLoad,
 };
 
 // -- selection ---------------------------------------------------------------
@@ -189,7 +206,18 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
  * project row stays untouched, so the same drift reappears on the next run.
  */
 function scopesToApply(item: PluginUpdateItem): PluginScope[] {
-	if (item.action === "current" || item.action === "unknown") return [];
+	// `stale-load` has no scopes, and that is not "skipped": it is applied by
+	// `repairStaleLoad`, which rewrites registry rows rather than installing
+	// anything, so there is no per-scope work to enumerate. A reinstall is
+	// measured NOT to clear it — it writes another row for this project while the
+	// row the loader picks belongs to a different one — which is exactly why it
+	// must not come through here. {@link pluginNeedsWork} counts it separately.
+	if (
+		item.action === "current" ||
+		item.action === "unknown" ||
+		item.action === "stale-load"
+	)
+		return [];
 	return item.action === "install" ? ["project"] : item.scopes;
 }
 
@@ -200,9 +228,12 @@ function scopesToApply(item: PluginUpdateItem): PluginScope[] {
  * predicate the loop applies. Re-deriving it at the call site is how the two
  * drift, and a bar that stops short of full at the end of a successful run
  * looks exactly like a hang.
+ *
+ * `stale-load` is work without scopes — see {@link scopesToApply} — so it is
+ * named here rather than counted through the scope list.
  */
 export function pluginNeedsWork(item: PluginUpdateItem): boolean {
-	return scopesToApply(item).length > 0;
+	return item.action === "stale-load" || scopesToApply(item).length > 0;
 }
 
 // -- plugins -----------------------------------------------------------------
@@ -277,6 +308,67 @@ function pluginNoMove(
 	return null;
 }
 
+/**
+ * Repair ONE broken plugin — the `stale-load` half of {@link applyPlugins}.
+ *
+ * Success is the repair's own POST-WRITE assertion (`StaleLoadRepairResult.ok`),
+ * never "the call returned". The whole class of bug this state reports is a
+ * version that looks right and does not load, so a repair that rewrote rows
+ * without changing what the loader resolves is a FAILURE and says so.
+ */
+async function applyStaleLoad(
+	item: PluginUpdateItem,
+	projectPath: string,
+	deps: PluginApplyDeps,
+	report: ApplyReporter,
+	result: PluginApplyResult,
+): Promise<void> {
+	report.begin(item.pluginId);
+	const startedAt = Date.now();
+	// The classifier sets this to the version installed here; a null one means
+	// there is nothing on disk to point the rows at, so there is no repair to run.
+	if (!item.target) {
+		report.finish(
+			false,
+			item.pluginId,
+			`no installed version to point ${item.pluginId}'s registry rows at`,
+			Date.now() - startedAt,
+		);
+		result.failed.push(item.pluginId);
+		return;
+	}
+	try {
+		const outcome = await deps.repairStaleLoad(
+			item.pluginId,
+			item.target,
+			projectPath,
+		);
+		if (outcome.ok) {
+			report.finish(
+				true,
+				item.pluginId,
+				`registry → v${outcome.target} (${outcome.rewritten} row${
+					outcome.rewritten === 1 ? "" : "s"
+				} moved forward)`,
+				Date.now() - startedAt,
+			);
+			result.ok++;
+		} else {
+			report.finish(
+				false,
+				item.pluginId,
+				outcome.error ?? `${item.pluginId} still does not load v${item.target}`,
+				Date.now() - startedAt,
+			);
+			result.failed.push(item.pluginId);
+		}
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		report.finish(false, item.pluginId, msg, Date.now() - startedAt);
+		result.failed.push(item.pluginId);
+	}
+}
+
 export async function applyPlugins(
 	items: PluginUpdateItem[],
 	projectPath: string,
@@ -291,6 +383,16 @@ export async function applyPlugins(
 	};
 
 	for (const item of items) {
+		// A stale load is repaired in the REGISTRY, not by any installer, so it
+		// leaves the scope loop entirely. Its own branch rather than a scope with a
+		// special case inside: everything below reads back a per-scope version and
+		// compares it against the catalog, and none of those questions applies to a
+		// row rewrite.
+		if (item.action === "stale-load") {
+			await applyStaleLoad(item, projectPath, deps, report, result);
+			continue;
+		}
+
 		const scopes = scopesToApply(item);
 		if (scopes.length === 0) continue;