@crossdelta/platform-sdk 0.9.4 → 0.10.0

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

@@ -0,0 +1,101 @@
+# Hono Service (Bun Runtime) - AI Generator Guidelines
+
+These guidelines are for generating Hono microservices that run with **Bun runtime**.
+
+---
+
+## Entry Point Template (src/index.ts)
+
+**Basic REST API:**
+```ts
+import '@crossdelta/telemetry'
+
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+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 })
+```
+
+**Event Consumer (NATS) - Multiple Streams:**
+```ts
+import '@crossdelta/telemetry'
+
+import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+Bun.serve({ port, fetch: app.fetch })
+
+await ensureJetStreamStreams({
+  streams: [
+    { stream: 'ORDERS', subjects: ['orders.*'] },
+    { stream: 'CUSTOMERS', subjects: ['customers.*'] },
+  ]
+})
+
+consumeJetStreamStreams({
+  streams: ['ORDERS', 'CUSTOMERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.event.ts',
+})
+```
+
+**Event Publisher (REST + CloudEvents):**
+```ts
+import '@crossdelta/telemetry'
+
+import { publish } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || 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, { source: 'my-service' })
+  return c.json({ success: true })
+})
+
+Bun.serve({ port, fetch: app.fetch })
+```
+
+---
+
+## 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
+
+**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"
+  }
+}
+```

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

@@ -0,0 +1,116 @@
+# Hono Service (Node.js Runtime) - AI Generator Guidelines
+
+These guidelines are for generating Hono microservices that run with **Node.js runtime** (pnpm, npm, yarn).
+
+---
+
+## Entry Point Template (src/index.ts)
+
+**Basic REST API:**
+```ts
+import '@crossdelta/telemetry'
+
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 8080
+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}`)
+})
+```
+
+**Event Consumer (NATS) - Multiple Streams:**
+```ts
+import '@crossdelta/telemetry'
+
+import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || 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 is running on http://localhost:${info.port}`)
+})
+
+await ensureJetStreamStreams({
+  streams: [
+    { stream: 'ORDERS', subjects: ['orders.*'] },
+    { stream: 'CUSTOMERS', subjects: ['customers.*'] },
+  ]
+})
+
+consumeJetStreamStreams({
+  streams: ['ORDERS', 'CUSTOMERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.event.ts',
+})
+```
+
+**Event Publisher (REST + CloudEvents):**
+```ts
+import '@crossdelta/telemetry'
+
+import { publish } from '@crossdelta/cloudevents'
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || 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, { source: 'my-service' })
+  return c.json({ success: true })
+})
+
+serve({
+  fetch: app.fetch,
+  port
+}, (info) => {
+  console.log(`Server is 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
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts"
+  }
+}
+```

package/bin/docs/generators/nest.md

@@ -0,0 +1,265 @@
+# NestJS Service - AI Generator Guidelines
+
+These guidelines are for generating NestJS microservices.
+
+**For handler location and structure rules (shared for all frameworks), see:** [Service Generator - Handler Location & Structure](./service.md#handler-location--structure-critical)
+
+---
+
+## 🚨 CRITICAL: Commands Block (REQUIRED - MUST BE FIRST IN YOUR RESPONSE)
+
+Your response **MUST** start with a commands block that scaffolds the NestJS service structure:
+
+```commands
+pf new nest-micro <service-path> -y
+```
+
+**Example:** If user asks for "orders service", generate:
+```commands
+pf new nest-micro services/orders -y
+```
+
+This command creates: `package.json`, `tsconfig.json`, NestJS structure, and basic files.
+**Without this command, the service cannot be built or run!**
+
+- Services MUST be in `services/` directory
+- User says "orders" → Generate path: `services/orders`
+- Always include `-y` flag to skip prompts
+
+---
+
+## NestJS Event Consumer Architecture
+
+For NestJS event consumers, we use NestJS's application context to bridge
+`@crossdelta/cloudevents` handlers with NestJS's dependency injection system.
+
+### Entry Point (src/main.ts)
+
+```ts
+import '@crossdelta/telemetry'
+
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+import { EventsService } from './events/events.service'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  const port = Number(process.env.MY_SERVICE_PORT) || 8080
+
+  // Get EventsService from DI container and start consuming
+  const eventsService = app.get(EventsService)
+  await eventsService.startConsumers()
+
+  await app.listen(port)
+  console.log(`Service running on http://localhost:${port}`)
+}
+
+bootstrap()
+```
+
+---
+
+## Events Module (src/events/events.module.ts)
+
+```ts
+import { Module } from '@nestjs/common'
+import { EventsService } from './events.service'
+
+@Module({
+  providers: [EventsService],
+  exports: [EventsService],
+})
+export class EventsModule {}
+```
+
+---
+
+## Events Service (src/events/events.service.ts)
+
+```ts
+import { Injectable, Logger } from '@nestjs/common'
+import { consumeJetStreamStreams, ensureJetStreamStreams } from '@crossdelta/cloudevents'
+
+@Injectable()
+export class EventsService {
+  private readonly logger = new Logger(EventsService.name)
+
+  async startConsumers(): Promise<void> {
+    await ensureJetStreamStreams({
+      streams: [
+        { stream: 'ORDERS', subjects: ['orders.*'] },
+      ],
+    })
+
+    consumeJetStreamStreams({
+      streams: ['ORDERS'],
+      consumer: 'my-service',
+      discover: './src/events/**/*.event.ts',
+    })
+  }
+}
+```
+
+---
+
+## Accessing NestJS Services in Handlers
+
+For handlers that need NestJS DI (database, external services), use the app context:
+
+### App Context Singleton (src/app.context.ts)
+
+```ts
+import type { INestApplication, Type } from '@nestjs/common'
+
+let app: INestApplication
+
+export const setAppContext = (nestApp: INestApplication): void => {
+  app = nestApp
+}
+
+export const getAppContext = (): INestApplication => {
+  if (!app) throw new Error('App context not initialized')
+  return app
+}
+
+export const getService = <T>(serviceClass: Type<T>): T => {
+  return getAppContext().get(serviceClass)
+}
+```
+
+### Updated main.ts with App Context
+
+```ts
+import '@crossdelta/telemetry'
+
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+import { setAppContext } from './app.context'
+import { EventsService } from './events/events.service'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  const port = Number(process.env.MY_SERVICE_PORT) || 8080
+
+  // Make app context available to event handlers
+  setAppContext(app)
+
+  // Start event consumers
+  const eventsService = app.get(EventsService)
+  await eventsService.startConsumers()
+
+  await app.listen(port)
+  console.log(`Service running on http://localhost:${port}`)
+}
+
+bootstrap()
+```
+
+### Handler with DI Access (src/events/orders-created.event.ts)
+
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { getService } from '../app.context'
+import { OrdersService } from '../orders/orders.service'
+
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+  // Get service from NestJS DI container
+  const ordersService = getService(OrdersService)
+  await ordersService.processOrder(data)
+})
+```
+
+### Orders Service (src/orders/orders.service.ts)
+
+```ts
+import { Injectable, Logger } from '@nestjs/common'
+import type { OrdersCreatedData } from '{{scope}}/contracts'
+
+@Injectable()
+export class OrdersService {
+  private readonly logger = new Logger(OrdersService.name)
+
+  async processOrder(data: OrdersCreatedData): Promise<void> {
+    this.logger.log(`Processing order: ${data.orderId}`)
+    // Business logic with full DI access
+  }
+}
+```
+
+---
+
+## App Module Structure
+
+```ts
+// src/app.module.ts
+import { Module } from '@nestjs/common'
+import { AppController } from './app.controller'
+import { EventsModule } from './events/events.module'
+import { OrdersModule } from './orders/orders.module'
+
+@Module({
+  imports: [EventsModule, OrdersModule],
+  controllers: [AppController],
+})
+export class AppModule {}
+```
+
+```ts
+// src/app.controller.ts
+import { Controller, Get } from '@nestjs/common'
+
+@Controller()
+export class AppController {
+  @Get('health')
+  health() {
+    return { status: 'ok' }
+  }
+}
+```
+
+---
+
+## Testing
+
+### Unit Test for Service
+
+```ts
+// src/orders/orders.service.spec.ts
+import { Test, TestingModule } from '@nestjs/testing'
+import { OrdersService } from './orders.service'
+
+describe('OrdersService', () => {
+  let service: OrdersService
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [OrdersService],
+    }).compile()
+
+    service = module.get<OrdersService>(OrdersService)
+  })
+
+  it('should process order', async () => {
+    const mockData = {
+      orderId: 'ord_123',
+      customerId: 'cust_456',
+      total: 99.99,
+    }
+
+    await expect(service.processOrder(mockData)).resolves.not.toThrow()
+  })
+})
+```
+
+---
+
+## Dev Command
+
+```json
+{
+  "scripts": {
+    "start:dev": "nest start --watch"
+  }
+}
+```