@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/nestjs/.claude/rules/interceptors.md

@@ -0,0 +1,317 @@
+---
+paths:
+  - "src/**/*.interceptor.ts"
+  - "src/**/interceptors/**/*.ts"
+  - "src/**/*.controller.ts"
+  - "src/**/*.module.ts"
+---
+
+# NestJS Interceptors
+
+## Interceptor Basics
+
+Interceptors can:
+- Transform response data
+- Transform exceptions
+- Extend/override function behavior
+- Implement caching, logging, timeout
+
+```typescript
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map, tap } from 'rxjs/operators';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const { method, url } = request;
+    const now = Date.now();
+
+    console.log(`[${method}] ${url} - Started`);
+
+    return next.handle().pipe(
+      tap(() => {
+        console.log(`[${method}] ${url} - ${Date.now() - now}ms`);
+      }),
+    );
+  }
+}
+```
+
+## Response Transform Interceptor
+
+```typescript
+// Wrap all responses in standard format
+export interface ApiResponse<T> {
+  data: T;
+  meta: {
+    timestamp: string;
+    requestId: string;
+  };
+}
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<ApiResponse<T>> {
+    const request = context.switchToHttp().getRequest();
+
+    return next.handle().pipe(
+      map((data) => ({
+        data,
+        meta: {
+          timestamp: new Date().toISOString(),
+          requestId: request.id,
+        },
+      })),
+    );
+  }
+}
+```
+
+## Timeout Interceptor
+
+```typescript
+import { Injectable, RequestTimeoutException } from '@nestjs/common';
+import { Observable, throwError, TimeoutError } from 'rxjs';
+import { catchError, timeout } from 'rxjs/operators';
+
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  constructor(private readonly timeoutMs: number = 30000) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next.handle().pipe(
+      timeout(this.timeoutMs),
+      catchError((err) => {
+        if (err instanceof TimeoutError) {
+          return throwError(() => new RequestTimeoutException('Request timeout'));
+        }
+        return throwError(() => err);
+      }),
+    );
+  }
+}
+```
+
+## Caching Interceptor
+
+```typescript
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Cache } from 'cache-manager';
+
+@Injectable()
+export class HttpCacheInterceptor implements NestInterceptor {
+  constructor(@Inject(CACHE_MANAGER) private cacheManager: Cache) {}
+
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
+    const request = context.switchToHttp().getRequest();
+
+    // Only cache GET requests
+    if (request.method !== 'GET') {
+      return next.handle();
+    }
+
+    const cacheKey = `http:${request.url}`;
+    const cachedResponse = await this.cacheManager.get(cacheKey);
+
+    if (cachedResponse) {
+      return of(cachedResponse);
+    }
+
+    return next.handle().pipe(
+      tap(async (response) => {
+        await this.cacheManager.set(cacheKey, response, 60000); // 60s TTL
+      }),
+    );
+  }
+}
+```
+
+## Error Mapping Interceptor
+
+```typescript
+@Injectable()
+export class ErrorMappingInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next.handle().pipe(
+      catchError((error) => {
+        // Map domain errors to HTTP errors
+        if (error instanceof EntityNotFoundError) {
+          return throwError(() => new NotFoundException(error.message));
+        }
+        if (error instanceof ValidationError) {
+          return throwError(() => new BadRequestException(error.errors));
+        }
+        if (error instanceof UnauthorizedError) {
+          return throwError(() => new UnauthorizedException(error.message));
+        }
+
+        // Re-throw unknown errors
+        return throwError(() => error);
+      }),
+    );
+  }
+}
+```
+
+## Serialization Interceptor
+
+```typescript
+import { ClassSerializerInterceptor, PlainLiteralObject } from '@nestjs/common';
+import { ClassTransformOptions, plainToClass } from 'class-transformer';
+
+@Injectable()
+export class CustomSerializerInterceptor extends ClassSerializerInterceptor {
+  transformToPlain(
+    data: object,
+    options: ClassTransformOptions,
+  ): PlainLiteralObject | PlainLiteralObject[] {
+    // Add custom serialization logic
+    return super.transformToPlain(data, {
+      ...options,
+      excludeExtraneousValues: true, // Only @Expose() fields
+    });
+  }
+}
+
+// DTO with explicit exposure
+export class UserResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  email: string;
+
+  @Expose()
+  name: string;
+
+  @Exclude()
+  password: string; // Never exposed
+
+  @Expose()
+  @Transform(({ value }) => value.toISOString())
+  createdAt: Date;
+}
+```
+
+## Audit Log Interceptor
+
+```typescript
+@Injectable()
+export class AuditLogInterceptor implements NestInterceptor {
+  constructor(private readonly auditService: AuditService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const { method, url, user, body } = request;
+
+    // Only audit mutating operations
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      return next.handle().pipe(
+        tap({
+          next: (response) => {
+            this.auditService.log({
+              userId: user?.id,
+              action: method,
+              resource: url,
+              input: this.sanitize(body),
+              output: this.sanitize(response),
+              timestamp: new Date(),
+            });
+          },
+          error: (error) => {
+            this.auditService.log({
+              userId: user?.id,
+              action: method,
+              resource: url,
+              input: this.sanitize(body),
+              error: error.message,
+              timestamp: new Date(),
+            });
+          },
+        }),
+      );
+    }
+
+    return next.handle();
+  }
+
+  private sanitize(data: Record<string, unknown> | null): Record<string, unknown> | null {
+    if (!data) return data;
+    const { password, token, secret, ...safe } = data;
+    return safe;
+  }
+}
+```
+
+## Applying Interceptors
+
+```typescript
+// Global (main.ts)
+app.useGlobalInterceptors(new LoggingInterceptor());
+
+// Global with DI (module)
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: TransformInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+
+// Controller level
+@UseInterceptors(LoggingInterceptor)
+@Controller('users')
+export class UsersController {}
+
+// Method level
+@UseInterceptors(CacheInterceptor)
+@Get(':id')
+findOne(@Param('id') id: string) {}
+
+// Multiple interceptors (order matters: first to last)
+@UseInterceptors(LoggingInterceptor, TransformInterceptor)
+@Controller('users')
+export class UsersController {}
+```
+
+## Custom Decorator for Interceptors
+
+```typescript
+// Skip certain interceptors conditionally
+export const SKIP_TRANSFORM = 'skipTransform';
+export const SkipTransform = () => SetMetadata(SKIP_TRANSFORM, true);
+
+@Injectable()
+export class TransformInterceptor implements NestInterceptor {
+  constructor(private reflector: Reflector) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const skipTransform = this.reflector.get<boolean>(
+      SKIP_TRANSFORM,
+      context.getHandler(),
+    );
+
+    if (skipTransform) {
+      return next.handle();
+    }
+
+    return next.handle().pipe(map((data) => ({ data })));
+  }
+}
+
+// Usage
+@SkipTransform()
+@Get('raw')
+getRawData() {
+  return { raw: true };
+}
+```

package/configs/nestjs/.claude/rules/middleware.md

@@ -0,0 +1,321 @@
+---
+paths:
+  - "**/*.middleware.ts"
+  - "**/middleware/**/*.ts"
+---
+
+# NestJS Middleware
+
+## Functional Middleware
+
+```typescript
+// middleware/logger.middleware.ts
+import { Request, Response, NextFunction } from 'express';
+
+export function loggerMiddleware(req: Request, res: Response, next: NextFunction) {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    console.log(`${req.method} ${req.url} ${res.statusCode} - ${duration}ms`);
+  });
+
+  next();
+}
+
+// Apply in module
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(loggerMiddleware).forRoutes('*');
+  }
+}
+```
+
+## Class Middleware
+
+```typescript
+// middleware/auth.middleware.ts
+import { Injectable, NestMiddleware, UnauthorizedException } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { JwtService } from '@nestjs/jwt';
+
+@Injectable()
+export class AuthMiddleware implements NestMiddleware {
+  constructor(private readonly jwtService: JwtService) {}
+
+  async use(req: Request, res: Response, next: NextFunction) {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+      throw new UnauthorizedException('Missing token');
+    }
+
+    const token = authHeader.split(' ')[1];
+
+    try {
+      const payload = await this.jwtService.verifyAsync(token);
+      req['user'] = payload;
+      next();
+    } catch {
+      throw new UnauthorizedException('Invalid token');
+    }
+  }
+}
+```
+
+## Correlation ID Middleware
+
+```typescript
+// middleware/correlation-id.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'crypto';
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    const correlationId = req.headers['x-correlation-id'] as string || randomUUID();
+
+    req['correlationId'] = correlationId;
+    res.setHeader('x-correlation-id', correlationId);
+
+    next();
+  }
+}
+```
+
+## Request Validation Middleware
+
+```typescript
+// middleware/content-type.middleware.ts
+import { Injectable, NestMiddleware, UnsupportedMediaTypeException } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+
+@Injectable()
+export class JsonContentTypeMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+      const contentType = req.headers['content-type'];
+
+      if (!contentType?.includes('application/json')) {
+        throw new UnsupportedMediaTypeException('Content-Type must be application/json');
+      }
+    }
+
+    next();
+  }
+}
+```
+
+## Rate Limiting Middleware
+
+```typescript
+// middleware/rate-limit.middleware.ts
+import { Injectable, NestMiddleware, HttpException, HttpStatus } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { Redis } from 'ioredis';
+
+@Injectable()
+export class RateLimitMiddleware implements NestMiddleware {
+  private readonly windowMs = 60 * 1000; // 1 minute
+  private readonly maxRequests = 100;
+
+  constructor(private readonly redis: Redis) {}
+
+  async use(req: Request, res: Response, next: NextFunction) {
+    const key = `rate-limit:${req.ip}`;
+    const current = await this.redis.incr(key);
+
+    if (current === 1) {
+      await this.redis.pexpire(key, this.windowMs);
+    }
+
+    const remaining = Math.max(0, this.maxRequests - current);
+    const ttl = await this.redis.pttl(key);
+
+    res.setHeader('X-RateLimit-Limit', this.maxRequests);
+    res.setHeader('X-RateLimit-Remaining', remaining);
+    res.setHeader('X-RateLimit-Reset', Math.ceil(Date.now() / 1000 + ttl / 1000));
+
+    if (current > this.maxRequests) {
+      throw new HttpException('Too Many Requests', HttpStatus.TOO_MANY_REQUESTS);
+    }
+
+    next();
+  }
+}
+```
+
+## Request Sanitization Middleware
+
+```typescript
+// middleware/sanitize.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import * as sanitizeHtml from 'sanitize-html';
+
+@Injectable()
+export class SanitizeMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    if (req.body) {
+      req.body = this.sanitizeObject(req.body);
+    }
+
+    next();
+  }
+
+  private sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+    const sanitized: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+      if (typeof value === 'string') {
+        sanitized[key] = sanitizeHtml(value, {
+          allowedTags: [],
+          allowedAttributes: {},
+        });
+      } else if (typeof value === 'object' && value !== null) {
+        sanitized[key] = this.sanitizeObject(value as Record<string, unknown>);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+
+    return sanitized;
+  }
+}
+```
+
+## Applying Middleware
+
+```typescript
+// app.module.ts
+import { Module, NestModule, MiddlewareConsumer, RequestMethod } from '@nestjs/common';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Apply to all routes
+    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
+
+    // Apply to specific path
+    consumer.apply(AuthMiddleware).forRoutes('api/protected');
+
+    // Apply to specific controller
+    consumer.apply(LoggerMiddleware).forRoutes(UsersController);
+
+    // Apply with method filter
+    consumer
+      .apply(JsonContentTypeMiddleware)
+      .forRoutes({ path: '*', method: RequestMethod.POST });
+
+    // Exclude routes
+    consumer
+      .apply(AuthMiddleware)
+      .exclude(
+        { path: 'auth/login', method: RequestMethod.POST },
+        { path: 'auth/register', method: RequestMethod.POST },
+        { path: 'health', method: RequestMethod.GET },
+      )
+      .forRoutes('*');
+
+    // Chain multiple middleware
+    consumer
+      .apply(CorrelationIdMiddleware, LoggerMiddleware, AuthMiddleware)
+      .forRoutes('api');
+  }
+}
+```
+
+## Global Middleware (Express)
+
+```typescript
+// main.ts
+import * as helmet from 'helmet';
+import * as compression from 'compression';
+import * as cookieParser from 'cookie-parser';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Security headers
+  app.use(helmet());
+
+  // Compression
+  app.use(compression());
+
+  // Cookie parsing
+  app.use(cookieParser());
+
+  // CORS
+  app.enableCors({
+    origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
+    credentials: true,
+  });
+
+  // Body parsing limits
+  app.use(express.json({ limit: '10mb' }));
+  app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+  await app.listen(3000);
+}
+```
+
+## Middleware vs Guards vs Interceptors
+
+| Feature | Middleware | Guards | Interceptors |
+|---------|------------|--------|--------------|
+| Execution Order | First | After middleware | After guards |
+| Access to ExecutionContext | No | Yes | Yes |
+| Can transform response | No | No | Yes |
+| DI support | Class only | Yes | Yes |
+| Use case | Request processing | Authorization | Transform/logging |
+
+## Anti-patterns
+
+```typescript
+// BAD: Heavy operations in middleware
+@Injectable()
+export class HeavyMiddleware implements NestMiddleware {
+  async use(req: Request, res: Response, next: NextFunction) {
+    await this.db.query('SELECT * FROM logs'); // Blocks every request!
+    next();
+  }
+}
+
+// GOOD: Keep middleware lightweight
+
+// BAD: Not calling next()
+use(req: Request, res: Response, next: NextFunction) {
+  if (someCondition) {
+    return; // Request hangs!
+  }
+  next();
+}
+
+// GOOD: Always call next() or send response
+use(req: Request, res: Response, next: NextFunction) {
+  if (someCondition) {
+    res.status(400).json({ error: 'Bad request' });
+    return;
+  }
+  next();
+}
+
+// BAD: Modifying response after next()
+async use(req: Request, res: Response, next: NextFunction) {
+  next();
+  res.setHeader('X-Custom', 'value'); // May not work!
+}
+
+// GOOD: Modify before next() or use interceptor
+use(req: Request, res: Response, next: NextFunction) {
+  res.setHeader('X-Custom', 'value');
+  next();
+}
+
+// BAD: Using middleware for auth when guards exist
+// Middleware can't access ExecutionContext
+
+// GOOD: Use guards for authorization
+@UseGuards(AuthGuard)
+```

package/configs/nestjs/.claude/rules/modules.md

@@ -3,10 +3,36 @@ paths:
   - "src/**/*.module.ts"
   - "src/**/*.controller.ts"
   - "src/**/*.service.ts"
+  - "src/main.ts"
 ---
 
 # NestJS Module Architecture
 
+## Global Configuration (main.ts)
+
+### ValidationPipe Setup
+
+```typescript
+import { ValidationPipe } from '@nestjs/common';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,           // Strip non-whitelisted properties
+      forbidNonWhitelisted: true, // Throw error on extra properties
+      transform: true,            // Auto-transform payloads to DTO types
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+    }),
+  );
+
+  await app.listen(3000);
+}
+```
+
 ## Module Design
 
 ### Single Responsibility