@podosoft/podokit 0.15.0 → 0.16.0

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/health.controller.ts

@@ -1,10 +1,20 @@
 import { Controller, Get, ServiceUnavailableException } from "@nestjs/common";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource } from "typeorm";
+import { ReadinessService, type ReadinessStatus } from "./readiness.service";
+
+interface ReadinessResponse {
+  status: "ready";
+  db: "up";
+  checks: Record<string, ReadinessStatus>;
+}
 
 @Controller("health")
 export class HealthController {
-  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly readinessService: ReadinessService,
+  ) {}
 
   @Get()
   liveness(): { status: string; uptime: number; timestamp: string } {
@@ -12,12 +22,17 @@ export class HealthController {
   }
 
   @Get("ready")
-  async readiness(): Promise<{ status: string; db: string }> {
+  async readiness(): Promise<ReadinessResponse> {
+    let db: ReadinessStatus = "up";
     try {
       await this.dataSource.query("SELECT 1");
-      return { status: "ready", db: "up" };
     } catch {
-      throw new ServiceUnavailableException({ status: "degraded", db: "down" });
+      db = "down";
+    }
+    const checks = await this.readinessService.run();
+    if (db === "down" || Object.values(checks).includes("down")) {
+      throw new ServiceUnavailableException({ status: "degraded", db, checks });
     }
+    return { status: "ready", db: "up", checks };
   }
 }

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/health.module.ts

@@ -1,7 +1,11 @@
-import { Module } from "@nestjs/common";
+import { Global, Module } from "@nestjs/common";
 import { HealthController } from "./health.controller";
+import { ReadinessService } from "./readiness.service";
 
+@Global()
 @Module({
   controllers: [HealthController],
+  providers: [ReadinessService],
+  exports: [ReadinessService],
 })
 export class HealthModule {}

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/readiness.service.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "@jest/globals";
+import { ReadinessService } from "./readiness.service";
+
+describe("ReadinessService", () => {
+  it("runs registered checks and removes them with the returned callback", async () => {
+    const service = new ReadinessService();
+    const unregister = service.register("cache", () => Promise.resolve());
+    service.register("events", () => Promise.reject(new Error("unavailable")));
+
+    await expect(service.run()).resolves.toEqual({ cache: "up", events: "down" });
+    unregister();
+    await expect(service.run()).resolves.toEqual({ events: "down" });
+  });
+
+  it("rejects duplicate names", () => {
+    const service = new ReadinessService();
+    service.register("cache", () => Promise.resolve());
+    expect(() => service.register("cache", () => Promise.resolve())).toThrow(
+      'Readiness check "cache" is already registered',
+    );
+  });
+});

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/readiness.service.ts

@@ -0,0 +1,33 @@
+import { Injectable } from "@nestjs/common";
+
+export type ReadinessStatus = "up" | "down";
+export type ReadinessCheck = () => Promise<void>;
+
+@Injectable()
+export class ReadinessService {
+  private readonly checks = new Map<string, ReadinessCheck>();
+
+  register(name: string, check: ReadinessCheck): () => void {
+    if (this.checks.has(name)) {
+      throw new Error(`Readiness check "${name}" is already registered`);
+    }
+    this.checks.set(name, check);
+    return () => {
+      this.checks.delete(name);
+    };
+  }
+
+  async run(): Promise<Record<string, ReadinessStatus>> {
+    const results = await Promise.all(
+      [...this.checks].map(async ([name, check]): Promise<[string, ReadinessStatus]> => {
+        try {
+          await check();
+          return [name, "up"];
+        } catch {
+          return [name, "down"];
+        }
+      }),
+    );
+    return Object.fromEntries(results);
+  }
+}

package/dist/templates/fullstack-nest-svelte/apps/web/Dockerfile

@@ -19,11 +19,11 @@ ENV NODE_ENV=production
 # Keep the adapter-node proxy above the 2 MiB application upload policy so the
 # API can return stable validation codes after accounting for multipart framing.
 ENV BODY_SIZE_LIMIT=3M
-RUN addgroup -S app && adduser -S app -G app
+RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/web ./apps/web
 COPY --from=build /app/apps/web/build ./apps/web/build
 WORKDIR /app/apps/web
-USER app
+USER 100:101
 EXPOSE 3000
 CMD ["node", "build"]

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -1,16 +1,14 @@
 # Containerized development environment.
 #
-#   podo dev watch                                                # core stack
-#   podo dev watch --profile cache --profile storage \
-#     --profile queue                                             # with modules
+#   podo dev watch   # installed modules activate their required profiles
 #
 # A user-level PodoKit gateway owns loopback :80 and routes each *.localhost host
 # to this stack. The legacy per-project Traefik service is opt-in only.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
-# Core services (traefik, web, api, postgres) always run. Module-specific
-# services are behind profiles — enable the ones your app uses:
+# Core services (traefik, web, api, postgres) always run. PodoKit activates
+# module-specific profiles from .podokit/manifest.json:
 #   --profile cache    redis    (redis / rate-limit / bullmq modules)
 #   --profile storage  minio    (object-storage-s3 / file-upload modules)
 #   --profile queue    worker   (bullmq / job-progress modules)

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: podokit-deploy
+description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit deployment profile and confirmation hash. Use when an agent needs to initialize a .podokit/deploy profile, diagnose a target cluster, preview a release, perform an approved deployment, inspect rollout state, verify public endpoints, or prepare an application rollback.
+---
+
+# Deploy a PodoKit application
+
+1. Run `npx @podosoft/podokit status`, `npx @podosoft/podokit diff`, and `npx @podosoft/podokit doctor`. Stop if managed-file conflicts or unsupported framework versions could make the image unreliable.
+2. Read [references/profile.md](references/profile.md) before creating or changing a deployment profile.
+3. Run `npx @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing Secret values.
+4. Run `npx @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
+5. Show the user the context, cluster fingerprint result, namespace, Helm release, exact images, current revision and status, actions, migration warning, and plan hash.
+6. Do not apply until the user explicitly approves that exact plan.
+7. Apply with `npx @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
+8. Run `npx @podosoft/podokit deploy status --profile <name> --json` and `npx @podosoft/podokit deploy verify --profile <name> --json`.
+9. Report the exact images, Helm revision, ready replicas, restart totals, and verification result.
+
+For rollback, read [references/rollback.md](references/rollback.md), preview the target revision without `--confirm`, show the new plan hash, and obtain explicit approval.
+
+Never create or rotate cluster credentials, registry credentials, DNS, virtual machines, Kubernetes Secrets, or backup repositories. Never put a password, token, private key, connection URL containing credentials, or Secret value in a profile, command argument, log, or report.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Deploy"
+  short_description: "Plan and verify safe Kubernetes releases"
+  default_prompt: "Use $podokit-deploy to inspect and plan this PodoKit Kubernetes release safely."

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/profile.md

@@ -0,0 +1,37 @@
+# Deployment profile
+
+The profile at `.podokit/deploy/<name>.json` is application-owned and contains no Secret values.
+
+Initialize it with an explicit kubeconfig context:
+
+```bash
+npx @podosoft/podokit deploy init --profile production --context production --host app.example.com
+```
+
+Review these fields before planning:
+
+- `target`: context, cluster fingerprint, namespace, release
+- `release`: API/web repositories and stable SemVer tag pattern
+- `exposure`: Ingress or NodePort; Ingress routes every public path to web
+- `workloads`: API/web replicas and resources plus an optional worker
+- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
+- `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
+- `runtimeConfig`: non-sensitive environment values only
+- `verification`: HTTPS origin and checks with exact statuses and optional JSON fields
+
+The cluster namespace and referenced Secrets must already exist. PodoKit asks `kubectl` to output only Secret key names and never prints or stores their values; the Kubernetes client still materializes the Secret while evaluating that output.
+
+Required keys:
+
+| Secret | Required keys |
+| --- | --- |
+| API | Profile-declared keys plus enabled dependency connection keys: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `REDIS_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+| web | Only explicitly declared web keys; omitted by default |
+| PostgreSQL dependency | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| Redis dependency | `REDIS_PASSWORD` |
+| Object storage dependency | `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+| image pull | A `kubernetes.io/dockerconfigjson` Secret |
+
+Use `inCluster` when the generated Helm release should manage a dependency, `external` when application configuration points to an existing service, and `disabled` only when the application does not require it.
+
+Use the same stable SemVer tag for API and web. `latest`, branch tags, and empty tags are rejected. Planning resolves every deployed tag to an immutable registry digest through Docker Buildx.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/rollback.md

@@ -0,0 +1,18 @@
+# Application rollback
+
+Inspect status and Helm history before choosing a revision:
+
+```bash
+npx @podosoft/podokit deploy status --profile production --json
+helm history <release> --namespace <namespace> --kube-context <context>
+```
+
+Preview a rollback:
+
+```bash
+npx @podosoft/podokit deploy rollback --profile production --revision <number>
+```
+
+Show the target revision, current revision, context, namespace, warning, and generated plan hash. Obtain explicit approval, then pass that exact hash with `--confirm`.
+
+Rollback changes only the application Helm release. It does not reverse database migrations, change the dependency release, delete PersistentVolumeClaims, or delete Secrets. If the old application is incompatible with the current database schema, do not roll back; prepare a forward fix instead.

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-deploy/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: podokit-deploy
+description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit profile and confirmation hash. Use for Kubernetes deployment and rollback work in a generated PodoKit project.
+---
+
+# PodoKit deployment
+
+Read and follow the canonical skill at `../../../.agents/skills/podokit-deploy/SKILL.md`.

package/dist/templates/fullstack-nest-svelte/dot-env.example

@@ -21,3 +21,9 @@ BODY_SIZE_LIMIT=3M
 # job-progress, sse). Start it with: docker compose --profile cache up
 REDIS_HOST=localhost
 REDIS_PORT=6379
+# REDIS_URL takes precedence over the individual settings below.
+# REDIS_URL=rediss://user:password@cache.example.com:6380/0
+REDIS_DB=0
+# REDIS_USERNAME=
+# REDIS_PASSWORD=
+REDIS_TLS=false

package/dist/templates/fullstack-nest-svelte/infra/k3s/api-deployment.yaml

@@ -20,5 +20,5 @@ spec:
             - configMapRef: { name: app-config }
             - secretRef: { name: app-secrets }
           readinessProbe:
-            httpGet: { path: /health, port: 3000 }
+            httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5

package/dist/templates/fullstack-nest-svelte/infra/k3s/ingress.yaml

@@ -18,10 +18,6 @@ spec:
     - host: example.com
       http:
         paths:
-          - path: /api
-            pathType: Prefix
-            backend:
-              service: { name: api, port: { number: 3000 } }
           - path: /
             pathType: Prefix
             backend:

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/site-runtime.svelte

@@ -4,6 +4,10 @@
   import { site, type SiteSettings } from "$lib/site.svelte";
   import { applyTheme, themeConfigFromSettings } from "$lib/site/apply-theme";
   import SessionIdleTimeout from "$lib/components/session-idle-timeout.svelte";
+  // Optional modules add global runtime components here without taking
+  // ownership of the application's root layout.
+  // podokit:begin:site-runtime-imports
+  // podokit:end:site-runtime-imports
 
   const loadedSite = $derived(
     (page.data as { site?: Partial<SiteSettings> | null }).site,
@@ -42,3 +46,5 @@
 
 <ModeWatcher />
 <SessionIdleTimeout timeoutMinutes={sessionIdleTimeoutMinutes} />
+<!-- podokit:begin:site-runtime-components -->
+<!-- podokit:end:site-runtime-components -->

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.spec.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { ApiKeyVerifier } from "./api-key-verifier";
+
+const originalApiKeys = process.env.API_KEYS;
+
+afterEach(() => {
+  if (originalApiKeys === undefined) {
+    delete process.env.API_KEYS;
+  } else {
+    process.env.API_KEYS = originalApiKeys;
+  }
+});
+
+describe("ApiKeyVerifier", () => {
+  it("accepts trimmed configured keys and rejects other values", () => {
+    process.env.API_KEYS = " first-service-key, second-service-key , ";
+    const verifier = new ApiKeyVerifier();
+
+    expect(verifier.isValid("first-service-key")).toBe(true);
+    expect(verifier.isValid("second-service-key")).toBe(true);
+    expect(verifier.isValid("different-service-key")).toBe(false);
+  });
+
+  it("rejects keys when the allowlist is empty", () => {
+    delete process.env.API_KEYS;
+
+    expect(new ApiKeyVerifier().isValid("any-service-key")).toBe(false);
+  });
+
+  it("compares fixed-length digests for differently sized input", () => {
+    process.env.API_KEYS = "short";
+    const verifier = new ApiKeyVerifier();
+
+    expect(verifier.isValid("a-much-longer-unconfigured-service-key")).toBe(false);
+  });
+});

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.ts

@@ -0,0 +1,20 @@
+import { Injectable } from "@nestjs/common";
+import { createHash, timingSafeEqual } from "node:crypto";
+
+function digest(value: string): Buffer {
+  return createHash("sha256").update(value, "utf8").digest();
+}
+
+@Injectable()
+export class ApiKeyVerifier {
+  private readonly keyDigests = (process.env.API_KEYS ?? "")
+    .split(",")
+    .map((key) => key.trim())
+    .filter(Boolean)
+    .map(digest);
+
+  isValid(provided: string): boolean {
+    const supplied = digest(provided);
+    return this.keyDigests.some((expected) => timingSafeEqual(expected, supplied));
+  }
+}

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.guard.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import { type ExecutionContext, UnauthorizedException } from "@nestjs/common";
+import type { ApiKeyVerifier } from "./api-key-verifier";
+import { ApiKeyGuard } from "./api-key.guard";
+
+function requestContext(apiKey?: string): ExecutionContext {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => ({
+        header: (name: string) => (name === "x-api-key" ? apiKey : undefined),
+      }),
+    }),
+  } as unknown as ExecutionContext;
+}
+
+describe("ApiKeyGuard", () => {
+  it("delegates a supplied key to the shared verifier", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => true),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(guard.canActivate(requestContext("service-key"))).toBe(true);
+    expect(verifier.isValid).toHaveBeenCalledWith("service-key");
+  });
+
+  it("rejects a missing key without invoking the verifier", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => true),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(() => guard.canActivate(requestContext())).toThrow(
+      new UnauthorizedException("Missing X-API-Key"),
+    );
+    expect(verifier.isValid).not.toHaveBeenCalled();
+  });
+
+  it("rejects a key that the verifier does not recognize", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => false),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(() => guard.canActivate(requestContext("invalid-key"))).toThrow(
+      new UnauthorizedException("Invalid API key"),
+    );
+  });
+});

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.guard.ts

@@ -1,14 +1,11 @@
 import { type CanActivate, type ExecutionContext, Injectable, UnauthorizedException } from "@nestjs/common";
-import { timingSafeEqual } from "node:crypto";
 import type { Request } from "express";
+import { ApiKeyVerifier } from "./api-key-verifier";
 
 // Validates the X-API-Key header against the API_KEYS allowlist.
 @Injectable()
 export class ApiKeyGuard implements CanActivate {
-  private readonly keys = (process.env.API_KEYS ?? "")
-    .split(",")
-    .map((key) => key.trim())
-    .filter(Boolean);
+  constructor(private readonly verifier: ApiKeyVerifier) {}
 
   canActivate(context: ExecutionContext): boolean {
     const request = context.switchToHttp().getRequest<Request>();
@@ -16,12 +13,7 @@ export class ApiKeyGuard implements CanActivate {
     if (!provided) {
       throw new UnauthorizedException("Missing X-API-Key");
     }
-    const supplied = Buffer.from(provided);
-    const valid = this.keys.some((key) => {
-      const expected = Buffer.from(key);
-      return expected.length === supplied.length && timingSafeEqual(expected, supplied);
-    });
-    if (!valid) {
+    if (!this.verifier.isValid(provided)) {
       throw new UnauthorizedException("Invalid API key");
     }
     return true;

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.module.ts

@@ -1,9 +1,11 @@
 import { Module } from "@nestjs/common";
 import { MachineController } from "../machine/machine.controller";
 import { ApiKeyGuard } from "./api-key.guard";
+import { ApiKeyVerifier } from "./api-key-verifier";
 
 @Module({
   controllers: [MachineController],
-  providers: [ApiKeyGuard],
+  providers: [ApiKeyGuard, ApiKeyVerifier],
+  exports: [ApiKeyVerifier],
 })
 export class ApiKeyModule {}

package/dist/templates/modules/api-key-auth/module.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "api-key-auth",
-  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and @ApiKeyProtected() to open a route to key holders. Requires auth.",
+  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and shared ApiKeyVerifier that compare SHA-256 key digests in constant time. Requires auth.",
   "requires": ["auth"],
   "targetApp": "api",
   "env": [

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-environment.ts

@@ -0,0 +1,32 @@
+export function authSecret(): string {
+  const value = process.env.BETTER_AUTH_SECRET?.trim();
+  if (
+    process.env.NODE_ENV === "production" &&
+    (!value || value.startsWith("change-me-"))
+  ) {
+    throw new Error("BETTER_AUTH_SECRET must be set to a non-placeholder value in production");
+  }
+  const resolved = value || "development-only-auth-secret-min-32-characters";
+  if (resolved.length < 32) {
+    throw new Error("BETTER_AUTH_SECRET must contain at least 32 characters");
+  }
+  return resolved;
+}
+
+export function authBaseUrl(): string {
+  const value = process.env.BETTER_AUTH_URL?.trim();
+  if (process.env.NODE_ENV === "production" && !value) {
+    throw new Error("BETTER_AUTH_URL must be set in production");
+  }
+  const resolved = value || "http://localhost:5002";
+  let url: URL;
+  try {
+    url = new URL(resolved);
+  } catch {
+    throw new Error("BETTER_AUTH_URL must be a valid URL");
+  }
+  if (process.env.NODE_ENV === "production" && url.protocol !== "https:") {
+    throw new Error("BETTER_AUTH_URL must use HTTPS in production");
+  }
+  return resolved;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.runtime.spec.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { authBaseUrl, authSecret } from "./auth-environment";
+
+const originalEnvironment = {
+  NODE_ENV: process.env.NODE_ENV,
+  BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
+  BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,
+};
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(originalEnvironment)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe("authentication production environment", () => {
+  it("rejects missing and placeholder production secrets", () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.BETTER_AUTH_SECRET;
+    expect(() => authSecret()).toThrow("must be set");
+    process.env.BETTER_AUTH_SECRET = "change-me-in-production-min-32-characters";
+    expect(() => authSecret()).toThrow("non-placeholder");
+  });
+
+  it("requires an HTTPS production origin", () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.BETTER_AUTH_URL;
+    expect(() => authBaseUrl()).toThrow("must be set");
+    process.env.BETTER_AUTH_URL = "http://app.example.com";
+    expect(() => authBaseUrl()).toThrow("must use HTTPS");
+    process.env.BETTER_AUTH_URL = "https://app.example.com";
+    expect(authBaseUrl()).toBe("https://app.example.com");
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -12,6 +12,7 @@ import { passkey } from "@better-auth/passkey";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 import { runUserDeletedHandlers } from "./user-delete-handlers";
+import { authBaseUrl, authSecret } from "./auth-environment";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -214,8 +215,8 @@ export function buildAuth(config: AuthConfig) {
     ...(session ? { session } : {}),
     plugins,
     hooks,
-    secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
-    baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:5002",
+    secret: authSecret(),
+    baseURL: authBaseUrl(),
     advanced: {
       ipAddress: {
         // The API sits behind the SvelteKit server proxy, which forwards the

package/dist/templates/modules/auth/files/apps/api/src/health/health.controller.ts

@@ -2,12 +2,22 @@ import { Controller, Get, ServiceUnavailableException } from "@nestjs/common";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource } from "typeorm";
 import { Public } from "@thallesp/nestjs-better-auth";
+import { ReadinessService, type ReadinessStatus } from "./readiness.service";
+
+interface ReadinessResponse {
+  status: "ready";
+  db: "up";
+  checks: Record<string, ReadinessStatus>;
+}
 
 // Health checks stay public under the global auth guard.
 @Public()
 @Controller("health")
 export class HealthController {
-  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly readinessService: ReadinessService,
+  ) {}
 
   @Get()
   liveness(): { status: string; uptime: number; timestamp: string } {
@@ -15,12 +25,17 @@ export class HealthController {
   }
 
   @Get("ready")
-  async readiness(): Promise<{ status: string; db: string }> {
+  async readiness(): Promise<ReadinessResponse> {
+    let db: ReadinessStatus = "up";
     try {
       await this.dataSource.query("SELECT 1");
-      return { status: "ready", db: "up" };
     } catch {
-      throw new ServiceUnavailableException({ status: "degraded", db: "down" });
+      db = "down";
+    }
+    const checks = await this.readinessService.run();
+    if (db === "down" || Object.values(checks).includes("down")) {
+      throw new ServiceUnavailableException({ status: "degraded", db, checks });
     }
+    return { status: "ready", db: "up", checks };
   }
 }

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/queue.ts

@@ -1,8 +1,7 @@
+import { redisConnectionOptions, type RedisConnectionOptions } from "../config/redis.connection";
+
 export const DEMO_QUEUE = "demo";
 
-export function redisConnection(): { host: string; port: number } {
-  return {
-    host: process.env.REDIS_HOST ?? "localhost",
-    port: Number(process.env.REDIS_PORT ?? 6379),
-  };
+export function redisConnection(): RedisConnectionOptions {
+  return redisConnectionOptions(process.env, { maxRetriesPerRequest: null });
 }

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

@@ -2,6 +2,9 @@
   "name": "bullmq",
   "description": "Background jobs with BullMQ: a demo queue, a separate worker process, and enqueue/status endpoints (needs Redis).",
   "requires": [],
+  "requiredProjectFiles": [
+    "apps/api/src/config/redis.connection.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
     "@nestjs/bullmq": "^11.0.4",
@@ -12,7 +15,7 @@
     "dev:worker": "nest start --watch --builder swc --entryFile main-worker"
   },
   "env": [
-    "# bullmq uses REDIS_HOST / REDIS_PORT (already defined above)"
+    "# bullmq uses REDIS_URL or the individual Redis settings defined above"
   ],
   "inject": [
     {