@intentius/chant 0.124.79 → 0.124.81

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/dist/ci-note-commands.d.ts +199 -0
  2. package/dist/ci-note-commands.d.ts.map +1 -0
  3. package/dist/ci-note-commands.js +372 -0
  4. package/dist/cli/handlers/build.d.ts.map +1 -1
  5. package/dist/cli/handlers/build.js +7 -1
  6. package/dist/cli/handlers/pr-notes.d.ts +13 -0
  7. package/dist/cli/handlers/pr-notes.d.ts.map +1 -0
  8. package/dist/cli/handlers/pr-notes.js +73 -0
  9. package/dist/cli/main.d.ts.map +1 -1
  10. package/dist/cli/main.js +10 -1
  11. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  12. package/dist/cli/mcp/product-tools.js +1 -2
  13. package/dist/cli/parse-args.d.ts.map +1 -1
  14. package/dist/cli/parse-args.js +10 -0
  15. package/dist/cli/registry.d.ts +4 -0
  16. package/dist/cli/registry.d.ts.map +1 -1
  17. package/dist/components/capability.d.ts +22 -0
  18. package/dist/components/capability.d.ts.map +1 -1
  19. package/dist/components/pr-pipeline.d.ts +22 -0
  20. package/dist/components/pr-pipeline.d.ts.map +1 -1
  21. package/dist/components/pr-pipeline.js +26 -0
  22. package/dist/components/product-pipeline.d.ts +12 -0
  23. package/dist/components/product-pipeline.d.ts.map +1 -1
  24. package/dist/components/product-pipeline.js +5 -1
  25. package/dist/lifecycle/release-version.d.ts.map +1 -1
  26. package/dist/lifecycle/release-version.js +1 -2
  27. package/dist/op/index.d.ts +3 -3
  28. package/dist/op/index.d.ts.map +1 -1
  29. package/dist/op/index.js +2 -2
  30. package/dist/op/op-waves-after-plan.d.ts +33 -0
  31. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  32. package/dist/op/op-waves-after-plan.js +41 -4
  33. package/dist/op/op-waves-capability.d.ts +13 -1
  34. package/dist/op/op-waves-capability.d.ts.map +1 -1
  35. package/dist/op/op-waves-capability.js +22 -14
  36. package/dist/op/op-waves-run-hooks.d.ts.map +1 -1
  37. package/dist/op/op-waves-run-hooks.js +1 -2
  38. package/dist/op/op-waves-run.d.ts.map +1 -1
  39. package/dist/op/op-waves-run.js +125 -20
  40. package/dist/op/op-waves.d.ts +9 -5
  41. package/dist/op/op-waves.d.ts.map +1 -1
  42. package/dist/parallelism.d.ts +9 -0
  43. package/dist/parallelism.d.ts.map +1 -1
  44. package/dist/parallelism.js +15 -0
  45. package/dist/pr-forge-reads.d.ts +151 -1
  46. package/dist/pr-forge-reads.d.ts.map +1 -1
  47. package/dist/pr-forge-reads.js +265 -1
  48. package/dist/release-floors.d.ts +15 -1
  49. package/dist/release-floors.d.ts.map +1 -1
  50. package/dist/release-floors.js +17 -3
  51. package/dist/wave-runtime.mjs +288 -288
  52. package/package.json +1 -1
  53. package/src/ci-note-commands.test.ts +377 -0
  54. package/src/ci-note-commands.ts +479 -0
  55. package/src/cli/handlers/build.ts +7 -1
  56. package/src/cli/handlers/pr-notes.ts +70 -0
  57. package/src/cli/main.ts +10 -1
  58. package/src/cli/mcp/product-tools.test.ts +1 -2
  59. package/src/cli/mcp/product-tools.ts +1 -2
  60. package/src/cli/parse-args.ts +8 -0
  61. package/src/cli/registry.ts +4 -0
  62. package/src/components/capability.ts +22 -0
  63. package/src/components/pr-pipeline.ts +35 -0
  64. package/src/components/product-pipeline.test.ts +14 -0
  65. package/src/components/product-pipeline.ts +13 -1
  66. package/src/lifecycle/release-version.ts +1 -2
  67. package/src/op/index.ts +3 -2
  68. package/src/op/op-waves-after-plan-wave.test.ts +2 -3
  69. package/src/op/op-waves-after-plan.ts +61 -4
  70. package/src/op/op-waves-capability.test.ts +3 -1
  71. package/src/op/op-waves-capability.ts +27 -18
  72. package/src/op/op-waves-gate-port.test.ts +231 -0
  73. package/src/op/op-waves-parallel-plans.test.ts +185 -0
  74. package/src/op/op-waves-parallelism.test.ts +5 -0
  75. package/src/op/op-waves-run-hooks.test.ts +2 -3
  76. package/src/op/op-waves-run-hooks.ts +1 -2
  77. package/src/op/op-waves-run.ts +123 -23
  78. package/src/op/op-waves-step-wave.test.ts +3 -4
  79. package/src/op/op-waves.ts +9 -5
  80. package/src/parallelism.ts +26 -0
  81. package/src/pr-forge-reads-compare.test.ts +145 -0
  82. package/src/pr-forge-reads.test.ts +203 -0
  83. package/src/pr-forge-reads.ts +398 -1
  84. package/src/release-floors.ts +24 -3
@@ -579,6 +579,10 @@ export interface ParsedArgs {
579
579
  controlSettings?: Record<string, string>;
580
580
  /** `chant build --pr-loop --stale-notes` (#4628): the note carries its target commit, and a push to the target branch marks open notes stale. */
581
581
  staleNotes?: boolean;
582
+ /** `chant build --pr-loop --note-commands` (#4785): on GitLab, the scheduled job that answers the product's comment commands by polling merge request notes. */
583
+ noteCommands?: boolean;
584
+ /** `chant components pr-notes --locks` (#4785): the pipeline has the lock and unlock jobs, so a lock or unlock note starts them. */
585
+ locks?: boolean;
582
586
  /** `chant components pr-post --stale` (#4628): mark the open pull requests' notes stale after the target branch moved. */
583
587
  stale?: boolean;
584
588
  /** `chant components pr-post --tip <sha>` (#4628): the target branch's commit, which the note carries, or with --stale its commit now. */
@@ -133,6 +133,13 @@ export interface DeployContext {
133
133
  * environment as it is.
134
134
  */
135
135
  processEnv?: Record<string, string>;
136
+ /**
137
+ * The directory the caller runs the step in (#4854): an op wave's `cwd`,
138
+ * absolute. A capability that looks for a project file, such as the
139
+ * nearest `chant.config.*`, starts there when its input names no directory
140
+ * of its own. Absent: `process.cwd()`, as before.
141
+ */
142
+ cwd?: string;
136
143
  /**
137
144
  * A check to call once the engine has initialised the run and before its
138
145
  * plan runs any of the run's code (#4842), such as a check of the module
@@ -141,6 +148,17 @@ export interface DeployContext {
141
148
  * nothing to call.
142
149
  */
143
150
  afterInit?: () => Promise<void>;
151
+ /**
152
+ * Run `fn` alone among the runs beside this one that call it with the
153
+ * same `key` (#4864), and return what it returns. An op wave whose
154
+ * `parallelism` plans and applies several runs at once gives each run the
155
+ * wave's one section, so a capability keeps the part that cannot run twice
156
+ * at once to one run at a time, such as `terraform init` writing the
157
+ * shared provider cache (`TF_PLUGIN_CACHE_DIR`), keyed on that directory.
158
+ * Never nest two calls with the same key: the inner one waits on the
159
+ * outer. Absent where runs go one at a time: then nothing runs beside it.
160
+ */
161
+ serial?: <T>(key: string, fn: () => Promise<T>) => Promise<T>;
144
162
  /**
145
163
  * The run's row lease (#4594), set by an apply path that plans inside its
146
164
  * steps (`run --components`, `components fan-out`, a promote). The driver
@@ -426,6 +444,8 @@ export interface Capability<In = unknown, Out = unknown> {
426
444
  export interface RunDiscoveryContext {
427
445
  /** The environment the wave's runs plan in, as `DeployContext.env`. */
428
446
  env: string;
447
+ /** The directory the wave runs in, as `DeployContext.cwd` (#4854). */
448
+ cwd?: string;
429
449
  /** The wave: its name in the spec and its number from 1. A `rest` wave past the spec's asks with each number in turn. */
430
450
  wave: { name: string; number: number };
431
451
  }
@@ -445,6 +465,8 @@ export interface DiscoveredRuns {
445
465
  */
446
466
  export interface GroupContext {
447
467
  env: string;
468
+ /** The directory the group runs in, as `DeployContext.cwd` (#4854). Absent outside an op wave. */
469
+ cwd?: string;
448
470
  vars?: Record<string, unknown>;
449
471
  /** The group's components, upstreams first. */
450
472
  components: string[];
@@ -369,6 +369,15 @@ export interface PrLoopPipelineOptions {
369
369
  * from `--stale-notes` beside `--pr-loop`. Default false.
370
370
  */
371
371
  staleNotes?: boolean;
372
+ /**
373
+ * GitLab's comment commands (#4785): GitLab starts no pipeline on a note,
374
+ * so a job of the target branch's pipeline, started by a schedule with
375
+ * `CHANT_NOTE_COMMANDS=1`, polls the merge requests' notes and starts the
376
+ * jobs the commands ask for ({@link prNoteCommandsJob}). Refused on GitHub
377
+ * and Forgejo, which start a workflow on a comment. Set from
378
+ * `--note-commands` beside `--pr-loop`. Default off.
379
+ */
380
+ noteCommands?: boolean;
372
381
  /**
373
382
  * The responses to pipeline events (#4629, ../ci-respond.ts), from
374
383
  * `chant build --pr-loop --respond <list>`: the apply job and the
@@ -605,6 +614,32 @@ export function prActionJob(forge: ForgeKind, options: Pick<PrLoopPipelineOption
605
614
  export const PR_COMMENT_PREVIEW_JOB = "comment-preview";
606
615
  /** The job that posts the comment preview's note and status (#4620). */
607
616
  export const PR_COMMENT_PREVIEW_NOTE_JOB = "comment-preview-note";
617
+ /** The job that polls GitLab's merge request notes for comment commands (#4785). */
618
+ export const PR_NOTE_COMMANDS_JOB = "note-commands";
619
+ /** The variable a schedule (or a person) starts a pipeline of the target branch with to run the note-commands job (#4785). */
620
+ export const GITLAB_NOTE_COMMANDS_VAR = "CHANT_NOTE_COMMANDS";
621
+
622
+ /**
623
+ * The note-commands job's command (#4785): `chant components pr-notes
624
+ * --forge gitlab`, with a flag for each job the pipeline has that a command
625
+ * starts. Undefined without `noteCommands`; refused on GitHub and Forgejo,
626
+ * which start a workflow on a comment.
627
+ */
628
+ export function prNoteCommandsJob(forge: ForgeKind, options: Pick<PrLoopPipelineOptions, "noteCommands" | "previewComment" | "applyBeforeMerge" | "applyOnMerge" | "waveGate" | "locks" | "branch" | "words"> = {}): { command: string } | undefined {
629
+ if (!options.noteCommands) return undefined;
630
+ if (forge !== "gitlab") throw new Error(`--note-commands polls GitLab's merge request notes, and ${forge} starts a workflow on a comment; drop --note-commands`);
631
+ const words = resolveProductWords(options.words);
632
+ const command = [
633
+ "chant", "components", "pr-notes", "--forge", "gitlab",
634
+ ...(options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
635
+ ...(options.previewComment ? ["--preview-comment"] : []),
636
+ ...(options.applyBeforeMerge ? ["--apply-before-merge"] : []),
637
+ ...(options.applyOnMerge || options.waveGate ? ["--apply-on-merge"] : []),
638
+ ...(options.locks === "plan" ? ["--locks"] : []),
639
+ ].join(" ");
640
+ return { command: withProductBin(command, words.bin) };
641
+ }
642
+
608
643
  /** The GitLab variable a pipeline of the target branch is started with to preview a merge request again (#4620). */
609
644
  export const GITLAB_PREVIEW_PR_VAR = "CHANT_PREVIEW_PR";
610
645
  /** The variable the GitHub-shaped preview job's checkout script reads the pull request's head ref from (#4620). */
@@ -225,3 +225,17 @@ describe("the commit jobs (#4722)", () => {
225
225
  expect(() => productCheckCommit(words, "fmt-check", { command: [], allowed: ["infra/"] })).toThrow(/argv/);
226
226
  });
227
227
  });
228
+
229
+ describe("GitLab's comment commands by polling the notes (#4785)", () => {
230
+ test("noteCommands is one switch: the note-commands job's command, with the jobs a command starts", () => {
231
+ const jobs = productPipelineJobs("gitlab", "production", { words: PLYWOOD, waves, locks: "plan", previewComment: true, noteCommands: true });
232
+ expect(jobs.noteCommands!.command).toBe("npx --no-install plywood components pr-notes --forge gitlab --preview-comment --apply-on-merge --locks");
233
+ expect(productPipelineJobs("gitlab", "production", { words: PLYWOOD, waves, locks: "plan" }).noteCommands).toBeUndefined();
234
+ });
235
+
236
+ test("refused on GitHub and Forgejo, which start a workflow on a comment", () => {
237
+ for (const forge of ["github", "forgejo"] as const) {
238
+ expect(() => productPipelineJobs(forge, "production", { words: PLYWOOD, waves, locks: "plan", noteCommands: true })).toThrow(/--note-commands polls GitLab's merge request notes/);
239
+ }
240
+ });
241
+ });
@@ -34,7 +34,7 @@ import {
34
34
  type CiProductWords,
35
35
  type CiProductWordsInput,
36
36
  } from "../ci-product-words";
37
- import { prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
37
+ import { prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prNoteCommandsJob, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
38
38
  import type { DriverComponent } from "./driver";
39
39
  import type { ScheduledOpSpec } from "../lexicon";
40
40
  import type { CiRunner } from "../ci-jobs";
@@ -155,6 +155,15 @@ export interface ProductPipelineJobs {
155
155
  * lexicons render the same job, `stale-notes`.
156
156
  */
157
157
  stale?: { command: string; env: Record<string, string>; runner?: CiRunner };
158
+ /**
159
+ * GitLab's comment commands (#4785), with `noteCommands`: the command of
160
+ * the `note-commands` job, which a schedule starts with
161
+ * `CHANT_NOTE_COMMANDS=1` on the target branch. It polls the merge
162
+ * requests' notes and starts the jobs the commands ask for. The GitLab
163
+ * lexicon renders the same job from `chant build --pr-loop
164
+ * --note-commands`. Refused on GitHub and Forgejo.
165
+ */
166
+ noteCommands?: { command: string; runner?: CiRunner };
158
167
  /**
159
168
  * The agent (#4616), with `agent`: the comment it answers, `/<product>
160
169
  * agent <ask>`, and the scheduled Op spec whose generated workflow runs
@@ -301,6 +310,9 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
301
310
  if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
302
311
  const stale = prStaleJob(forge, env, prLoop, member);
303
312
  if (stale) out.stale = { ...stale, ...defaultRunner };
313
+ // #4785: GitLab's comment commands, polled from the notes; waves on merge are retried by an apply on a merged merge request.
314
+ const notes = prNoteCommandsJob(forge, { ...prLoop, ...(options.waves || options.componentWaves ? { applyOnMerge: true } : {}) });
315
+ if (notes) out.noteCommands = { ...notes, ...defaultRunner };
304
316
  const preview = prCommentPreviewJob(forge, env, prLoop, member);
305
317
  if (preview) out.preview = { ...preview, ...(defaultRunner.runner !== undefined ? { noteRunner: defaultRunner.runner } : {}) };
306
318
  // #4616: the agent answers its comment from a workflow of its own, generated from this spec.
@@ -29,10 +29,9 @@
29
29
  import { execFileSync } from "node:child_process";
30
30
  import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
31
31
  import { isAbsolute, posix, relative, resolve } from "node:path";
32
- import { NEXT_RELEASE } from "../release-floors";
33
32
 
34
33
  /** The first chant with `release.version` and `chant release stamp` (#4840). Products feature-detect on it. */
35
- export const RELEASE_VERSION_FLOOR = NEXT_RELEASE;
34
+ export const RELEASE_VERSION_FLOOR = "0.124.79";
36
35
 
37
36
  /** `release.version` in `chant.config.ts`. */
38
37
  export interface ReleaseVersionConfig {
package/src/op/index.ts CHANGED
@@ -124,6 +124,7 @@ export type {
124
124
  export {
125
125
  OP_WAVE_COST_FORMATS,
126
126
  OP_WAVE_COST_MEMBER,
127
+ OP_WAVE_PARALLEL_STEP_FLOOR,
127
128
  OP_WAVE_STEP_WAVE_FLOOR,
128
129
  OP_WAVE_TOGETHER_MEMBER,
129
130
  opWaveCostVerdict,
@@ -141,8 +142,8 @@ export type { OpWaveNewerCommit, OpWaveNewerCommitPort } from "./op-waves-stand-
141
142
  export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems, releaseOfCommit } from "./op-waves-release";
142
143
  export { gitOpWaveReleasePort } from "./op-waves-release-port";
143
144
  export type { OpWaveReleaseNames, OpWaveReleaseOutcome, OpWaveReleasePort, OpWaveReleaseRequest } from "./op-waves-release";
144
- export { OP_WAVE_AFTER_PLAN_WAVE_FLOOR, foldPolicyRows, opWaveAfterPlanProblems, opWaveAfterPlanResultProblems, opWaveAfterPlanWaveResultProblems, runOpWaveAfterPlanHooks } from "./op-waves-after-plan";
145
- export type { OpWaveAfterPlanHook, OpWaveAfterPlanOutcome, OpWaveAfterPlanResult, OpWaveAfterPlanRun, OpWaveAfterPlanRunOutcome, OpWaveAfterPlanWave, OpWaveAfterPlanWaveOutcome, OpWaveAfterPlanWaveResult } from "./op-waves-after-plan";
145
+ export { OP_WAVE_AFTER_PLAN_WAVE_FLOOR, OP_WAVE_ANSWER_APPROVALS_FLOOR, foldPolicyRows, opWaveAfterPlanProblems, opWaveAfterPlanResultProblems, opWaveAfterPlanWaveResultProblems, runOpWaveAfterPlanHooks } from "./op-waves-after-plan";
146
+ export type { OpWaveAfterPlanHook, OpWaveAnswerApproval, OpWaveAfterPlanOutcome, OpWaveAfterPlanResult, OpWaveAfterPlanRun, OpWaveAfterPlanRunOutcome, OpWaveAfterPlanWave, OpWaveAfterPlanWaveOutcome, OpWaveAfterPlanWaveResult } from "./op-waves-after-plan";
146
147
  export { OP_WAVE_AFTER_PLAN_FLOOR } from "./runtime";
147
148
  export { OP_WAVE_RUN_HOOKS_FLOOR, opWaveRunHooksProblems } from "./op-waves-run-hooks";
148
149
  export type { OpWaveAfterApplyResult, OpWaveBeforePlanResult, OpWaveRunHookApplied, OpWaveRunHookPlanned, OpWaveRunHookRun, OpWaveRunHooks } from "./op-waves-run-hooks";
@@ -217,10 +217,9 @@ describe("the after-plan hook's wave answer (#4842)", () => {
217
217
  expect(opWaveAfterPlanResultProblems({ overriders: "carol" })).toEqual(["`overriders` must be a list of principals"]);
218
218
  });
219
219
 
220
- test("the floor is the next release", async () => {
220
+ test("the floor is 0.124.79", async () => {
221
221
  const entry = await import("./index");
222
- const { NEXT_RELEASE } = await import("../release-floors");
223
- expect(entry.OP_WAVE_AFTER_PLAN_WAVE_FLOOR).toBe(NEXT_RELEASE);
222
+ expect(entry.OP_WAVE_AFTER_PLAN_WAVE_FLOOR).toBe("0.124.79");
224
223
  });
225
224
  });
226
225
 
@@ -48,7 +48,6 @@
48
48
  */
49
49
 
50
50
  import { isAbsolute } from "node:path";
51
- import { NEXT_RELEASE } from "../release-floors";
52
51
  import type { ChangeSetPart } from "../change-set";
53
52
  import type { OpRunPolicyRow } from "./runtime";
54
53
  import type { WaveMember } from "../wave-engine";
@@ -56,7 +55,34 @@ import { OP_WAVE_HOOK_FAILURES, opWaveHookRuns, type OpWaveHookFailure } from ".
56
55
  import { OP_WAVE_PENDING_RESERVED, type OpWaveHookOutcome } from "./stage-hooks";
57
56
 
58
57
  /** 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;
58
+ export const OP_WAVE_AFTER_PLAN_WAVE_FLOOR = "0.124.79";
59
+
60
+ /** The first chant whose wave answer takes `approvals`, recorded at the wave's gate before chant decides it (terragucci issue 1303). */
61
+ export const OP_WAVE_ANSWER_APPROVALS_FLOOR = "0.124.80";
62
+
63
+ /**
64
+ * An approval a product settled before the gate (terragucci issue 1303),
65
+ * which chant records at the wave's gate for the digest it decides: a
66
+ * covered round's (the approval of the plans these are covered by), the
67
+ * rest of a stopped apply's (the approval the stopped apply ran under), or
68
+ * a review the product read itself. It counts as any approval does, under
69
+ * the wave's approval mode, `approvals.involved` and `approvals.quorum`.
70
+ */
71
+ export interface OpWaveAnswerApproval {
72
+ /** Who approved, as the ledger names an approver. */
73
+ resolvedBy: string;
74
+ /** Why this approval stands for these plans, for the ledger and the log. */
75
+ note: string;
76
+ /** Where it was approved, an http or https URL. */
77
+ url?: string;
78
+ /**
79
+ * A review the product read (`approvals.reviewLedger` names the spec's op):
80
+ * written as the product's own review line, `via: "pr-review"` with the
81
+ * pull request, its head and its reviewers, which proves each reviewer
82
+ * under `pr-review`.
83
+ */
84
+ review?: { pr: number; head: string; reviewers: string[] };
85
+ }
60
86
 
61
87
  /** One planned run, as an after-plan hook in the job's process sees it (#4614). */
62
88
  export interface OpWaveAfterPlanRun {
@@ -124,6 +150,8 @@ export interface OpWaveAfterPlanWaveResult {
124
150
  overridersSource?: string;
125
151
  /** The product's report of these plans: stored beside the pending fact, and written for the respond job after the plans moved. */
126
152
  report?: string;
153
+ /** Approvals the product settled before the gate (terragucci issue 1303), recorded at the gate for the wave's digest before it is decided. */
154
+ approvals?: OpWaveAnswerApproval[];
127
155
  }
128
156
 
129
157
  /** An after-plan hook in the wave job's process (#4614). */
@@ -189,7 +217,7 @@ const principals = (v: unknown): v is string[] => Array.isArray(v) && v.every((p
189
217
  /** 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
218
  export function opWaveAfterPlanWaveResultProblems(value: unknown, targets: readonly string[]): string[] {
191
219
  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? }"];
220
+ if (typeof value !== "object" || Array.isArray(value)) return ["the wave answer must be { pending?, members?, holds?, overriders?, overridersSource?, report?, approvals? }"];
193
221
  const r = value as Record<string, unknown>;
194
222
  const problems: string[] = [];
195
223
  if (r.pending !== undefined) {
@@ -220,6 +248,30 @@ export function opWaveAfterPlanWaveResultProblems(value: unknown, targets: reado
220
248
  }
221
249
  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
250
  if (r.report !== undefined && typeof r.report !== "string") problems.push("`report` must be the report's text");
251
+ if (r.approvals !== undefined) {
252
+ if (!Array.isArray(r.approvals)) problems.push("`approvals` must be a list of { resolvedBy, note, url?, review? }");
253
+ else (r.approvals as unknown[]).forEach((x, i) => problems.push(...answerApprovalProblems(x, `approvals[${i}]`)));
254
+ }
255
+ return problems;
256
+ }
257
+
258
+ /** What is wrong with one of a wave answer's `approvals` (terragucci issue 1303). */
259
+ function answerApprovalProblems(value: unknown, at: string): string[] {
260
+ const a = value as Partial<Record<keyof OpWaveAnswerApproval, unknown>> | null;
261
+ if (!a || typeof a !== "object" || Array.isArray(a)) return [`${at} must be { resolvedBy, note, url?, review? }`];
262
+ const problems: string[] = [];
263
+ if (typeof a.resolvedBy !== "string" || a.resolvedBy.trim() === "") problems.push(`${at}.resolvedBy must name the approver`);
264
+ if (typeof a.note !== "string" || a.note.trim() === "") problems.push(`${at}.note must say why the approval stands for these plans`);
265
+ if (a.url !== undefined && (typeof a.url !== "string" || !/^https?:\/\/\S+$/.test(a.url))) problems.push(`${at}.url must be an http or https URL`);
266
+ if (a.review !== undefined) {
267
+ const r = a.review as { pr?: unknown; head?: unknown; reviewers?: unknown } | null;
268
+ if (!r || typeof r !== "object") problems.push(`${at}.review must be { pr, head, reviewers }`);
269
+ else {
270
+ if (typeof r.pr !== "number" || !Number.isInteger(r.pr) || r.pr < 1) problems.push(`${at}.review.pr must be the pull request's number`);
271
+ if (typeof r.head !== "string" || r.head.trim() === "") problems.push(`${at}.review.head must be the commit the review approved`);
272
+ if (!principals(r.reviewers) || r.reviewers.length === 0) problems.push(`${at}.review.reviewers must list the reviewers`);
273
+ }
274
+ }
223
275
  return problems;
224
276
  }
225
277
 
@@ -240,6 +292,8 @@ export interface OpWaveAfterPlanWaveOutcome {
240
292
  overriders?: string[];
241
293
  overridersSource?: string;
242
294
  report?: string;
295
+ /** Each hook's `approvals`, in order (terragucci issue 1303). */
296
+ approvals: OpWaveAnswerApproval[];
243
297
  }
244
298
 
245
299
  /** What the after-plan hooks in the job's process came to (#4614). */
@@ -266,7 +320,7 @@ export async function runOpWaveAfterPlanHooks(
266
320
  runs: readonly OpWaveAfterPlanRun[],
267
321
  log: (line: string) => void,
268
322
  ): Promise<OpWaveAfterPlanOutcome> {
269
- const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map(), wave: { members: [], holds: [] } };
323
+ const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map(), wave: { members: [], holds: [], approvals: [] } };
270
324
  const targets = runs.map((r) => r.target);
271
325
  for (const hook of hooks) {
272
326
  const mine = opWaveHookRuns(hook, runs);
@@ -349,6 +403,9 @@ function foldWaveAnswer(into: OpWaveAfterPlanWaveOutcome, answer: OpWaveAfterPla
349
403
  if (answer.overriders) into.overriders = [...new Set(answer.overriders)].sort();
350
404
  if (answer.overridersSource) into.overridersSource = answer.overridersSource;
351
405
  if (answer.report !== undefined) into.report = answer.report;
406
+ for (const a of answer.approvals ?? []) {
407
+ into.approvals.push({ resolvedBy: a.resolvedBy, note: a.note, ...(a.url ? { url: a.url } : {}), ...(a.review ? { review: { pr: a.review.pr, head: a.review.head, reviewers: [...a.review.reviewers] } } : {}) });
408
+ }
352
409
  }
353
410
 
354
411
  /** Fold policy rows into a run's denial and hold: the rules of every `denied` row, and of every `held` row. */
@@ -81,7 +81,9 @@ describe("op waves through a capability step (#4545)", () => {
81
81
  { root: "app", lockTimeout: "5m", vars: { size: "s" } },
82
82
  ]);
83
83
  // #4613: the plan reads its policy packs at the wave's base.
84
- expect(calls.planned[0]!.ctx).toEqual({ env: "dev", component: "network", policyBase: "b".repeat(40) });
84
+ // #4854: and runs in the wave's directory.
85
+ expect(calls.planned[0]!.ctx).toEqual({ env: "dev", component: "network", cwd: h.cwd, policyBase: "b".repeat(40) });
86
+ expect(calls.ran[0]!.ctx.cwd).toBe(h.cwd);
85
87
  // The apply gets the plan's artifact under the capability's member.
86
88
  expect(calls.ran[0]!.ctx.plans).toEqual({ network: { planFile: "network.tfplan", planJson: "network.tfplan.json" } });
87
89
  // The plan file hooks read carries the digest, the artifact and the part.
@@ -72,19 +72,19 @@
72
72
 
73
73
  import { spawnSync } from "node:child_process";
74
74
  import { existsSync, mkdirSync, writeFileSync } from "node:fs";
75
- import { dirname, join } from "node:path";
75
+ import { dirname, join, resolve } from "node:path";
76
76
  import type { Capability, CapabilityPlan, CapabilityRegistry, DeployContext, GroupContext, GroupMember } from "../components/capability";
77
77
  import { isPlanMovedError } from "../components/capability";
78
78
  import type { CapabilityTraceFacts } from "../otlp";
79
79
  import { composeChangeSet, type ChangeSetDocument, type ChangeSetPart } from "../change-set";
80
80
  import { computePlanDigest } from "../lifecycle/plan-digest";
81
81
  import { groupDigest } from "../components/group-digest";
82
- import { NEXT_RELEASE } from "../release-floors";
83
82
  import type { GatePolicyExec, GatePolicyRun } from "../gate-policy";
84
83
  import type { ResolvedGatePolicySource } from "../policy-source";
85
84
  import type { WaveMember } from "../wave-engine";
86
85
  import type { OpWave, OpWaveRun, OpWavesSpec } from "./op-waves";
87
86
  import { resolvePlannedLock, type LockGrain, type PlannedLock } from "../lifecycle/lock-rows";
87
+ import { NEXT_RELEASE } from "../release-floors";
88
88
 
89
89
  import { OP_WAVE_COST_FORMATS, OP_WAVE_COST_MEMBER, type OpWaveCostFormat, type OpWaveCostHold, type OpWaveStep } from "./op-waves-capability-spec";
90
90
 
@@ -115,8 +115,9 @@ export function opWaveDiscoverInput(spec: Pick<OpWavesSpec, "op" | "step">, wave
115
115
  }
116
116
 
117
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. */
118
- export function opWaveStepContext(spec: Pick<OpWavesSpec, "labels">, wave: Pick<OpWave, "name">, run: OpWaveRun): DeployContext {
119
- return { env: spec.labels?.Env ?? wave.name, component: run.target };
118
+ export function opWaveStepContext(spec: Pick<OpWavesSpec, "labels">, wave: Pick<OpWave, "name">, run: OpWaveRun, cwd?: string): DeployContext {
119
+ // #4854: the wave's directory, where a capability looks for its project's config.
120
+ return { env: spec.labels?.Env ?? wave.name, component: run.target, ...(cwd !== undefined ? { cwd: resolve(cwd) } : {}) };
120
121
  }
121
122
 
122
123
  const registries = new WeakMap<object, Promise<CapabilityRegistry>>();
@@ -168,7 +169,15 @@ export interface OpWaveStepGroup {
168
169
  export const OP_WAVE_TOGETHER_MEMBER = "(wave plan)";
169
170
 
170
171
  /** The release that has `discover` with a `step`, and `together` waves (#4842). */
171
- export const OP_WAVE_STEP_WAVE_FLOOR = NEXT_RELEASE;
172
+ export const OP_WAVE_STEP_WAVE_FLOOR = "0.124.79";
173
+
174
+ /**
175
+ * The first chant whose step plans a wave's runs `parallelism` at once, as it
176
+ * applies them, and hands each run the wave's serial section
177
+ * (`DeployContext.serial`), where `terraform-apply` and `terragrunt-apply`
178
+ * take their inits one at a time on a shared provider cache (#4864).
179
+ */
180
+ export const OP_WAVE_PARALLEL_STEP_FLOOR = NEXT_RELEASE;
172
181
 
173
182
  /** Whether a part changes nothing, and whether it destroys or replaces something. A plan that changes only outputs changes something (#4849). */
174
183
  export function partEffects(part: ChangeSetPart | undefined): { empty: boolean; destructive: boolean } {
@@ -184,7 +193,7 @@ function resolveCapability(registry: CapabilityRegistry, kind: string): Capabili
184
193
 
185
194
  /** 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. */
186
195
  export async function planOpWaveStep(
187
- at: { spec: OpWavesSpec; wave: OpWave; cwd: string; registry: CapabilityRegistry; planPath: string; lockGrain?: LockGrain | null; policyBase?: string; processEnv?: Record<string, string>; afterInit?: () => Promise<void> },
196
+ at: { spec: OpWavesSpec; wave: OpWave; cwd: string; registry: CapabilityRegistry; planPath: string; lockGrain?: LockGrain | null; policyBase?: string; processEnv?: Record<string, string>; afterInit?: () => Promise<void>; serial?: DeployContext["serial"] },
188
197
  run: OpWaveRun,
189
198
  ): Promise<OpWaveStepPlan> {
190
199
  const { spec, wave, cwd, registry } = at;
@@ -195,7 +204,7 @@ export async function planOpWaveStep(
195
204
  let lock: PlannedLock;
196
205
  try {
197
206
  // #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);
207
+ planned = await capability.plan({ ...opWaveStepContext(spec, wave, run, cwd), ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}), ...(at.policyBase ? { policyBase: at.policyBase } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}), ...(at.afterInit ? { afterInit: at.afterInit } : {}), ...(at.serial ? { serial: at.serial } : {}) }, input as never);
199
208
  // #4552: the run's grain (declared at base, else its lexicon's) and, on the resource grain, the rows its apply leases.
200
209
  lock = await resolvePlannedLock(capability, input, planned, at.lockGrain);
201
210
  } catch (err) {
@@ -250,14 +259,14 @@ function writeStepPlanFile(file: string, plan: OpWaveStepPlan): void {
250
259
  * capability's `discoverRuns` finds for wave `k`, each a run of the spec's
251
260
  * op, and how many waves it found.
252
261
  */
253
- export async function discoverOpWaveStepRuns(at: { spec: OpWavesSpec; wave: OpWave; k: number; registry: CapabilityRegistry }): Promise<{ runs: OpWaveRun[]; waves?: number }> {
262
+ export async function discoverOpWaveStepRuns(at: { spec: OpWavesSpec; wave: OpWave; k: number; registry: CapabilityRegistry; cwd?: string }): Promise<{ runs: OpWaveRun[]; waves?: number }> {
254
263
  const { spec, wave, k } = at;
255
264
  const kind = spec.step!.kind;
256
265
  const capability = resolveCapability(at.registry, kind);
257
266
  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
267
  let found: { targets?: unknown; waves?: unknown };
259
268
  try {
260
- found = await capability.discoverRuns({ env: spec.labels?.Env ?? wave.name, wave: { name: wave.name, number: k } }, opWaveDiscoverInput(spec, wave) as never);
269
+ found = await capability.discoverRuns({ env: spec.labels?.Env ?? wave.name, wave: { name: wave.name, number: k }, ...(at.cwd !== undefined ? { cwd: resolve(at.cwd) } : {}) }, opWaveDiscoverInput(spec, wave) as never);
261
270
  } catch (err) {
262
271
  throw new Error(`finding the runs of wave ${k} (${wave.name}) through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
263
272
  }
@@ -280,8 +289,8 @@ function waveGroupMembers(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWave
280
289
  });
281
290
  }
282
291
 
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) };
292
+ function waveGroupContext(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWaveRun[], cwd?: string): GroupContext {
293
+ return { env: spec.labels?.Env ?? wave.name, ...(cwd !== undefined ? { cwd: resolve(cwd) } : {}), components: runs.map((r) => r.target) };
285
294
  }
286
295
 
287
296
  function requireGroup(capability: Capability<never, unknown>, kind: string, wave: OpWave): void {
@@ -315,7 +324,7 @@ export async function planOpWaveStepGroup(
315
324
  const members = waveGroupMembers(spec, wave, runs, (run) => {
316
325
  const own = at.runCtx?.(run.target) ?? {};
317
326
  return {
318
- ...opWaveStepContext(spec, wave, run),
327
+ ...opWaveStepContext(spec, wave, run, at.cwd),
319
328
  ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}),
320
329
  ...(at.policyBase ? { policyBase: at.policyBase } : {}),
321
330
  ...(own.processEnv ? { processEnv: own.processEnv } : {}),
@@ -324,7 +333,7 @@ export async function planOpWaveStepGroup(
324
333
  });
325
334
  let planned: { members?: Record<string, CapabilityPlan>; digest?: unknown; artifact?: unknown };
326
335
  try {
327
- planned = await capability.planGroup!(waveGroupContext(spec, wave, runs), members as never);
336
+ planned = await capability.planGroup!(waveGroupContext(spec, wave, runs, at.cwd), members as never);
328
337
  } catch (err) {
329
338
  throw new Error(`planning wave "${wave.name}" together through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
330
339
  }
@@ -376,7 +385,7 @@ export async function planOpWaveStepGroup(
376
385
  * when it is a moved plan (`isPlanMovedError`).
377
386
  */
378
387
  export async function applyOpWaveStepGroup(
379
- at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; runEnv?: (target: string) => Record<string, string> | undefined },
388
+ at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; runEnv?: (target: string) => Record<string, string> | undefined; cwd?: string },
380
389
  runs: ReadonlyArray<{ run: OpWaveRun; plan: OpWaveStepPlan }>,
381
390
  ): Promise<OpWaveStepApply[]> {
382
391
  const { spec, wave } = at;
@@ -395,12 +404,12 @@ export async function applyOpWaveStepGroup(
395
404
  const members = waveGroupMembers(spec, wave, runs.map((r) => r.run), (run) => {
396
405
  const plan = byTarget.get(run.target)!;
397
406
  const env = at.runEnv?.(run.target);
398
- return { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
407
+ return { ...opWaveStepContext(spec, wave, run, at.cwd), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
399
408
  });
400
409
  const plans = Object.fromEntries(runs.flatMap((r) => (group.plans[r.run.target] ? [[r.run.target, group.plans[r.run.target]!] as const] : [])));
401
410
  let got: { members?: Record<string, { status: string; outputs?: Record<string, unknown>; error?: string }>; error?: string };
402
411
  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);
412
+ got = await capability.runGroup!(waveGroupContext(spec, wave, runs.map((r) => r.run), at.cwd), { ...(group.artifact !== undefined ? { artifact: group.artifact } : {}), digest: group.digest, plans }, members as never);
404
413
  } catch (err) {
405
414
  const reason = err instanceof Error ? err.message : String(err);
406
415
  const moved = isPlanMovedError(err);
@@ -458,7 +467,7 @@ export async function opWaveStepFacts(
458
467
  }
459
468
 
460
469
  /** Apply one run through the spec's step (#4545), with the plan the gate decided. */
461
- export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; processEnv?: Record<string, string> }, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply> {
470
+ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; processEnv?: Record<string, string>; cwd?: string; serial?: DeployContext["serial"] }, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply> {
462
471
  const { spec, wave, registry } = at;
463
472
  let capability: Capability<never, unknown>;
464
473
  try {
@@ -466,7 +475,7 @@ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; reg
466
475
  } catch (err) {
467
476
  return { outcome: "failed", reason: err instanceof Error ? err.message : String(err) };
468
477
  }
469
- const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}) };
478
+ const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run, at.cwd), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}), ...(at.serial ? { serial: at.serial } : {}) };
470
479
  const input = opWaveStepInput(spec, wave, run);
471
480
  try {
472
481
  const output = await capability.run(ctx, input as never);