@flow-as-code/cli 0.1.0

package/src/studio.ts

@@ -0,0 +1,143 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// `flow-cli studio [dir]`: serve the local visual editor over a directory.
+//
+// The command is thin on purpose. Everything it does is start the bridge in
+// src/bridge/server.ts, point it at the studio's built assets, and print the
+// URL; the interesting behaviour is testable there without a subprocess. It
+// asks the bridge for `ensurePairs`, which writes the missing `<name>.flow.ts`
+// for every document in the directory so that a directory of FlowDocs alone
+// can start the edit-the-builder-file loop, and prints what that wrote.
+//
+// The assets are resolved through the studio package's own exports rather than
+// a relative path, because @flow-as-code/cli is published and installed on its
+// own: in a user's node_modules the studio is a sibling package, not a sibling
+// directory. A studio that is installed but not built is the common local
+// failure and gets its own message naming the command that fixes it.
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, relative, resolve } from "node:path";
+
+import { PACKAGE_NAMES } from "@flow-as-code/core";
+
+import type { BridgeEvent } from "./bridge/protocol.js";
+import { startStudioServer, type StudioServer } from "./bridge/server.js";
+import { CliError } from "./errors.js";
+
+/** The studio's published entry point, resolved through its package exports. */
+const STUDIO_INDEX = `${PACKAGE_NAMES.studio}/dist/index.html`;
+const STUDIO_PACKAGE = `${PACKAGE_NAMES.studio}/package.json`;
+
+/**
+ * Absolute path of the built studio assets. Throws a CliError naming the fix
+ * when the package is missing or has not been built.
+ */
+export function resolveStudioAssets(): string {
+  const require = createRequire(import.meta.url);
+  let packageJson: string;
+  try {
+    packageJson = require.resolve(STUDIO_PACKAGE);
+  } catch {
+    throw new CliError(
+      `flow-cli studio needs ${PACKAGE_NAMES.studio}, which is not installed. ` +
+        `It ships as a dependency of ${PACKAGE_NAMES.cli}, so this usually means a partial install: ` +
+        `run "npm install".`,
+    );
+  }
+  const dist = resolve(dirname(packageJson), "dist");
+  if (!existsSync(resolve(dist, "index.html"))) {
+    throw new CliError(
+      `The studio has not been built: ${resolve(dist, "index.html")} does not exist. ` +
+        `Run "npm run build --workspace ${PACKAGE_NAMES.studio}" (or "npm run build" ` +
+        `at the repository root) and try again.`,
+    );
+  }
+  // Resolving the entry through the exports map as well, so a package whose
+  // exports stop publishing dist/ fails here rather than serving nothing.
+  try {
+    require.resolve(STUDIO_INDEX);
+  } catch {
+    throw new CliError(
+      `${PACKAGE_NAMES.studio} does not export ${STUDIO_INDEX.split("/").pop() ?? "dist"}; ` +
+        `this flow-cli is not compatible with the installed studio.`,
+    );
+  }
+  return dist;
+}
+
+export interface StudioOptions {
+  /** Commander passes strings; 0 or absent means "pick a free port". */
+  port?: string;
+  /** Test seam: skip the asset directory (API only). */
+  assetsDir?: string;
+}
+
+/** One line per bridge event, so the terminal shows the sync happening. */
+export function eventLine(event: BridgeEvent, dir: string): string {
+  const where = (path: string): string => relative(dir, path) || path;
+  switch (event.kind) {
+    case "synced":
+      return `synced   ${event.name}`;
+    case "conflict":
+      return `conflict ${event.name}: ${event.reason}`;
+    case "error":
+      return `error    ${where(event.path)}: ${event.message}`;
+  }
+}
+
+/**
+ * Starts the studio server and returns it. The caller keeps the process alive;
+ * the command body below waits for a signal.
+ */
+export async function runStudio(dir: string | undefined, options: StudioOptions = {}) {
+  const target = resolve(dir ?? process.cwd());
+  const port = options.port === undefined ? 0 : Number(options.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new CliError(`--port must be a whole number between 0 and 65535, not "${options.port}".`);
+  }
+
+  const assetsDir = options.assetsDir ?? resolveStudioAssets();
+  let server: StudioServer;
+  try {
+    server = await startStudioServer({
+      dir: target,
+      assetsDir,
+      port,
+      // A directory of FlowDocs with no builder files beside them cannot start
+      // the loop this command exists for, because there is nothing to edit.
+      ensurePairs: true,
+      onEvent: (event) => console.log(eventLine(event, target)),
+    });
+  } catch (error) {
+    throw new CliError(error instanceof Error ? error.message : String(error));
+  }
+
+  for (const { tsPath, name } of server.prepared.generated) {
+    console.log(`wrote    ${basename(tsPath)} from ${name}.flowdoc.json`);
+  }
+  for (const { name, message } of server.prepared.problems) {
+    console.log(`skipped  ${name}.flowdoc.json: ${message}`);
+  }
+  console.log(`flow-cli studio serving ${target}`);
+  console.log(`  open ${server.url}`);
+  console.log(`  the bridge listens on ${server.host} only; press Ctrl+C to stop`);
+  return server;
+}
+
+/** The command body: run until the terminal interrupts it. */
+export async function studioCommand(
+  dir: string | undefined,
+  options: StudioOptions,
+): Promise<void> {
+  const server = await runStudio(dir, options);
+  await new Promise<void>((resolveP) => {
+    const stop = () => {
+      void server.close().then(() => resolveP());
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}

package/src/synth-resolve-hook.ts

@@ -0,0 +1,152 @@
+/*
+ * 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: string | undefined;
+
+/**
+ * @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: string | undefined;
+
+export interface HookData {
+  fallbackParentURL?: string;
+  flowCorePackage?: string;
+}
+
+export function initialize(data: HookData | undefined): void {
+  fallbackParentURL = data?.fallbackParentURL;
+  flowCorePackage = data?.flowCorePackage;
+}
+
+interface ResolveContext {
+  parentURL?: string;
+  conditions?: readonly string[];
+  importAttributes?: Record<string, string>;
+}
+
+interface Resolution {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+
+type NextResolve = (specifier: string, context: ResolveContext) => Promise<Resolution>;
+
+function isFlowCore(specifier: string): boolean {
+  if (flowCorePackage === undefined) return false;
+  return specifier === flowCorePackage || specifier.startsWith(`${flowCorePackage}/`);
+}
+
+function isTypeScript(url: string): boolean {
+  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: string): boolean {
+  let dir: string;
+  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: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): Promise<Resolution> {
+  let resolution: 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 as NodeJS.ErrnoException).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;
+}

package/src/synth-runner.ts

@@ -0,0 +1,157 @@
+/*
+ * 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 type { Flow } from "@flow-as-code/core";
+import { PACKAGE_NAMES, synth } from "@flow-as-code/core";
+
+export const SYNTH_ENVELOPE_SENTINEL = "__FLOW_CLI_SYNTH_ENVELOPE_V1__";
+
+export interface SynthEnvelope {
+  flows?: { name: string; doc: unknown }[];
+  error?: { message: string; stack?: string };
+}
+
+/**
+ * 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: unknown): value is Flow {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  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: Record<string, unknown>): Flow[] {
+  const flows: Flow[] = [];
+  const seen = new Set<unknown>();
+  const push = (f: Flow) => {
+    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: unknown;
+      try {
+        result = (value as () => unknown)();
+      } 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: SynthEnvelope): void {
+  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: string, fallbackParentURL: string): void {
+  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(): Promise<void> {
+  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: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(sourcePath).href)) as Record<string, unknown>;
+  } 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<string, Flow>();
+  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();