@crossdelta/platform-sdk 0.7.21 → 0.8.0

package/bin/services/ai/instructions/ai-instructions.md

@@ -20,31 +20,28 @@ These rules define how AI-generated scaffolded services must be structured.
 
 **Rule:** Always use **plural namespace** (`orders.`, `users.`, `payments.`) to match JetStream stream subjects (`orders.>`, `users.>`, etc.)
 
-### 4-Step Workflow
+### 3-Step Workflow
 
 **STEP 1: CREATE Contract** (`packages/contracts/src/events/<event-name>.ts`):
 ```ts
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
+export const OrdersCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+})
+
 export const OrdersCreatedContract = createContract({
   type: 'orders.created',  // plural namespace!
-  schema: z.object({
-    orderId: z.string(),
-    customerId: z.string(),
-    total: z.number(),
-  }),
+  schema: OrdersCreatedSchema,
 })
 
 export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
-**STEP 2: Export Contract** (`packages/contracts/src/index.ts`):
-```ts
-export * from './events/orders-created'
-```
-
-**STEP 3: Create Event Handler** (`src/events/orders-created.event.ts`):
+**STEP 2: Create Event Handler** (`src/events/orders-created.event.ts`):
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
@@ -55,7 +52,7 @@ export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData
 })
 ```
 
-**STEP 4: Setup Consumer** (`src/index.ts`):
+**STEP 3: Setup Consumer** (`src/index.ts`):
 ```ts
 import '@crossdelta/telemetry'
 
@@ -107,9 +104,11 @@ pf new hono-micro services/my-service -y
 For Event Consumer services:
 
 ```post-commands
-pf event:generate services/my-service --overwrite
+pf event add <event.type> --service services/my-service
 ```
 
+**Note:** `pf event add` creates contract, mock, handler, and adds the export to `packages/contracts/src/index.ts`.
+
 ---
 
 # 3. Dependencies Block
@@ -134,18 +133,13 @@ services/my-service/
 │   ├── index.ts                    # NATS consumer setup
 │   ├── events/
 │   │   └── orders-created.event.ts # Event handler
-│   ├── use-cases/
-│   │   ├── process-order.use-case.ts
-│   │   └── process-order.test.ts
-│   └── types/
-│       └── orders.ts
+│   └── use-cases/
+│       ├── process-order.use-case.ts
+│       └── process-order.test.ts
 └── README.md
 
-packages/contracts/
-├── src/
-│   ├── events/
-│   │   └── orders-created.ts       # Contract
-│   └── index.ts
+packages/contracts/src/events/
+└── orders-created.ts               # Contract (export added by CLI)
 ```
 
 **Event Publisher:**
@@ -153,14 +147,16 @@ packages/contracts/
 services/my-service/
 ├── src/
 │   ├── index.ts                    # REST API + publish()
-│   ├── use-cases/
-│   │   ├── create-order.use-case.ts
-│   │   └── create-order.test.ts
-│   └── types/
-│       └── orders.ts
+│   └── use-cases/
+│       ├── create-order.use-case.ts
+│       └── create-order.test.ts
 └── README.md
 ```
 
+**IMPORTANT:** Do NOT create `src/types/` directories. All types come from contracts:
+- `OrdersCreatedData` → import from `@scope/contracts`
+- Custom request/response types → define inline or in use-case files
+
 ---
 
 # 5. Code Style
@@ -209,9 +205,10 @@ Combines REST endpoints + NATS consumer.
 
 - Live in `src/use-cases/*.use-case.ts`
 - Pure functions, no framework imports
-- Import types from `src/types/`, NOT Zod schemas
+- Import types from `@scope/contracts`
 - Inject dependencies as parameters (Map, services, etc.)
 - NO manual validation (adapters handle that)
+- **Event handlers:** Always log the event type and a key identifier (e.g., `console.log('📦 Processing order:', data.orderId)`) at the start of the use-case for debugging visibility
 
 ```ts
 import type { OrdersCreatedData } from '{{scope}}/contracts'
@@ -220,6 +217,8 @@ export const processOrder = async (
   data: OrdersCreatedData,
   orderStore: Map<string, any>
 ) => {
+  console.log('📦 Processing order:', data.orderId)
+
   orderStore.set(data.orderId, { ...data, processedAt: new Date() })
   return { success: true }
 }
@@ -257,8 +256,10 @@ describe('Process Order', () => {
 - Put logic in handlers or index.ts
 - Use `src/handlers/` (use `src/events/`)
 - Insert semicolons
+- Edit `packages/contracts/src/index.ts` directly (CLI handles exports)
 
 **DO:**
 - Follow naming convention (plural event types)
-- Create contracts in `packages/contracts`
+- Create contracts in `packages/contracts/src/events/`
+- Export schema separately from contract
 - Keep code minimal and clean

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

@@ -70,8 +70,8 @@ Contracts are **auto-generated** when you create event handlers:
 # 1. Create service with event handler
 pf new hono-micro notifications --ai -d "Sends emails on orders.created events"
 
-# 2. Generate contract (if missing) and mock data
-pf event:generate services/notifications
+# 2. Add event (creates contract, mock, handler)
+pf event add orders.created --service services/notifications
 ```
 
 This creates:
@@ -109,13 +109,13 @@ export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 
 ```bash
 # List all available events
-pf event:list
+pf event list
 
 # Publish mock event
-pf event:publish orders.created
+pf event publish orders.created
 
 # Publish with custom data
-pf event:publish orders.created --data '{"orderId":"test-123"}'
+pf event publish orders.created --data '{"orderId":"test-123"}'
 ```
 
 ## Guidelines

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.7.21",
-  "description": "Your AI-powered platform engineer. Scaffold complete Turborepo workspaces, generate microservice boilerplate with natural language, and deploy to the cloud — all from one CLI",
+  "version": "0.8.0",
+  "description": "Opinionated platform toolkit for event-driven microservices. Scaffold Turborepo workspaces, generate services from natural language, and deploy via Pulumi.",
   "keywords": [
     "cli",
     "scaffolding",