@crossdelta/platform-sdk 0.3.21 → 0.3.23

package/README.md

@@ -14,29 +14,37 @@
   with natural language, and deploy to the cloud — all from one CLI.
 </p>
 
+<p align="center">
+  <strong>🚀 Scaffold • 🤖 Generate • ☁️ Deploy</strong>
+</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=flat-square" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@crossdelta/platform-sdk"><img src="https://img.shields.io/npm/dm/@crossdelta/platform-sdk?style=flat-square" alt="Downloads" /></a>
+  <img src="https://img.shields.io/bundlephobia/min/@crossdelta/platform-sdk?style=flat-square&label=size" alt="Package size" />
   <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>
 
+<br />
+
 ---
 
-## 👤 Who is this for?
+## Who is this for?
 
 - You run **multiple microservices** and want a unified developer experience
 - You prefer **monorepos + Infrastructure-as-Code** as your architectural baseline
 - You're okay with **DigitalOcean as the initial cloud provider** (AWS/GCP coming soon)
 
----
-
 > ⚠️ **Cloud Provider Support:** Currently only **DigitalOcean** is supported:
 > - **App Platform** — Managed PaaS for simple deployments
 > - **DOKS (Kubernetes)** — Full Kubernetes control for production workloads
 >
 > **AWS and GCP support** is planned for future releases.
 
+<br />
+
 ---
 
 ## ✨ Features
@@ -54,18 +62,24 @@
 | 🔌 **Auto Port Assignment** | Unique ports per service |
 | 🔁 **Smart Watch Mode** | Watches infra & services, regenerates env, reinstalls deps |
 
+<br />
+
 ---
 
 ## 🚀 Quick Start
 
+> 💡 **Get started in under 2 minutes**
+
 ### 1. Create a new workspace
 
 ```bash
+# Install globally
 npm install -g @crossdelta/platform-sdk
 pf new workspace my-platform
 
-# Or with bunx:
-bunx @crossdelta/platform-sdk pf new workspace my-platform
+# Or use directly with npx/bunx (no installation required)
+npx @crossdelta/platform-sdk new workspace my-platform
+bunx @crossdelta/platform-sdk new workspace my-platform
 ```
 
 **Options:**
@@ -77,30 +91,45 @@ bunx @crossdelta/platform-sdk pf new workspace my-platform
 | `-s, --pulumi-stack <name>` | Pulumi stack base name |
 | `--no-github` | Skip GitHub Actions workflows |
 
----
-
 ### 2. Generate microservices
 
+**Manual scaffolding:**
 ```bash
 pf new hono-micro services/orders
 pf new nest-micro services/api-gateway
 ```
 
-With AI:
-
+**AI-powered generation:**
 ```bash
-pf new hono-micro services/payments --ai -d "Handle payment webhooks"
+# First time: configure AI provider (OpenAI or Anthropic)
 pf setup --ai
+
+# Generate service with AI
+pf new hono-micro services/payments --ai \
+  -d "Handle Stripe webhooks and send payment confirmations"
 ```
 
----
+**✨ AI generates:**
+- ✅ Complete service with event handlers & use cases
+- ✅ Pulumi infrastructure configuration
+- ✅ Test files with validation logic
+- ✅ Complete README documentation
 
 ### 3. Start local development
 
 ```bash
+cd my-platform
 pf dev
 ```
 
+This will:
+- 🔄 Auto-generate `.env.local` from infrastructure config
+- 🚀 Start all services in watch mode
+- 🔌 Auto-assign unique ports per service
+- 📦 Install dependencies when `package.json` changes
+
+<br />
+
 ---
 
 ## 📁 Workspace Structure
@@ -123,18 +152,90 @@ my-platform/
 └── biome.json
 ```
 
+<br />
+
+---
+
+## ⚡ Event-Driven Architecture
+
+Built on **CloudEvents** and **NATS JetStream** using **[`@crossdelta/cloudevents`](https://github.com/orderboss/platform/tree/main/packages/cloudevents)**:
+
+- 🎯 **Type-safe event handlers** with Zod schemas
+- 🔄 **Auto-discovery** of event handlers (`*.event.ts` files)
+- 📦 **Publisher/Consumer patterns** out of the box
+- 🚀 **Production-ready** NATS JetStream integration
+
+**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/handlers/order-created.event.ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+const OrderCreatedSchema = z.object({
+  type: z.literal('orders.created'),
+  orderId: z.string(),
+  total: z.number(),
+})
+
+export default handleEvent(OrderCreatedSchema, async (data) => {
+  await sendNotification(data)
+})
+```
+
+<br />
+
 ---
 
 ## 🛠 CLI Commands
 
+<details>
+<summary><strong>📖 View Full Command Reference</strong></summary>
+
+<br />
+
+### Workspace Commands
+
+| Command | Description |
+|---------|-------------|
+| `pf new` | Interactive creation wizard |
+| `pf new workspace <name>` | Scaffold a complete platform monorepo |
+| `pf setup --ai` | Configure AI provider (OpenAI or Anthropic) |
+| `pf dev [options]` | Start development environment with hot reload |
+
+### Service Commands
+
+| Command | Description |
+|---------|-------------|
+| `pf new hono-micro <path>` | Generate a Hono microservice (lightweight) |
+| `pf new nest-micro <path>` | Generate a NestJS microservice (enterprise-grade) |
+| `pf new hono-micro <path> --ai` | Generate service with AI (requires `pf setup --ai`) |
+
+### Code Generation
+
+| Command | Description |
+|---------|-------------|
+| `pf generate event-handler <name>` | Generate an event handler |
+| `pf generate use-case <name>` | Generate a use case |
+| `pf event:list` | List all available event mocks |
+| `pf event:send <name>` | Send a test event to NATS |
+
+### Utility Commands
+
 | Command | Description |
 |---------|-------------|
-| `pf new` | Interactive creation |
-| `pf new workspace <name>` | Scaffold a complete platform |
-| `pf new hono-micro <path>` | Generate a Hono microservice |
-| `pf new nest-micro <path>` | Generate a NestJS microservice |
-| `pf setup --ai` | Configure AI provider |
-| `pf dev` | Start dev environment |
+| `pf --version` | Show version information |
+| `pf --help` | Show help for any command |
+
+</details>
+
+<br />
 
 ---
 
@@ -155,6 +256,8 @@ export const config: K8sServiceConfig = {
 }
 ```
 
+<br />
+
 ---
 
 ## 🚢 Deployment
@@ -170,6 +273,8 @@ GitHub Secrets:
 - `DIGITALOCEAN_TOKEN`
 - `NPM_TOKEN` (optional)
 
+<br />
+
 ---
 
 ## 📚 Requirements
@@ -179,6 +284,7 @@ GitHub Secrets:
 - Pulumi CLI
 - Docker (for local Supabase/NATS)
 
+
 ---
 
 ## 📄 License