@dev-loops/core 0.8.0 → 1.0.0-rc.1

package/src/loop/ui-review-provision.mjs

@@ -0,0 +1,264 @@
+/**
+ * Provision + boot orchestrator for the ui_review route (Stage 1).
+ *
+ * Provisions an isolated worktree for a PR head and boots the branch's app to a
+ * ready state, then hands off a booted app for the running-app review stages.
+ * The orchestration is a fail-closed sequence:
+ *
+ *   1. create-or-reuse the PR worktree (fetch before) and provision it
+ *   2. refuse to operate in the primary checkout (worktree guard)
+ *   3. install ONLY the dependency-lock delta vs. the primary checkout
+ *   4. run pending dev-DB migrations; a destructive one stops for explicit ack
+ *   5. resolve a per-project run recipe (no app is ever guessed)
+ *   6. boot the app and poll an HTTP readiness probe (never a fixed sleep)
+ *
+ * Every bounded cap (install skipped, migration ack required, boot timeout) is
+ * logged — no silent truncation. This module is pure orchestration: all IO
+ * (git/worktree, config, spawn, HTTP probe, clock) is injected so it is fully
+ * testable against a fixture project. The thin CLI wires the real seams.
+ *
+ * Out of scope (later stages): browser driving, auth, screenshots, review
+ * posting, production DB.
+ */
+
+import path from "node:path";
+
+const MUST_FIX = "must-fix";
+
+/**
+ * Run the provision+boot sequence.
+ *
+ * @param {object} input
+ * @param {string} input.repoRoot - Absolute path to the primary checkout.
+ * @param {number} input.pr - PR number whose head is provisioned.
+ * @param {string} [input.branch] - Branch to check out (default: pr-<n>).
+ * @param {boolean} [input.ackDestructiveMigration] - Explicit ack unblocking a
+ *   destructive/blocked migration. Fail-closed: absent means "not acknowledged".
+ * @param {object} seams - Injected IO (all required except clock/log defaults).
+ * @param {(a:{repoRoot:string,pr:number,branch?:string})=>Promise<{path:string,created:boolean,reused:boolean}>} seams.ensureWorktree
+ * @param {(a:{worktreePath:string,repoRoot:string})=>{ok:boolean,message?:string,mainWorktreePath?:string|null}} seams.assertNotPrimary
+ * @param {(a:{repoRoot:string,worktreePath:string})=>Promise<{changed:boolean,detail:string}>} seams.detectDepDelta
+ * @param {(a:{worktreePath:string})=>Promise<{ok:boolean,detail:string}>} seams.installDeps
+ * @param {(worktreePath:string)=>Promise<object|null>} seams.resolveRunRecipe
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{pending:string[],destructive:string[],detail:string}>} seams.inspectMigrations — MUST run in `runCwd` (the guard-validated absolute cwd), never re-derive it
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{ok:boolean,applied:number,detail:string}>} seams.applyMigrations — MUST run in `runCwd`
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{pid:number|null,detail:string}>} seams.bootApp — MUST run in `runCwd`
+ * @param {(url:string)=>Promise<boolean>} seams.probe
+ * @param {(ms:number)=>Promise<false> & {clear?:()=>void}} [seams.probeTimeout] -
+ *   Per-attempt cap: resolves false once `ms` elapses, so a hung probe can't
+ *   outlive the budget. May expose `clear()`; the poll calls it after each race
+ *   resolves so a pending timer is cancelled rather than left to fire.
+ * @param {(ms:number)=>Promise<void>} [seams.delay]
+ * @param {()=>number} [seams.now]
+ * @param {(msg:string)=>void} [seams.log]
+ * @returns {Promise<object>} A result envelope (see fields assembled below).
+ */
+export async function provisionAndBoot(
+  { repoRoot, pr, branch, ackDestructiveMigration = false },
+  {
+    ensureWorktree,
+    assertNotPrimary,
+    detectDepDelta,
+    installDeps,
+    resolveRunRecipe,
+    inspectMigrations,
+    applyMigrations,
+    bootApp,
+    probe,
+    probeTimeout = (ms) => {
+      let t;
+      const p = /** @type {Promise<false> & {clear?:()=>void}} */ (
+        new Promise((resolve) => {
+          t = setTimeout(() => resolve(false), ms);
+        })
+      );
+      // Self-clearing: the poll calls clear() after the race resolves, so a
+      // still-pending timer is cancelled outright (never left to fire, never
+      // holds the process open) — bounding any injected probe seam.
+      p.clear = () => clearTimeout(t);
+      return p;
+    },
+    delay = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => Date.now(),
+    log = () => {},
+  } = {},
+) {
+  const logs = [];
+  const findings = [];
+  const record = (msg) => {
+    logs.push(msg);
+    log(msg);
+  };
+  const base = () => ({ pr, branch: branch ?? null, findings, logs });
+  const stop = (stopReason, finding, extra = {}) => {
+    if (finding) findings.push(finding);
+    record(`STOP: ${stopReason}`);
+    return { ok: false, stopped: true, stopReason, ...base(), ...extra };
+  };
+
+  // 1. Create-or-reuse the PR worktree (ensureWorktree fetches + provisions).
+  const wt = await ensureWorktree({ repoRoot, pr, branch });
+  const worktreePath = wt.path;
+  record(`worktree ${wt.created ? "created" : "reused"}: ${worktreePath}`);
+
+  // 2. Fail closed if that path is the primary checkout — never operate there.
+  const guard = assertNotPrimary({ worktreePath, repoRoot });
+  if (!guard.ok) {
+    return stop(
+      "worktree guard: refusing to operate in the primary checkout",
+      { kind: "worktree-guard", severity: MUST_FIX, message: guard.message ?? "resolved worktree is the primary checkout" },
+      { worktreePath },
+    );
+  }
+
+  // 3. Install only the dependency-lock delta vs. the primary checkout. No delta
+  //    => deps are shared; installing anything would be a blind re-install.
+  const delta = await detectDepDelta({ repoRoot, worktreePath });
+  let depInstall = { installed: false, detail: delta.detail };
+  if (delta.changed) {
+    record(`dependency-lock delta detected (${delta.detail}); installing branch deps`);
+    const inst = await installDeps({ worktreePath });
+    depInstall = { installed: inst.ok, detail: inst.detail };
+    record(`dependency install ${inst.ok ? "ok" : "FAILED"}: ${inst.detail}`);
+    if (!inst.ok) {
+      return stop(
+        "dependency install failed",
+        { kind: "dep-install", severity: MUST_FIX, message: inst.detail },
+        { worktreePath, depInstall },
+      );
+    }
+  } else {
+    record(`dependency install skipped: no lock delta vs primary checkout (${delta.detail})`);
+  }
+
+  // 4. Resolve the per-project run recipe before migrate/boot (no app guessed).
+  const recipe = await resolveRunRecipe(worktreePath);
+  if (!recipe) {
+    return stop(
+      "no run recipe: the branch declares no uiReview.run recipe (cannot boot the app)",
+      { kind: "run-recipe-missing", severity: MUST_FIX, message: "declare uiReview.run.command + readyUrl in .devloops" },
+      { worktreePath, depInstall },
+    );
+  }
+
+  // 4b. Resolve + validate the run recipe's cwd ONCE, here — the single source
+  //     of cwd truth. The recipe's cwd is worktree-relative; a recipe that
+  //     escapes the worktree (e.g. cwd "../..") would run migrate/boot in
+  //     another checkout, so fail closed unless the resolved cwd stays inside
+  //     the provisioned tree. The validated ABSOLUTE path (`runCwd`) is what the
+  //     migrate/boot seams execute in — they consume it verbatim and never
+  //     re-derive it, so the guarded path and the executed path cannot drift.
+  let runCwd = worktreePath;
+  if (recipe.cwd) {
+    const resolvedCwd = path.resolve(worktreePath, recipe.cwd);
+    const insideWorktree = resolvedCwd === worktreePath || resolvedCwd.startsWith(worktreePath + path.sep);
+    if (!insideWorktree) {
+      return stop(
+        "run recipe cwd escapes the provisioned worktree",
+        { kind: "cwd-traversal", severity: MUST_FIX, message: `uiReview.run.cwd (${recipe.cwd}) resolves outside the worktree: ${resolvedCwd}` },
+        { worktreePath, depInstall },
+      );
+    }
+    runCwd = resolvedCwd;
+  }
+
+  // 5. Dev-DB migrations. A destructive/blocked migration fails closed to a
+  //    finding requiring explicit ack; nothing is applied until acknowledged.
+  let migrations = { pending: 0, applied: 0, destructive: [], detail: "no migrate recipe" };
+  if (recipe.migrate) {
+    const mig = await inspectMigrations({ worktreePath, recipe, runCwd });
+    record(`migration status: ${mig.pending.length} pending, ${mig.destructive.length} destructive (${mig.detail})`);
+    if (mig.destructive.length > 0 && !ackDestructiveMigration) {
+      return stop(
+        "destructive migration requires explicit acknowledgement",
+        {
+          kind: "destructive-migration",
+          severity: MUST_FIX,
+          requiresAck: true,
+          message: `${mig.destructive.length} destructive migration(s) blocked pending ack`,
+          destructive: mig.destructive,
+        },
+        { worktreePath, depInstall, migrations: { pending: mig.pending.length, applied: 0, destructive: mig.destructive, detail: mig.detail } },
+      );
+    }
+    if (mig.pending.length > 0) {
+      if (mig.destructive.length > 0) {
+        record(`destructive migration(s) acknowledged; applying ${mig.pending.length} pending migration(s)`);
+      }
+      const applied = await applyMigrations({ worktreePath, recipe, runCwd });
+      if (!applied.ok) {
+        return stop(
+          "migration apply failed",
+          { kind: "migration-apply", severity: MUST_FIX, message: applied.detail },
+          { worktreePath, depInstall, migrations: { pending: mig.pending.length, applied: 0, destructive: mig.destructive, detail: applied.detail } },
+        );
+      }
+      migrations = { pending: mig.pending.length, applied: applied.applied, destructive: mig.destructive, detail: applied.detail };
+      record(`migrations applied: ${applied.applied} (${applied.detail})`);
+    } else {
+      migrations = { pending: 0, applied: 0, destructive: mig.destructive, detail: "no pending migrations" };
+      record("no pending migrations");
+    }
+  } else {
+    record("migrations skipped: branch declares no migrate recipe");
+  }
+
+  // 6. Boot the app, then poll the readiness probe against an explicit deadline.
+  const boot = await bootApp({ worktreePath, recipe, runCwd });
+  record(`app booting (pid ${boot.pid ?? "n/a"}): ${boot.detail}`);
+
+  const timeoutMs = recipe.readyTimeoutMs;
+  const intervalMs = recipe.readyIntervalMs;
+  const deadline = now() + timeoutMs;
+  let ready = false;
+  let attempts = 0;
+  // Bounded poll (never a fixed sleep): probe, then wait one interval, until the
+  // deadline. The injected clock/delay make the timeout deterministic in tests.
+  while (now() <= deadline) {
+    attempts += 1;
+    // Fail closed: a probe that throws/rejects counts as "not ready yet" so the
+    // deadline path produces the clean boot-timeout stop instead of crashing.
+    // Bound each attempt by the remaining budget (raced against probeTimeout) so
+    // a slow/hung probe can't exceed the deadline or block forever — a per-attempt
+    // timeout is just "not ready yet", keeping boot-timeout deterministic.
+    let probeOk = false;
+    const timeout = probeTimeout(Math.max(0, deadline - now()));
+    try {
+      probeOk = await Promise.race([Promise.resolve(probe(recipe.readyUrl)), timeout]);
+    } catch {
+      probeOk = false;
+    } finally {
+      timeout.clear?.(); // cancel the pending per-attempt timer once the race is decided
+    }
+    if (probeOk) {
+      ready = true;
+      break;
+    }
+    if (now() + intervalMs > deadline) break; // would overshoot the deadline
+    await delay(intervalMs);
+  }
+
+  const bootResult = { pid: boot.pid ?? null, ready, attempts, readyUrl: recipe.readyUrl, timeoutMs, intervalMs };
+  if (!ready) {
+    record(`boot timeout: not ready after ${timeoutMs}ms (${attempts} probe attempt(s)) at ${recipe.readyUrl}`);
+    return stop(
+      `readiness probe timed out after ${timeoutMs}ms (${attempts} attempt(s) at ${recipe.readyUrl})`,
+      { kind: "boot-timeout", severity: MUST_FIX, message: `app never became ready within ${timeoutMs}ms` },
+      { worktreePath, depInstall, migrations, boot: bootResult },
+    );
+  }
+
+  record(`app ready after ${attempts} probe attempt(s) at ${recipe.readyUrl}`);
+  return {
+    ok: true,
+    stopped: false,
+    stopReason: null,
+    worktreePath,
+    created: wt.created,
+    reused: wt.reused,
+    depInstall,
+    migrations,
+    boot: bootResult,
+    ...base(),
+  };
+}

package/src/loop/ui-review-report.mjs

@@ -0,0 +1,289 @@
+/**
+ * Report for the ui_review route (Stage 4, terminal reporting stage).
+ *
+ * Pure decision layer. Maps the Stage-3 ranked findings into:
+ *   - a pending draft-review input (consumed by buildDraftReviewPayload — the
+ *     shared poster's contract: {path,line,body,side:RIGHT} inline comments, no
+ *     `event`), with anchorable findings inlined on their exact diff anchors and
+ *     non-anchorable findings retained in the review body,
+ *   - a severity->event policy (a confirmed user-facing server error maps to
+ *     REQUEST_CHANGES ONLY when the caller authorizes submit; otherwise the
+ *     review stays pending with the severity recorded — never auto-submit),
+ *   - a self-contained, CSP-safe HTML artifact string (ranked findings + inline
+ *     screenshot evidence), and
+ *   - a harness-aware hosting directive (Claude Code -> a publishable Artifacts
+ *     directive for the orchestrator; any other harness -> a GitHub-native
+ *     gist-publish directive the CLI executes, which yields a real per-run URL
+ *     or fails closed with a stated reason — never a fake link).
+ *
+ * All IO (reading the diagnose output + the screenshot bytes, writing the HTML,
+ * invoking the poster) lives in the thin CLI. This module reads only its inputs.
+ */
+
+import { isClaudeHarness } from "./run-context.mjs";
+import { sanitizeCopilotSummonTokens } from "../github/copilot-helpers.mjs";
+
+/** Findings past this cap are dropped from the artifact and the drop is logged. */
+export const ARTIFACT_MAX_FINDINGS = 100;
+
+/** A screenshot whose data URI exceeds this is omitted from the artifact (logged). */
+export const ARTIFACT_MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
+
+/** The drive kinds that count as a confirmed user-facing server error. Both are
+ * must-fix in the drive's classification: an error response the app returned and
+ * a server-log exception the request raised. */
+const SERVER_ERROR_KINDS = new Set(["error-response", "server-log-exception"]);
+
+function normalizeSha(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/** A confirmed user-facing server error: a must-fix error-response / server-log
+ * exception. This is the single-source predicate the severity policy keys off. */
+function isBlockingFinding(finding) {
+  return finding?.severity === "must-fix" && SERVER_ERROR_KINDS.has(finding?.kind);
+}
+
+/** Render a finding's reproduced exception as one line, falling back to its
+ * message when the drive captured no parseable exception. */
+function reproducedLine(finding) {
+  const type = finding?.exception?.type;
+  const message = finding?.exception?.message;
+  if (typeof type === "string" && type.length > 0) {
+    return message ? `${type}: ${message}` : type;
+  }
+  return typeof finding?.message === "string" && finding.message.length > 0
+    ? finding.message
+    : "Captured failure (no exception detail)";
+}
+
+/** A short, kind-specific fix direction. Deliberately generic — the goal is to
+ * point the author at the changed line, not to prescribe the patch. */
+function fixDirection(kind) {
+  switch (kind) {
+    case "error-response":
+      return "Fix the request path so it no longer returns an error response.";
+    case "server-log-exception":
+    case "page-error":
+      return "Guard the throwing code path; the exception above was raised here.";
+    case "request-failed":
+      return "The request from this change failed at the wire; verify the endpoint/URL.";
+    default:
+      return "Address the reproduced failure on this changed line.";
+  }
+}
+
+/** Inline-comment body for an anchorable finding: reproduced exception + fix direction. */
+export function formatInlineBody(finding) {
+  return `Reproduced in the running app: ${reproducedLine(finding)}\nFix direction: ${fixDirection(finding?.kind)}`;
+}
+
+/**
+ * Severity->event policy (pure). A confirmed user-facing server error maps to
+ * REQUEST_CHANGES ONLY when submit is authorized; otherwise the review stays
+ * pending (event null) with the severity recorded. Never auto-submits.
+ *
+ * @param {{findings?: object[], submitAuthorized?: boolean}} [input]
+ * @returns {{event: "REQUEST_CHANGES"|null, blocking: boolean, submitAuthorized: boolean, severity: string}}
+ */
+export function severityToEvent({ findings = [], submitAuthorized = false } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const blocking = list.some(isBlockingFinding);
+  const severity = blocking
+    ? "must-fix"
+    : (list.some((f) => f?.severity === "must-fix") ? "must-fix" : (list.length > 0 ? "note" : "none"));
+  return {
+    event: submitAuthorized && blocking ? "REQUEST_CHANGES" : null,
+    blocking,
+    submitAuthorized: Boolean(submitAuthorized),
+    severity,
+  };
+}
+
+/**
+ * Harness-aware hosting directive (pure). Claude Code -> a publishable Artifacts
+ * directive for the orchestrator to host (this module never calls an agent tool
+ * itself). Any other harness -> the portable GitHub-native default: publish the
+ * self-contained HTML as a secret GitHub Gist (a real per-run URL, zero repo
+ * pollution). This module decides the STRATEGY only; the CLI performs the gist
+ * publish IO and fails closed with a stated reason if it does not yield a URL.
+ * The self-contained HTML is produced regardless; only this link step differs.
+ *
+ * @param {{htmlPath: string, env?: Record<string,string|undefined>}} input
+ */
+export function decideHosting({ htmlPath, env = process.env } = {}) {
+  if (isClaudeHarness(env)) {
+    return { hosting: "claude-artifact", publishable: true, htmlPath: htmlPath ?? null };
+  }
+  return { hosting: "github-gist", publishable: true, htmlPath: htmlPath ?? null };
+}
+
+/** One review-body line describing where the screenshot artifact lives. Links a
+ * real hosted URL when one exists; otherwise states the harness-aware status so
+ * the review never blocks on hosting. */
+function artifactBodyLine({ hosting, hostedUrl }) {
+  if (typeof hostedUrl === "string" && hostedUrl.length > 0) {
+    // Only an ACTUALLY-published gist gets the source-rendered caveat: an explicit
+    // --hosted-url override leaves the strategy as github-gist but sets no gist, so
+    // a self-hosted (maybe live-rendered) URL falls through to the neutral line.
+    const rawUrl = hosting?.gist?.rawUrl;
+    if (rawUrl) {
+      // A gist renders HTML as source, not a live page; the raw file is the
+      // download/plain-text view — surface it so "open raw" is actually actionable.
+      return `Screenshot artifact (GitHub Gist — renders as source; open the raw file to view/download the HTML): ${hostedUrl} (raw: ${rawUrl})`;
+    }
+    return `Screenshot artifact: ${hostedUrl}`;
+  }
+  if (hosting?.hosting === "claude-artifact") {
+    return "Screenshot artifact prepared for Claude Artifacts hosting (published by the harness; see run output).";
+  }
+  const reason = hosting?.reason ? ` (${hosting.reason})` : "";
+  return `Screenshot artifact is unhosted this stage${reason}. Findings are included below.`;
+}
+
+/** A finding is inlineable ONLY with a complete anchor buildDraftReviewPayload
+ * will keep: a non-blank path and a line > 0 (exactly the payload's inline
+ * filter), side RIGHT. A finding flagged anchorable but carrying a
+ * malformed/incomplete anchor (blank path, line <= 0) falls back to the body
+ * (summaryFindings) instead of being dropped by the payload's inline filter. */
+function hasValidAnchor(finding) {
+  const a = finding?.anchor;
+  return Boolean(
+    finding?.anchorable &&
+    a &&
+    typeof a.path === "string" && a.path.trim().length > 0 &&
+    typeof a.line === "number" && a.line > 0 &&
+    a.side === "RIGHT"
+  );
+}
+
+/** Body line for a non-anchorable finding: it is kept, never dropped. */
+function nonAnchorableBodyMessage(finding) {
+  const reason = finding?.nonAnchorableReason ? ` — not inlined: ${finding.nonAnchorableReason}` : "";
+  return `${reproducedLine(finding)}${reason}`;
+}
+
+/**
+ * Map Stage-3 findings + hosting status into the merged-result input that the
+ * shared buildDraftReviewPayload consumes. Anchorable findings become inline
+ * comments on their exact {path,line,side:RIGHT} anchors; the artifact line and
+ * every non-anchorable finding are retained as summary (body) findings.
+ *
+ * @param {{findings?: object[], headSha?: string|null, hosting?: object, hostedUrl?: string}} input
+ */
+export function buildReviewInput({ findings = [], headSha = null, hosting = null, hostedUrl = null } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const anchorable = list.filter(hasValidAnchor);
+  const nonAnchorable = list.filter((f) => !hasValidAnchor(f));
+
+  // Untrusted target-app text (exception type/message, log lines, nonAnchorableReason)
+  // flows into these bodies. Sanitize copilot-summon tokens before they enter the
+  // payload buildDraftReviewPayload posts verbatim — every sibling posting path does.
+  const inlineComments = anchorable.map((f) => ({
+    path: f.anchor.path,
+    line: f.anchor.line,
+    message: sanitizeCopilotSummonTokens(formatInlineBody(f)),
+    severity: f.severity ?? "note",
+  }));
+
+  const summaryFindings = [
+    { message: sanitizeCopilotSummonTokens(artifactBodyLine({ hosting, hostedUrl })), severity: "note" },
+    ...nonAnchorable.map((f) => ({ message: sanitizeCopilotSummonTokens(nonAnchorableBodyMessage(f)), severity: f.severity ?? "note" })),
+  ];
+
+  const blocking = list.some(isBlockingFinding);
+  const verdict = list.length === 0 ? "APPROVE" : (blocking ? "REQUEST_CHANGES" : "COMMENT");
+
+  return {
+    headSha: normalizeSha(headSha),
+    verdict,
+    inlineComments,
+    summaryFindings,
+    totalFindings: list.length,
+    runsMerged: 0,
+  };
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/gu, (c) => (
+    { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]
+  ));
+}
+
+const ARTIFACT_STYLE = [
+  "body{font:14px/1.5 system-ui,sans-serif;margin:0;padding:24px;color:#1a1a1a;background:#fafafa}",
+  "h1{font-size:20px;margin:0 0 4px}",
+  ".meta{color:#666;margin-bottom:20px}",
+  ".finding{border:1px solid #ddd;border-radius:6px;padding:12px 16px;margin:0 0 12px;background:#fff}",
+  ".finding.blocking{border-left:4px solid #c0392b}",
+  ".finding.note{border-left:4px solid #999}",
+  ".sev{font-weight:600;text-transform:uppercase;font-size:11px;letter-spacing:.05em}",
+  ".anchor{color:#2c3e50;font-family:ui-monospace,monospace;font-size:12px}",
+  ".exc{font-family:ui-monospace,monospace;white-space:pre-wrap;margin:6px 0}",
+  ".reason{color:#c0392b;font-size:12px}",
+  "img{max-width:100%;border:1px solid #ddd;border-radius:4px;margin-top:12px}",
+].join("");
+
+const ARTIFACT_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'";
+
+/**
+ * Build the self-contained, CSP-safe HTML artifact (ranked findings + inline
+ * screenshot evidence). Fully inlined: no external scripts/styles/fonts/images.
+ * Bounded caps (findings past ARTIFACT_MAX_FINDINGS, an oversized screenshot)
+ * are applied here and returned in `caps` so the CLI can log them — never a
+ * silent truncation.
+ *
+ * @param {{findings?: object[], counts?: object, pr?: object, screenshot?: {path:string,dataUri:string}|null, generatedAt?: string}} input
+ * @returns {{html: string, caps: string[]}}
+ */
+export function buildArtifactHtml({ findings = [], counts = {}, pr = {}, screenshot = null, generatedAt } = {}) {
+  const caps = [];
+  const list = Array.isArray(findings) ? findings : [];
+
+  let shown = list;
+  if (list.length > ARTIFACT_MAX_FINDINGS) {
+    shown = list.slice(0, ARTIFACT_MAX_FINDINGS);
+    caps.push(`artifact: findings truncated to ${ARTIFACT_MAX_FINDINGS} of ${list.length} (${list.length - ARTIFACT_MAX_FINDINGS} not rendered)`);
+  }
+
+  let screenshotHtml = "";
+  if (screenshot && typeof screenshot.dataUri === "string") {
+    if (screenshot.dataUri.length > ARTIFACT_MAX_SCREENSHOT_BYTES) {
+      caps.push(`artifact: screenshot omitted (${screenshot.dataUri.length} bytes > ${ARTIFACT_MAX_SCREENSHOT_BYTES} cap): ${screenshot.path ?? "unknown"}`);
+    } else {
+      screenshotHtml = `<h2>Reproduced evidence</h2><img alt="reproduced state" src="${escapeHtml(screenshot.dataUri)}" />`;
+    }
+  }
+
+  const findingsHtml = shown.map((f) => {
+    const blocking = isBlockingFinding(f);
+    const cls = blocking ? "blocking" : "note";
+    const anchor = f?.anchor
+      ? `<div class="anchor">${escapeHtml(f.anchor.path)}:${escapeHtml(f.anchor.line)} (${escapeHtml(f.anchor.side)})</div>`
+      : `<div class="reason">not inlined: ${escapeHtml(f?.nonAnchorableReason ?? "no anchor")}</div>`;
+    return [
+      `<div class="finding ${cls}">`,
+      `<div class="sev">${escapeHtml(f?.severity ?? "note")} · ${escapeHtml(f?.kind ?? "finding")}</div>`,
+      `<div class="exc">${escapeHtml(reproducedLine(f))}</div>`,
+      anchor,
+      "</div>",
+    ].join("");
+  }).join("");
+
+  const total = Number.isFinite(counts?.total) ? counts.total : list.length;
+  const html = [
+    "<!doctype html>",
+    '<html lang="en"><head><meta charset="utf-8" />',
+    `<meta http-equiv="Content-Security-Policy" content="${ARTIFACT_CSP}" />`,
+    "<title>UI review findings</title>",
+    `<style>${ARTIFACT_STYLE}</style>`,
+    "</head><body>",
+    `<h1>UI review findings — PR #${escapeHtml(pr?.number ?? "?")}</h1>`,
+    `<div class="meta">head ${escapeHtml(pr?.headSha ?? "?")} · ${escapeHtml(total)} finding(s) · ${escapeHtml(counts?.anchorable ?? 0)} anchorable · generated ${escapeHtml(generatedAt ?? "")}</div>`,
+    findingsHtml,
+    screenshotHtml,
+    "</body></html>",
+  ].join("");
+
+  return { html, caps };
+}