@stupidloud/codegraph 0.7.20 → 0.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +127 -106
  2. package/dist/bin/codegraph.d.ts +4 -0
  3. package/dist/bin/codegraph.d.ts.map +1 -1
  4. package/dist/bin/codegraph.js +327 -8
  5. package/dist/bin/codegraph.js.map +1 -1
  6. package/dist/bin/node-version-check.d.ts +17 -0
  7. package/dist/bin/node-version-check.d.ts.map +1 -1
  8. package/dist/bin/node-version-check.js +37 -0
  9. package/dist/bin/node-version-check.js.map +1 -1
  10. package/dist/config.d.ts.map +1 -1
  11. package/dist/config.js +1 -11
  12. package/dist/config.js.map +1 -1
  13. package/dist/db/index.d.ts +30 -1
  14. package/dist/db/index.d.ts.map +1 -1
  15. package/dist/db/index.js +75 -25
  16. package/dist/db/index.js.map +1 -1
  17. package/dist/db/queries.d.ts +16 -0
  18. package/dist/db/queries.d.ts.map +1 -1
  19. package/dist/db/queries.js +80 -27
  20. package/dist/db/queries.js.map +1 -1
  21. package/dist/db/sqlite-adapter.d.ts +17 -23
  22. package/dist/db/sqlite-adapter.d.ts.map +1 -1
  23. package/dist/db/sqlite-adapter.js +51 -174
  24. package/dist/db/sqlite-adapter.js.map +1 -1
  25. package/dist/extraction/grammars.d.ts +7 -1
  26. package/dist/extraction/grammars.d.ts.map +1 -1
  27. package/dist/extraction/grammars.js +42 -2
  28. package/dist/extraction/grammars.js.map +1 -1
  29. package/dist/extraction/index.d.ts +9 -14
  30. package/dist/extraction/index.d.ts.map +1 -1
  31. package/dist/extraction/index.js +131 -124
  32. package/dist/extraction/index.js.map +1 -1
  33. package/dist/extraction/languages/index.d.ts.map +1 -1
  34. package/dist/extraction/languages/index.js +4 -0
  35. package/dist/extraction/languages/index.js.map +1 -1
  36. package/dist/extraction/languages/lua.d.ts +3 -0
  37. package/dist/extraction/languages/lua.d.ts.map +1 -0
  38. package/dist/extraction/languages/lua.js +150 -0
  39. package/dist/extraction/languages/lua.js.map +1 -0
  40. package/dist/extraction/languages/luau.d.ts +3 -0
  41. package/dist/extraction/languages/luau.d.ts.map +1 -0
  42. package/dist/extraction/languages/luau.js +37 -0
  43. package/dist/extraction/languages/luau.js.map +1 -0
  44. package/dist/extraction/tree-sitter.d.ts.map +1 -1
  45. package/dist/extraction/tree-sitter.js +38 -0
  46. package/dist/extraction/tree-sitter.js.map +1 -1
  47. package/dist/extraction/wasm/tree-sitter-lua.wasm +0 -0
  48. package/dist/extraction/wasm/tree-sitter-luau.wasm +0 -0
  49. package/dist/extraction/wasm-runtime-flags.d.ts +38 -0
  50. package/dist/extraction/wasm-runtime-flags.d.ts.map +1 -0
  51. package/dist/extraction/wasm-runtime-flags.js +105 -0
  52. package/dist/extraction/wasm-runtime-flags.js.map +1 -0
  53. package/dist/graph/traversal.d.ts.map +1 -1
  54. package/dist/graph/traversal.js +71 -36
  55. package/dist/graph/traversal.js.map +1 -1
  56. package/dist/index.d.ts +11 -5
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +28 -18
  59. package/dist/index.js.map +1 -1
  60. package/dist/installer/config-writer.d.ts.map +1 -1
  61. package/dist/installer/config-writer.js +3 -1
  62. package/dist/installer/config-writer.js.map +1 -1
  63. package/dist/installer/index.d.ts +66 -2
  64. package/dist/installer/index.d.ts.map +1 -1
  65. package/dist/installer/index.js +195 -5
  66. package/dist/installer/index.js.map +1 -1
  67. package/dist/installer/instructions-template.d.ts +2 -2
  68. package/dist/installer/instructions-template.d.ts.map +1 -1
  69. package/dist/installer/instructions-template.js +4 -2
  70. package/dist/installer/instructions-template.js.map +1 -1
  71. package/dist/installer/targets/claude.d.ts +26 -6
  72. package/dist/installer/targets/claude.d.ts.map +1 -1
  73. package/dist/installer/targets/claude.js +165 -10
  74. package/dist/installer/targets/claude.js.map +1 -1
  75. package/dist/installer/targets/cursor.d.ts.map +1 -1
  76. package/dist/installer/targets/cursor.js +57 -3
  77. package/dist/installer/targets/cursor.js.map +1 -1
  78. package/dist/installer/targets/hermes.d.ts +18 -0
  79. package/dist/installer/targets/hermes.d.ts.map +1 -0
  80. package/dist/installer/targets/hermes.js +305 -0
  81. package/dist/installer/targets/hermes.js.map +1 -0
  82. package/dist/installer/targets/registry.d.ts.map +1 -1
  83. package/dist/installer/targets/registry.js +2 -0
  84. package/dist/installer/targets/registry.js.map +1 -1
  85. package/dist/installer/targets/types.d.ts +1 -1
  86. package/dist/installer/targets/types.d.ts.map +1 -1
  87. package/dist/mcp/index.d.ts +12 -0
  88. package/dist/mcp/index.d.ts.map +1 -1
  89. package/dist/mcp/index.js +213 -18
  90. package/dist/mcp/index.js.map +1 -1
  91. package/dist/mcp/server-instructions.d.ts +1 -1
  92. package/dist/mcp/server-instructions.d.ts.map +1 -1
  93. package/dist/mcp/server-instructions.js +15 -0
  94. package/dist/mcp/server-instructions.js.map +1 -1
  95. package/dist/mcp/tools.d.ts +25 -1
  96. package/dist/mcp/tools.d.ts.map +1 -1
  97. package/dist/mcp/tools.js +221 -30
  98. package/dist/mcp/tools.js.map +1 -1
  99. package/dist/mcp/transport.d.ts +17 -0
  100. package/dist/mcp/transport.d.ts.map +1 -1
  101. package/dist/mcp/transport.js +63 -0
  102. package/dist/mcp/transport.js.map +1 -1
  103. package/dist/resolution/frameworks/drupal.d.ts +51 -0
  104. package/dist/resolution/frameworks/drupal.d.ts.map +1 -0
  105. package/dist/resolution/frameworks/drupal.js +335 -0
  106. package/dist/resolution/frameworks/drupal.js.map +1 -0
  107. package/dist/resolution/frameworks/index.d.ts +2 -0
  108. package/dist/resolution/frameworks/index.d.ts.map +1 -1
  109. package/dist/resolution/frameworks/index.js +9 -1
  110. package/dist/resolution/frameworks/index.js.map +1 -1
  111. package/dist/resolution/frameworks/nestjs.d.ts +26 -0
  112. package/dist/resolution/frameworks/nestjs.d.ts.map +1 -0
  113. package/dist/resolution/frameworks/nestjs.js +374 -0
  114. package/dist/resolution/frameworks/nestjs.js.map +1 -0
  115. package/dist/resolution/index.d.ts.map +1 -1
  116. package/dist/resolution/index.js +40 -7
  117. package/dist/resolution/index.js.map +1 -1
  118. package/dist/resolution/lru-cache.d.ts +24 -0
  119. package/dist/resolution/lru-cache.d.ts.map +1 -0
  120. package/dist/resolution/lru-cache.js +62 -0
  121. package/dist/resolution/lru-cache.js.map +1 -0
  122. package/dist/sync/git-hooks.d.ts +45 -0
  123. package/dist/sync/git-hooks.d.ts.map +1 -0
  124. package/dist/sync/git-hooks.js +223 -0
  125. package/dist/sync/git-hooks.js.map +1 -0
  126. package/dist/sync/index.d.ts +4 -0
  127. package/dist/sync/index.d.ts.map +1 -1
  128. package/dist/sync/index.js +12 -1
  129. package/dist/sync/index.js.map +1 -1
  130. package/dist/sync/watch-policy.d.ts +48 -0
  131. package/dist/sync/watch-policy.d.ts.map +1 -0
  132. package/dist/sync/watch-policy.js +124 -0
  133. package/dist/sync/watch-policy.js.map +1 -0
  134. package/dist/sync/watcher.d.ts +2 -4
  135. package/dist/sync/watcher.d.ts.map +1 -1
  136. package/dist/sync/watcher.js +14 -6
  137. package/dist/sync/watcher.js.map +1 -1
  138. package/dist/types.d.ts +1 -1
  139. package/dist/types.d.ts.map +1 -1
  140. package/dist/types.js +11 -0
  141. package/dist/types.js.map +1 -1
  142. package/dist/utils.js +1 -1
  143. package/package.json +4 -4
  144. package/scripts/add-lang/bench.sh +60 -0
  145. package/scripts/add-lang/check-grammar.mjs +75 -0
  146. package/scripts/add-lang/dump-ast.mjs +103 -0
  147. package/scripts/add-lang/verify-extraction.mjs +70 -0
  148. package/scripts/agent-eval/audit.sh +68 -0
  149. package/scripts/agent-eval/itrun.sh +1 -1
  150. package/scripts/agent-eval/run-all.sh +67 -0
  151. package/scripts/build-bundle.sh +118 -0
  152. package/scripts/npm-shim.js +246 -0
  153. package/scripts/pack-npm.sh +95 -0
  154. package/scripts/patch-tree-sitter-dart.js +0 -112
  155. package/scripts/release.sh +0 -68
package/dist/mcp/index.js CHANGED
@@ -52,9 +52,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
52
52
  exports.ToolHandler = exports.tools = exports.StdioTransport = exports.MCPServer = void 0;
53
53
  const path = __importStar(require("path"));
54
54
  const index_1 = __importStar(require("../index"));
55
+ const sync_1 = require("../sync");
55
56
  const transport_1 = require("./transport");
56
57
  const tools_1 = require("./tools");
57
58
  const server_instructions_1 = require("./server-instructions");
59
+ const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
58
60
  /**
59
61
  * Convert a file:// URI to a filesystem path.
60
62
  * Handles URL encoding and Windows drive letter paths.
@@ -85,6 +87,74 @@ const SERVER_INFO = {
85
87
  * MCP Protocol Version
86
88
  */
87
89
  const PROTOCOL_VERSION = '2024-11-05';
90
+ /**
91
+ * How long to wait for the client's `roots/list` response before giving up
92
+ * and falling back to the process cwd.
93
+ */
94
+ const ROOTS_LIST_TIMEOUT_MS = 5000;
95
+ /**
96
+ * How often to poll `process.ppid` to detect parent process death (see #277).
97
+ * 5s is a deliberate trade-off: the failure mode being guarded against is rare
98
+ * (parent SIGKILL'd), and longer poll = less wakeup overhead while idle.
99
+ */
100
+ const DEFAULT_PPID_POLL_MS = 5000;
101
+ /**
102
+ * Resolve the PPID watchdog poll interval from an env override. A value of
103
+ * `0` disables the watchdog entirely (escape hatch for embedded scenarios
104
+ * where the parent legitimately re-parents the server on purpose). Anything
105
+ * non-numeric or negative falls back to the default.
106
+ */
107
+ function parsePpidPollMs(raw) {
108
+ if (raw === undefined || raw === '')
109
+ return DEFAULT_PPID_POLL_MS;
110
+ const parsed = Number(raw);
111
+ if (!Number.isFinite(parsed))
112
+ return DEFAULT_PPID_POLL_MS;
113
+ if (parsed < 0)
114
+ return DEFAULT_PPID_POLL_MS;
115
+ return Math.floor(parsed);
116
+ }
117
+ /**
118
+ * Parse the host PID propagated across the `--liftoff-only` re-exec
119
+ * ({@link HOST_PPID_ENV}). Returns a positive integer PID, or null when
120
+ * unset/invalid — the direct-launch path, where the watchdog falls back to
121
+ * `process.ppid` divergence. PIDs of 0/1 are rejected (0 = unknown, 1 = init,
122
+ * i.e. already orphaned), so the watchdog doesn't latch onto init.
123
+ */
124
+ function parseHostPpid(raw) {
125
+ if (raw === undefined || raw === '')
126
+ return null;
127
+ const parsed = Number(raw);
128
+ if (!Number.isInteger(parsed) || parsed <= 1)
129
+ return null;
130
+ return parsed;
131
+ }
132
+ /** True if a process with `pid` currently exists (signal-0 probe). */
133
+ function isProcessAlive(pid) {
134
+ try {
135
+ process.kill(pid, 0);
136
+ return true;
137
+ }
138
+ catch {
139
+ return false;
140
+ }
141
+ }
142
+ /**
143
+ * Extract the first usable filesystem path from a `roots/list` result.
144
+ * Shape per MCP spec: `{ roots: [{ uri: "file:///path", name?: string }] }`.
145
+ * Returns null if the result is empty or malformed.
146
+ */
147
+ function firstRootPath(result) {
148
+ if (!result || typeof result !== 'object')
149
+ return null;
150
+ const roots = result.roots;
151
+ if (!Array.isArray(roots) || roots.length === 0)
152
+ return null;
153
+ const first = roots[0];
154
+ if (typeof first?.uri !== 'string')
155
+ return null;
156
+ return fileUriToPath(first.uri);
157
+ }
88
158
  /**
89
159
  * MCP Server for CodeGraph
90
160
  *
@@ -99,6 +169,26 @@ class MCPServer {
99
169
  // In-flight background init kicked off from handleInitialize. Tracked so the
100
170
  // sync retry path doesn't race against it (double-opening the SQLite file).
101
171
  initPromise = null;
172
+ // Whether the client advertised the MCP `roots` capability during initialize.
173
+ // If so, and no explicit project path was given, we ask it for the workspace
174
+ // root via roots/list rather than guessing from the (often wrong) cwd.
175
+ clientSupportsRoots = false;
176
+ // Guards the one-shot deferred resolution (roots/list or cwd) so we don't
177
+ // re-issue roots/list on every tool call.
178
+ rootsAttempted = false;
179
+ // PPID watchdog — see start(). Captured at construction so we always have a
180
+ // baseline, even if start() runs after a fork-style reparent.
181
+ originalPpid = process.ppid;
182
+ // The MCP host's PID, propagated across the `--liftoff-only` re-exec (see
183
+ // HOST_PPID_ENV). When set, the watchdog polls it directly: the re-exec
184
+ // inserts an intermediate process whose *death* — not just our reparenting —
185
+ // is what we'd otherwise miss. null on the direct (bundled) launch path.
186
+ hostPpid = parseHostPpid(process.env[wasm_runtime_flags_1.HOST_PPID_ENV]);
187
+ ppidWatchdog = null;
188
+ // Idempotency guard for stop(). Without it, the watchdog can race with the
189
+ // stdin `end`/`close` handlers (or SIGTERM/SIGINT) and double-close cg and
190
+ // the transport before process.exit() lands.
191
+ stopped = false;
102
192
  constructor(projectPath) {
103
193
  this.projectPath = projectPath || null;
104
194
  this.transport = new transport_1.StdioTransport();
@@ -122,6 +212,35 @@ class MCPServer {
122
212
  // Detect this and shut down gracefully to prevent orphaned processes.
123
213
  process.stdin.on('end', () => this.stop());
124
214
  process.stdin.on('close', () => this.stop());
215
+ // PPID watchdog (#277). Linux doesn't propagate parent death to children,
216
+ // so when the MCP host (Claude Code, opencode, …) is SIGKILL'd by the OOM
217
+ // killer / a force-quit / a container teardown, the child is reparented to
218
+ // init/systemd and the stdin `end`/`close` events don't always fire. The
219
+ // server would then linger indefinitely, holding inotify watches, file
220
+ // descriptors, and the SQLite WAL. Poll `process.ppid` and shut down the
221
+ // moment it changes from what we observed at startup. Cross-platform:
222
+ // reparenting changes ppid on Linux *and* macOS; on Windows the value can
223
+ // also drop to 0 once the parent is gone. When the CLI re-execs itself for
224
+ // `--liftoff-only`, an intermediate process sits between us and the host and
225
+ // outlives it, so our own ppid wouldn't change — in that case we poll the
226
+ // host PID (propagated via HOST_PPID_ENV) for liveness instead. The watchdog
227
+ // is `.unref()`'d so it never holds the event loop open on its own.
228
+ const pollMs = parsePpidPollMs(process.env.CODEGRAPH_PPID_POLL_MS);
229
+ if (pollMs > 0) {
230
+ this.ppidWatchdog = setInterval(() => {
231
+ const current = process.ppid;
232
+ const ppidChanged = current !== this.originalPpid;
233
+ const hostGone = this.hostPpid !== null && !isProcessAlive(this.hostPpid);
234
+ if (ppidChanged || hostGone) {
235
+ const reason = ppidChanged
236
+ ? `ppid ${this.originalPpid} -> ${current}`
237
+ : `host pid ${this.hostPpid} exited`;
238
+ process.stderr.write(`[CodeGraph MCP] Parent process exited (${reason}); shutting down.\n`);
239
+ this.stop();
240
+ }
241
+ }, pollMs);
242
+ this.ppidWatchdog.unref();
243
+ }
125
244
  }
126
245
  /**
127
246
  * Try to initialize CodeGraph for the default project.
@@ -134,6 +253,8 @@ class MCPServer {
134
253
  * are still possible.
135
254
  */
136
255
  async tryInitializeDefault(projectPath) {
256
+ // Record where we searched so a later "not initialized" error can name it.
257
+ this.toolHandler.setDefaultProjectHint(projectPath);
137
258
  // Walk up parent directories to find nearest .codegraph/
138
259
  const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(projectPath);
139
260
  if (!resolvedRoot) {
@@ -172,10 +293,28 @@ class MCPServer {
172
293
  // Already initialized successfully
173
294
  if (this.toolHandler.hasDefaultCodeGraph())
174
295
  return;
175
- // No project path to retry with
176
- if (!this.projectPath)
177
- return;
178
- const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(this.projectPath);
296
+ // No explicit path was given at initialize. Resolve it now, exactly once:
297
+ // ask the client via roots/list (if it advertised roots), else use cwd.
298
+ // Deferring to here lets a roots answer override the wrong cwd, and the
299
+ // one-shot guard means we never re-issue roots/list per tool call.
300
+ if (!this.projectPath && !this.rootsAttempted) {
301
+ this.rootsAttempted = true;
302
+ this.initPromise = (this.clientSupportsRoots
303
+ ? this.initFromRoots()
304
+ : this.tryInitializeDefault(process.cwd())).finally(() => { this.initPromise = null; });
305
+ try {
306
+ await this.initPromise;
307
+ }
308
+ catch { /* fall through to last-resort below */ }
309
+ if (this.toolHandler.hasDefaultCodeGraph())
310
+ return;
311
+ }
312
+ // Last resort: re-walk from the best candidate we have. Picks up projects
313
+ // initialized after the server started, and covers clients that sent no
314
+ // usable initialize signal at all.
315
+ const candidate = this.projectPath ?? process.cwd();
316
+ this.toolHandler.setDefaultProjectHint(candidate);
317
+ const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(candidate);
179
318
  if (!resolvedRoot)
180
319
  return;
181
320
  try {
@@ -196,6 +335,29 @@ class MCPServer {
196
335
  // Still failing — will retry on next tool call
197
336
  }
198
337
  }
338
+ /**
339
+ * Resolve the project root via the MCP `roots/list` request and initialize
340
+ * from the first root the client reports. Falls back to the process cwd if
341
+ * the client returns no usable root or doesn't answer in time. See issue #196.
342
+ */
343
+ async initFromRoots() {
344
+ let target = process.cwd();
345
+ try {
346
+ const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
347
+ const rootPath = firstRootPath(result);
348
+ if (rootPath) {
349
+ target = rootPath;
350
+ }
351
+ else {
352
+ process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
353
+ }
354
+ }
355
+ catch (err) {
356
+ const msg = err instanceof Error ? err.message : String(err);
357
+ process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
358
+ }
359
+ await this.tryInitializeDefault(target);
360
+ }
199
361
  /**
200
362
  * Start file watching on the active CodeGraph instance.
201
363
  * Logs sync activity to stderr for diagnostics.
@@ -203,6 +365,15 @@ class MCPServer {
203
365
  startWatching() {
204
366
  if (!this.cg)
205
367
  return;
368
+ // When the watcher is intentionally disabled (e.g. WSL2 /mnt drives, or
369
+ // CODEGRAPH_NO_WATCH=1), say so explicitly and tell the user how to keep
370
+ // the graph fresh — otherwise the silent staleness is hard to diagnose.
371
+ const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
372
+ if (disabledReason) {
373
+ process.stderr.write(`[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
374
+ `The graph will not auto-update; run \`codegraph sync\` (or install the git sync hooks via \`codegraph init\`) to refresh.\n`);
375
+ return;
376
+ }
206
377
  const started = this.cg.watch({
207
378
  onSyncComplete: (result) => {
208
379
  if (result.filesChanged > 0) {
@@ -216,11 +387,22 @@ class MCPServer {
216
387
  if (started) {
217
388
  process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
218
389
  }
390
+ else {
391
+ // start() can also return false when recursive fs.watch isn't supported.
392
+ process.stderr.write('[CodeGraph MCP] File watcher unavailable on this platform — run `codegraph sync` to refresh the graph after changes.\n');
393
+ }
219
394
  }
220
395
  /**
221
396
  * Stop the server
222
397
  */
223
398
  stop() {
399
+ if (this.stopped)
400
+ return;
401
+ this.stopped = true;
402
+ if (this.ppidWatchdog) {
403
+ clearInterval(this.ppidWatchdog);
404
+ this.ppidWatchdog = null;
405
+ }
224
406
  // Close all cached cross-project connections first
225
407
  this.toolHandler.closeAll();
226
408
  // Close the main CodeGraph instance
@@ -273,17 +455,23 @@ class MCPServer {
273
455
  */
274
456
  async handleInitialize(request) {
275
457
  const params = request.params;
276
- // Extract project path from rootUri or workspaceFolders
277
- let projectPath = this.projectPath;
458
+ // Does the client support the MCP `roots` protocol? If so, and we have no
459
+ // explicit path, we ask it for the workspace root after the handshake
460
+ // instead of falling back to the (frequently wrong) cwd. See issue #196.
461
+ this.clientSupportsRoots = !!params?.capabilities?.roots;
462
+ // Explicit project signal, strongest first: a client-provided rootUri /
463
+ // workspaceFolders (LSP-style, non-standard but some clients send it), else
464
+ // the --path the server was launched with. cwd is NOT used here — we defer
465
+ // it so a roots/list answer can win over it.
466
+ let explicitPath = null;
278
467
  if (params?.rootUri) {
279
- projectPath = fileUriToPath(params.rootUri);
468
+ explicitPath = fileUriToPath(params.rootUri);
280
469
  }
281
470
  else if (params?.workspaceFolders?.[0]?.uri) {
282
- projectPath = fileUriToPath(params.workspaceFolders[0].uri);
471
+ explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
283
472
  }
284
- // Fall back to current working directory if no path provided
285
- if (!projectPath) {
286
- projectPath = process.cwd();
473
+ else if (this.projectPath) {
474
+ explicitPath = this.projectPath;
287
475
  }
288
476
  // Respond to the handshake BEFORE doing any heavy initialization. Loading
289
477
  // the SQLite DB and the tree-sitter WASM runtime can take many seconds on
@@ -304,13 +492,20 @@ class MCPServer {
304
492
  serverInfo: SERVER_INFO,
305
493
  instructions: server_instructions_1.SERVER_INSTRUCTIONS,
306
494
  });
307
- // Kick off the default-project init in the background. Tool calls that
308
- // arrive before it finishes will see the "not initialized yet" path and
309
- // fall through to `retryInitIfNeeded`, which now waits for this promise
310
- // rather than racing against it with a second open.
311
- this.initPromise = this.tryInitializeDefault(projectPath).finally(() => {
312
- this.initPromise = null;
313
- });
495
+ // If we know the project dir, kick off init in the background now. Tool
496
+ // calls that arrive before it finishes fall through to `retryInitIfNeeded`,
497
+ // which waits for this promise rather than racing it with a second open.
498
+ //
499
+ // If we DON'T know it (no rootUri, no --path), defer: the first tool call
500
+ // resolves it via roots/list (when the client supports roots) or cwd. This
501
+ // is the fix for issue #196 — clients that launch the server outside the
502
+ // project and don't pass a rootUri previously got a misleading "not
503
+ // initialized" error on every call.
504
+ if (explicitPath) {
505
+ this.initPromise = this.tryInitializeDefault(explicitPath).finally(() => {
506
+ this.initPromise = null;
507
+ });
508
+ }
314
509
  }
315
510
  /**
316
511
  * Handle tools/list request
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"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"}
@@ -15,5 +15,5 @@
15
15
  * burn tokens. Reference only tools that exist on `main`; gate any
16
16
  * conditional tools behind feature checks if/when they ship.
17
17
  */
18
- export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Tool selection by intent\n\n- **\"How does X work? / trace X end to end / explain the Y system / architecture?\"** \u2192 `codegraph_explore` (PRIMARY for understanding \u2014 seed it with the key symbol names, read its output, don't grep+Read your way there)\n- **\"What is the symbol named X? / where is X defined?\"** \u2192 `codegraph_search` (pinpoint lookups)\n- **\"What's the deal with this task / feature / area?\"** \u2192 `codegraph_context` (lighter composed view of search + node + callers + callees)\n- **\"What calls this?\"** \u2192 `codegraph_callers`\n- **\"What does this call?\"** \u2192 `codegraph_callees`\n- **\"What would changing this break?\"** \u2192 `codegraph_impact`\n- **\"Show me this symbol's source / signature / docstring.\"** \u2192 `codegraph_node`\n- **\"What's in directory X?\"** \u2192 `codegraph_files`\n- **\"Is the index ready / what's its size?\"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Understanding / onboarding**: feed `codegraph_explore` the key symbol/file names and read its output (line-numbered source from many files in one call). If the question names nothing concrete, do ONE quick `codegraph_search` / `codegraph_context` to surface the names, then explore with them. Fill remaining gaps with `codegraph_node` / Read \u2014 don't drop back to grep+Read for the whole topic.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Don't search-then-Read your way through an understanding question** \u2014 feed the names you find into `codegraph_explore` instead of Reading the files one by one; it does that whole loop in one call and returns line numbers you can cite directly.\n- **Don't grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don't reach for `codegraph_explore` on a pinpoint \"where is X defined\" lookup** \u2014 `codegraph_search` is one cheap call.\n- **Don't query the index immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync. Wait for the next turn.\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
18
+ export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don't delegate exploration\n\nFor \"how does X work\", architecture, trace, or where-is-X questions,\nanswer DIRECTLY using 2-3 codegraph calls: `codegraph_context` first,\nthen ONE `codegraph_explore` for the source of the symbols it surfaces.\nCodegraph IS the pre-built search index \u2014 so delegating the lookup to a\nseparate file-reading sub-task/agent, or running your own grep + read\nloop, repeats work codegraph already did and costs more for the same\nanswer. Reach for raw Read/Grep only to confirm a specific detail\ncodegraph didn't cover. A direct codegraph answer is typically a handful\nof calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **\"How does X work? / trace X end to end / explain the Y system / architecture?\"** \u2192 `codegraph_explore` (PRIMARY for understanding \u2014 seed it with the key symbol names, read its output, don't grep+Read your way there)\n- **\"What is the symbol named X? / where is X defined?\"** \u2192 `codegraph_search` (pinpoint lookups)\n- **\"What's the deal with this task / feature / area?\"** \u2192 `codegraph_context` (lighter composed view of search + node + callers + callees)\n- **\"What calls this?\"** \u2192 `codegraph_callers`\n- **\"What does this call?\"** \u2192 `codegraph_callees`\n- **\"What would changing this break?\"** \u2192 `codegraph_impact`\n- **\"Show me this symbol's source / signature / docstring.\"** \u2192 `codegraph_node`\n- **\"Show me several related symbols' source / survey an area.\"** \u2192 `codegraph_explore` (ONE capped call; prefer over many codegraph_node/Read)\n- **\"What's in directory X?\"** \u2192 `codegraph_files`\n- **\"Is the index ready / what's its size?\"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Understanding / onboarding**: feed `codegraph_explore` the key symbol/file names and read its output (line-numbered source from many files in one call). If the question names nothing concrete, do ONE quick `codegraph_search` / `codegraph_context` to surface the names, then explore with them. Fill remaining gaps with `codegraph_node` / Read \u2014 don't drop back to grep+Read for the whole topic.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Don't search-then-Read your way through an understanding question** \u2014 feed the names you find into `codegraph_explore` instead of Reading the files one by one; it does that whole loop in one call and returns line numbers you can cite directly.\n- **Don't grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don't reach for `codegraph_explore` on a pinpoint \"where is X defined\" lookup** \u2014 `codegraph_search` is one cheap call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one round-trip.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use `codegraph_node` for a single symbol.\n- **Don't query the index immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync. Wait for the next turn.\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
19
19
  //# sourceMappingURL=server-instructions.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,07FAqC/B,CAAC"}
1
+ {"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,ymIAoD/B,CAAC"}
@@ -25,6 +25,18 @@ in the workspace. Reads are sub-millisecond; the index lags writes by
25
25
  about a second through the file watcher. Consult it BEFORE writing or
26
26
  editing code, not during.
27
27
 
28
+ ## Answer directly — don't delegate exploration
29
+
30
+ For "how does X work", architecture, trace, or where-is-X questions,
31
+ answer DIRECTLY using 2-3 codegraph calls: \`codegraph_context\` first,
32
+ then ONE \`codegraph_explore\` for the source of the symbols it surfaces.
33
+ Codegraph IS the pre-built search index — so delegating the lookup to a
34
+ separate file-reading sub-task/agent, or running your own grep + read
35
+ loop, repeats work codegraph already did and costs more for the same
36
+ answer. Reach for raw Read/Grep only to confirm a specific detail
37
+ codegraph didn't cover. A direct codegraph answer is typically a handful
38
+ of calls; a grep/read exploration is dozens.
39
+
28
40
  ## Tool selection by intent
29
41
 
30
42
  - **"How does X work? / trace X end to end / explain the Y system / architecture?"** → \`codegraph_explore\` (PRIMARY for understanding — seed it with the key symbol names, read its output, don't grep+Read your way there)
@@ -34,6 +46,7 @@ editing code, not during.
34
46
  - **"What does this call?"** → \`codegraph_callees\`
35
47
  - **"What would changing this break?"** → \`codegraph_impact\`
36
48
  - **"Show me this symbol's source / signature / docstring."** → \`codegraph_node\`
49
+ - **"Show me several related symbols' source / survey an area."** → \`codegraph_explore\` (ONE capped call; prefer over many codegraph_node/Read)
37
50
  - **"What's in directory X?"** → \`codegraph_files\`
38
51
  - **"Is the index ready / what's its size?"** → \`codegraph_status\`
39
52
 
@@ -48,6 +61,8 @@ editing code, not during.
48
61
  - **Don't search-then-Read your way through an understanding question** — feed the names you find into \`codegraph_explore\` instead of Reading the files one by one; it does that whole loop in one call and returns line numbers you can cite directly.
49
62
  - **Don't grep first** when looking up a symbol by name — \`codegraph_search\` is faster and returns kind + location + signature.
50
63
  - **Don't reach for \`codegraph_explore\` on a pinpoint "where is X defined" lookup** — \`codegraph_search\` is one cheap call.
64
+ - **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one round-trip.
65
+ - **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use \`codegraph_node\` for a single symbol.
51
66
  - **Don't query the index immediately after editing a file** — the watcher needs ~500ms to debounce + sync. Wait for the next turn.
52
67
 
53
68
  ## Limitations
@@ -1 +1 @@
1
- {"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqClC,CAAC"}
1
+ {"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDlC,CAAC"}
@@ -97,11 +97,17 @@ export declare const tools: ToolDefinition[];
97
97
  export declare class ToolHandler {
98
98
  private cg;
99
99
  private projectCache;
100
+ private defaultProjectHint;
100
101
  constructor(cg: CodeGraph | null);
101
102
  /**
102
103
  * Update the default CodeGraph instance (e.g. after lazy initialization)
103
104
  */
104
105
  setDefaultCodeGraph(cg: CodeGraph): void;
106
+ /**
107
+ * Record the directory the server tried to resolve the default project from.
108
+ * Used only to make the "no default project" error actionable.
109
+ */
110
+ setDefaultProjectHint(searchedPath: string): void;
105
111
  /**
106
112
  * Whether a default CodeGraph instance is available
107
113
  */
@@ -127,9 +133,19 @@ export declare class ToolHandler {
127
133
  */
128
134
  closeAll(): void;
129
135
  /**
130
- * Validate that a value is a non-empty string
136
+ * Validate that a value is a non-empty string within length bounds.
137
+ *
138
+ * The `maxLength` cap protects against MCP clients that ship huge
139
+ * payloads (10MB+ query strings either by accident or maliciously).
140
+ * Without this, a single oversized input can pin the FTS5 index or
141
+ * exhaust memory before any real work runs.
131
142
  */
132
143
  private validateString;
144
+ /**
145
+ * Validate an optional path-like string input. Returns the value if
146
+ * valid (or undefined), or a ToolResult with the error.
147
+ */
148
+ private validateOptionalPath;
133
149
  /**
134
150
  * Execute a tool by name
135
151
  */
@@ -234,6 +250,14 @@ export declare class ToolHandler {
234
250
  private formatSearchResults;
235
251
  private formatNodeList;
236
252
  private formatImpact;
253
+ /**
254
+ * Build a compact structural outline of a container symbol from its
255
+ * indexed children (methods, fields, properties, …) — name, kind,
256
+ * line number, and signature — so the agent gets the shape of a class
257
+ * without the full source of every method. Returns '' when the container
258
+ * has no indexed children, so the caller can fall back to full source.
259
+ */
260
+ private buildContainerOutline;
237
261
  private formatNodeDetails;
238
262
  private formatTaskContext;
239
263
  private textResult;
@@ -1 +1 @@
1
- {"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAuC,MAAM,UAAU,CAAC;AA2B/D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,2BAA2B,EAAE,MAAM,CAAC;IACpC,2CAA2C;IAC3C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,yEAAyE;IACzE,sBAAsB,EAAE,OAAO,CAAC;IAChC,sEAAsE;IACtE,yBAAyB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAuD7E;AAgDD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,cAAc,EAkMjC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,YAAY,CAAqC;gBAErC,EAAE,EAAE,SAAS,GAAG,IAAI;IAExC;;OAEG;IACH,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;;;OAIG;IACH,QAAQ,IAAI,cAAc,EAAE;IAqB5B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAqCpB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAOhB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BnF;;OAEG;YACW,YAAY;IAsB1B;;OAEG;YACW,aAAa;IAmC3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;YACW,aAAa;IAgC3B;;OAEG;YACW,aAAa;IAgC3B;;OAEG;YACW,YAAY;IAyC1B;;;;;;;;;;OAUG;YACW,aAAa;IA2a3B;;OAEG;YACW,UAAU;IAuBxB;;OAEG;YACW,YAAY;IA4C1B;;OAEG;YACW,WAAW;IAgDzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAcvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IA4EvB;;;OAGG;IACH;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;IAqCrB,OAAO,CAAC,UAAU;IA4ClB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA6BtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;CAMpB"}
1
+ {"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}