@voidbase-cloud/voidbase 0.2.2 → 0.4.0

package/src/adapter/runtime.ts

@@ -0,0 +1,325 @@
+// Runs a Void app's server code inside voidbase, from a pb_hooks file.
+//
+// This module is bundled into `.voidbase/pb_hooks/void-app.js` together with the app's own routes, so it must not
+// import anything from voidbase: a hook runs in a sandbox whose `require` reaches only its sibling hook files.
+// PocketBase's API reaches it through `pb`, which reads the hook globals the generated `.pb.js` wrapper publishes
+// before it requires this bundle. Its only imports are Void's own runtime, which is bundled along with it.
+//
+// Two things make Void code run unchanged:
+//   - routes register through `routerAdd`, the registry every pb_hooks route uses, and the RequestEvent it hands
+//     the handler carries `.c`, the real Hono context Void handlers expect;
+//   - every handler body runs inside `withRuntimeEnv`, Void's AsyncLocalStorage for bindings, so `void/db`,
+//     `void/storage`, `void/env` and `void/queues` resolve against voidbase's D1 and R2 with no shim.
+import { withRuntimeEnv } from "void/_env";
+import { convertReturnValue } from "void/response";
+import type { Context } from "hono";
+// types only: erased by the bundler, so this file keeps its promise of importing nothing from voidbase at runtime
+import type { AppApi, RequestEvent } from "../server/hooks/runtime";
+import type { CollectionRef, HookRecord } from "../server/hooks/record";
+
+type Handler = (c: Context) => unknown;
+export type Middleware = (c: Context, next: () => Promise<void>) => Promise<void>;
+
+/** PocketBase's global request middleware: every request, before whatever answers it. */
+export const REQUEST_HOOK = "routerUse";
+/** The name of a PocketBase hook: `routerUse`, or one of its `on*` events. */
+export type HookName = typeof REQUEST_HOOK | `on${string}`;
+/** A `vb_hooks/` file's default export. */
+export interface HookModule<E = HookEvent> { (e: E): unknown; hook: HookName; tags: string[] }
+/** What a hook handler is given. Request hooks carry `.c`, the Hono context; every hook carries `.next()`. */
+export type HookEvent = { next(): Promise<unknown> } & Record<string, unknown>;
+type Bindings = Record<string, unknown>;
+
+type ErrorClass = new (message?: string, data?: unknown) => Error;
+/* eslint-disable @typescript-eslint/no-explicit-any -- PocketBase events are many shapes; the hook API is loose by nature */
+type EventRegistrar = (fn: (e: any) => unknown, ...tags: string[]) => void;
+
+/**
+ * PocketBase's API, as the app's own code sees it. A route compiled into pb_hooks cannot import voidbase, so the
+ * generated hook publishes the hook globals and this reads them:
+ *
+ *     import { defineHandler } from "void";
+ *     import { pb, requireAuth } from "@voidbase-cloud/voidbase/adapter";
+ *
+ *     export const GET = defineHandler(requireAuth("users"), async () => {
+ *       return { posts: await pb.$app.findRecordsByFilter("posts", "published = true", "-created", 20, 0) };
+ *     });
+ *
+ * It is filled in before any module body runs, so a plain module under `src/` can register PocketBase's *event*
+ * hooks at import time, exactly as a hook file does — as long as a route or middleware imports it:
+ *
+ *     // src/server/audit.ts, imported by the routes that need it
+ *     pb.onRecordAfterCreateSuccess((e) => { ... }, "posts");
+ */
+export type PocketBaseApi = {
+  /** the data API: findRecordById, findRecordsByFilter, save, delete, settings, ... */
+  $app: AppApi;
+  $apis: { requireAuth(...collections: string[]): unknown; requireSuperuserAuth(): unknown; requireGuestOnly(): unknown };
+  $os: { getenv(name: string): string };
+  /** the bindings of the request, cron tick or job running now */
+  $env(): Bindings;
+  /** voidbase's background queue */
+  $jobs: {
+    queueJob(job: { type: "queue"; queue: string; body: unknown }): Promise<unknown>;
+    onJob(type: "queue", fn: (env: Bindings, job: { queue: string; body: unknown }) => Promise<void>): void;
+  };
+  Record: new (collection: CollectionRef, data?: Record<string, unknown>) => HookRecord;
+  ApiError: ErrorClass;
+  BadRequestError: ErrorClass;
+  UnauthorizedError: ErrorClass;
+  ForbiddenError: ErrorClass;
+  NotFoundError: ErrorClass;
+  InternalServerError: ErrorClass;
+  ValidationError: ErrorClass;
+  routerAdd(method: string, path: string, handler: (e: RequestEvent) => unknown): void;
+  /** PocketBase's global middleware: every request, before the route that answers it */
+  routerUse(...middlewares: ((e: RequestEvent) => unknown)[]): void;
+  cronAdd(id: string, expr: string, fn: () => unknown): void;
+} & { [K in `on${string}`]: EventRegistrar };
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/** where the generated hook publishes the globals, before it requires this bundle */
+const HANDOFF = "__voidbaseHooks";
+const hookGlobals = () => (globalThis as Record<string, unknown>)[HANDOFF] as Record<string | symbol, unknown> | undefined;
+
+// Registering something -- an event hook, a route, a cron -- is the one thing a module may do while it is being
+// imported, and a module is imported in more places than the generated app: Void's build evaluates the same code
+// to prerender the pages, with no PocketBase anywhere. So registrations made before the hook globals arrive are
+// held and replayed once they do, and discarded with the process when they never do. Everything else -- $app and
+// the rest of the data API -- has no answer outside the app and says so.
+const REGISTRAR = /^(on[A-Z]|routerAdd$|routerUse$|cronAdd$)/;
+const deferred: { prop: string; args: unknown[] }[] = [];
+let replayed = false;
+function replay(globals: Record<string | symbol, unknown>) {
+  if (replayed) return;
+  replayed = true;
+  for (const call of deferred.splice(0)) (globals[call.prop] as (...a: unknown[]) => unknown)(...call.args);
+}
+
+export const pb: PocketBaseApi = new Proxy({} as PocketBaseApi, {
+  get(_t, prop) {
+    const globals = hookGlobals();
+    if (globals) { replay(globals); return globals[prop]; }
+    if (typeof prop === "string" && REGISTRAR.test(prop)) return (...args: unknown[]) => { deferred.push({ prop, args }); };
+    throw new Error(`voidbase: pb.${String(prop)} is only available inside the generated app, where the hook publishes PocketBase's API`);
+  },
+});
+
+/**
+ * A `vb_hooks/` file: one PocketBase hook, registered once when the app mounts. The file names its hook here, so
+ * the build can read it without running anything:
+ *
+ *     // vb_hooks/10.audit.ts
+ *     import { defineHook } from "@voidbase-cloud/voidbase/adapter";
+ *
+ *     export default defineHook("onRecordAfterCreateSuccess", async (e) => {
+ *       await e.next();
+ *       console.log("created", e.record);
+ *     }, "posts");
+ *
+ * The trailing arguments are PocketBase's tags, the collections the hook is limited to. A middleware that runs on
+ * every request is Void's own thing and belongs in `middleware/`, written with `defineMiddleware`.
+ */
+export function defineHook<E = HookEvent>(hook: HookName, handler: (e: E) => unknown, ...tags: string[]): HookModule<E> {
+  return Object.assign(handler, { hook, tags }) as HookModule<E>;
+}
+
+/**
+ * `vb_secrets/main.ts`: the secrets the app needs, named where the build can read them. Their values live in
+ * `vb_secrets/secrets.json` (git-ignored) on a dev machine and as the Worker's secrets once deployed; the app reads
+ * them like any binding (`c.env.SMTP_PASSWORD`, `pb.$os.getenv("SMTP_PASSWORD")`):
+ *
+ *     export default defineSecrets({
+ *       SMTP_PASSWORD: "the mail provider's SMTP password",
+ *     });
+ *
+ * The result is the declaration itself, so `keyof typeof secrets` names them for the app's own typing.
+ */
+export function defineSecrets<const T extends Record<string, string | { description?: string }>>(secrets: T): T {
+  return secrets;
+}
+
+const AUTH = Symbol.for("voidbase.auth");
+/** The authenticated record of this request, exactly as a PocketBase hook sees it (`e.auth`). */
+export function authOf(c: Context): HookRecord | null {
+  return ((c as unknown as Record<symbol, HookRecord | null>)[AUTH]) ?? null;
+}
+
+/** Void-shaped counterparts of $apis.requireAuth / requireSuperuserAuth, for `defineHandler(mw, handler)`. */
+export function requireAuth(...collections: string[]): Middleware {
+  return async (c, next) => {
+    const auth = authOf(c);
+    if (!auth || (collections.length && !collections.includes(auth.collection().name))) throw new pb.UnauthorizedError("The request requires valid record authorization token.");
+    await next();
+  };
+}
+export function requireSuperuser(): Middleware {
+  return async (c, next) => {
+    const auth = authOf(c);
+    if (!auth) throw new pb.UnauthorizedError("The request requires valid record authorization token.");
+    if (!auth.isSuperuser()) throw new pb.ForbiddenError("The authorized record is not allowed to perform this action.");
+    await next();
+  };
+}
+
+export interface MountedRoute {
+  url: string;
+  hookPath: string;
+  methods: string[];
+  params: string[];
+  splat?: string;
+  /** the route module: { GET, POST, ... } */
+  mod: Record<string, unknown>;
+}
+export interface MountedQueue {
+  name: string;
+  binding: string;
+  /** the queue module's default export, a `defineQueue` consumer */
+  consumer: (batch: QueueBatch, env: Bindings) => unknown;
+}
+export interface MountedCron {
+  /** the cron id, taken from the file name */
+  name: string;
+  /** the schedule the module exports as `cron` */
+  expr: string;
+  handler: (controller: { cron: string; scheduledTime: number }, env: Bindings) => unknown;
+}
+export interface QueueMessage { id: string; body: unknown; timestamp: Date; attempts: number; ack(): void; retry(): void }
+export interface QueueBatch { queue: string; messages: QueueMessage[]; ackAll(): void; retryAll(): void }
+
+export interface MountedHook {
+  /** the hook this file attaches to, read from its source at build time */
+  hook: HookName;
+  /** the file's default export */
+  handler: HookModule;
+}
+
+export interface MountSpec {
+  /** vb_hooks/, in file order: one PocketBase hook each, registered once */
+  hooks?: MountedHook[];
+  routes?: MountedRoute[];
+  /** middleware/, in file order: Void's own, registered through routerUse so it runs on every request */
+  middleware?: Middleware[];
+  crons?: MountedCron[];
+  queues?: MountedQueue[];
+}
+
+/** Producer bindings for the app's queues, overlaid on the real env so `void/queues` and `c.env.QUEUE_X` both work. */
+function queueBindings(queues: MountedQueue[]): Bindings {
+  const out: Bindings = {};
+  for (const q of queues) {
+    out[q.binding] = {
+      send: (body: unknown) => pb.$jobs.queueJob({ type: "queue", queue: q.name, body }),
+      sendBatch: async (messages: Iterable<{ body: unknown }>) => { for (const m of messages) await pb.$jobs.queueJob({ type: "queue", queue: q.name, body: m.body }); },
+    };
+  }
+  return out;
+}
+
+/** Pulls `:param` and `[...splat]` values out of the path the router matched. */
+function paramsOf(route: MountedRoute, path: string): Record<string, string> {
+  const pattern = route.hookPath.split("/");
+  const actual = path.split("/");
+  const params: Record<string, string> = {};
+  for (let i = 0; i < pattern.length; i++) {
+    const seg = pattern[i]!;
+    if (seg === "*") { if (route.splat) params[route.splat] = actual.slice(i).join("/"); break; }
+    if (seg.startsWith(":")) params[seg.slice(1)] = decodeURIComponent(actual[i] ?? "");
+  }
+  return params;
+}
+
+/** The Hono context a Void handler sees: real context, with the route's params and the queue bindings overlaid. */
+function voidContext(c: Context, params: Record<string, string>, env: Bindings, auth: HookRecord | null): Context {
+  const bind = <T extends object>(target: T, prop: string | symbol) => {
+    const value = Reflect.get(target, prop, target);
+    return typeof value === "function" ? (value as (...a: unknown[]) => unknown).bind(target) : value;
+  };
+  const req = new Proxy(c.req, {
+    get(target, prop) {
+      if (prop === "param") return (name?: string) => (name === undefined ? { ...target.param(), ...params } : params[name] ?? target.param(name as never));
+      return bind(target, prop);
+    },
+  });
+  return new Proxy(c, {
+    get(target, prop) {
+      if (prop === "req") return req;
+      if (prop === "env") return env;
+      if (prop === AUTH) return auth;
+      return bind(target, prop);
+    },
+    set(target, prop, value) { return Reflect.set(target, prop, value, target); },
+  }) as Context;
+}
+
+/** A handler's return value becomes a Response exactly as Void converts it. */
+async function runHandler(c: Context, handler: Handler): Promise<Response> {
+  c.res = convertReturnValue(await handler(c));
+  return c.res;
+}
+
+export function mountVoidApp(spec: MountSpec): void {
+  const { hooks = [], routes = [], middleware = [], crons = [], queues = [] } = spec;
+
+  const envFor = (base: Bindings): Bindings => (queues.length ? { ...base, ...queueBindings(queues) } : base);
+
+  // vb_hooks/ first, in file order: one PocketBase hook per file, registered once. An onBootstrap has to be in
+  // place before voidbase opens the database, and nothing else here depends on the order.
+  for (const h of hooks) {
+    const register = pb[h.hook] as (fn: (e: HookEvent) => unknown, ...tags: string[]) => void;
+    if (typeof register !== "function") throw new Error(`voidbase: "${h.hook}" is not one of PocketBase's hooks`);
+    register(h.handler, ...(h.handler.tags ?? []));
+  }
+
+  // Void's middleware/ means every request, and PocketBase's routerUse is exactly that: in file order, before
+  // whatever answers, PocketBase's own endpoints and the admin panel included. So a middleware that throws takes
+  // the whole backend with it.
+  for (const voidMw of middleware) {
+    pb.routerUse(async (e: RequestEvent) => {
+      const c = e.c;
+      const env = envFor(c.env as unknown as Bindings);
+      const ctx = voidContext(c, {}, env, e.auth ?? null);
+      let called = false;
+      const res = await withRuntimeEnv(env, () => voidMw(ctx, async () => { called = true; await e.next(); }));
+      if (!called && res === undefined) await e.next(); // a middleware that returned without calling next() still passes through
+      return res;
+    });
+  }
+
+  for (const route of routes) {
+    for (const method of route.methods) {
+      const handler = route.mod[method] as Handler | undefined;
+      if (typeof handler !== "function") continue;
+      pb.routerAdd(method === "ALL" ? "ANY" : method, route.hookPath, async (e) => {
+        const c = e.c;
+        const env = envFor(c.env as unknown as Bindings);
+        const ctx = voidContext(c, paramsOf(route, new URL(c.req.url).pathname), env, e.auth ?? null);
+        return withRuntimeEnv(env, () => runHandler(ctx, handler));
+      });
+    }
+  }
+
+  for (const cron of crons) {
+    // cronAdd's callback takes no arguments: the bindings come from the hook store the cron runner opens
+    pb.cronAdd(cron.name, cron.expr, async () => {
+      const env = pb.$env();
+      const controller = { cron: cron.expr, scheduledTime: Date.now() };
+      await withRuntimeEnv(envFor(env), () => cron.handler(controller, env));
+    });
+  }
+
+  if (queues.length) {
+    const byName = new Map(queues.map((q) => [q.name, q]));
+    // One handler for every app queue: voidbase carries the message on its own jobs queue (or runs it inline when
+    // the deploy has none), so a Void consumer sees a one-message batch. A throw is the retry signal.
+    pb.$jobs.onJob("queue", async (env, job) => {
+      const q = byName.get(job.queue);
+      if (!q) throw new Error(`voidbase: no consumer for queue "${job.queue}"`);
+      let retry = false;
+      const message: QueueMessage = { id: crypto.randomUUID(), body: job.body, timestamp: new Date(), attempts: 1, ack: () => { retry = false; }, retry: () => { retry = true; } };
+      const batch: QueueBatch = { queue: q.name, messages: [message], ackAll: () => { retry = false; }, retryAll: () => { retry = true; } };
+      await withRuntimeEnv(envFor(env), () => q.consumer(batch, env));
+      if (retry) throw new Error(`voidbase: queue "${job.queue}" asked to retry`);
+    });
+  }
+}

package/src/adapter/scan.ts

@@ -0,0 +1,277 @@
+// Reads a Void app's file conventions (void/docs/reference/structure.md) into a manifest. The scan is pure
+// filesystem plus a TypeScript parse for the exported names, so it never imports the app's own code: the same
+// function runs inside the Vite plugin, in `voidbase adapt` and in tests without booting the app.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative, resolve } from "node:path";
+import ts from "typescript";
+import { EVENT_HOOKS } from "../../hooks-plugin";
+import { DECLARATION_FILES, parseSecretsDeclaration, readSecretsValues, VALUES_FILE, type SecretsDeclaration } from "../node/secrets";
+
+const CODE = new Set([".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs"]);
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "ALL"] as const;
+
+export interface VoidRoute {
+  /** source file, relative to the app root */
+  file: string;
+  /** URL the file maps to, in Void's own syntax: /api/users/:id, /files/* */
+  url: string;
+  /** the same path in the hook router's dialect (identical today; kept explicit so one can move) */
+  hookPath: string;
+  /** exported HTTP methods, uppercase */
+  methods: string[];
+  /** :param names in order, and the trailing [...name] when the route is a catch-all */
+  params: string[];
+  splat?: string;
+}
+export interface VoidModule { file: string; name: string }
+/** A `vb_hooks/` file: one PocketBase hook, registered once. `hook` is `routerUse` or an `on*` event name. */
+export interface VoidHook extends VoidModule { hook: string }
+export interface VoidQueue extends VoidModule {
+  /** Void derives the producer binding from the file name: queues/send-mail.ts -> QUEUE_SEND_MAIL */
+  binding: string;
+}
+export interface VoidMigration { file: string; name: string }
+
+/** Where a Void app keeps what belongs to voidbase rather than to Void. All of it is optional. */
+export interface VoidbaseExtras {
+  /** vb_migrations/: PocketBase JS migrations, copied in beside the ones generated from db/migrations */
+  migrationsDir?: string;
+  /** vb_secrets/: main.ts declares the configuration (defineSecrets), secrets.json (git-ignored) holds the local values */
+  secretsDir?: string;
+}
+/** The two directories this adapter adds to a Void app, both named for the voidbase thing they are, both sitting
+ * at the project root beside Void's own `db/`. Everything else is Void's and means what Void means by it:
+ * `routes/`, `middleware/`, `crons/` and `queues/` are the server code, compiled into the generated app's
+ * pb_hooks, and `src/` is library code they import. */
+export const MIGRATIONS_DIR = "vb_migrations";
+export const HOOKS_DIR = "vb_hooks";
+export const SECRETS_DIR = "vb_secrets";
+
+/** PocketBase's global request middleware: what Void's own `middleware/` becomes. */
+export const REQUEST_HOOK = "routerUse";
+/** every name a `vb_hooks/` file may attach itself to */
+export const HOOK_NAMES: readonly string[] = [REQUEST_HOOK, ...EVENT_HOOKS];
+/** the known hooks whose names are closest to `name`, for the build error */
+function nearestHooks(name: string): string[] {
+  const needle = name.toLowerCase();
+  return HOOK_NAMES.filter((h) => { const k = h.toLowerCase(); return k.includes(needle) || needle.includes(k); }).slice(0, 4);
+}
+
+/** paths voidbase serves itself; an app route under one of these never reaches the app (PocketBase answers first) */
+export const RESERVED_PREFIXES = ["/api/backups", "/api/batch", "/api/collections", "/api/crons", "/api/files", "/api/health", "/api/logs", "/api/realtime", "/api/settings", "/api/webauthn", "/_/"];
+
+export interface VoidManifest {
+  root: string;
+  /** static: nothing to run, the build is just files under pb_public. server: routes/middleware/crons/queues exist. */
+  mode: "static" | "server";
+  routes: VoidRoute[];
+  middleware: VoidModule[];
+  /** vb_hooks/: one PocketBase hook per file, registered once when the app mounts */
+  hooks: VoidHook[];
+  crons: VoidModule[];
+  queues: VoidQueue[];
+  migrations: VoidMigration[];
+  /** vb_secrets/main.ts: the configuration the app declares, names and tiers only (values are never part of the manifest) */
+  secrets: SecretsDeclaration | null;
+  /** the app's own voidbase side (vb_migrations/, vb_secrets/) */
+  extras: VoidbaseExtras;
+  /** directories the app has that this adapter cannot carry, with the reason */
+  unsupported: { what: string; why: string }[];
+  /** app routes shadowed by voidbase's own API */
+  collisions: string[];
+}
+
+const isDir = (p: string) => existsSync(p) && statSync(p).isDirectory();
+
+/** Every code file under dir, depth first, skipping `_`-prefixed files and directories (Void ignores those). */
+function walk(dir: string, base = dir): string[] {
+  if (!isDir(dir)) return [];
+  return readdirSync(dir).sort().flatMap((entry) => {
+    if (entry.startsWith("_")) return [];
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) return walk(full, base);
+    return CODE.has(extname(entry)) ? [relative(base, full)] : [];
+  });
+}
+
+/** `debug.dev.ts` builds in development only, `metrics.prod.ts` in production only; everything else in both. */
+function envSuffix(file: string): "dev" | "prod" | null {
+  const stem = basename(file, extname(file));
+  if (stem.endsWith(".dev")) return "dev";
+  if (stem.endsWith(".prod")) return "prod";
+  return null;
+}
+/** the file name without its extension and without a `.dev` / `.prod` suffix (`[...path].ts` keeps its dots) */
+function stemOf(file: string): string {
+  return basename(file, extname(file)).replace(/\.(dev|prod)$/, "");
+}
+
+/**
+ * The PocketBase hook a `vb_hooks/` file attaches to, read from the source without evaluating it:
+ *
+ *     export default defineHook("onRecordCreate", handler, "posts")
+ *
+ * `export const hook = "onRecordCreate"` names it too, for a handler that comes from somewhere else. Returns null
+ * when the file names no hook, which is a build error: there is nowhere to register it.
+ */
+export function hookName(code: string, file = "m.ts"): string | null {
+  const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+  const literal = (n: ts.Node | undefined) => (n && ts.isStringLiteralLike(n) ? n.text : null);
+  let fromCall: string | null = null;
+  let fromConst: string | null = null;
+
+  const callName = (expr: ts.Expression): string | null => {
+    if (!ts.isCallExpression(expr)) return null;
+    const callee = ts.isPropertyAccessExpression(expr.expression) ? expr.expression.name.text : ts.isIdentifier(expr.expression) ? expr.expression.text : "";
+    return callee === "defineHook" ? literal(expr.arguments[0]) : null;
+  };
+
+  for (const st of sf.statements) {
+    if (ts.isExportAssignment(st) && !st.isExportEquals) fromCall ??= callName(st.expression);
+    if (ts.isVariableStatement(st)) {
+      for (const d of st.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || !d.initializer) continue;
+        if (d.name.text === "hook") fromConst ??= literal(d.initializer);
+        // `const mw = defineHook(...); export default mw;` is the same declaration, read through
+        fromCall ??= callName(d.initializer);
+      }
+    }
+  }
+  return fromCall ?? fromConst;
+}
+
+/** The names a module exports, without evaluating it (`export const GET`, `export { GET }`, `export default`). */
+export function exportedNames(code: string, file = "m.ts"): Set<string> {
+  const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+  const names = new Set<string>();
+  const exported = (node: ts.Node) => !!ts.canHaveModifiers(node) && !!ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+  for (const st of sf.statements) {
+    if (ts.isVariableStatement(st) && exported(st)) for (const d of st.declarationList.declarations) if (ts.isIdentifier(d.name)) names.add(d.name.text);
+    if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && exported(st) && st.name) names.add(st.name.text);
+    if (ts.isExportAssignment(st)) names.add("default");
+    if (ts.isExportDeclaration(st) && st.exportClause && ts.isNamedExports(st.exportClause)) for (const el of st.exportClause.elements) names.add(el.name.text);
+    if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && ts.canHaveModifiers(st) && ts.getModifiers(st)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) names.add("default");
+  }
+  return names;
+}
+
+/** routes/api/users/[id].ts -> { url: "/api/users/:id", params: ["id"] }; (group)/ is stripped, index is the directory. */
+export function routeUrl(file: string): { url: string; params: string[]; splat?: string } {
+  const params: string[] = [];
+  let splat: string | undefined;
+  const stem = stemOf(file);
+  const segments = [...file.split(/[\\/]/).slice(0, -1), stem]
+    .filter((s) => s && !(s.startsWith("(") && s.endsWith(")")))
+    .filter((s, i, all) => !(s === "index" && i === all.length - 1));
+  const path = segments.map((seg) => {
+    const catchAll = /^\[\.\.\.(.+)\]$/.exec(seg);
+    if (catchAll) { splat = catchAll[1]!; return "*"; }
+    const param = /^\[(.+)\]$/.exec(seg);
+    if (param) { params.push(param[1]!); return `:${param[1]}`; }
+    return seg;
+  }).join("/");
+  return { url: "/" + path, params, splat };
+}
+
+export interface ScanOptions { root?: string; dev?: boolean }
+
+export function scanVoidApp(opts: ScanOptions = {}): VoidManifest {
+  const root = resolve(opts.root ?? ".");
+  const dev = !!opts.dev;
+  const rel = (dir: string, file: string) => `${dir}/${file.split("\\").join("/")}`;
+
+  const routes: VoidRoute[] = [];
+  for (const file of walk(join(root, "routes"))) {
+    const suffix = envSuffix(file);
+    if (suffix && (suffix === "dev") !== dev) continue;
+    const methods = [...exportedNames(readFileSync(join(root, "routes", file), "utf8"), file)].filter((n) => (HTTP_METHODS as readonly string[]).includes(n));
+    if (!methods.length) continue; // a file in routes/ that exports no verb is not a route
+    const { url, params, splat } = routeUrl(file);
+    routes.push({ file: rel("routes", file), url, hookPath: url, methods, params, ...(splat ? { splat } : {}) });
+  }
+  // most specific first, so /api/users/me is registered before /api/users/:id and /files/*
+  routes.sort((a, b) => score(b.url) - score(a.url) || a.url.localeCompare(b.url));
+
+  const modules = (dir: string): VoidModule[] =>
+    walk(join(root, dir)).map((file) => ({ file: rel(dir, file), name: stemOf(file) }));
+
+  // Void's own middleware/: every request, in file order, which is PocketBase's routerUse. A file that turns out to
+  // be a PocketBase hook belongs next door, and says so rather than being called with the wrong arguments.
+  const middleware = modules("middleware").map((m) => {
+    const named = hookName(readFileSync(join(root, m.file), "utf8"), m.file);
+    if (named) throw new Error(`voidbase: ${m.file} is a PocketBase hook ("${named}"), not a Void middleware. Move it to ${HOOKS_DIR}/, where one file is one hook.\n  middleware/ is Void's: defineMiddleware((c, next) => ...), every request, no hook to name.`);
+    return m;
+  });
+
+  // vb_hooks/: one file, one PocketBase hook, registered once when the app mounts. Numeric prefixes order them,
+  // and walk() already sorts by name.
+  const hooks: VoidHook[] = modules(HOOKS_DIR).map((m) => {
+    const hook = hookName(readFileSync(join(root, m.file), "utf8"), m.file);
+    if (!hook) throw new Error(`voidbase: ${m.file} is not attached to a hook, so there is nowhere to register it. Name the hook it is:\n  export default defineHook("onRecordCreate", handler, "posts")\n  A plain Void middleware, running on every request, belongs in middleware/ instead.`);
+    if (!HOOK_NAMES.includes(hook)) {
+      const near = nearestHooks(hook);
+      throw new Error(`voidbase: ${m.file} names "${hook}", which is not one of PocketBase's hooks.${near.length ? ` Did you mean ${near.join(", ")}?` : ` Use "${REQUEST_HOOK}" for a request middleware, or one of PocketBase's on* event hooks.`}`);
+    }
+    return { ...m, hook };
+  });
+  const crons = modules("crons");
+  const queues: VoidQueue[] = modules("queues").map((q) => ({ ...q, binding: `QUEUE_${q.name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}` }));
+
+  const migrationsDir = join(root, "db", "migrations");
+  const migrations: VoidMigration[] = isDir(migrationsDir)
+    ? readdirSync(migrationsDir).sort().filter((f) => f.endsWith(".sql")).map((f) => ({ file: `db/migrations/${f}`, name: basename(f, ".sql") }))
+    : [];
+
+  // `output: "static"` prerenders every page to HTML at build time, which is exactly what pb_public wants; pages
+  // that still need rendering per request have no runtime here, so say so.
+  let voidOutput = "server";
+  try { voidOutput = (JSON.parse(readFileSync(join(root, "void.json"), "utf8")) as { output?: string }).output ?? "server"; } catch { /* no void.json */ }
+  const unsupported: { what: string; why: string }[] = [];
+  if (isDir(join(root, "pages")) && voidOutput !== "static") unsupported.push({ what: "pages/", why: 'server-rendered pages need Void\'s render pipeline; set "output": "static" in void.json to prerender them into pb_public' });
+  if (walk(join(root, "routes")).some((f) => f.endsWith(".ws.ts"))) unsupported.push({ what: "routes/**/*.ws.ts", why: "document WebSockets are Durable Objects; voidbase's realtime hub owns that binding" });
+  if (grepImports(root, "void/kv")) unsupported.push({ what: "void/kv", why: "voidbase binds D1 and R2 only; keep key-value data in a collection" });
+  if (grepImports(root, "void/isr")) unsupported.push({ what: "void/isr", why: "ISR caches through the Void platform's dispatch worker, which a voidbase app does not have" });
+
+  const extras: VoidbaseExtras = {
+    migrationsDir: isDir(join(root, MIGRATIONS_DIR)) ? MIGRATIONS_DIR : undefined,
+    secretsDir: isDir(join(root, SECRETS_DIR)) ? SECRETS_DIR : undefined,
+  };
+
+  // vb_secrets/: main.ts declares the configuration (`export default defineSecrets({ NAME: string().secret(), ... })`),
+  // read here without running it (names and tiers; the validators run where values are parsed); secrets.json
+  // beside it is the git-ignored local values file. Values that nothing declares are a build error: they would
+  // silently never reach the Worker.
+  let secrets: SecretsDeclaration | null = null;
+  if (extras.secretsDir) {
+    const decl = DECLARATION_FILES.map((f) => join(root, SECRETS_DIR, f)).find((f) => existsSync(f));
+    const values = readSecretsValues(join(root, SECRETS_DIR));
+    if (!decl && values && Object.keys(values).length) throw new Error(`voidbase: ${SECRETS_DIR}/${VALUES_FILE} holds ${Object.keys(values).join(", ")} but ${SECRETS_DIR}/main.ts does not exist to declare them:\n  export default defineSecrets({ ${Object.keys(values).map((k) => `${k}: string().secret()`).join(", ")} })`);
+    if (decl) {
+      secrets = parseSecretsDeclaration(readFileSync(decl, "utf8"), relative(root, decl));
+      const undeclared = Object.keys(values ?? {}).filter((k) => !secrets!.names.includes(k));
+      if (undeclared.length) throw new Error(`voidbase: ${SECRETS_DIR}/${VALUES_FILE} holds ${undeclared.join(", ")}, which ${relative(root, decl)} does not declare. Add them to defineSecrets({...}) or remove them: an undeclared value never reaches the Worker.`);
+    }
+  }
+
+  const collisions = routes.filter((r) => RESERVED_PREFIXES.some((p) => r.url === p || r.url.startsWith(p + "/"))).map((r) => r.url);
+  // "static" means nothing has to run: no Void server code and no voidbase extensions of the app's own
+  const mode = routes.length || middleware.length || hooks.length || crons.length || queues.length ? "server" : "static";
+  return { root, mode, routes, middleware, hooks, crons, queues, migrations, secrets, extras, unsupported, collisions };
+}
+
+/** literal segments beat params beat wildcards, longer paths beat shorter (the hook router scores the same way) */
+function score(path: string): number {
+  const segs = path.split("/").filter(Boolean);
+  return (path.includes("*") ? 0 : 1000) + segs.filter((s) => !s.startsWith(":") && s !== "*").length * 10 + segs.length;
+}
+
+/** cheap source grep for a bare-specifier import, used only to report what the adapter cannot carry */
+function grepImports(root: string, specifier: string): boolean {
+  const needle = new RegExp(`from\\s+["']${specifier.replace("/", "\\/")}["']`);
+  for (const dir of ["routes", "middleware", "crons", "queues", "src", "db"]) {
+    for (const file of walk(join(root, dir))) {
+      if (needle.test(readFileSync(join(root, dir, file), "utf8"))) return true;
+    }
+  }
+  return false;
+}

package/src/cloud/rest.ts

@@ -258,8 +258,16 @@ export async function destroyInstance(cf: CfApi, o: { account: string; name: str
   const log = o.log ?? (() => undefined); const res = instanceResources(o.name); const out: DestroyResult = { name: o.name, deleted: [], skipped: [], errors: [] };
   const attempt = async (label: string, fn: () => Promise<boolean>) => { try { (await fn()) ? out.deleted.push(label) : out.skipped.push(label); log(`${label}: ${out.deleted.includes(label) ? "deleted" : "not found"}`); } catch (e) { out.errors.push(`${label}: ${e instanceof Error ? e.message : e}`); log(`${label}: ${e instanceof Error ? e.message : e}`); } };
   await attempt(`custom domains of ${o.name}`, async () => (await detachCustomDomains(cf, o.account, o.name)).length > 0);
-  // the script first so nothing keeps serving with bindings that are about to vanish
-  await attempt(`worker ${o.name}`, async () => { const r = await cf.raw("DELETE", `/accounts/${o.account}/workers/scripts/${o.name}?force=true`); await r.text(); if (r.status === 404) return false; if (!r.ok) throw new Error(`HTTP ${r.status}`); return true; });
+  // Cloudflare refuses to delete a Worker that consumes a queue (10064) and a queue a Worker still binds (11005):
+  // the consumer goes first, then the script (so nothing keeps serving with bindings about to vanish), then the queue
+  await attempt(`queue consumer of ${o.name}`, async () => {
+    const q = await findQueue(cf, o.account, res.queue); if (!q) return false;
+    const consumers = await cf.json<{ consumer_id?: string; id?: string; script?: string; script_name?: string }[]>("GET", `/accounts/${o.account}/queues/${q.id}/consumers`);
+    let removed = false;
+    for (const c of consumers.result ?? []) { if ((c.script ?? c.script_name) !== o.name) continue; await cf.json("DELETE", `/accounts/${o.account}/queues/${q.id}/consumers/${c.consumer_id ?? c.id}`); removed = true; }
+    return removed;
+  });
+  await attempt(`worker ${o.name}`, async () => { const r = await cf.raw("DELETE", `/accounts/${o.account}/workers/scripts/${o.name}?force=true`); const body = await r.text(); if (r.status === 404) return false; if (!r.ok) throw new Error(`HTTP ${r.status} ${body.slice(0, 200)}`); return true; });
   await attempt(`queue ${res.queue}`, async () => { const q = await findQueue(cf, o.account, res.queue); if (!q) return false; await cf.json("DELETE", `/accounts/${o.account}/queues/${q.id}`); return true; });
   await attempt(`D1 ${res.db}`, async () => { const d = await findD1(cf, o.account, res.db); if (!d) return false; await cf.json("DELETE", `/accounts/${o.account}/d1/database/${d.uuid}`); return true; });
   await attempt(`R2 ${res.bucket}`, async () => {