@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/nestjs/CLAUDE.md

@@ -4,260 +4,102 @@
 
 ## Stack
 
-- NestJS 10+ (latest stable)
+- NestJS 11+
 - TypeScript strict mode
 - Node.js 20+
-- Jest for testing
-- Supertest for E2E
+- Vitest + Supertest
+- Prisma or TypeORM
 
-## Architecture
-
-### Modular Monolith (Recommended)
+## Architecture - Modular Monolith
 
 ```
 src/
 ├── modules/
-│   ├── users/
-│   │   ├── users.module.ts
-│   │   ├── users.controller.ts
-│   │   ├── users.service.ts
+│   ├── [feature]/
+│   │   ├── [feature].module.ts
+│   │   ├── [feature].controller.ts
+│   │   ├── [feature].service.ts
+│   │   ├── [feature].repository.ts
 │   │   ├── dto/
-│   │   │   ├── create-user.dto.ts
-│   │   │   └── update-user.dto.ts
-│   │   ├── entities/
-│   │   │   └── user.entity.ts
-│   │   └── users.repository.ts
-│   │
-│   ├── auth/
-│   │   ├── auth.module.ts
-│   │   ├── auth.controller.ts
-│   │   ├── auth.service.ts
-│   │   ├── strategies/
-│   │   │   ├── jwt.strategy.ts
-│   │   │   └── local.strategy.ts
-│   │   └── guards/
-│   │       └── jwt-auth.guard.ts
-│   │
-│   └── [feature]/
-│       └── ...
-│
+│   │   └── entities/
+│   └── auth/
+│       ├── strategies/
+│       └── guards/
 ├── common/
 │   ├── decorators/
 │   ├── filters/
 │   ├── guards/
 │   ├── interceptors/
 │   └── pipes/
-│
 ├── config/
-│   ├── config.module.ts
-│   └── database.config.ts
-│
 ├── app.module.ts
 └── main.ts
 ```
 
-### Module Principles
-
-- **Single Responsibility**: Each module owns one domain
-- **Clear Boundaries**: Modules communicate via exported services
-- **In-Memory Communication**: Direct method calls, not HTTP between modules
-- **Barrel Exports**: Use `index.ts` for clean imports
+## Request Lifecycle
 
-## Code Style
+```
+Request → Middleware → Guard → Interceptor (pre) → Pipe → Controller → Interceptor (post) → Response
+```
 
-### Controllers
+## Core Principles
 
-- Handle HTTP concerns only (request/response)
-- Delegate business logic to services
-- Use DTOs for all inputs
-- Return consistent response shapes
+### Module Design
 
-```typescript
-@Controller('users')
-export class UsersController {
-  constructor(private readonly usersService: UsersService) {}
+- **Single Responsibility**: One module = one domain
+- **Clear Boundaries**: Communicate via exported services only
+- **Barrel Exports**: Use `index.ts` for clean imports
 
-  @Post()
-  @HttpCode(HttpStatus.CREATED)
-  create(@Body() createUserDto: CreateUserDto): Promise<User> {
-    return this.usersService.create(createUserDto);
-  }
+### Layer Responsibilities
 
-  @Get(':id')
-  findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-    return this.usersService.findOne(id);
-  }
-}
-```
+| Layer | Responsibility |
+|-------|---------------|
+| Controller | HTTP only, delegates to service |
+| Service | All business logic |
+| Repository | Data access only |
+| DTO | Validation with class-validator |
 
-### Services
+### Exception Handling
 
-- Contain all business logic
-- Inject repositories/other services
-- Throw appropriate NestJS exceptions
+Use built-in NestJS exceptions:
+- `NotFoundException` - 404
+- `BadRequestException` - 400
+- `UnauthorizedException` - 401
+- `ForbiddenException` - 403
+- `ConflictException` - 409
 
-```typescript
-@Injectable()
-export class UsersService {
-  constructor(private readonly usersRepository: UsersRepository) {}
+### Validation (Global)
 
-  async findOne(id: string): Promise<User> {
-    const user = await this.usersRepository.findById(id);
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-    return user;
-  }
-}
-```
+Enable global `ValidationPipe` in main.ts with:
+- `whitelist: true` - Strip non-whitelisted properties
+- `forbidNonWhitelisted: true` - Throw on extra properties
+- `transform: true` - Auto-transform to DTO types
 
 ### DTOs
 
 - Always use class-validator decorators
-- Use class-transformer for transformation
-- Extend with PartialType/PickType/OmitType for variants
+- `PartialType`, `PickType`, `OmitType` for variants
+- Combine with Swagger decorators
 
-```typescript
-export class CreateUserDto {
-  @IsEmail()
-  @IsNotEmpty()
-  email: string;
+## Authentication
 
-  @IsString()
-  @MinLength(8)
-  password: string;
-
-  @IsString()
-  @IsOptional()
-  name?: string;
-}
-
-export class UpdateUserDto extends PartialType(CreateUserDto) {}
-```
+- Passport.js + JWT strategy
+- Global `JwtAuthGuard` with `@Public()` decorator for exceptions
+- `@CurrentUser()` decorator for accessing user
 
 ## Commands
 
 ```bash
-# Development
-npm run start:dev
-
-# Build
-npm run build
-
-# Tests
-npm run test              # Unit tests
-npm run test:watch        # Watch mode
-npm run test:cov          # Coverage
-npm run test:e2e          # E2E tests
-
-# Linting
-npm run lint
-npm run format
-```
-
-## Global Setup (main.ts)
-
-```typescript
-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();
-
-  // 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);
-}
-```
-
-## Common Patterns
-
-### Custom Decorator
-
-```typescript
-// current-user.decorator.ts
-export const CurrentUser = createParamDecorator(
-  (data: keyof User | undefined, ctx: ExecutionContext) => {
-    const request = ctx.switchToHttp().getRequest();
-    const user = request.user;
-    return data ? user?.[data] : user;
-  },
-);
-
-// Usage
-@Get('profile')
-getProfile(@CurrentUser() user: User) { ... }
+npm run start:dev       # Dev with watch
+npm run build           # Production build
+npm run test            # Unit tests
+npm run test:e2e        # E2E tests
+npm run test:cov        # Coverage
 ```
 
-### Global Exception Filter
-
-```typescript
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const message =
-      exception instanceof HttpException
-        ? exception.message
-        : 'Internal server error';
-
-    response.status(status).json({
-      statusCode: status,
-      message,
-      timestamp: new Date().toISOString(),
-    });
-  }
-}
-```
-
-### Response Interceptor
+## Code Style
 
-```typescript
-@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,
-      })),
-    );
-  }
-}
-```
+- Constructor injection (not property injection)
+- `readonly` for injected dependencies
+- Async methods return `Promise<T>`
+- Use `ParseUUIDPipe`, `ParseIntPipe` for params

package/configs/nestjs/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,
+) { ... }
+```