@sdsrs/code-graph 0.140.0 → 0.142.0

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.140.0",
+  "version": "0.142.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');
@@ -826,6 +844,48 @@ function unadopt({ cwd, home } = {}) {
   };
 }
 
+/**
+ * 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 printed with the bare name is
+ * answered by their shell 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 this file, 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 this file 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 this script. It carries its own `require.main === module` arm, and
+ * `__filename` is the one locator that cannot be wrong in any install layout —
+ * plugin cache, npm package, dev checkout. Quoted, since a plugin cache path
+ * under a home directory with a space is otherwise not runnable as printed.
+ *
+ * Lives here rather than in session-init.js (0.141.0's home for it) because
+ * BOTH printers that hand a user this command must agree, and the other one is
+ * `formatResult` directly below — the site 0.141.0's sweep missed.
+ */
+function shellQuote(value) {
+  // SINGLE quotes, not JSON.stringify. `JSON.stringify` emits DOUBLE quotes, and
+  // a POSIX shell still expands `$`, backticks and `$(...)` inside those — so a
+  // path holding any of them would be rewritten, or executed, when the user
+  // pastes the line we printed. Single quotes are literal for everything except
+  // `'` itself, which is closed, escaped and reopened. POSIX-only is fine here:
+  // `platformGuard()` refuses adopt on win32, so this string never targets cmd
+  // or PowerShell. (CodeRabbit on PR #46; inherited from the 0.141.0 spelling.)
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function unadoptCommand() {
+  return `node ${shellQuote(__filename)} unadopt`;
+}
+
 function formatResult(action, result) {
   if (!result.ok && result.reason === 'windows-not-supported') {
     return '[code-graph] adopt/unadopt are POSIX-only on this build. ' +
@@ -863,7 +923,7 @@ function formatResult(action, result) {
     lines.push(`[code-graph] Detail table → ${result.detailPath}`);
     lines.push('[code-graph] CLAUDE.md is git-tracked — commit the block, or gitignore');
     lines.push('[code-graph]   .claude/plugin_code_graph_mcp.md (a generated copy) as you prefer.');
-    lines.push('[code-graph] Reverse:  code-graph-mcp unadopt');
+    lines.push(`[code-graph] Reverse:  ${unadoptCommand()}`);
     lines.push('[code-graph] Opt out:  CODE_GRAPH_NO_AUTO_ADOPT=1 in ~/.claude/settings.json env');
     return lines.join('\n');
   }
@@ -891,14 +951,32 @@ 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);
 }
 
 module.exports = {
-  adopt, unadopt, memoryDir, formatResult, stripSentinelBlock,
+  adopt, unadopt, memoryDir, formatResult, unadoptCommand, shellQuote, stripSentinelBlock,
   readAdoptedProjects, readAdoptedResult, recordAdopted, removeAdopted, adoptedRegistryFile,
   isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
   detectProjectType, buildBlock, buildTriggerRows, migrateLegacyMemoryDir,

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/lifecycle.js

@@ -780,7 +780,24 @@ function reportUnadoptSweep(entries) {
       lines.push('             Your own text outside the block was kept; .code-graph/ index dirs are untouched.');
     }
     if (failed.length) {
-      lines.push(`[code-graph] Could NOT clean ${failed.length} project(s) — remove the block by hand or run \`code-graph-mcp unadopt\` there:`);
+      // Issue #41's third printer. The other two now spend `unadoptCommand()`,
+      // and that IS still runnable at the instant this line prints — the reclaim
+      // below never touches the plugin's script dir. But this is advice acted on
+      // minutes or days later, in OTHER repositories, and the plugin directory is
+      // Claude Code's to reap once the uninstall settles. A path into it is
+      // correct-when-printed and possibly-stale-when-pasted, and the bare name it
+      // replaced was never runnable for a plugin-only install at all.
+      //
+      // So lead with the remedy that cannot go stale: the block is
+      // sentinel-delimited, so deleting the lines between the two markers is a
+      // complete instruction that needs no tooling, no network and no surviving
+      // install. The tool route follows it, named as optional.
+      const { SENTINEL_BEGIN, SENTINEL_END } = require('./adopt');
+      lines.push(`[code-graph] Could NOT clean ${failed.length} project(s). In each CLAUDE.md below, delete`);
+      lines.push(`             everything from  ${SENTINEL_BEGIN}`);
+      lines.push(`             through          ${SENTINEL_END}`);
+      lines.push('             (your own text outside those markers is not ours to remove), or run');
+      lines.push('             `npx -y @sdsrs/code-graph unadopt` in the project:');
       for (const p of failed.slice(0, 10)) lines.push(`             ${p}`);
     }
     process.stderr.write(lines.join('\n') + '\n');

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

@@ -10,7 +10,7 @@ const {
 } = require('./lifecycle');
 const { UPDATE_STATE_FILE } = require('./cache-paths');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
-const { maybeAutoAdopt, isAdopted, unadopt } = require('./adopt');
+const { maybeAutoAdopt, isAdopted, unadopt, unadoptCommand } = require('./adopt');
 const { isNonProjectCwd } = require('./project-detect');
 const { hidden } = require('./proc-opts');
 const { installHookFailOpen, remainingMs } = require('./hook-fail-open');
@@ -557,6 +557,13 @@ function verifyBinary() {
   return { available: true, binary };
 }
 
+// `unadoptCommand` now lives in adopt.js (issue #41's rationale travels with
+// it). It moved because THIS file was not the only printer handing a user that
+// command — adopt.js's own `formatResult` prints a `Reverse:` line too, and it
+// was still spending the bare name after 0.141.0 fixed the announcement below.
+// Two spellings of one remedy is what let that survive; re-exported here so the
+// name stays importable from this module.
+
 /**
  * Lightweight consistency checks — called from runSessionInit().
  * Returns an array of issue objects: { id, msg, fix }.
@@ -806,7 +813,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 +827,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 +1097,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.142.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.142.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.142.0",
+    "@sdsrs/code-graph-linux-arm64": "0.142.0",
+    "@sdsrs/code-graph-darwin-x64": "0.142.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.142.0",
+    "@sdsrs/code-graph-win32-x64": "0.142.0"
   }
 }