@voidbase-cloud/voidbase 0.1.0

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "@voidbase-cloud/voidbase",
+  "version": "0.1.0",
+  "description": "PocketBase-compatible backend on Cloudflare Workers (D1, R2, Queues, Durable Objects) via Void, or a single Bun process",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voidbase-cloud/voidbase.git"
+  },
+  "homepage": "https://github.com/voidbase-cloud/voidbase#readme",
+  "bugs": {
+    "url": "https://github.com/voidbase-cloud/voidbase/issues"
+  },
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "voidbase": "bin/voidbase.ts"
+  },
+  "exports": {
+    "./app": "./src/server/app.ts",
+    "./crons": "./src/server/crons.ts",
+    "./jobs": "./src/server/jobs.ts",
+    "./hub": "./src/server/hub.ts",
+    "./plugin": "./hooks-plugin.ts",
+    "./schema": "./db/schema.ts",
+    "./env": "./env.ts",
+    "./scripts/*": "./scripts/*",
+    "./package.json": "./package.json",
+    ".": "./src/node/index.ts",
+    "./serve": "./src/node/serve.ts",
+    "./static": "./src/server/static.ts",
+    "./api": "./src/server/api.ts",
+    "./passkeys": "./src/server/webauthn.ts",
+    "./cloud": "./src/cloud/rest.ts",
+    "./bundle": "./src/node/bundle.ts"
+  },
+  "imports": {
+    "#platform/env": {
+      "workerd": "./src/platform/workers/env.ts",
+      "default": "./src/platform/node/env.ts"
+    },
+    "#platform/log": {
+      "workerd": "./src/platform/workers/log.ts",
+      "default": "./src/platform/node/log.ts"
+    },
+    "#platform/sse": {
+      "workerd": "./src/platform/workers/sse.ts",
+      "default": "./src/platform/node/sse.ts"
+    },
+    "#platform/sockets": {
+      "workerd": "./src/platform/workers/sockets.ts",
+      "default": "./src/platform/node/sockets.ts"
+    },
+    "#platform/hooks": {
+      "workerd": "./src/platform/workers/hooks.ts",
+      "default": "./src/platform/node/hooks.ts"
+    },
+    "#platform/migrations": {
+      "workerd": "./src/platform/workers/migrations.ts",
+      "default": "./src/platform/node/migrations.ts"
+    },
+    "#platform/photon": {
+      "workerd": "./src/platform/workers/photon.ts",
+      "default": "./src/platform/node/photon.ts"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "db",
+    "crons",
+    "queues",
+    "routes",
+    "scripts",
+    "docs",
+    "hooks-plugin.ts",
+    "vite.config.ts",
+    "void.json",
+    "env.ts",
+    "tsconfig.json",
+    ".env.example",
+    "README.md",
+    "COMPAT.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "types",
+    "tsconfig.node.json"
+  ],
+  "keywords": [
+    "pocketbase",
+    "cloudflare-workers",
+    "d1",
+    "r2",
+    "void",
+    "backend",
+    "baas"
+  ],
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build",
+    "preview": "vp preview",
+    "panel:sync": "bun scripts/sync-panel.ts",
+    "surface": "bun surface/render.ts",
+    "test": "bun test",
+    "app:sync": "bun scripts/sync-app.ts",
+    "check": "void prepare && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.node.json --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "bun run check && bun test"
+  },
+  "dependencies": {
+    "@cf-wasm/photon": "^0.4.0",
+    "@simplewebauthn/server": "^14.0.1",
+    "bcryptjs": "^3.0.2",
+    "fflate": "^0.8.3",
+    "hono": "^4.11.9",
+    "typescript": "^5.9.3",
+    "void": "^0.10.13",
+    "vite": "^8.0.10",
+    "vite-plus": "^0.1.21",
+    "@cloudflare/workers-types": "^4.20250903.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.1",
+    "playwright": "^1.63.0",
+    "pocketbase": "0.28.0"
+  }
+}

package/queues/jobs.ts

@@ -0,0 +1,13 @@
+// Cloudflare Queue consumer for voidbase's background jobs: outbound mail and automatic backups.
+// Its presence gives the Worker the QUEUE_JOBS producer binding; without this file every job runs
+// inline in the request (the Bun runtime always does). Retries: up to maxRetries with backoff, then dropped and alerted.
+import { defineQueue } from "void";
+import "../src/server/app"; // registers the job handlers (mail, backups, thumbnails) and the hooks
+import { consumeJobs, type Job } from "../src/server/jobs";
+
+export const maxBatchSize = 10;
+export const maxBatchTimeout = 1; // seconds: mail should leave promptly
+export const maxRetries = 5;
+export const retryDelay = 30;
+
+export default defineQueue<Job>(async (batch, env) => { await consumeJobs(batch as never, env as never, maxRetries); });

package/routes/api/[...path].ts

@@ -0,0 +1,19 @@
+// Every /api/* request is handled by the voidbase Hono app (PocketBase wire protocol).
+import { defineHandler } from "void";
+import { app } from "../../src/server/app";
+import { appApi } from "../../src/server/api";
+import { mountWebAuthn } from "../../src/server/webauthn";
+
+// this checkout serves the pocketbase-sveltekit-starter, whose backend registers passkey routes (pb/webauthn)
+mountWebAuthn(appApi().router);
+
+const handle = defineHandler((c) =>
+  app.fetch(c.req.raw, c.env, (c as unknown as { executionCtx?: ExecutionContext }).executionCtx),
+);
+
+export const GET = handle;
+export const POST = handle;
+export const PATCH = handle;
+export const PUT = handle;
+export const DELETE = handle;
+export const OPTIONS = handle;

package/scripts/bench-realtime.ts

@@ -0,0 +1,46 @@
+// Realtime fan-out check: opens N SSE clients, subscribes each to a collection, creates one record and measures how
+// many clients receive the event and how long it takes (the poll loop targets about one second).
+//   bun scripts/bench-realtime.ts [url=http://127.0.0.1:5180] [clients=100]
+const url = (process.argv[2] ?? "http://127.0.0.1:5180").replace(/\/$/, ""); const N = Number(process.argv[3] ?? 100);
+const su = await fetch(`${url}/api/collections/_superusers/auth-with-password`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ identity: process.env.VOIDBASE_SUPERUSER_EMAIL ?? "admin@example.com", password: process.env.VOIDBASE_SUPERUSER_PASSWORD ?? "changeme123" }) }).then((r) => r.json()) as { token: string };
+const H = { authorization: su.token, "content-type": "application/json" };
+await fetch(`${url}/api/collections/ks_rt`, { method: "DELETE", headers: H });
+await fetch(`${url}/api/collections`, { method: "POST", headers: H, body: JSON.stringify({ name: "ks_rt", type: "base", listRule: "", viewRule: "", fields: [{ name: "title", type: "text" }] }) });
+interface Client { id: string; ac: AbortController; received: number[] }
+const clients: Client[] = []; let sent = 0;
+async function open(): Promise<Client> {
+  const ac = new AbortController(); const res = await fetch(`${url}/api/realtime`, { headers: { accept: "text/event-stream" }, signal: ac.signal });
+  const reader = res.body!.getReader(); const dec = new TextDecoder(); let buf = "";
+  const client: Client = { id: "", ac, received: [] };
+  const connected = new Promise<void>((resolve) => {
+    (async () => {
+      for (;;) {
+        const { value, done } = await reader.read().catch(() => ({ value: undefined, done: true })); if (done) break;
+        buf += dec.decode(value, { stream: true }); let i: number;
+        while ((i = buf.indexOf("\n\n")) >= 0) {
+          const chunk = buf.slice(0, i); buf = buf.slice(i + 2); let ev = "message", data = "";
+          for (const line of chunk.split("\n")) { if (line.startsWith("event:")) ev = line.slice(6).trim(); else if (line.startsWith("data:")) data += line.slice(5).trim(); }
+          if (ev === "PB_CONNECT") { client.id = (JSON.parse(data) as { clientId: string }).clientId; resolve(); }
+          else if (ev === "ks_rt/*") client.received.push(performance.now() - sent);
+        }
+      }
+    })();
+  });
+  await connected;
+  const sub = await fetch(`${url}/api/realtime`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ clientId: client.id, subscriptions: ["ks_rt/*"] }) });
+  if (sub.status !== 204) throw new Error(`subscribe failed: ${sub.status}`);
+  return client;
+}
+const t0 = performance.now();
+const BATCH = 25;
+for (let i = 0; i < N; i += BATCH) clients.push(...(await Promise.all(Array.from({ length: Math.min(BATCH, N - i) }, open))));
+const openMs = performance.now() - t0;
+sent = performance.now();
+await fetch(`${url}/api/collections/ks_rt/records`, { method: "POST", headers: H, body: JSON.stringify({ title: "ping" }) });
+await new Promise((r) => setTimeout(r, 5000));
+const got = clients.filter((c) => c.received.length > 0); const lat = got.map((c) => c.received[0]!).sort((a, b) => a - b);
+const pct = (p: number) => lat.length ? lat[Math.min(lat.length - 1, Math.floor(lat.length * p))]!.toFixed(0) : "-";
+console.log(`clients: ${N} opened+subscribed in ${(openMs / 1000).toFixed(1)}s; event received by ${got.length}/${N}; delivery latency p50 ${pct(0.5)} ms, p95 ${pct(0.95)} ms, max ${pct(1)} ms`);
+for (const c of clients) c.ac.abort();
+await fetch(`${url}/api/collections/ks_rt`, { method: "DELETE", headers: H });
+process.exit(0);

package/scripts/bench.ts

@@ -0,0 +1,39 @@
+// Latency and throughput baseline per endpoint against a running voidbase (or PocketBase): sequential p50/p95 and a
+// concurrent burst. Numbers from a local dev server (miniflare) are not production numbers; see docs/perf.md.
+//   bun scripts/bench.ts [url=http://127.0.0.1:5180] [--n 30] [--concurrency 10]
+const args = process.argv.slice(2); const url = (args.find((a) => !a.startsWith("--")) ?? "http://127.0.0.1:5180").replace(/\/$/, "");
+const opt = (k: string, d: number) => { const i = args.indexOf(`--${k}`); return i >= 0 ? Number(args[i + 1]) : d; };
+const N = opt("n", 30), C = opt("concurrency", 10);
+const su = await fetch(`${url}/api/collections/_superusers/auth-with-password`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ identity: process.env.VOIDBASE_SUPERUSER_EMAIL ?? "admin@example.com", password: process.env.VOIDBASE_SUPERUSER_PASSWORD ?? "changeme123" }) }).then((r) => r.json()) as { token: string };
+const H = { authorization: su.token, "content-type": "application/json" };
+await fetch(`${url}/api/collections/ks_bench`, { method: "DELETE", headers: H });
+await fetch(`${url}/api/collections`, { method: "POST", headers: H, body: JSON.stringify({ name: "ks_bench", type: "base", listRule: "", viewRule: "", fields: [{ name: "title", type: "text" }, { name: "n", type: "number" }, { name: "pic", type: "file", maxSelect: 1, thumbs: ["100x100"] }] }) });
+const png = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8AAQv8ZYAwAQ84H+VjtZqAAAAAASUVORK5CYII="), (c) => c.charCodeAt(0));
+const fd = new FormData(); fd.append("title", "seed"); fd.append("pic", new Blob([png], { type: "image/png" }), "dot.png");
+const seeded = (await fetch(`${url}/api/collections/ks_bench/records`, { method: "POST", headers: { authorization: su.token }, body: fd }).then((r) => r.json())) as { id: string; pic: string };
+for (let i = 0; i < 50; i++) await fetch(`${url}/api/collections/ks_bench/records`, { method: "POST", headers: H, body: JSON.stringify({ title: `row ${i}`, n: i }) });
+const created: string[] = [];
+const cases: { name: string; run: () => Promise<Response> }[] = [
+  { name: "GET /api/health", run: () => fetch(`${url}/api/health`) },
+  { name: "GET records list (30)", run: () => fetch(`${url}/api/collections/ks_bench/records?perPage=30`) },
+  { name: "GET records list + filter + sort", run: () => fetch(`${url}/api/collections/ks_bench/records?perPage=30&filter=${encodeURIComponent("n > 10 && title ~ 'row'")}&sort=-n`) },
+  { name: "GET record view", run: () => fetch(`${url}/api/collections/ks_bench/records/${seeded.id}`) },
+  { name: "POST record create", run: async () => { const r = await fetch(`${url}/api/collections/ks_bench/records`, { method: "POST", headers: H, body: JSON.stringify({ title: "bench", n: 1 }) }); created.push(String(((await r.clone().json()) as { id: string }).id)); return r; } },
+  { name: "PATCH record update", run: () => fetch(`${url}/api/collections/ks_bench/records/${seeded.id}`, { method: "PATCH", headers: H, body: JSON.stringify({ n: Math.random() }) }) },
+  { name: "POST auth-with-password", run: () => fetch(`${url}/api/collections/_superusers/auth-with-password`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ identity: "admin@example.com", password: "changeme123" }) }) },
+  { name: "GET file", run: () => fetch(`${url}/api/files/ks_bench/${seeded.id}/${seeded.pic}`) },
+  { name: "GET thumb 100x100 (cached after first)", run: () => fetch(`${url}/api/files/ks_bench/${seeded.id}/${seeded.pic}?thumb=100x100`) },
+  { name: "GET collections list (superuser)", run: () => fetch(`${url}/api/collections`, { headers: H }) },
+];
+const pct = (xs: number[], p: number) => xs.slice().sort((a, b) => a - b)[Math.min(xs.length - 1, Math.floor(xs.length * p))]!;
+console.log(`voidbase bench against ${url}: ${N} sequential requests, then ${C}x${N} concurrent, per endpoint\n`);
+console.log("| endpoint | p50 ms | p95 ms | max ms | concurrent req/s | errors |\n| --- | ---: | ---: | ---: | ---: | ---: |");
+for (const c of cases) {
+  const lat: number[] = []; let errors = 0;
+  for (let i = 0; i < N; i++) { const t = performance.now(); const r = await c.run(); await r.arrayBuffer(); lat.push(performance.now() - t); if (r.status >= 400) errors++; }
+  const t0 = performance.now();
+  await Promise.all(Array.from({ length: C }, async () => { for (let i = 0; i < N; i++) { const r = await c.run(); await r.arrayBuffer(); if (r.status >= 400) errors++; } }));
+  const rps = (C * N) / ((performance.now() - t0) / 1000);
+  console.log(`| ${c.name} | ${pct(lat, 0.5).toFixed(1)} | ${pct(lat, 0.95).toFixed(1)} | ${Math.max(...lat).toFixed(1)} | ${rps.toFixed(0)} | ${errors} |`);
+}
+await fetch(`${url}/api/collections/ks_bench`, { method: "DELETE", headers: H });

package/scripts/ci-suites.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Runs every differential and browser suite against a reference PocketBase and a voidbase, printing one line per
+# suite and failing if any suite fails. Needs test/smtp-sink.ts (2525/2526), test/mock-oidc.ts (5190) and test/s3-mock.ts (5195) running.
+#   scripts/ci-suites.sh [pb=http://127.0.0.1:8090] [vb=http://127.0.0.1:5180] [suites...]
+set -u
+cd "$(dirname "$0")/.."
+PB="${1:-http://127.0.0.1:8090}"; VB="${2:-http://127.0.0.1:5180}"; shift 2 2>/dev/null || true
+LOGS="${CI_LOGS:-.void/ci-logs}"; mkdir -p "$LOGS"
+POSITIONAL="auth-flows backups batch cascade filter-corpus filters-extra hardening logs-crons manage-rule oauth2 otp-mfa protected-files providers rules s3 security settings sql thumbs views"
+FLAGGED="compare records realtime collections"
+fail=0; run() { local name="$1"; shift; if timeout 900 "$@" > "$LOGS/$name.log" 2>&1; then echo "PASS  $name  $(tail -1 "$LOGS/$name.log" | cut -c1-90)"; else fail=$((fail+1)); echo "FAIL  $name  (see $LOGS/$name.log)"; grep -E "^FAIL|Error|error:" "$LOGS/$name.log" | head -5 | sed 's/^/      /'; fi; }
+SEL="${*:-all}"
+want() { [ "$SEL" = "all" ] || [[ " $SEL " == *" $1 "* ]]; }
+for s in $POSITIONAL; do want "$s" && run "$s" bun "test/conformance/$s.ts" "$PB" "$VB"; done
+for s in $FLAGGED; do want "$s" && run "$s" bun "test/conformance/$s.ts" --pb "$PB" --vb "$VB"; done
+want sdk-suite && run sdk-suite bun test/sdk-suite.ts "$PB" "$VB"
+want unit && run unit bun test
+want cloud-rest && run cloud-rest bun test/cloud-rest.ts
+if [ "${CI_BROWSER:-1}" = "1" ]; then
+  want panel-smoke && run panel-smoke bun test/panel-smoke.ts "$VB" "$LOGS/panel.png"
+  want panel-collections && run panel-collections bun test/panel-collections.ts "$VB" "$LOGS/panel-collections.png"
+  want panel-records && run panel-records bun test/panel-records.ts "$VB" "$LOGS/panel-records.png"
+  want panel-admin && run panel-admin bun test/panel-admin.ts "$VB"
+  want panel-login && run panel-login bun test/panel-login.ts "$PB" "$VB"
+fi
+echo; [ "$fail" = 0 ] && echo "ALL SUITES PASSED" || echo "$fail SUITE(S) FAILED"
+exit $fail

package/scripts/dev.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Start/stop the Vite+Void dev server in the background with a pidfile (used by the test harnesses).
+#   scripts/dev.sh start [port]   scripts/dev.sh stop   scripts/dev.sh status   scripts/dev.sh log
+set -u
+cd "$(dirname "$0")/.."
+PORT="${2:-${PORT:-5180}}"
+PIDFILE=".void/dev.pid"; LOG=".void/dev.log"
+mkdir -p .void
+running() { [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; }
+case "${1:-status}" in
+  start)
+    if running; then echo "already running (pid $(cat "$PIDFILE"))"; exit 0; fi
+    setsid nohup ./node_modules/.bin/vp dev --port "$PORT" --host 127.0.0.1 > "$LOG" 2>&1 < /dev/null &
+    echo $! > "$PIDFILE"
+    echo "started pid $! on http://127.0.0.1:$PORT (log: $LOG)"
+    curl --retry 90 --retry-delay 1 --retry-all-errors -s -o /dev/null -w "ready: HTTP %{http_code} for /api/health\n" "http://127.0.0.1:$PORT/api/health" ;;
+  stop)
+    if running; then
+      pid="$(cat "$PIDFILE")"
+      # setsid made $pid a group leader: signal the whole group so vite and workerd children die too
+      kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null
+      for _ in $(seq 1 50); do kill -0 "$pid" 2>/dev/null || break; sleep 0.2; done
+      kill -0 "$pid" 2>/dev/null && { kill -KILL -- "-$pid" 2>/dev/null; sleep 0.5; }
+      echo "stopped"
+    else echo "not running"; fi
+    rm -f "$PIDFILE" ;;
+  status) if running; then echo "running (pid $(cat "$PIDFILE"))"; else echo "not running"; fi ;;
+  log) tail -n "${2:-40}" "$LOG" ;;
+esac

package/scripts/export.ts

@@ -0,0 +1,70 @@
+// Exports everything from a running voidbase into a directory you can take elsewhere:
+//   <out>/data.db           SQLite file with the same tables and columns as PocketBase (user collections, _collections,
+//                           _params, _externalAuths, _authOrigins, _mfas, _otps), rows copied verbatim (password hashes included)
+//   <out>/collections.json  the collections in PocketBase's import format (Settings > Import collections)
+//   <out>/storage/          every uploaded file under {collectionId}/{recordId}/{filename}
+// Reads through the superuser API only (POST /api/sql, GET /api/files), so it works against a deployed instance.
+//   bun scripts/export.ts <url> <outDir> [superuserEmail] [superuserPassword]
+import { Database } from "bun:sqlite";
+import { mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+export async function exportAll(url: string, out: string, email: string, password: string): Promise<{ collections: number; rows: number; files: number }> {
+const base = url.replace(/\/$/, "");
+const auth = await fetch(`${base}/api/collections/_superusers/auth-with-password`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ identity: email, password }) });
+if (auth.status !== 200) throw new Error(`superuser login failed: ${auth.status} ${await auth.text()}`);
+const token = ((await auth.json()) as { token: string }).token;
+const H = { authorization: token, "content-type": "application/json" };
+async function sql(query: string): Promise<{ columns: { name: string; type: string }[]; rows: (string | null)[][] }> {
+  const r = await fetch(`${base}/api/sql`, { method: "POST", headers: H, body: JSON.stringify({ query }) });
+  if (r.status !== 200) throw new Error(`sql failed (${r.status}): ${query.slice(0, 80)} -> ${await r.text()}`);
+  return (await r.json()) as { columns: { name: string; type: string }[]; rows: (string | null)[][] };
+}
+const collections = ((await fetch(`${base}/api/collections?perPage=500&sort=+created`, { headers: H }).then((r) => r.json())) as { items: Record<string, unknown>[] }).items;
+if (existsSync(out)) rmSync(out, { recursive: true, force: true });
+mkdirSync(`${out}/storage`, { recursive: true });
+writeFileSync(`${out}/collections.json`, JSON.stringify(collections, null, 2));
+const db = new Database(`${out}/data.db`, { create: true });
+// system auth collections (_externalAuths, _authOrigins, _mfas, _otps) are collections too, so dedupe
+const tables = [...new Set([...collections.filter((c) => c.type !== "view").map((c) => String(c.name)), "_collections", "_params", "_externalAuths", "_authOrigins", "_mfas", "_otps"])];
+let files = 0, rows = 0;
+for (const table of tables) {
+  const info = await sql(`PRAGMA table_info("${table}")`);
+  if (!info.rows.length) { console.warn(`skip ${table}: no such table`); continue; }
+  const cols = info.rows.map((r) => ({ name: String(r[1]), type: String(r[2] ?? ""), pk: r[5] === "1" }));
+  db.run(`CREATE TABLE "${table}" (${cols.map((c) => `"${c.name}" ${c.type}${c.pk ? " PRIMARY KEY" : ""}`).join(", ")})`);
+  const insert = db.prepare(`INSERT INTO "${table}" (${cols.map((c) => `"${c.name}"`).join(", ")}) VALUES (${cols.map(() => "?").join(", ")})`);
+  const coll = collections.find((c) => c.name === table);
+  const fileFields = ((coll?.fields as { name: string; type: string }[] | undefined) ?? []).filter((f) => f.type === "file").map((f) => f.name);
+  let after = 0;
+  for (;;) {
+    const page = await sql(`SELECT rowid AS __rowid, ${cols.map((c) => `"${c.name}"`).join(", ")} FROM "${table}" WHERE rowid > ${after} ORDER BY rowid LIMIT 1000`);
+    if (!page.rows.length) break;
+    db.transaction(() => { for (const r of page.rows) insert.run(...r.slice(1)); })();
+    rows += page.rows.length; after = Number(page.rows.at(-1)![0]);
+    for (const r of page.rows) {
+      const rec = Object.fromEntries(cols.map((c, i) => [c.name, r[i + 1]]));
+      for (const f of fileFields) {
+        let names: string[] = []; const raw = rec[f]; if (!raw) continue;
+        try { const parsed = JSON.parse(String(raw)); names = Array.isArray(parsed) ? parsed.map(String) : [String(parsed)]; } catch { names = [String(raw)]; }
+        for (const name of names) {
+          const res = await fetch(`${base}/api/files/${coll!.id}/${rec.id}/${encodeURIComponent(name)}?download=1`, { headers: { authorization: token } });
+          if (res.status !== 200) { console.warn(`file ${table}/${rec.id}/${name}: HTTP ${res.status}`); continue; }
+          mkdirSync(`${out}/storage/${coll!.id}/${rec.id}`, { recursive: true });
+          writeFileSync(`${out}/storage/${coll!.id}/${rec.id}/${name}`, new Uint8Array(await res.arrayBuffer())); files++;
+        }
+      }
+    }
+    if (page.rows.length < 1000) break;
+  }
+}
+for (const c of collections.filter((c) => c.type === "view")) { try { db.run(`CREATE VIEW "${c.name}" AS ${String(c.viewQuery ?? "")}`); } catch (e) { console.warn(`view ${c.name} not recreated: ${e instanceof Error ? e.message : e}`); } }
+db.close();
+writeFileSync(`${out}/README.txt`, `voidbase export from ${base} at ${new Date().toISOString()}\n\ndata.db          SQLite: one table per collection with PocketBase's column layout, plus _collections/_params/_externalAuths/_authOrigins/_mfas/_otps\ncollections.json PocketBase collections import format (Settings > Import collections in any PocketBase or voidbase)\nstorage/         uploaded files as {collectionId}/{recordId}/{filename}\n\nTo move to PocketBase: import collections.json, then load rows from data.db (same table and column names) and copy storage/ into pb_data/storage/.\n`);
+return { collections: collections.length, rows, files };
+}
+
+if (import.meta.main) {
+  const [url, out, email = process.env.VOIDBASE_SUPERUSER_EMAIL ?? "admin@example.com", password = process.env.VOIDBASE_SUPERUSER_PASSWORD ?? "changeme123"] = process.argv.slice(2);
+  if (!url || !out) { console.error("usage: bun scripts/export.ts <url> <outDir> [email] [password]"); process.exit(1); }
+  const r = await exportAll(url, out, email, password);
+  console.log(`exported ${r.collections} collections, ${r.rows} rows, ${r.files} files to ${out}`);
+}

package/scripts/seed-app-user.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Creates the app user the differential suites and the starter expect (user@example.com / changeme123) on a
+# server, idempotently. Works against voidbase and PocketBase alike.
+#   scripts/seed-app-user.sh [url=http://127.0.0.1:5180]
+set -euo pipefail
+URL="${1:-http://127.0.0.1:5180}"
+SU_EMAIL="${VOIDBASE_SUPERUSER_EMAIL:-admin@example.com}"; SU_PASSWORD="${VOIDBASE_SUPERUSER_PASSWORD:-changeme123}"
+USER_EMAIL="${REFERENCE_USER_EMAIL:-user@example.com}"; USER_PASSWORD="${REFERENCE_USER_PASSWORD:-changeme123}"
+TOKEN=$(curl -s -X POST "$URL/api/collections/_superusers/auth-with-password" -H "content-type: application/json" -d "{\"identity\":\"$SU_EMAIL\",\"password\":\"$SU_PASSWORD\"}" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
+[ -n "$TOKEN" ] || { echo "superuser login failed at $URL"; exit 1; }
+existing=$(curl -s "$URL/api/collections/users/records?filter=email%3D%27$USER_EMAIL%27" -H "authorization: $TOKEN" | sed -n 's/.*"totalItems":\([0-9]*\).*/\1/p')
+if [ "${existing:-0}" = "0" ]; then
+  curl -s -o /dev/null -w "user $USER_EMAIL at $URL: HTTP %{http_code}\n" -X POST "$URL/api/collections/users/records" -H "content-type: application/json" -H "authorization: $TOKEN" -d "{\"email\":\"$USER_EMAIL\",\"password\":\"$USER_PASSWORD\",\"passwordConfirm\":\"$USER_PASSWORD\"}"
+else echo "user $USER_EMAIL already present at $URL"; fi

package/scripts/seed-d1.ts

@@ -0,0 +1,17 @@
+// Seeds a local Void state directory's D1 file with the system tables from db/migrations/*.sql, for dev/preview
+// servers that use `voidPlugin({ persistTo })` (void db migrate only knows the default .void state).
+//   bun scripts/seed-d1.ts <persistDir>   e.g. .void-ci
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+const target = process.argv[2]; if (!target) { console.error("usage: bun scripts/seed-d1.ts <persistDir>"); process.exit(1); }
+// miniflare names the database file deterministically from the binding; reuse the default state's name when present
+const defaultDir = ".void/v3/d1/miniflare-D1DatabaseObject";
+const fileName = (existsSync(defaultDir) ? readdirSync(defaultDir).find((f) => f.endsWith(".sqlite") && f !== "metadata.sqlite") : undefined) ?? "6a4e4d6dbf1fb3c3d2b0b0b6b2a2d4e7c1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6.sqlite";
+const dir = `${target}/v3/d1/miniflare-D1DatabaseObject`; mkdirSync(dir, { recursive: true });
+const db = new Database(`${dir}/${fileName}`, { create: true });
+let applied = 0;
+for (const f of readdirSync("db/migrations").filter((f) => f.endsWith(".sql")).sort()) {
+  for (const statement of readFileSync(`db/migrations/${f}`, "utf8").split("--> statement-breakpoint")) if (statement.trim()) { try { db.run(statement); applied++; } catch (e) { if (!String(e).includes("already exists")) throw e; } }
+}
+db.close();
+console.log(`seeded ${dir}/${fileName} with ${applied} statements`);

package/scripts/seed-reference.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Prepares and starts a reference PocketBase for the differential suites: downloads the release binary, runs the
+# starter's pb_migrations and pb_hooks, upserts the superuser and creates the app user the suites expect.
+#   scripts/seed-reference.sh <dir> [port=8090] [version=0.39.11] [starter=../pocketbase-sveltekit-starter]
+#   scripts/seed-reference.sh stop <dir>
+set -euo pipefail
+if [ "${1:-}" = "stop" ]; then d="$2"; [ -f "$d/pb.pid" ] && { kill -TERM -- "-$(cat "$d/pb.pid")" 2>/dev/null || kill -TERM "$(cat "$d/pb.pid")" 2>/dev/null || true; rm -f "$d/pb.pid"; echo "stopped"; }; exit 0; fi
+DIR="${1:?dir}"; PORT="${2:-8090}"; VERSION="${3:-0.39.11}"; STARTER="${4:-../pocketbase-sveltekit-starter}"
+SU_EMAIL="${VOIDBASE_SUPERUSER_EMAIL:-admin@example.com}"; SU_PASSWORD="${VOIDBASE_SUPERUSER_PASSWORD:-changeme123}"
+USER_EMAIL="${REFERENCE_USER_EMAIL:-user@example.com}"; USER_PASSWORD="${REFERENCE_USER_PASSWORD:-changeme123}"
+mkdir -p "$DIR"; STARTER="$(cd "$STARTER" && pwd)"
+if [ ! -x "$DIR/pocketbase" ] || [ "$("$DIR/pocketbase" --version 2>/dev/null)" != "pocketbase version $VERSION" ]; then
+  arch="linux_amd64"; case "$(uname -m)" in aarch64|arm64) arch="linux_arm64";; esac
+  echo "downloading pocketbase $VERSION ($arch)"
+  curl -sSL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${arch}.zip" -o "$DIR/pb.zip"
+  (cd "$DIR" && unzip -oq pb.zip pocketbase && rm pb.zip)
+fi
+PB=("$DIR/pocketbase" "--dir" "$DIR/pb_data" "--migrationsDir" "$STARTER/pb/pb_migrations" "--hooksDir" "$STARTER/pb/pb_hooks")
+"${PB[@]}" superuser upsert "$SU_EMAIL" "$SU_PASSWORD" >/dev/null
+# the starter's hooks read AUDITLOG like its Docker entrypoint sets it
+AUDITLOG="${AUDITLOG:-posts,users}" setsid nohup "${PB[@]}" serve --automigrate=0 --http "127.0.0.1:$PORT" > "$DIR/pb.log" 2>&1 < /dev/null &
+echo $! > "$DIR/pb.pid"
+curl --retry 60 --retry-delay 1 --retry-all-errors -s -o /dev/null "http://127.0.0.1:$PORT/api/health"
+TOKEN=$(curl -s -X POST "http://127.0.0.1:$PORT/api/collections/_superusers/auth-with-password" -H "content-type: application/json" -d "{\"identity\":\"$SU_EMAIL\",\"password\":\"$SU_PASSWORD\"}" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
+existing=$(curl -s "http://127.0.0.1:$PORT/api/collections/users/records?filter=email%3D%27$USER_EMAIL%27" -H "authorization: $TOKEN" | sed -n 's/.*"totalItems":\([0-9]*\).*/\1/p')
+if [ "${existing:-0}" = "0" ]; then
+  curl -s -o /dev/null -w "user $USER_EMAIL: HTTP %{http_code}\n" -X POST "http://127.0.0.1:$PORT/api/collections/users/records" -H "content-type: application/json" -H "authorization: $TOKEN" -d "{\"email\":\"$USER_EMAIL\",\"password\":\"$USER_PASSWORD\",\"passwordConfirm\":\"$USER_PASSWORD\"}"
+fi
+echo "reference pocketbase $VERSION on http://127.0.0.1:$PORT (pid $(cat "$DIR/pb.pid"), data $DIR/pb_data)"

package/scripts/starter.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Runs the unmodified pocketbase-sveltekit-starter frontend (sk) against voidbase instead of PocketBase.
+#   scripts/starter.sh start [port] [backend]   scripts/starter.sh stop   scripts/starter.sh log
+set -u
+cd "$(dirname "$0")/.."
+SK="${STARTER_SK_DIR:-../voidbase-sveltekit-starter/sk}"
+PORT="${2:-5174}"; BACKEND="${3:-http://127.0.0.1:5180}"
+PIDFILE=".void/starter.pid"; LOG=".void/starter.log"
+mkdir -p .void
+running() { [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; }
+case "${1:-status}" in
+  start)
+    if running; then echo "already running (pid $(cat "$PIDFILE"))"; exit 0; fi
+    ( cd "$SK" && POCKETBASE_URL="$BACKEND" setsid nohup ./node_modules/.bin/vite dev --port "$PORT" --host 127.0.0.1 --strictPort > "$OLDPWD/$LOG" 2>&1 < /dev/null & echo $! > "$OLDPWD/$PIDFILE" )
+    echo "started pid $(cat "$PIDFILE") on http://127.0.0.1:$PORT -> $BACKEND (log: $LOG)"
+    curl --retry 60 --retry-delay 1 --retry-all-errors -s -o /dev/null -w "ready: HTTP %{http_code}\n" "http://127.0.0.1:$PORT/" ;;
+  stop)
+    if running; then pid="$(cat "$PIDFILE")"; kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null; for _ in $(seq 1 50); do kill -0 "$pid" 2>/dev/null || break; sleep 0.2; done; kill -0 "$pid" 2>/dev/null && kill -KILL -- "-$pid" 2>/dev/null; echo "stopped"; else echo "not running"; fi
+    rm -f "$PIDFILE" ;;
+  status) if running; then echo "running (pid $(cat "$PIDFILE"))"; else echo "not running"; fi ;;
+  log) tail -n "${2:-40}" "$LOG" ;;
+esac

package/scripts/sync-app.ts

@@ -0,0 +1,22 @@
+// Copies a static app build (default: the SvelteKit starter's adapter-static output) into public/ so the same
+// Worker serves the app at / and the PocketBase admin panel at /_/. Everything but public/_ is replaced.
+//   bun run app:sync            # uses VOIDBASE_APP_DIR or ../pocketbase-sveltekit-starter/sk/build
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+const src = resolve(process.env.VOIDBASE_APP_DIR ?? `${import.meta.dir}/../../pocketbase-sveltekit-starter/sk/build`);
+const destArg = process.argv.indexOf("--dest");
+const dest = resolve(destArg >= 0 ? process.argv[destArg + 1]! : `${import.meta.dir}/../public`);
+if (!existsSync(`${src}/index.html`)) {
+  console.error(`app build not found at ${src} (set VOIDBASE_APP_DIR; for the starter run \`bun run build\` in sk/)`);
+  process.exit(1);
+}
+mkdirSync(dest, { recursive: true });
+for (const entry of readdirSync(dest)) if (entry !== "_") rmSync(`${dest}/${entry}`, { recursive: true, force: true });
+for (const entry of readdirSync(src)) {
+  if (entry === "_") { console.warn("skipping the app's /_ directory: that path belongs to the admin panel"); continue; }
+  cpSync(`${src}/${entry}`, `${dest}/${entry}`, { recursive: true });
+}
+console.log(`synced app ${src} -> ${dest} (${statSync(`${dest}/index.html`).size} bytes index.html)`);
+// Cloudflare 404-page handling: deep links get index.html (status 404) from the asset layer, never from the Worker
+if (!existsSync(`${dest}/404.html`)) copyFileSync(`${dest}/index.html`, `${dest}/404.html`);

package/scripts/sync-panel.ts

@@ -0,0 +1,66 @@
+// Copies PocketBase's prebuilt admin panel (ui/dist) into public/_ so the Worker serves it at /_/.
+// The panel is used unmodified; it talks to ../ relative to /_/, i.e. this Worker's /api.
+//
+// Optional branding (VOIDBASE_BRAND_DIR or --brand <dir>): a directory with any of
+//   logo.svg, logo_white.svg, favicon.png   replace the panel's images
+//   brand.json                              { "title": "...", "docsUrl": "https://..." }
+// title replaces <title> in index.html, docsUrl rewrites the https://pocketbase.io/docs links in the bundles.
+// The panel code itself is untouched; run without a brand dir to get the stock panel back.
+//   bun scripts/sync-panel.ts [--brand <dir>] [--dest <dir>]
+// Source: POCKETBASE_UI_DIST, else ../pocketbase/ui/dist, else the pinned release tarball (POCKETBASE_PANEL_VERSION) cached under ~/.cache/voidbase.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => (a.startsWith("--") ? [a.slice(2), arr[i + 1] ?? "1"] : [])).filter((x) => x.length));
+const PANEL_VERSION = process.env.POCKETBASE_PANEL_VERSION ?? "0.40.2";
+let src = resolve(process.env.POCKETBASE_UI_DIST ?? `${import.meta.dir}/../../pocketbase/ui/dist`);
+const dest = resolve(args.dest ?? `${import.meta.dir}/../public/_`);
+const brandDir = args.brand ?? process.env.VOIDBASE_BRAND_DIR;
+if (!existsSync(`${src}/index.html`)) {
+  // no local PocketBase checkout: fetch the committed ui/dist of the pinned release once into a cache
+  const cache = resolve(`${process.env.XDG_CACHE_HOME ?? `${process.env.HOME}/.cache`}/voidbase/panel-${PANEL_VERSION}`);
+  if (!existsSync(`${cache}/index.html`)) {
+    console.log(`downloading PocketBase ${PANEL_VERSION} admin panel (ui/dist) from GitHub`);
+    const res = await fetch(`https://codeload.github.com/pocketbase/pocketbase/tar.gz/refs/tags/v${PANEL_VERSION}`);
+    if (!res.ok) { console.error(`download failed: HTTP ${res.status} (set POCKETBASE_UI_DIST to a local ui/dist)`); process.exit(1); }
+    mkdirSync(cache, { recursive: true });
+    const tgz = `${cache}.tgz`; writeFileSync(tgz, new Uint8Array(await res.arrayBuffer()));
+    const tar = Bun.spawnSync(["tar", "-xzf", tgz, "-C", cache, "--strip-components=3", `pocketbase-${PANEL_VERSION}/ui/dist`]);
+    if (tar.exitCode !== 0) { console.error(new TextDecoder().decode(tar.stderr)); process.exit(1); }
+    rmSync(tgz, { force: true });
+  }
+  src = cache;
+}
+rmSync(dest, { recursive: true, force: true });
+cpSync(src, dest, { recursive: true });
+// PocketBase serves /_/extensions.js (UI extension registry). Without extensions it is an empty module.
+writeFileSync(`${dest}/extensions.js`, "// voidbase: no UI extensions configured\n");
+console.log(`synced panel ${src} -> ${dest} (${statSync(`${dest}/index.html`).size} bytes index.html)`);
+
+if (brandDir) {
+  const brand = resolve(brandDir);
+  const applied: string[] = [];
+  for (const img of ["logo.svg", "logo_white.svg", "favicon.png"]) {
+    if (existsSync(`${brand}/${img}`)) { cpSync(`${brand}/${img}`, `${dest}/images/${img}`); applied.push(img); }
+  }
+  const meta = existsSync(`${brand}/brand.json`) ? (JSON.parse(readFileSync(`${brand}/brand.json`, "utf8")) as { title?: string; docsUrl?: string }) : {};
+  if (meta.title) {
+    const index = `${dest}/index.html`;
+    writeFileSync(index, readFileSync(index, "utf8").replace(/<title>[^<]*<\/title>/, `<title>${meta.title.replace(/[<&]/g, "")}</title>`));
+    applied.push(`title "${meta.title}"`);
+  }
+  if (meta.docsUrl) {
+    const docsUrl = meta.docsUrl.replace(/\/$/, "");
+    let files = 0;
+    for (const f of readdirSync(`${dest}/assets`).filter((f) => f.endsWith(".js"))) {
+      const p = `${dest}/assets/${f}`; const code = readFileSync(p, "utf8");
+      const next = code.replace(/https:\/\/pocketbase\.io\/docs/g, docsUrl);
+      if (next !== code) { writeFileSync(p, next); files++; }
+    }
+    applied.push(`docs links -> ${docsUrl} in ${files} bundles`);
+  }
+  console.log(`branding from ${brand}: ${applied.length ? applied.join(", ") : "nothing to apply (expected logo.svg, logo_white.svg, favicon.png or brand.json)"}`);
+}
+// Cloudflare 404-page handling: the panel index doubles as its 404 page (PocketBase serves the panel for any /_/ path)
+import { copyFileSync } from "node:fs";
+if (existsSync(`${dest}/index.html`)) copyFileSync(`${dest}/index.html`, `${dest}/404.html`);