@crossdelta/platform-sdk 0.3.13 → 0.3.14

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

@@ -203,6 +203,22 @@ These commands will be executed automatically by the CLI.
 
 **CRITICAL:** The service path in the `pf new` command MUST match the service name provided by the user exactly. If the user specifies `services/my-service`, use `services/my-service`. Do NOT modify or prepend paths.
 
+### Dependencies (Optional)
+
+If the service requires additional npm packages beyond what's scaffolded, list them in a `dependencies` block:
+
+```dependencies
+@pusher/push-notifications-server
+zod
+drizzle-orm
+```
+
+**Format:**
+- One package per line
+- Use exact package names from npm (e.g., `@scope/package-name`)
+- Comments starting with `#` are ignored
+- These packages will be installed using the existing integration system
+
 ### Source Files
 
 Format source files with path headers. Paths are relative to the service directory (e.g., `src/index.ts`, NOT `services/my-service/src/index.ts`):
@@ -212,8 +228,173 @@ Format source files with path headers. Paths are relative to the service directo
 // code here
 ```
 
-**Important:**
-- Always include the `pf new` command to scaffold the service first
-- Only generate `src/` files - package.json, Dockerfile, tsconfig.json are created by `pf new`
-- Follow the Service Entry Point Pattern above
-- Biome lint/format runs automatically after generation – don't worry about minor formatting
+#### `src/handlers/event-name.event.ts`
+```typescript
+// event handler code
+```
+
+#### `src/use-cases/business-logic.use-case.ts`
+```typescript
+// business logic code
+```
+
+### Tests
+
+Always generate tests for the service. Use Bun's native test runner (`bun:test`):
+
+#### `src/index.test.ts`
+```typescript
+import { describe, expect, it } from 'bun:test'
+
+describe('Service Health Check', () => {
+  it('should respond to health check', async () => {
+    const app = new Hono()
+    app.get('/health', (c) => c.json({ status: 'ok' }))
+    
+    const req = new Request('http://localhost/health')
+    const res = await app.fetch(req)
+    
+    expect(res.status).toBe(200)
+    const json = await res.json()
+    expect(json).toEqual({ status: 'ok' })
+  })
+})
+```
+
+#### `src/use-cases/business-logic.use-case.test.ts`
+```typescript
+import { describe, expect, it, beforeEach, vi } from 'bun:test'
+import { myUseCase } from './business-logic.use-case'
+
+describe('BusinessLogic Use Case', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  
+  it('should handle valid input correctly', async () => {
+    const result = await myUseCase({ id: '123' })
+    expect(result).toBeDefined()
+  })
+  
+  it('should throw error for invalid input', async () => {
+    await expect(myUseCase({ id: '' })).rejects.toThrow()
+  })
+})
+```
+
+**Test Guidelines:**
+- Write tests ONLY for use cases (NOT event handlers)
+- Event handlers are thin wrappers - the use cases contain the testable logic
+- Use Bun's native test runner: `import { describe, expect, it, beforeEach, afterEach, vi } from 'bun:test'`
+- Use `vi` from `bun:test` for mocking (NOT jest or vitest)
+- Use descriptive test names in English
+- Test both happy paths and error cases
+- Focus on validation and error handling
+- DO NOT mock external libraries (Pusher, AWS SDK, etc.) - they are hard to mock correctly
+- Test environment variable validation and input validation
+- Use `beforeEach`/`afterEach` to clean up mocks: `vi.clearAllMocks()` or `vi.restoreAllMocks()`
+
+**Example: Testing validation and error handling**
+```typescript
+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 are not set', async () => {
+    delete process.env.PUSHER_BEAMS_INSTANCE_ID
+    
+    await expect(
+      sendNotification({ orderId: '123', customerId: 'cust-1' })
+    ).rejects.toThrow('Missing Pusher Beams credentials')
+  })
+})
+```
+
+### README
+
+Generate a service-specific README documenting:
+
+#### `README.md`
+```markdown
+# Service Name
+
+Brief description of what this service does.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `SERVICE_PORT` | Port the service runs on | No | 4001 |
+| `NATS_URL` | NATS server URL | Yes | - |
+
+## Events
+
+### Publishes
+- `{{projectName}}.service.event` - Description
+
+### Consumes
+- `{{projectName}}.other.event` - Description
+
+## API Endpoints
+
+### `GET /health`
+Health check endpoint.
+
+**Response:**
+\`\`\`json
+{ "status": "ok" }
+\`\`\`
+
+## Development
+
+\`\`\`bash
+bun dev              # Start in development mode
+bun test             # Run tests
+\`\`\`
+```
+
+**CRITICAL - You MUST generate ALL of these:**
+1. ✅ `pf new` command (first step - scaffolds the service)
+2. ✅ Source files (`src/index.ts`, `src/handlers/*.event.ts`, `src/use-cases/*.use-case.ts`)
+3. ✅ **Test files for EVERY use case** (`src/use-cases/*.test.ts`) - DO NOT test event handlers
+4. ✅ **Complete README.md** with:
+   - Service description & features
+   - Environment variables table
+   - Events (published/consumed)
+   - API endpoints documentation
+   - Development commands
+
+**DO NOT skip tests or README** - they are REQUIRED, not optional.
+
+**Test Strategy:**
+- Focus on validation (input parameters, environment variables)
+- Test error handling and edge cases
+- Keep tests simple - avoid complex mocking of external libraries
+- Test the business logic, not the external API calls
+
+**Format notes:**
+- Follow the Service Entry Point Pattern and folder structure above
+- Biome lint/format runs automatically after generation – don't worry about minor formatting
+- **ALL code comments, documentation, and README files MUST be written in English**
+- **Tests MUST be compatible with Bun's test runner** (`bun:test` module with `describe`, `it`, `expect`, `beforeEach`, `afterEach`, `vi` for mocking)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "CLI toolkit for scaffolding Turborepo workspaces with Pulumi infrastructure and Hono/NestJS microservices",
   "keywords": [
     "cli",