@voidbase-cloud/voidbase 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,8 +1,21 @@
 # Changelog
 
-Releases are tagged `vX.Y.Z`; the section for the tagged version becomes the GitHub release notes.
+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.
 
-## Unreleased
+## [0.2.1](https://github.com/voidbase-cloud/voidbase/compare/v0.2.0...v0.2.1) (2026-09-06)
+
+
+### Bug Fixes
+
+* **oauth2:** Cloudflare sign-in without the openid scope ([16d660d](https://github.com/voidbase-cloud/voidbase/commit/16d660de61728b705e1aa385b71b2fdf9397a216))
+
+## [0.2.0](https://github.com/voidbase-cloud/voidbase/compare/v0.1.0...v0.2.0) (2026-09-06)
+
+
+### Features
+
+* **cli:** prebuilt executables with voidbase update, PocketBase-style release archives ([48eef41](https://github.com/voidbase-cloud/voidbase/commit/48eef41f080092cd4c3bdb533e58fa83bfec1026))
 
 ## 0.1.0
 

package/README.md

@@ -28,8 +28,16 @@ bun add @voidbase-cloud/voidbase        # the package: library, CLI (`voidbase`)
 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).
+Or, like PocketBase, a single prebuilt executable from the
+[releases](https://github.com/voidbase-cloud/voidbase/releases): `voidbase_<version>_<os>_<arch>.zip` for Linux,
+macOS and Windows (amd64 and arm64; musl builds for Alpine), with the admin panel, the system migrations and the hooks
+typings inside, so `./voidbase serve` needs nothing else. `./voidbase update` fetches the latest release for the
+platform, verifies its checksum and replaces the executable (`--backup` zips `pb_data` first). The Cloudflare
+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).
 
 ## Run it like PocketBase
 

package/bin/voidbase.ts

@@ -5,6 +5,12 @@
 import { existsSync, mkdirSync, writeFileSync, cpSync } from "node:fs";
 import { resolve } from "node:path";
 import { exportAll } from "../scripts/export";
+import { embedded, isExecutable } from "../src/node/embedded";
+
+// the version: the executable carries it, a checkout reads package.json
+async function currentVersion(): Promise<string> { return (await embedded())?.version ?? (JSON.parse(await Bun.file(resolve(import.meta.dir, "../package.json")).text()) as { version: string }).version; }
+// the prebuilt executable serves; the Cloudflare toolchain (Void, Vite, wrangler) comes with the npm package
+const TOOLCHAIN = new Set(["dev", "build", "preview", "deploy", "bundle", "release", "cloud", "panel", "app", "init", "seed-user"]);
 
 const ROOT = resolve(`${import.meta.dir}/..`);
 const argv = process.argv.slice(2);
@@ -32,6 +38,9 @@ const HELP = `voidbase - PocketBase-compatible backend: a single Bun process loc
                                      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
+  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
   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)
@@ -59,8 +68,16 @@ async function login(): Promise<string> {
   return String(r.json.token);
 }
 
+if (cmd && TOOLCHAIN.has(cmd) && isExecutable()) { console.error(`"${cmd}" needs the Cloudflare toolchain, which comes with the npm package, not the prebuilt executable:\n  bunx @voidbase-cloud/voidbase ${argv.join(" ")}`); process.exit(1); }
 switch (cmd) {
   case undefined: case "help": case "--help": console.log(HELP); break;
+  case "version": case "--version": console.log(await currentVersion()); break;
+  case "update": {
+    if (!isExecutable()) { console.error("voidbase update replaces the prebuilt executable; this is a checkout or an npm install: update the package instead (bun update @voidbase-cloud/voidbase)."); process.exit(1); }
+    const { update } = await import("../src/node/update");
+    await update({ currentVersion: await currentVersion(), dataDir: resolve(flags.dir ?? "pb_data"), backup: !!flags.backup });
+    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");

package/docs/releasing.md

@@ -1,38 +1,87 @@
 # Releasing
 
-The package is `@voidbase-cloud/voidbase`. A release is a git tag `vX.Y.Z` that matches `package.json`; pushing
-the tag runs `.github/workflows/release.yml`, which checks, packs, smoke-installs and publishes.
+Every release has release notes because every commit message is a release note in waiting: commits follow
+[Conventional Commits](https://www.conventionalcommits.org), husky and CI enforce it, and
+[release-please](https://github.com/googleapis/release-please) compiles the commits merged since the previous
+release into `CHANGELOG.md`, the version bump and the GitHub release notes.
 
-```bash
-# on master, tree clean, CHANGELOG.md has a "## X.Y.Z" section
-npm version minor            # or patch / major / 0.2.0: bumps package.json, commits "vX.Y.Z", tags it
-git push --follow-tags       # the tag triggers the release workflow
-```
+## Commit messages
 
-What the workflow does, in order:
+```
+type(scope): subject            # scope optional; subject in the imperative, no trailing period, header <= 100 chars
 
-1. `bun install --frozen-lockfile`, the two typechecks, `bun test`, `test/cloud-rest.ts` (self-contained mocks).
-2. Refuses to continue if the tag and `package.json` disagree, or if that version is already on npm.
-3. `npm pack`, then installs the tarball into a temporary project and runs the CLI from it.
-4. `npm publish` to npm with `--access public`, and with `--provenance` when the repository is public (npm's
-   provenance needs a public repository; the workflow turns it off while the repository is private).
-5. The same tarball to GitHub Packages (`npm.pkg.github.com`, the `@voidbase-cloud` scope matches the organization).
-6. A GitHub release for the tag with the `CHANGELOG.md` section for that version as notes and the tarball attached.
+body (optional): what and why, wrapped at 120
 
-Secrets and permissions: `NPM_TOKEN` (repository secret: an npm granular token with publish rights on the
-`@voidbase-cloud` scope, created at npmjs.com > Access Tokens); GitHub Packages and the release use the
-workflow's own `GITHUB_TOKEN` (`packages: write`, `contents: write`, `id-token: write` for provenance).
+BREAKING CHANGE: description    # footer; or `feat(scope)!: subject`
+```
 
-Try the pipeline without publishing: Actions > release > Run workflow with `dry_run` on (or
-`gh workflow run release.yml -f dry_run=true`). It runs every step with `npm publish --dry-run` and creates no
-release.
+| type | in the release notes as | bumps |
+| --- | --- | --- |
+| `feat` | Features | minor (0.x: minor) |
+| `fix` | Bug Fixes | patch |
+| `perf` | Performance | patch |
+| `revert` | Reverts | patch |
+| `docs`, `refactor` | Documentation, Refactoring | nothing on their own |
+| `build`, `ci`, `chore`, `test`, `style` | hidden | nothing |
 
-Publishing by hand, when Actions is not an option:
+A breaking change (`!` or the footer) bumps the minor while the version is below 1.0, the major after.
+Scopes are the areas of the code base (`commitlint.config.js` lists them; an unknown scope is a warning, a
+wrong type or a long header is an error). Examples:
 
-```bash
-bun run check && bun test
-NPM_CONFIG_//registry.npmjs.org/:_authToken=$VOIDBASE_NPM_TOKEN npm publish --access public
 ```
+feat(realtime): push changes through the hub Durable Object
+fix(mail): keep stored SMTP passwords when the settings PATCH sends a blank
+docs(deploy): custom domains through the Workers API
+ci(release): compile release notes with release-please
+```
+
+`.husky/commit-msg` runs commitlint on every commit; `.husky/pre-commit` runs `bun run check` and `bun test`.
+`bun install` installs the hooks (`prepare`); `git commit --no-verify` skips them, and CI (`ci.yml`, job
+`commitlint`) checks the pushed or proposed commits regardless.
+
+## The release
+
+1. Push or merge conventional commits to `master`. `release.yml` runs release-please, which opens or updates the
+   pull request "chore(master): release X.Y.Z": the next version from the commit types, the `CHANGELOG.md`
+   section compiled from the commits, the `package.json` bump. Keep merging work; the PR follows.
+2. Merge the PR. release-please tags `vX.Y.Z` and creates the GitHub release with that section as notes.
+3. The `publish` job of the same run then installs, typechecks, runs the unit and cloud-rest tests, packs, smoke-
+   installs the tarball and runs the CLI from it, publishes to npm (`--provenance` when the repository is public)
+   and to GitHub Packages, and attaches the tarball to the release.
+4. The `executables` job builds the prebuilt executables for every platform (`scripts/build-exe.ts`: Bun
+   cross-compiles from one runner; the panel, the system migrations and the hooks typings are embedded), smokes the
+   runner's own build (`test/exe-smoke.ts`: serve with pb_hooks, the panel from the embedded zip, a thumbnail through
+   the wasm, then `voidbase update` against a mock GitHub API), attaches `voidbase_<version>_<os>_<arch>.zip` for
+   linux/darwin/windows × amd64/arm64 (plus musl builds) and `checksums.txt` to the release, attests each archive
+   with `actions/attest-build-provenance`, and puts the release notes in PocketBase's shape: the
+   `./voidbase update` hint first, then the compiled notes.
+
+The layout mirrors PocketBase's releases: the zip holds the executable, `CHANGELOG.md` and `LICENSE`;
+`checksums.txt` is goreleaser's format (`<sha256>  <file>`), which `voidbase update` checks before replacing the
+executable. Verify an archive's provenance with `gh attestation verify voidbase_X.Y.Z_linux_amd64.zip --owner
+voidbase-cloud`. For the "Immutable" badge and the release attestation GitHub adds itself, enable immutable releases
+once in the repository settings (Settings > General > Releases); it is a setting, not something the workflow can
+turn on.
+
+`.release-please-manifest.json` holds the released version (0.1.0 was cut by hand and its notes written by hand;
+everything after it is compiled). `release-please-config.json` maps commit types to changelog sections.
+
+## Rehearsals and manual paths
+
+- Actions > release > Run workflow with `dry_run` on (or `gh workflow run release.yml -f dry_run=true`): the
+  publish job with `npm publish --dry-run`, nothing published, no release touched.
+- A release cut by hand also publishes: `gh release create vX.Y.Z --notes-file notes.md` after bumping
+  `package.json` to X.Y.Z on `master`; the `release: published` event runs the publish job against that tag.
+- Publishing from a machine: `bun run check && bun test`, then
+  `NPM_CONFIG_//registry.npmjs.org/:_authToken=$VOIDBASE_NPM_TOKEN npm publish --access public`.
+
+Secrets and permissions: `NPM_TOKEN` (repository secret, an npm granular token with publish rights on the
+`@voidbase-cloud` scope). release-please opens the release PR with the workflow's own token only if the
+organization allows it (voidbase-cloud > Settings > Actions > General > "Allow GitHub Actions to create and
+approve pull requests", then the same switch on the repository); otherwise add `RELEASE_PLEASE_TOKEN`, a
+fine-grained PAT with contents and pull requests write on this repository, which the workflow prefers when
+present and which also makes CI run on the release PR (the workflow's own token cannot trigger other workflows).
+GitHub Packages and the release assets use the workflow's `GITHUB_TOKEN`.
 
-Consumers install with `bun add @voidbase-cloud/voidbase`. From GitHub Packages instead, add to `.npmrc`:
-`@voidbase-cloud:registry=https://npm.pkg.github.com` plus a token with `read:packages`.
+Consumers: `bun add @voidbase-cloud/voidbase`; from GitHub Packages instead, `.npmrc` with
+`@voidbase-cloud:registry=https://npm.pkg.github.com` and a token with `read:packages`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidbase-cloud/voidbase",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "PocketBase-compatible backend on Cloudflare Workers (D1, R2, Queues, Durable Objects) via Void, or a single Bun process",
   "license": "MIT",
   "repository": {
@@ -112,7 +112,9 @@
     "app:sync": "bun scripts/sync-app.ts",
     "check": "void prepare && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.node.json --noEmit",
     "pack:check": "npm pack --dry-run",
-    "prepublishOnly": "bun run check && bun test"
+    "prepublishOnly": "bun run check && bun test",
+    "prepare": "husky || true",
+    "build:exe": "bun scripts/build-exe.ts"
   },
   "dependencies": {
     "@cf-wasm/photon": "^0.4.0",
@@ -127,7 +129,10 @@
     "@cloudflare/workers-types": "^4.20250903.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@types/bun": "^1.4.1",
+    "husky": "^9.1.7",
     "playwright": "^1.63.0",
     "pocketbase": "0.28.0"
   }

package/scripts/build-exe.ts

@@ -0,0 +1,72 @@
+// Prebuilt executables laid out like PocketBase's release assets: voidbase_<version>_<os>_<arch>.zip holding the
+// executable, CHANGELOG.md and LICENSE, plus checksums.txt (sha256, goreleaser's format). Bun cross-compiles every
+// target from one machine; the admin panel, the system migrations and the hooks typings are embedded
+// (src/node/embedded.ts), so `voidbase serve` works offline from the single file.
+//   bun scripts/build-exe.ts [--targets host|all|linux-x64,darwin-arm64,...] [--out dist/release] [--version X.Y.Z] [--keep-embedded]
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { zipSync, type Zippable } from "fflate";
+
+const PKG = resolve(import.meta.dir, "..");
+export const TARGETS: Record<string, { bun: string; os: string; arch: string; exe: string }> = {
+  "linux-x64": { bun: "bun-linux-x64", os: "linux", arch: "amd64", exe: "voidbase" },
+  "linux-arm64": { bun: "bun-linux-arm64", os: "linux", arch: "arm64", exe: "voidbase" },
+  "linux-x64-musl": { bun: "bun-linux-x64-musl", os: "linux", arch: "amd64_musl", exe: "voidbase" },
+  "linux-arm64-musl": { bun: "bun-linux-arm64-musl", os: "linux", arch: "arm64_musl", exe: "voidbase" },
+  "darwin-x64": { bun: "bun-darwin-x64", os: "darwin", arch: "amd64", exe: "voidbase" },
+  "darwin-arm64": { bun: "bun-darwin-arm64", os: "darwin", arch: "arm64", exe: "voidbase" },
+  "windows-x64": { bun: "bun-windows-x64", os: "windows", arch: "amd64", exe: "voidbase.exe" },
+};
+export const hostTarget = () => `${process.platform === "win32" ? "windows" : process.platform}-${process.arch}`;
+
+const walk = (dir: string, base = dir): string[] => readdirSync(dir).flatMap((n) => { const f = join(dir, n); return statSync(f).isDirectory() ? walk(f, base) : [relative(base, f).replace(/\\/g, "/")]; });
+const b64 = (bytes: Uint8Array) => { let s = ""; for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000)); return btoa(s); };
+const sha256 = async (bytes: Uint8Array) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes as BufferSource))].map((b) => b.toString(16).padStart(2, "0")).join("");
+const UNIX_EXEC = { os: 3, attrs: 0o100755 << 16 }; // zip external attributes: a regular file, mode 0755
+
+export interface BuildOptions { targets?: string[]; out?: string; version?: string; keepEmbedded?: boolean; log?: (line: string) => void }
+export async function buildExecutables(o: BuildOptions = {}): Promise<{ version: string; out: string; archives: { target: string; file: string; bytes: number; sha256: string }[] }> {
+  const log = o.log ?? ((l: string) => console.log(l));
+  const version = o.version ?? (JSON.parse(readFileSync(`${PKG}/package.json`, "utf8")) as { version: string }).version;
+  const targets = (o.targets ?? ["host"]).flatMap((t) => (t === "all" ? Object.keys(TARGETS) : t === "host" ? [hostTarget()] : [t]));
+  for (const t of targets) if (!TARGETS[t]) throw new Error(`unknown target ${t} (known: ${Object.keys(TARGETS).join(", ")})`);
+  const out = resolve(o.out ?? `${PKG}/dist/release`); mkdirSync(out, { recursive: true });
+
+  // what the executable must carry: the panel (zipped), the system migrations, the typings, the version
+  const panelDir = `${PKG}/public/_`;
+  if (!existsSync(`${panelDir}/index.html`)) { log("syncing the admin panel into public/_"); const r = Bun.spawnSync(["bun", `${PKG}/scripts/sync-panel.ts`], { cwd: PKG, stdout: "inherit", stderr: "inherit" }); if (r.exitCode !== 0) throw new Error("panel sync failed"); }
+  const panelFiles: Zippable = {}; for (const f of walk(panelDir)) panelFiles[f] = [new Uint8Array(readFileSync(join(panelDir, f))), { level: 6 }];
+  const panelVersion = (() => { try { return (JSON.parse(readFileSync(`${panelDir}/../../pocketbase-panel.json`, "utf8")) as { version: string }).version; } catch { return process.env.POCKETBASE_PANEL_VERSION ?? "0.40.2"; } })();
+  const migrations: Record<string, string> = {}; for (const f of readdirSync(`${PKG}/db/migrations`).filter((f) => f.endsWith(".sql")).sort()) migrations[f] = readFileSync(`${PKG}/db/migrations/${f}`, "utf8");
+  const embeddedPath = `${PKG}/src/node/embedded.generated.json`;
+  writeFileSync(embeddedPath, JSON.stringify({ version, migrations, typesDts: readFileSync(`${PKG}/types/pb_data.d.ts`, "utf8"), panel: { version: panelVersion, zipBase64: b64(zipSync(panelFiles)) } }));
+  log(`embedded: ${Object.keys(migrations).length} migrations, the typings, the ${panelVersion} panel (${Object.keys(panelFiles).length} files)`);
+
+  const archives: { target: string; file: string; bytes: number; sha256: string }[] = [];
+  const changelog = new Uint8Array(readFileSync(`${PKG}/CHANGELOG.md`)), license = new Uint8Array(readFileSync(`${PKG}/LICENSE`));
+  try {
+    for (const t of targets) {
+      const T = TARGETS[t]!; const exeDir = `${PKG}/dist/exe/${t}`; mkdirSync(exeDir, { recursive: true });
+      const exe = `${exeDir}/${T.exe}`;
+      log(`compiling ${t} (${T.bun})`);
+      const r = Bun.spawnSync(["bun", "build", "--compile", `--target=${T.bun}`, `${PKG}/bin/voidbase.ts`, "--outfile", exe], { cwd: PKG, stdout: "pipe", stderr: "pipe" });
+      if (r.exitCode !== 0) throw new Error(`bun build --compile failed for ${t}:\n${new TextDecoder().decode(r.stderr)}`);
+      const name = `voidbase_${version}_${T.os}_${T.arch}.zip`;
+      const entries: Zippable = { [T.exe]: [new Uint8Array(readFileSync(exe)), { level: 6, ...(T.os === "windows" ? {} : UNIX_EXEC) }], "CHANGELOG.md": [changelog, { level: 6 }], LICENSE: [license, { level: 6 }] };
+      const zip = zipSync(entries);
+      writeFileSync(`${out}/${name}`, zip);
+      archives.push({ target: t, file: name, bytes: zip.length, sha256: await sha256(zip) });
+      log(`  ${name}: ${(zip.length / 1024 / 1024).toFixed(1)} MB`);
+    }
+    writeFileSync(`${out}/checksums.txt`, archives.map((a) => `${a.sha256}  ${a.file}`).join("\n") + "\n");
+    log(`checksums.txt: ${archives.length} archives in ${out}`);
+  } finally { if (!o.keepEmbedded) rmSync(embeddedPath, { force: true }); }
+  return { version, out, archives };
+}
+
+if (import.meta.main) {
+  const flags: Record<string, string> = {};
+  const argv = process.argv.slice(2);
+  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"); } }
+  await buildExecutables({ targets: (flags.targets ?? "host").split(","), out: flags.out, version: flags.version, keepEmbedded: !!flags["keep-embedded"] });
+}

package/src/node/embedded.ts

@@ -0,0 +1,16 @@
+// What a standalone executable carries that a checkout reads from disk: the version, the system migrations, the
+// hooks typings and the admin panel (zipped). scripts/build-exe.ts writes src/node/embedded.generated.json right
+// before compiling; in a checkout the file does not exist and every reader falls back to the package directory.
+export interface Embedded { version: string; migrations: Record<string, string>; typesDts: string; panel: { version: string; zipBase64: string } | null }
+
+let cached: Embedded | null | undefined;
+export async function embedded(): Promise<Embedded | null> {
+  if (cached !== undefined) return cached;
+  // the file exists only while scripts/build-exe.ts compiles; consumers typecheck this module without it
+  // @ts-ignore
+  try { cached = ((await import("./embedded.generated.json", { with: { type: "json" } })) as { default: Embedded }).default; } catch { cached = null; }
+  return cached;
+}
+
+// Bun mounts a compiled executable's modules under a virtual root ("/$bunfs/root", "B:\~BUN\root" on Windows)
+export const isExecutable = (): boolean => /\$bunfs|~BUN/.test(import.meta.dir);

package/src/node/panel.ts

@@ -1,12 +1,26 @@
 // 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";
+import { dirname, resolve } from "node:path";
+import { unzipSync } from "fflate";
+import { embedded } from "./embedded";
 export const PANEL_VERSION = process.env.POCKETBASE_PANEL_VERSION ?? "0.40.2";
+const cacheDir = (version: string) => resolve(`${process.env.XDG_CACHE_HOME ?? `${process.env.HOME ?? process.env.USERPROFILE ?? "."}/.cache`}/voidbase/panel-${version}`);
 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}`);
+  // a standalone executable carries the panel: unpacked once into the cache
+  const emb = await embedded();
+  if (emb?.panel) {
+    const dir = cacheDir(emb.panel.version);
+    if (!existsSync(`${dir}/index.html`)) {
+      const files = unzipSync(Uint8Array.from(atob(emb.panel.zipBase64), (c) => c.charCodeAt(0)));
+      for (const [name, bytes] of Object.entries(files)) { if (name.endsWith("/")) continue; mkdirSync(dirname(`${dir}/${name}`), { recursive: true }); writeFileSync(`${dir}/${name}`, bytes); }
+      if (!existsSync(`${dir}/extensions.js`)) writeFileSync(`${dir}/extensions.js`, "// voidbase: no UI extensions configured\n");
+    }
+    return dir;
+  }
+  const cache = cacheDir(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}`);

package/src/node/serve.ts

@@ -1,25 +1,31 @@
 // `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 { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } 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";
+import { embedded } from "./embedded";
 
 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 {
+export function readSystemMigrations(): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const f of readdirSync(`${PKG}/db/migrations`).filter((f) => f.endsWith(".sql")).sort()) out[f] = readFileSync(`${PKG}/db/migrations/${f}`, "utf8");
+  return out;
+}
+export function applySystemMigrations(db: ReturnType<typeof openDatabase>, migrations: Record<string, string> = readSystemMigrations()): 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()) {
+  for (const f of Object.keys(migrations).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);
+      for (const statement of migrations[f]!.split("--> statement-breakpoint")) if (statement.trim()) db.exec(statement);
       db.query("INSERT INTO `_vb_migrations` (name, applied) VALUES (?, ?)").run(f, new Date().toISOString());
     })();
     applied++;
@@ -49,10 +55,12 @@ export async function openLocal(opts: ServeOptions) {
   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 */ }
+  // pb_data/types.d.ts for editor support in pb_hooks (PocketBase's JSVM typings); a standalone executable carries
+  // the typings and the system migrations itself (src/node/embedded.ts)
+  const emb = await embedded();
+  try { if (!existsSync(`${dir}/types.d.ts`)) writeFileSync(`${dir}/types.d.ts`, emb?.typesDts ?? readFileSync(`${PKG}/types/pb_data.d.ts`, "utf8")); } catch { /* optional */ }
   const sqlite = openDatabase(`${dir}/data.db`);
-  applySystemMigrations(sqlite);
+  applySystemMigrations(sqlite, emb?.migrations ?? readSystemMigrations());
   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 };
 }

package/src/node/update.ts

@@ -0,0 +1,91 @@
+// `voidbase update`: PocketBase's `pocketbase update` for the prebuilt executable. The latest GitHub release, the
+// asset for this platform (voidbase_<version>_<os>_<arch>.zip), its sha256 against checksums.txt, then the running
+// executable replaced in place (the old one kept as `.old` until the end), optionally a pb_data backup first.
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { unzipSync } from "fflate";
+
+export const REPO = "voidbase-cloud/voidbase";
+export const EXECUTABLE = "voidbase";
+
+// the archive name PocketBase uses, per Go's GOOS/GOARCH names, for the platforms Bun can build for
+export function archiveSuffix(platform: string = process.platform, arch: string = process.arch): string | null {
+  const os = platform === "win32" ? "windows" : platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : null;
+  const cpu = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : null;
+  return os && cpu ? `_${os}_${cpu}.zip` : null;
+}
+// "0.1.0" vs "0.2.0-rc.1": numeric parts first, a pre-release tag sorts before the plain version
+export function compareVersions(a: string, b: string): number {
+  const split = (v: string) => { const [core, pre] = v.replace(/^v/, "").split("-", 2); return { nums: core!.split(".").map((n) => Number(n) || 0), pre: pre ?? "" }; };
+  const x = split(a), y = split(b);
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) { const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0); if (d) return d < 0 ? -1 : 1; }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1; if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+// goreleaser's checksums.txt: "<sha256>  <file>" per line
+export function parseChecksums(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const line of text.split("\n")) { const m = /^([0-9a-f]{64})\s+\*?(.+)$/.exec(line.trim()); if (m) out.set(m[2]!.trim(), m[1]!); }
+  return out;
+}
+export async function sha256(bytes: Uint8Array): Promise<string> { return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes as BufferSource))].map((b) => b.toString(16).padStart(2, "0")).join(""); }
+
+export interface Release { tag: string; body: string; assets: { name: string; url: string }[] }
+export async function fetchLatestRelease(api = process.env.VOIDBASE_UPDATE_API || "https://api.github.com"): Promise<Release> {
+  const res = await fetch(`${api.replace(/\/$/, "")}/repos/${REPO}/releases/latest`, { headers: { accept: "application/vnd.github+json", "user-agent": "voidbase-update" } });
+  if (!res.ok) throw new Error(`fetching the latest release: HTTP ${res.status}`);
+  const r = (await res.json()) as { tag_name: string; body?: string; assets?: { name: string; browser_download_url: string }[] };
+  return { tag: r.tag_name, body: r.body ?? "", assets: (r.assets ?? []).map((a) => ({ name: a.name, url: a.browser_download_url })) };
+}
+
+export interface UpdateOptions { currentVersion: string; dataDir: string; backup?: boolean; api?: string; execPath?: string; log?: (line: string) => void }
+export async function update(o: UpdateOptions): Promise<{ updated: boolean; version: string }> {
+  const log = o.log ?? ((l: string) => console.log(l));
+  log("Fetching release information...");
+  const latest = await fetchLatestRelease(o.api);
+  if (compareVersions(o.currentVersion, latest.tag) >= 0) { log(`You already have the latest version ${o.currentVersion}.`); return { updated: false, version: o.currentVersion }; }
+  const suffix = archiveSuffix();
+  if (!suffix) throw new Error(`unsupported platform ${process.platform}/${process.arch}`);
+  const asset = latest.assets.find((a) => a.name.startsWith(`${EXECUTABLE}_`) && a.name.endsWith(suffix));
+  if (!asset) throw new Error(`release ${latest.tag} has no asset for this platform (${EXECUTABLE}_*${suffix})`);
+  const tmp = resolve(o.dataDir, ".tmp", `update-${latest.tag}`); rmSync(tmp, { recursive: true, force: true }); mkdirSync(tmp, { recursive: true });
+  try {
+    log(`Downloading ${asset.name}...`);
+    const zip = new Uint8Array(await (await fetchOk(asset.url)).arrayBuffer());
+    const sums = latest.assets.find((a) => a.name === "checksums.txt");
+    if (sums) {
+      const expected = parseChecksums(await (await fetchOk(sums.url)).text()).get(asset.name);
+      if (!expected) throw new Error(`checksums.txt has no entry for ${asset.name}`);
+      const actual = await sha256(zip);
+      if (actual !== expected) throw new Error(`checksum mismatch for ${asset.name}: expected ${expected}, got ${actual}`);
+      log("Checksum verified.");
+    } else log("No checksums.txt in the release; skipping the checksum check.");
+    log(`Extracting ${asset.name}...`);
+    const files = unzipSync(zip);
+    const name = [EXECUTABLE, `${EXECUTABLE}.exe`].find((n) => files[n]);
+    if (!name) throw new Error("the archive has no executable in it");
+    const extracted = join(tmp, name); writeFileSync(extracted, files[name]!); if (process.platform !== "win32") chmodSync(extracted, 0o755);
+    if (o.backup) {
+      log("Creating pb_data backup...");
+      const { openLocal } = await import("./serve"); const { createBackup } = await import("../server/backups");
+      const { env } = await openLocal({ dir: o.dataDir });
+      await createBackup(env as never, `@update_${latest.tag}.zip`);
+    }
+    log("Replacing the executable...");
+    const oldExec = o.execPath ?? process.execPath;
+    const renamedOld = `${oldExec}.old`;
+    renameSync(oldExec, renamedOld);
+    try { renameSync(extracted, oldExec); } catch (err) { renameSync(renamedOld, oldExec); throw new Error(`failed replacing the executable: ${err instanceof Error ? err.message : err}`); }
+    try { rmSync(renamedOld, { force: true }); } catch { /* Windows keeps a running executable's file; it goes on the next update */ }
+    log("---\nUpdate completed successfully! You can start the executable as usual.");
+    const notes = latest.body.replace(/^> _To update the prebuilt executable you can run `\.\/voidbase update`\._\s*/m, "").trim();
+    if (notes) log(`\nHere is a list with some of the ${latest.tag} changes:\n${notes}`);
+    return { updated: true, version: latest.tag.replace(/^v/, "") };
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+async function fetchOk(url: string): Promise<Response> {
+  const res = await fetch(url, { headers: { "user-agent": "voidbase-update" }, redirect: "follow" });
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+  return res;
+}

package/src/server/oauth2/providers.ts

@@ -7,11 +7,14 @@ export interface ProviderContext { name: string; clientId: string; clientSecret:
 type Raw = Record<string, unknown>;
 
 const oidc: ProviderDefaults = { displayName: "OIDC", pkce: true, scopes: ["openid", "email", "profile"] };
-// Cloudflare OAuth (developers.cloudflare.com/fundamentals/oauth): plain OIDC on dash.cloudflare.com whose userinfo
-// carries only `sub`, so identity comes from the API's GET /user. Resource scopes (API token permission names such
-// as workers-platform.write) are added per provider with extra.scopes; extra.apiBase overrides the API for tests.
+// Cloudflare OAuth (developers.cloudflare.com/fundamentals/oauth): OAuth 2.0 on dash.cloudflare.com, not OIDC: `openid`
+// is not a Cloudflare scope and a request carrying it is refused (invalid_scope). Identity comes from the API's GET
+// /user (scope user-details.read); the userinfo endpoint, when it answers, only adds `sub`. Resource scopes (API token
+// permission ids such as workers-scripts.write, plus offline_access for a refresh token) must be registered on the
+// client and are added per provider with extra.scopes; extra.apiBase overrides the API for tests. The client
+// authenticates with HTTP Basic at the token endpoint (the token exchange tries that first).
 export const CF_API_BASE = "https://api.cloudflare.com/client/v4";
-const cloudflare: ProviderDefaults = { displayName: "Cloudflare", pkce: true, scopes: ["openid", "offline_access"], authURL: "https://dash.cloudflare.com/oauth2/auth", tokenURL: "https://dash.cloudflare.com/oauth2/token", userInfoURL: "https://dash.cloudflare.com/oauth2/userinfo" };
+const cloudflare: ProviderDefaults = { displayName: "Cloudflare", pkce: true, scopes: ["user-details.read"], authURL: "https://dash.cloudflare.com/oauth2/auth", tokenURL: "https://dash.cloudflare.com/oauth2/token", userInfoURL: "https://dash.cloudflare.com/oauth2/userinfo" };
 export const PROVIDER_DEFAULTS: Record<string, ProviderDefaults> = {
   oidc, oidc2: oidc, oidc3: oidc, cloudflare,
   apple: { displayName: "Apple", pkce: true, scopes: ["name", "email"], authURL: "https://appleid.apple.com/auth/authorize", tokenURL: "https://appleid.apple.com/auth/token" },
@@ -72,7 +75,9 @@ export async function fetchRawUser(p: ProviderContext, token: Token): Promise<Ra
       if (!token.id_token) throw new Error("empty id_token");
       return jwtClaims(String(token.id_token));
     case "cloudflare": {
-      const info = p.userInfoURL ? await getJSON(p.userInfoURL, token) : (token.id_token ? jwtClaims(String(token.id_token)) : {});
+      let info: Raw = {};
+      if (p.userInfoURL) { try { info = await getJSON(p.userInfoURL, token); } catch { /* no openid: identity comes from GET /user */ } }
+      else if (token.id_token) info = jwtClaims(String(token.id_token));
       const base = String(p.extra.apiBase || CF_API_BASE).replace(/\/$/, "");
       const me = await getJSON(`${base}/user`, token);
       return { ...info, cf_user: (me.result ?? me) as Raw };