@crossdelta/platform-sdk 0.2.30 → 0.2.31

package/README.md

@@ -1,140 +1,188 @@
-# @crossdelta/platform-sdk
 
-[![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)
+# @crossdelta/platform-sdk
+**Bun-first CLI toolkit for building event-driven microservice platforms.**
 
-> 🚀 CLI toolkit for scaffolding and managing microservice platforms
+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.
 
-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.
+> Stop wiring Turborepo, Pulumi, ports, env files & service scripts by hand.
+> Build a production-ready microservice platform in under a minute.
 
-## Features
+---
 
-- ⚡ **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
+## ✨ Features
 
-## Installation
+- ⚡ **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
 
-```bash
-npm install -g @crossdelta/platform-sdk
+---
 
-# or
-bun add -g @crossdelta/platform-sdk
-```
+## 🚀 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
+```
+
+> 💡 `pf` is the CLI binary shipped with this package.
+> It automatically works through `npx` — no global install required.
+
+---
 
-# Create a Hono microservice
+### 2. Generate microservices
+
+```bash
+# Hono microservice
 pf new hono-micro services/orders
 
-# Create a NestJS microservice
+# NestJS microservice
 pf new nest-micro services/api-gateway
+```
 
-# Start development
+---
+
+### 3. Start local development
+
+```bash
 pf dev
 ```
 
-## Commands
+What happens:
 
-### `pf dev`
+- `.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
 
-Start the development environment with hot reload.
+---
+
+## 🧠 Example: Automatic env generation
+
+```ts
+// infra/services/orders.ts
+import type { ServiceConfig } from '@crossdelta/infrastructure'
+
+export const orders: ServiceConfig = {
+  name: 'orders',
+  httpPort: 4001,
+  env: {
+    ORDERS_DB_URL: 'postgres://...',
+    NATS_URL: 'nats://localhost:4222',
+  },
+}
+```
+
+Running:
 
 ```bash
-pf dev              # Start with watch mode (default)
-pf dev --no-watch   # Start without watching for changes
+pf dev
 ```
 
-**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"]
-    }
-  }
-}
+Creates:
+
+```
+.env.local
+ORDERS_DB_URL=postgres://...
+NATS_URL=nats://localhost:4222
+ORDERS_PORT=4001
 ```
 
-### `pf new workspace [name]`
+And automatically reloads services on change.
 
-Scaffold a complete platform workspace with Pulumi infrastructure.
+---
+
+## 🛠 Commands
+
+### `pf dev`
+Start the development environment with optional watch mode.
 
 ```bash
-pf new workspace my-platform
-pf new workspace my-platform -y  # Skip prompts, use defaults
+pf dev              # Start with watch mode
+pf dev --no-watch   # Disable watching
 ```
 
-**Creates:**
-```
-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
+---
+
+### `pf new workspace <name>`
+Scaffold a complete platform workspace with Pulumi infrastructure.
+
+```bash
+pf new workspace my-platform
+pf new workspace my-platform -y   # Skip prompts
 ```
 
-### `pf new hono-micro [name]`
+---
 
-Generate a lightweight Hono-based microservice.
+### `pf new hono-micro <path>`
+Generate a lightweight Hono microservice.
 
 ```bash
 pf new hono-micro services/orders
 ```
 
-### `pf new nest-micro [name]`
+---
 
-Generate a NestJS microservice with full enterprise setup.
+### `pf new nest-micro <path>`
+Generate a NestJS microservice with enterprise-ready setup.
 
 ```bash
 pf new nest-micro services/api-gateway
 ```
 
-**Includes:**
-- TypeScript configuration
-- Biome linting
-- Docker support
-- Health checks
+---
+
+## 📦 Installation (optional)
+
+```bash
+npm install -g @crossdelta/platform-sdk
+# or
+bun add -g @crossdelta/platform-sdk
+```
+
+---
 
-## 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 |
+- 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**
 
-## Requirements
+---
 
-- Node.js >= 21.0.0
+## ❌ 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
+
+---
+
+## 📚 Requirements
+
+- Node.js ≥ 21
 - Bun (recommended) or npm/yarn/pnpm
+- Pulumi CLI (optional, required for infra)
+
+---
+
+## 🔗 Related
 
-## Related
+- **[@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
 
-- [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure) - Infrastructure helpers for Pulumi + DigitalOcean
+---
 
-## License
+## 📄 License
 
-MIT © [Crossdelta](https://github.com/crossdelta)
+MIT © Crossdelta