@sdsrs/code-graph 0.140.0 → 0.141.0

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

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

package/claude-plugin/scripts/adopt.js

@@ -71,6 +71,21 @@ function writeFileAtomic(filePath, data, { followLink = false } = {}) {
 // the full table at .claude/plugin_code_graph_mcp.md (opened on demand, never
 // auto-loaded). Project-type tailoring swaps a couple of rows (web → HTTP-route
 // tracing; frontend → reference audits) — body of the detail doc is unchanged.
+//
+// Every row spends the bare name `code-graph-mcp`, and a plugin-only install has
+// it nowhere on PATH: findBinary() resolves the plugin's own download at
+// ~/.cache/code-graph/bin (auto-update.js `cachedBinaryPath`), and the global-npm
+// tiers below it exist only for users who ran `npm i -g` themselves. Issue #41 is
+// what that reads like from the other side — a table of commands the user's shell
+// answers with "command not found". Hence the fallback line below the table.
+//
+// It names a path SHAPE, never a resolved one. This file goes into a git-tracked
+// CLAUDE.md (the adopt output says so two screens down), so a resolved
+// /home/<user>/… is right on one machine and wrong on every teammate's — and
+// buildBlock's byte-determinism is exactly what needsRefresh diffs, so
+// machine-varying content would rewrite the block on every clone's next
+// SessionStart. No `.exe` variant for the same reason it is safe not to have one:
+// platformGuard() refuses adopt on win32, so this block never exists there.
 const BLOCK_HEADING = '## Code Graph (repo-wide AST index)';
 
 function buildTriggerRows(projectType = 'generic') {
@@ -116,6 +131,9 @@ function buildBlock(projectType = 'generic') {
     '',
     table,
     '',
+    'Not on PATH? A plugin-only install keeps its own copy — same commands, run',
+    '`~/.cache/code-graph/bin/code-graph-mcp` (or `npm i -g @sdsrs/code-graph` once).',
+    '',
     "Still use Grep for literal strings/regex in non-code files; still Read files you'll edit.",
     'Full command + MCP-tool table: `.claude/plugin_code_graph_mcp.md`',
   ].join('\n');
@@ -891,7 +909,25 @@ function formatResult(action, result) {
 }
 
 if (require.main === module) {
-  const action = process.argv[2] === 'unadopt' ? 'unadopt' : 'adopt';
+  // Strict, because SessionStart now hands users this entry point directly
+  // (`node <…>/adopt.js unadopt`) rather than the binary, which validates its
+  // arguments in main.rs before dispatching here. The old `argv[2] === 'unadopt'
+  // ? … : 'adopt'` fell back to ADOPT for anything else, so `--help` performed
+  // an unadopt where the binary prints help, and a mistyped verb silently
+  // adopted the current project — the footgun main.rs's `reject_extra_args`
+  // exists to prevent.
+  //
+  // Both binary call sites stay valid: main.rs passes `["unadopt"]` for unadopt
+  // and no arguments at all for adopt.
+  const argv = process.argv.slice(2);
+  const action = argv.length === 0 ? 'adopt' : argv[0];
+  if (argv.length > 1 || (action !== 'adopt' && action !== 'unadopt')) {
+    process.stderr.write(
+      `[code-graph] Usage: node ${path.basename(__filename)} [adopt|unadopt]\n` +
+      '  Exactly one verb and no flags. No argument means `adopt`.\n' +
+      '  Refusing rather than guessing: both verbs write to your CLAUDE.md.\n');
+    process.exit(2);
+  }
   const result = action === 'unadopt' ? unadopt() : adopt();
   process.stdout.write(formatResult(action, result) + '\n');
   process.exit(result.ok === false ? 1 : 0);

package/claude-plugin/scripts/incremental-index.js

@@ -12,6 +12,24 @@ const { execFileSync } = require('child_process');
 const { findBinary } = require('./find-binary');
 const { hidden } = require('./proc-opts');
 
+// Default allowance for this hook's one child, spent through the hook budget
+// below. The PostToolUse deadline armed at the top of this file is 10 s.
+const CHILD_TIMEOUT_MS = 8000;
+
+/**
+ * How long the indexer child may run: the default when nothing armed a deadline
+ * (a test importing this module, a manual invocation), or whatever is LEFT of
+ * the PostToolUse budget. `null` means the budget is exhausted — do not run.
+ *
+ * JS-32: the child spent a literal 8 s no matter how much of the 10 s deadline
+ * `findBinary()` had already consumed, so a cold cache overran it and Claude
+ * Code killed the hook on the user's own edit. Exported because `runMain()`
+ * cannot be reached from a test without spawning the hook (JS-18's shape).
+ */
+function childBudgetMs() {
+  return require('./hook-fail-open').remainingMs(CHILD_TIMEOUT_MS);
+}
+
 // v0.21 — gated default-off. v0.18.0 added query-time freshness
 // (ensure_file_indexed) inside MCP tools that take a file_path arg, so a
 // PostToolUse hook spawning a fresh process on every Edit/Write was redundant
@@ -37,9 +55,14 @@ function runMain() {
   const bin = findBinary();
   if (!bin) return; // silent — binary not installed yet
 
+  // Read AFTER findBinary(): that chain is what eats the budget on a cold
+  // cache, and asking before it would hand the child an allowance nobody had.
+  const budget = childBudgetMs();
+  if (budget === null) return; // exhausted — the index waits for the next edit
+
   try {
     execFileSync(bin, ['incremental-index', '--quiet'], hidden({
-      timeout: 8000,
+      timeout: budget,
       stdio: ['pipe', 'pipe', 'pipe']
     }));
   } catch { /* timeout or error — silent for hook */ }
@@ -49,4 +72,4 @@ if (require.main === module) {
   runMain();
 }
 
-module.exports = { shouldRun };
+module.exports = { shouldRun, childBudgetMs, CHILD_TIMEOUT_MS };

package/claude-plugin/scripts/session-init.js

@@ -557,6 +557,35 @@ function verifyBinary() {
   return { available: true, binary };
 }
 
+/**
+ * The `unadopt` invocation to hand the user, spelled so their shell can run it.
+ *
+ * Issue #41: the reporter drives this plugin through `/plugin install` only and
+ * has no `code-graph-mcp` on PATH, so every remedy this hook printed spent a
+ * bare name their shell answers with "command not found".
+ *
+ * The obvious repair — print the binary `verifyBinary()` resolved — is WRONG,
+ * and a pre-ship review caught it as a net regression. `unadopt` is one of the
+ * three JS-dispatched subcommands (`main.rs`: doctor / adopt / unadopt): the
+ * native binary re-execs `claude-plugin/scripts/adopt.js`, which it locates via
+ * `$_FIND_BINARY_ROOT` or a path relative to its own exe. The plugin's cached
+ * binary at ~/.cache/code-graph/bin has no such neighbour, so
+ * `<cache>/code-graph-mcp unadopt` exits 1 with "adopt.js not found" —
+ * reproduced. Worse, npm-global users reach adopt.js today through the
+ * `bin/cli.js` shim that sets `_FIND_BINARY_ROOT`, so printing a resolved
+ * platform-package binary would BREAK a path that currently works.
+ *
+ * So point at the script itself. `adopt.js` carries its own
+ * `require.main === module` arm (`node adopt.js unadopt`), and this file is its
+ * neighbour in every install layout — plugin cache, npm package, dev checkout —
+ * because both are shipped inside `claude-plugin/scripts/`. `__dirname` is
+ * therefore the one locator that cannot be wrong. Quoted, since a plugin cache
+ * path under a home directory with a space is otherwise not runnable as printed.
+ */
+function unadoptCommand() {
+  return `node ${JSON.stringify(path.join(__dirname, 'adopt.js'))} unadopt`;
+}
+
 /**
  * Lightweight consistency checks — called from runSessionInit().
  * Returns an array of issue objects: { id, msg, fix }.
@@ -806,7 +835,7 @@ function runSessionInit({ source } = {}) {
         '[code-graph] Installed code-graph block into project CLAUDE.md (plugin install → knowing consent).\n' +
         '            Detail table: .claude/plugin_code_graph_mcp.md (generated; safe to gitignore)\n' +
         '            Opt out:    CODE_GRAPH_NO_AUTO_ADOPT=1 in ~/.claude/settings.json env\n' +
-        '            Reverse:    code-graph-mcp unadopt\n'
+        `            Reverse:    ${unadoptCommand()}\n`
       );
     }
     // `adopt()` has returned `registryRecorded` since it stopped throwing on a
@@ -820,7 +849,7 @@ function runSessionInit({ source } = {}) {
       process.stderr.write(
         '[code-graph] Note: this project could not be recorded in the adopted-projects registry,\n' +
         '            so `/plugin uninstall` will NOT strip the block from this CLAUDE.md.\n' +
-        '            Remove it by hand with `code-graph-mcp unadopt` before uninstalling.\n'
+        `            Remove it by hand with \`${unadoptCommand()}\` before uninstalling.\n`
       );
     }
   }
@@ -1090,7 +1119,7 @@ module.exports = {
   indexNeedsRevalidation,
   injectProjectMap,
   injectRecentImpact,
-  verifyBinary, missingBinaryMessage,
+  verifyBinary, missingBinaryMessage, unadoptCommand,
   consistencyCheck,
   runSessionInit,
   computeQuietHooks,

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

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y -p @sdsrs/code-graph@0.140.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.141.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/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -49,6 +49,19 @@ type: reference
 > ToolSearch 加载），而 Bash 永远在线——真实编程夜（2026-06-12）观测到的全部
 > 转化都是 CLI 调用。结构化查询的最快路径是 Bash 直呼
 > `code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`。
+>
+> **裸名字不在 PATH 上时**（纯 `/plugin install`，没跑过 `npm i -g`）：插件自己
+> 下载的那份在 `~/.cache/code-graph/bin/code-graph-mcp`，本文下面所有查询类子命令
+> （callgraph / impact / overview / show / search / grep / refs / similar / deps /
+> dead-code / trace）都能直接用它跑；`npm i -g @sdsrs/code-graph` 则把裸名字放上
+> PATH（issue #41）。
+>
+> **三个例外**：`doctor` / `adopt` / `unadopt` 是 JS 派发的——二进制会去自己旁边
+> 找对应脚本（前者 `doctor.js`，后两者 `adopt.js`），而缓存目录里没有那些邻居，
+> 所以从缓存路径调它们会报 `<脚本名> not found`。直接跑脚本即可：
+> `node <插件目录>/claude-plugin/scripts/adopt.js unadopt`（SessionStart 的提示行
+> 会印出这台机器上的完整路径）、`node <插件目录>/claude-plugin/scripts/doctor.js`。
+>
 > `grep` 是 drop-in 替代：`-F` 字面 / `-i` / `-w` / `-l` / `-c` 计数 / `-t <lang>` 按语言筛 /
 > `-g <glob>` 路径过滤 / `-A/-B/-C N` 上下文 / `-M N` 行宽上限（默认 512，防长行刷屏）/
 > 多路径 / `-m 0` 取消每文件上限，退出码兼容 grep（0/1/2），召回达 git-grep 级

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.140.0",
+  "version": "0.141.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.140.0",
-    "@sdsrs/code-graph-linux-arm64": "0.140.0",
-    "@sdsrs/code-graph-darwin-x64": "0.140.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.140.0",
-    "@sdsrs/code-graph-win32-x64": "0.140.0"
+    "@sdsrs/code-graph-linux-x64": "0.141.0",
+    "@sdsrs/code-graph-linux-arm64": "0.141.0",
+    "@sdsrs/code-graph-darwin-x64": "0.141.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.141.0",
+    "@sdsrs/code-graph-win32-x64": "0.141.0"
   }
 }