@uniflowed/vite 0.0.0-alpha.18 → 0.0.0-alpha.21

package/driver.js

@@ -7,7 +7,7 @@
 //
 //   <host> driver.js dev     --root <dir> [--mode <m>] [--host <h>] [--port <n>] [--strict-port]
 //                            [--uf-env-file <file>]...
-//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>]
+//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>] [--target <target>]
 //                            [--prerender everything|possible|nothing]
 //                            [--static-build] [--because <sentence>]
 //   <host> driver.js library --root <dir> [--mode <m>] [--out-dir <dir>]
@@ -39,6 +39,7 @@
 // Rust side reads a config that may hold functions and plugin instances: the
 // one host that can evaluate the file evaluates it.
 
+import { randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { builtinModules, register } from "node:module";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -49,14 +50,18 @@ import { COMPILE_ASSETS_ID, compileAssetsPlugin } from "./internal/compile-asset
 import { emit, errorEvent, eventLogger } from "./internal/events.js";
 import { loadUfConfig, projectConfig } from "./internal/config.js";
 import { send, toRequest } from "./internal/http.js";
+import { createOpenApiDocument } from "./internal/openapi.js";
 import { withProjectConfig } from "./merge.js";
-import { VIRTUAL, scanRoutes } from "./internal/routes.js";
+import { VIRTUAL, resolveRouteTarget, scanRoutes } from "./internal/routes.js";
 import {
+  BUILD_ID_FILE,
   assetsFromManifest,
+  buildIdentity,
   createPrerenderGate,
   createServeHandler,
   loadBuild,
   nodeListener,
+  providerSpecifier,
   withRequest,
 } from "./internal/serve.js";
 
@@ -113,6 +118,33 @@ run().catch((error) => {
   process.exit(1);
 });
 
+/**
+ * What this build is called, for anything that outlives it.
+ *
+ * `UF_BUILD_ID` when it is set, and a fresh random name otherwise — which is
+ * `crates/uf_rsc`'s `BuildId::from_env_or_generate` exactly, reading the same
+ * variable, because it is the same question asked by a different half of the
+ * toolchain. Two artefacts that have to *be* one build say so with the
+ * variable; everything else gets a name no other build has.
+ *
+ * Minted once per build and written into the build, never per process. Four
+ * servers started from one artefact are one build and must share one cache;
+ * generating this where the server starts would give them four, which is worse
+ * than none at all — four copies of everything written into one directory and
+ * none of them read.
+ *
+ * Not a hash of the output. A content hash would be reproducible, which is
+ * appealing and wrong here: two builds with identical client bundles can have
+ * different server behaviour — a loader's body moves and no asset hash does —
+ * and a cache keyed by one would serve the old loader's documents. A name that
+ * changes whenever the build ran is the conservative direction to be wrong in.
+ */
+function mintBuildId() {
+  const named = process.env.UF_BUILD_ID;
+  if (typeof named === "string" && named.trim() !== "") return named.trim();
+  return randomUUID().replaceAll("-", "");
+}
+
 /** Load `uf.config.js`, reporting where it was found. */
 async function loadConfig() {
   const { config, file } = await loadUfConfig(root);
@@ -130,6 +162,7 @@ async function viteConfig(config, mode) {
   const port = Number(argument("--port") ?? dev.port ?? 5173);
   const allowedHosts =
     Array.isArray(dev.allowedHosts) && dev.allowedHosts.length > 0 ? dev.allowedHosts : undefined;
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
 
   // What uf generates from the semantics it owns: where the project is, which
   // plugins make Flow compile, and the few settings uf enforces rather than
@@ -160,7 +193,7 @@ async function viteConfig(config, mode) {
     mode,
     clearScreen: false,
     customLogger: eventLogger(argument("--log-level") ?? "info"),
-    plugins: [uniflowed({ root, config })],
+    plugins: [uniflowed({ root, config, target: routeTarget })],
     server: {
       host,
       port,
@@ -224,6 +257,7 @@ async function viteConfig(config, mode) {
 async function dev() {
   const { createServer } = await import("vite");
   const config = await loadConfig();
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
   // 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.
@@ -235,9 +269,9 @@ async function dev() {
   emit("listening", {
     local: urls.local,
     network: urls.network,
-    routes: scanRoutes(path.resolve(root, config.app?.router?.root ?? "app")).routes.map(
-      (route) => route.path,
-    ),
+    routes: scanRoutes(path.resolve(root, config.app?.router?.root ?? "app"), {
+      target: routeTarget,
+    }).routes.map((route) => route.path),
   });
   watchSources(server);
   watchEnvFiles(server);
@@ -359,6 +393,7 @@ function watchEnvFiles(server) {
 async function preview() {
   const { preview: startPreview } = await import("vite");
   const config = await loadConfig();
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
   const inline = await viteConfig(config, argument("--mode") ?? "production");
   // A build that declared it emits no server has none to mount. `uf` refuses
   // `uf start` for such a project and lets this one through, because a preview
@@ -423,6 +458,30 @@ async function preview() {
   if (handle != null) {
     server.middlewares.use(answer(server));
   }
+  // The rewrite rule a single-page deployment needs, in the one place uf can
+  // apply one. A `["csr"]` build writes `index.html` and nothing else that is a
+  // page, so a file server answers `/` and 404s every other URL — and this
+  // preview exists to be believed about the deployment. A host serving that
+  // build has to send unmatched paths to the shell, so a preview that did not
+  // would be right about a deployment nobody is doing.
+  //
+  // Behind the static middleware, which is what makes it a *fallback*: a real
+  // file still wins, so `/assets/client.js` is still the chunk and not the
+  // shell. And `Accept: text/html` only, so a `fetch` for a missing JSON file
+  // gets a 404 rather than a document — the failure mode of a fallback that
+  // answers everything is a parse error two layers away from the missing file.
+  if (flag("--spa-fallback")) {
+    const shell = path.resolve(root, inline.build.outDir, "index.html");
+    server.middlewares.use((request, response, next) => {
+      if (request.method !== "GET" && request.method !== "HEAD") return next();
+      if (!(request.headers.accept ?? "").includes("text/html")) return next();
+      if (!existsSync(shell)) return next();
+      response.statusCode = 200;
+      response.setHeader("content-type", "text/html; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : readFileSync(shell));
+      return undefined;
+    });
+  }
 
   const urls = server.resolvedUrls ?? { local: [], network: [] };
   emit("listening", {
@@ -434,9 +493,9 @@ async function preview() {
     // be the report being wrong about the thing it exists to report.
     routes:
       build == null
-        ? scanRoutes(path.resolve(root, config.app?.router?.root ?? "app")).routes.map(
-            (route) => route.path,
-          )
+        ? scanRoutes(path.resolve(root, config.app?.router?.root ?? "app"), {
+            target: routeTarget,
+          }).routes.map((route) => route.path)
         : build.entry.routes.map((route) => route.path),
     handlers: build == null ? [] : build.entry.handlers.map((handler) => handler.path),
   });
@@ -560,6 +619,13 @@ async function build() {
       },
     },
   });
+  // What this build is, beside the bundle it is about. One line, written by
+  // every build and read by nothing unless a project turned a durable cache on
+  // — at which point it is the thing that stops a deploy answering the new
+  // build's URLs with the previous build's documents. See
+  // `packages/server/internal/cache-key.js`, which argues the whole of it, and
+  // `internal/serve.js`'s `buildIdentity`, which is what reads this.
+  writeFileSync(path.join(serverDir, BUILD_ID_FILE), `${mintBuildId()}\n`);
 
   // 3. Which routes this build renders when, and every route it renders now.
   //
@@ -570,6 +636,10 @@ async function build() {
   emit("phase", { name: "prerender" });
   const server = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
   const assets = assetsFromManifest(manifest);
+  const openapi = await createOpenApiDocument(server.handlers);
+  const openapiFile = path.join(root, ".uf", "build", "meta", "openapi.json");
+  mkdirSync(path.dirname(openapiFile), { recursive: true });
+  writeFileSync(openapiFile, `${JSON.stringify(openapi, null, 2)}\n`);
   const plan = await renderingPlan(server, prerender);
   emit("rendering", {
     prerender,
@@ -645,7 +715,7 @@ async function build() {
   //
   // 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`
+  // `$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.
   //
@@ -657,11 +727,50 @@ async function build() {
   // 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;
+  // The single-page build's whole output, written here because it is the one
+  // document this build has and the loop above had no route to write it for.
+  //
+  // Twice, to two names, and the second is the load-bearing one. `index.html`
+  // is what a host serves for `/`; `404.html` is what a static host serves for
+  // every path it has no file for, which under this plan is *every other URL
+  // in the application*. Without it a deployment of `dist/` answers `/` and
+  // 404s `/orders` — a build with a hole in it, found from a 404, which is the
+  // failure ubugeeei-prod/uf#336 is about wearing a different hat.
+  //
+  // It is still the host's rewrite rule that makes this correct, and the two
+  // files are what uf can do without one: a host with a proper SPA fallback
+  // serves `index.html` and never looks at `404.html`, and a host with only an
+  // error document (Pages, Netlify, an S3 bucket) serves `404.html` and gets
+  // the same bytes with a 404 status — which is the right status for a URL
+  // this application does not have, and the not-found boundary is what the
+  // browser then renders into it.
+  if (prerender === "shell") {
+    const html = server.shellDocument(assets);
+    for (const [file, url, status] of [
+      ["index.html", "/", 200],
+      ["404.html", "/404", 404],
+    ]) {
+      const target = path.join(outDir, file);
+      writeFileSync(target, html);
+      attempted += 1;
+      emit("page", {
+        url,
+        file: path.relative(root, target),
+        status,
+        bytes: Buffer.byteLength(html),
+      });
+    }
+  }
   // Not for a build that prerenders nothing. `404.html` is a file a static
   // host serves for every path it has no file for, and a project whose
   // `rendering.modes` allows only `ssr` has no such host: its not-found
   // boundary is rendered per request, by the server, with the right status.
-  if (prerender !== "nothing" && server.notFound.some((boundary) => boundary.path === "/")) {
+  //
+  // Nor for a shell build, which has just written its own: the boundary this
+  // would render is one the *browser* renders in that plan, and a document
+  // holding the framework's 404 markup would be served in place of the shell
+  // for every URL the host could not match.
+  else if (prerender !== "nothing" && 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`.
@@ -969,15 +1078,15 @@ async function compile() {
  * 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
+ * `static` is 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.
+ * `docs/app/reference/cli/$page.mdx` says why.
  */
 const ADAPTERS = {
   node: {
-    entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES),
-      server: nodeEntrySource("./handler.js"),
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build),
+      server: nodeEntrySource("./handler.js", schedules),
     }),
   },
   // The same two files as `node`, with `@uniflowed/server/bun` in place of
@@ -995,9 +1104,15 @@ const ADAPTERS = {
   // nobody here. `edge` pays that price because it must: there is no
   // `node:stream` in a Worker.
   bun: {
-    entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache, BUN_CAPABILITIES),
-      server: bunEntrySource("./handler.js"),
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, BUN_CAPABILITIES, build),
+      server: bunEntrySource("./handler.js", schedules),
+    }),
+  },
+  deno: {
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, DENO_CAPABILITIES, build),
+      server: denoEntrySource("./handler.js", schedules),
     }),
   },
   // The same two files. What `--adapter container` adds is a `Dockerfile` and
@@ -1005,25 +1120,31 @@ const ADAPTERS = {
   // output rather than anything the bundler produces — see `uf_cli`'s
   // `commands::deploy`.
   container: {
-    entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES),
-      server: nodeEntrySource("./handler.js"),
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build),
+      server: nodeEntrySource("./handler.js", schedules),
     }),
   },
   edge: {
-    entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES),
-      worker: workerEntrySource("./handler.js"),
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES, build),
+      worker: workerEntrySource("./handler.js", schedules),
     }),
     // `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"],
+    // A Worker has no filesystem, so uf's built-in durable provider cannot run
+    // here. Refused by name at the build rather than linked into a bundle that
+    // fails on its first `node:fs` import — the deployment rule is that a
+    // target which cannot provide a durable store says so, and this is the one
+    // target that cannot.
+    filesystem: false,
   },
   serverless: {
-    entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES),
+    entries: (document, cache, build) => ({
+      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES, build),
       lambda: lambdaEntrySource("./handler.js"),
     }),
   },
@@ -1048,6 +1169,7 @@ const ADAPTERS = {
  */
 const NODE_CAPABILITIES = { module: "@uniflowed/server/node", name: "nodeCapabilities" };
 const BUN_CAPABILITIES = { module: "@uniflowed/server/bun", name: "bunCapabilities" };
+const DENO_CAPABILITIES = { module: "@uniflowed/server/deno", name: "denoCapabilities" };
 const EDGE_CAPABILITIES = { module: "@uniflowed/server/edge", name: "edgeCapabilities" };
 const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lambdaCapabilities" };
 
@@ -1099,7 +1221,7 @@ const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lam
  * It is the one implemented target with no application to link: a static host
  * returns files, and `uf build` has already written them. So `uf` copies the
  * output directory itself and never spawns this driver for it, which is why
- * [`ADAPTERS`] has four rows and not five. What that target does instead of
+ * [`ADAPTERS`] has six rows and not seven. What that target does instead of
  * linking is refuse a project whose route handlers, middleware, unprerendered
  * routes or server actions a static host cannot answer — in Rust, because the
  * facts it needs are the route table and what the prerender reported.
@@ -1115,6 +1237,12 @@ async function deploy() {
   if (adapter == null || workArgument == null || outputArgument == null) {
     throw new Error("uf: `driver.js deploy` needs --adapter, --work and --output");
   }
+  // What the project declared, read by `uf`'s own walk of the route handlers
+  // and handed over rather than found again here — one reading of a module,
+  // and the same list `wrangler.json`'s `triggers.crons` is written from.
+  // Absent on an older `uf` spawning a newer driver, which is a build with no
+  // schedules rather than an error. See ubugeeei-prod/uf#531.
+  const schedules = JSON.parse(argument("--schedules") ?? "[]");
   // 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
@@ -1140,7 +1268,22 @@ async function deploy() {
   // misbehaves.
   mkdirSync(work, { recursive: true });
   const document = assetsFromManifest(readManifest(outDir));
-  const entries = shape.entries(document, config.app?.rendering?.cache);
+  // Whatever `build` above minted, so a durable cache in the deployed artefact
+  // is keyed by the build that produced it and not by the moment it was
+  // packaged. Read rather than minted again for exactly that reason: a second
+  // `randomUUID()` here would key the adapter's copy differently from the one
+  // `uf start` serves out of `.uf/build/`, which is two caches for one build.
+  const buildId = await buildIdentity(root, path.join(".uf", "build", "server"));
+  const cacheConfig = config.app?.rendering?.cache;
+  if (shape.filesystem === false && cacheConfig?.store === "filesystem") {
+    throw new Error(
+      `uf: rendering.cache.store is "filesystem" and \`--adapter ${adapter}\` has no ` +
+        "filesystem. Name a module exporting `createCacheProvider` instead — a KV " +
+        "namespace or a Redis behind the same seam — or leave the store in memory. See " +
+        "docs/app/guide/cache.",
+    );
+  }
+  const entries = shape.entries(document, cacheConfig, buildId, schedules);
   const input = {};
   for (const name of Object.keys(entries)) {
     writeFileSync(path.join(work, `${name}.js`), entries[name]);
@@ -1230,8 +1373,22 @@ async function deploy() {
  * re-exported above — a module-level singleton belongs to whichever copy of the
  * package a bundler happened to give it, and the copy that matters is the one
  * the application resolved. See ubugeeei-prod/uf#277 and #389.
+ *
+ * # And where a durable store is named
+ *
+ * `rendering.cache.store` is the fifth key, and it is the one that turns the
+ * store into a shared one: `"filesystem"` links uf's built-in provider, and
+ * anything else is a module specifier the project wrote, imported here by name
+ * so the bundler links it like any other dependency of the application. Neither
+ * appears at all when the key is absent, which is what a default project keeps.
+ *
+ * `build` is baked in beside it, and it is the reason this can be an `import`
+ * at all rather than something read at boot: the build id is a fact about the
+ * artefact being written, known here and nowhere later. `internal/serve.js`'s
+ * `buildIdentity` is where it came from and
+ * `packages/server/internal/cache-key.js` is why it exists.
  */
-function handlerEntrySource(document, cache, capabilities) {
+function handlerEntrySource(document, cache, capabilities, build) {
   const route = cache?.route === true;
   const fetchCache = cache?.fetch === true;
   // Nothing at all when both switches are off, so a default project's
@@ -1239,6 +1396,7 @@ function handlerEntrySource(document, cache, capabilities) {
   // generated output nobody asked for is the second half of the complaint
   // #277 makes about the first half.
   const store = route || fetchCache;
+  const durable = store ? durableStoreSource(root, cache, build) : null;
   const options = [
     "app",
     `document: ${JSON.stringify(document)}`,
@@ -1246,23 +1404,33 @@ function handlerEntrySource(document, cache, capabilities) {
     "capabilities",
   ].join(", ");
   const cacheImport = store ? 'import { createCacheStore } from "@uniflowed/server/cache";\n' : "";
+  const providerImport = durable == null ? "" : `${durable.import}\n`;
   const from = JSON.stringify(capabilities.module);
   const capabilityImport = `import { ${capabilities.name} } from ${from};`;
   return `// Generated by \`uf build --adapter\`. Not checked in, not edited.
 import { createFetchHandler } from "@uniflowed/server/fetch";
-${cacheImport}${capabilityImport}
+${cacheImport}${providerImport}${capabilityImport}
 import * as app from ${JSON.stringify(VIRTUAL.server)};
 
 ${
   store
-    ? `// \`rendering.cache\` from uf.config.js. One store per process: it is
+    ? `// \`rendering.cache\` from uf.config.js. ${
+        durable == null
+          ? `One store per process: it is
 // emptied by a restart and is not shared with any other instance of this
-// application. See ubugeeei-prod/uf#277.
-const cache = { store: createCacheStore(), route: ${String(route)}, fetch: ${String(fetchCache)} };
+// application.`
+          : `Entries are kept by ${durable.what},
+// under this build's identity, so a restart finds them where it left them and
+// every process of this deployment reads one store — and \`revalidateTag\` in
+// any of them takes an entry out of the store all of them fill from.`
+      } See ubugeeei-prod/uf#277.
+const cache = { store: createCacheStore(${
+        durable == null ? "" : `{ provider: ${durable.provider}, build: ${JSON.stringify(build)} }`
+      }), route: ${String(route)}, fetch: ${String(fetchCache)} };
 
 `
     : ""
-}// What this target can do, and it is not the same for all four: whether a
+}// What this target can do, and it is not the same for all six: whether a
 // response body reaches the client as it is produced, and whether the process
 // is still there once it has. A route handler that streams events or takes a
 // socket asks through this rather than finding out in production. Nothing is
@@ -1277,6 +1445,89 @@ export default { fetch, beginRequest };
 `;
 }
 
+/**
+ * The import and the expression that give a generated handler a durable store.
+ *
+ * `null` for `"memory"` and for a project that said nothing, which is every
+ * project until one asks: persistence is a second opt-in on top of `route` and
+ * `fetch`, not something a build decides on a project's behalf.
+ *
+ * The directory is baked in as written rather than resolved here, and that is
+ * deliberate. This function runs on the machine doing the build; the path has
+ * to mean something on the machine doing the *serving*, which may be a
+ * container with one writable mount or a Lambda with only `/tmp`. A relative
+ * one is resolved against the working directory at boot, by the provider, where
+ * the answer is a fact rather than a guess.
+ *
+ * The specifier is resolved against the project for the same reason
+ * `internal/serve.js`'s `providerSpecifier` does it: `"./cache/redis.js"` in
+ * `uf.config.js` is relative to the project, and this file is written into
+ * `.uf/deploy/work/`, where that path means nothing. Absolute is safe here
+ * because the bundler inlines the module rather than emitting the specifier.
+ *
+ * @param {string} root
+ * @param {{store?: string, storeDir?: string}} cache
+ * @param {string | null} build
+ */
+function durableStoreSource(root, cache, build) {
+  const named = cache?.store ?? "memory";
+  if (named === "memory") return null;
+  if (build == null) {
+    throw new Error(
+      `uf: rendering.cache.store is ${JSON.stringify(named)}, which keeps entries between ` +
+        "restarts, and this build has no identity to key them by. Run `uf build` so one is " +
+        "written, or set UF_BUILD_ID. Without one the deployment would answer this build's " +
+        "URLs with the previous build's documents.",
+    );
+  }
+  const directory = JSON.stringify(cache?.storeDir ?? path.join(".uf", "cache", "route"));
+  if (named === "filesystem") {
+    return {
+      import: 'import { createFilesystemCache } from "@uniflowed/server/cache/filesystem";',
+      provider: `createFilesystemCache({ directory: ${directory} })`,
+      what: "uf's filesystem provider",
+    };
+  }
+  const from = JSON.stringify(providerSpecifier(root, named));
+  return {
+    import: `import { createCacheProvider } from ${from};`,
+    provider: `createCacheProvider({ build: ${JSON.stringify(build)}, directory: ${directory} })`,
+    what: `${named}'s provider`,
+  };
+}
+
+/**
+ * The lines a process entry needs to run what the project declared.
+ *
+ * Shared by `nodeEntrySource` and `bunEntrySource` because the two differ in
+ * which module they take `serve` from and in nothing else — and a schedule
+ * that behaved differently between them would be the drift the whole seam
+ * exists to prevent. Empty strings when a project declared none, so the entry
+ * a default project gets is the file it has always been.
+ */
+function scheduleLines(module, schedules) {
+  const declared = schedules ?? [];
+  if (declared.length === 0) {
+    return { imports: "", declarations: "", option: "" };
+  }
+  const built = declared
+    .map(
+      (schedule) =>
+        `  routeSchedule({ handle: fetch, beginRequest, path: ${JSON.stringify(
+          schedule.path,
+        )}, cron: ${JSON.stringify(schedule.cron)} }),`,
+    )
+    .join("\n");
+  return {
+    imports: `import { routeSchedule } from ${JSON.stringify(module)};\n`,
+    // A schedule runs the route by asking the application for it, so a
+    // scheduled run and a request for the same path are one code path. See
+    // ubugeeei-prod/uf#531.
+    declarations: `\nconst schedules = [\n${built}\n];\n`,
+    option: ", schedules",
+  };
+}
+
 /**
  * The source of `server.js`: the Node socket around that handler.
  *
@@ -1286,13 +1537,14 @@ export default { fetch, beginRequest };
  * request answered by `uf start` go through one implementation, not two that
  * agree today.
  */
-function nodeEntrySource(handlerSpecifier) {
+function nodeEntrySource(handlerSpecifier, schedules) {
+  const cron = scheduleLines("@uniflowed/server/schedule", schedules);
   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";
-
+${cron.imports}
 // \`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
@@ -1305,12 +1557,12 @@ import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
 // 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");
-
+${cron.declarations}
 // 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) => {
+serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
   process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
   process.exit(1);
 });
@@ -1325,13 +1577,14 @@ serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
  * purpose, so that the two adapters are one contract and a project moving
  * between them changes a flag and nothing else.
  */
-function bunEntrySource(handlerSpecifier) {
+function bunEntrySource(handlerSpecifier, schedules) {
+  const cron = scheduleLines("@uniflowed/server/schedule", schedules);
   return `// Generated by \`uf build --adapter bun\`. Not checked in, not edited.
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { serve } from "@uniflowed/server/bun";
-
+${cron.imports}
 // \`beginRequest\` comes from the handler beside this file rather than from
 // \`@uniflowed/server/bun\` above, because the request has to be established in
 // the storage the *application* reads, which is the copy bundled into
@@ -1344,14 +1597,60 @@ import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
 // 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");
-
-serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
+${cron.declarations}
+serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
   process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
   process.exit(1);
 });
 `;
 }
 
+/**
+ * The source of `server.js`: the Deno socket around that handler.
+ *
+ * The same generated contract as Node and Bun, with `@uniflowed/server/deno`
+ * owning the host-specific pieces. The static directory is resolved with
+ * `import.meta.url` alone so the entry carries no `node:` imports.
+ */
+function denoEntrySource(handlerSpecifier, schedules) {
+  const cron = scheduleLines("@uniflowed/server/schedule", schedules);
+  return `// Generated by \`uf build --adapter deno\`. Not checked in, not edited.
+import { serve } from "@uniflowed/server/deno";
+${cron.imports}
+// \`beginRequest\` comes from the handler beside this file rather than from
+// \`@uniflowed/server/deno\` 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.
+//
+// Deno has no Node globals, but dependency bundles may still carry a CommonJS
+// production branch that expects a few of them. Establish the small environment
+// shape before \`handler.js\` is evaluated, which requires a dynamic import here
+// rather than a static one.
+globalThis.process ??= { env: {} };
+globalThis.process.env ??= {};
+globalThis.process.env.NODE_ENV ??= "production";
+globalThis.Buffer ??= {
+  byteLength(value) {
+    return new TextEncoder().encode(String(value)).byteLength;
+  },
+};
+globalThis.setImmediate ??= (callback, ...args) => setTimeout(callback, 0, ...args);
+globalThis.clearImmediate ??= (handle) => clearTimeout(handle);
+const { beginRequest, fetch } = await import(${JSON.stringify(handlerSpecifier)});
+
+// Resolved from this file and not from the working directory: a process
+// manager 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 = decodeURIComponent(new URL("./static", import.meta.url).pathname);
+${cron.declarations}
+serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
+  console.error(\`uf: \${error?.message ?? String(error)}\`);
+  Deno.exit(1);
+});
+`;
+}
+
 /**
  * The source of `worker.js`: the Cloudflare Workers entry around that handler.
  *
@@ -1364,13 +1663,39 @@ serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
  * `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.
+function workerEntrySource(handlerSpecifier, schedules) {
+  const declared = schedules ?? [];
+  // Nothing at all when the project declared none, so a `worker.js` without
+  // schedules is the file it has always been — and `wrangler.json` carries no
+  // `triggers` for it either, so there is nothing to call the export that
+  // would not be there.
+  if (declared.length === 0) {
+    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 expression Cloudflare fires, mapped to the route that answers it.
+  // `event.cron` arrives spelled exactly as `wrangler.json` spells it, and
+  // `uf` writes both from one list, so the two cannot disagree.
+  const routes = Object.fromEntries(declared.map((schedule) => [schedule.cron, schedule.path]));
+  return `// Generated by \`uf build --adapter edge\`. Not checked in, not edited.
+import { createWorkerFetch, createWorkerScheduled } from "@uniflowed/server/edge";
+
+import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+
+// \`triggers.crons\` in the wrangler.json beside this file names these same
+// expressions. See ubugeeei-prod/uf#531.
+const routes = ${JSON.stringify(routes, null, 2)};
+
+export default {
+  fetch: createWorkerFetch({ handle, beginRequest }),
+  scheduled: createWorkerScheduled({ handle, beginRequest, routes }),
+};
 `;
 }
 
@@ -1525,7 +1850,7 @@ function readManifest(outDir) {
  * this function are about.
  *
  * Handlers and middleware are in the same list, and they belong there: this is
- * the list of things that need a process, and a `_uf.route.js` needs one more
+ * the list of things that need a process, and a `$route.js` needs one more
  * obviously than any page does. They carry no per-route render — the build has
  * never written a file for either — so they appear only when the answer might
  * be a refusal.
@@ -1537,6 +1862,15 @@ async function renderingPlan(server, prerender) {
   const urls = [];
   const perRequest = [];
 
+  // One document, and it is no route's, so there is no route to ask anything
+  // about. `perRequest` is empty rather than "every route": nothing here is
+  // left for a server — the browser answers all of it — and listing routes
+  // under a heading that means "these need a process" would be a build
+  // describing itself wrongly to `uf`, which prints that list.
+  if (prerender === "shell") {
+    return { urls: [], perRequest: [] };
+  }
+
   // Nothing is prerendered and nothing is refused, so no page module is
   // loaded: a project that renders everything per request should not pay for
   // a `generateStaticParams` this build will not call.