@sdsrs/code-graph 0.101.0 → 0.103.0

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

@@ -4,7 +4,8 @@ const { execFileSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { readBinaryVersion } = require('./version-utils');
+const { readBinaryVersion, compareVersions } = require('./version-utils');
+const { npmSpawnOpts } = require('./npm-exec');
 
 const PLATFORM = os.platform();
 const ARCH = os.arch();
@@ -51,29 +52,22 @@ function unsupportedPlatformHint(platform = PLATFORM, arch = ARCH, libc = null)
   return null;
 }
 
-/** Read the npm pkg version from this script's package.json (claude-plugin/../package.json). */
+/**
+ * Version that arms the gates below. Two shipped layouts resolve differently:
+ * npm install has `<pkg>/package.json` two levels up; the marketplace/plugin-cache
+ * copy ships ONLY the claude-plugin subtree, so `../.claude-plugin/plugin.json`
+ * is the sole version source there. Without the fallback, every marketplace
+ * install ran with a null version and each gate degraded to
+ * first-candidate-wins (the pre-d578d99 relic-shadowing behavior).
+ */
 function getPackageVersion() {
-  try { return require('../../package.json').version; }
+  try { return require('../../package.json').version; } catch { /* not npm layout */ }
+  try { return require('../.claude-plugin/plugin.json').version; }
   catch { return null; }
 }
 
-/**
- * Compare semver-ish "M.m.p" strings; returns -1, 0, or 1. Non-numeric parts → 0.
- * Assumes plain numeric releases (the project's tag scheme); a pre-release tag
- * (e.g. "1.2.3-rc1") is NOT semver-ordered — `parseInt("3-rc1", 10)` keeps the
- * leading 3 and drops the suffix, so "1.2.3-rc1" compares EQUAL to "1.2.3".
- * Revisit only if releases adopt pre-release tags.
- */
-function compareVersions(a, b) {
-  const pa = String(a).split('.').map(s => parseInt(s, 10));
-  const pb = String(b).split('.').map(s => parseInt(s, 10));
-  for (let i = 0; i < 3; i++) {
-    const x = Number.isFinite(pa[i]) ? pa[i] : 0;
-    const y = Number.isFinite(pb[i]) ? pb[i] : 0;
-    if (x !== y) return x < y ? -1 : 1;
-  }
-  return 0;
-}
+// compareVersions lives in version-utils.js (single canonical implementation,
+// pre-release-aware); re-exported below for existing consumers.
 
 /**
  * Candidate paths for npm global `node_modules`.
@@ -87,7 +81,19 @@ function globalNodeModulesCandidates() {
   const out = [];
   const nodeBinDir = path.dirname(process.execPath);
 
-  // 1. Derive from process.execPath. Works for nvm + standard Unix prefixes
+  // 1. NPM_CONFIG_PREFIX env override (users with `~/.npm-global` etc.) FIRST:
+  //    when set, `npm install -g` actually installs THERE, so it is the most
+  //    authoritative location — matching npm's own prefix-resolution order.
+  //    (It also used to rank below the execPath derivation, which let a stale
+  //    relic in the nvm prefix shadow the user's real prefix.)
+  const envPrefix = process.env.NPM_CONFIG_PREFIX || process.env.npm_config_prefix;
+  if (envPrefix) {
+    out.push(PLATFORM === 'win32'
+      ? path.join(envPrefix, 'node_modules')
+      : path.join(envPrefix, 'lib', 'node_modules'));
+  }
+
+  // 2. Derive from process.execPath. Works for nvm + standard Unix prefixes
   //    (`<prefix>/bin/node` → globals at `<prefix>/lib/node_modules`); on
   //    Windows globals sit next to `node.exe`.
   if (PLATFORM === 'win32') {
@@ -96,25 +102,17 @@ function globalNodeModulesCandidates() {
     out.push(path.resolve(nodeBinDir, '..', 'lib', 'node_modules'));
   }
 
-  // 2. NPM_CONFIG_PREFIX env override (set by users using `~/.npm-global` etc.)
-  const envPrefix = process.env.NPM_CONFIG_PREFIX || process.env.npm_config_prefix;
-  if (envPrefix) {
-    out.push(PLATFORM === 'win32'
-      ? path.join(envPrefix, 'node_modules')
-      : path.join(envPrefix, 'lib', 'node_modules'));
-  }
-
   // 3. Common no-sudo user prefix
   out.push(path.join(os.homedir(), '.npm-global', 'lib', 'node_modules'));
 
   // 4. Last resort: ask npm directly. Slow (~50-200ms) but most accurate when
   //    user has a non-standard prefix. Cached at the disk-cache layer above.
   try {
-    const root = execFileSync('npm', ['root', '-g'], {
+    const root = execFileSync('npm', ['root', '-g'], npmSpawnOpts({
       timeout: 2000,
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
-    }).trim();
+    })).trim();
     if (root) out.push(root);
   } catch { /* npm not on PATH or timed out */ }
 
@@ -160,6 +158,10 @@ function isCachedBinaryFresh(cachedPath, pkgVersion) {
  *   auto-update cache → platform npm pkg → bundled (bin/) →
  *   cargo install → PATH → npx cache
  *
+ * Every tier after dev-mode is version-gated (createVersionGate): the first
+ * candidate at/above the pkg version wins; when NONE is current, the newest
+ * stale candidate is returned rather than null.
+ *
  * Returns the absolute path or null if not found.
  */
 function findBinary() {
@@ -200,21 +202,67 @@ function isDevRepo(rootDir) {
  * nvm/standard setups), so a working `npm install -g @sdsrs/code-graph` can
  * still be invisible without the fallback.
  */
-function findPlatformBinary() {
+// Truncation gate for the npm platform-package tier ONLY: an interrupted npm
+// install can leave a partial binary with the right name, and unlike the
+// GitHub-download path (size + sha256 sidecar + version-exec before promote)
+// nothing else checks this tier. Real release binaries are ~40MB; 1MB matches
+// promoteVerifiedBinary's floor. Deliberately NOT inside isNativeBinary —
+// dev builds, cargo installs, and test fixtures go through other tiers.
+function isPlausibleReleaseBinary(candidate) {
+  try { return fs.statSync(candidate).size > 1_000_000; } catch { return false; }
+}
+
+function platformBinaryCandidates() {
+  const out = [];
   // Fast path: standard module resolution.
   try {
     const pkgPath = require.resolve(`${PLATFORM_PKG}/package.json`);
     const bin = path.join(path.dirname(pkgPath), BINARY_NAME);
-    if (isNativeBinary(bin)) return bin;
+    if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
   } catch { /* not in node_modules walk-up */ }
 
   // Slow path: explicit global node_modules probe.
   for (const globalRoot of globalNodeModulesCandidates()) {
     const bin = path.join(globalRoot, '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`, BINARY_NAME);
-    if (isNativeBinary(bin)) return bin;
+    if (isNativeBinary(bin) && isPlausibleReleaseBinary(bin)) out.push(bin);
   }
 
-  return null;
+  return out;
+}
+
+function findPlatformBinary() {
+  return platformBinaryCandidates()[0] || null;
+}
+
+/**
+ * Version gate for discovery candidates. `consider(bin)` accepts a candidate
+ * outright when it is current (version >= pkgVersion) or unverifiable (no pkg
+ * version / binary won't report one — don't refuse the only path we may have);
+ * a candidate OLDER than the package is recorded as a stale fallback instead of
+ * being returned, and `best()` yields the NEWEST of those.
+ *
+ * Why: candidates below the auto-update cache had no version check at all, so
+ * a years-old relic (a 0.16.6 `npm install -g` leftover in the nvm global
+ * node_modules) was returned VERBATIM during every post-release window in
+ * which the cache binary was one version behind — an ancient server on a
+ * modern schema, presenting as the MCP 30s connect-timeout. Newest-stale
+ * beats null because every consumer (statusline, hooks, CLI) degrades more
+ * gracefully on a slightly-old binary than on "offline", and the stale-binary
+ * self-heal in auto-update.js re-downloads shortly anyway.
+ */
+function createVersionGate(pkgVersion, { readVersion = readBinaryVersion } = {}) {
+  let bestStale = null;
+  return {
+    consider(bin) {
+      if (!isNativeBinary(bin)) return null;
+      if (!pkgVersion) return bin;
+      const ver = readVersion(bin);
+      if (!ver || compareVersions(ver, pkgVersion) >= 0) return bin;
+      if (!bestStale || compareVersions(ver, bestStale.ver) > 0) bestStale = { bin, ver };
+      return null;
+    },
+    best() { return bestStale ? bestStale.bin : null; },
+  };
 }
 
 function findBinaryUncached() {
@@ -240,24 +288,31 @@ function findBinaryUncached() {
     }
   }
 
+  // Every tier below runs through the version gate: a candidate at or above
+  // the npm pkg version is returned on the spot (tier order = priority, same
+  // as before); an OLDER candidate is only remembered as a fallback. Without
+  // the gate, tiers below the auto-update cache accepted any binary verbatim —
+  // so when the cache was one release behind (every post-release window), an
+  // ancient global-npm relic could shadow it (the 0.16.6-serves-a-modern-DB
+  // incident behind the MCP 30s connect-timeout).
+  const gate = createVersionGate(getPackageVersion());
+
   // --- Auto-update cache (binary downloaded directly from GitHub release) ---
   // Cache wins when its version >= the npm pkg version. After `npm update`
   // refreshes the platform-pkg, an older auto-update cache binary must NOT
   // shadow the freshly-installed one; this version check prevents the
   // upgrade-race where users keep running stale binary until auto-update fires.
   const autoUpdateBin = path.join(os.homedir(), '.cache', 'code-graph', 'bin', BINARY_NAME);
-  if (isNativeBinary(autoUpdateBin)) {
-    const cacheVer = readBinaryVersion(autoUpdateBin);
-    const pkgVer = getPackageVersion();
-    if (!pkgVer || !cacheVer || compareVersions(cacheVer, pkgVer) >= 0) {
-      return autoUpdateBin;
-    }
-    // Cache is older than npm pkg — fall through to platform-pkg.
+  {
+    const hit = gate.consider(autoUpdateBin);
+    if (hit) return hit;
   }
 
   // --- Platform-specific npm package (@sdsrs/code-graph-{os}-{arch}) ---
-  const platformBin = findPlatformBinary();
-  if (platformBin) return platformBin;
+  for (const platformBin of platformBinaryCandidates()) {
+    const hit = gate.consider(platformBin);
+    if (hit) return hit;
+  }
 
   // --- Bundled binary (in same directory as cli.js or plugin scripts) ---
   // Check bin/ directory of the npm package
@@ -267,20 +322,23 @@ function findBinaryUncached() {
   }
   binDirs.add(path.resolve(__dirname, '..', '..', 'bin'));
   for (const dir of binDirs) {
-    const bundled = path.join(dir, BINARY_NAME);
-    if (isNativeBinary(bundled)) return bundled;
+    const hit = gate.consider(path.join(dir, BINARY_NAME));
+    if (hit) return hit;
   }
 
   // --- Cargo install (~/.cargo/bin) ---
-  const cargoBin = path.join(os.homedir(), '.cargo', 'bin', BINARY_NAME);
-  if (isNativeBinary(cargoBin)) return cargoBin;
+  {
+    const hit = gate.consider(path.join(os.homedir(), '.cargo', 'bin', BINARY_NAME));
+    if (hit) return hit;
+  }
 
   // --- PATH lookup (last resort for intentionally installed binaries) ---
   try {
     const which = PLATFORM === 'win32' ? 'where' : 'which';
     const found = execFileSync(which, [BINARY_NAME], { stdio: ['pipe', 'pipe', 'pipe'] })
       .toString().trim().split('\n')[0];
-    if (isNativeBinary(found)) return found;
+    const hit = gate.consider(found);
+    if (hit) return hit;
   } catch { /* not in PATH */ }
 
   // --- npx cache (very last resort — may be outdated) ---
@@ -288,12 +346,15 @@ function findBinaryUncached() {
   try {
     for (const entry of fs.readdirSync(npxDir)) {
       const platDir = path.join(npxDir, entry, 'node_modules', '@sdsrs', `code-graph-${PLATFORM}-${ARCH}`);
-      const platBin = path.join(platDir, BINARY_NAME);
-      if (isNativeBinary(platBin)) return platBin;
+      const hit = gate.consider(path.join(platDir, BINARY_NAME));
+      if (hit) return hit;
     }
   } catch { /* no npx cache */ }
 
-  return null;
+  // Nothing current anywhere: the newest stale candidate (if any) beats null —
+  // consumers degrade better on a slightly-old binary than on "offline", and
+  // auto-update's stale-binary self-heal replaces it shortly.
+  return gate.best();
 }
 
 /**
@@ -306,7 +367,7 @@ function clearCache() {
 
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
-  globalNodeModulesCandidates, findPlatformBinary,
+  globalNodeModulesCandidates, findPlatformBinary, platformBinaryCandidates, createVersionGate,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,

package/claude-plugin/scripts/install-lock.js

@@ -0,0 +1,48 @@
+'use strict';
+// Inter-process install lock. N concurrently-opened sessions each spawn a
+// launcher / auto-update process; without a lock they ran parallel
+// `npm install -g` against one global prefix (npm's staging dir is not
+// concurrency-safe → EEXIST/ENOTEMPTY tree corruption) and clobbered each
+// other's update-state counters. O_EXCL create is the atomic primitive; a lock
+// whose owner pid is dead or whose file is older than staleMs is reclaimed
+// (crashed installer must not wedge every future session).
+const fs = require('fs');
+const path = require('path');
+
+const STALE_MS = 10 * 60 * 1000; // > the longest install step (npm 180s heal timeout)
+
+function lockIsStale(lockPath, staleMs) {
+  try {
+    const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+    if (age > staleMs) return true;
+    const info = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (!info || !Number.isInteger(info.pid)) return false; // unreadable → trust age only
+    try { process.kill(info.pid, 0); return false; }        // owner alive
+    catch (e) { return e.code !== 'EPERM'; }                // EPERM = alive, not ours
+  } catch {
+    return false; // raced away / unreadable — treat as held; age check re-runs next attempt
+  }
+}
+
+/**
+ * Try to take the lock. Returns `{ release() }` on success, null when another
+ * live process holds it. Never throws, never blocks.
+ */
+function acquireLock(lockPath, { staleMs = STALE_MS } = {}) {
+  try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch { return null; }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+      fs.closeSync(fd);
+      return { release: () => { try { fs.unlinkSync(lockPath); } catch { /* ok */ } } };
+    } catch (e) {
+      if (!e || e.code !== 'EEXIST') return null;
+      if (!lockIsStale(lockPath, staleMs)) return null;
+      try { fs.unlinkSync(lockPath); } catch { /* another reclaimer won — retry loop */ }
+    }
+  }
+  return null;
+}
+
+module.exports = { acquireLock, STALE_MS };

package/claude-plugin/scripts/launcher-install.js

@@ -0,0 +1,146 @@
+'use strict';
+/**
+ * Background binary installer for mcp-launcher.js.
+ *
+ * Replaces the launcher's old SYNCHRONOUS missing-binary chain — `npm install
+ * -g` (60s timeout) then the GitHub-release fallback (90s) — which ran BEFORE
+ * any MCP JSON-RPC was answered. Claude Code's connect timeout is 30s, so a
+ * cold install always presented as "connection timed out after 30000ms" and
+ * the tools only appeared on a later reconnect. The launcher now answers the
+ * handshake from an upgradeable 0-tool stub immediately and runs this chain in
+ * the background; `onInstalled` fires as soon as a step yields a resolvable
+ * binary so the caller can hand the live connection over to it.
+ *
+ * Steps (same order + timeouts as the old sync chain):
+ *   1. npm install -g @sdsrs/code-graph@<version>   — the normal package path
+ *   2. auto-update.js --silent --install-missing    — direct GitHub release
+ *      download, for when npm succeeds but the platform optionalDependency
+ *      fails silently (OS-mismatch tolerance, flaky registry — issue #12)
+ *
+ * `spawnFn` is injectable so the chain is unit-testable without touching npm
+ * or the network (launcher-install.test.js).
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const { NPM_NEEDS_SHELL } = require('./npm-exec');
+const { acquireLock } = require('./install-lock');
+
+const NPM_TIMEOUT_MS = 60000;
+const GITHUB_TIMEOUT_MS = 90000;
+
+/**
+ * Run one install step, capture its stderr, and invoke `cb` exactly once when
+ * the step is over — whether it exited, timed out (spawn's `timeout` option
+ * SIGTERMs and still emits 'exit'), or failed to start at all ('error' without
+ * 'exit', e.g. npm missing from PATH). Never throws: a failed step just means
+ * the chain moves on. `cb` receives the step's exit code (null when it never
+ * exited cleanly); `spawnOpts` merges extras into the spawn options (shell for
+ * npm on Windows, env for the auto-update child).
+ */
+function runStep(cmd, args, timeoutMs, prefix, spawnFn, cb, spawnOpts = {}) {
+  let settled = false;
+  let exitCode = null;
+  const done = () => {
+    if (settled) return;
+    settled = true;
+    cb(exitCode);
+  };
+
+  let child;
+  try {
+    child = spawnFn(cmd, args, {
+      timeout: timeoutMs,
+      stdio: ['ignore', 'ignore', 'pipe'],
+      ...spawnOpts,
+    });
+  } catch (e) {
+    process.stderr.write(`[code-graph] install step ${cmd} failed to start: ${e.message}\n`);
+    done();
+    return;
+  }
+
+  let stderr = '';
+  if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString(); });
+  child.on('error', (err) => {
+    process.stderr.write(`[code-graph] install step ${cmd} failed to start: ${err.message}\n`);
+    done();
+  });
+  child.on('exit', (code) => {
+    exitCode = code;
+    if (stderr.trim()) {
+      process.stderr.write(stderr.trim().split('\n').map((l) => `${prefix} ${l}\n`).join(''));
+    }
+    done();
+  });
+}
+
+/**
+ * Kick off the background install chain. Fire-and-forget: exactly one of
+ * `onInstalled` / `onFailed` is eventually called — EXCEPT when `lockPath` is
+ * given and another live session already holds the lock, in which case the
+ * chain is skipped entirely (neither callback fires; that session's install
+ * lands and our stub's poller picks the binary up).
+ *
+ * - findBinary / clearCache: injected from find-binary.js (clear the disk
+ *   cache before each re-resolve so a pre-install negative result can't mask a
+ *   freshly landed binary).
+ * - onInstalled: a step produced a resolvable binary — attempt the stub→real
+ *   handover now instead of waiting for the stub's next 4s poll.
+ * - onFailed: both steps ran and no binary resolved — surface manual hints.
+ * - recordGlobalInstall: called when the npm step itself exited 0 AND yielded a
+ *   binary — i.e. the plugin (not the user) introduced the global packages.
+ *   lifecycle.js uninstall uses that marker to know it owns their removal.
+ * - lockPath: opt-in inter-process lock — N cold sessions otherwise run
+ *   parallel `npm install -g` against one global prefix (npm staging is not
+ *   concurrency-safe).
+ */
+function installBinaryInBackground({
+  version,
+  findBinary,
+  clearCache,
+  onInstalled,
+  onFailed,
+  spawnFn = spawn,
+  autoUpdateScript = path.join(__dirname, 'auto-update.js'),
+  npmTimeoutMs = NPM_TIMEOUT_MS,
+  githubTimeoutMs = GITHUB_TIMEOUT_MS,
+  recordGlobalInstall = null,
+  lockPath = null,
+}) {
+  let lock = null;
+  if (lockPath) {
+    lock = acquireLock(lockPath);
+    if (!lock) {
+      process.stderr.write('[code-graph] another session is already installing the binary; this stub will pick it up when it lands\n');
+      return;
+    }
+  }
+  const finish = (fn) => {
+    if (lock) { lock.release(); lock = null; }
+    fn();
+  };
+  const resolved = () => {
+    clearCache();
+    return findBinary();
+  };
+
+  runStep('npm', ['install', '-g', `@sdsrs/code-graph@${version}`], npmTimeoutMs, '[code-graph][npm]', spawnFn, (npmExit) => {
+    if (resolved()) {
+      if (npmExit === 0 && recordGlobalInstall) {
+        try { recordGlobalInstall(); } catch { /* marker is best-effort */ }
+      }
+      finish(onInstalled);
+      return;
+    }
+    process.stderr.write('[code-graph] npm install did not yield a binary; falling back to GitHub release download...\n');
+    runStep(process.execPath, [autoUpdateScript, '--silent', '--install-missing'], githubTimeoutMs, '[code-graph][auto-update]', spawnFn, () => {
+      if (resolved()) { finish(onInstalled); return; }
+      finish(onFailed);
+    }, {
+      // The child would otherwise try to take the same install lock we hold.
+      env: { ...process.env, CODE_GRAPH_INSTALL_LOCK_HELD: '1' },
+    });
+  }, NPM_NEEDS_SHELL ? { shell: true } : {});
+}
+
+module.exports = { installBinaryInBackground, runStep, NPM_TIMEOUT_MS, GITHUB_TIMEOUT_MS };