jarvis-ai-framework 2.1.0 → 2.1.1

package/skills/eng-backend-nestjs/references/2-guards-autenticacao.md

@@ -0,0 +1,118 @@
+# Guards e Autenticação (Passport + JWT)
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando a tarefa envolver guards, roles/permissões ou autenticação com Passport e JWT.
+
+### Guards
+
+Guards determinam se uma requisição deve ser processada. Executam **antes** dos interceptors.
+
+```typescript
+// ✅ Guard de autenticação JWT
+import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common'
+import { JwtService } from '@nestjs/jwt'
+import { Request } from 'express'
+
+@Injectable()
+export class JwtAuthGuard implements CanActivate {
+  constructor(private readonly jwtService: JwtService) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<Request>()
+    const token = this.extractTokenFromHeader(request)
+
+    if (!token) throw new UnauthorizedException('Token não fornecido')
+
+    try {
+      const payload = this.jwtService.verify(token)
+      request['user'] = payload
+      return true
+    } catch {
+      throw new UnauthorizedException('Token inválido ou expirado')
+    }
+  }
+
+  private extractTokenFromHeader(request: Request): string | undefined {
+    const [type, token] = request.headers.authorization?.split(' ') ?? []
+    return type === 'Bearer' ? token : undefined
+  }
+}
+```
+
+```typescript
+// ✅ Guard de roles (RBAC)
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>('roles', [
+      context.getHandler(),
+      context.getClass(),
+    ])
+
+    if (!requiredRoles) return true
+
+    const { user } = context.switchToHttp().getRequest()
+    return requiredRoles.some((role) => user.roles?.includes(role))
+  }
+}
+```
+
+```typescript
+// ✅ Decorator combinado (Auth + Roles)
+export const Auth = (...roles: string[]) =>
+  applyDecorators(
+    UseGuards(JwtAuthGuard, RolesGuard),
+    SetMetadata('roles', roles),
+  )
+
+// Uso na rota
+@Auth('admin')
+@Delete(':id')
+async remove(@Param('id') id: string) { ... }
+```
+
+---
+
+### Autenticação (Passport + JWT)
+
+```typescript
+// ✅ JWT Strategy
+import { ExtractJwt, Strategy } from 'passport-jwt' // importar de 'passport-jwt', NÃO 'passport-local'
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(configService: ConfigService) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: configService.getOrThrow('JWT_SECRET'),
+    })
+  }
+
+  async validate(payload: { sub: string; email: string }) {
+    return { userId: payload.sub, email: payload.email }
+  }
+}
+```
+
+```typescript
+// ✅ AuthModule
+@Module({
+  imports: [
+    PassportModule,
+    JwtModule.registerAsync({
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        secret: configService.getOrThrow('JWT_SECRET'),
+        signOptions: { expiresIn: '15m' },
+      }),
+    }),
+  ],
+  providers: [AuthService, JwtStrategy],
+  exports: [JwtModule],
+})
+export class AuthModule {}
+```
+
+---

package/skills/eng-backend-nestjs/references/3-interceptors-pipes-filters.md

@@ -0,0 +1,113 @@
+# Interceptors, Pipes e Exception Filters
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando a tarefa envolver interceptors, validação com pipes ou tratamento de exceções.
+
+### Interceptors
+
+Interceptors executam antes E depois do route handler. Ideais para logging, transformação de resposta, caching.
+
+```typescript
+// ✅ Interceptor de logging de requisições
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(LoggingInterceptor.name)
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const request = context.switchToHttp().getRequest()
+    const { method, url } = request
+    const start = Date.now()
+
+    return next.handle().pipe(
+      tap(() => {
+        const ms = Date.now() - start
+        this.logger.log(`${method} ${url} — ${ms}ms`)
+      }),
+    )
+  }
+}
+```
+
+```typescript
+// ✅ Interceptor de transformação de resposta
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, { data: T }> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<{ data: T }> {
+    return next.handle().pipe(
+      map((data) => ({ data }))
+    )
+  }
+}
+```
+
+---
+
+### Pipes e Validação
+
+Pipes validam e transformam dados de entrada **antes** do route handler.
+
+```typescript
+// ✅ Configuração global de ValidationPipe (no main.ts)
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,             // remove campos não declarados no DTO
+    forbidNonWhitelisted: true,  // lança erro se campos extras existirem
+    transform: true,             // transforma payload para instância do DTO
+    transformOptions: {
+      enableImplicitConversion: true,
+    },
+  }),
+)
+```
+
+```typescript
+// ✅ DTO com class-validator
+export class CreateUserDto {
+  @IsString()
+  @MinLength(2)
+  name: string
+
+  @IsEmail()
+  email: string
+
+  @IsOptional()
+  @IsEnum(['admin', 'editor', 'viewer'])
+  role?: string
+}
+```
+
+---
+
+### Exception Filters
+
+```typescript
+// ✅ Exception filter customizado para erros de negócio
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(HttpExceptionFilter.name)
+
+  catch(exception: HttpException, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp()
+    const response = ctx.getResponse<Response>()
+    const request = ctx.getRequest<Request>()
+    const status = exception.getStatus()
+    const exceptionResponse = exception.getResponse()
+
+    const body = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      error: typeof exceptionResponse === 'string'
+        ? exceptionResponse
+        : (exceptionResponse as Record<string, unknown>).message,
+    }
+
+    if (status >= 500) {
+      this.logger.error({ exception, path: request.url }, 'Erro interno')
+    }
+
+    response.status(status).json(body)
+  }
+}
+```
+
+---

package/skills/eng-backend-nestjs/references/4-config-logging.md

@@ -0,0 +1,61 @@
+# ConfigModule e Logging
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando a tarefa envolver variáveis de ambiente (ConfigModule) ou logging.
+
+### ConfigModule
+
+```typescript
+// ✅ ConfigModule com validação via Joi
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: '.env',
+      validationSchema: Joi.object({
+        NODE_ENV: Joi.string().valid('development', 'production', 'test').default('development'),
+        PORT: Joi.number().default(3000),
+        DATABASE_URL: Joi.string().required(),
+        JWT_SECRET: Joi.string().min(32).required(),
+        MESSAGE_BROKER_URL: Joi.string().required(),
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+// ✅ Usar ConfigService em vez de process.env diretamente
+@Injectable()
+export class DatabaseService {
+  constructor(private readonly configService: ConfigService) {}
+
+  getUrl(): string {
+    return this.configService.getOrThrow<string>('DATABASE_URL')
+  }
+}
+```
+
+---
+
+### Logging
+
+Consultar o guia de logs do projeto antes de implementar logging:
+`(guia de logs do projeto)`
+
+```typescript
+// ✅ Logger padrão NestJS
+import { Logger } from '@nestjs/common'
+
+@Injectable()
+export class UserService {
+  private readonly logger = new Logger(UserService.name)
+
+  async findById(id: string) {
+    this.logger.log(`Buscando usuário ${id}`)
+    // ...
+  }
+}
+```
+
+---

package/skills/eng-backend-nestjs/references/5-testes.md

@@ -0,0 +1,83 @@
+# Testes (NestJS)
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando a tarefa envolver testes unitários, de integração ou e2e.
+
+### Testes
+
+> **Obrigatório**: Antes de escrever qualquer teste, verificar se existe schematic ou modelo no projeto (ver Padrão 5).
+> Consultar o guia: (guia de testes do projeto)
+
+#### Service — teste unitário
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing'
+import { UserService } from './user.service'
+import { getRepositoryToken } from '@nestjs/typeorm'
+import { UserEntity } from './user.entity'
+
+describe('UserService', () => {
+  let service: UserService
+
+  const mockRepository = {
+    findOne: jest.fn(),
+    save: jest.fn(),
+    create: jest.fn(),
+  }
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UserService,
+        {
+          provide: getRepositoryToken(UserEntity), // ✅ token correto para TypeORM
+          useValue: mockRepository,
+        },
+      ],
+    }).compile()
+
+    service = module.get<UserService>(UserService)
+  })
+
+  afterEach(() => jest.clearAllMocks())
+
+  it('lança NotFoundException quando usuário não existe', async () => {
+    mockRepository.findOne.mockResolvedValue(null)
+    await expect(service.findById('id-inexistente')).rejects.toThrow('Usuário não encontrado')
+  })
+})
+```
+
+#### Controller — teste de integração (Supertest)
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing'
+import { INestApplication, ValidationPipe } from '@nestjs/common'
+import * as request from 'supertest'
+
+describe('UserController (integração)', () => {
+  let app: INestApplication
+
+  beforeAll(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [UserModule],
+    })
+      .overrideProvider(UserService)
+      .useValue({ findById: jest.fn().mockResolvedValue({ id: '1', name: 'Test' }) })
+      .compile()
+
+    app = module.createNestApplication()
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true }))
+    await app.init()
+  })
+
+  afterAll(() => app.close())
+
+  it('GET /users/:id → 200', async () => {
+    const response = await request(app.getHttpServer()).get('/users/1')
+    expect(response.status).toBe(200)
+    expect(response.body.data.id).toBe('1')
+  })
+})
+```
+
+---

package/skills/eng-backend-nestjs/references/6-problemas-comuns.md

@@ -0,0 +1,53 @@
+# Problemas Comuns e Soluções
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando houver erro de injeção de dependência, dependência circular, estratégia de autenticação, conexão com banco, escopo de provider ou guard não aplicado.
+
+## Problemas Comuns e Soluções
+
+### "Nest can't resolve dependencies of [Service] (?, +)"
+1. O `?` indica a posição do parâmetro faltando no construtor
+2. Verificar se o provider está em `providers[]` do módulo
+3. Se usado em outro módulo, verificar `exports[]` do módulo de origem
+4. Erros de digitação em barrel exports (`index.ts`) também causam este erro
+
+### "Circular dependency detected"
+**Proibido usar `forwardRef`.** Seguir obrigatoriamente:
+1. Refatorar a estrutura de módulos — rever responsabilidades
+2. Extrair lógica compartilhada para um terceiro módulo
+3. Ajustar escopo do provider como última alternativa
+
+### "Unknown authentication strategy 'jwt'"
+1. Importar `Strategy` de `'passport-jwt'`, **não** de `'passport-local'`
+2. Garantir que `JWT_SECRET` no `JwtModule` bate com `secretOrKey` na `JwtStrategy`
+3. Verificar formato do header: `Authorization: Bearer <token>`
+
+### "[TypeOrmModule] Unable to connect to the database"
+Frequentemente enganoso — verificar:
+1. Sintaxe das entities (ex: `@Column()` não `@Column('description')`)
+2. Decorators faltando em propriedades das entities
+3. Configuração de host/porta/credenciais
+
+### "Nest can't resolve dependencies of the Repository (testing)"
+```typescript
+// ✅ Usar getRepositoryToken para mockar repositórios TypeORM em testes
+{ provide: getRepositoryToken(UserEntity), useValue: mockRepo }
+```
+
+### "secretOrPrivateKey must have a value" (JWT)
+1. Definir `JWT_SECRET` nas variáveis de ambiente
+2. Verificar que `ConfigModule` carrega antes do `JwtModule`
+3. Usar `ConfigService` para configuração dinâmica
+
+### Guard não está sendo aplicado
+```typescript
+// ✅ Guard global com acesso ao DI — usar APP_GUARD, não useGlobalGuards()
+@Module({
+  providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
+})
+export class AppModule {}
+```
+
+### Provider com escopo errado
+- `DEFAULT` (Singleton) → instância única por aplicação
+- `REQUEST` → nova instância por requisição (todos os providers injetados herdam o escopo)
+- `TRANSIENT` → nova instância por injeção