sproutboat 0.7.0 → 0.9.0

package/src/build.ts

@@ -3,7 +3,9 @@ import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { walkAssets, type AssetManifest } from "./assets";
 import { resourceRefs, type SproutboatConfig } from "./config";
-import { compileSprout } from "./compile";
+import { ensureSqliteObject } from "./sqlite";
+import { ensureBearssl } from "./bearssl";
+import { compileSprout, type Transport } from "./compile";
 import {
   ARTIFACT_SCHEMA_VERSION,
   CAPABILITY_PROFILE,
@@ -30,6 +32,16 @@ export type BuildInput = {
    * the real target, which is what stops the result being deployed.
    */
   target?: "linux-x86_64" | "host";
+  /** #15 — `embedded` compiles SQLite into the sprout instead of a broker
+   *  transport. Defaults to the broker transport. */
+  transport?: Transport;
+  /**
+   * `dev` compiles at -O0, which is roughly three times faster and produces a
+   * bigger binary. Only for artifacts that cannot be deployed: `deploy` refuses
+   * a host build already, and this defaults to `release` so a caller has to ask
+   * for the fast path deliberately.
+   */
+  optimize?: "dev" | "release";
 };
 
 export type BuildOutput = {
@@ -37,6 +49,10 @@ export type BuildOutput = {
   manifest: ArtifactManifest;
 };
 
+/** Baking megabytes of assets into the module makes the Porffor compile crawl;
+ *  past this it is the wrong tool and the error says what to do instead. */
+const MAX_BAKED_ASSET_BYTES = 8_000_000;
+
 function digest(value: Uint8Array | string): `sha256:${string}` {
   return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
@@ -77,6 +93,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     queues: refsByKind.queue.map((ref) => ref.binding),
     analytics: input.config.analytics_engine_datasets ?? [],
     do: Object.entries(input.config.durable_objects ?? {}).map(([binding, className]) => ({ binding, className })),
+    services: input.config.services ?? [],
     crons: input.config.triggers?.crons ?? [],
     assets: input.config.assets?.binding ?? "",
     // Baked plain values, read as env.NAME. The broker never serves these (they
@@ -91,6 +108,43 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   // for it — that download is the slowest part of a first local build.
   const host = input.target === "host";
   const zigBin = host ? undefined : await ensureZig();
+  // #15 — an embedded sprout carries its own storage and TLS instead of talking
+  // to a broker: SQLite and BearSSL are compiled once per target and added to
+  // the link line, and BearSSL's header to the compile line.
+  const embedded = input.transport === "embedded";
+  const target = input.target ?? "linux-x86_64";
+  const sqliteObject = embedded ? await ensureSqliteObject({ target, zigBin }) : null;
+  const tls = embedded ? await ensureBearssl({ target, zigBin }) : null;
+  const extraLink = [...(sqliteObject ? [sqliteObject] : []), ...(tls ? tls.objects : [])];
+  const extraCflags = tls ? ["-I", tls.includeDir] : [];
+  // #15 — an embedded binary has no files beside it, so assets are baked into
+  // the module. Read them from the source directory: the artifact copy happens
+  // after the compile, and the compile is what needs them. Bytes travel as a
+  // latin1 string, one char per byte, which is what the asset shim hands back.
+  let bakedAssets: { manifest: AssetManifest; files: Record<string, string> } | undefined;
+  if (input.transport === "embedded" && input.config.assets) {
+    const dir = resolve(input.projectDir, input.config.assets.directory);
+    const manifest: AssetManifest = {
+      notFound: input.config.assets.not_found_handling ?? "none",
+      runSproutFirst: input.config.assets.run_sprout_first ?? false,
+      files: walkAssets(dir),
+    };
+    const files: Record<string, string> = {};
+    let total = 0;
+    for (const key of Object.keys(manifest.files)) {
+      const bytes = await readFile(resolve(dir, `.${key}`));
+      total += bytes.byteLength;
+      if (total > MAX_BAKED_ASSET_BYTES) {
+        throw new Error(
+          `assets are too large to compile into a standalone binary (over ${MAX_BAKED_ASSET_BYTES / 1_000_000} MB). ` +
+            "Serve them from R2, or drop the assets binding and put a web server in front.",
+        );
+      }
+      files[key] = bytes.toString("latin1");
+    }
+    bakedAssets = { manifest, files };
+  }
+
   await compileSprout({
     sourcePath: input.sourcePath,
     source: input.source,
@@ -100,6 +154,12 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     zigBin,
     target: input.target,
     compatibilityDate: input.config.compatibility_date,
+    transport: input.transport,
+    appName: input.config.name,
+    assets: bakedAssets,
+    extraLink,
+    extraCflags,
+    optimize: input.optimize,
   });
 
   const sprout = await readFile(sproutPath);

package/src/compile.ts

@@ -12,8 +12,17 @@
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
-import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
-import { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
+import { ensureUWebSockets, ensureUWebSocketsHost, porfforRoot, UwsUnavailableError } from "./toolchain";
+import {
+  EMPTY_BINDINGS,
+  preludePath,
+  transportPath,
+  wrapNativeFetchHandler,
+  TRANSPORT_MARKER,
+  type Bindings,
+  type Transport,
+} from "./wrap";
+export type { Transport } from "./wrap";
 
 export {
   BASELINE_COMPATIBILITY_DATE,
@@ -35,6 +44,26 @@ export type CompileInput = {
   /** The project's `compatibility_date`, baked in so the runtime can gate a
    *  behaviour change on it. Defaults to the baseline when absent. */
   compatibilityDate?: string;
+  /** #15 — which `__sbCall` to compile in. Defaults to the broker transport. */
+  transport?: Transport;
+  /** #15 — the project name, baked so an embedded build can default its data dir. */
+  appName?: string;
+  /** #15 — assets baked into the module (embedded builds have no files on disk). */
+  assets?: { manifest: unknown; files: Record<string, string> };
+  /** #15 — objects to add to the native-fetch link line (SQLite, BearSSL). */
+  extraLink?: string[];
+  /** #15 — flags for the compile step, so inline C can include BearSSL's header. */
+  extraCflags?: string[];
+  /**
+   * How hard the C compiler works on the generated code.
+   *
+   * Porffor defaults to `-O3` (compiler/index.js reads `-O` from its own argv),
+   * which costs most of the build: `examples/hello` is 8.4s at -O3 against 2.9s
+   * at -O0 on an M-series host. `dev` pays that on every edit for a binary that
+   * never leaves the machine, so it compiles at -O0 and takes a ~55% larger
+   * file. Anything that could be deployed stays at -O3.
+   */
+  optimize?: "dev" | "release";
   /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
   zigBin?: string;
   /**
@@ -46,15 +75,65 @@ export type CompileInput = {
   target?: "linux-x86_64" | "host";
 };
 
+/**
+ * The prelude with a transport spliced in — the exact text the compiler sees.
+ *
+ * Exported because more than one caller composes a sprout: the build, and the
+ * kitchen-sink harness that compiles one itself. Reading
+ * `native-fetch-prelude.js` alone yields a module with no `__sbCall` at all.
+ */
+export async function loadPrelude(transport: Transport = "broker"): Promise<string> {
+  const [core, chosen] = await Promise.all([readFile(preludePath, "utf8"), readFile(transportPath(transport), "utf8")]);
+  if (!core.includes(TRANSPORT_MARKER)) {
+    throw new Error("prelude is missing its transport marker — src/native-fetch-prelude.js changed shape");
+  }
+  return core.replace(TRANSPORT_MARKER, chosen);
+}
+
+/** Child env for the Porffor run. `SB_EXTRA_LINK` is read by the patched link
+ *  step (#15) and is absent entirely for a normal build. */
+function compileEnv(path: string, extraLink?: string[], extraCflags?: string[]) {
+  const link = extraLink && extraLink.length > 0 ? extraLink.join(" ") : undefined;
+  const cflags = extraCflags && extraCflags.length > 0 ? extraCflags.join(" ") : undefined;
+  return { ...process.env, PATH: path, SB_EXTRA_LINK: link, SB_EXTRA_CFLAGS: cflags };
+}
+
+/**
+ * The argument list handed to Porffor, minus the launcher.
+ *
+ * Exported for the test: the one thing worth pinning is that `-O0` reaches only
+ * a build that cannot be deployed. `-s` strips at link, because the unstripped
+ * static-musl binary is ~90% DWARF that nothing needs at runtime (12 MB down to
+ * ~1.3 MB for the kitchen-sink). `--musl` is what makes it a cross-compile; a
+ * host build omits it and Porffor targets the machine it runs on.
+ */
+export function porfforArgs(
+  generatedPath: string,
+  outPath: string,
+  target: CompileInput["target"],
+  optimize: CompileInput["optimize"],
+): string[] {
+  const args = ["native", generatedPath, "-o", outPath];
+  if (target !== "host") args.push("--musl");
+  args.push("-s");
+  // Porffor reads -O from its own argv and defaults to -O3. -O0 is roughly
+  // three times faster to compile, so dev takes it and everything else does
+  // not: a deployable artifact is never built with it.
+  if (optimize === "dev" && target === "host") args.push("-O0");
+  return args;
+}
+
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
 export async function compileSprout(input: CompileInput): Promise<void> {
   await ensurePorfforPatched();
 
   // Seed the Porffor uWebSockets cache from the prebuilt archive in `vendor/` so
-  // the first build needs no `git` / `make`. Fall back to Porffor's own git+make
-  // path if the archive is missing or fails its checksum.
+  // the first build needs no `git` / `make`. The two targets keep separate
+  // cache trees and separate uSockets.a, so seed whichever this build wants.
+  // Fall back to Porffor's own git+make path if the archive is unusable.
   try {
-    await ensureUWebSockets();
+    if (input.target === "host") await ensureUWebSocketsHost();
+    else await ensureUWebSockets();
   } catch (error) {
     if (!(error instanceof UwsUnavailableError)) throw error;
     const haveGit = Bun.which("git");
@@ -83,7 +162,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   const generatedPath = resolve(outDir, "sprout.generated.js");
   const [source, prelude] = await Promise.all([
     input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
-    readFile(preludePath, "utf8"),
+    loadPrelude(input.transport ?? "broker"),
   ]);
   await writeFile(
     generatedPath,
@@ -94,6 +173,8 @@ export async function compileSprout(input: CompileInput): Promise<void> {
       input.bindings ?? EMPTY_BINDINGS,
       undefined,
       input.compatibilityDate,
+      input.appName,
+      input.assets,
     ),
   );
 
@@ -105,15 +186,14 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   const zigDir = input.zigBin ? `${dirname(input.zigBin)}:` : "";
   const path = `${zigDir}${binDir}:${process.env.PATH ?? ""}`;
 
-  // `-s`: strip at link. The unstripped static-musl binary is ~90% DWARF that
-  // nothing needs at runtime (12 MB -> ~1.3 MB for the kitchen-sink). Porffor
-  // forwards `-s` straight to the `zig cc` link step.
-  // `--musl` is what makes it a cross-compile; a host build simply omits it and
-  // Porffor targets the machine it is running on.
-  const crossFlags = input.target === "host" ? [] : ["--musl"];
   const child = Bun.spawn(
-    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, ...crossFlags, "-s"],
-    { cwd: outDir, stdout: "pipe", stderr: "pipe", env: { ...process.env, PATH: path } },
+    [process.execPath, launcher, ...porfforArgs(generatedPath, input.outPath, input.target, input.optimize)],
+    {
+      cwd: outDir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: compileEnv(path, input.extraLink, input.extraCflags),
+    },
   );
   let timedOut = false;
   const timer = setTimeout(() => {

package/src/config.ts

@@ -58,6 +58,9 @@ export type SproutboatConfig = {
   analytics_engine_datasets?: string[];
   /** Durable Object bindings: `{ BINDING_NAME: "ClassName" }`. The class is defined in the handler module. */
   durable_objects?: Record<string, string>;
+  /** #48 — worker-to-worker calls: `env.<BINDING>.fetch(request)` reaches another
+   *  project on this control plane, resolved to its hostname at activation. */
+  services?: Array<{ binding: string; service: string }>;
   /** Scheduled triggers, e.g. `{ "crons": ["0 3 * * *"] }` — a `scheduled(event)` handler runs on each tick. */
   triggers?: { crons?: string[] };
   /** Static assets: a directory served edge-first (like Cloudflare), optionally bound as `env.<BINDING>.fetch(request)`. */
@@ -114,6 +117,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     "queues",
     "analytics_engine_datasets",
     "durable_objects",
+    "services",
     "triggers",
     "assets",
   ]);
@@ -233,6 +237,25 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     }
   }
 
+  let services: Array<{ binding: string; service: string }> | undefined;
+  if (value.services !== undefined) {
+    if (!Array.isArray(value.services)) {
+      errors.push('services must be an array of { binding: "NAME", service: "project-name" }');
+    } else {
+      services = [];
+      for (const entry of value.services) {
+        const row = isRecord(entry) ? entry : null;
+        const binding = row && isString(row.binding) ? row.binding : "";
+        const service = row && isString(row.service) ? row.service : "";
+        if (!bindingName.test(binding) || !isProjectSlug(service)) {
+          errors.push('services entries must be { binding: "UPPER_SNAKE", service: "project-name" }');
+        } else if (services.some((s) => s.binding === binding)) {
+          errors.push(`services: duplicate binding ${binding}`);
+        } else services.push({ binding, service });
+      }
+    }
+  }
+
   let triggers: { crons?: string[] } | undefined;
   if (value.triggers !== undefined) {
     if (!isRecord(value.triggers)) {
@@ -301,6 +324,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     ...resourceNames(queues),
     ...(analytics_engine_datasets ?? []),
     ...Object.keys(durable_objects ?? {}),
+    ...(services ?? []).map((entry) => entry.binding),
     ...Object.keys(vars ?? {}),
     ...(assets?.binding ? [assets.binding] : []),
   ];
@@ -319,6 +343,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   if ("queues" in value) config.queues = queues;
   if ("analytics_engine_datasets" in value) config.analytics_engine_datasets = analytics_engine_datasets;
   if ("durable_objects" in value) config.durable_objects = durable_objects;
+  if ("services" in value) config.services = services;
   if ("triggers" in value) config.triggers = triggers;
   if ("assets" in value) config.assets = assets;
   return { ok: true, value: config };

package/src/dev.ts

@@ -85,6 +85,8 @@ async function start(input: DevInput, source: string): Promise<Running> {
     sourcePath: input.sourcePath,
     source,
     target: "host",
+    // Never deployable, rebuilt on every edit: buy the iteration loop.
+    optimize: "dev",
   });
   const artifactDir = artifact.artifactDir;
   const sproutPath = resolve(artifactDir, "sprout");

package/src/main.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env bun
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, resolve } from "node:path";
+import { mkdir, open, readFile, rename, writeFile } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
 import { isBoolean, isSafeInteger, isString, jsonObject, parseJsonValue, type JsonObject } from "./json";
 import type { AssetFiles } from "./assets";
 import { parseConfig, pinBindingId, resourceRefs, type SproutboatConfig } from "./config";
 import { validateHttpSyncSource } from "./source";
 import { buildArtifact } 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 { hostTarget, validateManifest, type ArtifactManifest } from "./manifest";
 import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
@@ -230,6 +233,35 @@ async function check(directory?: string) {
   console.log(ok(`check passed — ${project.config.name} (${project.config.main}, native-fetch)`));
 }
 
+async function types(directory?: string) {
+  const project = await readProject(directory);
+  const path = resolve(project.directory, TYPES_FILE);
+  await writeFile(path, generateTypes(project.config));
+  console.log(ok(`wrote ${relative(process.cwd(), path) || TYPES_FILE}`));
+  console.log(dim("  Commit it. Add it to tsconfig `include` if your project has one."));
+}
+
+/**
+ * Rewrite the generated types when the config has moved on, and only then.
+ *
+ * Called from `dev` and `deploy` so a binding added to sproutboat.jsonc cannot
+ * sit unreflected in the editor. It writes only when the content actually
+ * differs, which keeps it out of the way of git and of file watchers.
+ */
+async function refreshTypes(projectDir: string, config: SproutboatConfig): Promise<void> {
+  const path = resolve(projectDir, TYPES_FILE);
+  const wanted = generateTypes(config);
+  try {
+    if ((await readFile(path, "utf8")) === wanted) return;
+  } catch {
+    // No file yet: only write one if the project already opted in by having a
+    // tsconfig. Generating into a plain JavaScript project is noise.
+    if (!(await Bun.file(resolve(projectDir, "tsconfig.json")).exists())) return;
+  }
+  await writeFile(path, wanted);
+  console.log(dim(`  ${TYPES_FILE} refreshed from sproutboat.jsonc`));
+}
+
 async function build(directory?: string, target: "linux-x86_64" | "host" = "linux-x86_64") {
   const project = await readProject(directory);
   console.log(
@@ -251,6 +283,32 @@ async function build(directory?: string, target: "linux-x86_64" | "host" = "linu
   return { project, artifact };
 }
 
+/**
+ * #15 — one executable carrying the sprout, its assets and its bindings.
+ *
+ * Defaults to a host build: the point is a binary you can run right here. Pass
+ * `--target linux-x86_64` for a box, but note the Bun launcher is compiled for
+ * *this* machine either way in phase 0 — cross-compiling both halves comes with
+ * the embedded backend, which removes the launcher entirely.
+ */
+async function buildStandaloneBinary(directory: string | undefined, target: "linux-x86_64" | "host") {
+  const project = await readProject(directory);
+  console.log(dim(`Building a standalone ${project.config.name} (${target})…`));
+  try {
+    const result = await buildStandalone({
+      projectDir: project.directory,
+      config: project.config,
+      sourcePath: project.sourcePath,
+      source: project.bundle.code,
+      target,
+    });
+    console.log(ok(`built ${result.outPath} (${(result.bytes / 1_000_000).toFixed(1)} MB)`));
+    console.log(dim(`  run it: ${result.outPath}   ·   state lands in ./${project.config.name}.data`));
+  } 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));
@@ -260,6 +318,7 @@ async function dev(args: string[]) {
   if (!Number.isSafeInteger(port) || port < 1 || port > 65_535)
     usageError(`invalid --port: ${portArg}`, "dev [project-dir] [--port <n>] [--no-watch]");
   const project = await readProject(directory);
+  await refreshTypes(project.directory, project.config);
   console.log(dim(`Building ${project.config.name} for this machine (${hostTarget()})…`));
   await runDev({
     projectDir: project.directory,
@@ -383,6 +442,8 @@ async function deploy(args: string[]) {
     projectName = built.project.config.name;
     artifactDir = built.artifact.artifactDir;
     config = built.project.config;
+    // After provisioning: ids may have been pinned into the config just now.
+    await refreshTypes(built.project.directory, built.project.config);
   }
   const manifest = Bun.file(resolve(artifactDir, "manifest.json"));
   const sprout = Bun.file(resolve(artifactDir, "sprout"));
@@ -870,6 +931,194 @@ async function storage(key: string, args: string[]) {
   console.log(ok(`deleted ${product.noun} ${name}`));
 }
 
+function option(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+async function writeAtomic(
+  path: string,
+  chunks: AsyncIterable<string> | readonly string[],
+  overwrite: boolean,
+): Promise<void> {
+  const destination = resolve(path);
+  if (!overwrite && (await Bun.file(destination).exists())) fail(`${path} already exists; pass --force to replace it`);
+  await mkdir(dirname(destination), { recursive: true });
+  const temporary = `${destination}.tmp-${process.pid}-${Date.now()}`;
+  const cleanup = () => {
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+      /* best effort during process shutdown */
+    }
+  };
+  process.once("exit", cleanup);
+  const file = await open(temporary, "wx", 0o600);
+  try {
+    for await (const chunk of chunks) await file.write(chunk);
+    await file.sync();
+    await file.close();
+    await rename(temporary, destination);
+    process.off("exit", cleanup);
+  } catch (error) {
+    await file.close().catch(() => undefined);
+    cleanup();
+    process.off("exit", cleanup);
+    throw error;
+  }
+}
+
+async function kvContents(args: string[]): Promise<void> {
+  const area = args.shift();
+  if (!area || !["key", "bulk", "export"].includes(area))
+    usageError("kv: unknown contents command", "kv <key | bulk | export> ...");
+  const namespace = area === "export" ? args.shift() : args[1];
+  if (!namespace) usageError(`kv ${area}: missing <namespace>`, `kv ${area} <namespace> ...`);
+  const { apiUrl, token } = await apiCredentials();
+  const rows = await storageRows(`${apiUrl}/api/kv`, { "x-api-key": token }, STORAGE_PRODUCTS[0]);
+  const id = idForName(rows, namespace, STORAGE_PRODUCTS[0]);
+  const base = `${apiUrl}/api/kv/${id}`;
+  const auth = { "x-api-key": token };
+
+  if (area === "key") {
+    const verb = args.shift();
+    args.shift();
+    if (!verb || !["list", "get", "put", "delete"].includes(verb))
+      usageError("kv key: unknown operation", "kv key <list | get | put | delete> <namespace> ...");
+    if (verb === "list") {
+      const query = new URLSearchParams();
+      for (const flag of ["--prefix", "--cursor", "--limit"] as const) {
+        const value = option(args, flag);
+        if (value !== undefined) query.set(flag.slice(2), value);
+      }
+      const body = await responseText(await fetch(`${base}/keys?${query}`, { headers: auth }), "list rejected");
+      console.log(body);
+      return;
+    }
+    const key = args.shift();
+    if (!key) usageError(`kv key ${verb}: missing <key>`, `kv key ${verb} <namespace> <key>`);
+    const url = `${base}/keys/${encodeURIComponent(key)}`;
+    if (verb === "get") {
+      const body = await responseText(await fetch(url, { headers: auth }), "get rejected");
+      const record = jsonObject(parseJsonValue(body));
+      if (!record || !isString(record.value)) fail("get response did not contain a value");
+      const output = option(args, "--output");
+      if (output) await writeAtomic(output, [record.value], args.includes("--force"));
+      else console.log(args.includes("--text") ? record.value : JSON.stringify({ key, value: record.value }, null, 2));
+      return;
+    }
+    if (verb === "put") {
+      const path = option(args, "--path");
+      const positional = args.find((arg, index) => !arg.startsWith("-") && args[index - 1] !== "--path");
+      if (path && positional)
+        usageError(
+          "kv key put: use a value or --path, not both",
+          "kv key put <namespace> <key> [value] [--path <file>]",
+        );
+      const value = path ? await readFile(resolve(path), "utf8") : (positional ?? (await Bun.stdin.text()));
+      await responseText(
+        await fetch(url, {
+          method: "PUT",
+          headers: { ...auth, "content-type": "application/json" },
+          body: JSON.stringify({ value }),
+        }),
+        "put rejected",
+      );
+      console.log(ok(`set ${key}`));
+      return;
+    }
+    if (!args.includes("--yes")) fail(`this permanently deletes "${key}"; re-run with --yes`);
+    await responseText(await fetch(url, { method: "DELETE", headers: auth }), "delete rejected");
+    console.log(ok(`deleted ${key}`));
+    return;
+  }
+
+  if (area === "bulk") {
+    const verb = args.shift();
+    args.shift();
+    const input = args.shift();
+    if (!verb || !["get", "put", "delete"].includes(verb) || !input)
+      usageError(
+        "kv bulk: expected an operation, namespace, and JSON file",
+        "kv bulk <get | put | delete> <namespace> <file>",
+      );
+    if (verb === "delete" && !args.includes("--yes")) fail("bulk deletion requires --yes");
+    const parsed = parseJsonValue(await readFile(resolve(input), "utf8"));
+    if (!Array.isArray(parsed) || parsed.length === 0) fail("bulk input must be a non-empty JSON array");
+    const responses: unknown[] = [];
+    let changed = 0;
+    const failures: unknown[] = [];
+    for (let start = 0; start < parsed.length; start += 100) {
+      const body = await responseText(
+        await fetch(`${base}/bulk/${verb}`, {
+          method: "POST",
+          headers: { ...auth, "content-type": "application/json" },
+          body: JSON.stringify(parsed.slice(start, start + 100)),
+        }),
+        `bulk ${verb} rejected`,
+      );
+      const result = parseJsonValue(body);
+      if (verb === "get" && Array.isArray(result)) responses.push(...result);
+      else {
+        const summary = jsonObject(result);
+        changed += Number(summary?.written ?? summary?.deleted ?? 0);
+        if (Array.isArray(summary?.failures)) failures.push(...summary.failures);
+      }
+    }
+    const result = verb === "get" ? responses : { [verb === "put" ? "written" : "deleted"]: changed, failures };
+    const output = option(args, "--output");
+    if (output) await writeAtomic(output, [JSON.stringify(result, null, 2) + "\n"], args.includes("--force"));
+    else console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const output = option(args, "--output");
+  if (!output)
+    usageError(
+      "kv export: missing --output <file>",
+      "kv export <namespace> --output <dump.json> [--prefix <prefix>] [--force]",
+    );
+  const prefix = option(args, "--prefix") ?? "";
+  async function* dump(): AsyncGenerator<string> {
+    yield "[\n";
+    let cursor = "";
+    let first = true;
+    do {
+      const query = new URLSearchParams({ prefix, limit: "100" });
+      if (cursor) query.set("cursor", cursor);
+      const listed = jsonObject(
+        parseJsonValue(
+          await responseText(await fetch(`${base}/keys?${query}`, { headers: auth }), "export list rejected"),
+        ),
+      );
+      const keys = Array.isArray(listed?.keys) ? listed.keys.filter(isString) : [];
+      if (keys.length) {
+        const values = parseJsonValue(
+          await responseText(
+            await fetch(`${base}/bulk/get`, {
+              method: "POST",
+              headers: { ...auth, "content-type": "application/json" },
+              body: JSON.stringify(keys),
+            }),
+            "export read rejected",
+          ),
+        );
+        if (!Array.isArray(values)) fail("export response was not an array");
+        for (const entry of values) {
+          const record = jsonObject(entry);
+          if (!record || !isString(record.key) || !isString(record.value)) continue;
+          yield `${first ? "" : ",\n"}  ${JSON.stringify({ key: record.key, value: record.value })}`;
+          first = false;
+        }
+      }
+      cursor = isString(listed?.cursor) ? listed.cursor : "";
+    } while (cursor);
+    yield "\n]\n";
+  }
+  await writeAtomic(output, dump(), args.includes("--force"));
+  console.log(ok(`exported ${namespace} to ${output}`));
+}
+
 async function deleteProject(args: string[]) {
   // `sproutboat delete [project-dir] [--name <project>] --yes` — flags in any order.
   const positional: string[] = [];
@@ -936,15 +1185,17 @@ switch (command) {
   case "check":
     await check(args[0]);
     break;
+  case "types":
+    await types(args[0]);
+    break;
   case "dev":
     await dev(args);
     break;
   case "build": {
     const hostBuild = args.includes("--target") && args[args.indexOf("--target") + 1] === "host";
-    await build(
-      args.find((arg) => !arg.startsWith("--") && arg !== "host"),
-      hostBuild ? "host" : "linux-x86_64",
-    );
+    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");
     break;
   }
   case "login":
@@ -972,6 +1223,9 @@ switch (command) {
     await secrets(args);
     break;
   case "kv":
+    if (["key", "bulk", "export"].includes(args[0] ?? "")) await kvContents(args);
+    else await storage(command, args);
+    break;
   case "d1":
   case "r2":
   case "queues":