@biffo/cli 0.296.12 → 0.296.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.296.12",
+  "version": "0.296.14",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/scripts/branch-health.sh

@@ -54,6 +54,18 @@
 # merges landing seconds apart cancel the first run by design. It is called out
 # by name so nobody debugs a phantom.
 #
+# `plan-only` (#1582) is likewise reported but does not fail the branch — a
+# `Deploy Infrastructure` dispatch left at the default `action: plan` really did
+# succeed at planning, and that can be entirely deliberate (an operator running
+# a dry run). What it must never do is share the plain `ok` label a real apply
+# gets: `conclusion` is "success" either way, so the ONLY signal that tells them
+# apart is the run's own title (`displayTitle`), which #1678 made carry a
+# `PLAN ONLY ... (nothing applied)` marker for exactly this. This script fails
+# CLOSED on that signal going missing — see the summary query below, where
+# `displayTitle`'s absence collapses the whole `gh run list` call to empty
+# output, which is already handled as exit 2 ("cannot tell"), not as a silent
+# `ok`.
+#
 # ## Usage
 #
 #   sh scripts/branch-health.sh [-R owner/repo] [--branch dev] [--quiet]
@@ -67,7 +79,7 @@ BRANCH=""
 QUIET=""
 
 usage() {
-  sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '2,73p' "$0" | sed 's/^# \{0,1\}//'
   exit 2
 }
 
@@ -144,13 +156,24 @@ label=${REPO:-$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")}
 # list": the ordering is gh's to change, and a status tool that quietly reports
 # an older run because an API changed its sort is the same class of defect as the
 # truncated list this replaces. Ask for the newest explicitly.
+#
+# `displayTitle` is requested here for #1582's second half: a `workflow_dispatch`
+# left at the default `action: plan` runs its plan step for real and concludes
+# "success" — conclusion alone can never tell that apart from a real apply, by
+# design (#1582's whole point). #1678 fixed the Actions-UI half by giving such a
+# run a `run-name` that says "PLAN ONLY ... (nothing applied)"; this line is what
+# lets branch-health.sh see that same marker instead of rendering the run as a
+# plain, indistinguishable "ok". The per-workflow history query further below
+# already requests this field for a different reason (naming who broke a
+# failure) — same field, independent reason to want it here.
 summary=$(gh_run list --branch "$BRANCH" --limit 200 \
-  --json workflowName,status,conclusion,headSha,createdAt,url,event \
+  --json workflowName,status,conclusion,headSha,createdAt,url,event,displayTitle \
   --jq 'group_by(.workflowName)
         | map(max_by(.createdAt))
         | .[]
         | [ (if .status == "completed" then (.conclusion // "unknown") else .status end),
-            .workflowName, .headSha[0:8], .createdAt[0:16], .url, .event ]
+            .workflowName, .headSha[0:8], .createdAt[0:16], .url, .event,
+            (.displayTitle // "") ]
         | @tsv' 2>/dev/null)
 
 if [ -z "$summary" ]; then
@@ -164,11 +187,24 @@ pending=""
 cancelled=""
 skipped=""
 ok=""
+planonly=""
 
-while IFS="$TAB" read -r state name sha when url event; do
+while IFS="$TAB" read -r state name sha when url event title; do
   [ -n "$name" ] || continue
   case "$state" in
-    success) ok="${ok}${name}\n" ;;
+    success)
+      # A literal, upper-case "PLAN ONLY" is the #1678 run-name marker
+      # (`format('PLAN ONLY {0} (nothing applied)', ...)`) — never something a
+      # commit-subject-derived title produces by coincidence (this repo's own
+      # history has "plan-only" and "plan-time" in commit subjects, always
+      # lower-case, and grep confirms zero for the exact upper-case phrase).
+      # A "success" run whose title carries it applied nothing and must not
+      # collapse into the same "ok" bucket as a real apply.
+      case "$title" in
+        *"PLAN ONLY"*) planonly="${planonly}${name}\n" ;;
+        *) ok="${ok}${name}\n" ;;
+      esac
+      ;;
     failure | timed_out | startup_failure)
       failed="${failed}${state}\t${name}\t${sha}\t${when}\t${url}\t${event}\n"
       ;;
@@ -193,6 +229,10 @@ echo
 [ -n "$ok" ] && printf '%b' "$ok" | sed "s/^/  ${GREEN}ok${OFF}         /"
 [ -n "$skipped" ] && printf '%b' "$skipped" | sed "s/^/  ${DIM}skipped${OFF}    /"
 [ -n "$cancelled" ] && printf '%b' "$cancelled" | sed "s/^/  ${YELLOW}cancelled${OFF}  /"
+# Own label, not "ok" — #1582's second half. A skim-reader tells rows apart by
+# this left-hand column, not by reading every run's title, so the row itself
+# has to say "nothing applied" rather than reusing the label a real apply gets.
+[ -n "$planonly" ] && printf '%b' "$planonly" | sed "s/^/  ${YELLOW}plan-only${OFF}  /" | sed "s/\$/ — nothing applied/"
 
 if [ -n "$pending" ]; then
   printf '%b' "$pending" | awk -F'\t' -v d="$YELLOW" -v o="$OFF" 'NF{printf "  %srunning%s    %s (%s)\n", d, o, $2, $1}'
@@ -204,6 +244,11 @@ if [ -z "$failed" ]; then
     echo "${DIM}A cancelled run is usually spot reclamation or a superseded concurrency${OFF}"
     echo "${DIM}group, not the code. Re-run it rather than debugging it.${OFF}"
   fi
+  if [ -n "$planonly" ]; then
+    echo
+    echo "${DIM}A plan-only dispatch did not apply anything — Terraform state is${OFF}"
+    echo "${DIM}unchanged for that environment. Not a failure, but not a deploy either.${OFF}"
+  fi
   echo
   echo "${GREEN}Nothing on '$BRANCH' is failing.${OFF}"
   exit 0

package/scripts/wait-for-checks.sh

@@ -98,10 +98,37 @@
 #   anything     keep waiting on the checks as before. An unreadable field
 #   else         (old gh, missing scope) must never become a verdict.
 #
+# ## A wait that outlives its caller is worse than no wait
+#
+# This script's timeout says how long IT will wait. It said nothing about how
+# long its CALLER has left, and that gap loses whole sessions.
+#
+# Measured 2026-08-22, biffo-fleet Foreman `7d362ba7`, which runs under
+# `timeout 3300`. It pushed a commit at 05:37:03 and started this script at
+# 05:37:04 with about five minutes of its 55-minute budget left. CI was
+# genuinely in flight and would have concluded at 05:48:18 — a correct ~11
+# minute wait. The session was SIGKILLed at 05:42:45, this script returned
+# **137**, and the turn was lost mid-flight: no verdict, no cost record, the
+# tick reporting `cost=UNKNOWN tokens=UNKNOWN`. Nothing was wrong with the
+# checks or with the waiting; the wait could not fit in the time left and
+# neither side knew it. It was the eleventh such kill in three days.
+#
+# So a caller that knows when it dies can say so:
+#
+#   WAIT_FOR_CHECKS_DEADLINE  absolute unix epoch the CALLER dies at
+#   WAIT_FOR_CHECKS_MARGIN    seconds to leave it to react (default 60)
+#
+# The effective deadline becomes the EARLIER of its own timeout and that bound,
+# and if not even one poll fits it exits 2 immediately — before any API call —
+# rather than starting a wait it cannot finish. Both remain exit 2, "cannot
+# tell", never a pass: "ran out of time" and "checks are green" must never be
+# the same answer. Unset, nothing changes.
+#
 # ## Usage
 #
 #   sh scripts/wait-for-checks.sh <pr-number> [-R owner/repo]
 #                                 [--timeout SECONDS] [--interval SECONDS]
+#                                 [--deadline EPOCH]
 #
 # Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary is needed.
 
@@ -111,6 +138,8 @@ PR=""
 REPO=""
 TIMEOUT="${WAIT_FOR_CHECKS_TIMEOUT:-1800}"
 INTERVAL="${WAIT_FOR_CHECKS_INTERVAL:-30}"
+SESSION_DEADLINE="${WAIT_FOR_CHECKS_DEADLINE:-}"
+MARGIN="${WAIT_FOR_CHECKS_MARGIN:-60}"
 
 usage() {
   # Print the whole header block, however long it grows: from line 2 up to the
@@ -134,6 +163,10 @@ while [ $# -gt 0 ]; do
       INTERVAL="${2:-}"
       shift 2
       ;;
+    --deadline)
+      SESSION_DEADLINE="${2:-}"
+      shift 2
+      ;;
     -h | --help) usage ;;
     *)
       PR="$1"
@@ -152,6 +185,24 @@ GREEN=$(printf '\033[32m')
 DIM=$(printf '\033[90m')
 OFF=$(printf '\033[0m')
 
+# --- Bound the wait by the CALLER's life, not only by our own timeout ----------
+#
+# A non-numeric or empty bound is IGNORED rather than read as zero: an unreadable
+# value must never become "no time left", which would turn a caller's typo into a
+# script that refuses to wait for anything.
+deadline=$(($(date +%s) + TIMEOUT))
+bounded_by_caller=0
+case "$SESSION_DEADLINE" in
+  '' | *[!0-9]*) : ;;
+  *)
+    caller_limit=$((SESSION_DEADLINE - MARGIN))
+    if [ "$caller_limit" -lt "$deadline" ]; then
+      deadline=$caller_limit
+      bounded_by_caller=1
+    fi
+    ;;
+esac
+
 gh_pr() {
   if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi
 }
@@ -176,6 +227,33 @@ case "$state" in
     ;;
 esac
 
+# Not even one poll fits in what the CALLER has left. Refuse BEFORE the polling
+# starts: being killed mid-wait costs the caller its whole turn, while exiting now
+# leaves it time to record what it already knows.
+#
+# TWO PLACEMENT RULES, both learned by getting them wrong (cli/src/lib/
+# wait-for-checks.test.ts caught both):
+#
+#   1. ONLY when a caller bound is actually in force. Keyed on the effective
+#      deadline alone, `--timeout 0` -- a deliberate, tested "one pass then
+#      report" -- started refusing to run at all. A caller's own short timeout is
+#      its own business; this bound is about the caller's LIFE, not its patience.
+#
+#   2. AFTER the MERGED/CLOSED fast path. Placed before it, an already-merged PR
+#      with no time left returned "cannot tell" instead of the exit 0 it had
+#      already earned. There is nothing to wait for there, so there is nothing to
+#      refuse. One state read is a cost worth paying to answer correctly.
+if [ "$bounded_by_caller" = "1" ] && [ "$deadline" -le "$(( $(date +%s) + INTERVAL ))" ]; then
+  left=$(( deadline - $(date +%s) ))
+  [ "$left" -lt 0 ] && left=0
+  echo "${RED}wait-for-checks: not enough time left to wait for PR $PR.${OFF}" >&2
+  echo "The caller dies in ${left}s (margin ${MARGIN}s) and one poll takes ${INTERVAL}s," >&2
+  echo "so this would be killed mid-wait, losing the turn without a verdict." >&2
+  echo "Re-run with more time, or raise the caller's budget." >&2
+  echo "Not a failure and not a pass: this is 'cannot tell'." >&2
+  exit 2
+fi
+
 # --- Signal 1: the checks branch protection says MUST report ------------------
 
 owner_repo="$REPO"
@@ -198,7 +276,7 @@ fi
 
 # --- Poll ---------------------------------------------------------------------
 
-deadline=$(($(date +%s) + TIMEOUT))
+# `deadline` and `bounded_by_caller` were settled above, before any API call.
 prev_count=-1
 rollup=""
 
@@ -298,7 +376,15 @@ EOF
 
   now=$(date +%s)
   if [ "$now" -ge "$deadline" ]; then
-    echo "${RED}wait-for-checks: timed out after ${TIMEOUT}s.${OFF}" >&2
+    if [ "$bounded_by_caller" = "1" ]; then
+      # Distinct wording on purpose: "the caller ran out" sends you to its budget,
+      # "we ran out" sends you to CI. Same exit code, different fix.
+      echo "${RED}wait-for-checks: stopped early — the caller's deadline arrived.${OFF}" >&2
+      echo "Checks had not concluded. Waiting longer would have been killed" >&2
+      echo "mid-wait instead of returning this. Raise the caller's budget." >&2
+    else
+      echo "${RED}wait-for-checks: timed out after ${TIMEOUT}s.${OFF}" >&2
+    fi
     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