@crossdelta/platform-sdk 0.8.4 → 0.8.31

package/README.md

@@ -1,137 +1,118 @@
 <p align="center">
-  <img src="https://unpkg.com/@crossdelta/platform-sdk/logo.png" alt="pf" width="140" />
+  <img src="https://unpkg.com/@crossdelta/platform-sdk/logo.png" alt="pf" width="120" />
 </p>
 
 <h1 align="center">Platform SDK</h1>
 
 <p align="center">
-  <strong>The platform toolkit for backend + infrastructure.</strong>
+  <code>@crossdelta/platform-sdk</code>
 </p>
 
 <p align="center">
-  <code>pf</code> scaffolds real-world platforms: backend services, event-driven messaging, infrastructure — all wired together and kept in sync.
+  <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.
 </p>
 
 <p align="center">
-  <sub>Fontend SDK coming soon — contract-based client models.</sub>
-
+  <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>
 
-<br />
+<p align="center">
+  <em>Includes optional AI-assisted service generation (OpenAI / Anthropic).</em>
+</p>
 
 <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=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" />
+  <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" />
 </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 />
+---
 
-<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>
+## Who is this for?
 
----
+- **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
 
-<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.
+You can start without understanding all the pieces. The depth reveals itself as you grow.
 
 ---
 
-## 🚀 Quick Start
+## Installation
 
 ```bash
-# With Bun
 bun add -g @crossdelta/platform-sdk
+# or: npm install -g @crossdelta/platform-sdk
+```
 
-# With npm
-npm install -g @crossdelta/platform-sdk
+<details>
+<summary>Alternative: Auto-installer or run without installing</summary>
 
-# Or auto-install (macOS/Linux/WSL)
+**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 users:** Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience.
+**Windows:**
+```powershell
+# Recommended: Use npm directly
+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
+```
+
+</details>
+
+---
+
+## Quick Start
 
-**Then create your first platform:**
 ```bash
 pf new workspace my-platform -y && cd my-platform
 pf dev
 ```
 
-<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>
+**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.
 
 ---
 
-## 🎯 5-Minute Tutorial
+## 5-Minute Tutorial
 
-Add two services and wire an event between them:
+After running Quick Start, add services and wire events:
 
 ```bash
-# 1. Create two services
+# 1. Add two services
 pf new hono-micro services/orders
 pf new hono-micro services/notifications
 
-# 2. Wire an event from orders → notifications
+# 2. Wire an event between them
 pf event add orders.created --service services/notifications
 
 # 3. Restart to pick up new services
@@ -141,194 +122,92 @@ pf dev
 pf event publish orders.created
 ```
 
-<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>
-
----
-
-## 💡 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>
-
----
-
-## 📋 Commands
-
-| 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).
+That's it. Two services, one event contract, auto-discovered handlers, no manual wiring.
 
 ---
 
-## 🤖 AI-Assisted Generation
+## 🧭 Commands & Options
 
-> **Optional but powerful.** Configure once, then use `--ai` with any generator.
+### Service generators
 
+**Hono** (lightweight, Bun-optimized):
 ```bash
-pf setup --ai   # OpenAI or Anthropic
-
-pf new hono-micro services/notifications --ai \
-  -d "Send emails when orders are created"
+pf new hono-micro services/orders
 ```
 
-AI generates service code, event handlers, use cases, and tests — **all following the same conventions you'd write by hand.**
-
----
-
-## 🚢 Deployment
-
+**NestJS** (full-featured, decorator-based):
 ```bash
-pf pulumi up --stack dev
+pf new nest-micro services/orders
 ```
 
-**Pre-configured GitHub Actions included:**
-
-| Trigger | Action |
-|:--------|:-------|
-| PR to `main` | 🧪 Lint + test |
-| Push to `main` | 🚀 Build, push to GHCR, deploy |
-| Changes in `packages/` | 📦 Publish to npm |
-
-<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>
-
----
-
-## 📋 Requirements
-
-| 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>
+Both generate the service structure, Pulumi config in `infra/services/`, and wire everything automatically.
 
-<br />
+### AI-assisted generation (optional)
 
+Configure once:
+```bash
+pf setup --ai   # OpenAI or Anthropic
 ```
-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
+
+Then use `--ai` with any generator:
+```bash
+pf new hono-micro services/notifications --ai -d "Send emails on order events"
 ```
 
-**The key insight:** Services define their ports, env vars, and event subscriptions once. Everything else is derived.
+AI generates: service code, event handlers, use cases, tests, and documentation.
+All generated code follows the same conventions and can be written manually.
 
-</details>
+### Daily commands
 
-<details>
-<summary>🛠️ <b>Tech stack</b></summary>
-
-<br />
+| 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/`) |
 
-| 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) |
+`pf` proxies to Turborepo from any subdirectory.
 
-</details>
+### Configuration (advanced)
 
 <details>
-<summary>⚙️ <b>Workspace configuration</b></summary>
-
-<br />
+<summary>Workspace configuration via <code>package.json</code></summary>
 
 ```json
 {
   "pf": {
-    "registry": "my-org/my-platform",
+    "registry": "my-platform/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>🏗️ <b>Service infrastructure config</b></summary>
+<summary>Infrastructure configuration via <code>infra/services/*.ts</code></summary>
 
-<br />
-
-```typescript
-// infra/services/orders.ts
+```ts
 import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
 
-const config: K8sServiceConfig = {
+export const config: K8sServiceConfig = {
   name: 'orders',
   ports: ports().http(4001).build(),
   replicas: 1,
@@ -338,21 +217,102 @@ 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>
 
-<details>
-<summary>📡 <b>Event-driven architecture</b></summary>
+---
+
+## 🎯 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
 
-<br />
+| 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 |
 
-**Contracts** live in `packages/contracts/` as the single source of truth:
+> **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
+
+**Test events locally:**
+```bash
+pf event list              # Show available events
+pf event publish orders.created  # Publish mock event to NATS
+```
+
+**Manual pattern (if you prefer):**
+
+**1. Define contract:**
 ```typescript
 // packages/contracts/src/events/orders-created.ts
 import { createContract } from '@crossdelta/cloudevents'
@@ -364,27 +324,25 @@ export const OrdersCreatedContract = createContract({
 })
 ```
 
-**Handlers** import contracts and delegate to use cases:
+**2. Publish (Service A):**
+```typescript
+// services/orders/src/use-cases/create-order.use-case.ts
+await publish(OrdersCreatedContract, { orderId: '123', total: 99.99 })
+```
 
+**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)
 })
 ```
 
-Handlers are auto-discovered. No manual subscriptions.
-
-</details>
+No manual subscriptions. Convention over configuration.
 
-<details>
-<summary>⚡ <b>NATS message broker</b></summary>
+---
 
-<br />
+## ⚡ NATS Message Broker
 
 Every workspace includes pre-configured NATS with JetStream:
 
@@ -392,39 +350,46 @@ Every workspace includes pre-configured NATS with JetStream:
 - Ports: `4222` (client), `8222` (monitoring)
 - Health check: `curl http://localhost:8222/healthz`
 
-</details>
+See `services/nats/README.md` for details.
 
 ---
 
-## 🧭 Philosophy
+##  Deployment
+
+```bash
+pulumi login && pulumi up --stack dev
+```
 
-<table>
-<tr>
-<td width="50%">
+### GitHub Actions (pre-configured)
 
-### ✅ What pf is
+| 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 |
 
-- Opinionated full-stack platform toolkit
-- Unified dev workflow — one command to run everything
-- Infrastructure that stays in sync with your code
+<details>
+<summary>Required secrets</summary>
 
-</td>
-<td width="50%">
+| 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`) |
 
-### ❌ What pf is not
+</details>
 
-- 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
+---
 
-</td>
-</tr>
-</table>
+## 📚 Requirements
 
-> **`pf` makes architectural decisions so your team doesn't have to — without hiding how things work.**
+- **Bun** (recommended) or Node.js ≥ 21
+- **[Pulumi CLI](https://www.pulumi.com/docs/install/)** for deployment
+- **[Docker](https://www.docker.com/)** for local NATS
 
 ---
 
-<p align="center">
-  <strong>MIT © crossdelta</strong>
-</p>
+## 📄 License
+
+MIT © Crossdelta