@intentius/chant 0.124.84 → 0.124.86

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 (254) hide show
  1. package/dist/bundle-check.d.ts +102 -0
  2. package/dist/bundle-check.d.ts.map +1 -0
  3. package/dist/bundle-check.js +310 -0
  4. package/dist/chant-install.d.ts +100 -0
  5. package/dist/chant-install.d.ts.map +1 -0
  6. package/dist/chant-install.js +158 -0
  7. package/dist/ci-commit.d.ts +19 -6
  8. package/dist/ci-commit.d.ts.map +1 -1
  9. package/dist/ci-commit.js +23 -4
  10. package/dist/ci-evidence-jobs.d.ts +54 -0
  11. package/dist/ci-evidence-jobs.d.ts.map +1 -0
  12. package/dist/ci-evidence-jobs.js +55 -0
  13. package/dist/ci-image.d.ts +274 -0
  14. package/dist/ci-image.d.ts.map +1 -0
  15. package/dist/ci-image.js +635 -0
  16. package/dist/ci-login.d.ts +150 -0
  17. package/dist/ci-login.d.ts.map +1 -0
  18. package/dist/ci-login.js +240 -0
  19. package/dist/ci-product.d.ts +16 -0
  20. package/dist/ci-product.d.ts.map +1 -1
  21. package/dist/ci-product.js +17 -0
  22. package/dist/cli/commands/import-index.js +2 -2
  23. package/dist/cli/handlers/build.d.ts +8 -0
  24. package/dist/cli/handlers/build.d.ts.map +1 -1
  25. package/dist/cli/handlers/build.js +22 -4
  26. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  27. package/dist/cli/handlers/ci-check.js +57 -2
  28. package/dist/cli/handlers/ci-evidence.d.ts +3 -0
  29. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -0
  30. package/dist/cli/handlers/ci-evidence.js +171 -0
  31. package/dist/cli/handlers/components.js +3 -3
  32. package/dist/cli/handlers/dead-guards.d.ts +3 -0
  33. package/dist/cli/handlers/dead-guards.d.ts.map +1 -0
  34. package/dist/cli/handlers/dead-guards.js +35 -0
  35. package/dist/cli/handlers/graph.js +4 -4
  36. package/dist/cli/handlers/lifecycle.d.ts +2 -1
  37. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  38. package/dist/cli/handlers/lifecycle.js +5 -4
  39. package/dist/cli/handlers/local-chant.d.ts +16 -0
  40. package/dist/cli/handlers/local-chant.d.ts.map +1 -0
  41. package/dist/cli/handlers/local-chant.js +109 -0
  42. package/dist/cli/handlers/operator.js +2 -2
  43. package/dist/cli/handlers/search.js +5 -5
  44. package/dist/cli/main.d.ts.map +1 -1
  45. package/dist/cli/main.js +38 -0
  46. package/dist/cli/parse-args.d.ts.map +1 -1
  47. package/dist/cli/parse-args.js +28 -0
  48. package/dist/cli/registry.d.ts +16 -0
  49. package/dist/cli/registry.d.ts.map +1 -1
  50. package/dist/components/check-hooks.d.ts +49 -0
  51. package/dist/components/check-hooks.d.ts.map +1 -1
  52. package/dist/components/check-hooks.js +64 -4
  53. package/dist/components/check-steps.d.ts +17 -0
  54. package/dist/components/check-steps.d.ts.map +1 -1
  55. package/dist/components/check-steps.js +37 -5
  56. package/dist/components/product-pipeline.d.ts +23 -0
  57. package/dist/components/product-pipeline.d.ts.map +1 -1
  58. package/dist/components/product-pipeline.js +6 -2
  59. package/dist/components/product-plan.d.ts +137 -0
  60. package/dist/components/product-plan.d.ts.map +1 -0
  61. package/dist/components/product-plan.js +143 -0
  62. package/dist/components/release-compile.d.ts.map +1 -1
  63. package/dist/components/release-compile.js +2 -2
  64. package/dist/config.d.ts +39 -1
  65. package/dist/config.d.ts.map +1 -1
  66. package/dist/config.js +35 -3
  67. package/dist/dead-guards.d.ts +82 -0
  68. package/dist/dead-guards.d.ts.map +1 -0
  69. package/dist/dead-guards.js +436 -0
  70. package/dist/discovery/files.d.ts +3 -1
  71. package/dist/discovery/files.d.ts.map +1 -1
  72. package/dist/discovery/files.js +5 -3
  73. package/dist/drift-issue.d.ts +152 -0
  74. package/dist/drift-issue.d.ts.map +1 -0
  75. package/dist/drift-issue.js +167 -0
  76. package/dist/floor-table.d.ts +30 -0
  77. package/dist/floor-table.d.ts.map +1 -0
  78. package/dist/floor-table.data.d.ts +3 -0
  79. package/dist/floor-table.data.d.ts.map +1 -0
  80. package/dist/floor-table.data.js +178 -0
  81. package/dist/floor-table.js +56 -0
  82. package/dist/forge-flags.d.ts +90 -0
  83. package/dist/forge-flags.d.ts.map +1 -0
  84. package/dist/forge-flags.js +184 -0
  85. package/dist/lexicon.d.ts +69 -0
  86. package/dist/lexicon.d.ts.map +1 -1
  87. package/dist/lifecycle/gated-op.d.ts +7 -1
  88. package/dist/lifecycle/gated-op.d.ts.map +1 -1
  89. package/dist/lifecycle/gated-op.js +7 -4
  90. package/dist/local-chant.d.ts +98 -0
  91. package/dist/local-chant.d.ts.map +1 -0
  92. package/dist/local-chant.js +307 -0
  93. package/dist/op/activities/predict-behaviour.js +2 -2
  94. package/dist/op/op-waves-evidence-spec.d.ts +13 -0
  95. package/dist/op/op-waves-evidence-spec.d.ts.map +1 -0
  96. package/dist/op/op-waves-evidence-spec.js +21 -0
  97. package/dist/op/op-waves-evidence.d.ts +38 -0
  98. package/dist/op/op-waves-evidence.d.ts.map +1 -0
  99. package/dist/op/op-waves-evidence.js +57 -0
  100. package/dist/op/op-waves-run.d.ts +4 -0
  101. package/dist/op/op-waves-run.d.ts.map +1 -1
  102. package/dist/op/op-waves-run.js +24 -1
  103. package/dist/op/op-waves.d.ts +17 -1
  104. package/dist/op/op-waves.d.ts.map +1 -1
  105. package/dist/op/op-waves.js +23 -0
  106. package/dist/op/schedule-overdue.d.ts +41 -9
  107. package/dist/op/schedule-overdue.d.ts.map +1 -1
  108. package/dist/op/schedule-overdue.js +154 -25
  109. package/dist/plan-summary.d.ts +25 -0
  110. package/dist/plan-summary.d.ts.map +1 -1
  111. package/dist/plan-summary.js +31 -0
  112. package/dist/pr-plan-note.d.ts +35 -0
  113. package/dist/pr-plan-note.d.ts.map +1 -1
  114. package/dist/pr-plan-note.js +10 -0
  115. package/dist/pr-post.d.ts +23 -0
  116. package/dist/pr-post.d.ts.map +1 -1
  117. package/dist/pr-post.js +125 -3
  118. package/dist/release-floors.d.ts +31 -1
  119. package/dist/release-floors.d.ts.map +1 -1
  120. package/dist/release-floors.js +31 -1
  121. package/dist/state-migration.d.ts +24 -0
  122. package/dist/state-migration.d.ts.map +1 -1
  123. package/dist/state-migration.js +100 -5
  124. package/dist/wave-runtime.mjs +305 -298
  125. package/dist/workspace/lexicon-outputs.d.ts.map +1 -1
  126. package/dist/workspace/lexicon-outputs.js +21 -7
  127. package/dist/workspace/reason-codes.d.ts +3 -0
  128. package/dist/workspace/reason-codes.d.ts.map +1 -1
  129. package/dist/workspace/reason-codes.js +4 -0
  130. package/dist/workspace/ref-gate.schema.json +85 -0
  131. package/dist/workspace/search-contract.d.ts +1 -1
  132. package/dist/workspace/search-contract.d.ts.map +1 -1
  133. package/dist/workspace/trust/check-evidence-report.d.ts +51 -0
  134. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -0
  135. package/dist/workspace/trust/check-evidence-report.js +102 -0
  136. package/dist/workspace/trust/check-evidence.d.ts +126 -0
  137. package/dist/workspace/trust/check-evidence.d.ts.map +1 -0
  138. package/dist/workspace/trust/check-evidence.js +237 -0
  139. package/dist/workspace/trust/local-evidence.d.ts +120 -0
  140. package/dist/workspace/trust/local-evidence.d.ts.map +1 -0
  141. package/dist/workspace/trust/local-evidence.js +259 -0
  142. package/dist/workspace/trust/policy.d.ts +84 -0
  143. package/dist/workspace/trust/policy.d.ts.map +1 -1
  144. package/dist/workspace/trust/policy.js +94 -1
  145. package/dist/workspace/trust/ref-gate-cli.d.ts +33 -0
  146. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -0
  147. package/dist/workspace/trust/ref-gate-cli.js +234 -0
  148. package/dist/workspace/trust/ref-gate-fixture.d.ts +38 -0
  149. package/dist/workspace/trust/ref-gate-fixture.d.ts.map +1 -0
  150. package/dist/workspace/trust/ref-gate-fixture.js +97 -0
  151. package/dist/workspace/trust/ref-gate.d.ts +187 -0
  152. package/dist/workspace/trust/ref-gate.d.ts.map +1 -0
  153. package/dist/workspace/trust/ref-gate.js +430 -0
  154. package/dist/workspace/trust/trust-files.d.ts.map +1 -1
  155. package/dist/workspace/trust/trust-files.js +18 -1
  156. package/package.json +1 -1
  157. package/src/bundle-check.test.ts +140 -0
  158. package/src/bundle-check.ts +352 -0
  159. package/src/chant-install.test.ts +112 -0
  160. package/src/chant-install.ts +179 -0
  161. package/src/ci-commit.test.ts +45 -0
  162. package/src/ci-commit.ts +38 -4
  163. package/src/ci-evidence-jobs.ts +67 -0
  164. package/src/ci-image.test.ts +506 -0
  165. package/src/ci-image.ts +822 -0
  166. package/src/ci-login.test.ts +235 -0
  167. package/src/ci-login.ts +307 -0
  168. package/src/ci-product.ts +18 -0
  169. package/src/cli/commands/__fixtures__/source-dir-include/chant.config.json +1 -0
  170. package/src/cli/commands/__fixtures__/source-dir-include/infra.ts +1 -0
  171. package/src/cli/commands/__fixtures__/source-dir-include/scripts/run-on-load.ts +3 -0
  172. package/src/cli/commands/__fixtures__/source-dir-root/chant.config.json +1 -0
  173. package/src/cli/commands/__fixtures__/source-dir-root/infra.test.ts +1 -0
  174. package/src/cli/commands/__fixtures__/source-dir-root/infra.ts +1 -0
  175. package/src/cli/commands/__fixtures__/source-dir-root/scripts/run-on-load.ts +3 -0
  176. package/src/cli/commands/__fixtures__/source-dir-scoped/app.ts +3 -0
  177. package/src/cli/commands/__fixtures__/source-dir-scoped/chant.config.json +1 -0
  178. package/src/cli/commands/__fixtures__/source-dir-scoped/infra/net.ts +1 -0
  179. package/src/cli/commands/__fixtures__/source-dir-scoped/scripts/run-on-load.ts +3 -0
  180. package/src/cli/commands/import-index.ts +2 -2
  181. package/src/cli/handlers/build-source-dir.test.ts +64 -0
  182. package/src/cli/handlers/build.ts +21 -4
  183. package/src/cli/handlers/ci-check.ts +56 -3
  184. package/src/cli/handlers/ci-evidence.ts +162 -0
  185. package/src/cli/handlers/components.ts +3 -3
  186. package/src/cli/handlers/dead-guards.ts +37 -0
  187. package/src/cli/handlers/graph.ts +4 -4
  188. package/src/cli/handlers/lifecycle.ts +5 -4
  189. package/src/cli/handlers/local-chant.ts +106 -0
  190. package/src/cli/handlers/operator.ts +2 -2
  191. package/src/cli/handlers/search.ts +5 -5
  192. package/src/cli/main.test.ts +7 -0
  193. package/src/cli/main.ts +38 -0
  194. package/src/cli/parse-args.ts +21 -0
  195. package/src/cli/registry.ts +16 -0
  196. package/src/components/check-evidence-stage.test.ts +80 -0
  197. package/src/components/check-hooks.ts +84 -4
  198. package/src/components/check-local-evidence-stage.test.ts +141 -0
  199. package/src/components/check-steps.ts +56 -6
  200. package/src/components/product-pipeline.ts +28 -3
  201. package/src/components/product-plan.test.ts +87 -0
  202. package/src/components/product-plan.ts +226 -0
  203. package/src/components/release-compile.ts +2 -2
  204. package/src/config.ts +44 -3
  205. package/src/dead-guards.test.ts +206 -0
  206. package/src/dead-guards.ts +446 -0
  207. package/src/discovery/files.ts +5 -3
  208. package/src/drift-issue-bundle.test.ts +31 -0
  209. package/src/drift-issue.test.ts +206 -0
  210. package/src/drift-issue.ts +274 -0
  211. package/src/fit-note.test.ts +44 -0
  212. package/src/floor-table.data.ts +180 -0
  213. package/src/floor-table.ts +77 -0
  214. package/src/forge-flags.test.ts +110 -0
  215. package/src/forge-flags.ts +208 -0
  216. package/src/gate-decision-bundle.test.ts +1 -0
  217. package/src/lexicon.ts +68 -0
  218. package/src/lifecycle/gated-op.ts +10 -5
  219. package/src/local-chant.e2e.test.ts +94 -0
  220. package/src/local-chant.test.ts +162 -0
  221. package/src/local-chant.ts +341 -0
  222. package/src/op/activities/predict-behaviour.ts +2 -2
  223. package/src/op/op-waves-evidence-spec.ts +24 -0
  224. package/src/op/op-waves-evidence.test.ts +130 -0
  225. package/src/op/op-waves-evidence.ts +57 -0
  226. package/src/op/op-waves-run.ts +25 -1
  227. package/src/op/op-waves.ts +31 -1
  228. package/src/op/schedule-overdue.test.ts +85 -0
  229. package/src/op/schedule-overdue.ts +162 -26
  230. package/src/plan-summary.ts +40 -0
  231. package/src/pr-plan-note.ts +34 -0
  232. package/src/pr-post-plan-note.test.ts +146 -0
  233. package/src/pr-post.ts +127 -3
  234. package/src/release-floors.ts +44 -1
  235. package/src/stage-hooks-bundle.test.ts +1 -0
  236. package/src/state-migration.test.ts +52 -1
  237. package/src/state-migration.ts +107 -5
  238. package/src/workspace/lexicon-outputs.ts +23 -6
  239. package/src/workspace/reason-codes.test.ts +3 -0
  240. package/src/workspace/reason-codes.ts +4 -0
  241. package/src/workspace/ref-gate.schema.json +85 -0
  242. package/src/workspace/trust/check-evidence-report.ts +106 -0
  243. package/src/workspace/trust/check-evidence.test.ts +133 -0
  244. package/src/workspace/trust/check-evidence.ts +257 -0
  245. package/src/workspace/trust/local-evidence.test.ts +127 -0
  246. package/src/workspace/trust/local-evidence.ts +266 -0
  247. package/src/workspace/trust/policy.ts +134 -1
  248. package/src/workspace/trust/ref-gate-cli.ts +244 -0
  249. package/src/workspace/trust/ref-gate-fixture.ts +125 -0
  250. package/src/workspace/trust/ref-gate.e2e.test.ts +76 -0
  251. package/src/workspace/trust/ref-gate.test.ts +247 -0
  252. package/src/workspace/trust/ref-gate.ts +538 -0
  253. package/src/workspace/trust/trust-files.test.ts +16 -0
  254. package/src/workspace/trust/trust-files.ts +41 -1
@@ -0,0 +1,822 @@
1
+ /**
2
+ * CI images and engine installs for a CI product (#4784).
3
+ *
4
+ * terragucci, plywood and SQL Yodeler each built their CI image the same way:
5
+ * `node:22-bookworm-slim` by digest, git and CA certificates,
6
+ * `safe.directory '*'`, the product's bundle and the OCI labels, with each
7
+ * engine fetched in a separate stage and checked there. Each also installed
8
+ * engines in a job, and terragucci at run time from Node. This module is the
9
+ * one copy:
10
+ *
11
+ * - {@link ciToolRelease} names every engine release a product installs
12
+ * (tofu, terraform, terragrunt, choudoufu, infracost, cosign, atmos,
13
+ * terramate, pulumi, plunge, the AWS CLI, just, act) for Linux on amd64
14
+ * and arm64.
15
+ * - {@link CI_TOOL_SHA256} records the sha256 chant knows for a release. A
16
+ * product records others in its own config and passes them as `sha256`.
17
+ * - {@link ciToolFetchScript} is the shell that downloads one release and
18
+ * checks it, for an image's fetch stage; {@link ciToolInstallLine} is the
19
+ * job line that runs it unless the binary is there; {@link installCiTool}
20
+ * does the same from Node, for a product that installs a pinned release
21
+ * at run time.
22
+ * - {@link productImageStages} is a product's image as stages a Dockerfile
23
+ * takes (the docker lexicon's `new Dockerfile({ stages })`), and
24
+ * {@link productImageDockerfile} is the same as text. The product passes
25
+ * its name, its bundle, its words and its engines.
26
+ * - {@link derivedImageDockerfile} is an image a user builds FROM the
27
+ * product's, such as a provider mirror or preinstalled plugins.
28
+ *
29
+ * Every check follows one rule, in the shell and in Node. A release whose
30
+ * project publishes a checksums file is checked against that file's line
31
+ * for the archive, and against the recorded sha256 when there is one, so a
32
+ * tampered checksums file fails as a tampered archive does. A release with
33
+ * no checksums file (the AWS CLI, just, act) needs a recorded sha256. An
34
+ * image always needs a recorded sha256 for both architectures, and a caller
35
+ * passes `requirePin` to ask the same of a job line or a run-time install.
36
+ *
37
+ * Like `./policy-engine.ts` this module imports only node built-ins and
38
+ * chant's release floors, so a product can bundle it or import it from a
39
+ * plain Node script.
40
+ */
41
+
42
+ import { spawnSync } from "node:child_process";
43
+ import { createHash, randomBytes } from "node:crypto";
44
+ import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
45
+ import { tmpdir } from "node:os";
46
+ import { join } from "node:path";
47
+ import { gunzipSync, inflateRawSync } from "node:zlib";
48
+ import { tarEntry } from "./policy-engine";
49
+ import { CI_IMAGE_FLOOR } from "./release-floors";
50
+
51
+ export { CI_IMAGE_FLOOR };
52
+
53
+ // ---------------------------------------------------------------------------
54
+ // Engine releases
55
+
56
+ export type CiTool =
57
+ | "tofu"
58
+ | "terraform"
59
+ | "terragrunt"
60
+ | "choudoufu"
61
+ | "infracost"
62
+ | "cosign"
63
+ | "atmos"
64
+ | "terramate"
65
+ | "pulumi"
66
+ | "plunge"
67
+ | "aws-cli"
68
+ | "just"
69
+ | "act";
70
+
71
+ /** The architectures chant fetches, as Docker's `TARGETARCH` names them. */
72
+ export type CiToolArch = "amd64" | "arm64";
73
+ export const CI_TOOL_ARCHES: readonly CiToolArch[] = ["amd64", "arm64"];
74
+
75
+ /**
76
+ * How a release file holds its binary: the file is the binary, a `.tar.gz`
77
+ * or `.zip` holds it as `member`, a `.tar.gz` holds a tree with one top
78
+ * directory that is unpacked whole (Pulumi's language hosts sit beside the
79
+ * binary), or the AWS CLI's zip with its own installer.
80
+ */
81
+ export type CiToolLayout = "binary" | "tar.gz" | "zip" | "tree" | "aws-cli";
82
+
83
+ interface ToolSpec {
84
+ /** The command's name on PATH. */
85
+ bin: string;
86
+ /** The release's architecture word for each of chant's. */
87
+ words: Record<CiToolArch, string>;
88
+ base(version: string): string;
89
+ asset(version: string, word: string): string;
90
+ /** The checksums file, beside the asset under `base`; absent when the release publishes none. */
91
+ checksums?(version: string, asset: string): string;
92
+ layout: CiToolLayout;
93
+ /** The binary inside the archive, for `tar.gz` and `zip`. Default `bin`. */
94
+ member?(word: string): string;
95
+ /** The binary under the install directory, for `tree` and `aws-cli`. Default `bin`. */
96
+ path?: string;
97
+ }
98
+
99
+ const STD = { amd64: "amd64", arm64: "arm64" };
100
+ const GNU = { amd64: "x86_64", arm64: "aarch64" };
101
+ const NODE_WORDS = { amd64: "x64", arm64: "arm64" };
102
+
103
+ const TOOLS: Record<CiTool, ToolSpec> = {
104
+ tofu: {
105
+ bin: "tofu",
106
+ words: STD,
107
+ base: (v) => `https://github.com/opentofu/opentofu/releases/download/v${v}`,
108
+ asset: (v, w) => `tofu_${v}_linux_${w}.tar.gz`,
109
+ checksums: (v) => `tofu_${v}_SHA256SUMS`,
110
+ layout: "tar.gz",
111
+ },
112
+ terraform: {
113
+ bin: "terraform",
114
+ words: STD,
115
+ base: (v) => `https://releases.hashicorp.com/terraform/${v}`,
116
+ asset: (v, w) => `terraform_${v}_linux_${w}.zip`,
117
+ checksums: (v) => `terraform_${v}_SHA256SUMS`,
118
+ layout: "zip",
119
+ },
120
+ terragrunt: {
121
+ bin: "terragrunt",
122
+ words: STD,
123
+ base: (v) => `https://github.com/gruntwork-io/terragrunt/releases/download/v${v}`,
124
+ asset: (_v, w) => `terragrunt_linux_${w}`,
125
+ checksums: () => "SHA256SUMS",
126
+ layout: "binary",
127
+ },
128
+ choudoufu: {
129
+ bin: "choudoufu",
130
+ words: STD,
131
+ base: (v) => `https://github.com/INTENTIUS/choudoufu/releases/download/v${v}`,
132
+ asset: (v, w) => `choudoufu_v${v}_linux_${w}.tar.gz`,
133
+ checksums: () => "SHA256SUMS",
134
+ layout: "tar.gz",
135
+ },
136
+ infracost: {
137
+ bin: "infracost",
138
+ words: STD,
139
+ base: (v) => `https://github.com/infracost/infracost/releases/download/v${v}`,
140
+ asset: (_v, w) => `infracost-linux-${w}.tar.gz`,
141
+ // Each file has its own checksum file, in SHA256SUMS form.
142
+ checksums: (_v, asset) => `${asset}.sha256`,
143
+ layout: "tar.gz",
144
+ member: (w) => `infracost-linux-${w}`,
145
+ },
146
+ cosign: {
147
+ bin: "cosign",
148
+ words: STD,
149
+ base: (v) => `https://github.com/sigstore/cosign/releases/download/v${v}`,
150
+ asset: (_v, w) => `cosign-linux-${w}`,
151
+ checksums: () => "cosign_checksums.txt",
152
+ layout: "binary",
153
+ },
154
+ atmos: {
155
+ bin: "atmos",
156
+ words: STD,
157
+ base: (v) => `https://github.com/cloudposse/atmos/releases/download/v${v}`,
158
+ asset: (v, w) => `atmos_${v}_linux_${w}`,
159
+ checksums: (v) => `atmos_${v}_SHA256SUMS`,
160
+ layout: "binary",
161
+ },
162
+ terramate: {
163
+ bin: "terramate",
164
+ words: { amd64: "x86_64", arm64: "arm64" },
165
+ base: (v) => `https://github.com/terramate-io/terramate/releases/download/v${v}`,
166
+ asset: (v, w) => `terramate_${v}_linux_${w}.tar.gz`,
167
+ checksums: () => "checksums.txt",
168
+ layout: "tar.gz",
169
+ },
170
+ pulumi: {
171
+ bin: "pulumi",
172
+ words: NODE_WORDS,
173
+ base: (v) => `https://github.com/pulumi/pulumi/releases/download/v${v}`,
174
+ asset: (v, w) => `pulumi-v${v}-linux-${w}.tar.gz`,
175
+ checksums: (v) => `pulumi-${v}-checksums.txt`,
176
+ layout: "tree",
177
+ },
178
+ plunge: {
179
+ bin: "plunge",
180
+ words: NODE_WORDS,
181
+ base: (v) => `https://github.com/INTENTIUS/plunge/releases/download/plunge-v${v}`,
182
+ asset: (v, w) => `plunge-v${v}-linux-${w}.tar.gz`,
183
+ checksums: (v) => `plunge-v${v}-checksums.txt`,
184
+ layout: "tree",
185
+ },
186
+ "aws-cli": {
187
+ bin: "aws",
188
+ words: GNU,
189
+ base: () => "https://awscli.amazonaws.com",
190
+ asset: (v, w) => `awscli-exe-linux-${w}-${v}.zip`,
191
+ layout: "aws-cli",
192
+ path: "v2/current/bin/aws",
193
+ },
194
+ just: {
195
+ bin: "just",
196
+ words: GNU,
197
+ base: (v) => `https://github.com/casey/just/releases/download/${v}`,
198
+ asset: (v, w) => `just-${v}-${w}-unknown-linux-musl.tar.gz`,
199
+ layout: "tar.gz",
200
+ },
201
+ act: {
202
+ bin: "act",
203
+ words: { amd64: "x86_64", arm64: "arm64" },
204
+ base: (v) => `https://github.com/nektos/act/releases/download/v${v}`,
205
+ asset: (_v, w) => `act_Linux_${w}.tar.gz`,
206
+ layout: "tar.gz",
207
+ },
208
+ };
209
+
210
+ export const CI_TOOLS: readonly CiTool[] = Object.keys(TOOLS) as CiTool[];
211
+
212
+ /**
213
+ * The sha256 of each release file chant records, as
214
+ * `<tool>-<version>-linux-<arch>`, copied from the release's checksums file
215
+ * (the AWS CLI's from the archives, as plywood and terragucci recorded them).
216
+ * A checksums file that lists another sum for one of these fails the
217
+ * install. Add a release's two lines when a product moves to it, or record
218
+ * them in the product's config and pass `sha256`.
219
+ */
220
+ export const CI_TOOL_SHA256: Readonly<Record<string, string>> = {
221
+ "tofu-1.13.1-linux-amd64": "378ada19d4bc70c43732004e8159be771b23b9a5afdf059e5f8a2b3fa2c70a69",
222
+ "tofu-1.13.1-linux-arm64": "9c1ef375aa1852db0b2888aa921b640c71f8140d4682aa4fec99378a64fa7dc3",
223
+ "choudoufu-0.31.0-linux-amd64": "1f38e5840b2e8c82e13a90652a9ffd75d5fbdff691f3f1a0ecee33fb8e4fae5b",
224
+ "choudoufu-0.31.0-linux-arm64": "00c9dc5c0a4260bae577bce081bc7fb7f2cc9f56757de2da4b3bdb4afaff3586",
225
+ "pulumi-3.272.0-linux-amd64": "58d545f2b98761051922008ebd381ecef95484d7f7a5ff7faa15d7a780ea84f6",
226
+ "pulumi-3.272.0-linux-arm64": "4f0741901b8982c4326b702dabf483c63d2cf77c88ac42dd752b72541284a534",
227
+ "plunge-0.1.0-linux-amd64": "22b89da39ab7dc11268c7b625fec3d99c0793c9c47bf8d031fa94e6967ee8187",
228
+ "plunge-0.1.0-linux-arm64": "6855611b8cf8381d73f5ddf0b5c0a0d83bdc2a5bd8c50d415e52bb05a4574f83",
229
+ "plunge-0.2.0-linux-amd64": "c9c73d05cca9ad214b7f44230a6162cdcb6ad64bbfc725bc94688b997b191495",
230
+ "plunge-0.2.0-linux-arm64": "c176a82f038164085aa19c8ad6530d6022e560e124050e535dbe364ae0473357",
231
+ "aws-cli-2.22.0-linux-amd64": "f315aa564190a12ae05a05bd8ab7b0645dd4a1ad71ce9e47dae4ff3dfeee8ceb",
232
+ "aws-cli-2.22.0-linux-arm64": "c932ac00901ea3c430f3829140b8dc00fa6e9b8b99d6891929a4795947de7f3e",
233
+ };
234
+
235
+ /** One release file of one tool for one architecture. */
236
+ export interface CiToolRelease {
237
+ tool: CiTool;
238
+ version: string;
239
+ arch: CiToolArch;
240
+ /** The command's name on PATH. */
241
+ bin: string;
242
+ /** The release file's name. */
243
+ asset: string;
244
+ url: string;
245
+ /** The release's checksums file, when it publishes one. */
246
+ checksumsUrl?: string;
247
+ /** Its name, for messages. */
248
+ checksums?: string;
249
+ layout: CiToolLayout;
250
+ /** The binary inside a `tar.gz` or `zip`. */
251
+ member: string;
252
+ /** The binary under the install directory. */
253
+ path: string;
254
+ }
255
+
256
+ const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;
257
+ const SHA256 = /^[0-9a-f]{64}$/;
258
+ const DIR = /^\/[A-Za-z0-9._/-]*$/;
259
+
260
+ function spec(tool: CiTool): ToolSpec {
261
+ const s = TOOLS[tool];
262
+ if (!s) throw new Error(`chant installs ${CI_TOOLS.join(", ")}, not ${JSON.stringify(tool)}`);
263
+ return s;
264
+ }
265
+
266
+ function checkVersion(tool: CiTool, version: string): void {
267
+ if (!VERSION.test(version)) throw new Error(`${tool} version ${JSON.stringify(version)} is not a release version such as 1.2.3`);
268
+ }
269
+
270
+ /** The release file of `tool` at `version` for `arch`. A version is a plain semver, so it is safe on a shell line. */
271
+ export function ciToolRelease(tool: CiTool, version: string, arch: CiToolArch): CiToolRelease {
272
+ const s = spec(tool);
273
+ checkVersion(tool, version);
274
+ const word = s.words[arch];
275
+ if (!word) throw new Error(`chant fetches ${tool} for ${CI_TOOL_ARCHES.join(" and ")}, not ${JSON.stringify(arch)}`);
276
+ const base = s.base(version);
277
+ const asset = s.asset(version, word);
278
+ const checksums = s.checksums?.(version, asset);
279
+ return {
280
+ tool,
281
+ version,
282
+ arch,
283
+ bin: s.bin,
284
+ asset,
285
+ url: `${base}/${asset}`,
286
+ ...(checksums ? { checksums, checksumsUrl: `${base}/${checksums}` } : {}),
287
+ layout: s.layout,
288
+ member: s.member?.(word) ?? s.bin,
289
+ path: s.path ?? s.bin,
290
+ };
291
+ }
292
+
293
+ /** The recorded sha256 of `tool` at `version` by architecture: the caller's, else {@link CI_TOOL_SHA256}'s. */
294
+ export function ciToolSha256(tool: CiTool, version: string, given?: Partial<Record<CiToolArch, string>>): Partial<Record<CiToolArch, string>> {
295
+ spec(tool);
296
+ checkVersion(tool, version);
297
+ const out: Partial<Record<CiToolArch, string>> = {};
298
+ for (const arch of CI_TOOL_ARCHES) {
299
+ const sum = given ? given[arch] : CI_TOOL_SHA256[`${tool}-${version}-linux-${arch}`];
300
+ if (sum === undefined) continue;
301
+ if (!SHA256.test(sum)) throw new Error(`the recorded sha256 for ${tool} ${version} on ${arch} is not 64 lower-case hex digits`);
302
+ out[arch] = sum;
303
+ }
304
+ return out;
305
+ }
306
+
307
+ /** Where a tool lives once installed: `<root>/<tool>-<version>`. */
308
+ export function ciToolDir(tool: CiTool, version: string, root: string): string {
309
+ checkVersion(tool, version);
310
+ if (!DIR.test(root)) throw new Error(`a tool root is an absolute path of letters, digits and ._/-, not ${JSON.stringify(root)}`);
311
+ return `${root.replace(/\/+$/, "")}/${tool}-${version}`;
312
+ }
313
+
314
+ /** The binary's path once installed under `root`. */
315
+ export function ciToolBin(tool: CiTool, version: string, root: string): string {
316
+ const s = spec(tool);
317
+ return `${ciToolDir(tool, version, root)}/${s.path ?? s.bin}`;
318
+ }
319
+
320
+ // ---------------------------------------------------------------------------
321
+ // The shell check, for an image's fetch stage and a job line
322
+
323
+ /** A shell expression giving the job's architecture as amd64 or arm64. */
324
+ export const CI_TOOL_JOB_ARCH = `"$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"`;
325
+
326
+ /** A Docker build's target architecture (`ARG TARGETARCH`), amd64 or arm64. */
327
+ export const CI_TOOL_DOCKER_ARCH = `"$TARGETARCH"`;
328
+
329
+ export interface CiToolCheckOptions {
330
+ /** Recorded sums by architecture, in place of {@link CI_TOOL_SHA256}'s for this release. */
331
+ sha256?: Partial<Record<CiToolArch, string>>;
332
+ /** Refuse a release with no recorded sha256 for an architecture, rather than trust its checksums file alone. Default false. */
333
+ requirePin?: boolean;
334
+ }
335
+
336
+ export interface CiToolFetchOptions extends CiToolCheckOptions {
337
+ /** The directory the tool installs into, an absolute path: {@link ciToolDir} under the image's tool root. */
338
+ dir: string;
339
+ /** A shell expression giving amd64 or arm64. Default {@link CI_TOOL_JOB_ARCH}; an image build passes {@link CI_TOOL_DOCKER_ARCH}. */
340
+ arch?: string;
341
+ /** A shell word for the checksums file's URL, such as `"$CHECKSUMS_URL"`. Default the release's own. */
342
+ checksumsUrl?: string;
343
+ }
344
+
345
+ function needPins(tool: CiTool, version: string, sums: Partial<Record<CiToolArch, string>>, requirePin: boolean): void {
346
+ const hasSums = spec(tool).checksums !== undefined;
347
+ const missing = CI_TOOL_ARCHES.filter((a) => !sums[a]);
348
+ if (missing.length && (requirePin || !hasSums)) {
349
+ const why = hasSums ? "" : `; ${tool}'s release publishes no checksums file, so chant needs one`;
350
+ throw new Error(`no recorded sha256 for ${tool} ${version} on ${missing.join(" and ")}${why}: record it from the release's checksums in the product's config and pass sha256`);
351
+ }
352
+ }
353
+
354
+ /**
355
+ * Shell that downloads one release into `dir` and checks it (#4784). Run it
356
+ * under `set -e`. `arch` and `checksumsUrl` go onto the line as they are, so
357
+ * they are the caller's shell, never a value from outside. Throws when the
358
+ * release needs a recorded sha256 it lacks.
359
+ */
360
+ export function ciToolFetchScript(tool: CiTool, version: string, options: CiToolFetchOptions): string {
361
+ if (!DIR.test(options.dir)) throw new Error(`a fetch directory is an absolute path of letters, digits and ._/-, not ${JSON.stringify(options.dir)}`);
362
+ const s = spec(tool);
363
+ const sums = ciToolSha256(tool, version, options.sha256);
364
+ needPins(tool, version, sums, options.requirePin === true);
365
+ const name = `${tool} ${version}`;
366
+ const base = s.base(version);
367
+ const file = s.asset(version, "$w");
368
+ const dir = options.dir;
369
+ const lines = [
370
+ `a=${options.arch ?? CI_TOOL_JOB_ARCH}`,
371
+ `case "$a" in ${CI_TOOL_ARCHES.map((a) => `(${a}) w=${s.words[a]} ;;`).join(" ")} (*) echo "${name}: chant fetches it for ${CI_TOOL_ARCHES.join(" and ")}, not $a" >&2; exit 1 ;; esac`,
372
+ `f="${file}"`,
373
+ `t="$(mktemp -d)"`,
374
+ `curl -fsSLo "$t/$f" "${base}/$f"`,
375
+ `case "$a" in ${CI_TOOL_ARCHES.filter((a) => sums[a]).map((a) => `(${a}) want=${sums[a]} ;;`).join(" ")} (*) want= ;; esac`,
376
+ ];
377
+ const checksums = s.checksums?.(version, file);
378
+ if (checksums) {
379
+ lines.push(
380
+ `curl -fsSLo "$t/sums" ${options.checksumsUrl ?? `"${base}/${checksums}"`}`,
381
+ // The archive's line, with any ./ or * before the name taken off.
382
+ `line="$(sed -n "s#^\\([0-9a-f]\\{64\\}\\) *[*.]*/*$f\\$#\\1#p" "$t/sums")"`,
383
+ `{ [ -n "$line" ] || { echo "${name}: $f is not in ${checksums}" >&2; exit 1; }; }`,
384
+ `{ [ -z "$want" ] || [ "$line" = "$want" ] || { echo "${name}: ${checksums} lists $line for $f; chant records $want" >&2; exit 1; }; }`,
385
+ `want="$line"`,
386
+ );
387
+ } else {
388
+ lines.push(`{ [ -n "$want" ] || { echo "${name}: no sha256 is recorded for $f" >&2; exit 1; }; }`);
389
+ }
390
+ lines.push(`echo "$want $t/$f" | sha256sum -c - >/dev/null`, `mkdir -p "${dir}"`);
391
+ const member = s.member?.("$w") ?? s.bin;
392
+ switch (s.layout) {
393
+ case "binary":
394
+ lines.push(`install -m 0755 "$t/$f" "${dir}/${s.bin}"`);
395
+ break;
396
+ case "tar.gz":
397
+ lines.push(`tar -xzf "$t/$f" -C "$t" "${member}"`, `install -m 0755 "$t/${member}" "${dir}/${s.bin}"`);
398
+ break;
399
+ case "zip":
400
+ lines.push(`unzip -q -o "$t/$f" "${member}" -d "$t"`, `install -m 0755 "$t/${member}" "${dir}/${s.bin}"`);
401
+ break;
402
+ case "tree":
403
+ lines.push(`tar -xzf "$t/$f" -C "${dir}" --strip-components=1`);
404
+ break;
405
+ case "aws-cli":
406
+ lines.push(`unzip -q "$t/$f" -d "$t"`, `"$t/aws/install" -i "${dir}" -b "${dir}/bin"`);
407
+ break;
408
+ }
409
+ return lines.join(" && ");
410
+ }
411
+
412
+ export interface CiToolInstallOptions extends CiToolCheckOptions {
413
+ /** Where the versioned directories live. Default {@link CI_TOOL_ROOT}. */
414
+ root?: string;
415
+ /** Link the binary into /usr/local/bin (default true). `false` leaves PATH alone, for a pin a step runs by its path. */
416
+ link?: boolean;
417
+ /** Skip the install when any `<bin>` is on PATH, whatever its version. Default false: only the versioned directory counts. */
418
+ onPath?: boolean;
419
+ }
420
+
421
+ /** Where a job line installs each release by default. */
422
+ export const CI_TOOL_ROOT = "/opt/chant";
423
+
424
+ /**
425
+ * The job line that installs `tool` at `version` under
426
+ * `<root>/<tool>-<version>/`, checked as {@link ciToolFetchScript} checks
427
+ * it. It skips the download when that directory holds the binary, as in an
428
+ * image that carries the release, and links the binary into /usr/local/bin
429
+ * unless `link` is false.
430
+ */
431
+ export function ciToolInstallLine(tool: CiTool, version: string, options: CiToolInstallOptions = {}): string {
432
+ const root = options.root ?? CI_TOOL_ROOT;
433
+ const dir = ciToolDir(tool, version, root);
434
+ const bin = ciToolBin(tool, version, root);
435
+ const s = spec(tool);
436
+ const install = `(set -e; ${ciToolFetchScript(tool, version, { dir, sha256: options.sha256, requirePin: options.requirePin })})`;
437
+ const inDir = `[ -x "${bin}" ]`;
438
+ const line = options.link === false ? `${inDir} || ${install}` : `{ ${inDir} || ${install}; } && ln -sf "${bin}" /usr/local/bin/${s.bin}`;
439
+ return options.onPath ? `command -v ${s.bin} >/dev/null 2>&1 || { ${line}; }` : line;
440
+ }
441
+
442
+ // ---------------------------------------------------------------------------
443
+ // The run-time install, from Node
444
+
445
+ /** The expected digest for `file` in a checksums file's text, or undefined when it lists none. A name may carry `*` or `./` before it. */
446
+ export function checksumFor(sums: string, file: string): string | undefined {
447
+ for (const line of sums.split("\n")) {
448
+ const m = /^([0-9a-fA-F]{64})\s+\*?(?:\.\/)?(\S+)\s*$/.exec(line.trim());
449
+ if (m && m[2] === file) return m[1]!.toLowerCase();
450
+ }
451
+ return undefined;
452
+ }
453
+
454
+ /** One file out of a zip archive, by name. Stored and deflated entries only, which is what releases use. */
455
+ export function unzipEntry(zip: Uint8Array, name: string): Uint8Array | undefined {
456
+ const buf = Buffer.from(zip.buffer, zip.byteOffset, zip.byteLength);
457
+ let eocd = -1;
458
+ // The end-of-central-directory record is in the last 64 KiB plus 22 bytes.
459
+ for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
460
+ if (buf.readUInt32LE(i) === 0x06054b50) {
461
+ eocd = i;
462
+ break;
463
+ }
464
+ }
465
+ if (eocd < 0) throw new Error("not a zip archive");
466
+ const count = buf.readUInt16LE(eocd + 10);
467
+ let p = buf.readUInt32LE(eocd + 16);
468
+ for (let n = 0; n < count; n++) {
469
+ if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error("corrupt zip central directory");
470
+ const method = buf.readUInt16LE(p + 10);
471
+ const size = buf.readUInt32LE(p + 20);
472
+ const nameLen = buf.readUInt16LE(p + 28);
473
+ const extraLen = buf.readUInt16LE(p + 30);
474
+ const commentLen = buf.readUInt16LE(p + 32);
475
+ const local = buf.readUInt32LE(p + 42);
476
+ if (buf.toString("utf-8", p + 46, p + 46 + nameLen) === name) {
477
+ const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
478
+ const data = buf.subarray(start, start + size);
479
+ if (method === 0) return new Uint8Array(data);
480
+ if (method === 8) return new Uint8Array(inflateRawSync(data));
481
+ throw new Error(`zip entry ${name} uses compression method ${method}`);
482
+ }
483
+ p += 46 + nameLen + extraLen + commentLen;
484
+ }
485
+ return undefined;
486
+ }
487
+
488
+ export interface InstallCiToolOptions extends CiToolCheckOptions {
489
+ /** Fetches a release file. Default: Node's fetch. Tests pass their own. */
490
+ download?: (url: string) => Promise<Uint8Array>;
491
+ /** Where the versioned directories live. Default `CHANT_TOOL_CACHE`, else `chant-tools` in the temp directory. */
492
+ root?: string;
493
+ /** The architecture to fetch for. Default this process's. */
494
+ arch?: CiToolArch;
495
+ /** The platform this runs on. Default this process's; the releases are Linux builds, so any other is refused. */
496
+ platform?: string;
497
+ }
498
+
499
+ /** This process's architecture as chant fetches it. Throws on one chant has no builds for. */
500
+ export function ciToolArch(arch: string = process.arch): CiToolArch {
501
+ if (arch === "x64" || arch === "x86_64" || arch === "amd64") return "amd64";
502
+ if (arch === "arm64" || arch === "aarch64") return "arm64";
503
+ throw new Error(`chant fetches tools for ${CI_TOOL_ARCHES.join(" and ")}, not ${arch}`);
504
+ }
505
+
506
+ async function fetchBytes(url: string): Promise<Uint8Array> {
507
+ const res = await fetch(url);
508
+ if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
509
+ return new Uint8Array(await res.arrayBuffer());
510
+ }
511
+
512
+ /**
513
+ * Install `tool` at `version` under `<root>/<tool>-<version>/` and return
514
+ * the directory and the binary, checked by the same rule as the shell
515
+ * (#4784). A binary already there is returned without a download. A
516
+ * download that does not match is never written.
517
+ */
518
+ export async function installCiTool(tool: CiTool, version: string, options: InstallCiToolOptions = {}): Promise<{ dir: string; bin: string }> {
519
+ const platform = options.platform ?? process.platform;
520
+ if (platform !== "linux") throw new Error(`chant installs Linux builds of ${tool} for a CI job, and this machine is ${platform}; install it with your package manager`);
521
+ const arch = options.arch ?? ciToolArch();
522
+ const r = ciToolRelease(tool, version, arch);
523
+ if (r.layout === "aws-cli") throw new Error("the AWS CLI installs with its own installer; use ciToolInstallLine in a job or the image's fetch stage");
524
+ const root = options.root ?? (process.env.CHANT_TOOL_CACHE || join(tmpdir(), "chant-tools"));
525
+ const dir = join(root, `${tool}-${version}`);
526
+ const bin = join(dir, r.path);
527
+ if (existsSync(bin)) return { dir, bin };
528
+
529
+ const pinned = ciToolSha256(tool, version, options.sha256)[arch];
530
+ if (!pinned && (options.requirePin || !r.checksumsUrl)) {
531
+ throw new Error(`no recorded sha256 for ${tool} ${version} on ${arch} (${r.asset}): record it from the release's checksums in the product's config and pass sha256`);
532
+ }
533
+ const download = options.download ?? fetchBytes;
534
+ const [body, sums] = await Promise.all([download(r.url), r.checksumsUrl ? download(r.checksumsUrl) : Promise.resolve(undefined)]);
535
+ let want = pinned;
536
+ if (sums !== undefined) {
537
+ const line = checksumFor(Buffer.from(sums).toString("utf-8"), r.asset);
538
+ if (!line) throw new Error(`${tool} ${version}: ${r.asset} is not in ${r.checksums}`);
539
+ if (pinned && line !== pinned) throw new Error(`${tool} ${version}: ${r.checksums} lists ${line} for ${r.asset}; chant records ${pinned}`);
540
+ want = line;
541
+ }
542
+ const sum = createHash("sha256").update(body).digest("hex");
543
+ if (sum !== want) throw new Error(`${tool} ${version} from ${r.url} has sha256 ${sum}, not ${want}; not installing it`);
544
+
545
+ const nonce = randomBytes(6).toString("hex");
546
+ if (r.layout === "tree") {
547
+ // Unpacked beside the directory and renamed into place, so the binary is there only when the whole tree is.
548
+ if (existsSync(dir)) throw new Error(`${dir} is there without ${r.path}; remove it and run the install again`);
549
+ mkdirSync(root, { recursive: true });
550
+ const staging = join(root, `.${tool}-${version}.${nonce}`);
551
+ mkdirSync(staging);
552
+ const out = spawnSync("tar", ["-xz", "-C", staging, "--strip-components=1"], { input: body });
553
+ if (out.status !== 0) throw new Error(`${r.asset} did not unpack: ${out.stderr?.toString().trim() || out.error?.message}`);
554
+ if (!existsSync(join(staging, r.path))) throw new Error(`${r.asset} holds no ${r.path}`);
555
+ renameSync(staging, dir);
556
+ return { dir, bin };
557
+ }
558
+ mkdirSync(dir, { recursive: true });
559
+ // Written beside its final name and renamed, so a job that stops halfway leaves no binary behind.
560
+ const part = join(dir, `.${r.bin}.${nonce}`);
561
+ const binary = r.layout === "binary" ? body : r.layout === "zip" ? unzipEntry(body, r.member) : tarEntry(gunzipSync(body), r.member);
562
+ if (!binary) throw new Error(`${r.asset} holds no ${r.member}`);
563
+ writeFileSync(part, binary);
564
+ chmodSync(part, 0o755);
565
+ renameSync(part, bin);
566
+ return { dir, bin };
567
+ }
568
+
569
+ // ---------------------------------------------------------------------------
570
+ // The product image
571
+
572
+ /**
573
+ * Base images by index digest, so a rebuild cannot change underneath a tag:
574
+ * the ones all three products pinned. `node` carries Node 22.23.3.
575
+ */
576
+ export const CI_BASE_IMAGES = {
577
+ node: "node:22-bookworm-slim@sha256:c3de60bf2f9dd0ac6370e6117950ff62d6e339527e7472301c9c78a017978392",
578
+ debian: "debian:bookworm-slim@sha256:3783cc01769c7b2b1b83a5c5ad96c815348e28ed7da68e2e3687004faa906251",
579
+ } as const;
580
+
581
+ /** The build argument a release passes its label in (chant's release.version). */
582
+ export const CI_IMAGE_LABEL_ARG = "CHANT_RELEASE_LABEL";
583
+
584
+ /** One Dockerfile instruction, as the docker lexicon's stage `steps` take it: `{ run: "..." }`. */
585
+ export type CiImageStep = Readonly<Partial<Record<"arg" | "env" | "run" | "copy" | "label" | "cmd" | "user" | "workdir" | "expose" | "entrypoint", string>>>;
586
+
587
+ /** One stage, as the docker lexicon's `new Dockerfile({ stages })` takes it. */
588
+ export interface CiImageStage {
589
+ from: string;
590
+ as?: string;
591
+ steps: CiImageStep[];
592
+ }
593
+
594
+ /** One engine an image carries. */
595
+ export interface CiImageTool {
596
+ tool: CiTool;
597
+ version: string;
598
+ /** Recorded sums by architecture, from the product's config, for a release chant records none for. */
599
+ sha256?: Partial<Record<CiToolArch, string>>;
600
+ /** A build argument naming the checksums file, defaulting to the release's own, so a tampered one can be shown to fail the build. */
601
+ checksumsArg?: string;
602
+ /** Link the binary into /usr/local/bin. Default true. */
603
+ link?: boolean;
604
+ }
605
+
606
+ /** How the product's own code goes into the image. */
607
+ export type CiImageBundle =
608
+ /** A one-file bundle in the build context, copied in as `/usr/local/bin/<bin>`. */
609
+ | { file: string; bin: string }
610
+ /** A tarball from `npm pack` in the build context, installed globally. `check` runs after, such as `plywood --version`. */
611
+ | { tarball: string; check?: string }
612
+ /**
613
+ * Packages npm installs into `prefix`, whose `node_modules` is linked at
614
+ * /node_modules so a checkout anywhere in the container resolves them, and
615
+ * whose `.bin` goes on PATH. `packages` is shell words, such as
616
+ * `"${PKG:-@scope/name@$VERSION}" $PINS`. npm lists a release before it
617
+ * serves its tarballs, so an E404 or ETARGET is tried again, three times,
618
+ * 45s apart. With `mountContext` the build context is at /ctx, so a packed
619
+ * tarball installs as /ctx/<file>.tgz. `require` names build arguments
620
+ * that must be set; `check` runs after.
621
+ */
622
+ | { npm: string; prefix: string; mountContext?: boolean; require?: string[]; check?: string[] };
623
+
624
+ export interface ProductImageSpec {
625
+ /** The image's title, such as `terragucci-tofu`. */
626
+ name: string;
627
+ /** The product, the job's `USER` and the default tool root `/opt/<product>`. */
628
+ product: string;
629
+ description: string;
630
+ /** The repository URL for `org.opencontainers.image.source`. */
631
+ source: string;
632
+ /** Default Apache-2.0. */
633
+ licenses?: string;
634
+ /** The engines, fetched and checked in a stage of their own, so curl never reaches the image. Each needs a recorded sha256 for both architectures. */
635
+ tools?: CiImageTool[];
636
+ /** Where the engines live. Default `/opt/<product>`. */
637
+ toolRoot?: string;
638
+ /** apt packages beside git and ca-certificates, such as openssh-client. */
639
+ packages?: string[];
640
+ /** Environment beside chant's (`USER`, `HOME=/tmp`, no Node compile cache, no npm debug logs). */
641
+ env?: string[];
642
+ /** npm packages installed into /usr/local, on the bundle's module path, at exact versions: `@cdktn/hcl2json@0.24.0`. */
643
+ npm?: string[];
644
+ /** The chant release whose one-file wave runtime is the image's `chant`, for a product whose bundle runs `chant` off PATH. */
645
+ chant?: string;
646
+ bundle: CiImageBundle;
647
+ /** The product's own steps, after the engines and before the bundle, such as plugin installs. */
648
+ steps?: CiImageStep[];
649
+ /** The build argument the version label reads. Default {@link CI_IMAGE_LABEL_ARG}. */
650
+ versionArg?: string;
651
+ /** More build arguments the final stage takes. */
652
+ args?: string[];
653
+ /** Default `["bash"]`. */
654
+ cmd?: string;
655
+ }
656
+
657
+ const NAME = /^[a-z0-9][a-z0-9._-]*$/;
658
+ const PKG = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
659
+ const ARG = /^[A-Za-z_][A-Za-z0-9_]*$/;
660
+
661
+ function label(field: string, value: string): string {
662
+ if (/["\n\\]/.test(value)) throw new Error(`the image's ${field} cannot hold a double quote, a backslash or a newline`);
663
+ return value;
664
+ }
665
+
666
+ /** apt's and dpkg's logs and ldconfig's cache carry the time of the build, so they go with the lists (#4657). */
667
+ function aptLine(packages: string[]): string {
668
+ return `apt-get update && apt-get install -y --no-install-recommends ${packages.join(" ")} && rm -rf /var/lib/apt/lists/* /var/log/apt/* /var/log/dpkg.log /var/cache/ldconfig/aux-cache`;
669
+ }
670
+
671
+ /** The fetch stage's steps for `tools`, each into its directory under `root`. */
672
+ function fetchStage(tools: CiImageTool[], root: string): CiImageStage {
673
+ const steps: CiImageStep[] = [{ arg: "TARGETARCH" }];
674
+ for (const t of tools) {
675
+ if (t.checksumsArg === undefined) continue;
676
+ if (!ARG.test(t.checksumsArg)) throw new Error(`${t.tool}: checksumsArg ${JSON.stringify(t.checksumsArg)} is not a build argument name`);
677
+ const any = ciToolRelease(t.tool, t.version, "amd64");
678
+ if (!any.checksumsUrl) throw new Error(`${t.tool}: its release publishes no checksums file, so checksumsArg has nothing to name`);
679
+ steps.push({ arg: `${t.checksumsArg}=${any.checksumsUrl}` });
680
+ }
681
+ steps.push({ run: "apt-get update && apt-get install -y --no-install-recommends ca-certificates curl unzip && rm -rf /var/lib/apt/lists/*" });
682
+ for (const t of tools) {
683
+ const script = ciToolFetchScript(t.tool, t.version, {
684
+ dir: ciToolDir(t.tool, t.version, root),
685
+ arch: CI_TOOL_DOCKER_ARCH,
686
+ sha256: t.sha256,
687
+ requirePin: true,
688
+ ...(t.checksumsArg ? { checksumsUrl: `"$${t.checksumsArg}"` } : {}),
689
+ });
690
+ steps.push({ run: `set -e; ${script}` });
691
+ }
692
+ return { from: CI_BASE_IMAGES.debian, as: "fetch", steps };
693
+ }
694
+
695
+ function bundleSteps(b: CiImageBundle): CiImageStep[] {
696
+ if ("file" in b) {
697
+ if (!NAME.test(b.bin)) throw new Error(`bundle.bin ${JSON.stringify(b.bin)} is not a command name`);
698
+ return [{ copy: `--chmod=0755 ${b.file} /usr/local/bin/${b.bin}` }];
699
+ }
700
+ if ("tarball" in b) {
701
+ const base = b.tarball.split("/").pop()!;
702
+ return [
703
+ { copy: `${b.tarball} /tmp/${base}` },
704
+ { run: [`npm install -g --omit=dev --no-audit --no-fund /tmp/${base}`, `rm -f /tmp/${base}`, "npm cache clean --force", ...(b.check ? [b.check] : [])].join(" && ") },
705
+ ];
706
+ }
707
+ if (!DIR.test(b.prefix)) throw new Error(`bundle.prefix ${JSON.stringify(b.prefix)} is not an absolute path`);
708
+ for (const a of b.require ?? []) if (!ARG.test(a)) throw new Error(`bundle.require ${JSON.stringify(a)} is not a build argument name`);
709
+ const install = [
710
+ ...(b.require ?? []).map((a) => `test -n "$${a}"`),
711
+ `mkdir -p ${b.prefix}`,
712
+ `cd ${b.prefix}`,
713
+ `echo '{"name":"ci-image","private":true}' > package.json`,
714
+ `{ ok=; for try in 1 2 3; do if npm install --omit=dev --no-audit --no-fund ${b.npm} 2>/tmp/npm.err; then ok=1; break; fi; cat /tmp/npm.err >&2; grep -qE "E404|ETARGET" /tmp/npm.err || break; [ "$try" = 3 ] || sleep 45; done; test -n "$ok"; }`,
715
+ "npm cache clean --force",
716
+ `ln -s ${b.prefix}/node_modules /node_modules`,
717
+ ...(b.check ?? []),
718
+ ].join(" && ");
719
+ return [{ run: b.mountContext ? `--mount=type=bind,target=/ctx ${install}` : install }];
720
+ }
721
+
722
+ /**
723
+ * A product's CI image as stages (#4784): a fetch stage that downloads each
724
+ * engine and checks it against a recorded sha256, then the pinned Node base
725
+ * with git and CA certificates, `safe.directory '*'`, the engines, the
726
+ * product's steps, its bundle and the OCI labels. Pass the stages to the
727
+ * docker lexicon's `new Dockerfile({ stages })`, or write
728
+ * {@link productImageDockerfile}'s text.
729
+ */
730
+ export function productImageStages(spec: ProductImageSpec): CiImageStage[] {
731
+ if (!NAME.test(spec.name)) throw new Error(`image name ${JSON.stringify(spec.name)} is not lower-case letters, digits and ._-`);
732
+ if (!NAME.test(spec.product)) throw new Error(`product ${JSON.stringify(spec.product)} is not lower-case letters, digits and ._-`);
733
+ const versionArg = spec.versionArg ?? CI_IMAGE_LABEL_ARG;
734
+ for (const a of [versionArg, ...(spec.args ?? [])]) if (!ARG.test(a)) throw new Error(`build argument ${JSON.stringify(a)} is not a name`);
735
+ for (const p of spec.packages ?? []) if (!/^[a-z0-9][a-z0-9.+-]*$/.test(p)) throw new Error(`apt package ${JSON.stringify(p)} is not a package name`);
736
+ for (const p of spec.npm ?? []) if (!PKG.test(p)) throw new Error(`npm package ${JSON.stringify(p)} is not a name at an exact version`);
737
+ if (spec.chant !== undefined && !VERSION.test(spec.chant)) throw new Error(`chant ${JSON.stringify(spec.chant)} is not a release version`);
738
+ const root = spec.toolRoot ?? `/opt/${spec.product}`;
739
+ const tools = spec.tools ?? [];
740
+ const seen = new Set<string>();
741
+ for (const t of tools) {
742
+ if (seen.has(t.tool)) throw new Error(`${spec.name}: ${t.tool} is listed twice`);
743
+ seen.add(t.tool);
744
+ }
745
+
746
+ const steps: CiImageStep[] = [];
747
+ for (const a of [versionArg, ...(spec.args ?? [])]) steps.push({ arg: a });
748
+ // A forge may run the job as a uid with no /etc/passwd entry, and Go then reads $USER and $HOME. A release builds each
749
+ // image twice and the two archives must match (#4657), so Node's compile cache and npm's debug logs are not written.
750
+ const env = [`USER=${spec.product}`, "HOME=/tmp", "NODE_DISABLE_COMPILE_CACHE=1", "npm_config_logs_max=0", ...(spec.env ?? [])];
751
+ if ("npm" in spec.bundle) env.push(`PATH=${spec.bundle.prefix}/node_modules/.bin:$PATH`);
752
+ for (const e of env) steps.push({ env: e });
753
+ steps.push({ run: aptLine(["git", "ca-certificates", ...(spec.packages ?? [])]) });
754
+ // A job often runs as another user than the one who owns its checkout, and git then refuses it ("dubious
755
+ // ownership"). Debian's git 2.39 matches no path prefix, so it is every directory (#4768).
756
+ steps.push({ run: "git config --system --add safe.directory '*'" });
757
+ if (spec.npm?.length) {
758
+ steps.push({ run: `npm install --prefix /usr/local --no-save --omit=dev --no-audit --no-fund ${spec.npm.join(" ")} && npm cache clean --force && rm -rf /tmp/.npm` });
759
+ }
760
+ if (spec.chant) {
761
+ // chant's one-file wave runtime from the release (npm checks the tarball's integrity), with a `chant` on PATH that runs it.
762
+ steps.push({
763
+ run: [
764
+ `cd /tmp && npm pack --silent @intentius/chant@${spec.chant}`,
765
+ `tar -xzf intentius-chant-${spec.chant}.tgz package/dist/wave-runtime.mjs`,
766
+ "install -D -m 0644 package/dist/wave-runtime.mjs /opt/chant/wave-runtime.mjs",
767
+ `printf '#!/bin/sh\\nexec node /opt/chant/wave-runtime.mjs "$@"\\n' > /usr/local/bin/chant && chmod 0755 /usr/local/bin/chant`,
768
+ "rm -rf /tmp/package /tmp/intentius-chant-*.tgz && npm cache clean --force && rm -rf /tmp/.npm",
769
+ ].join(" && "),
770
+ });
771
+ }
772
+ if (tools.length) {
773
+ steps.push({ copy: `--from=fetch ${root}/ ${root}/` });
774
+ const links = tools.filter((t) => t.link !== false).map((t) => `ln -sf ${ciToolBin(t.tool, t.version, root)} /usr/local/bin/${TOOLS[t.tool].bin}`);
775
+ if (links.length) steps.push({ run: links.join(" && ") });
776
+ }
777
+ steps.push(...(spec.steps ?? []));
778
+ steps.push(...bundleSteps(spec.bundle));
779
+ steps.push(
780
+ { label: `org.opencontainers.image.title="${spec.name}"` },
781
+ { label: `org.opencontainers.image.description="${label("description", spec.description)}"` },
782
+ { label: `org.opencontainers.image.version="\${${versionArg}}"` },
783
+ { label: `org.opencontainers.image.source="${label("source", spec.source)}"` },
784
+ { label: `org.opencontainers.image.licenses="${label("licenses", spec.licenses ?? "Apache-2.0")}"` },
785
+ { cmd: spec.cmd ?? '["bash"]' },
786
+ );
787
+ return [...(tools.length ? [fetchStage(tools, root)] : []), { from: CI_BASE_IMAGES.node, steps }];
788
+ }
789
+
790
+ /** Stages as Dockerfile text, as the docker lexicon writes them, with `header` as comment lines on top. */
791
+ export function dockerfileText(stages: readonly CiImageStage[], header: readonly string[] = []): string {
792
+ const lines = header.map((h) => (h ? `# ${h}` : "#"));
793
+ for (const s of stages) {
794
+ lines.push(`FROM ${s.from}${s.as ? ` AS ${s.as}` : ""}`);
795
+ for (const step of s.steps) {
796
+ const keys = Object.keys(step).filter((k) => step[k as keyof CiImageStep] !== undefined);
797
+ if (keys.length !== 1) throw new Error(`a step names exactly one instruction, found ${keys.join(", ") || "none"}`);
798
+ lines.push(`${keys[0]!.toUpperCase()} ${step[keys[0] as keyof CiImageStep]}`);
799
+ }
800
+ }
801
+ return lines.join("\n") + "\n";
802
+ }
803
+
804
+ /** A product's CI image as Dockerfile text, with `header` as comment lines on top. */
805
+ export function productImageDockerfile(spec: ProductImageSpec, header: readonly string[] = []): string {
806
+ return dockerfileText(productImageStages(spec), header);
807
+ }
808
+
809
+ /** An image a user builds FROM the product's in their own CI. */
810
+ export interface DerivedImageSpec {
811
+ /** The product's image, by digest when it is known. */
812
+ from: string;
813
+ /** Comment lines on top: what it is, how to build it, where to name it. */
814
+ header?: readonly string[];
815
+ steps: CiImageStep[];
816
+ }
817
+
818
+ /** A derived image's Dockerfile (#4784): FROM the product's image, the user's steps, nothing pushed. */
819
+ export function derivedImageDockerfile(spec: DerivedImageSpec): string {
820
+ if (!spec.from || /\s/.test(spec.from)) throw new Error(`the derived image's from ${JSON.stringify(spec.from)} is not an image reference`);
821
+ return dockerfileText([{ from: spec.from, steps: spec.steps }], spec.header ?? []);
822
+ }