@podosoft/podokit 0.1.1 → 0.3.0

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.config.ts

@@ -0,0 +1,31 @@
+import type { S3ClientConfig } from "@aws-sdk/client-s3";
+
+export interface StorageSettings {
+  provider: "minio" | "aws";
+  bucket: string;
+}
+
+export function storageSettings(): StorageSettings {
+  const provider = process.env.STORAGE_PROVIDER === "aws" ? "aws" : "minio";
+  return { provider, bucket: process.env.S3_BUCKET ?? "podokit" };
+}
+
+// Build an S3 client config that works for both AWS S3 and MinIO.
+// MinIO needs a custom endpoint and path-style addressing; AWS does not.
+export function storageClientConfig(): S3ClientConfig {
+  const { provider } = storageSettings();
+  const region = process.env.S3_REGION ?? "us-east-1";
+
+  const accessKeyId = process.env.S3_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.S3_SECRET_ACCESS_KEY;
+  const credentials = accessKeyId && secretAccessKey ? { accessKeyId, secretAccessKey } : undefined;
+
+  const forcePathStyle = process.env.S3_FORCE_PATH_STYLE
+    ? process.env.S3_FORCE_PATH_STYLE === "true"
+    : provider === "minio";
+
+  const config: S3ClientConfig = { region, forcePathStyle };
+  if (credentials) config.credentials = credentials;
+  if (process.env.S3_ENDPOINT) config.endpoint = process.env.S3_ENDPOINT;
+  return config;
+}

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.controller.ts

@@ -0,0 +1,29 @@
+import { Body, Controller, Get, Param, Put } from "@nestjs/common";
+import { ApiTags } from "@nestjs/swagger";
+import { StorageService } from "./storage.service";
+import { PutObjectDto } from "./dto/put-object.dto";
+
+// Demo endpoints — replace with your own. See the file-upload module for
+// multipart uploads built on this service.
+@ApiTags("storage")
+@Controller("storage")
+export class StorageController {
+  constructor(private readonly storage: StorageService) {}
+
+  @Put(":key")
+  async put(@Param("key") key: string, @Body() dto: PutObjectDto): Promise<{ key: string }> {
+    await this.storage.put(key, dto.content, "text/plain");
+    return { key };
+  }
+
+  @Get(":key")
+  async get(@Param("key") key: string): Promise<{ key: string; content: string }> {
+    const buffer = await this.storage.get(key);
+    return { key, content: buffer.toString("utf8") };
+  }
+
+  @Get(":key/presigned")
+  async presigned(@Param("key") key: string): Promise<{ url: string }> {
+    return { url: await this.storage.presignedGetUrl(key) };
+  }
+}

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.module.ts

@@ -0,0 +1,11 @@
+import { Global, Module } from "@nestjs/common";
+import { StorageController } from "./storage.controller";
+import { StorageService } from "./storage.service";
+
+@Global()
+@Module({
+  controllers: [StorageController],
+  providers: [StorageService],
+  exports: [StorageService],
+})
+export class StorageModule {}

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.ts

@@ -0,0 +1,37 @@
+import { Injectable } from "@nestjs/common";
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { storageClientConfig, storageSettings } from "./storage.config";
+
+@Injectable()
+export class StorageService {
+  private readonly client = new S3Client(storageClientConfig());
+  private readonly bucket = storageSettings().bucket;
+
+  async put(key: string, body: Buffer | string, contentType?: string): Promise<void> {
+    await this.client.send(
+      new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body, ContentType: contentType }),
+    );
+  }
+
+  async get(key: string): Promise<Buffer> {
+    const res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+    const bytes = await res.Body?.transformToByteArray();
+    return Buffer.from(bytes ?? new Uint8Array());
+  }
+
+  presignedGetUrl(key: string, expiresIn = 3600): Promise<string> {
+    return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
+      expiresIn,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+}

package/dist/templates/modules/object-storage-s3/files/infra/docker/minio.compose.yml

@@ -0,0 +1,33 @@
+# MinIO for local S3-compatible object storage (dev).
+# The default docker-compose.yml is postgres + redis; add MinIO with:
+#
+#   docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d
+#
+# Console: http://localhost:9001  (S3 API: http://localhost:9000)
+services:
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${S3_ACCESS_KEY_ID:-podokit}
+      MINIO_ROOT_PASSWORD: ${S3_SECRET_ACCESS_KEY:-podokitsecret}
+    ports:
+      - "${S3_PORT:-9000}:9000"
+      - "${S3_CONSOLE_PORT:-9001}:9001"
+    volumes:
+      - minio-data:/data
+
+  # Waits for MinIO, then creates the bucket and exits.
+  minio-init:
+    image: minio/mc:latest
+    depends_on:
+      - minio
+    entrypoint: >
+      /bin/sh -c "
+      until mc alias set local http://minio:9000 ${S3_ACCESS_KEY_ID:-podokit} ${S3_SECRET_ACCESS_KEY:-podokitsecret}; do echo 'waiting for minio'; sleep 1; done;
+      mc mb -p local/${S3_BUCKET:-podokit};
+      echo 'bucket ready';
+      exit 0"
+
+volumes:
+  minio-data:

package/dist/templates/modules/object-storage-s3/module.manifest.json

@@ -0,0 +1,31 @@
+{
+  "name": "object-storage-s3",
+  "description": "S3-compatible object storage (AWS S3 or MinIO, chosen by STORAGE_PROVIDER) with a StorageService and presigned URLs.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0"
+  },
+  "env": [
+    "# object storage — STORAGE_PROVIDER: minio | aws",
+    "STORAGE_PROVIDER=minio",
+    "S3_ENDPOINT=http://localhost:9000",
+    "S3_REGION=us-east-1",
+    "S3_BUCKET=podokit",
+    "S3_ACCESS_KEY_ID=podokit",
+    "S3_SECRET_ACCESS_KEY=podokitsecret",
+    "S3_FORCE_PATH_STYLE=true"
+  ],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { StorageModule } from \"./storage/storage.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "StorageModule," }
+  ],
+  "instructions": [
+    "Start MinIO for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
+    "Store an object:  curl -XPUT localhost:3000/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
+    "Read it back:     curl localhost:3000/storage/hello",
+    "Presigned URL:    curl localhost:3000/storage/hello/presigned",
+    "For AWS S3: set STORAGE_PROVIDER=aws, remove S3_ENDPOINT, set S3_FORCE_PATH_STYLE=false and real credentials/bucket."
+  ]
+}

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.module.ts

@@ -0,0 +1,26 @@
+import { Module } from "@nestjs/common";
+import { APP_GUARD } from "@nestjs/core";
+import { ThrottlerGuard, ThrottlerModule } from "@nestjs/throttler";
+import { ThrottlerStorageRedisService } from "@nest-lab/throttler-storage-redis";
+import Redis from "ioredis";
+
+const ttlSeconds = Number(process.env.RATE_LIMIT_TTL ?? 60);
+const limit = Number(process.env.RATE_LIMIT_MAX ?? 100);
+
+// Distributed rate limiting: the counter lives in Redis, so the limit holds
+// across API replicas. Registers a global guard (429 when exceeded).
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      throttlers: [{ ttl: ttlSeconds * 1000, limit }],
+      storage: new ThrottlerStorageRedisService(
+        new Redis({
+          host: process.env.REDIS_HOST ?? "localhost",
+          port: Number(process.env.REDIS_PORT ?? 6379),
+        }),
+      ),
+    }),
+  ],
+  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
+})
+export class RateLimitModule {}

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -0,0 +1,25 @@
+{
+  "name": "rate-limit",
+  "description": "Rate limiting with @nestjs/throttler backed by Redis (correct across API replicas). Installs a global throttler guard; configurable via env.",
+  "requires": ["redis"],
+  "targetApp": "api",
+  "dependencies": {
+    "@nestjs/throttler": "^6.5.0",
+    "@nest-lab/throttler-storage-redis": "^1.2.0"
+  },
+  "env": [
+    "# rate limit (window in seconds, max requests per window per client)",
+    "RATE_LIMIT_TTL=60",
+    "RATE_LIMIT_MAX=100"
+  ],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { RateLimitModule } from \"./rate-limit/rate-limit.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "RateLimitModule," }
+  ],
+  "instructions": [
+    "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "Tune RATE_LIMIT_TTL / RATE_LIMIT_MAX in .env.",
+    "Exceeding the limit returns HTTP 429. Skip a route with @SkipThrottle() or tune it with @Throttle().",
+    "The limit is shared across API replicas because it is stored in Redis."
+  ]
+}

package/dist/templates/modules/redis/files/apps/api/src/redis/cache.controller.ts

@@ -0,0 +1,21 @@
+import { Body, Controller, Get, Param, Put } from "@nestjs/common";
+import { ApiTags } from "@nestjs/swagger";
+import { RedisService } from "./redis.service";
+import { SetCacheDto } from "./dto/set-cache.dto";
+
+@ApiTags("cache")
+@Controller("cache")
+export class CacheController {
+  constructor(private readonly redis: RedisService) {}
+
+  @Put(":key")
+  async put(@Param("key") key: string, @Body() dto: SetCacheDto): Promise<{ key: string }> {
+    await this.redis.set(key, dto.value, dto.ttl);
+    return { key };
+  }
+
+  @Get(":key")
+  async get(@Param("key") key: string): Promise<{ key: string; value: string | null }> {
+    return { key, value: await this.redis.get(key) };
+  }
+}

package/dist/templates/modules/redis/files/apps/api/src/redis/dto/set-cache.dto.ts

@@ -0,0 +1,14 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsInt, IsOptional, IsString, Min } from "class-validator";
+
+export class SetCacheDto {
+  @ApiProperty({ example: "hello" })
+  @IsString()
+  value!: string;
+
+  @ApiPropertyOptional({ example: 60, description: "TTL in seconds" })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  ttl?: number;
+}

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from "@nestjs/common";
+import { CacheController } from "./cache.controller";
+import { RedisService } from "./redis.service";
+
+// Global so any module can inject RedisService (cache, pub/sub, etc.).
+@Global()
+@Module({
+  controllers: [CacheController],
+  providers: [RedisService],
+  exports: [RedisService],
+})
+export class RedisModule {}

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.ts

@@ -0,0 +1,43 @@
+import { Injectable, type OnModuleDestroy } from "@nestjs/common";
+import Redis from "ioredis";
+
+@Injectable()
+export class RedisService implements OnModuleDestroy {
+  readonly client = new Redis({
+    host: process.env.REDIS_HOST ?? "localhost",
+    port: Number(process.env.REDIS_PORT ?? 6379),
+    maxRetriesPerRequest: null,
+  });
+  private readonly subscribers: Redis[] = [];
+
+  get(key: string): Promise<string | null> {
+    return this.client.get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    if (ttlSeconds) await this.client.set(key, value, "EX", ttlSeconds);
+    else await this.client.set(key, value);
+  }
+
+  del(key: string): Promise<number> {
+    return this.client.del(key);
+  }
+
+  publish(channel: string, message: string): Promise<number> {
+    return this.client.publish(channel, message);
+  }
+
+  // Subscribe on a dedicated connection (ioredis can't mix subscribe + commands).
+  subscribe(channel: string, handler: (message: string) => void): void {
+    const sub = this.client.duplicate();
+    this.subscribers.push(sub);
+    void sub.subscribe(channel);
+    sub.on("message", (ch, message) => {
+      if (ch === channel) handler(message);
+    });
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await Promise.allSettled([this.client.quit(), ...this.subscribers.map((s) => s.quit())]);
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "name": "redis",
+  "description": "Redis client (ioredis) with get/set/del and publish/subscribe, plus demo cache endpoints.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "ioredis": "^5.4.1"
+  },
+  "env": [
+    "# redis (REDIS_HOST / REDIS_PORT already defined above)"
+  ],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { RedisModule } from \"./redis/redis.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "RedisModule," }
+  ],
+  "instructions": [
+    "Start Redis:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "Set a value:  curl -XPUT localhost:3000/cache/greeting -H 'content-type: application/json' -d '{\"value\":\"hi\",\"ttl\":60}'",
+    "Read it back: curl localhost:3000/cache/greeting"
+  ]
+}

package/dist/templates/modules/sse/files/apps/api/src/events/dto/publish-event.dto.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString } from "class-validator";
+
+export class PublishEventDto {
+  @ApiProperty({ example: "hello" })
+  @IsString()
+  message!: string;
+}

package/dist/templates/modules/sse/files/apps/api/src/events/events.controller.ts

@@ -0,0 +1,25 @@
+import { Body, Controller, Post, Sse, type MessageEvent } from "@nestjs/common";
+import { ApiTags } from "@nestjs/swagger";
+import { interval, map, merge, type Observable } from "rxjs";
+import { EventsService } from "./events.service";
+import { PublishEventDto } from "./dto/publish-event.dto";
+
+@ApiTags("events")
+@Controller("events")
+export class EventsController {
+  constructor(private readonly events: EventsService) {}
+
+  @Sse("stream")
+  stream(): Observable<MessageEvent> {
+    const heartbeat = interval(5000).pipe(
+      map((n): MessageEvent => ({ data: { type: "heartbeat", n } })),
+    );
+    return merge(this.events.asObservable(), heartbeat);
+  }
+
+  @Post()
+  publish(@Body() dto: PublishEventDto): { ok: true } {
+    this.events.publish({ type: "message", message: dto.message });
+    return { ok: true };
+  }
+}

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from "@nestjs/common";
+import { EventsController } from "./events.controller";
+import { EventsService } from "./events.service";
+
+// Global so any module can inject EventsService to broadcast updates.
+@Global()
+@Module({
+  controllers: [EventsController],
+  providers: [EventsService],
+  exports: [EventsService],
+})
+export class EventsModule {}

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -0,0 +1,17 @@
+import { Injectable, type MessageEvent } from "@nestjs/common";
+import { Observable, Subject } from "rxjs";
+
+@Injectable()
+export class EventsService {
+  private readonly subject = new Subject<MessageEvent>();
+
+  // Push an event to all connected clients. Inject this service anywhere
+  // (e.g. a queue processor) to broadcast progress or notifications.
+  publish(data: unknown): void {
+    this.subject.next({ data } as MessageEvent);
+  }
+
+  asObservable(): Observable<MessageEvent> {
+    return this.subject.asObservable();
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "name": "sse",
+  "description": "Server-Sent Events: a /events/stream endpoint (heartbeat + published messages) and a POST /events publisher.",
+  "requires": [],
+  "targetApp": "api",
+  "env": [],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { EventsModule } from \"./events/events.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "EventsModule," }
+  ],
+  "instructions": [
+    "Stream events:  curl -N localhost:3000/events/stream",
+    "Publish a message (in another terminal):  curl -XPOST localhost:3000/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
+    "Inject EventsService anywhere to push updates (e.g. job progress)."
+  ]
+}

package/dist/templates/todo/README.md

@@ -0,0 +1,40 @@
+# {{projectName}}
+
+Full-stack TypeScript app generated with [PodoKit](https://github.com/podosoft-dev/podokit).
+
+- `apps/api` — NestJS API: schema-validated env, `/health` + `/health/ready`, a `todos` CRUD resource (TypeORM + PostgreSQL), Swagger docs at `/api-docs`, and a standard error envelope.
+- `apps/web` — SvelteKit app (TailwindCSS v4, shadcn-svelte, typesafe-i18n) with a todo UI that talks to the API through a server-side proxy.
+- `infra/` — Docker Compose (PostgreSQL, Redis) and k3s manifests.
+
+## Getting started
+
+```bash
+{{packageManager}} install
+cp .env.example .env
+
+# start local PostgreSQL + Redis
+docker compose -f infra/docker/docker-compose.yml up -d
+
+# run database migrations
+{{packageManager}} run migration:run -w {{projectName}}-api
+
+# run api + web
+{{packageManager}} run dev
+```
+
+- API: http://localhost:3000 — health at `/health`, docs at `/api-docs`
+- Web: http://localhost:5173
+
+## Database & migrations
+
+The API uses TypeORM with PostgreSQL. A sample `Todo` entity and an initial migration are included — replace them with your own domain model.
+
+```bash
+{{packageManager}} run migration:run -w {{projectName}}-api      # apply migrations
+{{packageManager}} run migration:revert -w {{projectName}}-api   # roll back the last one
+```
+
+## Deploy
+
+Docker Compose in `infra/docker`; example k3s manifests in `infra/k3s`
+(use `secret.example.yaml` as a template — never commit real secrets).

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

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json ./
+RUN npm install --omit=dev=false --no-audit --no-fund
+
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -S app && adduser -S app -G app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY package.json ./
+USER app
+EXPOSE 3000
+CMD ["node", "dist/main"]

package/dist/templates/todo/apps/api/nest-cli.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src"
+}

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

@@ -0,0 +1,44 @@
+{
+  "name": "{{projectName}}-api",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "nest start --watch",
+    "build": "nest build",
+    "start": "node dist/main",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "jest",
+    "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",
+    "migration:generate": "npm run typeorm -- migration:generate"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.1.27",
+    "@nestjs/platform-express": "^11.1.27",
+    "@nestjs/swagger": "^11.4.5",
+    "@nestjs/typeorm": "^11.0.3",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "dotenv": "^16.4.5",
+    "pg": "^8.12.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typeorm": "^0.3.20",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^11.0.23",
+    "@nestjs/testing": "^11.1.27",
+    "@types/express": "^5.0.1",
+    "@types/node": "^20.17.0",
+    "@types/supertest": "^6.0.2",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  }
+}

package/dist/templates/todo/apps/api/src/app.module.ts

@@ -0,0 +1,22 @@
+import { Module } from "@nestjs/common";
+import { ConfigModule } from "@nestjs/config";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { validateEnv } from "./config/env.validation";
+import { dataSourceOptions } from "./database/data-source";
+import { HealthModule } from "./health/health.module";
+import { TodosModule } from "./todos/todos.module";
+// podokit:imports
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }),
+    TypeOrmModule.forRoot(dataSourceOptions),
+    HealthModule,
+    TodosModule,
+    // podokit:module-imports
+  ],
+  providers: [
+    // podokit:providers
+  ],
+})
+export class AppModule {}

package/dist/templates/todo/apps/api/src/common/all-exceptions.filter.ts

@@ -0,0 +1,43 @@
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { AppException } from "./app-exception";
+
+interface ErrorBody {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    statusCode: number;
+    path: string;
+    timestamp: string;
+  };
+}
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    let statusCode = HttpStatus.INTERNAL_SERVER_ERROR;
+    let code = "INTERNAL_ERROR";
+    let message = "Internal server error";
+
+    if (exception instanceof AppException) {
+      statusCode = exception.statusCode;
+      code = exception.code;
+      message = exception.message;
+    } else if (exception instanceof HttpException) {
+      statusCode = exception.getStatus();
+      code = "HTTP_ERROR";
+      message = exception.message;
+    }
+
+    const body: ErrorBody = {
+      success: false,
+      error: { code, message, statusCode, path: request.url, timestamp: new Date().toISOString() },
+    };
+    response.status(statusCode).json(body);
+  }
+}

package/dist/templates/todo/apps/api/src/common/app-exception.ts

@@ -0,0 +1,12 @@
+// Stable, language-independent error codes. The frontend branches on `code`,
+// not on the human-readable message.
+export class AppException extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly statusCode = 400,
+  ) {
+    super(message);
+    this.name = "AppException";
+  }
+}

package/dist/templates/todo/apps/api/src/config/env.validation.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+// Schema-validated environment. Fails fast at boot if something is wrong.
+const schema = z.object({
+  NODE_ENV: z.string().default("development"),
+  PORT: z.coerce.number().default(3000),
+  CORS_ORIGIN: z.string().optional(),
+  POSTGRES_HOST: z.string().default("localhost"),
+  POSTGRES_PORT: z.coerce.number().default(5432),
+  POSTGRES_USER: z.string().default("podokit"),
+  POSTGRES_PASSWORD: z.string().default("podokit"),
+  POSTGRES_DB: z.string().default("podokit"),
+});
+
+export type AppEnv = z.infer<typeof schema>;
+
+export function validateEnv(config: Record<string, unknown>): AppEnv {
+  const parsed = schema.safeParse(config);
+  if (!parsed.success) {
+    throw new Error(`Invalid environment:\n${parsed.error.toString()}`);
+  }
+  return parsed.data;
+}