@intentius/chant-lexicon-terraform 0.124.56 → 0.124.58

package/src/components/capability-plugin.test.ts

@@ -208,7 +208,7 @@ describe("terraform-apply on a choudoufu root in a gated wave (#3459)", () => {
 
 describe("terraform-apply", () => {
   test("the plugin contributes it", () => {
-    expect(terraformCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["terraform-apply", "terraform-state-unlock", "terraform-state-push", "terraform-copy"]);
+    expect(terraformCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["terraform-apply", "terraform-state-unlock", "terraform-state-push", "terraform-copy", "terraform-action"]);
   });
 
   test("plan inits and plans the root, with its vars, and names the root as the member", async () => {

package/src/components/capability-plugin.ts

@@ -153,7 +153,7 @@ import { terraformPlanMoved } from "../exit-codes";
 import { terraformPlanShape } from "../plan-shape";
 import { plannerForBinary, terraformChangeSetPart } from "../change-set";
 import { terraformDefaultLockGrain, terraformLockGrainRefusal, terraformLockRows, terraformLockRowsFromPart } from "../lock-rows";
-import type { LockRow } from "@intentius/chant/lifecycle/lock-rows";
+import { rootRowKey, type LockRow } from "@intentius/chant/lifecycle/lock-rows";
 import type { TerraformConfig } from "../config";
 import { rootTexts } from "../compose/hcl";
 import { declaredVariables } from "../compose/root";
@@ -165,6 +165,7 @@ import { DEFAULT_LOCK_TIMEOUT, isLockTimeout } from "../lock-timeout";
 import { conePlanDigest, type PlanCone } from "../cone";
 import { fillStateReads, stateReadsProblems, waitingReadsReason, type TerraformStateRead } from "../state-reads";
 import { terraformStateOpCapabilities } from "../state-ops";
+import { terraformActionCapability } from "../action-ops";
 
 /** The `terraform-apply` step's input. */
 export interface TerraformApplyStepInput {
@@ -610,6 +611,11 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
     const binary = (await rootDir(input).catch(() => undefined))?.binary;
     return terraformLockGrainRefusal(grain, await plannerOf(input, plan), binary);
   },
+  // The ruling for ci-products (2026-10-28): a Terraform, tofu or Terragrunt root waits for its root row on the ledger in place of
+  // the backend's lock. A choudoufu root stays on the resource grain and never asks for this row.
+  targetLockRow(input) {
+    return typeof input?.root === "string" && input.root !== "" ? { key: rootRowKey(input.root), target: input.root, address: input.root } : undefined;
+  },
   lockRows(input, plan) {
     const kept = (plan.artifact as { lockRows?: LockRow[] } | undefined)?.lockRows;
     if (Array.isArray(kept)) return kept;
@@ -659,6 +665,8 @@ export const TERRAFORM_VERB_FAMILIES = {
   // #4618: the binary runs outside waves, each a fixed operation; the two that change state on their own run under a gated request.
   state: ["terraform-state-unlock", "terraform-state-push"],
   copy: ["terraform-copy"],
+  // #4653: one action block invoked on its own, under a gated request.
+  action: ["terraform-action"],
 } as const;
 
 export const terraformCapabilityPlugin: CapabilityPlugin = {
@@ -667,7 +675,7 @@ export const terraformCapabilityPlugin: CapabilityPlugin = {
     return ownPackageVersion(import.meta.url);
   },
   capabilities(): Array<Capability<never, unknown>> {
-    return [terraformApplyCapability as Capability<never, unknown>, ...terraformStateOpCapabilities.map((c) => c as unknown as Capability<never, unknown>)];
+    return [terraformApplyCapability as Capability<never, unknown>, ...terraformStateOpCapabilities.map((c) => c as unknown as Capability<never, unknown>), terraformActionCapability as unknown as Capability<never, unknown>];
   },
   families(): Record<string, readonly string[]> {
     return TERRAFORM_VERB_FAMILIES;

package/src/lock-rows.test.ts

@@ -6,6 +6,7 @@
 import { describe, expect, test } from "vitest";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
 import { terraformDefaultLockGrain, terraformLockGrainRefusal, terraformLockRows, terraformLockRowsFromPart } from "./lock-rows";
+import { terraformApplyCapability } from "./components/capability-plugin";
 
 const plan = {
   resource_changes: [
@@ -68,3 +69,10 @@ describe("the grain", () => {
     expect(terraformLockGrainRefusal("repo", "tofu")).toBeUndefined();
   });
 });
+
+describe("the ledger lock (ruling for ci-products 2026-10-28)", () => {
+  test("a root's target row is `root <root>`, which a Terraform, tofu or Terragrunt apply waits for", async () => {
+    expect(await terraformApplyCapability.targetLockRow!({ root: "stacks/net" } as never)).toEqual({ key: "root stacks/net", target: "stacks/net", address: "stacks/net" });
+    expect(await terraformApplyCapability.targetLockRow!({ root: "" } as never)).toBeUndefined();
+  });
+});

package/src/pin/scan.ts

@@ -303,7 +303,18 @@ export function unescapeHcl(raw: string): string {
   return out;
 }
 
-/** Write a value as the content of an HCL string literal. */
+const CONTROL_ESCAPES: Record<string, string> = { "\n": "\\n", "\r": "\\r", "\t": "\\t" };
+
+/**
+ * Write a value as the content of an HCL string literal: `\` and `"`
+ * escaped, a control character as `\n`, `\r`, `\t` or `\uNNNN`, and `${`
+ * and `%{` doubled so nothing in it is a template. The replacements are
+ * functions because a replacement string reads `$$` as one `$`.
+ */
 export function escapeHcl(value: string): string {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\$\{/g, "$${").replace(/%\{/g, "%%{");
+  return value
+    .replace(/[\\"]/g, (c) => `\\${c}`)
+    .replace(/[\u0000-\u001f\u007f]/g, (c) => CONTROL_ESCAPES[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`)
+    .replace(/\$\{/g, () => "$${")
+    .replace(/%\{/g, () => "%%{");
 }

package/src/state-ops.ts

@@ -259,6 +259,11 @@ export interface GatedStateOpInput {
    * the operation with that reason, and the approval is not spent.
    */
   beforeSpend?: () => Promise<string | undefined>;
+  /**
+   * The flat facts of a failed act's finished line, beside its `error`, such
+   * as the binary's exit code and last lines (#4653). Default none.
+   */
+  failedDetail?: (error: Error) => Record<string, string | number | boolean>;
 }
 
 /** How a gated operation ended. */
@@ -324,7 +329,7 @@ export async function gatedStateOp<T>(
     return { status: "done", digest, request: asked.request, approvedBy, output, recorded: await finish("applied", detail) };
   } catch (e) {
     const error = e instanceof Error ? e : new Error(String(e));
-    return { status: "failed", digest, request: asked.request, approvedBy, error, recorded: await finish("failed", { error: error.message.slice(0, 400) }) };
+    return { status: "failed", digest, request: asked.request, approvedBy, error, recorded: await finish("failed", { ...(input.failedDetail?.(error) ?? {}), error: error.message.slice(0, 400) }) };
   }
 }
 

package/src/template/__fixtures__/app-root.golden.tf

@@ -0,0 +1,25 @@
+# The app orders, from the template acme/orders/aws. Written by chant from a template request; a rollout moves the version.
+
+module "app" {
+  source  = "registry.example.com/acme/orders/aws"
+  version = "1.2.0"
+
+  bucket_name = "orders-data"
+  replicas    = 3
+  public      = true
+  readers     = ["svc-a", "svc-b"]
+  tags = {
+    cost-center = "42"
+    team        = "payments"
+  }
+  retention_days = 30
+}
+
+output "app_endpoint" {
+  value = module.app.endpoint
+}
+
+output "app_bucket_arn" {
+  value       = module.app.bucket_arn
+  description = "The bucket's ARN."
+}

package/src/template/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@intentius/chant-lexicon-terraform/template` (#4652): a template request
+ * (`@intentius/chant/template-request`) as Terraform files, an app's new
+ * root or an add-on's module call in it. Nothing here reads the disk.
+ */
+
+export {
+  renderAppRoot,
+  renderAddonCall,
+  terraformInputType,
+  addonFile,
+  TemplateRenderError,
+  APP_MODULE_NAME,
+  APP_OUTPUT_PREFIX,
+  APP_ROOT_FILE,
+} from "./render";
+export type { RenderAppRootOptions, RenderAddonCallOptions, RenderedFile, TemplateOutput, TemplateRenderErrorCode } from "./render";

package/src/template/render.test.ts

@@ -0,0 +1,230 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+import { loadHcl2json, parseTerraformDir } from "@intentius/chant/terraform/parse";
+import { makeTemplateRequest, type TemplateInput, type TemplateRequest } from "@intentius/chant/template-request";
+import { editPins } from "../pin/edit";
+import { scanBlocks } from "../pin/scan";
+import { readModulePin } from "../pin/source";
+import { renderAddonCall, renderAppRoot, terraformInputType, TemplateRenderError } from "./index";
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+const GOLDEN = join(FIXTURES, "app-root.golden.tf");
+const SOURCE = "registry.example.com/acme/orders/aws";
+const CACHE = "registry.example.com/acme/cache/aws";
+
+const parser = await loadHcl2json();
+
+const APP_INPUTS: TemplateInput[] = [
+  { name: "bucket_name", kind: "string" },
+  { name: "replicas", kind: "number" },
+  { name: "public", kind: "bool", default: false },
+  { name: "readers", kind: "list", of: "string" },
+  { name: "tags", kind: "map", of: "string" },
+  { name: "retention_days", kind: "number", default: 30 },
+  { name: "note", kind: "string", required: false },
+];
+
+const appRequest = (inputs: Record<string, unknown> = {}): TemplateRequest =>
+  makeTemplateRequest({
+    kind: "app",
+    template: "acme/orders/aws",
+    version: "1.2.0",
+    app: "orders",
+    inputs: {
+      // Out of the template's order on purpose: the file follows the template.
+      tags: { team: "payments", "cost-center": "42" },
+      readers: ["svc-a", "svc-b"],
+      public: true,
+      replicas: 3,
+      bucket_name: "orders-data",
+      ...inputs,
+    },
+    requestedBy: "alice",
+    via: "form",
+  });
+
+const OUTPUTS = [{ name: "endpoint" }, { name: "bucket_arn", description: "The bucket's ARN." }];
+
+const renderApp = (request = appRequest()) => renderAppRoot({ request, source: SOURCE, inputs: APP_INPUTS, outputs: OUTPUTS });
+
+const addonRequest = (inputs: Record<string, unknown>): TemplateRequest =>
+  makeTemplateRequest({ kind: "addon", template: "acme/cache/aws", version: "2.0.1", app: "orders", addon: "cache", inputs, requestedBy: "bob", via: "cli" });
+
+const ADDON_INPUTS: TemplateInput[] = [
+  { name: "endpoint", kind: "string" },
+  { name: "size", kind: "number", default: 1 },
+];
+
+const renderAddon = (inputs: Record<string, unknown>, appOutputs: string[] = ["endpoint", "bucket_arn"]) =>
+  renderAddonCall({ request: addonRequest(inputs), source: CACHE, inputs: ADDON_INPUTS, appOutputs });
+
+const refusal = (fn: () => unknown): TemplateRenderError => {
+  try {
+    fn();
+  } catch (e) {
+    if (e instanceof TemplateRenderError) return e;
+    throw e;
+  }
+  throw new Error("expected a TemplateRenderError");
+};
+
+describe("renderAppRoot", () => {
+  test("a request with a string, a number, a bool, a list of strings and a map matches the golden file", () => {
+    const files = renderApp();
+    expect(files.map((f) => f.path)).toEqual(["main.tf"]);
+    expect(files[0]!.text).toBe(readFileSync(GOLDEN, "utf-8"));
+  });
+
+  test("the golden file parses with zero errors, into one module call and the re-exported outputs", async () => {
+    const tree = (await parser.parse("main.tf", readFileSync(GOLDEN, "utf-8"))) as { module?: Record<string, unknown>; output?: Record<string, unknown> };
+    expect(Object.keys(tree.module ?? {})).toEqual(["app"]);
+    expect(Object.keys(tree.output ?? {}).sort()).toEqual(["app_bucket_arn", "app_endpoint"]);
+    const graph = await parseTerraformDir(FIXTURES);
+    expect(graph).toBeDefined();
+  });
+
+  test("the version is read back as 1.2.0, and the pin editor moves it", async () => {
+    const [file] = renderApp();
+    const call = scanBlocks(file!.text, "main.tf").find((b) => b.type === "module" && b.labels[0] === "app")!;
+    const attr = (name: string) => call.attributes.find((a) => a.name === name)!.literal!.raw;
+    expect(readModulePin(attr("source"), attr("version"))).toEqual({ module: SOURCE, at: "version", pin: "1.2.0" });
+
+    const moved = await editPins(file!.text, "main.tf", { module: SOURCE, from: "1.2.0", to: "1.3.0" }, parser);
+    expect(moved.calls.map((c) => c.outcome)).toEqual(["moved"]);
+    expect(moved.content).toBe(file!.text.replace('version = "1.2.0"', 'version = "1.3.0"'));
+  });
+
+  test("the same request renders to the same bytes, whatever order its inputs and map keys came in", () => {
+    const a = renderApp();
+    const b = renderApp();
+    expect(b).toEqual(a);
+    const reordered = appRequest({ tags: { "cost-center": "42", team: "payments" } });
+    expect(renderApp(reordered)).toEqual(a);
+  });
+
+  test("an input the request leaves out takes the template's default, or is left to the module", () => {
+    const text = renderApp()[0]!.text;
+    expect(text).toContain("retention_days = 30\n");
+    expect(text).not.toContain("note");
+    expect(renderApp(appRequest({ note: "hi ${x}" }))[0]!.text).toContain('note           = "hi $${x}"\n');
+  });
+
+  test("a string with quotes, a backslash, a template and control characters reads back as itself", async () => {
+    const note = 'say "hi" \\ ${var.x} %{if} \n\r\t\u0001';
+    const text = renderApp(appRequest({ note }))[0]!.text;
+    expect(text).toContain('"say \\"hi\\" \\\\ $${var.x} %%{if} \\n\\r\\t\\u0001"');
+    const tree = (await parser.parse("main.tf", text)) as { module: { app: Array<{ note: string }> } };
+    // hcl2json hands a literal `${` back escaped, as Terraform's JSON syntax would write it.
+    expect(tree.module.app[0]!.note.replace(/\$\$\{/g, "${").replace(/%%\{/g, "%{")).toBe(note);
+  });
+
+  test("a sensitive input becomes a sensitive root variable of its Terraform type", async () => {
+    const inputs: TemplateInput[] = [{ name: "readers", kind: "list", of: "string" }, { name: "db_password", kind: "string", sensitive: true }];
+    const request = makeTemplateRequest({ kind: "app", template: "acme/orders/aws", version: "1.2.0", app: "orders", inputs: { readers: [] }, requestedBy: "a", via: "cli" });
+    const text = renderAppRoot({ request, source: SOURCE, inputs })[0]!.text;
+    expect(text).toContain('variable "app_db_password" {\n  type      = string\n  sensitive = true\n}\n');
+    expect(text).toContain("  readers     = []\n  db_password = var.app_db_password\n");
+    await parser.parse("main.tf", text);
+    expect(refusal(() => renderAppRoot({ request: { ...request, inputs: { readers: [], db_password: "x" } }, source: SOURCE, inputs })).code).toBe("sensitive-input");
+  });
+
+  test("objects and lists of maps open one line per entry, and still parse", async () => {
+    const inputs: TemplateInput[] = [{ name: "settings", kind: "object" }];
+    const request = makeTemplateRequest({
+      kind: "app",
+      template: "acme/orders/aws",
+      version: "1.2.0",
+      app: "orders",
+      inputs: { settings: { rules: [{ port: 80 }], empty: {}, "a b": null } },
+      requestedBy: "a",
+      via: "cli",
+    });
+    const text = renderAppRoot({ request, source: SOURCE, inputs })[0]!.text;
+    expect(text).toContain('  settings = {\n    "a b" = null\n    empty = {}\n    rules = [\n      {\n        port = 80\n      },\n    ]\n  }\n');
+    const tree = (await parser.parse("main.tf", text)) as { module: { app: Array<{ settings: unknown }> } };
+    expect(tree.module.app[0]!.settings).toEqual({ "a b": null, empty: {}, rules: [{ port: 80 }] });
+  });
+
+  test("refusals: wrong kind, a version that is not exact, unknown, missing and mistyped inputs", () => {
+    expect(refusal(() => renderAppRoot({ request: addonRequest({}), source: SOURCE, inputs: APP_INPUTS })).code).toBe("wrong-kind");
+    expect(refusal(() => renderApp({ ...appRequest(), version: "~> 1.2" })).code).toBe("not-a-version");
+    expect(refusal(() => renderApp({ ...appRequest(), version: `sha256:${"a".repeat(64)}` })).code).toBe("not-a-version");
+    const unknown = refusal(() => renderApp(appRequest({ colour: "red" })));
+    expect([unknown.code, unknown.subject]).toEqual(["unknown-input", "colour"]);
+    const { bucket_name: _b, ...rest } = appRequest().inputs;
+    const missing = refusal(() => renderApp({ ...appRequest(), inputs: rest }));
+    expect([missing.code, missing.subject]).toEqual(["missing-input", "bucket_name"]);
+    const typed = refusal(() => renderApp(appRequest({ replicas: "3" })));
+    expect([typed.code, typed.subject]).toEqual(["input-type", "replicas"]);
+    // An app root has no app module to reference yet.
+    expect(refusal(() => renderApp(appRequest({ replicas: "app.endpoint" }))).code).toBe("input-type");
+  });
+});
+
+describe("renderAddonCall", () => {
+  test("an input app.endpoint becomes module.app.endpoint in addon-<name>.tf", async () => {
+    const file = renderAddon({ endpoint: "app.endpoint" });
+    expect(file.path).toBe("addon-cache.tf");
+    expect(file.text).toBe(
+      [
+        "# The add-on cache of the app orders, from the template acme/cache/aws. Written by chant from a template request; a rollout moves the version.",
+        "",
+        'module "cache" {',
+        `  source  = "${CACHE}"`,
+        '  version = "2.0.1"',
+        "",
+        "  endpoint = module.app.endpoint",
+        "  size     = 1",
+        "}",
+        "",
+      ].join("\n"),
+    );
+    const tree = (await parser.parse("addon-cache.tf", file.text)) as { module: { cache: Array<{ endpoint: string }> } };
+    expect(tree.module.cache[0]!.endpoint).toBe("${module.app.endpoint}");
+  });
+
+  test("app.missing is refused with unknown-output naming missing", () => {
+    const e = refusal(() => renderAddon({ endpoint: "app.missing" }));
+    expect(e.code).toBe("unknown-output");
+    expect(e.subject).toBe("missing");
+    expect(e.message).toMatch(/^unknown-output: .*\bmissing\b/);
+  });
+
+  test("the app's outputs may be given as the catalog lists them", () => {
+    const file = renderAddonCall({ request: addonRequest({ endpoint: "app.endpoint", size: 2 }), source: CACHE, inputs: ADDON_INPUTS, appOutputs: [{ name: "endpoint", description: null, sensitive: false }] });
+    expect(file.text).toContain("  endpoint = module.app.endpoint\n  size     = 2\n");
+  });
+
+  test("a string that only looks like a reference stays a string", () => {
+    expect(renderAddon({ endpoint: "app.endpoint.extra" }).text).toContain('  endpoint = "app.endpoint.extra"\n');
+  });
+
+  test("the same add-on request renders to the same bytes", () => {
+    expect(renderAddon({ endpoint: "app.endpoint", size: 3 })).toEqual(renderAddon({ size: 3, endpoint: "app.endpoint" }));
+  });
+
+  test("refusals: an add-on named app, no add-on name, and a request for an app", () => {
+    expect(refusal(() => renderAddonCall({ request: { ...addonRequest({ endpoint: "x" }), addon: "app" }, source: CACHE, inputs: ADDON_INPUTS, appOutputs: [] })).code).toBe("bad-name");
+    const { addon: _a, ...noName } = addonRequest({ endpoint: "x" });
+    expect(refusal(() => renderAddonCall({ request: noName as TemplateRequest, source: CACHE, inputs: ADDON_INPUTS, appOutputs: [] })).code).toBe("bad-name");
+    expect(refusal(() => renderAddonCall({ request: appRequest(), source: CACHE, inputs: APP_INPUTS, appOutputs: [] })).code).toBe("wrong-kind");
+  });
+});
+
+describe("terraformInputType", () => {
+  test("each engine-neutral kind maps to a Terraform type", () => {
+    const rows: Array<[Pick<TemplateInput, "kind" | "of">, string]> = [
+      [{ kind: "string" }, "string"],
+      [{ kind: "number" }, "number"],
+      [{ kind: "bool" }, "bool"],
+      [{ kind: "list", of: "string" }, "list(string)"],
+      [{ kind: "list" }, "list(any)"],
+      [{ kind: "map", of: "number" }, "map(number)"],
+      [{ kind: "map" }, "map(any)"],
+      [{ kind: "object" }, "any"],
+    ];
+    for (const [input, type] of rows) expect(terraformInputType(input)).toBe(type);
+  });
+});