@duytransipher/gitnexus 1.4.6-sipher.0

package/dist/server/api.js

@@ -0,0 +1,344 @@
+/**
+ * HTTP API Server
+ *
+ * REST API for browser-based clients to query the local .gitnexus/ index.
+ * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
+ *
+ * Security: binds to 127.0.0.1 by default (use --host to override).
+ * CORS is restricted to localhost and the deployed site.
+ */
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import fs from 'fs/promises';
+import { loadMeta, listRegisteredRepos } from '../storage/repo-manager.js';
+import { executeQuery, closeLbug, withLbugDb } from '../core/lbug/lbug-adapter.js';
+import { NODE_TABLES } from '../core/lbug/schema.js';
+import { searchFTSFromLbug } from '../core/search/bm25-index.js';
+import { hybridSearch } from '../core/search/hybrid-search.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at server startup — crashes on unsupported Node ABI versions (#89)
+import { LocalBackend } from '../mcp/local/local-backend.js';
+import { mountMCPEndpoints } from './mcp-http.js';
+const buildGraph = async () => {
+    const nodes = [];
+    for (const table of NODE_TABLES) {
+        try {
+            let query = '';
+            if (table === 'File') {
+                query = `MATCH (n:File) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`;
+            }
+            else if (table === 'Folder') {
+                query = `MATCH (n:Folder) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
+            }
+            else if (table === 'Community') {
+                query = `MATCH (n:Community) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.cohesion AS cohesion, n.symbolCount AS symbolCount`;
+            }
+            else if (table === 'Process') {
+                query = `MATCH (n:Process) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
+            }
+            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);
+            for (const row of rows) {
+                nodes.push({
+                    id: row.id ?? row[0],
+                    label: table,
+                    properties: {
+                        name: row.name ?? row.label ?? row[1],
+                        filePath: row.filePath ?? row[2],
+                        startLine: row.startLine,
+                        endLine: row.endLine,
+                        content: row.content,
+                        heuristicLabel: row.heuristicLabel,
+                        cohesion: row.cohesion,
+                        symbolCount: row.symbolCount,
+                        processType: row.processType,
+                        stepCount: row.stepCount,
+                        communities: row.communities,
+                        entryPointId: row.entryPointId,
+                        terminalId: row.terminalId,
+                    },
+                });
+            }
+        }
+        catch {
+            // ignore empty tables
+        }
+    }
+    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,
+        });
+    }
+    return { nodes, relationships };
+};
+const statusFromError = (err) => {
+    const msg = String(err?.message ?? '');
+    if (msg.includes('No indexed repositories') || msg.includes('not found'))
+        return 404;
+    if (msg.includes('Multiple repositories'))
+        return 400;
+    return 500;
+};
+const requestedRepo = (req) => {
+    const fromQuery = typeof req.query.repo === 'string' ? req.query.repo : undefined;
+    if (fromQuery)
+        return fromQuery;
+    if (req.body && typeof req.body === 'object' && typeof req.body.repo === 'string') {
+        return req.body.repo;
+    }
+    return undefined;
+};
+export const createServer = async (port, host = '127.0.0.1') => {
+    const app = express();
+    // CORS: only allow localhost origins and the deployed site.
+    // Non-browser requests (curl, server-to-server) have no origin and are allowed.
+    app.use(cors({
+        origin: (origin, callback) => {
+            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' }));
+    // Initialize MCP backend (multi-repo, shared across all MCP sessions)
+    const backend = new LocalBackend();
+    await backend.init();
+    const cleanupMcp = mountMCPEndpoints(app, backend);
+    // Helper: resolve a repo by name from the global registry, or default to first
+    const resolveRepo = async (repoName) => {
+        const repos = await listRegisteredRepos();
+        if (repos.length === 0)
+            return null;
+        if (repoName)
+            return repos.find(r => r.name === repoName) || null;
+        return repos[0]; // default to first
+    };
+    // List all registered repos
+    app.get('/api/repos', async (_req, res) => {
+        try {
+            const repos = await listRegisteredRepos();
+            res.json(repos.map(r => ({
+                name: r.name, path: r.path, indexedAt: r.indexedAt,
+                lastCommit: r.lastCommit, stats: r.stats,
+            })));
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to list repos' });
+        }
+    });
+    // Get repo info
+    app.get('/api/repo', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found. Run: gitnexus analyze' });
+                return;
+            }
+            const meta = await loadMeta(entry.storagePath);
+            res.json({
+                name: entry.name,
+                repoPath: entry.path,
+                indexedAt: meta?.indexedAt ?? entry.indexedAt,
+                stats: meta?.stats ?? entry.stats ?? {},
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to get repo info' });
+        }
+    });
+    // Get full graph
+    app.get('/api/graph', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const graph = await withLbugDb(lbugPath, async () => buildGraph());
+            res.json(graph);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to build graph' });
+        }
+    });
+    // Execute Cypher query
+    app.post('/api/query', async (req, res) => {
+        try {
+            const cypher = req.body.cypher;
+            if (!cypher) {
+                res.status(400).json({ error: 'Missing "cypher" in request body' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const result = await withLbugDb(lbugPath, () => executeQuery(cypher));
+            res.json({ result });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Query failed' });
+        }
+    });
+    // Search
+    app.post('/api/search', async (req, res) => {
+        try {
+            const query = (req.body.query ?? '').trim();
+            if (!query) {
+                res.status(400).json({ error: 'Missing "query" in request body' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const parsedLimit = Number(req.body.limit ?? 10);
+            const limit = Number.isFinite(parsedLimit)
+                ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
+                : 10;
+            const results = await withLbugDb(lbugPath, async () => {
+                const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
+                if (isEmbedderReady()) {
+                    const { semanticSearch } = await import('../core/embeddings/embedding-pipeline.js');
+                    return hybridSearch(query, limit, executeQuery, semanticSearch);
+                }
+                // FTS-only fallback when embeddings aren't loaded
+                return searchFTSFromLbug(query, limit);
+            });
+            res.json({ results });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Search failed' });
+        }
+    });
+    // Read file — with path traversal guard
+    app.get('/api/file', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const filePath = req.query.path;
+            if (!filePath) {
+                res.status(400).json({ error: 'Missing path' });
+                return;
+            }
+            // Prevent path traversal — resolve and verify the path stays within the repo root
+            const repoRoot = path.resolve(entry.path);
+            const fullPath = path.resolve(repoRoot, filePath);
+            if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot) {
+                res.status(403).json({ error: 'Path traversal denied' });
+                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(500).json({ error: err.message || 'Failed to read file' });
+            }
+        }
+    });
+    // List all processes
+    app.get('/api/processes', async (req, res) => {
+        try {
+            const result = await backend.queryProcesses(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query processes' });
+        }
+    });
+    // Process detail
+    app.get('/api/process', async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryProcessDetail(name, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query process detail' });
+        }
+    });
+    // List all clusters
+    app.get('/api/clusters', async (req, res) => {
+        try {
+            const result = await backend.queryClusters(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query clusters' });
+        }
+    });
+    // Cluster detail
+    app.get('/api/cluster', async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryClusterDetail(name, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query cluster detail' });
+        }
+    });
+    // Global error handler — catch anything the route handlers miss
+    app.use((err, _req, res, _next) => {
+        console.error('Unhandled error:', err);
+        res.status(500).json({ error: 'Internal server error' });
+    });
+    const server = app.listen(port, host, () => {
+        console.log(`GitNexus server running on http://${host}:${port}`);
+    });
+    // Graceful shutdown — close Express + LadybugDB cleanly
+    const shutdown = async () => {
+        server.close();
+        await cleanupMcp();
+        await closeLbug();
+        await backend.disconnect();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+};

package/dist/server/mcp-http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import type { Express } from 'express';
+import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;

package/dist/server/mcp-http.js

@@ -0,0 +1,100 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMCPServer } from '../mcp/server.js';
+import { randomUUID } from 'crypto';
+/** Idle sessions are evicted after 30 minutes */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+/** Cleanup sweep runs every 5 minutes */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+export function mountMCPEndpoints(app, backend) {
+    const sessions = new Map();
+    // Periodic cleanup of idle sessions (guards against network drops)
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, session] of sessions) {
+            if (now - session.lastActivity > SESSION_TTL_MS) {
+                try {
+                    session.server.close();
+                }
+                catch { }
+                sessions.delete(id);
+            }
+        }
+    }, CLEANUP_INTERVAL_MS);
+    if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+        cleanupTimer.unref();
+    }
+    const handleMcpRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — delegate to its transport
+            const session = sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            await session.transport.handleRequest(req, res, req.body);
+        }
+        else if (sessionId) {
+            // Unknown/expired session ID — tell client to re-initialize (per MCP spec)
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32001, message: 'Session not found. Re-initialize.' },
+                id: null,
+            });
+        }
+        else if (req.method === 'POST') {
+            // No session ID — new client initializing
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const server = createMCPServer(backend);
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            if (transport.sessionId) {
+                sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
+                transport.onclose = () => {
+                    sessions.delete(transport.sessionId);
+                };
+            }
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'No valid session. Send a POST to initialize.' },
+                id: null,
+            });
+        }
+    };
+    app.all('/api/mcp', (req, res) => {
+        void handleMcpRequest(req, res).catch((err) => {
+            console.error('MCP HTTP request failed:', err);
+            if (res.headersSent)
+                return;
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Internal MCP server error' },
+                id: null,
+            });
+        });
+    });
+    const cleanup = async () => {
+        clearInterval(cleanupTimer);
+        const closers = [...sessions.values()].map(async (session) => {
+            try {
+                await Promise.resolve(session.server.close());
+            }
+            catch { }
+        });
+        sessions.clear();
+        await Promise.allSettled(closers);
+    };
+    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    return cleanup;
+}

package/dist/storage/git.d.ts

@@ -0,0 +1,6 @@
+export declare const isGitRepo: (repoPath: string) => boolean;
+export declare const getCurrentCommit: (repoPath: string) => string;
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export declare const getGitRoot: (fromPath: string) => string | null;

package/dist/storage/git.js

@@ -0,0 +1,35 @@
+import { execSync } from 'child_process';
+import path from 'path';
+// Git utilities for repository detection, commit tracking, and diff analysis
+export const isGitRepo = (repoPath) => {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd: repoPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getCurrentCommit = (repoPath) => {
+    try {
+        return execSync('git rev-parse HEAD', { cwd: repoPath }).toString().trim();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export const getGitRoot = (fromPath) => {
+    try {
+        const raw = execSync('git rev-parse --show-toplevel', { cwd: fromPath })
+            .toString()
+            .trim();
+        // On Windows, git returns /d/Projects/Foo — path.resolve normalizes to D:\Projects\Foo
+        return path.resolve(raw);
+    }
+    catch {
+        return null;
+    }
+};

package/dist/storage/repo-manager.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Repository Manager
+ *
+ * Manages GitNexus index storage in .gitnexus/ at repo root.
+ * Also maintains a global registry at ~/.gitnexus/registry.json
+ * so the MCP server can discover indexed repos from any cwd.
+ */
+export interface RepoMeta {
+    repoPath: string;
+    lastCommit: string;
+    indexedAt: string;
+    stats?: {
+        files?: number;
+        nodes?: number;
+        edges?: number;
+        communities?: number;
+        processes?: number;
+        embeddings?: number;
+    };
+}
+export interface IndexedRepo {
+    repoPath: string;
+    storagePath: string;
+    lbugPath: string;
+    metaPath: string;
+    meta: RepoMeta;
+}
+/**
+ * Shape of an entry in the global registry (~/.gitnexus/registry.json)
+ */
+export interface RegistryEntry {
+    name: string;
+    path: string;
+    storagePath: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RepoMeta['stats'];
+}
+/**
+ * Get the .gitnexus storage path for a repository
+ */
+export declare const getStoragePath: (repoPath: string) => string;
+/**
+ * Get paths to key storage files
+ */
+export declare const getStoragePaths: (repoPath: string) => {
+    storagePath: string;
+    lbugPath: string;
+    metaPath: string;
+};
+/**
+ * Check whether a KuzuDB index exists in the given storage path.
+ * Non-destructive — safe to call from status commands.
+ */
+export declare const hasKuzuIndex: (storagePath: string) => Promise<boolean>;
+/**
+ * Clean up stale KuzuDB files after migration to LadybugDB.
+ *
+ * Returns:
+ *   found        — true if .gitnexus/kuzu existed and was deleted
+ *   needsReindex — true if kuzu existed but lbug does not (re-analyze required)
+ *
+ * Callers own the user-facing messaging; this function only deletes files.
+ */
+export declare const cleanupOldKuzuFiles: (storagePath: string) => Promise<{
+    found: boolean;
+    needsReindex: boolean;
+}>;
+/**
+ * Load metadata from an indexed repo
+ */
+export declare const loadMeta: (storagePath: string) => Promise<RepoMeta | null>;
+/**
+ * Save metadata to storage
+ */
+export declare const saveMeta: (storagePath: string, meta: RepoMeta) => Promise<void>;
+/**
+ * Check if a path has a GitNexus index
+ */
+export declare const hasIndex: (repoPath: string) => Promise<boolean>;
+/**
+ * Load an indexed repo from a path
+ */
+export declare const loadRepo: (repoPath: string) => Promise<IndexedRepo | null>;
+/**
+ * Find .gitnexus by walking up from a starting path
+ */
+export declare const findRepo: (startPath: string) => Promise<IndexedRepo | null>;
+/**
+ * Add .gitnexus to .gitignore if not already present
+ */
+export declare const addToGitignore: (repoPath: string) => Promise<void>;
+/**
+ * Get the path to the global GitNexus directory
+ */
+export declare const getGlobalDir: () => string;
+/**
+ * Get the path to the global registry file
+ */
+export declare const getGlobalRegistryPath: () => string;
+/**
+ * Read the global registry. Returns empty array if not found.
+ */
+export declare const readRegistry: () => Promise<RegistryEntry[]>;
+/**
+ * Register (add or update) a repo in the global registry.
+ * Called after `gitnexus analyze` completes.
+ */
+export declare const registerRepo: (repoPath: string, meta: RepoMeta) => Promise<void>;
+/**
+ * Remove a repo from the global registry.
+ * Called after `gitnexus clean`.
+ */
+export declare const unregisterRepo: (repoPath: string) => Promise<void>;
+/**
+ * List all registered repos from the global registry.
+ * Optionally validates that each entry's .gitnexus/ still exists.
+ */
+export declare const listRegisteredRepos: (opts?: {
+    validate?: boolean;
+}) => Promise<RegistryEntry[]>;
+export interface CLIConfig {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * Get the path to the global CLI config file
+ */
+export declare const getGlobalConfigPath: () => string;
+/**
+ * Load CLI config from ~/.gitnexus/config.json
+ */
+export declare const loadCLIConfig: () => Promise<CLIConfig>;
+/**
+ * Save CLI config to ~/.gitnexus/config.json
+ */
+export declare const saveCLIConfig: (config: CLIConfig) => Promise<void>;