gitnexus 1.6.4-rc.2 → 1.6.4-rc.21

package/dist/core/run-analyze.js

@@ -12,6 +12,7 @@ import path from 'path';
 import fs from 'fs/promises';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
+import { createSearchFTSIndexes } from './search/fts-indexes.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
@@ -139,7 +140,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
         const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
         const scaled = Math.round(p.percent * 0.6);
-        progress(p.phase, scaled, phaseLabel);
+        const message = p.detail ? `${p.message || phaseLabel} (${p.detail})` : p.message || phaseLabel;
+        progress(p.phase, scaled, message);
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
@@ -165,12 +167,9 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             progress('lbug', pct, msg);
         });
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
-        // FTS indexes are created lazily on first `query`/`context` call instead
-        // of eagerly here. On small repos / CI runners the LadybugDB
-        // CREATE_FTS_INDEX cost is ~440 ms × 5 (≈2 s) regardless of table size,
-        // which dominated `analyze` runtime and pushed Windows CI past its
-        // 30 s test budget. Lazy creation is implemented in
-        // `core/search/bm25-index.ts` via `ensureFTSIndex`.
+        progress('fts', 85, 'Creating search indexes...');
+        await createSearchFTSIndexes();
+        progress('fts', 90, 'Search indexes ready');
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         if (cachedEmbeddings.length > 0) {
             const cachedDims = cachedEmbeddings[0].embedding.length;
@@ -199,6 +198,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
         const stats = await getLbugStats();
         let embeddingSkipped = true;
+        let semanticMode;
         if (shouldGenerateEmbeddings) {
             if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
                 embeddingSkipped = false;
@@ -220,7 +220,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             const { readServerMapping } = await import('./embeddings/server-mapping.js');
             const projectName = path.basename(repoPath);
             const serverName = await readServerMapping(projectName);
-            await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
+            const embeddingResult = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
                     ? httpMode
@@ -229,6 +229,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
                 progress('embeddings', scaled, label);
             }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, { repoName: projectName, serverName }, existingEmbeddings);
+            if (embeddingResult.semanticMode === 'exact-scan') {
+                semanticMode = 'exact-scan';
+                log('Semantic embeddings were generated without a VECTOR index; ' +
+                    'queries will use exact-scan fallback within the configured limit.');
+            }
+            else {
+                semanticMode = 'vector-index';
+            }
         }
         // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
         progress('done', 98, 'Saving metadata...');
@@ -236,11 +244,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         let embeddingCount = 0;
         try {
             const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
-            embeddingCount = embResult?.[0]?.cnt ?? 0;
+            const row = embResult?.[0];
+            embeddingCount = Number(row?.cnt ?? row?.[0] ?? 0);
         }
         catch {
             /* table may not exist if embeddings never ran */
         }
+        if (!embeddingSkipped && stats.nodes > 0 && embeddingCount === 0) {
+            throw new Error('Embedding generation completed without persisted embeddings. ' +
+                'The index was not registered to avoid silently reporting embeddings: 0.');
+        }
+        const { getRuntimeCapabilities } = await import('./platform/capabilities.js');
+        const runtimeCapabilities = getRuntimeCapabilities();
+        const effectiveSemanticMode = semanticMode ??
+            (runtimeCapabilities.semanticMode === 'vector-index' ? 'vector-index' : 'exact-scan');
         const meta = {
             repoPath,
             lastCommit: currentCommit,
@@ -260,6 +277,16 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 processes: pipelineResult.processResult?.stats.totalProcesses,
                 embeddings: embeddingCount,
             },
+            capabilities: {
+                graph: { provider: 'ladybugdb', status: runtimeCapabilities.graph },
+                fts: { provider: 'ladybugdb-fts', status: runtimeCapabilities.fts },
+                vectorSearch: {
+                    provider: effectiveSemanticMode === 'vector-index' ? 'ladybugdb-vector' : 'exact-scan',
+                    status: embeddingCount > 0 ? effectiveSemanticMode : 'unavailable',
+                    exactScanLimit: runtimeCapabilities.exactScanLimit,
+                    reason: runtimeCapabilities.reason,
+                },
+            },
         };
         await saveMeta(storagePath, meta);
         // Forward the --name alias and the registry-collision bypass bit.

package/dist/core/search/bm25-index.d.ts

@@ -3,12 +3,6 @@
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
  * Always reads from the database (no cached state to drift).
- *
- * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
- * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
- * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
- * small repos / CI runners) at the cost of paying that overhead on the
- * first `query`/`context` call in a session.
  */
 export interface BM25SearchResult {
     filePath: string;
@@ -16,17 +10,6 @@ export interface BM25SearchResult {
     rank: number;
     nodeIds?: string[];
 }
-/**
- * Drop all ensured-FTS cache entries for a given repoId.
- *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
- */
-export declare function invalidateEnsuredFTSForRepo(repoId: string): void;
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *

package/dist/core/search/bm25-index.js

@@ -3,96 +3,9 @@
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
  * Always reads from the database (no cached state to drift).
- *
- * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
- * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
- * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
- * small repos / CI runners) at the cost of paying that overhead on the
- * first `query`/`context` call in a session.
- */
-import { queryFTS, ensureFTSIndex } from '../lbug/lbug-adapter.js';
-/**
- * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
- * CLI/pipeline path and the MCP pool path use identical (table, index,
- * properties) tuples and the lazy-create logic stays in one place.
- */
-const FTS_INDEXES = [
-    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
-    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
-    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
-    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
-    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
-];
-/**
- * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
- * pairs have been ensured. The CLI/pipeline path gets its own cache inside
- * `lbug-adapter.ts` keyed by table/index, scoped to the singleton connection.
- *
- * IMPORTANT: an entry is added ONLY when the index was confirmed to exist
- * (CREATE_FTS_INDEX succeeded, or failed with `'already exists'`). Other
- * failures (transient lock errors, missing extension, etc.) leave the key
- * unset so the next query retries instead of silently caching the failure.
- *
- * Entries for a given repoId are invalidated when its pool is closed —
- * see the `addPoolCloseListener` registration in `searchFTSFromLbug`.
- */
-const ensuredPoolFTS = new Set();
-/**
- * Drop all ensured-FTS cache entries for a given repoId.
- *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
  */
-export function invalidateEnsuredFTSForRepo(repoId) {
-    const prefix = `${repoId}:`;
-    for (const key of ensuredPoolFTS) {
-        if (key.startsWith(prefix))
-            ensuredPoolFTS.delete(key);
-    }
-}
-/**
- * Tracks whether we've already wired the pool-close listener for this
- * process. The pool adapter is dynamically imported, so registration
- * happens lazily on the first MCP-pool-backed FTS query.
- */
-let poolCloseListenerRegistered = false;
-function registerPoolCloseListenerOnce(addPoolCloseListener) {
-    if (poolCloseListenerRegistered)
-        return;
-    poolCloseListenerRegistered = true;
-    addPoolCloseListener((repoId) => invalidateEnsuredFTSForRepo(repoId));
-}
-async function ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties) {
-    const key = `${repoId}:${table}:${indexName}`;
-    if (ensuredPoolFTS.has(key))
-        return;
-    const propList = properties.map((p) => `'${p}'`).join(', ');
-    try {
-        await executor(`CALL CREATE_FTS_INDEX('${table}', '${indexName}', [${propList}], stemmer := 'porter')`);
-        // Index was created successfully — safe to cache.
-        ensuredPoolFTS.add(key);
-    }
-    catch (e) {
-        // 'already exists' is the happy path (index persists on disk between
-        // process invocations) — cache it. Anything else is treated as a
-        // transient failure: surface a one-time warning and leave the key
-        // unset so the NEXT query retries rather than silently using a
-        // cached failure (which previously disabled BM25 for the whole
-        // process for that repo).
-        const msg = String(e?.message ?? '');
-        if (msg.includes('already exists')) {
-            ensuredPoolFTS.add(key);
-        }
-        else {
-            console.warn(`[gitnexus] FTS index ensure failed for repo "${repoId}" table "${table}" ` +
-                `(index "${indexName}"): ${msg || e}. Will retry on next query.`);
-        }
-    }
-}
+import { queryFTS } from '../lbug/lbug-adapter.js';
+import { FTS_INDEXES } from './fts-schema.js';
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
  * Returns the same shape as core queryFTS (from LadybugDB adapter).
@@ -134,41 +47,23 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  * @returns Ranked search results from FTS indexes
  */
 export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
-    let fileResults, functionResults, classResults, methodResults, interfaceResults;
+    const resultsByIndex = [];
     if (repoId) {
         // Use MCP connection pool via dynamic import
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
         const poolMod = await import('../lbug/pool-adapter.js');
-        const { executeQuery, addPoolCloseListener } = poolMod;
-        // Register the pool-close listener lazily on first use so a teardown of
-        // the pool entry (LRU eviction, idle timeout, explicit close) drops the
-        // matching `ensuredPoolFTS` entries. Without this, stale ensure-state
-        // can outlive the pool that produced it.
-        registerPoolCloseListenerOnce(addPoolCloseListener);
+        const { executeQuery } = poolMod;
         const executor = (cypher) => executeQuery(repoId, cypher);
-        // Lazy-create FTS indexes on first query for this repo (analyze no longer
-        // creates them up-front, so we ensure them here). Cached per-process.
-        for (const { table, indexName, properties } of FTS_INDEXES) {
-            await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
+        for (const { table, indexName } of FTS_INDEXES) {
+            resultsByIndex.push(await queryFTSViaExecutor(executor, table, indexName, query, limit));
         }
-        fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
-        functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
-        classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
-        methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
-        interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
-        // Lazy-create FTS indexes on first query (analyze no longer does it).
-        for (const { table, indexName, properties } of FTS_INDEXES) {
-            await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
+        for (const { table, indexName } of FTS_INDEXES) {
+            resultsByIndex.push(await queryFTS(table, indexName, query, limit, false).catch(() => []));
         }
-        fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
-        functionResults = await queryFTS('Function', 'function_fts', query, limit, false).catch(() => []);
-        classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
-        methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
-        interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
     }
     // Collect all node scores per filePath to track which nodes actually matched
     const fileNodeScores = new Map();
@@ -179,11 +74,8 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
             fileNodeScores.get(r.filePath).push({ score: r.score, nodeId: r.nodeId });
         }
     };
-    addResults(fileResults);
-    addResults(functionResults);
-    addResults(classResults);
-    addResults(methodResults);
-    addResults(interfaceResults);
+    for (const results of resultsByIndex)
+        addResults(results);
     // Sum the top-3 highest-scoring nodes per file and collect their nodeIds.
     // Summing all nodes naively inflates scores for files with many mediocre
     // matches (e.g. test files) over files with a single highly-relevant symbol.

package/dist/core/search/fts-indexes.d.ts

@@ -0,0 +1 @@
+export declare function createSearchFTSIndexes(): Promise<void>;

package/dist/core/search/fts-indexes.js

@@ -0,0 +1,7 @@
+import { createFTSIndex } from '../lbug/lbug-adapter.js';
+import { FTS_INDEXES } from './fts-schema.js';
+export async function createSearchFTSIndexes() {
+    for (const { table, indexName, properties } of FTS_INDEXES) {
+        await createFTSIndex(table, indexName, [...properties]);
+    }
+}

package/dist/core/search/fts-schema.d.ts

@@ -0,0 +1,6 @@
+export interface FTSIndexDefinition {
+    readonly table: string;
+    readonly indexName: string;
+    readonly properties: readonly string[];
+}
+export declare const FTS_INDEXES: readonly FTSIndexDefinition[];

package/dist/core/search/fts-schema.js

@@ -0,0 +1,7 @@
+export const FTS_INDEXES = [
+    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
+    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
+    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
+    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
+    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+];

package/dist/mcp/core/embedder.js

@@ -8,6 +8,7 @@ import { pipeline, env } from '@huggingface/transformers';
 import os from 'os';
 import { join } from 'path';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
+import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
@@ -37,11 +38,11 @@ export const initEmbedder = async () => {
             // when gitnexus is installed globally (e.g. /usr/lib/node_modules/).
             // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
             env.cacheDir = process.env.HF_HOME ?? join(os.homedir(), '.cache', 'huggingface');
+            const embeddingConfig = resolveEmbeddingConfig();
             console.error('GitNexus: Loading embedding model (first search may take a moment)...');
-            // Try GPU first (DirectML on Windows, CUDA on Linux), fall back to CPU
-            const isWindows = process.platform === 'win32';
-            const gpuDevice = isWindows ? 'dml' : 'cuda';
-            const devicesToTry = [gpuDevice, 'cpu'];
+            const devicesToTry = embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'
+                ? [embeddingConfig.device, 'cpu']
+                : ['cpu'];
             for (const device of devicesToTry) {
                 try {
                     // Silence stdout and stderr during model load — ONNX Runtime and transformers.js
@@ -55,6 +56,12 @@ export const initEmbedder = async () => {
                         embedderInstance = await pipeline('feature-extraction', MODEL_ID, {
                             device: device,
                             dtype: 'fp32',
+                            session_options: {
+                                logSeverityLevel: 3,
+                                intraOpNumThreads: embeddingConfig.threads,
+                                interOpNumThreads: 1,
+                                executionMode: 'sequential',
+                            },
                         });
                     }
                     finally {

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

@@ -18,7 +18,9 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
+import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (gitnexus analyze)
@@ -889,26 +891,59 @@ export class LocalBackend {
             const queryVec = await embedQuery(query);
             const dims = getEmbeddingDims();
             const queryVecStr = `[${queryVec.join(',')}]`;
-            const bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
-                const vectorQuery = `
-          CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
-            CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
-          YIELD node AS emb, distance
-          WITH emb, distance
-          WHERE distance < 0.6
-          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
-                 emb.startLine AS startLine, emb.endLine AS endLine, distance
-          ORDER BY distance
-        `;
-                const embResults = await executeQuery(repo.id, vectorQuery);
-                return embResults.map((row) => ({
+            let bestChunks = new Map();
+            try {
+                bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
+                    const vectorQuery = `
+            CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+              CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
+            YIELD node AS emb, distance
+            WITH emb, distance
+            WHERE distance < 0.6
+            RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                   emb.startLine AS startLine, emb.endLine AS endLine, distance
+            ORDER BY distance
+          `;
+                    const embResults = await executeQuery(repo.id, vectorQuery);
+                    return embResults.map((row) => ({
+                        nodeId: row.nodeId ?? row[0],
+                        chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+                        startLine: row.startLine ?? row[2] ?? 0,
+                        endLine: row.endLine ?? row[3] ?? 0,
+                        distance: row.distance ?? row[4],
+                    }));
+                });
+            }
+            catch {
+                bestChunks = new Map();
+            }
+            if (bestChunks.size === 0) {
+                const embeddingCount = Number(tableCheck[0].cnt ?? tableCheck[0][0] ?? 0);
+                const exactLimit = getExactScanLimit();
+                if (embeddingCount > exactLimit)
+                    return [];
+                const rows = await executeQuery(repo.id, `
+          MATCH (e:${EMBEDDING_TABLE_NAME})
+          RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
+                 e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
+        `);
+                const exactRows = rows.map((row) => ({
                     nodeId: row.nodeId ?? row[0],
                     chunkIndex: row.chunkIndex ?? row[1] ?? 0,
                     startLine: row.startLine ?? row[2] ?? 0,
                     endLine: row.endLine ?? row[3] ?? 0,
-                    distance: row.distance ?? row[4],
+                    embedding: row.embedding ?? row[4] ?? [],
                 }));
-            });
+                bestChunks = new Map(rankExactEmbeddingRows(exactRows, queryVec, limit, 0.6).map((row) => [
+                    row.nodeId,
+                    {
+                        distance: row.distance,
+                        chunkIndex: row.chunkIndex,
+                        startLine: row.startLine,
+                        endLine: row.endLine,
+                    },
+                ]));
+            }
             if (bestChunks.size === 0)
                 return [];
             const results = [];

package/dist/server/api.d.ts

@@ -41,6 +41,11 @@ export declare class ClientDisconnectedError extends Error {
     constructor();
 }
 export declare const isIgnorableGraphQueryError: (err: unknown) => boolean;
+export declare const SPA_FALLBACK_REGEX: RegExp;
+export declare const resolveWebDistDir: (primaryDir: string, fallbackDir: string) => Promise<string | null>;
+export declare const landingPageHtml: () => string;
+export declare const staticCacheControlSetHeaders: (res: express.Response, filePath: string) => void;
+export declare const registerWebUI: (app: express.Express, staticDir: string | null) => void;
 export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
 export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
 export declare const createServer: (port: number, host?: string) => Promise<void>;

package/dist/server/api.js

@@ -103,6 +103,98 @@ export const isIgnorableGraphQueryError = (err) => {
         message.includes('not found') ||
         message.includes('No table named'));
 };
+export const SPA_FALLBACK_REGEX = /^(?!\/api(?:\/|$))(?!.*\.\w{1,10}$).*/;
+export const resolveWebDistDir = async (primaryDir, fallbackDir) => {
+    const envDir = process.env.GITNEXUS_WEB_DIST;
+    const dirs = envDir ? [envDir, primaryDir, fallbackDir] : [primaryDir, fallbackDir];
+    for (const dir of dirs) {
+        try {
+            await fs.access(path.join(dir, 'index.html'));
+            return dir;
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT') {
+                console.warn(`[serve] could not access web UI dir ${dir}:`, err.message);
+            }
+        }
+    }
+    return null;
+};
+export const landingPageHtml = () => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>GitNexus</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:Outfit,system-ui,-apple-system,sans-serif;background:#06060a;color:#e4e4ed;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:1.5rem}
+.card{background:#101018;border:1px solid #2a2a3a;border-radius:0.75rem;padding:2rem;max-width:480px;width:100%}
+.logo{font-size:1.5rem;font-weight:700;color:#e4e4ed;letter-spacing:-0.02em;margin-bottom:0.25rem}
+.subtitle{font-size:0.875rem;color:#8888a0;margin-bottom:1.5rem}
+.section-title{font-size:0.75rem;font-weight:600;text-transform:uppercase;letter-spacing:0.05em;color:#5a5a70;margin-bottom:0.75rem}
+.endpoint{margin:0.25rem 0;font-size:0.875rem}
+.endpoint a{color:#7c3aed;text-decoration:none}
+.endpoint a:hover{text-decoration:underline}
+.endpoint code{background:#16161f;padding:0.15em 0.4em;border-radius:0.25rem;font-size:0.8rem;color:#8888a0}
+.divider{height:1px;background:#1e1e2a;margin:1.25rem 0}
+.terminal{background:#0a0a10;border:1px solid #1e1e2a;border-radius:0.5rem;padding:0.75rem 1rem;font-family:'SF Mono',SFMono-Regular,Consolas,'Liberation Mono',Menlo,monospace;font-size:0.8rem;color:#8888a0;margin-bottom:1rem;overflow-x:auto}
+.terminal .prompt{color:#7c3aed;user-select:none}
+.terminal .cmd{color:#e4e4ed}
+.link-row{display:flex;align-items:center;gap:0.5rem;font-size:0.875rem;margin-top:0.5rem}
+.link-row svg{flex-shrink:0}
+a.ext{color:#7c3aed;text-decoration:none;display:inline-flex;align-items:center;gap:0.25rem}
+a.ext:hover{text-decoration:underline}
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="logo">GitNexus</div>
+  <div class="subtitle">API server is running</div>
+  <div class="section-title">Endpoints</div>
+  <p class="endpoint"><a href="/api/info">/api/info</a> <span style="color:#5a5a70">— Server version &amp; context</span></p>
+  <p class="endpoint"><a href="/api/repos">/api/repos</a> <span style="color:#5a5a70">— Indexed repositories</span></p>
+  <p class="endpoint"><code>/api/heartbeat</code> <span style="color:#5a5a70">— SSE heartbeat</span></p>
+  <p class="endpoint"><code>/api/graph</code> <code>/api/query</code> <code>/api/search</code> <span style="color:#5a5a70">— Data</span></p>
+  <p class="endpoint"><code>/api/mcp</code> <span style="color:#5a5a70">— MCP over StreamableHTTP</span></p>
+  <div class="divider"></div>
+  <div class="section-title">Web UI not found</div>
+  <div class="terminal"><span class="prompt">$ </span><span class="cmd">cd gitnexus-web &amp;&amp; npm run build</span></div>
+  <div class="link-row">
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#7c3aed" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>
+    <a class="ext" href="https://gitnexus.vercel.app" target="_blank" rel="noopener noreferrer">gitnexus.vercel.app</a>
+    <span style="color:#5a5a70">— connects to this server</span>
+  </div>
+</div>
+</body>
+</html>`;
+export const staticCacheControlSetHeaders = (res, filePath) => {
+    if (filePath.endsWith('.html')) {
+        res.setHeader('Cache-Control', 'no-cache');
+    }
+    else {
+        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+    }
+};
+export const registerWebUI = (app, staticDir) => {
+    if (staticDir) {
+        app.use(express.static(staticDir, {
+            setHeaders: staticCacheControlSetHeaders,
+        }));
+        // ⚠ This must remain the LAST route before the global error handler.
+        // The regex excludes /api paths AND paths with file extensions (.js, .css, etc.)
+        // so missing assets get real 404s instead of the SPA HTML.
+        // Adding routes below this will be unreachable for non-API, non-asset paths.
+        app.get(SPA_FALLBACK_REGEX, (_req, res) => {
+            res.sendFile(path.join(staticDir, 'index.html'));
+        });
+    }
+    else {
+        app.get('/', (_req, res) => {
+            res.type('html').send(landingPageHtml());
+        });
+    }
+};
 const ensureStreamIsWritable = (res, signal) => {
     if (signal?.aborted || res.destroyed || res.writableEnded) {
         throw new ClientDisconnectedError();
@@ -1373,6 +1465,15 @@ export const createServer = async (port, host = '127.0.0.1') => {
         embedJobManager.cancelJob(req.params.jobId, 'Cancelled by user');
         res.json({ id: job.id, status: 'failed', error: 'Cancelled by user' });
     });
+    // ── Web UI (served at root) ───────────────────────────────────────
+    // Resolve the gitnexus-web dist directory relative to this file's location.
+    // In the published package: <pkg>/dist/server/api.js → <pkg>/web/
+    // In dev (tsx):            gitnexus/src/server/api.ts → gitnexus-web/dist/
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const webDistDir = path.resolve(__dirname, '..', '..', 'web');
+    const devWebDistDir = path.resolve(__dirname, '..', '..', '..', 'gitnexus-web', 'dist');
+    const staticDir = await resolveWebDistDir(webDistDir, devWebDistDir);
+    registerWebUI(app, staticDir);
     // Global error handler — catch anything the route handlers miss
     app.use((err, _req, res, _next) => {
         console.error('Unhandled error:', err);
@@ -1400,5 +1501,17 @@ export const createServer = async (port, host = '127.0.0.1') => {
         };
         process.once('SIGINT', shutdown);
         process.once('SIGTERM', shutdown);
+        // Catch-all crash guards (mirrors startMCPServer in mcp/server.ts)
+        let shuttingDown = false;
+        process.on('uncaughtException', (err) => {
+            console.error('GitNexus uncaughtException:', err?.stack || err);
+            if (!shuttingDown) {
+                shuttingDown = true;
+                shutdown().catch(() => { });
+            }
+        });
+        process.on('unhandledRejection', (reason) => {
+            console.error('GitNexus unhandledRejection:', reason?.stack || reason);
+        });
     });
 };

package/hooks/claude/gitnexus-hook.cjs

@@ -31,11 +31,21 @@ function readInput() {
  * Find the .gitnexus directory by walking up from startDir.
  * Returns the path to .gitnexus/ or null if not found.
  */
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
 function findGitNexusDir(startDir) {
   let dir = startDir || process.cwd();
   for (let i = 0; i < 5; i++) {
     const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;