@podosoft/podokit 0.15.0 → 0.16.0

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

@@ -1,9 +1,21 @@
 {
   "name": "sse",
-  "description": "Server-Sent Events: a /events/stream endpoint (heartbeat + published messages) and a POST /events publisher.",
+  "description": "Server-Sent Events with memory or Redis transport for multi-replica delivery.",
   "requires": [],
+  "requiredProjectFiles": [
+    "apps/api/src/config/redis.connection.ts",
+    "apps/api/src/health/readiness.service.ts"
+  ],
   "targetApp": "api",
-  "env": [],
+  "dependencies": {
+    "ioredis": "^5.4.1"
+  },
+  "env": [
+    "# Server-Sent Events transport: memory for one API replica, redis for multiple replicas",
+    "SSE_TRANSPORT=memory",
+    "SSE_REDIS_CHANNEL=podokit:events",
+    "SSE_MAX_EVENT_BYTES=65536"
+  ],
   "inject": [
     { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { EventsModule } from \"./events/events.module\";" },
     { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "EventsModule," }
@@ -11,6 +23,7 @@
   "instructions": [
     "Stream events:  curl -N localhost:5002/events/stream",
     "Publish a message (in another terminal):  curl -XPOST localhost:5002/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
-    "Inject EventsService anywhere to push updates (e.g. job progress)."
+    "Set SSE_TRANSPORT=redis for delivery across API replicas; Redis uses the shared REDIS_URL or individual Redis settings.",
+    "Inject EventsService and call publishAsync for confirmed delivery, publish for best-effort delivery, or publishLocal for events already fanned out to every replica."
   ]
 }

package/dist/templates/todo/AGENTS.md

@@ -70,6 +70,7 @@ Useful commands:
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
+- `podo deploy` — plan, apply, verify, or roll back an immutable Kubernetes release. Use `.agents/skills/podokit-deploy`.
 
 ## Commit conventions
 

package/dist/templates/todo/README.md

@@ -33,16 +33,17 @@ npx @podosoft/podokit dev logs
 npx @podosoft/podokit dev down
 ```
 
-If installed modules require extra services, use their profiles on the initial
-watch command instead:
+`dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
+`storage`, and `queue` when installed modules require Redis, MinIO, or a worker.
+You can still activate an additional Compose profile explicitly:
 
 ```bash
-npx @podosoft/podokit dev watch \
-  --profile cache --profile storage --profile queue
+npx @podosoft/podokit dev watch --profile dev
 ```
 
-Pass the same profile flags to other lifecycle commands when applicable. `dev down`
-removes this project's stack and route. If it is the final registered
+Explicit profile flags are preserved for other lifecycle commands. `dev down`
+activates all profiles while removing this project's stack and route. If it is
+the final registered
 project, it also removes the shared gateway and network. Source changes are synced
 through Compose Watch, including Vite HMR on the same portless browser origin.
 
@@ -78,5 +79,8 @@ The API uses TypeORM with PostgreSQL. A sample `Todo` entity and an initial migr
 
 ## Deploy
 
-Docker Compose in `infra/docker`; example k3s manifests in `infra/k3s`
-(use `secret.example.yaml` as a template — never commit real secrets).
+Docker Compose lives in `infra/docker`; the basic k3s manifests in `infra/k3s`
+route every public path through the web proxy. Use `podo deploy init`, `doctor`,
+and `plan` for an exact-image Helm release on an existing cluster. Applying or
+rolling back requires the exact confirmation hash from a fresh plan. See the
+PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/docs/deployment.md).

package/dist/templates/todo/apps/api/Dockerfile

@@ -16,12 +16,12 @@ RUN npm run build --workspace=apps/api
 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/api ./apps/api
 COPY --from=build /app/apps/api/dist ./apps/api/dist
 COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
-USER app
+USER 100:101
 EXPOSE 3000
 CMD ["node", "dist/main"]

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

@@ -8,6 +8,7 @@
     "start": "node dist/main",
     "lint": "tsc -p tsconfig.json --noEmit",
     "test": "jest --passWithNoTests",
+    "migrate:all": "node dist/database/migrate",
     "typeorm": "typeorm-ts-node-commonjs -d src/database/data-source.ts",
     "migration:run": "npm run typeorm -- migration:run",
     "migration:revert": "npm run typeorm -- migration:revert",

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

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "@jest/globals";
+import { redisConnectionOptions } from "./redis.connection";
+
+describe("redisConnectionOptions", () => {
+  it("prefers an authenticated URL over individual settings", () => {
+    expect(
+      redisConnectionOptions({
+        REDIS_URL: "rediss://user:p%40ss@cache.example.com:6381/4",
+        REDIS_HOST: "ignored",
+        REDIS_PASSWORD: "ignored",
+      }),
+    ).toEqual({
+      host: "cache.example.com",
+      port: 6381,
+      db: 4,
+      username: "user",
+      password: "p@ss",
+      tls: {},
+    });
+  });
+
+  it("uses authenticated host settings when a URL is absent", () => {
+    expect(
+      redisConnectionOptions({
+        REDIS_HOST: "cache",
+        REDIS_PORT: "6380",
+        REDIS_DB: "2",
+        REDIS_USERNAME: "app",
+        REDIS_PASSWORD: "secret",
+        REDIS_TLS: "true",
+      }),
+    ).toEqual({
+      host: "cache",
+      port: 6380,
+      db: 2,
+      username: "app",
+      password: "secret",
+      tls: {},
+    });
+  });
+
+  it("does not include a malformed URL value in its error", () => {
+    const secretUrl = "not-a-url-with-a-secret";
+    expect(() => redisConnectionOptions({ REDIS_URL: secretUrl })).toThrow(
+      "REDIS_URL must be a valid redis:// or rediss:// URL",
+    );
+    try {
+      redisConnectionOptions({ REDIS_URL: secretUrl });
+    } catch (error) {
+      expect(String(error)).not.toContain(secretUrl);
+    }
+  });
+});

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.15.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"
   }
 }