@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/wave-executor.js

@@ -0,0 +1,224 @@
+/**
+ * Wave Executor
+ *
+ * Executes tasks in waves (batches) honouring a dependency graph.
+ * Uses Kahn's algorithm for topological sorting to determine the
+ * correct execution order, then runs each wave in parallel.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/wave-executor
+ * @version 3.0.0
+ */
+
+const { EventEmitter } = require("events");
+
+// ---------------------------------------------------------------------------
+//  WaveExecutor
+// ---------------------------------------------------------------------------
+
+class WaveExecutor extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {number}   [config.maxParallel=4]     Max tasks per wave chunk.
+   * @param {number}   [config.taskTimeout=600000] Per-task timeout (10 min).
+   * @param {Function} [config.taskRunner]         Async (task) => result.
+   */
+  constructor(config = {}) {
+    super();
+    this.maxParallel = config.maxParallel || 4;
+    this.taskTimeout = config.taskTimeout || 600000;
+    this.taskRunner = config.taskRunner || null;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Plan execution waves from a list of tasks with dependencies.
+   *
+   * Each task must have `{ id, [dependsOn: string[]] }`.
+   *
+   * @param {Array<Object>} tasks
+   * @returns {Array<Array<Object>>} Array of waves, each wave is an array of tasks.
+   */
+  plan(tasks) {
+    const graph = this._buildDependencyGraph(tasks);
+    const sorted = this._topologicalSort(graph, tasks);
+    return sorted;
+  }
+
+  /**
+   * Execute pre-planned waves sequentially. Within each wave, tasks
+   * run in parallel (up to maxParallel).
+   *
+   * @param {Array<Array<Object>>} waves - Output of `plan()`.
+   * @returns {Promise<Object>} Execution summary.
+   */
+  async execute(waves) {
+    const startTime = Date.now();
+    const results = [];
+
+    for (let i = 0; i < waves.length; i++) {
+      const wave = waves[i];
+      this.emit("wave-start", { waveIndex: i, taskCount: wave.length });
+
+      const waveResults = await this._runWave(wave);
+      results.push({ waveIndex: i, results: waveResults });
+
+      this.emit("wave-end", {
+        waveIndex: i,
+        success: waveResults.every((r) => r.success),
+      });
+    }
+
+    return {
+      success: results.every((w) => w.results.every((r) => r.success)),
+      waves: results,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  //  Dependency Graph
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build an adjacency list from tasks.
+   *
+   * @param {Array<Object>} tasks - Tasks with optional `dependsOn`.
+   * @returns {Map<string, string[]>} adjacency list (taskId -> dependants).
+   */
+  _buildDependencyGraph(tasks) {
+    const graph = new Map();
+
+    for (const t of tasks) {
+      if (!graph.has(t.id)) graph.set(t.id, []);
+    }
+
+    for (const t of tasks) {
+      const deps = t.dependsOn || [];
+      for (const dep of deps) {
+        if (!graph.has(dep)) graph.set(dep, []);
+        graph.get(dep).push(t.id);
+      }
+    }
+
+    return graph;
+  }
+
+  /**
+   * Topological sort via Kahn's algorithm, returning layers (waves).
+   *
+   * @param {Map<string, string[]>} graph
+   * @param {Array<Object>} tasks
+   * @returns {Array<Array<Object>>} Waves of tasks.
+   */
+  _topologicalSort(graph, tasks) {
+    const taskMap = new Map(tasks.map((t) => [t.id, t]));
+
+    // Compute in-degree
+    const inDegree = new Map();
+    for (const t of tasks) {
+      inDegree.set(t.id, (t.dependsOn || []).length);
+    }
+
+    // Seed queue with zero in-degree
+    let queue = [];
+    for (const [id, deg] of inDegree) {
+      if (deg === 0) queue.push(id);
+    }
+
+    const waves = [];
+
+    while (queue.length > 0) {
+      const wave = queue.map((id) => taskMap.get(id)).filter(Boolean);
+      waves.push(wave);
+
+      const nextQueue = [];
+
+      for (const id of queue) {
+        const dependants = graph.get(id) || [];
+        for (const dep of dependants) {
+          inDegree.set(dep, (inDegree.get(dep) || 1) - 1);
+          if (inDegree.get(dep) === 0) {
+            nextQueue.push(dep);
+          }
+        }
+      }
+
+      queue = nextQueue;
+    }
+
+    return waves;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Wave Runner
+  // -----------------------------------------------------------------------
+
+  /**
+   * Run a single wave in parallel (respecting maxParallel).
+   * @private
+   */
+  async _runWave(wave) {
+    const results = [];
+    const chunks = [];
+
+    for (let i = 0; i < wave.length; i += this.maxParallel) {
+      chunks.push(wave.slice(i, i + this.maxParallel));
+    }
+
+    for (const chunk of chunks) {
+      const settled = await Promise.allSettled(
+        chunk.map((task) => this._runTask(task)),
+      );
+
+      for (let i = 0; i < settled.length; i++) {
+        const task = chunk[i];
+        const s = settled[i];
+
+        const result =
+          s.status === "fulfilled"
+            ? { taskId: task.id, success: s.value.success, ...s.value }
+            : {
+                taskId: task.id,
+                success: false,
+                error: s.reason?.message || "Unknown",
+              };
+
+        results.push(result);
+        this.emit("task-complete", result);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Run a single task with timeout.
+   * @private
+   */
+  async _runTask(task) {
+    if (!this.taskRunner) {
+      return { success: true, output: "No runner configured (dry run)" };
+    }
+
+    return Promise.race([
+      this.taskRunner(task),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`Task ${task.id} timed out`)),
+          this.taskTimeout,
+        ),
+      ),
+    ]);
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { WaveExecutor };

package/.merlin-core/core/health-check/health-engine.js

@@ -0,0 +1,415 @@
+/**
+ * Health Engine -- System Health Monitoring
+ *
+ * Runs diagnostic checks across all Merlin subsystems:
+ * configuration, agents, skills, MCP servers, and filesystem.
+ *
+ * Supports custom check registration for project-specific diagnostics.
+ *
+ * @module core/health-check/health-engine
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Health status enum
+ * @enum {string}
+ */
+const HealthStatus = {
+  HEALTHY: "HEALTHY",
+  DEGRADED: "DEGRADED",
+  UNHEALTHY: "UNHEALTHY",
+};
+
+class HealthEngine {
+  /**
+   * @param {string} projectRoot - Absolute path to the project root
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+
+    /** @type {Map<string, function>} */
+    this._customChecks = new Map();
+  }
+
+  /**
+   * Run all health checks and return a summary.
+   *
+   * @returns {Promise<{status: string, checks: Array<object>, formatted: string, timestamp: number}>}
+   */
+  async runCheck() {
+    const checks = [];
+    const builtInChecks = [
+      () => this._checkConfigSystem(),
+      () => this._checkAgentSystem(),
+      () => this._checkSkillSystem(),
+      () => this._checkMCPSystem(),
+      () => this._checkFilesystem(),
+    ];
+
+    // Run built-in checks
+    for (const checkFn of builtInChecks) {
+      const result = await this._runSingle(checkFn);
+      checks.push(result);
+    }
+
+    // Run custom checks
+    for (const [name, checkFn] of this._customChecks) {
+      const result = await this._runSingle(checkFn, name);
+      checks.push(result);
+    }
+
+    // Derive overall status
+    const hasUnhealthy = checks.some(
+      (c) => c.status === HealthStatus.UNHEALTHY,
+    );
+    const hasDegraded = checks.some((c) => c.status === HealthStatus.DEGRADED);
+
+    let status;
+    if (hasUnhealthy) {
+      status = HealthStatus.UNHEALTHY;
+    } else if (hasDegraded) {
+      status = HealthStatus.DEGRADED;
+    } else {
+      status = HealthStatus.HEALTHY;
+    }
+
+    const formatted = this._formatReport(status, checks);
+
+    return { status, checks, formatted, timestamp: Date.now() };
+  }
+
+  /**
+   * Register a custom health check.
+   *
+   * @param {string} name - Check name
+   * @param {function(): Promise<{name: string, status: string, message: string}>} checkFn - Check function
+   */
+  registerCheck(name, checkFn) {
+    this._customChecks.set(name, checkFn);
+  }
+
+  /**
+   * Get a formatted health report (runs all checks).
+   *
+   * @returns {Promise<string>}
+   */
+  async getReport() {
+    const result = await this.runCheck();
+    return result.formatted;
+  }
+
+  /**
+   * Check configuration system health.
+   *
+   * @returns {{name: string, status: string, message: string}}
+   * @private
+   */
+  _checkConfigSystem() {
+    const name = "config-system";
+    const configDir = path.join(this.projectRoot, ".merlin-core", "config");
+    const constitutionFile = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "CONSTITUTION.md",
+    );
+    const merlinYaml = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "config",
+      "merlin.yaml",
+    );
+
+    if (!fs.existsSync(configDir)) {
+      return {
+        name,
+        status: HealthStatus.UNHEALTHY,
+        message: "Config directory not found (.merlin-core/config/)",
+      };
+    }
+
+    if (!fs.existsSync(constitutionFile)) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "CONSTITUTION.md not found",
+      };
+    }
+
+    if (!fs.existsSync(merlinYaml)) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "merlin.yaml not found in config/",
+      };
+    }
+
+    return {
+      name,
+      status: HealthStatus.HEALTHY,
+      message: "Configuration files present",
+    };
+  }
+
+  /**
+   * Check agent system health.
+   *
+   * @returns {{name: string, status: string, message: string}}
+   * @private
+   */
+  _checkAgentSystem() {
+    const name = "agent-system";
+    const agentsDir = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "development",
+      "agents",
+    );
+
+    if (!fs.existsSync(agentsDir)) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "Agents directory not found",
+      };
+    }
+
+    try {
+      const agents = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md"));
+      if (agents.length === 0) {
+        return {
+          name,
+          status: HealthStatus.DEGRADED,
+          message: "No agent definitions found",
+        };
+      }
+      return {
+        name,
+        status: HealthStatus.HEALTHY,
+        message: `${agents.length} agent(s) discovered`,
+      };
+    } catch {
+      return {
+        name,
+        status: HealthStatus.UNHEALTHY,
+        message: "Cannot read agents directory",
+      };
+    }
+  }
+
+  /**
+   * Check skill system health.
+   *
+   * @returns {{name: string, status: string, message: string}}
+   * @private
+   */
+  _checkSkillSystem() {
+    const name = "skill-system";
+    const generalDir = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "skills",
+      "general",
+    );
+    const domainDir = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "skills",
+      "domain",
+    );
+
+    let skillCount = 0;
+
+    try {
+      if (fs.existsSync(generalDir)) {
+        skillCount += fs.readdirSync(generalDir).filter((f) => {
+          return fs.statSync(path.join(generalDir, f)).isDirectory();
+        }).length;
+      }
+      if (fs.existsSync(domainDir)) {
+        skillCount += fs.readdirSync(domainDir).filter((f) => {
+          return fs.statSync(path.join(domainDir, f)).isDirectory();
+        }).length;
+      }
+    } catch {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "Error reading skills directories",
+      };
+    }
+
+    if (skillCount === 0) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "No skills discovered",
+      };
+    }
+
+    return {
+      name,
+      status: HealthStatus.HEALTHY,
+      message: `${skillCount} skill(s) discovered`,
+    };
+  }
+
+  /**
+   * Check MCP system health.
+   *
+   * @returns {{name: string, status: string, message: string}}
+   * @private
+   */
+  _checkMCPSystem() {
+    const name = "mcp-system";
+    const mcpFile = path.join(this.projectRoot, ".mcp.json");
+    const claudeMcpFile = path.join(this.projectRoot, ".claude", "mcp.json");
+
+    const hasMcpJson = fs.existsSync(mcpFile);
+    const hasClaudeMcp = fs.existsSync(claudeMcpFile);
+
+    if (!hasMcpJson && !hasClaudeMcp) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "No MCP configuration found (.mcp.json or .claude/mcp.json)",
+      };
+    }
+
+    let serverCount = 0;
+    try {
+      if (hasMcpJson) {
+        const content = JSON.parse(fs.readFileSync(mcpFile, "utf8"));
+        const servers = content.mcpServers || content.servers || {};
+        serverCount += Object.keys(servers).length;
+      }
+      if (hasClaudeMcp) {
+        const content = JSON.parse(fs.readFileSync(claudeMcpFile, "utf8"));
+        const servers = content.mcpServers || content.servers || {};
+        serverCount += Object.keys(servers).length;
+      }
+    } catch {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "MCP config files found but could not be parsed",
+      };
+    }
+
+    if (serverCount === 0) {
+      return {
+        name,
+        status: HealthStatus.DEGRADED,
+        message: "MCP config found but no servers defined",
+      };
+    }
+
+    return {
+      name,
+      status: HealthStatus.HEALTHY,
+      message: `${serverCount} MCP server(s) configured`,
+    };
+  }
+
+  /**
+   * Check filesystem health (locks directory writable, tmp accessible).
+   *
+   * @returns {{name: string, status: string, message: string}}
+   * @private
+   */
+  _checkFilesystem() {
+    const name = "filesystem";
+    const runtimeDir = path.join(this.projectRoot, ".merlin");
+
+    // Check that the runtime directory is writable (or can be created)
+    try {
+      if (!fs.existsSync(runtimeDir)) {
+        fs.mkdirSync(runtimeDir, { recursive: true });
+      }
+
+      // Write a test file to verify writability
+      const testFile = path.join(runtimeDir, ".health-check-probe");
+      fs.writeFileSync(testFile, `health-check ${Date.now()}`, "utf8");
+      fs.unlinkSync(testFile);
+
+      return {
+        name,
+        status: HealthStatus.HEALTHY,
+        message: "Runtime directory writable",
+      };
+    } catch {
+      return {
+        name,
+        status: HealthStatus.UNHEALTHY,
+        message: "Runtime directory (.merlin/) is not writable",
+      };
+    }
+  }
+
+  /**
+   * Run a single check function with timing.
+   *
+   * @param {function} checkFn - Check function to run
+   * @param {string} [fallbackName] - Name to use if check throws
+   * @returns {Promise<{name: string, status: string, message: string, duration: number}>}
+   * @private
+   */
+  async _runSingle(checkFn, fallbackName = "unknown") {
+    const start = Date.now();
+    try {
+      const result = await checkFn();
+      return { ...result, duration: Date.now() - start };
+    } catch (err) {
+      return {
+        name: fallbackName,
+        status: HealthStatus.UNHEALTHY,
+        message: `Check threw an error: ${err.message}`,
+        duration: Date.now() - start,
+      };
+    }
+  }
+
+  /**
+   * Format a health report for console output.
+   *
+   * @param {string} overallStatus - Overall health status
+   * @param {Array<object>} checks - Individual check results
+   * @returns {string}
+   * @private
+   */
+  _formatReport(overallStatus, checks) {
+    const statusIcon = {
+      [HealthStatus.HEALTHY]: "[OK]",
+      [HealthStatus.DEGRADED]: "[!!]",
+      [HealthStatus.UNHEALTHY]: "[XX]",
+    };
+
+    const lines = [
+      "",
+      `Merlin Health Report`,
+      `${"=".repeat(40)}`,
+      `Overall: ${statusIcon[overallStatus] || "[??]"} ${overallStatus}`,
+      `Platform: ${os.platform()} ${os.arch()} (Node ${process.version})`,
+      `Project: ${this.projectRoot}`,
+      `Time: ${new Date().toISOString()}`,
+      "",
+      "Checks:",
+    ];
+
+    for (const check of checks) {
+      const icon = statusIcon[check.status] || "[??]";
+      const duration = check.duration != null ? ` (${check.duration}ms)` : "";
+      lines.push(`  ${icon} ${check.name}: ${check.message}${duration}`);
+    }
+
+    lines.push("");
+    return lines.join("\n");
+  }
+}
+
+module.exports = { HealthEngine, HealthStatus };