@uniflowed/vite 0.0.0-alpha.6 → 0.0.0-alpha.8

package/driver.js

@@ -2,11 +2,15 @@
 //
 // Plain JavaScript: the host runs this file directly.
 //
-// The driver `uf dev`, `uf build` and `uf preview` spawn.
+// 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 preview --root <dir> [--host <h>] [--port <n>]
+//   <host> driver.js compile --root <dir> [--out-dir <dir>] --assets <file> --bundle <dir>
+//   <host> driver.js deploy  --root <dir> [--out-dir <dir>] --adapter <name> --work <dir> --output <dir>
+//   <host> driver.js preview --root <dir> [--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>
 //
 // `uf` in Rust owns the terminal; this process owns Vite. They talk over
@@ -18,15 +22,24 @@
 // Rust side reads a config that may hold functions and plugin instances: the
 // one host that can evaluate the file evaluates it.
 
+import { createServer as createHttpServer } from "node:http";
 import { register } from "node:module";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { emit, errorEvent, eventLogger } from "./internal/events.js";
+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 {
+  assetsFromManifest,
+  createServeHandler,
+  loadBuild,
+  nodeListener,
+  withRequest,
+} from "./internal/serve.js";
 
 function argument(name) {
   const at = process.argv.indexOf(name);
@@ -59,7 +72,7 @@ process.stdin.on("end", () => process.exit(0));
 process.stdin.on("error", () => process.exit(0));
 process.stdin.resume();
 
-const commands = { dev, build, preview, 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)}` });
@@ -93,10 +106,17 @@ async function viteConfig(config, mode) {
   // plugins make Flow compile, and the few settings uf enforces rather than
   // 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.
   const generated = {
     root,
     configFile: false,
-    envFile: false,
+    envDir: false,
     mode,
     clearScreen: false,
     customLogger: eventLogger(argument("--log-level") ?? "info"),
@@ -111,7 +131,17 @@ async function viteConfig(config, mode) {
         deny: dev.fs?.deny,
       },
     },
-    preview: { host, port },
+    // Not `server`, and not `dev.port` either. Vite's own default for a
+    // preview is 4173 rather than 5173, and the reason is the case this
+    // command exists for: somebody comparing a build against the dev server
+    // they left running. Taking `dev.port` would have made the two collide,
+    // and Vite would have moved the preview to the next free port and served
+    // it somewhere nobody was looking.
+    preview: {
+      host: argument("--host") ?? "127.0.0.1",
+      port: Number(argument("--port") ?? 4173),
+      strictPort: flag("--strict-port"),
+    },
     build: {
       outDir: argument("--out-dir") ?? build.outDir ?? "dist",
       sourcemap: build.sourcemap ?? true,
@@ -140,11 +170,19 @@ 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.
  */
@@ -160,32 +198,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;
+        }
 
-      // 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") {
+        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;
+      });
+
+      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);
-      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);
@@ -201,6 +284,7 @@ async function dev() {
       (route) => route.path,
     ),
   });
+  watchSources(server);
 
   const shutdown = async () => {
     await server.close();
@@ -211,67 +295,99 @@ async function dev() {
 }
 
 /**
- * A Node request as a `Request`.
+ * 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".
  *
- * The handler contract is the platform's, so the adapter belongs here rather
- * than in every handler. The body is read as a stream where the host supports
- * it, because a handler that accepts an upload should not need the whole thing
- * buffered before it starts.
+ * 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.
  */
-async function toRequest(incoming, config) {
-  const host = incoming.headers.host ?? "localhost";
-  const protocol = config?.server?.https == null ? "http" : "https";
-  const url = new URL(incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
-
-  const headers = new Headers();
-  for (const [name, value] of Object.entries(incoming.headers)) {
-    if (value == null) continue;
-    for (const entry of Array.isArray(value) ? value : [value]) {
-      headers.append(name, entry);
-    }
-  }
-
-  const method = (incoming.method ?? "GET").toUpperCase();
-  const init = { method, headers };
-  if (method !== "GET" && method !== "HEAD") {
-    // `duplex` is required by the specification whenever a body is a stream,
-    // and Node throws without it.
-    init.body = incoming;
-    init.duplex = "half";
-  }
-  return new Request(url, init);
-}
-
-/** Write a `Response` to a Node response. */
-async function send(outgoing, result) {
-  outgoing.statusCode = result.status;
-  if (result.statusText !== "") {
-    outgoing.statusMessage = result.statusText;
-  }
-  for (const [name, value] of result.headers) {
-    outgoing.setHeader(name, value);
-  }
-  if (result.body == null) {
-    outgoing.end();
-    return;
-  }
-  // Streamed rather than buffered, so a handler returning a large or
-  // open-ended body is not read into memory first.
-  const reader = result.body.getReader();
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    outgoing.write(value);
+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();
+    });
   }
-  outgoing.end();
 }
 
+/**
+ * The preview server: the build, as Vite serves it.
+ *
+ * Vite's `preview()` is a static file server, and a uf build is not only
+ * static files — a route handler answers a `POST` and a route with parameters
+ * and no `generateStaticParams` was never prerendered. On its own it would
+ * therefore 404 every request the interesting half of an application exists to
+ * answer, which is worse than having no preview at all, because a preview is
+ * checked and believed.
+ *
+ * So the application handler is mounted behind it, and `appType: "custom"` is
+ * what makes that reachable: with Vite's default `spa` it inserts an
+ * index.html fallback and a 404 middleware of its own, so every unmatched path
+ * would have been answered with the home page — a 200 for a path that does not
+ * exist — before anything of uf's ran.
+ *
+ * The static middleware still runs first, and that is deliberate rather than
+ * incidental; see `internal/serve.js` for why `uf start` orders itself the
+ * same way.
+ */
 async function preview() {
   const { preview: startPreview } = await import("vite");
   const config = await loadConfig();
-  const server = await startPreview(await viteConfig(config, "production"));
+  const inline = await viteConfig(config, "production");
+  const build = await loadBuild({
+    root,
+    outDir: inline.build.outDir,
+    serverDir: path.join(".uf", "build", "server"),
+  });
+
+  const server = await startPreview({ ...inline, appType: "custom" });
+  const handle = createServeHandler(build);
+  server.middlewares.use(async (request, response, next) => {
+    try {
+      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);
+    }
+  });
+
   const urls = server.resolvedUrls ?? { local: [], network: [] };
-  emit("listening", { local: urls.local, network: urls.network, routes: [] });
+  emit("listening", {
+    local: urls.local,
+    network: urls.network,
+    routes: build.entry.routes.map((route) => route.path),
+    handlers: build.entry.handlers.map((handler) => handler.path),
+  });
+
   const shutdown = async () => {
     await server.close();
     process.exit(0);
@@ -280,6 +396,65 @@ async function preview() {
   process.on("SIGTERM", shutdown);
 }
 
+/**
+ * The production server: the build, with no bundler in the process.
+ *
+ * `preview` proves the build works through Vite. This is the thing that is
+ * actually deployed, and it imports `vite` nowhere — a host running a built
+ * application should not need the bundler that produced it, and the moment it
+ * does, "portable output" is a claim rather than a property.
+ *
+ * There is no `--strict-port` here and there is nothing to add: this server
+ * binds the port it was given or fails, where Vite's would have quietly moved
+ * to the next free one. `PORT` and `HOST` are read from the environment
+ * because that is how every process manager and container platform says which
+ * socket to take, and a production server that could only be told on the
+ * command line would need a wrapper script everywhere it ran.
+ *
+ * It is not the only thing that can be deployed. `uf build --compile` puts
+ * this same application behind this same resolution order inside a single
+ * executable, for a host that should not have to have a JavaScript runtime
+ * installed at all; see [`compile`] for what that costs and what it shares.
+ */
+async function start() {
+  const config = await loadConfig();
+  const outDir = argument("--out-dir") ?? config.build?.outDir ?? "dist";
+  const build = await loadBuild({
+    root,
+    outDir,
+    serverDir: path.join(".uf", "build", "server"),
+  });
+
+  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), build.entry));
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+
+  const bound = server.address();
+  // `0.0.0.0` is not a URL anybody can open, so the loopback spelling is what
+  // is printed as `local` and the bound address is reported as the network
+  // one — the same split `uf dev` prints, and for the same reason: one of the
+  // two is a link and the other is a fact about the socket.
+  const shown = `${bound.address}:${bound.port}`;
+  const wildcard = bound.address === "0.0.0.0" || bound.address === "::";
+  emit("listening", {
+    local: [`http://${wildcard ? `localhost:${bound.port}` : shown}/`],
+    network: wildcard ? [`http://${shown}/`] : [],
+    routes: build.entry.routes.map((route) => route.path),
+    handlers: build.entry.handlers.map((handler) => handler.path),
+  });
+
+  const shutdown = () => {
+    server.close(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
 async function build() {
   const vite = await import("vite");
   const config = await loadConfig();
@@ -324,8 +499,40 @@ async function build() {
   const server = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
   const assets = assetsFromManifest(manifest);
   const pages = await staticPaths(server.routes);
+
+  // A route that throws fails *that route*, and the rest of the build still
+  // happens. This loop had no `try`: the first page to throw rejected out of
+  // `build()`, `run().catch` reported the exception, and which URL was being
+  // rendered was a local variable nobody could see. One broken page was the
+  // whole build, and the message named a stack rather than a route.
+  //
+  // The render itself no longer throws for an ordinary component failure —
+  // `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);
+    emit("page-failed", { url, ...errorEvent(error) });
+  };
   for (const url of pages) {
-    const result = await server.render(url, assets);
+    let result;
+    try {
+      result = await server.prerender(url, assets);
+    } catch (error) {
+      failed(url, error);
+      continue;
+    }
+    if (result.error != null) {
+      failed(url, result.error);
+      continue;
+    }
     const file = htmlPathFor(outDir, url);
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, result.html);
@@ -336,92 +543,447 @@ async function build() {
       bytes: Buffer.byteLength(result.html),
     });
   }
-  if (server.notFound != null) {
-    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),
+  // One `404.html`, from the boundary at the router root: a static host serves
+  // a single error document for the whole site, so the nested boundaries a
+  // project declares are the server's and the client's to render, not
+  // something this loop can write a file for.
+  //
+  // The condition is "there is a root boundary", not "there is any boundary",
+  // because `/__uf_not_found__` is a path at the root: a project whose only
+  // `_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 === "/")) {
+    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) {
+    // Emitted rather than thrown, so the message is the routes and not the
+    // last exception: each one has already been reported with its own frame.
+    //
+    // The first line stands on its own, because it is the one `uf build` uses
+    // 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 ${attempted} prerendered ${plural(
+        attempted,
+        "route",
+      )} failed\n${failures.map((url) => `  ${url}`).join("\n")}`,
     });
+    process.exit(1);
   }
 
   emit("done", { outDir: path.relative(root, outDir), pages: pages.length });
   process.exit(0);
 }
 
-async function printConfig() {
+/**
+ * Link the whole application into one JavaScript file, for `uf build --compile`.
+ *
+ * This runs after `build`, on a `dist/` that is already complete, and produces
+ * the module a runtime is wrapped around. It differs from the server build in
+ * `build()` in exactly three ways, and each of them is what "one file" means:
+ *
+ *   * `ssr.noExternal: true` — the 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 binary does not, so they come in.
+ *   * `codeSplitting: false` — a route is a lazy `import()` so that the browser
+ *     can fetch one chunk per page. On the server that split buys nothing and
+ *     costs everything: chunks are separate files, and separate files are the
+ *     one thing this output may not have.
+ *   * the native-addon guard below, which turns "cannot resolve" into a
+ *     sentence naming the package that cannot be compiled.
+ *
+ * The embedded copy of `dist/` is *not* built here. `uf` writes it (see
+ * `uf_bundle::embed`) and passes its path in `--assets`, because walking an
+ * output directory and encoding every file in it is bulk work over the whole
+ * build, which belongs in Rust rather than in the host process.
+ *
+ * # Three front doors onto one build, and why they are not one function
+ *
+ * `preview` and `start` above serve `dist/` from disk, and they share a single
+ * handler in `./internal/serve.js` for the express purpose of being unable to
+ * answer differently. What is linked here is a third front door onto the same
+ * build, and it deliberately does *not* import that module. Two reasons, and
+ * either would be enough: `internal/serve.js` answers by opening files under
+ * `dist/`, and a compiled binary has no `dist/` to open — it carries the bytes
+ * — so the half that reads a request would arrive with a half that cannot run;
+ * and it lives in `@uniflowed/vite`, so linking it would put the package named
+ * after the bundler inside the artefact a deployment runs, which is the one
+ * thing `start` exists to avoid.
+ *
+ * What a binary uses instead is `@uniflowed/server/standalone`, and the thing
+ * that is shared between the three is not code but the *answer*: an asset or a
+ * prerendered document first, then a route handler, then a render for whatever
+ * is left. That order is not a preference. `preview` cannot deviate from it —
+ * Vite's preview server runs its own file middleware before anything uf mounts
+ * behind it — so `start` matches Vite, and the binary matches `start`. A
+ * compiled application that resolved a collision the other way would be the
+ * trap `preview` exists to prevent, one deployment further along, and the only
+ * copy nobody can check with `uf preview` first.
+ */
+async function compile() {
+  const vite = await import("vite");
   const config = await loadConfig();
-  emit("config", { config: projectConfig(config) });
+  const inline = await viteConfig(config, argument("--mode") ?? "production");
+  const outDir = path.resolve(root, inline.build.outDir);
+  const assetsArgument = argument("--assets");
+  const bundleArgument = argument("--bundle");
+  if (assetsArgument == null || bundleArgument == null) {
+    throw new Error("uf: `driver.js compile` needs both --assets and --bundle");
+  }
+  const assets = path.resolve(root, assetsArgument);
+  const bundleDir = path.resolve(root, bundleArgument);
+
+  emit("phase", { name: "standalone" });
+
+  // The entry is written to disk rather than served as another virtual module:
+  // it is generated per build (it names this build's asset file), and a real
+  // file is the version a person can open when a compiled binary misbehaves.
+  const entry = path.join(bundleDir, "entry.js");
+  mkdirSync(bundleDir, { recursive: true });
+  const specifier = `./${path.relative(bundleDir, assets)}`;
+  writeFileSync(entry, entrySource(specifier, assetsFromManifest(readManifest(outDir))));
+
+  await vite.build({
+    ...inline,
+    customLogger: eventLogger("warn"),
+    plugins: [...inline.plugins, nativeAddonGuard()],
+    ssr: { ...(inline.ssr ?? {}), noExternal: true },
+    build: {
+      ...inline.build,
+      manifest: false,
+      // The map would describe this intermediate bundle rather than the
+      // binary, and nothing downstream reads it. Turning it off is a smaller
+      // `.uf/` and one less file to explain.
+      sourcemap: false,
+      ssr: true,
+      outDir: bundleDir,
+      emptyOutDir: false,
+      rollupOptions: {
+        input: { server: entry },
+        output: { entryFileNames: "server.js", format: "es", codeSplitting: false },
+      },
+    },
+  });
+
+  emit("done", { outDir: path.relative(root, bundleDir), pages: 0 });
   process.exit(0);
 }
 
-function readManifest(outDir) {
-  const file = path.join(outDir, ".vite", "manifest.json");
-  if (!existsSync(file)) throw new Error(`uf: the client build wrote no manifest at ${file}`);
-  return JSON.parse(readFileSync(file, "utf8"));
+/**
+ * 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 you copy onto a machine that has a JavaScript runtime and nothing
+ * else — no `node_modules`, no checkout, no `uf`. That is what this writes.
+ *
+ * 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 — every other target
+ * in `app.runtime.deploy.adapters` is this file with a different thing wrapped
+ * around it.
+ *
+ * `server.js` is the wrapper for *this* target: `node:http`, with the build's
+ * files served from `static/` beside it. It is thirty lines, and that is the
+ * point — the work is in the handler, and what a second adapter has to write
+ * is the thirty lines, not the application.
+ *
+ * Both are ordinary entries of one Rolldown build, so `server.js` 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.
+  if (adapter !== "node") {
+    throw new Error(
+      `uf: this driver implements the \`node\` adapter 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));
+  writeFileSync(path.join(work, "handler.js"), handlerEntrySource(document));
+  writeFileSync(path.join(work, "server.js"), nodeEntrySource("./handler.js"));
+
+  await vite.build({
+    ...inline,
+    customLogger: eventLogger("warn"),
+    plugins: [...inline.plugins, nativeAddonGuard()],
+    ssr: { ...(inline.ssr ?? {}), noExternal: true },
+    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: {
+          handler: path.join(work, "handler.js"),
+          server: path.join(work, "server.js"),
+        },
+        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);
 }
 
 /**
- * Script, stylesheet and preload URLs for the client entry chunk.
+ * 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 entry is found by its `isEntry` flag rather than by key, because a
- * virtual module's manifest key is an implementation detail of the bundler.
+ * 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 tags a prerendered document needs.
- *
- * Two walks over the manifest, because the two answers are different. A
- * `modulepreload` is worth emitting only for a chunk this document will
- * certainly load, which is the entry's *static* imports. A stylesheet has to
- * be emitted for anything the page might render, and the router loads every
- * route module dynamically — so a stylesheet imported by a layout is reached
- * through `dynamicImports` and through nothing else. Following only the static
- * graph, as this did, meant a layout could import a stylesheet and the built
- * HTML would silently ship without it.
- *
- * The cost is that a project with per-route stylesheets links all of them on
- * every page. Narrowing that needs the route table to say which chunk each
- * route came from, which the manifest alone cannot tell us.
+ * 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 assetsFromManifest(manifest) {
-  const entry = Object.values(manifest).find((chunk) => chunk.isEntry);
-  if (entry == null) throw new Error("uf: the client manifest has no entry chunk");
-
-  const styles = new Set(entry.css ?? []);
-  const seen = new Set();
-  const collectStyles = (chunk) => {
-    for (const imported of [...(chunk.imports ?? []), ...(chunk.dynamicImports ?? [])]) {
-      if (seen.has(imported)) continue;
-      seen.add(imported);
-      const dependency = manifest[imported];
-      if (dependency == null) continue;
-      for (const css of dependency.css ?? []) styles.add(css);
-      collectStyles(dependency);
-    }
-  };
-  collectStyles(entry);
-
-  const preloads = new Set();
-  const collectPreloads = (chunk) => {
-    for (const imported of chunk.imports ?? []) {
-      const dependency = manifest[imported];
-      if (dependency == null || preloads.has(dependency.file)) continue;
-      preloads.add(dependency.file);
-      collectPreloads(dependency);
-    }
-  };
-  collectPreloads(entry);
+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: Node runs top-level \`await\` happily
+// and the Flow parser uf vendors does not (ubugeeei-prod/uf#204), so the generated
+// entry would fail its own transform. \`.catch\` is the better spelling anyway —
+// 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 the module a runtime gets wrapped around.
+ *
+ * Three imports and one call: the shim that serves, the application, and the
+ * bytes of `dist/`. 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 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.
+  return `// Generated by \`uf build --compile\`. Not checked in, not edited.
+import { serve } from "@uniflowed/server/standalone";
+import { assets } from ${JSON.stringify(assetsSpecifier)};
+import * as app from ${JSON.stringify(VIRTUAL.server)};
 
+serve({ app, assets, document: ${JSON.stringify(document)} }).catch((error) => {
+  process.stderr.write(\`uf: \${error?.message ?? String(error)}\n\`);
+  process.exit(1);
+});
+`;
+}
+
+/**
+ * Refuse a native addon by name instead of by stack trace.
+ *
+ * A `.node` file is a compiled shared object for one platform: it cannot be
+ * inlined into a JavaScript bundle, and a binary that carried one would stop
+ * being a single file. Without this, `ssr.noExternal: true` hands the addon to
+ * Rolldown and the build fails somewhere inside the bundler with a message
+ * about an unexpected character — which is true, and useless. Failing here
+ * with the addon's path and the importer that reached it is the difference
+ * between a feature and a trap.
+ *
+ * It catches what can be caught: a static `import` or `require` that resolves
+ * to a `.node` file. An addon loaded through a runtime string — `process.dlopen`,
+ * or `require(variable)` — is not visible to any bundler, so such a project
+ * still compiles and still fails on the first request that reaches the addon.
+ * That limit is real, it is not fixable from inside a bundler, and it is
+ * written down in the CLI reference rather than papered over.
+ */
+function nativeAddonGuard() {
   return {
-    scripts: [`/${entry.file}`],
-    styles: [...styles].map((file) => `/${file}`),
-    preloads: [...preloads].map((file) => `/${file}`),
+    name: "uf:no-native-addons",
+    enforce: "pre",
+    resolveId(source, importer) {
+      if (!source.endsWith(".node")) return null;
+      const from = importer == null ? "the application" : path.relative(root, importer);
+      throw new Error(
+        `${from} loads the native addon ${source}, and \`uf build --compile\` cannot put one ` +
+          "inside a single executable: a `.node` file is a shared object built for one " +
+          "platform, and embedding it would make the output two files rather than one. " +
+          "Build without `--compile` and deploy `dist/` with a runtime, or replace the " +
+          "dependency with one that has no native addon.",
+      );
+    },
   };
 }
 
+/** `word`, pluralised for `count`. */
+function plural(count, word) {
+  return count === 1 ? word : `${word}s`;
+}
+
+async function printConfig() {
+  const config = await loadConfig();
+  emit("config", { config: projectConfig(config) });
+  process.exit(0);
+}
+
+function readManifest(outDir) {
+  const file = path.join(outDir, ".vite", "manifest.json");
+  if (!existsSync(file)) throw new Error(`uf: the client build wrote no manifest at ${file}`);
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
 /**
  * The URLs to prerender: every route without parameters, plus every set of
  * parameters a page's `generateStaticParams` returns.