magus-cli 7.5.2 → 7.5.4

package/src/services/plugin-manager.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { defaultMarketplaces } from "../data/marketplaces.js";
 import type {
+	InstalledPluginEntry,
 	InstalledPluginsRegistry,
 	PluginRelease,
 } from "../types/index.js";
@@ -17,6 +18,7 @@ import {
 	getLocalInstalledPluginVersions,
 	getProjectInstalledPluginVersions,
 	getSettingsPath,
+	ownRegistryEntry,
 	pickRegistryEntry,
 	readInstalledPluginsRegistry,
 	readSettings,
@@ -61,8 +63,25 @@ export {
 let localMarketplacesPromise: Promise<Map<string, LocalMarketplace>> | null =
 	null;
 
+/**
+ * A plugin's state at one scope. There are exactly two: installed, or not.
+ *
+ * `installed` means the settings file for that scope turns the plugin on,
+ * `enabledPlugins[id] === true` — `~/.claude/settings.json` for user,
+ * `<dir>/.claude/settings.json` for project, `<dir>/.claude/settings.local.json`
+ * for local. That is the fact Claude Code loads by. A registry row alone never
+ * makes it load a plugin: measured on 2.1.281, started in a subdirectory, Claude
+ * Code reads only that directory's `settings.json`. Read it through
+ * {@link isInstalledInScope}, never directly.
+ *
+ * `version` is the registry version that loads at this scope, and it can be
+ * inherited from another checkout of the same repository. It means something
+ * only where the plugin is installed — {@link versionInScope} hides it
+ * everywhere else. Installed with no version is the one broken sub-state,
+ * {@link scopeFilesMissing}.
+ */
 export interface ScopeStatus {
-	enabled: boolean;
+	installed: boolean;
 	version?: string;
 }
 
@@ -73,7 +92,14 @@ export interface PluginInfo {
 	description: string;
 	marketplace: string;
 	marketplaceDisplay: string;
-	enabled: boolean;
+	/**
+	 * The highest version at a scope where the plugin is INSTALLED —
+	 * {@link highestInstalledVersion}, the classifier's `installed`. Undefined
+	 * when no installed scope has one: installed nowhere, or installed with its
+	 * files missing. A row inherited from another checkout, at a scope whose
+	 * settings do not turn the plugin on, is not an install Claude Code loads here
+	 * and never supplies this.
+	 */
 	installedVersion?: string;
 	/**
 	 * The version Claude Code's loader will ACTUALLY load in this project, or
@@ -172,91 +198,181 @@ export interface PluginInfo {
 	updateCheckFailure?: MarketplaceFetchFailure;
 }
 
+/** The three scopes a plugin carries — all the installed-state helpers read. */
+type PluginScopes = Pick<
+	PluginInfo,
+	"userScope" | "projectScope" | "localScope"
+>;
+
 /**
- * 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.
+ * THE test for "installed at this scope": the scope's settings file turns the
+ * plugin on. See {@link ScopeStatus}.
  *
- * 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.
+ * Every consumer asks this and nothing else — the list row's squares and name
+ * colour, the detail pane's dots, the header count, the classifier, the scope
+ * keys, the mate slots — so no two of them can show a different state.
  *
- * `isOrphaned` is a different failure — installed, but no longer offered by any
- * marketplace — and is rendered as "deprecated" already.
+ * A version is not part of the test. Installed with no version is still
+ * installed, in the broken sub-state {@link scopeFilesMissing} names.
+ */
+export function isInstalledInScope(scope: ScopeStatus | undefined): boolean {
+	return scope?.installed === true;
+}
+
+/** Installed at user, project or local scope. */
+export function isInstalledAnywhere(plugin: PluginScopes | undefined): boolean {
+	return (
+		isInstalledInScope(plugin?.userScope) ||
+		isInstalledInScope(plugin?.projectScope) ||
+		isInstalledInScope(plugin?.localScope)
+	);
+}
+
+/**
+ * The version at this scope, or undefined where the plugin is not installed.
  *
- * "0.0.0" means installed-with-unknown-version (Anthropic's official plugins
- * record exactly that), so it must NOT count as missing.
+ * A scope that is not installed can still carry a registry version, inherited
+ * from another checkout of the repository. Shown, it claims an install Claude
+ * Code does not load in this directory.
  */
-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;
+export function versionInScope(
+	scope: ScopeStatus | undefined,
+): string | undefined {
+	return isInstalledInScope(scope) ? scope?.version : undefined;
 }
 
 /**
- * True when a scope genuinely has the plugin installed.
+ * Installed at this scope with no version: Claude Code wants to load the plugin
+ * and has nothing to load. The repair is `install`.
  *
- * `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".
+ * "0.0.0" is a version — Anthropic's official plugins record exactly that — so
+ * it is not missing, which is why this tests presence, not `isKnownVersion`.
+ */
+export function scopeFilesMissing(scope: ScopeStatus | undefined): boolean {
+	return isInstalledInScope(scope) && !scope?.version;
+}
+
+/** The three scopes, in the one order every per-scope list uses: user, project, local. */
+function scopeStatuses(
+	plugin: PluginScopes | undefined,
+): Array<[PluginScope, ScopeStatus | undefined]> {
+	return [
+		["user", plugin?.userScope],
+		["project", plugin?.projectScope],
+		["local", plugin?.localScope],
+	];
+}
+
+/**
+ * Scope → version, for the scopes where the plugin is installed and a version
+ * resolves.
  *
- * 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".
+ * Only installed scopes. A scope that is not can still carry a registry version
+ * inherited from another checkout, and counting it planned an update — and
+ * printed a version — for a plugin Claude Code does not load here.
+ */
+export function installedScopeVersions(
+	plugin: PluginScopes | undefined,
+): Array<[PluginScope, string]> {
+	const out: Array<[PluginScope, string]> = [];
+	for (const [scope, status] of scopeStatuses(plugin)) {
+		const version = versionInScope(status);
+		if (version) out.push([scope, version]);
+	}
+	return out;
+}
+
+/** The scopes where the plugin is installed with its files missing. */
+export function filesMissingScopes(
+	plugin: PluginScopes | undefined,
+): PluginScope[] {
+	return scopeStatuses(plugin)
+		.filter(([, status]) => scopeFilesMissing(status))
+		.map(([scope]) => scope);
+}
+
+/**
+ * The highest version installed across scopes, or null.
  *
- * 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`.
+ * THE installed version: the classifier's `installed` and
+ * `PluginInfo.installedVersion` are both this, so the Plugins header, the row
+ * and the status line cannot name different versions for one plugin.
+ *
+ * `compareVersions` answers null for an unorderable pair, and null is not
+ * `>= 0`, so the reduce keeps the right-hand side when two versions cannot be
+ * ranked. "Highest" is not meaningful across commit ids; picking one
+ * deterministically is, and every caller only needs *an* installed version.
  */
-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;
+export function highestInstalledVersion(
+	plugin: PluginScopes | undefined,
+): string | null {
+	const versions = installedScopeVersions(plugin).map(([, v]) => v);
+	if (versions.length === 0) return null;
+	return versions.reduce((a, b) =>
+		(compareVersions(a, b) ?? -1) >= 0 ? a : b,
+	);
 }
 
 /**
- * One scope's status, from the two facts that define it.
+ * Files missing, at plugin level: installed somewhere, and no installed scope
+ * has a version — the classifier's own test for reason `files-missing`.
+ *
+ * Broken, not healthy: Claude Code will not load the plugin, and because the
+ * update check is `installedVersion && compare(...)`, it is also invisible to
+ * every update path.
  *
- * 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:
+ * Read from the scopes, never from `installedVersion`: a version that field
+ * once took from a scope NOT installed here made the header say "● Installed"
+ * beside a status line saying files missing.
  *
- *   enabledPlugins[id] !== undefined ? {...} : undefined
+ * `isOrphaned` is a different failure — no longer offered by any marketplace —
+ * and has its own rendering 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 hasMissingFiles(plugin: PluginInfo): boolean {
+	if (plugin.isOrphaned) return false;
+	return (
+		isInstalledAnywhere(plugin) && highestInstalledVersion(plugin) === null
+	);
+}
+
+/**
+ * One scope's status, from the scope's `enabledPlugins` map and the registry
+ * versions resolved for it.
  *
- * 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.
+ * Exported and taken as arguments so all three scopes share one implementation
+ * and it is unit-tested. `installed` is the settings flag and nothing else. The
+ * version is carried whenever the registry resolves one; {@link versionInScope}
+ * is what keeps it off screen for a scope where the plugin is not installed.
+ * Neither fact present means no scope at all.
  */
 export function buildScopeStatus(
 	enabledPlugins: Record<string, boolean>,
 	installedVersions: Record<string, string>,
 	pluginId: string,
 ): ScopeStatus | undefined {
-	const enabled = enabledPlugins[pluginId];
+	const flag = enabledPlugins[pluginId];
 	const version = installedVersions[pluginId];
-	if (enabled === undefined && version === undefined) return undefined;
-	return { enabled: enabled === true, version };
+	if (flag === undefined && version === undefined) return undefined;
+	return { installed: flag === 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).
+ * `install` for a scope that is not installed, and for one whose files are
+ * missing — there it is the repair. Measured against Claude Code 2.1.223 in
+ * exactly that state — `dev@magus` 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).
+ *
+ * Files missing must never resolve to `uninstall`. The scope key runs
+ * `cliUninstallPlugin` with no confirmation, and that answer removed a plugin
+ * the row beside it was reporting as broken — the user asked for the repair.
  *
  * `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
@@ -269,18 +385,7 @@ 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";
+	if (!isInstalledInScope(scope) || scopeFilesMissing(scope)) return "install";
 	return behind ? "update" : "uninstall";
 }
 
@@ -288,6 +393,7 @@ export async function getAvailablePlugins(
 	projectPath?: string,
 ): Promise<PluginInfo[]> {
 	const configuredMarketplaces = await getConfiguredMarketplaces(projectPath);
+	// The project scope's two facts. They also seed the orphan list below.
 	const enabledPlugins = await getEnabledPlugins(projectPath);
 	const installedVersions = await getInstalledPluginVersions(projectPath);
 
@@ -303,12 +409,9 @@ export async function getAvailablePlugins(
 	const loadedVersionOf = (pluginId: string): string | null =>
 		loadedVersions[pluginId] ?? null;
 
-	// Fetch all scopes for per-scope status
+	// The other two scopes.
 	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);
@@ -316,21 +419,13 @@ export async function getAvailablePlugins(
 	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) => ({
+	const scopeStatusFor = (pluginId: string): PluginScopes => ({
 		userScope: buildScopeStatus(
 			userEnabledPlugins,
 			userInstalledVersions,
 			pluginId,
 		),
-		projectScope: buildScopeStatus(
-			projectEnabledPlugins,
-			projectInstalledVersions,
-			pluginId,
-		),
+		projectScope: buildScopeStatus(enabledPlugins, installedVersions, pluginId),
 		localScope: buildScopeStatus(
 			localEnabledPlugins,
 			localInstalledVersions,
@@ -338,6 +433,17 @@ export async function getAvailablePlugins(
 		),
 	});
 
+	// A version is an install only at a scope where Claude Code loads the plugin.
+	// The registry resolves a row here for plugins no settings file in this
+	// directory turns on — inherited from another checkout of the repository.
+	// This used to take the PROJECT lookup whenever the plugin was installed at
+	// any scope, so a plugin installed at user scope at 0.9.0 read "(v0.8.1
+	// installed)" off an inherited project row beside a status saying current at
+	// 0.9.0 — and with its user files missing, the header said "● Installed".
+	// The classifier's rule, from the same per-scope versions, is the only rule.
+	const installedVersionFor = (scopes: PluginScopes): string | undefined =>
+		highestInstalledVersion(scopes) ?? undefined;
+
 	// Get all marketplace names (configured + official/featured defaults)
 	// Always include official and featured marketplaces so users can browse them
 	const marketplaceNames = new Set<string>();
@@ -396,9 +502,8 @@ export async function getAvailablePlugins(
 
 		for (const plugin of marketplacePlugins) {
 			const pluginId = `${plugin.name}@${mpName}`;
-			const installedVersion = installedVersions[pluginId];
-			const isEnabled = enabledPlugins[pluginId] === true;
 			const scopeStatus = scopeStatusFor(pluginId);
+			const installedVersion = installedVersionFor(scopeStatus);
 
 			seenPluginIds.add(pluginId);
 			plugins.push({
@@ -408,7 +513,6 @@ export async function getAvailablePlugins(
 				description: plugin.description,
 				marketplace: mpName,
 				marketplaceDisplay: marketplace.displayName,
-				enabled: isEnabled,
 				installedVersion: installedVersion,
 				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(plugin.version, installedVersion) === true,
@@ -436,9 +540,8 @@ export async function getAvailablePlugins(
 			const pluginId = `${localPlugin.name}@${mpName}`;
 			if (seenPluginIds.has(pluginId)) continue;
 
-			const installedVersion = installedVersions[pluginId];
-			const isEnabled = enabledPlugins[pluginId] === true;
 			const scopeStatus = scopeStatusFor(pluginId);
+			const installedVersion = installedVersionFor(scopeStatus);
 
 			seenPluginIds.add(pluginId);
 			plugins.push({
@@ -448,7 +551,6 @@ export async function getAvailablePlugins(
 				description: localPlugin.description || "",
 				marketplace: mpName,
 				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
-				enabled: isEnabled,
 				installedVersion: installedVersion,
 				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(localPlugin.version, installedVersion) === true,
@@ -466,7 +568,7 @@ export async function getAvailablePlugins(
 		}
 	}
 
-	// Add orphaned plugins (enabled/installed but not in any cache)
+	// Add orphaned plugins (in this project's settings or registry, but not in any cache)
 	const allPluginIds = new Set([
 		...Object.keys(enabledPlugins),
 		...Object.keys(installedVersions),
@@ -479,9 +581,8 @@ export async function getAvailablePlugins(
 		if (!parsed) continue;
 
 		const { pluginName, marketplace: mpName } = parsed;
-		const installedVersion = installedVersions[pluginId];
-		const isEnabled = enabledPlugins[pluginId] === true;
 		const scopeStatus = scopeStatusFor(pluginId);
+		const installedVersion = installedVersionFor(scopeStatus);
 
 		// Try to get plugin info from local marketplace cache (fallback)
 		const localMp = localMarketplaces.get(mpName);
@@ -498,7 +599,6 @@ export async function getAvailablePlugins(
 			description,
 			marketplace: mpName,
 			marketplaceDisplay: localMp?.name || formatMarketplaceName(mpName),
-			enabled: isEnabled,
 			installedVersion: installedVersion,
 			loadedVersion: loadedVersionOf(pluginId),
 			hasUpdate,
@@ -507,7 +607,7 @@ export async function getAvailablePlugins(
 		});
 	}
 
-	await annotateContentDrift(plugins, "project", projectPath);
+	await annotateContentDrift(plugins, projectPath);
 	return plugins;
 }
 
@@ -538,19 +638,58 @@ export function contentDriftCandidate(plugin: PluginInfo): boolean {
 	return compareVersions(plugin.version, plugin.installedVersion) === 0;
 }
 
+/**
+ * The registry row whose commit a drift check compares: the row behind an
+ * INSTALLED scope at `installedVersion`, picked the way that scope's version
+ * was resolved — so a worktree that inherits a version inherits its
+ * `gitCommitSha` with it, and drift detection does not switch off for exactly
+ * the plugins that just started reporting as installed.
+ *
+ * It used to be the project lookup for every plugin. For one installed only at
+ * user scope, beside a project row inherited from another checkout, that
+ * compared the inherited row's commit — another version's files — against the
+ * user install's version.
+ *
+ * Project, then local, then user: this directory's rows before the user row,
+ * the precedence the project lookup always had.
+ *
+ * Exported to be tested directly; `annotateContentDrift` needs the registry.
+ */
+export function contentDriftEntry(
+	plugin: PluginInfo,
+	entries: InstalledPluginEntry[] | undefined,
+	projectPath: string,
+	fallbackPaths: string[],
+): InstalledPluginEntry | undefined {
+	const atShown = new Set(
+		installedScopeVersions(plugin)
+			.filter(([, version]) => version === plugin.installedVersion)
+			.map(([scope]) => scope),
+	);
+	for (const scope of ["project", "local", "user"] as const) {
+		if (!atShown.has(scope)) continue;
+		const entry =
+			scope === "user"
+				? pickRegistryEntry(entries, "user")
+				: pickRegistryEntry(entries, scope, projectPath, fallbackPaths);
+		if (entry) return entry;
+	}
+	return undefined;
+}
+
 /**
  * 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}.
+ * {@link contentDriftCandidate}, and which row to ask about is
+ * {@link contentDriftEntry}.
  *
  * 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;
@@ -560,20 +699,16 @@ async function annotateContentDrift(
 		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) : [];
+	const target = projectPath ?? process.cwd();
+	const fallbackPaths = await inheritablePaths(target);
 
 	await Promise.all(
 		plugins.map(async (plugin) => {
 			if (!contentDriftCandidate(plugin)) return;
 
-			const entry = pickRegistryEntry(
+			const entry = contentDriftEntry(
+				plugin,
 				registry.plugins[plugin.id],
-				scope,
 				target,
 				fallbackPaths,
 			);
@@ -762,6 +897,13 @@ export async function saveInstalledPluginVersion(
  * 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.
+ *
+ * Only THIS project's own row at `scope` ({@link ownRegistryEntry}) — no
+ * inherited row and no user-row fallback. A fallback answered for a row the
+ * command never wrote: the apply engine took it as "this project holds a row"
+ * and ran `update` where only `install` is safe, and a read-back after a
+ * project install that wrote nothing returned the user row's version, to be
+ * recorded as the project's.
  */
 export async function readInstalledVersionForScope(
 	pluginId: string,
@@ -769,7 +911,7 @@ export async function readInstalledVersionForScope(
 	projectPath: string = process.cwd(),
 ): Promise<string | null> {
 	const registry = await readInstalledPluginsRegistry();
-	const entry = pickRegistryEntry(
+	const entry = ownRegistryEntry(
 		registry.plugins?.[pluginId],
 		scope,
 		projectPath,