@podosoft/podokit 1.3.0 → 1.4.0

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

@@ -16,11 +16,18 @@ POSTGRES_DB=podokit
 # 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_QUERY_TIMEOUT_MS bounds how long a query waits for a server that stopped
+# answering; migrations and maintenance commands are not bounded.
 # DB_POOL_MAX=20
 # DB_CONNECT_TIMEOUT_MS=10000
 # DB_IDLE_TIMEOUT_MS=30000
+# DB_QUERY_TIMEOUT_MS=10000
 # DB_AUTH_POOL_MAX=10
 
+# Largest API request body in bytes (Bun's default is 128 MiB). Requests through
+# the web app's /api proxy are also bounded by BODY_SIZE_LIMIT below.
+# API_MAX_REQUEST_BODY_SIZE=134217728
+
 # 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
@@ -44,3 +51,6 @@ REDIS_DB=0
 # REDIS_USERNAME=
 # REDIS_PASSWORD=
 REDIS_TLS=false
+# Longest wait in milliseconds for Redis to answer one command. A command that
+# gets no reply in time fails, and its connection is closed and reopened.
+# REDIS_COMMAND_TIMEOUT_MS=1000

package/dist/templates/fullstack/dot-gitignore

@@ -5,6 +5,7 @@ build/
 .env
 .env.*
 !.env.example
+!.env.docker.example
 .DS_Store
 *.log
 

package/dist/templates/fullstack/dot-podokit/dev.json

@@ -1,5 +1,6 @@
 {
   "schemaVersion": 1,
   "hostname": "{{projectName}}.localhost",
-  "webSocketPaths": []
+  "webSocketPaths": [],
+  "apiPaths": []
 }

package/dist/templates/fullstack/infra/k3s/README.md

@@ -20,4 +20,6 @@ branch tags, and empty tags, and so should you.
 For a hand-managed API WebSocket endpoint, add a `pathType: Exact` Ingress path to
 the API service before the existing `/` web path. Do not route a prefix or the root
 to API. Deployment profiles express the same rule with
-`exposure.webSocketPaths` and validate it before rendering.
+`exposure.webSocketPaths` and validate it before rendering. A large-upload route
+under `/api/` needs `/api` removed on the way to the API; `exposure.apiPaths`
+renders a separate Ingress with a Traefik `stripPrefix` Middleware for that.

package/dist/templates/modules/admin-dashboard/files/apps/api/src/bootstrap-admin-runtime.ts

@@ -3,7 +3,7 @@
 // The command runs against a migrated schema and reports a missing table from its
 // own query. Better Auth's asynchronous startup check would only race the
 // connection the command closes when it finishes.
-import "./auth/skip-schema-validation";
+import "./auth/maintenance-command";
 import { verifyPassword } from "better-auth/crypto";
 import { auth } from "./auth/auth";
 import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -1,9 +1,12 @@
-import { error } from "@sveltejs/kit";
+import { error, type RequestEvent } from "@sveltejs/kit";
 import type { Handle } from "@sveltejs/kit/hooks";
+import { building } from "$app/env";
+import { routes } from "$app/manifest";
 import { serverApiClient } from "#lib/server/api.js";
 import { resolveLocale } from "#lib/i18n/messages.js";
 import { applySearchIndexingHeaders } from "#lib/server/search-indexing.js";
 import { isPublicPath } from "#lib/server/guards.js";
+import { needsRuntimeContext } from "#lib/server/runtime-context.js";
 import type { SiteSettings } from "#lib/site.svelte.js";
 import { ApiError } from "@podosoft/podokit-api-client";
 
@@ -12,15 +15,18 @@ function isTemporaryServiceFailure(cause: unknown): boolean {
   return cause.statusCode === 408 || cause.statusCode === 429 || cause.statusCode >= 500;
 }
 
-export const handle: Handle = async ({ event, resolve }) => {
-  // Static assets and API proxy requests do not render application layouts.
-  // Avoid multiplying settings/session API calls for every asset and proxied
-  // request; page and data routes still receive the complete runtime context.
-  if (event.route.id === null || event.url.pathname.startsWith("/api/")) {
-    const response = await resolve(event);
-    return applySearchIndexingHeaders(response, event.url.pathname);
-  }
+// An anonymous visitor with no site settings, for responses that render no
+// layout. The locale still follows the visitor's cookie.
+function setEmptyRuntimeContext(event: RequestEvent): void {
+  event.locals.site = null;
+  event.locals.siteUnavailable = false;
+  event.locals.user = null;
+  event.locals.session = null;
+  event.locals.authUnavailable = false;
+  event.locals.locale = resolveLocale(event.cookies.get("locale"));
+}
 
+async function loadRuntimeContext(event: RequestEvent): Promise<void> {
   // Public site settings (branding, locale/timezone defaults, maintenance, …)
   // and the session are independent, so both requests run at once. The
   // settings are loaded once here and reused by the layout load. The async
@@ -73,6 +79,18 @@ export const handle: Handle = async ({ event, resolve }) => {
   ) {
     error(503, "Service temporarily unavailable");
   }
+}
+
+export const handle: Handle = async ({ event, resolve }) => {
+  // Listed asset endpoints, missing subresources, the API proxy, and
+  // prerendering skip the two API lookups. Pages, their data, form actions,
+  // remote functions, and the 404 page get the complete runtime context.
+  const route = routes.find(({ id }) => id === event.route.id);
+  if (needsRuntimeContext(event, { building, route })) {
+    await loadRuntimeContext(event);
+  } else {
+    setEmptyRuntimeContext(event);
+  }
   const response = await resolve(event, {
     transformPageChunk: ({ html }) =>
       html.replace(

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/asset-paths.ts

@@ -0,0 +1,11 @@
+/**
+ * Application-owned prefixes for `+server.ts` endpoints that serve files, feeds,
+ * or other responses needing neither the session nor the site settings (for
+ * example "/docs" when an endpoint serves documentation files). A listed path
+ * also covers its subpaths. When an endpoint under a listed prefix answers a
+ * request, hooks.server.ts skips its two API lookups and the endpoint sees an
+ * anonymous `locals.user`. A `+page` under a listed prefix still gets the
+ * session and site settings, so it keeps its sign-in and maintenance checks.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_ASSET_PATHS: readonly string[] = [];

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/runtime-context.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Stands in for the application's own list in the app-owned asset-paths.ts.
+vi.mock("./asset-paths", () => ({ APP_ASSET_PATHS: ["/docs", "/feed.xml"] }));
+
+const { needsRuntimeContext, prefersHtml } = await import("./runtime-context");
+
+const NAVIGATION = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+const IMAGE = "image/avif,image/webp,image/apng,*/*;q=0.8";
+
+interface RequestOptions {
+  routeId?: string | null;
+  method?: string;
+  headers?: Record<string, string>;
+  isDataRequest?: boolean;
+  isRemoteRequest?: boolean;
+}
+
+function request(path: string, options: RequestOptions = {}) {
+  const url = new URL(path, "http://app.localhost");
+  return {
+    url,
+    route: { id: options.routeId === undefined ? url.pathname : options.routeId },
+    request: new Request(url, { method: options.method ?? "GET", headers: options.headers }),
+    isDataRequest: options.isDataRequest ?? false,
+    isRemoteRequest: options.isRemoteRequest ?? false,
+  };
+}
+
+describe("needsRuntimeContext", () => {
+  it("loads the session and site settings for pages and their data", () => {
+    expect(needsRuntimeContext(request("/account", { headers: { accept: NAVIGATION } }))).toBe(true);
+    expect(needsRuntimeContext(request("/account", { headers: { accept: "*/*" } }))).toBe(true);
+    expect(needsRuntimeContext(request("/account", { isDataRequest: true }))).toBe(true);
+  });
+
+  it("loads them for an unmatched route because the 404 page renders the root layout", () => {
+    // Without the session a signed-in visitor was sent to /login, which sent
+    // them straight back: a redirect loop on every missing page.
+    expect(
+      needsRuntimeContext(
+        request("/missing", { routeId: null, headers: { accept: NAVIGATION, "sec-fetch-dest": "document" } }),
+      ),
+    ).toBe(true);
+    expect(needsRuntimeContext(request("/missing", { routeId: null, headers: { accept: "*/*" } }))).toBe(true);
+    expect(needsRuntimeContext(request("/missing", { routeId: null, isDataRequest: true }))).toBe(true);
+  });
+
+  it("skips them for a missing subresource that SvelteKit answers without a layout", () => {
+    for (const destination of ["image", "script", "style", "font"]) {
+      expect(
+        needsRuntimeContext(request("/missing.png", { routeId: null, headers: { "sec-fetch-dest": destination } })),
+      ).toBe(false);
+    }
+  });
+
+  it("skips them for the backend proxy", () => {
+    expect(needsRuntimeContext(request("/api", { routeId: "/api/[...path]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/api/site/settings", { routeId: "/api/[...path]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/api/auth/get-session", { routeId: "/api/auth/[...all]" }))).toBe(false);
+    expect(needsRuntimeContext(request("/apiary", { headers: { accept: NAVIGATION } }))).toBe(true);
+  });
+
+  it("skips them while prerendering", () => {
+    expect(needsRuntimeContext(request("/pricing", { headers: { accept: NAVIGATION } }), { building: true })).toBe(false);
+  });
+
+  it("loads them for remote functions, which may read the session without a route", () => {
+    expect(needsRuntimeContext(request("/_app/remote/abc/list", { routeId: null, isRemoteRequest: true }))).toBe(true);
+  });
+
+  it("skips them when an endpoint under an application asset path answers", () => {
+    const files = { page: false, endpoint: true };
+    expect(
+      needsRuntimeContext(
+        request("/docs/guide/diagram.png", { routeId: "/docs/[...path]", headers: { accept: IMAGE, "sec-fetch-dest": "image" } }),
+        { route: files },
+      ),
+    ).toBe(false);
+    // Opening a file in a tab is a navigation, but no page renders.
+    expect(
+      needsRuntimeContext(
+        request("/docs/manual.pdf", { routeId: "/docs/[...path]", headers: { accept: NAVIGATION, "sec-fetch-dest": "document" } }),
+        { route: files },
+      ),
+    ).toBe(false);
+    expect(needsRuntimeContext(request("/feed.xml", { headers: { accept: "application/rss+xml" } }), { route: files })).toBe(false);
+    expect(needsRuntimeContext(request("/documents", { headers: { accept: "*/*" } }), { route: files })).toBe(true);
+  });
+
+  it("keeps them when a page under an application asset path answers", () => {
+    const page = { page: true, endpoint: false };
+    expect(needsRuntimeContext(request("/docs", { headers: { accept: "*/*" } }), { route: page })).toBe(true);
+    expect(needsRuntimeContext(request("/docs", { headers: { accept: NAVIGATION } }), { route: page })).toBe(true);
+  });
+
+  it("follows SvelteKit's page or endpoint choice when an asset route has both", () => {
+    const both = { page: true, endpoint: true };
+    const docs = (options: RequestOptions) =>
+      needsRuntimeContext(request("/docs/intro", { routeId: "/docs/[slug]", ...options }), { route: both });
+    expect(docs({ headers: { accept: NAVIGATION } })).toBe(true);
+    expect(docs({ isDataRequest: true })).toBe(true);
+    expect(docs({ method: "POST", headers: { accept: "application/json", "x-sveltekit-action": "true" } })).toBe(true);
+    expect(docs({ headers: { accept: IMAGE } })).toBe(false);
+    expect(docs({ headers: { accept: "*/*" } })).toBe(false);
+    expect(docs({ method: "PUT", headers: { accept: NAVIGATION } })).toBe(false);
+    // Without route information the same negotiation applies.
+    expect(needsRuntimeContext(request("/docs/intro", { headers: { accept: IMAGE } }))).toBe(false);
+    expect(needsRuntimeContext(request("/docs/intro", { headers: { accept: NAVIGATION } }))).toBe(true);
+  });
+});
+
+describe("prefersHtml", () => {
+  it("follows SvelteKit's page and endpoint negotiation", () => {
+    expect(prefersHtml(NAVIGATION)).toBe(true);
+    expect(prefersHtml("text/*")).toBe(true);
+    expect(prefersHtml("*/*")).toBe(false);
+    expect(prefersHtml(null)).toBe(false);
+    expect(prefersHtml(IMAGE)).toBe(false);
+    expect(prefersHtml("application/json, text/html;q=0.5")).toBe(true);
+    expect(prefersHtml("application/json, */*;q=0.9, text/html;q=0.5")).toBe(false);
+    expect(prefersHtml("*/*;q=0.9, text/html")).toBe(true);
+    expect(prefersHtml("text/html;q=0, */*")).toBe(false);
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/runtime-context.ts

@@ -0,0 +1,107 @@
+import { APP_ASSET_PATHS } from "./asset-paths";
+
+/** The request fields that decide whether a response can use the session and site settings. */
+export interface RuntimeContextRequest {
+  url: URL;
+  route: { id: string | null };
+  request: Request;
+  isDataRequest: boolean;
+  isRemoteRequest: boolean;
+}
+
+// Fetch destinations that SvelteKit answers with a plain-text 404, without the
+// root layout, when no route matches.
+const SUBRESOURCE_DESTINATIONS = new Set([
+  "audio",
+  "audioworklet",
+  "font",
+  "image",
+  "json",
+  "manifest",
+  "paintworklet",
+  "report",
+  "script",
+  "serviceworker",
+  "sharedworker",
+  "style",
+  "track",
+  "video",
+  "webidentity",
+  "worker",
+  "xslt",
+]);
+
+function underPrefix(pathname: string, prefix: string): boolean {
+  return pathname === prefix || (prefix !== "/" && pathname.startsWith(`${prefix}/`));
+}
+
+/**
+ * True when an Accept header ranks HTML ahead of the wildcard. This mirrors how
+ * SvelteKit chooses between a page and an endpoint on the same route.
+ */
+export function prefersHtml(accept: string | null): boolean {
+  const ranges = (accept ?? "*/*")
+    .split(",")
+    .map((part, index) => {
+      const [range = "", ...params] = part.trim().toLowerCase().split(";");
+      const quality = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+      return { range: range.trim(), q: quality ? Number(quality.slice(2)) : 1, index };
+    })
+    .filter(({ range, q }) => range.includes("/") && q > 0)
+    .sort((a, b) => b.q - a.q || specificity(b.range) - specificity(a.range) || a.index - b.index);
+  const html = ranges.findIndex(({ range }) => range === "text/html" || range === "text/*");
+  const wildcard = ranges.findIndex(({ range }) => range === "*/*");
+  return html !== -1 && (wildcard === -1 || html < wildcard);
+}
+
+function specificity(range: string): number {
+  if (range === "*/*") return 0;
+  return range.endsWith("/*") ? 1 : 2;
+}
+
+/** Which files the matched route has, from `routes` in `$app/manifest`. */
+export interface RouteFiles {
+  page: boolean;
+  endpoint: boolean;
+}
+
+/** True when SvelteKit answers the request with the route's `+page` rather than its `+server`. */
+function answeredByPage(event: RuntimeContextRequest, route: RouteFiles | undefined): boolean {
+  if (route && !route.page) return false;
+  if (route && !route.endpoint) return true;
+  if (event.isDataRequest) return true;
+  const { headers, method } = event.request;
+  if (method !== "GET" && method !== "HEAD" && method !== "POST") return false;
+  if (method === "POST" && headers.get("x-sveltekit-action") === "true") return true;
+  return prefersHtml(headers.get("accept"));
+}
+
+/**
+ * Decide whether hooks.server.ts must load the session and the site settings
+ * before SvelteKit answers the request. It skips them only when the response
+ * cannot render a layout, or when the application listed the path in
+ * APP_ASSET_PATHS and a `+server` endpoint, not a `+page`, answers it.
+ */
+export function needsRuntimeContext(
+  event: RuntimeContextRequest,
+  options: { building?: boolean; route?: RouteFiles } = {},
+): boolean {
+  // Prerendering runs at build time without the API, and the stored HTML must
+  // not depend on one visitor's session or on runtime site settings.
+  if (options.building) return false;
+  const { pathname } = event.url;
+  // The backend proxy forwards the cookies; the API resolves the session itself.
+  if (underPrefix(pathname, "/api")) return false;
+  // Remote functions run application code that may read the session.
+  if (event.isRemoteRequest) return true;
+  if (event.route.id === null) {
+    // SvelteKit renders its 404 page with the root layout, which redirects or
+    // greets the visitor, unless the browser fetched a subresource.
+    const destination = event.request.headers.get("sec-fetch-dest") ?? "";
+    return !SUBRESOURCE_DESTINATIONS.has(destination);
+  }
+  if (APP_ASSET_PATHS.some((prefix) => underPrefix(pathname, prefix))) {
+    return answeredByPage(event, options.route);
+  }
+  return true;
+}

package/dist/templates/modules/admin-dashboard/files/tests/api/profile-image.api.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "@playwright/test";
 import { ADMIN } from "../helpers/accounts";
+import { expectObjectLength } from "../helpers/object-response";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -48,7 +49,7 @@ test("profile image upload, replacement, public read, and removal", async ({ pla
   expect(firstImage.ok()).toBeTruthy();
   expect(firstImage.headers()["content-type"]).toContain("image/png");
   expect(firstImage.headers()["cache-control"]).toBe("public, max-age=31536000, immutable");
-  expect(firstImage.headers()["content-length"]).toBe(String(PNG.byteLength));
+  expectObjectLength(firstImage.headers(), PNG.byteLength);
   expect((await firstImage.body()).equals(PNG)).toBe(true);
   const etag = firstImage.headers()["etag"];
   expect(etag).toMatch(/^"[^"]+"$/);

package/dist/templates/modules/admin-dashboard/files/tests/api/site-settings.api.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "@playwright/test";
 import { ADMIN } from "../helpers/accounts";
+import { expectObjectLength } from "../helpers/object-response";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -101,7 +102,7 @@ test("site favicon: the versioned URL is cached for good and other URLs revalida
     expect(current.status()).toBe(200);
     expect(current.headers()["cache-control"]).toBe(IMMUTABLE);
     expect(current.headers()["content-type"]).toContain("image/png");
-    expect(current.headers()["content-length"]).toBe(String(ICON.byteLength));
+    expectObjectLength(current.headers(), ICON.byteLength);
     expect((await current.body()).equals(ICON)).toBe(true);
     const etag = current.headers()["etag"] ?? "";
     expect(etag).toMatch(/^"[^"]+"$/);

package/dist/templates/modules/admin-dashboard/files/tests/helpers/disposable-users.ts

@@ -35,16 +35,16 @@ async function readCreatedUserId(response: CreatedUserResponse): Promise<string>
 export const test = base.extend<{ disposableUsers: DisposableUsers }>({
   disposableUsers: async ({ context, playwright }, use, testInfo) => {
     // API projects do not inherit the UI project's admin storageState, while a
-    // second admin sign-in can invalidate the shared UI session. Authenticate an
-    // isolated request context only for API tests and reuse browser cookies for UI.
-    let request = context.request;
-    let ownsRequest = false;
+    // second admin sign-in can invalidate the shared UI session. API tests sign in
+    // an isolated request context. UI tests copy the browser's admin cookies into
+    // their own context once, so a test that later signs its page in as another
+    // user does not turn cleanup into that user's (forbidden) requests.
+    const request = await playwright.request.newContext({
+      baseURL,
+      extraHTTPHeaders: origin,
+      ...(testInfo.project.name === "api" ? {} : { storageState: await context.storageState() }),
+    });
     if (testInfo.project.name === "api") {
-      request = await playwright.request.newContext({
-        baseURL,
-        extraHTTPHeaders: origin,
-      });
-      ownsRequest = true;
       const signIn = await request.post("/api/auth/sign-in/email", {
         data: { email: ADMIN.email, password: ADMIN.password },
       });
@@ -94,7 +94,7 @@ export const test = base.extend<{ disposableUsers: DisposableUsers }>({
           }
         }
       } finally {
-        if (ownsRequest) await request.dispose();
+        await request.dispose();
       }
     }
   },

package/dist/templates/modules/admin-dashboard/files/tests/helpers/object-response.ts

@@ -0,0 +1,12 @@
+import { expect } from "@playwright/test";
+
+// IN_MEMORY_READ_BYTES of @podosoft/podokit-runtime. Both object storage
+// providers and the web proxy keep the Content-Length of objects up to this
+// size; Bun may send larger ones chunked.
+const IN_MEMORY_READ_BYTES = 2 * 1024 * 1024;
+
+export function expectObjectLength(headers: Record<string, string>, size: number): void {
+  const length = headers["content-length"];
+  if (length === undefined && size > IN_MEMORY_READ_BYTES) return;
+  expect(length).toBe(String(size));
+}

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -14,7 +14,8 @@
   "ownedGlobs": [
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**",
-    "apps/web/src/lib/server/public-paths.ts"
+    "apps/web/src/lib/server/public-paths.ts",
+    "apps/web/src/lib/server/asset-paths.ts"
   ],
   "managedOverrides": [
     "apps/web/src/lib/components/ui/input/input.svelte",
@@ -118,7 +119,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- `hooks.server.ts` loads the site settings and the session for pages, page data, form actions, remote functions, and the 404 page. When a `+server.ts` endpoint serves files or feeds that need neither, list its prefix in `APP_ASSET_PATHS` in the app-owned `apps/web/src/lib/server/asset-paths.ts` to skip both API calls; such endpoints see an anonymous `locals.user`, and page requests under the prefix still get the full context.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.ts",

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.spec.ts

@@ -0,0 +1,26 @@
+import type { SQL } from "bun";
+import { describe, expect, it } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import { refreshForRequest } from "./auth-provider";
+import { configureAuthQueryDatabase } from "./db";
+
+describe("refreshForRequest", () => {
+  it("stops waiting for a configuration refresh the database does not answer", async () => {
+    let queries = 0;
+    // Every query waits forever, like one on a paused server.
+    const silent = (): Promise<never> => {
+      queries += 1;
+      return new Promise(() => undefined);
+    };
+    configureAuthQueryDatabase(silent as unknown as SQL);
+
+    const waitMs = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
+    const started = Date.now();
+    await refreshForRequest();
+    const waited = Date.now() - started;
+
+    expect(queries).toBeGreaterThan(0);
+    expect(waited).toBeGreaterThanOrEqual(waitMs - 10);
+    expect(waited).toBeLessThan(waitMs + 500);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.ts

@@ -1,7 +1,12 @@
 import type { AuthConfig } from "@podosoft/podokit-auth";
+import { validateEnv } from "../config/env.validation";
 import { auth as bootstrapAuth, buildAuth } from "./auth";
 import { authConfigStore } from "./auth-config-store";
 import { publishConfigChanged } from "./config-events";
+import { answersWithin, checkAuthResponse } from "./database-outage";
+import { authDatabaseReachable } from "./db";
+
+const REFRESH_WAIT_MS = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
 
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
@@ -52,10 +57,20 @@ export async function refreshAuthNow(): Promise<void> {
   await publishConfigChanged();
 }
 
+/**
+ * Refreshes before a request is served. While PostgreSQL does not answer, the
+ * refresh lasts as long as a query may wait, and the request would wait for
+ * Better Auth's own queries after it. Past the readiness check timeout the
+ * current instance serves the request, and the refresh finishes in the background.
+ */
+export async function refreshForRequest(): Promise<void> {
+  await answersWithin(refreshIfStale, REFRESH_WAIT_MS);
+}
+
 // Stable handler reference the adapter captures once; redispatches per request.
 const dynamicHandler: typeof bootstrapAuth.handler = async (request) => {
-  await refreshIfStale();
-  return current.handler(request);
+  await refreshForRequest();
+  return checkAuthResponse(await current.handler(request), authDatabaseReachable);
 };
 
 export const authRuntime: typeof bootstrapAuth = new Proxy(bootstrapAuth, {

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.service.ts

@@ -1,8 +1,9 @@
 import { AppException } from "@podosoft/podokit-contracts";
 import type { AccessPolicy, RequestIdentity } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
-import { getAuth, refreshIfStale } from "./auth-provider";
-import { closeAuthDatabase } from "./db";
+import { getAuth, refreshForRequest } from "./auth-provider";
+import { rethrowAuthError } from "./database-outage";
+import { authDatabaseReachable, closeAuthDatabase } from "./db";
 
 export interface AuthUser extends Record<string, unknown> {
   id: string;
@@ -18,9 +19,12 @@ export interface AuthSession {
 export type SessionResolver = (headers: Headers) => Promise<AuthSession | null>;
 
 function defaultSessionResolver(headers: Headers): Promise<AuthSession | null> {
-  return refreshIfStale()
+  return refreshForRequest()
     .then(() => getAuth().api.getSession({ headers }))
-    .then((session) => session as AuthSession | null);
+    .then(
+      (session) => session as AuthSession | null,
+      (error: unknown) => rethrowAuthError(error, authDatabaseReachable),
+    );
 }
 
 export function rolesOf(user: AuthUser): string[] {

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -14,7 +14,7 @@ import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 import { runUserDeletedHandlers } from "./user-delete-handlers";
 import { authBaseUrl, authSecret } from "./auth-environment";
-import { authSchemaValidation } from "./schema-validation";
+import { isMaintenanceCommand } from "./maintenance";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -233,7 +233,7 @@ export function buildAuth(config: AuthConfig) {
         // resolved client IP as x-forwarded-for; trust it so sessions record an IP.
         ipAddressHeaders: ["x-forwarded-for"],
       },
-      ...(authSchemaValidation() ? {} : { database: { validateSchema: false } }),
+      ...(isMaintenanceCommand() ? { database: { validateSchema: false } } : {}),
     },
     user: {
       additionalFields: {