@crossdelta/platform-sdk 0.12.0 → 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' }))
@@ -79,51 +104,70 @@ console.log(`Service running on http://localhost:${port}`)
 
 ## Environment Validation (Optional)
 
-For services with required env vars, validate at startup with Zod:
+**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({
-  PORT: z.string().transform(Number).default('8080'),
-  PUSHER_INSTANCE_ID: z.string().min(1),
-  PUSHER_SECRET_KEY: z.string().min(1),
+  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 at module load - crashes immediately if invalid
-export const env = envSchema.parse(process.env)
+// 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'
+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'
-import { env } from './config/env'
 
+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
+  // Use validated env vars
   await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
   return c.json({ success: true })
 })
 
-Bun.serve({ port: env.PORT, fetch: app.fetch })
-console.log(`Service running on http://localhost:${env.PORT}`)
+Bun.serve({ port, fetch: app.fetch })
+console.log(`Service running on http://localhost:${port}`)
 ```
 
-**Benefits:**
-- ✅ Fail-fast at startup (not at runtime)
-- ✅ Type-safe env access (`env.PORT` is `number`)
-- ✅ Clear error messages for missing vars
-- ✅ Defaults for optional vars
+**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
 
 ---
 

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' }))
@@ -85,53 +109,79 @@ serve({ fetch: app.fetch, port }, (info) => {
 
 ## Environment Validation (Optional)
 
-For services with required env vars, validate at startup with Zod:
+**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({
-  PORT: z.string().transform(Number).default('8080'),
-  PUSHER_INSTANCE_ID: z.string().min(1),
-  PUSHER_SECRET_KEY: z.string().min(1),
+  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 at module load - crashes immediately if invalid
-export const env = envSchema.parse(process.env)
+// 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'
+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 { env } from './config/env'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 
-const app = new Hono()
+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
+  // Use validated env vars
   await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
   return c.json({ success: true })
 })
 
-serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+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}`)
 })
 ```
 
-**Benefits:**
-- ✅ Fail-fast at startup (not at runtime)
-- ✅ Type-safe env access (`env.PORT` is `number`)
-- ✅ Clear error messages for missing vars
-- ✅ Defaults for optional vars
+**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
 
 ---
 

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:**
@@ -87,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
@@ -126,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)
@@ -161,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',
     })
   }
 }
@@ -208,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: