@intentius/chant 0.124.97 → 0.124.98

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 (223) hide show
  1. package/dist/audit/core.d.ts +29 -0
  2. package/dist/audit/core.d.ts.map +1 -1
  3. package/dist/audit/core.js +48 -11
  4. package/dist/audit/identity.d.ts +27 -0
  5. package/dist/audit/identity.d.ts.map +1 -0
  6. package/dist/audit/identity.js +36 -0
  7. package/dist/audit/report-html.d.ts +3 -1
  8. package/dist/audit/report-html.d.ts.map +1 -1
  9. package/dist/audit/report-html.js +1 -1
  10. package/dist/audit/report-model.d.ts +16 -0
  11. package/dist/audit/report-model.d.ts.map +1 -1
  12. package/dist/audit/report-model.js +5 -1
  13. package/dist/ci-agent.d.ts +17 -0
  14. package/dist/ci-agent.d.ts.map +1 -1
  15. package/dist/ci-agent.js +32 -0
  16. package/dist/ci-comment-allow.d.ts +88 -0
  17. package/dist/ci-comment-allow.d.ts.map +1 -0
  18. package/dist/ci-comment-allow.js +178 -0
  19. package/dist/ci-comment-commands.d.ts +12 -0
  20. package/dist/ci-comment-commands.d.ts.map +1 -1
  21. package/dist/ci-comment-commands.js +22 -0
  22. package/dist/ci-control.d.ts +6 -1
  23. package/dist/ci-control.d.ts.map +1 -1
  24. package/dist/ci-control.js +6 -1
  25. package/dist/ci-product.d.ts +3 -0
  26. package/dist/ci-product.d.ts.map +1 -1
  27. package/dist/ci-product.js +3 -0
  28. package/dist/cli/commands/audit.d.ts +3 -1
  29. package/dist/cli/commands/audit.d.ts.map +1 -1
  30. package/dist/cli/commands/audit.js +23 -6
  31. package/dist/cli/commands/import.d.ts +8 -1
  32. package/dist/cli/commands/import.d.ts.map +1 -1
  33. package/dist/cli/commands/import.js +31 -6
  34. package/dist/cli/handlers/agent.d.ts.map +1 -1
  35. package/dist/cli/handlers/agent.js +12 -2
  36. package/dist/cli/handlers/pr-comment.d.ts +6 -0
  37. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  38. package/dist/cli/handlers/pr-comment.js +12 -0
  39. package/dist/cli/handlers/promote.d.ts.map +1 -1
  40. package/dist/cli/handlers/promote.js +53 -6
  41. package/dist/cli/main.d.ts.map +1 -1
  42. package/dist/cli/main.js +29 -6
  43. package/dist/cli/parse-args.d.ts.map +1 -1
  44. package/dist/cli/parse-args.js +23 -0
  45. package/dist/cli/registry.d.ts +8 -0
  46. package/dist/cli/registry.d.ts.map +1 -1
  47. package/dist/cloud-lister/mask.d.ts +30 -1
  48. package/dist/cloud-lister/mask.d.ts.map +1 -1
  49. package/dist/cloud-lister/mask.js +66 -3
  50. package/dist/components/driver.d.ts +8 -1
  51. package/dist/components/driver.d.ts.map +1 -1
  52. package/dist/components/driver.js +1 -0
  53. package/dist/components/product-pipeline.d.ts +23 -1
  54. package/dist/components/product-pipeline.d.ts.map +1 -1
  55. package/dist/components/product-pipeline.js +40 -7
  56. package/dist/components/product-plan.d.ts +20 -0
  57. package/dist/components/product-plan.d.ts.map +1 -1
  58. package/dist/components/product-plan.js +11 -1
  59. package/dist/control/applied.d.ts +8 -1
  60. package/dist/control/applied.d.ts.map +1 -1
  61. package/dist/control/applied.js +18 -2
  62. package/dist/control/dispatch.d.ts +52 -0
  63. package/dist/control/dispatch.d.ts.map +1 -1
  64. package/dist/control/dispatch.js +140 -4
  65. package/dist/control/train.d.ts +198 -0
  66. package/dist/control/train.d.ts.map +1 -0
  67. package/dist/control/train.js +294 -0
  68. package/dist/deep-observation.js +2 -2
  69. package/dist/floor-table.data.d.ts.map +1 -1
  70. package/dist/floor-table.data.js +11 -0
  71. package/dist/graph-detail.d.ts +9 -0
  72. package/dist/graph-detail.d.ts.map +1 -1
  73. package/dist/graph-detail.js +38 -13
  74. package/dist/graph-refs.d.ts +233 -3
  75. package/dist/graph-refs.d.ts.map +1 -1
  76. package/dist/graph-refs.js +106 -15
  77. package/dist/lint/post-synth.d.ts +22 -0
  78. package/dist/lint/post-synth.d.ts.map +1 -1
  79. package/dist/lint/rules/declarable-naming-convention.d.ts +12 -0
  80. package/dist/lint/rules/declarable-naming-convention.d.ts.map +1 -1
  81. package/dist/lint/rules/declarable-naming-convention.js +38 -8
  82. package/dist/lint/rules/imported-source.d.ts +20 -0
  83. package/dist/lint/rules/imported-source.d.ts.map +1 -0
  84. package/dist/lint/rules/imported-source.js +27 -0
  85. package/dist/lint/rules/no-unused-declarable.d.ts.map +1 -1
  86. package/dist/lint/rules/no-unused-declarable.js +3 -0
  87. package/dist/op/gate.d.ts +2 -0
  88. package/dist/op/gate.d.ts.map +1 -1
  89. package/dist/op/gate.js +8 -1
  90. package/dist/pr-forge-reads.d.ts +17 -0
  91. package/dist/pr-forge-reads.d.ts.map +1 -1
  92. package/dist/pr-forge-reads.js +55 -0
  93. package/dist/release-floors.d.ts +9 -1
  94. package/dist/release-floors.d.ts.map +1 -1
  95. package/dist/release-floors.js +9 -1
  96. package/dist/repo-path.d.ts +29 -0
  97. package/dist/repo-path.d.ts.map +1 -0
  98. package/dist/repo-path.js +81 -0
  99. package/dist/sensitive-key.d.ts +23 -0
  100. package/dist/sensitive-key.d.ts.map +1 -1
  101. package/dist/sensitive-key.js +37 -0
  102. package/dist/terraform/hcl2json.d.ts +7 -0
  103. package/dist/terraform/hcl2json.d.ts.map +1 -1
  104. package/dist/terraform/hcl2json.js +7 -0
  105. package/dist/wave-runtime.mjs +352 -345
  106. package/dist/workspace/catalog-edges.d.ts +147 -0
  107. package/dist/workspace/catalog-edges.d.ts.map +1 -0
  108. package/dist/workspace/catalog-edges.js +461 -0
  109. package/dist/workspace/compose-graph.d.ts +73 -3
  110. package/dist/workspace/compose-graph.d.ts.map +1 -1
  111. package/dist/workspace/declaration.d.ts +2 -0
  112. package/dist/workspace/declaration.d.ts.map +1 -1
  113. package/dist/workspace/declaration.js +1 -0
  114. package/dist/workspace/declaration.schema.json +6 -0
  115. package/dist/workspace/discover.d.ts +134 -0
  116. package/dist/workspace/discover.d.ts.map +1 -0
  117. package/dist/workspace/discover.js +372 -0
  118. package/dist/workspace/graph-cli.d.ts +20 -0
  119. package/dist/workspace/graph-cli.d.ts.map +1 -1
  120. package/dist/workspace/graph-cli.js +178 -20
  121. package/dist/workspace/graph.schema.json +195 -2
  122. package/dist/workspace/release-train.d.ts +214 -3
  123. package/dist/workspace/release-train.d.ts.map +1 -1
  124. package/dist/workspace/release-train.js +552 -16
  125. package/dist/workspace/repo-ref.d.ts +14 -0
  126. package/dist/workspace/repo-ref.d.ts.map +1 -1
  127. package/dist/workspace/repo-ref.js +26 -1
  128. package/dist/workspace/workspace-gates.d.ts +24 -0
  129. package/dist/workspace/workspace-gates.d.ts.map +1 -1
  130. package/dist/workspace/workspace-gates.js +29 -5
  131. package/dist/workspace/workspace-ledger.d.ts +31 -5
  132. package/dist/workspace/workspace-ledger.d.ts.map +1 -1
  133. package/dist/workspace/workspace-ledger.js +2 -1
  134. package/dist/workspace/workspace-run.d.ts +14 -0
  135. package/dist/workspace/workspace-run.d.ts.map +1 -1
  136. package/dist/workspace/workspace-run.js +2 -2
  137. package/dist/yaml.d.ts.map +1 -1
  138. package/dist/yaml.js +33 -8
  139. package/package.json +1 -1
  140. package/src/audit/core.test.ts +64 -1
  141. package/src/audit/core.ts +75 -10
  142. package/src/audit/identity.test.ts +31 -0
  143. package/src/audit/identity.ts +43 -0
  144. package/src/audit/report-html.ts +4 -2
  145. package/src/audit/report-model.ts +21 -1
  146. package/src/ci-agent.test.ts +32 -0
  147. package/src/ci-agent.ts +42 -0
  148. package/src/ci-comment-allow.test.ts +380 -0
  149. package/src/ci-comment-allow.ts +184 -0
  150. package/src/ci-comment-commands.ts +25 -0
  151. package/src/ci-control.ts +42 -0
  152. package/src/ci-product.ts +3 -0
  153. package/src/cli/commands/audit-parser-notice.test.ts +74 -0
  154. package/src/cli/commands/audit.test.ts +12 -0
  155. package/src/cli/commands/audit.ts +25 -7
  156. package/src/cli/commands/import-layout.test.ts +2 -1
  157. package/src/cli/commands/import.ts +29 -6
  158. package/src/cli/handlers/agent.ts +13 -2
  159. package/src/cli/handlers/pr-comment.ts +12 -0
  160. package/src/cli/handlers/promote.test.ts +68 -0
  161. package/src/cli/handlers/promote.ts +52 -6
  162. package/src/cli/main.test.ts +5 -0
  163. package/src/cli/main.ts +29 -6
  164. package/src/cli/parse-args.ts +18 -0
  165. package/src/cli/registry.ts +8 -0
  166. package/src/cloud-lister/kubernetes.k3d.e2e.test.ts +104 -0
  167. package/src/cloud-lister/mask-references.test.ts +132 -0
  168. package/src/cloud-lister/mask.ts +68 -3
  169. package/src/components/driver.ts +9 -1
  170. package/src/components/product-pipeline.ts +57 -7
  171. package/src/components/product-plan.ts +27 -2
  172. package/src/control/applied.ts +33 -3
  173. package/src/control/dispatch.ts +156 -5
  174. package/src/control/train.test.ts +215 -0
  175. package/src/control/train.ts +413 -0
  176. package/src/deep-observation.ts +2 -2
  177. package/src/floor-table.data.ts +6 -0
  178. package/src/graph-detail.ts +37 -12
  179. package/src/graph-refs.test.ts +45 -1
  180. package/src/graph-refs.ts +321 -14
  181. package/src/lint/post-synth.ts +20 -0
  182. package/src/lint/rules/declarable-naming-convention.test.ts +35 -1
  183. package/src/lint/rules/declarable-naming-convention.ts +35 -8
  184. package/src/lint/rules/imported-source.test.ts +22 -0
  185. package/src/lint/rules/imported-source.ts +31 -0
  186. package/src/lint/rules/no-unused-declarable.test.ts +16 -0
  187. package/src/lint/rules/no-unused-declarable.ts +7 -0
  188. package/src/op/gate.ts +10 -2
  189. package/src/pr-forge-reads.ts +62 -0
  190. package/src/release-floors.ts +13 -1
  191. package/src/repo-path.test.ts +72 -0
  192. package/src/repo-path.ts +103 -0
  193. package/src/sensitive-key.ts +38 -0
  194. package/src/terraform/hcl2json.ts +8 -0
  195. package/src/workspace/application-set.e2e.test.ts +405 -0
  196. package/src/workspace/catalog-edges.ts +507 -0
  197. package/src/workspace/ci-green-workflow.test.ts +2 -2
  198. package/src/workspace/cluster-join.e2e.test.ts +150 -0
  199. package/src/workspace/compose-graph.ts +74 -5
  200. package/src/workspace/declaration.schema.json +6 -0
  201. package/src/workspace/declaration.ts +3 -0
  202. package/src/workspace/discover.e2e.test.ts +122 -0
  203. package/src/workspace/discover.test.ts +225 -0
  204. package/src/workspace/discover.ts +406 -0
  205. package/src/workspace/external-secret-catalog.e2e.test.ts +98 -0
  206. package/src/workspace/external-secret-catalog.test.ts +142 -0
  207. package/src/workspace/graph-cli.ts +207 -21
  208. package/src/workspace/graph-contract.test.ts +92 -0
  209. package/src/workspace/graph.schema.json +195 -2
  210. package/src/workspace/helm-references.e2e.test.ts +135 -0
  211. package/src/workspace/identity-annotation-catalog.e2e.test.ts +91 -0
  212. package/src/workspace/identity-annotation-catalog.test.ts +139 -0
  213. package/src/workspace/release-train-repos.test.ts +304 -0
  214. package/src/workspace/release-train.test.ts +296 -0
  215. package/src/workspace/release-train.ts +631 -16
  216. package/src/workspace/repo-ref.ts +26 -1
  217. package/src/workspace/runs-on.test.ts +45 -0
  218. package/src/workspace/workspace-gates.ts +48 -5
  219. package/src/workspace/workspace-ledger.ts +28 -5
  220. package/src/workspace/workspace-run.test.ts +1 -1
  221. package/src/workspace/workspace-run.ts +2 -2
  222. package/src/yaml.test.ts +96 -8
  223. package/src/yaml.ts +36 -8
@@ -47,7 +47,8 @@ import { planEvidenceOf, productPlanContext, productPlanJobs, productPlanReachLo
47
47
  import { gitlabOpenEvidenceDir, type PipelineEvidence } from "../ci-evidence-jobs";
48
48
  import { prCheckJob, prRefGateJob, type PrCheckJob, type PrRefGateJob } from "./pr-checks";
49
49
  import { COMMENT_JOBS_ENV, PR_COMMENT_JOB, type CommentJobs } from "../ci-comment-commands";
50
- import { GITHUB_JOB_TOKEN } from "../ci-jobs";
50
+ import { COMMENT_ALLOW_ENV, COMMENT_ALLOW_TOKEN_ENV, commentAllowCovers, commentAllowList, commentAllowProblems, type CommentAllow } from "../ci-comment-allow";
51
+ import { GITHUB_JOB_TOKEN, githubSecret } from "../ci-jobs";
51
52
  import type { OpWavesBeforeMerge } from "../op/before-merge";
52
53
  import { defaultPipelineFiles, type WavesBeforeMergeJobs } from "../op/before-merge-decide";
53
54
  import { opWavesDispatchInputs, opWavesInputsRenamed, opWavesNamer, opWavesWorkflowFile, type OpWavesJobNames } from "../op/op-waves-names";
@@ -165,6 +166,20 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
165
166
  * whose comment job is `commentJob`.
166
167
  */
167
168
  noteCommandsJob?: ProductNoteCommandsJobOptions;
169
+ /**
170
+ * Limit `plan`, `apply`, `lock`, `unlock` and `agent` to logins and teams
171
+ * on GitHub and Forgejo (INTENTIUS/terragucci#1461, `../ci-comment-allow.ts`).
172
+ * The map is written into the workflow as `CHANT_COMMENT_ALLOW` in the
173
+ * comment job, the product plan's re-plan decision and the agent's jobs, so
174
+ * it is read from the default branch's copy of the workflow and a pull
175
+ * request cannot add its author. It limits the commands those jobs run:
176
+ * the comment job replies to a commenter the list leaves out, the re-plan
177
+ * replies when it has `replan.reply` and else stays silent, and the agent's
178
+ * push job answers its refusal. Refused on GitLab, and when a list covers a command that
179
+ * a job without the check answers: the apply before merge
180
+ * (`applyBeforeMerge`) and chant's comment lock jobs (`locks: "plan"`).
181
+ */
182
+ commentAllow?: ProductCommentAllow;
168
183
  /**
169
184
  * The waves' job names (#5027), the Op waves generators' `jobNames`
170
185
  * (#5022): `waves.pipeline` carries them to the generator, `waves.jobs`
@@ -229,6 +244,14 @@ export interface ProductWavesBeforeMerge {
229
244
  dispatchInputs?: Partial<Record<"pr" | "head" | "digest", string>>;
230
245
  }
231
246
 
247
+ /** The comment limits the pipeline writes into its jobs (INTENTIUS/terragucci#1461): {@link ProductPipelineOptions.commentAllow}, with the secret team membership is read with. */
248
+ export interface ProductCommentAllow {
249
+ /** Command to logins and `team:<org>/<team>` entries, and `default` for the five commands it does not name. */
250
+ allow: CommentAllow;
251
+ /** The secret that holds a token that can read the teams' members (GitHub: `read:org`, or Members: read; Forgejo: `read:organization`). Default: the job's own token, which GitHub's cannot do. */
252
+ tokenSecret?: string;
253
+ }
254
+
232
255
  /** {@link ProductPipelineOptions.noteCommandsJob} (#5038). */
233
256
  export interface ProductNoteCommandsJobOptions {
234
257
  /** The job's name, such as `comments`. Default `note-commands`. */
@@ -468,7 +491,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
468
491
  // #4946: the comment job answers every command but a commit word (the commit job's) with a reply, so the words may name any.
469
492
  const answered: CiProductCommand[] = options.commentJob ? [...new Set<CiProductCommand>([...jobs, ...CI_PRODUCT_COMMANDS.filter((c) => c !== "commit")])] : jobs;
470
493
  const words = assertProductWords({ ...options.words, applyMode }, { jobs: answered });
471
- const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, wavesBeforeMerge, applyStatus: _applyStatus, wavesJobNames, noteCommandsJob, ...loop } = options;
494
+ const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, commentAllow, wavesBeforeMerge, applyStatus: _applyStatus, wavesJobNames, noteCommandsJob, ...loop } = options;
495
+ if (commentAllow) commentAllowRefusals(forge, commentAllow, options);
472
496
  if (options.applyStatus && !given && !componentWaves) throw new Error("applyStatus posts the waves' apply statuses, and there are none: give waves (or componentWaves)");
473
497
  const { respond } = options;
474
498
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
@@ -495,7 +519,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
495
519
  comments,
496
520
  ...(options.applyBeforeMerge ? { applyBeforeMerge: apply! } : {}),
497
521
  // #4799: the product's plan verb, a plan job and a note job per target.
498
- ...(productPlan ? { productPlan: productPlanJobs(forge, env, { ...prLoop, plan: productPlan }, words, evidence) } : {}),
522
+ ...(productPlan ? { productPlan: productPlanJobs(forge, env, { ...prLoop, plan: withReplanAllow(productPlan, commentAllow) }, words, evidence) } : {}),
499
523
  };
500
524
  // #4935: the check job runs the change's code on the plan runner; the signing and the status run on the default one.
501
525
  // #4964: with the product's own services, variables, lines and report directory.
@@ -532,7 +556,10 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
532
556
  // #4616: the agent answers its comment from a workflow of its own, generated from this spec.
533
557
  const agentComment = options.agent ? comments.agent : undefined;
534
558
  if (options.agent && agentComment) {
535
- const spec = productAgentSpec(words, agentComment, options.agent === true ? {} : options.agent);
559
+ const agentOptions = options.agent === true ? {} : options.agent;
560
+ // INTENTIUS/terragucci#1461: the pipeline's list for the agent command, which the agent's prepare step checks.
561
+ const allowed = commentAllow && commentAllowList(commentAllow.allow, "agent") ? { commentAllow: commentAllow.allow, ...(commentAllow.tokenSecret ? { commentAllowTokenEnv: commentAllow.tokenSecret } : {}) } : {};
562
+ const spec = productAgentSpec(words, agentComment, { ...agentOptions, ...allowed });
536
563
  out.agent = { comment: agentComment, name: spec.name, spec };
537
564
  }
538
565
  // #4722: each comment commit job answers its own word from a workflow of its own.
@@ -624,7 +651,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
624
651
  // #5027: a re-run looks for the waves' jobs by the product's names; without them, by chant's pattern.
625
652
  ...(namedWaveJobs && wavesJobNames ? { applyJobs: productApplyJobs(named!, waveJobs!, namedWaveJobs, forge, wavesJobNames, wavesBeforeMerge !== undefined) } : {}),
626
653
  };
627
- const comment = productCommentJob(forge, words, commentJobs, typeof options.commentJob === "object" ? options.commentJob.jobName : undefined);
654
+ const comment = productCommentJob(forge, words, commentJobs, typeof options.commentJob === "object" ? options.commentJob.jobName : undefined, commentAllow);
628
655
  // #4984: the decision before merge locks what the reach line prints, at stage apply.
629
656
  if (bmJobs && productPlan?.reach) comment.env = { ...comment.env, [LOCK_REACH_ENV]: productPlan.reach.command };
630
657
  out.comment = { ...comment, ...defaultRunner };
@@ -799,19 +826,42 @@ function noteCommandsNames(forge: ForgeKind, given: ProductNoteCommandsJobOption
799
826
  * note. `jobName` is the product's name for the job (#5027), default
800
827
  * {@link PR_COMMENT_JOB}.
801
828
  */
802
- export function productCommentJob(forge: ForgeKind, words: CiProductWords, jobs: CommentJobs, jobName: string = PR_COMMENT_JOB): ProductCommentJob {
829
+ export function productCommentJob(forge: ForgeKind, words: CiProductWords, jobs: CommentJobs, jobName: string = PR_COMMENT_JOB, allow?: ProductCommentAllow): ProductCommentJob {
803
830
  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");
804
831
  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`);
805
832
  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 _`);
806
833
  return {
807
834
  jobName,
808
835
  command: withProductBin(`chant components pr-comment --forge ${forge}`, words.bin),
809
- env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN, [COMMENT_JOBS_ENV]: JSON.stringify(jobs) },
836
+ env: {
837
+ GITHUB_TOKEN: GITHUB_JOB_TOKEN,
838
+ [COMMENT_JOBS_ENV]: JSON.stringify(jobs),
839
+ // INTENTIUS/terragucci#1461: the comment limits, and the secret teams are read with.
840
+ ...(allow ? { [COMMENT_ALLOW_ENV]: JSON.stringify(allow.allow), ...(allow.tokenSecret ? { [COMMENT_ALLOW_TOKEN_ENV]: githubSecret(allow.tokenSecret) } : {}) } : {}),
841
+ },
810
842
  prefixes: [`/${words.product}`, ...words.aliases.map((a) => a.from)],
811
843
  jobs,
812
844
  };
813
845
  }
814
846
 
847
+ /** The product plan with the comment limits in its re-plan (INTENTIUS/terragucci#1461), when the plan comment has a list. */
848
+ function withReplanAllow(plan: ProductPlanOptions, allow: ProductCommentAllow | undefined): ProductPlanOptions {
849
+ if (!allow || !plan.replan || !commentAllowList(allow.allow, "plan")) return plan;
850
+ const replan = typeof plan.replan === "object" ? plan.replan : {};
851
+ return { ...plan, replan: { ...replan, commentAllow: allow.allow, ...(allow.tokenSecret ? { commentAllowTokenSecret: allow.tokenSecret } : {}) } };
852
+ }
853
+
854
+ /** What `commentAllow` is refused for: a forge it does not cover, a bad map, a secret name, and a command a job without the check answers. */
855
+ function commentAllowRefusals(forge: ForgeKind, given: ProductCommentAllow, options: Pick<ProductPipelineOptions, "applyBeforeMerge" | "locks">): void {
856
+ if (forge === "gitlab") throw new Error("commentAllow limits the comment jobs of GitHub and Forgejo; GitLab's note poll is the product's own to limit");
857
+ const problems = commentAllowProblems(given.allow, "commentAllow.allow");
858
+ if (given.tokenSecret !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(given.tokenSecret)) problems.push("commentAllow.tokenSecret is a secret's name");
859
+ if (problems.length > 0) throw new Error(problems.join("; "));
860
+ const covered = commentAllowCovers(given.allow);
861
+ if (covered.includes("apply") && options.applyBeforeMerge) throw new Error("commentAllow lists who may apply, and the apply before merge (applyBeforeMerge) checks write access alone; use wavesBeforeMerge, whose apply the comment job decides");
862
+ if ((covered.includes("lock") || covered.includes("unlock")) && options.locks === "plan") throw new Error("commentAllow lists who may lock or unlock, and the comment lock jobs of locks: \"plan\" check write access alone; name the commands that are not theirs (plan, apply, agent), or use wavesBeforeMerge with the reach line, whose lock the comment job answers");
863
+ }
864
+
815
865
  /** A shell line with the product's bin in place of `chant`, for a product's own jobs beside these. */
816
866
  export function productCommand(words: CiProductWords, line: string): string {
817
867
  return withProductBin(line, words.bin);
@@ -50,6 +50,7 @@ import { PLAN_WATCHES_ENV, scheduledWatchProblem, type ScheduledWatch } from "..
50
50
  import { PLAN_RUN_OP, PLAN_RUN_RECORD_FILE } from "../pr-plan-record";
51
51
  import { idTokenVar, tradedClouds, type CloudTradeSpec } from "../ci-identity";
52
52
  import { prNoteMarker } from "../pr-loop";
53
+ import { COMMENT_ALLOW_GATE_JS, commentAllowList, type CommentAllow } from "../ci-comment-allow";
53
54
  import { PRODUCT_MARKER_NAME } from "../pr-plan-note";
54
55
  import { gitlabJobArtifacts, type PrCheckArtifacts } from "./pr-checks";
55
56
 
@@ -118,6 +119,19 @@ export interface ProductPlanReplanOptions {
118
119
  * (`pr-post --not-affected <argument>`).
119
120
  */
120
121
  notAffected?: boolean;
122
+ /**
123
+ * Limit the plan comment to logins and teams (INTENTIUS/terragucci#1461,
124
+ * `../ci-comment-allow.ts`), on GitHub and Forgejo: the decision step makes
125
+ * the check before anything is checked out, from the list the generator
126
+ * wrote into the workflow on the default branch. A commenter the list
127
+ * leaves out plans nothing; the comment job replies, or the re-plan itself
128
+ * with `reply`. A dispatch asks no
129
+ * list, as it asks no permission. `productPipelineJobs` sets it from its
130
+ * `commentAllow`.
131
+ */
132
+ commentAllow?: CommentAllow;
133
+ /** The secret that holds the token team membership is read with, for `commentAllow`. Default: the job's token. */
134
+ commentAllowTokenSecret?: string;
121
135
  }
122
136
 
123
137
  /**
@@ -162,6 +176,8 @@ export interface ProductPlanReplanJob {
162
176
  reply?: { prefix: string; others: string[] };
163
177
  /** With `notAffected` (#4963): the note job's command carries `--not-affected`, and reads the argument as {@link PLAN_ARGUMENT_ENV}. */
164
178
  notAffected?: true;
179
+ /** With `commentAllow`, GitHub and Forgejo: the list the decision step checks the commenter against, and the secret the team read uses. */
180
+ allow?: { list: CommentAllow; tokenSecret?: string };
165
181
  }
166
182
 
167
183
  /**
@@ -761,6 +777,7 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
761
777
  ...(github && dispatchArg !== undefined ? { dispatch: { argument: dispatchArg } } : {}),
762
778
  ...(replies ? { reply: { prefix: `/${words.product}`, others } } : {}),
763
779
  ...(replanOpts.notAffected ? { notAffected: true as const } : {}),
780
+ ...(github && replanOpts.commentAllow && commentAllowList(replanOpts.commentAllow, "plan") ? { allow: { list: replanOpts.commentAllow, ...(replanOpts.commentAllowTokenSecret ? { tokenSecret: replanOpts.commentAllowTokenSecret } : {}) } } : {}),
764
781
  }
765
782
  : undefined;
766
783
  const replan = replan0 && plan.record ? { ...replan0, post: { ...replan0.post, command: `${replan0.post.command} --record-run ${replan0.jobName}` } } : replan0;
@@ -954,8 +971,13 @@ export const REPLAN_DECIDE_JS = replanDecideJs();
954
971
  * get a reply comment with the reason, once the commenter's permission
955
972
  * is known (Forgejo). A dispatch's reason goes to the log alone.
956
973
  */
957
- export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {}): string {
958
- const { dispatch = false, reply = false } = opts;
974
+ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean; allow?: boolean } = {}): string {
975
+ const { dispatch = false, reply = false, allow = false } = opts;
976
+ // INTENTIUS/terragucci#1461: the pipeline's list for the plan comment, after the permission check; a dispatch asks none.
977
+ // With `reply` the re-plan speaks for itself (the comment job cannot be there beside it); without, it says nothing and the comment job replies.
978
+ const allowLine = allow
979
+ ? `${dispatch ? "if(!dispatch)" : ""}{const asker=e.comment&&e.comment.user&&e.comment.user.login;if(!asker){say("the comment has no author, so nothing is planned again");return}const no=await commentAllowRefusal(asker,"plan");if(no){${reply ? 'await post(no+", so nothing is planned again")' : 'say(no+", so nothing is planned again")'};return}}`
980
+ : undefined;
959
981
  const replyLine = reply
960
982
  ? [
961
983
  // The reply, as the product: on a dispatch the log alone.
@@ -997,6 +1019,7 @@ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {
997
1019
  : 'const n=e.issue&&e.issue.number;if(!Number.isInteger(n)||!(e.issue.pull_request||e.is_pull)){say("the comment is not on a pull request");process.exit(0)}',
998
1020
  'const api=String(process.env.GITHUB_API_URL||"").replace(/\\/+$/,""),repo=process.env.GITHUB_REPOSITORY;',
999
1021
  'const get=async(p)=>{const r=await fetch(api+"/repos/"+repo+p,{headers:{authorization:"token "+process.env.CHANT_REPLAN_TOKEN,accept:"application/json"}});if(!r.ok)throw new Error(p+" answered "+r.status);return r.json()};',
1022
+ ...(allow ? [COMMENT_ALLOW_GATE_JS] : []),
1000
1023
  ...replyLine,
1001
1024
  "(async()=>{",
1002
1025
  ...(reply
@@ -1004,6 +1027,7 @@ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {
1004
1027
  // Who asked comes first: a commenter who cannot write gets no reply.
1005
1028
  `if(process.env.CHANT_REPLAN_PERMISSION${dispatch ? "&&!dispatch" : ""}){const who=e.comment&&e.comment.user&&e.comment.user.login;const p=who?await get("/collaborators/"+encodeURIComponent(who)+"/permission"):{};`,
1006
1029
  'if(!["owner","admin","maintain","write"].includes(p.permission)){say((who||"the commenter")+" cannot write to "+repo+", so nothing is planned again");return}}',
1030
+ ...(allowLine ? [`if(!refusal)${allowLine}`] : []),
1007
1031
  "if(refusal){await post(refusal);return}",
1008
1032
  'const pr=await get("/pulls/"+n);',
1009
1033
  'if(pr.state!=="open"){say("pull request "+n+" is not open, so it is not planned again");return}',
@@ -1017,6 +1041,7 @@ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {
1017
1041
  'if(!same&&process.env.CHANT_REPLAN_FORKS==="skip"){say("pull request "+n+" is from a fork, and its code never runs with this repository\\u0027s credentials");return}',
1018
1042
  `if(process.env.CHANT_REPLAN_PERMISSION${dispatch ? "&&!dispatch" : ""}){const who=e.comment&&e.comment.user&&e.comment.user.login;const p=who?await get("/collaborators/"+encodeURIComponent(who)+"/permission"):{};`,
1019
1043
  'if(!["owner","admin","maintain","write"].includes(p.permission)){say((who||"the commenter")+" cannot write to "+repo+", so nothing is planned again");return}}',
1044
+ ...(allowLine ? [allowLine] : []),
1020
1045
  ]),
1021
1046
  'const sha=/^[0-9a-f]{40}$/;if(!sha.test(String(pr.head&&pr.head.sha))||!sha.test(String(pr.base&&pr.base.sha)))throw new Error("the pull request names no head or base commit");',
1022
1047
  'out("go","1");out("pr",String(n));out("head",pr.head.sha);out("base",pr.base.sha);out("argument",arg);',
@@ -18,7 +18,18 @@
18
18
  import { createHash } from "node:crypto";
19
19
  import { passesThrough, type WaveMemberOutcome } from "../wave-blocked";
20
20
  import { CONTROL_LEDGER_DIR, type ControlLedgerPort } from "./records";
21
- import { CONTROL_APPLY_OUTCOMES, CONTROL_OUTCOME_VAR, CONTROL_RUNS_DEPENDENTS, type ControlApplyOutcome } from "./dispatch";
21
+ import {
22
+ CONTROL_APPLY_OUTCOMES,
23
+ CONTROL_ENV_VAR,
24
+ CONTROL_OUTCOME_VAR,
25
+ CONTROL_RELEASE_VAR,
26
+ CONTROL_RUN_VAR,
27
+ CONTROL_RUNS_DEPENDENTS,
28
+ CONTROL_TRAIN_VAR,
29
+ controlTrainProblems,
30
+ type ControlApplyOutcome,
31
+ type ControlTrainAnswer,
32
+ } from "./dispatch";
22
33
 
23
34
  export { CONTROL_APPLY_OUTCOMES, CONTROL_OUTCOME_VAR, CONTROL_RUNS_DEPENDENTS, type ControlApplyOutcome };
24
35
 
@@ -69,6 +80,12 @@ export interface ControlAppliedRecord {
69
80
  outcome: ControlApplyOutcome;
70
81
  /** When the control repo took the dispatch, ISO 8601. */
71
82
  at: string;
83
+ /**
84
+ * The release train the apply answers (#5119): the train, the control
85
+ * repo's run of its promote, the environment and the release the member
86
+ * ran. Absent on every other dispatch; a record without it hashes as it did before.
87
+ */
88
+ train?: ControlTrainAnswer;
72
89
  /** sha256 over the canonical JSON of every other field. */
73
90
  digest: string;
74
91
  }
@@ -93,6 +110,10 @@ export function controlAppliedProblems(v: unknown): string[] {
93
110
  if (!(typeof r.sha === "string" && SHA.test(r.sha))) out.push("sha must be a commit sha");
94
111
  if (!CONTROL_APPLY_OUTCOMES.includes(r.outcome as ControlApplyOutcome)) out.push(`outcome must be one of ${CONTROL_APPLY_OUTCOMES.join(", ")}`);
95
112
  if (!(typeof r.at === "string" && !Number.isNaN(Date.parse(r.at)))) out.push("at must be a time");
113
+ if (r.train !== undefined) {
114
+ if (typeof r.train !== "object" || r.train === null || Array.isArray(r.train)) out.push("train must be a train's answer");
115
+ else out.push(...controlTrainProblems(r.train as Record<string, unknown>).map((p) => `train.${p}`));
116
+ }
96
117
  if (typeof r.digest !== "string") out.push("digest is missing");
97
118
  else if (out.length === 0) {
98
119
  const { digest: _d, ...rest } = r as unknown as ControlAppliedRecord;
@@ -148,7 +169,7 @@ export function gitControlAppliedLedger(opts: { cwd?: string } = {}): ControlLed
148
169
  /** Appends one record of a dispatch the control repo took. Does not push. */
149
170
  export async function recordControlApplied(
150
171
  port: ControlLedgerPort,
151
- d: { member: string; op: string; sha: string; outcome: ControlApplyOutcome },
172
+ d: { member: string; op: string; sha: string; outcome: ControlApplyOutcome; train?: ControlTrainAnswer },
152
173
  opts: { now?: () => Date } = {},
153
174
  ): Promise<{ record: ControlAppliedRecord; commit: string }> {
154
175
  const fields: Omit<ControlAppliedRecord, "digest"> = {
@@ -159,6 +180,7 @@ export async function recordControlApplied(
159
180
  sha: d.sha,
160
181
  outcome: d.outcome,
161
182
  at: (opts.now ?? (() => new Date()))().toISOString(),
183
+ ...(d.train ? { train: { train: d.train.train, run: d.train.run, env: d.train.env, releaseDigest: d.train.releaseDigest } } : {}),
162
184
  };
163
185
  const record: ControlAppliedRecord = { ...fields, digest: digestOf(fields) };
164
186
  const problems = controlAppliedProblems(record);
@@ -184,7 +206,15 @@ export async function recordControlAppliedFromEnv(
184
206
  if (!outcome) return { skipped: "the dispatch carries no outcome" };
185
207
  if (!CONTROL_APPLY_OUTCOMES.includes(outcome as ControlApplyOutcome)) return { skipped: `the dispatch's outcome "${outcome}" is not one chant knows` };
186
208
  if (!SHA.test(sha)) return { skipped: "the dispatch names no commit sha" };
187
- const { record } = await recordControlApplied(gitControlAppliedLedger({ cwd: opts.cwd }), { member, op, sha, outcome: outcome as ControlApplyOutcome }, opts.now ? { now: opts.now } : {});
209
+ // #5119: a train's answer is kept with the train it answers, or not at all.
210
+ let train: ControlTrainAnswer | undefined;
211
+ if (env[CONTROL_TRAIN_VAR]) {
212
+ const t = { train: env[CONTROL_TRAIN_VAR], run: env[CONTROL_RUN_VAR] ?? "", env: env[CONTROL_ENV_VAR] ?? "", releaseDigest: env[CONTROL_RELEASE_VAR] ?? "" };
213
+ const problems = controlTrainProblems(t);
214
+ if (problems.length > 0) return { skipped: `the dispatch's train fields are not usable: ${problems.join(", ")}` };
215
+ train = t as ControlTrainAnswer;
216
+ }
217
+ const { record } = await recordControlApplied(gitControlAppliedLedger({ cwd: opts.cwd }), { member, op, sha, outcome: outcome as ControlApplyOutcome, ...(train ? { train } : {}) }, opts.now ? { now: opts.now } : {});
188
218
  const { pushLifecycleReport } = await import("../lifecycle/git");
189
219
  const pushed = await pushLifecycleReport({ ...(opts.cwd ? { cwd: opts.cwd } : {}) });
190
220
  return { recorded: record, ...(pushed.pushWarning ? { pushWarning: pushed.pushWarning } : {}) };
@@ -65,6 +65,42 @@ export const CONTROL_SHA_VAR = "CHANT_CONTROL_SHA";
65
65
  /** The variable the apply outcome travels in (#4617): the member's dispatch step reads it, a GitLab trigger sets it, the control repo's step reads it. */
66
66
  export const CONTROL_OUTCOME_VAR = "CHANT_CONTROL_OUTCOME";
67
67
 
68
+ /**
69
+ * The variables a train's answer travels in (#5119): the release train and
70
+ * the control repo's run of its promote, the environment, and the release
71
+ * the member ran. A member's train job sets them; its dispatch step reads
72
+ * them; the control repo's step reads them back.
73
+ */
74
+ export const CONTROL_TRAIN_VAR = "CHANT_CONTROL_TRAIN";
75
+ export const CONTROL_RUN_VAR = "CHANT_CONTROL_RUN";
76
+ export const CONTROL_ENV_VAR = "CHANT_CONTROL_ENV";
77
+ export const CONTROL_RELEASE_VAR = "CHANT_CONTROL_RELEASE";
78
+
79
+ /** A release train's id, as `chant workspace train` writes it. */
80
+ export const CONTROL_TRAIN_ID = /^train-[A-Za-z0-9-]{1,64}$/;
81
+ /** A workspace run's id, as `chant workspace train promote` writes it. */
82
+ export const CONTROL_RUN_ID = /^ws-[A-Za-z0-9-]{1,64}$/;
83
+ /** A release digest: `<scheme>:<64 hex digits>`, such as `jcs1-sha256:...`. */
84
+ export const CONTROL_RELEASE_DIGEST = /^[a-z0-9]+(-[a-z0-9]+)*:[0-9a-f]{64}$/;
85
+
86
+ /** What a member's answer to a train's dispatch carries besides the apply (#5119). */
87
+ export interface ControlTrainAnswer {
88
+ train: string;
89
+ run: string;
90
+ env: string;
91
+ releaseDigest: string;
92
+ }
93
+
94
+ /** The problems with a train's answer, or [] when it is usable. */
95
+ export function controlTrainProblems(t: Partial<Record<keyof ControlTrainAnswer, unknown>>): string[] {
96
+ const out: string[] = [];
97
+ if (!(typeof t.train === "string" && CONTROL_TRAIN_ID.test(t.train))) out.push("train must be a release train's id");
98
+ if (!(typeof t.run === "string" && CONTROL_RUN_ID.test(t.run))) out.push("run must be a workspace run's id");
99
+ if (!(typeof t.env === "string" && CONTROL_NAME.test(t.env))) out.push("env must be an environment's name");
100
+ if (!(typeof t.releaseDigest === "string" && CONTROL_RELEASE_DIGEST.test(t.releaseDigest))) out.push("releaseDigest must be a release digest");
101
+ return out;
102
+ }
103
+
68
104
  /**
69
105
  * What a member's op waves did, as its dispatch says it (#4617, `applyOutcomeOf` in ./applied.ts):
70
106
  * - `applied`: at least one run applied, and every other run applied or had nothing to apply.
@@ -247,6 +283,8 @@ export interface ControlDispatch {
247
283
  sha: string;
248
284
  /** What the member's op waves did (#4617). Absent from the pull request loop's dispatch, which is sent on green only. */
249
285
  outcome?: ControlApplyOutcome;
286
+ /** The train the apply answers (#5119), when the member ran for one. */
287
+ train?: ControlTrainAnswer;
250
288
  }
251
289
 
252
290
  /** Where the token goes in a {@link ControlDispatchRequest}. */
@@ -270,6 +308,16 @@ function checkDispatch(d: ControlDispatch): void {
270
308
  if (!CONTROL_NAME.test(d.op)) throw new ControlConfigError(`the dispatch's op "${d.op}" is not an Op name`);
271
309
  if (!SHA.test(d.sha)) throw new ControlConfigError(`the dispatch names no commit sha ("${d.sha}")`);
272
310
  if (d.outcome !== undefined && !CONTROL_APPLY_OUTCOMES.includes(d.outcome)) throw new ControlConfigError(`the dispatch's outcome "${d.outcome}" is not one of ${CONTROL_APPLY_OUTCOMES.join(", ")}`);
311
+ if (d.train !== undefined) {
312
+ if (d.outcome === undefined) throw new ControlConfigError("a train's answer carries the outcome of the member's run");
313
+ const problems = controlTrainProblems(d.train);
314
+ if (problems.length > 0) throw new ControlConfigError(`the dispatch's train fields: ${problems.join(", ")}`);
315
+ }
316
+ }
317
+
318
+ /** A train's answer as payload fields (#5119): the same names in a GitHub `client_payload` and Forgejo `inputs`. */
319
+ function trainFields(d: ControlDispatch): Record<string, string> {
320
+ return d.train ? { train: d.train.train, run: d.train.run, env: d.train.env, release: d.train.releaseDigest } : {};
273
321
  }
274
322
 
275
323
  /**
@@ -286,7 +334,7 @@ export function controlDispatchRequest(target: ControlTarget, d: ControlDispatch
286
334
  url: `${target.apiBase}/repos/${target.path}/dispatches`,
287
335
  method: "POST",
288
336
  headers: { Accept: "application/vnd.github+json", "Content-Type": "application/json" },
289
- body: { json: { event_type: controlDispatchEvent(wordsIn), client_payload: { member: d.member, op: d.op, sha: d.sha, ...(d.outcome ? { outcome: d.outcome } : {}) } } },
337
+ body: { json: { event_type: controlDispatchEvent(wordsIn), client_payload: { member: d.member, op: d.op, sha: d.sha, ...(d.outcome ? { outcome: d.outcome } : {}), ...trainFields(d) } } },
290
338
  token: { in: "header", name: "Authorization", scheme: "Bearer" },
291
339
  };
292
340
  }
@@ -302,6 +350,14 @@ export function controlDispatchRequest(target: ControlTarget, d: ControlDispatch
302
350
  [`variables[${CONTROL_OP_VAR}]`, d.op],
303
351
  [`variables[${CONTROL_SHA_VAR}]`, d.sha],
304
352
  ...(d.outcome ? ([[`variables[${CONTROL_OUTCOME_VAR}]`, d.outcome]] as Array<[string, string]>) : []),
353
+ ...(d.train
354
+ ? ([
355
+ [`variables[${CONTROL_TRAIN_VAR}]`, d.train.train],
356
+ [`variables[${CONTROL_RUN_VAR}]`, d.train.run],
357
+ [`variables[${CONTROL_ENV_VAR}]`, d.train.env],
358
+ [`variables[${CONTROL_RELEASE_VAR}]`, d.train.releaseDigest],
359
+ ] as Array<[string, string]>)
360
+ : []),
305
361
  ],
306
362
  },
307
363
  token: { in: "form", field: "token" },
@@ -311,7 +367,7 @@ export function controlDispatchRequest(target: ControlTarget, d: ControlDispatch
311
367
  url: `${target.apiBase}/repos/${target.path}/actions/workflows/${controlPipelineFileName(wordsIn)}/dispatches`,
312
368
  method: "POST",
313
369
  headers: { Accept: "application/json", "Content-Type": "application/json" },
314
- body: { json: { ref: target.ref, inputs: { member: d.member, op: d.op, sha: d.sha, ...(d.outcome ? { outcome: d.outcome } : {}) } } },
370
+ body: { json: { ref: target.ref, inputs: { member: d.member, op: d.op, sha: d.sha, ...(d.outcome ? { outcome: d.outcome } : {}), ...trainFields(d) } } },
315
371
  token: { in: "header", name: "Authorization", scheme: "token" },
316
372
  };
317
373
  }
@@ -371,6 +427,19 @@ export async function dispatchControl(target: ControlTarget, d: ControlDispatch,
371
427
  return { status: res.status };
372
428
  }
373
429
 
430
+ /**
431
+ * Shell lines that set each pattern into a variable, `<name>_re`. Bash's
432
+ * `=~` matches a quoted pattern as a plain string, so a script quotes it
433
+ * once here and matches against the variable unquoted. The patterns here
434
+ * hold no quote.
435
+ */
436
+ export function shellPatterns(patterns: Record<string, RegExp>): string[] {
437
+ return Object.entries(patterns).map(([name, re]) => {
438
+ if (re.source.includes("'")) throw new ControlConfigError(`not a pattern a shell word can hold: ${re.source}`);
439
+ return `${name}_re='${re.source}'`;
440
+ });
441
+ }
442
+
374
443
  /** A value that passed {@link CONTROL_NAME} or {@link CONTROL_REF} is safe in a single-quoted shell word. */
375
444
  function sq(v: string, re: RegExp): string {
376
445
  if (!re.test(v)) throw new ControlConfigError(`not a safe name: ${v}`);
@@ -404,6 +473,14 @@ export interface ControlDispatchScriptOptions {
404
473
  * repo records it and runs the dependents only when something applied.
405
474
  */
406
475
  outcome?: boolean;
476
+ /**
477
+ * Carry a train's answer (#5119): the step reads the train, the run, the
478
+ * environment and the release from {@link CONTROL_TRAIN_VAR},
479
+ * {@link CONTROL_RUN_VAR}, {@link CONTROL_ENV_VAR} and
480
+ * {@link CONTROL_RELEASE_VAR}, refuses any that is not usable, and sends
481
+ * them with the outcome. Needs `outcome`.
482
+ */
483
+ train?: boolean;
407
484
  }
408
485
 
409
486
  /**
@@ -431,13 +508,24 @@ export function controlDispatchScript(target: ControlTarget, opts: ControlDispat
431
508
  `case "$outcome" in ${CONTROL_APPLY_OUTCOMES.join("|")}) ;; *) echo "${label}: the waves' outcome (\\"$outcome\\") is not one of ${CONTROL_APPLY_OUTCOMES.join(", ")}, so ${target.repo} was not told" >&2; exit 1 ;; esac`,
432
509
  ]
433
510
  : []),
511
+ ...(opts.train
512
+ ? [
513
+ `train="\${${CONTROL_TRAIN_VAR}:-}"`,
514
+ `run="\${${CONTROL_RUN_VAR}:-}"`,
515
+ `tenv="\${${CONTROL_ENV_VAR}:-}"`,
516
+ `release="\${${CONTROL_RELEASE_VAR}:-}"`,
517
+ ...shellPatterns({ train: CONTROL_TRAIN_ID, run: CONTROL_RUN_ID, name: CONTROL_NAME, release: CONTROL_RELEASE_DIGEST }),
518
+ `[[ $train =~ $train_re && $run =~ $run_re && $tenv =~ $name_re && $release =~ $release_re ]] || { echo "${label}: the train's fields are not usable (train=\\"$train\\", run=\\"$run\\", env=\\"$tenv\\", release=\\"$release\\"), so ${target.repo} was not told" >&2; exit 1; }`,
519
+ ]
520
+ : []),
434
521
  `[ -n "\${${tok}:-}" ] || { echo "${label}: ${tok} is empty; map the ${target.tokenSecret} secret into it, so ${target.repo} can be told" >&2; exit 1; }`,
435
522
  ...(opts.sentCheck ? [`if [ "$(${opts.sentCheck} 2>/dev/null)" = 1 ]; then echo "${label}: ${target.repo} was told about \${sha:0:8} already"; exit 0; fi`] : []),
436
523
  'answer="$(mktemp)"',
437
524
  ];
438
525
  let send: string;
526
+ if (opts.train && !opts.outcome) throw new ControlConfigError("a train's answer carries the outcome of the member's run; set outcome too");
439
527
  if ("json" in req.body) {
440
- const carried = opts.outcome ? `,"outcome":"'"$outcome"'"` : "";
528
+ const carried = `${opts.outcome ? `,"outcome":"'"$outcome"'"` : ""}${opts.train ? `,"train":"'"$train"'","run":"'"$run"'","env":"'"$tenv"'","release":"'"$release"'"` : ""}`;
441
529
  const json =
442
530
  target.forge === "github"
443
531
  ? `{"event_type":"${controlDispatchEvent(words)}","client_payload":{"member":"'"$member"'","op":"'"$op"'","sha":"'"$sha"'"${carried}}}`
@@ -453,6 +541,14 @@ export function controlDispatchScript(target: ControlTarget, opts: ControlDispat
453
541
  `--form "variables[${CONTROL_OP_VAR}]=$op"`,
454
542
  `--form "variables[${CONTROL_SHA_VAR}]=$sha"`,
455
543
  ...(opts.outcome ? [`--form "variables[${CONTROL_OUTCOME_VAR}]=$outcome"`] : []),
544
+ ...(opts.train
545
+ ? [
546
+ `--form "variables[${CONTROL_TRAIN_VAR}]=$train"`,
547
+ `--form "variables[${CONTROL_RUN_VAR}]=$run"`,
548
+ `--form "variables[${CONTROL_ENV_VAR}]=$tenv"`,
549
+ `--form "variables[${CONTROL_RELEASE_VAR}]=$release"`,
550
+ ]
551
+ : []),
456
552
  ];
457
553
  send = `code="$(printf '%s' "$${tok}" | curl -sS -o "$answer" -w '%{http_code}' -X POST --form 'token=<-' ${fields.join(" ")} ${sqUrl(req.url)})"`;
458
554
  }
@@ -489,6 +585,11 @@ function recordAppliedLine(label: string): string {
489
585
  * and {@link CONTROL_APPLY_OUTCOMES} before they reach a command line. A
490
586
  * dispatch that carries an outcome is recorded first (#4617), and its
491
587
  * dependents run only when something applied ({@link CONTROL_RUNS_DEPENDENTS}).
588
+ *
589
+ * A dispatch that answers a release train (#5119) runs no dependents: once
590
+ * it is recorded, the train's promote continues from it (`chant workspace
591
+ * train promote <env> <train> --continue`), which dispatches the next member
592
+ * or stops the train, and the job pushes what that wrote.
492
593
  */
493
594
  export function controlDependentsScript(opts: { command?: string; label?: string } = {}): string {
494
595
  const label = opts.label ?? "chant";
@@ -501,8 +602,18 @@ export function controlDependentsScript(opts: { command?: string; label?: string
501
602
  `re='${CONTROL_NAME.source}'`,
502
603
  `[[ $member =~ $re && $op =~ $re ]] || { echo "${label}: the dispatch names no usable member and Op (member=\\"$member\\", op=\\"$op\\")" >&2; exit 2; }`,
503
604
  `case "$outcome" in ""|${CONTROL_APPLY_OUTCOMES.join("|")}) ;; *) echo "${label}: the dispatch's outcome (\\"$outcome\\") is not one of ${CONTROL_APPLY_OUTCOMES.join(", ")}" >&2; exit 2 ;; esac`,
605
+ `train="\${${CONTROL_TRAIN_VAR}:-}"`,
606
+ `tenv="\${${CONTROL_ENV_VAR}:-}"`,
607
+ ...shellPatterns({ train: CONTROL_TRAIN_ID }),
608
+ `[ -z "$train" ] || [[ $train =~ $train_re && $tenv =~ $re ]] || { echo "${label}: the dispatch names no usable train and environment (train=\\"$train\\", env=\\"$tenv\\")" >&2; exit 2; }`,
504
609
  "npm ci",
505
610
  recordAppliedLine(label),
611
+ // #5119: a train's answer moves the train on; the member's dependents are not this dispatch's to run.
612
+ `if [ -n "$train" ]; then`,
613
+ ` code=0; ${chant} workspace train promote "$tenv" "$train" --continue --json || code=$?`,
614
+ ` git push -q origin refs/heads/chant/lifecycle:refs/heads/chant/lifecycle || echo "${label}: the train's records were not pushed to chant/lifecycle" >&2`,
615
+ ` exit "$code"`,
616
+ "fi",
506
617
  `case "$outcome" in ""|${CONTROL_RUNS_DEPENDENTS.join("|")}) ;; *) echo "${label}: $member's waves ended $outcome and applied nothing, so its dependents do not run"; exit 0 ;; esac`,
507
618
  `${chant} workspace run --dependents-of "$member" --op "$op" --json`,
508
619
  ].join("\n");
@@ -531,11 +642,31 @@ export interface ControlPipelineSpec {
531
642
  notes: string[];
532
643
  }
533
644
 
645
+ /** The variable a train's promote reads one member repository's dispatch token from, and the secret it is kept in (#5119): `CHANT_TRAIN_TOKEN_<MEMBER>`. */
646
+ export function trainTokenEnv(member: string): string {
647
+ return `CHANT_TRAIN_TOKEN_${member.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
648
+ }
649
+
650
+ /** Each member's dispatch token variable mapped from the secret of the same name, refusing two members that would share one. */
651
+ export function trainTokenEnvOf(members: readonly string[]): Record<string, string> {
652
+ const out: Record<string, string> = {};
653
+ const owner = new Map<string, string>();
654
+ for (const m of members) {
655
+ if (!CONTROL_NAME.test(m)) throw new ControlConfigError(`train member "${m}" is not a name the control repo's workspace can hold`);
656
+ const name = trainTokenEnv(m);
657
+ const had = owner.get(name);
658
+ if (had !== undefined && had !== m) throw new ControlConfigError(`members ${had} and ${m} would share the dispatch token ${name}; rename one`);
659
+ owner.set(name, m);
660
+ out[name] = `\${{ secrets.${name} }}`;
661
+ }
662
+ return out;
663
+ }
664
+
534
665
  /** The first chant with `chant workspace run --dependents-of`, which the control repo's package.json pins. terragucci's `CONTROL_CHANT_FLOOR`. */
535
666
  export const CONTROL_DEPENDENTS_FLOOR = "0.124.47";
536
667
 
537
668
  /** The control repo's pipeline for `forge`, in the product's words. */
538
- export function controlPipelineSpec(forge: ForgeKind, wordsIn: CiProductWordsInput | CiProductWords = {}, opts: { command?: string } = {}): ControlPipelineSpec {
669
+ export function controlPipelineSpec(forge: ForgeKind, wordsIn: CiProductWordsInput | CiProductWords = {}, opts: { command?: string; trainMembers?: readonly string[] } = {}): ControlPipelineSpec {
539
670
  const words = resolveProductWords(wordsIn);
540
671
  const product = words.product;
541
672
  const gitlab = forge === "gitlab";
@@ -543,6 +674,7 @@ export function controlPipelineSpec(forge: ForgeKind, wordsIn: CiProductWordsInp
543
674
  const op = gitlab ? `$${CONTROL_OP_VAR}` : "${{ github.event.client_payload.op || inputs.op }}";
544
675
  const sha = gitlab ? `$${CONTROL_SHA_VAR}` : "${{ github.event.client_payload.sha || inputs.sha }}";
545
676
  const outcome = "${{ github.event.client_payload.outcome || inputs.outcome }}";
677
+ const payload = (key: string) => `\${{ github.event.client_payload.${key} || inputs.${key} }}`;
546
678
  const bin = words.bin ?? product;
547
679
  const notes = [
548
680
  `the repo's package.json must pin @intentius/chant at ${CONTROL_DEPENDENTS_FLOOR} or later, which has \`chant workspace run --dependents-of\``,
@@ -569,8 +701,27 @@ export function controlPipelineSpec(forge: ForgeKind, wordsIn: CiProductWordsInp
569
701
  op: { description: "The Op to run on them", required: true, type: "string" },
570
702
  sha: { description: "The member's commit that applied", required: false, type: "string" },
571
703
  outcome: { description: `What the member's waves did: ${CONTROL_APPLY_OUTCOMES.join(", ")}`, required: false, type: "string" },
704
+ train: { description: "The release train the member's run answers, when it ran for one", required: false, type: "string" },
705
+ run: { description: "The run of the train's promote", required: false, type: "string" },
706
+ env: { description: "The environment the train promotes to", required: false, type: "string" },
707
+ release: { description: "The release digest the member ran", required: false, type: "string" },
708
+ },
709
+ env: {
710
+ ...(gitlab
711
+ ? {}
712
+ : {
713
+ [CONTROL_MEMBER_VAR]: member,
714
+ [CONTROL_OP_VAR]: op,
715
+ [CONTROL_SHA_VAR]: sha,
716
+ [CONTROL_OUTCOME_VAR]: outcome,
717
+ [CONTROL_TRAIN_VAR]: payload("train"),
718
+ [CONTROL_RUN_VAR]: payload("run"),
719
+ [CONTROL_ENV_VAR]: payload("env"),
720
+ [CONTROL_RELEASE_VAR]: payload("release"),
721
+ }),
722
+ // #5119: a train's promote dispatches the next member with that repository's dispatch token.
723
+ ...(gitlab || !opts.trainMembers?.length ? {} : { CHANT_TRAIN_PRODUCT: product, ...trainTokenEnvOf(opts.trainMembers) }),
572
724
  },
573
- env: gitlab ? {} : { [CONTROL_MEMBER_VAR]: member, [CONTROL_OP_VAR]: op, [CONTROL_SHA_VAR]: sha, [CONTROL_OUTCOME_VAR]: outcome },
574
725
  script: controlDependentsScript({ label: product, ...(opts.command ? { command: opts.command } : {}) }),
575
726
  group: `${product}-dependents-${member}`,
576
727
  rule: `$CI_PIPELINE_SOURCE == "trigger" && $${CONTROL_MEMBER_VAR} && $${CONTROL_OP_VAR}`,