magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/claude-settings.ts

@@ -0,0 +1,1564 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import semver from "semver";
+import type {
+	ClaudeLocalSettings,
+	ClaudeSettings,
+	DiscoveredMarketplace,
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+	MarketplaceSource,
+	McpServerConfig,
+} from "../types/index.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import { repoHeadSha } from "./content-drift.js";
+import { inheritablePaths } from "./git-worktree.js";
+
+const CLAUDE_DIR = ".claude";
+const SETTINGS_FILE = "settings.json";
+const LOCAL_SETTINGS_FILE = "settings.local.json";
+const MCP_CONFIG_FILE = ".mcp.json";
+
+// MCP config file types
+interface McpConfigFile {
+	mcpServers?: Record<string, McpServerConfig>;
+}
+
+export function getClaudeDir(projectPath?: string): string {
+	const base = projectPath || process.cwd();
+	return path.join(base, CLAUDE_DIR);
+}
+
+export function getGlobalClaudeDir(): string {
+	return path.join(os.homedir(), CLAUDE_DIR);
+}
+
+export async function ensureClaudeDir(projectPath?: string): Promise<string> {
+	const claudeDir = getClaudeDir(projectPath);
+	await fs.ensureDir(claudeDir);
+	return claudeDir;
+}
+
+export async function readSettings(
+	projectPath?: string,
+): Promise<ClaudeSettings> {
+	const settingsPath = path.join(getClaudeDir(projectPath), SETTINGS_FILE);
+	try {
+		if (await fs.pathExists(settingsPath)) {
+			return await fs.readJson(settingsPath);
+		}
+	} catch {
+		// Return empty settings on error
+	}
+	return {};
+}
+
+export async function writeSettings(
+	settings: ClaudeSettings,
+	projectPath?: string,
+): Promise<void> {
+	const claudeDir = await ensureClaudeDir(projectPath);
+	const settingsPath = path.join(claudeDir, SETTINGS_FILE);
+	await fs.writeJson(settingsPath, settings, { spaces: 2 });
+}
+
+export async function readLocalSettings(
+	projectPath?: string,
+): Promise<ClaudeLocalSettings> {
+	const localPath = path.join(getClaudeDir(projectPath), LOCAL_SETTINGS_FILE);
+	try {
+		if (await fs.pathExists(localPath)) {
+			return await fs.readJson(localPath);
+		}
+	} catch {
+		// Return empty settings on error
+	}
+	return {};
+}
+
+export async function writeLocalSettings(
+	settings: ClaudeLocalSettings,
+	projectPath?: string,
+): Promise<void> {
+	const claudeDir = await ensureClaudeDir(projectPath);
+	const localPath = path.join(claudeDir, LOCAL_SETTINGS_FILE);
+	await fs.writeJson(localPath, settings, { spaces: 2 });
+}
+
+// MCP config file management (.mcp.json at project root)
+export function getMcpConfigPath(projectPath?: string): string {
+	const base = projectPath || process.cwd();
+	return path.join(base, MCP_CONFIG_FILE);
+}
+
+export async function readMcpConfig(
+	projectPath?: string,
+): Promise<McpConfigFile> {
+	const mcpPath = getMcpConfigPath(projectPath);
+	try {
+		if (await fs.pathExists(mcpPath)) {
+			return await fs.readJson(mcpPath);
+		}
+	} catch {
+		// Return empty config on error
+	}
+	return {};
+}
+
+export async function writeMcpConfig(
+	config: McpConfigFile,
+	projectPath?: string,
+): Promise<void> {
+	const mcpPath = getMcpConfigPath(projectPath);
+	await fs.writeJson(mcpPath, config, { spaces: 2 });
+}
+
+export async function readGlobalSettings(): Promise<ClaudeSettings> {
+	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
+	try {
+		if (await fs.pathExists(settingsPath)) {
+			return await fs.readJson(settingsPath);
+		}
+	} catch {
+		// Return empty settings on error
+	}
+	return {};
+}
+
+export async function writeGlobalSettings(
+	settings: ClaudeSettings,
+): Promise<void> {
+	await fs.ensureDir(getGlobalClaudeDir());
+	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
+	await fs.writeJson(settingsPath, settings, { spaces: 2 });
+}
+
+// MCP Server management (writes to .mcp.json at project root)
+export async function addMcpServer(
+	name: string,
+	config: McpServerConfig,
+	projectPath?: string,
+): Promise<void> {
+	// Extract env vars from config - they go to settings.local.json, not .mcp.json
+	const envVars = config.env || {};
+	const configWithoutEnv: McpServerConfig = { ...config };
+	// biome-ignore lint/performance/noDelete: this object is serialised into .mcp.json; the env key must be absent, not present as undefined
+	delete configWithoutEnv.env;
+
+	// Add to .mcp.json (without env vars)
+	const mcpConfig = await readMcpConfig(projectPath);
+	mcpConfig.mcpServers = mcpConfig.mcpServers || {};
+	mcpConfig.mcpServers[name] = configWithoutEnv;
+	await writeMcpConfig(mcpConfig, projectPath);
+
+	// Enable in settings.local.json and add env vars
+	const localSettings = await readLocalSettings(projectPath);
+	const enabledServers = localSettings.enabledMcpjsonServers || [];
+	if (!enabledServers.includes(name)) {
+		enabledServers.push(name);
+	}
+	localSettings.enabledMcpjsonServers = enabledServers;
+	localSettings.enableAllProjectMcpServers = true;
+
+	// Add env vars to settings.local.json
+	if (Object.keys(envVars).length > 0) {
+		localSettings.env = localSettings.env || {};
+		for (const [key, value] of Object.entries(envVars)) {
+			// Only add non-reference values (references like ${VAR} don't need to be stored)
+			if (!value.startsWith("${") || !value.endsWith("}")) {
+				localSettings.env[key] = value;
+			}
+		}
+	}
+
+	await writeLocalSettings(localSettings, projectPath);
+}
+
+export async function removeMcpServer(
+	name: string,
+	projectPath?: string,
+): Promise<void> {
+	// Remove from .mcp.json
+	const mcpConfig = await readMcpConfig(projectPath);
+	if (mcpConfig.mcpServers) {
+		delete mcpConfig.mcpServers[name];
+	}
+	await writeMcpConfig(mcpConfig, projectPath);
+
+	// Remove from settings.local.json
+	const localSettings = await readLocalSettings(projectPath);
+	if (localSettings.enabledMcpjsonServers) {
+		localSettings.enabledMcpjsonServers =
+			localSettings.enabledMcpjsonServers.filter((s) => s !== name);
+		await writeLocalSettings(localSettings, projectPath);
+	}
+}
+
+export async function toggleMcpServer(
+	name: string,
+	enabled: boolean,
+	projectPath?: string,
+): Promise<void> {
+	// Toggle is now a remove operation since .mcp.json doesn't have enabled/disabled state
+	// If disabled, remove from config; if enabled, the server should already be in config
+	if (!enabled) {
+		await removeMcpServer(name, projectPath);
+	}
+	// If enabling, the server should already exist in the config
+}
+
+export async function setAllowMcp(
+	_allow: boolean,
+	_projectPath?: string,
+): Promise<void> {
+	// .mcp.json doesn't have an allowMcp setting - servers are either in the file or not
+	// This function is kept for API compatibility but is now a no-op
+}
+
+// Marketplace management - READ ONLY
+// Use Claude Code CLI commands to add/remove marketplaces:
+// claude marketplace add owner/repo
+// claude marketplace remove name
+
+// Plugin management
+export async function enablePlugin(
+	pluginId: string,
+	enabled: boolean,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readSettings(projectPath);
+	settings.enabledPlugins = settings.enabledPlugins || {};
+	if (enabled) {
+		settings.enabledPlugins[pluginId] = true;
+	} else {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeSettings(settings, projectPath);
+}
+
+export async function getEnabledPlugins(
+	projectPath?: string,
+): Promise<Record<string, boolean>> {
+	const settings = await readSettings(projectPath);
+	return settings.enabledPlugins || {};
+}
+
+export async function getLocalEnabledPlugins(
+	projectPath?: string,
+): Promise<Record<string, boolean>> {
+	const settings = await readLocalSettings(projectPath);
+	return settings.enabledPlugins || {};
+}
+
+/**
+ * Overlay the installed_plugins.json registry onto a settings-derived version map.
+ *
+ * `settings.installedPluginVersions` is magus's own bookkeeping and is routinely
+ * incomplete: Claude Code's own `plugin install` writes the registry but not our
+ * settings key, so a plugin can be genuinely installed and still be absent here.
+ * Callers that only read settings then see `undefined` and — because the update
+ * check is `installedVersion && compare(...)` — silently treat the plugin as
+ * up to date instead of unknown. That hides real updates.
+ *
+ * The registry is what Claude Code actually loaded, so it wins on conflict.
+ *
+ * Scope resolution mirrors Claude Code: for a project scope, prefer an entry
+ * pinned to that exact projectPath (project or local), then any `fallbackPaths`
+ * that are the same repository (see git-worktree.ts), then the user-scope entry,
+ * which is what a project without its own install resolves to.
+ */
+export function pickRegistryEntry(
+	entries: InstalledPluginEntry[] | undefined,
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+	/**
+	 * Same-repository directories whose rows may be inherited, nearest first —
+	 * a linked worktree's main working tree, or the root of this checkout.
+	 *
+	 * A fresh worktree has no rows of its own, so without this every plugin read
+	 * as not installed while Claude Code was loading all of them quite happily.
+	 * These rank above the user-scope entry: "installed in this repository" is a
+	 * closer answer than "installed globally somewhere".
+	 */
+	fallbackPaths: string[] = [],
+): InstalledPluginEntry | undefined {
+	if (!Array.isArray(entries) || entries.length === 0) return undefined;
+
+	if (scope === "user") return entries.find((e) => e.scope === "user");
+
+	const pinnedTo = (target: string) =>
+		entries.find(
+			(e) =>
+				(e.scope === scope || e.scope === "local") &&
+				e.projectPath !== undefined &&
+				path.resolve(e.projectPath) === target,
+		);
+
+	if (projectPath) {
+		const own = pinnedTo(path.resolve(projectPath));
+		if (own) return own;
+	}
+	for (const fallback of fallbackPaths) {
+		const inherited = pinnedTo(path.resolve(fallback));
+		if (inherited) return inherited;
+	}
+	// A project with no install of its own resolves to the user-scope entry.
+	return entries.find((e) => e.scope === "user");
+}
+
+async function overlayRegistryVersions(
+	base: Record<string, string>,
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<Record<string, string>> {
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = await readInstalledPluginsRegistry();
+	} catch {
+		return base; // registry unreadable — settings-only is still better than nothing
+	}
+
+	// `readSettings(undefined)` already resolves to the current directory, so the
+	// registry lookup has to as well. While it did not, the base map described one
+	// project while the overlay refused to match any project's rows at all, and every
+	// version was deleted as unbacked — which is why the global
+	// plugin view, both of which pass no path, saw project-scope plugins as
+	// uninstalled everywhere, not only in a worktree.
+	const target = scope === "user" ? undefined : (projectPath ?? process.cwd());
+
+	// Resolved once, not per plugin: this shells out to git, and the loop runs
+	// across every key in the registry (76 on a well-used machine) for each scope.
+	const fallbackPaths = target ? await inheritablePaths(target) : [];
+
+	const merged = { ...base };
+	for (const [pluginId, entries] of Object.entries(registry.plugins ?? {})) {
+		const pick = pickRegistryEntry(entries, scope, target, fallbackPaths);
+		if (pick?.version) {
+			merged[pluginId] = pick.version;
+			continue;
+		}
+
+		// The registry knows this plugin but has no entry for this scope, so it
+		// is NOT installed here. Any leftover `installedPluginVersions` value is
+		// a claim about an install that does not exist.
+		//
+		// Claude Code never writes that field — it appears 0 times in the 2.1.223
+		// binary, and `claude plugin install` writes it at no scope — so only
+		// magus's own past writes can be in there, and they go stale silently.
+		// Measured: user settings claimed browser-use 1.1.2 / terminal 4.0.2 /
+		// code-search 5.1.0 while the registry said 1.4.0 / 4.1.4 / 5.3.1, and
+		// none of the claimed versions had a cache directory. Keeping the stale
+		// value made every one of them read as a permanent pending update.
+		if (entries && entries.length > 0) delete merged[pluginId];
+	}
+	return merged;
+}
+
+export async function getLocalInstalledPluginVersions(
+	projectPath?: string,
+): Promise<Record<string, string>> {
+	const settings = await readLocalSettings(projectPath);
+	return overlayRegistryVersions(
+		settings.installedPluginVersions || {},
+		"local",
+		projectPath,
+	);
+}
+
+/**
+ * Overlay the registry onto a project-scope settings map.
+ * Exported for plugin-manager, which reads project settings itself.
+ */
+export async function getProjectInstalledPluginVersions(
+	base: Record<string, string>,
+	projectPath?: string,
+): Promise<Record<string, string>> {
+	return overlayRegistryVersions(base, "project", projectPath);
+}
+
+// Local plugin management (writes to settings.local.json)
+export async function enableLocalPlugin(
+	pluginId: string,
+	enabled: boolean,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readLocalSettings(projectPath);
+	settings.enabledPlugins = settings.enabledPlugins || {};
+	if (enabled) {
+		settings.enabledPlugins[pluginId] = true;
+	} else {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeLocalSettings(settings, projectPath);
+}
+
+export async function saveLocalInstalledPluginVersion(
+	pluginId: string,
+	version: string,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readLocalSettings(projectPath);
+	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions[pluginId] = version;
+	await writeLocalSettings(settings, projectPath);
+
+	// Update registry for local scope
+	await updateInstalledPluginsRegistry(
+		pluginId,
+		version,
+		"local",
+		projectPath ? path.resolve(projectPath) : undefined,
+	);
+}
+
+export async function removeLocalInstalledPluginVersion(
+	pluginId: string,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readLocalSettings(projectPath);
+	if (settings.installedPluginVersions) {
+		delete settings.installedPluginVersions[pluginId];
+	}
+	if (settings.enabledPlugins) {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeLocalSettings(settings, projectPath);
+
+	// Remove from registry for local scope
+	await removeFromInstalledPluginsRegistry(
+		pluginId,
+		"local",
+		projectPath ? path.resolve(projectPath) : undefined,
+	);
+}
+
+// Status line management
+// Claude Code expects statusLine as an object: { type: "template", template: "..." }
+// or { type: "command", command: "..." }. Writing a bare string causes a validation error
+// that skips the entire settings file.
+
+function wrapStatusLine(
+	template: string,
+): { type: string; template: string } | undefined {
+	if (!template) return undefined;
+	return { type: "template", template };
+}
+
+function unwrapStatusLine(
+	value:
+		| string
+		| { type: string; template?: string; command?: string }
+		| undefined,
+): string | undefined {
+	if (!value) return undefined;
+	if (typeof value === "string") return value; // legacy format
+	return value.template ?? value.command;
+}
+
+export async function setStatusLine(
+	template: string,
+	projectPath?: string,
+): Promise<void> {
+	const settings = await readSettings(projectPath);
+	const wrapped = wrapStatusLine(template);
+	if (wrapped) {
+		settings.statusLine = wrapped;
+	} else {
+		// biome-ignore lint/performance/noDelete: settings is written back to settings.json; the key must be removed from the file, and readers check `Object.keys`/`in`
+		delete settings.statusLine;
+	}
+	await writeSettings(settings, projectPath);
+}
+
+export async function getStatusLine(
+	projectPath?: string,
+): Promise<string | undefined> {
+	const settings = await readSettings(projectPath);
+	return unwrapStatusLine(settings.statusLine);
+}
+
+// Global status line management
+export async function setGlobalStatusLine(template: string): Promise<void> {
+	const settings = await readGlobalSettings();
+	const wrapped = wrapStatusLine(template);
+	if (wrapped) {
+		settings.statusLine = wrapped;
+	} else {
+		// biome-ignore lint/performance/noDelete: settings is written back to settings.json; the key must be removed from the file, and readers check `Object.keys`/`in`
+		delete settings.statusLine;
+	}
+	await writeGlobalSettings(settings);
+}
+
+export async function getGlobalStatusLine(): Promise<string | undefined> {
+	const settings = await readGlobalSettings();
+	return unwrapStatusLine(settings.statusLine);
+}
+
+// Get effective status line (project overrides global)
+export async function getEffectiveStatusLine(projectPath?: string): Promise<{
+	template: string | undefined;
+	source: "project" | "global" | "default";
+}> {
+	const projectStatusLine = await getStatusLine(projectPath);
+	if (projectStatusLine) {
+		return { template: projectStatusLine, source: "project" };
+	}
+
+	const globalStatusLine = await getGlobalStatusLine();
+	if (globalStatusLine) {
+		return { template: globalStatusLine, source: "global" };
+	}
+
+	return { template: undefined, source: "default" };
+}
+
+// Check if .claude directory exists
+export async function hasClaudeDir(projectPath?: string): Promise<boolean> {
+	return fs.pathExists(getClaudeDir(projectPath));
+}
+
+// Get installed MCP servers (from .mcp.json)
+export async function getInstalledMcpServers(
+	projectPath?: string,
+): Promise<Record<string, McpServerConfig>> {
+	const mcpConfig = await readMcpConfig(projectPath);
+	return mcpConfig.mcpServers || {};
+}
+
+// Get env vars for MCP servers (from settings.local.json)
+export async function getMcpEnvVars(
+	projectPath?: string,
+): Promise<Record<string, string>> {
+	const localSettings = await readLocalSettings(projectPath);
+	return localSettings.env || {};
+}
+
+// Set an env var for MCP servers (in settings.local.json)
+export async function setMcpEnvVar(
+	name: string,
+	value: string,
+	projectPath?: string,
+): Promise<void> {
+	const localSettings = await readLocalSettings(projectPath);
+	localSettings.env = localSettings.env || {};
+	localSettings.env[name] = value;
+	await writeLocalSettings(localSettings, projectPath);
+}
+
+// Remove an env var (from settings.local.json)
+export async function removeMcpEnvVar(
+	name: string,
+	projectPath?: string,
+): Promise<void> {
+	const localSettings = await readLocalSettings(projectPath);
+	if (localSettings.env) {
+		delete localSettings.env[name];
+		await writeLocalSettings(localSettings, projectPath);
+	}
+}
+
+// Get enabled MCP servers (all servers in .mcp.json are considered enabled)
+export async function getEnabledMcpServers(
+	projectPath?: string,
+): Promise<Record<string, boolean>> {
+	const mcpConfig = await readMcpConfig(projectPath);
+	const servers = mcpConfig.mcpServers || {};
+	const enabled: Record<string, boolean> = {};
+	for (const name of Object.keys(servers)) {
+		enabled[name] = true;
+	}
+	return enabled;
+}
+
+// Get all configured marketplaces — merges known_marketplaces.json (primary) with extraKnownMarketplaces (legacy fallback)
+export async function getConfiguredMarketplaces(
+	projectPath?: string,
+): Promise<Record<string, MarketplaceSource>> {
+	const result: Record<string, MarketplaceSource> = {};
+
+	// Primary: known_marketplaces.json (official Claude Code registry)
+	const known = await readKnownMarketplaces();
+	for (const [name, entry] of Object.entries(known)) {
+		if (entry.source?.repo) {
+			result[name] = {
+				source: { source: "github" as const, repo: entry.source.repo },
+			};
+		}
+	}
+
+	// Fallback: extraKnownMarketplaces (legacy — only adds entries not already in known)
+	const settings = await readSettings(projectPath);
+	for (const [name, config] of Object.entries(
+		settings.extraKnownMarketplaces || {},
+	)) {
+		if (!result[name]) {
+			result[name] = config;
+		}
+	}
+
+	return result;
+}
+
+// Global marketplace management - READ ONLY
+// Marketplaces are managed via Claude Code's native system
+
+export async function getGlobalConfiguredMarketplaces(): Promise<
+	Record<string, MarketplaceSource>
+> {
+	const result: Record<string, MarketplaceSource> = {};
+
+	// Primary: known_marketplaces.json
+	const known = await readKnownMarketplaces();
+	for (const [name, entry] of Object.entries(known)) {
+		if (entry.source?.repo) {
+			result[name] = {
+				source: { source: "github" as const, repo: entry.source.repo },
+			};
+		}
+	}
+
+	// Fallback: extraKnownMarketplaces
+	const settings = await readGlobalSettings();
+	for (const [name, config] of Object.entries(
+		settings.extraKnownMarketplaces || {},
+	)) {
+		if (!result[name]) {
+			result[name] = config;
+		}
+	}
+
+	return result;
+}
+
+// Global plugin management
+export async function enableGlobalPlugin(
+	pluginId: string,
+	enabled: boolean,
+): Promise<void> {
+	const settings = await readGlobalSettings();
+	settings.enabledPlugins = settings.enabledPlugins || {};
+	if (enabled) {
+		settings.enabledPlugins[pluginId] = true;
+	} else {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeGlobalSettings(settings);
+}
+
+export async function getGlobalEnabledPlugins(): Promise<
+	Record<string, boolean>
+> {
+	const settings = await readGlobalSettings();
+	return settings.enabledPlugins || {};
+}
+
+export async function getGlobalInstalledPluginVersions(): Promise<
+	Record<string, string>
+> {
+	const settings = await readGlobalSettings();
+	return overlayRegistryVersions(
+		settings.installedPluginVersions || {},
+		"user",
+	);
+}
+
+export async function saveGlobalInstalledPluginVersion(
+	pluginId: string,
+	version: string,
+): Promise<void> {
+	const settings = await readGlobalSettings();
+	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions[pluginId] = version;
+	await writeGlobalSettings(settings);
+
+	// Update registry for user scope
+	await updateInstalledPluginsRegistry(pluginId, version, "user");
+}
+
+export async function removeGlobalInstalledPluginVersion(
+	pluginId: string,
+): Promise<void> {
+	const settings = await readGlobalSettings();
+	if (settings.installedPluginVersions) {
+		delete settings.installedPluginVersions[pluginId];
+	}
+	if (settings.enabledPlugins) {
+		delete settings.enabledPlugins[pluginId];
+	}
+	await writeGlobalSettings(settings);
+
+	// Remove from registry for user scope
+	await removeFromInstalledPluginsRegistry(pluginId, "user");
+}
+
+// Shared logic for discovering marketplaces from settings
+function discoverMarketplacesFromSettings(
+	settings: ClaudeSettings,
+	knownMarketplaces?: KnownMarketplaces,
+): DiscoveredMarketplace[] {
+	const discovered = new Map<string, DiscoveredMarketplace>();
+
+	// 1. From known_marketplaces.json (official Claude Code registry — primary source)
+	if (knownMarketplaces) {
+		for (const [name, entry] of Object.entries(knownMarketplaces)) {
+			if (entry.source?.repo) {
+				discovered.set(name, {
+					name,
+					source: "configured",
+					config: {
+						source: { source: "github" as const, repo: entry.source.repo },
+					},
+				});
+			}
+		}
+	}
+
+	// 2. From extraKnownMarketplaces (legacy/team fallback — only adds entries not already in known_marketplaces.json)
+	for (const [name, config] of Object.entries(
+		settings.extraKnownMarketplaces || {},
+	)) {
+		if (!discovered.has(name)) {
+			discovered.set(name, { name, source: "configured", config });
+		}
+	}
+
+	// 3. From enabledPlugins (infer marketplace from plugin ID format: pluginName@marketplaceName)
+	for (const pluginId of Object.keys(settings.enabledPlugins || {})) {
+		const parsed = parsePluginId(pluginId);
+		if (parsed && !discovered.has(parsed.marketplace)) {
+			discovered.set(parsed.marketplace, {
+				name: parsed.marketplace,
+				source: "inferred",
+			});
+		}
+	}
+
+	// 4. From installedPluginVersions (same format)
+	for (const pluginId of Object.keys(settings.installedPluginVersions || {})) {
+		const parsed = parsePluginId(pluginId);
+		if (parsed && !discovered.has(parsed.marketplace)) {
+			discovered.set(parsed.marketplace, {
+				name: parsed.marketplace,
+				source: "inferred",
+			});
+		}
+	}
+
+	return Array.from(discovered.values());
+}
+
+// Discover all marketplaces from settings (configured + inferred from plugins)
+export async function discoverAllMarketplaces(
+	projectPath?: string,
+): Promise<DiscoveredMarketplace[]> {
+	try {
+		const settings = await readSettings(projectPath);
+		const known = await readKnownMarketplaces();
+		return discoverMarketplacesFromSettings(settings, known);
+	} catch (error) {
+		// Graceful degradation - return empty array instead of crashing
+		console.error(
+			"Failed to discover project marketplaces:",
+			error instanceof Error ? error.message : "Unknown error",
+		);
+		return [];
+	}
+}
+
+// Discover all marketplaces from global settings
+export async function discoverAllGlobalMarketplaces(): Promise<
+	DiscoveredMarketplace[]
+> {
+	try {
+		const settings = await readGlobalSettings();
+		const known = await readKnownMarketplaces();
+		return discoverMarketplacesFromSettings(settings, known);
+	} catch (error) {
+		// Graceful degradation - return empty array instead of crashing
+		console.error(
+			"Failed to discover global marketplaces:",
+			error instanceof Error ? error.message : "Unknown error",
+		);
+		return [];
+	}
+}
+
+// installed_plugins.json registry management.
+// Resolved lazily (per-call) rather than cached at module load: caching
+// os.homedir() in a module-level constant makes the path capture whatever
+// HOME was set to when this module was first imported, which is fragile
+// (import-order-dependent) and breaks any caller that changes HOME afterward.
+const installedPluginsFile = (): string =>
+	path.join(os.homedir(), ".claude", "plugins", "installed_plugins.json");
+
+const knownMarketplacesFile = (): string =>
+	path.join(os.homedir(), ".claude", "plugins", "known_marketplaces.json");
+
+interface KnownMarketplaceEntry {
+	source: { source: string; path?: string; repo?: string };
+	installLocation: string;
+	lastUpdated: string;
+	autoUpdate?: boolean;
+}
+
+type KnownMarketplaces = Record<string, KnownMarketplaceEntry>;
+
+/**
+ * Write known_marketplaces.json
+ */
+async function writeKnownMarketplaces(
+	marketplaces: KnownMarketplaces,
+): Promise<void> {
+	await fs.ensureDir(path.dirname(knownMarketplacesFile()));
+	await fs.writeJson(knownMarketplacesFile(), marketplaces, { spaces: 2 });
+}
+
+/**
+ * Read a marketplace's `autoUpdate` flag — Claude Code's refresh policy.
+ *
+ * READ ONLY, and there is deliberately no setter. `autoUpdate` is Claude Code's
+ * field (50 occurrences in the 2.1.269 binary, with its own manifest-schema
+ * entry and a "Synced autoUpdate= from settings" path), so Claude Code decides
+ * its value. magus used to write `true` into every MadAppGang entry on TUI
+ * startup, which is a direct write to `known_marketplaces.json` — the file at
+ * the top of CLAUDE.md's never-write-directly list — and it fought Claude Code's
+ * own sync for ownership of the same byte.
+ */
+export async function getMarketplaceAutoUpdate(
+	marketplaceName: string,
+): Promise<boolean | undefined> {
+	const known = await readKnownMarketplaces();
+	return known[marketplaceName]?.autoUpdate;
+}
+
+export interface MarketplaceRecoveryResult {
+	removed: string[];
+	reregistered: string[];
+}
+
+// =============================================================================
+// MARKETPLACE RENAME MIGRATION: mag-claude-plugins / MadAppGang-claude-code → magus
+// =============================================================================
+
+const OLD_MARKETPLACE_NAMES = ["mag-claude-plugins", "MadAppGang-claude-code"];
+const NEW_MARKETPLACE_NAME = "magus";
+const NEW_MARKETPLACE_REPO = "MadAppGang/magus";
+const OLD_MARKETPLACE_REPOS = ["MadAppGang/claude-code"];
+
+/**
+ * Rename plugin keys in a Record from any old marketplace name to new.
+ * e.g., "frontend@mag-claude-plugins" → "frontend@magus"
+ *        "dev@MadAppGang-claude-code" → "dev@magus"
+ * Returns [migratedRecord, count] — count=0 means no changes.
+ */
+function migratePluginKeys<T>(
+	record: Record<string, T> | undefined,
+): [Record<string, T>, number] {
+	if (!record) return [{}, 0];
+	const migrated: Record<string, T> = {};
+	let count = 0;
+	for (const [key, value] of Object.entries(record)) {
+		const oldName = OLD_MARKETPLACE_NAMES.find((n) => key.endsWith(`@${n}`));
+		if (oldName) {
+			const pluginName = key.slice(0, key.lastIndexOf("@"));
+			const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
+			// Don't overwrite if canonical key already exists
+			if (!record[newKey]) {
+				migrated[newKey] = value;
+			}
+			count++;
+		} else {
+			migrated[key] = value;
+		}
+	}
+	return [migrated, count];
+}
+
+/**
+ * Migrate a single settings object in-place.
+ * Returns number of keys renamed.
+ */
+function migrateSettingsObject(settings: ClaudeSettings): number {
+	let total = 0;
+
+	const [ep, epCount] = migratePluginKeys(settings.enabledPlugins);
+	if (epCount > 0) {
+		settings.enabledPlugins = ep;
+		total += epCount;
+	}
+
+	const [iv, ivCount] = migratePluginKeys(settings.installedPluginVersions);
+	if (ivCount > 0) {
+		settings.installedPluginVersions = iv;
+		total += ivCount;
+	}
+
+	// Migrate extraKnownMarketplaces keys
+	for (const oldName of OLD_MARKETPLACE_NAMES) {
+		if (settings.extraKnownMarketplaces?.[oldName]) {
+			const entry = settings.extraKnownMarketplaces[oldName];
+			delete settings.extraKnownMarketplaces[oldName];
+			if (!settings.extraKnownMarketplaces[NEW_MARKETPLACE_NAME]) {
+				settings.extraKnownMarketplaces[NEW_MARKETPLACE_NAME] = {
+					...entry,
+					source: {
+						...entry.source,
+						repo: NEW_MARKETPLACE_REPO,
+					},
+				};
+			}
+			total++;
+		}
+	}
+
+	// Fix stale repo URL on existing magus entry (e.g. key is "magus" but repo is still "MadAppGang/claude-code")
+	const magusEntry = settings.extraKnownMarketplaces?.[NEW_MARKETPLACE_NAME];
+	if (
+		magusEntry?.source?.repo &&
+		OLD_MARKETPLACE_REPOS.includes(magusEntry.source.repo)
+	) {
+		magusEntry.source.repo = NEW_MARKETPLACE_REPO;
+		total++;
+	}
+
+	return total;
+}
+
+export interface MigrationResult {
+	projectMigrated: number;
+	globalMigrated: number;
+	localMigrated: number;
+	knownMarketplacesMigrated: boolean;
+	registryMigrated: number;
+}
+
+/**
+ * Migrate all settings from mag-claude-plugins to magus.
+ * Safe to call multiple times — no-ops if already migrated.
+ * Runs across project settings, global settings, local settings,
+ * known_marketplaces.json, and installed_plugins.json.
+ */
+/**
+ * Decode a ~/.claude/projects/ directory name back to a filesystem path.
+ * Claude Code encodes paths by replacing "/" with "-", which is lossy when
+ * directory names themselves contain dashes (e.g., "circl-infra" → "circl/infra").
+ * Strategy: split on "-", then greedily recombine segments by checking which
+ * combinations actually exist on disk.
+ * Returns null if no valid path can be resolved.
+ */
+async function decodeProjectDirName(encoded: string): Promise<string | null> {
+	// Split into segments: "-Users-jack-dev-circl-infra" → ["Users","jack","dev","circl","infra"]
+	const segments = encoded.replace(/^-/, "").split("-");
+	if (segments.length === 0) return null;
+
+	// Build path greedily: at each step, try joining the next segment with a dash first
+	// (preserving directory names like "circl-infra"), fall back to slash (new path segment)
+	let current = `/${segments[0]}`;
+	for (let i = 1; i < segments.length; i++) {
+		const withDash = `${current}-${segments[i]}`;
+		const withSlash = `${current}/${segments[i]}`;
+		// Prefer dash (keeps compound names intact) if that path prefix exists
+		if (await fs.pathExists(withDash)) {
+			current = withDash;
+		} else {
+			current = withSlash;
+		}
+	}
+
+	return (await fs.pathExists(current)) ? current : null;
+}
+
+export async function migrateMarketplaceRename(
+	projectPath?: string,
+): Promise<MigrationResult> {
+	const result: MigrationResult = {
+		projectMigrated: 0,
+		globalMigrated: 0,
+		localMigrated: 0,
+		knownMarketplacesMigrated: false,
+		registryMigrated: 0,
+	};
+
+	// 1. Project settings
+	try {
+		const settings = await readSettings(projectPath);
+		const count = migrateSettingsObject(settings);
+		if (count > 0) {
+			await writeSettings(settings, projectPath);
+			result.projectMigrated = count;
+		}
+	} catch {
+		/* skip if unreadable */
+	}
+
+	// 2. Global settings
+	try {
+		const settings = await readGlobalSettings();
+		const count = migrateSettingsObject(settings);
+		if (count > 0) {
+			await writeGlobalSettings(settings);
+			result.globalMigrated = count;
+		}
+	} catch {
+		/* skip if unreadable */
+	}
+
+	// 3. Local settings (settings.local.json)
+	try {
+		const local = await readLocalSettings(projectPath);
+		let localCount = 0;
+		const [ep, epCount] = migratePluginKeys(local.enabledPlugins);
+		if (epCount > 0) {
+			local.enabledPlugins = ep;
+			localCount += epCount;
+		}
+		const [iv, ivCount] = migratePluginKeys(local.installedPluginVersions);
+		if (ivCount > 0) {
+			local.installedPluginVersions = iv;
+			localCount += ivCount;
+		}
+		if (localCount > 0) {
+			await writeLocalSettings(local, projectPath);
+			result.localMigrated = localCount;
+		}
+	} catch {
+		/* skip if unreadable */
+	}
+
+	// 4. known_marketplaces.json — rename old keys + physical directory cleanup
+	const pluginsDir = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"marketplaces",
+	);
+	const newDir = path.join(pluginsDir, NEW_MARKETPLACE_NAME);
+
+	try {
+		const known = await readKnownMarketplaces();
+		let knownModified = false;
+
+		for (const oldName of OLD_MARKETPLACE_NAMES) {
+			if (known[oldName]) {
+				const oldEntry = known[oldName];
+				// If canonical entry doesn't exist yet, create it
+				if (!known[NEW_MARKETPLACE_NAME]) {
+					known[NEW_MARKETPLACE_NAME] = {
+						...oldEntry,
+						source: {
+							...oldEntry.source,
+							repo: "MadAppGang/magus",
+						},
+					};
+				}
+				delete known[oldName];
+				knownModified = true;
+			}
+
+			// Ensure installLocation doesn't reference old directory names
+			if (known[NEW_MARKETPLACE_NAME]?.installLocation?.includes(oldName)) {
+				known[NEW_MARKETPLACE_NAME].installLocation = known[
+					NEW_MARKETPLACE_NAME
+				].installLocation.replace(oldName, NEW_MARKETPLACE_NAME);
+				knownModified = true;
+			}
+		}
+
+		if (knownModified) {
+			await writeKnownMarketplaces(known);
+			result.knownMarketplacesMigrated = true;
+		}
+	} catch {
+		/* skip if unreadable */
+	}
+
+	// 4b. Rename/remove old physical directories (runs even if keys were already migrated)
+	for (const oldName of OLD_MARKETPLACE_NAMES) {
+		const oldDir = path.join(pluginsDir, oldName);
+		try {
+			if (await fs.pathExists(oldDir)) {
+				if (!(await fs.pathExists(newDir))) {
+					await fs.rename(oldDir, newDir);
+				} else {
+					// Both exist — remove the old one (magus dir is canonical)
+					await fs.remove(oldDir);
+				}
+			}
+		} catch {
+			/* non-fatal: directory cleanup is best-effort */
+		}
+	}
+
+	// 4c. Update git remote URL in the marketplace clone (old → new repo)
+	try {
+		if (await fs.pathExists(path.join(newDir, ".git"))) {
+			const { execSync } = await import("node:child_process");
+			const remote = execSync("git remote get-url origin", {
+				cwd: newDir,
+				encoding: "utf-8",
+				timeout: 5000,
+			}).trim();
+			if (remote.includes("claude-code") && remote.includes("MadAppGang")) {
+				const newRemote = remote.replace("claude-code", NEW_MARKETPLACE_NAME);
+				execSync(`git remote set-url origin "${newRemote}"`, {
+					cwd: newDir,
+					encoding: "utf-8",
+					timeout: 5000,
+				});
+			}
+		}
+	} catch {
+		/* non-fatal: git remote update is best-effort */
+	}
+
+	// 5. installed_plugins.json — rename plugin ID keys
+	try {
+		const registry = await readInstalledPluginsRegistry();
+		let regCount = 0;
+		const newPlugins: typeof registry.plugins = {};
+		for (const [pluginId, entries] of Object.entries(registry.plugins)) {
+			const oldName = OLD_MARKETPLACE_NAMES.find((n) =>
+				pluginId.endsWith(`@${n}`),
+			);
+			if (oldName) {
+				const pluginName = pluginId.slice(0, pluginId.lastIndexOf("@"));
+				const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
+				if (!newPlugins[newKey]) {
+					newPlugins[newKey] = entries;
+				}
+				regCount++;
+			} else {
+				newPlugins[pluginId] = entries;
+			}
+		}
+		if (regCount > 0) {
+			registry.plugins = newPlugins;
+			await writeInstalledPluginsRegistry(registry);
+			result.registryMigrated = regCount;
+		}
+	} catch {
+		/* skip if unreadable */
+	}
+
+	// 6. Scan all known project settings (derived from ~/.claude/projects/ directory names)
+	try {
+		const projectsDir = path.join(os.homedir(), ".claude", "projects");
+		if (await fs.pathExists(projectsDir)) {
+			const entries = await fs.readdir(projectsDir);
+			const seenPaths = new Set<string>();
+			// Current project (from step 1) already handled — skip it
+			const currentProject = projectPath || process.cwd();
+			seenPaths.add(currentProject);
+
+			for (const entry of entries) {
+				const decoded = await decodeProjectDirName(entry);
+				if (!decoded || seenPaths.has(decoded)) continue;
+				seenPaths.add(decoded);
+
+				const settingsFile = path.join(decoded, ".claude", "settings.json");
+				try {
+					if (await fs.pathExists(settingsFile)) {
+						const raw = await fs.readJson(settingsFile);
+						const count = migrateSettingsObject(raw);
+						if (count > 0) {
+							await fs.writeJson(settingsFile, raw, { spaces: 2 });
+							result.projectMigrated += count;
+						}
+					}
+				} catch {
+					/* skip individual projects that fail */
+				}
+			}
+		}
+	} catch {
+		/* non-fatal: cross-project scan is best-effort */
+	}
+
+	return result;
+}
+
+/**
+ * Recover/sync marketplace settings:
+ * - Remove entries for marketplaces whose installLocation no longer exists
+ * - Fix stale "directory" source for known Magus marketplaces that should be "github"
+ *
+ * It does NOT touch `autoUpdate`. It used to set it to `true` on every
+ * MadAppGang entry whose flag was unset, on every TUI startup — writing a
+ * Claude Code-owned field that Claude Code also syncs from settings. See
+ * {@link getMarketplaceAutoUpdate}.
+ */
+export async function recoverMarketplaceSettings(): Promise<MarketplaceRecoveryResult> {
+	const known = await readKnownMarketplaces();
+	const result: MarketplaceRecoveryResult = {
+		removed: [],
+		reregistered: [],
+	};
+
+	const updatedKnown: KnownMarketplaces = {};
+
+	// Import defaultMarketplaces lazily to get canonical repo URLs
+	const { defaultMarketplaces } = await import("../data/marketplaces.js");
+
+	for (const [name, entry] of Object.entries(known)) {
+		// Check if install location still exists
+		if (
+			entry.installLocation &&
+			!(await fs.pathExists(entry.installLocation))
+		) {
+			result.removed.push(name);
+			continue;
+		}
+
+		// Fix stale "directory" source for known marketplaces.
+		// Some machines have magus registered as source: "directory" pointing to
+		// a local dev checkout. This prevents Claude Code's auto-update from
+		// refreshing the marketplace, causing "plugin not found" errors for
+		// newly added plugins. Re-register as "github" with the canonical repo.
+		if (entry.source?.source === "directory") {
+			const defaultMp = defaultMarketplaces.find((m) => m.name === name);
+			if (defaultMp?.source.repo) {
+				const marketplacesDir = path.join(
+					os.homedir(),
+					".claude",
+					"plugins",
+					"marketplaces",
+				);
+				entry.source = {
+					source: "github",
+					repo: defaultMp.source.repo,
+				};
+				entry.installLocation = path.join(marketplacesDir, name);
+				result.reregistered.push(name);
+			}
+		}
+
+		updatedKnown[name] = entry;
+	}
+
+	// Write back if any changes were made
+	if (result.removed.length > 0 || result.reregistered.length > 0) {
+		await writeKnownMarketplaces(updatedKnown);
+	}
+
+	return result;
+}
+
+/**
+ * Read known_marketplaces.json to get marketplace source info
+ */
+async function readKnownMarketplaces(): Promise<KnownMarketplaces> {
+	try {
+		if (await fs.pathExists(knownMarketplacesFile())) {
+			return await fs.readJson(knownMarketplacesFile());
+		}
+	} catch {
+		// Return empty if can't read
+	}
+	return {};
+}
+
+/**
+ * Check whether a marketplace is registered locally. A marketplace is
+ * considered registered when it has an entry in known_marketplaces.json
+ * AND its clone directory exists on disk. Either condition alone is not
+ * enough: an entry with a missing directory means the clone was lost; a
+ * directory without an entry means Claude Code doesn't know about it.
+ */
+export async function isMarketplaceRegistered(name: string): Promise<boolean> {
+	const known = await readKnownMarketplaces();
+	if (!known[name]) return false;
+	const marketplacesDir = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"marketplaces",
+	);
+	return fs.pathExists(path.join(marketplacesDir, name));
+}
+
+/**
+ * Get the source path for a plugin from its marketplace
+ * For directory-based marketplaces, returns the local directory path
+ * For GitHub marketplaces, returns the cloned repo path in ~/.claude/plugins/marketplaces/
+ */
+async function getPluginSourcePath(
+	pluginName: string,
+	marketplace: string,
+): Promise<string | null> {
+	const known = await readKnownMarketplaces();
+	const mpEntry = known[marketplace];
+
+	if (!mpEntry) {
+		return null;
+	}
+
+	let basePath: string;
+
+	if (mpEntry.source.source === "directory" && mpEntry.source.path) {
+		// Directory-based marketplace - use the source path directly
+		basePath = mpEntry.source.path;
+	} else {
+		// GitHub-based marketplace - use installLocation (cloned repo path)
+		basePath = mpEntry.installLocation;
+	}
+
+	// Look for plugin in standard locations
+	const possiblePaths = [
+		path.join(basePath, "plugins", pluginName),
+		path.join(basePath, pluginName),
+	];
+
+	for (const pluginPath of possiblePaths) {
+		if (await fs.pathExists(pluginPath)) {
+			return pluginPath;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Copy plugin files from source to cache
+ * This ensures the cache is populated with the latest plugin version
+ *
+ * Returns the directory the files were copied FROM, or null if nothing was
+ * copied. The caller needs the source path, not just a success flag: that path
+ * is what identifies the commit the cached files came from.
+ */
+async function copyPluginToCache(
+	pluginId: string,
+	version: string,
+	marketplace: string,
+): Promise<string | null> {
+	const { pluginName } = parsePluginId(pluginId) || {
+		pluginName: pluginId.split("@")[0],
+	};
+
+	const sourcePath = await getPluginSourcePath(pluginName, marketplace);
+	if (!sourcePath) {
+		return null;
+	}
+
+	const cachePath = getPluginCachePath(pluginId, version, marketplace);
+
+	try {
+		// Remove existing cache directory if it exists
+		if (await fs.pathExists(cachePath)) {
+			await fs.remove(cachePath);
+		}
+
+		// Copy plugin files to cache
+		await fs.copy(sourcePath, cachePath, {
+			overwrite: true,
+			errorOnExist: false,
+		});
+
+		return sourcePath;
+	} catch (error) {
+		console.warn(
+			`Failed to copy plugin ${pluginId} to cache:`,
+			error instanceof Error ? error.message : "Unknown error",
+		);
+		return null;
+	}
+}
+
+/**
+ * The commit a cache copy should be stamped with.
+ *
+ * `gitCommitSha` must describe the files sitting in the cache RIGHT NOW, which
+ * is the single thing content-drift detection reads it for. Two rules:
+ *
+ * - Files were copied → the source repo's HEAD is their provenance. Undefined
+ *   is a legitimate answer here: a directory-type marketplace has no commit,
+ *   and content-drift stays silent rather than guessing.
+ * - Nothing was copied → the cache is untouched, so whatever sha already
+ *   described it still does. Advancing it would claim the cache holds newer
+ *   files than it does, hiding real drift.
+ *
+ * The bug this replaces did neither: it preserved the pre-update sha even when
+ * fresh files HAD been copied, so the recorded commit drifted further behind
+ * with every release and drift detection reported a false positive on every
+ * plugin at once.
+ */
+export async function resolveCacheProvenance(
+	copiedFrom: string | null,
+	previousSha: string | undefined,
+): Promise<string | undefined> {
+	if (!copiedFrom) return previousSha;
+	return await repoHeadSha(copiedFrom);
+}
+
+/**
+ * Read installed_plugins.json registry
+ */
+export async function readInstalledPluginsRegistry(): Promise<InstalledPluginsRegistry> {
+	try {
+		if (await fs.pathExists(installedPluginsFile())) {
+			const content = await fs.readJson(installedPluginsFile());
+			// Validate structure
+			if (!content.version || !content.plugins) {
+				throw new Error("Invalid registry structure");
+			}
+			return content;
+		}
+	} catch (error) {
+		// Backup corrupted file
+		if (await fs.pathExists(installedPluginsFile())) {
+			try {
+				const backup = `${installedPluginsFile()}.backup.${Date.now()}`;
+				await fs.copy(installedPluginsFile(), backup);
+				console.warn(`Corrupted registry backed up to: ${backup}`);
+			} catch {
+				// Ignore backup errors
+			}
+		}
+	}
+	return { version: 2, plugins: {} };
+}
+
+/**
+ * Write installed_plugins.json registry
+ */
+export async function writeInstalledPluginsRegistry(
+	registry: InstalledPluginsRegistry,
+): Promise<void> {
+	await fs.ensureDir(path.dirname(installedPluginsFile()));
+	await fs.writeJson(installedPluginsFile(), registry, { spaces: 2 });
+}
+
+/**
+ * Get install path for a plugin version in cache
+ */
+function getPluginCachePath(
+	pluginId: string,
+	version: string,
+	marketplace: string,
+): string {
+	const { pluginName } = parsePluginId(pluginId) || {
+		pluginName: pluginId.split("@")[0],
+	};
+	return path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"cache",
+		marketplace,
+		pluginName,
+		version,
+	);
+}
+
+/**
+ * Update installed_plugins.json when a plugin is installed/updated
+ * Also copies plugin files from source to cache to ensure latest version is available
+ */
+export async function updateInstalledPluginsRegistry(
+	pluginId: string,
+	version: string,
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<void> {
+	try {
+		const registry = await readInstalledPluginsRegistry();
+
+		// Get marketplace from plugin ID
+		const parsed = parsePluginId(pluginId);
+		if (!parsed) {
+			console.warn(`Invalid plugin ID: ${pluginId}, skipping registry update`);
+			return;
+		}
+
+		const { marketplace } = parsed;
+
+		// Copy plugin files from source to cache
+		// This ensures the cache has the latest plugin version
+		const copiedFrom = await copyPluginToCache(pluginId, version, marketplace);
+
+		const installPath = getPluginCachePath(pluginId, version, marketplace);
+		const now = new Date().toISOString();
+
+		// Initialize plugin array if it doesn't exist
+		if (!registry.plugins[pluginId]) {
+			registry.plugins[pluginId] = [];
+		}
+
+		// Find existing entry for this scope and project
+		const existingIndex = registry.plugins[pluginId].findIndex((entry) => {
+			if (entry.scope !== scope) return false;
+			if (scope === "user") return true;
+			return entry.projectPath === projectPath;
+		});
+
+		const entry: InstalledPluginEntry = {
+			scope,
+			projectPath,
+			installPath,
+			version,
+			installedAt:
+				existingIndex >= 0
+					? registry.plugins[pluginId][existingIndex].installedAt
+					: now,
+			lastUpdated: now,
+			gitCommitSha: await resolveCacheProvenance(
+				copiedFrom,
+				existingIndex >= 0
+					? registry.plugins[pluginId][existingIndex].gitCommitSha
+					: undefined,
+			),
+		};
+
+		if (existingIndex >= 0) {
+			// Update existing entry
+			registry.plugins[pluginId][existingIndex] = entry;
+		} else {
+			// Add new entry
+			registry.plugins[pluginId].push(entry);
+		}
+
+		await writeInstalledPluginsRegistry(registry);
+	} catch (error) {
+		// Log warning but don't block plugin operation
+		console.warn(
+			`Failed to update registry for ${pluginId}:`,
+			error instanceof Error ? error.message : "Unknown error",
+		);
+	}
+}
+
+/**
+ * Remove plugin from installed_plugins.json registry
+ */
+export async function removeFromInstalledPluginsRegistry(
+	pluginId: string,
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<void> {
+	try {
+		const registry = await readInstalledPluginsRegistry();
+
+		if (!registry.plugins[pluginId]) return;
+
+		// Remove entry matching scope and projectPath
+		registry.plugins[pluginId] = registry.plugins[pluginId].filter((entry) => {
+			if (entry.scope !== scope) return true;
+			if (scope === "user") return false;
+			return entry.projectPath !== projectPath;
+		});
+
+		// Remove plugin key if no entries remain
+		if (registry.plugins[pluginId].length === 0) {
+			delete registry.plugins[pluginId];
+		}
+
+		await writeInstalledPluginsRegistry(registry);
+	} catch (error) {
+		// Log warning but don't block plugin operation
+		console.warn(
+			`Failed to remove from registry for ${pluginId}:`,
+			error instanceof Error ? error.message : "Unknown error",
+		);
+	}
+}