cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skill-library/stack/frameworks/nestjs/SKILL.md

@@ -0,0 +1,878 @@
+---
+name: nestjs
+description: Build scalable server-side applications with NestJS including modules, controllers, providers, dependency injection, guards, interceptors, pipes, and testing. Use when developing structured Node.js backends with TypeScript, REST/GraphQL APIs, WebSocket servers, or microservices.
+version: 1.0.0
+---
+
+# NestJS
+
+Build scalable, maintainable server-side applications with NestJS. NestJS is a TypeScript-first Node.js framework that uses decorators, dependency injection, and a modular architecture inspired by Angular.
+
+## When to Use This Skill
+
+- Building structured REST or GraphQL APIs
+- Implementing microservice architectures
+- Creating WebSocket servers
+- Developing applications that need dependency injection and modular organization
+- Building enterprise-grade Node.js backends with strong typing
+
+## Project Structure
+
+```
+src/
+  app.module.ts              # Root module
+  main.ts                    # Entry point
+  common/
+    decorators/              # Custom decorators
+    filters/                 # Exception filters
+    guards/                  # Auth and role guards
+    interceptors/            # Request/response interceptors
+    pipes/                   # Validation pipes
+    middleware/              # HTTP middleware
+  modules/
+    users/
+      users.module.ts
+      users.controller.ts
+      users.service.ts
+      users.repository.ts
+      dto/
+        create-user.dto.ts
+        update-user.dto.ts
+      entities/
+        user.entity.ts
+      users.controller.spec.ts
+      users.service.spec.ts
+    auth/
+      auth.module.ts
+      auth.controller.ts
+      auth.service.ts
+      auth.guard.ts
+      strategies/
+        jwt.strategy.ts
+        local.strategy.ts
+test/
+  app.e2e-spec.ts
+```
+
+## Setup
+
+```bash
+# Create new project
+npx @nestjs/cli new project-name
+
+# Or add NestJS to existing project
+pnpm add @nestjs/core @nestjs/common @nestjs/platform-express reflect-metadata
+```
+
+### Entry Point
+
+```typescript
+// src/main.ts
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe, VersioningType } from '@nestjs/common';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import helmet from 'helmet';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, {
+    logger: ['error', 'warn', 'log'],
+  });
+
+  // Security
+  app.use(helmet());
+  app.enableCors({
+    origin: process.env.CLIENT_URL,
+    credentials: true,
+  });
+
+  // Global validation pipe
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,          // Strip unknown properties
+      forbidNonWhitelisted: true, // Throw on unknown properties
+      transform: true,          // Auto-transform payloads to DTO instances
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+    }),
+  );
+
+  // API versioning
+  app.enableVersioning({
+    type: VersioningType.URI,
+    defaultVersion: '1',
+  });
+
+  // Swagger / OpenAPI
+  const config = new DocumentBuilder()
+    .setTitle('API')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api/docs', app, document);
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+
+bootstrap();
+```
+
+## Modules
+
+Modules organize the application into cohesive blocks.
+
+```typescript
+// src/modules/users/users.module.ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+import { UsersRepository } from './users.repository';
+import { User } from './entities/user.entity';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService, UsersRepository],
+  exports: [UsersService], // Available to other modules that import UsersModule
+})
+export class UsersModule {}
+```
+
+```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { UsersModule } from './modules/users/users.module';
+import { AuthModule } from './modules/auth/auth.module';
+import { PostsModule } from './modules/posts/posts.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: `.env.${process.env.NODE_ENV ?? 'development'}`,
+    }),
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        type: 'postgres',
+        host: config.get('DB_HOST'),
+        port: config.get('DB_PORT'),
+        username: config.get('DB_USER'),
+        password: config.get('DB_PASSWORD'),
+        database: config.get('DB_NAME'),
+        autoLoadEntities: true,
+        synchronize: config.get('NODE_ENV') === 'development',
+      }),
+    }),
+    UsersModule,
+    AuthModule,
+    PostsModule,
+  ],
+})
+export class AppModule {}
+```
+
+## Controllers
+
+Controllers handle incoming requests and return responses.
+
+```typescript
+// src/modules/users/users.controller.ts
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Param,
+  Body,
+  Query,
+  HttpCode,
+  HttpStatus,
+  ParseUUIDPipe,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth, ApiResponse } from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { ListUsersQueryDto } from './dto/list-users-query.dto';
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { RolesGuard } from '../../common/guards/roles.guard';
+import { Roles } from '../../common/decorators/roles.decorator';
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+
+@ApiTags('Users')
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({ status: 201, description: 'User created' })
+  @ApiResponse({ status: 422, description: 'Validation failed' })
+  async create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'List all users' })
+  async findAll(@Query() query: ListUsersQueryDto) {
+    return this.usersService.findAll(query);
+  }
+
+  @Get(':id')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async findOne(@Param('id', ParseUUIDPipe) id: string) {
+    return this.usersService.findOneOrFail(id);
+  }
+
+  @Put(':id')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  async update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() updateUserDto: UpdateUserDto,
+    @CurrentUser() currentUser: UserPayload,
+  ) {
+    return this.usersService.update(id, updateUserDto, currentUser);
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @UseGuards(JwtAuthGuard, RolesGuard)
+  @Roles('admin')
+  @ApiBearerAuth()
+  async remove(@Param('id', ParseUUIDPipe) id: string) {
+    await this.usersService.remove(id);
+  }
+}
+```
+
+## DTOs (Data Transfer Objects)
+
+```typescript
+// src/modules/users/dto/create-user.dto.ts
+import { IsString, IsEmail, MinLength, MaxLength, IsOptional, IsEnum } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({ example: 'John Doe' })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(100)
+  name: string;
+
+  @ApiProperty({ example: 'john@example.com' })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({ minLength: 8 })
+  @IsString()
+  @MinLength(8)
+  @MaxLength(128)
+  password: string;
+
+  @ApiPropertyOptional({ enum: ['user', 'admin'], default: 'user' })
+  @IsOptional()
+  @IsEnum(['user', 'admin'])
+  role?: 'user' | 'admin';
+}
+```
+
+```typescript
+// src/modules/users/dto/update-user.dto.ts
+import { PartialType, OmitType } from '@nestjs/swagger';
+import { CreateUserDto } from './create-user.dto';
+
+// All fields from CreateUserDto become optional, password excluded
+export class UpdateUserDto extends PartialType(OmitType(CreateUserDto, ['password'] as const)) {}
+```
+
+```typescript
+// src/modules/users/dto/list-users-query.dto.ts
+import { IsOptional, IsInt, Min, Max, IsEnum } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class ListUsersQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  @IsOptional()
+  @IsEnum(['user', 'admin'])
+  role?: 'user' | 'admin';
+}
+```
+
+## Providers (Services)
+
+```typescript
+// src/modules/users/users.service.ts
+import { Injectable, NotFoundException, ConflictException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { User } from './entities/user.entity';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { ListUsersQueryDto } from './dto/list-users-query.dto';
+import * as bcrypt from 'bcrypt';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User)
+    private readonly userRepo: Repository<User>,
+  ) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const existing = await this.userRepo.findOne({ where: { email: dto.email } });
+    if (existing) {
+      throw new ConflictException('Email already registered');
+    }
+
+    const hashedPassword = await bcrypt.hash(dto.password, 12);
+    const user = this.userRepo.create({
+      ...dto,
+      password: hashedPassword,
+    });
+
+    return this.userRepo.save(user);
+  }
+
+  async findAll(query: ListUsersQueryDto) {
+    const { page = 1, limit = 20, role } = query;
+    const where = role ? { role } : {};
+
+    const [data, total] = await this.userRepo.findAndCount({
+      where,
+      skip: (page - 1) * limit,
+      take: limit,
+      order: { createdAt: 'DESC' },
+      select: ['id', 'name', 'email', 'role', 'createdAt'], // Never return password
+    });
+
+    return { data, total, page, limit, totalPages: Math.ceil(total / limit) };
+  }
+
+  async findOneOrFail(id: string): Promise<User> {
+    const user = await this.userRepo.findOne({ where: { id } });
+    if (!user) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+    return user;
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.userRepo.findOne({ where: { email } });
+  }
+
+  async update(id: string, dto: UpdateUserDto, currentUser: UserPayload): Promise<User> {
+    const user = await this.findOneOrFail(id);
+
+    if (currentUser.id !== id && currentUser.role !== 'admin') {
+      throw new ForbiddenException('Cannot update another user');
+    }
+
+    Object.assign(user, dto);
+    return this.userRepo.save(user);
+  }
+
+  async remove(id: string): Promise<void> {
+    const result = await this.userRepo.delete(id);
+    if (result.affected === 0) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+  }
+}
+```
+
+## Guards
+
+Guards determine whether a request should be handled.
+
+```typescript
+// src/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.includes(user.role);
+  }
+}
+```
+
+```typescript
+// JWT Auth Guard
+// src/modules/auth/jwt-auth.guard.ts
+import { Injectable, ExecutionContext, UnauthorizedException } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  handleRequest(err: any, user: any) {
+    if (err || !user) {
+      throw new UnauthorizedException('Invalid or expired token');
+    }
+    return user;
+  }
+}
+```
+
+## Interceptors
+
+Interceptors transform the result or handle cross-cutting concerns.
+
+```typescript
+// src/common/interceptors/transform.interceptor.ts
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable, map } from 'rxjs';
+
+export interface ApiResponse<T> {
+  data: T;
+  statusCode: number;
+  timestamp: string;
+}
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<ApiResponse<T>> {
+    const statusCode = context.switchToHttp().getResponse().statusCode;
+
+    return next.handle().pipe(
+      map((data) => ({
+        data,
+        statusCode,
+        timestamp: new Date().toISOString(),
+      })),
+    );
+  }
+}
+```
+
+```typescript
+// src/common/interceptors/logging.interceptor.ts
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly logger = new Logger('HTTP');
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const req = context.switchToHttp().getRequest();
+    const { method, url } = req;
+    const start = Date.now();
+
+    return next.handle().pipe(
+      tap(() => {
+        const elapsed = Date.now() - start;
+        this.logger.log(`${method} ${url} ${elapsed}ms`);
+      }),
+    );
+  }
+}
+```
+
+## Pipes
+
+Pipes transform or validate input data.
+
+```typescript
+// src/common/pipes/parse-optional-int.pipe.ts
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+
+@Injectable()
+export class ParseOptionalIntPipe implements PipeTransform<string | undefined, number | undefined> {
+  transform(value: string | undefined): number | undefined {
+    if (value === undefined || value === null || value === '') {
+      return undefined;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+      throw new BadRequestException(`"${value}" is not a valid integer`);
+    }
+    return parsed;
+  }
+}
+```
+
+## Exception Filters
+
+```typescript
+// src/common/filters/all-exceptions.filter.ts
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger('ExceptionFilter');
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : 'Internal server error';
+
+    // Log internal errors with stack trace
+    if (status >= 500) {
+      this.logger.error(
+        `${request.method} ${request.url} ${status}`,
+        exception instanceof Error ? exception.stack : undefined,
+      );
+    }
+
+    response.status(status).json({
+      statusCode: status,
+      message: typeof message === 'string' ? message : (message as any).message,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}
+```
+
+## Custom Decorators
+
+```typescript
+// src/common/decorators/roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
+```
+
+```typescript
+// src/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: @CurrentUser() user: UserPayload
+// Usage: @CurrentUser('id') userId: string
+```
+
+## Middleware
+
+```typescript
+// src/common/middleware/request-id.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'node:crypto';
+
+@Injectable()
+export class RequestIdMiddleware implements NestMiddleware {
+  use(req: Request, _res: Response, next: NextFunction) {
+    req.headers['x-request-id'] = req.headers['x-request-id'] ?? randomUUID();
+    next();
+  }
+}
+
+// Register in module
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RequestIdMiddleware).forRoutes('*');
+  }
+}
+```
+
+## Database Integration (TypeORM)
+
+```typescript
+// src/modules/users/entities/user.entity.ts
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  OneToMany,
+  Index,
+} from 'typeorm';
+import { Exclude } from 'class-transformer';
+
+@Entity('users')
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ length: 100 })
+  name: string;
+
+  @Index({ unique: true })
+  @Column({ length: 255 })
+  email: string;
+
+  @Column()
+  @Exclude() // Never serialize password
+  password: string;
+
+  @Column({ type: 'enum', enum: ['user', 'admin'], default: 'user' })
+  role: 'user' | 'admin';
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @OneToMany(() => Post, (post) => post.author)
+  posts: Post[];
+}
+```
+
+## Database Integration (Prisma)
+
+```typescript
+// src/prisma/prisma.service.ts
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  async onModuleInit() {
+    await this.$connect();
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+  }
+}
+
+// src/prisma/prisma.module.ts
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}
+
+// Usage in service
+@Injectable()
+export class UsersService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findAll() {
+    return this.prisma.user.findMany();
+  }
+}
+```
+
+## OpenAPI Generation
+
+```typescript
+// Swagger decorators on controllers
+@ApiTags('Users')
+@ApiBearerAuth()
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiOperation({ summary: 'Create user' })
+  @ApiBody({ type: CreateUserDto })
+  @ApiResponse({ status: 201, description: 'User created', type: UserResponseDto })
+  @ApiResponse({ status: 409, description: 'Email already exists' })
+  @ApiResponse({ status: 422, description: 'Validation failed' })
+  create(@Body() dto: CreateUserDto) { /* ... */ }
+}
+
+// Generate OpenAPI spec as JSON
+// Available at: GET /api/docs-json
+// Swagger UI at: GET /api/docs
+```
+
+## Testing
+
+### Unit Test (Service)
+
+```typescript
+// src/modules/users/users.service.spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { UsersService } from './users.service';
+import { User } from './entities/user.entity';
+import { NotFoundException, ConflictException } from '@nestjs/common';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repo: jest.Mocked<Repository<User>>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: getRepositoryToken(User),
+          useValue: {
+            findOne: jest.fn(),
+            findAndCount: jest.fn(),
+            create: jest.fn(),
+            save: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get(UsersService);
+    repo = module.get(getRepositoryToken(User));
+  });
+
+  describe('findOneOrFail', () => {
+    it('returns user when found', async () => {
+      const user = { id: '1', name: 'John', email: 'john@test.com' } as User;
+      repo.findOne.mockResolvedValue(user);
+
+      const result = await service.findOneOrFail('1');
+      expect(result).toEqual(user);
+    });
+
+    it('throws NotFoundException when user does not exist', async () => {
+      repo.findOne.mockResolvedValue(null);
+
+      await expect(service.findOneOrFail('999')).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe('create', () => {
+    it('throws ConflictException when email exists', async () => {
+      repo.findOne.mockResolvedValue({ id: '1' } as User);
+
+      await expect(
+        service.create({ name: 'Test', email: 'exists@test.com', password: 'password123' }),
+      ).rejects.toThrow(ConflictException);
+    });
+  });
+});
+```
+
+### E2E Test
+
+```typescript
+// test/users.e2e-spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from '../src/app.module';
+
+describe('Users (e2e)', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
+    await app.init();
+
+    // Get auth token
+    const loginRes = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'admin@test.com', password: 'password' });
+    authToken = loginRes.body.access_token;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('POST /users - creates a user', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/users')
+      .send({ name: 'New User', email: 'new@test.com', password: 'password123' })
+      .expect(201);
+
+    expect(res.body).toHaveProperty('id');
+    expect(res.body.email).toBe('new@test.com');
+    expect(res.body).not.toHaveProperty('password');
+  });
+
+  it('GET /users - requires authentication', async () => {
+    await request(app.getHttpServer()).get('/users').expect(401);
+  });
+
+  it('GET /users - returns paginated users', async () => {
+    const res = await request(app.getHttpServer())
+      .get('/users?page=1&limit=10')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(200);
+
+    expect(res.body).toHaveProperty('data');
+    expect(res.body).toHaveProperty('total');
+    expect(Array.isArray(res.body.data)).toBe(true);
+  });
+});
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Injecting `Repository` directly into controllers | Controllers call services, services use repositories |
+| Using `any` types for request/response | Define DTOs with class-validator decorators |
+| Putting business logic in controllers | Controllers handle HTTP; services contain logic |
+| Not using `ValidationPipe` globally | Set it in `main.ts` to validate all incoming DTOs |
+| Creating circular module dependencies | Extract shared logic into a common module |
+| Not using `@Exclude()` on sensitive entity fields | Password, tokens, internal IDs should never be serialized |
+| Catching all exceptions in controllers | Use exception filters for centralized error handling |
+| Using `@Res()` decorator (bypasses interceptors) | Return values from handlers; NestJS serializes them |
+| Not splitting large modules | One module per bounded context / domain area |
+| Hardcoding config values | Use `ConfigModule` and `ConfigService` for all environment values |