@dewtech/dare-cli 3.3.0 → 3.5.0

package/templates/ide/cursor/.cursor/rules/skill-nestjs-api.mdc

@@ -1,346 +1,346 @@
----
-description: Padrões DARE para APIs REST em NestJS + TypeScript + Prisma + Swagger. Modules, Controllers, Services, DTOs com class-validator, Guards JWT, throttler, exceções globais, Jest + Supertest, OpenAPI auto-gerado.
-globs: src/**/*.ts,src/**/*.controller.ts,src/**/*.service.ts,src/**/*.module.ts,prisma/schema.prisma
-alwaysApply: false
----
-
-# Skill: NestJS API DARE
-
-Você é um desenvolvedor sênior TypeScript / NestJS focado em APIs REST. Esta skill garante código **idiomático Nest, fortemente tipado, com auth/autz robustos e OpenAPI auto-gerado**, seguindo Layered Design DARE.
-
-## Stack canônica
-
-- **TypeScript 5.5+** com `strict: true`
-- **NestJS 11.x**
-- **Prisma 5.x** ORM (PostgreSQL ou MySQL)
-- **class-validator + class-transformer**
-- **@nestjs/swagger**
-- **@nestjs/throttler**
-- **@nestjs/passport + @nestjs/jwt**
-- **Jest + Supertest**
-
----
-
-## Estrutura de módulo (Layered Design)
-
-```
-src/<feature>/
-├── <feature>.module.ts          ← providers + controllers
-├── <feature>.controller.ts      ← Handler
-├── <feature>.service.ts         ← Service (1 operação ou facade)
-├── <feature>.repository.ts      ← Repository (Prisma)
-├── dto/
-│   ├── create-<feature>.dto.ts
-│   └── update-<feature>.dto.ts
-├── entities/
-│   └── <feature>.entity.ts      ← Model
-└── tests/
-    ├── <feature>.service.spec.ts
-    └── <feature>.e2e-spec.ts
-```
-
----
-
-## Controllers (Handler)
-
-```typescript
-import { Body, Controller, Post, UseGuards } from '@nestjs/common';
-import { ApiTags, ApiOperation, ApiCreatedResponse } from '@nestjs/swagger';
-import { JwtAuthGuard } from '@/auth/jwt-auth.guard';
-import { CreateUserDto } from './dto/create-user.dto';
-import { UserResponseDto } from './dto/user-response.dto';
-import { RegisterUserService } from './register-user.service';
-
-@ApiTags('users')
-@Controller('users')
-@UseGuards(JwtAuthGuard)
-export class UsersController {
-  constructor(private readonly register: RegisterUserService) {}
-
-  @Post()
-  @ApiOperation({ summary: 'Criar novo usuário' })
-  @ApiCreatedResponse({ type: UserResponseDto })
-  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
-    const user = await this.register.execute(dto);
-    return UserResponseDto.from(user);
-  }
-}
-```
-
-Regras:
-- Apenas: recebe → valida via DTO → chama Service → retorna ResponseDto
-- NUNCA: Prisma direto, lógica de negócio, validação inline
-
----
-
-## DTOs com class-validator
-
-```typescript
-import { IsEmail, IsString, MinLength } from 'class-validator';
-import { ApiProperty } from '@nestjs/swagger';
-
-export class CreateUserDto {
-  @ApiProperty({ example: 'jane@example.com' })
-  @IsEmail() email!: string;
-
-  @ApiProperty({ example: 'Jane Doe' })
-  @IsString() name!: string;
-
-  @ApiProperty({ minLength: 12 })
-  @IsString() @MinLength(12) password!: string;
-}
-```
-
-`main.ts` global pipe:
-```typescript
-app.useGlobalPipes(new ValidationPipe({
-  whitelist: true,
-  forbidNonWhitelisted: true,
-  transform: true,
-}));
-```
-
----
-
-## Services
-
-Uma operação por classe:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { hash } from '@node-rs/argon2';
-import { UsersRepository } from './users.repository';
-import { CreateUserDto } from './dto/create-user.dto';
-import { UserAlreadyExistsError } from './errors';
-
-@Injectable()
-export class RegisterUserService {
-  constructor(private readonly repo: UsersRepository) {}
-
-  async execute(dto: CreateUserDto) {
-    if (await this.repo.existsByEmail(dto.email)) {
-      throw new UserAlreadyExistsError();
-    }
-    return this.repo.create({
-      ...dto,
-      password: await hash(dto.password),
-    });
-  }
-}
-```
-
----
-
-## Repositories (Prisma)
-
-```typescript
-@Injectable()
-export class UsersRepository {
-  constructor(private readonly prisma: PrismaService) {}
-
-  async existsByEmail(email: string): Promise<boolean> {
-    return !!(await this.prisma.user.findUnique({ where: { email } }));
-  }
-
-  async create(data: { email: string; name: string; password: string }) {
-    return this.prisma.user.create({ data });
-  }
-}
-```
-
----
-
-## Tratamento global de exceções
-
-```typescript
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    const response = host.switchToHttp().getResponse<Response>();
-
-    if (exception instanceof UserAlreadyExistsError) {
-      return response.status(409).json({ error: 'USER_EXISTS' });
-    }
-    if (exception instanceof HttpException) {
-      return response.status(exception.getStatus()).json(exception.getResponse());
-    }
-    return response.status(500).json({ error: 'INTERNAL' });
-  }
-}
-
-// main.ts
-app.useGlobalFilters(new AllExceptionsFilter());
-```
-
----
-
-## OpenAPI auto-gerado
-
-```typescript
-const config = new DocumentBuilder()
-  .setTitle('Projeto API')
-  .setVersion('1.0')
-  .addBearerAuth()
-  .build();
-
-const document = SwaggerModule.createDocument(app, config);
-SwaggerModule.setup('docs', app, document);          // UI em /docs
-writeFileSync('./public/openapi.json', JSON.stringify(document));
-```
-
----
-
-## Rate limiting
-
-```typescript
-import { ThrottlerModule, Throttle } from '@nestjs/throttler';
-
-@Module({
-  imports: [
-    ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]),
-  ],
-})
-export class AppModule {}
-
-// Endpoint sensível
-@Throttle({ default: { limit: 5, ttl: 900_000 } })  // 5/15min
-@Post('login')
-async login() {...}
-```
-
----
-
-## Auth (JWT + Passport)
-
-```typescript
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor(config: ConfigService) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: config.getOrThrow('JWT_SECRET'),
-    });
-  }
-  async validate(payload: any) {
-    return { id: payload.sub, email: payload.email };
-  }
-}
-
-@Injectable()
-export class JwtAuthGuard extends AuthGuard('jwt') {}
-```
-
----
-
-## Testes
-
-### Unit (service)
-
-```typescript
-describe('RegisterUserService', () => {
-  it('falha se email já existe', async () => {
-    const repo = { existsByEmail: jest.fn().mockResolvedValue(true) } as any;
-    const sut = new RegisterUserService(repo);
-    await expect(sut.execute({ email: 'x@y.com', name: 'X', password: 'longsecret123' }))
-      .rejects.toThrow(UserAlreadyExistsError);
-  });
-});
-```
-
-### E2E (Supertest)
-
-```typescript
-describe('POST /users', () => {
-  it('cria com sucesso', async () => {
-    const res = await request(app.getHttpServer())
-      .post('/users')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ email: 'jane@example.com', name: 'Jane', password: 'longsecret123' });
-    expect(res.status).toBe(201);
-    expect(res.body.email).toBe('jane@example.com');
-  });
-});
-```
-
----
-
-## Antipatterns
-
-| AP | Antipattern | Correção |
-|---|---|---|
-| AP-01 | Validação inline | DTO + ValidationPipe |
-| AP-02 | Prisma no Controller | Repository |
-| AP-03 | Lógica no Controller | Service |
-| AP-04 | Sem DTO de saída | `UserResponseDto.from(user)` |
-| AP-05 | Secret hardcoded | `ConfigService.getOrThrow` |
-| AP-06 | Login sem throttler | rate limit obrigatório |
-| AP-07 | OpenAPI à mão | `@nestjs/swagger` |
-| AP-08 | Erros sem filter global | inconsistência de response |
-| AP-09 | `Prisma.user.findFirst` sem WHERE em tenant | A01 — Broken Access Control |
-
----
-
-## Segurança (combinar com `skill-security`)
-
-- Hash com `@node-rs/argon2` (Argon2id)
-- JWT RS256 público, HS256+secret≥256bits interno
-- `helmet` middleware para headers
-- CORS específico
-- Rate limit em login (5/15min)
-- Refresh token com rotação no DB
-
----
-
-## CI
-
-```bash
-npm run lint
-npm run test
-npm run test:e2e
-npm run build
-npx prisma migrate deploy --dry-run
-npm audit --audit-level=high
-```
-
----
-
-## Aplicação por fase DARE
-
-### Design
-- Listar endpoints REST com tags e métodos
-- Definir DTOs de input e output
-- Auth strategy escolhida
-
-### Blueprint
-- Estrutura de módulos
-- Prisma schema preliminar
-- Endpoints com `@ApiOperation` documentados
-
-### Tasks
-- Por módulo: 4 tasks (Module, Controller+DTO, Service, Repository)
-- Task de configuração Swagger + throttler + global filter
-
-### Execute
-- Ralph Loop:
-  ```bash
-  npm run lint && npm run test && npm run test:e2e && npm run build
-  ```
-
----
-
-## Checklist final
-
-- [ ] `strict: true` no tsconfig
-- [ ] Todos os Controllers usam DTOs com class-validator
-- [ ] `ValidationPipe` global em main.ts
-- [ ] Services injetáveis (não `new`)
-- [ ] Repositories encapsulam Prisma
-- [ ] OpenAPI gerado em `public/openapi.json`
-- [ ] ThrottlerModule global + endpoints sensíveis com `@Throttle`
-- [ ] AllExceptionsFilter global
-- [ ] Auth via `JwtAuthGuard` + secret via env
-- [ ] Testes unit + E2E
-
----
-
-Skill licenciada MIT — parte do DARE Method v3.
+---
+description: Padrões DARE para APIs REST em NestJS + TypeScript + Prisma + Swagger. Modules, Controllers, Services, DTOs com class-validator, Guards JWT, throttler, exceções globais, Jest + Supertest, OpenAPI auto-gerado.
+globs: src/**/*.ts,src/**/*.controller.ts,src/**/*.service.ts,src/**/*.module.ts,prisma/schema.prisma
+alwaysApply: false
+---
+
+# Skill: NestJS API DARE
+
+Você é um desenvolvedor sênior TypeScript / NestJS focado em APIs REST. Esta skill garante código **idiomático Nest, fortemente tipado, com auth/autz robustos e OpenAPI auto-gerado**, seguindo Layered Design DARE.
+
+## Stack canônica
+
+- **TypeScript 5.5+** com `strict: true`
+- **NestJS 11.x**
+- **Prisma 5.x** ORM (PostgreSQL ou MySQL)
+- **class-validator + class-transformer**
+- **@nestjs/swagger**
+- **@nestjs/throttler**
+- **@nestjs/passport + @nestjs/jwt**
+- **Jest + Supertest**
+
+---
+
+## Estrutura de módulo (Layered Design)
+
+```
+src/<feature>/
+├── <feature>.module.ts          ← providers + controllers
+├── <feature>.controller.ts      ← Handler
+├── <feature>.service.ts         ← Service (1 operação ou facade)
+├── <feature>.repository.ts      ← Repository (Prisma)
+├── dto/
+│   ├── create-<feature>.dto.ts
+│   └── update-<feature>.dto.ts
+├── entities/
+│   └── <feature>.entity.ts      ← Model
+└── tests/
+    ├── <feature>.service.spec.ts
+    └── <feature>.e2e-spec.ts
+```
+
+---
+
+## Controllers (Handler)
+
+```typescript
+import { Body, Controller, Post, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiCreatedResponse } from '@nestjs/swagger';
+import { JwtAuthGuard } from '@/auth/jwt-auth.guard';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UserResponseDto } from './dto/user-response.dto';
+import { RegisterUserService } from './register-user.service';
+
+@ApiTags('users')
+@Controller('users')
+@UseGuards(JwtAuthGuard)
+export class UsersController {
+  constructor(private readonly register: RegisterUserService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Criar novo usuário' })
+  @ApiCreatedResponse({ type: UserResponseDto })
+  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
+    const user = await this.register.execute(dto);
+    return UserResponseDto.from(user);
+  }
+}
+```
+
+Regras:
+- Apenas: recebe → valida via DTO → chama Service → retorna ResponseDto
+- NUNCA: Prisma direto, lógica de negócio, validação inline
+
+---
+
+## DTOs com class-validator
+
+```typescript
+import { IsEmail, IsString, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({ example: 'jane@example.com' })
+  @IsEmail() email!: string;
+
+  @ApiProperty({ example: 'Jane Doe' })
+  @IsString() name!: string;
+
+  @ApiProperty({ minLength: 12 })
+  @IsString() @MinLength(12) password!: string;
+}
+```
+
+`main.ts` global pipe:
+```typescript
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,
+  forbidNonWhitelisted: true,
+  transform: true,
+}));
+```
+
+---
+
+## Services
+
+Uma operação por classe:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { hash } from '@node-rs/argon2';
+import { UsersRepository } from './users.repository';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UserAlreadyExistsError } from './errors';
+
+@Injectable()
+export class RegisterUserService {
+  constructor(private readonly repo: UsersRepository) {}
+
+  async execute(dto: CreateUserDto) {
+    if (await this.repo.existsByEmail(dto.email)) {
+      throw new UserAlreadyExistsError();
+    }
+    return this.repo.create({
+      ...dto,
+      password: await hash(dto.password),
+    });
+  }
+}
+```
+
+---
+
+## Repositories (Prisma)
+
+```typescript
+@Injectable()
+export class UsersRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async existsByEmail(email: string): Promise<boolean> {
+    return !!(await this.prisma.user.findUnique({ where: { email } }));
+  }
+
+  async create(data: { email: string; name: string; password: string }) {
+    return this.prisma.user.create({ data });
+  }
+}
+```
+
+---
+
+## Tratamento global de exceções
+
+```typescript
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<Response>();
+
+    if (exception instanceof UserAlreadyExistsError) {
+      return response.status(409).json({ error: 'USER_EXISTS' });
+    }
+    if (exception instanceof HttpException) {
+      return response.status(exception.getStatus()).json(exception.getResponse());
+    }
+    return response.status(500).json({ error: 'INTERNAL' });
+  }
+}
+
+// main.ts
+app.useGlobalFilters(new AllExceptionsFilter());
+```
+
+---
+
+## OpenAPI auto-gerado
+
+```typescript
+const config = new DocumentBuilder()
+  .setTitle('Projeto API')
+  .setVersion('1.0')
+  .addBearerAuth()
+  .build();
+
+const document = SwaggerModule.createDocument(app, config);
+SwaggerModule.setup('docs', app, document);          // UI em /docs
+writeFileSync('./public/openapi.json', JSON.stringify(document));
+```
+
+---
+
+## Rate limiting
+
+```typescript
+import { ThrottlerModule, Throttle } from '@nestjs/throttler';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]),
+  ],
+})
+export class AppModule {}
+
+// Endpoint sensível
+@Throttle({ default: { limit: 5, ttl: 900_000 } })  // 5/15min
+@Post('login')
+async login() {...}
+```
+
+---
+
+## Auth (JWT + Passport)
+
+```typescript
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(config: ConfigService) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: config.getOrThrow('JWT_SECRET'),
+    });
+  }
+  async validate(payload: any) {
+    return { id: payload.sub, email: payload.email };
+  }
+}
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {}
+```
+
+---
+
+## Testes
+
+### Unit (service)
+
+```typescript
+describe('RegisterUserService', () => {
+  it('falha se email já existe', async () => {
+    const repo = { existsByEmail: jest.fn().mockResolvedValue(true) } as any;
+    const sut = new RegisterUserService(repo);
+    await expect(sut.execute({ email: 'x@y.com', name: 'X', password: 'longsecret123' }))
+      .rejects.toThrow(UserAlreadyExistsError);
+  });
+});
+```
+
+### E2E (Supertest)
+
+```typescript
+describe('POST /users', () => {
+  it('cria com sucesso', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/users')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ email: 'jane@example.com', name: 'Jane', password: 'longsecret123' });
+    expect(res.status).toBe(201);
+    expect(res.body.email).toBe('jane@example.com');
+  });
+});
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | Validação inline | DTO + ValidationPipe |
+| AP-02 | Prisma no Controller | Repository |
+| AP-03 | Lógica no Controller | Service |
+| AP-04 | Sem DTO de saída | `UserResponseDto.from(user)` |
+| AP-05 | Secret hardcoded | `ConfigService.getOrThrow` |
+| AP-06 | Login sem throttler | rate limit obrigatório |
+| AP-07 | OpenAPI à mão | `@nestjs/swagger` |
+| AP-08 | Erros sem filter global | inconsistência de response |
+| AP-09 | `Prisma.user.findFirst` sem WHERE em tenant | A01 — Broken Access Control |
+
+---
+
+## Segurança (combinar com `skill-security`)
+
+- Hash com `@node-rs/argon2` (Argon2id)
+- JWT RS256 público, HS256+secret≥256bits interno
+- `helmet` middleware para headers
+- CORS específico
+- Rate limit em login (5/15min)
+- Refresh token com rotação no DB
+
+---
+
+## CI
+
+```bash
+npm run lint
+npm run test
+npm run test:e2e
+npm run build
+npx prisma migrate deploy --dry-run
+npm audit --audit-level=high
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Listar endpoints REST com tags e métodos
+- Definir DTOs de input e output
+- Auth strategy escolhida
+
+### Blueprint
+- Estrutura de módulos
+- Prisma schema preliminar
+- Endpoints com `@ApiOperation` documentados
+
+### Tasks
+- Por módulo: 4 tasks (Module, Controller+DTO, Service, Repository)
+- Task de configuração Swagger + throttler + global filter
+
+### Execute
+- Ralph Loop:
+  ```bash
+  npm run lint && npm run test && npm run test:e2e && npm run build
+  ```
+
+---
+
+## Checklist final
+
+- [ ] `strict: true` no tsconfig
+- [ ] Todos os Controllers usam DTOs com class-validator
+- [ ] `ValidationPipe` global em main.ts
+- [ ] Services injetáveis (não `new`)
+- [ ] Repositories encapsulam Prisma
+- [ ] OpenAPI gerado em `public/openapi.json`
+- [ ] ThrottlerModule global + endpoints sensíveis com `@Throttle`
+- [ ] AllExceptionsFilter global
+- [ ] Auth via `JwtAuthGuard` + secret via env
+- [ ] Testes unit + E2E
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.