@crossdelta/platform-sdk 0.8.3 → 0.8.4

package/bin/docs/generators/README.md

@@ -0,0 +1,47 @@
+# Generator Documentation
+
+This directory contains AI instructions for code generators.
+
+## Structure
+
+```
+generators/
+├── README.md           # This file
+└── service.md          # Service generator instructions
+```
+
+## 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
+
+3. **Project AI guidelines** (`docs/ai-guidelines.md`)
+   - General architectural principles
+   - Validation patterns
+   - Testing guidelines
+
+## Adding New Generators
+
+To add instructions for a new generator:
+
+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`
+
+## 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/service.md

@@ -0,0 +1,258 @@
+# Service Generator Instructions
+
+These rules define how AI-generated scaffolded services must be structured.
+
+---
+
+## 🚨 CRITICAL: Event Consumer Workflow
+
+**FOR EVENT CONSUMER SERVICES (services that "consume", "listen to", "react to" events):**
+
+### Naming Convention (CRITICAL!)
+
+**Event Type → Contract Name → File Name:**
+
+| Event Type | Contract Name | File Name |
+|------------|---------------|-----------|
+| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` |
+| `users.registered` | `UsersRegisteredContract` | `users-registered.ts` |
+| `payments.completed` | `PaymentsCompletedContract` | `payments-completed.ts` |
+
+**Rule:** Always use **plural namespace** (`orders.`, `users.`, `payments.`) to match JetStream stream subjects (`orders.>`, `users.>`, etc.)
+
+### 3-Step Workflow
+
+**STEP 1: CREATE Contract** (`packages/contracts/src/events/<event-name>.ts`):
+```ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrdersCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+})
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',  // plural namespace!
+  schema: OrdersCreatedSchema,
+})
+
+export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+```
+
+**STEP 2: Create Event Handler** (`src/events/orders-created.event.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) => {
+  await processOrder(data)
+})
+```
+
+**STEP 3: Setup Consumer** (`src/index.ts`):
+```ts
+import '@crossdelta/telemetry'
+
+import { consumeJetStreamEvents, ensureJetStreamStream } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 4003
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+Bun.serve({ port, fetch: app.fetch })
+
+await ensureJetStreamStream({
+  stream: 'ORDERS',
+  subjects: ['orders.>'],
+})
+
+consumeJetStreamEvents({
+  stream: 'ORDERS',
+  consumer: 'my-service',
+  discover: './src/events/**/*.event.ts',
+})
+```
+
+---
+
+## ⚠️ Code Quality Guidelines
+
+- ✅ **Verify package names** on npmjs.com before using
+- ✅ Use exact package names: `@crossdelta/cloudevents`, `@crossdelta/telemetry`
+- ❌ **DO NOT hallucinate** APIs or package names
+
+---
+
+## Commands Block (REQUIRED - MUST BE FIRST)
+
+```commands
+pf new hono-micro services/my-service -y
+```
+
+- Services MUST be in `services/` directory
+- User says "orders" → Generate: `services/orders`
+
+---
+
+## Post-Generation Commands
+
+For Event Consumer services:
+
+```post-commands
+pf event add <event.type> --service services/my-service
+```
+
+**Note:** `pf event add` creates contract, mock, handler, and adds the export to `packages/contracts/src/index.ts`.
+
+---
+
+## Dependencies Block
+
+Only include packages not in the scaffold:
+
+```dependencies
+zod
+@pusher/push-notifications-server
+```
+
+**Note:** `{{scope}}/contracts` is already in the template's package.json.
+
+---
+
+## Required Files
+
+**Event Consumer:**
+```
+services/my-service/
+├── src/
+│   ├── index.ts                    # NATS consumer setup
+│   ├── events/
+│   │   └── orders-created.event.ts # Event handler
+│   └── use-cases/
+│       ├── process-order.use-case.ts
+│       └── process-order.test.ts
+└── README.md
+
+packages/contracts/src/events/
+└── orders-created.ts               # Contract (export added by CLI)
+```
+
+**Event Publisher:**
+```
+services/my-service/
+├── src/
+│   ├── index.ts                    # REST API + publish()
+│   └── use-cases/
+│       ├── create-order.use-case.ts
+│       └── create-order.test.ts
+└── README.md
+```
+
+**IMPORTANT:** Do NOT create `src/types/` directories. All types come from contracts:
+- `OrdersCreatedData` → import from `@scope/contracts`
+- Custom request/response types → define inline or in use-case files
+
+---
+
+## Service Types
+
+### 📤 Event Publisher (REST API)
+
+**Keywords:** "publishes", "creates", "manages", "REST API"
+
+```ts
+import '@crossdelta/telemetry'
+
+import { publish } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.post('/orders', async (c) => {
+  const data = await c.req.json()
+  await publish('orders.created', data, { source: 'my-service' })
+  return c.json({ success: true })
+})
+
+Bun.serve({ port: 4001, fetch: app.fetch })
+```
+
+### 📥 Event Consumer (NATS)
+
+**Keywords:** "consumes", "listens to", "reacts to", "handles events"
+
+See 3-Step Workflow above.
+
+### 🔄 Hybrid (Both)
+
+Combines REST endpoints + NATS consumer.
+
+---
+
+## Use-Case Rules
+
+- Live in `src/use-cases/*.use-case.ts`
+- Pure functions, no framework imports
+- Import types from `@scope/contracts`
+- Inject dependencies as parameters (Map, services, etc.)
+- NO manual validation (adapters handle that)
+- **Event handlers:** Always log the event type and a key identifier (e.g., `console.log('📦 Processing order:', data.orderId)`) at the start of the use-case for debugging visibility
+
+```ts
+import type { OrdersCreatedData } from '{{scope}}/contracts'
+
+export const processOrder = async (
+  data: OrdersCreatedData,
+  orderStore: Map<string, any>
+) => {
+  console.log('📦 Processing order:', data.orderId)
+
+  orderStore.set(data.orderId, { ...data, processedAt: new Date() })
+  return { success: true }
+}
+```
+
+---
+
+## Testing Rules
+
+- Test ONLY use-cases
+- Use `import { describe, expect, it } from 'bun:test'`
+- NO mocking (Bun doesn't support it)
+- Focus on error handling and validation
+
+```ts
+import { describe, expect, it } from 'bun:test'
+import { processOrder } from './process-order.use-case'
+
+describe('Process Order', () => {
+  it('should store order', async () => {
+    const store = new Map()
+    const result = await processOrder({ orderId: '123', customerId: 'c1', total: 100 }, store)
+    expect(store.has('123')).toBe(true)
+  })
+})
+```
+
+---
+
+## Absolute Rules
+
+**DO NOT:**
+- Generate full rewrites
+- Use raw NATS clients
+- Put logic in handlers or index.ts
+- Use `src/handlers/` (use `src/events/`)
+- Insert semicolons
+- Edit `packages/contracts/src/index.ts` directly (CLI handles exports)
+
+**DO:**
+- Follow naming convention (plural event types)
+- Create contracts in `packages/contracts/src/events/`
+- Export schema separately from contract
+- Keep code minimal and clean

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

@@ -10,6 +10,7 @@ Always generate **minimal diffs**, never full rewrites.
 - 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.
@@ -60,8 +61,6 @@ Always generate **minimal diffs**, never full rewrites.
 When working with specific service types or packages, refer to these detailed guidelines:
 
 ### Service Generation & Architecture
-- [Service Architecture Guidelines](../docs/generators/services/architecture-guidelines.md) - General patterns for all services
-- [Hono Microservice Guidelines](../docs/generators/services/hono-micro-guidelines.md) - Event-driven Hono patterns
 - [CLI Service Generator](../packages/platform-sdk/docs/generators/service.md) - AI code generation rules
 
 ### Key Packages

package/install.sh

@@ -11,15 +11,15 @@ NC='\033[0m'
 
 printf "${CYAN}"
 cat << "EOF"
-             ______ 
+             ______
             / ____/
-    ____   / /_    
-   / __ \ / __/    
-  / /_/ // /       
- / .___//_/        
-/_/                
-  
-  @crossdelta/platform-sdk installer
+    ____   / /_
+   / __ \ / __/
+  / /_/ // /
+ / .___//_/
+/_/
+
+@crossdelta/platform-sdk installer
 EOF
 printf "${NC}\n"
 
@@ -44,28 +44,28 @@ detect_or_install_package_manager() {
     echo "npm"
     return 0
   fi
-  
+
   # No package manager found - ask user for permission
   printf "${YELLOW}No package manager found (bun, pnpm, yarn, npm).${NC}\n"
   printf "${YELLOW}To use @crossdelta/platform-sdk, we recommend installing Bun (fast JavaScript runtime).${NC}\n"
   printf "\n"
   read -p "Do you want to install Bun now? (y/n) " -n 1 -r
   printf "\n"
-  
+
   if [[ ! $REPLY =~ ^[Yy]$ ]]; then
     printf "${RED}Installation cancelled. Please install Bun or another package manager manually.${NC}\n"
     printf "${BLUE}Visit: https://bun.sh${NC}\n"
     exit 1
   fi
-  
+
   # Install Bun
   printf "${BLUE}Installing Bun...${NC}\n"
   curl -fsSL https://bun.sh/install | bash
-  
+
   # Load Bun into current shell
   export BUN_INSTALL="$HOME/.bun"
   export PATH="$BUN_INSTALL/bin:$PATH"
-  
+
   printf "${GREEN}✓${NC} Bun installed successfully\n"
   echo "bun"
 }
@@ -117,7 +117,7 @@ if [ $# -eq 0 ]; then
 else
   # Arguments provided: Run pf command directly
   PF_ARGS=()
-  
+
   while [[ $# -gt 0 ]]; do
     case $1 in
       -h|--help)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",
@@ -29,7 +29,7 @@
   "files": [
     "bin/**/*.js",
     "bin/**/templates/**",
-    "bin/**/instructions/**",
+    "bin/docs/generators/**",
     "bin/**/*.json",
     "!bin/**/*.map",
     "dist/",