@intentius/chant 0.124.79 → 0.124.80

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 (75) 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 +11 -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 +2 -2
  28. package/dist/op/index.d.ts.map +1 -1
  29. package/dist/op/index.js +1 -1
  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 -3
  33. package/dist/op/op-waves-capability.d.ts +4 -1
  34. package/dist/op/op-waves-capability.d.ts.map +1 -1
  35. package/dist/op/op-waves-capability.js +14 -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 +78 -12
  40. package/dist/pr-forge-reads.d.ts +151 -1
  41. package/dist/pr-forge-reads.d.ts.map +1 -1
  42. package/dist/pr-forge-reads.js +265 -1
  43. package/dist/release-floors.d.ts +15 -1
  44. package/dist/release-floors.d.ts.map +1 -1
  45. package/dist/release-floors.js +17 -3
  46. package/dist/wave-runtime.mjs +272 -272
  47. package/package.json +1 -1
  48. package/src/ci-note-commands.test.ts +377 -0
  49. package/src/ci-note-commands.ts +479 -0
  50. package/src/cli/handlers/build.ts +7 -1
  51. package/src/cli/handlers/pr-notes.ts +70 -0
  52. package/src/cli/main.ts +10 -1
  53. package/src/cli/mcp/product-tools.test.ts +1 -2
  54. package/src/cli/mcp/product-tools.ts +1 -2
  55. package/src/cli/parse-args.ts +8 -0
  56. package/src/cli/registry.ts +4 -0
  57. package/src/components/capability.ts +11 -0
  58. package/src/components/pr-pipeline.ts +35 -0
  59. package/src/components/product-pipeline.test.ts +14 -0
  60. package/src/components/product-pipeline.ts +13 -1
  61. package/src/lifecycle/release-version.ts +1 -2
  62. package/src/op/index.ts +2 -2
  63. package/src/op/op-waves-after-plan-wave.test.ts +2 -3
  64. package/src/op/op-waves-after-plan.ts +61 -3
  65. package/src/op/op-waves-capability.test.ts +3 -1
  66. package/src/op/op-waves-capability.ts +17 -17
  67. package/src/op/op-waves-gate-port.test.ts +232 -0
  68. package/src/op/op-waves-run-hooks.test.ts +2 -3
  69. package/src/op/op-waves-run-hooks.ts +1 -2
  70. package/src/op/op-waves-run.ts +78 -14
  71. package/src/op/op-waves-step-wave.test.ts +3 -4
  72. package/src/pr-forge-reads-compare.test.ts +145 -0
  73. package/src/pr-forge-reads.test.ts +203 -0
  74. package/src/pr-forge-reads.ts +398 -1
  75. 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
@@ -426,6 +433,8 @@ export interface Capability<In = unknown, Out = unknown> {
426
433
  export interface RunDiscoveryContext {
427
434
  /** The environment the wave's runs plan in, as `DeployContext.env`. */
428
435
  env: string;
436
+ /** The directory the wave runs in, as `DeployContext.cwd` (#4854). */
437
+ cwd?: string;
429
438
  /** 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
439
  wave: { name: string; number: number };
431
440
  }
@@ -445,6 +454,8 @@ export interface DiscoveredRuns {
445
454
  */
446
455
  export interface GroupContext {
447
456
  env: string;
457
+ /** The directory the group runs in, as `DeployContext.cwd` (#4854). Absent outside an op wave. */
458
+ cwd?: string;
448
459
  vars?: Record<string, unknown>;
449
460
  /** The group's components, upstreams first. */
450
461
  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
@@ -141,8 +141,8 @@ export type { OpWaveNewerCommit, OpWaveNewerCommitPort } from "./op-waves-stand-
141
141
  export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems, releaseOfCommit } from "./op-waves-release";
142
142
  export { gitOpWaveReleasePort } from "./op-waves-release-port";
143
143
  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";
144
+ export { OP_WAVE_AFTER_PLAN_WAVE_FLOOR, OP_WAVE_ANSWER_APPROVALS_FLOOR, foldPolicyRows, opWaveAfterPlanProblems, opWaveAfterPlanResultProblems, opWaveAfterPlanWaveResultProblems, runOpWaveAfterPlanHooks } from "./op-waves-after-plan";
145
+ export type { OpWaveAfterPlanHook, OpWaveAnswerApproval, OpWaveAfterPlanOutcome, OpWaveAfterPlanResult, OpWaveAfterPlanRun, OpWaveAfterPlanRunOutcome, OpWaveAfterPlanWave, OpWaveAfterPlanWaveOutcome, OpWaveAfterPlanWaveResult } from "./op-waves-after-plan";
146
146
  export { OP_WAVE_AFTER_PLAN_FLOOR } from "./runtime";
147
147
  export { OP_WAVE_RUN_HOOKS_FLOOR, opWaveRunHooksProblems } from "./op-waves-run-hooks";
148
148
  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
 
@@ -56,7 +56,34 @@ import { OP_WAVE_HOOK_FAILURES, opWaveHookRuns, type OpWaveHookFailure } from ".
56
56
  import { OP_WAVE_PENDING_RESERVED, type OpWaveHookOutcome } from "./stage-hooks";
57
57
 
58
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;
59
+ export const OP_WAVE_AFTER_PLAN_WAVE_FLOOR = "0.124.79";
60
+
61
+ /** The first chant whose wave answer takes `approvals`, recorded at the wave's gate before chant decides it (terragucci issue 1303). */
62
+ export const OP_WAVE_ANSWER_APPROVALS_FLOOR = NEXT_RELEASE;
63
+
64
+ /**
65
+ * An approval a product settled before the gate (terragucci issue 1303),
66
+ * which chant records at the wave's gate for the digest it decides: a
67
+ * covered round's (the approval of the plans these are covered by), the
68
+ * rest of a stopped apply's (the approval the stopped apply ran under), or
69
+ * a review the product read itself. It counts as any approval does, under
70
+ * the wave's approval mode, `approvals.involved` and `approvals.quorum`.
71
+ */
72
+ export interface OpWaveAnswerApproval {
73
+ /** Who approved, as the ledger names an approver. */
74
+ resolvedBy: string;
75
+ /** Why this approval stands for these plans, for the ledger and the log. */
76
+ note: string;
77
+ /** Where it was approved, an http or https URL. */
78
+ url?: string;
79
+ /**
80
+ * A review the product read (`approvals.reviewLedger` names the spec's op):
81
+ * written as the product's own review line, `via: "pr-review"` with the
82
+ * pull request, its head and its reviewers, which proves each reviewer
83
+ * under `pr-review`.
84
+ */
85
+ review?: { pr: number; head: string; reviewers: string[] };
86
+ }
60
87
 
61
88
  /** One planned run, as an after-plan hook in the job's process sees it (#4614). */
62
89
  export interface OpWaveAfterPlanRun {
@@ -124,6 +151,8 @@ export interface OpWaveAfterPlanWaveResult {
124
151
  overridersSource?: string;
125
152
  /** The product's report of these plans: stored beside the pending fact, and written for the respond job after the plans moved. */
126
153
  report?: string;
154
+ /** Approvals the product settled before the gate (terragucci issue 1303), recorded at the gate for the wave's digest before it is decided. */
155
+ approvals?: OpWaveAnswerApproval[];
127
156
  }
128
157
 
129
158
  /** An after-plan hook in the wave job's process (#4614). */
@@ -189,7 +218,7 @@ const principals = (v: unknown): v is string[] => Array.isArray(v) && v.every((p
189
218
  /** 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
219
  export function opWaveAfterPlanWaveResultProblems(value: unknown, targets: readonly string[]): string[] {
191
220
  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? }"];
221
+ if (typeof value !== "object" || Array.isArray(value)) return ["the wave answer must be { pending?, members?, holds?, overriders?, overridersSource?, report?, approvals? }"];
193
222
  const r = value as Record<string, unknown>;
194
223
  const problems: string[] = [];
195
224
  if (r.pending !== undefined) {
@@ -220,6 +249,30 @@ export function opWaveAfterPlanWaveResultProblems(value: unknown, targets: reado
220
249
  }
221
250
  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
251
  if (r.report !== undefined && typeof r.report !== "string") problems.push("`report` must be the report's text");
252
+ if (r.approvals !== undefined) {
253
+ if (!Array.isArray(r.approvals)) problems.push("`approvals` must be a list of { resolvedBy, note, url?, review? }");
254
+ else (r.approvals as unknown[]).forEach((x, i) => problems.push(...answerApprovalProblems(x, `approvals[${i}]`)));
255
+ }
256
+ return problems;
257
+ }
258
+
259
+ /** What is wrong with one of a wave answer's `approvals` (terragucci issue 1303). */
260
+ function answerApprovalProblems(value: unknown, at: string): string[] {
261
+ const a = value as Partial<Record<keyof OpWaveAnswerApproval, unknown>> | null;
262
+ if (!a || typeof a !== "object" || Array.isArray(a)) return [`${at} must be { resolvedBy, note, url?, review? }`];
263
+ const problems: string[] = [];
264
+ if (typeof a.resolvedBy !== "string" || a.resolvedBy.trim() === "") problems.push(`${at}.resolvedBy must name the approver`);
265
+ if (typeof a.note !== "string" || a.note.trim() === "") problems.push(`${at}.note must say why the approval stands for these plans`);
266
+ if (a.url !== undefined && (typeof a.url !== "string" || !/^https?:\/\/\S+$/.test(a.url))) problems.push(`${at}.url must be an http or https URL`);
267
+ if (a.review !== undefined) {
268
+ const r = a.review as { pr?: unknown; head?: unknown; reviewers?: unknown } | null;
269
+ if (!r || typeof r !== "object") problems.push(`${at}.review must be { pr, head, reviewers }`);
270
+ else {
271
+ if (typeof r.pr !== "number" || !Number.isInteger(r.pr) || r.pr < 1) problems.push(`${at}.review.pr must be the pull request's number`);
272
+ if (typeof r.head !== "string" || r.head.trim() === "") problems.push(`${at}.review.head must be the commit the review approved`);
273
+ if (!principals(r.reviewers) || r.reviewers.length === 0) problems.push(`${at}.review.reviewers must list the reviewers`);
274
+ }
275
+ }
223
276
  return problems;
224
277
  }
225
278
 
@@ -240,6 +293,8 @@ export interface OpWaveAfterPlanWaveOutcome {
240
293
  overriders?: string[];
241
294
  overridersSource?: string;
242
295
  report?: string;
296
+ /** Each hook's `approvals`, in order (terragucci issue 1303). */
297
+ approvals: OpWaveAnswerApproval[];
243
298
  }
244
299
 
245
300
  /** What the after-plan hooks in the job's process came to (#4614). */
@@ -266,7 +321,7 @@ export async function runOpWaveAfterPlanHooks(
266
321
  runs: readonly OpWaveAfterPlanRun[],
267
322
  log: (line: string) => void,
268
323
  ): Promise<OpWaveAfterPlanOutcome> {
269
- const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map(), wave: { members: [], holds: [] } };
324
+ const out: OpWaveAfterPlanOutcome = { holds: [], outcomes: [], runs: new Map(), wave: { members: [], holds: [], approvals: [] } };
270
325
  const targets = runs.map((r) => r.target);
271
326
  for (const hook of hooks) {
272
327
  const mine = opWaveHookRuns(hook, runs);
@@ -349,6 +404,9 @@ function foldWaveAnswer(into: OpWaveAfterPlanWaveOutcome, answer: OpWaveAfterPla
349
404
  if (answer.overriders) into.overriders = [...new Set(answer.overriders)].sort();
350
405
  if (answer.overridersSource) into.overridersSource = answer.overridersSource;
351
406
  if (answer.report !== undefined) into.report = answer.report;
407
+ for (const a of answer.approvals ?? []) {
408
+ 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] } } : {}) });
409
+ }
352
410
  }
353
411
 
354
412
  /** 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,14 +72,13 @@
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";
@@ -115,8 +114,9 @@ export function opWaveDiscoverInput(spec: Pick<OpWavesSpec, "op" | "step">, wave
115
114
  }
116
115
 
117
116
  /** 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 };
117
+ export function opWaveStepContext(spec: Pick<OpWavesSpec, "labels">, wave: Pick<OpWave, "name">, run: OpWaveRun, cwd?: string): DeployContext {
118
+ // #4854: the wave's directory, where a capability looks for its project's config.
119
+ return { env: spec.labels?.Env ?? wave.name, component: run.target, ...(cwd !== undefined ? { cwd: resolve(cwd) } : {}) };
120
120
  }
121
121
 
122
122
  const registries = new WeakMap<object, Promise<CapabilityRegistry>>();
@@ -168,7 +168,7 @@ export interface OpWaveStepGroup {
168
168
  export const OP_WAVE_TOGETHER_MEMBER = "(wave plan)";
169
169
 
170
170
  /** The release that has `discover` with a `step`, and `together` waves (#4842). */
171
- export const OP_WAVE_STEP_WAVE_FLOOR = NEXT_RELEASE;
171
+ export const OP_WAVE_STEP_WAVE_FLOOR = "0.124.79";
172
172
 
173
173
  /** Whether a part changes nothing, and whether it destroys or replaces something. A plan that changes only outputs changes something (#4849). */
174
174
  export function partEffects(part: ChangeSetPart | undefined): { empty: boolean; destructive: boolean } {
@@ -195,7 +195,7 @@ export async function planOpWaveStep(
195
195
  let lock: PlannedLock;
196
196
  try {
197
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);
198
+ 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 } : {}) }, input as never);
199
199
  // #4552: the run's grain (declared at base, else its lexicon's) and, on the resource grain, the rows its apply leases.
200
200
  lock = await resolvePlannedLock(capability, input, planned, at.lockGrain);
201
201
  } catch (err) {
@@ -250,14 +250,14 @@ function writeStepPlanFile(file: string, plan: OpWaveStepPlan): void {
250
250
  * capability's `discoverRuns` finds for wave `k`, each a run of the spec's
251
251
  * op, and how many waves it found.
252
252
  */
253
- export async function discoverOpWaveStepRuns(at: { spec: OpWavesSpec; wave: OpWave; k: number; registry: CapabilityRegistry }): Promise<{ runs: OpWaveRun[]; waves?: number }> {
253
+ export async function discoverOpWaveStepRuns(at: { spec: OpWavesSpec; wave: OpWave; k: number; registry: CapabilityRegistry; cwd?: string }): Promise<{ runs: OpWaveRun[]; waves?: number }> {
254
254
  const { spec, wave, k } = at;
255
255
  const kind = spec.step!.kind;
256
256
  const capability = resolveCapability(at.registry, kind);
257
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
258
  let found: { targets?: unknown; waves?: unknown };
259
259
  try {
260
- found = await capability.discoverRuns({ env: spec.labels?.Env ?? wave.name, wave: { name: wave.name, number: k } }, opWaveDiscoverInput(spec, wave) as never);
260
+ 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
261
  } catch (err) {
262
262
  throw new Error(`finding the runs of wave ${k} (${wave.name}) through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
263
263
  }
@@ -280,8 +280,8 @@ function waveGroupMembers(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWave
280
280
  });
281
281
  }
282
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) };
283
+ function waveGroupContext(spec: OpWavesSpec, wave: OpWave, runs: readonly OpWaveRun[], cwd?: string): GroupContext {
284
+ return { env: spec.labels?.Env ?? wave.name, ...(cwd !== undefined ? { cwd: resolve(cwd) } : {}), components: runs.map((r) => r.target) };
285
285
  }
286
286
 
287
287
  function requireGroup(capability: Capability<never, unknown>, kind: string, wave: OpWave): void {
@@ -315,7 +315,7 @@ export async function planOpWaveStepGroup(
315
315
  const members = waveGroupMembers(spec, wave, runs, (run) => {
316
316
  const own = at.runCtx?.(run.target) ?? {};
317
317
  return {
318
- ...opWaveStepContext(spec, wave, run),
318
+ ...opWaveStepContext(spec, wave, run, at.cwd),
319
319
  ...(at.lockGrain ? { lockGrain: at.lockGrain } : {}),
320
320
  ...(at.policyBase ? { policyBase: at.policyBase } : {}),
321
321
  ...(own.processEnv ? { processEnv: own.processEnv } : {}),
@@ -324,7 +324,7 @@ export async function planOpWaveStepGroup(
324
324
  });
325
325
  let planned: { members?: Record<string, CapabilityPlan>; digest?: unknown; artifact?: unknown };
326
326
  try {
327
- planned = await capability.planGroup!(waveGroupContext(spec, wave, runs), members as never);
327
+ planned = await capability.planGroup!(waveGroupContext(spec, wave, runs, at.cwd), members as never);
328
328
  } catch (err) {
329
329
  throw new Error(`planning wave "${wave.name}" together through ${kind} failed: ${err instanceof Error ? err.message : String(err)}`);
330
330
  }
@@ -376,7 +376,7 @@ export async function planOpWaveStepGroup(
376
376
  * when it is a moved plan (`isPlanMovedError`).
377
377
  */
378
378
  export async function applyOpWaveStepGroup(
379
- at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; runEnv?: (target: string) => Record<string, string> | undefined },
379
+ at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; runEnv?: (target: string) => Record<string, string> | undefined; cwd?: string },
380
380
  runs: ReadonlyArray<{ run: OpWaveRun; plan: OpWaveStepPlan }>,
381
381
  ): Promise<OpWaveStepApply[]> {
382
382
  const { spec, wave } = at;
@@ -395,12 +395,12 @@ export async function applyOpWaveStepGroup(
395
395
  const members = waveGroupMembers(spec, wave, runs.map((r) => r.run), (run) => {
396
396
  const plan = byTarget.get(run.target)!;
397
397
  const env = at.runEnv?.(run.target);
398
- return { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
398
+ return { ...opWaveStepContext(spec, wave, run, at.cwd), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(env ? { processEnv: env } : {}) };
399
399
  });
400
400
  const plans = Object.fromEntries(runs.flatMap((r) => (group.plans[r.run.target] ? [[r.run.target, group.plans[r.run.target]!] as const] : [])));
401
401
  let got: { members?: Record<string, { status: string; outputs?: Record<string, unknown>; error?: string }>; error?: string };
402
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);
403
+ 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
404
  } catch (err) {
405
405
  const reason = err instanceof Error ? err.message : String(err);
406
406
  const moved = isPlanMovedError(err);
@@ -458,7 +458,7 @@ export async function opWaveStepFacts(
458
458
  }
459
459
 
460
460
  /** 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> {
461
+ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; registry: CapabilityRegistry; processEnv?: Record<string, string>; cwd?: string }, run: OpWaveRun, plan: OpWaveStepPlan): Promise<OpWaveStepApply> {
462
462
  const { spec, wave, registry } = at;
463
463
  let capability: Capability<never, unknown>;
464
464
  try {
@@ -466,7 +466,7 @@ export async function applyOpWaveStep(at: { spec: OpWavesSpec; wave: OpWave; reg
466
466
  } catch (err) {
467
467
  return { outcome: "failed", reason: err instanceof Error ? err.message : String(err) };
468
468
  }
469
- const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}) };
469
+ const ctx: DeployContext = { ...opWaveStepContext(spec, wave, run, at.cwd), ...(plan.artifact !== undefined ? { plans: { [plan.member]: plan.artifact } } : {}), ...(at.processEnv ? { processEnv: at.processEnv } : {}) };
470
470
  const input = opWaveStepInput(spec, wave, run);
471
471
  try {
472
472
  const output = await capability.run(ctx, input as never);