@intentius/chant 0.124.89 → 0.124.90

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.
Files changed (163) hide show
  1. package/dist/ci-comment-commands.d.ts +18 -2
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +30 -2
  4. package/dist/ci-job-guard.d.ts +42 -45
  5. package/dist/ci-job-guard.d.ts.map +1 -1
  6. package/dist/ci-job-guard.js +206 -3
  7. package/dist/ci-note-commands.d.ts +41 -1
  8. package/dist/ci-note-commands.d.ts.map +1 -1
  9. package/dist/ci-note-commands.js +64 -5
  10. package/dist/ci-product.d.ts +41 -1
  11. package/dist/ci-product.d.ts.map +1 -1
  12. package/dist/ci-product.js +44 -7
  13. package/dist/cli/handlers/pr-comment.d.ts +13 -1
  14. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  15. package/dist/cli/handlers/pr-comment.js +90 -1
  16. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  17. package/dist/cli/handlers/pr-notes.js +23 -1
  18. package/dist/cli/handlers/pr.js +16 -14
  19. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  20. package/dist/cli/handlers/run-wave.js +154 -4
  21. package/dist/cli/main.d.ts.map +1 -1
  22. package/dist/cli/main.js +17 -0
  23. package/dist/cli/parse-args.d.ts.map +1 -1
  24. package/dist/cli/parse-args.js +15 -0
  25. package/dist/cli/registry.d.ts +8 -1
  26. package/dist/cli/registry.d.ts.map +1 -1
  27. package/dist/components/pr-checks.d.ts +28 -1
  28. package/dist/components/pr-checks.d.ts.map +1 -1
  29. package/dist/components/pr-checks.js +35 -2
  30. package/dist/components/pr-pipeline.d.ts +3 -2
  31. package/dist/components/pr-pipeline.d.ts.map +1 -1
  32. package/dist/components/pr-pipeline.js +4 -2
  33. package/dist/components/product-pipeline.d.ts +54 -2
  34. package/dist/components/product-pipeline.d.ts.map +1 -1
  35. package/dist/components/product-pipeline.js +59 -5
  36. package/dist/components/product-plan.d.ts +13 -1
  37. package/dist/components/product-plan.d.ts.map +1 -1
  38. package/dist/components/product-plan.js +36 -10
  39. package/dist/floor-table.data.d.ts.map +1 -1
  40. package/dist/floor-table.data.js +32 -23
  41. package/dist/lexicon.d.ts +82 -4
  42. package/dist/lexicon.d.ts.map +1 -1
  43. package/dist/lifecycle/gate-applied.d.ts +9 -0
  44. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  45. package/dist/op/apply-status.d.ts +84 -0
  46. package/dist/op/apply-status.d.ts.map +1 -0
  47. package/dist/op/apply-status.js +106 -0
  48. package/dist/op/before-merge-decide.d.ts +102 -0
  49. package/dist/op/before-merge-decide.d.ts.map +1 -0
  50. package/dist/op/before-merge-decide.js +142 -0
  51. package/dist/op/before-merge-done.d.ts +56 -0
  52. package/dist/op/before-merge-done.d.ts.map +1 -0
  53. package/dist/op/before-merge-done.js +69 -0
  54. package/dist/op/before-merge-store.d.ts +20 -0
  55. package/dist/op/before-merge-store.d.ts.map +1 -0
  56. package/dist/op/before-merge-store.js +48 -0
  57. package/dist/op/before-merge.d.ts +150 -0
  58. package/dist/op/before-merge.d.ts.map +1 -0
  59. package/dist/op/before-merge.js +207 -0
  60. package/dist/op/follow-on-run.d.ts +117 -0
  61. package/dist/op/follow-on-run.d.ts.map +1 -0
  62. package/dist/op/follow-on-run.js +154 -0
  63. package/dist/op/follow-on-store.d.ts +17 -0
  64. package/dist/op/follow-on-store.d.ts.map +1 -0
  65. package/dist/op/follow-on-store.js +54 -0
  66. package/dist/op/gate.d.ts +6 -0
  67. package/dist/op/gate.d.ts.map +1 -1
  68. package/dist/op/gate.js +10 -1
  69. package/dist/op/index.d.ts +3 -1
  70. package/dist/op/index.d.ts.map +1 -1
  71. package/dist/op/index.js +1 -0
  72. package/dist/op/op-waves-after-plan.d.ts +13 -0
  73. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  74. package/dist/op/op-waves-evidence-jobs.d.ts +4 -1
  75. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  76. package/dist/op/op-waves-evidence-jobs.js +10 -2
  77. package/dist/op/op-waves-follow-on.d.ts +162 -0
  78. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  79. package/dist/op/op-waves-follow-on.js +355 -0
  80. package/dist/op/op-waves-run.d.ts +146 -6
  81. package/dist/op/op-waves-run.d.ts.map +1 -1
  82. package/dist/op/op-waves-run.js +871 -99
  83. package/dist/op/op-waves-split.d.ts +122 -0
  84. package/dist/op/op-waves-split.d.ts.map +1 -0
  85. package/dist/op/op-waves-split.js +166 -0
  86. package/dist/op/op-waves.d.ts +20 -0
  87. package/dist/op/op-waves.d.ts.map +1 -1
  88. package/dist/op/op-waves.js +15 -1
  89. package/dist/op/schedule-overdue.d.ts +15 -1
  90. package/dist/op/schedule-overdue.d.ts.map +1 -1
  91. package/dist/op/schedule-overdue.js +18 -2
  92. package/dist/op/stage-hooks.d.ts +36 -1
  93. package/dist/op/stage-hooks.d.ts.map +1 -1
  94. package/dist/op/stage-hooks.js +17 -3
  95. package/dist/op/wave-stop.d.ts +4 -1
  96. package/dist/op/wave-stop.d.ts.map +1 -1
  97. package/dist/op/wave-stop.js +4 -2
  98. package/dist/pr-post.d.ts.map +1 -1
  99. package/dist/pr-post.js +2 -1
  100. package/dist/release-floors.d.ts +3 -1
  101. package/dist/release-floors.d.ts.map +1 -1
  102. package/dist/release-floors.js +21 -19
  103. package/dist/wave-blocked.d.ts +7 -1
  104. package/dist/wave-blocked.d.ts.map +1 -1
  105. package/dist/wave-blocked.js +7 -2
  106. package/dist/wave-runtime.mjs +364 -351
  107. package/package.json +1 -1
  108. package/src/ci-comment-commands.test.ts +63 -0
  109. package/src/ci-comment-commands.ts +43 -4
  110. package/src/ci-image.test.ts +1 -2
  111. package/src/ci-job-guard.before-merge.test.ts +148 -0
  112. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  113. package/src/ci-job-guard.follow-on.test.ts +144 -0
  114. package/src/ci-job-guard.ts +221 -3
  115. package/src/ci-note-commands.test.ts +76 -1
  116. package/src/ci-note-commands.ts +96 -7
  117. package/src/ci-product.ts +55 -7
  118. package/src/cli/handlers/pr-comment.ts +85 -2
  119. package/src/cli/handlers/pr-notes.ts +30 -6
  120. package/src/cli/handlers/pr.ts +14 -11
  121. package/src/cli/handlers/run-wave.ts +144 -4
  122. package/src/cli/main.ts +17 -0
  123. package/src/cli/parse-args.ts +11 -0
  124. package/src/cli/registry.ts +8 -1
  125. package/src/components/pr-checks.ts +55 -2
  126. package/src/components/pr-pipeline.ts +5 -3
  127. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  128. package/src/components/product-pipeline.ts +113 -8
  129. package/src/components/product-plan.test.ts +23 -5
  130. package/src/components/product-plan.ts +43 -12
  131. package/src/floor-table.data.ts +32 -23
  132. package/src/lexicon.ts +78 -1
  133. package/src/lifecycle/gate-applied.ts +7 -0
  134. package/src/op/apply-status.test.ts +83 -0
  135. package/src/op/apply-status.ts +132 -0
  136. package/src/op/before-merge-decide.ts +190 -0
  137. package/src/op/before-merge-done.ts +99 -0
  138. package/src/op/before-merge-store.ts +44 -0
  139. package/src/op/before-merge.test.ts +201 -0
  140. package/src/op/before-merge.ts +266 -0
  141. package/src/op/follow-on-run.ts +206 -0
  142. package/src/op/follow-on-store.ts +54 -0
  143. package/src/op/gate.ts +16 -1
  144. package/src/op/index.ts +5 -0
  145. package/src/op/op-waves-after-plan.ts +13 -0
  146. package/src/op/op-waves-evidence-jobs.ts +11 -3
  147. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  148. package/src/op/op-waves-follow-on.test.ts +247 -0
  149. package/src/op/op-waves-follow-on.ts +385 -0
  150. package/src/op/op-waves-render-spec.test.ts +1 -2
  151. package/src/op/op-waves-run.ts +971 -93
  152. package/src/op/op-waves-split-product.test.ts +288 -0
  153. package/src/op/op-waves-split-step.test.ts +298 -0
  154. package/src/op/op-waves-split.test.ts +196 -0
  155. package/src/op/op-waves-split.ts +189 -0
  156. package/src/op/op-waves.ts +28 -3
  157. package/src/op/schedule-overdue.test.ts +29 -1
  158. package/src/op/schedule-overdue.ts +27 -3
  159. package/src/op/stage-hooks.ts +52 -4
  160. package/src/op/wave-stop.ts +5 -3
  161. package/src/pr-post.ts +2 -1
  162. package/src/release-floors.ts +22 -19
  163. package/src/wave-blocked.ts +9 -4
package/src/ci-product.ts CHANGED
@@ -10,10 +10,10 @@
10
10
  */
11
11
 
12
12
  import type { CiProductWords, CiProductWordsInput } from "./ci-product-words";
13
+ import { NEXT_RELEASE } from "./release-floors";
13
14
  import type { ProductMcpHook } from "./cli/mcp/product-tools";
14
15
  import type { ProductWaveHook } from "./op/op-waves-after-plan";
15
16
  import { OTLP_EXPORTER_FLOOR } from "./otlp";
16
- import { NEXT_RELEASE } from "./release-floors";
17
17
 
18
18
  /**
19
19
  * The first chant with the product pipeline (#4550): the words, the
@@ -151,7 +151,7 @@ export const COMMENT_LEAVES_COMMIT_FLOOR = "0.124.88";
151
151
  /**
152
152
  * The first chant with the comment job on GitHub and Forgejo and the replies to commands no job runs (#4946): `commentJob` in the product pipeline (`chant components pr-comment`, `answerProductComment` in `@intentius/chant/ci-comment-commands`), which replies to a refusal and to a command the pipeline runs no job for, and with waves on merge starts a merged pull request's apply again; the words' `replies` and an alias's `refuse`, which the GitLab note poll reads too, as `chantNoteRuns`' `members`; `retryApply`; and `locks: "plan"` in GitHub's and Forgejo's product plan, with the lock, unlock and comment lock jobs.
153
153
  */
154
- export const COMMENT_COMMANDS_FLOOR = NEXT_RELEASE;
154
+ export const COMMENT_COMMANDS_FLOOR = "0.124.89";
155
155
  export { answerProductComment, answeredElsewhere, COMMENT_JOBS_ENV, commentRuns, PR_COMMENT_JOB, RERUN_APPLY_JOBS, type CommentJobs, type CommentOutcome, type CommentRuns, type AnswerCommentOptions } from "./ci-comment-commands";
156
156
  export { forkReply, memberReply, notRunReply } from "./ci-comment-replies";
157
157
  export type { CiProductCommentReplies } from "./ci-product-words";
@@ -160,7 +160,7 @@ export { productCommentJob, type ProductCommentJob } from "./components/product-
160
160
  /**
161
161
  * The first chant whose product plan locks what a change reaches (#4979): `productPlan.reach`, a reach line the lock job runs at the target branch's commit with `chant lock --reach` (`@intentius/chant/lifecycle/reach-locks`), on GitHub, Forgejo and GitLab, where the lock job runs in the plan notes pipeline with `--open` beside the comment lock and unlock jobs; and whose comment job answers a re-plan comment with flags the product plan's re-plan cannot take (`noPlanFlags`).
162
162
  */
163
- export const PRODUCT_PLAN_REACH_LOCKS_FLOOR = NEXT_RELEASE;
163
+ export const PRODUCT_PLAN_REACH_LOCKS_FLOOR = "0.124.89";
164
164
  export { LOCK_REACH_ENV, reachedTargets, reachOpen, type Reached, type ReachInput } from "./lifecycle/reach-locks";
165
165
  export { productPlanReachLock, type ProductPlanReachLock } from "./components/product-plan";
166
166
  export { planFlagsReply } from "./ci-comment-commands";
@@ -168,14 +168,62 @@ export { planFlagsReply } from "./ci-comment-commands";
168
168
  /**
169
169
  * The first chant whose comment job stops a merged pull request's re-run at a wave (#4979): `/<product> apply wave-<n>` writes a stop for the merge commit on `chant/lifecycle` (`_waves/<op>.stops.json`, `@intentius/chant/op/wave-stop`) before GitHub's re-run or Forgejo's dispatch, and `chant run wave` leaves each wave after n waiting (exit 3).
170
170
  */
171
- export const WAVE_STOP_FLOOR = NEXT_RELEASE;
171
+ export const WAVE_STOP_FLOOR = "0.124.89";
172
172
  export { setWaveStop, waveStopAt, waveStopLine, type WaveStop } from "./op/wave-stop";
173
173
 
174
+ /**
175
+ * The first chant whose Op waves run before merge (#4984): `wavesBeforeMerge` in the product pipeline, where the comment job (GitHub, Forgejo) or the note poll (GitLab) decides `/<product> apply [wave-<n>]` on an open pull request (`decideWavesBeforeMerge`, `@intentius/chant/op/before-merge-decide`), records the head and its digest on `chant/lifecycle` (`_waves/<op>.before-merge.json`) and starts the waves for it; the generators' `beforeMerge`, whose guard admits that head alone, whose jobs check it out and read the base from the default branch, and whose `before-merge-done` job merges and releases the locks (`chant run wave --merge`); `waveJobs.<wave>.prelude`; the GitLab note poll's wave stop (`chantNoteRuns`' `waves`); a re-plan word that never starts with `-`; and the terraform lexicon's reach helpers (`@intentius/chant-lexicon-terraform/reach`).
176
+ */
177
+ export const WAVES_BEFORE_MERGE_FLOOR = NEXT_RELEASE;
178
+ export { BEFORE_MERGE_DIGEST_ENV, BEFORE_MERGE_DONE_JOB, BEFORE_MERGE_HEAD_ENV, BEFORE_MERGE_PR_ENV, beforeMergeDigest, beforeMergePath, beforeMergeProblems, WAVES_BASE_ENV, type BeforeMergeDecision, type BeforeMergeRecord, type OpWavesBeforeMerge } from "./op/before-merge";
179
+ export { decideWavesBeforeMerge, defaultPipelineFiles, type WavesBeforeMergeJobs } from "./op/before-merge-decide";
180
+ export type { ProductWavesBeforeMerge } from "./components/product-pipeline";
181
+
182
+ /**
183
+ * The first chant whose Op waves post the apply statuses (#4987): the generators' `applyStatus`, a job `apply-status-<n>` after each wave at the default branch's commit that posts `<product>/apply` on the commit the waves applied (a before-merge run's decided head) with `chant run wave --apply-status` (`@intentius/chant/op/apply-status`), and the product pipeline's `applyStatus`; whose product plan takes `staleNotes`, each target's note carrying the target branch's commit and a `stale-notes` job beside wave 1 on a push marking each target's note (`pr-post --stale` with one `--member` per target); whose `productPipelineJobs` returns `waves.pipeline` for the generators; and whose GitLab reach line reaches the lock and note-commands jobs unexpanded (`expand: false`).
184
+ */
185
+ export const WAVES_APPLY_STATUS_FLOOR = NEXT_RELEASE;
186
+ export { applyStatusJobName, opWaveApplyStatus, postOpWaveApplyStatus, type OpWaveApplyStatus, type OpWavesApplyStatus } from "./op/apply-status";
187
+
188
+ /**
189
+ * The first chant whose before-merge waves never run the change's code beside a write token (#4987): with `beforeMerge` each wave is a plan job (the change's code, a checkout with no credentials kept, a read-only token; GitLab drops `CHANT_FORGE_TOKEN` and the job token), a gate job at the default branch with the token, an applying job on the saved plan with no write token, and a record job at the default branch that writes the run records (`chant run wave --phase plan|gate|apply|record`, `@intentius/chant/op/op-waves-split`). A `rest` wave is refused with `beforeMerge`.
190
+ */
191
+ export const WAVES_BEFORE_MERGE_SPLIT_FLOOR = NEXT_RELEASE;
192
+ export { opWaveSplitJobs, type OpWavePhase, type OpWaveSplitJob } from "./op/op-waves-split";
193
+
194
+ /**
195
+ * The first chant whose split before-merge waves take a `step` spec, Forgejo's hand-off, holds on other gates and one approval per wave (#4992): the plan job saves each run's step plan, the gate job leases the rows they change (no heartbeat; the decision names the lease) before it spends the approval, the applying job plans its runs again through the step and applies each whose digest the decision holds, and the record job writes the release records and lets go of the rows; a hook in the plan or apply job that holds the wave on another gate reads it with no write token and leaves its pending fact to the gate or record job; on Forgejo the plan and applying jobs hand their files on as job outputs (`packJs`), never through the artifact upload, and the gate and record jobs keep them as the artifacts; the plan job names no environment on GitHub (a wave's `planEnvironment` when set; on GitLab it prepares it), so the environment's reviewers are asked once. A `rest` wave splits from {@link WAVES_BEFORE_MERGE_REST_FLOOR} on.
196
+ */
197
+ export const WAVES_BEFORE_MERGE_STEP_FLOOR = NEXT_RELEASE;
198
+ export type { OpWaveSavedStep, OpWaveSplitHandoff, OpWaveSplitLease } from "./op/op-waves-run";
199
+
200
+ /**
201
+ * The first chant whose split waves run a product's own process in every job (#4994): the product wave hook's `hooks` (`runChantInProcess(["run", "wave", ..., "--phase", <phase>], words, { wave: { afterPlan, capabilities, hookExec, runHooks, hooks } })`, `RunOpWaveOptions.inProcessHooks`) serves a spec hook by its name in the process of whichever job runs it, plan, gate or applying job or the one-job shape, in place of a command that called back over a socket; `opWaveProductStateDir` is where the plan job's code keeps what the later jobs read; a `record: true` hold in the plan job is spent by the gate job for a re-run of the hook at the wave's commit (an applied line with `rerun.head`), which the next run's plan job runs and its gate job finishes (`holdsFinished`); and `waveJobs.<wave>.artifact.path` takes a list and `waveJobs.<wave>.gate` gives the gate job a report and an artifact, so a product's own upload steps go through chant's Forgejo hand-off.
202
+ */
203
+ export const WAVES_PRODUCT_HOOKS_FLOOR = NEXT_RELEASE;
204
+ export type { OpWaveHandedFinished, OpWaveInProcessHook, OpWaveInProcessHookCall } from "./op/op-waves-run";
205
+ export { opWaveProductStateDir } from "./op/op-waves-split";
206
+
207
+ /**
208
+ * The first chant whose split before-merge waves take a `rest` wave (#4992): its four jobs run one wave per run, the wave `CHANT_WAVES_WAVE` names (their own by default), and its record job, once the run applied and the plan found another wave, starts the waves workflow again for it (GitHub and Forgejo: a dispatch with the inputs `wave` and the decision's `pr`, `head` and `digest`, or a push's `commit`; GitLab: a pipeline with the same variables, with `CHANT_FORGE_TOKEN`), whose guard admits it as the same decided head; the jobs of the waves before it do not run in that follow-on; the record job's note (`rest-wave.json` beside the outcomes, `@intentius/chant/op/op-waves-follow-on`) tells `before-merge-done`, the control dispatch and the apply status that a run which started a follow-on is not the last.
209
+ */
210
+ export const WAVES_BEFORE_MERGE_REST_FLOOR = NEXT_RELEASE;
211
+
212
+ /**
213
+ * The first chant whose rest wave's record job records each follow-on it starts on `chant/lifecycle` before it starts it (#4998): `_waves/<op>.follow-on.json` keeps, per decided head or pushed commit, the wave started, the run that started it, the decision (`pr`, `digest`) or the `commit`, and the outcomes of every run of the chain so far; the guard admits a follow-on only for the wave that record names, so a wave started by hand past it is refused; and the last run's control dispatch, apply status and `before-merge-done` add up the outcomes of every run of the chain (the note's `chain`), so a chain whose last wave changed nothing reports `applied`.
214
+ */
215
+ export const WAVES_FOLLOW_ON_RECORD_FLOOR = NEXT_RELEASE;
216
+
174
217
  /**
175
218
  * The first chant whose product plan takes `watches`, the product's own scheduled jobs the note job's `pr-post` checks for having stopped with the job's token (#4888), and whose `checkOverdueOps` and `overdueOpsAt` take a product's `logPrefix` and `label`.
176
219
  */
177
220
  export const PRODUCT_PLAN_WATCHES_FLOOR = "0.124.88";
178
- export { PLAN_WATCHES_ENV } from "./op/schedule-overdue";
221
+ export { PLAN_WATCHES_ENV, watchesForTarget } from "./op/schedule-overdue";
222
+
223
+ /**
224
+ * The first chant whose product plan's `watches` take `targets` (#4988): a watch scoped to those targets is checked by their notes alone, and the note of another target checks neither it nor the discovered Op of its name (`watchesForTarget`).
225
+ */
226
+ export const PRODUCT_PLAN_WATCH_TARGETS_FLOOR = NEXT_RELEASE;
179
227
 
180
228
  /**
181
229
  * The first chant whose product plan takes `record` (#4899): the plan step writes the plan job's run record into the hand-off, and the note job keeps it as Op `pr-plan` on `chant/lifecycle` with `pr-post --record-run <plan job>` (`--open` on GitLab), as `chant ci run plan --in-place` records `pr-plan`'s.
@@ -186,14 +234,14 @@ export { PLAN_RUN_OP, PLAN_RUN_RECORD_FILE, readPlanRunRecord } from "./pr-plan-
186
234
  /**
187
235
  * The first chant whose product plan carries what terragucci's and sql-yodeler's plan jobs did themselves (#4963, #4951): `trade` (a plan's or a target's) before the checkout, `replan: { dispatch, reply, notAffected }` (a re-plan from `workflow_dispatch`, a reply to a comment no other job takes, `pr-post --not-affected`), `previousMarker` (`CHANT_PLAN_PREVIOUS_MARKER`), `noteSteps.pullRequest`, a `PrReport`'s `marker`, and a hand-off of the product's own note text (`planBodyHandoff`).
188
236
  */
189
- export const PRODUCT_PLAN_REPLAN_FLOOR = NEXT_RELEASE;
237
+ export const PRODUCT_PLAN_REPLAN_FLOOR = "0.124.89";
190
238
  export { gitlabReplanArgumentLines, PREVIOUS_MARKER_JS, replanDecideJs, type ProductPlanReplanOptions } from "./components/product-plan";
191
239
  export { planBodyHandoff, PLAN_BODY_LIMIT, type PrPlanBodyHandoff } from "./pr-plan-note";
192
240
 
193
241
  /**
194
242
  * The first chant whose note job compares the plan's subject with the previous note's (#4972), on GitHub, Forgejo and GitLab: a plan note hand-off's `subject` (`PrPlanSubject`, an id and named parts) is kept in the note, and `pr-post` adds the note words' `sinceLast` line, naming the parts added, gone and changed (`subjectParts`), when the previous note kept another id. The plan job reads no note, and `previousMarker` is deprecated.
195
243
  */
196
- export const PRODUCT_PLAN_SUBJECT_FLOOR = NEXT_RELEASE;
244
+ export const PRODUCT_PLAN_SUBJECT_FLOOR = "0.124.89";
197
245
  export { PLAN_SUBJECT_LIMIT, planSubjectProblem, sinceLastLine, subjectChanges, type PrPlanSubject, type PrPlanSubjectPartWords } from "./pr-plan-note";
198
246
 
199
247
  /**
@@ -16,7 +16,9 @@
16
16
 
17
17
  import { readFileSync } from "node:fs";
18
18
  import { activeProductWords } from "../../ci-product-words";
19
- import { answerProductComment, COMMENT_JOBS_ENV, commentRuns, type CommentJobs } from "../../ci-comment-commands";
19
+ import { answerProductComment, COMMENT_JOBS_ENV, commentRuns, type CommentBeforeMerge, type CommentJobs } from "../../ci-comment-commands";
20
+ import type { WavesBeforeMergeJobs } from "../../op/before-merge-decide";
21
+ import { PR_APPLY_REQUIRES } from "../../pr-requires";
20
22
  import { forgeFromEnv, forgeTargetFromEnv, type PrForge } from "../../pr-forge";
21
23
  import { forgeReadsFor } from "../../pr-forge-reads";
22
24
  import { formatError, formatInfo } from "../format";
@@ -32,10 +34,15 @@ export function commentJobsFromEnv(raw: string | undefined): CommentJobs {
32
34
  if (raw === undefined || raw.trim() === "") return {};
33
35
  const v: unknown = JSON.parse(raw);
34
36
  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new Error(`${COMMENT_JOBS_ENV} is a JSON object of the jobs the pipeline has`);
35
- const known = new Set(["preview", "applyBeforeMerge", "applyOnMerge", "locks", "agent", "commits", "actions", "skipForks", "targets", "noPlanFlags", "waves"]);
37
+ const known = new Set(["preview", "applyBeforeMerge", "applyOnMerge", "locks", "agent", "commits", "actions", "skipForks", "targets", "noPlanFlags", "waves", "wavesBeforeMerge"]);
36
38
  const jobs: Record<string, unknown> = {};
37
39
  for (const [k, x] of Object.entries(v)) {
38
40
  if (!known.has(k)) throw new Error(`${COMMENT_JOBS_ENV} names ${JSON.stringify(k)}, which is not one of ${[...known].join(", ")}`);
41
+ // #4984: the waves before merge.
42
+ if (k === "wavesBeforeMerge") {
43
+ jobs.wavesBeforeMerge = wavesBeforeMergeOf(x);
44
+ continue;
45
+ }
39
46
  // #4979: the waves' op and count, for a wave stop on a re-run.
40
47
  if (k === "waves") {
41
48
  const w = x as { op?: unknown; count?: unknown } | null;
@@ -51,9 +58,83 @@ export function commentJobsFromEnv(raw: string | undefined): CommentJobs {
51
58
  if (typeof x !== "boolean") throw new Error(`${COMMENT_JOBS_ENV}.${k} is true or false`);
52
59
  if (x) jobs[k] = true;
53
60
  }
61
+ if (jobs.wavesBeforeMerge && !jobs.waves) throw new Error(`${COMMENT_JOBS_ENV}.wavesBeforeMerge needs waves: { op, count }, the waves it starts`);
54
62
  return jobs as CommentJobs;
55
63
  }
56
64
 
65
+ /** {@link COMMENT_JOBS_ENV}'s `wavesBeforeMerge` (#4984), each field checked, since the comment job pushes and dispatches with what it names. */
66
+ export function wavesBeforeMergeOf(x: unknown): WavesBeforeMergeJobs {
67
+ const what = `${COMMENT_JOBS_ENV}.wavesBeforeMerge`;
68
+ const o = x as Partial<WavesBeforeMergeJobs> | null;
69
+ if (!o || typeof o !== "object" || Array.isArray(o)) throw new Error(`${what} is { workflow?, requires?, plan, pipelineFiles, locks? }`);
70
+ const strings = (v: unknown): v is string[] => Array.isArray(v) && v.every((s) => typeof s === "string" && s.trim() !== "" && !/[\r\n]/.test(s));
71
+ if (o.workflow !== undefined && (typeof o.workflow !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(o.workflow))) throw new Error(`${what}.workflow is a workflow file name, like deploy.yml`);
72
+ if (o.requires !== undefined && (!Array.isArray(o.requires) || o.requires.some((r) => !(PR_APPLY_REQUIRES as readonly string[]).includes(r)))) throw new Error(`${what}.requires is a list of ${PR_APPLY_REQUIRES.join(", ")}`);
73
+ if (!strings(o.plan)) throw new Error(`${what}.plan is the list of plan statuses that must pass on the head`);
74
+ if (!strings(o.pipelineFiles)) throw new Error(`${what}.pipelineFiles is the list of paths a change may not touch`);
75
+ if (o.locks !== undefined && (typeof o.locks !== "object" || o.locks === null || (o.locks.gate !== undefined && (typeof o.locks.gate !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(o.locks.gate))))) throw new Error(`${what}.locks is { gate? }`);
76
+ return {
77
+ ...(o.workflow ? { workflow: o.workflow } : {}),
78
+ ...(o.requires ? { requires: [...o.requires] } : {}),
79
+ plan: [...o.plan],
80
+ pipelineFiles: [...o.pipelineFiles],
81
+ ...(o.locks ? { locks: { ...(o.locks.gate ? { gate: o.locks.gate } : {}) } } : {}),
82
+ };
83
+ }
84
+
85
+ /**
86
+ * What the decision before merge reads and writes with (#4984), in the
87
+ * comment job (GitHub, Forgejo) and the note poll (GitLab): the requires
88
+ * and statuses through the job's client, git in the checkout of the
89
+ * default branch, the reach line's locks at stage apply, and the decision
90
+ * and the wave stop on this checkout's `chant/lifecycle`.
91
+ */
92
+ export async function beforeMergeDeps(forge: PrForge, jobs: CommentJobs, env: NodeJS.ProcessEnv = process.env): Promise<CommentBeforeMerge> {
93
+ const bm = jobs.wavesBeforeMerge!;
94
+ const op = jobs.waves!.op;
95
+ const { spawnSync } = await import("node:child_process");
96
+ const { checkPrRequires, unmetRequires } = await import("../../pr-requires");
97
+ const { productStatusContext, activeProductWords } = await import("../../ci-product-words");
98
+ const { LOCK_REACH_ENV, reachedTargets } = await import("../../lifecycle/reach-locks");
99
+ const { takeTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
100
+ const { recordBeforeMerge } = await import("../../op/before-merge-store");
101
+ const { setWaveStop } = await import("../../op/wave-stop");
102
+ const { PR_APPLY_GATE } = await import("../../pr-loop");
103
+ const words = activeProductWords();
104
+ const line = env[LOCK_REACH_ENV];
105
+ const name = (n: number) => (forge.kind === "gitlab" ? `!${n}` : `pull request ${n}`);
106
+ return {
107
+ // The plan and apply statuses never hold the apply back: the plan status is asked for by name.
108
+ requires: async (pr, head) => unmetRequires(await checkPrRequires(forge, pr, head, { ignore: [productStatusContext(words, "apply"), productStatusContext(words, "plan"), `${productStatusContext(words, "plan")}/`], ...(bm.requires ? { only: bm.requires } : {}) })),
109
+ statuses: async (sha) => (await forge.commitStatuses?.(sha)) ?? [],
110
+ git: (argv, o) => {
111
+ const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", ...(o.cwd ? { cwd: o.cwd } : {}) });
112
+ return { status: r.status, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
113
+ },
114
+ // #4979's reach line says what the change reaches; the locks go up at stage apply, refused while another holds one.
115
+ ...(line && line.trim()
116
+ ? {
117
+ lock: async (pr: number, head: string, base: string, by: string) => {
118
+ const reached = reachedTargets({ forge: forge.kind, pr, head, base, line });
119
+ if ("error" in reached) throw new Error(reached.error);
120
+ if ("moved" in reached) return { ok: false as const, text: `${name(pr)} moved while this comment was read, so nothing is ${words.verbs.apply[1]}; comment again once its checks pass` };
121
+ const isOpen = forge.pullRequestOpen?.bind(forge);
122
+ const r = await takeTargetLocks(bm.locks?.gate ?? PR_APPLY_GATE, reached.targets, { pr, by, at: new Date().toISOString(), stage: "apply", head }, { ...(isOpen ? { isOpen } : {}) });
123
+ if (!r.ok) {
124
+ const request = forge.kind === "gitlab" ? "merge request" : "pull request";
125
+ return { ok: false as const, text: `${describeHeldTargetLocks(r.held, name)}, so ${name(pr)} is not ${words.verbs.apply[1]}. It ${words.verbs.apply[0]}s once that ${request} merges or closes, or someone with write access unlocks it` };
126
+ }
127
+ return { ok: true as const, targets: r.taken };
128
+ },
129
+ }
130
+ : {}),
131
+ record: (d) => recordBeforeMerge(op, d),
132
+ stop: async (head, through) => {
133
+ await setWaveStop(op, head, through === null ? null : { through, at: new Date().toISOString() });
134
+ },
135
+ };
136
+ }
137
+
57
138
  export async function runComponentsPrComment(ctx: CommandContext): Promise<number> {
58
139
  const { args } = ctx;
59
140
  const kind = args.forge;
@@ -87,6 +168,8 @@ export async function runComponentsPrComment(ctx: CommandContext): Promise<numbe
87
168
  base,
88
169
  jobs,
89
170
  env,
171
+ // #4984: the decision before merge, its record and its wave stop on this checkout's chant/lifecycle.
172
+ ...(jobs.wavesBeforeMerge ? { beforeMerge: await beforeMergeDeps(poster, jobs, env) } : {}),
90
173
  // #4979: the wave stop goes on this checkout's chant/lifecycle, which the job pushes with its token.
91
174
  ...(jobs.waves
92
175
  ? {
@@ -12,6 +12,8 @@
12
12
  import { resolve } from "node:path";
13
13
  import { activeProductWords } from "../../ci-product-words";
14
14
  import { chantNoteRuns, gitlabPipelines, ledgerNoteLog, pollNoteCommands } from "../../ci-note-commands";
15
+ import { COMMENT_JOBS_ENV, type CommentJobs } from "../../ci-comment-commands";
16
+ import { beforeMergeDeps, commentJobsFromEnv } from "./pr-comment";
15
17
  import { forgeFromEnv, forgeTargetFromEnv, type PrForge } from "../../pr-forge";
16
18
  import { forgeReadsFor } from "../../pr-forge-reads";
17
19
  import { formatError, formatInfo, formatWarning } from "../format";
@@ -41,20 +43,42 @@ export async function runComponentsPrNotes(ctx: CommandContext): Promise<number>
41
43
  // The ledger keeps the notes answered: read it as the remote has it.
42
44
  await fetchLifecycle({ cwd });
43
45
  const words = activeProductWords();
46
+ // #4984: the waves' op and count, and the waves before merge, as the pipeline wrote them in CHANT_COMMENT_JOBS.
47
+ let more: CommentJobs;
48
+ try {
49
+ more = commentJobsFromEnv(env[COMMENT_JOBS_ENV]);
50
+ } catch (err) {
51
+ return fail(err instanceof Error ? err.message : String(err));
52
+ }
53
+ const beforeMerge = more.wavesBeforeMerge && more.waves ? await beforeMergeDeps(forge, more, env) : undefined;
44
54
  const polled = await pollNoteCommands({
45
55
  reads: forgeReadsFor(target),
46
56
  forge,
47
57
  pipelines: gitlabPipelines({ apiBase: target.apiBase, project: target.repo, token: target.token, host: target.host, ...(target.tokenHeader ? { tokenHeader: target.tokenHeader } : {}) }),
48
58
  words,
49
59
  base,
50
- runs: chantNoteRuns({
51
- ...(args.previewComment ? { preview: true } : {}),
52
- ...(args.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
53
- ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
54
- ...(args.locks ? { locks: true } : {}),
55
- }),
60
+ runs: chantNoteRuns(
61
+ {
62
+ ...(args.previewComment ? { preview: true } : {}),
63
+ ...(args.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
64
+ ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
65
+ ...(args.locks ? { locks: true } : {}),
66
+ ...(more.waves ? { waves: more.waves } : {}),
67
+ ...(more.wavesBeforeMerge ? { wavesBeforeMerge: more.wavesBeforeMerge } : {}),
68
+ },
69
+ beforeMerge ? { beforeMerge } : {},
70
+ ),
56
71
  log: ledgerNoteLog({ cwd }),
57
72
  env,
73
+ // #4984: a merged merge request's wave-<n> stops the retried waves after it.
74
+ ...(more.waves
75
+ ? {
76
+ stops: async (op, sha, stop) => {
77
+ const { setWaveStop } = await import("../../op/wave-stop");
78
+ await setWaveStop(op, sha, stop, { cwd });
79
+ },
80
+ }
81
+ : {}),
58
82
  });
59
83
  let failed = polled.fail !== undefined;
60
84
  for (const o of polled.outcomes) {
@@ -2935,7 +2935,8 @@ async function descriptionCheckOf(ctx: CommandContext, forge: PrForge): Promise<
2935
2935
  * `--preview-comment`, and set its plan status back to pending
2936
2936
  * (`markStaleNotes`, ../../pr-post.ts). The branch is `--branch`, else the
2937
2937
  * job's (`GITHUB_REF_NAME`, `CI_COMMIT_BRANCH`). It exits 0 once it has
2938
- * marked, as `pr-post` does.
2938
+ * marked, as `pr-post` does. `--member` given more than once (#4987, a
2939
+ * product plan's targets) marks each member's note in turn.
2939
2940
  */
2940
2941
  async function runComponentsPrPostStale(ctx: CommandContext): Promise<number> {
2941
2942
  const { args } = ctx;
@@ -2943,7 +2944,6 @@ async function runComponentsPrPostStale(ctx: CommandContext): Promise<number> {
2943
2944
  if (!args.tip) return fail("pr-post --stale needs the target branch's commit now: --tip <sha>");
2944
2945
  if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
2945
2946
  if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`pr-post posts to a forge: --forge ${FORGE_KINDS.join("|")}`);
2946
- if (args.members && args.members.length > 1) return fail(`pr-post takes one --member, not ${args.members.join(", ")}`);
2947
2947
  const branch = args.branch ?? process.env.CI_COMMIT_BRANCH ?? process.env.GITHUB_REF_NAME;
2948
2948
  if (!branch) return fail("pr-post --stale marks the notes of the pull requests into a branch: run it in a job of a push, or pass --branch <branch>");
2949
2949
  let forge: PrForge;
@@ -2952,17 +2952,20 @@ async function runComponentsPrPostStale(ctx: CommandContext): Promise<number> {
2952
2952
  } catch (err) {
2953
2953
  return fail(err instanceof Error ? err.message : String(err));
2954
2954
  }
2955
- const member = args.members?.[0];
2955
+ // #4987: a product plan's targets each have their note, so --member may be given once per target.
2956
+ const members: Array<string | undefined> = args.members?.length ? [...new Set(args.members)] : [undefined];
2956
2957
  const { markStaleNotes } = await import("../../pr-post");
2957
- let done: Awaited<ReturnType<typeof markStaleNotes>>;
2958
- try {
2959
- done = await markStaleNotes({ forge, branch, tip: args.tip, env: args.env, ...(member ? { member } : {}), ...(args.previewComment ? { previewComment: true } : {}) });
2960
- } catch (err) {
2961
- return fail(err instanceof Error ? err.message : String(err));
2958
+ for (const member of members) {
2959
+ let done: Awaited<ReturnType<typeof markStaleNotes>>;
2960
+ try {
2961
+ done = await markStaleNotes({ forge, branch, tip: args.tip, env: args.env, ...(member ? { member } : {}), ...(args.previewComment ? { previewComment: true } : {}) });
2962
+ } catch (err) {
2963
+ return fail(err instanceof Error ? err.message : String(err));
2964
+ }
2965
+ for (const message of done.warnings) console.error(formatWarning({ message }));
2966
+ const marked = done.marks.filter((m) => m.marked).map((m) => `#${m.pr}`);
2967
+ console.error(formatInfo(`pr-post --stale${member ? ` (${member})` : ""}: ${marked.length > 0 ? `marked ${marked.join(", ")} stale` : "no note to mark"} after ${branch} moved to ${args.tip.slice(0, 12)}`));
2962
2968
  }
2963
- for (const message of done.warnings) console.error(formatWarning({ message }));
2964
- const marked = done.marks.filter((m) => m.marked).map((m) => `#${m.pr}`);
2965
- console.error(formatInfo(`pr-post --stale: ${marked.length > 0 ? `marked ${marked.join(", ")} stale` : "no note to mark"} after ${branch} moved to ${args.tip.slice(0, 12)}`));
2966
2969
  return 0;
2967
2970
  }
2968
2971
 
@@ -14,6 +14,8 @@ import { formatError, formatWarning } from "../format";
14
14
  import { ledgerRecordingOff, NO_RECORD_ENV, noRecordEndNote, noRecordStartNote, resetNoRecordLedger } from "../../lifecycle/no-record";
15
15
  import type { CommandContext } from "../registry";
16
16
  import { waveStopLine } from "../../op/wave-stop";
17
+ import { OP_WAVE_PHASES, type OpWavePhase } from "../../op/op-waves-split";
18
+ import { beforeMergeRunFromEnv } from "../../op/before-merge";
17
19
  import { CHANT_EXIT } from "../../exit-codes";
18
20
 
19
21
  /**
@@ -46,6 +48,10 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
46
48
 
47
49
  async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
48
50
  const { args } = ctx;
51
+ // #4984: the job after a before-merge run's last wave merges the pull request, or says it is ready.
52
+ if (args.merge !== undefined) return runBeforeMergeDone(ctx);
53
+ // #4987: the job after a wave posts its apply status, at the default branch's commit.
54
+ if (args.applyStatus !== undefined) return runApplyStatus(ctx);
49
55
  const specFile = args.opsSpec;
50
56
  if (specFile && args.recordPlans) {
51
57
  try {
@@ -67,7 +73,16 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
67
73
  const { opWaveOutcomeDir } = await import("../../op/op-waves");
68
74
  const { earlierWaveOutcomes } = await import("../../wave-blocked");
69
75
  const { applyOutcomeOf } = await import("../../control/applied");
70
- const summary = applyOutcomeOf(earlierWaveOutcomes([resolve(opWaveOutcomeDir(spec))], Number.MAX_SAFE_INTEGER).members);
76
+ // #4992: a run that started a follow-on is not the last; the follow-on's control job tells the control repo.
77
+ const { readOpWaveRestNote } = await import("../../op/op-waves-follow-on");
78
+ const note = readOpWaveRestNote([resolve(opWaveOutcomeDir(spec))]);
79
+ if (note?.next !== undefined) {
80
+ console.error(`${spec.name}: wave ${note.wave} started a follow-on run for wave ${note.next}, so this run's outcome is not the waves'; that run sends it`);
81
+ return 0;
82
+ }
83
+ // #4998: the last run of a chain adds up the earlier runs' outcomes, which its note carries.
84
+ const { withChainOutcomes } = await import("../../op/op-waves-follow-on");
85
+ const summary = applyOutcomeOf(withChainOutcomes(earlierWaveOutcomes([resolve(opWaveOutcomeDir(spec))], Number.MAX_SAFE_INTEGER).members, note));
71
86
  if (args.json) console.log(JSON.stringify(summary, null, 2));
72
87
  else {
73
88
  console.log(summary.outcome);
@@ -95,6 +110,14 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
95
110
  console.error(formatError({ message: `--policy-only runs a wave's policy in its own or its deciding job; a --${args.share !== undefined ? "share" : "group"} job has none of its own` }));
96
111
  return 1;
97
112
  }
113
+ // #4987: one of a split wave's four jobs before merge.
114
+ const phase = args.phase as OpWavePhase | undefined;
115
+ if (phase !== undefined && !OP_WAVE_PHASES.includes(phase)) {
116
+ console.error(formatError({ message: `--phase is one of ${OP_WAVE_PHASES.join(", ")}: a split wave's plan, gate, apply or record job`, hint: `got ${JSON.stringify(args.phase ?? "")}` }));
117
+ return 1;
118
+ }
119
+ // The gate and record jobs run at the default branch; a before-merge run's applied commit is its decided head.
120
+ const decidedHead = phase === "gate" || phase === "record" ? beforeMergeRunFromEnv().head : undefined;
98
121
  let spec: OpWavesSpec | undefined;
99
122
  const job = { ...(args.share !== undefined ? { share: args.share } : {}), ...(args.group !== undefined ? { group: args.group } : {}) };
100
123
  if (args.eventsJson && args.json) {
@@ -119,8 +142,9 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
119
142
  spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
120
143
  }
121
144
  // #4979: a comment that ran the apply again through wave n leaves the waves after it waiting, as a gate does.
122
- if (!args.policyOnly) {
123
- const stopped = await waveStopLine(spec.name, args.wave);
145
+ // #4987: in a split wave the gate job reads the stop, with the token, at the decided head.
146
+ if (!args.policyOnly && (phase === undefined || phase === "gate")) {
147
+ const stopped = await waveStopLine(spec.name, args.wave, decidedHead ? { sha: decidedHead } : {});
124
148
  if (stopped) {
125
149
  console.error(stopped);
126
150
  return CHANT_EXIT.waiting;
@@ -138,6 +162,8 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
138
162
  ...(product?.capabilities ? { capabilities: product.capabilities } : {}),
139
163
  ...(product?.hookExec ? { hookExec: product.hookExec } : {}),
140
164
  ...(product?.runHooks ? { runHooks: product.runHooks } : {}),
165
+ // #4994: the spec's hooks the product serves in this process, in whichever job of a split wave runs them.
166
+ ...(product?.hooks ? { inProcessHooks: product.hooks } : {}),
141
167
  spec,
142
168
  specFile: relative(process.cwd(), path),
143
169
  wave: args.wave,
@@ -147,10 +173,17 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
147
173
  ...(args.group !== undefined ? { group: args.group } : {}),
148
174
  ...(args.base ? { base: args.base } : {}),
149
175
  ...(show ? { show } : {}),
176
+ ...(phase ? { phase } : {}),
177
+ ...(decidedHead ? { head: decidedHead } : {}),
150
178
  });
179
+ // #4992: the rest wave's record job starts the follow-on run for the next wave its plan found.
180
+ if (phase === "record") result.exitCode = await (await import("../../op/op-waves-follow-on")).followOnAfterRecord({ spec, wave: args.wave, exitCode: result.exitCode });
151
181
  if (args.json) console.log(JSON.stringify(result, null, 2));
152
182
  // #4926: the policy step applied nothing; the wave's own step tells people how it went.
153
183
  if (args.policyOnly) return result.exitCode;
184
+ // #4987: the plan and apply jobs run the change's code and hold no token; the gate job tells people when the wave stops
185
+ // there, and the record job how it applied.
186
+ if (phase === "plan" || phase === "apply" || (phase === "gate" && result.exitCode === CHANT_EXIT.done)) return result.exitCode;
154
187
  // #3761: tell people, when the spec says where. Delivery never changes the exit code.
155
188
  await notifyOpWave(spec, args.wave, { result }, job);
156
189
  // #4629: a refused wave's diff and a failed apply's triage, on the pull request or a tracking issue.
@@ -159,7 +192,7 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
159
192
  } catch (err) {
160
193
  const message = err instanceof Error ? err.message : String(err);
161
194
  console.error(formatError({ message }));
162
- if (spec) {
195
+ if (spec && phase !== "plan" && phase !== "apply") {
163
196
  await notifyOpWave(spec, args.wave, { error: message }, job);
164
197
  await respondWave(spec, args.wave, { error: message });
165
198
  }
@@ -167,6 +200,113 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
167
200
  }
168
201
  }
169
202
 
203
+ /**
204
+ * `chant run wave --op <op> --wave <last> --merge auto|manual --forge <kind>
205
+ * [--gate <name>] [--merge-token-env <VAR>]` (#4984): the job after a
206
+ * before-merge run's last wave (`../../op/before-merge-done.ts`). A push run
207
+ * names no decided head, and the job does nothing.
208
+ */
209
+ async function runBeforeMergeDone(ctx: CommandContext): Promise<number> {
210
+ const { args } = ctx;
211
+ const fail = (message: string): number => {
212
+ console.error(formatError({ message }));
213
+ return 1;
214
+ };
215
+ if (args.merge !== "auto" && args.merge !== "manual") return fail("--merge is auto or manual: auto merges the pull request once every wave applied its decided head, manual says it is ready");
216
+ const op = args.op;
217
+ if (!op || args.wave === undefined) return fail("--merge closes a before-merge run: --op <name> --wave <last wave> --merge auto|manual --forge <kind>");
218
+ const { FORGE_KINDS } = await import("../../pr-forge");
219
+ if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`--merge replies on the pull request: --forge ${FORGE_KINDS.join("|")}`);
220
+ const kind = args.forge as (typeof FORGE_KINDS)[number];
221
+ const { beforeMergeRunFromEnv, isBeforeMergeRun } = await import("../../op/before-merge");
222
+ const run = beforeMergeRunFromEnv();
223
+ if (!isBeforeMergeRun(run)) {
224
+ console.error("this run names no decided head: a push applies on its own, so nothing is merged here");
225
+ return 0;
226
+ }
227
+ try {
228
+ const { beforeMergeRecordAt } = await import("../../op/before-merge-store");
229
+ const { beforeMergeDone } = await import("../../op/before-merge-done");
230
+ const { opWaveOutcomeDir } = await import("../../op/op-waves");
231
+ const { earlierWaveOutcomes } = await import("../../wave-blocked");
232
+ const { applyOutcomeOf } = await import("../../control/applied");
233
+ const { forgeFromJobEnv } = await import("../../pr-forge-job");
234
+ const { mergeTokenEnv } = await import("../../pr-merge");
235
+ const { releaseTargetLocks } = await import("../../lifecycle/target-lock");
236
+ const { PR_APPLY_GATE } = await import("../../pr-loop");
237
+ const { activeProductWords } = await import("../../ci-product-words");
238
+ const record = run.head ? await beforeMergeRecordAt(op, run.head) : undefined;
239
+ // #4992: a run whose rest wave started a follow-on leaves the merge to that run.
240
+ const { readOpWaveRestNote, withChainOutcomes } = await import("../../op/op-waves-follow-on");
241
+ const note = readOpWaveRestNote([resolve(opWaveOutcomeDir({ name: op }))]);
242
+ // #4998: the last run of a chain adds up the earlier runs' outcomes, which its note carries.
243
+ const outcome = applyOutcomeOf(withChainOutcomes(earlierWaveOutcomes([resolve(opWaveOutcomeDir({ name: op }))], Number.MAX_SAFE_INTEGER).members, note));
244
+ let merger;
245
+ if (args.merge === "auto" && args.mergeTokenEnv) {
246
+ const env = mergeTokenEnv(args.mergeTokenEnv);
247
+ if ("error" in env) return fail(String(env.error));
248
+ merger = forgeFromJobEnv(kind, env);
249
+ }
250
+ const gate = args.gate ?? PR_APPLY_GATE;
251
+ const done = await beforeMergeDone({
252
+ op,
253
+ waves: args.wave,
254
+ run,
255
+ record,
256
+ outcome,
257
+ ...(note?.next !== undefined ? { followOn: { wave: note.wave, next: note.next, found: note.found } } : {}),
258
+ merge: args.merge,
259
+ forge: forgeFromJobEnv(kind),
260
+ ...(merger ? { merger } : {}),
261
+ release: async (pr) => (await releaseTargetLocks(gate, pr)).released,
262
+ words: activeProductWords(),
263
+ });
264
+ console.error(done.text);
265
+ return done.code;
266
+ } catch (err) {
267
+ return fail(err instanceof Error ? err.message : String(err));
268
+ }
269
+ }
270
+
271
+ /**
272
+ * `chant run wave --op <op> --wave <n> --of <count> --apply-status <context>
273
+ * --at <sha> --forge <kind>` (#4987): the job after wave n posts its apply
274
+ * status on the commit the waves applied, from every outcome file the job
275
+ * downloaded (`../../op/apply-status.ts`). It runs at the default branch's
276
+ * commit and none of the change's code. A refused post fails the job.
277
+ */
278
+ async function runApplyStatus(ctx: CommandContext): Promise<number> {
279
+ const { args } = ctx;
280
+ const fail = (message: string): number => {
281
+ console.error(formatError({ message }));
282
+ return 1;
283
+ };
284
+ const op = args.op;
285
+ if (!op || args.wave === undefined || args.of === undefined || !args.at) return fail("--apply-status posts one wave's apply status: --op <name> --wave <n> --of <count> --apply-status <context> --at <sha> --forge <kind>");
286
+ const { FORGE_KINDS } = await import("../../pr-forge");
287
+ if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`--apply-status posts on a forge: --forge ${FORGE_KINDS.join("|")}`);
288
+ const kind = args.forge as (typeof FORGE_KINDS)[number];
289
+ try {
290
+ const { postOpWaveApplyStatus } = await import("../../op/apply-status");
291
+ const { opWaveOutcomeDir } = await import("../../op/op-waves");
292
+ const { forgeFromJobEnv } = await import("../../pr-forge-job");
293
+ const pipeline = kind === "gitlab" && args.at === process.env.CI_COMMIT_SHA && /^[0-9]+$/.test(process.env.CI_PIPELINE_ID ?? "") ? Number(process.env.CI_PIPELINE_ID) : undefined;
294
+ const line = await postOpWaveApplyStatus({
295
+ forge: forgeFromJobEnv(kind),
296
+ dirs: [resolve(opWaveOutcomeDir({ name: op }))],
297
+ wave: args.wave,
298
+ of: args.of,
299
+ context: args.applyStatus!,
300
+ at: args.at,
301
+ ...(pipeline !== undefined ? { pipelineId: pipeline } : {}),
302
+ });
303
+ console.error(line);
304
+ return 0;
305
+ } catch (err) {
306
+ return fail(`the apply status was not posted: ${err instanceof Error ? err.message : String(err)}`);
307
+ }
308
+ }
309
+
170
310
  /**
171
311
  * The wave job's responses (#4629), through the forge the job's variables
172
312
  * name. A job with no forge token posts nothing. Never throws.
package/src/cli/main.ts CHANGED
@@ -619,6 +619,23 @@ Ops:
619
619
  names (a JSON argv) with CHANT_WAVES_SPEC_AT set to
620
620
  the base, writes the spec it prints over --spec, and
621
621
  reads the rules at base from it (#4982).
622
+ --phase plan|gate|apply|record: one of a wave's four
623
+ jobs before merge (#4987). plan saves the plan and
624
+ writes nothing to chant/lifecycle; gate decides the
625
+ gate on the saved plan at the default branch; apply
626
+ applies the saved plans the decision holds; record
627
+ writes the applying jobs' run records.
628
+ --op <name> --wave <last> --merge auto|manual
629
+ --forge <kind> [--gate <name>] [--merge-token-env
630
+ <VAR>]: the job after a before-merge run's last wave
631
+ (#4984): checks the decided head and that every wave
632
+ applied, then merges the pull request at that head
633
+ and releases its locks (auto), or says it is ready.
634
+ --op <name> --wave <n> --of <count> --apply-status
635
+ <context> --at <sha> --forge <kind>: the job after
636
+ wave n posts <context> on the commit the waves
637
+ applied, from the outcome files: pending until the
638
+ last wave's success, failed for a failed run (#4987).
622
639
  --record-plans (no --wave), in a pull request's
623
640
  pipeline: plan every wave at its head and record the
624
641
  digests a pr-review approval mode compares.
@@ -505,6 +505,16 @@ export function parseArgs(args: string[]): ParsedArgs {
505
505
  result.approvalStatus = true;
506
506
  } else if (arg === "--waves-outcome") {
507
507
  result.wavesOutcome = true;
508
+ } else if (arg === "--apply-status") {
509
+ // `chant run wave --op <op> --wave <n> --of <count> --apply-status <context> --at <sha>` (#4987): post wave n's apply status.
510
+ const value = args[++i];
511
+ if (!value || value.startsWith("-")) throw new Error("--apply-status needs the status's name: --apply-status <context>");
512
+ result.applyStatus = value;
513
+ } else if (arg === "--of") {
514
+ const raw = args[++i];
515
+ const of = Number(raw);
516
+ if (!Number.isInteger(of) || of < 1) throw new Error(`--of needs the number of waves: got "${raw ?? ""}"`);
517
+ result.of = of;
508
518
  } else if (arg === "--group") {
509
519
  const raw = args[++i];
510
520
  if (!raw || raw.startsWith("-")) throw new Error("--group needs a job group's name: --group <name>");
@@ -1381,6 +1391,7 @@ export function parseArgs(args: string[]): ParsedArgs {
1381
1391
  result.quarantineOnly = true;
1382
1392
  } else if (arg === "--phase") {
1383
1393
  // `chant ci base --phase <name>` (#4643): the ci.green phase whose base to find.
1394
+ // `chant run wave --phase plan|gate|apply|record` (#4987): one job of a split wave; the handler checks the word.
1384
1395
  result.phase = args[++i];
1385
1396
  } else if (arg === "--audit-log") {
1386
1397
  // `chant audit-log attribute|unrecorded --audit-log aws[:<region>]` (#4632).
@@ -344,6 +344,10 @@ export interface ParsedArgs {
344
344
  approvalStatus?: boolean;
345
345
  /** `chant run wave --waves-outcome` (#4617) — print how every wave job's outcome file adds up: the outcome a control dispatch carries. */
346
346
  wavesOutcome?: boolean;
347
+ /** `chant run wave --op <op> --wave <n> --of <count> --apply-status <context> --at <sha> --forge <kind>` (#4987) — post wave n's apply status from the outcome files. */
348
+ applyStatus?: string;
349
+ /** `chant run wave --of <count>` (#4987) — how many waves the run has, with `--apply-status`. */
350
+ of?: number;
347
351
  /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
348
352
  share?: number;
349
353
  /** `chant run wave --group <name>` (#3914) — apply one job group's runs of a decided wave. */
@@ -1012,7 +1016,10 @@ export interface ParsedArgs {
1012
1016
  ciTimeoutMinutes?: number;
1013
1017
  /** `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662) — a ci.green lane. `chant release cut --lane <name>` and `chant release candidates --lane <name>` (#4692) — check that lane's green tags. */
1014
1018
  lane?: string;
1015
- /** `chant ci base --phase <name>` (#4643) — the ci.green phase whose base to find. `chant ci quarantine filter --phase <name>` (#4677) — the phase whose runner takes the filter. */
1019
+ /**
1020
+ * `chant ci base --phase <name>` (#4643) — the ci.green phase whose base to find. `chant ci quarantine filter --phase <name>` (#4677) — the phase whose runner takes the filter.
1021
+ * `chant run wave --phase plan|gate|apply|record` (#4987) — one of a split wave's four jobs before merge.
1022
+ */
1016
1023
  phase?: string;
1017
1024
  /** `chant ci quarantine filter --runner nextest|playwright|list` (#4677). */
1018
1025
  quarantineRunner?: string;