@girardelli/architect-agents 8.1.0

package/src/core/agent-generator/templates/core/hooks-generator.ts

@@ -0,0 +1,244 @@
+import { TemplateContext, EnrichedTemplateContext } from '@girardelli/architect-agents/src/core/agent-generator/types/template.js';
+import { getEnriched } from '../template-helpers.js';
+
+/**
+ * Generates executable hook scripts (.sh) for the .agent/hooks/ directory.
+ * These are real, runnable shell scripts tied to git lifecycle events.
+ *
+ * v5.1: Uses project-specific toolchain commands, score thresholds,
+ * and coverage targets from the enriched context.
+ */
+
+/**
+ * Pre-commit hook: lint + build check
+ */
+export function generatePreCommitHook(ctx: TemplateContext | EnrichedTemplateContext): string {
+  const enriched = getEnriched(ctx);
+  const tc = enriched.toolchain;
+    // @ts-ignore - Audit cleanup unused variable
+  const config = ctx.config;
+  const projectName = ctx.projectName;
+
+  const lintCmd = tc?.lintCmd || 'npx eslint .';
+  const buildCmd = tc?.buildCmd || 'npm run build';
+
+  return `#!/bin/bash
+# ============================================================
+# PRE-COMMIT HOOK — ${projectName}
+# Gerado por Architect v5.1
+#
+# Instalação:
+#   cp .agent/hooks/pre-commit.sh .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+# ============================================================
+
+set -e
+
+echo "🔍 [pre-commit] Verificando qualidade do código..."
+
+# ── 1. Branch Safety ──
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" == "main" || "$BRANCH" == "master" || "$BRANCH" == "staging" || "$BRANCH" == "develop" ]]; then
+  echo "❌ BLOQUEADO: Commit direto em '$BRANCH' é proibido."
+  echo "   Crie uma branch: git checkout -b feature/<nome>"
+  exit 1
+fi
+
+# ── 2. Secrets Check ──
+echo "🔐 Verificando secrets..."
+SECRETS_PATTERN='(password|secret|api[_-]?key|access[_-]?token|private[_-]?key)\\s*[:=]\\s*["\\'\\x60][^"\\x60]{8,}'
+
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+if echo "$STAGED_FILES" | xargs grep -ilE "$SECRETS_PATTERN" 2>/dev/null; then
+  echo "❌ BLOQUEADO: Possível secret detectado nos arquivos staged."
+  echo "   Remova o secret e use variáveis de ambiente."
+  exit 1
+fi
+
+# ── 3. File Size Check ──
+echo "📏 Verificando tamanho de arquivos..."
+for file in $STAGED_FILES; do
+  if [ -f "$file" ]; then
+    LINES=$(wc -l < "$file" 2>/dev/null || echo "0")
+    if [ "$LINES" -gt 500 ]; then
+      echo "⚠️  AVISO: $file tem $LINES linhas (limite: 500)"
+    fi
+  fi
+done
+
+# ── 4. Lint ──
+echo "🧹 Executando lint..."
+${lintCmd} --quiet 2>/dev/null || {
+  echo "❌ BLOQUEADO: Lint falhou."
+  echo "   Corrija: ${lintCmd}"
+  exit 1
+}
+
+# ── 5. Build ──
+echo "🔨 Verificando build..."
+${buildCmd} 2>/dev/null || {
+  echo "❌ BLOQUEADO: Build falhou."
+  echo "   Corrija: ${buildCmd}"
+  exit 1
+}
+
+# ── 6. Debug Statements ──
+echo "🐛 Verificando debug statements..."
+if echo "$STAGED_FILES" | xargs grep -n 'console\\.log\\|debugger\\|print(' 2>/dev/null | grep -v 'node_modules' | grep -v '.test.'; then
+  echo "⚠️  AVISO: Debug statements encontrados. Remova antes do merge."
+fi
+
+echo "✅ [pre-commit] Tudo OK — commit liberado."
+exit 0
+`;
+}
+
+/**
+ * Pre-push hook: test + score gate
+ */
+export function generatePrePushHook(ctx: TemplateContext | EnrichedTemplateContext): string {
+  const enriched = getEnriched(ctx);
+  const tc = enriched.toolchain;
+  const config = ctx.config;
+  const projectName = ctx.projectName;
+
+  const testCmd = tc?.testCmd || 'npm test';
+  const coverageCmd = tc?.coverageCmd || 'npm run test -- --coverage';
+
+  return `#!/bin/bash
+# ============================================================
+# PRE-PUSH HOOK — ${projectName}
+# Gerado por Architect v5.1
+#
+# Instalação:
+#   cp .agent/hooks/pre-push.sh .git/hooks/pre-push
+#   chmod +x .git/hooks/pre-push
+# ============================================================
+
+set -e
+
+echo "🚀 [pre-push] Verificação completa antes do push..."
+
+# ── 1. Branch Safety ──
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
+  echo "❌ BLOQUEADO: Push direto para '$BRANCH' é proibido."
+  echo "   Use Pull Request."
+  exit 1
+fi
+
+# ── 2. Full Test Suite ──
+echo "🧪 Executando testes completos..."
+${testCmd} || {
+  echo "❌ BLOQUEADO: Testes falharam."
+  echo "   Corrija antes de fazer push."
+  exit 1
+}
+
+# ── 3. Coverage Gate ──
+echo "📊 Verificando cobertura (mínimo: ${config.coverageMinimum}%)..."
+COVERAGE_OUTPUT=$(${coverageCmd} 2>&1 || true)
+echo "$COVERAGE_OUTPUT" | tail -5
+
+# Parse coverage percentage (works with Jest/Istanbul output)
+COVERAGE=$(echo "$COVERAGE_OUTPUT" | grep -oP 'All files[^|]*\\|\\s*[\\d.]+' | grep -oP '[\\d.]+$' || echo "0")
+if [ -n "$COVERAGE" ]; then
+  COVERAGE_INT=\${COVERAGE%.*}
+  if [ "$COVERAGE_INT" -lt ${config.coverageMinimum} ] 2>/dev/null; then
+    echo "⚠️  AVISO: Cobertura ($COVERAGE_INT%) abaixo do mínimo (${config.coverageMinimum}%)"
+  fi
+fi
+
+# ── 4. Architecture Score Gate ──
+echo "🏗️ Verificando score de arquitetura (mínimo: ${config.scoreThreshold}/100)..."
+if command -v architect &> /dev/null; then
+  SCORE=$(architect score . --json 2>/dev/null | grep -oP '"overall":\\s*\\K[0-9]+' || echo "N/A")
+  if [ "$SCORE" != "N/A" ] && [ "$SCORE" -lt ${config.scoreThreshold} ] 2>/dev/null; then
+    echo "❌ BLOQUEADO: Score ($SCORE/100) abaixo do mínimo (${config.scoreThreshold}/100)"
+    exit 1
+  fi
+  echo "   Score: $SCORE/100 ✅"
+else
+  echo "   ⏭️  architect não instalado — skip score gate"
+fi
+
+echo "✅ [pre-push] Tudo OK — push liberado."
+exit 0
+`;
+}
+
+/**
+ * Post-analysis hook: remediation actions
+ */
+export function generatePostAnalysisHook(ctx: TemplateContext | EnrichedTemplateContext): string {
+    // @ts-ignore - Audit cleanup unused variable
+  const enriched = getEnriched(ctx);
+  const projectName = ctx.projectName;
+  const report = ctx.report;
+
+  return `#!/bin/bash
+# ============================================================
+# POST-ANALYSIS HOOK — ${projectName}
+# Gerado por Architect v5.1
+#
+# Executa após 'architect analyze .' para gerar ações
+# de remediação automáticas.
+#
+# Uso:
+#   architect analyze . && bash .agent/hooks/post-analysis.sh
+# ============================================================
+
+set -e
+
+echo "🔧 [post-analysis] Processando resultados da análise..."
+
+REPORT_JSON="architect-report.json"
+REPORT_HTML="architect-report.html"
+
+# ── 1. Score Evolution ──
+CURRENT_SCORE=${report.score.overall}
+echo "📊 Score atual: $CURRENT_SCORE/100"
+echo "   Meta curto prazo: ${Math.min(100, report.score.overall + 5)}/100"
+echo "   Meta médio prazo: ${Math.min(100, report.score.overall + 10)}/100"
+
+# ── 2. Critical Anti-Patterns Alert ──
+CRITICAL_COUNT=$(grep -c '"severity":"CRITICAL"' "$REPORT_JSON" 2>/dev/null || echo "0")
+HIGH_COUNT=$(grep -c '"severity":"HIGH"' "$REPORT_JSON" 2>/dev/null || echo "0")
+
+if [ "$CRITICAL_COUNT" -gt 0 ]; then
+  echo ""
+  echo "🔴 ATENÇÃO: $CRITICAL_COUNT anti-patterns CRÍTICOS detectados!"
+  echo "   Resolva antes do próximo sprint."
+fi
+
+if [ "$HIGH_COUNT" -gt 0 ]; then
+  echo "🟠 $HIGH_COUNT anti-patterns HIGH detectados."
+fi
+
+# ── 3. Generate Summary ──
+echo ""
+echo "📋 Resumo:"
+echo "   Arquivos: ${report.projectInfo.totalFiles}"
+echo "   Linhas: ${report.projectInfo.totalLines.toLocaleString()}"
+echo "   Anti-patterns: ${report.antiPatterns.length}"
+echo ""
+
+# ── 4. Suggestions ──
+if [ -f "$REPORT_JSON" ]; then
+  echo "💡 Top 5 sugestões:"
+  cat "$REPORT_JSON" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for s in data.get('suggestions', [])[:5]:
+    print(f'   → {s.get(\"description\", \"\")}')
+" 2>/dev/null || echo "   (instale python3 para ver sugestões)"
+fi
+
+echo ""
+echo "📄 Report HTML: $REPORT_HTML"
+echo "📦 Report JSON: $REPORT_JSON"
+echo ""
+echo "✅ [post-analysis] Concluído."
+exit 0
+`;
+}

package/src/core/agent-generator/templates/core/index-md.ts

@@ -0,0 +1,261 @@
+import { TemplateContext } from '@girardelli/architect-agents/src/core/agent-generator/types/template.js';
+
+/**
+ * Generates enterprise-grade INDEX.md — master navigation guide for the agent framework.
+ * ~350+ lines with: mandatory reads, situational guide, agent catalog, templates, flow diagram.
+ */
+export function generateIndexMd(ctx: TemplateContext): string {
+    // @ts-ignore - Audit cleanup unused variable
+  const { report, stack, projectName, stackLabel, plan, config } = ctx;
+
+  const agents = buildAgentCatalog(ctx);
+  const situationalGuide = buildSituationalGuide(ctx);
+  const templates = buildTemplatesCatalog();
+
+  return `# ${projectName} — Agent Framework
+
+> **Auto-generated by [Architect v8.1](https://github.com/camilooscargbaptista/architect)**
+> Stack: **${stackLabel}** | Score: **${report.score.overall}/100** | Files: **${report.projectInfo.totalFiles}** | Lines: **${report.projectInfo.totalLines.toLocaleString()}**
+
+---
+
+## ⛔ PARE AQUI — LEITURA OBRIGATÓRIA
+
+> **Antes de qualquer ação, leia estes documentos NA ORDEM.**
+> Pular esta etapa é violação do protocolo.
+
+| # | Arquivo | O que contém | Quando ler |
+|---|---------|-------------|-----------|
+| 1 | [00-general.md](./rules/00-general.md) | Regras de Ouro, convenções, identidade do projeto | **SEMPRE** |
+| 2 | [PREFLIGHT.md](./guards/PREFLIGHT.md) | Checklist pré-ação por camada | **SEMPRE** |
+| 3 | [QUALITY-GATES.md](./guards/QUALITY-GATES.md) | Métricas mínimas, blockers, processo de verificação | **SEMPRE** |
+| 4 | [CODE-REVIEW-CHECKLIST.md](./guards/CODE-REVIEW-CHECKLIST.md) | Pontos obrigatórios de revisão | Antes de PR |
+
+---
+
+## 🗺️ Guia Situacional
+
+> **"O que vou fazer?"** → Siga a coluna correspondente.
+
+${situationalGuide}
+
+---
+
+## 🤖 Agentes Disponíveis
+
+${agents}
+
+---
+
+## 📋 Templates Disponíveis
+
+${templates}
+
+---
+
+## 📁 Estrutura do Framework
+
+\`\`\`
+.agent/
+├── INDEX.md              ← VOCÊ ESTÁ AQUI
+├── agents/               → Agentes especializados
+│   ├── AGENT-ORCHESTRATOR.md
+${stack.hasBackend ? `│   ├── ${stack.primary.toUpperCase()}-BACKEND-DEVELOPER.md\n` : ''}${stack.hasFrontend ? `│   ├── FRONTEND-DEVELOPER.md\n` : ''}${stack.hasMobile ? `│   ├── FLUTTER-UI-DEVELOPER.md\n` : ''}${stack.hasDatabase ? `│   ├── DATABASE-ENGINEER.md\n` : ''}│   ├── SECURITY-AUDITOR.md
+│   ├── QA-TEST-ENGINEER.md
+│   └── TECH-DEBT-CONTROLLER.md
+├── rules/                → Regras de codificação
+│   ├── 00-general.md
+│   ├── 01-architecture.md
+│   └── 02-security.md
+├── guards/               → Checklists e quality gates
+│   ├── PREFLIGHT.md
+│   ├── QUALITY-GATES.md
+│   └── CODE-REVIEW-CHECKLIST.md
+├── workflows/            → Fluxos de trabalho
+│   ├── new-feature.md
+│   ├── fix-bug.md
+│   └── review.md
+├── templates/            → Templates reutilizáveis
+│   ├── C4.md
+│   ├── BDD.md
+│   ├── TDD.md
+│   ├── ADR.md
+│   └── THREAT-MODEL.md
+└── skills/               → Padrões e referências
+\`\`\`
+
+---
+
+## 🔄 Fluxo Completo de Desenvolvimento
+
+\`\`\`
+REQUISIÇÃO RECEBIDA
+       │
+       ▼
+┌──────────────────┐
+│  PREFLIGHT.md    │ ← Ler OBRIGATÓRIO
+│  (diagnóstico)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  ORCHESTRATOR    │ ← Decompõe a requisição
+│  (classificar)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────────────────────────┐
+│         6 GATES OBRIGATÓRIOS         │
+│                                      │
+│  1. MOCKUP (se tem UI)               │
+│  2. User Stories                     │
+│  3. Arquitetura (C4)                 │
+│  4. Tarefas (breakdown)              │
+│  5. BDD (cenários)                   │
+│  6. TDD (casos de teste)            │
+│                                      │
+│  ⚠️  /approved após cada gate        │
+└────────┬─────────────────────────────┘
+         │
+         ▼
+┌──────────────────────────────────────┐
+│      IMPLEMENTAÇÃO (ordenada)        │
+│                                      │
+│  1° Backend (se houver)              │
+│  2° Documento de Integração          │
+│  3° Frontend / App (se houver)       │
+└────────┬─────────────────────────────┘
+         │
+         ▼
+┌──────────────────┐
+│  QUALITY-GATES   │ ← Build + Coverage ≥ ${config.coverageMinimum}%
+│  (verificação)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  CODE REVIEW     │ ← Checklist obrigatório
+│  (PR)            │
+└────────┬─────────┘
+         │
+         ▼
+      ✅ DONE
+\`\`\`
+
+---
+
+## ⚡ Atalhos Rápidos
+
+| Situação | Comando / Workflow |
+|----------|-------------------|
+| Nova feature | \`/new-feature\` → [workflow](./workflows/new-feature.md) |
+| Corrigir bug | \`/fix-bug\` → [workflow](./workflows/fix-bug.md) |
+| Code review | \`/review\` → [workflow](./workflows/review.md) |
+| Verificar qualidade | \`architect score ./src\` |
+| Analisar arquitetura | \`architect analyze ./src\` |
+
+---
+
+## 🔌 Plugin Recomendado
+
+Para análise contínua de arquitetura e manutenção do score:
+
+\`\`\`
+┌─────────────────────────────────────────────┐
+│  📦 @girardelli/architect                   │
+│  Plugin para Claude Code                    │
+│                                             │
+│  npm install -g @girardelli/architect       │
+│                                             │
+│  Comandos:                                  │
+│  • architect analyze ./src                  │
+│  • architect score ./src                    │
+│  • architect agents ./src                   │
+│  • architect refactor ./src                 │
+│                                             │
+│  Score atual: ${String(report.score.overall).padEnd(2)}/100                        │
+│  Meta: ${String(Math.min(100, report.score.overall + 10)).padEnd(3)}/100                       │
+└─────────────────────────────────────────────┘
+\`\`\`
+
+---
+
+## ⚠️ REGRA DE OURO
+
+> **Na dúvida, PARA e PERGUNTA ao humano.**
+> Nunca assuma. Nunca decida sozinho. Sempre valide.
+
+---
+
+**Gerado por Architect v8.1 · Score: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}
+
+function buildAgentCatalog(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const rows: string[] = [];
+
+  rows.push('| Agente | Role | Capabilities |');
+  rows.push('|--------|------|-------------|');
+  rows.push('| [AGENT-ORCHESTRATOR](./agents/AGENT-ORCHESTRATOR.md) | coordination | Decomposição, dispatch, consolidação, quality gate |');
+
+  if (stack.hasBackend) {
+    rows.push(`| [${stack.primary.toUpperCase()}-BACKEND-DEVELOPER](./agents/${stack.primary.toUpperCase()}-BACKEND-DEVELOPER.md) | development | APIs, serviços, lógica de negócio, migrations |`);
+  }
+  if (stack.hasFrontend) {
+    const fw = stack.frameworks.find(f => ['Angular', 'Vue', 'Next.js', 'React'].includes(f)) || 'FRONTEND';
+    rows.push(`| [${fw.toUpperCase().replace('.', '')}-FRONTEND-DEVELOPER](./agents/${fw.toUpperCase().replace('.', '')}-FRONTEND-DEVELOPER.md) | development | Componentes, state management, UX responsiva |`);
+  }
+  if (stack.hasMobile) {
+    rows.push('| [FLUTTER-UI-DEVELOPER](./agents/FLUTTER-UI-DEVELOPER.md) | development | Screens, widgets, navegação, integração API |');
+  }
+  if (stack.hasDatabase) {
+    rows.push('| [DATABASE-ENGINEER](./agents/DATABASE-ENGINEER.md) | development | Schema, migrations, indexação, performance |');
+  }
+
+  rows.push('| [SECURITY-AUDITOR](./agents/SECURITY-AUDITOR.md) | quality | Ameaças STRIDE, OWASP, LGPD, vulnerabilidades |');
+  rows.push('| [QA-TEST-ENGINEER](./agents/QA-TEST-ENGINEER.md) | quality | Planos de teste, BDD/TDD, cobertura, regressão |');
+  rows.push('| [TECH-DEBT-CONTROLLER](./agents/TECH-DEBT-CONTROLLER.md) | governance | Débito técnico, refatorações, metas de score |');
+
+  return rows.join('\n');
+}
+
+function buildSituationalGuide(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const rows: string[] = [];
+
+  rows.push('| Ação | Leia antes | Workflow | Agente principal |');
+  rows.push('|------|-----------|---------|-----------------|');
+  rows.push('| Nova feature | 00-general + PREFLIGHT | [new-feature](./workflows/new-feature.md) | ORCHESTRATOR |');
+  rows.push('| Corrigir bug | 00-general + PREFLIGHT | [fix-bug](./workflows/fix-bug.md) | ORCHESTRATOR |');
+
+  if (stack.hasBackend) {
+    rows.push(`| Mexer em backend | 00-general + 01-architecture | new-feature ou fix-bug | ${stack.primary.toUpperCase()}-BACKEND |`);
+  }
+  if (stack.hasFrontend) {
+    rows.push('| Mexer em frontend | 00-general + 01-architecture | new-feature ou fix-bug | FRONTEND |');
+  }
+  if (stack.hasMobile) {
+    rows.push('| Mexer no app | 00-general | new-feature ou fix-bug | FLUTTER-UI |');
+  }
+  if (stack.hasDatabase) {
+    rows.push('| Mexer em banco | 00-general + 01-architecture | new-feature | DATABASE-ENGINEER |');
+  }
+
+  rows.push('| Segurança | 02-security | — | SECURITY-AUDITOR |');
+  rows.push('| Testes | 00-general | — | QA-TEST-ENGINEER |');
+  rows.push('| Refatoração | QUALITY-GATES | — | TECH-DEBT-CONTROLLER |');
+  rows.push('| Code review | CODE-REVIEW-CHECKLIST | [review](./workflows/review.md) | QA-TEST-ENGINEER |');
+
+  return rows.join('\n');
+}
+
+function buildTemplatesCatalog(): string {
+  return `| Template | Arquivo | Quando usar |
+|----------|---------|-----------|
+| C4 Architecture | [C4.md](./templates/C4.md) | Documentar arquitetura de qualquer feature |
+| BDD Scenarios | [BDD.md](./templates/BDD.md) | Antes de implementar — cenários de aceite |
+| TDD Cases | [TDD.md](./templates/TDD.md) | Antes de implementar — casos de teste |
+| ADR | [ADR.md](./templates/ADR.md) | Decisões arquiteturais significativas |
+| Threat Model | [THREAT-MODEL.md](./templates/THREAT-MODEL.md) | Features que lidam com dados sensíveis |`;
+}