@intentius/chant-lexicon-terraform 0.124.87 → 0.124.89

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 (82) hide show
  1. package/dist/action-ops.d.ts.map +1 -1
  2. package/dist/action-ops.js +3 -1
  3. package/dist/chant-floors.d.ts +30 -0
  4. package/dist/chant-floors.d.ts.map +1 -0
  5. package/dist/chant-floors.js +29 -0
  6. package/dist/components/capability-plugin.d.ts +15 -1
  7. package/dist/components/capability-plugin.d.ts.map +1 -1
  8. package/dist/components/capability-plugin.js +13 -5
  9. package/dist/components/compose-group.d.ts +5 -1
  10. package/dist/components/compose-group.d.ts.map +1 -1
  11. package/dist/components/compose-group.js +7 -4
  12. package/dist/engine-runner.d.ts +86 -0
  13. package/dist/engine-runner.d.ts.map +1 -0
  14. package/dist/engine-runner.js +134 -0
  15. package/dist/engine-timings.d.ts +249 -0
  16. package/dist/engine-timings.d.ts.map +1 -0
  17. package/dist/engine-timings.js +569 -0
  18. package/dist/integrity.json +2 -2
  19. package/dist/live-roots.d.ts +143 -0
  20. package/dist/live-roots.d.ts.map +1 -0
  21. package/dist/live-roots.js +304 -0
  22. package/dist/manifest.json +1 -1
  23. package/dist/migration-history.d.ts +105 -0
  24. package/dist/migration-history.d.ts.map +1 -0
  25. package/dist/migration-history.js +159 -0
  26. package/dist/module-catalog/index.d.ts +1 -0
  27. package/dist/module-catalog/index.d.ts.map +1 -1
  28. package/dist/module-catalog/index.js +3 -1
  29. package/dist/op/activities/live-detect.d.ts +15 -0
  30. package/dist/op/activities/live-detect.d.ts.map +1 -1
  31. package/dist/op/activities/live-detect.js +94 -0
  32. package/dist/op/activities/terraform.d.ts +1 -65
  33. package/dist/op/activities/terraform.d.ts.map +1 -1
  34. package/dist/op/activities/terraform.js +4 -54
  35. package/dist/op/command-hook.d.ts +98 -0
  36. package/dist/op/command-hook.d.ts.map +1 -0
  37. package/dist/op/command-hook.js +115 -0
  38. package/dist/registry/index.d.ts +1 -0
  39. package/dist/registry/index.d.ts.map +1 -1
  40. package/dist/registry/index.js +1 -0
  41. package/dist/state/exec.d.ts +23 -0
  42. package/dist/state/exec.d.ts.map +1 -1
  43. package/dist/state/exec.js +38 -0
  44. package/dist/state-ops.d.ts.map +1 -1
  45. package/dist/state-ops.js +3 -1
  46. package/dist/terragrunt/index.d.ts +3 -1
  47. package/dist/terragrunt/index.d.ts.map +1 -1
  48. package/dist/terragrunt/index.js +3 -1
  49. package/dist/terragrunt/place.d.ts +27 -0
  50. package/dist/terragrunt/place.d.ts.map +1 -0
  51. package/dist/terragrunt/place.js +52 -0
  52. package/dist/terragrunt/run.d.ts +23 -0
  53. package/dist/terragrunt/run.d.ts.map +1 -1
  54. package/dist/terragrunt/run.js +107 -3
  55. package/package.json +2 -2
  56. package/src/action-ops.ts +3 -1
  57. package/src/chant-floors.ts +32 -0
  58. package/src/components/capability-plugin.ts +27 -6
  59. package/src/components/compose-group.test.ts +29 -0
  60. package/src/components/compose-group.ts +12 -5
  61. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  62. package/src/engine-runner.test.ts +261 -0
  63. package/src/engine-runner.ts +191 -0
  64. package/src/engine-timings.test.ts +203 -0
  65. package/src/engine-timings.ts +718 -0
  66. package/src/live-record-store.test.ts +76 -0
  67. package/src/live-roots.test.ts +80 -0
  68. package/src/live-roots.ts +347 -0
  69. package/src/migration-history.test.ts +83 -0
  70. package/src/migration-history.ts +199 -0
  71. package/src/module-catalog/index.ts +4 -1
  72. package/src/op/activities/live-detect.ts +87 -0
  73. package/src/op/activities/terraform.ts +12 -111
  74. package/src/op/command-hook.ts +189 -0
  75. package/src/registry/index.ts +1 -0
  76. package/src/state/engine-env.test.ts +18 -0
  77. package/src/state/exec.ts +38 -0
  78. package/src/state-ops.ts +3 -1
  79. package/src/terragrunt/index.ts +3 -1
  80. package/src/terragrunt/place.test.ts +42 -0
  81. package/src/terragrunt/place.ts +75 -0
  82. package/src/terragrunt/run.ts +128 -4
@@ -0,0 +1,199 @@
1
+ /**
2
+ * A state migration's history, read back from the lines chant wrote
3
+ * (chant#4910): each `finished` line of the migration's gated requests
4
+ * (`_gates/<op>/applied.jsonl` on `chant/lifecycle`, written by core's
5
+ * `runStateMigration` with `migrationFacts`), as one history line per run,
6
+ * and the revert of a migration that applied, each root back to the version
7
+ * the migration recorded before it wrote.
8
+ *
9
+ * The history line is the form terragucci's `done.jsonl` has always held,
10
+ * so a product that kept such a file before chant ran its gate reads the two
11
+ * together ({@link migrationHistory}). Besides core's facts, a finished
12
+ * line's detail may carry the product's `file_digest`, its change
13
+ * (`migration_change`, else `change`) and the migration a revert put back
14
+ * (`revert`); they are read when there.
15
+ *
16
+ * Lifted from terragucci's `finishedMigrationLines`, `migrationHistory` and
17
+ * `revertMigration` (migrate.ts), so terragucci deletes its copies and keeps
18
+ * its file's words.
19
+ */
20
+ import { MigrationError, type Restore } from "./state-migration";
21
+
22
+ /** One root of a history line: where its state is, and its version and digest before and after. */
23
+ export interface MigrationHistoryRoot {
24
+ root: string;
25
+ location: string | null;
26
+ before: string | null;
27
+ after: string | null;
28
+ before_digest: string | null;
29
+ after_digest: string | null;
30
+ /** A backend move's source, and the version read there. */
31
+ source?: string | null;
32
+ source_version?: string | null;
33
+ }
34
+
35
+ /** One run of a migration, as its history holds it. */
36
+ export interface MigrationHistoryLine {
37
+ version: 1;
38
+ kind: "migration";
39
+ op: string;
40
+ /** The migration's name. */
41
+ gate: string;
42
+ timestamp: string;
43
+ planDigest?: string;
44
+ file_digest?: string;
45
+ /** `applied` or `failed`. A run refused under the locks wrote nothing and has no line. */
46
+ result: string;
47
+ approvedBy?: string;
48
+ /** The migration's change: `moves`, `backends`, `revert`, `retag`, `adopt`, as the product's detail names it. */
49
+ change: string | null;
50
+ /** The migration a revert put back. */
51
+ revert?: string;
52
+ roots: MigrationHistoryRoot[];
53
+ error?: string;
54
+ /** `finished`: read from a gated request's finished line. */
55
+ source?: string;
56
+ }
57
+
58
+ /**
59
+ * The finished lines of a migration op's `applied.jsonl` as history lines,
60
+ * oldest first. A line without a `result` is skipped (the migration threw
61
+ * before it ended), and so is a run refused under the lock, which wrote
62
+ * nothing.
63
+ */
64
+ export function finishedMigrationLines(appliedText: string, op: string): MigrationHistoryLine[] {
65
+ const out: MigrationHistoryLine[] = [];
66
+ for (const l of appliedText.split("\n").map((x) => x.trim()).filter(Boolean)) {
67
+ let r: Record<string, unknown>;
68
+ try {
69
+ r = JSON.parse(l) as Record<string, unknown>;
70
+ } catch {
71
+ continue;
72
+ }
73
+ if (r.version !== 1 || r.kind !== "finished" || typeof r.gate !== "string" || typeof r.timestamp !== "string") continue;
74
+ const d = r.detail && typeof r.detail === "object" ? (r.detail as Record<string, unknown>) : {};
75
+ if (typeof d.result !== "string" || d.result === "refused") continue;
76
+ const str = (k: string): string | null => (typeof d[k] === "string" ? (d[k] as string) : null);
77
+ const roots = (str("roots") ?? "")
78
+ .split(",")
79
+ .filter(Boolean)
80
+ .map((root): MigrationHistoryRoot => ({
81
+ root,
82
+ location: str(`${root}.location`),
83
+ before: str(`${root}.before`),
84
+ after: str(`${root}.after`),
85
+ before_digest: str(`${root}.before_digest`),
86
+ after_digest: str(`${root}.after_digest`),
87
+ ...(str(`${root}.source`) ? { source: str(`${root}.source`), source_version: str(`${root}.source_version`) } : {}),
88
+ }));
89
+ out.push({
90
+ version: 1,
91
+ kind: "migration",
92
+ op,
93
+ gate: r.gate,
94
+ timestamp: r.timestamp,
95
+ ...(typeof r.planDigest === "string" ? { planDigest: r.planDigest } : {}),
96
+ ...(str("file_digest") ? { file_digest: str("file_digest")! } : {}),
97
+ result: d.result,
98
+ ...(str("approved_by") ? { approvedBy: str("approved_by")! } : {}),
99
+ change: str("migration_change") ?? str("change"),
100
+ ...(str("revert") ? { revert: str("revert")! } : {}),
101
+ roots,
102
+ ...(str("error") ? { error: str("error")! } : {}),
103
+ source: "finished",
104
+ });
105
+ }
106
+ return out;
107
+ }
108
+
109
+ /** Where a migration op's history is kept on `chant/lifecycle`: chant's `applied.jsonl`, and the product's own earlier file, if it kept one. */
110
+ export interface MigrationHistoryFiles {
111
+ op: string;
112
+ /** The product's file of history lines written before chant ran the gate, such as `_gates/tf-migrate/done.jsonl`. */
113
+ earlier?: string;
114
+ }
115
+
116
+ /**
117
+ * A migration op's history as history-line text, one JSON line each: the
118
+ * product's earlier lines first, then each finished line of chant's gated
119
+ * requests. The newest line of a migration wins. `show` reads a path on
120
+ * `chant/lifecycle` as the caller wants it read (the remote ref as last
121
+ * fetched, say), answering "" for a path that is not there.
122
+ */
123
+ export function migrationHistory(show: (path: string) => string, files: MigrationHistoryFiles): string {
124
+ const earlier = files.earlier ? show(files.earlier).split("\n").map((l) => l.trim()).filter(Boolean) : [];
125
+ const finished = finishedMigrationLines(show(`_gates/${files.op}/applied.jsonl`), files.op).map((l) => JSON.stringify(l));
126
+ return [...earlier, ...finished].join("\n") + "\n";
127
+ }
128
+
129
+ /** The newest line of each migration that ran its writes, by name. */
130
+ export function doneMigrations(history: string): Map<string, { status: string; file_digest?: string; timestamp: string }> {
131
+ const out = new Map<string, { status: string; file_digest?: string; timestamp: string }>();
132
+ for (const line of history.split("\n").map((l) => l.trim()).filter(Boolean)) {
133
+ try {
134
+ const r = JSON.parse(line) as Record<string, unknown>;
135
+ if (r.kind !== "migration" || typeof r.gate !== "string" || typeof r.timestamp !== "string") continue;
136
+ out.set(r.gate, { status: String(r.result), ...(typeof r.file_digest === "string" ? { file_digest: r.file_digest } : {}), timestamp: r.timestamp });
137
+ } catch {
138
+ continue;
139
+ }
140
+ }
141
+ return out;
142
+ }
143
+
144
+ /** The name a revert of `name` takes. */
145
+ export const revertName = (name: string): string => `${name}-revert`;
146
+
147
+ /** A revert of a migration that applied: its name, each root's restore, and the migration file that asks for it. */
148
+ export interface MigrationRevert {
149
+ name: string;
150
+ restores: Restore[];
151
+ /** The file, `revert:` and `restores:`, under the caller's comment lines. */
152
+ text: string;
153
+ }
154
+
155
+ /**
156
+ * The revert of a migration that applied, from its newest applied line in
157
+ * `history`: each root back to the version the migration recorded before it
158
+ * wrote, from the version it recorded after (the write is refused when a
159
+ * state moved past it). A backend move, a revert, an estate retag or an
160
+ * estate adoption is not put back this way, and a root whose bucket kept no
161
+ * version cannot be put back: each throws {@link MigrationError} naming why.
162
+ * `where` names the history in the refusal; `header` are the file's comment
163
+ * lines, without their `# `.
164
+ */
165
+ export function revertMigration(name: string, history: string, options: { where?: string; header?: readonly string[] } = {}): MigrationRevert {
166
+ let line: Record<string, unknown> | undefined;
167
+ for (const l of history.split("\n").map((x) => x.trim()).filter(Boolean)) {
168
+ try {
169
+ const r = JSON.parse(l) as Record<string, unknown>;
170
+ if (r.kind === "migration" && r.gate === name && r.result === "applied") line = r;
171
+ } catch {
172
+ continue;
173
+ }
174
+ }
175
+ if (!line) throw new MigrationError(`chant/lifecycle records no applied migration ${name}${options.where ? `, ${options.where}` : ""}`);
176
+ if (line.change === "backends") throw new MigrationError(`${name} moved states to new backends; put it back with a backend move the other way, which reads each state where it is now`);
177
+ if (line.change === "revert") throw new MigrationError(`${name} is a revert; apply the migration it put back again with a new migration file`);
178
+ if (line.change === "retag") throw new MigrationError(`${name} retagged resources between estates; put it back with a moves migration the other way`);
179
+ if (line.change === "adopt") throw new MigrationError(`${name} adopted a state into an estate and left the state where it was; to go back, put the backend block back in place of the live block`);
180
+ const roots = Array.isArray(line.roots) ? (line.roots as Record<string, unknown>[]) : [];
181
+ const problems: string[] = [];
182
+ const restores: Restore[] = roots.map((r) => {
183
+ const root = String(r.root);
184
+ if (typeof r.location !== "string" || !/^(s3|gs|az):\/\//.test(r.location)) problems.push(`${root}: its backend keeps no versions, so there is no earlier state to put back`);
185
+ if (r.before === null && r.before_digest !== null) problems.push(`${root}: its bucket kept no version before ${name} wrote, so there is no earlier state to put back`);
186
+ if (typeof r.after !== "string") problems.push(`${root}: ${name} recorded no version after its write, so a later change could not be told apart`);
187
+ return { root, location: String(r.location), version_id: typeof r.before === "string" ? r.before : null, from_version_id: typeof r.after === "string" ? r.after : null };
188
+ });
189
+ if (problems.length > 0) throw new MigrationError(`${name} cannot be put back:\n ${problems.join("\n ")}`);
190
+ const q = (v: string | null): string => (v === null ? "null" : JSON.stringify(v));
191
+ const text = [
192
+ ...(options.header ?? [`Puts back the states migration ${name} wrote, to the versions it recorded before it wrote them.`]).map((h) => `# ${h}`),
193
+ `revert: ${name}`,
194
+ "restores:",
195
+ ...restores.flatMap((r) => [` - root: ${r.root}`, ` location: ${r.location}`, ` version_id: ${q(r.version_id)}`, ` from_version_id: ${q(r.from_version_id)}`]),
196
+ "",
197
+ ].join("\n");
198
+ return { name: revertName(name), restores, text };
199
+ }
@@ -14,11 +14,14 @@
14
14
  * it counts static rows only.
15
15
  *
16
16
  * This subpath, `@intentius/chant-lexicon-terraform/module-catalog`, imports
17
- * nothing but its own data, so a consumer can load it on its own.
17
+ * nothing but its own data and the lexicon's floors file (#4916), so a
18
+ * consumer can load it on its own.
18
19
  */
19
20
  import { SOURCE_COMMIT, SOURCE_PATH, STATIC_MEASUREMENT, STATIC_ROWS } from "./static-tier";
20
21
  import type { StaticRow } from "./types";
21
22
 
23
+ export { MODULE_CATALOG_FLOOR } from "../chant-floors";
24
+
22
25
  export type { StaticRefusal, StaticRow, StaticMeasurement, StaticSource } from "./types";
23
26
 
24
27
  /** Where the vendored rows came from. */
@@ -189,3 +189,90 @@ export function detectLivePolicyVerbs(dir: string, binary = "choudoufu"): LivePo
189
189
 
190
190
  return undefined;
191
191
  }
192
+
193
+ /**
194
+ * Whether the root module directory `dir` keeps its resources under
195
+ * choudoufu's live markers (chant#4910): an `estate.chdf.hcl` sidecar, or a
196
+ * `live` block in a `terraform` block, whether or not it names an estate.
197
+ */
198
+ export function declaresLive(dir: string, binary = "choudoufu"): boolean {
199
+ if (existsSync(join(dir, LIVE_SIDECAR_FILENAME))) return true;
200
+ let names: string[];
201
+ try {
202
+ names = liveFiles(dir, binary);
203
+ } catch {
204
+ return false;
205
+ }
206
+ return names.some((name) => {
207
+ try {
208
+ return liveBlocksOf(name, stripLineComments(name, readFileSync(join(dir, name), "utf-8"))).length > 0;
209
+ } catch {
210
+ return false;
211
+ }
212
+ });
213
+ }
214
+
215
+ /**
216
+ * Each `data "terraform_estate_outputs"` block of the root module directory
217
+ * `dir` (chant#4910): its label and the estate whose recorded outputs it
218
+ * reads. A block that names no estate as a literal is left out.
219
+ */
220
+ export function estateOutputReads(dir: string, binary = "choudoufu"): Array<{ name: string; estate: string }> {
221
+ let names: string[];
222
+ try {
223
+ names = liveFiles(dir, binary);
224
+ } catch {
225
+ return [];
226
+ }
227
+ const out: Array<{ name: string; estate: string }> = [];
228
+ for (const name of names) {
229
+ let source: string;
230
+ try {
231
+ source = readFileSync(join(dir, name), "utf-8");
232
+ } catch {
233
+ continue;
234
+ }
235
+ if (isJsonConfigFile(name)) {
236
+ let doc: unknown;
237
+ try {
238
+ doc = JSON.parse(source);
239
+ } catch {
240
+ continue;
241
+ }
242
+ const data = [(doc as { data?: unknown } | null)?.data].flat();
243
+ for (const d of data) {
244
+ const reads = d && typeof d === "object" ? (d as Record<string, unknown>).terraform_estate_outputs : undefined;
245
+ for (const r of [reads].flat()) {
246
+ if (!r || typeof r !== "object") continue;
247
+ for (const [label, body] of Object.entries(r as Record<string, unknown>)) {
248
+ const estate = [body].flat().map((b) => nonEmpty((b as { estate?: unknown } | null)?.estate)).find((e) => e !== undefined);
249
+ if (estate) out.push({ name: label, estate });
250
+ }
251
+ }
252
+ }
253
+ continue;
254
+ }
255
+ const text = stripLineComments(name, source);
256
+ for (const m of text.matchAll(/\bdata\s+"terraform_estate_outputs"\s+"([^"]+)"\s*\{/g)) {
257
+ const body = bodyAt(text, m.index! + m[0].length - 1);
258
+ const estate = body === undefined ? undefined : extractEstateAttr(body);
259
+ if (estate) out.push({ name: m[1]!, estate });
260
+ }
261
+ }
262
+ return out;
263
+ }
264
+
265
+ /** An HCL file's text with its `#` and `//` line comments blanked; a JSON file's as it is. */
266
+ function stripLineComments(name: string, source: string): string {
267
+ return isJsonConfigFile(name) ? source : source.replace(/^\s*(#|\/\/).*$/gm, "");
268
+ }
269
+
270
+ /** The inner text of the `{ ... }` block whose opening brace is at `open`, or undefined when it never closes. */
271
+ function bodyAt(source: string, open: number): string | undefined {
272
+ let depth = 0;
273
+ for (let i = open; i < source.length; i++) {
274
+ if (source[i] === "{") depth++;
275
+ else if (source[i] === "}" && --depth === 0) return source.slice(open + 1, i);
276
+ }
277
+ return undefined;
278
+ }
@@ -39,7 +39,6 @@
39
39
  * {@link MIN_CHOUDOUFU_VERSION}.
40
40
  */
41
41
 
42
- import { AsyncLocalStorage } from "node:async_hooks";
43
42
  import { exec } from "node:child_process";
44
43
  import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
45
44
  import { tmpdir } from "node:os";
@@ -53,6 +52,7 @@ import { choudoufuSetPlanParts, plannerForBinary, terraformChangeSetPart } from
53
52
  import type { ChangeSetPart } from "@intentius/chant/change-set";
54
53
  import type { TerraformConfig, TerraformRootConfig } from "../../config";
55
54
  import { detectLiveEstate } from "./live-detect";
55
+ import { commandWords, currentCommandScope, scopedCommand, type TerraformCommand } from "../command-hook";
56
56
  import { backendConfigValues } from "../../backend-config";
57
57
  import { lockTimeoutArgs } from "../../lock-timeout";
58
58
  import { coneArgs, readPlanCone, type PlanCone } from "../../cone";
@@ -1043,112 +1043,15 @@ interface ExecFailure {
1043
1043
  stderr?: string;
1044
1044
  }
1045
1045
 
1046
- /**
1047
- * One engine command as a product's {@link TerraformCommandHook} sees it
1048
- * before it runs (chant#4865).
1049
- */
1050
- export interface TerraformCommand {
1051
- /** The step's root the command runs for. */
1052
- root: string;
1053
- /** The upstream root whose state the command reads for `root`'s `reads`, when it runs for one. */
1054
- upstream?: string;
1055
- /** The step method that runs it: `plan`, `run` (the apply) or `outputs`. */
1056
- method: string;
1057
- /** The binary, as the command line names it. */
1058
- binary: string;
1059
- /** The subcommand, the first argument that is not a flag: `init`, `plan`, `show`, `apply`, `output`, `workspace`, `live-plan-set`. */
1060
- name: string;
1061
- /** The arguments after the binary, unquoted. */
1062
- args: string[];
1063
- /** The command line as the shell runs it. */
1064
- line: string;
1065
- /** The directory it runs in. */
1066
- cwd: string;
1067
- /** The variables chant sets for it over the job's environment, such as `TF_IN_AUTOMATION`, `TF_WORKSPACE` and the run hook's `processEnv`. */
1068
- env: Record<string, string>;
1069
- }
1070
-
1071
- /** How a {@link TerraformCommand} came out, for the hook's `after` (chant#4865). */
1072
- export interface TerraformCommandResult {
1073
- /** The exit code; null when the command did not exit on its own (a signal, an abort, a spawn failure). */
1074
- code: number | null;
1075
- /** How long it ran, in seconds. */
1076
- seconds: number;
1077
- stdout: string;
1078
- stderr: string;
1079
- }
1080
-
1081
- /** What a {@link TerraformCommandHook} answers for one command (chant#4865). */
1082
- export interface TerraformCommandRun {
1083
- /** Variables laid over the command's own, such as a span receiver's exporter or a trace parent. */
1084
- env?: Record<string, string>;
1085
- /** Called once the command ends, on a failure too, before the step reads its result. */
1086
- after?: (result: TerraformCommandResult) => void | Promise<void>;
1087
- }
1088
-
1089
- /**
1090
- * A product's hook around each engine command a `terraform-apply` step runs
1091
- * for a root (chant#4865), `terraformApplyCapabilityWith({ onCommand })`:
1092
- * called before the command with what it is, and its answer's `after` once
1093
- * it ends. terragucci times each root's plan and apply with it and sets its
1094
- * span receiver's variables, as its own runs of the binary did.
1095
- */
1096
- export type TerraformCommandHook = (command: TerraformCommand) => TerraformCommandRun | void | Promise<TerraformCommandRun | void>;
1097
-
1098
- /** The hook, and the root and method it is for, that the commands run in an async call see (chant#4865). */
1099
- interface CommandScope {
1100
- hook: TerraformCommandHook;
1101
- root: string;
1102
- upstream?: string;
1103
- method: string;
1104
- }
1105
-
1106
- /**
1107
- * The command scope of the step call that runs the engine (chant#4865). An
1108
- * async-local store, so each root a wave runs at once (chant#4864) sees its
1109
- * own, and the activities need no hook argument threaded through.
1110
- */
1111
- const commandScope = new AsyncLocalStorage<CommandScope>();
1112
-
1113
- /**
1114
- * Run `fn` with every engine command it runs going through `hook`, as
1115
- * commands for `scope.root` (chant#4865). Inside another scope, a field this
1116
- * one leaves out (`upstream`) is not kept from the outer.
1117
- */
1118
- export function withTerraformCommandHook<T>(hook: TerraformCommandHook | undefined, scope: Omit<CommandScope, "hook">, fn: () => Promise<T>): Promise<T> {
1119
- if (!hook) return fn();
1120
- return commandScope.run({ hook, ...scope }, fn);
1121
- }
1122
-
1123
- /** Run `fn` with the commands it runs marked as a read of `upstream`'s state for the scope's root (chant#4865). Outside a scope, `fn` as it is. */
1124
- export function asUpstreamCommands<T>(upstream: string, fn: () => Promise<T>): Promise<T> {
1125
- const scope = commandScope.getStore();
1126
- return scope ? commandScope.run({ ...scope, upstream }, fn) : fn();
1127
- }
1128
-
1129
- /** The words of a command line the builders here wrote: plain words, and `quoteArg`'s single-quoted ones. */
1130
- export function commandWords(line: string): string[] {
1131
- const words: string[] = [];
1132
- let word: string | undefined;
1133
- for (let i = 0; i < line.length; i++) {
1134
- const c = line[i]!;
1135
- if (c === " ") {
1136
- if (word !== undefined) words.push(word);
1137
- word = undefined;
1138
- } else if (c === "'") {
1139
- const end = line.indexOf("'", i + 1);
1140
- const stop = end < 0 ? line.length : end;
1141
- word = (word ?? "") + line.slice(i + 1, stop);
1142
- i = stop;
1143
- } else if (c === "\\" && i + 1 < line.length) {
1144
- word = (word ?? "") + line[++i];
1145
- } else {
1146
- word = (word ?? "") + c;
1147
- }
1148
- }
1149
- if (word !== undefined) words.push(word);
1150
- return words;
1151
- }
1046
+ export {
1047
+ asUpstreamCommands,
1048
+ commandWords,
1049
+ withTerraformCommandHook,
1050
+ type TerraformCommand,
1051
+ type TerraformCommandHook,
1052
+ type TerraformCommandResult,
1053
+ type TerraformCommandRun,
1054
+ } from "../command-hook";
1152
1055
 
1153
1056
  /** Run `cmd` in `dir`, forwarding the signal so an abort kills the child. */
1154
1057
  function runPlain(cmd: string, dir: string, env: Record<string, string>, signal?: AbortSignal, unset: readonly string[] = []): Promise<{ stdout: string; stderr: string }> {
@@ -1169,14 +1072,12 @@ async function run(
1169
1072
  signal?: AbortSignal,
1170
1073
  unset: readonly string[] = [],
1171
1074
  ): Promise<{ stdout: string; stderr: string }> {
1172
- const scope = commandScope.getStore();
1075
+ const scope = currentCommandScope();
1173
1076
  if (!scope) return runPlain(cmd, dir, env, signal, unset);
1174
1077
  const words = commandWords(cmd);
1175
1078
  const args = words.slice(1);
1176
1079
  const command: TerraformCommand = {
1177
- root: scope.root,
1178
- ...(scope.upstream !== undefined ? { upstream: scope.upstream } : {}),
1179
- method: scope.method,
1080
+ ...scopedCommand(scope),
1180
1081
  binary: words[0] ?? "",
1181
1082
  name: args.find((a) => !a.startsWith("-")) ?? "",
1182
1083
  args,
@@ -0,0 +1,189 @@
1
+ /**
2
+ * The hook a product puts around each engine command `terraform-apply`
3
+ * runs (chant#4865), and the async-local scope that carries it to the
4
+ * activities that run the binary. Kept apart from
5
+ * `./activities/terraform.ts` so the composed group's runs
6
+ * (`../components/compose-group.ts`, through `BinaryExec`) and the engine
7
+ * timings (`../engine-timings.ts`) read the same scope (chant#4887).
8
+ */
9
+ import { AsyncLocalStorage } from "node:async_hooks";
10
+ import type { BinaryExec, Ran } from "../state/exec";
11
+
12
+ /**
13
+ * One engine command as a product's {@link TerraformCommandHook} sees it
14
+ * before it runs (chant#4865).
15
+ */
16
+ export interface TerraformCommand {
17
+ /** The step's root the command runs for. */
18
+ root: string;
19
+ /** The upstream root whose state the command reads for `root`'s `reads`, when it runs for one. */
20
+ upstream?: string;
21
+ /**
22
+ * The roots a composed group's command runs for (chant#4887): a group's
23
+ * plan and apply run one engine command for all its members, in the
24
+ * composed directory. `root` is then the first of them.
25
+ */
26
+ members?: string[];
27
+ /** The step method that runs it: `plan`, `run` (the apply) or `outputs`. */
28
+ method: string;
29
+ /** The binary, as the command line names it. */
30
+ binary: string;
31
+ /** The subcommand, the first argument that is not a flag: `init`, `plan`, `show`, `apply`, `output`, `workspace`, `live-plan-set`. */
32
+ name: string;
33
+ /** The arguments after the binary, unquoted. */
34
+ args: string[];
35
+ /** The command line as the shell runs it. */
36
+ line: string;
37
+ /** The directory it runs in. */
38
+ cwd: string;
39
+ /** The variables chant sets for it over the job's environment, such as `TF_IN_AUTOMATION`, `TF_WORKSPACE` and the run hook's `processEnv`. */
40
+ env: Record<string, string>;
41
+ }
42
+
43
+ /** How a {@link TerraformCommand} came out, for the hook's `after` (chant#4865). */
44
+ export interface TerraformCommandResult {
45
+ /** The exit code; null when the command did not exit on its own (a signal, an abort, a spawn failure). */
46
+ code: number | null;
47
+ /** How long it ran, in seconds. */
48
+ seconds: number;
49
+ stdout: string;
50
+ stderr: string;
51
+ /**
52
+ * When it ran, in Unix milliseconds, for a command timed apart from its
53
+ * call (chant#4954): a Terragrunt unit's plan, from Terragrunt's run
54
+ * report, whose `after` is called once the whole wave ends. Unset, it ran
55
+ * from the hook's call to its `after`.
56
+ */
57
+ at?: { start: number; end: number };
58
+ }
59
+
60
+ /** What a {@link TerraformCommandHook} answers for one command (chant#4865). */
61
+ export interface TerraformCommandRun {
62
+ /** Variables laid over the command's own, such as a span receiver's exporter or a trace parent. */
63
+ env?: Record<string, string>;
64
+ /** Called once the command ends, on a failure too, before the step reads its result. */
65
+ after?: (result: TerraformCommandResult) => void | Promise<void>;
66
+ }
67
+
68
+ /**
69
+ * A product's hook around each engine command a `terraform-apply` step runs
70
+ * for a root (chant#4865), `terraformApplyCapabilityWith({ onCommand })`:
71
+ * called before the command with what it is, and its answer's `after` once
72
+ * it ends. terragucci times each root's plan and apply with it and sets its
73
+ * span receiver's variables, as its own runs of the binary did.
74
+ */
75
+ export type TerraformCommandHook = (command: TerraformCommand) => TerraformCommandRun | void | Promise<TerraformCommandRun | void>;
76
+
77
+ /** The hook, and the root and method it is for, that the commands run in an async call see (chant#4865). */
78
+ export interface CommandScope {
79
+ hook: TerraformCommandHook;
80
+ root: string;
81
+ upstream?: string;
82
+ /** The members of a composed group, for its commands (chant#4887). */
83
+ members?: string[];
84
+ method: string;
85
+ }
86
+
87
+ /**
88
+ * The command scope of the step call that runs the engine (chant#4865). An
89
+ * async-local store, so each root a wave runs at once (chant#4864) sees its
90
+ * own, and the activities need no hook argument threaded through.
91
+ */
92
+ const commandScope = new AsyncLocalStorage<CommandScope>();
93
+
94
+ /**
95
+ * Run `fn` with every engine command it runs going through `hook`, as
96
+ * commands for `scope.root` (chant#4865). Inside another scope, a field this
97
+ * one leaves out (`upstream`, `members`) is not kept from the outer.
98
+ */
99
+ export function withTerraformCommandHook<T>(hook: TerraformCommandHook | undefined, scope: Omit<CommandScope, "hook">, fn: () => Promise<T>): Promise<T> {
100
+ if (!hook) return fn();
101
+ return commandScope.run({ hook, ...scope }, fn);
102
+ }
103
+
104
+ /** Run `fn` with the commands it runs marked as a read of `upstream`'s state for the scope's root (chant#4865). Outside a scope, `fn` as it is. */
105
+ export function asUpstreamCommands<T>(upstream: string, fn: () => Promise<T>): Promise<T> {
106
+ const scope = commandScope.getStore();
107
+ return scope ? commandScope.run({ ...scope, upstream }, fn) : fn();
108
+ }
109
+
110
+ /** The scope the current async call runs in, or undefined outside one. */
111
+ export function currentCommandScope(): CommandScope | undefined {
112
+ return commandScope.getStore();
113
+ }
114
+
115
+ /** The fields of a {@link TerraformCommand} that come from the scope. */
116
+ export function scopedCommand(scope: CommandScope): Pick<TerraformCommand, "root" | "upstream" | "members" | "method"> {
117
+ return {
118
+ root: scope.root,
119
+ ...(scope.upstream !== undefined ? { upstream: scope.upstream } : {}),
120
+ ...(scope.members !== undefined ? { members: [...scope.members] } : {}),
121
+ method: scope.method,
122
+ };
123
+ }
124
+
125
+ /**
126
+ * `exec` with each run going through the command hook of the step call it
127
+ * runs in (chant#4887), as the activities' own commands do: a composed
128
+ * group's `init`, `plan`, `show` and `apply`, and the `version` its estate
129
+ * check asks. The hook sees the variables the run sets over the job's
130
+ * environment, its variables are laid over the run's, and its `after` gets
131
+ * the exit code, time and output. Outside a scope, `exec` as it is.
132
+ */
133
+ export function hookedBinaryExec(exec: BinaryExec): BinaryExec {
134
+ return async (binary, args, dir, env, io) => {
135
+ const scope = commandScope.getStore();
136
+ if (!scope) return exec(binary, args, dir, env, io);
137
+ const own: Record<string, string> = { TF_IN_AUTOMATION: "1" };
138
+ for (const [k, v] of Object.entries(env)) if (v !== undefined && process.env[k] !== v) own[k] = v;
139
+ const command: TerraformCommand = {
140
+ ...scopedCommand(scope),
141
+ binary,
142
+ name: args.find((a) => !a.startsWith("-")) ?? "",
143
+ args: [...args],
144
+ line: [binary, `-chdir=${dir}`, ...args].map((w) => (/^[\w@%+=:,./-]+$/.test(w) ? w : quoteWord(w))).join(" "),
145
+ cwd: dir,
146
+ env: own,
147
+ };
148
+ const given = (await scope.hook(command)) ?? {};
149
+ const start = performance.now();
150
+ let ran: Ran;
151
+ try {
152
+ ran = await exec(binary, args, dir, given.env ? { ...env, ...given.env } : env, io);
153
+ } catch (err) {
154
+ await given.after?.({ code: null, seconds: (performance.now() - start) / 1000, stdout: "", stderr: err instanceof Error ? err.message : String(err) });
155
+ throw err;
156
+ }
157
+ // `out` holds stdout and stderr together, as they came; stderr alone is what is left once stdout is taken out of it.
158
+ const stderr = ran.out.startsWith(ran.stdout) ? ran.out.slice(ran.stdout.length) : ran.out;
159
+ await given.after?.({ code: ran.code, seconds: (performance.now() - start) / 1000, stdout: ran.stdout, stderr });
160
+ return ran;
161
+ };
162
+ }
163
+
164
+ /** A word single-quoted for a shell, as `quoteArg` writes it. */
165
+ const quoteWord = (w: string): string => `'${w.replace(/'/g, `'\\''`)}'`;
166
+
167
+ /** The words of a command line the builders here wrote: plain words, and `quoteArg`'s single-quoted ones. */
168
+ export function commandWords(line: string): string[] {
169
+ const words: string[] = [];
170
+ let word: string | undefined;
171
+ for (let i = 0; i < line.length; i++) {
172
+ const c = line[i]!;
173
+ if (c === " ") {
174
+ if (word !== undefined) words.push(word);
175
+ word = undefined;
176
+ } else if (c === "'") {
177
+ const end = line.indexOf("'", i + 1);
178
+ const stop = end < 0 ? line.length : end;
179
+ word = (word ?? "") + line.slice(i + 1, stop);
180
+ i = stop;
181
+ } else if (c === "\\" && i + 1 < line.length) {
182
+ word = (word ?? "") + line[++i];
183
+ } else {
184
+ word = (word ?? "") + c;
185
+ }
186
+ }
187
+ if (word !== undefined) words.push(word);
188
+ return words;
189
+ }
@@ -29,3 +29,4 @@ export * from "./source-forms";
29
29
  export * from "./proxies";
30
30
  export { moduleConsumers, isLocalSource, type ModuleConsumer } from "../pin/consumers";
31
31
  export { usedSources, type UsedSource, type UnreadSource, type UsedSourcesOptions } from "../used-sources";
32
+ export { MODULE_CONSUMERS_FLOOR, USED_SOURCES_FLOOR } from "../chant-floors";
@@ -0,0 +1,18 @@
1
+ /** chant#4910: the engine's environment without the forge's tokens, and the binary runner that applies it. */
2
+ import { describe, expect, test } from "vitest";
3
+ import { engineEnv, tokenlessBinaryExec, type BinaryExec } from "./exec";
4
+
5
+ describe("engineEnv (chant#4910)", () => {
6
+ test("drops chant's forge token variables, the product's own, and any variable holding one's value, but never a TF_ variable", () => {
7
+ const env = { PATH: "/bin", GITHUB_TOKEN: "ghs_1", TG_TOKEN: "glpat-2", GITLAB_TOKEN: "glpat-2", MY_COPY: "ghs_1", TF_VAR_token: "glpat-2", TF_HTTP_PASSWORD: "ghs_1", AWS_REGION: "eu-west-1" };
8
+ expect(engineEnv(env, ["TG_TOKEN"])).toEqual({ PATH: "/bin", TF_VAR_token: "glpat-2", TF_HTTP_PASSWORD: "ghs_1", AWS_REGION: "eu-west-1" });
9
+ expect(engineEnv({ TG_TOKEN: "x", PATH: "/bin" })).toEqual({ TG_TOKEN: "x", PATH: "/bin" });
10
+ });
11
+
12
+ test("tokenlessBinaryExec runs the binary with that environment", async () => {
13
+ let got: NodeJS.ProcessEnv = {};
14
+ const exec: BinaryExec = async (_b, _a, _d, env) => ((got = env), { code: 0, stdout: "", out: "" });
15
+ await tokenlessBinaryExec(["TG_MERGE_TOKEN"], exec)("tofu", ["plan"], "/w", { TG_MERGE_TOKEN: "m", CI_JOB_TOKEN: "j", HOME: "/h" });
16
+ expect(got).toEqual({ HOME: "/h" });
17
+ });
18
+ });