@uniflowed/vite 0.0.0-alpha.7 → 0.0.0-alpha.9

package/driver.js

@@ -5,13 +5,20 @@
 // The driver `uf dev`, `uf build`, `uf build --compile`, `uf preview` and
 // `uf start` spawn.
 //
-//   <host> driver.js dev     --root <dir> [--host <h>] [--port <n>] [--strict-port]
-//   <host> driver.js build   --root <dir> [--out-dir <dir>] [--mode <m>]
-//   <host> driver.js compile --root <dir> [--out-dir <dir>] --assets <file> --bundle <dir>
-//   <host> driver.js preview --root <dir> [--out-dir <dir>] [--host <h>] [--port <n>]
+//   <host> driver.js dev     --root <dir> [--mode <m>] [--host <h>] [--port <n>] [--strict-port]
+//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>]
+//   <host> driver.js compile --root <dir> [--mode <m>] [--out-dir <dir>] --assets <file> --bundle <dir>
+//   <host> driver.js deploy  --root <dir> [--mode <m>] [--out-dir <dir>] --adapter <name> --work <dir> --output <dir>
+//   <host> driver.js preview --root <dir> [--mode <m>] [--out-dir <dir>] [--host <h>] [--port <n>]
 //   <host> driver.js start   --root <dir> [--out-dir <dir>] [--host <h>] [--port <n>]
 //   <host> driver.js config  --root <dir>
 //
+// `--mode` is what `uf` resolved from `--mode`, `.uniflowed/profile` and
+// `env.active`; it is Vite's mode, so it is `import.meta.env.MODE`. The `.env`
+// files it selected have already been read, by `uf`, into this process's
+// environment — see `viteConfig` below and `crates/uf_config/src/env_files.rs`.
+// `start` has no Vite in it and therefore no mode.
+//
 // `uf` in Rust owns the terminal; this process owns Vite. They talk over
 // stdout, one JSON event per line (see `./internal/events.js`), and the driver
 // exits when its stdin closes so it cannot outlive the command that started
@@ -29,6 +36,7 @@ import { pathToFileURL } from "node:url";
 
 import { emit, errorEvent, eventLogger, reportRenderError } from "./internal/events.js";
 import { loadUfConfig, projectConfig } from "./internal/config.js";
+import { send, toRequest } from "./internal/http.js";
 import { withProjectConfig } from "./merge.js";
 import { VIRTUAL, scanRoutes } from "./internal/routes.js";
 import {
@@ -36,8 +44,7 @@ import {
   createServeHandler,
   loadBuild,
   nodeListener,
-  send,
-  toRequest,
+  withRequest,
 } from "./internal/serve.js";
 
 function argument(name) {
@@ -71,7 +78,7 @@ process.stdin.on("end", () => process.exit(0));
 process.stdin.on("error", () => process.exit(0));
 process.stdin.resume();
 
-const commands = { dev, build, compile, preview, start, config: printConfig };
+const commands = { dev, build, compile, deploy, preview, start, config: printConfig };
 const run = commands[command];
 if (run == null) {
   emit("error", { message: `unknown driver command ${JSON.stringify(command)}` });
@@ -106,12 +113,23 @@ async function viteConfig(config, mode) {
   // merely passes on — `allowedHosts` gates binding a routable address, and
   // `manifest` is how the prerender finds its assets.
   //
-  // `envDir: false` rather than `envFile: false`: Vite 8 deprecated the second
-  // spelling and prints a line saying so on every dev server and every build,
-  // twice in the docs site's. A project turns the loader back on with
-  // `vite: { envDir: "." }`, which is the default directory — the project's own
-  // configuration is merged over this one, so it wins. See #259 for why uf
-  // switches it off at all.
+  // `envDir: false` turns off Vite's *file* loading, and only that. uf reads
+  // the `.env` cascade itself, in Rust, before this process starts — one
+  // parser, one precedence, one answer for `uf dev`, `uf build`, `uf start`,
+  // `uf test` and `uf run` — and sets what it read in this process's
+  // environment. Vite's `loadEnv` still runs with `envDir: false` and still
+  // picks every `envPrefix`-matching name out of `process.env`, so the client
+  // half is Vite's own, unchanged: the prefixed subset becomes
+  // `import.meta.env.*` in the browser bundle and nothing else does. See
+  // `crates/uf_config/src/env_files.rs`, `docs/app/guide/env` and #259.
+  //
+  // A project that would rather Vite read the files can still say
+  // `vite: { envDir: "." }` — its own configuration is merged over this one —
+  // and then both parsers run, uf's answer still standing. `loadEnv` takes the
+  // prefixed names out of the files it read and then copies every prefixed name
+  // in `process.env` over the top, and uf put its own there before this process
+  // started; so the second parser adds prefixed names uf did not set and
+  // changes none that it did.
   const generated = {
     root,
     configFile: false,
@@ -169,18 +187,29 @@ async function viteConfig(config, mode) {
  *
  *   1. load the server entry through `ssrLoadModule`, so it is transformed the
  *      same way the browser's copy is and picks up edits without a restart;
- *   2. render the URL, pointing the client script at the dev entry rather than
+ *   2. run the middleware guarding this path, which may answer instead;
+ *   3. render the URL, pointing the client script at the dev entry rather than
  *      at a built asset;
- *   3. hand the HTML to `transformIndexHtml`, which is what injects the HMR
+ *   4. hand the HTML to `transformIndexHtml`, which is what injects the HMR
  *      client and lets any Vite plugin see the document.
  *
+ * Step 4 is why `uf dev` collects the stream instead of piping it: Vite's HTML
+ * hook takes a whole document and any plugin may rewrite any part of it, so
+ * there is no first byte to send until it has run. `uf start` and `uf preview`
+ * have no such hook and stream — see `internal/serve.js` — and it is worth
+ * being clear that this is a property of the development server rather than of
+ * the renderer. Streaming through the transform is ubugeeei-prod/uf#374.
+ *
  * Anything Vite already serves — a module, a public file — never reaches this,
  * because the middleware runs after Vite's own.
  */
 async function dev() {
   const { createServer } = await import("vite");
   const config = await loadConfig();
-  const inline = await viteConfig(config, "development");
+  // The mode is uf's to decide, not this file's: `uf dev` resolves `--mode`,
+  // the profile `uf env use` wrote and `env.active` before it starts anything,
+  // and always passes the answer. The fallback is for a driver started by hand.
+  const inline = await viteConfig(config, argument("--mode") ?? "development");
   const server = await createServer({ ...inline, appType: "custom" });
 
   // In dev the browser loads the client entry from Vite, not from a manifest;
@@ -189,33 +218,77 @@ async function dev() {
 
   server.middlewares.use(async (request, response, next) => {
     const url = request.originalUrl ?? request.url ?? "/";
+    // Declared out here so the catch below can still settle: a request that
+    // failed is a request that happened, and a middleware that logged its
+    // arrival is owed its callback either way.
+    let lifecycle = null;
     try {
       const entry = await server.ssrLoadModule(VIRTUAL.server);
+      const asRequest = await toRequest(request, server.config);
 
-      // Route handlers first, and for every method: a handler is the only
-      // thing that answers a POST, and it may also answer a GET for a path
-      // that has no page.
-      const handled = await entry.dispatch(await toRequest(request, server.config));
-      if (handled != null) {
-        await send(response, handled);
-        return;
-      }
+      // The request begins here and ends when the document has been written,
+      // which is what `after()` promises and what `uf preview`, `uf start` and
+      // a compiled binary all do too — a middleware that logs a response's
+      // status has to mean the same thing in development as in production.
+      // `entry.beginRequest` rather than an import: the storage that holds the
+      // request belongs to the application's own copy of `@uniflowed/server`.
+      // See `internal/serve.js` and ubugeeei-prod/uf#389.
+      lifecycle = entry.beginRequest(asRequest);
+      const answered = await lifecycle.run(async () => {
+        // Middleware first, above everything: it guards a subtree, so it has to
+        // run for a page, for a route handler, and for a path under it that
+        // matches neither. Running it inside the dispatcher and again inside the
+        // renderer would have left `/dashboard/typo` unguarded and run it twice
+        // for a path that is both.
+        const guarded = await entry.runMiddleware(asRequest);
+        if (guarded != null) {
+          await send(response, guarded);
+          return true;
+        }
+
+        // Route handlers next, and for every method: a handler is the only
+        // thing that answers a POST, and it may also answer a GET for a path
+        // that has no page.
+        const handled = await entry.dispatch(asRequest);
+        if (handled != null) {
+          await send(response, handled);
+          return true;
+        }
+
+        // Only a navigation reaches the renderer. A page cannot answer a POST,
+        // and letting one try would turn a missing handler into a rendered page
+        // with a 200 rather than a 404.
+        if (request.method !== "GET" && request.method !== "HEAD") {
+          return false;
+        }
+
+        const result = await entry.render(url, assets, {
+          // A boundary that threw after the shell went out. `result.error` cannot
+          // carry it — the caller already has the result by then — so the
+          // terminal hears about it here or not at all.
+          onError: (error) => reportRenderError(server, url, error),
+        });
+        if (result.error != null) reportRenderError(server, url, result.error);
+        const html = await server.transformIndexHtml(url, await result.text());
+        response.statusCode = result.status ?? 200;
+        response.setHeader("content-type", "text/html; charset=utf-8");
+        response.end(html);
+        return true;
+      });
 
-      // Only a navigation reaches the renderer. A page cannot answer a POST,
-      // and letting one try would turn a missing handler into a rendered page
-      // with a 200 rather than a 404.
-      if (request.method !== "GET" && request.method !== "HEAD") {
+      if (!answered) {
+        // The one path where uf is not the one writing the response: a
+        // non-navigation nothing claimed goes back to Vite's chain. The guard
+        // has still run and may have deferred work, so `close` — the socket
+        // saying the response is over, however it ended — is the only honest
+        // signal left that the bytes are out.
+        response.once("close", lifecycle.settle);
         next();
         return;
       }
-
-      const result = await entry.render(url, assets);
-      if (result.error != null) reportRenderError(server, url, result.error);
-      const html = await server.transformIndexHtml(url, result.html);
-      response.statusCode = result.status ?? 200;
-      response.setHeader("content-type", "text/html; charset=utf-8");
-      response.end(html);
+      await lifecycle.settle();
     } catch (error) {
+      if (lifecycle != null) await lifecycle.settle();
       // Map the stack back onto the Flow source before it reaches the overlay.
       if (error instanceof Error) server.ssrFixStacktrace(error);
       next(error);
@@ -231,6 +304,7 @@ async function dev() {
       (route) => route.path,
     ),
   });
+  watchSources(server);
 
   const shutdown = async () => {
     await server.close();
@@ -240,6 +314,43 @@ async function dev() {
   process.on("SIGTERM", shutdown);
 }
 
+/**
+ * Tell the Rust side when a module under the project root changed.
+ *
+ * `uf dev` answers questions Vite does not: whether a module is a Server
+ * Component, and whether a Server Component reaches for something that only
+ * exists in a browser. Those are whole-project answers, so they go stale on
+ * any edit and there is no module to recompute them *for* — which is why this
+ * event carries no path. What it carries is "ask again".
+ *
+ * Vite's watcher is the only watcher. A second one over the same tree, in
+ * Rust, would be a second answer to "did this file change", and two watchers
+ * disagree exactly when an editor writes through a temporary file — which is
+ * every editor, and which is not a thing anybody tests.
+ *
+ * Debounced, because a `git checkout` is one intention and several hundred
+ * `change` events, and unrefed so a pending timer cannot keep this process
+ * alive after the server has closed.
+ */
+function watchSources(server) {
+  let timer = null;
+  const changed = () => {
+    if (timer != null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      emit("source-changed");
+    }, 50);
+    timer.unref?.();
+  };
+  const isSource = (file) =>
+    (file.endsWith(".js") || file.endsWith(".jsx")) && !file.includes("node_modules");
+  for (const event of ["add", "change", "unlink"]) {
+    server.watcher.on(event, (file) => {
+      if (isSource(file)) changed();
+    });
+  }
+}
+
 /**
  * The preview server: the build, as Vite serves it.
  *
@@ -263,7 +374,7 @@ async function dev() {
 async function preview() {
   const { preview: startPreview } = await import("vite");
   const config = await loadConfig();
-  const inline = await viteConfig(config, "production");
+  const inline = await viteConfig(config, argument("--mode") ?? "production");
   const build = await loadBuild({
     root,
     outDir: inline.build.outDir,
@@ -274,7 +385,16 @@ async function preview() {
   const handle = createServeHandler(build);
   server.middlewares.use(async (request, response, next) => {
     try {
-      await send(response, await handle(await toRequest(request, server.config)));
+      const asRequest = await toRequest(request, server.config);
+      // The same lifecycle `uf start` gets from `nodeListener`, spelled out
+      // because this door is Vite's connect chain rather than a bare
+      // `node:http` server: the whole request runs inside it, and it settles
+      // once `send` has returned. A preview whose `after()` fired at a
+      // different moment from the production server's would be a preview that
+      // is checked and believed and wrong.
+      await withRequest(build.entry, asRequest, async () => {
+        await send(response, await handle(asRequest));
+      });
     } catch (error) {
       next(error);
     }
@@ -327,7 +447,7 @@ async function start() {
 
   const host = argument("--host") ?? process.env.HOST ?? "0.0.0.0";
   const port = Number(argument("--port") ?? process.env.PORT ?? 3000);
-  const server = createHttpServer(nodeListener(createServeHandler(build)));
+  const server = createHttpServer(nodeListener(createServeHandler(build), build.entry));
 
   await new Promise((resolve, reject) => {
     server.once("error", reject);
@@ -410,6 +530,12 @@ async function build() {
   // `createRenderer` renders the error boundary and reports the exception on
   // the result — so both are checked here. Neither writes a file: an error
   // page written into `dist/` is a build that shipped its own failure.
+  //
+  // `prerender`, not `render`: a build wants the document React produces once
+  // every boundary has resolved, with the content where the fallback was. The
+  // streaming renderer would write a file whose slow parts are `<template>`
+  // elements waiting for a script — correct in a browser, blank to a crawler
+  // and to `curl`, which is most of what a static file is for.
   const failures = [];
   const failed = (url, error) => {
     failures.push(url);
@@ -418,7 +544,7 @@ async function build() {
   for (const url of pages) {
     let result;
     try {
-      result = await server.render(url, assets);
+      result = await server.prerender(url, assets);
     } catch (error) {
       failed(url, error);
       continue;
@@ -447,16 +573,40 @@ async function build() {
   // `_uf.not-found.js` is in `app/guide/` would otherwise get a `404.html`
   // rendered from the framework's bare default, which is worse than the file
   // it used to write, which was none.
+  //
+  // Through the same two checks as the loop, and for the same reason. A
+  // not-found boundary is a component like any other: it can throw, and when it
+  // does `prerender` answers with the *error* page's HTML and a non-null
+  // `error` rather than rejecting. Writing that HTML and emitting `page` was a
+  // build publishing its own failure as `404.html` and exiting 0 — the static
+  // host would then serve uf's error page to every visitor who mistyped a URL,
+  // and nothing between the throw and the deploy would have mentioned it.
+  let attempted = pages.length;
   if (server.notFound.some((boundary) => boundary.path === "/")) {
-    const result = await server.render("/__uf_not_found__", assets);
-    const file = path.join(outDir, "404.html");
-    writeFileSync(file, result.html);
-    emit("page", {
-      url: "/404",
-      file: path.relative(root, file),
-      status: 404,
-      bytes: Buffer.byteLength(result.html),
-    });
+    attempted += 1;
+    // `/404` rather than `/__uf_not_found__`: the internal path is how the
+    // router is asked, and the file the reader is looking for is `404.html`.
+    let result;
+    try {
+      result = await server.prerender("/__uf_not_found__", assets);
+    } catch (error) {
+      failed("/404", error);
+      result = null;
+    }
+    if (result != null && result.error != null) {
+      failed("/404", result.error);
+      result = null;
+    }
+    if (result != null) {
+      const file = path.join(outDir, "404.html");
+      writeFileSync(file, result.html);
+      emit("page", {
+        url: "/404",
+        file: path.relative(root, file),
+        status: 404,
+        bytes: Buffer.byteLength(result.html),
+      });
+    }
   }
 
   if (failures.length > 0) {
@@ -467,9 +617,12 @@ async function build() {
     // as the headline and the one a CI log's last line will be. It read
     // `... failed:` with the routes below it, and the headline was then a
     // sentence ending in a colon and nothing.
+    // `attempted`, not `pages.length`: the root 404 is prerendered too, and
+    // counting a failure of it against a total that excludes it produced
+    // "1 of 12" for a build that rendered thirteen things.
     emit("error", {
-      message: `${failures.length} of ${pages.length} prerendered ${plural(
-        pages.length,
+      message: `${failures.length} of ${attempted} prerendered ${plural(
+        attempted,
         "route",
       )} failed\n${failures.map((url) => `  ${url}`).join("\n")}`,
     });
@@ -574,6 +727,322 @@ async function compile() {
   process.exit(0);
 }
 
+/**
+ * What each adapter links, and what it links it against.
+ *
+ * Every entry in this table produces the same `handler.js` — the application
+ * as `Request` → `Response`, from `@uniflowed/server/fetch` — and differs only
+ * in the file wrapped around it and, for a target whose dependencies have a
+ * different build, in the export conditions that pick one. That is the whole
+ * of what an adapter is, and keeping the differences in one object is what
+ * stops a second one from quietly becoming a second application.
+ *
+ * `bun`, `deno` and `static` are deliberately absent; `uf_config`'s
+ * `DeployAdapter::is_implemented` is the other half of that fact and
+ * `docs/app/reference/cli/_uf.page.mdx` says why for each of them.
+ */
+const ADAPTERS = {
+  node: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      server: nodeEntrySource("./handler.js"),
+    }),
+  },
+  // The same two files. What `--adapter container` adds is a `Dockerfile` and
+  // a `.dockerignore`, and both are plain text that `uf` writes beside this
+  // output rather than anything the bundler produces — see `uf_cli`'s
+  // `commands::deploy`.
+  container: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      server: nodeEntrySource("./handler.js"),
+    }),
+  },
+  edge: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      worker: workerEntrySource("./handler.js"),
+    }),
+    // `workerd` first, so React resolves to the build that has
+    // `renderToReadableStream` and no `node:stream`. `browser` and `module`
+    // after it are Vite's own SSR defaults, kept so a dependency with no
+    // worker condition still resolves the way it does for every other target.
+    conditions: ["workerd", "worker", "edge-light", "browser", "module", "import", "default"],
+  },
+  serverless: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      lambda: lambdaEntrySource("./handler.js"),
+    }),
+  },
+};
+
+/**
+ * Link the application into a directory that can be copied, for
+ * `uf build --adapter`.
+ *
+ * `uf start` serves a build and `uf build --compile` puts one inside an
+ * executable, and between them is the shape most hosts actually want: a
+ * directory that carries everything and nothing that is still in the checkout
+ * — no `node_modules`, no source, no `uf`. That is what this writes, for
+ * whichever of [`ADAPTERS`] was asked for.
+ *
+ * It differs from the server build in [`build`] in one way, and that one way
+ * is the whole of the difference between a build artefact and a checkout:
+ * `ssr.noExternal: true`. The ordinary server build leaves `react`,
+ * `react-dom` and every other dependency as bare imports, because the host it
+ * runs on has `node_modules` beside it; a copied directory does not, so they
+ * come in. (`@uniflowed/*` was never external — `index.js` sets
+ * `ssr.noExternal: [/^@uniflowed\//]` because Node cannot import Flow — which
+ * is why serving a build has never needed `uf transform` alive, and why the
+ * blocker ubugeeei-prod/uf#335 records was not one.)
+ *
+ * # Two entries, because an adapter is exactly one of them
+ *
+ * `handler.js` is the application as a Web-standard `fetch` export: a
+ * `Request` in, a `Response` out, no filesystem, no socket, no `node:` import
+ * that a worker does not already have. That is the seam, and it is the same
+ * file for every target in [`ADAPTERS`].
+ *
+ * The second entry is the wrapper for *this* target — `node:http` for `node`
+ * and `container`, `export default { fetch }` for a Worker, `export const
+ * handler` for a Lambda — and each of them is a handful of lines around an
+ * import from `@uniflowed/server`. That is the point: the work is in the
+ * handler, and what a new adapter has to write is the handful of lines, not
+ * the application.
+ *
+ * Both are ordinary entries of one Rolldown build, so the wrapper imports the
+ * emitted `handler.js` rather than a second copy of the application.
+ *
+ * The `static/` directory is *not* written here. `uf` copies it (see
+ * `uf_cli`'s `commands::deploy`), because walking an output directory and
+ * copying every file in it is bulk work over the whole build, which belongs in
+ * Rust rather than in the host process — the same division `--compile` makes
+ * with its embedded assets.
+ */
+async function deploy() {
+  const vite = await import("vite");
+  const config = await loadConfig();
+  const inline = await viteConfig(config, argument("--mode") ?? "production");
+  const outDir = path.resolve(root, inline.build.outDir);
+  const adapter = argument("--adapter");
+  const workArgument = argument("--work");
+  const outputArgument = argument("--output");
+  if (adapter == null || workArgument == null || outputArgument == null) {
+    throw new Error("uf: `driver.js deploy` needs --adapter, --work and --output");
+  }
+  // The Rust side has already refused every adapter it has no implementation
+  // for, by name and with the issue that tracks it. This is the second half of
+  // that fact rather than a duplicate of it: the driver may be spawned by a
+  // future `uf` that knows an adapter this copy does not, and answering "one
+  // moment, here is a directory" for a target nobody wrote would be the silent
+  // wrong answer the whole issue is about.
+  const shape = ADAPTERS[adapter];
+  if (shape == null) {
+    throw new Error(
+      `uf: this driver implements ${Object.keys(ADAPTERS)
+        .map((name) => JSON.stringify(name))
+        .join(", ")} and was asked for ${JSON.stringify(adapter)}`,
+    );
+  }
+  const work = path.resolve(root, workArgument);
+  const output = path.resolve(root, outputArgument);
+
+  emit("phase", { name: adapter });
+
+  // Written to disk rather than served as virtual modules: they are generated
+  // per build — `handler.js` names this build's hashed assets — and a real
+  // file is the version a person can open when a deployed directory
+  // misbehaves.
+  mkdirSync(work, { recursive: true });
+  const document = assetsFromManifest(readManifest(outDir));
+  const entries = shape.entries(document);
+  const input = {};
+  for (const name of Object.keys(entries)) {
+    writeFileSync(path.join(work, `${name}.js`), entries[name]);
+    input[name] = path.join(work, `${name}.js`);
+  }
+
+  const ssr = { ...(inline.ssr ?? {}), noExternal: true };
+  if (shape.conditions != null) {
+    // Which build of a dependency this target gets, and it is the difference
+    // between a worker that renders and one that fails to link. React ships
+    // `server.node.js` under the `node` condition and `server.edge.js` under
+    // `workerd`; the first one imports `node:stream`, and the router picks its
+    // renderer by asking whether `renderToPipeableStream` is there — so the
+    // condition list is what decides that, not a flag in the application.
+    ssr.resolve = { ...(inline.ssr?.resolve ?? {}), conditions: shape.conditions };
+  }
+
+  await vite.build({
+    ...inline,
+    customLogger: eventLogger("warn"),
+    plugins: [...inline.plugins, nativeAddonGuard()],
+    ssr,
+    build: {
+      ...inline.build,
+      manifest: false,
+      // The map would describe this bundle rather than the source, and nothing
+      // downstream reads it. Off is a smaller directory to copy and one less
+      // file to explain.
+      sourcemap: false,
+      ssr: true,
+      outDir: output,
+      // `uf` has already removed the directory, and `static/` is copied in
+      // after this returns; letting Vite empty it would be Vite deciding when
+      // that happens.
+      emptyOutDir: false,
+      rollupOptions: {
+        input,
+        output: {
+          entryFileNames: "[name].js",
+          // Route modules are lazy `import()`s, so the server bundle splits
+          // whether or not anything asks it to, and the chunks have to land
+          // somewhere. `chunks/` rather than the default `assets/`, because
+          // `static/assets/` beside it is the *client's* — two directories
+          // with one name in a directory whose whole purpose is to be copied
+          // and read by a stranger.
+          chunkFileNames: "chunks/[name]-[hash].js",
+          format: "es",
+        },
+      },
+    },
+  });
+
+  emit("done", { outDir: path.relative(root, output), pages: 0 });
+  process.exit(0);
+}
+
+/**
+ * The source of `handler.js`: the application, as one `fetch` export.
+ *
+ * `export default { fetch }` as well as the named export, because those are
+ * the two spellings the hosts this shape exists for actually read — a worker
+ * and Deno Deploy want the default export's `fetch`, and a Node or Bun entry
+ * wants the name. Writing both costs a line and removes the one thing that
+ * would make an otherwise portable file not portable.
+ *
+ * `beginRequest` is exported beside it, and it is not decoration. `fetch`
+ * answers with a `Response`; it does not know when that response reached
+ * anybody, and `after()` promises a callback once it has. So the host owns the
+ * request: begin it, run `fetch` inside `run`, and `settle` when the bytes are
+ * out — `server.js` below does exactly that through
+ * `@uniflowed/server/node`, and a worker hands `settle` to `ctx.waitUntil`.
+ * It comes from the bundle rather than from the host's own
+ * `@uniflowed/server`, because the request lives in an `AsyncLocalStorage`
+ * belonging to a module instance and the instance the application reads is the
+ * one inlined here. See ubugeeei-prod/uf#389.
+ *
+ * The document's script and stylesheet URLs are baked in here because they
+ * come from the client manifest, which exists at this moment and not in the
+ * directory that gets copied.
+ */
+function handlerEntrySource(document) {
+  return `// Generated by \`uf build --adapter\`. Not checked in, not edited.
+import { createFetchHandler } from "@uniflowed/server/fetch";
+import * as app from ${JSON.stringify(VIRTUAL.server)};
+
+export const fetch = createFetchHandler({ app, document: ${JSON.stringify(document)} });
+export const beginRequest = app.beginRequest;
+
+export default { fetch, beginRequest };
+`;
+}
+
+/**
+ * The source of `server.js`: the Node socket around that handler.
+ *
+ * Everything host-specific about serving a build is in
+ * `@uniflowed/server/node`, which is the same module `uf start` reaches
+ * through `./internal/serve.js` — so a request answered here and the same
+ * request answered by `uf start` go through one implementation, not two that
+ * agree today.
+ */
+function nodeEntrySource(handlerSpecifier) {
+  return `// Generated by \`uf build --adapter node\`. Not checked in, not edited.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { serve } from "@uniflowed/server/node";
+
+// \`beginRequest\` comes from the handler beside this file rather than from
+// \`@uniflowed/server/node\` above, because the request has to be established in
+// the storage the *application* reads, which is the copy bundled into
+// \`handler.js\`. See ubugeeei-prod/uf#389.
+import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
+
+// Resolved from this file and not from the working directory: a process
+// manager, a container entrypoint and a person in a shell each start a server
+// from wherever they happen to be, and a directory that only served its own
+// assets when it was started from inside itself would be a deployment with a
+// trap in it.
+const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
+
+// Not \`await serve(...)\` at the top level. uf parses that now
+// (ubugeeei-prod/uf#204) and this entry is a module, so it would work; \`.catch\`
+// is the better spelling regardless — a server that cannot take its port should
+// say so and exit non-zero, rather than die as an unhandled rejection.
+serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
+  process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
+  process.exit(1);
+});
+`;
+}
+
+/**
+ * The source of `worker.js`: the Cloudflare Workers entry around that handler.
+ *
+ * `export default { fetch }`, which is the modules-format Worker Cloudflare
+ * runs, and everything host-specific is in `@uniflowed/server/edge` — the
+ * asset lookup through the `ASSETS` binding `wrangler.json` declares, and the
+ * `ctx.waitUntil` that keeps the isolate alive for `after()`.
+ *
+ * `beginRequest` comes from the handler beside this file for the reason
+ * `nodeEntrySource` gives: the request has to be established in the storage the
+ * *application* reads. See ubugeeei-prod/uf#389.
+ */
+function workerEntrySource(handlerSpecifier) {
+  return `// Generated by \`uf build --adapter edge\`. Not checked in, not edited.
+import { createWorkerFetch } from "@uniflowed/server/edge";
+
+import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+
+export default { fetch: createWorkerFetch({ handle, beginRequest }) };
+`;
+}
+
+/**
+ * The source of `lambda.js`: the AWS Lambda entry around that handler.
+ *
+ * `export const handler`, so the function's configured handler is
+ * `lambda.handler`. Everything platform-specific — the payload format 2.0
+ * event, the base64 rules, the `cookies` array — is in
+ * `@uniflowed/server/lambda`.
+ *
+ * `staticDir` points at the `static/` copied beside this file, so an uploaded
+ * package answers a prerendered document without any other infrastructure
+ * existing. That is a starting point rather than a destination, and the module
+ * it is passed to says so at length.
+ */
+function lambdaEntrySource(handlerSpecifier) {
+  return `// Generated by \`uf build --adapter serverless\`. Not checked in, not edited.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createLambdaHandler } from "@uniflowed/server/lambda";
+
+import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+
+// Resolved from this file and not from the working directory: Lambda sets the
+// working directory to the task root today and is under no obligation to keep
+// doing so, and a deployment that only found its own assets by accident is a
+// deployment with a trap in it.
+const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
+
+export const handler = createLambdaHandler({ handle, beginRequest, staticDir });
+`;
+}
+
 /**
  * The source of the module a runtime gets wrapped around.
  *
@@ -583,11 +1052,11 @@ async function compile() {
  * and not inside the binary.
  */
 function entrySource(assetsSpecifier, document) {
-  // Not `await serve(...)` at the top level. Node runs top-level `await`
-  // happily and the Flow parser uf vendors does not parse it (ubugeeei-prod/uf#204),
-  // so the generated entry would fail its own transform. `.catch` is the better
-  // spelling anyway: a binary that cannot take its port should say which port
-  // and exit non-zero, rather than die as an unhandled rejection.
+  // Not `await serve(...)` at the top level. uf parses that now
+  // (ubugeeei-prod/uf#204) and this entry is a module, so it would work;
+  // `.catch` is the better spelling regardless: a binary that cannot take its
+  // port should say which port and exit non-zero, rather than die as an
+  // unhandled rejection.
   return `// Generated by \`uf build --compile\`. Not checked in, not edited.
 import { serve } from "@uniflowed/server/standalone";
 import { assets } from ${JSON.stringify(assetsSpecifier)};