@podosoft/podokit 1.2.0 → 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/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/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/core/api-contract.ts

@@ -37,6 +37,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "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", "GET /audit-logs/actions"],

package/dist/templates/fullstack/apps/api/src/database/data-source.spec.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "bun:test";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+// SQLite applications migrate with the Bun SQLite migrator, not this TypeORM source.
+describe.skipIf(databaseProvider() !== "postgres")("migration data source", () => {
+  it("runs each migration in its own transaction so one can build indexes concurrently", async () => {
+    const { dataSourceOptions } = await import("./data-source.js");
+    expect(dataSourceOptions.migrationsTransactionMode).toBe("each");
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/data-source.ts

@@ -15,6 +15,9 @@ const migrations = existsSync(compiledMigrations)
 const commonOptions = {
   entities: [],
   migrations,
+  // One transaction per migration, so a migration can set `transaction = false`
+  // for statements such as CREATE INDEX CONCURRENTLY.
+  migrationsTransactionMode: "each" as const,
   synchronize: false,
 };
 

package/dist/templates/fullstack/apps/api/src/database/migrate.ts

@@ -25,7 +25,7 @@ async function migrate(): Promise<void> {
   await dataSource.initialize();
   try {
     if (process.argv.includes("--revert")) await dataSource.undoLastMigration({ transaction: "all" });
-    else await dataSource.runMigrations({ transaction: "all" });
+    else await dataSource.runMigrations();
   } finally {
     await dataSource.destroy();
   }

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/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/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;
   });
 }

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-sessions/admin-sessions.migration.spec.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import type { QueryRunner } from "typeorm";
+import { revertLatestSqliteMigration, runSqliteMigrations } from "../database/sqlite-migrator";
+import { IndexSessionCreatedAt1792060000000 } from "../migrations/1792060000000-IndexSessionCreatedAt";
+
+function runner(type: "postgres" | "better-sqlite3", queries: string[], invalid = false): QueryRunner {
+  return {
+    connection: { options: { type } },
+    query: (sql: string): Promise<unknown[]> => {
+      queries.push(sql);
+      return Promise.resolve(invalid && sql.includes("indisvalid") ? [{ invalid: 1 }] : []);
+    },
+  } as unknown as QueryRunner;
+}
+
+// Finalized at once: an open statement keeps SQLite from dropping an index.
+function rows<Row>(database: Database, sql: string): Row[] {
+  const statement = database.prepare<Row, []>(sql);
+  try {
+    return statement.all();
+  } finally {
+    statement.finalize();
+  }
+}
+
+const CREATE = 'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_session_createdAt_id" ON "session" ("createdAt", "id")';
+
+describe("admin session list index migration", () => {
+  it("builds the PostgreSQL index concurrently outside a transaction", async () => {
+    const migration = new IndexSessionCreatedAt1792060000000();
+    expect(migration.transaction).toBe(false);
+    const up: string[] = [];
+    await migration.up(runner("postgres", up));
+    expect(up).toEqual([
+      "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid",
+      CREATE,
+    ]);
+
+    const down: string[] = [];
+    await migration.down(runner("postgres", down));
+    expect(down).toEqual(['DROP INDEX IF EXISTS "IDX_session_createdAt_id"']);
+  });
+
+  it("rebuilds an invalid index left by an interrupted build", async () => {
+    const up: string[] = [];
+    await new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, true));
+    expect(up.slice(1)).toEqual(['DROP INDEX CONCURRENTLY IF EXISTS "IDX_session_createdAt_id"', CREATE]);
+  });
+
+  it("serves the newest-first session page on SQLite and reverts", async () => {
+    const database = new Database(":memory:");
+    try {
+      database.run(`CREATE TABLE "session" (
+        "id" text PRIMARY KEY, "userId" text NOT NULL, "token" text NOT NULL,
+        "expiresAt" date NOT NULL, "createdAt" date NOT NULL, "updatedAt" date NOT NULL
+      )`);
+      const migrations = [{ timestamp: 1792060000000, migration: new IndexSessionCreatedAt1792060000000() }];
+      await runSqliteMigrations(database, migrations);
+      const plan = rows<{ detail: string }>(
+        database,
+        `EXPLAIN QUERY PLAN SELECT "id" FROM "session" WHERE "expiresAt" > '2026' ORDER BY "createdAt" DESC, "id" DESC LIMIT 16`,
+      ).map((row) => row.detail).join("\n");
+      expect(plan).toContain("IDX_session_createdAt_id");
+      expect(plan).not.toContain("TEMP B-TREE");
+
+      expect(await revertLatestSqliteMigration(database, migrations)).toBe(true);
+      expect(rows(database, `SELECT "name" FROM "sqlite_master" WHERE "type" = 'index' AND "name" LIKE 'IDX_%'`))
+        .toEqual([]);
+    } finally {
+      database.close();
+    }
+  });
+});