@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.
- package/dist/__fixtures__/notify-messages/events.d.ts +9 -0
- package/dist/__fixtures__/notify-messages/events.d.ts.map +1 -0
- package/dist/__fixtures__/notify-messages/events.js +21 -0
- package/dist/__fixtures__/product-words.d.ts +14 -0
- package/dist/__fixtures__/product-words.d.ts.map +1 -1
- package/dist/__fixtures__/product-words.js +11 -0
- package/dist/__fixtures__/terragucci-notify.d.ts +66 -0
- package/dist/__fixtures__/terragucci-notify.d.ts.map +1 -0
- package/dist/__fixtures__/terragucci-notify.js +133 -0
- package/dist/action-pins.d.ts +8 -0
- package/dist/action-pins.d.ts.map +1 -1
- package/dist/action-pins.js +8 -0
- package/dist/agent-guard.d.ts.map +1 -1
- package/dist/agent-guard.js +1 -2
- package/dist/change-set.d.ts +10 -1
- package/dist/change-set.d.ts.map +1 -1
- package/dist/change-set.js +4 -1
- package/dist/ci-agent.d.ts +16 -2
- package/dist/ci-agent.d.ts.map +1 -1
- package/dist/ci-agent.js +6 -1
- package/dist/ci-commit.d.ts +66 -2
- package/dist/ci-commit.d.ts.map +1 -1
- package/dist/ci-commit.js +147 -19
- package/dist/ci-own-jobs.d.ts.map +1 -1
- package/dist/ci-own-jobs.js +1 -2
- package/dist/ci-product-words.d.ts +18 -4
- package/dist/ci-product-words.d.ts.map +1 -1
- package/dist/ci-product-words.js +26 -6
- package/dist/ci-product.d.ts +7 -3
- package/dist/ci-product.d.ts.map +1 -1
- package/dist/ci-product.js +8 -5
- package/dist/cli/handlers/release.d.ts +8 -0
- package/dist/cli/handlers/release.d.ts.map +1 -1
- package/dist/cli/handlers/release.js +68 -6
- package/dist/cli/handlers/run-wave.js +1 -0
- package/dist/cli/main.d.ts.map +1 -1
- package/dist/cli/main.js +7 -0
- package/dist/cli/mcp/product-tools.d.ts +6 -0
- package/dist/cli/mcp/product-tools.d.ts.map +1 -1
- package/dist/cli/mcp/product-tools.js +7 -0
- package/dist/cli/mcp/read-only.d.ts +12 -0
- package/dist/cli/mcp/read-only.d.ts.map +1 -1
- package/dist/cli/mcp/read-only.js +16 -0
- package/dist/cli/mcp/server.d.ts +11 -0
- package/dist/cli/mcp/server.d.ts.map +1 -1
- package/dist/cli/mcp/server.js +26 -5
- package/dist/cli/mcp/types.d.ts +5 -1
- package/dist/cli/mcp/types.d.ts.map +1 -1
- package/dist/components/capability.d.ts +42 -0
- package/dist/components/capability.d.ts.map +1 -1
- package/dist/components/group-digest.d.ts +17 -0
- package/dist/components/group-digest.d.ts.map +1 -0
- package/dist/components/group-digest.js +18 -0
- package/dist/components/groups.d.ts +2 -11
- package/dist/components/groups.d.ts.map +1 -1
- package/dist/components/groups.js +2 -12
- package/dist/components/index.d.ts +1 -1
- package/dist/components/index.d.ts.map +1 -1
- package/dist/components/pr-env-components.d.ts.map +1 -1
- package/dist/components/pr-env-components.js +1 -2
- package/dist/config.d.ts +28 -8
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +21 -1
- package/dist/lexicon.d.ts +8 -0
- package/dist/lexicon.d.ts.map +1 -1
- package/dist/lexicon.js +8 -0
- package/dist/lifecycle/release-cut.d.ts +7 -1
- package/dist/lifecycle/release-cut.d.ts.map +1 -1
- package/dist/lifecycle/release-cut.js +1 -0
- package/dist/lifecycle/release-images.d.ts +86 -3
- package/dist/lifecycle/release-images.d.ts.map +1 -1
- package/dist/lifecycle/release-images.js +131 -6
- package/dist/lifecycle/release-publish.d.ts +8 -1
- package/dist/lifecycle/release-publish.d.ts.map +1 -1
- package/dist/lifecycle/release-publish.js +30 -3
- package/dist/lifecycle/release-version.d.ts +86 -0
- package/dist/lifecycle/release-version.d.ts.map +1 -0
- package/dist/lifecycle/release-version.js +209 -0
- package/dist/mcp/types.d.ts +26 -0
- package/dist/mcp/types.d.ts.map +1 -1
- package/dist/notify-product.d.ts +11 -2
- package/dist/notify-product.d.ts.map +1 -1
- package/dist/notify-product.js +15 -4
- package/dist/notify-relay.d.ts.map +1 -1
- package/dist/notify-relay.js +1 -2
- package/dist/notify.d.ts +36 -4
- package/dist/notify.d.ts.map +1 -1
- package/dist/notify.js +31 -21
- package/dist/notify.schema.json +1 -0
- package/dist/op/activities/review-product.d.ts +111 -0
- package/dist/op/activities/review-product.d.ts.map +1 -0
- package/dist/op/activities/review-product.js +115 -0
- package/dist/op/gate.d.ts +17 -0
- package/dist/op/gate.d.ts.map +1 -1
- package/dist/op/gate.js +36 -0
- package/dist/op/index.d.ts +8 -6
- package/dist/op/index.d.ts.map +1 -1
- package/dist/op/index.js +5 -4
- package/dist/op/op-waves-after-plan.d.ts +76 -1
- package/dist/op/op-waves-after-plan.d.ts.map +1 -1
- package/dist/op/op-waves-after-plan.js +142 -3
- package/dist/op/op-waves-capability-spec.js +1 -2
- package/dist/op/op-waves-capability.d.ts +89 -2
- package/dist/op/op-waves-capability.d.ts.map +1 -1
- package/dist/op/op-waves-capability.js +215 -7
- package/dist/op/op-waves-run-hooks.d.ts +104 -0
- package/dist/op/op-waves-run-hooks.d.ts.map +1 -0
- package/dist/op/op-waves-run-hooks.js +146 -0
- package/dist/op/op-waves-run.d.ts +21 -0
- package/dist/op/op-waves-run.d.ts.map +1 -1
- package/dist/op/op-waves-run.js +233 -13
- package/dist/op/op-waves.d.ts +11 -1
- package/dist/op/op-waves.d.ts.map +1 -1
- package/dist/op/op-waves.js +7 -1
- package/dist/op/runtime.d.ts +2 -0
- package/dist/op/runtime.d.ts.map +1 -1
- package/dist/policy-engine.d.ts.map +1 -1
- package/dist/policy-engine.js +1 -2
- package/dist/pr-forge-reads.d.ts +124 -0
- package/dist/pr-forge-reads.d.ts.map +1 -0
- package/dist/pr-forge-reads.js +322 -0
- package/dist/pr-forge.d.ts +14 -0
- package/dist/pr-forge.d.ts.map +1 -1
- package/dist/pr-forge.js +21 -13
- package/dist/pr-plan-note.d.ts +293 -0
- package/dist/pr-plan-note.d.ts.map +1 -0
- package/dist/pr-plan-note.js +361 -0
- package/dist/release-floors.d.ts +13 -1
- package/dist/release-floors.d.ts.map +1 -1
- package/dist/release-floors.js +13 -1
- package/dist/state-export.d.ts.map +1 -1
- package/dist/state-export.js +1 -2
- package/dist/state-migration.d.ts.map +1 -1
- package/dist/state-migration.js +1 -2
- package/dist/state-unlock.d.ts.map +1 -1
- package/dist/state-unlock.js +1 -2
- package/dist/wave-runtime.mjs +314 -314
- package/dist/workspace/change-set.schema.json +7 -0
- package/dist/workspace/release-workflow.d.ts +7 -0
- package/dist/workspace/release-workflow.d.ts.map +1 -1
- package/dist/workspace/release-workflow.js +13 -2
- package/package.json +1 -1
- package/src/__fixtures__/notify-messages/events.ts +23 -0
- package/src/__fixtures__/notify-messages/messages.json +50 -0
- package/src/__fixtures__/pr-loop/terragucci-plan.note.golden.md +53 -0
- package/src/__fixtures__/pr-loop/terragucci-plan.note.json +83 -0
- package/src/__fixtures__/product-words.ts +12 -0
- package/src/__fixtures__/review-agent/terragucci-review.json +94 -0
- package/src/__fixtures__/terragucci-notify.ts +170 -0
- package/src/action-pins.test.ts +11 -1
- package/src/action-pins.ts +9 -0
- package/src/agent-guard.test.ts +1 -2
- package/src/agent-guard.ts +1 -2
- package/src/change-set.test.ts +20 -0
- package/src/change-set.ts +11 -1
- package/src/ci-agent.test.ts +9 -0
- package/src/ci-agent.ts +15 -2
- package/src/ci-commit.test.ts +162 -0
- package/src/ci-commit.ts +167 -21
- package/src/ci-own-jobs.test.ts +1 -2
- package/src/ci-own-jobs.ts +1 -2
- package/src/ci-product-words.ts +35 -7
- package/src/ci-product.ts +9 -6
- package/src/cli/handlers/build-pr-loop-control.test.ts +1 -2
- package/src/cli/handlers/build-run-group.test.ts +1 -2
- package/src/cli/handlers/release.ts +60 -7
- package/src/cli/handlers/run-wave.ts +1 -0
- package/src/cli/main.ts +7 -0
- package/src/cli/mcp/product-tools.test.ts +50 -0
- package/src/cli/mcp/product-tools.ts +8 -0
- package/src/cli/mcp/read-only.ts +19 -0
- package/src/cli/mcp/server.test.ts +30 -0
- package/src/cli/mcp/server.ts +28 -5
- package/src/cli/mcp/types.ts +6 -1
- package/src/components/capability.ts +41 -0
- package/src/components/group-digest.ts +20 -0
- package/src/components/groups.ts +3 -13
- package/src/components/index.ts +2 -0
- package/src/components/pr-env-components.test.ts +1 -2
- package/src/components/pr-env-components.ts +1 -2
- package/src/config.ts +38 -3
- package/src/gate-policy-bundle.test.ts +1 -1
- package/src/lexicon.ts +9 -0
- package/src/lifecycle/release-cut.ts +11 -0
- package/src/lifecycle/release-images-dockerfile.test.ts +229 -0
- package/src/lifecycle/release-images.ts +171 -8
- package/src/lifecycle/release-publish.ts +34 -3
- package/src/lifecycle/release-version.test.ts +155 -0
- package/src/lifecycle/release-version.ts +227 -0
- package/src/mcp/types.ts +27 -0
- package/src/notify-message-words.test.ts +185 -0
- package/src/notify-product.ts +16 -4
- package/src/notify-relay.ts +1 -2
- package/src/notify.schema.json +1 -0
- package/src/notify.ts +59 -19
- package/src/op/activities/review-product.test.ts +116 -0
- package/src/op/activities/review-product.ts +199 -0
- package/src/op/gate.ts +46 -0
- package/src/op/index.ts +10 -4
- package/src/op/op-waves-after-plan-wave.test.ts +226 -0
- package/src/op/op-waves-after-plan.ts +170 -5
- package/src/op/op-waves-capability-spec.ts +1 -1
- package/src/op/op-waves-capability.test.ts +6 -0
- package/src/op/op-waves-capability.ts +243 -10
- package/src/op/op-waves-run-hooks.test.ts +184 -0
- package/src/op/op-waves-run-hooks.ts +195 -0
- package/src/op/op-waves-run.ts +240 -16
- package/src/op/op-waves-step-wave.test.ts +277 -0
- package/src/op/op-waves.ts +15 -2
- package/src/op/runtime.ts +2 -0
- package/src/op/schedule-overdue.test.ts +26 -0
- package/src/policy-engine.test.ts +1 -2
- package/src/policy-engine.ts +1 -2
- package/src/pr-forge-reads.test.ts +285 -0
- package/src/pr-forge-reads.ts +424 -0
- package/src/pr-forge.ts +30 -16
- package/src/pr-plan-note.test.ts +105 -0
- package/src/pr-plan-note.ts +520 -0
- package/src/release-floors.ts +19 -1
- package/src/state-export.test.ts +1 -2
- package/src/state-export.ts +1 -2
- package/src/state-migration.test.ts +1 -2
- package/src/state-migration.ts +1 -2
- package/src/state-unlock.test.ts +1 -2
- package/src/state-unlock.ts +1 -2
- package/src/workspace/change-set.schema.json +7 -0
- package/src/workspace/release-workflow.test.ts +18 -0
- 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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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;
|