@crossdelta/platform-sdk 0.12.0 → 0.13.0

package/bin/docs/generators/service.md

@@ -7,26 +7,223 @@
 
 ---
 
+## 🚨 CRITICAL: Port Configuration
+
+Services MUST read their port from environment variables using this pattern:
+
+```typescript
+// Convert service name to ENV key format
+// Example: my-hono-service → MY_HONO_SERVICE_PORT
+const port = Number(process.env.MY_HONO_SERVICE_PORT) || 8080
+```
+
+**Port ENV variable naming:**
+- Take service name from package.json `name` field (without scope)
+- Convert to SCREAMING_SNAKE_CASE
+- Append `_PORT`
+
+**Examples:**
+- `@my-platform/orders` → `ORDERS_PORT`
+- `@my-platform/my-nest-service` → `MY_NEST_SERVICE_PORT`
+- `@my-platform/api-gateway` → `API_GATEWAY_PORT`
+
+**⚠️ CRITICAL: DO NOT hardcode or modify the port!**
+- The `pf new` command automatically assigns a unique port
+- The port is written to `.env.local` (e.g., `MY_SERVICE_PORT=4001`)
+- Service code MUST use the correct env variable name
+- DO NOT change the port in generated files!
+
+**When generating service code:**
+1. Determine the correct env variable name from service name
+2. Use ONLY that variable: `process.env.MY_SERVICE_PORT`
+3. DO NOT use generic `PORT` - it causes conflicts!
+4. Keep the `|| 8080` fallback for when `.env.local` is missing
+
+---
+
+## 🚨 CRITICAL: Stream Architecture
+
+> **Services NEVER create streams!**
+>
+> In development, `pf dev` ensures ephemeral streams derived from contracts.
+> In production, streams are materialized explicitly via Pulumi.
+
+---
+
+## Development Workflow
+
+### 1️⃣ **Initial Setup** (once per workspace)
+
+```bash
+pf new workspace my-platform
+cd my-platform
+```
+
+### 2️⃣ **Create Service** (AI or manual)
+
+#### Option A: AI Generation (via GitHub Copilot Chat)
+```
+"Create an order processing service that consumes orders.created events"
+```
+
+**What AI generates:**
+1. **Contract** (`packages/contracts/src/events/orders/created.ts`) - With proper Zod schema in domain-grouped structure
+2. **Service** (`services/order-processing/`) - Scaffolded via `pf new hono-micro`
+3. **Event Handler** (`services/order-processing/src/events/orders-created.handler.ts`)
+4. **Use-Cases** (`services/order-processing/src/use-cases/`)
+5. **Tests** (`services/order-processing/src/use-cases/*.test.ts`)
+
+**What AI includes in response:**
+```commands
+pf new hono-micro services/order-processing -y
+```
+
+```post-commands
+pf event add orders.created --service services/order-processing
+```
+
+**What `pf event add` does:**
+- Creates `packages/contracts/src/events/orders-created.mock.json` (test mock)
+- Adds export to `packages/contracts/src/index.ts`
+- Skips contract creation if already exists (AI's schema is preserved!)
+
+#### Option B: Manual Creation
+
+**Step 1: Create contract with CLI**
+```bash
+# Create contract with schema
+pf event add orders.created --fields "orderId:string,total:number,customerId:string"
+
+# Or with JSON schema
+pf event add orders.created --schema '{"orderId":"string","total":"number"}'
+```
+
+**Step 2: Scaffold service**
+```bash
+pf new hono-micro services/order-processing
+```
+
+**Step 3: Register event and create handler**
+```bash
+pf event add orders.created --service services/order-processing
+```
+
+**Step 4: Implement use-cases**
+```bash
+# Edit services/order-processing/src/use-cases/process-order.use-case.ts
+```
+
+#### Option C: Pure Manual (no CLI)
+
+```bash
+# 1. Create contract manually (domain-grouped)
+mkdir -p packages/contracts/src/events/orders
+# Edit packages/contracts/src/events/orders/created.ts
+
+# 2. Scaffold service
+pf new hono-micro services/order-processing
+
+# 3. Create handler manually
+# Edit services/order-processing/src/events/orders-created.handler.ts
+
+# 4. Implement use-cases
+# Edit services/order-processing/src/use-cases/
+```
+
+### 3️⃣ **Run Development Environment**
+
+```bash
+pf dev  # Starts NATS + creates ephemeral streams from contracts + all services
+```
+
+**What happens:**
+- **NATS** starts in Docker with JetStream enabled
+- **Ephemeral streams** auto-created from contract channel metadata (memory storage, 1h retention)
+- **Services** start and consume from streams
+- **Hot reload** watches for changes
+
+**Stream Creation:** `pf dev` scans `packages/contracts/src/index.ts` for contracts with `channel.stream` metadata and creates ephemeral streams automatically. No manual stream creation needed!
+
+### 4️⃣ **Deploy to Production**
+
+```bash
+cd infra
+pulumi up
+```
+
+**What happens:**
+1. **`infra/streams/`** collects contracts via `collectStreamDefinitions()`
+2. **Streams materialized** via Pulumi with retention policies
+3. **Services deployed** to Kubernetes
+
+---
+
+## �🚨 CRITICAL: Stream Architecture
+
+> **Services NEVER create streams!**
+> **Dev:** Streams are auto-created (ephemeral, memory)
+> **Prod:** Streams are materialized via Pulumi from contracts
+
+### Contracts → Streams → Infra Flow
+
+```typescript
+// 1. Contract defines conceptually (packages/contracts)
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },  // Routing metadata
+  schema: OrderSchema,
+})
+
+// 2. Services consume (no stream creation!)
+consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// 3. Infra materializes (infra/streams/)
+import { collectStreamDefinitions } from '@crossdelta/infrastructure'
+import * as contracts from '@workspace/contracts'
+
+// Generic logic in library, workspace data injected
+const streams = collectStreamDefinitions(contracts)
+deployStreams(provider, namespace, streams)
+```
+
+**Architecture layers:**
+- **@crossdelta/infrastructure:** Generic stream collection logic
+- **Contracts:** Define event semantics + channel routing (workspace data)
+- **`pf dev`:** Ensures ephemeral streams (transient, memory-only)
+- **Platform-Infra:** Materializes streams via Pulumi (persistent, retention)
+- **Services:** Consume streams (never create!)
+
+**Separation of concerns:**
+- **Libraries contain logic** (generic, reusable)
+- **Workspaces contain data** (contracts, policies)
+- **No workspace imports inside libraries**
+
+---
+
 ## 🚨 CRITICAL: @crossdelta/cloudevents API
 
 **ONLY these exports exist:**
-- `ensureJetStreams` / `consumeJetStreams` (preferred)
-- `ensureJetStreamStream` / `consumeJetStreamEvents` (legacy)
+- `consumeJetStreams` (preferred) - Consume from multiple streams
+- `consumeJetStreamEvents` (legacy) - Consume from single stream
 - `handleEvent`, `publish`, `createContract`
 
 ```ts
-await ensureJetStreams({
-  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }]
-})
-
+// Services only consume (DO NOT use ensureJetStreams!)
 consumeJetStreams({
   streams: ['ORDERS'],
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 ```
 
-**DO NOT USE (these do NOT exist):** `stream`, `consumer`, `subscribe`, `name:`, `handler:`, `topic:`
+**DO NOT USE in services:**
+- ❌ `ensureJetStreams()` - Only for infra materialization
+- ❌ `ensureJetStreamStream()` - Legacy, only for infra
+- ❌ Manual stream creation - Services never create streams!
 
 ---
 
@@ -49,6 +246,16 @@ The exact command depends on the framework - see the framework-specific docs:
 
 **Without this command, the service cannot be built!**
 
+**What `pf new` creates automatically:**
+1. Service directory structure (`services/<name>/`)
+2. Infrastructure config (`infra/services/<name>.ts`) with assigned port
+3. Package.json with dependencies
+4. Entry point (`src/index.ts` or `src/main.ts`) with port configuration
+5. Health check endpoint
+6. Dockerfile
+
+**⚠️ AI MUST NOT generate `infra/services/<name>.ts`** - This file is automatically created by the CLI with the correct port assignment!
+
 ---
 
 ## 🚨 CRITICAL: Post-Commands Block (REQUIRED for Event Consumers)
@@ -74,22 +281,23 @@ pf event add customers.updated --service services/my-service
 
 ### What YOU (the AI) generate:
 
-1. **`packages/contracts/src/events/<event>.ts`** - Contract with correct schema fields
-2. **`src/index.ts`** - Entry point with NATS stream/consumer setup
-3. **`src/events/<event>.event.ts`** - Event handler that calls the use-case
-4. **`src/use-cases/*.use-case.ts`** - Business logic (called by handlers)
-5. **`src/use-cases/*.test.ts`** - Tests for use-cases
-6. **`README.md`** - Documentation
+1. **`packages/contracts/src/events/<domain>/<event>.ts`** - Contract with correct schema fields in domain-grouped structure (e.g., `events/orders/created.ts`)
+2. **`src/events/<event>.handler.ts`** - Event handler that calls the use-case
+3. **`src/use-cases/*.use-case.ts`** - Business logic (called by handlers)
+4. **`src/use-cases/*.test.ts`** - Tests for use-cases
+5. **`README.md`** - Documentation
+
+**⚠️ DO NOT generate `src/index.ts` or `src/main.ts`** - These are created by `pf new` with correct port config!
 
 ### Handler Location (CRITICAL!)
 
-**⚠️ MUST be in `src/events/*.event.ts` - NEVER in `handlers/` subdirectory**
+**⚠️ MUST be in `src/events/*.handler.ts` - NEVER in `handlers/` subdirectory**
 
 ```
 ✅ CORRECT:
 services/my-service/src/events/
-├── orders-created.event.ts
-└── customers-updated.event.ts
+├── orders-created.handler.ts
+└── customers-updated.handler.ts
 
 ❌ WRONG:
 services/my-service/src/events/handlers/  # NEVER create!
@@ -126,7 +334,7 @@ export default handleEvent(OrdersCreatedContract, async (data) => {
 pf new hono-micro services/my-service -y
 ```
 
-#### `packages/contracts/src/events/orders-created.ts`
+#### `packages/contracts/src/events/orders/created.ts`
 ```ts
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
@@ -138,13 +346,14 @@ export const OrdersCreatedSchema = z.object({
 
 export const OrdersCreatedContract = createContract({
   type: 'orders.created',
+  channel: { stream: 'ORDERS' },
   schema: OrdersCreatedSchema,
 })
 
 export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
-#### `src/events/orders-created.event.ts`
+#### `src/events/orders-created.handler.ts`
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
@@ -216,11 +425,79 @@ export const OrdersCreatedSchema = z.object({
 
 ## Naming Convention
 
-| Event Type | Contract | File |
-|------------|----------|------|
-| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` |
+**Architecture Rule:**
+
+| Component | Format | Example | Reason |
+|-----------|--------|---------|--------|
+| **Event Type** | **Singular** | `domain.created` | Describes a single event |
+| **Stream** | **PLURAL** | `DOMAINS` | Collection of events for a domain |
+
+**Merksatz:** Events sind singular. Streams sind plural.
+
+### Examples
+
+| Event Type | Contract | File | Stream |
+|------------|----------|------|--------|
+| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` | `ORDERS` ✅ |
+| `domain.created` | `DomainCreatedContract` | `domain-created.ts` | `DOMAINS` ✅ |
+
+```typescript
+// ✅ CORRECT
+export const DomainCreatedContract = createContract({
+  type: 'domain.created',           // Singular event
+  channel: { stream: 'DOMAINS' },   // Plural stream
+  schema: DomainCreatedSchema,
+})
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',           // Singular event (but namespace plural!)
+  channel: { stream: 'ORDERS' },    // Plural stream
+  schema: OrdersCreatedSchema,
+})
+
+// ❌ WRONG
+export const DomainCreatedContract = createContract({
+  type: 'domain.created',
+  channel: { stream: 'DOMAIN' },    // ❌ Must be DOMAINS (plural!)
+  schema: DomainCreatedSchema,
+})
+```
+
+### Stream Names in consumeJetStreams
+
+**CRITICAL:** When consuming from streams, use the **PLURAL** stream name from the contract's `channel.stream`:
+
+```typescript
+// ✅ CORRECT - domain.created event → DOMAINS stream
+consumeJetStreams({
+  streams: ['DOMAINS'],  // ✅ Plural!
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ✅ CORRECT - orders.created event → ORDERS stream
+consumeJetStreams({
+  streams: ['ORDERS'],  // ✅ Plural!
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ❌ WRONG - Don't use singular!
+consumeJetStreams({
+  streams: ['DOMAIN'],   // ❌ Wrong! Should be DOMAINS
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ❌ WRONG - Don't use lowercase!
+consumeJetStreams({
+  streams: ['domains'],  // ❌ Wrong! Should be DOMAINS (uppercase)
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+```
 
-**⚠️ ALWAYS use PLURAL namespace:** `orders.created` ✅, `order.created` ❌
+**Rule:** Extract the stream name from your contract's `channel.stream` field and use it EXACTLY in `consumeJetStreams({ streams: ['...'] })`.
 
 ---
 
@@ -253,7 +530,7 @@ Combines REST endpoints + NATS consumer.
 ```
 services/my-service/src/
 ├── index.ts
-├── events/orders-created.event.ts
+├── events/orders-created.handler.ts
 └── use-cases/
     ├── process-order.use-case.ts
     └── process-order.test.ts
@@ -279,7 +556,7 @@ packages/contracts/src/events/
 
 **DO:**
 - ✅ Contracts in `packages/contracts/src/events/`
-- ✅ Handlers in `src/events/*.event.ts`
+- ✅ Handlers in `src/events/*.handler.ts`
 - ✅ Hono: Use-cases in `src/use-cases/*.use-case.ts`
 - ✅ NestJS: Business logic in Services + pure helper functions
 - ✅ Log event type and key identifier in handlers

package/bin/templates/hono-microservice/src/index.ts.hbs

@@ -0,0 +1,18 @@
+// IMPORTANT: telemetry must be imported first to patch modules before they're loaded
+import '@crossdelta/telemetry'
+
+import { Hono } from 'hono'
+
+const port = Number(process.env.{{envKey}}_PORT) || 8080
+const app = new Hono()
+
+app.get('/health', (c) => {
+  return c.json({ status: 'ok' })
+})
+
+Bun.serve({
+  port,
+  fetch: app.fetch,
+})
+
+console.log(`🚀 Service ready at http://localhost:${port}`)

package/bin/templates/nest-microservice/src/events/events.service.ts.hbs

@@ -1,25 +1,22 @@
 import { Injectable, Logger } from '@nestjs/common'
-import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 
 @Injectable()
 export class EventsService {
   private readonly logger = new Logger(EventsService.name)
 
   async startConsumers(): Promise<void> {
-    // Configure your streams here
-    // Example:
-    // await ensureJetStreamStreams({
-    //   streams: [
-    //     { stream: 'ORDERS', subjects: ['orders.*'] },
-    //   ],
-    // })
+    // Services NEVER create streams!
+    // - Development: pf dev auto-creates ephemeral streams from contracts
+    // - Production: Pulumi materializes persistent streams
 
-    // consumeJetStreamStreams({
+    // Uncomment and configure when you have events:
+    // consumeJetStreams({
     //   streams: ['ORDERS'],
     //   consumer: '{{serviceName}}',
     //   discover: './src/events/**/*.event.ts',
     // })
 
-    this.logger.log('Event consumers ready (configure streams in events.service.ts)')
+    this.logger.log('Event consumers ready')
   }
 }

package/bin/templates/nest-microservice/src/main.ts.hbs

@@ -8,7 +8,7 @@ import { AppModule } from './app.module'
 import { setAppContext } from './app.context'
 import { EventsService } from './events/events.service'
 
-const port = Number(process.env.PORT || process.env.{{envKey}}_PORT) || {{defaultPort}}
+const port = Number(process.env.{{envKey}}_PORT) || {{defaultPort}}
 const serviceName = '{{displayName}}'
 
 const logger = new ConsoleLogger({

package/bin/templates/workspace/package.json.hbs

@@ -37,8 +37,8 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.1",
-    "@crossdelta/telemetry": "^0.1.4"
+    "@crossdelta/cloudevents": "latest",
+    "@crossdelta/telemetry": "latest"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.7",

package/bin/templates/workspace/packages/contracts/README.md.hbs

@@ -10,18 +10,39 @@ This package contains **shared event definitions** (contracts) for events that a
 
 ```
 src/
-├── events/            # Event contracts and mock data
-│   ├── orders-created.ts        # Contract definition
-│   ├── orders-created.mock.json # Mock data for testing
-│   └── index.ts                 # Re-exports
-└── index.ts           # Main exports
+├── events/                    # Event contracts grouped by domain
+│   ├── orders/               # Orders domain
+│   │   ├── created.ts        # orders.created event
+│   │   ├── updated.ts        # orders.updated event
+│   │   └── index.ts          # Re-exports
+│   ├── customers/            # Customers domain
+│   │   ├── updated.ts        # customers.updated event
+│   │   └── index.ts          # Re-exports
+│   └── index.ts              # Re-exports all domains
+├── stream-policies.ts        # NATS JetStream retention policies
+└── index.ts                  # Main export file
 ```
 
 **Contract files contain:**
 - Zod schema definition
-- Contract object (type + schema)
+- Contract object (type + schema + **channel metadata**)
 - TypeScript type inference
-- Mock JSON for `pf event:publish`
+
+**Channel metadata** defines which NATS JetStream stream the event belongs to. This enables infrastructure-as-code workflows where streams are auto-created in dev (`pf dev`) and materialized via Pulumi in production.
+
+## Adding New Events
+
+### Using the CLI (Recommended)
+
+```bash
+pf event add products.created --fields "productId:string,name:string,price:number"
+```
+
+This will create `src/events/products/created.ts` with proper domain structure.
+
+### Manual Creation
+
+See [Adding Events](#manual-creation) section below.
 
 ## Usage
 
@@ -82,7 +103,7 @@ This creates:
 ### Manual Contract Creation
 
 ```ts
-// packages/contracts/src/events/orders-created.ts
+// packages/contracts/src/events/orders/created.ts
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
@@ -99,12 +120,23 @@ export const OrdersCreatedSchema = z.object({
 
 export const OrdersCreatedContract = createContract({
   type: 'orders.created',
+  channel: { stream: 'ORDERS' },  // Stream routing metadata
   schema: OrdersCreatedSchema,
 })
 
 export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
+**Channel Metadata:**
+- `stream` - NATS JetStream stream name (e.g., `ORDERS`)
+- `subject` - Optional, defaults to event type (e.g., `orders.created`)
+
+**Stream Materialization:**
+1. **Development**: `pf dev` scans contracts and auto-creates ephemeral streams from channel metadata
+2. **Production**: Pulumi collects streams from contracts and materializes with retention policies
+
+See [`infra/streams/README.md`](../../infra/streams/README.md) for details.
+
 ## Testing with Mocks
 
 ```bash

package/bin/templates/workspace/packages/contracts/package.json.hbs

@@ -11,7 +11,8 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.2",
+    "@crossdelta/cloudevents": "^0.5.3",
+    "@crossdelta/infrastructure": "^0.5.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/bin/templates/workspace/packages/contracts/src/events/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Event Contracts Index
+ *
+ * Re-exports all event contracts for convenient importing.
+ * Services can import from '{{scope}}/contracts' instead of deep imports.
+ *
+ * Structure:
+ * - events/<domain>/<event>.ts - Individual event contracts
+ * - events/<domain>/index.ts - Domain-specific exports
+ * - This file: Re-exports all domains
+ */
+
+// Add your event domains here as you create them:
+// export * from './orders'
+// export * from './customers'
+// export * from './products'

package/bin/templates/workspace/packages/contracts/src/index.ts

@@ -1 +1,10 @@
 // Export your event contracts and schemas here
+// Use the CLI to generate contracts:
+//
+//   pf event add orders.created --fields "orderId:string,total:number"
+//
+// This will create: src/events/orders/created.ts
+// Then uncomment the exports below:
+
+// export * from './events'
+// export * from './stream-policies'

package/bin/templates/workspace/packages/contracts/src/stream-policies.ts.hbs

@@ -0,0 +1,40 @@
+/**
+ * {{workspaceName}} Stream Policies
+ *
+ * Business rules for NATS JetStream stream configuration.
+ * Defines retention, replication, and storage policies per stream.
+ *
+ * Architecture:
+ * - This file: Business rules (data)
+ * - @crossdelta/infrastructure: Deployment logic
+ * - infra/streams: Connects business rules + deployment logic
+ */
+
+import type { StreamPolicy } from '@crossdelta/infrastructure'
+
+// Time constants for readability
+const DAYS = 24 * 60 * 60 * 1000
+const MB = 1024 * 1024
+
+/**
+ * Stream-specific policies
+ * Add entries here as you create new streams via event contracts
+ */
+export const STREAM_POLICIES: Record<string, Partial<StreamPolicy>> = {
+  // Example:
+  // ORDERS: {
+  //   maxAge: 14 * DAYS,
+  //   replicas: 3,
+  // },
+}
+
+/**
+ * Default stream policy
+ * Applied to all streams without specific overrides
+ */
+export const DEFAULT_POLICY: Partial<StreamPolicy> = {
+  maxAge: 7 * DAYS, // 7 days default retention
+  storage: 'file', // Persistent storage
+  replicas: 1, // Single replica for non-critical streams
+  maxMsgSize: 1 * MB, // 1MB max message size
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",