@crossdelta/platform-sdk 0.7.22 → 0.8.1

package/README.md

@@ -11,7 +11,12 @@
 <p align="center">
   <strong>Opinionated platform toolkit for event-driven microservices.</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.
+  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">
+  <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>
 
 <p align="center">
@@ -26,11 +31,23 @@
 </p>
 
 <p align="center">
-  <em><code>pf</code> enforces conventions that keep application code and cloud infrastructure in lockstep — from local development to production.</em>
+  <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" />
 </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
+
+You can start without understanding all the pieces. The depth reveals itself as you grow.
+
+---
+
 ## Installation
 
 ```bash
@@ -41,12 +58,25 @@ bun add -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
+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"
+```
 
-# Or run directly without installing
+**Run without installing:**
+```bash
 bunx @crossdelta/platform-sdk new workspace my-platform
+# or: npx @crossdelta/platform-sdk new workspace my-platform
 ```
 
 </details>
@@ -73,49 +103,59 @@ pf dev
 
 ---
 
-## 🧭 How You Work With pf (Happy Paths)
+## 5-Minute Tutorial
 
-### Start a new platform
+After running Quick Start, add services and wire events:
 
 ```bash
-pf new workspace my-platform --github-owner my-org --pulumi-stack dev -y
-cd my-platform
+# 1. Add two services
+pf new hono-micro services/orders
+pf new hono-micro services/notifications
+
+# 2. Wire an event between them
+pf event add orders.created --service services/notifications
+
+# 3. Restart to pick up new services
 pf dev
+
+# 4. Publish a test event — watch notifications react
+pf event publish orders.created
 ```
 
-This scaffolds a complete Turborepo monorepo with NATS, Pulumi infrastructure, GitHub Actions workflows, and auto-generated environment variables.
+That's it. Two services, one event contract, auto-discovered handlers, no manual wiring.
+
+---
+
+## 🧭 Commands & Options
 
-### Add a new microservice
+### Service generators
 
+**Hono** (lightweight, Bun-optimized):
 ```bash
 pf new hono-micro services/orders
 ```
 
-Or use AI generation:
-
+**NestJS** (full-featured, decorator-based):
 ```bash
-pf new hono-micro services/orders --ai -d "Handle order creation and publish order events"
+pf new nest-micro services/orders
 ```
 
 Both generate the service structure, Pulumi config in `infra/services/`, and wire everything automatically.
 
-### Generate with AI (optional)
-
-Configure your AI provider once:
+### AI-assisted generation (optional)
 
+Configure once:
 ```bash
 pf setup --ai   # OpenAI or Anthropic
 ```
 
-Then use `--ai` with any service generator:
-
+Then use `--ai` with any generator:
 ```bash
 pf new hono-micro services/notifications --ai -d "Send emails on order events"
 ```
 
 AI generates: service code, event handlers, use cases, tests, and documentation.
-
-AI is a productivity layer — all generated code follows the same conventions and can be written manually without loss of functionality.
+All generated code follows the same conventions and can be written manually.
 
 ### Daily commands
 
@@ -125,6 +165,9 @@ AI is a productivity layer — all generated code follows the same conventions a
 | `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/`) |
 
 `pf` proxies to Turborepo from any subdirectory.
@@ -192,7 +235,7 @@ See [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infra
 
 **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.
+**In short: docker-compose starts services — `pf` prevents systems from drifting apart over time.**
 
 ---
 
@@ -203,11 +246,11 @@ In short: docker-compose starts services — `pf` prevents systems from drifting
 - 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 deployment target
+- DigitalOcean-first for speed and simplicity — providers replaceable by design
 
 **❌ pf is not:**
 - Generic microservice generator — makes architectural choices for you
-- Multi-cloud (not yet) — DigitalOcean first, extensible architecture
+- 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.
@@ -249,6 +292,26 @@ my-platform/
 
 ### 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
@@ -313,6 +376,7 @@ pulumi login && pulumi up --stack dev
 | `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`) |
 
 </details>