sproutboat 0.4.10 → 0.5.0

package/README.md

@@ -1,13 +1,22 @@
 # sproutboat
 
-The CLI for [Sproutboat](https://github.com/baronunread/sproutboat) — a
-Wrangler-shaped tool for deploying workers to any Sproutboat control plane.
-MIT licensed.
+The CLI for [Sproutboat](https://github.com/baronunread/sproutboat). It is a
+Wrangler-shaped tool that compiles a `fetch` handler to a native binary and
+ships it to any Sproutboat control plane. MIT licensed.
+
+Full reference: [sproutboat.com/docs](https://sproutboat.com/docs)
+(plain text for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
 
 ```sh
-bunx sproutboat login --api-url https://control.example.com
 bunx sproutboat init hello
 cd hello
+bunx sproutboat dev        # runs it right here, no control plane needed
+```
+
+Happy with it? Ship it:
+
+```sh
+bunx sproutboat login --api-url https://control.example.com   # one browser approval
 bunx sproutboat deploy
 ```
 
@@ -19,7 +28,11 @@ bun add -g sproutboat     # then: sproutboat deploy, sproutboat tail, ...
 
 Want it shorter? Alias it yourself: `alias sprout='sproutboat'`.
 
-For CI, skip `login` and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN`.
+The `login` browser step is one-time. It writes a long-lived token to
+`~/.config/sproutboat/credentials.json`, keyed by API URL, so you can hold
+logins for several instances at once. For CI or an agent, skip `login`
+entirely and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN` (copy the token out
+of that file).
 
 ## Commands
 
@@ -27,20 +40,35 @@ For CI, skip `login` and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN`.
 | --- | --- |
 | `init [name]` | Scaffold `sproutboat.jsonc` + `src/index.js` |
 | `check` | Validate the config and entry point |
-| `build` | Cross-compile the worker artifact |
-| `deploy [--dry-run] [--artifact <dir>]` | Build and upload (`--dry-run` prints the report only) |
-| `login [--api-url <url>] [--token <token>]` | Browser device flow, or store a token |
-| `tail [name]` | Recent logs |
-| `versions list [name]` | Deployed versions |
+| `dev [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save |
+| `build [--target host]` | Cross-compile the sprout binary (Porffor + Zig); `--target host` builds for this machine instead, for `dev` — not deployable |
+| `deploy [--dry-run] [--no-wait] [--no-provision] [--artifact <dir>]` | Build, auto-provision id-less storage bindings, upload, wait until the URL serves |
+| `login [--api-url <url>] [--token <token>]` | Browser device flow, or store a token directly |
+| `tail [name] [--sprout]` | Recent request logs; `--sprout` streams the running sprout + broker output |
+| `versions <list \| view <id>>` | Deployed versions, or one version's artifact and bindings |
 | `rollback <id>` | Activate a previous version |
-| `delete --yes` | Delete the project |
-
-Credentials are keyed by API URL in `~/.config/sproutboat/credentials.json`, so
-you can hold logins for several instances at once.
+| `logout [--api-url <url>]` | Forget the stored credential |
+| `whoami` | Active endpoint and the account the token belongs to |
+| `kv <list \| create \| info \| rename \| delete>` | KV namespaces |
+| `d1 <list \| create \| info \| rename \| delete>` | D1 databases |
+| `r2 <list \| create \| info \| rename \| delete>` | R2 buckets |
+| `queues <list \| create \| info \| rename \| delete>` | Queues |
+| `secrets <list \| put <NAME> [--value <v>] \| delete <NAME>>` | Encrypted project secrets, read as `env.NAME` |
+| `domains <list \| add <host> \| verify <host> \| delete <host>>` | Attach your own hostname (TXT + A, apex allowed) |
+| `delete --yes` | Delete the project, every version, and its route |
+
+Each storage product is its own command with the same five verbs. Wrangler nests
+two of its four (`kv namespace create`, `r2 bucket create`) and leaves the other
+two flat; the nesting separates a container from its contents, which the verb
+already does, so ours are uniform. Contents get their own noun when they arrive
+(`kv key get`, `r2 object put`).
+
+Run `sproutboat` with no arguments for the grouped list.
+[`SURFACE.md`](SURFACE.md) is the generated inventory of every command and env var.
 
 ## Config
 
-`sproutboat.jsonc` — the entry point plus Cloudflare-shaped `env.*` bindings:
+`sproutboat.jsonc`: the entry point plus Cloudflare-shaped `env.*` bindings.
 
 ```jsonc
 {
@@ -50,42 +78,66 @@ you can hold logins for several instances at once.
 
   "vars": { "SITE": "hi" },
   "secrets": ["API_KEY"],
-  "kv_namespaces": ["CACHE"],
+  "kv_namespaces": ["CACHE"],                 // bare name, or { "binding": "CACHE", "id": "kv_..." }
   "d1_databases": ["DB"],
   "r2_buckets": ["UPLOADS"],
   "queues": ["JOBS"],
-  "analytics_engine_datasets": ["METRICS"],
+  "analytics_engine_datasets": ["METRICS"],   // bare name only, no id
   "durable_objects": { "COUNTER": "Counter" },
   "outbound": ["api.example.com"],
   "triggers": { "crons": ["*/5 * * * *"] },
-  "assets": { "directory": "public", "binding": "ASSETS" }
+  "assets": { "directory": "public", "binding": "ASSETS", "run_sprout_first": ["/api/*"] }
 }
 ```
 
-The handler is one `export default { fetch }`, optionally with `scheduled` /
-`queue` handlers and exported Durable Object classes. See
-[`examples/kitchen-sink/`](examples/kitchen-sink) for one app that uses every
-binding, with an Astro UI and a runnable end-to-end harness.
+A bare `"CACHE"` binding is auto-provisioned on `deploy`: the CLI creates an
+account-level resource, writes its id back into `sproutboat.jsonc`, and the
+store then survives redeploys. Pass `--no-provision` to keep it a throwaway
+per-deploy store instead, or `sproutboat kv create <name>` (or `d1`/`r2`/`queues`) to make one up front
+and share its id across projects.
+
+The handler is `export default { fetch(request) }`; it may import from other
+files in the project and from its own `node_modules`, and optionally export
+`scheduled(event)` / `queue(batch)` handlers and Durable Object classes.
+`env` is a global (not a parameter), and every binding call is synchronous.
+See [`examples/kitchen-sink/`](examples/kitchen-sink) for one app that uses
+every binding.
+
+`sproutboat dev` runs against a real local broker, so bindings behave like
+production without a deploy — except `secrets`, which live only in the
+control plane. Give it a value with a `.dev.vars` file next to
+`sproutboat.jsonc` (`API_KEY=whatever`, one per line, gitignore it):
+`env.API_KEY` then resolves to that value under `dev` only.
 
 ## Requirements
 
 - [Bun](https://bun.sh) 1.4+
 
 `build` / `deploy` cross-compile the handler to a static `linux-x86_64` binary
-with Porffor and Zig (Zig is fetched automatically on first use). The package
-ships a prebuilt uWebSockets, so nothing else is compiled from source. No Docker,
-no root. On Windows, build from WSL.
+with Porffor and Zig (the CLI fetches Zig automatically on first use). The
+package ships a prebuilt uWebSockets and compiles nothing else from source. No
+Docker, no root. On Windows, build from WSL.
 
 If that prebuilt is unusable (a `porffor` pin bump before the archive is
 refreshed), the first build falls back to compiling uWebSockets locally, which
 needs `git` and `make` on `PATH`. `SPROUTBOAT_UWS_TARBALL=<archive>` overrides
 the shipped one.
 
-## Limits (v1)
-
-Binding values are text/JSON and travel one at a time over a loopback frame; an
-upload is capped at 1 MiB by the worker's HTTP server (large-object R2 is
-[#56](https://github.com/baronunread/sproutboat/issues/56)). No WebSockets yet.
+## Limits
+
+Capability profile `http-sync-v0`: one synchronous `fetch` handler, optional
+`scheduled` / `queue` handlers, no streaming, no WebSockets. Binding values are
+text/JSON and travel one at a time over the loopback frame (32 MiB cap);
+large-object R2 is [#56](https://github.com/baronunread/sproutboat/issues/56).
+The sprout upload caps at 16 MiB, assets at 64 MiB / 4096 files. The entry
+point is bundled before it compiles, so relative imports and npm dependencies
+from the project's own `node_modules` work; CommonJS `require`, dynamic
+`import()`, and any `process`/`Bun`/`Deno`/`node:*` reached even through a
+dependency do not. `new Proxy(...)` compiles but its traps are silently
+ignored by Porffor alpha, so it's rejected too. A parsed `Date` with a numeric
+timezone offset (`+02:00`) currently comes out wrong; plain ISO-8601 UTC
+strings are fine. `sproutboat check` catches most of this before a build.
+Full list at [sproutboat.com/docs](https://sproutboat.com/docs).
 
 ---
 

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.4.10 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.5.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -11,19 +11,25 @@
 | --- | --- | --- |
 | `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
-| `build` | `[project-dir]` | Cross-compile the native-fetch sprout (Porffor + Zig). |
+| `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]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. |
 | `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 [project-dir]` | List the project's deployed versions. |
+| `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
 | `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
-| `domains` | `[list | add <host> | verify <host> | rm <host>] [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
-| `secrets` | `[list | set <NAME> [value] | rm <NAME>] [project-dir]` | Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy. |
-| `resource` | `[list [kind] | create <kind> <name> | rename <id> <name> | delete <id>]` | Manage account-level storage resources (kv | d1 | r2 | queue). `create` prints the id to reference from sproutboat.jsonc bindings. |
+| `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc. |
+| `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | D1 databases. `create` prints the id to bind from sproutboat.jsonc. |
+| `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc. |
+| `queues` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | Queues. `create` prints the id to bind from sproutboat.jsonc; consumers are not implemented yet. |
+| `domains` | `<list | add <host> | verify <host> | delete <host>> [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
+| `secrets` | `<list | put <NAME> [--value <value>] | delete <NAME>> [project-dir]` | Manage encrypted project secrets (read as env.NAME). `put` reads the value from stdin unless --value is given, so it stays out of shell history; applies on next deploy. |
 | `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
 | `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
+| `logout` | `[--api-url <url>]` | Forget the stored credential for the active endpoint, or for <url>. |
+| `whoami` | — | Show the active endpoint and the account the stored token belongs to. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions list [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | resource [list [kind] | create <kind> <name> | rename <id> <name> | delete <id>] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>]>
+usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] | 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>> | 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>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
     "test": "bun test",
     "example:kitchen-sink": "bun examples/kitchen-sink/harness.ts",
     "surface": "UPDATE_SURFACE=1 bun test src/surface.test.ts",
@@ -55,7 +56,9 @@
     "porffor": "github:CanadaHonk/porffor#alpha-4"
   },
   "devDependencies": {
+    "@oxlint/plugins": "1.81.0",
     "@types/bun": "1.4.0",
+    "oxlint": "1.81.0",
     "typescript": "5.9.2"
   }
 }

package/src/broker.ts

@@ -23,6 +23,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, normalize, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { resolveAssetKey, type AssetManifest } from "./assets";
+import { isBoolean, isString, jsonObject, parseJsonValue, type JsonObject, type JsonValue } from "./json";
 
 export type Bindings = {
   kv: string[];
@@ -44,7 +45,12 @@ export type Bindings = {
    */
   resources: Record<string, { kind: "kv" | "d1" | "r2" | "queue"; id: string }>;
 };
-export type Frame = Record<string, unknown>;
+/** One decoded wire frame. `undefined` fields are dropped by `JSON.stringify`, so
+ *  an optional reply field can be left off without a second object shape. */
+export type Frame = { [key: string]: JsonValue | undefined };
+
+/** The only shape of `fetch` the broker calls — the global `fetch` satisfies it. */
+export type FetchLike = (input: URL | string, init?: RequestInit) => Promise<Response>;
 
 export type BrokerOptions = {
   db?: string;
@@ -69,21 +75,24 @@ export type BrokerOptions = {
   /** Directory of published static assets (its sibling `assets.json` is the manifest). Backs `assets.get`. */
   assetsDir?: string;
   /** Injected in tests; defaults to the global `fetch`. */
-  fetchImpl?: typeof fetch;
+  fetchImpl?: FetchLike;
 };
 
 type SqlParam = string | number | null;
+/** The `{ results, meta }` shape Cloudflare's D1 client expects back per statement. */
+type D1Result = { results: JsonValue[]; meta: { duration: number; changes: number; last_row_id: number; rows_read: number } };
 type R2Row = { key: string; body: string; size: number; etag: string; uploaded: string; http_json: string; custom_json: string };
-const sqlParams = (v: unknown): SqlParam[] => {
+const isNumber = (v: JsonValue | undefined): v is number => Number.isFinite(v);
+const sqlParams = (v: JsonValue | undefined): SqlParam[] => {
   if (!Array.isArray(v)) return [];
-  return v.map((p) => (p === null || typeof p === "number" || typeof p === "string" ? p : typeof p === "boolean" ? (p ? 1 : 0) : String(p)));
+  return v.map((p) => (p === null || isNumber(p) || isString(p) ? p : isBoolean(p) ? (p ? 1 : 0) : String(p)));
 };
 
 // One binding call = one frame, and an R2/KV value travels inside it as a JSON
 // string (escaping can inflate binary content several ×). 32 MiB keeps a ~25 MB
 // upload working; true large-object streaming is v2.
 const MAX_FRAME = 32 * 1024 * 1024;
-const str = (v: unknown): string => (typeof v === "string" ? v : String(v ?? ""));
+const str = (v: JsonValue | undefined): string => (isString(v) ? v : String(v ?? ""));
 
 export type Broker = {
   /** Run one parsed request object through the op dispatch. */
@@ -103,7 +112,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   let assetManifest: AssetManifest | null = null;
   if (assetsDir) {
     const manifestPath = join(dirname(assetsDir), "assets.json");
-    if (existsSync(manifestPath)) assetManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as AssetManifest;
+    if (existsSync(manifestPath)) {
+      // SAFETY: assets.json sits beside the published assets dir and is written
+      // only by `sproutboat build` from the AssetManifest contract.
+      assetManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as AssetManifest;
+    }
   }
   const readAsset = (path: string): { type: string; hash: string; body: string } | null => {
     if (!assetsDir || !assetManifest) return null;
@@ -200,7 +213,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     return stmts;
   };
 
-  const bound = (list: string[], kind: string) => (name: unknown): string => {
+  const bound = (list: string[], kind: string) => (name: JsonValue | undefined): string => {
     const n = str(name);
     if (!list.includes(n)) throw new Error(`${kind} not bound: ${n}`);
     return n;
@@ -211,7 +224,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const requireQueue = bound(bindings.queues, "queue");
   const requireAe = bound(bindings.analytics, "analytics dataset");
   const doClasses = new Set(bindings.do.map((d) => d.className));
-  const requireDoClass = (cls: unknown): string => {
+  const requireDoClass = (cls: JsonValue | undefined): string => {
     const n = str(cls);
     if (!doClasses.has(n)) throw new Error(`Durable Object class not bound: ${n}`);
     return n;
@@ -239,9 +252,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   };
 
   // Run one statement, return CF-D1-shaped { results, meta }.
-  const d1Run = (conn: Database, sql: string, params: SqlParam[]): { results: unknown[]; meta: Record<string, unknown> } => {
+  const d1Run = (conn: Database, sql: string, params: SqlParam[]): D1Result => {
     const started = performance.now();
-    const results = conn.query(sql).all(...params);
+    // SQLite hands back column->(string|number|null|blob) rows, i.e. a JSON object.
+    const results = conn.query<JsonObject, SqlParam[]>(sql).all(...params);
     const m = conn.query<{ changes: number; last_row_id: number }, []>(
       "SELECT changes() AS changes, last_insert_rowid() AS last_row_id",
     ).get();
@@ -256,8 +270,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     size: r.size,
     etag: r.etag,
     uploaded: r.uploaded,
-    httpMetadata: JSON.parse(r.http_json) as unknown,
-    customMetadata: JSON.parse(r.custom_json) as unknown,
+    httpMetadata: parseJsonValue(r.http_json),
+    customMetadata: parseJsonValue(r.custom_json),
   });
 
   async function proxyFetch(msg: Frame): Promise<Frame> {
@@ -272,7 +286,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
 
     const headers = new Headers();
     if (Array.isArray(msg.headers)) {
-      for (const pair of msg.headers as unknown[]) {
+      for (const pair of msg.headers) {
         if (Array.isArray(pair) && pair.length === 2) headers.set(str(pair[0]), str(pair[1]));
       }
     }
@@ -326,7 +340,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "d1.batch": {
         const conn = d1(requireD1(msg.db));
-        const stmts = Array.isArray(msg.statements) ? (msg.statements as Frame[]) : [];
+        const stmts = Array.isArray(msg.statements) ? msg.statements.map((s) => jsonObject(s) ?? {}) : [];
         const runAll = conn.transaction(() => stmts.map((s) => d1Run(conn, str(s.sql), sqlParams(s.params))));
         return { ok: true, results: runAll() };
       }
@@ -393,7 +407,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "queue.send_batch": {
         const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
-        const msgs = Array.isArray(msg.messages) ? (msg.messages as Frame[]) : [];
+        const msgs = Array.isArray(msg.messages) ? msg.messages.map((m) => jsonObject(m) ?? {}) : [];
         const ins = store.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)");
         store.transaction(() => {
           for (const m of msgs) ins.run(q, newId(), str(m.body), Date.now() + Math.max(0, Number(m.delaySeconds) || 0) * 1000);
@@ -426,9 +440,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
           count: total?.n ?? 0,
           rows: rows.map((r) => ({
             timestamp: r.ts,
-            indexes: JSON.parse(r.indexes_json) as unknown,
-            blobs: JSON.parse(r.blobs_json) as unknown,
-            doubles: JSON.parse(r.doubles_json) as unknown,
+            indexes: parseJsonValue(r.indexes_json),
+            blobs: parseJsonValue(r.blobs_json),
+            doubles: parseJsonValue(r.doubles_json),
           })),
         };
       }
@@ -493,7 +507,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     const json = nl === -1 ? payload : payload.slice(nl + 1);
     if (token && gotToken !== token) return { ok: false, error: "unauthorized" };
     try {
-      return await dispatch(JSON.parse(json) as Frame);
+      const msg = jsonObject(parseJsonValue(json));
+      if (!msg) throw new Error("request frame was not a JSON object");
+      return await dispatch(msg);
     } catch (e) {
       return { ok: false, error: e instanceof Error ? e.message : String(e) };
     }
@@ -504,7 +520,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const QUEUE_BATCH = 10;
   const QUEUE_MAX_ATTEMPTS = 5;
 
-  async function deliverTrigger(kind: "scheduled" | "queue", body: unknown): Promise<Response | null> {
+  async function deliverTrigger(kind: "scheduled" | "queue", body: JsonObject): Promise<Response | null> {
     if (!opts.sproutUrl) return null;
     try {
       return await doFetch(opts.sproutUrl, {
@@ -541,9 +557,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         let retry: string[] = [];
         if (res && res.ok) {
           try {
-            const parsed = (await res.json()) as { ack?: string[]; retry?: string[] };
-            ack = Array.isArray(parsed.ack) ? parsed.ack : ack;
-            retry = Array.isArray(parsed.retry) ? parsed.retry : [];
+            const parsed = jsonObject(parseJsonValue(await res.text()));
+            const ids = (value: JsonValue | undefined) => (Array.isArray(value) ? value.filter(isString) : null);
+            ack = (parsed && ids(parsed.ack)) ?? ack;
+            retry = (parsed && ids(parsed.retry)) ?? [];
           } catch { /* keep defaults */ }
         } else {
           ack = []; retry = rows.map((r) => r.id); // delivery failed → retry all
@@ -614,8 +631,11 @@ export function encodeFrame(obj: Frame): Buffer {
   return frame;
 }
 
+/** The bound TCP listener: the port actually assigned, and its shutdown handle. */
+export type BrokerServer = { port: number; stop(): void };
+
 /** Start the TCP listener. Returns the bound port. */
-export function listen(broker: Broker, hostname: string, port: number): { port: number; stop(): void } {
+export function listen(broker: Broker, hostname: string, port: number): BrokerServer {
   const server = Bun.listen<{ buf: Buffer }>({
     hostname,
     port,
@@ -659,9 +679,12 @@ if (import.meta.main) {
       "assets-dir": { type: "string" },
     },
   });
+  // SAFETY: --bindings and --secrets are the artifact's own bindings.json /
+  // secrets.json, written by `sproutboat build` and handed to us by the supervisor.
   const bindings: Partial<Bindings> | undefined = values.bindings
     ? (JSON.parse(readFileSync(values.bindings, "utf8")) as Partial<Bindings>)
     : undefined;
+  // SAFETY: as above — secrets.json is a flat name->value map written by the build.
   const secrets: Record<string, string> | undefined = values.secrets
     ? (JSON.parse(readFileSync(values.secrets, "utf8")) as Record<string, string>)
     : undefined;

package/src/build.ts

@@ -4,13 +4,25 @@ import { resolve } from "node:path";
 import { walkAssets, type AssetManifest } from "./assets";
 import { resourceRefs, type SproutboatConfig } from "./config";
 import { compileSprout } from "./compile";
-import { ARTIFACT_SCHEMA_VERSION, CAPABILITY_PROFILE, RUNTIME, type ArtifactManifest } from "./manifest";
+import { ARTIFACT_SCHEMA_VERSION, CAPABILITY_PROFILE, DEPLOY_TARGET, hostTarget, RUNTIME, type ArtifactManifest } from "./manifest";
 import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
 
 export type BuildInput = {
   projectDir: string;
   config: SproutboatConfig;
   sourcePath: string;
+  /**
+   * The bundled module (#89). When present this is what gets hashed and
+   * compiled, so the artifact tracks every imported file rather than just the
+   * entry point — change a dependency, get a different version.
+   */
+  source?: string;
+  /**
+   * `host` (#62) compiles for this machine instead of cross-compiling for a
+   * box, so `sproutboat dev` can run the sprout locally. The manifest records
+   * the real target, which is what stops the result being deployed.
+   */
+  target?: "linux-x86_64" | "host";
 };
 
 export type BuildOutput = {
@@ -29,7 +41,7 @@ function digest(value: Uint8Array | string): `sha256:${string}` {
  * does not come up.
  */
 export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
-  const source = await readFile(input.sourcePath);
+  const source = input.source ?? await readFile(input.sourcePath);
   const sourceHash = digest(source);
   const artifactId = sourceHash.slice("sha256:".length, 24);
   const artifactDir = resolve(input.projectDir, ".sproutboat/dist", artifactId);
@@ -63,20 +75,25 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     resources,
   };
 
-  const zigBin = await ensureZig();
+  // A host build never shells out to `zig`, so do not fetch a 50 MB toolchain
+  // for it — that download is the slowest part of a first local build.
+  const host = input.target === "host";
+  const zigBin = host ? undefined : await ensureZig();
   await compileSprout({
     sourcePath: input.sourcePath,
+    source: input.source,
     outPath: sproutPath,
     vars: input.config.vars ?? {},
     bindings,
     zigBin,
+    target: input.target,
   });
 
   const sprout = await readFile(sproutPath);
   const manifest: ArtifactManifest = {
     schemaVersion: ARTIFACT_SCHEMA_VERSION,
     project: input.config.name,
-    target: "linux-x86_64",
+    target: host ? hostTarget() : DEPLOY_TARGET,
     runtime: RUNTIME,
     capabilityProfile: CAPABILITY_PROFILE,
     porfforVersion: porfforVersion(),

package/src/bundle.ts

@@ -0,0 +1,69 @@
+/**
+ * #89 — bundle the handler before Porffor sees it.
+ *
+ * Porffor compiles one self-contained module, so until now a project was one
+ * file with no imports: no router, no validation library, no SDK, no splitting
+ * a codebase in two. Bundling first lifts that without touching the compiler.
+ *
+ * Bun's bundler resolves relative imports across the project and bare
+ * specifiers out of the project's own `node_modules`, then emits a single ESM
+ * module. The capability bans (`process`, `Bun`, `node:`, WebSocket, …) are
+ * checked against that output rather than the entry file, so a dependency
+ * reaching for a Node API fails exactly as user code would.
+ */
+import { relative } from "node:path";
+
+export type BundleResult = {
+  /** One self-contained ESM module: what gets validated, hashed, and compiled. */
+  code: string;
+};
+
+export class BundleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BundleError";
+  }
+}
+
+const entryLabel = (entryPath: string, projectDir: string): string => relative(projectDir, entryPath) || entryPath;
+
+/** Bun reports resolution failures on `AggregateError.errors`; its own message is just "Bundle failed". */
+function bundleDetail(cause: unknown): string {
+  const errors = cause instanceof AggregateError ? cause.errors : [];
+  if (errors.length > 0) return errors.map((error) => `  ${error instanceof Error ? error.message : String(error)}`).join("\n");
+  return `  ${cause instanceof Error ? cause.message : String(cause)}`;
+}
+
+/** Bundle `entryPath` into a single module, resolving imports from `projectDir`. */
+export async function bundleHandler(entryPath: string, projectDir: string): Promise<BundleResult> {
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [entryPath],
+      root: projectDir,
+      // `browser` keeps the output free of Node shims — a dependency that wants
+      // `process` must fail the capability check, not get a polyfill smuggled in.
+      target: "browser",
+      format: "esm",
+      // Readability over size: a compile error from Porffor should point at
+      // something a human can find, and Porffor strips the binary anyway.
+      minify: false,
+      splitting: false,
+      sourcemap: "none",
+    });
+  } catch (cause) {
+    // An unresolvable specifier arrives as an AggregateError whose `errors`
+    // carry the useful part ("Could not resolve: ./missing.js"); the top-level
+    // message is only "Bundle failed", which tells nobody which import broke.
+    throw new BundleError(`could not bundle ${entryLabel(entryPath, projectDir)}:\n${bundleDetail(cause)}`);
+  }
+
+  if (!built.success) {
+    const detail = built.logs.map((log) => `  ${log.message}`).join("\n");
+    throw new BundleError(`could not bundle ${entryLabel(entryPath, projectDir)}:\n${detail}`);
+  }
+  const [output] = built.outputs;
+  if (output === undefined) throw new BundleError("the bundler produced no output");
+
+  return { code: await output.text() };
+}