/**
 * HTTP API Server
 *
 * REST API for browser-based clients to query the local .codragraph/ index.
 * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
 *
 * Security: binds to localhost by default (use --host to override).
 * CORS is restricted to localhost, private/LAN networks, and the deployed site.
 */
import express from 'express';
import cors from 'cors';
import path from 'path';
import fs from 'fs/promises';
import { createRequire } from 'node:module';
import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeCgdb, withCgdbDb, } from '../core/cgdb/cgdb-adapter.js';
import { isWriteQuery } from '../core/cgdb/pool-adapter.js';
import { decodeContentField } from '../core/cgdb/content-read.js';
import { NODE_TABLES } from '../_shared/index.js';
import { searchFTSFromCgdb } 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 { 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';
import { extractRepoName, getCloneDir, cloneOrPull } from './git-clone.js';
const _require = createRequire(import.meta.url);
const pkg = _require('../../package.json');
/**
 * Determine whether an HTTP Origin header value is allowed by CORS policy.
 *
 * Permitted origins:
 * - No origin (non-browser requests such as curl or server-to-server calls)
 * - http://localhost:<port> — local development
 * - http://127.0.0.1:<port> — loopback alias
 * - RFC 1918 private/LAN networks (any port):
 *     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
 * - 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).
 * @returns `true` if the origin is allowed, `false` otherwise.
 */
export const isAllowedOrigin = (origin) => {
    if (origin === undefined) {
        // Non-browser requests (curl, server-to-server) have no Origin header
        return true;
    }
    if (origin.startsWith('http://localhost:') ||
        origin === 'http://localhost' ||
        origin.startsWith('http://127.0.0.1:') ||
        origin === 'http://127.0.0.1' ||
        origin.startsWith('http://[::1]:') ||
        origin === 'http://[::1]' ||
        origin === HOSTED_WEB_APP_URL) {
        return true;
    }
    // RFC 1918 private network ranges — allow any port on these hosts.
    // We parse the hostname out of the origin URL and check against each range.
    let hostname;
    let protocol;
    try {
        const parsed = new URL(origin);
        hostname = parsed.hostname;
        protocol = parsed.protocol;
    }
    catch {
        // Malformed origin — reject
        return false;
    }
    // Only allow HTTP(S) origins — reject ftp://, file://, etc.
    if (protocol !== 'http:' && protocol !== 'https:')
        return false;
    const octets = hostname.split('.').map(Number);
    if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) {
        return false;
    }
    const [a, b] = octets;
    // 10.0.0.0/8
    if (a === 10)
        return true;
    // 172.16.0.0/12  →  172.16.x.x – 172.31.x.x
    if (a === 172 && b >= 16 && b <= 31)
        return true;
    // 192.168.0.0/16
    if (a === 192 && b === 168)
        return true;
    return false;
};
export class ClientDisconnectedError extends Error {
    constructor() {
        super('Client disconnected during graph stream');
        this.name = 'ClientDisconnectedError';
    }
}
export const isIgnorableGraphQueryError = (err) => {
    const message = err instanceof Error ? err.message : String(err);
    return (message.includes('does not exist') ||
        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();
    }
};
const waitForDrain = async (res, signal) => {
    ensureStreamIsWritable(res, signal);
    await new Promise((resolve, reject) => {
        const cleanup = () => {
            res.off('drain', onDrain);
            res.off('close', onClose);
            signal?.removeEventListener('abort', onAbort);
        };
        const onDrain = () => {
            cleanup();
            resolve();
        };
        const onClose = () => {
            cleanup();
            reject(new ClientDisconnectedError());
        };
        const onAbort = () => {
            cleanup();
            reject(new ClientDisconnectedError());
        };
        res.once('drain', onDrain);
        res.once('close', onClose);
        signal?.addEventListener('abort', onAbort, { once: true });
        if (signal?.aborted || res.destroyed || res.writableEnded) {
            onAbort();
        }
    });
    ensureStreamIsWritable(res, signal);
};
const isClientDisconnectWriteError = (err) => {
    if (!(err instanceof Error))
        return false;
    return (err.code === 'ERR_STREAM_DESTROYED' ||
        err.code === 'EPIPE' ||
        err.code === 'ECONNRESET' ||
        err.message.includes('write after end'));
};
export const writeNdjsonRecord = async (res, record, signal) => {
    ensureStreamIsWritable(res, signal);
    try {
        const canContinue = res.write(JSON.stringify(record) + '\n');
        if (!canContinue) {
            await waitForDrain(res, signal);
        }
    }
    catch (err) {
        if (isClientDisconnectWriteError(err)) {
            throw new ClientDisconnectedError();
        }
        throw err;
    }
};
const buildGraph = async (includeContent = false) => {
    const nodes = [];
    for (const table of NODE_TABLES) {
        try {
            const rows = await executeQuery(getNodeQuery(table, includeContent));
            for (const row of rows) {
                nodes.push(mapGraphNodeRow(table, row, includeContent));
            }
        }
        catch (err) {
            if (!isIgnorableGraphQueryError(err)) {
                throw err;
            }
        }
    }
    const relationships = [];
    const relRows = await executeQuery(GRAPH_RELATIONSHIP_QUERY);
    for (const row of relRows) {
        relationships.push(mapGraphRelationshipRow(row));
    }
    return { nodes, relationships };
};
const GRAPH_RELATIONSHIP_QUERY = `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 quoteNodeTable = (table) => `\`${table.replace(/`/g, '``')}\``;
const getNodeQuery = (table, includeContent) => {
    const tableLabel = quoteNodeTable(table);
    if (table === 'File') {
        return includeContent
            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content, n.contentEncoding AS contentEncoding`
            : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
    }
    if (table === 'Folder') {
        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
    }
    if (table === 'Community') {
        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.cohesion AS cohesion, n.symbolCount AS symbolCount`;
    }
    if (table === 'Process') {
        return `MATCH (n:${tableLabel}) 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`;
    }
    if (table === 'FeatureCluster') {
        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.slug AS slug, n.featureKind AS featureKind, n.summary AS summary, n.description AS description, n.repo AS repo, n.service AS service, n.signals AS signals, n.memberCount AS memberCount, n.entryPointIds AS entryPointIds, n.routes AS routes, n.tools AS tools, n.testCoverageHints AS testCoverageHints, n.lastIndexedCommit AS lastIndexedCommit, n.confidence AS confidence, n.source AS source`;
    }
    if (table === 'Route') {
        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware`;
    }
    if (table === 'Tool') {
        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
    }
    return includeContent
        ? `MATCH (n:${tableLabel}) 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, n.contentEncoding AS contentEncoding`
        : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
};
const mapGraphNodeRow = (table, row, includeContent) => ({
    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: includeContent ? decodeContentField(row.content, row.contentEncoding) : undefined,
        responseKeys: row.responseKeys,
        errorKeys: row.errorKeys,
        middleware: row.middleware,
        heuristicLabel: row.heuristicLabel,
        cohesion: row.cohesion,
        symbolCount: row.symbolCount,
        description: row.description,
        processType: row.processType,
        stepCount: row.stepCount,
        communities: row.communities,
        entryPointId: row.entryPointId,
        terminalId: row.terminalId,
        slug: row.slug,
        featureKind: row.featureKind,
        summary: row.summary,
        repo: row.repo,
        service: row.service,
        signals: row.signals,
        memberCount: row.memberCount,
        entryPointIds: row.entryPointIds,
        routes: row.routes,
        tools: row.tools,
        testCoverageHints: row.testCoverageHints,
        lastIndexedCommit: row.lastIndexedCommit,
        confidence: row.confidence,
        source: row.source,
    },
});
const mapGraphRelationshipRow = (row) => ({
    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,
});
export const streamGraphNdjson = async (res, includeContent = false, signal) => {
    for (const table of NODE_TABLES) {
        try {
            await streamQuery(getNodeQuery(table, includeContent), async (row) => {
                await writeNdjsonRecord(res, {
                    type: 'node',
                    data: mapGraphNodeRow(table, row, includeContent),
                }, signal);
            });
        }
        catch (err) {
            if (!isIgnorableGraphQueryError(err)) {
                throw err;
            }
        }
    }
    await streamQuery(GRAPH_RELATIONSHIP_QUERY, async (row) => {
        await writeNdjsonRecord(res, {
            type: 'relationship',
            data: mapGraphRelationshipRow(row),
        }, signal);
    });
};
/**
 * Mount an SSE progress endpoint for a JobManager.
 * Handles: initial state, terminal events, heartbeat, event IDs, client disconnect.
 */
const mountSSEProgress = (app, routePath, jm) => {
    app.get(routePath, (req, res) => {
        const job = jm.getJob(req.params.jobId);
        if (!job) {
            res.status(404).json({ error: 'Job not found' });
            return;
        }
        let eventId = 0;
        res.writeHead(200, {
            'Content-Type': 'text/event-stream',
            'Cache-Control': 'no-cache',
            Connection: 'keep-alive',
            'X-Accel-Buffering': 'no',
        });
        // Send current state immediately
        eventId++;
        res.write(`id: ${eventId}\ndata: ${JSON.stringify(job.progress)}\n\n`);
        // If already terminal, send event and close
        if (job.status === 'complete' || job.status === 'failed') {
            eventId++;
            res.write(`id: ${eventId}\nevent: ${job.status}\ndata: ${JSON.stringify({
                repoName: job.repoName,
                error: job.error,
            })}\n\n`);
            res.end();
            return;
        }
        // Heartbeat to detect zombie connections
        const heartbeat = setInterval(() => {
            try {
                res.write(':heartbeat\n\n');
            }
            catch {
                clearInterval(heartbeat);
                unsubscribe();
            }
        }, 30_000);
        // Subscribe to progress updates
        const unsubscribe = jm.onProgress(job.id, (progress) => {
            try {
                eventId++;
                if (progress.phase === 'complete' || progress.phase === 'failed') {
                    const eventJob = jm.getJob(req.params.jobId);
                    res.write(`id: ${eventId}\nevent: ${progress.phase}\ndata: ${JSON.stringify({
                        repoName: eventJob?.repoName,
                        error: eventJob?.error,
                    })}\n\n`);
                    clearInterval(heartbeat);
                    res.end();
                    unsubscribe();
                }
                else {
                    res.write(`id: ${eventId}\ndata: ${JSON.stringify(progress)}\n\n`);
                }
            }
            catch {
                clearInterval(heartbeat);
                unsubscribe();
            }
        });
        req.on('close', () => {
            clearInterval(heartbeat);
            unsubscribe();
        });
    });
};
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;
    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', 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,
    // so the browser blocks it. We pass `false` instead of throwing an Error to
    // avoid crashing into Express's default error handler (which returned 500).
    app.use(cors({
        origin: (origin, callback) => {
            callback(null, isAllowedOrigin(origin));
        },
    }));
    app.use(express.json({ limit: '10mb' }));
    // Support Chromium Private Network Access (required since Chrome 130+).
    // Without this header, Chrome/Edge/Brave/Arc block public->loopback requests
    // which breaks bridge mode entirely.
    app.use((_req, res, next) => {
        res.setHeader('Access-Control-Allow-Private-Network', 'true');
        next();
    });
    // Handle PNA preflight: Chromium sends Access-Control-Request-Private-Network
    // on OPTIONS requests and expects the allow header in the response.
    // Note: the actual Allow-Private-Network header is already set by the global
    // middleware above, so we just need to call next() here.
    app.options('*', (_req, res, next) => {
        next();
    });
    // Initialize MCP backend (multi-repo, shared across all MCP sessions)
    const backend = new LocalBackend();
    await backend.init();
    const cleanupMcp = mountMCPEndpoints(app, backend);
    const jobManager = new JobManager();
    // Shared repo lock — prevents concurrent analyze + embed on the same repo path,
    // which would corrupt LadybugDB (analyze calls closeCgdb + initCgdb while embed has queries in flight).
    const activeRepoPaths = new Set();
    const acquireRepoLock = (repoPath) => {
        if (activeRepoPaths.has(repoPath)) {
            return `Another job is already active for this repository`;
        }
        activeRepoPaths.add(repoPath);
        return null;
    };
    const releaseRepoLock = (repoPath) => {
        activeRepoPaths.delete(repoPath);
    };
    /**
     * Maximum time the hold-queue will wait for an active analysis job to complete.
     * Must stay in sync with the frontend's `fetchRepoInfo({ awaitAnalysis: true })` timeout.
     */
    const HOLD_QUEUE_TIMEOUT_SECS = 300; // 5 minutes
    // Helper: resolve a repo by name from the global registry, or default to first.
    // Pass `req` to enable early exit if the client disconnects during the hold-queue wait.
    const resolveRepo = async (repoName, isRetry = false, req) => {
        const repos = await listRegisteredRepos();
        let found = null;
        // Normalize: if a full path is passed, extract just the basename.
        // e.g. "C:\Users\LENOVO\.codragraph\repos\todo.txt-cli" -> "todo.txt-cli"
        const normalizedName = repoName ? path.basename(repoName) : undefined;
        if (normalizedName) {
            found =
                repos.find((r) => r.name === normalizedName) ||
                    repos.find((r) => r.name.toLowerCase() === normalizedName.toLowerCase()) ||
                    null;
        }
        else if (repos.length > 0) {
            found = repos[0]; // default to first repo
        }
        // If not yet in the registry, check whether a background job is actively cloning or
        // analyzing this repo. Hold the connection open (up to 5 minutes) until it completes.
        // We only wait for in-progress jobs ('queued'|'cloning'|'analyzing') — a 'complete' job
        // whose repo is still missing means the registry sync failed; the fallback below handles it.
        if (!found && normalizedName) {
            const lower = normalizedName.toLowerCase();
            // Track client disconnect to cancel the wait early
            let clientGone = false;
            req?.on('close', () => {
                clientGone = true;
            });
            for (const job of jobManager.listJobs()) {
                const isMatch = job.repoName?.toLowerCase() === lower ||
                    (job.repoUrl && path.basename(job.repoUrl).replace('.git', '').toLowerCase() === lower) ||
                    (job.repoPath && path.basename(job.repoPath).toLowerCase() === lower);
                if (isMatch && ['queued', 'cloning', 'analyzing'].includes(job.status)) {
                    if (process.env.DEBUG) {
                        console.log(`[debug] resolveRepo waiting for active job ${job.id} (${normalizedName})...`);
                    }
                    for (let wait = 0; wait < HOLD_QUEUE_TIMEOUT_SECS; wait++) {
                        if (clientGone)
                            return null; // client disconnected — stop polling
                        const currentJob = jobManager.getJob(job.id);
                        if (!currentJob || currentJob.status === 'failed')
                            break;
                        if (currentJob.status === 'complete') {
                            await backend.init();
                            const freshRepos = await listRegisteredRepos();
                            return freshRepos.find((r) => r.name === normalizedName) || null;
                        }
                        await new Promise((r) => setTimeout(r, 1000));
                    }
                    // Timed out — signal to the caller with a specific message
                    return { __timedOut: true, repoName: normalizedName };
                }
            }
        }
        // Emergency fallback: re-sync the registry to handle Windows file-system race conditions
        // (e.g. registry file not yet flushed after clone completes).
        if (!found && normalizedName && !isRetry) {
            if (process.env.DEBUG) {
                console.log(`[debug] resolveRepo 404 for "${normalizedName}". Triggering deep init...`);
            }
            await backend.init();
            return await resolveRepo(normalizedName, true, req);
        }
        return found;
    };
    // SSE heartbeat — clients connect to detect server liveness instantly.
    // When the server shuts down, the TCP connection drops and the client's
    // EventSource fires onerror immediately (no polling delay).
    app.get('/api/heartbeat', (_req, res) => {
        // Use res.set() instead of res.writeHead() to preserve CORS headers from middleware
        res.set({
            'Content-Type': 'text/event-stream',
            'Cache-Control': 'no-cache',
            Connection: 'keep-alive',
        });
        res.flushHeaders();
        // Send initial ping so the client knows it connected
        res.write(':ok\n\n');
        // Keep-alive ping every 15s to prevent proxy/firewall timeout
        const interval = setInterval(() => res.write(':ping\n\n'), 15_000);
        _req.on('close', () => clearInterval(interval));
    });
    // Server info: version and launch context (npx / global / local dev)
    app.get('/api/info', (_req, res) => {
        const execPath = process.env.npm_execpath ?? '';
        const argv0 = process.argv[1] ?? '';
        let launchContext;
        if (execPath.includes('npx') ||
            argv0.includes('_npx') ||
            process.env.npm_config_prefix?.includes('_npx')) {
            launchContext = 'npx';
        }
        else if (argv0.includes('node_modules')) {
            launchContext = 'local';
        }
        else {
            launchContext = 'global';
        }
        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) => {
        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), false, req);
            if (!entry) {
                res.status(404).json({ error: 'Repository not found. Run: codragraph analyze' });
                return;
            }
            // Timed out waiting for an active analysis job
            if (entry.__timedOut) {
                res.status(503).json({
                    error: `Repository analysis for "${entry.repoName}" is taking longer than expected. Please try again in a moment.`,
                });
                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' });
        }
    });
    // Delete a repo — removes index, clone dir (if any), and unregisters it
    app.delete('/api/repo', async (req, res) => {
        try {
            const repoName = requestedRepo(req);
            if (!repoName) {
                res.status(400).json({ error: 'Missing repo name' });
                return;
            }
            const entry = await resolveRepo(repoName);
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            // Acquire repo lock — prevents deleting while analyze/embed is in flight
            const lockKey = getStoragePath(entry.path);
            const lockErr = acquireRepoLock(lockKey);
            if (lockErr) {
                res.status(409).json({ error: lockErr });
                return;
            }
            try {
                // Close any open LadybugDB handle before deleting files
                try {
                    await closeCgdb();
                }
                catch { }
                // 1. Delete the .codragraph index/storage directory
                const storagePath = getStoragePath(entry.path);
                await fs.rm(storagePath, { recursive: true, force: true }).catch(() => { });
                // 2. Delete the cloned repo dir if it lives under ~/.codragraph/repos/
                const cloneDir = getCloneDir(entry.name);
                try {
                    const stat = await fs.stat(cloneDir);
                    if (stat.isDirectory()) {
                        await fs.rm(cloneDir, { recursive: true, force: true });
                    }
                }
                catch {
                    /* clone dir may not exist (local repos) */
                }
                // 3. Unregister from the global registry
                const { unregisterRepo } = await import('../storage/repo-manager.js');
                await unregisterRepo(entry.path);
                // 4. Reinitialize backend to reflect the removal
                await backend.init().catch(() => { });
                res.json({ deleted: entry.name });
            }
            finally {
                releaseRepoLock(lockKey);
            }
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'Failed to delete repo' });
        }
    });
    // ─── Phase 4: versioned graph (graphstore) ─────────────────────────
    //
    // Each route resolves the repo, then delegates to the same handler
    // module the MCP server uses (mcp/local/graphstore-handler.ts) so
    // there is a single source of truth for serialization.
    app.get('/api/graphstore/log', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { handleGraphstoreLog } = await import('../mcp/local/graphstore-handler.js');
            const limitParam = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined;
            const result = await handleGraphstoreLog({
                storagePath: entry.storagePath,
                from: typeof req.query.from === 'string' ? req.query.from : undefined,
                limit: Number.isFinite(limitParam) ? limitParam : undefined,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphstore log failed' });
        }
    });
    app.get('/api/graphstore/branches', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { handleGraphstoreBranches } = await import('../mcp/local/graphstore-handler.js');
            const result = await handleGraphstoreBranches({ storagePath: entry.storagePath });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphstore branches failed' });
        }
    });
    app.get('/api/graphstore/diff', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const from = typeof req.query.from === 'string' ? req.query.from : '';
            const to = typeof req.query.to === 'string' ? req.query.to : '';
            if (!from || !to) {
                res
                    .status(400)
                    .json({ error: 'graphstore diff requires both `from` and `to` query params' });
                return;
            }
            const { handleGraphstoreDiff } = await import('../mcp/local/graphstore-handler.js');
            const result = await handleGraphstoreDiff({ storagePath: entry.storagePath, from, to });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphstore diff failed' });
        }
    });
    // Higher-fidelity diff: classifies modifications + surfaces added /
    // removed exported APIs and Processes. The dashboard's "what broke
    // / what fixed" panel renders this.
    app.get('/api/graphstore/semantic-diff', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const from = typeof req.query.from === 'string' ? req.query.from : '';
            const to = typeof req.query.to === 'string' ? req.query.to : '';
            if (!from || !to) {
                res.status(400).json({
                    error: 'graphstore semantic-diff requires both `from` and `to` query params',
                });
                return;
            }
            const { handleGraphstoreSemanticDiff } = await import('../mcp/local/graphstore-handler.js');
            const result = await handleGraphstoreSemanticDiff({
                storagePath: entry.storagePath,
                from,
                to,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphstore semantic-diff failed' });
        }
    });
    // ─── Phase 4 × Phase 3 moat: harness recipes ───────────────────────
    //
    // Lazy-imports the handler from codragraph-harness so the package
    // stays optional at runtime — same pattern as harness_run /
    // harness_swarm_run in local-backend.ts.
    app.get('/api/graphpack/status', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { getGraphpackStatus } = await import('../core/graphpack/index.js');
            const result = await getGraphpackStatus({
                repoPath: entry.path,
                storagePath: entry.storagePath,
                strict: req.query.strict === 'true',
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphpack status failed' });
        }
    });
    app.get('/api/graphpack/lock', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { defaultLockPath, readGraphpackLock } = await import('../core/graphpack/index.js');
            const lock = await readGraphpackLock(defaultLockPath(entry.path));
            if (!lock) {
                res.status(404).json({ error: 'No .codragraph/index.lock.json found' });
                return;
            }
            res.json(lock);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphpack lock failed' });
        }
    });
    app.post('/api/graphpack/publish', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { publishGraphpack } = await import('../core/graphpack/index.js');
            const body = (req.body ?? {});
            const result = await publishGraphpack({
                repoPath: entry.path,
                storagePath: entry.storagePath,
                repoName: typeof body.repo === 'string' ? body.repo : entry.name,
                analyzerVersion: typeof body.analyzerVersion === 'string' ? body.analyzerVersion : 'http',
                target: body.target === 'pr' ? 'pr' : 'main',
                artifactDir: typeof body.artifactDir === 'string' ? body.artifactDir : undefined,
                artifactUrl: typeof body.artifactUrl === 'string' ? body.artifactUrl : undefined,
                baseSnapshotId: typeof body.baseSnapshotId === 'string' ? body.baseSnapshotId : undefined,
                headSnapshotId: typeof body.headSnapshotId === 'string' ? body.headSnapshotId : undefined,
                pullRequest: typeof body.pullRequest === 'string' ? body.pullRequest : undefined,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphpack publish failed' });
        }
    });
    app.post('/api/graphpack/pull', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { pullGraphpack } = await import('../core/graphpack/index.js');
            const body = (req.body ?? {});
            const result = await pullGraphpack({
                repoPath: entry.path,
                storagePath: entry.storagePath,
                artifactDir: typeof body.artifactDir === 'string' ? body.artifactDir : undefined,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'graphpack pull failed' });
        }
    });
    app.get('/api/semantic/relationships', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const { analyzeSemanticRelationships } = await import('../core/semantic/relationships.js');
            const limit = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined;
            const result = await analyzeSemanticRelationships({
                storagePath: entry.storagePath,
                limit: Number.isFinite(limit) ? limit : 1000,
                llm: req.query.llm === 'true',
                write: false,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'semantic relationships failed' });
        }
    });
    const importRecipeHandler = async (handlerName) => {
        const moduleId = '@codragraph/harness/mcp/handler';
        try {
            const mod = (await import(/* @vite-ignore */ moduleId));
            const fn = mod[handlerName];
            if (typeof fn !== 'function') {
                throw new Error(`codragraph-harness does not export ${handlerName}`);
            }
            return fn;
        }
        catch (err) {
            throw new Error(`recipes endpoint requires codragraph-harness to be installed: ${err?.message ?? String(err)}`);
        }
    };
    app.get('/api/recipes', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const limitParam = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined;
            const handler = await importRecipeHandler('handleHarnessRecipesList');
            const result = await handler({
                recipe_store: path.join(entry.storagePath, 'recipes'),
                task_family: typeof req.query.task_family === 'string' ? req.query.task_family : undefined,
                snapshot_id: typeof req.query.snapshot_id === 'string' ? req.query.snapshot_id : undefined,
                required_subgraph_signature: typeof req.query.required_subgraph_signature === 'string'
                    ? req.query.required_subgraph_signature
                    : undefined,
                limit: Number.isFinite(limitParam) ? limitParam : undefined,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'recipes list failed' });
        }
    });
    app.get('/api/recipes/lookup', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const taskFamily = typeof req.query.task_family === 'string' ? req.query.task_family : '';
            const snapshotId = typeof req.query.snapshot_id === 'string' ? req.query.snapshot_id : '';
            if (!taskFamily || !snapshotId) {
                res.status(400).json({
                    error: 'recipes lookup requires `task_family` and `snapshot_id` query params',
                });
                return;
            }
            const handler = await importRecipeHandler('handleHarnessRecipesLookup');
            const result = await handler({
                recipe_store: path.join(entry.storagePath, 'recipes'),
                task_family: taskFamily,
                snapshot_id: snapshotId,
                required_subgraph_signature: typeof req.query.required_subgraph_signature === 'string'
                    ? req.query.required_subgraph_signature
                    : undefined,
                limit: typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : undefined,
            });
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'recipes lookup failed' });
        }
    });
    // Read one recipe's full content (harness body, scores, provenance)
    // by id. Powers the dashboard's recipe-detail drawer. Reads the file
    // directly from the FsRecipeStore layout under
    // `<storagePath>/recipes/by-id/<sanitized-id>.json` rather than going
    // through the MCP handler — the listing endpoint already covers
    // search and we want this route to be cheap and focused.
    app.get('/api/recipes/by-id/:id', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const safeId = req.params.id.replace(/[^A-Za-z0-9._-]/g, '_');
            const recipePath = path.join(entry.storagePath, 'recipes', 'by-id', `${safeId}.json`);
            try {
                const raw = await fs.readFile(recipePath, 'utf-8');
                res.type('application/json').send(raw);
            }
            catch (err) {
                if (err?.code === 'ENOENT') {
                    res.status(404).json({ error: `recipe ${req.params.id} not found` });
                    return;
                }
                throw err;
            }
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'recipe by-id failed' });
        }
    });
    // ─── Cross-repo groups (multi-repo + monorepo bridges) ─────────────
    //
    // Groups bundle multiple registered repos under a single name and
    // declare contract links between them (HTTP/gRPC/topic/lib). The
    // dashboard's Projects tab consumes these to render: which repos a
    // user's project is part of, what contracts cross between them, and
    // which sibling clones are stale.
    //
    // Each route delegates to the same group service the MCP layer uses
    // (LocalBackend.getGroupService) so there is one source of truth.
    const getGroupSvc = () => backend.getGroupService();
    app.get('/api/groups', async (_req, res) => {
        try {
            const result = (await getGroupSvc().groupList({}));
            res.json({ groups: result.groups ?? [] });
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'group list failed' });
        }
    });
    // Reverse lookup: MUST be registered BEFORE `/api/groups/:name` so
    // Express matches the literal `for-repo` segment first instead of
    // treating it as a group name parameter.
    app.get('/api/groups/for-repo', async (req, res) => {
        try {
            const repoName = typeof req.query.repo === 'string' ? req.query.repo : '';
            if (!repoName) {
                res.status(400).json({ error: 'repo query param is required' });
                return;
            }
            const svc = getGroupSvc();
            const list = (await svc.groupList({}));
            const matches = [];
            for (const groupName of list.groups ?? []) {
                const details = (await svc.groupList({ name: groupName }));
                if (!details.repos)
                    continue;
                for (const [groupPath, registryName] of Object.entries(details.repos)) {
                    if (registryName === repoName) {
                        matches.push({ group: groupName, groupPath });
                    }
                }
            }
            res.json({ repo: repoName, groups: matches });
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'groups-for-repo failed' });
        }
    });
    app.get('/api/groups/:name', async (req, res) => {
        try {
            const result = await getGroupSvc().groupList({ name: req.params.name });
            if (result.error) {
                res.status(404).json(result);
                return;
            }
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'group details failed' });
        }
    });
    app.get('/api/groups/:name/contracts', async (req, res) => {
        try {
            const params = { name: req.params.name };
            if (typeof req.query.type === 'string')
                params.type = req.query.type;
            if (typeof req.query.repo === 'string')
                params.repo = req.query.repo;
            if (req.query.unmatchedOnly === 'true')
                params.unmatchedOnly = true;
            const result = await getGroupSvc().groupContracts(params);
            const e = result.error;
            if (e) {
                res.status(e.toLowerCase().includes('not found') ? 404 : 400).json(result);
                return;
            }
            res.json(result);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'group contracts failed' });
        }
    });
    app.get('/api/groups/:name/status', async (req, res) => {
        try {
            const yaml = await backend.readGroupStatusResource(req.params.name);
            res.type('text/yaml').send(yaml);
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'group status failed' });
        }
    });
    // 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 cgdbPath = path.join(entry.storagePath, 'cgdb');
            const includeContent = req.query.includeContent === 'true';
            const stream = req.query.stream === 'true';
            // Guard: when a repo has no materialized cgdb schema (fixture-
            // seeded CAS-only repos), or the cgdb WAL is corrupt/stale from
            // a prior failed analyze, LadybugDB native will abort with
            // UNREACHABLE_CODE or an ANY-vector exception. Detect both
            // shapes — missing file (cheap fs.access) AND empty/4096-byte
            // schema-only file (fs.stat) — and return an empty graph so
            // the dashboard doesn't blow up. The Graph tab keeps working
            // for repos that actually have a real cgdb.
            const isCgdbMaterialized = await (async () => {
                try {
                    const stat = await fs.stat(cgdbPath);
                    // Schema-only cgdb is exactly 4096 bytes (one page, no real
                    // data). Real graphs are larger.
                    return stat.isFile() && stat.size > 4096;
                }
                catch {
                    return false;
                }
            })();
            if (!isCgdbMaterialized) {
                if (stream) {
                    res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
                    res.flushHeaders();
                    res.write(JSON.stringify({
                        type: 'meta',
                        repoName: entry.name,
                        note: 'no cgdb file — graph not yet materialized',
                        nodeCount: 0,
                        relationshipCount: 0,
                    }) + '\n');
                    res.end();
                    return;
                }
                res.json({
                    repoName: entry.name,
                    repoPath: entry.path,
                    nodes: [],
                    relationships: [],
                    stats: { nodes: 0, edges: 0 },
                    note: 'no cgdb file — graph not yet materialized',
                });
                return;
            }
            if (stream) {
                const abortController = new AbortController();
                let responseFinished = false;
                const markFinished = () => {
                    responseFinished = true;
                };
                const abortStreaming = () => {
                    if (!responseFinished) {
                        abortController.abort();
                    }
                };
                res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
                res.setHeader('Cache-Control', 'no-cache');
                res.flushHeaders();
                req.once('aborted', abortStreaming);
                res.once('finish', markFinished);
                res.once('close', abortStreaming);
                try {
                    await withCgdbDb(cgdbPath, async () => streamGraphNdjson(res, includeContent, abortController.signal));
                    if (!abortController.signal.aborted && !res.writableEnded) {
                        res.end();
                    }
                }
                finally {
                    req.off('aborted', abortStreaming);
                    res.off('finish', markFinished);
                    res.off('close', abortStreaming);
                }
                return;
            }
            const graph = await withCgdbDb(cgdbPath, async () => buildGraph(includeContent));
            res.json(graph);
        }
        catch (err) {
            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(graphStoreError
                        ? { type: 'error', ...graphStoreError }
                        : { type: 'error', error: message }) + '\n');
                }
                catch {
                    // Best-effort only after streaming has started.
                }
                res.end();
                return;
            }
            if (graphStoreError) {
                res.status(503).json(graphStoreError);
                return;
            }
            res.status(500).json({ error: message });
        }
    });
    // 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;
            }
            if (isWriteQuery(cypher)) {
                res.status(403).json({ error: 'Write queries are not allowed via the HTTP API' });
                return;
            }
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const cgdbPath = path.join(entry.storagePath, 'cgdb');
            const result = await withCgdbDb(cgdbPath, () => executeQuery(cypher));
            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' });
        }
    });
    // Symbol context through the same LocalBackend path as MCP `context`
    app.post('/api/context', async (req, res) => {
        try {
            const name = String(req.body?.name ?? '').trim();
            if (!name) {
                res.status(400).json({ error: 'Missing "name" in request body' });
                return;
            }
            const result = await backend.callTool('context', {
                ...req.body,
                name,
                repo: requestedRepo(req),
            });
            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' });
        }
    });
    // Symbol impact through the same LocalBackend path as MCP `impact`
    app.post('/api/impact', async (req, res) => {
        try {
            const target = String(req.body?.target ?? '').trim();
            if (!target) {
                res.status(400).json({ error: 'Missing "target" in request body' });
                return;
            }
            const result = await backend.callTool('impact', {
                ...req.body,
                target,
                direction: req.body?.direction ?? 'upstream',
                repo: requestedRepo(req),
            });
            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' });
        }
    });
    // Search (supports mode: 'hybrid' | 'semantic' | 'bm25', and optional enrichment)
    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 cgdbPath = path.join(entry.storagePath, 'cgdb');
            const parsedLimit = Number(req.body.limit ?? 10);
            const limit = Number.isFinite(parsedLimit)
                ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
                : 10;
            const mode = req.body.mode ?? 'hybrid';
            const enrich = req.body.enrich !== false; // default true
            const results = await withCgdbDb(cgdbPath, async () => {
                let searchResults;
                if (mode === 'semantic') {
                    const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
                    if (!isEmbedderReady()) {
                        return [];
                    }
                    const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
                    searchResults = await semSearch(executeQuery, query, limit);
                    // Normalize semantic results to HybridSearchResult shape
                    searchResults = searchResults.map((r, i) => ({
                        ...r,
                        score: r.score ?? 1 - (r.distance ?? 0),
                        rank: i + 1,
                        sources: ['semantic'],
                    }));
                }
                else if (mode === 'bm25') {
                    searchResults = await searchFTSFromCgdb(query, limit);
                    searchResults = searchResults.map((r, i) => ({
                        ...r,
                        rank: i + 1,
                        sources: ['bm25'],
                    }));
                }
                else {
                    // hybrid (default)
                    const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
                    if (isEmbedderReady()) {
                        const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
                        searchResults = await hybridSearch(query, limit, executeQuery, semSearch);
                    }
                    else {
                        searchResults = await searchFTSFromCgdb(query, limit);
                    }
                }
                if (!enrich)
                    return searchResults;
                // Server-side enrichment: add connections, cluster, processes per result
                // Uses parameterized queries to prevent Cypher injection via nodeId
                const validLabel = (label) => NODE_TABLES.includes(label);
                const enriched = await Promise.all(searchResults.slice(0, limit).map(async (r) => {
                    const nodeId = r.nodeId || r.id || '';
                    const nodeLabel = nodeId.split(':')[0];
                    const enrichment = {};
                    if (!nodeId || !validLabel(nodeLabel))
                        return { ...r, ...enrichment };
                    // Run connections, cluster, and process queries in parallel
                    // Label is validated against NODE_TABLES (compile-time safe identifiers);
                    // nodeId uses $nid parameter binding to prevent injection
                    const [connRes, clusterRes, procRes] = await Promise.all([
                        executePrepared(`
              MATCH (n:${nodeLabel} {id: $nid})
              OPTIONAL MATCH (n)-[r1:CodeRelation]->(dst)
              OPTIONAL MATCH (src)-[r2:CodeRelation]->(n)
              RETURN
                collect(DISTINCT {name: dst.name, type: r1.type, confidence: r1.confidence}) AS outgoing,
                collect(DISTINCT {name: src.name, type: r2.type, confidence: r2.confidence}) AS incoming
              LIMIT 1
            `, { nid: nodeId }).catch(() => []),
                        executePrepared(`
              MATCH (n:${nodeLabel} {id: $nid})
              MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
              RETURN c.label AS label, c.description AS description
              LIMIT 1
            `, { nid: nodeId }).catch(() => []),
                        executePrepared(`
              MATCH (n:${nodeLabel} {id: $nid})
              MATCH (n)-[rel:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
              RETURN p.id AS id, p.label AS label, rel.step AS step, p.stepCount AS stepCount
              ORDER BY rel.step
            `, { nid: nodeId }).catch(() => []),
                    ]);
                    if (connRes.length > 0) {
                        const row = connRes[0];
                        const outgoing = (Array.isArray(row) ? row[0] : row.outgoing || [])
                            .filter((c) => c?.name)
                            .slice(0, 5);
                        const incoming = (Array.isArray(row) ? row[1] : row.incoming || [])
                            .filter((c) => c?.name)
                            .slice(0, 5);
                        enrichment.connections = { outgoing, incoming };
                    }
                    if (clusterRes.length > 0) {
                        const row = clusterRes[0];
                        enrichment.cluster = Array.isArray(row) ? row[0] : row.label;
                    }
                    if (procRes.length > 0) {
                        enrichment.processes = procRes
                            .map((row) => ({
                            id: Array.isArray(row) ? row[0] : row.id,
                            label: Array.isArray(row) ? row[1] : row.label,
                            step: Array.isArray(row) ? row[2] : row.step,
                            stepCount: Array.isArray(row) ? row[3] : row.stepCount,
                        }))
                            .filter((p) => p.id && p.label);
                    }
                    return { ...r, ...enrichment };
                }));
                return enriched;
            });
            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' });
        }
    });
    // 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 raw = await fs.readFile(fullPath, 'utf-8');
            // Optional line-range support: ?startLine=10&endLine=50
            // Returns only the requested slice (0-indexed), plus metadata.
            const startLine = req.query.startLine !== undefined ? Number(req.query.startLine) : undefined;
            const endLine = req.query.endLine !== undefined ? Number(req.query.endLine) : undefined;
            if (startLine !== undefined && Number.isFinite(startLine)) {
                const lines = raw.split('\n');
                const start = Math.max(0, startLine);
                const end = endLine !== undefined && Number.isFinite(endLine)
                    ? Math.min(lines.length, endLine + 1)
                    : lines.length;
                res.json({
                    content: lines.slice(start, end).join('\n'),
                    startLine: start,
                    endLine: end - 1,
                    totalLines: lines.length,
                });
            }
            else {
                res.json({ content: raw, totalLines: raw.split('\n').length });
            }
        }
        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' });
            }
        }
    });
    // Grep — regex search across file contents in the indexed repo
    // Uses filesystem-based search for memory efficiency (never loads all files into memory)
    app.get('/api/grep', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            const pattern = req.query.pattern;
            if (!pattern) {
                res.status(400).json({ error: 'Missing "pattern" query parameter' });
                return;
            }
            // ReDoS protection: reject overly long or dangerous patterns
            if (pattern.length > 200) {
                res.status(400).json({ error: 'Pattern too long (max 200 characters)' });
                return;
            }
            // Validate regex syntax
            let regex;
            try {
                regex = new RegExp(pattern, 'gim');
            }
            catch {
                res.status(400).json({ error: 'Invalid regex pattern' });
                return;
            }
            const parsedLimit = Number(req.query.limit ?? 50);
            const limit = Number.isFinite(parsedLimit)
                ? Math.max(1, Math.min(200, Math.trunc(parsedLimit)))
                : 50;
            const results = [];
            const repoRoot = path.resolve(entry.path);
            // Get file paths from the graph (lightweight — no content loaded)
            const cgdbPath = path.join(entry.storagePath, 'cgdb');
            const fileRows = await withCgdbDb(cgdbPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`));
            // Search files on disk one at a time (constant memory)
            for (const row of fileRows) {
                if (results.length >= limit)
                    break;
                const filePath = row.filePath || '';
                const fullPath = path.resolve(repoRoot, filePath);
                // Path traversal guard
                if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot)
                    continue;
                let content;
                try {
                    content = await fs.readFile(fullPath, 'utf-8');
                }
                catch {
                    continue; // File may have been deleted since indexing
                }
                const lines = content.split('\n');
                for (let i = 0; i < lines.length; i++) {
                    if (results.length >= limit)
                        break;
                    if (regex.test(lines[i])) {
                        results.push({ filePath, line: i + 1, text: lines[i].trim().slice(0, 200) });
                    }
                    regex.lastIndex = 0;
                }
            }
            res.json({ results });
        }
        catch (err) {
            res.status(500).json({ error: err.message || 'Grep failed' });
        }
    });
    // 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' });
        }
    });
    // List all feature clusters
    app.get('/api/feature-clusters', async (req, res) => {
        try {
            const limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
            const query = String(req.query.query ?? '');
            const result = await backend.queryFeatureClusters(requestedRepo(req), limit, query);
            res.json(result);
        }
        catch (err) {
            res
                .status(statusFromError(err))
                .json({ error: err.message || 'Failed to query feature clusters' });
        }
    });
    // Feature cluster detail
    app.get('/api/feature-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 limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
            const result = await backend.queryFeatureContext(name, requestedRepo(req), limit);
            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 feature cluster detail' });
        }
    });
    // Feature cluster impact/context pack
    app.get(['/api/feature-impact', '/api/cluster-impact'], async (req, res) => {
        try {
            const name = String(req.query.name ?? '').trim();
            if (!name) {
                res.status(400).json({ error: 'Missing "name" query parameter' });
                return;
            }
            const limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
            const directionText = String(req.query.direction ?? 'upstream');
            const direction = directionText === 'downstream' || directionText === 'both' ? directionText : 'upstream';
            const result = await backend.queryFeatureImpact(name, requestedRepo(req), direction, limit);
            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 feature cluster impact' });
        }
    });
    // ── Analyze API ──────────────────────────────────────────────────────
    // POST /api/analyze — start a new analysis job
    app.post('/api/analyze', async (req, res) => {
        try {
            const { url: repoUrl, path: repoLocalPath, force, embeddings } = req.body;
            // Input type validation
            if (repoUrl !== undefined && typeof repoUrl !== 'string') {
                res.status(400).json({ error: '"url" must be a string' });
                return;
            }
            if (repoLocalPath !== undefined && typeof repoLocalPath !== 'string') {
                res.status(400).json({ error: '"path" must be a string' });
                return;
            }
            if (!repoUrl && !repoLocalPath) {
                res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
                return;
            }
            // Path validation: require absolute path, reject traversal (e.g. /tmp/../etc/passwd)
            if (repoLocalPath) {
                if (!path.isAbsolute(repoLocalPath)) {
                    res.status(400).json({ error: '"path" must be an absolute path' });
                    return;
                }
                if (path.normalize(repoLocalPath) !== path.resolve(repoLocalPath)) {
                    res.status(400).json({ error: '"path" must not contain traversal sequences' });
                    return;
                }
            }
            const job = jobManager.createJob({ repoUrl, repoPath: repoLocalPath });
            // If job was already running (dedup), just return its id
            if (job.status !== 'queued') {
                res.status(202).json({ jobId: job.id, status: job.status });
                return;
            }
            // Mark as active synchronously to prevent race with concurrent requests
            jobManager.updateJob(job.id, { status: 'cloning' });
            // Start async work — don't await
            (async () => {
                let targetPath = repoLocalPath;
                try {
                    // Clone if URL provided
                    if (repoUrl && !repoLocalPath) {
                        const repoName = extractRepoName(repoUrl);
                        targetPath = getCloneDir(repoName);
                        jobManager.updateJob(job.id, {
                            status: 'cloning',
                            repoName,
                            progress: { phase: 'cloning', percent: 0, message: `Cloning ${repoUrl}...` },
                        });
                        await cloneOrPull(repoUrl, targetPath, (progress) => {
                            jobManager.updateJob(job.id, {
                                progress: { phase: progress.phase, percent: 5, message: progress.message },
                            });
                        });
                    }
                    if (!targetPath) {
                        throw new Error('No target path resolved');
                    }
                    // Acquire shared repo lock (keyed on storagePath to match embed handler)
                    const analyzeLockKey = getStoragePath(targetPath);
                    const lockErr = acquireRepoLock(analyzeLockKey);
                    if (lockErr) {
                        jobManager.updateJob(job.id, { status: 'failed', error: lockErr });
                        return;
                    }
                    jobManager.updateJob(job.id, { repoPath: targetPath, status: 'analyzing' });
                    // ── Worker fork with auto-retry ──────────────────────────────
                    //
                    // Forks a child process with 8GB heap. If the worker crashes
                    // (OOM, native addon segfault, etc.), it retries up to
                    // MAX_WORKER_RETRIES times with exponential backoff before
                    // marking the job as permanently failed.
                    //
                    // In dev mode (tsx), registers the tsx ESM hook via a file://
                    // URL so the child can compile TypeScript on-the-fly.
                    const MAX_WORKER_RETRIES = 2;
                    const callerPath = fileURLToPath(import.meta.url);
                    const isDev = callerPath.endsWith('.ts');
                    const workerFile = isDev ? 'analyze-worker.ts' : 'analyze-worker.js';
                    const workerPath = path.join(path.dirname(callerPath), workerFile);
                    const tsxHookArgs = isDev
                        ? ['--import', pathToFileURL(_require.resolve('tsx/esm')).href]
                        : [];
                    const forkWorker = () => {
                        const currentJob = jobManager.getJob(job.id);
                        if (!currentJob || currentJob.status === 'complete' || currentJob.status === 'failed')
                            return;
                        const child = fork(workerPath, [], {
                            execArgv: [...tsxHookArgs, '--max-old-space-size=8192'],
                            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
                        });
                        // Capture stderr for crash diagnostics
                        let stderrChunks = '';
                        child.stderr?.on('data', (chunk) => {
                            stderrChunks += chunk.toString();
                            if (stderrChunks.length > 4096)
                                stderrChunks = stderrChunks.slice(-4096);
                        });
                        child.on('message', (msg) => {
                            if (msg.type === 'progress') {
                                jobManager.updateJob(job.id, {
                                    status: 'analyzing',
                                    progress: { phase: msg.phase, percent: msg.percent, message: msg.message },
                                });
                            }
                            else if (msg.type === 'complete') {
                                releaseRepoLock(analyzeLockKey);
                                // Reinitialize backend BEFORE marking complete — ensures the new
                                // repo is queryable when the client receives the SSE complete event.
                                backend
                                    .init()
                                    .then(() => {
                                    jobManager.updateJob(job.id, {
                                        status: 'complete',
                                        repoName: msg.result.repoName,
                                    });
                                })
                                    .catch((err) => {
                                    console.error('backend.init() failed after analyze:', err);
                                    jobManager.updateJob(job.id, {
                                        status: 'failed',
                                        error: 'Server failed to reload after analysis. Try again.',
                                    });
                                });
                            }
                            else if (msg.type === 'error') {
                                releaseRepoLock(analyzeLockKey);
                                jobManager.updateJob(job.id, {
                                    status: 'failed',
                                    error: msg.message,
                                });
                            }
                        });
                        child.on('error', (err) => {
                            releaseRepoLock(analyzeLockKey);
                            jobManager.updateJob(job.id, {
                                status: 'failed',
                                error: `Worker process error: ${err.message}`,
                            });
                        });
                        child.on('exit', (code) => {
                            const j = jobManager.getJob(job.id);
                            if (!j || j.status === 'complete' || j.status === 'failed')
                                return;
                            // Worker crashed — attempt retry if under the limit
                            if (j.retryCount < MAX_WORKER_RETRIES) {
                                j.retryCount++;
                                const delay = 1000 * Math.pow(2, j.retryCount - 1); // 1s, 2s
                                const lastErr = stderrChunks.trim().split('\n').pop() || '';
                                console.warn(`Analyze worker crashed (code ${code}), retry ${j.retryCount}/${MAX_WORKER_RETRIES} in ${delay}ms` +
                                    (lastErr ? `: ${lastErr}` : ''));
                                jobManager.updateJob(job.id, {
                                    status: 'analyzing',
                                    progress: {
                                        phase: 'retrying',
                                        percent: j.progress.percent,
                                        message: `Worker crashed, retrying (${j.retryCount}/${MAX_WORKER_RETRIES})...`,
                                    },
                                });
                                stderrChunks = '';
                                setTimeout(forkWorker, delay);
                            }
                            else {
                                // Exhausted retries — permanent failure
                                releaseRepoLock(analyzeLockKey);
                                jobManager.updateJob(job.id, {
                                    status: 'failed',
                                    error: `Worker crashed ${MAX_WORKER_RETRIES + 1} times (code ${code})${stderrChunks ? ': ' + stderrChunks.trim().split('\n').pop() : ''}`,
                                });
                            }
                        });
                        // Register child for cancellation + timeout tracking
                        jobManager.registerChild(job.id, child);
                        // Send start command to child
                        child.send({
                            type: 'start',
                            repoPath: targetPath,
                            options: { force: !!force, embeddings: !!embeddings },
                        });
                    };
                    forkWorker();
                }
                catch (err) {
                    if (targetPath)
                        releaseRepoLock(getStoragePath(targetPath));
                    jobManager.updateJob(job.id, {
                        status: 'failed',
                        error: err.message || 'Analysis failed',
                    });
                }
            })();
            res.status(202).json({ jobId: job.id, status: job.status });
        }
        catch (err) {
            if (err.message?.includes('already in progress')) {
                res.status(409).json({ error: err.message });
            }
            else {
                res.status(500).json({ error: err.message || 'Failed to start analysis' });
            }
        }
    });
    // GET /api/analyze/:jobId — poll job status
    app.get('/api/analyze/:jobId', (req, res) => {
        const job = jobManager.getJob(req.params.jobId);
        if (!job) {
            res.status(404).json({ error: 'Job not found' });
            return;
        }
        res.json({
            id: job.id,
            status: job.status,
            repoUrl: job.repoUrl,
            repoPath: job.repoPath,
            repoName: job.repoName,
            progress: job.progress,
            error: job.error,
            startedAt: job.startedAt,
            completedAt: job.completedAt,
        });
    });
    // GET /api/analyze/:jobId/progress — SSE stream (shared helper)
    mountSSEProgress(app, '/api/analyze/:jobId/progress', jobManager);
    // DELETE /api/analyze/:jobId — cancel a running analysis job
    app.delete('/api/analyze/:jobId', (req, res) => {
        const job = jobManager.getJob(req.params.jobId);
        if (!job) {
            res.status(404).json({ error: 'Job not found' });
            return;
        }
        if (job.status === 'complete' || job.status === 'failed') {
            res.status(400).json({ error: `Job already ${job.status}` });
            return;
        }
        jobManager.cancelJob(req.params.jobId, 'Cancelled by user');
        res.json({ id: job.id, status: 'failed', error: 'Cancelled by user' });
    });
    // ── Embedding endpoints ────────────────────────────────────────────
    const embedJobManager = new JobManager();
    // POST /api/embed — trigger server-side embedding generation
    app.post('/api/embed', async (req, res) => {
        try {
            const entry = await resolveRepo(requestedRepo(req));
            if (!entry) {
                res.status(404).json({ error: 'Repository not found' });
                return;
            }
            // Check shared repo lock — prevent concurrent analyze + embed on same repo
            const repoLockPath = entry.storagePath;
            const lockErr = acquireRepoLock(repoLockPath);
            if (lockErr) {
                res.status(409).json({ error: lockErr });
                return;
            }
            const job = embedJobManager.createJob({ repoPath: entry.storagePath });
            embedJobManager.updateJob(job.id, {
                repoName: entry.name,
                status: 'analyzing',
                progress: { phase: 'analyzing', percent: 0, message: 'Starting embedding generation...' },
            });
            // 30-minute timeout for embedding jobs (same as analyze jobs)
            const EMBED_TIMEOUT_MS = 30 * 60 * 1000;
            const embedTimeout = setTimeout(() => {
                const current = embedJobManager.getJob(job.id);
                if (current && current.status !== 'complete' && current.status !== 'failed') {
                    releaseRepoLock(repoLockPath);
                    embedJobManager.updateJob(job.id, {
                        status: 'failed',
                        error: 'Embedding timed out (30 minute limit)',
                    });
                }
            }, EMBED_TIMEOUT_MS);
            // Run embedding pipeline asynchronously
            (async () => {
                try {
                    const cgdbPath = path.join(entry.storagePath, 'cgdb');
                    await withCgdbDb(cgdbPath, async () => {
                        const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
                        // Fetch existing content hashes for incremental embedding.
                        // Delegated to cgdb-adapter which owns the DB query logic and legacy-fallback handling.
                        const { fetchExistingEmbeddingHashes } = await import('../core/cgdb/cgdb-adapter.js');
                        const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
                        if (existingEmbeddings && existingEmbeddings.size > 0) {
                            console.log(`[embed] ${existingEmbeddings.size} nodes already embedded — incremental run with content-hash comparison`);
                        }
                        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                            embedJobManager.updateJob(job.id, {
                                progress: {
                                    phase: p.phase === 'ready' ? 'complete' : p.phase === 'error' ? 'failed' : p.phase,
                                    percent: p.percent,
                                    message: p.phase === 'loading-model'
                                        ? 'Loading embedding model...'
                                        : p.phase === 'embedding'
                                            ? `Embedding nodes (${p.percent}%)...`
                                            : p.phase === 'indexing'
                                                ? 'Creating vector index...'
                                                : p.phase === 'ready'
                                                    ? 'Embeddings complete'
                                                    : `${p.phase} (${p.percent}%)`,
                                },
                            });
                        }, {}, // config: use defaults
                        undefined, // skipNodeIds
                        undefined, // context
                        existingEmbeddings);
                    });
                    clearTimeout(embedTimeout);
                    releaseRepoLock(repoLockPath);
                    // Don't overwrite 'failed' if the job was cancelled while the pipeline was running
                    const current = embedJobManager.getJob(job.id);
                    if (!current || current.status !== 'failed') {
                        embedJobManager.updateJob(job.id, { status: 'complete' });
                    }
                }
                catch (err) {
                    clearTimeout(embedTimeout);
                    releaseRepoLock(repoLockPath);
                    const current = embedJobManager.getJob(job.id);
                    if (!current || current.status !== 'failed') {
                        embedJobManager.updateJob(job.id, {
                            status: 'failed',
                            error: err.message || 'Embedding generation failed',
                        });
                    }
                }
            })();
            res.status(202).json({ jobId: job.id, status: 'analyzing' });
        }
        catch (err) {
            if (err.message?.includes('already in progress')) {
                res.status(409).json({ error: err.message });
            }
            else {
                res.status(500).json({ error: err.message || 'Failed to start embedding generation' });
            }
        }
    });
    // GET /api/embed/:jobId — poll embedding job status
    app.get('/api/embed/:jobId', (req, res) => {
        const job = embedJobManager.getJob(req.params.jobId);
        if (!job) {
            res.status(404).json({ error: 'Job not found' });
            return;
        }
        res.json({
            id: job.id,
            status: job.status,
            repoName: job.repoName,
            progress: job.progress,
            error: job.error,
            startedAt: job.startedAt,
            completedAt: job.completedAt,
        });
    });
    // GET /api/embed/:jobId/progress — SSE stream (shared helper)
    mountSSEProgress(app, '/api/embed/:jobId/progress', embedJobManager);
    // DELETE /api/embed/:jobId — cancel embedding job
    app.delete('/api/embed/:jobId', (req, res) => {
        const job = embedJobManager.getJob(req.params.jobId);
        if (!job) {
            res.status(404).json({ error: 'Job not found' });
            return;
        }
        if (job.status === 'complete' || job.status === 'failed') {
            res.status(400).json({ error: `Job already ${job.status}` });
            return;
        }
        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);
        res.status(500).json({ error: 'Internal server error' });
    });
    // Wrap listen in a promise so errors (EADDRINUSE, EACCES, etc.) propagate
    // to the caller instead of crashing with an unhandled 'error' event.
    await new Promise((resolve, reject) => {
        const server = app.listen(port, host, () => {
            const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
            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));
        // Graceful shutdown — close Express + LadybugDB cleanly
        const shutdown = async () => {
            console.log('\nShutting down...');
            server.close();
            jobManager.dispose();
            embedJobManager.dispose();
            await cleanupMcp();
            await closeCgdb();
            await backend.disconnect();
            process.exit(0);
        };
        process.once('SIGINT', shutdown);
        process.once('SIGTERM', shutdown);
    });
};
