@podosoft/podokit 1.4.0 → 1.4.1

package/README.md

@@ -66,7 +66,7 @@ bunx --bun @podosoft/podokit provider set events memory --apply
 bunx --bun @podosoft/podokit provider set jobs local --apply
 bun install
 cp .env.example .env
-bun run --cwd apps/api migration:run
+bun run --cwd apps/api migrate:all
 ```
 
 Run `bun run --cwd apps/api dev` and `bun run --cwd apps/web dev` in separate

package/dist/lockfile.js

@@ -57,6 +57,8 @@ exports.DEFAULT_OWNED_GLOBS = [
     // Owned additions to the managed /api proxy's header lists and body limits.
     "apps/web/src/lib/server/proxy-headers.ts",
     "apps/web/src/lib/server/body-limits.ts",
+    // Owned fallback page SvelteKit serves when the root layout or a hook fails.
+    "apps/web/src/error.html",
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
     "CLAUDE.md",

package/dist/templates/fullstack/AGENTS.md

@@ -27,7 +27,7 @@ Provider selection does not migrate or delete existing data.
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
@@ -50,10 +50,17 @@ Merge added module settings from `.env.example` into an existing `.env`.
   `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
   `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
   uploads larger than it must use a direct API path (`apiPaths`) instead.
+- When the root layout or a server hook fails, such as with 503 while the API is
+  down, SvelteKit serves the app-owned `apps/web/src/error.html`. It is plain HTML
+  with inline styles: no components, app CSS, scripts, or assets, and only the
+  `%sveltekit.status%` and `%sveltekit.error.message%` placeholders.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
-- Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
-- When `auth` is installed, run `{{apiRun}} migrate:all` for Better Auth and application tables.
+- Set up the database and apply later migrations, including after adding a module, with
+  `{{apiRun}} migrate:all` (PostgreSQL or SQLite). With `auth` installed it applies the
+  Better Auth schema before the application migrations. `{{apiRun}} migration:run` runs
+  only the application migrations and never creates Better Auth tables;
+  `{{apiRun}} migration:revert` reverts the latest application migration.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,

package/dist/templates/fullstack/README.md

@@ -82,7 +82,7 @@ Run lifecycle and container commands from a second terminal:
 {{packageExecutor}} @podosoft/podokit dev up -d # detached stack without source watching
 {{packageExecutor}} @podosoft/podokit dev ps
 {{packageExecutor}} @podosoft/podokit dev logs
-{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migration:run
+{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migrate:all
 {{packageExecutor}} @podosoft/podokit dev down
 ```
 
@@ -113,7 +113,7 @@ web and API processes on the host. Prepare the project first:
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 ```
 
 For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
@@ -140,12 +140,15 @@ runs PostgreSQL migrations; SQLite uses the local migration runner. Add a
 numbered migration under `apps/api/src/migrations`, then run it:
 
 ```bash
-{{apiRun}} migration:run
+{{apiRun}} migrate:all        # set up the database and apply new migrations
+{{apiRun}} migration:revert   # roll back the last application migration
 ```
 
-When `auth` is installed, use `{{apiRun}} migrate:all` to create or update both
-Better Auth and application tables. Set the module's required environment
-values before migrating.
+`migrate:all` is the one command for setup, after adding a module, and in
+production. When `auth` is installed, it applies the Better Auth schema before
+the application migrations, so set the module's required environment values
+first. `{{apiRun}} migration:run` runs only the application migrations and
+never creates Better Auth tables.
 
 Want a worked example? Generate the `todo` template instead:
 `{{packageExecutor}} @podosoft/podokit create my-app --template todo`.

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

@@ -9,7 +9,7 @@
     "lint": "bunx --bun tsc -p tsconfig.json --noEmit",
     "test": "bun test src",
     "contract": "bun scripts/verify-api-contract.ts",
-    "migrate:all": "bun dist/database/migrate.js",
+    "migrate:all": "bun scripts/run-migrations.mjs",
     "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
     "migration:run": "bun src/database/migrate.ts",
     "migration:revert": "bun src/database/migrate.ts --revert",

package/dist/templates/fullstack/apps/api/scripts/run-migrations.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// Production images ship only the compiled output.
+function entry(name) {
+  const compiled = new URL(`../dist/${name}.js`, import.meta.url);
+  if (process.env.NODE_ENV === "production" && existsSync(compiled)) return compiled;
+  const source = new URL(`../src/${name}.ts`, import.meta.url);
+  return existsSync(source) ? source : null;
+}
+
+// The auth module adds src/migrate.ts, which applies the Better Auth schema
+// before it runs the application migrations.
+const target = entry("migrate") ?? entry("database/migrate");
+if (!target) {
+  process.stderr.write("Run database migrations failed: no migration entry in src or dist\n");
+  process.exit(1);
+}
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(target)], {
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exitCode = await subprocess.exited;

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

@@ -183,6 +183,22 @@ describe("isDatabaseUnavailable", () => {
     expect(isDatabaseUnavailable(new Error("Failed to get session", { cause: acquire }))).toBe(true);
   });
 
+  it("recognizes refused, dropped, and shut-down connections from pg and Bun SQL", () => {
+    const socket = (code: string): Error => Object.assign(new Error(`connect ${code}`), { code });
+    const server = (code: string): Error => Object.assign(new Error("server error"), { code });
+    for (const code of ["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "EHOSTUNREACH", "ENETUNREACH", "EPIPE"]) {
+      expect(isDatabaseUnavailable(socket(code))).toBe(true);
+    }
+    expect(isDatabaseUnavailable(new Error("Connection terminated unexpectedly"))).toBe(true);
+    for (const code of ["57P01", "57P02", "57P03", "08006", "08P01"]) {
+      expect(isDatabaseUnavailable(server(code))).toBe(true);
+      expect(
+        isDatabaseUnavailable(new SQL.PostgresError("server error", { code: "ERR_POSTGRES_SERVER_ERROR", errno: code })),
+      ).toBe(true);
+    }
+    expect(isDatabaseUnavailable(new Error("Failed to save", { cause: socket("ECONNREFUSED") }))).toBe(true);
+  });
+
   it("leaves query and application errors alone", () => {
     expect(isDatabaseUnavailable(new SQL.PostgresError("syntax error", { code: "ERR_POSTGRES_SYNTAX_ERROR" })))
       .toBe(false);
@@ -190,6 +206,8 @@ describe("isDatabaseUnavailable", () => {
       isDatabaseUnavailable(new SQL.PostgresError("duplicate key", { code: "ERR_POSTGRES_SERVER_ERROR", errno: "23505" })),
     ).toBe(false);
     expect(isDatabaseUnavailable(new Error("timeout"))).toBe(false);
+    expect(isDatabaseUnavailable(Object.assign(new Error("duplicate key"), { code: "23505" }))).toBe(false);
+    expect(isDatabaseUnavailable(Object.assign(new Error("not found"), { code: "ENOENT" }))).toBe(false);
     expect(isDatabaseUnavailable("ERR_POSTGRES_CONNECTION_TIMEOUT")).toBe(false);
     expect(isDatabaseUnavailable(undefined)).toBe(false);
   });

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

@@ -75,14 +75,36 @@ const UNAVAILABLE_SQL_CODES = new Set([
 const UNAVAILABLE_PG_MESSAGES = new Set([
   "timeout exceeded when trying to connect",
   "Connection terminated due to connection timeout",
+  "Connection terminated unexpectedly",
   "Query read timeout",
 ]);
+// Socket errors from a pg client whose server is gone or unreachable.
+const UNAVAILABLE_SOCKET_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+]);
+// SQLSTATEs for a server shutting down or refusing connections (class 57P) and
+// for broken connections (class 08); pg reports them as `code`, Bun SQL as `errno`.
+const UNAVAILABLE_SQLSTATES = new Set(["57P01", "57P02", "57P03"]);
+
+function unavailableSqlState(value: unknown): boolean {
+  return typeof value === "string" && (UNAVAILABLE_SQLSTATES.has(value) || /^08[0-9A-Z]{3}$/.test(value));
+}
 
 /** Whether an error, or one it wraps, means the database is unavailable rather than the request being wrong. */
 export function isDatabaseUnavailable(error: unknown): boolean {
   let current: unknown = error;
   for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
-    if (current instanceof SQL.PostgresError && UNAVAILABLE_SQL_CODES.has(current.code)) return true;
+    if (current instanceof SQL.PostgresError) {
+      if (UNAVAILABLE_SQL_CODES.has(current.code) || unavailableSqlState(current.errno)) return true;
+    } else {
+      const code = (current as { code?: unknown }).code;
+      if (typeof code === "string" && (UNAVAILABLE_SOCKET_CODES.has(code) || unavailableSqlState(code))) return true;
+    }
     if (UNAVAILABLE_PG_MESSAGES.has(current.message)) return true;
     current = current.cause;
   }

package/dist/templates/fullstack/apps/api/src/database/pool-guard.spec.ts

@@ -91,7 +91,7 @@ describe("PoolGuard", () => {
       await sql`CREATE TABLE item (id INTEGER PRIMARY KEY, name TEXT)`;
       await sql`INSERT INTO item ${sql([{ id: 1, name: "a" }, { id: 2, name: "b" }], "id", "name")}`;
       const filter = sql`WHERE "name" = ${"b"}`;
-      expect(await sql`SELECT "id" FROM item ${filter}`).toEqual([{ id: 2 }]);
+      expect(await sql<Array<{ id: number }>>`SELECT "id" FROM item ${filter}`).toEqual([{ id: 2 }]);
       expect(await sql`SELECT count(*) AS n FROM item`.values()).toEqual([[2]]);
       const names = await sql.begin(async (tx) => {
         await tx`UPDATE item SET "name" = 'c' WHERE "id" = 1`;
@@ -119,7 +119,7 @@ describe("PoolGuard", () => {
     expect(server.pools.map((pool) => pool.closed())).toEqual([true, false]);
 
     server.stalled = false;
-    expect(await guard.sql`SELECT 1`).toEqual([{ ok: 1 }]);
+    expect(await guard.sql<Array<{ ok: number }>>`SELECT 1`).toEqual([{ ok: 1 }]);
   });
 
   it("keeps a slow query running while the server answers", async () => {

package/dist/templates/fullstack/apps/api/src/database/run-migrations.spec.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "bun:test";
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+const LAUNCHER = join(__dirname, "../../scripts/run-migrations.mjs");
+
+interface Launch {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Runs the migrate:all launcher in an API layout whose entries print their own path. */
+async function launch(entries: string[], nodeEnv: string, body = ""): Promise<Launch> {
+  const root = mkdtempSync(join(tmpdir(), "run-migrations-"));
+  try {
+    mkdirSync(join(root, "scripts"));
+    cpSync(LAUNCHER, join(root, "scripts/run-migrations.mjs"));
+    for (const entry of entries) {
+      mkdirSync(dirname(join(root, entry)), { recursive: true });
+      writeFileSync(join(root, entry), `console.log(${JSON.stringify(entry)});\n${body}`);
+    }
+    const child = Bun.spawn([process.execPath, "scripts/run-migrations.mjs"], {
+      cwd: root,
+      env: { ...process.env, NODE_ENV: nodeEnv },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, stdout: stdout.trim(), stderr };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe("migrate:all launcher", () => {
+  it("runs the application migrations from source in development", async () => {
+    const result = await launch(["src/database/migrate.ts", "dist/database/migrate.js"], "development");
+    expect(result).toMatchObject({ code: 0, stdout: "src/database/migrate.ts" });
+  });
+
+  it("runs the compiled application migrations in production", async () => {
+    const result = await launch(["src/database/migrate.ts", "dist/database/migrate.js"], "production");
+    expect(result).toMatchObject({ code: 0, stdout: "dist/database/migrate.js" });
+  });
+
+  it("prefers the auth module's entry, which applies the Better Auth schema first", async () => {
+    expect(await launch(["src/migrate.ts", "src/database/migrate.ts"], "development"))
+      .toMatchObject({ code: 0, stdout: "src/migrate.ts" });
+    // A production image has only the compiled output.
+    expect(await launch(["dist/migrate.js", "dist/database/migrate.js"], "production"))
+      .toMatchObject({ code: 0, stdout: "dist/migrate.js" });
+  });
+
+  it("exits with the migration's status", async () => {
+    const result = await launch(["src/database/migrate.ts"], "development", "process.exit(3);\n");
+    expect(result.code).toBe(3);
+  });
+
+  it("fails when no migration entry exists", async () => {
+    const result = await launch([], "development");
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("no migration entry in src or dist");
+  });
+});

package/dist/templates/fullstack/apps/web/src/error.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>%sveltekit.status% %sveltekit.error.message%</title>
+    <!-- SvelteKit serves this page when the root layout or a server hook fails,
+         so it cannot use the app's styles, scripts, assets, or components. It
+         fills in only the status and the HTML-escaped error message. -->
+    <style>
+      :root {
+        --background: oklch(1 0 0);
+        --foreground: oklch(0.141 0.005 285.823);
+        --muted-foreground: oklch(0.552 0.016 285.938);
+        --border: oklch(0.92 0.004 286.32);
+      }
+
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --background: oklch(0.141 0.005 285.823);
+          --foreground: oklch(0.985 0 0);
+          --muted-foreground: oklch(0.705 0.015 286.067);
+          --border: oklch(1 0 0 / 15%);
+        }
+      }
+
+      body {
+        box-sizing: border-box;
+        display: grid;
+        min-height: 100vh;
+        margin: 0;
+        padding: 1.5rem;
+        place-items: center;
+        background: var(--background);
+        color: var(--foreground);
+        font-family: ui-sans-serif, system-ui, sans-serif;
+        line-height: 1.5;
+      }
+
+      main {
+        display: flex;
+        align-items: center;
+        gap: 1rem;
+        max-width: 32rem;
+      }
+
+      .status {
+        margin: 0;
+        color: var(--muted-foreground);
+        font-size: 2.25rem;
+        font-variant-numeric: tabular-nums;
+        font-weight: 600;
+        line-height: 1;
+      }
+
+      h1 {
+        margin: 0;
+        padding-left: 1rem;
+        border-left: 1px solid var(--border);
+        font-size: 1rem;
+        font-weight: 500;
+        overflow-wrap: anywhere;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <p class="status">%sveltekit.status%</p>
+      <h1>%sveltekit.error.message%</h1>
+    </main>
+  </body>
+</html>

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

@@ -4,11 +4,16 @@ 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 {
+function runner(
+  type: "postgres" | "better-sqlite3",
+  queries: string[],
+  { invalid = false, session = true }: { invalid?: boolean; session?: boolean } = {},
+): QueryRunner {
   return {
     connection: { options: { type } },
     query: (sql: string): Promise<unknown[]> => {
       queries.push(sql);
+      if (sql.includes("IS NOT NULL")) return Promise.resolve([{ exists: session }]);
       return Promise.resolve(invalid && sql.includes("indisvalid") ? [{ invalid: 1 }] : []);
     },
   } as unknown as QueryRunner;
@@ -25,6 +30,7 @@ function rows<Row>(database: Database, sql: string): Row[] {
 }
 
 const CREATE = 'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_session_createdAt_id" ON "session" ("createdAt", "id")';
+const SESSION_EXISTS = 'SELECT to_regclass($1) IS NOT NULL AS "exists"';
 
 describe("admin session list index migration", () => {
   it("builds the PostgreSQL index concurrently outside a transaction", async () => {
@@ -33,6 +39,7 @@ describe("admin session list index migration", () => {
     const up: string[] = [];
     await migration.up(runner("postgres", up));
     expect(up).toEqual([
+      SESSION_EXISTS,
       "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid",
       CREATE,
     ]);
@@ -44,8 +51,30 @@ describe("admin session list index migration", () => {
 
   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]);
+    await new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, { invalid: true }));
+    expect(up.slice(2)).toEqual(['DROP INDEX CONCURRENTLY IF EXISTS "IDX_session_createdAt_id"', CREATE]);
+  });
+
+  // `migration:run` runs only the application migrations, so on a new database
+  // Better Auth has not created its tables yet.
+  it("fails with the command that creates the Better Auth tables on PostgreSQL", async () => {
+    const up: string[] = [];
+    await expect(new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, { session: false })))
+      .rejects.toThrow('Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all"');
+    expect(up).toEqual([SESSION_EXISTS]);
+  });
+
+  it("fails with the command that creates the Better Auth tables on SQLite and records nothing", async () => {
+    const database = new Database(":memory:");
+    try {
+      const migrations = [{ timestamp: 1792060000000, migration: new IndexSessionCreatedAt1792060000000() }];
+      await expect(runSqliteMigrations(database, migrations)).rejects.toThrow(
+        'Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all"',
+      );
+      expect(rows(database, 'SELECT "name" FROM "migrations"')).toEqual([]);
+    } finally {
+      database.close();
+    }
   });
 
   it("serves the newest-first session page on SQLite and reverts", async () => {

package/dist/templates/modules/admin-dashboard/files/apps/api/src/migrations/1792060000000-IndexSessionCreatedAt.ts

@@ -5,6 +5,12 @@ import type { MigrationInterface, QueryRunner } from "typeorm";
 // so without this index every page sorts the whole session table.
 const INDEX = "IDX_session_createdAt_id";
 
+// Better Auth creates "session" in its own schema step. `migrate:all` runs that
+// step before the application migrations; `migration:run` does not.
+const MISSING_SESSION_TABLE =
+  'Better Auth has not created the "session" table yet. Run "bun run --cwd apps/api migrate:all", ' +
+  "which applies the Better Auth schema before the application migrations.";
+
 export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
   name = "IndexSessionCreatedAt1792060000000";
   // CONCURRENTLY cannot run inside a transaction block. The runner therefore
@@ -13,9 +19,21 @@ export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
 
   async up(queryRunner: QueryRunner): Promise<void> {
     if (queryRunner.connection.options.type !== "postgres") {
-      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`);
+      try {
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`);
+      } catch (error) {
+        if (error instanceof Error && /no such table: (?:main\.)?session$/.test(error.message)) {
+          throw new Error(MISSING_SESSION_TABLE, { cause: error });
+        }
+        throw error;
+      }
       return;
     }
+    const [session] = await queryRunner.query(
+      `SELECT to_regclass($1) IS NOT NULL AS "exists"`,
+      [`"session"`],
+    ) as Array<{ exists: boolean } | undefined>;
+    if (!session?.exists) throw new Error(MISSING_SESSION_TABLE);
     // Sign-ins keep writing sessions while the index builds. An interrupted
     // build leaves an invalid index that IF NOT EXISTS would keep.
     const invalid = await queryRunner.query(

package/dist/templates/modules/audit-log/module.manifest.json

@@ -34,7 +34,7 @@
     }
   ],
   "instructions": [
-    "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Run migrations to create the audit_logs table: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit(); use recordAuditLater() only for high-volume, non-security events.",
     "List entries newest first (admin session required): curl -i -b cookies.txt 'localhost:5002/audit-logs?limit=50' and pass the X-Next-Cursor header back as ?cursor= for the next page"
   ],

package/dist/templates/modules/auth/module.manifest.json

@@ -19,7 +19,6 @@
     "@types/pg": "^8.11.10"
   },
   "scripts": {
-    "migrate:all": "bun scripts/run-migrations.mjs",
     "auth:configure": "bun scripts/configure-auth.mjs"
   },
   "env": [

package/dist/templates/modules/file-upload/files/tests/api/chunked-uploads.api.spec.ts

@@ -77,12 +77,18 @@ test("chunked upload: parts, a retried part, resume status, and complete store t
     // Completing again returns the same result.
     expect(await (await ctx.post(`${uploads}/${upload.id}/complete`, { data: {} })).json()).toMatchObject({ key: result.key });
 
-    // S3 returns an absolute presigned URL; local storage a signed API path.
-    const download = await ctx.get(result.url.startsWith("/") ? `${apiBase}${result.url}` : result.url);
-    expect(download.status()).toBe(200);
-    const stored = await download.body();
-    expect(stored.byteLength).toBe(file.byteLength);
-    expect(sha256(stored)).toBe(sha256(file));
+    // Local storage returns a signed API path. S3 returns a URL signed for the API's
+    // S3 endpoint; a containerized dev stack signs an in-network host, so download it
+    // only when the runner was given that endpoint too. The completed size above
+    // comes from the stored object either way.
+    const local = result.url.startsWith("/");
+    if (local || process.env.S3_ENDPOINT) {
+      const download = await ctx.get(local ? `${apiBase}${result.url}` : result.url);
+      expect(download.status()).toBe(200);
+      const stored = await download.body();
+      expect(stored.byteLength).toBe(file.byteLength);
+      expect(sha256(stored)).toBe(sha256(file));
+    }
   } finally {
     await ctx.dispose();
   }

package/dist/templates/modules/file-upload/module.manifest.json

@@ -31,12 +31,12 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### file-upload\n- `POST /files` stores one multipart file under `uploads/<userId>/`; `GET /files/:key/url` presigns it for the owner or an administrator.\n- For large files use the resumable upload in the browser: `uploadFile(file, { onProgress, signal })` and `resumeUpload(id, file)` from `$lib/uploads`. They create a session (`POST /files/uploads`), send parts (`PUT /files/uploads/:id/parts/:n`, `application/octet-stream`, `Content-Length` equal to the part size; with `XMLHttpRequest` in the browser so `onProgress` reports bytes), retry failed parts honoring `Retry-After`, and complete (`POST /files/uploads/:id/complete`). `GET /files/uploads/:id` lists stored parts; `DELETE` cancels.\n- Upload sessions live in the database (`file_upload_sessions`, `file_upload_parts`), so any API replica serves any request; never keep upload state in memory. Run `{{apiRun}} migration:run{{apiWorkspaceArg}}` after adding the module.\n- Parts are larger than the web `BODY_SIZE_LIMIT`, so the gateway sends `/api/files/uploads/` straight to the API: `podo add` listed it in `.podokit/dev.json` `apiPaths` and each deployment profile's `exposure.apiPaths`, and `podo deploy init` adds it to new profiles. Keep it there.\n- POST bodies must be `application/json` and parts `application/octet-stream` (else 415 `UNSUPPORTED_MEDIA_TYPE`), and a browser `Origin` outside `CORS_ORIGIN` gets 403. Branch on `error.code`: `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_PART_SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `UPLOAD_COMPLETING`, `UPLOAD_EXPIRED`, `UPLOAD_ABORTED`.\n"
+      "text": "### file-upload\n- `POST /files` stores one multipart file under `uploads/<userId>/`; `GET /files/:key/url` presigns it for the owner or an administrator.\n- For large files use the resumable upload in the browser: `uploadFile(file, { onProgress, signal })` and `resumeUpload(id, file)` from `$lib/uploads`. They create a session (`POST /files/uploads`), send parts (`PUT /files/uploads/:id/parts/:n`, `application/octet-stream`, `Content-Length` equal to the part size; with `XMLHttpRequest` in the browser so `onProgress` reports bytes), retry failed parts honoring `Retry-After`, and complete (`POST /files/uploads/:id/complete`). `GET /files/uploads/:id` lists stored parts; `DELETE` cancels.\n- Upload sessions live in the database (`file_upload_sessions`, `file_upload_parts`), so any API replica serves any request; never keep upload state in memory. Run `{{apiRun}} migrate:all{{apiWorkspaceArg}}` after adding the module.\n- Parts are larger than the web `BODY_SIZE_LIMIT`, so the gateway sends `/api/files/uploads/` straight to the API: `podo add` listed it in `.podokit/dev.json` `apiPaths` and each deployment profile's `exposure.apiPaths`, and `podo deploy init` adds it to new profiles. Keep it there.\n- POST bodies must be `application/json` and parts `application/octet-stream` (else 415 `UNSUPPORTED_MEDIA_TYPE`), and a browser `Origin` outside `CORS_ORIGIN` gets 403. Branch on `error.code`: `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_PART_SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `UPLOAD_COMPLETING`, `UPLOAD_EXPIRED`, `UPLOAD_ABORTED`.\n"
     }
   ],
   "instructions": [
     "Configure the selected object-storage provider before uploading files.",
-    "Run migrations to create the upload session tables: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Run migrations to create the upload session tables: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Uploads are stored as uploads/<userId>/<uuid>-<name>. Add the auth module so every upload has an owner.",
     "Upload a file:  curl -b cookies.txt -F 'file=@./some.png' localhost:5002/files",
     "The response includes { key, url } — an S3 presigned URL or a signed local download URL.",

package/dist/templates/todo/AGENTS.md

@@ -27,7 +27,7 @@ Provider selection does not migrate or delete existing data.
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
@@ -50,10 +50,17 @@ Merge added module settings from `.env.example` into an existing `.env`.
   `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
   `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
   uploads larger than it must use a direct API path (`apiPaths`) instead.
+- When the root layout or a server hook fails, such as with 503 while the API is
+  down, SvelteKit serves the app-owned `apps/web/src/error.html`. It is plain HTML
+  with inline styles: no components, app CSS, scripts, or assets, and only the
+  `%sveltekit.status%` and `%sveltekit.error.message%` placeholders.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
-- Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
-- When `auth` is installed, run `{{apiRun}} migrate:all` for Better Auth and application tables.
+- Set up the database and apply later migrations, including after adding a module, with
+  `{{apiRun}} migrate:all` (PostgreSQL or SQLite). With `auth` installed it applies the
+  Better Auth schema before the application migrations. `{{apiRun}} migration:run` runs
+  only the application migrations and never creates Better Auth tables;
+  `{{apiRun}} migration:revert` reverts the latest application migration.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,

package/dist/templates/todo/README.md

@@ -78,7 +78,7 @@ defaults in the example and credentials only in `.env.docker`.
 In a second terminal, apply the included Todo migration and use the lifecycle helpers:
 
 ```bash
-{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migration:run
+{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migrate:all
 {{packageExecutor}} @podosoft/podokit dev url
 {{packageExecutor}} @podosoft/podokit dev up -d # detached stack without source watching
 {{packageExecutor}} @podosoft/podokit dev ps
@@ -113,7 +113,7 @@ web and API processes on the host. Prepare the project first:
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 ```
 
 For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
@@ -143,13 +143,15 @@ runs PostgreSQL migrations; SQLite uses the local migration runner. A sample
 Todo repository and initial migration are included.
 
 ```bash
-{{apiRun}} migration:run      # apply migrations
-{{apiRun}} migration:revert   # roll back the last one
+{{apiRun}} migrate:all        # set up the database and apply new migrations
+{{apiRun}} migration:revert   # roll back the last application migration
 ```
 
-When `auth` is installed, use `{{apiRun}} migrate:all` to create or update both
-Better Auth and application tables. Set the module's required environment
-values before migrating.
+`migrate:all` is the one command for setup, after adding a module, and in
+production. When `auth` is installed, it applies the Better Auth schema before
+the application migrations, so set the module's required environment values
+first. `{{apiRun}} migration:run` runs only the application migrations and
+never creates Better Auth tables.
 
 ## Deploy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {

package/dist/templates/modules/auth/files/apps/api/scripts/run-migrations.mjs

@@ -1,14 +0,0 @@
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-
-const compiledEntry = new URL("../dist/migrate.js", import.meta.url);
-const sourceEntry = new URL("../src/migrate.ts", import.meta.url);
-const useCompiled = process.env.NODE_ENV === "production" && existsSync(compiledEntry);
-const entry = useCompiled ? compiledEntry : sourceEntry;
-const subprocess = Bun.spawn([process.execPath, fileURLToPath(entry)], {
-  stdin: "inherit",
-  stdout: "inherit",
-  stderr: "inherit",
-});
-
-process.exitCode = await subprocess.exited;