replume-cli 0.2.5 → 0.2.6

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "replume-cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "bin": {
     "replume": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsup src/cli.ts --format esm --target node20 --out-dir dist --shims",
+    "build": "tsup src/cli.ts --format esm --target node20 --out-dir dist --shims --env.REPLUME_TELEMETRY_DEFAULT ${REPLUME_TELEMETRY_DEFAULT:-on}",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "check:error-codes": "node scripts/check-error-codes.mjs",
     "check-context": "node scripts/check-context.mjs",
     "prepublishOnly": "npm run build && npm run typecheck && npm run check-context && npm test",
     "eval": "node eval/run.mjs"

package/templates/pr-check-publish.mjs

@@ -1,10 +1,18 @@
 // Copy beside the workflow as .github/replume-pr-check-publish.mjs on the trusted base branch.
 // The publisher reads the verify artifact; --check-policy reads committed policy from the PR base.
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-const marker = "<!-- replume-pr-check -->";
+// Before 0.2.6 every workflow shared this marker; such a comment is taken over, so an upgrade does not leave two.
+const legacyMarker = "<!-- replume-pr-check -->";
+const safeKey = (value) => String(value ?? "").replace(/[^A-Za-z0-9 ._/-]+/g, "-").trim().slice(0, 120);
+// One comment for each workflow and job. A matrix job sets REPLUME_CHECK_JOB to tell its legs apart.
+const checkKey = (env) => `${safeKey(env.GITHUB_WORKFLOW) || "workflow"} / ${safeKey(env.REPLUME_CHECK_JOB || env.GITHUB_JOB) || "job"}`;
+const markerFor = (env) => `<!-- replume-pr-check: ${checkKey(env)} -->`;
+const EARLIER_RUNS = 10;
+const runTag = /<!-- replume-run: sha=([0-9a-f]{7,40}) run=(\S+) attempt=(\S+) verdict=(PASS|FAIL|INCOMPLETE) -->/;
+const earlierLine = /^- `[0-9a-f]{7}` run \S+ attempt \S+: \*\*(?:PASS|FAIL|INCOMPLETE)\*\*$/;
 const text = (value) => String(value ?? "").replace(/[\r\n\t]+/g, " ").replace(/[<>`]/g, "").slice(0, 350);
 const items = (entries) => entries.length ? entries.map((entry) => `- ${entry}`).join("\n") : "- None recorded.";
 const contractPath = ".replume/contract.yaml";
@@ -46,11 +54,28 @@ function result(reportPath, exitPath, policyPath = join(dirname(reportPath), "po
   try { if (existsSync(exitPath)) exit = readFileSync(exitPath, "utf8").trim(); } catch { /* incomplete below */ }
   const expected = report?.verdict === "pass" ? "0" : report?.verdict === "fail" ? "1" : report?.verdict === "incomplete" ? "2" : "";
   const verdict = expected && exit === expected ? report.verdict.toUpperCase() : "INCOMPLETE";
+  // never green on nothing: a PASS has to name a check that ran
+  if (verdict === "PASS" && !(Array.isArray(report.done) && report.done.length)) return { report, verdict: "INCOMPLETE", reason: "Verification reported PASS but names no check that ran." };
   return { report: report && typeof report === "object" ? report : null, verdict,
     reason: verdict === "INCOMPLETE" && expected !== exit ? "Verification did not produce a usable, matching result." : "" };
 }
 
-export function commentBody(reportPath, exitPath, policyPath) {
+/** The earlier runs kept in a comment, plus the run that comment showed, as one list. */
+function earlierRuns(previous) {
+  const block = /<!-- replume-earlier -->\n([\s\S]*?)\n<!-- \/replume-earlier -->/.exec(previous ?? "")?.[1] ?? "";
+  return block.split("\n").filter((line) => earlierLine.test(line));
+}
+const runLine = (sha, run, attempt, verdict) => `- \`${String(sha).slice(0, 7)}\` run ${run} attempt ${attempt}: **${verdict}**`;
+function foldedRuns(lines) {
+  if (!lines.length) return [];
+  return [`<details><summary>Earlier runs (${lines.length})</summary>`, "", "<!-- replume-earlier -->", ...lines, "<!-- /replume-earlier -->", "", "</details>", ""];
+}
+/** Puts the earlier runs, newest first, into a body that has none yet. */
+function withEarlier(body, lines) {
+  return lines.length ? `${body}\n\n${foldedRuns(lines.slice(0, EARLIER_RUNS)).join("\n")}`.trimEnd() : body;
+}
+
+export function commentBody(reportPath, exitPath, policyPath, env = {}) {
   const { report, verdict, reason } = result(reportPath, exitPath, policyPath);
   const done = Array.isArray(report?.done) ? report.done : [];
   const failed = Array.isArray(report?.failed) ? report.failed : [];
@@ -68,7 +93,7 @@ export function commentBody(reportPath, exitPath, policyPath) {
     "CI did not observe agent steps; this result covers the commit diff and checks run here.",
   ];
   if (reason) unchecked.unshift(reason);
-  return [marker, `**Replume: ${verdict}${reason ? ` — ${text(reason)}` : ""}**`, "",
+  return [markerFor(env), `<!-- replume-run: sha=${/^[0-9a-f]{7,40}$/i.test(env.HEAD_SHA ?? "") ? env.HEAD_SHA.toLowerCase() : "0000000"} run=${safeKey(env.GITHUB_RUN_ID).replace(/\s/g, "-") || "-"} attempt=${safeKey(env.GITHUB_RUN_ATTEMPT).replace(/\s/g, "-") || "1"} verdict=${verdict} -->`, `**Replume: ${verdict}${reason ? ` — ${text(reason)}` : ""}**`, "",
     "## Verified", items(verified), "",
     ...(failures.length ? ["## Failed", items(failures), ""] : []),
     "## Changed beyond the task", items(beyond), "",
@@ -84,10 +109,17 @@ async function api(path, method, token, body) {
     headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "content-type": "application/json" },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }),
   });
-  if (!response.ok) throw new Error(`GitHub ${method} ${path} returned HTTP ${response.status}`);
+  if (!response.ok) throw Object.assign(new Error(`GitHub ${method} ${path} returned HTTP ${response.status}`), { status: response.status });
   return response.json();
 }
 
+// A fork's token and a Dependabot token are read-only: GitHub answers 403, or 404 for what the token may not see.
+const readOnlyError = (error) => error?.status === 403 || error?.status === 404;
+function toRunPage(env, body) {
+  if (!env.GITHUB_STEP_SUMMARY) return;
+  try { appendFileSync(env.GITHUB_STEP_SUMMARY, `${body}\n`); } catch { /* the page is an extra; the job's exit is the result */ }
+}
+
 export async function publish(env = process.env) {
   const repo = env.GITHUB_REPOSITORY, pr = Number(env.PR_NUMBER), sha = env.HEAD_SHA, token = env.GITHUB_TOKEN;
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo ?? "") || !Number.isSafeInteger(pr) || pr < 1 || !/^[a-fA-F0-9]{40}$/.test(sha ?? "") || !token)
@@ -95,23 +127,71 @@ export async function publish(env = process.env) {
   const reportPath = env.REPLUME_REPORT || "replume-ci/report.json";
   const exitPath = env.REPLUME_VERIFY_EXIT_FILE || "replume-ci/exit.txt";
   const policyPath = env.REPLUME_POLICY_NOTE || join(dirname(reportPath), "policy.txt");
-  const body = commentBody(reportPath, exitPath, policyPath);
+  const fresh = commentBody(reportPath, exitPath, policyPath, env);
   const verdict = result(reportPath, exitPath, policyPath).verdict;
-  let existing = null;
-  for (let page = 1; page <= 20; page++) {
-    const comments = await api(`/repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`, "GET", token);
-    if (!Array.isArray(comments)) throw new Error("GitHub comments response was not a list");
-    existing = comments.find((entry) => entry?.body?.startsWith(marker) && entry?.user?.login === "github-actions[bot]") ?? null;
-    if (existing || comments.length < 100) break;
+  // the run's result stays on its own page in every case, with or without a comment
+  toRunPage(env, fresh);
+  if (env.HEAD_REPO && env.HEAD_REPO !== repo) {
+    process.stdout.write(`Replume: ${verdict}; a fork's PR: no comment and no check from this token. The result is on the run page.\n`);
+    return;
   }
-  if (existing) await api(`/repos/${repo}/issues/comments/${existing.id}`, "PATCH", token, { body });
-  else await api(`/repos/${repo}/issues/${pr}/comments`, "POST", token, { body });
-  const conclusion = verdict === "PASS" ? "success" : verdict === "FAIL" ? "failure" : "neutral";
-  await api(`/repos/${repo}/check-runs`, "POST", token, {
-    name: "Replume / task", head_sha: sha, status: "completed", conclusion,
-    output: { title: `Replume: ${verdict}`, summary: body.slice(0, 60000) },
-  });
-  process.stdout.write(`Replume: ${verdict}; ${existing ? "updated" : "posted"} one PR comment; check ${conclusion}.\n`);
+  const marker = markerFor(env);
+  const ours = (entry, prefix) => entry?.body?.split("\n")[0] === prefix && entry?.user?.login === "github-actions[bot]";
+  const notes = [];
+  let action = "no comment";
+  // a check is not green because a comment could not be written, or the other way round: each has its own outcome
+  try {
+    let existing = null, legacy = null;
+    for (let page = 1; page <= 20; page++) {
+      const comments = await api(`/repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`, "GET", token);
+      if (!Array.isArray(comments)) throw new Error("GitHub comments response was not a list");
+      existing = comments.find((entry) => ours(entry, marker)) ?? null;
+      legacy ??= comments.find((entry) => ours(entry, legacyMarker)) ?? null;
+      if (existing || comments.length < 100) break;
+    }
+    const current = existing ?? legacy;
+    const prior = runTag.exec(current?.body ?? "");
+    const earlier = earlierRuns(current?.body);
+    const thisRun = runTag.exec(fresh);
+    const sameRun = prior && thisRun && prior[2] === thisRun[2] && prior[3] === thisRun[3];
+    // a rerun of an older commit does not take the place of the newest commit's result: it goes under Earlier runs
+    let newest = null;
+    try { newest = (await api(`/repos/${repo}/pulls/${pr}`, "GET", token))?.head?.sha ?? null; } catch { /* unknown: treat this run as the newest */ }
+    const stale = newest && newest.toLowerCase() !== sha.toLowerCase() && current;
+    const body = stale
+      ? current.body.replace(/\n\n<details><summary>Earlier runs[\s\S]*$/, "").concat(`\n\n${foldedRuns([runLine(sha, thisRun[2], thisRun[3], verdict), ...earlier].slice(0, EARLIER_RUNS)).join("\n")}`).trimEnd()
+      : withEarlier(fresh, sameRun || !prior ? earlier : [runLine(prior[1], prior[2], prior[3], prior[4]), ...earlier]);
+    if (current) await api(`/repos/${repo}/issues/comments/${current.id}`, "PATCH", token, { body });
+    else await api(`/repos/${repo}/issues/${pr}/comments`, "POST", token, { body });
+    action = current ? "updated one PR comment" : "posted one PR comment";
+  } catch (error) {
+    if (!readOnlyError(error)) throw error;
+    notes.push("the token cannot write comments here (a fork or a read-only token), so the result is on the run page");
+  }
+  // neutral counts as passing for a required check, so INCOMPLETE is not neutral: nothing that was not checked turns a PR green
+  const conclusion = verdict === "PASS" ? "success" : verdict === "FAIL" ? "failure" : "action_required";
+  const runPage = env.GITHUB_RUN_ID ? `${(env.GITHUB_SERVER_URL || "https://github.com").replace(/\/$/, "")}/${repo}/actions/runs/${env.GITHUB_RUN_ID}` : null;
+  let check = conclusion;
+  try {
+    await api(`/repos/${repo}/check-runs`, "POST", token, {
+      name: "Replume / task", head_sha: sha, status: "completed", conclusion, ...(runPage ? { details_url: runPage } : {}),
+      output: { title: `Replume: ${verdict}`, summary: fresh.slice(0, 60000) },
+    });
+  } catch (error) {
+    if (!readOnlyError(error)) throw error;
+    check = "not written";
+    notes.push("the token cannot write checks here");
+  }
+  process.stdout.write(`Replume: ${verdict}; ${action}; check ${check}.${notes.length ? ` ${notes.join("; ")}.` : ""}\n`);
+}
+
+/** The verify job's last step: the run page gets the result, and only PASS exits 0. Needs no token, so it works on a fork. */
+export function requirePass(dir, env = process.env) {
+  const reportPath = join(dir, "report.json"), exitPath = join(dir, "exit.txt"), policyPath = join(dir, "policy.txt");
+  toRunPage(env, commentBody(reportPath, exitPath, policyPath, env));
+  const { verdict } = result(reportPath, exitPath, policyPath);
+  process.stdout.write(`Replume: ${verdict}\n`);
+  return verdict === "PASS" ? 0 : verdict === "FAIL" ? 1 : 2;
 }
 
 if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
@@ -121,5 +201,7 @@ if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
       writeFileSync(process.argv[4], reason ? `${reason}\n` : "");
       if (reason) { process.stdout.write(`Replume: INCOMPLETE — ${reason}\n`); process.exitCode = 2; }
     } catch (error) { process.stderr.write(`replume-pr-check: ${error.message}\n`); process.exitCode = 2; }
+  } else if (process.argv[2] === "--require") {
+    process.exitCode = requirePass(process.argv[3]);
   } else publish().catch((error) => { process.stderr.write(`replume-pr-check: ${error.message}\n`); process.exitCode = 1; });
 }

package/templates/pr-check.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           node-version: '20'
       - run: mkdir -p "$RUNNER_TEMP/replume-ci"
-      - run: npm install -g replume-cli@0.2.4
+      - run: npm install -g replume-cli@0.2.5
       - name: Install project dependencies
         if: ${{ hashFiles('package-lock.json') != '' }}
         run: npm ci
@@ -56,12 +56,16 @@ jobs:
         if: always()
         shell: bash
         run: |
+          if grep -qs -- '--require' "$RUNNER_TEMP/replume-base-publisher.mjs"; then
+            node "$RUNNER_TEMP/replume-base-publisher.mjs" --require "$RUNNER_TEMP/replume-ci"
+            exit $?
+          fi
           if [ ! -f "$RUNNER_TEMP/replume-ci/exit.txt" ]; then exit 2; fi
           exit "$(cat "$RUNNER_TEMP/replume-ci/exit.txt")"
 
   publish:
     name: Replume / PR result
-    if: ${{ always() && github.event.pull_request.head.repo.full_name == github.repository }}
+    if: ${{ !cancelled() && github.event.pull_request.head.repo.full_name == github.repository }}
     needs: verify
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -88,6 +92,8 @@ jobs:
           GITHUB_REPOSITORY: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          REPLUME_CHECK_JOB: verify
           REPLUME_REPORT: replume-ci/report.json
           REPLUME_VERIFY_EXIT_FILE: replume-ci/exit.txt
           REPLUME_POLICY_NOTE: replume-ci/policy.txt