@ds9-solutions/mcp 0.1.0 → 0.3.0

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.

package/dist/test/mcp.test.js

@@ -1,112 +0,0 @@
-/**
- * Testes do pacote, com o runner nativo do Node (`node:test`).
- *
- * Por que `node:test`: evita configurar Jest + ts-jest com ESM e não adiciona dependência.
- * Os testes usam o conteúdo REAL do plugin, então também falham se alguém quebrar o frontmatter
- * de uma skill ou agente (ex.: remover a `description`).
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { loadEntries, parseFrontmatter } from "../src/content.js";
-import { createServer } from "../src/server.js";
-import { rankByMetadata, searchBodies } from "../src/search.js";
-import { TARGETS, mergeServerConfig, runInit, upsertAgentsBlock } from "../src/init.js";
-const entries = loadEntries();
-/**
- * Conecta um cliente MCP de verdade ao servidor, em memória (sem processo nem stdio). Assim os
- * testes exercitam o protocolo completo — o mesmo caminho que uma IDE usaria.
- */
-async function connect() {
-    const [a, b] = InMemoryTransport.createLinkedPair();
-    const client = new Client({ name: "test", version: "0" });
-    await Promise.all([createServer(entries).connect(a), client.connect(b)]);
-    return client;
-}
-// Extrai o texto da primeira parte de uma resposta de tool.
-const firstText = (r) => r.content[0].text;
-test("parseFrontmatter separa frontmatter e corpo", () => {
-    const { data, body } = parseFrontmatter("---\nname: x\ndescription: d\n---\n\n# Corpo\n");
-    assert.equal(data.name, "x");
-    assert.equal(body, "# Corpo");
-});
-test("loader carrega skills e agentes reais", () => {
-    assert.ok(entries.some((e) => e.kind === "skill" && e.id === "nestjs"));
-    assert.ok(entries.some((e) => e.kind === "agent" && e.id === "code-reviewer"));
-    // A description alimenta o ranking do `recommend_for_task`; sem ela a entrada fica invisível.
-    assert.ok(entries.every((e) => e.description.length > 0));
-});
-test("rankByMetadata prioriza a skill relevante", () => {
-    const top = rankByMetadata(entries, "criar Dockerfile multi-stage", "skill")[0];
-    assert.equal(top.entry.id, "docker");
-});
-test("searchBodies encontra trechos", () => {
-    assert.ok(searchBodies(entries, "migration").length > 0);
-    // "a" é stopword/1 letra: a consulta vira vazia e não deve devolver tudo.
-    assert.deepEqual(searchBodies(entries, "a"), []);
-});
-test("tools: list, get, erro em id inexistente, recommend", async () => {
-    const client = await connect();
-    const tools = (await client.listTools()).tools.map((t) => t.name);
-    for (const n of [
-        "list_skills",
-        "get_skill",
-        "list_agents",
-        "get_agent",
-        "search_guidelines",
-        "recommend_for_task",
-    ]) {
-        assert.ok(tools.includes(n), n);
-    }
-    assert.match(firstText(await client.callTool({ name: "list_skills", arguments: {} })), /hexagonal/);
-    assert.match(firstText(await client.callTool({ name: "get_skill", arguments: { name: "docker" } })), /Skill: docker/);
-    // Id inexistente deve ser um erro "de uso" (isError), não uma exceção do protocolo.
-    const missing = await client.callTool({ name: "get_agent", arguments: { name: "nope" } });
-    assert.equal(missing.isError, true);
-    assert.match(firstText(await client.callTool({
-        name: "recommend_for_task",
-        arguments: { task: "revisar segurança de código" },
-    })), /security-reviewer/);
-});
-test("prompts e resources expostos", async () => {
-    const client = await connect();
-    assert.ok((await client.listPrompts()).prompts.some((p) => p.name === "skill-nestjs"));
-    const res = await client.listResources();
-    assert.ok(res.resources.some((r) => r.uri === "ds9://skills/typeorm"));
-    const read = await client.readResource({ uri: "ds9://agents/test-writer" });
-    assert.match(read.contents[0].text, /Agente: test-writer/);
-});
-test("mergeServerConfig preserva outros servidores e é idempotente", () => {
-    const cursor = TARGETS.find((t) => t.id === "cursor");
-    const once = mergeServerConfig({ mcpServers: { outro: { command: "x" } } }, cursor, "linux");
-    // O servidor que o usuário já tinha ("outro") não pode ser perdido.
-    assert.deepEqual(Object.keys(once.mcpServers).sort(), ["ds9", "outro"]);
-    // Rodar de novo não pode mudar nada.
-    assert.deepEqual(mergeServerConfig(once, cursor, "linux"), once);
-    // VS Code usa `servers` + `type: stdio`; no Windows o comando passa por `cmd /c`.
-    const vscode = TARGETS.find((t) => t.id === "vscode");
-    const v = mergeServerConfig({}, vscode, "win32");
-    assert.equal(v.servers.ds9.type, "stdio");
-    assert.equal(v.servers.ds9.command, "cmd");
-});
-test("upsertAgentsBlock insere uma vez e atualiza sem duplicar", () => {
-    const once = upsertAgentsBlock("# Meu projeto\n");
-    assert.match(once, /# Meu projeto/); // conteúdo prévio preservado
-    assert.equal(upsertAgentsBlock(once), once); // segunda execução não muda nada
-    assert.equal(once.match(/ds9-mcp:start/g)?.length, 1); // bloco nunca duplica
-});
-test("runInit grava config e AGENTS.md; recusa JSON inválido", () => {
-    // Diretório temporário: o teste nunca toca em arquivos reais do usuário.
-    const dir = mkdtempSync(join(tmpdir(), "ds9-init-"));
-    const cursor = TARGETS.find((t) => t.id === "cursor");
-    const r = runInit(cursor, dir);
-    assert.ok(JSON.parse(readFileSync(r.configFile, "utf8")).mcpServers.ds9);
-    assert.match(readFileSync(r.agentsFile, "utf8"), /recommend_for_task/);
-    // Arquivo com comentário (JSONC) não pode ser sobrescrito: deve falhar com orientação.
-    writeFileSync(join(dir, ".mcp.json"), "{ // comentário\n}");
-    assert.throws(() => runInit(TARGETS[0], dir), /não é JSON puro/);
-});