@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/agents/db-specialist.agent.md

@@ -1,78 +0,0 @@
----
-name: DB Specialist
-description: Identifica o banco de dados e o ORM usados no projeto, analisa models/entities, migrations, índices e o impacto de performance das queries contra o schema. Somente leitura — devolve um relatório com as descobertas e recomendações, nunca aplica alterações. Use quando pedirem auditoria de banco de dados, revisão de schema/migrations, análise de performance de query, ou "o que esse projeto usa de banco".
-tools: ["read", "search"]
-disable-model-invocation: false
-user-invocable: true
-is_background: true
----
-
-# DB Specialist — DS9
-
-Você é um especialista em persistência: somente leitura, produz um relatório técnico sobre o banco de dados e o ORM do projeto analisado.
-
-## 1. Identificar o stack de dados
-
-- Banco de dados: procure em `package.json` (drivers como `mysql2`, `pg`, `mongodb`), `docker-compose.yml`, variáveis de ambiente (`DB_HOST`, `DATABASE_URL`) e arquivos de configuração (`ormconfig`, `data-source.ts`).
-- ORM/query builder: procure dependências (`typeorm`, `prisma`, `sequelize`, `knex`, `mongoose`) e a estrutura de pastas (`*.entity.ts`, `schema.prisma`, `migrations/`).
-- Se o projeto usa MySQL + TypeORM (padrão DS9), aplique as skills `mysql` e `typeorm` como critério de avaliação. Se usar outro stack, avalie pelos princípios gerais (tipos corretos, índices, migrations versionadas, queries parametrizadas) e sinalize a divergência do padrão DS9.
-
-## 2. Analisar models/entities
-
-- Tipos de coluna coerentes com o domínio (dinheiro em `decimal`, não `float`; datas em tipo de data, não `varchar`).
-- Chaves primárias e estratégia de ID consistente entre entidades.
-- Relações (`@ManyToOne`, `@OneToMany`, etc.) com FK explícita, e cascades/eager loading avaliados quanto a risco (ver skill `typeorm`).
-- Soft delete, auditoria (`created_at`/`updated_at`) presentes onde o domínio exige.
-
-## 3. Analisar migrations
-
-- Toda alteração de schema tem migration versionada (nenhuma evidência de alteração manual direta)?
-- Migrations têm `up`/`down` reversível? Alguma migration já aplicada parece ter sido editada depois (sinal: histórico de git mostrando mudança em migration antiga)?
-- Alterações potencialmente perigosas em produção (`DROP COLUMN`, `ALTER` bloqueante em tabela grande) sem cuidado explícito documentado.
-
-## 4. Analisar índices
-
-- FKs têm índice correspondente?
-- Índices compostos existentes fazem sentido para os padrões de consulta observados no código (repositórios/queries)?
-- Índices redundantes ou ausentes em colunas usadas com frequência em `WHERE`/`ORDER BY`/`JOIN`.
-- Existe índice único garantindo invariantes de negócio no banco (não só na aplicação)?
-
-## 5. Analisar queries e impacto de performance
-
-- `SELECT *` em código de produção; queries sem `LIMIT`/paginação em listagens.
-- Risco de N+1 (loop fazendo uma query por item, ou relation `eager` carregando grafos grandes).
-- Queries com filtro em coluna sem índice correspondente (risco de full table scan).
-- SQL concatenado com valor de usuário (risco de SQL Injection) em vez de query parametrizada/QueryBuilder.
-- Transações ausentes em operações que alteram múltiplas tabelas com invariantes relacionadas.
-
-## Formato do relatório
-
-```text
-## Stack de dados
-- Banco: ...
-- ORM: ...
-- Observações de configuração (synchronize, migrationsRun, etc.): ...
-
-## Achados — Models/Entities
-[severidade] local — descrição — recomendação
-
-## Achados — Migrations
-[severidade] local — descrição — recomendação
-
-## Achados — Índices
-[severidade] local — descrição — recomendação
-
-## Achados — Queries/Performance
-[severidade] local — descrição — recomendação
-
-## Resumo
-Total por severidade e prioridade sugerida de correção.
-```
-
-Severidade: 🔴 crítica (risco de perda de dados/corrupção/indisponibilidade) | 🟠 alta (performance ruim em produção, falta de integridade) | 🟡 média (dívida técnica) | ⚪ baixa (observação/sugestão).
-
-## Não fazer
-
-- Não editar entities, migrations ou qualquer arquivo — este agente é exclusivamente de leitura e relatório.
-- Não executar migrations nem comandos que alterem o banco.
-- Não recomendar mudança de stack (trocar de ORM/banco) a menos que explicitamente perguntado; o foco é avaliar o que já existe.

package/content/agents/nestjs-api-designer.agent.md

@@ -1,61 +0,0 @@
----
-name: NestJS API Designer
-description: Analisa, revisa e cria contratos de endpoints REST em projetos NestJS da DS9 — rotas, DTOs de entrada/saída, códigos de status HTTP, versionamento de API e documentação OpenAPI/Swagger. Use ao criar um novo endpoint, revisar o contrato de uma API existente, ou quando pedirem "desenhar endpoint", "contrato de API", "DTO" ou "versionamento".
-tools: ["read", "search", "edit"]
-disable-model-invocation: false
-user-invocable: true
-is_background: true
----
-
-# NestJS API Designer — DS9
-
-Projeta e revisa contratos de API REST em NestJS, seguindo as skills `nestjs` e `hexagonal` (controllers são adapters de entrada, sem regra de negócio) e `typescript` (tipagem estrita).
-
-## O que analisar/produzir
-
-### 1. Rotas
-
-- Recurso no plural, hierarquia clara (`/orders`, `/orders/:id`, `/orders/:id/items`).
-- Verbo HTTP correto para a ação: `GET` (leitura, idempotente), `POST` (criação ou ação não idempotente), `PUT` (substituição completa), `PATCH` (atualização parcial), `DELETE` (remoção).
-- Nomes de rota não repetem o nome do recurso já presente no controller (`@Controller('orders')` + `@Get(':id')`, não `@Get('orders/:id')`).
-
-### 2. DTOs
-
-- Um DTO de entrada por operação (`CreateOrderDto`, `UpdateOrderDto` — nunca reaproveitar o mesmo DTO para create e update se os campos obrigatórios diferem).
-- Um DTO de saída dedicado (`OrderResponseDto`), nunca a entidade de domínio/persistência exposta diretamente (ver skill `hexagonal`).
-- Toda propriedade do DTO de entrada tem decorator de validação (`class-validator`) compatível com a regra de negócio real (ex.: `@IsPositive()` para valores monetários, `@IsEmail()` para e-mail, `@IsEnum()` para status fechado).
-- DTOs aninhados usam `@ValidateNested()` + `@Type(() => SubDto)`.
-- Documente cada propriedade com `@ApiProperty({ description, example })` (ou `@ApiPropertyOptional` quando opcional).
-
-### 3. Códigos de status
-
-- `201 Created` em `POST` que cria recurso (com `@HttpCode(HttpStatus.CREATED)` se o Nest não aplicar por padrão).
-- `200 OK` para `GET`/`PATCH`/`PUT` bem-sucedidos com corpo de resposta.
-- `204 No Content` para `DELETE` bem-sucedido sem corpo.
-- `400 Bad Request` para falha de validação (já automático via `ValidationPipe`), `404 Not Found` para recurso inexistente, `409 Conflict` para violação de invariante única (ex.: e-mail duplicado), `422 Unprocessable Entity` apenas se o projeto já adotar essa distinção de `400`.
-- Documente cada status possível com `@ApiResponse({ status, description, type })`.
-
-### 4. Versionamento
-
-- Toda API nova decide explicitamente a estratégia de versionamento do projeto (padrão recomendado: URI versioning do Nest — `app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1' })`, rotas expostas como `/v1/orders`).
-- Breaking changes em um contrato existente exigem nova versão (`/v2/...`), nunca alteração destrutiva silenciosa na versão corrente.
-- Se o projeto já usa outra estratégia (header, media type), siga a convenção existente em vez de introduzir uma segunda.
-
-### 5. OpenAPI/Swagger
-
-- Todo controller tem `@ApiTags('orders')`; toda rota tem `@ApiOperation({ summary })`.
-- Gere/atualize a configuração do `SwaggerModule` se o projeto ainda não a tiver, mantendo o documento sincronizado com os DTOs reais (não escrever spec OpenAPI manual divergente do código).
-
-## Processo ao revisar um contrato existente
-
-1. Ler o controller, DTOs de entrada/saída e o use case associado.
-2. Checar os 5 pontos acima e listar divergências.
-3. Propor o contrato corrigido (rota, verbo, status, DTO, versão) antes de editar.
-4. Aplicar a edição apenas nos arquivos de contrato (controller, DTOs, decorators Swagger) — nunca na lógica de negócio do use case/domínio.
-
-## Não fazer
-
-- Não expor entidade de domínio/persistência como corpo de resposta.
-- Não reutilizar um DTO de criação para atualização parcial sem revisar `required`/`optional` de cada campo.
-- Não introduzir uma segunda estratégia de versionamento no mesmo projeto.
-- Não alterar regra de negócio do use case — este agente cuida apenas do contrato HTTP (ver skill `hexagonal` para a fronteira adapter/use case).

package/content/skills/hexagonal/SKILL.md

@@ -1,156 +0,0 @@
----
-name: hexagonal
-description: Diretrizes de arquitetura hexagonal (ports & adapters) aplicadas a projetos NestJS da DS9. Use ao criar, revisar ou refatorar módulos, definir camadas (domain/application/infrastructure), portas (interfaces) e adapters (controllers, repositórios, clients externos), ou quando o usuário pedir "arquitetura hexagonal", "ports and adapters" ou organização de um novo módulo/feature.
----
-
-# Arquitetura Hexagonal (Ports & Adapters) em NestJS
-
-Padrão arquitetural oficial da DS9 para backends NestJS. Objetivo: isolar as regras de negócio (domínio) de frameworks, banco de dados e protocolos de entrada/saída, tornando o core testável e substituível.
-
-## Camadas e responsabilidades
-
-```text
-src/
-└── <contexto>/                     # bounded context / módulo de negócio
-    ├── domain/                     # núcleo — sem dependência de NestJS, TypeORM, HTTP, etc.
-    │   ├── entities/                # entidades e value objects (regras e invariantes)
-    │   ├── ports/                   # interfaces (contratos) que o domínio precisa
-    │   │   ├── in/                  # casos de uso expostos (ex.: CreateOrderUseCase)
-    │   │   └── out/                 # dependências externas (ex.: OrderRepositoryPort)
-    │   └── errors/                  # exceções de domínio
-    ├── application/                # orquestração dos casos de uso (services)
-    │   └── use-cases/               # implementa as portas "in", orquestra portas "out"
-    └── infrastructure/              # adapters concretos — tudo que é "detalhe"
-        ├── adapters/
-        │   ├── in/                  # entrada: controllers REST, consumers de fila, resolvers GraphQL
-        │   └── out/                 # saída: repositórios TypeORM, HTTP clients, gateways de pagamento
-        └── <contexto>.module.ts     # module NestJS que faz o "wiring" via injeção de dependência
-```
-
-### Regra de dependência (inversão obrigatória)
-
-- `domain/` **não importa nada** de `infrastructure/`, `application/`, `@nestjs/*`, `typeorm`, `express`, etc. Só TypeScript puro.
-- `application/` depende apenas de `domain/` (entidades e ports).
-- `infrastructure/` depende de `domain/` e `application/`, nunca o contrário.
-- Sentido das setas: `infrastructure` → `application` → `domain`. Nunca inverter.
-
-## Ports (interfaces)
-
-- Toda porta é uma `interface` TypeScript definida em `domain/ports/`.
-- Ports de saída (`out`) representam o que o domínio **precisa** do mundo externo (persistência, mensageria, serviços externos). Nomeie como `<Algo>Port` (ex.: `OrderRepositoryPort`, `PaymentGatewayPort`).
-- Ports de entrada (`in`) representam casos de uso que o domínio **oferece**. Nomeie como `<Ação><Entidade>UseCase` (ex.: `CreateOrderUseCase`).
-- Use `Symbol`/token de injeção dedicado para cada porta (evita colisão e permite múltiplas implementações):
-
-```typescript
-// domain/ports/out/order-repository.port.ts
-export interface OrderRepositoryPort {
-  save(order: Order): Promise<void>;
-  findById(id: string): Promise<Order | null>;
-}
-export const ORDER_REPOSITORY_PORT = Symbol('ORDER_REPOSITORY_PORT');
-```
-
-## Adapters
-
-- **Adapter de entrada (`in`)**: controller HTTP, consumer de fila, cron job, resolver GraphQL. Responsabilidade única: traduzir o protocolo externo (DTO/request) para a chamada do caso de uso, e o retorno do caso de uso para a resposta do protocolo. Nunca contém regra de negócio.
-- **Adapter de saída (`out`)**: implementação concreta de uma port `out` (ex.: `TypeOrmOrderRepository implements OrderRepositoryPort`, usando as diretrizes da skill `typeorm`). Fica em `infrastructure/adapters/out/`.
-- DTOs de entrada/saída (`class-validator`/`class-transformer`) vivem no adapter de entrada, nunca no domínio.
-
-```typescript
-// infrastructure/adapters/out/typeorm-order.repository.ts
-@Injectable()
-export class TypeOrmOrderRepository implements OrderRepositoryPort {
-  constructor(@InjectRepository(OrderEntity) private readonly repo: Repository<OrderEntity>) {}
-
-  async save(order: Order): Promise<void> {
-    await this.repo.save(OrderMapper.toPersistence(order));
-  }
-
-  async findById(id: string): Promise<Order | null> {
-    const row = await this.repo.findOneBy({ id });
-    return row ? OrderMapper.toDomain(row) : null;
-  }
-}
-```
-
-## Wiring (module NestJS)
-
-O module conecta a porta ao adapter concreto via `useClass`/token:
-
-```typescript
-@Module({
-  controllers: [OrderController],
-  providers: [
-    CreateOrderUseCase,
-    { provide: ORDER_REPOSITORY_PORT, useClass: TypeOrmOrderRepository },
-  ],
-})
-export class OrderModule {}
-```
-
-Casos de uso recebem a porta por injeção, nunca a implementação concreta:
-
-```typescript
-@Injectable()
-export class CreateOrderUseCase {
-  constructor(@Inject(ORDER_REPOSITORY_PORT) private readonly orders: OrderRepositoryPort) {}
-}
-```
-
-## Transações cross-aggregate (Unit of Work)
-
-Quando um caso de uso precisa alterar **mais de um agregado atrás de ports diferentes** na mesma operação atômica (ex.: criar pedido + baixar estoque), não force esse acoplamento dentro de um único repositório concreto. Use uma port dedicada de coordenação transacional:
-
-```typescript
-// domain/ports/out/unit-of-work.port.ts
-export interface UnitOfWorkPort {
-  run<T>(work: () => Promise<T>): Promise<T>;
-}
-export const UNIT_OF_WORK_PORT = Symbol('UNIT_OF_WORK_PORT');
-```
-
-- O use case injeta `UnitOfWorkPort` além das ports dos agregados envolvidos, e executa as chamadas das ports **dentro** do `run()`:
-
-```typescript
-@Injectable()
-export class CreateOrderUseCase {
-  constructor(
-    @Inject(UNIT_OF_WORK_PORT) private readonly uow: UnitOfWorkPort,
-    @Inject(ORDER_REPOSITORY_PORT) private readonly orders: OrderRepositoryPort,
-    @Inject(STOCK_REPOSITORY_PORT) private readonly stock: StockRepositoryPort,
-  ) {}
-
-  async execute(cmd: CreateOrderCommand): Promise<Order> {
-    return this.uow.run(async () => {
-      const order = Order.create(cmd);
-      await this.stock.decrement(cmd.productId, cmd.quantity);
-      await this.orders.save(order);
-      return order;
-    });
-  }
-}
-```
-
-- O `UnitOfWorkPort` é a **única** peça com permissão de abrir uma transação técnica compartilhada; sua implementação concreta fica em `infrastructure/adapters/out/` (ver skill `typeorm` para a implementação com `DataSource.transaction()`).
-- Não implemente coordenação cross-aggregate escrevendo em duas entidades de tabelas diferentes dentro do repositório de um único agregado (ex.: `OrderRepository` não deve tocar `StockEntity`) — isso quebra a regra de "repositório só implementa a port do seu próprio agregado".
-
-## Mappers
-
-- Toda tradução entre entidade de domínio e modelo de persistência (`OrderEntity` do TypeORM) passa por um `Mapper` dedicado (`toDomain` / `toPersistence`) em `infrastructure/adapters/out/mappers/`.
-- O domínio nunca conhece decorators de ORM (`@Entity`, `@Column`).
-
-## Checklist ao criar/revisar um módulo
-
-1. O domínio compila sem `@nestjs/*` e sem `typeorm` nos imports?
-2. Toda dependência externa do domínio está atrás de uma `port`?
-3. Regras de negócio e invariantes estão nas entidades/use-cases, não nos controllers?
-4. Existe um teste unitário do use-case usando um fake/mock da port (sem subir banco/HTTP)?
-5. O adapter de entrada só faz tradução de protocolo (sem `if` de regra de negócio)?
-6. Erros de domínio são classes próprias (`OrderNotFoundError`), traduzidas para HTTP só no adapter de entrada (`ExceptionFilter`)?
-
-## Não fazer
-
-- Não injete `Repository<Entity>` do TypeORM diretamente em use-cases ou entidades de domínio.
-- Não coloque decorators de validação HTTP (`class-validator`) em entidades de domínio.
-- Não exponha entidades de persistência (`*Entity`) fora de `infrastructure/`.
-- Não crie "god services" que misturam orquestração de use-case com acesso direto a dados.

package/content/skills/jest-testing/SKILL.md

@@ -1,88 +0,0 @@
----
-name: jest-testing
-description: Diretrizes de testes com Jest para projetos NestJS/TypeScript da DS9 — testes unitários de use cases/services, testes de integração de controllers, mocks de ports, cobertura e convenções de nomenclatura. Use ao escrever/revisar testes, criar mocks/fakes, configurar `jest.config`, ou quando o usuário pedir "teste unitário", "teste de integração" ou "cobertura de testes".
----
-
-# Jest — Diretrizes de Teste DS9
-
-Jest é o test runner padrão para projetos TypeScript/NestJS da DS9. Esta skill cobre convenções de teste; a organização em camadas segue a skill `hexagonal` e as convenções de framework seguem a skill `nestjs`.
-
-## Estrutura e nomenclatura
-
-- Arquivo de teste ao lado do arquivo testado: `order.use-case.ts` → `order.use-case.spec.ts` (unitário) ou `*.e2e-spec.ts` (ponta a ponta, pasta `test/`).
-- `describe` nomeia a unidade testada (`describe('CreateOrderUseCase', ...)`); `it`/`test` descreve o comportamento esperado em linguagem natural (`it('deve lançar OrderNotFoundError quando o pedido não existe', ...)`), nunca o nome do método (`it('deve testar execute', ...)` é proibido).
-- Um `describe` por método/comportamento público quando a classe tiver múltiplos cenários relevantes.
-
-## Pirâmide de testes no projeto
-
-| Camada | O que testar | Ferramenta | Sobe banco/HTTP real? |
-|---|---|---|---|
-| Domínio (entities, value objects) | Invariantes e regras de negócio puras | Jest puro | Não |
-| Use cases / application | Orquestração, chamando ports mockadas | Jest + mocks das `ports` | Não |
-| Adapters de saída (repositórios TypeORM) | Mapeamento correto entidade ↔ persistência | Jest + banco de teste (ou testcontainers, ver skill `docker`) | Sim (banco de teste isolado) |
-| Controllers / adapters de entrada | Contrato HTTP: status, shape, validação | Jest + `supertest` (`*.e2e-spec.ts`) | Sim (app NestJS em memória, banco de teste) |
-
-A maior parte dos testes deve estar nas duas primeiras camadas (rápidos, sem I/O); testes de integração/e2e cobrem os caminhos críticos, não todo caso de borda.
-
-## Mocks de Ports (hexagonal)
-
-- Use cases são testados mockando as `ports` (interfaces), nunca subindo banco/HTTP real. Prefira um *fake* em memória simples a um mock excessivamente configurado quando a port tem poucos métodos:
-
-```typescript
-class InMemoryOrderRepository implements OrderRepositoryPort {
-  private readonly rows = new Map<string, Order>();
-  async save(order: Order): Promise<void> { this.rows.set(order.id, order); }
-  async findById(id: string): Promise<Order | null> { return this.rows.get(id) ?? null; }
-}
-
-describe('CreateOrderUseCase', () => {
-  it('deve salvar o pedido com status PENDING', async () => {
-    const repo = new InMemoryOrderRepository();
-    const useCase = new CreateOrderUseCase(repo);
-
-    const order = await useCase.execute({ customerId: 'c1', items: [...] });
-
-    expect(order.status).toBe('PENDING');
-  });
-});
-```
-
-- Para mocks com `jest.fn()`, tipar sempre contra a interface da port (`jest.Mocked<OrderRepositoryPort>`), nunca `any`.
-- Não mocke o que você não é dono (bibliotecas externas/SDKs) diretamente nos testes de domínio — isole-as atrás de uma port e mocke a port.
-
-## Testes de controller (NestJS)
-
-- Monte o módulo real via `Test.createTestingModule({ imports: [OrderModule] })`, sobrescrevendo apenas as dependências externas (`overrideProvider(ORDER_REPOSITORY_PORT)`), para validar o wiring de DI de verdade.
-- Use `supertest` contra a instância HTTP da aplicação Nest (`app.getHttpServer()`), verificando status code, shape do body e erros de validação (400) com payload inválido.
-
-## Assertions
-
-- Prefira matchers específicos (`toEqual`, `toMatchObject`, `toThrow(OrderNotFoundError)`) a `toBeTruthy()`/`toBeDefined()` genéricos quando o valor exato importa.
-- Para erros de domínio, sempre assertar a **classe/tipo** do erro (`expect(fn).rejects.toThrow(OrderNotFoundError)`), não só a mensagem em texto.
-- Nunca deixe um teste sem nenhuma asserção (`it` vazio/`TODO`) marcado como passando; use `it.todo('...')` ou `.skip` explicitamente se o teste ainda não foi implementado.
-
-## Isolamento e determinismo
-
-- Cada teste deve poder rodar isoladamente e em qualquer ordem — sem estado global compartilhado entre `it`s (use `beforeEach` para recriar fakes/mocks).
-- Nunca dependa de `Date.now()`/hora real sem controlar o clock (`jest.useFakeTimers()`); nunca dependa de ordem de `Promise`/timing sem `await` explícito.
-- Testes de integração usam um banco de dados de teste próprio (schema isolado por execução), nunca o banco de dev/homolog compartilhado. Se o projeto usar testcontainers para subir esse banco, siga a skill `docker` para a imagem/configuração do container.
-
-## Cobertura
-
-- Cobertura mínima definida pelo projeto é validada no CI (`jest --coverage`); regras de negócio no domínio/use-cases devem ter cobertura próxima de 100% dos branches (if/else, early-return de erro).
-- Cobertura alta não substitui qualidade das asserções — não escreva teste só para "bater número" sem validar comportamento real.
-
-## Checklist ao escrever/revisar testes
-
-1. O teste de use case mocka a port (sem banco/HTTP real)?
-2. Nomes de `describe`/`it` descrevem comportamento, não implementação?
-3. Erros de domínio são testados por tipo/classe, não só mensagem?
-4. O teste é determinístico (sem dependência de tempo real/ordem)?
-5. Testes de controller cobrem pelo menos um caso de validação inválida (400) além do caminho feliz?
-
-## Não fazer
-
-- Não usar `any` em mocks de ports.
-- Não deixar `it.skip`/`xit` sem um comentário explicando o motivo e um acompanhamento (issue/TODO).
-- Não testar detalhes de implementação privada (métodos privados) — teste pelo comportamento público.
-- Não compartilhar estado mutável entre testes sem reset em `beforeEach`/`afterEach`.

package/content/skills/nestjs/SKILL.md

@@ -1,100 +0,0 @@
----
-name: nestjs
-description: Diretrizes e convenções NestJS da DS9 — módulos, controllers, DTOs/validação, injeção de dependência, tratamento de erros, configuração e segurança. Use ao criar/revisar controllers, services, DTOs, guards, interceptors, pipes, ou quando o usuário pedir "endpoint", "controller", "module NestJS" ou "boas práticas NestJS".
----
-
-# NestJS — Diretrizes DS9
-
-Framework padrão de backend da DS9. Esta skill cobre convenções específicas do NestJS; a organização em camadas (domain/application/infrastructure) segue a skill `hexagonal`, e a persistência segue a skill `typeorm`.
-
-## Estrutura de módulo
-
-- Um módulo por bounded context/feature (`OrderModule`, `CustomerModule`), nunca um módulo "god" por tipo técnico (ex.: não criar `ControllersModule`).
-- Cada módulo exporta só o que outros módulos precisam (`exports: [...]`); mantenha providers internos privados por padrão.
-- `AppModule` apenas importa feature modules + módulos globais de infraestrutura (`ConfigModule`, `TypeOrmModule.forRoot`, etc.). Sem lógica de negócio.
-
-## Controllers (adapters de entrada)
-
-- Controller é "burro": recebe request, valida via DTO, chama um use case/service, mapeia o retorno. Nenhuma regra de negócio aqui (ver skill `hexagonal`).
-- Um controller por recurso REST, rotas no plural (`/orders`, `/orders/:id`).
-- Sempre tipar o retorno do handler e usar os decorators HTTP corretos (`@Get`, `@Post`, `@Patch` para update parcial, `@Put` para substituição completa, `@Delete`).
-- Use `@HttpCode()` explícito quando o código padrão do método não for o desejado (ex.: `201` em `POST`, `204` em `DELETE`).
-
-```typescript
-@Controller('orders')
-export class OrderController {
-  constructor(private readonly createOrder: CreateOrderUseCase) {}
-
-  @Post()
-  @HttpCode(HttpStatus.CREATED)
-  async create(@Body() dto: CreateOrderDto): Promise<OrderResponseDto> {
-    const order = await this.createOrder.execute(dto.toCommand());
-    return OrderResponseDto.fromDomain(order);
-  }
-}
-```
-
-## DTOs e validação
-
-- Todo input externo (`@Body`, `@Query`, `@Param`) é tipado com uma classe DTO usando `class-validator` + `class-transformer`. Nunca aceitar `any`/objeto não tipado.
-- Ative globalmente `ValidationPipe` com `whitelist: true` e `forbidNonWhitelisted: true` para rejeitar campos não declarados no DTO:
-
-```typescript
-app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
-```
-
-- DTOs de request e response são classes separadas (`CreateOrderDto` ≠ `OrderResponseDto`); nunca devolver a entidade de domínio/persistência diretamente na resposta HTTP.
-- Documente cada DTO com decorators do Swagger (`@ApiProperty`) quando o projeto expõe OpenAPI.
-
-## Injeção de dependência
-
-- Prefira injeção por construtor (`constructor(private readonly x: X) {}`), nunca `new` direto de um provider gerenciado pelo Nest.
-- Dependências para fora do domínio (ver skill `hexagonal`) são injetadas por token/interface (`@Inject(PORT_TOKEN)`), não pela implementação concreta.
-- Escopo padrão dos providers é singleton (`Scope.DEFAULT`); use `Scope.REQUEST` apenas quando houver necessidade real de estado por request (tem custo de performance).
-
-## Tratamento de erros
-
-- Erros de domínio são classes próprias (`OrderNotFoundError extends Error`), lançadas pelo use case/domínio.
-- Um `ExceptionFilter` global traduz erros de domínio para `HttpException`/status code correto; controllers não fazem `try/catch` manual para mapear erro de negócio em HTTP.
-- Nunca deixe vazar stack trace ou detalhes internos (query SQL, caminho de arquivo) na resposta HTTP em produção.
-- Erros de validação (DTO) já retornam 400 automaticamente via `ValidationPipe`; não duplique essa validação no controller.
-
-## Configuração
-
-- Toda configuração de ambiente passa por `@nestjs/config` com schema de validação (ex.: `Joi`/`zod`) no bootstrap — a aplicação **falha ao subir** se faltar uma env var obrigatória, nunca falha silenciosamente em runtime.
-- Nunca leia `process.env` diretamente em services/controllers; sempre via `ConfigService` tipado.
-- Segredos (DB password, JWT secret, API keys) vêm de variável de ambiente/secret manager, nunca hardcoded ou commitados.
-
-## Guards, Interceptors e Pipes
-
-- Autenticação/autorização: `Guard` (`CanActivate`), nunca checagem manual de token dentro do controller.
-- Transformação de resposta cross-cutting (ex.: envelope padrão, log de tempo de resposta): `Interceptor`.
-- Validação/transformação de parâmetros individuais: `Pipe` (além do `ValidationPipe` global).
-- Guards/interceptors de autorização específicos de negócio (ex.: "só o dono do pedido pode ver") ficam dentro do módulo de feature correspondente (ex.: `OrderModule`), na camada `infrastructure/adapters/in/` (ver skill `hexagonal`) — nunca em `domain/` (um `Guard`/`Interceptor` sempre importa `@nestjs/common`, o que viola a regra de pureza do domínio) nem em um guard genérico compartilhado por todo o app.
-
-## Logging e observabilidade
-
-- Use o `Logger` do Nest (ou logger estruturado configurado no projeto), nunca `console.log` em código de produção.
-- Logs de erro incluem contexto (ex.: `orderId`, `userId`) mas nunca dados sensíveis (senha, token, PII completo).
-- Toda rota crítica deve ter log de entrada/saída ou métrica associada (latência, taxa de erro) conforme padrão de observabilidade do projeto.
-
-## Testes
-
-- Services/use cases: teste unitário com `Test.createTestingModule` mockando as dependências (ports). Ver skill `jest-testing`.
-- Controllers: teste de integração (`supertest`) cobrindo status code, shape da resposta e validação de DTO.
-- Nunca suba banco real em teste unitário; use fakes/mocks das ports (ver skill `hexagonal`).
-
-## Checklist ao criar/revisar um endpoint
-
-1. Controller só traduz protocolo (sem regra de negócio)?
-2. Request e response têm DTOs próprios e validados?
-3. Erros de domínio são mapeados via `ExceptionFilter`, não `try/catch` ad hoc?
-4. Configuração/segredos vêm de `ConfigService`, não de `process.env` direto?
-5. Existe teste cobrindo o caminho feliz e pelo menos um erro de validação/negócio?
-
-## Não fazer
-
-- Não injetar `Repository`/clients externos diretamente em controllers.
-- Não retornar entidades de domínio/persistência cruas na resposta HTTP.
-- Não usar `any` em parâmetros de rota/body.
-- Não usar `console.log` como mecanismo de log em produção.

package/content/skills/typeorm/SKILL.md

@@ -1,119 +0,0 @@
----
-name: typeorm
-description: Diretrizes de uso do TypeORM como adapter de persistência em projetos NestJS/hexagonal da DS9 — entities, repositórios, migrations, relations, transações e mappers. Use ao criar/alterar entities, repositórios, migrations do TypeORM, ou quando o usuário pedir "entity", "migration TypeORM", "repository" ou "relação" (OneToMany, ManyToMany etc.).
----
-
-# TypeORM — Diretrizes DS9
-
-TypeORM é o ORM padrão para a camada de persistência (`infrastructure/adapters/out/`) nos projetos NestJS/hexagonal da DS9, sobre banco MySQL (ver skill `mysql`). O domínio nunca conhece TypeORM diretamente (ver skill `hexagonal`).
-
-## Localização no projeto
-
-- Entities (`@Entity`), repositórios concretos e migrations ficam em `infrastructure/`, nunca em `domain/` ou `application/`.
-- Entidade de persistência (`OrderEntity`) é uma classe **separada** da entidade de domínio (`Order`). A tradução entre as duas é feita por um `Mapper` dedicado (`OrderMapper.toDomain` / `toPersistence`), conforme a skill `hexagonal`.
-
-## Configuração
-
-- Sempre usar `migrationsRun: false` em produção — migrations rodam explicitamente no pipeline de deploy, nunca automaticamente no boot da aplicação.
-- `synchronize: false` **sempre**, em todos os ambientes (inclusive dev/teste). Schema é controlado só por migrations, nunca por auto-sync do TypeORM (risco de perda de dados em produção).
-- Configuração de conexão vem de `ConfigService` (ver skill `nestjs`), nunca hardcoded.
-
-```typescript
-TypeOrmModule.forRootAsync({
-  useFactory: (config: ConfigService) => ({
-    type: 'mysql',
-    host: config.getOrThrow('DB_HOST'),
-    port: config.getOrThrow('DB_PORT'),
-    synchronize: false,
-    migrationsRun: false,
-    entities: [__dirname + '/**/*.entity{.ts,.js}'],
-    migrations: [__dirname + '/migrations/*{.ts,.js}'],
-  }),
-  inject: [ConfigService],
-});
-```
-
-## Entities
-
-- Nome da classe: `<Nome>Entity` (ex.: `OrderEntity`), tabela em `snake_case` plural via `@Entity('orders')` (ver convenções da skill `mysql`).
-- Toda coluna usa `@Column` com tipo explícito (`type: 'decimal', precision: 19, scale: 4` para dinheiro — nunca deixar o TypeORM inferir tipo monetário).
-- Datas: `@CreateDateColumn()` / `@UpdateDateColumn()` para `created_at`/`updated_at`; `@DeleteDateColumn()` se o projeto usa soft delete (`deleted_at`).
-- Chave primária: `@PrimaryGeneratedColumn()` (auto-increment) ou `@PrimaryGeneratedColumn('uuid')`/`@PrimaryColumn()` conforme a estratégia de ID definida no projeto — manter consistência em todo o schema.
-
-```typescript
-@Entity('orders')
-export class OrderEntity {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ type: 'decimal', precision: 19, scale: 4 })
-  totalAmount: string; // decimal do MySQL vem como string — converter explicitamente no mapper
-
-  @ManyToOne(() => CustomerEntity, { nullable: false })
-  @JoinColumn({ name: 'customer_id' })
-  customer: CustomerEntity;
-
-  @CreateDateColumn({ name: 'created_at' })
-  createdAt: Date;
-
-  @UpdateDateColumn({ name: 'updated_at' })
-  updatedAt: Date;
-}
-```
-
-## Relations
-
-- Declare `@JoinColumn({ name: '...' })` explicitamente em toda relação `@ManyToOne`/`@OneToOne` — nunca deixe o TypeORM inferir o nome da coluna FK.
-- Evite `eager: true` em relations de entidades grandes/listas (causa N+1 e joins não intencionais); prefira carregar explicitamente via `relations: [...]` ou `QueryBuilder` quando necessário.
-- `@ManyToMany` só quando a tabela de junção não tem atributos próprios; se a relação carrega dados extras (ex.: `quantity` em `order_items`), modele como entidade própria com duas `@ManyToOne`.
-- Nunca use `cascade: true` sem necessidade explícita e documentada — cascatas implícitas de delete/update são fonte comum de perda de dados acidental.
-
-## Repositórios (adapters de saída)
-
-- Repositório concreto implementa a `port` definida no domínio (`OrderRepositoryPort`), conforme a skill `hexagonal`; nunca exponha `Repository<OrderEntity>` do TypeORM fora do adapter.
-- Prefira `Repository`/`QueryBuilder` injetado via `@InjectRepository(OrderEntity)` a `EntityManager` cru, exceto em casos que exigem múltiplas entidades na mesma transação.
-- Use `QueryBuilder` (não SQL raw) para queries complexas — mantém parametrização automática (proteção contra SQL Injection) e portabilidade.
-- Pagine toda listagem (`skip`/`take` ou keyset) e nunca retorne `find()` sem filtro em tabelas grandes.
-
-## Migrations
-
-- Gere migrations via CLI (`typeorm migration:generate`) a partir da comparação de entities, e **revise manualmente** o SQL gerado antes de commitar (o gerador pode incluir drops/alters não intencionais).
-- Toda migration tem `up()` e `down()` funcionais — ver regras detalhadas de migration na skill `mysql`.
-- Nomeie migrations com timestamp + descrição clara (`1700000000000-CreateOrdersTable.ts`, `1700000100000-AddStatusToOrders.ts`).
-- Nunca edite uma migration já aplicada em qualquer ambiente compartilhado (dev remoto, homolog, produção); crie uma nova migration corretiva.
-
-## Transações
-
-- Operações que tocam uma única port/agregado usam a transação implícita de cada chamada (`save`, `update`); para operações **cross-aggregate** (múltiplas ports), implemente a `UnitOfWorkPort` definida na skill `hexagonal` usando `DataSource.transaction()`:
-
-```typescript
-// infrastructure/adapters/out/typeorm-unit-of-work.ts
-@Injectable()
-export class TypeOrmUnitOfWork implements UnitOfWorkPort {
-  constructor(private readonly dataSource: DataSource) {}
-
-  async run<T>(work: () => Promise<T>): Promise<T> {
-    return this.dataSource.transaction(async () => work());
-  }
-}
-```
-
-- Dentro de `work()`, os repositórios concretos (`TypeOrmOrderRepository`, `TypeOrmStockRepository`) devem operar sobre o `QueryRunner`/`EntityManager` **da transação ativa**, não sobre o `Repository` injetado globalmente — normalmente resolvido com `AsyncLocalStorage` ou passando o `EntityManager` corrente via contexto de request, conforme o padrão de UoW adotado pelo projeto.
-- Nunca abra uma transação e faça chamadas de rede (HTTP/fila) dentro dela — mantenha transações curtas (ver skill `mysql`).
-- Não implemente a coordenação cross-aggregate manipulando entidades de outro agregado dentro do repositório de um agregado diferente (ex.: `TypeOrmOrderRepository` não deve escrever em `StockEntity`); isso é responsabilidade exclusiva do `UnitOfWorkPort` + use case (ver skill `hexagonal`).
-
-## Checklist ao criar/revisar entity/migration/repositório
-
-1. Entity e migration estão em `infrastructure/`, nunca vazando para `domain/application`?
-2. Tipos de coluna corretos (`decimal` para dinheiro, FKs com `@JoinColumn` explícito)?
-3. `synchronize: false` e migration revisada manualmente?
-4. Repositório implementa a port do domínio e usa `QueryBuilder`/`Repository` parametrizado (sem SQL concatenado)?
-5. Operações multi-entidade usam transação explícita?
-6. Existe mapper `toDomain`/`toPersistence` separando entidade de persistência da entidade de domínio?
-
-## Não fazer
-
-- Não usar `synchronize: true` em nenhum ambiente.
-- Não expor `Entity`/`Repository` do TypeORM fora da camada de infraestrutura.
-- Não usar `cascade: true` ou `eager: true` sem justificativa documentada.
-- Não escrever SQL raw concatenando valores de usuário.