@podosoft/podokit 1.1.6 → 1.3.0

package/dist/add.d.ts

@@ -1,5 +1,5 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
-import { type ProviderCapability } from "@podosoft/podokit-runtime";
+import { type ProviderCapability, type ProviderSelections } from "@podosoft/podokit-runtime";
 interface Injection {
     file: string;
     marker: string;
@@ -127,6 +127,8 @@ export declare function resolveModuleDir(name: string, modulesDir: string, proje
 /** Resolve a module and capture the package identity needed to replay external
  * modules during `podo update`. */
 export declare function resolveModule(name: string, modulesDir: string, projectRoot: string): ResolvedModule | null;
+/** Name of the module that implements the selected provider for a capability. */
+export declare function selectedProviderModule(modulesDir: string, projectRoot: string, providers: ProviderSelections, capability: ProviderCapability): string;
 /** List modules available to a project: the bundled ones under `modulesDir` plus,
  *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
  *  in it. Bundled names take precedence on a clash. */

package/dist/add.js

@@ -4,6 +4,7 @@ exports.SUPPORTED_MANIFEST_VERSION = void 0;
 exports.modulePackageOverlays = modulePackageOverlays;
 exports.resolveModuleDir = resolveModuleDir;
 exports.resolveModule = resolveModule;
+exports.selectedProviderModule = selectedProviderModule;
 exports.listModules = listModules;
 exports.readModuleManifest = readModuleManifest;
 exports.addModule = addModule;
@@ -106,11 +107,9 @@ function assertManifestVersion(name, manifest) {
         throw new Error(`Module "${name}" declares an invalid maxApiReplicas constraint.`);
     }
 }
-function providerModuleName(projectRoot, modulesDir, capability) {
-    const project = (0, lockfile_1.readManifest)(projectRoot);
-    if (!project)
-        throw new Error("Provider capabilities require a PodoKit project manifest.");
-    const selected = project.providers[capability];
+/** Name of the module that implements the selected provider for a capability. */
+function selectedProviderModule(modulesDir, projectRoot, providers, capability) {
+    const selected = providers[capability];
     for (const available of listModules(modulesDir, projectRoot)) {
         const resolved = resolveModule(available.name, modulesDir, projectRoot);
         if (!resolved)
@@ -122,6 +121,12 @@ function providerModuleName(projectRoot, modulesDir, capability) {
     throw new Error(`No module provides the selected ${capability} provider "${selected}". ` +
         `Choose another provider with podo provider set ${capability} <provider> --apply.`);
 }
+function providerModuleName(projectRoot, modulesDir, capability) {
+    const project = (0, lockfile_1.readManifest)(projectRoot);
+    if (!project)
+        throw new Error("Provider capabilities require a PodoKit project manifest.");
+    return selectedProviderModule(modulesDir, projectRoot, project.providers, capability);
+}
 function requiredModules(projectRoot, modulesDir, manifest) {
     const capabilities = (manifest.requiresCapabilities ?? []).map((capability) => providerModuleName(projectRoot, modulesDir, capability));
     return [...new Set([...(manifest.requires ?? []), ...capabilities])];
@@ -217,14 +222,24 @@ function projectName(projectRoot) {
     const pkg = readJson((0, node_path_1.join)(projectRoot, "package.json"));
     return typeof pkg.name === "string" ? pkg.name : "app";
 }
-function appendEnv(projectRoot, lines) {
+function appendEnv(projectRoot, lines, anchors = []) {
     const file = (0, node_path_1.join)(projectRoot, ".env.example");
     if (!(0, node_fs_1.existsSync)(file))
         return;
     const current = (0, node_fs_1.readFileSync)(file, "utf8");
-    const missing = lines.filter((line) => !current.split("\n").includes(line));
+    const existing = current.split("\n");
+    const missing = lines.filter((line) => !existing.includes(line));
     if (missing.length === 0)
         return;
+    // Each module appends its own blank-line separated block. Keep that shape
+    // when the block belongs in front of a displaced module's block.
+    const wanted = new Set(anchors);
+    const index = existing.findIndex((line, position) => position > 0 && existing[position - 1] === "" && wanted.has(line));
+    if (index !== -1) {
+        existing.splice(index, 0, ...missing, "");
+        (0, node_fs_1.writeFileSync)(file, existing.join("\n"));
+        return;
+    }
     const separator = current.endsWith("\n") ? "" : "\n";
     (0, node_fs_1.writeFileSync)(file, `${current}${separator}\n${missing.join("\n")}\n`);
 }
@@ -246,6 +261,91 @@ function isApplied(projectRoot, modulesDir, module) {
     }
     return false;
 }
+function injectionKey(file, marker) {
+    return `${file}\n${marker}`;
+}
+/** Modules `applyModule` would newly apply, in application order. */
+function plannedModules(projectRoot, module, modulesDir, planned = new Set(), order = []) {
+    planned.add(module);
+    const resolved = resolveModule(module, modulesDir, projectRoot);
+    if (!resolved)
+        return order;
+    for (const required of requiredModules(projectRoot, modulesDir, readModuleManifest(resolved.dir))) {
+        if (planned.has(required) || isApplied(projectRoot, modulesDir, required))
+            continue;
+        plannedModules(projectRoot, required, modulesDir, planned, order);
+    }
+    order.push(module);
+    return order;
+}
+function modulePlacement(projectRoot, module, modulesDir) {
+    const project = (0, lockfile_1.readManifest)(projectRoot);
+    if (!project)
+        return undefined;
+    const installed = [...project.modules].sort((a, b) => a.order - b.order);
+    const installedNames = new Set(installed.map((entry) => entry.name));
+    const fresh = new Set(plannedModules(projectRoot, module, modulesDir).filter((name) => !installedNames.has(name)));
+    if (!fresh.size)
+        return undefined;
+    const provided = new Set();
+    for (const name of fresh) {
+        const resolved = resolveModule(name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        for (const capability of Object.keys(readModuleManifest(resolved.dir).provides ?? {})) {
+            provided.add(capability);
+        }
+    }
+    const vars = {
+        projectName: projectName(projectRoot),
+        ...(0, lockfile_1.manifestTemplateVars)(project),
+    };
+    const manifests = installed.map((entry) => {
+        const resolved = resolveModule(entry.packageName ?? entry.name, modulesDir, projectRoot);
+        return resolved ? readModuleManifest(resolved.dir, vars) : undefined;
+    });
+    const first = manifests.findIndex((manifest) => manifest !== undefined && ((manifest.requires ?? []).some((name) => fresh.has(name))
+        || (manifest.requiresCapabilities ?? []).some((capability) => provided.has(capability))));
+    if (first === -1)
+        return undefined;
+    const injections = new Map();
+    const env = [];
+    for (const manifest of manifests.slice(first)) {
+        if (!manifest)
+            continue;
+        for (const injection of manifest.inject ?? []) {
+            const key = injectionKey(injection.file, injection.marker);
+            injections.set(key, [...(injections.get(key) ?? []), injection.text]);
+        }
+        env.push(...(manifest.env ?? []));
+    }
+    return { before: installed[first].name, injections, env };
+}
+/** Insert wiring at its marker, or in front of the first displaced module's wiring. */
+function injectAt(content, injection, anchors = []) {
+    if (!anchors.length || content.includes(injection.text)) {
+        return (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text);
+    }
+    const lines = content.split("\n");
+    const end = lines.findIndex((line) => line.includes(injection.marker));
+    if (end === -1)
+        throw new Error(`Marker not found: ${injection.marker}`);
+    const beginMarker = injection.marker.replace("podokit:end:", "podokit:begin:");
+    const begin = beginMarker === injection.marker
+        ? -1
+        : lines.slice(0, end).findIndex((line) => line.includes(beginMarker));
+    const wanted = new Set(anchors.map((text) => text.split("\n")[0].trim()));
+    let index = end;
+    for (let line = begin + 1; line < end; line += 1) {
+        if (wanted.has(lines[line].trim())) {
+            index = line;
+            break;
+        }
+    }
+    const indent = lines[end].match(/^\s*/)?.[0] ?? "";
+    lines.splice(index, 0, `${indent}${injection.text}`);
+    return lines.join("\n");
+}
 /**
  * Apply a module to an existing generated project: overlay files, merge the
  * target app's package.json dependencies and scripts, append env example lines,
@@ -262,7 +362,8 @@ function addModule(options) {
         })
             .map(([path]) => path)
         : [];
-    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false);
+    const placement = modulePlacement(options.projectRoot, options.module, options.modulesDir);
+    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false, placement);
     if (options.adopt && result.adopted.length) {
         releaseOwnedPaths(options.projectRoot, result.adopted);
     }
@@ -279,10 +380,10 @@ function addModule(options) {
             modulePaths: [...new Set(result.touched)],
             adoptedPaths: result.adopted,
         }
-        : undefined, result.managedOverrides);
+        : undefined, result.managedOverrides, placement?.before);
     return result;
 }
-function applyModule(projectRoot, module, modulesDir, applied, adopt) {
+function applyModule(projectRoot, module, modulesDir, applied, adopt, placement) {
     const resolved = resolveModule(module, modulesDir, projectRoot);
     if (!resolved) {
         const available = listModules(modulesDir, projectRoot).map((m) => m.name);
@@ -318,8 +419,8 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     for (const required of requiredModules(projectRoot, modulesDir, manifest)) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
-        const result = applyModule(projectRoot, required, modulesDir, applied, adopt);
-        added.push(required, ...result.added);
+        const result = applyModule(projectRoot, required, modulesDir, applied, adopt, placement);
+        added.push(...result.added, required);
         ownedGlobs.push(...result.ownedGlobs);
         managedOverrides.push(...result.managedOverrides);
         preserved.push(...result.preserved);
@@ -356,7 +457,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     }
     // 3) append env example lines
     if (manifest.env?.length) {
-        appendEnv(projectRoot, manifest.env);
+        appendEnv(projectRoot, manifest.env, placement?.env);
         touched.push(".env.example");
     }
     // 4) inject wiring at markers
@@ -370,7 +471,8 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         const content = (0, node_fs_1.readFileSync)(target, "utf8");
         if (injection.optional && !content.includes(injection.marker))
             continue;
-        (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
+        const anchors = placement?.injections.get(injectionKey(injection.file, injection.marker));
+        (0, node_fs_1.writeFileSync)(target, injectAt(content, injection, anchors));
         touched.push(injection.file);
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));

package/dist/deploy-render.js

@@ -385,6 +385,8 @@ metadata:
 ${entries.length ? `data:\n${entries.map(([key, value]) => `  ${key}: ${quote(value)}`).join("\n")}` : "data: {}"}
 `;
 }
+// Above the API's 800 ms per-check readiness bound; the Kubernetes default is 1 s.
+const API_PROBE_TIMEOUT_SECONDS = 2;
 function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest) {
     const name = `${profile.target.release}-${kind}`;
     const workloadSecret = kind === "api" ? profile.secrets.api : profile.secrets.web;
@@ -396,14 +398,17 @@ function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeC
         ? `          readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             periodSeconds: 5
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
           startupProbe:
             httpGet: { path: /health, port: 3000 }
             failureThreshold: 30
             periodSeconds: 2
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
 `
         : `          readinessProbe:
             httpGet: { path: /, port: 3000 }

package/dist/index.js

@@ -652,6 +652,9 @@ async function main(argv) {
         try {
             if (args.apply) {
                 const result = (0, update_1.applyUpdate)(process.cwd(), templatesDir, { oldTemplatesDir: args.from });
+                if (result.addedModules.length) {
+                    process.stdout.write(`Added required module(s): ${result.addedModules.join(", ")}\n`);
+                }
                 process.stdout.write(`Applied: ${result.written.length} written, ${result.moved.length} moved, ` +
                     `${result.removed.length} removed, ` +
                     `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
@@ -666,6 +669,11 @@ async function main(argv) {
             const counts = (0, update_1.summarize)(plan);
             const shown = plan.changes.filter((c) => c.action !== "up-to-date" && c.action !== "skip");
             process.stdout.write(`podo update ${plan.fromVersion} -> ${plan.toVersion}  (template: ${plan.template}; modules: ${plan.modules.join(", ") || "none"})\n\n`);
+            if (plan.addedModules.length) {
+                process.stdout.write("Modules to add:\n" +
+                    plan.addedModules.map((module) => `  ${module.name}  (${(0, update_1.addedModuleReason)(module)})`).join("\n") +
+                    "\n\n");
+            }
             if (!shown.length) {
                 process.stdout.write("Everything is up to date.\n");
             }

package/dist/lib.d.ts

@@ -8,8 +8,8 @@ export { listModules, addModule } from "./add";
 export type { ModuleManifest, ModuleMigration, ModulePathMove, ModuleTextReplacement, AddOptions, AddResult, } from "./add";
 export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
 export type { StatusReport, DoctorFinding } from "./inspect";
-export { planUpdate, summarize } from "./update";
-export type { UpdatePlan, FileChange } from "./update";
+export { addedModuleReason, planUpdate, summarize } from "./update";
+export type { AddedModule, UpdatePlan, FileChange } from "./update";
 export { readDevConfig, renderRoute, renderRuntimeCompose, resolveDevRuntime, runDevCommand } from "./dev";
 export type { CommandRunner, DevConfig, DevRuntime } from "./dev";
 export { applyDeployment, doctorDeployment, getDeploymentStatus, inspectClusterFingerprint, planDeployment, planRollback, rollbackDeployment, verifyDeployment, } from "./deploy";

package/dist/lib.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getComposeStatus = exports.doctorComposeDeployment = exports.applyComposeDeployment = exports.renderComposeDeployment = exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = exports.renderDeployment = exports.loadDeploymentProfile = exports.listDeploymentProfiles = exports.initializeDeploymentProfile = exports.deploymentProfileDigest = exports.assertReleaseTag = exports.verifyDeployment = exports.rollbackDeployment = exports.planRollback = exports.planDeployment = exports.inspectClusterFingerprint = exports.getDeploymentStatus = exports.doctorDeployment = exports.applyDeployment = exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.summarize = exports.planUpdate = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
-exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = void 0;
+exports.doctorComposeDeployment = exports.applyComposeDeployment = exports.renderComposeDeployment = exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = exports.renderDeployment = exports.loadDeploymentProfile = exports.listDeploymentProfiles = exports.initializeDeploymentProfile = exports.deploymentProfileDigest = exports.assertReleaseTag = exports.verifyDeployment = exports.rollbackDeployment = exports.planRollback = exports.planDeployment = exports.inspectClusterFingerprint = exports.getDeploymentStatus = exports.doctorDeployment = exports.applyDeployment = exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.summarize = exports.planUpdate = exports.addedModuleReason = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
+exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = exports.getComposeStatus = void 0;
 exports.builtinTemplatesDir = builtinTemplatesDir;
 exports.builtinModulesDir = builtinModulesDir;
 // Library entry point: the reusable functions behind the `podo` CLI, for other
@@ -29,6 +29,7 @@ Object.defineProperty(exports, "diff", { enumerable: true, get: function () { re
 Object.defineProperty(exports, "doctor", { enumerable: true, get: function () { return inspect_1.doctor; } });
 Object.defineProperty(exports, "SUPPORTED_FRAMEWORKS", { enumerable: true, get: function () { return inspect_1.SUPPORTED_FRAMEWORKS; } });
 var update_1 = require("./update");
+Object.defineProperty(exports, "addedModuleReason", { enumerable: true, get: function () { return update_1.addedModuleReason; } });
 Object.defineProperty(exports, "planUpdate", { enumerable: true, get: function () { return update_1.planUpdate; } });
 Object.defineProperty(exports, "summarize", { enumerable: true, get: function () { return update_1.summarize; } });
 var dev_1 = require("./dev");

package/dist/lockfile.d.ts

@@ -116,4 +116,6 @@ export declare function mergeOwnedGlobs(existing: string[], add: string[]): stri
  * `ownedGlobs` a module declares are merged into the manifest so its owned paths
  * survive every future recompute. No-op on projects without a manifest.
  */
-export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot, managedOverrides?: string[]): void;
+export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot, managedOverrides?: string[], 
+/** Installed module that newly recorded modules must configure before. */
+insertBefore?: string): void;

package/dist/lockfile.js

@@ -257,29 +257,40 @@ function mergeOwnedGlobs(existing, add) {
  * `ownedGlobs` a module declares are merged into the manifest so its owned paths
  * survive every future recompute. No-op on projects without a manifest.
  */
-function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot, managedOverrides) {
+function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot, managedOverrides, 
+/** Installed module that newly recorded modules must configure before. */
+insertBefore) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
     const stampedWith = version ?? podokitVersion();
-    const known = new Set(manifest.modules.map((m) => m.name));
+    const fresh = [];
     for (const input of moduleInputs) {
         const module = typeof input === "string" ? { name: input } : input;
-        const existing = manifest.modules.find((entry) => entry.name === module.name);
+        const existing = manifest.modules.find((entry) => entry.name === module.name)
+            ?? fresh.find((entry) => entry.name === module.name);
         if (existing) {
             existing.packageName = module.packageName ?? existing.packageName;
             existing.moduleVersion = module.moduleVersion ?? existing.moduleVersion;
             continue;
         }
-        manifest.modules.push({
+        fresh.push({
             name: module.name,
-            order: manifest.modules.length,
+            order: manifest.modules.length + fresh.length,
             addedWith: stampedWith,
             packageName: module.packageName,
             moduleVersion: module.moduleVersion,
             appliedMigrations: module.appliedMigrations,
         });
-        known.add(module.name);
+    }
+    const ordered = [...manifest.modules].sort((a, b) => a.order - b.order);
+    const position = insertBefore ? ordered.findIndex((entry) => entry.name === insertBefore) : -1;
+    if (position === -1) {
+        manifest.modules.push(...fresh);
+    }
+    else {
+        ordered.splice(position, 0, ...fresh);
+        manifest.modules = ordered.map((entry, order) => ({ ...entry, order }));
     }
     if (ownedGlobs?.length)
         manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);

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

@@ -16,8 +16,8 @@
     "migration:generate": "bun run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.4.0",
-    "@podosoft/podokit-runtime": "^0.2.0",
+    "@podosoft/podokit-contracts": "^0.5.0",
+    "@podosoft/podokit-runtime": "^0.3.0",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/scripts/build.mjs

@@ -5,6 +5,7 @@ const targets = [
   { entrypoint: "src/database/migrate.ts", outdir: "dist/database" },
   { entrypoint: "src/migrate.ts", outdir: "dist" },
   { entrypoint: "src/main-worker.ts", outdir: "dist" },
+  { entrypoint: "src/bootstrap-admin-runtime.ts", outdir: "dist" },
 ].filter((target) => existsSync(target.entrypoint));
 
 for (const target of targets) {

package/dist/templates/fullstack/apps/api/src/app.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, mock, type Mock } from "bun:test";
+import { cachedOpenApiDocument, type OpenApiDocumentLoader } from "./app";
+import type { OpenApiContribution } from "./core/services";
+
+function baseSpec(): Response {
+  return Response.json({ openapi: "3.1.0", paths: { "/health": { get: {} } } });
+}
+
+function source(options: {
+  contributions: () => OpenApiContribution[];
+  routeCount?: () => number;
+  base?: () => Response;
+}): { base: Mock<() => Promise<Response>>; load: OpenApiDocumentLoader } {
+  const base = mock(async () => (options.base ?? baseSpec)());
+  const load = cachedOpenApiDocument({
+    routeCount: options.routeCount ?? (() => 1),
+    base,
+    contributions: async () => options.contributions(),
+  });
+  return { base, load };
+}
+
+describe("cachedOpenApiDocument", () => {
+  it("reuses the merged document while the inputs are unchanged", async () => {
+    const auth = { document: { paths: { "/sign-in": { post: {} } } }, pathPrefix: "/api/auth" };
+    const { base, load } = source({ contributions: () => [{ ...auth }] });
+
+    const first = await load();
+    const second = await load();
+
+    expect(second).toBe(first);
+    expect(first).toMatchObject({
+      paths: { "/health": { get: {} }, "/api/auth/sign-in": { post: {} } },
+    });
+    expect(base).toHaveBeenCalledTimes(1);
+  });
+
+  it("rebuilds when a contributor returns a new document", async () => {
+    let auth: OpenApiContribution = {
+      document: { paths: { "/sign-in": { post: {} } } },
+      pathPrefix: "/api/auth",
+    };
+    const { base, load } = source({ contributions: () => [auth] });
+
+    await load();
+    auth = { document: { paths: { "/passkey": { post: {} } } }, pathPrefix: "/api/auth" };
+    const rebuilt = await load();
+
+    expect(rebuilt).toMatchObject({ paths: { "/api/auth/passkey": { post: {} } } });
+    expect(rebuilt).not.toHaveProperty(["paths", "/api/auth/sign-in"]);
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+
+  it("rebuilds when routes are added", async () => {
+    let routes = 1;
+    const { base, load } = source({ contributions: () => [], routeCount: () => routes });
+
+    await load();
+    routes = 2;
+    await load();
+
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns a failed base response without caching it", async () => {
+    let fail = true;
+    const { base, load } = source({
+      contributions: () => [],
+      base: () => fail ? Response.json({ success: false }, { status: 503 }) : baseSpec(),
+    });
+
+    const failed = await load();
+    fail = false;
+    const recovered = await load();
+
+    if (!(failed instanceof Response)) throw new Error("Expected the failed base response");
+    expect(failed.status).toBe(503);
+    expect(recovered).toMatchObject({ openapi: "3.1.0" });
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+});

package/dist/templates/fullstack/apps/api/src/app.ts

@@ -8,9 +8,11 @@ import {
   appContext,
   createCoreServices,
   type AppPlugin,
+  type OpenApiContribution,
   type PodokitModule,
   type ServiceRegistry,
 } from "./core/services";
+import { isDatabaseUnavailable } from "./database/database";
 import { healthPlugin } from "./health/health.plugin";
 // podokit:begin:imports
 // podokit:end:imports
@@ -52,6 +54,47 @@ function mergeOpenApi(
   return { ...base, paths, components, tags };
 }
 
+export interface OpenApiDocumentSource {
+  routeCount: () => number;
+  base: () => Promise<Response>;
+  contributions: () => Promise<OpenApiContribution[]>;
+}
+
+export type OpenApiDocumentLoader = () => Promise<Record<string, unknown> | Response>;
+
+function sameContributions(left: OpenApiContribution[], right: OpenApiContribution[]): boolean {
+  return left.length === right.length && left.every((contribution, index) =>
+    contribution.document === right[index]?.document &&
+    contribution.pathPrefix === right[index]?.pathPrefix
+  );
+}
+
+/** Contributors return the same document object while their inputs are unchanged,
+ *  so identity plus the route count (the base spec's own cache key) identifies the
+ *  merged result without a staleness window. */
+export function cachedOpenApiDocument(source: OpenApiDocumentSource): OpenApiDocumentLoader {
+  let cached: {
+    routeCount: number;
+    contributions: OpenApiContribution[];
+    document: Record<string, unknown>;
+  } | undefined;
+  return async () => {
+    const contributions = await source.contributions();
+    const routeCount = source.routeCount();
+    if (
+      cached?.routeCount === routeCount &&
+      sameContributions(cached.contributions, contributions)
+    ) {
+      return cached.document;
+    }
+    const response = await source.base();
+    if (!response.ok) return response;
+    const document = mergeOpenApi(record(await response.json()), contributions);
+    cached = { routeCount, contributions, document };
+    return document;
+  };
+}
+
 function errorEnvelope(
   code: string,
   message: string,
@@ -124,6 +167,10 @@ const buildApp = (options: CreateAppOptions = {}) => {
         set.status = error.statusCode;
         return errorEnvelope(error.code, error.message, error.statusCode, path);
       }
+      if (isDatabaseUnavailable(error)) {
+        set.status = 503;
+        return errorEnvelope("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503, path);
+      }
       const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;
       set.status = statusCode;
       const publicCode = code === "NOT_FOUND"
@@ -144,11 +191,12 @@ const buildApp = (options: CreateAppOptions = {}) => {
     ...modules.flatMap((module) => module.plugin ? [module.plugin] : []),
   ];
   for (const plugin of plugins) app.use(plugin(context));
-  app.get("/api-docs-json", async () => {
-    const response = await app.handle(new Request("http://localhost/api-docs-elysia-json"));
-    const base = record(await response.json());
-    return mergeOpenApi(base, await context.openapi.contributions());
-  }, {
+  const openApiDocument = cachedOpenApiDocument({
+    routeCount: () => app.routes.length,
+    base: () => app.handle(new Request("http://localhost/api-docs-elysia-json")),
+    contributions: () => context.openapi.contributions(),
+  });
+  app.get("/api-docs-json", () => openApiDocument(), {
     detail: { hide: true },
   });
   app.onStop(() => { void services.close(); });

package/dist/templates/fullstack/apps/api/src/config/env.validation.ts

@@ -11,6 +11,12 @@ const schema = z.object({
   POSTGRES_USER: z.string().default("podokit"),
   POSTGRES_PASSWORD: z.string().default("podokit"),
   POSTGRES_DB: z.string().default("podokit"),
+  DB_POOL_MAX: z.coerce.number().int().positive().default(20),
+  DB_CONNECT_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
+  DB_IDLE_TIMEOUT_MS: z.coerce.number().int().nonnegative().default(30000),
+  DB_AUTH_POOL_MAX: z.coerce.number().int().positive().default(10),
+  READINESS_CHECK_TIMEOUT_MS: z.coerce.number().int().positive().default(800),
+  READINESS_CACHE_MS: z.coerce.number().int().nonnegative().default(2000),
 });
 
 export type AppEnv = z.infer<typeof schema>;

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -35,9 +35,12 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "POST /account/profile-image",
     "DELETE /account/profile-image",
     "GET /profile-images/{fileName}",
+    "GET /admin/sessions",
+    "DELETE /admin/sessions/{id}",
+    "GET /admin/users",
   ],
   "api-key-auth": ["GET /machine/ping"],
-  "audit-log": ["GET /audit-logs"],
+  "audit-log": ["GET /audit-logs", "GET /audit-logs/actions"],
   analytics: [
     "GET /analytics/config",
     "GET /admin/analytics/config",
@@ -70,6 +73,12 @@ const MODULE_ROUTES: Record<string, string[]> = {
   bullmq: ["POST /jobs", "GET /jobs/{id}"],
   "file-upload": ["POST /files", "GET /files/{key}/url"],
   "job-progress": ["POST /progress"],
+  "object-storage-local": [
+    "GET /files/content/*",
+    "PUT /storage/{key}",
+    "GET /storage/{key}",
+    "GET /storage/{key}/presigned",
+  ],
   "object-storage-s3": [
     "PUT /storage/{key}",
     "GET /storage/{key}",

package/dist/templates/fullstack/apps/api/src/core/services.spec.ts

@@ -1,11 +1,20 @@
 import { describe, expect, test } from "bun:test";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { validateEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
 import {
   AccessPolicy,
+  createCoreServices,
   OpenApiRegistry,
+  REQUEST_IDENTITY,
   RequestGuardRegistry,
   ServiceRegistry,
 } from "./services";
 
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
 describe("ServiceRegistry", () => {
   test("awaits startup in registration order and starts only once", async () => {
     const registry = new ServiceRegistry();
@@ -88,3 +97,24 @@ describe("OpenApiRegistry", () => {
     expect(() => registry.register("auth", () => ({ document: {} }))).toThrow("already exists");
   });
 });
+
+describe("RequestIdentity", () => {
+  test("treats every request as anonymous until an auth module overrides it", async () => {
+    const services = createCoreServices(validateEnv({
+      NODE_ENV: "test",
+      DATABASE_URL: databaseProvider() === "sqlite"
+        ? "sqlite://:memory:"
+        : "postgres://podokit:podokit@localhost:5432/podokit",
+    }));
+    const identity = services.resolve(REQUEST_IDENTITY);
+    const request = new Request("http://localhost/todos");
+    try {
+      expect(await identity.userId(request)).toBeUndefined();
+      expect(await identity.isAdmin(request)).toBe(false);
+      expect(await identity.roles(request)).toEqual([]);
+      expect(await identity.activeOrganizationId(request)).toBeUndefined();
+    } finally {
+      await services.close();
+    }
+  });
+});