agent-master-devsecops 0.0.0-stage → 5.1.0

package/scripts/mcp/tool_handlers.js

@@ -0,0 +1,444 @@
+/**
+ * scripts/mcp/tool_handlers.js
+ * 
+ * Unified Tool Handlers Dispatcher — Roteador Canônico O(1) de Ferramentas MCP.
+ * Suporta execução síncrona e assíncrona não-bloqueante via tabela determinística,
+ * fábrica funcional pura para as 5 meta-ferramentas consolidadas (Perfil Lean/Consolidated),
+ * blindagem defensiva try/catch e auditoria oficial no padrão OASIS SARIF v2.1.0.
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+// 1. Handlers de Regras e Governança
+const {
+  handleGetRule,
+  handleValidateIdea,
+  handleValidateRule15
+} = require('./handlers/rules_handlers.js');
+
+// 2. Handlers de QA, Segurança e Auditoria
+const {
+  handleAuditCode,
+  handleReviewPr,
+  handleSastScan,
+  handleAuditQuality,
+  handleAuditA11y,
+  handleLintGitHygiene,
+  handleAuditDependenciesSca,
+  handleValidateApiContract,
+  handleEvalHarness,
+  handleRemediateCode
+} = require('./handlers/qa_handlers.js');
+
+// 3. Handlers da Tríade Atlassian & Pipeline Kanban
+const {
+  handleSyncAtlassian,
+  handleCheckCredentials,
+  handleConfigureCredentials,
+  handleStandardizeKanban,
+  handleFullDevPipeline
+} = require('./handlers/atlassian_handlers.js');
+
+// 4. Handlers de SRE, Observabilidade e Resiliência
+const {
+  handleOtelTrace,
+  handlePerfBenchmark,
+  handleCircuitBreaker,
+  handleSreTelemetry,
+  handleSreRemediate
+} = require('./handlers/sre_handlers.js');
+
+// 5. Handlers de Scaffolding, Contexto e Empacotamento
+const {
+  handleGenerateIdePlugins,
+  handleCompressContext,
+  handleExportUniversalBundle,
+  handleBootstrapEnvironment,
+  handleGenerateMagicPrompt,
+  handleExtractCodeSkeleton,
+  handleScaffoldFeature
+} = require('./handlers/scaffold_handlers.js');
+
+// 6. Handlers de Core, Orquestração e Inteligência Arquitetural
+const {
+  handleFullDevStatus,
+  handleOrchestrateEvent,
+  handleInspectorInfo,
+  handleSmartOnboarding,
+  handleVerifyTriadGate,
+  handleSetMcpProfile,
+  handleMineDomainIdeas,
+  handleRecommendArchitecture,
+  handleGroundKnowledge
+} = require('./handlers/core_handlers.js');
+
+/**
+ * Normaliza e mescla argumentos planos ou aninhados dentro de { payload: { ... } } (DRY)
+ */
+function extractPayload(args) {
+  if (!args || typeof args !== 'object') return {};
+  if (args.payload && typeof args.payload === 'object' && !Array.isArray(args.payload)) {
+    return { ...args, ...args.payload };
+  }
+  return { ...args };
+}
+
+/**
+ * Fábrica funcional pura para criação determinística de meta-ferramentas consolidadas (DRY total)
+ */
+function createMetaToolHandler(metaToolName, actionMap, options = {}) {
+  const validActions = Object.keys(actionMap);
+  const validActionsList = validActions.join(', ');
+
+  return function metaHandler(id, args) {
+    const cleanArgs = extractPayload(args);
+    let action = cleanArgs.action;
+
+    if (!action && options.defaultAction) {
+      action = options.defaultAction;
+    }
+
+    if (typeof options.normalizeArgs === 'function') {
+      options.normalizeArgs(cleanArgs);
+    }
+
+    const handler = actionMap[action];
+    if (typeof handler === 'function') {
+      return handler(id, cleanArgs);
+    }
+
+    return {
+      jsonrpc: '2.0',
+      id: id !== undefined ? id : null,
+      error: {
+        code: -32602,
+        message: `Ação inválida para ${metaToolName}: '${action}'. Ações válidas: ${validActionsList}.`
+      }
+    };
+  };
+}
+
+// 1. Meta-Ferramenta: agent_governance
+const handleAgentGovernance = createMetaToolHandler('agent_governance', {
+  get_rule: handleGetRule,
+  validate_idea: handleValidateIdea,
+  validate_rule15: handleValidateRule15,
+  smart_onboarding: handleSmartOnboarding,
+  verify_triad_gate: handleVerifyTriadGate,
+  check_credentials: handleCheckCredentials,
+  configure_credentials: handleConfigureCredentials,
+  set_profile: handleSetMcpProfile,
+  eval_harness: handleEvalHarness,
+  mine_domain_ideas: handleMineDomainIdeas,
+  recommend_architecture: handleRecommendArchitecture,
+  ground_knowledge: handleGroundKnowledge
+});
+
+// 2. Meta-Ferramenta: agent_audit
+const handleAgentAudit = createMetaToolHandler('agent_audit', {
+  audit_code: handleAuditCode,
+  sast_scan: handleSastScan,
+  audit_quality: handleAuditQuality,
+  audit_dependencies_sca: handleAuditDependenciesSca,
+  validate_api_contract: handleValidateApiContract,
+  lint_git_hygiene: handleLintGitHygiene,
+  audit_a11y: handleAuditA11y,
+  remediate_code: handleRemediateCode
+}, {
+  normalizeArgs: (args) => {
+    if (args.codeContent && !args.code) {
+      args.code = args.codeContent;
+    }
+  }
+});
+
+// 3. Meta-Ferramenta: agent_review
+const handleAgentReview = createMetaToolHandler('agent_review', {
+  review_pr: handleReviewPr,
+  qa_gate: handleAuditCode
+}, {
+  defaultAction: 'review_pr',
+  normalizeArgs: (args) => {
+    if (args.codeDiff && !args.diff) {
+      args.diff = args.codeDiff;
+    }
+  }
+});
+
+// 4. Meta-Ferramenta: agent_pipeline
+const handleAgentPipeline = createMetaToolHandler('agent_pipeline', {
+  sync_atlassian: handleSyncAtlassian,
+  standardize_kanban: handleStandardizeKanban,
+  full_dev_pipeline: handleFullDevPipeline,
+  full_dev_status: (id) => handleFullDevStatus(id),
+  scaffold_feature: handleScaffoldFeature,
+  extract_code_skeleton: handleExtractCodeSkeleton,
+  export_universal_bundle: handleExportUniversalBundle,
+  compress_context: handleCompressContext,
+  generate_ide_plugins: handleGenerateIdePlugins,
+  bootstrap_environment: handleBootstrapEnvironment,
+  generate_magic_prompt: handleGenerateMagicPrompt
+});
+
+// 5. Meta-Ferramenta: agent_telemetry
+const handleAgentTelemetry = createMetaToolHandler('agent_telemetry', {
+  sre_telemetry: handleSreTelemetry,
+  sre_remediate: handleSreRemediate,
+  otel_trace: handleOtelTrace,
+  perf_benchmark: handlePerfBenchmark,
+  circuit_breaker: handleCircuitBreaker,
+  orchestrate_event: handleOrchestrateEvent,
+  inspector_info: handleInspectorInfo
+});
+
+/**
+ * Tabela mestre de despacho O(1) de ferramentas MCP (imutável)
+ */
+const TOOL_DISPATCH_TABLE = Object.freeze({
+  agent_get_rule: handleGetRule,
+  agent_recommend_architecture: handleRecommendArchitecture,
+  agent_ground_knowledge: handleGroundKnowledge,
+  agent_validate_idea: handleValidateIdea,
+  agent_validate_rule15: handleValidateRule15,
+  agent_audit_code: handleAuditCode,
+  agent_review_pr: handleReviewPr,
+  agent_sast_scan: handleSastScan,
+  agent_audit_quality: handleAuditQuality,
+  agent_audit_a11y: handleAuditA11y,
+  agent_lint_git_hygiene: handleLintGitHygiene,
+  agent_audit_dependencies_sca: handleAuditDependenciesSca,
+  agent_validate_api_contract: handleValidateApiContract,
+  agent_remediate_code: handleRemediateCode,
+  agent_eval_harness: handleEvalHarness,
+  agent_sync_atlassian: handleSyncAtlassian,
+  agent_check_credentials: handleCheckCredentials,
+  agent_configure_credentials: handleConfigureCredentials,
+  agent_standardize_kanban: handleStandardizeKanban,
+  agent_full_dev_pipeline: handleFullDevPipeline,
+  agent_otel_trace: handleOtelTrace,
+  agent_perf_benchmark: handlePerfBenchmark,
+  agent_circuit_breaker: handleCircuitBreaker,
+  agent_sre_telemetry: handleSreTelemetry,
+  agent_sre_remediate: handleSreRemediate,
+  agent_generate_ide_plugins: handleGenerateIdePlugins,
+  agent_compress_context: handleCompressContext,
+  agent_export_universal_bundle: handleExportUniversalBundle,
+  agent_bootstrap_environment: handleBootstrapEnvironment,
+  agent_generate_magic_prompt: handleGenerateMagicPrompt,
+  agent_extract_code_skeleton: handleExtractCodeSkeleton,
+  agent_scaffold_feature: handleScaffoldFeature,
+  agent_full_dev_status: (id) => handleFullDevStatus(id),
+  agent_orchestrate_event: handleOrchestrateEvent,
+  agent_inspector_info: handleInspectorInfo,
+  agent_smart_onboarding: handleSmartOnboarding,
+  agent_verify_triad_gate: handleVerifyTriadGate,
+  agent_set_mcp_profile: handleSetMcpProfile,
+  agent_mine_domain_ideas: handleMineDomainIdeas,
+
+  // 5 Meta-Ferramentas Consolidadas (Perfil 'consolidated' / 'lean')
+  agent_governance: handleAgentGovernance,
+  agent_audit: handleAgentAudit,
+  agent_review: handleAgentReview,
+  agent_pipeline: handleAgentPipeline,
+  agent_telemetry: handleAgentTelemetry
+});
+
+/**
+ * Classe Canônica ToolHandlers — Despachante Central e Gestor de Rotas MCP
+ */
+class ToolHandlers {
+  constructor(customHandlers = {}) {
+    this.table = { ...TOOL_DISPATCH_TABLE, ...customHandlers };
+  }
+
+  static get TOOL_DISPATCH_TABLE() {
+    return TOOL_DISPATCH_TABLE;
+  }
+
+  static get META_TOOLS() {
+    return ['agent_governance', 'agent_audit', 'agent_review', 'agent_pipeline', 'agent_telemetry'];
+  }
+
+  /**
+   * Registra um novo handler customizado ou sobrescreve uma rota em tempo de execução
+   */
+  registerHandler(toolName, handlerFn) {
+    if (!toolName || typeof toolName !== 'string') {
+      throw new Error('Nome da tool deve ser uma string válida');
+    }
+    if (typeof handlerFn !== 'function') {
+      throw new Error('Handler da tool deve ser uma função executável');
+    }
+    this.table[toolName] = handlerFn;
+  }
+
+  /**
+   * Despacho síncrono com programação defensiva estrita
+   */
+  handleToolCall(id, params) {
+    try {
+      const safeParams = params && typeof params === 'object' ? params : {};
+      const { name, arguments: args } = safeParams;
+      const handler = this.table[name] || TOOL_DISPATCH_TABLE[name];
+
+      if (!handler) {
+        return {
+          jsonrpc: '2.0',
+          id: id !== undefined ? id : null,
+          error: {
+            code: -32601,
+            message: `Método de tool desconhecido: ${name}`
+          }
+        };
+      }
+
+      return handler(id, args);
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id: id !== undefined ? id : null,
+        error: {
+          code: -32603,
+          message: `Falha interna na execução da ferramenta: ${err.message}`
+        }
+      };
+    }
+  }
+
+  /**
+   * Despacho assíncrono não-bloqueante com captura defensiva de rejeições
+   */
+  async handleToolCallAsync(id, params) {
+    try {
+      const safeParams = params && typeof params === 'object' ? params : {};
+      const { name, arguments: args } = safeParams;
+      const handler = this.table[name] || TOOL_DISPATCH_TABLE[name];
+
+      if (!handler) {
+        return {
+          jsonrpc: '2.0',
+          id: id !== undefined ? id : null,
+          error: {
+            code: -32601,
+            message: `Método de tool desconhecido: ${name}`
+          }
+        };
+      }
+
+      const result = handler(id, args);
+      return result instanceof Promise ? await result : result;
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id: id !== undefined ? id : null,
+        error: {
+          code: -32603,
+          message: `Falha interna na execução da ferramenta: ${err.message}`
+        }
+      };
+    }
+  }
+
+  /**
+   * Auditoria de completude e integridade das rotas no padrão OASIS SARIF v2.1.0
+   */
+  auditToSarif() {
+    const findings = [];
+    const { TOOLS, META_TOOLS } = require('./tools_registry.js');
+    const allDeclared = [...(TOOLS || []), ...(META_TOOLS || [])];
+
+    for (const tool of allDeclared) {
+      const toolName = tool && tool.name;
+      if (!toolName) continue;
+
+      const handler = this.table[toolName] || TOOL_DISPATCH_TABLE[toolName];
+      if (typeof handler !== 'function') {
+        findings.push({
+          ruleId: 'RULE-TOOL-001',
+          severity: 'CRITICAL',
+          filename: 'scripts/mcp/tool_handlers.js',
+          line: 1,
+          column: 1,
+          snippet: `tool: ${toolName}`,
+          message: `Ferramenta declarada '${toolName}' não possui função de handler registrada na tabela de despacho.`,
+          remediation: `Implementar ou registrar o handler correspondente para '${toolName}' em TOOL_DISPATCH_TABLE.`
+        });
+      }
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-tool-dispatcher',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        totalDeclaredTools: allDeclared.length,
+        totalRegisteredHandlers: Object.keys(this.table).length,
+        metaToolsCount: ToolHandlers.META_TOOLS.length
+      }
+    });
+  }
+
+  /**
+   * Emite relatório executivo em Markdown com status de cobertura do roteador
+   */
+  formatReport() {
+    const totalHandlers = Object.keys(this.table).length;
+    return [
+      '# Relatório Executivo: Despachante de Ferramentas MCP',
+      '',
+      `- **Total de Handlers Registrados:** ${totalHandlers}`,
+      `- **Meta-Ferramentas Consolidadas:** ${ToolHandlers.META_TOOLS.length} (${ToolHandlers.META_TOOLS.join(', ')})`,
+      `- **Cobertura de Rotas:** 100% Determinística O(1)`,
+      `- **Status:** OPERACIONAL`,
+      ''
+    ].join('\n');
+  }
+
+  static handleToolCall(id, params) {
+    return defaultToolHandlersInstance.handleToolCall(id, params);
+  }
+
+  static async handleToolCallAsync(id, params) {
+    return await defaultToolHandlersInstance.handleToolCallAsync(id, params);
+  }
+
+  static auditToSarif() {
+    return defaultToolHandlersInstance.auditToSarif();
+  }
+
+  static formatReport() {
+    return defaultToolHandlersInstance.formatReport();
+  }
+}
+
+// Instância singleton padrão
+const defaultToolHandlersInstance = new ToolHandlers();
+
+function handleToolCall(id, params) {
+  return defaultToolHandlersInstance.handleToolCall(id, params);
+}
+
+async function handleToolCallAsync(id, params) {
+  return await defaultToolHandlersInstance.handleToolCallAsync(id, params);
+}
+
+module.exports = {
+  ToolHandlers,
+  defaultToolHandlersInstance,
+  handleToolCall,
+  handleToolCallAsync,
+  TOOL_DISPATCH_TABLE,
+  extractPayload,
+  createMetaToolHandler,
+  handleAgentGovernance,
+  handleAgentAudit,
+  handleAgentReview,
+  handleAgentPipeline,
+  handleAgentTelemetry,
+  auditToSarif: () => ToolHandlers.auditToSarif(),
+  formatReport: () => ToolHandlers.formatReport()
+};