@dewtech/dare-cli 2.17.0 → 3.0.0

package/templates/ide/antigravity/.agents/skills/skill-mcp-server/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: skill-mcp-server
+description: Padrões DARE para servidores MCP (Model Context Protocol) em TypeScript ou Python. Define tools, resources, prompts; suporta transports stdio, SSE e HTTP; validação Zod/Pydantic; autorização por tool; tracing estruturado; testes; publicação no MCP registry.
+---
+
+# DARE MCP Server Skill
+
+Você é um especialista em servidores MCP (Model Context Protocol da Anthropic). Seu papel é gerar servidores MCP **bem estruturados, seguros, testáveis e publicáveis**, expondo tools/resources/prompts via stdio, SSE ou HTTP.
+
+## Quando usar
+
+- Você precisa expor capacidades para Claude Code, Cursor ou outro cliente MCP
+- Você quer integrar uma API externa (Linear, GitHub, banco interno) como tool MCP
+- Você está auditando um servidor MCP existente
+
+## O que é MCP em 30 segundos
+
+MCP (Model Context Protocol) é um protocolo aberto da Anthropic para conectar agentes a fontes de dados e ações externas. Um servidor MCP expõe:
+
+- **Tools** — funções chamáveis pelo agente (ex: `create_issue`, `query_db`)
+- **Resources** — dados leitáveis (ex: documentos, schemas)
+- **Prompts** — templates parametrizados
+
+Transports suportados:
+- **stdio** — agente spawnea processo local, comunica via stdin/stdout (mais simples)
+- **SSE** — server remoto, agente conecta via Server-Sent Events
+- **HTTP** — server remoto stateless
+
+## Stack canônica (TypeScript)
+
+- **Node 20+** com TypeScript 5.5+
+- **@modelcontextprotocol/sdk** SDK oficial
+- **Zod** para validação de input/output de tools
+- **vitest** para testes
+- **eslint + prettier**
+
+## Stack canônica (Python)
+
+- **Python 3.11+**
+- **mcp** SDK oficial (`pip install mcp`)
+- **Pydantic v2** para schemas
+- **pytest + pytest-asyncio**
+- **ruff + mypy**
+
+## Estrutura recomendada (TypeScript)
+
+```
+mcp-meu-server/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts                ← entrypoint (stdio)
+│   ├── server.ts               ← criação do MCP Server
+│   ├── tools/
+│   │   ├── create_issue.ts
+│   │   └── search_issues.ts
+│   ├── resources/
+│   │   └── schema.ts
+│   ├── prompts/
+│   │   └── issue_template.ts
+│   ├── schemas/                ← Zod schemas
+│   └── lib/
+│       └── linear-client.ts    ← cliente da API externa
+└── tests/
+```
+
+## Exemplo: server stdio TypeScript
+
+```typescript
+// src/index.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools/index.js';
+import { registerResources } from './resources/index.js';
+
+const server = new Server(
+  { name: 'meu-mcp-server', version: '1.0.0' },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+registerTools(server);
+registerResources(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Definindo uma tool
+
+```typescript
+// src/tools/create_issue.ts
+import { z } from 'zod';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const CreateIssueInput = z.object({
+  title: z.string().min(1).max(255),
+  description: z.string().optional(),
+  priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  team_id: z.string().uuid(),
+});
+
+const CreateIssueOutput = z.object({
+  id: z.string(),
+  url: z.string().url(),
+  number: z.number(),
+});
+
+export function register(server: Server) {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [{
+      name: 'create_issue',
+      description: 'Create a new issue in Linear',
+      inputSchema: CreateIssueInput.shape,  // ou gerar via zod-to-json-schema
+    }],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (req.params.name !== 'create_issue') {
+      throw new Error('unknown tool');
+    }
+    const input = CreateIssueInput.parse(req.params.arguments);
+    const result = await linearClient.createIssue(input);
+    const output = CreateIssueOutput.parse({
+      id: result.id,
+      url: result.url,
+      number: result.number,
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+  });
+}
+```
+
+## Exemplo: server stdio Python
+
+```python
+# server.py
+import asyncio
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+from pydantic import BaseModel, Field
+
+app = Server("meu-mcp-server")
+
+class CreateIssueInput(BaseModel):
+    title: str = Field(min_length=1, max_length=255)
+    description: str | None = None
+    priority: str = Field(default="medium", pattern="^(low|medium|high)$")
+    team_id: str
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="create_issue",
+            description="Create a new issue in Linear",
+            inputSchema=CreateIssueInput.model_json_schema(),
+        )
+    ]
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name != "create_issue":
+        raise ValueError(f"unknown tool: {name}")
+    input_data = CreateIssueInput.model_validate(arguments)
+    result = await linear_client.create_issue(input_data)
+    return [TextContent(type="text", text=result.model_dump_json())]
+
+async def main():
+    async with stdio_server() as (read, write):
+        await app.run(read, write, app.create_initialization_options())
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Resources
+
+```typescript
+import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [{
+    uri: 'linear://schema',
+    name: 'Linear Issue Schema',
+    mimeType: 'application/json',
+  }],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params.uri === 'linear://schema') {
+    return { contents: [{ uri: req.params.uri, mimeType: 'application/json', text: JSON.stringify(schema) }] };
+  }
+  throw new Error('unknown resource');
+});
+```
+
+## Prompts
+
+```typescript
+import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: [{
+    name: 'triage_issue',
+    description: 'Triage an issue and assign priority',
+    arguments: [
+      { name: 'description', description: 'Issue description', required: true },
+    ],
+  }],
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => ({
+  messages: [{
+    role: 'user',
+    content: { type: 'text', text: `Triage this issue and suggest a priority:\n\n${req.params.arguments?.description}` },
+  }],
+}));
+```
+
+## Transports
+
+| Transport | Quando usar | Setup |
+|---|---|---|
+| **stdio** | Server local, agente spawnea processo | `StdioServerTransport` |
+| **SSE** | Server remoto, streaming bidirectional | `SSEServerTransport` + Express/Fastify |
+| **HTTP** | Server remoto stateless | endpoint POST que devolve JSON |
+
+## Autorização por tool
+
+Toda tool deve declarar:
+- **Quem pode chamar** — escopo ou role
+- **Quais argumentos validar** — não confiar no client
+- **Side effects** — destrutivo? idempotente?
+
+```typescript
+// tool destrutiva exige confirmação ou role admin
+if (input.confirm !== 'YES_I_AM_SURE') {
+  throw new Error('this tool requires confirmation');
+}
+if (!callerHasRole('admin')) {
+  throw new Error('admin only');
+}
+```
+
+## Observabilidade
+
+Logue cada tool call (sem dados sensíveis):
+
+```typescript
+console.error(JSON.stringify({
+  ts: new Date().toISOString(),
+  tool: req.params.name,
+  duration_ms: Date.now() - start,
+  success: true,
+  // sem args (PII), sem result (PII)
+}));
+```
+
+> stdio usa stdout para protocolo MCP — **logs sempre em stderr**.
+
+## Testes
+
+```typescript
+// tests/create_issue.test.ts
+import { test, expect, vi } from 'vitest';
+import { CreateIssueInput } from '../src/tools/create_issue.js';
+
+test('valida input correto', () => {
+  const valid = CreateIssueInput.parse({
+    title: 'Test',
+    team_id: '550e8400-e29b-41d4-a716-446655440000',
+  });
+  expect(valid.priority).toBe('medium');  // default
+});
+
+test('rejeita team_id inválido', () => {
+  expect(() => CreateIssueInput.parse({
+    title: 'Test',
+    team_id: 'not-a-uuid',
+  })).toThrow();
+});
+```
+
+E2E com cliente MCP de teste:
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({ command: 'node', args: ['dist/index.js'] });
+const client = new Client({ name: 'test', version: '0.0.0' }, { capabilities: {} });
+await client.connect(transport);
+
+const tools = await client.listTools();
+expect(tools.tools.map(t => t.name)).toContain('create_issue');
+```
+
+## Antipatterns
+
+| AP | Antipattern | Por quê |
+|---|---|---|
+| AP-01 | Logs no stdout (stdio) | Quebra o protocolo — sempre stderr |
+| AP-02 | Tool sem schema de input | Cliente vai passar lixo |
+| AP-03 | Sem validação no server | Confia no client (errado) |
+| AP-04 | Tool destrutiva sem confirmação | Agente pode deletar dados sem querer |
+| AP-05 | Secrets em código | Use env vars |
+| AP-06 | Tool name não-descritivo (`do_thing`) | Agente não sabe quando usar |
+| AP-07 | Description vago | Agente erra na escolha |
+| AP-08 | Resource sem mimeType | Cliente não sabe parsear |
+
+## Publicação
+
+### Pré-requisitos para registry
+
+- README.md com:
+  - Como instalar/configurar
+  - Lista de tools/resources/prompts
+  - Variáveis de ambiente necessárias
+  - Exemplo de `claude_desktop_config.json` (stdio)
+- LICENSE (MIT recomendado)
+- `package.json` ou `pyproject.toml` versionado
+- Schema JSON exposto (vem das definições Zod/Pydantic)
+
+### Distribuição
+
+- **npm** — `npm publish` para servers TS
+- **PyPI** — `python -m build && twine upload` para Python
+- **Docker** — para SSE/HTTP servers (multi-stage build)
+
+## Configuração no cliente (exemplo Claude Desktop)
+
+```json
+{
+  "mcpServers": {
+    "meu-server": {
+      "command": "node",
+      "args": ["/abs/path/to/dist/index.js"],
+      "env": {
+        "LINEAR_API_KEY": "lin_api_..."
+      }
+    }
+  }
+}
+```
+
+## Como aplicar
+
+### Passo 1: Decidir transport
+
+Local + uso pessoal → **stdio**. Multi-usuário ou cloud → **SSE/HTTP**.
+
+### Passo 2: Listar tools/resources/prompts
+
+Inventarie no DESIGN.md o que vai expor. Cada tool: nome, descrição clara, input schema, output schema.
+
+### Passo 3: Scaffold
+
+Use SDK oficial. Estruture em `tools/`, `resources/`, `prompts/`.
+
+### Passo 4: Schemas Zod/Pydantic
+
+Toda tool tem schema de input. Output validado antes de retornar.
+
+### Passo 5: Logs em stderr + observabilidade
+
+`console.error` (stdio) com JSON estruturado.
+
+### Passo 6: Testes + publicação
+
+Vitest/pytest. README + LICENSE MIT. Publicar npm/PyPI.
+
+## Dicas
+
+- **Combine** com `dare-llm-integration` se o server chama LLM
+- **Use** `dare-security` para auditar dependências
+- **Para tools destrutivas**, exija confirm flag explícito
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.

package/templates/ide/antigravity/.agents/skills/skill-nestjs-api/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: skill-nestjs-api
+description: Padrões DARE para APIs REST em NestJS + TypeScript + Prisma + Swagger. Modules, Controllers, Services, DTOs com class-validator, Guards, Interceptors, exceções globais, Jest + Supertest, OpenAPI auto-gerado, rate limiting com @nestjs/throttler.
+---
+
+# DARE NestJS API Skill
+
+Você é um desenvolvedor sênior TypeScript / NestJS especializado em APIs REST. Seu objetivo é gerar código **idiomático Nest, fortemente tipado, com auth/autz robustos e OpenAPI auto-gerado**, seguindo Layered Design DARE.
+
+## Quando usar
+
+- Projeto NestJS novo via DARE
+- Adicionar feature em API NestJS existente
+- Migrar API Express clássica para NestJS
+- Auditar projeto NestJS para conformidade DARE
+
+## Stack canônica
+
+- **TypeScript 5.5+** com `strict: true`
+- **NestJS 11.x** (módulos, providers, DI)
+- **Prisma 5.x** ORM (PostgreSQL ou MySQL)
+- **class-validator + class-transformer** para DTOs
+- **@nestjs/swagger** para OpenAPI auto-gerado
+- **@nestjs/throttler** para rate limiting
+- **@nestjs/passport + @nestjs/jwt** para auth
+- **Jest + Supertest** para testes
+- **ESLint + Prettier** para formatação
+
+## Layered Design em NestJS
+
+Cada módulo segue:
+
+```
+src/<feature>/
+├── <feature>.module.ts          ← define providers, controllers
+├── <feature>.controller.ts      ← Handler
+├── <feature>.service.ts         ← Service (uma operação) ou facade
+├── <feature>.repository.ts      ← Repository (Prisma)
+├── dto/
+│   ├── create-<feature>.dto.ts  ← class-validator
+│   └── update-<feature>.dto.ts
+├── entities/
+│   └── <feature>.entity.ts      ← Model
+└── tests/
+    ├── <feature>.service.spec.ts  ← unit
+    └── <feature>.e2e-spec.ts      ← E2E
+```
+
+## Controllers (Handler)
+
+```typescript
+import { Body, Controller, Post, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiCreatedResponse } from '@nestjs/swagger';
+import { JwtAuthGuard } from '@/auth/jwt-auth.guard';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UserResponseDto } from './dto/user-response.dto';
+import { RegisterUserService } from './register-user.service';
+
+@ApiTags('users')
+@Controller('users')
+@UseGuards(JwtAuthGuard)
+export class UsersController {
+  constructor(private readonly register: RegisterUserService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Criar novo usuário' })
+  @ApiCreatedResponse({ type: UserResponseDto })
+  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
+    const user = await this.register.execute(dto);
+    return UserResponseDto.from(user);
+  }
+}
+```
+
+## DTOs (validação)
+
+```typescript
+import { IsEmail, IsString, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({ example: 'jane@example.com' })
+  @IsEmail()
+  email!: string;
+
+  @ApiProperty({ example: 'Jane Doe' })
+  @IsString()
+  name!: string;
+
+  @ApiProperty({ minLength: 12 })
+  @IsString()
+  @MinLength(12)
+  password!: string;
+}
+```
+
+`main.ts` ativa global pipe:
+```typescript
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+```
+
+## Services (Business Logic)
+
+Uma operação por classe:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { hash } from '@node-rs/argon2';
+import { UsersRepository } from './users.repository';
+import { CreateUserDto } from './dto/create-user.dto';
+import { User } from './entities/user.entity';
+import { UserAlreadyExistsError } from './errors';
+
+@Injectable()
+export class RegisterUserService {
+  constructor(private readonly repo: UsersRepository) {}
+
+  async execute(dto: CreateUserDto): Promise<User> {
+    if (await this.repo.existsByEmail(dto.email)) {
+      throw new UserAlreadyExistsError();
+    }
+    return this.repo.create({
+      ...dto,
+      password: await hash(dto.password),
+    });
+  }
+}
+```
+
+## Repositories (Prisma)
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from '@/prisma/prisma.service';
+
+@Injectable()
+export class UsersRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async existsByEmail(email: string): Promise<boolean> {
+    return !!(await this.prisma.user.findUnique({ where: { email } }));
+  }
+
+  async create(data: { email: string; name: string; password: string }) {
+    return this.prisma.user.create({ data });
+  }
+}
+```
+
+## Tratamento global de exceções
+
+```typescript
+// src/common/filters/all-exceptions.filter.ts
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    if (exception instanceof UserAlreadyExistsError) {
+      return response.status(409).json({ error: 'USER_EXISTS' });
+    }
+    if (exception instanceof HttpException) {
+      return response.status(exception.getStatus()).json(exception.getResponse());
+    }
+    // log + 500 genérico
+    return response.status(500).json({ error: 'INTERNAL' });
+  }
+}
+
+// main.ts
+app.useGlobalFilters(new AllExceptionsFilter());
+```
+
+## OpenAPI auto-gerado
+
+```typescript
+// main.ts
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+
+const config = new DocumentBuilder()
+  .setTitle('Projeto API')
+  .setVersion('1.0')
+  .addBearerAuth()
+  .build();
+
+const document = SwaggerModule.createDocument(app, config);
+SwaggerModule.setup('docs', app, document); // UI em /docs
+writeFileSync('./public/openapi.json', JSON.stringify(document));
+```
+
+## Rate limiting
+
+```typescript
+import { ThrottlerModule } from '@nestjs/throttler';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]),
+  ],
+})
+
+// Endpoint sensível
+@Throttle({ default: { limit: 5, ttl: 900_000 } })  // 5/15min
+@Post('login')
+async login() {...}
+```
+
+## Auth (JWT + Passport)
+
+```typescript
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {}
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(config: ConfigService) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: config.getOrThrow('JWT_SECRET'),
+    });
+  }
+  async validate(payload: any) {
+    return { id: payload.sub, email: payload.email };
+  }
+}
+```
+
+## Testes
+
+### Unit (service)
+
+```typescript
+describe('RegisterUserService', () => {
+  it('falha se email já existe', async () => {
+    const repo = { existsByEmail: jest.fn().mockResolvedValue(true) } as any;
+    const sut = new RegisterUserService(repo);
+    await expect(sut.execute({ email: 'x@y.com', name: 'X', password: 'longsecret123' }))
+      .rejects.toThrow(UserAlreadyExistsError);
+  });
+});
+```
+
+### E2E (Supertest)
+
+```typescript
+describe('POST /users', () => {
+  it('cria usuário com sucesso', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/users')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ email: 'jane@example.com', name: 'Jane', password: 'longsecret123' });
+    expect(res.status).toBe(201);
+    expect(res.body.email).toBe('jane@example.com');
+  });
+});
+```
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | Validação inline no Controller | DTO + ValidationPipe |
+| AP-02 | Prisma direto no Controller | Repository |
+| AP-03 | Lógica no Controller | Service |
+| AP-04 | Sem DTO de saída | `UserResponseDto.from(user)` |
+| AP-05 | `JwtStrategy` com secret hardcoded | `ConfigService.getOrThrow` |
+| AP-06 | Sem `@nestjs/throttler` em login | rate limit obrigatório |
+| AP-07 | OpenAPI escrito à mão | `@nestjs/swagger` decorators |
+| AP-08 | Erros sem filter global | inconsistência de response |
+
+## Segurança (combinar com `dare-security`)
+
+- Hash com `@node-rs/argon2` (Argon2id)
+- JWT: RS256 para tokens públicos, HS256 + secret ≥256 bits para internos
+- `helmet` middleware para headers
+- CORS específico, nunca `*`
+- Rate limit em login (5/15min) + APIs públicas
+- Refresh token com rotação no DB
+
+## Validação no CI
+
+```bash
+npm run lint
+npm run test
+npm run test:e2e
+npm run build
+npx prisma migrate deploy --dry-run     # valida migrations
+npm audit --audit-level=high
+```
+
+## Como aplicar
+
+### Passo 1: Audit
+
+```bash
+grep -rn "@Body()" src/ | grep -v "Dto"        # AP-01
+grep -rn "prisma\." src/*/controllers/         # AP-02
+grep -rn "JwtStrategy" src/ | grep -v Config   # AP-05
+```
+
+### Passo 2: Migrar para DTOs
+
+Para cada `@Body() body: any`, criar DTO com class-validator + `@ApiProperty`.
+
+### Passo 3: Extrair Services
+
+Toda lógica > 5 linhas em Controller → Service injetável.
+
+### Passo 4: Adicionar Repositories
+
+Encapsular Prisma. Controller chama Service, Service chama Repository.
+
+### Passo 5: Configurar Swagger + throttler
+
+`main.ts` com `SwaggerModule.setup` e exportar `public/openapi.json`. Adicionar `ThrottlerModule` global.
+
+## Dicas
+
+- **Combine** com `dare-docker` para PHP-FPM-style separação (Node + Postgres + Redis)
+- **Use** `dare-llm-integration` se houver chamadas LLM
+- **Para realtime**, use `@nestjs/websockets` + skill `dare-realtime`
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.