@codragraph/cli 2.1.1 → 2.1.5

package/dist/server/api.js

@@ -22,7 +22,8 @@ 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';
+import { getMcpHttpRouteGuidance, mountMCPEndpoints } from './mcp-http.js';
+import { HOSTED_WEB_APP_URL, getWebDashboardInfo, mountWebDashboard, } from './web-dashboard.js';
 import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { JobManager } from './analyze-job.js';
@@ -40,7 +41,7 @@ const pkg = _require('../../package.json');
  *     10.0.0.0/8      → 10.x.x.x
  *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
  *     192.168.0.0/16  → 192.168.x.x
- * - https://codragraph.vercel.app — the deployed CodraGraph web UI
+ * - Hosted CodraGraph web UI — defaults to https://codragraph.vercel.app
  *
  * @param origin - The value of the HTTP `Origin` request header, or `undefined`
  *                 when the header is absent (non-browser request).
@@ -57,7 +58,7 @@ export const isAllowedOrigin = (origin) => {
         origin === 'http://127.0.0.1' ||
         origin.startsWith('http://[::1]:') ||
         origin === 'http://[::1]' ||
-        origin === 'https://codragraph.vercel.app') {
+        origin === HOSTED_WEB_APP_URL) {
         return true;
     }
     // RFC 1918 private network ranges — allow any port on these hosts.
@@ -104,6 +105,30 @@ export const isIgnorableGraphQueryError = (err) => {
         message.includes('not found') ||
         message.includes('No table named'));
 };
+export const isGraphStoreCorruptionError = (err) => {
+    const message = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (message.includes('wal checksum') ||
+        (message.includes('wal') && message.includes('corrupt')) ||
+        (message.includes('checksum') && message.includes('corrupt')) ||
+        message.includes('database disk image is malformed') ||
+        message.includes('database image is malformed'));
+};
+export const getGraphStoreErrorResponse = (err, operation) => {
+    if (!isGraphStoreCorruptionError(err))
+        return null;
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        error: message || 'Graph store is corrupted',
+        code: 'GRAPHSTORE_CORRUPT',
+        operation,
+        recovery: [
+            'Stop overlapping codragraph serve, mcp, analyze, and embedding jobs for this repo.',
+            'Retry: npx @codragraph/cli analyze --force',
+            'If this repo had embeddings, preserve them with: npx @codragraph/cli analyze --force --embeddings',
+            'Only after approval, use: npx @codragraph/cli clean --force',
+        ],
+    };
+};
 const ensureStreamIsWritable = (res, signal) => {
     if (signal?.aborted || res.destroyed || res.writableEnded) {
         throw new ClientDisconnectedError();
@@ -355,6 +380,8 @@ const mountSSEProgress = (app, routePath, jm) => {
     });
 };
 const statusFromError = (err) => {
+    if (isGraphStoreCorruptionError(err))
+        return 503;
     const msg = String(err?.message ?? '');
     if (msg.includes('No indexed repositories') || msg.includes('not found'))
         return 404;
@@ -371,9 +398,14 @@ const requestedRepo = (req) => {
     }
     return undefined;
 };
-export const createServer = async (port, host = '127.0.0.1') => {
+export const createServer = async (port, host = '127.0.0.1', options = {}) => {
     const app = express();
     app.disable('x-powered-by');
+    let webDashboard = {
+        mode: options.web ?? 'local',
+        served: false,
+        hostedUrl: HOSTED_WEB_APP_URL,
+    };
     // CORS: allow localhost, private/LAN networks, and the deployed site.
     // Non-browser requests (curl, server-to-server) have no origin and are allowed.
     // Disallowed origins get the response without Access-Control-Allow-Origin,
@@ -520,7 +552,15 @@ export const createServer = async (port, host = '127.0.0.1') => {
         else {
             launchContext = 'global';
         }
-        res.json({ version: pkg.version, launchContext, nodeVersion: process.version });
+        const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
+        const apiBaseUrl = `http://${displayHost}:${port}`;
+        res.json({
+            version: pkg.version,
+            launchContext,
+            nodeVersion: process.version,
+            mcp: getMcpHttpRouteGuidance(),
+            web: getWebDashboardInfo(webDashboard, apiBaseUrl),
+        });
     });
     // List all registered repos
     app.get('/api/repos', async (_req, res) => {
@@ -995,10 +1035,13 @@ export const createServer = async (port, host = '127.0.0.1') => {
             if (err instanceof ClientDisconnectedError) {
                 return;
             }
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.graph');
             const message = err.message || 'Failed to build graph';
             if (res.headersSent) {
                 try {
-                    res.write(JSON.stringify({ type: 'error', error: message }) + '\n');
+                    res.write(JSON.stringify(graphStoreError
+                        ? { type: 'error', ...graphStoreError }
+                        : { type: 'error', error: message }) + '\n');
                 }
                 catch {
                     // Best-effort only after streaming has started.
@@ -1006,6 +1049,10 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.end();
                 return;
             }
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: message });
         }
     });
@@ -1031,6 +1078,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json({ result });
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.query');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: err.message || 'Query failed' });
         }
     });
@@ -1050,6 +1102,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json(result);
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.context');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(statusFromError(err)).json({ error: err.message || 'Context query failed' });
         }
     });
@@ -1070,6 +1127,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json(result);
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.impact');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(statusFromError(err)).json({ error: err.message || 'Impact query failed' });
         }
     });
@@ -1197,6 +1259,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json({ results });
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.search');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: err.message || 'Search failed' });
         }
     });
@@ -1813,6 +1880,7 @@ 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' });
     });
+    webDashboard = mountWebDashboard(app, { mode: options.web ?? 'local' });
     // Global error handler — catch anything the route handlers miss
     app.use((err, _req, res, _next) => {
         console.error('Unhandled error:', err);
@@ -1823,7 +1891,22 @@ export const createServer = async (port, host = '127.0.0.1') => {
     await new Promise((resolve, reject) => {
         const server = app.listen(port, host, () => {
             const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
-            console.log(`CodraGraph server running on http://${displayHost}:${port}`);
+            const localUrl = `http://${displayHost}:${port}`;
+            console.log(`CodraGraph server running on ${localUrl}`);
+            if (webDashboard.served) {
+                console.log(`Web dashboard: ${localUrl}`);
+            }
+            else if (webDashboard.mode === 'hosted') {
+                console.log(`Hosted dashboard: ${webDashboard.hostedUrl}`);
+                console.log(`Connect it to local API: ${localUrl}`);
+            }
+            else if (webDashboard.mode === 'off') {
+                console.log('Web dashboard disabled (--web off).');
+            }
+            else {
+                console.warn(`Web dashboard not bundled: ${webDashboard.reason}`);
+                console.warn(`Hosted dashboard: ${webDashboard.hostedUrl}`);
+            }
             resolve();
         });
         server.on('error', (err) => reject(err));

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

@@ -10,4 +10,26 @@
  */
 import type { Express } from 'express';
 import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare const MCP_HTTP_ENDPOINT = "/api/mcp";
+export declare const UNSUPPORTED_MCP_REST_EXAMPLE = "/api/mcp/tools/list";
+export interface McpHttpRouteGuidance {
+    endpoint: string;
+    transport: 'streamable-http';
+    note: string;
+    unsupportedRestExample: string;
+    powershellHealthCheck: string;
+    clientInstruction: string;
+}
+export declare const getMcpHttpRouteGuidance: () => McpHttpRouteGuidance;
+export declare const getUnsupportedMcpRestRouteResponse: (path: string) => {
+    endpoint: string;
+    transport: "streamable-http";
+    note: string;
+    unsupportedRestExample: string;
+    powershellHealthCheck: string;
+    clientInstruction: string;
+    error: string;
+    code: string;
+    unsupportedRoute: string;
+};
 export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;

package/dist/server/mcp-http.js

@@ -11,6 +11,22 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createMCPServer } from '../mcp/server.js';
 import { randomUUID } from 'crypto';
+export const MCP_HTTP_ENDPOINT = '/api/mcp';
+export const UNSUPPORTED_MCP_REST_EXAMPLE = '/api/mcp/tools/list';
+export const getMcpHttpRouteGuidance = () => ({
+    endpoint: MCP_HTTP_ENDPOINT,
+    transport: 'streamable-http',
+    note: 'HTTP MCP is a protocol endpoint, not a REST tools namespace.',
+    unsupportedRestExample: UNSUPPORTED_MCP_REST_EXAMPLE,
+    powershellHealthCheck: "Invoke-RestMethod -Uri 'http://127.0.0.1:4747/api/info' -TimeoutSec 10",
+    clientInstruction: 'Point an MCP client at http://127.0.0.1:4747/api/mcp using StreamableHTTP.',
+});
+export const getUnsupportedMcpRestRouteResponse = (path) => ({
+    error: 'Unsupported MCP HTTP REST route',
+    code: 'MCP_HTTP_REST_ROUTE_UNSUPPORTED',
+    unsupportedRoute: path,
+    ...getMcpHttpRouteGuidance(),
+});
 /** Idle sessions are evicted after 30 minutes */
 const SESSION_TTL_MS = 30 * 60 * 1000;
 /** Cleanup sweep runs every 5 minutes */
@@ -72,7 +88,7 @@ export function mountMCPEndpoints(app, backend) {
             });
         }
     };
-    app.all('/api/mcp', (req, res) => {
+    app.all(MCP_HTTP_ENDPOINT, (req, res) => {
         void handleMcpRequest(req, res).catch((err) => {
             console.error('MCP HTTP request failed:', err);
             if (res.headersSent)
@@ -84,6 +100,9 @@ export function mountMCPEndpoints(app, backend) {
             });
         });
     });
+    app.all(/^\/api\/mcp\/.+/, (req, res) => {
+        res.status(200).json(getUnsupportedMcpRestRouteResponse(req.path));
+    });
     const cleanup = async () => {
         clearInterval(cleanupTimer);
         const closers = [...sessions.values()].map(async (session) => {
@@ -95,6 +114,6 @@ export function mountMCPEndpoints(app, backend) {
         sessions.clear();
         await Promise.allSettled(closers);
     };
-    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    console.log(`MCP HTTP endpoint mounted at ${MCP_HTTP_ENDPOINT}`);
     return cleanup;
 }

package/dist/server/web-dashboard.d.ts

@@ -0,0 +1,28 @@
+import { type Express } from 'express';
+export declare const HOSTED_WEB_APP_URL: string;
+export type WebDashboardMode = 'local' | 'hosted' | 'off';
+export interface WebDashboardMountOptions {
+    mode?: WebDashboardMode;
+    webAppPath?: string;
+}
+export interface WebDashboardMount {
+    mode: WebDashboardMode;
+    served: boolean;
+    hostedUrl: string;
+    localPath?: string;
+    reason?: string;
+}
+export interface WebDashboardInfo {
+    mode: WebDashboardMode;
+    served: boolean;
+    localUrl: string | null;
+    hostedUrl: string;
+    apiBaseUrl: string;
+    reason?: string;
+}
+export declare const normalizeWebDashboardMode: (raw: string | undefined) => WebDashboardMode;
+export declare const getBundledWebAppCandidates: () => string[];
+export declare const hasWebDashboardIndex: (candidate: string) => boolean;
+export declare const resolveBundledWebAppPath: (candidates?: readonly string[]) => string | null;
+export declare const mountWebDashboard: (app: Express, options?: WebDashboardMountOptions) => WebDashboardMount;
+export declare const getWebDashboardInfo: (mount: WebDashboardMount, apiBaseUrl: string) => WebDashboardInfo;

package/dist/server/web-dashboard.js

@@ -0,0 +1,61 @@
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const HOSTED_WEB_APP_URL = process.env.CODRAGRAPH_WEB_URL || 'https://codragraph.vercel.app';
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export const normalizeWebDashboardMode = (raw) => {
+    const value = (raw ?? 'local').trim().toLowerCase();
+    if (value === 'local' || value === 'hosted' || value === 'off')
+        return value;
+    throw new Error(`Invalid web dashboard mode "${raw}". Use one of: local, hosted, off.`);
+};
+export const getBundledWebAppCandidates = () => [
+    // Published package: packages/core/dist/server/*.js -> packages/core/dist/web
+    path.resolve(moduleDir, '..', 'web'),
+    // Monorepo/dev fallback after running `npm --prefix apps/web run build`.
+    path.resolve(moduleDir, '..', '..', '..', '..', 'apps', 'web', 'dist'),
+];
+export const hasWebDashboardIndex = (candidate) => {
+    try {
+        return fs.statSync(path.join(candidate, 'index.html')).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+export const resolveBundledWebAppPath = (candidates = getBundledWebAppCandidates()) => {
+    for (const candidate of candidates) {
+        if (hasWebDashboardIndex(candidate))
+            return candidate;
+    }
+    return null;
+};
+export const mountWebDashboard = (app, options = {}) => {
+    const mode = options.mode ?? 'local';
+    if (mode !== 'local') {
+        return { mode, served: false, hostedUrl: HOSTED_WEB_APP_URL };
+    }
+    const webAppPath = options.webAppPath ?? resolveBundledWebAppPath();
+    if (!webAppPath || !hasWebDashboardIndex(webAppPath)) {
+        return {
+            mode,
+            served: false,
+            hostedUrl: HOSTED_WEB_APP_URL,
+            reason: 'Bundled web dashboard not found. Rebuild the package or use --web hosted.',
+        };
+    }
+    app.use(express.static(webAppPath, { index: false }));
+    app.get(/^\/(?!api(?:\/|$)).*/, (_req, res) => {
+        res.sendFile(path.join(webAppPath, 'index.html'));
+    });
+    return { mode, served: true, hostedUrl: HOSTED_WEB_APP_URL, localPath: webAppPath };
+};
+export const getWebDashboardInfo = (mount, apiBaseUrl) => ({
+    mode: mount.mode,
+    served: mount.served,
+    localUrl: mount.served ? apiBaseUrl : null,
+    hostedUrl: mount.hostedUrl,
+    apiBaseUrl,
+    reason: mount.reason,
+});