@flow-as-code/cli 0.1.0

package/src/cdk-scaffold.ts

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The `emit --target cdk` scaffold, from the CLI's side.
+//
+// The generator itself lives in @flow-as-code/cdk/scaffold, because the
+// studio's CDK export button has to produce the same bytes and the studio
+// cannot import this package (@flow-as-code/cli depends on
+// @flow-as-code/studio for its assets, so the reverse import would be a
+// cycle). What is left here is the one thing that needs a filesystem view of
+// the world: turning an output directory and a docs directory into the
+// relative FLOW_DOCS expression.
+
+import { relative, resolve, sep } from "node:path";
+
+import { type CdkScaffoldInput, cdkScaffold } from "@flow-as-code/cdk/scaffold";
+import type { FlowDoc } from "@flow-as-code/core";
+
+export { CDK_SCAFFOLD_FILE, cdkScaffold, referencedNames } from "@flow-as-code/cdk/scaffold";
+export type { CdkScaffoldInput };
+
+/** `./flows`, `../flows`, or `.`: POSIX, always relative, always prefixed. */
+export function sourceExpression(outDir: string, docsDir: string): string {
+  const rel = relative(resolve(outDir), resolve(docsDir)).split(sep).join("/");
+  if (rel === "") return ".";
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+export interface CdkScaffoldForDirs {
+  docs: readonly FlowDoc[];
+  /** Directory the scaffold is written to. */
+  outDir: string;
+  /** Directory holding the `*.flowdoc.json` files FlowSet will read. */
+  docsDir: string;
+}
+
+/** The scaffold for a pair of real directories. */
+export function cdkScaffoldForDirs({ docs, outDir, docsDir }: CdkScaffoldForDirs): string {
+  return cdkScaffold({ docs, source: sourceExpression(outDir, docsDir) });
+}

package/src/codegen.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli codegen <doc.flowdoc.json>`: FlowDoc in, typed builder TypeScript
+// out. The inverse of `flow-cli synth`, and named to match: synth writes
+// `<flow.name>.flowdoc.json`, so codegen writes `<doc.name>.flow.ts` next to
+// its input unless `--out` says otherwise.
+//
+// When the output file already exists its current text is passed as
+// `options.previous`, which is how `@keep` comments survive regeneration
+// (packages/core/src/codegen.ts). Overwriting without reading first would
+// silently delete the one thing in a generated file a human is invited to own.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { codegen } from "@flow-as-code/core";
+
+import { loadOneDoc } from "./docs.js";
+
+export interface CodegenOptions {
+  out?: string;
+}
+
+export function runCodegen(file: string, options: CodegenOptions): string {
+  const { path, doc } = loadOneDoc(file, "codegen");
+  const target = resolve(options.out ?? join(dirname(path), `${doc.name}.flow.ts`));
+
+  const previous = existsSync(target) ? readFileSync(target, "utf8") : undefined;
+  const source = codegen(doc, previous === undefined ? {} : { previous });
+
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, source, "utf8");
+  return target;
+}

package/src/diff.ts

@@ -0,0 +1,279 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli diff <dir> --instance <arn>`.
+//
+// For every FlowDoc in <dir>, finds the live flow or module of the same kind
+// and name, exports it to FlowDoc through the same exporter `export` uses (so
+// the live side carries tokens, not ARNs, and the same slug names), and
+// compares the two canonical serializations with `layout` and `meta` removed.
+// Positions and provenance are not differences anyone deploys.
+//
+// Output is one line per local document, in path order, and a unified diff of
+// the canonical JSON under each changed one, so the same two states always
+// print the same bytes. Live flows with no local document are not reported:
+// the question is whether what is checked in matches what is deployed.
+//
+// A live flow that has never been published has no published content to
+// compare; the exporter reads its saved content through the `$SAVED` alias
+// (packages/core/src/export.ts, savedFallback), and this command says
+// so on the status line, `unchanged ($SAVED)`, and in the diff label,
+// `live/<name>:$SAVED`. "Unchanged" against a draft is not "deployed".
+//
+// Exit codes are three-way so a script can tell "differs" from "could not
+// tell": 0 when nothing differs, 1 when any document is changed or has no live
+// counterpart, 2 when the comparison itself failed (bad arguments, no SDK,
+// the instance unreadable, or a matched live flow that cannot be exported).
+
+import { relative } from "node:path";
+
+import type { ExportedFlow, ExportFailure, FlowDoc } from "@flow-as-code/core";
+import { exportInstance, normalizeArn, serialize } from "@flow-as-code/core";
+
+import { type LiveClients, parseInstanceArn, SDK_CLIENTS } from "./aws.js";
+import { loadDocs } from "./docs.js";
+import { CliError, messageOf } from "./errors.js";
+
+export interface DiffOptions {
+  instance: string;
+}
+
+export type DiffStatus = "unchanged" | "changed" | "missing-live" | "error";
+
+export interface DiffEntry {
+  /** Path of the local document, relative to the working directory. */
+  path: string;
+  name: string;
+  kind: FlowDoc["kind"];
+  status: DiffStatus;
+  /** Unified diff for `changed`, the exporter's reason for `error`. */
+  detail?: string;
+  /**
+   * True when the live twin has never been published and its saved content
+   * was compared instead (read through the `$SAVED` alias).
+   */
+  saved?: boolean;
+}
+
+/** The marker on a status line and a diff label for a `$SAVED` twin. */
+export const SAVED_MARKER = "$SAVED";
+
+/** Exit code for a failure of the comparison itself. */
+export const EXIT_DIFF_ERROR = 2;
+
+/** Lines of the canonical text with layout and meta removed. */
+export function comparableLines(doc: FlowDoc): string[] {
+  const { layout: _layout, meta: _meta, ...rest } = doc;
+  const lines = serialize(rest as FlowDoc).split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+// --- Unified diff ------------------------------------------------------------
+// A plain longest-common-subsequence over lines, common prefix and suffix
+// trimmed first. FlowDocs are small, but the table is quadratic, so a middle
+// larger than MAX_CELLS is reported as wholly replaced rather than aligned.
+
+/** Cap on the LCS table. 1e6 cells is 4 MB in a Uint32Array. */
+const MAX_CELLS = 1_000_000;
+
+/** Context lines on each side of a change. */
+const CONTEXT = 3;
+
+interface Edit {
+  kind: " " | "-" | "+";
+  text: string;
+}
+
+function align(left: string[], right: string[]): Edit[] {
+  const edits: Edit[] = [];
+  let start = 0;
+  while (start < left.length && start < right.length && left[start] === right[start]) {
+    edits.push({ kind: " ", text: left[start]! });
+    start++;
+  }
+  let endL = left.length;
+  let endR = right.length;
+  const suffix: Edit[] = [];
+  while (endL > start && endR > start && left[endL - 1] === right[endR - 1]) {
+    endL--;
+    endR--;
+    suffix.unshift({ kind: " ", text: left[endL]! });
+  }
+
+  const a = left.slice(start, endL);
+  const b = right.slice(start, endR);
+  if (a.length === 0 || b.length === 0 || a.length * b.length > MAX_CELLS) {
+    for (const text of a) edits.push({ kind: "-", text });
+    for (const text of b) edits.push({ kind: "+", text });
+    return [...edits, ...suffix];
+  }
+
+  const width = b.length + 1;
+  const table = new Uint32Array((a.length + 1) * width);
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i * width + j] =
+        a[i] === b[j]
+          ? table[(i + 1) * width + j + 1]! + 1
+          : Math.max(table[(i + 1) * width + j]!, table[i * width + j + 1]!);
+    }
+  }
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      edits.push({ kind: " ", text: a[i]! });
+      i++;
+      j++;
+    } else if (table[(i + 1) * width + j]! >= table[i * width + j + 1]!) {
+      edits.push({ kind: "-", text: a[i]! });
+      i++;
+    } else {
+      edits.push({ kind: "+", text: b[j]! });
+      j++;
+    }
+  }
+  while (i < a.length) edits.push({ kind: "-", text: a[i++]! });
+  while (j < b.length) edits.push({ kind: "+", text: b[j++]! });
+  return [...edits, ...suffix];
+}
+
+/** `start,count` as unified diff writes it: no count when 1, previous line when 0. */
+function range(start: number, count: number): string {
+  const shown = count === 0 ? start - 1 : start;
+  return count === 1 ? String(shown) : `${String(shown)},${String(count)}`;
+}
+
+/**
+ * Unified diff of two line arrays, with the usual three lines of context.
+ * Empty when the sides are identical.
+ */
+export function unifiedDiff(
+  left: string[],
+  right: string[],
+  leftLabel: string,
+  rightLabel: string,
+): string {
+  const edits = align(left, right);
+  if (edits.every((edit) => edit.kind === " ")) return "";
+
+  const out = [`--- ${leftLabel}`, `+++ ${rightLabel}`];
+  // Line numbers of the edit at each index, for hunk headers.
+  let leftNo = 1;
+  let rightNo = 1;
+  const positions = edits.map((edit) => {
+    const at = { left: leftNo, right: rightNo };
+    if (edit.kind !== "+") leftNo++;
+    if (edit.kind !== "-") rightNo++;
+    return at;
+  });
+
+  let index = 0;
+  while (index < edits.length) {
+    if (edits[index]!.kind === " ") {
+      index++;
+      continue;
+    }
+    const hunkStart = Math.max(0, index - CONTEXT);
+    let lastChange = index;
+    let cursor = index + 1;
+    // Extend while the next change is within two contexts of the last one.
+    while (cursor < edits.length && cursor - lastChange <= 2 * CONTEXT) {
+      if (edits[cursor]!.kind !== " ") lastChange = cursor;
+      cursor++;
+    }
+    const hunkEnd = Math.min(edits.length, lastChange + CONTEXT + 1);
+
+    const slice = edits.slice(hunkStart, hunkEnd);
+    const leftCount = slice.filter((edit) => edit.kind !== "+").length;
+    const rightCount = slice.filter((edit) => edit.kind !== "-").length;
+    const at = positions[hunkStart]!;
+    out.push(`@@ -${range(at.left, leftCount)} +${range(at.right, rightCount)} @@`);
+    for (const edit of slice) out.push(`${edit.kind}${edit.text}`);
+    index = hunkEnd;
+  }
+  return out.join("\n") + "\n";
+}
+
+// --- The command -------------------------------------------------------------
+
+/** Runs `work`, turning any failure into the operational exit code. */
+async function operational<T>(work: () => T | Promise<T>): Promise<T> {
+  try {
+    return await work();
+  } catch (error) {
+    throw new CliError(messageOf(error), EXIT_DIFF_ERROR, { cause: error });
+  }
+}
+
+const keyOf = (kind: string, name: string): string => `${kind}/${name}`;
+
+export async function runDiff(
+  dir: string,
+  options: DiffOptions,
+  clients: LiveClients = SDK_CLIENTS,
+): Promise<DiffEntry[]> {
+  const target = parseInstanceArn(options.instance, EXIT_DIFF_ERROR);
+  const docs = await operational(() => loadDocs(dir));
+  const client = await operational(() => clients.inventory(target));
+  const result = await operational(() => exportInstance(client, { onError: "collect" }));
+
+  const live = new Map<string, ExportedFlow>();
+  for (const flow of result.flows) live.set(keyOf(flow.doc.kind, flow.doc.name), flow);
+  // A failed export still has a reverse-map entry, which says what it would
+  // have been called; that is how a local document learns its live twin is
+  // unreadable rather than absent.
+  const failed = new Map<string, ExportFailure>();
+  for (const failure of result.failures) {
+    const entry = result.reverseMap.byArn.get(normalizeArn(failure.arn));
+    if (entry !== undefined) failed.set(keyOf(entry.type, entry.name), failure);
+  }
+
+  const entries: DiffEntry[] = docs.map(({ path, doc }) => {
+    const rel = relative(process.cwd(), path);
+    const key = keyOf(doc.kind, doc.name);
+    const base = { path: rel, name: doc.name, kind: doc.kind };
+    const twin = live.get(key);
+    if (twin !== undefined) {
+      const saved = twin.saved === true;
+      const diff = unifiedDiff(
+        comparableLines(doc),
+        comparableLines(twin.doc),
+        `local/${rel}`,
+        saved ? `live/${doc.name}:${SAVED_MARKER}` : `live/${doc.name}`,
+      );
+      const matched =
+        diff === ""
+          ? { status: "unchanged" as const }
+          : { status: "changed" as const, detail: diff };
+      return { ...base, ...matched, ...(saved ? { saved } : {}) };
+    }
+    const failure = failed.get(key);
+    if (failure !== undefined) return { ...base, status: "error", detail: failure.reason };
+    return { ...base, status: "missing-live" };
+  });
+
+  for (const entry of entries) {
+    const marker = entry.saved === true ? ` (${SAVED_MARKER})` : "";
+    const suffix = entry.status === "error" ? `: ${entry.detail ?? ""}` : "";
+    console.log(`${entry.path}: ${entry.status}${marker}${suffix}`);
+    if (entry.status === "changed") process.stdout.write(entry.detail ?? "");
+  }
+
+  const errors = entries.filter((entry) => entry.status === "error").length;
+  if (errors > 0) {
+    throw new CliError(
+      `${String(errors)} document(s) could not be compared with ${target.arn}`,
+      EXIT_DIFF_ERROR,
+    );
+  }
+  const differing = entries.filter((entry) => entry.status !== "unchanged").length;
+  if (differing > 0) {
+    throw new CliError(
+      `${String(differing)} of ${String(entries.length)} document(s) differ from ${target.arn}`,
+    );
+  }
+  return entries;
+}

package/src/docs.ts

@@ -0,0 +1,249 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Loading FlowDocs for the commands that take a `<dir-or-file>` argument.
+//
+// One entry point, one set of diagnostics: a path that does not exist, a file
+// that is not JSON, and a document that does not satisfy the FlowDoc schema all
+// come out as a CliError naming the offending path. Every problem in the set is
+// reported, not just the first, so one run fixes one round of edits.
+//
+// schema/flowdoc-0.1.schema.json is a byte copy of
+// conformance/schema/flowdoc-0.1.schema.json, kept inside the package because
+// the conformance tree is not published. src/schema.test.ts fails if the two
+// drift, so the CLI and the cross-language contract cannot disagree.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { FlowDoc } from "@flow-as-code/core";
+import { NO_LITERAL_ARN, literalArnMessage, literalArnPaths } from "@flow-as-code/core";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import type { AnySchema, ValidateFunction } from "ajv";
+
+import { CliError, messageOf } from "./errors.js";
+
+/** A directory argument loads every file with this suffix, sorted by name. */
+export const FLOWDOC_SUFFIX = ".flowdoc.json";
+
+/** Errors reported for one document before the rest are elided. */
+const MAX_SCHEMA_ERRORS = 10;
+
+/** Absolute path of the packaged FlowDoc schema (`../schema` from src or dist). */
+export const SCHEMA_PATH = fileURLToPath(
+  new URL("../schema/flowdoc-0.1.schema.json", import.meta.url),
+);
+
+export interface LoadedDoc {
+  /** Absolute path the document was read from. */
+  path: string;
+  doc: FlowDoc;
+}
+
+let compiled: ValidateFunction | undefined;
+
+function flowDocValidator(): ValidateFunction {
+  if (compiled === undefined) {
+    const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf8")) as AnySchema;
+    compiled = new Ajv2020({ allErrors: true, strict: false }).compile(schema);
+  }
+  return compiled;
+}
+
+/** One schema violation, as "<where> <what>". */
+function describeSchemaError(error: { instancePath: string; message?: string }): string {
+  const where = error.instancePath === "" ? "(root)" : error.instancePath;
+  return `${where} ${error.message ?? "is invalid"}`;
+}
+
+/**
+ * An ajv instancePath (`/content/Actions/3/Parameters/QueueId`) in the dotted
+ * form @flow-as-code/core's string walker produces
+ * (`content.Actions[3].Parameters.QueueId`), so the two can be compared.
+ */
+function pointerToPath(instancePath: string): string {
+  let out = "";
+  for (const raw of instancePath.split("/").slice(1)) {
+    const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (/^\d+$/.test(segment)) out += `[${segment}]`;
+    else out += out === "" ? segment : `.${segment}`;
+  }
+  return out;
+}
+
+/** True when this schema error is describing one of the literal ARNs found. */
+function causedByLiteralArn(instancePath: string, arnPaths: readonly string[]): boolean {
+  const path = pointerToPath(instancePath);
+  const under = (parent: string, child: string): boolean =>
+    child.startsWith(`${parent}.`) || child.startsWith(`${parent}[`);
+  return arnPaths.some((arn) => arn === path || under(path, arn) || under(arn, path));
+}
+
+/**
+ * Problems with a value that claims to be a FlowDoc, empty when it is one. The
+ * studio bridge validates documents arriving over HTTP with exactly the
+ * validator every command uses on documents read from disk.
+ *
+ * A literal ARN is reported once per offending field, by rule id, rather than
+ * as the several schema pattern errors one ARN produces: the token pattern
+ * fails, the alternative `$.` pattern fails, their `oneOf` fails, and the
+ * enclosing `if/then` fails, none of which say "literal ARN". The schema stays
+ * the backstop, and every schema error the ARN did not cause is still shown.
+ *
+ * The ARN scan runs whether or not the schema is satisfied. Only ref-shaped
+ * fields carry a `${cdref:...}` pattern, so an ARN pasted into free text
+ * (`Parameters.Text`, a prompt, a label) is schema-valid; `no-literal-arn` is
+ * a hard rule and the bridge write path has no other lint step, so scanning
+ * only after a schema failure would let exactly those documents onto disk.
+ */
+export function flowDocProblems(value: unknown): string[] {
+  const validate = flowDocValidator();
+  const valid = validate(value);
+  const errors = valid ? [] : (validate.errors ?? []);
+  const arnPaths = literalArnPaths(value);
+  if (valid && arnPaths.length === 0) return [];
+  const problems = [
+    ...arnPaths.map((path) => `${NO_LITERAL_ARN}: ${literalArnMessage(path)}`),
+    ...errors.filter((e) => !causedByLiteralArn(e.instancePath, arnPaths)).map(describeSchemaError),
+  ];
+  const shown = problems.slice(0, MAX_SCHEMA_ERRORS);
+  if (problems.length > MAX_SCHEMA_ERRORS) {
+    shown.push(`... and ${String(problems.length - MAX_SCHEMA_ERRORS)} more`);
+  }
+  return shown;
+}
+
+/** A problem that names a lint rule already reads as a sentence on its own. */
+function isRuleProblem(problem: string): boolean {
+  return problem.startsWith(`${NO_LITERAL_ARN}: `);
+}
+
+/**
+ * Absolute paths of the documents a `<dir-or-file>` argument names. A directory
+ * contributes every `*.flowdoc.json` in it, sorted, and is not walked
+ * recursively; a file contributes itself whatever its extension.
+ */
+export function resolveDocPaths(target: string): string[] {
+  const abs = resolve(target);
+  let stat;
+  try {
+    stat = statSync(abs);
+  } catch {
+    throw new CliError(`No such file or directory: ${abs}`);
+  }
+  if (!stat.isDirectory()) return [abs];
+
+  const files = readdirSync(abs)
+    .filter((f) => f.endsWith(FLOWDOC_SUFFIX))
+    .sort()
+    .map((f) => join(abs, f));
+  if (files.length === 0) {
+    throw new CliError(`No *${FLOWDOC_SUFFIX} files in ${abs}`);
+  }
+  return files;
+}
+
+/** Reads and schema-validates every document a `<dir-or-file>` argument names. */
+export function loadDocs(target: string): LoadedDoc[] {
+  const validate = flowDocValidator();
+  const problems: string[] = [];
+  const loaded: LoadedDoc[] = [];
+
+  for (const path of resolveDocPaths(target)) {
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch (error) {
+      problems.push(`${path}: ${messageOf(error)}`);
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      problems.push(`${path}: invalid JSON: ${messageOf(error)}`);
+      continue;
+    }
+
+    if (!validate(parsed)) {
+      for (const problem of flowDocProblems(parsed)) {
+        problems.push(
+          problem.startsWith("... and ") || isRuleProblem(problem)
+            ? `${path}: ${problem}`
+            : `${path}: not a valid FlowDoc: ${problem}`,
+        );
+      }
+      continue;
+    }
+
+    loaded.push({ path, doc: parsed as FlowDoc });
+  }
+
+  if (problems.length > 0) {
+    throw new CliError(`${String(problems.length)} problem(s):\n  - ${problems.join("\n  - ")}`);
+  }
+  return loaded;
+}
+
+/** Loads the one document a single-file argument names, refusing a directory. */
+export function loadOneDoc(target: string, command: string): LoadedDoc {
+  const abs = resolve(target);
+  let stat;
+  try {
+    stat = statSync(abs);
+  } catch {
+    throw new CliError(`No such file or directory: ${abs}`);
+  }
+  if (stat.isDirectory()) {
+    throw new CliError(`${command} takes a single FlowDoc file, not a directory: ${abs}`);
+  }
+  const [only] = loadDocs(abs);
+  if (only === undefined) throw new CliError(`No FlowDoc loaded from ${abs}`);
+  return only;
+}
+
+/** Where a command writes when `--out` is absent: the directory of its input. */
+export function defaultOutDir(target: string): string {
+  const abs = resolve(target);
+  try {
+    return statSync(abs).isDirectory() ? abs : dirname(abs);
+  } catch {
+    throw new CliError(`No such file or directory: ${abs}`);
+  }
+}
+
+/**
+ * Reads a JSON file that must hold a flat string to string object: the resource
+ * map for `render` and the address map for `emit --target tf`.
+ */
+export function readStringMap(path: string, what: string): Record<string, string> {
+  const abs = resolve(path);
+  let raw: string;
+  try {
+    raw = readFileSync(abs, "utf8");
+  } catch {
+    throw new CliError(`No such file or directory: ${abs}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new CliError(`${abs}: invalid JSON: ${messageOf(error)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${abs}: the ${what} must be a JSON object of string to string.`);
+  }
+
+  const bad = Object.entries(parsed as Record<string, unknown>)
+    .filter(([, value]) => typeof value !== "string")
+    .map(([key]) => key)
+    .sort();
+  if (bad.length > 0) {
+    throw new CliError(`${abs}: the ${what} has non-string value(s) for: ${bad.join(", ")}`);
+  }
+  return parsed as Record<string, string>;
+}

package/src/emit.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli emit <dir> --target cdk|tf`.
+//
+// The two targets are not symmetric, because the two emitters are not.
+//
+// - tf is a real code generator: @flow-as-code/tf turns the document set into HCL plus
+//   .tftpl files. This command is a thin wrapper over `writeTf`, deliberately
+//   adding nothing of its own so the bytes it writes are exactly the bytes
+//   `emitTf` returns. src/cli.test.ts asserts that equality.
+// - cdk is a library binding: FlowSet reads the FlowDoc directory itself at
+//   synth time, so there is nothing per-document to emit and what gets written
+//   is a stack scaffold with a TODO binder. See cdk-scaffold.ts.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { EmitTfError, writeTf } from "@flow-as-code/tf";
+
+import { CDK_SCAFFOLD_FILE, cdkScaffoldForDirs } from "./cdk-scaffold.js";
+import { defaultOutDir, loadDocs, readStringMap } from "./docs.js";
+import { CliError } from "./errors.js";
+
+export type EmitTarget = "cdk" | "tf";
+
+export interface EmitOptions {
+  target: string;
+  addressMap?: string;
+  out?: string;
+}
+
+const TARGETS = new Set<string>(["cdk", "tf"]);
+
+export function runEmit(input: string, options: EmitOptions): string[] {
+  if (!TARGETS.has(options.target)) {
+    throw new CliError(`Unknown --target "${options.target}". Use "cdk" or "tf".`);
+  }
+  if (options.target === "cdk" && options.addressMap !== undefined) {
+    throw new CliError("--address-map applies to --target tf only; the cdk target uses a binder.");
+  }
+
+  const docsDir = defaultOutDir(input);
+  const docs = loadDocs(input).map((l) => l.doc);
+  const outDir = resolve(options.out ?? docsDir);
+  mkdirSync(outDir, { recursive: true });
+
+  if (options.target === "tf") {
+    const addressMap =
+      options.addressMap === undefined
+        ? undefined
+        : readStringMap(options.addressMap, "address map");
+    let result;
+    try {
+      result = writeTf(docs, outDir, addressMap === undefined ? {} : { addressMap });
+    } catch (error) {
+      if (error instanceof EmitTfError) throw new CliError(error.message);
+      throw error;
+    }
+    return Object.keys(result.files)
+      .sort()
+      .map((file) => join(outDir, file));
+  }
+
+  const path = join(outDir, CDK_SCAFFOLD_FILE);
+  writeFileSync(path, cdkScaffoldForDirs({ docs, outDir, docsDir }), "utf8");
+  return [path];
+}