@sdsrs/code-graph 0.55.0 → 0.56.1

package/bin/cli.js

@@ -18,17 +18,19 @@ if (sub === "adopt" || sub === "unadopt") {
   process.exit(result.ok === false ? 1 : 0);
 }
 
-const { findBinary } = require("../claude-plugin/scripts/find-binary");
+const { findBinary, unsupportedPlatformHint } = require("../claude-plugin/scripts/find-binary");
 
 const binary = findBinary();
 
 if (!binary) {
+  const hint = unsupportedPlatformHint();
   console.error(
     "Error: code-graph-mcp binary not found.\n\n" +
+    (hint ? hint + "\n\n" : "") +
     "To install:\n" +
     "  npm install -g @sdsrs/code-graph\n\n" +
     "To build from source:\n" +
-    "  cargo build --release\n"
+    "  cargo install code-graph-mcp --features embed-model\n"
   );
   process.exit(1);
 }
@@ -41,6 +43,10 @@ const child = spawn(binary, process.argv.slice(2), {
 
 child.on("error", (err) => {
   console.error(`Failed to start code-graph-mcp: ${err.message}`);
+  // A glibc binary installed on musl (older npm ignores the `libc` field) is present
+  // but fails to exec — surface the actionable platform hint instead of a bare error.
+  const hint = unsupportedPlatformHint();
+  if (hint) console.error("\n" + hint);
   process.exit(1);
 });
 

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

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

package/claude-plugin/scripts/doctor.js

@@ -13,6 +13,38 @@ const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 
 // ── Diagnostics ───────────────────────────────────────────
 
+/**
+ * Classify embedding/vector availability from a `health-check --json` payload.
+ * Pure (no I/O) so it is unit-testable. Surfaces a silent FTS5-only degradation
+ * that the prior embedding_progress-only check false-greened as "no embeddable
+ * nodes": when the binary is embed-capable and the index HAS embeddable nodes but
+ * none are embedded, the vector channel is inactive and semantic search runs
+ * FTS5-only — that is a 'warn', not 'ok'.
+ * @returns {{name:string, status:'ok'|'warn', detail:string}}
+ */
+function classifyEmbeddings(hc) {
+  const ep = (hc && hc.embedding_progress) || '0/0';
+  const [done, total] = ep.split('/').map(Number);
+  if (hc && hc.model_available === false) {
+    return { name: 'Embeddings', status: 'warn',
+      detail: 'binary built without embed-model — semantic search is FTS5-only; reinstall via npm/plugin for the hybrid binary' };
+  }
+  if (!total) {
+    return { name: 'Embeddings', status: 'ok', detail: 'no embeddable nodes' };
+  }
+  if (!done) {
+    const why = (hc && hc.embedding_status === 'pending')
+      ? 'model not downloaded/loaded yet — auto-downloads in background on first search; retry shortly or restart the MCP server'
+      : `embedding_status=${(hc && hc.embedding_status) || 'unknown'}`;
+    return { name: 'Embeddings', status: 'warn',
+      detail: `vector INACTIVE — ${total} embeddable nodes, 0 embedded; semantic search is FTS5-only (${why})` };
+  }
+  if (done < total) {
+    return { name: 'Embeddings', status: 'ok', detail: `hybrid — ${Math.round((done / total) * 100)}% embedded (${done}/${total})` };
+  }
+  return { name: 'Embeddings', status: 'ok', detail: `hybrid — embeddings complete (${done}/${total})` };
+}
+
 /**
  * Run all diagnostic checks. Returns an array of:
  *   { name: string, status: 'ok'|'warn'|'error'|'skip', detail: string, fixId?: string }
@@ -119,17 +151,9 @@ function runDiagnostics() {
             });
           }
 
-          // Embeddings
-          const ep = hc.embedding_progress || '0/0';
-          const [done, total] = ep.split('/').map(Number);
-          if (total > 0 && done < total) {
-            const pct = Math.round((done / total) * 100);
-            results.push({ name: 'Embeddings', status: 'ok', detail: `${pct}% (${done}/${total})` });
-          } else if (total === 0) {
-            results.push({ name: 'Embeddings', status: 'ok', detail: 'no embeddable nodes' });
-          } else {
-            results.push({ name: 'Embeddings', status: 'ok', detail: `100% (${done}/${total})` });
-          }
+          // Embeddings / vector availability — pure classifier; warns on FTS5-only
+          // degradation (model missing/not loaded) instead of false-greening it.
+          results.push(classifyEmbeddings(hc));
         }
       } catch (e) {
         const rawStderr = e.stderr ? e.stderr.toString() : '';
@@ -453,7 +477,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage, relicRepairGuard };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage, relicRepairGuard, classifyEmbeddings };
 
 if (require.main === module) {
   const args = process.argv.slice(2);

package/claude-plugin/scripts/doctor.test.js

@@ -93,3 +93,32 @@ test('relicRepairGuard blocks settings repair from a relic copy and redirects',
   // Active (or dev/npm) context → repair proceeds.
   assert.equal(relicRepairGuard({ relic: false, log: () => {} }), false);
 });
+
+// ── classifyEmbeddings (vector-availability — warns on silent FTS5-only) ──
+
+test('classifyEmbeddings WARNS when embed-capable but nothing embedded (vector inactive)', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  // The exact silent-FTS5 gap: model_available compile-flag true, real embeddable
+  // nodes exist, but 0 embedded (model never downloaded/loaded).
+  const r = classifyEmbeddings({ model_available: true, embedding_progress: '0/2745',
+    embedding_status: 'pending', search_mode: 'fts_only' });
+  assert.equal(r.status, 'warn', 'must not false-green a vector-inactive index');
+  assert.match(r.detail, /FTS5-only|vector INACTIVE/);
+});
+
+test('classifyEmbeddings WARNS when binary lacks embed-model feature', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  const r = classifyEmbeddings({ model_available: false, embedding_progress: '0/0' });
+  assert.equal(r.status, 'warn');
+  assert.match(r.detail, /without embed-model/);
+});
+
+test('classifyEmbeddings OK for hybrid (partial + complete) and no-embeddable', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  assert.equal(classifyEmbeddings({ model_available: true, embedding_progress: '900/2745' }).status, 'ok');
+  assert.equal(classifyEmbeddings({ model_available: true, embedding_progress: '2745/2745' }).status, 'ok');
+  // total === 0 is a non-code index, genuinely nothing to embed → ok, not a false warn.
+  const none = classifyEmbeddings({ model_available: true, embedding_progress: '0/0' });
+  assert.equal(none.status, 'ok');
+  assert.match(none.detail, /no embeddable nodes/);
+});

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

@@ -12,6 +12,45 @@ const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path'
 const BINARY_NAME = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
 const PLATFORM_PKG = `@sdsrs/code-graph-${PLATFORM}-${ARCH}`;
 
+/**
+ * libc flavor of the current Linux runtime: 'glibc' or 'musl'. musl (Alpine) has
+ * no `glibcVersionRuntime` in the Node process-report header. Best-effort; returns
+ * 'glibc' off Linux or when detection is unavailable.
+ */
+function detectLibc() {
+  if (PLATFORM !== 'linux') return 'glibc';
+  try {
+    const header = process.report.getReport().header;
+    if (header && header.glibcVersionRuntime) return 'glibc';
+    return 'musl';
+  } catch {
+    try { if (fs.existsSync('/etc/alpine-release')) return 'musl'; } catch { /* ignore */ }
+    return 'glibc';
+  }
+}
+
+/**
+ * Actionable install hint for a platform that has NO published prebuilt binary
+ * (Alpine/musl, or native Windows-on-ARM), or null when the platform is supported
+ * (generic messaging applies). Pure in (platform, arch, libc) so it is unit-testable
+ * without running on each OS. Prevents the misleading "npm install
+ * @sdsrs/code-graph-<plat>-<arch>" suggestion for a package that does not exist.
+ */
+function unsupportedPlatformHint(platform = PLATFORM, arch = ARCH, libc = null) {
+  const lc = libc || (platform === 'linux' ? detectLibc() : 'glibc');
+  if (platform === 'linux' && lc === 'musl') {
+    return 'Detected Alpine/musl libc, which has no prebuilt binary. Install from source:\n'
+      + '  cargo install code-graph-mcp --features embed-model\n'
+      + 'or use a glibc-based image (e.g. node:20-slim / debian, not node:20-alpine).';
+  }
+  if (platform === 'win32' && arch === 'arm64') {
+    return 'Detected Windows on ARM (arm64), which has no native build. Either use an x64 '
+      + 'build of Node.js (the published x64 binary runs under Windows ARM emulation), '
+      + 'or install from source:\n  cargo install code-graph-mcp --features embed-model';
+  }
+  return null;
+}
+
 /** Read the npm pkg version from this script's package.json (claude-plugin/../package.json). */
 function getPackageVersion() {
   try { return require('../../package.json').version; }
@@ -263,6 +302,7 @@ module.exports = {
   findBinary, findBinaryUncached, clearCache,
   globalNodeModulesCandidates, findPlatformBinary,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
+  detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
 };
 

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

@@ -6,7 +6,8 @@ const os = require('os');
 const path = require('path');
 
 const { globalNodeModulesCandidates, findPlatformBinary, BINARY_NAME,
-        compareVersions, getPackageVersion, isCachedBinaryFresh } = require('./find-binary');
+        compareVersions, getPackageVersion, isCachedBinaryFresh,
+        unsupportedPlatformHint } = require('./find-binary');
 
 function mkDir(t, prefix) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -219,3 +220,27 @@ test('isCachedBinaryFresh: file basename mismatch → not fresh', (t) => {
   if (process.platform !== 'win32') fs.chmodSync(wrongName, 0o755);
   assert.equal(isCachedBinaryFresh(wrongName, '0.25.0'), false);
 });
+
+// ── unsupportedPlatformHint (actionable message for tails with no prebuilt binary) ──
+
+test('unsupportedPlatformHint flags Alpine/musl with a source/glibc-image hint', () => {
+  const hint = unsupportedPlatformHint('linux', 'x64', 'musl');
+  assert.ok(hint, 'musl should produce a hint');
+  assert.match(hint, /musl|Alpine/);
+  assert.match(hint, /cargo install/);
+});
+
+test('unsupportedPlatformHint flags native Windows-on-ARM with emulation/source hint', () => {
+  const hint = unsupportedPlatformHint('win32', 'arm64', 'glibc');
+  assert.ok(hint, 'win32-arm64 should produce a hint');
+  assert.match(hint, /Windows on ARM|arm64/);
+  assert.match(hint, /x64|cargo install/);
+});
+
+test('unsupportedPlatformHint returns null for supported platforms', () => {
+  assert.equal(unsupportedPlatformHint('linux', 'x64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('linux', 'arm64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('darwin', 'arm64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('darwin', 'x64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('win32', 'x64', 'glibc'), null);
+});

package/claude-plugin/scripts/lifecycle.e2e.test.js

@@ -141,3 +141,39 @@ test('lifecycle install writes to CLAUDE_CONFIG_DIR instead of ~/.claude when se
     'default ~/.claude/settings.json must not be written when override is set');
 });
 
+test('composite expands a leading ~ in a _previous command instead of dropping it (issue #24)', (t) => {
+  // A user whose prior statusline used a leading ~ (valid in settings.json, which
+  // Claude Code runs through a shell). install() captures it verbatim as _previous.
+  // The composite runs providers via execFileSync (no shell), so without tilde
+  // expansion the command throws ENOENT and is silently swallowed — the user's
+  // original statusline vanishes.
+  const homeDir = mkHome(t);
+  const prevScript = path.join(homeDir, '.claude', 'utils', 'statusline.sh');
+  fs.mkdirSync(path.dirname(prevScript), { recursive: true });
+  fs.writeFileSync(prevScript, '#!/bin/sh\necho "PREV-STATUSLINE-OK"\n');
+  fs.chmodSync(prevScript, 0o755);
+
+  const registryPath = path.join(homeDir, '.cache', 'code-graph', 'statusline-registry.json');
+  writeJson(registryPath, [
+    { id: '_previous', command: '~/.claude/utils/statusline.sh', needsStdin: true },
+  ]);
+
+  const out = runScript(homeDir, compositeCli, [], { input: '{}' });
+  assert.match(out, /PREV-STATUSLINE-OK/,
+    'a _previous command using a leading ~ must be tilde-expanded, not silently dropped');
+});
+
+test('expandTilde mirrors shell tilde expansion (only a leading ~ / ~/)', () => {
+  const composite = require('./statusline-composite');
+  const home = os.homedir();
+  assert.equal(composite.expandTilde('~'), home);
+  assert.equal(composite.expandTilde('~/.claude/utils/statusline.sh'),
+    path.join(home, '.claude', 'utils', 'statusline.sh'));
+  assert.equal(composite.expandTilde('/abs/path/script.sh'), '/abs/path/script.sh');
+  assert.equal(composite.expandTilde('node'), 'node');
+  assert.equal(composite.expandTilde('~user/script.sh'), '~user/script.sh',
+    'other-user home dirs are not resolved');
+  assert.equal(composite.expandTilde('a~/b'), 'a~/b',
+    'only a leading ~ expands, not a mid-string ~');
+});
+

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

@@ -105,7 +105,7 @@ if (process.env.CODE_GRAPH_FORCE_PLUGIN_MCP !== '1' && isNonProjectCwd(process.c
   return;
 }
 
-const { findBinary, clearCache } = require('./find-binary');
+const { findBinary, clearCache, unsupportedPlatformHint } = require('./find-binary');
 
 let binary = findBinary();
 
@@ -169,6 +169,14 @@ if (!binary) {
   const installedViaMarketplace = fs.existsSync(
     path.join(__dirname, '..', '.claude-plugin', 'plugin.json')
   );
+  const platformHint = unsupportedPlatformHint();
+  if (platformHint) {
+    // Unsupported platform (Alpine/musl or native Windows-on-ARM): the per-platform
+    // npm package does not exist, so the generic "npm install @sdsrs/code-graph-<plat>-<arch>"
+    // suggestion below would point at a nonexistent package. Show the source/emulation hint.
+    process.stderr.write('[code-graph] Binary not found.\n' + platformHint + '\n');
+    process.exit(1);
+  }
   process.stderr.write('[code-graph] Binary not found. Install manually:\n');
   if (installedViaMarketplace) {
     process.stderr.write(
@@ -217,6 +225,10 @@ child.on('error', (err) => {
       `  xattr -d com.apple.quarantine "${binary}"\n`
     );
   }
+  // A glibc binary installed on musl (older npm ignores the `libc` field) is present
+  // but execs into a loader error — surface the actionable platform hint.
+  const platformHint = unsupportedPlatformHint();
+  if (platformHint) process.stderr.write(platformHint + '\n');
   process.exit(1);
 });
 

package/claude-plugin/scripts/statusline-composite.js

@@ -7,22 +7,28 @@
  */
 const { execFileSync } = require('child_process');
 const path = require('path');
+const os = require('os');
 const lifecycle = require('./lifecycle');
 const { readRegistry } = lifecycle;
 const cleanupDisabledStatusline = lifecycle.cleanupDisabledStatusline || (() => ({ cleaned: false }));
 
 const SEPARATOR = ' \x1b[2m|\x1b[0m ';
 
-const disabledCleanup = cleanupDisabledStatusline();
-if (disabledCleanup.cleaned) process.exit(0);
+function main() {
+  const disabledCleanup = cleanupDisabledStatusline();
+  if (disabledCleanup.cleaned) process.exit(0);
 
-// Collect stdin (Claude Code pipes JSON context)
-let stdinData = '';
-let ran = false;
-const stdinTimeout = setTimeout(() => { if (!ran) { ran = true; run(''); } }, 2000);
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => { stdinData += chunk; });
-process.stdin.on('end', () => { clearTimeout(stdinTimeout); if (!ran) { ran = true; run(stdinData); } });
+  // Collect stdin (Claude Code pipes JSON context)
+  let stdinData = '';
+  let ran = false;
+  const stdinTimeout = setTimeout(() => { if (!ran) { ran = true; run(''); } }, 2000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { stdinData += chunk; });
+  process.stdin.on('end', () => { clearTimeout(stdinTimeout); if (!ran) { ran = true; run(stdinData); } });
+}
+
+// Only run the statusline when invoked as a CLI; `require()` (tests) just imports helpers.
+if (require.main === module) main();
 
 function run(stdin) {
   const registry = readRegistry();
@@ -58,7 +64,14 @@ function runProvider(command, needsStdin, stdin) {
     const parts = parseCommand(command);
     if (!parts) return null;
 
-    const out = execFileSync(parts[0], parts.slice(1), {
+    // Claude Code runs statusLine.command through a shell, so a leading `~`
+    // (e.g. `~/.claude/utils/statusline.sh`) is expanded natively. execFileSync
+    // does NOT use a shell, so we must expand `~/` ourselves on every word —
+    // otherwise a `_previous` command captured verbatim throws ENOENT and gets
+    // swallowed below, silently dropping the user's original statusline.
+    const argv = parts.map(expandTilde);
+
+    const out = execFileSync(argv[0], argv.slice(1), {
       timeout: 3000,
       stdio: ['pipe', 'pipe', 'pipe'],
       input: needsStdin ? stdin : '',
@@ -81,9 +94,19 @@ function parseCommand(cmd) {
   return parts.length > 0 ? parts : null;
 }
 
+// Expand a leading `~` / `~/` to the home directory, mirroring shell tilde
+// expansion (which Claude Code applies when it runs statusLine.command, but
+// execFileSync does not). Only a bare `~` or a `~/`-prefixed word is expanded;
+// `~user` and mid-string `~` are left untouched (we don't resolve other users).
+function expandTilde(p) {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
 function codeGraphCommand() {
   // Always derive from __dirname — CLAUDE_PLUGIN_ROOT can leak from other plugins
   return `node "${path.join(__dirname, 'statusline.js')}"`;
 }
 
-module.exports = { run };
+module.exports = { run, runProvider, parseCommand, expandTilde };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.55.0",
+  "version": "0.56.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": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.55.0",
-    "@sdsrs/code-graph-linux-arm64": "0.55.0",
-    "@sdsrs/code-graph-darwin-x64": "0.55.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.55.0",
-    "@sdsrs/code-graph-win32-x64": "0.55.0"
+    "@sdsrs/code-graph-linux-x64": "0.56.1",
+    "@sdsrs/code-graph-linux-arm64": "0.56.1",
+    "@sdsrs/code-graph-darwin-x64": "0.56.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.56.1",
+    "@sdsrs/code-graph-win32-x64": "0.56.1"
   }
 }