@girardelli/architect 5.0.0 → 6.0.0

package/.agent/rules/02-security.md

@@ -0,0 +1,388 @@
+---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'Regras de segurança para @girardelli/architect'
+  priority: CRITICAL
+---
+
+# 🛡️ Regras de Segurança — @girardelli/architect
+
+> **Segurança NÃO é feature — é requisito. Toda linha de código é superfície de ataque.**
+
+---
+
+## ⚠️ REGRA ZERO DE SEGURANÇA
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  NUNCA confiar em input do usuário.                         ║
+║  NUNCA expor detalhes internos em respostas de erro.        ║
+║  NUNCA armazenar secrets em código.                         ║
+║  NUNCA desabilitar validação "temporariamente".             ║
+║  NUNCA commitar com security warnings ignorados.            ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🔐 OWASP Top 10 — Checklist Obrigatório
+
+### A01: Broken Access Control
+```
+❌ PROIBIDO: Endpoint sem verificação de autorização
+❌ PROIBIDO: IDOR (Insecure Direct Object Reference) — acessar recurso de outro usuário via ID
+✅ CORRETO: RBAC (Role-Based Access Control) em TODOS os endpoints
+✅ CORRETO: Verificar ownership do recurso antes de retornar
+
+Padrão:
+1. Autenticar (quem é?)
+2. Autorizar (pode fazer isso?)
+3. Verificar ownership (esse recurso é dele?)
+4. Executar ação
+```
+
+### A02: Cryptographic Failures
+```
+❌ PROIBIDO: Senhas em plain text
+❌ PROIBIDO: HTTP para dados sensíveis
+❌ PROIBIDO: Algoritmos fracos (MD5, SHA1 para passwords)
+✅ CORRETO: bcrypt/argon2 para passwords (cost ≥ 12)
+✅ CORRETO: HTTPS everywhere (HSTS)
+✅ CORRETO: AES-256-GCM para dados em repouso
+✅ CORRETO: TLS 1.2+ para dados em trânsito
+```
+
+### A03: Injection
+```
+❌ PROIBIDO: Concatenação de strings em queries SQL
+❌ PROIBIDO: Template strings com input de usuário
+❌ PROIBIDO: eval(), exec(), Function() com input externo
+✅ CORRETO: Queries parametrizadas SEMPRE
+✅ CORRETO: ORM com bindings
+✅ CORRETO: Input sanitization na borda (controller/pipe)
+
+Exemplos:
+  ❌ `SELECT * FROM users WHERE id = '${userId}'`
+  ✅ `SELECT * FROM users WHERE id = $1` + [userId]
+  ❌ `db.query(`...WHERE name = '${name}'`)`
+  ✅ `db.query('...WHERE name = ?', [name])`
+```
+
+### A04: Insecure Design
+```
+❌ PROIBIDO: Endpoints sem rate limiting
+❌ PROIBIDO: Reset de senha via link sem expiração
+❌ PROIBIDO: Lógica de negócio sem threat model
+✅ CORRETO: STRIDE analysis antes de implementar features sensíveis
+✅ CORRETO: Rate limiting em auth endpoints (≤ 5 tentativas/minuto)
+✅ CORRETO: Tokens com expiração curta (15min access, 7d refresh)
+```
+
+### A05: Security Misconfiguration
+```
+❌ PROIBIDO: CORS com origin: '*' em produção
+❌ PROIBIDO: Debug mode em produção
+❌ PROIBIDO: Default credentials
+❌ PROIBIDO: Stack traces em respostas de erro
+✅ CORRETO: CORS restritivo (origins explícitos)
+✅ CORRETO: Headers de segurança (X-Frame-Options, CSP, X-Content-Type-Options)
+✅ CORRETO: Error handling que retorna apenas mensagem genérica ao usuário
+
+Headers obrigatórios:
+  X-Content-Type-Options: nosniff
+  X-Frame-Options: DENY
+  X-XSS-Protection: 0 (CSP substitui)
+  Content-Security-Policy: default-src 'self'
+  Strict-Transport-Security: max-age=31536000; includeSubDomains
+  Referrer-Policy: strict-origin-when-cross-origin
+```
+
+### A06: Vulnerable and Outdated Components
+```
+❌ PROIBIDO: Dependências com vulnerabilidades conhecidas
+❌ PROIBIDO: Ignorar security advisories
+✅ CORRETO: Audit regular (npm audit / pip audit / safety check)
+✅ CORRETO: Renovate/Dependabot configurado
+✅ CORRETO: Lock files commitados (package-lock.json, poetry.lock)
+
+Comandos de verificação:
+  $ npm audit
+  $ npx audit-ci --critical
+  $ npx snyk test
+```
+
+### A07: Identification and Authentication Failures
+```
+❌ PROIBIDO: Sessions sem expiração
+❌ PROIBIDO: Tokens previsíveis
+❌ PROIBIDO: Brute force sem proteção
+✅ CORRETO: JWT com algoritmo explícito (RS256 ou ES256)
+✅ CORRETO: Refresh token rotation
+✅ CORRETO: Account lockout após N tentativas
+✅ CORRETO: MFA para operações sensíveis
+
+JWT Checklist:
+  □ Algoritmo explícito (nunca 'none')
+  □ Audience (aud) verificado
+  □ Issuer (iss) verificado
+  □ Expiração (exp) curta
+  □ Secret key ≥ 256 bits
+  □ Stored em httpOnly cookie (não localStorage)
+```
+
+### A08: Software and Data Integrity Failures
+```
+❌ PROIBIDO: CI/CD sem verificação de integridade
+❌ PROIBIDO: Deserialização de dados não confiáveis
+✅ CORRETO: Subresource Integrity (SRI) para CDN scripts
+✅ CORRETO: Signed commits
+✅ CORRETO: Pipeline protegido (branch protection rules)
+```
+
+### A09: Security Logging and Monitoring Failures
+```
+❌ PROIBIDO: Ações sensíveis sem log
+❌ PROIBIDO: Logs com dados sensíveis (passwords, tokens, PII)
+✅ CORRETO: Audit log para: login, logout, password change, permission change
+✅ CORRETO: Log level adequado (WARN/ERROR para falhas de auth)
+✅ CORRETO: Alertas para atividades anômalas
+
+O que logar:
+  ✅ Quem (user ID)
+  ✅ O quê (ação)
+  ✅ Quando (timestamp UTC)
+  ✅ Onde (IP, user-agent)
+  ✅ Resultado (sucesso/falha)
+
+O que NUNCA logar:
+  ❌ Passwords (nem em debug)
+  ❌ Tokens de autenticação
+  ❌ Dados de cartão de crédito
+  ❌ PII sem necessidade
+```
+
+### A10: Server-Side Request Forgery (SSRF)
+```
+❌ PROIBIDO: Fetch de URL fornecida pelo usuário sem validação
+❌ PROIBIDO: Acesso a metadata endpoints (169.254.169.254)
+✅ CORRETO: Allowlist de domínios para requests externos
+✅ CORRETO: Validação de schema (https only)
+✅ CORRETO: Block de IPs internos/privados
+```
+
+---
+
+## 🔑 Validação de Input
+
+### Validação de Input — Padrão Geral
+
+```
+Regras de validação:
+1. TODOS os inputs passam por schema validation
+2. Tipos verificados (string, number, email, etc.)
+3. Limites definidos (min/max length, ranges)
+4. Whitelist de campos aceitos
+5. Sanitização de caracteres especiais
+6. Encoding correto (UTF-8)
+
+Pipeline:
+  Request → Schema Validation → Sanitization → Business Logic
+
+NUNCA:
+  ❌ request.body direto na lógica
+  ❌ Confiar em validação client-side apenas
+  ❌ Aceitar campos não declarados
+```
+
+---
+
+## 🔒 Autenticação & Autorização
+
+### Padrão de Autenticação/Autorização
+
+```
+Fluxo obrigatório:
+1. Autenticar: Verificar identidade (JWT/session)
+2. Autorizar: Verificar permissões (roles/policies)
+3. Ownership: Verificar se recurso pertence ao usuário
+4. Executar: Somente após passos 1-3
+
+Token management:
+  - Access Token: curta duração (15min)
+  - Refresh Token: longa duração (7d), httpOnly, secure
+  - Rotation: novo refresh token a cada uso
+  - Blacklist: invalidar tokens no logout
+
+RBAC mínimo:
+  - admin: tudo
+  - user: próprios recursos
+  - public: endpoints marcados explicitamente
+```
+
+---
+
+## 🗝️ Gestão de Secrets
+
+### Regras de Secrets
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  SECRETS NUNCA NO CÓDIGO. NUNCA. SEM EXCEÇÃO.               ║
+╚══════════════════════════════════════════════════════════════╝
+
+❌ PROIBIDO:
+  - API keys hardcoded
+  - Passwords em arquivos de config
+  - Tokens em constantes
+  - Connection strings com credenciais no código
+  - .env commitado no repositório
+
+✅ CORRETO:
+  - Environment variables
+  - Secret manager (AWS SSM, Vault, GCP Secret Manager)
+  - .env.example com placeholders (sem valores reais)
+  - .gitignore com: .env, .env.local, .env.*.local
+```
+
+### .gitignore obrigatório
+
+```
+# Secrets — NUNCA commitar
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+*.p12
+credentials.json
+service-account.json
+```
+
+### Detecção de secrets no CI
+
+```bash
+# Pre-commit hook (recomendado)
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+      - id: gitleaks
+
+# Ou manualmente:
+gitleaks detect --source . --verbose
+git secrets --scan
+```
+
+### Padrão de configuração
+
+```typescript
+// ✅ CORRETO
+const config = {
+  database: {
+    url: process.env.DATABASE_URL,     // De environment variable
+    ssl: process.env.DB_SSL === 'true',
+  },
+  jwt: {
+    secret: process.env.JWT_SECRET,     // NUNCA hardcoded
+    expiresIn: '15m',
+  },
+};
+
+// Validação no startup — falha rápido se falta secret
+const required = ['DATABASE_URL', 'JWT_SECRET'];
+for (const key of required) {
+  if (!process.env[key]) throw new Error(\`Missing env: \${key}\`);
+}
+```
+
+---
+
+## 🚨 Security Anti-Patterns Detectados
+
+✅ Nenhum anti-pattern de segurança detectado no scan automático.\n> ⚠️ Isso NÃO significa que o projeto está seguro. Análise manual é necessária.
+
+---
+
+## ✅ Checklist de Segurança por Camada
+
+### Controller / API Layer
+```
+□ Input validado com DTO/Schema
+□ Rate limiting configurado
+□ Auth guard aplicado
+□ CORS configurado corretamente
+□ Response não expõe dados internos
+□ Error handling sem stack trace
+```
+
+### Service / Business Layer
+```
+□ Autorização verificada (ownership)
+□ Dados sensíveis criptografados
+□ Lógica de negócio com audit log
+□ Sem eval/exec com input externo
+□ Timeout em operações externas
+```
+
+### Data / Repository Layer
+```
+□ Queries parametrizadas (NUNCA concatenação)
+□ Connection pooling com limits
+□ Migrations reversíveis
+□ Dados sensíveis com encryption at rest
+□ Backup policy definida
+```
+
+### Frontend / Mobile Layer
+```
+□ XSS prevenido (sanitization)
+□ CSRF token em formulários
+□ Tokens em httpOnly cookies (não localStorage)
+□ Content Security Policy
+□ Sem secrets no bundle (NUNCA)
+□ Validação client-side + server-side
+```
+
+---
+
+## 🛡️ Threat Model (STRIDE)
+
+Antes de implementar features sensíveis, usar template STRIDE:
+
+```
+| Ameaça              | Descrição                          | Mitigação |
+|---------------------|------------------------------------|-----------|
+| Spoofing            | Alguém se passando por outro       | Auth forte, MFA |
+| Tampering           | Dados alterados em trânsito        | TLS, HMAC, checksums |
+| Repudiation         | Negar ação realizada               | Audit logs |
+| Info Disclosure     | Vazamento de dados                 | Encryption, access control |
+| Denial of Service   | Indisponibilidade                  | Rate limiting, CDN, autoscaling |
+| Elevation of Priv.  | Escalar permissões                 | Least privilege, RBAC |
+```
+
+> Template completo disponível em: `templates/THREAT-MODEL.md`
+
+---
+
+## 📊 Verificação Automatizada
+
+```bash
+# Scan de vulnerabilidades em dependências
+npm audit
+npx audit-ci --critical
+
+# Scan de secrets no código
+# (configure pre-commit hook)
+git secrets --scan
+gitleaks detect
+
+# Score de arquitetura (inclui métricas de segurança)
+architect score ./src
+architect anti-patterns ./src
+```
+
+---
+
+**Gerado por Architect v3.1 · Score: 94/100**

package/.agent/skills/ARCHITECT-INTEGRATION.md

@@ -0,0 +1,103 @@
+---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Como usar o Architect para análise contínua de arquitetura'
+version: 5.1.0
+---
+
+# 🏗️ Skill: Architect Integration — @girardelli/architect
+
+> Como usar `@girardelli/architect` para manter a qualidade arquitetural.
+
+---
+
+## Instalação
+
+```bash
+npm install -g @girardelli/architect
+```
+
+---
+
+## Comandos Disponíveis
+
+### Análise completa
+```bash
+# Gera HTML report + JSON + .agent/ framework
+architect analyze .
+
+# Output:
+#   → architect-report.html (visual)
+#   → architect-report.json (dados)
+#   → .agent/ (framework de agentes)
+```
+
+### Score rápido
+```bash
+# Verificação rápida do score
+architect score .
+
+# JSON output (para CI)
+architect score . --json
+```
+
+### Regenerar agentes
+```bash
+# Regenera .agent/ com dados atualizados
+architect agents .
+```
+
+---
+
+## Estado Atual — @girardelli/architect
+
+| Métrica | Valor |
+|---------|-------|
+| **Score** | 94/100 |
+| **Meta** | 70/100 (mínimo) |
+| **Score Modularity** | 85/100 |
+| **Score Coupling** | 100/100 |
+| **Score Cohesion** | 100/100 |
+| **Score Layering** | 100/100 |
+| **Anti-patterns** | 0 |
+| **Arquivos** | 122 |
+| **Linhas** | 37.407 |
+
+---
+
+## Integração no Workflow
+
+### Antes de criar PR
+```bash
+# Verificar que o score não regrediu
+architect score .
+# Se score < 70 → NÃO criar PR
+```
+
+### Após refatoração
+```bash
+# Verificar melhoria
+architect analyze .
+# Comparar com score anterior
+```
+
+### Revisão de arquitetura
+```bash
+# Gerar report completo para code review
+architect analyze . --output-dir docs/
+```
+
+---
+
+## Quality Gates
+
+```
+Score mínimo para PR:       70/100
+Cobertura mínima:           80%
+Zero anti-patterns CRITICAL: Obrigatório
+Regressão de score:         Proibida
+```
+
+---
+
+**Gerado por Architect v5.1 · Score: 94/100**

package/.agent/skills/CI-PIPELINE.md

@@ -0,0 +1,113 @@
+---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Integração CI/CD com verificação de arquitetura'
+version: 5.1.0
+---
+
+# 🔄 Skill: CI Pipeline — @girardelli/architect
+
+> Pipeline de integração contínua com gates de qualidade arquitetural.
+
+---
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/architect-ci.yml
+name: Architecture CI
+
+on:
+  pull_request:
+    branches: [main, develop, staging]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Coverage
+        run: npm run test -- --coverage
+
+      - name: Architecture Score
+        run: |
+          npm install -g @girardelli/architect
+          SCORE=$(architect score . --json | jq '.overall')
+          echo "Architecture Score: $SCORE/100"
+          if [ "$SCORE" -lt 70 ]; then
+            echo "::error::Score ($SCORE) below threshold (70)"
+            exit 1
+          fi
+
+      - name: No Score Regression
+        run: |
+          # Compare with main branch score
+          CURRENT=$(architect score . --json | jq '.overall')
+          echo "Current: $CURRENT/100, Minimum: 70/100"
+```
+
+---
+
+## Comandos do Pipeline
+
+| Step | Comando | Gate |
+|------|---------|------|
+| Install | `npm install` | — |
+| Build | `npm run build` | ❌ Bloqueia se falhar |
+| Lint | `npm run lint` | ❌ Bloqueia se falhar |
+| Test | `npm test` | ❌ Bloqueia se falhar |
+| Coverage | `npm run test -- --coverage` | ⚠️ Mínimo 80% |
+| Score | `architect score .` | ❌ Mínimo 70/100 |
+
+---
+
+## GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - build
+  - test
+  - quality
+
+build:
+  stage: build
+  script:
+    - npm install
+    - npm run build
+
+test:
+  stage: test
+  script:
+    - npm test
+    - npm run test -- --coverage
+
+architecture:
+  stage: quality
+  script:
+    - npm install -g @girardelli/architect
+    - architect score . --json
+  allow_failure: false
+```
+
+---
+
+**Gerado por Architect v5.1 · Score: 94/100**

package/.agent/skills/PROJECT-PATTERNS.md

@@ -0,0 +1,62 @@
+---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Padrões e convenções específicos do projeto'
+version: 3.1.0
+---
+
+# 📚 Skills: Padrões do Projeto
+
+> Referência rápida dos padrões arquiteturais detectados e como seguí-los.
+
+---
+
+## Convenções
+
+- **Nomenclatura de arquivos:** camelCase para arquivos, PascalCase para classes
+- **Stack:** TypeScript, JavaScript
+- **Frameworks:** Jest v29.7.0, ESLint v8.55.0
+
+---
+
+## Padrões Arquiteturais Detectados
+
+### Extractor/Parser Pattern
+
+Extractors/Parsers são usados para extrair e transformar dados de fontes externas (PDFs, APIs, arquivos).
+
+**Exemplos no projeto:**
+- `src/core/agent-generator/enrichers/endpoint-extractor.ts`
+- `src/core/agent-generator/enrichers/endpoint-extractor.js`
+- `scripts/enrichers/endpoint-extractor.js`
+
+**Como criar um novo:**
+1. Criar interface: `I{Tipo}Extractor`
+2. Implementar: `{Tipo}Extractor implements I{Tipo}Extractor`
+3. Método principal: `extract(source): ExtractedData`
+4. Testar com fixtures (dados de exemplo)
+5. Tratar edge cases: dados vazios, formato inválido, timeout
+
+
+---
+
+## Padrões de Domínio: devtools / code-intelligence
+
+
+
+### Integrações
+- **AWS S3** (storage)
+
+
+
+---
+
+## Checklist para Novo Código
+
+```
+□ Segue os padrões acima?
+□ Testes escritos antes do código (TDD)?
+□ Nomenclatura consistente com convenções?
+□ Sem duplicação de lógica existente?
+□ Documentação atualizada (JSDoc/docstring)?
+```