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