@dewtech/dare-cli 2.17.0 → 3.0.0

package/templates/ide/cursor/.cursor/rules/skill-llm-integration.mdc

@@ -0,0 +1,295 @@
+---
+description: Integração segura e eficiente com LLMs (Gemini, Claude, OpenAI, Ollama) em projetos DARE. Fornece LLMProvider abstraction, cache TTL, rate limit via token bucket, prompts versionados e validação de output via JSON Schema.
+globs: prompts/**/*.md,**/llm*.ts,**/llm*.py,**/llm*.rs,**/llm*.go,**/providers/**
+alwaysApply: false
+---
+
+# Skill: LLM Integration DARE
+
+Você é um especialista em integração com LLMs. Esta skill garante que toda chamada a LLM em projeto DARE seja **abstraída, cacheada, rate-limited, validada e defendida contra prompt injection**.
+
+## Arquitetura recomendada
+
+```
+┌──────────────────────────────────────────────────────┐
+│  Handler / Service de negócio                        │
+└──────────────────────────────────────────────────────┘
+                       ↓ injeta
+┌──────────────────────────────────────────────────────┐
+│  LLMProvider (interface)                             │
+│  ├── GeminiProvider                                  │
+│  ├── ClaudeProvider                                  │
+│  ├── OpenAIProvider                                  │
+│  └── OllamaProvider (local)                          │
+└──────────────────────────────────────────────────────┘
+                       ↓ wrap
+┌──────────────────────────────────────────────────────┐
+│  Cache (TTL) + RateLimit (token bucket) + Schema     │
+└──────────────────────────────────────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────────────┐
+│  HTTP call externo                                   │
+└──────────────────────────────────────────────────────┘
+```
+
+## Os 5 pilares
+
+### 1. LLMProvider abstraction
+
+Nunca chame SDK direto em Handler ou Service de negócio.
+
+```typescript
+// ❌ Errado
+class SummaryService {
+  async run(text: string) {
+    const client = new GoogleGenAI({ apiKey: 'xxx' });
+    return client.generateContent({ contents: text });
+  }
+}
+
+// ✅ Certo
+class SummaryService {
+  constructor(private llm: LLMProvider) {}
+  async run(text: string) {
+    return this.llm.complete({
+      promptId: 'summarize-v1',
+      input: { text },
+      schema: SummarySchema,
+    });
+  }
+}
+```
+
+### 2. Cache em memória com TTL
+
+Key = `hash(promptId + input + model)`. TTL configurável (default 1h).
+
+**AP-02:** sem cache = custo explode em loops + latência ruim.
+
+### 3. Rate limit via token bucket
+
+| Provider | Limite típico |
+|---|---|
+| Gemini Free | 15 RPM, 1M tokens/dia |
+| Claude tier 1 | 50 RPM |
+| OpenAI tier 1 | 500 RPM |
+| Ollama local | sem limite, latência alta |
+
+Token bucket por provider, configurado em `app.config`.
+
+### 4. Prompts versionados
+
+Prompts vivem em `prompts/<id>.v<n>.md`:
+
+```markdown
+---
+id: summarize
+version: 1
+model: gemini-2.0-flash
+temperature: 0.2
+max_tokens: 500
+schema: SummarySchema
+---
+
+# System
+You are a concise summarizer. Output JSON matching: {schema}
+
+# User
+Summarize the following text in 3 bullet points:
+
+<text>{{ text }}</text>
+```
+
+Substituição com template engine **seguro** (Jinja2 sandboxed, Handlebars, string-interp com escape). Nunca `eval` ou `f-string` direta com user input.
+
+### 5. Validação de output
+
+LLM mente. Sempre valide:
+
+```typescript
+const raw = await llm.complete({...});
+const result = SummarySchema.parse(raw);  // Zod/Pydantic/ajv
+if (!result.success) {
+  throw new LLMOutputInvalidError(result.error);
+  // Pode indicar prompt injection ou drift de modelo — logar + alertar
+}
+```
+
+---
+
+## Métricas obrigatórias
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% das chamadas LLM via LLMProvider | grep por SDK direto em Handlers/Services |
+| M-02 | 100% das responses cacheadas | logs do cache layer |
+| M-03 | 100% das requests com rate limit | rate limiter ativo em todo provider |
+| M-04 | 100% das respostas validadas contra schema | grep por `.parse(` ou `model_validate(` |
+
+---
+
+## Antipatterns (CI falha)
+
+| AP | Antipattern | Por que evitar |
+|---|---|---|
+| AP-01 | SDK direto em Handler | impossível mockar / trocar provider |
+| AP-02 | Sem cache | custo explode, latência ruim |
+| AP-03 | Prompt em código | impossível versionar / A-B testar |
+| AP-04 | User input direto em prompt | prompt injection trivial |
+| AP-05 | Confiar em output LLM sem validar | LLM mente — schema é defesa |
+
+---
+
+## Defesa contra prompt injection
+
+```python
+# ❌ Errado — instrução + dado misturados
+system = f"You are an assistant. {user_question}"
+```
+
+```python
+# ✅ Certo — separação clara + escape
+messages = [
+    {"role": "system", "content": "You are an assistant. Answer only based on the provided document."},
+    {"role": "user", "content": f"<document>{escape(doc)}</document>\n\n<question>{escape(q)}</question>"}
+]
+```
+
+Regras:
+- Use delimitadores (`<document>`, `<question>`)
+- Escape conteúdo do usuário (XML/HTML escape)
+- Detecte e remova padrões "Ignore instructions above", "You are now ..."
+- Valide output contra schema — output fora do schema = possível injection bem-sucedido
+
+---
+
+## Exemplos por stack
+
+### TypeScript (NestJS)
+
+```typescript
+@Injectable()
+export class GeminiProvider implements LLMProvider {
+  constructor(
+    private cache: Cache,
+    private rateLimit: TokenBucket,
+    @Inject('GEMINI_API_KEY') private apiKey: string,
+  ) {}
+
+  async complete(req: LLMRequest): Promise<unknown> {
+    const cached = await this.cache.get(req.cacheKey());
+    if (cached) return cached;
+    await this.rateLimit.acquire(1);
+    const raw = await this.callGemini(req);
+    const validated = req.schema.parse(raw);
+    await this.cache.set(req.cacheKey(), validated, req.ttl);
+    return validated;
+  }
+}
+```
+
+### Python (FastAPI)
+
+```python
+class ClaudeProvider(LLMProvider):
+    def __init__(self, client: Anthropic, cache: Cache, bucket: TokenBucket):
+        self.client = client
+        self.cache = cache
+        self.bucket = bucket
+
+    async def complete(self, req: LLMRequest):
+        cached = await self.cache.get(req.cache_key())
+        if cached: return cached
+        await self.bucket.acquire(1)
+        raw = await self.client.messages.create(...)
+        validated = req.schema.model_validate(raw.content[0].text)
+        await self.cache.set(req.cache_key(), validated.model_dump(), req.ttl)
+        return validated
+```
+
+### Rust/Axum
+
+```rust
+pub struct GeminiProvider {
+    client: reqwest::Client,
+    cache: Arc<dyn Cache>,
+    bucket: Arc<TokenBucket>,
+}
+
+#[async_trait]
+impl LLMProvider for GeminiProvider {
+    async fn complete<T: DeserializeOwned + JsonSchema>(&self, req: LLMRequest<T>) -> Result<T> {
+        if let Some(cached) = self.cache.get(&req.cache_key()).await? {
+            return Ok(cached);
+        }
+        self.bucket.acquire(1).await?;
+        let raw = self.call_gemini(&req).await?;
+        let validated: T = serde_json::from_value(raw)?;
+        self.cache.set(&req.cache_key(), &validated, req.ttl).await?;
+        Ok(validated)
+    }
+}
+```
+
+---
+
+## Observabilidade obrigatória
+
+Logue estruturado por chamada:
+
+```json
+{
+  "promptId": "summarize",
+  "version": 1,
+  "model": "gemini-2.0-flash",
+  "cacheHit": false,
+  "tokensIn": 1342,
+  "tokensOut": 287,
+  "estimatedCostUsd": 0.0021,
+  "latencyMs": 850,
+  "schemaValid": true
+}
+```
+
+Não logue: prompt completo (privacidade), output completo (PII), API keys.
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Listar quais LLMs serão usados (provider, modelo)
+- Estimar volume de calls/dia → ajustar rate limit
+- Definir prompts iniciais com schema
+
+### Blueprint
+- Diagrama da camada LLM (provider, cache, rate limit)
+- Estratégia de fallback (primary → secondary)
+- Estratégia de versionamento de prompts
+
+### Tasks
+- Task dedicada: "Criar LLMProvider + cache + rate limit"
+- Task por prompt: "Extrair prompt X para `prompts/x.v1.md`"
+- Task de validação: "Adicionar schema Zod/Pydantic para cada prompt"
+
+### Execute
+- Ralph Loop: grep falha se SDK direto em Service/Handler
+- Métricas M-01 a M-04 reportadas em cada PR
+
+---
+
+## Checklist final
+
+- [ ] Interface `LLMProvider` definida
+- [ ] Pelo menos 1 provider implementado
+- [ ] Cache em memória com TTL configurado
+- [ ] Token bucket configurado por provider
+- [ ] Todos os prompts em `prompts/<id>.v<n>.md`
+- [ ] Schema para cada prompt
+- [ ] Validação de output em todo chamador
+- [ ] Logs estruturados com tokens + custo
+- [ ] Defesa contra prompt injection em prompts com user input
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.

package/templates/ide/cursor/.cursor/rules/skill-mcp-server.mdc

@@ -0,0 +1,367 @@
+---
+description: Padrões DARE para servidores MCP (Model Context Protocol da Anthropic) em TypeScript ou Python. Tools, resources, prompts; transports stdio/SSE/HTTP; validação Zod/Pydantic; autorização por tool; observabilidade; testes; publicação.
+globs: **/*.ts,**/*.py,package.json,pyproject.toml,claude_desktop_config.json
+alwaysApply: false
+---
+
+# Skill: MCP Server DARE
+
+Você é um especialista em servidores MCP (Model Context Protocol). Esta skill garante MCP servers **bem estruturados, seguros, testáveis e publicáveis**, expondo tools/resources/prompts via stdio, SSE ou HTTP.
+
+## O que é MCP em 30 segundos
+
+Protocolo aberto da Anthropic para conectar agentes (Claude Code, Claude Desktop, Cursor, etc.) a fontes de dados e ações externas. Server expõe:
+
+- **Tools** — funções chamáveis pelo agente
+- **Resources** — dados leitáveis (URI + mimeType)
+- **Prompts** — templates parametrizados
+
+Transports:
+
+| Transport | Quando usar |
+|---|---|
+| **stdio** | Server local, agente spawnea processo |
+| **SSE** | Server remoto, streaming bidirectional |
+| **HTTP** | Server remoto stateless |
+
+---
+
+## Stack canônica
+
+### TypeScript
+
+- Node 20+ + TS 5.5+
+- `@modelcontextprotocol/sdk` SDK oficial
+- Zod para schemas
+- vitest
+
+### Python
+
+- Python 3.11+
+- `mcp` (SDK oficial, `pip install mcp`)
+- Pydantic v2
+- pytest + pytest-asyncio
+
+---
+
+## Estrutura
+
+```
+mcp-meu-server/
+├── package.json   (ou pyproject.toml)
+├── src/
+│   ├── index.ts             ← stdio entrypoint
+│   ├── server.ts            ← criação do MCP Server
+│   ├── tools/
+│   │   ├── create_issue.ts
+│   │   └── search_issues.ts
+│   ├── resources/
+│   ├── prompts/
+│   ├── schemas/
+│   └── lib/                 ← clientes externos
+└── tests/
+```
+
+---
+
+## Exemplo TypeScript (stdio)
+
+```typescript
+// src/index.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+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 server = new Server(
+  { name: 'meu-server', version: '1.0.0' },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'create_issue',
+    description: 'Create a new issue in Linear with the given title, description, and priority',
+    inputSchema: CreateIssueInput.shape,
+  }],
+}));
+
+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);
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+---
+
+## Exemplo Python (stdio)
+
+```python
+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-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
+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
+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}`,
+    },
+  }],
+}));
+```
+
+---
+
+## Autorização por tool
+
+```typescript
+// Tool destrutiva exige confirm explícito
+if (input.confirm !== 'YES_I_AM_SURE') {
+  throw new Error('this tool requires confirmation');
+}
+
+// Tool admin
+if (!callerHasRole('admin')) {
+  throw new Error('admin only');
+}
+```
+
+---
+
+## Observabilidade
+
+**Crítico em stdio:** o protocolo MCP usa **stdout**. Logs SEMPRE em stderr.
+
+```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 completo (pode ter PII)
+}));
+```
+
+---
+
+## Testes
+
+```typescript
+// Unit
+import { test, expect } from 'vitest';
+test('valida input correto', () => {
+  const valid = CreateIssueInput.parse({
+    title: 'Test',
+    team_id: '550e8400-e29b-41d4-a716-446655440000',
+  });
+  expect(valid.priority).toBe('medium');
+});
+
+test('rejeita team_id inválido', () => {
+  expect(() => CreateIssueInput.parse({
+    title: 'Test',
+    team_id: 'not-uuid',
+  })).toThrow();
+});
+
+// E2E com client MCP
+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 MCP |
+| AP-02 | Tool sem schema de input | Cliente passa lixo |
+| AP-03 | Sem validação no server | Confia no client (errado) |
+| AP-04 | Tool destrutiva sem confirm | Agente apaga sem querer |
+| AP-05 | Secrets em código | Use env vars |
+| AP-06 | Tool name vago (`do_thing`) | Agente não sabe quando usar |
+| AP-07 | Description curto/vago | Agente erra na escolha |
+| AP-08 | Resource sem mimeType | Cliente não parseia |
+| AP-09 | Tool sem error handling | Erro vira crash em vez de mensagem |
+
+---
+
+## Publicação
+
+### Pré-requisitos
+
+- `README.md` com:
+  - Instalação e configuração
+  - Lista de tools/resources/prompts
+  - Variáveis de ambiente
+  - Exemplo `claude_desktop_config.json`
+- `LICENSE` (MIT recomendado)
+- `package.json`/`pyproject.toml` versionado
+
+### Distribuição
+
+| Stack | Comando |
+|---|---|
+| TypeScript | `npm publish` |
+| Python | `python -m build && twine upload dist/*` |
+| Docker (SSE/HTTP) | multi-stage build + push para registry |
+
+### Config no Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "meu-server": {
+      "command": "node",
+      "args": ["/abs/path/to/dist/index.js"],
+      "env": {
+        "LINEAR_API_KEY": "lin_api_..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Definir capabilities (tools, resources, prompts) com nomes e descrições claras
+- Decidir transport (stdio/SSE/HTTP)
+- Listar variáveis de ambiente necessárias
+
+### Blueprint
+- Estrutura de pastas
+- Schemas Zod/Pydantic por tool
+- Estratégia de autorização
+
+### Tasks
+- Por tool: 1 task (schema + handler + teste)
+- Task de configuração transport + entrypoint
+- Task de publicação (README + LICENSE + CI release)
+
+### Execute
+- Ralph Loop:
+  ```bash
+  npm run lint && npm test && npm run build
+  # ou
+  ruff check . && mypy . && pytest
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Transport escolhido (stdio/SSE/HTTP) com justificativa
+- [ ] Cada tool tem name descritivo, description completa, input schema
+- [ ] Validação Zod/Pydantic no início de cada handler
+- [ ] Tools destrutivas exigem `confirm`
+- [ ] Logs em stderr (stdio) com JSON estruturado
+- [ ] Secrets via env vars, nunca em código
+- [ ] Testes unit + E2E com client MCP
+- [ ] README + LICENSE MIT
+- [ ] Publicação configurada (npm/PyPI/Docker)
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.