@crossdelta/platform-sdk 0.3.42 → 0.4.1

package/README.md

@@ -30,36 +30,116 @@
 
 ---
 
-## Who is this for?
+## 🎯 Why This Exists
 
-- 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)
+Building microservice platforms is hard. You start with great intentions, but complexity creeps in fast:
 
-> ⚠️ **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.
+- **Scattered repositories** with inconsistent conventions across services
+- **No unified DX** — every team member invents their own scripts
+- **Infrastructure drift** — Terraform/Pulumi configs live in separate repos
+- **Environment hell** — `.env` files manually maintained, ports collide, services don't talk
+- **Slow onboarding** — new developers spend days setting up the platform
+
+**`pf` acts like an opinionated platform engineer on your team.** It's a single CLI that:
+
+- Scaffolds production-ready monorepos with best practices baked in
+- Generates microservices (manually or with AI) with consistent structure
+- Auto-wires infrastructure, environment variables, and port assignments
+- Unifies your dev workflow: one command to run everything locally
+
+Built for teams using **Turborepo + Pulumi + NATS + Bun** who want to move fast without sacrificing quality.
 
 <br />
 
 ---
 
-## ✨ Features
+## 🧩 What This SDK Is / Is Not
 
-| Feature | Description |
-|---------|-------------|
-| ⚡ **Instant Scaffolding** | Create fully wired platform workspaces with best practices baked in |
-| 🤖 **AI-Powered Generation** | Generate services with AI using `--ai` flag (OpenAI/Anthropic) |
-| 🥟 **Bun-first DX** | Ultra-fast dev workflow with fallback to npm/yarn/pnpm |
-| 🏗️ **Turborepo Monorepo** | Parallel builds, caching, and unified dev scripts |
-| 🔧 **Service Generators** | Hono (lightweight) and NestJS (enterprise-grade) templates |
-| 📦 **Pulumi-Ready Infra** | Infrastructure-as-Code for DigitalOcean |
-| 🚀 **GitHub Actions CI/CD** | Pre-configured workflows for build, test, deploy, and npm publish |
-| 🌍 **Auto `.env.local`** | Environment variables derived from `infra/services/*.ts` |
-| 🔌 **Auto Port Assignment** | Unique ports per service |
-| 🔁 **Smart Watch Mode** | Watches infra & services, regenerates env, reinstalls deps |
+### ✅ `pf` is:
+
+- **Opinionated CLI** for event-driven microservice platforms
+- **Turborepo scaffolder** with Pulumi IaC and NATS messaging built-in
+- **AI-powered code generator** that creates complete services from natural language
+- **Unified dev workflow** — one command to rule them all (`bun dev`)
+- **DigitalOcean-first** deployment target (App Platform + DOKS)
+
+### ❌ `pf` is not:
+
+- **Not a generic microservice generator** — we make architectural choices for you
+- **Not cloud-agnostic** (yet) — DigitalOcean first, AWS/GCP coming later
+- **Not a runtime manager** — we scaffold code, you deploy with Pulumi
+- **Not a replacement for Kubernetes** — we generate K8s configs via Pulumi
+
+<br />
+
+---
+
+## 🏗️ Architecture at 10,000 ft
+
+When you create a workspace with `pf`, you get a **Turborepo monorepo** with this structure:
+
+```
+my-platform/
+├── services/         # Microservices (Hono, NestJS)
+│   ├── orders/       # Example: Order processing service
+│   ├── notifications/# Example: Notification service
+│   └── nats/         # NATS message broker (auto-scaffolded)
+├── apps/             # Frontend apps (optional: Qwik, Next.js, etc.)
+├── packages/         # Shared libraries
+│   ├── cloudevents/  # Event publishing/consuming toolkit
+│   └── telemetry/    # OpenTelemetry setup
+├── infra/            # Pulumi Infrastructure-as-Code
+│   ├── index.ts      # Main Pulumi program
+│   └── services/     # Per-service K8s configs
+│       ├── orders.ts
+│       └── notifications.ts
+├── .github/
+│   └── workflows/    # CI/CD pipelines (auto-generated)
+├── turbo.json        # Turborepo task orchestration
+└── .env.local        # Auto-generated from infra configs
+```
+
+### Key Architectural Decisions
+
+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`
+5. **Bun-first DX** — Ultra-fast installs, tests, and dev server with fallback to npm/yarn
+
+### Event-Driven Mental Model
+
+Services communicate via **CloudEvents** over **NATS JetStream**:
+
+```typescript
+// Service A publishes an event
+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
+export default handleEvent(
+  { schema: OrderCreatedSchema, type: 'orders.created' },
+  async (data) => { await sendNotification(data) }
+)
+```
+
+No manual NATS subscriptions. No boilerplate. Just **convention over configuration**.
+
+<br />
+
+---
+
+## 🧭 Design Principles
+
+These principles guide every decision in `pf`:
+
+- **🥟 Bun-first DX** — Leverage Bun's speed for installs, tests, and dev mode (npm/yarn fallback supported)
+- **📦 Monorepo-centric** — One repo to rule them all. Turborepo for caching and parallel builds
+- **🏗️ Infrastructure-as-Code by default** — No ClickOps. Every service has Pulumi config
+- **🔁 Event-driven communication baked in** — NATS + JetStream are first-class citizens, not afterthoughts
+- **🌊 DigitalOcean-first, cloud-agnostic later** — Start simple with DO, expand to AWS/GCP when needed
+- **🤖 AI-augmented development** — Use AI to generate complete services, not just snippets
+- **📏 Convention over configuration** — Strong opinions enable automation
 
 <br />
 
@@ -126,30 +206,230 @@ This will:
 - 🔌 Auto-assign unique ports per service
 - 📦 Monitor for file changes and hot-reload
 
+### 4. Essential workspace commands
+
+```bash
+# Run all tests across the monorepo
+bun test
+
+# Lint and format all code with Biome
+bun lint
+
+# Build all packages and services
+bun run build
+```
+
 <br />
 
 ---
 
-## 📁 Workspace Structure
+## 📘 Typical Workflows
+
+Here's how developers actually use `pf` in real-world scenarios:
 
+### Workflow 1: Start a New Platform
+
+You're building a new product from scratch and want to establish a solid foundation.
+
+```bash
+# Step 1: Scaffold the workspace
+bunx @crossdelta/platform-sdk new workspace orderboss-platform \
+  --github-owner orderboss \
+  --pulumi-stack dev \
+  -y
+
+cd orderboss-platform
+
+# Step 2: Configure infrastructure (optional)
+# Edit infra/config.ts to customize:
+# - DigitalOcean region (defaults to nyc3)
+# - Kubernetes cluster size
+# - Database instance sizes
+
+# Step 3: Start local development
+bun dev
 ```
-my-platform/
-├── .github/
-│   ├── workflows/
-│   └── actions/
-├── infra/
-│   ├── index.ts
-│   ├── services/
-│   ├── Pulumi.yaml
-│   └── Pulumi.dev.yaml
-├── services/
-├── apps/
-├── packages/
-├── package.json
-├── turbo.json
-└── biome.json
+
+**What you get:**
+- ✅ Turborepo monorepo with Biome linting/formatting
+- ✅ NATS service running in Docker
+- ✅ Pulumi infrastructure setup for DigitalOcean
+- ✅ GitHub Actions workflows for CI/CD
+- ✅ `.env.local` auto-generated with all service ports
+
+**Time to first service running:** ~60 seconds
+
+---
+
+### 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, complete)**
+
+```bash
+# First time: configure AI provider
+pf setup --ai
+
+# Generate a complete service with AI
+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:
+# ✅ Complete service implementation with Stripe SDK
+# ✅ Event handlers for incoming orders
+# ✅ Event publishers for payment lifecycle
+# ✅ Use cases with validation logic
+# ✅ Test files for all use cases
+# ✅ Environment variable documentation
+# ✅ Complete README with API docs
+```
+
+**When to use which:**
+- **Manual scaffolding:** You know exactly what you're building, want full control
+- **AI generation:** Bootstrapping new domains, exploring integrations, speeding up prototyping
+
+---
+
+### Workflow 3: Build an Event-Driven Feature
+
+You want to send notifications whenever a new order is created.
+
+**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/transports/nats'
+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
+}
+```
+
+**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 />
 
 ---
@@ -291,16 +571,38 @@ export const config: K8sServiceConfig = {
 
 ## 🚢 Deployment
 
+### Local Deployment
+
 ```bash
 pulumi login
 pulumi up --stack dev
 ```
 
-GitHub Secrets:
+### CI/CD with GitHub Actions
+
+Every workspace includes pre-configured GitHub Actions workflows in `.github/workflows/`:
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| **`lint-and-tests.yml`** | Pull Requests to `main` | Runs `bun lint` and `bun test` on PRs |
+| **`build-and-deploy.yml`** | Push to `main` | Builds Docker images, pushes to GHCR, deploys via Pulumi |
+| **`publish-packages.yml`** | Changes in `packages/` | Auto-publishes packages to npm with versioning |
+
+### Required GitHub Secrets
+
+Configure these secrets in your repository settings (`Settings` → `Secrets and variables` → `Actions`):
+
+| Secret | Description | Required For |
+|--------|-------------|--------------|
+| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token | All deployments |
+| `DIGITALOCEAN_TOKEN` | DigitalOcean API token | Infrastructure provisioning |
+| `NPM_TOKEN` | npm registry token | Package publishing (optional) |
+| `GHCR_TOKEN` | GitHub Container Registry PAT | Docker image publishing |
 
-- `PULUMI_ACCESS_TOKEN`
-- `DIGITALOCEAN_TOKEN`
-- `NPM_TOKEN` (optional)
+**Get tokens:**
+- **Pulumi:** https://app.pulumi.com/account/tokens
+- **DigitalOcean:** https://cloud.digitalocean.com/account/api/tokens
+- **npm:** https://www.npmjs.com/settings/~/tokens
 
 <br />