@biffo/cli 0.236.0 → 0.238.0

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

@@ -1,208 +0,0 @@
-#!/usr/bin/env sh
-#
-# Is anyone already working this issue? Ask git, not a label.
-#
-# ## Why this exists
-#
-# Several agent sessions run against this estate at once, and on 2026-08-03
-# **four** of them collided in one morning:
-#
-#   - #1165 — another session built AND MERGED a PR for it while this one was
-#     claiming it. Three minutes, start to merge.
-#   - #1174 — a live worktree on `fix/1174-…` existed; the issue was unlabelled.
-#   - #621, #956 — live worktrees, no labels. Labelled on their behalf.
-#   - #1188 — the reverse: a label with no work, while another session built it
-#     and opened a PR.
-#
-# Three of the four were "work exists, label does not". That is the shape this
-# script is for.
-#
-# ## The rule it encodes
-#
-# **The `in-progress` label is a hand-maintained second copy of something git
-# already knows.** A branch exists. A PR exists. Those are automatic — you
-# cannot do the work without creating them — whereas the label is a separate
-# action a human or agent has to remember, in a workflow that may never have
-# been told to. Second copies of a decision drift; this estate says so about
-# `_extract_detail`, about AGENTS.md, and about the commit-msg type list.
-#
-# So this checks FOUR signals and reports all of them, rather than trusting the
-# one that is easiest to forget.
-#
-# ## What it cannot do
-#
-# Prevent a race. GitHub has no locking, two sessions can start in the same
-# second, and #1165 went from branch to merged in three minutes — no protocol
-# would have caught that. The goal is early, cheap detection, not exclusion.
-# Every collision that morning was caught before duplicate work merged; the
-# cost was minutes, not shipped rework.
-#
-# ## Usage
-#
-#   sh scripts/claim.sh 1234                 # check, and claim if free
-#   sh scripts/claim.sh 1234 --check         # report only, change nothing
-#   sh scripts/claim.sh 1234 -R owner/repo
-#
-#   0  free — and claimed, unless --check
-#   1  taken, or already closed — the reason is printed
-#   2  cannot tell — issue unreadable, gh unauthenticated
-#
-# 2 is deliberately not 0, matching `wait-for-checks.sh` and `branch-health.sh`.
-# A check that cannot see its input must not report "free".
-#
-# Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary needed.
-
-set -u
-
-ISSUE=""
-REPO=""
-CHECK_ONLY=""
-
-usage() {
-  sed -n '2,58p' "$0" | sed 's/^# \{0,1\}//'
-  exit 2
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    -R | --repo)
-      REPO="${2:-}"
-      shift 2
-      ;;
-    --check) CHECK_ONLY=1; shift ;;
-    -h | --help) usage ;;
-    *)
-      ISSUE="$1"
-      shift
-      ;;
-  esac
-done
-
-case "$ISSUE" in
-  '' | *[!0-9]*)
-    echo "claim: give an issue number, e.g. sh scripts/claim.sh 1234" >&2
-    exit 2
-    ;;
-esac
-
-RED=$(printf '\033[31m')
-GREEN=$(printf '\033[32m')
-YELLOW=$(printf '\033[33m')
-DIM=$(printf '\033[90m')
-OFF=$(printf '\033[0m')
-
-gh_issue() { if [ -n "$REPO" ]; then gh issue "$@" --repo "$REPO"; else gh issue "$@"; fi; }
-gh_pr() { if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi; }
-
-LABEL=in-progress
-TAKEN=0
-REASONS=""
-
-note() { REASONS="${REASONS}  $1\n"; TAKEN=1; }
-
-# --- 0. Does the issue exist, and is it still open? --------------------------
-
-meta=$(gh_issue view "$ISSUE" --json state,title,labels \
-  --jq '"\(.state)\t\(.title)\t\((.labels|map(.name)|join(",")))"' 2>/dev/null) || {
-  echo "${RED}claim: cannot read issue #$ISSUE${OFF} — wrong repo, or gh not authenticated." >&2
-  echo "${DIM}  That is 'cannot tell', not 'free'.${OFF}" >&2
-  exit 2
-}
-
-state=$(printf '%s' "$meta" | cut -f1)
-title=$(printf '%s' "$meta" | cut -f2)
-labels=$(printf '%s' "$meta" | cut -f3)
-
-echo "${DIM}#$ISSUE — $title${OFF}"
-echo
-
-if [ "$state" != "OPEN" ]; then
-  echo "${RED}Already $state.${OFF} Nothing to claim."
-  exit 1
-fi
-
-# --- 1. The label. Easiest to check, easiest to forget. ----------------------
-
-case ",$labels," in
-  *",$LABEL,"*)
-    updated=$(gh_issue view "$ISSUE" --json updatedAt --jq .updatedAt 2>/dev/null)
-    note "${YELLOW}label${OFF}      carries '$LABEL' (issue last updated $updated)"
-    ;;
-esac
-
-# --- 2. An open PR that references it ----------------------------------------
-#
-# The strongest signal, because a PR cannot be opened without the work existing.
-# Matches the issue number in the title or body as a whole number, so #118 does
-# not match #1188.
-
-open_prs=$(gh_pr list --state open --limit 100 --json number,title,body,headRefName \
-  --jq "[.[] | select(((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\")) or (.headRefName | test(\"(^|[^0-9])$ISSUE([^0-9]|\$)\")))] | .[] | \"#\(.number) \(.headRefName)\"" 2>/dev/null)
-
-if [ -n "$open_prs" ]; then
-  printf '%s\n' "$open_prs" | while IFS= read -r pr; do
-    [ -n "$pr" ] && echo "  ${RED}open PR${OFF}    $pr"
-  done
-  note "${RED}open PR${OFF}    see above — someone has working code"
-fi
-
-# --- 3. A remote branch naming it --------------------------------------------
-#
-# Catches work that has been pushed but has no PR yet. Whole-number match again.
-
-branches=$(git ls-remote --heads "${REPO:+https://github.com/$REPO.git}" 2>/dev/null |
-  sed 's|.*refs/heads/||' |
-  grep -E "(^|[^0-9])$ISSUE([^0-9]|$)" 2>/dev/null)
-
-if [ -n "$branches" ]; then
-  printf '%s\n' "$branches" | while IFS= read -r b; do
-    [ -n "$b" ] && echo "  ${RED}branch${OFF}     $b"
-  done
-  note "${RED}branch${OFF}     a remote branch names this issue"
-fi
-
-# --- 4. A recently merged PR that already closed it --------------------------
-#
-# Not "taken" — "possibly already done". #1165 was built and merged in three
-# minutes; the only trace afterwards is a merged PR.
-
-merged=$(gh_pr list --state merged --limit 30 --json number,title,body,mergedAt \
-  --jq "[.[] | select((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\"))] | .[0] | select(. != null) | \"#\(.number) merged \(.mergedAt[0:16])\"" 2>/dev/null)
-
-if [ -n "$merged" ]; then
-  echo "  ${YELLOW}merged${OFF}     $merged"
-  echo "  ${DIM}           the issue is still open, but work referencing it has landed —${OFF}"
-  echo "  ${DIM}           read it before rebuilding.${OFF}"
-fi
-
-# --- Verdict ------------------------------------------------------------------
-
-echo
-if [ "$TAKEN" -eq 1 ]; then
-  printf '%b' "${RED}Taken.${OFF} Signals:\n$REASONS"
-  echo
-  echo "${DIM}If you believe it is abandoned, check how old the work is and say so in a${OFF}"
-  echo "${DIM}comment before taking it. Never steal a fresh claim.${OFF}"
-  exit 1
-fi
-
-if [ -n "$CHECK_ONLY" ]; then
-  echo "${GREEN}Free.${OFF} ${DIM}(--check: nothing changed)${OFF}"
-  exit 0
-fi
-
-# Claim it. Label AND comment together: the label is what other sessions filter
-# on, the comment is what dates it so a stale claim can be recognised later.
-gh_issue edit "$ISSUE" --add-label "$LABEL" >/dev/null 2>&1 || {
-  echo "${RED}claim: could not apply the '$LABEL' label.${OFF}" >&2
-  echo "${DIM}  Not claimed. Do not start work on the assumption that it worked.${OFF}" >&2
-  exit 2
-}
-gh_issue comment "$ISSUE" \
-  --body "Claimed at $(date -u +%FT%TZ) by \`$(git config user.name 2>/dev/null || echo agent)\`. Release it — remove the label — on merge, or if you stop." \
-  >/dev/null 2>&1
-
-echo "${GREEN}Claimed.${OFF}"
-echo "${DIM}Push your branch as soon as it exists: a claim is a reservation, the branch${OFF}"
-echo "${DIM}is the evidence, and the window between them is where collisions happen.${OFF}"
-exit 0

package/_skeletons/sibling-template/scripts/hook-audit.sh

@@ -1,145 +0,0 @@
-#!/usr/bin/env bash
-#
-# Is a git hook actually going to execute here?
-#
-# ## Why this exists
-#
-# A configured hook that does not run is worse than no hook, because it is
-# assumed to be protecting you. On 2026-07-29 the estate was in exactly that
-# state: `core.hooksPath` pointed at `.husky/_`, a **gitignored** directory
-# created only by `prepare: husky` on `pnpm install` — and git resolves that
-# relative path against *each worktree's* root. Every fresh worktree therefore
-# had no hooks, and git said nothing: no warning, no error, no output.
-#
-# AGENTS.md §1 mandates a fresh worktree per unit of work, so the required
-# workflow disarmed its own gates. 6 of 32 working trees were armed. The pre-push
-# pyright, the pre-commit lint-staged and commitlint had all been silently
-# skipped in the other 26 for as long as anyone had been using worktrees.
-#
-# Nothing detected it because nothing looked. This is the thing that looks.
-#
-# ## Verdicts
-#
-#   ARMED     git will execute a hook here.
-#   DEAD      core.hooksPath is set and its target is missing or carries no
-#             hooks. Git skips silently. **This is the state that lies to you**,
-#             and the only one that makes this script exit non-zero.
-#   NO-HOOKS  no hooks configured at all. Honest, and visible in this report.
-#
-# Usage:
-#   sh scripts/hook-audit.sh                 # this repo and its worktrees
-#   sh scripts/hook-audit.sh --estate ~/code # every repo under a directory
-#   sh scripts/hook-audit.sh --quiet         # verdict counts only
-
-set -uo pipefail
-
-ESTATE=""
-QUIET=""
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --estate) ESTATE="$2"; shift 2 ;;
-    --quiet) QUIET=1; shift ;;
-    *) echo "unknown argument: $1" >&2; exit 2 ;;
-  esac
-done
-
-armed=0
-dead=0
-nohooks=0
-dead_list=""
-
-# The three hooks this standard cares about. A hooksPath directory containing
-# none of them is not armed for our purposes even if it holds something else.
-WANTED='^(pre-commit|pre-push|commit-msg)$'
-
-report() {
-  tree="$1"
-  label="$2"
-  hp=$(git -C "$tree" config core.hooksPath 2>/dev/null)
-
-  if [ -z "$hp" ]; then
-    # The default hooks directory is in the **common** git dir, which linked
-    # worktrees share. Reading "$tree/.git/hooks" is wrong for exactly the trees
-    # this audit exists to check: in a linked worktree `.git` is a *file*
-    # containing a gitdir pointer, so that path does not exist and every armed
-    # worktree was about to be reported NO-HOOKS. Ask git where it actually is.
-    #
-    # Git ships .sample files there that never execute, so counting the
-    # directory as armed merely for being non-empty would be exactly the false
-    # comfort this script exists to remove.
-    common=$(git -C "$tree" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
-    real=$(ls "${common:-$tree/.git}/hooks" 2>/dev/null | grep -vc '\.sample$' || true)
-    if [ "${real:-0}" -gt 0 ]; then
-      armed=$((armed + 1))
-      [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "(default)" "$real hook(s) in .git/hooks"
-    else
-      nohooks=$((nohooks + 1))
-      [ -n "$QUIET" ] || printf '%-56s %-14s \033[33mNO-HOOKS\033[0m %s\n' "$label" "(default)" "no hooks configured"
-    fi
-    return
-  fi
-
-  # Relative hooksPath resolves against the working tree root — the whole bug.
-  case "$hp" in
-    /*) dir="$hp" ;;
-    *) dir="$tree/$hp" ;;
-  esac
-
-  present=$(ls "$dir" 2>/dev/null | grep -E "$WANTED" | tr '\n' ',' || true)
-  if [ -z "$present" ]; then
-    dead=$((dead + 1))
-    dead_list="$dead_list  $label ($hp)
-"
-    [ -n "$QUIET" ] || printf '%-56s %-14s \033[31mDEAD\033[0m     %s\n' "$label" "$hp" "$hp missing or holds no hooks — git skips ALL hooks silently"
-  else
-    armed=$((armed + 1))
-    [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "$hp" "${present%,}"
-  fi
-}
-
-walk_repo() {
-  root="${1%/}"
-  name="$2"
-  # Every working tree, not just the primary — the primary is usually the one
-  # that IS armed, which is how this went unnoticed for so long.
-  git -C "$root" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2}' | while read -r t; do
-    [ -d "$t" ] || continue
-    if [ "$t" = "$root" ]; then echo "$t|$name"; else echo "$t|$name${t#$root}"; fi
-  done
-}
-
-[ -n "$QUIET" ] || printf '%-56s %-14s %-8s %s\n' "WORKING TREE" "hooksPath" "VERDICT" "detail"
-
-if [ -n "$ESTATE" ]; then
-  targets=$(for d in "$ESTATE"/*/; do
-    [ -e "$d/.git" ] || continue
-    walk_repo "$d" "$(basename "${d%/}")"
-  done)
-else
-  root=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "not a git repo" >&2; exit 2; }
-  # From inside a worktree, --show-toplevel gives the worktree; walk from the
-  # common repo so sibling worktrees are audited too.
-  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
-  root=$(dirname "$common")
-  targets=$(walk_repo "$root" "$(basename "$root")")
-fi
-
-while IFS='|' read -r tree label; do
-  [ -n "$tree" ] || continue
-  report "$tree" "$label"
-done <<EOF
-$targets
-EOF
-
-total=$((armed + dead + nohooks))
-printf '\n%s working trees — \033[32m%s armed\033[0m, \033[31m%s dead\033[0m, %s without hooks' "$total" "$armed" "$dead" "$nohooks"
-[ "$total" -gt 0 ] && printf ' (%s%% armed)' "$((100 * armed / total))"
-printf '\n'
-
-if [ "$dead" -gt 0 ]; then
-  printf '\n\033[31mDEAD working trees — hooks are configured here and are NOT running:\033[0m\n%s' "$dead_list"
-  printf 'Every commit and push made in these is unguarded, and nothing says so.\n'
-  printf 'Fix: run `pnpm install` there, or move the repo to tracked .githooks/.\n'
-  exit 1
-fi
-exit 0

package/_skeletons/sibling-template/scripts/pg-test-db.sh

@@ -1,275 +0,0 @@
-#!/usr/bin/env sh
-#
-# Give the Postgres-dependent test lane a database with a CURRENT schema, and
-# print its DSN.
-#
-# ## Why this exists
-#
-# `scripts/verify.sh` grew a `pg-test` check (#1089) because on 2026-08-02 nine
-# of thirteen locally-catchable failing CI steps across the estate were one
-# repo's real-Postgres lane -- a required check with no local counterpart at all.
-# But a gate can only run that lane against a database, and no repo documented
-# how to get one: no compose file, no script, no DSN written down. The container
-# that existed on the workstation had been created ad hoc in some earlier session
-# and held a scatter of scratch databases. That undocumented setup WAS the
-# fail-open, because a gate nobody can run is not a gate.
-#
-# ## Why freshness, not rebuild-every-time
-#
-# The expensive failure is not a slow rebuild, it is a STALE one. Measured on
-# tabsii-platform while writing this: a database built about an hour earlier,
-# before two PRs merged, produced **23 failures** in a module that had nothing to
-# do with the change in hand. Rebuilt from the same tree it passed 336/336, and
-# passed 336 again on an immediate re-run -- so the lane was genuinely
-# re-runnable and every one of those failures was the old schema.
-#
-# That is the worst shape a local gate can have. Twenty-three red tests that are
-# not your fault teach people the gate is unreliable, and an unreliable gate gets
-# bypassed -- which H4 pre-registered as the condition refuting the whole
-# local-gate programme. So the schema inputs are fingerprinted and a rebuild
-# happens only when they actually changed: reuse ~0.3s, rebuild ~4s.
-#
-# ## Why it is generic
-#
-# It adapts to the repo rather than being told about it, for the same reason
-# `verify.sh` does: forks drift, and a per-instance copy of this would drift from
-# the DDL layout it is meant to build. Everything instance-specific is DERIVED --
-# the schema directories from `db/imports/*/`, the engine image from whether the
-# DDL asks for PostGIS, and the did-it-build threshold from the number of
-# policies the DDL itself declares. Nothing here names a product.
-#
-# ## Usage
-#
-#   eval "$(sh scripts/pg-test-db.sh --export)"   # export BIFFO_TEST_PG_DSN
-#   sh scripts/pg-test-db.sh                      # print the DSN on stdout
-#   sh scripts/pg-test-db.sh --recreate           # force a rebuild
-#
-# Only the DSN reaches stdout, so it is safe to capture; progress goes to stderr.
-#
-# Overridable: BIFFO_PG_HOST, BIFFO_PG_PORT, BIFFO_PG_USER, BIFFO_PG_PASSWORD,
-# BIFFO_PG_DB, BIFFO_PG_CONTAINER, BIFFO_PG_IMAGE.
-#
-# ## Concurrency: derived, not coordinated
-#
-# The port, database name, and container name below default to values DERIVED
-# from this checkout's own path, not fixed constants. A fixed port
-# (`BIFFO_PG_PORT` used to default to `55432` everywhere) meant any two
-# checkouts running this script at the same time -- two worktrees of one repo,
-# or two entirely different repos on one machine -- attached to the SAME
-# Postgres cluster and raced on cluster-wide catalogs like `pg_shdepend`
-# (#1114). A fixed database name (`biffo_test`) meant they then shared one
-# database on top of that (#1120).
-#
-# The fix is not a lock: a machine-wide `flock` around this script would make
-# concurrent runs correct by serializing them, but that is coordination, and
-# this estate's shared-mutable-state defects have twice been solved instead by
-# making the value itself unique per user rather than making users take turns.
-# Deriving from `$REPO_ROOT` gets that for free -- it is already different for
-# every worktree and every repo -- and deterministically, so repeat runs
-# against the SAME checkout still land on the same port/db/container and reuse
-# the fingerprinted schema (see step 2 below) instead of rebuilding it under a
-# fresh identity every time. `BIFFO_PG_PORT`, `BIFFO_PG_DB`, and
-# `BIFFO_PG_CONTAINER` remain explicit overrides; only the *default* changed.
-
-set -eu
-
-REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd)
-
-# sha256sum is already a dependency of this script (see `fingerprint` below),
-# so reusing it here for a deterministic, cheap per-checkout key adds nothing
-# new to install. 12 hex chars is ample to keep collisions between checkouts
-# on one machine practically impossible while staying short enough to read in
-# `docker ps` output and a psql prompt.
-_checkout_key=$(printf '%s' "$REPO_ROOT" | sha256sum | cut -c1-12)
-_checkout_suffix=$(printf '%s' "$_checkout_key" | cut -c1-8)
-# IANA's dynamic/private port range (49152-65535, 16384 ports) mapped from the
-# next 4 hex chars of the same hash -- an ephemeral port picked deterministically
-# rather than asked of the OS, because a freshly-random port on every invocation
-# would break the reuse this key is for (a second run against the same checkout
-# has to land back on the same container to find its existing database).
-_checkout_port=$((49152 + (0x$(printf '%s' "$_checkout_key" | cut -c9-12) % 16384)))
-
-HOST="${BIFFO_PG_HOST:-localhost}"
-PORT="${BIFFO_PG_PORT:-$_checkout_port}"
-USER_="${BIFFO_PG_USER:-postgres}"
-PASS="${BIFFO_PG_PASSWORD:-postgres}"
-DB="${BIFFO_PG_DB:-biffo_test_$_checkout_suffix}"
-# Keyed the same way as PORT and for the same reason: the container is where
-# the port mapping actually lives (`docker run -p "$PORT:5432"`), so if the
-# container name stayed fixed while the port became per-checkout, a second
-# checkout would find the first checkout's container already occupying that
-# name, "start" it rather than create its own, and then poll forever against a
-# port that container was never bound to.
-CONTAINER="${BIFFO_PG_CONTAINER:-biffo-pg-test-$_checkout_suffix}"
-
-RECREATE=0
-EXPORT=0
-for arg in "$@"; do
-  case "$arg" in
-    --recreate) RECREATE=1 ;;
-    --export) EXPORT=1 ;;
-    -h | --help)
-      sed -n '2,72p' "$0" | sed 's/^#\{1,2\} \{0,1\}//'
-      exit 0
-      ;;
-    *)
-      echo "unknown argument: $arg" >&2
-      exit 2
-      ;;
-  esac
-done
-
-say() { echo "pg-test-db: $*" >&2; }
-
-cd "$REPO_ROOT"
-
-# --- what this repo's schema is made of --------------------------------------
-#
-# `db/imports/<name>/*.sql` is the Biffo DDL-import convention that the API's own
-# `ddl_import.list_sql_files` reads at startup, so deriving from it means this
-# script and the running app agree by construction rather than by someone
-# remembering to update both.
-DDL_FILES=$(find db/imports -mindepth 2 -maxdepth 2 -name '*.sql' 2>/dev/null | LC_ALL=C sort || true)
-ALEMBIC_DIR=""
-for _d in services/api .; do
-  [ -f "$_d/alembic.ini" ] && ALEMBIC_DIR="$_d" && break
-done
-
-if [ -z "$DDL_FILES" ] && [ -z "$ALEMBIC_DIR" ]; then
-  say "no db/imports/*/ DDL and no alembic.ini - this repo has no schema to build"
-  exit 1
-fi
-
-# PostGIS or plain, decided by what the DDL asks for. A plain `postgres` image
-# fails on the first `CREATE EXTENSION postgis`, and picking the heavier image
-# unconditionally would slow every repo that does not need it.
-if [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs grep -liE 'EXTENSION[[:space:]]+(IF[[:space:]]+NOT[[:space:]]+EXISTS[[:space:]]+)?postgis' >/dev/null 2>&1; then
-  IMAGE="${BIFFO_PG_IMAGE:-postgis/postgis:16-3.4}"
-else
-  IMAGE="${BIFFO_PG_IMAGE:-postgres:16}"
-fi
-
-export PGPASSWORD="$PASS"
-psql_admin() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d postgres "$@"; }
-psql_db() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" "$@"; }
-
-# --- 1. a reachable server ---------------------------------------------------
-#
-# Started here rather than assumed, because "docker run one yourself" is exactly
-# the tribal knowledge this script replaces. An already-running server is reused.
-if ! psql_admin -c 'SELECT 1' >/dev/null 2>&1; then
-  if ! command -v docker >/dev/null 2>&1; then
-    say "no Postgres at $HOST:$PORT and docker is not installed."
-    say "Start one and re-run, or set BIFFO_PG_HOST / BIFFO_PG_PORT."
-    exit 1
-  fi
-  if docker ps -a --format '{{.Names}}' | grep -qx "$CONTAINER"; then
-    say "starting existing container $CONTAINER"
-    docker start "$CONTAINER" >/dev/null
-  else
-    say "creating container $CONTAINER ($IMAGE) on port $PORT"
-    docker run -d --name "$CONTAINER" \
-      -e POSTGRES_PASSWORD="$PASS" -p "$PORT:5432" "$IMAGE" >/dev/null
-  fi
-  # Polled, not slept: a cold image pull and a warm restart differ by an order of
-  # magnitude, and one fixed sleep is wrong for both.
-  _waited=0
-  until psql_admin -c 'SELECT 1' >/dev/null 2>&1; do
-    _waited=$((_waited + 1))
-    if [ "$_waited" -gt 90 ]; then
-      say "Postgres did not become ready in 90s"
-      exit 1
-    fi
-    sleep 1
-  done
-  say "Postgres ready after ${_waited}s"
-fi
-
-DSN="postgresql+asyncpg://$USER_:$PASS@$HOST:$PORT/$DB"
-emit() {
-  if [ "$EXPORT" -eq 1 ]; then
-    echo "export BIFFO_TEST_PG_DSN='$DSN'"
-  else
-    echo "$DSN"
-  fi
-}
-
-# --- 2. is the existing schema current? --------------------------------------
-#
-# By CONTENT, not mtime: a branch switch changes content and leaves mtime
-# anywhere. Stored inside the database, so it cannot outlive a drop or describe
-# some other database.
-fingerprint() {
-  {
-    [ -n "$ALEMBIC_DIR" ] && find "$ALEMBIC_DIR" -name '*.py' -path '*alembic*' -type f 2>/dev/null |
-      LC_ALL=C sort | xargs cat 2>/dev/null
-    [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs cat 2>/dev/null
-  } | sha256sum | cut -d' ' -f1
-}
-
-WANT=$(fingerprint)
-HAVE=""
-if [ "$RECREATE" -eq 0 ] &&
-  psql_admin -tAc "SELECT 1 FROM pg_database WHERE datname='$DB'" 2>/dev/null | grep -q 1; then
-  HAVE=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
-    -c "SELECT value FROM biffo_pg_test_fingerprint LIMIT 1" 2>/dev/null || true)
-fi
-
-if [ -n "$HAVE" ] && [ "$HAVE" = "$WANT" ]; then
-  say "schema is current, reusing $DB"
-  emit
-  exit 0
-fi
-
-[ -n "$HAVE" ] && say "schema inputs changed - rebuilding rather than serving a stale schema"
-
-# --- 3. rebuild the way the app and CI do ------------------------------------
-say "rebuilding $DB"
-psql_admin -c "DROP DATABASE IF EXISTS $DB WITH (FORCE)" >/dev/null
-psql_admin -c "CREATE DATABASE $DB" >/dev/null
-
-if [ -n "$ALEMBIC_DIR" ]; then
-  BIFFO_DATABASE_URL="$DSN" uv run --directory "$ALEMBIC_DIR" alembic upgrade head >/dev/null
-  say "alembic upgrade head"
-fi
-
-if [ -n "$DDL_FILES" ]; then
-  # ONE psql session, sorted by filename, mirroring the API's own DDL import.
-  # Session state an early module sets -- typically `SET search_path` in the
-  # first file -- has to survive into later ones, so a per-file connection would
-  # silently change the meaning of every unqualified name after it. LC_ALL=C
-  # keeps the shell's sort byte-ordered to match Python's.
-  # shellcheck disable=SC2046
-  psql -q -v ON_ERROR_STOP=1 -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
-    --single-transaction $(echo "$DDL_FILES" | sed 's/^/-f /' | tr '\n' ' ') >/dev/null
-  say "$(echo "$DDL_FILES" | wc -l | tr -d ' ') DDL modules applied"
-fi
-
-# --- 4. refuse to bless a half-built schema ----------------------------------
-#
-# The threshold is derived, not guessed: count the policies the DDL declares and
-# require the database to hold at least half. Recording a fingerprint against a
-# partial schema is worse than failing, because the NEXT run would trust it and
-# every failure after that would look like the developer's own change.
-if [ -n "$DDL_FILES" ]; then
-  _declared=$(echo "$DDL_FILES" | xargs grep -ciE '^[[:space:]]*CREATE[[:space:]]+POLICY' 2>/dev/null |
-    awk -F: '{s+=$NF} END {print s+0}')
-  if [ "${_declared:-0}" -gt 0 ]; then
-    _actual=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
-      -c "SELECT count(*) FROM pg_policies" 2>/dev/null || echo 0)
-    if [ "${_actual:-0}" -lt $((_declared / 2)) ]; then
-      say "only ${_actual:-0} policies present against $_declared declared - the schema did not build."
-      say "Not recording a fingerprint; fix the DDL and re-run."
-      exit 1
-    fi
-    say "$_actual RLS policies ($_declared declared)"
-  fi
-fi
-
-psql_db \
-  -c "CREATE TABLE IF NOT EXISTS biffo_pg_test_fingerprint (value text primary key)" \
-  -c "TRUNCATE biffo_pg_test_fingerprint" \
-  -c "INSERT INTO biffo_pg_test_fingerprint (value) VALUES ('$WANT')" >/dev/null
-
-say "ready"
-emit