@intentius/chant 0.124.91 → 0.124.93

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 (108) 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-comment-commands.d.ts +11 -1
  4. package/dist/ci-comment-commands.d.ts.map +1 -1
  5. package/dist/ci-comment-commands.js +10 -3
  6. package/dist/ci-job-guard.d.ts +22 -8
  7. package/dist/ci-job-guard.d.ts.map +1 -1
  8. package/dist/ci-job-guard.js +93 -49
  9. package/dist/ci-jobs.d.ts +22 -0
  10. package/dist/ci-jobs.d.ts.map +1 -1
  11. package/dist/ci-jobs.js +23 -0
  12. package/dist/ci-product.d.ts +42 -1
  13. package/dist/ci-product.d.ts.map +1 -1
  14. package/dist/ci-product.js +44 -3
  15. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  16. package/dist/cli/handlers/pr-comment.js +15 -2
  17. package/dist/cli/handlers/pr.d.ts.map +1 -1
  18. package/dist/cli/handlers/pr.js +4 -1
  19. package/dist/components/pr-pipeline.d.ts +4 -2
  20. package/dist/components/pr-pipeline.d.ts.map +1 -1
  21. package/dist/components/pr-pipeline.js +7 -4
  22. package/dist/components/product-pipeline.d.ts +71 -7
  23. package/dist/components/product-pipeline.d.ts.map +1 -1
  24. package/dist/components/product-pipeline.js +84 -22
  25. package/dist/components/product-plan.d.ts +7 -0
  26. package/dist/components/product-plan.d.ts.map +1 -1
  27. package/dist/components/product-plan.js +1 -0
  28. package/dist/floor-table.data.d.ts.map +1 -1
  29. package/dist/floor-table.data.js +15 -5
  30. package/dist/lexicon.d.ts +59 -1
  31. package/dist/lexicon.d.ts.map +1 -1
  32. package/dist/notify.d.ts +8 -0
  33. package/dist/notify.d.ts.map +1 -1
  34. package/dist/notify.js +8 -3
  35. package/dist/op/before-merge-decide.d.ts +2 -0
  36. package/dist/op/before-merge-decide.d.ts.map +1 -1
  37. package/dist/op/before-merge.d.ts +8 -0
  38. package/dist/op/before-merge.d.ts.map +1 -1
  39. package/dist/op/before-merge.js +6 -0
  40. package/dist/op/index.d.ts +1 -1
  41. package/dist/op/index.d.ts.map +1 -1
  42. package/dist/op/index.js +1 -1
  43. package/dist/op/op-waves-evidence-jobs.d.ts +3 -2
  44. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  45. package/dist/op/op-waves-evidence-jobs.js +4 -3
  46. package/dist/op/op-waves-follow-on.d.ts +2 -0
  47. package/dist/op/op-waves-follow-on.d.ts.map +1 -1
  48. package/dist/op/op-waves-follow-on.js +8 -2
  49. package/dist/op/op-waves-names.d.ts +145 -0
  50. package/dist/op/op-waves-names.d.ts.map +1 -0
  51. package/dist/op/op-waves-names.js +201 -0
  52. package/dist/op/op-waves-run.d.ts +2 -0
  53. package/dist/op/op-waves-run.d.ts.map +1 -1
  54. package/dist/op/op-waves-run.js +2 -2
  55. package/dist/op/op-waves-stand-down.d.ts +9 -1
  56. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  57. package/dist/op/op-waves-stand-down.js +14 -2
  58. package/dist/op/op-waves.d.ts +12 -1
  59. package/dist/op/op-waves.d.ts.map +1 -1
  60. package/dist/op/op-waves.js +2 -0
  61. package/dist/pr-forge-job.d.ts +8 -0
  62. package/dist/pr-forge-job.d.ts.map +1 -1
  63. package/dist/pr-forge-job.js +13 -0
  64. package/dist/pr-plan-record.d.ts +3 -1
  65. package/dist/pr-plan-record.d.ts.map +1 -1
  66. package/dist/pr-plan-record.js +1 -1
  67. package/dist/pr-post.d.ts +9 -3
  68. package/dist/pr-post.d.ts.map +1 -1
  69. package/dist/pr-post.js +5 -2
  70. package/dist/release-floors.d.ts +1 -1
  71. package/dist/release-floors.d.ts.map +1 -1
  72. package/dist/release-floors.js +4 -4
  73. package/dist/wave-runtime.mjs +305 -305
  74. package/package.json +1 -1
  75. package/src/__golden__/notify-defaults-plain.json +52 -0
  76. package/src/__golden__/notify-defaults-relay.json +92 -0
  77. package/src/ci-comment-commands.test.ts +19 -5
  78. package/src/ci-comment-commands.ts +18 -3
  79. package/src/ci-job-guard.default-branch.test.ts +125 -0
  80. package/src/ci-job-guard.ts +64 -10
  81. package/src/ci-jobs.ts +26 -0
  82. package/src/ci-product.ts +54 -3
  83. package/src/cli/handlers/pr-comment.ts +12 -2
  84. package/src/cli/handlers/pr.ts +4 -1
  85. package/src/components/pr-pipeline.ts +7 -4
  86. package/src/components/product-job-names.test.ts +176 -0
  87. package/src/components/product-pipeline.ts +143 -31
  88. package/src/components/product-plan.ts +8 -0
  89. package/src/floor-table.data.ts +15 -5
  90. package/src/lexicon.ts +59 -1
  91. package/src/notify-bundle.test.ts +3 -2
  92. package/src/notify-relay-name.test.ts +72 -0
  93. package/src/notify.ts +16 -3
  94. package/src/op/before-merge-decide.ts +2 -0
  95. package/src/op/before-merge.ts +12 -0
  96. package/src/op/index.ts +1 -1
  97. package/src/op/op-waves-evidence-jobs.ts +4 -3
  98. package/src/op/op-waves-follow-on.ts +10 -2
  99. package/src/op/op-waves-names.test.ts +131 -0
  100. package/src/op/op-waves-names.ts +289 -0
  101. package/src/op/op-waves-run.ts +4 -2
  102. package/src/op/op-waves-stand-down.ts +15 -2
  103. package/src/op/op-waves.ts +13 -1
  104. package/src/pr-forge-job.ts +13 -0
  105. package/src/pr-plan-record.ts +4 -2
  106. package/src/pr-post-head.test.ts +116 -0
  107. package/src/pr-post.ts +15 -5
  108. package/src/release-floors.ts +4 -4
@@ -50,6 +50,8 @@ import { COMMENT_JOBS_ENV, PR_COMMENT_JOB, type CommentJobs } from "../ci-commen
50
50
  import { GITHUB_JOB_TOKEN } from "../ci-jobs";
51
51
  import type { OpWavesBeforeMerge } from "../op/before-merge";
52
52
  import { defaultPipelineFiles, type WavesBeforeMergeJobs } from "../op/before-merge-decide";
53
+ import { opWavesDispatchInputs, opWavesInputsRenamed, opWavesNamer, opWavesWorkflowFile, type OpWavesJobNames } from "../op/op-waves-names";
54
+ import { opWaveSplitJobs } from "../op/op-waves-split";
53
55
  import type { PrApplyRequire } from "../pr-requires";
54
56
  import { LOCK_REACH_ENV } from "../lifecycle/reach-locks";
55
57
 
@@ -149,9 +151,29 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
149
151
  * chant's), and with waves on merge the re-run of a merged pull request's
150
152
  * apply. The jobs it leaves comments to are the ones these options write.
151
153
  * On GitLab the note-commands job answers every note already; refused
152
- * there.
154
+ * there. `{ jobName }` (#5027) names the job, such as terragucci's
155
+ * `apply-comment`. Default `comment`.
153
156
  */
154
- commentJob?: boolean;
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;
168
+ /**
169
+ * The waves' job names (#5027), the Op waves generators' `jobNames`
170
+ * (#5022): `waves.pipeline` carries them to the generator, `waves.jobs`
171
+ * takes them, and the comment job's re-run of a merged pull request's
172
+ * apply looks for the jobs under them (`CHANT_COMMENT_JOBS`
173
+ * `applyJobs`). Absent: chant's names, and the re-run looks for
174
+ * `RERUN_APPLY_JOBS`. Needs `waves` (or `componentWaves`).
175
+ */
176
+ wavesJobNames?: OpWavesJobNames;
155
177
  /**
156
178
  * Waves before merge (#4984, maintainer decision 2026-11-10): `/<product>
157
179
  * apply [wave-<n>]` on an open pull request runs the waves on its head.
@@ -187,13 +209,46 @@ export interface ProductWavesBeforeMerge {
187
209
  merge?: "auto" | "manual";
188
210
  /** The merge token's secret or CI/CD variable, with `merge: "auto"` (needed on Forgejo and GitLab). */
189
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;
190
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/`. */
191
215
  pipelineFiles?: string[];
216
+ /**
217
+ * GitHub and Forgejo (#5022): the workflow the waves are in, which the
218
+ * comment job dispatches, such as `terragucci.yml`. Default `<op>.yml`.
219
+ * The product passes `waves.pipeline` on, which carries it as the
220
+ * generator's `workflowFile`.
221
+ */
222
+ workflowFile?: string;
223
+ /**
224
+ * GitHub and Forgejo (#5022): the waves workflow's names of the inputs
225
+ * `pr`, `head` and `digest`, which the comment job dispatches with, so
226
+ * they never meet the product's own. `waves.pipeline` carries them as
227
+ * the generator's `dispatchInputs`. Default chant's.
228
+ */
229
+ dispatchInputs?: Partial<Record<"pr" | "head" | "digest", string>>;
230
+ }
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
+
242
+ /** {@link ProductPipelineOptions.commentJob}'s settings (#5027). */
243
+ export interface ProductCommentJobOptions {
244
+ /** The comment job's name in the workflow, such as `apply-comment`. Default {@link PR_COMMENT_JOB}. */
245
+ jobName?: string;
192
246
  }
193
247
 
194
248
  /** The comment job (#4946): its command, the values it reads, and the comment prefixes that start it. */
195
249
  export interface ProductCommentJob {
196
- jobName: typeof PR_COMMENT_JOB;
250
+ /** {@link PR_COMMENT_JOB}, or the product's `commentJob.jobName` (#5027). */
251
+ jobName: string;
197
252
  /** `<bin> components pr-comment --forge <forge>`. */
198
253
  command: string;
199
254
  /** `GITHUB_TOKEN` and {@link COMMENT_JOBS_ENV}. */
@@ -241,8 +296,10 @@ export interface ProductPipelineJobs {
241
296
  * `applyStatus` and, with `staleNotes`, the stale marking job that runs
242
297
  * beside wave 1 on a push (one `--member` per product plan target). The
243
298
  * product spreads it into the `OpWavesPipelineOptions` it renders with.
299
+ * #5022: with them, `wavesBeforeMerge`'s `workflowFile` and
300
+ * `dispatchInputs`, which the comment job dispatches by.
244
301
  */
245
- pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes">;
302
+ pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes" | "workflowFile" | "dispatchInputs" | "jobNames">;
246
303
  };
247
304
  /**
248
305
  * The comment lock and unlock jobs (#4588), under `locks: "plan"`:
@@ -271,7 +328,7 @@ export interface ProductPipelineJobs {
271
328
  * lexicon renders the same job from `chant build --pr-loop
272
329
  * --note-commands`. Refused on GitHub and Forgejo.
273
330
  */
274
- 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 } };
275
332
  /**
276
333
  * The agent (#4616), with `agent`: the comment it answers, `/<product>
277
334
  * agent <ask>`, and the scheduled Op spec whose generated workflow runs
@@ -410,7 +467,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
410
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.
411
468
  const answered: CiProductCommand[] = options.commentJob ? [...new Set<CiProductCommand>([...jobs, ...CI_PRODUCT_COMMANDS.filter((c) => c !== "commit")])] : jobs;
412
469
  const words = assertProductWords({ ...options.words, applyMode }, { jobs: answered });
413
- const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, wavesBeforeMerge, applyStatus: _applyStatus, ...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;
414
471
  if (options.applyStatus && !given && !componentWaves) throw new Error("applyStatus posts the waves' apply statuses, and there are none: give waves (or componentWaves)");
415
472
  const { respond } = options;
416
473
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
@@ -466,7 +523,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
466
523
  // #4785: GitLab's comment commands, polled from the notes; waves on merge are retried by an apply on a merged merge request.
467
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.
468
525
  const notes = prNoteCommandsJob(forge, { ...prLoop, ...(options.waves || options.componentWaves ? { applyOnMerge: true } : {}), ...(productPlan?.replan ? { previewComment: true } : {}) });
469
- 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`);
470
528
  const preview = prCommentPreviewJob(forge, env, prLoop, member);
471
529
  if (preview) out.preview = { ...preview, ...(defaultRunner.runner !== undefined ? { noteRunner: defaultRunner.runner } : {}) };
472
530
  // #4616: the agent answers its comment from a workflow of its own, generated from this spec.
@@ -495,8 +553,13 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
495
553
  if (options.applyBeforeMerge) throw new Error("wavesBeforeMerge and applyBeforeMerge both answer an open pull request's apply; give one");
496
554
  if (forge === "gitlab" ? !options.noteCommands : !options.commentJob) throw new Error(`wavesBeforeMerge is decided by ${forge === "gitlab" ? "the note poll: set noteCommands" : "the comment job: set commentJob"}`);
497
555
  const targets = productPlan?.targets?.map((t) => t.name);
556
+ if (forge === "gitlab" && (wavesBeforeMerge.workflowFile !== undefined || wavesBeforeMerge.dispatchInputs !== undefined)) throw new Error("wavesBeforeMerge.workflowFile and dispatchInputs name a GitHub or Forgejo workflow; GitLab's note poll starts a pipeline with variables");
557
+ // #5022: the product's workflow and input names, checked as the generator checks them.
558
+ const workflowFile = opWavesWorkflowFile({ name: wavesOp }, wavesBeforeMerge.workflowFile);
559
+ const dispatchInputs = wavesBeforeMerge.dispatchInputs ? opWavesDispatchInputs(wavesBeforeMerge.dispatchInputs) : undefined;
498
560
  bmJobs = {
499
- ...(forge !== "gitlab" ? { workflow: `${wavesOp}.yml` } : {}),
561
+ ...(forge !== "gitlab" ? { workflow: workflowFile } : {}),
562
+ ...(dispatchInputs && opWavesInputsRenamed(dispatchInputs) ? { inputs: { pr: dispatchInputs.pr, head: dispatchInputs.head, digest: dispatchInputs.digest } } : {}),
500
563
  ...(wavesBeforeMerge.requires ? { requires: [...wavesBeforeMerge.requires] } : {}),
501
564
  // #5003: the product's own status contexts, when it named them.
502
565
  plan: planContexts ?? (targets?.length ? targets.map((t) => productStatusContext(words, "plan", t)) : [productStatusContext(words, "plan", member)]),
@@ -514,6 +577,27 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
514
577
  },
515
578
  };
516
579
  }
580
+ const wavesRespond = respond ? Object.fromEntries(Object.entries(respond).filter(([e]) => e !== "description")) : {};
581
+ // #4625: the waves run on the apply runner and with the plan's parallelism, unless the spec names its own.
582
+ const applyRunner = prLoopRunner(options, "apply");
583
+ const named = spec
584
+ ? {
585
+ ...productWavesSpec(
586
+ {
587
+ ...spec,
588
+ ...(spec.runner === undefined && applyRunner !== undefined ? { runner: applyRunner } : {}),
589
+ ...(spec.parallelism === undefined && options.parallelism !== undefined && spec.step !== undefined ? { parallelism: options.parallelism } : {}),
590
+ },
591
+ words,
592
+ ),
593
+ ...(Object.keys(wavesRespond).length > 0 ? { respond: { ...(spec.respond ?? {}), ...wavesRespond } } : {}),
594
+ }
595
+ : undefined;
596
+ const specFile = named ? (wavesSpecFile ?? productWavesSpecFile(named.name)) : undefined;
597
+ if (wavesJobNames !== undefined && !named) throw new Error("wavesJobNames names the waves' jobs, and there are none: give waves (or componentWaves)");
598
+ // #5027: the waves' jobs under the product's names, the same the generator gives them from the same jobNames.
599
+ const waveJobs = named && specFile ? opWaveJobs(named, specFile, { bin: words.bin, ...(wavesBeforeMerge ? { beforeMerge: true } : {}) }) : undefined;
600
+ const namedWaveJobs = waveJobs && wavesJobNames ? opWavesNamer(named!, forge, wavesJobNames).jobs(waveJobs) : waveJobs;
517
601
  // #4946: the comment job answers what no other job of the pipeline takes, so it is told which jobs there are.
518
602
  if (options.commentJob) {
519
603
  // #4963's re-plan reply answers the same stray comments, so one of the two answers them.
@@ -535,39 +619,43 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
535
619
  ...(out.agent ? { agent: true } : {}),
536
620
  ...(out.commits ? { commits: true } : {}),
537
621
  ...(options.actions || options.actionJob ? { actions: true } : {}),
622
+ // #5027: a re-run looks for the waves' jobs by the product's names; without them, by chant's pattern.
623
+ ...(namedWaveJobs && wavesJobNames ? { applyJobs: productApplyJobs(named!, waveJobs!, namedWaveJobs, forge, wavesJobNames, wavesBeforeMerge !== undefined) } : {}),
538
624
  };
539
- const comment = productCommentJob(forge, words, commentJobs);
625
+ const comment = productCommentJob(forge, words, commentJobs, typeof options.commentJob === "object" ? options.commentJob.jobName : undefined);
540
626
  // #4984: the decision before merge locks what the reach line prints, at stage apply.
541
627
  if (bmJobs && productPlan?.reach) comment.env = { ...comment.env, [LOCK_REACH_ENV]: productPlan.reach.command };
542
628
  out.comment = { ...comment, ...defaultRunner };
543
629
  }
544
- if (!spec) return { ...out, record: record! };
545
- const wavesRespond = respond ? Object.fromEntries(Object.entries(respond).filter(([e]) => e !== "description")) : {};
546
- // #4625: the waves run on the apply runner and with the plan's parallelism, unless the spec names its own.
547
- const applyRunner = prLoopRunner(options, "apply");
548
- const named = {
549
- ...productWavesSpec(
550
- {
551
- ...spec,
552
- ...(spec.runner === undefined && applyRunner !== undefined ? { runner: applyRunner } : {}),
553
- ...(spec.parallelism === undefined && options.parallelism !== undefined && spec.step !== undefined ? { parallelism: options.parallelism } : {}),
554
- },
555
- words,
556
- ),
557
- ...(Object.keys(wavesRespond).length > 0 ? { respond: { ...(spec.respond ?? {}), ...wavesRespond } } : {}),
558
- };
559
- const specFile = wavesSpecFile ?? productWavesSpecFile(named.name);
630
+ if (!named || !specFile || !namedWaveJobs) return { ...out, record: record! };
560
631
  // #4984: what the generator's before-merge mode takes: the merge after the last wave and the lock file it releases.
561
632
  const beforeMerge: OpWavesBeforeMerge | undefined = wavesBeforeMerge
562
- ? { ...(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 } : {}) }
563
634
  : undefined;
564
635
  // #4987: the apply statuses after each wave, and with a product plan the stale marking beside wave 1, one --member per target.
565
- const pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes"> = {
636
+ const pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes" | "workflowFile" | "dispatchInputs" | "jobNames"> = {
566
637
  ...(beforeMerge ? { beforeMerge } : {}),
638
+ // #5027: the same job names the comment job's re-run looks for.
639
+ ...(wavesJobNames ? { jobNames: wavesJobNames } : {}),
640
+ // #5022: the workflow and input names the comment job dispatches, for the generator.
641
+ ...(wavesBeforeMerge?.workflowFile ? { workflowFile: wavesBeforeMerge.workflowFile } : {}),
642
+ ...(wavesBeforeMerge?.dispatchInputs ? { dispatchInputs: { ...wavesBeforeMerge.dispatchInputs } } : {}),
567
643
  ...(options.applyStatus ? { applyStatus: { context: productStatusContext(words, "apply", member) } } : {}),
568
644
  ...(planStale ? { staleNotes: planStale } : {}),
569
645
  };
570
- return { ...out, waves: { spec: named, specFile, jobs: opWaveJobs(named, specFile, { bin: words.bin, ...(beforeMerge ? { beforeMerge: true } : {}) }), ...(beforeMerge ? { beforeMerge } : {}), pipeline } };
646
+ return { ...out, waves: { spec: named, specFile, jobs: namedWaveJobs, ...(beforeMerge ? { beforeMerge } : {}), pipeline } };
647
+ }
648
+
649
+ /**
650
+ * The waves' jobs a re-run looks for, by the product's names (#5027): each
651
+ * wave's job, its deciding, share and job group jobs, and before merge the
652
+ * split jobs, named as the Op waves generator names them from the same
653
+ * `jobNames`.
654
+ */
655
+ function productApplyJobs(spec: OpWavesSpec, chantJobs: readonly OpWaveJob[], named: readonly OpWaveJob[], forge: ForgeKind, jobNames: OpWavesJobNames, split: boolean): string[] {
656
+ const out = named.map((j) => j.jobName);
657
+ if (split) out.push(...opWavesNamer(spec, forge, jobNames).jobs(opWaveSplitJobs(spec, chantJobs)).map((j) => j.jobName));
658
+ return [...new Set(out)];
571
659
  }
572
660
 
573
661
  /** The capability steps a component waves spec runs (#4545, #4541): argv templates over `{runs}` and `{plans}`. */
@@ -679,18 +767,42 @@ export function componentWavesSpec(
679
767
  };
680
768
  }
681
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
+
682
792
  /**
683
793
  * The comment job's descriptor (#4946): `chant components pr-comment
684
794
  * --forge <forge>` through the words' bin, the jobs it leaves comments to as
685
795
  * {@link COMMENT_JOBS_ENV}, and the comment prefixes the forge's `if:`
686
796
  * starts it on. Throws on GitLab, whose note-commands job answers every
687
- * note.
797
+ * note. `jobName` is the product's name for the job (#5027), default
798
+ * {@link PR_COMMENT_JOB}.
688
799
  */
689
- export function productCommentJob(forge: ForgeKind, words: CiProductWords, jobs: CommentJobs): ProductCommentJob {
800
+ export function productCommentJob(forge: ForgeKind, words: CiProductWords, jobs: CommentJobs, jobName: string = PR_COMMENT_JOB): ProductCommentJob {
690
801
  if (forge === "gitlab") throw new Error("the comment job answers a GitHub or Forgejo comment; on GitLab the note-commands job (noteCommands) answers every note, so drop commentJob");
691
802
  for (const a of words.aliases) if (/['\\]/.test(a.from)) throw new Error(`the alias ${JSON.stringify(a.from)} holds a quote, which the comment job's condition cannot carry`);
803
+ if (typeof jobName !== "string" || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(jobName)) throw new Error(`commentJob.jobName ${JSON.stringify(jobName)} is not a job name of letters, digits, _ and -, starting with a letter or _`);
692
804
  return {
693
- jobName: PR_COMMENT_JOB,
805
+ jobName,
694
806
  command: withProductBin(`chant components pr-comment --forge ${forge}`, words.bin),
695
807
  env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN, [COMMENT_JOBS_ENV]: JSON.stringify(jobs) },
696
808
  prefixes: [`/${words.product}`, ...words.aliases.map((a) => a.from)],
@@ -512,6 +512,13 @@ export interface ProductPlanJob {
512
512
  login?: OpWaveRunStep[];
513
513
  /** The OIDC tokens the plan job requests (#4931), `{ <variable>: <audience> }`: the login's and the product's own. */
514
514
  idTokens?: Record<string, string>;
515
+ /**
516
+ * With the product's own `idTokens` (#5021): the plan verb asks the forge
517
+ * for them by audience, so on GitHub and Forgejo the plan step keeps the
518
+ * variables a token is requested with. Without it, every step after the
519
+ * checkout but the login's starts without them.
520
+ */
521
+ ownIdTokens?: true;
515
522
  /** The pending status posted before the checkout (#4899), on GitHub and Forgejo. */
516
523
  pending?: { context: string; description: string };
517
524
  /** The control repo read after the checkout (#4899). */
@@ -769,6 +776,7 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
769
776
  ...(Object.keys(jobEnv).length > 0 ? { jobEnv } : {}),
770
777
  ...(login && login.steps.length > 0 ? { login: login.steps } : {}),
771
778
  ...(Object.keys(idTokens).length > 0 ? { idTokens } : {}),
779
+ ...(Object.keys(ownTokens ?? {}).length > 0 ? { ownIdTokens: true as const } : {}),
772
780
  ...(plan.pending && github ? { pending: { context: context ?? productStatusContext(words, "plan", name), description: "planning" } } : {}),
773
781
  ...(control ? { control } : {}),
774
782
  ...(plan.setup?.length ? { setup: plan.setup } : {}),
@@ -50,8 +50,18 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
50
50
  { name: "PRODUCT_PLAN_RECORD_FLOOR", version: "0.124.88", gates: "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.", issue: "#4899", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
51
51
  { name: "PRODUCT_PLAN_REPLAN_FLOOR", version: "0.124.89", gates: "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`).", issue: "#4963", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
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
- { name: "PRODUCT_PLAN_NAMES_FLOOR", version: NEXT_RELEASE, 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
- { name: "PRODUCT_PLAN_ARTIFACTS_FLOOR", version: NEXT_RELEASE, 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"] },
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
+ { 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: "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: NEXT_RELEASE, 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: NEXT_RELEASE, 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: NEXT_RELEASE, 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: NEXT_RELEASE, 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: NEXT_RELEASE, 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: NEXT_RELEASE, 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"] },
55
65
  { 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"] },
56
66
  { 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"] },
57
67
  { 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"] },
@@ -216,16 +226,16 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
216
226
  { name: "CHECK_JOB_ARTIFACTS_FLOOR", version: "0.124.90", gates: "The first chant whose `checkJob` takes `artifacts: { paths, reports }` (`PrCheckArtifacts`), which GitLab's check job keeps beside its report as `artifacts:paths` and `artifacts:reports`, such as a lint hook's `codequality` report (#4988).", issue: "#4988", file: "release-floors.ts", modules: ["@intentius/chant/components/pr-checks","@intentius/chant/release-floors"] },
217
227
  { name: "GITLAB_WAVE_KEY_SCOPE_FLOOR", version: "0.124.89", gates: "The first chant whose GitLab Op waves pipeline with a runner key hands it to no wave job: each deciding wave's `<wave job>-evidence` job names the `chant-evidence` environment and signs `plan:<wave>` from the wave job (#4964).", issue: "#4964", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
218
228
  { name: "ACTOR_ORDER_FLOOR", version: "0.124.89", gates: "The first chant with `actorOf` and `actorOrder` in `@intentius/chant/actor`: the actor fallback with `GITHUB_TRIGGERING_ACTOR` ahead of the forge's actor and git's `user.name` before the login, each place switched on or off by the caller (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/actor","@intentius/chant/release-floors"] },
219
- { name: "ACTOR_GIT_ENV_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `actorOf({ env, repo })` runs `git config` in `repo` with the `env` it is given rather than the process's, so a job's `GIT_CONFIG_GLOBAL` or `HOME` picks the `user.name` it reads (#5005).", issue: "#5005", file: "release-floors.ts", modules: ["@intentius/chant/actor","@intentius/chant/release-floors"] },
229
+ { name: "ACTOR_GIT_ENV_FLOOR", version: "0.124.91", gates: "The first chant whose `actorOf({ env, repo })` runs `git config` in `repo` with the `env` it is given rather than the process's, so a job's `GIT_CONFIG_GLOBAL` or `HOME` picks the `user.name` it reads (#5005).", issue: "#5005", file: "release-floors.ts", modules: ["@intentius/chant/actor","@intentius/chant/release-floors"] },
220
230
  { name: "CI_BASE_REF_FLOOR", version: "0.124.89", gates: "The first chant with `@intentius/chant/ci-base` (`ciBaseRef`), the base a CI job measures a change from (the pull request's target branch, else the default branch for a push to another branch), and whose `chant ci check` defaults `--base` to it (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/ci-base","@intentius/chant/release-floors"] },
221
231
  { name: "PLANNED_FILES_FLOOR", version: "0.124.89", gates: "The first chant with `@intentius/chant/planned-files` (`planFile`, `planRemoval`, `writePlannedFiles`, `staleGeneratedFiles`): an init's planned files with their modes, written or removed in one call, and the generated files a product no longer renders, found by their header (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/planned-files","@intentius/chant/release-floors"] },
222
- { name: "PLANNED_BYTES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `planFile` in `@intentius/chant/planned-files` takes bytes (`Uint8Array` or `Buffer`) as well as text: `writePlannedFiles` writes them unchanged and the plan compares them with the file byte for byte (#5006).", issue: "#5006", file: "release-floors.ts", modules: ["@intentius/chant/planned-files","@intentius/chant/release-floors"] },
232
+ { name: "PLANNED_BYTES_FLOOR", version: "0.124.91", gates: "The first chant whose `planFile` in `@intentius/chant/planned-files` takes bytes (`Uint8Array` or `Buffer`) as well as text: `writePlannedFiles` writes them unchanged and the plan compares them with the file byte for byte (#5006).", issue: "#5006", file: "release-floors.ts", modules: ["@intentius/chant/planned-files","@intentius/chant/release-floors"] },
223
233
  { name: "FORGE_CHECK_OWN_JOBS_FLOOR", version: "0.124.89", gates: "The first chant whose `pipelineContract` takes `jobs`, the jobs a product builds from its own config, beside or in place of `pipelines`, so a product's forge check gets the required statuses and `refGateStatus` from chant (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/forge-check","@intentius/chant/forge-check/index","@intentius/chant/release-floors"] },
224
234
  { 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"] },
225
235
  { 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"] },
226
236
  { 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"] },
227
237
  { 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"] },
228
- { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: NEXT_RELEASE, 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"] },
238
+ { 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"] },
229
239
  { 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"] },
230
240
  { name: "RUN_EVENT_FAILURE_FLOOR", version: "0.124.30", gates: "The first chant that writes `failure` on `run-settle` (#4094).", issue: "#4094", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
231
241
  { name: "RUN_EVENT_COMPONENT_SKIP_FLOOR", version: "0.124.29", gates: "The first chant that writes `blocked`, `already-applied` and `blockedBy` on `component-settle` (#4007).", issue: "#4007", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
package/src/lexicon.ts CHANGED
@@ -1231,6 +1231,63 @@ export interface OpWavesPipelineOptions
1231
1231
  * target. On GitLab it posts with `CHANT_FORGE_TOKEN`.
1232
1232
  */
1233
1233
  staleNotes?: { command: string; env: Record<string, string> };
1234
+ /**
1235
+ * A product's job names (#5022, `@intentius/chant/op/op-waves-names`): a
1236
+ * function that gives each job the generator writes (a wave's job, its
1237
+ * deciding, share and job group jobs, a split wave's plan, gate, apply
1238
+ * and record jobs, the policy and evidence jobs, the apply status, stale,
1239
+ * before-merge done and control jobs) the product's name, or undefined
1240
+ * for chant's. Every `needs:`, `if:`, `{job}` and `--from-job` follows
1241
+ * it. A name the forge cannot take, and two jobs that share one, are
1242
+ * refused. Absent: chant's names.
1243
+ */
1244
+ jobNames?: import("./op/op-waves-names").OpWavesJobNames;
1245
+ /** GitLab (#5022): a product's stage names, as {@link jobNames}. Two stages may share one, such as terragucci's `apply`. Absent: chant's. */
1246
+ stageNames?: import("./op/op-waves-names").OpWavesStageNames;
1247
+ /** GitHub and Forgejo (#5022): the outcome, decision, saved plan and check claims artifacts' names, and the pattern a wave job downloads the earlier outcomes with. Absent: chant's. */
1248
+ artifactNames?: import("./op/op-waves-names").OpWavesArtifactNames;
1249
+ /**
1250
+ * GitHub and Forgejo (#5022): the workflow file the jobs go in, such as
1251
+ * `terragucci.yml`: the generator's file, and the one a rest wave's
1252
+ * record job dispatches. GitLab takes `opsFileName`. Absent: `<spec>.yml`.
1253
+ */
1254
+ workflowFile?: string;
1255
+ /**
1256
+ * GitHub and Forgejo (#5034): the file the spec's `resume` workflow goes
1257
+ * in, such as terragucci's `terragucci-resume.yml`. GitLab refuses it
1258
+ * (its resume job is in the pipeline; `jobNames` names it with the role
1259
+ * `resume`). Absent: `<spec>-resume.yml`.
1260
+ */
1261
+ resumeWorkflowFile?: string;
1262
+ /**
1263
+ * The jobs go in a product's own workflow or pipeline beside its other
1264
+ * jobs (#5022). GitHub and Forgejo: an expression (without `${{ }}`)
1265
+ * for the push the waves run on, such as `github.ref ==
1266
+ * format('refs/heads/{0}', github.event.repository.default_branch)`;
1267
+ * each job runs only on such a push, or a before-merge or follow-on
1268
+ * dispatch of its own inputs, and carries its permissions itself. GitLab:
1269
+ * a condition joined with `&&` to every rule of every job. Absent: the
1270
+ * jobs are the workflow's own, as before.
1271
+ */
1272
+ runIf?: string;
1273
+ /**
1274
+ * GitHub and Forgejo (#5022): the names of the `workflow_dispatch`
1275
+ * inputs `pr`, `head`, `digest` (before merge) and `wave`, `commit` (a
1276
+ * rest wave's follow-on), so they never meet the product's own, such as
1277
+ * a re-plan's `pr`. The comment job dispatches them by the same names
1278
+ * (`wavesBeforeMerge.dispatchInputs`). Absent: chant's.
1279
+ */
1280
+ dispatchInputs?: Partial<Record<import("./op/op-waves-names").OpWavesDispatchInput, string>>;
1281
+ /**
1282
+ * The product's own jobs the first wave's jobs need (#5032), such as
1283
+ * terragucci's `check`, so a push that fails the product's check applies
1284
+ * nothing. They go in `needs:` of wave 1's job (its deciding job for a
1285
+ * wide wave, and before merge its plan job). GitHub and Forgejo: each has
1286
+ * to pass, or, in a dispatched run, not have run. GitLab: each, optional,
1287
+ * has to pass (wave 1's policy job needs them too). The jobs must be in
1288
+ * the same workflow or pipeline, so this goes with `runIf`. Absent: none.
1289
+ */
1290
+ firstWaveNeeds?: string[];
1234
1291
  }
1235
1292
 
1236
1293
  /** A run step a product adds to a generated job (#4791): its name, and its shell lines in order. */
@@ -1264,7 +1321,8 @@ export interface OpWaveJobInputs {
1264
1321
  report?: OpWaveRunStep;
1265
1322
  /**
1266
1323
  * Files the job keeps as an artifact whatever its exit. `{job}` in
1267
- * `name` is the job's name, so a wide wave's jobs keep one each. GitHub
1324
+ * `name` is the job's name (#5022: the product's, under `jobNames`), so
1325
+ * a wide wave's jobs keep one each. GitHub
1268
1326
  * and Forgejo: an upload step named `step` after the report. GitLab: the
1269
1327
  * path joins the job's `artifacts:`, which keep the outcome files too,
1270
1328
  * under `name`.
@@ -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
  }
@@ -45,6 +45,8 @@ import type { BeforeMergeDecision, BeforeMergeRecord } from "./before-merge";
45
45
  export interface WavesBeforeMergeJobs {
46
46
  /** GitHub and Forgejo: the waves workflow's file, which the comment job dispatches. */
47
47
  workflow?: string;
48
+ /** GitHub and Forgejo (#5022): the product's names of the dispatch inputs `pr`, `head` and `digest`, as the waves workflow takes them. Default chant's. */
49
+ inputs?: Partial<Record<"pr" | "head" | "digest", string>>;
48
50
  /** The requires the forge is asked (`apply.requires`). Default every one. */
49
51
  requires?: PrApplyRequire[];
50
52
  /** The statuses that must have passed on the head: the product plan's `<product>/plan`, or one per target. */