@plot-pm/board 0.27.1 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plot-pm/board",
3
- "version": "0.27.1",
3
+ "version": "0.28.0",
4
4
  "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
5
5
  "type": "module",
6
6
  "license": "CC0-1.0",
package/plot-config.sh CHANGED
@@ -240,7 +240,11 @@
240
240
  # of any other workflow is not folded, so a publishing or
241
241
  # release workflow cannot raise the `default-branch-red`
242
242
  # hold or the board's red-branch status. Names match a run's
243
- # workflow name exactly. Absent = every workflow's runs.
243
+ # workflow name exactly; a bare name folds the whole run.
244
+ # `<workflow>/<job>` (`CI/validate`) folds that one job of
245
+ # that workflow, under GitHub Actions only: a job name no
246
+ # job carries matches no run and reads `unknown`, never
247
+ # green. Absent = every workflow's runs.
244
248
  # Merge checks comma-separated check names (a job's check run or a
245
249
  # status context, `validate`) that `plot-ask.mjs merge`
246
250
  # and fleetd's merge arm require to have a completed
package/plot-host.sh CHANGED
@@ -2440,14 +2440,19 @@ graphql_budget_spent() {
2440
2440
  #
2441
2441
  # THE ARMS, AND WHY EACH IS WHERE IT IS:
2442
2442
  #
2443
- # pr-state both transports. The only op with a REST fallback
2444
- # written, so the only one where the budget can change the
2445
- # answer.
2443
+ # pr-state both transports, so the budget can change the answer.
2444
+ # pr-list both transports for the PLAIN listing (`gh_pr_list_routed`).
2445
+ # `--rich`, `--rich-open`'s open half and the Jenkins arm stay
2446
+ # GraphQL whatever the route: REST's list endpoint carries no
2447
+ # check rollup, no `mergeable` and no `reviewDecision`, so a
2448
+ # rich row would cost four calls per PR on every refresh, and
2449
+ # `reviewDecision` has no REST field at all. A rich call with
2450
+ # GraphQL spent is refused (exit 5), never answered thinner.
2446
2451
  # limit REST-only BY NATURE rather than by omission. It is
2447
2452
  # reached through `gh api`, which is REST's transport.
2448
2453
  # It spends a GraphQL call to read its own headers —
2449
2454
  # the call it makes is GraphQL, the route to it is not.
2450
- # * GraphQL-only. Ten ops, and this is where "every op
2455
+ # * GraphQL-only. Nine ops, and this is where "every op
2451
2456
  # consults the router" is honest rather than decorative:
2452
2457
  # their answer is a statement about what THIS SCRIPT has
2453
2458
  # implemented, not about what GitHub offers, which serves
@@ -2460,8 +2465,9 @@ graphql_budget_spent() {
2460
2465
  # `PLOT_HOST_FORCE_REST=1` IS NOT A DEBUG SWITCH. It is how the rate-refusal
2461
2466
  # re-entry reaches the second path without a second copy of the REST code:
2462
2467
  # `pr-state` re-enters itself with the variable set after GraphQL is refused
2463
- # for rate. An operator may also set it, and that is supported, but the
2464
- # re-entry is why it exists. It is consulted before the budget because it is
2468
+ # for rate; plain `pr-list` asks REST in `gh_pr_list_routed` instead. An
2469
+ # operator may also set it, and that is supported, but the re-entry is why it
2470
+ # exists. It is consulted before the budget because it is
2465
2471
  # free and the budget read is not.
2466
2472
  #
2467
2473
  # THE BUDGET IS CONSULTED LAST, AND IT READS THE RECORD BY BUCKET NAME. Every
@@ -2484,8 +2490,8 @@ gh_route() { # $1=op → graphql|rest
2484
2490
  limit|pr-create|pr-body)
2485
2491
  printf 'rest\n'
2486
2492
  ;;
2487
- # Both transports implemented — the one op where the reasons apply.
2488
- pr-state)
2493
+ # Both transports implemented — the ops where the reasons apply.
2494
+ pr-state|pr-list)
2489
2495
  if [ "${PLOT_HOST_FORCE_REST:-0}" = "1" ] || graphql_budget_spent; then
2490
2496
  printf 'rest\n'
2491
2497
  else
@@ -2550,6 +2556,49 @@ rest_pr_state() { # $1=owner/repo $2=PR number or branch; returns 3 when the bra
2550
2556
  jq -cs "$CHECKS_OF$MERGEABLE_OF"'.[0] as $p | (.[1].check_runs // []) as $c | (.[2].statuses // []) as $s | (($p.merged == true) or ($p.merged_at != null)) as $m | {number: $p.number, state: (if $m then "MERGED" else ($p.state // "" | ascii_upcase) end), isDraft: ($p.draft // false), url: ($p.html_url // ""), mergeCommit: (if $m then {oid: ($p.merge_commit_sha // "")} else null end), headRefName: ($p.head.ref // ""), headRefOid: ($p.head.sha // ""), baseRefName: ($p.base.ref // ""), mergedAt: ($p.merged_at // ""), mergeable: (if $p.mergeable == true then "MERGEABLE" elif $p.mergeable == false then "CONFLICTING" else "UNKNOWN" end), mergeStateStatus: (($p.mergeable_state // "") | ascii_upcase), statusCheckRollup: ([$c[] | {name, status: ((.status // "") | ascii_upcase), conclusion: ((.conclusion // "") | ascii_upcase), startedAt: (.started_at // "")}] + [$s[] | {context, state: ((.state // "") | ascii_upcase), startedAt: (.created_at // "")}] + (if ((.[1].total_count // 0) > ($c | length)) or ((.[2].total_count // 0) > ($s | length)) then [{status: "QUEUED"}] else [] end))} |'"$PR_STATE_OF" <<<"$pr$ck$st"
2551
2557
  }
2552
2558
 
2559
+ # GITHUB'S `pr-list`, ON THE ROUTE `gh_route` CHOSE. "$@" is the `gh pr list` argv,
2560
+ # asked while the route is `graphql` and always under `--rich`: REST's list has no
2561
+ # rollup, no `mergeable` and no `reviewDecision`, so a rich row has no REST form.
2562
+ # A plain call refused by GraphQL for rate asks REST once, as `pr-state` does; the
2563
+ # REST answer, or REST's own failure for `pr_list_call` to classify, is the op's. Measured 2026-11-16: GraphQL at 0
2564
+ # while REST answered, and every `pr-list` caller failed with exit 5.
2565
+ #
2566
+ # REST PRINTS THE ARRAY `gh` PRINTS for the plain fields (`number,title,state,
2567
+ # headRefName,baseRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt`), so the plain
2568
+ # arm's one projection reads either. It reads the arm's `$state`, `$limit` (`gh`'s 30 when empty), `$since`
2569
+ # and one-branch `$head_args`. REST's `state` is `open|closed|all`: `merged` and
2570
+ # `closed` are its `closed` split on `merged_at`, as GraphQL splits them. Pages
2571
+ # run newest-created first, as `gh pr list` does; `--since` walks `sort=updated`
2572
+ # instead and stops at the first page that reaches the stamp. A failed page fails
2573
+ # the whole list, so no partial array is printed.
2574
+ gh_pr_list_routed() {
2575
+ local page=1 pages='' repo n="${limit:-30}" sel
2576
+ if [ "$route" != rest ] || [ "$rich" = 1 ]; then
2577
+ "$@" 2>"$HOST_ERR" && { cat "$HOST_ERR" >&2; return 0; }
2578
+ [ "$rich" = 0 ] && is_rate_refusal "$(cat "$HOST_ERR")" || { cat "$HOST_ERR" >&2; return 1; }
2579
+ fi
2580
+ repo="$(gh_rest_repo)"
2581
+ sel='def keep: .updated_at > $s and (if $st == "merged" then .merged_at != null elif $st == "closed" then .merged_at == null else true end);'
2582
+ while [ "$page" -gt 0 ]; do
2583
+ pages="$pages$(gh_api_harvest "repos/$repo/pulls?state=${state/merged/closed}&per_page=100&page=$page${since:+&sort=updated&direction=desc}${head_args[1]:+&head=${repo%%/*}:${head_args[1]}}")" || return
2584
+ page="$(jq -s --arg st "$state" --arg s "$since" --argjson n "$n" --argjson p "$page" "$sel"'if (.[-1] | length) == 100 and ([.[][] | select(keep)] | length) < $n and .[-1][-1].updated_at > $s then $p + 1 else 0 end' <<<"$pages")" || return
2585
+ done
2586
+ jq -cs --arg st "$state" --arg s "$since" --argjson n "$n" "$sel"'[.[][] | select(keep)] | sort_by(-.number) | .[:$n] | map({number, title, state: (if .merged_at then "MERGED" else (.state | ascii_upcase) end), headRefName: .head.ref, baseRefName: .base.ref, isDraft: (.draft // false), url: .html_url, updatedAt: .updated_at, author: {login: (.user.login // "")}, headRefOid: .head.sha, mergedAt: .merged_at})' <<<"$pages"
2587
+ }
2588
+
2589
+ # THE ARGUMENTS OF `pr-merged`, `pr-merge-commit`, `pr-merge-dest` and
2590
+ # `pr-merged-heads`: a branch, then `--repo <owner/repo>` at most. Sets `ref` and
2591
+ # `repo_args`; a missing branch or any other argument ends the script.
2592
+ op_branch_args() {
2593
+ ref="${1:?$op needs a branch}"; shift; repo_args=()
2594
+ while [ $# -gt 0 ]; do
2595
+ case "$1" in
2596
+ --repo) repo_args=(-R "${2:?}"); shift 2 ;;
2597
+ *) die "$op: unknown arg $1" ;;
2598
+ esac
2599
+ done
2600
+ }
2601
+
2553
2602
  # `owner/repo` from the `origin` URL, with no host call. An `ssh://` URL may carry
2554
2603
  # a port after the host, and an scp-style remote splits host and path at its first
2555
2604
  # colon. Prints nothing and exits 1 where the URL names no `owner/repo`.
@@ -4206,13 +4255,7 @@ case "$op" in
4206
4255
  # deciding whether to remove something. Exit 3 is still reserved for the call
4207
4256
  # itself failing in a way this adapter does not recognise as a miss.
4208
4257
  pr-merged)
4209
- ref="${1:?pr-merged needs a branch}"; shift || true; repo_args=()
4210
- while [ $# -gt 0 ]; do
4211
- case "$1" in
4212
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4213
- *) die "pr-merged: unknown arg $1" ;;
4214
- esac
4215
- done
4258
+ op_branch_args "$@"
4216
4259
  # NO REMOTE, NO PR: no repository holds one, so nothing merged, whatever gh's auth says.
4217
4260
  if [ ${#repo_args[@]} -eq 0 ] && [ -z "$(git remote 2>/dev/null)" ]; then echo "not-merged"; else
4218
4261
  if [ "$be" = "github" ]; then
@@ -4279,13 +4322,7 @@ case "$op" in
4279
4322
  # `pr_list_report_truncation`. Bitbucket's arm already pages in full via
4280
4323
  # `_bb_paged_walk` (#2484); its `mergedAt` is `updated_on` as in `pr-list`,
4281
4324
  # since the endpoint carries no real merge timestamp (#2202).
4282
- ref="${1:?$op needs a branch}"; shift || true; repo_args=()
4283
- while [ $# -gt 0 ]; do
4284
- case "$1" in
4285
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4286
- *) die "$op: unknown arg $1" ;;
4287
- esac
4288
- done
4325
+ op_branch_args "$@"
4289
4326
  if [ "$op" = pr-merge-dest ]; then pick='.[] | [.n, .b, .s, .t] | @tsv'; else pick='first.s // empty'; fi
4290
4327
  if [ "$be" = "github" ]; then
4291
4328
  limit=100
@@ -4337,13 +4374,7 @@ case "$op" in
4337
4374
  # A FAILURE WITH NO MESSAGE IS A FAILURE HERE, unlike `pr-state`: an empty
4338
4375
  # answer makes the caller fall back to a patch-id reading, so silence must
4339
4376
  # not stand in for *no merged head*. Only a recognised lookup miss is empty.
4340
- ref="${1:?pr-merged-heads needs a branch}"; shift || true; repo_args=()
4341
- while [ $# -gt 0 ]; do
4342
- case "$1" in
4343
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4344
- *) die "pr-merged-heads: unknown arg $1" ;;
4345
- esac
4346
- done
4377
+ op_branch_args "$@"
4347
4378
  if [ "$be" = "github" ]; then
4348
4379
  if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt,headRefOid 2>"$HOST_ERR")"; then
4349
4380
  rm -f "$HOST_ERR"
@@ -4660,6 +4691,18 @@ case "$op" in
4660
4691
  failing_checks:[]}'
4661
4692
  exit 0
4662
4693
  fi
4694
+ # ONE CALL FOR ALL THREE ARMS, and the arm decides only the fields and the
4695
+ # projection. The plain fields always travel; `--rich` adds the verdicts,
4696
+ # and the rollup only where CI is not Jenkins (the Jenkins arm discards it).
4697
+ # THE FIELD ORDER IS THE QUERY `gh` SENDS, and the corpus pins it
4698
+ # (`github-pr-listing.ts`'s fragments), so each arm keeps its own order.
4699
+ # `gh_pr_list_routed` asks GraphQL or REST; a rich call is GraphQL always.
4700
+ _json=number,title,state,headRefName,baseRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt
4701
+ [ "$rich" = 1 ] && _json="number,title,state,headRefName,baseRefName,isDraft,$([ "$ci" = jenkins ] || echo statusCheckRollup,)mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt"
4702
+ _gh_raw="$(pr_list_call gh_pr_list_routed gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4703
+ --json "$_json")" || exit $?
4704
+ pr_list_report_truncation github "$limit" "$state" \
4705
+ "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4663
4706
  if [ "$rich" = 1 ]; then
4664
4707
  # `checks` has FOUR states, and two of them mean "a person is the
4665
4708
  # blocker" rather than "a machine is busy":
@@ -4742,10 +4785,6 @@ case "$op" in
4742
4785
  # $jstatus != "ok" → Jenkins could not answer; every row `unknown`.
4743
4786
  # $jentry == null → the branch has no Jenkins job; `none`.
4744
4787
  # otherwise → the joined colour's `checks`, job named on fail.
4745
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4746
- --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4747
- pr_list_report_truncation github "$limit" "$state" \
4748
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4749
4788
  # GAPS 3/4/10: `jmap` names no commit, so a push between builds would
4750
4789
  # carry the OLD head's colour onto the new one. The bundle names the
4751
4790
  # rows `jmap` cannot settle (green/failing with a head sha, at most
@@ -4774,7 +4813,7 @@ case "$op" in
4774
4813
  # own field rather than collapsing into the same `checks` word
4775
4814
  # (`bitbucket-jenkins-a-pr-list-row`).
4776
4815
  {
4777
- number:.number, title:.title, state:.state, head:.headRefName,
4816
+ number:.number, title:.title, state:.state, head:.headRefName, base:(.baseRefName // ""),
4778
4817
  draft:.isDraft,
4779
4818
  checks:(if $jstatus != "ok" then "unknown" elif $eff == null then (if $ambiguous then "unknown" else "none" end) else $eff.checks end),
4780
4819
  mergeable:mergeable_of,
@@ -4787,13 +4826,9 @@ case "$op" in
4787
4826
  } + (if $jstatus == "ok" and $ambiguous and $eff == null then {checksLookup:"skipped"} else {} end)'
4788
4827
  else
4789
4828
  # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
4790
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4791
- --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4792
- pr_list_report_truncation github "$limit" "$state" \
4793
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4794
4829
  printf '%s' "$_gh_raw" \
4795
4830
  | jq -c "$CHECKS_OF$MERGEABLE_OF"'.[] | {
4796
- number:.number, title:.title, state:.state, head:.headRefName,
4831
+ number:.number, title:.title, state:.state, head:.headRefName, base:(.baseRefName // ""),
4797
4832
  draft:.isDraft,
4798
4833
  checks:checks_of, mergeable:mergeable_of,
4799
4834
  review:(.reviewDecision // ""),
@@ -4818,12 +4853,8 @@ case "$op" in
4818
4853
  # advances its watermark by. Without it a split full read would leave
4819
4854
  # the store unable to narrow and the daily full read would never fall
4820
4855
  # due against anything but a cold window.
4821
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4822
- --json number,title,state,headRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4823
- pr_list_report_truncation github "$limit" "$state" \
4824
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4825
4856
  printf '%s' "$_gh_raw" \
4826
- | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4857
+ | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,base:(.baseRefName // ""),draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4827
4858
  fi
4828
4859
  else
4829
4860
  # `headSha` IS `.source.commit.hash`, which the pullrequests endpoint
@@ -107,9 +107,9 @@ die() { echo "plot-release-refs: $*" >&2; exit 2; }
107
107
  command -v git >/dev/null 2>&1 || die "git not found"
108
108
  git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
109
109
 
110
- # The SAME gate the reaper uses, sourced rather than re-derived. `pr_merged`
111
- # reads `mergedAt` on ANY PR (never `state`, never ancestry); `pr_open` answers
112
- # the veto in guard 3.
110
+ # The SAME lookups the reaper uses, sourced rather than re-derived:
111
+ # `_plot_merged_lookup` reads `mergedAt` on ANY PR (never `state`, never
112
+ # ancestry), and `_plot_open_lookup` answers the open-PR veto.
113
113
  . "$script_dir/plot-pr-merged.sh"
114
114
 
115
115
  cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
@@ -169,27 +169,17 @@ fi
169
169
  # that estate may hold dozens of trees. The answer cannot change underneath a
170
170
  # single run in a way that matters — a worktree created mid-run holds a branch
171
171
  # whose ref this run has not yet reached, and the next run sees it.
172
- #
173
- # THE TREE'S STATE IS COLLECTED TOO, and that is what the shared rule needed.
174
- # `finishedWith` answers four conditions from a worktree, and it answers them
175
- # `unknown` where there is none — so it has to be told whether one was found.
176
- # That is a reading, not a refusal: this script asks none of those four, and
177
- # passing the tree is what lets the rule say `unknown` instead of inventing
178
- # `false`. Git's own `prunable` distinguishes a listed tree whose directory is
179
- # gone from one that was never made; both are unaskable, and the rule keeps the
180
- # two words apart because an operator acts on them differently.
181
172
  checked_out=$(git worktree list --porcelain 2>/dev/null \
182
- | awk '/^worktree /{wt=substr($0,10); pr="no"}
183
- /^prunable/{pr="yes"}
184
- /^branch refs\/heads\//{print substr($0,19) "\t" wt "\t" pr}')
173
+ | awk '/^worktree /{wt=substr($0,10)}
174
+ /^branch refs\/heads\//{print substr($0,19) "\t" wt}')
185
175
 
186
- # The worktree holding a branch and whether git calls it prunable, or empty
187
- # when no tree holds it.
176
+ # The worktree holding a branch, or empty when no tree holds it.
188
177
  worktree_of() {
189
- printf '%s\n' "$checked_out" | awk -F'\t' -v b="$1" '$1 == b {print $2 "\t" $3; exit}'
178
+ printf '%s\n' "$checked_out" | awk -F'\t' -v b="$1" '$1 == b {print $2; exit}'
190
179
  }
191
180
 
192
181
  released=0; kept=0; deleted=0
182
+ remote=$(git ls-remote --heads origin 2>/dev/null) || remote=unread
193
183
  printf '%-8s %-52s %s\n' "verdict" "branch" "why"
194
184
 
195
185
  # Branch and its deferred flag, one per line, from the plan's own parser.
@@ -205,115 +195,61 @@ while IFS=$'\t' read -r br deferred; do
205
195
  # `if` about whether a ref may go — only about which conditions it asks and
206
196
  # what to do with the answers.
207
197
  #
208
- # `pr_merged` reads `mergedAt` on ANY PR (never `state`, never ancestry) and
209
- # answers false when the host cannot be asked, so silence keeps the ref.
210
- # `pr_open` is asked separately rather than derived from it: a branch carries
211
- # both, and `changeset-release/main` is the measured case.
212
- merge=not-merged
213
- pr_merged "$br" && merge=merged
198
+ # A REF ORIGIN DOES NOT HOLD HAS NOTHING TO RELEASE, and asking the host about
199
+ # it only spends the limit. A listing that failed asks the host as before.
200
+ if [ "$remote" != unread ] && ! awk -v r="refs/heads/$br" '$2 == r {f=1} END {exit !f}' <<<"$remote"; then
201
+ printf '%-8s %-52s %s\n' "absent" "$br" "no remote ref — nothing to release"; continue
202
+ fi
214
203
 
215
- open_pr=false
216
- pr_open "$br" && open_pr=true
204
+ # Each lookup answers `found`, `none` or `unaskable`. `merge` reads `mergedAt`
205
+ # on ANY PR (never `state`, never ancestry); the open PR is asked separately
206
+ # because a branch carries both, and `changeset-release/main` is the measured
207
+ # case. An `unaskable` answer from either keeps the ref under its own name.
208
+ merge=$(_plot_merged_lookup "$br")
209
+ open_pr=$(_plot_open_lookup "$br")
217
210
 
218
- # WHETHER A TREE HOLDS THE BRANCH, AND IN WHAT STATE. Three words, because
219
- # the rule answers its four tree-sourced conditions `unknown` without one and
220
- # `unknown` is a reading rather than a failure. `vanished` is git's own
221
- # `prunable`: it reads like `absent` to every condition — there is equally
222
- # nothing to measure — and stays a separate word because `git worktree prune`
223
- # is the repair for one and not the other.
224
- #
225
- # NOTHING INSIDE THE TREE IS READ. A live pid, an uncommitted file and a
226
- # `PLOT-BLOCKED` marker are the reaper's three conditions and this script
227
- # asks none of them; measuring them here would put a refusal within one edit's
228
- # reach of a licence written narrow on purpose. A checked-out branch keeps its
229
- # ref whatever is going on inside it, which is guard 4 and needs no reading
230
- # from the tree at all.
231
- wt_line=$(worktree_of "$br")
232
- wt=${wt_line%%$'\t'*}
233
- prunable=${wt_line#*$'\t'}
234
- tree=absent
235
- if [ -n "$wt" ]; then
236
- if [ "$prunable" = "yes" ] || [ ! -d "$wt" ]; then tree=vanished; else tree=present; fi
237
- fi
211
+ # WHETHER A WORKTREE HOLDS THE BRANCH. Nothing inside the tree is read: a live
212
+ # pid, an uncommitted file and a `PLOT-BLOCKED` marker are the reaper's
213
+ # conditions, and this script passes them empty so they never refuse. A
214
+ # checked-out branch keeps its ref whatever is going on inside it.
215
+ wt=$(worktree_of "$br")
238
216
 
239
- # THE DECISION. `packages/domain/src/rules/reapable.ts`, imported directly —
240
- # the same shape and the same reason as `plot-reap.sh`: node 24 strips the
241
- # types, so there is no build step between this script and the rule, and the
242
- # JS arrives on STDIN from a QUOTED heredoc so the shell expands none of it.
243
- #
244
- # ONE RULE, TWO CALLERS, AND THE CALLERS STAY DIFFERENT. `finishedWith`
245
- # STATES every condition that can hold a desk and JUDGES none of them; which
246
- # conditions refuse a ref is this caller's half, and it names exactly the five
247
- # this script has always asked. The reaper reads the same rule and names its
248
- # own. Neither script gains the other's, which is what makes the difference
249
- # visible instead of eliminating it.
250
- #
251
- # `unknown` PERMITS, AND THE ORDER OF THE TESTS IS THE ARGUMENT. Only the
252
- # first two conditions are answerable without a tree, and 69% of branches have
253
- # none. `=== "true"` is therefore the test at every guard: `unknown` falls
254
- # through, exactly as this script behaved before the rule existed. That is
255
- # deliberate and it is the caller's decision to make — the reaper reads the
256
- # same `unknown` as *nothing to reap*.
217
+ # THE DECISION. `firstRefRefusal` in `packages/domain/src/rules/reapable.ts`,
218
+ # imported directly: node strips the types, so there is no build step between
219
+ # this script and the rule, and the JS arrives on STDIN from a QUOTED heredoc
220
+ # so the shell expands none of it. The rule names the first refusal in its
221
+ # own order; a host that could not be asked refuses as `merge-unaskable` or
222
+ # `open-unaskable`.
257
223
  #
258
224
  # A rule that cannot be asked REFUSES: node missing, the import failing, the
259
225
  # module throwing all leave `verdict` empty, and an empty verdict keeps the
260
- # ref and says why. Silence is never permission on this path either — that is
261
- # the module being absent, which is not the same reading as a condition
262
- # answering `unknown`.
226
+ # ref and says why.
263
227
  verdict=$(PLOT_BRANCH="$br" PLOT_DEFAULT="$DEFAULT" PLOT_MERGE="$merge" \
264
228
  PLOT_GIVEN_UP="$deferred" PLOT_OPEN_PR="$open_pr" \
265
- PLOT_TREE="$tree" \
266
229
  PLOT_CHECKED_OUT="$([ -n "$wt" ] && echo true || echo false)" \
267
230
  PLOT_RULE="$RULE_PATH" \
268
231
  node --input-type=module - <<'NODE_EOF' 2>/dev/null
269
- // An ABSOLUTE path derived from this script, never from the cwd: this runs
270
- // wherever the operator invoked it, and the reconcile suite runs it against
271
- // sandbox repos in the temp directory.
232
+ // An ABSOLUTE path derived from this script, never from the cwd.
272
233
  //
273
- // NO APOSTROPHE MAY APPEAR ANYWHERE IN THIS BLOCK. bash 3.2 is /bin/bash on
274
- // macOS, and it is what the reconcile suite runs this script under when it
275
- // strips PATH. It parses the body of a quoted heredoc nested inside `$(...)`,
276
- // so one contraction opens a string that never closes and the whole file fails
277
- // to parse. The error reads `unexpected EOF` and names a line 30 further down,
278
- // which points nowhere near the apostrophe.
279
- const { finishedWith } = await import(process.env.PLOT_RULE);
280
-
281
- const held = finishedWith({
282
- branch: process.env.PLOT_BRANCH,
283
- defaultBranch: process.env.PLOT_DEFAULT,
284
- // This script never looks at the main checkout as a tree; the branch test
285
- // the rule makes is what catches the default branch.
234
+ // NO APOSTROPHE MAY APPEAR ANYWHERE IN THIS BLOCK. bash 3.2 parses the body of
235
+ // a quoted heredoc nested inside `$(...)`, so one contraction opens a string
236
+ // that never closes and the whole file fails to parse.
237
+ const { firstRefRefusal } = await import(process.env.PLOT_RULE);
238
+ const e = process.env;
239
+ const refusal = firstRefRefusal({
240
+ branch: e.PLOT_BRANCH,
241
+ defaultBranch: e.PLOT_DEFAULT,
286
242
  isMain: false,
287
- // The three the reaper measures and this script does not. They are passed
288
- // empty because the rule shape asks for them, and the tree reading below is
289
- // what makes them honest: with no tree they answer `unknown`, and this
290
- // caller reads none of the three either way.
291
243
  workerPid: null,
292
244
  dirtyPath: "",
293
245
  blockedMarker: false,
294
- merge: process.env.PLOT_MERGE,
295
- givenUp: process.env.PLOT_GIVEN_UP === "true",
296
- openPr: process.env.PLOT_OPEN_PR === "true",
297
- checkedOut: process.env.PLOT_CHECKED_OUT === "true",
298
- tree: process.env.PLOT_TREE,
246
+ merge: { found: "merged", none: "not-merged" }[e.PLOT_MERGE] ?? "unreachable",
247
+ givenUp: e.PLOT_GIVEN_UP === "true",
248
+ openPr: e.PLOT_OPEN_PR === "found",
249
+ openPrUnaskable: e.PLOT_OPEN_PR === "unaskable",
250
+ checkedOut: e.PLOT_CHECKED_OUT === "true",
299
251
  });
300
-
301
- // THE FIVE GUARDS, in the order they have always been tested, and each
302
- // satisfied only by a condition answering `true`. `unknown` permits: it means
303
- // no evidence against deletion, which on this estate is the majority reading
304
- // and the one the script already acted on. `liveWorker`, `uncommittedChanges`
305
- // and `blockedMarker` are in `held` and are deliberately not consulted.
306
- const guards = [
307
- ["given-up", held.givenUp, ""],
308
- ["no-merged-pr", held.noMergedPr, ""],
309
- ["open-pr", held.openPr, ""],
310
- ["checked-out", held.checkedOut, ""],
311
- ["on-default-branch", held.onDefaultBranch, process.env.PLOT_DEFAULT],
312
- ];
313
-
314
- const refusal = guards.find(([, reading]) => reading === "true");
315
-
316
- process.stdout.write(refusal === undefined ? "delete\t" : `${refusal[0]}\t${refusal[2]}`);
252
+ process.stdout.write(refusal === null ? "delete\t" : `${refusal.refusal}\t${refusal.detail}`);
317
253
  NODE_EOF
318
254
  )
319
255
 
@@ -324,7 +260,9 @@ NODE_EOF
324
260
  # produce is empty, and an empty refusal keeps the ref and says so.
325
261
  case "$refusal" in
326
262
  given-up) why="deferred — a given-up branch keeps its ref" ;;
263
+ merge-unaskable) why="the host could not be asked whether a PR merged" ;;
327
264
  no-merged-pr) why="unlanded work — no merged PR" ;;
265
+ open-unaskable) why="the host could not be asked for an open PR" ;;
328
266
  open-pr) why="an open PR is using this branch" ;;
329
267
  checked-out) why="checked out in a worktree — somebody is reading it" ;;
330
268
  on-default-branch) why="the default branch — never deleted" ;;
@@ -240,8 +240,8 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
240
240
  echo " usage: plot-state-receipt.sh --unowned-action <dispatch|approve|deliver|release|restart> <subject> <reason>" >&2
241
241
  echo "" >&2
242
242
  echo " The reason is required because each use names a routing gap, and a gap" >&2
243
- echo " nobody wrote down is one nobody closes. Where the board IS running, the" >&2
244
- echo " controller is the route and this is not needed." >&2
243
+ echo " nobody wrote down is one nobody closes. Where the controller command" >&2
244
+ echo " exists, it is the route and this is not needed." >&2
245
245
  exit 2
246
246
  fi
247
247
  # The action word, or the script name — an operator reaching for this has
@@ -271,7 +271,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
271
271
  echo "plot-state-receipt: recorded an UNOWNED action — $action_script $action_subject"
272
272
  echo " reason: $action_reason"
273
273
  echo " This clears plot-controller-gate.sh for one run of that script. The controller"
274
- echo " is still the route: this exists for a machine running no board."
274
+ echo " command is still the route: this exists where it cannot run."
275
275
  exit 0
276
276
  fi
277
277
 
@@ -284,7 +284,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
284
284
  echo " /plot-release writing 'State: Released'" >&2
285
285
  echo "" >&2
286
286
  echo "--unowned-action is the other layer: a controller-owned action run with no" >&2
287
- echo "controller, for a machine running no board." >&2
287
+ echo "controller command, where it cannot run." >&2
288
288
  echo "" >&2
289
289
  echo "Every other State: write has a command that owns it. Use that command." >&2
290
290
  exit 2