sproutboat 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -10,6 +10,56 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.22.0] - 2026-10-22
+
+### Added
+
+- `sproutboat build --standalone --emit-only` writes
+  `.sproutboat/porffor-units/linux-x86_64-embedded-release/sprout.generated.js`,
+  byte for byte what a full standalone build compiles, prints its path and
+  stops. It runs every check that can fail a build, but acquires no Zig,
+  SQLite, BearSSL or Porffor and writes no binary, so it takes well under a
+  second where a full build takes tens of seconds. Without `--standalone` it
+  emits the broker-transport module the same way.
+
+### Fixed
+
+- The `d1`, `queue` and `analytics` examples read the request body with
+  `await request.text()` rather than as `request.body`. From compatibility date
+  `2026-10-21`, `request.body` is a `ReadableStream`, as in Workers, so
+  `JSON.parse(request.body)` threw `SyntaxError: Unexpected token` and a D1
+  example moved to a current date answered every POST with a 500. The new form
+  works at every date. `bun run examples` now also builds the d1 example at
+  `2026-10-22` (`d1@2026-10-22`), so an example that only works before that
+  date fails the run.
+
+### Changed
+
+- `@sproutboat/toolchain` 0.12.1: heap-backed BigInts stay alive through
+  conservative garbage collection, which fixes crashes and wrong checksums in
+  BigInt-heavy code such as CRC64 and LTX encoding. `@sproutboat/wire` 0.14.1.
+
+## [0.21.0] - 2026-10-21
+
+### Changed
+
+- Apps compile with Porffor Alpha 19 (`@sproutboat/toolchain` 0.12.0).
+  Binaries are about 1.5% smaller, and build times are unchanged.
+- Alpha 19 brings JavaScript closer to V8, and the changes apply at every
+  compatibility date:
+  - `Error.prototype.stack` is an accessor;
+  - `instanceof` follows the spec, including `Symbol.hasInstance`;
+  - sloppy-mode functions box a primitive `this`;
+  - undeclared names are read from the global object;
+  - using a `let`, `const` or class binding before its declaration throws.
+
+### Fixed
+
+- `JSON.parse` with a reviver now gives the reviver the right `context.source`
+  when the input contains non-ASCII text.
+- `Map.groupBy` works, and private class fields no longer show up as
+  enumerable properties.
+
 ## [0.20.0] - 2026-10-21
 
 ### Added

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.20.0
+**Package:** `sproutboat` 0.22.0
 
 ## Commands
 
@@ -13,7 +13,7 @@
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `types` | `[project-dir]` | 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. |
 | `dev` | `[project-dir] [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save. |
-| `build` | `[project-dir] [--target host] [--standalone]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. |
+| `build` | `[project-dir] [--target host] [--standalone] [--emit-only]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled. |
 | `toolchain` | `doctor [--json]` | Report the selected compiler inputs, cache locations, overrides, and host prerequisites without downloading or compiling anything. |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
@@ -32,7 +32,7 @@
 | `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
 ```
 
 ## Environment variables
@@ -76,7 +76,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | | |
 | --- | --- |
 | Zig | `0.16.0` (`zig cc -target x86_64-linux-musl`, static) |
-| Provenance stamp | `zig-musl/0.16.0+porffor/deda494+uws/360c276d` |
+| Provenance stamp | `zig-musl/0.16.0+porffor/0c135ce+uws/360c276d` |
 | Artifact schema | `2` |
 | Runtime | `native-fetch` |
 | Capability profile | `http-sync-v0` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -65,8 +65,8 @@
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.5.0",
     "@sproutboat/runtime": "^0.21.1",
-    "@sproutboat/toolchain": "^0.11.0",
-    "@sproutboat/wire": "^0.14.0"
+    "@sproutboat/toolchain": "^0.12.1",
+    "@sproutboat/wire": "^0.14.1"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.20.0",
-    "@sproutboat/cli-darwin-x64": "0.20.0",
-    "@sproutboat/cli-linux-arm64": "0.20.0",
-    "@sproutboat/cli-linux-x64": "0.20.0"
+    "@sproutboat/cli-darwin-arm64": "0.22.0",
+    "@sproutboat/cli-darwin-x64": "0.22.0",
+    "@sproutboat/cli-linux-arm64": "0.22.0",
+    "@sproutboat/cli-linux-x64": "0.22.0"
   },
   "engines": {
     "node": ">=18"

package/scripts/with-local-packages.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env bun
+/**
+ * Run a command against local `@sproutboat/{runtime,toolchain,wire}` checkouts.
+ *
+ *   bun scripts/with-local-packages.ts <path-to-sproutboat-packages> [--only runtime,toolchain,wire] -- <command...>
+ *
+ * Moves each `node_modules/@sproutboat/<pkg>` aside, symlinks
+ * `<packages>/packages/<pkg>` in its place, runs the command with inherited
+ * stdio, then puts the original entries back. The restore runs whatever the
+ * command does: a non-zero exit, a throw here, SIGINT or SIGTERM. Only SIGKILL
+ * can skip it, and the next run repairs that before it starts (the moved-aside
+ * entry is left in a known place for exactly that reason).
+ *
+ * Refuses to run in the main checkout when it has uncommitted changes. Work in
+ * progress lives there, and anything already running from it (a dev server, a
+ * watcher) would silently pick up the linked packages. Use a worktree instead.
+ */
+import { existsSync, lstatSync, readlinkSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { resolve } from "node:path";
+
+const PACKAGES = ["runtime", "toolchain", "wire"] as const;
+type Pkg = (typeof PACKAGES)[number];
+const isPkg = (value: string): value is Pkg => PACKAGES.some((pkg) => pkg === value);
+
+const USAGE =
+  "usage: bun scripts/with-local-packages.ts <path-to-sproutboat-packages> [--only runtime,toolchain,wire] -- <command...>";
+
+function fail(message: string): never {
+  console.error(`with-local-packages: ${message}`);
+  process.exit(2);
+}
+
+// ---- arguments ----------------------------------------------------------
+
+const argv = process.argv.slice(2);
+const separator = argv.indexOf("--");
+if (separator === -1) fail(`missing "--" before the command\n${USAGE}`);
+const ours = argv.slice(0, separator);
+const command = argv.slice(separator + 1);
+if (command.length === 0) fail(`no command after "--"\n${USAGE}`);
+
+let packagesRoot: string | undefined;
+let only: Pkg[] | undefined;
+for (let i = 0; i < ours.length; i++) {
+  const arg = ours[i];
+  if (arg === "--only" || arg.startsWith("--only=")) {
+    const value = arg === "--only" ? ours[++i] : arg.slice("--only=".length);
+    if (!value) fail(`--only needs a value\n${USAGE}`);
+    const names = value.split(",").map((name) => name.trim());
+    const unknown = names.filter((name) => !isPkg(name));
+    if (unknown.length) fail(`unknown package ${unknown.join(", ")} (expected ${PACKAGES.join(", ")})`);
+    only = names.filter(isPkg);
+  } else if (arg === "-h" || arg === "--help") {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (arg.startsWith("-")) {
+    fail(`unknown option ${arg}\n${USAGE}`);
+  } else if (packagesRoot === undefined) {
+    packagesRoot = resolve(arg);
+  } else {
+    fail(`unexpected argument ${arg}\n${USAGE}`);
+  }
+}
+if (!packagesRoot) fail(`missing the path to a sproutboat-packages checkout\n${USAGE}`);
+if (!existsSync(resolve(packagesRoot, "packages")))
+  fail(`${packagesRoot} has no packages/ directory: is it a sproutboat-packages checkout?`);
+
+// ---- safety: never touch a dirty main checkout --------------------------
+
+const cliRoot = resolve(import.meta.dir, "..");
+function git(...args: string[]): string {
+  const result = Bun.spawnSync(["git", "-C", cliRoot, ...args], { stdout: "pipe", stderr: "pipe" });
+  if (result.exitCode !== 0) fail(`git ${args.join(" ")} failed: ${result.stderr.toString().trim()}`);
+  return result.stdout.toString().trim();
+}
+const gitDir = resolve(cliRoot, git("rev-parse", "--git-dir"));
+const commonDir = resolve(cliRoot, git("rev-parse", "--git-common-dir"));
+const linkedWorktree = gitDir !== commonDir;
+if (!linkedWorktree && git("status", "--porcelain") !== "") {
+  fail(
+    `refusing to run: ${cliRoot} is the main checkout and has uncommitted changes.\n` +
+      "Relinking its node_modules would change what that work runs against. Use a worktree:\n" +
+      `  git -C ${cliRoot} worktree add /tmp/sb-cli-local origin/main\n` +
+      "  cd /tmp/sb-cli-local && bun install --frozen-lockfile\n" +
+      `  bun scripts/with-local-packages.ts ${packagesRoot} -- <command...>`,
+  );
+}
+
+// ---- link ---------------------------------------------------------------
+
+const scope = resolve(cliRoot, "node_modules/@sproutboat");
+const entryPath = (pkg: Pkg) => resolve(scope, pkg);
+const backupPath = (pkg: Pkg) => resolve(scope, `.${pkg}.with-local-packages-backup`);
+const exists = (path: string) => {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Put one package's original entry back. Synchronous so the exit hook can use it. */
+function restore(pkg: Pkg): void {
+  const entry = entryPath(pkg);
+  const backup = backupPath(pkg);
+  if (!exists(backup)) return;
+  if (exists(entry)) {
+    // Only ever remove our own symlink, never a real directory.
+    if (!lstatSync(entry).isSymbolicLink()) {
+      console.error(`with-local-packages: ${entry} is not a symlink, leaving ${backup} for you to inspect`);
+      return;
+    }
+    rmSync(entry);
+  }
+  renameSync(backup, entry);
+}
+
+// A run killed with SIGKILL leaves a backup behind: repair that first.
+for (const pkg of PACKAGES) {
+  if (exists(backupPath(pkg))) {
+    console.error(`with-local-packages: restoring node_modules/@sproutboat/${pkg} left over from an interrupted run`);
+    restore(pkg);
+  }
+}
+
+const requested = only ?? PACKAGES.filter((pkg) => existsSync(resolve(packagesRoot!, "packages", pkg, "package.json")));
+if (requested.length === 0) fail(`no runtime, toolchain or wire package under ${packagesRoot}/packages`);
+for (const pkg of requested) {
+  if (!existsSync(resolve(packagesRoot, "packages", pkg, "package.json")))
+    fail(`${packagesRoot}/packages/${pkg} has no package.json`);
+  if (!exists(entryPath(pkg))) fail(`node_modules/@sproutboat/${pkg} is missing: run bun install first`);
+}
+if (!existsSync(resolve(packagesRoot, "node_modules")))
+  console.error(
+    `with-local-packages: warning: ${packagesRoot} has no node_modules; ` +
+      "the linked packages resolve their own imports from there, so run bun install in it if anything fails to resolve",
+  );
+
+const linked: Pkg[] = [];
+let restored = false;
+function restoreAll(): void {
+  if (restored) return;
+  restored = true;
+  for (const pkg of linked.toReversed()) {
+    try {
+      restore(pkg);
+    } catch (error) {
+      console.error(`with-local-packages: could not restore ${pkg}: ${String(error)}`);
+      process.exitCode = 1;
+    }
+  }
+  const leftover = linked.filter((pkg) => exists(backupPath(pkg)));
+  if (leftover.length === 0) console.error(`with-local-packages: restored ${linked.join(", ")}`);
+}
+// The last line of defence: runs on any exit this process gets to see.
+process.on("exit", restoreAll);
+
+let child: ReturnType<typeof Bun.spawn> | undefined;
+let signalled: NodeJS.Signals | undefined;
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+  process.on(signal, () => {
+    // A second signal means "stop now": kill the command, the restore still runs.
+    if (signalled && child) child.kill("SIGKILL");
+    signalled = signal;
+    // Ctrl-C already reached the command through the process group; SIGTERM
+    // and SIGHUP sent to this process alone are passed on.
+    if (child && signal !== "SIGINT") child.kill(signal);
+    if (!child) {
+      restoreAll();
+      process.exit(128 + (signal === "SIGINT" ? 2 : signal === "SIGTERM" ? 15 : 1));
+    }
+  });
+}
+
+try {
+  for (const pkg of requested) {
+    const target = resolve(packagesRoot, "packages", pkg);
+    renameSync(entryPath(pkg), backupPath(pkg));
+    linked.push(pkg);
+    symlinkSync(target, entryPath(pkg), "dir");
+    console.error(`with-local-packages: @sproutboat/${pkg} -> ${readlinkSync(entryPath(pkg))}`);
+  }
+
+  child = Bun.spawn(command, { cwd: process.cwd(), stdio: ["inherit", "inherit", "inherit"] });
+  const code = await child.exited;
+  restoreAll();
+  if (signalled) process.exit(128 + (signalled === "SIGINT" ? 2 : signalled === "SIGTERM" ? 15 : 1));
+  process.exit(child.signalCode ? 1 : code);
+} catch (error) {
+  restoreAll();
+  fail(error instanceof Error ? error.message : String(error));
+}

package/src/build.ts

@@ -111,12 +111,13 @@ async function acquireArtifactLock(artifactDir: string): Promise<string> {
 }
 
 /**
- * Cross-compile a handler into a linux-x86_64 native-fetch server binary with
- * Porffor + Zig — no Docker. The binary is not run here (the build host may not
- * be linux); the control plane starts it once on deploy and rejects it if it
- * does not come up.
+ * Everything a build derives before the native compile: bindings, assets,
+ * version metadata and the wrapped module itself. Every check that can fail a
+ * build on its source or config (a missing asset dir, oversized baked assets,
+ * a handler without a default export) runs here, so `emitGenerated` fails
+ * exactly where `buildArtifact` would.
  */
-export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
+async function prepareBuild(input: BuildInput) {
   const source = input.source ?? (await readFile(input.sourcePath));
   const sourceHash = digest(source);
   const target = input.target ?? "linux-x86_64";
@@ -220,6 +221,93 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     input.transport,
     versionMetadata,
   );
+  return {
+    sourceHash,
+    target,
+    embedded,
+    host,
+    bindings,
+    assetDir,
+    assetManifest,
+    bakedAssets,
+    builtAt,
+    versionId,
+    versionMetadata,
+    generatedSource,
+  };
+}
+
+/**
+ * Porffor caches compiled C units per entry path, so compile from one path per
+ * project and build shape: unchanged units (the uWebSockets server alone is
+ * ~1.75 s of clang) are reused instead of rebuilt, and Porffor keeps one build
+ * dir per shape instead of one per artifact. `sprout.generated.js` lives here.
+ */
+function unitDirFor(input: BuildInput): string {
+  return resolve(
+    input.projectDir,
+    ".sproutboat/porffor-units",
+    `${input.target ?? "linux-x86_64"}-${input.transport ?? "broker"}-${input.optimize ?? "release"}`,
+  );
+}
+
+/**
+ * Write the wrapped module a build would compile, at the same path, and stop.
+ *
+ * Runs every check `buildArtifact` runs before compiling, then hands
+ * `compileSprout` `emitOnly`: no Zig, SQLite, BearSSL, Porffor or uWebSockets
+ * is acquired, nothing is compiled, and no artifact directory is written.
+ */
+export async function emitGenerated(input: BuildInput): Promise<{ generatedPath: string }> {
+  const { bindings, bakedAssets, versionMetadata, generatedSource } = await prepareBuild(input);
+  const unitDir = unitDirFor(input);
+  const generatedPath = input.generatedPath ?? resolve(unitDir, "sprout.generated.js");
+  // Same lock as a full build, so an emit never races a compile reading the file.
+  const unitLock = input.generatedPath ? null : await acquireArtifactLock(unitDir);
+  try {
+    await compileSprout({
+      sourcePath: input.sourcePath,
+      generatedPath,
+      generatedSource,
+      outPath: resolve(unitDir, "sprout"),
+      vars: input.config.vars ?? {},
+      bindings,
+      target: input.target,
+      compatibilityDate: input.config.compatibility_date,
+      transport: input.transport,
+      appName: input.config.name,
+      assets: bakedAssets,
+      optimize: input.optimize,
+      versionMetadata,
+      emitOnly: true,
+    });
+  } finally {
+    if (unitLock) await rm(unitLock, { recursive: true, force: true });
+  }
+  return { generatedPath };
+}
+
+/**
+ * Cross-compile a handler into a linux-x86_64 native-fetch server binary with
+ * Porffor + Zig — no Docker. The binary is not run here (the build host may not
+ * be linux); the control plane starts it once on deploy and rejects it if it
+ * does not come up.
+ */
+export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
+  const {
+    sourceHash,
+    target,
+    embedded,
+    host,
+    bindings,
+    assetDir,
+    assetManifest,
+    bakedAssets,
+    builtAt,
+    versionId,
+    versionMetadata,
+    generatedSource,
+  } = await prepareBuild(input);
   const compileKey = digest(
     JSON.stringify({
       generatedSource,
@@ -248,15 +336,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       const [sqliteObject, tls] = embedded
         ? await Promise.all([ensureSqliteObject({ target, zigBin }), ensureBearssl({ target, zigBin })])
         : [null, null];
-      // Porffor caches compiled C units per entry path, so compile from one
-      // path per project and build shape: unchanged units (the uWebSockets
-      // server alone is ~1.75 s of clang) are reused instead of rebuilt, and
-      // Porffor keeps one build dir per shape instead of one per artifact.
-      const unitDir = resolve(
-        input.projectDir,
-        ".sproutboat/porffor-units",
-        `${input.target ?? "linux-x86_64"}-${input.transport ?? "broker"}-${input.optimize ?? "release"}`,
-      );
+      const unitDir = unitDirFor(input);
       const unitLock = input.generatedPath ? null : await acquireArtifactLock(unitDir);
       try {
         await compileSprout({

package/src/compile.ts

@@ -93,6 +93,13 @@ export type CompileInput = {
    * cannot execute the deploy artifact.
    */
   target?: "linux-x86_64" | "host";
+  /**
+   * Write `generatedPath` exactly as a full compile would, then stop: no
+   * Porffor, no uWebSockets, no compiler, nothing at `outPath`. For callers
+   * that need the wrapped module (prelude, bindings, handler) and never run the
+   * binary, such as a qualification run that only inspects the source.
+   */
+  emitOnly?: boolean;
 };
 
 /**
@@ -197,8 +204,48 @@ export function porfforArgs(
   return args;
 }
 
-/** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
+/** The wrapped module the compiler sees: `generatedSource` if given, else the source wrapped here. */
+async function generateSource(input: CompileInput): Promise<string> {
+  if (input.generatedSource !== undefined) return input.generatedSource;
+  const [source, prelude] = await Promise.all([
+    input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
+    loadPrelude(input.transport ?? "broker"),
+  ]);
+  return wrapNativeFetchHandler(
+    source,
+    prelude,
+    input.vars,
+    input.bindings ?? EMPTY_BINDINGS,
+    undefined,
+    input.compatibilityDate,
+    input.appName,
+    input.assets,
+    input.transport,
+    input.versionMetadata,
+  );
+}
+
+/** Write the wrapped module to `generatedPath` (default: beside `outPath`) and return that path. */
+async function writeGenerated(input: CompileInput): Promise<string> {
+  const generatedPath = input.generatedPath ?? resolve(dirname(input.outPath), "sprout.generated.js");
+  const generatedSource = await generateSource(input);
+  await mkdir(dirname(generatedPath), { recursive: true });
+  await writeFile(generatedPath, generatedSource);
+  return generatedPath;
+}
+
+/**
+ * Compile `sourcePath` to a native binary at `outPath` (mode 0555).
+ *
+ * With `emitOnly`, write `generatedPath` and return before any of the native
+ * compile's inputs are acquired. Generation needs only the runtime prelude and
+ * the wrapper, never Porffor itself.
+ */
 export async function compileSprout(input: CompileInput): Promise<void> {
+  if (input.emitOnly) {
+    await writeGenerated(input);
+    return;
+  }
   const porffor = await ensurePorffor();
   await ensurePorfforPatched(porffor);
 
@@ -238,29 +285,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   // OS may still be executing. The linker cannot overwrite either, so clear it
   // first rather than failing with "can't write output file".
   await rm(input.outPath, { force: true });
-  const generatedPath = input.generatedPath ?? resolve(outDir, "sprout.generated.js");
-  await mkdir(dirname(generatedPath), { recursive: true });
-  const generatedSource =
-    input.generatedSource ??
-    (await (async () => {
-      const [source, prelude] = await Promise.all([
-        input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
-        loadPrelude(input.transport ?? "broker"),
-      ]);
-      return wrapNativeFetchHandler(
-        source,
-        prelude,
-        input.vars,
-        input.bindings ?? EMPTY_BINDINGS,
-        undefined,
-        input.compatibilityDate,
-        input.appName,
-        input.assets,
-        input.transport,
-        input.versionMetadata,
-      );
-    })());
-  await writeFile(generatedPath, generatedSource);
+  const generatedPath = await writeGenerated(input);
 
   const launcher = resolve(porffor, "runtime/index.js");
   // A musl build shells `zig` bare (Porffor hardcodes the literal command), so

package/src/main.ts

@@ -6,11 +6,11 @@ import { isBoolean, isSafeInteger, isString, jsonObject, parseJsonValue, type Js
 import type { AssetFiles } from "./assets";
 import { parseConfig, pinBindingId, resourceRefs, type SproutboatConfig } from "./config";
 import { validateHttpSyncSource } from "./source";
-import { buildArtifact } from "./build";
+import { buildArtifact, emitGenerated } from "./build";
 import { generateTypes, TYPES_FILE } from "./types-gen";
 import { bundleHandler, BundleError, type BundleResult } from "./bundle";
 import { runDev } from "./dev";
-import { buildStandalone } from "./standalone-build";
+import { buildStandalone, emitStandalone } from "./standalone-build";
 import { hostTarget, validateManifest, type ArtifactManifest } from "./manifest";
 import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
@@ -353,6 +353,33 @@ async function buildStandaloneBinary(directory: string | undefined, target: "lin
   }
 }
 
+/**
+ * `build --emit-only`: run the build up to and including writing
+ * `sprout.generated.js` (prelude, bindings and handler, exactly what Porffor
+ * would compile), print its path and stop. Every source and config check still
+ * fails the build; no compiler, SQLite or BearSSL is acquired and no binary is
+ * written.
+ */
+async function emitOnly(directory: string | undefined, target: "linux-x86_64" | "host", standalone: boolean) {
+  const project = await readProject(directory);
+  console.log(
+    dim(`Emitting ${standalone ? "the standalone " : ""}${project.config.name} source (${target}, no native compile)…`),
+  );
+  try {
+    const input = {
+      projectDir: project.directory,
+      config: project.config,
+      sourcePath: project.sourcePath,
+      source: project.bundle.code,
+      target,
+    };
+    const { generatedPath } = standalone ? await emitStandalone(input) : await emitGenerated(input);
+    console.log(generatedPath);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 /** #62 — build for this machine, run it against a real broker, rebuild on save. */
 async function dev(args: string[]) {
   const directory = args.find((arg) => !arg.startsWith("--") && !/^\d+$/.test(arg));
@@ -1314,8 +1341,10 @@ switch (command) {
   case "build": {
     const hostBuild = args.includes("--target") && args[args.indexOf("--target") + 1] === "host";
     const directory = args.find((arg) => !arg.startsWith("--") && arg !== "host");
-    if (args.includes("--standalone")) await buildStandaloneBinary(directory, hostBuild ? "host" : "linux-x86_64");
-    else await build(directory, hostBuild ? "host" : "linux-x86_64");
+    const target = hostBuild ? "host" : "linux-x86_64";
+    if (args.includes("--emit-only")) await emitOnly(directory, target, args.includes("--standalone"));
+    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target);
+    else await build(directory, target);
     break;
   }
   case "toolchain":

package/src/standalone-build.ts

@@ -9,7 +9,7 @@
  */
 import { chmod, cp, mkdir } from "node:fs/promises";
 import { resolve } from "node:path";
-import { buildArtifact, type BuildInput } from "./build";
+import { buildArtifact, emitGenerated, type BuildInput } from "./build";
 import type { Bindings } from "./wrap";
 
 export type StandaloneBuildInput = BuildInput & {
@@ -37,11 +37,26 @@ export function unsupportedBindings(bindings: Pick<Partial<Bindings>, "services"
   return reasons;
 }
 
-export async function buildStandalone(input: StandaloneBuildInput): Promise<StandaloneBuildResult> {
+function assertStandaloneSupported(input: BuildInput): void {
   const blocked = unsupportedBindings(input.config);
   if (blocked.length > 0) {
     throw new Error(`cannot build a standalone binary for this project:\n  - ${blocked.join("\n  - ")}`);
   }
+}
+
+/**
+ * `sproutboat build --standalone --emit-only`: the standalone build up to and
+ * including `sprout.generated.js`, byte for byte what a full standalone build
+ * compiles, at the same path. Every check that fails a standalone build fails
+ * this too; nothing native is acquired or compiled and no binary is copied out.
+ */
+export async function emitStandalone(input: BuildInput): Promise<{ generatedPath: string }> {
+  assertStandaloneSupported(input);
+  return emitGenerated({ ...input, transport: "embedded" });
+}
+
+export async function buildStandalone(input: StandaloneBuildInput): Promise<StandaloneBuildResult> {
+  assertStandaloneSupported(input);
   const artifact = await buildArtifact({ ...input, transport: "embedded" });
 
   // The sprout *is* the binary: assets and bindings are compiled into it, and

package/src/surface.ts

@@ -97,10 +97,10 @@ export const COMMANDS: readonly Command[] = [
     name: "build",
     group: "Develop",
     emoji: "🔨",
-    args: "[project-dir] [--target host] [--standalone]",
+    args: "[project-dir] [--target host] [--standalone] [--emit-only]",
     brief: "[project-dir]",
     summary:
-      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process.",
+      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled.",
   },
   {
     name: "toolchain",