@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/lib/preflight.js

@@ -0,0 +1,607 @@
+/**
+ * Pre-flight intelligence for Merlin install/upgrade/convert operations.
+ *
+ * Runs BEFORE any destructive step:
+ *   - Idempotency: short-circuit when target already at source version
+ *   - Major-version-skip warning: loud block when CUR_MAJOR != SRC_MAJOR
+ *   - Bug class A defense: scan + remove broken symlinks (would crash backup)
+ *   - Bug class C detection: list legacy nested skills; opt-in flatten via flag
+ *   - Pre-flight summary: numbered list of steps that will run
+ *   - Dry-run gate: exit cleanly after summary
+ *
+ * Exported scanners are pure (no I/O side effects). runPreflight() orchestrates
+ * and prints to stdout; tests assert on returned object, not captured output.
+ *
+ * @module tools/commands/lib/preflight
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { parseSemverMajor } = require("./fs-safe");
+
+// === ANSI color escapes (minimal — disable for non-TTY or NO_COLOR env) ===
+
+const ANSI = {
+  RESET: "\x1b[0m",
+  RED: "\x1b[0;31m",
+  GREEN: "\x1b[0;32m",
+  YELLOW: "\x1b[1;33m",
+  BLUE: "\x1b[0;34m",
+  CYAN: "\x1b[0;36m",
+};
+
+function useColor() {
+  return !process.env.NO_COLOR && process.stdout.isTTY;
+}
+
+function c(color, text) {
+  return useColor() ? `${ANSI[color]}${text}${ANSI.RESET}` : String(text);
+}
+
+// === Scanners (pure helpers — no printing) ===
+
+/**
+ * Walk dirs looking for symlinks whose targets don't exist.
+ * POSIX-equivalent: `find $dir -type l ! -exec test -e {} \; -print`
+ *
+ * @param {string[]} dirs Directories to scan recursively
+ * @returns {string[]} Absolute paths of broken symlinks
+ */
+function scanBrokenSymlinks(dirs) {
+  const broken = [];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    walkForBrokenSymlinks(dir, broken);
+  }
+  return broken;
+}
+
+function walkForBrokenSymlinks(dir, broken) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // unreadable dir, skip
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      try {
+        // existsSync returns false for dangling links (follows symlink)
+        if (!fs.existsSync(full)) broken.push(full);
+      } catch {
+        broken.push(full);
+      }
+    } else if (entry.isDirectory()) {
+      walkForBrokenSymlinks(full, broken);
+    }
+  }
+}
+
+/**
+ * Remove the listed symlink paths via fs.unlinkSync.
+ *
+ * @param {string[]} paths
+ * @returns {number} Number of successful removals
+ */
+function removeBrokenSymlinks(paths) {
+  let removed = 0;
+  for (const p of paths) {
+    try {
+      fs.unlinkSync(p);
+      removed++;
+    } catch {
+      // best-effort; non-fatal
+    }
+  }
+  return removed;
+}
+
+/**
+ * Scan a domain-skills directory for legacy nested duplicates
+ * (`<skill_name>/<skill_name>/` pattern from prior pre-c59cfe3 buggy upgrades).
+ *
+ * @param {string} domainDir Path to .merlin-core/skills/domain/
+ * @returns {Array<{name: string, sizeBytes: number}>}
+ */
+function scanNestedSkills(domainDir) {
+  if (!fs.existsSync(domainDir)) return [];
+  const nested = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(domainDir, { withFileTypes: true });
+  } catch {
+    return nested;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const nestedPath = path.join(domainDir, entry.name, entry.name);
+    if (fs.existsSync(nestedPath)) {
+      try {
+        if (fs.statSync(nestedPath).isDirectory()) {
+          nested.push({
+            name: entry.name,
+            sizeBytes: dirSize(nestedPath),
+          });
+        }
+      } catch {
+        // stat failed; skip
+      }
+    }
+  }
+  return nested;
+}
+
+function dirSize(dir) {
+  let total = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      total += dirSize(full);
+    } else if (entry.isFile()) {
+      try {
+        total += fs.statSync(full).size;
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return total;
+}
+
+function formatBytes(b) {
+  if (b < 1024) return `${b}B`;
+  if (b < 1024 * 1024) return `${Math.round(b / 1024)}K`;
+  return `${(b / 1024 / 1024).toFixed(1)}M`;
+}
+
+/**
+ * Probe whether a shell command resolves (exit 0). Used to detect host
+ * prerequisites (Docker, etc.). Inject `probe` in tests to avoid real exec.
+ *
+ * @param {string} cmd
+ * @param {(cmd: string) => boolean} [probe]
+ * @returns {boolean}
+ */
+function commandWorks(cmd, probe) {
+  if (typeof probe === "function") return probe(cmd);
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Scan the host for Merlin install prerequisites. Docker + Docker Compose are
+ * REQUIRED: the Merlin install provisions the AI stack (RAGBASE — pgvector in
+ * Docker) and the self-hosted automation stacks (n8n / Postiz compose). Returns
+ * the MISSING prerequisites (empty array = all present).
+ *
+ * Pure w.r.t. the filesystem; probes the shell (injectable via `probe` in tests).
+ *
+ * @param {(cmd: string) => boolean} [probe] Test seam — returns presence per cmd
+ * @returns {Array<{name: string, cmd: string, requiredFor: string}>}
+ */
+function scanEnvironmentPrereqs(probe) {
+  const REQUIRED = [
+    {
+      name: "Docker",
+      cmd: "docker --version",
+      requiredFor: "RAGBASE (vector DB) + self-hosted stacks",
+    },
+    {
+      name: "Docker Compose",
+      cmd: "docker compose version",
+      requiredFor: "RAGBASE / n8n / Postiz compose stacks",
+    },
+  ];
+  return REQUIRED.filter((req) => !commandWorks(req.cmd, probe));
+}
+
+// === Orchestrator ===
+
+/**
+ * Run all pre-flight checks and print human-readable status.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir Target project's absolute path
+ * @param {string} opts.projectName Display name
+ * @param {string} opts.srcDir Source framework's absolute path (gestao-merlin root)
+ * @param {string} opts.srcVersion Source's framework_version (e.g., "3.0.2")
+ * @param {string} opts.currentVersion Target's project-config.yaml.version (e.g., "3.0.0", "none")
+ * @param {string} opts.mode "upgrade" | "convert" | "install"
+ * @param {boolean} [opts.dryRun=false]
+ * @param {boolean} [opts.flattenNesting=false]
+ * @param {number} [opts.thoughtCount=0]
+ * @param {number} [opts.domainSkillCount=0]
+ * @param {(cmd: string) => boolean} [opts.probeCommand] Test seam for env prereq probing
+ * @returns {object} { shouldExit, exitCode, brokenLinks, nestedSkills, willFlatten, missingPrereqs, summaryPrinted }
+ */
+function runPreflight(opts) {
+  const {
+    projectDir,
+    projectName = path.basename(opts.projectDir || ""),
+    srcDir,
+    srcVersion,
+    currentVersion,
+    mode,
+    dryRun = false,
+    flattenNesting = false,
+    thoughtCount = 0,
+    domainSkillCount = 0,
+  } = opts;
+
+  const result = {
+    shouldExit: false,
+    exitCode: 0,
+    brokenLinks: [],
+    nestedSkills: [],
+    willFlatten: false,
+    missingPrereqs: [],
+    summaryPrinted: false,
+  };
+
+  // 1. IDEMPOTENCY — bail before doing anything if target already at source
+  if (
+    mode === "upgrade" &&
+    currentVersion === srcVersion &&
+    currentVersion !== "unknown" &&
+    currentVersion !== "none"
+  ) {
+    printIdempotencyBail(projectName, currentVersion);
+    result.shouldExit = true;
+    result.exitCode = 0;
+    return result;
+  }
+
+  // 2. BANNER
+  printBanner(mode, srcVersion);
+  printProjectInfo({
+    projectName,
+    projectDir,
+    srcDir,
+    mode,
+    dryRun,
+    currentVersion,
+    srcVersion,
+    thoughtCount,
+    domainSkillCount,
+  });
+
+  // 3. MAJOR-VERSION-SKIP WARNING (only upgrade mode + parseable versions)
+  if (mode === "upgrade") {
+    const curMajor = parseSemverMajor(currentVersion);
+    const srcMajor = parseSemverMajor(srcVersion);
+    if (curMajor && srcMajor && curMajor !== srcMajor) {
+      printMajorVersionWarning(currentVersion, srcVersion, srcDir);
+    }
+  }
+
+  // 4. PRE-FLIGHT SUMMARY (numbered steps)
+  printPreflightSummary(mode);
+
+  // 4.5 ENVIRONMENT PREREQUISITES (Docker etc.) — warn loudly, never block the
+  //     base framework copy. The AI/automation stacks (RAGBASE/n8n/Postiz) need
+  //     these; provisioning them later will fail without Docker.
+  result.missingPrereqs = scanEnvironmentPrereqs(opts.probeCommand);
+  if (result.missingPrereqs.length > 0) {
+    printMissingPrereqsWarning(result.missingPrereqs);
+  }
+
+  // 5. BUG A — broken symlink scan (always runs; auto-removes unless dry-run)
+  const scanDirs = [
+    path.join(projectDir, ".claude"),
+    path.join(projectDir, ".merlin-core"),
+  ];
+  result.brokenLinks = scanBrokenSymlinks(scanDirs);
+  if (result.brokenLinks.length > 0) {
+    printBrokenSymlinkWarning(result.brokenLinks, dryRun);
+    if (!dryRun) {
+      const removed = removeBrokenSymlinks(result.brokenLinks);
+      for (let i = 0; i < removed; i++) {
+        console.log(
+          `  ${c("GREEN", "✓")} Removed broken symlink: ${result.brokenLinks[i]}`,
+        );
+      }
+      console.log("");
+    }
+  }
+
+  // 6. BUG C — nested skill detection (always informs; opt-in flatten action later)
+  const domainDir = path.join(projectDir, ".merlin-core", "skills", "domain");
+  result.nestedSkills = scanNestedSkills(domainDir);
+  if (result.nestedSkills.length > 0) {
+    result.willFlatten = flattenNesting === true;
+    printNestedSkillsWarning(result.nestedSkills, flattenNesting, dryRun);
+  }
+
+  // 7. DRY-RUN exit
+  if (dryRun) {
+    printDryRunComplete(projectDir);
+    result.shouldExit = true;
+    result.exitCode = 0;
+  }
+
+  result.summaryPrinted = true;
+  return result;
+}
+
+// === Print helpers (side-effecting; not exported) ===
+
+function printIdempotencyBail(projectName, version) {
+  console.log("");
+  console.log(
+    c("GREEN", "  ╔══════════════════════════════════════════════════════╗"),
+  );
+  console.log(
+    c("GREEN", "  ║         ALREADY AT TARGET VERSION                    ║"),
+  );
+  console.log(
+    c("GREEN", "  ╚══════════════════════════════════════════════════════╝"),
+  );
+  console.log("");
+  console.log(`  Project:  ${c("GREEN", projectName)}`);
+  console.log(`  Version:  ${c("GREEN", "v" + version)} (matches source)`);
+  console.log("");
+  console.log(
+    "  No upgrade needed. To force a re-run anyway, edit project-config.yaml",
+  );
+  console.log("  and bump the version manually, then re-invoke.");
+  console.log("");
+}
+
+function printBanner(mode, srcVersion) {
+  const labelMap = {
+    upgrade: "MERLIN FRAMEWORK — UPGRADE TOOL",
+    convert: "MERLIN FRAMEWORK — CONVERSION TOOL",
+    install: "MERLIN FRAMEWORK — INSTALL TOOL",
+  };
+  const label = labelMap[mode] || "MERLIN FRAMEWORK";
+  console.log("");
+  console.log(
+    c("CYAN", "  ╔══════════════════════════════════════════════════════╗"),
+  );
+  console.log(c("CYAN", `  ║         ${pad(label, 44)} ║`));
+  console.log(c("CYAN", `  ║                   v${pad(srcVersion, 33)} ║`));
+  console.log(
+    c("CYAN", "  ╚══════════════════════════════════════════════════════╝"),
+  );
+  console.log("");
+}
+
+function pad(s, width) {
+  s = String(s);
+  if (s.length >= width) return s;
+  return s + " ".repeat(width - s.length);
+}
+
+function printProjectInfo({
+  projectName,
+  projectDir,
+  srcDir,
+  mode,
+  dryRun,
+  currentVersion,
+  srcVersion,
+  thoughtCount,
+  domainSkillCount,
+}) {
+  console.log(`  Project:  ${c("GREEN", projectName)}`);
+  console.log(`  Path:     ${projectDir}`);
+  console.log(`  Source:   ${srcDir}`);
+  const modeColor = mode === "upgrade" ? "YELLOW" : "GREEN";
+  console.log(`  Mode:     ${c(modeColor, mode.toUpperCase())}`);
+  if (dryRun) {
+    console.log(`  Run:      ${c("YELLOW", "DRY-RUN (no writes)")}`);
+  }
+  if (mode === "upgrade") {
+    console.log(
+      `  Version:  ${c("YELLOW", "v" + currentVersion)} → ${c("GREEN", "v" + srcVersion)}`,
+    );
+    console.log(
+      `  Thoughts: ${c("YELLOW", String(thoughtCount))} files to preserve`,
+    );
+    console.log(
+      `  Domain:   ${c("YELLOW", String(domainSkillCount))} skills to preserve`,
+    );
+  }
+  console.log("");
+}
+
+function printMajorVersionWarning(curVersion, srcVersion, srcDir) {
+  console.log("");
+  console.log(
+    c("YELLOW", "  ╔══════════════════════════════════════════════════════╗"),
+  );
+  console.log(
+    c("YELLOW", "  ║              ⚠  MAJOR-VERSION JUMP  ⚠                 ║"),
+  );
+  console.log(
+    c("YELLOW", "  ╚══════════════════════════════════════════════════════╝"),
+  );
+  console.log("");
+  console.log(
+    `  This is a major-version upgrade: ${c("YELLOW", "v" + curVersion)} → ${c("GREEN", "v" + srcVersion)}`,
+  );
+  console.log(
+    "  Skipping multiple major releases — review CHANGELOG.md entries between these",
+  );
+  console.log(
+    "  versions before proceeding. Look for breaking changes in agents, commands, or",
+  );
+  console.log("  thoughts/ structure.");
+  console.log(`  CHANGELOG: ${path.join(srcDir, "CHANGELOG.md")}`);
+  console.log("");
+}
+
+function printPreflightSummary(mode) {
+  console.log(
+    c("BLUE", "  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"),
+  );
+  console.log(c("CYAN", "  PRE-FLIGHT SUMMARY"));
+  console.log(
+    c("BLUE", "  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"),
+  );
+  if (mode === "upgrade") {
+    console.log("  Will UPGRADE:");
+    console.log(
+      "    1. Backup .claude/ and .merlin-core/ to .merlin-backups/latest/",
+    );
+    console.log(
+      "    2. Preserve thoughts + domain skills + project-config.yaml",
+    );
+    console.log("    3. Replace .merlin-core/ with fresh source framework");
+    console.log("    4. Restore preserved data + bump project-config.yaml");
+    console.log("    5. Regenerate .claude/commands/ (sync-bridges)");
+    console.log(
+      "    6. Sync CLAUDE.md, .mcp.json, settings.json, hooks (additive merge for settings.local.json)",
+    );
+    console.log(
+      "    7. Verify: all configs present, agents ≥15, commands ≥20, no data loss",
+    );
+  } else if (mode === "convert") {
+    console.log("  Will CONVERT (no existing .merlin-core/):");
+    console.log("    1. Backup existing .claude/ if present");
+    console.log("    2. Install fresh .merlin-core/ from source");
+    console.log(
+      "    3. Clean source thoughts/ (belong to framework, not this project)",
+    );
+    console.log(
+      "    4. Migrate any thoughts/ at project root into .merlin-core/thoughts/shared/",
+    );
+    console.log(
+      "    5. Remove legacy .claude/agents/ and .claude/templates/ if present",
+    );
+    console.log("    6. Generate .claude/commands/ bridges (sync-bridges)");
+    console.log("    7. Generate project-config.yaml from defaults");
+  } else {
+    console.log("  Will INSTALL (auto-detected source from npm package):");
+    console.log(
+      "    1-7. Same as CONVERT — see plan for details (Phase 5 + 7).",
+    );
+  }
+  console.log("");
+}
+
+function printBrokenSymlinkWarning(links, dryRun) {
+  console.log(
+    `  ${c("YELLOW", "⚠")} Detected ${links.length} broken symlink(s) — these would crash cp -r backup:`,
+  );
+  for (const link of links) {
+    let target = "";
+    try {
+      target = fs.readlinkSync(link);
+    } catch {
+      target = "<unreadable>";
+    }
+    console.log(
+      `    ${c("YELLOW", "↳")} ${link}  →  ${target}  ${c("RED", "(target missing)")}`,
+    );
+  }
+  if (dryRun) {
+    console.log(
+      `  ${c("YELLOW", "◌")} ${c("YELLOW", "[DRY-RUN]")} would remove ${links.length} broken symlink(s) before backup`,
+    );
+    console.log("");
+  }
+}
+
+function printNestedSkillsWarning(nested, flattenNesting, dryRun) {
+  console.log(
+    `  ${c("YELLOW", "⚠")} Detected ${nested.length} legacy nested domain skill(s) from prior buggy upgrade(s):`,
+  );
+  for (const s of nested) {
+    console.log(
+      `    ${c("YELLOW", "↳")} .merlin-core/skills/domain/${s.name}/${s.name}/  (${formatBytes(s.sizeBytes)})`,
+    );
+  }
+  if (flattenNesting) {
+    if (dryRun) {
+      console.log(
+        `  ${c("YELLOW", "◌")} ${c("YELLOW", "[DRY-RUN]")} would flatten (remove inner) ${nested.length} nested skill(s) during Step 2 (--flatten-nesting set)`,
+      );
+    } else {
+      console.log(
+        `  ${c("CYAN", "→")} Will flatten (remove inner) ${nested.length} nested skill(s) during Step 2`,
+      );
+    }
+  } else {
+    console.log(
+      `  ${c("YELLOW", "⚠")} These nested dirs will be PRESERVED through upgrade (default behavior — safe but accumulates).`,
+    );
+    console.log(
+      `  ${c("YELLOW", "⚠")} To clean them automatically, re-run with: ${c("CYAN", "--flatten-nesting")}`,
+    );
+    console.log(
+      `  ${c("YELLOW", "⚠")} Only use --flatten-nesting AFTER verifying nested content isn't unique customization.`,
+    );
+  }
+  console.log("");
+}
+
+function printMissingPrereqsWarning(missing) {
+  console.log("");
+  console.log(
+    c("YELLOW", "  ╔══════════════════════════════════════════════════════╗"),
+  );
+  console.log(
+    c("YELLOW", "  ║          ⚠  PRÉ-REQUISITO AUSENTE: DOCKER  ⚠         ║"),
+  );
+  console.log(
+    c("YELLOW", "  ╚══════════════════════════════════════════════════════╝"),
+  );
+  console.log("");
+  console.log(
+    "  Docker é pré-requisito do Merlin para a stack de IA e automação.",
+  );
+  console.log("  Sem ele, estes passos da instalação NÃO sobem:");
+  for (const m of missing) {
+    console.log(
+      `    ${c("YELLOW", "↳")} ${m.name}  ${c("RED", "(não encontrado)")} — ${m.requiredFor}`,
+    );
+  }
+  console.log("");
+  console.log(
+    "  Instale o Docker Desktop (WSL 2 backend) — ver Manual 2.3 (WSL, Docker",
+  );
+  console.log("  Desktop e Pasta DevOps). Valide com: docker run hello-world");
+  console.log("");
+}
+
+function printDryRunComplete(projectDir) {
+  console.log("");
+  console.log(
+    c("GREEN", "  ╔══════════════════════════════════════════════════════╗"),
+  );
+  console.log(
+    c("GREEN", "  ║         DRY-RUN COMPLETE — NO CHANGES MADE           ║"),
+  );
+  console.log(
+    c("GREEN", "  ╚══════════════════════════════════════════════════════╝"),
+  );
+  console.log("");
+  console.log("  This was a simulation. To execute for real:");
+  console.log(
+    `    ${c("CYAN", `node .merlin-core/tools/merlin-tools.js upgrade "${projectDir}" --yes`)}`,
+  );
+  console.log("");
+}
+
+module.exports = {
+  scanBrokenSymlinks,
+  removeBrokenSymlinks,
+  scanNestedSkills,
+  scanEnvironmentPrereqs,
+  runPreflight,
+};