@intentius/chant-lexicon-terraform 0.124.86 → 0.124.88

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 (72) 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-timings.d.ts +249 -0
  13. package/dist/engine-timings.d.ts.map +1 -0
  14. package/dist/engine-timings.js +569 -0
  15. package/dist/integrity.json +2 -2
  16. package/dist/live-roots.d.ts +93 -0
  17. package/dist/live-roots.d.ts.map +1 -0
  18. package/dist/live-roots.js +206 -0
  19. package/dist/manifest.json +1 -1
  20. package/dist/migration-history.d.ts +105 -0
  21. package/dist/migration-history.d.ts.map +1 -0
  22. package/dist/migration-history.js +159 -0
  23. package/dist/module-catalog/index.d.ts +1 -0
  24. package/dist/module-catalog/index.d.ts.map +1 -1
  25. package/dist/module-catalog/index.js +3 -1
  26. package/dist/op/activities/live-detect.d.ts +15 -0
  27. package/dist/op/activities/live-detect.d.ts.map +1 -1
  28. package/dist/op/activities/live-detect.js +94 -0
  29. package/dist/op/activities/terraform.d.ts +1 -65
  30. package/dist/op/activities/terraform.d.ts.map +1 -1
  31. package/dist/op/activities/terraform.js +4 -54
  32. package/dist/op/command-hook.d.ts +88 -0
  33. package/dist/op/command-hook.d.ts.map +1 -0
  34. package/dist/op/command-hook.js +115 -0
  35. package/dist/registry/index.d.ts +1 -0
  36. package/dist/registry/index.d.ts.map +1 -1
  37. package/dist/registry/index.js +1 -0
  38. package/dist/state/exec.d.ts +23 -0
  39. package/dist/state/exec.d.ts.map +1 -1
  40. package/dist/state/exec.js +38 -0
  41. package/dist/state-ops.d.ts.map +1 -1
  42. package/dist/state-ops.js +3 -1
  43. package/dist/terragrunt/index.d.ts +3 -1
  44. package/dist/terragrunt/index.d.ts.map +1 -1
  45. package/dist/terragrunt/index.js +3 -1
  46. package/dist/terragrunt/place.d.ts +27 -0
  47. package/dist/terragrunt/place.d.ts.map +1 -0
  48. package/dist/terragrunt/place.js +52 -0
  49. package/package.json +2 -2
  50. package/src/action-ops.ts +3 -1
  51. package/src/chant-floors.ts +32 -0
  52. package/src/components/capability-plugin.ts +27 -6
  53. package/src/components/compose-group.test.ts +29 -0
  54. package/src/components/compose-group.ts +12 -5
  55. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  56. package/src/engine-timings.test.ts +203 -0
  57. package/src/engine-timings.ts +718 -0
  58. package/src/live-roots.test.ts +80 -0
  59. package/src/live-roots.ts +244 -0
  60. package/src/migration-history.test.ts +83 -0
  61. package/src/migration-history.ts +199 -0
  62. package/src/module-catalog/index.ts +4 -1
  63. package/src/op/activities/live-detect.ts +87 -0
  64. package/src/op/activities/terraform.ts +12 -111
  65. package/src/op/command-hook.ts +182 -0
  66. package/src/registry/index.ts +1 -0
  67. package/src/state/engine-env.test.ts +18 -0
  68. package/src/state/exec.ts +38 -0
  69. package/src/state-ops.ts +3 -1
  70. package/src/terragrunt/index.ts +3 -1
  71. package/src/terragrunt/place.test.ts +42 -0
  72. package/src/terragrunt/place.ts +75 -0
@@ -2,7 +2,8 @@
2
2
  * Terragrunt units as roots (#3414). `./units`, `./wave` and `./mocks` are pure and
3
3
  * bundle without TypeScript; `./run` spawns `terragrunt`. `./affected` picks
4
4
  * the units a git range touches (#3415). `./capability` is `terragrunt-apply`,
5
- * the units as an op wave's step (#4842).
5
+ * the units as an op wave's step (#4842). `./place` is where a unit's binary runs
6
+ * as Terragrunt prepares it (#4910).
6
7
  */
7
8
  export * from "./units.js";
8
9
  export * from "./wave.js";
@@ -10,3 +11,4 @@ export * from "./mocks.js";
10
11
  export * from "./run.js";
11
12
  export * from "./affected.js";
12
13
  export * from "./capability.js";
14
+ export * from "./place.js";
@@ -0,0 +1,27 @@
1
+ import { type TerragruntExec } from "./run.js";
2
+ /** Where a unit's binary runs: its directory, and the job's environment with what Terragrunt adds. */
3
+ export interface UnitPlace {
4
+ dir: string;
5
+ env: NodeJS.ProcessEnv;
6
+ }
7
+ /** A unit Terragrunt could not prepare. */
8
+ export declare class UnitPlaceError extends Error {
9
+ constructor(message: string);
10
+ }
11
+ export interface UnitPlaceInput {
12
+ /** The directory Terragrunt runs in; `unit` is relative to it. */
13
+ projectDir: string;
14
+ unit: string;
15
+ /** The binary Terragrunt calls through the wrapper. */
16
+ binary: string;
17
+ env: NodeJS.ProcessEnv;
18
+ /** A directory of the caller's, which the wrapper and its record go under. */
19
+ work: string;
20
+ /** The `terragrunt` executable. Default `terragrunt` on `PATH`. */
21
+ terragrunt?: string;
22
+ /** How Terragrunt runs. Default {@link defaultTerragruntExec}. */
23
+ exec?: TerragruntExec;
24
+ }
25
+ /** The unit's place, as Terragrunt prepares it. Throws {@link UnitPlaceError} when its init fails or never runs the binary. */
26
+ export declare function terragruntUnitPlace(input: UnitPlaceInput): Promise<UnitPlace>;
27
+ //# sourceMappingURL=place.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../../src/terragrunt/place.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnE,sGAAsG;AACtG,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,2CAA2C;AAC3C,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAKD,+HAA+H;AAC/H,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAmBnF"}
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Where a Terragrunt unit's binary runs (chant#4910): its working directory
3
+ * and environment as Terragrunt prepares them, so a reader or writer of the
4
+ * unit's state (a state migration, an export, an ephemeral environment) runs
5
+ * the binary there as for a plain root.
6
+ *
7
+ * `terragrunt run -- init` in the unit, with `TG_TF_PATH` a wrapper that
8
+ * records the directory and the environment Terragrunt runs the binary in
9
+ * (its working directory, in Terragrunt's cache when the unit names a
10
+ * source, with backend.tf and provider.tf generated, and its inputs as
11
+ * `TF_VAR_` variables) and then runs the binary. The wrapper records with
12
+ * the running Node (`process.execPath`), so it needs nothing on `PATH`.
13
+ *
14
+ * Lifted from terragucci's `unitPlace` (migrate.ts), so terragucci deletes
15
+ * its copy.
16
+ */
17
+ import { chmodSync, existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
18
+ import { basename, join } from "node:path";
19
+ import { defaultTerragruntExec } from "./run.js";
20
+ /** A unit Terragrunt could not prepare. */
21
+ export class UnitPlaceError extends Error {
22
+ constructor(message) {
23
+ super(message);
24
+ this.name = "UnitPlaceError";
25
+ }
26
+ }
27
+ /** The variables of the wrapper's own run that are not Terragrunt's additions. */
28
+ const SHELL_VARS = new Set(["TG_TF_PATH", "PWD", "OLDPWD", "SHLVL", "_"]);
29
+ /** The unit's place, as Terragrunt prepares it. Throws {@link UnitPlaceError} when its init fails or never runs the binary. */
30
+ export async function terragruntUnitPlace(input) {
31
+ const { unit, binary, env } = input;
32
+ const capture = mkdtempSync(join(input.work, "unit-"));
33
+ const file = join(capture, "place.json");
34
+ const wrapper = join(capture, basename(binary) || "tofu");
35
+ const q = (x) => `'${x.replace(/'/g, `'\\''`)}'`;
36
+ const record = `require("fs").writeFileSync(process.argv[1], JSON.stringify({ dir: process.cwd(), env: process.env }))`;
37
+ writeFileSync(wrapper, `#!/bin/sh\n${q(process.execPath)} -e ${q(record)} ${q(file)}\nexec ${q(binary)} "$@"\n`);
38
+ chmodSync(wrapper, 0o755);
39
+ const run = await (input.exec ?? defaultTerragruntExec)(input.terragrunt ?? "terragrunt", ["run", "--non-interactive", "--no-color", "--working-dir", unit, "--", "init", "-input=false", "-no-color"], {
40
+ cwd: input.projectDir,
41
+ env: { ...env, TG_TF_PATH: wrapper, TG_NON_INTERACTIVE: "true" },
42
+ });
43
+ if (run.code !== 0)
44
+ throw new UnitPlaceError(`terragrunt could not prepare ${unit} (init failed): ${lastLines(run.stderr || run.stdout)}`);
45
+ if (!existsSync(file))
46
+ throw new UnitPlaceError(`terragrunt prepared ${unit} without running ${binary}, so where it runs is not known`);
47
+ const got = JSON.parse(readFileSync(file, "utf-8"));
48
+ // The binary's own variables from Terragrunt: the unit's inputs, and any credentials an iam_role gave it.
49
+ const added = Object.fromEntries(Object.entries(got.env).filter(([k, v]) => env[k] !== v && !SHELL_VARS.has(k)));
50
+ return { dir: got.dir, env: { ...env, ...added } };
51
+ }
52
+ const lastLines = (s, n = 4) => s.trim().split("\n").slice(-n).join(" ").slice(0, 400);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant-lexicon-terraform",
3
- "version": "0.124.86",
3
+ "version": "0.124.88",
4
4
  "type": "module",
5
5
  "files": [
6
6
  "src/",
@@ -93,7 +93,7 @@
93
93
  "access": "public"
94
94
  },
95
95
  "peerDependencies": {
96
- "@intentius/chant": "^0.124.86",
96
+ "@intentius/chant": "^0.124.88",
97
97
  "zod": "^4.3.6"
98
98
  },
99
99
  "description": "terraform lexicon for chant, existing Terraform root modules as declarable entities",
package/src/action-ops.ts CHANGED
@@ -48,6 +48,7 @@ import { terraformChangeSetPart } from "./change-set";
48
48
  import { DEFAULT_LOCK_TIMEOUT, lockTimeoutArgs } from "./lock-timeout";
49
49
  import { lastLines, runBinary, type BinaryExec } from "./state/exec";
50
50
  import { gatedStateOp, StateOpError, StateOpWaitingError, type GatedRequestLedger } from "./state-ops";
51
+ import { actorFromEnv } from "@intentius/chant/actor";
51
52
 
52
53
  /** The op an action's request waits at. */
53
54
  export const ACTION_OP = "tf-action";
@@ -323,7 +324,8 @@ export interface ActionStepInput {
323
324
  lockTimeout?: string | false;
324
325
  }
325
326
 
326
- const actorOf = (env: NodeJS.ProcessEnv): string => env.GITHUB_ACTOR || env.GITLAB_USER_LOGIN || env.USER || env.USERNAME || "unknown";
327
+ /** Who asks when the caller names nobody: core's actor fallback (#4911). */
328
+ const actorOf = (env: NodeJS.ProcessEnv): string => actorFromEnv(env);
327
329
 
328
330
  function stepInvoke(input: ActionStepInput): InvokeActionInput {
329
331
  const cwd = input.cwd ?? process.cwd();
@@ -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,203 @@
1
+ /**
2
+ * Per-root engine timings (chant#4887): `engineTimings()`'s hook, passed as
3
+ * `terraformApplyCapabilityWith({ onCommand })`, times each root's commands
4
+ * and collects the spans the engine sends to its loopback receiver, read into
5
+ * per-root plan and apply seconds, span counts and lock waits. A plain wave
6
+ * runs through core's `runOpWave` with a fake `terraform` on `PATH`, a Node
7
+ * script that sends OTLP/JSON spans where the variables point it; a composed
8
+ * group's commands run through `hookedBinaryExec` with a fake exec. Nothing
9
+ * reaches a cloud or a collector off the machine.
10
+ */
11
+ import { chmodSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
12
+ import { tmpdir } from "node:os";
13
+ import { join } from "node:path";
14
+ import { afterEach, describe, expect, test, vi } from "vitest";
15
+ import { CapabilityRegistry, type Capability } from "@intentius/chant/components/capability";
16
+ import { memoryGateLedgerPort, runOpWave, type OpWavesSpec } from "@intentius/chant/op";
17
+ import { terraformApplyCapabilityWith } from "./components/capability-plugin";
18
+ import { decodeTracesJson, ENGINE_RUN_HEADER, engineTimings, rootTimings, SpanReceiver, type CollectedSpan } from "./engine-timings";
19
+ import { hookedBinaryExec, withTerraformCommandHook } from "./op/command-hook";
20
+ import type { BinaryExec } from "./state/exec";
21
+
22
+ afterEach(() => vi.unstubAllEnvs());
23
+
24
+ /** OTLP/JSON for spans of `ms` milliseconds each. */
25
+ const otlp = (spans: Array<{ name: string; ms: number; attributes?: Record<string, string | number> }>) => ({
26
+ resourceSpans: [
27
+ {
28
+ scopeSpans: [
29
+ {
30
+ spans: spans.map((s, i) => ({
31
+ spanId: `s${i}`,
32
+ name: s.name,
33
+ startTimeUnixNano: "1000000000",
34
+ endTimeUnixNano: String(1_000_000_000 + s.ms * 1_000_000),
35
+ attributes: Object.entries(s.attributes ?? {}).map(([key, v]) => ({ key, value: typeof v === "number" ? { intValue: String(v) } : { stringValue: v } })),
36
+ })),
37
+ },
38
+ ],
39
+ },
40
+ ],
41
+ });
42
+
43
+ describe("reading the engine's spans", () => {
44
+ test("a root's resources, provider calls and lock waits come from its spans", () => {
45
+ const spans: CollectedSpan[] = decodeTracesJson(
46
+ otlp([
47
+ { name: "Plan resource instance changes", ms: 120, attributes: { "opentofu.resource_instance.address": "aws_sqs_queue.jobs", "opentofu.resource.type": "aws_sqs_queue" } },
48
+ { name: "State lock wait", ms: 2500, attributes: { "opentofu.state.backend": "s3", "opentofu.state.lock.operation": "plan", "opentofu.state.lock.attempts": 3 } },
49
+ { name: "tfplugin5.Provider/PlanResourceChange", ms: 40 },
50
+ ]),
51
+ );
52
+ const t = rootTimings(spans, { binary: "tofu", seconds: 4, planSeconds: 3 });
53
+ expect(t).toMatchObject({ seconds: 4, plan_seconds: 3, spans: 3, detail: "resources" });
54
+ expect(t.resources).toEqual([{ address: "aws_sqs_queue.jobs", type: "aws_sqs_queue", ms: 120 }]);
55
+ expect(t.lock_waits).toEqual([{ backend: "s3", operation: "plan", attempts: 3, ms: 2500 }]);
56
+ expect(t.provider_calls).toEqual([{ method: "PlanResourceChange", ms: 40 }]);
57
+ });
58
+
59
+ test("the receiver keeps a batch under the key its exporter named, and refuses one with no token", async () => {
60
+ const r = new SpanReceiver();
61
+ expect(await r.listen()).toBeUndefined();
62
+ const vars = r.exporter("roots/a\u0000plan");
63
+ const token = vars.OTEL_EXPORTER_OTLP_TRACES_HEADERS!.split("=")[1]!;
64
+ const post = (headers: Record<string, string>) =>
65
+ fetch(vars.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT!, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(otlp([{ name: "State lock wait", ms: 10 }])) });
66
+ expect((await post({ [ENGINE_RUN_HEADER]: token })).status).toBe(200);
67
+ expect((await post({})).status).toBe(401);
68
+ expect(r.spansOf("roots/a\u0000plan").map((s) => s.name)).toEqual(["State lock wait"]);
69
+ expect(await r.close()).toEqual([]);
70
+ });
71
+ });
72
+
73
+ /** A fake `terraform`: a Node script that answers each command and sends a plan's and an apply's spans where the variables point. */
74
+ const FAKE = (node: string) => `#!${node}
75
+ const fs = require("fs");
76
+ const [cmd, ...rest] = process.argv.slice(2);
77
+ const root = process.cwd().split("/").pop();
78
+ const send = async (spans) => {
79
+ const url = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
80
+ if (!url) return;
81
+ const [k, v] = (process.env.OTEL_EXPORTER_OTLP_TRACES_HEADERS || "").split("=");
82
+ const span = (s, i) => ({ spanId: cmd + i, name: s[0], startTimeUnixNano: "1000000000", endTimeUnixNano: String(1000000000 + s[1] * 1000000), attributes: Object.entries(s[2] || {}).map(([key, x]) => ({ key, value: typeof x === "number" ? { intValue: String(x) } : { stringValue: x } })) });
83
+ await fetch(url, { method: "POST", headers: { "content-type": "application/json", [k]: v }, body: JSON.stringify({ resourceSpans: [{ scopeSpans: [{ spans: spans.map(span) }] }] }) });
84
+ };
85
+ (async () => {
86
+ if (cmd === "plan") {
87
+ const out = rest.find((a) => a.startsWith("-out=")).slice(5);
88
+ fs.writeFileSync(out, "plan");
89
+ await send([["State lock wait", root === "a" ? 300 : 0, { "opentofu.state.lock.attempts": 2 }], ["Plan resource instance changes", 50, { "opentofu.resource_instance.address": "terraform_data." + root }]].filter((s) => s[1] > 0));
90
+ await new Promise((r) => setTimeout(r, 30));
91
+ process.exit(2);
92
+ }
93
+ if (cmd === "apply") {
94
+ await send([["Apply resource instance changes", 80, { "opentofu.resource_instance.address": "terraform_data." + root }]]);
95
+ await new Promise((r) => setTimeout(r, 30));
96
+ }
97
+ if (cmd === "show") console.log(JSON.stringify({ format_version: "1.2", resource_changes: [{ address: "terraform_data." + root, mode: "managed", type: "terraform_data", name: root, change: { actions: ["create"], before: null, after: {} } }] }));
98
+ if (cmd === "output") console.log('{"id":{"value":"x"}}');
99
+ process.exit(0);
100
+ })();
101
+ `;
102
+
103
+ function project(): string {
104
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-tf-timings-")));
105
+ mkdirSync(join(dir, "bin"));
106
+ writeFileSync(join(dir, "bin", "terraform"), FAKE(process.execPath));
107
+ chmodSync(join(dir, "bin", "terraform"), 0o755);
108
+ vi.stubEnv("PATH", `${join(dir, "bin")}:${process.env.PATH ?? ""}`);
109
+ vi.stubEnv("TF_PLUGIN_CACHE_DIR", "");
110
+ for (const r of ["a", "b"]) {
111
+ mkdirSync(join(dir, "roots", r), { recursive: true });
112
+ writeFileSync(join(dir, "roots", r, "main.tf"), "");
113
+ }
114
+ writeFileSync(join(dir, "chant.config.json"), JSON.stringify({ lexicons: ["terraform"], terraform: { binary: "terraform" } }));
115
+ return dir;
116
+ }
117
+
118
+ const SPEC = {
119
+ name: "tf-apply",
120
+ op: "tf-apply",
121
+ gateName: "wave-{k}",
122
+ parallelism: 2,
123
+ step: { kind: "terraform-apply", root: "{target}", dir: "{target}", lockTimeout: false },
124
+ waves: [{ name: "wave-1", gate: "never", runs: [{ target: "roots/a" }, { target: "roots/b" }] }],
125
+ } as unknown as OpWavesSpec;
126
+
127
+ describe("engineTimings (chant#4887)", () => {
128
+ test("a plain wave's roots get their plan and apply seconds, span counts and lock waits", async () => {
129
+ const dir = project();
130
+ const timings = await engineTimings();
131
+ expect(timings.problem).toBeUndefined();
132
+ const result = await runOpWave({
133
+ spec: SPEC,
134
+ specFile: "waves.json",
135
+ wave: 1,
136
+ cwd: dir,
137
+ show: () => ({ sha: "c".repeat(40), text: JSON.stringify(SPEC) }),
138
+ gates: memoryGateLedgerPort(),
139
+ capabilities: new CapabilityRegistry().register(terraformApplyCapabilityWith({ onCommand: timings.onCommand }) as unknown as Capability<never, unknown>),
140
+ log: () => {},
141
+ });
142
+ expect(result.exitCode).toBe(0);
143
+ await timings.close();
144
+ const roots = timings.roots();
145
+ expect(Object.keys(roots)).toEqual(["roots/a", "roots/b"]);
146
+ const a = roots["roots/a"]!;
147
+ expect(a.commands.map((c) => `${c.method} ${c.command}`)).toEqual(["plan init", "plan plan", "plan show", "run apply", "run output"]);
148
+ expect(a.plan_seconds).toBeGreaterThanOrEqual(0.02);
149
+ expect(a.apply_seconds).toBeGreaterThanOrEqual(0.02);
150
+ expect(a.seconds).toBeGreaterThanOrEqual(a.plan_seconds! + a.apply_seconds!);
151
+ expect(a.spans).toBe(3);
152
+ expect(a.lock_waits).toEqual([{ attempts: 2, ms: 300 }]);
153
+ expect(a.resources.map((r) => r.address)).toEqual(["terraform_data.a", "terraform_data.a"]);
154
+ expect(roots["roots/b"]).toMatchObject({ spans: 2, lock_waits: [] });
155
+ expect(timings.run().roots.map((r) => r.root).sort()).toEqual(["roots/a", "roots/b"]);
156
+ });
157
+
158
+ test("a composed group's commands time every member, and the run counts its resources once", async () => {
159
+ const timings = await engineTimings({ noSpans: true });
160
+ const fake: BinaryExec = async (_bin, args) => {
161
+ await new Promise((r) => setTimeout(r, 10));
162
+ return { code: 0, stdout: args[0] === "plan" ? "Plan: 2 to add" : "", out: "" };
163
+ };
164
+ const exec = hookedBinaryExec(fake);
165
+ const seen: string[] = [];
166
+ const hook = timings.onCommand;
167
+ const watched: typeof hook = async (c) => {
168
+ seen.push(`${c.method} ${c.name} ${(c.members ?? []).join(",")}`);
169
+ return hook(c);
170
+ };
171
+ await withTerraformCommandHook(watched, { root: "roots/a", members: ["roots/a", "roots/b"], method: "plan" }, async () => {
172
+ await exec("tofu", ["init", "-input=false"], "/w/.chant-compose", {});
173
+ await exec("tofu", ["plan", "-out=/w/composed.tfplan"], "/w/.chant-compose", {});
174
+ });
175
+ await withTerraformCommandHook(watched, { root: "roots/a", members: ["roots/a", "roots/b"], method: "run" }, async () => {
176
+ await exec("tofu", ["apply", "-json", "/w/composed.tfplan"], "/w/.chant-compose", {});
177
+ });
178
+ expect(seen).toEqual(["plan init roots/a,roots/b", "plan plan roots/a,roots/b", "run apply roots/a,roots/b"]);
179
+ const roots = timings.roots();
180
+ for (const r of ["roots/a", "roots/b"]) {
181
+ expect(roots[r]!.composed).toEqual(["roots/a", "roots/b"]);
182
+ expect(roots[r]!.plan_seconds).toBeGreaterThan(0);
183
+ expect(roots[r]!.apply_seconds).toBeGreaterThan(0);
184
+ expect(roots[r]!.commands.map((c) => c.command)).toEqual(["init", "plan", "apply"]);
185
+ }
186
+ });
187
+
188
+ test("the product's own hook runs first: its variables reach the command under the receiver's, and its after runs", async () => {
189
+ const afters: string[] = [];
190
+ const got: Array<Record<string, string | undefined>> = [];
191
+ const fake: BinaryExec = async (_bin, _args, _dir, env) => {
192
+ got.push({ TRACEPARENT: env.TRACEPARENT, endpoint: env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT });
193
+ return { code: 0, stdout: "", out: "" };
194
+ };
195
+ const timings = await engineTimings({ inner: () => ({ env: { TRACEPARENT: "00-abc-def-01" }, after: (r) => void afters.push(String(r.code)) }) });
196
+ await withTerraformCommandHook(timings.onCommand, { root: "roots/a", method: "plan" }, () => hookedBinaryExec(fake)("tofu", ["plan"], "/w", {}));
197
+ expect(got[0]!.TRACEPARENT).toBe("00-abc-def-01");
198
+ expect(got[0]!.endpoint).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/v1\/traces$/);
199
+ expect(afters).toEqual(["0"]);
200
+ expect(timings.root("roots/a")!.commands).toEqual([{ command: "plan", method: "plan", seconds: expect.any(Number), code: 0 }]);
201
+ await timings.close();
202
+ });
203
+ });