@crossdelta/platform-sdk 0.8.3 → 0.8.21

package/bin/services/ai/instructions/ai-instructions.md

@@ -0,0 +1,265 @@
+# AI Generation Rules for CLI Code Output
+
+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
+
+---
+
+# 1. 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`
+
+---
+
+# 2. 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`.
+
+---
+
+# 3. 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.
+
+---
+
+# 4. 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
+
+---
+
+# 5. Code Style
+
+- Biome-compatible, strict TS, arrow functions only
+- No semicolons, minimal comments, alphabetized imports
+
+---
+
+# 6. 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 4-Step Workflow above.
+
+## 🔄 Hybrid (Both)
+
+Combines REST endpoints + NATS consumer.
+
+---
+
+# 7. 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 }
+}
+```
+
+---
+
+# 8. 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)
+  })
+})
+```
+
+---
+
+# 9. 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

@@ -62,7 +62,6 @@ When working with specific service types or packages, refer to these detailed gu
 ### 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
 - [@crossdelta/cloudevents](../packages/cloudevents/README.md) - Event handling with NATS and CloudEvents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.8.3",
+  "version": "0.8.21",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",
@@ -51,7 +51,7 @@
   "scripts": {
     "start:dev": "node esbuild.config.mjs --watch",
     "build:cli": "node esbuild.config.mjs",
-    "build:cli:copy": "cp cli/integration.collection.json bin/integration.collection.json && rm -rf bin/templates && mkdir -p bin/templates && cp -r cli/src/commands/create/workspace/templates bin/templates/workspace && cp -r cli/src/commands/create/hono-microservice/templates bin/templates/hono-microservice && cp -r cli/src/commands/create/nest-microservice/templates bin/templates/nest-microservice && mkdir -p bin/docs/generators && cp -r docs/generators/* bin/docs/generators/",
+    "build:cli:copy": "cp cli/integration.collection.json bin/integration.collection.json && rm -rf bin/templates && mkdir -p bin/templates && cp -r cli/src/commands/create/workspace/templates bin/templates/workspace && cp -r cli/src/commands/create/hono-microservice/templates bin/templates/hono-microservice && cp -r cli/src/commands/create/nest-microservice/templates bin/templates/nest-microservice && mkdir -p bin/services/ai/instructions && cp cli/src/services/ai/instructions/ai-instructions.md bin/services/ai/instructions/",
     "build:schematics:transpile": "tsc --project tsconfig.schematics.json",
     "build:schematics:copy": "cp -R schematics/* dist/schematics && find dist/schematics -name '*.ts' -delete",
     "build:schematics": "npm run build:schematics:transpile && npm run build:schematics:copy",