@crossdelta/platform-sdk 0.13.3 → 0.13.4

package/bin/docs/generators/service.md

@@ -0,0 +1,564 @@
+# Service Generator Instructions
+
+**Generic guidelines for all service types. Framework-specific details are in separate files:**
+- `hono-bun.md` - Hono with Bun runtime
+- `hono-node.md` - Hono with Node.js runtime
+- `nest.md` - NestJS framework
+
+---
+
+## 🚨 CRITICAL: Port Configuration
+
+Services MUST read their port from environment variables using this pattern:
+
+```typescript
+// Convert service name to ENV key format
+// Example: my-hono-service → MY_HONO_SERVICE_PORT
+const port = Number(process.env.MY_HONO_SERVICE_PORT) || 8080
+```
+
+**Port ENV variable naming:**
+- Take service name from package.json `name` field (without scope)
+- Convert to SCREAMING_SNAKE_CASE
+- Append `_PORT`
+
+**Examples:**
+- `@my-platform/orders` → `ORDERS_PORT`
+- `@my-platform/my-nest-service` → `MY_NEST_SERVICE_PORT`
+- `@my-platform/api-gateway` → `API_GATEWAY_PORT`
+
+**⚠️ CRITICAL: DO NOT hardcode or modify the port!**
+- The `pf new` command automatically assigns a unique port
+- The port is written to `.env.local` (e.g., `MY_SERVICE_PORT=4001`)
+- Service code MUST use the correct env variable name
+- DO NOT change the port in generated files!
+
+**When generating service code:**
+1. Determine the correct env variable name from service name
+2. Use ONLY that variable: `process.env.MY_SERVICE_PORT`
+3. DO NOT use generic `PORT` - it causes conflicts!
+4. Keep the `|| 8080` fallback for when `.env.local` is missing
+
+---
+
+## 🚨 CRITICAL: Stream Architecture
+
+> **Services NEVER create streams!**
+>
+> In development, `pf dev` ensures ephemeral streams derived from contracts.
+> In production, streams are materialized explicitly via Pulumi.
+
+---
+
+## Development Workflow
+
+### 1️⃣ **Initial Setup** (once per workspace)
+
+```bash
+pf new workspace my-platform
+cd my-platform
+```
+
+### 2️⃣ **Create Service** (AI or manual)
+
+#### Option A: AI Generation (via GitHub Copilot Chat)
+```
+"Create an order processing service that consumes orders.created events"
+```
+
+**What AI generates:**
+1. **Contract** (`packages/contracts/src/events/orders/created.ts`) - With proper Zod schema in domain-grouped structure
+2. **Service** (`services/order-processing/`) - Scaffolded via `pf new hono-micro`
+3. **Event Handler** (`services/order-processing/src/events/orders-created.handler.ts`)
+4. **Use-Cases** (`services/order-processing/src/use-cases/`)
+5. **Tests** (`services/order-processing/src/use-cases/*.test.ts`)
+
+**What AI includes in response:**
+```commands
+pf new hono-micro services/order-processing -y
+```
+
+```post-commands
+pf event add orders.created --service services/order-processing
+```
+
+**What `pf event add` does:**
+- Creates `packages/contracts/src/events/orders-created.mock.json` (test mock)
+- Adds export to `packages/contracts/src/index.ts`
+- Skips contract creation if already exists (AI's schema is preserved!)
+
+#### Option B: Manual Creation
+
+**Step 1: Create contract with CLI**
+```bash
+# Create contract with schema
+pf event add orders.created --fields "orderId:string,total:number,customerId:string"
+
+# Or with JSON schema
+pf event add orders.created --schema '{"orderId":"string","total":"number"}'
+```
+
+**Step 2: Scaffold service**
+```bash
+pf new hono-micro services/order-processing
+```
+
+**Step 3: Register event and create handler**
+```bash
+pf event add orders.created --service services/order-processing
+```
+
+**Step 4: Implement use-cases**
+```bash
+# Edit services/order-processing/src/use-cases/process-order.use-case.ts
+```
+
+#### Option C: Pure Manual (no CLI)
+
+```bash
+# 1. Create contract manually (domain-grouped)
+mkdir -p packages/contracts/src/events/orders
+# Edit packages/contracts/src/events/orders/created.ts
+
+# 2. Scaffold service
+pf new hono-micro services/order-processing
+
+# 3. Create handler manually
+# Edit services/order-processing/src/events/orders-created.handler.ts
+
+# 4. Implement use-cases
+# Edit services/order-processing/src/use-cases/
+```
+
+### 3️⃣ **Run Development Environment**
+
+```bash
+pf dev  # Starts NATS + creates ephemeral streams from contracts + all services
+```
+
+**What happens:**
+- **NATS** starts in Docker with JetStream enabled
+- **Ephemeral streams** auto-created from contract channel metadata (memory storage, 1h retention)
+- **Services** start and consume from streams
+- **Hot reload** watches for changes
+
+**Stream Creation:** `pf dev` scans `packages/contracts/src/index.ts` for contracts with `channel.stream` metadata and creates ephemeral streams automatically. No manual stream creation needed!
+
+### 4️⃣ **Deploy to Production**
+
+```bash
+cd infra
+pulumi up
+```
+
+**What happens:**
+1. **`infra/streams/`** collects contracts via `collectStreamDefinitions()`
+2. **Streams materialized** via Pulumi with retention policies
+3. **Services deployed** to Kubernetes
+
+---
+
+## �🚨 CRITICAL: Stream Architecture
+
+> **Services NEVER create streams!**
+> **Dev:** Streams are auto-created (ephemeral, memory)
+> **Prod:** Streams are materialized via Pulumi from contracts
+
+### Contracts → Streams → Infra Flow
+
+```typescript
+// 1. Contract defines conceptually (packages/contracts)
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },  // Routing metadata
+  schema: OrderSchema,
+})
+
+// 2. Services consume (no stream creation!)
+consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// 3. Infra materializes (infra/streams/)
+import { collectStreamDefinitions } from '@crossdelta/infrastructure'
+import * as contracts from '@workspace/contracts'
+
+// Generic logic in library, workspace data injected
+const streams = collectStreamDefinitions(contracts)
+deployStreams(provider, namespace, streams)
+```
+
+**Architecture layers:**
+- **@crossdelta/infrastructure:** Generic stream collection logic
+- **Contracts:** Define event semantics + channel routing (workspace data)
+- **`pf dev`:** Ensures ephemeral streams (transient, memory-only)
+- **Platform-Infra:** Materializes streams via Pulumi (persistent, retention)
+- **Services:** Consume streams (never create!)
+
+**Separation of concerns:**
+- **Libraries contain logic** (generic, reusable)
+- **Workspaces contain data** (contracts, policies)
+- **No workspace imports inside libraries**
+
+---
+
+## 🚨 CRITICAL: @crossdelta/cloudevents API
+
+**ONLY these exports exist:**
+- `consumeJetStreams` (preferred) - Consume from multiple streams
+- `consumeJetStreamEvents` (legacy) - Consume from single stream
+- `handleEvent`, `publish`, `createContract`
+
+```ts
+// Services only consume (DO NOT use ensureJetStreams!)
+consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+```
+
+**DO NOT USE in services:**
+- ❌ `ensureJetStreams()` - Only for infra materialization
+- ❌ `ensureJetStreamStream()` - Legacy, only for infra
+- ❌ Manual stream creation - Services never create streams!
+
+---
+
+## 🚨 CRITICAL: @crossdelta/telemetry Import
+
+```ts
+import '@crossdelta/telemetry'  // side-effect, MUST be FIRST import
+```
+
+**DO NOT USE:** `@crossdelta/telemetry/register`, named exports
+
+---
+
+## 🚨 CRITICAL: Commands Block (REQUIRED - MUST BE FIRST)
+
+Your response **MUST START** with a `commands` block that scaffolds the service.
+The exact command depends on the framework - see the framework-specific docs:
+- `hono-bun.md` / `hono-node.md` → `pf new hono-micro`
+- `nest.md` → `pf new nest-micro`
+
+**Without this command, the service cannot be built!**
+
+**What `pf new` creates automatically:**
+1. Service directory structure (`services/<name>/`)
+2. Infrastructure config (`infra/services/<name>.ts`) with assigned port
+3. Package.json with dependencies
+4. Entry point (`src/index.ts` or `src/main.ts`) with port configuration
+5. Health check endpoint
+6. Dockerfile
+
+**⚠️ AI MUST NOT generate `infra/services/<name>.ts`** - This file is automatically created by the CLI with the correct port assignment!
+
+---
+
+## 🚨 CRITICAL: Post-Commands Block (REQUIRED for Event Consumers)
+
+**For Event Consumer services, include a `post-commands` block with ALL events:**
+
+```post-commands
+pf event add orders.created --service services/my-service
+pf event add customers.updated --service services/my-service
+```
+
+**What `pf event add` creates:**
+- `packages/contracts/src/events/<event>.mock.json` - Test mock data
+- Adds export to `packages/contracts/src/index.ts`
+
+**⚠️ IMPORTANT:** `pf event add` skips contract creation if it already exists - so YOUR contract with the correct schema is preserved!
+
+---
+
+## 🚨 CRITICAL: Event Consumer Workflow
+
+**FOR EVENT CONSUMER SERVICES (services that "consume", "listen to", "react to" events):**
+
+### What YOU (the AI) generate:
+
+1. **`packages/contracts/src/events/<domain>/<event>.ts`** - Contract with correct schema fields in domain-grouped structure (e.g., `events/orders/created.ts`)
+2. **`src/events/<event>.handler.ts`** - Event handler that calls the use-case
+3. **`src/use-cases/*.use-case.ts`** - Business logic (called by handlers)
+4. **`src/use-cases/*.test.ts`** - Tests for use-cases
+5. **`README.md`** - Documentation
+
+**⚠️ DO NOT generate `src/index.ts` or `src/main.ts`** - These are created by `pf new` with correct port config!
+
+### Handler Location (CRITICAL!)
+
+**⚠️ MUST be in `src/events/*.handler.ts` - NEVER in `handlers/` subdirectory**
+
+```
+✅ CORRECT:
+services/my-service/src/events/
+├── orders-created.handler.ts
+└── customers-updated.handler.ts
+
+❌ WRONG:
+services/my-service/src/events/handlers/  # NEVER create!
+```
+
+### Handler Export Pattern
+
+```ts
+// ✅ CORRECT: Default export
+export default handleEvent(OrdersCreatedContract, async (data) => { ... })
+
+// ❌ WRONG: Named export
+export const OrdersCreatedHandler = handleEvent(...)
+```
+
+### Handler Logging
+
+**Handlers must be thin** - use `console.log` for logging, then delegate to use-case/service:
+
+```ts
+export default handleEvent(OrdersCreatedContract, async (data) => {
+  console.log(`[orders.created] Processing orderId=${data.orderId}`)  // ✅ console.log
+  await processOrder(data)
+})
+```
+
+**Services/use-cases** can use structured logging (NestJS: `new Logger(ServiceName.name)`).
+
+---
+
+## 🚨 Response Structure
+
+```commands
+pf new hono-micro services/my-service -y
+```
+
+#### `packages/contracts/src/events/orders/created.ts`
+```ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrdersCreatedSchema = z.object({
+  orderId: z.string(),
+  total: z.number(),
+})
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },
+  schema: OrdersCreatedSchema,
+})
+
+export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+```
+
+#### `src/events/orders-created.handler.ts`
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { processOrder } from '../use-cases/process-order.use-case'
+
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+  console.log('📦 Processing order:', data.orderId)
+  await processOrder(data)
+})
+```
+
+#### `src/use-cases/process-order.use-case.ts`
+```ts
+import type { OrdersCreatedData } from '{{scope}}/contracts'
+
+export const processOrder = async (data: OrdersCreatedData): Promise<void> => {
+  console.log('Processing:', data.orderId)
+}
+```
+
+```post-commands
+pf event add orders.created --service services/my-service
+```
+
+```dependencies
+@pusher/push-notifications-server
+```
+
+---
+
+## 🚨 CRITICAL: Schema Fields Consistency
+
+**ONLY use fields that exist in YOUR generated schema!**
+
+```ts
+// If you generate this schema:
+export const DomainCreatedSchema = z.object({
+  domainId: z.string(),
+  name: z.string(),
+  ownerEmail: z.string().email(),
+})
+
+// Then ONLY use these fields in service code:
+await sendEmail(data.ownerEmail)      // ✅ EXISTS in schema
+await notifyUser(data.userId)         // ❌ WRONG - userId not in schema!
+```
+
+**DO NOT hallucinate fields** like `userId`, `customerId`, etc. unless they are in YOUR schema.
+
+---
+
+## Contract Schema (Zod 4 Syntax)
+
+```ts
+export const OrdersCreatedSchema = z.object({
+  orderId: z.string(),
+  email: z.string().email(),        // ✅ Zod 4: no params
+  total: z.number(),
+  createdAt: z.string().datetime(), // ✅ Zod 4: no params
+})
+```
+
+**Zod 4 Quick Reference:**
+- ✅ `z.string().email()` - no params
+- ✅ `z.string().url()` - no params
+- ❌ `z.string().email('Invalid')` - DEPRECATED
+
+---
+
+## Naming Convention
+
+**Architecture Rule:**
+
+| Component | Format | Example | Reason |
+|-----------|--------|---------|--------|
+| **Event Type** | **Singular** | `domain.created` | Describes a single event |
+| **Stream** | **PLURAL** | `DOMAINS` | Collection of events for a domain |
+
+**Merksatz:** Events sind singular. Streams sind plural.
+
+### Examples
+
+| Event Type | Contract | File | Stream |
+|------------|----------|------|--------|
+| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` | `ORDERS` ✅ |
+| `domain.created` | `DomainCreatedContract` | `domain-created.ts` | `DOMAINS` ✅ |
+
+```typescript
+// ✅ CORRECT
+export const DomainCreatedContract = createContract({
+  type: 'domain.created',           // Singular event
+  channel: { stream: 'DOMAINS' },   // Plural stream
+  schema: DomainCreatedSchema,
+})
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',           // Singular event (but namespace plural!)
+  channel: { stream: 'ORDERS' },    // Plural stream
+  schema: OrdersCreatedSchema,
+})
+
+// ❌ WRONG
+export const DomainCreatedContract = createContract({
+  type: 'domain.created',
+  channel: { stream: 'DOMAIN' },    // ❌ Must be DOMAINS (plural!)
+  schema: DomainCreatedSchema,
+})
+```
+
+### Stream Names in consumeJetStreams
+
+**CRITICAL:** When consuming from streams, use the **PLURAL** stream name from the contract's `channel.stream`:
+
+```typescript
+// ✅ CORRECT - domain.created event → DOMAINS stream
+consumeJetStreams({
+  streams: ['DOMAINS'],  // ✅ Plural!
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ✅ CORRECT - orders.created event → ORDERS stream
+consumeJetStreams({
+  streams: ['ORDERS'],  // ✅ Plural!
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ❌ WRONG - Don't use singular!
+consumeJetStreams({
+  streams: ['DOMAIN'],   // ❌ Wrong! Should be DOMAINS
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+
+// ❌ WRONG - Don't use lowercase!
+consumeJetStreams({
+  streams: ['domains'],  // ❌ Wrong! Should be DOMAINS (uppercase)
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+})
+```
+
+**Rule:** Extract the stream name from your contract's `channel.stream` field and use it EXACTLY in `consumeJetStreams({ streams: ['...'] })`.
+
+---
+
+## Block Explanations
+
+| Block | Purpose |
+|-------|---------|
+| `commands` | Scaffolds service (REQUIRED FIRST) |
+| `post-commands` | Runs after files created (e.g., `pf event add`) |
+| `dependencies` | Extra npm packages (NOT `@crossdelta/*`) |
+
+---
+
+## Service Types
+
+### 📤 Event Publisher (REST API)
+**Keywords:** "publishes", "creates", "manages", "REST API"
+
+### 📥 Event Consumer (NATS)
+**Keywords:** "consumes", "listens to", "reacts to", "handles events"
+
+
+### 🔄 Hybrid (Both)
+Combines REST endpoints + NATS consumer.
+
+---
+
+## Required Files (Hono)
+
+```
+services/my-service/src/
+├── index.ts
+├── events/orders-created.handler.ts
+└── use-cases/
+    ├── process-order.use-case.ts
+    └── process-order.test.ts
+
+packages/contracts/src/events/
+└── orders-created.ts
+```
+
+**Note:** For NestJS structure, see `nest.md` - NestJS uses Services instead of use-cases.
+
+---
+
+## Absolute Rules
+
+**DO NOT:**
+- ❌ Use raw NATS clients
+- ❌ Put business logic in handlers or entry points
+- ❌ Use `src/handlers/` (use `src/events/`)
+- ❌ Create `src/types/` directory (use contracts)
+- ❌ Insert semicolons
+- ❌ Edit `packages/contracts/src/index.ts` (CLI handles exports)
+- ❌ Create `use-cases/` folder in NestJS (use Services instead)
+
+**DO:**
+- ✅ Contracts in `packages/contracts/src/events/`
+- ✅ Handlers in `src/events/*.handler.ts`
+- ✅ Hono: Use-cases in `src/use-cases/*.use-case.ts`
+- ✅ NestJS: Business logic in Services + pure helper functions
+- ✅ Log event type and key identifier in handlers
+- ✅ Keep handlers thin - delegate to use-cases/services
+- ✅ Verify package names on npmjs.com before using

package/bin/docs/generators/testing.md

@@ -0,0 +1,97 @@
+# Testing Guidelines
+
+## 🚨 CRITICAL: bun:test Only
+
+```ts
+// ✅ CORRECT
+import { describe, expect, it } from 'bun:test'
+
+// ❌ WRONG - do NOT use
+jest.mock(...)              // Jest doesn't work
+jest.unstable_mockModule()  // Jest doesn't work
+vi.mock(...)                // Vitest doesn't work
+```
+
+---
+
+## What to Test
+
+- Test ONLY use-cases (not handlers)
+- No mocking - use dependency injection
+
+```ts
+import { describe, expect, it } from 'bun:test'
+import { processOrder } from './process-order.use-case'
+
+describe('processOrder', () => {
+  it('processes order', async () => {
+    const store = new Map()
+    await processOrder({ orderId: '123', total: 100 }, store)
+    expect(store.has('123')).toBe(true)
+  })
+
+  it('throws on missing data', async () => {
+    await expect(processOrder(null as any, new Map())).rejects.toThrow()
+  })
+})
+```
+
+---
+
+## External Services & Config
+
+Use dependency injection, not mocking:
+
+```ts
+// ✅ Use-case accepts dependencies
+export const sendPush = async (
+  data: PushData,
+  config: { instanceId: string }
+) => {
+  if (!config.instanceId) throw new Error('Missing instanceId')
+}
+
+// ✅ Test with fake/config
+it('throws on missing config', async () => {
+  await expect(sendPush({}, { instanceId: '' })).rejects.toThrow()
+})
+```
+
+---
+
+## ❌ WRONG patterns (NEVER use these)
+
+```ts
+// process.env manipulation
+beforeEach(() => { process.env.X = 'test' })
+afterEach(() => { process.env = env })
+
+// @ts-ignore for mocking
+// @ts-ignore
+svc.beams = new FakeBeams()
+
+// Jest/Vitest mocking
+jest.mock(...)
+vi.mock(...)
+
+// Dynamic imports for error testing
+await expect(import('./module')).rejects.toThrow()
+```
+
+---
+
+## NestJS Services
+
+For NestJS: extract business logic into pure functions, test those:
+
+```ts
+// ✅ Extract testable logic from service
+export const validateConfig = (config: { id: string }) => {
+  if (!config.id) throw new Error('Missing id')
+}
+
+// ✅ Test the extracted function
+it('validates config', () => {
+  expect(() => validateConfig({ id: '' })).toThrow()
+})
+```

package/bin/integration.collection.json

@@ -0,0 +1,18 @@
+[
+    {
+        "name": "@crossdelta/cloudevents",
+        "description": "Type-safe event-driven microservices with NATS and Zod validation",
+        "link": "https://www.npmjs.com/package/@crossdelta/cloudevents",
+        "install": ["@crossdelta/cloudevents", "zod@^4.0.0"],
+        "run": [],
+        "initial": true
+    },
+    {
+        "name": "@crossdelta/telemetry",
+        "description": "Zero-config OpenTelemetry instrumentation for TypeScript services",
+        "link": "https://www.npmjs.com/package/@crossdelta/telemetry",
+        "install": "@crossdelta/telemetry",
+        "run": [],
+        "initial": true
+    }
+]

package/bin/templates/hono-microservice/Dockerfile.hbs

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1.7-labs
+ARG BUN_VERSION={{bunVersion}}
+
+FROM oven/bun:${BUN_VERSION}-alpine AS production
+WORKDIR /app
+
+COPY bunfig.toml package.json ./
+COPY src ./src
+
+RUN --mount=type=secret,id=NPM_TOKEN \
+  export NPM_TOKEN="$(cat /run/secrets/NPM_TOKEN)" && \
+  bun install --production --omit=optional
+
+USER bun
+
+CMD ["bun", "run", "src/index.ts"]

package/bin/templates/hono-microservice/biome.json.hbs

@@ -0,0 +1,3 @@
+{
+  "extends": ["../../biome.json"]
+}