@plot-pm/board 0.19.0 → 0.20.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/plot-host.sh CHANGED
@@ -74,6 +74,12 @@
74
74
  # empty answer sends the reaper to a weaker
75
75
  # reading, so only a recognised lookup miss is
76
76
  # empty.
77
+ # pr-review <number> one JSON line `{"sha","state","bypass"}`: the PR's
78
+ # head sha, the newest `plot/review` status on it
79
+ # (`success|failure|pending|error`, or `absent`),
80
+ # and whether a comment starts `review-bypass:`.
81
+ # Bitbucket EXITS 4 (unaskable). EXIT 3 is the
82
+ # question failing.
77
83
  # pr-create --title T [--body B] [--base BR] [--head BR] [--draft]
78
84
  # create a PR, print its URL
79
85
  # pr-merge <number> [--squash] [--delete-branch] [--match-head <sha>]
@@ -255,7 +261,26 @@
255
261
  # human click as merely pending forever.
256
262
  # NOTHING on bitbucket (bb has no run listing) —
257
263
  # unavailable, never "no run".
258
- # issue-list [--limit N] open tracker issues as JSON lines:
264
+ # issue-list [--limit N] [--state open|closed] [--since <iso>] [--page-token T] [--paged]
265
+ # tracker issues as JSON lines, open by default.
266
+ # `--state closed` needs `--since` (a date, or
267
+ # a date and `THH:MM`) and adds `closedAt` to
268
+ # each row, in no promised order — the caller
269
+ # sorts: GitHub keeps what closed at or after
270
+ # `since`; Jira requires `Ticket prefixes`,
271
+ # reads `since`'s time in the reader's Jira
272
+ # profile zone (JQL takes no offset), and reads
273
+ # one page of 100, printing
274
+ # `{"nextPageToken":"…"}` as a last line for the
275
+ # caller to pass back as `--page-token`. The
276
+ # closed read and an open read given `--paged`
277
+ # print that line, and on Jira ask 100 rows a
278
+ # page; an open read without `--paged` prints
279
+ # issue rows alone. EXIT 4 where the closed read
280
+ # cannot be asked at all: Bitbucket (`bb issue
281
+ # list` prints no closing date) and Jira with no
282
+ # `Ticket prefixes`, both before any bb or curl.
283
+ # Open issues:
259
284
  # {"number":N,"title":"…","url":"…",
260
285
  # "createdAt":"…","status":"…",
261
286
  # "statusCategory":"…"}
@@ -279,10 +304,8 @@
279
304
  # abandoned work beside finished work.
280
305
  # READ-ONLY. Plot writes no label, no assignee
281
306
  # and no close-on-merge, because a copy of
282
- # tracker state ages into a lie. The one write
283
- # that exists is `issue-status`, and it records
284
- # a status Plot itself just caused rather than
285
- # mirroring one the tracker holds.
307
+ # tracker state ages into a lie. The two
308
+ # writes are `issue-status` and `issue-open`.
286
309
  # `url` is "" when the host omits it, and a
287
310
  # consumer renders the number as plain text
288
311
  # rather than inventing an address — the rule
@@ -343,7 +366,15 @@
343
366
  # as issue-list. Jira answers 404 for a missing
344
367
  # key, which is exit 3 here (the tracker moved),
345
368
  # never an empty body.
346
- # issue-status <key> <status> THE ONE WRITE TO A TRACKER: record one status
369
+ # issue-open <request-json> (jira)
370
+ # issue-open <title> <body> [--label <label>...] (github-issues)
371
+ # THE SECOND OF TWO WRITES TO A TRACKER: open
372
+ # one issue. Prints Jira's JSON answer or the
373
+ # new GitHub issue's address. The connector
374
+ # builds the Jira request, including the
375
+ # `Tracker issue type` key's word (default
376
+ # `Task`). Exit 4 with the reason elsewhere.
377
+ # issue-status <key> <status> THE FIRST OF TWO WRITES: record one status
347
378
  # against one issue, and nothing else. No
348
379
  # create, no close, no comment, no label — a
349
380
  # plan referencing an issue is Plot's record,
@@ -414,6 +445,43 @@
414
445
  # Actions, ekzweb is Bitbucket + Jenkins.
415
446
  # Jenkins reports no limit, so it answers
416
447
  # `predicted`.
448
+ # commit-status <sha> <state> <context> <description> <url>
449
+ # GITHUB AND BITBUCKET. On GitHub, writes a
450
+ # commit status via `POST
451
+ # /repos/{owner}/{repo}/statuses/{sha}`,
452
+ # authenticated as a GitHub App installation —
453
+ # NOT the signed-in `gh` user — so the review
454
+ # verdict carries its own identity rather than
455
+ # whoever's laptop ran this. The App ID and a
456
+ # path to its private key come from the
457
+ # `Review app` config key (`<app id> <key
458
+ # path>`, read via plot-config.sh); a relative
459
+ # key path resolves against the repository
460
+ # root. EXIT 4, naming the key, where `Review
461
+ # app` is absent or its key file cannot be
462
+ # read — a configuration gap, not a transient:
463
+ # this script mints no token against a default
464
+ # App and asks no `gh`-signed-in identity in
465
+ # its place. On Bitbucket, writes a build status
466
+ # via `POST /2.0/repositories/{workspace}
467
+ # /{repo_slug}/commit/{sha}/statuses/build`,
468
+ # authenticated with a dedicated account's App
469
+ # password — BITBUCKET_REVIEW_USER and
470
+ # BITBUCKET_REVIEW_APP_PASSWORD, read from the
471
+ # environment or this repository's `.env`, NOT
472
+ # from `bb`'s own signed-in identity — mapping
473
+ # GitHub's state word to Bitbucket's
474
+ # (success→SUCCESSFUL, failure→FAILED). EXIT 4,
475
+ # naming both variables, where neither is
476
+ # configured; EXIT 4 naming `unsupported` where
477
+ # the workspace/repo cannot be resolved from
478
+ # `origin` or `state` has no mapping. A backend
479
+ # with no arm at all exits 4 too. `state` is one
480
+ # of GitHub's own words
481
+ # (success|failure|error|pending); `context`
482
+ # groups repeat statuses on one sha (this
483
+ # estate's caller passes `plot/review`). A call
484
+ # that reaches the API and fails exits 3.
417
485
  #
418
486
  # TRANSPORT IS NOT A CALLER'S CONCERN. Where a host offers a question over more
419
487
  # than one transport — GitHub's REST against its GraphQL — the choice is made
@@ -451,6 +519,16 @@ plot_tmpfile HOST_ERR host-err || { echo "plot-host: no temp file could be made
451
519
 
452
520
  die() { echo "plot-host: $*" >&2; exit 1; }
453
521
 
522
+ # Rows in one page of an issue read: `maxResults` on Jira, and the rows `gh issue
523
+ # list` fetches per request inside its one process.
524
+ ISSUE_PAGE_ROWS=100
525
+
526
+ # Reports the host CLI's own words from the last call and exits 3 — a question
527
+ # that failed, as opposed to exit 4 (cannot be asked) or an answered empty list.
528
+ # An empty message or a recognised lookup miss is an answer; anything else exits 3.
529
+ miss_or_exit3() { [ -z "$1" ] || is_lookup_miss "$1" || { echo "plot-host: $1" >&2; exit 3; }; }
530
+ gh_fail() { echo "plot-host: $(cat "$HOST_ERR" 2>/dev/null)" >&2; rm -f "$HOST_ERR"; exit 3; }
531
+
454
532
  # Exit 3 — reserved for "the op itself cannot proceed", distinct from `die`'s
455
533
  # generic 1. A Jenkins overlay with no instance to ask is such a case: a config
456
534
  # error a person must fix, not a transient the board should retry past.
@@ -1307,102 +1385,6 @@ ci_scheme() {
1307
1385
  ci_raw | awk '{print tolower($1)}'
1308
1386
  }
1309
1387
 
1310
- # Whether a candidate token is a host `jen -I` could be given.
1311
- #
1312
- # A URL passes whole. Otherwise it must be dot-separated labels ending in an
1313
- # alphabetic TLD, carrying no path separator and no `@`.
1314
- #
1315
- # THE FINAL FILTER IS THE FILE EXTENSION, and that is a measurement rather than
1316
- # a preference. `ci.yml` and `package.json` both match the dotted-label pattern,
1317
- # while `.ch` and `.io` are real two-letter TLDs — so TLD LENGTH cannot separate
1318
- # a host from a filename in either direction, and a `CI:` value naming a
1319
- # workflow file (`github-actions (see .github/workflows/ci.yml)`) is the
1320
- # measured case that would otherwise be read as a server.
1321
- ci_looks_like_host() {
1322
- case "$1" in
1323
- https://*|http://*) return 0 ;;
1324
- */*|*@*) return 1 ;;
1325
- esac
1326
- printf '%s\n' "$1" \
1327
- | grep -qE '^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*\.[a-z]{2,}$' || return 1
1328
- case "$1" in
1329
- *.yml|*.yaml|*.json|*.md|*.sh|*.js|*.ts|*.mjs|*.cjs|*.toml|*.xml|*.txt|*.lock|*.gradle) return 1 ;;
1330
- esac
1331
- return 0
1332
- }
1333
-
1334
- # Where this repository's CI lives: the `Jenkins instance` key, then
1335
- # `$JENKINS_INSTANCE`, then a host read out of the `CI` value. Empty when none
1336
- # of the three names one.
1337
- #
1338
- # THE ORDER IS NOT THE TRACKER'S, and the reason is information content.
1339
- # `tracker_base_url()` lets `$PLOT_JIRA_BASE_URL` win over its config value
1340
- # because both carry the same shape — a URL. Here the key carries MORE than the
1341
- # prose can express: `jenkins_instance()` (`:665`) returns `<slug>/<job/path>`,
1342
- # and the container path is a fact no file in a repository states
1343
- # (`stack.ts:98` calls the host *"the SLUG half"*). A prose-derived slug alone
1344
- # degrades `jenkins_build_map()` to root-scope listing, where its own comment
1345
- # says *"every branch reads `none`"* — and `quaweb` is nested
1346
- # (`job/quaweb/job/release`), so that renders an empty board for the exact
1347
- # repository this serves. So the explicit key is the primary and the prose is
1348
- # the fallback, never the other way round.
1349
- #
1350
- # IT EXTRACTS A HOST, NOT A REMAINDER. "Everything after the first token" was
1351
- # measured against all three real values and fails on every one:
1352
- # `at jenkins-ci-ewz… (Bitbucket PRs…`, `pipelines in .build/pipelines/ …`,
1353
- # `(e.g. continuous-build…)`. None is a host, and handing `jen -I` a sentence
1354
- # is worse than handing it nothing. `Tracker:` gets away with the naive split
1355
- # because its value is a scheme and a URL; `CI:` is prose in every repository
1356
- # that declares it.
1357
- #
1358
- # A BACKTICKED SPAN IS PREFERRED because the backticks are a deliberate act —
1359
- # the writer pointed at the value. It must still look like a host: one real
1360
- # repository marks up a PATH (`` `.build/pipelines/` ``), which is not a server.
1361
- #
1362
- # BACKTICKS ARE STRIPPED AND NO SCHEME IS NORMALISED ON. `ewz` writes a bare
1363
- # host in backticks and the probe used a full `https://` URL; `jen -I` accepts
1364
- # either, so inventing a canonical form would break whichever caller passes the
1365
- # other one.
1366
- #
1367
- # EMPTY IS AN ANSWER, not a failure: `Jenkins (e.g. continuous-build, …)` names
1368
- # no instance. Read the exit code, never the emptiness.
1369
- ci_instance() {
1370
- local instance candidate
1371
- instance=$(bash "$here/plot-config.sh" get "Jenkins instance" "" 2>/dev/null || echo "")
1372
- [ -n "$instance" ] || instance="${JENKINS_INSTANCE:-}"
1373
- if [ -n "$instance" ]; then
1374
- printf '%s' "$instance"
1375
- return
1376
- fi
1377
-
1378
- local value
1379
- value="$(ci_raw)"
1380
-
1381
- # The backticked spans, in order: `tr` puts each on its own line, so the
1382
- # even-numbered lines are what sat between a pair of backticks.
1383
- while IFS= read -r candidate; do
1384
- [ -n "$candidate" ] || continue
1385
- if ci_looks_like_host "$candidate"; then
1386
- printf '%s' "$candidate"
1387
- return
1388
- fi
1389
- done <<EOF
1390
- $(printf '%s\n' "$value" | tr '\`' '\n' | awk 'NR % 2 == 0')
1391
- EOF
1392
-
1393
- # Otherwise the first bare token that looks like a host. Punctuation that
1394
- # ends a clause is split off so `(jenkins.acme.dev)` reads as the host.
1395
- while IFS= read -r candidate; do
1396
- [ -n "$candidate" ] || continue
1397
- if ci_looks_like_host "$candidate"; then
1398
- printf '%s' "$candidate"
1399
- return
1400
- fi
1401
- done <<EOF
1402
- $(printf '%s\n' "$value" | tr -d '\`' | tr ' \t,()[]<>"'"'" '\n')
1403
- EOF
1404
- }
1405
-
1406
1388
  # Fetch Jenkins build statuses for every branch in a multibranch job, in ONE
1407
1389
  # call, and return them as a JSON object keyed by DECODED branch name.
1408
1390
  #
@@ -2239,7 +2221,6 @@ bb_lacks_issue_command() {
2239
2221
 
2240
2222
  # Cached capability state — empty until first call to bb_require_json.
2241
2223
  BB_CAP_CHECKED=""
2242
- BB_CAP_HAS_JSON=""
2243
2224
  BB_CAP_IDENTITY="" # "craftamap/0.6.0" or "quatico/1.2.3" or "unknown/<ver>"
2244
2225
  BB_CAP_PROBE_RC="" # the exit code `bb pr list --help --json` returned
2245
2226
  BB_CAP_PROBE_MATCH="" # the line that matched a rejection pattern, if one did
@@ -2349,7 +2330,6 @@ bb_require_json() {
2349
2330
 
2350
2331
  # Allow tests to skip this (their stubs may not implement --help)
2351
2332
  if [ -n "${PLOT_BB_SKIP_CAP_CHECK:-}" ]; then
2352
- BB_CAP_HAS_JSON=1
2353
2333
  BB_CAP_IDENTITY="stub/test"
2354
2334
  return 0
2355
2335
  fi
@@ -2357,7 +2337,6 @@ bb_require_json() {
2357
2337
  BB_CAP_IDENTITY="$(bb_identify)"
2358
2338
 
2359
2339
  if ! bb_test_json_support; then
2360
- BB_CAP_HAS_JSON=0
2361
2340
  # THE OBSERVATION FIRST, THE IDENTITY WHERE ONE IS KNOWN.
2362
2341
  #
2363
2342
  # The plan asked for the observation and for dropping the provenance CLAIM
@@ -2373,7 +2352,6 @@ bb_require_json() {
2373
2352
  die3 "bb ($BB_CAP_IDENTITY): bb pr list --help --json exited ${BB_CAP_PROBE_RC:-?}${BB_CAP_PROBE_MATCH:+, matched: $BB_CAP_PROBE_MATCH} — this bb does not support --json for PR commands"
2374
2353
  fi
2375
2354
 
2376
- BB_CAP_HAS_JSON=1
2377
2355
  return 0
2378
2356
  }
2379
2357
 
@@ -2626,8 +2604,6 @@ jira_curl() {
2626
2604
  # $1 = path (e.g. /rest/api/2/search/jql?...), remaining args appended to curl.
2627
2605
  # Config is assumed present — jira_require_config ran in the caller's shell.
2628
2606
  local path="$1"; shift
2629
- local base
2630
- base="$(tracker_base_url)"
2631
2607
  # -sS: quiet progress, but keep errors. -w writes the HTTP status on its own
2632
2608
  # line AFTER the body so the caller can split the two. --user does the Basic
2633
2609
  # base64 for us; the token never appears in argv of any child process here.
@@ -2635,7 +2611,7 @@ jira_curl() {
2635
2611
  --user "${JIRA_EMAIL}:${JIRA_API_TOKEN}" \
2636
2612
  -H 'Accept: application/json' \
2637
2613
  -w '\n%{http_code}' \
2638
- "$base$path" "$@"
2614
+ "$(tracker_base_url)$path" "$@"
2639
2615
  local rc=$?
2640
2616
  # JIRA IS COUNTED HERE AND NOT BY A WRAPPER, because it is reached through
2641
2617
  # `curl` rather than a CLI of its own — and shadowing `curl` would count every
@@ -2719,6 +2695,10 @@ jira_check() {
2719
2695
  printf '%s' "$body"
2720
2696
  }
2721
2697
 
2698
+ # jira_curl, then jira_check: the response body on stdout, or exit 3 with the
2699
+ # reason on stderr. Every Jira op asks through this pair and through nothing else.
2700
+ jira_ask() { local raw rc; raw="$(jira_curl "$@")"; rc=$?; jira_check "$raw" "$rc"; }
2701
+
2722
2702
  # --- pr-list truncation detection (#333) ------------------------------------
2723
2703
  #
2724
2704
  # `pr-list` returns a bulk page that two consumers (plot-fleet-scan.sh:474 and
@@ -3011,7 +2991,12 @@ plot_on_exit budget_memo_clear
3011
2991
  # account cannot be read still share one real budget, and dropping their lines
3012
2992
  # would under-count the machine — the failure this plan exists to remove. They
3013
2993
  # group together under one honest name instead.
2994
+ #
2995
+ # JIRA IS KEYED BY `jira_budget_account`, the key `budget_record_jira` writes,
2996
+ # and `PLOT_BUDGET_ACCOUNT` does not override it, because that writer reads no
2997
+ # override either.
3014
2998
  budget_account() {
2999
+ [ "${1:-}" != jira ] || { jira_budget_account; return; }
3015
3000
  if [ -n "${PLOT_BUDGET_ACCOUNT:-}" ]; then printf '%s\n' "$PLOT_BUDGET_ACCOUNT"; return; fi
3016
3001
  local who=''
3017
3002
  case "$1" in
@@ -3784,12 +3769,7 @@ case "$op" in
3784
3769
  # A lookup miss is an answer: no PR, so no merge commit. Anything else
3785
3770
  # is the question failing, and silence must not read as "carried
3786
3771
  # nothing" — the caller distinguishes the two by the exit code.
3787
- if [ -z "$err" ] || is_lookup_miss "$err"; then
3788
- :
3789
- else
3790
- echo "plot-host: $err" >&2
3791
- exit 3
3792
- fi
3772
+ miss_or_exit3 "$err"
3793
3773
  fi
3794
3774
  else
3795
3775
  bb_require_json
@@ -3800,12 +3780,7 @@ case "$op" in
3800
3780
  | map(.merge_commit.hash // empty) | first // empty' <<<"$out"
3801
3781
  else
3802
3782
  err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3803
- if [ -z "$err" ] || is_lookup_miss "$err"; then
3804
- :
3805
- else
3806
- echo "plot-host: $err" >&2
3807
- exit 3
3808
- fi
3783
+ miss_or_exit3 "$err"
3809
3784
  fi
3810
3785
  fi
3811
3786
  ;;
@@ -3860,6 +3835,12 @@ case "$op" in
3860
3835
  fi
3861
3836
  ;;
3862
3837
 
3838
+ pr-review)
3839
+ [ "$be" = "github" ] || { echo "plot-host: pr-review: bitbucket is not supported yet" >&2; exit 4; }
3840
+ out="$(gh pr view "${1:?pr-review needs a PR number}" --json headRefOid,comments)" && st="$(gh api "repos/{owner}/{repo}/commits/$(jq -r .headRefOid <<<"$out")/statuses")" \
3841
+ && jq -c --argjson st "$st" '{sha: .headRefOid, state: ([$st[] | select(.context == "plot/review")][0].state // "absent"), bypass: any(.comments[]?; .body | startswith("review-bypass:"))}' <<<"$out" \
3842
+ || { echo "plot-host: pr-review: the read failed" >&2; exit 3; } ;;
3843
+
3863
3844
  pr-create)
3864
3845
  title=""; body=""; base=""; head=""; draft=0
3865
3846
  while [ $# -gt 0 ]; do
@@ -4626,13 +4607,21 @@ case "$op" in
4626
4607
  # of them reproduces `an-outage-is-not-an-answer` — a board that says "no
4627
4608
  # issues" because it could not reach the tracker is stating a fact it does
4628
4609
  # not have.
4629
- limit=""
4610
+ limit=""; state="open"; since=""; page_token=""; paged=""
4630
4611
  while [ $# -gt 0 ]; do
4631
4612
  case "$1" in
4632
4613
  --limit) limit="${2:?}"; shift 2 ;;
4614
+ --state) state="${2:?}"; shift 2 ;;
4615
+ --since) since="${2:?}"; shift 2 ;;
4616
+ --page-token) page_token="${2:?}"; shift 2 ;;
4617
+ --paged) paged=1; shift ;;
4633
4618
  *) die "issue-list: unknown arg $1" ;;
4634
4619
  esac
4635
4620
  done
4621
+ # `--since` is spliced into a JQL string and a search qualifier, so its shape
4622
+ # is checked here: a value outside it is a usage error, never a query.
4623
+ [[ "$state" =~ ^(open|closed|inbox)$ ]] || die "issue-list: --state is open, closed or inbox, not '$state'"
4624
+ [ "$state" != closed ] || [[ "$since" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}[0-9:.]*Z?)?$ ]] || die "issue-list: --state closed needs --since <iso>"
4636
4625
  limit_args=()
4637
4626
  [ -n "$limit" ] && limit_args=(--limit "$limit")
4638
4627
  # WHO LISTS THESE ISSUES IS ASKED ONCE, HERE, BEFORE THE ARMS — after the
@@ -4640,13 +4629,10 @@ case "$op" in
4640
4629
  # rather than as a tracker refusal. The arms below then dispatch on the
4641
4630
  # ANSWER, never on a second reading of the config.
4642
4631
  source_said="$(issue_source)" || exit 1
4643
- if [ "${source_said%%$'\t'*}" = "nobody" ]; then
4644
- # Exit 4, the code this op already documents as *this host cannot be
4645
- # asked at all* — a configuration a person fixes, not a call to retry.
4646
- # NOTHING HAS BEEN SPENT: no `gh`, no `bb`, no curl has run yet.
4647
- echo "plot-host: ${source_said#*$'\t'}" >&2
4648
- exit 4
4649
- fi
4632
+ # Exit 4, the code this op already documents as *this host cannot be
4633
+ # asked at all* — a configuration a person fixes, not a call to retry.
4634
+ # NOTHING HAS BEEN SPENT: no `gh`, no `bb`, no curl has run yet.
4635
+ [ "${source_said%%$'\t'*}" != nobody ] || { echo "plot-host: ${source_said#*$'\t'}" >&2; exit 4; }
4650
4636
  if [ "$source_said" = $'tracker\tjira' ]; then
4651
4637
  # Jira, resolved through the REST API — DISPATCHED ON `Tracker`, never on
4652
4638
  # `backend()`: a Bitbucket repo tracking in Jira is the normal enterprise
@@ -4671,31 +4657,57 @@ case "$op" in
4671
4657
  # AN UNDECLARED KEY LEAVES THE QUERY BYTE-IDENTICAL. `$scope` is empty,
4672
4658
  # the two halves rejoin exactly as they were written, and an upgrade
4673
4659
  # changes nothing for a repository that never set the key.
4674
- scope=""
4675
- if projects="$(tracker_projects)" && [ -n "$projects" ]; then
4660
+ scope=""; if projects="$(tracker_projects)" && [ -n "$projects" ]; then
4676
4661
  # `IN (A, B)`, never a trailing comma: paste joins N-1 separators over N
4677
4662
  # elements, so a one-element list — what adoption's seed writes — yields
4678
4663
  # `IN (A)` rather than `IN (A,)`.
4679
4664
  scope=" AND project IN ($(printf '%s' "$projects" | paste -sd, - | sed 's/,/, /g'))"
4680
4665
  fi
4666
+ # THE PERSON CLAUSE DROPS ONCE A PROJECT SCOPE EXISTS (D20): the open and
4667
+ # closed reads keep `assignee = currentUser()` only where `$scope` is
4668
+ # empty. The inbox read below keeps it unconditionally, and the scope too.
4669
+ person=""; [ -n "$scope" ] || person="assignee = currentUser() AND "
4681
4670
  # PLOT_JIRA_JQL STILL WINS OVER BOTH. Teams worked around this bug with
4682
4671
  # their own JQL; an override that stopped overriding would break exactly
4683
4672
  # the people who noticed the problem first.
4684
- jql="${PLOT_JIRA_JQL:-assignee = currentUser() AND resolution = EMPTY${scope} ORDER BY created DESC}"
4673
+ jql="${PLOT_JIRA_JQL:-${person}resolution = EMPTY${scope} ORDER BY created DESC}"
4685
4674
  # maxResults bounds ONE page. The inbox is small by construction (a
4686
- # person's open tickets), so no nextPageToken loop is needed; the caller's
4687
- # --limit caps it, else Jira's default page. v2 `search/jql` takes the same
4688
- # params as v3 but returns `summary`/`description` as plain strings.
4675
+ # person's open tickets), so its default stays 50; the caller's --limit
4676
+ # caps it. A paged read (`--paged`, and every closed read) asks at most
4677
+ # ISSUE_PAGE_ROWS per page and prints the next page's token. v2
4678
+ # `search/jql` takes the same params as v3 but returns
4679
+ # `summary`/`description` as plain strings.
4689
4680
  max="${limit:-50}"
4681
+ fields="summary,created,status,assignee"
4682
+ if [ "$state" = closed ]; then
4683
+ # THE CLOSED READ REQUIRES `Ticket prefixes` AND READS NOT PLOT_JIRA_JQL.
4684
+ # An unscoped `resolved >=` query reads the whole instance — the hazard
4685
+ # `tracker_projects` measured for the open read — so with none declared
4686
+ # the read exits 4 before any curl. `jira_require_config` follows. The
4687
+ # closed read is always paged: a page is ISSUE_PAGE_ROWS, and the
4688
+ # TypeScript adapter walks the pages, so this arm holds no loop. JQL dates take
4689
+ # `yyyy-MM-dd` or `yyyy-MM-dd HH:mm`, so the ISO `since` is cut to the
4690
+ # shape it has: a date-only `since` sends the date alone. JQL takes no
4691
+ # offset, so Jira reads the time in the reader's profile zone. Its
4692
+ # person clause drops with the open read's (D20), same reason.
4693
+ [ -n "$scope" ] || { echo "plot-host: closed Jira issues need 'Ticket prefixes' declared; an unscoped resolved query reads the whole instance" >&2; exit 4; }
4694
+ when="${since:0:10} ${since:11:5}"; jql="resolved >= \"${when% }\"${scope} ORDER BY resolved DESC"
4695
+ fields="$fields,resolutiondate"; paged=1
4696
+ # THE D23 INBOX READ: always person-scoped, and project-scoped by `$scope`
4697
+ # like the open read, so *Waiting on you* shows the reader's own tickets of this repository's projects.
4698
+ elif [ "$state" = inbox ]; then jql="${PLOT_JIRA_JQL:-assignee = currentUser() AND resolution = EMPTY${scope} ORDER BY created DESC}"
4699
+ fi
4700
+ [ -z "$paged" ] || { max="${limit:-$ISSUE_PAGE_ROWS}"; [ "$max" -le "$ISSUE_PAGE_ROWS" ] || max="$ISSUE_PAGE_ROWS"; }
4701
+ token_args=(); [ -z "$page_token" ] || token_args=(--data-urlencode "nextPageToken=$page_token")
4690
4702
  # jq builds the query string so a JQL with spaces/quotes is encoded once,
4691
4703
  # not hand-escaped. --data-urlencode via curl -G keeps the token out of the
4692
4704
  # URL and the JQL correctly encoded.
4693
- raw="$(jira_curl "/rest/api/2/search/jql" \
4705
+ body="$(jira_ask "/rest/api/2/search/jql" \
4694
4706
  -G \
4695
4707
  --data-urlencode "jql=$jql" \
4696
- --data-urlencode "fields=summary,created,status" \
4697
- --data-urlencode "maxResults=$max")"; curl_rc=$?
4698
- body="$(jira_check "$raw" "$curl_rc")" || exit $?
4708
+ --data-urlencode "fields=$fields" \
4709
+ --data-urlencode "maxResults=$max" \
4710
+ ${token_args[@]+"${token_args[@]}"})" || exit $?
4699
4711
  # `number` is the Jira KEY (PROJ-123), a string — #447 taught the parser to
4700
4712
  # read that form. `url` is built from the base + /browse/<key>; Jira's
4701
4713
  # search payload carries no browse URL, and the base is ours to know
@@ -4707,14 +4719,20 @@ case "$op" in
4707
4719
  # substitutes for the other: the name is what a person reads, the
4708
4720
  # category is what a board groups on. A board grouping on the name
4709
4721
  # fragments across projects that spell the same stage differently.
4710
- printf '%s' "$body" | jq -c --arg base "$base" '.issues[]? | {
4722
+ # A closed row adds `closedAt`, the ticket's `resolutiondate`. A paged
4723
+ # read prints the next page's token as a LAST JSON line,
4724
+ # `{"nextPageToken":"…"}`, for the adapter to strip and loop on. An open
4725
+ # read without `--paged` prints no token line: the readers of that read
4726
+ # take every line as an issue.
4727
+ printf '%s' "$body" | jq -c --arg base "$base" --arg state "$state" --arg paged "$paged" '(.issues[]? | {
4711
4728
  number: .key,
4712
4729
  title: (.fields.summary // ""),
4713
4730
  url: ($base + "/browse/" + .key),
4714
4731
  createdAt: (.fields.created // ""),
4715
4732
  status: (.fields.status.name // ""),
4716
- statusCategory: (.fields.status.statusCategory.name // "")
4717
- }'
4733
+ statusCategory: (.fields.status.statusCategory.name // ""), assignees: ([.fields.assignee.emailAddress // .fields.assignee.accountId] | map(select(. != null)))
4734
+ } + (if $state == "closed" then {closedAt: (.fields.resolutiondate // "")} else {} end)),
4735
+ (select($paged == "1") | (.nextPageToken // empty) | {nextPageToken: .})'
4718
4736
  elif [ "$be" = "github" ]; then
4719
4737
  # `gh issue list` — not `gh api /issues`. On GitHub every PR IS an issue,
4720
4738
  # so the REST endpoint returns both, and every open PR would arrive here
@@ -4727,21 +4745,29 @@ case "$op" in
4727
4745
  # a second literal would be a copy that a widened filter silently
4728
4746
  # outdates. `To Do` is the category because an open GitHub issue is
4729
4747
  # unstarted by the only vocabulary GitHub has.
4730
- gh_state="open"
4748
+ gh_state="$state"
4749
+ # A CLOSED READ IS THE SAME ARM with `closedAt` asked for and a search that
4750
+ # keeps what closed since `$since`. GitHub search has no close-date sort
4751
+ # (`sort:closed-desc` was measured ignored, 2026-10-13), so the adapter
4752
+ # sorts by `closedAt`.
4753
+ gh_json="number,title,url,createdAt,assignees"; search_args=()
4754
+ [ "$gh_state" = open ] || { gh_json+=",closedAt"; search_args=(--search "closed:>=$since"); }
4731
4755
  if out="$(gh issue list --state "$gh_state" ${limit_args[@]+"${limit_args[@]}"} \
4732
- --json number,title,url,createdAt 2>"$HOST_ERR")"; then
4756
+ ${search_args[@]+"${search_args[@]}"} --json "$gh_json" 2>"$HOST_ERR")"; then
4733
4757
  rm -f "$HOST_ERR"
4734
4758
  jq -c --arg status "$gh_state" \
4735
4759
  '.[] | {number:.number,title:.title,url:(.url // ""),createdAt:(.createdAt // ""),
4736
- status:$status,statusCategory:(if $status == "open" then "To Do" else "Done" end)}' <<<"$out"
4760
+ status:$status,statusCategory:(if $status == "open" then "To Do" else "Done" end),assignees:[.assignees[]?.login]}
4761
+ + (if $status == "closed" then {closedAt:(.closedAt // "")} else {} end)' <<<"$out"
4762
+ # `gh` pages by 100 inside ONE process and the wrapper records one call
4763
+ # per process, so each page past the first is recorded here.
4764
+ jq -r "[range(1; length / $ISSUE_PAGE_ROWS | ceil)] | .[]" <<<"$out" | while read -r _; do budget_record_call github github graphql; done
4737
4765
  else
4738
- err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
4739
4766
  # NO empty-list fallback. `host_miss_or_fail` exists for a lookup whose
4740
4767
  # subject is absent — one PR that does not exist. A LIST has no absent
4741
4768
  # subject: if the call failed, the answer is unknown, and printing
4742
4769
  # nothing while exiting non-zero is what says so.
4743
- echo "plot-host: $err" >&2
4744
- exit 3
4770
+ gh_fail
4745
4771
  fi
4746
4772
  else
4747
4773
  # `bb issue list` — measured against bb 0.6.0. Three things the GitHub arm
@@ -4750,6 +4776,10 @@ case "$op" in
4750
4776
  # data; (2) it has no `--limit`, so the caller's bound is honoured HERE,
4751
4777
  # after parsing; (3) the list carries no per-issue URL, so `url` is "" —
4752
4778
  # the same answer the header documents for a host that omits it.
4779
+ #
4780
+ # A CLOSED READ IS EXIT 4: `bb issue list` prints no closing date, so there
4781
+ # is nothing honest to return. It runs before any `bb` command.
4782
+ [ "$state" = open ] || { echo "plot-host: bitbucket cannot list closed issues; bb prints no closing date" >&2; exit 4; }
4753
4783
  bb_assert_issue_version || exit $?
4754
4784
  # `--state new,open` is bb's own default for `issue list` and is what
4755
4785
  # "open tracker issues" means; stated explicitly so a bb default change
@@ -4791,25 +4821,17 @@ case "$op" in
4791
4821
  # neither is a Jira category. Empty says *this vocabulary has no word
4792
4822
  # for it*, which a board can render; inventing `Done` for WONTFIX
4793
4823
  # would file abandoned work beside finished work.
4794
- case "$state" in
4795
- NEW|OPEN) category="To Do" ;;
4796
- RESOLVED|CLOSED) category="Done" ;;
4797
- *) category="" ;;
4798
- esac
4799
4824
  # Drop the trailing reporter: bb prints three spaces then `by <name>`.
4800
4825
  title="$(sed -E 's/[[:space:]]{2,}by [^[:space:]].*$//' <<<"$rest")"
4801
4826
  # `url` is "" — bb issue list prints none; a consumer renders the number
4802
4827
  # as plain text, the rule the header states.
4803
- jq -cn --argjson number "$num" --arg title "$title" \
4804
- --arg status "$state" --arg category "$category" \
4805
- '{number:$number,title:$title,url:"",createdAt:"",
4806
- status:$status,statusCategory:$category}'
4828
+ jq -cn --argjson number "$num" --arg title "$title" --arg status "$state" \
4829
+ '{number:$number,title:$title,url:"",createdAt:"",status:$status,
4830
+ statusCategory:({NEW:"To Do",OPEN:"To Do",RESOLVED:"Done",CLOSED:"Done"}[$status] // "")}'
4807
4831
  count=$((count + 1))
4808
4832
  # Honour the caller's --limit HERE: bb has no --limit, so a bound the
4809
4833
  # caller asked for is enforced by the adapter after parsing (Done-when 7).
4810
- if [ -n "$limit" ] && [ "$count" -ge "$limit" ]; then
4811
- break
4812
- fi
4834
+ [ -z "$limit" ] || [ "$count" -lt "$limit" ] || break
4813
4835
  done <<<"$raw"
4814
4836
  fi
4815
4837
  ;;
@@ -4829,10 +4851,7 @@ case "$op" in
4829
4851
  # question with the same three answers and the same exit codes. A consumer
4830
4852
  # that maps 4 to `unsupported` needs no second table to read this op.
4831
4853
  source_said="$(issue_source)" || exit 1
4832
- if [ "${source_said%%$'\t'*}" = "nobody" ]; then
4833
- echo "plot-host: ${source_said#*$'\t'}" >&2
4834
- exit 4
4835
- fi
4854
+ [ "${source_said%%$'\t'*}" != nobody ] || { echo "plot-host: ${source_said#*$'\t'}" >&2; exit 4; }
4836
4855
  if [ "$source_said" = $'tracker\tjira' ]; then
4837
4856
  # Jira, dispatched on `Tracker` not `backend()` — the same rule issue-list
4838
4857
  # follows. `num` is a Jira KEY (PROJ-123), read off issue-list moments ago.
@@ -4846,9 +4865,8 @@ case "$op" in
4846
4865
  # adapter, so its absence (Jira answers 404) means the tracker moved under
4847
4866
  # the board. jira_check turns that 404 into exit 3 with empty stdout.
4848
4867
  jira_require_config
4849
- raw="$(jira_curl "/rest/api/2/issue/$num" \
4850
- -G --data-urlencode "fields=summary,description")"; curl_rc=$?
4851
- body_json="$(jira_check "$raw" "$curl_rc")" || exit $?
4868
+ body_json="$(jira_ask "/rest/api/2/issue/$num" \
4869
+ -G --data-urlencode "fields=summary,description")" || exit $?
4852
4870
  base="$(tracker_base_url)"
4853
4871
  printf '%s' "$body_json" | jq -c --arg base "$base" '{
4854
4872
  number: .key,
@@ -4861,7 +4879,6 @@ case "$op" in
4861
4879
  rm -f "$HOST_ERR"
4862
4880
  jq -c '{number:.number,title:(.title // ""),body:(.body // ""),url:(.url // "")}' <<<"$out"
4863
4881
  else
4864
- err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
4865
4882
  # NO miss/fail split here, and that is deliberate. `host_miss_or_fail`
4866
4883
  # exists where an absent subject is a NORMAL answer — a branch with no
4867
4884
  # PR. An issue number reaching this op was read off `issue-list`
@@ -4869,8 +4886,7 @@ case "$op" in
4869
4886
  # means the tracker moved under the board. Both shapes exit non-zero
4870
4887
  # with the CLI's own words, so the caller says *could not be read*
4871
4888
  # rather than planning against an empty body.
4872
- echo "plot-host: $err" >&2
4873
- exit 3
4889
+ gh_fail
4874
4890
  fi
4875
4891
  else
4876
4892
  # `bb issue view <n>` — measured against bb 0.6.0. The output, once ANSI
@@ -4945,16 +4961,14 @@ case "$op" in
4945
4961
  # and Jira answers a transition to the state an issue already holds by
4946
4962
  # naming no such transition — which this reports as `no-target` rather than
4947
4963
  # as a failure.
4948
- key="${1:?issue-status needs an issue key}"; shift
4949
- want="${1:?issue-status needs a status}"; shift
4964
+ key="${1:?issue-status needs an issue key}"; want="${2:?issue-status needs a status}"
4950
4965
  [ "$(tracker_scheme)" = "jira" ] || exit 4
4951
4966
  jira_require_config
4952
4967
  # THE TRANSITION IS LOOKED UP, NEVER GUESSED. Jira transitions are per
4953
4968
  # workflow and per issue: the id for "In Progress" differs between projects
4954
4969
  # and the transition may not be available from the issue's current state at
4955
4970
  # all. A hardcoded id writes a status to the wrong column silently.
4956
- raw="$(jira_curl "/rest/api/2/issue/$key/transitions")"; curl_rc=$?
4957
- body_json="$(jira_check "$raw" "$curl_rc")" || exit $?
4971
+ body_json="$(jira_ask "/rest/api/2/issue/$key/transitions")" || exit $?
4958
4972
  tid="$(printf '%s' "$body_json" | jq -r --arg want "$want" \
4959
4973
  '[.transitions[]? | select((.name // "" | ascii_downcase) == ($want | ascii_downcase)
4960
4974
  or ((.to.name // "" | ascii_downcase) == ($want | ascii_downcase)))]
@@ -4967,13 +4981,29 @@ case "$op" in
4967
4981
  printf '%s\n' 'no-target'
4968
4982
  exit 0
4969
4983
  fi
4970
- raw="$(jira_curl "/rest/api/2/issue/$key/transitions" \
4971
- -X POST -H 'Content-Type: application/json' \
4972
- --data "$(jq -cn --arg id "$tid" '{transition:{id:$id}}')")"; curl_rc=$?
4973
- jira_check "$raw" "$curl_rc" >/dev/null || exit $?
4984
+ jira_ask "/rest/api/2/issue/$key/transitions" \
4985
+ -X POST -H 'Content-Type: application/json' \
4986
+ --data "$(jq -cn --arg id "$tid" '{transition:{id:$id}}')" >/dev/null || exit $?
4974
4987
  printf '%s\n' 'written'
4975
4988
  ;;
4976
4989
 
4990
+ issue-open)
4991
+ # THE SECOND WRITE TO A TRACKER: open one issue, and nothing else. NOT
4992
+ # IDEMPOTENT: the same call twice opens two issues, and this op never looks
4993
+ # for a duplicate, so the caller records what it opened. The connector
4994
+ # builds the request and reads the identifier out of the answer; this op
4995
+ # sends the one and prints the other.
4996
+ # jira <request-json> the POST /rest/api/2/issue body, sent
4997
+ # verbatim; prints Jira's JSON answer.
4998
+ # github-issues <title> <body> [--label <label>...]; prints the new
4999
+ # issue's address.
5000
+ # Exit 4, with the reason, for any other tracker.
5001
+ case "$(tracker_scheme)" in
5002
+ jira) jira_require_config; jira_ask /rest/api/2/issue -X POST -H 'Content-Type: application/json' --data-raw "${1:?issue-open needs a request}" || exit $? ;;
5003
+ github-issues) gh issue create --title "${1:?issue-open needs a title}" --body "${2-}" "${@:3}" 2>"$HOST_ERR" || gh_fail ;;
5004
+ *) echo "plot-host: issue-open answers for jira and github-issues only, not '$(tracker_scheme)'" >&2; exit 4 ;;
5005
+ esac ;;
5006
+
4977
5007
  pr-body)
4978
5008
  num="${1:?pr-body needs a PR number}"; shift
4979
5009
  body=""
@@ -5221,7 +5251,7 @@ case "$op" in
5221
5251
  # `perHour` IS null WHERE THERE IS NO SPAN TO DIVIDE BY — one line, or
5222
5252
  # several written inside one millisecond. An invented rate would be exactly
5223
5253
  # the dishonest cadence input this slice exists to remove.
5224
- _sr_connector=""; _sr_account=""; _sr_bucket=""
5254
+ _sr_connector="$be"; _sr_account=""; _sr_bucket=""
5225
5255
  while [ $# -gt 0 ]; do
5226
5256
  case "$1" in
5227
5257
  --connector) _sr_connector="${2:?}"; shift 2 ;;
@@ -5232,9 +5262,9 @@ case "$op" in
5232
5262
  done
5233
5263
  # Defaults name THIS connector and THIS account, which is what a caller
5234
5264
  # asking "what am I spending?" means. An explicit triple is for a caller
5235
- # asking about a connector it is not itself using.
5236
- [ -n "$_sr_connector" ] || _sr_connector="$be"
5237
- [ -n "$_sr_account" ] || _sr_account="$(budget_account "$be")"
5265
+ # asking about a connector it is not itself using. An omitted `--account`
5266
+ # names this machine's account on the connector asked.
5267
+ [ -n "$_sr_account" ] || _sr_account="$(budget_account "$_sr_connector")"
5238
5268
  # AN OMITTED `--bucket` MEANS EVERY BUCKET, which is what *what am I
5239
5269
  # spending?* asks. One connector meters several pools independently, and the
5240
5270
  # cadence this feeds is about how fast the ACCOUNT is going — it spends both,
@@ -5245,7 +5275,23 @@ case "$op" in
5245
5275
  '{connector:$connector,account:$account,bucket:$bucket} + .' <<<"$_sr_rate"
5246
5276
  ;;
5247
5277
 
5278
+ commit-status)
5279
+ # GITHUB AND BITBUCKET — the only two words `backend` above ever returns,
5280
+ # which already refused anything else before this case ran. Each backend's
5281
+ # logic lives in its own Node helper, never inline here —
5282
+ # `plot-commit-status.mjs` holds the GitHub App JWT/installation-token
5283
+ # exchange; `plot-bitbucket-commit-status.mjs` holds the Bitbucket state
5284
+ # mapping and Basic-auth build-status write, given a workspace/repo slug
5285
+ # parsed here from `origin` (never from `bb`, which would mean asking
5286
+ # whichever identity is signed in on this machine) — `.git` is stripped
5287
+ # before capturing the slug, not inside a trailing optional group, or a
5288
+ # greedy match absorbs it into the slug itself.
5289
+ [ "$be" = "github" ] || { node "$here/plot-bitbucket-commit-status.mjs" "$(git config --get remote.origin.url 2>/dev/null | sed -E 's#\.git$##' | sed -nE 's#^.*bitbucket\.org[:/]([^/]+)/(.+)$#\1/\2#p')" "$@" || exit $?; exit 0; }
5290
+ node "$here/plot-commit-status.mjs" --check "$@" || exit $?
5291
+ node "$here/plot-commit-status.mjs" --repo "$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)" "$@" || exit $?
5292
+ ;;
5293
+
5248
5294
  *)
5249
- die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|pr-body|rate-limit|limit|ci-limit|spend-rate)"
5295
+ die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|issue-open|pr-body|pr-review|rate-limit|limit|ci-limit|spend-rate|commit-status)"
5250
5296
  ;;
5251
5297
  esac