@crossdelta/platform-sdk 0.7.16 → 0.7.17

package/README.md

@@ -9,9 +9,9 @@
 </p>
 
 <p align="center">
-  <strong>Your AI-powered platform engineer.</strong><br />
-  Scaffold complete <a href="https://turbo.build/repo">Turborepo</a> workspaces, generate microservice boilerplate<br />
-  with natural language, and deploy to the cloud — all from one CLI.
+  <strong>Opinionated CLI for event-driven microservice platforms.</strong><br />
+  Scaffold <a href="https://turbo.build/repo">Turborepo</a> workspaces, generate services from natural language,<br />
+  and deploy via <a href="https://www.pulumi.com">Pulumi</a> — DigitalOcean-first, provider-agnostic by design.
 </p>
 
 <p align="center">
@@ -27,7 +27,7 @@
 </p>
 
 <p align="center">
-  <em><code>pf</code> is not a framework — it's a set of conventions that wire code and infrastructure together.</em>
+  <em><code>pf</code> enforces conventions that keep application code and cloud infrastructure in lockstep — from local development to production.</em>
 </p>
 
 <br />
@@ -151,38 +151,52 @@ When you create a workspace with `pf`, you get a **Turborepo monorepo** with thi
 
 ```
 my-platform/
-├── services/         # Microservices (generate with pf new hono-micro)
-│   └── nats/         # NATS message broker (auto-scaffolded)
-├── apps/             # Frontend apps (optional)
-├── packages/         # Shared libraries
-│   └── contracts/    # Event contracts (Schema Registry)
+├── services/              # Microservices (generate with pf new hono-micro)
+│   ├── nats/              # NATS message broker (auto-scaffolded)
+│   └── <service>/         # Your services go here
 │       └── src/
-│           └── index.ts
-├── infra/            # Pulumi Infrastructure-as-Code
-│   ├── index.ts      # Main Pulumi program
-│   └── services/     # Per-service K8s configs (auto-generated)
+│           ├── events/    # Event handlers (*.event.ts)
+│           ├── use-cases/ # Business logic (*.use-case.ts)
+│           ├── types/     # Zod schemas & types
+│           └── index.ts   # Service entrypoint
+├── apps/                  # Frontend apps (optional)
+├── packages/
+│   └── contracts/         # Event contracts (Schema Registry)
+│       └── src/
+│           └── events/    # Event schemas (single source of truth)
+├── infra/                 # Pulumi Infrastructure-as-Code
+│   ├── index.ts           # Main Pulumi program
+│   └── services/          # Per-service K8s configs (auto-generated)
 ├── .github/
-│   └── workflows/    # CI/CD pipelines
-├── turbo.json        # Turborepo task orchestration
-└── .env.local        # Auto-generated from infra configs
+│   └── workflows/         # CI/CD pipelines
+├── turbo.json             # Turborepo task orchestration
+└── .env.local             # Auto-generated from infra configs
 ```
 
-### Key Architectural Decisions
+### Key Conventions
+
+| Location | Purpose |
+|----------|---------|
+| `services/*/src/events/*.event.ts` | Event handlers (auto-discovered) |
+| `services/*/src/use-cases/*.use-case.ts` | Business logic (pure functions) |
+| `services/*/src/types/*.ts` | Service-local Zod schemas |
+| `packages/contracts/src/events/*.ts` | Event contracts (Schema Registry) |
+| `infra/services/*.ts` | Pulumi configs per service |
+
+### Key Rules
 
-1. **NATS + JetStream baseline** — Event-driven communication is built-in, not bolted on
-2. **Schema Registry Pattern** — All event schemas live in `packages/contracts` as single source of truth
-3. **Infrastructure-as-Code by default** — Every service has a matching `infra/services/<name>.ts` config
-4. **Auto-wiring everywhere** — Ports, env vars, NATS subjects, and event contracts are derived automatically
-5. **AI-assisted generation** — Services generate with correct event schemas from natural language descriptions
-6. **Opinionated conventions** — Event handlers in `src/events/*.event.ts`, business logic in `src/use-cases/*.use-case.ts`, schemas in `src/types/*.ts`
-7. **Bun-first DX** — Ultra-fast installs, tests, and dev server with fallback to npm/yarn
+- **Never duplicate schemas** — Contracts in `packages/contracts` are the single source of truth
+- **Event handlers stay thin** — Delegate to use-cases, no business logic in handlers
+- **Infrastructure is explicit** — Ports, env vars derived from `infra/services/*.ts`
 
 ### Event-Driven Mental Model
 
 Services communicate via **CloudEvents** over **NATS JetStream** using the **Schema Registry** as single source of truth:
 
+**1. Define contract (Schema Registry):**
+
 ```typescript
-// packages/contracts/src/events/orders-created.ts (Schema Registry)
+// packages/contracts/src/events/orders-created.ts
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
@@ -196,8 +210,12 @@ export const OrdersCreatedContract = createContract({
 })
 
 export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+```
 
-// Service A publishes an event (Event Publisher)
+**2. Service A publishes an event:**
+
+```typescript
+// services/orders/src/index.ts
 import { publish } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract } from '@my-platform/contracts'
 
@@ -206,14 +224,18 @@ await publish(OrdersCreatedContract, {
   customerId: 'cust-456',
   total: 99.99
 })
+```
+
+**3. Service B auto-discovers and handles it:**
 
-// Service B auto-discovers and handles it (Event Consumer)
-// File: services/notifications/src/events/orders-created.event.ts
+```typescript
+// services/notifications/src/events/orders-created.event.ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { OrdersCreatedContract, type OrdersCreatedData } from '@my-platform/contracts'
+import { sendOrderNotification } from '../use-cases/send-order-notification.use-case'
 
 export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
-  await sendNotification(data)
+  await sendOrderNotification(data)  // Delegate to use-case
 })
 ```
 
@@ -409,22 +431,11 @@ pf dev
 
 ---
 
-## ⚡ Event-Driven Architecture
-
-Every workspace includes **NATS + JetStream** for event-driven microservices communication using **[`@crossdelta/cloudevents`](https://www.npmjs.com/package/@crossdelta/cloudevents)**:
-
-- 🎯 **Type-safe event handlers** with Zod schemas
-- 🔄 **Auto-discovery** of event handlers (`*.event.ts` files)
-- 📦 **Publisher/Consumer patterns** out of the box
-- 🚀 **NATS auto-scaffolded** in `services/nats/` with Docker setup
-- 🗄️ **JetStream persistence** for durable event streaming
-
-### NATS Message Broker
+## ⚡ NATS Message Broker
 
-Every workspace includes a pre-configured NATS service:
+Every workspace includes a pre-configured NATS service with JetStream:
 
-```bash
-# Auto-started with `bun dev`
+```
 services/nats/
 ├── nats.conf              # Local dev config (JetStream enabled)
 ├── nats.prod.conf         # Production config (auth + persistence)
@@ -433,44 +444,11 @@ services/nats/
 ```
 
 **Local Development:**
+- Auto-started with `pf dev`
 - Runs in Docker on ports `4222` (client) and `8222` (HTTP monitoring)
 - Data persisted in `.nats-data/` directory
 - Health check: `curl http://localhost:8222/healthz`
 
-### Publish Events
-
-```typescript
-import { publish } from '@crossdelta/cloudevents'
-
-await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
-```
-
-### Consume Events (Auto-Discovered)
-
-```typescript
-// services/notifications/src/events/orders-created.event.ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-
-const OrdersCreatedSchema = z.object({
-  orderId: z.string(),
-  total: z.number(),
-})
-
-// Export type for use in use-cases
-export type OrdersCreatedEvent = z.infer<typeof OrdersCreatedSchema>
-
-export default handleEvent(
-  {
-    schema: OrdersCreatedSchema,
-    type: 'orders.created',
-  },
-  async (data) => {
-    await sendNotification(data)
-  },
-)
-```
-
 **📚 Learn more:** See `services/nats/README.md` in your workspace for monitoring, configuration, and JetStream details.
 
 <br />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.7.16",
+  "version": "0.7.17",
   "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",
   "keywords": [
     "cli",