@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,32 @@
1
+ /**
2
+ * The chant floors of the terraform lexicon's parts (#4916): for each part a
3
+ * product may feature-detect on, the first chant release whose lexicon has
4
+ * it. Lexicons release with chant at the same version, so each is a chant
5
+ * version, and chant core's floor table (`@intentius/chant/floor-table`)
6
+ * lists them beside core's, which `chant dev dead-guards` reads.
7
+ *
8
+ * Only this file is read for the table: the `_FLOOR` constants elsewhere in
9
+ * the lexicon name versions of other tools (`NEXUS_HOSTED_FLOOR` in
10
+ * ./registry/targets/nexus.ts is a Nexus version). The entries that serve a
11
+ * part re-export its floor by name, so the table names those subpaths too.
12
+ *
13
+ * This file imports nothing, so an entry that must stay light (./module-catalog)
14
+ * can re-export from it.
15
+ */
16
+
17
+ /**
18
+ * The first chant whose terraform lexicon has `moduleConsumers`, the scan of
19
+ * every registry module call a root makes, with `readRegistryCatalog` and
20
+ * `deprecatedPins` beside it on `./registry` (#4599).
21
+ */
22
+ export const MODULE_CONSUMERS_FLOOR = "0.124.55";
23
+
24
+ /**
25
+ * The first chant whose terraform lexicon has `usedSources`, every module
26
+ * source and provider address a root uses, with `moduleSourceForms`,
27
+ * `providerAddressForms` and `lockedProviders` on `./registry` (#3924).
28
+ */
29
+ export const USED_SOURCES_FLOOR = "0.124.55";
30
+
31
+ /** The first chant whose terraform lexicon has `./module-catalog`, the known-module catalog TF047 reads (#4560). */
32
+ export const MODULE_CATALOG_FLOOR = "0.124.55";
@@ -182,7 +182,7 @@ import { rootRowKey, type LockRow } from "@intentius/chant/lifecycle/lock-rows";
182
182
  import type { TerraformConfig } from "../config";
183
183
  import { rootTexts } from "../compose/hcl";
184
184
  import { declaredVariables } from "../compose/root";
185
- import { terraformComposeGroup } from "./compose-group";
185
+ import { composeGroup, terraformComposeGroup, type ComposeGroupDeps } from "./compose-group";
186
186
  import { markPlaceholderDriven, placeholderVars, waitingHole } from "./placeholder-preview";
187
187
  import { terraformReleaseInputs } from "./release-inputs";
188
188
  import { terraformTraceFacts } from "./trace-facts";
@@ -260,9 +260,22 @@ export interface TerraformApplyDeps {
260
260
  * and `output` of each upstream its `reads` name. The hook sees the
261
261
  * command's name, args, directory and environment, may add variables to
262
262
  * it, and its `after` gets the exit code, duration and output. Roots a
263
- * wave runs at once (chant#4864) each see their own commands.
263
+ * wave runs at once (chant#4864) each see their own commands. A composed
264
+ * group's `init`, `plan`, `show` and `apply` (`terraform.compose`) go
265
+ * through it too, as commands for all the group's roots: `members` names
266
+ * them and `root` is the first (chant#4887). `engineTimings()`
267
+ * (`../engine-timings.ts`) is a hook that times each root and collects the
268
+ * engine's spans.
264
269
  */
265
270
  onCommand?: TerraformCommandHook;
271
+ /**
272
+ * The composed group's deps (`terraform.compose`), such as the project,
273
+ * the identities and the environment its run takes, in place of the
274
+ * defaults (chant#4887). A product that spread `composeGroup(...)`'s
275
+ * methods over this capability passes its deps here instead, so the
276
+ * group's commands go through `onCommand` too.
277
+ */
278
+ compose?: ComposeGroupDeps;
266
279
  }
267
280
 
268
281
  export type { TerraformCommand, TerraformCommandHook, TerraformCommandResult, TerraformCommandRun } from "../op/activities/terraform";
@@ -707,16 +720,24 @@ export function terraformApplyCapabilityWith(deps: TerraformApplyDeps = {}): Cap
707
720
  if (!hook) return cap;
708
721
  // chant#4865: each method that runs the engine for a root runs it through the product's hook, as commands for that root.
709
722
  const scope = (method: string, step: TerraformApplyStepInput) => ({ root: typeof step?.root === "string" ? step.root : "", method });
723
+ // chant#4887: a composed group's commands run once for all its members; the hook sees them as commands for each, `root` the first.
724
+ const groupScope = (method: string, members: readonly { step: { root?: unknown } }[]) => {
725
+ const roots = [...new Set(members.map((m) => (typeof m.step?.root === "string" ? m.step.root : "")).filter((r) => r !== ""))].sort();
726
+ return { root: roots[0] ?? "", members: roots, method };
727
+ };
710
728
  return {
711
729
  ...cap,
712
730
  plan: (ctx, step) => withTerraformCommandHook(hook, scope("plan", step), () => cap.plan(ctx, step)),
713
731
  run: (ctx, step) => withTerraformCommandHook(hook, scope("run", step), () => cap.run(ctx, step)),
714
732
  outputs: (ctx, step) => withTerraformCommandHook(hook, scope("outputs", step), () => cap.outputs!(ctx, step)),
733
+ planGroup: (ctx, members) => withTerraformCommandHook(hook, groupScope("plan", members), () => cap.planGroup!(ctx, members)),
734
+ runGroup: (ctx, run, members) => withTerraformCommandHook(hook, groupScope("run", members), () => cap.runGroup!(ctx, run, members)),
715
735
  };
716
736
  }
717
737
 
718
738
  /** The step's methods with `deps.resolveRoot`, before {@link terraformApplyCapabilityWith} puts its command hook around them. */
719
739
  function terraformApplyMethods(deps: TerraformApplyDeps): Capability<TerraformApplyStepInput, TerraformApplyStepOutput> & Required<Pick<Capability<TerraformApplyStepInput, TerraformApplyStepOutput>, "plan" | "outputs">> {
740
+ const group = deps.compose ? composeGroup(deps.compose) : terraformComposeGroup;
720
741
  return {
721
742
  kind: "terraform-apply",
722
743
  // A root's apply has no undo short of applying the previous configuration,
@@ -781,12 +802,12 @@ function terraformApplyMethods(deps: TerraformApplyDeps): Capability<TerraformAp
781
802
  },
782
803
  // #4447 (ws-107): a group core forms of components that read each other plans and applies as one composed run
783
804
  // when `terraform.compose.enabled` is set (./compose-group.ts). Delegates, so the methods are read when called.
784
- groupReads: (ctx, members) => terraformComposeGroup.groupReads(ctx, members),
805
+ groupReads: (ctx, members) => group.groupReads(ctx, members),
785
806
  // #4542: a member pointed at a release's recorded copy plans alone, since a composition reads the declared roots.
786
807
  groupFallback: async (ctx, members) =>
787
808
  members.some((m) => typeof m.step.dir === "string")
788
809
  ? { kind: "release-copy", reason: "a member deploys a release's recorded copy of its root, which a composition does not read" }
789
- : terraformComposeGroup.groupFallback(ctx, members),
810
+ : group.groupFallback(ctx, members),
790
811
  // #4542: the root's files, which a release cut records and a promote under it plans.
791
812
  releaseInputs: (input, ctx) => terraformReleaseInputs(input, ctx),
792
813
  // #4552: resource under choudoufu, the root under Terraform, tofu and Terragrunt, which refuse resource by name.
@@ -813,11 +834,11 @@ function terraformApplyMethods(deps: TerraformApplyDeps): Capability<TerraformAp
813
834
  planGroup: (ctx, members) => {
814
835
  // chant#4854: each member's lock grain reads the config at the wave's directory too.
815
836
  for (const m of members) if (m.input) withContextCwd(m.ctx ?? ctx, m.input);
816
- return terraformComposeGroup.planGroup(ctx, members);
837
+ return group.planGroup(ctx, members);
817
838
  },
818
839
  runGroup: (ctx, run, members) => {
819
840
  for (const m of members) if (m.input) withContextCwd(m.ctx ?? ctx, m.input);
820
- return terraformComposeGroup.runGroup(ctx, run, members);
841
+ return group.runGroup(ctx, run, members);
821
842
  },
822
843
  async run(ctx: DeployContext, step: TerraformApplyStepInput): Promise<TerraformApplyStepOutput> {
823
844
  const input = await filledInput(deps.resolveRoot, ctx, step);
@@ -484,3 +484,32 @@ describe("helpers (#4447)", () => {
484
484
  expect(c.reads.get("b")).toEqual([{ via: "vars", upstream: "a", variable: "a_id", output: "id" }]);
485
485
  });
486
486
  });
487
+
488
+ describe("the composed run's commands go through the step's command hook (chant#4887)", () => {
489
+ test("with no runner given, each command the composed run makes reaches the hook as a command for every member", async () => {
490
+ const { withTerraformCommandHook } = await import("../op/command-hook");
491
+ const dir = project();
492
+ const ran: string[] = [];
493
+ const g = composeGroup({
494
+ project: async () => ({ projectRoot: dir, terraform: terraform(true) }),
495
+ identity: async () => undefined,
496
+ // The first member's init fails, so the run stops before it plans: what matters is that its command went through the hook.
497
+ exec: async (_bin, args, _dir, env) => {
498
+ ran.push(`${args[0]} ${env.HOOK_TAG ?? "none"}`);
499
+ return { code: 1, stdout: "", out: "Error: no provider" };
500
+ },
501
+ env: {},
502
+ log: () => {},
503
+ });
504
+ const seen: Array<{ name: string; root: string; members?: string[]; method: string; code?: number | null }> = [];
505
+ const hook = (c: { name: string; root: string; members?: string[]; method: string }) => {
506
+ const at = seen.push({ name: c.name, root: c.root, ...(c.members ? { members: c.members } : {}), method: c.method }) - 1;
507
+ return { env: { HOOK_TAG: `${c.method}:${c.name}` }, after: (r: { code: number | null }) => void (seen[at]!.code = r.code) };
508
+ };
509
+ await expect(
510
+ withTerraformCommandHook(hook, { root: "a", members: ["a", "b", "c"], method: "plan" }, () => g.planGroup({ env: "test" } as never, members())),
511
+ ).rejects.toThrow(/init failed/);
512
+ expect(ran).toEqual(["init plan:init"]);
513
+ expect(seen).toEqual([{ name: "init", root: "a", members: ["a", "b", "c"], method: "plan", code: 1 }]);
514
+ });
515
+ });
@@ -61,6 +61,7 @@ import { COMPOSE_STEP_KIND, composeOff, compositionIfEnabled, identityKey, rootH
61
61
  import type { TerraformConfig } from "../config";
62
62
  import { terraformBinary, terraformOutputs } from "../op/activities/terraform";
63
63
  import { runBinary, type BinaryExec } from "../state/exec";
64
+ import { hookedBinaryExec } from "../op/command-hook";
64
65
  import { estateVersionFallback, EstateRun, type ComposedRunner } from "../compose/estate";
65
66
  import { ComposedRun } from "../compose/run";
66
67
  import { relPath, rootTexts } from "../compose/hcl";
@@ -113,7 +114,11 @@ export interface ComposeGroupDeps {
113
114
  * `declaredTargetCloudIdentity` from the project root.
114
115
  */
115
116
  identity?: (projectRoot: string, env: string) => Promise<TargetCloudIdentityLookup | undefined>;
116
- /** How `choudoufu version` runs. Default `runBinary`. */
117
+ /**
118
+ * How the binary runs: `choudoufu version`, and the composed run's own
119
+ * commands when `runner` is not given. Default `runBinary`. Either way each
120
+ * run goes through the step's command hook (chant#4887).
121
+ */
117
122
  exec?: BinaryExec;
118
123
  /** A root's outputs as its state holds them, for a member whose part of the working state could not be shown. Default `terraformOutputs`. */
119
124
  outputs?: (root: string) => Promise<Record<string, unknown>>;
@@ -137,11 +142,12 @@ async function loadProject(cwd?: string): Promise<ComposeProject> {
137
142
  return { projectRoot, terraform: { ...(terraform ?? {}), roots: terraform?.roots ?? {} } as TerraformConfig };
138
143
  }
139
144
 
140
- function defaultRunner(o: GroupRunnerOptions, log?: (line: string) => void): ComposedRunner {
145
+ function defaultRunner(o: GroupRunnerOptions, exec: BinaryExec, log?: (line: string) => void): ComposedRunner {
141
146
  if (o.composition.estate) {
142
- return new EstateRun({ projectRoot: o.projectRoot, composition: o.composition, terraform: o.terraform, env: o.env, work: o.work, ...(log ? { log } : {}) });
147
+ return new EstateRun({ projectRoot: o.projectRoot, composition: o.composition, terraform: o.terraform, env: o.env, work: o.work, exec, ...(log ? { log } : {}) });
143
148
  }
144
149
  return new ComposedRun({
150
+ exec,
145
151
  projectRoot: o.projectRoot,
146
152
  composition: o.composition,
147
153
  terraform: o.terraform,
@@ -354,7 +360,8 @@ export class ComposedPlanMovedError extends Error {
354
360
  /** The group methods, with `deps` in place of the defaults. */
355
361
  export function composeGroup(deps: ComposeGroupDeps = {}): ComposeGroupMethods {
356
362
  const project = deps.project ?? loadProject;
357
- const exec = deps.exec ?? runBinary;
363
+ // chant#4887: the composed group's commands go through the step's command hook, as a plain root's do.
364
+ const exec = hookedBinaryExec(deps.exec ?? runBinary);
358
365
  const envOf = (): NodeJS.ProcessEnv => deps.env ?? process.env;
359
366
  const log = deps.log ?? ((line: string) => console.error(line));
360
367
  const readOutputs = deps.outputs ?? ((root: string) => terraformOutputs({ root }));
@@ -391,7 +398,7 @@ export function composeGroup(deps: ComposeGroupDeps = {}): ComposeGroupMethods {
391
398
  env: envOf(),
392
399
  work,
393
400
  };
394
- const runner = deps.runner ? deps.runner(o) : defaultRunner(o, log);
401
+ const runner = deps.runner ? deps.runner(o) : defaultRunner(o, exec, log);
395
402
  try {
396
403
  return await fn(runner);
397
404
  } finally {
@@ -154,4 +154,47 @@ describe("terraform-apply's hook around each engine command (chant#4865)", () =>
154
154
  expect(results[0]![1].code).toBe(1);
155
155
  expect(results[0]![1].stderr).toContain("broken");
156
156
  });
157
+ test("a composed group's commands reach the hook as commands for each member (chant#4887)", async () => {
158
+ const p = project();
159
+ // The lexicon's runBinary passes `-chdir=<dir>` first, so the fake logs its second word, the subcommand.
160
+ writeFileSync(join(p.dir, "bin", "tofu"), `#!/bin/sh\necho "$2 \${1##*/} \${FAKE_TAG:-none}" >> "$FAKE_LOG"\necho "Error: no provider" >&2\nexit 1\n`);
161
+ chmodSync(join(p.dir, "bin", "tofu"), 0o755);
162
+ writeFileSync(join(p.dir, "roots", "a", "main.tf"), 'output "id" {\n value = "a"\n}\n');
163
+ writeFileSync(join(p.dir, "roots", "b", "main.tf"), 'variable "a_id" {\n type = string\n}\n');
164
+ writeFileSync(join(p.dir, "chant.config.json"), JSON.stringify({ lexicons: ["terraform"], terraform: { binary: "tofu", roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" } }, compose: { enabled: true } } }));
165
+ const seen: TerraformCommand[] = [];
166
+ const cap = terraformApplyCapabilityWith({ onCommand: (c) => ({ env: { FAKE_TAG: `${c.members?.join("+")}:${c.name}` }, after: () => void seen.push(c) }) });
167
+ const members = [
168
+ { component: "a", step: { root: "a", vars: {} }, input: { root: "a", vars: {} }, reads: [], dependsOn: [], ctx: { env: "test", component: "a" } },
169
+ { component: "b", step: { root: "b", vars: { a_id: { stackOutput: { stack: "a", name: "id" } } } }, input: { root: "b", vars: { a_id: undefined } }, reads: [{ at: "/vars/a_id", ref: "a.id", component: "a", output: "id" }], dependsOn: ["a"], ctx: { env: "test", component: "b" } },
170
+ ];
171
+ await expect(cap.planGroup!({ env: "test", cwd: p.dir } as never, members as never)).rejects.toThrow(/init failed/);
172
+ expect(seen.map((c) => [c.name, c.root, c.members, c.method])).toEqual([["init", "a", ["a", "b"], "plan"]]);
173
+ expect(readFileSync(p.log, "utf-8").trim()).toBe("init a a+b:init");
174
+ });
175
+ test("a product's own compose deps are taken by the capability, so its group's commands reach the hook too (chant#4887)", async () => {
176
+ const seen: string[] = [];
177
+ const ran: string[] = [];
178
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-tf-hook-compose-")));
179
+ for (const r of ["a", "b"]) mkdirSync(join(dir, "roots", r), { recursive: true });
180
+ writeFileSync(join(dir, "roots", "a", "main.tf"), 'output "id" {\n value = "a"\n}\n');
181
+ writeFileSync(join(dir, "roots", "b", "main.tf"), 'variable "a_id" {\n type = string\n}\n');
182
+ const cap = terraformApplyCapabilityWith({
183
+ onCommand: (c) => ({ env: { TAG: `${c.members?.join("+")}:${c.name}` }, after: () => void seen.push(`${c.method} ${c.name} ${c.members?.join("+")}`) }),
184
+ compose: {
185
+ project: async () => ({ projectRoot: dir, terraform: { binary: "tofu", roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" } }, compose: { enabled: true } } as never }),
186
+ identity: async () => undefined,
187
+ exec: async (_bin, args, _dir, env) => (ran.push(`${args[0]} ${env.TAG}`), { code: 1, stdout: "", out: "Error: no provider" }),
188
+ env: {},
189
+ log: () => {},
190
+ },
191
+ });
192
+ const members = [
193
+ { component: "a", step: { root: "a", vars: {} }, input: { root: "a", vars: {} }, reads: [], dependsOn: [], ctx: { env: "test", component: "a" } },
194
+ { component: "b", step: { root: "b", vars: { a_id: { stackOutput: { stack: "a", name: "id" } } } }, input: { root: "b", vars: { a_id: undefined } }, reads: [{ at: "/vars/a_id", ref: "a.id", component: "a", output: "id" }], dependsOn: ["a"], ctx: { env: "test", component: "b" } },
195
+ ];
196
+ await expect(cap.planGroup!({ env: "test" } as never, members as never)).rejects.toThrow(/init failed/);
197
+ expect(seen).toEqual(["plan init a+b"]);
198
+ expect(ran).toEqual(["init a+b:init"]);
199
+ });
157
200
  });
@@ -0,0 +1,261 @@
1
+ /**
2
+ * One runner of the engine for a product (chant#4954): a plan stage's own
3
+ * commands and each Terragrunt unit's plan reach the same `onCommand` as
4
+ * `terraform-apply`'s, the trace parent per command is the lexicon's, and
5
+ * every run (async, blocking, Terragrunt, the script chant's step runs)
6
+ * leaves the forge's tokens out. Fake binaries are small `sh` scripts in a
7
+ * temporary directory; nothing reaches a cloud, a forge or a collector.
8
+ */
9
+ import { spawnSync } from "node:child_process";
10
+ import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
11
+ import { tmpdir } from "node:os";
12
+ import { dirname, join } from "node:path";
13
+ import { describe, expect, test } from "vitest";
14
+ import { OtlpTrace } from "@intentius/chant/otlp";
15
+ import { commandTrace, commandTraceEnv, engineRunner, withTerraformCommandHook, type TerraformCommand, type TerraformCommandResult } from "./engine-runner";
16
+ import { engineTimings } from "./engine-timings";
17
+ import type { BinaryExec } from "./state/exec";
18
+ import { planTerragruntWave, terragruntUnitWrapper, type TerragruntExec } from "./terragrunt/run";
19
+
20
+ const tmp = (): string => mkdtempSync(join(tmpdir(), "chant-engine-runner-"));
21
+
22
+ /** An executable `sh` script at `path`. */
23
+ function script(path: string, body: string): string {
24
+ mkdirSync(dirname(path), { recursive: true });
25
+ writeFileSync(path, `#!/bin/sh\n${body}\n`);
26
+ chmodSync(path, 0o755);
27
+ return path;
28
+ }
29
+
30
+ const JOB = { PATH: process.env.PATH ?? "/usr/bin:/bin", GITHUB_TOKEN: "ghs_forge", TG_TOKEN: "tg-secret", COPY: "tg-secret", TF_VAR_token: "tg-secret", KEEP: "yes" };
31
+
32
+ describe("the plan stage's own commands", () => {
33
+ test("go through the command hook of the call they run in, as commands for its root", async () => {
34
+ const seen: TerraformCommand[] = [];
35
+ const ran: Array<{ args: string[]; env: NodeJS.ProcessEnv }> = [];
36
+ const fake: BinaryExec = async (_b, args, _d, env) => {
37
+ ran.push({ args, env });
38
+ return { code: args[0] === "plan" ? 2 : 0, stdout: "out", out: "outerr" };
39
+ };
40
+ const results: TerraformCommandResult[] = [];
41
+ const runner = engineRunner({ tokens: ["TG_TOKEN"], exec: fake });
42
+ await withTerraformCommandHook(
43
+ (c) => {
44
+ seen.push(c);
45
+ // A hook that names a token gets it taken out all the same.
46
+ return { env: { HOOKED: c.name, GITHUB_TOKEN: "put-back" }, after: (r) => void results.push(r) };
47
+ },
48
+ { root: "roots/a", method: "plan" },
49
+ async () => {
50
+ await runner.exec("tofu", ["init", "-input=false"], "/w/roots/a", { ...JOB });
51
+ await runner.exec("tofu", ["plan", "-detailed-exitcode"], "/w/roots/a", { ...JOB });
52
+ },
53
+ );
54
+ expect(seen.map((c) => [c.root, c.method, c.name])).toEqual([
55
+ ["roots/a", "plan", "init"],
56
+ ["roots/a", "plan", "plan"],
57
+ ]);
58
+ expect(ran[1]!.env.HOOKED).toBe("plan");
59
+ expect(ran[1]!.env.GITHUB_TOKEN).toBeUndefined();
60
+ expect(ran[1]!.env.TG_TOKEN).toBeUndefined();
61
+ expect(ran[1]!.env.COPY).toBeUndefined();
62
+ expect(ran[1]!.env.TF_VAR_token).toBe("tg-secret");
63
+ expect(results.map((r) => r.code)).toEqual([0, 2]);
64
+ expect(results[1]).toMatchObject({ stdout: "out", stderr: "err" });
65
+ });
66
+
67
+ test("outside a hook's call the binary just runs, its tokens left out", async () => {
68
+ const ran: NodeJS.ProcessEnv[] = [];
69
+ const runner = engineRunner({ tokens: ["TG_TOKEN"], exec: async (_b, _a, _d, env) => (ran.push(env), { code: 0, stdout: "", out: "" }) });
70
+ await runner.exec("tofu", ["version"], "/w", { ...JOB });
71
+ expect(ran[0]!.KEEP).toBe("yes");
72
+ expect(ran[0]!.TG_TOKEN).toBeUndefined();
73
+ expect(runner.tokens).toEqual(expect.arrayContaining(["TG_TOKEN", "GITHUB_TOKEN"]));
74
+ });
75
+ });
76
+
77
+ describe("the blocking, Terragrunt and script runs", () => {
78
+ test("execSync runs the binary in its directory with TF_IN_AUTOMATION and no tokens", () => {
79
+ const dir = tmp();
80
+ const bin = script(join(dir, "bin/tofu"), 'echo "args=$*"\necho "tok=${GITHUB_TOKEN:-none} copy=${COPY:-none} tfvar=${TF_VAR_token:-none} auto=$TF_IN_AUTOMATION"\necho oops >&2\nexit 3');
81
+ const r = engineRunner({ tokens: ["TG_TOKEN"] }).execSync(bin, ["plan"], "/w/roots/a", { ...JOB });
82
+ expect(r.code).toBe(3);
83
+ expect(r.stdout).toContain("args=-chdir=/w/roots/a plan");
84
+ expect(r.stdout).toContain("tok=none copy=none tfvar=tg-secret auto=1");
85
+ expect(r.out).toContain("oops");
86
+ });
87
+
88
+ test("execSync answers 127 for a binary that is not there", () => {
89
+ const r = engineRunner().execSync(join(tmp(), "missing"), ["version"], "/w", { ...JOB });
90
+ expect(r.code).toBe(127);
91
+ expect(r.out).toMatch(/ENOENT/);
92
+ });
93
+
94
+ test("terragrunt runs with the job's environment under the call's, less the tokens", async () => {
95
+ const dir = tmp();
96
+ const tg = script(join(dir, "terragrunt"), 'echo "pwd=$(pwd) tok=${GITHUB_TOKEN:-none} copy=${COPY:-none} call=$CALL"');
97
+ const saved = { ...process.env };
98
+ Object.assign(process.env, { GITHUB_TOKEN: "ghs_forge", TG_TOKEN: "tg-secret", COPY: "tg-secret" });
99
+ try {
100
+ const r = await engineRunner({ tokens: ["TG_TOKEN"] }).terragrunt(tg, ["find"], { cwd: dir, env: { CALL: "given" } });
101
+ expect(r.code).toBe(0);
102
+ expect(r.stdout).toContain("tok=none copy=none call=given");
103
+ } finally {
104
+ for (const k of ["GITHUB_TOKEN", "TG_TOKEN", "COPY"]) if (saved[k] === undefined) delete process.env[k];
105
+ }
106
+ });
107
+
108
+ test("script writes one same-named script that drops the tokens, by name and by value, and runs the binary", () => {
109
+ const dir = tmp();
110
+ const bin = script(join(dir, "real/tofu"), 'echo "tok=${GITHUB_TOKEN:-none} tg=${TG_TOKEN:-none} copy=${COPY:-none} tfvar=${TF_VAR_token:-none} keep=$KEEP args=$*"');
111
+ const runner = engineRunner({ tokens: ["TG_TOKEN"] });
112
+ const path = runner.script(join(dir, "scripts"), bin, { ...JOB });
113
+ expect(path.endsWith("/tofu")).toBe(true);
114
+ expect(runner.script(join(dir, "scripts"), bin, { ...JOB })).toBe(path);
115
+ const r = spawnSync(path, ["plan"], { encoding: "utf-8", env: { ...JOB } });
116
+ expect(r.stdout.trim()).toBe("tok=none tg=none copy=none tfvar=tg-secret keep=yes args=plan");
117
+ });
118
+
119
+ test("script finds a bare name on PATH, so it never runs itself", () => {
120
+ const dir = tmp();
121
+ script(join(dir, "real/tofu"), "echo real");
122
+ const env = { ...JOB, PATH: `${join(dir, "scripts-first")}:${join(dir, "real")}:/usr/bin:/bin` };
123
+ const path = engineRunner().script(join(dir, "scripts"), "tofu", env);
124
+ expect(readFileSync(path, "utf-8")).toContain(`'${join(dir, "real/tofu")}'`);
125
+ });
126
+ });
127
+
128
+ describe("the trace parent per command", () => {
129
+ test("commandTraceEnv gives TRACEPARENT and names the span, keeping the job's resource attributes and exporter", () => {
130
+ const trace = new OtlpTrace();
131
+ const span = trace.start("root roots/a");
132
+ const env = commandTraceEnv({ OTEL_RESOURCE_ATTRIBUTES: "team=infra", OTEL_TRACES_EXPORTER: "none" }, trace, span, { prefix: "terragucci", root: "roots/a" });
133
+ expect(env.TRACEPARENT).toBe(`00-${trace.traceId}-${span.spanId}-01`);
134
+ expect(env.OTEL_TRACES_EXPORTER).toBe("none");
135
+ expect(env.OTEL_RESOURCE_ATTRIBUTES).toContain("team=infra");
136
+ expect(env.OTEL_RESOURCE_ATTRIBUTES).toContain(`terragucci.span_id=${span.spanId}`);
137
+ expect(env.OTEL_RESOURCE_ATTRIBUTES).toContain("terragucci.root=roots%2Fa");
138
+ expect(commandTraceEnv({}, trace, span, { prefix: "p", root: "r" }).OTEL_TRACES_EXPORTER).toBe("otlp");
139
+ });
140
+
141
+ test("commandTrace opens a span per command under the root's, and ends it with the exit code", async () => {
142
+ const trace = new OtlpTrace();
143
+ const root = trace.start("root roots/a");
144
+ const hook = commandTrace({ trace, prefix: "terragucci", parent: (c) => (c.root === "roots/a" ? root : undefined), env: {} });
145
+ const runner = engineRunner({ exec: async (_b, args) => ({ code: args[0] === "plan" ? 2 : args[0] === "apply" ? 1 : 0, stdout: "", out: "" }) });
146
+ const envs: string[] = [];
147
+ await withTerraformCommandHook(
148
+ async (c) => {
149
+ const r = await hook(c);
150
+ if (r?.env) envs.push(r.env.TRACEPARENT!);
151
+ return r;
152
+ },
153
+ { root: "roots/a", method: "plan" },
154
+ async () => {
155
+ await runner.exec("tofu", ["plan"], "/w", {});
156
+ await runner.exec("tofu", ["apply"], "/w", {});
157
+ },
158
+ );
159
+ const spans = trace.spans.filter((s) => s !== root);
160
+ expect(spans.map((s) => [s.name, s.parentSpanId, s.kind, s.attributes["process.exit.code"], s.error])).toEqual([
161
+ ["tofu plan", root.spanId, 3, 2, undefined],
162
+ ["tofu apply", root.spanId, 3, 1, "exit 1"],
163
+ ]);
164
+ expect(envs).toEqual(spans.map((s) => trace.traceparent(s)));
165
+ });
166
+
167
+ test("an upstream's reads are not traced unless asked, and a command timed apart spans its own time", async () => {
168
+ const trace = new OtlpTrace();
169
+ const hook = commandTrace({ trace, prefix: "p", env: {} });
170
+ const base = { root: "roots/a", method: "plan", binary: "tofu", name: "init", args: ["init"], line: "tofu init", cwd: "/w", env: {} };
171
+ expect(await hook({ ...base, upstream: "roots/up" })).toBeUndefined();
172
+ const run = await hook({ ...base, name: "plan", args: ["plan"] });
173
+ await run!.after!({ code: 0, seconds: 2, stdout: "", stderr: "", at: { start: 1_700_000_000_000, end: 1_700_000_002_000 } });
174
+ expect(trace.spans[0]!.start).toBe(1_700_000_000_000n * 1_000_000n);
175
+ expect(trace.spans[0]!.end).toBe(1_700_000_002_000n * 1_000_000n);
176
+ });
177
+
178
+ test("as engineTimings' inner hook, a command gets the trace parent and the receiver's exporter", async () => {
179
+ const trace = new OtlpTrace();
180
+ const timings = await engineTimings({ inner: commandTrace({ trace, prefix: "p", env: {} }) });
181
+ try {
182
+ const envs: NodeJS.ProcessEnv[] = [];
183
+ const runner = engineRunner({ exec: async (_b, _a, _d, env) => (envs.push(env), { code: 0, stdout: "", out: "" }) });
184
+ await withTerraformCommandHook(timings.onCommand, { root: "roots/a", method: "plan" }, () => runner.exec("tofu", ["plan"], "/w", {}));
185
+ expect(envs[0]!.TRACEPARENT).toBe(trace.traceparent(trace.spans[0]!));
186
+ if (!timings.problem) expect(envs[0]!.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT).toMatch(/^http:\/\/127\.0\.0\.1:/);
187
+ expect(timings.root("roots/a")?.commands.map((c) => c.command)).toEqual(["plan"]);
188
+ } finally {
189
+ await timings.close();
190
+ }
191
+ });
192
+ });
193
+
194
+ describe("a Terragrunt unit's plan", () => {
195
+ test("the wrapper sets a unit's variables for the plan whose -out names it, and runs the binary as it is otherwise", () => {
196
+ const text = terragruntUnitWrapper("/bin/tofu", ["/w/plans", "/private/w/plans"], new Map<string, Record<string, string>>([["live/a", { X: "it's" }], ["live/b", {}]]));
197
+ expect(text).toContain(`'/w/plans/live/a/tfplan.tfplan' | '/private/w/plans/live/a/tfplan.tfplan') export X='it'\\''s' ;;`);
198
+ expect(text).not.toContain("live/b");
199
+ expect(text.trimEnd().endsWith(`exec '/bin/tofu' "$@"`)).toBe(true);
200
+ });
201
+
202
+ test("reaches onCommand once per unit, its variables reach that unit's plan alone, and its after has the report's time", async () => {
203
+ const dir = tmp();
204
+ const record = join(dir, "seen");
205
+ const bin = script(join(dir, "bin/tofu"), `echo "$UNIT_VAR" >> '${record}'`);
206
+ const seen: TerraformCommand[] = [];
207
+ const after = new Map<string, TerraformCommandResult>();
208
+ const calls: Array<{ args: readonly string[]; env: Record<string, string> }> = [];
209
+ const exec: TerragruntExec = async (_f, args, opts) => {
210
+ calls.push({ args, env: opts.env });
211
+ const at = (flag: string): string => args[args.indexOf(flag) + 1]!;
212
+ // Terragrunt runs the binary through TG_TF_PATH for each unit's plan, then an init with no -out.
213
+ for (const unit of ["live/a", "live/b"]) spawnSync(opts.env.TG_TF_PATH!, ["plan", `-out=${join(at("--out-dir"), unit, "tfplan.tfplan")}`], { encoding: "utf-8" });
214
+ spawnSync(opts.env.TG_TF_PATH!, ["init"], { encoding: "utf-8", env: { ...process.env, UNIT_VAR: "none" } });
215
+ writeFileSync(
216
+ at("--report-file"),
217
+ JSON.stringify([
218
+ { Name: "live/a", Result: "succeeded", Started: "2026-11-10T10:00:00Z", Ended: "2026-11-10T10:00:04Z" },
219
+ { Name: "live/b", Result: "failed", Reason: "run error", Started: "2026-11-10T10:00:00Z", Ended: "2026-11-10T10:00:01Z" },
220
+ ]),
221
+ );
222
+ return { code: 1, stdout: "", stderr: "" };
223
+ };
224
+ await planTerragruntWave({
225
+ dir,
226
+ units: ["live/b", "live/a"],
227
+ workDir: "w",
228
+ binary: bin,
229
+ provisional: true,
230
+ exec,
231
+ onCommand: (c) => {
232
+ seen.push(c);
233
+ return { env: { UNIT_VAR: `for ${c.root}` }, after: (r) => void after.set(c.root, r) };
234
+ },
235
+ });
236
+ expect(seen.map((c) => [c.root, c.method, c.name, c.binary])).toEqual([
237
+ ["live/a", "plan", "plan", bin],
238
+ ["live/b", "plan", "plan", bin],
239
+ ]);
240
+ expect(seen[0]!.cwd).toBe(join(dir, "live/a"));
241
+ expect(readFileSync(record, "utf-8").trim().split("\n")).toEqual(["for live/a", "for live/b", "none"]);
242
+ expect(after.get("live/a")).toMatchObject({ code: 0, seconds: 4, at: { start: Date.parse("2026-11-10T10:00:00Z"), end: Date.parse("2026-11-10T10:00:04Z") } });
243
+ expect(after.get("live/b")).toMatchObject({ code: 1, seconds: 1, stderr: "failed: run error" });
244
+ expect(calls[0]!.env.TG_TF_PATH).not.toBe(bin);
245
+ });
246
+
247
+ test("a unit missing from the report gets a null code, and a wave with no binary calls no hook", async () => {
248
+ const dir = tmp();
249
+ const bin = script(join(dir, "bin/tofu"), "true");
250
+ const after: TerraformCommandResult[] = [];
251
+ const exec: TerragruntExec = async (_f, args) => {
252
+ writeFileSync(args[args.indexOf("--report-file") + 1]!, "[]");
253
+ return { code: 0, stdout: "", stderr: "" };
254
+ };
255
+ await planTerragruntWave({ dir, units: ["live/a"], workDir: "w", binary: bin, provisional: true, exec, onCommand: () => ({ after: (r) => void after.push(r) }) });
256
+ expect(after).toMatchObject([{ code: null, seconds: 0 }]);
257
+ let called = false;
258
+ await planTerragruntWave({ dir, units: ["live/a"], workDir: "w2", provisional: true, exec, onCommand: () => void (called = true) });
259
+ expect(called).toBe(false);
260
+ });
261
+ });