@sdsrs/code-graph 0.103.0 → 0.104.1

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.103.0",
+  "version": "0.104.1",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/scripts/auto-update.js

@@ -9,7 +9,7 @@ const path = require('path');
 const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
 const { claudeHome } = require('./claude-config');
-const { clearCache: clearBinaryCache, globalNodeModulesCandidates, PLATFORM_PKG, detectLibc } = require('./find-binary');
+const { clearCache: clearBinaryCache, globalNodeModulesCandidates, nvmNodeModulesDirs, PLATFORM_PKG, detectLibc } = require('./find-binary');
 const { readBinaryVersion, compareVersions, isDevMode } = require('./version-utils');
 const { cgTmpDir } = require('./tmp-dir');
 const { npmSpawnOpts } = require('./npm-exec');
@@ -597,6 +597,31 @@ function staleGlobalPkgs(latestVersion, roots = null) {
   return out;
 }
 
+/**
+ * Global installs of ours stranded under a NON-active node version. nvm keeps a
+ * separate global prefix per node; switching the default node leaves the old
+ * prefix's `@sdsrs/code-graph` behind — invisible to selfHealGlobalPkgs (which
+ * only sees, and can only `npm install -g` into, the ACTIVE node's prefix) yet
+ * still able to seed stale settings.json hooks / shadow PATH shims (the
+ * v24.11.1@0.46.0 relic firing beside the active install — RCA 2026-07-24).
+ * Detection-only: returns each relic's package + version + node prefix so doctor
+ * can surface it with manual remediation. `dirs`/`activeDir` injectable for tests.
+ */
+function inactiveNodeGlobalRelics({ dirs = null, activeDir = null } = {}) {
+  const active = path.resolve(activeDir
+    || path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules'));
+  const roots = dirs || nvmNodeModulesDirs();
+  const out = [];
+  for (const dir of roots) {
+    if (path.resolve(dir) === active) continue; // active prefix → not a relic
+    for (const name of [SHELL_PKG, PLATFORM_PKG]) {
+      const version = globalPkgVersion(name, [dir]);
+      if (version) out.push({ name, version, nodeModulesDir: dir });
+    }
+  }
+  return out;
+}
+
 /** One targeted `npm install -g` for the given specs. Resolves true on exit 0. */
 function npmInstallGlobal(specs) {
   return new Promise((resolve) => {
@@ -647,6 +672,21 @@ async function selfHealGlobalPkgs(latest, state, {
   };
 }
 
+// Whether a THROTTLED checkForUpdate should still attempt the global-npm
+// self-heal. The post-fetch heal below only runs on the non-throttle path, but
+// the ONLY context that can SEE a user's nvm/global prefix is a CLI run under
+// that node (globalNodeModulesCandidates is execPath-derived) — and such a run,
+// once binary+shell are current, short-circuits at the throttle early-return and
+// never reaches the heal. That gap stranded a global `code-graph-mcp` shim at
+// 0.101.0 while the binary reached 0.103.0 (RCA 2026-07-24). Cheap local
+// package.json read (readStale) gates the slow, lock-guarded npm path. Split out
+// so the decision is unit-testable without the full checkForUpdate harness.
+function shouldHealGlobalsOnThrottle(state, { readStale = staleGlobalPkgs } = {}) {
+  if (!state || !state.latestVersion) return false;
+  if (process.env.CODE_GRAPH_INSTALL_LOCK_HELD === '1') return false; // parent launcher holds it
+  return readStale(state.latestVersion).length > 0;
+}
+
 async function checkForUpdate({ installMissing = false, force = false } = {}) {
   let installLock = null;
   try {
@@ -671,6 +711,16 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
       if (state.installedVersion !== installedVersion) {
         saveState({ ...state, installedVersion });
       }
+      // Global-npm shell/platform self-heal reaches the throttle window too (see
+      // shouldHealGlobalsOnThrottle). Cheap local check first; only the actually-
+      // stale case takes the slow, lock-guarded npm path.
+      if (shouldHealGlobalsOnThrottle(state)) {
+        installLock = acquireLock(path.join(CACHE_DIR, 'install.lock'));
+        if (installLock) {
+          const globalHeal = await selfHealGlobalPkgs({ version: state.latestVersion }, state);
+          saveState({ ...readState(), ...globalHeal });
+        }
+      }
       if (state.updateAvailable && state.latestVersion
           && compareVersions(state.latestVersion, installedVersion) > 0) {
         return { updateAvailable: true, from: installedVersion, to: state.latestVersion };
@@ -776,6 +826,7 @@ module.exports = {
   getPlatformAssetName,
   selfHealStaleBinary,
   selfHealGlobalPkgs, staleGlobalPkgs, globalPkgVersion, npmInstallGlobal,
+  shouldHealGlobalsOnThrottle, inactiveNodeGlobalRelics,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
 };
 

package/claude-plugin/scripts/doctor.js

@@ -285,11 +285,29 @@ function runDiagnostics() {
   //    `lifecycle.js uninstall` removes them; without it they are treated as
   //    user-installed and a plugin uninstall leaves them on PATH.
   try {
-    const { globalPkgVersion } = require('./auto-update');
+    const { globalPkgVersion, inactiveNodeGlobalRelics } = require('./auto-update');
     const { PLATFORM_PKG } = require('./find-binary');
     const found = [SHELL_PKG, PLATFORM_PKG]
       .map((name) => ({ name, version: globalPkgVersion(name) }))
       .filter((p) => p.version);
+
+    // Relics stranded under a NON-active node version (nvm keeps a per-node
+    // global prefix). selfHealGlobalPkgs / the check above only see the active
+    // node, so these drift unseen for months and can seed stale settings.json
+    // hooks — the v24.11.1@0.46.0 relic behind the RCA. Report-only: `npm i -g`
+    // can't target another node's prefix, so hand the user the exact remediation.
+    const relics = inactiveNodeGlobalRelics();
+    if (relics.length) {
+      const home = require('os').homedir();
+      results.push({
+        name: 'Global npm relics',
+        status: 'warn',
+        detail: relics.map((r) => `${r.name}@${r.version} (${r.nodeModulesDir.replace(home, '~')})`).join('; ')
+          + ' — installed under a non-active node version; auto-heal cannot reach another node\'s prefix. '
+          + 'Remove each via `nvm use <that node> && npm rm -g <pkg>`, or uninstall the unused node (`nvm uninstall <ver>`).',
+      });
+    }
+
     if (found.length) {
       const marker = !!readJson(GLOBAL_INSTALL_MARKER);
       // Heal-exhausted is otherwise invisible: selfHealGlobalPkgs stops after

package/claude-plugin/scripts/find-binary.js

@@ -119,6 +119,22 @@ function globalNodeModulesCandidates() {
   return [...new Set(out)];
 }
 
+// Every nvm-managed node version's global node_modules dir (`~/.nvm/versions/
+// node/*/lib/node_modules`). nvm keeps a SEPARATE global prefix per node
+// version; switching the default node strands the previous version's globals —
+// a global `@sdsrs/code-graph` there is invisible to globalNodeModulesCandidates
+// (execPath-derived → only the ACTIVE node) yet still shadows PATH shims / seeds
+// stale settings.json hooks (the v24.11.1@0.46.0 relic — RCA 2026-07-24). Used
+// for detection/reporting only; `npm install -g` cannot target another node's
+// prefix. `base` is injectable for hermetic tests (never the real ~/.nvm).
+function nvmNodeModulesDirs(base = path.join(os.homedir(), '.nvm', 'versions', 'node')) {
+  let entries;
+  try { entries = fs.readdirSync(base); } catch { return []; }
+  return entries
+    .map((v) => path.join(base, v, 'lib', 'node_modules'))
+    .filter((d) => { try { return fs.statSync(d).isDirectory(); } catch { return false; } });
+}
+
 function isNativeBinary(candidate) {
   if (!candidate) return false;
   try {
@@ -367,7 +383,7 @@ function clearCache() {
 
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
-  globalNodeModulesCandidates, findPlatformBinary, platformBinaryCandidates, createVersionGate,
+  globalNodeModulesCandidates, nvmNodeModulesDirs, findPlatformBinary, platformBinaryCandidates, createVersionGate,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,

package/claude-plugin/scripts/lifecycle.js

@@ -375,13 +375,17 @@ function isOurHookEntry(entry) {
   if (!entry || !entry.hooks) return false;
   // Primary: match by description (immune to path pollution).
   if (entry.description && OUR_DESCRIPTIONS.includes(entry.description)) return true;
-  // Fallback: script name + MARKETPLACE_NAME in path. v0.32.1: tightened from
-  // bare 'code-graph' (which would claim a user's own ~/code-graph/foo.js) to
-  // the actual marketplace dir name 'code-graph-mcp' — Requirement 3 says
-  // foreign-entry strip is unacceptable, so be conservative.
+  // Fallback: script basename + a delivery-surface marker in the path. TWO
+  // surfaces ship these scripts: the marketplace plugin-cache (dir
+  // 'code-graph-mcp') AND the global npm package (dir '@sdsrs/code-graph' — note
+  // NO '-mcp' suffix). v0.32.1 tightened from bare 'code-graph' (which would
+  // claim a user's own ~/code-graph/foo.js) to MARKETPLACE_NAME, but that alone
+  // missed the npm-global surface, so `npm i -g`-delivered hooks were never
+  // evicted and orphan-accumulated across node/version switches (RCA 2026-07-24).
+  // Both markers are specific enough not to claim a user's unrelated file.
   return entry.hooks.some(h =>
     h.command && OUR_HOOK_SCRIPTS.some(s => h.command.includes(s)) &&
-    h.command.includes(MARKETPLACE_NAME)
+    (h.command.includes(MARKETPLACE_NAME) || h.command.includes(SHELL_PKG))
   );
 }
 
@@ -448,6 +452,23 @@ function buildSettingsHookEntries() {
 // re-write it to settings.json.
 function registerHooksToSettings(settings) {
   settings.hooks = settings.hooks || {};
+
+  // Idempotent across delivery surfaces: if every desired (event,matcher) is
+  // already present exactly once, pointing at a current, existing script
+  // (plugin-cache OR global-npm), do nothing. Stops the settings.json ping-pong
+  // where the cache session-init and the npm-global CLI doctor each rewrote the
+  // other's valid entry every run (RCA 2026-07-24). Any missing/stale/dead entry
+  // — or a duplicate ( oursCount > expected) — still triggers evict+rewrite.
+  const survey = surveyHookCoverage(settings);
+  let oursCount = 0;
+  for (const entries of Object.values(settings.hooks)) {
+    if (Array.isArray(entries)) oursCount += entries.filter(isOurHookEntry).length;
+  }
+  if (survey.missing.length === 0 && survey.stale.length === 0
+      && oursCount === survey.expected.length) {
+    return false;
+  }
+
   const before = JSON.stringify(settings.hooks);
 
   // Pass 1: evict our entries across every event.
@@ -467,6 +488,22 @@ function registerHooksToSettings(settings) {
   return before !== JSON.stringify(settings.hooks);
 }
 
+// Extract the .js script path a hook command invokes — bare (`node "…"`) or
+// existence-guarded (`if [ -f "…" ]; then node "…"; fi`).
+function hookCmdScript(cmd) {
+  const m = (cmd || '').match(/node "([^"]+\.js)"/) || (cmd || '').match(/"([^"]+\.js)"/);
+  return m ? m[1] : null;
+}
+
+// Version encoded in a plugin-cache path (.../code-graph-mcp/code-graph-mcp/<ver>/scripts/…).
+// Null for in-place installs (global npm), whose path never carries a version
+// dir — npm overwrites the same path on upgrade, so such a path never goes
+// version-stale (only dead-path-stale, caught separately by fs.existsSync).
+function cacheDirVersion(scriptPath) {
+  const m = (scriptPath || '').match(/\/code-graph-mcp\/code-graph-mcp\/(\d+\.\d+\.\d+[^/]*)\//);
+  return m ? m[1] : null;
+}
+
 // Inventory of (event, matcher) tuples we expect to find in settings.json after
 // install. Consumed by doctor (report + fix) and session-init (self-heal):
 // `missing` = entry absent; `stale` = present but the registered command no
@@ -504,10 +541,34 @@ function surveyHookCoverage(settings) {
     }
   }
 
+  const { compareVersions } = require('./version-utils');
   const missing = expected.filter(k => !present.has(k));
-  const stale = expected.filter(k =>
-    present.has(k) && desiredCmd[k] && presentCmd[k] && presentCmd[k] !== desiredCmd[k]
-  );
+  // Version/surface-tolerant staleness. Was an exact command-string compare,
+  // which made two registration authorities (plugin-cache session-init vs
+  // global-npm CLI doctor — different absolute paths) each flag the other's
+  // VALID CURRENT entry stale and rewrite it → settings.json ping-pong on every
+  // alternating run (RCA 2026-07-24). An entry is stale only when its script is
+  // a dead path OR resolves to an OLDER plugin-cache version dir than we'd write
+  // now. A present entry on a different but valid, current surface (npm in-place
+  // install: file exists, no version in path) is NOT stale.
+  const stale = expected.filter(k => {
+    if (!present.has(k) || !presentCmd[k]) return false;
+    const pScript = hookCmdScript(presentCmd[k]);
+    if (!pScript) return false;
+    if (!fs.existsSync(pScript)) return true;             // dead path
+    const pv = cacheDirVersion(pScript);
+    if (pv) {
+      // Pinned to a plugin-cache version dir: stale iff older than us. Compare
+      // against the desired cache dir when we're the cache authority; the
+      // global-npm/dev authority's desired path carries no version dir, so
+      // fall back to our own plugin version — an old-version cache pin must be
+      // healed from EITHER surface, not only when the desired path happens to
+      // be cache-shaped. Newer-than-us stays (downgrade-war guard, §1.11).
+      const dv = cacheDirVersion(hookCmdScript(desiredCmd[k])) || getPluginVersion();
+      return compareVersions(pv, dv) < 0;
+    }
+    return false;                                         // in-place/current surface
+  });
   return { expected, present: [...present], missing, stale };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.103.0",
+  "version": "0.104.1",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -29,17 +29,17 @@
   ],
   "scripts": {
     "build": "cargo build --release --no-default-features && node scripts/copy-binary.js",
-    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit || true",
+    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath scripts/githooks || true",
     "preuninstall": "node claude-plugin/scripts/lifecycle.js uninstall || true"
   },
   "engines": {
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.103.0",
-    "@sdsrs/code-graph-linux-arm64": "0.103.0",
-    "@sdsrs/code-graph-darwin-x64": "0.103.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.103.0",
-    "@sdsrs/code-graph-win32-x64": "0.103.0"
+    "@sdsrs/code-graph-linux-x64": "0.104.1",
+    "@sdsrs/code-graph-linux-arm64": "0.104.1",
+    "@sdsrs/code-graph-darwin-x64": "0.104.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.104.1",
+    "@sdsrs/code-graph-win32-x64": "0.104.1"
   }
 }