@riddledc/riddle-proof 0.8.37 → 0.8.38

package/dist/cli.cjs

@@ -17377,6 +17377,210 @@ function extractRiddleProofProfileResult(input) {
   return void 0;
 }
 
+// src/pr-comment.ts
+var RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function stringValue3(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function numberValue2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function booleanValue2(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function artifactKind(name, url) {
+  const target = `${name} ${url}`.toLowerCase();
+  if (/\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(target)) return "image";
+  if (/\.(json|har|txt|md|html|log)(\?|#|$)/.test(target)) return "data";
+  return "artifact";
+}
+function artifactDisplayName(value, fallback) {
+  const raw = stringValue3(value);
+  if (raw) return raw;
+  return fallback;
+}
+function collectArtifacts(runResponse) {
+  const proofResult = asRecord(runResponse.proofResult);
+  const outputs = asArray(proofResult.outputs);
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, item] of outputs.entries()) {
+    const artifact = asRecord(item);
+    const url = stringValue3(artifact.url);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    const name = artifactDisplayName(artifact.name, `artifact-${index + 1}`);
+    artifacts.push({
+      name,
+      url,
+      kind: artifactKind(name, url),
+      size_bytes: numberValue2(artifact.size)
+    });
+  }
+  return artifacts;
+}
+function pageSummaries(result) {
+  const pages = [];
+  for (const page of asArray(result.pages)) {
+    const record = asRecord(page);
+    const route = stringValue3(record.route) || stringValue3(record.url) || "page";
+    const checks = asRecord(record.checks);
+    let passed = 0;
+    let failed = 0;
+    for (const value of Object.values(checks)) {
+      if (value === true) passed += 1;
+      if (value === false) failed += 1;
+    }
+    pages.push({ route, passed, failed });
+  }
+  return pages;
+}
+function summarizeExplicitChecks(value) {
+  let passed = 0;
+  let failed = 0;
+  const visit = (current, inChecks = false) => {
+    if (current === true && inChecks) {
+      passed += 1;
+      return;
+    }
+    if (current === false && inChecks) {
+      failed += 1;
+      return;
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item, inChecks);
+      return;
+    }
+    if (current && typeof current === "object") {
+      for (const [key, item] of Object.entries(current)) {
+        visit(item, inChecks || key === "checks");
+      }
+    }
+  };
+  visit(value);
+  return { passed, failed };
+}
+function selectPrimaryImage(artifacts) {
+  const images = artifacts.filter((artifact) => artifact.kind === "image");
+  return images.find((artifact) => /after|proof|screenshot/i.test(artifact.name)) || images[0];
+}
+function summarizeRiddleProofPrComment(input) {
+  const runResponse = asRecord(input.runResponse);
+  const result = asRecord(input.result);
+  const proofResult = asRecord(runResponse.proofResult);
+  const preview = asRecord(runResponse.preview);
+  const artifacts = collectArtifacts(runResponse);
+  const pages = pageSummaries(result);
+  const checkSource = { ...result };
+  delete checkSource.ok;
+  const nestedChecks = summarizeExplicitChecks(checkSource);
+  const ok = booleanValue2(result.ok) ?? booleanValue2(runResponse.ok) ?? null;
+  return {
+    ok,
+    status: stringValue3(proofResult.status),
+    job_id: stringValue3(proofResult.job_id),
+    duration_ms: numberValue2(proofResult.duration_ms),
+    proof_url: stringValue3(runResponse.proofUrl),
+    preview_id: stringValue3(preview.id),
+    preview_url: stringValue3(preview.preview_url) || stringValue3(preview.url),
+    preview_publish_recovered: booleanValue2(preview.publish_recovered),
+    preview_publish_error: stringValue3(preview.publish_error),
+    passed_checks: nestedChecks.passed,
+    failed_checks: nestedChecks.failed,
+    pages,
+    artifacts,
+    primary_image: selectPrimaryImage(artifacts)
+  };
+}
+function formatDuration(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "";
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${seconds}s`;
+}
+function markdownLink(label, url) {
+  return `[${label.replace(/\]/g, "\\]")}](${url})`;
+}
+function resultLabel(summary) {
+  if (summary.ok === true) return "passed";
+  if (summary.ok === false) return "failed";
+  return summary.status || "recorded";
+}
+function artifactRank(artifact) {
+  const name = artifact.name.toLowerCase();
+  if (name === "proof.json") return 0;
+  if (name === "result.json") return 1;
+  if (name.includes("proof") && name.endsWith(".json") && !name.includes("layout")) return 2;
+  if (name === "console.json") return 3;
+  if (artifact.kind === "data") return 10;
+  if (artifact.kind === "image") return 20;
+  return 30;
+}
+function buildRiddleProofPrCommentMarkdown(input) {
+  const summary = summarizeRiddleProofPrComment(input);
+  const title = input.title?.trim() || "Riddle Proof Evidence";
+  const lines = [
+    RIDDLE_PROOF_PR_COMMENT_MARKER,
+    `## ${title}`,
+    "",
+    `**Result:** ${resultLabel(summary)}`
+  ];
+  if (input.goal?.trim()) lines.push(`**Goal:** ${input.goal.trim()}`);
+  if (input.successCriteria?.trim()) lines.push(`**Success criteria:** ${input.successCriteria.trim()}`);
+  if (summary.status) lines.push(`**Riddle job status:** ${summary.status}`);
+  if (summary.job_id) lines.push(`**Riddle job:** \`${summary.job_id}\``);
+  if (summary.duration_ms) lines.push(`**Duration:** ${formatDuration(summary.duration_ms)}`);
+  if (summary.proof_url) lines.push(`**Proof URL:** ${markdownLink(summary.proof_url, summary.proof_url)}`);
+  if (summary.preview_id || summary.preview_url) {
+    const previewLabel = summary.preview_id ? `\`${summary.preview_id}\`` : "preview";
+    lines.push(`**Preview:** ${summary.preview_url ? markdownLink(previewLabel, summary.preview_url) : previewLabel}`);
+  }
+  if (summary.preview_publish_recovered) {
+    const detail = summary.preview_publish_error ? `: ${summary.preview_publish_error}` : "";
+    lines.push(`**Preview publish recovery:** recovered after publish error${detail}`);
+  }
+  lines.push(`**Checks:** ${summary.passed_checks} passed / ${summary.failed_checks} failed`);
+  lines.push("");
+  if (summary.primary_image) {
+    lines.push("### Screenshot");
+    lines.push(`![${summary.primary_image.name}](${summary.primary_image.url})`);
+    lines.push("");
+  }
+  if (summary.pages.length) {
+    lines.push("### Page Checks");
+    for (const page of summary.pages.slice(0, 12)) {
+      lines.push(`- \`${page.route}\`: ${page.passed} passed / ${page.failed} failed`);
+    }
+    if (summary.pages.length > 12) lines.push(`- ${summary.pages.length - 12} more page(s) omitted`);
+    lines.push("");
+  }
+  const linkedArtifacts = summary.artifacts.filter((artifact) => artifact.url !== summary.primary_image?.url).sort((left, right) => artifactRank(left) - artifactRank(right) || left.name.localeCompare(right.name)).slice(0, 20);
+  if (linkedArtifacts.length) {
+    lines.push("### Artifacts");
+    for (const artifact of linkedArtifacts) {
+      lines.push(`- ${markdownLink(artifact.name, artifact.url)}`);
+    }
+    if (summary.artifacts.length - (summary.primary_image ? 1 : 0) > linkedArtifacts.length) {
+      lines.push(`- ${summary.artifacts.length - (summary.primary_image ? 1 : 0) - linkedArtifacts.length} more artifact(s) omitted`);
+    }
+    lines.push("");
+  }
+  if (input.source?.trim()) {
+    lines.push(`_Source: ${input.source.trim()}_`);
+  } else {
+    lines.push("_Updated by `riddle-proof-loop pr-comment`._");
+  }
+  return `${lines.join("\n").trim()}
+`;
+}
+
 // src/cli.ts
 var RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB = 30;
 var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
@@ -17399,11 +17603,14 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "codexSandbox",
   "codexTimeoutMs",
   "command",
+  "commentMode",
   "continueWithStage",
   "createdAt",
   "decision",
   "defaultReviewer",
   "defaultShipMode",
+  "bodyFile",
+  "dryRun",
   "exclude",
   "format",
   "framework",
@@ -17431,20 +17638,25 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "pack",
   "packFile",
   "profile",
+  "proofDir",
+  "pr",
   "progressEveryMs",
   "quiet",
   "readinessPath",
   "readinessTimeout",
   "reasonsJson",
+  "repo",
   "requestJson",
   "requiredJson",
   "responseJson",
   "resultFormat",
+  "resultJson",
   "resultsDir",
   "riddleEngineModuleUrl",
   "riddleProofDir",
   "route",
   "runDir",
+  "runResponse",
   "runner",
   "scriptFile",
   "sourceKind",
@@ -17481,6 +17693,7 @@ function usage() {
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> [--base-url <base-url>] --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> [--base-url <base-url>] --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop regression-pack run [--pack oc-flow-regression|--pack-file <file>] [--local-core true|false; default true] [--hosted-riddle true|false; default false] [--format json|markdown|compact-json; default json] [--output <dir>|--output-dir <dir>]",
+    "  riddle-proof-loop pr-comment --proof-dir <dir>|--run-response <file> [--result-json <file>] --pr <number|url> [--repo owner/name] [--dry-run] [--body-file <file>] [--comment-mode update|append]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
     "  riddle-proof-loop profile-http-status-preflight --profile <file|json|-> --url <base-url> [--format json|summary]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label> [--framework spa|static] [--quiet]",
@@ -18289,6 +18502,81 @@ function riddlePreviewProgressLine(snapshot) {
   const messagePart = snapshot.message ? ` ${snapshot.message}` : "";
   return `[riddle-preview] ${snapshot.stage}${idPart}${statusPart}${attemptPart} elapsed=${formatPollDuration(snapshot.elapsed_ms)} label=${snapshot.label} framework=${snapshot.framework}${filePart}${totalPart}${archivePart}${previewPart}${recoveryPart}${messagePart}`;
 }
+function readJsonFileIfExists(filePath) {
+  if (!filePath || !(0, import_node_fs6.existsSync)(filePath)) return void 0;
+  return readJsonValue(filePath, filePath);
+}
+function defaultProofDirJsonPath(proofDir, filename) {
+  return proofDir ? import_node_path6.default.join(proofDir, filename) : void 0;
+}
+function prNumberFromValue(value) {
+  const text = value?.trim();
+  if (!text) return "";
+  const match = text.match(/\/pull\/(\d+)(?:\/|$)/) || text.match(/^#?(\d+)$/);
+  return match ? match[1] : text;
+}
+function ghJson(args, input) {
+  const result = (0, import_node_child_process5.spawnSync)("gh", args, {
+    input: typeof input === "undefined" ? void 0 : `${JSON.stringify(input)}
+`,
+    encoding: "utf-8",
+    timeout: 9e4
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new Error(`gh ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+  const stdout = (result.stdout || "").trim();
+  return stdout ? JSON.parse(stdout) : {};
+}
+function resolveGhRepoName(repoOption) {
+  if (repoOption?.trim()) return repoOption.trim();
+  const result = (0, import_node_child_process5.spawnSync)("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], {
+    encoding: "utf-8",
+    timeout: 3e4
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0 || !result.stdout.trim()) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new Error(`Could not resolve GitHub repository. Pass --repo owner/name.${detail ? ` gh said: ${detail}` : ""}`);
+  }
+  return result.stdout.trim();
+}
+function findManagedPrComment(repo, prNumber) {
+  const comments = ghJson(["api", `repos/${repo}/issues/${prNumber}/comments`, "--paginate"]);
+  return comments.find((comment) => typeof comment.body === "string" && comment.body.includes(RIDDLE_PROOF_PR_COMMENT_MARKER));
+}
+function upsertPrComment(input) {
+  const payload = { body: input.body };
+  if (input.mode !== "append") {
+    const existing = findManagedPrComment(input.repo, input.prNumber);
+    if (existing?.id) {
+      return {
+        action: "updated",
+        comment: ghJson([
+          "api",
+          `repos/${input.repo}/issues/comments/${existing.id}`,
+          "-X",
+          "PATCH",
+          "--input",
+          "-"
+        ], payload)
+      };
+    }
+  }
+  return {
+    action: "created",
+    comment: ghJson([
+      "api",
+      `repos/${input.repo}/issues/${input.prNumber}/comments`,
+      "-X",
+      "POST",
+      "--input",
+      "-"
+    ], payload)
+  };
+}
 function readJsonValue(value, label) {
   if (!value) throw new Error(`${label} is required.`);
   const raw = value === "-" ? readStdin() : (0, import_node_fs6.existsSync)(value) ? (0, import_node_fs6.readFileSync)(value, "utf-8") : value;
@@ -21921,6 +22209,47 @@ async function main() {
     process.exitCode = result.ok ? 0 : 1;
     return;
   }
+  if (command === "pr-comment") {
+    const proofDir = optionString(options, "proofDir") || optionString(options, "outputDir") || positional[1];
+    const runResponsePath = optionString(options, "runResponse") || defaultProofDirJsonPath(proofDir, "riddle-run-response.json");
+    const resultJsonPath = optionString(options, "resultJson") || defaultProofDirJsonPath(proofDir, "result.json");
+    const runResponse = readJsonFileIfExists(runResponsePath);
+    const result = readJsonFileIfExists(resultJsonPath);
+    if (!runResponse && !result) {
+      throw new Error("pr-comment requires --proof-dir with riddle-run-response.json/result.json or explicit --run-response/--result-json.");
+    }
+    const body = buildRiddleProofPrCommentMarkdown({
+      title: optionString(options, "title"),
+      goal: optionString(options, "summary"),
+      successCriteria: optionString(options, "successCriteria"),
+      runResponse,
+      result
+    });
+    const bodyFile = optionString(options, "bodyFile");
+    if (bodyFile) (0, import_node_fs6.writeFileSync)(bodyFile, body);
+    if (optionBoolean(options, "dryRun")) {
+      process.stdout.write(body);
+      return;
+    }
+    const prNumber = prNumberFromValue(optionString(options, "pr"));
+    if (!prNumber) throw new Error("pr-comment requires --pr <number|url> unless --dry-run is used.");
+    const commentMode = optionString(options, "commentMode") || "update";
+    if (!["update", "append"].includes(commentMode)) throw new Error("--comment-mode must be update or append.");
+    const repo = resolveGhRepoName(optionString(options, "repo"));
+    const resultPayload = upsertPrComment({ repo, prNumber, body, mode: commentMode });
+    const comment = resultPayload.comment;
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      action: resultPayload.action,
+      repo,
+      pr: prNumber,
+      comment_url: cliString(comment.html_url) || null,
+      summary: summarizeRiddleProofPrComment({ runResponse, result }),
+      body_file: bodyFile || null
+    }, null, 2)}
+`);
+    return;
+  }
   if (command === "profile-http-status-preflight") {
     const profile = normalizeProfileForCli(options);
     const result = await preflightRiddleProofProfileHttpStatusChecks(profile);

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import "./chunk-F4HKK2YH.js";
-import "./chunk-Z2LCVROU.js";
+import "./chunk-U44KBAPH.js";
 import "./chunk-DI2XNGEZ.js";
+import "./chunk-6KYXX4OE.js";
+import "./chunk-Z2LCVROU.js";
 import "./chunk-ZREWMTFA.js";
 import "./chunk-ZQWVXQKJ.js";
 import "./chunk-RDPG554T.js";

package/dist/index.cjs

@@ -3411,6 +3411,7 @@ __export(index_exports, {
   RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: () => RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES: () => RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION: () => RIDDLE_PROOF_PROFILE_VERSION,
+  RIDDLE_PROOF_PR_COMMENT_MARKER: () => RIDDLE_PROOF_PR_COMMENT_MARKER,
   RIDDLE_PROOF_RUN_CARD_VERSION: () => RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
@@ -3433,6 +3434,7 @@ __export(index_exports, {
   buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult: () => buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket: () => buildProofAssessmentCheckpointPacket,
+  buildRiddleProofPrCommentMarkdown: () => buildRiddleProofPrCommentMarkdown,
   buildRiddleProofProfileScript: () => buildRiddleProofProfileScript,
   buildStageCheckpointPacket: () => buildStageCheckpointPacket,
   buildVisualProofSession: () => buildVisualProofSession,
@@ -3507,6 +3509,7 @@ __export(index_exports, {
   slugifyRiddleProofProfileName: () => slugifyRiddleProofProfileName,
   statePathsForRunState: () => statePathsForRunState,
   summarizeCaptureArtifacts: () => summarizeCaptureArtifacts,
+  summarizeRiddleProofPrComment: () => summarizeRiddleProofPrComment,
   summarizeRiddleProofProfileResult: () => summarizeRiddleProofProfileResult,
   visualSessionFingerprint: () => visualSessionFingerprint,
   visualSessionFingerprintBasis: () => visualSessionFingerprintBasis
@@ -19566,6 +19569,210 @@ function createRiddleApiClient(config = {}) {
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
+
+// src/pr-comment.ts
+var RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function stringValue6(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function numberValue4(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function booleanValue2(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function artifactKind(name, url) {
+  const target = `${name} ${url}`.toLowerCase();
+  if (/\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(target)) return "image";
+  if (/\.(json|har|txt|md|html|log)(\?|#|$)/.test(target)) return "data";
+  return "artifact";
+}
+function artifactDisplayName(value, fallback) {
+  const raw = stringValue6(value);
+  if (raw) return raw;
+  return fallback;
+}
+function collectArtifacts(runResponse) {
+  const proofResult = asRecord(runResponse.proofResult);
+  const outputs = asArray(proofResult.outputs);
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, item] of outputs.entries()) {
+    const artifact = asRecord(item);
+    const url = stringValue6(artifact.url);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    const name = artifactDisplayName(artifact.name, `artifact-${index + 1}`);
+    artifacts.push({
+      name,
+      url,
+      kind: artifactKind(name, url),
+      size_bytes: numberValue4(artifact.size)
+    });
+  }
+  return artifacts;
+}
+function pageSummaries(result) {
+  const pages = [];
+  for (const page of asArray(result.pages)) {
+    const record = asRecord(page);
+    const route = stringValue6(record.route) || stringValue6(record.url) || "page";
+    const checks = asRecord(record.checks);
+    let passed = 0;
+    let failed = 0;
+    for (const value of Object.values(checks)) {
+      if (value === true) passed += 1;
+      if (value === false) failed += 1;
+    }
+    pages.push({ route, passed, failed });
+  }
+  return pages;
+}
+function summarizeExplicitChecks(value) {
+  let passed = 0;
+  let failed = 0;
+  const visit = (current, inChecks = false) => {
+    if (current === true && inChecks) {
+      passed += 1;
+      return;
+    }
+    if (current === false && inChecks) {
+      failed += 1;
+      return;
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item, inChecks);
+      return;
+    }
+    if (current && typeof current === "object") {
+      for (const [key, item] of Object.entries(current)) {
+        visit(item, inChecks || key === "checks");
+      }
+    }
+  };
+  visit(value);
+  return { passed, failed };
+}
+function selectPrimaryImage(artifacts) {
+  const images = artifacts.filter((artifact) => artifact.kind === "image");
+  return images.find((artifact) => /after|proof|screenshot/i.test(artifact.name)) || images[0];
+}
+function summarizeRiddleProofPrComment(input) {
+  const runResponse = asRecord(input.runResponse);
+  const result = asRecord(input.result);
+  const proofResult = asRecord(runResponse.proofResult);
+  const preview = asRecord(runResponse.preview);
+  const artifacts = collectArtifacts(runResponse);
+  const pages = pageSummaries(result);
+  const checkSource = { ...result };
+  delete checkSource.ok;
+  const nestedChecks = summarizeExplicitChecks(checkSource);
+  const ok = booleanValue2(result.ok) ?? booleanValue2(runResponse.ok) ?? null;
+  return {
+    ok,
+    status: stringValue6(proofResult.status),
+    job_id: stringValue6(proofResult.job_id),
+    duration_ms: numberValue4(proofResult.duration_ms),
+    proof_url: stringValue6(runResponse.proofUrl),
+    preview_id: stringValue6(preview.id),
+    preview_url: stringValue6(preview.preview_url) || stringValue6(preview.url),
+    preview_publish_recovered: booleanValue2(preview.publish_recovered),
+    preview_publish_error: stringValue6(preview.publish_error),
+    passed_checks: nestedChecks.passed,
+    failed_checks: nestedChecks.failed,
+    pages,
+    artifacts,
+    primary_image: selectPrimaryImage(artifacts)
+  };
+}
+function formatDuration(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "";
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${seconds}s`;
+}
+function markdownLink(label, url) {
+  return `[${label.replace(/\]/g, "\\]")}](${url})`;
+}
+function resultLabel(summary) {
+  if (summary.ok === true) return "passed";
+  if (summary.ok === false) return "failed";
+  return summary.status || "recorded";
+}
+function artifactRank(artifact) {
+  const name = artifact.name.toLowerCase();
+  if (name === "proof.json") return 0;
+  if (name === "result.json") return 1;
+  if (name.includes("proof") && name.endsWith(".json") && !name.includes("layout")) return 2;
+  if (name === "console.json") return 3;
+  if (artifact.kind === "data") return 10;
+  if (artifact.kind === "image") return 20;
+  return 30;
+}
+function buildRiddleProofPrCommentMarkdown(input) {
+  const summary = summarizeRiddleProofPrComment(input);
+  const title = input.title?.trim() || "Riddle Proof Evidence";
+  const lines = [
+    RIDDLE_PROOF_PR_COMMENT_MARKER,
+    `## ${title}`,
+    "",
+    `**Result:** ${resultLabel(summary)}`
+  ];
+  if (input.goal?.trim()) lines.push(`**Goal:** ${input.goal.trim()}`);
+  if (input.successCriteria?.trim()) lines.push(`**Success criteria:** ${input.successCriteria.trim()}`);
+  if (summary.status) lines.push(`**Riddle job status:** ${summary.status}`);
+  if (summary.job_id) lines.push(`**Riddle job:** \`${summary.job_id}\``);
+  if (summary.duration_ms) lines.push(`**Duration:** ${formatDuration(summary.duration_ms)}`);
+  if (summary.proof_url) lines.push(`**Proof URL:** ${markdownLink(summary.proof_url, summary.proof_url)}`);
+  if (summary.preview_id || summary.preview_url) {
+    const previewLabel = summary.preview_id ? `\`${summary.preview_id}\`` : "preview";
+    lines.push(`**Preview:** ${summary.preview_url ? markdownLink(previewLabel, summary.preview_url) : previewLabel}`);
+  }
+  if (summary.preview_publish_recovered) {
+    const detail = summary.preview_publish_error ? `: ${summary.preview_publish_error}` : "";
+    lines.push(`**Preview publish recovery:** recovered after publish error${detail}`);
+  }
+  lines.push(`**Checks:** ${summary.passed_checks} passed / ${summary.failed_checks} failed`);
+  lines.push("");
+  if (summary.primary_image) {
+    lines.push("### Screenshot");
+    lines.push(`![${summary.primary_image.name}](${summary.primary_image.url})`);
+    lines.push("");
+  }
+  if (summary.pages.length) {
+    lines.push("### Page Checks");
+    for (const page of summary.pages.slice(0, 12)) {
+      lines.push(`- \`${page.route}\`: ${page.passed} passed / ${page.failed} failed`);
+    }
+    if (summary.pages.length > 12) lines.push(`- ${summary.pages.length - 12} more page(s) omitted`);
+    lines.push("");
+  }
+  const linkedArtifacts = summary.artifacts.filter((artifact) => artifact.url !== summary.primary_image?.url).sort((left, right) => artifactRank(left) - artifactRank(right) || left.name.localeCompare(right.name)).slice(0, 20);
+  if (linkedArtifacts.length) {
+    lines.push("### Artifacts");
+    for (const artifact of linkedArtifacts) {
+      lines.push(`- ${markdownLink(artifact.name, artifact.url)}`);
+    }
+    if (summary.artifacts.length - (summary.primary_image ? 1 : 0) > linkedArtifacts.length) {
+      lines.push(`- ${summary.artifacts.length - (summary.primary_image ? 1 : 0) - linkedArtifacts.length} more artifact(s) omitted`);
+    }
+    lines.push("");
+  }
+  if (input.source?.trim()) {
+    lines.push(`_Source: ${input.source.trim()}_`);
+  } else {
+    lines.push("_Updated by `riddle-proof-loop pr-comment`._");
+  }
+  return `${lines.join("\n").trim()}
+`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BASIC_GAMEPLAY_ACTION_TYPES,
@@ -19590,6 +19797,7 @@ function createRiddleApiClient(config = {}) {
   RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION,
+  RIDDLE_PROOF_PR_COMMENT_MARKER,
   RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
@@ -19612,6 +19820,7 @@ function createRiddleApiClient(config = {}) {
   buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket,
+  buildRiddleProofPrCommentMarkdown,
   buildRiddleProofProfileScript,
   buildStageCheckpointPacket,
   buildVisualProofSession,
@@ -19686,6 +19895,7 @@ function createRiddleApiClient(config = {}) {
   slugifyRiddleProofProfileName,
   statePathsForRunState,
   summarizeCaptureArtifacts,
+  summarizeRiddleProofPrComment,
   summarizeRiddleProofProfileResult,
   visualSessionFingerprint,
   visualSessionFingerprintBasis

package/dist/index.d.cts

@@ -12,3 +12,4 @@ export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
 export { AssessBasicGameplayOptions, AttachBasicGameplayArtifactOptions, BASIC_GAMEPLAY_ACTION_TYPES, BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES, BasicGameplayActionResult, BasicGameplayActionType, BasicGameplayArtifactResolution, BasicGameplayAssessmentSummary, BasicGameplayBoundsOffender, BasicGameplayCanvasState, BasicGameplayCatchRecord, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMetric, BasicGameplayMobileEvidence, BasicGameplayProgressCheckType, BasicGameplayProgressionCheck, BasicGameplayProofArtifact, BasicGameplayResponsiveViewportEvidence, BasicGameplayRouteReference, BasicGameplaySnapshot, BasicGameplaySuiteFailure, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayProgressionCheck, assessBasicGameplayProgressionChecks, assessBasicGameplayRoute, attachBasicGameplayArtifactScreenshotHashes, augmentBasicGameplayAssessmentWithProgressionChecks, compactBasicGameplayText, createBasicGameplayCatchRecords, createBasicGameplayCatchSummary, extractBasicGameplayEvidence, resolveBasicGameplayProgressionCheckWithArtifactScreenshots, sanitizeBasicGameplayJsonString } from './basic-gameplay.cjs';
 export { NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_NETWORK_ABORT_ERROR_CODES, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, RiddleProofArtifactBodyAssertionInput, RiddleProofArtifactBodyAssertionResult, RiddleProofProfile, RiddleProofProfileArtifactRef, RiddleProofProfileBaselinePolicy, RiddleProofProfileBoundsOffender, RiddleProofProfileCheck, RiddleProofProfileCheckResult, RiddleProofProfileCheckType, RiddleProofProfileEvidence, RiddleProofProfileFailureAction, RiddleProofProfileHttpStatusBodyJsonAssertion, RiddleProofProfileHttpStatusBodyJsonAssertionResult, RiddleProofProfileHttpStatusPreflightCheckResult, RiddleProofProfileHttpStatusPreflightFetch, RiddleProofProfileHttpStatusPreflightFetchResponse, RiddleProofProfileHttpStatusPreflightOptions, RiddleProofProfileHttpStatusPreflightResult, RiddleProofProfileJsonValueType, RiddleProofProfileNetworkAbortErrorCode, RiddleProofProfileNetworkMock, RiddleProofProfileNetworkMockResponse, RiddleProofProfileResult, RiddleProofProfileReturnSummaryField, RiddleProofProfileRouteEvidence, RiddleProofProfileRouteInventoryRoute, RiddleProofProfileRunner, RiddleProofProfileSetupAction, RiddleProofProfileSetupActionType, RiddleProofProfileStatus, RiddleProofProfileTarget, RiddleProofProfileViewport, RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, collectRiddleProofProfileWarnings, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, deriveRiddleProofArtifactBodyAssertions, extractRiddleProofProfileResult, normalizeRiddleProofProfile, preflightRiddleProofProfileHttpStatusChecks, profileStatusExitCode, resolveRiddleProofProfileRouteUrl, resolveRiddleProofProfileTargetUrl, resolveRiddleProofProfileTimeoutSec, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult } from './profile.cjs';
 export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployProgressSnapshot, RiddlePreviewDeployResult, RiddlePreviewDeployStage, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';
+export { RIDDLE_PROOF_PR_COMMENT_MARKER, RiddleProofPrCommentArtifact, RiddleProofPrCommentArtifactKind, RiddleProofPrCommentInput, RiddleProofPrCommentPageSummary, RiddleProofPrCommentSummary, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment } from './pr-comment.cjs';