@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/nestjs/.claude/rules/common-patterns.md

@@ -0,0 +1,300 @@
+---
+paths:
+  - "src/common/**/*.ts"
+  - "src/**/*.decorator.ts"
+  - "src/**/*.filter.ts"
+  - "src/**/*.interceptor.ts"
+  - "src/**/*.pipe.ts"
+  - "src/main.ts"
+---
+
+# NestJS Common Patterns
+
+## Global Setup (main.ts)
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Global validation pipe
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+    }),
+  );
+
+  // Global prefix
+  app.setGlobalPrefix('api/v1');
+
+  // CORS
+  app.enableCors({
+    origin: process.env.CORS_ORIGIN?.split(',') || '*',
+    credentials: true,
+  });
+
+  // Swagger (dev only)
+  if (process.env.NODE_ENV !== 'production') {
+    const config = new DocumentBuilder()
+      .setTitle('API')
+      .setVersion('1.0')
+      .addBearerAuth()
+      .build();
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('docs', app, document);
+  }
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+bootstrap();
+```
+
+## Custom Decorators
+
+### @CurrentUser Decorator
+
+```typescript
+// common/decorators/current-user.decorator.ts
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const CurrentUser = createParamDecorator(
+  (data: string | undefined, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const user = request.user;
+    return data ? user?.[data] : user;
+  },
+);
+
+// Usage
+@Get('profile')
+getProfile(@CurrentUser() user: User) {
+  return user;
+}
+
+@Get('email')
+getEmail(@CurrentUser('email') email: string) {
+  return { email };
+}
+```
+
+### @Public Decorator
+
+```typescript
+// common/decorators/public.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
+
+// Usage
+@Public()
+@Get('health')
+healthCheck() {
+  return { status: 'ok' };
+}
+```
+
+### @Roles Decorator
+
+```typescript
+// common/decorators/roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
+
+// Usage
+@Roles('admin')
+@Get('admin')
+adminOnly() { ... }
+```
+
+## Exception Filters
+
+### Global Exception Filter
+
+```typescript
+// common/filters/all-exceptions.filter.ts
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(AllExceptionsFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException
+        ? exception.message
+        : 'Internal server error';
+
+    // Log error
+    this.logger.error(
+      `${request.method} ${request.url} - ${status} - ${message}`,
+      exception instanceof Error ? exception.stack : undefined,
+    );
+
+    response.status(status).json({
+      statusCode: status,
+      message,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}
+
+// Register globally in main.ts
+app.useGlobalFilters(new AllExceptionsFilter());
+```
+
+## Interceptors
+
+### Transform Response Interceptor
+
+```typescript
+// common/interceptors/transform.interceptor.ts
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface Response<T> {
+  success: boolean;
+  data: T;
+}
+
+@Injectable()
+export class TransformInterceptor<T>
+  implements NestInterceptor<T, Response<T>>
+{
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<Response<T>> {
+    return next.handle().pipe(
+      map((data) => ({
+        success: true,
+        data,
+      })),
+    );
+  }
+}
+```
+
+### Logging Interceptor
+
+```typescript
+// common/interceptors/logging.interceptor.ts
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Logger,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(LoggingInterceptor.name);
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const { method, url } = request;
+    const now = Date.now();
+
+    return next.handle().pipe(
+      tap(() => {
+        this.logger.log(`${method} ${url} - ${Date.now() - now}ms`);
+      }),
+    );
+  }
+}
+```
+
+## Guards
+
+### Roles Guard
+
+```typescript
+// common/guards/roles.guard.ts
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredRoles) {
+      return true;
+    }
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+}
+```
+
+## Pipes
+
+### Parse Optional Int Pipe
+
+```typescript
+// common/pipes/parse-optional-int.pipe.ts
+import { PipeTransform, Injectable } from '@nestjs/common';
+
+@Injectable()
+export class ParseOptionalIntPipe implements PipeTransform {
+  transform(value: string | undefined): number | undefined {
+    if (value === undefined || value === '') {
+      return undefined;
+    }
+    const val = parseInt(value, 10);
+    return isNaN(val) ? undefined : val;
+  }
+}
+
+// Usage
+@Get()
+findAll(
+  @Query('page', ParseOptionalIntPipe) page?: number,
+  @Query('limit', ParseOptionalIntPipe) limit?: number,
+) { ... }
+```

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

@@ -0,0 +1,376 @@
+---
+paths:
+  - "**/*.filter.ts"
+  - "**/filters/**/*.ts"
+---
+
+# NestJS Exception Filters
+
+## Built-in Exceptions
+
+```typescript
+import {
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  ConflictException,
+  GoneException,
+  PayloadTooLargeException,
+  UnsupportedMediaTypeException,
+  UnprocessableEntityException,
+  InternalServerErrorException,
+  NotImplementedException,
+  BadGatewayException,
+  ServiceUnavailableException,
+  GatewayTimeoutException,
+} from '@nestjs/common';
+
+// Usage with message
+throw new NotFoundException('User not found');
+
+// Usage with object
+throw new BadRequestException({
+  message: 'Validation failed',
+  errors: [{ field: 'email', message: 'Invalid email format' }],
+});
+```
+
+## Global Exception Filter
+
+```typescript
+// filters/all-exceptions.filter.ts
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(AllExceptionsFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : 'Internal server error';
+
+    const errorResponse = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      method: request.method,
+      message: typeof message === 'string' ? message : (message as Record<string, unknown>).message,
+      ...(typeof message === 'object' && message !== null
+        ? { details: message }
+        : {}),
+    };
+
+    // Log error
+    this.logger.error(
+      `${request.method} ${request.url} ${status}`,
+      exception instanceof Error ? exception.stack : undefined,
+    );
+
+    response.status(status).json(errorResponse);
+  }
+}
+```
+
+## HTTP Exception Filter
+
+```typescript
+// filters/http-exception.filter.ts
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+    const status = exception.getStatus();
+    const exceptionResponse = exception.getResponse();
+
+    response.status(status).json({
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      ...(typeof exceptionResponse === 'object'
+        ? exceptionResponse
+        : { message: exceptionResponse }),
+    });
+  }
+}
+```
+
+## Custom Exception Classes
+
+```typescript
+// exceptions/business.exception.ts
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+export class BusinessException extends HttpException {
+  constructor(
+    public readonly code: string,
+    message: string,
+    status: HttpStatus = HttpStatus.BAD_REQUEST,
+  ) {
+    super({ code, message }, status);
+  }
+}
+
+// exceptions/domain-exceptions.ts
+export class UserNotFoundException extends BusinessException {
+  constructor(userId: string) {
+    super('USER_NOT_FOUND', `User with ID ${userId} not found`, HttpStatus.NOT_FOUND);
+  }
+}
+
+export class InsufficientCreditsException extends BusinessException {
+  constructor(required: number, available: number) {
+    super(
+      'INSUFFICIENT_CREDITS',
+      `Required ${required} credits but only ${available} available`,
+      HttpStatus.PAYMENT_REQUIRED,
+    );
+  }
+}
+
+export class DuplicateEmailException extends BusinessException {
+  constructor(email: string) {
+    super('DUPLICATE_EMAIL', `Email ${email} is already registered`, HttpStatus.CONFLICT);
+  }
+}
+```
+
+## Domain Exception Filter
+
+```typescript
+// filters/business-exception.filter.ts
+import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
+import { Response } from 'express';
+import { BusinessException } from '../exceptions/business.exception';
+
+@Catch(BusinessException)
+export class BusinessExceptionFilter implements ExceptionFilter {
+  catch(exception: BusinessException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const status = exception.getStatus();
+
+    response.status(status).json({
+      type: `https://api.example.com/errors/${exception.code}`,
+      title: exception.code.replace(/_/g, ' ').toLowerCase(),
+      status,
+      detail: exception.message,
+    });
+  }
+}
+```
+
+## Database Exception Filter
+
+```typescript
+// filters/prisma-exception.filter.ts
+import { ExceptionFilter, Catch, ArgumentsHost, HttpStatus } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { Response } from 'express';
+
+@Catch(Prisma.PrismaClientKnownRequestError)
+export class PrismaExceptionFilter implements ExceptionFilter {
+  catch(exception: Prisma.PrismaClientKnownRequestError, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    switch (exception.code) {
+      case 'P2002': // Unique constraint violation
+        const field = (exception.meta?.target as string[])?.[0] || 'field';
+        response.status(HttpStatus.CONFLICT).json({
+          statusCode: HttpStatus.CONFLICT,
+          message: `Duplicate value for ${field}`,
+          error: 'Conflict',
+        });
+        break;
+
+      case 'P2025': // Record not found
+        response.status(HttpStatus.NOT_FOUND).json({
+          statusCode: HttpStatus.NOT_FOUND,
+          message: 'Record not found',
+          error: 'Not Found',
+        });
+        break;
+
+      case 'P2003': // Foreign key constraint
+        response.status(HttpStatus.BAD_REQUEST).json({
+          statusCode: HttpStatus.BAD_REQUEST,
+          message: 'Related record not found',
+          error: 'Bad Request',
+        });
+        break;
+
+      default:
+        response.status(HttpStatus.INTERNAL_SERVER_ERROR).json({
+          statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+          message: 'Database error',
+          error: 'Internal Server Error',
+        });
+    }
+  }
+}
+```
+
+## Validation Exception Filter
+
+```typescript
+// filters/validation-exception.filter.ts
+import { ExceptionFilter, Catch, ArgumentsHost, BadRequestException } from '@nestjs/common';
+import { Response } from 'express';
+
+@Catch(BadRequestException)
+export class ValidationExceptionFilter implements ExceptionFilter {
+  catch(exception: BadRequestException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const exceptionResponse = exception.getResponse() as Record<string, unknown>;
+
+    // Handle class-validator errors
+    if (exceptionResponse.message && Array.isArray(exceptionResponse.message)) {
+      response.status(400).json({
+        statusCode: 400,
+        error: 'Validation Error',
+        message: 'Request validation failed',
+        details: exceptionResponse.message.map((msg: string) => {
+          const [field, ...rest] = msg.split(' ');
+          return { field, message: rest.join(' ') };
+        }),
+      });
+      return;
+    }
+
+    response.status(400).json(exceptionResponse);
+  }
+}
+```
+
+## Filter Binding
+
+```typescript
+// Method level
+@Post()
+@UseFilters(HttpExceptionFilter)
+create(@Body() dto: CreateDto) {}
+
+// Controller level
+@Controller('users')
+@UseFilters(AllExceptionsFilter)
+export class UsersController {}
+
+// Global level (main.ts)
+app.useGlobalFilters(new AllExceptionsFilter());
+
+// Global with DI
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: AllExceptionsFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Filter Order
+
+```typescript
+// Filters are applied in reverse order (last registered = first executed)
+@UseFilters(
+  AllExceptionsFilter,      // Fallback (executed last)
+  HttpExceptionFilter,      // HTTP exceptions
+  BusinessExceptionFilter,  // Business exceptions (executed first)
+)
+export class AppController {}
+```
+
+## WebSocket Exception Filter
+
+```typescript
+// filters/ws-exception.filter.ts
+import { Catch, ArgumentsHost } from '@nestjs/common';
+import { BaseWsExceptionFilter, WsException } from '@nestjs/websockets';
+
+@Catch()
+export class WsExceptionsFilter extends BaseWsExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const client = host.switchToWs().getClient();
+
+    const error =
+      exception instanceof WsException
+        ? exception.getError()
+        : { message: 'Internal error' };
+
+    client.emit('error', {
+      event: 'error',
+      data: error,
+    });
+  }
+}
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Swallowing errors without logging
+@Catch()
+export class SilentFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse();
+    response.status(500).json({ error: 'Error' }); // No logging!
+  }
+}
+
+// GOOD: Always log errors
+this.logger.error(exception);
+
+// BAD: Exposing internal details
+catch(exception: Error, host: ArgumentsHost) {
+  response.json({
+    stack: exception.stack,    // Security risk!
+    query: request.query,      // Leaking data!
+  });
+}
+
+// GOOD: Sanitize response
+response.json({
+  statusCode: 500,
+  message: 'Internal server error',
+});
+
+// BAD: Not handling specific exceptions
+@Catch()
+export class GenericFilter {}  // Catches everything the same way
+
+// GOOD: Layer filters by specificity
+@UseFilters(AllExceptionsFilter, HttpExceptionFilter, BusinessExceptionFilter)
+```