@crossdelta/platform-sdk 0.8.3 → 0.8.4

package/README.md

@@ -1,118 +1,137 @@
 <p align="center">
-  <img src="https://unpkg.com/@crossdelta/platform-sdk/logo.png" alt="pf" width="120" />
+  <img src="https://unpkg.com/@crossdelta/platform-sdk/logo.png" alt="pf" width="140" />
 </p>
 
 <h1 align="center">Platform SDK</h1>
 
 <p align="center">
-  <code>@crossdelta/platform-sdk</code>
+  <strong>The platform toolkit for backend + infrastructure.</strong>
 </p>
 
 <p align="center">
-  <strong>Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.</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 for speed and simplicity, providers replaceable by design.
+  <code>pf</code> scaffolds real-world platforms: backend services, event-driven messaging, infrastructure — all wired together and kept in sync.
 </p>
 
 <p align="center">
-  <em>Platform SDK (<code>pf</code>) is a platform opinion, not a generator.<br />
-  It encodes architectural decisions so teams don't have to rediscover them.</em>
-</p>
+  <sub>Fontend SDK coming soon — contract-based client models.</sub>
 
-<p align="center">
-  <em>Includes optional AI-assisted service generation (OpenAI / Anthropic).</em>
 </p>
 
+<br />
+
 <p align="center">
-  <a href="https://www.npmjs.com/package/@crossdelta/platform-sdk"><img src="https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg?style=flat-square" alt="npm version" /></a>
-  <img src="https://img.shields.io/badge/bun-%E2%9A%A1-f9f1e1?style=flat-square" alt="Bun" />
-  <img src="https://img.shields.io/badge/pulumi-ready-blueviolet?style=flat-square" alt="Pulumi" />
-  <img src="https://img.shields.io/badge/DigitalOcean-App_Platform_|_DOKS-0080FF?style=flat-square" alt="DigitalOcean" />
+  <a href="https://www.npmjs.com/package/@crossdelta/platform-sdk"><img src="https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg?style=for-the-badge&color=cb3837" alt="npm version" /></a>
+  &nbsp;
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/Bun-000000?style=for-the-badge&logo=bun&logoColor=white" alt="Bun" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge" alt="MIT License" />
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/Hono-E36002?style=flat-square&logo=hono&logoColor=white" alt="Hono" />
   <img src="https://img.shields.io/badge/NestJS-E0234E?style=flat-square&logo=nestjs&logoColor=white" alt="NestJS" />
   <img src="https://img.shields.io/badge/NATS-27AAE1?style=flat-square&logo=natsdotio&logoColor=white" alt="NATS" />
+  <img src="https://img.shields.io/badge/Pulumi-8A3391?style=flat-square&logo=pulumi&logoColor=white" alt="Pulumi" />
+  <img src="https://img.shields.io/badge/Turborepo-EF4444?style=flat-square&logo=turborepo&logoColor=white" alt="Turborepo" />
+  <img src="https://img.shields.io/badge/DigitalOcean-0080FF?style=flat-square&logo=digitalocean&logoColor=white" alt="DigitalOcean" />
 </p>
 
----
+<br />
 
-## Who is this for?
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-5-minute-tutorial">Tutorial</a> •
+  <a href="#-commands">Commands</a> •
+  <a href="#-ai-assisted-generation">AI Generation</a> •
+  <a href="#-deployment">Deployment</a>
+</p>
 
-- **Teams building event-driven backends** — NATS, CloudEvents, type-safe contracts
-- **Startups & internal platforms** that want long-term consistency over short-term speed
-- **Engineers tired of infra & app drift** — ports, env vars, deployments always in sync
+---
 
-You can start without understanding all the pieces. The depth reveals itself as you grow.
+<br />
+
+## 👋 Who is this for?
+
+<table>
+<tr>
+<td width="60">🏗️</td>
+<td><strong>Teams building full-stack platforms</strong> — services, events, apps that actually work together</td>
+</tr>
+<tr>
+<td>📡</td>
+<td><strong>Event-driven architectures</strong> — or teams ready to start using events</td>
+</tr>
+<tr>
+<td>😤</td>
+<td><strong>Engineers tired of drift</strong> — ports, env vars, and infra configs that never match</td>
+</tr>
+<tr>
+<td>🚀</td>
+<td><strong>Startups & platform teams</strong> — who want consistency without building everything from scratch</td>
+</tr>
+</table>
+
+> **You can start without understanding all the pieces.**
+> The depth reveals itself as you grow.
 
 ---
 
-## Installation
+## 🚀 Quick Start
 
 ```bash
+# With Bun
 bun add -g @crossdelta/platform-sdk
-# or: npm install -g @crossdelta/platform-sdk
-```
 
-<details>
-<summary>Alternative: Auto-installer or run without installing</summary>
-
-**Unix/macOS:**
-```bash
-# Auto-installer (installs CLI globally, prompts to install Bun if missing)
-curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
-```
-
-**Windows:**
-```powershell
-# Recommended: Use npm directly
+# With npm
 npm install -g @crossdelta/platform-sdk
 
-# Or use WSL (Windows Subsystem for Linux)
-wsl bash -c "curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash"
-```
-
-**Run without installing:**
-```bash
-bunx @crossdelta/platform-sdk new workspace my-platform
-# or: npx @crossdelta/platform-sdk new workspace my-platform
+# Or auto-install (macOS/Linux/WSL)
+curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
 ```
 
-</details>
-
----
-
-## Quick Start
+> **Windows users:** Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience.
 
+**Then create your first platform:**
 ```bash
 pf new workspace my-platform -y && cd my-platform
 pf dev
 ```
 
-**What you get:**
-- Turborepo monorepo with Biome linting
-- NATS + JetStream for event-driven messaging
-- Pulumi infrastructure (`infra/services/*.ts`)
-- Auto-generated `.env.local` with service ports
-
-> **Lockstep by design:**
-> In `pf`, application code and infrastructure are generated from the same source of truth.
-> Service metadata defines ports, env vars, event wiring, and Pulumi configs —
-> eliminating drift between local development, CI, and production.
+<br />
+
+<table>
+<tr>
+<td>✅</td>
+<td>Turborepo monorepo with Biome linting</td>
+</tr>
+<tr>
+<td>✅</td>
+<td>NATS + JetStream for event-driven messaging</td>
+</tr>
+<tr>
+<td>✅</td>
+<td>Pulumi infrastructure ready for deployment</td>
+</tr>
+<tr>
+<td>✅</td>
+<td>Auto-generated <code>.env.local</code> with service ports</td>
+</tr>
+</table>
 
 ---
 
-## 5-Minute Tutorial
+## 🎯 5-Minute Tutorial
 
-After running Quick Start, add services and wire events:
+Add two services and wire an event between them:
 
 ```bash
-# 1. Add two services
+# 1. Create two services
 pf new hono-micro services/orders
 pf new hono-micro services/notifications
 
-# 2. Wire an event between them
+# 2. Wire an event from orders → notifications
 pf event add orders.created --service services/notifications
 
 # 3. Restart to pick up new services
@@ -122,92 +141,194 @@ pf dev
 pf event publish orders.created
 ```
 
-That's it. Two services, one event contract, auto-discovered handlers, no manual wiring.
+<br />
+
+<table>
+<tr>
+<th align="left">What just happened</th>
+</tr>
+<tr>
+<td>
+  📦 Two services with health checks and Pulumi configs<br />
+  📝 One event contract in <code>packages/contracts/</code><br />
+  🔗 One handler that auto-discovers the event<br />
+  ✨ <strong>No manual wiring. No config drift. Everything is explicit.</strong>
+</td>
+</tr>
+</table>
 
 ---
 
-## 🧭 Commands & Options
+## 💡 What problem does pf solve?
+
+<table>
+<tr>
+<th width="300">❌ The Problem</th>
+<th width="300">✅ With pf</th>
+</tr>
+<tr>
+<td>Application code lives here, infra config lives somewhere else</td>
+<td>Both generated from the same source of truth</td>
+</tr>
+<tr>
+<td>Ports, env vars, and event wiring drift over time</td>
+<td>Change a service → infra stays in sync</td>
+</tr>
+<tr>
+<td>New devs spend days setting up local environments</td>
+<td>Run <code>pf dev</code> → everything starts together</td>
+</tr>
+<tr>
+<td>Manual event subscriptions and handler registration</td>
+<td>Add an event → consumers are wired automatically</td>
+</tr>
+</table>
 
-### Service generators
+---
 
-**Hono** (lightweight, Bun-optimized):
-```bash
-pf new hono-micro services/orders
-```
+## 📋 Commands
 
-**NestJS** (full-featured, decorator-based):
-```bash
-pf new nest-micro services/orders
-```
+| Command | What it does |
+|:--------|:-------------|
+| `pf dev` | 🚀 Start NATS + all services in watch mode |
+| `pf new hono-micro <path>` | ⚡ Create a Hono service (lightweight, Bun-optimized) |
+| `pf new nest-micro <path>` | 🏢 Create a NestJS service (full-featured, decorators) |
+| `pf event add <type> --service <path>` | 🔗 Add contract + handler + wire stream |
+| `pf event list` | 📋 List available events and consumers |
+| `pf event publish <type>` | 📤 Publish mock event to NATS |
+| `pf test` | 🧪 Run tests across the monorepo |
+| `pf build` | 📦 Build all packages and services |
+| `pf lint` | ✨ Lint and format with Biome |
+
+> `pf` proxies all commands to Turborepo (works from any subdirectory).
+
+---
 
-Both generate the service structure, Pulumi config in `infra/services/`, and wire everything automatically.
+## 🤖 AI-Assisted Generation
 
-### AI-assisted generation (optional)
+> **Optional but powerful.** Configure once, then use `--ai` with any generator.
 
-Configure once:
 ```bash
 pf setup --ai   # OpenAI or Anthropic
+
+pf new hono-micro services/notifications --ai \
+  -d "Send emails when orders are created"
 ```
 
-Then use `--ai` with any generator:
+AI generates service code, event handlers, use cases, and tests — **all following the same conventions you'd write by hand.**
+
+---
+
+## 🚢 Deployment
+
 ```bash
-pf new hono-micro services/notifications --ai -d "Send emails on order events"
+pf pulumi up --stack dev
 ```
 
-AI generates: service code, event handlers, use cases, tests, and documentation.
-All generated code follows the same conventions and can be written manually.
+**Pre-configured GitHub Actions included:**
 
-### Daily commands
+| Trigger | Action |
+|:--------|:-------|
+| PR to `main` | 🧪 Lint + test |
+| Push to `main` | 🚀 Build, push to GHCR, deploy |
+| Changes in `packages/` | 📦 Publish to npm |
 
-| Command | What it does |
-|---------|--------------|
-| `pf dev` | Start NATS + all services in watch mode |
-| `pf test` | Run tests across the monorepo |
-| `pf lint` | Lint and format with Biome |
-| `pf build` | Build all packages and services |
-| `pf event add <type> --service <path>` | Add contract, mock, handler + wire stream |
-| `pf event list` | List available events and their consumers |
-| `pf event publish <type>` | Publish mock event to NATS |
-| `pf pulumi up` | Deploy infrastructure (runs in `infra/`) |
+<details>
+<summary>🔐 Required secrets</summary>
+
+<br />
+
+| Secret | Description |
+|:-------|:------------|
+| `PULUMI_ACCESS_TOKEN` | [Pulumi Cloud token](https://app.pulumi.com/account/tokens) |
+| `DIGITALOCEAN_TOKEN` | [DO API token](https://cloud.digitalocean.com/account/api/tokens) |
+| `GHCR_TOKEN` | GitHub Container Registry PAT |
+
+</details>
+
+---
 
-`pf` proxies to Turborepo from any subdirectory.
+## 📋 Requirements
 
-### Configuration (advanced)
+| Requirement | Notes |
+|:------------|:------|
+| **Bun** or Node.js ≥ 21 | Bun recommended for speed |
+| **[Pulumi CLI](https://www.pulumi.com/docs/install/)** | For infrastructure deployment |
+| **[Docker](https://www.docker.com/)** | For local NATS |
+
+---
+
+## 🔍 Under the Hood
+
+<details>
+<summary>📁 <b>Project structure</b></summary>
+
+<br />
+
+```
+my-platform/
+├── services/           # Your microservices
+│   ├── orders/
+│   └── notifications/
+├── packages/
+│   └── contracts/      # Event contracts (single source of truth)
+├── infra/
+│   └── services/       # Auto-generated Pulumi configs
+└── .env.local          # Auto-generated from infra
+```
+
+**The key insight:** Services define their ports, env vars, and event subscriptions once. Everything else is derived.
+
+</details>
 
 <details>
-<summary>Workspace configuration via <code>package.json</code></summary>
+<summary>🛠️ <b>Tech stack</b></summary>
+
+<br />
+
+| Layer | Technology |
+|:------|:-----------|
+| Monorepo | [Turborepo](https://turbo.build/repo) |
+| Services | [Hono](https://hono.dev) or [NestJS](https://nestjs.com) |
+| Messaging | [NATS](https://nats.io) + JetStream |
+| Events | [CloudEvents](https://cloudevents.io) + Zod validation |
+| Infrastructure | [Pulumi](https://pulumi.com) → DigitalOcean (extensible) |
+| Runtime | [Bun](https://bun.sh) |
+
+</details>
+
+<details>
+<summary>⚙️ <b>Workspace configuration</b></summary>
+
+<br />
 
 ```json
 {
   "pf": {
-    "registry": "my-platform/platform",
+    "registry": "my-org/my-platform",
     "commands": {
-      "pulumi": { "cwd": "infra" },
       "deploy": { "cwd": "infra", "command": "pulumi up --yes" }
     },
     "paths": {
       "services": { "path": "services", "watch": true },
-      "apps": { "path": "apps", "watch": true },
-      "packages": { "path": "packages", "watch": true },
       "contracts": { "path": "packages/contracts" }
     }
   }
 }
 ```
 
-- `commands`: Custom shortcuts with working directory overrides
-- `paths.<type>.watch`: Enable file watching in dev mode
-- `paths.<type>.ignorePatterns`: Glob patterns to exclude
-
 </details>
 
 <details>
-<summary>Infrastructure configuration via <code>infra/services/*.ts</code></summary>
+<summary>🏗️ <b>Service infrastructure config</b></summary>
 
-```ts
+<br />
+
+```typescript
+// infra/services/orders.ts
 import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
 
-export const config: K8sServiceConfig = {
+const config: K8sServiceConfig = {
   name: 'orders',
   ports: ports().http(4001).build(),
   replicas: 1,
@@ -217,102 +338,21 @@ export const config: K8sServiceConfig = {
     limits: { cpu: '150m', memory: '128Mi' },
   },
 }
+
+export default config
 ```
 
 See [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure) for full options.
 
 </details>
 
----
-
-## 🎯 Why This Exists
-
-`pf` solves platform engineering problems:
-
-- **Infrastructure drift** — Infra configs diverge from code in separate repos
-- **Manual wiring** — Ports, env vars, service discovery configured by hand
-- **Slow onboarding** — New devs spend days setting up local environments
-
-**Solution:** Services auto-generate `infra/services/*.ts`, ports/env derived automatically, event handlers type-safe and auto-discovered.
-
-**In short: docker-compose starts services — `pf` prevents systems from drifting apart over time.**
-
----
-
-## 🧩 What pf Is / Is Not
-
-**✅ pf is:**
-- Opinionated platform toolkit for event-driven microservices
-- Turborepo scaffolder with Pulumi IaC and NATS messaging built-in
-- AI-assisted code generator from natural language descriptions
-- Unified dev workflow — one command to run everything
-- DigitalOcean-first for speed and simplicity — providers replaceable by design
-
-**❌ pf is not:**
-- Generic microservice generator — makes architectural choices for you
-- Multi-cloud out of the box — DigitalOcean first, extensible to other providers
-- Runtime manager — scaffolds code, you deploy with Pulumi
-
-**Note:** `pf` runs nothing implicitly. No hidden daemons, no automatic deployments. You control when code runs and infrastructure deploys.
-
----
-
-## 🏗️ Architecture
-
-```
-my-platform/
-├── services/              # Microservices
-│   ├── nats/              # NATS message broker (auto-scaffolded)
-│   └── <service>/
-│       └── src/
-│           ├── events/    # Event handlers (*.event.ts)
-│           ├── use-cases/ # Business logic (*.use-case.ts)
-│           ├── types/     # Zod schemas
-│           └── index.ts
-├── packages/
-│   └── contracts/         # Event contracts (Schema Registry)
-├── infra/                 # Pulumi Infrastructure-as-Code
-│   └── services/          # Per-service K8s configs
-└── .env.local             # Auto-generated from infra
-```
-
-### Conventions
-
-| Location | Purpose |
-|----------|---------|
-| `services/*/src/events/*.event.ts` | Event handlers (auto-discovered) |
-| `services/*/src/use-cases/*.use-case.ts` | Business logic (pure functions) |
-| `packages/contracts/src/events/*.ts` | Event contracts (single source of truth) |
-| `infra/services/*.ts` | Pulumi configs per service |
-
-> **Schema Registry pattern:**
-> All event contracts live in `packages/contracts` as the single source of truth.
-> Services import contracts instead of redefining schemas, ensuring
-> type safety, compatibility, and explicit ownership across service boundaries.
-
-### Event-Driven Pattern
-
-**Add events with one command:**
-```bash
-# Creates contract, mock, handler, and wires the stream automatically
-pf event add orders.created --service services/notifications
-```
-
-This generates:
-- `packages/contracts/src/events/orders-created.ts` (contract)
-- `packages/contracts/src/events/orders-created.mock.json` (test data)
-- `services/notifications/src/events/orders-created.event.ts` (handler)
-- Adds stream to service `index.ts` if needed
+<details>
+<summary>📡 <b>Event-driven architecture</b></summary>
 
-**Test events locally:**
-```bash
-pf event list              # Show available events
-pf event publish orders.created  # Publish mock event to NATS
-```
+<br />
 
-**Manual pattern (if you prefer):**
+**Contracts** live in `packages/contracts/` as the single source of truth:
 
-**1. Define contract:**
 ```typescript
 // packages/contracts/src/events/orders-created.ts
 import { createContract } from '@crossdelta/cloudevents'
@@ -324,25 +364,27 @@ export const OrdersCreatedContract = createContract({
 })
 ```
 
-**2. Publish (Service A):**
-```typescript
-// services/orders/src/use-cases/create-order.use-case.ts
-await publish(OrdersCreatedContract, { orderId: '123', total: 99.99 })
-```
+**Handlers** import contracts and delegate to use cases:
 
-**3. Handle (Service B, auto-discovered):**
 ```typescript
 // services/notifications/src/events/orders-created.event.ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract } from '@my-org/contracts'
+import { sendOrderNotification } from '../use-cases/send-notification.use-case'
+
 export default handleEvent(OrdersCreatedContract, async (data) => {
   await sendOrderNotification(data)
 })
 ```
 
-No manual subscriptions. Convention over configuration.
+Handlers are auto-discovered. No manual subscriptions.
 
----
+</details>
+
+<details>
+<summary>⚡ <b>NATS message broker</b></summary>
 
-## ⚡ NATS Message Broker
+<br />
 
 Every workspace includes pre-configured NATS with JetStream:
 
@@ -350,46 +392,39 @@ Every workspace includes pre-configured NATS with JetStream:
 - Ports: `4222` (client), `8222` (monitoring)
 - Health check: `curl http://localhost:8222/healthz`
 
-See `services/nats/README.md` for details.
+</details>
 
 ---
 
-##  Deployment
-
-```bash
-pulumi login && pulumi up --stack dev
-```
+## 🧭 Philosophy
 
-### GitHub Actions (pre-configured)
+<table>
+<tr>
+<td width="50%">
 
-| Workflow | Trigger | Purpose |
-|----------|---------|---------|
-| `lint-and-tests.yml` | PR to `main` | Lint + test |
-| `build-and-deploy.yml` | Push to `main` | Build, push to GHCR, deploy |
-| `publish-packages.yml` | Changes in `packages/` | Publish to npm |
+### ✅ What pf is
 
-<details>
-<summary>Required secrets</summary>
+- Opinionated full-stack platform toolkit
+- Unified dev workflow — one command to run everything
+- Infrastructure that stays in sync with your code
 
-| Secret | Description |
-|--------|-------------|
-| `PULUMI_ACCESS_TOKEN` | [Pulumi Cloud token](https://app.pulumi.com/account/tokens) |
-| `DIGITALOCEAN_TOKEN` | [DO API token](https://cloud.digitalocean.com/account/api/tokens) |
-| `GHCR_TOKEN` | GitHub Container Registry PAT |
-| `NPM_TOKEN` | [npm access token](https://www.npmjs.com/settings/~/tokens) (only for `publish-packages.yml`) |
+</td>
+<td width="50%">
 
-</details>
+### ❌ What pf is not
 
----
+- Generic scaffolder — it makes choices for you
+- Multi-cloud out of the box — DigitalOcean first, extensible later
+- Magic — no hidden daemons, you control when things run
 
-## 📚 Requirements
+</td>
+</tr>
+</table>
 
-- **Bun** (recommended) or Node.js ≥ 21
-- **[Pulumi CLI](https://www.pulumi.com/docs/install/)** for deployment
-- **[Docker](https://www.docker.com/)** for local NATS
+> **`pf` makes architectural decisions so your team doesn't have to — without hiding how things work.**
 
 ---
 
-## 📄 License
-
-MIT © Crossdelta
+<p align="center">
+  <strong>MIT © crossdelta</strong>
+</p>