From 5c981102d824e4fa51a66c0ef3f923493f118f72 Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Sun, 15 Nov 2026 15:24:12 -0500 Subject: [PATCH] feat(bin): settle captain holds from Bitbucket Cloud PR events --- FORK.md | 1 + bin/fm-captain-hold.sh | 33 ++++++-- bin/fm-contributions.jq | 17 +++- bin/fm-contributions.sh | 26 ++++-- docs/configuration.md | 4 +- docs/fork-configuration.md | 17 ++++ tests/fm-contributions-bitbucket.test.sh | 100 ++++++++++++++++++++++- 7 files changed, 182 insertions(+), 16 deletions(-) diff --git a/FORK.md b/FORK.md index f6bd536b94a..7071cd92641 100644 --- a/FORK.md +++ b/FORK.md @@ -11,6 +11,7 @@ It is current with upstream through commit `427056c4` (2026-11-12). | Bitbucket Cloud pull requests | Work whose pull request lives on Bitbucket Cloud is tracked like a GitHub pull request or GitLab merge request. Firstmate notices when it merges and shows its state in crew status, using your own signed-in `twg`. You still merge it yourself on Bitbucket. | | Unanswered Bitbucket review comments | You are told when a reviewer's comment on a Bitbucket pull request goes unanswered for a time you choose. Review-bot comments count only when attached to a line of code, and you can skip named commenters. | | Bitbucket pull request alerts | Optional alerts when a Bitbucket pull request has a merge conflict, a failed merge check, a failed build, or an unresolved review thread. Firstmate only tells you and never changes the pull request. | +| Bitbucket pull requests that answer a held decision | A decision you have put on hold can be answered automatically when its Bitbucket pull request merges, is declined or superseded, or either. You are also told once if the pull request is closed without merging. Firstmate never touches the pull request itself. | | Open pull request with nobody watching | You are told once when a pull request is still open but nothing is monitoring it any more, for example after the no-mistakes daemon restarted, so it does not sit unnoticed. | | Jira status that follows the work | A task's Jira work item moves to In Progress when work starts, Review when its pull request is ready, and Done when it merges. A Jira failure never blocks your work. | diff --git a/bin/fm-captain-hold.sh b/bin/fm-captain-hold.sh index 1c1caadab10..fe93ab389ea 100755 --- a/bin/fm-captain-hold.sh +++ b/bin/fm-captain-hold.sh @@ -220,8 +220,9 @@ # or no longer a captain hold, and with a non-zero exit naming the cause when # the question changed or the PR ended in the other terminal state. # A `release` policy waits while the home is away, like `answer --release`, and -# a later settle-pr applies it. Only github.com PRs supported -# by the contribution observer qualify. settle-pr reads that observer's durable, +# a later settle-pr applies it. Only github.com and Bitbucket Cloud PRs supported +# by the contribution observer qualify. tasks-axi cannot link a Bitbucket PR +# through --pr, so pr-policy names its URL in the hold's title instead. settle-pr reads that observer's durable, # validated terminal evidence, never caller-supplied state or a captain answer. # It records forge-closed/forge-released reconciliation evidence before changing # the task, and retries interrupted settlement without duplicating the record. @@ -1840,20 +1841,42 @@ $(body_hold_set_timestamp "$(show_field_value "$1" body)") $(resolution_record_count "$(show_field "$1" body)")" } +show_has_link() { # : the task's structured links name this URL + local word + local -a words=() + IFS=, read -r -a words <<< "$(show_field_value "$1" links)" + for word in ${words[@]+"${words[@]}"}; do + [ "${word#*:}" != "$2" ] || return 0 + done + return 1 +} + command_pr_policy() { local id=${1:-} url=${2:-} event=${3:-} action=${4:-} show dir tmp occurrence fingerprint [ "$#" -eq 4 ] || { usage >&2; exit 2; } [ -f "$CONFIG/hold-pr-settle" ] || fail 'config/hold-pr-settle is required' validate_slug task-id "$id" - jq -ne --arg url "$url" '$url | test("^https://github[.]com/[A-Za-z0-9-]+/[A-Za-z0-9._-]+/pull/[1-9][0-9]*$")' >/dev/null \ - || fail 'pr-policy requires a canonical github.com PR URL' + jq -ne --arg url "$url" '$url | test("^https://github[.]com/[A-Za-z0-9-]+/[A-Za-z0-9._-]+/pull/[1-9][0-9]*$") + or test("^https://bitbucket[.]org/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/pull-requests/[1-9][0-9]*$")' >/dev/null \ + || fail 'pr-policy requires a canonical github.com or bitbucket.org PR URL' case "$event" in merged|closed|terminal) ;; *) fail 'event must be merged, closed, or terminal' ;; esac case "$action" in close|release) ;; *) fail 'action must be close or release' ;; esac acquire_task_control_lock "$id" require_tasks_axi command_open "$id" || fail "task $id is not an open captain hold" - tasks_axi update "$id" --pr "$url" >/dev/null || fail "could not link the PR on $id" + case "$url" in + https://bitbucket.org/*) + # tasks-axi only links GitHub or Forgejo PRs through --pr, so a Bitbucket + # PR is linked by naming its URL in the title, which the backlog reads as a link. + task_show_or_fail "$id" "task $id disappeared while declaring its PR policy" + show_has_link "$show" "$url" \ + || tasks_axi update "$id" --title "$(show_field_value "$show" title) $url" >/dev/null \ + || fail "could not link the PR on $id" + ;; + *) tasks_axi update "$id" --pr "$url" >/dev/null || fail "could not link the PR on $id" ;; + esac task_show_or_fail "$id" "task $id disappeared while declaring its PR policy" + show_has_link "$show" "$url" || fail "could not link the PR on $id" fingerprint=$(pr_hold_fingerprint "$show") occurrence=$(( $(resolution_record_count "$(show_field "$show" body)") + 1 )) dir="$DATA/$id" diff --git a/bin/fm-contributions.jq b/bin/fm-contributions.jq index 62f17e9838e..7c318b8686d 100644 --- a/bin/fm-contributions.jq +++ b/bin/fm-contributions.jq @@ -71,7 +71,7 @@ def known($input; $saved): | [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired | map(select(. as $pair | any($retired[]; . == $pair) | not)); # Bitbucket pull requests a fleet task recorded as its pr=, plus those already -# observed. Read only when review-thread tracking is on. +# observed. bitbucket_polled below decides which of them poll reads. def bitbucket_known($input; $saved): ([($input.tasks // [])[] | select(.kind != "secondmate") | select(.pr.url | bitbucket_url) | {task:.id,url:.pr.url}] @@ -79,6 +79,21 @@ def bitbucket_known($input; $saved): | unique_by([.task,.url]) | [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired | map(select(. as $pair | any($retired[]; . == $pair) | not)); +# The Bitbucket pull requests poll and arm --if-owned read. With thread tracking +# on, that is every one bitbucket_known names. With config/hold-pr-settle +# present, a held task's linked Bitbucket PR is read as well, and with tracking +# off it is the only one read, so its terminal state can settle the hold. +def bitbucket_polled($input; $saved; $track; $settle): + [($input.backlog.records // [])[] | select(.structured == true and .hold_bucket != null) | .id] as $held + | (bitbucket_known($input; $saved) + + (if $settle then + [($input.backlog.records // [])[] | select(.structured == true and .hold_bucket != null) as $task + | ($task.links // [])[] | select(bitbucket_url) | {task:$task.id,url:.}] + else [] end)) + | map(select($track or ($settle and (.task as $task | $held | index($task) != null)))) + | unique_by([.task,.url]) + | [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired + | map(select(. as $pair | any($retired[]; . == $pair) | not)); def latest_checks: group_by(.name) | map(sort_by([(.started_at // ""),(.id // 0)]) | last); def projected($input; $saved; $now; $max_age): diff --git a/bin/fm-contributions.sh b/bin/fm-contributions.sh index ab907642710..54a2894c371 100755 --- a/bin/fm-contributions.sh +++ b/bin/fm-contributions.sh @@ -37,6 +37,10 @@ # other accepted URLs remain visibly unmeasured. A Bitbucket Cloud pull request # is the one exception, described with the reply age below, and is never a # coverage row. +# With config/hold-pr-settle present, a Bitbucket pull request named by a held +# task's backlog row is also observed, even with the reply age unset, so that its +# merged, declined or superseded state can settle the hold; an untracked read +# keeps no thread list and changes nothing on the forge. # poll skips unsupported URLs without forge calls, unavailable output, wakes or # new error stamps, and clears their legacy errors without changing observation, # timestamps or ownership evidence. @@ -201,7 +205,8 @@ # state and unanswered threads alone, so these pull requests never become # coverage rows, counts or unmeasured entries. arm copies the ignore setting # into the generated check, as it does the reply age, and arm --if-owned -# counts a Bitbucket pull request only while the reply age is set. +# counts a Bitbucket pull request only while the reply age is set or a held +# task's linked one can settle its hold. # Source bodies are data, never commands. # All mutations serialize on this home's .contributions.lock. Writes refuse # symlinks and publish by rename. No forge writes are performed. @@ -257,6 +262,8 @@ if [ -n "$REPLY_AGE" ]; then else REPLY_AGE=0 fi +SETTLE_HOLDS=false +[ ! -f "$CONFIG/hold-pr-settle" ] || SETTLE_HOLDS=true case "$BUDGET" in ''|*[!0-9]*) fail 'invalid poll budget' ;; esac [ "$BUDGET" -ge 1 ] && [ "$BUDGET" -le 25 ] || fail 'poll budget must be 1..25 seconds' CHECK_TIMEOUT=${FM_CHECK_TIMEOUT:-30} @@ -774,16 +781,15 @@ poll() { | if . != null and (.observation.state | IN("merged","closed")) then .error == null else null end] as $final | [(if all($final[]; .) then "settled" elif any($final[]; . != null) then "final" else "live" end), $known.url] + $known.tasks | @tsv' > "$TMP/known.tsv" - if [ "$TRACK_THREADS" = true ]; then - jq_lib -nr --slurpfile input "$TMP/input.json" --slurpfile saved "$TMP/saved.json" ' - bitbucket_known($input[0];$saved[0]) + jq_lib -nr --slurpfile input "$TMP/input.json" --slurpfile saved "$TMP/saved.json" \ + --argjson track "$TRACK_THREADS" --argjson settle "$SETTLE_HOLDS" ' + bitbucket_polled($input[0];$saved[0];$track;$settle) | group_by(.url) | map({url:.[0].url,tasks:(map(.task) | unique)}) | .[] | . as $known | [$known.tasks[] as $task | [$saved[0][] | select(.task == $task) | .records[] | select(.url == $known.url)] | first | if . != null and (.observation.state | IN("merged","closed")) then .error == null else null end] as $final | [(if all($final[]; .) then "settled" elif any($final[]; . != null) then "final" else "live" end), $known.url] + $known.tasks | @tsv' >> "$TMP/known.tsv" - fi : > "$TMP/live.tsv" # One pass picks the retained closures still owed to an open captain hold, so # a home's settled history costs no process per row. @@ -853,7 +859,9 @@ poll() { | ($tracked | map(.key)) as $live | ($due | map(.key)) as $due_keys | $old + {checked_at:$now,error:null, - observation:($o + {absent_checks:((($old.observation.absent_checks // []) + [($old.observation.checks // [])[] | .name]) - [$o.checks[].name] | unique)}), + observation:($o + {absent_checks:((($old.observation.absent_checks // []) + [($old.observation.checks // [])[] | .name]) - [$o.checks[].name] | unique)} + # Untracked Bitbucket reads settle holds only; keep no thread list. + | if $track or (has("threads") | not) then . else .threads = [] end), seen:((($old.seen // []) + ($events | map(.token))) | unique), pending:((($old.pending // []) + $arrived | map(select(.type != "unanswered" or (.thread as $k | ($live | index($k)) != null and ($due_keys | index($k)) == null)))) @@ -879,9 +887,11 @@ arm() { acquire if [ "${1:-}" = --if-owned ]; then get_input; read_saved - # A Bitbucket pull request counts only while review-thread tracking is on. + # A Bitbucket pull request counts only while review-thread tracking is on or + # a held task's linked one can settle its hold. if [ "$ERRORS" -eq 0 ] && ! jq_lib -ne --slurpfile input "$TMP/input.json" --argjson track "$TRACK_THREADS" \ - --slurpfile saved "$TMP/saved.json" 'known($input[0];$saved[0]) + (if $track then bitbucket_known($input[0];$saved[0]) else [] end) | length > 0' >/dev/null; then + --argjson settle "$SETTLE_HOLDS" --slurpfile saved "$TMP/saved.json" \ + 'known($input[0];$saved[0]) + bitbucket_polled($input[0];$saved[0];$track;$settle) | length > 0' >/dev/null; then return 0 fi fi diff --git a/docs/configuration.md b/docs/configuration.md index b78d73e3865..41c4d2173b5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -878,7 +878,9 @@ The flag is a home-local preference and is not inherited by secondmate homes. The optional local, gitignored `config/hold-pr-settle` presence flag enables settlement of explicitly declared PR-dependent captain holds. Create the empty flag in the owning home and use `bin/fm-captain-hold.sh pr-policy` to declare each hold's settlement policy. The command's `--help` owns its arguments and durable record format. -The existing contribution observer applies matching GitHub merge or closure evidence, including observations retained after the worker stops. +The existing contribution observer applies matching GitHub or Bitbucket Cloud merge or closure evidence, including observations retained after the worker stops. +A Bitbucket Cloud PR linked to a held task is read for its terminal state even when `config/contributions-reply-age` is unset, and it is never merged or otherwise changed. +A declined or superseded Bitbucket PR counts as an unmerged closure. It also reports an unmerged closure through the contribution notification channel, once for each owning task that is still an open captain hold after settlement. A task without a captain hold gets no closure notification, so enabling the flag does not replay historical closed PRs. No captain answer is invented, and unrelated holds remain open. diff --git a/docs/fork-configuration.md b/docs/fork-configuration.md index bd575c41dd5..6611db25e4e 100644 --- a/docs/fork-configuration.md +++ b/docs/fork-configuration.md @@ -31,6 +31,23 @@ export FM_CONTRIBUTIONS_REPLY_AGE=1800 export FM_CONTRIBUTIONS_IGNORE_COMMENTERS=ci-bot ``` +## Bitbucket pull requests that answer a held decision + +`config/hold-pr-settle` is the upstream flag that lets a pull request event answer a decision you have put on hold. +In this fork it also works for Bitbucket Cloud pull requests, so a hold can be answered when the pull request merges, is declined or superseded, or either. +It needs no reply age: a Bitbucket pull request linked to a held decision is checked for its final state even when `config/contributions-reply-age` is unset. +Firstmate only settles the hold and never changes the pull request. + +| Setting | What it controls | +| --- | --- | +| `config/hold-pr-settle` | An empty file that turns the feature on. Without it, nothing settles and no extra closure notice is sent. | + +```sh +# Turn it on, then declare that a Bitbucket pull request closes the decision when it merges. +touch config/hold-pr-settle +bin/fm-captain-hold.sh pr-policy my-decision https://bitbucket.org/myworkspace/my-repo/pull-requests/7 merged close +``` + ## Jira status transitions `config/jira-status-transitions` turns on Jira status follow-through for the projects it lists. diff --git a/tests/fm-contributions-bitbucket.test.sh b/tests/fm-contributions-bitbucket.test.sh index 40940fb3081..bb3b70d3252 100755 --- a/tests/fm-contributions-bitbucket.test.sh +++ b/tests/fm-contributions-bitbucket.test.sh @@ -293,8 +293,106 @@ SH pass 'a GitHub pull request is read, shaped and projected as before beside a Bitbucket one' } +# hold_home : a home with no fleet task, one held decision linking the Bitbucket PR, and settlement on. +hold_home() { + local home + home=$(new_home "$1") + rm "$home/state/task-a.meta" + touch "$home/config/hold-pr-settle" + with_home "$home" "$ROOT/bin/fm-tasks-axi.sh" add decision "Decide this PR $URL" >/dev/null || fail 'add failed' + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" hold decision --reason 'Decide this PR' >/dev/null || fail 'hold failed' + printf '%s\n' "$home" +} + +poll_untracked() { # home now: a poll with reply-age tracking off + local home=$1 now=$2 + with_home "$home" env FM_CONTRIBUTIONS_NOW="$now" "$ROOT/bin/fm-contributions.sh" poll +} + +test_hold_policy_accepts_a_bitbucket_url() { + local home + home=$(hold_home policy-url) + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision "$URL" merged close >/dev/null \ + || fail 'a Bitbucket pull request URL was refused' + jq -e --arg url "$URL" '.url == $url and .on == "merged" and .action == "close"' "$home/data/decision/hold-pr-policy.json" >/dev/null \ + || fail 'the Bitbucket policy was not recorded' + # A hold that does not name the pull request yet is linked by the declaration. + with_home "$home" "$ROOT/bin/fm-tasks-axi.sh" add unlinked 'Decide without a link' >/dev/null || fail 'add failed' + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" hold unlinked --reason 'Decide without a link' >/dev/null || fail 'hold failed' + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy unlinked "$URL" terminal release >/dev/null || fail 'an unlinked hold was not linked' + with_home "$home" "$ROOT/bin/fm-tasks-axi.sh" show unlinked --full | grep -F "$URL" >/dev/null || fail 'the declaration did not link the pull request' + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" open unlinked || fail 'linking the pull request released the hold' + if with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision https://bitbucket.org/myworkspace/pull-requests/7 merged close 2>/dev/null; then + fail 'a malformed Bitbucket URL was accepted' + fi + if with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision https://example.com/o/r/pull-requests/7 merged close 2>/dev/null; then + fail 'a foreign host was accepted' + fi + pass 'pr-policy accepts a canonical Bitbucket pull request URL and nothing looser' +} + +test_merged_bitbucket_pr_settles_a_hold_without_reply_age() { + local home out body + home=$(hold_home settle-merged) + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision "$URL" merged close >/dev/null || fail 'policy failed' + out=$(poll_untracked "$home" "$T0") || fail 'open poll failed' + [ -z "$out" ] || fail "an open pull request produced output: $out" + jq -e '.records[0].observation.state == "open" and (.records[0].observation.threads | length) == 0' "$home/data/decision/contributions.json" >/dev/null \ + || fail 'an untracked read kept a thread list' + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" open decision || fail 'an open pull request settled the hold' + write_pr "$home" MERGED '[]' + out=$(poll_untracked "$home" "$HOUR") || fail 'merged poll failed' + [ -z "$out" ] || fail "a successful settlement produced poll output: $out" + if with_home "$home" "$ROOT/bin/fm-captain-hold.sh" open decision; then fail 'a merged Bitbucket pull request left the hold open'; fi + body=$(with_home "$home" "$ROOT/bin/fm-tasks-axi.sh" show decision --full) + printf '%s\n' "$body" | grep -F "Forge PR merged: $URL" >/dev/null || fail 'terminal evidence missing from the settled hold' + printf '%s\n' "$body" | grep -F 'Captain decision:' >/dev/null && fail 'forge event claimed a captain answer' + [ ! -e "$home/data/decision/hold-pr-policy.json" ] || fail 'a settled policy was kept' + [ ! -s "$home/forge/gh.log" ] || fail "settlement reached gh: $(cat "$home/forge/gh.log")" + pass 'a merged Bitbucket pull request settles its declared hold with reply-age tracking off' +} + +test_closed_bitbucket_pr_settles_and_notifies_once() { + local home state out + for state in DECLINED SUPERSEDED; do + home=$(hold_home "settle-$state") + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision "$URL" merged close >/dev/null || fail 'policy failed' + write_pr "$home" "$state" '[]' + out=$(poll_untracked "$home" "$HOUR") || fail "$state poll failed" + # The policy waits for a merge, so the other terminal state drops it and keeps the hold. + printf '%s\n' "$out" | grep -Fq 'dropped the PR policy for decision' || fail "$state did not drop the merge-only policy: $out" + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" open decision || fail "$state closed a merge-only hold" + with_home "$home" "$ROOT/bin/fm-contributions.sh" pending \ + | jq -e --arg url "$URL" '[.[] | select(.type == "closed" and .url == $url) | .task] == ["decision"]' >/dev/null \ + || fail "$state closure was not reported once to the held task" + poll_untracked "$home" 2026-09-16T10:00:00Z >/dev/null || fail 'repeat poll failed' + with_home "$home" "$ROOT/bin/fm-contributions.sh" pending | jq -e '[.[] | select(.type == "closed")] | length == 1' >/dev/null \ + || fail "$state closure was reported twice" + # An unmerged closure settles a hold that declared it. + with_home "$home" "$ROOT/bin/fm-captain-hold.sh" pr-policy decision "$URL" terminal close >/dev/null || fail 'second policy failed' + poll_untracked "$home" 2026-09-16T11:00:00Z >/dev/null || fail 'settling poll failed' + if with_home "$home" "$ROOT/bin/fm-captain-hold.sh" open decision; then fail "$state did not settle a terminal policy"; fi + done + pass 'a declined or superseded Bitbucket pull request is an unmerged closure, reported once and settled by a terminal policy' +} + +test_bitbucket_hold_needs_the_flag_and_a_hold() { + local home + home=$(hold_home flag-off) + rm "$home/config/hold-pr-settle" + poll_untracked "$home" "$T0" >/dev/null || fail 'poll without the flag failed' + [ ! -s "$home/forge/twg.log" ] || fail 'a Bitbucket pull request was read without the flag or reply age' + home=$(new_home no-hold) + rm "$home/state/task-a.meta" + touch "$home/config/hold-pr-settle" + with_home "$home" "$ROOT/bin/fm-tasks-axi.sh" add plain "Plain work $URL" >/dev/null || fail 'add failed' + poll_untracked "$home" "$T0" >/dev/null || fail 'poll without a hold failed' + [ ! -s "$home/forge/twg.log" ] || fail 'a Bitbucket pull request of an unheld task was read' + pass 'an untracked Bitbucket pull request is read only for a held task with settlement enabled' +} + failures=0 -for test_name in test_unanswered_thread_is_raised_after_the_age_and_again test_author_reply_answers test_resolved_thread_is_answered test_bot_comments_are_ignored test_inline_bot_comments_count test_merged_pull_request_ends_tracking test_unset_setting_reads_nothing test_arm_and_coverage test_failed_read_is_reported_once test_github_path_is_unchanged; do +for test_name in test_unanswered_thread_is_raised_after_the_age_and_again test_author_reply_answers test_resolved_thread_is_answered test_bot_comments_are_ignored test_inline_bot_comments_count test_merged_pull_request_ends_tracking test_unset_setting_reads_nothing test_arm_and_coverage test_failed_read_is_reported_once test_github_path_is_unchanged test_hold_policy_accepts_a_bitbucket_url test_merged_bitbucket_pr_settles_a_hold_without_reply_age test_closed_bitbucket_pr_settles_and_notifies_once test_bitbucket_hold_needs_the_flag_and_a_hold; do ( "$test_name" ) || failures=$((failures + 1)) done [ "$failures" -eq 0 ] || fail "$failures Bitbucket contribution regressions"