@crossdelta/platform-sdk 0.13.3 → 0.13.6

package/bin/docs/generators/nest.md

@@ -0,0 +1,358 @@
+# NestJS Service
+
+**For handler location and structure rules, see:** [service.md](./service.md)
+
+---
+
+## 🚨 CRITICAL: AI Generation Rules
+
+**DO NOT generate these files** - they are created by `pf new nest-micro`:
+- ❌ `infra/services/<name>.ts` - Infrastructure config with assigned port
+- ❌ `Dockerfile` - Container configuration
+- ❌ `package.json` - Dependencies and scripts
+
+**Always generate:**
+- ✅ Modules (`src/**/*.module.ts`)
+- ✅ Services (`src/**/*.service.ts`)
+- ✅ Controllers (`src/**/*.controller.ts`)
+- ✅ Tests (`src/**/*.spec.ts`)
+- ✅ README.md
+- ✅ Contracts (`packages/contracts/src/events/`)
+
+---
+
+## 🚨 CRITICAL: Use NestJS Built-in Features
+
+**NEVER create manual implementations when NestJS provides the feature:**
+
+| ❌ 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({
+  PORT: z.string().transform(Number).default('8080'),
+  PUSHER_INSTANCE_ID: z.string().min(1),
+  PUSHER_SECRET_KEY: z.string().min(1),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
+})
+
+export type Env = z.infer<typeof envSchema>
+```
+
+```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 {}
+```
+
+```ts
+// ✅ Service uses ConfigService - already validated at startup
+import { Injectable } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import type { Env } from './config/env.schema'
+
+@Injectable()
+export class MyService {
+  constructor(private config: ConfigService<Env, true>) {}
+
+  doSomething() {
+    const instanceId = this.config.get('PUSHER_INSTANCE_ID') // Type-safe!
+    const port = this.config.get('PORT') // number (auto-transformed)
+  }
+}
+```
+
+**Benefits:**
+- ✅ Fail-fast at startup (not at runtime)
+- ✅ Type-safe config access with `ConfigService<Env, true>`
+- ✅ Clear error messages for missing vars
+- ✅ Defaults for optional vars
+- ✅ Auto-transform strings to numbers/booleans
+
+---
+
+## 🚨 CRITICAL: NestJS Structure (NO use-cases folder!)
+
+NestJS has Services - they ARE the use-cases. Don't create a separate `use-cases/` folder:
+
+```
+✅ CORRECT NestJS structure:
+src/
+├── main.ts
+├── app.module.ts
+├── app.context.ts
+├── events/
+│   ├── events.module.ts
+│   ├── events.service.ts
+│   └── domain-created.handler.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
+```
+
+---
+
+## 🚨 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)
+  // Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+  const port = Number(process.env.MY_SERVICE_PORT) || 8080
+
+  setAppContext(app)
+
+  const eventsService = app.get(EventsService)
+  await eventsService.startConsumers()
+
+  await app.listen(port)
+  console.log(`Service running on http://localhost:${port}`)
+}
+
+bootstrap()
+```
+
+---
+
+## Events Module (src/events/events.module.ts)
+
+```ts
+import { Module } from '@nestjs/common'
+import { EventsService } from './events.service'
+
+@Module({
+  providers: [EventsService],
+  exports: [EventsService],
+})
+export class EventsModule {}
+```
+
+---
+
+## Events Service (src/events/events.service.ts)
+
+```ts
+import { Injectable, Logger } from '@nestjs/common'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
+
+@Injectable()
+export class EventsService {
+  private readonly logger = new Logger(EventsService.name)
+
+  async startConsumers(): Promise<void> {
+    // Services NEVER create streams!
+    // - Development: pf dev auto-creates ephemeral streams from contracts
+    // - Production: Pulumi materializes persistent streams
+
+    consumeJetStreams({
+      streams: ['ORDERS'],
+      consumer: 'my-service',
+      discover: './src/events/**/*.handler.ts',
+    })
+  }
+}
+```
+
+---
+
+## App Context (src/app.context.ts)
+
+For handlers to access NestJS DI:
+
+```ts
+import type { INestApplication, Type } from '@nestjs/common'
+
+let app: INestApplication
+
+export const setAppContext = (nestApp: INestApplication): void => {
+  app = nestApp
+}
+
+export const getAppContext = (): INestApplication => {
+  if (!app) throw new Error('App context not initialized')
+  return app
+}
+
+export const getService = <T>(serviceClass: Type<T>): T => {
+  return getAppContext().get(serviceClass)
+}
+```
+
+---
+
+## Event Handler (src/events/orders-created.handler.ts)
+
+**Handlers must be thin** - just log and delegate to a service:
+
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { getService } from '../app.context'
+import { OrdersService } from '../orders/orders.service'
+
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+  console.log(`[orders.created] Processing orderId=${data.orderId}`)
+  const ordersService = getService(OrdersService)
+  await ordersService.processOrder(data)
+})
+```
+
+**⚠️ CRITICAL:** Use `console.log` in handlers for logging. Do NOT use `getService(Logger)` - Logger is not injectable via app context!
+
+---
+
+## App Module (src/app.module.ts)
+
+```ts
+import { Module } from '@nestjs/common'
+import { AppController } from './app.controller'
+import { EventsModule } from './events/events.module'
+import { OrdersModule } from './orders/orders.module'
+
+@Module({
+  imports: [EventsModule, OrdersModule],
+  controllers: [AppController],
+})
+export class AppModule {}
+```
+
+---
+
+## App Controller (src/app.controller.ts)
+
+```ts
+import { Controller, Get } from '@nestjs/common'
+
+@Controller()
+export class AppController {
+  @Get('health')
+  health() {
+    return { status: 'ok' }
+  }
+}
+```
+
+---
+
+## Testing
+
+**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/notifications/send-notification.ts (pure function)
+import type { DomainCreatedData } from '{{scope}}/contracts'
+
+export const buildNotificationPayload = (data: DomainCreatedData) => ({
+  title: 'Domain Created',
+  body: `Domain ${data.domainId} was created`,
+})
+```
+
+```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
+```
+
+---
+
+## 🚨 Use NestJS Best Practices
+
+**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