opencode-rag-plugin 1.19.4 → 1.19.5

package/dist/web/api.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { extname, join, resolve as resolvePathModule } from "node:path";
 import { createHash } from "node:crypto";
 import { listSessions, getSession, deleteSession, compareSessions, validateSessionID } from "../eval/storage.js";
@@ -30,14 +30,53 @@ function parseQuery(url) {
         params: new URLSearchParams(queryString ?? ""),
     };
 }
-/** Serialise an {@link ApiResponse} as JSON and write it to the HTTP response with CORS headers. */
-function sendJson(res, response) {
-    res.writeHead(response.status, {
+/**
+ * Determine whether a browser Origin header may call the API.
+ *
+ * Only same-machine origins are allowed (the server binds to 127.0.0.1). Any
+ * other origin — e.g. a random website doing a drive-by fetch — is rejected.
+ * Returns the origin to echo in `Access-Control-Allow-Origin`, or `null`.
+ */
+function isAllowedOrigin(origin) {
+    if (!origin)
+        return null;
+    try {
+        const u = new URL(origin);
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            return null;
+        return u.hostname === "127.0.0.1" || u.hostname === "localhost" || u.hostname === "[::1]" ? origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare two tokens in constant time to avoid timing side-channels. */
+function tokensEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Serialise an {@link ApiResponse} as JSON and write it to the HTTP response.
+ *
+ * CORS headers are only emitted for allowed (localhost) origins; cross-origin
+ * callers get no CORS headers at all, so browsers block reading the response.
+ */
+function sendJson(res, response, origin) {
+    const headers = {
         "Content-Type": "application/json",
-        "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-        "Access-Control-Allow-Headers": "Content-Type",
-    });
+        "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        "X-Content-Type-Options": "nosniff",
+    };
+    if (origin) {
+        headers["Access-Control-Allow-Origin"] = origin;
+        headers["Vary"] = "Origin";
+    }
+    res.writeHead(response.status, headers);
     res.end(JSON.stringify(response.body));
 }
 /**
@@ -57,11 +96,43 @@ function sendJson(res, response) {
  * @param cfg          - Active RAG configuration (used by quirk endpoints).
  * @returns An async handler that returns `true` when a route matched or `false` otherwise.
  */
-export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEmbedder) {
+export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEmbedder, token) {
     return async (req, res) => {
         const url = req.url ?? "/";
         const method = req.method ?? "GET";
         const { path, params } = parseQuery(url);
+        const origin = isAllowedOrigin(req.headers.origin);
+        // CORS preflight — only answer for allowed localhost origins
+        if (method === "OPTIONS") {
+            if (!origin) {
+                res.writeHead(403, { "Content-Type": "text/plain" });
+                res.end("Forbidden");
+                return true;
+            }
+            res.writeHead(204, {
+                "Access-Control-Allow-Origin": origin,
+                "Vary": "Origin",
+                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type, Authorization",
+            });
+            res.end();
+            return true;
+        }
+        // Same-machine-only: reject cross-origin requests outright (defeats drive-by
+        // website fetches and DNS rebinding even where CORS headers would block reads).
+        if (origin && !isAllowedOrigin(origin)) {
+            sendJson(res, { status: 403, body: { error: "Forbidden origin" } }, null);
+            return true;
+        }
+        // Token auth for every API request when a token is configured
+        if (token) {
+            const header = req.headers.authorization;
+            const supplied = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : params.get("token");
+            if (!supplied || !tokensEqual(supplied, token)) {
+                sendJson(res, { status: 401, body: { error: "Unauthorized — missing or invalid token" } }, origin);
+                return true;
+            }
+        }
         // Quirk store dependencies (embedder is a no-op stub for the read-only UI context).
         const quirkDeps = {
             embedder: stubEmbedder,
@@ -70,16 +141,6 @@ export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEm
             cfg: cfg ?? {},
             storePath,
         };
-        // CORS preflight
-        if (method === "OPTIONS") {
-            res.writeHead(204, {
-                "Access-Control-Allow-Origin": "*",
-                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
-                "Access-Control-Allow-Headers": "Content-Type",
-            });
-            res.end();
-            return true;
-        }
         let response;
         try {
             // Existing endpoints
@@ -155,6 +216,14 @@ export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEm
             else if (path === "/api/eval/sessions" && method === "GET") {
                 response = await handleEvalSessions(storePath);
             }
+            else if (path === "/api/eval/compare" && method === "GET") {
+                response = await handleEvalCompare(storePath, params);
+            }
+            // Token analysis endpoints — must precede the generic `/api/eval/sessions/:id` route
+            else if (path.startsWith("/api/eval/sessions/") && path.endsWith("/analysis") && method === "GET") {
+                const id = path.slice("/api/eval/sessions/".length, -"/analysis".length);
+                response = await handleEvalAnalysis(storePath, id);
+            }
             else if (path.startsWith("/api/eval/sessions/") && method === "GET") {
                 const id = path.slice("/api/eval/sessions/".length);
                 response = await handleEvalSession(storePath, id);
@@ -163,14 +232,6 @@ export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEm
                 const id = path.slice("/api/eval/sessions/".length);
                 response = await handleEvalDeleteSession(storePath, id);
             }
-            else if (path === "/api/eval/compare" && method === "GET") {
-                response = await handleEvalCompare(storePath, params);
-            }
-            // Token analysis endpoints
-            else if (path.startsWith("/api/eval/sessions/") && path.endsWith("/analysis") && method === "GET") {
-                const id = path.slice("/api/eval/sessions/".length, -"/analysis".length);
-                response = await handleEvalAnalysis(storePath, id);
-            }
             else if (path === "/api/eval/token-compare" && method === "GET") {
                 response = await handleEvalTokenCompare(storePath, params);
             }
@@ -197,12 +258,20 @@ export function createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEm
             else {
                 return false;
             }
-            sendJson(res, response);
+            sendJson(res, response, origin);
             return true;
         }
         catch (err) {
+            if (err instanceof BodyTooLargeError) {
+                if (!res.destroyed) {
+                    sendJson(res, { status: 413, body: { error: err.message } }, origin);
+                }
+                return true;
+            }
             const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, { status: 500, body: { error: message } });
+            if (!res.destroyed) {
+                sendJson(res, { status: 500, body: { error: message } }, origin);
+            }
             return true;
         }
     };
@@ -260,23 +329,19 @@ async function handleQuirkDelete(deps, id) {
 /**
  * Respond with a paginated, optionally filtered list of chunks.
  *
- * Query params: `offset` (default 0), `limit` (default 50), `lang`, `file`.
+ * Query params: `offset` (default 0, clamped >= 0), `limit` (default 50,
+ * clamped 1..500), `lang`, `file`. Filtering and pagination are pushed
+ * down into the store query — loading 100k rows per request was a memory
+ * blowup on large stores.
  */
 async function handleChunks(store, params) {
-    const offset = parseInt(params.get("offset") ?? "0", 10);
-    const limit = parseInt(params.get("limit") ?? "50", 10);
+    const rawOffset = parseInt(params.get("offset") ?? "0", 10);
+    const rawLimit = parseInt(params.get("limit") ?? "50", 10);
+    const offset = Number.isFinite(rawOffset) ? Math.max(0, rawOffset) : 0;
+    const limit = Number.isFinite(rawLimit) ? Math.min(500, Math.max(1, rawLimit)) : 50;
     const langFilter = params.get("lang");
     const fileFilter = params.get("file");
-    const allChunks = await store.getChunks(0, 100000);
-    let filtered = allChunks;
-    if (langFilter) {
-        filtered = filtered.filter((c) => c.language === langFilter);
-    }
-    if (fileFilter) {
-        filtered = filtered.filter((c) => c.filePath.startsWith(fileFilter));
-    }
-    const total = filtered.length;
-    const chunks = filtered.slice(offset, offset + limit);
+    const { chunks, total } = await store.getChunksFiltered(offset, limit, langFilter || undefined, fileFilter || undefined);
     return {
         status: 200,
         body: { chunks, total, offset, limit },
@@ -284,8 +349,7 @@ async function handleChunks(store, params) {
 }
 /** Respond with a single chunk identified by its ID, or 404 if not found. */
 async function handleChunkById(store, id) {
-    const chunks = await store.getChunks(0, 100000);
-    const chunk = chunks.find((c) => c.id === id);
+    const chunk = await store.getChunkById(id);
     if (!chunk) {
         return { status: 404, body: { error: "Chunk not found" } };
     }
@@ -294,7 +358,8 @@ async function handleChunkById(store, id) {
 /** Run a keyword search against the index and return ranked results. Query param: `q` (query string), `topK` (default 20). */
 async function handleSearch(keywordIndex, params) {
     const query = params.get("q") ?? "";
-    const topK = parseInt(params.get("topK") ?? "20", 10);
+    const rawTopK = parseInt(params.get("topK") ?? "20", 10);
+    const topK = Number.isFinite(rawTopK) ? Math.min(100, Math.max(1, rawTopK)) : 20;
     if (!query.trim()) {
         return { status: 200, body: { results: [] } };
     }
@@ -337,9 +402,14 @@ async function handleRetrieve(store, keywordIndex, getEmbedder, cfg, params) {
     catch (err) {
         return { status: 503, body: { error: `Embedding model unavailable: ${err.message}. Check that your embedding provider is running.` } };
     }
-    const topK = parseInt(params.get("topK") ?? "10", 10);
-    const minScore = parseFloat(params.get("minScore") ?? "0.35");
-    const keywordWeight = parseFloat(params.get("keywordWeight") ?? "0.4");
+    const rawTopK = parseInt(params.get("topK") ?? "10", 10);
+    const rawMinScore = parseFloat(params.get("minScore") ?? "0.35");
+    const rawKeywordWeight = parseFloat(params.get("keywordWeight") ?? "0.4");
+    // Clamp all numeric params — a topK of 1e9 would overfetch 3x via the
+    // retriever's overfetch factor and blow up memory.
+    const topK = Number.isFinite(rawTopK) ? Math.min(100, Math.max(1, rawTopK)) : 10;
+    const minScore = Number.isFinite(rawMinScore) ? Math.min(1, Math.max(0, rawMinScore)) : 0.35;
+    const keywordWeight = Number.isFinite(rawKeywordWeight) ? Math.min(1, Math.max(0, rawKeywordWeight)) : 0.4;
     const hybrid = params.get("hybrid") !== "false";
     const explain = params.get("explain") !== "false";
     const pathFilter = params.get("path") ?? undefined;
@@ -404,10 +474,15 @@ async function handleCompare(store, params) {
     if (ids.length === 0) {
         return { status: 400, body: { error: "No chunk IDs provided" } };
     }
-    const allChunks = await store.getChunks(0, 100000);
-    const chunks = allChunks.filter((c) => ids.includes(c.id ?? ""));
+    if (ids.length > 100) {
+        return { status: 400, body: { error: "Too many chunk IDs (max 100)" } };
+    }
+    const chunks = await store.getChunksByIds(ids);
     return { status: 200, body: { chunks } };
 }
+// Re-hashing every manifest file per status request is expensive — cache the
+// result keyed on the manifest file's mtime+size (invalidated on any write).
+let statusCache = null;
 /**
  * Return indexing status — manifest stats, staleness, and a placeholder for watcher state.
  */
@@ -431,20 +506,37 @@ async function handleIndexingStatus(storePath, cwd) {
     if (manifest?.lastIndexedAt) {
         lastIndexedAt = new Date(manifest.lastIndexedAt).toISOString();
     }
-    // Count stale files by comparing manifest file list against current disk state
+    // Count stale files by comparing manifest file list against current disk state.
+    // Cached by manifest mtime+size so the poll loop doesn't hash every file
+    // synchronously on the event loop per request.
     if (cwd && manifest?.files) {
-        const storedFiles = manifest.files;
-        for (const [filePath, fileMeta] of Object.entries(storedFiles)) {
+        const cacheKey = (() => {
             try {
-                const fullPath = filePath;
-                const content = readFileSync(fullPath, "utf-8");
-                const hash = createHash("sha256").update(content).digest("hex");
-                if (hash !== fileMeta.hash)
-                    staleFileCount++;
+                const st = statSync(manifestPath);
+                return `${st.mtimeMs}:${st.size}`;
             }
             catch {
-                staleFileCount++; // file was deleted or unreadable
+                return "missing";
             }
+        })();
+        if (statusCache && statusCache.key === cacheKey) {
+            staleFileCount = statusCache.staleFileCount;
+        }
+        else {
+            const storedFiles = manifest.files;
+            for (const [filePath, fileMeta] of Object.entries(storedFiles)) {
+                try {
+                    const fullPath = filePath;
+                    const content = readFileSync(fullPath, "utf-8");
+                    const hash = createHash("sha256").update(content).digest("hex");
+                    if (hash !== fileMeta.hash)
+                        staleFileCount++;
+                }
+                catch {
+                    staleFileCount++; // file was deleted or unreadable
+                }
+            }
+            statusCache = { key: cacheKey, staleFileCount, manifest };
         }
     }
     return {
@@ -456,22 +548,38 @@ async function handleIndexingStatus(storePath, cwd) {
         },
     };
 }
+/** Guards concurrent reindex requests — only one pass may run at a time. */
+let reindexInFlight = false;
 /**
  * Trigger a one-shot reindex pass in the background.
  */
 async function handleReindex(cwd, cfg, storePath, store, getEmbedder) {
+    if (reindexInFlight) {
+        return { status: 409, body: { error: "A reindex is already running" } };
+    }
     try {
         const { runIndexPass } = await import("../indexer.js");
         const embedder = getEmbedder ? await getEmbedder() : undefined;
         if (!embedder) {
             return { status: 503, body: { error: "Embedder not available" } };
         }
-        runIndexPass({ cwd, storePath, config: cfg, store, embedder }).catch((err) => {
+        reindexInFlight = true;
+        runIndexPass({ cwd, storePath, config: cfg, store, embedder })
+            .then(() => {
+            reindexInFlight = false;
+            statusCache = null; // invalidate the status cache after a pass
+            projectionCache = null;
+        })
+            .catch((err) => {
+            reindexInFlight = false;
+            statusCache = null;
+            projectionCache = null;
             console.error("Background reindex failed:", err);
         });
         return { status: 200, body: { started: true } };
     }
     catch (err) {
+        reindexInFlight = false;
         return { status: 500, body: { error: `Failed to start reindex: ${err.message}` } };
     }
 }
@@ -485,7 +593,7 @@ function handleConfig(cfg) {
 }
 function redactKeys(obj) {
     for (const key of Object.keys(obj)) {
-        if (key.toLowerCase().includes("apikey") || key === "apiKey") {
+        if (/api\s*key|apikey|password|passwd|secret|token|authorization|credential/i.test(key)) {
             obj[key] = "***";
         }
         else if (typeof obj[key] === "object" && obj[key] !== null) {
@@ -495,16 +603,28 @@ function redactKeys(obj) {
 }
 /**
  * Project chunk embeddings to 2D via PCA for the Embedding Space Explorer.
+ * Capped at 5000 chunks and memoized per (storePath, maxChunks) so the
+ * O(n·dim²) computation does not run on every visit.
  */
+let projectionCache = null;
 async function handleEmbeddingProjection(store, params) {
-    const maxChunks = parseInt(params.get("maxChunks") ?? "5000", 10);
+    const rawMaxChunks = parseInt(params.get("maxChunks") ?? "5000", 10);
+    const maxChunks = Number.isFinite(rawMaxChunks) ? Math.min(5000, Math.max(1, rawMaxChunks)) : 5000;
     try {
+        // Invalidated after a reindex pass completes (see handleReindex)
+        const cacheKey = `${maxChunks}`;
+        if (projectionCache && projectionCache.key === cacheKey) {
+            return { status: 200, body: projectionCache.body };
+        }
         const chunks = await store.getChunksWithEmbeddings(maxChunks);
         if (chunks.length === 0) {
-            return { status: 200, body: { points: [], totalChunks: 0 } };
+            projectionCache = { key: cacheKey, body: { points: [], totalChunks: 0 } };
+            return { status: 200, body: projectionCache.body };
         }
         if (chunks.length === 1) {
-            return { status: 200, body: { points: [{ id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description }], totalChunks: 1, displayedChunks: 1 } };
+            const body = { points: [{ id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description }], totalChunks: 1, displayedChunks: 1 };
+            projectionCache = { key: cacheKey, body };
+            return { status: 200, body };
         }
         const { computePCA } = await import("./pca.js");
         const vectors = chunks.map(c => c.embedding);
@@ -519,10 +639,9 @@ async function handleEmbeddingProjection(store, params) {
             language: c.language,
             description: c.description,
         }));
-        return {
-            status: 200,
-            body: { points, totalChunks: chunks.length, displayedChunks: points.length },
-        };
+        const body = { points, totalChunks: chunks.length, displayedChunks: points.length };
+        projectionCache = { key: cacheKey, body };
+        return { status: 200, body };
     }
     catch (err) {
         return { status: 500, body: { error: `Projection failed: ${err.message}` } };
@@ -654,6 +773,13 @@ export function handleEvalProjectSavings(body) {
 }
 /** Collect the full request body as a Buffer and parse it as JSON. Returns `{}` on empty or invalid input. */
 const MAX_BODY_BYTES = 1_048_576; // 1 MB
+/** Thrown when the request body exceeds {@link MAX_BODY_BYTES}; mapped to a 413 response. */
+export class BodyTooLargeError extends Error {
+    constructor() {
+        super(`Request body exceeds ${MAX_BODY_BYTES} byte limit`);
+        this.name = "BodyTooLargeError";
+    }
+}
 async function readBody(req) {
     const chunks = [];
     let totalSize = 0;
@@ -661,8 +787,8 @@ async function readBody(req) {
         const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
         totalSize += buf.length;
         if (totalSize > MAX_BODY_BYTES) {
-            req.destroy(new Error("Request body too large"));
-            throw new Error(`Request body exceeds ${MAX_BODY_BYTES} byte limit`);
+            req.destroy();
+            throw new BodyTooLargeError();
         }
         chunks.push(buf);
     }

package/dist/web/server.d.ts

@@ -2,6 +2,8 @@
 export interface WebUiServer {
     /** The port the HTTP server is listening on. */
     port: number;
+    /** Random per-run token required on every `/api/*` request (Bearer header or `?token=`). */
+    token: string;
     /** Gracefully shut down the HTTP server. */
     close: () => Promise<void>;
 }

package/dist/web/server.js

@@ -4,6 +4,7 @@
 import { createServer } from "node:http";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, extname, join, sep } from "node:path";
+import { randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { LanceDbStore } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
@@ -26,7 +27,12 @@ const MIME_TYPES = {
 };
 /** Serve an HTML string as the HTTP response with UTF-8 content type. */
 function serveStatic(res, html) {
-    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-cache",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+    });
     res.end(html);
 }
 /** Read a UI asset file from disk and serve it with the correct MIME type. Falls back to 404 if the file is missing. */
@@ -35,7 +41,13 @@ function serveUiAsset(res, filePath) {
         const data = readFileSync(filePath);
         const ext = extname(filePath);
         const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-        res.writeHead(200, { "Content-Type": contentType });
+        // Vite emits hashed filenames, so assets can be cached aggressively
+        const cacheControl = /[.-][a-f0-9]{8,}\./.test(filePath) ? "public, max-age=31536000, immutable" : "no-cache";
+        res.writeHead(200, {
+            "Content-Type": contentType,
+            "Cache-Control": cacheControl,
+            "X-Content-Type-Options": "nosniff",
+        });
         res.end(data);
     }
     catch {
@@ -69,49 +81,75 @@ export async function startWebUi(storePath, port, cwd, vectorDimension = 384, cf
         return embedderPromise;
     }
     const html = getStaticHtml();
-    const apiHandler = createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEmbedder);
+    const token = randomBytes(24).toString("hex");
+    const apiHandler = createApiHandler(store, keywordIndex, storePath, cwd, cfg, getEmbedder, token);
     const server = createServer(async (req, res) => {
-        const url = req.url ?? "/";
-        if (url === "/" || url === "/index.html") {
-            serveStatic(res, html);
-            return;
-        }
-        if (url.startsWith("/ui/")) {
-            const decoded = decodeURIComponent(url.slice("/ui/".length));
-            if (decoded.includes("..") || decoded === "") {
-                res.writeHead(403, { "Content-Type": "text/plain" });
-                res.end("Forbidden");
+        try {
+            // Strip the query string before routing — the auth token arrives as
+            // `/?token=...` and must not break the root route match.
+            const url = (req.url ?? "/").split("?")[0] || "/";
+            if (url === "/" || url === "/index.html") {
+                serveStatic(res, html);
                 return;
             }
-            // Try production build output first, fall back to dev source
-            const distAsset = resolveDistAsset(decoded);
-            if (distAsset) {
-                serveUiAsset(res, distAsset);
+            if (url.startsWith("/ui/")) {
+                let decoded;
+                try {
+                    decoded = decodeURIComponent(url.slice("/ui/".length));
+                }
+                catch {
+                    res.writeHead(400, { "Content-Type": "text/plain" });
+                    res.end("Bad Request");
+                    return;
+                }
+                if (decoded.includes("..") || decoded === "") {
+                    res.writeHead(403, { "Content-Type": "text/plain" });
+                    res.end("Forbidden");
+                    return;
+                }
+                // Try production build output first, fall back to dev source
+                const distAsset = resolveDistAsset(decoded);
+                if (distAsset) {
+                    serveUiAsset(res, distAsset);
+                    return;
+                }
+                const devPath = join(uiDir, decoded);
+                if (devPath.startsWith(uiDir + sep) && existsSync(devPath)) {
+                    serveUiAsset(res, devPath);
+                    return;
+                }
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("Not Found");
                 return;
             }
-            const devPath = join(uiDir, decoded);
-            if (devPath.startsWith(uiDir + sep) && existsSync(devPath)) {
-                serveUiAsset(res, devPath);
-                return;
+            if (url.startsWith("/api/")) {
+                const handled = await apiHandler(req, res);
+                if (handled)
+                    return;
             }
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not Found");
-            return;
         }
-        if (url.startsWith("/api/")) {
-            const handled = await apiHandler(req, res);
-            if (handled)
-                return;
+        catch (err) {
+            // Never let a malformed request crash the process
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "text/plain" });
+                res.end("Internal Server Error");
+            }
+            else {
+                res.end();
+            }
         }
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
     });
     return new Promise((resolve, reject) => {
         server.on("error", reject);
         server.listen(port, "127.0.0.1", () => {
             resolve({
                 port,
+                token,
                 close: () => new Promise((resolveClose) => {
+                    // Close idle keep-alive connections so `server.close()` cannot hang
+                    server.closeAllConnections();
                     server.close(() => {
                         store.close().catch(() => { });
                         keywordIndex.close();

package/dist/web/static.d.ts

@@ -1,8 +1,11 @@
 /**
  * Read and cache the Web UI `index.html` from disk.
  *
- * Reads from the Vite production build output (`dist/web/ui/index.html`) when available,
- * falling back to the development source (`src/web/ui/index.html`).
+ * Reads from the Vite production build output (`dist/web/ui/index.html`).
+ * There is deliberately NO fallback to `src/web/ui/index.html`: the dev
+ * source references `/src/main.tsx`, which the embedded server does not
+ * serve — a "working" fallback would render a blank page. Use
+ * `npm run build` (or `npm run dev:ui` with the Vite dev server) instead.
  *
  * @returns The full HTML string of the Web UI entry page.
  */

package/dist/web/static.js

@@ -18,8 +18,11 @@ let cachedHtml = null;
 /**
  * Read and cache the Web UI `index.html` from disk.
  *
- * Reads from the Vite production build output (`dist/web/ui/index.html`) when available,
- * falling back to the development source (`src/web/ui/index.html`).
+ * Reads from the Vite production build output (`dist/web/ui/index.html`).
+ * There is deliberately NO fallback to `src/web/ui/index.html`: the dev
+ * source references `/src/main.tsx`, which the embedded server does not
+ * serve — a "working" fallback would render a blank page. Use
+ * `npm run build` (or `npm run dev:ui` with the Vite dev server) instead.
  *
  * @returns The full HTML string of the Web UI entry page.
  */
@@ -28,9 +31,10 @@ export function getStaticHtml() {
         return cachedHtml;
     const root = projectRoot();
     const prodPath = join(root, "dist", "web", "ui", "index.html");
-    const devPath = join(root, "src", "web", "ui", "index.html");
-    const targetPath = existsSync(prodPath) ? prodPath : devPath;
-    cachedHtml = readFileSync(targetPath, "utf-8");
+    if (!existsSync(prodPath)) {
+        throw new Error("Web UI not built — run `npm run build` (or use `npm run dev:ui` with the Vite dev server).");
+    }
+    cachedHtml = readFileSync(prodPath, "utf-8");
     return cachedHtml;
 }
 /**