@veewo/gitnexus 1.3.4

package/dist/mcp/local/local-backend.js

@@ -0,0 +1,1646 @@
+/**
+ * Local Backend (Multi-Repo)
+ *
+ * Provides tool implementations using local .gitnexus/ indexes.
+ * Supports multiple indexed repositories via a global registry.
+ * KuzuDB connections are opened lazily per repo on first query.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { initKuzu, executeQuery, closeKuzu, isKuzuReady } from '../core/kuzu-adapter.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at MCP server startup — crashes on unsupported Node ABI versions (#89)
+// git utilities available if needed
+// import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
+import { listRegisteredRepos, } from '../../storage/repo-manager.js';
+// AI context generation is CLI-only (gitnexus analyze)
+// import { generateAIContextFiles } from '../../cli/ai-context.js';
+/**
+ * Quick test-file detection for filtering impact results.
+ * Matches common test file patterns across all supported languages.
+ */
+function isTestFilePath(filePath) {
+    const p = filePath.toLowerCase().replace(/\\/g, '/');
+    return (p.includes('.test.') || p.includes('.spec.') ||
+        p.includes('__tests__/') || p.includes('__mocks__/') ||
+        p.includes('/test/') || p.includes('/tests/') ||
+        p.includes('/testing/') || p.includes('/fixtures/') ||
+        p.endsWith('_test.go') || p.endsWith('_test.py') ||
+        p.includes('/test_') || p.includes('/conftest.'));
+}
+/** Valid KuzuDB node labels for safe Cypher query construction */
+const VALID_NODE_LABELS = new Set([
+    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement',
+    'Community', 'Process', 'Struct', 'Enum', 'Macro', 'Typedef', 'Union',
+    'Namespace', 'Trait', 'Impl', 'TypeAlias', 'Const', 'Static', 'Property',
+    'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module',
+]);
+function inferTypeFromId(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return undefined;
+    const firstColon = id.indexOf(':');
+    if (firstColon <= 0)
+        return undefined;
+    return id.slice(0, firstColon);
+}
+function getRowValue(row, key, index) {
+    if (!row || typeof row !== 'object')
+        return undefined;
+    const named = row[key];
+    if (named !== undefined)
+        return named;
+    return row[index];
+}
+export class LocalBackend {
+    repos = new Map();
+    contextCache = new Map();
+    initializedRepos = new Set();
+    // ─── Initialization ──────────────────────────────────────────────
+    /**
+     * Initialize from the global registry.
+     * Returns true if at least one repo is available.
+     */
+    async init() {
+        await this.refreshRepos();
+        return this.repos.size > 0;
+    }
+    /**
+     * Re-read the global registry and update the in-memory repo map.
+     * New repos are added, existing repos are updated, removed repos are pruned.
+     * KuzuDB connections for removed repos are NOT closed (they idle-timeout naturally).
+     */
+    async refreshRepos() {
+        const entries = await listRegisteredRepos({ validate: true });
+        const freshIds = new Set();
+        for (const entry of entries) {
+            const id = this.repoId(entry.name, entry.path);
+            freshIds.add(id);
+            const storagePath = entry.storagePath;
+            const kuzuPath = path.join(storagePath, 'kuzu');
+            const handle = {
+                id,
+                name: entry.name,
+                repoPath: entry.path,
+                storagePath,
+                kuzuPath,
+                indexedAt: entry.indexedAt,
+                lastCommit: entry.lastCommit,
+                stats: entry.stats,
+            };
+            this.repos.set(id, handle);
+            // Build lightweight context (no KuzuDB needed)
+            const s = entry.stats || {};
+            this.contextCache.set(id, {
+                projectName: entry.name,
+                stats: {
+                    fileCount: s.files || 0,
+                    functionCount: s.nodes || 0,
+                    communityCount: s.communities || 0,
+                    processCount: s.processes || 0,
+                },
+            });
+        }
+        // Prune repos that no longer exist in the registry
+        for (const id of this.repos.keys()) {
+            if (!freshIds.has(id)) {
+                this.repos.delete(id);
+                this.contextCache.delete(id);
+                this.initializedRepos.delete(id);
+            }
+        }
+    }
+    /**
+     * Generate a stable repo ID from name + path.
+     * If names collide, append a hash of the path.
+     */
+    repoId(name, repoPath) {
+        const base = name.toLowerCase();
+        // Check for name collision with a different path
+        for (const [id, handle] of this.repos) {
+            if (id === base && handle.repoPath !== path.resolve(repoPath)) {
+                // Collision — use path hash
+                const hash = Buffer.from(repoPath).toString('base64url').slice(0, 6);
+                return `${base}-${hash}`;
+            }
+        }
+        return base;
+    }
+    // ─── Repo Resolution ─────────────────────────────────────────────
+    /**
+     * Resolve which repo to use.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If 0 or multiple without param, throw with helpful message
+     *
+     * On a miss, re-reads the registry once in case a new repo was indexed
+     * while the MCP server was running.
+     */
+    async resolveRepo(repoParam) {
+        const result = this.resolveRepoFromCache(repoParam);
+        if (result)
+            return result;
+        // Miss — refresh registry and try once more
+        await this.refreshRepos();
+        const retried = this.resolveRepoFromCache(repoParam);
+        if (retried)
+            return retried;
+        // Still no match — throw with helpful message
+        if (this.repos.size === 0) {
+            throw new Error('No indexed repositories. Run: gitnexus analyze');
+        }
+        if (repoParam) {
+            const names = [...this.repos.values()].map(h => h.name);
+            throw new Error(`Repository "${repoParam}" not found. Available: ${names.join(', ')}`);
+        }
+        const names = [...this.repos.values()].map(h => h.name);
+        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${names.join(', ')}`);
+    }
+    /**
+     * Try to resolve a repo from the in-memory cache. Returns null on miss.
+     */
+    resolveRepoFromCache(repoParam) {
+        if (this.repos.size === 0)
+            return null;
+        if (repoParam) {
+            const paramLower = repoParam.toLowerCase();
+            // Match by id
+            if (this.repos.has(paramLower))
+                return this.repos.get(paramLower);
+            // Match by name (case-insensitive)
+            for (const handle of this.repos.values()) {
+                if (handle.name.toLowerCase() === paramLower)
+                    return handle;
+            }
+            // Match by path (substring)
+            const resolved = path.resolve(repoParam);
+            for (const handle of this.repos.values()) {
+                if (handle.repoPath === resolved)
+                    return handle;
+            }
+            // Match by partial name
+            for (const handle of this.repos.values()) {
+                if (handle.name.toLowerCase().includes(paramLower))
+                    return handle;
+            }
+            return null;
+        }
+        if (this.repos.size === 1) {
+            return this.repos.values().next().value;
+        }
+        return null; // Multiple repos, no param — ambiguous
+    }
+    // ─── Lazy KuzuDB Init ────────────────────────────────────────────
+    async ensureInitialized(repoId) {
+        // Always check the actual pool — the idle timer may have evicted the connection
+        if (this.initializedRepos.has(repoId) && isKuzuReady(repoId))
+            return;
+        const handle = this.repos.get(repoId);
+        if (!handle)
+            throw new Error(`Unknown repo: ${repoId}`);
+        try {
+            await initKuzu(repoId, handle.kuzuPath);
+            this.initializedRepos.add(repoId);
+        }
+        catch (err) {
+            // If lock error, mark as not initialized so next call retries
+            this.initializedRepos.delete(repoId);
+            throw err;
+        }
+    }
+    // ─── Public Getters ──────────────────────────────────────────────
+    /**
+     * Get context for a specific repo (or the single repo if only one).
+     */
+    getContext(repoId) {
+        if (repoId && this.contextCache.has(repoId)) {
+            return this.contextCache.get(repoId);
+        }
+        if (this.repos.size === 1) {
+            return this.contextCache.values().next().value ?? null;
+        }
+        return null;
+    }
+    /**
+     * List all registered repos with their metadata.
+     * Re-reads the global registry so newly indexed repos are discovered
+     * without restarting the MCP server.
+     */
+    async listRepos() {
+        await this.refreshRepos();
+        return [...this.repos.values()].map(h => ({
+            name: h.name,
+            path: h.repoPath,
+            indexedAt: h.indexedAt,
+            lastCommit: h.lastCommit,
+            stats: h.stats,
+        }));
+    }
+    // ─── Tool Dispatch ───────────────────────────────────────────────
+    async callTool(method, params) {
+        if (method === 'list_repos') {
+            return this.listRepos();
+        }
+        // Resolve repo from optional param (re-reads registry on miss)
+        const repo = await this.resolveRepo(params?.repo);
+        switch (method) {
+            case 'query':
+                return this.query(repo, params);
+            case 'cypher': {
+                const raw = await this.cypher(repo, params);
+                return this.formatCypherAsMarkdown(raw);
+            }
+            case 'context':
+                return this.context(repo, params);
+            case 'impact':
+                return this.impact(repo, params);
+            case 'detect_changes':
+                return this.detectChanges(repo, params);
+            case 'rename':
+                return this.rename(repo, params);
+            // Legacy aliases for backwards compatibility
+            case 'search':
+                return this.query(repo, params);
+            case 'explore':
+                return this.context(repo, { name: params?.name, ...params });
+            case 'overview':
+                return this.overview(repo, params);
+            default:
+                throw new Error(`Unknown tool: ${method}`);
+        }
+    }
+    // ─── Tool Implementations ────────────────────────────────────────
+    /**
+     * Query tool — process-grouped search.
+     *
+     * 1. Hybrid search (BM25 + semantic) to find matching symbols
+     * 2. Trace each match to its process(es) via STEP_IN_PROCESS
+     * 3. Group by process, rank by aggregate relevance + internal cluster cohesion
+     * 4. Return: { processes, process_symbols, definitions }
+     */
+    async query(repo, params) {
+        if (!params.query?.trim()) {
+            return { error: 'query parameter is required and cannot be empty.' };
+        }
+        await this.ensureInitialized(repo.id);
+        const processLimit = params.limit || 5;
+        const maxSymbolsPerProcess = params.max_symbols || 10;
+        const includeContent = params.include_content ?? false;
+        const searchQuery = params.query.trim();
+        // Step 1: Run hybrid search to get matching symbols
+        const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
+        const [bm25Results, semanticResults] = await Promise.all([
+            this.bm25Search(repo, searchQuery, searchLimit),
+            this.semanticSearch(repo, searchQuery, searchLimit),
+        ]);
+        // Merge via reciprocal rank fusion
+        const scoreMap = new Map();
+        for (let i = 0; i < bm25Results.length; i++) {
+            const result = bm25Results[i];
+            const key = result.nodeId || result.filePath;
+            const rrfScore = 1 / (60 + i);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scoreMap.set(key, { score: rrfScore, data: result });
+            }
+        }
+        for (let i = 0; i < semanticResults.length; i++) {
+            const result = semanticResults[i];
+            const key = result.nodeId || result.filePath;
+            const rrfScore = 1 / (60 + i);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrfScore;
+            }
+            else {
+                scoreMap.set(key, { score: rrfScore, data: result });
+            }
+        }
+        const merged = Array.from(scoreMap.entries())
+            .sort((a, b) => b[1].score - a[1].score)
+            .slice(0, searchLimit);
+        // Step 2: For each match with a nodeId, trace to process(es)
+        const processMap = new Map();
+        const definitions = []; // standalone symbols not in any process
+        for (const [_, item] of merged) {
+            const sym = item.data;
+            if (!sym.nodeId) {
+                // File-level results go to definitions
+                definitions.push({
+                    name: sym.name,
+                    type: sym.type || 'File',
+                    filePath: sym.filePath,
+                });
+                continue;
+            }
+            const escaped = sym.nodeId.replace(/'/g, "''");
+            // Find processes this symbol participates in
+            let processRows = [];
+            try {
+                processRows = await executeQuery(repo.id, `
+          MATCH (n {id: '${escaped}'})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          RETURN p.id AS pid, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `);
+            }
+            catch { /* symbol might not be in any process */ }
+            // Get cluster membership + cohesion (cohesion used as internal ranking signal)
+            let cohesion = 0;
+            let module;
+            try {
+                const cohesionRows = await executeQuery(repo.id, `
+          MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          RETURN c.cohesion AS cohesion, c.heuristicLabel AS module
+          LIMIT 1
+        `);
+                if (cohesionRows.length > 0) {
+                    cohesion = (cohesionRows[0].cohesion ?? cohesionRows[0][0]) || 0;
+                    module = cohesionRows[0].module ?? cohesionRows[0][1];
+                }
+            }
+            catch { /* no cluster info */ }
+            // Optionally fetch content
+            let content;
+            if (includeContent) {
+                try {
+                    const contentRows = await executeQuery(repo.id, `
+            MATCH (n {id: '${escaped}'})
+            RETURN n.content AS content
+          `);
+                    if (contentRows.length > 0) {
+                        content = contentRows[0].content ?? contentRows[0][0];
+                    }
+                }
+                catch { /* skip */ }
+            }
+            const symbolEntry = {
+                id: sym.nodeId,
+                name: sym.name,
+                type: sym.type,
+                filePath: sym.filePath,
+                startLine: sym.startLine,
+                endLine: sym.endLine,
+                ...(module ? { module } : {}),
+                ...(includeContent && content ? { content } : {}),
+            };
+            if (processRows.length === 0) {
+                // Symbol not in any process — goes to definitions
+                definitions.push(symbolEntry);
+            }
+            else {
+                // Add to each process it belongs to
+                for (const row of processRows) {
+                    const pid = row.pid ?? row[0];
+                    const label = row.label ?? row[1];
+                    const hLabel = row.heuristicLabel ?? row[2];
+                    const pType = row.processType ?? row[3];
+                    const stepCount = row.stepCount ?? row[4];
+                    const step = row.step ?? row[5];
+                    if (!processMap.has(pid)) {
+                        processMap.set(pid, {
+                            id: pid,
+                            label,
+                            heuristicLabel: hLabel,
+                            processType: pType,
+                            stepCount,
+                            totalScore: 0,
+                            cohesionBoost: 0,
+                            symbols: [],
+                        });
+                    }
+                    const proc = processMap.get(pid);
+                    proc.totalScore += item.score;
+                    proc.cohesionBoost = Math.max(proc.cohesionBoost, cohesion);
+                    proc.symbols.push({
+                        ...symbolEntry,
+                        process_id: pid,
+                        step_index: step,
+                    });
+                }
+            }
+        }
+        // Step 3: Rank processes by aggregate score + internal cohesion boost
+        const rankedProcesses = Array.from(processMap.values())
+            .map(p => ({
+            ...p,
+            priority: p.totalScore + (p.cohesionBoost * 0.1), // cohesion as subtle ranking signal
+        }))
+            .sort((a, b) => b.priority - a.priority)
+            .slice(0, processLimit);
+        // Step 4: Build response
+        const processes = rankedProcesses.map(p => ({
+            id: p.id,
+            summary: p.heuristicLabel || p.label,
+            priority: Math.round(p.priority * 1000) / 1000,
+            symbol_count: p.symbols.length,
+            process_type: p.processType,
+            step_count: p.stepCount,
+        }));
+        const processSymbols = rankedProcesses.flatMap(p => p.symbols.slice(0, maxSymbolsPerProcess).map(s => ({
+            ...s,
+            // remove internal fields
+        })));
+        // Deduplicate process_symbols by id
+        const seen = new Set();
+        const dedupedSymbols = processSymbols.filter(s => {
+            if (seen.has(s.id))
+                return false;
+            seen.add(s.id);
+            return true;
+        });
+        return {
+            processes,
+            process_symbols: dedupedSymbols,
+            definitions: definitions.slice(0, 20), // cap standalone definitions
+        };
+    }
+    /**
+     * BM25 keyword search helper - uses KuzuDB FTS for always-fresh results
+     */
+    async bm25Search(repo, query, limit) {
+        const escapedQuery = query.replace(/'/g, "''");
+        const symbolTables = [
+            { table: 'Function', index: 'function_fts', type: 'Function' },
+            { table: 'Class', index: 'class_fts', type: 'Class' },
+            { table: 'Method', index: 'method_fts', type: 'Method' },
+            { table: 'Interface', index: 'interface_fts', type: 'Interface' },
+        ];
+        const symbolHits = [];
+        for (const spec of symbolTables) {
+            try {
+                const rows = await executeQuery(repo.id, `
+          CALL QUERY_FTS_INDEX('${spec.table}', '${spec.index}', '${escapedQuery}', conjunctive := false)
+          RETURN node.id AS id, node.name AS name, node.filePath AS filePath, node.startLine AS startLine, node.endLine AS endLine, score AS score
+          ORDER BY score DESC
+          LIMIT ${limit}
+        `);
+                for (const row of rows) {
+                    const nodeId = getRowValue(row, 'id', 0);
+                    if (!nodeId)
+                        continue;
+                    symbolHits.push({
+                        nodeId,
+                        name: getRowValue(row, 'name', 1) || '',
+                        type: spec.type,
+                        filePath: getRowValue(row, 'filePath', 2) || '',
+                        startLine: getRowValue(row, 'startLine', 3),
+                        endLine: getRowValue(row, 'endLine', 4),
+                        bm25Score: Number(getRowValue(row, 'score', 5) ?? 0),
+                    });
+                }
+            }
+            catch {
+                // Missing FTS index for this table is expected in some repos/languages.
+            }
+        }
+        const rawTokens = query
+            .toLowerCase()
+            .split(/[^a-z0-9_]+/)
+            .filter(Boolean);
+        const stopTokens = new Set(['class', 'method', 'function', 'interface', 'file', 'symbol']);
+        const meaningfulTokens = rawTokens.filter(t => t.length >= 4 && !stopTokens.has(t));
+        // Add exact-name hits so symbol lookup queries rank correctly.
+        for (const token of meaningfulTokens) {
+            try {
+                const exactRows = await executeQuery(repo.id, `
+          MATCH (n)
+          WHERE toLower(n.name) = '${token.replace(/'/g, "''")}'
+          RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+          LIMIT ${limit}
+        `);
+                for (const row of exactRows) {
+                    const nodeId = getRowValue(row, 'id', 0);
+                    if (!nodeId)
+                        continue;
+                    symbolHits.push({
+                        nodeId,
+                        name: getRowValue(row, 'name', 1) || '',
+                        type: inferTypeFromId(nodeId) || 'CodeElement',
+                        filePath: getRowValue(row, 'filePath', 2) || '',
+                        startLine: getRowValue(row, 'startLine', 3),
+                        endLine: getRowValue(row, 'endLine', 4),
+                        bm25Score: 10_000,
+                    });
+                }
+            }
+            catch {
+                // ignore exact-hit fallback failures
+            }
+        }
+        if (symbolHits.length > 0) {
+            const filteredByName = meaningfulTokens.length > 0
+                ? symbolHits.filter(hit => meaningfulTokens.some(t => (hit.name || '').toLowerCase().includes(t)))
+                : symbolHits;
+            const candidateHits = filteredByName.length > 0 ? filteredByName : symbolHits;
+            const deduped = new Map();
+            for (const hit of candidateHits) {
+                const existing = deduped.get(hit.nodeId);
+                if (!existing || hit.bm25Score > existing.bm25Score) {
+                    deduped.set(hit.nodeId, hit);
+                }
+            }
+            return Array.from(deduped.values())
+                .sort((a, b) => b.bm25Score - a.bm25Score)
+                .slice(0, limit);
+        }
+        // Fallback to file-level FTS when symbol indexes are missing/empty.
+        try {
+            const fileRows = await executeQuery(repo.id, `
+        CALL QUERY_FTS_INDEX('File', 'file_fts', '${escapedQuery}', conjunctive := false)
+        RETURN node.filePath AS filePath, score AS score
+        ORDER BY score DESC
+        LIMIT ${limit}
+      `);
+            return fileRows.map((row) => {
+                const filePath = getRowValue(row, 'filePath', 0) || '';
+                const fileName = filePath.split('/').pop() || filePath;
+                return {
+                    name: fileName,
+                    type: 'File',
+                    filePath,
+                    bm25Score: Number(getRowValue(row, 'score', 1) ?? 0),
+                };
+            });
+        }
+        catch (err) {
+            console.error('GitNexus: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
+            return [];
+        }
+    }
+    /**
+     * Semantic vector search helper
+     */
+    async semanticSearch(repo, query, limit) {
+        try {
+            // Check if embedding table exists before loading the model (avoids heavy model init when embeddings are off)
+            const tableCheck = await executeQuery(repo.id, `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt LIMIT 1`);
+            if (!tableCheck.length || (tableCheck[0].cnt ?? tableCheck[0][0]) === 0)
+                return [];
+            const { embedQuery, getEmbeddingDims } = await import('../core/embedder.js');
+            const queryVec = await embedQuery(query);
+            const dims = getEmbeddingDims();
+            const queryVecStr = `[${queryVec.join(',')}]`;
+            const vectorQuery = `
+        CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
+          CAST(${queryVecStr} AS FLOAT[${dims}]), ${limit})
+        YIELD node AS emb, distance
+        WITH emb, distance
+        WHERE distance < 0.6
+        RETURN emb.nodeId AS nodeId, distance
+        ORDER BY distance
+      `;
+            const embResults = await executeQuery(repo.id, vectorQuery);
+            if (embResults.length === 0)
+                return [];
+            const results = [];
+            for (const embRow of embResults) {
+                const nodeId = embRow.nodeId ?? embRow[0];
+                const distance = embRow.distance ?? embRow[1];
+                const labelEndIdx = nodeId.indexOf(':');
+                const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
+                // Validate label against known node types to prevent Cypher injection
+                if (!VALID_NODE_LABELS.has(label))
+                    continue;
+                try {
+                    const escapedId = nodeId.replace(/'/g, "''");
+                    const nodeQuery = label === 'File'
+                        ? `MATCH (n:File {id: '${escapedId}'}) RETURN n.name AS name, n.filePath AS filePath`
+                        : `MATCH (n:\`${label}\` {id: '${escapedId}'}) RETURN n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
+                    const nodeRows = await executeQuery(repo.id, nodeQuery);
+                    if (nodeRows.length > 0) {
+                        const nodeRow = nodeRows[0];
+                        results.push({
+                            nodeId,
+                            name: nodeRow.name ?? nodeRow[0] ?? '',
+                            type: label,
+                            filePath: nodeRow.filePath ?? nodeRow[1] ?? '',
+                            distance,
+                            startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[2]) : undefined,
+                            endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[3]) : undefined,
+                        });
+                    }
+                }
+                catch { }
+            }
+            return results;
+        }
+        catch {
+            // Expected when embeddings are disabled — silently fall back to BM25-only
+            return [];
+        }
+    }
+    async executeCypher(repoName, query) {
+        const repo = await this.resolveRepo(repoName);
+        return this.cypher(repo, { query });
+    }
+    async cypher(repo, params) {
+        await this.ensureInitialized(repo.id);
+        if (!isKuzuReady(repo.id)) {
+            return { error: 'KuzuDB not ready. Index may be corrupted.' };
+        }
+        try {
+            const result = await executeQuery(repo.id, params.query);
+            return result;
+        }
+        catch (err) {
+            return { error: err.message || 'Query failed' };
+        }
+    }
+    /**
+     * Format raw Cypher result rows as a markdown table for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    formatCypherAsMarkdown(result) {
+        if (!Array.isArray(result) || result.length === 0)
+            return result;
+        const normalizedRows = result.map((row) => {
+            if (!row || typeof row !== 'object')
+                return row;
+            const next = { ...row };
+            if (Object.prototype.hasOwnProperty.call(next, 'type')) {
+                const typeValue = next.type;
+                if (typeValue === null || typeValue === undefined || (typeof typeValue === 'string' && typeValue.trim() === '')) {
+                    const inferred = inferTypeFromId(next.id ?? next.uid ?? next.sourceId ?? next.targetId);
+                    if (inferred)
+                        next.type = inferred;
+                }
+            }
+            if (Object.prototype.hasOwnProperty.call(next, 'kind')) {
+                const kindValue = next.kind;
+                if (kindValue === null || kindValue === undefined || (typeof kindValue === 'string' && kindValue.trim() === '')) {
+                    const inferred = inferTypeFromId(next.id ?? next.uid ?? next.sourceId ?? next.targetId);
+                    if (inferred)
+                        next.kind = inferred;
+                }
+            }
+            return next;
+        });
+        const firstRow = normalizedRows[0];
+        if (typeof firstRow !== 'object' || firstRow === null)
+            return result;
+        const keys = Object.keys(firstRow);
+        if (keys.length === 0)
+            return result;
+        const header = '| ' + keys.join(' | ') + ' |';
+        const separator = '| ' + keys.map(() => '---').join(' | ') + ' |';
+        const dataRows = normalizedRows.map((row) => '| ' + keys.map(k => {
+            const v = row[k];
+            if (v === null || v === undefined)
+                return '';
+            if (typeof v === 'object')
+                return JSON.stringify(v);
+            return String(v);
+        }).join(' | ') + ' |');
+        return {
+            markdown: [header, separator, ...dataRows].join('\n'),
+            row_count: normalizedRows.length,
+        };
+    }
+    /**
+     * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
+     * weighted-average cohesion, filter out tiny clusters (<5 symbols).
+     * Raw communities stay intact in KuzuDB for Cypher queries.
+     */
+    aggregateClusters(clusters) {
+        const groups = new Map();
+        for (const c of clusters) {
+            const label = c.heuristicLabel || c.label || 'Unknown';
+            const symbols = c.symbolCount || 0;
+            const cohesion = c.cohesion || 0;
+            const existing = groups.get(label);
+            if (!existing) {
+                groups.set(label, { ids: [c.id], totalSymbols: symbols, weightedCohesion: cohesion * symbols, largest: c });
+            }
+            else {
+                existing.ids.push(c.id);
+                existing.totalSymbols += symbols;
+                existing.weightedCohesion += cohesion * symbols;
+                if (symbols > (existing.largest.symbolCount || 0)) {
+                    existing.largest = c;
+                }
+            }
+        }
+        return Array.from(groups.entries())
+            .map(([label, g]) => ({
+            id: g.largest.id,
+            label,
+            heuristicLabel: label,
+            symbolCount: g.totalSymbols,
+            cohesion: g.totalSymbols > 0 ? g.weightedCohesion / g.totalSymbols : 0,
+            subCommunities: g.ids.length,
+        }))
+            .filter(c => c.symbolCount >= 5)
+            .sort((a, b) => b.symbolCount - a.symbolCount);
+    }
+    async overview(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const limit = params.limit || 20;
+        const result = {
+            repo: repo.name,
+            repoPath: repo.repoPath,
+            stats: repo.stats,
+            indexedAt: repo.indexedAt,
+            lastCommit: repo.lastCommit,
+        };
+        if (params.showClusters !== false) {
+            try {
+                // Fetch more raw communities than the display limit so aggregation has enough data
+                const rawLimit = Math.max(limit * 5, 200);
+                const clusters = await executeQuery(repo.id, `
+          MATCH (c:Community)
+          RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+          ORDER BY c.symbolCount DESC
+          LIMIT ${rawLimit}
+        `);
+                const rawClusters = clusters.map((c) => ({
+                    id: c.id || c[0],
+                    label: c.label || c[1],
+                    heuristicLabel: c.heuristicLabel || c[2],
+                    cohesion: c.cohesion || c[3],
+                    symbolCount: c.symbolCount || c[4],
+                }));
+                result.clusters = this.aggregateClusters(rawClusters).slice(0, limit);
+            }
+            catch {
+                result.clusters = [];
+            }
+        }
+        if (params.showProcesses !== false) {
+            try {
+                const processes = await executeQuery(repo.id, `
+          MATCH (p:Process)
+          RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+          ORDER BY p.stepCount DESC
+          LIMIT ${limit}
+        `);
+                result.processes = processes.map((p) => ({
+                    id: p.id || p[0],
+                    label: p.label || p[1],
+                    heuristicLabel: p.heuristicLabel || p[2],
+                    processType: p.processType || p[3],
+                    stepCount: p.stepCount || p[4],
+                }));
+            }
+            catch {
+                result.processes = [];
+            }
+        }
+        return result;
+    }
+    /**
+     * Context tool — 360-degree symbol view with categorized refs.
+     * Disambiguation when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    async context(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { name, uid, file_path, include_content } = params;
+        if (!name && !uid) {
+            return { error: 'Either "name" or "uid" parameter is required.' };
+        }
+        // Step 1: Find the symbol
+        let symbols;
+        if (uid) {
+            const escaped = uid.replace(/'/g, "''");
+            symbols = await executeQuery(repo.id, `
+        MATCH (n {id: '${escaped}'})
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
+        LIMIT 1
+      `);
+        }
+        else {
+            const escaped = name.replace(/'/g, "''");
+            const isQualified = name.includes('/') || name.includes(':');
+            let whereClause;
+            if (file_path) {
+                const fpEscaped = file_path.replace(/'/g, "''");
+                whereClause = `WHERE n.name = '${escaped}' AND n.filePath CONTAINS '${fpEscaped}'`;
+            }
+            else if (isQualified) {
+                whereClause = `WHERE n.id = '${escaped}' OR n.name = '${escaped}'`;
+            }
+            else {
+                whereClause = `WHERE n.name = '${escaped}'`;
+            }
+            symbols = await executeQuery(repo.id, `
+        MATCH (n) ${whereClause}
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
+        LIMIT 10
+      `);
+        }
+        if (symbols.length === 0) {
+            return { error: `Symbol '${name || uid}' not found` };
+        }
+        // Step 2: Disambiguation
+        if (symbols.length > 1 && !uid) {
+            return {
+                status: 'ambiguous',
+                message: `Found ${symbols.length} symbols matching '${name}'. Use uid or file_path to disambiguate.`,
+                candidates: symbols.map((s) => ({
+                    uid: getRowValue(s, 'id', 0),
+                    name: getRowValue(s, 'name', 1),
+                    kind: inferTypeFromId(getRowValue(s, 'id', 0)) || 'CodeElement',
+                    filePath: getRowValue(s, 'filePath', 2),
+                    line: getRowValue(s, 'startLine', 3),
+                })),
+            };
+        }
+        // Step 3: Build full context
+        const sym = symbols[0];
+        const symNodeId = getRowValue(sym, 'id', 0) || '';
+        const symId = symNodeId.replace(/'/g, "''");
+        const symKind = inferTypeFromId(symNodeId) || 'CodeElement';
+        const symFilePath = getRowValue(sym, 'filePath', 2) || '';
+        // Categorized incoming refs
+        let incomingRows = await executeQuery(repo.id, `
+      MATCH (caller)-[r:CodeRelation]->(n {id: '${symId}'})
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+      RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath
+      LIMIT 30
+    `);
+        // Categorized outgoing refs
+        let outgoingRows = await executeQuery(repo.id, `
+      MATCH (n {id: '${symId}'})-[r:CodeRelation]->(target)
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+      RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath
+      LIMIT 30
+    `);
+        // Process participation
+        let processRows = [];
+        try {
+            processRows = await executeQuery(repo.id, `
+        MATCH (n {id: '${symId}'})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+        RETURN p.id AS pid, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+      `);
+        }
+        catch { /* no process info */ }
+        // Classes/interfaces are often represented by method/property level edges.
+        // When direct edges are empty, fall back to file-scoped references/processes.
+        if ((symKind === 'Class' || symKind === 'Interface') && symFilePath) {
+            const escapedPath = symFilePath.replace(/'/g, "''");
+            if (incomingRows.length === 0) {
+                try {
+                    incomingRows = await executeQuery(repo.id, `
+            MATCH (caller)-[r:CodeRelation]->(n)
+            WHERE n.filePath = '${escapedPath}' AND r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+            RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath
+            LIMIT 30
+          `);
+                }
+                catch { /* ignore fallback failures */ }
+            }
+            if (outgoingRows.length === 0) {
+                try {
+                    outgoingRows = await executeQuery(repo.id, `
+            MATCH (n)-[r:CodeRelation]->(target)
+            WHERE n.filePath = '${escapedPath}' AND r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+            RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath
+            LIMIT 30
+          `);
+                }
+                catch { /* ignore fallback failures */ }
+            }
+            if (processRows.length === 0) {
+                try {
+                    const scopedProcessRows = await executeQuery(repo.id, `
+            MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+            WHERE n.filePath = '${escapedPath}'
+            RETURN p.id AS pid, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+            LIMIT 200
+          `);
+                    const minStepByProcess = new Map();
+                    for (const row of scopedProcessRows) {
+                        const pid = getRowValue(row, 'pid', 0);
+                        if (!pid)
+                            continue;
+                        const step = Number(getRowValue(row, 'step', 2) ?? Number.MAX_SAFE_INTEGER);
+                        const existing = minStepByProcess.get(pid);
+                        if (!existing || step < existing.step) {
+                            minStepByProcess.set(pid, {
+                                pid,
+                                label: getRowValue(row, 'label', 1),
+                                step,
+                                stepCount: getRowValue(row, 'stepCount', 3),
+                            });
+                        }
+                    }
+                    processRows = Array.from(minStepByProcess.values());
+                }
+                catch { /* ignore fallback failures */ }
+            }
+        }
+        // Helper to categorize refs
+        const categorize = (rows) => {
+            const cats = {};
+            for (const row of rows) {
+                const relType = String(getRowValue(row, 'relType', 0) || '').toLowerCase();
+                const uid = getRowValue(row, 'uid', 1);
+                const entry = {
+                    uid,
+                    name: getRowValue(row, 'name', 2),
+                    filePath: getRowValue(row, 'filePath', 3),
+                    kind: getRowValue(row, 'kind', 4) || inferTypeFromId(uid) || 'CodeElement',
+                };
+                if (!cats[relType])
+                    cats[relType] = [];
+                cats[relType].push(entry);
+            }
+            return cats;
+        };
+        return {
+            status: 'found',
+            symbol: {
+                uid: getRowValue(sym, 'id', 0),
+                name: getRowValue(sym, 'name', 1),
+                kind: symKind,
+                filePath: symFilePath,
+                startLine: getRowValue(sym, 'startLine', 3),
+                endLine: getRowValue(sym, 'endLine', 4),
+                ...(include_content && getRowValue(sym, 'content', 5) ? { content: getRowValue(sym, 'content', 5) } : {}),
+            },
+            incoming: categorize(incomingRows),
+            outgoing: categorize(outgoingRows),
+            processes: processRows.map((r) => ({
+                id: getRowValue(r, 'pid', 0),
+                name: getRowValue(r, 'label', 1),
+                step_index: getRowValue(r, 'step', 2),
+                step_count: getRowValue(r, 'stepCount', 3),
+            })),
+        };
+    }
+    /**
+     * Legacy explore — kept for backwards compatibility with resources.ts.
+     * Routes cluster/process types to direct graph queries.
+     */
+    async explore(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { name, type } = params;
+        if (type === 'symbol') {
+            return this.context(repo, { name });
+        }
+        if (type === 'cluster') {
+            const escaped = name.replace(/'/g, "''");
+            const clusterQuery = `
+        MATCH (c:Community)
+        WHERE c.label = '${escaped}' OR c.heuristicLabel = '${escaped}'
+        RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+      `;
+            const clusters = await executeQuery(repo.id, clusterQuery);
+            if (clusters.length === 0)
+                return { error: `Cluster '${name}' not found` };
+            const rawClusters = clusters.map((c) => ({
+                id: c.id || c[0], label: c.label || c[1], heuristicLabel: c.heuristicLabel || c[2],
+                cohesion: c.cohesion || c[3], symbolCount: c.symbolCount || c[4],
+            }));
+            let totalSymbols = 0, weightedCohesion = 0;
+            for (const c of rawClusters) {
+                const s = c.symbolCount || 0;
+                totalSymbols += s;
+                weightedCohesion += (c.cohesion || 0) * s;
+            }
+            const members = await executeQuery(repo.id, `
+        MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+        WHERE c.label = '${escaped}' OR c.heuristicLabel = '${escaped}'
+        RETURN DISTINCT n.id AS id, n.name AS name, n.filePath AS filePath
+        LIMIT 30
+      `);
+            return {
+                cluster: {
+                    id: rawClusters[0].id,
+                    label: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                    heuristicLabel: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                    cohesion: totalSymbols > 0 ? weightedCohesion / totalSymbols : 0,
+                    symbolCount: totalSymbols,
+                    subCommunities: rawClusters.length,
+                },
+                members: members.map((m) => ({
+                    name: getRowValue(m, 'name', 1),
+                    type: inferTypeFromId(getRowValue(m, 'id', 0)) || 'CodeElement',
+                    filePath: getRowValue(m, 'filePath', 2),
+                })),
+            };
+        }
+        if (type === 'process') {
+            const processes = await executeQuery(repo.id, `
+        MATCH (p:Process)
+        WHERE p.label = '${name.replace(/'/g, "''")}' OR p.heuristicLabel = '${name.replace(/'/g, "''")}'
+        RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+        LIMIT 1
+      `);
+            if (processes.length === 0)
+                return { error: `Process '${name}' not found` };
+            const proc = processes[0];
+            const procId = proc.id || proc[0];
+            const steps = await executeQuery(repo.id, `
+        MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p {id: '${procId}'})
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, r.step AS step
+        ORDER BY r.step
+      `);
+            return {
+                process: {
+                    id: procId, label: proc.label || proc[1], heuristicLabel: proc.heuristicLabel || proc[2],
+                    processType: proc.processType || proc[3], stepCount: proc.stepCount || proc[4],
+                },
+                steps: steps.map((s) => ({
+                    step: getRowValue(s, 'step', 3),
+                    name: getRowValue(s, 'name', 1),
+                    type: inferTypeFromId(getRowValue(s, 'id', 0)) || 'CodeElement',
+                    filePath: getRowValue(s, 'filePath', 2),
+                })),
+            };
+        }
+        return { error: 'Invalid type. Use: symbol, cluster, or process' };
+    }
+    /**
+     * Detect changes — git-diff based impact analysis.
+     * Maps changed lines to indexed symbols, then finds affected processes.
+     */
+    async detectChanges(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const scope = params.scope || 'unstaged';
+        const { execSync } = await import('child_process');
+        // Build git diff command based on scope
+        let diffCmd;
+        switch (scope) {
+            case 'staged':
+                diffCmd = 'git diff --staged --name-only';
+                break;
+            case 'all':
+                diffCmd = 'git diff HEAD --name-only';
+                break;
+            case 'compare':
+                if (!params.base_ref)
+                    return { error: 'base_ref is required for "compare" scope' };
+                diffCmd = `git diff ${params.base_ref} --name-only`;
+                break;
+            case 'unstaged':
+            default:
+                diffCmd = 'git diff --name-only';
+                break;
+        }
+        let changedFiles;
+        try {
+            const output = execSync(diffCmd, { cwd: repo.repoPath, encoding: 'utf-8' });
+            changedFiles = output.trim().split('\n').filter(f => f.length > 0);
+        }
+        catch (err) {
+            return { error: `Git diff failed: ${err.message}` };
+        }
+        if (changedFiles.length === 0) {
+            return {
+                summary: { changed_count: 0, affected_count: 0, risk_level: 'none', message: 'No changes detected.' },
+                changed_symbols: [],
+                affected_processes: [],
+            };
+        }
+        // Map changed files to indexed symbols
+        const changedSymbols = [];
+        for (const file of changedFiles) {
+            const escaped = file.replace(/\\/g, '/').replace(/'/g, "''");
+            try {
+                const symbols = await executeQuery(repo.id, `
+          MATCH (n) WHERE n.filePath CONTAINS '${escaped}'
+          RETURN n.id AS id, n.name AS name, n.filePath AS filePath
+          LIMIT 20
+        `);
+                for (const sym of symbols) {
+                    const id = getRowValue(sym, 'id', 0) || '';
+                    changedSymbols.push({
+                        id,
+                        name: getRowValue(sym, 'name', 1),
+                        type: inferTypeFromId(id) || 'CodeElement',
+                        filePath: getRowValue(sym, 'filePath', 2),
+                        change_type: 'Modified',
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+        // Find affected processes
+        const affectedProcesses = new Map();
+        for (const sym of changedSymbols) {
+            const escaped = sym.id.replace(/'/g, "''");
+            try {
+                const procs = await executeQuery(repo.id, `
+          MATCH (n {id: '${escaped}'})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          RETURN p.id AS pid, p.heuristicLabel AS label, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `);
+                for (const proc of procs) {
+                    const pid = proc.pid || proc[0];
+                    if (!affectedProcesses.has(pid)) {
+                        affectedProcesses.set(pid, {
+                            id: pid,
+                            name: proc.label || proc[1],
+                            process_type: proc.processType || proc[2],
+                            step_count: proc.stepCount || proc[3],
+                            changed_steps: [],
+                        });
+                    }
+                    affectedProcesses.get(pid).changed_steps.push({
+                        symbol: sym.name,
+                        step: proc.step || proc[4],
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+        const processCount = affectedProcesses.size;
+        const risk = processCount === 0 ? 'low' : processCount <= 5 ? 'medium' : processCount <= 15 ? 'high' : 'critical';
+        return {
+            summary: {
+                changed_count: changedSymbols.length,
+                affected_count: processCount,
+                changed_files: changedFiles.length,
+                risk_level: risk,
+            },
+            changed_symbols: changedSymbols,
+            affected_processes: Array.from(affectedProcesses.values()),
+        };
+    }
+    /**
+     * Rename tool — multi-file coordinated rename using graph + text search.
+     * Graph refs are tagged "graph" (high confidence).
+     * Additional refs found via text search are tagged "text_search" (lower confidence).
+     */
+    async rename(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { new_name, file_path } = params;
+        const dry_run = params.dry_run ?? true;
+        if (!params.symbol_name && !params.symbol_uid) {
+            return { error: 'Either symbol_name or symbol_uid is required.' };
+        }
+        // Step 1: Find the target symbol (reuse context's lookup)
+        const lookupResult = await this.context(repo, {
+            name: params.symbol_name,
+            uid: params.symbol_uid,
+            file_path,
+        });
+        if (lookupResult.status === 'ambiguous') {
+            return lookupResult; // pass disambiguation through
+        }
+        if (lookupResult.error) {
+            return lookupResult;
+        }
+        const sym = lookupResult.symbol;
+        const oldName = sym.name;
+        if (oldName === new_name) {
+            return { error: 'New name is the same as the current name.' };
+        }
+        // Step 2: Collect edits from graph (high confidence)
+        const changes = new Map();
+        const addEdit = (filePath, line, oldText, newText, confidence) => {
+            if (!changes.has(filePath)) {
+                changes.set(filePath, { file_path: filePath, edits: [] });
+            }
+            changes.get(filePath).edits.push({ line, old_text: oldText, new_text: newText, confidence });
+        };
+        // The definition itself
+        if (sym.filePath && sym.startLine) {
+            try {
+                const content = await fs.readFile(path.join(repo.repoPath, sym.filePath), 'utf-8');
+                const lines = content.split('\n');
+                const lineIdx = sym.startLine - 1;
+                if (lineIdx >= 0 && lineIdx < lines.length && lines[lineIdx].includes(oldName)) {
+                    addEdit(sym.filePath, sym.startLine, lines[lineIdx].trim(), lines[lineIdx].replace(oldName, new_name).trim(), 'graph');
+                }
+            }
+            catch { /* skip */ }
+        }
+        // All incoming refs from graph (callers, importers, etc.)
+        const allIncoming = [
+            ...(lookupResult.incoming.calls || []),
+            ...(lookupResult.incoming.imports || []),
+            ...(lookupResult.incoming.extends || []),
+            ...(lookupResult.incoming.implements || []),
+        ];
+        let graphEdits = changes.size > 0 ? 1 : 0; // count definition edit
+        for (const ref of allIncoming) {
+            if (!ref.filePath)
+                continue;
+            try {
+                const content = await fs.readFile(path.join(repo.repoPath, ref.filePath), 'utf-8');
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].includes(oldName)) {
+                        addEdit(ref.filePath, i + 1, lines[i].trim(), lines[i].replace(new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'), new_name).trim(), 'graph');
+                        graphEdits++;
+                        break; // one edit per file from graph refs
+                    }
+                }
+            }
+            catch { /* skip */ }
+        }
+        // Step 3: Text search for refs the graph might have missed
+        let astSearchEdits = 0;
+        const graphFiles = new Set([sym.filePath, ...allIncoming.map(r => r.filePath)].filter(Boolean));
+        // Simple text search across the repo for the old name (in files not already covered by graph)
+        try {
+            const { execSync } = await import('child_process');
+            const rgCmd = `rg -l --type-add "code:*.{ts,tsx,js,jsx,py,go,rs,java}" -t code "\\b${oldName}\\b" .`;
+            const output = execSync(rgCmd, { cwd: repo.repoPath, encoding: 'utf-8', timeout: 5000 });
+            const files = output.trim().split('\n').filter(f => f.length > 0);
+            for (const file of files) {
+                const normalizedFile = file.replace(/\\/g, '/').replace(/^\.\//, '');
+                if (graphFiles.has(normalizedFile))
+                    continue; // already covered by graph
+                try {
+                    const content = await fs.readFile(path.join(repo.repoPath, normalizedFile), 'utf-8');
+                    const lines = content.split('\n');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    for (let i = 0; i < lines.length; i++) {
+                        if (regex.test(lines[i])) {
+                            addEdit(normalizedFile, i + 1, lines[i].trim(), lines[i].replace(regex, new_name).trim(), 'text_search');
+                            astSearchEdits++;
+                            regex.lastIndex = 0; // reset regex
+                        }
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* rg not available or no additional matches */ }
+        // Step 4: Apply or preview
+        const allChanges = Array.from(changes.values());
+        const totalEdits = allChanges.reduce((sum, c) => sum + c.edits.length, 0);
+        if (!dry_run) {
+            // Apply edits to files
+            for (const change of allChanges) {
+                try {
+                    const fullPath = path.join(repo.repoPath, change.file_path);
+                    let content = await fs.readFile(fullPath, 'utf-8');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    content = content.replace(regex, new_name);
+                    await fs.writeFile(fullPath, content, 'utf-8');
+                }
+                catch { /* skip failed files */ }
+            }
+        }
+        return {
+            status: 'success',
+            old_name: oldName,
+            new_name,
+            files_affected: allChanges.length,
+            total_edits: totalEdits,
+            graph_edits: graphEdits,
+            text_search_edits: astSearchEdits,
+            changes: allChanges,
+            applied: !dry_run,
+        };
+    }
+    async impact(repo, params) {
+        await this.ensureInitialized(repo.id);
+        const { target, direction } = params;
+        const maxDepth = params.maxDepth ?? 3;
+        const relationTypes = params.relationTypes && params.relationTypes.length > 0
+            ? params.relationTypes
+            : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
+        const includeTests = params.includeTests ?? false;
+        const minConfidence = params.minConfidence ?? 0.3;
+        const relTypeFilter = relationTypes.map(t => `'${t}'`).join(', ');
+        const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
+        let targets = [];
+        if (params.target_uid?.trim()) {
+            const escapedUid = params.target_uid.trim().replace(/'/g, "''");
+            targets = await executeQuery(repo.id, `
+        MATCH (n {id: '${escapedUid}'})
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine
+        LIMIT 1
+      `);
+        }
+        else {
+            const escapedTarget = target.replace(/'/g, "''");
+            const fileFilter = params.file_path?.trim()
+                ? ` AND n.filePath CONTAINS '${params.file_path.trim().replace(/'/g, "''")}'`
+                : '';
+            targets = await executeQuery(repo.id, `
+        MATCH (n)
+        WHERE n.name = '${escapedTarget}'${fileFilter}
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine
+        LIMIT 20
+      `);
+        }
+        if (targets.length === 0)
+            return { error: `Target '${target}' not found` };
+        if (targets.length > 1 && !params.target_uid) {
+            return {
+                status: 'ambiguous',
+                message: `Found ${targets.length} symbols matching '${target}'. Use target_uid or file_path to disambiguate.`,
+                candidates: targets.map((s) => ({
+                    uid: getRowValue(s, 'id', 0),
+                    name: getRowValue(s, 'name', 1),
+                    kind: inferTypeFromId(getRowValue(s, 'id', 0)) || 'CodeElement',
+                    filePath: getRowValue(s, 'filePath', 2),
+                    line: getRowValue(s, 'startLine', 3),
+                })),
+            };
+        }
+        const sym = targets[0];
+        const symId = getRowValue(sym, 'id', 0) || '';
+        const symType = inferTypeFromId(symId) || 'CodeElement';
+        let seedIds = [symId];
+        // Class/interface references are frequently attached to member symbols.
+        // Seed traversal with symbols from the same file to approximate class blast radius.
+        if ((symType === 'Class' || symType === 'Interface')) {
+            const targetFilePath = getRowValue(sym, 'filePath', 2);
+            if (targetFilePath) {
+                try {
+                    const escapedPath = targetFilePath.replace(/'/g, "''");
+                    const seedRows = await executeQuery(repo.id, `
+            MATCH (n)
+            WHERE n.filePath = '${escapedPath}'
+            RETURN n.id AS id
+            LIMIT 200
+          `);
+                    const seedSet = new Set([symId]);
+                    for (const row of seedRows) {
+                        const id = getRowValue(row, 'id', 0);
+                        if (!id)
+                            continue;
+                        if (id.startsWith('File:') || id.startsWith('Folder:') || id.startsWith('Community:') || id.startsWith('Process:')) {
+                            continue;
+                        }
+                        seedSet.add(id);
+                    }
+                    seedIds = Array.from(seedSet);
+                }
+                catch {
+                    // fallback to class node only
+                }
+            }
+        }
+        const impacted = [];
+        const visited = new Set(seedIds);
+        let frontier = [...seedIds];
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            // Batch frontier nodes into a single Cypher query per depth level
+            const idList = frontier.map(id => `'${id.replace(/'/g, "''")}'`).join(', ');
+            const query = direction === 'upstream'
+                ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
+                : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
+            try {
+                const related = await executeQuery(repo.id, query);
+                for (const rel of related) {
+                    const relId = getRowValue(rel, 'id', 1) || '';
+                    const filePath = getRowValue(rel, 'filePath', 3) || '';
+                    const relNodeType = inferTypeFromId(relId) || 'CodeElement';
+                    if (!includeTests && isTestFilePath(filePath))
+                        continue;
+                    if (relNodeType === 'File' || relNodeType === 'Folder' || relNodeType === 'Community' || relNodeType === 'Process')
+                        continue;
+                    if (!visited.has(relId)) {
+                        visited.add(relId);
+                        nextFrontier.push(relId);
+                        impacted.push({
+                            depth,
+                            id: relId,
+                            name: getRowValue(rel, 'name', 2),
+                            type: relNodeType,
+                            filePath,
+                            relationType: getRowValue(rel, 'relType', 4),
+                            confidence: Number(getRowValue(rel, 'confidence', 5) ?? 1.0),
+                        });
+                    }
+                }
+            }
+            catch { /* query failed for this depth level */ }
+            frontier = nextFrontier;
+        }
+        const grouped = {};
+        for (const item of impacted) {
+            if (!grouped[item.depth])
+                grouped[item.depth] = [];
+            grouped[item.depth].push(item);
+        }
+        // ── Enrichment: affected processes, modules, risk ──────────────
+        const directCount = (grouped[1] || []).length;
+        let affectedProcesses = [];
+        let affectedModules = [];
+        if (impacted.length > 0) {
+            const allIds = impacted.map(i => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            const d1Ids = (grouped[1] || []).map((i) => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            // Affected processes: which execution flows are broken and at which step
+            const [processRows, moduleRows, directModuleRows] = await Promise.all([
+                executeQuery(repo.id, `
+          MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE s.id IN [${allIds}]
+          RETURN p.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits, MIN(r.step) AS minStep, p.stepCount AS stepCount
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${allIds}]
+          RETURN c.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                d1Ids ? executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${d1Ids}]
+          RETURN DISTINCT c.heuristicLabel AS name
+        `).catch(() => []) : Promise.resolve([]),
+            ]);
+            affectedProcesses = processRows.map((r) => ({
+                name: r.name || r[0],
+                hits: r.hits || r[1],
+                broken_at_step: r.minStep ?? r[2],
+                step_count: r.stepCount ?? r[3],
+            }));
+            const directModuleSet = new Set(directModuleRows.map((r) => r.name || r[0]));
+            affectedModules = moduleRows.map((r) => {
+                const name = r.name || r[0];
+                return {
+                    name,
+                    hits: r.hits || r[1],
+                    impact: directModuleSet.has(name) ? 'direct' : 'indirect',
+                };
+            });
+        }
+        // Risk scoring
+        const processCount = affectedProcesses.length;
+        const moduleCount = affectedModules.length;
+        let risk = 'LOW';
+        if (directCount >= 30 || processCount >= 5 || moduleCount >= 5 || impacted.length >= 200) {
+            risk = 'CRITICAL';
+        }
+        else if (directCount >= 15 || processCount >= 3 || moduleCount >= 3 || impacted.length >= 100) {
+            risk = 'HIGH';
+        }
+        else if (directCount >= 5 || impacted.length >= 30) {
+            risk = 'MEDIUM';
+        }
+        return {
+            target: {
+                id: symId,
+                name: getRowValue(sym, 'name', 1),
+                type: symType,
+                filePath: getRowValue(sym, 'filePath', 2),
+            },
+            direction,
+            impactedCount: impacted.length,
+            risk,
+            summary: {
+                direct: directCount,
+                processes_affected: processCount,
+                modules_affected: moduleCount,
+            },
+            affected_processes: affectedProcesses,
+            affected_modules: affectedModules,
+            byDepth: grouped,
+        };
+    }
+    // ─── Direct Graph Queries (for resources.ts) ────────────────────
+    /**
+     * Query clusters (communities) directly from graph.
+     * Used by getClustersResource — avoids legacy overview() dispatch.
+     */
+    async queryClusters(repoName, limit = 100) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        try {
+            const rawLimit = Math.max(limit * 5, 200);
+            const clusters = await executeQuery(repo.id, `
+        MATCH (c:Community)
+        RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+        ORDER BY c.symbolCount DESC
+        LIMIT ${rawLimit}
+      `);
+            const rawClusters = clusters.map((c) => ({
+                id: c.id || c[0],
+                label: c.label || c[1],
+                heuristicLabel: c.heuristicLabel || c[2],
+                cohesion: c.cohesion || c[3],
+                symbolCount: c.symbolCount || c[4],
+            }));
+            return { clusters: this.aggregateClusters(rawClusters).slice(0, limit) };
+        }
+        catch {
+            return { clusters: [] };
+        }
+    }
+    /**
+     * Query processes directly from graph.
+     * Used by getProcessesResource — avoids legacy overview() dispatch.
+     */
+    async queryProcesses(repoName, limit = 50) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        try {
+            const processes = await executeQuery(repo.id, `
+        MATCH (p:Process)
+        RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+        ORDER BY p.stepCount DESC
+        LIMIT ${limit}
+      `);
+            return {
+                processes: processes.map((p) => ({
+                    id: p.id || p[0],
+                    label: p.label || p[1],
+                    heuristicLabel: p.heuristicLabel || p[2],
+                    processType: p.processType || p[3],
+                    stepCount: p.stepCount || p[4],
+                })),
+            };
+        }
+        catch {
+            return { processes: [] };
+        }
+    }
+    /**
+     * Query cluster detail (members) directly from graph.
+     * Used by getClusterDetailResource.
+     */
+    async queryClusterDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        const escaped = name.replace(/'/g, "''");
+        const clusterQuery = `
+      MATCH (c:Community)
+      WHERE c.label = '${escaped}' OR c.heuristicLabel = '${escaped}'
+      RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+    `;
+        const clusters = await executeQuery(repo.id, clusterQuery);
+        if (clusters.length === 0)
+            return { error: `Cluster '${name}' not found` };
+        const rawClusters = clusters.map((c) => ({
+            id: c.id || c[0], label: c.label || c[1], heuristicLabel: c.heuristicLabel || c[2],
+            cohesion: c.cohesion || c[3], symbolCount: c.symbolCount || c[4],
+        }));
+        let totalSymbols = 0, weightedCohesion = 0;
+        for (const c of rawClusters) {
+            const s = c.symbolCount || 0;
+            totalSymbols += s;
+            weightedCohesion += (c.cohesion || 0) * s;
+        }
+        const members = await executeQuery(repo.id, `
+      MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+      WHERE c.label = '${escaped}' OR c.heuristicLabel = '${escaped}'
+      RETURN DISTINCT n.id AS id, n.name AS name, n.filePath AS filePath
+      LIMIT 30
+    `);
+        return {
+            cluster: {
+                id: rawClusters[0].id,
+                label: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                heuristicLabel: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                cohesion: totalSymbols > 0 ? weightedCohesion / totalSymbols : 0,
+                symbolCount: totalSymbols,
+                subCommunities: rawClusters.length,
+            },
+            members: members.map((m) => ({
+                name: getRowValue(m, 'name', 1),
+                type: inferTypeFromId(getRowValue(m, 'id', 0)) || 'CodeElement',
+                filePath: getRowValue(m, 'filePath', 2),
+            })),
+        };
+    }
+    /**
+     * Query process detail (steps) directly from graph.
+     * Used by getProcessDetailResource.
+     */
+    async queryProcessDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo.id);
+        const escaped = name.replace(/'/g, "''");
+        const processes = await executeQuery(repo.id, `
+      MATCH (p:Process)
+      WHERE p.label = '${escaped}' OR p.heuristicLabel = '${escaped}'
+      RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+      LIMIT 1
+    `);
+        if (processes.length === 0)
+            return { error: `Process '${name}' not found` };
+        const proc = processes[0];
+        const procId = proc.id || proc[0];
+        const steps = await executeQuery(repo.id, `
+      MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p {id: '${procId}'})
+      RETURN n.id AS id, n.name AS name, n.filePath AS filePath, r.step AS step
+      ORDER BY r.step
+    `);
+        return {
+            process: {
+                id: procId, label: proc.label || proc[1], heuristicLabel: proc.heuristicLabel || proc[2],
+                processType: proc.processType || proc[3], stepCount: proc.stepCount || proc[4],
+            },
+            steps: steps.map((s) => ({
+                step: getRowValue(s, 'step', 3),
+                name: getRowValue(s, 'name', 1),
+                type: inferTypeFromId(getRowValue(s, 'id', 0)) || 'CodeElement',
+                filePath: getRowValue(s, 'filePath', 2),
+            })),
+        };
+    }
+    async disconnect() {
+        await closeKuzu(); // close all connections
+        // Note: we intentionally do NOT call disposeEmbedder() here.
+        // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs,
+        // and importing the embedder module on Node v24+ crashes if onnxruntime
+        // was never loaded during the session. Since process.exit(0) follows
+        // immediately after disconnect(), the OS reclaims everything. See #38, #89.
+        this.repos.clear();
+        this.contextCache.clear();
+        this.initializedRepos.clear();
+    }
+}