@crossdelta/platform-sdk 0.11.3 → 0.13.0

package/bin/docs/generators/hono-bun.md

@@ -1,5 +1,21 @@
 # Hono (Bun Runtime)
 
+## 🚨 CRITICAL: AI Generation Rules
+
+**DO NOT create from scratch:**
+- ❌ `infra/services/<name>.ts` - Created by CLI with port assignment
+- ❌ `Dockerfile` - Created by CLI
+- ❌ `package.json` - Created by CLI
+
+**Always generate:**
+- ✅ Event handlers (`src/events/*.handler.ts`)
+- ✅ Use-cases (`src/use-cases/*.use-case.ts`)
+- ✅ Tests (`src/**/*.test.ts`)
+- ✅ README.md
+- ✅ Contracts (`packages/contracts/src/events/`)
+
+---
+
 ## 🚨 CRITICAL: Commands Block (REQUIRED FIRST)
 
 ```commands
@@ -20,7 +36,9 @@ pf new hono-micro services/push-notifications -y
 import '@crossdelta/telemetry'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+// Example: my-hono-service → MY_HONO_SERVICE_PORT
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -32,10 +50,11 @@ console.log(`Service running on http://localhost:${port}`)
 **Event Consumer:**
 ```ts
 import '@crossdelta/telemetry'
-import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -43,24 +62,30 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 Bun.serve({ port, fetch: app.fetch })
 console.log(`Service running on http://localhost:${port}`)
 
-await ensureJetStreams({
-  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }]
-})
-
+// Services NEVER create streams!
+// - Development: pf dev auto-creates ephemeral streams from contracts
+// - Production: Pulumi materializes persistent streams
 consumeJetStreams({
-  streams: ['ORDERS'],
+  streams: ['ORDERS'],  // ⚠️ MUST be PLURAL! Extract from contract's channel.stream
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 ```
 
+**CRITICAL:** Stream names MUST be PLURAL:
+- ✅ `streams: ['ORDERS']` - for orders.created event
+- ✅ `streams: ['DOMAINS']` - for domain.created event
+- ❌ `streams: ['ORDER']` - WRONG (singular)
+- ❌ `streams: ['DOMAIN']` - WRONG (singular)
+
 **Event Publisher:**
 ```ts
 import '@crossdelta/telemetry'
 import { publish } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -77,6 +102,75 @@ console.log(`Service running on http://localhost:${port}`)
 
 ---
 
+## Environment Validation (Optional)
+
+**For services with required env vars:**
+
+### 1️⃣ Create `src/config/env.ts`:
+
+```ts
+// src/config/env.ts
+import { z } from 'zod'
+
+// ⚠️ DO NOT include SERVICE_NAME_PORT here - it's already handled by template!
+// Only validate YOUR custom env vars
+const envSchema = z.object({
+  PUSHER_INSTANCE_ID: z.string().min(1, 'PUSHER_INSTANCE_ID is required'),
+  PUSHER_SECRET_KEY: z.string().min(1, 'PUSHER_SECRET_KEY is required'),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
+})
+
+export type Env = z.infer<typeof envSchema>
+
+// Validate and crash process if invalid (like @nestjs/config)
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)  // ← Force crash with exit code 1
+}
+
+export const env = result.data
+```
+
+### 2️⃣ **CRITICAL: Import in `src/index.ts` early!**
+
+```ts
+// src/index.ts
+import '@crossdelta/telemetry'  // ← MUST be first!
+
+// ⚠️ CRITICAL: Import env IMMEDIATELY after telemetry
+// This executes validation and crashes process if env invalid
+import { env } from './config/env'  // ← THIS LINE IS REQUIRED!
+
+import { Hono } from 'hono'
+
+const port = Number(process.env.MY_SERVICE_PORT) || 8080  // ← Handled by template
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+app.post('/notify', async (c) => {
+  const data = await c.req.json()
+  // Use validated env vars
+  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
+  return c.json({ success: true })
+})
+
+Bun.serve({ port, fetch: app.fetch })
+console.log(`Service running on http://localhost:${port}`)
+```
+
+**CRITICAL:**
+- ✅ **MUST import `env` in `src/index.ts`** - without import, validation never runs!
+- ✅ Import early (after telemetry, before everything else)
+- ✅ Use `safeParse()` + `process.exit(1)` - Bun doesn't crash on top-level throws
+- ✅ Explicit exit ensures Turbo shows red X (like NestJS)
+- ❌ **DO NOT** include `SERVICE_NAME_PORT` in env schema - already handled by CLI template
+- ❌ **DO NOT** validate inside handlers or use-cases
+
+---
+
 ## Rules
 
 - ✅ `Bun.serve({ port, fetch: app.fetch })`

package/bin/docs/generators/hono-node.md

@@ -1,5 +1,21 @@
 # Hono (Node.js Runtime)
 
+## 🚨 CRITICAL: AI Generation Rules
+
+**DO NOT generate these files** - they are created by `pf new hono-micro`:
+- ❌ `infra/services/<name>.ts` - Infrastructure config with assigned port
+- ❌ `Dockerfile` - Container configuration
+- ❌ `package.json` - Dependencies and scripts
+
+**Always generate:**
+- ✅ Event handlers (`src/events/*.handler.ts`)
+- ✅ Use-cases (`src/use-cases/*.use-case.ts`)
+- ✅ Tests (`src/**/*.test.ts`)
+- ✅ README.md
+- ✅ Contracts (`packages/contracts/src/events/`)
+
+---
+
 ## 🚨 CRITICAL: Commands Block (REQUIRED FIRST)
 
 ```commands
@@ -21,7 +37,8 @@ import '@crossdelta/telemetry'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -34,11 +51,12 @@ serve({ fetch: app.fetch, port }, (info) => {
 **Event Consumer:**
 ```ts
 import '@crossdelta/telemetry'
-import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -47,17 +65,22 @@ serve({ fetch: app.fetch, port }, (info) => {
   console.log(`Server running on http://localhost:${info.port}`)
 })
 
-await ensureJetStreams({
-  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }]
-})
-
+// Services NEVER create streams!
+// - Development: pf dev auto-creates ephemeral streams from contracts
+// - Production: Pulumi materializes persistent streams
 consumeJetStreams({
-  streams: ['ORDERS'],
+  streams: ['ORDERS'],  // ⚠️ MUST be PLURAL! Extract from contract's channel.stream
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 ```
 
+**CRITICAL:** Stream names MUST be PLURAL:
+- ✅ `streams: ['ORDERS']` - for orders.created event
+- ✅ `streams: ['DOMAINS']` - for domain.created event
+- ❌ `streams: ['ORDER']` - WRONG (singular)
+- ❌ `streams: ['DOMAIN']` - WRONG (singular)
+
 **Event Publisher:**
 ```ts
 import '@crossdelta/telemetry'
@@ -65,7 +88,8 @@ import { publish } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
+const port = Number(process.env.MY_SERVICE_PORT) || 8080
 const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
@@ -83,6 +107,84 @@ serve({ fetch: app.fetch, port }, (info) => {
 
 ---
 
+## Environment Validation (Optional)
+
+**For services with required env vars:**
+
+### 1️⃣ Create `src/config/env.ts`:
+
+```ts
+// src/config/env.ts
+import { z } from 'zod'
+
+// ⚠️ DO NOT include SERVICE_NAME_PORT here - it's already handled by template!
+// Only validate YOUR custom env vars
+const envSchema = z.object({
+  PUSHER_INSTANCE_ID: z.string().min(1, 'PUSHER_INSTANCE_ID is required'),
+  PUSHER_SECRET_KEY: z.string().min(1, 'PUSHER_SECRET_KEY is required'),
+  NATS_URL: z.string().url().default('nats://localhost:4222'),
+})
+
+export type Env = z.infer<typeof envSchema>
+
+// Validate and crash process if invalid (like @nestjs/config)
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)  // ← Force crash with exit code 1
+}
+
+export const env = result.data
+```
+
+### 2️⃣ **CRITICAL: Import in `src/index.ts` early!**
+
+```ts
+// src/index.ts
+import '@crossdelta/telemetry'  // ← MUST be first!
+
+// ⚠️ CRITICAL: Import env IMMEDIATELY after telemetry
+// This executes validation and crashes process if env invalid
+import { env } from './config/env'  // ← THIS LINE IS REQUIRED!
+
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
+
+const port = Number(process.env.NOTIFICATIONS_PORT) || 8080  // ← Handled by template
+
+const app = new Hono()
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+app.post('/notify', async (c) => {
+  const data = await c.req.json()
+  // Use validated env vars
+  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
+  return c.json({ success: true })
+})
+
+consumeJetStreams({
+  streams: ['DOMAINS'],
+  consumer: 'notifications',
+  discover: './src/events/**/*.handler.ts',
+})
+
+serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`Server running on http://localhost:${info.port}`)
+})
+```
+
+**CRITICAL:**
+- ✅ **MUST import `env` in `src/index.ts`** - without import, validation never runs!
+- ✅ Import early (after telemetry, before everything else)
+- ✅ Use `safeParse()` + `process.exit(1)` - ensures proper crash behavior
+- ✅ Explicit exit ensures Turbo shows red X (like NestJS)
+- ❌ **DO NOT** include `SERVICE_NAME_PORT` in env schema - already handled by CLI template
+- ❌ **DO NOT** validate inside handlers or use-cases
+
+---
+
 ## Rules
 
 - ✅ `serve()` from `@hono/node-server`

package/bin/docs/generators/nest.md

@@ -4,6 +4,23 @@
 
 ---
 
+## 🚨 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:**
@@ -22,9 +39,13 @@
 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
@@ -48,17 +69,26 @@ export class AppModule {}
 // ✅ 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) {}
+  constructor(private config: ConfigService<Env, true>) {}
 
   doSomething() {
-    const instanceId = this.config.getOrThrow<string>('PUSHER_INSTANCE_ID')
+    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!)
@@ -74,7 +104,7 @@ src/
 ├── events/
 │   ├── events.module.ts
 │   ├── events.service.ts
-│   └── domain-created.event.ts    # Handler → calls service
+│   └── domain-created.handler.ts    # Handler → calls service
 └── notifications/
     ├── notifications.module.ts
     ├── notifications.service.ts   # Business logic HERE
@@ -113,6 +143,7 @@ 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)
@@ -148,21 +179,21 @@ export class EventsModule {}
 
 ```ts
 import { Injectable, Logger } from '@nestjs/common'
-import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 
 @Injectable()
 export class EventsService {
   private readonly logger = new Logger(EventsService.name)
 
   async startConsumers(): Promise<void> {
-    await ensureJetStreams({
-      streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }],
-    })
+    // 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/**/*.event.ts',
+      discover: './src/events/**/*.handler.ts',
     })
   }
 }
@@ -195,7 +226,7 @@ export const getService = <T>(serviceClass: Type<T>): T => {
 
 ---
 
-## Event Handler (src/events/orders-created.event.ts)
+## Event Handler (src/events/orders-created.handler.ts)
 
 **Handlers must be thin** - just log and delegate to a service: