@crossdelta/platform-sdk 0.16.3 → 0.16.4

package/bin/docs/generators/code-style.md

@@ -14,14 +14,14 @@
 
 ```ts
 // ✅ CORRECT - sorted alphabetically, type imports first
-import type { DomainCreatedData } from '@my-platform/contracts'
+import type { DomainCreatedData } from '{workspaceScope}/contracts'
 import type { OrdersCreatedData } from '@scope/contracts'
 import { handleEvent } from '@crossdelta/cloudevents'
 import PusherPushNotifications from '@pusher/push-notifications-server'
 
 // ❌ WRONG - unsorted
 import PusherPushNotifications from '@pusher/push-notifications-server'
-import type { DomainCreatedData } from '@my-platform/contracts'
+import type { DomainCreatedData } from '{workspaceScope}/contracts'
 
 // ❌ WRONG - missing 'type' keyword
 import { OrdersCreatedData } from '@scope/contracts'

package/bin/docs/generators/nest.md

@@ -242,7 +242,7 @@ export const getService = <T>(serviceClass: Type<T>): T => {
 
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{workspaceScope}/contracts'
 import { getService } from '../app.context'
 import { OrdersService } from '../orders/orders.service'
 
@@ -299,7 +299,7 @@ export class AppController {
 
 ```ts
 // src/notifications/send-notification.ts (pure function)
-import type { DomainCreatedData } from '{{scope}}/contracts'
+import type { DomainCreatedData } from '{workspaceScope}/contracts'
 
 export const buildNotificationPayload = (data: DomainCreatedData) => ({
   title: 'Domain Created',

package/bin/docs/generators/service.md

@@ -47,8 +47,33 @@ const port = Number(process.env.MY_HONO_SERVICE_PORT) || 8080
 
 > **Services NEVER create streams!**
 >
-> In development, `pf dev` ensures ephemeral streams derived from contracts.
-> In production, streams are materialized explicitly via Pulumi.
+> **Dev:** `pf dev` auto-creates ephemeral streams from contracts (memory, 1h retention)
+> **Prod:** Streams materialized via Pulumi with retention policies
+
+### Architecture Flow
+
+```typescript
+// 1. Contract defines routing
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },
+  schema: OrderSchema,
+})
+
+// 2. Services consume (never create!)
+consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// 3. Infra materializes (infra/streams/)
+import { collectStreamDefinitions } from '@crossdelta/infrastructure'
+const streams = collectStreamDefinitions(contracts)
+deployStreams(provider, namespace, streams)
+```
+
+**Key Principle:** Contracts define **what** (routing), infrastructure defines **how** (retention).
 
 ---
 
@@ -160,52 +185,6 @@ pulumi up
 
 ---
 
-## �🚨 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:**
@@ -285,13 +264,30 @@ pf event add customers.updated --service services/my-service
 
 **FOR EVENT CONSUMER SERVICES (services that "consume", "listen to", "react to" events):**
 
+### ⚠️ CRITICAL: Contract Exports (MUST DO FIRST!)
+
+**Before generating ANY files, check if the contract export exists:**
+
+```typescript
+// packages/contracts/src/index.ts
+export * from './events/orders/created'  // ← MUST exist!
+```
+
+**If missing, ADD IT before generating handler!** Services import from `{workspaceScope}/contracts`, not individual files.
+
+**Common Error if missing:**
+```
+Export named 'OrderCreatedContract' not found in module 'packages/contracts/src/index.ts'
+```
+
 ### What YOU (the AI) generate:
 
 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
+2. **`packages/contracts/src/index.ts`** - ⚠️ **ADD EXPORT** for the contract (CRITICAL!)
+3. **`src/events/<event>.handler.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
 
 **⚠️ DO NOT generate `src/index.ts` or `src/main.ts`** - These are created by `pf new` with correct port config!
 
@@ -359,10 +355,16 @@ export const OrdersCreatedContract = createContract({
 export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
+#### `packages/contracts/src/index.ts`
+```ts
+// Export all contracts (REQUIRED - handlers import from here!)
+export * from './events/orders/created'
+```
+
 #### `src/events/orders-created.handler.ts`
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{workspaceScope}/contracts'
 import { processOrder } from '../use-cases/process-order.use-case'
 
 export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
@@ -373,7 +375,7 @@ export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData
 
 #### `src/use-cases/process-order.use-case.ts`
 ```ts
-import type { OrdersCreatedData } from '{{scope}}/contracts'
+import type { OrdersCreatedData } from '{workspaceScope}/contracts'
 
 export const processOrder = async (data: OrdersCreatedData): Promise<void> => {
   console.log('Processing:', data.orderId)
@@ -466,36 +468,37 @@ packages/contracts/src/events/
 
 ### Contract Examples
 
-### Contract Examples
-
 | Event Type | Contract | Folder | Stream |
 |------------|----------|--------|--------|
-| `customer.created` | `CustomerCreatedContract` | `customers/` | `CUSTOMERS` ✅ |
-| `order.created` | `OrderCreatedContract` | `orders/` | `ORDERS` ✅ |
-| `domain.created` | `DomainCreatedContract` | `domains/` | `DOMAINS` ✅ |
+| `customer.created` | `CustomersCreatedContract` | `customers/` | `CUSTOMERS` ✅ |
+| `order.created` | `OrdersCreatedContract` | `orders/` | `ORDERS` ✅ |
+| `domain.created` | `DomainsCreatedContract` | `domains/` | `DOMAINS` ✅ |
+
+**Naming Pattern:** `{PluralDomain}{Action}Contract` - matches folder and stream names
 
 ```typescript
 // ✅ CORRECT
-export const CustomerCreatedContract = createContract({
-  type: 'customer.created',         // Singular event
-  channel: { stream: 'CUSTOMERS' }, // Plural stream
-  schema: CustomerCreatedSchema,
+export const CustomersCreatedContract = createContract({
+  type: 'customer.created',         // Singular event type
+  channel: { stream: 'CUSTOMERS' }, // Plural stream (matches contract name prefix)
+  schema: CustomersCreatedSchema,
 })
 
 // Folder: packages/contracts/src/events/customers/created.ts    ✅ PLURAL
 // Mock:   packages/contracts/src/events/customers/created.mock.json ✅ PLURAL
 
-// ❌ WRONG - Singular stream
+// ❌ WRONG - Singular domain in contract name
 export const CustomerCreatedContract = createContract({
   type: 'customer.created',
-  channel: { stream: 'CUSTOMER' },  // ❌ Must be CUSTOMERS (plural!)
+  channel: { stream: 'CUSTOMERS' },  // Mismatch: plural stream, singular contract
   schema: CustomerCreatedSchema,
 })
 
-// ❌ WRONG - Mixed folders
-// Folder: packages/contracts/src/events/customers/created.ts    ✅
-// Mock:   packages/contracts/src/events/customer/created.mock.json ❌ Singular!
-  schema: DomainCreatedSchema,
+// ❌ WRONG - Singular stream
+export const CustomersCreatedContract = createContract({
+  type: 'customer.created',
+  channel: { stream: 'CUSTOMER' },  // ❌ Wrong! Should be CUSTOMERS (plural)
+  schema: CustomersCreatedSchema,
 })
 ```
 
@@ -595,11 +598,12 @@ packages/contracts/src/events/
 - ❌ Use `src/handlers/` (use `src/events/`)
 - ❌ Create `src/types/` directory (use contracts)
 - ❌ Insert semicolons
-- ❌ Edit `packages/contracts/src/index.ts` (CLI handles exports)
+- ❌ Create contracts without adding exports to `packages/contracts/src/index.ts`
 - ❌ Create `use-cases/` folder in NestJS (use Services instead)
 
 **DO:**
 - ✅ Contracts in `packages/contracts/src/events/`
+- ✅ **ALWAYS add contract exports to `packages/contracts/src/index.ts`** (CRITICAL!)
 - ✅ Handlers in `src/events/*.handler.ts`
 - ✅ Hono: Use-cases in `src/use-cases/*.use-case.ts`
 - ✅ NestJS: Business logic in Services + pure helper functions

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

@@ -7,7 +7,7 @@
     "pulumi": "pulumi"
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.5",
+    "@crossdelta/cloudevents": "^0.5.6",
     "@crossdelta/infrastructure": "^0.5.3",
     "{{scope}}/contracts": "workspace:*",
     "@pulumi/digitalocean": "^4.55.0",

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

@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.5",
+    "@crossdelta/cloudevents": "^0.5.6",
     "@crossdelta/infrastructure": "^0.5.3",
     "zod": "^4.0.0"
   },

package/package.json

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