@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
@@ -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
@@ -58,6 +75,8 @@ import { dirname, join } from "node:path";
58
75
  import { isPlanMovedError } from "../components/capability.js";
59
76
  import { composeChangeSet } from "../change-set.js";
60
77
  import { computePlanDigest } from "../lifecycle/plan-digest.js";
78
+ import { groupDigest } from "../components/group-digest.js";
79
+ import { NEXT_RELEASE } from "../release-floors.js";
61
80
  import { resolvePlannedLock } from "../lifecycle/lock-rows.js";
62
81
  import { OP_WAVE_COST_MEMBER } from "./op-waves-capability-spec.js";
63
82
  export { OP_WAVE_COST_FORMATS, OP_WAVE_COST_MEMBER, opWaveHoldsAt, opWaveHoldsProblems, opWaveStepProblems } from "./op-waves-capability-spec.js";
@@ -79,6 +98,13 @@ export function opWaveStepInput(spec, wave, run) {
79
98
  const vars = { target: run.target, op: run.op ?? spec.op, wave: wave.name };
80
99
  return { ...fill(rest, vars), ...(run.input ? fill(run.input, vars) : {}) };
81
100
  }
101
+ /** The input `discoverRuns` gets (#4842): the spec's step with `{op}` and `{wave}` filled and `{target}` left as written. */
102
+ export function opWaveDiscoverInput(spec, wave) {
103
+ if (!spec.step)
104
+ throw new Error("the spec names no step");
105
+ const { kind: _kind, ...rest } = spec.step;
106
+ return fill(rest, { target: "{target}", op: spec.op, wave: wave.name });
107
+ }
82
108
  /** 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. */
83
109
  export function opWaveStepContext(spec, wave, run) {
84
110
  return { env: spec.labels?.Env ?? wave.name, component: run.target };
@@ -99,12 +125,16 @@ export function opWaveRegistry(key, cwd, given) {
99
125
  }
100
126
  return found;
101
127
  }
102
- /** Whether a part changes nothing, and whether it destroys or replaces something. */
128
+ /** The digest member a wave planned `together` adds (#4842): no run has this name. */
129
+ export const OP_WAVE_TOGETHER_MEMBER = "(wave plan)";
130
+ /** The release that has `discover` with a `step`, and `together` waves (#4842). */
131
+ export const OP_WAVE_STEP_WAVE_FLOOR = NEXT_RELEASE;
132
+ /** Whether a part changes nothing, and whether it destroys or replaces something. A plan that changes only outputs changes something (#4849). */
103
133
  export function partEffects(part) {
104
134
  if (!part)
105
135
  return { empty: false, destructive: false };
106
136
  const changing = part.entries.filter((e) => e.action !== "no-op" && e.action !== "read");
107
- return { empty: changing.length === 0, destructive: changing.some((e) => e.action === "delete" || e.action === "replace") };
137
+ return { empty: changing.length === 0 && (part.member.outputs?.length ?? 0) === 0, destructive: changing.some((e) => e.action === "delete" || e.action === "replace") };
108
138
  }
109
139
  function resolveCapability(registry, kind) {
110
140
  if (!registry.has(kind))
@@ -121,7 +151,8 @@ export async function planOpWaveStep(at, run) {
121
151
  let planned;
122
152
  let lock;
123
153
  try {
124
- planned = await capability.plan({ ...opWaveStepContext(spec, wave, run), ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}), ...(at.policyBase ? { policyBase: at.policyBase } : {}) }, input);
154
+ // #4842: the run hooks' environment and check after init.
155
+ 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);
125
156
  // #4552: the run's grain (declared at base, else its lexicon's) and, on the resource grain, the rows its apply leases.
126
157
  lock = await resolvePlannedLock(capability, input, planned, at.lockGrain);
127
158
  }
@@ -148,11 +179,15 @@ export async function planOpWaveStep(at, run) {
148
179
  ...effects,
149
180
  lock,
150
181
  };
151
- const file = join(cwd, at.planPath);
182
+ writeStepPlanFile(join(cwd, at.planPath), plan);
183
+ return plan;
184
+ }
185
+ /** A run's plan file, as a per-run `plan` command writes it: its digest, effects, member, artifact (when it is JSON) and part. */
186
+ function writeStepPlanFile(file, plan) {
152
187
  mkdirSync(dirname(file), { recursive: true });
153
188
  let artifact;
154
189
  try {
155
- artifact = planned.artifact === undefined ? undefined : JSON.parse(JSON.stringify(planned.artifact));
190
+ artifact = plan.artifact === undefined ? undefined : JSON.parse(JSON.stringify(plan.artifact));
156
191
  }
157
192
  catch {
158
193
  artifact = undefined;
@@ -165,7 +200,180 @@ export async function planOpWaveStep(at, run) {
165
200
  ...(artifact !== undefined ? { artifact } : {}),
166
201
  ...(plan.part ? { changeSet: plan.part } : {}),
167
202
  }) + "\n");
168
- return plan;
203
+ }
204
+ /**
205
+ * The runs of a `discover` wave through the spec's step (#4842): what the
206
+ * capability's `discoverRuns` finds for wave `k`, each a run of the spec's
207
+ * op, and how many waves it found.
208
+ */
209
+ export async function discoverOpWaveStepRuns(at) {
210
+ const { spec, wave, k } = at;
211
+ const kind = spec.step.kind;
212
+ const capability = resolveCapability(at.registry, kind);
213
+ if (!capability.discoverRuns)
214
+ throw new Error(`wave ${k} (${wave.name}) discovers its runs, and the capability "${kind}" cannot find them (it has no discoverRuns)`);
215
+ let found;
216
+ try {
217
+ found = await capability.discoverRuns({ env: spec.labels?.Env ?? wave.name, wave: { name: wave.name, number: k } }, opWaveDiscoverInput(spec, wave));
218
+ }
219
+ catch (err) {
220
+ throw new Error(`finding the runs of wave ${k} (${wave.name}) through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
221
+ }
222
+ const targets = found?.targets;
223
+ if (!Array.isArray(targets) || !targets.every((t) => typeof t === "string" && t !== ""))
224
+ throw new Error(`${kind} found the runs of wave ${k} (${wave.name}) as ${JSON.stringify(targets)}; give a list of targets`);
225
+ const dup = targets.find((t, i) => targets.indexOf(t) !== i);
226
+ if (dup !== undefined)
227
+ throw new Error(`${kind} found ${dup} twice in wave ${k} (${wave.name})`);
228
+ const waves = found.waves;
229
+ if (waves !== undefined && (typeof waves !== "number" || !Number.isInteger(waves) || waves < 0))
230
+ throw new Error(`${kind} found ${JSON.stringify(waves)} waves for wave ${k} (${wave.name}); give a whole number`);
231
+ return { runs: targets.map((target) => ({ target })), ...(waves !== undefined ? { waves: waves } : {}) };
232
+ }
233
+ /** The group members of a wave's runs (#4842): each run's filled input, its `dependsOn` within the wave, and its own context. */
234
+ function waveGroupMembers(spec, wave, runs, ctxOf) {
235
+ const inWave = new Set(runs.map((r) => r.target));
236
+ return runs.map((run) => {
237
+ const input = opWaveStepInput(spec, wave, run);
238
+ const dependsOn = (run.dependsOn ?? []).filter((d) => inWave.has(d));
239
+ return { component: run.target, step: input, input, reads: [], ...(dependsOn.length > 0 ? { dependsOn } : {}), ctx: ctxOf(run) };
240
+ });
241
+ }
242
+ function waveGroupContext(spec, wave, runs) {
243
+ return { env: spec.labels?.Env ?? wave.name, components: runs.map((r) => r.target) };
244
+ }
245
+ function requireGroup(capability, kind, wave) {
246
+ if (!capability.planGroup || !capability.runGroup)
247
+ throw new Error(`wave "${wave.name}" plans its runs together, and the capability "${kind}" cannot (it needs planGroup and runGroup)`);
248
+ }
249
+ /**
250
+ * Plan a `together` wave's runs in one `planGroup` call (#4842), writing
251
+ * each run's plan file at `planPath(target)` (relative to `cwd`). Each run's
252
+ * plan carries the group. Throws when the call does or leaves a run out, and
253
+ * on a run's plan as {@link planOpWaveStep} does.
254
+ */
255
+ export async function planOpWaveStepGroup(at, runs) {
256
+ const { spec, wave } = at;
257
+ const kind = spec.step.kind;
258
+ const capability = resolveCapability(at.registry, kind);
259
+ requireGroup(capability, kind, wave);
260
+ const members = waveGroupMembers(spec, wave, runs, (run) => {
261
+ const own = at.runCtx?.(run.target) ?? {};
262
+ return {
263
+ ...opWaveStepContext(spec, wave, run),
264
+ ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}),
265
+ ...(at.policyBase ? { policyBase: at.policyBase } : {}),
266
+ ...(own.processEnv ? { processEnv: own.processEnv } : {}),
267
+ ...(own.afterInit ? { afterInit: own.afterInit } : {}),
268
+ };
269
+ });
270
+ let planned;
271
+ try {
272
+ planned = await capability.planGroup(waveGroupContext(spec, wave, runs), members);
273
+ }
274
+ catch (err) {
275
+ throw new Error(`planning wave "${wave.name}" together through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
276
+ }
277
+ if (typeof planned?.digest !== "string" || planned.digest === "")
278
+ throw new Error(`${kind} planned wave "${wave.name}" together with no digest of the whole`);
279
+ const own = new Map();
280
+ for (const run of runs) {
281
+ const p = planned.members?.[run.target];
282
+ if (!p)
283
+ throw new Error(`${kind} planned wave "${wave.name}" together without a plan for ${run.target}`);
284
+ own.set(run.target, p);
285
+ }
286
+ const digest = groupDigest(kind, runs.map((r) => ({ component: r.target, member: own.get(r.target).member, planDigest: own.get(r.target).planDigest })), planned.digest);
287
+ const group = { digest, ...(planned.artifact !== undefined ? { artifact: planned.artifact } : {}), plans: Object.fromEntries(own) };
288
+ const out = [];
289
+ for (const [i, run] of runs.entries()) {
290
+ const p = own.get(run.target);
291
+ if (typeof p.planDigest !== "string" || p.planDigest === "")
292
+ throw new Error(`${kind} planned ${run.target} with no plan digest`);
293
+ const holes = p.changeSet?.member.holes ?? [];
294
+ if (holes.length > 0 && p.artifact === undefined && planned.artifact === undefined)
295
+ throw new Error(`${run.target} was not planned: ${holes.map((h) => h.reason).join("; ")}`);
296
+ const effects = partEffects(p.changeSet);
297
+ if ((p.destructive?.length ?? 0) > 0)
298
+ effects.destructive = true;
299
+ let lock;
300
+ try {
301
+ lock = await resolvePlannedLock(capability, members[i].input, p, at.lockGrain);
302
+ }
303
+ catch (err) {
304
+ throw new Error(`planning ${run.target} through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
305
+ }
306
+ const plan = {
307
+ target: run.target,
308
+ member: p.member,
309
+ planDigest: p.planDigest,
310
+ ...(p.resourceDigests ? { resources: p.resourceDigests } : {}),
311
+ ...(p.artifact !== undefined ? { artifact: p.artifact } : {}),
312
+ ...(p.changeSet ? { part: p.changeSet } : {}),
313
+ ...effects,
314
+ lock,
315
+ group,
316
+ };
317
+ writeStepPlanFile(join(at.cwd, at.planPath(run.target)), plan);
318
+ out.push(plan);
319
+ }
320
+ return out;
321
+ }
322
+ /**
323
+ * Apply a `together` wave's runs in one `runGroup` call (#4842), with the
324
+ * plan the gate decided. Each run's outcome, in the order given: `applied`
325
+ * and `no-changes` applied, with the member's outputs; `partial`, `failed`
326
+ * and `not-started` failed. A throw fails every run, or moves every run
327
+ * when it is a moved plan (`isPlanMovedError`).
328
+ */
329
+ export async function applyOpWaveStepGroup(at, runs) {
330
+ const { spec, wave } = at;
331
+ const kind = spec.step.kind;
332
+ let capability;
333
+ try {
334
+ capability = resolveCapability(at.registry, kind);
335
+ requireGroup(capability, kind, wave);
336
+ }
337
+ catch (err) {
338
+ const reason = err instanceof Error ? err.message : String(err);
339
+ return runs.map(() => ({ outcome: "failed", reason }));
340
+ }
341
+ const group = runs[0]?.plan.group;
342
+ if (!group || runs.some((r) => r.plan.group !== group))
343
+ return runs.map(() => ({ outcome: "failed", reason: `the runs of wave "${wave.name}" were not planned together, so they cannot apply together` }));
344
+ const byTarget = new Map(runs.map((r) => [r.run.target, r.plan]));
345
+ const members = waveGroupMembers(spec, wave, runs.map((r) => r.run), (run) => {
346
+ const plan = byTarget.get(run.target);
347
+ const env = at.runEnv?.(run.target);
348
+ return { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
349
+ });
350
+ const plans = Object.fromEntries(runs.flatMap((r) => (group.plans[r.run.target] ? [[r.run.target, group.plans[r.run.target]]] : [])));
351
+ let got;
352
+ try {
353
+ got = await capability.runGroup(waveGroupContext(spec, wave, runs.map((r) => r.run)), { ...(group.artifact !== undefined ? { artifact: group.artifact } : {}), digest: group.digest, plans }, members);
354
+ }
355
+ catch (err) {
356
+ const reason = err instanceof Error ? err.message : String(err);
357
+ const moved = isPlanMovedError(err);
358
+ return Promise.all(runs.map(async (r, i) => {
359
+ const facts = await opWaveStepFacts(capability, members[i].input, r.plan, { error: err });
360
+ return { ...(moved ? { outcome: "moved", reason } : { outcome: "failed", reason }), ...(facts ? { facts } : {}) };
361
+ }));
362
+ }
363
+ return Promise.all(runs.map(async (r, i) => {
364
+ const o = got?.members?.[r.run.target];
365
+ const input = members[i].input;
366
+ if (o && (o.status === "applied" || o.status === "no-changes")) {
367
+ const output = { status: o.status, ...(o.outputs ? { outputs: o.outputs } : {}) };
368
+ const facts = await opWaveStepFacts(capability, input, r.plan, { output });
369
+ return { outcome: "applied", output, ...(facts ? { facts } : {}) };
370
+ }
371
+ 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`;
372
+ const why = o?.error ?? got?.error;
373
+ const reason = `${what}${why ? `: ${why}` : ""}`;
374
+ const facts = await opWaveStepFacts(capability, input, r.plan, { error: new Error(reason) });
375
+ return { outcome: "failed", reason, ...(facts ? { facts } : {}) };
376
+ }));
169
377
  }
170
378
  /**
171
379
  * A step's facts for its span and run record (#4555): the plan's resource
@@ -198,7 +406,7 @@ export async function applyOpWaveStep(at, run, plan) {
198
406
  catch (err) {
199
407
  return { outcome: "failed", reason: err instanceof Error ? err.message : String(err) };
200
408
  }
201
- const ctx = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}) };
409
+ const ctx = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}) };
202
410
  const input = opWaveStepInput(spec, wave, run);
203
411
  try {
204
412
  const output = await capability.run(ctx, input);
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Run hooks in the wave job's process (#4842): what a product does around
3
+ * each run of a wave with a `step`, beside its after-plan hooks
4
+ * (`./op-waves-after-plan.ts`). A product that runs chant in process
5
+ * (`runOpWave`, or a bin built on `runChantInProcess`) passes `runHooks`.
6
+ *
7
+ * - `beforePlan` is called before the run's step plans. Its answer can give
8
+ * the run an `env`, the environment variables its engine plans and
9
+ * applies with over the job's (a role's credentials, values read from a
10
+ * secret store), and an `afterInit` check, which the capability calls
11
+ * once its engine has initialised the run and before the plan runs any of
12
+ * the run's code (a module and provider source check). `refuse` stops the
13
+ * run before its engine starts: the wave then plans nothing more and
14
+ * applies nothing, as a run whose plan failed.
15
+ * - `beforeApply` is called before the run's step applies the plan the gate
16
+ * decided. A hook that throws fails the run, and nothing of it applies.
17
+ * - `afterApply` is called once the step's apply came back, whatever the
18
+ * outcome, with the capability's output when it applied. Its `files` go
19
+ * on the run record beside the run's apply. A hook that throws after an
20
+ * apply fails the run, as an after-apply command hook does.
21
+ *
22
+ * Several hooks run in the order given. Their `env` values are laid over one
23
+ * another, the later winning. `targets` limits a hook to the runs it
24
+ * matches, as for a command hook. A wave whose spec names no `step` has no
25
+ * plan or apply of chant's to run them around, so they are not called.
26
+ */
27
+ /** The first chant that runs a product's `runHooks` around each run of a wave with a `step` (#4842), and hands its `env` and `afterInit` to the capability (`DeployContext.processEnv`, `DeployContext.afterInit`). */
28
+ export declare const OP_WAVE_RUN_HOOKS_FLOOR = "0.124.79";
29
+ /** One run of a wave, as a run hook sees it (#4842). */
30
+ export interface OpWaveRunHookRun {
31
+ /** The spec's name and `op`. */
32
+ spec: string;
33
+ op: string;
34
+ wave: number;
35
+ waveName: string;
36
+ /** The job: `wave` for a whole wave, `decide` for a wide wave's deciding job, `share` or `group` for its apply jobs. */
37
+ job: "wave" | "decide" | "share" | "group";
38
+ target: string;
39
+ /** The run's own op. */
40
+ runOp: string;
41
+ /** The job's directory. */
42
+ cwd: string;
43
+ }
44
+ /** A planned run, as `beforeApply` and `afterApply` see it. */
45
+ export interface OpWaveRunHookPlanned extends OpWaveRunHookRun {
46
+ planDigest: string;
47
+ /** The run's plan file, relative to the job's directory: `{plan}`. */
48
+ plan: string;
49
+ /** The capability's artifact. */
50
+ artifact?: unknown;
51
+ }
52
+ /** An applied run, as `afterApply` sees it. */
53
+ export interface OpWaveRunHookApplied extends OpWaveRunHookPlanned {
54
+ outcome: "applied" | "moved" | "failed";
55
+ /** The capability's output, when it applied. */
56
+ output?: unknown;
57
+ /** Why it did not apply. */
58
+ reason?: string;
59
+ }
60
+ /** What `beforePlan` gives a run. */
61
+ export interface OpWaveBeforePlanResult {
62
+ /** Environment variables the run's engine plans and applies with, over the job's. */
63
+ env?: Record<string, string>;
64
+ /** A check the capability calls after its engine's init and before its plan. It throws to stop the run. */
65
+ afterInit?: () => void | Promise<void>;
66
+ /** Why the run is not planned at all. */
67
+ refuse?: string;
68
+ }
69
+ /** What `afterApply` adds to a run. */
70
+ export interface OpWaveAfterApplyResult {
71
+ /** Files the hook wrote for the run, relative to the job's directory. They go on the run record. */
72
+ files?: string[];
73
+ }
74
+ /** Hooks around each run of a wave with a `step`, in the job's process (#4842). */
75
+ export interface OpWaveRunHooks {
76
+ /** The hook's name in the log. */
77
+ name: string;
78
+ /** The runs it is for, as a command hook's `targets`. Default: every run. */
79
+ targets?: string[];
80
+ beforePlan?(run: OpWaveRunHookRun): OpWaveBeforePlanResult | void | Promise<OpWaveBeforePlanResult | void>;
81
+ beforeApply?(run: OpWaveRunHookPlanned): void | Promise<void>;
82
+ afterApply?(run: OpWaveRunHookApplied): OpWaveAfterApplyResult | void | Promise<OpWaveAfterApplyResult | void>;
83
+ }
84
+ /** What is wrong with `runHooks`, empty when nothing is. */
85
+ export declare function opWaveRunHooksProblems(hooks: unknown): string[];
86
+ /** The hooks as a list. */
87
+ export declare function opWaveRunHookList(given: OpWaveRunHooks | readonly OpWaveRunHooks[] | undefined): readonly OpWaveRunHooks[];
88
+ /** What the `beforePlan` hooks gave one run. */
89
+ export type OpWaveBeforePlanOutcome = {
90
+ refused: string;
91
+ } | {
92
+ env?: Record<string, string>;
93
+ afterInit?: () => Promise<void>;
94
+ };
95
+ /** Call each hook's `beforePlan` for `run`, in order. A hook that throws or refuses stops the rest and refuses the run. */
96
+ export declare function runOpWaveBeforePlan(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookRun): Promise<OpWaveBeforePlanOutcome>;
97
+ /** Call each hook's `beforeApply` for `run`. Returns why the run must not apply, or undefined. */
98
+ export declare function runOpWaveBeforeApply(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookPlanned): Promise<string | undefined>;
99
+ /** Call each hook's `afterApply` for `run`: the files they wrote, and why the run fails when one threw or answered badly. */
100
+ export declare function runOpWaveAfterApply(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookApplied): Promise<{
101
+ files: string[];
102
+ failed?: string;
103
+ }>;
104
+ //# sourceMappingURL=op-waves-run-hooks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"op-waves-run-hooks.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-run-hooks.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,146 @@
1
+ /**
2
+ * Run hooks in the wave job's process (#4842): what a product does around
3
+ * each run of a wave with a `step`, beside its after-plan hooks
4
+ * (`./op-waves-after-plan.ts`). A product that runs chant in process
5
+ * (`runOpWave`, or a bin built on `runChantInProcess`) passes `runHooks`.
6
+ *
7
+ * - `beforePlan` is called before the run's step plans. Its answer can give
8
+ * the run an `env`, the environment variables its engine plans and
9
+ * applies with over the job's (a role's credentials, values read from a
10
+ * secret store), and an `afterInit` check, which the capability calls
11
+ * once its engine has initialised the run and before the plan runs any of
12
+ * the run's code (a module and provider source check). `refuse` stops the
13
+ * run before its engine starts: the wave then plans nothing more and
14
+ * applies nothing, as a run whose plan failed.
15
+ * - `beforeApply` is called before the run's step applies the plan the gate
16
+ * decided. A hook that throws fails the run, and nothing of it applies.
17
+ * - `afterApply` is called once the step's apply came back, whatever the
18
+ * outcome, with the capability's output when it applied. Its `files` go
19
+ * on the run record beside the run's apply. A hook that throws after an
20
+ * apply fails the run, as an after-apply command hook does.
21
+ *
22
+ * Several hooks run in the order given. Their `env` values are laid over one
23
+ * another, the later winning. `targets` limits a hook to the runs it
24
+ * matches, as for a command hook. A wave whose spec names no `step` has no
25
+ * plan or apply of chant's to run them around, so they are not called.
26
+ */
27
+ import { isAbsolute } from "node:path";
28
+ import { NEXT_RELEASE } from "../release-floors.js";
29
+ import { opWaveHookRuns } from "./op-waves.js";
30
+ /** The first chant that runs a product's `runHooks` around each run of a wave with a `step` (#4842), and hands its `env` and `afterInit` to the capability (`DeployContext.processEnv`, `DeployContext.afterInit`). */
31
+ export const OP_WAVE_RUN_HOOKS_FLOOR = NEXT_RELEASE;
32
+ /** What is wrong with `runHooks`, empty when nothing is. */
33
+ export function opWaveRunHooksProblems(hooks) {
34
+ if (hooks === undefined)
35
+ return [];
36
+ const list = Array.isArray(hooks) ? hooks : [hooks];
37
+ const problems = [];
38
+ list.forEach((h, i) => {
39
+ const at = `runHooks[${i}]`;
40
+ const hook = h;
41
+ if (!hook || typeof hook !== "object")
42
+ return void problems.push(`${at} must be { name, beforePlan?, beforeApply?, afterApply?, targets? }`);
43
+ if (typeof hook.name !== "string" || hook.name.trim() === "")
44
+ problems.push(`${at} needs a name`);
45
+ const moments = ["beforePlan", "beforeApply", "afterApply"].filter((m) => hook[m] !== undefined);
46
+ if (moments.length === 0)
47
+ problems.push(`${at} gives none of beforePlan, beforeApply and afterApply`);
48
+ for (const m of moments)
49
+ if (typeof hook[m] !== "function")
50
+ problems.push(`${at}.${m} must be a function`);
51
+ if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== "")))
52
+ problems.push(`${at}.targets must be a non-empty list of targets or patterns`);
53
+ });
54
+ return problems;
55
+ }
56
+ /** The hooks as a list. */
57
+ export function opWaveRunHookList(given) {
58
+ if (given === undefined)
59
+ return [];
60
+ return Array.isArray(given) ? given : [given];
61
+ }
62
+ const forRun = (hook, run) => opWaveHookRuns(hook, [run]).length > 0;
63
+ /** Call each hook's `beforePlan` for `run`, in order. A hook that throws or refuses stops the rest and refuses the run. */
64
+ export async function runOpWaveBeforePlan(hooks, run) {
65
+ let env;
66
+ const checks = [];
67
+ for (const hook of hooks) {
68
+ if (!hook.beforePlan || !forRun(hook, run))
69
+ continue;
70
+ let answer;
71
+ try {
72
+ answer = await hook.beforePlan(run);
73
+ }
74
+ catch (err) {
75
+ return { refused: `the before-plan hook ${hook.name} failed: ${err instanceof Error ? err.message : String(err)}` };
76
+ }
77
+ if (!answer)
78
+ continue;
79
+ if (answer.refuse !== undefined)
80
+ return { refused: `the before-plan hook ${hook.name} refused it: ${answer.refuse}` };
81
+ if (answer.env !== undefined) {
82
+ const bad = typeof answer.env !== "object" || answer.env === null || Array.isArray(answer.env) || !Object.values(answer.env).every((v) => typeof v === "string");
83
+ if (bad)
84
+ return { refused: `the before-plan hook ${hook.name} answered with an env that is not a map of names to strings` };
85
+ env = { ...env, ...answer.env };
86
+ }
87
+ if (answer.afterInit !== undefined) {
88
+ if (typeof answer.afterInit !== "function")
89
+ return { refused: `the before-plan hook ${hook.name} answered with an afterInit that is not a function` };
90
+ const name = hook.name;
91
+ const check = answer.afterInit;
92
+ checks.push(async () => {
93
+ try {
94
+ await check();
95
+ }
96
+ catch (err) {
97
+ throw new Error(`the check after init of ${name} refused it: ${err instanceof Error ? err.message : String(err)}`);
98
+ }
99
+ });
100
+ }
101
+ }
102
+ return {
103
+ ...(env ? { env } : {}),
104
+ ...(checks.length > 0 ? { afterInit: async () => { for (const c of checks)
105
+ await c(); } } : {}),
106
+ };
107
+ }
108
+ /** Call each hook's `beforeApply` for `run`. Returns why the run must not apply, or undefined. */
109
+ export async function runOpWaveBeforeApply(hooks, run) {
110
+ for (const hook of hooks) {
111
+ if (!hook.beforeApply || !forRun(hook, run))
112
+ continue;
113
+ try {
114
+ await hook.beforeApply(run);
115
+ }
116
+ catch (err) {
117
+ return `the before-apply hook ${hook.name} failed, so nothing of it was applied: ${err instanceof Error ? err.message : String(err)}`;
118
+ }
119
+ }
120
+ return undefined;
121
+ }
122
+ /** Call each hook's `afterApply` for `run`: the files they wrote, and why the run fails when one threw or answered badly. */
123
+ export async function runOpWaveAfterApply(hooks, run) {
124
+ const files = [];
125
+ for (const hook of hooks) {
126
+ if (!hook.afterApply || !forRun(hook, run))
127
+ continue;
128
+ let answer;
129
+ try {
130
+ answer = await hook.afterApply(run);
131
+ }
132
+ catch (err) {
133
+ return { files, failed: `the after-apply hook ${hook.name} failed: ${err instanceof Error ? err.message : String(err)}` };
134
+ }
135
+ const given = answer?.files;
136
+ if (given === undefined)
137
+ continue;
138
+ if (!Array.isArray(given) || !given.every((f) => typeof f === "string" && f !== "" && !isAbsolute(f) && !f.split("/").includes(".."))) {
139
+ return { files, failed: `the after-apply hook ${hook.name} answered with files that are not paths inside the job's directory` };
140
+ }
141
+ for (const f of given)
142
+ if (!files.includes(f))
143
+ files.push(f);
144
+ }
145
+ return { files };
146
+ }
@@ -58,6 +58,7 @@ import type { HeadPlans, ReviewSource } from "./gate-review.js";
58
58
  import type { TrustPolicy } from "../workspace/trust/policy.js";
59
59
  import type { GateSigners } from "../lifecycle/gate-seal.js";
60
60
  import type { OpRunRecordInput, OpRunWavePlan, OpRunWaveTarget } from "./runtime.js";
61
+ import { type OpWaveRunHooks } from "./op-waves-run-hooks.js";
61
62
  import { type OpWaveAfterPlanHook } from "./op-waves-after-plan.js";
62
63
  import { type OtlpExporter } from "../otlp.js";
63
64
  import { type RunEventSink } from "../run-event-stream.js";
@@ -191,6 +192,8 @@ export interface OpWaveMember extends WaveMember {
191
192
  rules: string[];
192
193
  reason?: string;
193
194
  };
195
+ /** Who may override this run's denial (#4842), from an after-plan hook, in place of the wave's overriders. */
196
+ overriders?: string[];
194
197
  }
195
198
  /** Where a wave's policy came from. */
196
199
  export type OpWavePolicySource = "base" | "absent-at-base";
@@ -316,6 +319,15 @@ export interface OpWaveDecision {
316
319
  overridesSpentAt?: string;
317
320
  /** Digest members that are no run, from the plans file (#3821), such as the wave's cost. */
318
321
  extras?: WaveMember[];
322
+ /**
323
+ * After an approval of other plans (#4842): the after-plan hook's report of
324
+ * the plans now and the one stored for the plans approved, written for the
325
+ * job that explains the refusal. Paths relative to the job's directory.
326
+ */
327
+ reports?: {
328
+ current: string;
329
+ approved?: string;
330
+ };
319
331
  /** On a discovering wave (#3821): how many waves the plan command found. */
320
332
  discovered?: {
321
333
  waves?: number;
@@ -662,6 +674,13 @@ export interface RunOpWaveOptions {
662
674
  * files go on the run record. See `./op-waves-after-plan.ts`.
663
675
  */
664
676
  afterPlan?: OpWaveAfterPlanHook | readonly OpWaveAfterPlanHook[];
677
+ /**
678
+ * Hooks around each run of a wave with a `step`, in the job's own process
679
+ * (#4842): `beforePlan` gives a run its engine's environment and a check
680
+ * after init, or refuses it; `beforeApply` and `afterApply` run around
681
+ * its apply. See `./op-waves-run-hooks.ts`.
682
+ */
683
+ runHooks?: OpWaveRunHooks | readonly OpWaveRunHooks[];
665
684
  /**
666
685
  * How the spec's command hooks run (#4614), when they call back into the
667
686
  * caller's own process: a product that runs the wave in process and serves
@@ -809,6 +828,8 @@ export declare function opWaveRunRecord(options: Pick<RunOpWaveOptions, "spec" |
809
828
  }): OpRunRecordInput;
810
829
  /** How many times one wave job plans again when its apply asks to (#3821). */
811
830
  export declare const OP_WAVE_MAX_REPLANS = 10;
831
+ /** Where a wave's reports go for the job that explains a moved approval (#4842), relative to the job's directory. */
832
+ export declare function opWaveReportDir(spec: Pick<OpWavesSpec, "name">, k: number): string;
812
833
  export interface RecordHeadPlansOptions {
813
834
  spec: OpWavesSpec;
814
835
  cwd?: string;