@flow-as-code/tf 0.1.0

package/dist/template.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Rendering FlowDoc content into a `templatefile` template (.tftpl).
+//
+// The body of a .tftpl is Connect Flow language JSON, and that JSON legitimately
+// contains prompt text a caller wrote, which may include the two sequences HCL
+// treats as template introducers: `${` (interpolation) and `%{` (directive).
+// Both must survive rendering byte for byte, so both are escaped by doubling
+// their leading character, per the HCL string template grammar:
+// https://developer.hashicorp.com/terraform/language/expressions/strings#escape-sequences
+// https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md#template-expressions
+//
+// Escaping is applied to the WHOLE serialized document, then the reference
+// interpolations this emitter owns are substituted in. Doing it the other way
+// round would escape our own interpolations. The intermediate values are unique
+// sentinels chosen so they cannot appear in the document (see sentinelPrefix),
+// which keeps the substitution from colliding with authored text that happens to
+// look like a sentinel.
+import { materializeWithMap, serializeContent } from "@flow-as-code/core";
+/**
+ * Doubles the leading character of every HCL template introducer so the text
+ * renders literally. `${` becomes `$${` and `%{` becomes `%%{`.
+ *
+ * The two patterns are disjoint and the expansion of one can never produce the
+ * other, so a single pass in either order is correct. It is also correct for
+ * already-doubled input: HCL scans left to right and takes the longest match,
+ * so escaping `$${` to `$$${` renders back to `$${` (a literal `$` followed by
+ * the escape for a literal `${`).
+ */
+export function escapeTemplateText(text) {
+    // The replacements are functions on purpose. A string replacement gives `$`
+    // its substitution meaning, so the literal "$${" would be inserted as "${"
+    // and every escape would silently undo itself.
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll#specifying_a_string_as_the_replacement
+    return text.replaceAll("${", () => "$${").replaceAll("%{", () => "%%{");
+}
+/** Root of the sentinel names used while substituting reference tokens. */
+const SENTINEL_BASE = "CDREF_TF_SENTINEL";
+/**
+ * A sentinel prefix that does not occur in `haystack`. Authored text is allowed
+ * to contain anything, sentinel lookalikes included, so the prefix grows until
+ * it is absent from the document being rendered. It terminates: every extra
+ * character makes the prefix longer, and a string cannot contain a substring
+ * longer than itself.
+ */
+export function sentinelPrefix(haystack) {
+    let prefix = SENTINEL_BASE;
+    while (haystack.includes(prefix))
+        prefix += "X";
+    return `${prefix}_`;
+}
+/**
+ * The `.tftpl` body for one document: deployable content JSON with every
+ * `${cdref:...}` token replaced by a `${var}` interpolation naming the entry in
+ * `local.flow_refs`, and every other template introducer escaped.
+ *
+ * `variableNames` maps token to template variable name and must cover every
+ * token in the document; @flow-as-code/core's strict materializer raises a
+ * MaterializeError listing all missing tokens at once if it does not.
+ */
+export function renderTemplate(doc, variableNames) {
+    // Sentinels are chosen against the authored document, before materialization,
+    // so a value that looks like a sentinel cannot be smuggled in through a token.
+    const prefix = sentinelPrefix(JSON.stringify(doc.content));
+    const sentinels = new Map();
+    const substitutions = new Map();
+    let index = 0;
+    for (const [token, variable] of [...variableNames].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        const sentinel = `${prefix}${String(index)}_`;
+        index += 1;
+        sentinels.set(token, sentinel);
+        substitutions.set(sentinel, `\${${variable}}`);
+    }
+    const content = materializeWithMap(doc, Object.fromEntries(sentinels));
+    let body = escapeTemplateText(serializeContent(content));
+    for (const [sentinel, interpolation] of substitutions) {
+        body = body.replaceAll(sentinel, interpolation);
+    }
+    return body;
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qEAAqE;AACrE,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,gEAAgE;AAChE,0FAA0F;AAC1F,oFAAoF;AACpF,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,wBAAwB;AAExB,OAAO,EAAgB,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAExF;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,4EAA4E;IAC5E,2EAA2E;IAC3E,+CAA+C;IAC/C,4IAA4I;IAC5I,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED,2EAA2E;AAC3E,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,IAAI,MAAM,GAAG,aAAa,CAAC;IAC3B,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,GAAG,CAAC;IAChD,OAAO,GAAG,MAAM,GAAG,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,aAA0C;IACrF,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,MAAM,QAAQ,GAAG,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;QAC9C,KAAK,IAAI,CAAC,CAAC;QACX,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC/B,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,QAAQ,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;IACvE,IAAI,IAAI,GAAG,kBAAkB,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IACzD,KAAK,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,IAAI,aAAa,EAAE,CAAC;QACtD,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/write.d.ts

@@ -0,0 +1,12 @@
+import type { FlowDoc } from "@flow-as-code/core";
+import { type EmitTfOptions, type EmitTfResult } from "./emit.js";
+/**
+ * Emits `docs` and writes the result under `outDir`, creating directories as
+ * needed. Returns the emitted files so a caller can report or re-check them.
+ *
+ * Existing files are overwritten and nothing else in `outDir` is touched: the
+ * user owns their provider, backend, and resource files, and this emitter must
+ * never remove them.
+ */
+export declare function writeTf(docs: readonly FlowDoc[], outDir: string, options?: EmitTfOptions): EmitTfResult;
+//# sourceMappingURL=write.d.ts.map

package/dist/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAU,MAAM,WAAW,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAQd"}

package/dist/write.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The filesystem half of the emitter, kept apart from emit.ts so the emitter
+// itself stays pure and the goldens compare bytes with no disk involved.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { emitTf } from "./emit.js";
+/**
+ * Emits `docs` and writes the result under `outDir`, creating directories as
+ * needed. Returns the emitted files so a caller can report or re-check them.
+ *
+ * Existing files are overwritten and nothing else in `outDir` is touched: the
+ * user owns their provider, backend, and resource files, and this emitter must
+ * never remove them.
+ */
+export function writeTf(docs, outDir, options = {}) {
+    const result = emitTf(docs, options);
+    for (const [relative, content] of Object.entries(result.files)) {
+        const target = join(outDir, relative);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content, "utf8");
+    }
+    return result;
+}
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,6EAA6E;AAC7E,yEAAyE;AAEzE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAyC,MAAM,EAAE,MAAM,WAAW,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,IAAwB,EACxB,MAAc,EACd,UAAyB,EAAE;IAE3B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@flow-as-code/tf",
+  "version": "0.1.0",
+  "description": "Terraform/OpenTofu emitter: FlowDoc to aws_connect_* resources, .tftpl content, and an awscc version/alias scaffold. One-way in v1.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./emit": {
+      "types": "./dist/emit.d.ts",
+      "import": "./dist/emit.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/__fixtures__",
+    "!**/__generated__",
+    "!**/*.tsbuildinfo",
+    "!**/__snapshots__",
+    "!**/*.snap",
+    "!**/test-helpers.ts",
+    "!**/test-helpers.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@flow-as-code/core": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flow-as-code/flow-as-code.git",
+    "directory": "packages/tf"
+  },
+  "homepage": "https://github.com/flow-as-code/flow-as-code/tree/main/packages/tf#readme",
+  "bugs": {
+    "url": "https://github.com/flow-as-code/flow-as-code/issues"
+  }
+}