jarvis-ai-framework 2.0.0 → 2.1.1

package/skills/SKILLS-ROADMAP.md

@@ -221,10 +221,6 @@ Removidas: `checkin`, `checkout`, `daily`, `task-log`, `send-priority`, `sent-pr
 - **Trigger**: auto-report de bugs no framework Jarvis via GitLab API
 - **Status**: `criado`
 
-### `skill-creator` ✅
-- **Trigger**: criação de novos skills
-- **Status**: `criado`
-
 ### `jarvis-docs-index` / `jarvis-docs-central` / `jarvis-context-detect` ✅
 - **Trigger**: indexação de docs, sync com repo central, detecção de contexto
 - **Status**: `criado`

package/skills/eng-ai-engineer/SKILL.md

@@ -205,6 +205,12 @@ Sempre avaliar tradeoffs antes de escolher modelo:
 - Plano de rollout gradual com métricas de avaliação
 - Documentar comportamento do sistema de IA
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Comportamentos Esperados

package/skills/eng-backend/SKILL.md

@@ -154,6 +154,12 @@ Depurar um problema?                   → tema 12 (erros e logging)
 4. **Testar**: cobrir o caso feliz, os casos de erro e os limites
 5. **Validar**: percorrer o checklist de conclusão abaixo
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Base Universal

package/skills/eng-backend-arch-c4/SKILL.md

@@ -32,10 +32,10 @@ Criar e manter documentação de arquitetura usando os 4 níveis do C4:
 **Exemplos de uso:**
 
 ```
-/arch-c4 context                    # Criar/Atualizar diagrama de contexto
-/arch-c4 container                  # Criar/Atualizar diagrama de containers
-/arch-c4 component api-backend      # Detalhar componentes de um container
-/arch-c4 code user-service          # Diagrama de código (raro)
+/eng-backend-arch-c4 context                    # Criar/Atualizar diagrama de contexto
+/eng-backend-arch-c4 container                  # Criar/Atualizar diagrama de containers
+/eng-backend-arch-c4 component api-backend      # Detalhar componentes de um container
+/eng-backend-arch-c4 code user-service          # Diagrama de código (raro)
 ```
 
 ## Recursos
@@ -259,6 +259,12 @@ git diff origin/main --name-only | grep -E "docker|config|src/(domain|infrastruc
 | Novo container/serviço | Container | Adicionar |
 | Novo módulo/componente | Component | Atualizar |
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Integração com ADRs

package/skills/eng-backend-microservices-trace/SKILL.md

@@ -411,6 +411,12 @@ Ao concluir, retornar:
    - Se inconclusivo: `→ eng.debug Passo 3 (Plano de Investigação) — coletar logs de {serviços}`
    - Se bug multi-serviço complexo: `→ eng.plan {TASK_MANAGER_KEY} — múltiplos componentes afetados`
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Regras

package/skills/eng-backend-nestjs/SKILL.md

@@ -77,8 +77,8 @@ Use este skill quando:
 **NÃO usar quando:**
 - A tarefa é sobre design de APIs, paginação, RabbitMQ, caching → usar `eng-backend`
 - A tarefa envolve scraping ou extração de dados → usar `eng-scraper`
-- A tarefa é puramente de banco de dados (queries, migrations, schema) → usar `eng-database`
-- Problema é de TypeScript puro (tipos, generics) → usar `typescript-type-expert`
+- A tarefa é puramente de banco de dados (queries, migrations, schema) → ainda não há skill específico; seguir `eng-backend`
+- Problema é de TypeScript puro (tipos, generics) → ainda não há skill específico; seguir as convenções de TypeScript do projeto
 
 ---
 
@@ -249,469 +249,24 @@ find src -name "*.module.ts" | head -10
 find src -name "*.spec.ts" | head -5
 ```
 
-### Arquitetura de Módulos
+### Referências (leia só o tema que a tarefa pedir)
 
-#### Estrutura de módulo de feature
+Leia **só** o arquivo do tema que a tarefa pedir; o restante fica fora do contexto.
 
-```typescript
-// ✅ Padrão de módulo de feature
-@Module({
-  imports: [
-    TypeOrmModule.forFeature([UserEntity]),
-    CommonModule,
-  ],
-  controllers: [UserController],
-  providers: [UserService, UserRepository],
-  exports: [UserService], // exportar apenas o que outros módulos precisam
-})
-export class UserModule {}
-```
-
-#### Módulo global (para providers transversais)
-
-```typescript
-// ✅ Módulo global — disponível sem importar
-@Global()
-@Module({
-  providers: [LoggerService],
-  exports: [LoggerService],
-})
-export class LoggerModule {}
-```
-
-#### Módulo dinâmico
-
-```typescript
-// ✅ Módulo dinâmico para configuração em runtime
-@Module({})
-export class HttpClientModule {
-  static forRoot(options: HttpClientOptions): DynamicModule {
-    return {
-      module: HttpClientModule,
-      providers: [
-        { provide: HTTP_CLIENT_OPTIONS, useValue: options },
-        HttpClientService,
-      ],
-      exports: [HttpClientService],
-    }
-  }
-}
-```
-
----
-
-### 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) { ... }
-```
-
----
-
-### 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
-}
-```
-
----
+| Tema | Quando ler | Arquivo |
+|------|-----------|---------|
+| Arquitetura de Módulos (NestJS) | A tarefa criar ou reorganizar módulos, providers e injeção de dependência | `references/1-arquitetura-modulos.md` |
+| Guards e Autenticação (Passport + JWT) | A tarefa envolver guards, roles/permissões ou autenticação com Passport e JWT | `references/2-guards-autenticacao.md` |
+| Interceptors, Pipes e Exception Filters | A tarefa envolver interceptors, validação com pipes ou tratamento de exceções | `references/3-interceptors-pipes-filters.md` |
+| ConfigModule e Logging | A tarefa envolver variáveis de ambiente (ConfigModule) ou logging | `references/4-config-logging.md` |
+| Testes (NestJS) | A tarefa envolver testes unitários, de integração ou e2e | `references/5-testes.md` |
+| Problemas Comuns e Soluções | 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 | `references/6-problemas-comuns.md` |
 
-### 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')
-  }
-}
-```
-
----
-
-### 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 {}
-```
-
----
-
-### 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)
-  }
-}
-```
-
----
-
-### 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')
-  })
-})
-```
-
----
-
-### 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}`)
-    // ...
-  }
-}
-```
-
----
-
-## 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 {}
-```
+### Skills invocados durante a execução do skill
 
-### 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
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
 
 ---
 

package/skills/eng-backend-nestjs/references/1-arquitetura-modulos.md

@@ -0,0 +1,54 @@
+# Arquitetura de Módulos (NestJS)
+
+> Parte do skill `eng-backend-nestjs`. Leia este arquivo quando a tarefa criar ou reorganizar módulos, providers e injeção de dependência.
+
+### Arquitetura de Módulos
+
+#### Estrutura de módulo de feature
+
+```typescript
+// ✅ Padrão de módulo de feature
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([UserEntity]),
+    CommonModule,
+  ],
+  controllers: [UserController],
+  providers: [UserService, UserRepository],
+  exports: [UserService], // exportar apenas o que outros módulos precisam
+})
+export class UserModule {}
+```
+
+#### Módulo global (para providers transversais)
+
+```typescript
+// ✅ Módulo global — disponível sem importar
+@Global()
+@Module({
+  providers: [LoggerService],
+  exports: [LoggerService],
+})
+export class LoggerModule {}
+```
+
+#### Módulo dinâmico
+
+```typescript
+// ✅ Módulo dinâmico para configuração em runtime
+@Module({})
+export class HttpClientModule {
+  static forRoot(options: HttpClientOptions): DynamicModule {
+    return {
+      module: HttpClientModule,
+      providers: [
+        { provide: HTTP_CLIENT_OPTIONS, useValue: options },
+        HttpClientService,
+      ],
+      exports: [HttpClientService],
+    }
+  }
+}
+```
+
+---