@crossdelta/platform-sdk 0.5.12 → 0.7.0

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

@@ -1,694 +1,56 @@
-# {{projectName}} Platform – AI Coding Guidelines
-
-## Architecture Overview
-
-Bun-based **monorepo** (Tu  }).optional(),
-})
-
-// Export type for use in use-cases
-export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
-
-export default handleEvent() with event-driven microservices:
-
-| Directory | Stack | Purpose |
-|-----------|-------|---------|
-| `apps/storefront/` | Qwik + RxDB + Supabase | Offline-first PWA, multi-tenant |
-| `services/orders/` | Hono | Microservice (events via NATS) |
-| `services/notifications/` | Hono | Event consumer (auto-discovery) |
-| `services/api-gateway/` | NestJS | Optional REST entry point |
-| `packages/cloudevents/` | TypeScript | CloudEvents + NATS/JetStream toolkit |
-| `packages/telemetry/` | OpenTelemetry | Zero-config tracing/metrics |
-| `infra/` | Pulumi | IaC for DigitalOcean Kubernetes |
-
-**Data flow:** Storefront ↔ Supabase (realtime sync) → Services publish CloudEvents → NATS JetStream → Consumer services.
-
-## Essential Commands
-
-```bash
-bun install                          # Install all workspace dependencies
-bun dev                              # Start all services (generates .env.local first)
-bun pf new hono-micro services/NAME  # Scaffold new microservice + infra config
-bun test                             # Run tests with Bun
-bun lint && bun format               # Biome linting/formatting
-cd apps/storefront && bun supabase start  # Local Supabase (Docker required)
-```
-
-## Creating Microservices
-
-Use the CLI—it scaffolds code + infrastructure + environment in one command:
-
-```bash
-bun pf new hono-micro services/my-service -y
-```
-
-This creates `services/my-service/` + `infra/services/my-service.ts`, assigns a port, and updates `.env.local`.
-
-### Service Entry Point Pattern
-
-All service logic belongs in `src/index.ts` - do NOT create separate files for consumers or startup code.
-
-```ts
-// IMPORTANT: telemetry MUST be first import
-import '@crossdelta/telemetry'
-
-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 })
-```
-
-## CloudEvents & NATS Messaging
-
-**Always use `@crossdelta/cloudevents`**, never raw NATS client.
-
-### Publishing Events
-
-```ts
-import { publish } from '@crossdelta/cloudevents'
-
-await publish('orders.created', { orderId, customerId, total }, {
-  source: '{{projectName}}://orders-service',
-  subject: orderId
-})
-```
-
-The `publish` function automatically:
-- Constructs the CloudEvent type from the subject (e.g., `orders.created` → `{{projectName}}.orders.created`)
-- Adds required CloudEvent metadata (id, time, specversion, datacontenttype)
-- Publishes to NATS JetStream
-
-### Consuming Events (Auto-Discovery)
-
-Create handler files in `src/handlers/*.event.ts`:
-
-```ts
-// services/notifications/src/handlers/order-created.event.ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-import { sendNotification } from '../use-cases/send-notification.use-case'
-
-const OrderCreatedSchema = z.object({
-  orderId: z.string(),
-  customerId: z.string(),
-  total: z.number(),
-  items: z.array(
-    z.object({
-      productId: z.string(),
-      quantity: z.number(),
-      price: z.number(),
-    }),
-  ).optional(),
-})
-
-// Export type for reuse in other services
-export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
-
-export default handleEvent(
-  {
-    schema: OrderCreatedSchema,
-    type: 'orders.created',
-  },
-  async (data) => {
-    await sendNotification(data)
-  },
-)
-```
-
-**Important:**
-- **Schema** validates only the event data payload (without `type` field)
-- **Event type** is declared in the options object, not in the schema
-- Event type matches the first parameter of `publish()` (e.g., `'orders.created'`)
-- Do NOT include `type: z.literal('...')` in the schema - it's redundant and causes validation errors
-- **Always export the inferred type** using `export type EventName = z.infer<typeof EventSchema>` for use in use-cases
-
-**Naming conventions:**
-- Schema constants: PascalCase with `Schema` suffix (e.g., `OrderCreatedSchema`, `UserUpdatedSchema`)
-- Exported types: PascalCase with `Event` suffix (e.g., `OrderCreatedEvent`, `UserUpdatedEvent`)
-
-### Service Folder Structure
-
-Organize service code with this structure:
-
-```
-src/
-├── index.ts              # Entry point with telemetry, Hono app, NATS setup
-├── handlers/             # Event handlers (*.event.ts files for NATS events)
-│   └── order-created.event.ts
-└── use-cases/            # Business logic / use cases
-    └── send-notification.use-case.ts
-```
-
-- **`src/handlers/`**: Event handlers that consume CloudEvents from NATS
-- **`src/use-cases/`**: Reusable business logic (pure functions or classes)
-- Keep `src/index.ts` focused on wiring (server, consumers, routes)
-
-Start consumption in `src/index.ts` (NOT in a separate file):
-
-```ts
-// src/index.ts - complete example with event consumption
-import '@crossdelta/telemetry'
-
-import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
-import { Hono } from 'hono'
-
-const port = Number(process.env.PORT || process.env.NOTIFICATIONS_PORT) || 4002
-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: 'notifications',
-  discover: './src/handlers/**/*.event.ts',
-})
-
-Bun.serve({ port, fetch: app.fetch })
-```
-
-## Storefront: RxDB + Supabase Replication
-
-### Adding a New Collection
-
-1. Create schema in `apps/storefront/src/db/schemas/generated/`
-2. Add collection definition in `apps/storefront/src/db/collections/definitions/`:
-
-```ts
-export const ordersCollectionDefinition = defineCollection({
-  name: 'orders',
-  creator: { schema: ordersRxdbSchema },
-  setup: async (collection) => {
-    await replicateSupabaseTable(collection, 'orders', { tenant: createTenantScopeGuard() })
-  },
-  useCollectionQuery,
-})
-```
-
-3. Register in `apps/storefront/src/db/collections/definitions/index.ts`
-
-**Supabase tables require:** `id`, `updated_at`, `_deleted` (boolean for soft-delete).
-
-## Infrastructure (Pulumi + Kubernetes)
-
-### 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',
-  ports: ports().http(4001).build(),
-  replicas: 1,
-  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 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 |
-|---------|---------|
-| Hono service entry | `services/orders/src/index.ts` |
-| Event handler | `services/notifications/src/handlers/order-created.event.ts` |
-| RxDB collection | `apps/storefront/src/db/collections/definitions/orders.ts` |
-| Service infra config | `infra/services/orders.ts` |
-| Supabase migrations | `apps/storefront/supabase/migrations/` |
-
-## AI Code Generation Format
-
-When generating code via `pf ai generate-service`, use this output format:
-
-### Commands to Execute
-
-List commands that should be run BEFORE the source files are created:
-
-```commands
-pf new hono-micro services/my-service -y
-```
-
-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`):
-
-#### `src/index.ts`
-```typescript
-// code here
-```
-
-#### `src/handlers/event-name.event.ts`
-```typescript
-import { handleEvent } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-import { businessLogic } from '../use-cases/business-logic.use-case'
-
-const EventDataSchema = z.object({
-  id: z.string(),
-  // ... other fields
-})
-
-// Export type for use in use-cases
-export type EventDataType = z.infer<typeof EventDataSchema>
-
-export default handleEvent(
-  {
-    schema: EventDataSchema,
-    type: 'resource.action',  // e.g., 'orders.created', 'users.updated'
-  },
-  async (data) => {
-    await businessLogic(data)
-  },
-)
-```
-
-#### `src/use-cases/business-logic.use-case.ts`
-```typescript
-import type { EventDataType } from '../handlers/event-name.event'
-
-/**
- * Business logic that processes the event data.
- * Uses the exported type from the handler for type safety.
- */
-export async function businessLogic(data: EventDataType): Promise<void> {
-  // Full type inference from the handler schema
-  console.log('Processing:', data.id)
-  
-  // All business logic here
-  // - Validation
-  // - External API calls
-  // - Database operations
-}
-```
-
-### 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 } from 'bun:test'
-import { myUseCase } from './business-logic.use-case'
-
-describe('BusinessLogic Use Case', () => {
-  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('Invalid input')
-  })
-})
-```
-
-**Test Guidelines:**
-- **Keep tests simple and lightweight** - Bun's test runner is minimal, not a full-featured test framework
-- 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 } from 'bun:test'`
-- **NO mocking available** - Bun's test runner does NOT have `vi`, `mock`, or similar utilities
-  - ❌ NO `vi` object (that's Vitest, not Bun)
-  - ❌ NO `jest.fn()` or `jest.mock()`
-  - ❌ NO module mocking
-  - ✅ Use simple, direct testing without mocks
-- Use descriptive test names in English
-- Test both happy paths and error cases
-- Focus on validation and error handling (input params, env vars)
-- **DO NOT mock external libraries** - Bun doesn't support mocking, keep tests simple
-- Test environment variable validation and input validation
-- Keep cleanup simple in `afterEach`: restore `process.env` only
-
-**Example: Simple validation and error handling tests**
-```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(() => {
-    // Save original environment
-    process.env = { ...originalEnv }
-  })
-
-  afterEach(() => {
-    // Restore original environment (no vi.resetModules needed)
-    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')
-  })
-})
-```
-
-**What to test:**
-- ✅ Input validation (missing/empty parameters)
-- ✅ Environment variable validation
-- ✅ Error messages and error types
-- ✅ Basic logic flows
-- ❌ Complex mocking scenarios
-- ❌ External API integrations (Pusher, AWS, etc.)
-- ❌ Module reloading/resetting
-
-**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
-- If a function calls an external API, test the validation BEFORE the call, not the call itself
-
-**Example of what NOT to do:**
-```typescript
-// ❌ BAD - Trying to mock Pusher (not possible in Bun)
-import { describe, expect, it, beforeEach, afterEach, vi } from 'bun:test'
-
-describe('Bad Test', () => {
-  afterEach(() => {
-    vi.resetModules()  // ❌ This doesn't exist in Bun!
-  })
-  
-  it('should send notification', async () => {
-    // ❌ Trying to mock external library
-    const mockPusher = vi.fn()  // ❌ vi doesn't exist!
-  })
-})
-```
-
-**Example of what TO do:**
-```typescript
-// ✅ GOOD - Simple validation tests
-import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
-
-describe('Good Test', () => {
-  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')
-  })
-})
-```
-
-### 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)
+# Copilot Instructions (Project-Agnostic, TypeScript-Focused)
+
+You are assisting in TypeScript-first monorepos using modern TypeScript tooling such as Bun or Node, Turborepo, Hono, NestJS, Zod, event-driven patterns, and Pulumi/Kubernetes infrastructure.
+
+Always generate **minimal diffs**, never full rewrites.
+
+## General Behavior
+- Produce short, focused, code-first answers.
+- Modify only the necessary parts.
+- Analyze only the opened file unless explicitly asked.
+- Follow existing architecture and naming conventions.
+- Prefer strict typing; avoid `any`.
+
+## Code Style
+- Single quotes, no semicolons, 2-space indent, trailing commas.
+- Alphabetically sorted imports; no unused imports.
+- Arrow functions over `function` declarations.
+- Prefer pure and functional programming patterns (map/filter/reduce).
+- Avoid mutable state and imperative loops.
+- No decorative section header blocks (no ASCII art separators like `// ─────────────`).
+- Use blank lines to separate logical sections naturally.
+- Organize code: types → helpers → higher-order functions.
+- Use JSDoc for exported functions and complex logic; keep inline comments minimal.
+- Self-documenting code over comments: clear naming, pure functions, obvious control flow.
+
+## Validation & Types
+- Use Zod for schemas.
+- Export inferred types using `z.infer`.
+- Do NOT include literal event types inside schemas.
+- Do not duplicate validation logic across layers.
+
+## Service & Module Structure
+- Entry points handle wiring (server start, telemetry, routing, consumers).
+- Business logic lives in use-case modules.
+- Event handlers must be thin wrappers around use-cases.
+
+## Event Handling
+- Use shared CloudEvents/messaging libraries, not raw clients.
+- Handlers: Schema → inferred type → thin handler → use-case delegation.
+- Handlers named `*.event.ts`.
+
+## Infrastructure
+- Use fluent port builders when available.
+- Expose a `/health` endpoint.
+- Avoid legacy containerPort usage.
+
+## Testing
+- Test use-cases, not handlers or frameworks.
+- Prefer simple direct tests, no mocks.
+- Validate both error and success paths.
+
+## AI Output Format
+- Provide only necessary files.
+- Use relative paths.
+- Keep comments minimal.
+- Do not generate abstractions not already present.