@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/framework/templates/codebase/conventions.md

@@ -0,0 +1,204 @@
+# Template de Convenções de Código
+
+Template para `.planning/codebase/CONVENTIONS.md` - captura estilo e padrões de código.
+
+**Propósito:** Documentar como o código é escrito neste codebase. Guia prescritivo para o Claude corresponder ao estilo existente.
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Convenções de Código
+
+**Data da Análise:** [AAAA-MM-DD]
+
+## Padrões de Nomenclatura
+
+**Arquivos:**
+- [Padrão: ex.: "kebab-case para todos os arquivos"]
+- [Arquivos de teste: ex.: "*.test.ts junto ao source"]
+- [Componentes: ex.: "PascalCase.tsx para componentes React"]
+
+**Funções:**
+- [Padrão: ex.: "camelCase para todas as funções"]
+- [Async: ex.: "sem prefixo especial para funções async"]
+- [Handlers: ex.: "handleNomeDoEvento para event handlers"]
+
+**Variáveis:**
+- [Padrão: ex.: "camelCase para variáveis"]
+- [Constantes: ex.: "UPPER_SNAKE_CASE para constantes"]
+- [Privadas: ex.: "_prefixo para membros privados" ou "sem prefixo"]
+
+**Tipos:**
+- [Interfaces: ex.: "PascalCase, sem prefixo I"]
+- [Types: ex.: "PascalCase para type aliases"]
+- [Enums: ex.: "PascalCase para nome do enum, UPPER_CASE para valores"]
+
+## Estilo de Código
+
+**Formatação:**
+- [Ferramenta: ex.: "Prettier com config em .prettierrc"]
+- [Comprimento de linha: ex.: "100 caracteres no máximo"]
+- [Aspas: ex.: "aspas simples para strings"]
+- [Ponto e vírgula: ex.: "obrigatório" ou "omitido"]
+
+**Linting:**
+- [Ferramenta: ex.: "ESLint com eslint.config.js"]
+- [Regras: ex.: "extends airbnb-base, sem console em produção"]
+- [Executar: ex.: "npm run lint"]
+
+## Organização de Imports
+
+**Ordem:**
+1. [ex.: "Pacotes externos (react, express, etc.)"]
+2. [ex.: "Módulos internos (@/lib, @/components)"]
+3. [ex.: "Imports relativos (., ..)"]
+4. [ex.: "Type imports (import type {})"]
+
+**Agrupamento:**
+- [Linhas em branco: ex.: "linha em branco entre grupos"]
+- [Ordenação: ex.: "alfabética dentro de cada grupo"]
+
+**Path Aliases:**
+- [Aliases usados: ex.: "@/ para src/, @components/ para src/components/"]
+
+## Tratamento de Erros
+
+**Padrões:**
+- [Estratégia: ex.: "lançar errors, capturar nos limites"]
+- [Erros customizados: ex.: "estender classe Error, nomeados *Error"]
+- [Async: ex.: "usar try/catch, sem cadeias .catch()"]
+
+**Tipos de Erro:**
+- [Quando lançar: ex.: "entrada inválida, dependências faltando"]
+- [Quando retornar: ex.: "falhas esperadas retornam Result<T, E>"]
+- [Logging: ex.: "logar error com contexto antes de lançar"]
+
+## Logging
+
+**Framework:**
+- [Ferramenta: ex.: "console.log, pino, winston"]
+- [Níveis: ex.: "debug, info, warn, error"]
+
+**Padrões:**
+- [Formato: ex.: "logging estruturado com objeto de contexto"]
+- [Quando: ex.: "logar transições de estado, chamadas externas"]
+- [Onde: ex.: "logar nos limites de serviço, não em utils"]
+
+## Comentários
+
+**Quando Comentar:**
+- [ex.: "explicar por quê, não o quê"]
+- [ex.: "documentar lógica de negócio, algoritmos, casos extremos"]
+- [ex.: "evitar comentários óbvios como // incrementar contador"]
+
+**JSDoc/TSDoc:**
+- [Uso: ex.: "obrigatório para APIs públicas, opcional para internas"]
+- [Formato: ex.: "usar tags @param, @returns, @throws"]
+
+**Comentários TODO:**
+- [Padrão: ex.: "// TODO(username): descrição"]
+- [Rastreamento: ex.: "link para número do issue se disponível"]
+
+## Design de Funções
+
+**Tamanho:**
+- [ex.: "manter abaixo de 50 linhas, extrair helpers"]
+
+**Parâmetros:**
+- [ex.: "máximo 3 parâmetros, usar objeto para mais"]
+- [ex.: "desestruturar objetos na lista de parâmetros"]
+
+**Valores de Retorno:**
+- [ex.: "returns explícitos, sem undefined implícito"]
+- [ex.: "retornar cedo para cláusulas de guarda"]
+
+## Design de Módulos
+
+**Exports:**
+- [ex.: "named exports preferidos, default exports para componentes React"]
+- [ex.: "exportar de index.ts para API pública"]
+
+**Barrel Files:**
+- [ex.: "usar index.ts para re-exportar API pública"]
+- [ex.: "evitar dependências circulares"]
+
+---
+
+*Análise de convenções: [data]*
+*Atualizar quando padrões mudarem*
+```
+
+<good_examples>
+```markdown
+# Coding Conventions
+
+**Analysis Date:** 2025-01-20
+
+## Naming Patterns
+
+**Files:**
+- kebab-case for all files (command-handler.ts, user-service.ts)
+- *.test.ts alongside source files
+- index.ts for barrel exports
+
+**Functions:**
+- camelCase for all functions
+- No special prefix for async functions
+- handleEventName for event handlers (handleClick, handleSubmit)
+
+## Code Style
+
+**Formatting:**
+- Prettier with .prettierrc
+- 100 character line length
+- Single quotes for strings
+- Semicolons required
+- 2 space indentation
+
+---
+
+*Convention analysis: 2025-01-20*
+*Update when patterns change*
+```
+</good_examples>
+
+<guidelines>
+**O que pertence ao CONVENTIONS.md:**
+- Padrões de nomenclatura observados no codebase
+- Regras de formatação (config Prettier, regras de linting)
+- Padrões de organização de imports
+- Estratégia de tratamento de erros
+- Abordagem de logging
+- Convenções de comentários
+- Padrões de design de funções e módulos
+
+**O que NÃO pertence aqui:**
+- Decisões de arquitetura (isso é ARCHITECTURE.md)
+- Escolhas tecnológicas (isso é STACK.md)
+- Padrões de teste (isso é TESTING.md)
+- Organização de arquivos (isso é STRUCTURE.md)
+
+**Ao preencher este template:**
+- Verificar .prettierrc, .eslintrc ou arquivos de config similares
+- Examinar 5-10 arquivos fonte representativos para padrões
+- Procurar consistência: se 80%+ segue um padrão, documentar
+- Ser prescritivo: "Use X" não "Às vezes Y é usado"
+- Notar desvios: "Código legado usa Y, novo código deve usar X"
+- Manter abaixo de ~150 linhas no total
+
+**Útil para planejamento de fases quando:**
+- Escrevendo novo código (corresponder ao estilo existente)
+- Adicionando funcionalidades (seguir padrões de nomenclatura)
+- Refatorando (aplicar convenções consistentes)
+- Revisão de código (verificar contra padrões documentados)
+- Integração (entender expectativas de estilo)
+
+**Abordagem de análise:**
+- Escanear diretório src/ para padrões de nomenclatura de arquivos
+- Verificar scripts do package.json para comandos lint/format
+- Ler 5-10 arquivos para identificar nomenclatura de funções, tratamento de erros
+- Procurar arquivos de config (.prettierrc, eslint.config.js)
+- Notar padrões em imports, comentários, assinaturas de funções
+</guidelines>

package/kit/framework/templates/codebase/integrations.md

@@ -0,0 +1,192 @@
+# Template de Integrações Externas
+
+Template para `.planning/codebase/INTEGRATIONS.md` - captura dependências de serviços externos.
+
+**Propósito:** Documentar com quais sistemas externos este codebase se comunica. Focado em "o que vive fora do nosso código do qual dependemos."
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Integrações Externas
+
+**Data da Análise:** [AAAA-MM-DD]
+
+## APIs & Serviços Externos
+
+**Processamento de Pagamentos:**
+- [Serviço] - [Para o que é usado: ex.: "cobrança de assinatura, pagamentos únicos"]
+  - SDK/Client: [ex.: "pacote npm stripe v14.x"]
+  - Auth: [ex.: "chave de API em variável de ambiente STRIPE_SECRET_KEY"]
+  - Endpoints usados: [ex.: "sessões de checkout, webhooks"]
+
+**Email/SMS:**
+- [Serviço] - [Para o que é usado: ex.: "emails transacionais"]
+  - SDK/Client: [ex.: "sendgrid/mail v8.x"]
+  - Auth: [ex.: "chave de API em variável de ambiente SENDGRID_API_KEY"]
+  - Templates: [ex.: "gerenciados no dashboard SendGrid"]
+
+**APIs Externas:**
+- [Serviço] - [Para o que é usado]
+  - Método de integração: [ex.: "REST API via fetch", "cliente GraphQL"]
+  - Auth: [ex.: "token OAuth2 em variável de ambiente AUTH_TOKEN"]
+  - Rate limits: [se aplicável]
+
+## Armazenamento de Dados
+
+**Bancos de Dados:**
+- [Tipo/Provedor] - [ex.: "PostgreSQL no Supabase"]
+  - Conexão: [ex.: "via variável de ambiente DATABASE_URL"]
+  - Client: [ex.: "Prisma ORM v5.x"]
+  - Migrations: [ex.: "prisma migrate em migrations/"]
+
+**Armazenamento de Arquivos:**
+- [Serviço] - [ex.: "AWS S3 para uploads de usuários"]
+  - SDK/Client: [ex.: "@aws-sdk/client-s3"]
+  - Auth: [ex.: "credenciais IAM em variáveis de ambiente AWS_*"]
+  - Buckets: [ex.: "prod-uploads, dev-uploads"]
+
+**Cache:**
+- [Serviço] - [ex.: "Redis para armazenamento de sessão"]
+  - Conexão: [ex.: "variável de ambiente REDIS_URL"]
+  - Client: [ex.: "ioredis v5.x"]
+
+## Autenticação & Identidade
+
+**Provedor de Auth:**
+- [Serviço] - [ex.: "Supabase Auth", "Auth0", "JWT customizado"]
+  - Implementação: [ex.: "SDK client Supabase"]
+  - Armazenamento de token: [ex.: "cookies httpOnly", "localStorage"]
+  - Gerenciamento de sessão: [ex.: "JWT refresh tokens"]
+
+**Integrações OAuth:**
+- [Provedor] - [ex.: "Google OAuth para login"]
+  - Credenciais: [ex.: "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
+  - Escopos: [ex.: "email, profile"]
+
+## Monitoramento & Observabilidade
+
+**Rastreamento de Erros:**
+- [Serviço] - [ex.: "Sentry"]
+  - DSN: [ex.: "variável de ambiente SENTRY_DSN"]
+  - Rastreamento de release: [ex.: "via SENTRY_RELEASE"]
+
+**Analytics:**
+- [Serviço] - [ex.: "Mixpanel para analytics de produto"]
+  - Token: [ex.: "variável de ambiente MIXPANEL_TOKEN"]
+  - Eventos rastreados: [ex.: "ações do usuário, page views"]
+
+**Logs:**
+- [Serviço] - [ex.: "CloudWatch", "Datadog", "nenhum (apenas stdout)"]
+  - Integração: [ex.: "built-in do AWS Lambda"]
+
+## CI/CD & Deployment
+
+**Hospedagem:**
+- [Plataforma] - [ex.: "Vercel", "AWS Lambda", "Docker no ECS"]
+  - Deployment: [ex.: "automático no push para branch main"]
+  - Variáveis de ambiente: [ex.: "configuradas no dashboard Vercel"]
+
+**Pipeline CI:**
+- [Serviço] - [ex.: "GitHub Actions"]
+  - Workflows: [ex.: "test.yml, deploy.yml"]
+  - Segredos: [ex.: "armazenados nos secrets do repositório GitHub"]
+
+## Configuração de Ambiente
+
+**Desenvolvimento:**
+- Variáveis de ambiente necessárias: [Listar variáveis críticas]
+- Localização dos segredos: [ex.: ".env.local (gitignored)", "cofre 1Password"]
+- Serviços mock/stub: [ex.: "modo de teste Stripe", "PostgreSQL local"]
+
+**Staging:**
+- Diferenças específicas do ambiente: [ex.: "usa conta Stripe de staging"]
+- Dados: [ex.: "banco de dados de staging separado"]
+
+**Produção:**
+- Gerenciamento de segredos: [ex.: "variáveis de ambiente Vercel"]
+- Failover/redundância: [ex.: "replicação DB multi-região"]
+
+## Webhooks & Callbacks
+
+**Recebidos:**
+- [Serviço] - [Endpoint: ex.: "/api/webhooks/stripe"]
+  - Verificação: [ex.: "validação de assinatura via stripe.webhooks.constructEvent"]
+  - Eventos: [ex.: "payment_intent.succeeded, customer.subscription.updated"]
+
+**Enviados:**
+- [Serviço] - [O que o aciona]
+  - Endpoint: [ex.: "webhook CRM externo no cadastro do usuário"]
+  - Lógica de retry: [se aplicável]
+
+---
+
+*Auditoria de integrações: [data]*
+*Atualizar ao adicionar/remover serviços externos*
+```
+
+<good_examples>
+```markdown
+# External Integrations
+
+**Analysis Date:** 2025-01-20
+
+## APIs & External Services
+
+**Payment Processing:**
+- Stripe - Subscription billing and one-time course payments
+  - SDK/Client: stripe npm package v14.8
+  - Auth: API key in STRIPE_SECRET_KEY env var
+  - Endpoints used: checkout sessions, customer portal, webhooks
+
+**Email/SMS:**
+- SendGrid - Transactional emails (receipts, password resets)
+  - SDK/Client: @sendgrid/mail v8.1
+  - Auth: API key in SENDGRID_API_KEY env var
+  - Templates: Managed in SendGrid dashboard (template IDs in code)
+
+---
+
+*Integration audit: 2025-01-20*
+*Update when adding/removing external services*
+```
+</good_examples>
+
+<guidelines>
+**O que pertence ao INTEGRATIONS.md:**
+- Serviços externos com os quais o código se comunica
+- Padrões de autenticação (onde os segredos vivem, não os segredos em si)
+- SDKs e bibliotecas client usadas
+- Nomes das variáveis de ambiente (não os valores)
+- Endpoints de webhook e métodos de verificação
+- Padrões de conexão com banco de dados
+- Localizações de armazenamento de arquivos
+- Serviços de monitoramento e logging
+
+**O que NÃO pertence aqui:**
+- Chaves de API ou segredos reais (NUNCA escreva esses)
+- Arquitetura interna (isso é ARCHITECTURE.md)
+- Padrões de código (isso é PATTERNS.md)
+- Escolhas tecnológicas (isso é STACK.md)
+- Problemas de performance (isso é CONCERNS.md)
+
+**Ao preencher este template:**
+- Verificar .env.example ou .env.template para variáveis de ambiente necessárias
+- Procurar imports de SDK (stripe, @sendgrid/mail, etc.)
+- Verificar handlers de webhook em rotas/endpoints
+- Notar onde os segredos são gerenciados (não os segredos)
+- Documentar diferenças específicas do ambiente (dev/staging/prod)
+- Incluir padrões de auth para cada serviço
+
+**Útil para planejamento de fases quando:**
+- Adicionando novas integrações com serviços externos
+- Depurando problemas de autenticação
+- Entendendo fluxo de dados fora da aplicação
+- Configurando novos ambientes
+- Auditando dependências de terceiros
+- Planejando para falhas ou migrações de serviço
+
+**Nota de segurança:**
+Documentar ONDE os segredos vivem (variáveis de ambiente, dashboard Vercel, 1Password), nunca QUAIS são os segredos.
+</guidelines>

package/kit/framework/templates/codebase/stack.md

@@ -0,0 +1,158 @@
+# Template de Stack Tecnológico
+
+Template para `.planning/codebase/STACK.md` - captura a fundação tecnológica.
+
+**Propósito:** Documentar quais tecnologias executam este codebase. Focado em "o que executa quando você roda o código."
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Stack Tecnológico
+
+**Data da Análise:** [AAAA-MM-DD]
+
+## Linguagens
+
+**Primária:**
+- [Linguagem] [Versão] - [Onde usada: ex.: "todo o código da aplicação"]
+
+**Secundária:**
+- [Linguagem] [Versão] - [Onde usada: ex.: "scripts de build, tooling"]
+
+## Runtime
+
+**Ambiente:**
+- [Runtime] [Versão] - [ex.: "Node.js 20.x"]
+- [Requisitos adicionais, se houver]
+
+**Gerenciador de Pacotes:**
+- [Gerenciador] [Versão] - [ex.: "npm 10.x"]
+- Lockfile: [ex.: "package-lock.json presente"]
+
+## Frameworks
+
+**Core:**
+- [Framework] [Versão] - [Propósito: ex.: "servidor web", "framework de UI"]
+
+**Testes:**
+- [Framework] [Versão] - [ex.: "Jest para testes unitários"]
+- [Framework] [Versão] - [ex.: "Playwright para E2E"]
+
+**Build/Dev:**
+- [Ferramenta] [Versão] - [ex.: "Vite para bundling"]
+- [Ferramenta] [Versão] - [ex.: "Compilador TypeScript"]
+
+## Dependências Chave
+
+[Incluir apenas dependências críticas para entender o stack — limitar a 5-10 mais importantes]
+
+**Críticas:**
+- [Pacote] [Versão] - [Por que importa: ex.: "autenticação", "acesso ao banco de dados"]
+- [Pacote] [Versão] - [Por que importa]
+
+**Infraestrutura:**
+- [Pacote] [Versão] - [ex.: "Express para roteamento HTTP"]
+- [Pacote] [Versão] - [ex.: "Client PostgreSQL"]
+
+## Configuração
+
+**Ambiente:**
+- [Como configurado: ex.: "arquivos .env", "variáveis de ambiente"]
+- [Configs chave: ex.: "DATABASE_URL, API_KEY obrigatórios"]
+
+**Build:**
+- [Arquivos de config de build: ex.: "vite.config.ts, tsconfig.json"]
+
+## Requisitos de Plataforma
+
+**Desenvolvimento:**
+- [Requisitos de SO ou "qualquer plataforma"]
+- [Tooling adicional: ex.: "Docker para banco local"]
+
+**Produção:**
+- [Alvo de deployment: ex.: "Vercel", "AWS Lambda", "container Docker"]
+- [Requisitos de versão]
+
+---
+
+*Análise de stack: [data]*
+*Atualizar após mudanças principais de dependências*
+```
+
+<good_examples>
+```markdown
+# Technology Stack
+
+**Analysis Date:** 2025-01-20
+
+## Languages
+
+**Primary:**
+- TypeScript 5.3 - All application code
+
+**Secondary:**
+- JavaScript - Build scripts, config files
+
+## Runtime
+
+**Environment:**
+- Node.js 20.x (LTS)
+- No browser runtime (CLI tool only)
+
+**Package Manager:**
+- npm 10.x
+- Lockfile: `package-lock.json` present
+
+## Frameworks
+
+**Core:**
+- None (vanilla Node.js CLI)
+
+**Testing:**
+- Vitest 1.0 - Unit tests
+- tsx - TypeScript execution without build step
+
+## Key Dependencies
+
+**Critical:**
+- commander 11.x - CLI argument parsing and command structure
+- chalk 5.x - Terminal output styling
+- fs-extra 11.x - Extended file system operations
+
+---
+
+*Stack analysis: 2025-01-20*
+*Update after major dependency changes*
+```
+</good_examples>
+
+<guidelines>
+**O que pertence ao STACK.md:**
+- Linguagens e versões
+- Requisitos de runtime (Node, Bun, Deno, browser)
+- Gerenciador de pacotes e lockfile
+- Escolhas de framework
+- Dependências críticas (limitar a 5-10 mais importantes)
+- Tooling de build
+- Requisitos de plataforma/deployment
+
+**O que NÃO pertence aqui:**
+- Estrutura de arquivos (isso é STRUCTURE.md)
+- Padrões arquiteturais (isso é ARCHITECTURE.md)
+- Toda dependência no package.json (apenas as críticas)
+- Detalhes de implementação (diferir para o código)
+
+**Ao preencher este template:**
+- Verificar package.json para dependências
+- Notar versão do runtime em .nvmrc ou engines do package.json
+- Incluir apenas dependências que afetam o entendimento (não todo utilitário)
+- Especificar versões apenas quando a versão importa (mudanças breaking, compatibilidade)
+
+**Útil para planejamento de fases quando:**
+- Adicionando novas dependências (verificar compatibilidade)
+- Atualizando frameworks (saber o que está em uso)
+- Escolhendo abordagem de implementação (deve funcionar com stack existente)
+- Entendendo requisitos de build
+</guidelines>