@stupidloud/codegraph 0.7.20 → 0.9.5

package/dist/mcp/tools.js

@@ -47,9 +47,22 @@ const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const os_1 = require("os");
 const path_1 = require("path");
-const db_1 = require("../db");
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
+/**
+ * Maximum length for free-form string inputs (query, task, symbol).
+ * Bounds memory and CPU when a buggy or hostile MCP client sends a
+ * huge payload — without this an attacker could ship a 100MB string
+ * and force a full FTS5 scan / OOM the server. 10 000 characters is
+ * far beyond any realistic legitimate query.
+ */
+const MAX_INPUT_LENGTH = 10_000;
+/**
+ * Maximum length for path-like string inputs (projectPath, path
+ * filter, glob pattern). Paths beyond a few thousand chars are
+ * never legitimate and signal abuse or a bug upstream.
+ */
+const MAX_PATH_LENGTH = 4_096;
 /**
  * Rust path roots that have no file-system equivalent — `crate` is the
  * current crate, `super` is the parent module, `self` is the current
@@ -58,6 +71,15 @@ const MAX_OUTPUT_LENGTH = 15000;
  * same as `configurator::stage_apply::run`.
  */
 const RUST_PATH_PREFIXES = new Set(['crate', 'super', 'self']);
+/**
+ * Node kinds that contain other symbols. For these, `codegraph_node` with
+ * `includeCode=true` returns a structural outline (member names + signatures
+ * + line numbers) instead of the full body, which for a large class is a
+ * multi-thousand-character wall of source that bloats the agent's context.
+ */
+const CONTAINER_NODE_KINDS = new Set([
+    'class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'namespace', 'module',
+]);
 /** Last `::` / `.` / `/`-separated segment of a qualified symbol. */
 function lastQualifierPart(symbol) {
     const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
@@ -96,12 +118,12 @@ function getExploreOutputBudget(fileCount) {
     }
     if (fileCount < 5000) {
         return {
-            maxOutputChars: 28000,
-            defaultMaxFiles: 9,
-            maxCharsPerFile: 5000,
-            gapThreshold: 12,
-            maxSymbolsInFileHeader: 10,
-            maxEdgesPerRelationshipKind: 10,
+            maxOutputChars: 13000,
+            defaultMaxFiles: 6,
+            maxCharsPerFile: 2500,
+            gapThreshold: 10,
+            maxSymbolsInFileHeader: 8,
+            maxEdgesPerRelationshipKind: 8,
             includeRelationships: true,
             includeAdditionalFiles: true,
             includeCompletenessSignal: true,
@@ -168,15 +190,50 @@ function numberSourceLines(slice, firstLineNumber) {
 /**
  * Mark a Claude session as having consulted MCP tools.
  * This enables Grep/Glob/Bash commands that would otherwise be blocked.
+ *
+ * Why the explicit openSync + O_NOFOLLOW dance instead of plain writeFileSync:
+ * tmpdir() is world-writable on Linux (mode 1777), so on a shared multi-user
+ * machine any other local user can pre-create `codegraph-consulted-<hash>` as
+ * a symlink pointing at a file the victim owns. The old `writeFileSync` would
+ * happily follow that link and overwrite the target's contents with the ISO
+ * timestamp string (CWE-59). The session-id hash provides the predictability
+ * gate, but it's defense-in-depth: if a session id ever surfaces in logs,
+ * argv, or telemetry the attack becomes trivial, and the right fix is to not
+ * follow links from /tmp paths in the first place.
  */
 function markSessionConsulted(sessionId) {
     try {
         const hash = (0, crypto_1.createHash)('md5').update(sessionId).digest('hex').slice(0, 16);
         const markerPath = (0, path_1.join)((0, os_1.tmpdir)(), `codegraph-consulted-${hash}`);
-        (0, fs_1.writeFileSync)(markerPath, new Date().toISOString(), 'utf8');
+        // Refuse to follow a pre-planted symlink at the marker path (CWE-59).
+        // O_NOFOLLOW (below) is the atomic, TOCTOU-free guard on POSIX, but it is
+        // `undefined` on Windows (libuv ignores it), so the bitwise-OR silently
+        // drops it and openSync would follow the link. This lstat check closes that
+        // gap cross-platform; ENOENT (path is free) falls through to create it.
+        try {
+            if ((0, fs_1.lstatSync)(markerPath).isSymbolicLink())
+                return;
+        }
+        catch {
+            // No existing entry (or stat failed) — nothing to refuse; proceed.
+        }
+        // O_NOFOLLOW makes openSync throw ELOOP if markerPath is already a symlink.
+        // O_CREAT + O_TRUNC keep the original "create-or-overwrite" semantics, and
+        // mode 0o600 prevents readback by other local users (the marker payload is
+        // benign, but narrowing the exposure costs nothing).
+        const flags = fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_TRUNC | fs_1.constants.O_NOFOLLOW;
+        const fd = (0, fs_1.openSync)(markerPath, flags, 0o600);
+        try {
+            (0, fs_1.writeSync)(fd, new Date().toISOString());
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
     }
     catch {
-        // Silently fail - don't break MCP on marker write failure
+        // Silently fail - don't break MCP on marker write failure. ELOOP from a
+        // planted symlink lands here too, which is the intended behavior: refuse
+        // to write rather than overwrite an attacker-chosen target.
     }
 }
 /**
@@ -222,7 +279,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_context',
-        description: 'PRIMARY TOOL: Build comprehensive context for a task. Returns entry points, related symbols, and key code - often enough to understand the codebase without additional tool calls. NOTE: This provides CODE context, not product requirements. For new features, still clarify UX/behavior questions with the user before implementing.',
+        description: 'PRIMARY TOOL — call this FIRST for any "how does X work", architecture, feature, or bug-context question. Composes search + node + callers + callees and returns entry points, related symbols, and key code in ONE call — usually enough to answer with no further search/Read/Grep. Prefer this over chaining codegraph_search + codegraph_node, and over codegraph_explore. NOTE: provides CODE context, not product requirements; for new features still clarify UX/edge cases with the user.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -307,7 +364,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_node',
-        description: 'Get detailed information about a specific code symbol. Use includeCode=true only when you need the full source code - otherwise just get location and signature to minimize context usage.',
+        description: 'Get detailed info about ONE symbol (location, signature, docstring). Pass includeCode=true for source: a function/method returns its body; a class/interface/struct/enum returns a compact member OUTLINE (fields + method signatures + line numbers), not every method body — Read or codegraph_node a specific member for its body. Keep includeCode=false to minimize context. For SEVERAL related symbols, make ONE codegraph_explore (or codegraph_context) call instead of many node calls — repeated node calls each re-read the whole context and cost far more.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -327,7 +384,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_explore',
-        description: 'PRIMARY TOOL for understanding questions — "how does X work", "trace X end to end", "explain the Y system", architecture/onboarding. Returns comprehensive context in a SINGLE call: relevant source grouped by file (contiguous, line-numbered sections, not snippets) + a relationship map + deep graph traversal. It REPLACES the grep+Read exploration loop: feed it the key symbol/file names and read its output — do NOT Read the files one by one. It works best when your query names the relevant symbols (e.g. "readAgentsFromDirectory createClaudeSession chat-manager agents.ts"); if the question is a plain sentence that names nothing concrete, do ONE quick codegraph_search or codegraph_context to surface the names, then call this with them. After exploring, use codegraph_node / Read only to fill specific gaps it did not cover. Prefer codegraph_search over this only for a pinpoint "where is X defined" lookup.',
+        description: 'PRIMARY TOOL for understanding questions and inspecting SEVERAL related symbols in ONE capped call. Returns relevant source grouped by file (contiguous, line-numbered sections) plus a relationship map. Use it after codegraph_context when you need actual source for the surfaced symbols, or query it directly with specific symbol/file/code terms. Strongly prefer it over many codegraph_node or Read calls. For a pinpoint "where is X defined" lookup, use codegraph_search instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -399,6 +456,9 @@ class ToolHandler {
     cg;
     // Cache of opened CodeGraph instances for cross-project queries
     projectCache = new Map();
+    // The directory the server last searched for a default project. Surfaced in
+    // the "not initialized" error so users can see why detection missed.
+    defaultProjectHint = null;
     constructor(cg) {
         this.cg = cg;
     }
@@ -408,6 +468,13 @@ class ToolHandler {
     setDefaultCodeGraph(cg) {
         this.cg = cg;
     }
+    /**
+     * Record the directory the server tried to resolve the default project from.
+     * Used only to make the "no default project" error actionable.
+     */
+    setDefaultProjectHint(searchedPath) {
+        this.defaultProjectHint = searchedPath;
+    }
     /**
      * Whether a default CodeGraph instance is available
      */
@@ -451,7 +518,14 @@ class ToolHandler {
     getCodeGraph(projectPath) {
         if (!projectPath) {
             if (!this.cg) {
-                throw new Error('CodeGraph not initialized for this project. Run \'codegraph init\' first.');
+                const searched = this.defaultProjectHint ?? process.cwd();
+                throw new Error('No CodeGraph project is loaded for this session.\n' +
+                    `Searched for a .codegraph/ directory starting from: ${searched}\n` +
+                    'The index is likely fine — this is a working-directory detection issue: ' +
+                    "the MCP client launched the server outside your project and didn't report the " +
+                    'workspace root. Fix it either way:\n' +
+                    '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project"\n' +
+                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]');
             }
             return this.cg;
         }
@@ -459,11 +533,32 @@ class ToolHandler {
         if (this.projectCache.has(projectPath)) {
             return this.projectCache.get(projectPath);
         }
+        // Reject sensitive system directories before opening. Only validate a
+        // path that actually exists — a nested or not-yet-created sub-path of a
+        // real project must still be allowed to resolve UP to its .codegraph/
+        // root below (issue #238), so we don't run the existence-checking
+        // validator on paths that are meant to walk up.
+        if ((0, fs_1.existsSync)(projectPath)) {
+            const pathError = (0, utils_1.validateProjectPath)(projectPath);
+            if (pathError) {
+                throw new Error(pathError);
+            }
+        }
         // Walk up parent directories to find nearest .codegraph/
         const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(projectPath);
         if (!resolvedRoot) {
             throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);
         }
+        // If the path resolves to the default project, reuse the already-open
+        // default instance rather than opening a SECOND connection to the same DB.
+        // A duplicate connection serializes reads against the watcher's auto-sync
+        // writes; on the wasm backend (no WAL) that surfaces as intermittent
+        // "database is locked" on concurrent tool calls. See issue #238. Deliberately
+        // not cached under projectPath — the server owns and closes the default
+        // instance, so routing it through projectCache.closeAll() would double-close it.
+        if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
+            return this.cg;
+        }
         // Check if we already have this resolved root cached (different path, same project)
         if (this.projectCache.has(resolvedRoot)) {
             const cg = this.projectCache.get(resolvedRoot);
@@ -489,12 +584,35 @@ class ToolHandler {
         this.projectCache.clear();
     }
     /**
-     * Validate that a value is a non-empty string
+     * Validate that a value is a non-empty string within length bounds.
+     *
+     * The `maxLength` cap protects against MCP clients that ship huge
+     * payloads (10MB+ query strings either by accident or maliciously).
+     * Without this, a single oversized input can pin the FTS5 index or
+     * exhaust memory before any real work runs.
      */
-    validateString(value, name) {
+    validateString(value, name, maxLength = MAX_INPUT_LENGTH) {
         if (typeof value !== 'string' || value.length === 0) {
             return this.errorResult(`${name} must be a non-empty string`);
         }
+        if (value.length > maxLength) {
+            return this.errorResult(`${name} exceeds maximum length of ${maxLength} characters (got ${value.length})`);
+        }
+        return value;
+    }
+    /**
+     * Validate an optional path-like string input. Returns the value if
+     * valid (or undefined), or a ToolResult with the error.
+     */
+    validateOptionalPath(value, name) {
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof value !== 'string') {
+            return this.errorResult(`${name} must be a string`);
+        }
+        if (value.length > MAX_PATH_LENGTH) {
+            return this.errorResult(`${name} exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length})`);
+        }
         return value;
     }
     /**
@@ -502,6 +620,26 @@ class ToolHandler {
      */
     async execute(toolName, args) {
         try {
+            // Cross-cutting input validation. All tools accept an optional
+            // `projectPath` and most accept either `query`, `task`, or
+            // `symbol` — bound their lengths centrally so individual handlers
+            // can stay focused on tool-specific logic.
+            const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath');
+            if (typeof pathCheck === 'object' && pathCheck !== undefined) {
+                return pathCheck;
+            }
+            // The `path` and `pattern` properties used by codegraph_files are
+            // also path-shaped — apply the same cap.
+            if (args.path !== undefined) {
+                const check = this.validateOptionalPath(args.path, 'path');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
+            if (args.pattern !== undefined) {
+                const check = this.validateOptionalPath(args.pattern, 'pattern');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
             switch (toolName) {
                 case 'codegraph_search':
                     return await this.handleSearch(args);
@@ -577,10 +715,10 @@ class ToolHandler {
             : '';
         // buildContext returns string when format is 'markdown'
         if (typeof context === 'string') {
-            return this.textResult(context + reminder);
+            return this.textResult(this.truncateOutput(context + reminder));
         }
         // If it returns TaskContext, format it
-        return this.textResult(this.formatTaskContext(context) + reminder);
+        return this.textResult(this.truncateOutput(this.formatTaskContext(context) + reminder));
     }
     /**
      * Heuristic to detect if a query looks like a feature request
@@ -1123,7 +1261,20 @@ class ToolHandler {
                 // Stats unavailable — skip budget note
             }
         }
-        return this.textResult(lines.join('\n'));
+        // Hard-cap to the adaptive budget. The per-file loop bounds the source
+        // sections, but the relationship map, additional-files list, and
+        // completeness/budget notes can still push the assembled output past
+        // maxOutputChars (observed 30k against a 28k tier cap). A fat explore
+        // payload persists in the agent's context and is re-read as cache-input
+        // on every subsequent turn, so the overrun is paid many times over.
+        const output = lines.join('\n');
+        if (output.length > budget.maxOutputChars) {
+            const cut = output.slice(0, budget.maxOutputChars);
+            const lastNewline = cut.lastIndexOf('\n');
+            const safe = lastNewline > budget.maxOutputChars * 0.8 ? cut.slice(0, lastNewline) : cut;
+            return this.textResult(safe + '\n\n... (explore output truncated to budget — use codegraph_node or Read for more)');
+        }
+        return this.textResult(output);
     }
     /**
      * Handle codegraph_node
@@ -1140,10 +1291,22 @@ class ToolHandler {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
         let code = null;
+        let outline = null;
         if (includeCode) {
-            code = await cg.getCode(match.node.id);
+            // For container symbols (class/interface/struct/…), the full body is the
+            // sum of every method body — a wall of source (e.g. a 10k-char class)
+            // that bloats context and is rarely needed in full. Return a structural
+            // outline (members + signatures + line numbers) instead; the agent can
+            // Read or codegraph_node a specific method for its body. Leaf symbols
+            // (function/method/etc.) return their full body as before.
+            if (CONTAINER_NODE_KINDS.has(match.node.kind)) {
+                outline = this.buildContainerOutline(cg, match.node);
+            }
+            if (!outline) {
+                code = await cg.getCode(match.node.id);
+            }
         }
-        const formatted = this.formatNodeDetails(match.node, code) + match.note;
+        const formatted = this.formatNodeDetails(match.node, code, outline) + match.note;
         return this.textResult(this.truncateOutput(formatted));
     }
     /**
@@ -1160,16 +1323,20 @@ class ToolHandler {
             `**Total edges:** ${stats.edgeCount}`,
             `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`,
         ];
-        // Surface the active SQLite backend. Without this, users on the
-        // silent WASM fallback (better-sqlite3 install failed) see "slow"
-        // indexing and DB-lock errors with no signal of why.
-        const backend = cg.getBackend();
-        if (backend === 'native') {
-            lines.push(`**Backend:** native (better-sqlite3)`);
+        // Surface the active SQLite backend (node:sqlite, Node's built-in real
+        // SQLite — full WAL + FTS5, no native build).
+        lines.push(`**Backend:** node:sqlite (Node built-in) — full WAL + FTS5`);
+        // Effective journal mode. 'wal' ⇒ concurrent reads never block on a writer;
+        // anything else ⇒ they can ("database is locked"). node:sqlite supports WAL
+        // everywhere, so a non-wal mode means the filesystem can't (network/
+        // virtualized mounts, WSL2 /mnt). See issue #238.
+        const journalMode = cg.getJournalMode();
+        if (journalMode === 'wal') {
+            lines.push(`**Journal mode:** wal (concurrent reads safe)`);
         }
         else {
-            lines.push(`**Backend:** ⚠ wasm (better-sqlite3 unavailable) — ` +
-                `5-10x slower than native. Fix: ${db_1.WASM_FALLBACK_FIX_RECIPE}`);
+            lines.push(`**Journal mode:** ⚠ ${journalMode || 'unknown'} — WAL not active, so reads ` +
+                `can block on a concurrent write (WAL appears unsupported on this filesystem)`);
         }
         lines.push('', '### Nodes by Kind:');
         for (const [kind, count] of Object.entries(stats.nodesByKind)) {
@@ -1520,7 +1687,28 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
-    formatNodeDetails(node, code) {
+    /**
+     * Build a compact structural outline of a container symbol from its
+     * indexed children (methods, fields, properties, …) — name, kind,
+     * line number, and signature — so the agent gets the shape of a class
+     * without the full source of every method. Returns '' when the container
+     * has no indexed children, so the caller can fall back to full source.
+     */
+    buildContainerOutline(cg, node) {
+        const children = cg.getChildren(node.id)
+            .filter(c => c.kind !== 'import' && c.kind !== 'export')
+            .sort((a, b) => (a.startLine ?? 0) - (b.startLine ?? 0));
+        if (children.length === 0)
+            return '';
+        const lines = [`**Members (${children.length}):**`, ''];
+        for (const c of children) {
+            const loc = c.startLine ? `:${c.startLine}` : '';
+            const sig = c.signature ? ` — \`${c.signature}\`` : '';
+            lines.push(`- ${c.name} (${c.kind})${loc}${sig}`);
+        }
+        return lines.join('\n');
+    }
+    formatNodeDetails(node, code, outline) {
         const location = node.startLine ? `:${node.startLine}` : '';
         const lines = [
             `## ${node.name} (${node.kind})`,
@@ -1534,7 +1722,10 @@ class ToolHandler {
         if (node.docstring && node.docstring.length < 200) {
             lines.push('', node.docstring);
         }
-        if (code) {
+        if (outline) {
+            lines.push('', outline, '', `> Structural outline only. Read \`${node.filePath}\` or call codegraph_node on a specific member for its body.`);
+        }
+        else if (code) {
             lines.push('', '```' + node.language, code, '```');
         }
         return lines.join('\n');