@voidbase-cloud/voidbase 0.1.0

package/src/node/deploy-cf.ts

@@ -0,0 +1,179 @@
+// `voidbase deploy`: go live on your own Cloudflare account with one API token (VOIDBASE_DEPLOY_CF_API_KEY).
+// Resolves the account, creates the D1 database, the R2 bucket and the jobs queue over the REST API (idempotent),
+// writes the Void project (cloud/) with a wrangler.jsonc carrying the real ids plus the rate-limit and Analytics
+// Engine bindings, stores the superuser credentials as worker secrets and runs `void deploy --backend cloudflare`,
+// which builds, applies the D1 migrations and uploads the Worker.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { writeCloudProject } from "./cloud-init";
+import { loadEnv } from "./serve";
+import { CfApi, attachCustomDomain, ensureD1, ensureQueue, ensureR2, rateLimitNamespace, resolveAccount, workersSubdomain } from "../cloud/rest";
+
+const API = (process.env.CLOUDFLARE_API_BASE ?? "https://api.cloudflare.com/client/v4").replace(/\/$/, "");
+export const TOKEN_ENV = "VOIDBASE_DEPLOY_CF_API_KEY";
+// Account-owned token template (docs: fundamentals/api/how-to/account-owned-token-template): the dashboard resolves
+// :account to the signed-in account and pre-selects exactly what the deploy needs.
+export const TOKEN_PERMISSIONS = [
+  { key: "workers_scripts", type: "edit" }, // upload the Worker, its cron trigger and secrets
+  { key: "d1", type: "edit" },              // create the database, apply migrations
+  { key: "workers_r2", type: "edit" },      // create the files bucket
+  { key: "queues", type: "edit" },          // create the jobs queue (mail and backups with retries); optional
+  { key: "account_settings", type: "read" }, // resolve the account id and workers.dev subdomain
+];
+export const tokenDeepLink = () => `https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=${encodeURIComponent(JSON.stringify(TOKEN_PERMISSIONS))}&name=${encodeURIComponent(TOKEN_ENV)}`;
+export const tokenHelp = () => `Create the deploy token in the Cloudflare dashboard (permissions pre-selected):
+
+  ${tokenDeepLink()}
+
+Then make it available as ${TOKEN_ENV} (shell export, .env next to pb_hooks, or a CI secret) and run: voidbase deploy
+Permissions the link pre-selects: Workers Scripts (edit), D1 (edit), Workers R2 Storage (edit), Queues (edit),
+Account Settings (read). Queues is optional: without it the deploy skips the jobs queue and sends mail inline.
+If the link format ever changes, pick those by hand at https://dash.cloudflare.com/?to=/:account/api-tokens
+(reference: https://developers.cloudflare.com/fundamentals/api/reference/permissions/).`;
+
+export interface DeployOptions { cron?: boolean; domain?: string; name?: string; account?: string; dir?: string; // dir: a visible project instead of <package>/.cloud/<slug>
+  publicDir?: string; dryRun?: boolean; regenerate?: boolean; superuserEmail?: string; superuserPassword?: string; log?: (line: string) => void;
+  queue?: boolean;      // jobs queue for mail and automatic backups (default on; skipped when the token cannot create queues)
+  analytics?: boolean;  // Analytics Engine dataset with one data point per request (opt-in: --analytics or VOIDBASE_DEPLOY_ANALYTICS=1; the account must have Analytics Engine enabled)
+  rateLimit?: string;   // exact per-location ceiling per IP as "<requests>/<10|60>", default "300/10" (PocketBase's /api/ rule); "0" disables
+  hub?: boolean;        // realtime hub Durable Object in this Worker (default on; VOIDBASE_DEPLOY_HUB=0 keeps the D1 poll)
+}
+
+// the Cloudflare calls live in src/cloud/rest.ts (shared with control planes); this module adds the deploy's own wording
+export { rateLimitNamespace } from "../cloud/rest";
+export function parseRateLimit(spec: string | undefined): { limit: number; period: 10 | 60 } | null {
+  const v = (spec ?? "").trim();
+  if (!v || v === "0" || v === "off") return v ? null : { limit: 300, period: 10 };
+  const m = /^(\d+)\/(10|60)$/.exec(v);
+  if (!m) throw new Error(`invalid rate limit "${spec}": use <requests>/10 or <requests>/60 (seconds), or 0 to disable`);
+  return { limit: Number(m[1]), period: Number(m[2]) as 10 | 60 };
+}
+
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 54) || "voidbase";
+function projectName(): string {
+  try { const n = String((JSON.parse(readFileSync("package.json", "utf8")) as { name?: string }).name ?? ""); if (n && n !== "vb" && n !== "pb") return slug(n); } catch { /* no package.json */ }
+  const dir = slug(resolve(".").split("/").at(-1) ?? "");
+  return dir === "vb" || dir === "pb" ? slug(`${resolve("..").split("/").at(-1) ?? "voidbase"}-backend`) : dir;
+}
+const randomPassword = () => { const a = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789"; const b = crypto.getRandomValues(new Uint8Array(20)); return Array.from(b, (x) => a[x % a.length]).join(""); };
+
+// Bun only loads the .env of the working directory; the starter keeps its PB_* and deploy variables one level up.
+const ENV_KEYS = [TOKEN_ENV, "VOIDBASE_DEPLOY_CF_ACCOUNT_ID", "VOIDBASE_DEPLOY_NAME", "VOIDBASE_DEPLOY_QUEUE", "VOIDBASE_DEPLOY_HUB", "VOIDBASE_DEPLOY_ANALYTICS", "VOIDBASE_DEPLOY_RATE_LIMIT", "VOIDBASE_SUPERUSER_EMAIL", "VOIDBASE_SUPERUSER_PASSWORD", "PB_SUPERUSER_EMAIL", "PB_SUPERUSER_PASSWORD", "AUDITLOG"];
+export function loadEnvFiles(files = [".env", ".env.local", "../.env", "../.env.local"]): string[] {
+  const loaded: string[] = [];
+  for (const f of files) {
+    if (!existsSync(f)) continue;
+    for (const line of readFileSync(f, "utf8").split("\n")) {
+      const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*?)\s*$/.exec(line); if (!m) continue;
+      const [, k, raw] = m as unknown as [string, string, string];
+      if (!ENV_KEYS.includes(k) || process.env[k]) continue;
+      process.env[k] = raw.replace(/^(['"])(.*)\1$/, "$2"); loaded.push(`${k} (${f})`);
+    }
+  }
+  return loaded;
+}
+
+export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ name: string; account: string; url: string | null; wranglerConfig: string; project: string }> {
+  const log = opts.log ?? ((l: string) => console.log(l));
+  loadEnv(); const fromFiles = loadEnvFiles(); if (fromFiles.length) log(`from .env: ${fromFiles.join(", ")}`);
+  const token = process.env[TOKEN_ENV] || process.env.CLOUDFLARE_API_TOKEN || ""; // empty means unset
+  if (!token) { log(`${TOKEN_ENV} is not set.\n\n${tokenHelp()}`); throw new Error(`${TOKEN_ENV} missing`); }
+  const name = slug(opts.name || process.env.VOIDBASE_DEPLOY_NAME || projectName());
+  const api = new CfApi(token, API);
+  const account = await resolveAccount(api, opts.account || process.env.VOIDBASE_DEPLOY_CF_ACCOUNT_ID || undefined).catch((e: Error) => { throw new Error(`${e.message} (is it ${TOKEN_ENV} with Account Settings read?)`); });
+  log(`account ${account.name} (${account.id}), worker "${name}"`);
+  const db = await ensureD1(api, account.id, `${name}-db`); log(`D1 ${name}-db ${db.created ? "created" : "exists"} (${db.uuid})`);
+  const bucket = await ensureR2(api, account.id, `${name}-storage`); log(`R2 ${name}-storage ${bucket.created ? "created" : "exists"}`);
+  const off = (v: string | undefined) => v !== undefined && ["0", "false", "off", "no"].includes(v.trim().toLowerCase());
+  const wantQueue = opts.queue ?? !off(process.env.VOIDBASE_DEPLOY_QUEUE);
+  const on = (v: string | undefined) => v !== undefined && ["1", "true", "on", "yes"].includes(v.trim().toLowerCase());
+  const analytics = opts.analytics ?? on(process.env.VOIDBASE_DEPLOY_ANALYTICS);
+  const rateLimit = parseRateLimit(opts.rateLimit ?? process.env.VOIDBASE_DEPLOY_RATE_LIMIT);
+  const hub = opts.hub ?? !off(process.env.VOIDBASE_DEPLOY_HUB);
+  // Workers Free allows 5 cron triggers per account; without the trigger PocketBase's maintenance runs lazily in requests
+  const cron = opts.cron ?? !off(process.env.VOIDBASE_DEPLOY_CRON);
+  // a custom domain on a zone of the account (wrangler attaches it: DNS record + certificate); workers.dev is then off
+  const domain = String(opts.domain || process.env.VOIDBASE_DEPLOY_DOMAIN || "").trim().replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase();
+  if (domain && !/^[a-z0-9.-]+\.[a-z]{2,}$/.test(domain)) throw new Error(`invalid custom domain "${domain}"`);
+  let queue: string | false = false;
+  if (wantQueue) {
+    const q = await ensureQueue(api, account.id, `${name}-jobs`);
+    queue = q.id ? `${name}-jobs` : false;
+    if (queue) log(`Queue ${name}-jobs ${q.created ? "created" : "exists"} (mail and automatic backups run from it with retries)`);
+    else log(`Queue ${name}-jobs not created (${q.reason}): mail is sent inline and backups run in the cron tick. Give the token the Queues edit permission (${tokenDeepLink()}) to enable it, or VOIDBASE_DEPLOY_QUEUE=0 to silence this.`);
+  }
+
+  // the Void project lives inside the voidbase package (<package>/.cloud/<slug>), not in the consumer's tree:
+  // its entry files import this package by relative path and resolve `void`/`vite` by walking up to node_modules
+  const PKG = resolve(import.meta.dir, "../.."); const cloud = opts.dir ? resolve(opts.dir) : resolve(PKG, ".cloud", name);
+  const consumer = resolve(".");
+  const entry = ["main.ts", "main.js"].map((f) => resolve(consumer, f)).find((f) => existsSync(f) && /export\s+(async\s+)?function\s+register\b|export\s*\{[^}]*\bregister\b/.test(readFileSync(f, "utf8")));
+  if (entry) log(`composing ${entry} (register) into the Worker`);
+  writeCloudProject(cloud, opts.dir ? "package" : "internal", { hooksDir: resolve(consumer, process.env.VOIDBASE_HOOKS_DIR || "pb_hooks"), migrationsDir: resolve(consumer, process.env.VOIDBASE_MIGRATIONS_DIR || "pb_migrations"), entry, queue, hub });
+  if (!queue) { const { rmSync } = await import("node:fs"); rmSync(`${cloud}/queues`, { recursive: true, force: true }); }
+  if (!cron) { const { rmSync } = await import("node:fs"); rmSync(`${cloud}/crons`, { recursive: true, force: true }); log("cron trigger disabled (VOIDBASE_DEPLOY_CRON=0 / --no-cron): maintenance runs lazily in requests"); }
+  // Smart Placement runs the Worker next to its D1 database: PocketBase-shaped requests are several dependent queries.
+  // The rate-limit binding is an exact per-location ceiling per IP on top of the settings' rules (which count per
+  // isolate); the Analytics Engine dataset takes one data point per request at any log level.
+  const wranglerConfig = JSON.stringify({
+    name, account_id: account.id, placement: { mode: "smart" },
+    ...(domain ? { workers_dev: false } : {}), // the custom domain is attached through the API after the upload (see below)
+    d1_databases: [{ binding: "DB", database_name: `${name}-db`, database_id: db.uuid, migrations_dir: "./db/migrations" }],
+    r2_buckets: [{ binding: "STORAGE", bucket_name: `${name}-storage` }],
+    ...(rateLimit ? { ratelimits: [{ name: "RATE_LIMITER", namespace_id: rateLimitNamespace(name), simple: { limit: rateLimit.limit, period: rateLimit.period } }] } : {}),
+    ...(analytics ? { analytics_engine_datasets: [{ binding: "LOGS_ANALYTICS", dataset: `${name.replace(/-/g, "_")}_requests` }] } : {}),
+    // the realtime hub: a SQLite-backed Durable Object class exported from this Worker (free plan included), one per instance
+    ...(hub ? { durable_objects: { bindings: [{ name: "HUB", class_name: "VoidbaseHub" }] }, migrations: [{ tag: "voidbase-hub-v1", new_sqlite_classes: ["VoidbaseHub"] }] } : {}),
+  }, null, 2) + "\n";
+  writeFileSync(`${cloud}/wrangler.jsonc`, `// written by voidbase deploy; ids are real resources on account ${account.id}\n${wranglerConfig}`);
+  // non-secret worker vars: the instance's own name and account (a control plane needs them to find itself), the
+  // hooks' AUDITLOG, plus VOIDBASE_DEPLOY_VARS=A,B from the environment; secrets (VOIDBASE_DEPLOY_SECRETS=X,Y) never go here
+  const listed = (key: string) => (process.env[key] ?? "").split(",").map((k) => k.trim()).filter(Boolean);
+  const extraVars = listed("VOIDBASE_DEPLOY_VARS"), extraSecrets = listed("VOIDBASE_DEPLOY_SECRETS");
+  const baked: Record<string, string> = { VOIDBASE_WORKER_NAME: name, VOIDBASE_ACCOUNT_ID: account.id };
+  for (const k of ["AUDITLOG", ...extraVars]) if (process.env[k]) baked[k] = process.env[k]!;
+  writeFileSync(`${cloud}/.env`, Object.entries(baked).map(([k, v]) => `${k}=${v}\n`).join(""));
+  log(`project: ${cloud}`);
+
+  // superuser: from the environment (PB_* is what the starter's entrypoint uses) or generated once and kept in pb_data
+  const dataDir = resolve(consumer, process.env.VOIDBASE_DATA_DIR || "pb_data"); mkdirSync(dataDir, { recursive: true });
+  const credFile = `${dataDir}/.superuser-credentials`;
+  let email = opts.superuserEmail || process.env.VOIDBASE_SUPERUSER_EMAIL || process.env.PB_SUPERUSER_EMAIL || "";
+  let password = opts.superuserPassword || process.env.VOIDBASE_SUPERUSER_PASSWORD || process.env.PB_SUPERUSER_PASSWORD || "";
+  const saved = existsSync(credFile) ? (JSON.parse(readFileSync(credFile, "utf8")) as { email: string; password: string }) : null;
+  const placeholder = !password || password === "changeme123"; // the local dev default never goes live
+  if (placeholder && saved && (!email || email === saved.email)) { email = saved.email; password = saved.password; }
+  if (!email) email = "admin@example.com";
+  if (!password || password === "changeme123") { password = randomPassword(); log(`generated a superuser password for ${email} (saved in ${credFile}; change it after the first login)`); }
+  writeFileSync(credFile, JSON.stringify({ email, password }, null, 2) + "\n", { mode: 0o600 });
+
+  const url = domain ? `https://${domain}` : await workersSubdomain(api, account.id).then((s) => (s ? `https://${name}.${s}.workers.dev` : null));
+  if (domain) log(`custom domain ${domain} (workers.dev off): attached through the Workers Custom Domains API after the upload (Cloudflare adds the DNS record and certificate)`);
+  log(`bindings: D1, R2${hub ? ", realtime hub (Durable Object)" : ""}${queue ? ", Queue" : ""}${rateLimit ? `, rate limit ceiling ${rateLimit.limit}/${rateLimit.period}s per IP` : ""}${analytics ? ", Analytics Engine (needs Analytics Engine enabled once for the account: https://dash.cloudflare.com/" + account.id + "/workers/analytics-engine)" : ""}`);
+  if (opts.dryRun) { log(`dry run: would sync the panel${opts.publicDir ? ` and ${opts.publicDir}` : ""} into ${cloud}/public, put 2 secrets and run void deploy --backend cloudflare (${url ?? "url unknown"})`); return { name, account: account.id, url, wranglerConfig, project: cloud }; }
+
+  // the toolchain comes with the voidbase package (void, and wrangler through void)
+  const voidDir = resolve(Bun.resolveSync("void/package.json", PKG), "..");
+  const voidBin = resolve(voidDir, "..", ".bin", "void"); const wrangler = resolve(Bun.resolveSync("wrangler/package.json", voidDir), "..", "bin", "wrangler.js");
+  // values also exported in the shell are stripped from baked vars by the Cloudflare backend, so keep the vars file clean instead
+  // the generated project has no node_modules of its own: `void deploy` shells out to `vite build`, so the package's toolchain goes on PATH
+  const binDirs = [resolve(PKG, "node_modules/.bin"), resolve(voidDir, "..", ".bin")].filter((d, i, a) => a.indexOf(d) === i);
+  const env: Record<string, string | undefined> = { ...process.env, PATH: `${binDirs.join(":")}:${process.env.PATH ?? ""}`, CLOUDFLARE_API_TOKEN: token, CLOUDFLARE_ACCOUNT_ID: account.id, VOIDBASE_SUPERUSER_EMAIL: email, VOIDBASE_SUPERUSER_PASSWORD: password };
+  for (const k of Object.keys(baked)) delete env[k];
+  const sh = async (cmd: string[], input?: string) => { const p = Bun.spawn(cmd, { cwd: cloud, env: env as Record<string, string>, stdin: input === undefined ? "inherit" : new TextEncoder().encode(input), stdout: "inherit", stderr: "inherit" }); const code = await p.exited; if (code !== 0) throw new Error(`${cmd.join(" ")} exited with ${code}`); };
+  mkdirSync(`${cloud}/public`, { recursive: true });
+  await sh(["bun", resolve(PKG, "scripts/sync-panel.ts"), "--dest", `${cloud}/public/_`]);
+  if (opts.publicDir) await sh(["bun", resolve(PKG, "scripts/sync-app.ts"), "--dest", `${cloud}/public`], undefined).catch((e) => log(`frontend build not synced: ${e instanceof Error ? e.message : e}`));
+  const secrets: [string, string][] = [["VOIDBASE_SUPERUSER_EMAIL", email], ["VOIDBASE_SUPERUSER_PASSWORD", password], ...extraSecrets.filter((k) => process.env[k]).map((k): [string, string] => [k, process.env[k]!])];
+  for (const [k, v] of secrets) await sh(["bun", wrangler, "secret", "put", k, "--name", name], v + "\n");
+  await sh([voidBin, "deploy", "--backend", "cloudflare"]);
+  if (domain) {
+    const d = await attachCustomDomain(api, account.id, { hostname: domain, service: name });
+    log(`custom domain ${d.hostname} ${d.created ? "attached" : "already attached"} (zone ${d.zone_id}); the certificate can take a minute`);
+  }
+  if (url) {
+    const ok = await fetch(`${url}/api/health`).then((r) => r.status).catch(() => 0);
+    log(`\nlive: ${url}  (health ${ok || "not reachable yet"})\n├─ REST API:  ${url}/api/\n└─ Dashboard: ${url}/_/   sign in as ${email} (password in ${credFile})`);
+  } else log("deployed; workers.dev subdomain not enabled on this account, add a route or enable it in the dashboard (or VOIDBASE_DEPLOY_DOMAIN=<host> / --domain)");
+  return { name, account: account.id, url, wranglerConfig, project: cloud };
+}

package/src/node/index.ts

@@ -0,0 +1,5 @@
+// voidbase as a library (Bun): PocketBase's server as a process you compose in your own main.ts.
+export { voidbase, serve, parseServeArgs, openLocal, type ServeOptions, type VoidbaseServer } from "./serve";
+export type { VoidbaseApp, HookGlobals } from "../server/api";
+export { RequestEvent } from "../server/hooks/runtime";
+export { HookRecord, CollectionRef } from "../server/hooks/record";

package/src/node/panel.ts

@@ -0,0 +1,21 @@
+// Where the unmodified PocketBase admin panel comes from: a synced public/_ in this checkout, else the pinned
+// release's committed ui/dist downloaded once into ~/.cache/voidbase.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+export const PANEL_VERSION = process.env.POCKETBASE_PANEL_VERSION ?? "0.40.2";
+export async function ensurePanelDir(): Promise<string> {
+  const local = [process.env.POCKETBASE_UI_DIST, resolve(import.meta.dir, "../../public/_"), resolve(import.meta.dir, "../../../pocketbase/ui/dist")].filter((p): p is string => !!p);
+  for (const p of local) if (existsSync(`${p}/index.html`)) return p;
+  const cache = resolve(`${process.env.XDG_CACHE_HOME ?? `${process.env.HOME}/.cache`}/voidbase/panel-${PANEL_VERSION}`);
+  if (existsSync(`${cache}/index.html`)) return cache;
+  console.log(`voidbase: downloading the PocketBase ${PANEL_VERSION} admin panel (ui/dist) into ${cache}`);
+  const res = await fetch(`https://codeload.github.com/pocketbase/pocketbase/tar.gz/refs/tags/v${PANEL_VERSION}`);
+  if (!res.ok) throw new Error(`panel download failed: HTTP ${res.status} (set POCKETBASE_UI_DIST to a local ui/dist)`);
+  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`]);
+  rmSync(tgz, { force: true });
+  if (tar.exitCode !== 0) throw new Error(new TextDecoder().decode(tar.stderr));
+  writeFileSync(`${cache}/extensions.js`, "// voidbase: no UI extensions configured\n");
+  return cache;
+}

package/src/node/serve.ts

@@ -0,0 +1,125 @@
+// `voidbase serve`: the PocketBase-shaped single process. The same Hono app that runs on Cloudflare, with D1 on
+// bun:sqlite, R2 on the filesystem, SMTP on node sockets and the cron scheduler on a timer.
+//   import { serve } from "@voidbase-cloud/voidbase";  serve({ http: "127.0.0.1:8090", dir: "pb_data", publicDir: "../sk/build" });
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { d1, openDatabase } from "./d1";
+import { fsBucket } from "./storage";
+import { assetsFetcher } from "./assets";
+import { ensurePanelDir } from "./panel";
+
+export interface ServeOptions { http?: string; dir?: string; hooksDir?: string; migrationsDir?: string; publicDir?: string; quiet?: boolean }
+const PKG = resolve(import.meta.dir, "../..");
+
+// system tables: the same SQL migrations Void applies on Cloudflare
+export function applySystemMigrations(db: ReturnType<typeof openDatabase>): number {
+  db.exec("CREATE TABLE IF NOT EXISTS `_vb_migrations` (name TEXT PRIMARY KEY, applied TEXT NOT NULL)");
+  const done = new Set((db.query("SELECT name FROM `_vb_migrations`").all() as { name: string }[]).map((r) => r.name));
+  let applied = 0;
+  for (const f of readdirSync(`${PKG}/db/migrations`).filter((f) => f.endsWith(".sql")).sort()) {
+    if (done.has(f)) continue;
+    db.transaction(() => {
+      for (const statement of readFileSync(`${PKG}/db/migrations/${f}`, "utf8").split("--> statement-breakpoint")) if (statement.trim()) db.exec(statement);
+      db.query("INSERT INTO `_vb_migrations` (name, applied) VALUES (?, ?)").run(f, new Date().toISOString());
+    })();
+    applied++;
+  }
+  return applied;
+}
+
+// Opens (and prepares) a data directory without serving: bindings for the CLI and for embedding.
+// Bun loads ./.env itself; a project that keeps its environment one level up (the SvelteKit starter) gets that too.
+// PB_* names from the PocketBase starter convention are accepted as aliases of the VOIDBASE_* ones.
+const ENV_ALIASES: Record<string, string> = { PB_SUPERUSER_EMAIL: "VOIDBASE_SUPERUSER_EMAIL", PB_SUPERUSER_PASSWORD: "VOIDBASE_SUPERUSER_PASSWORD", PB_USER_EMAIL: "VOIDBASE_USER_EMAIL", PB_USER_PASSWORD: "VOIDBASE_USER_PASSWORD", PB_ENCRYPTION_KEY: "VOIDBASE_ENCRYPTION_KEY" };
+export function loadEnv(files = [".env", ".env.local", "../.env", "../.env.local"]): void {
+  for (const f of files) {
+    if (!existsSync(f)) continue;
+    for (const line of readFileSync(f, "utf8").split("\n")) {
+      const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*?)\s*$/.exec(line); if (!m) continue;
+      const key = m[1]!; const value = m[2]!.replace(/^(['"])(.*)\1$/, "$2");
+      if (!process.env[key]) process.env[key] = value;
+    }
+  }
+  for (const [alias, key] of Object.entries(ENV_ALIASES)) if (!process.env[key] && process.env[alias]) process.env[key] = process.env[alias];
+}
+
+export async function openLocal(opts: ServeOptions) {
+  loadEnv();
+  const dir = resolve(opts.dir ?? "pb_data");
+  mkdirSync(dir, { recursive: true });
+  process.env.VOIDBASE_HOOKS_DIR = resolve(opts.hooksDir ?? process.env.VOIDBASE_HOOKS_DIR ?? "pb_hooks");
+  process.env.VOIDBASE_MIGRATIONS_DIR = resolve(opts.migrationsDir ?? process.env.VOIDBASE_MIGRATIONS_DIR ?? "pb_migrations");
+  // pb_data/types.d.ts for editor support in pb_hooks (PocketBase's JSVM typings)
+  try { if (!existsSync(`${dir}/types.d.ts`)) copyFileSync(`${PKG}/types/pb_data.d.ts`, `${dir}/types.d.ts`); } catch { /* optional */ }
+  const sqlite = openDatabase(`${dir}/data.db`);
+  applySystemMigrations(sqlite);
+  const env = { DB: d1(sqlite), STORAGE: fsBucket(`${dir}/storage`), ASSETS: assetsFetcher({ panelDir: await ensurePanelDir(), publicDir: opts.publicDir ? resolve(opts.publicDir) : undefined }) };
+  return { dir, sqlite, env };
+}
+
+export interface VoidbaseServer { server: ReturnType<typeof Bun.serve>; env: Awaited<ReturnType<typeof openLocal>>["env"]; stop: () => void }
+
+// The library entry: `const app = await voidbase(opts); register things; await app.start()` (main.go's shape).
+export async function voidbase(opts: ServeOptions = {}) {
+  const { dir, env } = await openLocal(opts);
+  // the app module reads the hooks and migrations directories while loading
+  const { app } = await import("../server/app");
+  const { appApi } = await import("../server/api");
+  const api = appApi();
+  const start = async (): Promise<VoidbaseServer> => {
+    const [hostname, portStr] = (opts.http ?? "127.0.0.1:8090").split(":");
+    const port = Number(portStr ?? 8090);
+    const { runDue } = await import("../server/crons");
+    const { staticFallback } = await import("../server/static");
+    const ctx = { waitUntil: (p: Promise<unknown>) => { Promise.resolve(p).catch((e) => console.error("voidbase: background task failed", e)); }, passThroughOnException() {} };
+    const server = Bun.serve({
+      hostname, port, idleTimeout: 255,
+      async fetch(req) {
+        const res = await app.fetch(req, env, ctx as never);
+        if (res.status !== 404) return res;
+        return (await staticFallback(req, env.ASSETS)) ?? res;
+      },
+    });
+    // cron: every minute on the minute, like the Cloudflare trigger
+    const tick = () => runDue(env as never, new Date()).catch((e) => console.error("voidbase: cron failed", e));
+    const first = 60_000 - (Date.now() % 60_000);
+    const timer = setTimeout(() => { void tick(); setInterval(() => void tick(), 60_000); }, first);
+    if (!opts.quiet) {
+      const shown = hostname === "0.0.0.0" ? "127.0.0.1" : hostname;
+      console.log(`voidbase (data: ${dir}, hooks: ${process.env.VOIDBASE_HOOKS_DIR})`);
+      console.log(`Server started at http://${shown}:${port}\n├─ REST API:  http://${shown}:${port}/api/\n└─ Dashboard: http://${shown}:${port}/_/`);
+    }
+    // bootstrap now (system collections, settings, superuser from env, pb_migrations) instead of on the first request
+    await fetch(`http://127.0.0.1:${port}/api/health`).catch(() => undefined);
+    await seedUser(port);
+    return { server, env, stop: () => { clearTimeout(timer); server.stop(true); } };
+  };
+  return { ...api, env, dir, start };
+}
+
+// VOIDBASE_USER_EMAIL / VOIDBASE_USER_PASSWORD: a test user in the `users` collection, created once (the starter's
+// entrypoint used to do this with curl)
+async function seedUser(port: number): Promise<void> {
+  const email = process.env.VOIDBASE_USER_EMAIL, password = process.env.VOIDBASE_USER_PASSWORD;
+  const su = process.env.VOIDBASE_SUPERUSER_EMAIL, suPass = process.env.VOIDBASE_SUPERUSER_PASSWORD;
+  if (!email || !password || !su || !suPass) return;
+  const base = `http://127.0.0.1:${port}`;
+  const json = (r: Response) => r.json() as Promise<Record<string, unknown>>;
+  const auth = await fetch(`${base}/api/collections/_superusers/auth-with-password`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ identity: su, password: suPass }) }).then(json).catch(() => null);
+  const token = auth?.token ? String(auth.token) : ""; if (!token) return;
+  const existing = await fetch(`${base}/api/collections/users/records?perPage=1&filter=${encodeURIComponent(`email = '${email.replace(/'/g, "\\'")}'`)}`, { headers: { authorization: token } }).then(json).catch(() => null);
+  if (!existing || Number(existing.totalItems ?? 0) > 0 || existing.status === 404) return;
+  const r = await fetch(`${base}/api/collections/users/records`, { method: "POST", headers: { "content-type": "application/json", authorization: token }, body: JSON.stringify({ email, password, passwordConfirm: password }) });
+  console.log(r.status === 200 ? `voidbase: created user ${email}` : `voidbase: could not create user ${email}: ${r.status}`);
+}
+
+export async function serve(opts: ServeOptions = {}): Promise<VoidbaseServer> {
+  return (await voidbase(opts)).start();
+}
+
+// `pocketbase serve`-style flags: --http host:port --dir --hooksDir --migrationsDir --publicDir
+export function parseServeArgs(argv: string[] = process.argv.slice(2)): ServeOptions {
+  const flags: Record<string, 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"); } }
+  return { http: flags.http, dir: flags.dir, hooksDir: flags.hooksDir, migrationsDir: flags.migrationsDir, publicDir: flags.publicDir };
+}

package/src/node/storage.ts

@@ -0,0 +1,51 @@
+/// <reference types="@cloudflare/workers-types" />
+// R2Bucket on the filesystem: keys are paths under the root, object metadata lives in .meta/<key>.json.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+interface Meta { contentType?: string; uploaded: string; etag: string; size: number }
+interface Obj { key: string; size: number; uploaded: Date; etag: string; httpMetadata: { contentType?: string } }
+export class FsBucket {
+  constructor(private root: string) { mkdirSync(join(root, ".meta"), { recursive: true }); }
+  private path(key: string) { return join(this.root, key); }
+  private metaPath(key: string) { return join(this.root, ".meta", `${key}.json`); }
+  private meta(key: string): Meta | null { try { return JSON.parse(readFileSync(this.metaPath(key), "utf8")) as Meta; } catch { return null; } }
+  private obj(key: string): Obj | null {
+    const p = this.path(key); if (!existsSync(p) || !statSync(p).isFile()) return null;
+    const m = this.meta(key); const st = statSync(p);
+    return { key, size: st.size, uploaded: new Date(m?.uploaded ?? st.mtimeMs), etag: m?.etag ?? String(st.mtimeMs), httpMetadata: { contentType: m?.contentType } };
+  }
+  async head(key: string) { return this.obj(key); }
+  async get(key: string, opts?: { range?: { offset: number; length: number } }) {
+    const o = this.obj(key); if (!o) return null;
+    const file = Bun.file(this.path(key));
+    const part = opts?.range ? file.slice(opts.range.offset, opts.range.offset + opts.range.length) : file;
+    return { ...o, body: part.stream(), arrayBuffer: () => part.arrayBuffer(), text: () => part.text(), json: <T>() => part.json() as Promise<T> };
+  }
+  async put(key: string, value: ArrayBuffer | Uint8Array | string | ReadableStream | Blob | null, opts?: { httpMetadata?: { contentType?: string } }) {
+    let bytes: Uint8Array;
+    if (value === null) bytes = new Uint8Array();
+    else if (typeof value === "string") bytes = new TextEncoder().encode(value);
+    else if (value instanceof Uint8Array) bytes = value;
+    else if (value instanceof ArrayBuffer) bytes = new Uint8Array(value);
+    else if (value instanceof Blob) bytes = new Uint8Array(await value.arrayBuffer());
+    else bytes = new Uint8Array(await new Response(value).arrayBuffer());
+    mkdirSync(dirname(this.path(key)), { recursive: true }); mkdirSync(dirname(this.metaPath(key)), { recursive: true });
+    writeFileSync(this.path(key), bytes);
+    const meta: Meta = { contentType: opts?.httpMetadata?.contentType, uploaded: new Date().toISOString(), etag: Bun.hash(bytes).toString(16), size: bytes.byteLength };
+    writeFileSync(this.metaPath(key), JSON.stringify(meta));
+    return { key, size: meta.size, uploaded: new Date(meta.uploaded), etag: meta.etag, httpMetadata: { contentType: meta.contentType } };
+  }
+  async delete(keys: string | string[]) {
+    for (const key of Array.isArray(keys) ? keys : [keys]) { rmSync(this.path(key), { force: true }); rmSync(this.metaPath(key), { force: true }); }
+  }
+  async list(opts: { prefix?: string; cursor?: string; limit?: number } = {}) {
+    const keys: string[] = [];
+    const walk = (dir: string) => { if (!existsSync(dir)) return; for (const e of readdirSync(dir, { withFileTypes: true })) { if (dir === this.root && e.name === ".meta") continue; const p = join(dir, e.name); if (e.isDirectory()) walk(p); else keys.push(relative(this.root, p).split("\\").join("/")); } };
+    walk(this.root);
+    const prefix = opts.prefix ?? ""; const limit = opts.limit ?? 1000;
+    const all = keys.filter((k) => k.startsWith(prefix) && (!opts.cursor || k > opts.cursor)).sort();
+    const page = all.slice(0, limit);
+    return { objects: page.map((k) => this.obj(k)!).filter(Boolean), truncated: all.length > limit, cursor: all.length > limit ? page.at(-1) : undefined, delimitedPrefixes: [] as string[] };
+  }
+}
+export const fsBucket = (root: string) => new FsBucket(root) as unknown as R2Bucket;

package/src/platform/node/env.ts

@@ -0,0 +1,4 @@
+// Process environment (Bun loads .env files itself)
+export const env = process.env as Record<string, string | undefined>;
+// a local SQLite file is cheap: log every request like PocketBase does
+export const defaultLogMinLevel = 0;

package/src/platform/node/hooks.ts

@@ -0,0 +1,19 @@
+// pb_hooks compiled at startup (the same transform the Vite plugin applies at build time) and imported as a module.
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { compileHooksDir } from "../../../hooks-plugin";
+const dir = resolve(process.env.VOIDBASE_HOOKS_DIR ?? "pb_hooks");
+export async function loadCompiled(code: string, tag: string) {
+  const out = join(tmpdir(), "voidbase"); mkdirSync(out, { recursive: true });
+  const file = join(out, `${tag}-${createHash("sha256").update(code).digest("hex").slice(0, 16)}.mjs`);
+  writeFileSync(file, code);
+  return import(pathToFileURL(file).href);
+}
+const mod = await loadCompiled(compileHooksDir(dir), "hooks");
+export const hooksDir: string = mod.hooksDir;
+export const hooks: { name: string; run: (globals: Record<string, unknown>) => Promise<void> }[] = mod.hooks;
+export const modules: Record<string, (globals: Record<string, unknown>) => Promise<unknown>> = mod.modules;
+export const files: Record<string, string> = mod.files;

package/src/platform/node/log.ts

@@ -0,0 +1,7 @@
+// One JSON line per call, like void/log, so `voidbase serve` logs stay greppable
+const line = (level: string, message: string, fields?: Record<string, unknown>) => console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](JSON.stringify({ level, message, time: new Date().toISOString(), ...(fields ?? {}) }));
+export const logger = {
+  error: (message: string, fields?: Record<string, unknown>) => line("error", message, fields),
+  warn: (message: string, fields?: Record<string, unknown>) => line("warn", message, fields),
+  info: (message: string, fields?: Record<string, unknown>) => line("info", message, fields),
+};

package/src/platform/node/migrations.ts

@@ -0,0 +1,5 @@
+import { resolve } from "node:path";
+import { compileMigrationsDir } from "../../../hooks-plugin";
+import { loadCompiled } from "./hooks";
+const mod = await loadCompiled(compileMigrationsDir(resolve(process.env.VOIDBASE_MIGRATIONS_DIR ?? "pb_migrations")), "migrations");
+export const migrations: { name: string; run: (globals: Record<string, unknown>) => Promise<void> }[] = mod.migrations;

package/src/platform/node/photon.ts

@@ -0,0 +1 @@
+export { PhotonImage, SamplingFilter, crop, resize } from "@cf-wasm/photon/node";

package/src/platform/node/sockets.ts

@@ -0,0 +1,22 @@
+// cloudflare:sockets `connect` on node:net / node:tls (Bun): readable/writable web streams and STARTTLS upgrade.
+import net from "node:net";
+import tls from "node:tls";
+export interface Socket { readable: ReadableStream<Uint8Array>; writable: WritableStream<Uint8Array>; closed: Promise<void>; close(): void; startTls(): Socket }
+function wrap(sock: net.Socket, host: string): Socket {
+  let ctrl: ReadableStreamDefaultController<Uint8Array> | null = null;
+  const onData = (d: Buffer) => { try { ctrl?.enqueue(new Uint8Array(d)); } catch { /* closed */ } };
+  const onEnd = () => { try { ctrl?.close(); } catch { /* closed */ } };
+  const onError = (e: Error) => { try { ctrl?.error(e); } catch { /* closed */ } };
+  const readable = new ReadableStream<Uint8Array>({ start(c) { ctrl = c; sock.on("data", onData); sock.on("end", onEnd); sock.on("error", onError); } });
+  const writable = new WritableStream<Uint8Array>({ write(chunk) { return new Promise<void>((res, rej) => sock.write(chunk, (e) => (e ? rej(e) : res()))); }, close() { sock.end(); } });
+  return {
+    readable, writable,
+    closed: new Promise<void>((r) => sock.once("close", () => r())),
+    close() { sock.destroy(); },
+    startTls() { sock.off("data", onData); sock.off("end", onEnd); sock.off("error", onError); return wrap(tls.connect({ socket: sock, servername: host }), host); },
+  };
+}
+export function connect(addr: { hostname: string; port: number }, opts: { secureTransport?: "on" | "off" | "starttls"; allowHalfOpen?: boolean } = {}): Socket {
+  const sock = opts.secureTransport === "on" ? tls.connect({ host: addr.hostname, port: addr.port, servername: addr.hostname }) : net.connect({ host: addr.hostname, port: addr.port });
+  return wrap(sock, addr.hostname);
+}

package/src/platform/node/sse.ts

@@ -0,0 +1,23 @@
+// Server-sent events on a plain Response stream (the same surface as void/sse's eventStream).
+export interface SSEStream { send(msg: { id?: string; event?: string; data: unknown }): Promise<void>; closed: Promise<void>; close(): void }
+export function eventStream(handler: (stream: SSEStream) => Promise<void>, opts: { signal?: AbortSignal; keepAlive?: { intervalMs: number; comment?: string } } = {}): Response {
+  const enc = new TextEncoder();
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let done = false; let resolveClosed = () => {};
+  const closed = new Promise<void>((r) => { resolveClosed = r; });
+  const finish = () => { if (done) return; done = true; if (keepAlive) clearInterval(keepAlive); resolveClosed(); try { controller?.close(); } catch { /* already closed */ } };
+  const write = (s: string) => { if (done) return; try { controller!.enqueue(enc.encode(s)); } catch { finish(); } };
+  const body = new ReadableStream<Uint8Array>({ start(c) { controller = c; }, cancel() { finish(); } });
+  const keepAlive = opts.keepAlive ? setInterval(() => write(`: ${opts.keepAlive!.comment ?? ""}\n\n`), opts.keepAlive.intervalMs) : null;
+  opts.signal?.addEventListener("abort", finish);
+  const stream: SSEStream = {
+    async send({ id, event, data }) {
+      let msg = ""; if (id) msg += `id: ${id}\n`; if (event) msg += `event: ${event}\n`;
+      for (const l of (typeof data === "string" ? data : JSON.stringify(data)).split("\n")) msg += `data: ${l}\n`;
+      write(msg + "\n");
+    },
+    closed, close: finish,
+  };
+  handler(stream).catch((e) => console.error("voidbase: sse handler failed", e)).finally(finish);
+  return new Response(body, { status: 200, headers: { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-store", connection: "keep-alive" } });
+}

package/src/platform/workers/env.ts

@@ -0,0 +1,3 @@
+export { env } from "void/env";
+// on Cloudflare every request log is a billed D1 row: only warnings and errors by default (VOIDBASE_LOG_MIN_LEVEL overrides)
+export const defaultLogMinLevel = 4;

package/src/platform/workers/hooks.ts

@@ -0,0 +1,2 @@
+// pb_hooks bundled at build time by hooks-plugin.ts (virtual module)
+export { files, hooks, hooksDir, modules } from "virtual:voidbase-hooks";

package/src/platform/workers/log.ts

@@ -0,0 +1 @@
+export { logger } from "void/log";

package/src/platform/workers/migrations.ts

@@ -0,0 +1 @@
+export { migrations } from "virtual:voidbase-migrations";

package/src/platform/workers/photon.ts

@@ -0,0 +1 @@
+export { PhotonImage, SamplingFilter, crop, resize } from "@cf-wasm/photon";

package/src/platform/workers/sockets.ts

@@ -0,0 +1,3 @@
+export { connect } from "cloudflare:sockets";
+// the global Socket interface from @cloudflare/workers-types
+export type Socket = globalThis.Socket;

package/src/platform/workers/sse.ts

@@ -0,0 +1 @@
+export { eventStream } from "void/sse";

package/src/server/api.ts

@@ -0,0 +1,27 @@
+// The programmatic API a project's main.ts receives (the counterpart of `pocketbase.New()` + app.OnServe() in Go):
+// the same hook functions the JS hooks see ($app, $apis, routerAdd, cronAdd, on* events, Record, ...) plus the
+// Hono router for raw routes. Registrations made here are committed with commit() before requests are served.
+import type { Context, Hono } from "hono";
+import { app } from "./app";
+import { hookGlobals } from "./hooks";
+import type { RequestEvent } from "./hooks/runtime";
+import type { AppEnv } from "./types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HookGlobals = Record<string, any>;
+/** Hono-style handlers (c: Context) on any path, registered at any time; served after PocketBase's own routes. */
+export interface LateRouter { get: LateRegister; post: LateRegister; patch: LateRegister; put: LateRegister; delete: LateRegister; all: LateRegister }
+type LateRegister = (path: string, handler: (c: Context<AppEnv>) => Response | Promise<Response>) => void;
+export interface VoidbaseApp {
+  /** app.router.get("/api/x", (c) => c.json(...)): Hono-style routes, usable before or after the JS hooks loaded */
+  router: LateRouter;
+  /** the Hono instance itself (routes added here must be added before the first request) */
+  hono: Hono<AppEnv>;
+  /** $app, $apis, $os, $security, routerAdd, routerUse, cronAdd, cronRemove, on* event registrations, Record, Collection, ... */
+  hooks: HookGlobals;
+}
+export function appApi(): VoidbaseApp {
+  const hooks = hookGlobals() as HookGlobals;
+  const late = (method: string): LateRegister => (path, handler) => hooks.routerAdd(method, path, (e: RequestEvent) => handler(e.c));
+  return { router: { get: late("GET"), post: late("POST"), patch: late("PATCH"), put: late("PUT"), delete: late("DELETE"), all: late("ALL") }, hono: app, hooks };
+}