@crossdelta/platform-sdk 0.2.31 → 0.3.1

package/README.md

@@ -1,24 +1,54 @@
+<p align="center">
+  <img src="logo.svg" alt="pf" width="120" />
+</p>
 
-# @crossdelta/platform-sdk
-**Bun-first CLI toolkit for building event-driven microservice platforms.**
+<h1 align="center">Platform SDK</h1>
 
-Spin up a complete Turborepo workspace with [Pulumi](https://www.pulumi.com/) infrastructure, ready-to-run [Hono](https://hono.dev/) / [NestJS](https://nestjs.com/) microservices, automatic env generation, and a unified development workflow — all from a single CLI.
+<p align="center">
+  <code>@crossdelta/platform-sdk</code>
+</p>
 
-> Stop wiring Turborepo, Pulumi, ports, env files & service scripts by hand.
-> Build a production-ready microservice platform in under a minute.
+<p align="center">
+  <strong>Agentic CLI for event-driven microservice platforms</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>
+  <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 DigitalOcean — all from one CLI.
+</p>
+
+---
+
+> ⚠️ **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.
 
 ---
 
 ## ✨ Features
 
-- ⚡ **Instant Scaffolding** – Create fully wired platform workspaces with best practices baked in
-- 🥟 **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 via [Pulumi](https://www.pulumi.com/)
-- 🌍 **Automatic `.env.local` Generation** – 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 when needed
+| 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 |
 
 ---
 
@@ -28,9 +58,25 @@ Spin up a complete Turborepo workspace with [Pulumi](https://www.pulumi.com/) in
 
 ```bash
 npx @crossdelta/platform-sdk new workspace my-platform
-cd my-platform
 ```
 
+Or 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
+```
+
+**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.
 
@@ -39,13 +85,36 @@ cd my-platform
 ### 2. Generate microservices
 
 ```bash
-# Hono microservice
-pf new hono-micro services/orders
+pf new hono-micro services/orders       # Lightweight Hono service
+pf new nest-micro services/api-gateway  # Enterprise NestJS service
+```
+
+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:
+
+```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
+```
 
-# NestJS microservice
-pf new nest-micro services/api-gateway
+First-time setup:
+
+```bash
+pf setup --ai   # Configure OpenAI or Anthropic API key
 ```
 
+The AI reads your project's `copilot-instructions.md` and generates code following your conventions.
+
 ---
 
 ### 3. Start local development
@@ -56,94 +125,125 @@ pf dev
 
 What happens:
 
-- `.env.local` is generated from all `infra/services/*.ts` configs
-- Services are started in parallel via Turborepo
-- Watching:
-  - `infra/services/` → regenerate env + restart
-  - `services/` and `apps/` → detect new/deleted packages and reinstall deps
+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
 
 ---
 
-## 🧠 Example: Automatic env generation
+## 📁 Generated 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
+```
+
+---
+
+## 🛠 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 { ServiceConfig } from '@crossdelta/infrastructure'
+import type { K8sServiceConfig } from '@crossdelta/infrastructure'
 
-export const orders: ServiceConfig = {
+export const config: K8sServiceConfig = {
   name: 'orders',
-  httpPort: 4001,
+  containerPort: 4001,
+  replicas: 1,
+  healthCheck: { port: 4001 },
+  resources: {
+    requests: { cpu: '50m', memory: '64Mi' },
+    limits: { cpu: '150m', memory: '128Mi' },
+  },
   env: {
-    ORDERS_DB_URL: 'postgres://...',
-    NATS_URL: 'nats://localhost:4222',
+    DATABASE_URL: databaseUrl,
+    NATS_URL: natsUrl,
   },
 }
 ```
 
-Running:
-
-```bash
-pf dev
-```
+Running `pf dev` generates:
 
-Creates:
-
-```
-.env.local
-ORDERS_DB_URL=postgres://...
+```env
+# .env.local
+DATABASE_URL=postgres://...
 NATS_URL=nats://localhost:4222
 ORDERS_PORT=4001
 ```
 
-And automatically reloads services on change.
-
 ---
 
-## 🛠 Commands
+## 🚢 Deployment (DigitalOcean)
 
-### `pf dev`
-Start the development environment with optional watch mode.
+### Prerequisites
 
-```bash
-pf dev              # Start with watch mode
-pf dev --no-watch   # Disable watching
-```
+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
 
-### `pf new workspace <name>`
-Scaffold a complete platform workspace with Pulumi infrastructure.
+| Secret | Description |
+|--------|-------------|
+| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token |
+| `DIGITALOCEAN_TOKEN` | DigitalOcean API token |
+| `NPM_TOKEN` | (optional) For private npm packages |
 
-```bash
-pf new workspace my-platform
-pf new workspace my-platform -y   # Skip prompts
-```
-
----
-
-### `pf new hono-micro <path>`
-Generate a lightweight Hono microservice.
+### Deploy
 
 ```bash
-pf new hono-micro services/orders
+pulumi login
+pulumi up --stack dev
 ```
 
 ---
 
-### `pf new nest-micro <path>`
-Generate a NestJS microservice with enterprise-ready setup.
+## 📦 Installation
 
 ```bash
-pf new nest-micro services/api-gateway
-```
-
----
-
-## 📦 Installation (optional)
+# Via npx (recommended)
+npx @crossdelta/platform-sdk new workspace my-platform
 
-```bash
-npm install -g @crossdelta/platform-sdk
-# or
+# Global install
 bun add -g @crossdelta/platform-sdk
 ```
 
@@ -151,38 +251,55 @@ bun add -g @crossdelta/platform-sdk
 
 ## 👍 When to use this
 
-- You want a **Bun-first microservice platform** with minimal boilerplate
-- You prefer **Turborepo + Pulumi** as your architectural baseline
-- You want fast **Hono/NestJS service scaffolding**
-- You need a **unified dev workflow** for multiple services
-- You plan to deploy to **DigitalOcean, GCP, AWS**
+- ✅ **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 a hosted PaaS (Render, Fly.io, Netlify, etc.)
-- You are not using a monorepo
-- You don’t use Infrastructure-as-Code
-- You prefer fully unopinionated setups
+- ❌ 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
 
-- Node.js ≥ 21
-- Bun (recommended) or npm/yarn/pnpm
-- Pulumi CLI (optional, required for infra)
+| 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 |
 
 ---
 
-## 🔗 Related
+## 🗺️ Roadmap
 
-- **[@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure)** – Shared helpers & types for Pulumi + DigitalOcean
-- **[@crossdelta/cloudevents](https://www.npmjs.com/package/@crossdelta/cloudevents)** – CloudEvents + NATS toolkit for event-driven microservices
+- [x] AI-powered service generation (OpenAI/Anthropic)
+- [ ] AWS ECS/Fargate provider
+- [ ] GCP Cloud Run provider
+- [ ] Kubernetes (generic) provider
+- [ ] `pf migrate` command for database migrations
 
 ---
 
 ## 📄 License
 
-MIT © Crossdelta
+MIT © [Crossdelta](https://github.com/crossdelta)