@intentius/chant 0.124.77 → 0.124.79

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 (228) hide show
  1. package/dist/__fixtures__/notify-messages/events.d.ts +9 -0
  2. package/dist/__fixtures__/notify-messages/events.d.ts.map +1 -0
  3. package/dist/__fixtures__/notify-messages/events.js +21 -0
  4. package/dist/__fixtures__/product-words.d.ts +14 -0
  5. package/dist/__fixtures__/product-words.d.ts.map +1 -1
  6. package/dist/__fixtures__/product-words.js +11 -0
  7. package/dist/__fixtures__/terragucci-notify.d.ts +66 -0
  8. package/dist/__fixtures__/terragucci-notify.d.ts.map +1 -0
  9. package/dist/__fixtures__/terragucci-notify.js +133 -0
  10. package/dist/action-pins.d.ts +8 -0
  11. package/dist/action-pins.d.ts.map +1 -1
  12. package/dist/action-pins.js +8 -0
  13. package/dist/agent-guard.d.ts.map +1 -1
  14. package/dist/agent-guard.js +1 -2
  15. package/dist/change-set.d.ts +10 -1
  16. package/dist/change-set.d.ts.map +1 -1
  17. package/dist/change-set.js +4 -1
  18. package/dist/ci-agent.d.ts +16 -2
  19. package/dist/ci-agent.d.ts.map +1 -1
  20. package/dist/ci-agent.js +6 -1
  21. package/dist/ci-commit.d.ts +66 -2
  22. package/dist/ci-commit.d.ts.map +1 -1
  23. package/dist/ci-commit.js +147 -19
  24. package/dist/ci-own-jobs.d.ts.map +1 -1
  25. package/dist/ci-own-jobs.js +1 -2
  26. package/dist/ci-product-words.d.ts +18 -4
  27. package/dist/ci-product-words.d.ts.map +1 -1
  28. package/dist/ci-product-words.js +26 -6
  29. package/dist/ci-product.d.ts +7 -3
  30. package/dist/ci-product.d.ts.map +1 -1
  31. package/dist/ci-product.js +8 -5
  32. package/dist/cli/handlers/release.d.ts +8 -0
  33. package/dist/cli/handlers/release.d.ts.map +1 -1
  34. package/dist/cli/handlers/release.js +68 -6
  35. package/dist/cli/handlers/run-wave.js +1 -0
  36. package/dist/cli/main.d.ts.map +1 -1
  37. package/dist/cli/main.js +7 -0
  38. package/dist/cli/mcp/product-tools.d.ts +6 -0
  39. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  40. package/dist/cli/mcp/product-tools.js +7 -0
  41. package/dist/cli/mcp/read-only.d.ts +12 -0
  42. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  43. package/dist/cli/mcp/read-only.js +16 -0
  44. package/dist/cli/mcp/server.d.ts +11 -0
  45. package/dist/cli/mcp/server.d.ts.map +1 -1
  46. package/dist/cli/mcp/server.js +26 -5
  47. package/dist/cli/mcp/types.d.ts +5 -1
  48. package/dist/cli/mcp/types.d.ts.map +1 -1
  49. package/dist/components/capability.d.ts +42 -0
  50. package/dist/components/capability.d.ts.map +1 -1
  51. package/dist/components/group-digest.d.ts +17 -0
  52. package/dist/components/group-digest.d.ts.map +1 -0
  53. package/dist/components/group-digest.js +18 -0
  54. package/dist/components/groups.d.ts +2 -11
  55. package/dist/components/groups.d.ts.map +1 -1
  56. package/dist/components/groups.js +2 -12
  57. package/dist/components/index.d.ts +1 -1
  58. package/dist/components/index.d.ts.map +1 -1
  59. package/dist/components/pr-env-components.d.ts.map +1 -1
  60. package/dist/components/pr-env-components.js +1 -2
  61. package/dist/config.d.ts +28 -8
  62. package/dist/config.d.ts.map +1 -1
  63. package/dist/config.js +21 -1
  64. package/dist/lexicon.d.ts +8 -0
  65. package/dist/lexicon.d.ts.map +1 -1
  66. package/dist/lexicon.js +8 -0
  67. package/dist/lifecycle/release-cut.d.ts +7 -1
  68. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  69. package/dist/lifecycle/release-cut.js +1 -0
  70. package/dist/lifecycle/release-images.d.ts +86 -3
  71. package/dist/lifecycle/release-images.d.ts.map +1 -1
  72. package/dist/lifecycle/release-images.js +131 -6
  73. package/dist/lifecycle/release-publish.d.ts +8 -1
  74. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  75. package/dist/lifecycle/release-publish.js +30 -3
  76. package/dist/lifecycle/release-version.d.ts +86 -0
  77. package/dist/lifecycle/release-version.d.ts.map +1 -0
  78. package/dist/lifecycle/release-version.js +209 -0
  79. package/dist/mcp/types.d.ts +26 -0
  80. package/dist/mcp/types.d.ts.map +1 -1
  81. package/dist/notify-product.d.ts +11 -2
  82. package/dist/notify-product.d.ts.map +1 -1
  83. package/dist/notify-product.js +15 -4
  84. package/dist/notify-relay.d.ts.map +1 -1
  85. package/dist/notify-relay.js +1 -2
  86. package/dist/notify.d.ts +36 -4
  87. package/dist/notify.d.ts.map +1 -1
  88. package/dist/notify.js +31 -21
  89. package/dist/notify.schema.json +1 -0
  90. package/dist/op/activities/review-product.d.ts +111 -0
  91. package/dist/op/activities/review-product.d.ts.map +1 -0
  92. package/dist/op/activities/review-product.js +115 -0
  93. package/dist/op/gate.d.ts +17 -0
  94. package/dist/op/gate.d.ts.map +1 -1
  95. package/dist/op/gate.js +36 -0
  96. package/dist/op/index.d.ts +8 -6
  97. package/dist/op/index.d.ts.map +1 -1
  98. package/dist/op/index.js +5 -4
  99. package/dist/op/op-waves-after-plan.d.ts +76 -1
  100. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  101. package/dist/op/op-waves-after-plan.js +142 -3
  102. package/dist/op/op-waves-capability-spec.js +1 -2
  103. package/dist/op/op-waves-capability.d.ts +89 -2
  104. package/dist/op/op-waves-capability.d.ts.map +1 -1
  105. package/dist/op/op-waves-capability.js +215 -7
  106. package/dist/op/op-waves-run-hooks.d.ts +104 -0
  107. package/dist/op/op-waves-run-hooks.d.ts.map +1 -0
  108. package/dist/op/op-waves-run-hooks.js +146 -0
  109. package/dist/op/op-waves-run.d.ts +21 -0
  110. package/dist/op/op-waves-run.d.ts.map +1 -1
  111. package/dist/op/op-waves-run.js +233 -13
  112. package/dist/op/op-waves.d.ts +11 -1
  113. package/dist/op/op-waves.d.ts.map +1 -1
  114. package/dist/op/op-waves.js +7 -1
  115. package/dist/op/runtime.d.ts +2 -0
  116. package/dist/op/runtime.d.ts.map +1 -1
  117. package/dist/policy-engine.d.ts.map +1 -1
  118. package/dist/policy-engine.js +1 -2
  119. package/dist/pr-forge-reads.d.ts +124 -0
  120. package/dist/pr-forge-reads.d.ts.map +1 -0
  121. package/dist/pr-forge-reads.js +322 -0
  122. package/dist/pr-forge.d.ts +14 -0
  123. package/dist/pr-forge.d.ts.map +1 -1
  124. package/dist/pr-forge.js +21 -13
  125. package/dist/pr-plan-note.d.ts +293 -0
  126. package/dist/pr-plan-note.d.ts.map +1 -0
  127. package/dist/pr-plan-note.js +361 -0
  128. package/dist/release-floors.d.ts +13 -1
  129. package/dist/release-floors.d.ts.map +1 -1
  130. package/dist/release-floors.js +13 -1
  131. package/dist/state-export.d.ts.map +1 -1
  132. package/dist/state-export.js +1 -2
  133. package/dist/state-migration.d.ts.map +1 -1
  134. package/dist/state-migration.js +1 -2
  135. package/dist/state-unlock.d.ts.map +1 -1
  136. package/dist/state-unlock.js +1 -2
  137. package/dist/wave-runtime.mjs +314 -314
  138. package/dist/workspace/change-set.schema.json +7 -0
  139. package/dist/workspace/release-workflow.d.ts +7 -0
  140. package/dist/workspace/release-workflow.d.ts.map +1 -1
  141. package/dist/workspace/release-workflow.js +13 -2
  142. package/package.json +1 -1
  143. package/src/__fixtures__/notify-messages/events.ts +23 -0
  144. package/src/__fixtures__/notify-messages/messages.json +50 -0
  145. package/src/__fixtures__/pr-loop/terragucci-plan.note.golden.md +53 -0
  146. package/src/__fixtures__/pr-loop/terragucci-plan.note.json +83 -0
  147. package/src/__fixtures__/product-words.ts +12 -0
  148. package/src/__fixtures__/review-agent/terragucci-review.json +94 -0
  149. package/src/__fixtures__/terragucci-notify.ts +170 -0
  150. package/src/action-pins.test.ts +11 -1
  151. package/src/action-pins.ts +9 -0
  152. package/src/agent-guard.test.ts +1 -2
  153. package/src/agent-guard.ts +1 -2
  154. package/src/change-set.test.ts +20 -0
  155. package/src/change-set.ts +11 -1
  156. package/src/ci-agent.test.ts +9 -0
  157. package/src/ci-agent.ts +15 -2
  158. package/src/ci-commit.test.ts +162 -0
  159. package/src/ci-commit.ts +167 -21
  160. package/src/ci-own-jobs.test.ts +1 -2
  161. package/src/ci-own-jobs.ts +1 -2
  162. package/src/ci-product-words.ts +35 -7
  163. package/src/ci-product.ts +9 -6
  164. package/src/cli/handlers/build-pr-loop-control.test.ts +1 -2
  165. package/src/cli/handlers/build-run-group.test.ts +1 -2
  166. package/src/cli/handlers/release.ts +60 -7
  167. package/src/cli/handlers/run-wave.ts +1 -0
  168. package/src/cli/main.ts +7 -0
  169. package/src/cli/mcp/product-tools.test.ts +50 -0
  170. package/src/cli/mcp/product-tools.ts +8 -0
  171. package/src/cli/mcp/read-only.ts +19 -0
  172. package/src/cli/mcp/server.test.ts +30 -0
  173. package/src/cli/mcp/server.ts +28 -5
  174. package/src/cli/mcp/types.ts +6 -1
  175. package/src/components/capability.ts +41 -0
  176. package/src/components/group-digest.ts +20 -0
  177. package/src/components/groups.ts +3 -13
  178. package/src/components/index.ts +2 -0
  179. package/src/components/pr-env-components.test.ts +1 -2
  180. package/src/components/pr-env-components.ts +1 -2
  181. package/src/config.ts +38 -3
  182. package/src/gate-policy-bundle.test.ts +1 -1
  183. package/src/lexicon.ts +9 -0
  184. package/src/lifecycle/release-cut.ts +11 -0
  185. package/src/lifecycle/release-images-dockerfile.test.ts +229 -0
  186. package/src/lifecycle/release-images.ts +171 -8
  187. package/src/lifecycle/release-publish.ts +34 -3
  188. package/src/lifecycle/release-version.test.ts +155 -0
  189. package/src/lifecycle/release-version.ts +227 -0
  190. package/src/mcp/types.ts +27 -0
  191. package/src/notify-message-words.test.ts +185 -0
  192. package/src/notify-product.ts +16 -4
  193. package/src/notify-relay.ts +1 -2
  194. package/src/notify.schema.json +1 -0
  195. package/src/notify.ts +59 -19
  196. package/src/op/activities/review-product.test.ts +116 -0
  197. package/src/op/activities/review-product.ts +199 -0
  198. package/src/op/gate.ts +46 -0
  199. package/src/op/index.ts +10 -4
  200. package/src/op/op-waves-after-plan-wave.test.ts +226 -0
  201. package/src/op/op-waves-after-plan.ts +170 -5
  202. package/src/op/op-waves-capability-spec.ts +1 -1
  203. package/src/op/op-waves-capability.test.ts +6 -0
  204. package/src/op/op-waves-capability.ts +243 -10
  205. package/src/op/op-waves-run-hooks.test.ts +184 -0
  206. package/src/op/op-waves-run-hooks.ts +195 -0
  207. package/src/op/op-waves-run.ts +240 -16
  208. package/src/op/op-waves-step-wave.test.ts +277 -0
  209. package/src/op/op-waves.ts +15 -2
  210. package/src/op/runtime.ts +2 -0
  211. package/src/op/schedule-overdue.test.ts +26 -0
  212. package/src/policy-engine.test.ts +1 -2
  213. package/src/policy-engine.ts +1 -2
  214. package/src/pr-forge-reads.test.ts +285 -0
  215. package/src/pr-forge-reads.ts +424 -0
  216. package/src/pr-forge.ts +30 -16
  217. package/src/pr-plan-note.test.ts +105 -0
  218. package/src/pr-plan-note.ts +520 -0
  219. package/src/release-floors.ts +19 -1
  220. package/src/state-export.test.ts +1 -2
  221. package/src/state-export.ts +1 -2
  222. package/src/state-migration.test.ts +1 -2
  223. package/src/state-migration.ts +1 -2
  224. package/src/state-unlock.test.ts +1 -2
  225. package/src/state-unlock.ts +1 -2
  226. package/src/workspace/change-set.schema.json +7 -0
  227. package/src/workspace/release-workflow.test.ts +18 -0
  228. package/src/workspace/release-workflow.ts +23 -2
@@ -20,13 +20,43 @@
20
20
  * The spec's command hooks at `hooks.after.plan` keep running where they
21
21
  * ran: after the set digest, before the gate settles. A `perRun` one gets
22
22
  * `{planJson}`, `CHANT_PLAN_DIGEST` and `CHANT_PLAN_JSON` the same way.
23
+ *
24
+ * ## The wave answer (#4842)
25
+ *
26
+ * A hook's `wave`, when it has one, is called once per job after its `run`
27
+ * was called for each of its runs, with all of them. It answers for the wave
28
+ * as a whole, as a plans file does for a wave-level plan command:
29
+ *
30
+ * - `pending`: fields for the pending fact (a `description`, the commit it
31
+ * planned), under the plans file's rules (`pendingFields`).
32
+ * - `members`: digest members that are no run, such as the wave's monthly
33
+ * cost from the product's own estimator.
34
+ * - `holds`: reasons the wave waits for a person whatever its gate, one line
35
+ * each, as a held hook's.
36
+ * - `overriders` and `overridersSource`: who may override a denial, in place
37
+ * of the overriders file at base. A run's own answer can name its own
38
+ * `overriders`, which count for that run in place of the wave's.
39
+ * - `report`: the product's report of these plans. When the wave waits,
40
+ * chant stores it beside the pending fact, at
41
+ * `_gates/<op>/<gate>/<digest>.json`, once. When the plans moved after an
42
+ * approval, chant writes it and the report stored for the approved plans
43
+ * to `.chant/op-waves/<name>/wave-<k>/report/` (`current.json`,
44
+ * `approved.json`) and names them on the decision, for the job that
45
+ * explains the refusal.
46
+ *
47
+ * A `wave` that throws follows the hook's `onFailure`, as `run` does.
23
48
  */
24
49
 
25
50
  import { isAbsolute } from "node:path";
51
+ import { NEXT_RELEASE } from "../release-floors";
26
52
  import type { ChangeSetPart } from "../change-set";
27
53
  import type { OpRunPolicyRow } from "./runtime";
54
+ import type { WaveMember } from "../wave-engine";
28
55
  import { OP_WAVE_HOOK_FAILURES, opWaveHookRuns, type OpWaveHookFailure } from "./op-waves";
29
- import type { OpWaveHookOutcome } from "./stage-hooks";
56
+ import { OP_WAVE_PENDING_RESERVED, type OpWaveHookOutcome } from "./stage-hooks";
57
+
58
+ /** The first chant whose after-plan hooks answer for the wave as a whole (`wave`), take a run's own `overriders`, and whose wave keeps the hook's report beside its pending fact (#4842). */
59
+ export const OP_WAVE_AFTER_PLAN_WAVE_FLOOR = NEXT_RELEASE;
30
60
 
31
61
  /** One planned run, as an after-plan hook in the job's process sees it (#4614). */
32
62
  export interface OpWaveAfterPlanRun {
@@ -64,6 +94,36 @@ export interface OpWaveAfterPlanResult {
64
94
  policy?: OpRunPolicyRow[];
65
95
  /** Files the hook wrote for the run, relative to the job's directory. */
66
96
  files?: string[];
97
+ /** Who may override this run's denial (#4842), in place of the wave's overriders. */
98
+ overriders?: string[];
99
+ }
100
+
101
+ /** A job's planned runs, as a hook's wave answer sees them (#4842). */
102
+ export interface OpWaveAfterPlanWave {
103
+ spec: string;
104
+ op: string;
105
+ wave: number;
106
+ waveName: string;
107
+ job: OpWaveAfterPlanRun["job"];
108
+ /** The runs the hook is for, in the wave's order, as its `run` saw each. */
109
+ runs: OpWaveAfterPlanRun[];
110
+ cwd: string;
111
+ }
112
+
113
+ /** What a hook adds to the wave as a whole (#4842). */
114
+ export interface OpWaveAfterPlanWaveResult {
115
+ /** Fields for the wave's pending fact, as a plans file's `pending`. */
116
+ pending?: Record<string, unknown>;
117
+ /** Digest members that are no run, such as the wave's cost. */
118
+ members?: WaveMember[];
119
+ /** Why the wave waits for a person whatever its gate, a line each. */
120
+ holds?: string[];
121
+ /** Who may override a denial, in place of the overriders file at base. */
122
+ overriders?: string[];
123
+ /** Where those overriders come from, for a refusal: "policy.override in terragucci.yml". */
124
+ overridersSource?: string;
125
+ /** The product's report of these plans: stored beside the pending fact, and written for the respond job after the plans moved. */
126
+ report?: string;
67
127
  }
68
128
 
69
129
  /** An after-plan hook in the wave job's process (#4614). */
@@ -75,6 +135,8 @@ export interface OpWaveAfterPlanHook {
75
135
  /** The runs it is for, as a command hook's `targets`. Default: every run. */
76
136
  targets?: string[];
77
137
  run(planned: OpWaveAfterPlanRun): OpWaveAfterPlanResult | void | Promise<OpWaveAfterPlanResult | void>;
138
+ /** Called once per job after `run` for each of its runs (#4842): what the hook adds to the wave. */
139
+ wave?(planned: OpWaveAfterPlanWave): OpWaveAfterPlanWaveResult | void | Promise<OpWaveAfterPlanWaveResult | void>;
78
140
  }
79
141
 
80
142
  const ROW_RESULTS: ReadonlyArray<OpRunPolicyRow["result"]> = ["passed", "warned", "denied", "held"];
@@ -90,6 +152,7 @@ export function opWaveAfterPlanProblems(hooks: unknown): string[] {
90
152
  if (!hook || typeof hook !== "object") return void problems.push(`${at} must be { name, run, onFailure?, targets? }`);
91
153
  if (typeof hook.name !== "string" || hook.name.trim() === "") problems.push(`${at} needs a name`);
92
154
  if (typeof hook.run !== "function") problems.push(`${at} needs a run function`);
155
+ if (hook.wave !== undefined && typeof hook.wave !== "function") problems.push(`${at}.wave must be a function`);
93
156
  if (hook.onFailure !== undefined && !OP_WAVE_HOOK_FAILURES.includes(hook.onFailure)) problems.push(`${at} has onFailure "${String(hook.onFailure)}"; use ${OP_WAVE_HOOK_FAILURES.join(" or ")}`);
94
157
  if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== ""))) problems.push(`${at}.targets must be a non-empty list of targets or patterns`);
95
158
  });
@@ -99,8 +162,8 @@ export function opWaveAfterPlanProblems(hooks: unknown): string[] {
99
162
  /** What is wrong with one answer of a hook, empty when nothing is. */
100
163
  export function opWaveAfterPlanResultProblems(value: unknown): string[] {
101
164
  if (value === undefined || value === null) return [];
102
- if (typeof value !== "object" || Array.isArray(value)) return ["the answer must be { policy?, files? }"];
103
- const r = value as { policy?: unknown; files?: unknown };
165
+ if (typeof value !== "object" || Array.isArray(value)) return ["the answer must be { policy?, files?, overriders? }"];
166
+ const r = value as { policy?: unknown; files?: unknown; overriders?: unknown };
104
167
  const problems: string[] = [];
105
168
  if (r.policy !== undefined) {
106
169
  if (!Array.isArray(r.policy)) problems.push("`policy` must be a list of rows");
@@ -117,6 +180,46 @@ export function opWaveAfterPlanResultProblems(value: unknown): string[] {
117
180
  if (r.files !== undefined && (!Array.isArray(r.files) || !r.files.every((f) => typeof f === "string" && f !== "" && !isAbsolute(f) && !f.split("/").includes("..")))) {
118
181
  problems.push("`files` must be paths inside the job's directory, relative to it");
119
182
  }
183
+ if (r.overriders !== undefined && !principals(r.overriders)) problems.push("`overriders` must be a list of principals");
184
+ return problems;
185
+ }
186
+
187
+ const principals = (v: unknown): v is string[] => Array.isArray(v) && v.every((p) => typeof p === "string" && p.trim() !== "");
188
+
189
+ /** What is wrong with one wave answer (#4842), empty when nothing is. `targets` are the wave's runs, which no digest member may be named. */
190
+ export function opWaveAfterPlanWaveResultProblems(value: unknown, targets: readonly string[]): string[] {
191
+ if (value === undefined || value === null) return [];
192
+ if (typeof value !== "object" || Array.isArray(value)) return ["the wave answer must be { pending?, members?, holds?, overriders?, overridersSource?, report? }"];
193
+ const r = value as Record<string, unknown>;
194
+ const problems: string[] = [];
195
+ if (r.pending !== undefined) {
196
+ const p = r.pending;
197
+ if (p === null || typeof p !== "object" || Array.isArray(p)) problems.push("`pending` must be an object of fields for the pending fact");
198
+ else {
199
+ const reserved = Object.keys(p).filter((key) => (OP_WAVE_PENDING_RESERVED as readonly string[]).includes(key));
200
+ if (reserved.length > 0) problems.push(`\`pending\` cannot set ${reserved.join(", ")}, which chant writes`);
201
+ if ("description" in p && typeof (p as { description?: unknown }).description !== "string") problems.push("`pending.description` must be a string");
202
+ }
203
+ }
204
+ if (r.overriders !== undefined && !principals(r.overriders)) problems.push("`overriders` must be a list of principals");
205
+ if (r.overridersSource !== undefined && (typeof r.overridersSource !== "string" || r.overridersSource.trim() === "")) problems.push("`overridersSource` must say where the overriders come from");
206
+ if (r.members !== undefined) {
207
+ if (!Array.isArray(r.members)) problems.push("`members` must be a list of { member, planDigest }");
208
+ else {
209
+ const seen = new Set<string>();
210
+ for (const m of r.members as Array<Partial<WaveMember> | null>) {
211
+ if (!m || typeof m.member !== "string" || m.member === "" || typeof m.planDigest !== "string" || m.planDigest === "") {
212
+ problems.push("each of `members` needs a member and a planDigest");
213
+ continue;
214
+ }
215
+ if (targets.includes(m.member)) problems.push(`member ${m.member} is also a run's target; a digest member that is no run needs a name of its own`);
216
+ else if (seen.has(m.member)) problems.push(`\`members\` names ${m.member} twice`);
217
+ seen.add(m.member);
218
+ }
219
+ }
220
+ }
221
+ if (r.holds !== undefined && !(Array.isArray(r.holds) && r.holds.every((h) => typeof h === "string" && h.trim() !== ""))) problems.push("`holds` must be a list of reasons, each a line saying why the wave waits for a person");
222
+ if (r.report !== undefined && typeof r.report !== "string") problems.push("`report` must be the report's text");
120
223
  return problems;
121
224
  }
122
225
 
@@ -125,6 +228,18 @@ export interface OpWaveAfterPlanRunOutcome {
125
228
  /** The hooks' rows, in order. */
126
229
  policy: OpRunPolicyRow[];
127
230
  files: string[];
231
+ /** Who may override its denial (#4842), when a hook named anyone: the last hook's list. */
232
+ overriders?: string[];
233
+ }
234
+
235
+ /** What the hooks' wave answers came to (#4842), each hook's in order. */
236
+ export interface OpWaveAfterPlanWaveOutcome {
237
+ pending?: Record<string, unknown>;
238
+ members: WaveMember[];
239
+ holds: string[];
240
+ overriders?: string[];
241
+ overridersSource?: string;
242
+ report?: string;
128
243
  }
129
244
 
130
245
  /** What the after-plan hooks in the job's process came to (#4614). */
@@ -136,6 +251,8 @@ export interface OpWaveAfterPlanOutcome {
136
251
  outcomes: OpWaveHookOutcome[];
137
252
  /** Each run's rows and files, by target, for the runs a hook answered. */
138
253
  runs: Map<string, OpWaveAfterPlanRunOutcome>;
254
+ /** The wave answers (#4842). */
255
+ wave: OpWaveAfterPlanWaveOutcome;
139
256
  }
140
257
 
141
258
  /**
@@ -149,9 +266,11 @@ export async function runOpWaveAfterPlanHooks(
149
266
  runs: readonly OpWaveAfterPlanRun[],
150
267
  log: (line: string) => void,
151
268
  ): Promise<OpWaveAfterPlanOutcome> {
152
- const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map() };
269
+ const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map(), wave: { members: [], holds: [] } };
270
+ const targets = runs.map((r) => r.target);
153
271
  for (const hook of hooks) {
154
- for (const run of opWaveHookRuns(hook, runs)) {
272
+ const mine = opWaveHookRuns(hook, runs);
273
+ for (const run of mine) {
155
274
  const label = `after-plan hook ${hook.name} (${run.target})`;
156
275
  let problem: string | undefined;
157
276
  let answer: OpWaveAfterPlanResult | void = undefined;
@@ -171,6 +290,11 @@ export async function runOpWaveAfterPlanHooks(
171
290
  for (const f of answer.files ?? []) if (!got.files.includes(f)) got.files.push(f);
172
291
  out.runs.set(run.target, got);
173
292
  }
293
+ if (answer?.overriders) {
294
+ const got = out.runs.get(run.target) ?? { policy: [], files: [] };
295
+ got.overriders = [...new Set(answer.overriders)].sort();
296
+ out.runs.set(run.target, got);
297
+ }
174
298
  continue;
175
299
  }
176
300
  if (hook.onFailure === "approve") {
@@ -184,10 +308,49 @@ export async function runOpWaveAfterPlanHooks(
184
308
  log(problem);
185
309
  return out;
186
310
  }
311
+ if (!hook.wave || mine.length === 0) continue;
312
+ // #4842: the hook's answer for the wave, once its runs were each answered.
313
+ const first = mine[0]!;
314
+ const label = `after-plan hook ${hook.name} (wave ${first.wave})`;
315
+ let problem: string | undefined;
316
+ let answer: OpWaveAfterPlanWaveResult | void = undefined;
317
+ try {
318
+ answer = await hook.wave({ spec: first.spec, op: first.op, wave: first.wave, waveName: first.waveName, job: first.job, runs: [...mine], cwd: first.cwd });
319
+ const wrong = opWaveAfterPlanWaveResultProblems(answer, targets);
320
+ if (wrong.length > 0) problem = `${label} answered with ${wrong.join("; ")}`;
321
+ } catch (err) {
322
+ problem = `${label} failed: ${err instanceof Error ? err.message : String(err)}`;
323
+ }
324
+ const base = { moment: "after-plan" as const, name: hook.name };
325
+ if (problem === undefined) {
326
+ out.outcomes.push({ ...base, exit: 0, outcome: "passed" });
327
+ if (answer) foldWaveAnswer(out.wave, answer);
328
+ continue;
329
+ }
330
+ if (hook.onFailure === "approve") {
331
+ out.outcomes.push({ ...base, exit: 1, outcome: "held" });
332
+ out.holds.push(label);
333
+ log(`${problem}, so wave ${first.wave} (${first.waveName}) waits for an approval of its set digest`);
334
+ continue;
335
+ }
336
+ out.outcomes.push({ ...base, exit: 1, outcome: "failed" });
337
+ out.failed = problem;
338
+ log(problem);
339
+ return out;
187
340
  }
188
341
  return out;
189
342
  }
190
343
 
344
+ /** Fold one hook's wave answer into what the answers so far came to: fields and lists add up, a later list of overriders or report wins. */
345
+ function foldWaveAnswer(into: OpWaveAfterPlanWaveOutcome, answer: OpWaveAfterPlanWaveResult): void {
346
+ if (answer.pending && Object.keys(answer.pending).length > 0) into.pending = { ...into.pending, ...answer.pending };
347
+ for (const m of answer.members ?? []) if (!into.members.some((x) => x.member === m.member)) into.members.push({ member: m.member, planDigest: m.planDigest });
348
+ for (const h of answer.holds ?? []) if (!into.holds.includes(h)) into.holds.push(h);
349
+ if (answer.overriders) into.overriders = [...new Set(answer.overriders)].sort();
350
+ if (answer.overridersSource) into.overridersSource = answer.overridersSource;
351
+ if (answer.report !== undefined) into.report = answer.report;
352
+ }
353
+
191
354
  /** Fold policy rows into a run's denial and hold: the rules of every `denied` row, and of every `held` row. */
192
355
  export function foldPolicyRows(
193
356
  rows: readonly OpRunPolicyRow[],
@@ -216,6 +379,8 @@ export interface ProductWaveHook {
216
379
  capabilities?: import("../components/capability").CapabilityRegistry;
217
380
  /** How the spec's command hooks run, when they call back into the product's process (`RunOpWaveOptions.hookExec`). */
218
381
  hookExec?: import("./stage-hooks").OpWaveAsyncExec;
382
+ /** Hooks around each run of a wave with a `step` (#4842, `RunOpWaveOptions.runHooks`). */
383
+ runHooks?: import("./op-waves-run-hooks").OpWaveRunHooks | readonly import("./op-waves-run-hooks").OpWaveRunHooks[];
219
384
  }
220
385
 
221
386
  let activeWave: ProductWaveHook | undefined;
@@ -62,7 +62,7 @@ export function opWaveStepProblems(spec: Pick<OpWavesSpec, "step" | "plan" | "ap
62
62
  }
63
63
  if (spec.hooks?.apply?.runBy === "apply") problems.push("`hooks.apply.runBy: \"apply\"` hands the apply-stage hooks to an apply command, and a `step` has none; leave runBy as chant");
64
64
  for (const wave of spec.waves) {
65
- if (wave.discover) problems.push(`wave "${wave.name}" discovers its runs, which only \`planWave\` can report; a \`step\` plans the runs the spec lists`);
65
+ // #4842: a step's capability finds a discovering wave's runs (`discoverRuns`), checked when the wave plans.
66
66
  if (wave.hooks?.apply?.runBy === "apply") problems.push(`wave "${wave.name}" hands its apply-stage hooks to an apply command, and a \`step\` has none`);
67
67
  for (const run of wave.runs ?? []) {
68
68
  const input = run.input as unknown;
@@ -214,4 +214,10 @@ describe("the step and holds settings (#4545)", () => {
214
214
  expect(partEffects(part("a", "delete"))).toEqual({ empty: false, destructive: true });
215
215
  expect(partEffects(undefined)).toEqual({ empty: false, destructive: false });
216
216
  });
217
+
218
+ test("a part whose plan changes only outputs is not empty (#4849)", () => {
219
+ const p = part("a", "no-op");
220
+ expect(partEffects({ ...p, member: { ...p.member, outputs: ["url"] } })).toEqual({ empty: false, destructive: false });
221
+ expect(partEffects({ ...p, member: { ...p.member, outputs: [] } })).toEqual({ empty: true, destructive: false });
222
+ });
217
223
  });
@@ -31,6 +31,23 @@
31
31
  * capability refuses as moved (`isPlanMovedError`) applied nothing and the
32
32
  * job exits 4, the table's moved code (#4553); any other error fails it.
33
33
  *
34
+ * ## A wave planned as one (#4842)
35
+ *
36
+ * Some tools plan a wave as a whole. A `discover` wave asks the step's
37
+ * capability for its runs (`discoverRuns`), such as one layer of a
38
+ * Terragrunt repo's units from `terragrunt find`, and plans each run found
39
+ * with `{target}` filled. A wave marked `together` plans its runs in one
40
+ * `planGroup` call and applies them in one `runGroup` call, as a fan-out
41
+ * applies a group (ws-107): Terragrunt's `run --all` over the layer, or a
42
+ * composed run of roots that read each other. Each run keeps its own member
43
+ * digest (its share of the plan), and the group digest (the capability's
44
+ * digest of the whole with each run's, `groupDigest`) is one more digest
45
+ * member, `(wave plan)`, so an approval of one composition does not apply
46
+ * another. The group's artifact goes back to `runGroup`; a run's own
47
+ * artifact stays on its plan file for `{planJson}`. The run hooks run per
48
+ * run around the one call, each run's `processEnv` and `afterInit` on its
49
+ * member's context.
50
+ *
34
51
  * The registry is the project's (`fanOutRegistry`, the one `chant run
35
52
  * --components` builds), loaded once per job behind a dynamic import, so the
36
53
  * wave-job runtime bundle stays without the config loader. A product that
@@ -56,11 +73,13 @@
56
73
  import { spawnSync } from "node:child_process";
57
74
  import { existsSync, mkdirSync, writeFileSync } from "node:fs";
58
75
  import { dirname, join } from "node:path";
59
- import type { Capability, CapabilityPlan, CapabilityRegistry, DeployContext } from "../components/capability";
76
+ import type { Capability, CapabilityPlan, CapabilityRegistry, DeployContext, GroupContext, GroupMember } from "../components/capability";
60
77
  import { isPlanMovedError } from "../components/capability";
61
78
  import type { CapabilityTraceFacts } from "../otlp";
62
79
  import { composeChangeSet, type ChangeSetDocument, type ChangeSetPart } from "../change-set";
63
80
  import { computePlanDigest } from "../lifecycle/plan-digest";
81
+ import { groupDigest } from "../components/group-digest";
82
+ import { NEXT_RELEASE } from "../release-floors";
64
83
  import type { GatePolicyExec, GatePolicyRun } from "../gate-policy";
65
84
  import type { ResolvedGatePolicySource } from "../policy-source";
66
85
  import type { WaveMember } from "../wave-engine";
@@ -88,6 +107,13 @@ export function opWaveStepInput(spec: Pick<OpWavesSpec, "op" | "step">, wave: Pi
88
107
  return { ...(fill(rest, vars) as Record<string, unknown>), ...((run.input ? fill(run.input, vars) : {}) as Record<string, unknown>) };
89
108
  }
90
109
 
110
+ /** The input `discoverRuns` gets (#4842): the spec's step with `{op}` and `{wave}` filled and `{target}` left as written. */
111
+ export function opWaveDiscoverInput(spec: Pick<OpWavesSpec, "op" | "step">, wave: Pick<OpWave, "name">): Record<string, unknown> {
112
+ if (!spec.step) throw new Error("the spec names no step");
113
+ const { kind: _kind, ...rest } = spec.step;
114
+ return fill(rest, { target: "{target}", op: spec.op, wave: wave.name }) as Record<string, unknown>;
115
+ }
116
+
91
117
  /** The context a run's step plans and applies with: the spec's `labels.Env`, else the wave's name, and the run's target as the component. */
92
118
  export function opWaveStepContext(spec: Pick<OpWavesSpec, "labels">, wave: Pick<OpWave, "name">, run: OpWaveRun): DeployContext {
93
119
  return { env: spec.labels?.Env ?? wave.name, component: run.target };
@@ -124,13 +150,31 @@ export interface OpWaveStepPlan {
124
150
  destructive: boolean;
125
151
  /** The run's lock grain and rows (#4552), which the apply leases on the resource grain. */
126
152
  lock?: PlannedLock;
153
+ /** Set when the wave planned `together` (#4842): the one plan every run of it shares. */
154
+ group?: OpWaveStepGroup;
155
+ }
156
+
157
+ /** A wave's plan in one `planGroup` call (#4842), shared by each of its runs' plans. */
158
+ export interface OpWaveStepGroup {
159
+ /** The group digest (`groupDigest`): the capability's digest of the whole, with each run's member and plan digest. */
160
+ digest: string;
161
+ /** What `planGroup` gave for `runGroup`. */
162
+ artifact?: unknown;
163
+ /** Each run's plan as the capability gave it, by target. */
164
+ plans: Record<string, CapabilityPlan>;
127
165
  }
128
166
 
129
- /** Whether a part changes nothing, and whether it destroys or replaces something. */
167
+ /** The digest member a wave planned `together` adds (#4842): no run has this name. */
168
+ export const OP_WAVE_TOGETHER_MEMBER = "(wave plan)";
169
+
170
+ /** The release that has `discover` with a `step`, and `together` waves (#4842). */
171
+ export const OP_WAVE_STEP_WAVE_FLOOR = NEXT_RELEASE;
172
+
173
+ /** Whether a part changes nothing, and whether it destroys or replaces something. A plan that changes only outputs changes something (#4849). */
130
174
  export function partEffects(part: ChangeSetPart | undefined): { empty: boolean; destructive: boolean } {
131
175
  if (!part) return { empty: false, destructive: false };
132
176
  const changing = part.entries.filter((e) => e.action !== "no-op" && e.action !== "read");
133
- return { empty: changing.length === 0, destructive: changing.some((e) => e.action === "delete" || e.action === "replace") };
177
+ return { empty: changing.length === 0 && (part.member.outputs?.length ?? 0) === 0, destructive: changing.some((e) => e.action === "delete" || e.action === "replace") };
134
178
  }
135
179
 
136
180
  function resolveCapability(registry: CapabilityRegistry, kind: string): Capability<never, unknown> {
@@ -140,7 +184,7 @@ function resolveCapability(registry: CapabilityRegistry, kind: string): Capabili
140
184
 
141
185
  /** Plan one run through the spec's step (#4545), writing its plan file at `planPath` (relative to `cwd`) as a per-run `plan` command would. */
142
186
  export async function planOpWaveStep(
143
- at: { spec: OpWavesSpec; wave: OpWave; cwd: string; registry: CapabilityRegistry; planPath: string; lockGrain?: LockGrain | null; policyBase?: string },
187
+ at: { spec: OpWavesSpec; wave: OpWave; cwd: string; registry: CapabilityRegistry; planPath: string; lockGrain?: LockGrain | null; policyBase?: string; processEnv?: Record<string, string>; afterInit?: () => Promise<void> },
144
188
  run: OpWaveRun,
145
189
  ): Promise<OpWaveStepPlan> {
146
190
  const { spec, wave, cwd, registry } = at;
@@ -150,7 +194,8 @@ export async function planOpWaveStep(
150
194
  let planned: CapabilityPlan;
151
195
  let lock: PlannedLock;
152
196
  try {
153
- planned = await capability.plan({ ...opWaveStepContext(spec, wave, run), ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}), ...(at.policyBase ? { policyBase: at.policyBase } : {}) }, input as never);
197
+ // #4842: the run hooks' environment and check after init.
198
+ planned = await capability.plan({ ...opWaveStepContext(spec, wave, run), ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}), ...(at.policyBase ? { policyBase: at.policyBase } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}), ...(at.afterInit ? { afterInit: at.afterInit } : {}) }, input as never);
154
199
  // #4552: the run's grain (declared at base, else its lexicon's) and, on the resource grain, the rows its apply leases.
155
200
  lock = await resolvePlannedLock(capability, input, planned, at.lockGrain);
156
201
  } catch (err) {
@@ -174,11 +219,16 @@ export async function planOpWaveStep(
174
219
  ...effects,
175
220
  lock,
176
221
  };
177
- const file = join(cwd, at.planPath);
222
+ writeStepPlanFile(join(cwd, at.planPath), plan);
223
+ return plan;
224
+ }
225
+
226
+ /** A run's plan file, as a per-run `plan` command writes it: its digest, effects, member, artifact (when it is JSON) and part. */
227
+ function writeStepPlanFile(file: string, plan: OpWaveStepPlan): void {
178
228
  mkdirSync(dirname(file), { recursive: true });
179
229
  let artifact: unknown;
180
230
  try {
181
- artifact = planned.artifact === undefined ? undefined : JSON.parse(JSON.stringify(planned.artifact));
231
+ artifact = plan.artifact === undefined ? undefined : JSON.parse(JSON.stringify(plan.artifact));
182
232
  } catch {
183
233
  artifact = undefined;
184
234
  }
@@ -193,7 +243,190 @@ export async function planOpWaveStep(
193
243
  ...(plan.part ? { changeSet: plan.part } : {}),
194
244
  }) + "\n",
195
245
  );
196
- return plan;
246
+ }
247
+
248
+ /**
249
+ * The runs of a `discover` wave through the spec's step (#4842): what the
250
+ * capability's `discoverRuns` finds for wave `k`, each a run of the spec's
251
+ * op, and how many waves it found.
252
+ */
253
+ export async function discoverOpWaveStepRuns(at: { spec: OpWavesSpec; wave: OpWave; k: number; registry: CapabilityRegistry }): Promise<{ runs: OpWaveRun[]; waves?: number }> {
254
+ const { spec, wave, k } = at;
255
+ const kind = spec.step!.kind;
256
+ const capability = resolveCapability(at.registry, kind);
257
+ if (!capability.discoverRuns) throw new Error(`wave ${k} (${wave.name}) discovers its runs, and the capability "${kind}" cannot find them (it has no discoverRuns)`);
258
+ let found: { targets?: unknown; waves?: unknown };
259
+ try {
260
+ found = await capability.discoverRuns({ env: spec.labels?.Env ?? wave.name, wave: { name: wave.name, number: k } }, opWaveDiscoverInput(spec, wave) as never);
261
+ } catch (err) {
262
+ throw new Error(`finding the runs of wave ${k} (${wave.name}) through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
263
+ }
264
+ const targets = found?.targets;
265
+ if (!Array.isArray(targets) || !targets.every((t) => typeof t === "string" && t !== "")) throw new Error(`${kind} found the runs of wave ${k} (${wave.name}) as ${JSON.stringify(targets)}; give a list of targets`);
266
+ const dup = targets.find((t, i) => targets.indexOf(t) !== i);
267
+ if (dup !== undefined) throw new Error(`${kind} found ${dup} twice in wave ${k} (${wave.name})`);
268
+ const waves = found.waves;
269
+ if (waves !== undefined && (typeof waves !== "number" || !Number.isInteger(waves) || waves < 0)) throw new Error(`${kind} found ${JSON.stringify(waves)} waves for wave ${k} (${wave.name}); give a whole number`);
270
+ return { runs: (targets as string[]).map((target) => ({ target })), ...(waves !== undefined ? { waves: waves as number } : {}) };
271
+ }
272
+
273
+ /** The group members of a wave's runs (#4842): each run's filled input, its `dependsOn` within the wave, and its own context. */
274
+ function waveGroupMembers(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWaveRun[], ctxOf: (run: OpWaveRun) => DeployContext): GroupMember<Record<string, unknown>>[] {
275
+ const inWave = new Set(runs.map((r) => r.target));
276
+ return runs.map((run) => {
277
+ const input = opWaveStepInput(spec, wave, run);
278
+ const dependsOn = (run.dependsOn ?? []).filter((d) => inWave.has(d));
279
+ return { component: run.target, step: input, input, reads: [], ...(dependsOn.length > 0 ? { dependsOn } : {}), ctx: ctxOf(run) };
280
+ });
281
+ }
282
+
283
+ function waveGroupContext(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWaveRun[]): GroupContext {
284
+ return { env: spec.labels?.Env ?? wave.name, components: runs.map((r) => r.target) };
285
+ }
286
+
287
+ function requireGroup(capability: Capability<never, unknown>, kind: string, wave: OpWave): void {
288
+ if (!capability.planGroup || !capability.runGroup) throw new Error(`wave "${wave.name}" plans its runs together, and the capability "${kind}" cannot (it needs planGroup and runGroup)`);
289
+ }
290
+
291
+ /**
292
+ * Plan a `together` wave's runs in one `planGroup` call (#4842), writing
293
+ * each run's plan file at `planPath(target)` (relative to `cwd`). Each run's
294
+ * plan carries the group. Throws when the call does or leaves a run out, and
295
+ * on a run's plan as {@link planOpWaveStep} does.
296
+ */
297
+ export async function planOpWaveStepGroup(
298
+ at: {
299
+ spec: OpWavesSpec;
300
+ wave: OpWave;
301
+ cwd: string;
302
+ registry: CapabilityRegistry;
303
+ planPath: (target: string) => string;
304
+ lockGrain?: LockGrain | null;
305
+ policyBase?: string;
306
+ /** Each run's environment and check after init, from the run hooks. */
307
+ runCtx?: (target: string) => { processEnv?: Record<string, string>; afterInit?: () => Promise<void> };
308
+ },
309
+ runs: readonly OpWaveRun[],
310
+ ): Promise<OpWaveStepPlan[]> {
311
+ const { spec, wave } = at;
312
+ const kind = spec.step!.kind;
313
+ const capability = resolveCapability(at.registry, kind);
314
+ requireGroup(capability, kind, wave);
315
+ const members = waveGroupMembers(spec, wave, runs, (run) => {
316
+ const own = at.runCtx?.(run.target) ?? {};
317
+ return {
318
+ ...opWaveStepContext(spec, wave, run),
319
+ ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}),
320
+ ...(at.policyBase ? { policyBase: at.policyBase } : {}),
321
+ ...(own.processEnv ? { processEnv: own.processEnv } : {}),
322
+ ...(own.afterInit ? { afterInit: own.afterInit } : {}),
323
+ };
324
+ });
325
+ let planned: { members?: Record<string, CapabilityPlan>; digest?: unknown; artifact?: unknown };
326
+ try {
327
+ planned = await capability.planGroup!(waveGroupContext(spec, wave, runs), members as never);
328
+ } catch (err) {
329
+ throw new Error(`planning wave "${wave.name}" together through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
330
+ }
331
+ if (typeof planned?.digest !== "string" || planned.digest === "") throw new Error(`${kind} planned wave "${wave.name}" together with no digest of the whole`);
332
+ const own = new Map<string, CapabilityPlan>();
333
+ for (const run of runs) {
334
+ const p = planned.members?.[run.target];
335
+ if (!p) throw new Error(`${kind} planned wave "${wave.name}" together without a plan for ${run.target}`);
336
+ own.set(run.target, p);
337
+ }
338
+ const digest = groupDigest(kind, runs.map((r) => ({ component: r.target, member: own.get(r.target)!.member, planDigest: own.get(r.target)!.planDigest })), planned.digest);
339
+ const group: OpWaveStepGroup = { digest, ...(planned.artifact !== undefined ? { artifact: planned.artifact } : {}), plans: Object.fromEntries(own) };
340
+ const out: OpWaveStepPlan[] = [];
341
+ for (const [i, run] of runs.entries()) {
342
+ const p = own.get(run.target)!;
343
+ if (typeof p.planDigest !== "string" || p.planDigest === "") throw new Error(`${kind} planned ${run.target} with no plan digest`);
344
+ const holes = p.changeSet?.member.holes ?? [];
345
+ if (holes.length > 0 && p.artifact === undefined && planned.artifact === undefined) throw new Error(`${run.target} was not planned: ${holes.map((h) => h.reason).join("; ")}`);
346
+ const effects = partEffects(p.changeSet);
347
+ if ((p.destructive?.length ?? 0) > 0) effects.destructive = true;
348
+ let lock: PlannedLock;
349
+ try {
350
+ lock = await resolvePlannedLock(capability, members[i]!.input, p, at.lockGrain);
351
+ } catch (err) {
352
+ throw new Error(`planning ${run.target} through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
353
+ }
354
+ const plan: OpWaveStepPlan = {
355
+ target: run.target,
356
+ member: p.member,
357
+ planDigest: p.planDigest,
358
+ ...(p.resourceDigests ? { resources: p.resourceDigests } : {}),
359
+ ...(p.artifact !== undefined ? { artifact: p.artifact } : {}),
360
+ ...(p.changeSet ? { part: p.changeSet } : {}),
361
+ ...effects,
362
+ lock,
363
+ group,
364
+ };
365
+ writeStepPlanFile(join(at.cwd, at.planPath(run.target)), plan);
366
+ out.push(plan);
367
+ }
368
+ return out;
369
+ }
370
+
371
+ /**
372
+ * Apply a `together` wave's runs in one `runGroup` call (#4842), with the
373
+ * plan the gate decided. Each run's outcome, in the order given: `applied`
374
+ * and `no-changes` applied, with the member's outputs; `partial`, `failed`
375
+ * and `not-started` failed. A throw fails every run, or moves every run
376
+ * when it is a moved plan (`isPlanMovedError`).
377
+ */
378
+ export async function applyOpWaveStepGroup(
379
+ at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; runEnv?: (target: string) => Record<string, string> | undefined },
380
+ runs: ReadonlyArray<{ run: OpWaveRun; plan: OpWaveStepPlan }>,
381
+ ): Promise<OpWaveStepApply[]> {
382
+ const { spec, wave } = at;
383
+ const kind = spec.step!.kind;
384
+ let capability: Capability<never, unknown>;
385
+ try {
386
+ capability = resolveCapability(at.registry, kind);
387
+ requireGroup(capability, kind, wave);
388
+ } catch (err) {
389
+ const reason = err instanceof Error ? err.message : String(err);
390
+ return runs.map(() => ({ outcome: "failed", reason }));
391
+ }
392
+ const group = runs[0]?.plan.group;
393
+ if (!group || runs.some((r) => r.plan.group !== group)) return runs.map(() => ({ outcome: "failed", reason: `the runs of wave "${wave.name}" were not planned together, so they cannot apply together` }));
394
+ const byTarget = new Map(runs.map((r) => [r.run.target, r.plan]));
395
+ const members = waveGroupMembers(spec, wave, runs.map((r) => r.run), (run) => {
396
+ const plan = byTarget.get(run.target)!;
397
+ const env = at.runEnv?.(run.target);
398
+ return { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
399
+ });
400
+ const plans = Object.fromEntries(runs.flatMap((r) => (group.plans[r.run.target] ? [[r.run.target, group.plans[r.run.target]!] as const] : [])));
401
+ let got: { members?: Record<string, { status: string; outputs?: Record<string, unknown>; error?: string }>; error?: string };
402
+ try {
403
+ got = await capability.runGroup!(waveGroupContext(spec, wave, runs.map((r) => r.run)), { ...(group.artifact !== undefined ? { artifact: group.artifact } : {}), digest: group.digest, plans }, members as never);
404
+ } catch (err) {
405
+ const reason = err instanceof Error ? err.message : String(err);
406
+ const moved = isPlanMovedError(err);
407
+ return Promise.all(
408
+ runs.map(async (r, i): Promise<OpWaveStepApply> => {
409
+ const facts = await opWaveStepFacts(capability, members[i]!.input, r.plan, { error: err });
410
+ return { ...(moved ? { outcome: "moved" as const, reason } : { outcome: "failed" as const, reason }), ...(facts ? { facts } : {}) };
411
+ }),
412
+ );
413
+ }
414
+ return Promise.all(
415
+ runs.map(async (r, i): Promise<OpWaveStepApply> => {
416
+ const o = got?.members?.[r.run.target];
417
+ const input = members[i]!.input;
418
+ if (o && (o.status === "applied" || o.status === "no-changes")) {
419
+ const output = { status: o.status, ...(o.outputs ? { outputs: o.outputs } : {}) };
420
+ const facts = await opWaveStepFacts(capability, input, r.plan, { output });
421
+ return { outcome: "applied", output, ...(facts ? { facts } : {}) };
422
+ }
423
+ const what = o?.status === "not-started" ? "its part of the wave's apply never started" : o?.status === "partial" ? "part of its plan applied, and the rest did not" : o ? "its part of the wave's apply failed" : `${kind} said nothing of it`;
424
+ const why = o?.error ?? got?.error;
425
+ const reason = `${what}${why ? `: ${why}` : ""}`;
426
+ const facts = await opWaveStepFacts(capability, input, r.plan, { error: new Error(reason) });
427
+ return { outcome: "failed", reason, ...(facts ? { facts } : {}) };
428
+ }),
429
+ );
197
430
  }
198
431
 
199
432
  /** How one run's apply through its step came out, with what the capability knew about it (#4555). */
@@ -225,7 +458,7 @@ export async function opWaveStepFacts(
225
458
  }
226
459
 
227
460
  /** Apply one run through the spec's step (#4545), with the plan the gate decided. */
228
- export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry }, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply> {
461
+ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; processEnv?: Record<string, string> }, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply> {
229
462
  const { spec, wave, registry } = at;
230
463
  let capability: Capability<never, unknown>;
231
464
  try {
@@ -233,7 +466,7 @@ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; reg
233
466
  } catch (err) {
234
467
  return { outcome: "failed", reason: err instanceof Error ? err.message : String(err) };
235
468
  }
236
- const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}) };
469
+ const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}) };
237
470
  const input = opWaveStepInput(spec, wave, run);
238
471
  try {
239
472
  const output = await capability.run(ctx, input as never);