@podosoft/podokit 0.4.0 → 0.5.1

package/dist/templates/modules/auth/files/apps/api/src/migrations/1720400000000-InitAppSettings.ts

@@ -0,0 +1,38 @@
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+export class InitAppSettings1720400000000 implements MigrationInterface {
+  name = "InitAppSettings1720400000000";
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE "app_setting" (
+        "key" text NOT NULL,
+        "value" text NOT NULL,
+        "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        CONSTRAINT "PK_app_setting_key" PRIMARY KEY ("key")
+      )
+    `);
+    // Shipped defaults for the admin-managed auth feature flags (single source of
+    // truth is this table; toggle them on the admin Settings page). Must match
+    // FLAG_DEFAULTS in settings/settings.service.ts. phoneNumber ships off —
+    // real SMS delivery needs a provider wired into sendOTP.
+    await queryRunner.query(`
+      INSERT INTO "app_setting" ("key", "value") VALUES
+        ('twoFactor', 'true'),
+        ('magicLink', 'true'),
+        ('emailOtp', 'true'),
+        ('username', 'true'),
+        ('multiSession', 'true'),
+        ('phoneNumber', 'false'),
+        ('apiKey', 'true'),
+        ('passkey', 'true'),
+        ('organization', 'true'),
+        ('oidcProvider', 'false')
+      ON CONFLICT ("key") DO NOTHING
+    `);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "app_setting"`);
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/migrations/1720500000000-InitAuthConfig.ts

@@ -0,0 +1,27 @@
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+export class InitAuthConfig1720500000000 implements MigrationInterface {
+  name = "InitAuthConfig1720500000000";
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    // Admin-managed auth configuration (OAuth providers, SMTP, server-enforced
+    // toggles). Secrets (OAuth client secret, SMTP password) are stored encrypted
+    // in "secret" (AES-256-GCM envelope; key derived from BETTER_AUTH_SECRET —
+    // never in this DB). Non-secret fields live in "config" (jsonb). No rows are
+    // seeded: an empty table means "use environment variables" (legacy behavior).
+    await queryRunner.query(`
+      CREATE TABLE "auth_config" (
+        "key" text NOT NULL,
+        "enabled" boolean NOT NULL DEFAULT false,
+        "config" jsonb NOT NULL DEFAULT '{}',
+        "secret" text,
+        "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        CONSTRAINT "PK_auth_config_key" PRIMARY KEY ("key")
+      )
+    `);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "auth_config"`);
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/app-setting.entity.ts

@@ -0,0 +1,16 @@
+import { Column, Entity, PrimaryColumn, UpdateDateColumn } from "typeorm";
+
+/** A single admin-editable application setting, stored as a string key/value.
+ *  Feature flags (twoFactor, magicLink, ...) live here so an admin can change
+ *  them from the UI instead of editing environment variables. */
+@Entity({ name: "app_setting" })
+export class AppSetting {
+  @PrimaryColumn({ type: "text" })
+  key!: string;
+
+  @Column({ type: "text" })
+  value!: string;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -0,0 +1,25 @@
+/** Admin-managed auth feature flags and their shipped defaults.
+ *
+ *  Kept free of Nest/TypeORM imports so both the DI-managed SettingsService and
+ *  the better-auth feature gate (loaded by auth.ts, outside DI — including when
+ *  the better-auth CLI evaluates auth.ts for migrations) can import it safely.
+ *
+ *  Must match the rows seeded by the InitAppSettings migration. phoneNumber is
+ *  off by default because real delivery needs an SMS provider. */
+export type FeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider";
+
+export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
+  twoFactor: true,
+  magicLink: true,
+  emailOtp: true,
+  username: true,
+  multiSession: true,
+  phoneNumber: false,
+  apiKey: true,
+  passkey: true,
+  organization: true,
+  // Acting as an OIDC identity provider is an enterprise opt-in; off by default.
+  oidcProvider: false,
+};
+
+export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];

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

@@ -0,0 +1,11 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { AppSetting } from "./app-setting.entity";
+import { SettingsService } from "./settings.service";
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AppSetting])],
+  providers: [SettingsService],
+  exports: [SettingsService],
+})
+export class SettingsModule {}

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

@@ -0,0 +1,57 @@
+import { Injectable, type OnModuleInit } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { AppSetting } from "./app-setting.entity";
+
+import { FLAG_DEFAULTS, FEATURE_FLAGS, type FeatureFlag } from "./flag-defaults";
+
+/** Admin-editable feature flags — the DB (app_setting) is the single source of
+ *  truth. Defaults are seeded by the InitAppSettings migration and changed live
+ *  from the admin Settings page. Only features whose plugin can be mounted
+ *  unconditionally live here; their endpoints are blocked server-side when off
+ *  (see auth/feature-gate.ts). Server-enforced flags (email verification, breach
+ *  check, self-deletion) and secrets/infra stay in the environment. */
+export { FEATURE_FLAGS, type FeatureFlag };
+
+@Injectable()
+export class SettingsService implements OnModuleInit {
+  private cache = new Map<string, string>();
+
+  constructor(@InjectRepository(AppSetting) private readonly repo: Repository<AppSetting>) {}
+
+  async onModuleInit(): Promise<void> {
+    await this.refresh();
+  }
+
+  private async refresh(): Promise<void> {
+    try {
+      const rows = await this.repo.find();
+      this.cache = new Map(rows.map((r) => [r.key, r.value]));
+    } catch {
+      // Table not migrated yet — fall back to the shipped defaults until it exists.
+      this.cache = new Map();
+    }
+  }
+
+  /** DB value (migration-seeded or admin-set); shipped default if the row is missing. */
+  getBool(flag: FeatureFlag): boolean {
+    const stored = this.cache.get(flag);
+    if (stored !== undefined) return stored === "true";
+    return FLAG_DEFAULTS[flag];
+  }
+
+  flags(): Record<FeatureFlag, boolean> {
+    return Object.fromEntries(FEATURE_FLAGS.map((f) => [f, this.getBool(f)])) as Record<FeatureFlag, boolean>;
+  }
+
+  async setMany(update: Partial<Record<FeatureFlag, boolean>>): Promise<Record<FeatureFlag, boolean>> {
+    for (const flag of FEATURE_FLAGS) {
+      const next = update[flag];
+      if (typeof next === "boolean") {
+        await this.repo.save({ key: flag, value: String(next) });
+      }
+    }
+    await this.refresh();
+    return this.flags();
+  }
+}

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

@@ -0,0 +1,23 @@
+// Outgoing SMS transport. Point SMS_WEBHOOK_URL at your provider's HTTP API in
+// production (or adapt this to a vendor SDK); in local dev it targets the SMS
+// sink (docker-compose `dev` profile), which captures every message for tests to
+// read back. With no SMS_WEBHOOK_URL set, fall back to logging so nothing crashes.
+export type Sms = { to: string; body: string };
+
+export async function sendSms(sms: Sms): Promise<void> {
+  const url = process.env.SMS_WEBHOOK_URL;
+  if (!url) {
+    console.warn(`[sms] no SMS_WEBHOOK_URL configured; not delivered — to ${sms.to}: ${sms.body}`);
+    return;
+  }
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(sms),
+    });
+    if (!res.ok) console.warn(`[sms] delivery returned ${res.status} for ${sms.to}`);
+  } catch (err) {
+    console.warn(`[sms] delivery failed for ${sms.to}:`, err);
+  }
+}

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

@@ -4,20 +4,43 @@
   "requires": [],
   "targetApp": "api",
   "dependencies": {
+    "@podosoft/podokit-auth": "^0.1.0",
+    "@podosoft/podokit-contracts": "^0.1.0",
     "better-auth": "^1.6.23",
     "@thallesp/nestjs-better-auth": "^2.7.0",
-    "pg": "^8.12.0"
+    "pg": "^8.12.0",
+    "nodemailer": "^7.0.9",
+    "@better-auth/api-key": "^1.6.23",
+    "@better-auth/passkey": "^1.6.23",
+    "@better-auth/oauth-provider": "^1.6.23"
   },
   "devDependencies": {
-    "@types/pg": "^8.11.10"
+    "@types/pg": "^8.11.10",
+    "@types/nodemailer": "^7.0.4"
   },
   "env": [
-    "# auth (better-auth) \u2014 set a strong secret (>= 32 chars) in production",
+    "# \u2500\u2500 Auth (better-auth) \u2014 the only required secrets \u2500\u2500",
+    "# BETTER_AUTH_SECRET also derives the key that encrypts config secrets stored in the",
+    "# DB (OAuth client secrets, SMTP password). Keep it stable and secret; rotating it",
+    "# makes previously-saved DB secrets undecryptable.",
     "BETTER_AUTH_SECRET=change-me-in-production-min-32-characters",
-    "BETTER_AUTH_URL=http://localhost:3000",
-    "# 2FA (TOTP): set true to enable the plugin",
-    "AUTH_TWO_FACTOR=false",
-    "# OAuth (optional) \u2014 set a provider's id+secret to enable it",
+    "BETTER_AUTH_URL=http://localhost:5002",
+    "# Everything below is OPTIONAL. OAuth providers, SMTP, and the server-enforced",
+    "# toggles (email verification, breached-password check, self-delete) \u2014 plus the",
+    "# feature flags \u2014 are configured on the admin Settings page, stored encrypted in",
+    "# the DB and applied live (no restart). These env vars still work as a fallback/",
+    "# override (e.g. for secrets-manager injection in production); the DB takes",
+    "# precedence when set.",
+    "# --- Optional overrides / local development ---",
+    "# Email (Mailpit in local dev: docker compose --profile dev up \u2192 http://localhost:8025)",
+    "# SMTP_HOST=localhost",
+    "# SMTP_PORT=1025",
+    "# MAIL_FROM=PodoKit <no-reply@example.com>",
+    "# Phone-number SMS webhook (dev: SMS sink on port 8095)",
+    "# SMS_WEBHOOK_URL=http://localhost:8095/sms",
+    "# AUTH_HIBP=false",
+    "# AUTH_EMAIL_VERIFICATION=false",
+    "# AUTH_ALLOW_DELETE=false",
     "# GOOGLE_CLIENT_ID=",
     "# GOOGLE_CLIENT_SECRET=",
     "# GITHUB_CLIENT_ID=",
@@ -26,45 +49,56 @@
   "inject": [
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:imports",
+      "marker": "// podokit:end:imports",
       "text": "import { APP_GUARD } from \"@nestjs/core\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:imports",
+      "marker": "// podokit:end:imports",
       "text": "import { AuthModule, AuthGuard } from \"@thallesp/nestjs-better-auth\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:imports",
-      "text": "import { auth } from \"./auth/auth\";"
+      "marker": "// podokit:end:imports",
+      "text": "import { authRuntime } from \"./auth/auth-provider\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:imports",
+      "marker": "// podokit:end:imports",
       "text": "import { AccountModule } from \"./account/account.module\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:module-imports",
-      "text": "AuthModule.forRoot(auth),"
+      "marker": "// podokit:end:imports",
+      "text": "import { AuthConfigModule } from \"./auth-config/auth-config.module\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:module-imports",
+      "marker": "// podokit:end:module-imports",
+      "text": "AuthModule.forRoot(authRuntime),"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:module-imports",
       "text": "AccountModule,"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:providers",
+      "marker": "// podokit:end:module-imports",
+      "text": "AuthConfigModule,"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:providers",
       "text": "{ provide: APP_GUARD, useClass: AuthGuard },"
     }
   ],
   "instructions": [
-    "Set BETTER_AUTH_SECRET in .env (>= 32 chars).",
+    "Set BETTER_AUTH_SECRET in .env (>= 32 chars). This also derives the key that encrypts config secrets stored in the DB, so keep it stable and secret.",
     "Create the auth tables:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
-    "Sign up:  curl -c cookies.txt -XPOST localhost:3000/api/auth/sign-up/email -H 'content-type: application/json' -d '{\"email\":\"a@example.com\",\"password\":\"password123\",\"name\":\"A\"}'",
-    "Call a protected route with the session:  curl -b cookies.txt localhost:3000/account/me",
-    "Everything is now protected by default; mark public routes with @Public(). Enable OAuth by setting a provider's env vars; enable 2FA with AUTH_TWO_FACTOR=true."
+    "Create the app tables (auth_config, app_setting):  npm run migration:run",
+    "Sign up:  curl -c cookies.txt -XPOST localhost:5002/api/auth/sign-up/email -H 'content-type: application/json' -d '{\"email\":\"a@example.com\",\"password\":\"password123\",\"name\":\"A\"}'",
+    "Call a protected route with the session:  curl -b cookies.txt localhost:5002/account/me",
+    "Everything is protected by default; mark public routes with @Public(). Configure OAuth (Google/GitHub), SMTP, and server-enforced toggles on the admin Settings page \u2014 stored encrypted in the DB and applied live (no restart). Environment variables (GOOGLE_CLIENT_*, SMTP_*, AUTH_*) still work as an optional fallback/override."
   ]
 }

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

@@ -2,7 +2,8 @@ import { Module } from "@nestjs/common";
 import { BullModule } from "@nestjs/bullmq";
 import { DemoProcessor } from "./demo.processor";
 import { DEMO_QUEUE, redisConnection } from "./queue";
-// podokit:worker-imports
+// podokit:begin:worker-imports
+// podokit:end:worker-imports
 
 // Consumer side: runs BullMQ processors. Bootstrapped by main-worker.ts as a
 // separate process so workers scale independently of the API.
@@ -10,11 +11,13 @@ import { DEMO_QUEUE, redisConnection } from "./queue";
   imports: [
     BullModule.forRoot({ connection: redisConnection() }),
     BullModule.registerQueue({ name: DEMO_QUEUE }),
-    // podokit:worker-queues
+    // podokit:begin:worker-queues
+    // podokit:end:worker-queues
   ],
   providers: [
     DemoProcessor,
-    // podokit:worker-providers
+    // podokit:begin:worker-providers
+    // podokit:end:worker-providers
   ],
 })
 export class WorkerModule {}

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

@@ -17,20 +17,20 @@
   "inject": [
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:imports",
+      "marker": "// podokit:end:imports",
       "text": "import { JobsModule } from \"./jobs/jobs.module\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:module-imports",
+      "marker": "// podokit:end:module-imports",
       "text": "JobsModule,"
     }
   ],
   "instructions": [
     "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",
     "Run the worker in a separate terminal:  npm run dev:worker -w <app>-api",
-    "Enqueue a job:  curl -XPOST localhost:3000/jobs -H 'content-type: application/json' -d '{\"text\":\"hello\"}'",
-    "Check status:   curl localhost:3000/jobs/<id>  (state goes waiting -> active -> completed)",
+    "Enqueue a job:  curl -XPOST localhost:5002/jobs -H 'content-type: application/json' -d '{\"text\":\"hello\"}'",
+    "Check status:   curl localhost:5002/jobs/<id>  (state goes waiting -> active -> completed)",
     "Deploy the worker as its own process: k3s manifest added at infra/k3s/worker-deployment.yaml; Docker Compose example at infra/docker/worker.compose.example.yml"
   ]
 }

package/dist/templates/modules/file-upload/module.manifest.json

@@ -8,12 +8,12 @@
   },
   "env": [],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { FilesModule } from \"./files/files.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "FilesModule," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { FilesModule } from \"./files/files.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "FilesModule," }
   ],
   "instructions": [
     "Start MinIO (or configure AWS S3):  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
-    "Upload a file:  curl -F 'file=@./some.png' localhost:3000/files",
+    "Upload a file:  curl -F 'file=@./some.png' localhost:5002/files",
     "The response includes { key, url } — a presigned download URL."
   ]
 }

package/dist/templates/modules/job-progress/module.manifest.json

@@ -5,19 +5,19 @@
   "targetApp": "api",
   "env": [],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { JobProgressModule } from \"./progress/job-progress.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "JobProgressModule," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-imports", "text": "import { ProgressProcessor } from \"../progress/progress.processor\";" },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-imports", "text": "import { RedisModule } from \"../redis/redis.module\";" },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-queues", "text": "RedisModule," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-queues", "text": "BullModule.registerQueue({ name: \"progress\" })," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-providers", "text": "ProgressProcessor," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { JobProgressModule } from \"./progress/job-progress.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "JobProgressModule," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { ProgressProcessor } from \"../progress/progress.processor\";" },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { RedisModule } from \"../redis/redis.module\";" },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-queues", "text": "RedisModule," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-queues", "text": "BullModule.registerQueue({ name: \"progress\" })," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-providers", "text": "ProgressProcessor," }
   ],
   "instructions": [
     "Start Redis + Postgres:  docker compose -f infra/docker/docker-compose.yml up -d",
     "Run API and worker in separate terminals:  npm run dev   /   npm run dev:worker -w <app>-api",
-    "Watch progress:  curl -N localhost:3000/events/stream",
-    "Start a job:     curl -XPOST localhost:3000/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
+    "Watch progress:  curl -N localhost:5002/events/stream",
+    "Start a job:     curl -XPOST localhost:5002/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
     "The stream shows job-progress events 20 -> 40 -> ... -> 100 pushed from the worker via Redis."
   ]
 }

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

@@ -15,12 +15,12 @@
     "LOG_LEVEL=info"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { LoggingModule } from \"./logging/logging.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "LoggingModule," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { LoggingModule } from \"./logging/logging.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "LoggingModule," }
   ],
   "instructions": [
     "Every HTTP request is now logged as structured JSON with a correlation id.",
-    "Make a request and watch the API logs:  curl localhost:3000/health",
+    "Make a request and watch the API logs:  curl localhost:5002/health",
     "Set LOG_LEVEL (debug|info|warn|error) in .env. Logs are pretty in dev and JSON when NODE_ENV=production.",
     "To route Nest's own logs through pino too, add to main.ts: NestFactory.create(AppModule, { bufferLogs: true }) then app.useLogger(app.get(Logger))."
   ]

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

@@ -1,12 +1,13 @@
-# MinIO for local S3-compatible object storage (dev).
-# The default docker-compose.yml is postgres + redis; add MinIO with:
+# MinIO for local S3-compatible object storage — development only (in production
+# point S3_* at a real S3-compatible service). Part of the `dev` profile; add it with:
 #
-#   docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d
+#   docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml --profile dev up -d
 #
 # Console: http://localhost:9001  (S3 API: http://localhost:9000)
 services:
   minio:
     image: minio/minio:latest
+    profiles: ["dev"]
     command: server /data --console-address ":9001"
     environment:
       MINIO_ROOT_USER: ${S3_ACCESS_KEY_ID:-podokit}
@@ -20,6 +21,7 @@ services:
   # Waits for MinIO, then creates the bucket and exits.
   minio-init:
     image: minio/mc:latest
+    profiles: ["dev"]
     depends_on:
       - minio
     entrypoint: >

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

@@ -18,14 +18,14 @@
     "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," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { StorageModule } from \"./storage/storage.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end: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",
+    "Store an object:  curl -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
+    "Read it back:     curl localhost:5002/storage/hello",
+    "Presigned URL:    curl localhost:5002/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/module.manifest.json

@@ -13,8 +13,8 @@
     "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," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RateLimitModule } from \"./rate-limit/rate-limit.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "RateLimitModule," }
   ],
   "instructions": [
     "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",

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

@@ -10,12 +10,12 @@
     "# 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," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RedisModule } from \"./redis/redis.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end: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"
+    "Set a value:  curl -XPUT localhost:5002/cache/greeting -H 'content-type: application/json' -d '{\"value\":\"hi\",\"ttl\":60}'",
+    "Read it back: curl localhost:5002/cache/greeting"
   ]
 }

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

@@ -5,12 +5,12 @@
   "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," }
+    { "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," }
   ],
   "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\"}'",
+    "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)."
   ]
 }

package/dist/templates/todo/README.md

@@ -22,8 +22,8 @@ docker compose -f infra/docker/docker-compose.yml up -d
 {{packageManager}} run dev
 ```
 
-- API: http://localhost:3000 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5173
+- API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
+- Web: http://localhost:5001
 
 ## Database & migrations
 

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

@@ -14,6 +14,7 @@
     "migration:generate": "npm run typeorm -- migration:generate"
   },
   "dependencies": {
+    "@podosoft/podokit-contracts": "^0.1.0",
     "@nestjs/common": "^11.1.27",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.27",

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

@@ -5,7 +5,8 @@ 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
+// podokit:begin:imports
+// podokit:end:imports
 
 @Module({
   imports: [
@@ -13,10 +14,12 @@ import { TodosModule } from "./todos/todos.module";
     TypeOrmModule.forRoot(dataSourceOptions),
     HealthModule,
     TodosModule,
-    // podokit:module-imports
+    // podokit:begin:module-imports
+    // podokit:end:module-imports
   ],
   providers: [
-    // podokit:providers
+    // podokit:begin:providers
+    // podokit:end:providers
   ],
 })
 export class AppModule {}

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

@@ -1,12 +1,4 @@
-// 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";
-  }
-}
+// AppException is a shared contract (stable, language-independent error `code`
+// the frontend branches on). Re-exported from @podosoft/podokit-contracts so the
+// backend and any other layer reference one definition.
+export { AppException } from "@podosoft/podokit-contracts";

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

@@ -3,7 +3,7 @@ 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),
+  PORT: z.coerce.number().default(5002),
   CORS_ORIGIN: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
   POSTGRES_PORT: z.coerce.number().default(5432),