agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/mcp/handlers/rules_handlers.js

@@ -0,0 +1,379 @@
+/**
+ * scripts/mcp/handlers/rules_handlers.js
+ * 
+ * Rules, Ideation & Governance MCP Handlers.
+ * Despacha chamadas JSON-RPC 2.0 para consulta aos 10 Princípios Canônicos de Engenharia,
+ * mapeamento retrocompatível de regras legadas, filtro de sanidade de backlog/ideação (Regra 14)
+ * e validação estrita da inviolabilidade de requisitos e credenciais (Regra 15).
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ROOT_DIR } = require('../resources_registry.js');
+const { createSarifReport } = require('../../core/sarif_engine.js');
+
+/**
+ * Catálogo imutável em profundidade de mapeamento das regras legadas (8 a 27)
+ * para os 10 Princípios Canônicos da versão 5.0 Enterprise.
+ */
+const LEGACY_RULES_MAP = Object.freeze({
+  14: Object.freeze({
+    principle: 7,
+    title: '14. Curadoria & Revalidação Contextual de Ideias (Ideation Sanity Check)',
+    text: 'Consolidada no Princípio 7: Onboarding Bimodal, Resiliência Offline & Sanidade Contextual. É mandatório que o Agente avalie e filtre as ideias geradas por quaisquer subagentes antes de apresentá-las ao usuário, aplicando filtro de sanidade contextual contra overengineering e desconexão de domínio.'
+  }),
+  18: Object.freeze({
+    principle: 5,
+    title: '18. Descoberta Compulsória de MCP & Proibição Estrita de Scripts Locais Descartáveis (Native Tool First Principle)',
+    text: 'Consolidada no Princípio 5: DevSecOps & Ferramentas Nativas Blindadas por Padrão. É expressamente proibido criar scripts descartáveis no repositório. Priorize ferramentas nativas MCP (agent-master-devsecops, mcp-atlassian) e ferramentas de linha de comando padrão (gh, npm, git).'
+  }),
+  22: Object.freeze({
+    principle: 3,
+    title: '22. Integridade e Renderização de Documentação Wiki (Confluence XHTML Storage Format Nativo)',
+    text: 'Consolidada no Princípio 3: Rastreabilidade Tríplice & Governança Contínua. Toda documentação sincronizada no Confluence deve utilizar formatação semântica limpa e tags estruturadas XHTML Storage Format (v2).'
+  }),
+  23: Object.freeze({
+    principle: 3,
+    title: '23. Descoberta Compulsória de Ticket Jira & Proibição Estrita de Identificadores Alucinados (Traceability Verification First Gate)',
+    text: 'Consolidada no Princípio 3 (Rastreabilidade) e Princípio 1 (Verdade Factual). É expressamente proibido supor, adivinhar ou alucinar chaves de tickets Jira sem prévia consulta determinística à API REST do Jira.'
+  }),
+  24: Object.freeze({
+    principle: 5,
+    title: '24. Auto-Auditoria Compulsória Pré-Execução & Validação por Linters Nativos (Pre-Flight Self-Compliance Gate)',
+    text: 'Consolidada no Princípio 5 (DevSecOps) e Princípio 4 (Qualidade Técnica). Antes de formular propostas de branch, commit ou PR, o agente auto-audita seu output invocando os linters nativos (git_hygiene_linter, sast_scanner, code_quality_auditor).'
+  }),
+  25: Object.freeze({
+    principle: 3,
+    title: '25. Ciclo Fechado Compulsório de Pós-Merge & Tríplice Fechamento (Post-Merge Full Lifecycle Closure Gate)',
+    text: 'Consolidada no Princípio 3: Rastreabilidade Tríplice. Uma vez mergeado o PR, executar compulsoriamente a transição no Jira para Concluído, registro de ADR no Confluence e git pull na branch main local.'
+  }),
+  26: Object.freeze({
+    principle: 3,
+    title: '26. Consolidação Canônica em Página Única no Confluence (Single-Ledger Confluence Integrity)',
+    text: 'Consolidada no Princípio 3: Rastreabilidade Tríplice. Livro-razão consolidado append-only para ADRs e governança, preservando a árvore do Confluence.'
+  }),
+  27: Object.freeze({
+    principle: 3,
+    title: '27. Rastreabilidade Visual Compulsória na Interface Web do Jira (UI-Visible Web Links Gate)',
+    text: 'Consolidada no Princípio 3: Rastreabilidade Tríplice. Vínculos de documentação Confluence devem ser transmitidos como Links da Web acessíveis diretamente na interface gráfica moderna do Jira.'
+  })
+});
+
+/**
+ * Cache em memória reativo para o conteúdo de docs/ENGINEERING_RULES.md
+ */
+let _rulesCache = null;
+let _rulesMtime = null;
+
+function getEngineeringRulesContent() {
+  const rulesPath = path.join(ROOT_DIR, 'docs', 'ENGINEERING_RULES.md');
+  if (!fs.existsSync(rulesPath)) {
+    return null;
+  }
+  try {
+    const stat = fs.statSync(rulesPath);
+    if (!_rulesCache || !_rulesMtime || stat.mtimeMs > _rulesMtime) {
+      _rulesCache = fs.readFileSync(rulesPath, 'utf8');
+      _rulesMtime = stat.mtimeMs;
+    }
+    return _rulesCache;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Helpers funcionais puros para construção determinística de respostas JSON-RPC 2.0 (DRY)
+ */
+function buildSuccessResponse(id, data) {
+  const textContent = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  return {
+    jsonrpc: '2.0',
+    id,
+    result: {
+      content: [
+        {
+          type: 'text',
+          text: textContent
+        }
+      ]
+    }
+  };
+}
+
+function buildErrorResponse(id, code, message, data = null) {
+  const errObj = { code, message };
+  if (data) errObj.data = data;
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: errObj
+  };
+}
+
+/**
+ * 1. Recupera o texto canônico de uma regra ou princípio (agent_get_rule)
+ */
+function handleGetRule(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const num = Number(safeArgs.ruleNumber);
+
+    if (isNaN(num) || num <= 0) {
+      const fallbackText = 'Número da regra não especificado. Consulte os 10 Princípios Canônicos em docs/ENGINEERING_RULES.md.';
+      return buildSuccessResponse(id, fallbackText);
+    }
+
+    const content = getEngineeringRulesContent();
+    if (!content) {
+      return buildErrorResponse(id, -32603, 'ENGINEERING_RULES.md não encontrado.');
+    }
+
+    // 1. Busca direta pelos 10 Princípios Canônicos (v5.0 Enterprise)
+    if (num >= 1 && num <= 10) {
+      const regex = new RegExp(`(?:^|\\n)\\s*${num}\\.\\s+\\*\\*(?:Princípio\\s+${num}:)?\\s*([\\s\\S]*?)(?=\\r?\\n\\s*\\d+\\.\\s+\\*\\*|\\r?\\n### |\\r?\\n## |$(?![\\r\\n]))`, 'i');
+      const match = content.match(regex);
+      if (match) {
+        if (safeArgs.format === 'sarif') {
+          const sarif = createSarifReport({
+            toolName: 'agent-master-rules-engine',
+            toolVersion: '5.1.0',
+            findings: [],
+            properties: {
+              ruleNumber: num,
+              type: 'CANONICAL_PRINCIPLE',
+              content: match[0].trim()
+            }
+          });
+          return buildSuccessResponse(id, sarif);
+        }
+        return buildSuccessResponse(id, match[0].trim());
+      }
+    }
+
+    // 2. Mapeamento retrocompatível para regras legadas (8 a 27)
+    if (LEGACY_RULES_MAP[num]) {
+      const leg = LEGACY_RULES_MAP[num];
+      const text = `[REGRA LEGADA ${num} - CONSOLIDAÇÃO CANÔNICA v5.0]\n${leg.title}\n${leg.text}\nReferência: Princípio ${leg.principle} de docs/ENGINEERING_RULES.md`;
+      if (safeArgs.format === 'sarif') {
+        const sarif = createSarifReport({
+          toolName: 'agent-master-rules-engine',
+          toolVersion: '5.1.0',
+          findings: [],
+          properties: {
+            ruleNumber: num,
+            type: 'LEGACY_RULE_MAPPED',
+            consolidatedPrinciple: leg.principle,
+            content: text
+          }
+        });
+        return buildSuccessResponse(id, sarif);
+      }
+      return buildSuccessResponse(id, text);
+    }
+
+    // 3. Fallback para busca genérica ou aviso de consolidação
+    const fallbackRegex = new RegExp(`(?:^|\\n)\\s*${num}\\.\\s+([\\s\\S]*?)(?=\\r?\\n\\s*\\d+\\.\\s+\\*\\*|\\r?\\n### |\\r?\\n## |$(?![\\r\\n]))`);
+    const match = content.match(fallbackRegex);
+    const ruleText = match
+      ? match[0].trim()
+      : `Regra ${num} consolidada na v5.0 Enterprise. Consulte os 10 Princípios Canônicos em docs/ENGINEERING_RULES.md.`;
+
+    if (safeArgs.format === 'sarif') {
+      const sarif = createSarifReport({
+        toolName: 'agent-master-rules-engine',
+        toolVersion: '5.1.0',
+        findings: [],
+        properties: {
+          ruleNumber: num,
+          type: 'GENERIC_RULE_SEARCH',
+          content: ruleText
+        }
+      });
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, ruleText);
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleGetRule: ${err.message}`);
+  }
+}
+
+/**
+ * 2. Filtro de Sanidade Contextual & Anti-Overengineering de Ideias (agent_validate_idea / Regra 14)
+ */
+function handleValidateIdea(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const ideaTitle = String(safeArgs.ideaTitle || '').trim();
+    const ideaDescription = String(safeArgs.ideaDescription || '').trim();
+    const projectStack = String(safeArgs.projectStack || '').trim();
+    const projectDomain = String(safeArgs.projectDomain || '').trim();
+    const format = safeArgs.format || 'json';
+
+    const fullIdeaText = `${ideaTitle} ${ideaDescription}`;
+    const fullContextText = `${projectStack} ${projectDomain}`;
+
+    const isOffDomain = /blockchain|crypto|metaverse|web3/i.test(fullIdeaText) && !/crypto|blockchain/i.test(projectDomain);
+    const isOverengineering = /kubernetes|kafka|microservices|distributed/i.test(fullIdeaText) && /bot|cli|pequeno|monolito|sqlite/i.test(fullContextText);
+
+    let approved = true;
+    let verdict = 'APROVADA';
+    let rationale = 'A ideia apresenta coerência arquitetural com a stack e o domínio fornecidos.';
+
+    if (isOffDomain) {
+      approved = false;
+      verdict = 'REJEITADA (Critério 1: Desconexão de Domínio)';
+      rationale = 'A proposta introduz componentes fora do propósito e regras de negócio da aplicação.';
+    } else if (isOverengineering) {
+      approved = false;
+      verdict = 'REJEITADA (Critério 2: Overengineering / Complexidade Artificial)';
+      rationale = 'A solução proposta introduz complexidade operacional desproporcional à escala do projeto.';
+    }
+
+    if (format === 'sarif') {
+      const findings = [];
+      if (!approved) {
+        findings.push({
+          ruleId: isOffDomain ? 'RULE-IDEA-001' : 'RULE-IDEA-002',
+          severity: 'HIGH',
+          filename: 'docs/IDEAS.md',
+          line: 1,
+          column: 1,
+          snippet: ideaTitle || 'Ideia sem título',
+          message: `${verdict}: ${rationale}`,
+          remediation: isOffDomain
+            ? 'Reorientar a proposta para os limites estritos do domínio do negócio.'
+            : 'Simplificar a arquitetura adotando soluções nativas e monólito modular.'
+        });
+      }
+
+      const sarif = createSarifReport({
+        toolName: 'agent-master-sanity-filter',
+        toolVersion: '5.1.0',
+        findings,
+        properties: {
+          idea: ideaTitle,
+          verdict,
+          approved,
+          rationale,
+          rule: 'Regra 14 - Ideation Sanity Filter'
+        }
+      });
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, {
+      idea: ideaTitle,
+      veredito: verdict,
+      aprovado: approved,
+      justificativa: rationale,
+      regra: 'Regra 14 - Ideation Sanity Filter'
+    });
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleValidateIdea: ${err.message}`);
+  }
+}
+
+/**
+ * 3. Validação Estrita da Inviolabilidade de Requisitos & Credenciais (agent_validate_rule15 / Regra 15)
+ */
+function handleValidateRule15(id, args) {
+  const safeArgs = args && typeof args === 'object' ? args : {};
+  const { validateRule15, auditToSarif } = require('../../integrations/credentials_guard.js');
+  try {
+    const res = validateRule15({
+      failFast: Boolean(safeArgs.failFast),
+      requireGitHub: safeArgs.requireGitHub !== false,
+      requireAtlassian: safeArgs.requireAtlassian !== false
+    });
+
+    if (safeArgs.format === 'sarif') {
+      const sarif = auditToSarif(res);
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, {
+      status: res.valid ? 'SUCCESS' : 'BLOCKED',
+      rule: 'Regra 15 - Imutabilidade de Requisitos & Validação Compulsória de Segredos',
+      valid: res.valid,
+      missing: res.missing,
+      remediation: res.remediation,
+      atlassianConfigured: res.atlassian.isConfigured,
+      githubAuthenticated: res.github.isAuthenticated
+    });
+  } catch (err) {
+    return buildErrorResponse(id, -32015, err.message, {
+      missing: err.missingRequirements || [],
+      remediation: err.remediationSteps || []
+    });
+  }
+}
+
+/**
+ * Classe Canônica RulesHandlers
+ * Fornece API orientada a objetos com suporte a métodos estáticos e de instância.
+ */
+class RulesHandlers {
+  static get LEGACY_RULES() {
+    return LEGACY_RULES_MAP;
+  }
+
+  static buildSuccessResponse(id, data) {
+    return buildSuccessResponse(id, data);
+  }
+
+  static buildErrorResponse(id, code, message, data = null) {
+    return buildErrorResponse(id, code, message, data);
+  }
+
+  static handleGetRule(id, args) {
+    return handleGetRule(id, args);
+  }
+
+  static handleValidateIdea(id, args) {
+    return handleValidateIdea(id, args);
+  }
+
+  static handleValidateRule15(id, args) {
+    return handleValidateRule15(id, args);
+  }
+
+  get LEGACY_RULES() {
+    return RulesHandlers.LEGACY_RULES;
+  }
+
+  buildSuccessResponse(id, data) {
+    return RulesHandlers.buildSuccessResponse(id, data);
+  }
+
+  buildErrorResponse(id, code, message, data = null) {
+    return RulesHandlers.buildErrorResponse(id, code, message, data);
+  }
+
+  handleGetRule(id, args) {
+    return RulesHandlers.handleGetRule(id, args);
+  }
+
+  handleValidateIdea(id, args) {
+    return RulesHandlers.handleValidateIdea(id, args);
+  }
+
+  handleValidateRule15(id, args) {
+    return RulesHandlers.handleValidateRule15(id, args);
+  }
+}
+
+module.exports = {
+  RulesHandlers,
+  LEGACY_RULES_MAP,
+  buildSuccessResponse,
+  buildErrorResponse,
+  handleGetRule,
+  handleValidateIdea,
+  handleValidateRule15
+};

package/scripts/mcp/handlers/scaffold_handlers.js

@@ -0,0 +1,334 @@
+/**
+ * scripts/mcp/handlers/scaffold_handlers.js
+ * 
+ * Scaffold, AST & Code Generation MCP Handlers.
+ * Despacha chamadas JSON-RPC 2.0 para geração atômica de features (Fast-Path / Princípio 7),
+ * extração de esqueletos AST (ast_skeletonizer), compressão de contexto LLM (context_compressor),
+ * empacotamento universal de personas (universal_packager), bootstrap de ambientes IDE
+ * e exportação de Magic Prompts.
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const path = require('node:path');
+const { ROOT_DIR } = require('../resources_registry.js');
+const { createSarifReport } = require('../../core/sarif_engine.js');
+
+/**
+ * Helpers funcionais puros para construção determinística de respostas JSON-RPC 2.0 (DRY)
+ */
+function buildSuccessResponse(id, data) {
+  const textContent = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  return {
+    jsonrpc: '2.0',
+    id,
+    result: {
+      content: [
+        {
+          type: 'text',
+          text: textContent
+        }
+      ]
+    }
+  };
+}
+
+function buildErrorResponse(id, code, message, data = null) {
+  const errObj = { code, message };
+  if (data) errObj.data = data;
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: errObj
+  };
+}
+
+/**
+ * 1. Geração de Manifestos e Configurações de IDE (agent_generate_ide_plugins)
+ */
+function handleGenerateIdePlugins(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { generateIdeConfigs } = require('../../core/universal_packager.js');
+    const target = safeArgs.target || 'all';
+    const targetDir = safeArgs.targetDir || ROOT_DIR;
+    const generated = generateIdeConfigs(targetDir, { target, dryRun: Boolean(safeArgs.dryRun) });
+
+    return buildSuccessResponse(id, {
+      status: 'SUCCESS',
+      generatedFiles: generated,
+      target,
+      targetDir
+    });
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleGenerateIdePlugins: ${err.message}`);
+  }
+}
+
+/**
+ * 2. Compressão de Contexto e Estimativa de Tokens (agent_compress_context)
+ */
+function handleCompressContext(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { generateCompactPrompt, compressCustomText, estimateTokens } = require('../../core/context_compressor.js');
+    const customText = safeArgs.text;
+    const maxTokens = Number(safeArgs.maxTokens) || 1500;
+
+    let compressedText = '';
+    if (customText) {
+      compressedText = compressCustomText(customText, maxTokens);
+    } else {
+      compressedText = generateCompactPrompt();
+    }
+
+    const tokenCount = estimateTokens(compressedText);
+    return buildSuccessResponse(id, {
+      status: 'SUCCESS',
+      tokensEstimados: tokenCount,
+      limiteTokens: maxTokens,
+      dentroDoOrcamento: tokenCount <= maxTokens,
+      tamanhoCaracteres: compressedText.length,
+      textoCompactado: compressedText
+    });
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleCompressContext: ${err.message}`);
+  }
+}
+
+/**
+ * 3. Exportação de Bundles Universais para LLMs/Plataformas (agent_export_universal_bundle)
+ */
+function handleExportUniversalBundle(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { UniversalPackager } = require('../../core/universal_packager.js');
+    const packager = new UniversalPackager();
+    const platform = safeArgs.platform || 'all';
+    const targetDir = safeArgs.targetDir || path.join(ROOT_DIR, 'dist', 'bundles', platform);
+    const dryRun = safeArgs.dryRun;
+
+    const result = packager.exportProfile(platform, targetDir, { dryRun });
+
+    return buildSuccessResponse(id, {
+      status: 'SUCCESS',
+      exportResult: result
+    });
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleExportUniversalBundle: ${err.message}`);
+  }
+}
+
+/**
+ * 4. Bootstrap de Ambiente e Provisionamento de Arquivos Canônicos (agent_bootstrap_environment)
+ */
+function handleBootstrapEnvironment(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { bootstrapEnvironment } = require('../../bin/bootstrap_cli.js');
+    const targetDir = safeArgs.targetDir || ROOT_DIR;
+    const dryRun = safeArgs.dryRun;
+    const platforms = safeArgs.platforms;
+
+    const result = bootstrapEnvironment(targetDir, { dryRun, platforms });
+
+    if (safeArgs.format === 'sarif') {
+      const sarif = createSarifReport({
+        toolName: 'agent-master-bootstrap-cli',
+        toolVersion: '5.1.0',
+        findings: [],
+        properties: {
+          status: result.status,
+          dryRun: result.dryRun,
+          configuredPlatforms: result.configuredPlatforms,
+          copiedFilesCount: (result.copiedFiles && result.copiedFiles.length) || 0
+        }
+      });
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, result);
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleBootstrapEnvironment: ${err.message}`);
+  }
+}
+
+/**
+ * 5. Geração de Magic Prompt e Bookmarklet (agent_generate_magic_prompt)
+ */
+function handleGenerateMagicPrompt(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { MagicPromptGenerator } = require('../../core/magic_prompt_generator.js');
+    const generator = new MagicPromptGenerator(ROOT_DIR);
+    const targetDir = safeArgs.targetDir || path.join(ROOT_DIR, 'dist', 'magic_prompt');
+    const dryRun = safeArgs.dryRun;
+
+    const result = generator.exportArtifacts(targetDir, { dryRun });
+
+    return buildSuccessResponse(id, result);
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleGenerateMagicPrompt: ${err.message}`);
+  }
+}
+
+/**
+ * 6. Esqueletização AST de Código-Fonte (agent_extract_code_skeleton)
+ */
+function handleExtractCodeSkeleton(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { extractCodeSkeleton } = require('../../core/ast_skeletonizer.js');
+    const code = String(safeArgs.code || '');
+    const language = String(safeArgs.language || 'javascript');
+    const result = extractCodeSkeleton(code, language);
+
+    if (safeArgs.format === 'sarif') {
+      const sarif = createSarifReport({
+        toolName: 'agent-master-ast-skeletonizer',
+        toolVersion: '5.1.0',
+        findings: [],
+        properties: {
+          language,
+          tokenEconomyPercent: result.tokenEconomyPercent || 0,
+          originalTokens: result.originalTokens || 0,
+          skeletonTokens: result.skeletonTokens || 0,
+          skeletonCode: result.skeletonCode
+        }
+      });
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, result);
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleExtractCodeSkeleton: ${err.message}`);
+  }
+}
+
+/**
+ * 7. Scaffolding Atômico Rápido de Features (agent_scaffold_feature / Fast-Path)
+ */
+function handleScaffoldFeature(id, args) {
+  try {
+    const safeArgs = args && typeof args === 'object' ? args : {};
+    const { scaffoldFeatureFast } = require('../../core/fast_feature_scaffold.js');
+    const targetDir = safeArgs.targetDir ? path.resolve(safeArgs.targetDir) : process.cwd();
+    const result = scaffoldFeatureFast(safeArgs, {
+      rootDir: targetDir,
+      writeToDisk: Boolean(safeArgs.writeToDisk)
+    });
+
+    if (safeArgs.format === 'sarif') {
+      const sarif = createSarifReport({
+        toolName: 'agent-master-fast-feature-scaffold',
+        toolVersion: '5.1.0',
+        findings: [],
+        properties: {
+          status: result.status,
+          featureName: result.featureName,
+          stack: result.stack,
+          filesGeneratedCount: result.filesGeneratedCount,
+          executionTimeMs: result.executionTimeMs
+        }
+      });
+      return buildSuccessResponse(id, sarif);
+    }
+
+    return buildSuccessResponse(id, result);
+  } catch (err) {
+    return buildErrorResponse(id, -32603, `Falha em handleScaffoldFeature: ${err.message}`);
+  }
+}
+
+/**
+ * Classe Canônica ScaffoldHandlers
+ * Fornece API orientada a objetos com suporte a métodos estáticos e de instância.
+ */
+class ScaffoldHandlers {
+  static buildSuccessResponse(id, data) {
+    return buildSuccessResponse(id, data);
+  }
+
+  static buildErrorResponse(id, code, message, data = null) {
+    return buildErrorResponse(id, code, message, data);
+  }
+
+  static handleGenerateIdePlugins(id, args) {
+    return handleGenerateIdePlugins(id, args);
+  }
+
+  static handleCompressContext(id, args) {
+    return handleCompressContext(id, args);
+  }
+
+  static handleExportUniversalBundle(id, args) {
+    return handleExportUniversalBundle(id, args);
+  }
+
+  static handleBootstrapEnvironment(id, args) {
+    return handleBootstrapEnvironment(id, args);
+  }
+
+  static handleGenerateMagicPrompt(id, args) {
+    return handleGenerateMagicPrompt(id, args);
+  }
+
+  static handleExtractCodeSkeleton(id, args) {
+    return handleExtractCodeSkeleton(id, args);
+  }
+
+  static handleScaffoldFeature(id, args) {
+    return handleScaffoldFeature(id, args);
+  }
+
+  buildSuccessResponse(id, data) {
+    return ScaffoldHandlers.buildSuccessResponse(id, data);
+  }
+
+  buildErrorResponse(id, code, message, data = null) {
+    return ScaffoldHandlers.buildErrorResponse(id, code, message, data);
+  }
+
+  handleGenerateIdePlugins(id, args) {
+    return ScaffoldHandlers.handleGenerateIdePlugins(id, args);
+  }
+
+  handleCompressContext(id, args) {
+    return ScaffoldHandlers.handleCompressContext(id, args);
+  }
+
+  handleExportUniversalBundle(id, args) {
+    return ScaffoldHandlers.handleExportUniversalBundle(id, args);
+  }
+
+  handleBootstrapEnvironment(id, args) {
+    return ScaffoldHandlers.handleBootstrapEnvironment(id, args);
+  }
+
+  handleGenerateMagicPrompt(id, args) {
+    return ScaffoldHandlers.handleGenerateMagicPrompt(id, args);
+  }
+
+  handleExtractCodeSkeleton(id, args) {
+    return ScaffoldHandlers.handleExtractCodeSkeleton(id, args);
+  }
+
+  handleScaffoldFeature(id, args) {
+    return ScaffoldHandlers.handleScaffoldFeature(id, args);
+  }
+}
+
+module.exports = {
+  ScaffoldHandlers,
+  buildSuccessResponse,
+  buildErrorResponse,
+  handleGenerateIdePlugins,
+  handleCompressContext,
+  handleExportUniversalBundle,
+  handleBootstrapEnvironment,
+  handleGenerateMagicPrompt,
+  handleExtractCodeSkeleton,
+  handleScaffoldFeature
+};