cc-devflow 4.3.0 → 4.5.0

package/.claude/skills/_reference-implementations/backend-express-prisma/resources/configuration.md

@@ -1,275 +0,0 @@
-# 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](SKILL.md)
-- [testing-guide.md](testing-guide.md)

package/.claude/skills/_reference-implementations/backend-express-prisma/resources/database-patterns.md

@@ -1,224 +0,0 @@
-# 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](SKILL.md)
-- [services-and-repositories.md](services-and-repositories.md)
-- [async-and-errors.md](async-and-errors.md)

package/.claude/skills/_reference-implementations/backend-express-prisma/resources/middleware-guide.md

@@ -1,213 +0,0 @@
-# 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](SKILL.md)
-- [routing-and-controllers.md](routing-and-controllers.md)
-- [async-and-errors.md](async-and-errors.md)