@intentius/chant 0.124.92 → 0.124.94

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 (93) hide show
  1. package/dist/__golden__/notify-defaults-plain.json +52 -0
  2. package/dist/__golden__/notify-defaults-relay.json +92 -0
  3. package/dist/ci-job-guard.d.ts +22 -8
  4. package/dist/ci-job-guard.d.ts.map +1 -1
  5. package/dist/ci-job-guard.js +93 -49
  6. package/dist/ci-jobs.d.ts +22 -0
  7. package/dist/ci-jobs.d.ts.map +1 -1
  8. package/dist/ci-jobs.js +23 -0
  9. package/dist/ci-product.d.ts +41 -1
  10. package/dist/ci-product.d.ts.map +1 -1
  11. package/dist/ci-product.js +45 -5
  12. package/dist/cli/handlers/run-wave.js +17 -3
  13. package/dist/cli/main.d.ts.map +1 -1
  14. package/dist/cli/main.js +4 -1
  15. package/dist/components/product-pipeline.d.ts +30 -0
  16. package/dist/components/product-pipeline.d.ts.map +1 -1
  17. package/dist/components/product-pipeline.js +28 -3
  18. package/dist/floor-table.data.d.ts.map +1 -1
  19. package/dist/floor-table.data.js +17 -4
  20. package/dist/gate-resume-run.d.ts +7 -0
  21. package/dist/gate-resume-run.d.ts.map +1 -1
  22. package/dist/gate-resume-run.js +42 -3
  23. package/dist/lexicon.d.ts +64 -1
  24. package/dist/lexicon.d.ts.map +1 -1
  25. package/dist/lifecycle/gate-applied.d.ts +18 -0
  26. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  27. package/dist/notify.d.ts +8 -0
  28. package/dist/notify.d.ts.map +1 -1
  29. package/dist/notify.js +8 -3
  30. package/dist/op/before-merge.d.ts +8 -0
  31. package/dist/op/before-merge.d.ts.map +1 -1
  32. package/dist/op/before-merge.js +6 -0
  33. package/dist/op/gate-run-locator.d.ts +17 -0
  34. package/dist/op/gate-run-locator.d.ts.map +1 -1
  35. package/dist/op/index.d.ts +4 -2
  36. package/dist/op/index.d.ts.map +1 -1
  37. package/dist/op/index.js +3 -2
  38. package/dist/op/op-waves-names.d.ts +65 -2
  39. package/dist/op/op-waves-names.d.ts.map +1 -1
  40. package/dist/op/op-waves-names.js +129 -0
  41. package/dist/op/op-waves-remainder.d.ts +110 -0
  42. package/dist/op/op-waves-remainder.d.ts.map +1 -0
  43. package/dist/op/op-waves-remainder.js +120 -0
  44. package/dist/op/op-waves-render-spec.d.ts +63 -5
  45. package/dist/op/op-waves-render-spec.d.ts.map +1 -1
  46. package/dist/op/op-waves-render-spec.js +68 -10
  47. package/dist/op/op-waves-run.d.ts +29 -1
  48. package/dist/op/op-waves-run.d.ts.map +1 -1
  49. package/dist/op/op-waves-run.js +194 -6
  50. package/dist/op/op-waves-split-resume.d.ts +57 -0
  51. package/dist/op/op-waves-split-resume.d.ts.map +1 -0
  52. package/dist/op/op-waves-split-resume.js +94 -0
  53. package/dist/op/op-waves-stand-down.d.ts +9 -1
  54. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  55. package/dist/op/op-waves-stand-down.js +14 -2
  56. package/dist/op/op-waves.d.ts +38 -2
  57. package/dist/op/op-waves.d.ts.map +1 -1
  58. package/dist/op/op-waves.js +13 -2
  59. package/dist/release-floors.d.ts +9 -1
  60. package/dist/release-floors.d.ts.map +1 -1
  61. package/dist/release-floors.js +9 -1
  62. package/dist/wave-runtime.mjs +368 -368
  63. package/package.json +1 -1
  64. package/src/__golden__/notify-defaults-plain.json +52 -0
  65. package/src/__golden__/notify-defaults-relay.json +92 -0
  66. package/src/ci-job-guard.default-branch.test.ts +125 -0
  67. package/src/ci-job-guard.ts +64 -10
  68. package/src/ci-jobs.ts +26 -0
  69. package/src/ci-product.ts +54 -5
  70. package/src/cli/handlers/run-wave.ts +16 -3
  71. package/src/cli/main.ts +4 -1
  72. package/src/components/product-pipeline.ts +49 -4
  73. package/src/floor-table.data.ts +17 -4
  74. package/src/gate-resume-run.ts +38 -3
  75. package/src/lexicon.ts +64 -1
  76. package/src/lifecycle/gate-applied.ts +16 -0
  77. package/src/notify-bundle.test.ts +3 -2
  78. package/src/notify-relay-name.test.ts +72 -0
  79. package/src/notify.ts +16 -3
  80. package/src/op/before-merge.ts +12 -0
  81. package/src/op/gate-run-locator.ts +14 -0
  82. package/src/op/index.ts +6 -1
  83. package/src/op/op-waves-names.ts +130 -2
  84. package/src/op/op-waves-remainder.test.ts +342 -0
  85. package/src/op/op-waves-remainder.ts +146 -0
  86. package/src/op/op-waves-render-spec.test.ts +107 -0
  87. package/src/op/op-waves-render-spec.ts +81 -10
  88. package/src/op/op-waves-run.ts +204 -7
  89. package/src/op/op-waves-split-resume.test.ts +149 -0
  90. package/src/op/op-waves-split-resume.ts +109 -0
  91. package/src/op/op-waves-stand-down.ts +15 -2
  92. package/src/op/op-waves.ts +46 -3
  93. package/src/release-floors.ts +13 -1
@@ -155,6 +155,16 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
155
155
  * `apply-comment`. Default `comment`.
156
156
  */
157
157
  commentJob?: boolean | ProductCommentJobOptions;
158
+ /**
159
+ * GitLab's note poll under the product's names (#5038), with
160
+ * `noteCommands`: its job's name (default `note-commands`), its stage
161
+ * (default the job's name), and the variable and value a pipeline
162
+ * schedule starts it with (default `CHANT_NOTE_COMMANDS` and `1`), such
163
+ * as terragucci's `comments` job, which `TERRAGUCCI_SCHEDULE=comments`
164
+ * starts. Its resource group is its name. Refused on GitHub and Forgejo,
165
+ * whose comment job is `commentJob`.
166
+ */
167
+ noteCommandsJob?: ProductNoteCommandsJobOptions;
158
168
  /**
159
169
  * The waves' job names (#5027), the Op waves generators' `jobNames`
160
170
  * (#5022): `waves.pipeline` carries them to the generator, `waves.jobs`
@@ -199,6 +209,8 @@ export interface ProductWavesBeforeMerge {
199
209
  merge?: "auto" | "manual";
200
210
  /** The merge token's secret or CI/CD variable, with `merge: "auto"` (needed on Forgejo and GitLab). */
201
211
  mergeTokenSecret?: string;
212
+ /** The forge environment the merge job runs in, which the merge token is scoped to (#5037; GitHub and GitLab). `waves.pipeline` carries it as the generator's `beforeMerge.environment`. */
213
+ environment?: string;
202
214
  /** Paths a change may not touch to apply before merge; one ending in `/` is a directory. Default the forge's workflow directory and `.chant/op-waves/`. */
203
215
  pipelineFiles?: string[];
204
216
  /**
@@ -217,6 +229,16 @@ export interface ProductWavesBeforeMerge {
217
229
  dispatchInputs?: Partial<Record<"pr" | "head" | "digest", string>>;
218
230
  }
219
231
 
232
+ /** {@link ProductPipelineOptions.noteCommandsJob} (#5038). */
233
+ export interface ProductNoteCommandsJobOptions {
234
+ /** The job's name, such as `comments`. Default `note-commands`. */
235
+ jobName?: string;
236
+ /** Its stage. Default the job's name. */
237
+ stage?: string;
238
+ /** The variable and value a pipeline schedule starts it with, such as `{ variable: "TERRAGUCCI_SCHEDULE", value: "comments" }`. Default `CHANT_NOTE_COMMANDS` and `1`. */
239
+ schedule?: { variable: string; value: string };
240
+ }
241
+
220
242
  /** {@link ProductPipelineOptions.commentJob}'s settings (#5027). */
221
243
  export interface ProductCommentJobOptions {
222
244
  /** The comment job's name in the workflow, such as `apply-comment`. Default {@link PR_COMMENT_JOB}. */
@@ -306,7 +328,7 @@ export interface ProductPipelineJobs {
306
328
  * lexicon renders the same job from `chant build --pr-loop
307
329
  * --note-commands`. Refused on GitHub and Forgejo.
308
330
  */
309
- noteCommands?: { command: string; runner?: CiRunner; env?: Record<string, string> };
331
+ noteCommands?: { command: string; runner?: CiRunner; env?: Record<string, string>; jobName?: string; stage?: string; schedule?: { variable: string; value: string } };
310
332
  /**
311
333
  * The agent (#4616), with `agent`: the comment it answers, `/<product>
312
334
  * agent <ask>`, and the scheduled Op spec whose generated workflow runs
@@ -445,7 +467,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
445
467
  // #4946: the comment job answers every command but a commit word (the commit job's) with a reply, so the words may name any.
446
468
  const answered: CiProductCommand[] = options.commentJob ? [...new Set<CiProductCommand>([...jobs, ...CI_PRODUCT_COMMANDS.filter((c) => c !== "commit")])] : jobs;
447
469
  const words = assertProductWords({ ...options.words, applyMode }, { jobs: answered });
448
- const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, wavesBeforeMerge, applyStatus: _applyStatus, wavesJobNames, ...loop } = options;
470
+ const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, wavesBeforeMerge, applyStatus: _applyStatus, wavesJobNames, noteCommandsJob, ...loop } = options;
449
471
  if (options.applyStatus && !given && !componentWaves) throw new Error("applyStatus posts the waves' apply statuses, and there are none: give waves (or componentWaves)");
450
472
  const { respond } = options;
451
473
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
@@ -501,7 +523,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
501
523
  // #4785: GitLab's comment commands, polled from the notes; waves on merge are retried by an apply on a merged merge request.
502
524
  // #4899: the product plan's comment re-plan runs in the preview's pipeline, so the poll starts it as it starts a preview.
503
525
  const notes = prNoteCommandsJob(forge, { ...prLoop, ...(options.waves || options.componentWaves ? { applyOnMerge: true } : {}), ...(productPlan?.replan ? { previewComment: true } : {}) });
504
- if (notes) out.noteCommands = { ...notes, ...defaultRunner };
526
+ if (notes) out.noteCommands = { ...notes, ...defaultRunner, ...noteCommandsNames(forge, noteCommandsJob) };
527
+ else if (noteCommandsJob !== undefined) throw new Error(forge === "gitlab" ? "noteCommandsJob names the note poll, and there is none: set noteCommands" : `noteCommandsJob names GitLab's note poll; on ${forge} the comment job (commentJob) answers comments`);
505
528
  const preview = prCommentPreviewJob(forge, env, prLoop, member);
506
529
  if (preview) out.preview = { ...preview, ...(defaultRunner.runner !== undefined ? { noteRunner: defaultRunner.runner } : {}) };
507
530
  // #4616: the agent answers its comment from a workflow of its own, generated from this spec.
@@ -607,7 +630,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
607
630
  if (!named || !specFile || !namedWaveJobs) return { ...out, record: record! };
608
631
  // #4984: what the generator's before-merge mode takes: the merge after the last wave and the lock file it releases.
609
632
  const beforeMerge: OpWavesBeforeMerge | undefined = wavesBeforeMerge
610
- ? { ...(wavesBeforeMerge.merge ? { merge: wavesBeforeMerge.merge } : {}), ...(wavesBeforeMerge.mergeTokenSecret ? { mergeTokenSecret: wavesBeforeMerge.mergeTokenSecret } : {}), ...(productPlan?.reach?.gate ? { gate: productPlan.reach.gate } : {}) }
633
+ ? { ...(wavesBeforeMerge.merge ? { merge: wavesBeforeMerge.merge } : {}), ...(wavesBeforeMerge.mergeTokenSecret ? { mergeTokenSecret: wavesBeforeMerge.mergeTokenSecret } : {}), ...(wavesBeforeMerge.environment !== undefined ? { environment: wavesBeforeMerge.environment } : {}), ...(productPlan?.reach?.gate ? { gate: productPlan.reach.gate } : {}) }
611
634
  : undefined;
612
635
  // #4987: the apply statuses after each wave, and with a product plan the stale marking beside wave 1, one --member per target.
613
636
  const pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes" | "workflowFile" | "dispatchInputs" | "jobNames"> = {
@@ -744,6 +767,28 @@ export function componentWavesSpec(
744
767
  };
745
768
  }
746
769
 
770
+ /** GitLab's reserved top-level keys, which no job may be named. */
771
+ const GITLAB_RESERVED = new Set(["default", "include", "stages", "variables", "workflow", "image", "services", "cache", "before_script", "after_script", "spec", "pages"]);
772
+
773
+ /** The note poll's names (#5038), checked: only those the product gave, so a pipeline without them renders as before. */
774
+ function noteCommandsNames(forge: ForgeKind, given: ProductNoteCommandsJobOptions | undefined): Pick<NonNullable<ProductPipelineJobs["noteCommands"]>, "jobName" | "stage" | "schedule"> {
775
+ if (given === undefined) return {};
776
+ if (forge !== "gitlab") throw new Error(`noteCommandsJob names GitLab's note poll; on ${forge} the comment job (commentJob) answers comments`);
777
+ const name = (what: string, v: unknown): string => {
778
+ if (typeof v !== "string" || !/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(v) || GITLAB_RESERVED.has(v)) throw new Error(`noteCommandsJob.${what} ${JSON.stringify(v)} is not a GitLab ${what === "stage" ? "stage" : "job"} name of letters, digits, _, . and -, and no GitLab keyword`);
779
+ return v;
780
+ };
781
+ const s = given.schedule;
782
+ if (s !== undefined && (typeof s.variable !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(s.variable) || typeof s.value !== "string" || !/^[A-Za-z0-9_.-]+$/.test(s.value))) {
783
+ throw new Error(`noteCommandsJob.schedule ${JSON.stringify(s)} is a variable name and a value of letters, digits, _, . and -, such as { variable: "TERRAGUCCI_SCHEDULE", value: "comments" }`);
784
+ }
785
+ return {
786
+ ...(given.jobName !== undefined ? { jobName: name("jobName", given.jobName) } : {}),
787
+ ...(given.stage !== undefined ? { stage: name("stage", given.stage) } : {}),
788
+ ...(s !== undefined ? { schedule: { variable: s.variable, value: s.value } } : {}),
789
+ };
790
+ }
791
+
747
792
  /**
748
793
  * The comment job's descriptor (#4946): `chant components pr-comment
749
794
  * --forge <forge>` through the words' bin, the jobs it leaves comments to as
@@ -52,10 +52,19 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
52
52
  { name: "PRODUCT_PLAN_SUBJECT_FLOOR", version: "0.124.89", gates: "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.", issue: "#4972", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
53
53
  { name: "PRODUCT_PLAN_NAMES_FLOOR", version: "0.124.91", gates: "The first chant whose product plan keeps a product's own names (#5003): `workflowFile` (the generators' `path`), `jobNames` (the plan, note, re-plan and re-plan note jobs, with `{target}`), `statusContext` (which `pr-post --context`, the pending step, the stale job and the apply before merge use) and `reportDir` (`{output}`, the hand-off, the artifact's path and `pr-post --output`), and whose `pr-post --open` finds a plan job of the product's name (`--plan-job`).", issue: "#5003", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
54
54
  { name: "PRODUCT_PLAN_ARTIFACTS_FLOOR", version: "0.124.91", gates: "The first chant whose GitLab product plan job keeps a product's own artifacts beside the report directory (#5004): `productPlan.artifacts: { paths, reports }`, as `artifacts:paths` and `artifacts:reports`, such as terragucci's `terraform` report for the merge request's widget, with `{target}` and `{output}` filled.", issue: "#5004", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
55
- { name: "PRODUCT_PLAN_LOGIN_TOKENS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose GitHub and Forgejo product plan, after a `login` or with `idTokens`, starts every step after the checkout but the login's without `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` (#5021), as after a `trade`: the setup, the probe and the plan step, in the plan and the re-plan job, so the change's code can request no token.", issue: "#5021", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
56
- { name: "PR_HEAD_SHA_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose pull request jobs on GitHub and Forgejo name the pull request's head, `github.event.pull_request.head.sha`, where `github.sha` named the merge preview (#5020): the product plan's pending step (`CHANT_PENDING_SHA`), the note job's `HEAD_SHA` (the product plan's, the pull request loop's and the product pipeline's) and the `env-post` job's.", issue: "#5020", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
57
- { name: "OP_WAVES_NAMES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators keep a product's own names (#5022): `jobNames` (every job they write: a wave's, deciding, share and job group jobs, a split wave's plan, gate, apply and record jobs, the policy and evidence jobs, the apply status, stale, before-merge done and control jobs; `needs:`, `if:`, `{job}` and `--from-job` follow it), `stageNames` (GitLab), `artifactNames` (the outcome, decision, saved plan and check claims artifacts, and the pattern a wave job downloads the earlier outcomes with), `workflowFile` (the generators' file and the follow-on's dispatch), `runIf` (the jobs go in the product's own workflow, each running on a push it admits or a before-merge or follow-on dispatch, with its own permissions; on GitLab joined to every rule) and `dispatchInputs` (the dispatch inputs' names, which the comment job's dispatch and the follow-on use), with `buildForgejoOpWavesDoc` for the Forgejo jobs, and whose product pipeline's `wavesBeforeMerge` takes `workflowFile` and `dispatchInputs`.", issue: "#5022", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
58
- { name: "PRODUCT_JOB_NAMES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose product pipeline names its comment job and its waves' jobs as the product does (#5027): `commentJob: { jobName }` (default `comment`, such as terragucci's `apply-comment`), refused when another job of the workflow has the name, and `wavesJobNames`, the Op waves generators' `jobNames`, which `waves.pipeline` carries to the generator and `waves.jobs` takes, and under which the comment job's re-run of a merged pull request's apply looks for the waves' jobs (`CHANT_COMMENT_JOBS` `applyJobs`, `rerunApplyJobs`), so terragucci's `apply-wave-<k>`, `-share-<n>`, group jobs and `apply-rest` run again.", issue: "#5027", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
55
+ { name: "PRODUCT_PLAN_LOGIN_TOKENS_FLOOR", version: "0.124.92", gates: "The first chant whose GitHub and Forgejo product plan, after a `login` or with `idTokens`, starts every step after the checkout but the login's without `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` (#5021), as after a `trade`: the setup, the probe and the plan step, in the plan and the re-plan job, so the change's code can request no token.", issue: "#5021", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
56
+ { name: "PR_HEAD_SHA_FLOOR", version: "0.124.92", gates: "The first chant whose pull request jobs on GitHub and Forgejo name the pull request's head, `github.event.pull_request.head.sha`, where `github.sha` named the merge preview (#5020): the product plan's pending step (`CHANT_PENDING_SHA`), the note job's `HEAD_SHA` (the product plan's, the pull request loop's and the product pipeline's) and the `env-post` job's.", issue: "#5020", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
57
+ { name: "OP_WAVES_NAMES_FLOOR", version: "0.124.92", gates: "The first chant whose Op waves generators keep a product's own names (#5022): `jobNames` (every job they write: a wave's, deciding, share and job group jobs, a split wave's plan, gate, apply and record jobs, the policy and evidence jobs, the apply status, stale, before-merge done and control jobs; `needs:`, `if:`, `{job}` and `--from-job` follow it), `stageNames` (GitLab), `artifactNames` (the outcome, decision, saved plan and check claims artifacts, and the pattern a wave job downloads the earlier outcomes with), `workflowFile` (the generators' file and the follow-on's dispatch), `runIf` (the jobs go in the product's own workflow, each running on a push it admits or a before-merge or follow-on dispatch, with its own permissions; on GitLab joined to every rule) and `dispatchInputs` (the dispatch inputs' names, which the comment job's dispatch and the follow-on use), with `buildForgejoOpWavesDoc` for the Forgejo jobs, and whose product pipeline's `wavesBeforeMerge` takes `workflowFile` and `dispatchInputs`.", issue: "#5022", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
58
+ { name: "PRODUCT_JOB_NAMES_FLOOR", version: "0.124.92", gates: "The first chant whose product pipeline names its comment job and its waves' jobs as the product does (#5027): `commentJob: { jobName }` (default `comment`, such as terragucci's `apply-comment`), refused when another job of the workflow has the name, and `wavesJobNames`, the Op waves generators' `jobNames`, which `waves.pipeline` carries to the generator and `waves.jobs` takes, and under which the comment job's re-run of a merged pull request's apply looks for the waves' jobs (`CHANT_COMMENT_JOBS` `applyJobs`, `rerunApplyJobs`), so terragucci's `apply-wave-<k>`, `-share-<n>`, group jobs and `apply-rest` run again.", issue: "#5027", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
59
+ { name: "OP_WAVES_DEFAULT_BRANCH_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves run from the repository's default branch by the name the forge gives it at run time (#5032): the spec's `defaultBranch: true`, with or without `branches` beside it.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
60
+ { name: "OP_WAVES_FIRST_WAVE_NEEDS_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves generators take `firstWaveNeeds` (#5032): the product's own jobs, such as terragucci's `check`, that the first wave's own or deciding job (and before merge its plan job, and on GitLab its policy job) needs, so a push that fails the product's check applies nothing.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
61
+ { name: "NOTIFY_RELAY_NAME_FLOOR", version: "0.124.93", gates: "The first chant whose notify config takes `relayName` (#5033): the relay's name as people mention it in Teams, a plain value, which `sendNotify` (and so a wave's and a drift notice's messages) passes to the Teams card over the product's words' own, so a waiting wave's card spells out `reply @<name> approve <token>`.", issue: "#5033", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
62
+ { name: "OP_WAVES_RESUME_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves resume keeps a product's names (#5034): `resumeWorkflowFile` names the GitHub and Forgejo resume workflow's file (such as terragucci's `terragucci-resume.yml`; default `<spec>-resume.yml`, refused on GitLab and when it is the waves' own file), and `jobNames` is called for the resume job with the role `resume` (GitHub and Forgejo `resume`, GitLab `<spec>-resume` by default).", issue: "#5034", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
63
+ { name: "WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves before merge take `beforeMerge.environment` (#5037): the forge environment the job after the last wave runs in, so a merge token scoped to it reaches that job alone (GitLab `environment: { name, action: access }`, GitHub `environment: <name>`; Forgejo refuses it), with the product pipeline's `wavesBeforeMerge.environment` carried through `waves.pipeline`.", issue: "#5037", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
64
+ { name: "NOTE_POLL_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose GitLab note poll keeps a product's names (#5038): the product pipeline's `noteCommandsJob` gives its job's name (default `note-commands`), its stage (default the job's name) and the variable and value a pipeline schedule starts it with (default `CHANT_NOTE_COMMANDS=1`), such as terragucci's `comments` job and `TERRAGUCCI_SCHEDULE=comments`, rendered in the job, its stage, its rule, its resource group and the workflow's rules.", issue: "#5038", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
65
+ { name: "OP_WAVES_COMMAND_TOKEN_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own.", issue: "#5044", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
66
+ { name: "OP_WAVES_GITLAB_CACHE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache.", issue: "#5045", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
67
+ { name: "OP_WAVES_GROUPS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`.", issue: "#5053", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
59
68
  { name: "PRODUCT_ACTIONS_FLOOR", version: "0.124.58", gates: "Day-2 actions in the product pipeline (#4654): the `action` comment command counted as answered by the product's own workflow (`productPipelineJobs(forge, env, { words, actions: true })`), or the pipeline's own action job (`actionJob`, `build --pr-loop --action-job`), which answers the comment and a dispatch with a member and an action input, and runs the product's action verb with `--from-event`.", issue: "#4654", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
60
69
  { name: "APPROVAL_STATUS_FLOOR", version: "0.124.56", gates: "The approval status before merge (#4630): under a `pr-review` wave, the op waves generators add a job that posts `<product>/approval` on each open pull request's head.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
61
70
  { name: "APPROVAL_STATUS_PULL_REQUEST_FLOOR", version: "0.124.56", gates: "The approval status for `pull-request` waves too (#4630, 2026-10-28 ruling): the generators add the record-plans and approval-status jobs for a spec whose waves take the pull request's own approval, and the status reads that approval's coverage of each wave's change set.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
@@ -228,6 +237,10 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
228
237
  { name: "BEFORE_MERGE_REF_GATE_FLOOR", version: "0.124.89", gates: "The first chant whose `chant components pr-apply --before-merge` waits for the ref gate's status: the status the policy at base sets for the target branch is passed as `require` to the `checks` require (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
229
238
  { name: "TARGET_SIGNED_CHECKS_FLOOR", version: "0.124.89", gates: "The first chant whose product plan with `targets` and `evidence` signs each target's plan job as `plan:<target>` and `policy:<target>` (`ci evidence sign --member <target>`, `targetEvidenceCheck`, `productPlanEvidenceChecks`), and whose `refGateInitPlan` takes `targets` and names those checks in the `refs` rule (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/ref-gate-init","@intentius/chant/release-floors"] },
230
239
  { name: "RUNTIME_WAVES_SPEC_FLOOR", version: "0.124.89", gates: "The first chant whose Op waves generators take `renderSpec` (the wave jobs run `chant run wave --render-spec`, and `CHANT_WAVES_SPEC_COMMAND` names the product command that prints the spec at the commit in `CHANT_WAVES_SPEC_AT`), so a product whose spec is built from its config at base renders its wave jobs, policy step, evidence job and cloud trade through chant (#4982).", issue: "#4982", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
240
+ { name: "RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves `renderSpec` takes `runsAtHead` (the jobs carry `CHANT_WAVES_SPEC_RUNS=head`): the job's own spec is rendered at the applied commit, with `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`, so the runs a change adds apply at its merge, while the gate policy, holds, hooks and evidence rules still come from the render at base (#5046).", issue: "#5046", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
241
+ { name: "OP_WAVES_REMAINDER_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves keep the record of an apply under an approval themselves (#5047): with `approvals.spend`, `approvals.remainder` writes each change the approved plans make, the commit and the run on the applied line (a split wave's gate job writes it), the job that applies the whole wave or the record job writes how the apply ended, and a wave run again at that commit applies the rest under the same approval when its plans make only changes the stopped apply did not finish; a wave that plans no change closes a stopped apply, and `approvals.spendStanding` spends an approval of the digest a wave its gate let through applies.", issue: "#5047", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
242
+ { name: "OP_WAVES_SPLIT_RESUME_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `chant run resume` starts a killed split apply again on GitLab and Forgejo (#5052): under `approvals.remainder` the gate job's applied line names its run there too, GitLab's with the wave's applying and record jobs by name (`retry`), which the resume retries, and Forgejo's with the run's dispatch inputs (`inputs`), which the resume dispatches with, so the new run applies the rest at the same decided head or commit.", issue: "#5052", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-split-resume","@intentius/chant/release-floors"] },
243
+ { name: "OP_WAVES_REMAINDER_PARITY_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides.", issue: "#5056", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
231
244
  { name: "GITLAB_WAVE_EVIDENCE_RETRY_FLOOR", version: "0.124.89", gates: "The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
232
245
  { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: "0.124.91", gates: "The first chant whose terraform lexicon's engine runs carry what a product's own command tracing read: `runBinary` and the engine runner's `exec` and `execSync` answer stderr apart (`Ran.stderr`) and a spawn failure's message (`Ran.error`), a hook's `after` gets a binary that could not be started as a null code with `error`, `commandTrace` ends that span with the message, and `composeCommandHooks` runs a product's own hook and `commandTrace` as one `onCommand` (#5007).", issue: "#5007", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
233
246
  { name: "RUN_EVENT_FLOOR", version: "0.124.28", gates: "The first chant that writes contract version 1 of the run-event stream.", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
@@ -27,6 +27,13 @@
27
27
  * jobs before the gate run again too; they must be safe to repeat (a wave
28
28
  * whose runs already applied plans nothing and applies nothing new).
29
29
  *
30
+ * A killed split apply (#5052): a split wave's gate job writes the applied
31
+ * line, and its applying job is the one killed. On GitLab its locator names
32
+ * the wave's applying and record jobs (`retry`), and each applying job's
33
+ * newest try that failed or was cancelled is retried, then the record job.
34
+ * On Forgejo it carries the run's dispatch inputs (`inputs`), and the
35
+ * dispatch sends them, so a before-merge run plans the same decided head.
36
+ *
30
37
  * Resuming approves nothing. The resumed job decides the gate again from the
31
38
  * ledger, so resuming a run whose approval does not count only makes it wait
32
39
  * again. {@link resumeGateRun} skips a run that is still going, that ended
@@ -77,6 +84,8 @@ export function gitlabEvidenceJobOf(job: string): string {
77
84
 
78
85
  /** The GitLab job statuses of a job that ran and ended; a `skipped` or `created` job GitLab runs again after a retry itself. */
79
86
  const GITLAB_FINISHED = new Set(["success", "failed", "canceled"]);
87
+ /** The statuses of a job that is not going and will not start by itself: finished, skipped, or waiting for a person. */
88
+ const GITLAB_ENDED = new Set([...GITLAB_FINISHED, "skipped", "manual"]);
80
89
 
81
90
  const trimSlash = (s: string): string => s.replace(/\/+$/, "");
82
91
 
@@ -131,6 +140,28 @@ export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOpti
131
140
  if (loc.forge === "gitlab") {
132
141
  const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
133
142
  const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
143
+ // #5052: a split wave's applying jobs, by name in the same pipeline, and its record job after them.
144
+ if (loc.retry?.apply.length) {
145
+ const listed = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
146
+ // The list leaves retried jobs out, so the job of a name is its newest try.
147
+ const jobs = Array.isArray(listed) ? listed.filter(isObject) : [];
148
+ const newest = (name: string) => jobs.find((j) => j.name === name);
149
+ const applying = loc.retry.apply.map((name) => ({ name, job: newest(name) }));
150
+ const going = applying.find((a) => a.job && !GITLAB_ENDED.has(String(a.job.status)));
151
+ if (going) return skip(`job ${String(going.job!.id)} (${going.name}) is ${String(going.job!.status)}, not finished`);
152
+ const stopped = applying.filter((a) => a.job && (a.job.status === "failed" || a.job.status === "canceled"));
153
+ if (stopped.length > 0) {
154
+ const record = loc.retry.record ? newest(loc.retry.record) : undefined;
155
+ const after = record && GITLAB_FINISHED.has(String(record.status)) ? record : undefined;
156
+ const what = [...stopped.map((a) => `job ${String(a.job!.id)} (${a.name})`), ...(after ? [`its record job ${String(after.id)}`] : [])].join(" and ");
157
+ if (opts.dryRun) return wouldResume(`retry ${what}`);
158
+ for (const a of stopped) await call("POST", `${project}/jobs/${String(a.job!.id)}/retry`);
159
+ // It needs the applying jobs, so it waits for their new tries.
160
+ if (after) await call("POST", `${project}/jobs/${String(after.id)}/retry`);
161
+ return { status: "resumed", forge: "gitlab", how: `retried ${what}`, ...url };
162
+ }
163
+ // No applying job stopped: the gate job's own try says what is left (it succeeded, or stopped before them).
164
+ }
134
165
  const job = await call("GET", `${project}/jobs/${loc.job}`);
135
166
  if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
136
167
  const status = String(job.status);
@@ -172,16 +203,20 @@ export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOpti
172
203
  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
173
204
  // Forgejo reports `created` in whole seconds.
174
205
  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
206
+ // #5052: a run that a resume with inputs started is a dispatch; a push or a comment of the branch since is not one.
207
+ const inputs = loc.inputs && Object.keys(loc.inputs).length > 0 ? loc.inputs : undefined;
175
208
  const later = runs.find(
176
209
  (r) =>
177
210
  isObject(r) && Number(r.id) > Number(loc.run) &&
178
211
  (r.prettyref === undefined || r.prettyref === loc.ref) &&
212
+ (!inputs || r.event === undefined || r.event === "workflow_dispatch") &&
179
213
  (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
180
214
  );
181
215
  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
182
- if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
183
- await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
184
- return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
216
+ const with_ = inputs ? ` with ${Object.entries(inputs).map(([k, v]) => `${k}=${v}`).join(", ")}` : "";
217
+ if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}${with_}`);
218
+ await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref, ...(inputs ? { inputs } : {}) });
219
+ return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}${with_}`, ...url };
185
220
  }
186
221
 
187
222
  /**
package/src/lexicon.ts CHANGED
@@ -1182,7 +1182,11 @@ export interface OpWavesPipelineOptions
1182
1182
  * the commit in `CHANT_WAVES_SPEC_AT`. The spec handed to the generator
1183
1183
  * is the pipeline's shape (its waves, shares, job groups, `cloud`,
1184
1184
  * runners, environments and `holds.policy`); the rendered one sets the
1185
- * rules. Absent: the jobs read the committed spec as before.
1185
+ * rules. Absent: the jobs read the committed spec as before. With
1186
+ * `runsAtHead: true` (#5046) the jobs also carry
1187
+ * `CHANT_WAVES_SPEC_RUNS=head`: the job's own spec, its runs, is rendered
1188
+ * at the applied commit with `CHANT_WAVES_SPEC_BASE` set to the base, and
1189
+ * the rules still come from the render at base.
1186
1190
  */
1187
1191
  renderSpec?: import("./op/op-waves-render-spec").OpWavesRenderSpec;
1188
1192
  /**
@@ -1252,6 +1256,13 @@ export interface OpWavesPipelineOptions
1252
1256
  * record job dispatches. GitLab takes `opsFileName`. Absent: `<spec>.yml`.
1253
1257
  */
1254
1258
  workflowFile?: string;
1259
+ /**
1260
+ * GitHub and Forgejo (#5034): the file the spec's `resume` workflow goes
1261
+ * in, such as terragucci's `terragucci-resume.yml`. GitLab refuses it
1262
+ * (its resume job is in the pipeline; `jobNames` names it with the role
1263
+ * `resume`). Absent: `<spec>-resume.yml`.
1264
+ */
1265
+ resumeWorkflowFile?: string;
1255
1266
  /**
1256
1267
  * The jobs go in a product's own workflow or pipeline beside its other
1257
1268
  * jobs (#5022). GitHub and Forgejo: an expression (without `${{ }}`)
@@ -1271,6 +1282,58 @@ export interface OpWavesPipelineOptions
1271
1282
  * (`wavesBeforeMerge.dispatchInputs`). Absent: chant's.
1272
1283
  */
1273
1284
  dispatchInputs?: Partial<Record<import("./op/op-waves-names").OpWavesDispatchInput, string>>;
1285
+ /**
1286
+ * The product's own jobs the first wave's jobs need (#5032), such as
1287
+ * terragucci's `check`, so a push that fails the product's check applies
1288
+ * nothing. They go in `needs:` of wave 1's job (its deciding job for a
1289
+ * wide wave, and before merge its plan job). GitHub and Forgejo: each has
1290
+ * to pass, or, in a dispatched run, not have run. GitLab: each, optional,
1291
+ * has to pass (wave 1's policy job needs them too). The jobs must be in
1292
+ * the same workflow or pipeline, so this goes with `runIf`. Absent: none.
1293
+ */
1294
+ firstWaveNeeds?: string[];
1295
+ /**
1296
+ * GitHub and Forgejo (#5044): the job's token in the command step of the
1297
+ * jobs that run only the default branch's code (a push's wave, deciding,
1298
+ * share and job group jobs; a split wave's gate and record jobs), as
1299
+ * `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and
1300
+ * a failed apply's triage, and a product's hooks can read the forge. The
1301
+ * jobs ask for `permissions` beside chant's own, such as terragucci's
1302
+ * `pull-requests: write` and, with its review agent, `actions: read`.
1303
+ * A split wave's plan and applying jobs run the change's code and never
1304
+ * get it. GitLab refuses it: its jobs read `CHANT_FORGE_TOKEN`. Absent:
1305
+ * no wave job holds a token, as before.
1306
+ */
1307
+ commandToken?: import("./op/op-waves-names").OpWavesCommandToken;
1308
+ /**
1309
+ * GitLab (#5045): the `cache:` of each job that runs the wave's command
1310
+ * (the wave's own, deciding, share and job group jobs, the policy job, and
1311
+ * a split wave's plan and applying jobs), one entry or a list as GitLab
1312
+ * takes them, such as terragucci's Terragrunt sources and providers cache.
1313
+ * The gate and record jobs plan and apply nothing, so they take none.
1314
+ * GitHub and Forgejo refuse it: a wave's `setup` step does this there.
1315
+ * Absent: no cache, as before.
1316
+ */
1317
+ cache?: Record<string, unknown> | Array<Record<string, unknown>>;
1318
+ /**
1319
+ * The control job's group (#5053), so the control repo gets one send per
1320
+ * commit when a push's run and a resume's run both reach it: GitHub and
1321
+ * Forgejo `concurrency: { group, cancel-in-progress: false }`, GitLab
1322
+ * `resource_group`. `{commit}` in it stands for the commit the job tells
1323
+ * the control repo about (`${{ github.sha }}`, or a follow-on run's commit
1324
+ * input; GitLab `$CI_COMMIT_SHA` or `CHANT_WAVES_COMMIT`), such as
1325
+ * terragucci's `terragucci-control-${{ github.repository }}-{commit}`.
1326
+ * Needs `control` on the spec. Absent: no group, as before.
1327
+ */
1328
+ controlGroup?: string;
1329
+ /**
1330
+ * GitLab (#5053): the resume job's `resource_group`, such as terragucci's
1331
+ * `terragucci-resume`, so two resume pipelines that overlap do not both
1332
+ * retry the same waiting job. GitHub and Forgejo refuse it: their resume
1333
+ * workflow has its own group, `<spec>-resume`. Needs `resume` on the
1334
+ * spec. Absent: no resource group, as before.
1335
+ */
1336
+ resumeGroup?: string;
1274
1337
  }
1275
1338
 
1276
1339
  /** A run step a product adds to a generated job (#4791): its name, and its shell lines in order. */
@@ -53,6 +53,22 @@ export interface AppliedGateRecord {
53
53
  * hook again under it; any other job reads it as spent.
54
54
  */
55
55
  rerun?: { head: string };
56
+ /**
57
+ * Under `approvals.remainder` (#5047): each change the approved plans
58
+ * make, a run's resource and its digest, sorted. A wave run again at
59
+ * `commit` whose plans make only some of them applies those under this
60
+ * line's approval while no finished line says the apply applied.
61
+ */
62
+ changes?: AppliedGateChange[];
63
+ /** With `changes` (#5047): the digest members that are no run (the wave's cost), as the approved set held them. */
64
+ extras?: { member: string; planDigest: string }[];
65
+ }
66
+
67
+ /** One change an approved plan makes (#5047): a run's resource, by the engine's address, and its digest. */
68
+ export interface AppliedGateChange {
69
+ target: string;
70
+ address: string;
71
+ digest: string;
56
72
  }
57
73
 
58
74
  /**
@@ -40,8 +40,9 @@ describe("the notify bundle", () => {
40
40
  expect(inputs).toEqual(["packages/core/src/notify-verify.ts", "packages/core/src/notify.ts"]);
41
41
  expect(imports).toEqual(["node:crypto"]);
42
42
  // 17 KiB since ci.stale (#4678): the ci. events' names and headlines took it to 16.0 KiB, and the cap
43
- // is there to catch a dependency pulled in, which would add far more than an event name.
44
- expect(bytes).toBeLessThan(17 * 1024);
43
+ // is there to catch a dependency pulled in, which would add far more than an event name. 18 KiB since
44
+ // relayName (#5033), whose check and pass-through took it just over 17 KiB (17.3).
45
+ expect(bytes).toBeLessThan(18 * 1024);
45
46
  });
46
47
 
47
48
  test("the verifier holds itself alone, and imports only node:crypto", async () => {
@@ -0,0 +1,72 @@
1
+ /**
2
+ * #5033: a notify config's `relayName`, the relay's name as people mention
3
+ * it in Teams, so a waiting event's card says the whole reply. The
4
+ * `notify-defaults` golden was written from main before the change: a
5
+ * config without it sends what it sent.
6
+ */
7
+ import { describe, expect, test } from "vitest";
8
+ import { makeNotifyEvent, notifyConfigProblem, notifyVariables, sendNotify, type NotifyFetch } from "./notify";
9
+
10
+ const NOW = new Date("2026-10-11T12:00:00.000Z");
11
+ const GITHUB = { GITHUB_ACTIONS: "true", GITHUB_SERVER_URL: "https://github.com", GITHUB_REPOSITORY: "acme/db", GITHUB_RUN_ID: "42", GITHUB_SHA: "abc123" };
12
+ const DIGEST = "jcs1-sha256:" + "a".repeat(64);
13
+ const env = { ...GITHUB, SLACK: "https://hooks.slack.com/services/T/B/x", TEAMS: "https://teams.example/workflows/x", RELAY_KEY: "relay-secret" };
14
+
15
+ const waiting = makeNotifyEvent(
16
+ {
17
+ source: "terragucci",
18
+ event: "waiting",
19
+ summary: "wave 1 (wave-1) of tf-apply waits for an approval",
20
+ wave: { number: 1, name: "wave-1", gate: "wave-1" },
21
+ targets: ["network"],
22
+ digest: DIGEST,
23
+ approve: { command: `terragucci approve tf-apply wave-1 --plan ${DIGEST}` },
24
+ },
25
+ { env: GITHUB, now: NOW },
26
+ );
27
+
28
+ /** What each target was sent, by its URL's order. */
29
+ async function sent(config: Parameters<typeof sendNotify>[0]): Promise<unknown[]> {
30
+ const bodies: unknown[] = [];
31
+ const fetch: NotifyFetch = async (_url, init) => {
32
+ bodies.push(JSON.parse(init.body));
33
+ return { ok: true, status: 200 };
34
+ };
35
+ await sendNotify(config, waiting, { env, fetch, now: 1_760_184_000, sleep: async () => {}, log: () => {} });
36
+ return bodies;
37
+ }
38
+
39
+ type Card = { attachments: Array<{ content: { body: Array<{ type: string; text?: string; facts?: Array<{ title: string; value: string }> }> } }> };
40
+ const texts = (card: unknown): string => JSON.stringify((card as Card).attachments[0]!.content.body);
41
+
42
+ describe("notify with relayName (#5033)", () => {
43
+ test("the Teams card says the whole reply, mentioning the relay by name", async () => {
44
+ const [, teams] = await sent({ slack: "SLACK", teams: "TEAMS", relay: "RELAY_KEY", relayName: "Terragucci Relay" });
45
+ expect(texts(teams)).toContain("reply @Terragucci Relay approve ");
46
+ expect(texts(teams)).not.toContain("mention the relay and reply");
47
+ });
48
+
49
+ test("it is over the product's words' own name", async () => {
50
+ const bodies: unknown[] = [];
51
+ const fetch: NotifyFetch = async (_url, init) => (bodies.push(JSON.parse(init.body)), { ok: true, status: 200 });
52
+ await sendNotify({ teams: "TEAMS", relay: "RELAY_KEY", relayName: "acme-relay" }, waiting, { env, fetch, message: { relayName: "words-relay" }, sleep: async () => {}, log: () => {} });
53
+ expect(texts(bodies[0])).toContain("reply @acme-relay approve ");
54
+ });
55
+
56
+ test("without the relay's key there are no buttons, so the name changes nothing", async () => {
57
+ expect(await sent({ teams: "TEAMS", relayName: "acme-relay" })).toEqual(await sent({ teams: "TEAMS" }));
58
+ });
59
+
60
+ test("it is checked, and named by no variable", () => {
61
+ expect(notifyConfigProblem({ teams: "TEAMS", relayName: "acme-relay" })).toBeUndefined();
62
+ for (const bad of ["", " lead", "@acme", "a<b>", "two\nlines", "x".repeat(81), 7]) expect(notifyConfigProblem({ teams: "TEAMS", relayName: bad }), String(bad)).toMatch(/relayName/);
63
+ expect(notifyVariables({ teams: "TEAMS", relay: "RELAY_KEY", relayName: "acme-relay" })).toEqual(["TEAMS", "RELAY_KEY"]);
64
+ });
65
+ });
66
+
67
+ describe("notify without relayName (#5033)", () => {
68
+ test("Slack and Teams get what they got before", async () => {
69
+ await expect(JSON.stringify(await sent({ slack: "SLACK", teams: "TEAMS", relay: "RELAY_KEY" }), null, 2) + "\n").toMatchFileSnapshot("./__golden__/notify-defaults-relay.json");
70
+ await expect(JSON.stringify(await sent({ teams: "TEAMS" }), null, 2) + "\n").toMatchFileSnapshot("./__golden__/notify-defaults-plain.json");
71
+ });
72
+ });
package/src/notify.ts CHANGED
@@ -403,10 +403,18 @@ export interface NotifyConfig {
403
403
  * Decline buttons, and its Teams card the reply that approves.
404
404
  */
405
405
  relay?: string;
406
+ /**
407
+ * The relay's name as people mention it in Teams (#5033), such as a
408
+ * product's `notify.relay`: a waiting event's Teams card then says the
409
+ * whole reply, `reply @<name> approve <token>`. A plain value, not a
410
+ * variable, since it is no secret. Over the product's words' own
411
+ * `relayName`. Absent: the card says to mention the relay.
412
+ */
413
+ relayName?: string;
406
414
  }
407
415
 
408
416
  const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
409
- const SETTINGS = ["webhook", "key", "slack", "teams", "events", "relay"];
417
+ const SETTINGS = ["webhook", "key", "slack", "teams", "events", "relay", "relayName"];
410
418
 
411
419
  /** The first problem with a {@link NotifyConfig}, or undefined. `where` prefixes the message. */
412
420
  export function notifyConfigProblem(value: unknown, where = "notify"): string | undefined {
@@ -423,6 +431,9 @@ export function notifyConfigProblem(value: unknown, where = "notify"): string |
423
431
  }
424
432
  if (v.webhook !== undefined && v.key === undefined) return `${where}.key: a webhook needs a signing key; name the variable that holds it`;
425
433
  if (v.key !== undefined && v.webhook === undefined) return `${where}.webhook: a key is for a webhook; name the variable that holds its URL`;
434
+ if (v.relayName !== undefined && (typeof v.relayName !== "string" || !/^[^\s@<>][^\r\n@<>]{0,79}$/.test(v.relayName) || v.relayName.trim() !== v.relayName)) {
435
+ return `${where}.relayName: the relay's name as Teams mentions it, one line of at most 80 characters without @, < or >`;
436
+ }
426
437
  if (v.webhook === undefined && v.slack === undefined && v.teams === undefined) return `${where}: name a webhook (with its key), a slack or a teams URL variable`;
427
438
  if (v.events !== undefined && !(Array.isArray(v.events) && v.events.every((e) => (NOTIFY_EVENTS as readonly unknown[]).includes(e)))) {
428
439
  return `${where}.events: a list of ${NOTIFY_EVENTS.join(", ")}`;
@@ -571,7 +582,9 @@ export async function sendNotify(config: NotifyConfig | undefined, event: Notify
571
582
  const relayKey = config.relay ? env[config.relay] : undefined;
572
583
  if (config.relay && ref && !relayKey) log(`notify: ${config.relay} is not set, so the message carries no relay buttons`);
573
584
  const buttons = ref && relayKey ? { token: relayToken(relayKey, ref) } : undefined;
574
- if (config.slack) await deliver("slack", config.slack, () => json(options.render?.slack ? options.render.slack(event, buttons) : slackMessage(event, buttons, options.message)));
575
- if (config.teams) await deliver("teams", config.teams, () => json(options.render?.teams ? options.render.teams(event, buttons) : teamsMessage(event, buttons, options.message)));
585
+ // #5033: the config's relay name, over the product's words'.
586
+ const message = config.relayName ? { ...options.message, relayName: config.relayName } : options.message;
587
+ if (config.slack) await deliver("slack", config.slack, () => json(options.render?.slack ? options.render.slack(event, buttons) : slackMessage(event, buttons, message)));
588
+ if (config.teams) await deliver("teams", config.teams, () => json(options.render?.teams ? options.render.teams(event, buttons) : teamsMessage(event, buttons, message)));
576
589
  return out;
577
590
  }
@@ -195,6 +195,14 @@ export interface OpWavesBeforeMerge {
195
195
  mergeTokenSecret?: string;
196
196
  /** The lock file the change's locks are in, `_locks/<gate>.json`, which `merge: "auto"` releases. Default the pull request loop's. */
197
197
  gate?: string;
198
+ /**
199
+ * The forge environment the job after the last wave runs in (#5037), so
200
+ * a merge token scoped to it reaches that job alone, such as terragucci's
201
+ * `terragucci-merge`. GitLab: `environment: { name, action: access }`,
202
+ * which deploys nothing. GitHub: `environment: <name>`, whose secrets the
203
+ * job reads. Forgejo has no environments and refuses it. Absent: none.
204
+ */
205
+ environment?: string;
198
206
  }
199
207
 
200
208
  /** The job after the last wave of a before-merge run (#4984). */
@@ -208,6 +216,10 @@ export function assertOpWavesBeforeMerge(forge: "github" | "forgejo" | "gitlab",
208
216
  if (bm.merge !== undefined && bm.merge !== "auto" && bm.merge !== "manual") throw new Error(`beforeMerge.merge is auto or manual, not ${JSON.stringify(bm.merge)}`);
209
217
  if (bm.mergeTokenSecret !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(bm.mergeTokenSecret)) throw new Error(`beforeMerge.mergeTokenSecret ${JSON.stringify(bm.mergeTokenSecret)} is not a variable name`);
210
218
  if (bm.gate !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(bm.gate)) throw new Error(`beforeMerge.gate ${JSON.stringify(bm.gate)} is not a lock file name`);
219
+ if (bm.environment !== undefined) {
220
+ if (forge === "forgejo") throw new Error("beforeMerge.environment names a forge environment, and Forgejo Actions has none; scope the merge token another way, or leave it out");
221
+ if (typeof bm.environment !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.\/-]{0,254}$/.test(bm.environment)) throw new Error(`beforeMerge.environment ${JSON.stringify(bm.environment)} is not an environment name`);
222
+ }
211
223
  if (bm.merge === "auto" && forge !== "github" && !bm.mergeTokenSecret) {
212
224
  throw new Error(`beforeMerge.merge auto on ${forge} needs mergeTokenSecret: ${forge === "forgejo" ? "Forgejo refuses a merge made with the job's own token" : "GitLab's job token cannot merge"}`);
213
225
  }
@@ -28,6 +28,20 @@ export interface GateRunLocator {
28
28
  workflow?: string;
29
29
  /** Forgejo: the branch a dispatch runs on. */
30
30
  ref?: string;
31
+ /**
32
+ * GitLab (#5052): the jobs of the same pipeline a resume retries, by name,
33
+ * in place of `job`: a split wave's applying jobs, each retried when its
34
+ * newest try failed or was cancelled, and its record job, retried after
35
+ * them when it ran. The gate job that writes the applied line knows their
36
+ * names, not their ids.
37
+ */
38
+ retry?: { apply: string[]; record?: string };
39
+ /**
40
+ * Forgejo (#5052): the `workflow_dispatch` inputs a resume dispatches
41
+ * with, so a before-merge run or a follow-on is started again for the
42
+ * same decided head or commit instead of the branch's head.
43
+ */
44
+ inputs?: Record<string, string>;
31
45
  /** The run's page, for a person. */
32
46
  url?: string;
33
47
  }
package/src/op/index.ts CHANGED
@@ -143,14 +143,19 @@ export { notifyOpWave, opWaveNotifyFields } from "./op-waves-notify";
143
143
  export {
144
144
  OP_WAVES_RENDER_SPEC_FLAG,
145
145
  OP_WAVES_SPEC_AT_ENV,
146
+ OP_WAVES_SPEC_BASE_ENV,
146
147
  OP_WAVES_SPEC_COMMAND_ENV,
147
148
  OP_WAVES_SPEC_FILE_ENV,
149
+ OP_WAVES_SPEC_RUNS_ENV,
148
150
  RUNTIME_WAVES_SPEC_FLOOR,
151
+ RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR,
149
152
  opWavesRenderSpecEnv,
150
153
  opWavesRenderSpecProblems,
151
154
  } from "./op-waves-render-spec";
152
155
  export type { OpWavesRenderSpec } from "./op-waves-render-spec";
153
- export { OP_WAVE_STAND_DOWN_FLOOR, gitOpWaveNewerCommit, newerCommitOnBranch, opWaveRunBranch, opWaveStandDownReason, tipAppliesTargets } from "./op-waves-stand-down";
156
+ export { OP_WAVES_REMAINDER_FLOOR, opWaveApprovedChanges, opWaveCoverRemainder, opWaveRunCovered, opWaveStoppedApply, opWaveUnfinishedApply } from "./op-waves-remainder";
157
+ export type { AppliedGateChange, OpWaveCover, OpWaveRemainderMember } from "./op-waves-remainder";
158
+ export { OP_WAVE_STAND_DOWN_FLOOR, gitOpWaveNewerCommit, newerCommitOnBranch, opWaveDefaultBranch, opWaveRunBranch, opWaveStandDownReason, tipAppliesTargets } from "./op-waves-stand-down";
154
159
  export type { OpWaveNewerCommit, OpWaveNewerCommitPort } from "./op-waves-stand-down";
155
160
  export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems, releaseOfCommit } from "./op-waves-release";
156
161
  export { gitOpWaveReleasePort } from "./op-waves-release-port";