@crossdelta/platform-sdk 0.13.1 → 0.13.2

package/bin/docs/generators/README.md

@@ -1,56 +0,0 @@
-# Generator Documentation
-
-This directory contains AI instructions for code generators.
-
-## Structure
-
-```
-generators/
-├── README.md           # This file
-├── service.md          # Main service generator instructions
-├── code-style.md       # Code style, formatting, naming conventions
-├── testing.md          # Testing rules and patterns
-├── hono-bun.md         # Hono with Bun runtime specifics
-├── hono-node.md        # Hono with Node.js runtime specifics
-└── nest.md             # NestJS framework specifics
-```
-
-## How Instructions Are Loaded
-
-Instructions are configured in `package.json` under `generatorConfig.docs`:
-
-```json
-{
-  "generatorConfig": {
-    "docs": {
-      "base": ["service.md", "code-style.md", "testing.md"],
-      "frameworks": {
-        "hono": { "bun": "hono-bun.md", "node": "hono-node.md" },
-        "nest": "nest.md"
-      }
-    }
-  }
-}
-```
-
-**Load Order:**
-1. **Base docs** - Always loaded (service.md, code-style.md, testing.md)
-2. **Framework-specific** - Based on `serviceType` and `packageManager`
-3. **Workspace instructions** - `.github/copilot-instructions.md`, `docs/ai-guidelines.md`
-
-## Adding New Generators
-
-To add instructions for a new framework:
-
-1. Create `<framework>.md` in this directory
-2. Add to `generatorConfig.docs.frameworks` in `package.json`
-3. Follow the existing format from `hono-bun.md` or `nest.md`
-
-## Template Variables
-
-The following variables are replaced at runtime:
-
-| Variable | Description |
-|----------|-------------|
-| `{{scope}}` | Package scope (e.g., `@orderboss`) |
-| `{{AVAILABLE_CONTRACTS}}` | Auto-generated list of existing contracts |

package/bin/docs/generators/code-style.md

@@ -1,96 +0,0 @@
-# Code Style
-
-## Formatting
-
-- Single quotes, no semicolons, 2-space indent, trailing commas
-- Arrow functions over `function`
-- Template literals over concatenation
-
----
-
-## Imports
-
-**Must be alphabetically sorted** (Biome enforces this):
-
-```ts
-// ✅ CORRECT - sorted alphabetically, type imports first
-import type { DomainCreatedData } from '@my-platform/contracts'
-import type { OrdersCreatedData } from '@scope/contracts'
-import { handleEvent } from '@crossdelta/cloudevents'
-import PusherPushNotifications from '@pusher/push-notifications-server'
-
-// ❌ WRONG - unsorted
-import PusherPushNotifications from '@pusher/push-notifications-server'
-import type { DomainCreatedData } from '@my-platform/contracts'
-
-// ❌ WRONG - missing 'type' keyword
-import { OrdersCreatedData } from '@scope/contracts'
-
-// ❌ WRONG - unused imports
-import { handleEvent, publish } from '@crossdelta/cloudevents'
-```
-
----
-
-## Environment Variables
-
-```ts
-// ✅ CORRECT
-const apiKey = process.env.API_KEY
-if (!apiKey) throw new Error('Missing API_KEY')
-
-// ❌ WRONG
-const apiKey = process.env.API_KEY!  // no assertions
-```
-
----
-
-## Naming
-
-| Type | Convention | Example |
-|------|------------|---------|
-| Files | kebab-case | `send-notification.use-case.ts` |
-| Contracts | PascalCase | `OrdersCreatedContract` |
-| Types | PascalCase + Data | `OrdersCreatedData` |
-
----
-
-## Config Validation (Type Narrowing)
-
-Use validation functions that return typed objects - avoids `!` assertions:
-
-```ts
-// ✅ CORRECT - validation returns typed object
-export const validateBeamsConfig = (config: {
-  instanceId?: string
-  secretKey?: string
-}): { instanceId: string; secretKey: string } => {
-  if (!config.instanceId) throw new Error('Missing PUSHER_BEAMS_INSTANCE_ID')
-  if (!config.secretKey) throw new Error('Missing PUSHER_BEAMS_SECRET_KEY')
-  return { instanceId: config.instanceId, secretKey: config.secretKey }
-}
-
-// Usage - no assertions needed
-const config = validateBeamsConfig({
-  instanceId: process.env.PUSHER_BEAMS_INSTANCE_ID,
-  secretKey: process.env.PUSHER_BEAMS_SECRET_KEY,
-})
-new PusherClient(config)  // ✅ Typed correctly
-
-// ❌ WRONG - non-null assertions (Biome error)
-validateConfig({ instanceId, secretKey })
-new PusherClient({ instanceId: instanceId!, secretKey: secretKey! })
-```
-
----
-
-## Zod 4
-
-```ts
-// ✅ No params
-z.string().email()
-z.string().datetime()
-
-// ❌ Deprecated
-z.string().email('Invalid')
-```

package/bin/docs/generators/hono-bun.md

@@ -1,181 +0,0 @@
-# Hono (Bun Runtime)
-
-## 🚨 CRITICAL: AI Generation Rules
-
-**DO NOT create from scratch:**
-- ❌ `infra/services/<name>.ts` - Created by CLI with port assignment
-- ❌ `Dockerfile` - Created by CLI
-- ❌ `package.json` - Created by CLI
-
-**Always generate:**
-- ✅ Event handlers (`src/events/*.handler.ts`)
-- ✅ Use-cases (`src/use-cases/*.use-case.ts`)
-- ✅ Tests (`src/**/*.test.ts`)
-- ✅ README.md
-- ✅ Contracts (`packages/contracts/src/events/`)
-
----
-
-## 🚨 CRITICAL: Commands Block (REQUIRED FIRST)
-
-```commands
-pf new hono-micro services/<service-name> -y
-```
-
-**Example:** User asks for "push notifications service" → generate:
-```commands
-pf new hono-micro services/push-notifications -y
-```
-
----
-
-## Entry Point (src/index.ts)
-
-**REST API:**
-```ts
-import '@crossdelta/telemetry'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-// Example: my-hono-service → MY_HONO_SERVICE_PORT
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-Bun.serve({ port, fetch: app.fetch })
-console.log(`Service running on http://localhost:${port}`)
-```
-
-**Event Consumer:**
-```ts
-import '@crossdelta/telemetry'
-import { consumeJetStreams } from '@crossdelta/cloudevents'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-Bun.serve({ port, fetch: app.fetch })
-console.log(`Service running on http://localhost:${port}`)
-
-// Services NEVER create streams!
-// - Development: pf dev auto-creates ephemeral streams from contracts
-// - Production: Pulumi materializes persistent streams
-consumeJetStreams({
-  streams: ['ORDERS'],  // ⚠️ MUST be PLURAL! Extract from contract's channel.stream
-  consumer: 'my-service',
-  discover: './src/events/**/*.handler.ts',
-})
-```
-
-**CRITICAL:** Stream names MUST be PLURAL:
-- ✅ `streams: ['ORDERS']` - for orders.created event
-- ✅ `streams: ['DOMAINS']` - for domain.created event
-- ❌ `streams: ['ORDER']` - WRONG (singular)
-- ❌ `streams: ['DOMAIN']` - WRONG (singular)
-
-**Event Publisher:**
-```ts
-import '@crossdelta/telemetry'
-import { publish } from '@crossdelta/cloudevents'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-app.post('/orders', async (c) => {
-  const data = await c.req.json()
-  await publish('orders.created', data)
-  return c.json({ success: true })
-})
-
-Bun.serve({ port, fetch: app.fetch })
-console.log(`Service running on http://localhost:${port}`)
-```
-
----
-
-## Environment Validation (Optional)
-
-**For services with required env vars:**
-
-### 1️⃣ Create `src/config/env.ts`:
-
-```ts
-// src/config/env.ts
-import { z } from 'zod'
-
-// ⚠️ DO NOT include SERVICE_NAME_PORT here - it's already handled by template!
-// Only validate YOUR custom env vars
-const envSchema = z.object({
-  PUSHER_INSTANCE_ID: z.string().min(1, 'PUSHER_INSTANCE_ID is required'),
-  PUSHER_SECRET_KEY: z.string().min(1, 'PUSHER_SECRET_KEY is required'),
-  NATS_URL: z.string().url().default('nats://localhost:4222'),
-})
-
-export type Env = z.infer<typeof envSchema>
-
-// Validate and crash process if invalid (like @nestjs/config)
-const result = envSchema.safeParse(process.env)
-if (!result.success) {
-  console.error('❌ Environment validation failed:')
-  console.error(result.error.format())
-  process.exit(1)  // ← Force crash with exit code 1
-}
-
-export const env = result.data
-```
-
-### 2️⃣ **CRITICAL: Import in `src/index.ts` early!**
-
-```ts
-// src/index.ts
-import '@crossdelta/telemetry'  // ← MUST be first!
-
-// ⚠️ CRITICAL: Import env IMMEDIATELY after telemetry
-// This executes validation and crashes process if env invalid
-import { env } from './config/env'  // ← THIS LINE IS REQUIRED!
-
-import { Hono } from 'hono'
-
-const port = Number(process.env.MY_SERVICE_PORT) || 8080  // ← Handled by template
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-app.post('/notify', async (c) => {
-  const data = await c.req.json()
-  // Use validated env vars
-  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
-  return c.json({ success: true })
-})
-
-Bun.serve({ port, fetch: app.fetch })
-console.log(`Service running on http://localhost:${port}`)
-```
-
-**CRITICAL:**
-- ✅ **MUST import `env` in `src/index.ts`** - without import, validation never runs!
-- ✅ Import early (after telemetry, before everything else)
-- ✅ Use `safeParse()` + `process.exit(1)` - Bun doesn't crash on top-level throws
-- ✅ Explicit exit ensures Turbo shows red X (like NestJS)
-- ❌ **DO NOT** include `SERVICE_NAME_PORT` in env schema - already handled by CLI template
-- ❌ **DO NOT** validate inside handlers or use-cases
-
----
-
-## Rules
-
-- ✅ `Bun.serve({ port, fetch: app.fetch })`
-- ✅ Import telemetry FIRST
-- ✅ Always include `/health`
-- ✅ Use port env var from prompt (e.g., `PUSH_NOTIFICATIONS_PORT`)
-- ❌ `export default Bun.serve(...)` - wrong
-- ❌ `export default app` - not needed

package/bin/docs/generators/hono-node.md

@@ -1,194 +0,0 @@
-# Hono (Node.js Runtime)
-
-## 🚨 CRITICAL: AI Generation Rules
-
-**DO NOT generate these files** - they are created by `pf new hono-micro`:
-- ❌ `infra/services/<name>.ts` - Infrastructure config with assigned port
-- ❌ `Dockerfile` - Container configuration
-- ❌ `package.json` - Dependencies and scripts
-
-**Always generate:**
-- ✅ Event handlers (`src/events/*.handler.ts`)
-- ✅ Use-cases (`src/use-cases/*.use-case.ts`)
-- ✅ Tests (`src/**/*.test.ts`)
-- ✅ README.md
-- ✅ Contracts (`packages/contracts/src/events/`)
-
----
-
-## 🚨 CRITICAL: Commands Block (REQUIRED FIRST)
-
-```commands
-pf new hono-micro services/<service-name> -y
-```
-
-**Example:** User asks for "push notifications service" → generate:
-```commands
-pf new hono-micro services/push-notifications -y
-```
-
----
-
-## Entry Point (src/index.ts)
-
-**REST API:**
-```ts
-import '@crossdelta/telemetry'
-import { serve } from '@hono/node-server'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-serve({ fetch: app.fetch, port }, (info) => {
-  console.log(`Server running on http://localhost:${info.port}`)
-})
-```
-
-**Event Consumer:**
-```ts
-import '@crossdelta/telemetry'
-import { consumeJetStreams } from '@crossdelta/cloudevents'
-import { serve } from '@hono/node-server'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-serve({ fetch: app.fetch, port }, (info) => {
-  console.log(`Server running on http://localhost:${info.port}`)
-})
-
-// Services NEVER create streams!
-// - Development: pf dev auto-creates ephemeral streams from contracts
-// - Production: Pulumi materializes persistent streams
-consumeJetStreams({
-  streams: ['ORDERS'],  // ⚠️ MUST be PLURAL! Extract from contract's channel.stream
-  consumer: 'my-service',
-  discover: './src/events/**/*.handler.ts',
-})
-```
-
-**CRITICAL:** Stream names MUST be PLURAL:
-- ✅ `streams: ['ORDERS']` - for orders.created event
-- ✅ `streams: ['DOMAINS']` - for domain.created event
-- ❌ `streams: ['ORDER']` - WRONG (singular)
-- ❌ `streams: ['DOMAIN']` - WRONG (singular)
-
-**Event Publisher:**
-```ts
-import '@crossdelta/telemetry'
-import { publish } from '@crossdelta/cloudevents'
-import { serve } from '@hono/node-server'
-import { Hono } from 'hono'
-
-// Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
-const port = Number(process.env.MY_SERVICE_PORT) || 8080
-const app = new Hono()
-
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-app.post('/orders', async (c) => {
-  const data = await c.req.json()
-  await publish('orders.created', data)
-  return c.json({ success: true })
-})
-
-serve({ fetch: app.fetch, port }, (info) => {
-  console.log(`Server running on http://localhost:${info.port}`)
-})
-```
-
----
-
-## Environment Validation (Optional)
-
-**For services with required env vars:**
-
-### 1️⃣ Create `src/config/env.ts`:
-
-```ts
-// src/config/env.ts
-import { z } from 'zod'
-
-// ⚠️ DO NOT include SERVICE_NAME_PORT here - it's already handled by template!
-// Only validate YOUR custom env vars
-const envSchema = z.object({
-  PUSHER_INSTANCE_ID: z.string().min(1, 'PUSHER_INSTANCE_ID is required'),
-  PUSHER_SECRET_KEY: z.string().min(1, 'PUSHER_SECRET_KEY is required'),
-  NATS_URL: z.string().url().default('nats://localhost:4222'),
-})
-
-export type Env = z.infer<typeof envSchema>
-
-// Validate and crash process if invalid (like @nestjs/config)
-const result = envSchema.safeParse(process.env)
-if (!result.success) {
-  console.error('❌ Environment validation failed:')
-  console.error(result.error.format())
-  process.exit(1)  // ← Force crash with exit code 1
-}
-
-export const env = result.data
-```
-
-### 2️⃣ **CRITICAL: Import in `src/index.ts` early!**
-
-```ts
-// src/index.ts
-import '@crossdelta/telemetry'  // ← MUST be first!
-
-// ⚠️ CRITICAL: Import env IMMEDIATELY after telemetry
-// This executes validation and crashes process if env invalid
-import { env } from './config/env'  // ← THIS LINE IS REQUIRED!
-
-import { serve } from '@hono/node-server'
-import { Hono } from 'hono'
-import { consumeJetStreams } from '@crossdelta/cloudevents'
-
-const port = Number(process.env.NOTIFICATIONS_PORT) || 8080  // ← Handled by template
-
-const app = new Hono()
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-app.post('/notify', async (c) => {
-  const data = await c.req.json()
-  // Use validated env vars
-  await sendPush(env.PUSHER_INSTANCE_ID, env.PUSHER_SECRET_KEY, data)
-  return c.json({ success: true })
-})
-
-consumeJetStreams({
-  streams: ['DOMAINS'],
-  consumer: 'notifications',
-  discover: './src/events/**/*.handler.ts',
-})
-
-serve({ fetch: app.fetch, port }, (info) => {
-  console.log(`Server running on http://localhost:${info.port}`)
-})
-```
-
-**CRITICAL:**
-- ✅ **MUST import `env` in `src/index.ts`** - without import, validation never runs!
-- ✅ Import early (after telemetry, before everything else)
-- ✅ Use `safeParse()` + `process.exit(1)` - ensures proper crash behavior
-- ✅ Explicit exit ensures Turbo shows red X (like NestJS)
-- ❌ **DO NOT** include `SERVICE_NAME_PORT` in env schema - already handled by CLI template
-- ❌ **DO NOT** validate inside handlers or use-cases
-
----
-
-## Rules
-
-- ✅ `serve()` from `@hono/node-server`
-- ✅ Import telemetry FIRST
-- ✅ Always include `/health`
-- ✅ Use port env var from prompt (e.g., `API_GATEWAY_PORT`)
-- ❌ `Bun.serve()` - wrong runtime