@voidbase-cloud/voidbase 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env for local dev. Both must be set for the bootstrap superuser upsert.
+VOIDBASE_SUPERUSER_EMAIL=admin@example.com
+VOIDBASE_SUPERUSER_PASSWORD=changeme123
+
+# PocketBase-style JS hooks directory bundled at build time (default: ./pb_hooks)
+VOIDBASE_HOOKS_DIR=./pb_hooks
+# Build-time: directories bundled into the Worker (PocketBase pb_hooks and pb_migrations layouts)
+VOIDBASE_HOOKS_DIR=pb_hooks
+VOIDBASE_MIGRATIONS_DIR=pb_migrations

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Releases are tagged `vX.Y.Z`; the section for the tagged version becomes the GitHub release notes.
+
+## Unreleased
+
+## 0.1.0
+
+First release candidate: PocketBase 0.40 wire compatibility on Cloudflare Workers (D1, R2, cron) via Void.
+
+- Collections engine with runtime DDL, all 14 field types, views with inferred fields, import/export, API rule validation.
+- Records API: filter/sort/expand/fields, files with thumbnails and ranges, batch, cascade delete.
+- Auth: password, OAuth2 (32 providers), OTP, MFA, passkeys, verification / password reset / email change flows, impersonation, auth alerts.
+- Realtime over SSE with a D1 change feed; JS hooks and migrations (`pb_hooks`, `pb_migrations`) bundled at build time.
+- Settings, SMTP over Cloudflare sockets, S3 file and backup storage, logs, crons, backups, SQL console, rate limits, trusted proxy, encryption at rest.
+- Unmodified PocketBase admin panel served at `/_/`; unmodified `pocketbase` JS SDK 0.28 supported.
+- Published as `@voidbase-cloud/voidbase` from GitHub Actions (npm + GitHub Packages).
+- Cloudflare cost shape: assets and deep links served by the asset layer without invoking the Worker (`404.html` shells, deep links carry status 404), request logs written only from warnings up by default (`VOIDBASE_LOG_MIN_LEVEL`), change-feed rows only while a client is subscribed, cron triggers derived from the hooks' `cronAdd` expressions plus lazy maintenance, Smart Placement, lazy Photon. Background jobs (system mail, automatic backups) through a Cloudflare Queue with retries, a rate-limit binding as a per-location ceiling, an opt-in Analytics Engine request log; `voidbase deploy` creates the queue and declares the bindings. Realtime pushes through a per-instance Durable Object hub (hibernating sockets, tens of milliseconds instead of a one-second poll); the D1 poll remains the fallback without the binding.
+- Differential conformance suites against a reference PocketBase, SDK coverage matrix, security suite, generated filter corpus, browser suites for the panel and the SvelteKit starter, CI workflow.

package/COMPAT.md

@@ -0,0 +1,43 @@
+# Compatibility matrix
+
+Verified against these upstream versions. "Verified" means a differential test drives the same requests (or the
+same UI) against a reference PocketBase and voidbase and compares the results; see `surface/surface.json` for the
+item-level map (`bun run surface`).
+
+| Component | Version | How it is verified |
+| --- | --- | --- |
+| PocketBase admin panel (`ui/dist`, served unmodified at `/_/`) | 0.40.2 | `test/panel-*.ts` (Playwright + system Chrome): login, collections, records, admin screens, superuser password reset, API preview |
+| Reference PocketBase server | 0.39.11 binary (0.40.2 source for behavior) | `test/conformance/*.ts` differential suites. 0.40-only features (`Cross-Origin-Opener-Policy`, Instagram provider, `DELETE /api/logs`) are tolerated when the 0.39 binary lacks them |
+| `pocketbase` JS SDK | 0.28 | through `pocketbase-sveltekit-starter` (`test/starter-*.ts`) and the SDK-shaped requests in the conformance suites |
+| Void | 0.10.13 | dev, preview and build |
+| Cloudflare Workers compatibility date | 2026-09-05, `nodejs_compat` | `void.json` |
+
+## API endpoints
+
+| Area | Endpoints | Status |
+| --- | --- | --- |
+| Health | `GET /api/health` | verified |
+| Collections | `GET/POST /api/collections`, `GET/PATCH/DELETE /api/collections/:c`, `DELETE .../truncate`, `PUT /api/collections/import`, `GET /api/collections/meta/scaffolds`, `GET /api/collections/meta/oauth2-providers` | verified (incl. view inference, rule validation) |
+| Records | `GET/POST .../records`, `GET/PATCH/DELETE .../records/:id` with filter, sort, expand, fields, skipTotal, `@request`/`@collection` rules, multipart files, modifiers | verified (88 recorded + live cases) |
+| Auth | `auth-methods`, `auth-with-password`, `auth-refresh`, `auth-with-oauth2`, `auth-with-otp`, `request-otp`, MFA handshake, `impersonate`, `request/confirm-verification`, `request/confirm-password-reset`, `request/confirm-email-change`, auth alerts, `GET/POST /api/oauth2-redirect` | verified |
+| Files | `GET /api/files/:c/:r/:f` (thumbs, ranges, 304, download), `POST /api/files/token`, protected files | verified |
+| Realtime | `GET /api/realtime` (SSE), `POST /api/realtime` | verified (polling fanout, see differences) |
+| Batch | `POST /api/batch` | verified (transaction emulated with undo statements) |
+| Settings | `GET/PATCH /api/settings`, `test/email`, `test/s3` (validation only), `apple/generate-client-secret` | verified; S3 backend not implemented |
+| Logs | `GET /api/logs`, `/api/logs/:id`, `/api/logs/stats`, `DELETE /api/logs` | verified |
+| Crons | `GET /api/crons`, `POST /api/crons/:id` | verified (built-ins + `cronAdd`) |
+| Backups | `GET/POST /api/backups`, `upload`, `GET/DELETE /api/backups/:key`, `POST .../restore` | verified; voidbase archive format |
+| SQL console | `POST /api/sql` | verified |
+| Passkeys (starter) | `/api/webauthn/*` | verified with a virtual authenticator |
+
+## Hooks
+
+All `on*` event families, `routerAdd`/`routerUse`, `cronAdd`/`cronRemove`, `migrate` and the `$app`, `$apis`,
+`$http`, `$filesystem`, `$security`, `$os`, `$dbx` globals listed in [docs/hooks.md](docs/hooks.md).
+
+## Tracking upstream
+
+- Panel: rerun `bun run panel:sync` from a newer `pocketbase/ui/dist`, then `bun test/panel-*.ts`.
+- Server behavior: point the conformance suites at a newer reference binary
+  (`bun test/conformance/compare.ts http://127.0.0.1:8090 http://127.0.0.1:5180`) and fix the diffs.
+- SDK: bump `pocketbase` in the starter and rerun `test/starter-*.ts`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 voidbase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,8 @@
+voidbase reimplements the HTTP API, validation rules, email templates and JS hooks surface of PocketBase
+(https://pocketbase.io, MIT License, Copyright (c) 2022 - present, Gani Georgiev) on Cloudflare Workers.
+The admin panel served at /_/ is PocketBase's own unmodified UI build (ui/dist), copied in by
+`bun scripts/sync-panel.ts`; it stays under PocketBase's MIT license. voidbase is not affiliated with or endorsed
+by the PocketBase project.
+
+Runtime dependencies: hono (MIT), fflate (MIT), @cf-wasm/photon (Apache-2.0, Photon by Silvia O'Dwyer),
+@simplewebauthn/server (MIT), bcryptjs (MIT). Built and deployed with Void (https://void.cloud).

package/README.md

@@ -0,0 +1,124 @@
+# voidbase
+
+A PocketBase-wire-compatible backend on Cloudflare Workers, built with [Void](https://void.cloud).
+The unmodified PocketBase admin panel (0.40.2) and the unmodified `pocketbase` JS SDK (0.28) are the two oracles that define done.
+
+Codename: `kanz-zjy`. Progress map: `surface/surface.json` rendered by `bun run surface`.
+
+## Use it like PocketBase as a framework
+
+```ts
+// main.ts
+import { voidbase, parseServeArgs, type VoidbaseApp } from "@voidbase-cloud/voidbase";
+export function register(app: VoidbaseApp) {
+  app.hooks.onRecordAfterCreateSuccess(async (e) => { /* ... */ }, "posts");   // the same on* functions pb_hooks get
+  app.router.get("/api/hello", (c) => c.json({ hello: "world" }));              // Hono-style routes
+  app.hooks.cronAdd("digest", "0 8 * * *", () => { /* ... */ });
+}
+if (import.meta.main) { const app = await voidbase(parseServeArgs()); register(app); await app.start(); }
+```
+
+`bun main.ts --http 127.0.0.1:8090` runs it; `voidbase deploy` composes `register` into the Worker as well.
+`voidbase-sveltekit-starter/vb` is the worked example (audit log, `hooks` collection actions, passkeys).
+
+## Install
+
+```bash
+bun add @voidbase-cloud/voidbase        # the package: library, CLI (`voidbase`) and the Cloudflare project generator
+bunx @voidbase-cloud/voidbase serve     # or run the CLI without installing
+```
+
+Releases are tagged `vX.Y.Z` and published from GitHub Actions to npm (with provenance once the repository is
+public) and to GitHub Packages; see [docs/releasing.md](docs/releasing.md).
+
+## Run it like PocketBase
+
+```bash
+bun install
+bunx voidbase serve --http 127.0.0.1:8090 --dir pb_data --hooksDir pb_hooks --migrationsDir pb_migrations --publicDir ./public
+```
+
+One Bun process, SQLite in `pb_data/data.db`, files in `pb_data/storage/`, the admin panel at `/_/`, the same
+`pb_hooks` and `pb_migrations` you would give PocketBase (`--dev` restarts on hook changes, `voidbase superuser
+upsert email pass` works offline on `pb_data`). The Cloudflare deployment runs the same code on D1 and R2 with
+`voidbase deploy` from the same directory (see docs/deploy.md). The PocketBase-shaped
+consumer is `voidbase-sveltekit-starter/vb`.
+
+## Run locally (this checkout, Workers dev server)
+
+```bash
+bun install
+cp .env.example .env            # first superuser, upserted at bootstrap
+bun run panel:sync              # copies ../pocketbase/ui/dist to public/_ (set POCKETBASE_UI_DIST to override)
+./node_modules/.bin/void db migrate
+./scripts/dev.sh start 5180     # background dev server with a pidfile; stop / status / log
+```
+
+Panel: http://127.0.0.1:5180/_/  ·  API: http://127.0.0.1:5180/api/health
+
+## Verify against PocketBase
+
+With a reference PocketBase on 127.0.0.1:8090 (the starter's `pb/` works, superuser admin@example.com / changeme123):
+
+```bash
+bun test/conformance/compare.ts          # same requests at both servers, JSON diffed with volatile fields masked
+bun test/panel-smoke.ts                  # headless login through the unmodified panel, screenshot to /tmp/panel.png
+```
+
+## The starter fork
+
+`voidbase-sveltekit-starter` is the reference consumer: `pocketbase-sveltekit-starter` with `pb/` replaced by
+`vb/` (a PocketBase-shaped directory: `pb_hooks`, `pb_migrations`, `pb_data`, `main.ts`, `entrypoint.sh`) and
+nothing else changed. Its `vb/package.json` depends on this package; `bun run backend` in `sk` runs `voidbase serve`,
+`bun run dev:backend` runs `main.ts`, and `bun run deploy` in `vb` goes live on Cloudflare. The original
+`pocketbase-sveltekit-starter` checkout stays on upstream master as the PocketBase reference for the differential
+suites (`scripts/seed-reference.sh` runs its `pb/` against the reference binary).
+
+## CLI
+
+`bun bin/voidbase.ts --help` (or `voidbase` when installed): `init`, `dev`, `build`, `preview`, `deploy [--cloudflare]`,
+`superuser upsert|list`, `import <collections.json>`, `export <outDir>`, `panel sync [--brand dir]`, `app sync`,
+`seed-user`. Remote commands take `--url` and `--admin email:password`.
+
+## Tests
+
+Conformance suites in `test/conformance/` run the same requests against a reference PocketBase (8090) and voidbase
+(5180) and compare; browser suites `test/panel-*.ts` and `test/starter-*.ts` drive the unmodified panel and the
+unmodified `pocketbase-sveltekit-starter`. Helpers that must be running for some suites: `bun test/smtp-sink.ts`
+(SMTP 2525 / HTTP 2526), `bun test/mock-oidc.ts` (5190) and `bun test/s3-mock.ts` (5195, S3 with SigV4 verification). `bun test/fresh-db.ts` builds the production Worker
+with the fixture hooks and migrations and boots it on an empty D1; `bun test/mail-http.ts` does the same with the HTTP mail
+provider variables.
+
+## Go live
+
+`voidbase token` prints a Cloudflare dashboard link that creates `VOIDBASE_DEPLOY_CF_API_KEY` with the right
+permissions pre-selected; with that variable set, `voidbase deploy` provisions D1 and R2, generates the Void project
+inside the package (`node_modules/voidbase/.cloud/<name>`), stores the superuser as secrets and uploads the Worker.
+Your directory stays `pb_hooks` + `pb_migrations` + `pb_data`, like a PocketBase folder. See [docs/deploy.md](docs/deploy.md).
+
+## Continuous integration
+
+`.github/workflows/ci.yml` checks out the two oracles (the starter and PocketBase's panel build), starts voidbase and
+a seeded reference PocketBase (`scripts/seed-reference.sh`), and runs every suite through `scripts/ci-suites.sh`,
+then `test/fresh-db.ts` and the starter smoke. The same scripts run locally against any pair of servers.
+
+## Docs
+
+- [docs/deploy.md](docs/deploy.md): Void platform or your own Cloudflare account.
+- [docs/differences.md](docs/differences.md): what the platform changes (D1 batches, per-isolate limits, polling realtime, backups format).
+- [docs/hooks.md](docs/hooks.md): `pb_hooks` and `pb_migrations` on Workers, supported events and globals.
+- [docs/migrating.md](docs/migrating.md): moving an existing PocketBase app.
+- [docs/platform.md](docs/platform.md): how to run cheap and fast on Cloudflare (assets off the Worker, log writes, change feed, crons, placement, queues, rate limits, the realtime hub) and the per-app Durable Object design for going beyond the account limits.
+- [COMPAT.md](COMPAT.md): verified upstream versions and endpoint matrix.
+
+## Layout
+
+- `routes/api/[...path].ts` hands every `/api/*` request to the Hono app in `src/server/app.ts`.
+- `src/server/` is the server: collections model, auth, settings, records, bootstrap.
+- `db/schema.ts` defines only the system tables. User collections are rows in `_collections` and tables created at runtime, as in PocketBase.
+- `public/_` is the panel build, synced, never edited (`bun run panel:sync --brand <dir>` for an optional logo/title/docs-link swap).
+- Everything outside `/api` is served by Cloudflare's asset layer without invoking the Worker; deep links get the SPA shell through `404.html` copies of `index.html` (written at build time by `hooks-plugin.ts` and by the sync scripts).
+- `crons/every-minute.ts` runs PocketBase's maintenance jobs and `cronAdd` jobs.
+- `queues/jobs.ts` consumes the jobs queue (system mail, automatic backups) with retries; without it every job runs inline.
+- `src/server/hub.ts` is the realtime hub, a Durable Object exported from this Worker (`hooks-plugin.ts` appends it to Void's entry; `wrangler.jsonc` binds it); without the binding realtime polls the D1 change feed.
+- `hooks-plugin.ts` bundles `pb_hooks` and `pb_migrations` into the Worker at build time.

package/bin/voidbase.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+// voidbase CLI: the PocketBase-shaped chores (superuser upsert, collections import/export, panel sync) plus thin
+// wrappers over the Void toolchain (dev, build, preview, deploy). Runs with Bun from the project root.
+//   voidbase <command> [options]     voidbase --help
+import { existsSync, mkdirSync, writeFileSync, cpSync } from "node:fs";
+import { resolve } from "node:path";
+import { exportAll } from "../scripts/export";
+
+const ROOT = resolve(`${import.meta.dir}/..`);
+const argv = process.argv.slice(2);
+const flags: Record<string, string> = {}; const positional: string[] = [];
+for (let i = 0; i < argv.length; i++) { const a = argv[i]!; if (a.startsWith("--")) { const [k, v] = a.slice(2).split("="); flags[k!] = v ?? (argv[i + 1] && !argv[i + 1]!.startsWith("--") ? argv[++i]! : "1"); } else positional.push(a); }
+const [cmd, sub, ...rest] = positional;
+const url = (flags.url ?? process.env.VOIDBASE_URL ?? "http://127.0.0.1:8090").replace(/\/$/, "");
+const serveOpts = () => ({ http: flags.http, dir: flags.dir, hooksDir: flags.hooksDir, migrationsDir: flags.migrationsDir, publicDir: flags.publicDir });
+const admin = () => { const [email, password] = (flags.admin ?? `${process.env.VOIDBASE_SUPERUSER_EMAIL ?? "admin@example.com"}:${process.env.VOIDBASE_SUPERUSER_PASSWORD ?? ""}`).split(":") as [string, string]; return { email, password }; };
+const HELP = `voidbase - PocketBase-compatible backend: a single Bun process locally, Cloudflare Workers via Void in production
+
+  serve [--http 127.0.0.1:8090] [--dir pb_data] [--hooksDir pb_hooks] [--migrationsDir pb_migrations] [--publicDir ../sk/build] [--dev] [--entry main.ts]
+                                     run the server like "pocketbase serve" (--dev restarts when hooks or migrations change;
+                                     --entry runs your own main.ts, the counterpart of a custom PocketBase build)
+  superuser upsert <email> <password>  create or update a superuser: on the local data directory (--dir) or on a running
+                                     instance (--url, --admin email:pass)
+
+  init [dir]                         scaffold .env, pb_hooks/, pb_migrations/ in a fresh checkout and sync the panel
+  dev [--port 5180]                  start the Void dev server (vp dev)
+  build | preview [--port 5181]      production build / run the built Worker locally (vp build / vp preview)
+  deploy [--name worker] [--account id] [--domain api.example.com] [--public-dir ../sk/build] [--dry-run] [--no-queue] [--no-hub] [--no-cron]
+         [--analytics] [--rate-limit 300/10]
+                                     go live on your Cloudflare account with VOIDBASE_DEPLOY_CF_API_KEY: creates the D1
+                                     database and R2 bucket, writes cloud/ (voidbase cloud init) with wrangler.jsonc,
+                                     stores the superuser as worker secrets and runs void deploy --backend cloudflare
+  deploy --void                      deploy to the Void platform instead (void auth login first)
+  token                              print the Cloudflare dashboard link that creates VOIDBASE_DEPLOY_CF_API_KEY
+  bundle [--out dir] [--version v]   build the generic Worker + panel as a release directory (default .cloud/releases/<v>)
+         [--push http://vb --token t]  and optionally push it into a voidbase control plane (POST /api/vbcloud/releases)
+  release push <dir> --url http://vb --token <superuser token>   push a built release ( --no-activate keeps the current one)
+  superuser list                     list superusers (--url, --admin)
+  import <collections.json> [--delete-missing]   PUT /api/collections/import on a running instance (--url, --admin)
+  export <outDir>                    SQLite + collections.json + storage/ from a running instance (--url, --admin)
+  cloud init [dir=cloud]             write a Void project (routes, middleware, crons, db, env, vite/void config) that
+                                     imports voidbase and uses ../pb_hooks and ../pb_migrations, for "void deploy"
+  panel sync [--brand <dir>]         copy PocketBase's ui/dist into public/_ (POCKETBASE_UI_DIST), optional branding
+  app sync                           copy a static app build into public/ (VOIDBASE_APP_DIR)
+  seed-user [email] [password]       create the app user (default user@example.com) on a running instance
+
+Options: --url http://host (default $VOIDBASE_URL or http://127.0.0.1:5180); --admin email:password (default $VOIDBASE_SUPERUSER_EMAIL / _PASSWORD)`;
+const run = async (bin: string, args: string[], env: Record<string, string> = {}) => { const p = Bun.spawn([bin, ...args], { cwd: ROOT, stdio: ["inherit", "inherit", "inherit"], env: { ...process.env, ...env } }); const code = await p.exited; if (code !== 0) process.exit(code); };
+async function api(method: string, path: string, body?: unknown, token?: string) {
+  const r = await fetch(url + path, { method, headers: { ...(body !== undefined ? { "content-type": "application/json" } : {}), ...(token ? { authorization: token } : {}) }, body: body !== undefined ? JSON.stringify(body) : undefined });
+  const text = await r.text(); let json: Record<string, unknown> = {}; try { json = JSON.parse(text); } catch { json = { raw: text }; }
+  return { status: r.status, json };
+}
+async function login(): Promise<string> {
+  const { email, password } = admin();
+  if (!password) { console.error("superuser credentials needed: --admin email:password or VOIDBASE_SUPERUSER_EMAIL/_PASSWORD"); process.exit(1); }
+  const r = await api("POST", "/api/collections/_superusers/auth-with-password", { identity: email, password });
+  if (r.status !== 200) { console.error(`login as ${email} at ${url} failed: ${r.status} ${JSON.stringify(r.json)}`); process.exit(1); }
+  return String(r.json.token);
+}
+
+switch (cmd) {
+  case undefined: case "help": case "--help": console.log(HELP); break;
+  case "token": { const { tokenHelp } = await import("../src/node/deploy-cf"); console.log(tokenHelp()); break; }
+  case "bundle": {
+    const { buildRelease, pushRelease } = await import("../src/node/bundle");
+    const r = await buildRelease({ out: flags.out as string | undefined, version: flags.version as string | undefined, hub: flags["no-hub"] ? false : undefined, queue: flags["no-queue"] ? false : undefined, keepProject: !!flags["keep-project"] });
+    if (flags.push) await pushRelease({ dir: r.dir, url: String(flags.push), token: String(flags.token ?? process.env.VOIDBASE_RELEASE_TOKEN ?? ""), activate: !flags["no-activate"] });
+    break;
+  }
+  case "release": {
+    if (sub !== "push") { console.error(`unknown release command "${sub}"\n\n${HELP}`); process.exit(1); }
+    const { pushRelease } = await import("../src/node/bundle");
+    await pushRelease({ dir: resolve(String(rest[0] ?? flags.dir ?? ".")), url: String(flags.url ?? process.env.VOIDBASE_URL ?? "http://127.0.0.1:8090"), token: String(flags.token ?? process.env.VOIDBASE_RELEASE_TOKEN ?? ""), activate: !flags["no-activate"] });
+    break;
+  }
+  case "serve": {
+    // --entry main.ts: the project's own composition (pb's "custom" build), otherwise the stock server
+    if (!flags.dev) { if (flags.entry) { await run("bun", [resolve(flags.entry), ...process.argv.slice(3).filter((a, i, arr) => a !== "--entry" && arr[i - 1] !== "--entry")]); break; } const { serve } = await import("../src/node/serve"); await serve(serveOpts()); break; }
+    // --dev: run the server as a child and restart it when pb_hooks / pb_migrations change (like modd for PocketBase)
+    const { watch } = await import("node:fs");
+    const childArgs = process.argv.slice(2).filter((a) => a !== "--dev");
+    const entry = flags.entry ? resolve(flags.entry) : null;
+    let child: ReturnType<typeof Bun.spawn> | null = null; let timer: ReturnType<typeof setTimeout> | null = null;
+    const entryArgs = childArgs.slice(1).filter((a, i, arr) => a !== "--entry" && arr[i - 1] !== "--entry");
+    const start = () => { child = Bun.spawn(entry ? ["bun", entry, ...entryArgs] : ["bun", import.meta.path, ...childArgs], { stdio: ["inherit", "inherit", "inherit"], env: process.env }); };
+    const restart = () => { if (timer) clearTimeout(timer); timer = setTimeout(() => { console.log("voidbase: hooks changed, restarting"); child?.kill(); start(); }, 300); };
+    for (const d of [flags.hooksDir ?? "pb_hooks", flags.migrationsDir ?? "pb_migrations", ...(entry ? [entry] : [])]) { try { watch(resolve(d), { recursive: true }, restart); } catch { /* directory may not exist yet */ } }
+    start();
+    process.on("SIGINT", () => { child?.kill(); process.exit(0); }); process.on("SIGTERM", () => { child?.kill(); process.exit(0); });
+    await new Promise(() => undefined);
+    break;
+  }
+  case "init": {
+    const dir = resolve(sub ?? ".");
+    mkdirSync(`${dir}/pb_hooks`, { recursive: true }); mkdirSync(`${dir}/pb_migrations`, { recursive: true });
+    if (!existsSync(`${dir}/.env`)) { cpSync(`${ROOT}/.env.example`, `${dir}/.env`); console.log("wrote .env from .env.example (set VOIDBASE_SUPERUSER_EMAIL/PASSWORD)"); }
+    if (!existsSync(`${dir}/pb_hooks/main.pb.js`)) writeFileSync(`${dir}/pb_hooks/main.pb.js`, `/// <reference path="../pb_data/types.d.ts" />\nrouterAdd("GET", "/api/hello", (e) => e.json(200, { hello: "voidbase" }));\n`);
+    console.log("pb_hooks/ and pb_migrations/ ready");
+    await run("bun", ["scripts/sync-panel.ts"]).catch(() => undefined);
+    console.log("\nnext: bun install && ./node_modules/.bin/void db migrate && voidbase dev");
+    break;
+  }
+  case "dev": await run("./node_modules/.bin/vp", ["dev", "--port", flags.port ?? "5180", "--host", flags.host ?? "127.0.0.1"]); break;
+  case "build": await run("./node_modules/.bin/vp", ["build"]); break;
+  case "preview": await run("./node_modules/.bin/vp", ["preview", "--port", flags.port ?? "5181", "--host", flags.host ?? "127.0.0.1"]); break;
+  case "deploy": {
+    if (flags.void) { await run("./node_modules/.bin/void", ["deploy"]); break; } // the Void platform (void auth login first)
+    const { deployToCloudflare } = await import("../src/node/deploy-cf");
+    await deployToCloudflare({ name: flags.name, account: flags.account, dir: flags.dir, publicDir: flags["public-dir"] ?? flags.publicDir, dryRun: !!flags["dry-run"], regenerate: !!flags.regenerate, queue: flags["no-queue"] ? false : undefined, cron: flags["no-cron"] ? false : undefined, domain: flags.domain as string | undefined, analytics: flags.analytics ? true : undefined, rateLimit: flags["rate-limit"], hub: flags["no-hub"] ? false : undefined });
+    break;
+  }
+  case "superuser": {
+    if (!flags.url && sub === "upsert" && rest.length >= 2) {
+      // offline, straight on the data directory (pocketbase superuser upsert)
+      const { openLocal } = await import("../src/node/serve"); const { upsertSuperuser } = await import("../src/server/bootstrap");
+      const { env, sqlite } = await openLocal({ ...serveOpts(), dir: flags.dir ?? "pb_data" });
+      const { ensureBootstrapped } = await import("../src/server/bootstrap"); await ensureBootstrapped(env.DB);
+      const [email, password] = rest as [string, string];
+      console.log(`${await upsertSuperuser(env.DB, email, password)} superuser ${email} in ${flags.dir ?? "pb_data"}`); sqlite.close(); break;
+    }
+    const token = await login();
+    if (sub === "list") { const r = await api("GET", "/api/collections/_superusers/records?perPage=200&sort=email", undefined, token); for (const s of (r.json.items as { id: string; email: string; created: string }[]) ?? []) console.log(`${s.id}  ${s.email}  ${s.created}`); break; }
+    if (sub !== "upsert" || rest.length < 2) { console.error("usage: voidbase superuser upsert <email> <password>"); process.exit(1); }
+    const [email, password] = rest as [string, string];
+    const existing = await api("GET", `/api/collections/_superusers/records?filter=${encodeURIComponent(`email = '${email.replace(/'/g, "\\'")}'`)}`, undefined, token);
+    const found = ((existing.json.items as { id: string }[]) ?? [])[0];
+    const r = found ? await api("PATCH", `/api/collections/_superusers/records/${found.id}`, { password, passwordConfirm: password }, token) : await api("POST", "/api/collections/_superusers/records", { email, password, passwordConfirm: password }, token);
+    if (r.status !== 200) { console.error(`upsert failed: ${r.status} ${JSON.stringify(r.json)}`); process.exit(1); }
+    console.log(`${found ? "updated" : "created"} superuser ${email} (${r.json.id})`); break;
+  }
+  case "import": {
+    if (!sub) { console.error("usage: voidbase import <collections.json> [--delete-missing]"); process.exit(1); }
+    const token = await login();
+    const collections = JSON.parse(await Bun.file(sub).text()) as unknown[];
+    const r = await api("PUT", "/api/collections/import", { collections, deleteMissing: !!flags["delete-missing"] }, token);
+    if (r.status !== 204) { console.error(`import failed: ${r.status} ${JSON.stringify(r.json)}`); process.exit(1); }
+    console.log(`imported ${collections.length} collections into ${url}`); break;
+  }
+  case "export": {
+    if (!sub) { console.error("usage: voidbase export <outDir>"); process.exit(1); }
+    const { email, password } = admin();
+    const r = await exportAll(url, sub, email, password);
+    console.log(`exported ${r.collections} collections, ${r.rows} rows, ${r.files} files to ${sub}`); break;
+  }
+  case "cloud": {
+    if (sub !== "init") { console.error("usage: voidbase cloud init [dir]"); process.exit(1); }
+    const { writeCloudProject } = await import("../src/node/cloud-init");
+    const r = writeCloudProject(resolve(rest[0] ?? "cloud"));
+    console.log(`wrote ${r.files} files + db/migrations to ${rest[0] ?? "cloud"}\nnext: voidbase deploy   (or: cd ${rest[0] ?? "cloud"} && bun install && bun run panel:sync && void deploy)`);
+    break;
+  }
+  // destinations resolve against the caller's directory (run() executes in the package root)
+  case "panel": await run("bun", ["scripts/sync-panel.ts", "--dest", resolve(flags.dest ?? "public/_"), ...(flags.brand ? ["--brand", resolve(flags.brand)] : [])]); break;
+  case "app": await run("bun", ["scripts/sync-app.ts", "--dest", resolve(flags.dest ?? "public")], { VOIDBASE_APP_DIR: resolve(flags.src ?? process.env.VOIDBASE_APP_DIR ?? "../sk/build") }); break;
+  case "seed-user": await run("bash", ["scripts/seed-app-user.sh", url], { REFERENCE_USER_EMAIL: sub ?? "user@example.com", REFERENCE_USER_PASSWORD: rest[0] ?? "changeme123" }); break;
+  default: console.error(`unknown command "${cmd}"\n\n${HELP}`); process.exit(1);
+}

package/crons/every-minute.ts

@@ -0,0 +1,13 @@
+// Cloudflare cron trigger. Hourly here (PocketBase's maintenance and settings.backups.cron are caught up to an hour late);
+// `voidbase deploy` generates a project whose triggers are the hooks' own cronAdd expressions plus this hourly tick.
+// `runDue` runs every job that became due since the previous tick.
+import { defineScheduled } from "void";
+import "../src/server/app"; // loads the pb_hooks so their cronAdd registrations exist
+import { runDue } from "../src/server/crons";
+
+export const cron = "0 * * * *";
+
+export default defineScheduled(async (controller, env) => {
+  const ran = await runDue(env as never, new Date(controller.scheduledTime));
+  if (ran.length) console.log(`voidbase: cron ran ${ran.join(", ")}`);
+});

package/db/migrations/20260905175935_large_swarm.sql

@@ -0,0 +1,87 @@
+CREATE TABLE `_authOrigins` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`collectionRef` text DEFAULT '' NOT NULL,
+	`recordRef` text DEFAULT '' NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`updated` text DEFAULT '' NOT NULL,
+	`fingerprint` text DEFAULT '' NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_authOrigins_unique_pairs` ON `_authOrigins` (`collectionRef`,`recordRef`,`fingerprint`);--> statement-breakpoint
+CREATE TABLE `_collections` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`system` integer DEFAULT false NOT NULL,
+	`type` text DEFAULT 'base' NOT NULL,
+	`name` text NOT NULL,
+	`fields` text DEFAULT '[]' NOT NULL,
+	`indexes` text DEFAULT '[]' NOT NULL,
+	`listRule` text,
+	`viewRule` text,
+	`createRule` text,
+	`updateRule` text,
+	`deleteRule` text,
+	`options` text DEFAULT '{}' NOT NULL,
+	`created` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL,
+	`updated` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `_collections_name_unique` ON `_collections` (`name`);--> statement-breakpoint
+CREATE INDEX `idx__collections_type` ON `_collections` (`type`);--> statement-breakpoint
+CREATE TABLE `_externalAuths` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`collectionRef` text DEFAULT '' NOT NULL,
+	`recordRef` text DEFAULT '' NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`updated` text DEFAULT '' NOT NULL,
+	`provider` text DEFAULT '' NOT NULL,
+	`providerId` text DEFAULT '' NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_externalAuths_record_provider` ON `_externalAuths` (`collectionRef`,`recordRef`,`provider`);--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_externalAuths_collection_provider` ON `_externalAuths` (`collectionRef`,`provider`,`providerId`);--> statement-breakpoint
+CREATE TABLE `_mfas` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`collectionRef` text DEFAULT '' NOT NULL,
+	`recordRef` text DEFAULT '' NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`updated` text DEFAULT '' NOT NULL,
+	`method` text DEFAULT '' NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_mfas_collectionRef_recordRef` ON `_mfas` (`collectionRef`,`recordRef`);--> statement-breakpoint
+CREATE TABLE `_pbMigrations` (
+	`file` text PRIMARY KEY NOT NULL,
+	`applied` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `_otps` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`collectionRef` text DEFAULT '' NOT NULL,
+	`recordRef` text DEFAULT '' NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`updated` text DEFAULT '' NOT NULL,
+	`password` text DEFAULT '' NOT NULL,
+	`sentTo` text DEFAULT '' NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_otps_collectionRef_recordRef` ON `_otps` (`collectionRef`,`recordRef`);--> statement-breakpoint
+CREATE TABLE `_params` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`value` text,
+	`created` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL,
+	`updated` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `_superusers` (
+	`id` text PRIMARY KEY DEFAULT ('r'||lower(hex(randomblob(7)))) NOT NULL,
+	`password` text DEFAULT '' NOT NULL,
+	`tokenKey` text DEFAULT '' NOT NULL,
+	`email` text DEFAULT '' NOT NULL,
+	`emailVisibility` integer DEFAULT false NOT NULL,
+	`verified` integer DEFAULT false NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`updated` text DEFAULT '' NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_tokenKey_pbc_3142635823` ON `_superusers` (`tokenKey`);--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_email_pbc_3142635823` ON `_superusers` (`email`) WHERE "_superusers"."email" != '';

package/db/migrations/20260905185720_wild_sunspot.sql

@@ -0,0 +1,16 @@
+CREATE TABLE `_changes` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`collection` text NOT NULL,
+	`recordId` text NOT NULL,
+	`action` text NOT NULL,
+	`created` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx__changes_collection` ON `_changes` (`collection`,`id`);--> statement-breakpoint
+CREATE TABLE `_realtime_clients` (
+	`id` text PRIMARY KEY NOT NULL,
+	`subscriptions` text DEFAULT '[]' NOT NULL,
+	`token` text DEFAULT '' NOT NULL,
+	`created` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL,
+	`updated` text DEFAULT (strftime('%Y-%m-%d %H:%M:%fZ')) NOT NULL
+);

package/db/migrations/20260905190723_solid_toro.sql

@@ -0,0 +1 @@
+ALTER TABLE `_changes` ADD `data` text;

package/db/migrations/20260905213340_remarkable_union_jack.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `_logs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`created` text DEFAULT '' NOT NULL,
+	`data` text DEFAULT '{}' NOT NULL,
+	`message` text DEFAULT '' NOT NULL,
+	`level` integer DEFAULT 0 NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_logs_created` ON `_logs` (`created`);--> statement-breakpoint
+CREATE INDEX `idx_logs_level` ON `_logs` (`level`);--> statement-breakpoint
+CREATE INDEX `idx_logs_message` ON `_logs` (`message`);