codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/backend-dev-guidelines/resources/configuration.md

@@ -0,0 +1,275 @@
+# Configuration Management - UnifiedConfig Pattern
+
+Complete guide to managing configuration in backend microservices.
+
+## Table of Contents
+
+- [UnifiedConfig Overview](#unifiedconfig-overview)
+- [NEVER Use process.env Directly](#never-use-processenv-directly)
+- [Configuration Structure](#configuration-structure)
+- [Environment-Specific Configs](#environment-specific-configs)
+- [Secrets Management](#secrets-management)
+- [Migration Guide](#migration-guide)
+
+---
+
+## UnifiedConfig Overview
+
+### Why UnifiedConfig?
+
+**Problems with process.env:**
+- ❌ No type safety
+- ❌ No validation
+- ❌ Hard to test
+- ❌ Scattered throughout code
+- ❌ No default values
+- ❌ Runtime errors for typos
+
+**Benefits of unifiedConfig:**
+- ✅ Type-safe configuration
+- ✅ Single source of truth
+- ✅ Validated at startup
+- ✅ Easy to test with mocks
+- ✅ Clear structure
+- ✅ Fallback to environment variables
+
+---
+
+## NEVER Use process.env Directly
+
+### The Rule
+
+```typescript
+// ❌ NEVER DO THIS
+const timeout = parseInt(process.env.TIMEOUT_MS || '5000');
+const dbHost = process.env.DB_HOST || 'localhost';
+
+// ✅ ALWAYS DO THIS
+import { config } from './config/unifiedConfig';
+const timeout = config.timeouts.default;
+const dbHost = config.database.host;
+```
+
+### Why This Matters
+
+**Example of problems:**
+```typescript
+// Typo in environment variable name
+const host = process.env.DB_HSOT; // undefined! No error!
+
+// Type safety
+const port = process.env.PORT; // string! Need parseInt
+const timeout = parseInt(process.env.TIMEOUT); // NaN if not set!
+```
+
+**With unifiedConfig:**
+```typescript
+const port = config.server.port; // number, guaranteed
+const timeout = config.timeouts.default; // number, with fallback
+```
+
+---
+
+## Configuration Structure
+
+### UnifiedConfig Interface
+
+```typescript
+export interface UnifiedConfig {
+    database: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+        database: string;
+    };
+    server: {
+        port: number;
+        sessionSecret: string;
+    };
+    tokens: {
+        jwt: string;
+        inactivity: string;
+        internal: string;
+    };
+    keycloak: {
+        realm: string;
+        client: string;
+        baseUrl: string;
+        secret: string;
+    };
+    aws: {
+        region: string;
+        emailQueueUrl: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    sentry: {
+        dsn: string;
+        environment: string;
+        tracesSampleRate: number;
+    };
+    // ... more sections
+}
+```
+
+### Implementation Pattern
+
+**File:** `/blog-api/src/config/unifiedConfig.ts`
+
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ini from 'ini';
+
+const configPath = path.join(__dirname, '../../config.ini');
+const iniConfig = ini.parse(fs.readFileSync(configPath, 'utf-8'));
+
+export const config: UnifiedConfig = {
+    database: {
+        host: iniConfig.database?.host || process.env.DB_HOST || 'localhost',
+        port: parseInt(iniConfig.database?.port || process.env.DB_PORT || '3306'),
+        username: iniConfig.database?.username || process.env.DB_USER || 'root',
+        password: iniConfig.database?.password || process.env.DB_PASSWORD || '',
+        database: iniConfig.database?.database || process.env.DB_NAME || 'blog_dev',
+    },
+    server: {
+        port: parseInt(iniConfig.server?.port || process.env.PORT || '3002'),
+        sessionSecret: iniConfig.server?.sessionSecret || process.env.SESSION_SECRET || 'dev-secret',
+    },
+    // ... more configuration
+};
+
+// Validate critical config
+if (!config.tokens.jwt) {
+    throw new Error('JWT secret not configured!');
+}
+```
+
+**Key Points:**
+- Read from config.ini first
+- Fallback to process.env
+- Default values for development
+- Validation at startup
+- Type-safe access
+
+---
+
+## Environment-Specific Configs
+
+### config.ini Structure
+
+```ini
+[database]
+host = localhost
+port = 3306
+username = root
+password = password1
+database = blog_dev
+
+[server]
+port = 3002
+sessionSecret = your-secret-here
+
+[tokens]
+jwt = your-jwt-secret
+inactivity = 30m
+internal = internal-api-token
+
+[keycloak]
+realm = myapp
+client = myapp-client
+baseUrl = http://localhost:8080
+secret = keycloak-client-secret
+
+[sentry]
+dsn = https://your-sentry-dsn
+environment = development
+tracesSampleRate = 0.1
+```
+
+### Environment Overrides
+
+```bash
+# .env file (optional overrides)
+DB_HOST=production-db.example.com
+DB_PASSWORD=secure-password
+PORT=80
+```
+
+**Precedence:**
+1. config.ini (highest priority)
+2. process.env variables
+3. Hard-coded defaults (lowest priority)
+
+---
+
+## Secrets Management
+
+### DO NOT Commit Secrets
+
+```gitignore
+# .gitignore
+config.ini
+.env
+sentry.ini
+*.pem
+*.key
+```
+
+### Use Environment Variables in Production
+
+```typescript
+// Development: config.ini
+// Production: Environment variables
+
+export const config: UnifiedConfig = {
+    database: {
+        password: process.env.DB_PASSWORD || iniConfig.database?.password || '',
+    },
+    tokens: {
+        jwt: process.env.JWT_SECRET || iniConfig.tokens?.jwt || '',
+    },
+};
+```
+
+---
+
+## Migration Guide
+
+### Find All process.env Usage
+
+```bash
+grep -r "process.env" blog-api/src/ --include="*.ts" | wc -l
+```
+
+### Migration Example
+
+**Before:**
+```typescript
+// Scattered throughout code
+const timeout = parseInt(process.env.OPENID_HTTP_TIMEOUT_MS || '15000');
+const keycloakUrl = process.env.KEYCLOAK_BASE_URL;
+const jwtSecret = process.env.JWT_SECRET;
+```
+
+**After:**
+```typescript
+import { config } from './config/unifiedConfig';
+
+const timeout = config.keycloak.timeout;
+const keycloakUrl = config.keycloak.baseUrl;
+const jwtSecret = config.tokens.jwt;
+```
+
+**Benefits:**
+- Type-safe
+- Centralized
+- Easy to test
+- Validated at startup
+
+---
+
+**Related Files:**
+- SKILL.md
+- [testing-guide.md](testing-guide.md)

package/templates/.agent/skills/backend-dev-guidelines/resources/database-patterns.md

@@ -0,0 +1,224 @@
+# Database Patterns - Prisma Best Practices
+
+Complete guide to database access patterns using Prisma in backend microservices.
+
+## Table of Contents
+
+- [PrismaService Usage](#prismaservice-usage)
+- [Repository Pattern](#repository-pattern)
+- [Transaction Patterns](#transaction-patterns)
+- [Query Optimization](#query-optimization)
+- [N+1 Query Prevention](#n1-query-prevention)
+- [Error Handling](#error-handling)
+
+---
+
+## PrismaService Usage
+
+### Basic Pattern
+
+```typescript
+import { PrismaService } from '@project-lifecycle-portal/database';
+
+// Always use PrismaService.main
+const users = await PrismaService.main.user.findMany();
+```
+
+### Check Availability
+
+```typescript
+if (!PrismaService.isAvailable) {
+    throw new Error('Prisma client not initialized');
+}
+
+const user = await PrismaService.main.user.findUnique({ where: { id } });
+```
+
+---
+
+## Repository Pattern
+
+### Why Use Repositories
+
+✅ **Use repositories when:**
+- Complex queries with joins/includes
+- Query used in multiple places
+- Need caching layer
+- Want to mock for testing
+
+❌ **Skip repositories for:**
+- Simple one-off queries
+- Prototyping (can refactor later)
+
+### Repository Template
+
+```typescript
+export class UserRepository {
+    async findById(id: string): Promise<User | null> {
+        return PrismaService.main.user.findUnique({
+            where: { id },
+            include: { profile: true },
+        });
+    }
+
+    async findActive(): Promise<User[]> {
+        return PrismaService.main.user.findMany({
+            where: { isActive: true },
+            orderBy: { createdAt: 'desc' },
+        });
+    }
+
+    async create(data: Prisma.UserCreateInput): Promise<User> {
+        return PrismaService.main.user.create({ data });
+    }
+}
+```
+
+---
+
+## Transaction Patterns
+
+### Simple Transaction
+
+```typescript
+const result = await PrismaService.main.$transaction(async (tx) => {
+    const user = await tx.user.create({ data: userData });
+    const profile = await tx.userProfile.create({ data: { userId: user.id } });
+    return { user, profile };
+});
+```
+
+### Interactive Transaction
+
+```typescript
+const result = await PrismaService.main.$transaction(
+    async (tx) => {
+        const user = await tx.user.findUnique({ where: { id } });
+        if (!user) throw new Error('User not found');
+
+        return await tx.user.update({
+            where: { id },
+            data: { lastLogin: new Date() },
+        });
+    },
+    {
+        maxWait: 5000,
+        timeout: 10000,
+    }
+);
+```
+
+---
+
+## Query Optimization
+
+### Use select to Limit Fields
+
+```typescript
+// ❌ Fetches all fields
+const users = await PrismaService.main.user.findMany();
+
+// ✅ Only fetch needed fields
+const users = await PrismaService.main.user.findMany({
+    select: {
+        id: true,
+        email: true,
+        profile: { select: { firstName: true, lastName: true } },
+    },
+});
+```
+
+### Use include Carefully
+
+```typescript
+// ❌ Excessive includes
+const user = await PrismaService.main.user.findUnique({
+    where: { id },
+    include: {
+        profile: true,
+        posts: { include: { comments: true } },
+        workflows: { include: { steps: { include: { actions: true } } } },
+    },
+});
+
+// ✅ Only include what you need
+const user = await PrismaService.main.user.findUnique({
+    where: { id },
+    include: { profile: true },
+});
+```
+
+---
+
+## N+1 Query Prevention
+
+### Problem: N+1 Queries
+
+```typescript
+// ❌ N+1 Query Problem
+const users = await PrismaService.main.user.findMany(); // 1 query
+
+for (const user of users) {
+    // N queries (one per user)
+    const profile = await PrismaService.main.userProfile.findUnique({
+        where: { userId: user.id },
+    });
+}
+```
+
+### Solution: Use include or Batching
+
+```typescript
+// ✅ Single query with include
+const users = await PrismaService.main.user.findMany({
+    include: { profile: true },
+});
+
+// ✅ Or batch query
+const userIds = users.map(u => u.id);
+const profiles = await PrismaService.main.userProfile.findMany({
+    where: { userId: { in: userIds } },
+});
+```
+
+---
+
+## Error Handling
+
+### Prisma Error Types
+
+```typescript
+import { Prisma } from '@prisma/client';
+
+try {
+    await PrismaService.main.user.create({ data });
+} catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError) {
+        // Unique constraint violation
+        if (error.code === 'P2002') {
+            throw new ConflictError('Email already exists');
+        }
+
+        // Foreign key constraint
+        if (error.code === 'P2003') {
+            throw new ValidationError('Invalid reference');
+        }
+
+        // Record not found
+        if (error.code === 'P2025') {
+            throw new NotFoundError('Record not found');
+        }
+    }
+
+    // Unknown error
+    Sentry.captureException(error);
+    throw error;
+}
+```
+
+---
+
+**Related Files:**
+- SKILL.md
+- [services-and-repositories.md](services-and-repositories.md)
+- [async-and-errors.md](async-and-errors.md)

package/templates/.agent/skills/backend-dev-guidelines/resources/middleware-guide.md

@@ -0,0 +1,213 @@
+# Middleware Guide - Express Middleware Patterns
+
+Complete guide to creating and using middleware in backend microservices.
+
+## Table of Contents
+
+- [Authentication Middleware](#authentication-middleware)
+- [Audit Middleware with AsyncLocalStorage](#audit-middleware-with-asynclocalstorage)
+- [Error Boundary Middleware](#error-boundary-middleware)
+- [Validation Middleware](#validation-middleware)
+- [Composable Middleware](#composable-middleware)
+- [Middleware Ordering](#middleware-ordering)
+
+---
+
+## Authentication Middleware
+
+### SSOMiddleware Pattern
+
+**File:** `/form/src/middleware/SSOMiddleware.ts`
+
+```typescript
+export class SSOMiddlewareClient {
+    static verifyLoginStatus(req: Request, res: Response, next: NextFunction): void {
+        const token = req.cookies.refresh_token;
+
+        if (!token) {
+            return res.status(401).json({ error: 'Not authenticated' });
+        }
+
+        try {
+            const decoded = jwt.verify(token, config.tokens.jwt);
+            res.locals.claims = decoded;
+            res.locals.effectiveUserId = decoded.sub;
+            next();
+        } catch (error) {
+            res.status(401).json({ error: 'Invalid token' });
+        }
+    }
+}
+```
+
+---
+
+## Audit Middleware with AsyncLocalStorage
+
+### Excellent Pattern from Blog API
+
+**File:** `/form/src/middleware/auditMiddleware.ts`
+
+```typescript
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface AuditContext {
+    userId: string;
+    userName?: string;
+    impersonatedBy?: string;
+    sessionId?: string;
+    timestamp: Date;
+    requestId: string;
+}
+
+export const auditContextStorage = new AsyncLocalStorage<AuditContext>();
+
+export function auditMiddleware(req: Request, res: Response, next: NextFunction): void {
+    const context: AuditContext = {
+        userId: res.locals.effectiveUserId || 'anonymous',
+        userName: res.locals.claims?.preferred_username,
+        impersonatedBy: res.locals.isImpersonating ? res.locals.originalUserId : undefined,
+        timestamp: new Date(),
+        requestId: req.id || uuidv4(),
+    };
+
+    auditContextStorage.run(context, () => {
+        next();
+    });
+}
+
+// Getter for current context
+export function getAuditContext(): AuditContext | null {
+    return auditContextStorage.getStore() || null;
+}
+```
+
+**Benefits:**
+- Context propagates through entire request
+- No need to pass context through every function
+- Automatically available in services, repositories
+- Type-safe context access
+
+**Usage in Services:**
+```typescript
+import { getAuditContext } from '../middleware/auditMiddleware';
+
+async function someOperation() {
+    const context = getAuditContext();
+    console.log('Operation by:', context?.userId);
+}
+```
+
+---
+
+## Error Boundary Middleware
+
+### Comprehensive Error Handler
+
+**File:** `/form/src/middleware/errorBoundary.ts`
+
+```typescript
+export function errorBoundary(
+    error: Error,
+    req: Request,
+    res: Response,
+    next: NextFunction
+): void {
+    // Determine status code
+    const statusCode = getStatusCodeForError(error);
+
+    // Capture to Sentry
+    Sentry.withScope((scope) => {
+        scope.setLevel(statusCode >= 500 ? 'error' : 'warning');
+        scope.setTag('error_type', error.name);
+        scope.setContext('error_details', {
+            message: error.message,
+            stack: error.stack,
+        });
+        Sentry.captureException(error);
+    });
+
+    // User-friendly response
+    res.status(statusCode).json({
+        success: false,
+        error: {
+            message: getUserFriendlyMessage(error),
+            code: error.name,
+        },
+        requestId: Sentry.getCurrentScope().getPropagationContext().traceId,
+    });
+}
+
+// Async wrapper
+export function asyncErrorWrapper(
+    handler: (req: Request, res: Response, next: NextFunction) => Promise<any>
+) {
+    return async (req: Request, res: Response, next: NextFunction) => {
+        try {
+            await handler(req, res, next);
+        } catch (error) {
+            next(error);
+        }
+    };
+}
+```
+
+---
+
+## Composable Middleware
+
+### withAuthAndAudit Pattern
+
+```typescript
+export function withAuthAndAudit(...authMiddleware: any[]) {
+    return [
+        ...authMiddleware,
+        auditMiddleware,
+    ];
+}
+
+// Usage
+router.post('/:formID/submit',
+    ...withAuthAndAudit(SSOMiddlewareClient.verifyLoginStatus),
+    async (req, res) => controller.submit(req, res)
+);
+```
+
+---
+
+## Middleware Ordering
+
+### Critical Order (Must Follow)
+
+```typescript
+// 1. Sentry request handler (FIRST)
+app.use(Sentry.Handlers.requestHandler());
+
+// 2. Body parsing
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// 3. Cookie parsing
+app.use(cookieParser());
+
+// 4. Auth initialization
+app.use(SSOMiddleware.initialize());
+
+// 5. Routes registered here
+app.use('/api/users', userRoutes);
+
+// 6. Error handler (AFTER routes)
+app.use(errorBoundary);
+
+// 7. Sentry error handler (LAST)
+app.use(Sentry.Handlers.errorHandler());
+```
+
+**Rule:** Error handlers MUST be registered AFTER all routes!
+
+---
+
+**Related Files:**
+- SKILL.md
+- [routing-and-controllers.md](routing-and-controllers.md)
+- [async-and-errors.md](async-and-errors.md)