@crossdelta/platform-sdk 0.16.0 → 0.16.2

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

@@ -3,6 +3,7 @@
 ## 🚨 CRITICAL: AI Generation Rules
 
 **DO NOT create from scratch:**
+- ❌ `src/index.ts` - Entry point created by CLI with port configuration
 - ❌ `infra/services/<name>.ts` - Created by CLI with port assignment
 - ❌ `Dockerfile` - Created by CLI
 - ❌ `package.json` - Created by CLI
@@ -31,9 +32,16 @@ pf new hono-micro services/push-notifications -y
 
 ## Entry Point (src/index.ts)
 
+**⚠️ CRITICAL: Import Order**
+1. **Environment validation** (`./config/env`) - Validate env vars before loading any modules
+2. **Telemetry** (`@crossdelta/telemetry`) - Patch modules before they're imported
+3. All other imports follow
+
 **REST API:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { Hono } from 'hono'
 
 // Replace MY_SERVICE with actual service name in SCREAMING_SNAKE_CASE
@@ -49,7 +57,9 @@ console.log(`Service running on http://localhost:${port}`)
 
 **Event Consumer:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { consumeJetStreams } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
@@ -80,7 +90,9 @@ consumeJetStreams({
 
 **Event Publisher:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { publish } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
@@ -102,9 +114,68 @@ console.log(`Service running on http://localhost:${port}`)
 
 ---
 
-## Environment Validation (Optional)
+## Environment Validation (src/config/env.ts)
+
+**⚠️ REQUIRED: Environment validation must be created for all services**
+
+The scaffold automatically creates `src/config/env.ts` with basic validation.
+
+**Default generated file:**
+
+```ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  MY_SERVICE_PORT: z.string().optional(),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)
+}
+
+export const env = result.data
+```
+
+**Add required environment variables:**
+
+```ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  // Port is optional (has fallback in index.ts)
+  MY_SERVICE_PORT: z.string().optional(),
+
+  // Add your required env vars here
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().min(1, 'API_KEY is required'),
+  REDIS_URL: z.string().url().optional(),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)
+}
+
+export const env = result.data
+```
+
+**Rules:**
+- ✅ Use `safeParse()` + explicit error handling for better error messages
+- ✅ Export validated `env` object for type-safe access
+- ✅ Use Zod v4 syntax (no params on `.email()`, `.url()`, etc.)
+- ✅ Port is always optional (has fallback in index.ts)
+- ❌ DO NOT add PORT to env schema - it's read directly from process.env
+
+---
+
+## Environment Validation (Optional - Legacy)
 
-**For services with required env vars:**
+**For services with required env vars (DEPRECATED - use src/config/env.ts instead):**
 
 ### 1️⃣ Create `src/config/env.ts`:
 

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

@@ -3,6 +3,7 @@
 ## 🚨 CRITICAL: AI Generation Rules
 
 **DO NOT generate these files** - they are created by `pf new hono-micro`:
+- ❌ `src/index.ts` - Entry point with port configuration
 - ❌ `infra/services/<name>.ts` - Infrastructure config with assigned port
 - ❌ `Dockerfile` - Container configuration
 - ❌ `package.json` - Dependencies and scripts
@@ -31,9 +32,16 @@ pf new hono-micro services/push-notifications -y
 
 ## Entry Point (src/index.ts)
 
+**⚠️ CRITICAL: Import Order**
+1. **Environment validation** (`./config/env`) - Validate env vars before loading any modules
+2. **Telemetry** (`@crossdelta/telemetry`) - Patch modules before they're imported
+3. All other imports follow
+
 **REST API:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
@@ -50,7 +58,9 @@ serve({ fetch: app.fetch, port }, (info) => {
 
 **Event Consumer:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { consumeJetStreams } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
@@ -83,7 +93,9 @@ consumeJetStreams({
 
 **Event Publisher:**
 ```ts
+import './config/env'
 import '@crossdelta/telemetry'
+
 import { publish } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
@@ -107,6 +119,64 @@ serve({ fetch: app.fetch, port }, (info) => {
 
 ---
 
+## Environment Validation (src/config/env.ts)
+
+**⚠️ REQUIRED: Environment validation must be created for all services**
+
+The scaffold automatically creates `src/config/env.ts` with basic validation.
+
+**Default generated file:**
+
+```ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  MY_SERVICE_PORT: z.string().optional(),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)
+}
+
+export const env = result.data
+```
+
+**Add required environment variables:**
+
+```ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  // Port is optional (has fallback in index.ts)
+  MY_SERVICE_PORT: z.string().optional(),
+
+  // Add your required env vars here
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().min(1, 'API_KEY is required'),
+  REDIS_URL: z.string().url().optional(),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)
+}
+
+export const env = result.data
+```
+
+**Rules:**
+- ✅ Use `safeParse()` + explicit error handling for better error messages
+- ✅ Export validated `env` object for type-safe access
+- ✅ Use Zod v4 syntax (no params on `.email()`, `.url()`, etc.)
+- ✅ Port is always optional (has fallback in index.ts)
+- ❌ DO NOT add PORT to env schema - it's read directly from process.env
+
+---
 ## Environment Validation (Optional)
 
 **For services with required env vars:**

package/bin/docs/generators/nest.md

@@ -7,6 +7,7 @@
 ## 🚨 CRITICAL: AI Generation Rules
 
 **DO NOT generate these files** - they are created by `pf new nest-micro`:
+- ❌ `src/main.ts` - Entry point with port configuration
 - ❌ `infra/services/<name>.ts` - Infrastructure config with assigned port
 - ❌ `Dockerfile` - Container configuration
 - ❌ `package.json` - Dependencies and scripts
@@ -39,7 +40,10 @@
 import { z } from 'zod'
 
 export const envSchema = z.object({
-  PORT: z.string().transform(Number).default('8080'),
+  // ❌ WRONG: Don't define service port - it's set by CLI via SERVICE_NAME_PORT
+  // PORT: z.string().transform(Number).default('8080'),
+
+  // ✅ CORRECT: Only define service-specific env vars
   PUSHER_INSTANCE_ID: z.string().min(1),
   PUSHER_SECRET_KEY: z.string().min(1),
   NATS_URL: z.string().url().default('nats://localhost:4222'),
@@ -48,6 +52,12 @@ export const envSchema = z.object({
 export type Env = z.infer<typeof envSchema>
 ```
 
+**⚠️ CRITICAL: Port Configuration**
+- **DO NOT** define `PORT` or `SERVICE_NAME_PORT` in `env.schema.ts`
+- Service port is automatically set by CLI via `MY_SERVICE_PORT` env variable
+- Read port in `main.ts`: `const port = Number(process.env.MY_SERVICE_PORT) || 8080`
+- Port is assigned during `pf new nest-micro` and stored in `.env.local`
+
 ```ts
 // src/app.module.ts
 import { Module } from '@nestjs/common'
@@ -77,7 +87,7 @@ export class MyService {
 
   doSomething() {
     const instanceId = this.config.get('PUSHER_INSTANCE_ID') // Type-safe!
-    const port = this.config.get('PORT') // number (auto-transformed)
+    const natsUrl = this.config.get('NATS_URL') // string with default
   }
 }
 ```

package/bin/docs/generators/service.md

@@ -32,12 +32,14 @@ const port = Number(process.env.MY_HONO_SERVICE_PORT) || 8080
 - 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!
+- **DO NOT include port in env schemas** (e.g., Zod schemas, ConfigModule validation)
 
 **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
+5. **DO NOT add port to env.schema.ts** - it's read directly from process.env
 
 ---
 
@@ -254,7 +256,11 @@ The exact command depends on the framework - see the framework-specific docs:
 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!
+**⚠️ AI MUST NOT generate these files** - They are automatically created by the CLI:
+- ❌ `infra/services/<name>.ts` - CLI creates with correct port assignment
+- ❌ `src/index.ts` (Hono) or `src/main.ts` (NestJS) - CLI creates with correct entry point
+- ❌ `package.json` - CLI creates with correct dependencies
+- ❌ `Dockerfile` - CLI creates with correct runtime
 
 ---
 
@@ -382,6 +388,8 @@ pf event add orders.created --service services/my-service
 @pusher/push-notifications-server
 ```
 
+> **Note:** When using external packages, always check the official documentation for the current API. Example: `@pusher/push-notifications-server` - check [npmjs.com](https://www.npmjs.com/package/@pusher/push-notifications-server) for latest usage patterns and avoid deprecated methods.
+
 ---
 
 ## 🚨 CRITICAL: Schema Fields Consistency
@@ -425,40 +433,68 @@ export const OrdersCreatedSchema = z.object({
 
 ## Naming Convention
 
-**Architecture Rule:**
+**🚨 CRITICAL: Singular vs. Plural Architecture Rule**
 
 | Component | Format | Example | Reason |
 |-----------|--------|---------|--------|
-| **Event Type** | **Singular** | `domain.created` | Describes a single event |
-| **Stream** | **PLURAL** | `DOMAINS` | Collection of events for a domain |
+| **Event Type** | **Singular** | `customer.created` | Describes a single event |
+| **Event Folder** | **PLURAL** | `customers/` | Domain grouping (matches stream) |
+| **Stream** | **PLURAL** | `CUSTOMERS` | Collection of events for a domain |
+| **Mock Files** | **PLURAL folder** | `customers/created.mock.json` | Must match event folder |
+
+**Merksatz:**
+- **Singular** describes an event
+- **Plural** describes a domain
 
-**Merksatz:** Events sind singular. Streams sind plural.
+### File Structure Example
+
+```
+packages/contracts/src/events/
+├── customers/                          ✅ PLURAL (domain)
+│   ├── created.ts                     (customer.created event)
+│   ├── created.mock.json              ✅ PLURAL folder
+│   └── updated.ts                     (customer.updated event)
+└── orders/                            ✅ PLURAL (domain)
+    ├── created.ts                     (order.created event)
+    └── created.mock.json              ✅ PLURAL folder
+
+// ❌ WRONG - Mixed singular/plural:
+packages/contracts/src/events/
+├── customers/created.ts               ✅ PLURAL
+└── customer/created.mock.json         ❌ SINGULAR - causes inconsistency!
+```
 
-### Examples
+### Contract Examples
 
-| Event Type | Contract | File | Stream |
-|------------|----------|------|--------|
-| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` | `ORDERS` ✅ |
-| `domain.created` | `DomainCreatedContract` | `domain-created.ts` | `DOMAINS` ✅ |
+### Contract Examples
+
+| Event Type | Contract | Folder | Stream |
+|------------|----------|--------|--------|
+| `customer.created` | `CustomerCreatedContract` | `customers/` | `CUSTOMERS` ✅ |
+| `order.created` | `OrderCreatedContract` | `orders/` | `ORDERS` ✅ |
+| `domain.created` | `DomainCreatedContract` | `domains/` | `DOMAINS` ✅ |
 
 ```typescript
 // ✅ CORRECT
-export const DomainCreatedContract = createContract({
-  type: 'domain.created',           // Singular event
-  channel: { stream: 'DOMAINS' },   // Plural stream
-  schema: DomainCreatedSchema,
+export const CustomerCreatedContract = createContract({
+  type: 'customer.created',         // Singular event
+  channel: { stream: 'CUSTOMERS' }, // Plural stream
+  schema: CustomerCreatedSchema,
 })
 
-export const OrdersCreatedContract = createContract({
-  type: 'orders.created',           // Singular event (but namespace plural!)
-  channel: { stream: 'ORDERS' },    // Plural stream
-  schema: OrdersCreatedSchema,
+// Folder: packages/contracts/src/events/customers/created.ts    ✅ PLURAL
+// Mock:   packages/contracts/src/events/customers/created.mock.json ✅ PLURAL
+
+// ❌ WRONG - Singular stream
+export const CustomerCreatedContract = createContract({
+  type: 'customer.created',
+  channel: { stream: 'CUSTOMER' },  // ❌ Must be CUSTOMERS (plural!)
+  schema: CustomerCreatedSchema,
 })
 
-// ❌ WRONG
-export const DomainCreatedContract = createContract({
-  type: 'domain.created',
-  channel: { stream: 'DOMAIN' },    // ❌ Must be DOMAINS (plural!)
+// ❌ WRONG - Mixed folders
+// Folder: packages/contracts/src/events/customers/created.ts    ✅
+// Mock:   packages/contracts/src/events/customer/created.mock.json ❌ Singular!
   schema: DomainCreatedSchema,
 })
 ```
@@ -509,6 +545,14 @@ consumeJetStreams({
 | `post-commands` | Runs after files created (e.g., `pf event add`) |
 | `dependencies` | Extra npm packages (NOT `@crossdelta/*`) |
 
+**When adding dependencies:**
+- ✅ Search npm for the latest stable version
+- ✅ Check package README for current API usage
+- ✅ Avoid deprecated APIs - look for deprecation warnings in docs
+- ✅ Prefer packages with TypeScript definitions (`@types/*` or built-in)
+- ✅ Check GitHub for recent activity and TypeScript support
+- ⚠️ If using an unfamiliar package, mention: "Check official docs for latest API"
+
 ---
 
 ## Service Types
@@ -561,4 +605,6 @@ packages/contracts/src/events/
 - ✅ 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
+- ✅ Use current, non-deprecated APIs - check package documentation
+- ✅ Prefer TypeScript-first packages with good type definitions
+- ✅ Check npm for latest package versions and breaking changes

package/bin/templates/hono-microservice/src/config/env.ts.hbs

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+const envSchema = z.object({
+  {{envKey}}_PORT: z.string().optional(),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Environment validation failed:')
+  console.error(result.error.format())
+  process.exit(1)
+}
+
+export const env = result.data

package/bin/templates/hono-microservice/src/index.ts.hbs

@@ -1,4 +1,4 @@
-// IMPORTANT: telemetry must be imported first to patch modules before they're loaded
+import './config/env'
 import '@crossdelta/telemetry'
 
 import { Hono } from 'hono'

package/bin/templates/workspace/infra/package.json.hbs

@@ -7,7 +7,7 @@
     "pulumi": "pulumi"
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.3",
+    "@crossdelta/cloudevents": "^0.5.4",
     "@crossdelta/infrastructure": "^0.5.3",
     "{{scope}}/contracts": "workspace:*",
     "@pulumi/digitalocean": "^4.55.0",

package/bin/templates/workspace/packages/contracts/package.json.hbs

@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@crossdelta/cloudevents": "^0.5.3",
+    "@crossdelta/cloudevents": "^0.5.4",
     "@crossdelta/infrastructure": "^0.5.3",
     "zod": "^4.0.0"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",

package/bin/templates/workspace/.github/copilot-instructions.md.hbs

@@ -1,72 +0,0 @@
-# Copilot Instructions (Project-Agnostic, TypeScript-Focused)
-
-You are assisting in TypeScript-first monorepos using modern TypeScript tooling such as Bun or Node, Turborepo, Hono, NestJS, Zod, event-driven patterns, and Pulumi/Kubernetes infrastructure.
-
-Always generate **minimal diffs**, never full rewrites.
-
-## General Behavior
-- Produce short, focused, code-first answers.
-- Modify only the necessary parts.
-- Analyze only the opened file unless explicitly asked.
-- Follow existing architecture and naming conventions.
-- Prefer strict typing; avoid `any`.
-- **Reuse existing code**: Before implementing new functionality, search the codebase for existing functions, utilities, or services that can be reused. Avoid duplicating logic.
-
-## Code Style
-- Single quotes, no semicolons, 2-space indent, trailing commas.
-- Alphabetically sorted imports; no unused imports.
-- Arrow functions over `function` declarations.
-- Template literals over string concatenation.
-- Prefer pure and functional programming patterns (map/filter/reduce).
-- Avoid mutable state and imperative loops.
-- No decorative section header blocks (no ASCII art separators like `// ─────────────`).
-- Use blank lines to separate logical sections naturally.
-- Organize code: types → helpers → higher-order functions.
-- Use JSDoc for exported functions and complex logic; keep inline comments minimal.
-- Self-documenting code over comments: clear naming, pure functions, obvious control flow.
-
-## Validation & Types
-- Use Zod for schemas.
-- Export inferred types using `z.infer`.
-- Do NOT include literal event types inside schemas.
-- Do not duplicate validation logic across layers.
-
-## Service & Module Structure
-- Entry points handle wiring (server start, telemetry, routing, consumers).
-- Business logic lives in use-case modules.
-- Event handlers must be thin wrappers around use-cases.
-
-## Event Handling
-- Use shared CloudEvents/messaging libraries, not raw clients.
-- Handlers: Schema → inferred type → thin handler → use-case delegation.
-- Handlers named `*.event.ts`.
-
-## Infrastructure
-- Use fluent port builders when available.
-- Expose a `/health` endpoint.
-- Avoid legacy containerPort usage.
-
-## Testing
-- Test use-cases, not handlers or frameworks.
-- Prefer simple direct tests, no mocks.
-- Validate both error and success paths.
-
-## AI Output Format
-- Provide only necessary files.
-- Use relative paths.
-- Keep comments minimal.
-- Do not generate abstractions not already present.
-
-## Service-Specific Guidelines
-
-When working with specific service types or packages, refer to these detailed guidelines:
-
-### Service Generation & Architecture
-- [CLI Service Generator](../packages/platform-sdk/docs/generators/service.md) - AI code generation rules
-
-### Key Packages
-- [@crossdelta/cloudevents](../packages/cloudevents/README.md) - Event handling with NATS and CloudEvents
-- [@crossdelta/telemetry](../packages/telemetry/README.md) - OpenTelemetry instrumentation
-- [@crossdelta/infrastructure](../packages/infrastructure/README.md) - Pulumi/K8s configuration
-
-**When generating services**: Always check the appropriate guidelines above to ensure correct patterns, especially for event-driven architectures.