@intentius/chant 0.124.109 → 0.124.110

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 (338) hide show
  1. package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
  2. package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
  3. package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
  4. package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
  5. package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
  6. package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
  7. package/dist/agent-facts.d.ts +130 -0
  8. package/dist/agent-facts.js +196 -0
  9. package/dist/change-risk.d.ts +216 -0
  10. package/dist/change-risk.js +304 -0
  11. package/dist/change-set.d.ts +8 -0
  12. package/dist/ci-agent-alert.d.ts +139 -0
  13. package/dist/ci-agent-alert.js +342 -0
  14. package/dist/ci-agent-triggers.d.ts +152 -0
  15. package/dist/ci-agent-triggers.js +232 -0
  16. package/dist/ci-agent-verify-failed.d.ts +149 -0
  17. package/dist/ci-agent-verify-failed.js +191 -0
  18. package/dist/ci-agent.d.ts +136 -8
  19. package/dist/ci-agent.js +353 -26
  20. package/dist/ci-comment-commands.d.ts +8 -0
  21. package/dist/ci-comment-commands.js +17 -1
  22. package/dist/ci-comment-reject.d.ts +70 -0
  23. package/dist/ci-comment-reject.js +135 -0
  24. package/dist/ci-comment-replies.d.ts +3 -1
  25. package/dist/ci-comment-replies.js +6 -0
  26. package/dist/ci-estate/delivery.d.ts +25 -3
  27. package/dist/ci-estate/delivery.js +28 -9
  28. package/dist/ci-estate/page.d.ts +7 -3
  29. package/dist/ci-estate/page.js +19 -4
  30. package/dist/ci-estate/rows.d.ts +14 -2
  31. package/dist/ci-estate/rows.js +9 -1
  32. package/dist/ci-estate.d.ts +5 -2
  33. package/dist/ci-estate.js +3 -2
  34. package/dist/ci-handover.d.ts +2 -7
  35. package/dist/ci-handover.js +3 -20
  36. package/dist/ci-jobs.d.ts +6 -0
  37. package/dist/ci-jobs.js +17 -0
  38. package/dist/ci-note-commands.d.ts +2 -0
  39. package/dist/ci-note-commands.js +12 -1
  40. package/dist/ci-product-words.d.ts +151 -1
  41. package/dist/ci-product-words.js +1390 -3
  42. package/dist/ci-product.d.ts +100 -4
  43. package/dist/ci-product.js +99 -3
  44. package/dist/ci-respond-run.d.ts +9 -0
  45. package/dist/ci-respond-run.js +35 -4
  46. package/dist/ci-respond-summary-env.d.ts +56 -0
  47. package/dist/ci-respond-summary-env.js +81 -0
  48. package/dist/ci-respond-summary.d.ts +103 -0
  49. package/dist/ci-respond-summary.js +243 -0
  50. package/dist/ci-respond.d.ts +4 -2
  51. package/dist/ci-respond.js +4 -2
  52. package/dist/cli/command-group.js +1 -1
  53. package/dist/cli/commands/lint.js +21 -3
  54. package/dist/cli/handlers/agent.js +49 -4
  55. package/dist/cli/handlers/approve.js +3 -1
  56. package/dist/cli/handlers/build.d.ts +97 -1
  57. package/dist/cli/handlers/build.js +251 -3
  58. package/dist/cli/handlers/fan-out.js +55 -0
  59. package/dist/cli/handlers/graph.d.ts +14 -0
  60. package/dist/cli/handlers/graph.js +58 -3
  61. package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
  62. package/dist/cli/handlers/lifecycle-health.js +47 -9
  63. package/dist/cli/handlers/lifecycle.js +4 -1
  64. package/dist/cli/handlers/notify-relay.d.ts +2 -2
  65. package/dist/cli/handlers/notify-relay.js +67 -7
  66. package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
  67. package/dist/cli/handlers/pipeline-agent.js +255 -0
  68. package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
  69. package/dist/cli/handlers/pipeline-artifacts.js +203 -0
  70. package/dist/cli/handlers/pipeline.d.ts +16 -0
  71. package/dist/cli/handlers/pipeline.js +112 -0
  72. package/dist/cli/handlers/pr-comment.js +4 -0
  73. package/dist/cli/handlers/pr-notes.js +4 -1
  74. package/dist/cli/handlers/pr.d.ts +20 -0
  75. package/dist/cli/handlers/pr.js +114 -11
  76. package/dist/cli/handlers/promote.js +792 -47
  77. package/dist/cli/handlers/reject.d.ts +84 -0
  78. package/dist/cli/handlers/reject.js +216 -0
  79. package/dist/cli/handlers/replan.d.ts +54 -0
  80. package/dist/cli/handlers/replan.js +177 -0
  81. package/dist/cli/handlers/run-generate.d.ts +5 -0
  82. package/dist/cli/handlers/run-generate.js +31 -4
  83. package/dist/cli/handlers/run-wave.js +15 -2
  84. package/dist/cli/handlers/run.js +4 -2
  85. package/dist/cli/handlers/stage.d.ts +35 -0
  86. package/dist/cli/handlers/stage.js +90 -0
  87. package/dist/cli/lsp/server.js +4 -0
  88. package/dist/cli/main.js +88 -8
  89. package/dist/cli/parse-args.js +35 -2
  90. package/dist/cli/registry.d.ts +12 -0
  91. package/dist/components/auto-release.d.ts +2 -0
  92. package/dist/components/auto-release.js +1 -0
  93. package/dist/components/capability.d.ts +40 -0
  94. package/dist/components/cli-support.d.ts +21 -1
  95. package/dist/components/cli-support.js +28 -6
  96. package/dist/components/component.d.ts +23 -4
  97. package/dist/components/component.schema.json +28 -0
  98. package/dist/components/declared-reads.d.ts +44 -4
  99. package/dist/components/declared-reads.js +80 -3
  100. package/dist/components/discover.d.ts +8 -0
  101. package/dist/components/discover.js +1 -1
  102. package/dist/components/driver.d.ts +13 -0
  103. package/dist/components/driver.js +23 -2
  104. package/dist/components/environment-sets.d.ts +229 -0
  105. package/dist/components/environment-sets.js +338 -0
  106. package/dist/components/fan-out-canary.d.ts +47 -0
  107. package/dist/components/fan-out-canary.js +58 -0
  108. package/dist/components/fan-out-run.d.ts +17 -0
  109. package/dist/components/fan-out-run.js +14 -1
  110. package/dist/components/fan-out-support.d.ts +7 -0
  111. package/dist/components/fan-out-support.js +1 -1
  112. package/dist/components/groups.d.ts +8 -1
  113. package/dist/components/groups.js +19 -1
  114. package/dist/components/index.d.ts +5 -2
  115. package/dist/components/index.js +4 -1
  116. package/dist/components/pr-cost.d.ts +28 -0
  117. package/dist/components/pr-cost.js +53 -0
  118. package/dist/components/pr-pipeline.d.ts +33 -0
  119. package/dist/components/pr-pipeline.js +32 -5
  120. package/dist/components/pr-policy.d.ts +33 -2
  121. package/dist/components/pr-policy.js +5 -2
  122. package/dist/components/pr-risk.d.ts +42 -0
  123. package/dist/components/pr-risk.js +74 -0
  124. package/dist/components/product-pipeline.d.ts +43 -0
  125. package/dist/components/product-pipeline.js +67 -1
  126. package/dist/components/promote.d.ts +6 -0
  127. package/dist/components/promote.js +13 -0
  128. package/dist/components/release-compile.js +3 -1
  129. package/dist/components/release-gate.d.ts +6 -1
  130. package/dist/components/release-gate.js +10 -2
  131. package/dist/components/step-environments.d.ts +236 -0
  132. package/dist/components/step-environments.js +392 -0
  133. package/dist/components/upstream-replan.d.ts +201 -0
  134. package/dist/components/upstream-replan.js +249 -0
  135. package/dist/components/verify-step.d.ts +30 -0
  136. package/dist/components/verify-step.js +27 -0
  137. package/dist/components/wave-plan.js +6 -2
  138. package/dist/config-environments.d.ts +4 -2
  139. package/dist/control/dispatch.d.ts +15 -0
  140. package/dist/control/dispatch.js +28 -4
  141. package/dist/cost-estimate.d.ts +188 -0
  142. package/dist/cost-estimate.js +363 -0
  143. package/dist/drift-record.d.ts +36 -0
  144. package/dist/drift-record.js +44 -0
  145. package/dist/engine-facts.d.ts +105 -0
  146. package/dist/engine-facts.js +111 -0
  147. package/dist/exit-codes.d.ts +4 -3
  148. package/dist/exit-codes.js +4 -3
  149. package/dist/flag-params.d.ts +2 -2
  150. package/dist/flag-params.js +9 -4
  151. package/dist/floor-table.data.js +53 -0
  152. package/dist/forge-token-vars.d.ts +12 -0
  153. package/dist/forge-token-vars.js +25 -0
  154. package/dist/gate-decision.d.ts +3 -1
  155. package/dist/gate-decision.js +3 -1
  156. package/dist/gated-waves.d.ts +2 -0
  157. package/dist/gated-waves.js +1 -0
  158. package/dist/graph-ir.d.ts +30 -0
  159. package/dist/graph-ir.js +33 -1
  160. package/dist/graph-refs.d.ts +26 -0
  161. package/dist/graph-refs.js +34 -3
  162. package/dist/graph-schema/graph.schema.json +136 -0
  163. package/dist/health.d.ts +65 -0
  164. package/dist/health.js +62 -0
  165. package/dist/lexicon.d.ts +188 -1
  166. package/dist/lifecycle/disruption.d.ts +14 -1
  167. package/dist/lifecycle/disruption.js +5 -1
  168. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  169. package/dist/lifecycle/gate-change-set.js +2 -1
  170. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  171. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  172. package/dist/lifecycle/gate-rejection.js +93 -0
  173. package/dist/lifecycle/gate-seal.d.ts +3 -3
  174. package/dist/lifecycle/gate-seal.js +5 -5
  175. package/dist/lifecycle/observe.d.ts +17 -0
  176. package/dist/lifecycle/observe.js +10 -1
  177. package/dist/lifecycle/release-cut.js +4 -0
  178. package/dist/lifecycle/release-ledger.d.ts +8 -0
  179. package/dist/lifecycle/release-risk.d.ts +137 -0
  180. package/dist/lifecycle/release-risk.js +214 -0
  181. package/dist/lifecycle/release-store.d.ts +9 -0
  182. package/dist/lifecycle/release-store.js +4 -0
  183. package/dist/lifecycle/stage-log.d.ts +85 -0
  184. package/dist/lifecycle/stage-log.js +141 -0
  185. package/dist/lint/canary-checks.d.ts +31 -0
  186. package/dist/lint/canary-checks.js +45 -0
  187. package/dist/lint/rule.d.ts +1 -0
  188. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  190. package/dist/lint/rules/index.d.ts +1 -0
  191. package/dist/lint/rules/index.js +3 -0
  192. package/dist/notify-relay-repo.d.ts +54 -0
  193. package/dist/notify-relay-repo.js +84 -0
  194. package/dist/notify-relay.d.ts +53 -3
  195. package/dist/notify-relay.js +96 -3
  196. package/dist/notify.d.ts +57 -1
  197. package/dist/notify.js +7 -1
  198. package/dist/notify.schema.json +61 -3
  199. package/dist/observation.d.ts +34 -0
  200. package/dist/observation.js +14 -1
  201. package/dist/op/activities/review-agent.d.ts +39 -2
  202. package/dist/op/activities/review-agent.js +88 -5
  203. package/dist/op/agent-permit.d.ts +88 -0
  204. package/dist/op/agent-permit.js +97 -0
  205. package/dist/op/gate-approval-base.d.ts +8 -0
  206. package/dist/op/gate-approval-base.js +9 -0
  207. package/dist/op/gate-approval.d.ts +30 -1
  208. package/dist/op/gate-approval.js +23 -2
  209. package/dist/op/gate-quorum.d.ts +114 -8
  210. package/dist/op/gate-quorum.js +198 -21
  211. package/dist/op/gate-reject.d.ts +79 -0
  212. package/dist/op/gate-reject.js +96 -0
  213. package/dist/op/gate-summary.js +1 -1
  214. package/dist/op/gate.d.ts +28 -3
  215. package/dist/op/gate.js +55 -13
  216. package/dist/op/generate-pipeline.d.ts +15 -1
  217. package/dist/op/generate-pipeline.js +32 -5
  218. package/dist/op/index.d.ts +11 -6
  219. package/dist/op/index.js +10 -5
  220. package/dist/op/local-executor.d.ts +2 -0
  221. package/dist/op/local-executor.js +23 -4
  222. package/dist/op/op-waves-after-plan.d.ts +23 -0
  223. package/dist/op/op-waves-after-plan.js +12 -1
  224. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  225. package/dist/op/op-waves-capability-spec.js +46 -6
  226. package/dist/op/op-waves-capability.d.ts +21 -13
  227. package/dist/op/op-waves-capability.js +22 -59
  228. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  229. package/dist/op/op-waves-environment-sets.js +82 -0
  230. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  231. package/dist/op/op-waves-quorum-warnings.js +90 -0
  232. package/dist/op/op-waves-release-port.d.ts +7 -0
  233. package/dist/op/op-waves-release-port.js +15 -3
  234. package/dist/op/op-waves-release.d.ts +15 -0
  235. package/dist/op/op-waves-release.js +15 -0
  236. package/dist/op/op-waves-run.d.ts +37 -3
  237. package/dist/op/op-waves-run.js +141 -18
  238. package/dist/op/op-waves-soak.d.ts +57 -0
  239. package/dist/op/op-waves-soak.js +111 -0
  240. package/dist/op/op-waves-split.d.ts +4 -0
  241. package/dist/op/op-waves-split.js +4 -0
  242. package/dist/op/op-waves.d.ts +67 -4
  243. package/dist/op/op-waves.js +71 -3
  244. package/dist/pipeline/agent-ajv.d.ts +4 -0
  245. package/dist/pipeline/agent-ajv.js +14 -0
  246. package/dist/pipeline/agent-steps.d.ts +329 -0
  247. package/dist/pipeline/agent-steps.js +602 -0
  248. package/dist/pipeline/artifacts.d.ts +264 -0
  249. package/dist/pipeline/artifacts.js +425 -0
  250. package/dist/pipeline/diff.d.ts +45 -0
  251. package/dist/pipeline/diff.js +177 -0
  252. package/dist/pipeline/fold.d.ts +43 -0
  253. package/dist/pipeline/fold.js +140 -0
  254. package/dist/pipeline/generate.d.ts +52 -0
  255. package/dist/pipeline/generate.js +120 -0
  256. package/dist/pipeline/product.d.ts +225 -0
  257. package/dist/pipeline/product.js +257 -0
  258. package/dist/pipeline/promote.d.ts +404 -0
  259. package/dist/pipeline/promote.js +694 -0
  260. package/dist/pipeline/read.d.ts +37 -0
  261. package/dist/pipeline/read.js +58 -0
  262. package/dist/pipeline/rendered.d.ts +25 -0
  263. package/dist/pipeline/rendered.js +53 -0
  264. package/dist/pipeline/soak-checks.d.ts +80 -0
  265. package/dist/pipeline/soak-checks.js +254 -0
  266. package/dist/pipeline/soak-gate.d.ts +97 -0
  267. package/dist/pipeline/soak-gate.js +176 -0
  268. package/dist/pipeline/soak-sources.d.ts +17 -0
  269. package/dist/pipeline/soak-sources.js +42 -0
  270. package/dist/pipeline/soak.d.ts +260 -0
  271. package/dist/pipeline/soak.js +378 -0
  272. package/dist/pipeline/spec.d.ts +724 -0
  273. package/dist/pipeline/spec.js +567 -0
  274. package/dist/pipeline/stage-ledger.d.ts +187 -0
  275. package/dist/pipeline/stage-ledger.js +185 -0
  276. package/dist/pipeline/stage-waves.d.ts +114 -0
  277. package/dist/pipeline/stage-waves.js +161 -0
  278. package/dist/pipeline/stages.d.ts +64 -0
  279. package/dist/pipeline/stages.js +174 -0
  280. package/dist/pipeline/verify-rollback.d.ts +277 -0
  281. package/dist/pipeline/verify-rollback.js +393 -0
  282. package/dist/pipeline.d.ts +142 -0
  283. package/dist/pipeline.js +143 -0
  284. package/dist/pr-loop.d.ts +22 -0
  285. package/dist/pr-loop.js +8 -0
  286. package/dist/pr-plan-note.d.ts +15 -1
  287. package/dist/pr-plan-note.js +8 -0
  288. package/dist/pr-post.d.ts +31 -0
  289. package/dist/pr-post.js +89 -0
  290. package/dist/release-floors.d.ts +1 -1
  291. package/dist/release-floors.js +1 -1
  292. package/dist/report-store/audit.schema.json +50 -0
  293. package/dist/report-store/dora.schema.json +331 -0
  294. package/dist/report-store/estate.schema.json +96 -0
  295. package/dist/report-store/run.schema.json +14 -0
  296. package/dist/report-store.d.ts +151 -0
  297. package/dist/report-store.js +344 -0
  298. package/dist/run-event.d.ts +7 -2
  299. package/dist/wave-runtime.mjs +458 -404
  300. package/dist/workspace/catalog-edges.js +3 -3
  301. package/dist/workspace/change-set.schema.json +4 -0
  302. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  303. package/dist/workspace/ci-cloud-identity.js +30 -0
  304. package/dist/workspace/ci-run.js +17 -2
  305. package/dist/workspace/ci-secrets.d.ts +3 -1
  306. package/dist/workspace/ci-secrets.js +7 -1
  307. package/dist/workspace/compose-graph.d.ts +1 -1
  308. package/dist/workspace/compose-graph.js +3 -1
  309. package/dist/workspace/declaration.d.ts +27 -0
  310. package/dist/workspace/declaration.js +35 -0
  311. package/dist/workspace/declaration.schema.json +56 -0
  312. package/dist/workspace/graph-cli.js +26 -0
  313. package/dist/workspace/graph.schema.json +5 -1
  314. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  315. package/dist/workspace/identity-gate-rule.js +2 -2
  316. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  317. package/dist/workspace/identity-reject-rule.js +24 -0
  318. package/dist/workspace/identity.d.ts +3 -0
  319. package/dist/workspace/identity.js +2 -1
  320. package/dist/workspace/nested-graph.js +2 -0
  321. package/dist/workspace/pr-report.schema.json +65 -0
  322. package/dist/workspace/promotion-order.d.ts +19 -4
  323. package/dist/workspace/promotion-order.js +26 -4
  324. package/dist/workspace/release-train.d.ts +14 -0
  325. package/dist/workspace/release-train.js +32 -0
  326. package/dist/workspace/run-event.schema.json +2 -2
  327. package/dist/workspace/stack-read-edges.d.ts +19 -0
  328. package/dist/workspace/stack-read-edges.js +54 -0
  329. package/dist/workspace/status-gates.d.ts +51 -1
  330. package/dist/workspace/status-gates.js +60 -0
  331. package/dist/workspace/status-stages.d.ts +223 -0
  332. package/dist/workspace/status-stages.js +279 -0
  333. package/dist/workspace/status.d.ts +45 -1
  334. package/dist/workspace/status.js +109 -5
  335. package/dist/workspace/status.schema.json +283 -2
  336. package/dist/workspace/trust/seal.d.ts +7 -0
  337. package/dist/workspace/trust/seal.js +9 -0
  338. package/package.json +5 -1
@@ -0,0 +1,187 @@
1
+ /**
2
+ * A stage's own ledger (#5355): pauses, resumes, the releases that waited
3
+ * while the stage was paused, and each promote that passed on the urgent
4
+ * rule.
5
+ *
6
+ * The lines sit in `<stage>/stage.jsonl` on `chant/lifecycle`, beside the
7
+ * stage's `releases.jsonl`, in the member's part of the branch. Each names
8
+ * the pipeline, so two pipelines of one member keep their own state.
9
+ *
10
+ * - `pause`: `chant stage pause <stage>`, or a rollback of a stage that sets
11
+ * `pauseAfterRollback` (`cause: "rollback"`). A paused stage refuses
12
+ * promotion with exit 3. A promote already applying is not stopped; it
13
+ * finishes and records as usual.
14
+ * - `waiting`: a promote the pause refused, with the release it carried.
15
+ * - `resume`: `chant stage resume <stage>`. It names the newest release that
16
+ * waited (`admits`) and the older ones it replaces (`superseded`). A
17
+ * promote of a superseded release is refused from then on, so the newest
18
+ * waiting release is the one that enters.
19
+ * - `urgent`: a promote that passed the stage's gate on its urgent rule, with
20
+ * who approved it, who promoted it, and why.
21
+ * - `failed` (#5328): a verify after a promote, or a check of the stage's
22
+ * soak, failed, with each member's state. Written by a stage whose
23
+ * `onVerifyFail` is `rollback`; a separate reader (an agent trigger) can
24
+ * read it on its own, since nothing about it names the rollback.
25
+ * - `rollback-requested` (#5328): the rollback to the stage's previous
26
+ * release that a `failed` line asks for, and the members it restores. It
27
+ * waits at gate `<stage>-rollback` until a person approves it.
28
+ * - `rollback-held` (#5328): a `failed` line for which no rollback could be
29
+ * requested, and why: no earlier release, or one that is revoked.
30
+ * - `rolled-back` (#5328): the requested rollback ran, linked to its request
31
+ * and its failure, with who approved it.
32
+ *
33
+ * Every line records who wrote it (`by`) and, where one was given, why
34
+ * (`reason`).
35
+ */
36
+ import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
37
+ import type { DeployOutcome } from "../lifecycle/deploy-outcome.js";
38
+ /** The file a stage's lines are kept in, under the stage's directory on `chant/lifecycle`. */
39
+ export declare const STAGE_LEDGER_FILE = "stage.jsonl";
40
+ /** A release a line names: its digest and label. */
41
+ export interface StageRelease {
42
+ digest: string;
43
+ label: string | null;
44
+ }
45
+ /** The kinds of line a stage's ledger holds. */
46
+ export declare const STAGE_LINE_KINDS: readonly ["pause", "resume", "waiting", "urgent", "failed", "rollback-requested", "rollback-held", "rolled-back"];
47
+ export type StageLineKind = (typeof STAGE_LINE_KINDS)[number];
48
+ /**
49
+ * What a run left one member (a component) of a stage in (#5328):
50
+ *
51
+ * - `applied`: it deployed, and the release ledger records it;
52
+ * - `left-applied`: it failed after a step changed something that its
53
+ * capability does not undo (`rollback-opted-out`), so the change stays;
54
+ * - `rolled-back`: it failed, and each step that ran was undone;
55
+ * - `not-applied`: nothing of it ran, or it stopped at a gate.
56
+ */
57
+ export type StageMemberStateName = "applied" | "left-applied" | "rolled-back" | "not-applied";
58
+ /** One member's state on a `failed` line, and on a rollback request whether it is rolled back. */
59
+ export interface StageMemberState {
60
+ member: string;
61
+ state: StageMemberStateName;
62
+ /** On a request: whether the rollback restores it, and why not when it does not. */
63
+ rollback?: "requested" | string;
64
+ }
65
+ /** One line of a stage's ledger. */
66
+ export interface StagePauseLine {
67
+ version: 1;
68
+ kind: StageLineKind;
69
+ pipeline: string;
70
+ stage: string;
71
+ /** Who wrote it: the person who paused or resumed, or the promote's actor. */
72
+ by: string;
73
+ /** Why, as the person gave it. */
74
+ reason?: string;
75
+ timestamp: string;
76
+ /** On a pause a rollback wrote. */
77
+ cause?: "rollback";
78
+ /** On `waiting` and `urgent`, the release promoted; on a pause after a rollback, the release rolled back to. */
79
+ release?: StageRelease;
80
+ /** On `resume`: the newest release that waited while the stage was paused. */
81
+ admits?: StageRelease;
82
+ /** On `resume`: the digests of the older releases that waited, which no longer enter. */
83
+ superseded?: string[];
84
+ /** On `urgent`: the approval the urgent rule passed on. On `rolled-back` (#5328): the approval of the rollback gate, with no role. */
85
+ approval?: {
86
+ by: string;
87
+ at: string;
88
+ role?: string;
89
+ note?: string;
90
+ };
91
+ /** On `failed` and `rollback-requested` (#5328): the line's own id, which later lines link to. */
92
+ id?: string;
93
+ /** On `failed` (#5328): what failed, a verify after a promote or a check of the stage's soak. */
94
+ failure?: "verify" | "soak";
95
+ /** On `failed` (#5328): the release that failed in the stage, or the promotion's digest when it named none. */
96
+ failed?: StageRelease;
97
+ /** On `failed`: each member's state. On `rollback-requested`: each member, and whether the rollback restores it. On `rolled-back`: the members restored. */
98
+ members?: StageMemberState[];
99
+ /** On `failed` (#5328): what the failure said, one line each. */
100
+ detail?: string[];
101
+ /** On `rollback-requested`, `rollback-held` and `rolled-back` (#5328): the id of the `failed` line it answers. */
102
+ failureId?: string;
103
+ /** On `rolled-back` (#5328): the id of the request it carried out. */
104
+ requestId?: string;
105
+ /** On `rollback-requested` and `rolled-back` (#5328): the gate the rollback passes, under the pipeline's op. */
106
+ gate?: string;
107
+ /** On `rollback-held` (#5328): why no rollback was requested. */
108
+ held?: string;
109
+ }
110
+ /** Reads and appends a stage's lines. */
111
+ export interface StageLedgerPort {
112
+ /** The stage's lines for `pipeline`, oldest first. */
113
+ read(pipeline: string, stage: string): Promise<StagePauseLine[]>;
114
+ append(line: StagePauseLine): Promise<{
115
+ pushed: boolean;
116
+ pushWarning?: string;
117
+ }>;
118
+ }
119
+ /** Parse a stage ledger's text: the lines that read, and how many did not. */
120
+ export declare function parseStagePauseLines(text: string | null): {
121
+ lines: StagePauseLine[];
122
+ malformed: number;
123
+ };
124
+ /** A ledger held in memory, for tests and for a caller that read the lines already. */
125
+ export declare function memoryStageLedgerPort(seed?: StagePauseLine[]): StageLedgerPort & {
126
+ lines: StagePauseLine[];
127
+ };
128
+ /** The real port: `<stage>/stage.jsonl` on `chant/lifecycle`, appended with the ledger's retry and pushed. */
129
+ export declare function gitStageLedgerPort(opts?: {
130
+ cwd?: string;
131
+ }): StageLedgerPort;
132
+ /** The pause standing on the stage, or undefined when it is not paused: the newest pause or resume line decides. */
133
+ export declare function stagePaused(lines: readonly StagePauseLine[]): StagePauseLine | undefined;
134
+ /** The line a paused stage's refusal prints. */
135
+ export declare function stagePausedLine(pause: StagePauseLine): string;
136
+ /** The releases that waited since the standing pause, oldest first, each once at its newest wait. */
137
+ export declare function waitingReleases(lines: readonly StagePauseLine[]): StageRelease[];
138
+ /** The pause line for `chant stage pause`, or a refusal when the stage is paused already. */
139
+ export declare function pauseLine(input: {
140
+ pipeline: string;
141
+ stage: string;
142
+ by: string;
143
+ reason?: string;
144
+ lines: readonly StagePauseLine[];
145
+ now: Date;
146
+ cause?: "rollback";
147
+ release?: StageRelease;
148
+ }): StagePauseLine | {
149
+ refused: string;
150
+ };
151
+ /** The resume line for `chant stage resume`: the newest waiting release enters, the older ones are superseded. A refusal when the stage is not paused. */
152
+ export declare function resumeLine(input: {
153
+ pipeline: string;
154
+ stage: string;
155
+ by: string;
156
+ reason?: string;
157
+ lines: readonly StagePauseLine[];
158
+ now: Date;
159
+ }): StagePauseLine | {
160
+ refused: string;
161
+ };
162
+ /** The line a promote the pause refused records. */
163
+ export declare function waitingLine(input: {
164
+ pipeline: string;
165
+ stage: string;
166
+ by: string;
167
+ release: StageRelease;
168
+ now: Date;
169
+ }): StagePauseLine;
170
+ /**
171
+ * The resume that superseded `digest`, when the stage's newest resume names
172
+ * it among the releases that waited behind a newer one; undefined otherwise.
173
+ */
174
+ export declare function supersededBy(lines: readonly StagePauseLine[], digest: string): StagePauseLine | undefined;
175
+ /**
176
+ * The components of `components` that release `releaseDigest` (cut from
177
+ * `commit`) has not deployed in a stage, by its release ledger and deploy
178
+ * outcomes: each needs a record of the release (or of its commit), and no
179
+ * failed or gated run of it since. Empty when the release succeeded there.
180
+ */
181
+ export declare function releaseMissingIn(input: {
182
+ records: readonly ReleaseRecord[];
183
+ outcomes: readonly DeployOutcome[];
184
+ releaseDigest: string;
185
+ commit?: string;
186
+ components: readonly string[];
187
+ }): string[];
@@ -0,0 +1,185 @@
1
+ /**
2
+ * A stage's own ledger (#5355): pauses, resumes, the releases that waited
3
+ * while the stage was paused, and each promote that passed on the urgent
4
+ * rule.
5
+ *
6
+ * The lines sit in `<stage>/stage.jsonl` on `chant/lifecycle`, beside the
7
+ * stage's `releases.jsonl`, in the member's part of the branch. Each names
8
+ * the pipeline, so two pipelines of one member keep their own state.
9
+ *
10
+ * - `pause`: `chant stage pause <stage>`, or a rollback of a stage that sets
11
+ * `pauseAfterRollback` (`cause: "rollback"`). A paused stage refuses
12
+ * promotion with exit 3. A promote already applying is not stopped; it
13
+ * finishes and records as usual.
14
+ * - `waiting`: a promote the pause refused, with the release it carried.
15
+ * - `resume`: `chant stage resume <stage>`. It names the newest release that
16
+ * waited (`admits`) and the older ones it replaces (`superseded`). A
17
+ * promote of a superseded release is refused from then on, so the newest
18
+ * waiting release is the one that enters.
19
+ * - `urgent`: a promote that passed the stage's gate on its urgent rule, with
20
+ * who approved it, who promoted it, and why.
21
+ * - `failed` (#5328): a verify after a promote, or a check of the stage's
22
+ * soak, failed, with each member's state. Written by a stage whose
23
+ * `onVerifyFail` is `rollback`; a separate reader (an agent trigger) can
24
+ * read it on its own, since nothing about it names the rollback.
25
+ * - `rollback-requested` (#5328): the rollback to the stage's previous
26
+ * release that a `failed` line asks for, and the members it restores. It
27
+ * waits at gate `<stage>-rollback` until a person approves it.
28
+ * - `rollback-held` (#5328): a `failed` line for which no rollback could be
29
+ * requested, and why: no earlier release, or one that is revoked.
30
+ * - `rolled-back` (#5328): the requested rollback ran, linked to its request
31
+ * and its failure, with who approved it.
32
+ *
33
+ * Every line records who wrote it (`by`) and, where one was given, why
34
+ * (`reason`).
35
+ */
36
+ import { unsettledComponents } from "../lifecycle/mixed-environment.js";
37
+ /** The file a stage's lines are kept in, under the stage's directory on `chant/lifecycle`. */
38
+ export const STAGE_LEDGER_FILE = "stage.jsonl";
39
+ /** The kinds of line a stage's ledger holds. */
40
+ export const STAGE_LINE_KINDS = ["pause", "resume", "waiting", "urgent", "failed", "rollback-requested", "rollback-held", "rolled-back"];
41
+ /** Parse a stage ledger's text: the lines that read, and how many did not. */
42
+ export function parseStagePauseLines(text) {
43
+ const lines = [];
44
+ let malformed = 0;
45
+ for (const raw of (text ?? "").split("\n")) {
46
+ if (raw.trim() === "")
47
+ continue;
48
+ try {
49
+ const v = JSON.parse(raw);
50
+ if (v && v.version === 1 && typeof v.pipeline === "string" && typeof v.stage === "string" && typeof v.by === "string" && typeof v.timestamp === "string" && STAGE_LINE_KINDS.includes(v.kind))
51
+ lines.push(v);
52
+ else
53
+ malformed++;
54
+ }
55
+ catch {
56
+ malformed++;
57
+ }
58
+ }
59
+ return { lines, malformed };
60
+ }
61
+ /** A ledger held in memory, for tests and for a caller that read the lines already. */
62
+ export function memoryStageLedgerPort(seed = []) {
63
+ const lines = [...seed];
64
+ return {
65
+ lines,
66
+ async read(pipeline, stage) {
67
+ return lines.filter((l) => l.pipeline === pipeline && l.stage === stage);
68
+ },
69
+ async append(line) {
70
+ lines.push(line);
71
+ return { pushed: true };
72
+ },
73
+ };
74
+ }
75
+ /** The real port: `<stage>/stage.jsonl` on `chant/lifecycle`, appended with the ledger's retry and pushed. */
76
+ export function gitStageLedgerPort(opts) {
77
+ return {
78
+ async read(pipeline, stage) {
79
+ const { readBlobFromPath } = await import("../lifecycle/git.js");
80
+ return parseStagePauseLines(await readBlobFromPath(stage, STAGE_LEDGER_FILE, opts)).lines.filter((l) => l.pipeline === pipeline && l.stage === stage);
81
+ },
82
+ async append(line) {
83
+ const { appendLedgerLine, pushLifecycleRebasing, LifecyclePushLostError } = await import("../lifecycle/git.js");
84
+ const { sortedJsonReplacer } = await import("../utils.js");
85
+ await appendLedgerLine(line.stage, STAGE_LEDGER_FILE, JSON.stringify(line, sortedJsonReplacer), `Stage ${line.kind}: ${line.pipeline} ${line.stage}`, opts);
86
+ try {
87
+ return await pushLifecycleRebasing(opts);
88
+ }
89
+ catch (err) {
90
+ if (err instanceof LifecyclePushLostError)
91
+ return { pushed: false, pushWarning: err.message };
92
+ throw err;
93
+ }
94
+ },
95
+ };
96
+ }
97
+ /** The pause standing on the stage, or undefined when it is not paused: the newest pause or resume line decides. */
98
+ export function stagePaused(lines) {
99
+ const last = [...lines].reverse().find((l) => l.kind === "pause" || l.kind === "resume");
100
+ return last?.kind === "pause" ? last : undefined;
101
+ }
102
+ /** The line a paused stage's refusal prints. */
103
+ export function stagePausedLine(pause) {
104
+ const why = pause.cause === "rollback" ? `after a rollback${pause.release ? ` to ${pause.release.label ?? pause.release.digest}` : ""}` : "";
105
+ const parts = [why, pause.reason ? pause.reason : ""].filter(Boolean).join(": ");
106
+ return `stage "${pause.stage}" is paused since ${pause.timestamp} by ${pause.by}${parts ? ` (${parts})` : ""}, so nothing is promoted into it`;
107
+ }
108
+ /** The releases that waited since the standing pause, oldest first, each once at its newest wait. */
109
+ export function waitingReleases(lines) {
110
+ const pause = stagePaused(lines);
111
+ if (!pause)
112
+ return [];
113
+ const since = lines.lastIndexOf(pause);
114
+ const out = [];
115
+ for (const l of lines.slice(since + 1)) {
116
+ if (l.kind !== "waiting" || !l.release)
117
+ continue;
118
+ const at = out.findIndex((r) => r.digest === l.release.digest);
119
+ if (at >= 0)
120
+ out.splice(at, 1);
121
+ out.push(l.release);
122
+ }
123
+ return out;
124
+ }
125
+ /** The pause line for `chant stage pause`, or a refusal when the stage is paused already. */
126
+ export function pauseLine(input) {
127
+ const standing = stagePaused(input.lines);
128
+ if (standing)
129
+ return { refused: `${stagePausedLine(standing)}; it is paused already` };
130
+ return {
131
+ version: 1,
132
+ kind: "pause",
133
+ pipeline: input.pipeline,
134
+ stage: input.stage,
135
+ by: input.by,
136
+ ...(input.reason ? { reason: input.reason } : {}),
137
+ timestamp: input.now.toISOString(),
138
+ ...(input.cause ? { cause: input.cause } : {}),
139
+ ...(input.release ? { release: input.release } : {}),
140
+ };
141
+ }
142
+ /** The resume line for `chant stage resume`: the newest waiting release enters, the older ones are superseded. A refusal when the stage is not paused. */
143
+ export function resumeLine(input) {
144
+ if (!stagePaused(input.lines))
145
+ return { refused: `stage "${input.stage}" is not paused` };
146
+ const waited = waitingReleases(input.lines);
147
+ const admits = waited[waited.length - 1];
148
+ const superseded = waited.slice(0, -1).map((r) => r.digest);
149
+ return {
150
+ version: 1,
151
+ kind: "resume",
152
+ pipeline: input.pipeline,
153
+ stage: input.stage,
154
+ by: input.by,
155
+ ...(input.reason ? { reason: input.reason } : {}),
156
+ timestamp: input.now.toISOString(),
157
+ ...(admits ? { admits } : {}),
158
+ ...(superseded.length > 0 ? { superseded } : {}),
159
+ };
160
+ }
161
+ /** The line a promote the pause refused records. */
162
+ export function waitingLine(input) {
163
+ return { version: 1, kind: "waiting", pipeline: input.pipeline, stage: input.stage, by: input.by, timestamp: input.now.toISOString(), release: input.release };
164
+ }
165
+ /**
166
+ * The resume that superseded `digest`, when the stage's newest resume names
167
+ * it among the releases that waited behind a newer one; undefined otherwise.
168
+ */
169
+ export function supersededBy(lines, digest) {
170
+ const last = [...lines].reverse().find((l) => l.kind === "pause" || l.kind === "resume");
171
+ return last?.kind === "resume" && last.superseded?.includes(digest) ? last : undefined;
172
+ }
173
+ /**
174
+ * The components of `components` that release `releaseDigest` (cut from
175
+ * `commit`) has not deployed in a stage, by its release ledger and deploy
176
+ * outcomes: each needs a record of the release (or of its commit), and no
177
+ * failed or gated run of it since. Empty when the release succeeded there.
178
+ */
179
+ export function releaseMissingIn(input) {
180
+ const unsettled = unsettledComponents(input.records, input.outcomes);
181
+ return input.components.filter((component) => {
182
+ const ran = input.records.filter((r) => r.component === component && (r.releaseDigest === input.releaseDigest || (input.commit !== undefined && r.gitSha === input.commit)));
183
+ return ran.length === 0 || unsettled.has(component);
184
+ });
185
+ }
@@ -0,0 +1,114 @@
1
+ /**
2
+ * A stage's op waves, run by `chant components promote` (#5427).
3
+ *
4
+ * A member whose stages apply through a `step` and that declares no
5
+ * components (a yodel project's `sql-migrate`) has nothing for the
6
+ * component driver to deploy. Its promote runs the stage's op waves
7
+ * instead, once the stage's pause, rejections, soaks, agent steps and gate
8
+ * let the release in, as `chant run wave` runs them in a wave job:
9
+ *
10
+ * - The spec is the stage's, `stageWavesSpec` of the pipeline folded at the
11
+ * default branch, written over the stage's rendered spec file
12
+ * (`pipelineStageSpecFile`, the file a wave job of `chant pipeline
13
+ * generate` writes with `pipeline spec --stage`). A step input named
14
+ * `spec` names that file ({@link stageRunSpec}), so an engine that reads
15
+ * chant's decision by its spec file (`sql-migrate`) reads this stage's.
16
+ * - Each wave's gate, approval mode, holds and hooks are read at the
17
+ * default branch's commit from the same fold ({@link pipelineStageShow}),
18
+ * so the gate is the one the merged pipeline declares. A wave plans,
19
+ * decides its own gate on its plan digest and applies the plan it
20
+ * decided; one that waits stops the promote with exit 3, and the same
21
+ * promote carries on once it is approved.
22
+ * - The waves run in order in the one job, and the first that does not end
23
+ * with exit 0 ends the promote with its exit code.
24
+ * - The release records the step writes name the release promoted, with the
25
+ * step's plan digest, so later stages find the release applied here.
26
+ *
27
+ * The stand-down for a newer commit is off: a promote takes a release, not
28
+ * the branch's tip.
29
+ */
30
+ import type { OpWavesSpec } from "../op/op-waves.js";
31
+ import type { OpWaveShowAtBase, RunOpWaveOptions, RunOpWaveResult } from "../op/op-waves-run.js";
32
+ import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
33
+ import { type PipelineShow } from "./read.js";
34
+ import { type PipelineSpec } from "./spec.js";
35
+ /**
36
+ * The first chant whose `components promote` runs a stage's op waves for a
37
+ * member that declares no components (#5427): the stage's spec written to
38
+ * its rendered spec file with a step's `spec` input naming it, each wave's
39
+ * gate read from the pipeline at the default branch, release records under
40
+ * the release promoted, `pipelineStageShow` for an engine that reads a
41
+ * stage's gate at base, a stage's records under the pipeline's component
42
+ * when its targets name environments, and `idTokens` on a promote job
43
+ * (`PipelinePromoteStageInputs`). A product feature-detects the promote of
44
+ * its stages on this name.
45
+ */
46
+ export declare const PROMOTE_STAGE_WAVES_FLOOR = "0.124.110";
47
+ /** Whether stage `stage` of the pipeline applies through a `step`, so a member with no components promotes into it by its op waves. */
48
+ export declare function stageRunsWaves(spec: PipelineSpec, stage: string): boolean;
49
+ /**
50
+ * The op-waves spec a promote runs for `stage`: `stageWavesSpec`, with a
51
+ * step input `spec` set to the stage's rendered spec file, the file the
52
+ * promote writes it to. A step without that input is left as it is.
53
+ */
54
+ export declare function stageRunSpec(spec: PipelineSpec, stage: string): OpWavesSpec;
55
+ /**
56
+ * An `OpWaveShowAtBase` that reads a stage's rendered spec file
57
+ * (`.chant/op-waves/<pipeline>-<stage>.spec.json`) at a commit from the
58
+ * pipeline folded there: {@link stageRunSpec} of the stage whose file it
59
+ * is. A commit whose pipeline is absent, does not fold, or has no such stage
60
+ * reads as a spec absent at base, so every wave's gate is `always`. Every
61
+ * other file is read through `fallback`, which also resolves the commit.
62
+ *
63
+ * `readOpWavePolicy(specFile, wave, base, cwd, pipelineStageShow())` is how
64
+ * an engine that checks chant's decision again (`sql-migrate`) reads a
65
+ * stage's gate at base.
66
+ */
67
+ export declare function pipelineStageShow(fallback?: OpWaveShowAtBase, show?: PipelineShow): OpWaveShowAtBase;
68
+ /**
69
+ * What stage `stage` applied of a release (#5427), for a soak's clock: the
70
+ * newest record of each component on its ledger that names the release, or
71
+ * that was applied at the commit the release was cut from (the first
72
+ * stage's apply, recorded before the cut).
73
+ */
74
+ export declare function stageReleaseItems(records: readonly ReleaseRecord[], stage: string, release: {
75
+ releaseDigest: string;
76
+ commit: string;
77
+ }): Array<{
78
+ component: string;
79
+ digest: string;
80
+ source: ReleaseRecord;
81
+ }>;
82
+ /** One wave a promote ran (#5427). */
83
+ export interface StageWaveRan {
84
+ wave: number;
85
+ name: string;
86
+ result: RunOpWaveResult;
87
+ }
88
+ /** What {@link runStageWaves} did: the spec file it wrote, each wave it ran, and the exit code of the first that did not end with 0, else 0. */
89
+ export interface StageWavesRun {
90
+ specFile: string;
91
+ spec: OpWavesSpec;
92
+ waves: StageWaveRan[];
93
+ exitCode: number;
94
+ }
95
+ /**
96
+ * Run stage `stage`'s op waves for a release (#5427), in order, through
97
+ * `run` (`runOpWave`), as a wave job of the stage would. `spec` is the
98
+ * pipeline folded at `base`, the default branch's commit. Call it only once
99
+ * the stage's gate passed. `options` are the runner's seams (the gate
100
+ * ledger, the capabilities, the release port); `afterWave` is told how each
101
+ * wave ended, as `chant run wave` tells the spec's notify.
102
+ */
103
+ export declare function runStageWaves(input: {
104
+ spec: PipelineSpec;
105
+ stage: string;
106
+ base: string;
107
+ cwd: string;
108
+ release: {
109
+ releaseDigest: string;
110
+ };
111
+ options?: Omit<Partial<RunOpWaveOptions>, "spec" | "specFile" | "wave" | "base" | "cwd">;
112
+ run?: (options: RunOpWaveOptions) => Promise<RunOpWaveResult>;
113
+ afterWave?: (ran: StageWaveRan, spec: OpWavesSpec) => Promise<void>;
114
+ }): Promise<StageWavesRun>;
@@ -0,0 +1,161 @@
1
+ /**
2
+ * A stage's op waves, run by `chant components promote` (#5427).
3
+ *
4
+ * A member whose stages apply through a `step` and that declares no
5
+ * components (a yodel project's `sql-migrate`) has nothing for the
6
+ * component driver to deploy. Its promote runs the stage's op waves
7
+ * instead, once the stage's pause, rejections, soaks, agent steps and gate
8
+ * let the release in, as `chant run wave` runs them in a wave job:
9
+ *
10
+ * - The spec is the stage's, `stageWavesSpec` of the pipeline folded at the
11
+ * default branch, written over the stage's rendered spec file
12
+ * (`pipelineStageSpecFile`, the file a wave job of `chant pipeline
13
+ * generate` writes with `pipeline spec --stage`). A step input named
14
+ * `spec` names that file ({@link stageRunSpec}), so an engine that reads
15
+ * chant's decision by its spec file (`sql-migrate`) reads this stage's.
16
+ * - Each wave's gate, approval mode, holds and hooks are read at the
17
+ * default branch's commit from the same fold ({@link pipelineStageShow}),
18
+ * so the gate is the one the merged pipeline declares. A wave plans,
19
+ * decides its own gate on its plan digest and applies the plan it
20
+ * decided; one that waits stops the promote with exit 3, and the same
21
+ * promote carries on once it is approved.
22
+ * - The waves run in order in the one job, and the first that does not end
23
+ * with exit 0 ends the promote with its exit code.
24
+ * - The release records the step writes name the release promoted, with the
25
+ * step's plan digest, so later stages find the release applied here.
26
+ *
27
+ * The stand-down for a newer commit is off: a promote takes a release, not
28
+ * the branch's tip.
29
+ */
30
+ import { execFileSync } from "node:child_process";
31
+ import { mkdirSync, writeFileSync } from "node:fs";
32
+ import { dirname, isAbsolute, join, posix } from "node:path";
33
+ import { pipelineStageSpecFile } from "./generate.js";
34
+ import { gitShowPipeline, readPipelineAt } from "./read.js";
35
+ import { PIPELINE_FILE } from "./spec.js";
36
+ import { pipelineStage, stageWavesSpec } from "./stages.js";
37
+ /**
38
+ * The first chant whose `components promote` runs a stage's op waves for a
39
+ * member that declares no components (#5427): the stage's spec written to
40
+ * its rendered spec file with a step's `spec` input naming it, each wave's
41
+ * gate read from the pipeline at the default branch, release records under
42
+ * the release promoted, `pipelineStageShow` for an engine that reads a
43
+ * stage's gate at base, a stage's records under the pipeline's component
44
+ * when its targets name environments, and `idTokens` on a promote job
45
+ * (`PipelinePromoteStageInputs`). A product feature-detects the promote of
46
+ * its stages on this name.
47
+ */
48
+ export const PROMOTE_STAGE_WAVES_FLOOR = "0.124.110";
49
+ /** Whether stage `stage` of the pipeline applies through a `step`, so a member with no components promotes into it by its op waves. */
50
+ export function stageRunsWaves(spec, stage) {
51
+ return pipelineStage(spec, stage) !== undefined && spec.defaults?.step !== undefined;
52
+ }
53
+ /**
54
+ * The op-waves spec a promote runs for `stage`: `stageWavesSpec`, with a
55
+ * step input `spec` set to the stage's rendered spec file, the file the
56
+ * promote writes it to. A step without that input is left as it is.
57
+ */
58
+ export function stageRunSpec(spec, stage) {
59
+ const out = stageWavesSpec(spec, stage);
60
+ if (!out.step || typeof out.step.spec !== "string")
61
+ return out;
62
+ return { ...out, step: { ...out.step, spec: pipelineStageSpecFile(spec, stage) } };
63
+ }
64
+ const STAGE_SPEC_FILE = /^\.chant\/op-waves\/[^/]+\.spec\.json$/;
65
+ const posixPath = (p) => p.replace(/^\.\//, "").split("\\").join(posix.sep);
66
+ /** `git show <base>:<path>` in `cwd`, with the commit resolved; text null when the commit has no such file. */
67
+ const gitShowFile = (base, path, cwd) => {
68
+ let sha;
69
+ try {
70
+ sha = execFileSync("git", ["rev-parse", "--verify", `${base}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
71
+ }
72
+ catch {
73
+ throw new Error(`the gate policy is read at ${base}, which this checkout does not have. Check out the full history (fetch-depth: 0 on GitHub and Forgejo, GIT_DEPTH: "0" on GitLab).`);
74
+ }
75
+ try {
76
+ return { sha, text: execFileSync("git", ["show", `${sha}:./${path}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }) };
77
+ }
78
+ catch {
79
+ return { sha, text: null };
80
+ }
81
+ };
82
+ /**
83
+ * An `OpWaveShowAtBase` that reads a stage's rendered spec file
84
+ * (`.chant/op-waves/<pipeline>-<stage>.spec.json`) at a commit from the
85
+ * pipeline folded there: {@link stageRunSpec} of the stage whose file it
86
+ * is. A commit whose pipeline is absent, does not fold, or has no such stage
87
+ * reads as a spec absent at base, so every wave's gate is `always`. Every
88
+ * other file is read through `fallback`, which also resolves the commit.
89
+ *
90
+ * `readOpWavePolicy(specFile, wave, base, cwd, pipelineStageShow())` is how
91
+ * an engine that checks chant's decision again (`sql-migrate`) reads a
92
+ * stage's gate at base.
93
+ */
94
+ export function pipelineStageShow(fallback = gitShowFile, show = gitShowPipeline) {
95
+ return (base, path, cwd) => {
96
+ const file = posixPath(path);
97
+ if (!STAGE_SPEC_FILE.test(file))
98
+ return fallback(base, path, cwd);
99
+ const { sha } = fallback(base, PIPELINE_FILE, cwd);
100
+ const read = readPipelineAt(sha, cwd, show);
101
+ if (read.status !== "folded")
102
+ return { sha, text: null };
103
+ const stage = read.spec.stages.find((s) => pipelineStageSpecFile(read.spec, s.name) === file);
104
+ return { sha, text: stage ? `${JSON.stringify(stageRunSpec(read.spec, stage.name), null, 2)}\n` : null };
105
+ };
106
+ }
107
+ /**
108
+ * What stage `stage` applied of a release (#5427), for a soak's clock: the
109
+ * newest record of each component on its ledger that names the release, or
110
+ * that was applied at the commit the release was cut from (the first
111
+ * stage's apply, recorded before the cut).
112
+ */
113
+ export function stageReleaseItems(records, stage, release) {
114
+ const newest = new Map();
115
+ for (const r of records) {
116
+ if (r.env !== stage || (r.releaseDigest !== release.releaseDigest && r.gitSha !== release.commit))
117
+ continue;
118
+ const prior = newest.get(r.component);
119
+ if (!prior || Date.parse(r.timestamp) >= Date.parse(prior.timestamp))
120
+ newest.set(r.component, r);
121
+ }
122
+ return [...newest.values()].sort((a, b) => a.component.localeCompare(b.component)).map((source) => ({ component: source.component, digest: source.digest, source }));
123
+ }
124
+ /**
125
+ * Run stage `stage`'s op waves for a release (#5427), in order, through
126
+ * `run` (`runOpWave`), as a wave job of the stage would. `spec` is the
127
+ * pipeline folded at `base`, the default branch's commit. Call it only once
128
+ * the stage's gate passed. `options` are the runner's seams (the gate
129
+ * ledger, the capabilities, the release port); `afterWave` is told how each
130
+ * wave ended, as `chant run wave` tells the spec's notify.
131
+ */
132
+ export async function runStageWaves(input) {
133
+ const spec = stageRunSpec(input.spec, input.stage);
134
+ const specFile = pipelineStageSpecFile(input.spec, input.stage);
135
+ const path = isAbsolute(specFile) ? specFile : join(input.cwd, specFile);
136
+ mkdirSync(dirname(path), { recursive: true });
137
+ writeFileSync(path, `${JSON.stringify(spec, null, 2)}\n`);
138
+ const run = input.run ?? (await import("../op/op-waves-run.js")).runOpWave;
139
+ const own = input.options ?? {};
140
+ const releases = own.releases ?? (await import("../op/op-waves-release-port.js")).gitOpWaveReleasePort({ cwd: input.cwd, release: input.release });
141
+ const waves = [];
142
+ for (const [i, wave] of spec.waves.entries()) {
143
+ const result = await run({
144
+ ...own,
145
+ spec,
146
+ specFile,
147
+ wave: i + 1,
148
+ base: input.base,
149
+ cwd: input.cwd,
150
+ show: own.show ?? pipelineStageShow(),
151
+ standDown: false,
152
+ releases,
153
+ });
154
+ const ran = { wave: i + 1, name: wave.name, result };
155
+ waves.push(ran);
156
+ await input.afterWave?.(ran, spec);
157
+ if (result.exitCode !== 0)
158
+ return { specFile, spec, waves, exitCode: result.exitCode };
159
+ }
160
+ return { specFile, spec, waves, exitCode: 0 };
161
+ }