@uniflowed/host 0.0.0-alpha.10

package/assets.js

@@ -0,0 +1,248 @@
+// @noflow
+//
+// Plain JavaScript: this runs in the host that runs Vite, beside
+// `transform.js`, and reaching the Flow transform is what that file is for.
+//
+// The JavaScript side of the `uf assets` service.
+//
+// Decoding, resizing and re-encoding images lives in `crates/uf_assets` and is
+// reached exactly the way the Flow transform is reached: one long-lived `uf`
+// process per host process, newline-delimited JSON in, replies in request
+// order out. The protocol is documented on the other side, in
+// `crates/uf_cli/src/commands/assets.rs`.
+//
+// Why a second service rather than a second message on the transform one: the
+// transform service runs on a thread with half a gigabyte of stack because
+// every stage of the Flow chain recurses, and it is started for every host
+// that touches a module — the Node loader hook and the Bun preload included,
+// neither of which has any use for an image pipeline. A build that imports no
+// images should not start a process that can resize them, and a `uf test` run
+// should not start one at all.
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import { ufBinary, ufBinaryIdentity } from "./transform.js";
+
+/**
+ * File extensions the pipeline claims.
+ *
+ * `.svg` is deliberately not among them. uf could only ever copy one through —
+ * it is already resolution independent, so there is nothing to resize — and
+ * claiming it would take `.svg` away from `vite-plugin-svgr` and everything
+ * like it, which turn one into a component. A plugin that claims an extension
+ * to do nothing with it is the shape of red line 8 in `docs/red-lines.md`: if
+ * Vite can do it, a uf project can do it. So an SVG import stays Vite's, and
+ * `<Image src={url} width={…} height={…} />` is how you render one.
+ *
+ * `.gif` and `.avif` *are* claimed even though no decoder for them is compiled
+ * in, and that is the opposite decision for a reason: uf has something to say
+ * about them. The import still evaluates to a manifest, and the manifest
+ * carries a `note` saying the file was served unchanged and why — which is
+ * what tells an author their AVIF is not being resized, rather than leaving
+ * them to notice.
+ */
+export const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif"];
+
+/** Font file extensions the pipeline claims. */
+export const FONT_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf"];
+
+/**
+ * Whether this import is one uf's asset pipeline handles, and as what.
+ *
+ * Returns `"image"`, `"font"`, or `null`. The query string is stripped first:
+ * `./hero.png?width=400` is an image, and the query is how an import says what
+ * it wants.
+ */
+export function assetKind(id) {
+  const clean = stripQuery(id);
+  const lower = clean.toLowerCase();
+  if (IMAGE_EXTENSIONS.some((extension) => lower.endsWith(extension))) return "image";
+  if (FONT_EXTENSIONS.some((extension) => lower.endsWith(extension))) return "font";
+  return null;
+}
+
+function stripQuery(id) {
+  const at = id.indexOf("?");
+  return at === -1 ? id : id.slice(0, at);
+}
+
+/** An asset the pipeline could not process. */
+export class AssetError extends Error {
+  constructor(id, message) {
+    super(message);
+    this.name = "AssetError";
+    this.id = id;
+  }
+}
+
+/**
+ * One `uf assets` process, with requests answered in the order they were sent.
+ *
+ * The same arrangement as `TransformService` next door, including the reason
+ * there are no correlation ids: the service replies once per request and in
+ * order, so a plain queue of resolvers pairs a reply with its caller. Any exit
+ * is final and every outstanding request is rejected at once.
+ */
+export class AssetService {
+  #child;
+  #pending = [];
+  #identity;
+  #failure = null;
+
+  /**
+   * @param {object} [options]
+   * @param {string} [options.command] the `uf` binary; `ufBinary()` by default
+   * @param {string} [options.root] project root, so `uf.config.js` is found
+   */
+  constructor(options = {}) {
+    const command = options.command ?? ufBinary();
+    const root = options.root ?? process.cwd();
+    // Read before the spawn and kept, for the reason `TransformService` gives:
+    // the child goes on executing the binary it started from however many
+    // times that file is rewritten underneath it, and anything cached from an
+    // answer of this service belongs under *this* identity.
+    this.#identity = ufBinaryIdentity(command);
+    this.#child = spawn(command, ["--cwd", root, "assets"], {
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+
+    createInterface({ input: this.#child.stdout }).on("line", (line) => {
+      const waiting = this.#pending.shift();
+      if (!waiting) return;
+      let reply;
+      try {
+        reply = JSON.parse(line);
+      } catch {
+        waiting.reject(new Error(`uf assets sent a malformed reply: ${line}`));
+        return;
+      }
+      if (reply.error != null) {
+        waiting.reject(new AssetError(waiting.id, reply.error));
+        return;
+      }
+      waiting.resolve(reply);
+    });
+
+    this.#child.on("error", (error) => {
+      this.#settleAll(new Error(`could not run \`${command} assets\`: ${error.message}`));
+    });
+    this.#child.on("close", (code) => {
+      this.#settleAll(new Error(`uf assets exited (${code})`));
+    });
+  }
+
+  #send(request) {
+    if (this.#failure) return Promise.reject(this.#failure);
+    return new Promise((resolve, reject) => {
+      this.#pending.push({ id: request.id, resolve, reject });
+      this.#child.stdin.write(`${JSON.stringify(request)}\n`);
+    });
+  }
+
+  #settleAll(error) {
+    this.#failure = error;
+    while (this.#pending.length > 0) this.#pending.shift().reject(error);
+  }
+
+  /**
+   * Resize and re-encode one image.
+   *
+   * Resolves to the manifest the component reads: `{ width, height, format,
+   * variants, blur, declined, note }`. Every field is named here rather than
+   * passed through, which is deliberate and is the bug `transform.js` records
+   * next door: a shim that copies three of four fields drops the fourth
+   * silently, and the caller sees `undefined` rather than an error.
+   *
+   * @param {string} id absolute path to the source image
+   * @param {object} options
+   * @param {string} options.outDir where variants are written
+   * @param {number[]} [options.widths] overriding the project's
+   * @param {number} [options.quality]
+   * @param {boolean} [options.blur]
+   */
+  async image(id, options) {
+    const reply = await this.#send({
+      kind: "image",
+      id,
+      outDir: options.outDir,
+      widths: options.widths,
+      quality: options.quality,
+      blur: options.blur,
+    });
+    const image = reply.image;
+    if (image == null) throw new AssetError(id, "uf assets returned no image");
+    return {
+      width: image.width ?? null,
+      height: image.height ?? null,
+      format: image.format,
+      variants: image.variants ?? [],
+      blur: image.blur ?? null,
+      declined: image.declined ?? [],
+      note: image.note ?? null,
+    };
+  }
+
+  /**
+   * Self-host one font and describe it.
+   *
+   * Resolves to `{ file, mime, bytes, family, fallbackFamily, container,
+   * metrics, fallback, fallbackDeclined, css }`.
+   *
+   * @param {string} id absolute path to the source font
+   * @param {object} options
+   * @param {string} options.outDir where the copy is written
+   * @param {string} [options.family]
+   * @param {string} [options.weight]
+   * @param {string} [options.style]
+   * @param {string} [options.display]
+   * @param {string} [options.baseUrl] prefixed to the file name in `src: url()`
+   * @param {string | null} [options.fallback] `null` for no fallback face
+   */
+  async font(id, options) {
+    const request = {
+      kind: "font",
+      id,
+      outDir: options.outDir,
+      family: options.family,
+      weight: options.weight,
+      style: options.style,
+      display: options.display,
+      baseUrl: options.baseUrl,
+    };
+    // Only sent when the caller had an opinion. The service distinguishes "not
+    // mentioned, use the project's" from "explicitly none", and a key that is
+    // always present collapses the two.
+    if ("fallback" in options) request.fallback = options.fallback;
+    const reply = await this.#send(request);
+    const font = reply.font;
+    if (font == null) throw new AssetError(id, "uf assets returned no font");
+    return {
+      file: font.file,
+      mime: font.mime,
+      bytes: font.bytes,
+      family: font.family,
+      fallbackFamily: font.fallbackFamily ?? null,
+      container: font.container,
+      metrics: font.metrics,
+      fallback: font.fallback ?? null,
+      fallbackDeclined: font.fallbackDeclined ?? null,
+      css: font.css,
+    };
+  }
+
+  /**
+   * The build of `uf` this service's child is executing, or `null`.
+   *
+   * @returns {string | null}
+   */
+  get identity() {
+    return this.#identity;
+  }
+
+  /** Stop the process. Outstanding requests are rejected. */
+  close() {
+    this.#child.stdin.end();
+    this.#child.kill();
+  }
+}

package/bun-preload.js

@@ -0,0 +1,24 @@
+// @noflow
+//
+// Plain JavaScript: this file registers the loader, so it cannot need one.
+//
+// `bun --preload @uniflowed/vite/bun-preload app.js` runs a Flow project on
+// Bun without a build step, through Bun's own plugin API: every module uf is
+// responsible for is transformed by `uf transform` as Bun loads it. It is the
+// Bun counterpart of `./register.js`, and the policy of which files count is
+// the same `isFlowModule`.
+
+import { isFlowModule, transformFlow } from "./transform.js";
+
+Bun.plugin({
+  name: "uniflowed-flow",
+  setup(build) {
+    build.onLoad({ filter: /\.(js|jsx|mjs)$/ }, async (args) => {
+      if (!isFlowModule(args.path)) return undefined;
+      const source = await Bun.file(args.path).text();
+      const out = await transformFlow(source, args.path, { development: true, sourceMap: false });
+      if (out == null) return undefined;
+      return { contents: out.code, loader: "js" };
+    });
+  },
+});

package/internal/node-hooks.js

@@ -0,0 +1,147 @@
+// @noflow
+//
+// Plain JavaScript: this *is* the loader, so it cannot be Flow.
+//
+// Node.js module customization hooks that transform Flow on import.
+//
+// Registered by `@uniflowed/host/register` (through `node:module`'s
+// `register()`), which makes `node --import @uniflowed/host/register app.js`
+// run a Flow project directly: every `.js` module uf is responsible for is
+// transformed as it is loaded through `uf transform`, and everything else is
+// left to Node.
+//
+// Transforms are cached on disk under `.uf/cache/transform/` keyed by a hash
+// of the source *and* of the `uf` that compiled it, so a second run of the
+// same file is a read rather than a round trip.
+//
+// Both halves are load-bearing. The key was the source alone at first, on the
+// reasoning that a content-addressed cache has no invalidation to get wrong —
+// which quietly assumed the compiler was a constant. It is not: edit
+// `crates/uf_transform` or `crates/uf_stylex`, rebuild, run `uf test`, and
+// every module whose *source* had not changed came back as the previous
+// binary had compiled it. The suite then passed, or failed, for the previous
+// build's reasons, and the only symptom was an answer that made no sense.
+// `rm -rf .uf/cache/transform` was the cure, and finding that out cost a
+// debugging session while `@uniflowed/stylex`'s preset was being written.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isFlowModule, sharedService, transformFlow, ufBinaryIdentity } from "../transform.js";
+import { writeAtomically } from "../write-atomically.js";
+
+/**
+ * Bumped whenever *this file's* framing of the output changes, to retire old
+ * entries.
+ *
+ * Not the compiler's version, which is `ufBinaryIdentity` and which nobody
+ * has to remember. What is left for this to cover is what the loader adds
+ * around a transform — the appended source map, the module format it forces —
+ * and that is all it should ever be bumped for.
+ */
+const CACHE_VERSION = "2";
+
+let cacheDirectory = null;
+let root = null;
+
+/**
+ * Called once by `register()` with `{ root }`; the cache lives under it and
+ * the transform service is started there so it reads the right config.
+ */
+export async function initialize(data) {
+  root = data?.root ?? process.cwd();
+  cacheDirectory = path.join(root, ".uf", "cache", "transform");
+}
+
+/**
+ * The `load` hook: transform Flow modules, defer everything else.
+ */
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith("file:")) return nextLoad(url, context);
+  const filename = fileURLToPath(url);
+  if (!isFlowModule(filename)) return nextLoad(url, context);
+
+  const source = readFileSync(filename, "utf8");
+  const code = await cachedTransform(source, filename);
+  if (code == null) return nextLoad(url, context);
+  // uf projects are ES modules. Forcing the format here means a project whose
+  // package.json forgot `"type": "module"` still runs, rather than failing on
+  // an `import` in what Node would have guessed was CommonJS.
+  return { format: "module", source: code, shortCircuit: true };
+}
+
+/**
+ * The file this module's compiled form belongs in under `identity`, or `null`
+ * when it must not be cached at all.
+ *
+ * `null` when there is no cache directory, and — the case worth spelling out —
+ * when the caller has no identity to give: nothing is read and nothing is
+ * written. Hashing the rest anyway would give every build of `uf` one key
+ * again, and writing under it would leave an entry for the next run to trust.
+ * A host that cannot name its compiler compiles everything, every time, which
+ * is slower and is never wrong.
+ */
+function cacheEntryFor(identity, source, filename) {
+  if (cacheDirectory == null || identity == null) return null;
+  const key = createHash("sha256")
+    .update(CACHE_VERSION)
+    .update("\0")
+    .update(identity)
+    .update("\0")
+    .update(filename)
+    .update("\0")
+    .update(source)
+    .digest("hex");
+  return path.join(cacheDirectory, `${key}.mjs`);
+}
+
+/**
+ * The compiled form of one module, from disk if some build already produced
+ * it and from `uf` otherwise.
+ *
+ * The two keys are computed from two different identities on purpose.
+ *
+ * The **read** is keyed by the binary as it is *now*, stat'd per module rather
+ * than once when the hooks were installed. A rebuild between installing them
+ * and loading the first Flow module would otherwise serve the old build's
+ * output while the new one is what would run — the same staleness this key
+ * exists to remove, with a smaller window. A stat is a microsecond and a
+ * fully warm run still spawns nothing, which is the property that decided the
+ * key's shape in the first place.
+ *
+ * The **write** is keyed by the binary the compiler process is actually
+ * executing, which `sharedService` read before it spawned and which cannot
+ * change afterwards. Keying the write by the file's current state would file
+ * this build's output under the next build's name if the rebuild landed while
+ * the module was being compiled — the same lie pointing the other way.
+ *
+ * They are usually the same string. When they are not, a rebuild happened
+ * during this run, and each half is right about its own half.
+ */
+async function cachedTransform(source, filename) {
+  const entry = cacheEntryFor(ufBinaryIdentity(), source, filename);
+
+  if (entry) {
+    try {
+      return readFileSync(entry, "utf8");
+    } catch {
+      // not cached yet
+    }
+  }
+
+  const out = await transformFlow(source, filename, { root, development: true, sourceMap: true });
+  if (out == null) return null;
+  const output = out.map
+    ? `${out.code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(out.map).toString("base64")}\n`
+    : out.code;
+
+  const written = cacheEntryFor(sharedService(root).identity, source, filename);
+  if (written) {
+    // Tolerant: a cache that cannot be written is a slower run, not a
+    // failed one — a read-only checkout still works.
+    writeAtomically(written, output, { tolerant: true });
+  }
+  return output;
+}

package/module-mocks.js

@@ -0,0 +1,356 @@
+// @noflow
+//
+// Plain JavaScript: this is part of the loader, and `bun-preload.js` imports
+// it before any transform exists.
+//
+// Standing a module in for another one, at the only place that can do it: the
+// loader. `@uniflowed/test`'s `uft.mock` is the API; this is the mechanism, and
+// it lives here because by the time the runner sees an `import` the module has
+// already been fetched, linked and evaluated.
+//
+// # Why these are *synchronous* hooks
+//
+// `./register.js` installs Node's asynchronous customization hooks, and those
+// run on a loader thread of their own. That is right for the transform, which
+// only needs the file's bytes — and useless for a mock, which is a value the
+// test built: a spy the test holds a reference to cannot be sent to another
+// thread, and a registry written on the main thread is not a registry the
+// loader thread can read.
+//
+// So interception uses `node:module`'s `registerHooks`, which run in the thread
+// that is doing the importing. They see this module's `mocks` map directly, and
+// they chain into the asynchronous hooks for everything they do not claim — so
+// a module that is not mocked is still transformed, still cached on disk, and
+// still costs exactly what it cost before.
+//
+// # Why a mocked module gets a URL of its own
+//
+// A worker runs one file at a time and reuses the process, and Node's module
+// registry is keyed by URL and never forgets. If a mocked module were served
+// under its own URL, the *next* file in that worker would import the plain
+// specifier and be handed the previous file's stand-in — a mock leaking across
+// files, which is the one failure `docs/architecture.md` says the runner exists
+// to prevent.
+//
+// So a mock does not replace a module; it redirects to a new one. Registering a
+// mock takes the next revision number, the resolve hook appends it to the URL,
+// and the mocked module is a different module from the real one rather than the
+// same module with different contents. `unmock` stops appending, so the real
+// URL — which may still hold the real module — is what the next import gets.
+// Revisions are handed out for the life of the worker and never reused, which
+// is what makes a cleared registry actually clear.
+//
+// The same parameter carries the module *epoch*. A module that imports a mocked
+// one is standing in for it too — `consumer.js` computed its exports from
+// whatever `client.js` gave it — so registering a mock, removing one, or
+// calling `uft.resetModules` all start a new epoch, and every module reached by
+// a path is evaluated again on the next import of it. Epochs are handed out for
+// the life of the worker and never reused, for the reason revisions are not:
+// the file after this one must not be able to land on a URL this one filled.
+//
+// The epoch is appended only to modules reached by a path specifier (`./x.js`,
+// `/srv/x.js`): a bare specifier is a package, and handing a second copy of
+// `@uniflowed/test` to a test file would give it a second registry, a second
+// set of spies, and two of everything this package assumes there is one of. A
+// *mocked* package still gets a URL of its own, from its revision — being
+// stood in for is exactly the case where identity has to be given up.
+
+import * as nodeModule from "node:module";
+
+/** The URL parameter carrying `<module epoch>.<mock revision>`. */
+export const REVISION_PARAM = "uf-modules";
+
+/** The URL parameter marking an import that must reach the real module. */
+export const ACTUAL_PARAM = "uf-actual";
+
+/** This module's own URL, which a generated stand-in imports its values from. */
+const SELF = import.meta.url;
+
+/** Registered mocks, by module key. */
+const mocks = new Map();
+
+/** Namespaces handed to a generated module, by the exact URL it was loaded as. */
+const served = new Map();
+
+/** How many mocks have ever been registered in this process. */
+let revisions = 0;
+
+/** How many epochs have ever been started in this process. */
+let epochs = 0;
+
+/** The epoch this file is in; `0` until it does something that starts one. */
+let epoch = 0;
+
+/** The installed hooks, or `null` when interception is not installed. */
+let handle = null;
+
+/**
+ * A module's identity for the purpose of mocking: its URL with no query.
+ *
+ * The query is where every mechanism in this file writes — the worker's
+ * cache-busting `uf-run`, this file's revision, `importActual`'s marker — so
+ * two URLs that differ only there are the same module as far as a mock is
+ * concerned.
+ */
+export function moduleKey(url) {
+  const parsed = new URL(url);
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.href;
+}
+
+/**
+ * Whether this host can intercept a module before it is imported.
+ *
+ * The one requirement is synchronous, in-thread module hooks. Node has them;
+ * Bun's `node:module` has neither `register` nor `registerHooks`, and Deno has
+ * no loader in `@uniflowed/host` at all. `@uniflowed/test` turns a `false` here
+ * into an error that names the host rather than a mock that quietly does
+ * nothing.
+ */
+export function interceptionSupported() {
+  return typeof nodeModule.registerHooks === "function";
+}
+
+/**
+ * Install the interception hooks, once.
+ *
+ * Called on the first `uft.mock` or `uft.resetModules` rather than at import,
+ * because a resolve hook that runs for every specifier in the process is not
+ * something a suite that never mocks anything should pay for.
+ */
+export function installInterception() {
+  if (handle != null) {
+    return true;
+  }
+  if (!interceptionSupported()) {
+    return false;
+  }
+  handle = nodeModule.registerHooks({ load: loadHook, resolve: resolveHook });
+  return true;
+}
+
+/**
+ * Register `namespace` as the stand-in for the module at `url`.
+ *
+ * Returns nothing: what the caller needs is that the *next* resolution of that
+ * module lands somewhere else, which the resolve hook arranges from the
+ * revision recorded here.
+ */
+export function defineModuleMock(url, namespace) {
+  revisions += 1;
+  mocks.set(moduleKey(url), { namespace, revision: revisions });
+  startModuleEpoch();
+}
+
+/** Stop standing in for the module at `url`. */
+export function removeModuleMock(url) {
+  if (!mocks.delete(moduleKey(url))) {
+    return false;
+  }
+  startModuleEpoch();
+  return true;
+}
+
+/** Whether the module at `url` is currently stood in for. */
+export function isModuleMocked(url) {
+  return mocks.has(moduleKey(url));
+}
+
+/** The epoch path imports are currently loading into. */
+export function moduleEpoch() {
+  return epoch;
+}
+
+/**
+ * Begin a new epoch, so a path import evaluates its module again.
+ *
+ * Counted process-wide rather than per file. A file that reused the number a
+ * previous file's epoch had would be handed that file's modules, mocks and all,
+ * which is the leak the whole scheme exists to prevent.
+ */
+export function startModuleEpoch() {
+  epochs += 1;
+  epoch = epochs;
+  return epoch;
+}
+
+/**
+ * Forget every mock and leave the epoch.
+ *
+ * Called by the worker between files. Epochs and revisions deliberately keep
+ * counting: the next file's mock of the same module must not be handed the URL
+ * this file's mock is cached under.
+ */
+export function resetModuleMocks() {
+  mocks.clear();
+  served.clear();
+  epoch = 0;
+}
+
+/**
+ * The URL an import that must reach the real module should use.
+ *
+ * A mocked module is standing at the URL an ordinary import resolves to, so
+ * reaching past it takes a URL of its own — one per epoch, so that two calls in
+ * a row hand back the same module rather than compiling it twice.
+ *
+ * A module nobody is standing in for needs no marker: the URL an ordinary
+ * import would use already holds the real thing, and taking the marked path
+ * anyway would hand back a second copy of a module the test is already holding.
+ *
+ * `pathLike` is whether the caller wrote a path rather than a package name, and
+ * it is not a detail: this is the resolve hook's rule applied by hand, and the
+ * rule is that a package keeps its identity across an epoch. Getting it wrong
+ * here would hand a test a second copy of `@uniflowed/test` — a second registry
+ * and a second set of spies — from the one call that is supposed to reach the
+ * real thing.
+ */
+export function actualUrl(url, pathLike) {
+  const parsed = new URL(url);
+  if (!mocks.has(moduleKey(url))) {
+    if (epoch !== 0 && pathLike) {
+      parsed.searchParams.set(REVISION_PARAM, `${epoch}.0`);
+    }
+    return parsed.href;
+  }
+  parsed.searchParams.set(ACTUAL_PARAM, String(epoch));
+  return parsed.href;
+}
+
+/**
+ * The values a generated stand-in module exports.
+ *
+ * Keyed by the exact URL the stand-in was loaded as rather than by the module
+ * key, so that a stand-in evaluated after its mock was replaced still reads the
+ * namespace its export list was written from.
+ */
+export function namespaceFor(url) {
+  const namespace = served.get(url);
+  if (namespace == null) {
+    throw new Error(`@uniflowed/host: no mocked namespace was recorded for ${url}`);
+  }
+  return namespace;
+}
+
+/**
+ * The source of the stand-in module for `url`, or `null` when there is none.
+ *
+ * An ES module's export names are fixed when it is compiled, so they are
+ * written out here from the keys the mock actually has. That is the whole
+ * reason this returns source rather than an object: a namespace object cannot
+ * be handed to `import`, and a module with the wrong names would fail to link
+ * with an error about the importer rather than about the mock.
+ */
+export function mockedSource(url) {
+  const parsed = new URL(url);
+  if (parsed.searchParams.has(ACTUAL_PARAM)) {
+    return null;
+  }
+  const record = mocks.get(moduleKey(url));
+  if (record == null) {
+    return null;
+  }
+
+  served.set(url, record.namespace);
+  const lines = [
+    `import { namespaceFor } from ${JSON.stringify(SELF)};`,
+    `const values = namespaceFor(${JSON.stringify(url)});`,
+  ];
+  const bindings = [];
+  for (const [index, name] of Object.keys(record.namespace).entries()) {
+    lines.push(`const binding${index} = values[${JSON.stringify(name)}];`);
+    bindings.push(`binding${index} as ${exportName(name)}`);
+  }
+  // `export {}` rather than nothing, so a mock with no exports is still an ES
+  // module: without an export or import declaration Node would have to guess
+  // the format from the package, and the guess is not always "module".
+  lines.push(bindings.length === 0 ? "export {};" : `export { ${bindings.join(", ")} };`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** How an export is named in an `export {}` clause. */
+function exportName(name) {
+  // Reserved words are fine — `export { x as default }` is the whole point —
+  // but anything that is not an identifier at all has to be a string, which
+  // ES2022 allows and which is how a mock keeps a name like `foo-bar`.
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+/**
+ * The `load` hook: serve a stand-in, or defer to the transform.
+ *
+ * Deferring is the common case and has to stay cheap: with no mocks registered
+ * this is one map lookup on an empty map.
+ */
+function loadHook(url, context, nextLoad) {
+  if (mocks.size === 0 || !url.startsWith("file:")) {
+    return nextLoad(url, context);
+  }
+  const source = mockedSource(url);
+  if (source == null) {
+    return nextLoad(url, context);
+  }
+  return { format: "module", shortCircuit: true, source };
+}
+
+/**
+ * The `resolve` hook: send an import to the revision it belongs to.
+ *
+ * Runs after the rest of the chain, so what it rewrites is a fully resolved
+ * URL rather than a specifier it would have to resolve itself.
+ */
+function resolveHook(specifier, context, nextResolve) {
+  const resolved = nextResolve(specifier, context);
+  if (mocks.size === 0 && epoch === 0) {
+    return resolved;
+  }
+  const url = redirect(specifier, context?.parentURL, resolved?.url);
+  return url === resolved.url ? resolved : { ...resolved, url };
+}
+
+/** Where an import of `url` should actually go. */
+function redirect(specifier, parentURL, url) {
+  if (typeof url !== "string" || !url.startsWith("file:")) {
+    return url;
+  }
+  const parsed = new URL(url);
+  // Already answered: `importActual` names the URL it wants, and a URL that
+  // carries a revision was produced by this function on the way in.
+  if (parsed.searchParams.has(ACTUAL_PARAM) || parsed.searchParams.has(REVISION_PARAM)) {
+    return url;
+  }
+
+  const revision = mocks.get(moduleKey(url))?.revision ?? 0;
+  // A package keeps its identity across an epoch; a module of this project's
+  // own does not. See the note at the top of the file.
+  const at = isPathSpecifier(specifier) ? epochOf(parentURL) : 0;
+  if (revision === 0 && at === 0) {
+    return url;
+  }
+  parsed.searchParams.set(REVISION_PARAM, `${at}.${revision}`);
+  return parsed.href;
+}
+
+/** Whether `specifier` names a file rather than a package. */
+function isPathSpecifier(specifier) {
+  return specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+}
+
+/**
+ * The epoch an import from `parentURL` belongs to.
+ *
+ * A module loaded in epoch two loads its own dependencies in epoch two, however
+ * many mocks have been registered since: a graph half of which is one epoch and
+ * half another is two copies of a module that expects to be one.
+ */
+function epochOf(parentURL) {
+  if (parentURL == null || !parentURL.startsWith("file:")) {
+    return epoch;
+  }
+  const carried = new URL(parentURL).searchParams.get(REVISION_PARAM);
+  if (carried == null) {
+    return epoch;
+  }
+  return Number.parseInt(carried.split(".")[0], 10);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@uniflowed/host",
+  "version": "0.0.0-alpha.10",
+  "description": "Running Flow on a Capability JS Host, with no bundler in the way.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/host"
+  },
+  "exports": {
+    "./assets": "./assets.js",
+    "./bun-preload": "./bun-preload.js",
+    "./internal/node-hooks.js": "./internal/node-hooks.js",
+    "./module-mocks": "./module-mocks.js",
+    "./register": "./register.js",
+    "./transform": "./transform.js",
+    "./write-atomically": "./write-atomically.js"
+  },
+  "files": [
+    "register.js",
+    "assets.js",
+    "bun-preload.js",
+    "module-mocks.js",
+    "transform.js",
+    "write-atomically.js",
+    "internal/*.js"
+  ]
+}

package/register.js

@@ -0,0 +1,13 @@
+// @noflow
+//
+// Plain JavaScript: this file registers the loader, so it cannot need one.
+//
+// `node --import @uniflowed/host/register app.js` runs a Flow project on
+// Node.js without a build step. Importing this module installs the hooks in
+// `./internal/node-hooks.js` for the rest of the process.
+
+import { register } from "node:module";
+
+register("./internal/node-hooks.js", import.meta.url, {
+  data: { root: process.env.UF_PROJECT_ROOT ?? process.cwd() },
+});

package/transform.js

@@ -0,0 +1,322 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform
+// exists — this module is how the transform is reached, so it cannot be Flow.
+//
+// The Flow → JavaScript transform lives in `uf` itself (`crates/uf_transform`:
+// the official Flow parser, Flow's own lowering rules, the official React
+// Compiler, oxc for JSX and code generation). This module is the JavaScript
+// side of the `uf transform` service: one long-lived `uf` process per host
+// process, newline-delimited JSON in, replies in request order out.
+//
+// Every host that runs Flow — the Vite plugin, the Node loader hook, the Bun
+// preload, the config loader — goes through here, which is what makes them
+// all produce the same module from the same source.
+
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+
+/** File extensions uf treats as Flow source. */
+export const FLOW_EXTENSIONS = [".js", ".jsx", ".mjs", ".cjs"];
+
+/**
+ * Whether uf is responsible for transforming this module.
+ *
+ * Mirrors `uf_transform::is_flow_module`, and must keep mirroring it: a `uf
+ * dev` session and a `uf test` run that disagree about which files are Flow
+ * disagree about what the code is.
+ *
+ * A build tool synthesises modules of its own — ids beginning with a NUL byte,
+ * a bundler's shims — and a third-party dependency ships JavaScript that is
+ * already JavaScript; neither is Flow. `@uniflowed/*` under `node_modules` is
+ * the deliberate exception: those packages ship Flow source, because that is
+ * what uf tells everyone to write.
+ *
+ * Which build tool is deliberately not named. This loader runs Flow on a
+ * Capability JS Host and has no bundler in it; naming one would tie the answer
+ * to a tool that is not in this file's dependency graph.
+ */
+export function isFlowModule(id) {
+  if (id.startsWith("\0")) return false;
+  const clean = stripQuery(id);
+  if (!FLOW_EXTENSIONS.some((extension) => clean.endsWith(extension))) return false;
+  const at = clean.lastIndexOf("/node_modules/");
+  return at === -1 || clean.slice(at).startsWith("/node_modules/@uniflowed/");
+}
+
+function stripQuery(id) {
+  const at = id.indexOf("?");
+  return at === -1 ? id : id.slice(0, at);
+}
+
+/**
+ * The `uf` binary to talk to.
+ *
+ * `uf dev`, `uf build` and `uf test` set `UF_BINARY` to themselves when they
+ * start a host, so the host reaches exactly the binary that started it. A host
+ * started by hand finds `uf` on PATH, which is what the installer arranges.
+ */
+export function ufBinary() {
+  return process.env.UF_BINARY ?? "uf";
+}
+
+/**
+ * Which *build* of `uf` a host will transform through, or `null` when that
+ * cannot be established.
+ *
+ * `ufBinary()` names the compiler; this identifies it. Anything kept across
+ * runs needs the second, because the first does not change when the compiler
+ * does: `crates/uf_transform` is edited, `cargo build` writes a new binary
+ * over the old one, and every answer already on disk is now wrong while the
+ * name that produced them is unchanged. A version string is the same promise
+ * one step removed — every build between two releases shares one.
+ *
+ * So: the size and modification time of the file that will be executed. They
+ * move together on every rebuild, they are one `stat` away, and — this is the
+ * part that decided it — reading them does not require starting `uf`. A run
+ * that finds everything already compiled must not have to spawn the compiler
+ * to learn that it does not need it, which is what asking the running
+ * `uf transform` to introduce itself would have cost.
+ *
+ * The same test is applied to a path as to a bare name: a regular file with
+ * the execute bit. Size and mtime do not move when a binary loses that bit, so
+ * without the test a chmod produced the same identity as before, a warm cache
+ * went on serving, and a cold one failed to start `uf` — the answer depending
+ * on how warm the cache was, which is the class of bug this key exists to
+ * remove.
+ *
+ * `null` means the question could not be answered. It is not an invitation to
+ * hash the rest anyway: a key that leaves the compiler out is one key for
+ * every build of it, which is the whole defect.
+ *
+ * @param {string} [command] the binary; `ufBinary()` by default
+ * @returns {string | null} an opaque identity, stable while that build is
+ */
+export function ufBinaryIdentity(command = ufBinary()) {
+  const binary = resolveExecutable(command);
+  if (binary == null) return null;
+  try {
+    const stats = statSync(binary);
+    if (!stats.isFile()) return null;
+    accessSync(binary, constants.X_OK);
+    return `${binary}\0${stats.size}\0${stats.mtimeMs}`;
+  } catch {
+    // Named a binary that is not there, or is not one. The caller gets `null`
+    // and stops trusting the cache, which is right: nothing can be compiled
+    // either.
+    return null;
+  }
+}
+
+/**
+ * The file `spawn` will execute for `command`, or `null` when there is none.
+ *
+ * A bare name is searched along PATH the way `execvp` searches for it — the
+ * first regular, executable file wins — so that the identity above describes
+ * the binary that actually runs rather than some other `uf` further down the
+ * list. Getting this wrong is not a slow cache but a silently stale one, which
+ * is why a directory named `uf` is skipped here as `execvp` skips it, rather
+ * than being accepted because `access` says a directory is executable.
+ *
+ * Windows resolves a bare name by rules of its own — `PATHEXT`, the current
+ * directory — which this does not implement. There a bare name is `null` and
+ * the caller falls back to not caching, rather than to caching under the
+ * identity of a file that may not be the one that ran. `UF_BINARY`, which is
+ * how every uf-started host arrives here, is an absolute path on every
+ * platform and never takes this path at all.
+ */
+function resolveExecutable(command) {
+  // A path is taken as given — `spawn` will execute exactly it — and
+  // `ufBinaryIdentity` applies the file-and-executable test to the result
+  // either way, so a path that is a directory or is not executable is no more
+  // trusted than a bare name that resolves to one.
+  if (path.basename(command) !== command) return command;
+  for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (directory === "") continue;
+    const candidate = path.join(directory, command);
+    try {
+      if (!statSync(candidate).isFile()) continue;
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Not in this directory. Keep looking, exactly as the shell would.
+    }
+  }
+  return null;
+}
+
+/**
+ * An error the transform reported for one module, with its position when
+ * the parser or the lowering rules gave one.
+ */
+export class TransformError extends Error {
+  constructor(id, message, line, column) {
+    super(message);
+    this.name = "TransformError";
+    this.id = id;
+    this.loc = line != null ? { file: id, line, column: column ?? 0 } : undefined;
+  }
+}
+
+/**
+ * One `uf transform` process, with requests answered in the order they were
+ * sent.
+ *
+ * `uf transform` replies once per request, in order, so a plain queue of
+ * resolvers pairs a reply with its caller — no correlation ids and no map to
+ * leak. Any exit is final: a request made after the process has gone is
+ * rejected at once rather than queued against something that will never
+ * answer.
+ */
+export class TransformService {
+  #child;
+  #pending = [];
+  #identity;
+  #failure = null;
+
+  /**
+   * @param {object} [options]
+   * @param {string} [options.command] the `uf` binary; `ufBinary()` by default
+   * @param {string} [options.root] project root, so `uf.config.js` is found
+   */
+  constructor(options = {}) {
+    const command = options.command ?? ufBinary();
+    const root = options.root ?? process.cwd();
+    // Read before the spawn and kept: this is the identity of the build that
+    // answers every request this service ever serves, because a child goes on
+    // executing the binary it started from however many times that file is
+    // rewritten underneath it. Anything written to disk from an answer of
+    // this service belongs under *this* identity — a caller that stat'd the
+    // binary earlier and wrote under that would file build B's output under
+    // build A's name, which is the original defect with a smaller window.
+    this.#identity = ufBinaryIdentity(command);
+    this.#child = spawn(command, ["--cwd", root, "transform"], {
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+
+    createInterface({ input: this.#child.stdout }).on("line", (line) => {
+      const waiting = this.#pending.shift();
+      if (!waiting) return;
+      let reply;
+      try {
+        reply = JSON.parse(line);
+      } catch {
+        waiting.reject(new Error(`uf transform sent a malformed reply: ${line}`));
+        return;
+      }
+      if (reply.error != null) {
+        waiting.reject(new TransformError(waiting.id, reply.error, reply.line, reply.column));
+        return;
+      }
+      waiting.resolve(reply);
+    });
+
+    this.#child.on("error", (error) => {
+      this.#settleAll(new Error(`could not run \`${command} transform\`: ${error.message}`));
+    });
+    this.#child.on("close", (code) => {
+      this.#settleAll(new Error(`uf transform exited (${code})`));
+    });
+  }
+
+  #settleAll(error) {
+    this.#failure = error;
+    while (this.#pending.length > 0) this.#pending.shift().reject(error);
+  }
+
+  /**
+   * Transform one module.
+   *
+   * Resolves to `{ code, map, css, diagnostics }`, or to `null` when the
+   * module is not uf's to transform (see `isFlowModule`). Rejects with a
+   * `TransformError` carrying the position when the source is not valid Flow.
+   *
+   * `css` is the stylesheet the module's StyleX rules declare, and `null` when
+   * it declares none.
+   *
+   * @param {string} id absolute path, used for the map and for errors
+   * @param {string} code the Flow source
+   * @param {object} [options]
+   * @param {boolean} [options.development] readable output, `jsxDEV`
+   * @param {boolean} [options.refresh] Fast Refresh registrations (development only)
+   * @param {boolean} [options.sourceMap] produce a source map; on by default
+   */
+  transform(id, code, options = {}) {
+    if (this.#failure) return Promise.reject(this.#failure);
+    return new Promise((resolve, reject) => {
+      this.#pending.push({
+        id,
+        reject,
+        resolve: (reply) => {
+          if (reply.code == null) {
+            resolve(null);
+            return;
+          }
+          // Named field by field rather than passed through, so a host reads
+          // the protocol rather than whatever `uf transform` happens to send —
+          // which means every field the protocol grows has to be added here,
+          // and one was not. `css` arrived with the StyleX compiler and this
+          // object did not mention it, so `out.css` was `undefined` in every
+          // host: the Vite plugin's `if (out.css != null)` never ran, no module
+          // ever imported its own stylesheet, and an application styled with
+          // `stylex.create` shipped class names and no CSS. The transform was
+          // right the whole time; the shim in front of it was returning three
+          // quarters of the answer. See ubugeeei-prod/uf#306.
+          resolve({
+            code: reply.code,
+            map: reply.map ?? null,
+            css: reply.css ?? null,
+            diagnostics: reply.diagnostics ?? [],
+          });
+        },
+      });
+      this.#child.stdin.write(`${JSON.stringify({ id, code, options })}\n`);
+    });
+  }
+
+  /**
+   * The build of `uf` this service's child is executing, or `null` when that
+   * could not be established.
+   *
+   * Read once, before the spawn, and never again: the child goes on executing
+   * the binary it started from however many times that file is rewritten
+   * underneath it. Anything kept from an answer of this service belongs under
+   * this identity and not under whatever the file says now.
+   *
+   * @returns {string | null}
+   */
+  get identity() {
+    return this.#identity;
+  }
+
+  /** Stop the process. Outstanding requests are rejected. */
+  close() {
+    this.#child.stdin.end();
+    this.#child.kill();
+  }
+}
+
+let shared = null;
+
+/**
+ * The process-wide service, started on first use.
+ *
+ * The loader hooks and the config loader share one process per host rather
+ * than one per module; it lives as long as the host does.
+ */
+export function sharedService(root) {
+  shared ??= new TransformService({ root: root ?? process.env.UF_PROJECT_ROOT ?? process.cwd() });
+  return shared;
+}
+
+/**
+ * Transform one Flow module through the shared service.
+ *
+ * Returns `{ code, map, css, diagnostics }`; a module that is not uf's to
+ * transform comes back as `null`.
+ */
+export function transformFlow(code, filename, options = {}) {
+  return sharedService(options.root).transform(filename, code, options);
+}

package/write-atomically.js

@@ -0,0 +1,54 @@
+// @noflow
+//
+// Plain JavaScript: this is reached from the loader hooks, which run before
+// any transform, and from the config loader, which runs before them.
+//
+// Writing a file a second process may be reading at the same time.
+//
+// `writeFileSync` truncates and then writes, so a reader can observe the empty
+// file or half of one. When what is being written is a module, the reader does
+// not get an error it can act on — it gets a module with no exports, and says
+// so about the *source*:
+//
+//     uf: uf.config.js must `export default defineConfig({ ... })`
+//
+// which is a sentence about a file that is perfectly correct. That is not
+// hypothetical: two `uf` commands in one project, which is `uf dev` in one
+// terminal and `uf build` in another, produced exactly it. See
+// ubugeeei-prod/uf#240.
+//
+// Writing to a private name and renaming is atomic within a filesystem, so a
+// reader sees the old file or the new one and never a part of either.
+
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Write `contents` to `target` so a concurrent reader never sees half of it.
+ *
+ * The temporary name carries the process id and a random suffix, because two
+ * processes racing to write the *same* target is the case this exists for and
+ * they must not collide on the temporary either.
+ *
+ * @param {string} target absolute path to write
+ * @param {string} contents what to write
+ * @param {{ tolerant?: boolean }} [options] `tolerant` swallows a failure,
+ *   which is what a cache wants — a read-only checkout still runs, just
+ *   without one. A config that cannot be written is a failure the caller has
+ *   to see.
+ */
+export function writeAtomically(target, contents, options = {}) {
+  const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  try {
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(temporary, contents);
+    renameSync(temporary, target);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Nothing to clean up.
+    }
+    if (options.tolerant !== true) throw error;
+  }
+}