@intentius/chant 0.124.44 → 0.124.46

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 (249) hide show
  1. package/dist/capabilities/aws.paths +148 -0
  2. package/dist/capabilities/base-mappings.json +122 -0
  3. package/dist/capabilities/catalog.d.ts +89 -0
  4. package/dist/capabilities/catalog.d.ts.map +1 -0
  5. package/dist/capabilities/catalog.js +204 -0
  6. package/dist/capabilities/language.d.ts +103 -0
  7. package/dist/capabilities/language.d.ts.map +1 -0
  8. package/dist/capabilities/language.js +335 -0
  9. package/dist/capabilities/matcher.d.ts +65 -0
  10. package/dist/capabilities/matcher.d.ts.map +1 -0
  11. package/dist/capabilities/matcher.js +299 -0
  12. package/dist/capabilities/view.d.ts +207 -0
  13. package/dist/capabilities/view.d.ts.map +1 -0
  14. package/dist/capabilities/view.js +484 -0
  15. package/dist/ci-identity.d.ts +183 -12
  16. package/dist/ci-identity.d.ts.map +1 -1
  17. package/dist/ci-identity.js +362 -53
  18. package/dist/cli/commands/lint.d.ts.map +1 -1
  19. package/dist/cli/commands/lint.js +1 -0
  20. package/dist/cli/handlers/build.d.ts.map +1 -1
  21. package/dist/cli/handlers/build.js +17 -1
  22. package/dist/cli/handlers/declared-graph.d.ts +44 -0
  23. package/dist/cli/handlers/declared-graph.d.ts.map +1 -0
  24. package/dist/cli/handlers/declared-graph.js +87 -0
  25. package/dist/cli/handlers/graph.d.ts +25 -0
  26. package/dist/cli/handlers/graph.d.ts.map +1 -1
  27. package/dist/cli/handlers/graph.js +93 -87
  28. package/dist/cli/handlers/pr-env.d.ts +8 -2
  29. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  30. package/dist/cli/handlers/pr-env.js +127 -225
  31. package/dist/cli/handlers/pr.d.ts +3 -0
  32. package/dist/cli/handlers/pr.d.ts.map +1 -1
  33. package/dist/cli/handlers/pr.js +1 -0
  34. package/dist/cli/handlers/search-count.d.ts +89 -0
  35. package/dist/cli/handlers/search-count.d.ts.map +1 -0
  36. package/dist/cli/handlers/search-count.js +132 -0
  37. package/dist/cli/handlers/search.d.ts +358 -6
  38. package/dist/cli/handlers/search.d.ts.map +1 -1
  39. package/dist/cli/handlers/search.js +1065 -155
  40. package/dist/cli/main.d.ts.map +1 -1
  41. package/dist/cli/main.js +23 -3
  42. package/dist/cli/mcp/server.d.ts.map +1 -1
  43. package/dist/cli/mcp/server.js +3 -0
  44. package/dist/cli/mcp/tools/capabilities.d.ts +7 -0
  45. package/dist/cli/mcp/tools/capabilities.d.ts.map +1 -0
  46. package/dist/cli/mcp/tools/capabilities.js +27 -0
  47. package/dist/cli/mcp/workspace-tools.d.ts +3 -1
  48. package/dist/cli/mcp/workspace-tools.d.ts.map +1 -1
  49. package/dist/cli/mcp/workspace-tools.js +47 -2
  50. package/dist/cli/parse-args.d.ts.map +1 -1
  51. package/dist/cli/parse-args.js +64 -17
  52. package/dist/cli/registry.d.ts +22 -0
  53. package/dist/cli/registry.d.ts.map +1 -1
  54. package/dist/components/cli-support.d.ts +2 -0
  55. package/dist/components/cli-support.d.ts.map +1 -1
  56. package/dist/components/cli-support.js +4 -2
  57. package/dist/components/fan-out-support.d.ts +3 -0
  58. package/dist/components/fan-out-support.d.ts.map +1 -1
  59. package/dist/components/fan-out-support.js +1 -1
  60. package/dist/components/pr-env-ports.d.ts +29 -0
  61. package/dist/components/pr-env-ports.d.ts.map +1 -0
  62. package/dist/components/pr-env-ports.js +77 -0
  63. package/dist/components/pr-env-run.d.ts +254 -0
  64. package/dist/components/pr-env-run.d.ts.map +1 -0
  65. package/dist/components/pr-env-run.js +376 -0
  66. package/dist/components/pr-environment.d.ts +91 -15
  67. package/dist/components/pr-environment.d.ts.map +1 -1
  68. package/dist/components/pr-environment.js +95 -9
  69. package/dist/components/pr-pipeline.d.ts +10 -1
  70. package/dist/components/pr-pipeline.d.ts.map +1 -1
  71. package/dist/config-environments.d.ts +92 -0
  72. package/dist/config-environments.d.ts.map +1 -0
  73. package/dist/config-environments.js +102 -0
  74. package/dist/config.d.ts +24 -84
  75. package/dist/config.d.ts.map +1 -1
  76. package/dist/config.js +9 -96
  77. package/dist/graph-detail.d.ts.map +1 -1
  78. package/dist/graph-detail.js +15 -3
  79. package/dist/graph-effective.d.ts +33 -2
  80. package/dist/graph-effective.d.ts.map +1 -1
  81. package/dist/graph-effective.js +215 -68
  82. package/dist/graph-ir.d.ts +23 -0
  83. package/dist/graph-ir.d.ts.map +1 -1
  84. package/dist/graph-ir.js +130 -0
  85. package/dist/graph-sub-template.d.ts +11 -0
  86. package/dist/graph-sub-template.d.ts.map +1 -0
  87. package/dist/graph-sub-template.js +19 -0
  88. package/dist/lexicon.d.ts +9 -0
  89. package/dist/lexicon.d.ts.map +1 -1
  90. package/dist/lifecycle/observe.d.ts +28 -0
  91. package/dist/lifecycle/observe.d.ts.map +1 -1
  92. package/dist/lifecycle/observe.js +23 -1
  93. package/dist/lint/rule.d.ts +6 -0
  94. package/dist/lint/rule.d.ts.map +1 -1
  95. package/dist/live-endpoint.d.ts +1 -1
  96. package/dist/live-endpoint.d.ts.map +1 -1
  97. package/dist/live-endpoint.js +1 -1
  98. package/dist/observation.d.ts +48 -1
  99. package/dist/observation.d.ts.map +1 -1
  100. package/dist/observation.js +21 -5
  101. package/dist/op/activities/activity-contracts.d.ts +4 -4
  102. package/dist/op/op-waves.d.ts +17 -0
  103. package/dist/op/op-waves.d.ts.map +1 -1
  104. package/dist/op/op-waves.js +23 -1
  105. package/dist/pr-forge.d.ts +15 -1
  106. package/dist/pr-forge.d.ts.map +1 -1
  107. package/dist/pr-forge.js +28 -16
  108. package/dist/pr-requires.d.ts +5 -1
  109. package/dist/pr-requires.d.ts.map +1 -1
  110. package/dist/wave-runtime.mjs +251 -250
  111. package/dist/workspace/capabilities-contract.d.ts +66 -0
  112. package/dist/workspace/capabilities-contract.d.ts.map +1 -0
  113. package/dist/workspace/capabilities-contract.js +107 -0
  114. package/dist/workspace/capabilities.schema.json +229 -0
  115. package/dist/workspace/ci-cloud-identity.d.ts +3 -1
  116. package/dist/workspace/ci-cloud-identity.d.ts.map +1 -1
  117. package/dist/workspace/ci-cloud-identity.js +16 -1
  118. package/dist/workspace/ci-run.d.ts +35 -8
  119. package/dist/workspace/ci-run.d.ts.map +1 -1
  120. package/dist/workspace/ci-run.js +95 -21
  121. package/dist/workspace/ci-secrets.d.ts.map +1 -1
  122. package/dist/workspace/ci-secrets.js +4 -3
  123. package/dist/workspace/compose-graph.d.ts +9 -0
  124. package/dist/workspace/compose-graph.d.ts.map +1 -1
  125. package/dist/workspace/compose-graph.js +3 -1
  126. package/dist/workspace/conformance/index.d.ts +1 -1
  127. package/dist/workspace/conformance/index.d.ts.map +1 -1
  128. package/dist/workspace/conformance/index.js +39 -2
  129. package/dist/workspace/declaration.d.ts +10 -0
  130. package/dist/workspace/declaration.d.ts.map +1 -1
  131. package/dist/workspace/declaration.js +17 -1
  132. package/dist/workspace/declaration.schema.json +36 -1
  133. package/dist/workspace/graph-cache.d.ts +8 -0
  134. package/dist/workspace/graph-cache.d.ts.map +1 -1
  135. package/dist/workspace/graph-cache.js +27 -3
  136. package/dist/workspace/graph-cli.d.ts +39 -2
  137. package/dist/workspace/graph-cli.d.ts.map +1 -1
  138. package/dist/workspace/graph-cli.js +66 -24
  139. package/dist/workspace/graph.schema.json +148 -0
  140. package/dist/workspace/kind-readers.d.ts +3 -0
  141. package/dist/workspace/kind-readers.d.ts.map +1 -1
  142. package/dist/workspace/kind-readers.js +7 -1
  143. package/dist/workspace/member-commands.d.ts +10 -1
  144. package/dist/workspace/member-commands.d.ts.map +1 -1
  145. package/dist/workspace/member-commands.js +17 -1
  146. package/dist/workspace/nested-graph.d.ts +2 -0
  147. package/dist/workspace/nested-graph.d.ts.map +1 -1
  148. package/dist/workspace/nested-graph.js +32 -1
  149. package/dist/workspace/reason-codes.d.ts +10 -0
  150. package/dist/workspace/reason-codes.d.ts.map +1 -1
  151. package/dist/workspace/reason-codes.js +12 -0
  152. package/dist/workspace/search-cli.d.ts +204 -0
  153. package/dist/workspace/search-cli.d.ts.map +1 -0
  154. package/dist/workspace/search-cli.js +466 -0
  155. package/dist/workspace/search-contract.d.ts +56 -0
  156. package/dist/workspace/search-contract.d.ts.map +1 -0
  157. package/dist/workspace/search-contract.js +70 -0
  158. package/dist/workspace/search.schema.json +822 -0
  159. package/package.json +1 -1
  160. package/src/__snapshots__/okf.test.ts.snap +10 -0
  161. package/src/capabilities/aws.paths +148 -0
  162. package/src/capabilities/base-mappings.json +122 -0
  163. package/src/capabilities/catalog.ts +230 -0
  164. package/src/capabilities/language.test.ts +191 -0
  165. package/src/capabilities/language.ts +373 -0
  166. package/src/capabilities/matcher.ts +315 -0
  167. package/src/capabilities/view-compose.test.ts +76 -0
  168. package/src/capabilities/view.ts +631 -0
  169. package/src/ci-identity-targets.test.ts +275 -0
  170. package/src/ci-identity.ts +394 -61
  171. package/src/cli/commands/lint.ts +1 -0
  172. package/src/cli/handlers/build.ts +15 -1
  173. package/src/cli/handlers/declared-graph.ts +99 -0
  174. package/src/cli/handlers/graph.test.ts +94 -3
  175. package/src/cli/handlers/graph.ts +123 -96
  176. package/src/cli/handlers/pr-env.ts +135 -227
  177. package/src/cli/handlers/pr.ts +4 -0
  178. package/src/cli/handlers/search-build-roots.test.ts +144 -0
  179. package/src/cli/handlers/search-count.test.ts +191 -0
  180. package/src/cli/handlers/search-count.ts +165 -0
  181. package/src/cli/handlers/search-json.test.ts +333 -0
  182. package/src/cli/handlers/search-live.test.ts +387 -0
  183. package/src/cli/handlers/search-paths.test.ts +235 -0
  184. package/src/cli/handlers/search.ts +1312 -166
  185. package/src/cli/main.test.ts +28 -3
  186. package/src/cli/main.ts +23 -3
  187. package/src/cli/mcp/server.test.ts +3 -3
  188. package/src/cli/mcp/server.ts +3 -0
  189. package/src/cli/mcp/tools/capabilities.ts +32 -0
  190. package/src/cli/mcp/workspace-tools.e2e.test.ts +21 -1
  191. package/src/cli/mcp/workspace-tools.ts +47 -2
  192. package/src/cli/parse-args.ts +52 -13
  193. package/src/cli/registry.ts +22 -0
  194. package/src/components/cli-support.ts +6 -1
  195. package/src/components/fan-out-support.ts +4 -1
  196. package/src/components/pr-env-ports.ts +89 -0
  197. package/src/components/pr-env-run-bundle.test.ts +54 -0
  198. package/src/components/pr-env-run.test.ts +290 -0
  199. package/src/components/pr-env-run.ts +563 -0
  200. package/src/components/pr-environment.ts +161 -13
  201. package/src/components/pr-pipeline.ts +10 -1
  202. package/src/config-environments.ts +133 -0
  203. package/src/config.ts +37 -124
  204. package/src/graph-detail.ts +15 -3
  205. package/src/graph-effective.ts +226 -75
  206. package/src/graph-ir.test.ts +163 -0
  207. package/src/graph-ir.ts +147 -0
  208. package/src/graph-sub-template.ts +22 -0
  209. package/src/lexicon.ts +10 -0
  210. package/src/lifecycle/observe.test.ts +27 -1
  211. package/src/lifecycle/observe.ts +43 -1
  212. package/src/lint/rule.ts +6 -0
  213. package/src/live-endpoint.ts +1 -1
  214. package/src/observation.test.ts +25 -0
  215. package/src/observation.ts +69 -5
  216. package/src/op/op-waves.ts +38 -1
  217. package/src/pr-forge-bundle.test.ts +1 -1
  218. package/src/pr-forge.ts +44 -17
  219. package/src/pr-requires.test.ts +43 -6
  220. package/src/pr-requires.ts +5 -1
  221. package/src/workspace/capabilities-contract.test.ts +88 -0
  222. package/src/workspace/capabilities-contract.ts +132 -0
  223. package/src/workspace/capabilities.schema.json +229 -0
  224. package/src/workspace/ci-cloud-identity.test.ts +20 -0
  225. package/src/workspace/ci-cloud-identity.ts +14 -1
  226. package/src/workspace/ci-run.test.ts +74 -1
  227. package/src/workspace/ci-run.ts +122 -29
  228. package/src/workspace/ci-secrets.test.ts +1 -1
  229. package/src/workspace/ci-secrets.ts +4 -3
  230. package/src/workspace/compose-graph.ts +10 -1
  231. package/src/workspace/conformance/conformance.e2e.test.ts +14 -1
  232. package/src/workspace/conformance/index.ts +31 -2
  233. package/src/workspace/declaration.schema.json +36 -1
  234. package/src/workspace/declaration.test.ts +7 -0
  235. package/src/workspace/declaration.ts +24 -2
  236. package/src/workspace/graph-cache.ts +27 -3
  237. package/src/workspace/graph-cli.ts +96 -24
  238. package/src/workspace/graph.schema.json +148 -0
  239. package/src/workspace/kind-readers.e2e.test.ts +28 -0
  240. package/src/workspace/kind-readers.test.ts +1 -1
  241. package/src/workspace/kind-readers.ts +7 -1
  242. package/src/workspace/member-commands.ts +22 -1
  243. package/src/workspace/nested-graph.ts +32 -1
  244. package/src/workspace/reason-codes.test.ts +7 -0
  245. package/src/workspace/reason-codes.ts +12 -0
  246. package/src/workspace/search-cli.e2e.test.ts +305 -0
  247. package/src/workspace/search-cli.ts +591 -0
  248. package/src/workspace/search-contract.ts +95 -0
  249. package/src/workspace/search.schema.json +822 -0
@@ -0,0 +1,77 @@
1
+ /**
2
+ * The ports `chant components pr-env` runs ./pr-env-run.ts with: the records
3
+ * on chant/lifecycle (`_pr-envs/records.jsonl`), the gate ledger there, and
4
+ * the note and status on the forge. They sit apart from ./pr-env-run.ts
5
+ * because the gate port loads ./pr-run.ts and ../op/gate.ts, which bring
6
+ * Ajv, js-yaml and the component driver. A product with its own ports
7
+ * imports `@intentius/chant/components/pr-env-run` and never loads these.
8
+ */
9
+ import { PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, parsePrEnvRecords, prEnvNoteMarker, prEnvStatusContext, prEnvStatusDescription, prEnvStatusState, renderPrEnvNote, } from "./pr-environment.js";
10
+ /**
11
+ * The note and the `chant/pr-env` status on the forge. A refusal from the
12
+ * forge warns and never fails the run.
13
+ */
14
+ export function forgePrEnvPublisher(forge, warn = () => { }) {
15
+ return async (report) => {
16
+ const { forgePrincipalOf } = await import("../pr-forge.js");
17
+ const note = renderPrEnvNote(report, forgePrincipalOf(forge.kind, forge.host, "<your-login>"));
18
+ if (report.head) {
19
+ try {
20
+ await forge.setStatus(report.head, { context: prEnvStatusContext(report.member), state: prEnvStatusState(report), description: prEnvStatusDescription(report), ...(forge.runUrl ? { url: forge.runUrl } : {}) });
21
+ }
22
+ catch (err) {
23
+ warn(`could not set the ${prEnvStatusContext(report.member)} status: ${messageOf(err)}`);
24
+ }
25
+ }
26
+ try {
27
+ await forge.upsertNote(report.pr, prEnvNoteMarker(report.env, report.member), note);
28
+ }
29
+ catch (err) {
30
+ warn(`could not post the note on #${report.pr}: ${messageOf(err)}`);
31
+ }
32
+ };
33
+ }
34
+ /**
35
+ * The ports over chant/lifecycle in `cwd` (default the working directory):
36
+ * the records at `_pr-envs/records.jsonl`, appended and pushed, and the gate
37
+ * ledger read without writing a pending fact. With `forge`, the note and
38
+ * status are posted and the sweep asks it whether a pull request is open.
39
+ */
40
+ export function lifecyclePrEnvPorts(opts = {}) {
41
+ const at = opts.cwd ? { cwd: opts.cwd } : undefined;
42
+ const warn = opts.warn ?? (() => { });
43
+ const forge = opts.forge;
44
+ return {
45
+ async readRecords() {
46
+ const { fetchLifecycle, readBlobFromPath } = await import("../lifecycle/git.js");
47
+ await fetchLifecycle(at).catch(() => false);
48
+ return parsePrEnvRecords(await readBlobFromPath(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, at));
49
+ },
50
+ async appendRecord(record) {
51
+ const { appendLedgerLine, fetchLifecycle, pushLifecycleReport } = await import("../lifecycle/git.js");
52
+ try {
53
+ await fetchLifecycle(at).catch(() => false);
54
+ await appendLedgerLine(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, JSON.stringify(record), `Pull request environment ${record.env} ${record.kind} (${record.result})`, at);
55
+ const pushed = await pushLifecycleReport(at);
56
+ if (pushed.pushWarning)
57
+ warn(pushed.pushWarning);
58
+ }
59
+ catch (err) {
60
+ warn(`could not record ${record.env}'s ${record.kind} on chant/lifecycle: ${messageOf(err)}`);
61
+ }
62
+ },
63
+ async decideGate(input) {
64
+ const { approvalOf, decidePrGate, readOnlyLedger } = await import("./pr-run.js");
65
+ const { gitGateLedgerPort } = await import("../op/gate.js");
66
+ const approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort(at)), input));
67
+ return { status: approval.status, ...(approval.approvedBy ? { approvedBy: approval.approvedBy } : {}) };
68
+ },
69
+ ...(forge ? { publish: forgePrEnvPublisher(forge, warn) } : {}),
70
+ ...(forge?.pullRequestState ? { pullRequestState: (pr) => forge.pullRequestState(pr) } : {}),
71
+ ...(opts.log ? { log: opts.log } : {}),
72
+ warn,
73
+ };
74
+ }
75
+ function messageOf(err) {
76
+ return err instanceof Error ? err.message : String(err);
77
+ }
@@ -0,0 +1,254 @@
1
+ /**
2
+ * Running a pull request's environment (#4330): `up`, `down` and `sweep` as
3
+ * functions over an adapter, so a product that plans and applies with a tool
4
+ * chant does not run (terragucci, with Terraform roots under suffixed state
5
+ * keys) keeps its own plan, apply and teardown and takes the rest from chant:
6
+ *
7
+ * - the gate: a non-empty plan applies only once a person's approval of its
8
+ * digest stands under gate `pr-env` (ws-080, ws-104), and an empty one
9
+ * applies at once;
10
+ * - the records on chant/lifecycle (`_pr-envs/records.jsonl`), the TTL and
11
+ * which environments stand ({@link livePrEnvironments});
12
+ * - the ownership check on teardown ({@link teardownRefusal}), and the
13
+ * marker check on every candidate before anything is deleted
14
+ * ({@link tearDownPrEnvironment});
15
+ * - the sweep over expired and closed pull requests;
16
+ * - the report and the note ({@link renderPrEnvNote}).
17
+ *
18
+ * `chant components pr-env` (../cli/handlers/pr-env.ts) runs these with the
19
+ * components adapter and the lexicons' teardown, and the ports over
20
+ * chant/lifecycle and the gate ledger in ./pr-env-ports.ts
21
+ * (`lifecyclePrEnvPorts`). Those ports load the gate and its schema checks,
22
+ * so they live apart: a product that brings its own ports bundles this
23
+ * module without them (pr-env-run-bundle.test.ts).
24
+ */
25
+ import type { ChantConfig } from "../config.js";
26
+ import type { TeardownCandidate, TeardownHole, TeardownOutcome } from "../lexicon.js";
27
+ import type { ObservationLexicon } from "../lexicon.js";
28
+ import { type LivePrEnvironment, type PrEnvRecord, type PrEnvReport, type PrEnvReportRow, type PrEnvTeardownAdapter } from "./pr-environment.js";
29
+ /** The environment one run works on. */
30
+ export interface PrEnvTarget {
31
+ pr: number;
32
+ /** `pr-<n>`. */
33
+ env: string;
34
+ template: string;
35
+ /** The marker every resource of the environment carries. */
36
+ marker: {
37
+ stack: string;
38
+ env: string;
39
+ };
40
+ /** The commit planned and applied: the pull request's head. */
41
+ head: string;
42
+ member?: string;
43
+ /** The op the gate is recorded under: `pr-<n>`, or `pr-<n>-<member>`. */
44
+ op: string;
45
+ endpoint?: string;
46
+ }
47
+ /** What an adapter's plan came to. */
48
+ export interface PrEnvPlanned {
49
+ /** The digest an approval binds. */
50
+ digest: string;
51
+ /** Nothing changes: the plan applies with no approval (ws-104). */
52
+ empty: boolean;
53
+ /** Something failed to plan, or a hook stopped it: nothing applies. */
54
+ failed?: boolean;
55
+ /** One row per component (a Terraform root, a chant component), in apply order. None: the change reaches nothing deployed, and the environment gets nothing. */
56
+ rows: PrEnvReportRow[];
57
+ message?: string;
58
+ }
59
+ /** What an adapter's apply came to. */
60
+ export interface PrEnvApplied {
61
+ /**
62
+ * `waiting`: a component read an upstream output that moved, so it waits
63
+ * for the next run. `stopped`: nothing was applied (a before-apply hook
64
+ * failed), so no record is kept.
65
+ */
66
+ status: "applied" | "failed" | "waiting" | "stopped";
67
+ /** The rows again, with each component's status after the apply. */
68
+ rows: PrEnvReportRow[];
69
+ /** Where each component's copy lives, kept on the record for the teardown (a suffixed state key). */
70
+ locations?: Record<string, string>;
71
+ message?: string;
72
+ /** The apply stands, and something after it failed (an after-apply hook): the record says applied and the run exits 1. */
73
+ afterFailure?: string;
74
+ }
75
+ /** What `up` hands an adapter's apply: the plan, and who approved it. */
76
+ export interface PrEnvApplyInput {
77
+ planned: PrEnvPlanned;
78
+ /** Who approved the digest; absent for an empty plan. */
79
+ approvedBy?: string[];
80
+ }
81
+ /**
82
+ * The plan and apply of a pull request's environment, which a product
83
+ * supplies. `plan` must not change anything; `apply` applies exactly what
84
+ * `plan` answered, once `up` decided it may.
85
+ */
86
+ export interface PrEnvAdapter {
87
+ plan(target: PrEnvTarget): Promise<PrEnvPlanned>;
88
+ apply(target: PrEnvTarget, input: PrEnvApplyInput): Promise<PrEnvApplied>;
89
+ }
90
+ /** Where the approval of a digest stands, as `decideGate` answers. */
91
+ export interface PrEnvApproval {
92
+ status: "approved" | "changed" | "pending";
93
+ approvedBy?: string[];
94
+ }
95
+ /** What the runs read and write, which tests and products replace. */
96
+ export interface PrEnvPorts {
97
+ /** Every record, oldest first. */
98
+ readRecords(): Promise<PrEnvRecord[]>;
99
+ /** Keep one record. A failure should warn: what was applied or torn down stands. */
100
+ appendRecord(record: PrEnvRecord): Promise<void>;
101
+ /** Where the approval of `digest` stands under `gate` of `op`. Throws when the ledger cannot be read. */
102
+ decideGate(input: {
103
+ op: string;
104
+ gate: string;
105
+ digest: string;
106
+ description: string;
107
+ }): Promise<PrEnvApproval>;
108
+ /** Post the report: the note and the commit status. Absent: nothing is posted. */
109
+ publish?(report: PrEnvReport): Promise<void>;
110
+ /** Whether a pull request is still open, for the sweep. Absent: only the TTL counts. */
111
+ pullRequestState?(pr: number): Promise<"open" | "closed" | "merged">;
112
+ log?(line: string): void;
113
+ warn?(message: string): void;
114
+ }
115
+ /** What one run came to. */
116
+ export interface PrEnvRunResult {
117
+ /** {@link PR_ENV_EXIT}: 0 done, 1 failed or refused, 3 waiting on an approval. */
118
+ exit: number;
119
+ report: PrEnvReport;
120
+ /** The record kept, when the run kept one. */
121
+ record?: PrEnvRecord;
122
+ }
123
+ /** The op a pull request's gate is recorded under, as `prOp` in ../pr-loop.ts names it. */
124
+ export declare function prEnvOp(pr: number, member?: string): string;
125
+ /** The approve command an adapter's caller prints, the same the note shows. */
126
+ export { prEnvApproveCommand } from "./pr-environment.js";
127
+ export interface PrEnvUpInput {
128
+ pr: number;
129
+ /** The pull request's head, which is planned and applied. */
130
+ head: string;
131
+ /** `ci.prEnvironment.template`, read at base. */
132
+ template: string;
133
+ /** `ci.prEnvironment.ttl`, read at base: `72h`, `90m`, `7d`. Default 72h. */
134
+ ttl?: string;
135
+ /** The ownership stack every resource's marker names. */
136
+ stack: string;
137
+ member?: string;
138
+ endpoint?: string;
139
+ adapter: PrEnvAdapter;
140
+ ports: PrEnvPorts;
141
+ /** Who the record names. Default `chant`. */
142
+ actor?: string;
143
+ runUrl?: string;
144
+ now?: () => Date;
145
+ }
146
+ /**
147
+ * Plan pull request `pr`'s environment through the adapter and apply it once
148
+ * the plan is empty or an approval of its digest stands under gate `pr-env`.
149
+ * An apply that failed part way is kept as live too, so what applied is torn
150
+ * down with the rest.
151
+ */
152
+ export declare function prEnvUp(input: PrEnvUpInput): Promise<PrEnvRunResult>;
153
+ /** What tears an environment down: the lexicons, and the adapters a product supplies. */
154
+ export interface PrEnvTeardownSources {
155
+ /** The project's config, for its declared environments and stacks. */
156
+ config?: ChantConfig;
157
+ plugins?: ObservationLexicon[];
158
+ adapters?: PrEnvTeardownAdapter[];
159
+ }
160
+ export interface PrEnvDownInput extends PrEnvTeardownSources {
161
+ pr: number;
162
+ reason: "closed" | "expired";
163
+ member?: string;
164
+ ports: PrEnvPorts;
165
+ /** The environment as the records say it stands. Default: read through `ports`. */
166
+ live?: LivePrEnvironment;
167
+ /** The commit the teardown runs at, for the record. */
168
+ commit: string;
169
+ actor?: string;
170
+ runUrl?: string;
171
+ now?: () => Date;
172
+ }
173
+ /**
174
+ * Tear down pull request `pr`'s environment: the ownership check first, then
175
+ * only what carries `{ stack, env: "pr-<n>" }`, through the lexicons and the
176
+ * adapters. No gate holds it: closing the pull request, or the TTL the base
177
+ * set, is the decision. A teardown that left something keeps the
178
+ * environment live for the next sweep.
179
+ */
180
+ export declare function prEnvDown(input: PrEnvDownInput): Promise<PrEnvRunResult>;
181
+ export interface PrEnvSweepInput extends PrEnvTeardownSources {
182
+ ports: PrEnvPorts;
183
+ /** Only this member's environments. Default: every environment the records name. */
184
+ member?: string;
185
+ commit: string;
186
+ actor?: string;
187
+ runUrl?: string;
188
+ now?: () => Date;
189
+ }
190
+ /**
191
+ * Tear down each live environment whose TTL passed, or whose pull request
192
+ * the forge says is closed or merged. A state that cannot be read leaves the
193
+ * TTL to decide. Exits 1 when any teardown did not finish.
194
+ */
195
+ export declare function prEnvSweep(input: PrEnvSweepInput): Promise<{
196
+ exit: number;
197
+ results: PrEnvRunResult[];
198
+ }>;
199
+ /** `ci.prEnvironment.teardown` (#4330): a command that tears down what no lexicon does. */
200
+ export interface PrEnvTeardownCommand {
201
+ /** The name its outcomes are attributed to. Default `teardown`. */
202
+ name?: string;
203
+ /** Argv. `{env}`, `{pr}` and `{stage}` are filled in. */
204
+ command: string[];
205
+ /** The lexicons it tears down in place of, as {@link PrEnvTeardownAdapter.lexicons}. */
206
+ lexicons?: string[];
207
+ }
208
+ /** The variables a teardown command reads. */
209
+ export declare const PR_ENV_TEARDOWN_ENV: {
210
+ /** `owned` or `teardown`. */
211
+ readonly stage: "CHANT_PR_ENV_STAGE";
212
+ /** `pr-<n>`. */
213
+ readonly env: "CHANT_PR_ENV";
214
+ readonly pr: "CHANT_PR_NUMBER";
215
+ readonly stack: "CHANT_PR_ENV_STACK";
216
+ readonly template: "CHANT_PR_ENV_TEMPLATE";
217
+ /** The commit last applied to the environment. */
218
+ readonly commit: "CHANT_PR_ENV_COMMIT";
219
+ /** A JSON file: `{ components, locations }` from the records. */
220
+ readonly live: "CHANT_PR_ENV_LIVE";
221
+ /** `teardown` only: a JSON file holding the candidates to delete. */
222
+ readonly candidates: "CHANT_PR_ENV_CANDIDATES";
223
+ /** The JSON file the command writes its answer to. */
224
+ readonly result: "CHANT_PR_ENV_RESULT";
225
+ };
226
+ /** Runs one argv in `cwd` with `env` as its whole environment; returns its exit code. Injected so tests run no processes. */
227
+ export type PrEnvTeardownExec = (argv: string[], cwd: string, env: Record<string, string>) => number;
228
+ /** The candidates and holes a teardown command wrote, checked as data. Throws when they do not read. */
229
+ export declare function readTeardownEnumeration(raw: unknown): {
230
+ candidates: TeardownCandidate[];
231
+ holes: TeardownHole[];
232
+ };
233
+ /** The outcomes a teardown command wrote, checked as data. A candidate it leaves out counts as failed in core. */
234
+ export declare function readTeardownOutcomes(raw: unknown): TeardownOutcome[];
235
+ /**
236
+ * `ci.prEnvironment.teardown` as an adapter (#4330). chant runs the command
237
+ * twice, in `cwd`, with the job's environment less every forge token
238
+ * variable, and these besides ({@link PR_ENV_TEARDOWN_ENV}):
239
+ *
240
+ * - `CHANT_PR_ENV_STAGE=owned`: the command writes `{ candidates, holes }`
241
+ * to `CHANT_PR_ENV_RESULT`, each candidate with the marker it read back.
242
+ * - `CHANT_PR_ENV_STAGE=teardown`: it deletes the candidates in
243
+ * `CHANT_PR_ENV_CANDIDATES`, which chant has checked against the marker,
244
+ * and writes `{ outcomes }` to `CHANT_PR_ENV_RESULT`.
245
+ *
246
+ * A non-zero exit, or an answer that does not read, is a hole (`owned`) or a
247
+ * failure for every candidate (`teardown`), so the environment stays live.
248
+ */
249
+ export declare function commandTeardownAdapter(hook: PrEnvTeardownCommand, opts: {
250
+ cwd: string;
251
+ env?: Record<string, string | undefined>;
252
+ exec?: PrEnvTeardownExec;
253
+ }): PrEnvTeardownAdapter;
254
+ //# sourceMappingURL=pr-env-run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pr-env-run.d.ts","sourceRoot":"","sources":["../../src/components/pr-env-run.ts"],"names":[],"mappings":"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"}