magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/plugin-manager.ts

@@ -0,0 +1,847 @@
+import path from "node:path";
+import { defaultMarketplaces } from "../data/marketplaces.js";
+import type {
+	InstalledPluginsRegistry,
+	PluginRelease,
+} from "../types/index.js";
+import { formatMarketplaceName, parsePluginId } from "../utils/string-utils.js";
+import type { PluginScope } from "./claude-cli.js";
+import {
+	getConfiguredMarketplaces,
+	getEnabledPlugins,
+	getGlobalClaudeDir,
+	getGlobalConfiguredMarketplaces,
+	getGlobalEnabledPlugins,
+	getGlobalInstalledPluginVersions,
+	getLocalEnabledPlugins,
+	getLocalInstalledPluginVersions,
+	getProjectInstalledPluginVersions,
+	pickRegistryEntry,
+	readInstalledPluginsRegistry,
+	readSettings,
+	removeFromInstalledPluginsRegistry,
+	saveGlobalInstalledPluginVersion,
+	saveLocalInstalledPluginVersion,
+	updateInstalledPluginsRegistry,
+	writeSettings,
+} from "./claude-settings.js";
+import { hasContentDrift } from "./content-drift.js";
+import { inheritablePaths } from "./git-worktree.js";
+import {
+	type LocalMarketplace,
+	type ProgressCallback,
+	type RepairMarketplaceResult,
+	repairAllMarketplaces,
+	scanLocalMarketplaces,
+} from "./local-marketplace.js";
+import {
+	type CatalogSource,
+	type MarketplaceFetchFailure,
+	type MarketplacePlugin,
+	clearMarketplaceCache as clearFetcherCache,
+	clearPersistedCatalogs,
+	fetchMarketplacePlugins,
+	getMarketplaceFetchFailures,
+	isAuthoritative,
+	resolveMarketplacePlugins,
+} from "./marketplace-fetcher.js";
+export {
+	fetchMarketplacePlugins,
+	getMarketplaceFetchFailures,
+	isAuthoritative,
+	resolveMarketplacePlugins,
+	type CatalogSource,
+	type MarketplaceFetchFailure,
+	type MarketplacePlugin,
+};
+// Cache for local marketplaces (session-level) - Promise-based to prevent race conditions
+let localMarketplacesPromise: Promise<Map<string, LocalMarketplace>> | null =
+	null;
+
+export interface ScopeStatus {
+	enabled: boolean;
+	version?: string;
+}
+
+export interface PluginInfo {
+	id: string;
+	name: string;
+	version: string | null;
+	description: string;
+	marketplace: string;
+	marketplaceDisplay: string;
+	enabled: boolean;
+	installedVersion?: string;
+	/**
+	 * Provably behind the catalog, on ONE version pair.
+	 *
+	 * @deprecated Derive plugin state from `classifyPlugin` (update-plan.ts),
+	 * which answers per scope and distinguishes "cannot tell" from "current".
+	 * Nothing in `src/` reads this any more — the content-drift gate was its
+	 * last reader, and it now asks the version pair directly. It is still
+	 * computed because `blackbox-parity.test.ts` reproduces the pre-classifier
+	 * rule from it, which is what proves the fixture discriminates.
+	 *
+	 * Its sibling `updateUnknown` was written in six places and read in none,
+	 * and is gone.
+	 */
+	hasUpdate?: boolean;
+	// Per-scope installation status
+	userScope?: ScopeStatus;
+	projectScope?: ScopeStatus;
+	localScope?: ScopeStatus;
+	// Extended info
+	category?: string;
+	author?: { name: string; email?: string };
+	homepage?: string;
+	tags?: string[];
+	/** Recent release history, newest first. Absent when the manifest publishes none. */
+	releases?: PluginRelease[];
+	agents?: string[];
+	commands?: string[];
+	skills?: string[];
+	mcpServers?: string[];
+	lspServers?: Record<string, unknown>;
+	/**
+	 * The plugin's directory within its marketplace repo, as the manifest
+	 * declares it ("./" for a repo that is one plugin, "./plugins/dev" for a
+	 * multi-plugin marketplace). Needed to scope a skill listing to this
+	 * plugin's subtree rather than the whole repo.
+	 */
+	source?: string;
+	/**
+	 * Set only when the plugin's files live in a repo other than its
+	 * marketplace's — an object `source` naming a different repo.
+	 */
+	sourceRepo?: string;
+	isOrphaned?: boolean;
+	/**
+	 * Set when the installed version equals the catalog version, but the
+	 * plugin's files in the marketplace have changed since the commit it was
+	 * installed from. The version compare says "up to date" and is wrong: only
+	 * a reinstall delivers the current content. See content-drift.ts.
+	 */
+	contentStale?: boolean;
+	/**
+	 * Set when this plugin's installed version changed since magus last
+	 * rendered it — including updates made by Claude Code or a direct CLI call
+	 * rather than by magus itself. Drives the "updated" badge.
+	 */
+	recentlyUpdatedFrom?: string;
+	/**
+	 * Set when magus is seeing this plugin installed for the first time.
+	 * Never set on the very first run, when there is no baseline to compare to.
+	 */
+	recentlyInstalled?: boolean;
+	/**
+	 * Which catalog supplied `version` — i.e. the number this plugin's installed
+	 * version was compared against.
+	 *
+	 * `remote` (HTTP) and `remote-git` (a `git fetch`ed remote ref) are both
+	 * authoritative — each is upstream's own catalog file. `local-clone` is the
+	 * checked-out working tree, which is deliberately pinned by
+	 * `autoUpdate: false`, so its versions can be arbitrarily old.
+	 */
+	catalogSource?: CatalogSource;
+	/**
+	 * Set when `hasUpdate: false` could not actually be verified — the catalog
+	 * fetch failed and the comparison ran against the pinned clone.
+	 *
+	 * This exists because the absence of an update was indistinguishable from a
+	 * successful check. A rate-limited fetch returned `[]`, the stale clone filled
+	 * in, its version compared equal to the installed one, and the UI reported
+	 * "up to date" — the failure rendered as a clean bill of health. Anything that
+	 * tells the user they are current must check this flag first.
+	 */
+	updateCheckFailed?: boolean;
+	/** Why the check failed, for display. Set with `updateCheckFailed`. */
+	updateCheckFailure?: MarketplaceFetchFailure;
+}
+
+/**
+ * True when a plugin is enabled in some scope but no installed version resolves
+ * anywhere — it is listed in `enabledPlugins` but was never actually installed.
+ *
+ * This is a broken state, not a healthy one: Claude Code will not load the
+ * plugin, and because the update check is `installedVersion && compare(...)`,
+ * it is also invisible to every update path.
+ * It previously rendered identically to a working install.
+ *
+ * `isOrphaned` is a different failure — installed, but no longer offered by any
+ * marketplace — and is rendered as "deprecated" already.
+ *
+ * "0.0.0" means installed-with-unknown-version (Anthropic's official plugins
+ * record exactly that), so it must NOT count as missing.
+ */
+export function isEnabledButNotInstalled(plugin: PluginInfo): boolean {
+	if (plugin.isOrphaned) return false;
+	const enabledSomewhere =
+		!!plugin.userScope?.enabled ||
+		!!plugin.projectScope?.enabled ||
+		!!plugin.localScope?.enabled;
+	return enabledSomewhere && !plugin.installedVersion;
+}
+
+/**
+ * True when a scope genuinely has the plugin installed.
+ *
+ * `enabled` on its own is not proof. It is the `enabledPlugins` flag out of a
+ * settings file, and only magus and the user maintain it; `version` comes
+ * from `installed_plugins.json` via `overlayRegistryVersions`, which is what
+ * Claude Code actually loaded. When the two disagree — flag set, no registry
+ * entry — the plugin is in the broken enabled-but-not-installed state that the
+ * list already renders as "not installed".
+ *
+ * Every action that touches the filesystem must use this, not the flag alone.
+ * Deciding on the flag is what made the scope keys uninstall a plugin the row
+ * had just labelled "not installed".
+ *
+ * A version of "0.0.0" still counts as installed — Anthropic's official plugins
+ * record exactly that — which is why this tests presence, not `isKnownVersion`.
+ */
+export function isInstalledInScope(scope: ScopeStatus | undefined): boolean {
+	// Presence of files, NOT permission to load them. `enabled` was in this
+	// test until it was measured: a plugin with a real registry row that the
+	// user had simply switched off reported "not installed", so the row offered
+	// to install what was already on disk. Installation is a registry fact;
+	// enablement is a separate one, and `isEnabledButNotInstalled` is where the
+	// broken combination of the two is named.
+	return !!scope?.version;
+}
+
+/**
+ * One scope's status, from the two facts that define it.
+ *
+ * Exported and taken as arguments so this is testable and has exactly one
+ * implementation. It previously lived inline in `getAvailablePlugins` and its
+ * global twin — two copies, and both keyed existence off the settings flag:
+ *
+ *   enabledPlugins[id] !== undefined ? {...} : undefined
+ *
+ * so a plugin with a registry row but no settings key produced NO scope at all
+ * and rendered exactly like one that was never installed. Existence is now
+ * "either fact is present", and `enabled` defaults to false rather than
+ * deciding whether the scope exists.
+ */
+export function buildScopeStatus(
+	enabledPlugins: Record<string, boolean>,
+	installedVersions: Record<string, string>,
+	pluginId: string,
+): ScopeStatus | undefined {
+	const enabled = enabledPlugins[pluginId];
+	const version = installedVersions[pluginId];
+	if (enabled === undefined && version === undefined) return undefined;
+	return { enabled: enabled === true, version };
+}
+
+/**
+ * What a scope toggle (`u` / `p` / `l`, or the Enter scope picker) should do.
+ *
+ * `install` doubles as the repair for enabled-but-not-installed. Measured
+ * against Claude Code 2.1.223 in exactly that state — `dev@magus` flagged in
+ * `.claude/settings.json` with no registry entry for the project path —
+ * `claude plugin install dev@magus --scope project` installed it normally and
+ * wrote the registry entry. It does not report "already installed", so this
+ * needs no uninstall-first dance (unlike content drift, see repairPlugin).
+ *
+ * `behind` is the answer to "is this scope provably behind?", and it comes from
+ * the plugin classifier (`scopeIsBehind` in update-plan.ts), never from a
+ * comparison made here. This used to take the catalog version and compare raw
+ * strings — a fourth "is it behind?" rule, which offered `update` for a scope
+ * AHEAD of the catalog or one whose version cannot be ordered at all, while the
+ * row beside it said something else.
+ */
+export function resolveScopeAction(
+	scope: ScopeStatus | undefined,
+	behind: boolean,
+): "install" | "update" | "uninstall" {
+	// `enabled` is deliberately part of THIS decision even though it is no longer
+	// part of `isInstalledInScope`. The two ask different questions:
+	// "is it on disk" (installation) versus "what should this key do next".
+	//
+	// Installed-but-disabled must NOT resolve to uninstall. The scope key runs
+	// `cliUninstallPlugin` with no confirmation, so that combination would delete
+	// a plugin the user had merely switched off — with the row beside it showing
+	// no scope square, which reads as "not installed" and invites the press.
+	// `install` re-installs and re-enables, which is what the key meant before
+	// installation and enablement were separated, and is the only non-destructive
+	// answer here.
+	if (!isInstalledInScope(scope) || !scope?.enabled) return "install";
+	return behind ? "update" : "uninstall";
+}
+
+export async function getAvailablePlugins(
+	projectPath?: string,
+): Promise<PluginInfo[]> {
+	const configuredMarketplaces = await getConfiguredMarketplaces(projectPath);
+	const enabledPlugins = await getEnabledPlugins(projectPath);
+	const installedVersions = await getInstalledPluginVersions(projectPath);
+
+	// Fetch all scopes for per-scope status
+	const userEnabledPlugins = await getGlobalEnabledPlugins();
+	const userInstalledVersions = await getGlobalInstalledPluginVersions();
+	const projectEnabledPlugins = await getEnabledPlugins(projectPath);
+	const projectInstalledVersions =
+		await getInstalledPluginVersions(projectPath);
+	const localEnabledPlugins = await getLocalEnabledPlugins(projectPath);
+	const localInstalledVersions =
+		await getLocalInstalledPluginVersions(projectPath);
+
+	const plugins: PluginInfo[] = [];
+	const seenPluginIds = new Set<string>();
+
+	// Helper to build scope status
+	// One implementation, shared with the global view and unit-tested. Both
+	// copies used to key scope existence off the settings flag, so an installed
+	// plugin with no settings key produced no scope at all.
+	const scopeStatusFor = (pluginId: string) => ({
+		userScope: buildScopeStatus(
+			userEnabledPlugins,
+			userInstalledVersions,
+			pluginId,
+		),
+		projectScope: buildScopeStatus(
+			projectEnabledPlugins,
+			projectInstalledVersions,
+			pluginId,
+		),
+		localScope: buildScopeStatus(
+			localEnabledPlugins,
+			localInstalledVersions,
+			pluginId,
+		),
+	});
+
+	// Get all marketplace names (configured + official/featured defaults)
+	// Always include official and featured marketplaces so users can browse them
+	const marketplaceNames = new Set<string>();
+	for (const mp of defaultMarketplaces) {
+		if (
+			configuredMarketplaces[mp.name] ||
+			mp.official ||
+			mp.featured ||
+			mp.owned
+		) {
+			marketplaceNames.add(mp.name);
+		}
+	}
+
+	// Fetch local marketplace caches up front so we can detect stale caches
+	let localMarketplaces = await getLocalMarketplaces();
+
+	// Resolve every marketplace concurrently. These are independent HTTP calls
+	// with a 10s timeout each; awaited in sequence, one unreachable marketplace
+	// added its full timeout to the "Loading..." the user stares at. Measured on
+	// six marketplaces with four unreachable: 44.9s sequential.
+	const resolutions = await Promise.all(
+		[...marketplaceNames].map(async (mpName) => {
+			const marketplace = defaultMarketplaces.find((m) => m.name === mpName);
+			if (!marketplace) return null;
+			return {
+				mpName,
+				marketplace,
+				resolution: await resolveMarketplacePlugins(
+					mpName,
+					marketplace.source.repo,
+					localMarketplaces,
+				),
+			};
+		}),
+	);
+
+	for (const entry of resolutions) {
+		if (!entry) continue;
+		const { mpName, marketplace, resolution } = entry;
+		const marketplacePlugins = resolution.plugins;
+
+		// Auto-sync local cache if remote has plugins the local cache doesn't
+		localMarketplaces = await autoSyncIfStale(
+			mpName,
+			marketplacePlugins.map((p) => p.name),
+			localMarketplaces,
+		);
+
+		// The catalog that answered was not the authoritative one, so every
+		// version compare below is a guess, not a check.
+		// `remote-git` counts as verified: it is upstream's own catalog file, read
+		// through a git remote ref rather than over HTTP. Only the pinned working
+		// tree (`local-clone`) is untrustworthy for versions.
+		const unverified = !isAuthoritative(resolution.source);
+
+		for (const plugin of marketplacePlugins) {
+			const pluginId = `${plugin.name}@${mpName}`;
+			const installedVersion = installedVersions[pluginId];
+			const isEnabled = enabledPlugins[pluginId] === true;
+			const scopeStatus = scopeStatusFor(pluginId);
+
+			seenPluginIds.add(pluginId);
+			plugins.push({
+				id: pluginId,
+				name: plugin.name,
+				version: plugin.version,
+				description: plugin.description,
+				marketplace: mpName,
+				marketplaceDisplay: marketplace.displayName,
+				enabled: isEnabled,
+				installedVersion: installedVersion,
+				hasUpdate: isBehind(plugin.version, installedVersion) === true,
+				catalogSource: resolution.source,
+				updateCheckFailed: unverified,
+				updateCheckFailure: resolution.failure,
+				...scopeStatus,
+				category: plugin.category,
+				author: plugin.author,
+				homepage: plugin.homepage,
+				tags: plugin.tags,
+				releases: plugin.releases,
+				source: plugin.source,
+				sourceRepo: plugin.sourceRepo,
+			});
+		}
+	}
+
+	for (const [mpName, localMp] of localMarketplaces) {
+		// Skip if already fetched from defaults
+		if (marketplaceNames.has(mpName)) continue;
+
+		// Add ALL plugins from this local marketplace cache
+		for (const localPlugin of localMp.plugins) {
+			const pluginId = `${localPlugin.name}@${mpName}`;
+			if (seenPluginIds.has(pluginId)) continue;
+
+			const installedVersion = installedVersions[pluginId];
+			const isEnabled = enabledPlugins[pluginId] === true;
+			const scopeStatus = scopeStatusFor(pluginId);
+
+			seenPluginIds.add(pluginId);
+			plugins.push({
+				id: pluginId,
+				name: localPlugin.name,
+				version: localPlugin.version,
+				description: localPlugin.description || "",
+				marketplace: mpName,
+				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
+				enabled: isEnabled,
+				installedVersion: installedVersion,
+				hasUpdate: isBehind(localPlugin.version, installedVersion) === true,
+				...scopeStatus,
+				category: localPlugin.category,
+				author: localPlugin.author,
+				agents: localPlugin.agents,
+				commands: localPlugin.commands,
+				skills: localPlugin.skills,
+				source: localPlugin.source,
+				mcpServers: localPlugin.mcpServers,
+				lspServers: localPlugin.lspServers,
+				releases: localPlugin.releases,
+			});
+		}
+	}
+
+	// Add orphaned plugins (enabled/installed but not in any cache)
+	const allPluginIds = new Set([
+		...Object.keys(enabledPlugins),
+		...Object.keys(installedVersions),
+	]);
+
+	for (const pluginId of allPluginIds) {
+		if (seenPluginIds.has(pluginId)) continue;
+
+		const parsed = parsePluginId(pluginId);
+		if (!parsed) continue;
+
+		const { pluginName, marketplace: mpName } = parsed;
+		const installedVersion = installedVersions[pluginId];
+		const isEnabled = enabledPlugins[pluginId] === true;
+		const scopeStatus = scopeStatusFor(pluginId);
+
+		// Try to get plugin info from local marketplace cache (fallback)
+		const localMp = localMarketplaces.get(mpName);
+		const localPlugin = localMp?.plugins.find((p) => p.name === pluginName);
+
+		const latestVersion = localPlugin?.version || installedVersion || "unknown";
+		const description = localPlugin?.description || "Installed plugin";
+		const hasUpdate = isBehind(localPlugin?.version, installedVersion) === true;
+
+		plugins.push({
+			id: pluginId,
+			name: pluginName,
+			version: latestVersion,
+			description,
+			marketplace: mpName,
+			marketplaceDisplay: localMp?.name || formatMarketplaceName(mpName),
+			enabled: isEnabled,
+			installedVersion: installedVersion,
+			hasUpdate,
+			isOrphaned: true,
+			...scopeStatus,
+		});
+	}
+
+	await annotateContentDrift(plugins, "project", projectPath);
+	return plugins;
+}
+
+/**
+ * Is this plugin one whose files could have moved while its version did not?
+ *
+ * Drift is defined as "same version, different files", so it is only a
+ * question at all when the catalog version and the installed version are
+ * PROVABLY the same — `compareVersions` returning exactly 0, never null, which
+ * would be "cannot tell". A pending version bump is not drift: `hasContentDrift`
+ * compares the installed commit's subtree against the marketplace clone's HEAD,
+ * and for a plugin that is simply behind, that subtree differs BECAUSE of the
+ * newer version. Flagging it would turn an `update` into a `repair`, and a
+ * repair reinstalls whatever the clone holds — past a pin.
+ *
+ * This used to open with `if (plugin.hasUpdate || …)`, the pre-classifier
+ * boolean. It decided nothing the version compare below does not (`isBehind`
+ * cannot be true for a pair that compares 0), and gating the input the shared
+ * classifier reads on the rule it replaced is how the two drift apart again.
+ * An orphan is still excluded: it has no marketplace entry to diff against.
+ *
+ * Exported to be tested directly; `annotateContentDrift` itself needs the real
+ * registry.
+ */
+export function contentDriftCandidate(plugin: PluginInfo): boolean {
+	if (plugin.isOrphaned) return false;
+	if (!plugin.installedVersion || !plugin.version) return false;
+	return compareVersions(plugin.version, plugin.installedVersion) === 0;
+}
+
+/**
+ * Flag plugins whose files moved without their version moving.
+ *
+ * Runs after the plugin list is assembled so every code path that builds a
+ * PluginInfo gets the same treatment. Which plugins are worth asking about is
+ * {@link contentDriftCandidate}.
+ *
+ * Best-effort throughout: a plugin whose drift cannot be determined is left
+ * exactly as it is today.
+ */
+async function annotateContentDrift(
+	plugins: PluginInfo[],
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<void> {
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = await readInstalledPluginsRegistry();
+	} catch {
+		return;
+	}
+
+	// Must match how the version itself was resolved. Without this a worktree
+	// inherits an installed version but never its `gitCommitSha`, so drift
+	// detection silently switches off for exactly the plugins that just started
+	// reporting as installed.
+	const target = scope === "user" ? undefined : (projectPath ?? process.cwd());
+	const fallbackPaths = target ? await inheritablePaths(target) : [];
+
+	await Promise.all(
+		plugins.map(async (plugin) => {
+			if (!contentDriftCandidate(plugin)) return;
+
+			const entry = pickRegistryEntry(
+				registry.plugins[plugin.id],
+				scope,
+				target,
+				fallbackPaths,
+			);
+			if (!entry?.gitCommitSha) return;
+
+			try {
+				plugin.contentStale = await hasContentDrift({
+					marketplace: plugin.marketplace,
+					pluginName: plugin.name,
+					installedSha: entry.gitCommitSha,
+					installedVersion: plugin.installedVersion,
+				});
+			} catch {
+				/* leave unflagged */
+			}
+		}),
+	);
+}
+
+/** A dotted run of digits, optionally `v`-prefixed. Anything else is opaque. */
+const SEMVER_ISH = /^\d+(\.\d+)*$/;
+
+const normalize = (v: string) => v.replace(/^v/, "");
+
+/**
+ * Version comparison: 1 if a > b, -1 if a < b, 0 if equal, **null if the pair
+ * carries no ordering at all**.
+ *
+ * `null` is the whole point. This used to return 0 for every unorderable pair,
+ * and 0 means "equal" to every caller — so "I cannot tell" was indistinguishable
+ * from "they match". Measured against real registry values before the fix:
+ *
+ *   compareVersions("517b2fcd1b60", "b819188d2eea") = 0   ← two DIFFERENT commits
+ *   compareVersions("7.2.0",        "517b2fcd1b60") = 1   ← a fabricated ordering
+ *
+ * Anthropic's official plugins record a commit sha as their version, so the
+ * first line made every one of them permanently un-updatable, and the second
+ * invented an update whenever a sha met a semver.
+ *
+ * Three cases, and only the first has an answer:
+ * - both dotted-numeric → compare numerically, shorter side zero-padded
+ * - both opaque         → equal strings are 0; different strings are `null`,
+ *                         because two commit ids carry no order between them
+ * - one of each         → `null`; there is no shared scale
+ *
+ * A missing side is `null` too. It used to be 0, which claimed an absent
+ * version matched a present one.
+ *
+ * Callers asking "should this be updated?" want {@link isBehind}, not this.
+ */
+export function compareVersions(
+	a: string | null | undefined,
+	b: string | null | undefined,
+): number | null {
+	if (!a || !b) return null;
+	const A = normalize(a);
+	const B = normalize(b);
+
+	const aNumeric = SEMVER_ISH.test(A);
+	const bNumeric = SEMVER_ISH.test(B);
+
+	if (aNumeric !== bNumeric) return null; // no shared scale
+	if (!aNumeric) return A === B ? 0 : null; // two opaque ids: equal, or unordered
+
+	const partsA = A.split(".").map(Number);
+	const partsB = B.split(".").map(Number);
+	for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+		const numA = partsA[i] ?? 0;
+		const numB = partsB[i] ?? 0;
+		if (numA > numB) return 1;
+		if (numA < numB) return -1;
+	}
+	return 0;
+}
+
+/**
+ * Is `installed` out of date against what the catalog publishes as `latest`?
+ *
+ * `true` / `false` / `null`, where **null means unknown** — never a silent
+ * `false`. This is the question every update path actually asks, and keeping it
+ * separate from {@link compareVersions} is what lets the two opaque-id cases
+ * differ:
+ *
+ * - Ordering two commit shas is impossible, so `compareVersions` says `null`.
+ * - But the catalog is authoritative for what is published *now*, so an
+ *   installed sha that differs from it is **not current** — `isBehind` says
+ *   `true`. That is what makes a sha-versioned plugin updatable at all.
+ *
+ * Not installed is `null`, not `false`. The old inline check was
+ * `installedVersion && compare(...) > 0`, so a plugin with no install at all
+ * evaluated to `false` and was reported — and counted — as up to date.
+ */
+export function isBehind(
+	latest: string | null | undefined,
+	installed: string | null | undefined,
+): boolean | null {
+	if (!latest || !installed) return null;
+	const cmp = compareVersions(latest, installed);
+	if (cmp !== null) return cmp > 0;
+
+	// Unorderable. Two opaque ids that differ still mean "not what is published".
+	const bothOpaque =
+		!SEMVER_ISH.test(normalize(latest)) &&
+		!SEMVER_ISH.test(normalize(installed));
+	return bothOpaque ? true : null;
+}
+
+// Get installed plugin versions from settings.json (shared, not secret)
+async function getInstalledPluginVersions(
+	projectPath?: string,
+): Promise<Record<string, string>> {
+	const settings = await readSettings(projectPath);
+	// Settings alone under-report: Claude Code's own `plugin install` updates the
+	// registry without touching our settings key, so overlay the registry.
+	return getProjectInstalledPluginVersions(
+		settings.installedPluginVersions || {},
+		projectPath,
+	);
+}
+
+// Save installed plugin version to settings.json
+export async function saveInstalledPluginVersion(
+	pluginId: string,
+	version: string,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readSettings(projectPath);
+	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions[pluginId] = version;
+	await writeSettings(settings, projectPath);
+
+	// Update installed_plugins.json registry
+	await updateInstalledPluginsRegistry(
+		pluginId,
+		version,
+		"project",
+		projectPath ? path.resolve(projectPath) : undefined,
+	);
+}
+
+/**
+ * The version Claude Code's own registry records for a plugin at a scope, read
+ * fresh from disk.
+ *
+ * Exists because `claude plugin install` takes NO version argument — it installs
+ * whatever the marketplace currently publishes. The version we asked for and the
+ * version we got are therefore different questions, and only this one can answer
+ * the second. Callers must record what this returns, never what they intended:
+ * writing the intent fabricates state that the drift gate then trusts.
+ */
+export async function readInstalledVersionForScope(
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string = process.cwd(),
+): Promise<string | null> {
+	const registry = await readInstalledPluginsRegistry();
+	const entry = pickRegistryEntry(
+		registry.plugins?.[pluginId],
+		scope,
+		projectPath,
+	);
+	return entry?.version ?? null;
+}
+
+/**
+ * Record an installed version in the settings file that owns the given scope.
+ *
+ * Claude Code's CLI does not maintain `installedPluginVersions`, so magus
+ * keeps its own copy. Writing it at the WRONG scope is worse than not writing
+ * it: it makes a scope claim a version it does not have installed. Writing the
+ * wrong VERSION is worse still — see {@link readInstalledVersionForScope}.
+ */
+export async function saveInstalledPluginVersionForScope(
+	pluginId: string,
+	version: string,
+	scope: PluginScope,
+	projectPath: string = process.cwd(),
+): Promise<void> {
+	if (scope === "user") {
+		await saveGlobalInstalledPluginVersion(pluginId, version);
+	} else if (scope === "local") {
+		await saveLocalInstalledPluginVersion(pluginId, version, projectPath);
+	} else {
+		await saveInstalledPluginVersion(pluginId, version, projectPath);
+	}
+}
+
+// Remove installed plugin version from settings.json
+export async function removeInstalledPluginVersion(
+	pluginId: string,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readSettings(projectPath);
+	if (settings.installedPluginVersions) {
+		delete settings.installedPluginVersions[pluginId];
+	}
+	if (settings.enabledPlugins) {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeSettings(settings, projectPath);
+
+	// Remove from installed_plugins.json registry
+	await removeFromInstalledPluginsRegistry(
+		pluginId,
+		"project",
+		projectPath ? path.resolve(projectPath) : undefined,
+	);
+}
+
+// Clear marketplace cache
+export function clearMarketplaceCache(): void {
+	clearFetcherCache();
+	localMarketplacesPromise = null;
+}
+
+// Get local marketplaces (with Promise-based caching to prevent race conditions)
+async function getLocalMarketplaces(): Promise<Map<string, LocalMarketplace>> {
+	if (localMarketplacesPromise === null) {
+		localMarketplacesPromise = scanLocalMarketplaces();
+	}
+	return localMarketplacesPromise;
+}
+
+// Export local marketplaces for use in other modules
+export async function getLocalMarketplacesInfo(): Promise<
+	Map<string, LocalMarketplace>
+> {
+	return getLocalMarketplaces();
+}
+
+// Track which marketplaces have already been auto-synced this session
+// so we only attempt the update once per marketplace per magus run.
+const autoSyncedMarketplaces = new Set<string>();
+
+/**
+ * If the remote manifest lists plugins that aren't in the local cache,
+ * the local clone is stale. Log a warning but do NOT trigger a marketplace
+ * update from magus.
+ *
+ * Previously this called `updateMarketplace()` which invokes Claude Code's
+ * `cacheMarketplaceFromGit()` — a non-atomic delete-then-clone that can
+ * permanently delete the marketplace directory on clone failure.
+ * Claude Code's own background autoupdate handles marketplace refreshing
+ * after session start. See: ai-docs/plugin-marketplace-bug-investigation.md
+ */
+async function autoSyncIfStale(
+	mpName: string,
+	remotePluginNames: string[],
+	localMarketplaces: Map<string, LocalMarketplace>,
+): Promise<Map<string, LocalMarketplace>> {
+	if (autoSyncedMarketplaces.has(mpName)) return localMarketplaces;
+
+	const localMp = localMarketplaces.get(mpName);
+	if (!localMp) return localMarketplaces;
+
+	const localNames = new Set(localMp.plugins.map((p) => p.name));
+	const missingPlugins = remotePluginNames.filter(
+		(name) => !localNames.has(name),
+	);
+	if (missingPlugins.length === 0) return localMarketplaces;
+
+	autoSyncedMarketplaces.add(mpName);
+	// Log stale state but don't trigger update — Claude Code handles refresh
+	console.log(
+		`ℹ Marketplace ${mpName} is stale (missing: ${missingPlugins.join(", ")}). Claude Code will auto-update on next session start.`,
+	);
+	return localMarketplaces;
+}
+
+export interface RefreshAndRepairResult {
+	refresh: never[];
+	repair: RepairMarketplaceResult[];
+}
+
+/**
+ * Refresh magus's internal cache
+ * Note: Marketplace updates should be done via Claude Code's /plugin marketplace update command
+ */
+export async function refreshAllMarketplaces(
+	onProgress?: ProgressCallback,
+): Promise<RefreshAndRepairResult> {
+	onProgress?.({ current: 1, total: 1, name: "Clearing cache..." });
+
+	// Clear all caches to force fresh data. The on-disk catalog cache is awaited
+	// rather than fired and forgotten, so the refetch that follows cannot read the
+	// entries this is discarding.
+	clearMarketplaceCache();
+	await clearPersistedCatalogs();
+
+	// Auto-repair plugin.json files with missing agents/commands/skills
+	const repairResults = await repairAllMarketplaces();
+
+	return {
+		refresh: [],
+		repair: repairResults,
+	};
+}
+
+// Re-export types for consumers
+export type { ProgressCallback };