@voidbase-cloud/voidbase 0.2.2 → 0.4.0

package/scripts/ci.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# The whole CI flow in one script (docs/ci.md), the same on a dev machine and on Cloudflare Workers Builds (GitHub
+# Actions only starts the builds): commit messages, typecheck and unit tests, the differential and panel suites against a reference
+# PocketBase, the same suites on the Bun runtime, the deploy dry run, the production-build boots, the prebuilt
+# executable and the unmodified starter. Every step is recorded for the status page (ci/public, scripts/ci-status.ts);
+# the script stops at the first failed step and exits non-zero. It stops the servers it started when it ends.
+#   scripts/ci.sh
+# Environment: STARTER_DIR (scripts/ci-oracles.sh resolves it), CHROME_PATH (scripts/ci-browser.sh finds or provisions
+# a Chrome), CI_BROWSER=0 skips the browser suites, CI_PORT (5180) and CI_PB_PORT (8090) for voidbase and the reference,
+# CI_CACHE_DIR for the downloads kept between runs, CI_STATUS_URL for the record of the last green run
+# (scripts/ci-plan.ts skips what that run already verified on the same inputs; CI_PLAN=full runs everything).
+set -uo pipefail
+cd "$(dirname "$0")/.."; ROOT="$PWD"
+. scripts/ci-lib.sh
+export VOIDBASE_SUPERUSER_EMAIL="${VOIDBASE_SUPERUSER_EMAIL:-admin@example.com}"
+export VOIDBASE_SUPERUSER_PASSWORD="${VOIDBASE_SUPERUSER_PASSWORD:-changeme123}"
+export AUDITLOG="${AUDITLOG:-posts,users}" VOIDBASE_LOG_MIN_LEVEL=0
+BACKEND=$(ci_backend); export CI_BACKEND_NAME="$BACKEND"
+PORT="${CI_PORT:-5180}"; PB_PORT="${CI_PB_PORT:-8090}"; VB="http://127.0.0.1:$PORT"; PB="http://127.0.0.1:$PB_PORT"
+LOGS="$ROOT/.void/ci-logs"; rm -rf "$LOGS" "$CI_STEPS_TSV" .void/ci-plan.txt .void/ci-plan.json; mkdir -p "$LOGS"
+CI_CACHE_DIR="$(ci_cache_dir)"; export CI_CACHE_DIR; mkdir -p "$CI_CACHE_DIR"
+started_pb=0; booted=0
+echo "voidbase ci on $BACKEND: $(git rev-parse --short HEAD 2>/dev/null || echo '?') $(git log -1 --format=%s 2>/dev/null | cut -c1-80), bun $(bun --version)"
+echo "cache: $CI_CACHE_DIR ($(du -sh "$CI_CACHE_DIR" 2>/dev/null | cut -f1 || echo empty))"
+
+cleanup() {
+  local rc=$?
+  ./scripts/starter.sh stop >/dev/null 2>&1 || true
+  ./scripts/dev.sh stop >/dev/null 2>&1 || true
+  for d in serve smtp-sink mock-oidc s3-mock cf-mock; do stop_daemon "$d"; done
+  stop_reference
+  if [ -f .void/ci-env.backup ]; then mv .void/ci-env.backup .env; fi
+  if [ "$rc" != 0 ]; then
+    echo; echo "--- dev.log"; tail -n 60 .void/dev.log 2>/dev/null; echo "--- reference"; tail -n 30 .void/reference/pb.log 2>/dev/null
+    for f in "$LOGS"/*.log "$LOGS"/bun/*.log; do [ -f "$f" ] && grep -qE "^FAIL" "$f" 2>/dev/null && { echo "--- $f"; grep -E "^FAIL|Error|error:" "$f" | head -8; }; done
+  fi
+  render_status --kind ci || true
+  if [ "$rc" = 0 ]; then echo "CI PASSED"; else echo "CI FAILED (exit $rc)"; fi
+}
+trap cleanup EXIT
+
+install() { bun install --frozen-lockfile; }
+commitlint_check() {  # the commits this run introduces; the last one when there is nothing to compare with
+  local from="" to="HEAD"
+  if [ "$BACKEND" = github ] && [ "${GITHUB_EVENT_NAME:-}" = pull_request ]; then
+    from=$(bun -e 'const e = await Bun.file(process.env.GITHUB_EVENT_PATH!).json(); console.log(e.pull_request.base.sha)'); to=$(bun -e 'const e = await Bun.file(process.env.GITHUB_EVENT_PATH!).json(); console.log(e.pull_request.head.sha)')
+  elif [ "$BACKEND" = github ]; then
+    from=$(bun -e 'const e = await Bun.file(process.env.GITHUB_EVENT_PATH!).json(); console.log(e.before ?? "")'); [ "$from" = "0000000000000000000000000000000000000000" ] && from=""
+  elif [ "$BACKEND" = cloudflare ] && [ "${WORKERS_CI_BRANCH:-master}" != master ]; then
+    git fetch --quiet --depth=200 origin master 2>/dev/null && from=$(git merge-base origin/master HEAD 2>/dev/null || true)
+  elif [ "$BACKEND" = local ]; then from=$(git merge-base origin/master HEAD 2>/dev/null || true); fi
+  if [ -n "$from" ] && [ "$from" != "$(git rev-parse "$to")" ] && git cat-file -e "$from" 2>/dev/null; then node_modules/.bin/commitlint --from "$from" --to "$to" --verbose; else node_modules/.bin/commitlint --last --verbose; fi
+}
+oracles() {  # the starter and the panel next to a production-shaped public/ (the SPA shell the boot test checks)
+  . scripts/ci-oracles.sh
+  XDG_CACHE_HOME="$CI_CACHE_DIR/xdg" bun run panel:sync   # scripts/sync-panel.ts keeps the panel tarball under it
+  # the starter's frontend build is kept with the clone and reused while the starter's commit is the same
+  local head stamp; head=$(git -C "$STARTER_DIR" rev-parse HEAD 2>/dev/null || echo none); stamp="$STARTER_DIR/sk/build/.voidbase-ci-stamp"
+  if [ -d "$STARTER_DIR/sk/build" ] && [ -f "$stamp" ] && [ "$(cat "$stamp")" = "$head" ]; then echo "starter frontend build reused ($head)"
+  else (cd "$STARTER_DIR/sk" && bun install --frozen-lockfile && bunx svelte-kit sync && bun run build) && echo "$head" > "$stamp"; fi
+  VOIDBASE_APP_DIR="$STARTER_DIR/sk/build" bun run app:sync
+  ./node_modules/.bin/void prepare
+}
+plan() { bun scripts/ci-plan.ts; }
+cache_restore() { ./scripts/ci-cache.sh restore; }
+cache_save() { ./scripts/ci-cache.sh save; }
+typecheck() { bunx tsc --noEmit -p tsconfig.json && bunx tsc --noEmit -p tsconfig.node.json && bunx tsc --noEmit -p tsconfig.scripts.json; }
+unit() { bun test; }
+browser() { local exports; exports=$(./scripts/ci-browser.sh) || return 1; eval "$exports"; echo "$exports"; }
+boot() {
+  # the Worker reads its vars from .env (Void bakes them), not from the shell: the run writes its own values so both
+  # sides serve the same starter; a dev machine's file is put back when the run ends (cleanup)
+  if [ -f .env ] && [ ! -f .void/ci-env.backup ]; then cp .env .void/ci-env.backup; fi
+  printf 'VOIDBASE_SUPERUSER_EMAIL=%s\nVOIDBASE_SUPERUSER_PASSWORD=%s\nVOIDBASE_HOOKS_DIR=%s\nVOIDBASE_MIGRATIONS_DIR=%s\nAUDITLOG=%s\nVOIDBASE_LOG_MIN_LEVEL=0\n' "$VOIDBASE_SUPERUSER_EMAIL" "$VOIDBASE_SUPERUSER_PASSWORD" "$STARTER_DIR/pb/pb_hooks" "$STARTER_DIR/pb/pb_migrations" "$AUDITLOG" > .env
+  ./node_modules/.bin/void db migrate
+  ./scripts/dev.sh start "$PORT" && booted=1
+  ./scripts/seed-app-user.sh "$VB"
+  warm_up
+}
+warm_up() {  # first requests to the paths whose dependencies Vite+ optimizes on first use (a reload that would lose a
+  # suite's in-flight work, such as a queued mail), then wait until the optimizer has been quiet for a few seconds
+  local j='content-type: application/json'
+  curl -s -o /dev/null -X POST "$VB/api/collections/users/auth-with-password" -H "$j" -d '{"identity":"user@example.com","password":"changeme123"}'
+  curl -s -o /dev/null -X POST "$VB/api/collections/users/request-password-reset" -H "$j" -d '{"email":"user@example.com"}'
+  curl -s -o /dev/null "$VB/api/collections/users/auth-methods"
+  curl -s -o /dev/null -m 2 "$VB/api/realtime" || true
+  curl -s -o /dev/null "$VB/api/collections/posts/records?perPage=1"
+  local before after; for _ in $(seq 1 20); do before=$(grep -cE "optimized|program reload" .void/dev.log 2>/dev/null); sleep 3; after=$(grep -cE "optimized|program reload" .void/dev.log 2>/dev/null); [ "$before" = "$after" ] && break; done
+  wait_http "$VB/api/health" 30; echo "warm: optimizer quiet after $after optimization(s)"
+}
+helper() { local name="$1" port="$2"; shift 2; if port_busy "$port"; then echo "reusing $name on $port"; else daemon "$name" ".void/$name.log" "$@"; echo "started $name on $port"; fi; }
+start_reference() {  # a freshly seeded reference: state left by one run or one pass never reaches the next
+  rm -rf .void/reference/pb_data
+  ./scripts/seed-reference.sh .void/reference "$PB_PORT" 0.39.11 "$STARTER_DIR" && started_pb=1
+}
+stop_reference() { if [ "$started_pb" = 1 ] && [ -f .void/reference/pb.pid ]; then kill "$(cat .void/reference/pb.pid)" 2>/dev/null; for _ in $(seq 1 30); do port_busy "$PB_PORT" || break; sleep 0.5; done; started_pb=0; fi; }
+reference() {
+  if port_busy "$PB_PORT"; then echo "reusing the PocketBase listening on $PB"; else start_reference; fi
+  helper smtp-sink 2525 bun test/smtp-sink.ts
+  helper mock-oidc 5190 bun test/mock-oidc.ts
+  helper s3-mock 5195 bun test/s3-mock.ts
+  helper cf-mock 5197 bun test/cf-mock.ts
+  wait_http http://127.0.0.1:2526/messages 30; wait_http http://127.0.0.1:5190/ 30; wait_http http://127.0.0.1:5195/ 30; wait_http http://127.0.0.1:5197/__state 30
+  warm_mail
+}
+warm_mail() {  # the first mail through the SMTP transport goes out here, to the sink, before any suite waits for one
+  local j='content-type: application/json' tok n=0
+  tok=$(curl -s -X POST "$VB/api/collections/_superusers/auth-with-password" -H "$j" -d "{\"identity\":\"$VOIDBASE_SUPERUSER_EMAIL\",\"password\":\"$VOIDBASE_SUPERUSER_PASSWORD\"}" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
+  [ -n "$tok" ] || { echo "warm: superuser login failed, the mail transport stays cold"; return 0; }
+  curl -s -o /dev/null -X DELETE http://127.0.0.1:2526/messages
+  curl -s -o /dev/null -X PATCH "$VB/api/settings" -H "$j" -H "authorization: $tok" -d '{"smtp":{"enabled":true,"host":"127.0.0.1","port":2525,"username":"","password":"","authMethod":"","tls":false,"localName":""}}'
+  # the settings test email: a password reset for the same user would be rate-limited after the boot warm-up
+  curl -s -o /dev/null -X POST "$VB/api/settings/test/email" -H "$j" -H "authorization: $tok" -d '{"email":"warm@example.com","template":"verification"}'
+  for _ in $(seq 1 20); do n=$(curl -s http://127.0.0.1:2526/messages | grep -o '"subject"' | wc -l); [ "$n" -ge 1 ] && break; sleep 1; done
+  # back to the defaults a fresh database starts with (PocketBase's), which the settings comparisons expect
+  curl -s -o /dev/null -X PATCH "$VB/api/settings" -H "$j" -H "authorization: $tok" -d '{"smtp":{"enabled":false,"host":"smtp.example.com","port":587,"username":"","password":"","authMethod":"","tls":false,"localName":""}}'
+  curl -s -o /dev/null -X DELETE http://127.0.0.1:2526/messages
+  echo "warm: mail transport ${n:-0} message(s) delivered to the sink"
+}
+# shellcheck disable=SC2086
+suites() { ./scripts/ci-suites.sh "$PB" "$VB" $(plan_list suites); }
+suites_bun() {  # the selected suites against `voidbase serve` (Bun runtime, SQLite + local files)
+  [ "$booted" = 1 ] && ./scripts/dev.sh stop
+  # the reference PocketBase keeps some state the suites cannot undo (a stored S3 secret, for one), so the Bun pass
+  # gets a fresh one: both sides of every comparison then start from the same state
+  if [ "$started_pb" = 1 ]; then stop_reference; start_reference; fi
+  rm -rf .void/ci-serve; mkdir -p .void/ci-serve
+  daemon serve .void/serve.log bun bin/voidbase.ts serve --http 127.0.0.1:8093 --dir .void/ci-serve/pb_data --hooksDir "$STARTER_DIR/pb/pb_hooks" --migrationsDir "$STARTER_DIR/pb/pb_migrations"
+  wait_http http://127.0.0.1:8093/api/health 60
+  ./scripts/seed-app-user.sh http://127.0.0.1:8093
+  # shellcheck disable=SC2086
+  CI_BROWSER=0 CI_LOGS="$LOGS/bun" ./scripts/ci-suites.sh "$PB" http://127.0.0.1:8093 $(plan_list bun); local rc=$?
+  stop_daemon serve
+  [ "$booted" = 1 ] && ./scripts/dev.sh start "$PORT"
+  return "$rc"
+}
+deploy_cf() { bun test/deploy-cf.ts; }
+adapter() { bun test/adapter.ts; }   # a Void app converted into a voidbase app, then run
+fresh_db() { bun test/fresh-db.ts 5181; }
+mail_http() { bun test/mail-http.ts 5184; }
+exe_smoke() { STARTER_VB_DIR="$STARTER_DIR/pb" bun test/exe-smoke.ts; }
+starter() {  # the unmodified starter frontend against voidbase
+  STARTER_SK_DIR="$STARTER_DIR/sk" ./scripts/starter.sh start 5174 "$VB"
+  bun test/starter-smoke.ts http://127.0.0.1:5174 "$LOGS/starter.png"
+}
+
+release_work() {  # release-please, npm and the executables in this build (docs/releasing.md): on master, when the
+  # commits ask for it or a release still needs publishing; hot mode publishes to npm and leaves the executables
+  local branch; branch="${WORKERS_CI_BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null)}"
+  if [ "$branch" != master ]; then skip_step release "not master"; return 0; fi
+  if [ -z "${GH_TOKEN:-}" ]; then skip_step release "no GH_TOKEN"; return 0; fi
+  local why=""; plan_flag release-merge && why="the release PR was merged"; plan_flag release-pr && why="${why:-releasable commits, refreshing the release PR}"; plan_flag release-dry-run && why="${why:-dry run requested by a commit}"
+  if [ -z "$why" ]; then  # a release that still needs publishing or its executables: cut by hand, or left by hot mode
+    local v rel; v=$(node -p "require('./package.json').version"); rel=$(bun scripts/gh-release.ts view "v$v" 2>/dev/null) || rel=""
+    if [ -n "$rel" ]; then
+      if ! npm view "@voidbase-cloud/voidbase@$v" version >/dev/null 2>&1; then why="release v$v is not on npm yet"
+      elif ! printf '%s' "$rel" | grep -q checksums.txt && [ "${CI_HOT:-0}" != 1 ]; then why="release v$v has no executables yet"; fi
+    fi
+  fi
+  if [ -z "$why" ]; then skip_step release "nothing to release"; return 0; fi
+  echo; echo "=== release: $why"
+  local args=(); plan_flag release-pr || args+=(--no-pr); [ "${CI_HOT:-0}" = 1 ] && args+=(--hot); plan_flag release-dry-run && args+=(--dry-run)
+  export CI_STEPS_DIR CI_STEPS_TSV; CI_NESTED=1 bash scripts/release.sh "${args[@]}"
+}
+run() { step "$@" || exit 1; }
+# maybe <step> <command...>: the step when the plan selects it, else a recorded skip
+maybe() { local name="$1"; shift; if plan_run "step:$name"; then run "$name" "$@"; else skip_step "$name" "$(plan_reason "step:$name")"; fi; }
+run install install
+run cache-restore cache_restore
+run commitlint commitlint_check
+run plan plan
+maybe oracles oracles
+maybe typecheck typecheck
+maybe unit unit
+maybe browser browser
+maybe boot boot
+maybe reference reference
+maybe suites suites
+maybe suites-bun suites_bun
+maybe deploy-cf deploy_cf
+maybe adapter adapter
+maybe fresh-db fresh_db
+maybe mail-http mail_http
+maybe exe-smoke exe_smoke
+maybe starter starter
+release_work || exit 1
+run cache-save cache_save
+echo; echo "every selected step passed"

package/scripts/gh-release.ts

@@ -0,0 +1,48 @@
+// GitHub releases through the REST API for scripts/release.sh, on machines without `gh` (the Workers Builds image):
+//   bun scripts/gh-release.ts view <tag>                 prints {id, tag_name, html_url, assets} or exits 2 when there is no such release
+//   bun scripts/gh-release.ts upload <tag> <file...>     attaches files, replacing same-named assets
+//   bun scripts/gh-release.ts body <tag>                 prints the release notes
+//   bun scripts/gh-release.ts notes <tag> <file>         replaces the release notes with the file's content
+// GH_TOKEN (or GITHUB_TOKEN; `view` and `body` work without one on a public repository); GITHUB_REPOSITORY (default
+// voidbase-cloud/voidbase); GITHUB_API_URL for a mock.
+import { basename } from "node:path";
+
+const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+const [cmd, tag, ...files] = process.argv.slice(2);
+if (!token && cmd !== "view" && cmd !== "body") { console.error("GH_TOKEN is not set"); process.exit(1); }
+const repo = process.env.GITHUB_REPOSITORY ?? "voidbase-cloud/voidbase";
+const api = (process.env.GITHUB_API_URL ?? "https://api.github.com").replace(/\/$/, "");
+const headers: Record<string, string> = { ...(token ? { authorization: `Bearer ${token}` } : {}), accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28", "user-agent": "voidbase-release" };
+interface Asset { id: number; name: string }
+interface Release { id: number; tag_name: string; html_url: string; body: string | null; upload_url: string; assets: Asset[] }
+async function call<T>(method: string, url: string, body?: unknown, raw?: { bytes: Uint8Array; type: string }): Promise<{ status: number; data: T }> {
+  const h = raw ? { ...headers, "content-type": raw.type } : body !== undefined ? { ...headers, "content-type": "application/json" } : headers;
+  const res = await fetch(url.startsWith("http") ? url : `${api}${url}`, { method, headers: h, body: raw ? new Blob([raw.bytes as BlobPart]) : body !== undefined ? JSON.stringify(body) : undefined });
+  const text = await res.text(); let data: unknown = text; try { data = text ? JSON.parse(text) : null; } catch { /* not JSON */ }
+  return { status: res.status, data: data as T };
+}
+const fail = (what: string, r: { status: number; data: unknown }) => { console.error(`${what}: HTTP ${r.status} ${typeof r.data === "string" ? r.data.slice(0, 300) : JSON.stringify(r.data).slice(0, 300)}`); process.exit(1); };
+if (!cmd || !tag || !["view", "upload", "body", "notes"].includes(cmd)) { console.error("usage: bun scripts/gh-release.ts view|body <tag> | upload <tag> <file...> | notes <tag> <file>"); process.exit(2); }
+const got = await call<Release>("GET", `/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`);
+if (got.status === 404) { console.error(`no release ${tag} in ${repo}`); process.exit(2); }
+if (got.status !== 200) fail(`reading release ${tag}`, got);
+const rel = got.data;
+if (cmd === "view") console.log(JSON.stringify({ id: rel.id, tag_name: rel.tag_name, html_url: rel.html_url, assets: rel.assets.map((a) => a.name) }));
+else if (cmd === "body") process.stdout.write(rel.body ?? "");
+else if (cmd === "notes") {
+  if (!files[0]) { console.error("notes: file missing"); process.exit(2); }
+  const r = await call("PATCH", `/repos/${repo}/releases/${rel.id}`, { body: await Bun.file(files[0]).text() });
+  if (r.status !== 200) fail(`updating the notes of ${tag}`, r);
+  console.log(`notes of ${tag} updated`);
+} else {
+  if (!files.length) { console.error("upload: no files"); process.exit(2); }
+  for (const f of files) {
+    const name = basename(f), bytes = new Uint8Array(await Bun.file(f).arrayBuffer());
+    const existing = rel.assets.find((a) => a.name === name);
+    if (existing) { const d = await call("DELETE", `/repos/${repo}/releases/assets/${existing.id}`); if (d.status !== 204) fail(`replacing ${name}`, d); }
+    const type = name.endsWith(".zip") ? "application/zip" : name.endsWith(".tgz") ? "application/gzip" : "text/plain";
+    const r = await call<Asset>("POST", `${rel.upload_url.replace(/\{[^}]*\}$/, "")}?name=${encodeURIComponent(name)}`, undefined, { bytes, type });
+    if (r.status !== 201) fail(`uploading ${name}`, r);
+    console.log(`uploaded ${name} (${bytes.length} bytes)${existing ? " (replaced)" : ""}`);
+  }
+}

package/scripts/release.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# The release flow (docs/releasing.md) as one script, run by Cloudflare Workers Builds (or any machine):
+#   release-pr       keeps the "chore(master): release X.Y.Z" pull request up to date (every push to master)
+#   github-release   tags vX.Y.Z and creates the GitHub release with the compiled notes once that PR is merged
+#   publish          when release v<package.json version> exists and npm lacks that version: check, unit and cloud-rest
+#                    tests, pack, smoke install, npm publish (provenance only where GitHub Actions' OIDC token exists),
+#                    GitHub Packages, the tarball on the release
+#   executables      when that release lacks checksums.txt: every platform, the exe smoke, the archives and checksums on
+#                    the release, the notes opened with the `./voidbase update` hint
+# Idempotent: a re-run after a partial failure does only what is still missing. Steps are recorded for the status page
+# (ci/public, kind release).
+#   scripts/release.sh [--dry-run] [--tag vX.Y.Z] [--no-pr] [--hot]
+#     --dry-run   everything up to the actions: release-please in dry-run mode, npm publish --dry-run, no uploads
+#     --tag       publish a release cut by hand (skips release-please; the checkout must be that tag)
+#     --no-pr     skip the release PR refresh (nothing releasable in the push)
+#     --hot       hot mode: publish to npm, leave the executables to a later normal run
+# scripts/ci.sh runs it as the last step of a CI build (CI_NESTED=1: no reset, no cache, no page of its own).
+# Environment: GH_TOKEN (contents + pull requests write on the repository), NPM_TOKEN, GH_PACKAGES_TOKEN (optional: the
+# Actions token or a classic PAT with write:packages; fine-grained tokens cannot publish packages), GITHUB_REPOSITORY.
+set -uo pipefail
+cd "$(dirname "$0")/.."; ROOT="$PWD"
+. scripts/ci-lib.sh
+DRY=""; TAG=""; PR=1; HOT=""
+while [ $# -gt 0 ]; do case "$1" in --dry-run) DRY=1 ;; --tag) TAG="$2"; shift ;; --no-pr) PR=0 ;; --hot) HOT=1 ;; *) echo "unknown option $1"; exit 2 ;; esac; shift; done
+BACKEND=$(ci_backend); export CI_BACKEND_NAME="$BACKEND"
+REPO="${GITHUB_REPOSITORY:-voidbase-cloud/voidbase}"; export GITHUB_REPOSITORY="$REPO"
+BRANCH="${WORKERS_CI_BRANCH:-${GITHUB_REF_NAME:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null)}}"
+VERSION=$(node -p "require('./package.json').version"); PKG="@voidbase-cloud/voidbase"
+RP=(bunx release-please@17.11.2); RP_ARGS=(--repo-url "$REPO" --token "${GH_TOKEN:-}" --target-branch master --config-file release-please-config.json --manifest-file .release-please-manifest.json)
+CI_CACHE_DIR="$(ci_cache_dir)"; export CI_CACHE_DIR; mkdir -p "$CI_CACHE_DIR"
+outputs() { if [ -n "${GITHUB_OUTPUT:-}" ]; then printf '%s\n' "$@" >> "$GITHUB_OUTPUT"; fi; }
+if [ -z "${CI_NESTED:-}" ]; then
+  rm -rf .void/ci-logs "$CI_STEPS_TSV"; mkdir -p .void/ci-logs
+  finish() { local rc=$?; render_status --kind release || true; if [ "$rc" = 0 ]; then echo "RELEASE FLOW DONE"; else echo "RELEASE FLOW FAILED (exit $rc)"; fi; }
+  trap finish EXIT
+fi
+echo "release flow on $BACKEND: $REPO, branch $BRANCH, package $VERSION${TAG:+, tag $TAG}${DRY:+, dry run}${HOT:+, hot mode (npm only)}"
+
+if [ -z "${CI_NESTED:-}" ]; then step install bun install --frozen-lockfile || exit 1; step cache-restore ./scripts/ci-cache.sh restore || true; fi
+
+# release-please, on master only, unless a release cut by hand is being published; without GH_TOKEN the release PR
+# cannot be maintained, which only matters once something needs publishing (checked below without a token)
+if [ -z "${GH_TOKEN:-}" ]; then echo "GH_TOKEN is not set: release-please skipped, publishing would fail"; skip_step release-pr "no GH_TOKEN"; skip_step github-release "no GH_TOKEN"
+elif [ -z "$TAG" ] && [ "$BRANCH" = master ]; then
+  if [ "$PR" = 1 ]; then step release-pr "${RP[@]}" release-pr "${RP_ARGS[@]}" ${DRY:+--dry-run} || exit 1; else skip_step release-pr; fi
+  step github-release "${RP[@]}" github-release "${RP_ARGS[@]}" ${DRY:+--dry-run} || exit 1
+else skip_step release-pr; skip_step github-release; fi
+
+TAG="${TAG:-v$VERSION}"
+[ "$TAG" = "v$VERSION" ] || { echo "tag $TAG does not match package.json version $VERSION"; exit 1; }
+release_json=$(bun scripts/gh-release.ts view "$TAG" 2>/dev/null) || release_json=""
+if [ -z "$release_json" ] && [ -z "$DRY" ]; then echo; echo "no release $TAG: nothing to publish"; outputs "published=false" "executables=false" "tag=$TAG"; exit 0; fi
+echo "release $TAG: ${release_json:-none (dry run continues)}"
+has_asset() { printf '%s' "$release_json" | grep -qF "\"$1\""; }
+
+on_npm=0; npm view "$PKG@$VERSION" version >/dev/null 2>&1 && on_npm=1
+publish_npm() {
+  bun run check && bun test && bun test/cloud-rest.ts || return 1
+  rm -f voidbase-cloud-voidbase-*.tgz; npm pack || return 1
+  local tarball; tarball="$PWD/$(ls voidbase-cloud-voidbase-*.tgz)"; ls -la "$tarball"
+  local smoke; smoke=$(mktemp -d)
+  (cd "$smoke" && bun init -y >/dev/null && bun add "$tarball" && bunx voidbase help | head -n 5 && node -e "const p=require('$PKG/package.json'); if (p.version !== '$VERSION') throw new Error('version mismatch: ' + p.version)") || return 1
+  [ -n "${NPM_TOKEN:-}" ] || { echo "NPM_TOKEN is not set"; return 1; }
+  # a dry run of a version that is already on npm: npm refuses to "publish over" it even without publishing, so the
+  # rehearsal ends here (the real flow skips publishing altogether for a published version)
+  if [ -n "$DRY" ] && [ "$on_npm" = 1 ]; then echo "npm publish: $PKG@$VERSION is already published, the dry run skips the publish commands"; return 0; fi
+  local npmrc; npmrc=$(mktemp); printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$npmrc"
+  local provenance=""; [ "$BACKEND" = github ] && [ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] && provenance="--provenance"
+  echo "npm publish: provenance ${provenance:-off (only GitHub Actions can mint the OIDC token)}, dry run ${DRY:-no}"
+  NPM_CONFIG_USERCONFIG="$npmrc" npm publish "$tarball" --access public $provenance ${DRY:+--dry-run} || { rm -f "$npmrc"; return 1; }
+  rm -f "$npmrc"
+  if [ -n "${GH_PACKAGES_TOKEN:-}" ]; then
+    npmrc=$(mktemp); printf '@voidbase-cloud:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=%s\n' "$GH_PACKAGES_TOKEN" > "$npmrc"
+    NPM_CONFIG_USERCONFIG="$npmrc" npm publish "$tarball" --registry=https://npm.pkg.github.com ${DRY:+--dry-run} || echo "GitHub Packages publish failed (npm is the registry of record; continuing)"
+    rm -f "$npmrc"
+  else echo "GitHub Packages: skipped (no GH_PACKAGES_TOKEN)"; fi
+  if [ -z "$DRY" ]; then bun scripts/gh-release.ts upload "$TAG" "$tarball" || return 1; fi
+}
+if [ "$on_npm" = 1 ] && [ -z "$DRY" ]; then skip_step publish; echo "$PKG@$VERSION is already on npm"
+elif [ -z "${GH_TOKEN:-}" ]; then echo "release $TAG needs publishing but GH_TOKEN is not set"; exit 1
+else step publish publish_npm || exit 1; [ -z "$DRY" ] && outputs "published=true"; fi
+
+build_executables() {
+  . scripts/ci-oracles.sh
+  XDG_CACHE_HOME="$CI_CACHE_DIR/xdg" bun run panel:sync || return 1
+  bun scripts/build-exe.ts --targets all --out dist/release || return 1
+  cat dist/release/checksums.txt
+  STARTER_VB_DIR="$STARTER_DIR/pb" bun test/exe-smoke.ts || return 1
+  [ -n "$DRY" ] && return 0
+  bun scripts/gh-release.ts upload "$TAG" dist/release/*.zip dist/release/checksums.txt || return 1
+  # PocketBase's shape: the `./voidbase update` hint first, then the compiled notes (`voidbase update` strips the hint again)
+  bun scripts/gh-release.ts body "$TAG" > .void/release-body.md || return 1
+  if ! grep -qF 'To update the prebuilt executable you can run `./voidbase update`' .void/release-body.md; then
+    { printf '> _To update the prebuilt executable you can run `./voidbase update`._\n\n'; cat .void/release-body.md; } > .void/release-notes.md
+    bun scripts/gh-release.ts notes "$TAG" .void/release-notes.md || return 1
+  fi
+}
+if has_asset checksums.txt && [ -z "$DRY" ]; then skip_step executables; echo "release $TAG already has its executables"
+elif [ -n "$HOT" ]; then skip_step executables "hot mode: npm only, a normal run adds them"; echo "release $TAG: executables left to a normal run (hot mode)"
+elif [ -z "${GH_TOKEN:-}" ]; then echo "release $TAG needs its executables but GH_TOKEN is not set"; exit 1
+else step executables build_executables || exit 1; [ -z "$DRY" ] && outputs "executables=true"; fi
+outputs "tag=$TAG"
+if [ -z "${CI_NESTED:-}" ]; then step cache-save ./scripts/ci-cache.sh save || true; fi
+echo; echo "release $TAG: done${DRY:+ (dry run)}${HOT:+ (hot mode)}"

package/scripts/seed-reference.sh

@@ -11,8 +11,13 @@ USER_EMAIL="${REFERENCE_USER_EMAIL:-user@example.com}"; USER_PASSWORD="${REFEREN
 mkdir -p "$DIR"; STARTER="$(cd "$STARTER" && pwd)"
 if [ ! -x "$DIR/pocketbase" ] || [ "$("$DIR/pocketbase" --version 2>/dev/null)" != "pocketbase version $VERSION" ]; then
   arch="linux_amd64"; case "$(uname -m)" in aarch64|arm64) arch="linux_arm64";; esac
-  echo "downloading pocketbase $VERSION ($arch)"
-  curl -sSL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${arch}.zip" -o "$DIR/pb.zip"
+  cached="${CI_CACHE_DIR:+$CI_CACHE_DIR/archives/pocketbase_${VERSION}_${arch}.zip}"
+  if [ -n "$cached" ] && [ -f "$cached" ]; then echo "pocketbase $VERSION ($arch) from the cache"; cp "$cached" "$DIR/pb.zip"
+  else
+    echo "downloading pocketbase $VERSION ($arch)"
+    curl -sSL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${arch}.zip" -o "$DIR/pb.zip"
+    if [ -n "$cached" ]; then mkdir -p "$CI_CACHE_DIR/archives" && cp "$DIR/pb.zip" "$cached"; fi
+  fi
   (cd "$DIR" && unzip -oq pb.zip pocketbase && rm pb.zip)
 fi
 PB=("$DIR/pocketbase" "--dir" "$DIR/pb_data" "--migrationsDir" "$STARTER/pb/pb_migrations" "--hooksDir" "$STARTER/pb/pb_hooks")

package/scripts/sync-app.ts

@@ -15,6 +15,7 @@ mkdirSync(dest, { recursive: true });
 for (const entry of readdirSync(dest)) if (entry !== "_") rmSync(`${dest}/${entry}`, { recursive: true, force: true });
 for (const entry of readdirSync(src)) {
   if (entry === "_") { console.warn("skipping the app's /_ directory: that path belongs to the admin panel"); continue; }
+  if (entry === "_redirects") continue; // becomes void.json routing.redirects (host-aware); Cloudflare's asset layer would reject host sources
   cpSync(`${src}/${entry}`, `${dest}/${entry}`, { recursive: true });
 }
 console.log(`synced app ${src} -> ${dest} (${statSync(`${dest}/index.html`).size} bytes index.html)`);

package/src/adapter/bundle.ts

@@ -0,0 +1,130 @@
+// Bundles the Void app's server code into one file that a pb_hooks sandbox can run.
+//
+// A hook file has no module resolution: its `require` reaches only its sibling hook files, and nothing else. Void's
+// routes import npm packages (`void/response`, `void/db`, Drizzle), so they have to arrive pre-bundled. Two details
+// make that work:
+//   - `node:async_hooks` cannot be bundled and cannot be required at runtime inside the sandbox, so the build
+//     rewrites it to read `globalThis.AsyncLocalStorage`, which voidbase's hook runtime publishes on both runtimes
+//     (src/server/hooks/runtime.ts);
+//   - the output carries the `// voidbase:raw` pragma, which tells the hook compiler to leave it alone instead of
+//     running the await-insertion transform over it (hooks-plugin.ts).
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { BunPlugin } from "bun";
+
+export const RAW_PRAGMA = "// voidbase:raw";
+
+// A hook cannot require a node builtin: the sandbox resolves only its sibling hook files. Two are handled here and
+// anything else fails the build, loudly, rather than at the first request.
+const ASYNC_HOOKS_SHIM = `const g = globalThis;
+if (!g.AsyncLocalStorage) throw new Error("voidbase: AsyncLocalStorage is missing; the hook runtime publishes it");
+export const AsyncLocalStorage = g.AsyncLocalStorage;
+export default { AsyncLocalStorage };`;
+// Bun's CommonJS output opens with an unused \`require("node:module")\` for interop; an empty module satisfies it.
+const MODULE_SHIM = `export const createRequire = () => { throw new Error("voidbase: createRequire is not available inside a hook"); };
+export default { createRequire };`;
+
+const builtinShims: BunPlugin = {
+  name: "voidbase-node-builtins",
+  setup(build) {
+    build.onResolve({ filter: /^(node:)?async_hooks$/ }, () => ({ path: "async_hooks", namespace: "voidbase-shim" }));
+    build.onResolve({ filter: /^(node:)?module$/ }, () => ({ path: "module", namespace: "voidbase-shim" }));
+    build.onResolve({ filter: /^node:/ }, (args) => {
+      throw new Error(`voidbase: ${args.path} cannot be used in code compiled into pb_hooks (imported by ${args.importer}). A hook has no module resolution, so nothing reachable from routes/, middleware/, crons/ or queues/ may import a node builtin.`);
+    });
+    build.onLoad({ filter: /.*/, namespace: "voidbase-shim" }, (args) => ({
+      contents: args.path === "async_hooks" ? ASYNC_HOOKS_SHIM : MODULE_SHIM,
+      loader: "js",
+    }));
+  },
+};
+
+/**
+ * The aliases the bundle needs, which Vite would otherwise apply:
+ *  - `void` itself resolves to the package entry, which carries the Vite plugin and its Cloudflare dependency. A
+ *    route only ever wants the runtime half, so it is rewritten to `void/handler`.
+ *  - the tsconfig paths Void generates (`@schema`, and the shims this adapter points `void/db` and `void/queues`
+ *    at) are compiler-only, so the bundler is told about them explicitly.
+ */
+const CODE_EXT = ["", ".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs", "/index.ts", "/index.tsx", "/index.js"];
+// the bare "" comes first so `@schema` -> db/schema.ts wins over a `db/schema/` directory, but an alias whose target
+// is a directory (`@/shared` -> src/shared) has to fall through to its index file rather than resolve to the folder
+const isFile = (p: string) => { try { return statSync(p).isFile(); } catch { return false; } };
+const asFile = (base: string): string | null => CODE_EXT.map((e) => base + e).find(isFile) ?? null;
+
+/** every `paths` entry of a tsconfig fragment, with its targets resolved against that file */
+function pathsOf(file: string): Record<string, string[]> {
+  if (!existsSync(file)) return {};
+  try {
+    const cfg = JSON.parse(readFileSync(file, "utf8")) as { compilerOptions?: { paths?: Record<string, string[]> } };
+    const out: Record<string, string[]> = {};
+    for (const [key, targets] of Object.entries(cfg.compilerOptions?.paths ?? {})) {
+      out[key] = targets.map((t) => (isAbsolute(t) ? t : resolve(dirname(file), t)));
+    }
+    return out;
+  } catch { return {}; }
+}
+
+function aliasPlugin(root: string): BunPlugin {
+  // the adapter's own fragment first (it repoints void/db and void/queues at the shims), then Void's, then the
+  // project's own tsconfig; `@schema` falls back to Void's convention when no fragment has been generated yet
+  const paths: Record<string, string[]> = {
+    ...pathsOf(join(root, "tsconfig.json")),
+    ...pathsOf(join(root, ".void", "tsconfig.json")),
+    ...pathsOf(join(root, ".voidbase", "tsconfig.json")),
+  };
+  if (!paths["@schema"] && existsSync(join(root, "db", "schema.ts"))) paths["@schema"] = [join(root, "db", "schema.ts")];
+
+  const exact = Object.entries(paths).filter(([k]) => !k.includes("*"));
+  const wildcard = Object.entries(paths).filter(([k]) => k.endsWith("/*")).map(([k, v]) => [k.slice(0, -1), v] as const);
+
+  return {
+    name: "voidbase-aliases",
+    setup(build) {
+      // `void` itself is the package entry, which carries the Vite plugin; a route only wants the runtime half
+      build.onResolve({ filter: /^void$/ }, () => ({ path: Bun.resolveSync("void/handler", root) }));
+      build.onResolve({ filter: /.*/ }, (args) => {
+        for (const [key, targets] of exact) {
+          if (args.path !== key) continue;
+          const hit = targets.map(asFile).find(Boolean);
+          if (hit) return { path: hit };
+        }
+        for (const [prefix, targets] of wildcard) {
+          if (!args.path.startsWith(prefix)) continue;
+          const rest = args.path.slice(prefix.length);
+          const hit = targets.map((t) => asFile(t.replace(/\*$/, "") + rest)).find(Boolean);
+          if (hit) return { path: hit };
+        }
+        return undefined; // let Bun resolve it
+      });
+    },
+  };
+}
+
+export interface BundleResult { code: string; bytes: number }
+
+/**
+ * Builds `entry` (a generated module exporting `register(api)`) into a single CommonJS file.
+ * Throws with Bun's own diagnostics when the app's code does not bundle.
+ */
+export async function bundleHookApp(entry: string, root: string): Promise<BundleResult> {
+  if (!existsSync(entry)) throw new Error(`voidbase: bundle entry ${entry} does not exist`);
+  const built = await Bun.build({
+    entrypoints: [resolve(entry)],
+    root: resolve(root),
+    target: "node", // Bun and workerd both run the result; the shim keeps node builtins out of it
+    format: "cjs",
+    minify: false, // the file is read when something goes wrong in production
+    sourcemap: "none",
+    plugins: [builtinShims, aliasPlugin(resolve(root))],
+    throw: false, // the diagnostics below are more useful than Bun's AggregateError
+  });
+  if (!built.success) {
+    const why = built.logs.map((l) => `${l.level}: ${l.message}${(l as { position?: { file?: string } }).position?.file ? ` (${(l as { position?: { file?: string } }).position!.file})` : ""}`).join("\n");
+    throw new Error(`voidbase: could not bundle the app's server code for pb_hooks.\n${why}`);
+  }
+  const [artifact] = built.outputs;
+  if (!artifact) throw new Error("voidbase: the bundler produced no output");
+  const code = await artifact.text();
+  return { code: `${RAW_PRAGMA}\n// Generated by voidbase's Void adapter from routes/, middleware/, crons/ and queues/.\n${code}`, bytes: code.length };
+}