@podosoft/podokit 0.14.0 → 0.16.0

package/dist/templates/todo/apps/api/src/config/redis.connection.ts

@@ -0,0 +1,69 @@
+export interface RedisConnectionOptions {
+  host: string;
+  port: number;
+  db: number;
+  username?: string;
+  password?: string;
+  tls?: Record<string, never>;
+  lazyConnect?: boolean;
+  enableReadyCheck?: boolean;
+  enableOfflineQueue?: boolean;
+  maxRetriesPerRequest?: number | null;
+  connectTimeout?: number;
+  commandTimeout?: number;
+}
+
+function integer(name: string, value: string | undefined, fallback: number): number {
+  if (value === undefined || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function decoded(value: string, name: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new Error(`${name} contains invalid percent encoding`);
+  }
+}
+
+function fromUrl(value: string): RedisConnectionOptions {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("REDIS_URL must be a valid redis:// or rediss:// URL");
+  }
+  if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+    throw new Error("REDIS_URL must use the redis:// or rediss:// protocol");
+  }
+  const dbPath = url.pathname.replace(/^\/+/, "");
+  return {
+    host: url.hostname || "localhost",
+    port: integer("REDIS_URL port", url.port, 6379),
+    db: integer("REDIS_URL database", dbPath, 0),
+    ...(url.username ? { username: decoded(url.username, "REDIS_URL username") } : {}),
+    ...(url.password ? { password: decoded(url.password, "REDIS_URL password") } : {}),
+    ...(url.protocol === "rediss:" ? { tls: {} } : {}),
+  };
+}
+
+export function redisConnectionOptions(
+  env: NodeJS.ProcessEnv = process.env,
+  overrides: Partial<RedisConnectionOptions> = {},
+): RedisConnectionOptions {
+  const base = env.REDIS_URL
+    ? fromUrl(env.REDIS_URL)
+    : {
+        host: env.REDIS_HOST ?? "localhost",
+        port: integer("REDIS_PORT", env.REDIS_PORT, 6379),
+        db: integer("REDIS_DB", env.REDIS_DB, 0),
+        ...(env.REDIS_USERNAME ? { username: env.REDIS_USERNAME } : {}),
+        ...(env.REDIS_PASSWORD ? { password: env.REDIS_PASSWORD } : {}),
+        ...(env.REDIS_TLS === "true" ? { tls: {} } : {}),
+      };
+  return { ...base, ...overrides };
+}

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

@@ -0,0 +1,16 @@
+import dataSource from "./data-source";
+
+async function migrate(): Promise<void> {
+  await dataSource.initialize();
+  try {
+    await dataSource.runMigrations({ transaction: "all" });
+  } finally {
+    await dataSource.destroy();
+  }
+}
+
+void migrate().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Migration failed: ${message}\n`);
+  process.exitCode = 1;
+});

package/dist/templates/todo/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/todo/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/todo/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/todo/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/todo/apps/web/Dockerfile

@@ -16,11 +16,11 @@ RUN npm run build --workspace=apps/web
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
-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/todo/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/todo/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/todo/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/todo/dot-agents/skills/podokit-deploy/references/profile.md

@@ -0,0 +1,28 @@
+# 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 the target, immutable API/web repositories, exposure, workloads, dependency modes, API/optional web Secret names and required keys, non-sensitive runtime configuration, and verification checks before planning.
+
+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/todo/dot-agents/skills/podokit-deploy/references/rollback.md

@@ -0,0 +1,5 @@
+# Application rollback
+
+Preview the selected revision without `--confirm`, show the resulting plan hash, and obtain explicit approval before rerunning the command with that hash.
+
+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, prepare a forward fix instead.

package/dist/templates/todo/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/todo/dot-env.example

@@ -19,3 +19,9 @@ CORS_ORIGIN=http://localhost:5001
 # 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/todo/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/todo/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/todo/tests/playwright.config.ts

@@ -1,10 +1,15 @@
 import { defineConfig, devices } from "@playwright/test";
+import { loadPlaywrightProjects } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const coreProjects = [
+  { name: "api", testMatch: /.*\.api\.spec\.ts/ },
+  { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
+];
 
 export default defineConfig({
   testDir: ".",
@@ -18,8 +23,5 @@ export default defineConfig({
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [
-    { name: "api", testMatch: /.*\.api\.spec\.ts/ },
-    { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
-  ],
+  projects: [...coreProjects, ...loadPlaywrightProjects(coreProjects)],
 });

package/dist/templates/todo/tests/playwright.extensions.ts

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { TestConfig } from "@playwright/test";
+
+type Projects = NonNullable<TestConfig["projects"]>;
+
+const requireFromTests = createRequire(__filename);
+
+function projectName(project: unknown): string | null {
+  if (typeof project !== "object" || project === null || !("name" in project)) return null;
+  return typeof project.name === "string" && project.name.length > 0 ? project.name : null;
+}
+
+/**
+ * Merge application-owned Playwright projects into PodoKit's managed config.
+ * The optional CommonJS file stays owned so applications can add devices and
+ * browsers without creating a 3-way merge hotspot in playwright.config.ts.
+ */
+export function loadPlaywrightProjects(coreProjects: Projects): Projects {
+  const extensionPath = join(__dirname, "playwright.projects.cjs");
+  if (!existsSync(extensionPath)) return [];
+
+  const loaded = requireFromTests(extensionPath) as unknown;
+  if (!Array.isArray(loaded)) {
+    throw new Error("tests/playwright.projects.cjs must export an array of Playwright projects.");
+  }
+
+  const names = new Set(
+    coreProjects.map((project) => projectName(project)).filter((name): name is string => name !== null),
+  );
+  for (const project of loaded) {
+    const name = projectName(project);
+    if (!name) {
+      throw new Error("Every project in tests/playwright.projects.cjs must have a non-empty name.");
+    }
+    if (names.has(name)) {
+      throw new Error(`Duplicate Playwright project name: ${name}`);
+    }
+    names.add(name);
+  }
+
+  return loaded as Projects;
+}

package/dist/update.js

@@ -91,20 +91,24 @@ function planUpdate(projectRoot, templatesDir) {
         const locked = lock.files[path];
         const newText = treeText(newTree, path);
         const disk = diskContent(projectRoot, path);
-        // A newer module can explicitly take responsibility for a path that older
-        // projects classified under a broad owned glob (notably generated skills).
-        const managedByTarget = managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
-        const ownedByTarget = ownedGlobs.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
-        const tier = managedByTarget
-            ? "managed"
-            : ownedByTarget
-                ? "owned"
-                : locked?.tier ??
-                    (newText !== null
-                        ? (0, lockfile_1.classifyTier)(path, newText, ownedGlobs, managedOverrides)
-                        : "managed");
+        // Use the same ownership precedence as lockfile classification. In
+        // particular, an exact path recorded by `podo eject` must keep winning over
+        // a module's managed override, while managed overrides may still reclaim a
+        // path covered only by a broad owned glob.
+        const controlledByTarget = managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob)) ||
+            ownedGlobs.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
+        const classified = (0, lockfile_1.classifyTier)(path, newText ?? disk ?? "", ownedGlobs, managedOverrides);
+        const tier = controlledByTarget ? classified : locked?.tier ?? classified;
         if (tier === "owned") {
-            changes.push({ path, tier, action: "skip", note: "owned — never modified" });
+            const explicitlyOwned = ownedGlobs.some((glob) => !glob.includes("*") && (0, lockfile_1.matchGlob)(path, glob));
+            changes.push({
+                path,
+                tier,
+                action: "skip",
+                note: explicitlyOwned && disk === null && newText !== null
+                    ? "explicitly owned — missing or relocated; not restored"
+                    : "owned — never modified",
+            });
             continue;
         }
         // File removed upstream.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,6 +44,6 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-template-engine": "^0.4.0"
+    "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }