@mxalbert/context-mode 2.0.0

package/scripts/heal-installed-plugins.mjs

@@ -0,0 +1,635 @@
+/**
+ * Self-heal `~/.claude/plugins/installed_plugins.json` (#46915 follow-up).
+ *
+ * v1.0.113's `/ctx-upgrade` poisoned this file in two ways:
+ *   1. Per-entry `version` drifted from the actual cache directory's
+ *      `plugin.json` version.
+ *   2. The top-level `enabledPlugins[<key>]` was emptied (or never set)
+ *      so Claude Code's plugin loader skipped context-mode → MCP died.
+ *
+ * Single source of truth shared by:
+ *   - `start.mjs` HEAL 3+4 (every MCP boot)
+ *   - `scripts/postinstall.mjs` (every `npm install -g @mxalbert/context-mode`)
+ *
+ * Pure Node.js (built-ins only). Best-effort: never throws, always
+ * returns a plain result object so callers can log a one-liner.
+ *
+ * @see https://github.com/anthropics/claude-code/issues/46915
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+// npm package identity (v2.0.0 fork rename). The plugin/display id stays
+// "context-mode"; only the npm package name is scoped.
+export const PACKAGE_NAME = "@mxalbert/context-mode";
+export const PLUGIN_ID = "context-mode";
+// Claude Code registry key: "<pluginId>@<npmPackage>". A scoped package
+// yields a double-@ key ("context-mode@@mxalbert/context-mode").
+export const PLUGIN_KEY = `${PLUGIN_ID}@${PACKAGE_NAME}`;
+
+/**
+ * Parse a plugin registry key of the shape "<pluginId>@<npmPackage>" where
+ * <npmPackage> may be scoped ("@scope/name"). Returns the pluginId (segment
+ * before the FIRST "@") and the package segment (everything after it,
+ * verbatim — including a leading "@" for scoped packages). Splitting at the
+ * first "@" keeps legacy keys ("context-mode@context-mode") and scoped keys
+ * ("context-mode@@mxalbert/context-mode") both well-formed; a plain
+ * `split("@")` would mangle scoped keys into an empty middle segment.
+ *
+ * @param {string} pluginKey
+ * @returns {{ id: string, pkg: string } | null} null when the key has no
+ *   separator (bad shape).
+ */
+function parsePluginKey(pluginKey) {
+  const sepIdx = pluginKey.indexOf("@");
+  if (sepIdx <= 0) return null;
+  return { id: pluginKey.slice(0, sepIdx), pkg: pluginKey.slice(sepIdx + 1) };
+}
+
+/**
+ * @typedef {Object} HealResult
+ * @property {string[]} healed - one of: "entry-version", "enabled-plugins"
+ * @property {string} [skipped] - reason if no work performed
+ * @property {string} [error] - error message if heal aborted
+ */
+
+/**
+ * Heal a single plugin entry inside installed_plugins.json.
+ *
+ * @param {{
+ *   registryPath: string,
+ *   pluginCacheRoot: string,
+ *   pluginKey: string,
+ * }} opts
+ * @returns {HealResult}
+ */
+export function healInstalledPlugins({ registryPath, pluginCacheRoot, pluginKey }) {
+  if (!registryPath || !existsSync(registryPath)) {
+    return { healed: [], skipped: "no-registry" };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(registryPath, "utf-8");
+  } catch (err) {
+    return { healed: [], error: `read-failed: ${(err && err.message) || err}` };
+  }
+
+  let ip;
+  try {
+    ip = JSON.parse(raw);
+  } catch (err) {
+    return { healed: [], error: `parse-failed: ${(err && err.message) || err}` };
+  }
+  if (!ip || typeof ip !== "object") {
+    return { healed: [], error: "bad-shape" };
+  }
+
+  const entries = (ip.plugins && ip.plugins[pluginKey]) || [];
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return { healed: [], skipped: "no-entry" };
+  }
+
+  /** @type {string[]} */
+  const healed = [];
+  let syncedVersion = null;
+
+  // ── HEAL 3: per-entry version <- cache plugin.json version ──
+  // We trust the cache directory because that's what start.mjs actually
+  // boots from; the registry is just a stale label.
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const installPath = entry.installPath;
+    if (!installPath || typeof installPath !== "string") continue;
+
+    // Path-traversal guard: only consult plugin.json files inside the
+    // declared plugin cache root.
+    const resolvedInstall = resolve(installPath);
+    const cacheRootWithSep = resolve(pluginCacheRoot) + sep;
+    if (!resolvedInstall.startsWith(cacheRootWithSep)) continue;
+
+    const cachePluginJson = resolve(installPath, ".claude-plugin", "plugin.json");
+    if (!existsSync(cachePluginJson)) continue;
+    let actualVersion = null;
+    try {
+      const pj = JSON.parse(readFileSync(cachePluginJson, "utf-8"));
+      if (pj && typeof pj.version === "string" && pj.version) {
+        actualVersion = pj.version;
+      }
+    } catch {
+      continue;
+    }
+    if (!actualVersion) continue;
+
+    syncedVersion = actualVersion;
+    if (entry.version !== actualVersion) {
+      entry.version = actualVersion;
+      if (!healed.includes("entry-version")) healed.push("entry-version");
+    }
+  }
+
+  // ── HEAL 4: top-level enabledPlugins[key] presence ──
+  // Claude Code's plugin loader checks enabledPlugins. When /ctx-upgrade
+  // emptied it, our plugin was silently disabled. Set it to `true` (the
+  // simplest enabled-flag form) when missing or falsy.
+  if (syncedVersion) {
+    if (!ip.enabledPlugins || typeof ip.enabledPlugins !== "object" || Array.isArray(ip.enabledPlugins)) {
+      ip.enabledPlugins = {};
+    }
+    const current = ip.enabledPlugins[pluginKey];
+    if (current === undefined || current === null || current === false || current === "") {
+      ip.enabledPlugins[pluginKey] = true;
+      healed.push("enabled-plugins");
+    }
+  }
+
+  if (healed.length > 0) {
+    try {
+      writeFileSync(registryPath, JSON.stringify(ip, null, 2) + "\n", "utf-8");
+    } catch (err) {
+      return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+    }
+  }
+
+  return { healed };
+}
+
+/**
+ * Heal `~/.claude/settings.json.enabledPlugins[pluginKey]`.
+ *
+ * v1.0.114's heal targeted `installed_plugins.json.enabledPlugins`, which is
+ * what we control. But Claude Code's plugin loader actually reads the truth
+ * from `settings.json.enabledPlugins`. After every `/ctx-upgrade`, Claude
+ * Code's plugin manager seems to clear the settings.json key (likely on
+ * version-mismatch detection), so the plugin appears disabled even though
+ * `installed_plugins.json` is fully consistent. v1.0.116 closes that gap.
+ *
+ * Respects explicit user opt-out: if the key is `false`, leaves it alone.
+ *
+ * @param {{ settingsPath: string, pluginKey: string }} opts
+ * @returns {HealResult}
+ */
+export function healSettingsEnabledPlugins({ settingsPath, pluginKey }) {
+  if (!settingsPath || !existsSync(settingsPath)) {
+    return { healed: [], skipped: "no-settings" };
+  }
+
+  let raw;
+  try { raw = readFileSync(settingsPath, "utf-8"); }
+  catch (err) { return { healed: [], error: `read-failed: ${(err && err.message) || err}` }; }
+
+  let settings;
+  try { settings = JSON.parse(raw); }
+  catch (err) { return { healed: [], error: `parse-failed: ${(err && err.message) || err}` }; }
+
+  const healed = [];
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object" || Array.isArray(settings.enabledPlugins)) {
+    settings.enabledPlugins = {};
+  }
+  const current = settings.enabledPlugins[pluginKey];
+  if (current === false) {
+    return { healed: [], skipped: "explicit-opt-out" };
+  }
+  if (current !== true) {
+    settings.enabledPlugins[pluginKey] = true;
+    healed.push("enabled-plugins");
+  }
+
+  if (healed.length > 0) {
+    try {
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    } catch (err) {
+      return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+    }
+  }
+
+  return { healed };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Issue #523 (v1.0.119) — Layer 5 heal: plugin.json mcpServers args
+//
+// /ctx-upgrade in v1.0.118 wrote `.mcp.json` with the literal
+// `${CLAUDE_PLUGIN_ROOT}` placeholder (#411) but did NOT touch
+// `.claude-plugin/plugin.json`. On Windows, start.mjs's `normalizeHooksOnStartup`
+// (#378) rewrites that file's `mcpServers["context-mode"].args[0]` to an
+// absolute path. If `pluginRoot` happens to be the upgrade tmpdir at the time
+// of normalization (or an earlier upgrade left absolute paths in place), the
+// resulting plugin.json carries a `<tmpdir>/context-mode-upgrade-<epoch>/start.mjs`
+// path. After Node tmpdir cleanup, MCP fails to spawn with ENOENT and the user
+// has no /ctx-upgrade escape hatch.
+//
+// This heal is the sibling of #411's `.mcp.json` fix:
+//   - Detects tmpdir-prefixed args[0] (epoch-pattern, OS-agnostic)
+//   - Rewrites to literal `${CLAUDE_PLUGIN_ROOT}/start.mjs` placeholder
+//   - Never touches sibling mcpServers entries (only `pluginKey`'s server)
+//   - Refuses to write outside `pluginCacheRoot` (path-traversal guard)
+//
+// Single source of truth shared by:
+//   - `start.mjs` HEAL 5b (every MCP boot)
+//   - `scripts/postinstall.mjs` (every `npm install -g @mxalbert/context-mode`)
+//   - `src/cli.ts` upgrade() (post-bump)
+// ─────────────────────────────────────────────────────────────────────────
+
+const PLACEHOLDER_ARG = "${CLAUDE_PLUGIN_ROOT}/start.mjs";
+
+/**
+ * Heal `<pluginRoot>/.claude-plugin/plugin.json` mcpServers args.
+ *
+ * @param {{
+ *   pluginRoot: string,
+ *   pluginCacheRoot: string,
+ *   pluginKey: string,
+ * }} opts
+ * @returns {HealResult}
+ */
+export function healPluginJsonMcpServers({ pluginRoot, pluginCacheRoot, pluginKey }) {
+  if (!pluginRoot || !pluginCacheRoot || !pluginKey) {
+    return { healed: [], skipped: "missing-args" };
+  }
+
+  // Path-traversal guard: refuse to touch a plugin root that escapes the
+  // declared cache root. Mirrors HEAL 3's guard.
+  const resolvedRoot = resolve(pluginRoot);
+  const cacheRootWithSep = resolve(pluginCacheRoot) + sep;
+  if (!resolvedRoot.startsWith(cacheRootWithSep)) {
+    return { healed: [], skipped: "outside-cache-root" };
+  }
+
+  const pluginJsonPath = resolve(pluginRoot, ".claude-plugin", "plugin.json");
+  if (!existsSync(pluginJsonPath)) {
+    return { healed: [], skipped: "no-plugin-json" };
+  }
+
+  let raw;
+  try { raw = readFileSync(pluginJsonPath, "utf-8"); }
+  catch (err) { return { healed: [], error: `read-failed: ${(err && err.message) || err}` }; }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) { return { healed: [], error: `parse-failed: ${(err && err.message) || err}` }; }
+
+  const servers = parsed && parsed.mcpServers;
+  if (!servers || typeof servers !== "object") {
+    return { healed: [], skipped: "no-mcp-servers" };
+  }
+
+  // Derive our server name from pluginKey ("context-mode@@mxalbert/context-mode" → "context-mode").
+  const ourServerName = parsePluginKey(pluginKey)?.id ?? pluginKey.split("@")[0];
+  const ours = servers[ourServerName];
+  if (!ours || typeof ours !== "object" || !Array.isArray(ours.args)) {
+    return { healed: [], skipped: "no-our-server" };
+  }
+
+  /** @type {string[]} */
+  const healed = [];
+  const before = ours.args;
+  const after = before.map((a) => {
+    if (typeof a !== "string") return a;
+    // Already the placeholder — nothing to heal.
+    if (a === PLACEHOLDER_ARG) return a;
+    // Issue #711: any absolute path ending in start.mjs should be the
+    // placeholder. Catches tmpdir paths (context-mode-upgrade-<digits>)
+    // AND stale versioned cache-dir paths (.../1.0.103/start.mjs) that
+    // normalizeHooksOnStartup baked in during a prior upgrade.
+    if (/[/\\]start\.mjs$/.test(a)) {
+      return PLACEHOLDER_ARG;
+    }
+    return a;
+  });
+  const changed = after.some((v, i) => v !== before[i]);
+  if (changed) {
+    ours.args = after;
+    healed.push("plugin-json-args");
+    try {
+      writeFileSync(pluginJsonPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    } catch (err) {
+      return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+    }
+  }
+
+  return { healed };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Issue #531 (v1.0.122) — Layer 6 heal: .mcp.json mcpServers args
+//
+// Asymmetric-heal sibling of healPluginJsonMcpServers (#523). The regression
+// that broke `.mcp.json` was commit aea633c (PR #253, 2026-04-13): the shipped
+// `.mcp.json` template at repo root used a bare relative `./start.mjs` arg.
+// Claude Code spawns the MCP child with session CWD inherited (not pluginRoot)
+// so fresh npm marketplace installs throw MODULE_NOT_FOUND on every ctx_* tool.
+// v1.0.119 added healPluginJsonMcpServers for the `.claude-plugin/plugin.json`
+// sibling but missed `.mcp.json` — same plugin, same drift class, different
+// file. This module is the asymmetric-heal sibling.
+//
+// Same regex, same placeholder, same traversal guard as #523. Only difference:
+//   - Target: `<pluginRoot>/.mcp.json` (flat shape, no `.claude-plugin/` subdir)
+//   - Structure: `.mcpServers.<pluginName>.args[]`
+//   - Additional drift shape: bare relative `./start.mjs` (the #253 regression)
+//     that healPluginJsonMcpServers's tmpdir-only check would not catch.
+//
+// Single source of truth shared by:
+//   - `start.mjs` HEAL 5b (every MCP boot)
+//   - `scripts/postinstall.mjs` (every `npm install -g @mxalbert/context-mode`)
+//   - `src/cli.ts` upgrade() (post-bump)
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Heal `<pluginRoot>/.mcp.json` mcpServers args.
+ *
+ * Detects two drift shapes:
+ *   1. Bare relative `./start.mjs` (#253 regression — fresh-install class).
+ *   2. Tmpdir-prefixed `<...>/context-mode-upgrade-<digits>/start.mjs`
+ *      (mirrors healPluginJsonMcpServers's #523 tmpdir class).
+ * Both rewrite to the literal `${CLAUDE_PLUGIN_ROOT}/start.mjs` placeholder
+ * Claude Code resolves at load-time.
+ *
+ * @param {{
+ *   pluginRoot: string,
+ *   pluginCacheRoot: string,
+ *   pluginKey: string,
+ * }} opts
+ * @returns {HealResult}
+ */
+export function healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey }) {
+  if (!pluginRoot || !pluginCacheRoot || !pluginKey) {
+    return { healed: [], skipped: "missing-args" };
+  }
+
+  // Path-traversal guard: refuse to touch a plugin root that escapes the
+  // declared cache root. Mirrors healPluginJsonMcpServers + HEAL 3.
+  const resolvedRoot = resolve(pluginRoot);
+  const cacheRootWithSep = resolve(pluginCacheRoot) + sep;
+  if (!resolvedRoot.startsWith(cacheRootWithSep)) {
+    return { healed: [], skipped: "outside-cache-root" };
+  }
+
+  // `.mcp.json` lives at pluginRoot/.mcp.json (flat), NOT under .claude-plugin/.
+  const mcpJsonPath = resolve(pluginRoot, ".mcp.json");
+  if (!existsSync(mcpJsonPath)) {
+    return { healed: [], skipped: "no-mcp-json" };
+  }
+
+  let raw;
+  try { raw = readFileSync(mcpJsonPath, "utf-8"); }
+  catch (err) { return { healed: [], error: `read-failed: ${(err && err.message) || err}` }; }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) { return { healed: [], error: `parse-failed: ${(err && err.message) || err}` }; }
+
+  const servers = parsed && parsed.mcpServers;
+  if (!servers || typeof servers !== "object") {
+    return { healed: [], skipped: "no-mcp-servers" };
+  }
+
+  // Derive our server name from pluginKey ("context-mode@@mxalbert/context-mode" → "context-mode").
+  const ourServerName = parsePluginKey(pluginKey)?.id ?? pluginKey.split("@")[0];
+  const ours = servers[ourServerName];
+  if (!ours || typeof ours !== "object" || !Array.isArray(ours.args)) {
+    return { healed: [], skipped: "no-our-server" };
+  }
+
+  /** @type {string[]} */
+  const healed = [];
+  const before = ours.args;
+  const after = before.map((a) => {
+    if (typeof a !== "string") return a;
+    // Already the placeholder — nothing to heal.
+    if (a === PLACEHOLDER_ARG) return a;
+    // Drift shape #1 (issue #531 / commit aea633c): bare relative `./start.mjs`.
+    if (a === "./start.mjs" || a === "start.mjs") {
+      return PLACEHOLDER_ARG;
+    }
+    // Issue #711: any absolute path ending in start.mjs should be the
+    // placeholder. Catches tmpdir paths AND stale versioned cache-dir
+    // paths (.../1.0.103/start.mjs) from prior upgrades.
+    if (/[/\\]start\.mjs$/.test(a)) {
+      return PLACEHOLDER_ARG;
+    }
+    return a;
+  });
+  const changed = after.some((v, i) => v !== before[i]);
+  if (changed) {
+    ours.args = after;
+    healed.push("mcp-json-args");
+    try {
+      writeFileSync(mcpJsonPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    } catch (err) {
+      return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+    }
+  }
+
+  return { healed };
+}
+
+/**
+ * Heal user-level ~/.claude.json MCP server registrations that point to an
+ * old context-mode version dir in the plugin cache.
+ *
+ * Users who work around the Claude Code plugin MCP tool-exposure bug
+ * (anthropics/claude-code#59310) by running `claude mcp add --scope user`
+ * end up with an absolute path to a specific version dir in ~/.claude.json.
+ * After /ctx-upgrade that path is stale — this heal detects and updates it.
+ *
+ * @param {{
+ *   dotClaudeJsonPath: string,
+ *   pluginCacheParent: string,
+ *   newPluginRoot: string,
+ * }} opts
+ * @returns {HealResult}
+ */
+export function healClaudeJsonMcpArgs({ dotClaudeJsonPath, pluginCacheParent, newPluginRoot }) {
+  if (!dotClaudeJsonPath || !existsSync(dotClaudeJsonPath)) {
+    return { healed: [], skipped: "no-claude-json" };
+  }
+
+  let raw;
+  try { raw = readFileSync(dotClaudeJsonPath, "utf-8"); }
+  catch (err) { return { healed: [], error: `read-failed: ${(err && err.message) || err}` }; }
+
+  let config;
+  try { config = JSON.parse(raw); }
+  catch (err) { return { healed: [], error: `parse-failed: ${(err && err.message) || err}` }; }
+
+  const servers = config && config.mcpServers;
+  if (!servers || typeof servers !== "object") {
+    return { healed: [], skipped: "no-mcp-servers" };
+  }
+
+  const cacheParentFwd = pluginCacheParent.replace(/\\/g, "/");
+  // Post-resolve containment on newArg. ~/.claude.json is locally user-
+  // writable (same trust boundary as installed_plugins.json), and the
+  // `suffix` slice is derived from arg strings inside the existing config.
+  // A crafted arg like
+  //   .../cache/<owner>/<plugin>/1.0.0/../../../evil/start.mjs
+  // slices to suffix="../../../evil/start.mjs", and resolve(newPluginRoot,
+  // suffix) normalizes to an attacker-chosen .mjs path outside the plugin
+  // cache. Writing that path back into ~/.claude.json mutates the mcpServers
+  // args so the next MCP boot spawns from the attacker path. Reject any
+  // suffix that escapes newPluginRoot.
+  const newPluginRootResolved = resolve(newPluginRoot);
+  const newPluginRootWithSep = newPluginRootResolved + sep;
+
+  let mutated = false;
+  for (const srv of Object.values(servers)) {
+    if (!srv || typeof srv !== "object" || !Array.isArray(srv.args)) continue;
+    for (let i = 0; i < srv.args.length; i++) {
+      const arg = srv.args[i];
+      if (typeof arg !== "string") continue;
+      const argFwd = arg.replace(/\\/g, "/");
+      if (!argFwd.startsWith(cacheParentFwd + "/")) continue;
+      const rel = argFwd.slice(cacheParentFwd.length + 1);
+      const slashIdx = rel.indexOf("/");
+      if (slashIdx < 0) continue;
+      const suffix = rel.slice(slashIdx + 1);
+      const newArg = resolve(newPluginRoot, suffix);
+      if (
+        newArg !== newPluginRootResolved &&
+        !(newArg + sep).startsWith(newPluginRootWithSep)
+      ) {
+        continue;
+      }
+      if (newArg !== arg) {
+        srv.args[i] = newArg;
+        mutated = true;
+      }
+    }
+  }
+
+  if (!mutated) return { healed: [] };
+
+  try {
+    writeFileSync(dotClaudeJsonPath, JSON.stringify(config, null, 2), "utf-8");
+  } catch (err) {
+    return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+  }
+
+  return { healed: ["claude-json-mcp-args"] };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Issue #609 — sweepStaleMcpJson: remove cache-baked `.mcp.json` files.
+//
+// Background (per ISSUE-609-VERDICT, ISSUE-604-VERDICT):
+//   cli.ts upgrade() wrote `.mcp.json` into every per-version plugin-cache
+//   dir starting with #411. PR #531 (commit 9261377) removed `.mcp.json`
+//   from `package.json files[]` so the npm tarball no longer ships it,
+//   but the cli-side write persisted. Every `/ctx-upgrade` re-baked a
+//   per-version copy. When Claude Code's native plugin manager auto-update
+//   later copies a previous version's `.mcp.json` forward into a fresh
+//   version dir, the stale start.mjs absolute path goes with it →
+//   MODULE_NOT_FOUND on every MCP boot, and `ctx-doctor` stays green
+//   because nothing validates that path against current pluginRoot.
+//
+// The architectural fix is to STOP writing `.mcp.json` from the cache layer
+// entirely. `.claude-plugin/plugin.json.mcpServers` is the canonical source
+// (refs/platforms/claude-code/src/utils/plugins/mcpPluginIntegration.ts:131-212
+// — Claude Code reads it first). This sweep removes any pre-existing
+// `.mcp.json` from every per-version cache dir so the previous-version-
+// carry vector cannot replay across upgrades.
+//
+// Single source of truth shared by:
+//   - `start.mjs` HEAL 5c (every MCP boot)
+//   - `scripts/postinstall.mjs` (every `npm install -g @mxalbert/context-mode`)
+//   - `src/cli.ts` upgrade() (post-bump)
+//
+// Safety contracts:
+//   - Path-traversal guard: refuses to walk outside `pluginCacheRoot`.
+//   - Best-effort: NEVER throws; missing files / unreadable dirs are
+//     skipped silently and reported in the result.
+//   - Scope: deletes ONLY files named exactly `.mcp.json`; never touches
+//     sibling files in the same dir.
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} SweepResult
+ * @property {string[]} removed - absolute paths of removed `.mcp.json` files
+ * @property {string} [skipped] - reason if no work performed (e.g. "no-cache-root")
+ */
+
+/**
+ * Remove every `.mcp.json` from per-version directories under
+ * `<pluginCacheRoot>/<seg1>/<seg2>/`.
+ *
+ * @param {{ pluginCacheRoot: string, pluginKey: string }} opts
+ *   pluginKey is the "<pluginId>@<npmPackage>" form (e.g. the legacy
+ *   "context-mode@context-mode" or the scoped
+ *   "context-mode@@mxalbert/context-mode").
+ * @returns {SweepResult}
+ */
+export function sweepStaleMcpJson({ pluginCacheRoot, pluginKey }) {
+  /** @type {string[]} */
+  const removed = [];
+
+  if (!pluginCacheRoot || !pluginKey) {
+    return { removed, skipped: "missing-args" };
+  }
+
+  const resolvedCacheRoot = resolve(pluginCacheRoot);
+  if (!existsSync(resolvedCacheRoot)) {
+    return { removed, skipped: "no-cache-root" };
+  }
+
+  // pluginKey shape: "<pluginId>@<npmPackage>" where the package may be
+  // scoped ("@scope/name"), so the key may contain two '@' characters.
+  // Split at the FIRST '@' only — a plain split("@") would turn the scoped
+  // key into an empty middle segment and abort the sweep.
+  const keyParts = parsePluginKey(pluginKey);
+  if (!keyParts) {
+    return { removed, skipped: "bad-plugin-key" };
+  }
+  const ownerSegment = keyParts.id;
+  const pluginSegment = keyParts.pkg;
+  if (!ownerSegment || !pluginSegment) {
+    return { removed, skipped: "bad-plugin-key" };
+  }
+
+  // Path-traversal guard: refuse to walk outside the declared cache root,
+  // even if pluginKey contains `..` segments. Per Mert's standing Windows
+  // safety rule, resolve normalizes both `/` and `\` so the guard fires
+  // on either separator.
+  const ownerDir = resolve(resolvedCacheRoot, ownerSegment, pluginSegment);
+  const cacheRootWithSep = resolvedCacheRoot + sep;
+  if (!ownerDir.startsWith(cacheRootWithSep)) {
+    return { removed, skipped: "outside-cache-root" };
+  }
+
+  if (!existsSync(ownerDir)) {
+    return { removed, skipped: "no-plugin-dir" };
+  }
+
+  /** @type {string[]} */
+  let versionEntries = [];
+  try {
+    versionEntries = readdirSync(ownerDir);
+  } catch {
+    return { removed, skipped: "readdir-failed" };
+  }
+
+  for (const versionEntry of versionEntries) {
+    const versionDir = resolve(ownerDir, versionEntry);
+    // Per-version guard: only enter directories whose resolved path stays
+    // under the owner dir. Belt-and-braces against weird FS entries.
+    if (!versionDir.startsWith(ownerDir + sep)) continue;
+    try {
+      const stat = statSync(versionDir);
+      if (!stat.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const mcpJsonPath = resolve(versionDir, ".mcp.json");
+    if (!existsSync(mcpJsonPath)) continue;
+    try {
+      unlinkSync(mcpJsonPath);
+      removed.push(mcpJsonPath);
+    } catch {
+      // best-effort: file may have been removed by a concurrent process
+      // between existsSync and unlinkSync. Silent skip.
+    }
+  }
+
+  return { removed };
+}