@flow-as-code/core 0.1.0

package/src/lint/types.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Lint engine types.
+//
+// Nothing in this directory may import a Node builtin. The studio runs the
+// engine in a web worker, so the whole module graph has to be browser-safe.
+// Enforced by lint-browser-safe.test.ts, which walks the imports statically.
+
+import type { FlowDoc } from "../flowdoc.js";
+
+export type Severity = "error" | "warning";
+
+export interface Finding {
+  /** Stable rule id. Never renamed; the Go provider keys off these. */
+  rule: string;
+  severity: Severity;
+  message: string;
+  /** Name of the FlowDoc the finding belongs to. */
+  doc: string;
+  /** Action Identifier, when the finding is about one action. */
+  blockId?: string;
+}
+
+export interface RuleContext {
+  doc: FlowDoc;
+  /** Every doc being linted, for rules that need to follow module references. */
+  all: readonly FlowDoc[];
+  report(finding: Omit<Finding, "rule" | "doc">): void;
+}
+
+export interface Rule {
+  id: string;
+  description: string;
+  /**
+   * A hard rule blocks a save in the studio rather than merely reporting.
+   * docs/02-studio-design.md: the studio can never save a doc that fails
+   * no-literal-arn or no-unresolved-token.
+   */
+  hard?: boolean;
+  check(ctx: RuleContext): void;
+}

package/src/materialize.ts

@@ -0,0 +1,230 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Materialization: FlowDoc in, deployable Flow language content out.
+//
+// Two backends resolve `${cdref:...}` tokens (SPEC.md, Materialization):
+//   - materializeWithMap: strict lookup in a token -> value map; every missing
+//     token is reported at once in a MaterializeError.
+//   - materializeWithBinder: the binder returns opaque strings (CDK or
+//     CloudFormation tokens). They pass through byte-for-byte with no
+//     validation and no arn-shape checks, because intrinsics are resolved by
+//     CloudFormation long after this code runs.
+//
+// Both backends emit content ONLY: `layout`, `refs`, and `meta` are tool
+// metadata and are dropped. Before dropping, `layout` is projected into
+// `content.Metadata` so the flow lays out correctly in the Connect console
+// (docs/01-flowdoc-spec.md). The Metadata shape follows the Flow language
+// example, which uses EntryPointPosition and ActionMetadata.<id>.Position:
+// https://docs.aws.amazon.com/connect/latest/devguide/flow-language-example.html
+
+import type { FlowAction, FlowContent, FlowDoc, Point, RefEntry } from "./flowdoc.js";
+import { InvalidFlowDocError, assertFlowDoc } from "./flowdoc.js";
+import { autoLayout } from "./layout.js";
+import { collectRefs, parseToken } from "./refs.js";
+import { canonicalAction, ordered, sortKeys } from "./serialize.js";
+
+/**
+ * Strict map materialization failed: one or more tokens in the document have
+ * no entry in the resource map. `missingTokens` is sorted and complete, so a
+ * caller fixes the map once, not one missing key per run.
+ */
+export class MaterializeError extends Error {
+  readonly missingTokens: readonly string[];
+
+  constructor(missingTokens: readonly string[], reason?: string) {
+    super(
+      reason === undefined
+        ? `Cannot materialize: ${String(missingTokens.length)} unmapped token(s): ` +
+            missingTokens.join(", ")
+        : `Cannot materialize: ${reason} Offending token(s): ${missingTokens.join(", ")}`,
+    );
+    this.name = "MaterializeError";
+    this.missingTokens = missingTokens;
+  }
+}
+
+/**
+ * A reference token occupies an entire field value and is never interpolated
+ * into a longer string (FlowDoc invariant 4), so replacement only ever swaps
+ * whole string values. Binder output is inserted exactly as returned.
+ */
+function resolveDeep(value: unknown, resolve: (entry: RefEntry) => string): unknown {
+  if (typeof value === "string") {
+    const entry = parseToken(value);
+    return entry === undefined ? value : resolve(entry);
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveDeep(v, resolve));
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([k, v]) => [
+        k,
+        resolveDeep(v, resolve),
+      ]),
+    );
+  }
+  return value;
+}
+
+/** How far left of the StartAction block the console entry point marker sits. */
+const ENTRY_POINT_OFFSET_X = 100;
+
+/**
+ * Projects `layout` into the Metadata shape the console reads. Positions come
+ * from the document's layout; any action without one gets the same
+ * deterministic auto-layout synth would have assigned. Keys an imported
+ * document may already carry in content.Metadata are preserved; only the
+ * position keys are overwritten, because `layout` is the single source of
+ * truth for position (docs/01-flowdoc-spec.md).
+ */
+function projectLayout(
+  doc: FlowDoc,
+  resolve: (entry: RefEntry) => string,
+): Record<string, unknown> {
+  const actions = doc.content.Actions;
+  const layout = doc.layout ?? {};
+  const missing = actions.some((a) => layout[a.Identifier] === undefined);
+  const auto = missing ? autoLayout(actions) : {};
+
+  // Pre-existing Metadata (an imported document, say) is carried through, and
+  // it is RESOLVED like everything else: the strictness check scans the whole
+  // content, so substitution must cover the whole content too, or a token
+  // could survive into deployable output.
+  const existing = resolveDeep(doc.content.Metadata ?? {}, resolve) as Record<string, unknown>;
+  const existingRaw = existing.ActionMetadata;
+  const existingActionMetadata =
+    existingRaw !== null && typeof existingRaw === "object" && !Array.isArray(existingRaw)
+      ? (existingRaw as Record<string, unknown>)
+      : {};
+
+  // Start from what was already there (entries for unknown ids survive; never
+  // drop content), then overlay Position per action: layout is the single
+  // source of truth for position, but sibling keys inside an entry are kept.
+  const actionMetadata: Record<string, unknown> = { ...existingActionMetadata };
+  const positions: Record<string, Point> = {};
+  for (const a of actions) {
+    const p = layout[a.Identifier] ?? auto[a.Identifier] ?? { x: 0, y: 0 };
+    positions[a.Identifier] = p;
+    const prior = actionMetadata[a.Identifier];
+    const priorEntry =
+      prior !== null && typeof prior === "object" && !Array.isArray(prior)
+        ? (prior as Record<string, unknown>)
+        : {};
+    actionMetadata[a.Identifier] = { ...priorEntry, Position: { x: p.x, y: p.y } };
+  }
+
+  // The example places the entry point marker left of the first block
+  // (EntryPointPosition x=88 vs first Action x=270).
+  const start = positions[doc.content.StartAction] ?? { x: 0, y: 0 };
+  const entryPointPosition = { x: Math.max(start.x - ENTRY_POINT_OFFSET_X, 0), y: start.y };
+
+  return {
+    ...existing,
+    EntryPointPosition: entryPointPosition,
+    ActionMetadata: actionMetadata,
+  };
+}
+
+function materialize(doc: FlowDoc, resolve: (entry: RefEntry) => string): FlowContent {
+  // A module requires a top-level Settings in its deployable content; Connect
+  // rejects the create without it. Default to {} when the doc does not carry
+  // one; resolve tokens in it for consistency with the rest of the content.
+  const settings =
+    doc.kind === "module" || doc.content.Settings !== undefined
+      ? (resolveDeep(doc.content.Settings ?? {}, resolve) as Record<string, unknown>)
+      : undefined;
+  return {
+    Version: doc.content.Version,
+    StartAction: doc.content.StartAction,
+    ...(settings === undefined ? {} : { Settings: settings }),
+    Metadata: projectLayout(doc, resolve),
+    Actions: doc.content.Actions.map((a) => resolveDeep(a, resolve) as FlowAction),
+  };
+}
+
+/**
+ * Strict materialization against a token -> value map. Every token in the
+ * content must have an entry; otherwise a MaterializeError lists ALL missing
+ * tokens (sorted), not just the first. Mapped values are not validated: at
+ * this point literal ARNs are the goal, not a mistake.
+ */
+export function materializeWithMap(doc: FlowDoc, resourceMap: Record<string, string>): FlowContent {
+  assertFlowDoc(doc, "materializeWithMap");
+  if (typeof resourceMap !== "object" || resourceMap === null || Array.isArray(resourceMap)) {
+    throw new InvalidFlowDocError(
+      "materializeWithMap expects a token to value map object as its second argument.",
+    );
+  }
+  const missing = collectRefs(doc.content)
+    .map((e) => e.token)
+    .filter((t) => !Object.hasOwn(resourceMap, t));
+  if (missing.length > 0) throw new MaterializeError(missing);
+
+  const content = materialize(doc, (entry) => resourceMap[entry.token] as string);
+
+  // Completeness is not enough. collectRefs finds a token anywhere in a string
+  // while substitution only replaces a whole-value token, so an interpolated
+  // token used to satisfy the check above and then survive into deployable
+  // output as literal text that Connect would read aloud. Refusing here means
+  // render and emit, which do not run lint, cannot ship one either.
+  const leaked = [...new Set(JSON.stringify(content).match(/\$\{cdref:[^}"]*\}/g) ?? [])].sort();
+  if (leaked.length > 0) {
+    throw new MaterializeError(
+      leaked,
+      "Token(s) survived materialization because they are embedded in a longer string. " +
+        "A reference must be the entire field value (FlowDoc invariant 4).",
+    );
+  }
+  return content;
+}
+
+/**
+ * Binder materialization for IaC backends (@flow-as-code/cdk). The binder returns an
+ * opaque string per reference, typically a CDK token that CloudFormation later
+ * resolves to an ARN. Output passes through exactly as returned, with no
+ * validation and no arn-shape lint (SPEC.md, Materialization).
+ */
+export function materializeWithBinder(
+  doc: FlowDoc,
+  binder: (ref: RefEntry) => string,
+): FlowContent {
+  assertFlowDoc(doc, "materializeWithBinder");
+  if (typeof binder !== "function") {
+    throw new InvalidFlowDocError(
+      "materializeWithBinder expects a binder function as its second argument.",
+    );
+  }
+  return materialize(doc, binder);
+}
+
+// --- Deterministic serialization of deployable content -----------------------
+// Mirrors serialize.ts: fixed first-class key order, alphabetical for the
+// rest, two-space indent, trailing newline. Byte-identical for the same
+// content regardless of insertion order.
+
+/**
+ * Canonical JSON text of deployable content, two-space indented, newline
+ * terminated. Metadata leads with EntryPointPosition then ActionMetadata,
+ * matching the Flow language example; everything nested is key-sorted.
+ */
+export function serializeContent(content: FlowContent): string {
+  const canonical = ordered(
+    {
+      Version: content.Version,
+      StartAction: content.StartAction,
+      ...(content.Settings === undefined ? {} : { Settings: sortKeys(content.Settings) }),
+      ...(content.Metadata === undefined
+        ? {}
+        : {
+            Metadata: ordered(sortKeys(content.Metadata) as Record<string, unknown>, [
+              "EntryPointPosition",
+              "ActionMetadata",
+            ]),
+          }),
+      Actions: content.Actions.map(canonicalAction),
+    },
+    ["Version", "StartAction", "Settings", "Metadata", "Actions"],
+  );
+  return JSON.stringify(canonical, null, 2) + "\n";
+}

package/src/package-names.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The one place the npm package names are written down as values.
+//
+// Everything that embeds a package name in its output, rather than importing
+// it, reads it from here: codegen's default import, the cdk stack scaffold,
+// the tf "generated by" banner, and the CLI's studio asset resolution. A
+// rename is then one edit to PACKAGE_SCOPE plus the package.json files, and a
+// test in core keeps this file honest against those manifests.
+//
+// The hosted demo build (docs/05-hosted-demo.md) aliases this module to a
+// neutral placeholder so no package name reaches the deployed artifact.
+
+/** The npm scope every package publishes under. */
+export const PACKAGE_SCOPE = "@flow-as-code";
+
+/** Published package names, keyed by their short names. */
+export const PACKAGE_NAMES = {
+  core: `${PACKAGE_SCOPE}/core`,
+  cdk: `${PACKAGE_SCOPE}/cdk`,
+  cli: `${PACKAGE_SCOPE}/cli`,
+  tf: `${PACKAGE_SCOPE}/tf`,
+  studio: `${PACKAGE_SCOPE}/studio`,
+} as const;

package/src/refs.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Reference tokens. A reference occupies an entire field value and is never
+// interpolated into a longer string: Connect requires the fields that hold
+// references to be "either fully static or a single valid JSONPath
+// identifier". See conformance/flow-language/actions.md.
+
+import type { RefEntry, RefType } from "./flowdoc.js";
+import { SLUG_PATTERN } from "./flowdoc.js";
+
+/**
+ * A reference token, branded with the kind of resource it points at, so a
+ * queue cannot be passed where a Lambda is expected.
+ */
+export type Ref<T extends RefType = RefType> = string & { readonly __ref: T };
+
+/** A single JSONPath identifier, the dynamic alternative to a reference. */
+export type JsonPath = string & { readonly __jsonPath: true };
+
+/** A value legal in a reference-bearing parameter. */
+export type RefValue<T extends RefType> = Ref<T> | JsonPath;
+
+export const TOKEN_PATTERN =
+  /^\$\{cdref:(queue|hours|lambda|lex|prompt|flow|module):([a-z0-9]+(?:-[a-z0-9]+)*)(?:@([a-z0-9]+(?:-[a-z0-9]+)*))?\}$/;
+
+/** Matches tokens anywhere in a string, for building the refs index. */
+const TOKEN_SCAN = /\$\{cdref:[a-z]+:[^}]+\}/g;
+
+const JSONPATH_PATTERN = /^\$\.[A-Za-z0-9_$.[\]'-]+$/;
+
+function assertSlug(kind: string, value: string): void {
+  if (!SLUG_PATTERN.test(value)) {
+    throw new Error(
+      `Invalid ${kind} "${value}". Names must be lowercase words separated by single hyphens.`,
+    );
+  }
+}
+
+function token<T extends RefType>(type: T, name: string, alias?: string): Ref<T> {
+  assertSlug(`${type} name`, name);
+  if (alias !== undefined) assertSlug("module alias", alias);
+  const suffix = alias === undefined ? "" : `@${alias}`;
+  return `\${cdref:${type}:${name}${suffix}}` as Ref<T>;
+}
+
+export const Refs = {
+  queue: (name: string): Ref<"queue"> => token("queue", name),
+  hours: (name: string): Ref<"hours"> => token("hours", name),
+  lambda: (name: string): Ref<"lambda"> => token("lambda", name),
+  lex: (name: string): Ref<"lex"> => token("lex", name),
+  prompt: (name: string): Ref<"prompt"> => token("prompt", name),
+  flow: (name: string): Ref<"flow"> => token("flow", name),
+  /** Module references carry an alias so a flow can pin which version it invokes. */
+  module: (name: string, alias: string): Ref<"module"> => token("module", name, alias),
+} as const;
+
+/** Wraps a JSONPath expression for use in a reference-bearing parameter. */
+export function jsonPath(path: string): JsonPath {
+  if (!JSONPATH_PATTERN.test(path)) {
+    throw new Error(
+      `Invalid JSONPath "${path}". Expected a single identifier such as $.Attributes.queueId.`,
+    );
+  }
+  return path as JsonPath;
+}
+
+export function isToken(value: unknown): value is Ref {
+  return typeof value === "string" && TOKEN_PATTERN.test(value);
+}
+
+export function parseToken(value: string): RefEntry | undefined {
+  const m = TOKEN_PATTERN.exec(value);
+  if (!m) return undefined;
+  const [, type, name, alias] = m;
+  const entry: RefEntry = { token: value, type: type as RefType, name: name! };
+  if (alias !== undefined) entry.alias = alias;
+  return entry;
+}
+
+/**
+ * Derived index of every token in a document, sorted by token so the output is
+ * stable. Regenerated on save; never hand-maintained.
+ */
+export function collectRefs(value: unknown): RefEntry[] {
+  const found = new Map<string, RefEntry>();
+  for (const raw of JSON.stringify(value ?? null).match(TOKEN_SCAN) ?? []) {
+    const entry = parseToken(raw);
+    if (entry) found.set(entry.token, entry);
+  }
+  return [...found.values()].sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+}

package/src/serialize.ts

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Deterministic serialization. Invariant 1 of the FlowDoc spec: same inputs,
+// byte-identical output. Two authorings of the same flow must produce the same
+// bytes, so key order is fixed rather than insertion-dependent.
+
+import type { FlowAction, FlowDoc, Transitions } from "./flowdoc.js";
+
+/** Recursively sorts object keys. Arrays keep their order, which is meaningful. */
+export function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value === null || typeof value !== "object") return value;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  );
+  return Object.fromEntries(entries.map(([k, v]) => [k, sortKeys(v)]));
+}
+
+/** Emits keys in the given order, then anything else alphabetically. */
+export function ordered<T extends Record<string, unknown>>(value: T, keys: (keyof T)[]): T {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) {
+    if (value[k as string] !== undefined) out[k as string] = value[k as string];
+  }
+  for (const k of Object.keys(value).sort()) {
+    if (!keys.includes(k) && value[k] !== undefined) out[k] = value[k];
+  }
+  return out as T;
+}
+
+function canonicalTransitions(t: Transitions): Transitions {
+  // The arrays' ELEMENTS need canonicalizing too. Ordering only the top level
+  // copied Errors and Conditions by reference, so { ErrorType, NextAction } and
+  // { NextAction, ErrorType } serialized to different bytes: two authorings of
+  // the same flow produced different output, and downstream a different
+  // CloudFormation logical id.
+  const canonical: Record<string, unknown> = { ...(t as Record<string, unknown>) };
+  if (t.Errors !== undefined) {
+    canonical.Errors = t.Errors.map((e) => ordered({ ...e }, ["ErrorType", "NextAction"]));
+  }
+  if (t.Conditions !== undefined) {
+    canonical.Conditions = t.Conditions.map((c) =>
+      ordered(
+        {
+          NextAction: c.NextAction,
+          Condition: ordered({ ...c.Condition }, ["Operator", "Operands"]),
+        },
+        ["NextAction", "Condition"],
+      ),
+    );
+  }
+  return ordered(canonical, ["NextAction", "Errors", "Conditions"]) as unknown as Transitions;
+}
+
+export function canonicalAction(a: FlowAction): FlowAction {
+  return {
+    Identifier: a.Identifier,
+    Type: a.Type,
+    // Parameters are opaque to us for GenericBlocks, so sort for stability.
+    Parameters: sortKeys(a.Parameters) as Record<string, unknown>,
+    Transitions: canonicalTransitions(a.Transitions),
+  };
+}
+
+/**
+ * Canonical in-memory form. Key order below is the byte order of the output.
+ */
+export function canonicalize(doc: FlowDoc): FlowDoc {
+  const out: Record<string, unknown> = {
+    flowdoc: doc.flowdoc,
+    kind: doc.kind,
+    name: doc.name,
+    connectType: doc.connectType,
+    content: ordered(
+      {
+        Version: doc.content.Version,
+        StartAction: doc.content.StartAction,
+        ...(doc.content.Settings === undefined ? {} : { Settings: sortKeys(doc.content.Settings) }),
+        ...(doc.content.Metadata === undefined ? {} : { Metadata: sortKeys(doc.content.Metadata) }),
+        Actions: doc.content.Actions.map(canonicalAction),
+      } as Record<string, unknown>,
+      ["Version", "StartAction", "Settings", "Metadata", "Actions"],
+    ),
+  };
+  if (doc.layout !== undefined) out.layout = sortKeys(doc.layout);
+  if (doc.refs !== undefined)
+    out.refs = doc.refs.map((r) => ordered({ ...r }, ["token", "type", "name", "alias"]));
+  if (doc.meta !== undefined) out.meta = sortKeys(doc.meta);
+  return out as unknown as FlowDoc;
+}
+
+/** Canonical JSON text, two-space indented, newline terminated. */
+export function serialize(doc: FlowDoc): string {
+  return JSON.stringify(canonicalize(doc), null, 2) + "\n";
+}