@riddledc/riddle-proof 0.8.36 → 0.8.38

package/README.md

@@ -968,6 +968,27 @@ way to a ready PR after proof and CI; `leave_draft: true` is only an explicit
 debug or user-request escape hatch. The notification adapter is where a host
 updates Discord, OpenClaw, GitHub, or another integration.
 
+## PR Proof Comments
+
+Use `pr-comment` when a project already has a PR and a Riddle Proof output
+directory, but is not using the full ship loop. It reads
+`riddle-run-response.json` and `result.json`, builds a managed GitHub comment,
+embeds the primary hosted screenshot when available, links structured artifacts,
+summarizes check counts, and updates the existing Riddle Proof comment on
+reruns.
+
+```sh
+riddle-proof-loop pr-comment \
+  --proof-dir test-results/riddle-proof-docs \
+  --pr 228 \
+  --repo davisdiehl/riddle-site
+```
+
+Use `--dry-run` to print the exact Markdown without touching GitHub, or
+`--body-file proof-comment.md` to save the generated body for another tool. The
+markdown builder is also exported from `@riddledc/riddle-proof/pr-comment` for
+host integrations that want to post comments themselves.
+
 ## Runtime Scratch Space
 
 The packaged proof-run setup uses isolated git worktrees for before and after

package/dist/advanced/index.d.cts

@@ -1,5 +1,5 @@
 export { b as runner } from '../runner-4LJ5z0D-.cjs';
 export { l as engineHarness } from '../engine-harness-LBfqbFSe.cjs';
 export { p as proofRunCore } from '../proof-run-core-B1GeqkR8.cjs';
-export { p as proofRunEngine } from '../proof-run-engine-DYUu2mqY.cjs';
+export { p as proofRunEngine } from '../proof-run-engine-4dM37pEx.cjs';
 import '../types.cjs';

package/dist/advanced/index.d.ts

@@ -1,5 +1,5 @@
 export { b as runner } from '../runner-BdQpOkZD.js';
 export { l as engineHarness } from '../engine-harness-CMACHP6A.js';
 export { p as proofRunCore } from '../proof-run-core-B1GeqkR8.js';
-export { p as proofRunEngine } from '../proof-run-engine-BmNYuOJ7.js';
+export { p as proofRunEngine } from '../proof-run-engine-BqaeqAze.js';
 import '../types.js';

package/dist/advanced/proof-run-engine.d.cts

@@ -1,2 +1,2 @@
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-DYUu2mqY.cjs';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-4dM37pEx.cjs';
 import '../proof-run-core-B1GeqkR8.cjs';

package/dist/advanced/proof-run-engine.d.ts

@@ -1,2 +1,2 @@
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-BmNYuOJ7.js';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-BqaeqAze.js';
 import '../proof-run-core-B1GeqkR8.js';

package/dist/chunk-6KYXX4OE.js

@@ -0,0 +1,209 @@
+// 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 stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function booleanValue(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 = stringValue(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 = stringValue(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: numberValue(artifact.size)
+    });
+  }
+  return artifacts;
+}
+function pageSummaries(result) {
+  const pages = [];
+  for (const page of asArray(result.pages)) {
+    const record = asRecord(page);
+    const route = stringValue(record.route) || stringValue(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 = booleanValue(result.ok) ?? booleanValue(runResponse.ok) ?? null;
+  return {
+    ok,
+    status: stringValue(proofResult.status),
+    job_id: stringValue(proofResult.job_id),
+    duration_ms: numberValue(proofResult.duration_ms),
+    proof_url: stringValue(runResponse.proofUrl),
+    preview_id: stringValue(preview.id),
+    preview_url: stringValue(preview.preview_url) || stringValue(preview.url),
+    preview_publish_recovered: booleanValue(preview.publish_recovered),
+    preview_publish_error: stringValue(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()}
+`;
+}
+
+export {
+  RIDDLE_PROOF_PR_COMMENT_MARKER,
+  summarizeRiddleProofPrComment,
+  buildRiddleProofPrCommentMarkdown
+};

package/dist/{chunk-TWTEUS7R.js → chunk-DI2XNGEZ.js}

@@ -81,10 +81,68 @@ function previewDeployResultFromRecord(input) {
 function canRecoverPreviewPublish(error) {
   return error instanceof RiddleApiError && PREVIEW_PUBLISH_RECOVERY_STATUSES.has(error.status);
 }
+function summarizePreviewDirectory(directory) {
+  const stack = [directory];
+  let fileCount = 0;
+  let totalBytes = 0;
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const stat = statSync(fullPath);
+      fileCount += 1;
+      totalBytes += stat.size;
+    }
+  }
+  return { file_count: fileCount, total_bytes: totalBytes };
+}
+function previewProgressEmitter(config, base) {
+  return async (snapshot) => {
+    if (!config.onPreviewProgress) return;
+    await config.onPreviewProgress({
+      label: base.label,
+      framework: base.framework,
+      directory: base.directory,
+      elapsed_ms: Math.max(0, Date.now() - base.startedAt),
+      warnings: base.warnings?.length ? base.warnings : void 0,
+      ...snapshot
+    });
+  };
+}
 async function waitForPublishedPreview(config, input) {
+  await input.emitProgress?.({
+    stage: "publish_recovering",
+    id: input.id,
+    file_count: input.localSummary?.file_count,
+    total_bytes: input.localSummary?.total_bytes,
+    publish_error: input.publishError.message,
+    message: `publish returned ${input.publishError.status}; polling preview status`
+  });
   for (let attempt = 1; attempt <= PREVIEW_PUBLISH_RECOVERY_ATTEMPTS; attempt += 1) {
     const status = await riddleRequestJson(config, `/v1/preview/${input.id}`);
+    await input.emitProgress?.({
+      stage: "checking_status",
+      id: input.id,
+      attempt,
+      attempts: PREVIEW_PUBLISH_RECOVERY_ATTEMPTS,
+      status: typeof status.status === "string" ? status.status : null,
+      preview_url: typeof status.preview_url === "string" ? status.preview_url : void 0,
+      file_count: typeof status.file_count === "number" ? status.file_count : input.localSummary?.file_count,
+      total_bytes: typeof status.total_bytes === "number" ? status.total_bytes : input.localSummary?.total_bytes
+    });
     if (String(status.status || "") === "ready" && String(status.preview_url || "").trim()) {
+      await input.emitProgress?.({
+        stage: "ready",
+        id: input.id,
+        preview_url: String(status.preview_url),
+        file_count: typeof status.file_count === "number" ? status.file_count : input.localSummary?.file_count,
+        total_bytes: typeof status.total_bytes === "number" ? status.total_bytes : input.localSummary?.total_bytes
+      });
       return previewDeployResultFromRecord({
         record: status,
         id: input.id,
@@ -106,7 +164,17 @@ async function deployRiddlePreview(config, directory, label, framework = "static
   if (!directory?.trim()) throw new Error("directory is required");
   if (!label?.trim()) throw new Error("label is required");
   if (framework !== "spa" && framework !== "static") throw new Error("framework must be spa or static");
+  const startedAt = Date.now();
   const warnings = collectRiddlePreviewDeployWarnings(directory, framework);
+  const emitProgress = previewProgressEmitter(config, { label, framework, directory, startedAt, warnings });
+  await emitProgress({ stage: "validating", message: "checking preview input directory" });
+  const localSummary = summarizePreviewDirectory(directory);
+  await emitProgress({
+    stage: "creating",
+    file_count: localSummary.file_count,
+    total_bytes: localSummary.total_bytes,
+    message: "creating preview upload target"
+  });
   const created = await riddleRequestJson(config, "/v1/preview", {
     method: "POST",
     body: JSON.stringify({ framework, label })
@@ -114,10 +182,42 @@ async function deployRiddlePreview(config, directory, label, framework = "static
   const id = String(created.id || "");
   const uploadUrl = String(created.upload_url || "");
   if (!id || !uploadUrl) throw new Error("Riddle preview create response was missing id or upload_url.");
+  await emitProgress({
+    stage: "created",
+    id,
+    file_count: localSummary.file_count,
+    total_bytes: localSummary.total_bytes,
+    message: "preview upload target created"
+  });
   const scratch = mkdtempSync(path.join(tmpdir(), "riddle-preview-upload-"));
   const tarball = path.join(scratch, `${id}.tar.gz`);
+  let tarballBytes = 0;
   try {
+    await emitProgress({
+      stage: "archiving",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      message: "creating preview archive"
+    });
     execFileSync("tar", ["czf", tarball, "-C", directory, "."], { stdio: "pipe" });
+    tarballBytes = statSync(tarball).size;
+    await emitProgress({
+      stage: "archived",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "preview archive created"
+    });
+    await emitProgress({
+      stage: "uploading",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "uploading preview archive"
+    });
     const upload = await fetchFor(config)(uploadUrl, {
       method: "PUT",
       headers: { "Content-Type": "application/gzip" },
@@ -126,14 +226,37 @@ async function deployRiddlePreview(config, directory, label, framework = "static
     if (!upload.ok) {
       throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
     }
+    await emitProgress({
+      stage: "uploaded",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "preview archive uploaded"
+    });
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }
   const expiresAt = typeof created.expires_at === "string" ? created.expires_at : void 0;
   try {
+    await emitProgress({
+      stage: "publishing",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes || void 0,
+      message: "publishing preview"
+    });
     const published = await riddleRequestJson(config, `/v1/preview/${id}/publish`, {
       method: "POST"
     });
+    await emitProgress({
+      stage: "ready",
+      id,
+      preview_url: String(published.preview_url || ""),
+      file_count: typeof published.file_count === "number" ? published.file_count : localSummary.file_count,
+      total_bytes: typeof published.total_bytes === "number" ? published.total_bytes : localSummary.total_bytes
+    });
     return previewDeployResultFromRecord({ record: published, id, label, framework, expiresAt, warnings });
   } catch (error) {
     if (!canRecoverPreviewPublish(error)) throw error;
@@ -143,7 +266,9 @@ async function deployRiddlePreview(config, directory, label, framework = "static
       framework,
       expiresAt,
       publishError: error,
-      warnings
+      warnings,
+      localSummary,
+      emitProgress
     });
   }
 }