@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
@@ -0,0 +1,195 @@
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
+
28
+ import { isAbsolute } from "node:path";
29
+ import { NEXT_RELEASE } from "../release-floors";
30
+ import { opWaveHookRuns } from "./op-waves";
31
+
32
+ /** 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`). */
33
+ export const OP_WAVE_RUN_HOOKS_FLOOR = NEXT_RELEASE;
34
+
35
+ /** One run of a wave, as a run hook sees it (#4842). */
36
+ export interface OpWaveRunHookRun {
37
+ /** The spec's name and `op`. */
38
+ spec: string;
39
+ op: string;
40
+ wave: number;
41
+ waveName: string;
42
+ /** The job: `wave` for a whole wave, `decide` for a wide wave's deciding job, `share` or `group` for its apply jobs. */
43
+ job: "wave" | "decide" | "share" | "group";
44
+ target: string;
45
+ /** The run's own op. */
46
+ runOp: string;
47
+ /** The job's directory. */
48
+ cwd: string;
49
+ }
50
+
51
+ /** A planned run, as `beforeApply` and `afterApply` see it. */
52
+ export interface OpWaveRunHookPlanned extends OpWaveRunHookRun {
53
+ planDigest: string;
54
+ /** The run's plan file, relative to the job's directory: `{plan}`. */
55
+ plan: string;
56
+ /** The capability's artifact. */
57
+ artifact?: unknown;
58
+ }
59
+
60
+ /** An applied run, as `afterApply` sees it. */
61
+ export interface OpWaveRunHookApplied extends OpWaveRunHookPlanned {
62
+ outcome: "applied" | "moved" | "failed";
63
+ /** The capability's output, when it applied. */
64
+ output?: unknown;
65
+ /** Why it did not apply. */
66
+ reason?: string;
67
+ }
68
+
69
+ /** What `beforePlan` gives a run. */
70
+ export interface OpWaveBeforePlanResult {
71
+ /** Environment variables the run's engine plans and applies with, over the job's. */
72
+ env?: Record<string, string>;
73
+ /** A check the capability calls after its engine's init and before its plan. It throws to stop the run. */
74
+ afterInit?: () => void | Promise<void>;
75
+ /** Why the run is not planned at all. */
76
+ refuse?: string;
77
+ }
78
+
79
+ /** What `afterApply` adds to a run. */
80
+ export interface OpWaveAfterApplyResult {
81
+ /** Files the hook wrote for the run, relative to the job's directory. They go on the run record. */
82
+ files?: string[];
83
+ }
84
+
85
+ /** Hooks around each run of a wave with a `step`, in the job's process (#4842). */
86
+ export interface OpWaveRunHooks {
87
+ /** The hook's name in the log. */
88
+ name: string;
89
+ /** The runs it is for, as a command hook's `targets`. Default: every run. */
90
+ targets?: string[];
91
+ beforePlan?(run: OpWaveRunHookRun): OpWaveBeforePlanResult | void | Promise<OpWaveBeforePlanResult | void>;
92
+ beforeApply?(run: OpWaveRunHookPlanned): void | Promise<void>;
93
+ afterApply?(run: OpWaveRunHookApplied): OpWaveAfterApplyResult | void | Promise<OpWaveAfterApplyResult | void>;
94
+ }
95
+
96
+ /** What is wrong with `runHooks`, empty when nothing is. */
97
+ export function opWaveRunHooksProblems(hooks: unknown): string[] {
98
+ if (hooks === undefined) return [];
99
+ const list = Array.isArray(hooks) ? hooks : [hooks];
100
+ const problems: string[] = [];
101
+ list.forEach((h: unknown, i) => {
102
+ const at = `runHooks[${i}]`;
103
+ const hook = h as Partial<Record<keyof OpWaveRunHooks, unknown>> | null;
104
+ if (!hook || typeof hook !== "object") return void problems.push(`${at} must be { name, beforePlan?, beforeApply?, afterApply?, targets? }`);
105
+ if (typeof hook.name !== "string" || hook.name.trim() === "") problems.push(`${at} needs a name`);
106
+ const moments = (["beforePlan", "beforeApply", "afterApply"] as const).filter((m) => hook[m] !== undefined);
107
+ if (moments.length === 0) problems.push(`${at} gives none of beforePlan, beforeApply and afterApply`);
108
+ for (const m of moments) if (typeof hook[m] !== "function") problems.push(`${at}.${m} must be a function`);
109
+ 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`);
110
+ });
111
+ return problems;
112
+ }
113
+
114
+ /** The hooks as a list. */
115
+ export function opWaveRunHookList(given: OpWaveRunHooks | readonly OpWaveRunHooks[] | undefined): readonly OpWaveRunHooks[] {
116
+ if (given === undefined) return [];
117
+ return Array.isArray(given) ? (given as readonly OpWaveRunHooks[]) : [given as OpWaveRunHooks];
118
+ }
119
+
120
+ const forRun = <T extends { target: string }>(hook: OpWaveRunHooks, run: T): boolean => opWaveHookRuns(hook, [run]).length > 0;
121
+
122
+ /** What the `beforePlan` hooks gave one run. */
123
+ export type OpWaveBeforePlanOutcome = { refused: string } | { env?: Record<string, string>; afterInit?: () => Promise<void> };
124
+
125
+ /** Call each hook's `beforePlan` for `run`, in order. A hook that throws or refuses stops the rest and refuses the run. */
126
+ export async function runOpWaveBeforePlan(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookRun): Promise<OpWaveBeforePlanOutcome> {
127
+ let env: Record<string, string> | undefined;
128
+ const checks: Array<() => void | Promise<void>> = [];
129
+ for (const hook of hooks) {
130
+ if (!hook.beforePlan || !forRun(hook, run)) continue;
131
+ let answer: OpWaveBeforePlanResult | void;
132
+ try {
133
+ answer = await hook.beforePlan(run);
134
+ } catch (err) {
135
+ return { refused: `the before-plan hook ${hook.name} failed: ${err instanceof Error ? err.message : String(err)}` };
136
+ }
137
+ if (!answer) continue;
138
+ if (answer.refuse !== undefined) return { refused: `the before-plan hook ${hook.name} refused it: ${answer.refuse}` };
139
+ if (answer.env !== undefined) {
140
+ const bad = typeof answer.env !== "object" || answer.env === null || Array.isArray(answer.env) || !Object.values(answer.env).every((v) => typeof v === "string");
141
+ if (bad) return { refused: `the before-plan hook ${hook.name} answered with an env that is not a map of names to strings` };
142
+ env = { ...env, ...answer.env };
143
+ }
144
+ if (answer.afterInit !== undefined) {
145
+ if (typeof answer.afterInit !== "function") return { refused: `the before-plan hook ${hook.name} answered with an afterInit that is not a function` };
146
+ const name = hook.name;
147
+ const check = answer.afterInit;
148
+ checks.push(async () => {
149
+ try {
150
+ await check();
151
+ } catch (err) {
152
+ throw new Error(`the check after init of ${name} refused it: ${err instanceof Error ? err.message : String(err)}`);
153
+ }
154
+ });
155
+ }
156
+ }
157
+ return {
158
+ ...(env ? { env } : {}),
159
+ ...(checks.length > 0 ? { afterInit: async () => { for (const c of checks) await c(); } } : {}),
160
+ };
161
+ }
162
+
163
+ /** Call each hook's `beforeApply` for `run`. Returns why the run must not apply, or undefined. */
164
+ export async function runOpWaveBeforeApply(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookPlanned): Promise<string | undefined> {
165
+ for (const hook of hooks) {
166
+ if (!hook.beforeApply || !forRun(hook, run)) continue;
167
+ try {
168
+ await hook.beforeApply(run);
169
+ } catch (err) {
170
+ return `the before-apply hook ${hook.name} failed, so nothing of it was applied: ${err instanceof Error ? err.message : String(err)}`;
171
+ }
172
+ }
173
+ return undefined;
174
+ }
175
+
176
+ /** Call each hook's `afterApply` for `run`: the files they wrote, and why the run fails when one threw or answered badly. */
177
+ export async function runOpWaveAfterApply(hooks: readonly OpWaveRunHooks[], run: OpWaveRunHookApplied): Promise<{ files: string[]; failed?: string }> {
178
+ const files: string[] = [];
179
+ for (const hook of hooks) {
180
+ if (!hook.afterApply || !forRun(hook, run)) continue;
181
+ let answer: OpWaveAfterApplyResult | void;
182
+ try {
183
+ answer = await hook.afterApply(run);
184
+ } catch (err) {
185
+ return { files, failed: `the after-apply hook ${hook.name} failed: ${err instanceof Error ? err.message : String(err)}` };
186
+ }
187
+ const given = answer?.files;
188
+ if (given === undefined) continue;
189
+ if (!Array.isArray(given) || !given.every((f) => typeof f === "string" && f !== "" && !isAbsolute(f) && !f.split("/").includes(".."))) {
190
+ return { files, failed: `the after-apply hook ${hook.name} answered with files that are not paths inside the job's directory` };
191
+ }
192
+ for (const f of given) if (!files.includes(f)) files.push(f);
193
+ }
194
+ return { files };
195
+ }
@@ -92,7 +92,8 @@ import { appendRunRecord, DEFAULT_RUN_ENV } from "../lifecycle/run-ledger";
92
92
  import { LifecyclePushLostError, pushLifecycleRebasing } from "../lifecycle/git";
93
93
  import { resolveCiJob } from "../lifecycle/release-ledger";
94
94
  import type { OpRunPolicyRow, OpRunRecordInput, OpRunStepRecord, OpRunWave, OpRunWavePlan, OpRunWaveTarget } from "./runtime";
95
- import { foldPolicyRows, opWaveAfterPlanProblems, runOpWaveAfterPlanHooks, type OpWaveAfterPlanHook, type OpWaveAfterPlanRun } from "./op-waves-after-plan";
95
+ import { opWaveRunHookList, opWaveRunHooksProblems, runOpWaveAfterApply, runOpWaveBeforeApply, runOpWaveBeforePlan, type OpWaveRunHooks } from "./op-waves-run-hooks";
96
+ import { foldPolicyRows, opWaveAfterPlanProblems, runOpWaveAfterPlanHooks, type OpWaveAfterPlanHook, type OpWaveAfterPlanRun, type OpWaveAfterPlanWaveOutcome } from "./op-waves-after-plan";
96
97
  import { activeOtlp, RunEventTrace, type CapabilityTraceFacts, type OtlpExporter } from "../otlp";
97
98
  import { joinRunEventSinks, resolveRunEventRun, type RunEventSink } from "../run-event-stream";
98
99
  import { OpWaveRunEvents } from "./op-waves-events";
@@ -117,7 +118,12 @@ import {
117
118
  opWaveStepChangeSet,
118
119
  planJsonOf,
119
120
  planOpWaveStep,
121
+ planOpWaveStepGroup,
122
+ discoverOpWaveStepRuns,
123
+ applyOpWaveStepGroup,
124
+ OP_WAVE_TOGETHER_MEMBER,
120
125
  type OpWaveHolds,
126
+ type OpWaveStepApply,
121
127
  type OpWaveStepPlan,
122
128
  } from "./op-waves-capability";
123
129
  import {
@@ -279,6 +285,8 @@ export interface OpWaveMember extends WaveMember {
279
285
  override?: { by: string; at: string; digest: string; reason: string };
280
286
  /** The product's policy holds the plan for a person (#4294). */
281
287
  held?: { rules: string[]; reason?: string };
288
+ /** Who may override this run's denial (#4842), from an after-plan hook, in place of the wave's overriders. */
289
+ overriders?: string[];
282
290
  }
283
291
 
284
292
  /** Where a wave's policy came from. */
@@ -394,6 +402,12 @@ export interface OpWaveDecision {
394
402
  overridesSpentAt?: string;
395
403
  /** Digest members that are no run, from the plans file (#3821), such as the wave's cost. */
396
404
  extras?: WaveMember[];
405
+ /**
406
+ * After an approval of other plans (#4842): the after-plan hook's report of
407
+ * the plans now and the one stored for the plans approved, written for the
408
+ * job that explains the refusal. Paths relative to the job's directory.
409
+ */
410
+ reports?: { current: string; approved?: string };
397
411
  /** On a discovering wave (#3821): how many waves the plan command found. */
398
412
  discovered?: { waves?: number };
399
413
  /**
@@ -870,6 +884,13 @@ export interface RunOpWaveOptions {
870
884
  * files go on the run record. See `./op-waves-after-plan.ts`.
871
885
  */
872
886
  afterPlan?: OpWaveAfterPlanHook | readonly OpWaveAfterPlanHook[];
887
+ /**
888
+ * Hooks around each run of a wave with a `step`, in the job's own process
889
+ * (#4842): `beforePlan` gives a run its engine's environment and a check
890
+ * after init, or refuses it; `beforeApply` and `afterApply` run around
891
+ * its apply. See `./op-waves-run-hooks.ts`.
892
+ */
893
+ runHooks?: OpWaveRunHooks | readonly OpWaveRunHooks[];
873
894
  /**
874
895
  * How the spec's command hooks run (#4614), when they call back into the
875
896
  * caller's own process: a product that runs the wave in process and serves
@@ -947,8 +968,12 @@ interface WaveContext {
947
968
  gateRule: { approval: GateApprovalSource; base: string; neverOverMcp: boolean };
948
969
  /** With a `step` (#4545): each run's plan through it, by target, which its apply hands back. */
949
970
  steps?: Map<string, OpWaveStepPlan>;
971
+ /** Each run's environment from the run hooks (#4842), by target, which its plan and its apply run with. */
972
+ runEnv?: Map<string, Record<string, string>>;
950
973
  /** The plans file's change set (#4551), which a `pull-request` gate checks the pull request's approval against (#4550). */
951
974
  changeSetDoc?: ChangeSetDocument;
975
+ /** An after-plan hook's report of the wave's plans (#4842), stored beside the pending fact. */
976
+ report?: string;
952
977
  }
953
978
 
954
979
  function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpWaveExec }, waveName: string, run: OpWaveRun): OpWaveMember {
@@ -1116,13 +1141,45 @@ async function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: s
1116
1141
  };
1117
1142
  }
1118
1143
 
1144
+ /** Which job of the wave this is, as a hook names it. */
1145
+ function jobKind(options: Pick<RunOpWaveOptions, "decide" | "share" | "group">): "wave" | "decide" | "share" | "group" {
1146
+ return options.decide ? "decide" : options.group !== undefined ? "group" : options.share !== undefined ? "share" : "wave";
1147
+ }
1148
+
1149
+ /** A run as a run hook sees it (#4842). */
1150
+ function runHookRun(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; options: Pick<RunOpWaveOptions, "decide" | "share" | "group"> }, run: OpWaveRun) {
1151
+ return { spec: at.spec.name, op: at.spec.op, wave: at.k, waveName: at.wave.name, job: jobKind(at.options), target: run.target, runOp: run.op ?? at.spec.op, cwd: at.cwd };
1152
+ }
1153
+
1154
+ /**
1155
+ * Apply one run through the spec's step (#4545) with the product's run hooks
1156
+ * around it (#4842): `beforeApply` first, which can stop it, then the apply
1157
+ * with the run's environment, then `afterApply`, whose files go on the
1158
+ * result and whose failure fails a run that applied.
1159
+ */
1160
+ async function applyStepRun(ctx: WaveContext, registry: CapabilityRegistry, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply & { files?: string[] }> {
1161
+ const { spec, wave, k, options } = ctx;
1162
+ const hooks = opWaveRunHookList(options.runHooks);
1163
+ const env = ctx.runEnv?.get(run.target);
1164
+ if (hooks.length === 0) return applyOpWaveStep({ spec, wave, registry, ...(env ? { processEnv: env } : {}) }, run, plan);
1165
+ const planned = { ...runHookRun(ctx, run), planDigest: plan.planDigest, plan: opWavePlanPath(spec, k, run.target), ...(plan.artifact !== undefined ? { artifact: plan.artifact } : {}) };
1166
+ const stop = await runOpWaveBeforeApply(hooks, planned);
1167
+ if (stop !== undefined) return { outcome: "failed", reason: stop };
1168
+ const got = await applyOpWaveStep({ spec, wave, registry, ...(env ? { processEnv: env } : {}) }, run, plan);
1169
+ const after = await runOpWaveAfterApply(hooks, { ...planned, outcome: got.outcome, ...(got.outcome === "applied" ? { output: got.output } : { reason: got.reason }) });
1170
+ const files = after.files.length > 0 ? { files: after.files } : {};
1171
+ if (after.failed && got.outcome === "applied") return { outcome: "failed", reason: `applied, and then ${after.failed}`, ...(got.facts ? { facts: got.facts } : {}), ...files };
1172
+ if (after.failed) ctx.log(`${run.target}: ${after.failed}`);
1173
+ return { ...got, ...files };
1174
+ }
1175
+
1119
1176
  /**
1120
1177
  * Plan `runs` of wave `k` (#4545): through the spec's `step` when it names
1121
1178
  * one, each run's plan kept on `at.steps` for its apply, else with the
1122
1179
  * commands ({@link planRuns}).
1123
1180
  */
1124
1181
  async function planWaveRuns(
1125
- at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec; options: Pick<RunOpWaveOptions, "capabilities" | "lockGrain" | "base" | "waveExec">; steps?: Map<string, OpWaveStepPlan> },
1182
+ at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec; options: Pick<RunOpWaveOptions, "capabilities" | "lockGrain" | "base" | "waveExec" | "runHooks" | "decide" | "share" | "group">; steps?: Map<string, OpWaveStepPlan>; runEnv?: Map<string, Record<string, string>> },
1126
1183
  runs: readonly OpWaveRun[],
1127
1184
  discover = false,
1128
1185
  ): Promise<PlannedRuns> {
@@ -1133,11 +1190,42 @@ async function planWaveRuns(
1133
1190
  const lockGrain = at.options.lockGrain ?? (await declaredLockGrain(cwd, base));
1134
1191
  // #4613: a step's own policy engine (CrossGuard) reads its packs at the base the wave's rules were read at.
1135
1192
  const policyBase = base && base !== "HEAD" ? base : undefined;
1193
+ // #4842: a discovering wave's runs are the ones its step's capability finds for wave k.
1194
+ const found = discover ? await discoverOpWaveStepRuns({ spec, wave, k, registry }) : undefined;
1195
+ if (found) runs = found.runs;
1136
1196
  const plans: OpWaveStepPlan[] = [];
1137
- for (const run of runs) {
1138
- const plan = await planOpWaveStep({ spec, wave, cwd, registry, planPath: opWavePlanPath(spec, k, run.target), lockGrain, ...(policyBase ? { policyBase } : {}) }, run);
1139
- at.steps?.set(run.target, plan);
1140
- plans.push(plan);
1197
+ const hooks = opWaveRunHookList(at.options.runHooks);
1198
+ const beforePlan = async (run: OpWaveRun): Promise<{ env?: Record<string, string>; afterInit?: () => Promise<void> }> => {
1199
+ // #4842: the product's run hooks give the run its environment and a check after init, or refuse it.
1200
+ const before = hooks.length > 0 ? await runOpWaveBeforePlan(hooks, runHookRun(at, run)) : {};
1201
+ if ("refused" in before) throw new Error(`${run.target} was not planned: ${before.refused}`);
1202
+ if (before.env) {
1203
+ at.runEnv ??= new Map();
1204
+ at.runEnv.set(run.target, before.env);
1205
+ }
1206
+ return before;
1207
+ };
1208
+ let together: string | undefined;
1209
+ if (wave.together && runs.length > 0) {
1210
+ // #4842: one plan of the whole wave, each run's hooks first.
1211
+ const own = new Map<string, { env?: Record<string, string>; afterInit?: () => Promise<void> }>();
1212
+ for (const run of runs) own.set(run.target, await beforePlan(run));
1213
+ const runCtx = (target: string) => {
1214
+ const b = own.get(target) ?? {};
1215
+ return { ...(b.env ? { processEnv: b.env } : {}), ...(b.afterInit ? { afterInit: b.afterInit } : {}) };
1216
+ };
1217
+ for (const plan of await planOpWaveStepGroup({ spec, wave, cwd, registry, planPath: (target) => opWavePlanPath(spec, k, target), lockGrain, ...(policyBase ? { policyBase } : {}), runCtx }, runs)) {
1218
+ at.steps?.set(plan.target, plan);
1219
+ plans.push(plan);
1220
+ }
1221
+ together = plans[0]?.group?.digest;
1222
+ } else {
1223
+ for (const run of runs) {
1224
+ const before = await beforePlan(run);
1225
+ const plan = await planOpWaveStep({ spec, wave, cwd, registry, planPath: opWavePlanPath(spec, k, run.target), lockGrain, ...(policyBase ? { policyBase } : {}), ...(before.env ? { processEnv: before.env } : {}), ...(before.afterInit ? { afterInit: before.afterInit } : {}) }, run);
1226
+ at.steps?.set(run.target, plan);
1227
+ plans.push(plan);
1228
+ }
1141
1229
  }
1142
1230
  const members = plans.map((p) => ({
1143
1231
  member: p.target,
@@ -1149,7 +1237,14 @@ async function planWaveRuns(
1149
1237
  }));
1150
1238
  const parts = new Map(plans.flatMap((p) => (p.part ? [[p.target, p.part] as const] : [])));
1151
1239
  const changeSet = opWaveStepChangeSet(plans);
1152
- return { members, ...(parts.size > 0 ? { parts } : {}), ...(changeSet ? { changeSet } : {}) };
1240
+ return {
1241
+ members,
1242
+ ...(parts.size > 0 ? { parts } : {}),
1243
+ ...(changeSet ? { changeSet } : {}),
1244
+ // #4842: the capability's digest of the whole wave is a digest member of its own.
1245
+ ...(together ? { extras: [{ member: OP_WAVE_TOGETHER_MEMBER, planDigest: together }] } : {}),
1246
+ ...(found?.waves !== undefined ? { waves: found.waves } : {}),
1247
+ };
1153
1248
  }
1154
1249
 
1155
1250
  /**
@@ -1346,7 +1441,7 @@ async function runAfterPlan(
1346
1441
  members: OpWaveMember[],
1347
1442
  parts: ReadonlyMap<string, ChangeSetPart> | undefined,
1348
1443
  policyRows: ReadonlyMap<string, OpRunPolicyRow>,
1349
- ): Promise<{ failed?: string; holds: string[] }> {
1444
+ ): Promise<{ failed?: string; holds: string[]; wave?: OpWaveAfterPlanWaveOutcome }> {
1350
1445
  const { spec, k, wave, cwd, options, result } = ctx;
1351
1446
  const hooks = afterPlanHooks(options);
1352
1447
  const job: OpWaveAfterPlanRun["job"] = options.decide ? "decide" : options.group !== undefined ? "group" : options.share !== undefined ? "share" : "wave";
@@ -1387,11 +1482,12 @@ async function runAfterPlan(
1387
1482
  if (folded.denied) m.denied = folded.denied;
1388
1483
  if (folded.held) m.held = folded.held;
1389
1484
  }
1485
+ if (mine?.overriders) m.overriders = mine.overriders;
1390
1486
  if (rows.length === 0 && !mine?.files.length) continue;
1391
1487
  plans[m.member] = { planDigest: m.planDigest, ...(rows.length ? { policy: rows } : {}), ...(mine?.files.length ? { files: [...mine.files] } : {}) };
1392
1488
  }
1393
1489
  if (Object.keys(plans).length > 0) result.plans = plans;
1394
- return { ...(out?.failed ? { failed: out.failed } : {}), holds: out?.holds ?? [] };
1490
+ return { ...(out?.failed ? { failed: out.failed } : {}), holds: out?.holds ?? [], ...(out ? { wave: out.wave } : {}) };
1395
1491
  }
1396
1492
 
1397
1493
  /** One field of a plan file, or undefined when the file or the field is missing. */
@@ -1894,6 +1990,8 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
1894
1990
  assertOpWavesSpec(options.spec);
1895
1991
  const afterPlanWrong = opWaveAfterPlanProblems(options.afterPlan);
1896
1992
  if (afterPlanWrong.length > 0) throw new Error(`Op waves "${options.spec.name}": ${afterPlanWrong.join("; ")}`);
1993
+ const runHooksWrong = opWaveRunHooksProblems(options.runHooks);
1994
+ if (runHooksWrong.length > 0) throw new Error(`Op waves "${options.spec.name}": ${runHooksWrong.join("; ")}`);
1897
1995
  // #4551: one run record per job, on every way the job ends.
1898
1996
  const started = new Date().toISOString();
1899
1997
  // #4555: the job's run events and its trace, when a reader or an exporter wants them.
@@ -1952,7 +2050,7 @@ function targetStarted(options: RunOpWaveOptions, k: number, target: string): nu
1952
2050
  }
1953
2051
 
1954
2052
  /** A target's apply ended (#4555): its time and facts on the result, and its `step-settle`. */
1955
- function targetSettled(options: RunOpWaveOptions, result: RunOpWaveResult, k: number, target: string, startedMs: number, status: "ok" | "failed" | "skipped", opts: { error?: string; facts?: CapabilityTraceFacts } = {}): void {
2053
+ function targetSettled(options: RunOpWaveOptions, result: RunOpWaveResult, k: number, target: string, startedMs: number, status: "ok" | "failed" | "skipped", opts: { error?: string; facts?: CapabilityTraceFacts; files?: string[] } = {}): void {
1956
2054
  const durationMs = Math.max(0, Date.now() - startedMs);
1957
2055
  result.targets = {
1958
2056
  ...result.targets,
@@ -1966,6 +2064,8 @@ function targetSettled(options: RunOpWaveOptions, result: RunOpWaveResult, k: nu
1966
2064
  ...(status === "failed" && opts.facts?.resources?.some((r) => r.status === "failed")
1967
2065
  ? { failedResources: opts.facts.resources.filter((r) => r.status === "failed").map((r) => r.name ?? r.resource) }
1968
2066
  : {}),
2067
+ // #4842: what the run hooks wrote after the apply.
2068
+ ...(opts.files?.length ? { files: opts.files } : {}),
1969
2069
  },
1970
2070
  };
1971
2071
  jobEvents.get(options)?.stepSettle(k, target, status, durationMs, opts);
@@ -2501,7 +2601,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2501
2601
  if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
2502
2602
  if (before.waitingOn) return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
2503
2603
  if (spec.step) ctx.steps = new Map();
2504
- const { members, pending, overriders, overridersSource, extras: planExtras, waves: found, changeSet, parts } = await planWaveRuns(ctx, wave.runs, wave.discover === true);
2604
+ const { members, pending: planPending, overriders: planOverriders, overridersSource: planOverridersSource, extras: planExtras, waves: found, changeSet, parts } = await planWaveRuns(ctx, wave.runs, wave.discover === true);
2505
2605
  // #4545: the holds at base (else the change's), run over the plans before the gate decides.
2506
2606
  let extras = planExtras;
2507
2607
  let policyRows = new Map<string, OpRunPolicyRow>();
@@ -2521,6 +2621,19 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2521
2621
  const inProcess = await runAfterPlan(ctx, members, parts, policyRows);
2522
2622
  if (inProcess.failed) return { end: failed(ctx, `${inProcess.failed}, so nothing in wave ${k} was approved or applied`) };
2523
2623
  holds.push(...inProcess.holds);
2624
+ // #4842: what the hooks added to the wave as a whole, over what a plans file gave.
2625
+ const answer = inProcess.wave;
2626
+ holds.push(...(answer?.holds ?? []));
2627
+ const pending = answer?.pending ? { ...planPending, ...answer.pending } : planPending;
2628
+ const overriders = answer?.overriders ?? planOverriders;
2629
+ const overridersSource = answer?.overriders ? answer.overridersSource : planOverridersSource;
2630
+ if (answer?.members.length) {
2631
+ const named = new Set((extras ?? []).map((m) => m.member));
2632
+ const clash = answer.members.find((m) => named.has(m.member));
2633
+ if (clash) return { end: failed(ctx, `wave ${k} (${wave.name}): an after-plan hook and the wave's holds both name the digest member ${clash.member}, so nothing in it was approved or applied`) };
2634
+ extras = [...(extras ?? []), ...answer.members];
2635
+ }
2636
+ if (answer?.report !== undefined) ctx.report = answer.report;
2524
2637
  if (wave.discover) {
2525
2638
  wave = { ...wave, runs: members.map((m) => ({ target: m.member, ...(m.op !== spec.op ? { op: m.op } : {}) })) };
2526
2639
  ctx.wave = wave;
@@ -2642,6 +2755,7 @@ async function decideOpWave(
2642
2755
  // Plans nobody previewed apply only under an approval of these very plans, whatever the gate policy says.
2643
2756
  if (unseen) refuseUnseen(ctx, decision);
2644
2757
  }
2758
+ if (ctx.report !== undefined) await keepWaveReport(options, ctx, decision, ctx.report);
2645
2759
  const code = await decided(ctx, decision, recordPath);
2646
2760
  if (code.exitCode !== 0) return { end: code };
2647
2761
  log(
@@ -2659,6 +2773,51 @@ async function decideOpWave(
2659
2773
  return { go: { runs: wave.runs, earlierHolds: [], recordPath } };
2660
2774
  }
2661
2775
 
2776
+ /** Where a wave's reports go for the job that explains a moved approval (#4842), relative to the job's directory. */
2777
+ export function opWaveReportDir(spec: Pick<OpWavesSpec, "name">, k: number): string {
2778
+ return `.chant/op-waves/${spec.name}/wave-${k}/report`;
2779
+ }
2780
+
2781
+ /**
2782
+ * Keep an after-plan hook's report of the wave's plans (#4842). While the
2783
+ * wave waits, it is stored beside the pending fact, once per digest. When
2784
+ * the plans moved after an approval, it and the report stored for the
2785
+ * approved plans are written to {@link opWaveReportDir} and named on the
2786
+ * decision. A report that cannot be kept is logged; it never decides the gate.
2787
+ */
2788
+ async function keepWaveReport(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, report: string): Promise<void> {
2789
+ if (decision.status !== "waiting") return;
2790
+ const { spec, k, wave, cwd, log } = ctx;
2791
+ const port = options.gates ?? gitGateLedgerPort({ cwd });
2792
+ const label = `wave ${k} (${wave.name})`;
2793
+ if (port.storeGateReport) {
2794
+ try {
2795
+ await port.storeGateReport(spec.name, decision.gate, decision.digest, report);
2796
+ } catch (err) {
2797
+ log(`${label}: the report of these plans was not kept beside the pending fact: ${err instanceof Error ? err.message : String(err)}`);
2798
+ }
2799
+ }
2800
+ const was = decision.mismatch?.approved;
2801
+ if (was === undefined) return;
2802
+ let approved: string | null = null;
2803
+ try {
2804
+ approved = (await port.readGateReport?.(spec.name, decision.gate, was)) ?? null;
2805
+ } catch (err) {
2806
+ log(`${label}: the report of the approved plans could not be read: ${err instanceof Error ? err.message : String(err)}`);
2807
+ }
2808
+ if (approved === null) log(`${label}: no report was kept for the approved plans ${was}`);
2809
+ const dir = opWaveReportDir(spec, k);
2810
+ mkdirSync(join(cwd, dir), { recursive: true });
2811
+ const current = `${dir}/current.json`;
2812
+ writeFileSync(join(cwd, current), report);
2813
+ const reports: { current: string; approved?: string } = { current };
2814
+ if (approved !== null) {
2815
+ reports.approved = `${dir}/approved.json`;
2816
+ writeFileSync(join(cwd, reports.approved), approved);
2817
+ }
2818
+ decision.reports = reports;
2819
+ }
2820
+
2662
2821
  /**
2663
2822
  * Compare the wave's set digest with the one the merged pull request's head
2664
2823
  * recorded for it (`--record-plans`): the plans its reviewers saw. The pull
@@ -2858,14 +3017,16 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
2858
3017
  let moved = false;
2859
3018
  for (const m of decision.members) {
2860
3019
  if (!m.denied || m.override) continue;
3020
+ // #4842: a run's own overriders, from an after-plan hook, count for it in place of the wave's.
3021
+ const mayOverride = m.overriders ?? overriders;
2861
3022
  const verdict = og.decideOverride({
2862
3023
  ledger,
2863
3024
  applied,
2864
3025
  subject: m.member,
2865
3026
  planDigest: m.planDigest,
2866
3027
  rules: m.denied.rules,
2867
- overriders,
2868
- overridersPath: listed ? (source ?? "the overriders the plans file names") : path,
3028
+ overriders: mayOverride,
3029
+ overridersPath: m.overriders ? (source ?? `the overriders an after-plan hook names for ${m.member}`) : listed ? (source ?? "the overriders the plans file names") : path,
2869
3030
  mode: sealed ? "sealed" : "ledger",
2870
3031
  ...(signers ? { signers } : {}),
2871
3032
  now,
@@ -2897,7 +3058,7 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
2897
3058
  log(`${m.member}: the denial was not recorded for an override: ${err instanceof Error ? err.message : String(err)}`);
2898
3059
  }
2899
3060
  }
2900
- log(`${m.member}: ${overriders.length ? `${overriders.join(", ")} may` : "nobody listed may"} override it with: ${og.overrideCommand(m.member, m.denied.rules, sealed)}`);
3061
+ log(`${m.member}: ${mayOverride.length ? `${mayOverride.join(", ")} may` : "nobody listed may"} override it with: ${og.overrideCommand(m.member, m.denied.rules, sealed)}`);
2901
3062
  }
2902
3063
  if (still.length > 0) {
2903
3064
  decision.status = "refused";
@@ -3641,6 +3802,9 @@ async function applyLeased(
3641
3802
  log(`wave ${k} (${wave.name}): apply failed, so none of ${runs.map((r) => r.target).join(", ")} counts as applied`);
3642
3803
  result.failed.push(...runs.map((r) => r.target));
3643
3804
  }
3805
+ } else if (spec.step && wave.together) {
3806
+ // #4842: the wave's runs apply in one call of the step's capability.
3807
+ await applyStepRunsTogether(options, ctx, runs);
3644
3808
  } else if (spec.step && (wave.parallelism ?? spec.parallelism ?? 1) > 1) {
3645
3809
  // #4625: the step's runs apply several at once.
3646
3810
  await applyStepRunsAtOnce(options, ctx, runs, wave.parallelism ?? spec.parallelism!);
@@ -3665,10 +3829,11 @@ async function applyLeased(
3665
3829
  }
3666
3830
  const registry = await opWaveRegistry(options, ctx.cwd, options.capabilities);
3667
3831
  const startedMs = targetStarted(options, k, run.target);
3668
- const got = await applyOpWaveStep({ spec, wave, registry }, run, plan);
3832
+ const got = await applyStepRun(ctx, registry, run, plan);
3669
3833
  targetSettled(options, result, k, run.target, startedMs, got.outcome === "applied" ? "ok" : got.outcome === "moved" ? "skipped" : "failed", {
3670
3834
  ...(got.outcome !== "applied" ? { error: got.reason } : {}),
3671
3835
  ...(got.facts ? { facts: got.facts } : {}),
3836
+ ...(got.files ? { files: got.files } : {}),
3672
3837
  });
3673
3838
  if (got.outcome === "applied") result.applied.push(run.target);
3674
3839
  else if (got.outcome === "moved") {
@@ -3742,6 +3907,64 @@ async function applyLeased(
3742
3907
  if (recordPath && result.hooks.length > 0) writeRecord(recordPath, decision, result);
3743
3908
  }
3744
3909
 
3910
+ /**
3911
+ * A `together` wave's runs applied in one `runGroup` call (#4842), with the
3912
+ * run hooks around it: each run's `beforeApply` first, and any that stops
3913
+ * one fails every run with nothing applied, since the one call applies them
3914
+ * all; then the call, each run with its own environment; then each run's
3915
+ * `afterApply`, whose files go on the run and whose failure fails a run that
3916
+ * applied. The outcomes land in the result in the wave's order.
3917
+ */
3918
+ async function applyStepRunsTogether(options: RunOpWaveOptions, ctx: WaveContext, runs: readonly OpWaveRun[]): Promise<void> {
3919
+ const { spec, k, wave, log, result } = ctx;
3920
+ const missing = runs.filter((r) => !ctx.steps?.get(r.target)).map((r) => r.target);
3921
+ if (missing.length > 0) {
3922
+ log(`wave ${k} (${wave.name}): this job holds no plan of ${missing.join(", ")}, so none of its runs applied`);
3923
+ result.failed.push(...runs.map((r) => r.target));
3924
+ return;
3925
+ }
3926
+ const registry = await opWaveRegistry(options, ctx.cwd, options.capabilities);
3927
+ const hooks = opWaveRunHookList(options.runHooks);
3928
+ const planned = runs.map((run) => {
3929
+ const plan = ctx.steps!.get(run.target)!;
3930
+ return { run, plan, hook: { ...runHookRun(ctx, run), planDigest: plan.planDigest, plan: opWavePlanPath(spec, k, run.target), ...(plan.artifact !== undefined ? { artifact: plan.artifact } : {}) } };
3931
+ });
3932
+ const startedMs = new Map(runs.map((r) => [r.target, targetStarted(options, k, r.target)]));
3933
+ for (const p of hooks.length > 0 ? planned : []) {
3934
+ const stop = await runOpWaveBeforeApply(hooks, p.hook);
3935
+ if (stop === undefined) continue;
3936
+ log(`${p.run.target}: ${stop}, so none of wave ${k}'s runs applied`);
3937
+ for (const r of runs) targetSettled(options, result, k, r.target, startedMs.get(r.target)!, "failed", { error: r.target === p.run.target ? stop : `not applied: ${p.run.target}: ${stop}` });
3938
+ result.failed.push(...runs.map((r) => r.target));
3939
+ return;
3940
+ }
3941
+ const got = await applyOpWaveStepGroup({ spec, wave, registry, runEnv: (target) => ctx.runEnv?.get(target) }, planned);
3942
+ for (const [i, p] of planned.entries()) {
3943
+ let outcome = got[i]!;
3944
+ let files: string[] | undefined;
3945
+ if (hooks.length > 0) {
3946
+ const after = await runOpWaveAfterApply(hooks, { ...p.hook, outcome: outcome.outcome, ...(outcome.outcome === "applied" ? { output: outcome.output } : { reason: outcome.reason }) });
3947
+ if (after.files.length > 0) files = after.files;
3948
+ if (after.failed && outcome.outcome === "applied") outcome = { outcome: "failed", reason: `applied, and then ${after.failed}`, ...(outcome.facts ? { facts: outcome.facts } : {}) };
3949
+ else if (after.failed) log(`${p.run.target}: ${after.failed}`);
3950
+ }
3951
+ const target = p.run.target;
3952
+ targetSettled(options, result, k, target, startedMs.get(target)!, outcome.outcome === "applied" ? "ok" : outcome.outcome === "moved" ? "skipped" : "failed", {
3953
+ ...(outcome.outcome !== "applied" ? { error: outcome.reason } : {}),
3954
+ ...(outcome.facts ? { facts: outcome.facts } : {}),
3955
+ ...(files ? { files } : {}),
3956
+ });
3957
+ if (outcome.outcome === "applied") result.applied.push(target);
3958
+ else if (outcome.outcome === "moved") {
3959
+ log(`${target}: its plan moved since wave ${k} was decided, so it was not applied: ${outcome.reason}`);
3960
+ result.moved.push(target);
3961
+ } else {
3962
+ log(`${target}: apply failed: ${outcome.reason}`);
3963
+ result.failed.push(target);
3964
+ }
3965
+ }
3966
+ }
3967
+
3745
3968
  /**
3746
3969
  * A wave's step runs applied at most `limit` at once (#4625). A run waits
3747
3970
  * for each run the wave lists before it that it depends on, and is blocked,
@@ -3771,10 +3994,11 @@ async function applyStepRunsAtOnce(options: RunOpWaveOptions, ctx: WaveContext,
3771
3994
  return { failed: true };
3772
3995
  }
3773
3996
  const startedMs = targetStarted(options, k, run.target);
3774
- const got = await applyOpWaveStep({ spec, wave, registry }, run, plan);
3997
+ const got = await applyStepRun(ctx, registry, run, plan);
3775
3998
  targetSettled(options, result, k, run.target, startedMs, got.outcome === "applied" ? "ok" : got.outcome === "moved" ? "skipped" : "failed", {
3776
3999
  ...(got.outcome !== "applied" ? { error: got.reason } : {}),
3777
4000
  ...(got.facts ? { facts: got.facts } : {}),
4001
+ ...(got.files ? { files: got.files } : {}),
3778
4002
  });
3779
4003
  if (got.outcome === "applied") return { applied: true };
3780
4004
  if (got.outcome === "moved") {