agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/mcp/resources_registry.js

@@ -0,0 +1,453 @@
+/**
+ * scripts/mcp/resources_registry.js
+ * 
+ * Resources Registry — Catálogo e Leitor de Recursos Canônicos MCP.
+ * Fornece acesso à documentação viva (Princípios Canônicos, Arquitetura, Backlog de Ideias,
+ * Livro-Razão e Estado Ativo) e barramento de eventos multi-agente.
+ * Compatível com o protocolo oficial MCP (Model Context Protocol) resources/list e resources/read.
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+const ROOT_DIR = path.resolve(__dirname, '../..');
+
+/**
+ * Catálogo declarativo imutável de recursos canônicos do Agent Master
+ */
+const RESOURCE_DEFINITIONS = Object.freeze({
+  'agent://rules': Object.freeze({
+    uri: 'agent://rules',
+    name: 'Os 10 Princípios Canônicos de Engenharia de Software & Governança (ENGINEERING_RULES.md)',
+    mimeType: 'text/markdown',
+    relPath: 'docs/ENGINEERING_RULES.md'
+  }),
+  'agent://architecture': Object.freeze({
+    uri: 'agent://architecture',
+    name: 'Arquitetura Multi-Agente & Handovers (ARCHITECTURE.md)',
+    mimeType: 'text/markdown',
+    relPath: 'docs/ARCHITECTURE.md'
+  }),
+  'agent://ideas': Object.freeze({
+    uri: 'agent://ideas',
+    name: 'Backlog Vivo de Ideias & Auto-Evolução (IDEAS.md)',
+    mimeType: 'text/markdown',
+    relPath: 'docs/IDEAS.md'
+  }),
+  'agent://events': Object.freeze({
+    uri: 'agent://events',
+    name: 'Histórico e Barramento de Eventos Multi-Agente',
+    mimeType: 'application/json',
+    dynamicProvider: () => {
+      const { EVENT_TYPES, AGENT_PERSONAS } = require('../core/multi_agent_orchestrator.js');
+      return JSON.stringify({
+        status: 'ACTIVE',
+        busType: 'Mesh-Hierarchical Event Bus',
+        supportedEvents: Object.keys(EVENT_TYPES),
+        registeredPersonas: Object.keys(AGENT_PERSONAS || {})
+      }, null, 2);
+    }
+  }),
+  'agent://changelog': Object.freeze({
+    uri: 'agent://changelog',
+    name: 'Livro-Razão Imutável de Entregas (CHANGELOG.md)',
+    mimeType: 'text/markdown',
+    relPath: 'docs/CHANGELOG.md'
+  }),
+  'agent://state': Object.freeze({
+    uri: 'agent://state',
+    name: 'Quadro de Execução Ativo do Framework (STATE.md)',
+    mimeType: 'text/markdown',
+    relPath: 'docs/STATE.md'
+  })
+});
+
+/**
+ * Lista de recursos exposta pelo protocolo MCP resources/list (imutável)
+ */
+const RESOURCES = Object.freeze(
+  Object.values(RESOURCE_DEFINITIONS).map(def => Object.freeze({
+    uri: def.uri,
+    name: def.name,
+    mimeType: def.mimeType
+  }))
+);
+
+/**
+ * Helper puro de resolução de caminho absoluto com proteção contra Path Traversal (CWE-22)
+ */
+function resolveDocFile(rootDir, relPath) {
+  const safeRoot = path.resolve(rootDir || ROOT_DIR);
+  const targetPath = path.resolve(safeRoot, relPath);
+  if (!targetPath.startsWith(safeRoot)) {
+    throw new Error(`Tentativa de Path Traversal bloqueada: ${relPath}`);
+  }
+  return targetPath;
+}
+
+/**
+ * Helpers funcionais puros para envelopes JSON-RPC 2.0 (DRY)
+ */
+function buildSuccessResponse(id, result) {
+  return {
+    jsonrpc: '2.0',
+    id: id !== undefined && id !== null ? id : null,
+    result
+  };
+}
+
+function buildErrorResponse(id, code, message, data = null) {
+  const error = { code, message };
+  if (data !== null && data !== undefined) {
+    error.data = data;
+  }
+  return {
+    jsonrpc: '2.0',
+    id: id !== undefined && id !== null ? id : null,
+    error
+  };
+}
+
+function buildResourceContentResponse(id, uri, mimeType, text) {
+  return buildSuccessResponse(id, {
+    contents: [
+      {
+        uri,
+        mimeType,
+        text
+      }
+    ]
+  });
+}
+
+/**
+ * Classe Canônica ResourcesRegistry — Gerenciador de Recursos e Documentação Viva MCP
+ */
+class ResourcesRegistry {
+  constructor(rootDir = ROOT_DIR, customRegistry = null) {
+    this.rootDir = path.resolve(rootDir || ROOT_DIR);
+    this.customRegistry = customRegistry ? new Map(Object.entries(customRegistry)) : new Map();
+  }
+
+  static get ROOT_DIR() {
+    return ROOT_DIR;
+  }
+
+  static get RESOURCES() {
+    return RESOURCES;
+  }
+
+  static get RESOURCE_DEFINITIONS() {
+    return RESOURCE_DEFINITIONS;
+  }
+
+  /**
+   * Registra dinamicamente um novo recurso no registro em runtime
+   */
+  registerResource(uri, definition) {
+    if (!uri || typeof uri !== 'string') {
+      throw new Error('URI do recurso deve ser uma string válida');
+    }
+    if (!definition || typeof definition !== 'object') {
+      throw new Error('Definição do recurso deve ser um objeto válido');
+    }
+    this.customRegistry.set(uri, Object.freeze({
+      uri,
+      name: definition.name || uri,
+      mimeType: definition.mimeType || 'text/plain',
+      relPath: definition.relPath || null,
+      dynamicProvider: typeof definition.dynamicProvider === 'function' ? definition.dynamicProvider : null
+    }));
+  }
+
+  /**
+   * Resolve a definição de um recurso por URI
+   */
+  getDefinition(uri) {
+    if (!uri || typeof uri !== 'string') return null;
+    if (this.customRegistry.has(uri)) {
+      return this.customRegistry.get(uri);
+    }
+    return RESOURCE_DEFINITIONS[uri] || null;
+  }
+
+  /**
+   * Lista todos os recursos disponíveis (estático e instância)
+   */
+  listResources() {
+    const defaultList = [...RESOURCES];
+    const customList = Array.from(this.customRegistry.values()).map(def => ({
+      uri: def.uri,
+      name: def.name,
+      mimeType: def.mimeType
+    }));
+    return [...defaultList, ...customList];
+  }
+
+  static handleResourcesList(id) {
+    return buildSuccessResponse(id, {
+      resources: RESOURCES
+    });
+  }
+
+  handleResourcesList(id) {
+    return buildSuccessResponse(id, {
+      resources: this.listResources()
+    });
+  }
+
+  /**
+   * Resolução síncrona de conteúdo de recurso
+   */
+  resolveContentSync(uri) {
+    const def = this.getDefinition(uri);
+    if (!def) return null;
+
+    if (typeof def.dynamicProvider === 'function') {
+      return {
+        uri: def.uri,
+        mimeType: def.mimeType,
+        text: def.dynamicProvider()
+      };
+    }
+
+    if (def.relPath) {
+      const filePath = resolveDocFile(this.rootDir, def.relPath);
+      if (fs.existsSync(filePath)) {
+        const text = fs.readFileSync(filePath, 'utf8');
+        return {
+          uri: def.uri,
+          mimeType: def.mimeType,
+          text
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Resolução assíncrona de conteúdo de recurso
+   */
+  async resolveContentAsync(uri) {
+    const def = this.getDefinition(uri);
+    if (!def) return null;
+
+    if (typeof def.dynamicProvider === 'function') {
+      const res = def.dynamicProvider();
+      const text = res instanceof Promise ? await res : res;
+      return {
+        uri: def.uri,
+        mimeType: def.mimeType,
+        text
+      };
+    }
+
+    if (def.relPath) {
+      const filePath = resolveDocFile(this.rootDir, def.relPath);
+      try {
+        const text = await fs.promises.readFile(filePath, 'utf8');
+        return {
+          uri: def.uri,
+          mimeType: def.mimeType,
+          text
+        };
+      } catch {
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Leitura de recurso MCP síncrona (JSON-RPC 2.0)
+   */
+  handleResourceRead(id, params) {
+    try {
+      const safeParams = params && typeof params === 'object' ? params : {};
+      const uri = safeParams.uri;
+      const content = this.resolveContentSync(uri);
+
+      if (content) {
+        return buildResourceContentResponse(id, content.uri, content.mimeType, content.text);
+      }
+
+      return buildErrorResponse(id, -32602, `Recurso não encontrado: ${uri}`);
+    } catch (err) {
+      return buildErrorResponse(id, -32603, `Falha interna ao ler recurso: ${err.message}`);
+    }
+  }
+
+  static handleResourceRead(id, params) {
+    const defaultInstance = new ResourcesRegistry(ROOT_DIR);
+    return defaultInstance.handleResourceRead(id, params);
+  }
+
+  /**
+   * Leitura de recurso MCP assíncrona (JSON-RPC 2.0)
+   */
+  async handleResourceReadAsync(id, params) {
+    try {
+      const safeParams = params && typeof params === 'object' ? params : {};
+      const uri = safeParams.uri;
+      const content = await this.resolveContentAsync(uri);
+
+      if (content) {
+        return buildResourceContentResponse(id, content.uri, content.mimeType, content.text);
+      }
+
+      return buildErrorResponse(id, -32602, `Recurso não encontrado: ${uri}`);
+    } catch (err) {
+      return buildErrorResponse(id, -32603, `Falha interna ao ler recurso: ${err.message}`);
+    }
+  }
+
+  static async handleResourceReadAsync(id, params) {
+    const defaultInstance = new ResourcesRegistry(ROOT_DIR);
+    return await defaultInstance.handleResourceReadAsync(id, params);
+  }
+
+  /**
+   * Auditoria de integridade de todos os recursos no padrão OASIS SARIF v2.1.0
+   */
+  auditToSarif() {
+    const findings = [];
+    const allDefs = { ...RESOURCE_DEFINITIONS, ...Object.fromEntries(this.customRegistry) };
+
+    for (const [uri, def] of Object.entries(allDefs)) {
+      if (def.relPath) {
+        try {
+          const filePath = resolveDocFile(this.rootDir, def.relPath);
+          if (!fs.existsSync(filePath)) {
+            findings.push({
+              ruleId: 'RULE-RES-001',
+              severity: 'HIGH',
+              filename: def.relPath,
+              line: 1,
+              column: 1,
+              snippet: `URI: ${uri}`,
+              message: `Documento de governança '${def.relPath}' não foi encontrado no disco.`,
+              remediation: `Restaurar ou provisionar o arquivo '${def.relPath}' para conformidade com a Tríade.`
+            });
+          }
+        } catch (err) {
+          findings.push({
+            ruleId: 'RULE-RES-001',
+            severity: 'HIGH',
+            filename: def.relPath,
+            line: 1,
+            column: 1,
+            snippet: `URI: ${uri}`,
+            message: `Erro ao validar caminho do recurso: ${err.message}`,
+            remediation: 'Verificar integridade estrutural e permissões de acesso ao arquivo.'
+          });
+        }
+      } else if (typeof def.dynamicProvider === 'function') {
+        try {
+          const res = def.dynamicProvider();
+          if (!res) throw new Error('Provider retornou payload nulo');
+        } catch (err) {
+          findings.push({
+            ruleId: 'RULE-RES-002',
+            severity: 'HIGH',
+            filename: 'multi_agent_orchestrator.js',
+            line: 1,
+            column: 1,
+            snippet: `URI: ${uri}`,
+            message: `Falha ao gerar recurso dinâmico '${uri}': ${err.message}`,
+            remediation: 'Verificar status do barramento de eventos ou imports no orquestrador multi-agente.'
+          });
+        }
+      }
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-resources-registry',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        totalResources: Object.keys(allDefs).length,
+        brokenResources: findings.length
+      }
+    });
+  }
+
+  static auditToSarif() {
+    const defaultInstance = new ResourcesRegistry(ROOT_DIR);
+    return defaultInstance.auditToSarif();
+  }
+
+  /**
+   * Gera relatório executivo em Markdown com status de cada recurso
+   */
+  formatReport() {
+    const allDefs = { ...RESOURCE_DEFINITIONS, ...Object.fromEntries(this.customRegistry) };
+    const lines = [
+      '# Relatório Executivo: Recursos MCP & Documentação Viva',
+      '',
+      `| URI | Nome | Tipo MIME | Origem | Status |`,
+      `|---|---|---|---|---|`
+    ];
+
+    for (const [uri, def] of Object.entries(allDefs)) {
+      let status = 'ONLINE';
+      let origem = def.relPath ? `docs (${def.relPath})` : 'Barramento Dinâmico';
+
+      if (def.relPath) {
+        const filePath = resolveDocFile(this.rootDir, def.relPath);
+        if (!fs.existsSync(filePath)) {
+          status = 'AUSENTE (404)';
+        }
+      } else if (typeof def.dynamicProvider === 'function') {
+        try {
+          def.dynamicProvider();
+        } catch {
+          status = 'FALHA DE EXECUÇÃO';
+        }
+      }
+
+      lines.push(`| \`${uri}\` | ${def.name} | \`${def.mimeType}\` | ${origem} | ${status} |`);
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  static formatReport() {
+    const defaultInstance = new ResourcesRegistry(ROOT_DIR);
+    return defaultInstance.formatReport();
+  }
+}
+
+// Funções stand-alone compatíveis com a API legada
+function handleResourcesList(id) {
+  return ResourcesRegistry.handleResourcesList(id);
+}
+
+function handleResourceRead(id, params) {
+  return ResourcesRegistry.handleResourceRead(id, params);
+}
+
+async function handleResourceReadAsync(id, params) {
+  return await ResourcesRegistry.handleResourceReadAsync(id, params);
+}
+
+module.exports = {
+  ResourcesRegistry,
+  ROOT_DIR,
+  RESOURCES,
+  RESOURCE_DEFINITIONS,
+  resolveDocFile,
+  handleResourcesList,
+  handleResourceRead,
+  handleResourceReadAsync,
+  buildSuccessResponse,
+  buildErrorResponse,
+  buildResourceContentResponse
+};