@flow-as-code/cli 0.1.0

package/schema/scenario-0.1.schema.json

@@ -0,0 +1,318 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-as-code.dev/schema/scenario-0.1.schema.json",
+  "title": "Simulate scenario 0.1",
+  "description": "Authoring format for a flow simulation. This is not an Amazon Connect API shape: @flow-as-code/core compiles it into the Connect Testing language (a graph of Observations) that CreateTestCase takes as its Content string. See packages/core/src/simulate.ts and https://docs.aws.amazon.com/connect/latest/devguide/testing-language.html. The structural rules live here; the cross-field rules, including the live-agent safety rule, live in validateScenario.",
+  "type": "object",
+  "required": ["scenario", "name", "entryPoint", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "scenario": {
+      "const": "0.1"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "description": {
+      "type": "string"
+    },
+    "entryPoint": {
+      "$ref": "#/$defs/entryPoint"
+    },
+    "attributes": {
+      "description": "Initial contact attributes. Serialized into the InitializationData JSON string.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/step"
+      }
+    },
+    "substitutions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/substitution"
+      }
+    },
+    "endTest": {
+      "description": "Append a TestControl EndTest action. Default true. A simulated contact that reaches a queue can connect to a live agent, so a scenario that expects a transfer must either end the test or substitute the queue.",
+      "type": "boolean"
+    }
+  },
+  "$defs": {
+    "token": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:(queue|hours|lambda|lex|prompt|flow|module):[a-z0-9]+(-[a-z0-9]+)*(@[a-z0-9]+(-[a-z0-9]+)*)?\\}$"
+    },
+    "flowToken": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:flow:[a-z0-9]+(-[a-z0-9]+)*\\}$"
+    },
+    "queueToken": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:queue:[a-z0-9]+(-[a-z0-9]+)*\\}$"
+    },
+    "hoursToken": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:hours:[a-z0-9]+(-[a-z0-9]+)*\\}$"
+    },
+    "lambdaToken": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:lambda:[a-z0-9]+(-[a-z0-9]+)*\\}$"
+    },
+    "lexToken": {
+      "type": "string",
+      "pattern": "^\\$\\{cdref:lex:[a-z0-9]+(-[a-z0-9]+)*\\}$"
+    },
+    "jsonPath": {
+      "type": "string",
+      "pattern": "^\\$\\.[A-Za-z0-9_$.\\[\\]'-]+$"
+    },
+    "entryPoint": {
+      "description": "TestCaseEntryPointType is CHAT or VOICE_CALL. The channel is a property of the entry point, not of an input. The flow token resolves to a contact flow id or ARN for FlowId; there is no destination number because CreateTestCase rejects a FlowId combined with a DestinationPhoneNumber. https://docs.aws.amazon.com/connect/latest/APIReference/API_VoiceCallEntryPointParameters.html",
+      "type": "object",
+      "required": ["channel", "flow"],
+      "additionalProperties": false,
+      "properties": {
+        "channel": {
+          "enum": ["voice", "chat"]
+        },
+        "flow": {
+          "$ref": "#/$defs/flowToken"
+        },
+        "sourcePhoneNumber": {
+          "description": "Voice only. E.164, as VoiceCallEntryPointParameters.SourcePhoneNumber requires. Defaults to the fictional +15550100.",
+          "type": "string",
+          "pattern": "^\\+[1-9]\\d{1,14}$"
+        }
+      },
+      "if": {
+        "properties": {
+          "channel": {
+            "const": "chat"
+          }
+        },
+        "required": ["channel"]
+      },
+      "then": {
+        "not": {
+          "required": ["sourcePhoneNumber"]
+        }
+      }
+    },
+    "substitution": {
+      "description": "OverrideSystemBehavior with a SubstituteResource strategy: swaps a production resource for a test one. actionParameters names the production resource under the key the action type reads (QueueId, HoursOfOperationId, LambdaFunctionARN); CreateTestCase rejects an empty ActionParameters. https://docs.aws.amazon.com/connect/latest/devguide/testing-language-actions-override-system-behavior.html",
+      "type": "object",
+      "required": ["actionType", "actionParameters", "substitute"],
+      "additionalProperties": false,
+      "properties": {
+        "actionType": {
+          "enum": ["TransferContactToQueue", "CheckHoursOfOperation", "InvokeLambdaFunction"]
+        },
+        "actionParameters": {
+          "description": "Copied verbatim into Content, so every value is a token and never a literal. Which key the action type reads is a cross-field rule that lives in validateScenario.",
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "$ref": "#/$defs/token"
+          }
+        },
+        "substitute": {
+          "$ref": "#/$defs/token"
+        }
+      }
+    },
+    "step": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-prompt"
+            },
+            "contains": {
+              "type": "string",
+              "minLength": 1
+            },
+            "similarTo": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "oneOf": [
+            {
+              "required": ["contains"],
+              "not": {
+                "required": ["similarTo"]
+              }
+            },
+            {
+              "required": ["similarTo"],
+              "not": {
+                "required": ["contains"]
+              }
+            }
+          ]
+        },
+        {
+          "type": "object",
+          "required": ["kind", "lambda"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-lambda"
+            },
+            "lambda": {
+              "$ref": "#/$defs/lambdaToken"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "queue"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-transfer"
+            },
+            "queue": {
+              "$ref": "#/$defs/queueToken"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "hours"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-hours-check"
+            },
+            "hours": {
+              "$ref": "#/$defs/hoursToken"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "lex"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-lex"
+            },
+            "lex": {
+              "$ref": "#/$defs/lexToken"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "name"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "expect-queue"
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "path", "operator", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "assert"
+            },
+            "path": {
+              "$ref": "#/$defs/jsonPath"
+            },
+            "operator": {
+              "enum": [
+                "Equals",
+                "TextStartsWith",
+                "TextEndsWith",
+                "TextContains",
+                "NumberGreaterThan",
+                "NumberGreaterOrEqualTo",
+                "NumberLessThan",
+                "NumberLessOrEqualTo"
+              ]
+            },
+            "value": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "send-dtmf"
+            },
+            "value": {
+              "type": "string",
+              "pattern": "^[0-9*#]+$"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "text"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "send-speech"
+            },
+            "text": {
+              "type": "string",
+              "minLength": 1
+            },
+            "languageCode": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "text"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "send-text"
+            },
+            "text": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "disconnect"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/src/aws.ts

@@ -0,0 +1,149 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Where the CLI meets the AWS SDK, and the seam the tests replace.
+//
+// `export`, `simulate`, and `diff` each reach their instance through one of the
+// two factories in LiveClients. The default set builds @flow-as-code/core's SDK adapters
+// over a real ConnectClient; a test passes its own set, holding a fixture
+// client, and every line of the commands runs offline. Nothing else in this
+// package imports the SDK.
+//
+// Credentials: the SDK's default provider chain (environment variables, the
+// shared config and credentials files with their profiles and SSO sessions,
+// web identity, the container and instance metadata endpoints). The CLI takes
+// no credential flags and reads no secrets of its own.
+// https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html
+//
+// Region: the one in the instance ARN. A v3 client must be given a Region, and
+// an instance ARN spells it (`arn:aws:connect:<region>:<account>:instance/<id>`),
+// so nothing is read from AWS_REGION or a profile, and an instance in one
+// Region cannot be addressed through a client configured for another.
+// https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
+// https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html
+//
+// @aws-sdk/client-connect is an optional peer dependency, loaded with a dynamic
+// import at the moment a command needs it. A missing SDK is a CliError naming
+// the package, not a stack trace from inside a module resolver. Only the
+// package itself being unresolvable counts as missing; an SDK that is present
+// but cannot be loaded (a dependency of its own missing, a file it cannot
+// evaluate) is reported with the loader's reason, because the install command
+// is not the fix for that.
+
+import type { AwsCommandSender, ConnectInventoryClient, FlowTestClient } from "@flow-as-code/core";
+import {
+  createConnectInventoryClient,
+  createConnectTestClient,
+  parseConnectArn,
+} from "@flow-as-code/core";
+
+import { CliError, messageOf } from "./errors.js";
+
+/** An instance, as `--instance` names it. */
+export interface InstanceTarget {
+  /** The ARN exactly as given. */
+  arn: string;
+  region: string;
+  instanceId: string;
+}
+
+/** The clients a live command runs through. Tests supply fixture-backed ones. */
+export interface LiveClients {
+  /** For `export` and `diff`: the inventory and flow content of an instance. */
+  inventory(target: InstanceTarget): Promise<ConnectInventoryClient>;
+  /** For `simulate`: the TestCase operations. */
+  test(target: InstanceTarget): Promise<FlowTestClient>;
+}
+
+/** The peer dependency every live command needs. */
+export const SDK_PACKAGE = "@aws-sdk/client-connect";
+
+export const MISSING_SDK_MESSAGE =
+  `Connecting to an instance needs the optional peer dependency ${SDK_PACKAGE}. ` +
+  `Install it beside flow-cli (npm install ${SDK_PACKAGE}).`;
+
+export const STALE_SDK_MESSAGE =
+  `The installed ${SDK_PACKAGE} does not expose the TestCase operations. ` +
+  "They are recent; upgrade the SDK (3.1122.0 has them all).";
+
+/**
+ * Parses `--instance`. Only an instance ARN will do: a bare id carries no
+ * Region, and a resource ARN names the wrong thing. `exitCode` is the code the
+ * rejection exits with, because `diff` reserves 1 for "differs".
+ */
+export function parseInstanceArn(arn: string, exitCode = 1): InstanceTarget {
+  const parsed = parseConnectArn(arn);
+  if (parsed === undefined || parsed.resourceType !== undefined || parsed.qualifier !== undefined) {
+    throw new CliError(
+      "--instance must be an Amazon Connect instance ARN " +
+        `(arn:<partition>:connect:<region>:<account>:instance/<id>), got "${arn}". ` +
+        "The Region is read from it.",
+      exitCode,
+    );
+  }
+  if (parsed.region === "") {
+    throw new CliError(
+      `--instance ARN "${arn}" has no Region; one is needed to connect.`,
+      exitCode,
+    );
+  }
+  return { arn, region: parsed.region, instanceId: parsed.instanceId };
+}
+
+/** The slice of the SDK module the CLI touches. */
+interface ConnectSdk {
+  ConnectClient: new (config: { region: string }) => AwsCommandSender;
+  CreateTestCaseCommand?: unknown;
+}
+
+/**
+ * Whether `error` is Node failing to find the SDK package itself: the ESM
+ * resolver's ERR_MODULE_NOT_FOUND, whose message quotes the bare specifier it
+ * could not resolve (`Cannot find package '<name>' imported from <file>`). A
+ * package the SDK depends on being absent raises the same code for a
+ * different specifier, or CommonJS's MODULE_NOT_FOUND, and is not this.
+ * https://nodejs.org/api/errors.html#err_module_not_found
+ */
+function isSdkNotFound(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND" &&
+    error.message.includes(`'${SDK_PACKAGE}'`)
+  );
+}
+
+async function loadSdk(): Promise<ConnectSdk> {
+  try {
+    return (await import("@aws-sdk/client-connect")) as unknown as ConnectSdk;
+  } catch (error) {
+    if (isSdkNotFound(error)) throw new CliError(MISSING_SDK_MESSAGE, 1, { cause: error });
+    throw new CliError(`${SDK_PACKAGE} could not be loaded: ${messageOf(error)}`, 1, {
+      cause: error,
+    });
+  }
+}
+
+/** Loads the SDK and builds a client for the Region the ARN names. */
+async function connectClient(
+  target: InstanceTarget,
+): Promise<{ sdk: ConnectSdk; connect: AwsCommandSender }> {
+  const sdk = await loadSdk();
+  return { sdk, connect: new sdk.ConnectClient({ region: target.region }) };
+}
+
+/** The default LiveClients: @flow-as-code/core's SDK adapters over a real ConnectClient. */
+export const SDK_CLIENTS: LiveClients = {
+  async inventory(target) {
+    const { connect } = await connectClient(target);
+    return createConnectInventoryClient({ connect, instanceId: target.instanceId });
+  },
+  async test(target) {
+    const { sdk, connect } = await connectClient(target);
+    // @flow-as-code/core checks the whole TestCase command set on first use. Checking
+    // one here turns an SDK too old for `simulate` into a message before any
+    // scenario is reported as errored.
+    if (typeof sdk.CreateTestCaseCommand !== "function") throw new CliError(STALE_SDK_MESSAGE);
+    return createConnectTestClient({ connect, instanceId: target.instanceId });
+  },
+};

package/src/bin.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Command registration only. Every command's behaviour lives in its own module
+// so it can be tested without a subprocess; this file wires arguments, options,
+// and help text, in the order packages/cli/README.md lists them.
+
+import { PACKAGE_NAMES } from "@flow-as-code/core";
+import { Command } from "commander";
+
+import { runCodegen } from "./codegen.js";
+import { EXIT_DIFF_ERROR, runDiff } from "./diff.js";
+import { runEmit } from "./emit.js";
+import { runExport } from "./export.js";
+import { runLint } from "./lint.js";
+import { runRender } from "./render.js";
+import { action, usageErrorsExit } from "./run.js";
+import { runSimulate } from "./simulate.js";
+import { studioCommand, type StudioOptions } from "./studio.js";
+import { synthToFiles } from "./synth.js";
+
+const program = new Command();
+program
+  .name("flow-cli")
+  .description("Typed, IaC-native tooling for Amazon Connect flows")
+  .version("0.0.1");
+
+program
+  .command("lint")
+  .description(
+    `Check every FlowDoc in a directory (or one file) against the ${PACKAGE_NAMES.core} rule set. ` +
+      "The whole set is linted in one pass so cross-document rules can follow module " +
+      "references. Exits 1 when any finding has error severity; warnings alone exit 0.",
+  )
+  .argument("<dir-or-file>", "directory of *.flowdoc.json files, or one FlowDoc file")
+  .option("--format <format>", "report format: text or json", "text")
+  .action(action((target: string, opts: { format?: string }) => runLint(target, opts)));
+
+program
+  .command("codegen")
+  .description(
+    "Generate idiomatic TypeScript builder source from a FlowDoc. Writes " +
+      "<doc name>.flow.ts next to the input unless --out says otherwise, and re-reads " +
+      "an existing output file first so comments marked @keep survive regeneration.",
+  )
+  .argument("<file>", "path to a .flowdoc.json file")
+  .option("--out <file>", "output file (default: <doc name>.flow.ts beside the input)")
+  .action(
+    action((file: string, opts: { out?: string }) => {
+      console.log(runCodegen(file, opts));
+    }),
+  );
+
+program
+  .command("synth")
+  .description(
+    "Execute a TypeScript builder file in a sandboxed child process and write one " +
+      "<flow.name>.flowdoc.json per exported flow. A flow is any exported Flow instance " +
+      "or the result of any exported zero-argument function returning one.",
+  )
+  .argument("<file>", "path to a .flow.ts builder file")
+  .option("--out <dir>", "output directory (default: the source file's directory)")
+  .action(
+    action(async (file: string, opts: { out?: string }) => {
+      // SynthError already carries a terminal-ready message; action() prints it.
+      for (const path of await synthToFiles(file, opts.out)) {
+        console.log(path);
+      }
+    }),
+  );
+
+program
+  .command("render")
+  .description(
+    "Materialize FlowDocs into deployable Flow language JSON, replacing every " +
+      "${cdref:...} token from the resource map. Writes <doc name>.json. A token with " +
+      "no entry in the map is fatal, and every missing token is listed at once.",
+  )
+  .argument("<dir-or-file>", "directory of *.flowdoc.json files, or one FlowDoc file")
+  .requiredOption("--resources <map.json>", "JSON object mapping reference tokens to values")
+  .option("--out <dir>", "output directory (default: the input directory)")
+  .action(
+    action((target: string, opts: { resources: string; out?: string }) => {
+      for (const path of runRender(target, opts)) console.log(path);
+    }),
+  );
+
+program
+  .command("emit")
+  .description(
+    "Emit infrastructure as code for a set of FlowDocs. --target tf writes the " +
+      `Terraform/OpenTofu files from ${PACKAGE_NAMES.tf}; --target cdk writes a flow-stack.ts ` +
+      `scaffold that constructs a ${PACKAGE_NAMES.cdk} FlowSet over the directory.`,
+  )
+  .argument("<dir-or-file>", "directory of *.flowdoc.json files, or one FlowDoc file")
+  .requiredOption("--target <target>", "cdk or tf")
+  .option("--address-map <refs.tfmap.json>", "tf only: reference to terraform address expressions")
+  .option("--out <dir>", "output directory (default: the input directory)")
+  .action(
+    action((input: string, opts: { target: string; addressMap?: string; out?: string }) => {
+      for (const path of runEmit(input, opts)) console.log(path);
+    }),
+  );
+
+program
+  .command("diff")
+  .description(
+    "Compare every FlowDoc in a directory against the flow or module of the same name " +
+      "in a live Amazon Connect instance. Prints one line per document (unchanged, changed, " +
+      "missing-live) and a unified diff of the canonical JSON for each changed one; layout " +
+      "and meta are ignored. Exits 0 when nothing differs, 1 when something does, 2 when the " +
+      "comparison itself failed.",
+  )
+  .argument("<dir>", "directory of *.flowdoc.json files")
+  .requiredOption("--instance <arn>", "ARN of the Connect instance to compare against")
+  // 1 means "differs", so commander's own usage errors take the error code too.
+  .exitOverride(usageErrorsExit(EXIT_DIFF_ERROR))
+  .action(
+    action(async (dir: string, opts: { instance: string }) => {
+      await runDiff(dir, opts);
+    }),
+  );
+
+program
+  .command("export")
+  .description(
+    "Read every flow and module in a live Amazon Connect instance and write " +
+      "<name>.flowdoc.json plus <name>.flow.ts for each. References come out as tokens, " +
+      "never ARNs. Exits 1 when any flow could not be exported; --on-error collect (the " +
+      "default) still writes the rest and reports every failure at once.",
+  )
+  .requiredOption("--instance <arn>", "ARN of the Connect instance to read")
+  .option("--out <dir>", "output directory (default: the working directory)")
+  .option("--no-codegen", "write FlowDocs only, no TypeScript")
+  .option("--on-error <mode>", "abort on the first failed flow, or collect them all", "collect")
+  .action(
+    action(async (opts: { instance: string; out?: string; codegen: boolean; onError: string }) => {
+      await runExport(opts);
+    }),
+  );
+
+program
+  .command("simulate")
+  .description(
+    "Run a scenario suite against a live Amazon Connect instance through its TestCase " +
+      "operations, within the documented limits (5 concurrent, 100 in flight, 5 minutes " +
+      "each), and write a JUnit or JSON report. Exits 0 only when every scenario passed.",
+  )
+  .argument("<scenarios>", "scenario file, or a directory of scenario.json / *.scenario.json")
+  .requiredOption("--instance <arn>", "ARN of the Connect instance to run against")
+  .option("--resource-map <map.json>", "JSON object mapping reference tokens to ARNs")
+  .option("--format <format>", "report format: junit or json", "junit")
+  .option("--out <file>", "report file (default: stdout)")
+  .action(
+    action(
+      async (
+        scenarios: string,
+        opts: { instance: string; resourceMap?: string; format?: string; out?: string },
+      ) => {
+        await runSimulate(scenarios, opts);
+      },
+    ),
+  );
+
+program
+  .command("studio")
+  .description(
+    "Serve the local visual editor over a directory. The bridge binds 127.0.0.1 only, " +
+      "picks a free port unless --port says otherwise, and keeps every <name>.flowdoc.json " +
+      "in sync with its <name>.flow.ts: a canvas save regenerates the builder source, and " +
+      "an edit to the source reloads the canvas.",
+  )
+  .argument("[dir]", "directory to open (default: the working directory)")
+  .option("--port <port>", "port to listen on (default: a free port)")
+  .action(action((dir: string | undefined, opts: StudioOptions) => studioCommand(dir, opts)));
+
+program.parseAsync(process.argv);