@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/build-orchestrator.js

@@ -0,0 +1,296 @@
+/**
+ * Build Orchestrator
+ *
+ * Orchestrates the overall build pipeline for Merlin projects.
+ * Takes a build plan (from the architect layer) and executes it
+ * through four sequential phases: Prepare, Implement, Verify, Finalize.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/build-orchestrator
+ * @version 3.0.0
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { EventEmitter } = require("events");
+const { AutonomousBuildLoop } = require("./autonomous-build-loop");
+const { AttemptJournal } = require("./attempt-journal");
+
+// ---------------------------------------------------------------------------
+//  Enums
+// ---------------------------------------------------------------------------
+
+const BuildPhase = {
+  PREPARE: "prepare",
+  IMPLEMENT: "implement",
+  VERIFY: "verify",
+  FINALIZE: "finalize",
+};
+
+// ---------------------------------------------------------------------------
+//  BuildOrchestrator
+// ---------------------------------------------------------------------------
+
+class BuildOrchestrator extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.rootPath]          Project root path.
+   * @param {number} [config.maxIterations=5]   Passed to AutonomousBuildLoop.
+   * @param {number} [config.timeoutMs=600000]  Global timeout.
+   * @param {boolean} [config.runLint=true]     Run lint during verify.
+   * @param {boolean} [config.runTests=true]    Run tests during verify.
+   * @param {boolean} [config.runTypecheck=false] Run typecheck during verify.
+   */
+  constructor(config = {}) {
+    super();
+    // v3.0.0 — Shared AttemptJournal across build loops
+    this._attemptJournal =
+      config.attemptJournal || new AttemptJournal({ debug: config.debug });
+    this.config = {
+      rootPath: config.rootPath || process.cwd(),
+      maxIterations: config.maxIterations || 3,
+      timeoutMs: config.timeoutMs || 600000,
+      runLint: config.runLint !== false,
+      runTests: config.runTests !== false,
+      runTypecheck: config.runTypecheck || false,
+      ...config,
+    };
+    this.activeBuilds = new Map();
+  }
+
+  // -----------------------------------------------------------------------
+  //  Main Pipeline
+  // -----------------------------------------------------------------------
+
+  /**
+   * Execute the full build pipeline for a plan.
+   *
+   * @param {Object} plan - Build plan from architect.
+   * @param {string} plan.id - Unique plan identifier.
+   * @param {Array}  plan.tasks - Array of task descriptors.
+   * @param {Object} [options] - Runtime overrides.
+   * @returns {Promise<Object>} Build result.
+   */
+  async orchestrate(plan, options = {}) {
+    const merged = { ...this.config, ...options };
+    const startTime = Date.now();
+    const planId = plan.id || `plan-${Date.now()}`;
+
+    if (this.activeBuilds.has(planId)) {
+      throw new Error(`Build already in progress for plan ${planId}`);
+    }
+
+    const ctx = {
+      planId,
+      plan,
+      config: merged,
+      startTime,
+      phases: {},
+      errors: [],
+      result: null,
+    };
+
+    this.activeBuilds.set(planId, ctx);
+
+    try {
+      await this._runPhase(ctx, BuildPhase.PREPARE, () => this._prepare(ctx));
+      await this._runPhase(ctx, BuildPhase.IMPLEMENT, () =>
+        this._implement(ctx),
+      );
+      await this._runPhase(ctx, BuildPhase.VERIFY, () => this._verify(ctx));
+      await this._runPhase(ctx, BuildPhase.FINALIZE, () => this._finalize(ctx));
+
+      return {
+        success: true,
+        planId,
+        duration: Date.now() - startTime,
+        phases: ctx.phases,
+      };
+    } catch (err) {
+      ctx.errors.push(err);
+      return {
+        success: false,
+        planId,
+        error: err.message,
+        duration: Date.now() - startTime,
+        phases: ctx.phases,
+      };
+    } finally {
+      this.activeBuilds.delete(planId);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  //  Phase Runner
+  // -----------------------------------------------------------------------
+
+  /**
+   * Execute a single phase with event emission and timing.
+   * @private
+   */
+  async _runPhase(ctx, phaseName, fn) {
+    const phaseStart = Date.now();
+    this.emit("phase-start", { planId: ctx.planId, phase: phaseName });
+
+    try {
+      const result = await fn();
+      ctx.phases[phaseName] = {
+        status: "completed",
+        duration: Date.now() - phaseStart,
+        result,
+      };
+      this.emit("phase-end", {
+        planId: ctx.planId,
+        phase: phaseName,
+        status: "completed",
+      });
+      return result;
+    } catch (err) {
+      ctx.phases[phaseName] = {
+        status: "failed",
+        duration: Date.now() - phaseStart,
+        error: err.message,
+      };
+      this.emit("phase-end", {
+        planId: ctx.planId,
+        phase: phaseName,
+        status: "failed",
+      });
+      throw err;
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  //  Phase Implementations
+  // -----------------------------------------------------------------------
+
+  /**
+   * PREPARE: Validate prerequisites and create workspace.
+   * @private
+   */
+  async _prepare(ctx) {
+    const rootPath = ctx.config.rootPath;
+
+    // Ensure project root exists
+    if (!fs.existsSync(rootPath)) {
+      throw new Error(`Project root does not exist: ${rootPath}`);
+    }
+
+    // Ensure .merlin runtime directory exists
+    const merlinDir = path.join(rootPath, ".merlin");
+    if (!fs.existsSync(merlinDir)) {
+      fs.mkdirSync(merlinDir, { recursive: true });
+    }
+
+    // Validate plan has tasks
+    if (!ctx.plan.tasks || ctx.plan.tasks.length === 0) {
+      throw new Error("Build plan contains no tasks");
+    }
+
+    return {
+      rootPath,
+      taskCount: ctx.plan.tasks.length,
+      merlinDir,
+    };
+  }
+
+  /**
+   * IMPLEMENT: Dispatch each task to the AutonomousBuildLoop.
+   * @private
+   */
+  async _implement(ctx) {
+    const results = [];
+
+    for (const task of ctx.plan.tasks) {
+      const loop = new AutonomousBuildLoop(ctx.config.rootPath, {
+        maxIterations: ctx.config.maxIterations,
+        timeoutMs: ctx.config.timeoutMs,
+        runTests: ctx.config.runTests,
+        runLint: ctx.config.runLint,
+        runTypecheck: ctx.config.runTypecheck,
+      });
+
+      const result = await loop.run(task);
+      results.push({ taskId: task.id, ...result });
+
+      if (!result.passed) {
+        throw new Error(`Task ${task.id} failed: ${result.error}`);
+      }
+    }
+
+    ctx.result = results;
+    return { tasksCompleted: results.length };
+  }
+
+  /**
+   * VERIFY: Run the full quality gate one final time.
+   * @private
+   */
+  async _verify(ctx) {
+    const loop = new AutonomousBuildLoop(ctx.config.rootPath, {
+      maxIterations: 1,
+      timeoutMs: ctx.config.timeoutMs,
+      runTests: ctx.config.runTests,
+      runLint: ctx.config.runLint,
+      runTypecheck: ctx.config.runTypecheck,
+    });
+
+    const checks = await loop._runQualityChecks();
+
+    if (!checks.passed) {
+      const failures = checks.results
+        .filter((r) => !r.passed)
+        .map((r) => r.check);
+      throw new Error(`Final verification failed: ${failures.join(", ")}`);
+    }
+
+    return { verified: true, checks: checks.results.length };
+  }
+
+  /**
+   * FINALIZE: Clean up and record results.
+   * @private
+   */
+  async _finalize(ctx) {
+    const merlinDir = path.join(ctx.config.rootPath, ".merlin");
+    const reportPath = path.join(merlinDir, `build-report-${ctx.planId}.json`);
+
+    const report = {
+      planId: ctx.planId,
+      completedAt: new Date().toISOString(),
+      duration: Date.now() - ctx.startTime,
+      phases: ctx.phases,
+      taskResults: ctx.result,
+    };
+
+    if (!fs.existsSync(merlinDir)) {
+      fs.mkdirSync(merlinDir, { recursive: true });
+    }
+
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf-8");
+
+    return { reportPath };
+  }
+
+  // -----------------------------------------------------------------------
+  //  Utility
+  // -----------------------------------------------------------------------
+
+  /**
+   * @returns {Array} Currently active builds.
+   */
+  getActiveBuilds() {
+    return Array.from(this.activeBuilds.entries()).map(([planId, ctx]) => ({
+      planId,
+      phase: Object.keys(ctx.phases).pop() || "init",
+      duration: Date.now() - ctx.startTime,
+    }));
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { BuildOrchestrator, BuildPhase };

package/.merlin-core/core/execution/build-state-manager.js

@@ -0,0 +1,196 @@
+/**
+ * Build State Manager
+ *
+ * Manages build state with checkpoints for recovery. State is persisted
+ * to `.merlin/build-state/` so builds can be resumed after interruptions.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/build-state-manager
+ * @version 3.0.0
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ---------------------------------------------------------------------------
+//  BuildStateManager
+// ---------------------------------------------------------------------------
+
+class BuildStateManager {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.rootPath]   Project root.
+   * @param {string} [config.stateDir]   Override state directory name.
+   */
+  constructor(config = {}) {
+    this.rootPath = config.rootPath || process.cwd();
+    this.stateDir = path.join(
+      this.rootPath,
+      ".merlin",
+      config.stateDir || "build-state",
+    );
+    this._state = this._defaultState();
+  }
+
+  // -----------------------------------------------------------------------
+  //  Internal helpers
+  // -----------------------------------------------------------------------
+
+  /** @returns {Object} A blank state object. */
+  _defaultState() {
+    return {
+      phase: null,
+      progress: 0,
+      errors: [],
+      startedAt: null,
+      lastCheckpoint: null,
+      completedSubtasks: [],
+      metadata: {},
+    };
+  }
+
+  /** Ensure the state directory exists. */
+  _ensureDir() {
+    if (!fs.existsSync(this.stateDir)) {
+      fs.mkdirSync(this.stateDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Build a sanitised filename for a checkpoint label.
+   * @param {string} label
+   * @returns {string}
+   */
+  _checkpointPath(label) {
+    const safe = label.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(this.stateDir, `${safe}.json`);
+  }
+
+  // -----------------------------------------------------------------------
+  //  Checkpoint CRUD
+  // -----------------------------------------------------------------------
+
+  /**
+   * Save current state as a named checkpoint to disk.
+   *
+   * @param {string} label - Unique checkpoint label.
+   * @param {Object} [state] - Optional state override; defaults to current.
+   * @returns {Object} The persisted checkpoint object.
+   */
+  createCheckpoint(label, state) {
+    this._ensureDir();
+
+    const checkpoint = {
+      label,
+      timestamp: new Date().toISOString(),
+      id: crypto.randomBytes(6).toString("hex"),
+      state: state || { ...this._state },
+    };
+
+    fs.writeFileSync(
+      this._checkpointPath(label),
+      JSON.stringify(checkpoint, null, 2),
+      "utf-8",
+    );
+
+    this._state.lastCheckpoint = label;
+    return checkpoint;
+  }
+
+  /**
+   * Restore state from a named checkpoint.
+   *
+   * @param {string} label - Checkpoint label to restore.
+   * @returns {Object} The restored state.
+   * @throws {Error} If checkpoint does not exist.
+   */
+  restoreCheckpoint(label) {
+    const filePath = this._checkpointPath(label);
+
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Checkpoint not found: ${label}`);
+    }
+
+    const content = fs.readFileSync(filePath, "utf-8");
+    const checkpoint = JSON.parse(content);
+    this._state = { ...checkpoint.state };
+    return this._state;
+  }
+
+  /**
+   * List all available checkpoints, sorted by timestamp descending.
+   *
+   * @returns {Array<Object>} Array of {label, timestamp, id}.
+   */
+  listCheckpoints() {
+    if (!fs.existsSync(this.stateDir)) {
+      return [];
+    }
+
+    const files = fs
+      .readdirSync(this.stateDir)
+      .filter((f) => f.endsWith(".json"));
+
+    return files
+      .map((f) => {
+        try {
+          const content = fs.readFileSync(path.join(this.stateDir, f), "utf-8");
+          const cp = JSON.parse(content);
+          return { label: cp.label, timestamp: cp.timestamp, id: cp.id };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+  }
+
+  /**
+   * Delete a checkpoint by label.
+   *
+   * @param {string} label - Checkpoint label.
+   * @returns {boolean} True if deleted, false if not found.
+   */
+  deleteCheckpoint(label) {
+    const filePath = this._checkpointPath(label);
+
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+
+    fs.unlinkSync(filePath);
+    return true;
+  }
+
+  // -----------------------------------------------------------------------
+  //  State accessors
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get the current in-memory state.
+   *
+   * @returns {Object} Current state.
+   */
+  getCurrentState() {
+    return { ...this._state };
+  }
+
+  /**
+   * Merge partial updates into the current state.
+   *
+   * @param {Object} updates - Key/value pairs to merge.
+   * @returns {Object} Updated state.
+   */
+  updateState(updates) {
+    this._state = { ...this._state, ...updates };
+    return { ...this._state };
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { BuildStateManager };

package/.merlin-core/core/execution/context-injector.js

@@ -0,0 +1,204 @@
+/**
+ * Context Injector
+ *
+ * Injects context into agent invocations from the Alkimia engine.
+ * Enriches tasks with project knowledge, relevant files, and patterns
+ * so that agents have the best possible context for execution.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/context-injector
+ * @version 3.0.0
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+//  ContextInjector
+// ---------------------------------------------------------------------------
+
+class ContextInjector {
+  /**
+   * @param {Object} [config]
+   * @param {string}   [config.rootPath]      Project root.
+   * @param {number}   [config.tokenBudget=4000] Max tokens for injected context.
+   * @param {number}   [config.charsPerToken=4]  Approximate chars per token.
+   * @param {Function} [config.alkimiaQuery]  Optional Alkimia engine query fn.
+   */
+  constructor(config = {}) {
+    this.rootPath = config.rootPath || process.cwd();
+    this.tokenBudget = config.tokenBudget || 4000;
+    this.charsPerToken = config.charsPerToken || 4;
+    this.alkimiaQuery = config.alkimiaQuery || null;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Inject context into a task for a specific agent.
+   *
+   * @param {string} agentId         - Target agent identifier.
+   * @param {Object} task            - Task descriptor (id, description, files, ...).
+   * @param {Object} [sessionContext] - Current session context (memory, decisions).
+   * @returns {Promise<Object>} Enriched task with `.injectedContext` property.
+   */
+  async inject(agentId, task, sessionContext = {}) {
+    // 1. Build Alkimia-compatible input
+    const alkimiaInput = this._buildAlkimiaInput(agentId, task);
+
+    // 2. Query Alkimia (if available)
+    let alkimiaOutput = {};
+    if (this.alkimiaQuery) {
+      try {
+        alkimiaOutput = await this.alkimiaQuery(alkimiaInput);
+      } catch {
+        // Alkimia unavailable - continue with local context
+      }
+    }
+
+    // 3. Build local context
+    const localContext = await this._buildLocalContext(task);
+
+    // 4. Merge everything into the task
+    const merged = this._formatInjection(
+      { ...alkimiaOutput, ...localContext },
+      task,
+      sessionContext,
+    );
+
+    // 5. Trim to token budget
+    const maxChars = this.tokenBudget * this.charsPerToken;
+    const trimmed =
+      merged.length > maxChars
+        ? merged.substring(0, maxChars - 40) + "\n[Context truncated]"
+        : merged;
+
+    return {
+      ...task,
+      injectedContext: trimmed,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  //  Alkimia bridge
+  // -----------------------------------------------------------------------
+
+  /**
+   * Map a task to the Alkimia engine's expected input format.
+   *
+   * @param {string} agentId
+   * @param {Object} task
+   * @returns {Object} Alkimia query payload.
+   */
+  _buildAlkimiaInput(agentId, task) {
+    return {
+      agent: agentId,
+      query: task.description || task.id,
+      files: task.files || [],
+      tags: task.tags || [],
+      layers: ["project", "memory", "patterns"],
+    };
+  }
+
+  /**
+   * Merge Alkimia output and session context into a formatted string
+   * that can be prepended to an agent prompt.
+   *
+   * @param {Object} alkimiaOutput
+   * @param {Object} task
+   * @param {Object} sessionContext
+   * @returns {string} Formatted markdown context block.
+   */
+  _formatInjection(alkimiaOutput, task, sessionContext) {
+    let out = "## Injected Context\n\n";
+
+    // Task basics
+    out += `### Task\n- **ID:** ${task.id}\n- **Description:** ${task.description || "N/A"}\n\n`;
+
+    // Files
+    if (task.files && task.files.length > 0) {
+      out += "### Relevant Files\n";
+      for (const f of task.files) {
+        const exists = fs.existsSync(path.join(this.rootPath, f));
+        out += `- \`${f}\` ${exists ? "(exists)" : "(new)"}\n`;
+      }
+      out += "\n";
+    }
+
+    // Alkimia patterns
+    if (alkimiaOutput.patterns && alkimiaOutput.patterns.length > 0) {
+      out += "### Patterns\n";
+      for (const p of alkimiaOutput.patterns.slice(0, 5)) {
+        out += `- ${typeof p === "string" ? p : p.name}\n`;
+      }
+      out += "\n";
+    }
+
+    // Session context
+    if (sessionContext.decisions && sessionContext.decisions.length > 0) {
+      out += "### Recent Decisions\n";
+      for (const d of sessionContext.decisions.slice(0, 3)) {
+        out += `- ${d.decision || d}\n`;
+      }
+      out += "\n";
+    }
+
+    if (sessionContext.gotchas && sessionContext.gotchas.length > 0) {
+      out += "### Gotchas\n";
+      for (const g of sessionContext.gotchas.slice(0, 5)) {
+        out += `- **${g.title || "Warning"}**: ${g.description || g.workaround || ""}\n`;
+      }
+      out += "\n";
+    }
+
+    return out;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Local context builder
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build local project context from files on disk.
+   * @private
+   */
+  async _buildLocalContext(_task) {
+    const context = { patterns: [], conventions: [] };
+
+    try {
+      // Try reading Merlin codebase map
+      const mapPath = path.join(this.rootPath, ".merlin", "codebase-map.json");
+      if (fs.existsSync(mapPath)) {
+        const map = JSON.parse(fs.readFileSync(mapPath, "utf-8"));
+        context.patterns = map.patterns || [];
+      }
+
+      // Detect basic conventions
+      if (fs.existsSync(path.join(this.rootPath, "tsconfig.json"))) {
+        context.conventions.push("TypeScript project");
+      }
+      if (
+        fs.existsSync(path.join(this.rootPath, ".eslintrc.js")) ||
+        fs.existsSync(path.join(this.rootPath, ".eslintrc.json"))
+      ) {
+        context.conventions.push("Uses ESLint");
+      }
+      if (fs.existsSync(path.join(this.rootPath, ".prettierrc"))) {
+        context.conventions.push("Uses Prettier");
+      }
+    } catch {
+      // Non-critical
+    }
+
+    return context;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ContextInjector };