@ds9-solutions/mcp 0.1.0 → 0.3.0

package/dist/src/server.js

@@ -9,12 +9,14 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { rankByMetadata, searchBodies } from "./search.js";
+import { isSafeRelativePath, MAX_PATH_LENGTH, SKILL_ID } from "./skill-files.js";
 // Enviado ao host no handshake. Hosts sem suporte nativo a skills/agentes dependem disto (e do
 // bloco no AGENTS.md) para saber que devem consultar o servidor antes de implementar.
 const INSTRUCTIONS = [
     "Servidor de diretrizes oficiais da DS9 (skills por tecnologia e subagentes especializados).",
     "Antes de implementar, revisar ou testar código, chame `recommend_for_task` com a descrição da tarefa",
     "e depois `get_skill` / `get_agent` para ler as diretrizes recomendadas e segui-las.",
+    "Se a skill indicar arquivos complementares, use `list_skill_files` e `get_skill_file` para ler exemplos e referências sob demanda.",
 ].join(" ");
 // Monta a resposta padrão de uma tool. `isError` sinaliza ao LLM que a chamada falhou, mas sem
 // derrubar o protocolo (erro de uso != erro do servidor).
@@ -31,8 +33,21 @@ export function createServer(entries, version = "0.0.0") {
     // Helpers de consulta sobre as entradas.
     const byKind = (kind) => entries.filter((e) => e.kind === kind);
     const find = (kind, id) => entries.find((e) => e.kind === kind && e.id === id);
-    const render = (e) => `# ${e.kind === "skill" ? "Skill" : "Agente"}: ${e.id}\n\n> ${e.description}\n\n${e.body}`;
-    const listing = (items) => items.map((e) => `- ${e.id}: ${e.description}`).join("\n") || "(nenhum resultado)";
+    const render = (e) => `# ${e.kind === "skill" ? "Skill" : "Agente"}: ${e.id}\n\n> ${e.description}\n\n${e.body}` +
+        (e.files.length
+            ? `\n\n---\nArquivos complementares (${e.files.length}): use \`list_skill_files\` e \`get_skill_file\` com skill="${e.id}" para exemplos e referências sob demanda.`
+            : "");
+    const listing = (items) => items
+        .map((e) => `- ${e.id}: ${e.description}${e.files.length ? ` (+${e.files.length} arquivos)` : ""}`)
+        .join("\n") || "(nenhum resultado)";
+    // Erros de skill/arquivo nunca citam caminhos do disco: só ids e caminhos do índice.
+    const skillOrError = (skill) => {
+        const entry = find("skill", skill);
+        return entry
+            ? { entry }
+            : { error: text(`skill "${skill}" não encontrada. Disponíveis:\n${listing(byKind("skill"))}`, true) };
+    };
+    const fileList = (e) => e.files.map((f) => `- ${f.path} (${f.size} bytes)${f.description ? `: ${f.description}` : ""}`).join("\n");
     // Skills e agentes têm exatamente a mesma API (list/get/prompt/resource). Em vez de duplicar o
     // código, registramos os dois em um laço; só mudam os nomes e os rótulos.
     for (const [kind, plural, label] of [
@@ -63,7 +78,7 @@ export function createServer(entries, version = "0.0.0") {
             }
             return text(render(entry));
         });
-        // Um prompt por entrada (ex.: `skill-nestjs`). Fica estático porque o catálogo é conhecido na
+        // Um prompt por entrada (ex.: `skill-hex-pattern-dart`). Fica estático porque o catálogo é conhecido na
         // inicialização do servidor.
         for (const entry of byKind(kind)) {
             server.registerPrompt(`${kind}-${entry.id}`, { description: entry.description }, () => ({
@@ -91,6 +106,45 @@ export function createServer(entries, version = "0.0.0") {
             return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: render(entry) }] };
         });
     }
+    // list_skill_files / get_skill_file — carga sob demanda dos arquivos complementares de uma skill.
+    // Só leem o índice em memória montado no carregamento; o cliente nunca informa caminho de disco.
+    const skillSchema = z
+        .string()
+        .regex(SKILL_ID, "id de skill inválido")
+        .describe("Id da skill (veja list_skills)");
+    server.registerTool("list_skill_files", {
+        description: "Lista os arquivos complementares (exemplos, referências) de uma skill DS9, com tamanho e descrição.",
+        inputSchema: { skill: skillSchema },
+        annotations: { readOnlyHint: true },
+    }, async ({ skill }) => {
+        const { entry, error } = skillOrError(skill);
+        if (!entry)
+            return error;
+        return text(entry.files.length
+            ? `Arquivos da skill "${skill}" (leia com get_skill_file):\n${fileList(entry)}`
+            : `A skill "${skill}" não possui arquivos complementares.`);
+    });
+    server.registerTool("get_skill_file", {
+        description: "Retorna o conteúdo de um arquivo complementar de uma skill DS9. Use o caminho exato de list_skill_files.",
+        inputSchema: {
+            skill: skillSchema,
+            path: z
+                .string()
+                .max(MAX_PATH_LENGTH)
+                .describe("Caminho relativo listado por list_skill_files, ex.: examples/entity.dart"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ skill, path }) => {
+        const { entry, error } = skillOrError(skill);
+        if (!entry)
+            return error;
+        // Busca exata no índice: caminhos fora dele (inclusive `..`, absolutos etc.) simplesmente não existem.
+        const file = isSafeRelativePath(path) ? entry.files.find((f) => f.path === path) : undefined;
+        if (!file) {
+            return text(`Arquivo não encontrado na skill "${skill}". Arquivos válidos:\n${fileList(entry) || "(nenhum)"}`, true);
+        }
+        return text(`# ${skill}/${file.path}\n\n${file.text}`);
+    });
     // search_guidelines — para dúvidas pontuais ("como nomear migrations?") sem ler arquivos inteiros.
     server.registerTool("search_guidelines", {
         description: "Busca um termo no conteúdo de todas as skills e agentes DS9 e devolve as linhas mais relevantes.",
@@ -99,7 +153,9 @@ export function createServer(entries, version = "0.0.0") {
     }, async ({ query, limit }) => {
         const hits = searchBodies(entries, query, limit ?? 8);
         return text(hits.length
-            ? hits.map((h) => `[${h.kind}:${h.id}:L${h.line}] ${h.text}`).join("\n")
+            ? hits
+                .map((h) => `[${h.kind}:${h.id}${h.file ? `:${h.file}` : ""}:L${h.line}] ${h.text}`)
+                .join("\n")
             : "Nenhum trecho encontrado.");
     });
     // recommend_for_task — é a "ativação automática" possível via MCP: compensa a falta de roteamento

package/dist/src/skill-files.js

@@ -0,0 +1,125 @@
+/**
+ * Arquivos complementares de uma skill (`skills/<id>/examples/`, `references/` etc.).
+ *
+ * Segurança — por que é uma allowlist e não uma sanitização de caminho:
+ *  - tudo é indexado UMA vez, no carregamento, pelo próprio servidor;
+ *  - `get_skill_file` só encontra caminhos que estão nesse índice (comparação exata de string);
+ *  - o texto vem da memória: nenhuma chamada de tool toca o disco nem monta caminho com entrada do
+ *    cliente. Não há como escapar da pasta da skill porque o cliente nunca fornece um caminho de
+ *    arquivo, apenas uma chave de busca.
+ * A varredura ainda aplica limites e ignora symlinks, ocultos e extensões fora da lista.
+ */
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+export const ALLOWED_EXTENSIONS = new Set([
+    ".md",
+    ".dart",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".txt",
+]);
+export const MAX_FILE_BYTES = 100 * 1024;
+export const MAX_FILES_PER_SKILL = 200;
+export const MAX_DEPTH = 4;
+export const MAX_PATH_LENGTH = 200;
+// SKILL.md é servido por `get_skill`; README.md não é copiado pelo `sync-content`, então ignorá-lo
+// aqui mantém o comportamento igual em desenvolvimento e em produção.
+const IGNORED_NAMES = new Set(["skill.md", "readme.md", "node_modules"]);
+/** Id de skill válido: é o nome da pasta, em kebab-case. */
+export const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+ * Valida o formato do caminho informado pelo cliente. É uma barreira extra de entrada; a proteção
+ * real é a busca exata no índice. Rejeita tudo que não seja um caminho relativo simples com `/`.
+ */
+export function isSafeRelativePath(path) {
+    if (path.length === 0 || path.length > MAX_PATH_LENGTH)
+        return false;
+    if (CONTROL_CHARS.test(path))
+        return false;
+    if (path.includes("\\") || path.includes(":") || path.includes("%"))
+        return false;
+    if (path.startsWith("/"))
+        return false;
+    return path.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+/** Primeira linha útil do arquivo: título Markdown ou comentário `///`/`//`. */
+function describe(text) {
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const cleaned = line.replace(/^(#+|\/\/\/?|\*|>)\s*/, "").trim();
+        if (cleaned && cleaned !== "---")
+            return cleaned.slice(0, 160);
+    }
+    return "";
+}
+/**
+ * Varre a pasta de uma skill e devolve os arquivos complementares permitidos, em ordem estável.
+ * Problemas (arquivo grande, extensão proibida, symlink etc.) viram avisos e o arquivo é ignorado:
+ * um item ruim nunca derruba o carregamento das demais skills.
+ */
+export function scanSkillFiles(skillDir, warnings) {
+    const files = [];
+    const rootReal = realpathSync(skillDir);
+    const walk = (dir, prefix, depth) => {
+        for (const name of readdirSync(dir).sort()) {
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const abs = join(dir, name);
+            if (name.startsWith(".") || IGNORED_NAMES.has(name.toLowerCase()))
+                continue;
+            const stat = lstatSync(abs);
+            if (stat.isSymbolicLink()) {
+                warnings.push(`"${rel}" ignorado: link simbólico`);
+                continue;
+            }
+            if (stat.isDirectory()) {
+                if (depth >= MAX_DEPTH)
+                    warnings.push(`"${rel}" ignorado: profundidade acima de ${MAX_DEPTH}`);
+                else
+                    walk(abs, rel, depth + 1);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            const ext = name.includes(".") ? name.slice(name.lastIndexOf(".")).toLowerCase() : "";
+            if (!ALLOWED_EXTENSIONS.has(ext)) {
+                warnings.push(`"${rel}" ignorado: extensão não permitida`);
+                continue;
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                warnings.push(`"${rel}" ignorado: maior que ${MAX_FILE_BYTES} bytes`);
+                continue;
+            }
+            if (files.length >= MAX_FILES_PER_SKILL) {
+                warnings.push(`"${rel}" ignorado: limite de ${MAX_FILES_PER_SKILL} arquivos por skill`);
+                continue;
+            }
+            if (!rel.split("/").every((s) => isSafeRelativePath(s))) {
+                warnings.push(`"${rel}" ignorado: nome de arquivo inválido`);
+                continue;
+            }
+            // Confinamento: o arquivo real precisa estar dentro da pasta da skill.
+            const real = realpathSync(abs);
+            if (!real.startsWith(rootReal + sep)) {
+                warnings.push(`"${rel}" ignorado: fora da pasta da skill`);
+                continue;
+            }
+            let text;
+            try {
+                text = UTF8.decode(readFileSync(real));
+            }
+            catch {
+                warnings.push(`"${rel}" ignorado: não é texto UTF-8 válido`);
+                continue;
+            }
+            files.push({ path: rel, size: stat.size, description: describe(text), text });
+        }
+    };
+    walk(skillDir, "", 1);
+    return files;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds9-solutions/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Servidor MCP da DS9: expõe skills e subagentes oficiais para qualquer IDE/LLM com suporte a MCP",
   "type": "module",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
     "ds9-mcp": "dist/src/index.js"
   },
   "files": [
-    "dist",
+    "dist/src",
     "content"
   ],
   "engines": {

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`.