@intentius/chant 0.124.78 → 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 (150) hide show
  1. package/dist/action-pins.d.ts.map +1 -1
  2. package/dist/action-pins.js +1 -2
  3. package/dist/change-set.d.ts +10 -1
  4. package/dist/change-set.d.ts.map +1 -1
  5. package/dist/change-set.js +4 -1
  6. package/dist/ci-agent.d.ts +16 -2
  7. package/dist/ci-agent.d.ts.map +1 -1
  8. package/dist/ci-agent.js +6 -1
  9. package/dist/ci-commit.d.ts.map +1 -1
  10. package/dist/ci-commit.js +2 -3
  11. package/dist/ci-product.d.ts +6 -2
  12. package/dist/ci-product.d.ts.map +1 -1
  13. package/dist/ci-product.js +5 -1
  14. package/dist/cli/handlers/release.d.ts +8 -0
  15. package/dist/cli/handlers/release.d.ts.map +1 -1
  16. package/dist/cli/handlers/release.js +64 -2
  17. package/dist/cli/handlers/run-wave.js +1 -0
  18. package/dist/cli/main.d.ts.map +1 -1
  19. package/dist/cli/main.js +7 -0
  20. package/dist/cli/mcp/product-tools.d.ts +6 -0
  21. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  22. package/dist/cli/mcp/product-tools.js +7 -0
  23. package/dist/cli/mcp/read-only.d.ts +12 -0
  24. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  25. package/dist/cli/mcp/read-only.js +16 -0
  26. package/dist/cli/mcp/server.d.ts +11 -0
  27. package/dist/cli/mcp/server.d.ts.map +1 -1
  28. package/dist/cli/mcp/server.js +26 -5
  29. package/dist/cli/mcp/types.d.ts +5 -1
  30. package/dist/cli/mcp/types.d.ts.map +1 -1
  31. package/dist/components/capability.d.ts +42 -0
  32. package/dist/components/capability.d.ts.map +1 -1
  33. package/dist/components/group-digest.d.ts +17 -0
  34. package/dist/components/group-digest.d.ts.map +1 -0
  35. package/dist/components/group-digest.js +18 -0
  36. package/dist/components/groups.d.ts +2 -11
  37. package/dist/components/groups.d.ts.map +1 -1
  38. package/dist/components/groups.js +2 -12
  39. package/dist/components/index.d.ts +1 -1
  40. package/dist/components/index.d.ts.map +1 -1
  41. package/dist/config.d.ts +14 -0
  42. package/dist/config.d.ts.map +1 -1
  43. package/dist/config.js +5 -0
  44. package/dist/lexicon.d.ts.map +1 -1
  45. package/dist/lexicon.js +1 -2
  46. package/dist/lifecycle/release-cut.d.ts +7 -1
  47. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  48. package/dist/lifecycle/release-cut.js +1 -0
  49. package/dist/lifecycle/release-images.d.ts +12 -3
  50. package/dist/lifecycle/release-images.d.ts.map +1 -1
  51. package/dist/lifecycle/release-images.js +6 -7
  52. package/dist/lifecycle/release-publish.d.ts +8 -1
  53. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  54. package/dist/lifecycle/release-publish.js +30 -3
  55. package/dist/lifecycle/release-version.d.ts +86 -0
  56. package/dist/lifecycle/release-version.d.ts.map +1 -0
  57. package/dist/lifecycle/release-version.js +209 -0
  58. package/dist/mcp/types.d.ts +26 -0
  59. package/dist/mcp/types.d.ts.map +1 -1
  60. package/dist/notify-product.d.ts.map +1 -1
  61. package/dist/notify-product.js +1 -2
  62. package/dist/op/activities/review-product.d.ts.map +1 -1
  63. package/dist/op/activities/review-product.js +1 -2
  64. package/dist/op/gate.d.ts +17 -0
  65. package/dist/op/gate.d.ts.map +1 -1
  66. package/dist/op/gate.js +36 -0
  67. package/dist/op/index.d.ts +8 -6
  68. package/dist/op/index.d.ts.map +1 -1
  69. package/dist/op/index.js +5 -4
  70. package/dist/op/op-waves-after-plan.d.ts +76 -1
  71. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  72. package/dist/op/op-waves-after-plan.js +142 -3
  73. package/dist/op/op-waves-capability-spec.js +1 -2
  74. package/dist/op/op-waves-capability.d.ts +89 -2
  75. package/dist/op/op-waves-capability.d.ts.map +1 -1
  76. package/dist/op/op-waves-capability.js +215 -7
  77. package/dist/op/op-waves-run-hooks.d.ts +104 -0
  78. package/dist/op/op-waves-run-hooks.d.ts.map +1 -0
  79. package/dist/op/op-waves-run-hooks.js +146 -0
  80. package/dist/op/op-waves-run.d.ts +21 -0
  81. package/dist/op/op-waves-run.d.ts.map +1 -1
  82. package/dist/op/op-waves-run.js +233 -13
  83. package/dist/op/op-waves.d.ts +11 -1
  84. package/dist/op/op-waves.d.ts.map +1 -1
  85. package/dist/op/op-waves.js +7 -1
  86. package/dist/op/runtime.d.ts +2 -0
  87. package/dist/op/runtime.d.ts.map +1 -1
  88. package/dist/pr-plan-note.d.ts.map +1 -1
  89. package/dist/pr-plan-note.js +1 -2
  90. package/dist/release-floors.d.ts +5 -1
  91. package/dist/release-floors.d.ts.map +1 -1
  92. package/dist/release-floors.js +9 -5
  93. package/dist/wave-runtime.mjs +314 -314
  94. package/dist/workspace/change-set.schema.json +7 -0
  95. package/dist/workspace/release-workflow.d.ts +7 -0
  96. package/dist/workspace/release-workflow.d.ts.map +1 -1
  97. package/dist/workspace/release-workflow.js +11 -1
  98. package/package.json +1 -1
  99. package/src/action-pins.test.ts +1 -2
  100. package/src/action-pins.ts +1 -3
  101. package/src/change-set.test.ts +20 -0
  102. package/src/change-set.ts +11 -1
  103. package/src/ci-agent.test.ts +9 -0
  104. package/src/ci-agent.ts +15 -2
  105. package/src/ci-commit.test.ts +2 -3
  106. package/src/ci-commit.ts +2 -3
  107. package/src/ci-product.ts +6 -2
  108. package/src/cli/handlers/release.ts +55 -2
  109. package/src/cli/handlers/run-wave.ts +1 -0
  110. package/src/cli/main.ts +7 -0
  111. package/src/cli/mcp/product-tools.test.ts +50 -0
  112. package/src/cli/mcp/product-tools.ts +8 -0
  113. package/src/cli/mcp/read-only.ts +19 -0
  114. package/src/cli/mcp/server.test.ts +30 -0
  115. package/src/cli/mcp/server.ts +28 -5
  116. package/src/cli/mcp/types.ts +6 -1
  117. package/src/components/capability.ts +41 -0
  118. package/src/components/group-digest.ts +20 -0
  119. package/src/components/groups.ts +3 -13
  120. package/src/components/index.ts +2 -0
  121. package/src/config.ts +15 -0
  122. package/src/lexicon.ts +1 -2
  123. package/src/lifecycle/release-cut.ts +11 -0
  124. package/src/lifecycle/release-images-dockerfile.test.ts +10 -2
  125. package/src/lifecycle/release-images.ts +12 -8
  126. package/src/lifecycle/release-publish.ts +34 -3
  127. package/src/lifecycle/release-version.test.ts +155 -0
  128. package/src/lifecycle/release-version.ts +227 -0
  129. package/src/mcp/types.ts +27 -0
  130. package/src/notify-message-words.test.ts +1 -2
  131. package/src/notify-product.ts +1 -2
  132. package/src/op/activities/review-product.ts +1 -2
  133. package/src/op/gate.ts +46 -0
  134. package/src/op/index.ts +10 -4
  135. package/src/op/op-waves-after-plan-wave.test.ts +226 -0
  136. package/src/op/op-waves-after-plan.ts +170 -5
  137. package/src/op/op-waves-capability-spec.ts +1 -1
  138. package/src/op/op-waves-capability.test.ts +6 -0
  139. package/src/op/op-waves-capability.ts +243 -10
  140. package/src/op/op-waves-run-hooks.test.ts +184 -0
  141. package/src/op/op-waves-run-hooks.ts +195 -0
  142. package/src/op/op-waves-run.ts +240 -16
  143. package/src/op/op-waves-step-wave.test.ts +277 -0
  144. package/src/op/op-waves.ts +15 -2
  145. package/src/op/runtime.ts +2 -0
  146. package/src/pr-plan-note.ts +1 -2
  147. package/src/release-floors.ts +11 -5
  148. package/src/workspace/change-set.schema.json +7 -0
  149. package/src/workspace/release-workflow.test.ts +18 -0
  150. package/src/workspace/release-workflow.ts +21 -1
@@ -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);
@@ -0,0 +1,184 @@
1
+ /**
2
+ * Run hooks in the wave job's process (#4842): a product gives each run its
3
+ * environment and checks, and acts before and after its apply, around
4
+ * chant's step.
5
+ */
6
+
7
+ import { describe, expect, test } from "vitest";
8
+ import { mkdtempSync, rmSync } from "node:fs";
9
+ import { join } from "node:path";
10
+ import { tmpdir } from "node:os";
11
+ import type { OpWavesSpec } from "./op-waves";
12
+ import { runOpWave, type OpWaveShowAtBase } from "./op-waves-run";
13
+ import { memoryGateLedgerPort } from "./gate";
14
+ import { CapabilityRegistry, type Capability, type DeployContext } from "../components/capability";
15
+ import type { ChangeSetPart } from "../change-set";
16
+ import type { OpRunRecordInput } from "./runtime";
17
+ import { opWaveRunHooksProblems, type OpWaveRunHookApplied, type OpWaveRunHooks } from "./op-waves-run-hooks";
18
+ import { activeProductWaveHook, withProductWaveHook } from "./op-waves-after-plan";
19
+
20
+ const digest = (n: string) => `sha256:${n.repeat(64)}`;
21
+
22
+ const part = (member: string): ChangeSetPart => ({
23
+ member: { member, lexicon: "terraform", planner: "chant", status: "planned", planDigest: digest("9"), holes: [] },
24
+ entries: [{ member, address: `aws_s3_bucket.${member}`, type: "aws_s3_bucket", action: "create" } as ChangeSetPart["entries"][number]],
25
+ });
26
+
27
+ interface Seen {
28
+ planned: Array<{ root: string; env?: Record<string, string> }>;
29
+ applied: Array<{ root: string; env?: Record<string, string> }>;
30
+ order: string[];
31
+ }
32
+
33
+ function capability(digests: Record<string, string>, fail: string[] = []): { registry: CapabilityRegistry; seen: Seen } {
34
+ const seen: Seen = { planned: [], applied: [], order: [] };
35
+ const cap: Capability<Record<string, unknown>, unknown> = {
36
+ kind: "fake-apply",
37
+ async plan(ctx: DeployContext, input) {
38
+ const root = String(input.root);
39
+ seen.order.push(`init ${root}`);
40
+ await ctx.afterInit?.();
41
+ seen.order.push(`plan ${root}`);
42
+ seen.planned.push({ root, ...(ctx.processEnv ? { env: ctx.processEnv } : {}) });
43
+ return { member: root, planDigest: digests[root]!, artifact: { planFile: `${root}.tfplan` }, changeSet: part(root) };
44
+ },
45
+ async run(ctx: DeployContext, input) {
46
+ const root = String(input.root);
47
+ seen.order.push(`apply ${root}`);
48
+ if (fail.includes(root)) throw new Error(`${root} did not apply`);
49
+ seen.applied.push({ root, ...(ctx.processEnv ? { env: ctx.processEnv } : {}) });
50
+ return { root, outputs: { id: `${root}-1` } };
51
+ },
52
+ };
53
+ return { registry: new CapabilityRegistry().register(cap), seen };
54
+ }
55
+
56
+ const spec: OpWavesSpec = {
57
+ name: "tf-apply",
58
+ op: "tf-apply",
59
+ step: { kind: "fake-apply", root: "{target}" },
60
+ waves: [{ name: "wave-1", runs: [{ target: "network" }, { target: "app" }], gate: "never" }],
61
+ };
62
+
63
+ const digests = { network: digest("1"), app: digest("2") };
64
+
65
+ function harness(s: OpWavesSpec = spec) {
66
+ const cwd = mkdtempSync(join(tmpdir(), "op-waves-run-hooks-"));
67
+ const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(s) });
68
+ return { cwd, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
69
+ }
70
+
71
+ const run = (h: ReturnType<typeof harness>, registry: CapabilityRegistry, runHooks: OpWaveRunHooks | OpWaveRunHooks[], extra: { runs?: { append: (r: OpRunRecordInput) => Promise<void> }; spec?: OpWavesSpec } = {}) =>
72
+ runOpWave({ spec: extra.spec ?? spec, specFile: "waves.json", wave: 1, cwd: h.cwd, show: h.show, gates: memoryGateLedgerPort(), capabilities: registry, log: () => {}, runHooks, ...(extra.runs ? { runs: extra.runs } : {}) });
73
+
74
+ describe("run hooks in the job's process (#4842)", () => {
75
+ test("a run's env reaches its plan and its apply, the later hook's value winning", async () => {
76
+ const h = harness();
77
+ const { registry, seen } = capability(digests);
78
+ const result = await run(h, registry, [
79
+ { name: "roles", beforePlan: (r) => ({ env: { AWS_ROLE_ARN: `arn:${r.target}`, TF_VAR_x: "a" } }) },
80
+ { name: "secrets", targets: ["app"], beforePlan: () => ({ env: { TF_VAR_x: "b" } }) },
81
+ ]);
82
+ expect(result.exitCode).toBe(0);
83
+ expect(seen.planned).toEqual([
84
+ { root: "network", env: { AWS_ROLE_ARN: "arn:network", TF_VAR_x: "a" } },
85
+ { root: "app", env: { AWS_ROLE_ARN: "arn:app", TF_VAR_x: "b" } },
86
+ ]);
87
+ expect(seen.applied).toEqual(seen.planned);
88
+ h.done();
89
+ });
90
+
91
+ test("a check after init runs between the engine's init and its plan, and a refusal there stops the wave", async () => {
92
+ const h = harness();
93
+ const { registry, seen } = capability(digests);
94
+ // A run that cannot be planned fails the job, as a plan that fails does.
95
+ await expect(run(h, registry, {
96
+ name: "sources",
97
+ beforePlan: (r) => ({
98
+ afterInit: () => {
99
+ seen.order.push(`check ${r.target}`);
100
+ if (r.target === "app") throw new Error("module git::https://example.com/m is not on the list at base");
101
+ },
102
+ }),
103
+ })).rejects.toThrow("planning app through fake-apply failed: the check after init of sources refused it: module git::https://example.com/m is not on the list at base");
104
+ expect(seen.order).toEqual(["init network", "check network", "plan network", "init app", "check app"]);
105
+ expect(seen.applied).toEqual([]);
106
+ h.done();
107
+ });
108
+
109
+ test("a refusal before the plan stops the run before its engine starts, and nothing applies", async () => {
110
+ const h = harness();
111
+ const { registry, seen } = capability(digests);
112
+ await expect(run(h, registry, { name: "sources", beforePlan: (r) => (r.target === "network" ? { refuse: "a module source outside the list at base" } : undefined) }))
113
+ .rejects.toThrow("network was not planned: the before-plan hook sources refused it: a module source outside the list at base");
114
+ expect(seen.order).toEqual([]);
115
+ h.done();
116
+ });
117
+
118
+ test("a before-apply hook that throws fails its run, and the others apply", async () => {
119
+ const h = harness();
120
+ const { registry, seen } = capability(digests);
121
+ const result = await run(h, registry, { name: "steps", beforeApply: (r) => { if (r.target === "network") throw new Error("tflint failed"); } });
122
+ expect(result.exitCode).toBe(1);
123
+ expect(result.failed).toEqual(["network"]);
124
+ expect(result.applied).toEqual(["app"]);
125
+ expect(seen.order).not.toContain("apply network");
126
+ expect(result.targets?.network?.error).toContain("the before-apply hook steps failed, so nothing of it was applied: tflint failed");
127
+ h.done();
128
+ });
129
+
130
+ test("an after-apply hook sees each outcome and output, its files go on the run record, and a throw after an apply fails the run", async () => {
131
+ const h = harness();
132
+ const { registry } = capability(digests, ["app"]);
133
+ const got: OpWaveRunHookApplied[] = [];
134
+ const records: OpRunRecordInput[] = [];
135
+ const result = await run(h, registry, { name: "report", afterApply: (r) => (got.push(r), { files: [`states/${r.target}.json`] }) }, { runs: { append: async (r) => void records.push(r) } });
136
+ expect(got.map((r) => [r.target, r.outcome, r.planDigest])).toEqual([["network", "applied", digests.network], ["app", "failed", digests.app]]);
137
+ expect(got[0]!.output).toEqual({ root: "network", outputs: { id: "network-1" } });
138
+ expect(got[1]!.reason).toContain("app did not apply");
139
+ expect(result.exitCode).toBe(1);
140
+ expect(records[0]!.wave!.targets?.network?.files).toEqual(["states/network.json"]);
141
+
142
+ const again = harness();
143
+ const ok = capability(digests);
144
+ const thrown = await run(again, ok.registry, { name: "versions", targets: ["app"], afterApply: () => { throw new Error("the state version could not be read"); } });
145
+ expect(thrown.exitCode).toBe(1);
146
+ expect(thrown.applied).toEqual(["network"]);
147
+ expect(thrown.failed).toEqual(["app"]);
148
+ expect(thrown.targets?.app?.error).toContain("the after-apply hook versions failed: the state version could not be read");
149
+ h.done();
150
+ again.done();
151
+ });
152
+
153
+ test("runs applied at once take their hooks too", async () => {
154
+ const wide: OpWavesSpec = { ...spec, parallelism: 2 };
155
+ const h = harness(wide);
156
+ const { registry, seen } = capability(digests);
157
+ const after: string[] = [];
158
+ const result = await run(h, registry, { name: "roles", beforePlan: (r) => ({ env: { ROLE: r.target } }), afterApply: (r) => void after.push(r.target) }, { spec: wide });
159
+ expect(result.exitCode).toBe(0);
160
+ expect(seen.applied.map((a) => a.env)).toEqual([{ ROLE: "network" }, { ROLE: "app" }]);
161
+ expect(after.sort()).toEqual(["app", "network"]);
162
+ h.done();
163
+ });
164
+
165
+ test("a product's wave hook hands its run hooks to the job", async () => {
166
+ const hook = { runHooks: { name: "x", beforePlan: () => {} } };
167
+ await withProductWaveHook(hook, async () => expect(activeProductWaveHook()?.runHooks).toBe(hook.runHooks));
168
+ });
169
+
170
+ test("the hook list is checked", async () => {
171
+ expect(opWaveRunHooksProblems({ name: "", beforePlan: 1 })).toEqual(["runHooks[0] needs a name", "runHooks[0].beforePlan must be a function"]);
172
+ expect(opWaveRunHooksProblems([{ name: "x" }])).toEqual(["runHooks[0] gives none of beforePlan, beforeApply and afterApply"]);
173
+ const h = harness();
174
+ const { registry } = capability(digests);
175
+ await expect(run(h, registry, { name: "" } as OpWaveRunHooks)).rejects.toThrow(/runHooks\[0\] needs a name/);
176
+ h.done();
177
+ });
178
+
179
+ test("the floor is the next release", async () => {
180
+ const entry = await import("./index");
181
+ const { NEXT_RELEASE } = await import("../release-floors");
182
+ expect(entry.OP_WAVE_RUN_HOOKS_FLOOR).toBe(NEXT_RELEASE);
183
+ });
184
+ });