@caoscompanybr/merlin 3.5.0

package/bin/fleet-patch-hooks.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# fleet-patch-hooks.sh — One-time patch for V3 fleet: add missing hooks + cleanup debris
+#
+# Usage: bash bin/fleet-patch-hooks.sh [--yes]
+#
+# What it does:
+#   1. Finds all V3 projects (have .merlin-core/core-config.yaml with version 3.0.0)
+#   2. Copies .claude/hooks/ from Gestao Merlin source
+#   3. Merges hook registrations into settings.local.json
+#   4. Rebuilds INDEX.json
+#   5. Removes old backup directories (.claude-backup-*, .merlin-core-backup-*)
+#   6. Removes empty .agents/ directories
+
+set -euo pipefail
+
+MERLIN_SOURCE="$(cd "$(dirname "$0")/.." && pwd)"
+DEVOPS_DIR="$(dirname "$MERLIN_SOURCE")"
+AUTO_CONFIRM="${1:-}"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+
+PATCHED=0
+SKIPPED=0
+
+echo -e "${CYAN}Fleet Patch: Hooks + Cleanup for V3 Projects${NC}"
+echo -e "Source: $MERLIN_SOURCE"
+echo -e "Scanning: $DEVOPS_DIR"
+echo ""
+
+for project_dir in "$DEVOPS_DIR"/*/; do
+  [ ! -d "$project_dir" ] && continue
+
+  # Skip source and any projects you want excluded from the fleet scan
+  project_name="$(basename "$project_dir")"
+  [ "$project_name" = "Gestao Merlin" ] && continue
+  # Add additional project basenames to skip below, e.g.:
+  # [ "$project_name" = "ExcludedProject" ] && continue
+
+  # Only V3 projects (have core-config.yaml with version 3.0.0)
+  config="$project_dir.merlin-core/core-config.yaml"
+  [ ! -f "$config" ] && continue
+  grep -q "version.*3\.0\.0" "$config" 2>/dev/null || continue
+
+  echo -e "${CYAN}━━━ $project_name ━━━${NC}"
+
+  # 1. Sync hooks (backup existing hooks that differ before overwriting)
+  if [ -d "$MERLIN_SOURCE/.claude/hooks" ]; then
+    mkdir -p "$project_dir.claude/hooks"
+    HOOKS_UPDATED=0
+    for hook_file in "$MERLIN_SOURCE/.claude/hooks/"*.js; do
+      [ -f "$hook_file" ] || continue
+      hook_name="$(basename "$hook_file")"
+      target_hook="$project_dir.claude/hooks/$hook_name"
+      # If target exists and differs, back it up first
+      if [ -f "$target_hook" ] && ! diff -q "$hook_file" "$target_hook" >/dev/null 2>&1; then
+        cp "$target_hook" "$target_hook.pre-patch"
+        echo -e "  ${YELLOW}⚠${NC} Backed up differing hook: $hook_name → $hook_name.pre-patch"
+      fi
+      cp "$hook_file" "$target_hook"
+      HOOKS_UPDATED=$((HOOKS_UPDATED + 1))
+    done
+    echo -e "  ${GREEN}✓${NC} $HOOKS_UPDATED hooks synced"
+  fi
+
+  # 2. Merge hook registrations into settings.local.json
+  if [ -f "$MERLIN_SOURCE/.claude/settings.local.json" ]; then
+    if [ -f "$project_dir.claude/settings.local.json" ]; then
+      node -e "
+        const fs = require('fs');
+        const [srcPath, tgtPath] = process.argv.slice(1);
+        const src = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
+        const tgt = JSON.parse(fs.readFileSync(tgtPath, 'utf8'));
+        if (src.hooks) {
+          if (!tgt.hooks) tgt.hooks = {};
+          for (const [event, matchers] of Object.entries(src.hooks)) {
+            if (!tgt.hooks[event]) { tgt.hooks[event] = matchers; }
+            else {
+              for (const sm of matchers) {
+                const tm = tgt.hooks[event].find(m => m.matcher === sm.matcher);
+                if (tm) {
+                  const existing = new Set(tm.hooks.map(h => h.command));
+                  for (const h of sm.hooks) { if (!existing.has(h.command)) tm.hooks.push(h); }
+                } else { tgt.hooks[event].push(sm); }
+              }
+            }
+          }
+        }
+        fs.writeFileSync(tgtPath, JSON.stringify(tgt, null, 2) + '\n');
+      " "$MERLIN_SOURCE/.claude/settings.local.json" "$project_dir.claude/settings.local.json" \
+      2>/dev/null && echo -e "  ${GREEN}✓${NC} Hook registrations merged" || echo -e "  ${YELLOW}⚠${NC} Hook merge failed"
+    else
+      node -e "
+        const fs = require('fs');
+        const src = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+        const tgt = src.hooks ? { hooks: src.hooks } : {};
+        fs.writeFileSync(process.argv[2], JSON.stringify(tgt, null, 2) + '\n');
+      " "$MERLIN_SOURCE/.claude/settings.local.json" "$project_dir.claude/settings.local.json" \
+      2>/dev/null && echo -e "  ${GREEN}✓${NC} settings.local.json created" || echo -e "  ${YELLOW}⚠${NC} settings.local.json creation failed"
+    fi
+  fi
+
+  # 3. Rebuild INDEX.json
+  if [ -f "$project_dir.merlin-core/tools/merlin-tools.js" ]; then
+    ENTRIES=$(node "$project_dir.merlin-core/tools/merlin-tools.js" index 2>/dev/null | node -e "
+      let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
+        try { console.log(JSON.parse(d).entries); } catch { console.log('?'); }
+      });
+    " 2>/dev/null || echo "?")
+    echo -e "  ${GREEN}✓${NC} INDEX.json rebuilt ($ENTRIES entries)"
+  fi
+
+  # 4. Remove old backup directories
+  BACKUP_COUNT=0
+  while IFS= read -r dir; do
+    [ -z "$dir" ] && continue
+    if [ "$AUTO_CONFIRM" = "--yes" ]; then
+      rm -rf "$dir"
+      BACKUP_COUNT=$((BACKUP_COUNT + 1))
+    fi
+  done < <(find "$project_dir" -maxdepth 1 \( -name ".claude-backup-*" -o -name ".merlin-core-backup-*" \) -type d 2>/dev/null)
+  if [ "$BACKUP_COUNT" -gt 0 ]; then
+    echo -e "  ${GREEN}✓${NC} Removed $BACKUP_COUNT old backup(s)"
+  elif [ "$AUTO_CONFIRM" != "--yes" ]; then
+    HAVE_BACKUPS=$(find "$project_dir" -maxdepth 1 \( -name ".claude-backup-*" -o -name ".merlin-core-backup-*" \) -type d 2>/dev/null | head -1)
+    [ -n "$HAVE_BACKUPS" ] && echo -e "  ${YELLOW}⚠${NC} Old backups found (use --yes to remove)"
+  fi
+
+  # 5. Remove empty .agents/ directories
+  if [ -d "$project_dir.agents" ]; then
+    if [ -z "$(find "$project_dir.agents" -type f 2>/dev/null)" ]; then
+      rm -rf "$project_dir.agents"
+      echo -e "  ${GREEN}✓${NC} Removed empty .agents/"
+    fi
+  fi
+
+  PATCHED=$((PATCHED + 1))
+  echo ""
+done
+
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}Fleet patch complete: $PATCHED projects patched${NC}"
+if [ "$AUTO_CONFIRM" != "--yes" ]; then
+  echo -e "${YELLOW}Note: Old backups were NOT removed. Re-run with --yes to clean.${NC}"
+fi

package/bin/fleet-patch-v3-fixes.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+# fleet-patch-v3-fixes.sh — Apply c923ddf V3 review fixes to all fleet projects
+#
+# Usage: bash bin/fleet-patch-v3-fixes.sh [--yes]
+#
+# What it does (9-file changeset):
+#   1. Deletes stale core/orchestration/command-mode-system.test.js
+#   2. Copies 7 corrected files from Gestao Merlin source
+#   3. Copies updated development/agents/README.md (14→15 agents)
+#
+# All changes are lint/import fixes — no functional changes to runtime behavior.
+
+set -euo pipefail
+
+MERLIN_SOURCE="$(cd "$(dirname "$0")/.." && pwd)"
+DEVOPS_DIR="$(dirname "$MERLIN_SOURCE")"
+AUTO_CONFIRM="${1:-}"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+
+# Files to copy from source .merlin-core/ to target .merlin-core/
+COPY_FILES=(
+  "core/integration.test.js"
+  "core/orchestration/skill-dispatcher.js"
+  "core/mcp/mcp-registry.test.js"
+  "mcp-servers/lsp-bridge/index.js"
+  "skills/general/blkskrn/scripts/canvas-manager.js"
+  "tools/commands/archive-thoughts.js"
+  "tools/commands/sync-bridges.js"
+  "development/agents/README.md"
+)
+
+# File to delete from target .merlin-core/
+DELETE_FILE="core/orchestration/command-mode-system.test.js"
+
+PATCHED=0
+SKIPPED=0
+ERRORS=0
+
+echo -e "${CYAN}Fleet Patch: V3 Review Fixes (c923ddf) for V3 Projects${NC}"
+echo -e "Source: $MERLIN_SOURCE"
+echo -e "Scanning: $DEVOPS_DIR"
+echo ""
+
+# Verify source files exist
+echo -e "${CYAN}Verifying source files...${NC}"
+for file in "${COPY_FILES[@]}"; do
+  if [ ! -f "$MERLIN_SOURCE/.merlin-core/$file" ]; then
+    echo -e "${RED}✗ Missing source: .merlin-core/$file${NC}"
+    echo -e "${RED}Aborting — source files incomplete.${NC}"
+    exit 1
+  fi
+done
+echo -e "${GREEN}✓ All 8 source files verified${NC}"
+echo ""
+
+for project_dir in "$DEVOPS_DIR"/*/; do
+  [ ! -d "$project_dir" ] && continue
+
+  project_name="$(basename "$project_dir")"
+
+  # Skip source and any projects you want excluded from the fleet scan
+  [ "$project_name" = "Gestao Merlin" ] && continue
+  # Add additional project basenames to skip below, e.g.:
+  # [ "$project_name" = "ExcludedProject" ] && continue
+
+  # Only V3 projects (have core-config.yaml with version 3.0.0)
+  config="$project_dir.merlin-core/core-config.yaml"
+  [ ! -f "$config" ] && continue
+  grep -q "version.*3\.0\.0" "$config" 2>/dev/null || continue
+
+  echo -e "${CYAN}━━━ $project_name ━━━${NC}"
+
+  mc_dir="$project_dir.merlin-core"
+  CHANGES=0
+
+  # 1. Delete stale test file
+  stale_file="$mc_dir/$DELETE_FILE"
+  if [ -f "$stale_file" ]; then
+    rm "$stale_file"
+    echo -e "  ${GREEN}✓${NC} Deleted stale: $DELETE_FILE"
+    CHANGES=$((CHANGES + 1))
+  else
+    echo -e "  ${YELLOW}—${NC} Already clean: $DELETE_FILE"
+  fi
+
+  # 2. Copy corrected files
+  COPIED=0
+  ALREADY_OK=0
+  for file in "${COPY_FILES[@]}"; do
+    src="$MERLIN_SOURCE/.merlin-core/$file"
+    tgt="$mc_dir/$file"
+
+    if [ ! -f "$tgt" ]; then
+      echo -e "  ${YELLOW}⚠${NC} Target missing (skipped): $file"
+      continue
+    fi
+
+    # Only copy if files differ
+    if diff -q "$src" "$tgt" >/dev/null 2>&1; then
+      ALREADY_OK=$((ALREADY_OK + 1))
+    else
+      cp "$src" "$tgt"
+      COPIED=$((COPIED + 1))
+    fi
+  done
+
+  if [ "$COPIED" -gt 0 ]; then
+    echo -e "  ${GREEN}✓${NC} $COPIED files updated"
+  fi
+  if [ "$ALREADY_OK" -gt 0 ]; then
+    echo -e "  ${YELLOW}—${NC} $ALREADY_OK files already up-to-date"
+  fi
+
+  CHANGES=$((CHANGES + COPIED))
+
+  if [ "$CHANGES" -gt 0 ]; then
+    PATCHED=$((PATCHED + 1))
+  else
+    SKIPPED=$((SKIPPED + 1))
+  fi
+
+  echo ""
+done
+
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}Fleet V3 fixes complete: $PATCHED patched, $SKIPPED already up-to-date, $ERRORS errors${NC}"

package/bin/merlin-init.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Merlin Init -- Project Initialization Wizard
+ *
+ * Sets up Merlin in a target project:
+ * - Verifies .merlin-core/ template directory exists
+ * - Creates .merlin/ runtime directory (gitignored)
+ * - Creates .mcp.json if missing
+ * - Creates .claude/CLAUDE.md if missing
+ * - Ensures .merlin/ is in .gitignore
+ * - Prints summary of created/skipped files
+ *
+ * @module bin/merlin-init
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Initialize Merlin in the target project directory.
+ *
+ * @param {string} targetDir - Absolute path to the project root
+ * @param {object} [options={}]
+ * @param {boolean} [options.force=false] - Overwrite existing files
+ */
+function initProject(targetDir, options = {}) {
+  const summary = { created: [], skipped: [], errors: [] };
+  const force = options.force || false;
+
+  console.log("");
+  console.log("Merlin -- The Mage of Management");
+  console.log("================================");
+  console.log(`Initializing in: ${targetDir}`);
+  console.log("");
+
+  // 1. Verify .merlin-core/ template exists
+  const merlinCoreDir = path.join(targetDir, ".merlin-core");
+  if (!fs.existsSync(merlinCoreDir)) {
+    console.log("[!!] .merlin-core/ directory not found.");
+    console.log(
+      "     This project does not appear to have the Merlin framework installed.",
+    );
+    console.log(
+      "     Ensure the .merlin-core/ template is present before running init.",
+    );
+    process.exit(1);
+  }
+
+  // 2. Create .merlin/ runtime directory
+  const runtimeDir = path.join(targetDir, ".merlin");
+  ensureDir(runtimeDir, summary);
+  ensureDir(path.join(runtimeDir, "locks"), summary);
+  ensureDir(path.join(runtimeDir, "sessions"), summary);
+  ensureDir(path.join(runtimeDir, "cache"), summary);
+  ensureDir(path.join(runtimeDir, "logs"), summary);
+
+  // 3. Create .mcp.json if it doesn't exist
+  const mcpJsonPath = path.join(targetDir, ".mcp.json");
+  writeIfMissing(
+    mcpJsonPath,
+    JSON.stringify(
+      {
+        mcpServers: {},
+      },
+      null,
+      2,
+    ) + "\n",
+    force,
+    summary,
+  );
+
+  // 4. Create .claude/CLAUDE.md if it doesn't exist
+  const claudeDir = path.join(targetDir, ".claude");
+  ensureDir(claudeDir, summary);
+
+  const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+  writeIfMissing(
+    claudeMdPath,
+    [
+      "# Project Instructions for Claude",
+      "",
+      "This project uses the Merlin framework for AI-orchestrated development.",
+      "",
+      "## Framework",
+      "",
+      "Merlin configuration lives in `.merlin-core/`.",
+      "Runtime state lives in `.merlin/` (gitignored).",
+      "",
+      "## Agents",
+      "",
+      "See `.merlin-core/development/agents/` for available agent definitions.",
+      "",
+      "## Skills",
+      "",
+      "See `.merlin-core/skills/` for available skill modules.",
+      "",
+    ].join("\n"),
+    force,
+    summary,
+  );
+
+  // 5. Ensure .merlin/ is in .gitignore
+  const gitignorePath = path.join(targetDir, ".gitignore");
+  ensureGitignoreEntry(gitignorePath, ".merlin/", summary);
+
+  // 6. Print summary
+  console.log("");
+  console.log("Summary");
+  console.log("-------");
+
+  if (summary.created.length > 0) {
+    console.log(`Created (${summary.created.length}):`);
+    summary.created.forEach((f) =>
+      console.log(`  + ${relativeTo(targetDir, f)}`),
+    );
+  }
+
+  if (summary.skipped.length > 0) {
+    console.log(`Skipped (${summary.skipped.length}):`);
+    summary.skipped.forEach((f) =>
+      console.log(`  - ${relativeTo(targetDir, f)}`),
+    );
+  }
+
+  if (summary.errors.length > 0) {
+    console.log(`Errors (${summary.errors.length}):`);
+    summary.errors.forEach((e) => console.log(`  ! ${e}`));
+  }
+
+  console.log("");
+  console.log("Merlin initialization complete.");
+  console.log("Run `merlin doctor` to verify system health.");
+  console.log("");
+}
+
+/**
+ * Ensure a directory exists; create it if missing.
+ */
+function ensureDir(dirPath, summary) {
+  if (fs.existsSync(dirPath)) {
+    summary.skipped.push(dirPath);
+    return;
+  }
+  try {
+    fs.mkdirSync(dirPath, { recursive: true });
+    summary.created.push(dirPath);
+  } catch (err) {
+    summary.errors.push(`Failed to create ${dirPath}: ${err.message}`);
+  }
+}
+
+/**
+ * Write a file only if it doesn't exist (unless force=true).
+ */
+function writeIfMissing(filePath, content, force, summary) {
+  if (fs.existsSync(filePath) && !force) {
+    summary.skipped.push(filePath);
+    return;
+  }
+  try {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, "utf8");
+    summary.created.push(filePath);
+  } catch (err) {
+    summary.errors.push(`Failed to write ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Ensure a pattern is present in .gitignore.
+ */
+function ensureGitignoreEntry(gitignorePath, entry, summary) {
+  try {
+    let content = "";
+    if (fs.existsSync(gitignorePath)) {
+      content = fs.readFileSync(gitignorePath, "utf8");
+    }
+
+    // Check if entry already exists (exact line match)
+    const lines = content.split("\n").map((l) => l.trim());
+    if (lines.includes(entry)) {
+      summary.skipped.push(`${gitignorePath} (already contains ${entry})`);
+      return;
+    }
+
+    // Append entry
+    const separator = content.endsWith("\n") || content === "" ? "" : "\n";
+    const block = `${separator}\n# Merlin runtime state\n${entry}\n`;
+    fs.appendFileSync(gitignorePath, block, "utf8");
+    summary.created.push(`${gitignorePath} (added ${entry})`);
+  } catch (err) {
+    summary.errors.push(`Failed to update .gitignore: ${err.message}`);
+  }
+}
+
+/**
+ * Get a path relative to a base directory for display.
+ */
+function relativeTo(base, filePath) {
+  if (typeof filePath === "string" && filePath.startsWith(base)) {
+    return filePath.slice(base.length).replace(/^[/\\]/, "");
+  }
+  return filePath;
+}
+
+// Run directly if executed as a script
+if (require.main === module) {
+  (async () => {
+    try {
+      const { assertLicensed } = require("../.merlin-core/core/licensing/gate");
+      const verdict = await assertLicensed({ allowHeartbeat: true });
+      if (!verdict.allowed) {
+        console.error(`Merlin is licensed software. ${verdict.message}`);
+        process.exit(1);
+      }
+    } catch (e) {
+      console.error(`License check failed: ${e.message}`);
+      process.exit(1);
+    }
+    const targetDir = process.argv[2] || process.cwd();
+    const force = process.argv.includes("--force");
+    initProject(path.resolve(targetDir), { force });
+  })();
+}
+
+module.exports = { initProject };