@flow-as-code/cli 0.1.0

package/src/errors.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Terminal-facing errors. Every command surfaces failures as a CliError whose
+// message is already written for a human: the offending path, the offending
+// token, or the flag that was wrong, on stderr, with nothing else added.
+
+/**
+ * A failure with a message meant for the terminal, and the exit code to use.
+ * `cause` carries the error it was written from, for callers of the command
+ * functions; the terminal only ever sees the message.
+ */
+export class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode = 1, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+/** Message of an unknown thrown value, without a stack trace. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/export.ts

@@ -0,0 +1,167 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli export --instance <arn> [--out <dir>] [--no-codegen] [--on-error abort|collect]`.
+//
+// Reads every flow and module in a live instance through @flow-as-code/core's
+// exportInstance and writes one `<name>.flowdoc.json` per document, plus
+// `<name>.flow.ts` unless --no-codegen, into --out (default: the working
+// directory). The name is the slug the exporter derives from the console name,
+// which is also how `diff` finds the live counterpart of a local document.
+//
+// --on-error defaults to collect, not abort, because a fresh instance always
+// holds the stock "Sample Lambda integration" flow, which calls a Lambda in an
+// AWS-owned account that ListLambdaFunctions cannot return. That flow is an
+// unknown-ARN hard error by design (packages/core/SPEC.md, Export), and
+// aborting on it would make a first export of any new instance write nothing.
+// Collect writes everything else and reports every failure at once; either
+// mode exits 1 when any flow failed.
+//
+// Both halves of a pair are written the way `synth` and the studio write them:
+// the document carries `meta.sourceHash` of the generated source, so the watch
+// engine sees an exported pair as in sync rather than as a conflict. An
+// existing `<name>.flow.ts` is read first so its `@keep` comments survive, as
+// `codegen` does.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import type { ExportFailure, ExportedFlow, FlowDoc } from "@flow-as-code/core";
+import { codegen, collectInventory, exportInstance, serialize } from "@flow-as-code/core";
+
+import { type LiveClients, parseInstanceArn, SDK_CLIENTS } from "./aws.js";
+import { FLOWDOC_SUFFIX } from "./docs.js";
+import { CliError, messageOf } from "./errors.js";
+import { GENERATOR, sha256Hex } from "./synth.js";
+
+export const TS_SUFFIX = ".flow.ts";
+
+export interface ExportOptions {
+  instance: string;
+  out?: string;
+  /** commander's `--no-codegen` sets this false; absent means generate. */
+  codegen?: boolean;
+  onError?: string;
+}
+
+const ON_ERROR = new Set<string>(["abort", "collect"]);
+
+/** One document written to disk. */
+export interface WrittenDoc {
+  name: string;
+  kind: FlowDoc["kind"];
+  /** Paths relative to the output directory, document first. */
+  files: string[];
+  /** True when the content came through the `$SAVED` alias (never published). */
+  saved: boolean;
+}
+
+export interface ExportOutcome {
+  outDir: string;
+  written: WrittenDoc[];
+  failures: ExportFailure[];
+  warnings: string[];
+}
+
+/** Writes one exported document, and its source when asked. */
+function writeExported(flow: ExportedFlow, outDir: string, withCode: boolean): WrittenDoc {
+  const { doc } = flow;
+  const docFile = `${doc.name}${FLOWDOC_SUFFIX}`;
+  const files = [docFile];
+  let text: string;
+
+  if (withCode) {
+    const tsFile = `${doc.name}${TS_SUFFIX}`;
+    const tsPath = join(outDir, tsFile);
+    const previous = existsSync(tsPath) ? readFileSync(tsPath, "utf8") : undefined;
+    const source = codegen(doc, previous === undefined ? {} : { previous });
+    writeFileSync(tsPath, source, "utf8");
+    files.push(tsFile);
+    text = serialize({ ...doc, meta: { ...doc.meta, sourceHash: `sha256:${sha256Hex(source)}` } });
+  } else {
+    text = serialize(doc);
+  }
+  writeFileSync(join(outDir, docFile), text, "utf8");
+
+  return { name: doc.name, kind: doc.kind, files, saved: flow.saved === true };
+}
+
+export async function runExport(
+  options: ExportOptions,
+  clients: LiveClients = SDK_CLIENTS,
+): Promise<ExportOutcome> {
+  const onError = options.onError ?? "collect";
+  if (!ON_ERROR.has(onError)) {
+    throw new CliError(`Unknown --on-error "${onError}". Use "abort" or "collect".`);
+  }
+  const target = parseInstanceArn(options.instance);
+  const outDir = resolve(options.out ?? ".");
+  const withCode = options.codegen !== false;
+
+  const client = await clients.inventory(target);
+  // The inventory is listed on its own, apart from the flows: a refused list
+  // call, throttling, or the network failing there is not a flow failure, so
+  // --on-error has no say in it and the SDK's message is passed through as is.
+  let inventory;
+  try {
+    inventory = await collectInventory(client);
+  } catch (error) {
+    throw new CliError(messageOf(error), 1, { cause: error });
+  }
+  let result;
+  try {
+    result = await exportInstance(client, {
+      inventory,
+      onError: onError === "abort" ? "throw" : "collect",
+      generator: GENERATOR,
+    });
+  } catch (error) {
+    // With the inventory in hand, exportInstance throws only for a flow, and
+    // only in abort mode; collect records every flow failure in `failures`.
+    throw new CliError(`export aborted (--on-error abort): ${messageOf(error)}`, 1, {
+      cause: error,
+    });
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const failures = [...result.failures];
+  const written: WrittenDoc[] = [];
+  // Flow and module names are unique per kind, not across kinds, and both
+  // kinds write <name>.flowdoc.json. The second one is a failure, not a
+  // silent overwrite.
+  const claimed = new Map<string, ExportedFlow>();
+
+  for (const flow of result.flows) {
+    const other = claimed.get(flow.doc.name);
+    if (other !== undefined) {
+      failures.push({
+        arn: flow.arn,
+        name: flow.sourceName,
+        reason:
+          `a ${other.doc.kind} and a ${flow.doc.kind} both slug to "${flow.doc.name}"; ` +
+          `not written, ${other.doc.name}${FLOWDOC_SUFFIX} holds the ${other.doc.kind}`,
+      });
+      continue;
+    }
+    claimed.set(flow.doc.name, flow);
+    written.push(writeExported(flow, outDir, withCode));
+  }
+
+  for (const warning of result.warnings) console.error(`warning: ${warning}`);
+  for (const doc of written) {
+    const tag = doc.saved ? `${doc.kind}, $SAVED` : doc.kind;
+    console.log(`${doc.name} (${tag}): ${doc.files.join(", ")}`);
+  }
+  for (const failure of failures) {
+    console.error(`failed: ${failure.name} (${failure.arn}): ${failure.reason}`);
+  }
+  console.log(
+    `Exported ${String(written.length)} of ${String(written.length + failures.length)} to ${outDir}`,
+  );
+
+  if (failures.length > 0) {
+    throw new CliError(`${String(failures.length)} flow(s) could not be exported`);
+  }
+  return { outDir, written, failures, warnings: result.warnings };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Library entry. Importing this package must not run the CLI, so the commander
+// program lives in ./bin.ts and nothing here has a side effect at load time.
+// The three subpath exports (./synth, ./watch, ./bridge) are the public API and
+// this module is their union; src/index.test.ts holds the two in step.
+
+import { pathToFileURL } from "node:url";
+
+export * from "./synth.js";
+export * from "./watch.js";
+export * from "./bridge/server.js";
+
+// Before the bin split this file was the CLI, so `node .../dist/index.js studio`
+// still exists in scripts and in muscle memory. Left alone it now exits 0 having
+// done nothing, which reads as success. Refuse instead, but only when this module
+// is the process entry point: on the import path argv[1] is some other script (or
+// undefined under `node -e`), the branch is not taken, and importing stays free of
+// side effects.
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  process.stderr.write(
+    "flow-cli: this is the library entry and runs no commands. Run the CLI as dist/bin.js (or the installed flow-cli bin).\n",
+  );
+  process.exit(1);
+}

package/src/lint.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli lint <dir-or-file>`.
+//
+// The whole document set goes to @flow-as-code/core's lint in ONE call. Rules receive
+// `all` alongside `doc` (packages/core/src/lint/types.ts), and the ones
+// that follow module references need the rest of the set to answer at all:
+// linting file by file would silently downgrade module-depth-5 and every other
+// cross-document rule to a no-op.
+//
+// Exit status is severity, not finding count: any `error` exits 1, warnings
+// alone exit 0.
+
+import { lint, toJson, toText } from "@flow-as-code/core";
+
+import { loadDocs } from "./docs.js";
+import { CliError } from "./errors.js";
+
+export type LintFormat = "text" | "json";
+
+export interface LintOptions {
+  format?: string;
+}
+
+const FORMATS = new Set<string>(["text", "json"]);
+
+export function runLint(target: string, options: LintOptions): void {
+  const format = options.format ?? "text";
+  if (!FORMATS.has(format)) {
+    throw new CliError(`Unknown --format "${format}". Use "text" or "json".`);
+  }
+
+  const findings = lint(loadDocs(target).map((l) => l.doc));
+  process.stdout.write(format === "json" ? toJson(findings) : toText(findings));
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  if (errors > 0) {
+    throw new CliError(`lint failed: ${String(errors)} error-severity finding(s) in ${target}`);
+  }
+}

package/src/render.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli render <dir-or-file> --resources <map.json>`: standalone
+// materialization. FlowDoc in, deployable Flow language JSON out, with every
+// `${cdref:...}` token replaced from the resource map.
+//
+// This is the one path where literal ARNs are the goal rather than a mistake
+// (packages/core/SPEC.md, Materialization), so the map's values are not
+// linted. What is enforced is completeness: @flow-as-code/core's MaterializeError
+// carries every unmapped token, and all of them are printed, for every
+// document, before the command exits 1. One run, one round of map edits.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { MaterializeError, materializeWithMap, serializeContent } from "@flow-as-code/core";
+
+import { defaultOutDir, loadDocs, readStringMap } from "./docs.js";
+import { CliError } from "./errors.js";
+
+export interface RenderOptions {
+  resources: string;
+  out?: string;
+}
+
+export function runRender(target: string, options: RenderOptions): string[] {
+  const docs = loadDocs(target);
+  const resourceMap = readStringMap(options.resources, "resource map");
+  const outDir = resolve(options.out ?? defaultOutDir(target));
+
+  const problems: string[] = [];
+  const rendered: { path: string; text: string }[] = [];
+  for (const { path, doc } of docs) {
+    try {
+      rendered.push({
+        path: join(outDir, `${doc.name}.json`),
+        text: serializeContent(materializeWithMap(doc, resourceMap)),
+      });
+    } catch (error) {
+      if (!(error instanceof MaterializeError)) throw error;
+      problems.push(`${path}: ${String(error.missingTokens.length)} unmapped token(s):`);
+      for (const token of error.missingTokens) problems.push(`    ${token}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new CliError(
+      `Cannot render:\n  ${problems.join("\n  ")}\n` +
+        `Add the missing key(s) to ${resolve(options.resources)}.`,
+    );
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  for (const { path, text } of rendered) writeFileSync(path, text, "utf8");
+  return rendered.map((r) => r.path);
+}

package/src/run.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The one place a command's failure becomes an exit code.
+//
+// Every action is wrapped, so no command can throw past commander: a CliError
+// prints its own message and its own code, anything else prints its message and
+// exits 1. Nothing prints a stack trace, because a stack trace is never the
+// answer to "which file is wrong".
+
+import type { CommanderError } from "commander";
+
+import { CliError, messageOf } from "./errors.js";
+
+/** Wraps a command body so it reports failures as a message plus an exit code. */
+export function action<A extends unknown[]>(
+  body: (...args: A) => void | Promise<void>,
+): (...args: A) => Promise<void> {
+  return async (...args: A): Promise<void> => {
+    try {
+      await body(...args);
+    } catch (error) {
+      console.error(messageOf(error));
+      process.exitCode = error instanceof CliError ? error.exitCode : 1;
+    }
+  };
+}
+
+/**
+ * For a command's `exitOverride`: commander's own usage errors (a required
+ * option not given, an unknown option, a missing argument) exit with `code`
+ * instead of its default 1, so a command that reserves 1 for a result can
+ * keep bad arguments apart from it. Commander has written the message to
+ * stderr by the time this runs; help and version exit 0 and are left alone.
+ * https://github.com/tj/commander.js#override-exit-and-output-handling
+ */
+export function usageErrorsExit(code: number): (error: CommanderError) => void {
+  return (error) => {
+    if (error.exitCode !== 0) process.exit(code);
+  };
+}

package/src/simulate.ts

@@ -0,0 +1,244 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli simulate <scenarios> --instance <arn> [--resource-map <file>] [--format junit|json] [--out <file>]`.
+//
+// Runs a scenario suite through @flow-as-code/core's runScenarios, which owns the
+// TestCase lifecycle (create published, execute, poll, collect, delete) and the
+// documented limits: 5 concurrent, 100 in flight including the running 5,
+// 5 minutes per scenario.
+// https://docs.aws.amazon.com/connect/latest/adminguide/testing-simulation-execute-test-cases.html
+//
+// Everything that can fail offline fails before the instance is touched, and
+// all at once: every scenario file is schema-validated against the packaged
+// byte copy of conformance/schema/scenario-0.1.schema.json, then checked by
+// @flow-as-code/core's validateScenario for the cross-field rules the schema cannot
+// express, and every ${cdref:...} token is resolved against --resource-map. A
+// suite with one broken scenario creates no test case.
+//
+// The report goes to --out or stdout; failures also go to stderr, one block per
+// scenario that did not pass, so a CI log says why without opening the XML.
+// Exit 0 means every scenario PASSED. Anything else (FAILED, TIMED_OUT,
+// ERRORED, STOPPED) exits 1.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { RunOptions, Scenario, ScenarioResult, SimulationRun } from "@flow-as-code/core";
+import {
+  compileScenario,
+  jsonReport,
+  junitReport,
+  resolveScenario,
+  runScenarios,
+  validateScenario,
+} from "@flow-as-code/core";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import type { AnySchema, ValidateFunction } from "ajv";
+
+import { type LiveClients, parseInstanceArn, SDK_CLIENTS } from "./aws.js";
+import { readStringMap } from "./docs.js";
+import { CliError, messageOf } from "./errors.js";
+
+/** Absolute path of the packaged scenario schema (`../schema` from src or dist). */
+export const SCENARIO_SCHEMA_PATH = fileURLToPath(
+  new URL("../schema/scenario-0.1.schema.json", import.meta.url),
+);
+
+/** The file names a directory argument picks up, matching conformance/simulate/. */
+const SCENARIO_FILE = "scenario.json";
+const SCENARIO_SUFFIX = ".scenario.json";
+
+const FORMATS = new Set<string>(["junit", "json"]);
+
+/** Errors reported for one scenario before the rest are elided. */
+const MAX_SCHEMA_ERRORS = 10;
+
+export interface SimulateOptions {
+  instance: string;
+  resourceMap?: string;
+  format?: string;
+  out?: string;
+}
+
+export interface LoadedScenario {
+  /** Absolute path the scenario was read from. */
+  path: string;
+  scenario: Scenario;
+}
+
+let compiled: ValidateFunction | undefined;
+
+function scenarioValidator(): ValidateFunction {
+  if (compiled === undefined) {
+    const schema = JSON.parse(readFileSync(SCENARIO_SCHEMA_PATH, "utf8")) as AnySchema;
+    compiled = new Ajv2020({ allErrors: true, strict: false }).compile(schema);
+  }
+  return compiled;
+}
+
+/**
+ * Schema violations for a value that claims to be a scenario, then the
+ * cross-field findings for one that passes the schema. Empty when it is valid.
+ */
+export function scenarioProblems(value: unknown): string[] {
+  const validate = scenarioValidator();
+  if (!validate(value)) {
+    const errors = validate.errors ?? [];
+    const shown = errors.slice(0, MAX_SCHEMA_ERRORS).map((error) => {
+      const where = error.instancePath === "" ? "(root)" : error.instancePath;
+      return `${where} ${error.message ?? "is invalid"}`;
+    });
+    if (errors.length > MAX_SCHEMA_ERRORS) {
+      shown.push(`... and ${String(errors.length - MAX_SCHEMA_ERRORS)} more`);
+    }
+    return shown;
+  }
+  return validateScenario(value).map((finding) => `${finding.path}: ${finding.message}`);
+}
+
+function isScenarioFile(name: string): boolean {
+  return name === SCENARIO_FILE || name.endsWith(SCENARIO_SUFFIX);
+}
+
+/**
+ * Absolute paths of the scenario files a `<scenarios>` argument names. A file
+ * contributes itself. A directory contributes every `scenario.json` and
+ * `*.scenario.json` in it and in its immediate subdirectories (the layout of
+ * conformance/simulate/, one `<case>/scenario.json` per case), sorted by path.
+ */
+export function resolveScenarioPaths(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 found: string[] = [];
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    const path = join(abs, entry.name);
+    if (entry.isDirectory()) {
+      for (const inner of readdirSync(path)) {
+        if (isScenarioFile(inner)) found.push(join(path, inner));
+      }
+    } else if (isScenarioFile(entry.name)) {
+      found.push(path);
+    }
+  }
+  if (found.length === 0) {
+    throw new CliError(
+      `No ${SCENARIO_FILE} or *${SCENARIO_SUFFIX} files in ${abs} or its subdirectories`,
+    );
+  }
+  return found.sort();
+}
+
+/** Reads and validates every scenario a `<scenarios>` argument names. */
+export function loadScenarios(target: string): LoadedScenario[] {
+  const problems: string[] = [];
+  const loaded: LoadedScenario[] = [];
+
+  for (const path of resolveScenarioPaths(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;
+    }
+    const found = scenarioProblems(parsed);
+    if (found.length > 0) {
+      for (const problem of found) problems.push(`${path}: ${problem}`);
+      continue;
+    }
+    loaded.push({ path, scenario: parsed as Scenario });
+  }
+
+  if (problems.length > 0) {
+    throw new CliError(`${String(problems.length)} problem(s):\n  - ${problems.join("\n  - ")}`);
+  }
+  return loaded;
+}
+
+/** The lines stderr gets for one scenario that did not pass. */
+function describeFailure(result: ScenarioResult): string {
+  const lines = [
+    `${result.status}: ${result.name}${result.message === undefined ? "" : `: ${result.message}`}`,
+  ];
+  for (const detail of result.details ?? []) lines.push(`  ${detail}`);
+  return lines.join("\n");
+}
+
+/**
+ * Runs the suite. `timing` exists for the tests, which must not wait on real
+ * poll intervals; it is the subset of RunOptions that changes no behaviour.
+ */
+export async function runSimulate(
+  target: string,
+  options: SimulateOptions,
+  clients: LiveClients = SDK_CLIENTS,
+  timing: Pick<RunOptions, "now" | "sleep" | "pollIntervalMs"> = {},
+): Promise<SimulationRun> {
+  const format = options.format ?? "junit";
+  if (!FORMATS.has(format)) {
+    throw new CliError(`Unknown --format "${format}". Use "junit" or "json".`);
+  }
+  const instance = parseInstanceArn(options.instance);
+  const scenarios = loadScenarios(target);
+  const resourceMap =
+    options.resourceMap === undefined ? {} : readStringMap(options.resourceMap, "resource map");
+
+  // Every unresolved token in the suite, before a single test case exists.
+  const unresolved: string[] = [];
+  for (const { path, scenario } of scenarios) {
+    try {
+      resolveScenario(compileScenario(scenario), resourceMap);
+    } catch (error) {
+      unresolved.push(`${path}: ${messageOf(error)}`);
+    }
+  }
+  if (unresolved.length > 0) {
+    throw new CliError(
+      `${String(unresolved.length)} scenario(s) cannot be resolved` +
+        `${options.resourceMap === undefined ? " (no --resource-map given)" : ""}:\n  - ` +
+        unresolved.join("\n  - "),
+    );
+  }
+
+  const client = await clients.test(instance);
+  const run = await runScenarios(
+    scenarios.map((s) => s.scenario),
+    client,
+    { resourceMap, ...timing },
+  );
+
+  const report = format === "json" ? jsonReport(run) : junitReport(run);
+  if (options.out === undefined) {
+    process.stdout.write(report);
+  } else {
+    const out = resolve(options.out);
+    writeFileSync(out, report, "utf8");
+    console.log(out);
+  }
+
+  const notPassed = run.results.filter((result) => result.status !== "PASSED");
+  for (const result of notPassed) console.error(describeFailure(result));
+  if (notPassed.length > 0) {
+    throw new CliError(
+      `${String(notPassed.length)} of ${String(run.results.length)} scenario(s) did not pass`,
+    );
+  }
+  return run;
+}