@biffo/cli 0.234.1 → 0.235.0

package/_skeletons/plugin-template/scripts/biffo.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env sh
+#
+# Run the Biffo CLI, from whichever copy is correct for this repo.
+#
+#   - **Template** (no `biffo.core.json`): the local `cli/` workspace, through
+#     tsx. The template develops the CLI, so its own CI has to exercise the code
+#     in the working tree — running the published package here would test the
+#     last release instead of the change under review, and a broken guard would
+#     go green and only fail after publish.
+#
+#   - **Instance** (`biffo.core.json` present): the published package, pinned to
+#     the core version this instance is actually on. Instances no longer carry
+#     `cli/` at all: it is 31k lines of a scaffolding tool they never develop
+#     and never deploy, and shipping it meant the template's own test suite ran
+#     in every tenant's CI — where a failure could not be fixed by the repo it
+#     failed in.
+#
+# Pinning to `biffo.core.json` rather than `@latest` keeps the guards in step
+# with the core the instance runs. An instance mid-upgrade is checked by the
+# version it is upgrading from, which is the one whose rules its tree follows.
+#
+# That last sentence is why the version is read from `HEAD` and not the working
+# tree (#667). `biffo core upgrade --apply` rewrites `biffo.core.json` to the
+# TARGET version before committing, so by the time the `commit-msg` hook runs
+# the working tree already names a version that, by definition, may not be
+# published yet:
+#
+#     npm error notarget No matching version found for @biffo/cli@0.133.1
+#     husky - commit-msg script failed (code 1)
+#
+# The upgrade then cannot be committed at all, and `--no-verify` does not help
+# because CI runs the same check. Reading HEAD judges the commit by the rules
+# the tree currently follows, and decouples committing an upgrade from whether
+# the target has reached npm yet.
+set -eu
+
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+
+# Satellites (sibling apps, plugin repos, runner fleets) carry neither
+# `biffo.core.json` nor `cli/`. They DO carry `.biffo-shared-version`, written
+# by `scripts/shared-sync.sh` and naming the template core version their shared
+# files came from — the same pin, under a different name.
+#
+# Without this branch a satellite fell through to the template's `pnpm --filter`
+# line and failed, so every guard a satellite ran had to be a COPIED shell
+# script kept in step by hand. That is the drift surface `shared-files.json`
+# exists to police: 16 files across 15 repos, roughly 240 copies, and about ten
+# of the estate's guards written to police them. Giving satellites the same
+# versioned CLI instances already use is what makes those copies unnecessary
+# (#1109).
+#
+# The tag form is `core-v0.231.2`; npm wants `0.231.2`.
+if [ ! -f biffo.core.json ] && [ -f .biffo-shared-version ]; then
+  shared=$(tr -d ' \t\n\r' < .biffo-shared-version)
+  version=${shared#core-v}
+  if [ -z "$version" ]; then
+    echo "biffo.sh: .biffo-shared-version is present but carries no readable version." >&2
+    exit 2
+  fi
+  exec npx --yes "@biffo/cli@$version" "$@"
+fi
+
+if [ -f biffo.core.json ]; then
+  # The committed record first. Falls through to the working tree when there is
+  # no HEAD yet (a fresh `biffo init`, before the first commit) or when the file
+  # is newly added and not yet in any commit.
+  version=$(git show HEAD:biffo.core.json 2>/dev/null |
+    node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version" 2>/dev/null || echo '')
+  if [ -z "$version" ] || [ "$version" = 'undefined' ]; then
+    version=$(node -p "require('./biffo.core.json').version" 2>/dev/null || echo '')
+  fi
+  if [ -z "$version" ] || [ "$version" = 'undefined' ]; then
+    echo "biffo.sh: biffo.core.json is present but carries no readable version." >&2
+    exit 2
+  fi
+  exec npx --yes "@biffo/cli@$version" "$@"
+fi
+
+# NOT `pnpm --filter @biffo/cli exec tsx ...`: `pnpm exec` normalises every
+# non-zero exit to 1. Verified — the CLI exits 2 and pnpm reports 1.
+#
+# That silently flattened the exit code of every guard this bridge runs in the
+# template, and it matters now because the estate's conventions are built on a
+# THREE-valued contract: 0 green, 1 failed, **2 cannot tell**, where 2 is never
+# a pass (`wait-for-checks.sh`, `branch-health.sh`, `claim.sh`). Collapsing 2
+# into 1 turns "I could not tell" into "it failed", which is the safe direction
+# by luck rather than design — and the reverse collapse would be a fail-open.
+#
+# `exec` on the binary directly keeps the child's status as this script's own.
+exec "$root/cli/node_modules/.bin/tsx" "$root/cli/src/index.ts" "$@"

package/_skeletons/sibling-template/scripts/biffo.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env sh
+#
+# Run the Biffo CLI, from whichever copy is correct for this repo.
+#
+#   - **Template** (no `biffo.core.json`): the local `cli/` workspace, through
+#     tsx. The template develops the CLI, so its own CI has to exercise the code
+#     in the working tree — running the published package here would test the
+#     last release instead of the change under review, and a broken guard would
+#     go green and only fail after publish.
+#
+#   - **Instance** (`biffo.core.json` present): the published package, pinned to
+#     the core version this instance is actually on. Instances no longer carry
+#     `cli/` at all: it is 31k lines of a scaffolding tool they never develop
+#     and never deploy, and shipping it meant the template's own test suite ran
+#     in every tenant's CI — where a failure could not be fixed by the repo it
+#     failed in.
+#
+# Pinning to `biffo.core.json` rather than `@latest` keeps the guards in step
+# with the core the instance runs. An instance mid-upgrade is checked by the
+# version it is upgrading from, which is the one whose rules its tree follows.
+#
+# That last sentence is why the version is read from `HEAD` and not the working
+# tree (#667). `biffo core upgrade --apply` rewrites `biffo.core.json` to the
+# TARGET version before committing, so by the time the `commit-msg` hook runs
+# the working tree already names a version that, by definition, may not be
+# published yet:
+#
+#     npm error notarget No matching version found for @biffo/cli@0.133.1
+#     husky - commit-msg script failed (code 1)
+#
+# The upgrade then cannot be committed at all, and `--no-verify` does not help
+# because CI runs the same check. Reading HEAD judges the commit by the rules
+# the tree currently follows, and decouples committing an upgrade from whether
+# the target has reached npm yet.
+set -eu
+
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+
+# Satellites (sibling apps, plugin repos, runner fleets) carry neither
+# `biffo.core.json` nor `cli/`. They DO carry `.biffo-shared-version`, written
+# by `scripts/shared-sync.sh` and naming the template core version their shared
+# files came from — the same pin, under a different name.
+#
+# Without this branch a satellite fell through to the template's `pnpm --filter`
+# line and failed, so every guard a satellite ran had to be a COPIED shell
+# script kept in step by hand. That is the drift surface `shared-files.json`
+# exists to police: 16 files across 15 repos, roughly 240 copies, and about ten
+# of the estate's guards written to police them. Giving satellites the same
+# versioned CLI instances already use is what makes those copies unnecessary
+# (#1109).
+#
+# The tag form is `core-v0.231.2`; npm wants `0.231.2`.
+if [ ! -f biffo.core.json ] && [ -f .biffo-shared-version ]; then
+  shared=$(tr -d ' \t\n\r' < .biffo-shared-version)
+  version=${shared#core-v}
+  if [ -z "$version" ]; then
+    echo "biffo.sh: .biffo-shared-version is present but carries no readable version." >&2
+    exit 2
+  fi
+  exec npx --yes "@biffo/cli@$version" "$@"
+fi
+
+if [ -f biffo.core.json ]; then
+  # The committed record first. Falls through to the working tree when there is
+  # no HEAD yet (a fresh `biffo init`, before the first commit) or when the file
+  # is newly added and not yet in any commit.
+  version=$(git show HEAD:biffo.core.json 2>/dev/null |
+    node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version" 2>/dev/null || echo '')
+  if [ -z "$version" ] || [ "$version" = 'undefined' ]; then
+    version=$(node -p "require('./biffo.core.json').version" 2>/dev/null || echo '')
+  fi
+  if [ -z "$version" ] || [ "$version" = 'undefined' ]; then
+    echo "biffo.sh: biffo.core.json is present but carries no readable version." >&2
+    exit 2
+  fi
+  exec npx --yes "@biffo/cli@$version" "$@"
+fi
+
+# NOT `pnpm --filter @biffo/cli exec tsx ...`: `pnpm exec` normalises every
+# non-zero exit to 1. Verified — the CLI exits 2 and pnpm reports 1.
+#
+# That silently flattened the exit code of every guard this bridge runs in the
+# template, and it matters now because the estate's conventions are built on a
+# THREE-valued contract: 0 green, 1 failed, **2 cannot tell**, where 2 is never
+# a pass (`wait-for-checks.sh`, `branch-health.sh`, `claim.sh`). Collapsing 2
+# into 1 turns "I could not tell" into "it failed", which is the safe direction
+# by luck rather than design — and the reverse collapse would be a fail-open.
+#
+# `exec` on the binary directly keeps the child's status as this script's own.
+exec "$root/cli/node_modules/.bin/tsx" "$root/cli/src/index.ts" "$@"

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command26 } from "commander";
+import { Command as Command27 } from "commander";
 
 // src/commands/core.ts
 import { Command as Command4 } from "commander";
@@ -9684,8 +9684,8 @@ async function runOwnershipCheck(argv) {
     const { stdout } = await execa7("git", ["diff", "--cached", "--name-status"], { cwd: root });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
     if (messageFile) {
-      const { readFileSync: readFileSync28, existsSync: existsSync38 } = await import("fs");
-      if (existsSync38(messageFile)) commitMessage = readFileSync28(messageFile, "utf8");
+      const { readFileSync: readFileSync28, existsSync: existsSync39 } = await import("fs");
+      if (existsSync39(messageFile)) commitMessage = readFileSync28(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -10765,8 +10765,50 @@ function resolveGithubToken4() {
   );
 }
 
+// src/commands/wait-for-checks.ts
+import { spawnSync } from "child_process";
+import { dirname as dirname11 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+import { Command as Command26 } from "commander";
+
+// src/lib/packaged-scripts.ts
+import { existsSync as existsSync38 } from "fs";
+import { dirname as dirname10, join as join38 } from "path";
+function findPackagedScript(startDir, relativePath) {
+  let dir = startDir;
+  for (; ; ) {
+    const candidate = join38(dir, relativePath);
+    if (existsSync38(candidate)) return candidate;
+    const parent = dirname10(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function packagedScriptMissing(relativePath) {
+  return `biffo: cannot find ${relativePath}.
+It ships with this package via cli/scripts/packaged-root-assets.mjs; if you are running from a checkout, run from inside the template repo. If you are running the published package, this is a packaging bug \u2014 the asset was not copied at prepack.`;
+}
+
+// src/commands/wait-for-checks.ts
+var SCRIPT = "scripts/wait-for-checks.sh";
+var waitForChecksCommand = new Command26("wait-for-checks").description(
+  "Wait for a PR\u2019s required checks on a positive signal (0 green, 1 failed, 2 cannot tell)"
+).argument("<pr>", "Pull request number").allowExcessArguments(true).allowUnknownOption(true).action(() => {
+  const here = dirname11(fileURLToPath6(import.meta.url));
+  const script = findPackagedScript(here, SCRIPT);
+  if (!script) {
+    process.stderr.write(`${packagedScriptMissing(SCRIPT)}
+`);
+    process.exit(2);
+  }
+  const at = process.argv.indexOf("wait-for-checks");
+  const args = at === -1 ? [] : process.argv.slice(at + 1);
+  const result = spawnSync("sh", [script, ...args], { stdio: "inherit" });
+  process.exit(result.status === null ? 2 : result.status);
+});
+
 // src/index.ts
-var program = new Command26();
+var program = new Command27();
 function cliVersion() {
   try {
     return getLatestCoreVersion();
@@ -10779,6 +10821,7 @@ program.addCommand(initCommand);
 program.addCommand(deployCommand);
 program.addCommand(destroyCommand);
 program.addCommand(teardownCommand);
+program.addCommand(waitForChecksCommand);
 program.addCommand(pluginCommand);
 program.addCommand(dataCommand);
 program.addCommand(coreCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.234.1",
+  "version": "0.235.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,8 @@
   "files": [
     "dist",
     "schemas",
-    "_skeletons"
+    "_skeletons",
+    "scripts/wait-for-checks.sh"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",

package/scripts/wait-for-checks.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+#
+# Wait for a pull request's checks to finish, without mistaking "not started"
+# for "all green".
+#
+# ## Why this exists
+#
+# Every session hand-rolls this loop, and the natural formulation is wrong in
+# the dangerous direction:
+#
+#   until [ "$(gh pr checks "$N" | grep -c pending)" = 0 ]; do sleep 30; done
+#
+# That polls for the **absence** of pending work, so a transient empty set reads
+# as completion. Immediately after `gh pr update-branch` GitHub drops the
+# superseded check runs before registering the new ones — for a few seconds
+# there are **zero** checks, `pending` is 0, and the loop exits on a PR whose CI
+# has not started. The caller then merges. Observed on 2026-08-02 while clearing
+# a 13-repo queue; the same session also wrote an `until` whose `|| &&`
+# precedence never terminated and burned a full 10-minute timeout.
+#
+# That is the estate's dominant failure shape — a gate passing because it cannot
+# run — reproduced inside the agent's own tooling, where no CI guard can see it.
+#
+# ## The rule this encodes
+#
+# **Wait on a positive signal, never on the absence of a negative.** Two ways to
+# get one, strongest first:
+#
+# 1. **Branch protection's required contexts.** If the base branch is protected,
+#    those names are exactly the checks that MUST report, so "every required
+#    context has concluded" is a direct answer rather than an inference. This is
+#    the only condition that cannot be satisfied by an empty or half-registered
+#    set.
+# 2. **Stability, when protection is unreadable.** Some repos are unprotected
+#    (both plugin repos were until 2026-07-27) and a token may lack the scope to
+#    read protection. Then: at least one check present, all concluded, and the
+#    same count seen on two consecutive polls — so a fast check concluding while
+#    slower ones are still registering does not end the wait early.
+#
+# ## Exit codes, and why 2 exists
+#
+#   0  every required/observed check concluded, none failed
+#   1  a check failed — the names are printed
+#   2  cannot determine: timed out, no checks ever appeared, PR unreadable
+#
+# 2 is distinct from 1 on purpose, and neither is 0. A timeout is not a pass,
+# and a caller that treats "cannot tell" as "green" has rebuilt the defect this
+# script exists to prevent. `ci-wiring-audit.sh` uses the same 2-means-cannot-run
+# convention.
+#
+# `cancelled` is reported separately rather than as a failure: on this estate's
+# self-hosted runners a cancelled job is usually spot reclamation or a
+# `cancel-in-progress` concurrency group, not the code. It still exits 1 —
+# something must be re-run — but the message says which, so nobody debugs a
+# phantom.
+#
+# ## Usage
+#
+#   sh scripts/wait-for-checks.sh <pr-number> [-R owner/repo]
+#                                 [--timeout SECONDS] [--interval SECONDS]
+#
+# Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary is needed.
+
+set -uo pipefail
+
+PR=""
+REPO=""
+TIMEOUT="${WAIT_FOR_CHECKS_TIMEOUT:-1800}"
+INTERVAL="${WAIT_FOR_CHECKS_INTERVAL:-30}"
+
+usage() {
+  sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'
+  exit 2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R | --repo)
+      REPO="${2:-}"
+      shift 2
+      ;;
+    --timeout)
+      TIMEOUT="${2:-}"
+      shift 2
+      ;;
+    --interval)
+      INTERVAL="${2:-}"
+      shift 2
+      ;;
+    -h | --help) usage ;;
+    *)
+      PR="$1"
+      shift
+      ;;
+  esac
+done
+
+[ -n "$PR" ] || {
+  echo "wait-for-checks: no PR number given" >&2
+  usage
+}
+
+RED=$(printf '\033[31m')
+GREEN=$(printf '\033[32m')
+DIM=$(printf '\033[90m')
+OFF=$(printf '\033[0m')
+
+gh_pr() {
+  if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi
+}
+
+gh_api() {
+  gh api "$@" 2>/dev/null
+}
+
+# --- What is this PR, and is there anything to wait for? ----------------------
+
+meta=$(gh_pr view "$PR" --json state,baseRefName --jq '"\(.state)\t\(.baseRefName)"') || {
+  echo "${RED}wait-for-checks: cannot read PR $PR${OFF}" >&2
+  exit 2
+}
+state=${meta%%	*}
+base=${meta##*	}
+
+case "$state" in
+  MERGED | CLOSED)
+    echo "${DIM}PR $PR is $state — nothing to wait for.${OFF}"
+    exit 0
+    ;;
+esac
+
+# --- Signal 1: the checks branch protection says MUST report ------------------
+
+owner_repo="$REPO"
+[ -n "$owner_repo" ] || owner_repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null)
+
+required=""
+if [ -n "$owner_repo" ]; then
+  required=$(gh_api "repos/$owner_repo/branches/$base/protection" \
+    --jq '.required_status_checks.contexts[]?' | sort -u)
+fi
+
+if [ -n "$required" ]; then
+  echo "${DIM}Waiting on $(echo "$required" | wc -l | tr -d ' ') required check(s) on $base.${OFF}"
+else
+  # Not an error. An unprotected branch is a real configuration, and a token
+  # without the scope to read protection is common. Say which mode is in use, so
+  # a weaker guarantee is never mistaken for the strong one.
+  echo "${DIM}No readable branch protection on $base — falling back to stability.${OFF}"
+fi
+
+# --- Poll ---------------------------------------------------------------------
+
+deadline=$(($(date +%s) + TIMEOUT))
+prev_count=-1
+rollup=""
+
+while :; do
+  rollup=$(gh_pr view "$PR" --json statusCheckRollup --jq '
+    [ .statusCheckRollup[]?
+      | { name:  (.name // .context),
+          state: (.conclusion // .state // (if .status == "COMPLETED" then "" else null end))
+        }
+    ] | .[] | "\(.name)\t\(.state // "")"') || rollup=""
+
+  count=0
+  [ -n "$rollup" ] && count=$(printf '%s\n' "$rollup" | grep -c .)
+
+  # Every check that has reported a terminal state.
+  concluded=$(printf '%s\n' "$rollup" | awk -F'\t' 'NF && $2 != "" && $2 != "PENDING" && $2 != "IN_PROGRESS" && $2 != "QUEUED" && $2 != "WAITING" { print $1 }')
+
+  done_waiting=0
+
+  if [ -n "$required" ]; then
+    # Strong condition: every required context is present AND concluded.
+    missing=""
+    while IFS= read -r ctx; do
+      [ -n "$ctx" ] || continue
+      printf '%s\n' "$concluded" | grep -Fxq "$ctx" || missing="$missing $ctx"
+    done <<EOF
+$required
+EOF
+    [ -z "$missing" ] && done_waiting=1
+  else
+    # Fallback: at least one check, all concluded, and the set has stopped
+    # growing. The count check is what stops a fast Secret Scan concluding alone
+    # while five slower jobs are still being registered.
+    if [ "$count" -gt 0 ]; then
+      n_concluded=$(printf '%s\n' "$concluded" | grep -c .)
+      if [ "$n_concluded" = "$count" ] && [ "$count" = "$prev_count" ]; then
+        done_waiting=1
+      fi
+    fi
+  fi
+
+  [ "$done_waiting" = "1" ] && break
+
+  prev_count=$count
+
+  now=$(date +%s)
+  if [ "$now" -ge "$deadline" ]; then
+    echo "${RED}wait-for-checks: timed out after ${TIMEOUT}s.${OFF}" >&2
+    if [ "$count" = "0" ]; then
+      # The exact case the naive loop gets wrong, so name it explicitly.
+      echo "No checks ever appeared on PR $PR. That is 'cannot tell', not 'green'." >&2
+    else
+      echo "Still unfinished:" >&2
+      printf '%s\n' "$rollup" | awk -F'\t' 'NF && ($2 == "" || $2 == "PENDING" || $2 == "IN_PROGRESS" || $2 == "QUEUED" || $2 == "WAITING") { print "  " $1 }' >&2
+    fi
+    exit 2
+  fi
+
+  sleep "$INTERVAL"
+done
+
+# --- Report -------------------------------------------------------------------
+
+failed=$(printf '%s\n' "$rollup" | awk -F'\t' 'NF && ($2 == "FAILURE" || $2 == "TIMED_OUT" || $2 == "ACTION_REQUIRED" || $2 == "STARTUP_FAILURE" || $2 == "ERROR") { print "  " $1 " (" $2 ")" }')
+cancelled=$(printf '%s\n' "$rollup" | awk -F'\t' 'NF && $2 == "CANCELLED" { print "  " $1 }')
+
+if [ -n "$cancelled" ]; then
+  echo "${RED}Cancelled:${OFF}"
+  printf '%s\n' "$cancelled"
+  echo "${DIM}A cancelled check is usually infrastructure (spot reclamation, or a" >&2
+  echo "cancel-in-progress concurrency group), not your code. Re-run it rather" >&2
+  echo "than debugging a phantom.${OFF}" >&2
+fi
+
+if [ -n "$failed" ]; then
+  echo "${RED}Failed:${OFF}"
+  printf '%s\n' "$failed"
+  exit 1
+fi
+
+[ -n "$cancelled" ] && exit 1
+
+echo "${GREEN}All checks concluded, none failed.${OFF}"
+exit 0