comprehende 0.1.0

package/dist/schema/parse.js

@@ -0,0 +1,258 @@
+import { isReviewSize, REVIEW_SIZES } from "./types.js";
+const DOCUMENT_KEYS = new Set(["version", "source", "size", "walkthrough", "tickets", "groups"]);
+const SOURCE_KEYS = new Set(["baseRef", "headRef", "range"]);
+const TICKET_KEYS = new Set(["id", "url", "title"]);
+const GROUP_KEYS = new Set(["id", "title", "summary", "lookFor", "dependsOn", "suggestedOrder", "hunkRefs"]);
+const HUNK_KEYS = new Set(["path", "oldPath", "oldStart", "oldLines", "newStart", "newLines"]);
+export function parseReviewDocument(input) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["review document must be a JSON object"] };
+    }
+    extraKeys(input, DOCUMENT_KEYS, "document", errors);
+    if (input.version !== 1) {
+        errors.push("version must be 1");
+    }
+    const source = parseSource(input.source, errors);
+    const size = parseSize(input.size, errors);
+    const tickets = parseTickets(input.tickets, errors);
+    const groups = parseGroups(input.groups, errors);
+    const walkthrough = input.walkthrough === undefined ? undefined : requiredString(input.walkthrough, "walkthrough", errors);
+    if (errors.length > 0 || source === undefined || size === undefined) {
+        return { ok: false, errors };
+    }
+    const document = {
+        version: 1,
+        source,
+        size,
+        groups,
+    };
+    if (walkthrough !== undefined) {
+        document.walkthrough = walkthrough;
+    }
+    if (tickets !== undefined) {
+        document.tickets = tickets;
+    }
+    return { ok: true, document };
+}
+export function parseReviewJson(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, errors: ["review document is not valid JSON"] };
+    }
+    return parseReviewDocument(value);
+}
+function parseSize(value, errors) {
+    if (isReviewSize(value)) {
+        return value;
+    }
+    errors.push(`size must be one of ${REVIEW_SIZES.join(", ")}`);
+    return undefined;
+}
+function parseSource(value, errors) {
+    if (!isRecord(value)) {
+        errors.push("source must be an object");
+        return undefined;
+    }
+    extraKeys(value, SOURCE_KEYS, "source", errors);
+    const baseRef = requiredString(value.baseRef, "source.baseRef", errors);
+    const headRef = requiredString(value.headRef, "source.headRef", errors);
+    let range;
+    if (value.range !== undefined) {
+        range = requiredString(value.range, "source.range", errors);
+    }
+    if (baseRef === undefined || headRef === undefined) {
+        return undefined;
+    }
+    const source = { baseRef, headRef };
+    if (range !== undefined) {
+        source.range = range;
+    }
+    return source;
+}
+function parseTickets(value, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        errors.push("tickets must be an array");
+        return undefined;
+    }
+    const tickets = [];
+    value.forEach((item, i) => {
+        if (!isRecord(item)) {
+            errors.push(`tickets[${i}] must be an object`);
+            return;
+        }
+        extraKeys(item, TICKET_KEYS, `tickets[${i}]`, errors);
+        const id = requiredString(item.id, `tickets[${i}].id`, errors);
+        if (id === undefined) {
+            return;
+        }
+        const ticket = { id };
+        if (item.url !== undefined) {
+            const url = requiredString(item.url, `tickets[${i}].url`, errors);
+            if (url !== undefined) {
+                ticket.url = url;
+            }
+        }
+        if (item.title !== undefined) {
+            const title = requiredString(item.title, `tickets[${i}].title`, errors);
+            if (title !== undefined) {
+                ticket.title = title;
+            }
+        }
+        tickets.push(ticket);
+    });
+    return tickets;
+}
+function parseGroups(value, errors) {
+    if (!Array.isArray(value)) {
+        errors.push("groups must be an array");
+        return [];
+    }
+    const ids = new Set();
+    const groups = [];
+    value.forEach((item, i) => {
+        if (!isRecord(item)) {
+            errors.push(`groups[${i}] must be an object`);
+            return;
+        }
+        extraKeys(item, GROUP_KEYS, `groups[${i}]`, errors);
+        const id = requiredString(item.id, `groups[${i}].id`, errors);
+        const title = requiredString(item.title, `groups[${i}].title`, errors);
+        const summary = requiredString(item.summary, `groups[${i}].summary`, errors, { allowEmpty: true });
+        const suggestedOrder = requiredNumber(item.suggestedOrder, `groups[${i}].suggestedOrder`, errors);
+        const hunkRefs = parseHunkRefs(item.hunkRefs, `groups[${i}].hunkRefs`, errors);
+        const lookFor = parseStringList(item.lookFor, `groups[${i}].lookFor`, errors);
+        const dependsOn = parseStringList(item.dependsOn, `groups[${i}].dependsOn`, errors);
+        if (id === undefined || title === undefined || summary === undefined || suggestedOrder === undefined) {
+            return;
+        }
+        if (ids.has(id)) {
+            errors.push(`duplicate group id "${id}"`);
+        }
+        ids.add(id);
+        const group = { id, title, summary, suggestedOrder, hunkRefs };
+        if (lookFor !== undefined) {
+            group.lookFor = lookFor;
+        }
+        if (dependsOn !== undefined) {
+            group.dependsOn = dependsOn;
+        }
+        groups.push(group);
+    });
+    const known = new Set(groups.map((group) => group.id));
+    for (const group of groups) {
+        for (const dep of group.dependsOn ?? []) {
+            if (dep === group.id) {
+                errors.push(`groups id "${group.id}" depends on itself`);
+            }
+            else if (!known.has(dep)) {
+                errors.push(`groups id "${group.id}" dependsOn unknown group "${dep}"`);
+            }
+        }
+    }
+    return groups;
+}
+function parseHunkRefs(value, label, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${label} must be an array`);
+        return [];
+    }
+    const refs = [];
+    value.forEach((item, i) => {
+        const ref = parseHunkRef(item, `${label}[${i}]`, errors);
+        if (ref !== undefined) {
+            refs.push(ref);
+        }
+    });
+    return refs;
+}
+export function parseHunkRef(value, label, errors) {
+    if (!isRecord(value)) {
+        errors.push(`${label} must be an object`);
+        return undefined;
+    }
+    extraKeys(value, HUNK_KEYS, label, errors);
+    const path = requiredString(value.path, `${label}.path`, errors);
+    const oldStart = requiredInt(value.oldStart, `${label}.oldStart`, errors);
+    const oldLines = requiredInt(value.oldLines, `${label}.oldLines`, errors);
+    const newStart = requiredInt(value.newStart, `${label}.newStart`, errors);
+    const newLines = requiredInt(value.newLines, `${label}.newLines`, errors);
+    let oldPath;
+    if (value.oldPath !== undefined) {
+        oldPath = requiredString(value.oldPath, `${label}.oldPath`, errors);
+    }
+    if (path === undefined ||
+        oldStart === undefined ||
+        oldLines === undefined ||
+        newStart === undefined ||
+        newLines === undefined) {
+        return undefined;
+    }
+    const ref = { path, oldStart, oldLines, newStart, newLines };
+    if (oldPath !== undefined) {
+        ref.oldPath = oldPath;
+    }
+    return ref;
+}
+function parseStringList(value, label, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        errors.push(`${label} must be an array of strings`);
+        return undefined;
+    }
+    const items = [];
+    value.forEach((item, i) => {
+        const text = requiredString(item, `${label}[${i}]`, errors);
+        if (text !== undefined) {
+            items.push(text);
+        }
+    });
+    return items;
+}
+function extraKeys(value, allowed, label, errors) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            errors.push(`${label} has unknown field "${key}" (review documents may not store patch text or file contents)`);
+        }
+    }
+}
+function requiredString(value, label, errors, opts) {
+    if (typeof value !== "string") {
+        errors.push(`${label} must be a string`);
+        return undefined;
+    }
+    if (!opts?.allowEmpty && value.trim() === "") {
+        errors.push(`${label} must be a non-empty string`);
+        return undefined;
+    }
+    return value;
+}
+function requiredNumber(value, label, errors) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        errors.push(`${label} must be a finite number`);
+        return undefined;
+    }
+    return value;
+}
+function requiredInt(value, label, errors) {
+    const n = requiredNumber(value, label, errors);
+    if (n === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(n) || n < 0) {
+        errors.push(`${label} must be a non-negative integer`);
+        return undefined;
+    }
+    return n;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/schema/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/schema/parse.ts"],"names":[],"mappings":"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"}

package/dist/schema/skill-paths.d.ts

@@ -0,0 +1,7 @@
+export declare function skillPaths(root?: string): {
+    canonicalSchema: string;
+    publishedSkill: string;
+    installedSkill: string;
+    publishedSchema: string;
+    installedSchema: string;
+};

package/dist/schema/skill-paths.js

@@ -0,0 +1,11 @@
+import { join } from "node:path";
+import { findPackageRoot } from "../package-root.js";
+export function skillPaths(root = findPackageRoot()) {
+    return {
+        canonicalSchema: join(root, "src/schema/review.schema.json"),
+        publishedSkill: join(root, "skills/comprehende"),
+        installedSkill: join(root, ".agents/skills/comprehende"),
+        publishedSchema: join(root, "skills/comprehende/references/review.schema.json"),
+        installedSchema: join(root, ".agents/skills/comprehende/references/review.schema.json"),
+    };
+}

package/dist/schema/skill-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-paths.js","sourceRoot":"","sources":["../../src/schema/skill-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,IAAI,GAAG,eAAe,EAAE;IACjD,OAAO;QACL,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,+BAA+B,CAAC;QAC5D,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,oBAAoB,CAAC;QAChD,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,4BAA4B,CAAC;QACxD,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,kDAAkD,CAAC;QAC/E,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,0DAA0D,CAAC;KACxF,CAAC;AACJ,CAAC"}

package/dist/schema/types.d.ts

@@ -0,0 +1,73 @@
+export declare const REVIEW_SIZES: readonly ["trivial", "small", "medium", "large", "very-large"];
+export type ReviewSize = (typeof REVIEW_SIZES)[number];
+export declare function isReviewSize(value: unknown): value is ReviewSize;
+export type ReviewDocument = {
+    version: 1;
+    source: ReviewSource;
+    /** Human review burden of this change, not file or hunk count. */
+    size: ReviewSize;
+    walkthrough?: string;
+    tickets?: Ticket[];
+    groups: ReviewGroup[];
+};
+export type ReviewSource = {
+    baseRef: string;
+    headRef: string;
+    range?: string;
+};
+export type Ticket = {
+    id: string;
+    url?: string;
+    title?: string;
+};
+export type ReviewGroup = {
+    id: string;
+    title: string;
+    /** One sentence: what this layer is and why it exists. */
+    summary: string;
+    /** Scannable bullets of what to look at. Not a paragraph. */
+    lookFor?: string[];
+    /** Earlier layer ids this one depends on. */
+    dependsOn?: string[];
+    suggestedOrder: number;
+    hunkRefs: HunkRef[];
+};
+export type HunkRef = {
+    path: string;
+    oldPath?: string;
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+};
+export type HunkIndex = {
+    source: ReviewSource;
+    hunks: HunkRef[];
+    skipped: SkippedFile[];
+};
+export type SkippedFile = {
+    path: string;
+    reason: "binary";
+};
+export type DiffLineKind = "ctx" | "add" | "del";
+export type DiffLine = {
+    kind: DiffLineKind;
+    oldNumber: number | null;
+    newNumber: number | null;
+    text: string;
+};
+export type LiveHunk = HunkRef & {
+    header: string;
+    lines: DiffLine[];
+    patch: string;
+};
+export type FileStatus = "added" | "deleted" | "modified" | "renamed";
+export type DiffFile = {
+    path: string;
+    oldPath?: string;
+    status: FileStatus;
+    binary: boolean;
+    headerPatch: string;
+    patch: string;
+    hunks: LiveHunk[];
+};

package/dist/schema/types.js

@@ -0,0 +1,4 @@
+export const REVIEW_SIZES = ["trivial", "small", "medium", "large", "very-large"];
+export function isReviewSize(value) {
+    return typeof value === "string" && REVIEW_SIZES.includes(value);
+}

package/dist/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAU,CAAC;AAI3F,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC"}

package/dist/server/http.d.ts

@@ -0,0 +1,12 @@
+import { type Server } from "node:http";
+export type ServeOptions = {
+    cwd: string;
+    dataPath: string;
+    port: number;
+};
+export type RunningServer = {
+    server: Server;
+    port: number;
+    url: string;
+};
+export declare function startServer(opts: ServeOptions): Promise<RunningServer>;

package/dist/server/http.js

@@ -0,0 +1,270 @@
+import { createServer } from "node:http";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { coverReview } from "../review/coverage.js";
+import { fileLanguage, filePatchFromGit, readHunkIndex, resolveSource, toHunkRef } from "../git/diff.js";
+import { listCommits } from "../git/log.js";
+import { blameFile } from "../git/blame.js";
+import { showFile } from "../git/show.js";
+import { GitError } from "../git/exec.js";
+import { mergeBase } from "../git/repo.js";
+import { loadDocument } from "../cli/commands.js";
+import { findPackageRoot } from "../package-root.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".map": "application/json; charset=utf-8",
+    ".woff2": "font/woff2",
+};
+export async function startServer(opts) {
+    const uiRoot = join(findPackageRoot(), "dist/ui");
+    const server = createServer((req, res) => {
+        void handle(req, res, opts, uiRoot);
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(opts.port, "127.0.0.1", () => resolve());
+        server.once("error", reject);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("server failed to bind 127.0.0.1");
+    }
+    const url = `http://127.0.0.1:${address.port}`;
+    return { server, port: address.port, url };
+}
+async function handle(req, res, opts, uiRoot) {
+    try {
+        const host = req.headers.host ?? `127.0.0.1:${opts.port}`;
+        const url = new URL(req.url ?? "/", `http://${host}`);
+        if (req.method !== "GET") {
+            json(res, 405, { error: "method not allowed" });
+            return;
+        }
+        if (url.pathname === "/api/health") {
+            json(res, 200, { ok: true });
+            return;
+        }
+        if (url.pathname === "/api/review") {
+            json(res, 200, await reviewPayload(opts));
+            return;
+        }
+        if (url.pathname === "/api/hunks") {
+            json(res, 200, await hunksPayload(opts, url.searchParams.get("group")));
+            return;
+        }
+        if (url.pathname === "/api/file") {
+            json(res, 200, await filePayload(opts, url.searchParams));
+            return;
+        }
+        if (url.pathname === "/api/blame") {
+            json(res, 200, await blamePayload(opts, url.searchParams));
+            return;
+        }
+        await serveStatic(res, uiRoot, url.pathname);
+    }
+    catch (error) {
+        const status = error instanceof HttpError ? error.status : 500;
+        const message = error instanceof Error ? error.message : String(error);
+        const extra = error instanceof GitError ? { stderr: error.stderr } : {};
+        json(res, status, { error: message, ...extra });
+    }
+}
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+async function reviewPayload(opts) {
+    const document = await loadDocument(opts.dataPath);
+    const resolved = await resolveSource(opts.cwd, document.source.baseRef, document.source.headRef);
+    const { files, coverage } = await coverReview(opts.cwd, document);
+    const index = await readHunkIndex(opts.cwd, document.source.baseRef, document.source.headRef);
+    const commits = await listCommits(opts.cwd, document.source.baseRef, document.source.headRef);
+    return {
+        document,
+        resolved: {
+            baseRef: document.source.baseRef,
+            headRef: document.source.headRef,
+            range: document.source.range ?? `${document.source.baseRef}...${document.source.headRef}`,
+            baseSha: resolved.baseSha,
+            headSha: resolved.headSha,
+        },
+        coverage: {
+            totalHunks: coverage.totalHunks,
+            assignedHunks: coverage.assignedHunks,
+            unassignedCount: coverage.unassigned.length,
+            staleCount: coverage.stale.length,
+        },
+        groups: coverage.groups
+            .slice()
+            .sort((a, b) => a.group.suggestedOrder - b.group.suggestedOrder || a.group.id.localeCompare(b.group.id))
+            .map((group) => ({
+            id: group.group.id,
+            title: group.group.title,
+            summary: group.group.summary,
+            lookFor: group.group.lookFor ?? [],
+            dependsOn: group.group.dependsOn ?? [],
+            suggestedOrder: group.group.suggestedOrder,
+            hunkCount: group.hunks.length,
+            staleCount: group.stale.length,
+            files: uniquePaths(group.hunks),
+        })),
+        unassigned: {
+            hunkCount: coverage.unassigned.length,
+            files: uniquePaths(coverage.unassigned),
+        },
+        stale: coverage.stale,
+        files: files.map((file) => ({
+            path: file.path,
+            oldPath: file.oldPath,
+            status: file.status,
+            binary: file.binary,
+            hunkCount: file.hunks.length,
+        })),
+        skipped: index.skipped,
+        commits,
+    };
+}
+async function hunksPayload(opts, groupId) {
+    if (groupId === null || groupId === "") {
+        throw new HttpError(400, "missing group query");
+    }
+    const document = await loadDocument(opts.dataPath);
+    const { files, coverage } = await coverReview(opts.cwd, document);
+    if (groupId === "unassigned") {
+        return serializeLayer(files, coverage.unassigned);
+    }
+    const group = coverage.groups.find((item) => item.group.id === groupId);
+    if (group === undefined) {
+        throw new HttpError(404, `unknown group "${groupId}"`);
+    }
+    return serializeLayer(files, group.hunks);
+}
+function serializeLayer(files, hunks) {
+    const groups = [];
+    for (const hunk of hunks) {
+        const existing = groups.find((group) => group.file.path === hunk.path);
+        if (existing !== undefined) {
+            existing.hunks.push(hunk);
+            continue;
+        }
+        const file = files.find((item) => item.path === hunk.path);
+        if (file === undefined) {
+            continue;
+        }
+        groups.push({ file, hunks: [hunk] });
+    }
+    const serializedFiles = groups.map(({ file, hunks: fileHunks }) => {
+        const next = {
+            path: file.path,
+            patch: filePatchFromGit(file, fileHunks),
+            hunks: fileHunks.map(serializeHunk),
+        };
+        if (file.oldPath !== undefined) {
+            next.oldPath = file.oldPath;
+        }
+        return next;
+    });
+    return { hunks: hunks.map(serializeHunk), files: serializedFiles };
+}
+async function filePayload(opts, params) {
+    const path = requiredQuery(params, "path");
+    const side = params.get("side") === "old" ? "old" : "new";
+    const document = await loadDocument(opts.dataPath);
+    const { files } = await coverReview(opts.cwd, document);
+    const file = findFile(files, path);
+    const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
+    if (side === "old" && file.status === "added") {
+        throw new HttpError(404, "file did not exist on the base side");
+    }
+    if (side === "new" && file.status === "deleted") {
+        throw new HttpError(404, "file does not exist on the head side");
+    }
+    const ref = side === "old" ? await mergeBase(opts.cwd, document.source.baseRef, document.source.headRef) : document.source.headRef;
+    try {
+        const content = await showFile(opts.cwd, ref, lookup);
+        return { path: lookup, ref, side, content, language: fileLanguage(lookup) };
+    }
+    catch (error) {
+        throw new HttpError(404, error instanceof Error ? error.message : "file not found");
+    }
+}
+async function blamePayload(opts, params) {
+    const path = requiredQuery(params, "path");
+    const side = params.get("side") === "old" ? "old" : "new";
+    const document = await loadDocument(opts.dataPath);
+    const { files } = await coverReview(opts.cwd, document);
+    const file = findFile(files, path);
+    const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
+    if (side === "old" && file.status === "added") {
+        throw new HttpError(404, "file did not exist on the base side");
+    }
+    if (side === "new" && file.status === "deleted") {
+        throw new HttpError(404, "file does not exist on the head side");
+    }
+    const ref = side === "old" ? await mergeBase(opts.cwd, document.source.baseRef, document.source.headRef) : document.source.headRef;
+    try {
+        const lines = await blameFile(opts.cwd, ref, lookup);
+        return { path: lookup, ref, side, lines };
+    }
+    catch (error) {
+        throw new HttpError(404, error instanceof Error ? error.message : "blame not available");
+    }
+}
+function findFile(files, path) {
+    const file = files.find((item) => item.path === path || item.oldPath === path);
+    if (file === undefined) {
+        throw new HttpError(404, `path is not in the live diff: ${path}`);
+    }
+    return file;
+}
+function requiredQuery(params, name) {
+    const value = params.get(name);
+    if (value === null || value === "") {
+        throw new HttpError(400, `missing ${name}`);
+    }
+    return value;
+}
+function serializeHunk(hunk) {
+    return {
+        ...toHunkRef(hunk),
+        header: hunk.header,
+        language: fileLanguage(hunk.path),
+        lines: hunk.lines,
+    };
+}
+function uniquePaths(hunks) {
+    return [...new Set(hunks.map((hunk) => hunk.path))];
+}
+function json(res, status, body) {
+    const payload = `${JSON.stringify(body)}\n`;
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "content-length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+async function serveStatic(res, uiRoot, pathname) {
+    if (!existsSync(uiRoot)) {
+        throw new HttpError(503, "UI is missing from this install. Reinstall comprehende from npm, or from a git checkout run `pnpm build`.");
+    }
+    const relative = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
+    const uiAbs = resolve(uiRoot);
+    const candidate = resolve(uiRoot, relative);
+    if (candidate !== uiAbs && !candidate.startsWith(`${uiAbs}/`)) {
+        throw new HttpError(400, "invalid path");
+    }
+    const filePath = existsSync(candidate) && statSync(candidate).isFile() ? candidate : join(uiRoot, "index.html");
+    const stream = createReadStream(filePath);
+    res.writeHead(200, {
+        "content-type": MIME[extname(filePath)] ?? "application/octet-stream",
+        "cache-control": pathname.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-store",
+    });
+    stream.pipe(res);
+}