@prismatic-io/lux 0.0.2-preview.4 → 0.0.2-preview.41

package/src/previewer/server.ts

@@ -0,0 +1,789 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { basename, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type DriverMetricDescriptor, type DriverMetrics, exec } from "../core/index.js";
+import {
+  compareRuns,
+  compareSuiteRuns,
+  hasRegression,
+  type ListedRun,
+  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));
+
+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 }>;
+};
+
+type PreviewAssets = {
+  html: Buffer;
+  files: Map<string, { body: Buffer; contentType: 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;
+};
+
+const opaqueId = (runsRoot: string, path: string): string =>
+  Buffer.from(relative(resolve(runsRoot), resolve(path))).toString("base64url");
+
+const displayPath = (runsRoot: string, path: string): string => {
+  const value = relative(resolve(runsRoot), resolve(path));
+  return value.split(sep).join("/");
+};
+
+const runStatus = (run: ListedRun): PreviewStatus => {
+  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: string): PreviewStatus => {
+  if (status === "passed" || status === "failed" || status === "running" || status === "aborted") {
+    return status;
+  }
+  return "ungraded";
+};
+
+const buildSnapshot = async (
+  runsRoot: string,
+  options: Pick<StartPreviewServerOptions, "initialPath" | "initialKind" | "caseFilter">,
+): Promise<PreviewSnapshot> => {
+  const absoluteRunsRoot = resolve(runsRoot);
+  const readErrors: PreviewSnapshot["readErrors"] = [];
+  const onReadError = (kind: "suite" | "experiment") => (path: string, error: unknown) => {
+    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): PreviewRun => ({
+        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): PreviewSuite => ({
+      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): PreviewExperiment => ({
+      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: Array<PreviewRun | PreviewSuite | PreviewExperiment> = [
+    ...runs,
+    ...suites,
+    ...experiments,
+  ];
+  let initialEntry: (typeof candidates)[number] | undefined;
+  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: IncomingMessage,
+  response: ServerResponse,
+  status: number,
+  contentType: string,
+  body: Buffer | string,
+  cacheControl = "no-store",
+): void => {
+  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: IncomingMessage,
+  response: ServerResponse,
+  status: number,
+  value: unknown,
+): void => {
+  send(request, response, status, "application/json; charset=utf-8", JSON.stringify(value));
+};
+
+const findRunById = async (runsRoot: string, id: string): Promise<ListedRun | null> => {
+  const runs = await listRuns(runsRoot);
+  return runs.find((run) => opaqueId(runsRoot, run.runDir) === id) ?? null;
+};
+
+const findRunsById = async (
+  runsRoot: string,
+  ids: readonly string[],
+): Promise<ListedRun[] | null> => {
+  const runs = await listRuns(runsRoot);
+  const found = ids.map((id) => runs.find((run) => opaqueId(runsRoot, run.runDir) === id) ?? null);
+  return found.every((run): run is ListedRun => run !== null) ? found : null;
+};
+
+const findSuiteById = async (
+  runsRoot: string,
+  id: string,
+): Promise<Awaited<ReturnType<typeof listSuiteRuns>>[number] | null> => {
+  const suites = await listSuiteRuns(runsRoot, { onReadError: () => undefined });
+  return suites.find((suite) => opaqueId(runsRoot, suite.suiteDir) === id) ?? null;
+};
+
+const findSuitesById = async (
+  runsRoot: string,
+  ids: readonly string[],
+): Promise<Awaited<ReturnType<typeof listSuiteRuns>> | null> => {
+  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 is Awaited<ReturnType<typeof listSuiteRuns>>[number] => suite !== null,
+  )
+    ? found
+    : null;
+};
+
+const findExperimentById = async (
+  runsRoot: string,
+  id: string,
+): Promise<Awaited<ReturnType<typeof listExperimentRuns>>[number] | null> => {
+  const experiments = await listExperimentRuns(runsRoot, { onReadError: () => undefined });
+  return (
+    experiments.find((experiment) => opaqueId(runsRoot, experiment.experimentDir) === id) ?? null
+  );
+};
+
+const artifactPreview = async (run: ListedRun, path: string) => {
+  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: string, runDir: string) => ({
+  ...(await loadRunDetail(runDir, { maxArtifacts: 2_000 })),
+  runDir: displayPath(runsRoot, runDir),
+});
+
+const requiredPair = (url: URL): [string, string] | null => {
+  const before = url.searchParams.get("before");
+  const after = url.searchParams.get("after");
+  return before && after && before !== after ? [before, after] : null;
+};
+
+const isLoopbackHost = (host: string | undefined): boolean =>
+  host === LOOPBACK_HOST || host?.startsWith(`${LOOPBACK_HOST}:`) === true;
+
+type RouteContext = {
+  request: IncomingMessage;
+  response: ServerResponse;
+  url: URL;
+  runsRoot: string;
+};
+
+const handleRunComparison = async ({
+  request,
+  response,
+  url,
+  runsRoot,
+}: RouteContext): Promise<void> => {
+  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",
+    regressed: hasRegression(comparison),
+    comparison: {
+      ...comparison,
+      pathA: displayPath(runsRoot, before.runDir),
+      pathB: displayPath(runsRoot, after.runDir),
+    },
+    before: beforeDetail,
+    after: afterDetail,
+  });
+};
+
+const handleSuiteComparison = async ({
+  request,
+  response,
+  url,
+  runsRoot,
+}: RouteContext): Promise<void> => {
+  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,
+}: RouteContext): Promise<void> => {
+  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: RouteContext): Promise<boolean> => {
+  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,
+}: RouteContext): Promise<boolean> => {
+  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: string,
+  experiment: NonNullable<Awaited<ReturnType<typeof findExperimentById>>>,
+): Promise<Record<string, unknown>> => {
+  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,
+}: RouteContext): Promise<boolean> => {
+  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: PreviewAssets,
+    runsRoot: string,
+    options: Pick<StartPreviewServerOptions, "initialPath" | "initialKind" | "caseFilter">,
+  ) =>
+  async (request: IncomingMessage, response: ServerResponse): Promise<void> => {
+    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 (): Promise<PreviewAssets> => {
+  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"],
+  ] as const;
+  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: Server, port: number): Promise<void> =>
+  new Promise((resolveListen, reject) => {
+    const onError = (error: Error): void => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = (): void => {
+      server.off("error", onError);
+      resolveListen();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, LOOPBACK_HOST);
+  });
+
+export const startPreviewServer = async (
+  options: StartPreviewServerOptions,
+): Promise<PreviewServer> => {
+  const runsRoot = resolve(options.runsRoot);
+  const assets = await loadAssets();
+  const server = createServer((request, response) => {
+    void requestHandler(
+      assets,
+      runsRoot,
+      options,
+    )(request, response).catch((error: unknown) => {
+      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: Promise<void> | null = null;
+  const close = (): Promise<void> => {
+    closePromise ??= new Promise((resolveClose, reject) => {
+      server.close((error) => {
+        options.signal?.removeEventListener("abort", onAbort);
+        if (error) reject(error);
+        else resolveClose();
+      });
+    });
+    return closePromise;
+  };
+  const onAbort = (): void => {
+    void close();
+  };
+  if (options.signal?.aborted) onAbort();
+  else options.signal?.addEventListener("abort", onAbort, { once: true });
+  const closed = new Promise<void>((resolveClosed) => {
+    server.once("close", resolveClosed);
+  });
+  return {
+    url: `http://${LOOPBACK_HOST}:${address.port}`,
+    closed,
+    close,
+  };
+};
+
+export const openPreviewUrl = async (url: string): Promise<void> => {
+  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"}`,
+    );
+  }
+};