gitnexus 1.2.8 → 1.2.9

package/dist/mcp/server.js

@@ -185,14 +185,14 @@ export async function startMCPServer(backend) {
                         role: 'user',
                         content: {
                             type: 'text',
-                            text: `Analyze the impact of my current code changes before committing.
-
-Follow these steps:
-1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
-2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
-3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
-4. Summarize: changes, affected processes, risk level, and recommended actions
-
+                            text: `Analyze the impact of my current code changes before committing.
+
+Follow these steps:
+1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
+2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
+3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
+4. Summarize: changes, affected processes, risk level, and recommended actions
+
 Present the analysis as a clear risk report.`,
                         },
                     },
@@ -207,14 +207,14 @@ Present the analysis as a clear risk report.`,
                         role: 'user',
                         content: {
                             type: 'text',
-                            text: `Generate architecture documentation for this codebase using the knowledge graph.
-
-Follow these steps:
-1. READ \`gitnexus://repo/${repo || '{name}'}/context\` for codebase stats
-2. READ \`gitnexus://repo/${repo || '{name}'}/clusters\` to see all functional areas
-3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows  
-4. For the top 5 most important processes, READ \`gitnexus://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
-5. Generate a mermaid architecture diagram showing the major areas and their connections
+                            text: `Generate architecture documentation for this codebase using the knowledge graph.
+
+Follow these steps:
+1. READ \`gitnexus://repo/${repo || '{name}'}/context\` for codebase stats
+2. READ \`gitnexus://repo/${repo || '{name}'}/clusters\` to see all functional areas
+3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows  
+4. For the top 5 most important processes, READ \`gitnexus://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
+5. Generate a mermaid architecture diagram showing the major areas and their connections
 6. Write an ARCHITECTURE.md file with: overview, functional areas, key execution flows, and the mermaid diagram`,
                         },
                     },

package/dist/mcp/tools.js

@@ -7,14 +7,14 @@
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
-        description: `List all indexed repositories available to GitNexus.
-
-Returns each repo's name, path, indexed date, last commit, and stats.
-
-WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
-AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
-
-When multiple repos are indexed, you MUST specify the "repo" parameter
+        description: `List all indexed repositories available to GitNexus.
+
+Returns each repo's name, path, indexed date, last commit, and stats.
+
+WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
+AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
+
+When multiple repos are indexed, you MUST specify the "repo" parameter
 on other tools (query, context, impact, etc.) to target the correct one.`,
         inputSchema: {
             type: 'object',
@@ -24,17 +24,17 @@ on other tools (query, context, impact, etc.) to target the correct one.`,
     },
     {
         name: 'query',
-        description: `Query the code knowledge graph for execution flows related to a concept.
-Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
-
-WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
-AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
-
-Returns results grouped by process (execution flow):
-- processes: ranked execution flows with relevance priority
-- process_symbols: all symbols in those flows with file locations
-- definitions: standalone types/interfaces not in any process
-
+        description: `Query the code knowledge graph for execution flows related to a concept.
+Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
+
+WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
+
+Returns results grouped by process (execution flow):
+- processes: ranked execution flows with relevance priority
+- process_symbols: all symbols in those flows with file locations and module (functional area)
+- definitions: standalone types/interfaces not in any process
+
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
         inputSchema: {
             type: 'object',
@@ -52,32 +52,34 @@ Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank
     },
     {
         name: 'cypher',
-        description: `Execute Cypher query against the code knowledge graph.
-
-WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
-AFTER THIS: Use context() on result symbols for deeper context.
-
-SCHEMA:
-- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
-- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
-- All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
-- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
-
-EXAMPLES:
-• Find callers of a function:
-  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
-
-• Find community members:
-  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
-
-• Trace a process:
-  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
-
-TIPS:
-- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
-- Community = auto-detected functional area (Leiden algorithm)
-- Process = execution flow trace from entry point to terminal
+        description: `Execute Cypher query against the code knowledge graph.
+
+WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
+AFTER THIS: Use context() on result symbols for deeper context.
+
+SCHEMA:
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
+- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
+- All edges via single CodeRelation table with 'type' property
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
+- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
+
+EXAMPLES:
+• Find callers of a function:
+  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
+
+• Find community members:
+  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
+
+• Trace a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
+
+OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
+
+TIPS:
+- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
+- Community = auto-detected functional area (Leiden algorithm)
+- Process = execution flow trace from entry point to terminal
 - Use heuristicLabel (not label) for human-readable community/process names`,
         inputSchema: {
             type: 'object',
@@ -90,12 +92,12 @@ TIPS:
     },
     {
         name: 'context',
-        description: `360-degree view of a single code symbol.
-Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
-
-WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
-AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
-
+        description: `360-degree view of a single code symbol.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
+
+WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
+AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
+
 Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
         inputSchema: {
             type: 'object',
@@ -111,12 +113,12 @@ Handles disambiguation: if multiple symbols share the same name, returns candida
     },
     {
         name: 'detect_changes',
-        description: `Analyze uncommitted git changes and find affected execution flows.
-Maps git diff hunks to indexed symbols, then traces which processes are impacted.
-
-WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
-AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
-
+        description: `Analyze uncommitted git changes and find affected execution flows.
+Maps git diff hunks to indexed symbols, then traces which processes are impacted.
+
+WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
+AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
+
 Returns: changed symbols, affected processes, and a risk summary.`,
         inputSchema: {
             type: 'object',
@@ -130,14 +132,14 @@ Returns: changed symbols, affected processes, and a risk summary.`,
     },
     {
         name: 'rename',
-        description: `Multi-file coordinated rename using the knowledge graph + text search.
-Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
-
-WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
-AFTER THIS: Run detect_changes() to verify no unexpected side effects.
-
-Each edit is tagged with confidence:
-- "graph": found via knowledge graph relationships (high confidence, safe to accept)
+        description: `Multi-file coordinated rename using the knowledge graph + text search.
+Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
+
+WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
+AFTER THIS: Run detect_changes() to verify no unexpected side effects.
+
+Each edit is tagged with confidence:
+- "graph": found via knowledge graph relationships (high confidence, safe to accept)
 - "text_search": found via regex text search (lower confidence, review carefully)`,
         inputSchema: {
             type: 'object',
@@ -154,18 +156,25 @@ Each edit is tagged with confidence:
     },
     {
         name: 'impact',
-        description: `Analyze the blast radius of changing a code symbol.
-Returns all symbols affected by modifying the target, grouped by depth with edge types and confidence.
-
-WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
-AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected execution flows.
-
-Depth groups:
-- d=1: WILL BREAK (direct callers/importers)
-- d=2: LIKELY AFFECTED (indirect)
-- d=3: MAY NEED TESTING (transitive)
-
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
+        description: `Analyze the blast radius of changing a code symbol.
+Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
+
+WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
+AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
+
+Output includes:
+- risk: LOW / MEDIUM / HIGH / CRITICAL
+- summary: direct callers, processes affected, modules affected
+- affected_processes: which execution flows break and at which step
+- affected_modules: which functional areas are hit (direct vs indirect)
+- byDepth: all affected symbols grouped by traversal depth
+
+Depth groups:
+- d=1: WILL BREAK (direct callers/importers)
+- d=2: LIKELY AFFECTED (indirect)
+- d=3: MAY NEED TESTING (transitive)
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',

package/dist/server/api.d.ts

@@ -1,6 +1,8 @@
 /**
- * HTTP API Server
+ * HTTP API Server (Multi-Repo)
  *
- * REST API for browser-based clients to query the local .gitnexus/ index.
+ * REST API for browser-based clients to query indexed repositories.
+ * Uses LocalBackend for multi-repo support via the global registry —
+ * the same backend the MCP server uses.
  */
 export declare const createServer: (port: number) => Promise<void>;

package/dist/server/api.js

@@ -1,20 +1,21 @@
 /**
- * HTTP API Server
+ * HTTP API Server (Multi-Repo)
  *
- * REST API for browser-based clients to query the local .gitnexus/ index.
+ * REST API for browser-based clients to query indexed repositories.
+ * Uses LocalBackend for multi-repo support via the global registry —
+ * the same backend the MCP server uses.
  */
 import express from 'express';
 import cors from 'cors';
 import path from 'path';
 import fs from 'fs/promises';
-import { findRepo } from '../storage/repo-manager.js';
-import { initKuzu, executeQuery } from '../core/kuzu/kuzu-adapter.js';
+import { LocalBackend } from '../mcp/local/local-backend.js';
 import { NODE_TABLES } from '../core/kuzu/schema.js';
-import { searchFTSFromKuzu } from '../core/search/bm25-index.js';
-import { hybridSearch } from '../core/search/hybrid-search.js';
-import { semanticSearch } from '../core/embeddings/embedding-pipeline.js';
-import { isEmbedderReady } from '../core/embeddings/embedder.js';
-const buildGraph = async () => {
+/**
+ * Build the full knowledge graph for a repo by querying each node table
+ * and all relationships via the backend's cypher tool.
+ */
+const buildGraph = async (backend, repoName) => {
     const nodes = [];
     for (const table of NODE_TABLES) {
         try {
@@ -34,7 +35,9 @@ const buildGraph = async () => {
             else {
                 query = `MATCH (n:${table}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`;
             }
-            const rows = await executeQuery(query);
+            const result = await backend.executeCypher(repoName, query);
+            // cypher returns the rows directly (array), or { error } on failure
+            const rows = Array.isArray(result) ? result : [];
             for (const row of rows) {
                 nodes.push({
                     id: row.id ?? row[0],
@@ -62,95 +65,262 @@ const buildGraph = async () => {
         }
     }
     const relationships = [];
-    const relRows = await executeQuery(`MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
-    for (const row of relRows) {
-        relationships.push({
-            id: `${row.sourceId}_${row.type}_${row.targetId}`,
-            type: row.type,
-            sourceId: row.sourceId,
-            targetId: row.targetId,
-            confidence: row.confidence,
-            reason: row.reason,
-            step: row.step,
-        });
+    try {
+        const relResult = await backend.executeCypher(repoName, `MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
+        const relRows = Array.isArray(relResult) ? relResult : [];
+        for (const row of relRows) {
+            relationships.push({
+                id: `${row.sourceId}_${row.type}_${row.targetId}`,
+                type: row.type,
+                sourceId: row.sourceId,
+                targetId: row.targetId,
+                confidence: row.confidence,
+                reason: row.reason,
+                step: row.step,
+            });
+        }
+    }
+    catch (err) {
+        console.warn('GitNexus: relationship query failed:', err?.message);
     }
     return { nodes, relationships };
 };
+const httpStatus = (err) => {
+    const msg = err?.message ?? '';
+    if (msg.includes('not found') || msg.includes('No indexed'))
+        return 404;
+    if (msg.includes('Multiple repositories'))
+        return 400;
+    return 500;
+};
 export const createServer = async (port) => {
+    const backend = new LocalBackend();
+    const hasRepos = await backend.init();
+    if (!hasRepos) {
+        console.warn('GitNexus: No indexed repositories found. The server will start but most endpoints will return errors.');
+        console.warn('Run "gitnexus analyze" in a repository to index it first.');
+    }
     const app = express();
-    app.use(cors());
+    app.use(cors({
+        origin: (origin, callback) => {
+            // Allow requests with no origin (curl, server-to-server), localhost, and the deployed site.
+            // The server binds to 127.0.0.1 so only the local machine can reach it — CORS just gates
+            // which browser-tab origins may issue the request.
+            if (!origin
+                || origin.startsWith('http://localhost:')
+                || origin.startsWith('http://127.0.0.1:')
+                || origin === 'https://gitnexus.vercel.app') {
+                callback(null, true);
+            }
+            else {
+                callback(new Error('Not allowed by CORS'));
+            }
+        }
+    }));
     app.use(express.json({ limit: '10mb' }));
-    // Get repo info
-    app.get('/api/repo', async (_req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed. Run: gitnexus analyze' });
-            return;
-        }
-        res.json({
-            repoPath: repo.repoPath,
-            indexedAt: repo.meta.indexedAt,
-            stats: repo.meta.stats || {},
-        });
+    // ─── GET /api/repos ─────────────────────────────────────────────
+    // List all indexed repositories
+    app.get('/api/repos', async (_req, res) => {
+        try {
+            const repos = await backend.listRepos();
+            res.json(repos);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to list repos' });
+        }
+    });
+    // ─── GET /api/repo?repo=X ──────────────────────────────────────
+    // Get metadata for a specific repo
+    app.get('/api/repo', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const repo = await backend.resolveRepo(repoName);
+            res.json({
+                name: repo.name,
+                path: repo.repoPath,
+                indexedAt: repo.indexedAt,
+                lastCommit: repo.lastCommit,
+                stats: repo.stats || {},
+            });
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Repository not found' });
+        }
     });
-    // Get full graph
-    app.get('/api/graph', async (_req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const graph = await buildGraph();
-        res.json(graph);
+    // ─── GET /api/graph?repo=X ─────────────────────────────────────
+    // Full knowledge graph (all nodes + relationships)
+    app.get('/api/graph', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            // Resolve repo to validate it exists and get the name
+            const repo = await backend.resolveRepo(repoName);
+            const graph = await buildGraph(backend, repo.name);
+            res.json(graph);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to build graph' });
+        }
     });
-    // Execute Cypher query
+    // ─── POST /api/query ───────────────────────────────────────────
+    // Execute a raw Cypher query.
+    // This endpoint is intentionally unrestricted (no query validation) because
+    // the server binds to 127.0.0.1 only — it exposes full graph query
+    // capabilities to local clients by design.
     app.post('/api/query', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const result = await executeQuery(req.body.cypher);
-        res.json({ result });
+        try {
+            const repoName = (req.body.repo ?? req.query.repo);
+            const cypher = req.body.cypher;
+            if (!cypher) {
+                res.status(400).json({ error: 'Missing "cypher" in request body' });
+                return;
+            }
+            const result = await backend.executeCypher(repoName, cypher);
+            if (result && !Array.isArray(result) && result.error) {
+                res.status(500).json({ error: result.error });
+                return;
+            }
+            res.json({ result });
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Query failed' });
+        }
     });
-    // Search
+    // ─── POST /api/search ──────────────────────────────────────────
+    // Process-grouped semantic search
     app.post('/api/search', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const query = req.body.query ?? '';
-        const limit = req.body.limit ?? 10;
-        if (isEmbedderReady()) {
-            const results = await hybridSearch(query, limit, executeQuery, semanticSearch);
+        try {
+            const repoName = (req.body.repo ?? req.query.repo);
+            const query = (req.body.query ?? '').trim();
+            const limit = req.body.limit;
+            if (!query) {
+                res.status(400).json({ error: 'Missing "query" in request body' });
+                return;
+            }
+            const results = await backend.callTool('query', {
+                repo: repoName,
+                query,
+                limit,
+            });
             res.json({ results });
-            return;
         }
-        // FTS-only fallback when embeddings aren't loaded
-        const results = await searchFTSFromKuzu(query, limit);
-        res.json({ results });
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Search failed' });
+        }
     });
-    // Read file
+    // ─── GET /api/file?repo=X&path=Y ──────────────────────────────
+    // Read a file from a resolved repo path on disk
     app.get('/api/file', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        const filePath = req.query.path;
-        if (!filePath) {
-            res.status(400).json({ error: 'Missing path' });
-            return;
-        }
-        const fullPath = path.join(repo.repoPath, filePath);
-        const content = await fs.readFile(fullPath, 'utf-8');
-        res.json({ content });
+        try {
+            const repoName = req.query.repo;
+            const filePath = req.query.path;
+            if (!filePath) {
+                res.status(400).json({ error: 'Missing "path" query parameter' });
+                return;
+            }
+            const repo = await backend.resolveRepo(repoName);
+            // Resolve the full path and validate it stays within the repo root
+            const repoRoot = path.resolve(repo.repoPath);
+            const fullPath = path.resolve(repoRoot, filePath);
+            if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot) {
+                res.status(403).json({ error: 'Path traversal denied: path escapes repo root' });
+                return;
+            }
+            const content = await fs.readFile(fullPath, 'utf-8');
+            res.json({ content });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                res.status(404).json({ error: 'File not found' });
+            }
+            else {
+                res.status(httpStatus(err))
+                    .json({ error: err.message || 'Failed to read file' });
+            }
+        }
+    });
+    // ─── GET /api/processes?repo=X ─────────────────────────────────
+    // List all processes for a repo
+    app.get('/api/processes', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const result = await backend.queryProcesses(repoName);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query processes' });
+        }
+    });
+    // ─── GET /api/process?repo=X&name=Y ───────────────────────────
+    // Get detailed process info including steps
+    app.get('/api/process', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const name = req.query.name;
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryProcessDetail(name, repoName);
+            if (result.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query process detail' });
+        }
+    });
+    // ─── GET /api/clusters?repo=X ─────────────────────────────────
+    // List all clusters for a repo
+    app.get('/api/clusters', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const result = await backend.queryClusters(repoName);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query clusters' });
+        }
+    });
+    // ─── GET /api/cluster?repo=X&name=Y ───────────────────────────
+    // Get detailed cluster info including members
+    app.get('/api/cluster', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const name = req.query.name;
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryClusterDetail(name, repoName);
+            if (result.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query cluster detail' });
+        }
     });
-    app.listen(port, () => {
+    const server = app.listen(port, '127.0.0.1', () => {
         console.log(`GitNexus server running on http://localhost:${port}`);
+        console.log(`Serving ${hasRepos ? 'all indexed repositories' : 'no repositories (run gitnexus analyze first)'}`);
     });
+    const shutdown = async () => {
+        server.close();
+        await backend.disconnect();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
 };