sproutboat 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -10,6 +10,48 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.23.0] - 2026-10-22
+
+### Added
+
+- Experimental local backup of a D1 database to LTX files, in standalone
+  binaries (`@sproutboat/runtime` 0.22.0). It's off by default. To turn it on, set
+  the compatibility date to `2026-10-22` or later, `SB_LTX_ENABLE=1`, and
+  `SB_LTX_DATABASE=<binding>`. Every committed transaction is then written to a
+  durable LTX file, and the app resumes from the last one after a restart.
+  - Only one process may write to the database.
+  - Files stay on local disk; uploading them is not part of this release.
+  - See the runtime's `LTX_REPLICATION.md` for limits and recovery behaviour.
+
+## [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

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.21.0
+**Package:** `sproutboat` 0.23.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

package/package.json

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

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",