@voidbase-cloud/voidbase 0.2.1 → 0.3.0

package/src/adapter/codegen.ts

@@ -0,0 +1,269 @@
+// Turns the manifest into a whole voidbase app under `.voidbase/`: PocketBase's minimal layout (main.ts,
+// package.json, pb_hooks/, pb_migrations/, pb_public/, pb_data/) plus the generated glue that imports the Void
+// app's own modules. The project root stays a plain Void app and `.voidbase/` is git-ignored build output.
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { VoidManifest } from "./scan";
+import type { SecretsDeclaration } from "../node/secrets";
+
+const BANNER = "// Generated by voidbase's Void adapter. Do not edit: `vite build` (or `voidbase adapt`) rewrites it.";
+/** the import specifier the generated code uses for the adapter runtime; overridable so this repo can test itself */
+export const ADAPTER_PACKAGE = "@voidbase-cloud/voidbase";
+
+/** from inside .voidbase/, the app's own files are one directory up */
+const importPath = (file: string) => "../" + file.replace(/\.(m?[tj]sx?)$/, "");
+const ident = (prefix: string, i: number) => `${prefix}${i}`;
+
+export interface GenerateOptions {
+  /** package name the generated files import voidbase from */
+  pkg?: string;
+}
+
+/** The bundle entry: imports the app's own modules and hands them to the hook runtime. Bundled into pb_hooks. */
+export function generateServerModule(m: VoidManifest, opts: GenerateOptions = {}): string {
+  const pkg = opts.pkg ?? ADAPTER_PACKAGE;
+  const lines: string[] = [BANNER, "//", "// The project's routes, middleware, vb_hooks, crons and queues, as one module for the generated pb_hooks bundle.", ""];
+  lines.push(`import { mountVoidApp } from "${pkg}/adapter";`);
+  m.routes.forEach((r, i) => lines.push(`import * as ${ident("route", i)} from "${importPath(r.file)}";`));
+  m.middleware.forEach((x, i) => lines.push(`import ${ident("middleware", i)} from "${importPath(x.file)}";`));
+  m.hooks.forEach((x, i) => lines.push(`import ${ident("hook", i)} from "${importPath(x.file)}";`));
+  m.crons.forEach((x, i) => lines.push(`import * as ${ident("cron", i)} from "${importPath(x.file)}";`));
+  m.queues.forEach((x, i) => lines.push(`import ${ident("queue", i)} from "${importPath(x.file)}";`));
+  lines.push("", "export function register(): void {", "  mountVoidApp({");
+
+  lines.push("    routes: [");
+  m.routes.forEach((r, i) => {
+    const splat = r.splat ? `, splat: ${JSON.stringify(r.splat)}` : "";
+    lines.push(`      { url: ${JSON.stringify(r.url)}, hookPath: ${JSON.stringify(r.hookPath)}, methods: ${JSON.stringify(r.methods)}, params: ${JSON.stringify(r.params)}${splat}, mod: ${ident("route", i)} },`);
+  });
+  lines.push("    ],");
+
+  lines.push("    hooks: [");
+  m.hooks.forEach((x, i) => lines.push(`      { hook: ${JSON.stringify(x.hook)}, handler: ${ident("hook", i)} },`));
+  lines.push("    ],");
+
+  lines.push(`    middleware: [${m.middleware.map((_, i) => ident("middleware", i)).join(", ")}],`);
+
+  lines.push("    crons: [");
+  m.crons.forEach((c, i) => lines.push(`      { name: ${JSON.stringify(c.name)}, expr: ${ident("cron", i)}.cron, handler: ${ident("cron", i)}.default },`));
+  lines.push("    ],");
+
+  lines.push("    queues: [");
+  m.queues.forEach((q, i) => lines.push(`      { name: ${JSON.stringify(q.name)}, binding: ${JSON.stringify(q.binding)}, consumer: ${ident("queue", i)} },`));
+  lines.push("    ],");
+
+  lines.push("  });", "}", "");
+  return lines.join("\n");
+}
+
+/** The pb_hooks file that registers the bundle: the one place the hook globals are in scope. */
+export function generateHookWrapper(): string {
+  return `${BANNER}
+// The project's routes, middleware, vb_hooks, crons and queues. The code is in void-app.js beside this file, bundled
+// because a hook cannot import from npm; this is where the hook globals it needs are in scope.
+//
+// \`__g\` is the object every hook file is handed its globals from: $app, $apis, routerAdd, routerUse, cronAdd, the
+// error classes and every on* event registrar. Publishing it is what makes \`pb\` work inside the bundle, and it is
+// published *before* the bundle is required so a module can register an event hook while it is initialising.
+globalThis.__voidbaseHooks = __g;
+
+require(\`\${__hooks}/void-app.js\`).register();
+`;
+}
+
+/** The generated app's entry: the app's own voidbase extensions, and a Bun runner. */
+export function generateMainEntry(m: VoidManifest, opts: GenerateOptions = {}): string {
+  const pkg = opts.pkg ?? ADAPTER_PACKAGE;
+  const lines = [
+    BANNER,
+    "//",
+    "// The voidbase app this Void project builds into: `bun .voidbase/main.ts` runs it, `voidbase deploy` from this",
+    "// directory ships it. Edit the project, not this file.",
+    "//",
+    "// The whole app -- routes/, middleware/, crons/ and queues/ -- is compiled into pb_hooks, so nothing but the",
+    "// runner is left here.",
+    `import type { VoidbaseApp } from "${pkg}";`,
+  ];
+  lines.push("", "export function register(_app: VoidbaseApp) {");
+  lines.push("  // nothing to register here: routes/, middleware/, crons/ and queues/ are the app's server code, and");
+  lines.push("  // they are compiled into pb_hooks. Everything under src/ reaches PocketBase through them.");
+  lines.push("}", "");
+  lines.push(`if (import.meta.main) {
+  // the Bun runtime, imported dynamically (and hidden from the bundler) because \`voidbase deploy\` composes this
+  // file into the Worker for register() only, and the runtime entry pulls in bun:sqlite and the filesystem shims
+  const runtime = "${pkg}";
+  const { voidbase, parseServeArgs } = (await import(/* @vite-ignore */ runtime)) as typeof import("${pkg}");
+  // this app's directories sit next to this file, so it runs the same from any working directory
+  const flags = parseServeArgs(process.argv.slice(2).filter((a) => a !== "serve"));
+  for (const key of Object.keys(flags) as (keyof typeof flags)[]) if (flags[key] === undefined) delete flags[key];
+  const app = await voidbase({
+    dir: \`\${import.meta.dir}/pb_data\`,
+    hooksDir: process.env.VOIDBASE_HOOKS_DIR ?? \`\${import.meta.dir}/pb_hooks\`,
+    migrationsDir: process.env.VOIDBASE_MIGRATIONS_DIR ?? \`\${import.meta.dir}/pb_migrations\`,
+    publicDir: \`\${import.meta.dir}/pb_public\`,
+    ...flags,
+  });
+  register(app);
+  await app.start();
+}
+`);
+  return lines.join("\n");
+}
+
+/** The generated app's package.json: enough for voidbase deploy to read the dependency spec and for Bun to run it. */
+export function generatePackageJson(m: VoidManifest, opts: GenerateOptions = {}): string {
+  const pkg = opts.pkg ?? ADAPTER_PACKAGE;
+  let spec = "latest";
+  try {
+    const parent = JSON.parse(readFileSync(join(m.root, "package.json"), "utf8")) as { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    spec = parent.dependencies?.[pkg] ?? parent.devDependencies?.[pkg] ?? spec;
+    return JSON.stringify({ name: `${parent.name ?? "app"}-voidbase`, private: true, type: "module", main: "main.ts", dependencies: { [pkg]: spec } }, null, 2) + "\n";
+  } catch {
+    return JSON.stringify({ name: "app-voidbase", private: true, type: "module", main: "main.ts", dependencies: { [pkg]: spec } }, null, 2) + "\n";
+  }
+}
+
+/** Drizzle separates statements with its own marker; without it fall back to semicolons at end of line. */
+export function splitSql(sql: string): string[] {
+  const source = sql.includes("--> statement-breakpoint") ? sql.split("--> statement-breakpoint") : sql.split(/;\s*$/m);
+  return source.map((s) => s.replace(/^\s*--.*$/gm, "").trim().replace(/;$/, "")).filter(Boolean);
+}
+
+/** A Drizzle .sql migration as a PocketBase-style migration, so both runtimes apply it through the same runner. */
+export function generateMigration(name: string, sql: string): string {
+  const statements = splitSql(sql);
+  return `${BANNER}
+// Generated from db/migrations/${name}.sql (Drizzle). voidbase records it in _pbMigrations like any other migration.
+migrate(async (app) => {
+${statements.map((s) => `  await app.execSQL(${JSON.stringify(s)});`).join("\n")}
+}, async (_app) => {
+  // Drizzle migrations carry no down step; roll back with a new migration.
+});
+`;
+}
+
+// Void's codegen maps void/db and void/queues to declaration files in .void/ (schema-aware types for tsc). Bun
+// honours tsconfig paths at runtime too, so under voidbase those imports would resolve to a .d.ts and export
+// nothing. These shims take the values from the published runtime and the types from Void's declarations, and the
+// generated .voidbase/tsconfig.json points the two mappings at them, so both tsc and Bun get what they need.
+const DB_REEXPORTS = "and, asc, avg, between, count, createDb, desc, eq, exists, gt, gte, ilike, inArray, isNotNull, isNull, like, lt, lte, max, min, ne, not, notBetween, notExists, notInArray, notLike, or, sql, sum";
+
+export function generateDbShim(): string {
+  // void/_db is the same runtime module under a specifier the path mapping does not cover, so the shim can import
+  // it without importing itself; the schema-aware types still come from Void's own declaration.
+  return `${BANNER}
+// void/db for a voidbase app: Drizzle over voidbase's D1 binding, typed by .void/db.d.ts.
+import type * as Typed from "../.void/db";
+import { db as runtimeDb } from "void/_db";
+
+export { ${DB_REEXPORTS} } from "void/_db";
+export const db: typeof Typed.db = runtimeDb as never;
+`;
+}
+
+export function generateQueuesShim(): string {
+  // Void has no unmapped alias for the queue producers, so the shim is the same one-line proxy Void ships: a
+  // binding lookup per queue name. The adapter puts those bindings on the env (src/adapter/runtime.ts).
+  return `${BANNER}
+// void/queues for a voidbase app: the producers the adapter overlays on the env, typed by .void/queues.d.ts.
+import { requireRuntimeBinding } from "void/_env";
+import type * as Typed from "../.void/queues";
+
+export const queues: typeof Typed.queues = new Proxy({}, {
+  get: (_target, name: string) => requireRuntimeBinding(\`QUEUE_\${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}\`),
+}) as never;
+`;
+}
+
+/** Void's tsconfig fragment with the two runtime-breaking mappings repointed at the shims. */
+export function generateTsconfig(root: string): string | null {
+  const voidTs = join(root, ".void", "tsconfig.json");
+  if (!existsSync(voidTs)) return null;
+  const base = JSON.parse(readFileSync(voidTs, "utf8")) as { compilerOptions?: { paths?: Record<string, string[]> } };
+  const paths: Record<string, string[]> = {};
+  for (const [key, targets] of Object.entries(base.compilerOptions?.paths ?? {})) {
+    // .void and .voidbase sit at the same depth, so a target of the base config is rewritten once
+    paths[key] = targets.map((t) => (t.startsWith("./") ? `../.void/${t.slice(2)}` : t));
+  }
+  if (paths["void/db"]) paths["void/db"] = ["./shim-db.ts"];
+  if (paths["void/queues"]) paths["void/queues"] = ["./shim-queues.ts"];
+  return JSON.stringify({ extends: "../.void/tsconfig.json", compilerOptions: { paths } }, null, 2) + "\n";
+}
+
+export interface WriteResult { written: string[]; removed: string[] }
+
+const OUT = ".voidbase";
+
+/** whether anything under Void's server conventions has to run */
+export const hasServerCode = (m: VoidManifest) => !!(m.routes.length || m.middleware.length || m.crons.length || m.queues.length);
+
+/** Writes the whole generated app under `<root>/.voidbase`. Everything in there is build output. */
+/** pb_secrets/main.pb.js: what vb_secrets/main.ts declared, as the declaration `voidbase deploy` and `voidbase serve` read. */
+export function generateSecretsDeclaration(d: SecretsDeclaration): string {
+  const lines = [BANNER, "//", `// The secrets the app declares in ${d.file}. Read by voidbase serve and voidbase deploy, never run; the values`, "// live in secrets.json beside this file (git-ignored) and, once deployed, as the Worker's secrets.", "secrets({"];
+  for (const n of d.names) lines.push(`  ${n}: ${JSON.stringify(d.descriptions[n] ?? "")},`);
+  lines.push("});", "");
+  return lines.join("\n");
+}
+
+export function writeVoidbaseApp(m: VoidManifest, opts: GenerateOptions & { migrations?: boolean } = {}): WriteResult {
+  const written: string[] = [];
+  const removed: string[] = [];
+  const put = (rel: string, body: string) => {
+    const full = join(m.root, OUT, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    if (!existsSync(full) || readFileSync(full, "utf8") !== body) writeFileSync(full, body);
+    written.push(`${OUT}/${rel}`);
+  };
+  const drop = (rel: string) => {
+    const full = join(m.root, OUT, rel);
+    if (!existsSync(full)) return;
+    rmSync(full, { recursive: true, force: true });
+    removed.push(`${OUT}/${rel}`);
+  };
+
+  // PocketBase's minimal layout, generated whole: https://pocketbase.io/docs/going-to-production/#minimal-setup
+  put("main.ts", generateMainEntry(m, opts));
+  put("package.json", generatePackageJson(m, opts));
+  put(".gitignore", "# the generated voidbase app is build output; this is what it makes at runtime\npb_data/\n# the values of the secrets vb_secrets/main.ts declares (copied from vb_secrets/secrets.json)\npb_secrets/secrets.json\n");
+
+  // the tsconfig fragment the project's own tsconfig extends, and the shims it points at
+  const tsconfig = generateTsconfig(m.root);
+  if (tsconfig) {
+    put("tsconfig.json", tsconfig);
+    if (/"void\/db"/.test(tsconfig)) put("shim-db.ts", generateDbShim());
+    if (/"void\/queues"/.test(tsconfig)) put("shim-queues.ts", generateQueuesShim());
+  }
+
+  // routes/, middleware/, crons/ and queues/ become a pb_hooks bundle; this is the module the bundler builds
+  drop("pb_hooks");
+  if (hasServerCode(m)) put("void-entry.ts", generateServerModule(m, opts));
+  else drop("void-entry.ts");
+
+  // pb_migrations: the project's vb_migrations/, plus one per Drizzle migration
+  const migrationsOut = join(m.root, OUT, "pb_migrations");
+  drop("pb_migrations");
+  if (m.extras.migrationsDir) {
+    cpSync(join(m.root, m.extras.migrationsDir), migrationsOut, { recursive: true });
+    written.push(`${OUT}/pb_migrations`);
+    removed.pop();
+  }
+  if (opts.migrations !== false && m.migrations.length) {
+    mkdirSync(migrationsOut, { recursive: true });
+    for (const mig of m.migrations) {
+      const sql = readFileSync(resolve(m.root, mig.file), "utf8");
+      put(`pb_migrations/${mig.name}.void.js`, generateMigration(mig.name, sql));
+    }
+  }
+  if (existsSync(migrationsOut) && !readdirSync(migrationsOut).length) rmSync(migrationsOut, { recursive: true, force: true });
+
+  // pb_secrets: the declaration vb_secrets/main.ts makes, in the shape `voidbase deploy` reads, and the values beside it
+  drop("pb_secrets");
+  if (m.secrets) {
+    put("pb_secrets/main.pb.js", generateSecretsDeclaration(m.secrets));
+    const values = join(m.root, m.extras.secretsDir!, "secrets.json");
+    if (existsSync(values)) { cpSync(values, join(m.root, OUT, "pb_secrets/secrets.json")); written.push(`${OUT}/pb_secrets/secrets.json`); }
+  }
+
+  return { written, removed };
+}

package/src/adapter/index.ts

@@ -0,0 +1,6 @@
+// Node side of the Void adapter: the Vite plugin, the one-shot `adapt()` and the pieces they are made of.
+// The runtime half (`mountVoidApp`) is a separate entry, "@voidbase-cloud/voidbase/adapter", because generated
+// app code imports it and must stay free of node:fs so it bundles into a Worker.
+export { adapt, voidbaseAdapter, type AdaptResult, type AdapterOptions } from "./plugin";
+export { generateMainEntry, generateMigration, generateServerModule, splitSql, writeVoidbaseApp, type GenerateOptions, type WriteResult } from "./codegen";
+export { exportedNames, routeUrl, scanVoidApp, type ScanOptions, type VoidManifest, type VoidMigration, type VoidModule, type VoidQueue, type VoidRoute } from "./scan";

package/src/adapter/plugin.ts

@@ -0,0 +1,117 @@
+// The Vite plugin a Void app adds next to voidPlugin(): it makes `vite build` produce a voidbase app.
+//
+//   import { voidPlugin } from "void";
+//   import { voidbaseAdapter } from "@voidbase-cloud/voidbase/adapter/plugin";
+//   export default defineConfig({ plugins: [voidPlugin(), voidbaseAdapter()] });
+//
+// The whole voidbase app is generated under `.voidbase/`, in PocketBase's layout: the client build lands in
+// `.voidbase/pb_public` (served at `/`), and the server code (routes/, middleware/, vb_hooks/, crons/, queues/)
+// is bundled into `.voidbase/pb_hooks/`. The whole `.voidbase/` directory is build output: delete it and the next
+// build makes it again.
+// The project root stays a plain Void app. Void's own dist/ssr worker is left alone: voidbase composes the
+// generated main.ts into its own Worker on deploy, so the app's server code is bundled there instead.
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { bundleHookApp } from "./bundle";
+import { generateHookWrapper, hasServerCode, writeVoidbaseApp, type GenerateOptions } from "./codegen";
+import { scanVoidApp, type VoidManifest } from "./scan";
+
+export interface AdapterOptions extends GenerateOptions {
+  /** where the built site goes inside the generated app; voidbase serves it at `/` */
+  publicDir?: string;
+  /** the client build to copy from; defaults to <outDir>/client, then dist/client */
+  clientDir?: string;
+  /** turn db/migrations/*.sql into pb_migrations/*.void.js (default true) */
+  migrations?: boolean;
+  /** log what was produced (default true) */
+  quiet?: boolean;
+}
+
+export interface AdaptResult { manifest: VoidManifest; written: string[]; copied: number; bundleBytes: number }
+
+/** Runs the whole conversion once. Exported so `voidbase adapt` and the tests do not need Vite. */
+export async function adapt(root: string, opts: AdapterOptions & { clientDir?: string } = {}): Promise<AdaptResult> {
+  const manifest = scanVoidApp({ root, dev: false });
+  const { written } = writeVoidbaseApp(manifest, { pkg: opts.pkg, migrations: opts.migrations });
+
+  // routes/, middleware/, vb_hooks/, crons/ and queues/ become one bundled hook: a hook cannot import from npm, and Void's
+  // handlers do (see src/adapter/bundle.ts)
+  let bundleBytes = 0;
+  if (hasServerCode(manifest)) {
+    const hooks = join(root, ".voidbase", "pb_hooks");
+    mkdirSync(hooks, { recursive: true });
+    const { code, bytes } = await bundleHookApp(join(root, ".voidbase", "void-entry.ts"), root);
+    writeFileSync(join(hooks, "void-app.js"), code);
+    writeFileSync(join(hooks, "void-app.pb.js"), generateHookWrapper());
+    written.push(".voidbase/pb_hooks/void-app.js", ".voidbase/pb_hooks/void-app.pb.js");
+    bundleBytes = bytes;
+  }
+
+  const publicDir = resolve(root, opts.publicDir ?? ".voidbase/pb_public");
+  const client = opts.clientDir ? resolve(root, opts.clientDir) : firstExisting([join(root, "dist", "client"), join(root, "public")]);
+  const copied = client ? syncPublic(client, publicDir) : 0;
+  return { manifest, written, copied, bundleBytes };
+}
+
+const firstExisting = (paths: string[]) => paths.find((p) => existsSync(p) && statSync(p).isDirectory());
+
+/** Replaces pb_public with the build, keeping `_` (the admin panel) and dotfiles, and giving the asset layer a 404. */
+function syncPublic(from: string, to: string): number {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(to)) {
+    if (entry === "_" || entry.startsWith(".")) continue;
+    rmSync(join(to, entry), { recursive: true, force: true });
+  }
+  let copied = 0;
+  for (const entry of readdirSync(from)) {
+    if (entry === "_") continue; // that path belongs to the admin panel
+    cpSync(join(from, entry), join(to, entry), { recursive: true });
+    copied++;
+  }
+  // Cloudflare answers an unmatched path with 404.html (void.json routing.notFound "404-page"); on Bun voidbase
+  // falls back to index.html. Copying one to the other keeps a deep link behaving the same on both.
+  const index = join(to, "index.html");
+  if (existsSync(index) && !existsSync(join(to, "404.html"))) cpSync(index, join(to, "404.html"));
+  return copied;
+}
+
+export function voidbaseAdapter(options: AdapterOptions = {}) {
+  let root = process.cwd();
+  let clientOut: string | undefined;
+  let hasClient = false;
+  const log = (msg: string) => { if (!options.quiet) console.log(`voidbase: ${msg}`); };
+  // Rolldown prints only a plugin error's first line, and the adapter's build errors say what to change on the
+  // lines after it. Print the whole thing before it is rethrown.
+  const report = async <T>(work: () => T | Promise<T>): Promise<T> => {
+    try { return await work(); } catch (err) { if (err instanceof Error && err.message.includes("\n")) console.error(err.message); throw err; }
+  };
+
+  return {
+    name: "voidbase-adapter",
+    // after voidPlugin, so the manifest sees whatever it generated into .void/
+    enforce: "post" as const,
+    configResolved(config: { root: string; build?: { outDir?: string }; environments?: Record<string, { build?: { outDir?: string } }> }) {
+      root = config.root ?? root;
+      const fromEnv = config.environments?.client?.build?.outDir;
+      hasClient = !!config.environments?.client;
+      clientOut = fromEnv ?? config.build?.outDir;
+    },
+    async buildStart() {
+      // keep the glue in step with the files while developing, so `voidbase serve --entry main.ts` sees new routes
+      const manifest = await report(() => scanVoidApp({ root, dev: process.env.NODE_ENV !== "production" }));
+      writeVoidbaseApp(manifest, { pkg: options.pkg, migrations: options.migrations });
+    },
+    // fires once per built environment; the work is idempotent and the client builds last, so report only then
+    async closeBundle(this: { environment?: { name?: string } }) {
+      const clientDir = options.clientDir ?? (clientOut && existsSync(resolve(root, clientOut)) ? clientOut : undefined);
+      const { manifest, copied, bundleBytes } = await report(() => adapt(root, { ...options, clientDir }));
+      const counts = `${manifest.routes.length} route(s), ${manifest.middleware.length} middleware, ${manifest.hooks.length} hook(s), ${manifest.crons.length} cron(s), ${manifest.queues.length} queue(s), ${manifest.migrations.length} migration(s)${manifest.secrets ? `, ${manifest.secrets.names.length} secret(s)` : ""}${bundleBytes ? ` -> pb_hooks/void-app.js (${Math.round(bundleBytes / 1024)} kB)` : ""}`;
+      if (!hasClient || this.environment?.name === "client") {
+          log(`${manifest.mode === "static" ? "static site" : counts}; ${copied} entr(ies) into ${options.publicDir ?? ".voidbase/pb_public"}`);
+        for (const u of manifest.unsupported) console.warn(`voidbase: ${u.what} is not carried over — ${u.why}`);
+        for (const c of manifest.collisions) console.warn(`voidbase: ${c} is served by voidbase itself, so the app route never runs — move it off that path`);
+      }
+      writeFileSync(join(root, ".voidbase", "manifest.json"), JSON.stringify({ ...manifest, root: undefined }, null, 2) + "\n");
+    },
+  };
+}