@crossdelta/platform-sdk 0.7.22 → 0.8.0

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
@@ -73,6 +90,32 @@ pf dev
 
 ---
 
+## Day 1 with pf
+
+**5 minutes to your first event-driven system:**
+
+```bash
+# 1. Create a new platform
+pf new workspace my-platform -y && cd my-platform
+
+# 2. Add two services
+pf new hono-micro services/orders
+pf new hono-micro services/notifications
+
+# 3. Wire an event between them
+pf event add orders.created --service services/notifications
+
+# 4. Start everything
+pf dev
+
+# 5. Publish a test event — watch notifications react
+pf event publish orders.created
+```
+
+That's it. Two services, one event contract, auto-discovered handlers, no manual wiring.
+
+---
+
 ## 🧭 How You Work With pf (Happy Paths)
 
 ### Start a new platform
@@ -87,11 +130,17 @@ This scaffolds a complete Turborepo monorepo with NATS, Pulumi infrastructure, G
 
 ### Add a new microservice
 
+**Hono** (lightweight, Bun-optimized):
 ```bash
 pf new hono-micro services/orders
 ```
 
-Or use AI generation:
+**NestJS** (full-featured, decorator-based):
+```bash
+pf new nest-micro services/orders
+```
+
+Or use AI generation with either:
 
 ```bash
 pf new hono-micro services/orders --ai -d "Handle order creation and publish order events"
@@ -125,6 +174,11 @@ 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 new hono-micro <path>` | Create Hono microservice (lightweight) |
+| `pf new nest-micro <path>` | Create NestJS microservice (full-featured) |
+| `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 +246,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 +257,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 +303,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 +387,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>