@flow-as-code/cli 0.1.0

package/dist/docs.js

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

package/dist/docs.js.map

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

package/dist/emit.d.ts

@@ -0,0 +1,8 @@
+export type EmitTarget = "cdk" | "tf";
+export interface EmitOptions {
+    target: string;
+    addressMap?: string;
+    out?: string;
+}
+export declare function runEmit(input: string, options: EmitOptions): string[];
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,IAAI,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAiCrE"}

package/dist/emit.js

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

package/dist/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,yCAAyC;AACzC,EAAE;AACF,uEAAuE;AACvE,EAAE;AACF,uFAAuF;AACvF,8EAA8E;AAC9E,2EAA2E;AAC3E,6DAA6D;AAC7D,4EAA4E;AAC5E,+EAA+E;AAC/E,iEAAiE;AAEjE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAUvC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAE/C,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,OAAoB;IACzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,QAAQ,CAAC,qBAAqB,OAAO,CAAC,MAAM,uBAAuB,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjE,MAAM,IAAI,QAAQ,CAAC,0EAA0E,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC;IAC/C,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,UAAU,GACd,OAAO,CAAC,UAAU,KAAK,SAAS;YAC9B,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QACjF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,WAAW;gBAAE,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACpE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;aAC7B,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C,aAAa,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number, options?: ErrorOptions);
+}
+/** Message of an unknown thrown value, without a stack trace. */
+export declare function messageOf(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,OAAO,CAAC,EAAE,YAAY;CAKlE;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD"}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/*
+ * 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 {
+    exitCode;
+    constructor(message, exitCode = 1, options) {
+        super(message, options);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+/** Message of an unknown thrown value, without a stack trace. */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,QAAQ,GAAG,CAAC,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/export.d.ts

@@ -0,0 +1,27 @@
+import type { ExportFailure, FlowDoc } from "@flow-as-code/core";
+import { type LiveClients } from "./aws.js";
+export declare 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;
+}
+/** 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[];
+}
+export declare function runExport(options: ExportOptions, clients?: LiveClients): Promise<ExportOutcome>;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,aAAa,EAAgB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG/E,OAAO,EAAE,KAAK,WAAW,EAAiC,MAAM,UAAU,CAAC;AAK3E,eAAO,MAAM,SAAS,aAAa,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyBD,wBAAsB,SAAS,CAC7B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,WAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CA0ExB"}

package/dist/export.js

@@ -0,0 +1,126 @@
+/*
+ * 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 { codegen, collectInventory, exportInstance, serialize } from "@flow-as-code/core";
+import { 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";
+const ON_ERROR = new Set(["abort", "collect"]);
+/** Writes one exported document, and its source when asked. */
+function writeExported(flow, outDir, withCode) {
+    const { doc } = flow;
+    const docFile = `${doc.name}${FLOWDOC_SUFFIX}`;
+    const files = [docFile];
+    let text;
+    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, clients = SDK_CLIENTS) {
+    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 = [];
+    // 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();
+    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 };
+}
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8FAA8F;AAC9F,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,yEAAyE;AACzE,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,8EAA8E;AAC9E,2EAA2E;AAC3E,qCAAqC;AACrC,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,wEAAwE;AACxE,8EAA8E;AAC9E,kBAAkB;AAElB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE1F,OAAO,EAAoB,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC;AAUpC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;AAmBvD,+DAA+D;AAC/D,SAAS,aAAa,CAAC,IAAkB,EAAE,MAAc,EAAE,QAAiB;IAC1E,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACrB,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,IAAI,GAAG,cAAc,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,IAAI,IAAY,CAAC;IAEjB,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/E,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QACxE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACjG,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAEnD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;AAC/E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAsB,EACtB,UAAuB,WAAW;IAElC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC;IAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,QAAQ,CAAC,uBAAuB,OAAO,8BAA8B,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC;IAE3C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/C,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,SAAS,CAAC;IACd,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE;YACpC,SAAS;YACT,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YAClD,SAAS,EAAE,SAAS;SACrB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,wEAAwE;QACxE,MAAM,IAAI,QAAQ,CAAC,sCAAsC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE;YAC9E,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,wEAAwE;IACxE,sEAAsE;IACtE,oBAAoB;IACpB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEhD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,UAAU;gBACrB,MAAM,EACJ,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,UAAU,IAAI,CAAC,GAAG,CAAC,IAAI,kBAAkB,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK;oBAC9E,gBAAgB,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,cAAc,cAAc,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE;aAChF,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ;QAAE,OAAO,CAAC,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;IAC5E,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,CAAC,GAAG,CACT,YAAY,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,MAAM,EAAE,CACjG,CAAC;IAEF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,gCAAgC,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;AAClE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./synth.js";
+export * from "./watch.js";
+export * from "./bridge/server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/*
+ * 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);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,uEAAuE;AAEvE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AAEnC,iFAAiF;AACjF,iFAAiF;AACjF,kFAAkF;AAClF,kFAAkF;AAClF,mFAAmF;AACnF,gBAAgB;AAChB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7F,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yHAAyH,CAC1H,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/lint.d.ts

@@ -0,0 +1,6 @@
+export type LintFormat = "text" | "json";
+export interface LintOptions {
+    format?: string;
+}
+export declare function runLint(target: string, options: LintOptions): void;
+//# sourceMappingURL=lint.d.ts.map

package/dist/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAalE"}

package/dist/lint.js

@@ -0,0 +1,31 @@
+/*
+ * 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";
+const FORMATS = new Set(["text", "json"]);
+export function runLint(target, options) {
+    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}`);
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,iCAAiC;AACjC,EAAE;AACF,sFAAsF;AACtF,wEAAwE;AACxE,2EAA2E;AAC3E,+EAA+E;AAC/E,kCAAkC;AAClC,EAAE;AACF,4EAA4E;AAC5E,gBAAgB;AAEhB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAElD,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,OAAoB;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;IACxC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,QAAQ,CAAC,qBAAqB,MAAM,0BAA0B,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE9E,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACrE,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,gBAAgB,MAAM,CAAC,MAAM,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,6 @@
+export interface RenderOptions {
+    resources: string;
+    out?: string;
+}
+export declare function runRender(target: string, options: RenderOptions): string[];
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CA8B1E"}