@crossdelta/platform-sdk 0.5.13 → 0.7.0

package/README.md

@@ -26,44 +26,85 @@
   <img src="https://img.shields.io/badge/DigitalOcean-App_Platform_|_DOKS-0080FF?style=flat-square" alt="DigitalOcean" />
 </p>
 
+<p align="center">
+  <em><code>pf</code> is not a framework — it's a set of conventions that wire code and infrastructure together.</em>
+</p>
+
 <br />
 
 ---
 ## 🚀 Quick Start
 
 ```bash
-# Create workspace (works with npx/yarn/pnpm too)
+# Create workspace (works with bunx/npx/pnpm dlx/yarn dlx)
 bunx @crossdelta/platform-sdk new workspace my-platform -y
 cd my-platform
 
-# Generate service with AI
-# (first time: you'll be prompted to configure an AI provider)
+# Generate microservice with AI (first time: run `pf setup --ai` to configure provider)
 bunx @crossdelta/platform-sdk new hono-micro services/orders --ai \
-  -d "Handle order creation and payment processing"
+  -d "Handle order creation and payment"
 
-# Start all services (or: npm run dev)
-bun dev
+# Start development
+pf dev
 ```
 
-**In under a minute you have a running, event-driven microservice platform with infra parity between local and production.**
+**What you get in minutes:**
 
-You get: [Turborepo](https://turbo.build/repo) monorepo + [NATS](https://nats.io) + event-driven microservices + [Pulumi](https://www.pulumi.com) infra + auto-generated `.env.local` + **AI-generated services** — all wired automatically.
+- ✔ Turborepo monorepo with Biome linting
+- ✔ NATS + event-driven microservices
+- ✔ Pulumi infrastructure (`infra/services/*.ts`)
+- ✔ Auto-generated `.env.local` with service ports
+- ✔ AI-generated service code
 
-<details>
-<summary><strong>💡 Prefer shorter commands? Install globally (Bun/npm/yarn/pnpm)</strong></summary>
+All wired automatically. Local + production infra in lockstep.
+
+### ⚡ One CLI for everything
+
+`pf` runs your workspace scripts from anywhere:
 
 ```bash
-# With Bun (recommended)
-bun add -g @crossdelta/platform-sdk
+pf test         # → turbo run test
+pf build        # → turbo run build
+pf pulumi up    # → runs in infra/ directory
+```
+
+**Why:** Keeps commands consistent across the team and works from any subdirectory.
+
+**How it works:** `pf` walks up to find your workspace root, then proxies to your scripts. Configured commands via `pf.commands` can override the working directory or command. Registered `pf` commands (like `pf new`) take precedence.
+
+> **📖 Note:** You can be productive with `pf` in minutes using the commands above. The sections below are reference documentation—explore them when you need specific details.
+
+### No runtime installed?
+
+If you don't have a JavaScript runtime, use our installer that sets everything up.
+**The installer is optional** — you can always use `bunx`/`npx` or a global install.
 
-# With npm/yarn/pnpm
-npm install -g @crossdelta/platform-sdk
+```bash
+# Auto-installer (detects bun/pnpm/yarn/npm; if none found it can install Bun)
+curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
 
 # Then use short commands
 pf new workspace my-platform
 pf new hono-micro services/orders --ai -d "..."
 ```
 
+> **Security:** The installer asks permission before installing Bun (if needed) and does not run any workspace commands automatically.
+
+<details>
+<summary><strong>🔍 What does the installer do?</strong></summary>
+
+The script ([view source](https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh)):
+1. Checks for bun/pnpm/yarn/npm
+2. If none found, **asks permission** to install Bun
+3. Installs `pf` CLI globally
+
+**Manual installation:**
+```bash
+# With Bun/npm/yarn/pnpm
+bun add -g @crossdelta/platform-sdk
+# or: npm install -g @crossdelta/platform-sdk
+```
+
 </details>
 
 <br />
@@ -91,7 +132,7 @@ pf new hono-micro services/orders --ai -d "..."
 - **Opinionated CLI** for event-driven microservice platforms
 - **[Turborepo](https://turbo.build/repo) scaffolder** with [Pulumi](https://www.pulumi.com) IaC and [NATS](https://nats.io) messaging built-in
 - **AI-assisted code generator** that creates service boilerplate from descriptions
-- **Unified dev workflow** — one command to run all services (`bun dev`)
+- **Unified dev workflow** — one command to run all services (`pf dev`)
 - **[DigitalOcean](https://www.digitalocean.com)-first** deployment target (App Platform + DOKS)
 
 ### ❌ `pf` is not:
@@ -101,6 +142,8 @@ pf new hono-micro services/orders --ai -d "..."
 - **Runtime manager** — scaffolds code, you deploy with Pulumi
 - **Kubernetes replacement** — generates K8s configs via Pulumi
 
+**Note:** `pf` runs nothing implicitly—no hidden daemons, no automatic deployments or provisioning. You maintain explicit control over when code runs and infrastructure is deployed.
+
 ### 🔥 Why `pf` vs other tools?
 
 - **🔗 Lockstep infra + code** — `infra/services/*.ts` auto-generated from service metadata, ports/env derived automatically
@@ -141,7 +184,7 @@ my-platform/
 1. **NATS + JetStream baseline** — Event-driven communication is built-in, not bolted on
 2. **Infrastructure-as-Code by default** — Every service has a matching `infra/services/<name>.ts` config
 3. **Auto-wiring everywhere** — Ports, env vars, and NATS subjects are derived automatically
-4. **Opinionated conventions** — Event handlers live in `src/handlers/*.event.ts`, business logic in `src/use-cases/*.use-case.ts`
+4. **Opinionated conventions** — Event handlers live in `src/events/*.event.ts`, business logic in `src/use-cases/*.use-case.ts`
 5. **Bun-first DX** — Ultra-fast installs, tests, and dev server with fallback to npm/yarn
 
 ### Event-Driven Mental Model
@@ -153,7 +196,7 @@ Services communicate via **CloudEvents** over **NATS JetStream**:
 await publish('orders.created', { orderId: '123', total: 99.99 })
 
 // Service B auto-discovers and handles it
-// File: services/notifications/src/handlers/order-created.event.ts
+// File: services/notifications/src/events/order-created.event.ts
 export default handleEvent(
   { schema: OrderCreatedSchema, type: 'orders.created' },
   async (data) => { await sendNotification(data) }
@@ -186,6 +229,15 @@ These principles guide every decision in `pf`:
 
 `pf` is designed for **small to mid-sized teams building event-driven systems** who want strong conventions, infra parity, and fast onboarding — without maintaining their own internal platform.
 
+<br />
+
+---
+
+## 📚 Deep Dive & Reference
+
+The sections below cover architectural details, workflows, and advanced usage.
+**You don't need to read them to get started** — they're here when you need them.
+
 ---
 
 ## 📘 Workflows
@@ -220,7 +272,7 @@ pf new hono-micro services/payments --ai \
 
 ```bash
 cd my-platform
-bun dev
+pf dev
 ```
 
 This will:
@@ -233,15 +285,55 @@ This will:
 
 ```bash
 # Run all tests across the monorepo
-bun test
+pf test
 
 # Lint and format all code with Biome
-bun lint
+pf lint
 
 # Build all packages and services
-bun run build
+pf build
 ```
 
+### 5. Workspace Configuration
+
+Configure workspace behavior via the `pf` field in your root `package.json`:
+
+```json
+{
+  "pf": {
+    "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,
+        "ignorePatterns": ["packages/some-internal-package"]
+      },
+      "contracts": {
+        "path": "packages/contracts"
+      }
+    }
+  }
+}
+```
+
+**Options:**
+- `commands`: Custom command shortcuts with `cwd` (working directory) and `command` overrides
+- `paths.<type>.path`: Directory path for each workspace type
+- `paths.<type>.watch`: Whether to watch this directory in dev mode (default: `false`)
+- `paths.<type>.ignorePatterns`: Glob patterns to ignore within this path (optional)
+
 <br />
 
 ---
@@ -250,7 +342,10 @@ bun run build
 
 Here's how developers actually use `pf` in real-world scenarios:
 
-### Workflow 1: Start a New Platform
+<details>
+<summary><strong>Workflow 1: Start a New Platform</strong></summary>
+
+<br />
 
 You're building a new product from scratch and want to establish a solid foundation.
 
@@ -270,7 +365,7 @@ cd my-platform
 # - Database instance sizes
 
 # Step 3: Start local development
-bun dev
+pf dev
 ```
 
 **What you get:**
@@ -280,182 +375,23 @@ bun dev
 - ✅ GitHub Actions workflows for CI/CD
 - ✅ `.env.local` auto-generated with all service ports
 
-**Time to first service running:** ~60 seconds
+</details>
 
 ---
 
 ### Workflow 2: Add a New Microservice
 
-Your platform is growing and you need to add a new service for handling payments.
-
-**Option A: Manual scaffolding (fast, predictable)**
-
-```bash
-# Generate a lightweight Hono microservice
-pf new hono-micro services/payments -y
-
-# What gets auto-generated:
-# ✅ services/payments/src/index.ts (Hono server)
-# ✅ services/payments/src/handlers/*.event.ts (example event handler)
-# ✅ infra/services/payments.ts (Pulumi K8s config)
-# ✅ services/payments/README.md (service documentation)
-# ✅ Dockerfile + package.json with scripts
-# ✅ Auto-assigned port (e.g., 4003)
-
-# Start the service
-bun dev
-```
-
-**Option B: AI-powered generation (intelligent scaffolding)**
-
 ```bash
-# First time: configure AI provider
-pf setup --ai
-
-# Generate service boilerplate with AI
+# Generate with AI (optional: use --ai flag)
 pf new hono-micro services/payments --ai \
-  -d "Stripe payment processing: handle checkout.session.completed webhooks, \
-      publish payment.succeeded events, update order status in database"
-
-# AI generates:
-# ✅ Service structure with Stripe SDK integration
-# ✅ Event handler stubs for incoming webhooks
-# ✅ Event publisher functions for payment lifecycle
-# ✅ Use case templates with validation logic
-# ✅ Test file boilerplate
-# ✅ Environment variable documentation
-# ✅ Basic README with usage examples
-```
-
-**When to use which:**
-- **Manual scaffolding:** You know exactly what you're building, want full control
-- **AI generation:** Quick prototyping, exploring new integrations, generating boilerplate faster
-
-**Note:** AI-generated code is a starting point, not production-ready. Always review and refine.
-
----
-
-### Workflow 3: Build an Event-Driven Feature
-
-You want to send notifications whenever a new order is created.
+  -d "Stripe payment processing: handle webhooks, publish events"
 
-**Step 1: Create the notification service**
-
-```bash
-pf new hono-micro services/notifications -y
-```
-
-**Step 2: Implement the event handler**
-
-```typescript
-// services/notifications/src/handlers/order-created.event.ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-import { sendNotification } from '../use-cases/send-notification.use-case'
-
-const OrderCreatedSchema = z.object({
-  orderId: z.string(),
-  customerId: z.string(),
-  total: z.number(),
-  items: z.array(
-    z.object({
-      productId: z.string(),
-      quantity: z.number(),
-      price: z.number(),
-    }),
-  ).optional(),
-})
-
-// Export type for use in use-cases
-export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
-
-export default handleEvent(
-  {
-    schema: OrderCreatedSchema,
-    type: 'orders.created',  // Event type to subscribe to
-  },
-  async (data) => {
-    await sendNotification(data)
-  },
-)
-```
-
-**Step 3: Implement the use case**
-
-```typescript
-// services/notifications/src/use-cases/send-notification.use-case.ts
-import type { OrderCreatedEvent } from '../handlers/order-created.event'
-
-export async function sendNotification(data: OrderCreatedEvent): Promise<void> {
-  // Full type inference from the event handler schema
-  console.log(`Sending notification for order: ${data.orderId}`)
-
-  // Your notification logic here:
-  // - Send email via SendGrid
-  // - Push notification via Firebase
-  // - SMS via Twilio
-}
-```
-
-**Step 4: Start consuming events**
-
-```typescript
-// services/notifications/src/index.ts
-import '@crossdelta/telemetry'  // Must be first import
-
-import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
-import { Hono } from 'hono'
-
-const port = Number(process.env.PORT || process.env.NOTIFICATIONS_PORT) || 4002
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-// Auto-discover and register all event handlers
-consumeJetStreamEvents({
-  stream: 'ORDERS',
-  subjects: ['orders.>'],  // Subscribe to all orders.* events
-  consumer: 'notifications',
-  discover: './src/handlers/**/*.event.ts',
-})
-
-Bun.serve({ port, fetch: app.fetch })
-```
-
-**Step 5: Publish events from the orders service**
-
-```typescript
-// services/orders/src/routes/create-order.ts
-import { publish } from '@crossdelta/cloudevents'
-
-export async function createOrder(orderData) {
-  const order = await db.orders.create(orderData)
-
-  // Publish event to NATS
-  await publish('orders.created', {
-    orderId: order.id,
-    customerId: order.customerId,
-    total: order.total,
-    items: order.items,
-  })
-
-  return order
-}
+# Auto-generated: service code + infra config + tests + README
+# Start the service
+pf dev
 ```
 
-**How it works:**
-1. **Publishing:** `publish()` sends a CloudEvent to NATS JetStream
-2. **Auto-discovery:** `consumeJetStreamEvents()` scans `src/handlers/*.event.ts` and registers handlers
-3. **Type safety:** Zod schema validates incoming events, provides TypeScript types
-4. **Decoupling:** Services don't know about each other, only about events
-
-**Benefits:**
-- ✅ Zero boilerplate for NATS subscriptions
-- ✅ Type-safe event handling with Zod
-- ✅ Automatic retries and error handling (JetStream guarantees)
-- ✅ Easy to add new consumers without touching existing services
-
-<br />
+**AI generates:** Service structure, event handlers, use cases, tests, and documentation. Always review before deploying.
 
 ---
 
@@ -498,7 +434,7 @@ await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
 ### Consume Events (Auto-Discovered)
 
 ```typescript
-// services/notifications/src/handlers/order-created.event.ts
+// services/notifications/src/events/order-created.event.ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
@@ -550,14 +486,14 @@ export default handleEvent(
 | `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
+### Event Testing
 
 | Command | Description |
 |---------|-------------|
-| `pf generate event-handler <name>` | Generate an event handler |
-| `pf generate use-case <name>` | Generate a use case |
+| `pf event:generate <path>` | Generate event mocks from event handlers |
 | `pf event:list` | List all available event mocks |
-| `pf event:send <name>` | Send a test event to NATS |
+| `pf event:publish <name>` | Publish to NATS JetStream |
+| `pf event:http <name>` | Send via HTTP Pub/Sub endpoint |
 
 ### Utility Commands
 
@@ -643,8 +579,8 @@ Configure these secrets in your repository settings (`Settings` → `Secrets and
 
 ## 📚 Requirements
 
-- **[Bun](https://bun.sh)** (latest) — recommended for best performance
-- **Node.js** ≥ 21 — supported as fallback (npm/yarn/pnpm)
+- **JavaScript runtime** — Bun (recommended) or Node.js ≥ 21 (npm/yarn/pnpm)
+  _No runtime? Use our [installer](#no-nodejsbun-installed) — it sets up Bun automatically_
 - **[Pulumi CLI](https://www.pulumi.com/docs/install/)** — for infrastructure deployment
 - **[Docker](https://www.docker.com/)** — required for local NATS. Without Docker, you can still scaffold/build