claudeup 4.18.0 → 4.22.0

package/src/services/manifest.ts

@@ -0,0 +1,166 @@
+/**
+ * Team profile manifest (.claude/profiles.json) — read, migrate, validate.
+ *
+ * This is the v2 view over the same project-scoped profiles.json that the TUI's
+ * v1 saved-profiles code (services/profiles.ts) reads. v1 files migrate forward
+ * transparently: a v1 profile (`{name, plugins: Record<string,boolean>}`) is a
+ * structural subset of a v2 manifest entry, so migration is a version bump.
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
+
+const PROFILES_FILE = "profiles.json";
+
+/** Project-scoped manifest path: <projectPath|cwd>/.claude/profiles.json */
+export function getManifestPath(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", PROFILES_FILE);
+}
+
+/** An empty, valid v2 manifest. */
+export function emptyManifest(): ProfileManifest {
+	return { version: 2, profiles: {} };
+}
+
+/**
+ * Normalize any parsed profiles.json (v1 or v2) into a v2 manifest.
+ * Unknown/missing shapes degrade to an empty manifest rather than throwing —
+ * validation is the caller's job via {@link validateManifest}.
+ */
+export function migrateToV2(raw: unknown): ProfileManifest {
+	if (!raw || typeof raw !== "object") return emptyManifest();
+	const obj = raw as Record<string, unknown>;
+
+	const profilesRaw =
+		obj.profiles && typeof obj.profiles === "object"
+			? (obj.profiles as Record<string, unknown>)
+			: {};
+
+	const profiles: Record<string, ProfileManifestEntry> = {};
+	for (const [id, entry] of Object.entries(profilesRaw)) {
+		if (entry && typeof entry === "object") {
+			// v1 and v2 entries are both accepted as-is; v1's plugins map
+			// (Record<string, boolean>) is valid under v2's widened type.
+			profiles[id] = entry as ProfileManifestEntry;
+		}
+	}
+
+	const manifest: ProfileManifest = { version: 2, profiles };
+	// Only carry strictVersions when enabled, so a committed manifest that
+	// doesn't opt in stays minimal (no spurious `"strictVersions": false`).
+	if (obj.strictVersions === true) manifest.strictVersions = true;
+	return manifest;
+}
+
+/**
+ * Read and migrate the project manifest. Returns an empty v2 manifest if the
+ * file is absent or unreadable.
+ */
+export async function readManifest(
+	projectPath?: string,
+): Promise<ProfileManifest> {
+	const filePath = getManifestPath(projectPath);
+	try {
+		if (await fs.pathExists(filePath)) {
+			return migrateToV2(await fs.readJson(filePath));
+		}
+	} catch {
+		// Corrupt/unreadable — fall through to empty.
+	}
+	return emptyManifest();
+}
+
+/** Write the manifest back to disk (used by `profile sync`, tests). */
+export async function writeManifest(
+	manifest: ProfileManifest,
+	projectPath?: string,
+): Promise<void> {
+	const filePath = getManifestPath(projectPath);
+	await fs.ensureDir(path.dirname(filePath));
+	await fs.writeJson(filePath, manifest, { spaces: 2 });
+}
+
+export interface ManifestValidationError {
+	/** Dotted path to the offending field, e.g. "profiles.frontend.plugins". */
+	path: string;
+	message: string;
+}
+
+/**
+ * Validate a manifest structurally. Returns an empty array when valid.
+ * Strict enough to back `install --check`; does not touch the network or FS.
+ */
+export function validateManifest(
+	manifest: ProfileManifest,
+): ManifestValidationError[] {
+	const errors: ManifestValidationError[] = [];
+
+	if (manifest.version !== 2) {
+		errors.push({
+			path: "version",
+			message: `expected version 2, got ${JSON.stringify(manifest.version)}`,
+		});
+	}
+
+	const ids = Object.keys(manifest.profiles ?? {});
+	if (ids.length === 0) {
+		errors.push({ path: "profiles", message: "no profiles defined" });
+	}
+
+	for (const [id, entry] of Object.entries(manifest.profiles ?? {})) {
+		const base = `profiles.${id}`;
+		if (!entry || typeof entry !== "object") {
+			errors.push({ path: base, message: "profile must be an object" });
+			continue;
+		}
+		if (!entry.name || typeof entry.name !== "string") {
+			errors.push({ path: `${base}.name`, message: "missing name" });
+		}
+		if (entry.plugins !== undefined) {
+			for (const [pluginId, ver] of Object.entries(entry.plugins)) {
+				if (typeof ver !== "string" && typeof ver !== "boolean") {
+					errors.push({
+						path: `${base}.plugins.${pluginId}`,
+						message: "version must be a string or boolean",
+					});
+				}
+				if (!pluginId.includes("@")) {
+					errors.push({
+						path: `${base}.plugins.${pluginId}`,
+						message: "plugin id must be in the form name@marketplace",
+					});
+				}
+			}
+		}
+		if (entry.marketplaces !== undefined) {
+			for (const [mpName, ref] of Object.entries(entry.marketplaces)) {
+				if (ref.source === "github" && !ref.repo) {
+					errors.push({
+						path: `${base}.marketplaces.${mpName}`,
+						message: "github marketplace requires `repo`",
+					});
+				}
+				if (ref.source === "directory" && !ref.path) {
+					errors.push({
+						path: `${base}.marketplaces.${mpName}`,
+						message: "directory marketplace requires `path`",
+					});
+				}
+			}
+		}
+		if (entry.skills !== undefined) {
+			entry.skills.forEach((s, i) => {
+				if (!s.name || !s.repo || !s.path) {
+					errors.push({
+						path: `${base}.skills[${i}]`,
+						message: "skill requires name, repo, and path",
+					});
+				}
+			});
+		}
+	}
+
+	return errors;
+}

package/src/services/marketplace-refresh.ts

@@ -0,0 +1,173 @@
+/**
+ * Keep on-disk marketplace clones current — safely.
+ *
+ * The plugin *list* claudeup shows is fetched fresh from GitHub, but a plugin's
+ * `setup` block and Claude Code's own installer read the on-disk marketplace
+ * clone (~/.claude/plugins/marketplaces/<name>). Nothing else keeps that clone
+ * current — recoverMarketplaceSettings only pulls entries it had to re-register —
+ * so a healthy marketplace's clone goes stale and its plugin metadata (e.g. a
+ * pinned dependency version in a plugin's setup) is never seen, even while the
+ * displayed version looks up to date.
+ *
+ * IMPORTANT: this refreshes the clone with a NON-DESTRUCTIVE `git pull --ff-only`,
+ * never `claude plugin marketplace update`. The latter (cacheMarketplaceFromGit)
+ * deletes the clone directory before re-cloning, so a failed clone leaves the
+ * marketplace permanently deleted — a documented hazard this codebase deliberately
+ * avoids (see marketplace-sync.ts and ai-docs/plugin-marketplace-bug-investigation.md).
+ * A failed `git pull --ff-only` leaves the clone exactly as it was: stale, but intact.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	getConfiguredMarketplaces,
+	getGlobalClaudeDir,
+	getMarketplaceAutoUpdate,
+} from "./claude-settings.js";
+
+/** Per-git-invocation timeout. A hung pull must never block launching Claude. */
+const GIT_TIMEOUT_MS = 30_000;
+
+export interface RefreshResult {
+	/** Clones fast-forwarded to a newer commit (or already current). */
+	refreshed: string[];
+	/** Pull errored (network, diverged, timeout) — clone left intact and stale. */
+	failed: string[];
+	/** Nothing to do: no clone on disk, not a git repo, dirty tree, or opted out. */
+	skipped: string[];
+}
+
+function cloneDir(name: string): string {
+	return path.join(getGlobalClaudeDir(), "plugins", "marketplaces", name);
+}
+
+/** Run git in `cwd`, resolving stdout on exit 0. Killed after `timeoutMs`. */
+function runGit(
+	cwd: string,
+	args: string[],
+	timeoutMs: number,
+): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn("git", args, {
+			cwd,
+			timeout: timeoutMs,
+			killSignal: "SIGKILL",
+		});
+		let stdout = "";
+		let stderr = "";
+		proc.stdout?.on("data", (b) => {
+			stdout += b.toString();
+		});
+		proc.stderr?.on("data", (b) => {
+			stderr += b.toString();
+		});
+		proc.on("error", reject);
+		proc.on("close", (code, signal) => {
+			if (code === 0) {
+				resolve(stdout);
+			} else {
+				reject(
+					new Error(
+						`git ${args.join(" ")} ${
+							signal ? `killed (${signal})` : `exited ${code}`
+						}: ${stderr.trim()}`,
+					),
+				);
+			}
+		});
+	});
+}
+
+/** True if the clone has uncommitted changes we must not clobber. */
+async function isDirty(dir: string): Promise<boolean> {
+	const out = await runGit(dir, ["status", "--porcelain"], GIT_TIMEOUT_MS);
+	return out.trim().length > 0;
+}
+
+/**
+ * Outcome of fast-forwarding one clone:
+ *  - `absent`    no clone on disk (caller may create it via `marketplace add`)
+ *  - `skipped`   dirty tree — left untouched so local edits survive
+ *  - `refreshed` fast-forwarded, or already current
+ *  - `failed`    pull errored (network, diverged, timeout) — clone left intact
+ */
+export type CloneRefresh = "absent" | "skipped" | "refreshed" | "failed";
+
+/**
+ * Non-destructively fast-forward ONE marketplace clone. Never throws, never
+ * deletes: the worst case is `failed` (stale clone left intact). Shared by the
+ * batch refresh below and by claude-cli's "plugin not found" recovery, so both
+ * paths get the same safe semantics instead of the old `marketplace update`.
+ */
+export async function fastForwardCloneIfPresent(
+	name: string,
+): Promise<CloneRefresh> {
+	const dir = cloneDir(name);
+	// No clone on disk (claude never installed it) or not a git repo.
+	if (!fs.existsSync(path.join(dir, ".git"))) return "absent";
+	try {
+		// Never clobber a user's local edits to the clone.
+		if (await isDirty(dir)) return "skipped";
+		// --ff-only is the safety guarantee: it fetches and fast-forwards, and
+		// aborts without mutating the tree if it can't. It never deletes the dir,
+		// so a failure degrades to "stale clone", never "deleted marketplace".
+		await runGit(dir, ["pull", "--ff-only"], GIT_TIMEOUT_MS);
+		return "refreshed";
+	} catch {
+		return "failed";
+	}
+}
+
+/**
+ * Non-destructively fast-forward the on-disk clone of every registered,
+ * auto-update-enabled, github-sourced marketplace.
+ *
+ * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
+ *   so they aren't pulled twice.
+ * @returns which marketplaces were refreshed, which failed (clone left intact),
+ *   and which were skipped. Failures and skips are collected rather than thrown —
+ *   one unreachable marketplace must not block launching Claude. Pulls run
+ *   concurrently, so a slow one doesn't serialize the rest onto the launch path.
+ */
+export async function refreshRegisteredMarketplaces(
+	skip: Iterable<string> = [],
+): Promise<RefreshResult> {
+	const refreshed: string[] = [];
+	const failed: string[] = [];
+	const skipped: string[] = [];
+
+	const configured = await getConfiguredMarketplaces();
+	const skipSet = new Set(skip);
+
+	// Select eligible marketplaces first so the pulls can run concurrently.
+	const eligible: string[] = [];
+	for (const [name, cfg] of Object.entries(configured)) {
+		if (skipSet.has(name)) continue;
+		if (cfg.source?.source !== "github" || !cfg.source?.repo) {
+			skipped.push(name);
+			continue;
+		}
+		if ((await getMarketplaceAutoUpdate(name)) === false) {
+			skipped.push(name);
+			continue;
+		}
+		eligible.push(name);
+	}
+
+	// Fast-forward every eligible clone in parallel so a slow one doesn't
+	// serialize the rest onto the launch path. fastForwardCloneIfPresent never
+	// throws, so the batch always resolves.
+	const statuses = await Promise.all(
+		eligible.map((name) => fastForwardCloneIfPresent(name)),
+	);
+
+	statuses.forEach((status, i) => {
+		const name = eligible[i];
+		if (status === "refreshed") refreshed.push(name);
+		else if (status === "failed") failed.push(name);
+		else skipped.push(name); // absent | skipped
+	});
+
+	return { refreshed, failed, skipped };
+}

package/src/services/plugin-manager.ts

@@ -11,6 +11,7 @@ import {
 	getGlobalInstalledPluginVersions,
 	getLocalEnabledPlugins,
 	getLocalInstalledPluginVersions,
+	getProjectInstalledPluginVersions,
 	updateInstalledPluginsRegistry,
 	removeFromInstalledPluginsRegistry,
 } from "./claude-settings.js";
@@ -470,7 +471,12 @@ async function getInstalledPluginVersions(
 	projectPath?: string,
 ): Promise<Record<string, string>> {
 	const settings = await readSettings(projectPath);
-	return settings.installedPluginVersions || {};
+	// 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

package/src/services/plugin-requires.ts

@@ -0,0 +1,215 @@
+/**
+ * Read plugin-declared binary dependencies from plugin.json `requires.bin`.
+ *
+ * A plugin declares the binaries it needs on PATH (e.g. terminal@magus needs
+ * `tmux` and `tmux-mcp`). `claudeup install` resolves these transitively so a
+ * teammate who enables a plugin also gets its binaries — closing the class of
+ * bug where a plugin's MCP server silently fails because its binary is missing.
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import os from "node:os";
+import type {
+	BinInstaller,
+	BinRequirement,
+	PluginRequires,
+} from "../types/index.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import { getLocalMarketplacesInfo } from "./plugin-manager.js";
+
+const MARKETPLACES_DIR = (): string =>
+	path.join(os.homedir(), ".claude", "plugins", "marketplaces");
+
+const VALID_INSTALLERS: readonly BinInstaller[] = [
+	"bun",
+	"brew",
+	"npm",
+	"pip",
+	"go",
+];
+
+/**
+ * Normalize a raw `requires.bin` entry into a complete BinRequirement,
+ * filling in defaults. Returns null for entries that can't be made valid
+ * (missing name, or an unrecognized installer).
+ */
+function normalizeBin(raw: unknown): BinRequirement | null {
+	if (!raw || typeof raw !== "object") return null;
+	const o = raw as Record<string, unknown>;
+	const name = typeof o.name === "string" ? o.name.trim() : "";
+	if (!name) return null;
+
+	const via = o.via as BinInstaller;
+	if (!VALID_INSTALLERS.includes(via)) return null;
+
+	const bin: BinRequirement = {
+		name,
+		via,
+		check:
+			typeof o.check === "string" && o.check.trim()
+				? o.check.trim()
+				: `${name} --version`,
+	};
+	if (typeof o.package === "string") bin.package = o.package;
+	if (typeof o.formula === "string") bin.formula = o.formula;
+	if (typeof o.module === "string") bin.module = o.module;
+	if (typeof o.version === "string") bin.version = o.version;
+	return bin;
+}
+
+/** Split a package/module spec into its base and optional version. Handles
+ *  scoped npm (@scope/pkg@1.2.0) and go modules (host/path@latest). */
+function splitVersion(spec: string): { base: string; version?: string } {
+	const at = spec.lastIndexOf("@");
+	// at > 0 avoids treating a leading npm scope "@scope/..." as a version.
+	if (at > 0) return { base: spec.slice(0, at), version: spec.slice(at + 1) };
+	return { base: spec };
+}
+
+const basename = (p: string): string => p.split("/").pop() ?? p;
+
+/**
+ * Map a plugin.json `setup` block (the established convention: browser-use uses
+ * `pip`, terminal uses `go` + `required`) to BinRequirements.
+ *   setup: { bun|npm|pip: string[], go: string[], brew: string[], required: string[] }
+ */
+function parseSetup(setup: unknown): BinRequirement[] {
+	if (!setup || typeof setup !== "object") return [];
+	const s = setup as Record<string, unknown>;
+	const bins: BinRequirement[] = [];
+
+	const pkgManager = (
+		key: "bun" | "npm" | "pip",
+	): void => {
+		for (const spec of (s[key] as string[] | undefined) ?? []) {
+			if (typeof spec !== "string") continue;
+			const { base, version } = splitVersion(spec);
+			bins.push({
+				name: basename(base),
+				via: key,
+				package: base,
+				version,
+				check: `${basename(base)} --version`,
+			});
+		}
+	};
+	pkgManager("bun");
+	pkgManager("npm");
+	pkgManager("pip");
+
+	for (const spec of (s.go as string[] | undefined) ?? []) {
+		if (typeof spec !== "string") continue;
+		const { base, version } = splitVersion(spec);
+		bins.push({
+			name: basename(base),
+			via: "go",
+			module: base,
+			version,
+			check: `${basename(base)} --version`,
+		});
+	}
+	for (const spec of (s.brew as string[] | undefined) ?? []) {
+		if (typeof spec !== "string") continue;
+		bins.push({ name: spec, via: "brew", formula: spec, check: `${spec} --version` });
+	}
+	// `required` names a system tool that must be present; brew is the assumed
+	// installer (matches the "system tools via brew" decision).
+	for (const name of (s.required as string[] | undefined) ?? []) {
+		if (typeof name !== "string") continue;
+		bins.push({ name, via: "brew", formula: name, check: `${name} --version` });
+	}
+
+	return bins;
+}
+
+/**
+ * Parse a plugin.json's binary requirements from BOTH the established `setup`
+ * block and the richer explicit `requires.bin` form. On a name collision the
+ * explicit `requires.bin` entry wins (it can override installer/check/version).
+ */
+export function parsePluginRequires(pluginJson: unknown): PluginRequires {
+	if (!pluginJson || typeof pluginJson !== "object") return {};
+	const obj = pluginJson as Record<string, unknown>;
+
+	const fromSetup = parseSetup(obj.setup);
+
+	const requires = obj.requires;
+	const binRaw =
+		requires && typeof requires === "object"
+			? (requires as Record<string, unknown>).bin
+			: undefined;
+	const fromRequires = Array.isArray(binRaw)
+		? binRaw.map(normalizeBin).filter((b): b is BinRequirement => b !== null)
+		: [];
+
+	// Merge, requires.bin winning by name.
+	const byName = new Map<string, BinRequirement>();
+	for (const b of fromSetup) byName.set(b.name, b);
+	for (const b of fromRequires) byName.set(b.name, b);
+
+	const bin = [...byName.values()];
+	return bin.length > 0 ? { bin } : {};
+}
+
+/** Read `requires` from a plugin.json at a known plugin directory. */
+export async function readPluginRequires(
+	pluginPath: string,
+): Promise<PluginRequires> {
+	const manifestPath = path.join(pluginPath, "plugin.json");
+	try {
+		if (await fs.pathExists(manifestPath)) {
+			return parsePluginRequires(await fs.readJson(manifestPath));
+		}
+		// Some plugins nest the manifest under .claude-plugin/plugin.json.
+		const nested = path.join(pluginPath, ".claude-plugin", "plugin.json");
+		if (await fs.pathExists(nested)) {
+			return parsePluginRequires(await fs.readJson(nested));
+		}
+	} catch {
+		// Unreadable/malformed — treat as no requirements.
+	}
+	return {};
+}
+
+/**
+ * Resolve a plugin id (name@marketplace) to its on-disk source directory in
+ * the local marketplace cache. Returns null if the marketplace/plugin/source
+ * can't be located. Mirrors doctor.ts's resolvePluginPath.
+ */
+export async function resolvePluginPath(
+	pluginId: string,
+): Promise<string | null> {
+	const parsed = parsePluginId(pluginId);
+	if (!parsed) return null;
+	const { pluginName, marketplace } = parsed;
+
+	const localMarketplaces = await getLocalMarketplacesInfo();
+	const localMp = localMarketplaces.get(marketplace);
+	if (!localMp) return null;
+
+	const localPlugin = localMp.plugins.find((p) => p.name === pluginName);
+	if (!localPlugin?.source || typeof localPlugin.source !== "string") {
+		return null;
+	}
+
+	const pluginPath = path.join(
+		MARKETPLACES_DIR(),
+		marketplace,
+		localPlugin.source.replace("./", ""),
+	);
+	return (await fs.pathExists(pluginPath)) ? pluginPath : null;
+}
+
+/**
+ * Resolve the binary requirements a plugin declares. Returns an empty array
+ * when the plugin can't be located or declares none.
+ */
+export async function resolvePluginBinRequirements(
+	pluginId: string,
+): Promise<BinRequirement[]> {
+	const pluginPath = await resolvePluginPath(pluginId);
+	if (!pluginPath) return [];
+	const requires = await readPluginRequires(pluginPath);
+	return requires.bin ?? [];
+}

package/src/services/plugin-setup.ts

@@ -295,6 +295,65 @@ export function extractGoBinaryName(pkg: string): string {
 	return withoutVersion.split("/").pop() || pkg;
 }
 
+/**
+ * Extract the pinned version from a Go module path, or null when unpinned.
+ * e.g., "github.com/MadAppGang/tmux-mcp@v1.6.2" → "v1.6.2"
+ *       "github.com/MadAppGang/tmux-mcp@latest" → null (a moving target)
+ *       "github.com/user/tool"                  → null
+ */
+export function extractGoVersion(pkg: string): string | null {
+	const at = pkg.lastIndexOf("@");
+	if (at === -1) return null;
+	const version = pkg.slice(at + 1);
+	if (version === "" || version === "latest") return null;
+	return version;
+}
+
+/** Normalize a semver-ish string for comparison: trim and drop a leading "v". */
+function normalizeVersion(v: string): string {
+	return v.trim().replace(/^v/, "");
+}
+
+/**
+ * Read an installed binary's version via `<binary> --version`, normalized, or
+ * null if it produced no usable version string. Used to tell whether a pinned Go
+ * dependency is already at the right version.
+ */
+async function getInstalledBinaryVersion(
+	binaryName: string,
+): Promise<string | null> {
+	const { ok, stdout } = await run(binaryName, ["--version"], 10000);
+	if (!ok || !stdout) return null;
+	const match = stdout.split("\n")[0].match(/v?\d+\.\d+\.\d+[^\s]*/);
+	return match ? normalizeVersion(match[0]) : null;
+}
+
+/**
+ * Decide whether a Go dependency needs (re)installing. This is what makes a
+ * plugin *update* actually update its binary: without a version check an
+ * already-present binary is skipped forever, so a bumped plugin never pulls the
+ * new binary.
+ *
+ *  - binary absent                                    → yes
+ *  - pinned version, installed reports the same one   → no
+ *  - pinned version, installed reports a different one → yes
+ *  - pinned version, installed version can't be read  → yes (can't confirm the
+ *    pin, so reinstall to be safe)
+ *  - unpinned (@latest) and present                   → no (a moving target
+ *    can't be verified without a network round-trip)
+ */
+export async function goDepNeedsInstall(pkg: string): Promise<boolean> {
+	const binaryName = extractGoBinaryName(pkg);
+	if (!(await isBinaryAvailable(binaryName))) return true;
+
+	const pinned = extractGoVersion(pkg);
+	if (!pinned) return false;
+
+	const installed = await getInstalledBinaryVersion(binaryName);
+	if (installed === null) return true;
+	return normalizeVersion(pinned) !== installed;
+}
+
 /**
  * Install Go packages via `go install`
  */
@@ -311,8 +370,7 @@ async function installGoPackages(
 	}
 
 	for (const pkg of packages) {
-		const binaryName = extractGoBinaryName(pkg);
-		if (await isBinaryAvailable(binaryName)) {
+		if (!(await goDepNeedsInstall(pkg))) {
 			result.skipped.push(`go:${pkg}`);
 			continue;
 		}
@@ -515,8 +573,7 @@ export async function checkMissingDeps(
 	if (setup.go?.length) {
 		const missingGo: string[] = [];
 		for (const pkg of setup.go) {
-			const bin = extractGoBinaryName(pkg);
-			if (!(await isBinaryAvailable(bin))) {
+			if (await goDepNeedsInstall(pkg)) {
 				missingGo.push(pkg);
 			}
 		}

package/src/services/plugin-version-check.ts

@@ -1,14 +1,19 @@
 /**
  * Plugin version mismatch detection and fix.
  *
- * Claude Code's plugin loader (pluginLoader.ts:2051) takes the FIRST entry
+ * HISTORICAL (pre-2.1.209): Claude Code's plugin loader took the FIRST entry
  * from installed_plugins.json for each plugin ID:
  *
  *   const installEntry = installedPluginsData.plugins[pluginId]?.[0]
  *
- * This means the first project to install a plugin determines which version
- * loads for ALL projects. When different projects install different versions,
- * only the one at index [0] takes effect.
+ * so the first project to install a plugin determined the version loaded for
+ * ALL projects (bug #45997).
+ *
+ * FIXED in Claude Code 2.1.209: the loader is now project-aware — it filters
+ * entries to the current project/scope (same git root or user/managed scope)
+ * BEFORE selecting, so cross-project [0] contention no longer applies. This
+ * detection therefore mostly warns on older Claude Code; it is retained for
+ * those versions but should not be treated as a current-version defect.
  *
  * Bug report: https://github.com/anthropics/claude-code/issues/45997
  */