@crossdelta/platform-sdk 0.10.1 → 0.11.1

package/bin/docs/generators/README.md

@@ -7,35 +7,44 @@ This directory contains AI instructions for code generators.
 ```
 generators/
 ├── README.md           # This file
-└── service.md          # Service generator instructions
+├── 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
 
-The AI service generator loads instructions in priority order (most specific first):
-
-1. **Generator-specific** (`packages/platform-sdk/docs/generators/service.md`)
-   - Detailed rules for the service generator output format
-   - Event consumer/publisher workflows
-   - File structure requirements
-
-2. **Copilot instructions** (`.github/copilot-instructions.md`)
-   - Project-wide coding standards
-   - Code style rules
-   - Package-specific guidelines
+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"
+      }
+    }
+  }
+}
+```
 
-3. **Project AI guidelines** (`docs/ai-guidelines.md`)
-   - General architectural principles
-   - Validation patterns
-   - Testing guidelines
+**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 generator:
+To add instructions for a new framework:
 
-1. Create `<generator-name>.md` in this directory
-2. Update `INSTRUCTION_FILES` in `ai-service-generator.ts` if needed
-3. Follow the existing format from `service.md`
+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
 

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

@@ -0,0 +1,96 @@
+# 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,15 +1,23 @@
-# Hono Service (Bun Runtime) - AI Generator Guidelines
+# Hono (Bun Runtime)
 
-These guidelines are for generating Hono microservices that run with **Bun runtime**.
+## 🚨 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 Template (src/index.ts)
+## Entry Point (src/index.ts)
 
-**Basic REST API:**
+**REST API:**
 ```ts
 import '@crossdelta/telemetry'
-
 import { Hono } from 'hono'
 
 const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
@@ -17,17 +25,14 @@ const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
 
-// Your routes here
-app.get('/', (c) => c.text('Hello Hono!'))
-
 Bun.serve({ port, fetch: app.fetch })
+console.log(`Service running on http://localhost:${port}`)
 ```
 
-**Event Consumer (NATS) - Multiple Streams:**
+**Event Consumer:**
 ```ts
 import '@crossdelta/telemetry'
-
-import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
 const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
@@ -36,25 +41,22 @@ 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}`)
 
-await ensureJetStreamStreams({
-  streams: [
-    { stream: 'ORDERS', subjects: ['orders.*'] },
-    { stream: 'CUSTOMERS', subjects: ['customers.*'] },
-  ]
+await ensureJetStreams({
+  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }]
 })
 
-consumeJetStreamStreams({
-  streams: ['ORDERS', 'CUSTOMERS'],
+consumeJetStreams({
+  streams: ['ORDERS'],
   consumer: 'my-service',
   discover: './src/events/**/*.event.ts',
 })
 ```
 
-**Event Publisher (REST + CloudEvents):**
+**Event Publisher:**
 ```ts
 import '@crossdelta/telemetry'
-
 import { publish } from '@crossdelta/cloudevents'
 import { Hono } from 'hono'
 
@@ -65,37 +67,21 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 
 app.post('/orders', async (c) => {
   const data = await c.req.json()
-  await publish('orders.created', data, { source: 'my-service' })
+  await publish('orders.created', data)
   return c.json({ success: true })
 })
 
 Bun.serve({ port, fetch: app.fetch })
+console.log(`Service running on http://localhost:${port}`)
 ```
 
 ---
 
-## Key Points
-
-- ✅ Use `Bun.serve({ port, fetch: app.fetch })` for server
-- ✅ Import telemetry FIRST (before any other imports)
-- ✅ Use the port env var name provided in the prompt (e.g., `PUSH_NOTIFICATIONS_PORT`)
-- ✅ Always include `/health` endpoint
-- ✅ Keep routes simple and delegate logic to use-cases
-- ✅ Use `ensureJetStreamStreams` + `consumeJetStreamStreams` for multiple event types
+## Rules
 
-**DO NOT:**
-- ❌ `export default Bun.serve(...)` - Bun.serve returns Server, not for export
-- ❌ `export default app` - Not needed for Bun runtime
-- ❌ Multiple `ensureJetStreamStream` calls - use batch version instead
-
----
-
-## Dev Command
-
-```json
-{
-  "scripts": {
-    "dev": "bun run --hot src/index.ts"
-  }
-}
-```
+- ✅ `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,15 +1,23 @@
-# Hono Service (Node.js Runtime) - AI Generator Guidelines
+# Hono (Node.js Runtime)
 
-These guidelines are for generating Hono microservices that run with **Node.js runtime** (pnpm, npm, yarn).
+## 🚨 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 Template (src/index.ts)
+## Entry Point (src/index.ts)
 
-**Basic REST API:**
+**REST API:**
 ```ts
 import '@crossdelta/telemetry'
-
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
@@ -18,22 +26,15 @@ const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
 
-// Your routes here
-app.get('/', (c) => c.text('Hello Hono!'))
-
-serve({
-  fetch: app.fetch,
-  port
-}, (info) => {
-  console.log(`Server is running on http://localhost:${info.port}`)
+serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`Server running on http://localhost:${info.port}`)
 })
 ```
 
-**Event Consumer (NATS) - Multiple Streams:**
+**Event Consumer:**
 ```ts
 import '@crossdelta/telemetry'
-
-import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { consumeJetStreams, ensureJetStreams } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 
@@ -42,31 +43,24 @@ const app = new Hono()
 
 app.get('/health', (c) => c.json({ status: 'ok' }))
 
-serve({
-  fetch: app.fetch,
-  port
-}, (info) => {
-  console.log(`Server is running on http://localhost:${info.port}`)
+serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`Server running on http://localhost:${info.port}`)
 })
 
-await ensureJetStreamStreams({
-  streams: [
-    { stream: 'ORDERS', subjects: ['orders.*'] },
-    { stream: 'CUSTOMERS', subjects: ['customers.*'] },
-  ]
+await ensureJetStreams({
+  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }]
 })
 
-consumeJetStreamStreams({
-  streams: ['ORDERS', 'CUSTOMERS'],
+consumeJetStreams({
+  streams: ['ORDERS'],
   consumer: 'my-service',
   discover: './src/events/**/*.event.ts',
 })
 ```
 
-**Event Publisher (REST + CloudEvents):**
+**Event Publisher:**
 ```ts
 import '@crossdelta/telemetry'
-
 import { publish } from '@crossdelta/cloudevents'
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
@@ -78,39 +72,21 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 
 app.post('/orders', async (c) => {
   const data = await c.req.json()
-  await publish('orders.created', data, { source: 'my-service' })
+  await publish('orders.created', data)
   return c.json({ success: true })
 })
 
-serve({
-  fetch: app.fetch,
-  port
-}, (info) => {
-  console.log(`Server is running on http://localhost:${info.port}`)
+serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`Server running on http://localhost:${info.port}`)
 })
 ```
 
 ---
 
-## Key Points
-
-- ✅ Use `serve()` from `@hono/node-server` (NOT `Bun.serve`)
-- ✅ Import `serve` from `@hono/node-server`
-- ✅ Import telemetry FIRST (before any other imports)
-- ✅ Use the port env var name provided in the prompt (e.g., `API_GATEWAY_PORT`)
-- ✅ Always include `/health` endpoint
-- ✅ Include callback with console.log for server startup
-- ✅ Keep routes simple and delegate logic to use-cases
-- ✅ Use `ensureJetStreamStreams` + `consumeJetStreamStreams` for multiple event types
-
----
-
-## Dev Command
+## Rules
 
-```json
-{
-  "scripts": {
-    "dev": "tsx watch src/index.ts"
-  }
-}
-```
+- ✅ `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