@flow-as-code/cli 0.1.0

package/dist/synth.js

@@ -0,0 +1,327 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli synth`: execute a TypeScript builder file in a sandboxed child
+// process and turn its exported flows into FlowDoc JSON.
+//
+// The builder file NEVER runs in the CLI process. It runs in a spawned node
+// with tsx registered via --import, a stripped environment, cwd set to the
+// source file's directory, and (where the runtime supports it) Node's
+// permission model enabled.
+//
+// What the sandbox does and does not enforce, verified on node 25.9.0
+// (https://nodejs.org/api/permissions.html):
+//
+// - File WRITES are denied everywhere except a private temp directory the
+//   parent creates for tsx's own cache/pipe files (tsx honors TMPDIR). The
+//   child never writes FlowDocs; it prints them on stdout and the parent
+//   writes the files.
+// - child_process and cluster are denied (--allow-child-process not passed).
+// - Worker threads ARE allowed (--allow-worker): tsx registers its module
+//   hooks on a loader thread, which the permission model counts as a worker.
+//   Node warns that this weakens the model; the workers a builder file could
+//   start still inherit the same fs restrictions.
+// - File READS are NOT jailed. Scoped --allow-fs-read breaks tsx: its
+//   tsconfig discovery walks every ancestor directory and probes
+//   case-variant paths on macOS, each of which the permission model treats
+//   as a distinct denied resource. We therefore pass --allow-fs-read=* and
+//   a builder file can read anything the invoking user can.
+// - NETWORK: the permission model on Node 22/24 does not cover network
+//   access at all (https://nodejs.org/api/permissions.html), so no network
+//   jail exists there. Newer runtimes (observed on node 25.9.0) deny network
+//   by default under --permission because a net permission exists and we do
+//   not grant it. Do not rely on the sandbox to block exfiltration on the
+//   CI-supported Node 22/24.
+// - On runtimes without the stable --permission flag (Node < 22.13, which
+//   includes 22.12, the engines.node floor), the permission model is not
+//   applied at all; the sandbox is then only the stripped environment, the
+//   pinned cwd, and process isolation. If a spawn still fails with "bad
+//   option" we retry once without the permission flags and remember that for
+//   the process lifetime.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SLUG_PATTERN, serialize } from "@flow-as-code/core";
+/** Recorded in meta.generator of every FlowDoc this CLI writes. */
+export const GENERATOR = "cli@0.0.1";
+const SENTINEL = "__FLOW_CLI_SYNTH_ENVELOPE_V1__";
+/** A synth failure with a message meant for the terminal. */
+export class SynthError extends Error {
+}
+/**
+ * Where a stack frame points, with the `:line:column` suffix taken off.
+ *
+ * V8 writes a frame as `at <name> (<location>)` when it has a function name to
+ * report and as `at <location>` when it does not, so the location is the last
+ * parenthesised run of the line or, failing that, everything after `at `. The
+ * result is a path, a `file:` URL, a `node:` specifier, or (for the nameless
+ * `at Object.<anonymous>` form) something that is none of those.
+ */
+function frameLocation(line) {
+    const parenthesised = /\(([^()]*)\)\s*$/.exec(line)?.[1];
+    const location = parenthesised ?? line.replace(/^\s*at\s+/, "");
+    return location.replace(/:\d+:\d+$/, "");
+}
+/** Whether a location has `node_modules` as a whole path segment. */
+function underNodeModules(location) {
+    // Both separators: a Windows stack reads `at fn (C:\w\node_modules\x\y.js:1:1)`.
+    return location.split(/[/\\]/).includes("node_modules");
+}
+/**
+ * A frame location as one comparable path, or undefined when it names no file.
+ *
+ * A stack spells the same file three ways: the plain path a compiled frame
+ * carries, the `file:` URL the ESM loader produces, and either separator
+ * depending on the platform. Symlinks are the fourth: the loader reports the
+ * real path, while a caller holding the path the user typed may still be
+ * looking at the link (on macOS `/tmp/x` is really `/private/tmp/x`). So both
+ * sides go through realpath, and a path that does not resolve (a stack from
+ * another machine, a fixture) falls back to itself rather than throwing.
+ */
+function comparablePath(location) {
+    let asPath = location;
+    if (/^file:/i.test(asPath)) {
+        try {
+            asPath = fileURLToPath(asPath);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let real = asPath;
+    try {
+        real = realpathSync(asPath);
+    }
+    catch {
+        // Not a path on this machine; compare the literal text instead.
+    }
+    return real.replace(/\\/g, "/");
+}
+/**
+ * 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 function actionableFrames(stack, builderPath) {
+    if (stack === undefined)
+        return [];
+    const builder = builderPath === undefined ? undefined : comparablePath(resolve(builderPath));
+    return (stack
+        .split("\n")
+        .filter((line) => /^\s*at /.test(line))
+        // Vendor frames go by where the frame points, not by the text of the
+        // whole line. A substring test over the line drops a frame whose
+        // function name happens to read `loadNodeModules` or whose builder file
+        // sits in a directory called `node_modules-sandbox`, and those are the
+        // frames this function exists to keep. The segment test is what makes
+        // `node_modules` mean the dependency tree rather than eleven characters.
+        // The builder file itself is exempt: it is the user's own code wherever
+        // it lives.
+        .filter((line) => {
+        const location = frameLocation(line);
+        if (!underNodeModules(location))
+            return true;
+        return builder !== undefined && comparablePath(location) === builder;
+    })
+        // What is left must name a file on disk. That drops node's own frames,
+        // whose location is a `node:internal/...` specifier rather than a path
+        // (`at addChunk (node:internal/streams/readable:559:12)`), and the bare
+        // `at Object.<anonymous>` form that carries no location at all. Neither
+        // says anything about the user's flow.
+        .filter((line) => /[(\s](\/|[A-Za-z]:\\|file:)/.test(line)));
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function resolveSibling(base) {
+    // Compiled layout: dist/<base>.js next to dist/synth.js. Under vitest this
+    // module runs from src/, where only the .ts exists; the child runs under
+    // tsx either way, so both are executable.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const js = join(here, `${base}.js`);
+    if (existsSync(js))
+        return js;
+    const ts = join(here, `${base}.ts`);
+    if (existsSync(ts))
+        return ts;
+    throw new SynthError(`flow-cli is broken: ${base} not found next to ${here}`);
+}
+function resolveTsxLoader() {
+    // tsx's package export "." is dist/loader.mjs, the --import registration.
+    return createRequire(import.meta.url).resolve("tsx");
+}
+function supportsStablePermissionFlag() {
+    // --permission is stable from Node 23.5 and was backported to 22.13.
+    // https://nodejs.org/api/permissions.html
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    return major >= 23 || (major === 22 && minor >= 13);
+}
+/** Set after a sandbox retry so we do not pay the failed spawn twice. */
+let permissionFlagsUnsupported = false;
+/**
+ * True when the sandbox stopped the child before our runner produced anything.
+ *
+ * A denial raised by the USER's flow code must not trigger the retry: that
+ * would silently drop the sandbox for exactly the input it is protecting
+ * against. So this only matches a failure with no envelope on stdout, meaning
+ * the runner never got far enough to report.
+ */
+function sandboxRefusedToStart(result) {
+    if (parseEnvelope(result.stdout) !== undefined)
+        return false;
+    if (result.code === 9 && result.stderr.includes("bad option"))
+        return true;
+    return (result.stderr.includes("ERR_ACCESS_DENIED") || result.stderr.includes("ERR_DLOPEN_DISABLED"));
+}
+function runChild(args, cwd, env) {
+    return new Promise((resolveP, rejectP) => {
+        const child = spawn(process.execPath, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+        child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+        child.on("error", rejectP);
+        child.on("close", (code) => resolveP({ code, stdout, stderr }));
+    });
+}
+function parseEnvelope(stdout) {
+    // The envelope is the last sentinel-prefixed line; user code writing to
+    // stdout during module evaluation cannot fake or corrupt it earlier.
+    const lines = stdout.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line !== undefined && line.startsWith(SENTINEL)) {
+            return JSON.parse(line.slice(SENTINEL.length));
+        }
+    }
+    return undefined;
+}
+/**
+ * Evaluates the builder file in the sandboxed child and returns its flows.
+ * Throws SynthError with an actionable message on any failure.
+ */
+export async function synthFile(sourcePath) {
+    const absPath = resolve(sourcePath);
+    let sourceBytes;
+    try {
+        sourceBytes = await readFile(absPath);
+    }
+    catch {
+        throw new SynthError(`Cannot read ${absPath}: no such file. Pass the path of a .flow.ts builder file.`);
+    }
+    const sourceHash = `sha256:${sha256Hex(sourceBytes)}`;
+    const runner = resolveSibling("synth-runner");
+    const resolveHook = resolveSibling("synth-resolve-hook");
+    const loader = resolveTsxLoader();
+    const sourceDir = dirname(absPath);
+    // Private scratch dir for tsx (it writes a cache and an IPC pipe under
+    // os.tmpdir(), which honors TMPDIR/TEMP/TMP). This is the only path the
+    // permission model allows the child to write.
+    const scratch = await mkdtemp(join(tmpdir(), "flow-cli-synth-"));
+    const permissionArgs = supportsStablePermissionFlag() && !permissionFlagsUnsupported
+        ? ["--permission", "--allow-fs-read=*", `--allow-fs-write=${scratch}/`, "--allow-worker"]
+        : [];
+    // argv after the runner: the builder file, the resolution hook the runner
+    // registers before importing it, and the module URL that hook falls back to
+    // when the builder's own directory cannot resolve @flow-as-code/core. See
+    // synth-resolve-hook.ts.
+    const baseArgs = ["--import", loader, runner, absPath, resolveHook, import.meta.url];
+    const env = {
+        // Minimum the child needs: PATH for anything resolving binaries plus the
+        // temp override for tsx. Deliberately no NODE_OPTIONS, no AWS_*, no
+        // HOME-derived config.
+        PATH: process.env.PATH,
+        TMPDIR: scratch,
+        TEMP: scratch,
+        TMP: scratch,
+    };
+    try {
+        let result = await runChild([...permissionArgs, ...baseArgs], sourceDir, env);
+        if (permissionArgs.length > 0 && sandboxRefusedToStart(result)) {
+            // Two ways the permission model can stop the child from ever running our
+            // code: the runtime does not know the flags, or the TypeScript loader
+            // needs a capability we withheld (some versions shell out to compile).
+            // Both are environment problems rather than problems with the user's
+            // flow, so we retry unsandboxed rather than failing outright, and say so.
+            permissionFlagsUnsupported = true;
+            process.emitWarning("flow-cli synth: this runtime's permission model rejected the sandbox, " +
+                "so the builder file is being evaluated WITHOUT it. Environment stripping " +
+                "and the pinned working directory still apply. Upgrade Node to restore the sandbox.");
+            result = await runChild(baseArgs, sourceDir, env);
+        }
+        const envelope = parseEnvelope(result.stdout);
+        if (envelope === undefined) {
+            const detail = result.stderr.trim();
+            throw new SynthError(`Evaluating ${absPath} failed (exit code ${result.code ?? "unknown"}).` +
+                (detail === "" ? "" : `\n${detail}`));
+        }
+        if (envelope.error !== undefined) {
+            const frames = actionableFrames(envelope.error.stack, absPath);
+            throw new SynthError(`Evaluating ${absPath} threw: ${envelope.error.message}` +
+                (frames.length === 0 ? "" : `\n${frames.join("\n")}`));
+        }
+        const flows = envelope.flows ?? [];
+        if (flows.length === 0) {
+            throw new SynthError(`No flows exported from ${absPath}. Export a Flow instance or a zero-argument ` +
+                `function returning one (e.g. "export function myLine(): Flow { ... }").`);
+        }
+        return { flows, sourceHash };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** Serializes a doc with the meta this CLI stamps. Byte-stable. */
+export function serializeWithMeta(doc, sourceHash) {
+    return serialize({ ...doc, meta: { generator: GENERATOR, sourceHash } });
+}
+/**
+ * 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 async function synthToFiles(sourcePath, outDir) {
+    const absPath = resolve(sourcePath);
+    const dir = outDir === undefined ? dirname(absPath) : resolve(outDir);
+    const { flows, sourceHash } = await synthFile(absPath);
+    await mkdir(dir, { recursive: true });
+    const written = [];
+    for (const { name, doc } of flows) {
+        // The Flow constructor already rejects non-slug names, but the child
+        // process output is untrusted (a hostile module can fake a duck-typed
+        // Flow), so the name is re-checked here before it becomes a file path.
+        if (!SLUG_PATTERN.test(name)) {
+            throw new Error(`Refusing to write flow named "${name}": names must be lowercase words separated by single hyphens.`);
+        }
+        const docPath = join(dir, `${name}.flowdoc.json`);
+        await writeFile(docPath, serializeWithMeta(doc, sourceHash), "utf8");
+        written.push(docPath);
+    }
+    return written;
+}
+//# sourceMappingURL=synth.js.map

package/dist/synth.js.map

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

package/dist/watch.d.ts

@@ -0,0 +1,66 @@
+import type { FlowDoc } from "@flow-as-code/core";
+export interface SyncedEvent {
+    tsPath: string;
+    docPath: string;
+    name: string;
+}
+export interface ConflictEvent {
+    tsPath: string;
+    docPath: string;
+    name: string;
+    reason: string;
+}
+export interface ErrorEvent {
+    path: string;
+    message: string;
+}
+export interface WatcherEvents {
+    synced: SyncedEvent;
+    conflict: ConflictEvent;
+    error: ErrorEvent;
+    /** Initial scan finished and every startup synth settled. Not part of the
+     * A04 event contract; a convenience for consumers and tests. */
+    ready: Record<string, never>;
+}
+export interface FlowWatcher {
+    on<K extends keyof WatcherEvents>(event: K, listener: (payload: WatcherEvents[K]) => void): this;
+    off<K extends keyof WatcherEvents>(event: K, listener: (payload: WatcherEvents[K]) => void): this;
+    once<K extends keyof WatcherEvents>(event: K, listener: (payload: WatcherEvents[K]) => void): this;
+    /**
+     * Records a pair another part of this process just wrote as the clean
+     * baseline, so the watcher recognizes the write as its own instead of
+     * treating it as an external edit.
+     *
+     * The studio bridge (A11) writes both halves of a pair when the canvas
+     * saves: the FlowDoc and the regenerated builder source. Without this the
+     * watcher would see a ts change whose doc "changed externally" and emit a
+     * conflict for an edit the same process just made.
+     *
+     * Pass the exact bytes written. Call it AFTER both files are on disk:
+     * chokidar's awaitWriteFinish window (50 ms) is orders of magnitude longer
+     * than the gap between the writes and this call, so no event can be routed
+     * against a half-updated ledger. Contents that are not passed leave that
+     * half of the ledger alone.
+     */
+    noteWrite(name: string, contents: {
+        tsContent?: string;
+        docContent?: string;
+    }): void;
+    close(): Promise<void>;
+}
+/**
+ * The flow whose name matches the file base name, else a lone export. Exported
+ * so the studio bridge pairs a builder file with its FlowDoc by exactly the
+ * rule the watcher uses, rather than a second one that could disagree.
+ */
+export declare function pickDoc(flows: {
+    name: string;
+    doc: FlowDoc;
+}[], name: string): FlowDoc | undefined;
+/**
+ * Watches `dir` (non-recursive) and keeps every <name>.flow.ts /
+ * <name>.flowdoc.json pair in sync, ts -> doc, with the sourceHash dirty
+ * guard described at the top of this file.
+ */
+export declare function createWatcher(dir: string): FlowWatcher;
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAMlD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB;oEACgE;IAChE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACjG,GAAG,CAAC,CAAC,SAAS,MAAM,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAClG,IAAI,CAAC,CAAC,SAAS,MAAM,aAAa,EAChC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAC5C,IAAI,CAAC;IACR;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA4QD;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,EAAE,EACvC,IAAI,EAAE,MAAM,GACX,OAAO,GAAG,SAAS,CAKrB;AAYD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAEtD"}