@ds9-solutions/mcp 0.1.0

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

@@ -0,0 +1,88 @@
+---
+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/mysql/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mysql
+description: Diretrizes de modelagem, indexação, migrations, performance e segurança para bancos MySQL/MariaDB usados pelos projetos DS9. Use ao criar/alterar tabelas, escrever migrations, definir índices, revisar queries lentas, ou quando o usuário pedir "schema MySQL", "migration", "índice" ou "otimizar query".
+---
+
+# MySQL — Diretrizes DS9
+
+Convenções obrigatórias para schema, queries e migrations em MySQL (compatível com MariaDB), usadas em conjunto com a skill `typeorm` para a camada de persistência em projetos NestJS/hexagonal.
+
+## Engine e charset
+
+- Engine padrão: `InnoDB` (suporta transações e FKs). Nunca usar `MyISAM` para tabelas transacionais.
+- Charset/collation padrão: `utf8mb4` / `utf8mb4_unicode_ci` (ou `utf8mb4_0900_ai_ci` em MySQL 8+). Nunca `utf8` puro (não suporta 4 bytes/emojis).
+
+## Convenções de nomenclatura
+
+- Tabelas: `snake_case`, plural (`orders`, `order_items`).
+- Colunas: `snake_case` (`created_at`, `customer_id`).
+- Chave primária: `id` (`BIGINT UNSIGNED AUTO_INCREMENT` ou `CHAR(36)`/`BINARY(16)` para UUID — definir por projeto e manter consistente).
+- Chave estrangeira: `<tabela_singular>_id` (`customer_id` referenciando `customers.id`).
+- Índices: `idx_<tabela>_<colunas>`; únicos: `uq_<tabela>_<colunas>`; FKs: `fk_<tabela>_<tabela_referenciada>`.
+
+## Colunas obrigatórias
+
+Toda tabela transacional deve ter:
+
+```sql
+created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+deleted_at DATETIME(3) NULL          -- se o domínio usa soft delete
+```
+
+- Use `DATETIME` (não `TIMESTAMP`) para evitar o limite de ano 2038 e problemas de fuso; grave sempre em UTC na aplicação.
+- Nunca armazene datas/horas como `VARCHAR`.
+
+## Tipos de dados
+
+- Dinheiro/valores monetários: `DECIMAL(19,4)` (nunca `FLOAT`/`DOUBLE`).
+- Texto curto com tamanho conhecido: `VARCHAR(n)` com `n` justificado pelo domínio (evitar `VARCHAR(255)` por padrão sem pensar).
+- Texto longo: `TEXT`/`LONGTEXT` apenas quando necessário (impacta performance de index/row size).
+- Enums de domínio fixo e pequeno: `VARCHAR` + `CHECK` constraint (MySQL 8.0.16+) ou tabela de referência; evite `ENUM` nativo do MySQL (dificulta `ALTER` e não é portável).
+- Booleanos: `TINYINT(1)` (convenção do MySQL; mapeie como `boolean` na aplicação).
+- JSON: tipo nativo `JSON` apenas para dados verdadeiramente semiestruturados, nunca para modelar relações que deveriam ser colunas/tabelas.
+
+## Índices
+
+- Toda FK **precisa** de índice (MySQL não cria automaticamente para colunas de FK em alguns casos — sempre declare explicitamente).
+- Índices compostos: ordem das colunas segue o padrão de consulta (coluna de igualdade antes de coluna de range/order).
+- Evite índices redundantes (um índice composto `(a, b)` já cobre buscas por `a` sozinho).
+- Toda query de produção recorrente deve ter `EXPLAIN` validado antes do merge — sem `type: ALL` (full table scan) em tabelas grandes.
+- Use índice único (`UNIQUE KEY`) para garantir invariantes de negócio no banco (ex.: `email` único), nunca confie só em validação da aplicação.
+
+## Migrations
+
+- Toda alteração de schema é uma migration versionada (via TypeORM migrations — ver skill `typeorm`), nunca alteração manual direto no banco de produção.
+- Migrations são **imutáveis** após merge/deploy: para corrigir, crie uma nova migration (nunca edite uma já aplicada em outro ambiente).
+- Toda migration precisa de `up` e `down` reversível. Se o `down` não for possível com segurança (ex.: `DROP COLUMN`), documente explicitamente no corpo da migration.
+- Alterações em tabelas grandes (`ADD COLUMN`, `ADD INDEX`) em produção devem considerar lock de tabela: preferir `ALGORITHM=INPLACE, LOCK=NONE` quando suportado, e avaliar janela de manutenção para tabelas muito grandes.
+- Nunca faça `DROP TABLE`/`DROP COLUMN` na mesma migration que ainda está em uso por código em produção (deploy em etapas: parar de usar → migration de remoção).
+
+## Transações
+
+- Operações que alteram múltiplas tabelas com invariantes relacionadas (ex.: criar pedido + baixar estoque) **devem** rodar em uma transação explícita.
+- Nível de isolamento padrão do InnoDB é `REPEATABLE READ`; use `SELECT ... FOR UPDATE` quando precisar de lock pessimista para evitar race conditions em concorrência (ex.: controle de estoque, saldo).
+- Mantenha transações curtas: nunca faça chamadas de rede (HTTP, fila) dentro de uma transação de banco aberta.
+
+## Queries
+
+- Nunca concatene valores de usuário diretamente em SQL — sempre use *prepared statements*/query builder parametrizado (via TypeORM). Isso é mandatório contra SQL Injection.
+- Evite `SELECT *`; liste as colunas necessárias, especialmente em tabelas largas.
+- Pagine toda listagem (`LIMIT`/`OFFSET` ou keyset pagination para datasets grandes); nunca retorne uma tabela inteira sem limite.
+- Prefira keyset pagination (`WHERE id > :lastId ORDER BY id LIMIT :n`) a `OFFSET` alto em tabelas grandes (OFFSET grande é O(n)).
+
+## Segurança e acesso
+
+- Usuário da aplicação nunca deve ter privilégio `SUPER`, `GRANT OPTION` ou DDL (`CREATE`/`DROP`/`ALTER`) em produção — apenas `SELECT`, `INSERT`, `UPDATE`, `DELETE` nas tabelas do próprio schema. Migrations rodam com usuário/privilégio separado (pipeline de deploy).
+- Nunca commitar credenciais de conexão; usar variáveis de ambiente/secret manager (ver README do MCP).
+- Dados sensíveis (PII, senha, token) nunca em texto plano: hash (ex.: `bcrypt`/`argon2`) para senha, criptografia em nível de aplicação para PII quando exigido por compliance.
+
+## Checklist ao revisar schema/migration/query
+
+1. Engine `InnoDB`, charset `utf8mb4`?
+2. Nomenclatura `snake_case` consistente e FKs com índice?
+3. Tipos corretos (`DECIMAL` para dinheiro, sem `ENUM` nativo, sem `VARCHAR` para datas)?
+4. Migration tem `up`/`down`, é aditiva/segura para produção?
+5. Query usa parâmetros (sem concatenação), tem `LIMIT`, e passou por `EXPLAIN`?
+6. Alterações concorrentes têm transação e/ou lock explícito quando necessário?
+
+## Não fazer
+
+- Não usar `SELECT *` em código de produção.
+- Não usar `FLOAT`/`DOUBLE` para valores monetários.
+- Não rodar DDL manual direto em produção fora de migration versionada.
+- Não deixar queries sem paginação em endpoints de listagem.

package/content/skills/nestjs/SKILL.md

@@ -0,0 +1,100 @@
+---
+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

@@ -0,0 +1,119 @@
+---
+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.

package/content/skills/typescript/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: typescript
+description: Convenções de TypeScript da DS9 — tipagem estrita, modelagem de domínio, tratamento de erros, imports e estilo de código. Use ao escrever ou revisar qualquer código TypeScript (independente de framework), definir tipos/interfaces, ou quando o usuário pedir "tipagem", "strict mode" ou "boas práticas TypeScript".
+---
+
+# TypeScript — Diretrizes DS9
+
+Convenções de código TypeScript aplicáveis a qualquer projeto da empresa, incluindo os que usam NestJS (skill `nestjs`) e arquitetura hexagonal (skill `hexagonal`).
+
+## Configuração do compilador
+
+- `strict: true` obrigatório no `tsconfig.json` (ativa `strictNullChecks`, `noImplicitAny`, etc.). Não desative flags de strict mode isoladamente sem justificativa documentada.
+- `noUnusedLocals` e `noUnusedParameters` ativados — código morto não compila.
+- `noImplicitReturns` e `noFallthroughCasesInSwitch` ativados para evitar bugs de controle de fluxo.
+
+## Tipagem
+
+- Proibido `any` explícito em código novo. Quando o tipo é genuinamente desconhecido (ex.: payload externo não tipado), use `unknown` e faça *narrowing* explícito antes de usar.
+- Prefira `interface` para formas de objeto/contratos públicos (ports, DTOs) e `type` para unions, intersections e tipos utilitários.
+- Nunca use type assertion (`as Tipo`) para "calar" o compilador sem validação real; prefira type guards (`function isOrder(x: unknown): x is Order`).
+- Habilite e respeite `readonly` em propriedades que não devem mudar após criação (especialmente em entidades de domínio e DTOs).
+
+```typescript
+// Evitar
+function handle(payload: any) { return payload.items.map((i: any) => i.id); }
+
+// Preferir
+interface OrderPayload { items: Array<{ id: string }>; }
+function handle(payload: OrderPayload) { return payload.items.map((i) => i.id); }
+```
+
+## Modelagem de domínio
+
+- Use *value objects* para conceitos com regras próprias (ex.: `Email`, `Money`), em vez de `string`/`number` soltos, quando o projeto já segue esse padrão (ver skill `hexagonal`).
+- Invariantes de negócio são validadas no construtor/factory da entidade (`Order.create(...)`), lançando erro de domínio em vez de permitir estado inválido existir.
+- Prefira classes/funções imutáveis (métodos retornam uma nova instância) para entidades de domínio sensíveis a concorrência, salvo quando o projeto adota mutação controlada por padrão.
+
+## Tratamento de erros
+
+- Erros de domínio são classes que estendem `Error`, com nome específico (`class OrderNotFoundError extends Error`), nunca `throw` de string ou objeto genérico (`throw 'erro'` é proibido).
+- Nunca capture um erro (`catch`) só para logar e relançar sem adicionar contexto; se não for tratar, deixe propagar.
+- Funções assíncronas que podem falhar previsivelmente (ex.: "não encontrado") devem deixar isso explícito no tipo de retorno (`Promise<Order | null>`) quando fizer sentido, em vez de forçar o chamador a sempre usar `try/catch`.
+
+## Imports e organização de módulos
+
+- Imports absolutos/com alias (`@app/domain/...`) para cruzar camadas, imports relativos (`./`, `../`) dentro do mesmo módulo/camada — configurar via `paths` no `tsconfig.json`.
+- Nunca import circular entre módulos; se ocorrer, é sinal de fronteira de módulo mal definida (revisar com a skill `hexagonal`).
+- Um export principal por arquivo quando possível (facilita navegação e testes); evite arquivos "barril" (`index.ts`) gigantes que reexportam dezenas de símbolos sem necessidade.
+
+## Nulidade e valores opcionais
+
+- Prefira `T | null` para "ausência de valor conhecida" e `T | undefined`/parâmetro opcional (`param?: T`) para "valor não fornecido". Seja consistente dentro do mesmo módulo.
+- Nunca use `!` (non-null assertion) para contornar `strictNullChecks` sem uma garantia real logo acima no código (ex.: dentro de um `if` que já checou).
+
+## Nomenclatura
+
+- Classes/interfaces/tipos: `PascalCase`. Variáveis/funções: `camelCase`. Constantes verdadeiramente globais/imutáveis: `UPPER_SNAKE_CASE`.
+- Nomes de função descrevem a ação (`calculateTotal`, não `total` ou `doIt`); booleanos começam com `is`/`has`/`should` (`isValid`, `hasDiscount`).
+- Evite abreviações não óbvias (`qty` ok se for convenção do domínio; `tmp`, `data2` não).
+- Nome de **arquivo**: `kebab-case`, com sufixo que indica o papel do arquivo quando aplicável (`order-repository.port.ts`, `create-order.use-case.ts`, `typeorm-order.repository.ts`, `order.entity.ts`, `order.controller.ts`, `order.module.ts`). Arquivo de teste usa o mesmo nome base + `.spec.ts`/`.e2e-spec.ts` (ver skill `jest-testing`).
+
+## Checklist ao escrever/revisar código TypeScript
+
+1. Existe algum `any` que poderia ser `unknown` + narrowing, ou um tipo concreto?
+2. Erros são classes nomeadas, não strings/objetos genéricos?
+3. Nenhum `as Tipo`/`!` sem uma garantia lógica imediatamente visível?
+4. Nomes de variáveis/funções comunicam intenção sem precisar ler a implementação?
+5. O `tsconfig.json` do projeto mantém `strict: true` e nenhuma flag de strict foi desabilitada pontualmente?
+
+## Não fazer
+
+- Não usar `any` em código novo.
+- Não usar `// @ts-ignore` para silenciar erro de tipo sem comentário explicando o motivo e um plano de correção.
+- Não lançar (`throw`) valores que não sejam instância de `Error`.
+- Não criar imports circulares entre módulos/camadas.

package/dist/src/content.js

@@ -0,0 +1,98 @@
+/**
+ * Loader de conteúdo: lê as skills e os agentes (arquivos Markdown) do disco e os
+ * transforma em uma lista de `Entry` em memória.
+ *
+ * Por que existe: o servidor MCP não tem conhecimento embutido sobre nenhuma skill/agente.
+ * Tudo vem dos arquivos, então adicionar/editar/remover um `.md` não exige mexer em código.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+// Frontmatter = bloco YAML entre dois `---` no topo do arquivo. Aceita \r\n porque os arquivos
+// podem ter sido salvos no Windows.
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/**
+ * Separa o frontmatter (metadados) do corpo Markdown.
+ * Sem frontmatter, devolve o texto inteiro como corpo, para não perder conteúdo.
+ */
+export function parseFrontmatter(raw) {
+    const match = FRONTMATTER.exec(raw);
+    if (!match)
+        return { data: {}, body: raw };
+    return { data: (parseYaml(match[1]) ?? {}), body: match[2].trim() };
+}
+/**
+ * Descobre onde estão `skills/` e `agents/`. Testa várias origens, em ordem, porque o mesmo código
+ * roda em contextos diferentes:
+ *  1. `DS9_MCP_CONTENT` — override manual (útil para depurar com outro conteúdo);
+ *  2. `content/` na raiz do pacote — o caso de produção (copiado pelo `sync-content` no npm pack);
+ *  3. `plugins/ds9-mcp/` do monorepo — o caso de desenvolvimento, sem precisar sincronizar.
+ * A mistura de `..` existe porque o arquivo roda de `dist/src/` (compilado) ou de `src/`.
+ */
+export function resolveContentRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        process.env.DS9_MCP_CONTENT,
+        join(here, "..", "content"),
+        join(here, "..", "..", "content"),
+        join(here, "..", "..", "..", "plugins", "ds9-mcp"),
+        join(here, "..", "..", "..", "..", "plugins", "ds9-mcp"),
+    ];
+    for (const c of candidates) {
+        if (c && existsSync(join(c, "skills")))
+            return c;
+    }
+    throw new Error("Conteúdo (skills/agents) não encontrado. Rode `npm run sync-content`.");
+}
+/**
+ * Carrega todas as skills e agentes.
+ * Skill = `skills/<pasta>/SKILL.md` (id = nome da pasta).
+ * Agente = `agents/<nome>.agent.md` (id = nome do arquivo; estrutura plana, sem subpastas).
+ */
+export function loadEntries(root = resolveContentRoot()) {
+    const entries = [];
+    const warnings = [];
+    const skillsDir = join(root, "skills");
+    for (const dirent of readdirSync(skillsDir, { withFileTypes: true })) {
+        const file = join(skillsDir, dirent.name, "SKILL.md");
+        // Ignora arquivos soltos e pastas sem SKILL.md em vez de quebrar o servidor inteiro.
+        if (!dirent.isDirectory() || !existsSync(file))
+            continue;
+        const { data, body } = parseFrontmatter(readFileSync(file, "utf8"));
+        // Regra do AGENTS.md: `name` da skill deve ser idêntico ao nome da pasta. Só avisamos (não
+        // falhamos) para que uma skill mal formatada não derrube o acesso às demais.
+        if (data.name !== dirent.name) {
+            warnings.push(`skill "${dirent.name}": frontmatter name ("${String(data.name)}") difere da pasta`);
+        }
+        entries.push({
+            kind: "skill",
+            id: dirent.name,
+            name: String(data.name ?? dirent.name),
+            description: String(data.description ?? ""),
+            body,
+        });
+    }
+    const agentsDir = join(root, "agents");
+    if (existsSync(agentsDir)) {
+        for (const file of readdirSync(agentsDir)) {
+            if (!file.endsWith(".agent.md"))
+                continue;
+            const id = file.slice(0, -".agent.md".length);
+            const { data, body } = parseFrontmatter(readFileSync(join(agentsDir, file), "utf8"));
+            entries.push({
+                kind: "agent",
+                id,
+                // O `name` do agente é um rótulo de exibição ("Code Reviewer"); o id estável é o arquivo.
+                name: String(data.name ?? id),
+                description: String(data.description ?? ""),
+                body,
+            });
+        }
+    }
+    // stderr, nunca stdout: no transporte stdio o stdout é o canal do protocolo MCP, e qualquer
+    // texto extra nele corromperia a comunicação com a IDE.
+    for (const w of warnings)
+        console.error(`[ds9-mcp] aviso: ${w}`);
+    return entries;
+}

package/dist/src/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Ponto de entrada do pacote (o `bin` do npm aponta para este arquivo).
+ * Um único executável, dois modos:
+ *   - `ds9-mcp`        -> sobe o servidor MCP via stdio (é o que a IDE executa);
+ *   - `ds9-mcp init`   -> configura a IDE do usuário e sai.
+ * Manter os dois no mesmo comando permite que o `npx -y @ds9-solutions/mcp` sirva a ambos.
+ */
+import { createInterface } from "node:readline/promises";
+import { readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEntries } from "./content.js";
+import { createServer } from "./server.js";
+import { TARGETS, runInit } from "./init.js";
+// A versão vem do package.json para existir uma única fonte (o que foi publicado no npm).
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+/** Lê `--nome valor` dos argumentos. Parser mínimo de propósito: evita uma dependência de CLI. */
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i !== -1 ? args[i + 1] : undefined;
+}
+/** Modo `init`: escolhe a IDE (por `--ide` ou perguntando) e grava a configuração. */
+async function init(args) {
+    let ide = flag(args, "ide");
+    if (!ide) {
+        // Sem `--ide`, pergunta de forma interativa para o caso de uso "rodei e pronto".
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        console.log("Em qual IDE/agente configurar o MCP ds9?");
+        TARGETS.forEach((t, i) => console.log(`  ${i + 1}) ${t.label}`));
+        const answer = (await rl.question("Número: ")).trim();
+        rl.close();
+        ide = TARGETS[Number(answer) - 1]?.id;
+    }
+    const target = TARGETS.find((t) => t.id === ide);
+    if (!target) {
+        console.error(`IDE inválida. Opções: ${TARGETS.map((t) => t.id).join(", ")}`);
+        process.exit(1);
+    }
+    const result = runInit(target, flag(args, "dir") ?? process.cwd(), {
+        agentsMd: !args.includes("--no-agents-md"),
+    });
+    console.log(`✔ MCP ds9 configurado em ${result.configFile}`);
+    if (result.agentsFile)
+        console.log(`✔ Instruções adicionadas em ${result.agentsFile}`);
+    console.log("Reinicie a IDE/agente para carregar o servidor.");
+}
+/** Modo servidor: carrega o conteúdo e fica atendendo a IDE pela entrada/saída padrão. */
+async function serve() {
+    const server = createServer(loadEntries(), pkg.version);
+    await server.connect(new StdioServerTransport());
+    // stderr: o stdout pertence ao protocolo MCP e não pode receber logs.
+    console.error(`[ds9-mcp] v${pkg.version} pronto (stdio)`);
+}
+// Qualquer erro vira mensagem curta + código de saída 1, em vez de um stack trace assustador.
+const [command, ...rest] = process.argv.slice(2);
+(command === "init" ? init(rest) : serve()).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});