@sdsrs/code-graph 0.112.1 → 0.113.0

package/README.md

@@ -353,7 +353,7 @@ Skip the full local index for team members and CI runners by publishing a
 ~3-5MB graph snapshot with each GitHub release.
 
 **Setup (one-time):**
-1. Copy `node_modules/code-graph-mcp/templates/code-graph-snapshot.yml`
+1. Copy `node_modules/@sdsrs/code-graph/claude-plugin/templates/code-graph-snapshot.yml`
    into your repo's `.github/workflows/`.
 2. Push a release tag. The workflow uploads
    `code-graph-snapshot-<sha>.db.zst` as a release asset.
@@ -361,7 +361,7 @@ Skip the full local index for team members and CI runners by publishing a
 **Verify:**
 
 ```bash
-npx code-graph-mcp snapshot inspect ./code-graph-snapshot-<sha>.db.zst
+npx -y -p @sdsrs/code-graph code-graph-mcp snapshot inspect ./code-graph-snapshot-<sha>.db.zst
 ```
 
 After setup, the auto-fetch is **opt-in per consumer**: an untrusted repo could

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

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

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

@@ -130,26 +130,56 @@ function saveState(state) {
 
 // ── Throttle ───────────────────────────────────────────────
 
+// The updater has given up on the current target release (MAX_UPDATE_ATTEMPTS
+// consecutive failed installs of the SAME version, retried once a day).
+// `suspendedAt` is stamped only on entry to that state and cleared on success
+// and on a new target, so it alone identifies it; `updateAttempts` is required
+// too so a hand-edited or half-written state file cannot park the updater.
+function isUpdateSuspended(state) {
+  return Boolean(state && state.suspendedAt) && (state.updateAttempts || 0) >= MAX_UPDATE_ATTEMPTS;
+}
+
 // Whether to hit GitHub now. Keyed to the previous check's outcome, with a force
-// override for high-intent triggers (session start / explicit reload). Ordering:
+// override for high-intent triggers (session start / explicit reload) and two
+// binary-health overrides. EVERY bypass is decided here — the caller used to
+// short-circuit `binaryMissing`/`binaryStale` outside this function, which put
+// them above the rate-limit arm and made the "wins over everything" below false:
+// a stale binary plus `rateLimited: true` hit the API on every session start
+// (measured: 1 request per check, vs 0 for the same state with a current
+// binary). Ordering:
 //   1. rate-limit backoff (RATE_LIMIT_INTERVAL_MS, 1h = GitHub's own reset
-//      window) wins over everything, force included — never push more requests
-//      into a GitHub 403. Safe to outrank force only because it is an hour; the
-//      24h it said before made one 403 a silent day-long no-op for `--force`.
-//   2. force → only the short SESSION_START_MIN_GAP_MS floor applies, so opening
+//      window) wins over everything — force and both binary overrides included.
+//      Never push more requests into a GitHub 403; a 403 cannot hand us a
+//      download URL either, so the bypasses have nothing to gain by outranking
+//      it. Safe to outrank force only because it is an hour; the 24h it said
+//      before made one 403 a silent day-long no-op for `--force`.
+//   2. binaryMissing → check now. This is the one repair still reachable while
+//      the download chain is otherwise parked (the suspension branch in
+//      checkForUpdate keeps that heal alive), so it outranks suspension.
+//   3. suspension → neither `binaryStale` nor `force` applies. A stale binary
+//      cannot be healed while the chain is parked, and since suspension makes
+//      `cachedBinaryStaleVsState` permanently true, that bypass otherwise
+//      fired on every single session forever and did nothing with the answer.
+//      Both fall through to the ordinary interval, which still notices a newer
+//      release (that un-suspends) and still lets the daily retry come due.
+//   4. force → only the short SESSION_START_MIN_GAP_MS floor applies, so opening
 //      a new session re-checks immediately while a crash/reopen loop still can't
 //      hammer the API.
-//   3. otherwise → an "up to date" result is re-verified on a short cadence
+//   5. otherwise → an "up to date" result is re-verified on a short cadence
 //      (UP_TO_DATE_RECHECK_MS). This is the release-publish race guard: a version
 //      can go live seconds AFTER a check that said "up to date", and the plain 6h
 //      interval left it invisible for the full 6h (observed live — v0.85.7
 //      published 8s after a check pinned v0.85.6). A pending-but-unfinished update
 //      keeps the 6h steady-state interval.
-function shouldCheck(state, { force = false } = {}) {
+function shouldCheck(state, { force = false, binaryMissing = false, binaryStale = false } = {}) {
   if (!state.lastCheck) return true;
   const elapsed = Date.now() - new Date(state.lastCheck).getTime();
   if (state.rateLimited) return elapsed >= RATE_LIMIT_INTERVAL_MS;
-  if (force) return elapsed >= SESSION_START_MIN_GAP_MS;
+  if (binaryMissing) return true;
+  if (!isUpdateSuspended(state)) {
+    if (binaryStale) return true;
+    if (force) return elapsed >= SESSION_START_MIN_GAP_MS;
+  }
   const interval = state.updateAvailable === false ? UP_TO_DATE_RECHECK_MS : CHECK_INTERVAL_MS;
   return elapsed >= interval;
 }
@@ -373,8 +403,12 @@ async function downloadBinary(latest) {
 
   try {
     fs.mkdirSync(BINARY_CACHE_DIR, { recursive: true });
+    // `-f` (fail on HTTP >= 400), same as the sidecar fetch below. Without it
+    // curl writes GitHub's 404/503 HTML body to binaryTmp and exits 0, so the
+    // error page travelled on as a candidate binary and was only caught two
+    // gates later — by the silent size check, which reported nothing about why.
     execFileSync('curl', [
-      '-sL', '-o', binaryTmp,
+      '-sfL', '-o', binaryTmp,
       latest.binaryUrl,
     ], hidden({ timeout: 60000, stdio: 'pipe' }));
 
@@ -427,8 +461,20 @@ function sha256File(filePath) {
 
 function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSha256) {
   try {
+    // Size floor: every published binary is tens of MB, so anything under 1 MB
+    // is a truncated transfer or an error page. It used to return false without
+    // a word — and it sits ABOVE the two gates that DO explain themselves, so
+    // the most common download failures were also the only silent ones, each
+    // burning one of MAX_UPDATE_ATTEMPTS with nothing on stderr to explain it.
     const stat = fs.statSync(binaryTmp);
-    if (stat.size <= 1_000_000) return false;
+    if (stat.size <= 1_000_000) {
+      console.error(
+        `[code-graph] Refusing to install: downloaded binary is ${stat.size} bytes — far below the ~1 MB floor, ` +
+        'so the transfer was truncated or the server returned an error page. ' +
+        'The current binary is unchanged; the next update check retries.'
+      );
+      return false;
+    }
 
     // Integrity gate BEFORE the file is made executable or run, so a corrupted
     // or tampered download is never exec'd. The published <asset>.sha256 sidecar
@@ -462,13 +508,26 @@ function promoteVerifiedBinary(binaryTmp, binaryDst, expectedVersion, expectedSh
 
     const actualVersion = readBinaryVersion(binaryTmp);
     if (!actualVersion || (expectedVersion && actualVersion !== expectedVersion)) {
+      // Sibling of the size floor above: silent for the same reason and with the
+      // same cost. `--version` failing to run at all (wrong arch, missing libc)
+      // reads identically to a version mismatch without this.
+      console.error(
+        `[code-graph] Refusing to install: downloaded binary reports ${actualVersion ? `v${actualVersion}` : 'no runnable --version'}` +
+        `${expectedVersion ? `, expected v${expectedVersion}` : ''} — not installing it.`
+      );
       return false;
     }
 
     fs.renameSync(binaryTmp, binaryDst);
     clearBinaryCache();
     return true;
-  } catch {
+  } catch (e) {
+    // `e.code` is the whole diagnosis for this arm: ENOSPC (full disk), EACCES /
+    // EPERM (locked cache dir, or Windows refusing to replace the .exe the MCP
+    // server is running), EBUSY, EXDEV. A bare `catch { return false }` made all
+    // of them one indistinguishable failure that the caller counted as an
+    // attempt and printed nothing about.
+    console.error(`[code-graph] Binary promote failed${e && e.code ? ` (${e.code})` : ''}: ${e && e.message}`);
     return false;
   } finally {
     try {
@@ -834,10 +893,13 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
     // (launcher cannot start) and a present-but-stale binary (otherwise it stays
     // pinned to the old version for up to a full check interval — the binary
     // self-heal would never run inside the throttle window). Both bypass to the
-    // fetch + self-heal path below.
+    // fetch + self-heal path below — but they are ARGUMENTS to shouldCheck, not
+    // `||`-ed around it: as short-circuits out here they sat above the
+    // rate-limit backoff and the suspension state, the two conditions under
+    // which a fetch cannot accomplish anything at all.
     const binaryMissing = !fs.existsSync(cachedBinaryPath());
     const binaryStale = cachedBinaryStaleVsState(state);
-    if (!binaryMissing && !binaryStale && !shouldCheck(state, { force })) {
+    if (!shouldCheck(state, { force, binaryMissing, binaryStale })) {
       if (state.installedVersion !== installedVersion) {
         saveState({ ...state, installedVersion });
       }
@@ -1031,6 +1093,7 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
 
 module.exports = {
   checkForUpdate, commandExists, isDevMode, readState, compareVersions, shouldCheck,
+  isUpdateSuspended,
   getExtractedPluginVersion, readBinaryVersion, promoteVerifiedBinary,
   isSilentMode, isInstallMissingMode, isForceMode, isAutoUpdateDisabled,
   MAX_UPDATE_ATTEMPTS,

package/claude-plugin/scripts/doctor.js

@@ -138,6 +138,13 @@ function runDiagnostics({ checkOnly = false } = {}) {
     if (execOk) {
       try {
         const cwd = process.cwd();
+        // Deliberately NOT `--deep`. That flag forces the integrity pragmas the
+        // default path skips above INTEGRITY_PRAGMA_MAX_BYTES, and quick_check
+        // reads every page at ~2.4 ms/MB — a multi-GB index would blow the 5 s
+        // budget below and report a phantom "health-check failed" instead of the
+        // integrity answer it went looking for. Raising the timeout to fit trades
+        // that for a doctor run that appears hung. `--deep` stays a user-invoked
+        // escape hatch until this call can size its own budget from the index.
         const hcOutput = execFileSync(binary, ['health-check', '--json'], hidden({
           cwd,
           timeout: 5000,
@@ -495,7 +502,85 @@ function devBuildCommand(embed) {
     : 'cargo build --release --no-default-features';
 }
 
-function runRepairs(results) {
+// ── Post-repair re-scan for the auto-update-driven arms ────────────────────
+//
+// `auto-update.js check` has NO non-zero exit path: dev mode, the opt-out,
+// suspension, the rate-limit backoff and plain offline all print a line and exit
+// 0. So "execFileSync did not throw" carries no information about whether
+// anything was repaired, and the two arms below counted every one of those
+// no-ops as a fix — including the one the suspension notice sends the user here
+// to run, producing "✅ Update check complete" for a check that is suspended.
+// Re-read the same predicate the DIAGNOSIS used and let that decide, exactly as
+// the `hooks-invalid` arm does with its post-install re-scan.
+
+function triggerAutoUpdateCheck() {
+  execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
+    timeout: 60000,
+    stdio: 'inherit',
+  }));
+}
+
+/**
+ * Mirror of the `version-mismatch` diagnosis (runDiagnostics step 2): the binary
+ * on disk reports the version the plugin expects. find-binary memoizes, and the
+ * promote happened in a CHILD process, so the cache has to be dropped first or
+ * this re-reads the pre-repair answer.
+ */
+function binaryVersionResolved({
+  find = findBinary, readVersion = readBinaryVersion, pluginVersion = getPluginVersion,
+} = {}) {
+  clearBinaryCache();
+  const binary = find();
+  if (!binary) return false;
+  const actual = readVersion(binary);
+  return Boolean(actual) && actual === pluginVersion();
+}
+
+/** Mirror of the `update-incomplete` diagnosis (runDiagnostics step 5). */
+function updateIncompleteResolved({ readStateFile = readUpdateState } = {}) {
+  const state = readStateFile();
+  return !(state && state.updateAvailable && state.binaryUpdated === false);
+}
+
+function readUpdateState() {
+  try { return readJson(path.join(CACHE_DIR, 'update-state.json')); } catch { return null; }
+}
+
+/**
+ * Why a just-run `auto-update.js check` can have done nothing, in the updater's
+ * own terms. Without this the user is told to update manually with no idea that
+ * the updater is deliberately parked — which is the state the doctor prompt
+ * itself came from.
+ * @returns {string|null} one clause, or null when nothing is known to block it
+ */
+function autoUpdateNoOpReason(state = readUpdateState(), env = process.env) {
+  if (env.CODE_GRAPH_NO_AUTO_UPDATE === '1') {
+    return 'auto-update is switched off by CODE_GRAPH_NO_AUTO_UPDATE=1';
+  }
+  if (!state) return null;
+  if (state.suspendedAt && (state.updateAttempts || 0) >= MAX_UPDATE_ATTEMPTS) {
+    return `auto-update is SUSPENDED after ${state.updateAttempts} failed attempts on v${state.latestVersion} `
+      + '(it retries once a day, and immediately when a newer release is published)';
+  }
+  if (state.rateLimited) {
+    return 'the updater is in its GitHub rate-limit backoff (up to 1h)';
+  }
+  return null;
+}
+
+function reportAutoUpdateNoOp(what) {
+  console.log(`  ❌ ${what}`);
+  const why = autoUpdateNoOpReason();
+  if (why) console.log(`     Why: ${why}.`);
+  console.log('     Update manually: `npm install -g @sdsrs/code-graph` (or `/plugin update code-graph-mcp`)');
+}
+
+function runRepairs(results, {
+  devMode = isDevMode,
+  runAutoUpdate = triggerAutoUpdateCheck,
+  binaryResolved = binaryVersionResolved,
+  updateResolved = updateIncompleteResolved,
+} = {}) {
   const fixable = results.filter(r => r.fixId);
   if (fixable.length === 0) return 0;
 
@@ -504,17 +589,21 @@ function runRepairs(results) {
     switch (issue.fixId) {
       case 'binary-stale':
       case 'version-mismatch': {
-        if (!isDevMode()) {
+        if (!devMode()) {
           console.log('\n  Triggering binary update...');
           try {
-            execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
-              timeout: 60000,
-              stdio: 'inherit',
-            }));
-            console.log('  \u2705 Update check complete');
-            fixed++;
+            runAutoUpdate();
           } catch {
             console.log('  \u274c Update check failed — install manually');
+            break;
+          }
+          // Exited 0 — which says nothing about whether the binary moved (see
+          // the re-scan note above). Ask the disk, not the exit code.
+          if (binaryResolved()) {
+            console.log('  \u2705 Binary now matches the version the plugin expects');
+            fixed++;
+          } else {
+            reportAutoUpdateNoOp('Update check ran, but the binary version still does not match the plugin');
           }
           break;
         }
@@ -547,7 +636,7 @@ function runRepairs(results) {
 
       case 'binary-missing': {
         console.log('\n  Installing binary...');
-        if (isDevMode()) {
+        if (devMode()) {
           // No binary to probe \u2014 build the fast FTS5 binary, but point at the
           // hybrid option so FTS5 isn't silently presented as the only choice.
           console.log('    \u2192 cargo build --release --no-default-features');
@@ -612,14 +701,18 @@ function runRepairs(results) {
       case 'update-incomplete': {
         console.log('\n  Completing auto-update...');
         try {
-          execFileSync(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check'], hidden({
-            timeout: 60000,
-            stdio: 'inherit',
-          }));
-          console.log('  \u2705 Update check complete');
-          fixed++;
+          runAutoUpdate();
         } catch {
           console.log('  \u274c Update check failed');
+          break;
+        }
+        // Same as the version-mismatch arm: exit 0 is not evidence. Re-read
+        // the state file the diagnosis read.
+        if (updateResolved()) {
+          console.log('  \u2705 Auto-update completed — the binary download is no longer pending');
+          fixed++;
+        } else {
+          reportAutoUpdateNoOp('Update check ran, but the binary download is still recorded as incomplete');
         }
         break;
       }
@@ -739,7 +832,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, detectEmbedModel, devBuildCommand };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, autoUpdateNoOpReason };
 
 // Shared by BOTH doctor entry points: `node doctor.js …` and `node lifecycle.js
 // doctor …`. It exists as one function because the first version of this guard

package/claude-plugin/templates/code-graph-snapshot.yml

@@ -3,7 +3,13 @@
 # small (~3-5MB) zstd-compressed SQLite database that lets first-time
 # clones of your repo skip the initial full code-graph index.
 #
-# Requires: code-graph-mcp >= 0.23.0 published to npm.
+# Requires: @sdsrs/code-graph >= 0.23.0 published to npm.
+#
+# The package name is `@sdsrs/code-graph` (the `code-graph-mcp` binary lives
+# inside it). Do NOT shorten this to `npx -y code-graph-mcp` — that unscoped
+# name belongs to an unrelated publisher on npm, and `npx -y` would install and
+# execute their package in your CI with whatever permissions this job holds.
+# Bump the pinned version below when you want a newer snapshot format.
 
 name: Code Graph Snapshot
 on:
@@ -24,7 +30,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y code-graph-mcp@latest snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.113.0 code-graph-mcp snapshot create --out snapshot.db
           zstd -9 snapshot.db -o snapshot.db.zst
           mv snapshot.db.zst "code-graph-snapshot-${GITHUB_SHA:0:7}.db.zst"
       - name: Upload to release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.112.1",
+  "version": "0.113.0",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.112.1",
-    "@sdsrs/code-graph-linux-arm64": "0.112.1",
-    "@sdsrs/code-graph-darwin-x64": "0.112.1",
-    "@sdsrs/code-graph-darwin-arm64": "0.112.1",
-    "@sdsrs/code-graph-win32-x64": "0.112.1"
+    "@sdsrs/code-graph-linux-x64": "0.113.0",
+    "@sdsrs/code-graph-linux-arm64": "0.113.0",
+    "@sdsrs/code-graph-darwin-x64": "0.113.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.113.0",
+    "@sdsrs/code-graph-win32-x64": "0.113.0"
   }
 }