@crossdelta/platform-sdk 0.4.0 → 0.4.1

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

@@ -0,0 +1,234 @@
+# AI Generation Rules for CLI Code Output
+
+These rules define how AI-generated scaffolded services must be structured when produced by CLI tools.
+
+---
+
+# 1. Commands Block (REQUIRED - MUST BE FIRST)
+
+**EVERY GENERATION MUST START WITH A COMMANDS BLOCK:**
+
+```commands
+pf new hono-micro services/my-service -y
+```
+
+Rules:
+- **ALWAYS** include this commands block as the FIRST thing in your output
+- Use exactly the path provided by the user
+- Do not alter naming or prepend paths
+- The `-y` flag is REQUIRED to skip prompts
+
+---
+
+# 2. Dependencies Block
+
+```dependencies
+zod
+@pusher/push-notifications-server
+```
+
+Rules:
+- One package per line.
+- No versions.
+- Only packages not included in the scaffold.
+
+---
+
+# 3. Required Source Files
+
+Generated services must include:
+
+- `src/index.ts`
+- `src/handlers/*.event.ts`
+- `src/use-cases/*.use-case.ts`
+- `src/use-cases/*.test.ts`
+- `README.md`
+
+Rules:
+- Paths must be relative to the service root.
+- Do NOT generate controller or module folders unless requested.
+
+---
+
+# 4. Code Style
+
+- Biome-compatible formatting.
+- Strict TS.
+- Arrow functions only.
+- No semicolons.
+- Minimal comments.
+- Alphabetized imports.
+
+---
+
+# 5. Service Structure
+
+### index.ts
+**IMPORTANT:** Telemetry MUST be the first import!
+
+```ts
+import '@crossdelta/telemetry'
+
+import { consumeJetStreamEvents } from '@crossdelta/cloudevents/transports/nats'
+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' }))
+
+// Start NATS consumer - handlers are auto-discovered
+consumeJetStreamEvents({
+  stream: 'ORDERS',
+  subjects: ['orders.>'],
+  consumer: 'my-service',
+  discover: './src/handlers/**/*.event.ts',
+})
+
+Bun.serve({ port, fetch: app.fetch })
+```
+
+Contains only:
+- Telemetry import (MUST be first)
+- Server setup (Hono)
+- Health endpoint
+- Event consumer registration (if consuming events)
+- Port configuration from env vars
+
+---
+
+# 6. Use-Case Rules
+- All domain logic lives in `use-cases`.
+- Pure functions preferred.
+- No framework imports.
+- Use inferred schema types.
+
+---
+
+# 7. Event Handler Rules
+
+Handlers MUST:
+- Live under `src/handlers/*.event.ts`
+- Use Zod for validation (NO `type` field in schema!)
+- Export inferred types for use in use-cases
+- Delegate ALL logic to use-cases
+- Contain NO business logic
+
+**CRITICAL:** Schema validates ONLY the event data payload (without `type` field). Event type is declared in the options object.
+
+Example:
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+import { processOrder } from '../use-cases/process-order.use-case'
+
+const OrderCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+})
+
+// Export type for use in use-cases
+export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+
+export default handleEvent(
+  {
+    schema: OrderCreatedSchema,
+    type: 'orders.created',  // Event type here, NOT in schema
+  },
+  async (data) => {
+    await processOrder(data)
+  },
+)
+```
+
+**Naming conventions:**
+- Schema constants: PascalCase with `Schema` suffix (e.g., `OrderCreatedSchema`)
+- Exported types: PascalCase with `Event` suffix (e.g., `OrderCreatedEvent`)
+
+Forbidden in handlers:
+- `type: z.literal('...')` in schema (redundant and causes errors)
+- DB access
+- External API calls
+- Multi-step logic
+- Env var parsing
+
+---
+
+# 8. Testing Rules
+
+**CRITICAL:** 
+- Test ONLY use-cases (NOT event handlers)
+- Use Bun's native test runner: `import { describe, expect, it, beforeEach, afterEach } from 'bun:test'`
+- **NO mocking available** - Bun does NOT have `vi`, `mock`, `jest.fn()`, or module mocking
+- Focus on validation (input params, env vars) and error handling
+- Keep tests simple - avoid complex scenarios
+
+**What to test:**
+- ✅ Input validation (missing/empty parameters)
+- ✅ Environment variable validation
+- ✅ Error messages and error types
+- ❌ External API integrations (Pusher, AWS, etc.)
+- ❌ Complex mocking scenarios
+
+Example:
+```ts
+import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
+import { sendNotification } from './send-notification.use-case'
+
+describe('Send Notification Use Case', () => {
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    process.env = { ...originalEnv }
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+  })
+
+  it('should throw error if orderId is missing', async () => {
+    await expect(
+      sendNotification({ orderId: '', customerId: 'cust-1' })
+    ).rejects.toThrow('Missing orderId')
+  })
+
+  it('should throw error if credentials not set', async () => {
+    delete process.env.PUSHER_BEAMS_INSTANCE_ID
+    
+    await expect(
+      sendNotification({ orderId: '123', customerId: 'cust-1' })
+    ).rejects.toThrow('Missing Pusher Beams credentials')
+  })
+})
+```
+
+---
+
+# 9. README Requirements
+
+MUST include:
+- Description
+- Environment variable table
+- Published/consumed events
+- API endpoints
+- Dev commands
+
+---
+
+# 10. Absolute Rules
+
+DO NOT:
+- Generate full rewrites
+- Add new architecture concepts
+- Use raw NATS clients
+- Put logic in handlers or index.ts
+- Insert semicolons
+- Add unused folders/files
+
+DO:
+- Produce minimal, clean code
+- Follow structure and conventions strictly
+- Keep output compact and correct
+
+---

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

@@ -195,30 +195,180 @@ export const ordersCollectionDefinition = defineCollection({
 
 ## Infrastructure (Pulumi + Kubernetes)
 
-Service configs in `infra/services/<name>.ts`:
+### Modern Port Configuration (Fluent API)
+
+**Use the fluent `ports()` builder** for defining service ports:
 
 ```ts
+import { ports } from '@crossdelta/infrastructure'
+import type { K8sServiceConfig } from '@crossdelta/infrastructure'
+
+// Simple internal HTTP service
 const config: K8sServiceConfig = {
   name: 'orders',
-  containerPort: 4001,
+  ports: ports().http(4001).build(),
   replicas: 1,
-  healthCheck: { port: 4001 },
-  resources: { requests: { cpu: '50m', memory: '64Mi' }, limits: { cpu: '150m', memory: '128Mi' } },
+  healthCheck: { httpPath: '/health' },  // HTTP health check endpoint
+  resources: { 
+    requests: { cpu: '50m', memory: '64Mi' }, 
+    limits: { cpu: '150m', memory: '128Mi' } 
+  },
   env: { PUBLIC_SUPABASE_URL: supabaseUrl },
   secrets: { SUPABASE_SERVICE_ROLE_KEY: supabaseServiceRoleKey },
 }
+
+// Public HTTP service
+const publicConfig: K8sServiceConfig = {
+  name: 'api-gateway',
+  ports: ports().http(4000).public().build(),
+  ingress: { path: '/api', host: 'api.example.com' },
+}
+
+// Service with multiple ports
+const natsConfig: K8sServiceConfig = {
+  name: 'nats',
+  ports: ports()
+    .primary(4222, 'client')
+    .addHttp(8222, 'monitoring').public()
+    .add(6222, 'routing')
+    .build(),
+}
 ```
 
+**Port Builder Methods:**
+- `.http(port)` - HTTP primary port
+- `.https(port)` - HTTPS primary port
+- `.grpc(port)` - gRPC primary port
+- `.primary(port, name?)` - Custom primary port
+- `.add(port, name?, protocol?)` - Add additional port
+- `.addHttp(port, name?)` - Add HTTP additional port
+- `.addGrpc(port, name?)` - Add gRPC additional port
+- `.public()` - Mark last port as public (exposed via ingress)
+- `.protocol(type)` - Set protocol for last port
+- `.build()` - Build final config
+
+**Legacy `containerPort` is deprecated** - use the fluent API instead.
+
+### Health Checks
+
+Services should expose health check endpoints:
+
+```ts
+// HTTP health check (recommended)
+healthCheck: {
+  httpPath: '/health',           // GET endpoint
+  initialDelaySeconds: 10,       // Wait before first check
+  periodSeconds: 10,             // Check interval
+}
+
+// For services without HTTP endpoints, Kubernetes will use TCP checks automatically
+// based on the primary port
+```
+
+Health check endpoint implementation:
+
+```ts
+app.get('/health', (c) => c.json({ status: 'ok' }))
+```
+
+### Smart Service Discovery
+
+**Use `discoverServiceConfigs()` for automatic service discovery:**
+
+```ts
+import { discoverServiceConfigs, discoverServiceConfigsWithOptions } from '@crossdelta/infrastructure'
+
+// Simple discovery (backward compatible)
+const configs = discoverServiceConfigs('services')
+
+// Advanced discovery with filtering
+const result = discoverServiceConfigsWithOptions({
+  servicesDir: 'services',
+  filter: /^api-/,              // Pattern matching
+  exclude: ['test-service'],    // Exclude services
+  env: {                        // Inject env vars
+    NODE_ENV: 'production',
+    NATS_URL: natsUrl,
+  },
+  validate: true,               // Port conflict checks
+})
+```
+
+**Discovery Options:**
+- `filter` - Regex or string pattern to match service names
+- `include` - Array of service names to include
+- `exclude` - Array of service names to exclude
+- `tags` - Filter by service tags
+- `env` - Inject environment variables into all services
+- `validate` - Enable validation (port conflicts, missing fields)
+- `sort` - Sort services by name (default: true)
+- `registry` - Custom registry for auto-generated images
+
 Follow existing configs in `infra/services/`. Don't invent new providers or patterns.
 
 ## Code Style & Conventions
 
-- **Biome:** Single quotes, no semicolons, 2-space indent, 120 char width
+### Biome Configuration
+
+**CRITICAL:** All code MUST follow the Biome rules configured in the root `biome.json`:
+
+- **Formatting:** Single quotes, no semicolons, 2-space indent, 120 char width, trailing commas
+- **Import Organization:** Imports and exports MUST be sorted alphabetically (use `organizeImports: "on"`)
+- **Unused Imports:** Remove all unused imports (lint error)
+- **Code Quality:** Follow all Biome linter rules (security, style, complexity)
+
+**Always run before committing:**
+```bash
+bun lint    # Check for issues
+bun format  # Auto-fix formatting and organize imports
+```
+
+**In your editor:** Enable Biome's "Organize Imports on Save" for automatic sorting.
+
+### General Conventions
+
+- **Functions:** Prefer **arrow functions** and **functional programming patterns** (map, filter, reduce) over imperative loops
+- **Immutability:** Use `const` over `let`, avoid mutations, prefer spread operators and array methods
+- **Composition:** Small, composable functions over large classes
 - **Ports:** Always `process.env.PORT || process.env.SERVICE_PORT || default`
 - **Health:** All services expose `GET /health → { status: 'ok' }`
 - **Commits:** Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`)
 - **Tests:** Use `bun:test` — see `packages/cloudevents/test/*.test.ts` for patterns
 
+### Functional Programming Examples
+
+**Prefer:**
+```ts
+// Arrow functions
+const add = (a: number, b: number) => a + b
+
+// Map/filter/reduce over loops
+const activeUsers = users.filter(user => user.active)
+const userNames = users.map(user => user.name)
+const totalAge = users.reduce((sum, user) => sum + user.age, 0)
+
+// Composition
+const processData = (data: Data[]) =>
+  data
+    .filter(isValid)
+    .map(transform)
+    .reduce(aggregate, initialValue)
+```
+
+**Avoid:**
+```ts
+// Function declarations (unless needed for hoisting)
+function add(a: number, b: number) { return a + b }
+
+// Imperative loops
+const activeUsers = []
+for (let i = 0; i < users.length; i++) {
+  if (users[i].active) {
+    activeUsers.push(users[i])
+  }
+}
+```
+
 ## Key Files Reference
 
 | Pattern | Example |

package/bin/templates/workspace/.github/workflows/publish-packages.yml

@@ -104,18 +104,11 @@ jobs:
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
-        env:
-          NPM_TOKEN: ${{ secrets.NPMJS_TOKEN }}
-        run: |
-          # Copy package to isolated directory to avoid workspace resolution
-          mkdir -p /tmp/publish-pkg
-          cp -r ${{ matrix.package.dir }}/* /tmp/publish-pkg/
-          cd /tmp/publish-pkg
-          bun install
+        run: bun install
 
       - name: Bump version (only if already published)
         id: bump
-        working-directory: /tmp/publish-pkg
+        working-directory: ${{ matrix.package.dir }}
         run: |
           CURRENT=$(jq -r '.version' package.json)
           PUBLISHED=$(npm view "${{ matrix.package.name }}" version 2>/dev/null || echo "0.0.0")
@@ -134,15 +127,15 @@ jobs:
           fi
 
       - name: Build
-        working-directory: /tmp/publish-pkg
+        working-directory: ${{ matrix.package.dir }}
         run: bun run --if-present build
 
       - name: Test
-        working-directory: /tmp/publish-pkg
+        working-directory: ${{ matrix.package.dir }}
         run: bun run --if-present test
 
       - name: Publish
-        working-directory: /tmp/publish-pkg
+        working-directory: ${{ matrix.package.dir }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPMJS_TOKEN }}
         run: npm publish --access=public
@@ -152,8 +145,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          # Copy bumped version back to repo
-          cp /tmp/publish-pkg/package.json ${{ matrix.package.dir }}/package.json
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add "${{ matrix.package.dir }}/package.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI toolkit for scaffolding Turborepo workspaces with Pulumi infrastructure and Hono/NestJS microservices",
   "keywords": [
     "cli",
@@ -27,6 +27,7 @@
   "files": [
     "bin/**/*.js",
     "bin/**/templates/**",
+    "bin/**/instructions/**",
     "bin/**/*.json",
     "!bin/**/*.map",
     "dist/",
@@ -46,7 +47,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",
+    "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",
@@ -103,7 +104,7 @@
     "zx": "^8.5.3"
   },
   "peerDependencies": {
-    "@crossdelta/infrastructure": "^0.2.2",
+    "@crossdelta/infrastructure": "workspace:*",
     "@nestjs/schematics": "^11.0.5",
     "turbo": "^2.0.0"
   },