@crossdelta/platform-sdk 0.10.1 → 0.11.0

package/bin/docs/generators/nest.md

@@ -1,52 +1,122 @@
-# NestJS Service - AI Generator Guidelines
+# NestJS Service
 
-These guidelines are for generating NestJS microservices.
-
-**For handler location and structure rules (shared for all frameworks), see:** [Service Generator - Handler Location & Structure](./service.md#handler-location--structure-critical)
+**For handler location and structure rules, see:** [service.md](./service.md)
 
 ---
 
-## 🚨 CRITICAL: Commands Block (REQUIRED - MUST BE FIRST IN YOUR RESPONSE)
+## 🚨 CRITICAL: Use NestJS Built-in Features
 
-Your response **MUST** start with a commands block that scaffolds the NestJS service structure:
+**NEVER create manual implementations when NestJS provides the feature:**
 
-```commands
-pf new nest-micro <service-path> -y
+| ❌ WRONG (Manual) | ✅ CORRECT (NestJS) |
+|-------------------|---------------------|
+| `validateConfig()` function | `ConfigModule` + Zod |
+| `process.env.X` direct access | `ConfigService.get()` |
+| `console.log()` | `Logger` from `@nestjs/common` |
+| Manual error throwing | `HttpException` classes |
+| Custom auth checks | `@UseGuards()` decorator |
+
+**Env validation with `@nestjs/config` + Zod:**
+```ts
+// src/config/env.schema.ts
+import { z } from 'zod'
+
+export const envSchema = z.object({
+  PUSHER_INSTANCE_ID: z.string().min(1),
+  PUSHER_SECRET_KEY: z.string().min(1),
+})
 ```
 
-**Example:** If user asks for "orders service", generate:
-```commands
-pf new nest-micro services/orders -y
+```ts
+// src/app.module.ts
+import { Module } from '@nestjs/common'
+import { ConfigModule } from '@nestjs/config'
+import { envSchema } from './config/env.schema'
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      validate: (config) => envSchema.parse(config),
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-This command creates: `package.json`, `tsconfig.json`, NestJS structure, and basic files.
-**Without this command, the service cannot be built or run!**
+```ts
+// ✅ Service uses ConfigService - already validated at startup
+import { Injectable } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+
+@Injectable()
+export class MyService {
+  constructor(private config: ConfigService) {}
 
-- Services MUST be in `services/` directory
-- User says "orders" → Generate path: `services/orders`
-- Always include `-y` flag to skip prompts
+  doSomething() {
+    const instanceId = this.config.getOrThrow<string>('PUSHER_INSTANCE_ID')
+  }
+}
+```
 
 ---
 
-## NestJS Event Consumer Architecture
+## 🚨 CRITICAL: NestJS Structure (NO use-cases folder!)
+
+NestJS has Services - they ARE the use-cases. Don't create a separate `use-cases/` folder:
 
-For NestJS event consumers, we use NestJS's application context to bridge
-`@crossdelta/cloudevents` handlers with NestJS's dependency injection system.
+```
+✅ CORRECT NestJS structure:
+src/
+├── main.ts
+├── app.module.ts
+├── app.context.ts
+├── events/
+│   ├── events.module.ts
+│   ├── events.service.ts
+│   └── domain-created.event.ts    # Handler → calls service
+└── notifications/
+    ├── notifications.module.ts
+    ├── notifications.service.ts   # Business logic HERE
+    └── send-notification.ts       # Pure helper functions (testable)
+    └── send-notification.test.ts  # Tests for pure functions
+
+❌ WRONG - don't create use-cases folder in NestJS:
+src/
+├── use-cases/                     # NOT needed in NestJS!
+│   └── send-notification.use-case.ts
+```
 
-### Entry Point (src/main.ts)
+---
+
+## 🚨 CRITICAL: Commands Block (REQUIRED FIRST)
+
+```commands
+pf new nest-micro services/<service-name> -y
+```
+
+**Example:** User asks for "orders service" → generate:
+```commands
+pf new nest-micro services/orders -y
+```
+
+---
+
+## Entry Point (src/main.ts)
 
 ```ts
 import '@crossdelta/telemetry'
-
 import { NestFactory } from '@nestjs/core'
 import { AppModule } from './app.module'
+import { setAppContext } from './app.context'
 import { EventsService } from './events/events.service'
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule)
   const port = Number(process.env.MY_SERVICE_PORT) || 8080
 
-  // Get EventsService from DI container and start consuming
+  setAppContext(app)
+
   const eventsService = app.get(EventsService)
   await eventsService.startConsumers()
 
@@ -78,20 +148,18 @@ export class EventsModule {}
 
 ```ts
 import { Injectable, Logger } from '@nestjs/common'
-import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
 
 @Injectable()
 export class EventsService {
   private readonly logger = new Logger(EventsService.name)
 
   async startConsumers(): Promise<void> {
-    await ensureJetStreamStreams({
-      streams: [
-        { stream: 'ORDERS', subjects: ['orders.*'] },
-      ],
+    await ensureJetStreams({
+      streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }],
     })
 
-    consumeJetStreamStreams({
+    consumeJetStreams({
       streams: ['ORDERS'],
       consumer: 'my-service',
       discover: './src/events/**/*.event.ts',
@@ -102,11 +170,9 @@ export class EventsService {
 
 ---
 
-## Accessing NestJS Services in Handlers
+## App Context (src/app.context.ts)
 
-For handlers that need NestJS DI (database, external services), use the app context:
-
-### App Context Singleton (src/app.context.ts)
+For handlers to access NestJS DI:
 
 ```ts
 import type { INestApplication, Type } from '@nestjs/common'
@@ -127,35 +193,11 @@ export const getService = <T>(serviceClass: Type<T>): T => {
 }
 ```
 
-### Updated main.ts with App Context
-
-```ts
-import '@crossdelta/telemetry'
-
-import { NestFactory } from '@nestjs/core'
-import { AppModule } from './app.module'
-import { setAppContext } from './app.context'
-import { EventsService } from './events/events.service'
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule)
-  const port = Number(process.env.MY_SERVICE_PORT) || 8080
-
-  // Make app context available to event handlers
-  setAppContext(app)
-
-  // Start event consumers
-  const eventsService = app.get(EventsService)
-  await eventsService.startConsumers()
-
-  await app.listen(port)
-  console.log(`Service running on http://localhost:${port}`)
-}
+---
 
-bootstrap()
-```
+## Event Handler (src/events/orders-created.event.ts)
 
-### Handler with DI Access (src/events/orders-created.event.ts)
+**Handlers must be thin** - just log and delegate to a service:
 
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
@@ -164,35 +206,19 @@ import { getService } from '../app.context'
 import { OrdersService } from '../orders/orders.service'
 
 export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
-  // Get service from NestJS DI container
+  console.log(`[orders.created] Processing orderId=${data.orderId}`)
   const ordersService = getService(OrdersService)
   await ordersService.processOrder(data)
 })
 ```
 
-### Orders Service (src/orders/orders.service.ts)
-
-```ts
-import { Injectable, Logger } from '@nestjs/common'
-import type { OrdersCreatedData } from '{{scope}}/contracts'
-
-@Injectable()
-export class OrdersService {
-  private readonly logger = new Logger(OrdersService.name)
-
-  async processOrder(data: OrdersCreatedData): Promise<void> {
-    this.logger.log(`Processing order: ${data.orderId}`)
-    // Business logic with full DI access
-  }
-}
-```
+**⚠️ CRITICAL:** Use `console.log` in handlers for logging. Do NOT use `getService(Logger)` - Logger is not injectable via app context!
 
 ---
 
-## App Module Structure
+## App Module (src/app.module.ts)
 
 ```ts
-// src/app.module.ts
 import { Module } from '@nestjs/common'
 import { AppController } from './app.controller'
 import { EventsModule } from './events/events.module'
@@ -205,8 +231,11 @@ import { OrdersModule } from './orders/orders.module'
 export class AppModule {}
 ```
 
+---
+
+## App Controller (src/app.controller.ts)
+
 ```ts
-// src/app.controller.ts
 import { Controller, Get } from '@nestjs/common'
 
 @Controller()
@@ -222,44 +251,77 @@ export class AppController {
 
 ## Testing
 
-### Unit Test for Service
+**NestJS Services mit externen Dependencies (Pusher, DB, etc.):**
+- Extrahiere Business-Logik in testbare Funktionen
+- Service-Methoden sind thin wrappers
+- Teste die extrahierte Logik mit Dependency Injection
 
 ```ts
-// src/orders/orders.service.spec.ts
-import { Test, TestingModule } from '@nestjs/testing'
-import { OrdersService } from './orders.service'
-
-describe('OrdersService', () => {
-  let service: OrdersService
+// src/notifications/send-notification.ts (pure function)
+import type { DomainCreatedData } from '{{scope}}/contracts'
 
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [OrdersService],
-    }).compile()
-
-    service = module.get<OrdersService>(OrdersService)
-  })
-
-  it('should process order', async () => {
-    const mockData = {
-      orderId: 'ord_123',
-      customerId: 'cust_456',
-      total: 99.99,
-    }
+export const buildNotificationPayload = (data: DomainCreatedData) => ({
+  title: 'Domain Created',
+  body: `Domain ${data.domainId} was created`,
+})
+```
 
-    await expect(service.processOrder(mockData)).resolves.not.toThrow()
+```ts
+// src/notifications/send-notification.test.ts
+import { describe, expect, it } from 'bun:test'
+import { buildNotificationPayload } from './send-notification'
+
+describe('buildNotificationPayload', () => {
+  it('builds payload with domain info', () => {
+    const payload = buildNotificationPayload({ domainId: 'dom_1', name: 'Test' })
+    expect(payload.title).toBe('Domain Created')
+    expect(payload.body).toContain('dom_1')
   })
 })
 ```
 
+**❌ WRONG NestJS Testing patterns:**
+```ts
+// Don't do this:
+beforeEach(() => { process.env.X = 'test' })  // fragile
+// @ts-ignore                                   // code smell
+svc.beams = new FakeBeams()                    // mocking
+```
+
 ---
 
-## Dev Command
+## 🚨 Use NestJS Best Practices
 
-```json
-{
-  "scripts": {
-    "start:dev": "nest start --watch"
-  }
+**Always use NestJS built-in features instead of manual implementations:**
+
+| ❌ Manual Implementation | ✅ NestJS Way |
+|--------------------------|---------------|
+| Manual config validation functions | `ConfigModule` with Zod validation |
+| Manual environment parsing | `ConfigService` injection |
+| Manual logging | `Logger` from `@nestjs/common` |
+| Manual HTTP exceptions | `HttpException` classes |
+| Manual guards/interceptors | NestJS decorators (`@UseGuards`, etc.) |
+
+**Example - Config validation:**
+```ts
+// ❌ WRONG: Manual validator function
+export const validateConfig = (c: { key?: string }) => {
+  if (!c.key) throw new Error('Missing KEY')
 }
+
+// ✅ CORRECT: ConfigModule with validation at startup
+ConfigModule.forRoot({ validate: zodValidator, isGlobal: true })
+// Then inject ConfigService in your service
 ```
+
+---
+
+## Rules
+
+- ✅ Import telemetry FIRST in main.ts
+- ✅ Use `setAppContext(app)` before starting consumers
+- ✅ Handlers use `getService()` for DI access
+- ✅ Always include `/health` endpoint (AppController)
+- ✅ EventsModule only provides EventsService
+- ❌ Don't import NestJS services directly in handlers
+- ❌ Don't register handlers as module providers