clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/scripts/release-note-required.mjs

@@ -101,10 +101,46 @@
 // A deletion that gives no reason still refuses, and names the deleting commit as where the reason goes.
 // The move a pre-release makes — `.changeset/<name>.md` deleted and `.changeset/pre/<name>.md` added in
 // one commit — is not a withdrawal: the note still reaches a reader, and a version commit is that shape.
+// ── A LATER COMMIT MAY ANSWER A BARE `none` FOR ONE NAMED COMMIT ───────────────────────────────────────
+//
+// A commit carried `Release-note: none` with no reason and was merged into an integration branch before
+// anyone read it, and a second branch was already built on that merge. The only fix this check offered was
+// the commit's own message, so the answer was a rewrite of a shared branch. A later commit may therefore
+// answer for it, in its own message:
+//
+//     Release-note-for: <sha> none — <why a reader would see no difference>
+//
+// Held tight, because a loose one excuses by accident:
+//   - one line names one commit, by its full sha or a prefix of at least 7 characters, resolved against
+//     THIS range's commits only. A prefix that matches none of them, or several, is refused;
+//   - the named commit must be an ANCESTOR of the answering one (git ancestry, never timestamps), and a
+//     commit cannot answer for itself;
+//   - the reason is read by NO_NOTE itself, so the two forms cannot drift. Empty, or a dash, is refused;
+//   - one commit takes one answer: two lines naming the same commit are both refused, even when they agree;
+//   - an answer naming a commit that owes none (it ships no code, carries a note, or gives its own reason)
+//     is refused as stale. An answer ignored in silence reads as though it did something.
+// Every answer taken is printed with the sha that gave it, and every refused answer fails the check and
+// names the commit that carries it. The answering commit is read like any other: one that ships no code,
+// such as an empty commit, owes nothing of its own.
+//
+// ── …AND MAY ANSWER A LINE THAT PROMISED A NOTE, BY NAMING THE NOTE ─────────────────────────────────────
+//
+// Five commits on one design said `Release-note: to follow`, because the note's sentence was the owner's
+// to write, and a second and third branch were built on them before the sentence existed. A sentence in a
+// `Release-note:` line is refused, rightly: it reaches no reader. The only fix was again a rewrite of shared
+// branches. So a later commit may answer such a commit by NAMING the note that answers for it:
+//
+//     Release-note-for: <sha> .changeset/<name>.md
+//
+// under every rule above (one line, one earlier commit on its own history, one answer each), and one more:
+// the range must add that note, exactly as a `Release-note:` line naming a note is read. It answers a
+// commit whose own line is a sentence or a bare `none`. A commit that says nothing is answered by any note
+// in the range already, so naming one for it is refused as stale.
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -163,6 +199,52 @@ export const NEVER_A_NOTE = [/(^|\/)CHANGELOG\.md$/, /(^|\/)package(-lock)?\.jso
 const NOTE_LINE = /^\s*Release-note:[ \t]*(?<value>.*?)[ \t]*$/gim;
 /** A note named in a `Release-note:` line: `.changeset/<name>.md`, or the bare `<name>.md`. */
 const NAMED_NOTE = /^(?:\.changeset\/)?(?<name>[\w.-]+\.md)$/;
+/** `Release-note-for: <sha> none — <reason>`: a later commit answering a bare `none` (see the header). */
+const ANSWER_LINE = /^[ \t]*Release-note-for:[ \t]*(?<rest>.*?)[ \t]*$/gim;
+const ANSWER_HEAD = /^(?<sha>[0-9a-f]{7,40})(?<tail>(?:[ \t].*)?)$/i;
+
+/**
+ * PURE. Every `Release-note-for:` line in the range, judged. `isAncestor(a, b)` says whether commit `a` is
+ * an ancestor of commit `b`; without one, range order stands in for it (the range is read oldest first).
+ * @returns {{answers: Map<string, {by:string, subject:string, reason:string}>,
+ *   refused: Array<{sha:string, subject:string, text:string, problem:string}>}}
+ */
+export function readAnswers(commits = [], isAncestor = null) {
+  const refused = [];
+  const claims = new Map();
+  commits.forEach((c, at) => {
+    for (const m of String(c.message ?? "").matchAll(ANSWER_LINE)) {
+      const text = m[0].trim();
+      const bad = (problem) => refused.push({ sha: c.sha, subject: c.subject, text, problem });
+      const head = ANSWER_HEAD.exec(m.groups.rest);
+      if (!head) { bad("names no commit: the form is `Release-note-for: <sha> none — <reason>` or `Release-note-for: <sha> .changeset/<name>.md`"); continue; }
+      const note = NAMED_NOTE.exec(head.groups.tail.trim())?.groups.name ?? null;
+      const none = note ? null : NO_NOTE.exec(`Release-note:${head.groups.tail}`);
+      if (!note && !none) { bad("does not say `none` or name a note straight after one sha: one line answers one commit"); continue; }
+      if (!note && !none.groups?.reason) { bad("gives no reason, and the reason is the whole point of the line"); continue; }
+      const prefix = head.groups.sha.toLowerCase();
+      const hits = commits.filter((k) => String(k.sha).toLowerCase().startsWith(prefix));
+      if (!hits.length) { bad(`names ${prefix}, which is not a commit in this range`); continue; }
+      if (hits.length > 1) { bad(`names ${prefix}, which matches ${hits.length} commits in this range`); continue; }
+      const target = hits[0];
+      const later = target.sha !== c.sha
+        && (isAncestor ? isAncestor(target.sha, c.sha) : commits.indexOf(target) < at);
+      if (!later) { bad(`names ${prefix}, which is not an earlier commit on this commit's own history`); continue; }
+      if (!claims.has(target.sha)) claims.set(target.sha, []);
+      claims.get(target.sha).push({ by: c.sha, subject: c.subject, text, ...(note ? { note } : { reason: none.groups.reason }) });
+    }
+  });
+  const answers = new Map();
+  for (const [sha, list] of claims) {
+    if (list.length > 1) {
+      for (const a of list) refused.push({ sha: a.by, subject: a.subject, text: a.text,
+        problem: `is one of ${list.length} answers naming ${sha.slice(0, 7)}; one commit takes one answer` });
+      continue;
+    }
+    answers.set(sha, list[0]);
+  }
+  return { answers, refused };
+}
 
 const isNotePath = (p) => p.startsWith(".changeset/") && p.endsWith(".md") && !p.endsWith("README.md");
 const shipped = (paths, files) => paths.filter((p) => !NEVER_A_NOTE.some((re) => re.test(p)) && shipsCode(p, files));
@@ -181,12 +263,15 @@ const shipped = (paths, files) => paths.filter((p) => !NEVER_A_NOTE.some((re) =>
  *   non-merge, oldest first; `added` and `deleted` are the paths the commit adds and removes, when the caller read them
  * @param {string[]} o.files  the package's own `files` list
  * @param {string[]|null} [o.atHead]  every path the head carries under `.changeset/`, when the caller read it
+ * @param {((a:string, b:string) => boolean)|null} [o.isAncestor]  git ancestry for `Release-note-for:` answers; range order without it
  * @returns {{visible:string[], notes:string[], declined:Array<{sha:string, subject:string, reason:string}>,
  *   withdrawals:Array<{sha:string, subject:string, note:string, by:string, reason:string}>,
+ *   answered:Array<{sha:string, subject:string, by:string, reason:string}>,
+ *   refusedAnswers:Array<{sha:string, subject:string, text:string, problem:string}>,
  *   owed:Array<{sha:string, subject:string, why:"no-note"|"prose"|"bare-none"|"names-a-missing-note"|"note-withdrawn-unsaid",
  *   paths?:string[], text?:string, by?:string}>}}
  */
-export function commitVerdicts({ commits = [], files = [], atHead = null } = {}) {
+export function commitVerdicts({ commits = [], files = [], atHead = null, isAncestor = null } = {}) {
   // `added` and `atHead` are what the command reads from git; a caller that passes neither keeps the older
   // reading of every changed path, which is what a pure table of paths means.
   // MATCHED ON THE NAME, NOT THE PATH, BECAUSE A PRE-RELEASE MOVES A NOTE IT CONSUMES.
@@ -234,7 +319,9 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
   });
   // AND A NAME THE HEAD STILL CARRIES WAS NEVER WITHDRAWN AT ALL: the release assembles what the head has.
   if (presentNames) for (const name of [...withdrawn.keys()]) if (presentNames.has(name)) withdrawn.delete(name);
-  const declined = [], owed = [], withdrawals = [];
+  const declined = [], owed = [], withdrawals = [], answered = [];
+  const { answers, refused: refusedAnswers } = readAnswers(commits, isAncestor);
+  const used = new Set();
   for (const [i, c] of commits.entries()) {
     const ships = shipped(c.paths, files);
     if (!ships.length) continue;                              // nothing a reader could see in this commit
@@ -243,11 +330,26 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
     const named = values.map((v) => NAMED_NOTE.exec(v)?.groups.name).filter(Boolean);
     const prose = values.filter((v) => !/^none\b/i.test(v) && !NAMED_NOTE.test(v));
     const at = { sha: c.sha, subject: c.subject };
-    if (prose.length && !addsNote) { owed.push({ ...at, why: "prose", text: prose[0] }); continue; }
+    // A LATER COMMIT'S ANSWER NAMING A NOTE: taken for a sentence line or a bare `none`, when the range adds it.
+    const byNote = (answer) => {
+      used.add(c.sha);
+      if (!noteNames.has(answer.note)) { owed.push({ ...at, why: "names-a-missing-note", text: answer.note, by: answer.by }); return; }
+      answered.push({ ...at, by: answer.by, note: answer.note, said: prose[0] ?? "none" });
+    };
+    if (prose.length && !addsNote) {
+      const answer = answers.get(c.sha);
+      if (answer?.note) byNote(answer);
+      else owed.push({ ...at, why: "prose", text: prose[0] });
+      continue;
+    }
     const none = NO_NOTE.exec(String(c.message ?? ""));
     if (none) {
       const reason = none.groups?.reason;
-      if (reason) declined.push({ ...at, reason }); else owed.push({ ...at, why: "bare-none" });
+      const answer = reason ? null : answers.get(c.sha);
+      if (reason) declined.push({ ...at, reason });
+      else if (answer?.note) byNote(answer);
+      else if (answer) { answered.push({ ...at, by: answer.by, reason: answer.reason }); used.add(c.sha); }
+      else owed.push({ ...at, why: "bare-none" });
       continue;
     }
     if (addsNote) continue;                                   // it carries its own note
@@ -268,7 +370,18 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
     if (notes.length) continue;                               // a note in the range answers for it
     owed.push({ ...at, why: "no-note", paths: ships });
   }
-  return { visible, notes, declined, withdrawals, owed };
+  // AN ANSWER THAT ANSWERED NOTHING IS REFUSED, NOT IGNORED (see the header).
+  const owing = new Set(owed.map((o) => o.sha));
+  for (const [sha, a] of answers) {
+    if (used.has(sha)) continue;
+    refusedAnswers.push({ sha: a.by, subject: a.subject, text: a.text,
+      problem: owing.has(sha)
+        ? (a.note
+          ? `names ${sha.slice(0, 7)}, whose own line this answer does not reach: a note answers only a sentence or a bare \`none\` in the named commit`
+          : `names ${sha.slice(0, 7)}, which owes a note this line cannot give: an answer covers only a bare \`none\``)
+        : `names ${sha.slice(0, 7)}, which owes no answer: it ships no code, carries a note, or gives its own reason` });
+  }
+  return { visible, notes, declined, withdrawals, owed, answered, refusedAnswers };
 }
 
 const argAfter = (flag) => {
@@ -333,7 +446,9 @@ function main() {
       + "history is never read.");
     return;
   }
-  const { visible, notes, declined, withdrawals, owed } = commitVerdicts({ commits, files, atHead });
+  // ANCESTRY FROM GIT, NEVER TIMESTAMPS: an answer must come from a commit the named one is an ancestor of.
+  const isAncestor = (a, b) => { try { git("merge-base", "--is-ancestor", a, b); return true; } catch { return false; } };
+  const { visible, notes, declined, withdrawals, owed, answered, refusedAnswers } = commitVerdicts({ commits, files, atHead, isAncestor });
   console.log(`release-note-required: ${changed.length} changed file(s) against ${base}`
     + `${head === "HEAD" ? "" : ` (head ${head})`}; `
     + `${visible.length} ship as code; ${notes.length} release note(s) in the range; ${commits.length} commit(s) read`
@@ -352,7 +467,20 @@ function main() {
   for (const w of withdrawals) {
     console.log(`  ${w.sha.slice(0, 7)} answered with ${w.note}, which ${w.by.slice(0, 7)} withdrew: ${w.reason}`);
   }
-  if (!owed.length) return;
+  for (const a of answered) {
+    console.log(a.note
+      ? `  ${a.sha.slice(0, 7)} said ${a.said === "none" ? "a bare `none`" : `"${a.said}"`}, which ${a.by.slice(0, 7)} answers with ${a.note}`
+      : `  ${a.sha.slice(0, 7)} said a bare \`none\`, which ${a.by.slice(0, 7)} answers: ${a.reason}`);
+  }
+  if (!owed.length && !refusedAnswers.length) return;
+  if (refusedAnswers.length) {
+    console.error(`\n${refusedAnswers.length} Release-note-for answer(s) refused:\n`);
+    for (const r of refusedAnswers) {
+      console.error(`  ${r.sha.slice(0, 7)} ${r.subject}`);
+      console.error(`      "${r.text.slice(0, 120)}" ${r.problem}.`);
+    }
+  }
+  if (!owed.length) process.exit(1);
 
   console.error(`\n${owed.length} commit(s) that ship as code owe a release note:\n`);
   for (const o of owed) {
@@ -373,7 +501,9 @@ function main() {
         + "\n      release too, say that in THAT commit — `Release-note: none — <why>` — which is the newest of"
         + "\n      the two and the one that can still be amended.");
     } else {
-      console.error(`      names ${o.text} as its note, and this range adds no note by that name.`);
+      console.error(o.by
+        ? `      is answered by ${o.by.slice(0, 7)} with ${o.text}, and this range adds no note by that name.`
+        : `      names ${o.text} as its note, and this range adds no note by that name.`);
     }
   }
   console.error("\nSomebody installing Clearotron reads the releases page to decide whether to upgrade. Add a"
@@ -384,4 +514,4 @@ function main() {
   process.exit(1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main();
+if (isEntrypoint(import.meta.url)) main();

package/scripts/release-rehearsal-version.mjs

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// release-rehearsal-version.mjs — what a rehearsal publishes: the version a beta cut would publish now.
+//
+//   node scripts/release-rehearsal-version.mjs      # stdout: publish_dry_run=true|false; the rest on stderr
+//
+// WHY A REHEARSAL DOES NOT PUBLISH MAIN'S VERSION. Main's version is the one already out on almost every
+// day: a cut stamps it and publishes it, and it stays on main until the next cut. npm checks the registry
+// even on `npm publish --dry-run`, so a rehearsal of main's own version answered "You cannot publish over
+// the previously published versions" and went red (measured 2026-09-23 on 0.3.3), reading as a broken
+// pipeline when nothing was wrong. It passed only between a cut and its publish, when nobody rehearses.
+//
+// So a rehearsal stamps the tree the way a `cut: beta` dispatch does, with release-version.mjs itself, and
+// dry-runs that version: the one a cut made now would publish. The stamp lives in the job's own checkout
+// and is never committed.
+//
+// WITH NO NOTE PENDING THERE IS NOTHING TO CUT, and a cut would refuse for exactly that reason. The
+// version is then main's, which is out, so the publish dry run is skipped and says why, while every check
+// before it still runs on those bytes. A note that is pending and still cannot be cut is a real failure,
+// and the rehearsal fails with the version script's own refusal.
+//
+// Exit 0: stamped, or nothing to cut. Exit 1: the version script refused. Exit 2: could not look.
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { countNotes } from "./release-pre-gate.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** PURE. What a rehearsal does with the notes it finds pending at the top of `.changeset/`. */
+export function rehearsalPlan({ pendingNotes }) {
+  if (!Number.isInteger(pendingNotes) || pendingNotes < 0) return { action: "could-not-look" };
+  return pendingNotes > 0 ? { action: "stamp-next-beta" } : { action: "nothing-to-cut" };
+}
+
+export function main(root = ROOT) {
+  let pendingNotes;
+  try { pendingNotes = countNotes(join(root, ".changeset")); }
+  catch (e) { console.error(`release-rehearsal-version: could not read .changeset/: ${e.message}. Could not look.`); return 2; }
+  const plan = rehearsalPlan({ pendingNotes });
+  if (plan.action === "could-not-look") { console.error("release-rehearsal-version: could not count the pending notes. Could not look."); return 2; }
+  if (plan.action === "nothing-to-cut") {
+    console.error("release-rehearsal-version: no release note is pending, so there is nothing to cut and main's version is the one already out.");
+    console.log("publish_dry_run=false");
+    return 0;
+  }
+  console.error(`release-rehearsal-version: ${pendingNotes} note(s) pending; stamping the version a \`cut: beta\` would publish.`);
+  // The version script's own output goes to stderr, so stdout carries the one line the workflow keeps.
+  const r = spawnSync(process.execPath, [join(root, "scripts", "release-version.mjs"), "--cut=beta"], { cwd: root, stdio: ["ignore", 2, 2] });
+  if (r.status !== 0) {
+    console.error(`release-rehearsal-version: the version script refused (exit ${r.status ?? r.signal}), so a beta cut made now would refuse too.`);
+    return 1;
+  }
+  console.log("publish_dry_run=true");
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = main();

package/scripts/release-sbom.mjs

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// release-sbom.mjs — the parts list attached to every release, written from package-lock.json.
+//
+//   node scripts/release-sbom.mjs [--out <file>]      # CycloneDX 1.5 JSON; stdout when --out is absent
+//
+// WHY NOT `npm sbom`. It refuses this tree: `ESBOMPROBLEMS: invalid: uuid@11.1.1 … required by
+// exceljs@4.4.0`, on a clean `npm ci` as well, and `npm ls` flags the same edge. That is npm's reading of
+// the `uuid` override on the bundled `exceljs`, and an exact-version override is flagged the same way
+// (measured 2026-09-23 on npm 10.9.8). The reference tool, `@cyclonedx/cyclonedx-npm`, would add a
+// dependency that runs inside a release job. The lock already names every package, its version, its
+// integrity and its licence, which is what a parts list is.
+//
+// WHAT IS LISTED. Every package the lock installs that is not dev-only: the runtime dependencies and
+// everything they pull in, and the bundled ones this package carries inside its tarball. A consumer's
+// npm resolves the unbundled ones again at install time, so the list is what this release was built and
+// tested with, which is what an SBOM of a library can honestly say. Workspace links are this package's
+// own files, not parts, and are left out; a vendored package is listed by its path in this tree.
+//
+// THE SAME LOCK GIVES THE SAME BYTES. No timestamp and no serial number: both are optional in the spec,
+// and either would make two runs over one lock differ for no reason a reader can use.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** `pkg:npm/<name>@<version>`, with a scope's `@` encoded as the purl spec asks. */
+export const purlOf = (name, version) => `pkg:npm/${name.startsWith("@") ? `%40${name.slice(1)}` : name}@${version}`;
+
+/** An npm integrity string (`sha512-<base64>`) as CycloneDX hashes, hex-encoded. */
+export function hashesOf(integrity) {
+  const out = [];
+  for (const part of String(integrity ?? "").split(/\s+/).filter(Boolean)) {
+    const m = /^(sha512|sha384|sha256|sha1)-(.+)$/.exec(part);
+    if (!m) continue;
+    const alg = { sha512: "SHA-512", sha384: "SHA-384", sha256: "SHA-256", sha1: "SHA-1" }[m[1]];
+    out.push({ alg, content: Buffer.from(m[2], "base64").toString("hex") });
+  }
+  return out;
+}
+
+/**
+ * The CycloneDX document for a parsed lockfile and the root manifest. PURE.
+ * @param {{ lock: object, manifest: object }} input
+ */
+export function sbomFor({ lock, manifest }) {
+  const byRef = new Map();
+  const workspaces = new Set((manifest.workspaces ?? []).map((w) => w.replace(/\/+$/, "")));
+  for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+    if (!path.startsWith("node_modules/") && !path.includes("/node_modules/")) continue;   // the root and link targets
+    if (entry.dev) continue;                                                                 // dev-only tools
+    // A LINK TO A WORKSPACE is this package's own code. A link to anything else is code this package
+    // carries in its own tree, such as a vendored replacement, and it is listed by where it lives, with no
+    // npm purl: that would name the registry's package of the same name, which it is not.
+    if (entry.link) {
+      const target = lock.packages?.[entry.resolved] ?? {};
+      if (workspaces.has(entry.resolved) || !target.version || target.dev) continue;
+      const name = path.slice(path.lastIndexOf("node_modules/") + "node_modules/".length);
+      const ref = `file:${entry.resolved}`;
+      const vendored = { type: "library", "bom-ref": ref, name, version: target.version,
+        properties: [{ name: "clearotron:vendored-path", value: entry.resolved }] };
+      if (typeof target.license === "string" && target.license) vendored.licenses = [{ expression: target.license }];
+      byRef.set(ref, vendored);
+      continue;
+    }
+    const name = entry.name ?? path.slice(path.lastIndexOf("node_modules/") + "node_modules/".length);
+    if (!entry.version) continue;
+    const ref = purlOf(name, entry.version);
+    if (byRef.has(ref)) continue;
+    const component = { type: "library", "bom-ref": ref, name, version: entry.version, purl: ref };
+    const hashes = hashesOf(entry.integrity);
+    if (hashes.length) component.hashes = hashes;
+    if (typeof entry.license === "string" && entry.license) component.licenses = [{ expression: entry.license }];
+    byRef.set(ref, component);
+  }
+  const components = [...byRef.values()].sort((a, b) => a["bom-ref"].localeCompare(b["bom-ref"]));
+  const root = { type: "library", "bom-ref": purlOf(manifest.name, manifest.version), name: manifest.name, version: manifest.version,
+    purl: purlOf(manifest.name, manifest.version) };
+  if (manifest.license) root.licenses = [{ expression: manifest.license }];
+  return { bomFormat: "CycloneDX", specVersion: "1.5", version: 1, metadata: { component: root }, components };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf("--out");
+  const out = i === -1 ? null : argv[i + 1];
+  if (i !== -1 && !out) { console.error("release-sbom: --out needs a file."); return 2; }
+  let lock, manifest;
+  try {
+    lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8"));
+    manifest = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+  } catch (e) { console.error(`release-sbom: could not read the lock or the manifest: ${e.message}. Could not look.`); return 2; }
+  const doc = sbomFor({ lock, manifest });
+  if (!doc.components.length) { console.error("release-sbom: the lock lists no runtime package, so there is no parts list to write. Refusing an empty one."); return 1; }
+  const text = JSON.stringify(doc, null, 2) + "\n";
+  if (out) { writeFileSync(out, text); console.log(`release-sbom: ${doc.components.length} part(s) of ${manifest.name}@${manifest.version} written to ${out}.`); }
+  else process.stdout.write(text);
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = main();

package/scripts/release-visible-check.mjs

@@ -7,9 +7,11 @@
 //        [--timeout 900] [--interval 15] [--registry https://registry.npmjs.org] [--name clearotron]
 //
 // Exit 0: the registry serves <v>, the <dist-tag> names it, and the tarball it serves is byte for byte
-// the one at <file> — the bytes this run published. Exit 1: not within the bound, or the registry serves
-// different bytes; the caller creates no release entry. Exit 2: could not look — bad arguments, or the
-// local tarball cannot be read.
+// the one at <file> — the bytes this run published. Exit 1: not served within the bound, which is PENDING:
+// npm accepts a publish before it serves it. Exit 3: the registry serves DIFFERENT BYTES for <v>, which is
+// never pending and must go red at once, so it has a code of its own; it used to share 1, and a caller
+// that waits on 1 then waited six hours on a wrong tarball. Exit 2: could not look — bad arguments, or the
+// local tarball cannot be read. In every case but 0 the caller creates no release entry.
 //
 // ── WHY THIS RUNS BEFORE THE RELEASE ENTRY ─────────────────────────────────────────────────────────
 //
@@ -89,7 +91,7 @@ async function main() {
       console.error(`\nrelease-visible-check: after ${waited}s an unauthenticated client still cannot get ${name}@${version} `
         + `under \`${tag}\`. The publish was accepted and is not yet served, so no release entry is created: `
         + "the page would name a version nobody can install. The tag is already written, so the pipeline "
-        + "knows this version is published; re-run this job to create the entry once the registry serves it.");
+        + "knows this version is published; the scheduled entry job creates the entry once the registry serves it.");
       process.exit(1);
     }
     await sleep(intervalSec * 1000);
@@ -108,7 +110,7 @@ async function main() {
     console.error(`release-visible-check: the registry serves DIFFERENT BYTES for ${name}@${version}.\n`
       + `  published by this run: ${local}\n  served:                ${served}\n  recorded integrity:    ${seen.integrity ?? "none"}\n`
       + "No release entry is created for a version whose install is not the build this run verified.");
-    process.exit(1);
+    process.exit(3);
   }
   console.log(`release-visible-check: a stranger can install ${name}@${version} under \`${tag}\`, `
     + `and the tarball served is the one this run published (${served.slice(0, 22)}…).`);

package/scripts/render-check.mjs

@@ -288,9 +288,12 @@ window.addEventListener('message',function(e){var d=e.data;
 // Every wait below is a real wait for a named condition, and each one RECORDS which way it ended. A
 // deadline that fires is a fact about the page, not a silent substitute for the condition.
 function after(ms,cb){setTimeout(cb,ms);}
+// QUIET NEEDS SOMETHING TO GO QUIET. Timed from the shell's own start, 400ms with no post passed on a
+// starved runner before the frame had posted once (0 height posts, content 0), and the read found the
+// frame's default height. Every passing run has at least one post; none by the cap is named for itself.
 function whenQuiet(ms,cap,cb){var t0=Date.now();(function w(){
-  if(Date.now()-lastHeightAt>=ms)return cb('quiet');
-  if(Date.now()-t0>=cap)return cb('still-posting');
+  if(st.heightMsgs>0&&Date.now()-lastHeightAt>=ms)return cb('quiet');
+  if(Date.now()-t0>=cap)return cb(st.heightMsgs?'still-posting':'no-height-post');
   after(25,w);})();}
 function whenLaidOut(cb){var done=false,how='';
   var go=function(w){if(done)return;done=true;how=w;cb(w);};

package/scripts/report-offline-render-check.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// report-offline-render-check.mjs — opening a report contacts no one, measured in a real browser.
+//   node scripts/report-offline-render-check.mjs [--keep]
+//
+// A report used to fetch its typefaces from two font services, so opening one told them the reader's
+// address and that a report had been opened. It now carries its fonts inside itself. This opens every
+// report the demo publishes, and every pool index beside them, and records EVERY request each page makes:
+//   • from disk, as a report opened from an email or a download is;
+//   • served over HTTP with the portal's own report policy, as the portal frames it.
+// A request to any other machine fails the check. So does a report whose embedded faces did not load, or
+// a policy violation while it was drawn.
+//
+// WHAT THE REQUESTS ARE READ FROM. Chrome's own record of what the page asked for (Network.requestWillBeSent
+// on the page's session), not what reached a server: the network is blocked, so a request that was made
+// fails where it would have left, and it is still recorded. Chrome's background traffic is not the page's
+// and is not on this session.
+//
+// THE CONTROLS, because a blind instrument reads exactly like a clean page. Before any real page is
+// judged, one report is opened with a font service's stylesheet put back in its head, and the check must
+// see that request; and one with its embedded faces taken out, and the check must see no face loaded. If
+// either control passes, nothing measured after it means anything, and the check stops with exit 2.
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { extname, join, dirname, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { reapOnExit } from "../shared/reap-on-exit.mjs";
+import { browserRun } from "../shared/browser-temp-root.mjs";
+import { reportCsp } from "../driver/portal-static.mjs";
+import { TEXT_FACE, CODE_FACE, REPORT_FONT_STYLE } from "../shared/brand-fonts.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const keep = process.argv.includes("--keep");
+const TYPES = { ".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8", ".js": "text/javascript", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png" };
+
+// ── THE PAGES ────────────────────────────────────────────────────────────────────────────────────────
+const pool = mkdtempSync(join(tmpdir(), "offline-check-pool-"));
+const published = spawnSync(process.execPath, [join(ROOT, "bin", "example.mjs"), "--once", "--pool", pool], { encoding: "utf8" });
+if (published.status !== 0) { console.error(`the demo publisher failed:\n${published.stderr || published.stdout}`); process.exit(2); }
+const pages = [];
+const walk = (d) => { for (const n of readdirSync(d)) { const p = join(d, n); if (statSync(p).isDirectory()) walk(p); else if (n.endsWith(".html")) pages.push(p); } };
+walk(pool);
+const reports = pages.filter((p) => p.endsWith("/report.html"));
+if (reports.length !== 4) { console.error(`the demo published ${reports.length} reports, not one per product (4) — nothing to measure`); process.exit(2); }
+
+// The two controls, written beside a real report so its relative paths still resolve.
+const sample = readFileSync(reports[0], "utf8");
+if (!sample.includes(REPORT_FONT_STYLE)) { console.error("the sample report does not carry the embedded faces, so the controls cannot be built"); process.exit(2); }
+const leak = join(dirname(reports[0]), "control-leak.html");
+writeFileSync(leak, sample.replace("</title>", '</title><link href="https://api.fontshare.com/v2/css?f[]=satoshi@400&display=swap" rel="stylesheet">'));
+const bare = join(dirname(reports[0]), "control-no-faces.html");
+writeFileSync(bare, sample.replace(REPORT_FONT_STYLE, ""));
+
+// ── THE SERVER: the pool as the portal would serve a report, with the portal's report policy ─────────
+const server = createServer((req, res) => {
+  const file = join(pool, decodeURIComponent(new URL(req.url, "http://x").pathname));
+  if (!file.startsWith(pool) || !existsSync(file) || !statSync(file).isFile()) { res.writeHead(404); return res.end(); }
+  const headers = { "content-type": TYPES[extname(file)] ?? "application/octet-stream" };
+  if (file.endsWith(".html")) headers["content-security-policy"] = reportCsp();
+  res.writeHead(200, headers);
+  res.end(readFileSync(file));
+});
+await new Promise((r) => server.listen(0, "127.0.0.1", r));
+const origin = `http://127.0.0.1:${server.address().port}`;
+
+// ── THE BROWSER ──────────────────────────────────────────────────────────────────────────────────────
+const { root: browserRoot, profile, env: chromeEnv, keep: keepRoot } = browserRun("report-offline-check-");
+if (keep) keepRoot();
+const chrome = spawn("google-chrome", [
+  "--headless=new", "--disable-gpu", "--no-sandbox", "--hide-scrollbars",
+  // Nothing leaves the machine. A request the page makes still appears in the record below and fails
+  // where it would have left; that is how a leak is caught without one being made.
+  "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1",
+  `--user-data-dir=${profile}`, "--window-size=1280,900", "--remote-debugging-port=0", "about:blank",
+], { stdio: ["ignore", "ignore", "pipe"], detached: true, env: chromeEnv });
+reapOnExit(chrome);
+const wsUrl = await new Promise((resolve, reject) => {
+  let devtools = "";
+  const t = setTimeout(() => reject(new Error(`chrome reported no devtools endpoint in 60s:\n${devtools || "(nothing)"}`)), 60000);
+  chrome.stderr.on("data", (c) => { devtools += c; const m = devtools.match(/ws:\/\/[^\s]+/); if (m) { clearTimeout(t); resolve(m[0]); } });
+});
+const ws = new WebSocket(wsUrl);
+let id = 0;
+const pending = new Map();
+let requested = [];
+ws.addEventListener("message", (e) => {
+  const m = JSON.parse(e.data);
+  if (m.method === "Network.requestWillBeSent") requested.push(m.params.request.url);
+  if (m.id && pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id); }
+});
+await new Promise((r) => ws.addEventListener("open", r));
+const send = (method, params = {}, sessionId) => new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, method, params, ...(sessionId ? { sessionId } : {}) })); });
+const { result: targets } = await send("Target.getTargets");
+const target = targets.targetInfos.find((t) => t.type === "page");
+const sessionId = (await send("Target.attachToTarget", { targetId: target.targetId, flatten: true })).result.sessionId;
+const cmd = (method, params) => send(method, params, sessionId);
+const value = async (expr) => (await cmd("Runtime.evaluate", { expression: expr, awaitPromise: true, returnByValue: true })).result?.result?.value ?? null;
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+await cmd("Page.enable");
+await cmd("Network.enable");
+// Before any script of the page's own, so a violation raised while the head is parsed is not missed.
+await cmd("Page.addScriptToEvaluateOnNewDocument", { source: "window.__violations=[];document.addEventListener('securitypolicyviolation',function(e){window.__violations.push(e.violatedDirective+' '+e.blockedURI)});" });
+
+/** Open one page and report what it asked for, which faces it drew with, and any policy it broke. */
+async function open(url) {
+  requested = [];
+  await cmd("Page.navigate", { url });
+  const end = Date.now() + 15000;
+  while (Date.now() < end && (await value("document.readyState")) !== "complete") await wait(100);
+  await value("document.fonts.ready.then(() => true)");
+  await wait(300);
+  const faces = await value("JSON.stringify([...document.fonts].map((f) => ({ family: f.family.replace(/[\"']/g, ''), status: f.status })))");
+  const violations = await value("JSON.stringify(window.__violations || [])");
+  const away = requested.filter((u) => /^https?:/i.test(u) && !u.startsWith(origin));
+  return { away, faces: JSON.parse(faces ?? "[]"), violations: JSON.parse(violations ?? "[]"), requested: requested.length };
+}
+const loaded = (faces, family) => faces.some((f) => f.family === family && f.status === "loaded");
+
+let failures = 0;
+const fail = (m) => { failures += 1; console.error(`  ✕ ${m}`); };
+let exit = 0;
+try {
+  // ── THE CONTROLS FIRST ──────────────────────────────────────────────────────────────────────────────
+  const leaked = await open(pathToFileURL(leak).href);
+  if (!leaked.away.some((u) => URL.canParse(u) && new URL(u).hostname === "api.fontshare.com")) {
+    console.error("report-offline-render-check: a report with a font service put back made no request this check could see. The instrument is blind; nothing below would mean anything.");
+    exit = 2;
+  }
+  const noFaces = await open(pathToFileURL(bare).href);
+  if (exit === 0 && (loaded(noFaces.faces, TEXT_FACE) || loaded(noFaces.faces, CODE_FACE))) {
+    console.error("report-offline-render-check: a report with its embedded faces taken out still reports them loaded. The font reading is blind; nothing below would mean anything.");
+    exit = 2;
+  }
+  if (exit === 0) {
+    console.log(`controls: a planted font stylesheet was caught (${leaked.away.length} request(s)), and a report without its faces loaded none`);
+    // ── EVERY PAGE ───────────────────────────────────────────────────────────────────────────────────
+    const runs = [];
+    for (const page of pages.filter((p) => p !== leak && p !== bare)) {
+      const rel = relative(pool, page);
+      runs.push([`${rel} (from disk)`, pathToFileURL(page).href, page.endsWith("/report.html")]);
+      if (page.endsWith("/report.html")) runs.push([`${rel} (served, report policy)`, `${origin}/${rel}`, true]);
+    }
+    for (const [name, url, isReport] of runs) {
+      const got = await open(url);
+      if (!got.requested) { fail(`${name}: the page made no request at all, not even for itself — it was not opened`); continue; }
+      for (const u of got.away) fail(`${name}: asked another machine for ${u}`);
+      if (!loaded(got.faces, TEXT_FACE)) fail(`${name}: the ${TEXT_FACE} face it carries did not load (${JSON.stringify(got.faces)})`);
+      if (isReport && !loaded(got.faces, CODE_FACE)) fail(`${name}: the ${CODE_FACE} face it carries did not load (${JSON.stringify(got.faces)})`);
+      for (const v of got.violations) fail(`${name}: broke its content policy: ${v}`);
+      if (!got.away.length && !got.violations.length) {
+        const size = url.startsWith("file:") ? ` · ${statSync(fileURLToPath(url)).size} bytes` : "";
+        console.log(`${name}: no other machine asked, ${got.faces.filter((f) => f.status === "loaded").map((f) => f.family).join(" + ")} loaded${size}`);
+      }
+    }
+    if (failures) { console.error(`\nreport-offline-render-check: ${failures} problem(s).`); exit = 1; }
+    else console.log(`\nreport-offline-render-check: ${runs.length} page opening(s), none asked another machine for anything.`);
+  }
+} finally {
+  try { ws.close(); } catch { /* the browser may already be gone */ }
+  try { process.kill(-chrome.pid, "SIGTERM"); } catch { /* already exited */ }
+  server.close();
+  if (keep) console.log(`  kept: ${browserRoot} and the pool at ${pool}`);
+  else rmSync(pool, { recursive: true, force: true });
+}
+process.exit(exit);