@flow-as-code/cli 0.1.0

package/dist/aws.d.ts

@@ -0,0 +1,28 @@
+import type { ConnectInventoryClient, FlowTestClient } from "@flow-as-code/core";
+/** 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 declare const SDK_PACKAGE = "@aws-sdk/client-connect";
+export declare const MISSING_SDK_MESSAGE: string;
+export declare const STALE_SDK_MESSAGE: string;
+/**
+ * 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 declare function parseInstanceArn(arn: string, exitCode?: number): InstanceTarget;
+/** The default LiveClients: @flow-as-code/core's SDK adapters over a real ConnectClient. */
+export declare const SDK_CLIENTS: LiveClients;
+//# sourceMappingURL=aws.d.ts.map

package/dist/aws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws.d.ts","sourceRoot":"","sources":["../src/aws.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASnG,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnE,+CAA+C;IAC/C,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACvD;AAED,oDAAoD;AACpD,eAAO,MAAM,WAAW,4BAA4B,CAAC;AAErD,eAAO,MAAM,mBAAmB,QAE4B,CAAC;AAE7D,eAAO,MAAM,iBAAiB,QAE+B,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,cAAc,CAiB1E;AA2CD,4FAA4F;AAC5F,eAAO,MAAM,WAAW,EAAE,WAazB,CAAC"}

package/dist/aws.js

@@ -0,0 +1,104 @@
+/*
+ * 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 { createConnectInventoryClient, createConnectTestClient, parseConnectArn, } from "@flow-as-code/core";
+import { CliError, messageOf } from "./errors.js";
+/** 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, exitCode = 1) {
+    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 };
+}
+/**
+ * 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) {
+    return (error instanceof Error &&
+        error.code === "ERR_MODULE_NOT_FOUND" &&
+        error.message.includes(`'${SDK_PACKAGE}'`));
+}
+async function loadSdk() {
+    try {
+        return (await import("@aws-sdk/client-connect"));
+    }
+    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) {
+    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 = {
+    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 });
+    },
+};
+//# sourceMappingURL=aws.js.map

package/dist/aws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws.js","sourceRoot":"","sources":["../src/aws.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,mEAAmE;AACnE,EAAE;AACF,gFAAgF;AAChF,yFAAyF;AACzF,0EAA0E;AAC1E,4EAA4E;AAC5E,2BAA2B;AAC3B,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,8EAA8E;AAC9E,uDAAuD;AACvD,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,kFAAkF;AAClF,0EAA0E;AAC1E,sEAAsE;AACtE,wFAAwF;AACxF,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,2BAA2B;AAG3B,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAkBlD,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAErD,MAAM,CAAC,MAAM,mBAAmB,GAC9B,gEAAgE,WAAW,IAAI;IAC/E,2CAA2C,WAAW,IAAI,CAAC;AAE7D,MAAM,CAAC,MAAM,iBAAiB,GAC5B,iBAAiB,WAAW,4CAA4C;IACxE,2DAA2D,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,QAAQ,GAAG,CAAC;IACxD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChG,MAAM,IAAI,QAAQ,CAChB,oDAAoD;YAClD,oEAAoE,GAAG,KAAK;YAC5E,6BAA6B,EAC/B,QAAQ,CACT,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,QAAQ,CAChB,mBAAmB,GAAG,4CAA4C,EAClE,QAAQ,CACT,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;AACvE,CAAC;AAQD;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,KAAK,YAAY,KAAK;QACrB,KAA4B,CAAC,IAAI,KAAK,sBAAsB;QAC7D,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,WAAW,GAAG,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,OAAO;IACpB,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAA0B,CAAC;IAC5E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,QAAQ,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACvF,MAAM,IAAI,QAAQ,CAAC,GAAG,WAAW,yBAAyB,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE;YAC/E,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,KAAK,UAAU,aAAa,CAC1B,MAAsB;IAEtB,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAC;IAC5B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,MAAM,WAAW,GAAgB;IACtC,KAAK,CAAC,SAAS,CAAC,MAAM;QACpB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,4BAA4B,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,MAAM;QACf,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QACrD,kFAAkF;QAClF,yEAAyE;QACzE,mCAAmC;QACnC,IAAI,OAAO,GAAG,CAAC,qBAAqB,KAAK,UAAU;YAAE,MAAM,IAAI,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QAC3F,OAAO,uBAAuB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7E,CAAC;CACF,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,132 @@
+#!/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 } 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, opts) => 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, opts) => {
+    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, opts) => {
+    // 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, opts) => {
+    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, opts) => {
+    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, opts) => {
+    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) => {
+    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, opts) => {
+    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, opts) => studioCommand(dir, opts)));
+program.parseAsync(process.argv);
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/bridge/exportFiles.d.ts

@@ -0,0 +1,16 @@
+import { type BridgeExportRequest, type BridgeExportResult } from "./protocol.js";
+/**
+ * The absolute path an export file lands on, or undefined when it would leave
+ * the served directory. Containment is checked against `dir` itself rather
+ * than against `dir/subdir`, so neither half can escape on its own.
+ */
+export declare function exportPathFor(dir: string, subdir: string, relative: string): string | undefined;
+/** Validates a request body from the wire. Throws BridgeError with a status. */
+export declare function checkExportRequest(body: unknown): BridgeExportRequest;
+/**
+ * Writes a checked export under `dir`, creating directories as needed, and
+ * returns the absolute paths written, sorted. Existing files are overwritten
+ * and nothing else is touched, exactly as `flow-cli emit` behaves.
+ */
+export declare function writeExport(dir: string, request: BridgeExportRequest): Promise<BridgeExportResult>;
+//# sourceMappingURL=exportFiles.d.ts.map

package/dist/bridge/exportFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportFiles.d.ts","sourceRoot":"","sources":["../../src/bridge/exportFiles.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AAIvB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/F;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAsCrE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAe7B"}

package/dist/bridge/exportFiles.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Writing a studio export to disk (POST /bridge/export).
+//
+// The studio computes the bytes: it holds the documents, the address map, and
+// the resource map, and it runs the same emitters the CLI runs
+// (@flow-as-code/tf, the @flow-as-code/cdk scaffold, @flow-as-code/core
+// materialization). All that is left here is the half a browser cannot do,
+// and it is deliberately dumb: check, then write.
+//
+// The checks are the same ones every other bridge path gets. Paths are
+// validated by the shared protocol rule and then, independently, by resolving
+// them and requiring the result to be inside the served directory: the first
+// check states the rule, the second is what actually holds if the rule is ever
+// loosened. Nothing is sanitized into shape, because a sanitizer is a guess
+// about intent and this writes files the user owns.
+//
+// Unlike a document write this publishes no event and pairs nothing: emitted
+// terraform and CDK files are outputs, not documents, and the watch engine
+// ignores them (it pairs *.flow.ts with *.flowdoc.json only).
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { BridgeError } from "./pair.js";
+import { EXPORT_MAX_BYTES, EXPORT_MAX_FILES, EXPORT_TARGETS, isExportPath, isExportSubdir, } from "./protocol.js";
+const TARGETS = new Set(EXPORT_TARGETS);
+/**
+ * The absolute path an export file lands on, or undefined when it would leave
+ * the served directory. Containment is checked against `dir` itself rather
+ * than against `dir/subdir`, so neither half can escape on its own.
+ */
+export function exportPathFor(dir, subdir, relative) {
+    const base = resolve(dir);
+    const target = resolve(base, subdir, relative);
+    return target !== base && target.startsWith(base + sep) ? target : undefined;
+}
+/** Validates a request body from the wire. Throws BridgeError with a status. */
+export function checkExportRequest(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new BridgeError(400, "The body must be a JSON object.");
+    }
+    const request = body;
+    if (typeof request.target !== "string" || !TARGETS.has(request.target)) {
+        throw new BridgeError(400, `"target" must be one of: ${[...TARGETS].sort().join(", ")}.`);
+    }
+    const subdir = request.subdir ?? "";
+    if (typeof subdir !== "string" || !isExportSubdir(subdir)) {
+        throw new BridgeError(400, `"${subdir}" is not a usable export subdirectory.`);
+    }
+    const files = request.files;
+    if (files === null || typeof files !== "object" || Array.isArray(files)) {
+        throw new BridgeError(400, '"files" must be a JSON object of path to content.');
+    }
+    const entries = Object.entries(files);
+    if (entries.length === 0)
+        throw new BridgeError(400, "An export must carry at least one file.");
+    if (entries.length > EXPORT_MAX_FILES) {
+        throw new BridgeError(413, `An export may carry at most ${String(EXPORT_MAX_FILES)} files.`);
+    }
+    let bytes = 0;
+    for (const [path, content] of entries) {
+        if (typeof content !== "string") {
+            throw new BridgeError(400, `The content of "${path}" is not a string.`);
+        }
+        if (!isExportPath(path)) {
+            throw new BridgeError(400, `"${path}" is not a usable export path.`);
+        }
+        bytes += Buffer.byteLength(content, "utf8");
+    }
+    if (bytes > EXPORT_MAX_BYTES) {
+        throw new BridgeError(413, `An export may carry at most ${String(EXPORT_MAX_BYTES)} bytes.`);
+    }
+    return { target: request.target, files: files, subdir };
+}
+/**
+ * Writes a checked export under `dir`, creating directories as needed, and
+ * returns the absolute paths written, sorted. Existing files are overwritten
+ * and nothing else is touched, exactly as `flow-cli emit` behaves.
+ */
+export async function writeExport(dir, request) {
+    const subdir = request.subdir ?? "";
+    const written = [];
+    for (const [relative, content] of Object.entries(request.files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        const target = exportPathFor(dir, subdir, relative);
+        if (target === undefined) {
+            throw new BridgeError(400, `"${relative}" resolves outside the served directory.`);
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content, "utf8");
+        written.push(target);
+    }
+    return { target: request.target, paths: written };
+}
+//# sourceMappingURL=exportFiles.js.map

package/dist/bridge/exportFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportFiles.js","sourceRoot":"","sources":["../../src/bridge/exportFiles.ts"],"names":[],"mappings":"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"}

package/dist/bridge/pair.d.ts

@@ -0,0 +1,103 @@
+import { type FlowDoc } from "@flow-as-code/core";
+import { type FlowWatcher } from "../watch.js";
+import { type BridgeDocPayload, type BridgeWriteResult } from "./protocol.js";
+/** A failure with the HTTP status the bridge should answer with. */
+export declare class BridgeError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Thrown by writePair when the builder file has moved since the document being
+ * written was generated from it. Both sides changed, so the write is refused
+ * and the caller turns this into the "which side wins" question.
+ */
+export declare class PairConflict extends Error {
+    readonly name = "PairConflict";
+    readonly docName: string;
+    readonly reason: string;
+    constructor(docName: string, reason: string);
+}
+export interface PairPaths {
+    docPath: string;
+    tsPath: string;
+}
+/**
+ * Both file paths for a document name. The name is re-checked here rather than
+ * only at the route, because this function is what turns a client string into
+ * a filesystem path: a slug cannot contain a separator, a dot, or a NUL, so
+ * traversal is impossible by construction rather than by sanitizing.
+ */
+export declare function pairPaths(dir: string, name: string): PairPaths;
+/** Every FlowDoc name in the directory, sorted, non-recursive. */
+export declare function listDocNames(dir: string): Promise<string[]>;
+/** Parses and schema-validates a FlowDoc, naming what is wrong with it. */
+export declare function parseDoc(text: string, what: string): FlowDoc;
+/** The document on disk, exactly as the file holds it. */
+export declare function readPair(dir: string, name: string): Promise<BridgeDocPayload>;
+/**
+ * Writes both halves of the pair from a FlowDoc the canvas produced.
+ *
+ * Order matters and is: generate, hash the generated source, serialize the doc
+ * with that hash, write both, then tell the watcher these exact bytes are
+ * ours. The watcher is told last because chokidar's awaitWriteFinish window
+ * (50 ms) is far longer than the gap, so no change event can be routed against
+ * a half-updated ledger, and a write that throws leaves the ledger untouched.
+ */
+export interface WritePairOptions {
+    /**
+     * Write even though the builder file no longer matches the document's
+     * meta.sourceHash. Set only when the user has answered the conflict dialog.
+     */
+    force?: boolean;
+}
+export declare function writePair(dir: string, name: string, doc: FlowDoc, watcher?: FlowWatcher, options?: WritePairOptions): Promise<BridgeWriteResult>;
+/** The FlowDoc the builder file synths to right now. */
+export declare function synthPair(dir: string, name: string): Promise<FlowDoc>;
+/**
+ * Resolution in the code direction: the builder file wins, so the FlowDoc is
+ * rewritten from it. The source is NOT regenerated, because the user chose the
+ * source they have; only the doc moves.
+ */
+export declare function adoptCode(dir: string, name: string, watcher?: FlowWatcher): Promise<BridgeDocPayload>;
+/** One document whose builder file was written by ensureBuilderFiles. */
+export interface GeneratedBuilderFile {
+    name: string;
+    tsPath: string;
+    /** Exact bytes written, so the caller can seed a watcher's ledger. */
+    tsText: string;
+    docText: string;
+}
+/** One document ensureBuilderFiles could not generate a builder file for. */
+export interface UnbuildableDoc {
+    name: string;
+    message: string;
+}
+export interface EnsureBuilderFilesResult {
+    generated: GeneratedBuilderFile[];
+    problems: UnbuildableDoc[];
+}
+/**
+ * Writes `<name>.flow.ts` for every document in `dir` that has none.
+ *
+ * A directory holding only FlowDocs (an export from a live instance, a doc
+ * copied out of conformance/, a file a colleague sent) had no builder file, so
+ * the loop the studio is built around - edit the builder file, watch the canvas
+ * follow - could not start there: there was nothing to edit. Generating the
+ * file on open is safe because codegen is deterministic and the studio already
+ * regenerates it on every canvas save, so this writes exactly the bytes the
+ * first save would have written.
+ *
+ * It goes through writePair, which also stamps the document with the
+ * meta.sourceHash of the source just generated. Without that stamp the watcher
+ * would meet a pair it has never seen in sync and report a conflict on the
+ * first edit, which is the state a hand-assembled pair lands in. The bytes
+ * come back so the caller can hand them to the watcher's noteWrite as well:
+ * the stamp alone leaves the outcome resting on the initial scan winning a
+ * race against the user's first edit.
+ *
+ * A document that cannot be generated from (invalid, or holding something
+ * codegen cannot express) is reported and skipped, not thrown: the rest of the
+ * directory still opens.
+ */
+export declare function ensureBuilderFiles(dir: string): Promise<EnsureBuilderFilesResult>;
+//# sourceMappingURL=pair.d.ts.map

package/dist/bridge/pair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair.d.ts","sourceRoot":"","sources":["../../src/bridge/pair.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI3D,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,oEAAoE;AACpE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAS9D;AAED,kEAAkE;AAClE,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYjE;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAe5D;AAED,0DAA0D;AAC1D,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CASnF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,WAAW,EACrB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAyD5B;AAED,wDAAwD;AACxD,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3E;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAiBvF"}