@flow-as-code/cdk 0.1.0

package/src/flow-set.ts

@@ -0,0 +1,275 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// FlowSet: a construct that turns a set of FlowDocs into deployable
+// AWS::Connect resources.
+//
+// Flows become AWS::Connect::ContactFlow and modules become
+// AWS::Connect::ContactFlowModule, with content produced by @flow-as-code/core's
+// materializeWithBinder and serializeContent so the deployed JSON is
+// byte-stable for the same inputs.
+// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflow.html
+// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmodule.html
+//
+// Versioning model:
+// - Modules are versioned. Each module gets an AWS::Connect::ContactFlowModuleVersion
+//   whose logical ID embeds a hash of the module's canonical content, so a
+//   content change replaces the version resource and publishes a new immutable
+//   version, and an AWS::Connect::ContactFlowModuleAlias per alias name used by
+//   the doc set (default "live") whose logical ID is stable and which repoints
+//   to the new version. Flows reference the ALIAS ARN, so repointing an alias
+//   to a new version changes no flow content.
+//   https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmoduleversion.html
+//   https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmodulealias.html
+// - Full flows are NOT versioned; their content updates in place. Connect's
+//   CreateContactFlowVersion API states: "This API only supports creating
+//   versions for flows of type Campaign."
+//   https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateContactFlowVersion.html
+//   (verified 2026-08-31)
+
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  allRules,
+  collectRefs,
+  lint,
+  materializeWithBinder,
+  serializeContent,
+  toText,
+  type FlowDoc,
+  type RefEntry,
+} from "@flow-as-code/core";
+import {
+  CfnContactFlow,
+  CfnContactFlowModule,
+  CfnContactFlowModuleAlias,
+  CfnContactFlowModuleVersion,
+} from "aws-cdk-lib/aws-connect";
+import { Construct } from "constructs";
+
+import { bindRef, type TokenBinder } from "./binder.js";
+
+/** Alias created for a module no flow pins to a named alias. */
+export const DEFAULT_MODULE_ALIAS = "live";
+
+export interface FlowSetProps {
+  /** ARN of the Connect instance the flows deploy into. */
+  instanceArn: string;
+  /**
+   * Either a directory containing `*.flowdoc.json` files (read at synth time,
+   * sorted by file name) or the documents themselves.
+   */
+  source: string | FlowDoc[];
+  /** Resolves non-module references to CloudFormation-token strings. */
+  binder: TokenBinder;
+}
+
+/** `name@alias` key for a module alias resource. */
+const aliasKey = (name: string, alias: string | undefined): string =>
+  `${name}@${alias ?? DEFAULT_MODULE_ALIAS}`;
+
+function loadDocs(source: string | FlowDoc[]): FlowDoc[] {
+  if (Array.isArray(source)) return [...source];
+  const files = readdirSync(source)
+    .filter((f) => f.endsWith(".flowdoc.json"))
+    .sort();
+  if (files.length === 0) {
+    throw new Error(`FlowSet source directory "${source}" contains no *.flowdoc.json files.`);
+  }
+  return files.map((f) => JSON.parse(readFileSync(join(source, f), "utf8")) as FlowDoc);
+}
+
+/**
+ * Modules ordered so every module is created after the modules it references
+ * ("up to five levels" of nesting, per the flow language contract). Stable:
+ * ties break on name. Throws on a reference cycle, which Connect could never
+ * execute anyway.
+ */
+function topoSortModules(modules: FlowDoc[]): FlowDoc[] {
+  const byName = new Map(modules.map((m) => [m.name, m]));
+  const deps = new Map<string, string[]>(
+    modules.map((m) => [
+      m.name,
+      collectRefs(m.content)
+        .filter((r) => r.type === "module" && byName.has(r.name))
+        .map((r) => r.name)
+        .sort(),
+    ]),
+  );
+
+  const done = new Set<string>();
+  const visiting = new Set<string>();
+  const ordered: FlowDoc[] = [];
+  const visit = (name: string, path: string[]): void => {
+    if (done.has(name)) return;
+    if (visiting.has(name)) {
+      throw new Error(`Module reference cycle: ${[...path, name].join(" -> ")}.`);
+    }
+    visiting.add(name);
+    for (const dep of deps.get(name) ?? []) visit(dep, [...path, name]);
+    visiting.delete(name);
+    done.add(name);
+    ordered.push(byName.get(name) as FlowDoc);
+  };
+  for (const m of [...modules].sort((a, b) => a.name.localeCompare(b.name))) visit(m.name, []);
+  return ordered;
+}
+
+/**
+ * Creates every flow and module in a FlowDoc set on a Connect instance, with
+ * references resolved to CloudFormation tokens: non-module refs through the
+ * user's TokenBinder, module refs to the alias ARN of the module this
+ * construct manages.
+ */
+export class FlowSet extends Construct {
+  /** Created contact flows, keyed by document name. */
+  readonly flows: ReadonlyMap<string, CfnContactFlow>;
+  /** Created modules, keyed by document name. */
+  readonly modules: ReadonlyMap<string, CfnContactFlowModule>;
+  /** Created module aliases, keyed by `name@alias`. */
+  readonly moduleAliases: ReadonlyMap<string, CfnContactFlowModuleAlias>;
+
+  constructor(scope: Construct, id: string, props: FlowSetProps) {
+    super(scope, id);
+
+    const docs = loadDocs(props.source);
+    this.validateDocs(docs);
+
+    const moduleDocs = docs.filter((d) => d.kind === "module");
+    const flowDocs = docs
+      .filter((d) => d.kind === "flow")
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const moduleNames = new Set(moduleDocs.map((d) => d.name));
+
+    // Which aliases each module needs: every alias the doc set pins, plus the
+    // default so an unreferenced module still deploys with a usable alias.
+    const wanted = new Map<string, Set<string>>(moduleDocs.map((d) => [d.name, new Set()]));
+    for (const doc of docs) {
+      for (const ref of collectRefs(doc.content)) {
+        if (ref.type !== "module") continue;
+        if (!moduleNames.has(ref.name)) {
+          throw new Error(
+            `"${doc.name}" references ${ref.token}, but no module named "${ref.name}" is in this FlowSet.`,
+          );
+        }
+        (wanted.get(ref.name) as Set<string>).add(ref.alias ?? DEFAULT_MODULE_ALIAS);
+      }
+    }
+    for (const aliases of wanted.values()) {
+      if (aliases.size === 0) aliases.add(DEFAULT_MODULE_ALIAS);
+    }
+
+    const flows = new Map<string, CfnContactFlow>();
+    const modules = new Map<string, CfnContactFlowModule>();
+    const aliases = new Map<string, CfnContactFlowModuleAlias>();
+
+    const materializeDoc = (
+      doc: FlowDoc,
+    ): { content: string; used: CfnContactFlowModuleAlias[] } => {
+      const used: CfnContactFlowModuleAlias[] = [];
+      const content = materializeWithBinder(doc, (ref: RefEntry): string => {
+        if (ref.type !== "module") return bindRef(props.binder, ref, doc.name);
+        const alias = aliases.get(aliasKey(ref.name, ref.alias));
+        if (alias === undefined) {
+          // Unreachable for modules (topological order) and flows (created
+          // after every module); kept as a guard with a real message.
+          throw new Error(`Internal: alias for ${ref.token} not yet created (doc "${doc.name}").`);
+        }
+        used.push(alias);
+        return alias.attrContactFlowModuleAliasArn;
+      });
+      return { content: serializeContent(content), used };
+    };
+
+    // Modules first, dependency-ordered, each with its version and aliases.
+    for (const doc of topoSortModules(moduleDocs)) {
+      const { content, used } = materializeDoc(doc);
+      const module = new CfnContactFlowModule(this, `Module-${doc.name}`, {
+        instanceArn: props.instanceArn,
+        name: doc.name,
+        content,
+      });
+      for (const dep of used) module.addResourceDependency(dep);
+      modules.set(doc.name, module);
+
+      // The version's logical ID embeds the canonical content hash (computed
+      // over the doc with its own tokens left in place, so it is stable across
+      // processes): a content change replaces the resource, publishing a new
+      // immutable version; the alias below keeps a stable logical ID and
+      // repoints. See the header comment for the versioning model.
+      const discriminator = createHash("sha256")
+        .update(serializeContent(materializeWithBinder(doc, (r) => r.token)))
+        .digest("hex")
+        .slice(0, 8);
+      const version = new CfnContactFlowModuleVersion(
+        this,
+        `Module-${doc.name}-Version-${discriminator}`,
+        {
+          contactFlowModuleId: module.attrContactFlowModuleArn,
+        },
+      );
+      version.addResourceDependency(module);
+
+      for (const aliasName of [...(wanted.get(doc.name) as Set<string>)].sort()) {
+        const alias = new CfnContactFlowModuleAlias(this, `Module-${doc.name}-Alias-${aliasName}`, {
+          contactFlowModuleId: module.attrContactFlowModuleArn,
+          contactFlowModuleVersion: version.attrVersion,
+          name: aliasName,
+        });
+        alias.addResourceDependency(version);
+        aliases.set(aliasKey(doc.name, aliasName), alias);
+      }
+    }
+
+    // Then flows. Alias references inside content already imply the ordering;
+    // the explicit dependency keeps it true even if content is later composed
+    // differently.
+    for (const doc of flowDocs) {
+      const { content, used } = materializeDoc(doc);
+      const flow = new CfnContactFlow(this, `Flow-${doc.name}`, {
+        instanceArn: props.instanceArn,
+        name: doc.name,
+        type: doc.connectType,
+        content,
+      });
+      for (const dep of used) flow.addResourceDependency(dep);
+      flows.set(doc.name, flow);
+    }
+
+    this.flows = flows;
+    this.modules = modules;
+    this.moduleAliases = aliases;
+  }
+
+  /** Refuses duplicate names, kind mismatches, and hard lint findings. */
+  private validateDocs(docs: FlowDoc[]): void {
+    const seen = new Set<string>();
+    const duplicates = new Set<string>();
+    for (const d of docs) {
+      if (seen.has(d.name)) duplicates.add(d.name);
+      seen.add(d.name);
+      if (d.kind === "module" && d.connectType !== "MODULE") {
+        throw new Error(`Module "${d.name}" must have connectType MODULE, got ${d.connectType}.`);
+      }
+      if (d.kind === "flow" && d.connectType === "MODULE") {
+        throw new Error(`Flow "${d.name}" cannot have connectType MODULE.`);
+      }
+    }
+    if (duplicates.size > 0) {
+      throw new Error(
+        `Duplicate document name(s) in FlowSet: ${[...duplicates].sort().join(", ")}.`,
+      );
+    }
+
+    // Hard rules block deployment exactly as they block a studio save:
+    // no-literal-arn and no-unresolved-token (@flow-as-code/core lint).
+    const hard = new Set(allRules.filter((r) => r.hard).map((r) => r.id));
+    const blocking = lint(docs).filter((f) => hard.has(f.rule));
+    if (blocking.length > 0) {
+      throw new Error(`FlowSet refused ${blocking.length} document(s):\n${toText(blocking)}`);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// CDK binding for @flow-as-code/core. See README.md.
+//
+// TokenBinder maps FlowDoc references to CloudFormation-token strings;
+// FlowSet turns a set of FlowDocs into AWS::Connect resources with module
+// version publishing and alias repointing.
+//
+// aws-cdk-lib and constructs are OPTIONAL peers, so that installing @flow-as-code/cli
+// (which only reaches this package through the ./scaffold subpath, and that
+// subpath imports no CDK) does not drag 168 MB of CDK in. The cost is that npm
+// no longer warns at install time, so a consumer who forgets them used to meet
+// a bare ERR_MODULE_NOT_FOUND for aws-cdk-lib raised from flow-set.js. ESM
+// resolves the whole graph before any module body runs, so the only way to
+// front-run that is to keep flow-set.js off the static import graph: this
+// module checks the peer itself and then loads flow-set through a dynamic
+// import. The type-only imports below are erased and pull in nothing.
+
+import { createRequire } from "node:module";
+
+import { PACKAGE_NAMES } from "@flow-as-code/core";
+
+import type { FlowSet as FlowSetClass, FlowSetProps } from "./flow-set.js";
+
+export { bindRef, type TokenBinder } from "./binder.js";
+export type { FlowSetProps };
+
+/** Peer floor, kept in step with peerDependencies in package.json. */
+const CDK_PEERS = "aws-cdk-lib@^2.267.0 constructs@^10.8.1";
+
+function assertCdkPeersInstalled(): void {
+  try {
+    createRequire(import.meta.url).resolve("aws-cdk-lib");
+  } catch {
+    throw new Error(
+      `${PACKAGE_NAMES.cdk} needs the CDK at runtime, but aws-cdk-lib is not installed. ` +
+        "It and constructs are optional peers so that a CLI-only install stays small, " +
+        `which means npm does not warn about them at install time. Install them with: npm install ${CDK_PEERS}`,
+    );
+  }
+}
+
+assertCdkPeersInstalled();
+
+const flowSet = await import("./flow-set.js");
+
+export const DEFAULT_MODULE_ALIAS: string = flowSet.DEFAULT_MODULE_ALIAS;
+export const FlowSet: typeof FlowSetClass = flowSet.FlowSet;
+export type FlowSet = FlowSetClass;

package/src/scaffold.ts

@@ -0,0 +1,193 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The CDK stack scaffold, shared by `flow-cli emit --target cdk` and the
+// studio's CDK export button.
+//
+// @flow-as-code/cdk is a library, not a code generator: FlowSet reads the FlowDoc
+// directory at synth time, so there is nothing per-document to emit. What a
+// user actually has to write by hand is the stack that instantiates it and,
+// above all, the TokenBinder, whose method set depends on which reference types
+// their documents use. That is what this generates: a valid, compiling starting
+// point with a TODO on exactly the binder methods the document set needs.
+//
+// It lives in the package whose API it writes, and is published as
+// `@flow-as-code/cdk/scaffold`, so the CLI and the studio emit the
+// same bytes instead of two implementations that drift. The studio cannot
+// import the CLI (the CLI depends on the studio for its built assets) and
+// parity between the two is the point of the feature, so a shared module is
+// the only arrangement that holds.
+//
+// Pure by contract: no node builtins, no filesystem, no clock, no randomness,
+// because this module is bundled into a browser. The one calculation that
+// needs a path, the FLOW_DOCS expression, is passed in as `source`: the CLI
+// computes it with node:path and the studio with `sourceForDepth` below.
+//
+// Deterministic: same documents in, byte-identical TypeScript out. Reference
+// types and names are sorted, and nothing in the output depends on the order
+// files were read.
+//
+// FlowSet resolves `${cdref:module:...}` itself against the modules it manages,
+// so `module` never appears on a binder (packages/cdk/src/binder.ts).
+
+import { type FlowDoc, PACKAGE_NAMES, type RefType, collectRefs } from "@flow-as-code/core";
+
+/** Basename of the file the scaffold is written to. */
+export const CDK_SCAFFOLD_FILE = "flow-stack.ts";
+
+/** Required TokenBinder methods, in the order they are emitted. */
+const REQUIRED_TYPES = ["hours", "lambda", "lex", "prompt", "queue"] as const;
+
+/** What each binder method must return, echoing packages/cdk/src/binder.ts. */
+const RETURNS: Record<string, string> = {
+  flow: "ARN of a contact flow not managed by this FlowSet",
+  hours: "ARN of the hours of operation, e.g. hours.attrHoursOfOperationArn",
+  lambda: "ARN of the Lambda function, e.g. fn.functionArn",
+  lex: "ARN of the Lex bot alias",
+  prompt: "ARN of the prompt",
+  queue: "ARN of the queue, e.g. queue.attrQueueArn",
+};
+
+/** What each reference type names, for the comment on an unused method. */
+const NOUNS: Record<string, string> = {
+  flow: "contact flow",
+  hours: "hours of operation",
+  lambda: "Lambda function",
+  lex: "Lex bot alias",
+  prompt: "prompt",
+  queue: "queue",
+};
+
+/**
+ * Reference names per type across the whole set, sorted and deduplicated.
+ *
+ * A document's `refs` index is the authored answer, but it is derived data and
+ * nothing in the schema forces it to be current, so the content is scanned too
+ * and the two are unioned. A stale index can therefore only add a binder method
+ * the set does not strictly need, never drop one it does.
+ */
+export function referencedNames(docs: readonly FlowDoc[]): Map<RefType, string[]> {
+  const byType = new Map<RefType, Set<string>>();
+  for (const doc of docs) {
+    for (const ref of [...(doc.refs ?? []), ...collectRefs(doc.content)]) {
+      if (ref.type === "module") continue;
+      const names = byType.get(ref.type) ?? new Set<string>();
+      names.add(ref.name);
+      byType.set(ref.type, names);
+    }
+  }
+  return new Map([...byType].map(([type, names]) => [type, [...names].sort()]));
+}
+
+/**
+ * The FLOW_DOCS expression for an output directory `depth` levels below the
+ * directory holding the FlowDocs: `.`, `..`, `../..`. This is what node's
+ * `path.relative` produces for the same pair, which is what the CLI passes;
+ * packages/studio/tests/exportParity.test.ts compares the two byte for
+ * byte on a real `flow-cli emit --target cdk --out` run.
+ */
+export function sourceForDepth(depth: number): string {
+  if (depth <= 0) return ".";
+  return Array.from({ length: depth }, () => "..").join("/");
+}
+
+function binderMethod(type: string, names: readonly string[]): string[] {
+  const returns = RETURNS[type] ?? "ARN of the referenced resource";
+  const noun = NOUNS[type] ?? type;
+  const head =
+    names.length === 0
+      ? [`  // No document in this set references a ${noun}.`]
+      : [`  // TODO: return the ${returns}.`, `  // Names referenced: ${names.join(", ")}.`];
+  return [
+    ...head,
+    `  ${type}: (name) => {`,
+    names.length === 0
+      ? `    throw new Error(\`Unexpected ${type} reference "\${name}".\`);`
+      : `    throw new Error(\`TODO: bind ${type} "\${name}" to an ARN.\`);`,
+    "  },",
+  ];
+}
+
+export interface CdkScaffoldInput {
+  docs: readonly FlowDoc[];
+  /**
+   * Where FlowSet reads the `*.flowdoc.json` files, relative to the scaffold:
+   * `.` when they sit beside it, `..` from a subdirectory. See sourceForDepth.
+   */
+  source: string;
+}
+
+/** The scaffold source. Pure: no filesystem access, no clock, no randomness. */
+export function cdkScaffold({ docs, source }: CdkScaffoldInput): string {
+  const referenced = referencedNames(docs);
+  const types: RefType[] = [...REQUIRED_TYPES];
+  // `flow` is optional on TokenBinder, so it is emitted only when it is used.
+  if ((referenced.get("flow") ?? []).length > 0) types.unshift("flow");
+
+  const used = [...referenced]
+    .filter(([, names]) => names.length > 0)
+    .map(([type]) => type)
+    .sort();
+  const names = docs.map((d) => `${d.kind} ${d.name}`).sort();
+
+  // No licence header: this file lands in a user's project and is theirs, not
+  // ours. Same reasoning as codegen's banner (packages/core/src/codegen.ts).
+  const lines = [
+    "// Generated by `flow-cli emit --target cdk` as a starting point, then yours to",
+    "// keep: re-running the command overwrites this file, so move it or rename it",
+    "// once you have edited it.",
+    "//",
+    `// Documents in the set: ${names.join(", ")}.`,
+    "//",
+    "// FlowSet reads every *.flowdoc.json in the source directory at synth time and",
+    "// creates AWS::Connect::ContactFlow and AWS::Connect::ContactFlowModule",
+    "// resources, publishing a module version and repointing its alias whenever the",
+    `// module content changes. See the ${PACKAGE_NAMES.cdk} README.`,
+    "",
+    'import { fileURLToPath } from "node:url";',
+    "",
+    'import { Stack, type StackProps } from "aws-cdk-lib";',
+    `import { FlowSet, type TokenBinder } from "${PACKAGE_NAMES.cdk}";`,
+    'import type { Construct } from "constructs";',
+    "",
+    "/**",
+    " * Directory holding the FlowDocs. Resolved against this file rather than the",
+    " * working directory, so `cdk synth` works from the project root, from here, or",
+    " * from anywhere else.",
+    " */",
+    `const FLOW_DOCS = fileURLToPath(new URL(${JSON.stringify(source)}, import.meta.url));`,
+    "",
+    "/**",
+    " * Resolves each reference token in the documents to a CloudFormation token,",
+    ` * normally a construct attribute. ${PACKAGE_NAMES.cdk} inserts what you`,
+    " * return byte for byte, so CDK tokens pass through and CloudFormation",
+    " * resolves them at deploy time. Never return a literal ARN here.",
+    " *",
+    used.length === 0
+      ? " * These documents contain no references."
+      : ` * These documents reference: ${used.join(", ")}.`,
+    " */",
+    "const binder: TokenBinder = {",
+    ...types.flatMap((type) => binderMethod(type, referenced.get(type) ?? [])),
+    "};",
+    "",
+    "export interface FlowStackProps extends StackProps {",
+    "  /** ARN of the Amazon Connect instance these flows deploy into. */",
+    "  instanceArn: string;",
+    "}",
+    "",
+    "export class FlowStack extends Stack {",
+    "  constructor(scope: Construct, id: string, props: FlowStackProps) {",
+    "    super(scope, id, props);",
+    "",
+    '    new FlowSet(this, "Flows", {',
+    "      instanceArn: props.instanceArn,",
+    "      source: FLOW_DOCS,",
+    "      binder,",
+    "    });",
+    "  }",
+    "}",
+  ];
+  return lines.join("\n") + "\n";
+}