@caoscompanybr/merlin 3.5.0

package/.merlin-core/mcp-servers/lsp-bridge/index.js

@@ -0,0 +1,397 @@
+/**
+ * LSP Bridge MCP Server (#2)
+ *
+ * Wraps Language Server Protocol clients as MCP tools.
+ * Supports TypeScript (tsserver), Python (pyright), and Go (gopls).
+ * Falls back to grep-based resolution when no language server is available.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module mcp-servers/lsp-bridge
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+/**
+ * Supported language server configurations.
+ * @constant
+ */
+const LANGUAGE_SERVERS = {
+  typescript: {
+    command: "npx",
+    args: ["typescript-language-server", "--stdio"],
+    extensions: [".ts", ".tsx", ".js", ".jsx"],
+    fallbackPatterns: {
+      definition:
+        /(?:export\s+)?(?:class|function|const|let|var|type|interface|enum)\s+/,
+      reference: null, // uses grep
+    },
+  },
+  python: {
+    command: "pyright-langserver",
+    args: ["--stdio"],
+    extensions: [".py"],
+    fallbackPatterns: {
+      definition: /(?:class|def)\s+/,
+      reference: null,
+    },
+  },
+  go: {
+    command: "gopls",
+    args: ["serve"],
+    extensions: [".go"],
+    fallbackPatterns: {
+      definition: /(?:func|type)\s+/,
+      reference: null,
+    },
+  },
+};
+
+/**
+ * LSP Bridge -- MCP server providing code intelligence tools.
+ */
+class LSPBridge {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.projectRoot] - Project root directory
+   * @param {string[]} [config.languages] - Languages to enable (default: auto-detect)
+   */
+  constructor(config = {}) {
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.languages = config.languages || this._detectLanguages();
+    this._clients = new Map();
+  }
+
+  /**
+   * Go to definition of a symbol.
+   *
+   * @param {string} file - File path (relative to project root)
+   * @param {number} line - Line number (1-based)
+   * @param {number} col - Column number (0-based)
+   * @returns {Object} Definition location or fallback result
+   */
+  goToDefinition(file, line, col) {
+    // Try LSP first (placeholder — actual LSP integration requires async init)
+    // Fall back to grep-based resolution
+    return this._grepDefinition(file, line, col);
+  }
+
+  /**
+   * Find all references to a symbol.
+   *
+   * @param {string} symbol - Symbol name
+   * @param {Object} [options]
+   * @param {string[]} [options.extensions] - File extensions to search
+   * @returns {Array<{file: string, line: number, content: string}>}
+   */
+  findReferences(symbol, options = {}) {
+    const extensions = options.extensions || [
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".py",
+      ".go",
+    ];
+    // C2 fix: Use execFileSync with argument array to prevent command injection
+    const args = ["-rn", symbol];
+    for (const ext of extensions) {
+      args.push(`--include=*${ext}`);
+    }
+    args.push("--exclude-dir=node_modules", "--exclude-dir=.git", ".");
+
+    try {
+      const output = execFileSync("grep", args, {
+        cwd: this.projectRoot,
+        stdio: "pipe",
+        timeout: 10000,
+      }).toString();
+
+      return output
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+          const match = line.match(/^(.+?):(\d+):(.*)$/);
+          if (!match) return null;
+          return {
+            file: match[1],
+            line: parseInt(match[2], 10),
+            content: match[3].trim(),
+          };
+        })
+        .filter(Boolean)
+        .slice(0, 50);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get hover information for a symbol position.
+   *
+   * @param {string} file - File path
+   * @param {number} line - Line number
+   * @param {number} col - Column number
+   * @returns {Object} Hover info (type signature, documentation)
+   */
+  hoverSymbol(file, line, col) {
+    // Fallback: extract the word at position and grep for its definition
+    try {
+      const fullPath = path.resolve(this.projectRoot, file);
+      // C2 fix: Prevent path traversal outside project root
+      if (!fullPath.startsWith(path.resolve(this.projectRoot) + path.sep)) {
+        return { symbol: null, info: "Path traversal rejected" };
+      }
+      const content = require("fs").readFileSync(fullPath, "utf8");
+      const lines = content.split("\n");
+      const targetLine = lines[line - 1] || "";
+
+      // Extract word at column
+      const wordMatch = targetLine.substring(col).match(/^(\w+)/);
+      const symbol = wordMatch ? wordMatch[1] : null;
+
+      if (!symbol) return { symbol: null, info: "No symbol at position" };
+
+      const refs = this.findReferences(symbol, {
+        extensions: this._getExtensionsForFile(file),
+      });
+      const defLine = refs.find((r) =>
+        /(?:class|function|def|func|const|let|var|type|interface|enum)\s/.test(
+          r.content,
+        ),
+      );
+
+      return {
+        symbol,
+        definition: defLine || null,
+        referenceCount: refs.length,
+        source: "grep-fallback",
+      };
+    } catch {
+      return { symbol: null, info: "Error reading file" };
+    }
+  }
+
+  /**
+   * Get diagnostics (errors/warnings) for a file.
+   *
+   * @param {string} file - File path
+   * @returns {Array<{line: number, severity: string, message: string}>}
+   */
+  getDiagnostics(file) {
+    const ext = path.extname(file);
+
+    // TypeScript diagnostics
+    if ([".ts", ".tsx"].includes(ext)) {
+      return this._getTsDiagnostics(file);
+    }
+
+    // Python diagnostics
+    if (ext === ".py") {
+      return this._getPyDiagnostics(file);
+    }
+
+    return [
+      {
+        line: 0,
+        severity: "info",
+        message: `No diagnostics provider for ${ext}`,
+      },
+    ];
+  }
+
+  /**
+   * MCP tool definitions for registration.
+   * @returns {Array<Object>} Tool definitions
+   */
+  getToolDefinitions() {
+    return [
+      {
+        name: "go_to_definition",
+        description:
+          "Navigate to the definition of a symbol at a given file position",
+        parameters: {
+          file: {
+            type: "string",
+            description: "File path relative to project root",
+          },
+          line: { type: "number", description: "Line number (1-based)" },
+          col: { type: "number", description: "Column number (0-based)" },
+        },
+      },
+      {
+        name: "find_references",
+        description: "Find all references to a symbol across the codebase",
+        parameters: {
+          symbol: { type: "string", description: "Symbol name to search for" },
+          extensions: {
+            type: "array",
+            description: "File extensions to search",
+            optional: true,
+          },
+        },
+      },
+      {
+        name: "hover_symbol",
+        description: "Get type information and documentation for a symbol",
+        parameters: {
+          file: { type: "string" },
+          line: { type: "number" },
+          col: { type: "number" },
+        },
+      },
+      {
+        name: "get_diagnostics",
+        description: "Get errors and warnings for a file",
+        parameters: {
+          file: {
+            type: "string",
+            description: "File path relative to project root",
+          },
+        },
+      },
+    ];
+  }
+
+  // -------------------------------------------------------------------------
+  //  Private
+  // -------------------------------------------------------------------------
+
+  _grepDefinition(file, line, col) {
+    try {
+      const fullPath = path.resolve(this.projectRoot, file);
+      // C2 fix: Prevent path traversal outside project root
+      if (!fullPath.startsWith(path.resolve(this.projectRoot) + path.sep)) {
+        return { found: false, reason: "Path traversal rejected" };
+      }
+      const content = require("fs").readFileSync(fullPath, "utf8");
+      const lines = content.split("\n");
+      const targetLine = lines[line - 1] || "";
+
+      const wordMatch = targetLine.substring(col).match(/^(\w+)/);
+      if (!wordMatch) return { found: false, reason: "No symbol at position" };
+
+      const symbol = wordMatch[1];
+      const refs = this.findReferences(symbol);
+      const definition = refs.find((r) =>
+        /(?:export\s+)?(?:class|function|def|func|const|let|var|type|interface|enum)\s/.test(
+          r.content,
+        ),
+      );
+
+      if (definition) {
+        return {
+          found: true,
+          file: definition.file,
+          line: definition.line,
+          content: definition.content,
+          source: "grep-fallback",
+        };
+      }
+
+      return { found: false, symbol, reason: "Definition not found via grep" };
+    } catch (err) {
+      return { found: false, error: err.message };
+    }
+  }
+
+  _getTsDiagnostics(file) {
+    try {
+      // C2 fix: Use execFileSync to prevent command injection
+      const output = execFileSync(
+        "npx",
+        ["tsc", "--noEmit", "--pretty", "false", file],
+        { cwd: this.projectRoot, stdio: "pipe", timeout: 30000 },
+      ).toString();
+
+      return output
+        .split("\n")
+        .filter((l) => l.includes("error TS") || l.includes("warning"))
+        .map((l) => {
+          const match = l.match(/:(\d+):\d+\s*-\s*(error|warning)\s+(.+)/);
+          if (!match) return null;
+          return {
+            line: parseInt(match[1], 10),
+            severity: match[2],
+            message: match[3],
+          };
+        })
+        .filter(Boolean)
+        .slice(0, 20);
+    } catch (err) {
+      // tsc returns non-zero on errors — parse stderr
+      const output = (err.stdout || err.stderr || "").toString();
+      return output
+        .split("\n")
+        .filter((l) => l.includes("error TS"))
+        .map((l) => {
+          const match = l.match(/:(\d+):\d+\s*-\s*(error)\s+(.+)/);
+          if (!match) return null;
+          return {
+            line: parseInt(match[1], 10),
+            severity: match[2],
+            message: match[3],
+          };
+        })
+        .filter(Boolean)
+        .slice(0, 20);
+    }
+  }
+
+  _getPyDiagnostics(file) {
+    try {
+      // C2 fix: Use execFileSync to prevent command injection
+      const output = execFileSync("python", ["-m", "py_compile", file], {
+        cwd: this.projectRoot,
+        stdio: "pipe",
+        timeout: 10000,
+      }).toString();
+
+      if (!output.trim()) return []; // No errors
+
+      return [{ line: 0, severity: "error", message: output.trim() }];
+    } catch (err) {
+      return [
+        {
+          line: 0,
+          severity: "error",
+          message: (err.stderr || "").toString().trim(),
+        },
+      ];
+    }
+  }
+
+  _detectLanguages() {
+    const detected = [];
+    const fs = require("fs");
+
+    if (fs.existsSync(path.join(this.projectRoot, "tsconfig.json"))) {
+      detected.push("typescript");
+    }
+    if (
+      fs.existsSync(path.join(this.projectRoot, "requirements.txt")) ||
+      fs.existsSync(path.join(this.projectRoot, "pyproject.toml"))
+    ) {
+      detected.push("python");
+    }
+    if (fs.existsSync(path.join(this.projectRoot, "go.mod"))) {
+      detected.push("go");
+    }
+
+    return detected.length > 0 ? detected : ["typescript"];
+  }
+
+  _getExtensionsForFile(file) {
+    const ext = path.extname(file);
+    for (const [, config] of Object.entries(LANGUAGE_SERVERS)) {
+      if (config.extensions.includes(ext)) return config.extensions;
+    }
+    return [".ts", ".tsx", ".js", ".jsx"];
+  }
+}
+
+module.exports = { LSPBridge, LANGUAGE_SERVERS };

package/.merlin-core/modules/scraping/module.json

@@ -0,0 +1,23 @@
+{
+  "id": "scraping",
+  "name": "Scraping / Apify",
+  "description": "Puxa dados de concorrentes (perfis/vídeos/sites) — com trava de identidade e LGPD antes de gastar crédito.",
+  "version": "0.5.0",
+  "kind": "framework-capability",
+  "deploy_kind": "framework-skill",
+  "tier_min": "time",
+  "depends_on": [],
+  "access_policy": "collaborator",
+  "framework": {
+    "skills": ["apify-scrape", "youtube-transcript", "marketing-ops"],
+    "agents": ["web-researcher"],
+    "commands": ["special/scrape.md"],
+    "checklists": ["source-verification-checklist"]
+  },
+  "tenant": {
+    "no_gcp": true,
+    "activation": "config/modules.enabled[] (L2)",
+    "secrets_vault_stubs": ["APIFY_TOKEN", "IPROYAL_USERNAME", "IPROYAL_PASSWORD", "GLADIA_API_KEY"],
+    "preflight_gates": ["identity-gate", "lgpd-compliance-audit", "proxy-on-datacenter", "rate-limit-cache"]
+  }
+}

package/.merlin-core/project-config.yaml

@@ -0,0 +1,89 @@
+# ============================================
+# Merlin Project Configuration (Level 2)
+# ============================================
+# EDIT THIS FILE to customize for your project.
+# Values here override framework-config.yaml defaults.
+#
+# Level: L2 (Project)
+# Mutability: Editable by project team
+# Git status: Committed (project-specific)
+# ============================================
+
+# --- Project Identity ---
+project:
+  name: "Gestao Merlin"
+  description: "The Mage of Management - Unified AI Orchestration Framework"
+  version: "3.5.0"
+  language: "en"
+
+# --- Team Configuration ---
+team:
+  size: small
+  methodology: agile
+
+# --- Active Agent Configuration ---
+agents:
+  active:
+    - merlin-master
+    - analyst
+    - architect
+    - dev
+    - devops
+    - pm
+    - po
+    - qa
+    - sm
+    - ux
+    - data-engineer
+    - researcher
+    - scout
+
+# --- Merlin Modules (soft-activation, L2) ---
+# Modules enabled for this project (Merlin Modules system, v3.5). Mirrors the
+# `agents.active` precedent. `framework-skill` modules activate HERE (a soft
+# toggle), NOT via a Firestore flag. provision-module.mjs writes this list on
+# --apply, gated by a passing verifyModule().
+modules:
+  enabled: []
+
+# --- Active Workflow Configuration ---
+workflows:
+  default: development-cycle
+  available:
+    - development-cycle
+    - spec-pipeline
+    - folloni-funnel
+    - qa-loop
+    - greenfield-fullstack
+    - brownfield-discovery
+
+# --- Managed Projects ---
+# Register projects that this Merlin instance orchestrates. Each entry points at
+# a local checkout and records its stack so agents can reason about it.
+managed_projects: {}
+  # example-project:
+  #   name: "Example Project"
+  #   location: "/path/to/your/project"
+  #   stack:
+  #     backend: "Python 3.12 + FastAPI"
+  #     database: "PostgreSQL 16"
+  #     frontend: "Next.js 15 + Tailwind"
+  #   status: active
+  #   description: "Short description of what this project does"
+
+# --- MCP Servers (project-specific) ---
+mcp:
+  servers: {}
+
+# --- Approval Overrides ---
+approval:
+  high_stake_actions:
+    - production_deploy
+    - database_migration
+    - credential_rotation
+    - repository_deletion
+  medium_stake_actions:
+    - git_push_protected
+    - pr_creation
+    - epic_scope_change
+    - mcp_config_change

package/.merlin-core/schemas/README.md

@@ -0,0 +1,18 @@
+# JSON Schemas
+
+The schemas module contains JSON schemas for validating Merlin's configuration and definition files. Schemas define the structure and constraints for agents, commands, skills, workflows, and configuration files, ensuring consistency and enabling early validation.
+
+## Contents
+
+- **agent.schema.json** - Schema for agent definitions
+- **command.schema.json** - Schema for slash command definitions
+- **skill.schema.json** - Schema for skill definitions
+- **workflow.schema.json** - Schema for workflow definitions
+- **config.schema.json** - Schema for configuration files
+- **validator.js** - Schema validation utility
+
+## Related
+
+- [Development](../development/README.md)
+- [Config](../core/config/README.md)
+- [Skills](../skills/README.md)

package/.merlin-core/schemas/agent-hook-schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "merlin://schemas/agent-hook",
+  "title": "Agent Hook Definition",
+  "description": "Defines an event-driven hook that triggers command, prompt, or agent workflows in response to system events.",
+  "type": "object",
+  "required": ["id", "channel"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique hook identifier",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "channel": {
+      "type": "string",
+      "description": "Event channel to listen on (e.g., 'workflow', 'agent', 'git', 'file')",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "event": {
+      "type": "string",
+      "description": "Specific event name to trigger on, or '*' for all events on the channel",
+      "default": "*"
+    },
+    "handler": {
+      "type": "object",
+      "description": "Handler definition. Supports command, prompt, and agent types.",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command", "prompt", "agent"],
+          "description": "Handler type: command (shell), prompt (LLM-judged), agent (subagent dispatch)"
+        },
+        "command": {
+          "type": "string",
+          "description": "Shell command to execute (for type: command). Supports {{event}} and {{file}} placeholders."
+        },
+        "prompt": {
+          "type": "string",
+          "description": "Prompt template for LLM evaluation (for type: prompt). Supports {{event}} placeholder."
+        },
+        "model": {
+          "type": "string",
+          "enum": ["haiku", "sonnet", "opus"],
+          "description": "Model for prompt evaluation (for type: prompt). Default: haiku.",
+          "default": "haiku"
+        },
+        "agentId": {
+          "type": "string",
+          "description": "Agent to dispatch (for type: agent)",
+          "enum": [
+            "merlin-master", "analyst", "architect", "dev", "devops",
+            "pm", "po", "qa", "sm", "ux", "data-engineer",
+            "researcher", "scout", "web-researcher", "meta"
+          ]
+        },
+        "taskTemplate": {
+          "type": "string",
+          "description": "Task description template for agent dispatch (for type: agent). Supports {{event}} and {{files}} placeholders."
+        },
+        "timeout": {
+          "type": "integer",
+          "description": "Execution timeout in milliseconds",
+          "default": 30000,
+          "minimum": 1000,
+          "maximum": 300000
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "command" } } },
+          "then": { "required": ["command"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "prompt" } } },
+          "then": { "required": ["prompt"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "agent" } } },
+          "then": { "required": ["agentId"] }
+        }
+      ]
+    },
+    "agentId": {
+      "type": "string",
+      "description": "[DEPRECATED] Use handler.agentId instead. Kept for backward compatibility.",
+      "enum": [
+        "merlin-master", "analyst", "architect", "dev", "devops",
+        "pm", "po", "qa", "sm", "ux", "data-engineer",
+        "researcher", "scout", "web-researcher", "meta"
+      ]
+    },
+    "taskTemplate": {
+      "type": "string",
+      "description": "[DEPRECATED] Use handler.taskTemplate instead. Kept for backward compatibility.",
+      "default": "Execute agent hook"
+    },
+    "filter": {
+      "type": "object",
+      "description": "Optional key-value filter applied to event data. Hook only fires if all filter conditions match.",
+      "additionalProperties": true
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether the hook is active",
+      "default": true
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "id": "lint-on-save",
+      "channel": "file",
+      "event": "changed",
+      "handler": {
+        "type": "command",
+        "command": "npx eslint --fix {{file}}",
+        "timeout": 15000
+      },
+      "filter": { "extension": ".js" }
+    },
+    {
+      "id": "review-on-commit",
+      "channel": "git",
+      "event": "committed",
+      "handler": {
+        "type": "prompt",
+        "prompt": "Review this commit for quality issues: {{event}}",
+        "model": "haiku"
+      }
+    },
+    {
+      "id": "qa-after-deploy",
+      "channel": "workflow",
+      "event": "phase-completed",
+      "handler": {
+        "type": "agent",
+        "agentId": "qa",
+        "taskTemplate": "Run smoke tests after deployment: {{event}}",
+        "timeout": 120000
+      },
+      "filter": { "phase": "deployment" }
+    },
+    {
+      "id": "qa-after-commit",
+      "channel": "git",
+      "event": "committed",
+      "agentId": "qa",
+      "taskTemplate": "Run quality checks on the latest commit: {{event}}"
+    }
+  ]
+}