@intentius/chant 0.124.76 → 0.124.77

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 (146) hide show
  1. package/dist/__fixtures__/agent-guard/plywood.d.ts +8 -0
  2. package/dist/__fixtures__/agent-guard/plywood.d.ts.map +1 -0
  3. package/dist/__fixtures__/agent-guard/plywood.js +19 -0
  4. package/dist/__fixtures__/agent-guard/terragucci.d.ts +8 -0
  5. package/dist/__fixtures__/agent-guard/terragucci.d.ts.map +1 -0
  6. package/dist/__fixtures__/agent-guard/terragucci.js +30 -0
  7. package/dist/__fixtures__/gated-ledger.d.ts +10 -0
  8. package/dist/__fixtures__/gated-ledger.d.ts.map +1 -0
  9. package/dist/__fixtures__/gated-ledger.js +51 -0
  10. package/dist/agent-guard.d.ts +143 -0
  11. package/dist/agent-guard.d.ts.map +1 -0
  12. package/dist/agent-guard.js +456 -0
  13. package/dist/ci-commit.d.ts +54 -3
  14. package/dist/ci-commit.d.ts.map +1 -1
  15. package/dist/ci-commit.js +69 -7
  16. package/dist/ci-own-jobs.d.ts +81 -0
  17. package/dist/ci-own-jobs.d.ts.map +1 -0
  18. package/dist/ci-own-jobs.js +234 -0
  19. package/dist/ci-product.d.ts +39 -0
  20. package/dist/ci-product.d.ts.map +1 -1
  21. package/dist/ci-product.js +40 -0
  22. package/dist/cli/handlers/approve.d.ts +5 -1
  23. package/dist/cli/handlers/approve.d.ts.map +1 -1
  24. package/dist/cli/handlers/approve.js +17 -11
  25. package/dist/cli/handlers/build.d.ts +1 -1
  26. package/dist/cli/handlers/build.d.ts.map +1 -1
  27. package/dist/cli/handlers/build.js +88 -2
  28. package/dist/cli/handlers/commit.d.ts.map +1 -1
  29. package/dist/cli/handlers/commit.js +3 -1
  30. package/dist/cli/handlers/notify-relay.d.ts +18 -1
  31. package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
  32. package/dist/cli/handlers/notify-relay.js +90 -14
  33. package/dist/cli/handlers/pr.d.ts.map +1 -1
  34. package/dist/cli/handlers/pr.js +3 -1
  35. package/dist/cli/handlers/release.d.ts +5 -1
  36. package/dist/cli/handlers/release.d.ts.map +1 -1
  37. package/dist/cli/handlers/release.js +17 -5
  38. package/dist/cli/handlers/run-generate.d.ts.map +1 -1
  39. package/dist/cli/handlers/run-generate.js +2 -1
  40. package/dist/cli/main.d.ts.map +1 -1
  41. package/dist/cli/main.js +21 -1
  42. package/dist/cli/parse-args.d.ts.map +1 -1
  43. package/dist/cli/parse-args.js +60 -4
  44. package/dist/cli/registry.d.ts +16 -0
  45. package/dist/cli/registry.d.ts.map +1 -1
  46. package/dist/components/pr-env-components.d.ts +65 -0
  47. package/dist/components/pr-env-components.d.ts.map +1 -0
  48. package/dist/components/pr-env-components.js +163 -0
  49. package/dist/components/pr-policy.d.ts +15 -0
  50. package/dist/components/pr-policy.d.ts.map +1 -1
  51. package/dist/components/pr-policy.js +24 -1
  52. package/dist/components/release-compile.d.ts +15 -3
  53. package/dist/components/release-compile.d.ts.map +1 -1
  54. package/dist/components/release-compile.js +66 -15
  55. package/dist/gate-policy.d.ts +14 -1
  56. package/dist/gate-policy.d.ts.map +1 -1
  57. package/dist/gate-policy.js +16 -6
  58. package/dist/lexicon.d.ts +17 -1
  59. package/dist/lexicon.d.ts.map +1 -1
  60. package/dist/lexicon.js +1 -0
  61. package/dist/lifecycle/gated-op.d.ts +95 -0
  62. package/dist/lifecycle/gated-op.d.ts.map +1 -0
  63. package/dist/lifecycle/gated-op.js +96 -0
  64. package/dist/lifecycle/git.d.ts.map +1 -1
  65. package/dist/lifecycle/git.js +83 -2
  66. package/dist/notify-relay-repo.d.ts +131 -0
  67. package/dist/notify-relay-repo.d.ts.map +1 -0
  68. package/dist/notify-relay-repo.js +202 -0
  69. package/dist/notify-relay.d.ts +25 -1
  70. package/dist/notify-relay.d.ts.map +1 -1
  71. package/dist/notify-relay.js +28 -2
  72. package/dist/op/op-waves-capability.js +2 -2
  73. package/dist/policy-engine.d.ts +95 -0
  74. package/dist/policy-engine.d.ts.map +1 -0
  75. package/dist/policy-engine.js +158 -0
  76. package/dist/release-floors.d.ts +1 -1
  77. package/dist/release-floors.js +1 -1
  78. package/dist/state-export.d.ts +126 -0
  79. package/dist/state-export.d.ts.map +1 -0
  80. package/dist/state-export.js +157 -0
  81. package/dist/state-migration.d.ts +148 -0
  82. package/dist/state-migration.d.ts.map +1 -0
  83. package/dist/state-migration.js +147 -0
  84. package/dist/state-unlock.d.ts +167 -0
  85. package/dist/state-unlock.d.ts.map +1 -0
  86. package/dist/state-unlock.js +197 -0
  87. package/dist/wave-runtime.mjs +329 -329
  88. package/dist/workspace/declaration.schema.json +1 -1
  89. package/dist/workspace/release-workflow.d.ts +10 -0
  90. package/dist/workspace/release-workflow.d.ts.map +1 -1
  91. package/dist/workspace/release-workflow.js +8 -3
  92. package/package.json +1 -1
  93. package/src/__fixtures__/agent-guard/plywood.ts +27 -0
  94. package/src/__fixtures__/agent-guard/terragucci.ts +39 -0
  95. package/src/__fixtures__/gated-ledger.ts +58 -0
  96. package/src/agent-guard.test.ts +320 -0
  97. package/src/agent-guard.ts +548 -0
  98. package/src/ci-commit.test.ts +50 -2
  99. package/src/ci-commit.ts +93 -9
  100. package/src/ci-own-jobs.test.ts +109 -0
  101. package/src/ci-own-jobs.ts +253 -0
  102. package/src/ci-product.ts +81 -0
  103. package/src/cli/handlers/approve-cwd.test.ts +112 -0
  104. package/src/cli/handlers/approve.ts +22 -11
  105. package/src/cli/handlers/build-own-jobs.test.ts +80 -0
  106. package/src/cli/handlers/build-pr-loop-control.test.ts +88 -0
  107. package/src/cli/handlers/build-run-group.test.ts +60 -0
  108. package/src/cli/handlers/build.ts +83 -3
  109. package/src/cli/handlers/commit.ts +3 -0
  110. package/src/cli/handlers/notify-relay.ts +99 -17
  111. package/src/cli/handlers/pr.ts +3 -1
  112. package/src/cli/handlers/release.ts +15 -5
  113. package/src/cli/handlers/run-generate.ts +2 -1
  114. package/src/cli/main.ts +21 -1
  115. package/src/cli/parse-args.ts +45 -3
  116. package/src/cli/registry.ts +16 -0
  117. package/src/components/pr-env-components.test.ts +138 -0
  118. package/src/components/pr-env-components.ts +214 -0
  119. package/src/components/pr-policy.test.ts +41 -1
  120. package/src/components/pr-policy.ts +25 -1
  121. package/src/components/release-compile.test.ts +47 -0
  122. package/src/components/release-compile.ts +70 -13
  123. package/src/gate-policy-bundle.test.ts +14 -0
  124. package/src/gate-policy.test.ts +7 -0
  125. package/src/gate-policy.ts +22 -7
  126. package/src/lexicon.ts +18 -1
  127. package/src/lifecycle/gated-op.ts +158 -0
  128. package/src/lifecycle/git.test.ts +92 -0
  129. package/src/lifecycle/git.ts +71 -2
  130. package/src/notify-relay-repo.test.ts +284 -0
  131. package/src/notify-relay-repo.ts +234 -0
  132. package/src/notify-relay.test.ts +12 -0
  133. package/src/notify-relay.ts +30 -3
  134. package/src/op/op-waves-capability.ts +2 -2
  135. package/src/policy-engine.test.ts +163 -0
  136. package/src/policy-engine.ts +201 -0
  137. package/src/release-floors.ts +1 -1
  138. package/src/state-export.test.ts +125 -0
  139. package/src/state-export.ts +228 -0
  140. package/src/state-migration.test.ts +134 -0
  141. package/src/state-migration.ts +237 -0
  142. package/src/state-unlock.test.ts +166 -0
  143. package/src/state-unlock.ts +294 -0
  144. package/src/workspace/declaration.schema.json +1 -1
  145. package/src/workspace/release-workflow.test.ts +34 -0
  146. package/src/workspace/release-workflow.ts +17 -3
@@ -0,0 +1,197 @@
1
+ /**
2
+ * A stale state lock released behind a gated request (#4762): the lock a
3
+ * job killed mid-apply left behind, released once someone else approved
4
+ * that lock by its ID, and only while no run that may hold it is alive.
5
+ *
6
+ * Engine-neutral. The engine's adapter is a {@link StateLockSource}: where
7
+ * the lock is, the lock it holds now, and a release by ID. The terraform
8
+ * lexicon builds one from a root's backend and the binary's `force-unlock`
9
+ * (`@intentius/chant-lexicon-terraform/state-unlock`); a Pulumi stack's lock
10
+ * (`.pulumi/locks/...` and `pulumi cancel`) fits the same calls. The runs
11
+ * come from the forge ({@link forgeLiveRuns}), or the caller's own list.
12
+ *
13
+ * 1. The lock is read, with its ID, who took it and when.
14
+ * 2. A run of the repository that has not finished and began before the
15
+ * lock was taken (give or take {@link CLOCK_SKEW_MS}) may be the one
16
+ * holding it, so while one is alive nothing is asked and nothing is
17
+ * released. A forge that cannot be read refuses too: nothing then says
18
+ * the holder is gone.
19
+ * 3. The request (kind `unlock`, subject the root or stack, fields the
20
+ * lock's location and ID) waits for an approval by someone other than
21
+ * the requester. An approval binds that lock and no other.
22
+ * 4. Approved, the runs are read again just before the spend, the lock is
23
+ * released by its ID, read again to check it is gone, and the finished
24
+ * line records who released which lock under whose approval.
25
+ */
26
+ import { CHANT_EXIT } from "./exit-codes.js";
27
+ import { gatedOp } from "./lifecycle/gated-op.js";
28
+ import { NEXT_RELEASE } from "./release-floors.js";
29
+ /** The first chant with the engine-neutral lock release and {@link forgeLiveRuns} (#4762). */
30
+ export const STATE_UNLOCK_FLOOR = NEXT_RELEASE;
31
+ const text = (v) => (typeof v === "string" && v !== "" ? v : undefined);
32
+ /**
33
+ * The repository's runs that have not finished: GitHub's and Forgejo's
34
+ * Actions runs queued, waiting or in progress, GitLab's pipelines running,
35
+ * pending, preparing or waiting for a resource. Kept here rather than on the
36
+ * forge clients, so the bundles that carry those clients do not grow with
37
+ * a read only a lock release makes. Throws on a forge that answers an error.
38
+ */
39
+ export async function forgeLiveRuns(t) {
40
+ const fetchFn = t.fetch ?? globalThis.fetch;
41
+ const base = t.apiBase.replace(/\/+$/, "");
42
+ const headers = t.kind === "github"
43
+ ? { ...(t.token ? { Authorization: `Bearer ${t.token}` } : {}), Accept: "application/vnd.github+json" }
44
+ : t.kind === "forgejo"
45
+ ? { ...(t.token ? { Authorization: `token ${t.token}` } : {}), Accept: "application/json" }
46
+ : { ...(t.token ? { [t.tokenHeader ?? "PRIVATE-TOKEN"]: t.token } : {}), Accept: "application/json" };
47
+ const get = async (path) => {
48
+ const res = await fetchFn(`${base}${path}`, { method: "GET", headers });
49
+ const body = await res.text();
50
+ if (!res.ok)
51
+ throw new Error(`GET ${base}${path}: ${res.status} ${body.slice(0, 200)}`);
52
+ return body ? JSON.parse(body) : undefined;
53
+ };
54
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
55
+ const out = new Map();
56
+ if (t.kind === "gitlab") {
57
+ const project = encodeURIComponent(decodeURIComponent(t.repo));
58
+ for (const status of ["running", "pending", "preparing", "waiting_for_resource"]) {
59
+ const rows = await get(`/projects/${project}/pipelines?status=${status}&per_page=100`);
60
+ for (const p of Array.isArray(rows) ? rows : []) {
61
+ if (!isObject(p) || p.id === undefined)
62
+ continue;
63
+ const started = text(p.started_at) ?? text(p.created_at);
64
+ const url = text(p.web_url);
65
+ out.set(String(p.id), { id: String(p.id), status: text(p.status) ?? status, ...(started ? { started } : {}), ...(url ? { url } : {}) });
66
+ }
67
+ }
68
+ return [...out.values()];
69
+ }
70
+ const statuses = t.kind === "github" ? ["in_progress", "queued", "waiting", "pending", "requested"] : ["running", "waiting", "blocked"];
71
+ for (const status of statuses) {
72
+ const body = await get(`/repos/${t.repo}/actions/runs?status=${status}&${t.kind === "github" ? "per_page=100" : "limit=50"}`);
73
+ const runs = Array.isArray(body) ? body : isObject(body) && Array.isArray(body.workflow_runs) ? body.workflow_runs : [];
74
+ for (const r of runs) {
75
+ if (!isObject(r) || r.id === undefined)
76
+ continue;
77
+ const started = t.kind === "github" ? (text(r.run_started_at) ?? text(r.created_at)) : (text(r.started) ?? text(r.created));
78
+ // Forgejo leaves `started` at the epoch until a job starts.
79
+ const begun = started && Date.parse(started) > 0 ? started : (text(r.created) ?? text(r.created_at));
80
+ const url = text(r.html_url);
81
+ out.set(String(r.id), { id: String(r.id), status: text(r.status) ?? status, ...(begun ? { started: begun } : {}), ...(url ? { url } : {}) });
82
+ }
83
+ }
84
+ return [...out.values()];
85
+ }
86
+ /** How far a run's start may be after the lock's and still count as a run that could hold it: the clocks of the job and the forge differ. */
87
+ export const CLOCK_SKEW_MS = 2 * 60 * 1000;
88
+ /** A lock info's JSON, or undefined when it holds no lock ID. */
89
+ export function parseLockInfo(text) {
90
+ try {
91
+ const v = JSON.parse(text);
92
+ if (!v || typeof v !== "object" || typeof v.ID !== "string" || v.ID === "")
93
+ return undefined;
94
+ const out = { ID: v.ID };
95
+ for (const k of ["Operation", "Info", "Who", "Version", "Created", "Path"])
96
+ if (typeof v[k] === "string")
97
+ out[k] = v[k];
98
+ return out;
99
+ }
100
+ catch {
101
+ return undefined;
102
+ }
103
+ }
104
+ const time = (iso) => (iso ? Date.parse(iso) : Number.NaN);
105
+ /**
106
+ * The live runs that may hold a lock taken at `created`: those that began
107
+ * before it, give or take the clocks' skew. A lock with no time it was taken,
108
+ * or a run with no start, keeps every run in.
109
+ */
110
+ export function possibleHolders(runs, created, skewMs = CLOCK_SKEW_MS) {
111
+ const taken = time(created);
112
+ return runs.filter((r) => Number.isNaN(taken) || Number.isNaN(time(r.started)) || time(r.started) <= taken + skewMs);
113
+ }
114
+ /** A lock as one line: its ID, operation, holder and time. */
115
+ export const describeLock = (l) => `lock ${l.ID}${l.Operation ? `, ${l.Operation}` : ""}${l.Who ? ` by ${l.Who}` : ""}${l.Created ? ` at ${l.Created}` : ""}`;
116
+ /** A run as one line. */
117
+ export const describeRun = (r) => `run ${r.id} (${r.status}${r.started ? `, began ${r.started}` : ""})${r.url ? ` ${r.url}` : ""}`;
118
+ /** A refusal before anything is asked: the runs could not be read. */
119
+ export class StateUnlockError extends Error {
120
+ constructor(message) {
121
+ super(message);
122
+ this.name = "StateUnlockError";
123
+ }
124
+ }
125
+ /** Release a state's lock that no live run can hold, once an approval of that lock stands. */
126
+ export async function releaseStateLock(input) {
127
+ const location = input.lock.location;
128
+ const lock = await input.lock.read();
129
+ if (!lock)
130
+ return { status: "free", exit: CHANT_EXIT.done, location };
131
+ let live = 0;
132
+ const holders = async () => {
133
+ let runs;
134
+ try {
135
+ runs = await input.liveRuns();
136
+ }
137
+ catch (e) {
138
+ throw new StateUnlockError(`the repository's runs could not be read (${e.message}), so nothing says the run holding ${describeLock(lock)} is gone`);
139
+ }
140
+ live = runs.length;
141
+ return possibleHolders(runs, lock.Created, input.skewMs);
142
+ };
143
+ const alive = await holders();
144
+ if (alive.length > 0)
145
+ return { status: "alive", exit: CHANT_EXIT.held, location, lock, alive };
146
+ const result = await gatedOp({
147
+ op: input.words.op,
148
+ request: { kind: input.words.kind ?? "unlock", subject: input.subject, by: input.by, fields: { location, id: lock.ID } },
149
+ rules: input.rules,
150
+ description: `release ${describeLock(lock)} on ${location}`,
151
+ expiry: input.expiry ?? "48h",
152
+ ...(input.base ? { base: input.base } : {}),
153
+ ...(input.cwd ? { cwd: input.cwd } : {}),
154
+ ...(input.now ? { now: input.now } : {}),
155
+ ...(input.commit ? { commit: input.commit } : {}),
156
+ ...(input.ledger ? { ledger: input.ledger } : {}),
157
+ // The approval may be hours old: the runs are read again just before the spend.
158
+ beforeSpend: async () => {
159
+ const still = await holders();
160
+ return still.length > 0 ? `a run that began before the lock is alive again (${still.map(describeRun).join("; ")}), so the lock is not released` : undefined;
161
+ },
162
+ }, async ({ approvedBy }) => {
163
+ await input.lock.release(lock.ID);
164
+ const after = await input.lock.read();
165
+ if (after?.ID === lock.ID)
166
+ throw new StateUnlockError(`the release of lock ${lock.ID} ran, and ${location} still holds it`);
167
+ return {
168
+ output: approvedBy,
169
+ detail: {
170
+ by: input.by,
171
+ location,
172
+ lock_id: lock.ID,
173
+ ...(lock.Operation ? { operation: lock.Operation } : {}),
174
+ ...(lock.Who ? { locked_by: lock.Who } : {}),
175
+ ...(lock.Created ? { locked_at: lock.Created } : {}),
176
+ approved_by: approvedBy,
177
+ live_runs: live,
178
+ },
179
+ };
180
+ });
181
+ const command = (fallback) => (input.words.approveCommand ? input.words.approveCommand(input.subject, result.digest) : fallback);
182
+ const at = { location, lock, digest: result.digest };
183
+ switch (result.status) {
184
+ case "done":
185
+ return { status: "released", exit: CHANT_EXIT.done, ...at, approvedBy: result.approvedBy, liveRuns: live, recorded: result.recorded };
186
+ case "waiting":
187
+ return { status: "waiting", exit: CHANT_EXIT.waiting, ...at, command: command(result.command) };
188
+ case "refused":
189
+ return { status: "refused", exit: CHANT_EXIT.waiting, ...at, command: command(result.command), by: result.by, reason: result.reason };
190
+ case "held":
191
+ return { status: "held", exit: CHANT_EXIT.held, ...at, reason: result.reason };
192
+ case "spent":
193
+ return { status: "spent", exit: CHANT_EXIT.failed, ...at };
194
+ case "failed":
195
+ return { status: "failed", exit: CHANT_EXIT.failed, ...at, error: result.error, recorded: result.recorded };
196
+ }
197
+ }