testguard-cli 0.8.0__tar.gz → 0.8.1__tar.gz

testguard_cli-0.8.1/.github/scripts/sync-release-version.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * package.json is the single source of truth for the version. Every other
+ * surface that carries it is synced from there:
+ *   - pyproject.toml         `version = "x.y.z"`
+ *   - action.yml             default of the `version` input
+ *   - packaging/homebrew/*.rb the tarball URL; the `sha256` is set by `--sha256`
+ *                            from the PUBLISHED tarball (release.yml, after npm)
+ *   - packaging/gitlab/*.yml  the include URL tag and the `version` input default
+ *   - README.md               the GitHub Action reference AND the GitLab include URL
+ *
+ * A file may carry more than one form, and each needs its own entry: README
+ * holds both the `raccioly/testguard@vX.Y.Z` action reference and the
+ * `testguard/vX.Y.Z/packaging` template URL. Only the first was listed, so
+ * v0.6.0 shipped with both README copies of the GitLab URL left at v0.5.0
+ * while `--check` reported "all version surfaces at 0.6.0" — a surface this
+ * script was never told to look at cannot drift in its eyes.
+ *
+ * The Homebrew `sha256` is the same lesson one step further: the URL was a
+ * surface, the hash beside it was a comment telling a human to run curl. It
+ * carried 385d69f9… unchanged across v0.6.0, v0.7.0 and v0.8.0 — a hash
+ * matching none of them. So the hash is now a surface too, with three modes:
+ *
+ *   --check            offline: every version surface at package.json's version,
+ *                      the formula's sha256 is 64 hex and not the known-stale
+ *                      placeholder. Used by release.yml's test job (before the
+ *                      tag, when the tarball cannot exist yet) and prepublishOnly.
+ *   --check --online   additionally downloads the tarball the formula names and
+ *                      requires its sha256 to match. Used by release.yml's
+ *                      detect-version (is the formula still owed?) and by the
+ *                      sha job as a post-condition before it opens the PR.
+ *   --sha256           waits for the tarball to become downloadable (bounded by
+ *                      --wait), computes its sha256 and writes it into the
+ *                      formula — only when the value changes. Exit 1 on timeout
+ *                      or on a 200 that is not a gzip tarball: a hashed error
+ *                      page would poison the formula, and "never optimistic".
+ *
+ * The hash is always computed from the REGISTRY tarball — what Homebrew will
+ * download — never from a local `npm pack`: a provenance-signed publish can
+ * differ byte for byte from the pack output.
+ *
+ *   --list-surfaces    print every file this script may write, one per line. The
+ *                      release workflows allow-list exactly these (plus
+ *                      package.json, package-lock.json and CHANGELOG.md, which
+ *                      the bump writes directly), so a surface added above can
+ *                      never again be rejected as an "unexpected file in the
+ *                      release diff" — which is what stopped every weekly
+ *                      release after the GitLab template became a surface.
+ *   --registry <url>   registry base (default https://registry.npmjs.org); the
+ *                      tests point it at a local server so `npm test` is offline.
+ *   --wait <s>         how long --sha256 keeps polling (default 900).
+ *   --interval <s>     seconds between polls (default 15).
+ *   --timeout <s>      per-request timeout (default 60): a registry that accepts the
+ *                      connection and never answers is a failed attempt, not a hang.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const root = resolve(process.argv[1], '..', '..', '..');
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(name);
+const option = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? fallback : argv[i + 1];
+};
+const check = flag('--check');
+const listSurfaces = flag('--list-surfaces');
+const online = flag('--online');
+const setSha = flag('--sha256');
+const registry = (option('--registry', 'https://registry.npmjs.org')).replace(/\/+$/, '');
+const waitSeconds = Number(option('--wait', '900'));
+const intervalSeconds = Number(option('--interval', '15'));
+const timeoutSeconds = Number(option('--timeout', '60'));
+if (!Number.isFinite(waitSeconds) || waitSeconds < 0) throw new Error(`--wait must be a non-negative number of seconds, got ${option('--wait')}`);
+if (!Number.isFinite(intervalSeconds) || intervalSeconds < 0) throw new Error(`--interval must be a non-negative number of seconds, got ${option('--interval')}`);
+if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) throw new Error(`--timeout must be a positive number of seconds, got ${option('--timeout')}`);
+
+const version = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')).version;
+if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`package.json version is not a stable semver: ${version}`);
+
+const FORMULA = 'packaging/homebrew/testguard.rb';
+const formulaPath = resolve(root, FORMULA);
+/** The hash the formula carried, unchanged, from v0.6.0 through v0.8.0. It matches no published tarball. */
+const KNOWN_STALE_SHA256 = '385d69f9d3c153b934d9c1cb6a2c754eb9b221b0a8c0ba8b805858384d2d4678';
+const SHA_LINE = /^(\s*sha256 ")([^"]*)(")/m;
+const TARBALL = `testguard-cli-${version}.tgz`;
+const tarballUrl = `${registry}/testguard-cli/-/${TARBALL}`;
+
+const surfaces = [
+  ['pyproject.toml', /^version = "[^"]+"/m, `version = "${version}"`],
+  ['action.yml', /(\n  version:\n    description: [^\n]*\n    required: false\n    default: ')[^']*(')/, `$1${version}$2`],
+  [FORMULA, /testguard-cli-\d+\.\d+\.\d+\.tgz/g, TARBALL],
+  ['README.md', /raccioly\/testguard@v\d+\.\d+\.\d+/g, `raccioly/testguard@v${version}`],
+  ['README.md', /testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
+  ['packaging/gitlab/testguard.gitlab-ci.yml', /testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
+  ['packaging/gitlab/testguard.gitlab-ci.yml', /(\n    version:\n      description: [^\n]*\n      default: ")\d+\.\d+\.\d+(")/, `$1${version}$2`],
+];
+
+if (listSurfaces) {
+  // Derived from the same table the writes use, so the two cannot disagree.
+  for (const rel of [...new Set(surfaces.map(([rel]) => rel))]) console.log(rel);
+  process.exit(0);
+}
+
+/** The formula's current `sha256 "…"` value, or a throw when the line is missing. */
+function formulaSha256() {
+  const m = SHA_LINE.exec(readFileSync(formulaPath, 'utf8'));
+  if (!m) throw new Error(`${FORMULA}: sha256 line not found`);
+  return m[2];
+}
+
+/**
+ * One GET of the tarball. Returns `{ status, sha256 }`; `sha256` is set only
+ * for a 200 whose body starts with the gzip magic (1f 8b) — a registry error
+ * page with a 200 status is treated as "not a tarball", never hashed.
+ */
+async function fetchTarball() {
+  const res = await fetch(tarballUrl, { redirect: 'follow', signal: AbortSignal.timeout(timeoutSeconds * 1000) });
+  if (res.status !== 200) return { status: res.status };
+  const body = Buffer.from(await res.arrayBuffer());
+  if (body.length < 2 || body[0] !== 0x1f || body[1] !== 0x8b) return { status: 200, notTarball: true, bytes: body.length };
+  return { status: 200, sha256: createHash('sha256').update(body).digest('hex'), bytes: body.length };
+}
+
+const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
+
+/**
+ * Polls until the tarball downloads as a gzip, or the wait runs out. Every
+ * non-200 and every network error counts as "not yet": the registry answers
+ * `PUT 202` to a publish and can take minutes to serve the file.
+ */
+async function waitForTarball() {
+  const deadline = Date.now() + waitSeconds * 1000;
+  let attempt = 0;
+  for (;;) {
+    attempt++;
+    let result;
+    try {
+      result = await fetchTarball();
+    } catch (e) {
+      result = { status: 0, error: e.message };
+    }
+    if (result.sha256) return result;
+    const why = result.notTarball ? `200 but not a gzip tarball (${result.bytes} bytes)` : result.error ? `network error: ${result.error}` : `HTTP ${result.status}`;
+    if (Date.now() >= deadline) throw new Error(`${tarballUrl}: not downloadable after ${attempt} attempt(s) over ${waitSeconds}s — last: ${why}`);
+    console.error(`${TARBALL}: ${why}; retrying in ${intervalSeconds}s (attempt ${attempt})`);
+    await sleep(intervalSeconds);
+  }
+}
+
+if (setSha) {
+  const { sha256, bytes } = await waitForTarball();
+  const before = readFileSync(formulaPath, 'utf8');
+  const current = formulaSha256();
+  if (current === sha256) {
+    console.log(`${FORMULA}: sha256 unchanged (${sha256}, ${bytes} bytes)`);
+  } else {
+    writeFileSync(formulaPath, before.replace(SHA_LINE, `$1${sha256}$3`));
+    if (formulaSha256() !== sha256) throw new Error(`${FORMULA}: sha256 line did not take the new value`);
+    console.log(`${FORMULA}: sha256 ${current} -> ${sha256} (${bytes} bytes from ${tarballUrl})`);
+  }
+  process.exit(0);
+}
+
+let drift = 0;
+for (const [rel, pattern, replacement] of surfaces) {
+  const path = resolve(root, rel);
+  const before = readFileSync(path, 'utf8');
+  if (!pattern.test(before)) throw new Error(`${rel}: version pattern not found`);
+  const after = before.replace(pattern, replacement);
+  if (after === before) continue;
+  drift++;
+  if (check) console.error(`${rel}: out of sync with package.json ${version}`);
+  else { writeFileSync(path, after); console.log(`${rel}: synced to ${version}`); }
+}
+
+if (check) {
+  const sha = formulaSha256();
+  if (!/^[0-9a-f]{64}$/.test(sha)) { drift++; console.error(`${FORMULA}: sha256 is not 64 hex characters: "${sha}"`); }
+  else if (sha === KNOWN_STALE_SHA256) { drift++; console.error(`${FORMULA}: sha256 is the known-stale placeholder ${sha.slice(0, 8)}… (matches no published tarball); run --sha256 after publishing`); }
+  if (online) {
+    let result;
+    try {
+      result = await fetchTarball();
+    } catch (e) {
+      result = { status: 0, error: e.message };
+    }
+    if (!result.sha256) { drift++; console.error(`${FORMULA}: tarball not downloadable — ${tarballUrl}: ${result.error ?? (result.notTarball ? '200 but not a gzip tarball' : `HTTP ${result.status}`)}`); }
+    else if (result.sha256 !== sha) { drift++; console.error(`${FORMULA}: sha256 ${sha} does not match the published tarball ${result.sha256} (${tarballUrl})`); }
+    else console.log(`${FORMULA}: sha256 matches ${tarballUrl}`);
+  }
+}
+if (check && drift) process.exit(1);
+if (check) console.log(`all version surfaces at ${version}`);

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/.github/workflows/auto-merge.yml

@@ -46,7 +46,14 @@ jobs:
 
             const { data: files } = await github.rest.pulls.listFiles({ owner, repo, pull_number: num, per_page: 300 });
             const paths = files.map((f) => f.filename);
-            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md']);
+            // Deliberately spelled out, not derived: this is the gate that merges
+            // without human review, so what a bot may touch stays readable here
+            // and is not computed from code the PR itself could change. Keep it
+            // in step with `sync-release-version.mjs --list-surfaces` plus the
+            // three files the bump writes — test/release-sync.test.mjs fails if
+            // a surface is missing, which is how the GitLab template's absence
+            // (it would have held every release PR for review) was found.
+            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md', 'packaging/gitlab/testguard.gitlab-ci.yml']);
 
             if (author === 'dependabot[bot]') {
               const m = /from (\d+)\.(\d+)\.\S+ to (\d+)\.(\d+)\./.exec(pr.title || '');

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/.github/workflows/release.yml

@@ -36,6 +36,7 @@ jobs:
       tag_missing: ${{ steps.check.outputs.tag_missing }}
       npm_missing: ${{ steps.check.outputs.npm_missing }}
       pypi_missing: ${{ steps.check.outputs.pypi_missing }}
+      brew_missing: ${{ steps.check.outputs.brew_missing }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -45,6 +46,13 @@ jobs:
         # Each surface is gated on ITS OWN registry, not on the tag. A tag
         # whose npm or PyPI publish failed (e.g. Trusted Publishing not yet
         # configured) is retried by simply re-running this workflow.
+        #
+        # The Homebrew formula's sha256 is a surface too, gated on the registry
+        # tarball it names: `--check --online` downloads it and compares. It is
+        # owed (brew_missing=true) until npm serves the tarball AND the formula
+        # on main carries its hash — so a failed sha job is retried by the
+        # hourly sweep exactly like a failed publish. It does not set `changed`:
+        # only tag/npm/PyPI need the test job and the publish jobs.
         run: |
           CURRENT=$(node -p "require('./package.json').version")
           TAG="v${CURRENT}"
@@ -53,12 +61,17 @@ jobs:
           if npm view "testguard-cli@${CURRENT}" version >/dev/null 2>&1; then NPMM=false; else NPMM=true; fi
           CODE=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/testguard-cli/${CURRENT}/json")
           if [ "$CODE" = "200" ]; then PYPIM=false; else PYPIM=true; fi
+          if node .github/scripts/sync-release-version.mjs --check --online; then BREWM=false; else BREWM=true; fi
           echo "tag_missing=$TAGM" >> "$GITHUB_OUTPUT"
           echo "npm_missing=$NPMM" >> "$GITHUB_OUTPUT"
           echo "pypi_missing=$PYPIM" >> "$GITHUB_OUTPUT"
+          echo "brew_missing=$BREWM" >> "$GITHUB_OUTPUT"
           if [ "$TAGM" = true ] || [ "$NPMM" = true ] || [ "$PYPIM" = true ]; then
             echo "changed=true" >> "$GITHUB_OUTPUT"
-            echo "✅ $TAG — tag missing: $TAGM · npm missing: $NPMM · PyPI missing: $PYPIM"
+            echo "✅ $TAG — tag missing: $TAGM · npm missing: $NPMM · PyPI missing: $PYPIM · Homebrew sha256 owed: $BREWM"
+          elif [ "$BREWM" = true ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "✅ $TAG is published everywhere; only the Homebrew sha256 is owed"
           else
             echo "changed=false" >> "$GITHUB_OUTPUT"
             echo "⏭️ $TAG is fully released everywhere — nothing to do"
@@ -82,6 +95,12 @@ jobs:
       - name: Self-probe must be fully defended before anything ships
         run: node cli/testguard.mjs probe . --budget 180000 --out "$RUNNER_TEMP/self-evidence.json" --quiet --cost
       - name: Version surfaces are in sync
+        # Offline on purpose. Before the tag the tarball for this version
+        # cannot exist, so `--online` would say nothing in the normal path and
+        # would DEADLOCK the recovery path: npm published, the sha job failed,
+        # the formula still stale — an online check here fails and the job
+        # that fixes the formula never runs. The online comparison lives in
+        # detect-version (is it owed?) and in homebrew-sha (did it take?).
         run: node .github/scripts/sync-release-version.mjs --check
 
   create-release:
@@ -177,3 +196,113 @@ jobs:
       - name: Assert OIDC token is available
         run: '[ -n "$ACTIONS_ID_TOKEN_REQUEST_URL" ] || { echo "::error::no OIDC token endpoint"; exit 1; }'
       - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  homebrew-sha:
+    # The formula's sha256 is set from the PUBLISHED tarball — what Homebrew
+    # will download, which a provenance-signed publish can make differ byte
+    # for byte from `npm pack` — after npm serves it (a publish is `PUT 202`;
+    # the file can take minutes to appear, so the script polls, bounded).
+    #
+    # It cannot commit to main: branch protection requires the three CI legs
+    # on every commit and github-actions[bot] is no admin. So the one-line
+    # change lands as a bot PR with native auto-merge armed, and this job
+    # dispatches ci.yml on the branch itself — a PR opened with GITHUB_TOKEN
+    # gets no pull_request run, but workflow_dispatch is the documented
+    # exception. That also means the merge triggers nothing here; the hourly
+    # sweep observes the merged formula and finds brew_missing=false.
+    #
+    # Idempotent: an existing branch is reused, an existing open PR is left
+    # alone (CI re-dispatched only if its head has no check runs), a closed
+    # PR is respected as a human decision, and a formula that already carries
+    # the published hash lands nothing.
+    needs: [detect-version, test, create-release, publish-npm]
+    if: >-
+      !cancelled()
+      && needs.detect-version.outputs.brew_missing == 'true'
+      && needs.test.result != 'failure'
+      && needs.create-release.result != 'failure'
+      && (needs.publish-npm.result == 'success' || (needs.publish-npm.result == 'skipped' && needs.detect-version.outputs.npm_missing == 'false'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # pushes the chore/homebrew-sha-v* branch
+      pull-requests: write # opens the PR and arms auto-merge
+      actions: write # dispatches ci.yml on that branch
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - name: Set sha256 from the published tarball; land it as an auto-merging PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          VERSION="${{ needs.detect-version.outputs.version }}"
+          ON_MAIN=$(node -p "require('./package.json').version")
+          if [ "$ON_MAIN" != "$VERSION" ]; then
+            echo "⏭️ main is already at v${ON_MAIN}, not v${VERSION}; that release sets its own sha256"; exit 0
+          fi
+          BRANCH="chore/homebrew-sha-v${VERSION}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
+            git fetch origin "$BRANCH"
+            git checkout -B "$BRANCH" "origin/$BRANCH"
+          else
+            git checkout -b "$BRANCH"
+          fi
+
+          node .github/scripts/sync-release-version.mjs --sha256 --wait 900
+          # Post-condition: the file now on disk matches the tarball, and no
+          # other surface drifted. Nothing is pushed unless this passes.
+          node .github/scripts/sync-release-version.mjs --check --online
+
+          if git diff --quiet -- packaging/homebrew/testguard.rb; then
+            echo "✅ $BRANCH already carries the published sha256"
+          else
+            git add packaging/homebrew/testguard.rb
+            git commit -m "chore(homebrew): sha256 for v${VERSION}, from the published tarball"
+            git push origin "$BRANCH"
+          fi
+          if [ -z "$(git log --oneline origin/main..HEAD)" ]; then
+            echo "✅ main already matches the published tarball; nothing to land"; exit 0
+          fi
+
+          CLOSED=$(gh pr list --head "$BRANCH" --base main --state closed --json url,mergedAt --jq '[.[] | select(.mergedAt == null)][0].url')
+          if [ -n "$CLOSED" ]; then
+            echo "::warning::$CLOSED was closed without merging; leaving that decision alone. Delete branch $BRANCH to let the sweep retry."; exit 0
+          fi
+          PR=$(gh pr list --head "$BRANCH" --base main --state open --json url --jq '.[0].url')
+          if [ -z "$PR" ]; then
+            {
+              printf 'Automated: `sha256` of `packaging/homebrew/testguard.rb` set from the published tarball\n\n'
+              printf '    https://registry.npmjs.org/testguard-cli/-/testguard-cli-%s.tgz\n\n' "$VERSION"
+              printf 'Computed by `.github/scripts/sync-release-version.mjs --sha256` in release.yml after `npm publish`, from the registry — never from a local `npm pack`. `--check --online` confirmed the value before this PR was opened.\n\n'
+              printf 'Auto-merge is armed; CI was dispatched on this branch by the release workflow. If the checks never appear: `gh workflow run ci.yml --ref %s`.\n' "$BRANCH"
+            } > /tmp/pr-body.md
+            if PR=$(gh pr create --base main --head "$BRANCH" --title "chore(homebrew): sha256 for v${VERSION}" --body-file /tmp/pr-body.md 2>/tmp/pr-err); then
+              gh pr merge --auto --squash "$PR"
+              echo "Opened $PR"
+            else
+              cat /tmp/pr-err
+              if grep -q 'not permitted to create or approve pull requests' /tmp/pr-err; then
+                echo "::error::GITHUB_TOKEN may not open a pull request: \"GitHub Actions is not permitted to create or approve pull requests\". The branch is pushed and correct; only the PR is missing. Fix it once, in Settings -> Actions -> General -> Workflow permissions, by ticking \"Allow GitHub Actions to create and approve pull requests\" (equivalently: gh api -X PUT repos/$GITHUB_REPOSITORY/actions/permissions/workflow -F default_workflow_permissions=read -F can_approve_pull_request_reviews=true), then re-run this workflow. Until then, open it by hand: gh pr create --base main --head $BRANCH The formula on main still carries the previous release's hash until then, and detect-version will keep reporting it owed on every hourly sweep."
+              else
+                echo "::error::gh pr create failed for $BRANCH — see the output above."
+              fi
+              exit 1
+            fi
+          else
+            echo "✅ PR already open: $PR"
+          fi
+          HEAD_SHA=$(git rev-parse HEAD)
+          RUNS=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${HEAD_SHA}/check-runs" --jq '.total_count')
+          if [ "${RUNS:-0}" = "0" ]; then
+            gh workflow run ci.yml --ref "$BRANCH"
+            echo "Dispatched ci.yml on $BRANCH ($HEAD_SHA)"
+          else
+            echo "✅ $HEAD_SHA already has $RUNS check run(s)"
+          fi

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/.github/workflows/scheduled-release.yml

@@ -88,10 +88,23 @@ jobs:
 
       - name: Verify the tree is still green
         if: steps.check.outputs.changed == 'true'
+        # --include-dirty is REQUIRED here, not a convenience. The step above
+        # bumped the version and synced every surface, and those writes are
+        # still uncommitted: the commit happens later, in the PR step. One of
+        # those surfaces, packaging/gitlab/testguard.gitlab-ci.yml, is the
+        # fault target of TG-GITLAB-PROBE-EXIT-PRESERVED, so the default
+        # worktree mode refuses to run at all — "1 defender/target file has
+        # uncommitted changes … worktree mode probes HEAD, so those changes
+        # would be silently ignored" (exit 2). That refusal is correct; the
+        # answer is to probe the tree we are about to release, which is what
+        # --include-dirty does (it snapshots the working tree into a scratch
+        # commit). --ignore-dirty would probe HEAD and quietly verify the
+        # PREVIOUS version instead, which is the optimistic reading this
+        # project does not take.
         run: |
           npm ci
           npm test
-          node cli/testguard.mjs probe . --budget 180000 --quiet --out "$RUNNER_TEMP/self.json"
+          node cli/testguard.mjs probe . --budget 180000 --quiet --include-dirty --out "$RUNNER_TEMP/self.json"
 
       - name: Open release PR with auto-merge armed
         if: steps.check.outputs.changed == 'true'
@@ -99,12 +112,17 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           BRANCH="release/v${NEW_VERSION}"
-          # Only release surfaces may change in a release PR.
+          # Only release surfaces may change in a release PR. The list is
+          # DERIVED from the sync script, never retyped here: when the GitLab
+          # template became a surface it was left out of the hand-written list,
+          # so the first release to reach this guard would have been rejected
+          # for writing a file the release is supposed to write. The three
+          # extras are the ones the bump step writes directly.
+          ALLOWED=$(node .github/scripts/sync-release-version.mjs --list-surfaces; printf 'package.json\npackage-lock.json\nCHANGELOG.md\n')
+          echo "Release surfaces allowed in this diff:"; printf '%s\n' "$ALLOWED" | sed 's/^/  /'
           CHANGED=$(git diff --name-only HEAD --)
           for f in $CHANGED; do
-            case "$f" in package.json|package-lock.json|pyproject.toml|CHANGELOG.md|action.yml|packaging/homebrew/testguard.rb|README.md) ;;
-              *) echo "::error::unexpected file in release diff: $f"; exit 1;;
-            esac
+            printf '%s\n' "$ALLOWED" | grep -qxF "$f" || { echo "::error::unexpected file in release diff: $f"; exit 1; }
           done
           if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
             echo "::error::branch $BRANCH already exists; refusing to overwrite"; exit 1
@@ -116,6 +134,18 @@ jobs:
           git commit -m "release: v${NEW_VERSION} — automated weekly batch"
           git push origin "$BRANCH"
           printf 'Automated weekly release. Version bump + CHANGELOG entry + synced version surfaces. Merging tags and publishes to npm and PyPI via release.yml.\n\nCI does not start automatically on PRs opened by GITHUB_TOKEN. Run:\n\n    gh workflow run ci.yml --ref %s\n\nAuto-merge is armed; it completes once the required checks pass.\n' "$BRANCH" > /tmp/pr-body.md
-          PR=$(gh pr create --base main --head "$BRANCH" --title "release: v${NEW_VERSION} — automated weekly batch" --body-file /tmp/pr-body.md)
-          gh pr merge --auto --squash "$PR"
-          echo "Release PR: $PR"
+          # A bare `gh pr create` failure here reads as a GraphQL error with no
+          # hint of the cause, which is how v0.8.1 lost its release PR after
+          # everything else in the release had succeeded.
+          if PR=$(gh pr create --base main --head "$BRANCH" --title "release: v${NEW_VERSION} — automated weekly batch" --body-file /tmp/pr-body.md 2>/tmp/pr-err); then
+            gh pr merge --auto --squash "$PR"
+            echo "Release PR: $PR"
+          else
+            cat /tmp/pr-err
+            if grep -q 'not permitted to create or approve pull requests' /tmp/pr-err; then
+              echo "::error::GITHUB_TOKEN may not open a pull request: \"GitHub Actions is not permitted to create or approve pull requests\". The branch is pushed and correct; only the PR is missing. Fix it once, in Settings -> Actions -> General -> Workflow permissions, by ticking \"Allow GitHub Actions to create and approve pull requests\" (equivalently: gh api -X PUT repos/$GITHUB_REPOSITORY/actions/permissions/workflow -F default_workflow_permissions=read -F can_approve_pull_request_reviews=true), then re-run this workflow. Until then, open it by hand: gh pr create --base main --head $BRANCH"
+            else
+              echo "::error::gh pr create failed for $BRANCH — see the output above."
+            fi
+            exit 1
+          fi

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **A release that cannot open its pull request says why.** `GITHUB_TOKEN`
+  cannot call `createPullRequest` unless "Allow GitHub Actions to create and
+  approve pull requests" is enabled, and v0.8.1 hit exactly that: the branch,
+  the bump and the diff were all correct and the run still ended in a bare
+  `GraphQL: GitHub Actions is not permitted to create or approve pull
+  requests`. Both `scheduled-release.yml` and `release.yml`'s `homebrew-sha`
+  job now name the setting, give the one-line `gh api` equivalent and the
+  manual `gh pr create` fallback, and say what stays stale until it is fixed.
+  The failure is still a failure: the branch exists without a PR, and for the
+  formula `detect-version` keeps reporting the hash owed on every sweep.
+
+## [0.8.1] - 2026-09-18
+
+Automated weekly release — everything merged since `v0.8.0`.
+
+### Changed
+
+- fix(release): the release allow-list is derived, not retyped (#100)
+- fix(release): the weekly release verifies the tree it is about to ship (#99)
+- ci(release): set the Homebrew sha256 from the published tarball (#98)
+- chore(homebrew): sha256 for v0.8.0, from the published tarball (#97)
+
+
+### Fixed
+- **A release is no longer blocked by an allow-list that forgot one of its own
+  surfaces.** `sync-release-version.mjs` rewrites
+  `packaging/gitlab/testguard.gitlab-ci.yml`, and that path was missing from
+  both release guards: `scheduled-release.yml` would have failed with
+  "unexpected file in release diff" for a file the release exists to write,
+  and `auto-merge.yml` would have held every release PR for human review. The
+  script gained `--list-surfaces`, derived from the same table the writes use;
+  `scheduled-release.yml` now builds its allow-list from that instead of a
+  retyped copy. `auto-merge.yml` keeps an explicit list on purpose — it is the
+  gate that merges without review — and a test now fails when that list omits
+  any release surface. Claim `TG-RELEASE-SYNC-CHECK-FAILS-ON-DRIFT` gains a
+  fifth fault.
+- **The weekly release workflow can actually cut a release.** Its "verify the
+  tree is still green" step probed in worktree mode straight after syncing the
+  version surfaces, so the probe refused to run: the sync leaves
+  `packaging/gitlab/testguard.gitlab-ci.yml` uncommitted and that file is the
+  fault target of `TG-GITLAB-PROBE-EXIT-PRESERVED`, which worktree mode
+  correctly treats as a dirty defender (exit 2). It now probes with
+  `--include-dirty`, which verifies the bumped tree that is about to be
+  released rather than the version before it. `scheduled-release.yml` had
+  never completed a run since the GitLab template became both a sync surface
+  and a fault target on 2026-09-17; every release so far was cut by hand.
+- **The Homebrew formula's `sha256` matches its own `url`.** It had carried
+  `385d69f9…` unchanged across v0.6.0, v0.7.0 and v0.8.0 while
+  `release:sync` bumped the `url` each time — a hash that matches none of
+  the 0.4.0–0.7.0 tarballs, so `brew install` from the staged formula could
+  never have verified. Set to the sha256 of the published
+  `testguard-cli-0.8.0.tgz` (`5305ce22…`), computed from the registry, not
+  from a local `npm pack`.
+- **`release.yml` sets the Homebrew `sha256` itself, after publishing to npm.**
+  The formula header used to tell a human to run `curl | shasum` each release,
+  and nobody did. `sync-release-version.mjs --sha256` now waits for the
+  registry to serve the tarball (a publish is `PUT 202`; the file can lag by
+  minutes), hashes exactly the bytes Homebrew will download, and writes the
+  formula only when the value changes; a `200` that is not a gzip tarball is
+  refused, never hashed. `main` is protected, so the change lands as a bot PR
+  with auto-merge armed and CI dispatched by the workflow. The hash is a
+  release surface like the URL beside it: `detect-version` compares the
+  formula against the tarball (`--check --online`) on every hourly sweep, so
+  a failed run is retried the way a failed publish is, and `--check` refuses
+  the `385d69f9…` placeholder outright. Claim
+  `TG-RELEASE-SYNC-CHECK-FAILS-ON-DRIFT` gains three faults for the new modes.
+  Only the next release exercises the workflow path end to end.
+
 ## [0.8.0] - 2026-09-18
 
 A calibration you can quote.

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/CONTRIBUTING.md

@@ -81,6 +81,14 @@ on the fault.
 opens a release PR; merging it tags and publishes to npm and PyPI via OIDC
 Trusted Publishing. There are no tokens to rotate.
 
+The Homebrew formula's `sha256` is the one surface that cannot be known before
+publishing: `release.yml` sets it after `npm publish`, from the registry
+tarball (`sync-release-version.mjs --sha256`), and lands it as a bot PR with
+auto-merge armed — `main` is protected, so no job commits to it directly.
+`--check` (offline) refuses a placeholder hash; `--check --online` compares
+against the tarball and is what decides, on every hourly sweep, whether the
+formula is still owed.
+
 ## Licence
 
 MIT. By contributing you agree your contribution is licensed the same way.

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.8.0
+Version: 0.8.1
 Summary: Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest. Ships the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -150,9 +150,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.8.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.8.1` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.8.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.8.1/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -451,12 +451,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.8.0
+- uses: raccioly/testguard@v0.8.1
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.8.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.8.1/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/README.md

@@ -126,9 +126,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.8.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.8.1` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.8.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.8.1/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -427,12 +427,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.8.0
+- uses: raccioly/testguard@v0.8.1
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.8.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.8.1/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/action.yml

@@ -46,7 +46,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.8.0'
+    default: '0.8.1'
   node-version:
     description: 'Node.js version (20+)'
     required: false

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.8.0 → testguard_cli-0.8.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",