agent-master-devsecops 0.0.0-stage → 3.9.0

package/scripts/multi_agent_orchestrator.js

@@ -0,0 +1,258 @@
+/**
+ * Multi-Agent Event Bus & Orchestration Engine
+ * Topologia de cooperação determinística, barramento de eventos lógicos
+ * e handovers automáticos entre os 6 modos da suíte multi-agente.
+ * Conforme especificado em docs/ARCHITECTURE.md.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { SECURITY_RULES } = require('./sast_scanner.js');
+
+// Definição canônica dos 6 modos / personas oficiais
+const AGENT_PERSONAS = {
+  ORCHESTRATOR: 'modo: orchestrator',
+  UIUX: 'modo: uiux',
+  DEVSECOPS: 'modo: devsecops',
+  QA: 'modo: qa',
+  SCRUM: 'modo: scrum',
+  SRE: 'modo: sre',
+  FULL_DEV: 'modo: full-dev'
+};
+
+// Definição canônica dos eventos de barramento
+const EVENT_TYPES = {
+  EVENT_REQUIREMENTS_READY: 'EVENT_REQUIREMENTS_READY',
+  EVENT_DESIGN_READY: 'EVENT_DESIGN_READY',
+  EVENT_UI_REVIEW: 'EVENT_UI_REVIEW',
+  EVENT_CODE_COMPLETE: 'EVENT_CODE_COMPLETE',
+  EVENT_REVIEW_FAILED: 'EVENT_REVIEW_FAILED',
+  EVENT_REVIEW_PASSED: 'EVENT_REVIEW_PASSED',
+  EVENT_METRIC_ANOMALY: 'EVENT_METRIC_ANOMALY',
+  EVENT_REFACTOR_PROPOSAL: 'EVENT_REFACTOR_PROPOSAL',
+  EVENT_AGENT_SELF_IMPROVE: 'EVENT_AGENT_SELF_IMPROVE',
+  EVENT_KANBAN_DISPATCH: 'EVENT_KANBAN_DISPATCH'
+};
+
+class MultiAgentOrchestrator {
+  constructor() {
+    this.history = [];
+    this.subscribers = new Map();
+    this._setupDefaultRoutes();
+  }
+
+  _setupDefaultRoutes() {
+    // Rota 0A: EVENT_REQUIREMENTS_READY (Orchestrator/Scrum -> UIUX)
+    this.on(EVENT_TYPES.EVENT_REQUIREMENTS_READY, (payload) => {
+      return {
+        handoffTo: AGENT_PERSONAS.UIUX,
+        status: 'READY_FOR_DESIGN',
+        reason: 'Requisitos funcionais homologados; necessário design visual e acessibilidade.',
+        nextAction: 'UIUX elabora jornada, tokens e especificações WCAG 2.1 AA.',
+        requiresFix: false
+      };
+    });
+
+    // Rota 0B: EVENT_DESIGN_READY (UIUX -> DevSecOps)
+    this.on(EVENT_TYPES.EVENT_DESIGN_READY, (payload) => {
+      return {
+        handoffTo: AGENT_PERSONAS.DEVSECOPS,
+        status: 'READY_FOR_IMPLEMENTATION',
+        reason: 'Especificações visuais, design tokens e estados de componentes concluídos.',
+        nextAction: 'DevSecOps implementa código semântico aderente aos tokens e contratos.',
+        requiresFix: false
+      };
+    });
+
+    // Rota 0C: EVENT_UI_REVIEW (QA -> UIUX)
+    this.on(EVENT_TYPES.EVENT_UI_REVIEW, (payload) => {
+      const a11yPassed = payload.a11yPassed !== false;
+      return {
+        handoffTo: AGENT_PERSONAS.UIUX,
+        status: a11yPassed ? 'A11Y_APPROVED' : 'A11Y_REJECTED',
+        reason: a11yPassed ? 'Auditoria de acessibilidade WCAG aprovada.' : 'Violação de contraste ou semântica ARIA detectada.',
+        nextAction: a11yPassed ? 'Tokens e componentes homologados.' : 'UIUX deve reajustar contraste e hierarquia visual.',
+        requiresFix: !a11yPassed
+      };
+    });
+
+    // Rota 1: EVENT_CODE_COMPLETE (DevSecOps -> QA)
+    this.on(EVENT_TYPES.EVENT_CODE_COMPLETE, (payload) => {
+      const codeOrDiff = payload.diff || payload.code || '';
+      const hasTests = codeOrDiff.includes('test') || payload.testsPassing === true;
+      const hasSecrets = SECURITY_RULES.some(r => r.cwe === 'CWE-798' && r.pattern.test(codeOrDiff));
+
+      if (hasSecrets) {
+        return {
+          handoffTo: AGENT_PERSONAS.QA,
+          status: 'REJECTED',
+          reason: 'Credencial ou segredo em texto plano detectado no diff (Regra 5).',
+          nextAction: 'QA emite veto e exige expurgo imediato.',
+          requiresFix: true
+        };
+      }
+
+      if (!hasTests) {
+        return {
+          handoffTo: AGENT_PERSONAS.QA,
+          status: 'REJECTED',
+          reason: 'Entrega de código sem testes automatizados comprovados (Regra 4).',
+          nextAction: 'QA exige inclusão de testes unitários antes de qualquer aprovação.',
+          requiresFix: true
+        };
+      }
+
+      return {
+        handoffTo: AGENT_PERSONAS.QA,
+        status: 'READY_FOR_INSPECTION',
+        reason: 'Código submetido à auditoria cética adversária.',
+        nextAction: 'QA realiza análise de segurança AST e casos de borda.',
+        requiresFix: false
+      };
+    });
+
+    // Rota 2: EVENT_REVIEW_FAILED (QA -> DevSecOps)
+    this.on(EVENT_TYPES.EVENT_REVIEW_FAILED, (payload) => {
+      return {
+        handoffTo: AGENT_PERSONAS.DEVSECOPS,
+        status: 'CORRECTION_REQUIRED',
+        reason: payload.finding || 'Falha apontada pela auditoria adversária.',
+        nextAction: 'DevSecOps deve sanar a causa raiz sem contornar testes ou lint.',
+        requiresFix: true
+      };
+    });
+
+    // Rota 3: EVENT_REVIEW_PASSED (QA -> Orchestrator / CI)
+    this.on(EVENT_TYPES.EVENT_REVIEW_PASSED, (payload) => {
+      return {
+        handoffTo: AGENT_PERSONAS.ORCHESTRATOR,
+        status: 'APPROVED',
+        reason: 'Auditoria cética concluída com 100% de conformidade.',
+        nextAction: 'Liberar Pull Request, validar esteira de CI e efetuar Tríplice Registro.',
+        requiresFix: false
+      };
+    });
+
+    // Rota 4: EVENT_METRIC_ANOMALY (SRE -> Scrum & SRE)
+    this.on(EVENT_TYPES.EVENT_METRIC_ANOMALY, (payload) => {
+      const metric = payload.metric || 'unknown';
+      const value = payload.value || 0;
+      const threshold = payload.threshold || 0;
+
+      return {
+        handoffTo: AGENT_PERSONAS.SCRUM,
+        status: 'ANOMALY_TRIGGERED',
+        reason: `Métrica ${metric} atingiu ${value} (limiar: ${threshold}).`,
+        nextAction: 'Disparar playbook de auto-remediação SRE e iniciar investigação Ishikawa/PDCA.',
+        remediation: payload.recommendedPlaybook || 'PLAYBOOK_CIRCUIT_BREAKER_LLM.md'
+      };
+    });
+
+    // Rota 5: EVENT_REFACTOR_PROPOSAL (Scrum/DevSecOps -> QA Shift-Left Gate -> Backlog)
+    this.on(EVENT_TYPES.EVENT_REFACTOR_PROPOSAL, (payload) => {
+      const isAligned = payload.contextAligned !== false;
+      const isQaApproved = payload.qaApproved !== false;
+      const isOffDomain = payload.isOffDomain === true;
+      const isRedundant = payload.isRedundant === true;
+
+      if (!isAligned || !isQaApproved || isOffDomain || isRedundant) {
+        return {
+          handoffTo: AGENT_PERSONAS.QA,
+          status: 'REJECTED_SANITY_FILTER',
+          reason: 'Veto do Quality Architect (Regra 14 / Shift-Left Gate): proposta fora de domínio, overengineering ou arquivos redundantes.',
+          nextAction: 'Ideia descartada para evitar inchaço do repositório e preservar foco no produto real.',
+          ideaId: payload.ideaId || 'I-REJECTED',
+          requiresFix: true
+        };
+      }
+
+      return {
+        handoffTo: AGENT_PERSONAS.DEVSECOPS,
+        status: 'QUEUED',
+        reason: 'Proposta de melhoria homologada pelo Quality Architect em conformidade com a Regra 14.',
+        nextAction: 'Cadastrar card no backlog e criar branch dedicada.',
+        ideaId: payload.ideaId || 'I-NEW',
+        requiresFix: false
+      };
+    });
+
+    // Rota 6: EVENT_AGENT_SELF_IMPROVE (Suíte Completa -> QA Auditoria Empírica -> Orchestrator)
+    this.on(EVENT_TYPES.EVENT_AGENT_SELF_IMPROVE, (payload) => {
+      const evalPassed = payload.evalPassed !== false;
+      if (!evalPassed) {
+        return {
+          handoffTo: AGENT_PERSONAS.QA,
+          status: 'SELF_IMPROVE_REJECTED',
+          reason: 'Veto de Auditoria Empírica de QA: auto-evolução reflexiva reprovada por falta de evidência empírica mensurável.',
+          nextAction: 'Descartar hipótese para prevenir alucinação cumulativa de regras.',
+          requiresFix: true
+        };
+      }
+
+      return {
+        handoffTo: AGENT_PERSONAS.ORCHESTRATOR,
+        status: 'REFLEXIVE_LOGGED',
+        reason: 'Ciclo de auto-evolução reflexiva validado pelo Quality Architect com evidência empírica.',
+        nextAction: 'Registrar hipótese validada de domínio em IDEAS.md.',
+        tokenBudget: payload.tokenBudget || 'Under 1500 tokens',
+        requiresFix: false
+      };
+    });
+
+    // Rota 7: EVENT_KANBAN_DISPATCH (Full Dev continuous loop)
+    this.on(EVENT_TYPES.EVENT_KANBAN_DISPATCH, (payload) => {
+      const { processFullDevPipeline } = require('./jira_manager.js');
+      const pipeline = processFullDevPipeline(payload.tasks || [], payload.projectContext || {});
+      return {
+        handoffTo: AGENT_PERSONAS.FULL_DEV,
+        status: pipeline.activeTask ? 'RESUME_IN_PROGRESS' : (pipeline.nextApprovedTask ? 'START_NEXT_TASK' : 'IDLE_TODO_EMPTY'),
+        reason: pipeline.activeTask ? 'Concluir tarefa atualmente em andamento antes de avançar.' : (pipeline.nextApprovedTask ? 'Ideia aprovada pelo filtro de sanidade (Regra 14).' : 'Nenhuma tarefa pendente viável em A fazer.'),
+        nextAction: pipeline.lifecyclePlan[0] ? pipeline.lifecyclePlan[0].message : 'Aguardar novas demandas.',
+        pipeline
+      };
+    });
+  }
+
+  on(eventType, handler) {
+    this.subscribers.set(eventType, handler);
+  }
+
+  dispatch(eventType, payload = {}) {
+    if (!EVENT_TYPES[eventType]) {
+      throw new Error(`Evento desconhecido: ${eventType}. Eventos suportados: ${Object.keys(EVENT_TYPES).join(', ')}`);
+    }
+
+    const handler = this.subscribers.get(eventType);
+    const result = handler ? handler(payload) : { status: 'NO_HANDLER' };
+
+    const eventRecord = {
+      eventId: `EVT-${Date.now()}-${Math.floor(Math.random() * 1000)}`,
+      eventType,
+      timestamp: new Date().toISOString(),
+      payload,
+      result
+    };
+
+    this.history.push(eventRecord);
+    return eventRecord;
+  }
+
+    processKanbanPipeline(tasks = [], projectContext = {}) {
+    const { processFullDevPipeline } = require('./jira_manager.js');
+    return processFullDevPipeline(tasks, projectContext);
+  }
+
+  getHistory() {
+    return [...this.history];
+  }
+
+  clearHistory() {
+    this.history = [];
+  }
+}
+
+module.exports = {
+  MultiAgentOrchestrator,
+  AGENT_PERSONAS,
+  EVENT_TYPES
+};

package/scripts/otel_tracer.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * scripts/otel_tracer.js
+ * 
+ * Tracer Distribuído OpenTelemetry Nativo (AGDEV-24 / I-8).
+ * Suporte a W3C TraceContext (traceparent), hierarquia de spans (parent-child),
+ * exportação OTLP JSON e renderização de flamegraphs para playbooks de SRE.
+ */
+
+const crypto = require('crypto');
+
+function generateTraceId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function generateSpanId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+function formatTraceparent(traceId, spanId, sampled = true) {
+  const flags = sampled ? '01' : '00';
+  return `00-${traceId}-${spanId}-${flags}`;
+}
+
+function parseTraceparent(traceparent) {
+  if (!traceparent || typeof traceparent !== 'string') return null;
+  const parts = traceparent.split('-');
+  if (parts.length !== 4) return null;
+  return {
+    version: parts[0],
+    traceId: parts[1],
+    spanId: parts[2],
+    flags: parts[3],
+    sampled: parts[3] === '01'
+  };
+}
+
+class Span {
+  constructor(name, tracer, options = {}) {
+    this.name = name;
+    this.tracer = tracer;
+    this.traceId = options.traceId || tracer.traceId;
+    this.spanId = generateSpanId();
+    this.parentSpanId = options.parentSpanId || null;
+    this.startTime = options.startTime || Date.now();
+    this.endTime = null;
+    this.durationMs = 0;
+    this.attributes = Object.assign({}, options.attributes || {});
+    this.events = [];
+    this.status = { code: 'UNSET' };
+  }
+
+  setAttribute(key, value) {
+    this.attributes[key] = value;
+    return this;
+  }
+
+  addEvent(name, attributes = {}) {
+    this.events.push({
+      name,
+      time: Date.now(),
+      attributes
+    });
+    return this;
+  }
+
+  setStatus(code, message = '') {
+    this.status = { code, message };
+    return this;
+  }
+
+  end(endTime = Date.now()) {
+    this.endTime = endTime;
+    this.durationMs = Math.max(0, this.endTime - this.startTime);
+    this.tracer._recordSpan(this);
+    return this;
+  }
+}
+
+class Tracer {
+  constructor(serviceName, options = {}) {
+    this.serviceName = serviceName;
+    this.traceId = options.traceId || generateTraceId();
+    this.spans = [];
+  }
+
+  startSpan(name, options = {}) {
+    return new Span(name, this, options);
+  }
+
+  _recordSpan(span) {
+    this.spans.push(span);
+  }
+
+  getTraceContext(activeSpan = null) {
+    const spanId = activeSpan ? activeSpan.spanId : (this.spans[0] ? this.spans[0].spanId : generateSpanId());
+    return {
+      traceId: this.traceId,
+      spanId,
+      traceparent: formatTraceparent(this.traceId, spanId)
+    };
+  }
+
+  analyzeBottlenecks(thresholdMs = 50) {
+    const bottlenecks = [];
+    const totalDuration = this.spans.reduce((max, s) => Math.max(max, (s.endTime || s.startTime) - this.spans[0].startTime), 0) || 1;
+
+    for (const span of this.spans) {
+      const percentage = Math.round((span.durationMs / totalDuration) * 100);
+      if (span.durationMs >= thresholdMs || percentage >= 40) {
+        bottlenecks.push({
+          name: span.name,
+          durationMs: span.durationMs,
+          percentageTotal: percentage,
+          severity: percentage >= 70 ? 'CRÍTICA' : (percentage >= 40 ? 'ALTA' : 'MÉDIA'),
+          spanId: span.spanId
+        });
+      }
+    }
+
+    return bottlenecks;
+  }
+
+  renderFlamegraphAscii() {
+    if (this.spans.length === 0) return 'Trace vazio.';
+
+    const sorted = [...this.spans].sort((a, b) => a.startTime - b.startTime);
+    const traceStart = sorted[0].startTime;
+    const traceEnd = Math.max(...sorted.map(s => s.endTime || s.startTime));
+    const totalDuration = Math.max(1, traceEnd - traceStart);
+
+    let ascii = `=== FLAMEGRAPH DISTRIBUÍDO [Trace: ${this.traceId}] (${totalDuration}ms) ===\n`;
+
+    sorted.forEach((span, index) => {
+      const offsetMs = span.startTime - traceStart;
+      const offsetChars = Math.floor((offsetMs / totalDuration) * 30);
+      const barLength = Math.max(1, Math.floor((span.durationMs / totalDuration) * 40));
+      const indent = ' '.repeat(offsetChars);
+      const bar = '█'.repeat(barLength);
+
+      ascii += `[${String(index + 1).padStart(2, '0')}] ${indent}${bar} ${span.name} (${span.durationMs}ms)\n`;
+    });
+
+    return ascii;
+  }
+
+  exportOtlpJson() {
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: this.serviceName } }
+            ]
+          },
+          scopeSpans: [
+            {
+              scope: { name: 'agent-master-devsecops-tracer', version: '3.2.0' },
+              spans: this.spans.map(s => ({
+                traceId: s.traceId,
+                spanId: s.spanId,
+                parentSpanId: s.parentSpanId,
+                name: s.name,
+                startTimeUnixNano: String(s.startTime * 1000000),
+                endTimeUnixNano: String((s.endTime || s.startTime) * 1000000),
+                attributes: Object.entries(s.attributes).map(([k, v]) => ({
+                  key: k,
+                  value: { stringValue: String(v) }
+                })),
+                status: s.status
+              }))
+            }
+          ]
+        }
+      ]
+    };
+  }
+}
+
+function simulateMultiAgentTrace(serviceName = 'agent-pipeline') {
+  const tracer = new Tracer(serviceName);
+
+  // 1. Root span: Requisição do Usuário
+  const root = tracer.startSpan('user_goal_execution').setAttribute('agent.role', 'Orchestrator');
+  
+  // 2. Sub-span: Arquiteto planeja
+  const planSpan = tracer.startSpan('architect_plan', { parentSpanId: root.spanId })
+    .setAttribute('agent.role', 'Arquiteto')
+    .setAttribute('model', 'Claude 3.5 Sonnet');
+  // Simula 25ms
+  planSpan.end(planSpan.startTime + 25);
+
+  // 3. Sub-span: DevSecOps implementa
+  const devSpan = tracer.startSpan('devsecops_implementation', { parentSpanId: root.spanId })
+    .setAttribute('agent.role', 'DevSecOps Lead');
+  devSpan.end(devSpan.startTime + 60);
+
+  // 4. Sub-span: QA audita
+  const revSpan = tracer.startSpan('qa_audit', { parentSpanId: root.spanId })
+    .setAttribute('agent.role', 'QA Independente');
+  revSpan.end(revSpan.startTime + 15);
+
+  // 5. Finaliza root span
+  root.end(root.startTime + 105);
+
+  return tracer;
+}
+
+async function runCli() {
+  const tracer = simulateMultiAgentTrace();
+  console.log(tracer.renderFlamegraphAscii());
+  console.log('\nGargalos Identificados (Threshold 30ms):');
+  console.log(JSON.stringify(tracer.analyzeBottlenecks(30), null, 2));
+}
+
+if (require.main === module) {
+  runCli().catch(console.error);
+}
+
+module.exports = {
+  generateTraceId,
+  generateSpanId,
+  formatTraceparent,
+  parseTraceparent,
+  Span,
+  Tracer,
+  simulateMultiAgentTrace
+};

package/scripts/perf_benchmark.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * scripts/perf_benchmark.js
+ * 
+ * Scanner de Regressão de Performance em CI (AGDEV-25 / I-9).
+ * Executa micro-benchmarks comparativos de latência e consumo de RAM/Heap,
+ * detectando e bloqueando regressões superiores a 10% em relação ao baseline de referência.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const BASELINE_FILE = path.join(ROOT_DIR, 'benchmarks', 'baseline.json');
+
+function runBenchmark(iterations = 100) {
+  const { processMessage } = require('./mcp_server.js');
+  const { generateCompactPrompt } = require('./context_compressor.js');
+
+  const startMem = process.memoryUsage();
+  const startTime = process.hrtime.bigint();
+
+  // Benchmark 1: Processamento de JSON-RPC Initialize e Tools List
+  for (let i = 0; i < iterations; i++) {
+    processMessage({ jsonrpc: '2.0', id: i, method: 'tools/list' });
+    processMessage({ jsonrpc: '2.0', id: i, method: 'tools/call', params: { name: 'agent_full_dev_status', arguments: {} } });
+  }
+
+  // Benchmark 2: Compactação Semântica de Prompt
+  for (let i = 0; i < Math.floor(iterations / 2); i++) {
+    generateCompactPrompt();
+  }
+
+  const endTime = process.hrtime.bigint();
+  const endMem = process.memoryUsage();
+
+  const durationNs = Number(endTime - startTime);
+  const durationMs = durationNs / 1000000;
+  const avgLatencyUs = Math.round((durationNs / (iterations * 2)) / 1000);
+  const heapUsedMb = Math.round((endMem.heapUsed / (1024 * 1024)) * 100) / 100;
+  const opsPerSec = Math.round(((iterations * 2.5) / (durationMs / 1000)));
+
+  return {
+    iterations,
+    totalDurationMs: Math.round(durationMs * 100) / 100,
+    avgLatencyUs,
+    opsPerSec,
+    heapUsedMb
+  };
+}
+
+function comparePerformance(current, baseline, maxDegradationPct = 10) {
+  const latencyDeltaPct = Math.round(((current.avgLatencyUs - baseline.avgLatencyUs) / baseline.avgLatencyUs) * 100);
+  const memoryDeltaPct = Math.round(((current.heapUsedMb - baseline.heapUsedMb) / (baseline.heapUsedMb || 1)) * 100);
+
+  const hasLatencyRegression = latencyDeltaPct > maxDegradationPct;
+  const hasMemoryRegression = memoryDeltaPct > (maxDegradationPct * 2); // 20% tolerância para GC jitter
+  const passed = !hasLatencyRegression && !hasMemoryRegression;
+
+  return {
+    passed,
+    verdict: passed ? 'APROVADO' : 'REGRESSÃO_DETECTADA',
+    thresholdPct: maxDegradationPct,
+    current,
+    baseline,
+    deltas: {
+      latencyDeltaPct,
+      memoryDeltaPct
+    }
+  };
+}
+
+function formatPerfReport(comparison) {
+  let report = '================================================================================\n';
+  report += `RELATÓRIO DE PERFORMANCE & REGRESSÃO DE CI: [ ${comparison.verdict} ]\n`;
+  report += '================================================================================\n\n';
+
+  report += `Limiar Máximo de Degradação Permitido: ${comparison.thresholdPct}%\n\n`;
+
+  report += 'MÉTRICAS COMPARATIVAS:\n';
+  report += `- Latência Média por Operação: ${comparison.current.avgLatencyUs}µs (Baseline: ${comparison.baseline.avgLatencyUs}µs) -> Variação: ${comparison.deltas.latencyDeltaPct > 0 ? '+' : ''}${comparison.deltas.latencyDeltaPct}%\n`;
+  report += `- Throughput (Ops/sec): ${comparison.current.opsPerSec} ops/s (Baseline: ${comparison.baseline.opsPerSec} ops/s)\n`;
+  report += `- Memória Heap Utilizada: ${comparison.current.heapUsedMb} MB (Baseline: ${comparison.baseline.heapUsedMb} MB) -> Variação: ${comparison.deltas.memoryDeltaPct > 0 ? '+' : ''}${comparison.deltas.memoryDeltaPct}%\n\n`;
+
+  if (comparison.passed) {
+    report += 'STATUS: Nenhuma degradação crítica detectada. Aprovado para merge na esteira de CI.\n';
+  } else {
+    report += 'ALERTA SRE: Regressão superior a 10% identificada! Merge bloqueado conforme política DevSecOps.\n';
+  }
+
+  report += '================================================================================\n';
+  return report;
+}
+
+function getOrInitBaseline() {
+  const benchDir = path.dirname(BASELINE_FILE);
+  if (!fs.existsSync(benchDir)) {
+    fs.mkdirSync(benchDir, { recursive: true });
+  }
+
+  if (fs.existsSync(BASELINE_FILE)) {
+    try {
+      return JSON.parse(fs.readFileSync(BASELINE_FILE, 'utf8'));
+    } catch { /* ignora */ }
+  }
+
+  // Baseline padrão de referência calibrado para Node.js 22
+  const initialBaseline = {
+    iterations: 100,
+    totalDurationMs: 15.0,
+    avgLatencyUs: 60,
+    opsPerSec: 15000,
+    heapUsedMb: 18.5
+  };
+
+  fs.writeFileSync(BASELINE_FILE, JSON.stringify(initialBaseline, null, 2), 'utf8');
+  return initialBaseline;
+}
+
+async function runCli() {
+  const args = process.argv.slice(2);
+  const baseline = getOrInitBaseline();
+  const current = runBenchmark(100);
+
+  if (args.includes('--save-baseline')) {
+    fs.writeFileSync(BASELINE_FILE, JSON.stringify(current, null, 2), 'utf8');
+    console.log(`[Perf Scanner] Novo baseline salvo com sucesso em ${BASELINE_FILE}`);
+    return;
+  }
+
+  const comparison = comparePerformance(current, baseline, 15);
+  const report = formatPerfReport(comparison);
+  console.log(report);
+
+  if (args.includes('--strict') && !comparison.passed) {
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  runCli().catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  runBenchmark,
+  comparePerformance,
+  formatPerfReport,
+  getOrInitBaseline,
+  BASELINE_FILE
+};