@flow-as-code/tf 0.1.0

package/src/emit.ts

@@ -0,0 +1,532 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The Terraform/OpenTofu emitter. FlowDoc in, HCL plus .tftpl out, per
+// docs/03-tf-emitter.md. One-way in v1: there is no HCL to FlowDoc direction.
+//
+// `emitTf` is pure: it takes documents and returns a path -> content map, so the
+// goldens in conformance/emit-tf compare bytes with no filesystem involved.
+// `writeTf` (write.ts) is the thin wrapper that puts them on disk.
+//
+// Verified provider arguments (checked 2026-08-31 against the provider docs and
+// against `tofu validate` with hashicorp/aws 6.62.0 and hashicorp/awscc 1.99.0,
+// see src/validate.test.ts):
+// https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/connect_contact_flow
+// https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/connect_contact_flow_module
+// https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/connect_contact_flow_module_version
+// https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/connect_contact_flow_module_alias
+
+import {
+  type FlowDoc,
+  PACKAGE_NAMES,
+  type RefEntry,
+  SLUG_PATTERN,
+  collectRefs,
+  parseToken,
+} from "@flow-as-code/core";
+import { type HclLine, arg, blank, block, comment, objectArg, quote, renderFile } from "./hcl.js";
+import { renderTemplate } from "./template.js";
+
+/**
+ * The oldest core version the emitted configuration promises to work on, per
+ * docs/03-tf-emitter.md ("emit nothing Terraform 1.8+/OpenTofu 1.7+ do not both
+ * support"). It lands in every `versions.tf.example` as `required_version`, and
+ * the emit-tf CI job is asserted to run the gated suite against it, so the
+ * promise and the thing that checks the promise cannot drift apart.
+ */
+export const CORE_VERSION_FLOOR = "1.7.0";
+
+/** Emission refused. Every problem found is listed, not just the first. */
+export class EmitTfError extends Error {
+  readonly problems: readonly string[];
+
+  constructor(problems: readonly string[]) {
+    super(`Cannot emit terraform:\n  - ${problems.join("\n  - ")}`);
+    this.name = "EmitTfError";
+    this.problems = problems;
+  }
+}
+
+export interface EmitTfOptions {
+  /**
+   * Reference to terraform address expression, for references this emitter
+   * cannot resolve from the document set itself. A key is a token
+   * (`${cdref:queue:front-desk}`), the token body (`queue:front-desk`,
+   * `module:survey@prod`), or the generated variable name
+   * (`queue_front_desk_arn`); the three are tried in that order. Values are HCL
+   * expressions such as `aws_connect_queue.front_desk.arn`, never literal ARNs.
+   * Entries matching no reference in the set are ignored.
+   */
+  addressMap?: Record<string, string>;
+  /**
+   * Expression for the `instance_id` argument. Defaults to
+   * `var.connect_instance_id`, in which case variables.tf declaring that
+   * variable is emitted too. Pass something else (`aws_connect_instance.main.id`)
+   * to wire the flows into an instance you already manage; no variables.tf is
+   * emitted then.
+   */
+  instanceIdExpression?: string;
+}
+
+export interface EmitTfResult {
+  /** Relative POSIX path to file content, insertion-ordered by sorted path. */
+  files: Record<string, string>;
+}
+
+/** Where a reference's address came from. */
+type RefSource = "set" | "map" | "missing";
+
+interface Resolved {
+  entry: RefEntry;
+  variable: string;
+  expression: string;
+  source: RefSource;
+  /** Address map key ignored because the document set resolves this itself. */
+  shadowed?: string;
+}
+
+const DEFAULT_INSTANCE_ID_EXPRESSION = "var.connect_instance_id";
+const INSTANCE_ID_VARIABLE = "connect_instance_id";
+
+const GENERATED_BY = [
+  `Generated by ${PACKAGE_NAMES.tf}. Do not edit by hand: edit the`,
+  "FlowDoc and re-emit. See docs/03-tf-emitter.md.",
+];
+
+/** Slug to HCL identifier: hyphens are the only character needing a change. */
+/**
+ * A slug as a Terraform identifier. Slugs may begin with a digit (@flow-as-code/core's
+ * SLUG_PATTERN allows it) but Terraform identifiers may not: OpenTofu rejects
+ * `resource "aws_connect_contact_flow" "2fa_line"` with "Invalid resource
+ * name", so a leading digit is prefixed. Deterministic and collision-free
+ * against other slugs, since no slug can contain an underscore.
+ */
+const ident = (slug: string): string => {
+  const underscored = slug.replaceAll("-", "_");
+  return /^[0-9]/.test(underscored) ? `_${underscored}` : underscored;
+};
+
+/** `<type>_<name>_arn`, with the module alias folded in. Stable by contract. */
+function variableName(entry: RefEntry): string {
+  const alias = entry.alias === undefined ? "" : `_${ident(entry.alias)}`;
+  return `${entry.type}_${ident(entry.name)}${alias}_arn`;
+}
+
+/** The bare identifier emitted when no address is known. Fails `validate`. */
+const placeholder = (variable: string): string =>
+  `TODO_MISSING_ADDRESS_${variable.replace(/_arn$/, "")}`;
+
+/** `queue:front-desk`, `module:survey@prod`: the token without its wrapper. */
+const refKey = (entry: RefEntry): string =>
+  `${entry.type}:${entry.name}${entry.alias === undefined ? "" : `@${entry.alias}`}`;
+
+const resourceType = (doc: FlowDoc): string =>
+  doc.kind === "module" ? "aws_connect_contact_flow_module" : "aws_connect_contact_flow";
+
+/**
+ * Name of the locals entry a document's content is rendered with. Documents
+ * that reference something this set emits get their own, because putting those
+ * addresses in the shared map would make the map depend on resources the map
+ * itself feeds: terraform and tofu both refuse that as a dependency cycle
+ * (proved by the module-set case in src/validate.test.ts). Everything else
+ * shares `local.flow_refs`.
+ */
+const REFS_LOCAL = "flow_refs";
+const refsLocalFor = (doc: FlowDoc): string =>
+  `${doc.kind === "module" ? "module" : "flow"}_refs_${ident(doc.name)}`;
+
+/** A flow and a module may share a name, so a document key carries both. */
+const docKey = (doc: FlowDoc): string => `${doc.kind}:${doc.name}`;
+
+const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * An address expression is HCL the emitter pastes into `flow_refs.tf`
+ * unevaluated, so it is checked for the things that would corrupt the file or
+ * the deploy. Literal ARNs are rejected outright: references stay references
+ * (CLAUDE.md, docs/01-flowdoc-spec.md).
+ */
+function checkExpression(label: string, value: string, problems: string[]): void {
+  if (value.trim() === "") {
+    problems.push(`${label} is empty`);
+    return;
+  }
+  if (/arn:aws/i.test(value)) {
+    problems.push(`${label} is a literal ARN (${value}); map to a terraform address instead`);
+  }
+  if (/[\n\r]/.test(value))
+    problems.push(`${label} spans multiple lines (${JSON.stringify(value)})`);
+  if (/#|\/\/|\/\*/.test(value)) problems.push(`${label} contains a comment marker (${value})`);
+}
+
+/** Documents in emission order, with the structural problems reported first. */
+function checkDocs(docs: readonly FlowDoc[]): FlowDoc[] {
+  const problems: string[] = [];
+  if (docs.length === 0) problems.push("no documents to emit");
+
+  const seen = new Map<string, string>();
+  for (const doc of docs) {
+    if (!SLUG_PATTERN.test(doc.name)) {
+      problems.push(`document name "${doc.name}" is not a slug`);
+      continue;
+    }
+    // `type` accepts every ConnectType except MODULE, and the module resource
+    // takes no `type` at all, so kind and connectType have to agree.
+    if (doc.kind === "module" && doc.connectType !== "MODULE") {
+      problems.push(`module "${doc.name}" has connectType ${doc.connectType}, expected MODULE`);
+    }
+    if (doc.kind === "flow" && doc.connectType === "MODULE") {
+      problems.push(`flow "${doc.name}" has connectType MODULE; emit it as kind "module"`);
+    }
+    const address = `${resourceType(doc)}.${ident(doc.name)}`;
+    const prior = seen.get(address);
+    if (prior !== undefined) problems.push(`two documents both emit ${address}`);
+    else seen.set(address, doc.name);
+  }
+
+  if (problems.length > 0) throw new EmitTfError(problems);
+  // Kind breaks the tie, because a flow and a module may share a name and the
+  // order must not depend on the order the caller passed them in.
+  return [...docs].sort((a, b) => byString(a.name, b.name) || byString(a.kind, b.kind));
+}
+
+/**
+ * Every reference in the set, resolved. Documents in the set resolve their own
+ * references: a `${cdref:module:x@prod}` whose module x is emitted here points
+ * at the alias resource emitted with it, and a `${cdref:flow:y}` whose flow y is
+ * emitted here points at that flow. Everything else comes from the address map,
+ * and what the map does not cover gets a placeholder that fails `validate`.
+ */
+function resolveRefs(
+  docs: readonly FlowDoc[],
+  addressMap: Record<string, string>,
+  problems: string[],
+): Resolved[] {
+  const flows = new Set(docs.filter((d) => d.kind === "flow").map((d) => d.name));
+  const modules = new Set(docs.filter((d) => d.kind === "module").map((d) => d.name));
+
+  const entries = new Map<string, RefEntry>();
+  for (const doc of docs) {
+    for (const entry of collectRefs(doc.content)) entries.set(entry.token, entry);
+  }
+
+  const byVariable = new Map<string, string>();
+  const resolved: Resolved[] = [];
+  for (const entry of [...entries.values()].sort((a, b) => byString(a.token, b.token))) {
+    const variable = variableName(entry);
+    const clash = byVariable.get(variable);
+    if (clash !== undefined) {
+      problems.push(`${entry.token} and ${clash} both map to local.flow_refs.${variable}`);
+      continue;
+    }
+    byVariable.set(variable, entry.token);
+
+    const key = refKey(entry);
+    const supplied = addressMap[entry.token] ?? addressMap[key] ?? addressMap[variable];
+    if (supplied !== undefined) checkExpression(`address for ${entry.token}`, supplied, problems);
+
+    let inSet: string | undefined;
+    if (entry.type === "module" && entry.alias !== undefined && modules.has(entry.name)) {
+      inSet = `awscc_connect_contact_flow_module_alias.${ident(entry.name)}_${ident(entry.alias)}.contact_flow_module_alias_arn`;
+    } else if (entry.type === "flow" && flows.has(entry.name)) {
+      inSet = `aws_connect_contact_flow.${ident(entry.name)}.arn`;
+    }
+
+    if (inSet !== undefined) {
+      const shadowed = supplied === undefined ? undefined : key;
+      resolved.push({
+        entry,
+        variable,
+        expression: inSet,
+        source: "set",
+        ...(shadowed ? { shadowed } : {}),
+      });
+    } else if (supplied !== undefined) {
+      resolved.push({ entry, variable, expression: supplied, source: "map" });
+    } else {
+      resolved.push({ entry, variable, expression: placeholder(variable), source: "missing" });
+    }
+  }
+  return resolved;
+}
+
+/** Aliases each emitted module needs, derived from the references to it. */
+function aliasesByModule(docs: readonly FlowDoc[]): Map<string, string[]> {
+  const modules = new Set(docs.filter((d) => d.kind === "module").map((d) => d.name));
+  const aliases = new Map<string, Set<string>>();
+  for (const name of modules) aliases.set(name, new Set());
+  for (const doc of docs) {
+    for (const entry of collectRefs(doc.content)) {
+      if (entry.type !== "module" || entry.alias === undefined) continue;
+      aliases.get(entry.name)?.add(entry.alias);
+    }
+  }
+  return new Map([...aliases].map(([name, set]) => [name, [...set].sort(byString)]));
+}
+
+const AWS_FLOW_DOC =
+  "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/connect_contact_flow";
+const AWS_MODULE_DOC =
+  "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/connect_contact_flow_module";
+const AWSCC_VERSION_DOC =
+  "https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/connect_contact_flow_module_version";
+const AWSCC_ALIAS_DOC =
+  "https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/connect_contact_flow_module_alias";
+const CREATE_FLOW_VERSION_DOC =
+  "https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateContactFlowVersion.html";
+
+function flowsTf(
+  docs: readonly FlowDoc[],
+  instanceId: string,
+  inSetByDoc: ReadonlyMap<string, Resolved[]>,
+): string {
+  const aliases = aliasesByModule(docs);
+  const hasModule = docs.some((d) => d.kind === "module");
+  const lines: HclLine[] = GENERATED_BY.map(comment);
+  lines.push(
+    comment(""),
+    comment("Flow content is rendered from flows/<name>.flow.tftpl with the"),
+    comment("addresses in flow_refs.tf. Provider, credential, and backend"),
+    comment("configuration is yours; versions.tf.example lists what this needs."),
+    comment(""),
+    comment(AWS_FLOW_DOC),
+    comment(AWS_MODULE_DOC),
+  );
+  if (hasModule) {
+    lines.push(
+      comment(""),
+      comment("Modules carry versions and aliases; full flows do not."),
+      comment('CreateContactFlowVersion "only supports creating versions for'),
+      comment('flows of type Campaign", so a flow updates its content in place'),
+      comment("while a module pins content behind an alias."),
+      comment(CREATE_FLOW_VERSION_DOC),
+    );
+  }
+
+  for (const doc of docs) {
+    const refs = (inSetByDoc.get(docKey(doc)) ?? []).length > 0 ? refsLocalFor(doc) : REFS_LOCAL;
+    const template = `templatefile("\${path.module}/flows/${doc.name}.flow.tftpl", local.${refs})`;
+    const body: HclLine[] = [arg("instance_id", instanceId), arg("name", quote(doc.name))];
+    // `type` exists on the flow resource only; the module resource has none.
+    if (doc.kind === "flow") body.push(arg("type", quote(doc.connectType)));
+    body.push(arg("content", template));
+
+    lines.push(blank(), block("resource", [resourceType(doc), ident(doc.name)], body));
+    if (doc.kind !== "module") continue;
+
+    const self = `aws_connect_contact_flow_module.${ident(doc.name)}.arn`;
+    lines.push(
+      blank(),
+      comment("Snapshot of the module content as it stands when this resource is"),
+      comment("created. Replace it after a content change so the aliases below"),
+      comment("serve the new content."),
+      comment(AWSCC_VERSION_DOC),
+      block(
+        "resource",
+        ["awscc_connect_contact_flow_module_version", ident(doc.name)],
+        [arg("contact_flow_module_id", self)],
+      ),
+    );
+    for (const alias of aliases.get(doc.name) ?? []) {
+      lines.push(
+        blank(),
+        comment(AWSCC_ALIAS_DOC),
+        block(
+          "resource",
+          ["awscc_connect_contact_flow_module_alias", `${ident(doc.name)}_${ident(alias)}`],
+          [
+            arg("contact_flow_module_id", self),
+            arg(
+              "contact_flow_module_version",
+              `awscc_connect_contact_flow_module_version.${ident(doc.name)}.version`,
+            ),
+            arg("name", quote(alias)),
+          ],
+        ),
+      );
+    }
+  }
+  return renderFile(lines);
+}
+
+function flowRefsTf(
+  docs: readonly FlowDoc[],
+  resolved: readonly Resolved[],
+  inSetByDoc: ReadonlyMap<string, Resolved[]>,
+): string {
+  const lines: HclLine[] = GENERATED_BY.map(comment);
+  lines.push(
+    comment(""),
+    comment("One entry per reference token in the emitted flow set, named"),
+    comment("<type>_<name>_arn with hyphens as underscores and the module alias"),
+    comment("folded in. Values are terraform addresses, never literal ARNs."),
+  );
+
+  const shared: HclLine[] = [];
+  for (const ref of resolved) {
+    // Addresses of resources this set emits are deliberately left out of the
+    // shared map; see refsLocalFor and the per-document entries below.
+    if (ref.source === "set") continue;
+    if (ref.source === "missing") {
+      shared.push(
+        comment(`TODO: no terraform address for ${ref.entry.token}.`),
+        comment(`Add one to the address map under key "${refKey(ref.entry)}"`),
+        comment("and re-emit. Until then this placeholder is an undeclared"),
+        comment("reference, so `terraform validate` and `tofu validate` fail."),
+      );
+    }
+    shared.push(arg(ref.variable, ref.expression));
+  }
+  if (shared.length === 0) {
+    shared.push(comment("No reference resolves through this map."));
+  }
+
+  const body: HclLine[] = [objectArg(REFS_LOCAL, shared)];
+  for (const doc of docs) {
+    const own = inSetByDoc.get(docKey(doc)) ?? [];
+    if (own.length === 0) continue;
+    const entries: HclLine[] = [];
+    for (const ref of own) {
+      if (ref.shadowed !== undefined) {
+        entries.push(
+          comment(`Address map entry "${ref.shadowed}" ignored: this set emits`),
+          comment("the resource itself, so the reference resolves to it."),
+        );
+      }
+      entries.push(arg(ref.variable, ref.expression));
+    }
+    body.push(
+      blank(),
+      comment(`${doc.name} references a resource this set emits. Its addresses`),
+      comment("go in a local of their own: in the shared map they would make"),
+      comment("that map depend on resources rendered from it, which both tools"),
+      comment("report as a dependency cycle."),
+      objectArg(refsLocalFor(doc), entries, {
+        open: `merge(local.${REFS_LOCAL}, {`,
+        close: "})",
+      }),
+    );
+  }
+
+  lines.push(blank(), block("locals", [], body));
+  return renderFile(lines);
+}
+
+function variablesTf(): string {
+  const lines: HclLine[] = GENERATED_BY.map(comment);
+  lines.push(
+    blank(),
+    block(
+      "variable",
+      [INSTANCE_ID_VARIABLE],
+      [
+        arg(
+          "description",
+          quote("Identifier of the Amazon Connect instance that holds these flows."),
+        ),
+        arg("type", "string"),
+      ],
+    ),
+  );
+  return renderFile(lines);
+}
+
+function versionsExample(needsAwscc: boolean): string {
+  const providers: HclLine[] = [
+    objectArg("aws", [arg("source", quote("hashicorp/aws")), arg("version", quote(">= 5.0"))]),
+  ];
+  if (needsAwscc) {
+    providers.push(
+      blank(),
+      objectArg("awscc", [
+        arg("source", quote("hashicorp/awscc")),
+        arg("version", quote(">= 1.74")),
+      ]),
+    );
+  }
+
+  const lines: HclLine[] = GENERATED_BY.map(comment);
+  lines.push(
+    comment(""),
+    comment("Example only. This file is not loaded by terraform or tofu, which"),
+    comment("read *.tf; copy what you need into your own configuration. No"),
+    comment("provider credentials and no backend configuration are emitted."),
+    comment(""),
+    comment("The version constraint below is what both tools understand:"),
+    comment("this output uses nothing newer than Terraform 1.8 / OpenTofu 1.7."),
+  );
+  if (needsAwscc) {
+    lines.push(
+      comment(""),
+      comment("awscc is needed for the module version and alias resources; it"),
+      comment("carries them and the aws provider does not."),
+    );
+  }
+  lines.push(
+    blank(),
+    block(
+      "terraform",
+      [],
+      [
+        arg("required_version", quote(`>= ${CORE_VERSION_FLOOR}`)),
+        blank(),
+        block("required_providers", [], providers),
+      ],
+    ),
+  );
+  return renderFile(lines);
+}
+
+/**
+ * Emits a Terraform/OpenTofu configuration for a set of FlowDocs. Pure and
+ * deterministic: the same documents and options produce byte-identical files,
+ * and paths come back sorted.
+ */
+export function emitTf(docs: readonly FlowDoc[], options: EmitTfOptions = {}): EmitTfResult {
+  const ordered = checkDocs(docs);
+  const problems: string[] = [];
+
+  const instanceId = options.instanceIdExpression ?? DEFAULT_INSTANCE_ID_EXPRESSION;
+  if (options.instanceIdExpression !== undefined) {
+    checkExpression("instanceIdExpression", options.instanceIdExpression, problems);
+  }
+
+  const addressMap = options.addressMap ?? {};
+  for (const key of Object.keys(addressMap)) {
+    // A key in token form has to be a token we could actually have produced.
+    if (key.startsWith("${") && parseToken(key) === undefined) {
+      problems.push(`address map key "${key}" looks like a token but does not parse as one`);
+    }
+  }
+
+  const resolved = resolveRefs(ordered, addressMap, problems);
+  if (problems.length > 0) throw new EmitTfError(problems);
+
+  // Which of each document's own references resolve to resources this set
+  // emits. They are what the per-document locals hold; see refsLocalFor.
+  const bySet = new Map(resolved.filter((r) => r.source === "set").map((r) => [r.entry.token, r]));
+  const inSetByDoc = new Map<string, Resolved[]>(
+    ordered.map((doc) => [
+      docKey(doc),
+      collectRefs(doc.content)
+        .map((entry) => bySet.get(entry.token))
+        .filter((r): r is Resolved => r !== undefined),
+    ]),
+  );
+
+  const variables = new Map(resolved.map((r) => [r.entry.token, r.variable]));
+  const files: Record<string, string> = {
+    "flow_refs.tf": flowRefsTf(ordered, resolved, inSetByDoc),
+    "flows.tf": flowsTf(ordered, instanceId, inSetByDoc),
+    "versions.tf.example": versionsExample(ordered.some((d) => d.kind === "module")),
+  };
+  for (const doc of ordered) {
+    files[`flows/${doc.name}.flow.tftpl`] = renderTemplate(doc, variables);
+  }
+  if (options.instanceIdExpression === undefined) files["variables.tf"] = variablesTf();
+
+  return {
+    files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => byString(a, b))),
+  };
+}

package/src/hcl.ts

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// A very small HCL writer. It writes the handful of shapes this emitter needs
+// (comments, `key = expression` arguments, and nested blocks) in the layout
+// `terraform fmt` / `tofu fmt` produce, so emitted files are fmt-clean and stay
+// byte-stable across runs.
+//
+// fmt aligns the `=` of a maximal run of consecutive argument lines, and a
+// comment or a blank line ends the run. That rule is reproduced in `render`
+// below and is asserted against a real `tofu fmt` in the gated validate tests.
+
+/** One line of an HCL body. */
+export type HclLine =
+  | { kind: "arg"; key: string; value: string }
+  | { kind: "objectArg"; key: string; body: HclLine[]; open?: string; close?: string }
+  | { kind: "block"; type: string; labels: string[]; body: HclLine[] }
+  | { kind: "comment"; text: string }
+  | { kind: "blank" };
+
+export const arg = (key: string, value: string): HclLine => ({ kind: "arg", key, value });
+export const comment = (text: string): HclLine => ({ kind: "comment", text });
+export const blank = (): HclLine => ({ kind: "blank" });
+export const block = (type: string, labels: string[], body: HclLine[]): HclLine => ({
+  kind: "block",
+  type,
+  labels,
+  body,
+});
+/**
+ * `key = { ... }`: an object value, not a block. `open` and `close` wrap the
+ * body in something else, such as a `merge(...)` call around the braces.
+ */
+export const objectArg = (
+  key: string,
+  body: HclLine[],
+  wrap?: { open: string; close: string },
+): HclLine => ({ kind: "objectArg", key, body, ...wrap });
+
+/**
+ * A double-quoted HCL string with no template introducer left live. A quoted
+ * string in .tf is itself a template, so `${` and `%{` are escaped here too.
+ * The `$` replacements are functions because a string replacement would give
+ * `$` its substitution meaning and undo the escape.
+ */
+export function quote(value: string): string {
+  const escaped = value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r")
+    .replaceAll("\t", "\\t")
+    .replaceAll("${", () => "$${")
+    .replaceAll("%{", () => "%%{");
+  return `"${escaped}"`;
+}
+
+/**
+ * Renders body lines at the given indent, aligning the `=` within each run of
+ * consecutive argument lines the way fmt does.
+ */
+export function render(lines: readonly HclLine[], indent = ""): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    if (line.kind === "blank") {
+      out.push("");
+      continue;
+    }
+    if (line.kind === "comment") {
+      out.push(`${indent}# ${line.text}`.trimEnd());
+      continue;
+    }
+    if (line.kind === "block") {
+      const labels = line.labels.map((l) => ` ${quote(l)}`).join("");
+      out.push(`${indent}${line.type}${labels} {`);
+      out.push(...render(line.body, `${indent}  `));
+      out.push(`${indent}}`);
+      continue;
+    }
+    if (line.kind === "objectArg") {
+      out.push(`${indent}${line.key} = ${line.open ?? "{"}`);
+      out.push(...render(line.body, `${indent}  `));
+      out.push(`${indent}${line.close ?? "}"}`);
+      continue;
+    }
+    // An argument: gather the whole run so the `=` columns line up.
+    const run: { key: string; value: string }[] = [];
+    let j = i;
+    for (; j < lines.length; j += 1) {
+      const next = lines[j];
+      if (next === undefined || next.kind !== "arg") break;
+      run.push({ key: next.key, value: next.value });
+    }
+    const width = Math.max(...run.map((a) => a.key.length));
+    for (const a of run) out.push(`${indent}${a.key.padEnd(width)} = ${a.value}`);
+    i = j - 1;
+  }
+  return out;
+}
+
+/** A whole file: rendered lines plus the trailing newline fmt insists on. */
+export function renderFile(lines: readonly HclLine[]): string {
+  return `${render(lines).join("\n").replace(/\n+$/, "")}\n`;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Public surface of @flow-as-code/tf. FlowDoc in, Terraform/OpenTofu out, per
+// docs/03-tf-emitter.md. One-way in v1: HCL back to FlowDoc is a provider-era
+// feature and is not attempted here.
+
+export { EmitTfError, type EmitTfOptions, type EmitTfResult, emitTf } from "./emit.js";
+export { escapeTemplateText, renderTemplate } from "./template.js";
+export { writeTf } from "./write.js";