@podosoft/podokit 1.4.0 → 1.4.2

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/deploy-compose-render.js

@@ -311,7 +311,8 @@ function renderComposeDocument(profile, release, images, stateDigest, workerComm
         healthcheckPath: "/health/ready",
     }));
     services.push(applicationService(profile, "web", images.web, release, stateDigest, {
-        healthcheckPath: "/",
+        // The web server's own route: an API outage must not mark it unhealthy.
+        healthcheckPath: "/healthz",
         publish: !hasGateway,
     }));
     if (hasGateway) {

package/dist/deploy-render.js

@@ -386,8 +386,10 @@ 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;
+// Every rendered API and web probe allows 2 s instead of the Kubernetes default
+// of 1 s: above the API's 800 ms per-check readiness bound, and enough for a busy
+// web server.
+const 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;
@@ -399,25 +401,29 @@ function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeC
         ? `          readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             periodSeconds: 5
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           startupProbe:
             httpGet: { path: /health, port: 3000 }
             failureThreshold: 30
             periodSeconds: 2
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
 `
-        : `          readinessProbe:
-            httpGet: { path: /, port: 3000 }
+        : // The web server's own route: an API outage must not take the web pods
+            // out of service or restart them.
+            `          readinessProbe:
+            httpGet: { path: /healthz, port: 3000 }
             periodSeconds: 5
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           livenessProbe:
-            httpGet: { path: /, port: 3000 }
+            httpGet: { path: /healthz, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
 `;
     return `apiVersion: apps/v1
 kind: Deployment

package/dist/lockfile.d.ts

@@ -82,7 +82,14 @@ export declare function podokitVersion(): string;
 export declare function matchGlob(path: string, glob: string): boolean;
 /** Classify a file's ownership tier. See ADR-0010 priority order. */
 export declare function classifyTier(relPath: string, content: string | Buffer, ownedGlobs: string[], managedOverrides?: string[]): Tier;
-/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+/**
+ * Whether a path is a local environment file such as `.env`, `.env.docker` or
+ * `apps/api/.env.local`. Git ignores these and they hold secrets, so the lock
+ * never records them; the committed `*.example` files are project files.
+ */
+export declare function isLocalEnvFile(relPath: string): boolean;
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs
+ *  and local environment files. */
 export declare function walkFiles(projectRoot: string, prefix?: string): string[];
 /** Recompute the files.lock by hashing and classifying every project file. */
 export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[], managedOverrides?: string[]): FilesLock;

package/dist/lockfile.js

@@ -11,6 +11,7 @@ exports.writeFilesLock = writeFilesLock;
 exports.podokitVersion = podokitVersion;
 exports.matchGlob = matchGlob;
 exports.classifyTier = classifyTier;
+exports.isLocalEnvFile = isLocalEnvFile;
 exports.walkFiles = walkFiles;
 exports.computeFilesLock = computeFilesLock;
 exports.readFilesLock = readFilesLock;
@@ -57,6 +58,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",
@@ -166,7 +169,17 @@ function classifyTier(relPath, content, ownedGlobs, managedOverrides = []) {
         return "assembled";
     return "managed";
 }
-/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+/**
+ * Whether a path is a local environment file such as `.env`, `.env.docker` or
+ * `apps/api/.env.local`. Git ignores these and they hold secrets, so the lock
+ * never records them; the committed `*.example` files are project files.
+ */
+function isLocalEnvFile(relPath) {
+    const name = relPath.slice(relPath.lastIndexOf("/") + 1);
+    return (name === ".env" || name.startsWith(".env.")) && !name.endsWith(".example");
+}
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs
+ *  and local environment files. */
 function walkFiles(projectRoot, prefix = "") {
     const out = [];
     for (const entry of (0, node_fs_1.readdirSync)((0, node_path_1.join)(projectRoot, prefix))) {
@@ -176,7 +189,7 @@ function walkFiles(projectRoot, prefix = "") {
         if ((0, node_fs_1.statSync)((0, node_path_1.join)(projectRoot, rel)).isDirectory()) {
             out.push(...walkFiles(projectRoot, rel));
         }
-        else {
+        else if (!isLocalEnvFile(rel)) {
             out.push(rel);
         }
     }
@@ -196,7 +209,13 @@ function computeFilesLock(projectRoot, ownedGlobs, managedOverrides = []) {
 }
 function readFilesLock(projectRoot) {
     const file = filesLockPath(projectRoot);
-    return (0, node_fs_1.existsSync)(file) ? JSON.parse((0, node_fs_1.readFileSync)(file, "utf8")) : null;
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    const lock = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    // Earlier versions recorded local env files. Leaving them out here keeps
+    // update from treating them as PodoKit files, and the next write drops them.
+    const files = Object.entries(lock.files).filter(([path]) => !isLocalEnvFile(path));
+    return { ...lock, files: Object.fromEntries(files) };
 }
 /**
  * Compare the current disk against the lock: report managed/assembled files the

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,29 @@ 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.
+- Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
+  (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
+  response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
+  `GET /health` stops answering too, calls throw `BackendUnavailableError` and the
+  proxy answers 503 `BACKEND_UNAVAILABLE` at once until it answers again. Handle
+  any non-`ApiError` failure in a load function as a temporary outage. Raising
+  the API's `apiServerOptions.idleTimeout` needs a matching
+  `BACKEND_PROXY_TIMEOUT_MS`.
+- `GET /healthz` (`apps/web/src/routes/healthz/+server.ts`) is the web server's own
+  health route for the Kubernetes probes, the Compose healthcheck, and the image
+  `HEALTHCHECK`. Keep it free of API calls, so an API outage does not take the web
+  out of service.
+- 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`
@@ -131,7 +131,7 @@ Run each service in a separate terminal from the project root:
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5001
+- Web: http://localhost:5001 — its own health at `/healthz`, which never calls the API
 
 ## Database & migrations
 
@@ -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,29 @@
+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);
+}
+// Run in the API directory wherever this was started from: Bun reads decorator
+// settings from the tsconfig.json of the working directory, and the data source
+// finds .env and the migrations relative to it.
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(target)], {
+  cwd: fileURLToPath(new URL("..", import.meta.url)),
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exitCode = await subprocess.exited;

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

@@ -13,5 +13,7 @@ export const extensionModules: PodokitModule[] = [];
 // Bun server options such as a larger request body limit for uploads, for
 // example { maxRequestBodySize: 1024 ** 3, idleTimeout: 120 }. Values set here
 // win over API_MAX_REQUEST_BODY_SIZE; a function receives the validated
-// environment instead: (env) => ({ maxRequestBodySize: ... }).
+// environment instead: (env) => ({ maxRequestBodySize: ... }). A longer
+// idleTimeout also needs BACKEND_PROXY_TIMEOUT_MS on the web server, which stops
+// waiting for response headers after 30 seconds by default.
 export const apiServerOptions: ApiServerOptionsSource = {};

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

@@ -1,8 +1,10 @@
 import { SQL } from "bun";
 import { describe, expect, it } from "bun:test";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { connect, createServer, type AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { QueryFailedError } from "typeorm";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import {
@@ -183,6 +185,61 @@ 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("recognizes host lookup failures from Bun and Node", () => {
+    // Bun reports an unknown host as ENOTFOUND and a lookup timeout as ETIMEOUT;
+    // Node reports a lookup it could not complete as EAI_AGAIN.
+    for (const code of ["ENOTFOUND", "ETIMEOUT", "EAI_AGAIN"]) {
+      expect(isDatabaseUnavailable(Object.assign(new Error(`getaddrinfo ${code} db`), { code }))).toBe(true);
+    }
+  });
+
+  it("recognizes a pg client that was ended or broke while a query waited", () => {
+    for (const message of [
+      "Connection terminated",
+      "Client was closed and is not queryable",
+      "Client has encountered a connection error and is not queryable",
+    ]) {
+      expect(isDatabaseUnavailable(new Error(message))).toBe(true);
+    }
+  });
+
+  it("follows the per-address errors of a connection that tried several addresses", () => {
+    const refused = (address: string): Error =>
+      Object.assign(new Error(`connect ECONNREFUSED ${address}:5432`), { code: "ECONNREFUSED" });
+    expect(isDatabaseUnavailable(new AggregateError([refused("::1"), refused("127.0.0.1")]))).toBe(true);
+    expect(isDatabaseUnavailable(new AggregateError([new Error("first"), new Error("second")]))).toBe(false);
+  });
+
+  it("follows the driver error that TypeORM wraps", () => {
+    const failed = (driverError: Error): QueryFailedError => new QueryFailedError("SELECT 1", [], driverError);
+    expect(isDatabaseUnavailable(failed(new Error("Connection terminated")))).toBe(true);
+    const refused = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:5432"), { code: "ECONNREFUSED" });
+    expect(isDatabaseUnavailable(failed(new AggregateError([refused])))).toBe(true);
+    expect(isDatabaseUnavailable(failed(Object.assign(new Error("duplicate key"), { code: "23505" })))).toBe(false);
+  });
+
+  it("stops at an error that wraps itself", () => {
+    const loop = new Error("outer");
+    loop.cause = new Error("inner", { cause: loop });
+    expect(isDatabaseUnavailable(loop)).toBe(false);
+  });
+
   it("leaves query and application errors alone", () => {
     expect(isDatabaseUnavailable(new SQL.PostgresError("syntax error", { code: "ERR_POSTGRES_SYNTAX_ERROR" })))
       .toBe(false);
@@ -190,10 +247,37 @@ 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);
   });
 
+  it("recognizes a real lookup of a host that does not exist", async () => {
+    // .invalid never resolves (RFC 2606). A resolver that does not answer at all
+    // fails with ETIMEOUT after about 16 seconds, which is recognized too.
+    const error: unknown = await fetch("http://database.invalid/").then(() => undefined, (reason: unknown) => reason);
+    expect(isDatabaseUnavailable(error)).toBe(true);
+  }, 30_000);
+
+  it("recognizes a real refused connection to localhost", async () => {
+    const server = createServer();
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as AddressInfo;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    // localhost may resolve to ::1 and 127.0.0.1; a client that tries both fails
+    // with an AggregateError of the two refusals.
+    const error = await new Promise<unknown>((resolve) => {
+      const socket = connect({ host: "localhost", port });
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(undefined);
+      });
+      socket.once("error", resolve);
+    });
+    expect(isDatabaseUnavailable(error)).toBe(true);
+  });
+
   it("recognizes a real Bun SQL connection timeout", async () => {
     // Accepts the TCP connection and never answers, like an overloaded server.
     const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });

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

@@ -75,16 +75,61 @@ 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",
+  // The client was ended, for example by a pool replacement, while a query waited.
+  "Connection terminated",
+  "Client was closed and is not queryable",
+  "Client has encountered a connection error and is not queryable",
   "Query read timeout",
 ]);
+// Socket and host lookup errors from a pg client whose server is gone or
+// unreachable. Bun reports a lookup timeout as ETIMEOUT, Node as EAI_AGAIN.
+const UNAVAILABLE_SOCKET_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+  "ENOTFOUND",
+  "ETIMEOUT",
+  "EAI_AGAIN",
+]);
+// 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));
+}
+
+function signalsUnavailable(error: Error): boolean {
+  if (error instanceof SQL.PostgresError) {
+    if (UNAVAILABLE_SQL_CODES.has(error.code) || unavailableSqlState(error.errno)) return true;
+  } else {
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === "string" && (UNAVAILABLE_SOCKET_CODES.has(code) || unavailableSqlState(code))) return true;
+  }
+  return UNAVAILABLE_PG_MESSAGES.has(error.message);
+}
+
+// Bounds the walk over wrapped errors, which may form a cycle.
+const MAX_WRAPPED_ERRORS = 16;
 
 /** 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 (UNAVAILABLE_PG_MESSAGES.has(current.message)) return true;
-    current = current.cause;
+  const pending: unknown[] = [error];
+  const seen = new Set<Error>();
+  while (pending.length > 0 && seen.size < MAX_WRAPPED_ERRORS) {
+    const current = pending.shift();
+    if (!(current instanceof Error) || seen.has(current)) continue;
+    seen.add(current);
+    if (signalsUnavailable(current)) return true;
+    // TypeORM's QueryFailedError keeps the driver's error as `driverError`, and
+    // a connection that tried several addresses, such as IPv6 and IPv4 for
+    // localhost, fails with an AggregateError of the per-address errors.
+    pending.push(current.cause, (current as { driverError?: unknown }).driverError);
+    if (current instanceof AggregateError) pending.push(...current.errors);
   }
   return false;
 }

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,118 @@
+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;
+}
+
+interface LaunchOptions {
+  /** Starts the launcher from the directory above the API, like a repository root. */
+  fromParent?: boolean;
+  files?: Record<string, string>;
+}
+
+/** Runs the migrate:all launcher in an API layout whose entries print their own path. */
+async function launch(entries: string[], nodeEnv: string, body = "", options: LaunchOptions = {}): Promise<Launch> {
+  const parent = mkdtempSync(join(tmpdir(), "run-migrations-"));
+  const root = join(parent, "api");
+  try {
+    mkdirSync(join(root, "scripts"), { recursive: true });
+    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}`);
+    }
+    for (const [path, content] of Object.entries(options.files ?? {})) {
+      mkdirSync(dirname(join(root, path)), { recursive: true });
+      writeFileSync(join(root, path), content);
+    }
+    const child = Bun.spawn([process.execPath, options.fromParent ? "api/scripts/run-migrations.mjs" : "scripts/run-migrations.mjs"], {
+      cwd: options.fromParent ? parent : 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(parent, { 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("runs the migration in the API directory when started from elsewhere", async () => {
+    const apiRoot = 'realpathSync(join(import.meta.dir, "../.."))';
+    const result = await launch(
+      ["src/database/migrate.ts"],
+      "development",
+      `import { realpathSync } from "node:fs";\nimport { join } from "node:path";\n` +
+        `console.log(realpathSync(process.cwd()) === ${apiRoot});\n`,
+      { fromParent: true },
+    );
+    expect(result).toMatchObject({ code: 0, stdout: "src/database/migrate.ts\ntrue" });
+  });
+
+  it("applies the API's decorator settings when started from elsewhere", async () => {
+    // TypeORM entities need legacy decorators, which Bun takes from the
+    // tsconfig.json of the working directory rather than of the source file.
+    const result = await launch(
+      ["src/database/migrate.ts"],
+      "development",
+      'await import("../entity.ts");\n',
+      {
+        fromParent: true,
+        files: {
+          "tsconfig.json": JSON.stringify({ compilerOptions: { experimentalDecorators: true, emitDecoratorMetadata: true } }),
+          "src/entity.ts": [
+            "const Column = (): PropertyDecorator => (target) => console.log(typeof target);",
+            "export class Item {",
+            "  @Column()",
+            "  name!: string;",
+            "}",
+            "",
+          ].join("\n"),
+        },
+      },
+    );
+    expect(result).toMatchObject({ code: 0, stdout: "src/database/migrate.ts\nobject" });
+  });
+
+  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/Dockerfile

@@ -37,5 +37,5 @@ WORKDIR /app/apps/web
 USER bun
 EXPOSE 3000
 HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
-  CMD bun -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? '3000') + '/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+  CMD bun -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? '3000') + '/healthz').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
 CMD ["bun", "./build"]