@crossdelta/platform-sdk 0.7.9 → 0.7.11

package/README.md

@@ -33,17 +33,42 @@
 <br />
 
 ---
-## 🚀 Quick Start
+
+## Installation
+
+```bash
+# Pick your package manager
+bun add -g @crossdelta/platform-sdk
+npm install -g @crossdelta/platform-sdk
+pnpm add -g @crossdelta/platform-sdk
+```
+
+<details>
+<summary>Alternative: Auto-installer or use without installing</summary>
+
+```bash
+# Auto-installer (detects package manager, offers to install Bun if needed)
+curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
+
+# Or run directly without global install
+bunx @crossdelta/platform-sdk new workspace my-platform
+npx @crossdelta/platform-sdk new workspace my-platform
+```
+
+</details>
+
+---
+
+## Quick Start
 
 ```bash
-# Create workspace (works with bunx/npx/pnpm dlx/yarn dlx)
-bunx @crossdelta/platform-sdk new workspace my-platform -y
+# Create workspace
+pf new workspace my-platform -y
 cd my-platform
 
 # Generate microservice with AI
-# (first time: run `pf setup --ai` to configure provider)
-bunx @crossdelta/platform-sdk new hono-micro services/orders --ai \
-  -d "Handle order creation and payment"
+pf setup --ai                    # Configure AI provider (first time only)
+pf new hono-micro services/orders --ai -d "Handle order creation and payment"
 
 # Start development
 pf dev
@@ -71,43 +96,8 @@ pf pulumi up    # → runs in infra/ directory
 
 **Why:** Keeps commands consistent across the team and works from any subdirectory.
 
-**How it works:** `pf` walks up to find your workspace root, then proxies to your scripts. Configured commands via `pf.commands` can override the working directory or command. Registered `pf` commands (like `pf new`) take precedence.
-
 > **📖 Note:** You can be productive with `pf` in minutes using the commands above. The sections below are reference documentation—explore them when you need specific details.
 
-### No runtime installed?
-
-If you don't have a JavaScript runtime, use our installer that sets everything up.
-**The installer is optional** — you can always use `bunx`/`npx` or a global install.
-
-```bash
-# Auto-installer (detects bun/pnpm/yarn/npm; if none found it can install Bun)
-curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
-
-# Then use short commands
-pf new workspace my-platform
-pf new hono-micro services/orders --ai -d "..."
-```
-
-> **Security:** The installer asks permission before installing Bun (if needed) and does not run any workspace commands automatically.
-
-<details>
-<summary><strong>🔍 What does the installer do?</strong></summary>
-
-The script ([view source](https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh)):
-1. Checks for bun/pnpm/yarn/npm
-2. If none found, **asks permission** to install Bun
-3. Installs `pf` CLI globally
-
-**Manual installation:**
-```bash
-# With Bun/npm/yarn/pnpm
-bun add -g @crossdelta/platform-sdk
-# or: npm install -g @crossdelta/platform-sdk
-```
-
-</details>
-
 <br />
 
 ---
@@ -161,30 +151,23 @@ When you create a workspace with `pf`, you get a **Turborepo monorepo** with thi
 
 ```
 my-platform/
-├── services/         # Microservices (Hono, NestJS)
-│   ├── orders/       # Example: Order processing service (Event Publisher)
-│   ├── notifications/# Example: Notification service (Event Consumer)
+├── services/         # Microservices (generate with pf new hono-micro)
 │   └── nats/         # NATS message broker (auto-scaffolded)
-├── apps/             # Frontend apps (optional: Qwik, Next.js, etc.)
+├── apps/             # Frontend apps (optional)
 ├── packages/         # Shared libraries
-│   ├── contracts/    # Event contracts (Schema Registry - created when generating Event Consumers)
-│   │   └── src/
-│   │       └── index.ts       # Export all contracts
-│   ├── cloudevents/  # Event publishing/consuming toolkit
-│   ├── telemetry/    # OpenTelemetry setup
-│   └── infrastructure/ # Pulumi utilities and K8s builders
+│   └── contracts/    # Event contracts (Schema Registry)
+│       └── src/
+│           └── index.ts
 ├── infra/            # Pulumi Infrastructure-as-Code
 │   ├── index.ts      # Main Pulumi program
-│   └── services/     # Per-service K8s configs
-│       ├── orders.ts
-│       └── notifications.ts
+│   └── services/     # Per-service K8s configs (auto-generated)
 ├── .github/
-│   └── workflows/    # CI/CD pipelines (auto-generated)
+│   └── workflows/    # CI/CD pipelines
 ├── turbo.json        # Turborepo task orchestration
 └── .env.local        # Auto-generated from infra configs
 ```
 
-> **Note:** The `packages/contracts` package starts with just an `index.ts`. Event contract files (e.g., `events/order-created.ts`) are automatically generated when you create **Event Consumer** services with `pf new hono-micro --ai`.
+> **Note:** Services use external packages (`@crossdelta/cloudevents`, `@crossdelta/telemetry`, `@crossdelta/infrastructure`) installed via npm. Only `packages/contracts` is local to your workspace.
 
 ### Key Architectural Decisions
 
@@ -201,11 +184,11 @@ my-platform/
 Services communicate via **CloudEvents** over **NATS JetStream** using the **Schema Registry** as single source of truth:
 
 ```typescript
-// packages/contracts/src/events/order-created.ts (Schema Registry)
+// packages/contracts/src/events/orders-created.ts (Schema Registry)
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export const OrderCreatedContract = createContract({
+export const OrdersCreatedContract = createContract({
   type: 'orders.created',
   schema: z.object({
     orderId: z.string(),
@@ -214,24 +197,24 @@ export const OrderCreatedContract = createContract({
   }),
 })
 
-export type OrderCreatedData = z.infer<typeof OrderCreatedContract.schema>
+export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 
 // Service A publishes an event (Event Publisher)
 import { publish } from '@crossdelta/cloudevents'
-import { OrderCreatedContract } from '@my-platform/contracts'
+import { OrdersCreatedContract } from '@my-platform/contracts'
 
-await publish(OrderCreatedContract, {
+await publish(OrdersCreatedContract, {
   orderId: '123',
   customerId: 'cust-456',
   total: 99.99
 })
 
 // Service B auto-discovers and handles it (Event Consumer)
-// File: services/notifications/src/events/order-created.event.ts
+// File: services/notifications/src/events/orders-created.event.ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrderCreatedContract, type OrderCreatedData } from '@my-platform/contracts'
+import { OrdersCreatedContract, type OrdersCreatedData } from '@my-platform/contracts'
 
-export default handleEvent(OrderCreatedContract, async (data: OrderCreatedData) => {
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
   await sendNotification(data)
 })
 ```
@@ -467,21 +450,21 @@ await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
 ### Consume Events (Auto-Discovered)
 
 ```typescript
-// services/notifications/src/events/order-created.event.ts
+// services/notifications/src/events/orders-created.event.ts
 import { handleEvent } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-const OrderCreatedSchema = z.object({
+const OrdersCreatedSchema = z.object({
   orderId: z.string(),
   total: z.number(),
 })
 
 // Export type for use in use-cases
-export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+export type OrdersCreatedEvent = z.infer<typeof OrdersCreatedSchema>
 
 export default handleEvent(
   {
-    schema: OrderCreatedSchema,
+    schema: OrdersCreatedSchema,
     type: 'orders.created',
   },
   async (data) => {