sproutboat 0.4.11 → 0.6.0

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,35 @@ 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;
-type R2Row = { key: string; body: string; size: number; etag: string; uploaded: string; http_json: string; custom_json: string };
-const sqlParams = (v: unknown): SqlParam[] => {
+/** 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 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. */
@@ -94,7 +114,20 @@ export type Broker = {
 };
 
 export function createBroker(opts: BrokerOptions = {}): Broker {
-  const bindings: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "", resources: {}, ...opts.bindings };
+  const bindings: Bindings = {
+    kv: [],
+    secrets: [],
+    outbound: [],
+    d1: [],
+    r2: [],
+    queues: [],
+    analytics: [],
+    do: [],
+    crons: [],
+    assets: "",
+    resources: {},
+    ...opts.bindings,
+  };
   const secrets = opts.secrets ?? {};
 
   // Static assets: read the manifest once. Files are read from disk per request
@@ -103,7 +136,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;
@@ -130,7 +167,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     const conn = new Database(path, { create: true });
     conn.exec("PRAGMA journal_mode = WAL");
     conn.exec("PRAGMA synchronous = NORMAL");
-    conn.exec("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))");
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))",
+    );
     conn.exec(
       "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, body TEXT NOT NULL, size INTEGER NOT NULL, " +
         "etag TEXT NOT NULL, uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
@@ -191,27 +230,33 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     if (!stmts) {
       stmts = {
         get: store.query<{ value: string }, [string, string]>("SELECT value FROM kv WHERE ns = ? AND key = ?"),
-        put: store.query("INSERT INTO kv (ns, key, value) VALUES (?1, ?2, ?3) ON CONFLICT (ns, key) DO UPDATE SET value = ?3"),
+        put: store.query(
+          "INSERT INTO kv (ns, key, value) VALUES (?1, ?2, ?3) ON CONFLICT (ns, key) DO UPDATE SET value = ?3",
+        ),
         del: store.query("DELETE FROM kv WHERE ns = ? AND key = ?"),
-        list: store.query<{ key: string }, [string, string]>("SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' ORDER BY key LIMIT 1000"),
+        list: store.query<{ key: string }, [string, string]>(
+          "SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' ORDER BY key LIMIT 1000",
+        ),
       };
       kvStmtCache.set(store, stmts);
     }
     return stmts;
   };
 
-  const bound = (list: string[], kind: string) => (name: unknown): string => {
-    const n = str(name);
-    if (!list.includes(n)) throw new Error(`${kind} not bound: ${n}`);
-    return n;
-  };
+  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;
+    };
   const requireKv = bound(bindings.kv, "KV namespace");
   const requireD1 = bound(bindings.d1, "D1 database");
   const requireR2 = bound(bindings.r2, "R2 bucket");
   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,15 +284,23 @@ 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);
-    const m = conn.query<{ changes: number; last_row_id: number }, []>(
-      "SELECT changes() AS changes, last_insert_rowid() AS last_row_id",
-    ).get();
+    // 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();
     return {
       results,
-      meta: { duration: performance.now() - started, changes: m?.changes ?? 0, last_row_id: m?.last_row_id ?? 0, rows_read: results.length },
+      meta: {
+        duration: performance.now() - started,
+        changes: m?.changes ?? 0,
+        last_row_id: m?.last_row_id ?? 0,
+        rows_read: results.length,
+      },
     };
   };
 
@@ -256,8 +309,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 +325,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]));
       }
     }
@@ -309,7 +362,12 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "kv.list": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
-        return { ok: true, keys: kvStmts(store).list.all(part, str(msg.prefix)).map((r) => r.key) };
+        return {
+          ok: true,
+          keys: kvStmts(store)
+            .list.all(part, str(msg.prefix))
+            .map((r) => r.key),
+        };
       }
       case "secret.get": {
         const name = str(msg.name);
@@ -326,7 +384,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() };
       }
@@ -340,25 +398,32 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
         const body = str(msg.body);
         const etag = createHash("sha256").update(body).digest("hex");
-        store.query(
-          "INSERT INTO r2 (bucket, key, body, size, etag, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
-            "ON CONFLICT (bucket, key) DO UPDATE SET body=?3, size=?4, etag=?5, uploaded=?6, http_json=?7, custom_json=?8",
-        ).run(
-          bucket,
-          str(msg.key),
-          body,
-          Buffer.byteLength(body),
-          etag,
-          new Date().toISOString(),
-          JSON.stringify(msg.httpMetadata ?? {}),
-          JSON.stringify(msg.customMetadata ?? {}),
-        );
-        return { ok: true, object: { key: str(msg.key), size: Buffer.byteLength(body), etag, uploaded: new Date().toISOString() } };
+        store
+          .query(
+            "INSERT INTO r2 (bucket, key, body, size, etag, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
+              "ON CONFLICT (bucket, key) DO UPDATE SET body=?3, size=?4, etag=?5, uploaded=?6, http_json=?7, custom_json=?8",
+          )
+          .run(
+            bucket,
+            str(msg.key),
+            body,
+            Buffer.byteLength(body),
+            etag,
+            new Date().toISOString(),
+            JSON.stringify(msg.httpMetadata ?? {}),
+            JSON.stringify(msg.customMetadata ?? {}),
+          );
+        return {
+          ok: true,
+          object: { key: str(msg.key), size: Buffer.byteLength(body), etag, uploaded: new Date().toISOString() },
+        };
       }
       case "r2.get":
       case "r2.head": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
-        const row = store.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, str(msg.key));
+        const row = store
+          .query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?")
+          .get(bucket, str(msg.key));
         if (!row) return { ok: true, found: false };
         return { ok: true, found: true, object: r2Row(row), body: msg.op === "r2.get" ? row.body : undefined };
       }
@@ -372,9 +437,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const prefix = str(msg.prefix);
         const cursor = str(msg.cursor);
         const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 1000);
-        const rows = store.query<R2Row, [string, string, string, number]>(
-          "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT ?",
-        ).all(bucket, prefix, cursor, limit + 1);
+        const rows = store
+          .query<R2Row, [string, string, string, number]>(
+            "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT ?",
+          )
+          .all(bucket, prefix, cursor, limit + 1);
         const truncated = rows.length > limit;
         const page = truncated ? rows.slice(0, limit) : rows;
         return {
@@ -388,15 +455,18 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       case "queue.send": {
         const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
         const at = Date.now() + Math.max(0, Number(msg.delaySeconds) || 0) * 1000;
-        store.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)").run(q, newId(), str(msg.body), at);
+        store
+          .query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)")
+          .run(q, newId(), str(msg.body), at);
         return { ok: true };
       }
       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);
+          for (const m of msgs)
+            ins.run(q, newId(), str(m.body), Date.now() + Math.max(0, Number(m.delaySeconds) || 0) * 1000);
         })();
         return { ok: true, count: msgs.length };
       }
@@ -417,27 +487,31 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         // query it via the SQL API). Exposed here so a dashboard can read back.
         const ds = requireAe(msg.dataset);
         const limit = Math.min(Math.max(Number(msg.limit) || 20, 1), 200);
-        const rows = db.query<{ ts: number; indexes_json: string; blobs_json: string; doubles_json: string }, [string, number]>(
-          "SELECT ts, indexes_json, blobs_json, doubles_json FROM ae WHERE dataset = ? ORDER BY ts DESC, rowid DESC LIMIT ?",
-        ).all(ds, limit);
+        const rows = db
+          .query<{ ts: number; indexes_json: string; blobs_json: string; doubles_json: string }, [string, number]>(
+            "SELECT ts, indexes_json, blobs_json, doubles_json FROM ae WHERE dataset = ? ORDER BY ts DESC, rowid DESC LIMIT ?",
+          )
+          .all(ds, limit);
         const total = db.query<{ n: number }, [string]>("SELECT count(*) AS n FROM ae WHERE dataset = ?").get(ds);
         return {
           ok: true,
           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),
           })),
         };
       }
 
       case "do.storage.get": {
         const cls = requireDoClass(msg.cls);
-        const row = db.query<{ value: string }, [string, string, string]>(
-          "SELECT value FROM do_storage WHERE cls = ? AND id = ? AND key = ?",
-        ).get(cls, str(msg.id), str(msg.key));
+        const row = db
+          .query<{ value: string }, [string, string, string]>(
+            "SELECT value FROM do_storage WHERE cls = ? AND id = ? AND key = ?",
+          )
+          .get(cls, str(msg.id), str(msg.key));
         return row ? { ok: true, found: true, value: row.value } : { ok: true, found: false };
       }
       case "do.storage.put":
@@ -447,9 +521,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         ).run(requireDoClass(msg.cls), str(msg.id), str(msg.key), str(msg.value));
         return { ok: true };
       case "do.storage.delete": {
-        const r = db.query("DELETE FROM do_storage WHERE cls = ? AND id = ? AND key = ?").run(
-          requireDoClass(msg.cls), str(msg.id), str(msg.key),
-        );
+        const r = db
+          .query("DELETE FROM do_storage WHERE cls = ? AND id = ? AND key = ?")
+          .run(requireDoClass(msg.cls), str(msg.id), str(msg.key));
         return { ok: true, deleted: r.changes > 0 };
       }
       case "do.storage.delete_all":
@@ -458,9 +532,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       case "do.storage.list": {
         const cls = requireDoClass(msg.cls);
         const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 10000);
-        const rows = db.query<{ key: string; value: string }, [string, string, string, number]>(
-          "SELECT key, value FROM do_storage WHERE cls = ? AND id = ? AND key LIKE ? || '%' ORDER BY key LIMIT ?",
-        ).all(cls, str(msg.id), str(msg.prefix), limit);
+        const rows = db
+          .query<{ key: string; value: string }, [string, string, string, number]>(
+            "SELECT key, value FROM do_storage WHERE cls = ? AND id = ? AND key LIKE ? || '%' ORDER BY key LIMIT ?",
+          )
+          .all(cls, str(msg.id), str(msg.prefix), limit);
         return { ok: true, entries: rows.map((r) => [r.key, r.value]) };
       }
 
@@ -473,7 +549,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const nfh = assetManifest?.notFound ?? "none";
         if (nfh === "single-page-application") {
           const shell = readAsset("/index.html");
-          if (shell) return { ok: true, found: true, status: 200, type: shell.type, hash: shell.hash, body: shell.body };
+          if (shell)
+            return { ok: true, found: true, status: 200, type: shell.type, hash: shell.hash, body: shell.body };
         }
         if (nfh === "404-page") {
           const page = readAsset("/404.html");
@@ -493,7 +570,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 +583,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, {
@@ -524,9 +603,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       // `store`/`part` route the rows to this queue's backing file (#74); the
       // trigger payload still carries the binding name the sprout matches on.
       const { store, part } = storeFor("queue", binding);
-      const rows = store.query<{ id: string; body: string; attempts: number }, [string, number, number]>(
-        "SELECT id, body, attempts FROM mq WHERE queue = ? AND dead = 0 AND visible_at <= ? ORDER BY visible_at LIMIT ?",
-      ).all(part, now, QUEUE_BATCH);
+      const rows = store
+        .query<{ id: string; body: string; attempts: number }, [string, number, number]>(
+          "SELECT id, body, attempts FROM mq WHERE queue = ? AND dead = 0 AND visible_at <= ? ORDER BY visible_at LIMIT ?",
+        )
+        .all(part, now, QUEUE_BATCH);
       if (rows.length === 0) continue;
       // hide the batch so the next tick doesn't re-deliver it while in flight
       const hideUntil = now + 30_000;
@@ -541,12 +622,16 @@ 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 : [];
-          } catch { /* keep defaults */ }
+            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
+          ack = [];
+          retry = rows.map((r) => r.id); // delivery failed → retry all
         }
         const del = store.query("DELETE FROM mq WHERE id = ?");
         for (const id of ack) del.run(id);
@@ -562,15 +647,17 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     if (bindings.queues.length > 0) timers.push(setInterval(drainQueuesOnce, 500));
     if (bindings.crons.length > 0) {
       let lastTick = "";
-      timers.push(setInterval(() => {
-        const now = new Date();
-        const stamp = `${now.getUTCFullYear()}-${now.getUTCMonth()}-${now.getUTCDate()}-${now.getUTCHours()}-${now.getUTCMinutes()}`;
-        if (stamp === lastTick) return; // once per minute
-        lastTick = stamp;
-        for (const expr of bindings.crons) {
-          if (cronMatches(expr, now)) void deliverTrigger("scheduled", { cron: expr, scheduledTime: now.getTime() });
-        }
-      }, 15_000));
+      timers.push(
+        setInterval(() => {
+          const now = new Date();
+          const stamp = `${now.getUTCFullYear()}-${now.getUTCMonth()}-${now.getUTCDate()}-${now.getUTCHours()}-${now.getUTCMinutes()}`;
+          if (stamp === lastTick) return; // once per minute
+          lastTick = stamp;
+          for (const expr of bindings.crons) {
+            if (cronMatches(expr, now)) void deliverTrigger("scheduled", { cron: expr, scheduledTime: now.getTime() });
+          }
+        }, 15_000),
+      );
     }
   }
 
@@ -593,7 +680,13 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
 export function cronMatches(expr: string, when: Date): boolean {
   const parts = expr.trim().split(/\s+/);
   if (parts.length !== 5) return false;
-  const fields = [when.getUTCMinutes(), when.getUTCHours(), when.getUTCDate(), when.getUTCMonth() + 1, when.getUTCDay()];
+  const fields = [
+    when.getUTCMinutes(),
+    when.getUTCHours(),
+    when.getUTCDate(),
+    when.getUTCMonth() + 1,
+    when.getUTCDay(),
+  ];
   const inField = (spec: string, value: number): boolean =>
     spec.split(",").some((token) => {
       if (token === "*") return true;
@@ -614,8 +707,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 +755,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;
@@ -676,5 +775,7 @@ if (import.meta.main) {
     assetsDir: values["assets-dir"],
   });
   const { port } = listen(broker, "127.0.0.1", Number(values.port ?? process.env.SB_BROKER_PORT ?? 0));
-  console.log(`sproutboat broker: 127.0.0.1:${port} db=${values.db ?? ":memory:"} sprout=${values["sprout-url"] ?? process.env.SB_SPROUT_URL ?? "(none)"}`);
+  console.log(
+    `sproutboat broker: 127.0.0.1:${port} db=${values.db ?? ":memory:"} sprout=${values["sprout-url"] ?? process.env.SB_SPROUT_URL ?? "(none)"}`,
+  );
 }

package/src/build.ts

@@ -4,13 +4,32 @@ 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 +48,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);
@@ -60,23 +79,33 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     do: Object.entries(input.config.durable_objects ?? {}).map(([binding, className]) => ({ binding, className })),
     crons: input.config.triggers?.crons ?? [],
     assets: input.config.assets?.binding ?? "",
+    // Baked plain values, read as env.NAME. The broker never serves these (they
+    // are compiled in via SPROUTBOAT_VARS_JSON); they ride along so the control
+    // plane can show what a version was built with. Not secret — `secrets` is
+    // that, and it carries names only.
+    vars: input.config.vars ?? {},
     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(),
@@ -92,8 +121,10 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   // frozen at v2. The control plane reads this to configure the per-deployment
   // broker (KV / D1 / R2 / queue names, secret names, outbound allowlist, cron
   // schedules, Durable Object classes).
-  const hasBindings = Object.values(bindings).some((value) => Array.isArray(value) && value.length > 0)
-    || Object.keys(bindings.resources).length > 0;
+  const hasBindings =
+    Object.values(bindings).some((value) => Array.isArray(value) && value.length > 0) ||
+    Object.keys(bindings.resources).length > 0 ||
+    Object.keys(bindings.vars).length > 0;
   if (hasBindings) {
     await writeFile(resolve(artifactDir, "bindings.json"), `${JSON.stringify(bindings, null, 2)}\n`);
   }
@@ -104,7 +135,11 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   if (input.config.assets) {
     const srcDir = resolve(input.projectDir, input.config.assets.directory);
     const outDir = resolve(artifactDir, "assets");
-    if (!(await stat(srcDir).then((s) => s.isDirectory()).catch(() => false))) {
+    if (
+      !(await stat(srcDir)
+        .then((s) => s.isDirectory())
+        .catch(() => false))
+    ) {
       throw new Error(`assets.directory "${input.config.assets.directory}" not found — run your site build first`);
     }
     await cp(srcDir, outDir, { recursive: true });