sproutboat 0.8.0 → 0.10.0

package/src/patch-porffor.ts

@@ -1,144 +1,5 @@
-/**
- * Make Porffor's generated native-fetch server read its listen port from $PORT
- * at runtime (falling back to the compiled `port:` value). Porffor renders the
- * server as C text in `compiler/render.js`; we splice two lines into
- * `porf_native_fetch_get_port()`.
- *
- * Done as an idempotent in-place edit rather than a `postinstall` hook: package
- * managers block dependency lifecycle scripts by default, so a published
- * `postinstall` would silently not run. This is called from the build path
- * instead, where it always runs.
- *
- * Tracked upstream in patches/UPSTREAM.md — once Porffor reads $PORT (or exposes
- * env to handlers) this whole file goes away.
- */
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { porfforRoot } from "./toolchain";
-
-// Each edit below is independent and idempotent, with its own marker: a file
-// patched by an older version of this file must still receive the newer edits.
-const ANCHOR = "f64 porf_native_fetch_get_port(void) {\n";
-
-/** Port from $PORT (the supervisor and `sproutboat dev` set it). */
-const ENV_INJECT =
-  '  const char* __sb_port = getenv("PORT");\n' +
-  "  if (__sb_port && *__sb_port) { long __sb_v = strtol(__sb_port, NULL, 10); if (__sb_v > 0 && __sb_v < 65536) return (f64)__sb_v; }\n";
-const ENV_MARKER = 'getenv("PORT")';
-
-// #15 — no `--port` flag: Porffor's native-fetch entry point calls
-// `porf_init(0, NULL)` (see porf_native_fetch_runtime_init in render.js), so a
-// native-fetch binary never sees argv at all. A standalone binary takes its
-// port and data directory from the environment instead, which is what systemd
-// and docker set anyway. Worth an upstream note alongside the $PORT ask.
-
-/**
- * #15 — let the build add objects to the native-fetch link line.
- *
- * Porffor builds `linkArgs` as a fixed array, so an embedded backend that needs
- * SQLite compiled into the sprout has nowhere to put it. `CXX` is not a way in:
- * a musl (deploy) build overrides it outright. This splices one spread of
- * `SB_EXTRA_LINK` before `-lm`, inert unless the variable is set.
- */
-const LINK_ANCHOR = "          uSocketsArchive,\n          '-lm'\n";
-const LINK_INJECT =
-  "          ...(process.env.SB_EXTRA_LINK ? process.env.SB_EXTRA_LINK.split(' ').filter(Boolean) : []),\n";
-const LINK_MARKER = "SB_EXTRA_LINK";
-
-/**
- * #15 — and the same for the compile step, so the prelude's inline C can
- * `#include <bearssl.h>`. The link patch alone is not enough: Porffor compiles
- * the generated C from stdin with a fixed argument list, so there is otherwise
- * no way to add an include path.
- */
-const CFLAGS_ANCHOR = "          '-xc', '-', '-c',\n";
-const CFLAGS_INJECT =
-  "          ...(process.env.SB_EXTRA_CFLAGS ? process.env.SB_EXTRA_CFLAGS.split(' ').filter(Boolean) : []),\n";
-const CFLAGS_MARKER = "SB_EXTRA_CFLAGS";
-
-/**
- * #56 — make the inbound request-body limit configurable.
- *
- * Porffor's uWebSockets shim hardcodes 1 MiB and answers anything larger with a
- * bare `413 request body too large` before the handler runs, so a project can
- * neither accept a bigger upload nor say anything useful about the refusal.
- *
- * The default stays 1 MiB: a larger body is held in memory whole, so raising it
- * is a decision about this deployment's memory, not something to inherit.
- */
-const BODY_ANCHOR = "static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;";
-const BODY_INJECT = `static size_t sb_request_body_max(void) {
-  static size_t cached = 0;
-  if (cached == 0) {
-    const char* raw = getenv("SB_REQUEST_BODY_MAX");
-    long parsed = raw && *raw ? atol(raw) : 0;
-    cached = parsed > 0 ? (size_t)parsed : 1024u * 1024u;
-  }
-  return cached;
-}
-#define REQUEST_BODY_MAX_BYTES sb_request_body_max()`;
-const BODY_MARKER = "sb_request_body_max";
-
-let done = false;
-
-/** The uWebSockets shim source, which is where the body limit lives. */
-async function patchBodyLimit(): Promise<void> {
-  const file = resolve(porfforRoot(), "compiler/uwebsockets.js");
-  const src = await readFile(file, "utf8");
-  if (src.includes(BODY_MARKER)) return;
-  if (!src.includes(BODY_ANCHOR)) {
-    throw new Error(
-      `could not patch Porffor's request body limit: anchor not found in ${file}. ` +
-        "Porffor's uWebSockets shim changed — check patches/UPSTREAM.md.",
-    );
-  }
-  await writeFile(file, src.replace(BODY_ANCHOR, BODY_INJECT));
-}
-
-async function patchCompilerArgs(): Promise<void> {
-  const file = resolve(porfforRoot(), "compiler/index.js");
-  let src = await readFile(file, "utf8");
-  let changed = false;
-  for (const [marker, anchor, inject, what] of [
-    [LINK_MARKER, LINK_ANCHOR, LINK_INJECT, "extra link args"],
-    [CFLAGS_MARKER, CFLAGS_ANCHOR, CFLAGS_INJECT, "extra compiler flags"],
-  ] as const) {
-    if (src.includes(marker)) continue;
-    const at = src.indexOf(anchor);
-    if (at === -1) {
-      throw new Error(
-        `could not patch Porffor for ${what}: anchor not found in ${file}. ` +
-          "Porffor's native-fetch build changed — check patches/UPSTREAM.md.",
-      );
-    }
-    // After the anchor for cflags (the args follow it), before it for the link
-    // line (the object list ends with it).
-    src =
-      marker === CFLAGS_MARKER
-        ? src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length)
-        : src.slice(0, at) + inject + src.slice(at);
-    changed = true;
-  }
-  if (changed) await writeFile(file, src);
-}
-
-export async function ensurePorfforPatched(): Promise<void> {
-  if (done) return;
-  await patchCompilerArgs();
-  await patchBodyLimit();
-  const file = resolve(porfforRoot(), "compiler/render.js");
-  const src = await readFile(file, "utf8");
-  if (src.includes(ENV_MARKER)) {
-    done = true;
-    return;
-  }
-  const anchorAt = src.indexOf(ANCHOR);
-  if (anchorAt === -1) {
-    throw new Error(
-      `could not patch Porffor for $PORT: anchor not found in ${file}. ` +
-        "Porffor's native-fetch renderer changed — check patches/UPSTREAM.md.",
-    );
-  }
-  await writeFile(file, src.slice(0, anchorAt + ANCHOR.length) + ENV_INJECT + src.slice(anchorAt + ANCHOR.length));
-  done = true;
-}
+// Re-exported from @sproutboat/toolchain (moved verbatim). This shim keeps
+// every `./patch-porffor` importer working; the patch passes now live in the
+// shared package (`@sproutboat/toolchain/patch`) so the CLI and the monorepo
+// apply the same set. Mirrors src/broker.ts -> @sproutboat/wire.
+export { ensurePorfforPatched, patchRenderJs, patchUwebsockets } from "@sproutboat/toolchain";

package/src/porffor-toolchain.ts

@@ -0,0 +1,5 @@
+// Re-exported from @sproutboat/toolchain (moved verbatim). This shim keeps
+// every `./porffor-toolchain` importer working; the pin, the patches and the
+// fetch/verify/cache logic now live in the shared package so the CLI and the
+// monorepo cannot drift apart. Mirrors src/broker.ts -> @sproutboat/wire.
+export * from "@sproutboat/toolchain";

package/src/report.ts

@@ -1,15 +1,11 @@
-import { readFileSync } from "node:fs";
 import { gzipSync } from "bun";
 import { resourceRefs, type SproutboatConfig } from "./config";
 import type { ArtifactManifest } from "./manifest";
 import { bold, dim, leaf, sprout } from "./style";
 
-// Read from package.json so the banner never drifts from the published version.
-// SAFETY: our own package.json, shipped beside src/ by the `files` field; npm requires `version`.
-const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
-  version: string;
-};
-export const CLI_VERSION = packageJson.version;
+// `bun build --compile` has no package-relative filesystem at runtime. The
+// release build injects this value; source development keeps the package value.
+export const CLI_VERSION = process.env.SPROUTBOAT_CLI_VERSION ?? "0.9.0";
 
 function bytes(n: number): string {
   if (n < 1024) return `${n} B`;
@@ -65,6 +61,8 @@ function bindingRows(config: SproutboatConfig): string[][] {
   list(config.analytics_engine_datasets, "analytics");
   for (const [name, className] of Object.entries(config.durable_objects ?? {}))
     rows.push([`env.${name}`, "durable object", className]);
+  for (const rl of config.ratelimiters ?? [])
+    rows.push([`env.${rl.binding}`, "rate limiter", `${rl.limit} / ${rl.period}s`]);
   for (const host of config.outbound ?? []) rows.push([`fetch()`, "outbound", host]);
   for (const cron of config.triggers?.crons ?? []) rows.push([`scheduled()`, "cron", cron]);
   if (config.assets?.binding) rows.push([`env.${config.assets.binding}`, "assets", config.assets.directory ?? ""]);

package/src/source.ts

@@ -1,44 +1,4 @@
-import { neutraliseExports } from "./wrap";
-
-export type SourceValidation = { ok: true } | { ok: false; errors: string[] };
-
-// Checked against the *bundled* module (#89), not the entry file: after
-// bundling there are no imports left to reject, and a dependency reaching for a
-// Node API has to fail exactly as hand-written code would. A bare specifier
-// that resolves to nothing never gets this far — the bundler fails first.
-const alwaysForbidden: Array<[RegExp, string]> = [
-  [/^\s*import\s/m, "an import survived bundling — only static imports can be resolved at build time"],
-  [/\bimport\s*\(/, "dynamic import() is not supported: nothing can resolve it at build time"],
-  [/\brequire\s*\(/, "CommonJS require is not supported"],
-  [/\b(WebSocket|XMLHttpRequest)\s*\(/, "WebSocket / XMLHttpRequest are not supported"],
-  [/\b(process|Bun|Deno|Buffer|node:)\b/, "Node, Bun, and Deno APIs are not supported"],
-  // Porffor alpha-4 compiles `new Proxy(...)` and then ignores the handler: a
-  // trapped property reads back as `undefined`, with no throw. Rejecting it
-  // here is the difference between a build error and a 502 nobody can explain.
-  // It is why itty-router and other Proxy-based routers do not work yet.
-  [
-    /\bnew\s+Proxy\s*\(|\bProxy\s*\.\s*revocable\s*\(/,
-    "Proxy is not supported by the compiler: its traps are silently ignored and the property reads back as undefined",
-  ],
-];
-
-const fetchWithoutAllowlist: [RegExp, string] = [
-  /(?:\breturn\s+|\bawait\s+|=\s*)fetch\s*\(/,
-  "outbound networking needs an `outbound` host allowlist in sproutboat.jsonc",
-];
-
-export function validateHttpSyncSource(source: string, outboundAllowed = false): SourceValidation {
-  const errors: string[] = [];
-  // The default export must be an object literal with a `fetch` method. A module
-  // may also declare Durable Object classes / helpers before it, so this is not
-  // anchored to the start of the file.
-  // A hand-written file exports inline; a bundled one re-exports at the end.
-  // `neutraliseExports` is the same reader the compiler uses, so `check` cannot
-  // accept a module the build would then reject.
-  if (neutraliseExports(source) === null || !/\bfetch\s*\(/.test(source)) {
-    errors.push("handler must default-export an object with fetch(request)");
-  }
-  for (const [pattern, message] of alwaysForbidden) if (pattern.test(source)) errors.push(message);
-  if (!outboundAllowed && fetchWithoutAllowlist[0].test(source)) errors.push(fetchWithoutAllowlist[1]);
-  return errors.length ? { ok: false, errors } : { ok: true };
-}
+// Re-exported from @sproutboat/runtime (moved verbatim with wrap.ts).
+// This shim keeps every `./source` importer and the
+// `sproutboat/runtime/source` export path working.
+export * from "@sproutboat/runtime";

package/src/surface.ts

@@ -57,9 +57,9 @@ const storageCommands: readonly Command[] = STORAGE_PRODUCTS.map((product) => ({
   name: product.name,
   group: "Storage" as const,
   emoji: product.emoji,
-  args: STORAGE_ARGS,
+  args: product.name === "kv" ? `${STORAGE_ARGS} | <key | bulk | export> ...` : STORAGE_ARGS,
   brief: `<${STORAGE_VERBS.join(" | ")}>`,
-  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "queues" ? "; consumers deliver in batches with retries, and stop after 5 attempts" : ""}.`,
+  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "kv" ? "; key and bulk operations manage contents, and export writes a restorable JSON dump" : ""}${product.name === "queues" ? "; consumers deliver in batches with retries, and stop after 5 attempts" : ""}.`,
 }));
 
 export const COMMANDS: readonly Command[] = [
@@ -77,6 +77,14 @@ export const COMMANDS: readonly Command[] = [
     args: "[project-dir]",
     summary: "Validate the config and entry point without building.",
   },
+  {
+    name: "types",
+    group: "Develop",
+    emoji: "🧾",
+    args: "[project-dir]",
+    summary:
+      "Write sproutboat-env.d.ts from the config, so an editor knows what `env` holds. `dev` and `deploy` refresh it when the config is newer.",
+  },
   {
     name: "dev",
     group: "Develop",
@@ -189,9 +197,31 @@ export const ENV_VARS: readonly EnvVar[] = [
   {
     name: "SPROUTBOAT_UWS_TARBALL",
     purpose:
-      "Path to a prebuilt uWebSockets (x86_64-linux-musl) tarball to seed the Porffor cache with, instead of downloading it (removes the first-build git + make need).",
+      "Path to a uWebSockets source tarball to seed the Porffor cache with, instead of the one vendored in the package. Both targets are seeded from it.",
+  },
+  {
+    name: "CC",
+    purpose:
+      "C compiler used to build uSockets for a host build (default `cc`). A host build needs one regardless: it is what Porffor compiles its own generated C with.",
   },
+  { name: "AR", purpose: "Archiver used to assemble uSockets.a for a host build (default `ar`)." },
   { name: "SPROUTBOAT_COMPILE_TIMEOUT_MS", purpose: "Porffor compile timeout in ms (default 600000)." },
+  {
+    name: "SPROUTBOAT_TOOLCHAIN_CACHE",
+    purpose: "Managed Porffor and compiler cache root (default ~/.cache/sproutboat).",
+  },
+  {
+    name: "SPROUTBOAT_PORFFOR_DIR",
+    purpose: "Contributor override for an existing Porffor source checkout. Required files are validated before use.",
+  },
+  {
+    name: "SPROUTBOAT_BUILD_UWS_FROM_SOURCE",
+    purpose: "Set to 1 to explicitly allow the contributor-only Git and Make uWebSockets fallback.",
+  },
+  {
+    name: "SPROUTBOAT_CLI_VERSION",
+    purpose: "CLI version embedded by the release executable build. Not normally set by users.",
+  },
   {
     name: "SPROUTBOAT_VARS_JSON",
     purpose:

package/src/toolchain.ts

@@ -7,14 +7,17 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { chmod, mkdir, readFile, rm } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
+// @ts-expect-error Bun's file loader returns the embedded asset path in a compiled executable.
+import embeddedUwsArchive from "../vendor/uwebsockets-360c276d-musl.tar.xz" with { type: "file" };
+import { cachedPorfforRoot, PORFFOR_CHANNEL, PORFFOR_COMMIT } from "./porffor-toolchain";
 
 export const ZIG_VERSION = "0.16.0";
 
 /** The `<arch>-<os>` platforms ziglang.org publishes a tarball for that we pin. */
-type ZigPlatform = "x86_64-linux" | "aarch64-linux" | "x86_64-macos" | "aarch64-macos";
+export type ZigPlatform = "x86_64-linux" | "aarch64-linux" | "x86_64-macos" | "aarch64-macos";
 
 // sha256 of the official ziglang.org tarballs for ZIG_VERSION, keyed by
 // `<arch>-<os>` (the download naming). Bump alongside ZIG_VERSION.
@@ -25,17 +28,12 @@ const ZIG_SHA256 = {
   "aarch64-macos": "b23d70deaa879b5c2d486ed3316f7eaa53e84acf6fc9cc747de152450d401489",
 } satisfies Record<ZigPlatform, string>;
 
-// Pinned Porffor identity — must match the `porffor` entry in package.json
-// (`github:CanadaHonk/porffor#alpha-4`, commit a415d19). PORFFOR_VERSION overrides.
+// Pinned Porffor identity comes from porffor-toolchain.ts. PORFFOR_VERSION overrides.
 // When bumping this pin (#55): run the monorepo's `bun run diff` against the
 // frozen reference handlers and update its COMPAT.md for any new mismatch before
 // releasing — the alpha compiler's output can shift between pins. Checked by
 // hand at bump time, not in CI.
-const PORFFOR_CHANNEL = "alpha-4";
-const PORFFOR_COMMIT = "a415d19";
-
-// uWebSockets commit Porffor alpha-4 fetches for the native-fetch server. Read
-// from node_modules/porffor at build time; this is the fallback for the stamp.
+// uWebSockets commit Porffor alpha-4 fetches for the native-fetch server.
 const UWS_COMMIT = "360c276d";
 const UWS_COMMIT_FULL = "360c276d609d59af56ae6932adb95154ace9f15f";
 
@@ -56,51 +54,157 @@ function platformKey(): ZigPlatform {
   return `${arch}-${os}`;
 }
 
+export class ZigToolchainError extends Error {
+  constructor(
+    readonly kind: "download" | "integrity" | "archive" | "cache" | "unsupported",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export type EnsureZigOptions = {
+  cacheRoot?: string;
+  platform?: ZigPlatform;
+  url?: string;
+  expectedSha256?: string;
+  fetcher?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+  timeoutMs?: number;
+};
+
 async function sha256File(path: string): Promise<string> {
   const hash = createHash("sha256");
   hash.update(await readFile(path));
   return hash.digest("hex");
 }
 
-/** Absolute path to a usable `zig` binary, downloading it on first use. */
-export async function ensureZig(): Promise<string> {
+async function zigComplete(dir: string, key: ZigPlatform, expectedArchive: string): Promise<boolean> {
+  try {
+    // SAFETY: this manifest is private data written below; its values are only
+    // accepted when the immutable identity and binary digest both match.
+    const manifest = JSON.parse(await readFile(resolve(dir, ".sproutboat-complete"), "utf8")) as {
+      version?: string;
+      platform?: string;
+      archiveSha256?: string;
+      binarySha256?: string;
+    };
+    const bin = resolve(dir, "zig");
+    return (
+      manifest.version === ZIG_VERSION &&
+      manifest.platform === key &&
+      manifest.archiveSha256 === expectedArchive &&
+      manifest.binarySha256 !== undefined &&
+      (await sha256File(bin)) === manifest.binarySha256
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function downloadZig(
+  url: string,
+  path: string,
+  fetcher: NonNullable<EnsureZigOptions["fetcher"]>,
+  timeoutMs: number,
+): Promise<void> {
+  let last: unknown;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const response = await fetcher(url, { signal: AbortSignal.timeout(timeoutMs) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      await writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      return;
+    } catch (error) {
+      last = error;
+    }
+  }
+  throw new ZigToolchainError("download", `could not download pinned Zig from ${url}: ${String(last)}`);
+}
+
+async function waitForZigPublisher(
+  dir: string,
+  lock: string,
+  key: ZigPlatform,
+  expected: string,
+): Promise<string | null> {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
+    if (!existsSync(lock)) return null;
+    if (Date.now() - (await stat(lock)).mtimeMs > 5 * 60_000) {
+      await rm(lock, { recursive: true, force: true });
+      return null;
+    }
+    await Bun.sleep(25);
+  }
+  throw new ZigToolchainError("cache", `timed out waiting for Zig cache lock ${lock}`);
+}
+
+/** Absolute path to a verified Zig binary, downloading it on first use. */
+export async function ensureZig(options: EnsureZigOptions = {}): Promise<string> {
   const override = process.env.SPROUTBOAT_ZIG;
   if (override) {
-    if (!existsSync(override)) throw new Error(`SPROUTBOAT_ZIG=${override} does not exist`);
+    if (!existsSync(override)) throw new ZigToolchainError("unsupported", `SPROUTBOAT_ZIG=${override} does not exist`);
     return override;
   }
-  const key = platformKey();
-  const home = homedir();
-  const dir = resolve(home, ".cache/sproutboat", `zig-${ZIG_VERSION}`);
-  const bin = resolve(dir, "zig");
-  if (existsSync(bin)) return bin;
-
-  const url = `https://ziglang.org/download/${ZIG_VERSION}/zig-${key}-${ZIG_VERSION}.tar.xz`;
-  const expected = ZIG_SHA256[key];
+  const key = options.platform ?? platformKey();
+  const root = resolve(
+    options.cacheRoot ?? process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"),
+  );
+  const dir = resolve(root, `zig-${ZIG_VERSION}-${key}`);
+  const expected = options.expectedSha256 ?? ZIG_SHA256[key];
+  if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
+  await mkdir(root, { recursive: true });
+  const lock = `${dir}.lock`;
+  try {
+    await mkdir(lock);
+  } catch {
+    const published = await waitForZigPublisher(dir, lock, key, expected);
+    if (published) return published;
+    return ensureZig(options);
+  }
+  const stage = resolve(root, `.zig-${ZIG_VERSION}-${key}-${process.pid}-${crypto.randomUUID()}`);
+  const url = options.url ?? `https://ziglang.org/download/${ZIG_VERSION}/zig-${key}-${ZIG_VERSION}.tar.xz`;
   console.log(`Fetching Zig ${ZIG_VERSION} (${key}, one-time)...`);
-  await mkdir(dir, { recursive: true });
-  const archive = resolve(dir, "zig.tar.xz");
-  const response = await fetch(url);
-  if (!response.ok) throw new Error(`could not download Zig: ${url} (${response.status})`);
-  await Bun.write(archive, response);
-
-  const actual = await sha256File(archive);
-  if (expected && actual !== expected) {
+  try {
+    if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
     await rm(dir, { recursive: true, force: true });
-    throw new Error(`Zig download sha256 mismatch\n  expected ${expected}\n  got      ${actual}`);
+    await mkdir(stage);
+    const archive = resolve(stage, "zig.tar.xz");
+    await downloadZig(url, archive, options.fetcher ?? fetch, options.timeoutMs ?? 30_000);
+    const actual = await sha256File(archive);
+    if (actual !== expected)
+      throw new ZigToolchainError(
+        "integrity",
+        `Zig archive sha256 mismatch\n  expected ${expected}\n  got      ${actual}`,
+      );
+    const untar = Bun.spawn(["tar", "-xJf", archive, "-C", stage, "--strip-components=1"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
+    if (code !== 0)
+      throw new ZigToolchainError("archive", `could not extract Zig (needs \`tar\` with xz support): ${err.trim()}`);
+    await rm(archive, { force: true });
+    const bin = resolve(stage, "zig");
+    if (!existsSync(bin)) throw new ZigToolchainError("archive", "Zig archive did not contain a `zig` binary");
+    await chmod(bin, 0o755);
+    await writeFile(
+      resolve(stage, ".sproutboat-complete"),
+      JSON.stringify({
+        version: ZIG_VERSION,
+        platform: key,
+        archiveSha256: actual,
+        binarySha256: await sha256File(bin),
+      }),
+      { mode: 0o444 },
+    );
+    await rename(stage, dir);
+    return resolve(dir, "zig");
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+    await rm(lock, { recursive: true, force: true });
   }
-
-  // `tar -xJ` (xz) works on macOS bsdtar and GNU tar with xz on PATH.
-  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
-  if (code !== 0) throw new Error(`could not extract Zig (needs \`tar\` with xz support): ${err.trim()}`);
-  await rm(archive, { force: true });
-  if (!existsSync(bin)) throw new Error("Zig archive did not contain a `zig` binary");
-  await chmod(bin, 0o755);
-  return bin;
 }
 
 function uwsCommitFull(): string {
@@ -117,7 +221,9 @@ export class UwsUnavailableError extends Error {}
 
 /** Path to the vendored prebuilt archive for the given short commit. */
 export function uwsVendorArchive(short: string): string {
-  return resolve(import.meta.dir, "..", "vendor", `uwebsockets-${short}-musl.tar.xz`);
+  return short === UWS_COMMIT_FULL.slice(0, 8)
+    ? embeddedUwsArchive
+    : resolve(import.meta.dir, "..", "vendor", `uwebsockets-${short}-musl.tar.xz`);
 }
 
 /**
@@ -156,26 +262,104 @@ export async function ensureUWebSockets(): Promise<void> {
     }
   }
 
+  await extractUws(archive, dir);
+}
+
+/** Unpack the vendored source tree into `dir`. */
+async function extractUws(archive: string, dir: string): Promise<void> {
   await mkdir(dir, { recursive: true });
-  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], {
+  // External programs cannot read Bun's virtual /$bunfs paths. Materialize the
+  // embedded release asset inside the destination before handing it to tar.
+  const readableArchive = archive.includes("/$bunfs/") ? resolve(dir, ".sproutboat-uwebsockets.tar.xz") : archive;
+  if (readableArchive !== archive) await Bun.write(readableArchive, Bun.file(archive));
+  const untar = Bun.spawn(["tar", "-xJf", readableArchive, "-C", dir, "--strip-components=1"], {
     stdout: "pipe",
     stderr: "pipe",
   });
   const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
+  if (readableArchive !== archive) await rm(readableArchive, { force: true });
   if (code !== 0) {
     await rm(dir, { recursive: true, force: true });
     throw new UwsUnavailableError(`could not extract vendored uWebSockets: ${err.trim()}`);
   }
 }
 
+/**
+ * The same seeding for a **host** build (`dev`, `build --target host`,
+ * `--standalone` on this machine).
+ *
+ * The vendored archive is a full checkout, so the sources are the same for
+ * every target; only `uSockets.a` is target-specific. Porffor would build that
+ * with `make -C uSockets`, which is where the `git` and `make` requirements on
+ * a first build came from. Compiling the thirteen C files directly removes
+ * both, and adds no new dependency: a host build already needs a C compiler,
+ * because that is what Porffor compiles its own generated C with.
+ *
+ * Flags mirror the uSockets makefile's default target with the WITH_* switches
+ * Porffor passes (all off): `-std=c11 -Isrc -DLIBUS_NO_SSL -flto -O3`, then
+ * `ar rvs`. Nothing here is a judgement call; it is that recipe.
+ */
+export async function ensureUWebSocketsHost(): Promise<void> {
+  const commit = uwsCommitFull();
+  const dir = resolve(homedir(), ".cache/porffor/deps", `uWebSockets-${commit}`);
+  const uSockets = resolve(dir, "uSockets");
+  const archivePath = resolve(uSockets, "uSockets.a");
+  if (existsSync(resolve(dir, "src/App.h")) && existsSync(archivePath)) return;
+
+  const vendored = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(commit.slice(0, 8));
+  if (!existsSync(vendored)) {
+    throw new UwsUnavailableError(`no vendored uWebSockets archive at ${vendored}`);
+  }
+  if (!process.env.SPROUTBOAT_UWS_TARBALL) {
+    const actual = await sha256File(vendored);
+    if (actual !== UWS_TARBALL_SHA256) {
+      throw new UwsUnavailableError(
+        `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+      );
+    }
+  }
+  if (!existsSync(resolve(dir, "src/App.h"))) await extractUws(vendored, dir);
+
+  // The archive carries the musl-built uSockets.a. Linking that into a host
+  // binary fails in a way nobody would connect to this, so it goes first.
+  await rm(archivePath, { force: true });
+
+  const sources = ["src/*.c", "src/eventing/*.c", "src/crypto/*.c", "src/io_uring/*.c"];
+  const cc = process.env.CC || "cc";
+  const ar = process.env.AR || "ar";
+  const compile = Bun.spawn(["sh", "-c", `${cc} -std=c11 -Isrc -DLIBUS_NO_SSL -flto -O3 -c ${sources.join(" ")}`], {
+    cwd: uSockets,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [ccCode, ccErr] = await Promise.all([compile.exited, new Response(compile.stderr).text()]);
+  if (ccCode !== 0) {
+    throw new UwsUnavailableError(
+      `could not compile uSockets with ${cc}: ${ccErr.trim().split("\n").slice(-3).join(" ")}`,
+    );
+  }
+
+  const archiveStep = Bun.spawn(["sh", "-c", `${ar} rvs uSockets.a *.o`], {
+    cwd: uSockets,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [arCode, arErr] = await Promise.all([archiveStep.exited, new Response(archiveStep.stderr).text()]);
+  if (arCode !== 0 || !existsSync(archivePath)) {
+    throw new UwsUnavailableError(`could not archive uSockets with ${ar}: ${arErr.trim()}`);
+  }
+}
+
 /** Directory holding node_modules/porffor (walks up from this file). */
 export function porfforRoot(start = import.meta.dir): string {
+  const managed = cachedPorfforRoot();
+  if (existsSync(resolve(managed, "runtime/index.js"))) return managed;
   let dir = start;
   for (;;) {
     const candidate = resolve(dir, "node_modules/porffor");
     if (existsSync(resolve(candidate, "runtime/index.js"))) return candidate;
     const parent = dirname(dir);
-    if (parent === dir) throw new Error("node_modules/porffor not found — run `bun install`");
+    if (parent === dir) return managed;
     dir = parent;
   }
 }