@podosoft/podokit 0.12.1 → 0.12.3

package/dist/templates/modules/admin-dashboard/files/apps/web/src/app.d.ts

@@ -20,8 +20,10 @@ declare global {
     interface Locals {
       user: SessionUser | null;
       session: { id: string; impersonatedBy?: string | null } | null;
+      authUnavailable: boolean;
       locale: Locale;
       site: SiteSettings | null;
+      siteUnavailable: boolean;
     }
   }
 }

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

@@ -1,8 +1,15 @@
-import type { Handle } from "@sveltejs/kit";
+import { error, type Handle } from "@sveltejs/kit";
 import { serverApiClient } from "$lib/server/api";
 import { resolveLocale } from "$lib/i18n/messages";
 import { applySearchIndexingHeaders } from "$lib/server/search-indexing";
+import { isPublicPath } from "$lib/server/guards";
 import type { SiteSettings } from "$lib/site.svelte";
+import { ApiError } from "@podosoft/podokit-api-client";
+
+function isTemporaryServiceFailure(cause: unknown): boolean {
+  if (!(cause instanceof ApiError)) return true;
+  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.
@@ -16,23 +23,46 @@ export const handle: Handle = async ({ event, resolve }) => {
   // Public site settings (branding, locale/timezone defaults, maintenance, …),
   // loaded once here and reused by the layout load. A visitor with no locale
   // cookie falls back to the admin-configured site locale, then the app default.
+  event.locals.siteUnavailable = false;
   let site: SiteSettings | null = null;
   try {
     site = await serverApiClient(event).get<SiteSettings>("/site/settings");
-  } catch {
+  } catch (cause: unknown) {
     site = null;
+    // A request-level 4xx proves that the backend is reachable. In particular,
+    // the require-2FA guard returns 403 until enrolment and must remain able to
+    // redirect the user to /setup-2fa instead of being masked as an outage.
+    event.locals.siteUnavailable = isTemporaryServiceFailure(cause);
   }
   event.locals.site = site;
   event.locals.locale = resolveLocale(event.cookies.get("locale") ?? site?.locale ?? undefined);
+
+  event.locals.user = null;
+  event.locals.session = null;
+  event.locals.authUnavailable = false;
   try {
-    const { data } = await serverApiClient(event).auth.getSession();
-    event.locals.user = (data?.user as App.Locals["user"]) ?? null;
-    event.locals.session = data?.session
-      ? { id: data.session.id, impersonatedBy: (data.session as { impersonatedBy?: string | null }).impersonatedBy ?? null }
-      : null;
+    const { data, error } = await serverApiClient(event).auth.getSession();
+    // Better Auth returns HTTP authentication failures as data/error. A 401 is
+    // a confirmed anonymous session; every other error means that the session
+    // could not be checked and must not be treated as a logout.
+    if (error && error.status !== 401) {
+      event.locals.authUnavailable = true;
+    } else {
+      event.locals.user = (data?.user as App.Locals["user"]) ?? null;
+      event.locals.session = data?.session
+        ? { id: data.session.id, impersonatedBy: (data.session as { impersonatedBy?: string | null }).impersonatedBy ?? null }
+        : null;
+    }
   } catch {
-    event.locals.user = null;
-    event.locals.session = null;
+    // Transport failures do not invalidate the browser's session cookie. A
+    // protected loader will fail closed with 503 until the backend recovers.
+    event.locals.authUnavailable = true;
+  }
+  if (
+    (event.locals.authUnavailable || event.locals.siteUnavailable) &&
+    !isPublicPath(event.url.pathname)
+  ) {
+    error(503, "Service temporarily unavailable");
   }
   const response = await resolve(event, {
     transformPageChunk: ({ html }) =>

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

@@ -4,8 +4,34 @@ import { error } from "@sveltejs/kit";
  *  added here (and, later, replaced by a permission check) without touching every
  *  page loader. better-auth stores a user's role(s) as a comma-separated string. */
 const ADMIN_ROLES = ["admin"];
+const PUBLIC_PATHS = [
+  "/",
+  "/login",
+  "/signup",
+  "/forgot-password",
+  "/reset-password",
+  "/verify-email",
+  "/pending-approval",
+  "/maintenance",
+  // Modules add their public (no-session) page prefixes here.
+  // podokit:begin:public-paths
+  // podokit:end:public-paths
+];
 
 type WithRole = { role?: string | null } | null | undefined;
+type BackendAvailability = Pick<App.Locals, "authUnavailable" | "siteUnavailable">;
+
+/** True for routes that may render without a confirmed session or site policy. */
+export function isPublicPath(pathname: string): boolean {
+  return PUBLIC_PATHS.some((path) => pathname === path || (path !== "/" && pathname.startsWith(`${path}/`)));
+}
+
+/** Stop protected loaders when authentication or runtime policy cannot be checked. */
+export function requireBackendAvailable(locals: BackendAvailability): void {
+  if (locals.authUnavailable || locals.siteUnavailable) {
+    error(503, "Service temporarily unavailable");
+  }
+}
 
 /** True when the user holds at least one admin role. */
 export function isAdmin(user: WithRole): boolean {
@@ -16,7 +42,8 @@ export function isAdmin(user: WithRole): boolean {
   return roles.some((r) => ADMIN_ROLES.includes(r));
 }
 
-/** Guard an admin-only loader: throws 403 unless the user holds an admin role. */
-export function requireAdmin(user: WithRole): void {
+/** Guard an admin-only loader after confirming the backend is available. */
+export function requireAdmin(user: WithRole, availability?: BackendAvailability): void {
+  if (availability) requireBackendAvailable(availability);
   if (!isAdmin(user)) error(403, "Admins only");
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/+layout.server.ts

@@ -1,8 +1,11 @@
 import { redirect } from "@sveltejs/kit";
 import type { LayoutServerLoad } from "./$types";
 import type { Capabilities } from "@podosoft/podokit-api-client";
+import { requireBackendAvailable } from "$lib/server/guards";
 
 export const load: LayoutServerLoad = async ({ locals, fetch }) => {
+  requireBackendAvailable(locals);
+
   let capabilities: Capabilities = {
     twoFactor: false,
     providers: [],

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/audit/+page.server.ts

@@ -2,5 +2,5 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/organizations/+page.server.ts

@@ -2,5 +2,5 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/sessions/+page.server.ts

@@ -2,6 +2,6 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   return { currentSessionId: locals.session?.id ?? null };
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.server.ts

@@ -14,7 +14,7 @@ export type AuthConfigView = {
 };
 
 export const load: PageServerLoad = async ({ locals, fetch }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   let authConfig: AuthConfigView | null = null;
   try {
     const res = await fetch("/api/account/auth-config");

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/users/+page.server.ts

@@ -2,6 +2,6 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   return { currentUserId: locals.user!.id };
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+layout.server.ts

@@ -2,29 +2,13 @@ import type { LayoutServerLoad } from "./$types";
 import { redirect } from "@sveltejs/kit";
 import { safeAuthRedirect } from "$lib/auth-redirect";
 import { loadMessages } from "$lib/i18n/messages";
+import { isPublicPath, requireBackendAvailable } from "$lib/server/guards";
 
 // "/" is a public landing page. Auth pages return signed-in users to their safe
 // requested page, and the admin area requires a session. /maintenance is public
 // so it renders while the rest of the site is held back.
-const PUBLIC_PATHS = [
-  "/",
-  "/login",
-  "/signup",
-  "/forgot-password",
-  "/reset-password",
-  "/verify-email",
-  "/pending-approval",
-  "/maintenance",
-  // Modules add their public (no-session) page prefixes here.
-  // podokit:begin:public-paths
-  // podokit:end:public-paths
-];
 const AUTH_PATHS = ["/login", "/signup", "/forgot-password", "/reset-password"];
 
-function isPublic(pathname: string): boolean {
-  return PUBLIC_PATHS.some((path) => pathname === path || (path !== "/" && pathname.startsWith(`${path}/`)));
-}
-
 export const load: LayoutServerLoad = async (event) => {
   const { locals, url } = event;
   const { pathname } = url;
@@ -32,13 +16,18 @@ export const load: LayoutServerLoad = async (event) => {
   const site = locals.site;
   const isAdmin = locals.user?.role === "admin";
 
+  // Authentication and maintenance policy are both security boundaries. If
+  // either could not be checked, deny protected content without redirecting to
+  // login or modifying the session cookie. Public pages keep their static fallbacks.
+  if (!isPublicPath(pathname)) requireBackendAvailable(locals);
+
   // Maintenance mode holds everyone but admins on a maintenance page. /login and
   // /maintenance stay reachable so an admin can still sign in and turn it off.
   const maintenance = site?.maintenanceMode === "true";
   if (maintenance && !isAdmin && pathname !== "/maintenance" && pathname !== "/login") {
     redirect(303, "/maintenance");
   }
-  if (!maintenance && pathname === "/maintenance") {
+  if (!locals.siteUnavailable && !maintenance && pathname === "/maintenance") {
     redirect(303, "/");
   }
   // Registration closed from the admin Settings: send /signup back to /login.
@@ -50,7 +39,7 @@ export const load: LayoutServerLoad = async (event) => {
   if (locals.user && AUTH_PATHS.includes(pathname)) {
     redirect(303, safeAuthRedirect(url.searchParams.get("redirect")));
   }
-  if (!locals.user && !isPublic(pathname)) {
+  if (!locals.user && !isPublicPath(pathname)) {
     redirect(303, `/login?redirect=${encodeURIComponent(`${pathname}${url.search}`)}`);
   }
   const messages = await loadMessages(locals.locale, site?.locale);

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.server.ts

@@ -1,9 +1,11 @@
 import { redirect } from "@sveltejs/kit";
 import type { PageServerLoad } from "./$types";
+import { requireBackendAvailable } from "$lib/server/guards";
 
 // The mandatory two-factor enrolment page (reached via the require-2fa gate).
 // Must be signed in; already-enrolled users have nothing to do here.
 export const load: PageServerLoad = ({ locals }) => {
+  requireBackendAvailable(locals);
   if (!locals.user) redirect(302, "/login");
   const user = locals.user as App.Locals["user"] & { twoFactorEnabled?: boolean };
   if (user.twoFactorEnabled) redirect(302, "/admin");

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

@@ -53,7 +53,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; 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- **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.\n"
+      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; 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- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\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.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",

package/dist/update.d.ts

@@ -28,6 +28,8 @@ export declare function planUpdate(projectRoot: string, templatesDir: string): U
 export interface ApplyOptions {
     /** Templates for the version the project is currently on, for 3-way merges. */
     oldTemplatesDir?: string;
+    /** Preinstalled previous external modules. Primarily useful for offline updates. */
+    oldExternalModulesRoot?: string;
 }
 export interface ApplyResult {
     written: string[];

package/dist/update.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.planUpdate = planUpdate;
 exports.applyUpdate = applyUpdate;
 exports.summarize = summarize;
+const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const assemble_1 = require("./assemble");
@@ -124,20 +126,48 @@ function planUpdate(projectRoot, templatesDir) {
         changes,
     };
 }
-function assertPreviousExternalModulesInstalled(projectRoot, templatesDir, modules) {
+function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     for (const module of modules) {
         if (!module.packageName || !module.moduleVersion)
             continue;
-        const resolved = (0, add_1.resolveModule)(module.packageName, modulesDir, projectRoot);
-        if (!resolved?.moduleVersion || resolved.moduleVersion === module.moduleVersion)
+        const resolved = (0, add_1.resolveModule)(module.packageName, modulesDir, moduleRoot);
+        if (resolved?.moduleVersion === module.moduleVersion)
             continue;
-        throw new Error(`Cannot use --from while external module "${module.packageName}" is installed at ` +
-            `${resolved.moduleVersion} but the project records ${module.moduleVersion}. Restore ` +
-            `${module.packageName}@${module.moduleVersion}, update PodoKit with --from, then upgrade ` +
-            "external modules separately.");
+        const actual = resolved?.moduleVersion ?? "not installed";
+        throw new Error(`Previous external module root has ${module.packageName} at ${actual}; ` +
+            `expected ${module.moduleVersion} from the project manifest.`);
     }
 }
+function previousExternalModules(projectRoot, templatesDir, modules, providedRoot) {
+    const external = modules.filter((module) => Boolean(module.packageName && module.moduleVersion));
+    if (!external.length)
+        return { root: projectRoot, cleanup: false };
+    if (providedRoot) {
+        assertRecordedExternalModules(providedRoot, templatesDir, external);
+        return { root: providedRoot, cleanup: false };
+    }
+    const currentMatchesRecorded = external.every((module) => {
+        const resolved = (0, add_1.resolveModule)(module.packageName, (0, node_path_1.join)(templatesDir, "modules"), projectRoot);
+        return resolved?.moduleVersion === module.moduleVersion;
+    });
+    if (currentMatchesRecorded)
+        return { root: projectRoot, cleanup: false };
+    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "podokit-update-modules-"));
+    const devDependencies = Object.fromEntries(external.map((module) => [module.packageName, module.moduleVersion]));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, "package.json"), `${JSON.stringify({ name: "podokit-update-modules", private: true, devDependencies }, null, 2)}\n`);
+    try {
+        (0, node_child_process_1.execFileSync)("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--package-lock=false"], { cwd: root, stdio: "pipe" });
+        assertRecordedExternalModules(root, templatesDir, external);
+    }
+    catch {
+        (0, node_fs_1.rmSync)(root, { recursive: true, force: true });
+        const expected = external.map((module) => `${module.packageName}@${module.moduleVersion}`).join(", ");
+        throw new Error(`Cannot install previous external modules (${expected}) for the 3-way merge. ` +
+            "Check npm registry access and try again.");
+    }
+    return { root, cleanup: true };
+}
 function writeFile(projectRoot, path, content) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
@@ -203,18 +233,23 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
     const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs);
     const needsMergeBase = plan.changes.some((change) => change.action === "conflict");
+    let oldTree = null;
     if (options.oldTemplatesDir && needsMergeBase) {
-        assertPreviousExternalModulesInstalled(projectRoot, templatesDir, modules);
+        const previousModules = previousExternalModules(projectRoot, options.oldTemplatesDir, modules, options.oldExternalModulesRoot);
+        try {
+            oldTree = (0, assemble_1.assembleProject)({
+                templatesDir: options.oldTemplatesDir,
+                template: manifest.template,
+                answers: manifest.answers,
+                modules,
+                projectRoot: previousModules.root,
+            });
+        }
+        finally {
+            if (previousModules.cleanup)
+                (0, node_fs_1.rmSync)(previousModules.root, { recursive: true, force: true });
+        }
     }
-    const oldTree = options.oldTemplatesDir && needsMergeBase
-        ? (0, assemble_1.assembleProject)({
-            templatesDir: options.oldTemplatesDir,
-            template: manifest.template,
-            answers: manifest.answers,
-            modules,
-            projectRoot,
-        })
-        : null;
     const result = { written: [], removed: [], merged: [], conflicts: [] };
     for (const change of plan.changes) {
         const newText = treeText(newTree, change.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {