@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/fullstack/apps/api/src/health/readiness.service.ts

@@ -1,30 +1,104 @@
 export type ReadinessStatus = "up" | "down";
 export type ReadinessCheck = () => Promise<void>;
+export type ReadinessResults = Record<string, ReadinessStatus>;
+
+export const DEFAULT_READINESS_CHECK_TIMEOUT_MS = 800;
+export const DEFAULT_READINESS_CACHE_MS = 2_000;
+
+/** The core database check. The health endpoint reports it as `db`, apart from module checks. */
+export const DATABASE_READINESS_CHECK = "database";
+
+export interface ReadinessOptions {
+  /** Longest one check may run before it is reported down. */
+  timeoutMs?: number;
+  /** How long a finished evaluation is reused. `0` evaluates on every run. */
+  cacheMs?: number;
+  /** Receives the reason for each check that is down, once per evaluation. */
+  onCheckFailure?: (name: string, reason: string) => void;
+}
+
+class ReadinessTimeoutError extends Error {
+  constructor(name: string, timeoutMs: number) {
+    super(`Readiness check "${name}" timed out after ${timeoutMs} ms`);
+    this.name = "ReadinessTimeoutError";
+  }
+}
 
 export class ReadinessService {
   private readonly checks = new Map<string, ReadinessCheck>();
+  private readonly timeoutMs: number;
+  private readonly cacheMs: number;
+  private readonly onCheckFailure: ((name: string, reason: string) => void) | undefined;
+  // Bumped whenever the registered checks change, so an evaluation that started
+  // earlier is neither shared nor cached afterwards.
+  private generation = 0;
+  private inFlight?: Promise<ReadinessResults>;
+  private cached?: { results: ReadinessResults; expiresAt: number };
+
+  constructor(options: ReadinessOptions = {}) {
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_READINESS_CHECK_TIMEOUT_MS;
+    this.cacheMs = options.cacheMs ?? DEFAULT_READINESS_CACHE_MS;
+    this.onCheckFailure = options.onCheckFailure;
+  }
 
   register(name: string, check: ReadinessCheck): () => void {
     if (this.checks.has(name)) {
       throw new Error(`Readiness check "${name}" is already registered`);
     }
     this.checks.set(name, check);
+    this.invalidate();
     return () => {
       this.checks.delete(name);
+      this.invalidate();
     };
   }
 
-  async run(): Promise<Record<string, ReadinessStatus>> {
-    const results = await Promise.all(
-      [...this.checks].map(async ([name, check]): Promise<[string, ReadinessStatus]> => {
-        try {
-          await check();
-          return [name, "up"];
-        } catch {
-          return [name, "down"];
-        }
-      }),
-    );
-    return Object.fromEntries(results);
+  /**
+   * Runs every check in parallel, each bounded by the timeout. Concurrent callers
+   * share one evaluation, and a finished one is reused for the cache window.
+   */
+  async run(): Promise<ReadinessResults> {
+    if (this.cached && Date.now() < this.cached.expiresAt) return { ...this.cached.results };
+    this.inFlight ??= this.evaluate(this.generation);
+    return { ...(await this.inFlight) };
+  }
+
+  private invalidate(): void {
+    this.generation += 1;
+    this.inFlight = undefined;
+    this.cached = undefined;
+  }
+
+  private async evaluate(generation: number): Promise<ReadinessResults> {
+    try {
+      const entries = await Promise.all(
+        [...this.checks].map(
+          async ([name, check]): Promise<[string, ReadinessStatus]> => [name, await this.probe(name, check)],
+        ),
+      );
+      const results: ReadinessResults = Object.fromEntries(entries);
+      if (generation === this.generation && this.cacheMs > 0) {
+        this.cached = { results, expiresAt: Date.now() + this.cacheMs };
+      }
+      return results;
+    } finally {
+      if (generation === this.generation) this.inFlight = undefined;
+    }
+  }
+
+  private async probe(name: string, check: ReadinessCheck): Promise<ReadinessStatus> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new ReadinessTimeoutError(name, this.timeoutMs)), this.timeoutMs);
+    });
+    try {
+      await Promise.race([check(), timeout]);
+      return "up";
+    } catch (error) {
+      this.onCheckFailure?.(name, error instanceof Error ? error.message : String(error));
+      return "down";
+    } finally {
+      clearTimeout(timer);
+    }
   }
 }

package/dist/templates/fullstack/apps/web/package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.8.0",
+    "@podosoft/podokit-api-client": "^0.8.5",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.test.ts

@@ -1,5 +1,8 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { gzipSync } from "node:zlib";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { proxyRequest, resolveClientIp } from "./backend-proxy";
+import { proxyRequest, rawSubpath, resolveClientIp } from "./backend-proxy";
 
 describe("backend proxy client address handling", () => {
   afterEach(() => {
@@ -77,6 +80,23 @@ describe("backend proxy client address handling", () => {
     expect(upstreamHeaders?.get("user-agent")).toBe(agent);
   });
 
+  it("aborts the upstream request when the client disconnects", async () => {
+    let upstreamSignal: AbortSignal | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamSignal = init?.signal ?? undefined;
+      return new Response(null, { status: 204 });
+    });
+
+    const client = new AbortController();
+    const request = new Request("http://app.localhost/api/events", { signal: client.signal });
+    await proxyRequest(request, "http://api:5002/events");
+
+    expect(upstreamSignal).toBeDefined();
+    expect(upstreamSignal?.aborted).toBe(false);
+    client.abort();
+    expect(upstreamSignal?.aborted).toBe(true);
+  });
+
   it("relays rate-limit response headers to browser clients", async () => {
     vi.stubGlobal("fetch", async () => new Response(
       JSON.stringify({ success: false }),
@@ -101,4 +121,171 @@ describe("backend proxy client address handling", () => {
     expect(response.headers.get("ratelimit-limit")).toBe("300");
     expect(response.headers.get("ratelimit-remaining")).toBe("0");
   });
+
+  it("relays the next-page cursor of a cursor-paged list", async () => {
+    vi.stubGlobal("fetch", async () => new Response("[]", {
+      headers: { "content-type": "application/json", "x-next-cursor": "WyIyMDI2Il0" },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/audit-logs?limit=15"),
+      "http://api:5002/audit-logs?limit=15",
+    );
+
+    expect(response.headers.get("x-next-cursor")).toBe("WyIyMDI2Il0");
+  });
+
+  it("relays cache validator and download headers", async () => {
+    vi.stubGlobal("fetch", async () => new Response("report", {
+      headers: {
+        "content-type": "text/csv",
+        etag: '"report-v3"',
+        "last-modified": "Wed, 14 Oct 2026 08:00:00 GMT",
+        "content-disposition": 'attachment; filename="report.csv"',
+        vary: "accept-encoding, cookie",
+        "x-content-type-options": "nosniff",
+      },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/reports/3"),
+      "http://api:5002/reports/3",
+    );
+
+    expect(response.headers.get("etag")).toBe('"report-v3"');
+    expect(response.headers.get("last-modified")).toBe("Wed, 14 Oct 2026 08:00:00 GMT");
+    expect(response.headers.get("content-disposition")).toBe('attachment; filename="report.csv"');
+    expect(response.headers.get("vary")).toBe("accept-encoding, cookie");
+    expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+  });
+
+  it("relays content-length for an uncompressed upstream body", async () => {
+    vi.stubGlobal("fetch", async () => new Response("0123456789", {
+      headers: { "content-length": "10" },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/files/1"),
+      "http://api:5002/files/1",
+    );
+
+    expect(response.headers.get("content-length")).toBe("10");
+    expect(await response.text()).toBe("0123456789");
+  });
+
+  it("drops content-length when the upstream body was compressed", async () => {
+    vi.stubGlobal("fetch", async () => new Response("decoded body", {
+      headers: { "content-encoding": "gzip", "content-length": "4" },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/files/1"),
+      "http://api:5002/files/1",
+    );
+
+    expect(response.headers.get("content-length")).toBeNull();
+    expect(response.headers.get("content-encoding")).toBeNull();
+    expect(await response.text()).toBe("decoded body");
+  });
+
+  it("delivers a gzip-encoded upstream body in full", async () => {
+    const payload = `${"podokit ".repeat(4096)}end`;
+    const compressed = gzipSync(payload);
+    const server = createServer((_request, response) => {
+      response.writeHead(200, {
+        "content-type": "text/plain",
+        "content-encoding": "gzip",
+        "content-length": String(compressed.byteLength),
+      });
+      response.end(compressed);
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    try {
+      const { port } = server.address() as AddressInfo;
+      const response = await proxyRequest(
+        new Request("http://app.localhost/api/export"),
+        `http://127.0.0.1:${String(port)}/export`,
+      );
+
+      expect(response.headers.get("content-length")).toBeNull();
+      expect(await response.text()).toBe(payload);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it("forwards conditional and range request headers", async () => {
+    let upstreamHeaders: Headers | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 204 });
+    });
+
+    const request = new Request("http://app.localhost/api/files/1", {
+      headers: {
+        "if-none-match": '"file-v1"',
+        "if-modified-since": "Wed, 14 Oct 2026 08:00:00 GMT",
+        range: "bytes=0-99",
+        "if-range": '"file-v1"',
+      },
+    });
+    await proxyRequest(request, "http://api:5002/files/1");
+
+    expect(upstreamHeaders?.get("if-none-match")).toBe('"file-v1"');
+    expect(upstreamHeaders?.get("if-modified-since")).toBe("Wed, 14 Oct 2026 08:00:00 GMT");
+    expect(upstreamHeaders?.get("range")).toBe("bytes=0-99");
+    expect(upstreamHeaders?.get("if-range")).toBe('"file-v1"');
+  });
+
+  it("passes a 304 Not Modified response through without a body", async () => {
+    vi.stubGlobal("fetch", async () => new Response(null, {
+      status: 304,
+      headers: { etag: '"file-v1"', "cache-control": "private, no-cache" },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/files/1", {
+        headers: { "if-none-match": '"file-v1"' },
+      }),
+      "http://api:5002/files/1",
+    );
+
+    expect(response.status).toBe(304);
+    expect(response.headers.get("etag")).toBe('"file-v1"');
+    expect(await response.text()).toBe("");
+  });
+
+  it("passes a 206 Partial Content response through with its range", async () => {
+    vi.stubGlobal("fetch", async () => new Response("0123", {
+      status: 206,
+      headers: {
+        "content-range": "bytes 0-3/10",
+        "accept-ranges": "bytes",
+        "content-length": "4",
+      },
+    }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/files/1", { headers: { range: "bytes=0-3" } }),
+      "http://api:5002/files/1",
+    );
+
+    expect(response.status).toBe(206);
+    expect(response.headers.get("content-range")).toBe("bytes 0-3/10");
+    expect(response.headers.get("accept-ranges")).toBe("bytes");
+    expect(response.headers.get("content-length")).toBe("4");
+    expect(await response.text()).toBe("0123");
+  });
+});
+
+describe("backend proxy raw path", () => {
+  it("keeps encoded separators inside a path segment", () => {
+    const url = new URL("http://localhost/api/files/uploads%2Fu1%2Fa%3Fb.png/url?x=1");
+    expect(rawSubpath(url, "/api/")).toBe("files/uploads%2Fu1%2Fa%3Fb.png/url");
+  });
+
+  it("strips only the given prefix", () => {
+    expect(rawSubpath(new URL("http://localhost/api/auth/get-session"), "/api/auth/")).toBe("get-session");
+    expect(rawSubpath(new URL("http://localhost/other"), "/api/")).toBe("/other");
+  });
 });

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -15,16 +15,36 @@ const FORWARDED_HEADERS = [
   "origin",
   "referer",
   "user-agent",
+  "if-none-match",
+  "if-modified-since",
+  "range",
+  "if-range",
 ];
 const RELAYED_RESPONSE_HEADERS = [
   "content-type",
+  "content-disposition",
+  "content-range",
+  "accept-ranges",
   "location",
   "cache-control",
+  "etag",
+  "last-modified",
+  "vary",
+  "x-content-type-options",
+  "content-security-policy",
   "retry-after",
   "ratelimit-limit",
   "ratelimit-remaining",
+  // Cursor-paged lists (such as the audit log) return the next page's cursor here.
+  "x-next-cursor",
 ];
 
+// SvelteKit decodes rest params, so an encoded "%2F" or "%3F" inside a path
+// segment would reach the API as "/" or "?". Forward the raw pathname instead.
+export function rawSubpath(url: URL, prefix: string): string {
+  return url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : url.pathname;
+}
+
 export function backendBaseUrl(): string {
   return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
 }
@@ -71,6 +91,10 @@ export async function proxyRequest(
     // them as text corrupts bytes that are not valid UTF-8 before forwarding.
     body: hasBody ? await request.arrayBuffer() : undefined,
     redirect: "manual",
+    // Abort the upstream request when the browser disconnects. Without this, every
+    // closed EventSource or aborted request keeps its API socket open until Bun's
+    // fetch pool is exhausted and the web process stops serving requests.
+    signal: request.signal,
   });
 
   const responseHeaders = new Headers();
@@ -78,6 +102,12 @@ export async function proxyRequest(
     const value = upstream.headers.get(name);
     if (value) responseHeaders.set(name, value);
   }
+  // Bun's fetch decodes a compressed body but keeps the upstream content-encoding
+  // and compressed content-length, which would truncate the decoded body.
+  const contentLength = upstream.headers.get("content-length");
+  if (contentLength && !upstream.headers.has("content-encoding")) {
+    responseHeaders.set("content-length", contentLength);
+  }
   // Relay Set-Cookie so auth session cookies reach the browser.
   for (const cookie of upstream.headers.getSetCookie()) {
     responseHeaders.append("set-cookie", cookie);

package/dist/templates/fullstack/apps/web/src/routes/api/[...path]/+server.ts

@@ -1,11 +1,11 @@
 import type { RequestHandler } from "@sveltejs/kit";
-import { backendBaseUrl, proxyRequest, resolveClientIp } from "#lib/server/backend-proxy.js";
+import { backendBaseUrl, proxyRequest, rawSubpath, resolveClientIp } from "#lib/server/backend-proxy.js";
 
 // Proxy the app's REST API, stripping the /api prefix (backend routes are at root).
-const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+const handler: RequestHandler = ({ request, url, getClientAddress }) =>
   proxyRequest(
     request,
-    `${backendBaseUrl()}/${params.path}${url.search}`,
+    `${backendBaseUrl()}/${rawSubpath(url, "/api/")}${url.search}`,
     resolveClientIp(getClientAddress),
   );
 

package/dist/templates/fullstack/apps/web/src/routes/api/auth/[...all]/+server.ts

@@ -1,11 +1,11 @@
 import type { RequestHandler } from "@sveltejs/kit";
-import { backendBaseUrl, proxyRequest, resolveClientIp } from "#lib/server/backend-proxy.js";
+import { backendBaseUrl, proxyRequest, rawSubpath, resolveClientIp } from "#lib/server/backend-proxy.js";
 
 // Proxy the better-auth handler, keeping the /api/auth prefix.
-const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+const handler: RequestHandler = ({ request, url, getClientAddress }) =>
   proxyRequest(
     request,
-    `${backendBaseUrl()}/api/auth/${params.all}${url.search}`,
+    `${backendBaseUrl()}/api/auth/${rawSubpath(url, "/api/auth/")}${url.search}`,
     resolveClientIp(getClientAddress),
   );
 

package/dist/templates/fullstack/compose.dev.yaml

@@ -1,8 +1,15 @@
 # Containerized Bun development environment.
+#
+# Every service has a memory limit equal to its swap limit, so a runaway process
+# is OOM-killed inside its container instead of exhausting the host. Override a
+# limit with the matching *_MEM_LIMIT variable from the shell or the project's
+# .env file (not .env.docker), e.g. API_MEM_LIMIT=3g podo dev watch.
 name: {{projectName}}-dev
 
 services:
   traefik:
+    mem_limit: ${TRAEFIK_MEM_LIMIT:-256m}
+    memswap_limit: ${TRAEFIK_MEM_LIMIT:-256m}
     profiles: [podokit-legacy-proxy]
     image: traefik:v3.5
     command:
@@ -19,6 +26,8 @@ services:
     networks: [podokit]
 
   web:
+    mem_limit: ${WEB_MEM_LIMIT:-2g}
+    memswap_limit: ${WEB_MEM_LIMIT:-2g}
     build:
       context: .
       dockerfile: Dockerfile.dev
@@ -42,6 +51,8 @@ services:
         - { action: rebuild, path: ./apps/web/package.json }
 
   api:
+    mem_limit: ${API_MEM_LIMIT:-2g}
+    memswap_limit: ${API_MEM_LIMIT:-2g}
     build:
       context: .
       dockerfile: Dockerfile.dev
@@ -61,6 +72,8 @@ services:
         - { action: rebuild, path: ./apps/api/package.json }
 
   worker:
+    mem_limit: ${WORKER_MEM_LIMIT:-1g}
+    memswap_limit: ${WORKER_MEM_LIMIT:-1g}
     profiles: [queue]
     build:
       context: .
@@ -81,6 +94,8 @@ services:
         - { action: rebuild, path: ./apps/api/package.json }
 
   postgres:
+    mem_limit: ${POSTGRES_MEM_LIMIT:-1g}
+    memswap_limit: ${POSTGRES_MEM_LIMIT:-1g}
     image: postgres:16-alpine
     environment:
       POSTGRES_USER: podokit
@@ -96,11 +111,15 @@ services:
     networks: [podokit]
 
   redis:
+    mem_limit: ${REDIS_MEM_LIMIT:-256m}
+    memswap_limit: ${REDIS_MEM_LIMIT:-256m}
     profiles: [cache]
     image: redis:7-alpine
     networks: [podokit]
 
   minio:
+    mem_limit: ${MINIO_MEM_LIMIT:-512m}
+    memswap_limit: ${MINIO_MEM_LIMIT:-512m}
     profiles: [storage]
     image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
     command: server /data --console-address ":9001"
@@ -112,6 +131,8 @@ services:
     networks: [podokit]
 
   minio-init:
+    mem_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
+    memswap_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     profiles: [storage]
     image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
     depends_on:

package/dist/templates/fullstack/dot-claude/skills/podokit-sveltekit-route/SKILL.md

@@ -19,5 +19,12 @@ description: Use when adding or changing a SvelteKit page/route in apps/web —
    skill, added with the admin-dashboard module).
 5. **i18n**: no hardcoded user-facing strings — add keys to
    `apps/web/src/lib/i18n/messages.ts` for **every** locale.
-6. **Verify**: `{{webRun}} build` (includes `svelte-check`)
+6. **Public pages** (with the admin-dashboard module): every page outside the
+   sign-in flow, `/`, and module pages requires a session and answers 503 while
+   the API is unavailable. Add the prefix of a page anonymous visitors should see
+   (marketing, pricing, legal, `robots.txt`) to `APP_PUBLIC_PATHS` in the
+   app-owned `apps/web/src/lib/server/public-paths.ts`. A prefix covers its
+   subpaths. Give such a page's loader a fallback for when the API is down
+   instead of throwing. Never edit `PUBLIC_PATHS` in the managed `guards.ts`.
+7. **Verify**: `{{webRun}} build` (includes `svelte-check`)
    and add/adjust a Playwright test in `tests/`.

package/dist/templates/fullstack/dot-env.docker

@@ -1,3 +1,6 @@
+# Container environment for compose.dev.yaml. Compose does not interpolate
+# from this file: set container memory limits such as API_MEM_LIMIT=3g in the
+# shell or the project's .env file instead.
 NODE_ENV=development
 PORT=5002
 POSTGRES_HOST=postgres

package/dist/templates/fullstack/dot-env.example

@@ -12,6 +12,20 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 
+# PostgreSQL pools. Each API replica opens up to DB_POOL_MAX connections for
+# queries, plus DB_AUTH_POOL_MAX for the auth module when it is installed. Keep
+# replicas x (DB_POOL_MAX + DB_AUTH_POOL_MAX), plus a few for migrations, below
+# the server's max_connections (100 by default). The timeouts are milliseconds.
+# DB_POOL_MAX=20
+# DB_CONNECT_TIMEOUT_MS=10000
+# DB_IDLE_TIMEOUT_MS=30000
+# DB_AUTH_POOL_MAX=10
+
+# Readiness (GET /health/ready): the longest one dependency check may run, and how
+# long a result is reused across probes (0 checks on every request).
+# READINESS_CHECK_TIMEOUT_MS=800
+# READINESS_CACHE_MS=2000
+
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
 

package/dist/templates/fullstack/infra/k3s/api-deployment.yaml

@@ -24,6 +24,8 @@ spec:
           readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5
+            timeoutSeconds: 2
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 15
+            timeoutSeconds: 2

package/dist/templates/fullstack/tests/playwright.extensions.ts

@@ -1,9 +1,9 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import type { TestConfig } from "@playwright/test";
+import type { PlaywrightTestConfig } from "@playwright/test";
 
-type Projects = NonNullable<TestConfig["projects"]>;
+type Projects = NonNullable<PlaywrightTestConfig["projects"]>;
 
 const requireFromTests = createRequire(__filename);
 

package/dist/templates/modules/admin-dashboard/files/apps/api/scripts/bootstrap-admin.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env bun
 
+import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
+const compiledRuntime = new URL("../dist/bootstrap-admin-runtime.js", import.meta.url);
+const sourceRuntime = new URL("../src/bootstrap-admin-runtime.ts", import.meta.url);
+
 const args = process.argv.slice(2);
 
 function has(flag) {
@@ -130,34 +134,15 @@ async function main() {
   }
 
   const input = resolveBootstrapInput();
-  // Load the auth graph before importing one of its dependencies directly.
-  // Concurrent ESM imports can ask Node to link the same Better Auth submodule
-  // through two graph roots and fail before the command reaches the database.
-  const { auth } = await import("../dist/auth/auth.js");
-  const { pool } = await import("../dist/auth/db.js");
-  const { verifyPassword } = await import("better-auth/crypto");
+  // A production image runs the bundled entry; development runs the source.
+  const useCompiled = process.env.NODE_ENV === "production" && existsSync(compiledRuntime);
+  const runtime = await import((useCompiled ? compiledRuntime : sourceRuntime).href);
+  const { auth, findBootstrapUser, verifyPassword, closeAuthDatabase } = runtime;
 
   try {
     const result = await bootstrapAdmin(
       {
-        findUser: async (email) => {
-          const query = await pool.query(
-            `SELECT u.id,
-                    u.email,
-                    u.role,
-                    u."emailVerified" AS "emailVerified",
-                    u."signupApproved" AS "signupApproved",
-                    a.password AS "passwordHash"
-               FROM "user" AS u
-          LEFT JOIN "account" AS a
-                 ON a."userId" = u.id
-                AND a."providerId" = 'credential'
-              WHERE lower(u.email) = lower($1)
-              LIMIT 1`,
-            [email],
-          );
-          return query.rows[0] ?? null;
-        },
+        findUser: findBootstrapUser,
         createUser: async (user) => auth.api.createUser({ body: user }),
         verifyPassword: async (hash, password) => verifyPassword({ hash, password }),
       },
@@ -174,14 +159,24 @@ async function main() {
       console.log(`Verified existing administrator account ${result.email}.`);
     }
   } finally {
-    await pool.end();
+    await closeAuthDatabase();
+  }
+}
+
+// A refused PostgreSQL connection is an AggregateError with an empty message.
+export function errorMessage(error) {
+  if (!(error instanceof Error)) return String(error);
+  if (error.message) return error.message;
+  if (error instanceof AggregateError && error.errors.length > 0) {
+    return error.errors.map(errorMessage).join("; ");
   }
+  return error.name;
 }
 
 const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
 if (invokedPath === import.meta.url) {
   main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(errorMessage(error));
     process.exitCode = 1;
   });
 }