@voidbase-cloud/voidbase 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 Entries after 0.1.0 are compiled by release-please from the Conventional Commits merged since the previous release
 (docs/releasing.md); 0.1.0 was written by hand.
 
+## [0.4.0](https://github.com/voidbase-cloud/voidbase/compare/v0.3.0...v0.4.0) (2026-09-07)
+
+
+### Features
+
+* **deploy:** one configuration declaration with Void's validators, tiered secret / server / public ([e5ee202](https://github.com/voidbase-cloud/voidbase/commit/e5ee20261520fbfba8e90d80ff4f7aa07bf6bc78))
+
+## [0.3.0](https://github.com/voidbase-cloud/voidbase/compare/v0.2.2...v0.3.0) (2026-09-07)
+
+
+### Features
+
+* **adapter:** build a Void app into a voidbase app ([e1e221b](https://github.com/voidbase-cloud/voidbase/commit/e1e221b1df4b70b6b513a4ce5c665ed73a40efe8))
+* **adapter:** compile routes, middleware, crons and queues into pb_hooks ([3837897](https://github.com/voidbase-cloud/voidbase/commit/383789715e53a3467a0f7203df06bcd5b31fa491))
+* **adapter:** generate a whole voidbase app into .voidbase/ ([d11db67](https://github.com/voidbase-cloud/voidbase/commit/d11db674fea39954ca8afe8844ec2108040bd944))
+* **adapter:** PocketBase's API inside a Void route ([d6008cc](https://github.com/voidbase-cloud/voidbase/commit/d6008cc0d34a8a857965725efc83dcc76c4c8862))
+* **adapter:** vb_hooks/ and vb_migrations/ as project-root source ([fd861b0](https://github.com/voidbase-cloud/voidbase/commit/fd861b05afcc744481a0453a40a54149d1cd0c7e))
+* **adapter:** vb_hooks/ for PocketBase's event hooks, middleware/ through routerUse ([2baad03](https://github.com/voidbase-cloud/voidbase/commit/2baad03f6f03c57cd98d036b3e8ede6b9d5fe2d0))
+* **adapter:** vb_secrets/, the secrets a Void app declares ([a1fda2b](https://github.com/voidbase-cloud/voidbase/commit/a1fda2b4e17029b1db4380cfa118545b3e0efca8))
+* **deploy:** _redirects in the public dir become Void edge redirects ([8c43427](https://github.com/voidbase-cloud/voidbase/commit/8c434270bcf7e92731d90f1aaaee9c3cea3b89e6))
+* **deploy:** _redirects in the public dir become Void edge redirects ([bf873b4](https://github.com/voidbase-cloud/voidbase/commit/bf873b4ef45806646ee4ee8a80ecbbba5e70307c))
+* **deploy:** host-scoped _redirects become zone Redirect Rules ([cd1f8f7](https://github.com/voidbase-cloud/voidbase/commit/cd1f8f7e0080e55656a905c2c861eb923f624be7))
+* **deploy:** pb_secrets/, the app's secrets declared in git and valued outside it ([da8e4c6](https://github.com/voidbase-cloud/voidbase/commit/da8e4c636ed1b0b67cbfd61b6b6f2030fbdaaa08))
+* **deploy:** serve ./pb_public by default and attach several custom domains ([c8d39bd](https://github.com/voidbase-cloud/voidbase/commit/c8d39bd77ee5ef8e9a2a1c40348ea2715c6c4c18))
+* **deploy:** VOIDBASE_DEPLOY_ZONE_TOKEN for the zone redirect rules ([6013d48](https://github.com/voidbase-cloud/voidbase/commit/6013d485be4886f25096229d74309993a2260e16))
+* **hooks:** routerUse is PocketBase's global middleware, around every request ([12eaa8a](https://github.com/voidbase-cloud/voidbase/commit/12eaa8ab43214d72c225dc25ffb8411b2838978f))
+* **serve:** resolve an extensionless path against <path>.html ([5b7bb26](https://github.com/voidbase-cloud/voidbase/commit/5b7bb26b006d0c0cd5573d1cde99cd457175e5b4))
+
+
+### Bug Fixes
+
+* **adapter:** report once per build, not once per Vite environment ([a593b1b](https://github.com/voidbase-cloud/voidbase/commit/a593b1b55a99be6fe1b7cd8b148b1d6c357f48c0))
+* **adapter:** the generated entry finds its own directories ([3ec53cf](https://github.com/voidbase-cloud/voidbase/commit/3ec53cfe7039cd95efece83f2caf535626b56027))
+* **auth:** reject non-canonical base64url token segments like PocketBase ([7d00575](https://github.com/voidbase-cloud/voidbase/commit/7d005752598e640663dfa7cfa69321032ceb7fd2))
+* **ci:** read every pushed commit on a shallow checkout ([11acdf3](https://github.com/voidbase-cloud/voidbase/commit/11acdf39b040c8b280e4d5e292db4ddb24aa3060))
+* **cloud:** detach the queue consumer before destroying an instance ([2eb5797](https://github.com/voidbase-cloud/voidbase/commit/2eb579797351812b8322582f99a9731556947466))
+* **deploy:** a deploy never replaces a secret the Worker already has ([63cc651](https://github.com/voidbase-cloud/voidbase/commit/63cc65148b4bf2bc229c1ec4e7a8a5d2c20e4cfd))
+* **deploy:** one token; name the zone permission the redirect rules need ([16d0537](https://github.com/voidbase-cloud/voidbase/commit/16d0537589e6ca354b4220f50600d0569c2a12de))
+* **deploy:** secrets.json outranks the .env files ([9df1802](https://github.com/voidbase-cloud/voidbase/commit/9df180212dc0027210cb6f589856da972fa3cce9))
+
+
+### Performance
+
+* **auth:** passkey routes in every app, gated on a passkeys collection, loaded on first use ([77af85e](https://github.com/voidbase-cloud/voidbase/commit/77af85e447fd971be4e06e272799268982f88eca))
+
+
+### Documentation
+
+* **ci:** the reference is seeded fresh per run and before the Bun pass ([d3f6d0c](https://github.com/voidbase-cloud/voidbase/commit/d3f6d0c29b35e42b2738faf2f258e9177bebe17e))
+* **deploy:** the site's control plane moved to voidbase-site/cloud ([66f2e8c](https://github.com/voidbase-cloud/voidbase/commit/66f2e8c41fe4f66123534e338610d0975d2dcb10))
+* **surface:** CI live on Cloudflare with incremental runs ([82a5461](https://github.com/voidbase-cloud/voidbase/commit/82a5461b0af283efa34f32c02c0691c12b927bff))
+* **surface:** one CI project on Cloudflare, hot mode and incremental runs ([4665543](https://github.com/voidbase-cloud/voidbase/commit/46655431b081677d1e461f78977ceac1886d94fa))
+* **surface:** the Void adapter ([0228acb](https://github.com/voidbase-cloud/voidbase/commit/0228acb4d7e8105a864c32a48db80bc0f68b3ff1))
+
 ## [0.2.2](https://github.com/voidbase-cloud/voidbase/compare/v0.2.1...v0.2.2) (2026-09-06)
 
 

package/README.md

@@ -1,5 +1,7 @@
 # voidbase
 
+[![ci](https://release.voidbase.cloud/badge.svg)](https://release.voidbase.cloud/) The status page of the last green build: every step, every suite, the screenshots.
+
 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.
 
@@ -36,8 +38,8 @@ platform, verifies its checksum and replaces the executable (`--backup` zips `pb
 toolchain (`deploy`, `bundle`, `dev`) stays with the npm package.
 
 Commits follow Conventional Commits (enforced by husky and CI); release-please turns them into a release PR,
-and merging it publishes to npm (with provenance once the repository is public) and GitHub Packages with the
-compiled notes; see [docs/releasing.md](docs/releasing.md).
+and merging it publishes to npm and GitHub Packages and attaches the executables, with the compiled notes; see
+[docs/releasing.md](docs/releasing.md).
 
 ## Run it like PocketBase
 
@@ -101,14 +103,21 @@ provider variables.
 
 `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).
+inside the package (`node_modules/voidbase/.cloud/<name>`), stores the superuser and what `pb_secrets/` declares
+as the Worker's secrets and vars, and uploads the Worker. Your directory stays `pb_hooks` + `pb_migrations` +
+`pb_secrets` + `pb_data`, like a PocketBase folder: `pb_secrets/main.ts` declares the configuration with Void's
+validators (secret, server or public), the git-ignored `pb_secrets/secrets.json` holds the local values, and CI
+deploys with nothing but the deploy token once `voidbase secrets push` has stored the secrets. 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.
+`scripts/ci.sh` is the whole CI (`bun run ci` on a dev machine): it fetches the starter, syncs the panel, starts
+voidbase and a seeded reference PocketBase (`scripts/seed-reference.sh`), runs every suite through
+`scripts/ci-suites.sh` on the Workers and Bun runtimes, then the production-build boots, the prebuilt executable and
+the starter smoke, and renders the status page at [release.voidbase.cloud](https://release.voidbase.cloud/).
+Cloudflare Workers Builds runs it (`scripts/cf-builds.ts setup`); `.github/workflows/cloudflare.yml` only starts the
+builds; see [docs/ci.md](docs/ci.md).
 
 ## Docs
 

package/bin/voidbase.ts

@@ -18,26 +18,34 @@ 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 serveOpts = () => ({ http: flags.http, dir: flags.dir, hooksDir: flags.hooksDir, migrationsDir: flags.migrationsDir, secretsDir: flags.secretsDir, 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]
+  serve [--http 127.0.0.1:8090] [--dir pb_data] [--hooksDir pb_hooks] [--migrationsDir pb_migrations] [--secretsDir pb_secrets] [--publicDir pb_public] [--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
+  adapt [dir] [--public-dir .voidbase/pb_public] [--no-migrations]
+                                     generate a voidbase app under .voidbase/ from a Void app: PocketBase's layout
+                                     (main.ts, package.json, pb_hooks, pb_migrations, pb_public) with the project's
+                                     routes/middleware/crons/queues and whatever src/voidbase/ adds. vite build does
+                                     this too through the voidbaseAdapter() plugin; this is the same pass without Vite.
+  init [dir]                         scaffold .env, pb_hooks/, pb_migrations/, pb_secrets/ 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]
+  deploy [--name worker] [--account id] [--domain example.com,api.example.com] [--public-dir pb_public] [--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
+  secrets [list] [--dir pb_secrets]  what pb_secrets/main.ts declares (secret / server / public), which have a value in
+  secrets push [--name worker]       secrets.json (git-ignored) or a default, which secrets the Worker has; push stores the
+                                     local secrets on the Worker (vars are set by every deploy)
   update [--dir pb_data] [--backup]  prebuilt executable only: fetch the latest GitHub release for this platform, verify
                                      its checksum and replace the executable (--backup zips pb_data first)
   version                            print the version
@@ -78,6 +86,39 @@ switch (cmd) {
     await update({ currentVersion: await currentVersion(), dataDir: resolve(flags.dir ?? "pb_data"), backup: !!flags.backup });
     break;
   }
+  case "secrets": {
+    // pb_secrets/ (src/node/secrets.ts): what is declared, what has a value here, what the Worker has; push the values
+    const { secretsState, putWorkerSecrets, workerSecretNames, SECRETS_DIR } = await import("../src/node/secrets");
+    const { deployTarget } = await import("../src/node/deploy-cf");
+    const dir = resolve(flags.dir ?? process.env.VOIDBASE_SECRETS_DIR ?? SECRETS_DIR);
+    const state = await secretsState(dir);
+    if (!state.definition) { console.log(`${dir}/main.ts does not exist: nothing declared (voidbase init writes one)`); break; }
+    const def = state.definition; const secretNames = def.of("secret");
+    if (sub === "push") {
+      const { api, account, name } = await deployTarget({ name: flags.name, account: flags.account, log: () => undefined });
+      // only the secret tier is pushed: vars are the code's, set by every deploy
+      const ev = await def.evaluate({ ...(state.values ?? {}) }, ["secret"]);
+      if (ev.invalid.length) throw new Error(`${dir}/secrets.json: ${ev.invalid.map((i) => `${i.name}: ${i.message}`).join(", ")}`);
+      const values: Record<string, string> = {}; for (const k of secretNames) if (state.provided.includes(k) && ev.stored[k] !== undefined) values[k] = ev.stored[k]!;
+      if (!Object.keys(values).length) { console.log(`nothing to push: none of ${secretNames.join(", ") || "(no secrets declared)"} has a value in ${dir}/secrets.json`); break; }
+      const before = await workerSecretNames(api, account.id, name);
+      const done = await putWorkerSecrets(api, account.id, name, values).catch((e: Error) => { throw new Error(`${e.message}\n  (the Worker "${name}" must exist: voidbase deploy creates it and stores the secrets itself)`); });
+      console.log(`pushed ${done.length} secret(s) to worker "${name}" (account ${account.name}): ${done.map((k) => `${k}${before.includes(k) ? " (replaced)" : ""}`).join(", ")}`);
+      const left = secretNames.filter((k) => !values[k]); if (left.length) console.log(`no local value, left as they are: ${left.join(", ")}`);
+      break;
+    }
+    // list (default): a row per declared name
+    let onWorker: string[] | null = null; let worker = "";
+    try { const t = await deployTarget({ name: flags.name, account: flags.account, log: () => undefined }); worker = t.name; onWorker = await workerSecretNames(t.api, t.account.id, t.name); } catch { /* no token here: local view only */ }
+    console.log(`${dir}: ${def.names.length} declared (${secretNames.length} secret, ${def.of("server").length} server, ${def.of("public").length} public)${state.values ? `, ${state.provided.length} valued in secrets.json` : ", no secrets.json"}${onWorker ? `, worker "${worker}" has ${onWorker.filter((k) => secretNames.includes(k)).length} of the secrets` : " (set VOIDBASE_DEPLOY_CF_API_KEY to compare with the Worker)"}`);
+    for (const i of state.info) {
+      const where = state.provided.includes(i.name) ? "local value" : i.fallback !== undefined ? `default ${i.access === "secret" ? "(set)" : JSON.stringify(i.fallback)}` : i.optional ? "optional, unset" : "no local value";
+      const worker = onWorker && i.access === "secret" ? `  ${onWorker.includes(i.name) ? "on the worker" : "NOT on the worker"}` : "";
+      console.log(`  ${i.name.padEnd(30)} ${i.access.padEnd(7)} ${where.padEnd(18)}${worker}${i.description ? `  ${i.description}` : ""}`);
+    }
+    if (state.undeclared.length) console.log(`  in secrets.json but not declared (never deployed): ${state.undeclared.join(", ")}`);
+    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");
@@ -108,12 +149,32 @@ switch (cmd) {
     await new Promise(() => undefined);
     break;
   }
+  case "adapt": {
+    const { adapt } = await import("../src/adapter/index");
+    const root = resolve(sub ?? ".");
+    const { manifest, written, copied } = await adapt(root, { publicDir: flags["public-dir"], migrations: !flags["no-migrations"], quiet: true });
+    for (const u of manifest.unsupported) console.warn(`not carried over: ${u.what} — ${u.why}`);
+    for (const c of manifest.collisions) console.warn(`shadowed by voidbase's own API, the app route never runs: ${c}`);
+    console.log(`${manifest.mode === "static" ? "static" : "server"} app at ${root}`);
+    console.log(`  ${manifest.routes.length} route(s), ${manifest.middleware.length} middleware, ${manifest.hooks.length} hook(s), ${manifest.crons.length} cron(s), ${manifest.queues.length} queue(s), ${manifest.migrations.length} migration(s)${manifest.secrets ? `, ${manifest.secrets.names.length} secret(s)` : ""}`);
+    console.log(`  wrote ${written.join(", ") || "nothing"}${copied ? `, ${copied} entr(ies) into ${flags["public-dir"] ?? ".voidbase/pb_public"}` : ""}`);
+    console.log("  run it:    bun .voidbase/main.ts --http 127.0.0.1:8090");
+    console.log("  deploy it: cd .voidbase && voidbase deploy");
+    break;
+  }
   case "init": {
     const dir = resolve(sub ?? ".");
-    mkdirSync(`${dir}/pb_hooks`, { recursive: true }); mkdirSync(`${dir}/pb_migrations`, { recursive: true });
+    mkdirSync(`${dir}/pb_hooks`, { recursive: true }); mkdirSync(`${dir}/pb_migrations`, { recursive: true }); mkdirSync(`${dir}/pb_secrets`, { recursive: true });
+    { // pb_secrets/main.pb.js declares the secrets; secrets.json holds their values and never enters git
+      const { declarationScaffold } = await import("../src/node/secrets");
+      if (!existsSync(`${dir}/pb_secrets/main.ts`)) writeFileSync(`${dir}/pb_secrets/main.ts`, declarationScaffold());
+      const gi = `${dir}/.gitignore`; const have = existsSync(gi) ? await Bun.file(gi).text() : "";
+      const lines = ["pb_data/", "pb_secrets/secrets.json"].filter((l) => !have.split("\n").some((x) => x.trim() === l || x.trim() === l.replace(/\/$/, "")));
+      if (lines.length) writeFileSync(gi, `${have}${have && !have.endsWith("\n") ? "\n" : ""}${lines.join("\n")}\n`);
+    }
     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");
+    console.log("pb_hooks/, pb_migrations/ and pb_secrets/ ready (.gitignore covers pb_data/ and pb_secrets/secrets.json)");
     await run("bun", ["scripts/sync-panel.ts"]).catch(() => undefined);
     console.log("\nnext: bun install && ./node_modules/.bin/void db migrate && voidbase dev");
     break;

package/docs/adapter.md

@@ -0,0 +1,280 @@
+# Running a Void app on voidbase
+
+A [Void](https://void.cloud) app and a voidbase app are shaped differently. Void puts server code in `routes/`,
+`middleware/`, `crons/` and `queues/` and builds a Cloudflare Worker; voidbase is a PocketBase project, with the
+site in `pb_public/`, JS hooks in `pb_hooks/` and migrations in `pb_migrations/`. The adapter keeps the project a
+plain Void app and *generates* the voidbase one from it, whole, into a git-ignored `.voidbase/`.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { voidPlugin } from "void";
+import { voidbaseAdapter } from "@voidbase-cloud/voidbase/adapter/plugin";
+
+export default defineConfig({ plugins: [voidPlugin(), voidbaseAdapter()] });
+```
+
+`vite build` then writes [PocketBase's minimal layout](https://pocketbase.io/docs/going-to-production/#minimal-setup):
+
+```
+.voidbase/            generated; add it to .gitignore
+  main.ts             voidbase composed with the project's server code
+  package.json
+  .gitignore          pb_data/
+  pb_hooks/           routes/, middleware/, vb_hooks/, crons/ and queues/, compiled
+  pb_migrations/      the project's vb_migrations/, plus one file per Drizzle migration
+  pb_secrets/         the project's vb_secrets/: the declaration re-exported, the local values beside it
+  pb_public/          the client build, served at /
+  pb_data/            created on first run
+  void-entry.ts       what the bundler builds into pb_hooks/void-app.js
+  tsconfig.json       the fragment the project's tsconfig extends
+  shim-db.ts          void/db and void/queues at runtime (see below)
+  shim-queues.ts
+```
+
+`voidbase adapt` does the same pass without Vite, which is what CI and a pure-API project need.
+
+```bash
+bun run build                              # or: bunx voidbase adapt
+bun .voidbase/main.ts --http 127.0.0.1:8090   # the site, /api, and the panel at /_/
+cd .voidbase && bunx voidbase deploy          # one Cloudflare Worker with all three
+```
+
+## What the project owns
+
+The project root is Void's, with three additions, all optional and all named for the voidbase thing they are:
+
+| path | what it does |
+| --- | --- |
+| `vb_hooks/` | PocketBase's hooks, one per file, registered once when the app mounts |
+| `vb_migrations/` | PocketBase JS migrations, copied into the generated `pb_migrations/` beside the ones generated from `db/migrations` |
+| `vb_secrets/` | `main.ts` declares the app's configuration with `defineSecrets` and Void's validators, tiered secret / server / public; `secrets.json` (git-ignored) holds the local values |
+
+They sit at the project root beside Void's own `db/`, which `vb_migrations/` is the counterpart of. Everything else
+is Void's, and means what Void means by it: `routes/`, `middleware/`, `crons/` and `queues/` are the server code,
+`src/` is library code they import, `pages/` and `public/` are the site.
+
+There is no hooks directory to write by hand: `routes/`, `middleware/`, `crons/` and `queues/` **are** the hooks.
+The adapter compiles them into `.voidbase/pb_hooks/`, so the generated app carries its whole route surface where a
+PocketBase app carries it.
+
+### How Void code becomes a hook
+
+A pb_hooks file runs in a sandbox with PocketBase's globals and a `require` that reaches only its sibling hook
+files. A Void route imports from npm. Three things close that gap:
+
+1. **One bundle.** `routes/`, `middleware/`, `vb_hooks/`, `crons/` and `queues/` are built into a single CommonJS file,
+   `pb_hooks/void-app.js`, with everything they import (Void's runtime, Drizzle, the app's own modules) inlined.
+   The `void` specifier is rewritten to `void/handler` so the Vite plugin does not come with it, and the tsconfig
+   aliases (`@schema`, the project's own `@/*`, and the `void/db` / `void/queues` shims) are applied by the
+   bundler, an alias pointing at a directory resolving to its index file.
+2. **No node builtins.** `node:async_hooks`, which Void's binding context needs, is rewritten to read
+   `globalThis.AsyncLocalStorage`; voidbase's hook runtime publishes it there on both runtimes. Any other builtin
+   fails the build with the name of the file that imported it.
+3. **No rewriting of the bundle.** Every hook file normally goes through an await-insertion pass that rewrites
+   calls by method name (`delete`, `next`, `send`), which would corrupt bundled code. The generated file opens with
+   `// voidbase:raw`, and the compiler leaves it alone.
+
+`pb_hooks/void-app.pb.js` is the small hook beside it: the one place the hook globals are in scope. It publishes
+them on `globalThis` and then requires the bundle, in that order, so `pb` already works while a module is being
+imported. `main.ts` is left with nothing but the runner.
+
+### Writing API logic
+
+`defineHandler` and `defineMiddleware` are how a voidbase app writes its API. A route that only needs Void's own
+runtime (`void/db`, `void/storage`) needs nothing else; one that reads or writes PocketBase collections imports
+PocketBase's API from the adapter, because a bundled route cannot import voidbase directly:
+
+```ts
+// routes/api/posts/[id].ts  ->  GET /api/posts/:id
+import { defineHandler } from "void";
+import { authOf, pb, requireAuth } from "@voidbase-cloud/voidbase/adapter";
+
+export const GET = defineHandler(requireAuth("users"), async (c) => {
+  const post = await pb.$app.findRecordById("posts", c.req.param("id"));
+  if (!post) throw new pb.NotFoundError("No such post.");
+  if (post.getString("owner") !== authOf(c)?.id) throw new pb.ForbiddenError();
+  return { post: post.publicExport() };
+});
+```
+
+| import | what it is |
+| --- | --- |
+| `pb.$app` | the data API: `findRecordById`, `findRecordsByFilter`, `save`, `delete`, `settings`, ... |
+| `pb.Record`, `pb.$apis`, `pb.$os` | the rest of the hook surface a route is likely to want |
+| `pb.BadRequestError` and friends | PocketBase's error classes, so a thrown error becomes the right HTTP response |
+| `authOf(c)` | the authenticated record, exactly as a hook's `e.auth` |
+| `requireAuth(...)`, `requireSuperuser()` | the Void-shaped counterparts of `$apis.requireAuth` and `requireSuperuserAuth` |
+
+### Hooks
+
+PocketBase's *event* hooks (`onBootstrap`, `onRecordCreate`, the mailer hooks) fire on a record or a lifecycle
+moment rather than on a URL, so they have no `routes/` equivalent. They go in `vb_hooks/`: one file, one hook,
+registered once when the app mounts, in file-name order.
+
+A file names its hook where the build can read it, without running anything:
+
+```ts
+// vb_hooks/10.audit.ts  ->  onRecordAfterCreateSuccess, limited to `posts`
+import { defineHook } from "@voidbase-cloud/voidbase/adapter";
+
+export default defineHook("onRecordAfterCreateSuccess", async (e) => {
+  await e.next();
+  console.log("created", e.record?.id);
+}, "posts");
+```
+
+The trailing arguments are PocketBase's tags, the collections the hook is limited to. `routerUse`, PocketBase's
+global request middleware, is a hook like any other and can be written here too, but Void already has a directory
+for that, and it means the same thing:
+
+```ts
+// middleware/20.trace.ts  ->  every request
+import { defineMiddleware } from "void";
+
+export default defineMiddleware(async (c, next) => {
+  await next();
+  c.res.headers.set("x-trace-id", crypto.randomUUID());
+});
+```
+
+Two build errors keep the two apart. **A `vb_hooks/` file attached to no hook fails**, by name: there is nowhere to
+register it, and silently dropping it would be worse. So does a name that is not one of PocketBase's hooks, and the
+error offers the nearest real ones. **A `defineHook` left in `middleware/` fails too**, and says to move it: Void's
+middleware is called with `(c, next)`, which is not what a hook handler expects.
+
+`pb` is also usable while a module is being imported, which is what lets a plain module under `src/` register
+something of its own. Void's build imports the same modules again to prerender the pages, with no PocketBase in the
+process, so a registration made then is held and replayed, or dropped with the process. Reading anything
+(`pb.$app` and the rest) outside a request, a cron tick or a hook still throws.
+
+
+### Configuration and secrets
+
+The app's configuration is declared in `vb_secrets/main.ts`, with the validators a Void `env.ts` uses, and valued in
+`vb_secrets/secrets.json`, which stays out of git (add it to `.gitignore`; the generated app's own `.gitignore`
+already lists its copy):
+
+```ts
+// vb_secrets/main.ts
+import { defineSecrets, describe, string, number, url } from "@voidbase-cloud/voidbase/secrets";
+
+export default defineSecrets({
+  SMTP_PASSWORD: describe(string().secret(), "the mail provider's SMTP password"),   // the Worker's secrets
+  MAX_INSTANCES: number().default(5),                                                 // a Worker var
+  PUBLIC_API_URL: url().optional().public(),                                          // a var the browser gets too
+});
+```
+
+One declaration serves the three places the app runs. The Worker: `voidbase deploy` stores secrets as the Worker's
+secrets and the rest as its vars, and refuses to deploy while a value is invalid or missing everywhere. The build:
+every `public` key is inlined into the client as `import.meta.env.KEY`, parsed and defaulted, and no other key can
+reach it. The static site therefore knows exactly what it was declared to know. Locally, `bun .voidbase/main.ts`
+parses `secrets.json` and the shell into the environment, defaults included. Routes and hooks read
+`c.env.SMTP_PASSWORD` or `pb.$os.getenv("SMTP_PASSWORD")`, or the typed values through the same declaration:
+
+```ts
+import config from "../../vb_secrets/main";
+const { MAX_INSTANCES } = await config.read((n) => pb.$os.getenv(n));   // a number, on both runtimes
+```
+
+The adapter writes a re-export into `.voidbase/pb_secrets/main.ts`, where `voidbase serve` and `voidbase deploy`
+look for the declaration, and copies `secrets.json` beside it. A value in `secrets.json` that `main.ts` does not
+declare fails the build, by name: it would silently never reach the Worker. Details, the tiers and the `voidbase
+secrets` commands: `docs/deploy.md`.
+
+## What maps to what
+
+| Void | voidbase | notes |
+| --- | --- | --- |
+| `index.html`, `public/`, the client build | `.voidbase/pb_public/` | served at `/`; `404.html` is copied from `index.html` so a deep link behaves the same on Bun and on the asset layer |
+| `routes/**/*.ts` | `.voidbase/pb_hooks/void-app.js` | `[id]` → `:id`, `[...rest]` → catch-all, `(group)/` stripped, `_file.ts` ignored, `.dev.ts` / `.prod.ts` honoured |
+| `middleware/*.ts` | `routerUse(...)`, in file order | every request, as in Void (see below) |
+| `vb_hooks/*.ts` | the hook each file names, registered once | `onBootstrap`, `onRecordCreate`, the mailer hooks |
+| `vb_secrets/main.ts` + `secrets.json` | `.voidbase/pb_secrets/main.ts` (a re-export) + `secrets.json` | secrets to the Worker's secrets, the rest to its vars, `public` keys into the client build (see below) |
+| `crons/*.ts` | `cronAdd(<file name>, cron, handler)` | listed by `GET /api/crons`, runnable with `POST /api/crons/<name>` |
+| `queues/*.ts` | a voidbase job per message | `void/queues` and `c.env.QUEUE_<NAME>` produce; the consumer runs on the jobs queue, or inline where there is none |
+| `db/schema.ts` + `void/db` | Drizzle over voidbase's D1 | the same database PocketBase's collections live in |
+| `db/migrations/*.sql` | `.voidbase/pb_migrations/<name>.void.js` | applied and recorded like any other migration, on both runtimes |
+
+Point the project's `tsconfig.json` at the adapter's fragment so the editor and Bun agree:
+
+```jsonc
+{ "extends": "./.voidbase/tsconfig.json" }   // instead of "./.void/tsconfig.json"
+```
+
+Void's own fragment maps `void/db` and `void/queues` to declaration files. That is right for `tsc` and wrong for
+Bun, which honours `paths` at runtime and would resolve those imports to a `.d.ts` that exports nothing. The
+adapter's fragment repoints those two at shims that take the values from Void's published runtime and the types
+from Void's declarations, and passes every other mapping (`@schema`, `void/routes`) through unchanged.
+
+## Two shapes of app
+
+The adapter looks at what the project actually has:
+
+- **Static.** No `routes/`, `middleware/`, `vb_hooks/`, `crons/` or `queues/` (`vb_secrets/` alone changes nothing). The generated app is `main.ts`
+  plus `pb_public`.
+- **Server.** Anything else. The bundle and its hook go into `pb_hooks/`. `voidbase deploy`, run from `.voidbase/`,
+  ships that directory whole, so the same code serves on Cloudflare.
+
+Pages are prerendered when `void.json` sets `"output": "static"`; they land in `pb_public` as plain HTML and need no
+runtime. Pages that still render per request have nowhere to run here, and the build says so.
+
+## How the server code runs
+
+Void's `defineHandler` returns a plain Hono handler, and voidbase's app is Hono, so handlers run unchanged. Two
+details make that true rather than nearly true:
+
+- Routes register through `routerAdd`, the registry every pb_hooks route uses. The RequestEvent it hands the
+  handler carries `.c`, the real Hono context, and the adapter overlays the route's own parameters on
+  `c.req.param()`, since the hook router matched a pattern rather than Hono's own.
+- Every handler, cron and queue consumer runs inside `withRuntimeEnv`, Void's binding context. That is why
+  `void/db`, `void/storage`, `void/env` and `void/queues` resolve against voidbase's D1 and R2 with no shim of
+  their own, and why `c.env` carries the app's queue producers.
+
+Return values convert exactly as Void converts them (object → JSON, string → HTML, `null` → 204, `Response` as-is),
+because the adapter calls Void's own `convertReturnValue`.
+
+## Things to know
+
+**voidbase's API wins.** `/api/collections`, `/api/files`, `/api/realtime`, `/api/settings`, `/api/logs`,
+`/api/backups`, `/api/crons`, `/api/batch`, `/api/health`, `/api/webauthn` (voidbase's passkey endpoints) and `/_/`
+are voidbase's own. An app route on one of those paths never runs; the build warns and names it. Everything else
+under `/api` is yours.
+
+**Middleware runs on every request.** `middleware/` registers through `routerUse`, PocketBase's own global
+middleware, so it means what Void means by it: every request, in file order, before whatever answers. That includes
+PocketBase's endpoints and the admin panel, so a middleware that throws takes the whole backend with it. Guard on
+the path when a middleware is only meant for the app's own routes.
+
+**Queues are one queue.** Cloudflare Queues are provisioned per instance, so every app queue rides voidbase's own
+jobs queue as a `{ type: "queue", queue, body }` message and is fanned back out to the right consumer. Without a
+queue binding (the Bun runtime, or a deploy whose token could not create one) `send` runs the consumer inline. A
+consumer that throws, or calls `retry()`, is retried by voidbase's job runner.
+
+**Not carried over.** The build warns and keeps going:
+
+| what | why |
+| --- | --- |
+| `pages/` that render per request | prerender them with `"output": "static"` and they land in `pb_public`; there is no page renderer at runtime |
+| `routes/**/*.ws.ts` | document WebSockets are Durable Objects, and voidbase's realtime hub owns that binding |
+| `void/kv` | voidbase binds D1 and R2 only; a collection is the place for that data |
+| `void/isr` | ISR runs in the Void platform's dispatch worker, which a self-hosted app does not have |
+
+**Build with Bun.** voidbase ships TypeScript sources, and Vite loads its config through the runtime, so use
+`bunx --bun vite build` (or `bun run build` with Bun as the package manager). `voidbase adapt` has no such
+constraint.
+
+**Nothing is written outside `.voidbase/`.** Delete the directory and the next build makes it again, so it belongs
+in `.gitignore` and never in review.
+
+## Testing it
+
+`test/adapter.ts` converts `test/fixtures/void-app`, boots it with the generated `main.ts` and exercises the whole
+surface: the generated layout, route paths and parameters, literal-beats-parameter ordering, middleware order and
+its reach over PocketBase's own endpoints, `void/db` through the shim, `void/storage`, a queue round trip, a cron
+run, both kinds of migration, an `onBootstrap` hook running exactly once, a tagged event hook, a tsconfig alias
+resolving to a directory's index file, the four build errors (a hook attached to nothing, a misspelt hook name, a
+hook left in `middleware/`, a secret value nothing declares), `vb_secrets/` reaching the app through `$os.getenv`,
+and that nothing is written outside `.voidbase/`. Run it with
+`bun test/adapter.ts`, or as part of `bash scripts/ci.sh` (step `adapter`).