@flow-as-code/cli 0.1.0

package/dist/synth-resolve-hook.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Module-resolution hook for the `flow-cli synth` child process. Two jobs,
+// both aimed at the same thing: a `<name>.flow.ts` sitting in a plain folder
+// of FlowDocs must synth, because that is where `flow-cli codegen` writes it
+// and what `flow-cli studio` re-synths on every save.
+//
+// 1. TypeScript in the builder graph is ESM when nothing says otherwise.
+//    Without a package.json above it, the TypeScript loader compiles the file
+//    to CommonJS, so its `import { Flow } from "@flow-as-code/core"`
+//    becomes a `require` of an ESM-only package, which is not the module
+//    system codegen emits for.
+//    A directory that does declare a type keeps it: this only fills in a
+//    decision nobody made.
+//
+//    "Nobody made a decision" is read off the filesystem rather than off the
+//    resolver's answer, because runtimes have answered differently for the same
+//    plain folder: Node 22 and later return a null `format` for the builder
+//    file, while Node 20 returned "commonjs". Trusting a nullish `format` alone
+//    therefore fixed the plain-folder case on 22 and left it broken on 20.
+//    Node 20 is no longer supported, but the answer is not a contract, so the
+//    walk stays: a TypeScript file with no package.json anywhere above it is
+//    ESM whatever the resolver said, and one with a package.json above it is
+//    left exactly as resolved.
+//
+// 2. @flow-as-code/core resolves from @flow-as-code/cli when it resolves from
+//    nowhere else. A folder of FlowDocs has no node_modules, and requiring the
+//    user to install @flow-as-code/core beside every such folder to edit a file
+//    the CLI generated is not a reasonable price. It is a hard dependency of
+//    @flow-as-code/cli, so resolving from the CLI's own module always finds the
+//    copy the CLI is running against.
+//
+// The fallback runs after the default resolver, never before it, so a copy
+// installed next to the builder file still wins and version skew stays the
+// user's choice. It is scoped to @flow-as-code/core alone: a builder file
+// cannot use it to reach the rest of the CLI's dependency tree.
+//
+// Nothing about the sandbox changes. The child keeps its stripped environment,
+// its pinned working directory, and the permission flags synth.ts passes; the
+// fallback only reads a file the child could already read under
+// `--allow-fs-read=*`. See SECURITY.md.
+//
+// Loaded on the module-customization hooks thread by `module.register`
+// (https://nodejs.org/api/module.html#customization-hooks), which is why the
+// fallback target arrives through `initialize` rather than a module-level
+// import.
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Module URL whose resolution scope holds the CLI's own @flow-as-code/core. */
+let fallbackParentURL;
+/**
+ * @flow-as-code/core's package name, from PACKAGE_NAMES rather than a literal: the npm
+ * scope is written down in exactly one module (packages/core/src/package-names.ts)
+ * and this file runs on a thread that should not import it to find out.
+ */
+let flowCorePackage;
+export function initialize(data) {
+    fallbackParentURL = data?.fallbackParentURL;
+    flowCorePackage = data?.flowCorePackage;
+}
+function isFlowCore(specifier) {
+    if (flowCorePackage === undefined)
+        return false;
+    return specifier === flowCorePackage || specifier.startsWith(`${flowCorePackage}/`);
+}
+function isTypeScript(url) {
+    return url.startsWith("file:") && (url.endsWith(".ts") || url.endsWith(".tsx"));
+}
+/**
+ * True when no package.json exists in the file's directory or any directory
+ * above it, so nothing has declared a module type for it. This is the same walk
+ * node itself does to answer that question
+ * (https://nodejs.org/api/packages.html#determining-module-system); doing it
+ * here is what makes the answer the same whatever the resolver reports.
+ */
+function nothingDeclaredATypeFor(url) {
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(url));
+    }
+    catch {
+        return false;
+    }
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return false;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return true;
+        dir = parent;
+    }
+}
+export async function resolve(specifier, context, nextResolve) {
+    let resolution;
+    try {
+        resolution = await nextResolve(specifier, context);
+    }
+    catch (error) {
+        // Only a specifier that could not be found at all, and only
+        // @flow-as-code/core: an export map violation or a syntax error in the
+        // installed copy is the user's problem to see, not something to paper
+        // over with a second copy.
+        if (fallbackParentURL === undefined)
+            throw error;
+        if (!isFlowCore(specifier))
+            throw error;
+        if (error.code !== "ERR_MODULE_NOT_FOUND")
+            throw error;
+        resolution = await nextResolve(specifier, { ...context, parentURL: fallbackParentURL });
+    }
+    // A nullish `format` (Node 22 and later) or a defaulted "commonjs" (the
+    // answer Node 20 gave) on a TypeScript file with no package.json above it is
+    // the plain-folder case described above, and nothing else. Any other format
+    // is a decision somebody made and is left alone.
+    if (isTypeScript(resolution.url) &&
+        (resolution.format === null ||
+            resolution.format === undefined ||
+            resolution.format === "commonjs") &&
+        nothingDeclaredATypeFor(resolution.url)) {
+        return { ...resolution, format: "module" };
+    }
+    return resolution;
+}
+//# sourceMappingURL=synth-resolve-hook.js.map

package/dist/synth-resolve-hook.js.map

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

package/dist/synth-runner.d.ts

@@ -0,0 +1,12 @@
+export declare const SYNTH_ENVELOPE_SENTINEL = "__FLOW_CLI_SYNTH_ENVELOPE_V1__";
+export interface SynthEnvelope {
+    flows?: {
+        name: string;
+        doc: unknown;
+    }[];
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+//# sourceMappingURL=synth-runner.d.ts.map

package/dist/synth-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synth-runner.d.ts","sourceRoot":"","sources":["../src/synth-runner.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IACzC,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C"}

package/dist/synth-runner.js

@@ -0,0 +1,145 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Child-process entry point for `flow-cli synth`. Never imported by the
+// parent: it is spawned (see synth.ts) so that evaluating an untrusted
+// builder file cannot touch the CLI process. Runs under tsx (--import), so
+// this file works both compiled (dist/synth-runner.js) and straight from
+// source in tests (src/synth-runner.ts).
+//
+// Contract with the parent: argv[2] is the absolute path of the builder file,
+// argv[3] the path of the resolution hook module, and argv[4] the module URL
+// that hook resolves @flow-as-code/core from when the builder file's own directory
+// cannot. The runner prints exactly one envelope line to stdout, prefixed with
+// SYNTH_ENVELOPE_SENTINEL, so user code writing to stdout during module
+// evaluation cannot corrupt the channel. Everything else on stdout is ignored
+// by the parent.
+import { register } from "node:module";
+import { pathToFileURL } from "node:url";
+import { PACKAGE_NAMES, synth } from "@flow-as-code/core";
+export const SYNTH_ENVELOPE_SENTINEL = "__FLOW_CLI_SYNTH_ENVELOPE_V1__";
+/**
+ * Structural check instead of `instanceof Flow`: the builder file may resolve
+ * its own copy of @flow-as-code/core (dual-package or version skew), and a Flow from
+ * that copy is still a Flow for our purposes.
+ */
+function isFlowLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === "string" &&
+        (v.kind === "flow" || v.kind === "module") &&
+        typeof v.all === "function" &&
+        typeof v.startId === "function");
+}
+/**
+ * Convention: every exported Flow instance, plus the result of every exported
+ * zero-argument function that returns one. Functions that throw when called
+ * (including classes, which throw without `new`) are skipped; a throw during
+ * module evaluation itself is a hard error and is reported by main().
+ */
+function collectFlows(mod) {
+    const flows = [];
+    const seen = new Set();
+    const push = (f) => {
+        if (!seen.has(f)) {
+            seen.add(f);
+            flows.push(f);
+        }
+    };
+    for (const value of Object.values(mod)) {
+        if (isFlowLike(value)) {
+            push(value);
+        }
+        else if (typeof value === "function" && value.length === 0) {
+            let result;
+            try {
+                result = value();
+            }
+            catch {
+                continue; // not a flow factory (e.g. a class, or a helper that needs setup)
+            }
+            if (isFlowLike(result))
+                push(result);
+        }
+    }
+    return flows;
+}
+function emit(envelope) {
+    process.stdout.write("\n" + SYNTH_ENVELOPE_SENTINEL + JSON.stringify(envelope) + "\n");
+}
+/**
+ * Registers the @flow-as-code/core resolution fallback before the builder file is
+ * imported. See synth-resolve-hook.ts for what it does and why it is safe.
+ *
+ * `module.register` is the only registration API present on every Node this
+ * package supports (`registerHooks` landed in 22.15). Its deprecation warning
+ * on newer runtimes would otherwise reach the user inside a synth failure
+ * message, which is why it is silenced for the length of the call and no
+ * longer.
+ */
+function registerResolveFallback(hookPath, fallbackParentURL) {
+    const { noDeprecation } = process;
+    process.noDeprecation = true;
+    try {
+        register(pathToFileURL(hookPath).href, {
+            parentURL: import.meta.url,
+            data: { fallbackParentURL, flowCorePackage: PACKAGE_NAMES.core },
+        });
+    }
+    finally {
+        process.noDeprecation = noDeprecation;
+    }
+}
+async function main() {
+    const sourcePath = process.argv[2];
+    if (sourcePath === undefined) {
+        emit({ error: { message: "synth-runner: missing source file argument" } });
+        process.exitCode = 1;
+        return;
+    }
+    const hookPath = process.argv[3];
+    const fallbackParentURL = process.argv[4];
+    if (hookPath !== undefined && fallbackParentURL !== undefined) {
+        registerResolveFallback(hookPath, fallbackParentURL);
+    }
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(sourcePath).href));
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        emit({ error: { message: err.message, stack: err.stack } });
+        process.exitCode = 1;
+        return;
+    }
+    const flows = collectFlows(mod);
+    const byName = new Map();
+    for (const flow of flows) {
+        if (byName.has(flow.name)) {
+            emit({
+                error: {
+                    message: `Two exported flows share the name "${flow.name}". Flow names must be unique per file because each becomes <name>.flowdoc.json.`,
+                },
+            });
+            process.exitCode = 1;
+            return;
+        }
+        byName.set(flow.name, flow);
+    }
+    try {
+        // meta is stamped by the parent (generator + sourceHash of the file it
+        // actually read), so the runner synths without one.
+        emit({
+            flows: flows.map((f) => ({ name: f.name, doc: synth(f, { includeMeta: false }) })),
+        });
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        emit({ error: { message: err.message, stack: err.stack } });
+        process.exitCode = 1;
+    }
+}
+void main();
+//# sourceMappingURL=synth-runner.js.map

package/dist/synth-runner.js.map

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

package/dist/synth.d.ts

@@ -0,0 +1,55 @@
+import type { FlowDoc } from "@flow-as-code/core";
+/** Recorded in meta.generator of every FlowDoc this CLI writes. */
+export declare const GENERATOR = "cli@0.0.1";
+/** A synth failure with a message meant for the terminal. */
+export declare class SynthError extends Error {
+}
+/**
+ * The frames of a thrown value's stack that point at the user's own code.
+ *
+ * A syntax error in a builder file used to print the actionable line and then
+ * ten frames of esbuild and node stream internals under it
+ * (`at failureErrorWithLog (.../node_modules/esbuild/lib/main.js:1752:15)`,
+ * `at Pipe.onStreamRead (node:internal/stream_base_commons:191:23)`), which buries
+ * the file, line and column that the message above already names. The studio's
+ * badge shows only the first line for the same reason; the terminal now matches
+ * that intent.
+ *
+ * Frames inside node_modules and node's own internals are dropped, and so are
+ * the header lines the stack repeats from the message that is printed above it.
+ * A frame in the builder file or anywhere else the user wrote survives, because
+ * that is the one a runtime error in a flow needs. There is no verbose flag or
+ * env var in this CLI to hide the full stack behind, so what is dropped here is
+ * dropped: the retained frames plus the message carry the location.
+ *
+ * `builderPath` is the file being synthesized. Its own frames are kept even
+ * when it sits under a directory named node_modules, which a vendored or
+ * linked builder file legitimately does: the node_modules rule is about
+ * dependency code, and the file the user asked to run is never that. Without
+ * the exemption such a file reports a throw with no line or column at all.
+ */
+export declare function actionableFrames(stack: string | undefined, builderPath?: string): string[];
+export interface SynthesizedFlow {
+    name: string;
+    doc: FlowDoc;
+}
+export interface SynthFileResult {
+    flows: SynthesizedFlow[];
+    /** `sha256:<hex>` of the builder file bytes, ready for meta.sourceHash. */
+    sourceHash: string;
+}
+export declare function sha256Hex(bytes: Buffer | string): string;
+/**
+ * Evaluates the builder file in the sandboxed child and returns its flows.
+ * Throws SynthError with an actionable message on any failure.
+ */
+export declare function synthFile(sourcePath: string): Promise<SynthFileResult>;
+/** Serializes a doc with the meta this CLI stamps. Byte-stable. */
+export declare function serializeWithMeta(doc: FlowDoc, sourceHash: string): string;
+/**
+ * The `flow-cli synth` command body: synth every flow the file exports and
+ * write <flow.name>.flowdoc.json into outDir (default: the source file's
+ * directory). Returns the written paths in write order.
+ */
+export declare function synthToFiles(sourcePath: string, outDir?: string): Promise<string[]>;
+//# sourceMappingURL=synth.d.ts.map

package/dist/synth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synth.d.ts","sourceRoot":"","sources":["../src/synth.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,mEAAmE;AACnE,eAAO,MAAM,SAAS,cAAc,CAAC;AAIrC,6DAA6D;AAC7D,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAoDxC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA2B1F;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAExD;AAiFD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoF5E;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBzF"}