@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/install.js

@@ -0,0 +1,81 @@
+/**
+ * INSTALL mode entry — thin wrapper around upgrade.run() with source auto-detection.
+ *
+ * Two invocation paths:
+ *   1. Via merlin-tools.js CLI:
+ *        node .merlin-core/tools/merlin-tools.js install [TARGET] [--dry-run] [--flatten-nesting]
+ *      In this case, projectRoot is provided by merlin-tools.js (gestao-merlin root).
+ *
+ *   2. Direct (e.g., when packaged as npm consumer):
+ *        node node_modules/gestao-merlin/.merlin-core/tools/commands/install.js [TARGET]
+ *      In this case, source is auto-detected via __dirname (3 levels up).
+ *
+ * INSTALL is essentially CONVERSION + auto-detected source:
+ *   - If target has no .merlin-core/ → CONVERSION pipeline runs (Phase 5's branch)
+ *   - If target has .merlin-core/ already → UPGRADE pipeline runs
+ *   - Auto-routing via upgrade.js mode-detection (Phase 5)
+ *
+ * Default target: process.cwd() — matches `npx gestao-merlin install` UX.
+ *
+ * @module tools/commands/install
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const upgrade = require("./upgrade");
+
+/**
+ * Entry called by merlin-tools.js or test code.
+ *
+ * @param {string} command  Subcommand name ("install")
+ * @param {string[]} args   Remaining CLI args (positional + flags)
+ * @param {string} projectRoot  Source framework root (gestao-merlin root)
+ */
+async function run(command, args, projectRoot) {
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  const flags = args.filter((a) => a.startsWith("-"));
+  const target = positionals[0] || process.cwd();
+
+  // INSTALL = "use auto-detected source against this target, whatever its state"
+  return upgrade.run("upgrade", [target, ...flags], projectRoot);
+}
+
+function formatHuman(result) {
+  return upgrade.formatHuman(result);
+}
+
+// Direct invocation: auto-detect source from __dirname.
+// File lives at: <SOURCE>/.merlin-core/tools/commands/install.js
+//   → path.resolve(__dirname, "..", "..", "..") = SOURCE
+if (require.main === module) {
+  const sourceRoot = path.resolve(__dirname, "..", "..", "..");
+  // Sanity check: verify the resolved source actually contains a framework
+  const sentinelFile = path.join(
+    sourceRoot,
+    ".merlin-core",
+    "framework-config.yaml",
+  );
+  if (!fs.existsSync(sentinelFile)) {
+    console.error(
+      `INSTALL error: auto-detected source ${sourceRoot} does not contain ` +
+        `.merlin-core/framework-config.yaml. Are you running install.js from ` +
+        `inside an installed Merlin framework?`,
+    );
+    process.exit(1);
+  }
+  run("install", process.argv.slice(2), sourceRoot)
+    .then((result) => {
+      if (result && result.errors && result.errors.length > 0) {
+        process.exit(1);
+      }
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error(`INSTALL failed: ${err.message}`);
+      process.exit(1);
+    });
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/lib/__verify__/diff-reports.js

@@ -0,0 +1,170 @@
+/**
+ * Compare two upgrade-report.json files for schema parity.
+ *
+ * Used in Phase 9 of plan-a-shared-install-engine to verify the JS engine
+ * produces reports structurally equivalent to bash's (commit 722a4de-era schema).
+ *
+ * Allowed-to-differ fields (per-run values, not schema concerns):
+ *   - date          (timestamp differs per run)
+ *   - project_dir   (depends on target path)
+ *   - project_name  (depends on target dir basename)
+ *   - merlin_source (depends on source path)
+ *   - backups.*     (depends on backup model — bash timestamped vs JS rotated)
+ *
+ * Asserts structural equivalence on:
+ *   - schema (must be "merlin-upgrade-report/v1")
+ *   - mode (upgrade | convert | install)
+ *   - version_from + version_to type/shape
+ *   - preserved object shape (4 numeric keys)
+ *   - installed object shape (2 numeric keys)
+ *   - errors (number)
+ *   - verified (boolean)
+ *
+ * @module tools/commands/lib/__verify__/diff-reports
+ */
+
+"use strict";
+
+const fs = require("fs");
+
+// Keys whose VALUES can differ per-run (we check presence only, not value)
+const PER_RUN_KEYS = new Set([
+  "date",
+  "project_dir",
+  "project_name",
+  "merlin_source",
+]);
+
+// Schema-required keys at top level
+const SCHEMA_KEYS = [
+  "schema",
+  "project_name",
+  "project_dir",
+  "merlin_source",
+  "date",
+  "mode",
+  "version_from",
+  "version_to",
+  "preserved",
+  "installed",
+  "backups",
+  "errors",
+  "verified",
+];
+
+const PRESERVED_KEYS = [
+  "thoughts_before",
+  "thoughts_after",
+  "domain_skills_before",
+  "domain_skills_after",
+];
+
+const INSTALLED_KEYS = ["agents", "commands"];
+
+/**
+ * Compare two reports loaded from disk paths.
+ *
+ * @param {string} pathA
+ * @param {string} pathB
+ * @returns {{ same: boolean, differences: string[], details: object }}
+ */
+function diffReports(pathA, pathB) {
+  const a = JSON.parse(fs.readFileSync(pathA, "utf8"));
+  const b = JSON.parse(fs.readFileSync(pathB, "utf8"));
+  return diffParsed(a, b);
+}
+
+/**
+ * Compare two already-parsed report objects.
+ * @returns {{ same: boolean, differences: string[], details: object }}
+ */
+function diffParsed(a, b) {
+  const differences = [];
+
+  // 1. Same top-level keys (presence, not value)
+  for (const k of SCHEMA_KEYS) {
+    if (!(k in a)) differences.push(`A missing key: ${k}`);
+    if (!(k in b)) differences.push(`B missing key: ${k}`);
+  }
+
+  // 2. Schema value MUST match exactly
+  if (a.schema !== b.schema) {
+    differences.push(`schema mismatch: A="${a.schema}" B="${b.schema}"`);
+  }
+
+  // 3. Nested objects: preserved
+  if (a.preserved && b.preserved) {
+    for (const k of PRESERVED_KEYS) {
+      if (!(k in a.preserved))
+        differences.push(`A.preserved missing key: ${k}`);
+      if (!(k in b.preserved))
+        differences.push(`B.preserved missing key: ${k}`);
+      if (
+        k in a.preserved &&
+        k in b.preserved &&
+        typeof a.preserved[k] !== typeof b.preserved[k]
+      ) {
+        differences.push(
+          `preserved.${k} type mismatch: A=${typeof a.preserved[k]} B=${typeof b.preserved[k]}`,
+        );
+      }
+    }
+  }
+
+  // 4. Nested objects: installed
+  if (a.installed && b.installed) {
+    for (const k of INSTALLED_KEYS) {
+      if (!(k in a.installed))
+        differences.push(`A.installed missing key: ${k}`);
+      if (!(k in b.installed))
+        differences.push(`B.installed missing key: ${k}`);
+    }
+  }
+
+  // 5. backups shape (allow values to differ; check key presence)
+  if (a.backups && b.backups) {
+    for (const k of ["claude_backup", "merlin_core_backup"]) {
+      if (!(k in a.backups)) differences.push(`A.backups missing key: ${k}`);
+      if (!(k in b.backups)) differences.push(`B.backups missing key: ${k}`);
+    }
+  }
+
+  // 6. Type checks for top-level fields whose VALUES we don't compare
+  for (const k of ["mode", "version_from", "version_to"]) {
+    if (k in a && k in b && typeof a[k] !== typeof b[k]) {
+      differences.push(`${k} type mismatch: A=${typeof a[k]} B=${typeof b[k]}`);
+    }
+  }
+  if (typeof a.errors !== "number" || typeof b.errors !== "number") {
+    differences.push("errors must be number in both");
+  }
+  if (typeof a.verified !== "boolean" || typeof b.verified !== "boolean") {
+    differences.push("verified must be boolean in both");
+  }
+
+  return {
+    same: differences.length === 0,
+    differences,
+    details: {
+      perRunKeys: Array.from(PER_RUN_KEYS),
+      schemaA: a.schema,
+      schemaB: b.schema,
+      modeA: a.mode,
+      modeB: b.mode,
+    },
+  };
+}
+
+module.exports = { diffReports, diffParsed, SCHEMA_KEYS, PER_RUN_KEYS };
+
+// CLI invocation: node diff-reports.js <pathA> <pathB>
+if (require.main === module) {
+  const [pathA, pathB] = process.argv.slice(2);
+  if (!pathA || !pathB) {
+    console.error("Usage: node diff-reports.js <reportA.json> <reportB.json>");
+    process.exit(2);
+  }
+  const result = diffReports(pathA, pathB);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.same ? 0 : 1);
+}

package/.merlin-core/tools/commands/lib/fs-safe.js

@@ -0,0 +1,186 @@
+/**
+ * Shared filesystem utilities for Merlin tools.
+ *
+ * All operations follow the COPY-THEN-DELETE pattern for safety:
+ * never delete the original until the copy is verified.
+ *
+ * @module tools/commands/lib/fs-safe
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Recursively copy a directory. Creates destination if needed.
+ * @returns {number} Number of files copied.
+ */
+function copyDirSync(src, dst) {
+  if (!fs.existsSync(src)) return 0;
+  fs.mkdirSync(dst, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDirSync(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Safely remove a directory recursively. No-op if missing.
+ */
+function rmDirSync(dir) {
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Count all files in a directory recursively.
+ */
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * List immediate subdirectory names.
+ */
+function listSubdirs(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+}
+
+/**
+ * Count "real" thought files — excludes .gitkeep, README.md, INDEX.*.
+ */
+function countRealThoughts(thoughtsDir) {
+  if (!fs.existsSync(thoughtsDir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(thoughtsDir, { withFileTypes: true })) {
+    const full = path.join(thoughtsDir, entry.name);
+    if (entry.isDirectory()) {
+      count += countRealThoughts(full);
+    } else if (
+      entry.name !== ".gitkeep" &&
+      entry.name !== "README.md" &&
+      !entry.name.startsWith("INDEX.")
+    ) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Extract version from a Merlin YAML config file.
+ *
+ * Reads `version:` key (project-config.yaml + core-config.yaml convention).
+ * For framework BUILD version (sync source-of-truth), use extractFrameworkVersion().
+ */
+function extractVersion(configPath) {
+  try {
+    const content = fs.readFileSync(configPath, "utf8");
+    const match = content.match(/^\s+version:\s+(.+)$/m);
+    return match ? match[1].replace(/['"]/g, "").trim() : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Extract framework BUILD version from framework-config.yaml.
+ *
+ * Reads `framework_version:` key — this is the version that gets bumped on
+ * each framework release. Distinct from core-config.yaml.version (schema
+ * version, rarely changes) and project-config.yaml.version (what THIS project
+ * thinks the framework is at — sed-bumped after each upgrade).
+ *
+ * Use this when reading the SOURCE's version for upgrade comparisons.
+ *
+ * @param {string} frameworkConfigPath Path to source's .merlin-core/framework-config.yaml
+ * @returns {string} Version string (e.g., "3.0.2") or "unknown" on miss
+ */
+function extractFrameworkVersion(frameworkConfigPath) {
+  try {
+    const content = fs.readFileSync(frameworkConfigPath, "utf8");
+    const match = content.match(/^\s*framework_version:\s*(.+)$/m);
+    return match ? match[1].replace(/['"]/g, "").trim() : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Parse the major-version segment from a dotted semver string.
+ *
+ * Used to detect major-version-skip upgrades (e.g., v2.13.0 → v3.0.2)
+ * so the pre-flight can print a louder warning.
+ *
+ * @param {string} version Version string (e.g., "3.0.2", "2.13.0")
+ * @returns {string|null} Major segment as string (e.g., "3") or null for unparseable
+ */
+function parseSemverMajor(version) {
+  if (!version || version === "unknown" || version === "none") return null;
+  const match = String(version).match(/^(\d+)\./);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract project name from a Merlin YAML config file.
+ */
+function extractProjectName(configPath) {
+  try {
+    const content = fs.readFileSync(configPath, "utf8");
+    const match = content.match(/^\s+name:\s+"?([^"]+)"?$/m);
+    return match ? match[1].trim() : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Bump version in project-config.yaml.
+ */
+function bumpProjectConfigVersion(configPath, newVersion) {
+  try {
+    let content = fs.readFileSync(configPath, "utf8");
+    content = content.replace(
+      /^(\s+version:\s+)"?[^"\n]+"?/m,
+      `$1"${newVersion}"`,
+    );
+    fs.writeFileSync(configPath, content, "utf8");
+  } catch {
+    // Non-fatal: version bump is best-effort
+  }
+}
+
+module.exports = {
+  copyDirSync,
+  rmDirSync,
+  countFiles,
+  listSubdirs,
+  countRealThoughts,
+  extractVersion,
+  extractFrameworkVersion,
+  extractProjectName,
+  bumpProjectConfigVersion,
+  parseSemverMajor,
+};