@prismatic-io/lux 0.0.2-preview.3 → 0.0.2-preview.32

package/lib/previewer/server.d.ts

@@ -0,0 +1,111 @@
+import { type DriverMetricDescriptor, type DriverMetrics } from "../core/index.js";
+type PreviewKind = "run" | "suite" | "experiment";
+type PreviewStatus = "passed" | "failed" | "running" | "aborted" | "error" | "ungraded";
+type PreviewRun = {
+    id: string;
+    kind: "run";
+    status: PreviewStatus;
+    caseId: string;
+    driver: string;
+    agentId: string | null;
+    startedAt: string | null;
+    durationMs: number | null;
+    timeToFirstActionMs: number | null;
+    timeToFirstMutationMs: number | null;
+    timeToFirstDurableMutationMs: number | null;
+    driverMetrics: DriverMetrics;
+    subagentCount: number;
+    score: number | null;
+    assertions: {
+        passed: number;
+        total: number;
+    };
+    path: string;
+    readErrors?: string[];
+};
+type PreviewSuite = {
+    id: string;
+    kind: "suite";
+    status: PreviewStatus;
+    suiteId: string;
+    startedAt: string;
+    endedAt: string | null;
+    concurrency: number;
+    profileId?: string | undefined;
+    items: Array<{
+        caseId: string;
+        canonicalCaseId: string;
+        status: string;
+        exitReason: string | null;
+        casePassed: boolean | null;
+        runId: string | null;
+        errorMessage?: string | undefined;
+    }>;
+    path: string;
+};
+type PreviewExperiment = {
+    id: string;
+    kind: "experiment";
+    status: PreviewStatus;
+    experimentId: string;
+    campaignId: string;
+    mode: "experiment" | "optimize";
+    startedAt: string;
+    endedAt: string | null;
+    activeTimeMs: number;
+    candidateCount: number;
+    championCandidateId: string | null;
+    budget: {
+        metricCalls: number;
+        judgeCalls: number;
+        proposalCalls: number;
+        costUsd: number;
+    };
+    evaluations: Array<{
+        candidateId: string;
+        profileId: string;
+        split: "train" | "validation" | "test";
+        passRate: number;
+        metrics: Record<string, number>;
+        metricDefinitions: Record<string, DriverMetricDescriptor>;
+        failedCases: Array<{
+            caseId: string;
+            score: number | null;
+            feedback: string[];
+        }>;
+    }>;
+    path: string;
+};
+export type PreviewSnapshot = {
+    generatedAt: string;
+    runsRoot: string;
+    initial: {
+        kind: PreviewKind;
+        id: string;
+    } | null;
+    runs: PreviewRun[];
+    suites: PreviewSuite[];
+    experiments: PreviewExperiment[];
+    readErrors: Array<{
+        kind: "suite" | "experiment";
+        path: string;
+        message: string;
+    }>;
+};
+export type PreviewServer = {
+    url: string;
+    closed: Promise<void>;
+    close: () => Promise<void>;
+};
+export type StartPreviewServerOptions = {
+    runsRoot: string;
+    port?: number | undefined;
+    initialPath?: string | undefined;
+    initialKind?: PreviewKind | undefined;
+    caseFilter?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+export declare const startPreviewServer: (options: StartPreviewServerOptions) => Promise<PreviewServer>;
+export declare const openPreviewUrl: (url: string) => Promise<void>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/lib/previewer/server.d.ts.map

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

package/lib/previewer/server.js

@@ -0,0 +1,558 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { exec } from "../core/index.js";
+import { compareRuns, compareSuiteRuns, listExperimentRuns, listRuns, listSuiteRuns, loadExperimentCandidates, loadRunArtifacts, loadRunDetail, loadSuiteSummary, loadVerifiedExperimentDecisionSnapshot, } from "../orchestrator/index.js";
+import { compareArtifactPreviews, loadArtifactPreview } from "./artifacts.js";
+const LOOPBACK_HOST = "127.0.0.1";
+const ASSET_ROOT = fileURLToPath(new URL("../../viewer/", import.meta.url));
+const opaqueId = (runsRoot, path) => Buffer.from(relative(resolve(runsRoot), resolve(path))).toString("base64url");
+const displayPath = (runsRoot, path) => {
+    const value = relative(resolve(runsRoot), resolve(path));
+    return value.split(sep).join("/");
+};
+const runStatus = (run) => {
+    if (run.readErrors?.length)
+        return "error";
+    if (run.exitReason && run.exitReason !== "done")
+        return "error";
+    if (run.casePassed === true)
+        return "passed";
+    if (run.casePassed === false)
+        return "failed";
+    return "ungraded";
+};
+const normalizeStatus = (status) => {
+    if (status === "passed" || status === "failed" || status === "running" || status === "aborted") {
+        return status;
+    }
+    return "ungraded";
+};
+const buildSnapshot = async (runsRoot, options) => {
+    const absoluteRunsRoot = resolve(runsRoot);
+    const readErrors = [];
+    const onReadError = (kind) => (path, error) => {
+        readErrors.push({
+            kind,
+            path: displayPath(absoluteRunsRoot, path),
+            message: (error instanceof Error ? error.message : String(error)).replaceAll(absoluteRunsRoot, "."),
+        });
+    };
+    const [listedRuns, listedSuites, listedExperiments] = await Promise.all([
+        listRuns(absoluteRunsRoot),
+        listSuiteRuns(absoluteRunsRoot, { onReadError: onReadError("suite") }),
+        listExperimentRuns(absoluteRunsRoot, { onReadError: onReadError("experiment") }),
+    ]);
+    const runs = listedRuns
+        .filter((run) => !options.caseFilter || run.caseSlug === options.caseFilter)
+        .map((run) => ({
+        id: opaqueId(absoluteRunsRoot, run.runDir),
+        kind: "run",
+        status: runStatus(run),
+        caseId: run.caseSlug,
+        driver: run.driverName,
+        agentId: run.driverAgentId,
+        startedAt: run.startedAt,
+        durationMs: run.durationMs,
+        timeToFirstActionMs: run.timeToFirstActionMs,
+        timeToFirstMutationMs: run.timeToFirstMutationMs,
+        timeToFirstDurableMutationMs: run.timeToFirstDurableMutationMs,
+        driverMetrics: run.driverMetrics,
+        subagentCount: run.subagentCount,
+        score: run.caseScore,
+        assertions: { passed: run.assertionPassed, total: run.assertionTotal },
+        path: displayPath(absoluteRunsRoot, run.runDir),
+        ...(run.readErrors
+            ? {
+                readErrors: run.readErrors.map((message) => message.replaceAll(absoluteRunsRoot, ".")),
+            }
+            : {}),
+    }));
+    const runIdsByPath = new Map(listedRuns.map((run) => [resolve(run.runDir), opaqueId(absoluteRunsRoot, run.runDir)]));
+    const suites = listedSuites.map((suite) => ({
+        id: opaqueId(absoluteRunsRoot, suite.suiteDir),
+        kind: "suite",
+        status: normalizeStatus(suite.status),
+        suiteId: suite.suiteId,
+        startedAt: suite.startedAt,
+        endedAt: suite.endedAt,
+        concurrency: suite.concurrency,
+        ...(suite.profileId ? { profileId: suite.profileId } : {}),
+        items: suite.items.map((item) => ({
+            caseId: item.caseId,
+            canonicalCaseId: item.canonicalCaseId,
+            status: item.status,
+            exitReason: item.exitReason,
+            casePassed: item.casePassed,
+            runId: item.runDir
+                ? (runIdsByPath.get(resolve(suite.suiteDir, item.runDir)) ?? null)
+                : null,
+            ...(item.errorMessage ? { errorMessage: item.errorMessage } : {}),
+        })),
+        path: displayPath(absoluteRunsRoot, suite.suiteDir),
+    }));
+    const experiments = listedExperiments.map((experiment) => ({
+        id: opaqueId(absoluteRunsRoot, experiment.experimentDir),
+        kind: "experiment",
+        status: normalizeStatus(experiment.status),
+        experimentId: experiment.experimentId,
+        campaignId: experiment.campaignId,
+        mode: experiment.mode,
+        startedAt: experiment.startedAt,
+        endedAt: experiment.endedAt,
+        activeTimeMs: experiment.activeTimeMs,
+        candidateCount: experiment.candidates.length,
+        championCandidateId: experiment.championCandidateId ?? null,
+        budget: {
+            metricCalls: experiment.budgetUsage.metricCalls,
+            judgeCalls: experiment.budgetUsage.judgeCalls,
+            proposalCalls: experiment.budgetUsage.proposalCalls,
+            costUsd: experiment.budgetUsage.costUsd,
+        },
+        evaluations: experiment.evaluations.map((evaluation) => ({
+            candidateId: evaluation.candidateId,
+            profileId: evaluation.profileId,
+            split: evaluation.split,
+            passRate: evaluation.passRate,
+            metrics: evaluation.metrics,
+            metricDefinitions: evaluation.metricDefinitions ?? {},
+            failedCases: evaluation.failedCases,
+        })),
+        path: displayPath(absoluteRunsRoot, experiment.experimentDir),
+    }));
+    const initialPath = options.initialPath ? resolve(options.initialPath) : null;
+    const initialKind = options.initialKind;
+    const candidates = [
+        ...runs,
+        ...suites,
+        ...experiments,
+    ];
+    let initialEntry;
+    if (initialPath) {
+        initialEntry = candidates.find((entry) => (!initialKind || entry.kind === initialKind) &&
+            resolve(absoluteRunsRoot, entry.path) === initialPath);
+    }
+    else if (initialKind) {
+        initialEntry = candidates.find((entry) => entry.kind === initialKind);
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        runsRoot: absoluteRunsRoot,
+        initial: initialEntry ? { kind: initialEntry.kind, id: initialEntry.id } : null,
+        runs,
+        suites,
+        experiments,
+        readErrors: readErrors.sort((a, b) => a.path.localeCompare(b.path)),
+    };
+};
+const securityHeaders = {
+    "Content-Security-Policy": "default-src 'self'; base-uri 'none'; connect-src 'self'; form-action 'none'; frame-ancestors 'none'; img-src 'self' data:; object-src 'none'; script-src 'self'; style-src 'self'",
+    "Cross-Origin-Opener-Policy": "same-origin",
+    "Cross-Origin-Resource-Policy": "same-origin",
+    "Permissions-Policy": "camera=(), geolocation=(), microphone=()",
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+};
+const send = (request, response, status, contentType, body, cacheControl = "no-store") => {
+    const bytes = Buffer.isBuffer(body) ? body : Buffer.from(body);
+    response.writeHead(status, {
+        ...securityHeaders,
+        "Cache-Control": cacheControl,
+        "Content-Length": bytes.length,
+        "Content-Type": contentType,
+    });
+    response.end(request.method === "HEAD" ? undefined : bytes);
+};
+const sendJson = (request, response, status, value) => {
+    send(request, response, status, "application/json; charset=utf-8", JSON.stringify(value));
+};
+const findRunById = async (runsRoot, id) => {
+    const runs = await listRuns(runsRoot);
+    return runs.find((run) => opaqueId(runsRoot, run.runDir) === id) ?? null;
+};
+const findRunsById = async (runsRoot, ids) => {
+    const runs = await listRuns(runsRoot);
+    const found = ids.map((id) => runs.find((run) => opaqueId(runsRoot, run.runDir) === id) ?? null);
+    return found.every((run) => run !== null) ? found : null;
+};
+const findSuiteById = async (runsRoot, id) => {
+    const suites = await listSuiteRuns(runsRoot, { onReadError: () => undefined });
+    return suites.find((suite) => opaqueId(runsRoot, suite.suiteDir) === id) ?? null;
+};
+const findSuitesById = async (runsRoot, ids) => {
+    const suites = await listSuiteRuns(runsRoot, { onReadError: () => undefined });
+    const found = ids.map((id) => suites.find((suite) => opaqueId(runsRoot, suite.suiteDir) === id) ?? null);
+    return found.every((suite) => suite !== null)
+        ? found
+        : null;
+};
+const findExperimentById = async (runsRoot, id) => {
+    const experiments = await listExperimentRuns(runsRoot, { onReadError: () => undefined });
+    return (experiments.find((experiment) => opaqueId(runsRoot, experiment.experimentDir) === id) ?? null);
+};
+const artifactPreview = async (run, path) => {
+    const [detail, indexed] = await Promise.all([
+        loadRunDetail(run.runDir, { maxArtifacts: 2_000 }),
+        loadRunArtifacts(run.runDir),
+    ]);
+    return loadArtifactPreview(run.runDir, indexed, detail.artifacts, path);
+};
+const publicRunDetail = async (runsRoot, runDir) => ({
+    ...(await loadRunDetail(runDir, { maxArtifacts: 2_000 })),
+    runDir: displayPath(runsRoot, runDir),
+});
+const requiredPair = (url) => {
+    const before = url.searchParams.get("before");
+    const after = url.searchParams.get("after");
+    return before && after && before !== after ? [before, after] : null;
+};
+const isLoopbackHost = (host) => host === LOOPBACK_HOST || host?.startsWith(`${LOOPBACK_HOST}:`) === true;
+const handleRunComparison = async ({ request, response, url, runsRoot, }) => {
+    const pair = requiredPair(url);
+    if (!pair) {
+        sendJson(request, response, 400, { error: "two distinct run ids are required" });
+        return;
+    }
+    const runs = await findRunsById(runsRoot, pair);
+    if (!runs) {
+        sendJson(request, response, 404, { error: "run not found" });
+        return;
+    }
+    const [before, after] = runs;
+    if (!before || !after)
+        throw new Error("run pair resolution failed");
+    const [comparison, beforeDetail, afterDetail] = await Promise.all([
+        compareRuns({ pathA: before.runDir, pathB: after.runDir }),
+        publicRunDetail(runsRoot, before.runDir),
+        publicRunDetail(runsRoot, after.runDir),
+    ]);
+    sendJson(request, response, 200, {
+        kind: "run",
+        comparison: {
+            ...comparison,
+            pathA: displayPath(runsRoot, before.runDir),
+            pathB: displayPath(runsRoot, after.runDir),
+        },
+        before: beforeDetail,
+        after: afterDetail,
+    });
+};
+const handleSuiteComparison = async ({ request, response, url, runsRoot, }) => {
+    const pair = requiredPair(url);
+    if (!pair) {
+        sendJson(request, response, 400, { error: "two distinct suite ids are required" });
+        return;
+    }
+    const suites = await findSuitesById(runsRoot, pair);
+    if (!suites) {
+        sendJson(request, response, 404, { error: "suite not found" });
+        return;
+    }
+    const [before, after] = suites;
+    if (!before || !after)
+        throw new Error("suite pair resolution failed");
+    const [comparison, beforeSummary, afterSummary] = await Promise.all([
+        compareSuiteRuns(before.suiteDir, after.suiteDir),
+        loadSuiteSummary(before.suiteDir),
+        loadSuiteSummary(after.suiteDir),
+    ]);
+    sendJson(request, response, 200, {
+        kind: "suite",
+        comparison: {
+            ...comparison,
+            pathA: displayPath(runsRoot, before.suiteDir),
+            pathB: displayPath(runsRoot, after.suiteDir),
+        },
+        before: beforeSummary,
+        after: afterSummary,
+    });
+};
+const handleArtifactComparison = async ({ request, response, url, runsRoot, }) => {
+    const pair = requiredPair(url);
+    const path = url.searchParams.get("path");
+    if (!pair || !path) {
+        sendJson(request, response, 400, {
+            error: "two distinct run ids and an artifact path are required",
+        });
+        return;
+    }
+    const runs = await findRunsById(runsRoot, pair);
+    if (!runs) {
+        sendJson(request, response, 404, { error: "run not found" });
+        return;
+    }
+    const [before, after] = runs;
+    if (!before || !after)
+        throw new Error("artifact run pair resolution failed");
+    const [beforePreview, afterPreview] = await Promise.all([
+        artifactPreview(before, path),
+        artifactPreview(after, path),
+    ]);
+    sendJson(request, response, 200, compareArtifactPreviews(path, beforePreview, afterPreview));
+};
+const handleComparisonRoute = async (context) => {
+    if (context.url.pathname === "/api/compare/runs") {
+        await handleRunComparison(context);
+        return true;
+    }
+    if (context.url.pathname === "/api/compare/suites") {
+        await handleSuiteComparison(context);
+        return true;
+    }
+    if (context.url.pathname === "/api/compare/artifacts") {
+        await handleArtifactComparison(context);
+        return true;
+    }
+    return false;
+};
+const handleArtifactRoute = async ({ request, response, url, runsRoot, }) => {
+    if (url.pathname !== "/api/artifact")
+        return false;
+    const runId = url.searchParams.get("run");
+    const path = url.searchParams.get("path");
+    if (!runId || !path) {
+        sendJson(request, response, 400, { error: "a run id and artifact path are required" });
+        return true;
+    }
+    const run = await findRunById(runsRoot, runId);
+    if (!run) {
+        sendJson(request, response, 404, { error: "run not found" });
+        return true;
+    }
+    const preview = await artifactPreview(run, path);
+    sendJson(request, response, preview.exists ? 200 : 404, preview);
+    return true;
+};
+const experimentDetail = async (runsRoot, experiment) => {
+    const [candidateResult, decisionResult] = await Promise.allSettled([
+        loadExperimentCandidates(experiment.experimentDir),
+        loadVerifiedExperimentDecisionSnapshot(experiment.experimentDir),
+    ]);
+    const integrityErrors = [candidateResult, decisionResult].flatMap((result) => result.status === "rejected"
+        ? [result.reason instanceof Error ? result.reason.message : String(result.reason)]
+        : []);
+    return {
+        experiment: {
+            experimentId: experiment.experimentId,
+            campaignId: experiment.campaignId,
+            mode: experiment.mode,
+            evaluationKind: experiment.evaluationKind,
+            status: experiment.status,
+            startedAt: experiment.startedAt,
+            endedAt: experiment.endedAt,
+            activeTimeMs: experiment.activeTimeMs,
+            championCandidateId: experiment.championCandidateId ?? null,
+            errorMessage: experiment.errorMessage ?? null,
+            selection: experiment.selection ?? null,
+            budgetUsage: experiment.budgetUsage,
+            evaluations: experiment.evaluations.map((evaluation) => ({
+                candidateId: evaluation.candidateId,
+                profileId: evaluation.profileId,
+                split: evaluation.split,
+                repetitions: evaluation.repetitions,
+                passRate: evaluation.passRate,
+                casePassRates: evaluation.casePassRates,
+                metrics: evaluation.metrics,
+                metricDefinitions: evaluation.metricDefinitions ?? {},
+                costUsd: evaluation.costUsd ?? null,
+                failedCases: evaluation.failedCases,
+            })),
+        },
+        candidates: candidateResult.status === "fulfilled"
+            ? candidateResult.value.map((candidate) => ({
+                id: candidate.id,
+                parentIds: candidate.parentIds,
+                createdAt: candidate.createdAt,
+                proposer: candidate.proposer,
+                sourceBytes: candidate.sourceBytes,
+                rationale: candidate.rationale ?? null,
+                components: Object.keys(candidate.components).sort(),
+            }))
+            : [],
+        decision: decisionResult.status === "fulfilled"
+            ? {
+                ...decisionResult.value.report,
+                experimentDir: displayPath(runsRoot, experiment.experimentDir),
+            }
+            : null,
+        integrity: {
+            verified: integrityErrors.length === 0,
+            errors: integrityErrors,
+        },
+    };
+};
+const handleDetailRoute = async ({ request, response, url, runsRoot, }) => {
+    if (url.pathname.startsWith("/api/suites/")) {
+        const suite = await findSuiteById(runsRoot, url.pathname.slice("/api/suites/".length));
+        if (!suite)
+            sendJson(request, response, 404, { error: "suite not found" });
+        else
+            sendJson(request, response, 200, {
+                suite: {
+                    ...suite,
+                    suiteDir: displayPath(runsRoot, suite.suiteDir),
+                },
+                summary: await loadSuiteSummary(suite.suiteDir),
+            });
+        return true;
+    }
+    if (url.pathname.startsWith("/api/experiments/")) {
+        const experiment = await findExperimentById(runsRoot, url.pathname.slice("/api/experiments/".length));
+        if (!experiment)
+            sendJson(request, response, 404, { error: "experiment not found" });
+        else
+            sendJson(request, response, 200, await experimentDetail(runsRoot, experiment));
+        return true;
+    }
+    if (url.pathname.startsWith("/api/runs/")) {
+        const run = await findRunById(runsRoot, url.pathname.slice("/api/runs/".length));
+        if (!run)
+            sendJson(request, response, 404, { error: "run not found" });
+        else
+            sendJson(request, response, 200, await publicRunDetail(runsRoot, run.runDir));
+        return true;
+    }
+    return false;
+};
+const requestHandler = (assets, runsRoot, options) => async (request, response) => {
+    if (!isLoopbackHost(request.headers.host)) {
+        sendJson(request, response, 421, { error: "untrusted host" });
+        return;
+    }
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        sendJson(request, response, 405, { error: "method not allowed" });
+        return;
+    }
+    const url = new URL(request.url ?? "/", `http://${LOOPBACK_HOST}`);
+    if (url.pathname === "/" || url.pathname === "/index.html") {
+        send(request, response, 200, "text/html; charset=utf-8", assets.html);
+        return;
+    }
+    const asset = assets.files.get(url.pathname);
+    if (asset) {
+        send(request, response, 200, asset.contentType, asset.body, "no-cache");
+        return;
+    }
+    if (url.pathname === "/api/snapshot") {
+        sendJson(request, response, 200, await buildSnapshot(runsRoot, options));
+        return;
+    }
+    const context = { request, response, url, runsRoot };
+    if (await handleComparisonRoute(context))
+        return;
+    if (await handleArtifactRoute(context))
+        return;
+    if (await handleDetailRoute(context))
+        return;
+    if (url.pathname === "/health") {
+        sendJson(request, response, 200, { ok: true });
+        return;
+    }
+    sendJson(request, response, 404, { error: "not found" });
+};
+const loadAssets = async () => {
+    const htmlPath = resolve(ASSET_ROOT, "index.html");
+    const definitions = [
+        ["/assets/app.css", "app.css", "text/css; charset=utf-8"],
+        ["/assets/app.js", "app.js", "text/javascript; charset=utf-8"],
+        ["/assets/artifact-view.js", "artifact-view.js", "text/javascript; charset=utf-8"],
+        ["/assets/charts.js", "charts.js", "text/javascript; charset=utf-8"],
+        ["/assets/detail.js", "detail.js", "text/javascript; charset=utf-8"],
+        ["/assets/format.js", "format.js", "text/javascript; charset=utf-8"],
+    ];
+    const paths = [htmlPath, ...definitions.map((definition) => resolve(ASSET_ROOT, definition[1]))];
+    for (const path of paths) {
+        if (!existsSync(path))
+            throw new Error(`Lux preview asset is missing: ${basename(path)}`);
+    }
+    const [html, ...bodies] = await Promise.all(paths.map((path) => readFile(path)));
+    if (!html)
+        throw new Error("Lux preview index is empty");
+    const files = new Map(definitions.map(([url, , contentType], index) => {
+        const body = bodies[index];
+        if (!body)
+            throw new Error(`Lux preview asset is empty: ${url}`);
+        return [url, { body, contentType }];
+    }));
+    return { html, files };
+};
+const listen = (server, port) => new Promise((resolveListen, reject) => {
+    const onError = (error) => {
+        server.off("listening", onListening);
+        reject(error);
+    };
+    const onListening = () => {
+        server.off("error", onError);
+        resolveListen();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, LOOPBACK_HOST);
+});
+export const startPreviewServer = async (options) => {
+    const runsRoot = resolve(options.runsRoot);
+    const assets = await loadAssets();
+    const server = createServer((request, response) => {
+        void requestHandler(assets, runsRoot, options)(request, response).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!response.headersSent)
+                sendJson(request, response, 500, { error: message });
+            else
+                response.destroy();
+        });
+    });
+    await listen(server, options.port ?? 0);
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("Lux preview server did not receive a TCP address");
+    }
+    let closePromise = null;
+    const close = () => {
+        closePromise ??= new Promise((resolveClose, reject) => {
+            server.close((error) => {
+                options.signal?.removeEventListener("abort", onAbort);
+                if (error)
+                    reject(error);
+                else
+                    resolveClose();
+            });
+        });
+        return closePromise;
+    };
+    const onAbort = () => {
+        void close();
+    };
+    if (options.signal?.aborted)
+        onAbort();
+    else
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+    const closed = new Promise((resolveClosed) => {
+        server.once("close", resolveClosed);
+    });
+    return {
+        url: `http://${LOOPBACK_HOST}:${address.port}`,
+        closed,
+        close,
+    };
+};
+export const openPreviewUrl = async (url) => {
+    let launcher = { command: "xdg-open", args: [url] };
+    if (process.platform === "darwin") {
+        launcher = { command: "open", args: [url] };
+    }
+    else if (process.platform === "win32") {
+        launcher = { command: "cmd.exe", args: ["/d", "/s", "/c", "start", "", url] };
+    }
+    const result = await exec(launcher.command, launcher.args, {
+        timeoutMs: 5_000,
+        maxBuffer: 2_000,
+    });
+    if (result.exitCode !== 0 || result.timedOut) {
+        throw new Error(result.stderr.trim() || `browser launcher exited ${result.exitCode ?? "early"}`);
+    }
+};
+//# sourceMappingURL=server.js.map