@crossdelta/platform-sdk 0.3.20 → 0.3.22

package/README.md

@@ -9,29 +9,41 @@
 </p>
 
 <p align="center">
-  <strong>Agentic CLI for event-driven microservice platforms</strong>
+  <strong>Your AI-powered platform engineer.</strong><br />
+  Scaffold complete Turborepo workspaces, generate production-ready microservices<br />
+  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>
 
-<p align="center">
-  Your AI-powered platform engineer. Scaffold complete Turborepo workspaces,<br />
-  generate production-ready microservices with natural language,<br />
-  and deploy to the cloud — all from one CLI.
-</p>
+<br />
 
 ---
 
+## 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.
+> **AWS and GCP support** is planned for future releases.
+
+<br />
 
 ---
 
@@ -43,152 +55,156 @@
 | 🤖 **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](https://hono.dev/) (lightweight) and [NestJS](https://nestjs.com/) (enterprise-grade) templates |
-| 📦 **Pulumi-Ready Infra** | Infrastructure-as-Code for DigitalOcean (App Platform or DOKS) |
+| 🔧 **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, zero manual config |
+| 🔌 **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 (recommended)
+# Install globally
 npm install -g @crossdelta/platform-sdk
 pf new workspace my-platform
 
-# Or use bunx (no install needed)
-bunx @crossdelta/platform-sdk pf new workspace my-platform
-```
-
-**With options:**
-```bash
-pf new workspace my-platform -y                    # Skip prompts
-pf new workspace my-platform -o my-github-org      # Set GitHub owner
-pf new workspace my-platform --no-github           # Without CI/CD
+# 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:**
 
 | Flag | Description |
 |------|-------------|
-| `-y, --yes` | Skip prompts, use defaults |
+| `-y, --yes` | Skip prompts |
 | `-o, --github-owner <owner>` | GitHub org/user for GHCR registry |
-| `-s, --pulumi-stack <name>` | Pulumi stack base name (org/project) |
+| `-s, --pulumi-stack <name>` | Pulumi stack base name |
 | `--no-github` | Skip GitHub Actions workflows |
 
-> 💡 **Two ways to use the CLI:**
-> - **Global install** (recommended): `npm install -g @crossdelta/platform-sdk` → use `pf` command
-> - **Bunx** (no install): `bunx @crossdelta/platform-sdk pf <command>`
-
----
-
 ### 2. Generate microservices
 
+**Manual scaffolding:**
 ```bash
-pf new hono-micro services/orders       # Lightweight Hono service
-pf new nest-micro services/api-gateway  # Enterprise NestJS service
+pf new hono-micro services/orders
+pf new nest-micro services/api-gateway
 ```
 
-Both generators:
-- Auto-assign unique ports
-- Create Pulumi service config in `infra/services/`
-- Add Dockerfile for containerized deployment
-- Wire up health checks
-
-#### 🤖 AI-Powered Generation
-
-Generate services with AI assistance:
-
+**AI-powered generation:**
 ```bash
-# One-liner with description
-pf new hono-micro services/payments --ai -d "Handle payment webhooks and process transactions"
-
-# Interactive mode (prompts for description)
-pf new hono-micro services/notifications --ai
-```
-
-First-time setup:
+# First time: configure AI provider (OpenAI or Anthropic)
+pf setup --ai
 
-```bash
-pf setup --ai   # Configure OpenAI or Anthropic API key
+# Generate service with AI
+pf new hono-micro services/payments --ai \
+  -d "Handle Stripe webhooks and send payment confirmations"
 ```
 
-The AI reads your project's `copilot-instructions.md` and generates code following your conventions.
-
----
+**✨ 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
 ```
 
-What happens:
+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
 
-1. `.env.local` is generated from all `infra/services/*.ts` configs
-2. Services are started in parallel via Turborepo
-3. **Watching:**
-   - `infra/services/` → regenerate env + restart
-   - `services/` and `apps/` → detect new/deleted packages and reinstall deps
+<br />
 
 ---
 
-## 📁 Generated Workspace Structure
+## 📁 Workspace Structure
 
 ```
 my-platform/
 ├── .github/
 │   ├── workflows/
-│   │   ├── lint-and-tests.yml      # PR checks
-│   │   ├── build-and-deploy.yml    # Build & deploy on push to main
-│   │   └── publish-packages.yml    # Publish npm packages
 │   └── actions/
-│       ├── setup-bun-install/      # Cached Bun setup
-│       ├── generate-scope-matrix/  # Dynamic service detection
-│       ├── check-image-tag-exists/ # Skip unchanged builds
-│       └── ...                     # More reusable actions
 ├── infra/
-│   ├── index.ts                    # Pulumi entry point
-│   ├── services/                   # Service configs (auto-discovered)
-│   ├── Pulumi.yaml                 # Project config
-│   └── Pulumi.dev.yaml             # Dev stack config
-├── services/                       # Microservices
-├── apps/                           # Frontend apps
-├── packages/                       # Shared packages
-├── package.json                    # Root workspace config
-├── turbo.json                      # Turborepo config
-└── biome.json                      # Linting config
+│   ├── index.ts
+│   ├── services/
+│   ├── Pulumi.yaml
+│   └── Pulumi.dev.yaml
+├── services/
+├── apps/
+├── packages/
+├── package.json
+├── turbo.json
+└── biome.json
 ```
 
+<br />
+
 ---
 
 ## 🛠 CLI Commands
 
+<details>
+<summary><strong>📖 View Full Command Reference</strong></summary>
+
+<br />
+
+### Workspace Commands
+
 | Command | Description |
 |---------|-------------|
-| `pf new` | Interactive mode - choose project type and options |
-| `pf new workspace <name>` | Scaffold a complete platform workspace |
-| `pf new hono-micro <path>` | Generate a lightweight Hono microservice |
-| `pf new nest-micro <path>` | Generate a NestJS microservice |
-| `pf new hono-micro <path> --ai -d "..."` | Generate with AI assistance |
-| `pf setup --ai` | Configure AI provider (OpenAI/Anthropic) |
-| `pf dev` | Start dev environment with watch mode |
-| `pf dev --no-watch` | Start without file watching |
-| `pf generate <schematic> <name>` | Generate code using schematics |
+| `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 --version` | Show version information |
+| `pf --help` | Show help for any command |
+
+</details>
+
+<br />
 
-## 🔧 Configuration
+---
 
-### Service Config Example
+## 🔧 Configuration Example
 
 ```ts
-// infra/services/orders.ts
 import type { K8sServiceConfig } from '@crossdelta/infrastructure'
 
 export const config: K8sServiceConfig = {
@@ -196,10 +212,6 @@ export const config: K8sServiceConfig = {
   containerPort: 4001,
   replicas: 1,
   healthCheck: { port: 4001 },
-  resources: {
-    requests: { cpu: '50m', memory: '64Mi' },
-    limits: { cpu: '150m', memory: '128Mi' },
-  },
   env: {
     DATABASE_URL: databaseUrl,
     NATS_URL: natsUrl,
@@ -207,93 +219,50 @@ export const config: K8sServiceConfig = {
 }
 ```
 
-Running `pf dev` generates:
-
-```env
-# .env.local
-DATABASE_URL=postgres://...
-NATS_URL=nats://localhost:4222
-ORDERS_PORT=4001
-```
+<br />
 
 ---
 
-## 🚢 Deployment (DigitalOcean)
-
-### Prerequisites
-
-1. **Pulumi Account** – [Sign up free](https://app.pulumi.com/signup)
-2. **DigitalOcean Account** – [Create account](https://cloud.digitalocean.com/registrations/new)
-3. **GitHub Repository** – For CI/CD workflows
-
-### GitHub Secrets
-
-| Secret | Description |
-|--------|-------------|
-| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token |
-| `DIGITALOCEAN_TOKEN` | DigitalOcean API token |
-| `NPM_TOKEN` | (optional) For private npm packages |
-
-### Deploy
+## 🚢 Deployment
 
 ```bash
 pulumi login
 pulumi up --stack dev
 ```
 
----
+GitHub Secrets:
 
-##  When to use this
+- `PULUMI_ACCESS_TOKEN`
+- `DIGITALOCEAN_TOKEN`
+- `NPM_TOKEN` (optional)
 
-- ✅ **Bun-first microservice platform** with minimal boilerplate
-- ✅ **Turborepo + Pulumi** as architectural baseline
-- ✅ Fast **Hono/NestJS service scaffolding**
-- ✅ **Unified dev workflow** for multiple services
-- ✅ Deploy to **DigitalOcean App Platform**
-- ✅ **GitHub Actions** for CI/CD
-
----
-
-## ❌ When NOT to use this
-
-- ❌ You need AWS, GCP, or other cloud providers (coming soon)
-- ❌ You need a hosted PaaS (Render, Fly.io, Netlify)
-- ❌ You are not using a monorepo
-- ❌ You don't use Infrastructure-as-Code
+<br />
 
 ---
 
 ## 📚 Requirements
 
-| Requirement | Version |
-|-------------|---------|
-| Node.js | ≥ 21 |
-| Bun | Latest (recommended) |
-| Pulumi CLI | Latest |
-| Docker | For local Supabase/NATS |
-
----
+- Node.js ≥ 21
+- Bun (latest)
+- Pulumi CLI
+- Docker (for local Supabase/NATS)
 
-## 🔗 Related Packages
-
-| Package | Description |
-|---------|-------------|
-| [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure) | Pulumi helpers for DigitalOcean |
-| [@crossdelta/cloudevents](https://www.npmjs.com/package/@crossdelta/cloudevents) | CloudEvents + NATS toolkit |
-| [@crossdelta/telemetry](https://www.npmjs.com/package/@crossdelta/telemetry) | Zero-config OpenTelemetry |
+<br />
 
 ---
 
-## 🗺️ Roadmap
+## � Community & Support
+
+- 📖 [Full Documentation](https://github.com/orderboss/platform/tree/main/packages/platform-sdk/docs)
+- 🐛 [Report Issues](https://github.com/orderboss/platform/issues)
+- 💡 [Feature Requests](https://github.com/orderboss/platform/discussions)
+- 📦 [npm Package](https://www.npmjs.com/package/@crossdelta/platform-sdk)
+- ⭐ [Star on GitHub](https://github.com/orderboss/platform)
 
-- [x] AI-powered service generation (OpenAI/Anthropic)
-- [ ] AWS ECS/Fargate provider
-- [ ] GCP Cloud Run provider
-- [ ] Kubernetes (generic) provider
-- [ ] `pf migrate` command for database migrations
+<br />
 
 ---
 
-## 📄 License
+## �📄 License
 
-MIT © [Crossdelta](https://github.com/crossdelta)
+MIT © Crossdelta