@biffo/cli 0.249.3 → 0.249.5

package/_skeletons/plugin-template/.githooks/pre-push

@@ -35,11 +35,22 @@ fi
 root=$(git rev-parse --show-toplevel) || exit 0
 cd "$root" || exit 0
 
-# The rewrite-scope guard runs FIRST, and it is the only thing here that needs
-# the ref list git puts on stdin (<local ref> <local sha> <remote ref>
-# <remote sha>). verify.sh reads no stdin, so consuming it here costs nothing —
-# but it does mean this must run before the `exec` below, which replaces the
-# process entirely.
+# git puts the ref list (<local ref> <local sha> <remote ref> <remote sha>, one
+# line per ref) on this process's stdin, ONCE. Two things below need it --
+# rewrite-scope-check and the pg-test block gate -- and a pipe can only be read
+# once, so it is captured to a file here and each consumer is fed from that
+# file instead of the real stdin. Falling back to no capture (each reader gets
+# whatever is left of the real stdin, i.e. nothing for the second one) rather
+# than failing the push if a temp file cannot be created: this hook's job is to
+# run checks, not to invent a new way to block a push that has nothing to do
+# with any of them.
+REFS_FILE=$(mktemp) || REFS_FILE=""
+if [ -n "$REFS_FILE" ]; then
+  cat >"$REFS_FILE"
+  trap 'rm -f "$REFS_FILE"' EXIT HUP INT TERM
+fi
+
+# The rewrite-scope guard runs FIRST.
 #
 # Why it exists: a force-push can quietly add a file to a branch's change set
 # and record a stale copy of somebody else's merged work as your own change.
@@ -51,7 +62,11 @@ cd "$root" || exit 0
 # the file was the one where nothing checked. There is no absent case now --
 # the bridge resolves the script from the package -- and if the bridge itself
 # cannot run, that is a reason to stop, not to wave the push through.
-sh scripts/biffo.sh rewrite-scope-check || exit 1
+if [ -n "$REFS_FILE" ]; then
+  sh scripts/biffo.sh rewrite-scope-check <"$REFS_FILE" || exit 1
+else
+  sh scripts/biffo.sh rewrite-scope-check || exit 1
+fi
 
 # --- Claim guard (#1231 instance 2) -------------------------------------------
 #
@@ -94,6 +109,42 @@ if [ -n "$branch" ]; then
   # exit 1 instead, if you would rather block than guess.
 fi
 
+# --- pg-test block gate (#656) -------------------------------------------
+#
+# verify.sh already reports `pg-test` as `APPLICABLE BUT NOT RUN` when the repo
+# has Postgres-dependent tests and no DSN reached it, and tries to provision one
+# itself via `scripts/biffo.sh pg-test-db` before giving up. That is honest and
+# often self-healing -- but it surfaced on a push that was ENTIRELY RLS policy
+# DDL, where the lane still did not run and the push still went through amber.
+# A wall of green `OK` lines does not make a person weight one amber line
+# correctly at 5pm, and CI treats this lane as required, so a local pass that
+# quietly skipped it is not the thing it looks like.
+#
+# So: if this push touches `db/imports/**` or a `*_pg.py` module -- the
+# convention `scripts/pg-test-db.sh` and verify.sh's own module discovery both
+# use -- and verify.sh still cannot run the lane, block rather than warn.
+# `BIFFO_PGTEST_DIFF_RELEVANT=1` is how that intent reaches verify.sh; it makes
+# no decision itself, `scripts/pgtest-diff-check.sh` (through the same bridge
+# as rewrite-scope-check) does, from the same ref list captured above.
+#
+# Deliberately narrow: an ordinary frontend push touches none of those paths,
+# so `pgtest-diff-check` exits 1 and nothing here changes. A repo whose
+# integration branch cannot be resolved, or that got no ref list at all, exits
+# 2 -- "could not tell" -- and this does NOT block on that, the same posture
+# `rewrite-scope-check` and `claim.sh --guard` take on their own blind spots: a
+# coordination-shaped check that fails closed on not knowing teaches people to
+# route around it, which is the opposite of what a gate is for.
+#
+# `BIFFO_SKIP_PGTEST=1`, checked here rather than only inside verify.sh, is the
+# deliberate escape hatch AGENTS.md section 7 requires for loosening a gate --
+# in the open, not by reaching for `--no-verify` and skipping every other check
+# too.
+if [ -z "${BIFFO_SKIP_PGTEST:-}" ] && [ -n "$REFS_FILE" ]; then
+  if sh scripts/biffo.sh pgtest-diff-check <"$REFS_FILE"; then
+    export BIFFO_PGTEST_DIFF_RELEVANT=1
+  fi
+fi
+
 # Through the version-pinned CLI since #1109, so a repo cannot run a gate two
 # versions old -- eight of them did, and tabsii-crm checked ONE thing in eight
 # on a 700-line change and printed `verify passed` (#855). There is one copy of

package/_skeletons/sibling-template/.githooks/pre-push

@@ -35,11 +35,22 @@ fi
 root=$(git rev-parse --show-toplevel) || exit 0
 cd "$root" || exit 0
 
-# The rewrite-scope guard runs FIRST, and it is the only thing here that needs
-# the ref list git puts on stdin (<local ref> <local sha> <remote ref>
-# <remote sha>). verify.sh reads no stdin, so consuming it here costs nothing —
-# but it does mean this must run before the `exec` below, which replaces the
-# process entirely.
+# git puts the ref list (<local ref> <local sha> <remote ref> <remote sha>, one
+# line per ref) on this process's stdin, ONCE. Two things below need it --
+# rewrite-scope-check and the pg-test block gate -- and a pipe can only be read
+# once, so it is captured to a file here and each consumer is fed from that
+# file instead of the real stdin. Falling back to no capture (each reader gets
+# whatever is left of the real stdin, i.e. nothing for the second one) rather
+# than failing the push if a temp file cannot be created: this hook's job is to
+# run checks, not to invent a new way to block a push that has nothing to do
+# with any of them.
+REFS_FILE=$(mktemp) || REFS_FILE=""
+if [ -n "$REFS_FILE" ]; then
+  cat >"$REFS_FILE"
+  trap 'rm -f "$REFS_FILE"' EXIT HUP INT TERM
+fi
+
+# The rewrite-scope guard runs FIRST.
 #
 # Why it exists: a force-push can quietly add a file to a branch's change set
 # and record a stale copy of somebody else's merged work as your own change.
@@ -51,7 +62,11 @@ cd "$root" || exit 0
 # the file was the one where nothing checked. There is no absent case now --
 # the bridge resolves the script from the package -- and if the bridge itself
 # cannot run, that is a reason to stop, not to wave the push through.
-sh scripts/biffo.sh rewrite-scope-check || exit 1
+if [ -n "$REFS_FILE" ]; then
+  sh scripts/biffo.sh rewrite-scope-check <"$REFS_FILE" || exit 1
+else
+  sh scripts/biffo.sh rewrite-scope-check || exit 1
+fi
 
 # --- Claim guard (#1231 instance 2) -------------------------------------------
 #
@@ -94,6 +109,42 @@ if [ -n "$branch" ]; then
   # exit 1 instead, if you would rather block than guess.
 fi
 
+# --- pg-test block gate (#656) -------------------------------------------
+#
+# verify.sh already reports `pg-test` as `APPLICABLE BUT NOT RUN` when the repo
+# has Postgres-dependent tests and no DSN reached it, and tries to provision one
+# itself via `scripts/biffo.sh pg-test-db` before giving up. That is honest and
+# often self-healing -- but it surfaced on a push that was ENTIRELY RLS policy
+# DDL, where the lane still did not run and the push still went through amber.
+# A wall of green `OK` lines does not make a person weight one amber line
+# correctly at 5pm, and CI treats this lane as required, so a local pass that
+# quietly skipped it is not the thing it looks like.
+#
+# So: if this push touches `db/imports/**` or a `*_pg.py` module -- the
+# convention `scripts/pg-test-db.sh` and verify.sh's own module discovery both
+# use -- and verify.sh still cannot run the lane, block rather than warn.
+# `BIFFO_PGTEST_DIFF_RELEVANT=1` is how that intent reaches verify.sh; it makes
+# no decision itself, `scripts/pgtest-diff-check.sh` (through the same bridge
+# as rewrite-scope-check) does, from the same ref list captured above.
+#
+# Deliberately narrow: an ordinary frontend push touches none of those paths,
+# so `pgtest-diff-check` exits 1 and nothing here changes. A repo whose
+# integration branch cannot be resolved, or that got no ref list at all, exits
+# 2 -- "could not tell" -- and this does NOT block on that, the same posture
+# `rewrite-scope-check` and `claim.sh --guard` take on their own blind spots: a
+# coordination-shaped check that fails closed on not knowing teaches people to
+# route around it, which is the opposite of what a gate is for.
+#
+# `BIFFO_SKIP_PGTEST=1`, checked here rather than only inside verify.sh, is the
+# deliberate escape hatch AGENTS.md section 7 requires for loosening a gate --
+# in the open, not by reaching for `--no-verify` and skipping every other check
+# too.
+if [ -z "${BIFFO_SKIP_PGTEST:-}" ] && [ -n "$REFS_FILE" ]; then
+  if sh scripts/biffo.sh pgtest-diff-check <"$REFS_FILE"; then
+    export BIFFO_PGTEST_DIFF_RELEVANT=1
+  fi
+fi
+
 # Through the version-pinned CLI since #1109, so a repo cannot run a gate two
 # versions old -- eight of them did, and tabsii-crm checked ONE thing in eight
 # on a 700-line change and printed `verify passed` (#855). There is one copy of

package/dist/index.js

@@ -10849,6 +10849,13 @@ var pgTestDbCommand = packagedScriptCommand({
   description: "Provision the local Postgres test database and print its DSN"
 });
 
+// src/commands/pgtest-diff-check.ts
+var pgtestDiffCheckCommand = packagedScriptCommand({
+  name: "pgtest-diff-check",
+  script: "scripts/pgtest-diff-check.sh",
+  description: "Report whether the push touches db/imports/** or a *_pg.py module"
+});
+
 // src/commands/rewrite-scope-check.ts
 var rewriteScopeCheckCommand = packagedScriptCommand({
   name: "rewrite-scope-check",
@@ -10921,6 +10928,7 @@ program.addCommand(gateCoverageCommand);
 program.addCommand(runnerDropForensicsCommand);
 program.addCommand(hookAuditCommand);
 program.addCommand(pgTestDbCommand);
+program.addCommand(pgtestDiffCheckCommand);
 program.addCommand(rewriteScopeCheckCommand);
 program.addCommand(pluginCommand);
 program.addCommand(dataCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.249.3",
+  "version": "0.249.5",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,7 @@
     "scripts/hook-audit.sh",
     "scripts/pg-test-db.sh",
     "scripts/rewrite-scope-check.sh",
+    "scripts/pgtest-diff-check.sh",
     "scripts/gate-coverage.sh",
     "scripts/verify.sh",
     "scripts/runner-drop-forensics.mjs",

package/scripts/pgtest-diff-check.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env sh
+# Does the push about to happen touch the paths that make the real-Postgres
+# lane matter — `db/imports/**` or a `*_pg.py` module?
+#
+# ## Why this exists (tabsii-platform#656)
+#
+# `scripts/verify.sh` already reports `pg-test` as `APPLICABLE BUT NOT RUN`
+# when the repo has Postgres-dependent tests and no DSN reached it — an honest
+# amber line, not a silent pass. It surfaced on a change that was ENTIRELY RLS
+# policy DDL: the gate is least useful exactly where the diff most needs it,
+# and a human reading a wall of green `OK` lines does not weight one amber line
+# at 5pm.
+#
+# `verify.sh` cannot answer "is this push worth blocking over?" by itself —
+# that question is about the commits being PUSHED, and a plain
+# `sh scripts/biffo.sh verify` run by hand has no ref list at all. Only
+# `.githooks/pre-push` sees that, on stdin, in the same
+# `<local ref> <local sha> <remote ref> <remote sha>` form `rewrite-scope-check`
+# reads. This script answers that one question so the hook can decide whether
+# to escalate verify.sh's amber warning into a block.
+#
+# ## What it deliberately does NOT do
+#
+# It does not run the lane, provision a database, or decide whether to block —
+# `verify.sh` already tries to self-provision (`scripts/biffo.sh pg-test-db`),
+# and blocking is the hook's call, made by exporting
+# `BIFFO_PGTEST_DIFF_RELEVANT` before `exec`ing verify. This is a narrow
+# predicate: which files changed, on the paths that matter, nothing else.
+#
+# ## Exit codes
+#
+# 0 — the push touches a relevant path.
+# 1 — it does not (the ordinary case; most pushes are not DDL).
+# 2 — could not tell (no integration branch resolvable, no stdin, shallow
+#     history). Reported on stderr and treated as "do not block" by the
+#     caller, the same posture `rewrite-scope-check.sh` and `claim.sh --guard`
+#     take when their own inputs are unavailable — a coordination-shaped gate
+#     that fails closed on its OWN blind spot teaches people to route around
+#     it, and this estate has that lesson recorded more than once.
+
+set -u
+
+ZERO=0000000000000000000000000000000000000000
+PATTERN='(^|/)db/imports/|_pg\.py$'
+
+note() { printf 'pgtest-diff-check: %s\n' "$1" >&2; }
+
+integration=""
+for candidate in dev main master; do
+  if git rev-parse --verify --quiet "refs/remotes/origin/$candidate" >/dev/null 2>&1; then
+    integration="origin/$candidate"
+    break
+  fi
+done
+
+# Collected through a file rather than a variable, for the same reason
+# rewrite-scope-check.sh does: the read loop below cannot assign to a variable
+# in the parent shell once it is fed from a pipe. One line per ref: `hit` (this
+# ref touches a relevant path), `indeterminate` (could not compute its range),
+# or nothing (ref checked, not relevant).
+RESULT_FILE=$(mktemp) || {
+  note "could not create a temp file - could not tell"
+  exit 2
+}
+trap 'rm -f "$RESULT_FILE"' EXIT HUP INT TERM
+
+saw_ref=0
+while read -r _local_ref local_sha _remote_ref remote_sha; do
+  [ -z "${local_sha:-}" ] && continue
+  saw_ref=1
+  # Branch deletion: nothing is being pushed.
+  [ "$local_sha" = "$ZERO" ] && continue
+
+  range=""
+  if [ "$remote_sha" != "$ZERO" ] && git cat-file -e "$remote_sha^{commit}" 2>/dev/null; then
+    # The ordinary case: compare against what the remote tip actually holds.
+    range="$remote_sha..$local_sha"
+  elif [ -n "$integration" ]; then
+    # A brand-new branch, or a remote tip we do not have locally (shallow
+    # clone, pruned object). Fall back to "everything this branch adds since
+    # it forked from the integration branch" — the same shape a reviewer would
+    # see in the PR diff.
+    base=$(git merge-base "$local_sha" "$integration" 2>/dev/null) || base=""
+    [ -n "$base" ] && range="$base..$local_sha"
+  fi
+
+  if [ -z "$range" ]; then
+    echo indeterminate >>"$RESULT_FILE"
+    continue
+  fi
+
+  if git diff --name-only "$range" 2>/dev/null | grep -qE "$PATTERN"; then
+    echo hit >>"$RESULT_FILE"
+  fi
+done
+
+if [ "$saw_ref" -eq 0 ]; then
+  note "no ref list on stdin - could not tell"
+  exit 2
+fi
+
+if grep -qx hit "$RESULT_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+if grep -qx indeterminate "$RESULT_FILE" 2>/dev/null; then
+  note "could not resolve one or more refs' range - could not tell"
+  exit 2
+fi
+
+exit 1

package/scripts/verify.sh

@@ -757,6 +757,39 @@ elif [ -z "$PG_TEST_DSN" ]; then
       "CI runs these as a required check; nothing local is checking them."
     printf '       \033[90m%s\033[0m\n' \
       "set BIFFO_TEST_PG_DSN, or run scripts/pg-test-db.sh if this repo ships one"
+
+    # --- Block on a relevant diff (tabsii-platform#656) --------------------
+    #
+    # The line above is honest -- it says NOT RUN, not passing -- but that is
+    # not enough on its own: it does not block, and a wall of green `OK` lines
+    # trains a reader not to weight one amber line correctly. It surfaced on a
+    # push that was ENTIRELY RLS policy DDL, exactly the diff this lane exists
+    # to check.
+    #
+    # `BIFFO_PGTEST_DIFF_RELEVANT` is set by `.githooks/pre-push`, never by a
+    # developer -- it is the hook's answer to "does this push touch
+    # db/imports/** or a *_pg.py module?", computed from the actual ref list
+    # via `scripts/pgtest-diff-check.sh`. A plain `sh scripts/biffo.sh verify`
+    # run by hand therefore stays advisory, exactly as before: this variable is
+    # only ever present when the hook itself decided the diff warranted it.
+    #
+    # `BIFFO_SKIP_PGTEST` is checked again here, not only in the hook, so this
+    # is provable by driving verify.sh directly (see verify-pg-lane.test.ts)
+    # and so a developer who sets it before invoking verify.sh by hand gets the
+    # same escape hatch the hook advertises.
+    if [ -n "${BIFFO_PGTEST_DIFF_RELEVANT:-}" ] && [ -z "${BIFFO_SKIP_PGTEST:-}" ]; then
+      FAILED="$FAILED pg-test-required"
+      printf '\n'
+      printf '  \033[31mBLOCKED\033[0m: this push touches db/imports/** or a *_pg.py module, and\n'
+      printf '  the pg-test lane above did not run. CI treats it as a required check, so a\n'
+      printf '  push here would report green without having checked the thing most likely\n'
+      printf '  to need it.\n\n'
+      printf '  Get a DSN and re-run:\n'
+      printf '    eval "$(sh scripts/pg-test-db.sh --export)"   # if this repo ships one\n'
+      printf '    export BIFFO_TEST_PG_DSN=postgresql+asyncpg://user:pass@host:port/db\n\n'
+      printf '  Deliberate escape hatch, printed rather than silent (AGENTS.md section 7):\n'
+      printf '    BIFFO_SKIP_PGTEST=1 git push ...\n\n'
+    fi
   fi
 elif ! command -v uv >/dev/null 2>&1; then
   skip pg-test "uv not installed"