@crossdelta/platform-sdk 0.2.30 → 0.3.0

package/README.md

@@ -1,140 +1,305 @@
-# @crossdelta/platform-sdk
+<p align="center">
+  <img src="logo.svg" alt="pf" width="120" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg)](https://www.npmjs.com/package/@crossdelta/platform-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+<h1 align="center">Platform SDK</h1>
 
-> 🚀 CLI toolkit for scaffolding and managing microservice platforms
+<p align="center">
+  <code>@crossdelta/platform-sdk</code>
+</p>
 
-Build event-driven microservice platforms with minimal boilerplate. This CLI scaffolds [Turborepo](https://turbo.build) workspaces with [Pulumi](https://pulumi.com) infrastructure, generates microservices (Hono or NestJS), and provides a unified dev experience across all services.
+<p align="center">
+  <strong>Agentic CLI for event-driven microservice platforms</strong>
+</p>
 
-## Features
+<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>
+  <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>
 
-- ⚡ **Quick Scaffolding** - Generate projects with best practices baked in
-- 🥟 **[Bun](https://bun.sh)-first** - Optimized for Bun runtime with npm/yarn/pnpm fallback
-- 🏗️ **[Turborepo](https://turbo.build) Workspaces** - Monorepo setup with parallel builds and caching
-- 🔧 **Microservice Templates** - [Hono](https://hono.dev) (lightweight) & [NestJS](https://nestjs.com) (enterprise-grade)
-- 📦 **[Pulumi](https://www.pulumi.com) Ready** - Infrastructure-as-Code out of the box
-- 🔌 **Auto Port Assignment** - Unique ports per service, no manual configuration
-- 🌍 **Env Generation** - `.env.local` auto-generated from `infra/services/*.ts` configs
+<p align="center">
+  Your AI-powered platform engineer. Scaffold complete Turborepo workspaces,<br />
+  generate production-ready microservices with natural language,<br />
+  and deploy to DigitalOcean — all from one CLI.
+</p>
 
-## Installation
+---
 
-```bash
-npm install -g @crossdelta/platform-sdk
+> ⚠️ **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.
 
-# or
-bun add -g @crossdelta/platform-sdk
-```
+---
+
+## ✨ Features
+
+| 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](https://hono.dev/) (lightweight) and [NestJS](https://nestjs.com/) (enterprise-grade) templates |
+| 📦 **Pulumi-Ready Infra** | Infrastructure-as-Code for DigitalOcean (App Platform or DOKS) |
+| 🚀 **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 |
+| 🔁 **Smart Watch Mode** | Watches infra & services, regenerates env, reinstalls deps |
+
+---
+
+## 🚀 Quick Start
 
-## Quick Start
+### 1. Create a new workspace
 
 ```bash
-# Create a new workspace with infrastructure
 npx @crossdelta/platform-sdk new workspace my-platform
-cd my-platform
+```
 
-# Create a Hono microservice
-pf new hono-micro services/orders
+Or with options:
 
-# Create a NestJS microservice
-pf new nest-micro services/api-gateway
+```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
+```
 
-# Start development
-pf dev
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Skip prompts, use defaults |
+| `-o, --github-owner <owner>` | GitHub org/user for GHCR registry |
+| `-s, --pulumi-stack <name>` | Pulumi stack base name (org/project) |
+| `--no-github` | Skip GitHub Actions workflows |
+
+> 💡 `pf` is the CLI binary shipped with this package.
+> It automatically works through `npx` — no global install required.
+
+---
+
+### 2. Generate microservices
+
+```bash
+pf new hono-micro services/orders       # Lightweight Hono service
+pf new nest-micro services/api-gateway  # Enterprise NestJS service
 ```
 
-## Commands
+Both generators:
+- Auto-assign unique ports
+- Create Pulumi service config in `infra/services/`
+- Add Dockerfile for containerized deployment
+- Wire up health checks
 
-### `pf dev`
+#### 🤖 AI-Powered Generation
 
-Start the development environment with hot reload.
+Generate services with AI assistance:
 
 ```bash
-pf dev              # Start with watch mode (default)
-pf dev --no-watch   # Start without watching for changes
+# 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
 ```
 
-**What it does:**
-1. Generates `.env.local` from service configurations in `infra/services/*.ts`
-2. Starts all services in parallel via `turbo start:dev`
-3. Watches for changes:
-   - `infra/services/` → Regenerates env and restarts on config changes
-   - `services/` & `apps/` → Detects new/deleted packages and reinstalls dependencies
-
-**Configuration via `package.json`:**
-```json
-{
-  "pf": {
-    "dev": {
-      "watchDirs": ["infra/services"],
-      "watchPackages": ["services", "apps"]
-    }
-  }
-}
+First-time setup:
+
+```bash
+pf setup --ai   # Configure OpenAI or Anthropic API key
 ```
 
-### `pf new workspace [name]`
+The AI reads your project's `copilot-instructions.md` and generates code following your conventions.
+
+---
 
-Scaffold a complete platform workspace with Pulumi infrastructure.
+### 3. Start local development
 
 ```bash
-pf new workspace my-platform
-pf new workspace my-platform -y  # Skip prompts, use defaults
+pf dev
 ```
 
-**Creates:**
+What happens:
+
+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
+
+---
+
+## 📁 Generated Workspace Structure
+
 ```
 my-platform/
-├── package.json
-├── biome.json
-└── infra/
-    ├── index.ts           # Pulumi entry point
-    ├── tsconfig.json
-    ├── Pulumi.yaml
-    ├── Pulumi.dev.yaml
-    └── services/
-        └── example.ts     # Example service config
+├── .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
+```
+
+---
+
+## 🛠 CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `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` | 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 |
+
+---
+
+## 🔧 Configuration
+
+### Service Config Example
+
+```ts
+// infra/services/orders.ts
+import type { K8sServiceConfig } from '@crossdelta/infrastructure'
+
+export const config: K8sServiceConfig = {
+  name: 'orders',
+  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,
+  },
+}
+```
+
+Running `pf dev` generates:
+
+```env
+# .env.local
+DATABASE_URL=postgres://...
+NATS_URL=nats://localhost:4222
+ORDERS_PORT=4001
 ```
 
-### `pf new hono-micro [name]`
+---
+
+## 🚢 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
 
-Generate a lightweight Hono-based microservice.
+### GitHub Secrets
+
+| Secret | Description |
+|--------|-------------|
+| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token |
+| `DIGITALOCEAN_TOKEN` | DigitalOcean API token |
+| `NPM_TOKEN` | (optional) For private npm packages |
+
+### Deploy
 
 ```bash
-pf new hono-micro services/orders
+pulumi login
+pulumi up --stack dev
 ```
 
-### `pf new nest-micro [name]`
+---
 
-Generate a NestJS microservice with full enterprise setup.
+## 📦 Installation
 
 ```bash
-pf new nest-micro services/api-gateway
+# Via npx (recommended)
+npx @crossdelta/platform-sdk new workspace my-platform
+
+# Global install
+bun add -g @crossdelta/platform-sdk
 ```
 
-**Includes:**
-- TypeScript configuration
-- Biome linting
-- Docker support
-- Health checks
+---
 
-## Options
+## 👍 When to use this
 
-| Flag | Description |
-|------|-------------|
-| `-y, --yes` | Skip all prompts, use defaults |
-| `-P, --package-manager <pm>` | Specify package manager (npm, yarn, pnpm, bun) |
-| `-h, --help` | Show help |
+- ✅ **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
+
+---
+
+## 📚 Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js | ≥ 21 |
+| Bun | Latest (recommended) |
+| Pulumi CLI | Latest |
+| 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 |
 
-## Requirements
+---
 
-- Node.js >= 21.0.0
-- Bun (recommended) or npm/yarn/pnpm
+## 🗺️ Roadmap
 
-## Related
+- [x] AI-powered service generation (OpenAI/Anthropic)
+- [ ] AWS ECS/Fargate provider
+- [ ] GCP Cloud Run provider
+- [ ] Kubernetes (generic) provider
+- [ ] `pf migrate` command for database migrations
 
-- [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure) - Infrastructure helpers for Pulumi + DigitalOcean
+---
 
-## License
+## 📄 License
 
 MIT © [Crossdelta](https://github.com/crossdelta)