cool-workflow 0.2.2 → 0.2.4

package/scripts/release-flow.js

@@ -15,15 +15,22 @@
 // Modes:
 //   node release-flow.js [--check]                 gate + review, no mutation (default)
 //   node release-flow.js --cut --version x.y.z [--push]
-//                                                  also bump:version, commit verdict, tag,
-//                                                  (push), and — when --push — create the
-//                                                  GitHub Release for the tag (idempotent;
-//                                                  opt out with --no-release)
+//                                                  preflight (fail-fast checks BEFORE the
+//                                                  gate/vendor/reviewer spend anything),
+//                                                  then gate + review, then bump:version,
+//                                                  commit verdict, tag, and — when --push —
+//                                                  push ONLY the tag (refs/tags/vx.y.z; the
+//                                                  verdict commit is a one-hop leaf off the
+//                                                  reviewed main tip, it never lands on a
+//                                                  branch) and create the GitHub Release
+//                                                  (idempotent; opt out with --no-release)
 //   node release-flow.js --release --version x.y.z create-or-skip the GitHub Release for an
 //                                                  already-pushed tag (backfill); no gate/cut.
 //                                                  Fails closed if gh can't create it; add
 //                                                  --soft for best-effort (skip-not-fail).
-// Flags also accepted: --prev-tag <t>, --agent-command "...", --agent-model m, --dry-run
+// Flags also accepted: --prev-tag <t>, --agent-command "...", --agent-model m, --dry-run,
+//   --preflight-only (run the cut preflight and stop — used by release-oneclick.js),
+//   --allow-stale-head (skip the HEAD == origin/main tip check, deliberate re-cuts only)
 //
 // VERDICT CONTRACT (auto-generated by --cut, never write by hand):
 //   Path:  .cw-release/review-<FULLSHA>.verdict
@@ -31,6 +38,17 @@
 //   Both release-flow.js --cut and CI's release-gate.yml verify this exact path and
 //   format. The file MUST be committed to the tag's history.
 //
+// VERDICT SIGNING (optional, opt-in — see scripts/verdict-keygen.js):
+//   Set CW_RELEASE_VERDICT_PRIVKEY (a path or inline PEM) and this script signs
+//   the verdict file's exact bytes, writing a sidecar
+//   .cw-release/review-<FULLSHA>.verdict.sig (base64 ed25519). Once
+//   .cw-release/verdict-signing.pub is committed to the repo, release-gate.yml,
+//   npm-publish.yml, and block-unapproved-tag.sh all start REQUIRING a valid
+//   signature in addition to the APPROVED text check — closing the gap where
+//   anyone with shell access could hand-write a passing verdict file. Until
+//   that public key is committed, every check stays exactly as before
+//   (grep-only) — this is inert by default, never a silent behavior change.
+//
 // Test seams (smoke/operator only, never the delegated agent):
 //   CW_RELEASE_FLOW_GATE_CMD  overrides the deterministic gate command
 //     (default: `bash <thisdir>/release-gate.sh`) so the smoke can exercise the
@@ -48,6 +66,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const https = require("node:https");
 const http = require("node:http");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 
 const scriptsDir = __dirname;
@@ -364,6 +383,46 @@ function verifyVerdict(resultPath) {
   return cap;
 }
 
+// ---- verdict signing (optional, opt-in — see the header comment) -----------
+function resolveVerdictPrivateKey(value) {
+  const trimmed = String(value).trim();
+  if (trimmed.includes("BEGIN") && trimmed.includes("KEY")) return trimmed;
+  if (fs.existsSync(trimmed)) return fs.readFileSync(trimmed, "utf8");
+  die(`CW_RELEASE_VERDICT_PRIVKEY does not point to a readable key file or inline PEM: ${trimmed}`);
+}
+
+/** Called only after verifyVerdict() has confirmed resultPath's bytes are a
+ *  genuine "APPROVED <HEAD>" verdict. A no-op unless CW_RELEASE_VERDICT_PRIVKEY
+ *  is set. When it IS set, a signing failure fails closed (die()) rather than
+ *  silently emitting an unsigned verdict — an operator who deliberately
+ *  configured a signing key should never end up with the same on-disk state
+ *  as one who didn't. */
+function signVerdictIfConfigured(resultPath) {
+  const raw = process.env.CW_RELEASE_VERDICT_PRIVKEY;
+  if (!raw || !raw.trim()) return;
+  const pem = resolveVerdictPrivateKey(raw);
+  const sigPath = `${resultPath}.sig`;
+  try {
+    const key = crypto.createPrivateKey(pem);
+    // crypto.sign(null, ...) does NOT throw for an RSA or EC key — it silently
+    // signs with that algorithm's own default digest, producing a
+    // syntactically valid signature that can never verify against the
+    // committed ed25519 public key. Catching that here, at signing time,
+    // means a misconfigured key dies closed locally instead of only being
+    // caught later by CI (or not at all, if the repo hasn't committed
+    // verdict-signing.pub yet).
+    if (key.asymmetricKeyType !== "ed25519") {
+      die(`CW_RELEASE_VERDICT_PRIVKEY is a ${key.asymmetricKeyType || "unknown"} key, not ed25519 — generate one with scripts/verdict-keygen.js`);
+    }
+    const message = fs.readFileSync(resultPath);
+    const signature = crypto.sign(null, message, key).toString("base64");
+    fs.writeFileSync(sigPath, `${signature}\n`);
+  } catch (error) {
+    die(`failed to sign the verdict with CW_RELEASE_VERDICT_PRIVKEY: ${error.message}`);
+  }
+  say(`verdict signed → ${path.relative(repoRoot, sigPath)}`);
+}
+
 // ---- GitHub Release (optional, presentation/distribution) ------------------
 // NOT a correctness gate: the load-bearing artifacts (the tag + the
 // provenance-attested npm publish) already exist when this runs. So `gh` is NOT
@@ -398,13 +457,22 @@ function prevTagOf(version) {
   return git(["describe", "--tags", "--abbrev=0", `v${version}^`]).out || "";
 }
 
+// Full regex escape (same shape as parity-check.js's helper — scripts stay
+// zero-dependency single files, so it is copied, not required). The version
+// is SEMVER-validated on every path that reaches here, but escaping every
+// metacharacter costs nothing and keeps the RegExp construction safe on its
+// own terms.
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // Extract the `## <version>` section body from the CHANGELOG AS SHIPPED AT THE
 // TAG (git show), so the notes reflect what that tag actually carried.
 function changelogSection(version) {
   const show = git(["show", `v${version}:CHANGELOG.md`]);
   if (show.code !== 0 || !show.out) return "";
   const lines = show.out.split(/\r?\n/);
-  const esc = version.replace(/\./g, "\\.");
+  const esc = escapeRegExp(version);
   const startRe = new RegExp(`^## \\[?${esc}\\b`);
   let start = -1;
   for (let i = 0; i < lines.length; i++) if (startRe.test(lines[i])) { start = i; break; }
@@ -506,10 +574,102 @@ function releaseGitHub(version, { required = false } = {}) {
   return true;
 }
 
+// ---- 2b. cut preflight (fail fast, BEFORE any paid step) --------------------
+// Every check here answers one question: "will this cut die AFTER the gate,
+// the live vendor preflight, and the reviewer have already run?" Each check
+// was a real post-reviewer failure in the v0.2.3 cut (2026-07-10) — a missing
+// --version, an unsigned verdict the CI gate then rejected, a left-over local
+// tag, and a two-hop recovery that broke the HEAD~1 topology rule. All of
+// them are answerable in under a second, so answer them FIRST.
+//
+// Fixture safety: each check is gated on the thing it checks being present
+// (a committed signing pubkey, a CHANGELOG.md, an `origin` remote), so the
+// smoke fixtures — bare repos with none of those — pass through untouched.
+function preflightCut() {
+  say("[0/3] cut preflight");
+  // (a) version — cheap and load-bearing for every later step. Checking it
+  // here (not only inside cut()) is what stops a full gate+reviewer run from
+  // being thrown away over a missing flag.
+  if (!cutVersion || !/^\d+\.\d+\.\d+$/.test(cutVersion)) die("--cut requires --version x.y.z");
+
+  // (b) signing — once .cw-release/verdict-signing.pub is committed, CI's
+  // release-gate REQUIRES a valid signature; a cut without the private key
+  // configured would push an unsigned verdict that fails only in CI. Fail
+  // closed here instead, and also prove the configured key IS the committed
+  // key (a wrong key signs "successfully" and still fails in CI).
+  const pubPath = path.join(repoRoot, ".cw-release", "verdict-signing.pub");
+  if (fs.existsSync(pubPath)) {
+    const raw = process.env.CW_RELEASE_VERDICT_PRIVKEY;
+    if (!raw || !raw.trim()) {
+      die(
+        "verdict-signing.pub is committed, so CI requires a SIGNED verdict — set the private key first",
+        'fix:  export CW_RELEASE_VERDICT_PRIVKEY=~/.cw-keys/verdict-signing.key'
+      );
+    }
+    const pem = resolveVerdictPrivateKey(raw);
+    let key;
+    try {
+      key = crypto.createPrivateKey(pem);
+    } catch (error) {
+      die(`CW_RELEASE_VERDICT_PRIVKEY is not a readable private key: ${error.message}`);
+    }
+    if (key.asymmetricKeyType !== "ed25519") {
+      die(`CW_RELEASE_VERDICT_PRIVKEY is a ${key.asymmetricKeyType || "unknown"} key, not ed25519 — generate one with scripts/verdict-keygen.js`);
+    }
+    const derivedPub = crypto.createPublicKey(key).export({ type: "spki", format: "pem" }).toString().trim();
+    const committedPub = fs.readFileSync(pubPath, "utf8").trim();
+    if (derivedPub !== committedPub) {
+      die("CW_RELEASE_VERDICT_PRIVKEY does not match the committed .cw-release/verdict-signing.pub — wrong key; CI would reject its signature");
+    }
+  }
+
+  // (c) tag must not exist yet — a stale local tag makes cut() die at the very
+  // last step ("tag 'vX.Y.Z' already exists") after everything else has run.
+  if (git(["tag", "-l", `v${cutVersion}`]).out) {
+    die(`tag v${cutVersion} already exists locally — delete it first (git tag -d v${cutVersion}) or pick the next version`);
+  }
+
+  // (d) CHANGELOG must already carry the release section — release notes get
+  // pasted verbatim into the GitHub Release, and bump:version's content gate
+  // would only catch this inside cut(), after the reviewer.
+  const changelogPath = path.join(repoRoot, "CHANGELOG.md");
+  if (fs.existsSync(changelogPath) && !fs.readFileSync(changelogPath, "utf8").includes(`## ${cutVersion}`)) {
+    die(`CHANGELOG.md has no "## ${cutVersion}" section — write the release notes first`);
+  }
+
+  // (e) clean tree (tracked files only — cut()'s `git add -u` can never sweep
+  // an untracked stray in, so untracked files are not a cut hazard).
+  const dirty = git(["status", "--porcelain", "-uno"]).out;
+  if (dirty) die("working tree has tracked modifications — commit or stash them before a cut", dirty);
+
+  // (f) network-dependent checks, only when this cut will actually push and
+  // only when an `origin` remote exists (smoke fixtures have none):
+  if (PUSH && git(["remote"]).out.split("\n").includes("origin")) {
+    // remote tag must not exist (someone/some run already published this version)
+    const remoteTag = git(["ls-remote", "origin", `refs/tags/v${cutVersion}`]);
+    if (remoteTag.code === 0 && remoteTag.out) {
+      die(`tag v${cutVersion} already exists on origin — this version is already published; pick the next version`);
+    }
+    // HEAD must be the current origin/main tip — cutting a stale HEAD publishes
+    // old code (nearly happened on the v0.2.2 cut).
+    if (git(["fetch", "origin", "main", "--quiet"]).code !== 0) {
+      die("git fetch origin main failed — a --push cut needs the network anyway; fix connectivity first");
+    }
+    const mainTip = git(["rev-parse", "origin/main"]).out;
+    if (mainTip !== HEAD && !has("--allow-stale-head")) {
+      die(
+        `HEAD (${HEAD.slice(0, 12)}) is not the origin/main tip (${mainTip.slice(0, 12)}) — a cut must release exactly what main has`,
+        "fix:  git fetch origin main && git checkout -B <branch> origin/main   (or pass --allow-stale-head if this is deliberate)"
+      );
+    }
+  }
+  say("cut preflight OK");
+}
+
 // ---- 3. optional cut (bump + commit verdict + tag + push) ------------------
 function cut(resultPath, capability) {
   if (!cutVersion || !/^\d+\.\d+\.\d+$/.test(cutVersion)) die("--cut requires --version x.y.z");
-  if (DRY_RUN) { say(`[dry-run] would: bump:version ${cutVersion}, commit verdict, tag v${cutVersion}${PUSH ? ", push" : ""}`); return; }
+  if (DRY_RUN) { say(`[dry-run] would: bump:version ${cutVersion}, commit verdict, tag v${cutVersion}${PUSH ? `, push refs/tags/v${cutVersion} (tag only, no branch)` : ""}`); return; }
   const bump = spawnSync("npm", ["run", "bump:version", "--", cutVersion], { cwd: pluginRoot, encoding: "utf8", stdio: "inherit" });
   if (bump.status !== 0) die("bump:version failed");
   // Regenerate the gated project index after the version bump (PR #87 gate).
@@ -522,19 +682,27 @@ function cut(resultPath, capability) {
   // operator's local home path) must never ride into the immutable tag commit
   // (that tripped pii-redaction-smoke and red-failed release-gate for v0.1.96).
   // `git add -u` touches tracked files only, so no untracked file can be swept in;
-  // the verdict is the single new path the cut is allowed to add.
+  // the verdict (and its .sig sidecar, when verdict signing is configured) are
+  // the only new paths the cut is allowed to add.
   git(["add", "-u"]);
   git(["add", "--", path.relative(repoRoot, resultPath)]);
+  const sigPath = `${resultPath}.sig`;
+  if (fs.existsSync(sigPath)) git(["add", "--", path.relative(repoRoot, sigPath)]);
   const commit = git(["commit", "-m", `chore(release): record APPROVED reviewer verdict for v${cutVersion}`]);
   if (commit.code !== 0) die("verdict commit failed", commit.err);
   const tag = git(["tag", "-a", `v${cutVersion}`, "-m", `v${cutVersion}: ${capability || "release"}`]);
   if (tag.code !== 0) die("git tag failed", tag.err);
   if (PUSH) {
-    // Atomic: the verdict commit on HEAD and the tag land together or not at all.
-    // A non-atomic two-push could leave main advanced with no tag, so CI's
-    // release-gate (which fires on the tag) never runs and the release silently stalls.
-    const push = git(["push", "--atomic", "origin", "HEAD", `v${cutVersion}`]);
-    if (push.code !== 0) die("atomic push of HEAD + tag failed (nothing partially pushed)", push.err);
+    // Push ONLY the tag. The verdict commit is a one-hop leaf on the reviewed
+    // main-tip commit, reachable through the tag alone — it does not need to
+    // be on any branch. Pushing HEAD here used to (a) hit main's branch
+    // protection (enforce_admins blocks even the owner's direct push) or
+    // (b) mint a stray remote branch named after whatever branch the cut ran
+    // from. Tags are not protected in this repo, and CI's release-gate checks
+    // the TAG's own history (verdict at HEAD or HEAD~1), so the tag alone is
+    // the complete release artifact — proven live by the v0.2.3 cut.
+    const push = git(["push", "origin", `refs/tags/v${cutVersion}`]);
+    if (push.code !== 0) die("tag push failed (nothing was pushed)", push.err);
   }
   say(`tagged v${cutVersion}${PUSH ? " and pushed" : " (local only; push when ready)"}`);
   // Finishing step: create the GitHub Release for the just-pushed tag. Only when
@@ -559,6 +727,18 @@ function main() {
     return;
   }
 
+  // Fail-fast checks FIRST — nothing below (gate, live vendor calls, the
+  // reviewer) runs until every cheap precondition holds. --preflight-only
+  // lets an orchestrator (release-oneclick.js) run just this step. Without
+  // --cut there is no preflight to run, so answering ok:true would be a
+  // green light with zero checks done — refuse instead.
+  if (has("--preflight-only") && !MODE_CUT) die("--preflight-only requires --cut (there is no preflight to run in check/release mode)");
+  if (MODE_CUT) preflightCut();
+  if (has("--preflight-only")) {
+    process.stdout.write(`${JSON.stringify({ ok: true, mode: "preflight", version: cutVersion || null }, null, 2)}\n`);
+    return;
+  }
+
   const markerDir = path.join(repoRoot, ".cw-release");
   fs.mkdirSync(markerDir, { recursive: true });
   const resultPath = path.join(markerDir, `review-${HEAD}.verdict`);
@@ -569,6 +749,7 @@ function main() {
   fs.writeFileSync(inputPath, buildReviewerInput(resultPath));
   delegateReview(resultPath, inputPath);
   const capability = verifyVerdict(resultPath);
+  signVerdictIfConfigured(resultPath);
 
   if (MODE_CUT) cut(resultPath, capability);