@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/events/hook-handler.js

@@ -0,0 +1,419 @@
+/**
+ * Hook Handler — Multi-type hook execution engine
+ *
+ * Extends Merlin's hook system beyond shell commands with three handler types:
+ *   1. command — Deterministic shell command (existing pattern)
+ *   2. prompt  — LLM-judged evaluation returning allow/block/warn
+ *   3. agent   — Full subagent dispatch via SubagentDispatcher
+ *
+ * Includes recursion guard: hooks cannot trigger other hooks (max depth = 1).
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/events/hook-handler
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { spawn } = require("child_process");
+
+/**
+ * Hook handler types.
+ * @enum {string}
+ */
+const HookHandlerType = {
+  COMMAND: "command", // Shell command execution
+  PROMPT: "prompt", // LLM-judged evaluation
+  AGENT: "agent", // Full subagent dispatch
+};
+
+/**
+ * Prompt handler result actions.
+ * @enum {string}
+ */
+const PromptAction = {
+  ALLOW: "allow",
+  BLOCK: "block",
+  WARN: "warn",
+};
+
+/**
+ * Recursion guard: per-invocation tracking to avoid blocking parallel hooks.
+ * Each execution increments a shared counter; genuine recursion (hook depth > 1)
+ * is detected per async execution chain via the counter.
+ * @type {number}
+ */
+let _hookDepth = 0;
+const MAX_HOOK_DEPTH = 1;
+
+/**
+ * Shell-escape a string to prevent command injection.
+ * Wraps in single quotes and escapes embedded single quotes.
+ * @param {string} s - String to escape
+ * @returns {string} Shell-safe string
+ */
+function shellEscape(s) {
+  if (typeof s !== "string") return "''";
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * HookHandler — Execute hooks of different types.
+ */
+class HookHandler {
+  /**
+   * Execute a hook handler definition.
+   *
+   * @param {Object} handlerDef - Handler definition
+   * @param {string} handlerDef.type - Handler type (command|prompt|agent)
+   * @param {string} [handlerDef.command] - Shell command (for type: command)
+   * @param {string} [handlerDef.prompt] - Prompt template (for type: prompt)
+   * @param {string} [handlerDef.model] - Model for prompt evaluation (for type: prompt)
+   * @param {string} [handlerDef.agentId] - Agent to dispatch (for type: agent)
+   * @param {string} [handlerDef.taskTemplate] - Task template (for type: agent)
+   * @param {number} [handlerDef.timeout] - Execution timeout in ms
+   * @param {Object} eventData - Event data to inject into templates
+   * @param {Object} [options]
+   * @param {Object} [options.dispatcher] - SubagentDispatcher instance (for agent handlers)
+   * @param {string} [options.cwd] - Working directory for command handlers
+   * @returns {Promise<Object>} Execution result
+   */
+  static async execute(handlerDef, eventData, options = {}) {
+    // Recursion guard
+    if (_hookDepth >= MAX_HOOK_DEPTH) {
+      return {
+        success: false,
+        error: "Hook recursion blocked (max depth reached)",
+        type: handlerDef.type,
+      };
+    }
+
+    _hookDepth++;
+    try {
+      const type = handlerDef.type || HookHandlerType.COMMAND;
+
+      switch (type) {
+        case HookHandlerType.COMMAND:
+          return await HookHandler._executeCommand(
+            handlerDef.command,
+            eventData,
+            options,
+          );
+
+        case HookHandlerType.PROMPT:
+          return await HookHandler._executePrompt(
+            handlerDef.prompt,
+            eventData,
+            { ...options, model: handlerDef.model || "haiku" },
+          );
+
+        case HookHandlerType.AGENT:
+          return await HookHandler._executeAgent(
+            handlerDef.agentId,
+            handlerDef.taskTemplate,
+            eventData,
+            options,
+          );
+
+        default:
+          return {
+            success: false,
+            error: `Unknown handler type: ${type}`,
+            type,
+          };
+      }
+    } finally {
+      _hookDepth--;
+    }
+  }
+
+  /**
+   * Execute a shell command handler.
+   *
+   * @param {string} command - Shell command (supports {{event}} and {{file}} placeholders)
+   * @param {Object} eventData - Event data for template interpolation
+   * @param {Object} [options]
+   * @returns {Promise<Object>}
+   * @private
+   */
+  static _executeCommand(command, eventData, options = {}) {
+    if (!command) {
+      return Promise.resolve({
+        success: false,
+        error: "No command specified",
+        type: "command",
+      });
+    }
+
+    // C2 fix: shell-escape file/files values to prevent command injection
+    const interpolated = HookHandler._interpolate(command, eventData, {
+      shellSafe: true,
+    });
+    const timeout = options.timeout || 30000;
+
+    return new Promise((resolve) => {
+      const child = spawn(interpolated, {
+        shell: true,
+        cwd: options.cwd || process.cwd(),
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout,
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+      child.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      child.on("close", (code) => {
+        resolve({
+          success: code === 0,
+          type: "command",
+          output: stdout.trim(),
+          error: code !== 0 ? stderr.trim() || `Exit code ${code}` : null,
+          exitCode: code,
+        });
+      });
+
+      child.on("error", (err) => {
+        resolve({
+          success: false,
+          type: "command",
+          error: err.message,
+          exitCode: null,
+        });
+      });
+    });
+  }
+
+  /**
+   * Execute a prompt handler — LLM evaluates and returns a structured decision.
+   *
+   * @param {string} promptTemplate - Prompt template with {{event}} placeholders
+   * @param {Object} eventData - Event data
+   * @param {Object} [options]
+   * @returns {Promise<Object>}
+   * @private
+   */
+  static async _executePrompt(promptTemplate, eventData, options = {}) {
+    if (!promptTemplate) {
+      return {
+        success: false,
+        error: "No prompt template specified",
+        type: "prompt",
+      };
+    }
+
+    const prompt = HookHandler._interpolate(promptTemplate, eventData);
+    const model = options.model || "haiku";
+    const timeout = options.timeout || 30000;
+
+    // Use Claude CLI for prompt evaluation
+    const fullPrompt = [
+      prompt,
+      "",
+      "Respond with ONLY a JSON object containing:",
+      '  "action": "allow" | "block" | "warn"',
+      '  "reason": "brief explanation"',
+    ].join("\n");
+
+    const PROMPT_MODEL_MAP = {
+      haiku: "claude-haiku-4-5-20251001",
+      sonnet: "claude-sonnet-4-6",
+      opus: "claude-opus-4-6",
+    };
+
+    return new Promise((resolve) => {
+      const modelId = PROMPT_MODEL_MAP[model];
+      if (!modelId) {
+        resolve({
+          success: false,
+          error: `Unknown model: ${model}`,
+          type: "prompt",
+        });
+        return;
+      }
+      const args = ["--print", "--model", modelId, "-p", fullPrompt];
+
+      const child = spawn("claude", args, {
+        cwd: options.cwd || process.cwd(),
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+        timeout,
+      });
+
+      let stdout = "";
+
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      child.on("close", (code) => {
+        if (code !== 0) {
+          resolve({
+            success: false,
+            type: "prompt",
+            action: PromptAction.WARN,
+            reason: "Prompt evaluation failed",
+            error: `Claude exited with code ${code}`,
+          });
+          return;
+        }
+
+        // Parse JSON response (H1 fix: fail-closed — default to WARN on parse failure)
+        try {
+          const jsonMatch = stdout.match(/\{[\s\S]*\}/);
+          if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            // Validate action is a known enum value
+            const action = Object.values(PromptAction).includes(parsed.action)
+              ? parsed.action
+              : PromptAction.WARN;
+            resolve({
+              success: true,
+              type: "prompt",
+              action,
+              reason: parsed.reason || "",
+            });
+          } else {
+            resolve({
+              success: true,
+              type: "prompt",
+              action: PromptAction.WARN,
+              reason: `No JSON in response: ${stdout.trim().substring(0, 200)}`,
+            });
+          }
+        } catch {
+          resolve({
+            success: true,
+            type: "prompt",
+            action: PromptAction.WARN,
+            reason: `Parse error: ${stdout.trim().substring(0, 200)}`,
+          });
+        }
+      });
+
+      child.on("error", (err) => {
+        resolve({
+          success: false,
+          type: "prompt",
+          action: PromptAction.WARN,
+          reason: err.message,
+          error: err.message,
+        });
+      });
+    });
+  }
+
+  /**
+   * Execute an agent handler — dispatch a full subagent task.
+   *
+   * @param {string} agentId - Agent to dispatch
+   * @param {string} taskTemplate - Task description template
+   * @param {Object} eventData - Event data
+   * @param {Object} [options]
+   * @returns {Promise<Object>}
+   * @private
+   */
+  static async _executeAgent(agentId, taskTemplate, eventData, options = {}) {
+    if (!agentId) {
+      return { success: false, error: "No agentId specified", type: "agent" };
+    }
+
+    const dispatcher = options.dispatcher;
+    if (!dispatcher || typeof dispatcher.dispatch !== "function") {
+      return {
+        success: false,
+        error: "No SubagentDispatcher available for agent hook",
+        type: "agent",
+      };
+    }
+
+    const description = HookHandler._interpolate(
+      taskTemplate || "Execute hook task",
+      eventData,
+    );
+
+    const task = {
+      id: `hook-agent-${Date.now()}`,
+      description,
+      source: "hook-handler",
+    };
+
+    const result = await dispatcher.dispatch(agentId, task, {
+      timeout: options.timeout || 60000,
+    });
+
+    return {
+      success: result.success,
+      type: "agent",
+      agentId,
+      output: result.output,
+      error: result.error || null,
+    };
+  }
+
+  /**
+   * Interpolate template placeholders with event data.
+   *
+   * Supported placeholders:
+   *   {{event}} — full JSON event data
+   *   {{file}}  — file path from event data (if present)
+   *   {{files}} — comma-separated file list (if present)
+   *
+   * @param {string} template - Template string
+   * @param {Object} eventData - Event data
+   * @returns {string}
+   * @private
+   */
+  /**
+   * Interpolate template placeholders with event data.
+   *
+   * Supported placeholders:
+   *   {{event}} — full JSON event data
+   *   {{file}}  — file path from event data (if present)
+   *   {{files}} — comma-separated file list (if present)
+   *
+   * @param {string} template - Template string
+   * @param {Object} eventData - Event data
+   * @param {Object} [options]
+   * @param {boolean} [options.shellSafe=false] - Apply shell escaping to file/files values
+   * @returns {string}
+   * @private
+   */
+  static _interpolate(template, eventData, options = {}) {
+    if (!template) return "";
+    let result = template;
+
+    result = result.replace(/\{\{event\}\}/g, JSON.stringify(eventData || {}));
+
+    const data = eventData?.data || eventData || {};
+    if (data.file) {
+      const fileVal = options.shellSafe ? shellEscape(data.file) : data.file;
+      result = result.replace(/\{\{file\}\}/g, fileVal);
+    }
+    if (data.files && Array.isArray(data.files)) {
+      const filesVal = options.shellSafe
+        ? data.files.map(shellEscape).join(", ")
+        : data.files.join(", ");
+      result = result.replace(/\{\{files\}\}/g, filesVal);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get current hook execution depth (for testing/debugging).
+   * @returns {number}
+   */
+  static getDepth() {
+    return _hookDepth;
+  }
+}
+
+module.exports = { HookHandler, HookHandlerType, PromptAction, MAX_HOOK_DEPTH };

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

@@ -0,0 +1,17 @@
+# Execution Engine
+
+The execution engine drives Merlin's autonomous build and deployment operations. It manages the autonomous build loop, orchestrates parallel task execution, performs semantic-aware merging, and dispatches work to subagents while maintaining consistency and traceability.
+
+## Contents
+
+- **build-loop/** - Autonomous build loop controller with retry and recovery mechanisms
+- **parallel-executor/** - Concurrent task execution with dependency resolution
+- **semantic-merge/** - Intelligent merge engine with conflict resolution
+- **subagent-dispatcher/** - Delegation and coordination of work to specialized agents
+- **executor.js** - Main execution engine orchestrator
+
+## Related
+
+- [Alkimia](../alkimia/README.md)
+- [Orchestration](../orchestration/README.md)
+- [Quality Gates](../quality-gates/README.md)