@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/doc-sync.js

@@ -0,0 +1,127 @@
+/**
+ * doc-sync -- Detect stale documentation and manage suggestions
+ *
+ * Usage:
+ *   doc-sync check           Detect stale docs from git diff
+ *   doc-sync suggestions     Show current doc-sync suggestions
+ *   doc-sync clear           Clear suggestions file
+ *
+ * @module tools/commands/doc-sync
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { DocSyncEngine } = require("../../core/alkimia/memory/doc-sync");
+
+function getSuggestionsPath(projectRoot) {
+  return path.join(projectRoot, ".merlin", "doc-sync-suggestions.json");
+}
+
+async function run(_command, args, projectRoot) {
+  const engine = new DocSyncEngine({ projectRoot });
+  const action = args[0] || "check";
+
+  if (action === "check") {
+    // Get changed files from git diff
+    let changedFiles = [];
+    try {
+      const diff = execSync("git diff --name-only HEAD", {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      const staged = execSync("git diff --name-only --cached", {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      changedFiles = [
+        ...new Set([
+          ...diff.split("\n").filter(Boolean),
+          ...staged.split("\n").filter(Boolean),
+        ]),
+      ];
+    } catch {
+      return { error: "Failed to read git diff", suggestions: [] };
+    }
+
+    if (changedFiles.length === 0) {
+      return { message: "No changed files detected", suggestions: [] };
+    }
+
+    const suggestions = engine.detectStaleDoc(changedFiles);
+
+    // Save suggestions
+    if (suggestions.length > 0) {
+      const sugPath = getSuggestionsPath(projectRoot);
+      const dir = path.dirname(sugPath);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        sugPath,
+        JSON.stringify(
+          {
+            timestamp: new Date().toISOString(),
+            changedFiles,
+            suggestions,
+          },
+          null,
+          2,
+        ),
+      );
+    }
+
+    return {
+      changedFiles: changedFiles.length,
+      suggestions,
+      message:
+        suggestions.length > 0
+          ? `${suggestions.length} documentation sections may need updating`
+          : "No documentation updates needed",
+    };
+  }
+
+  if (action === "suggestions") {
+    const sugPath = getSuggestionsPath(projectRoot);
+    try {
+      const data = JSON.parse(fs.readFileSync(sugPath, "utf8"));
+      return data;
+    } catch {
+      return { message: "No suggestions file found", suggestions: [] };
+    }
+  }
+
+  if (action === "clear") {
+    const sugPath = getSuggestionsPath(projectRoot);
+    try {
+      if (fs.existsSync(sugPath)) fs.unlinkSync(sugPath);
+      return { success: true, message: "Suggestions cleared" };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  throw new Error("Usage: doc-sync [check|suggestions|clear]");
+}
+
+function formatHuman(result) {
+  if (result.error) return `Error: ${result.error}`;
+  if (
+    result.message &&
+    (!result.suggestions || result.suggestions.length === 0)
+  ) {
+    return result.message;
+  }
+
+  const lines = [result.message || `${result.suggestions.length} suggestions:`];
+  for (const s of result.suggestions || []) {
+    lines.push(`  - [${s.docFile}] "${s.section}": ${s.reason}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/eval-skill.js

@@ -0,0 +1,193 @@
+/**
+ * eval-skill — Evaluate a skill against test cases
+ *
+ * Thin wrapper that:
+ * 1. Validates evals.json against skill-eval-schema
+ * 2. Lists test cases and their assertions
+ * 3. Delegates to skill-creator's Python scripts when available
+ *
+ * Usage: node merlin-tools.js eval-skill <skill-name> [--json]
+ *
+ * @since v3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+async function run(_command, args, projectRoot) {
+  // H1 fix: filter flags before extracting skill name
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const skillName = positional[0];
+
+  if (!skillName) {
+    const msg = [
+      "Usage: merlin-tools eval-skill <skill-name> [--json]",
+      "",
+      "Evaluates a skill against its evals/evals.json test cases.",
+      "If skill-creator scripts are available, delegates to them.",
+    ].join("\n");
+    return { success: false, error: msg };
+  }
+
+  projectRoot = projectRoot || process.cwd();
+
+  // H2 fix: sanitize skill name — reject path separators and traversal
+  if (/[/\\]/.test(skillName) || skillName.includes("..")) {
+    return {
+      success: false,
+      error: `Invalid skill name "${skillName}" — must not contain path separators or traversal`,
+    };
+  }
+
+  // Find skill directory
+  const skillDirs = [
+    path.join(projectRoot, ".merlin-core", "skills", "general", skillName),
+    path.join(projectRoot, ".merlin-core", "skills", "domain", skillName),
+    path.join(projectRoot, ".agents", "skills", skillName),
+  ];
+
+  let skillDir = null;
+  for (const dir of skillDirs) {
+    if (fs.existsSync(path.join(dir, "SKILL.md"))) {
+      skillDir = dir;
+      break;
+    }
+  }
+
+  if (!skillDir) {
+    return {
+      success: false,
+      error: `Skill "${skillName}" not found in any skill directory.`,
+    };
+  }
+
+  // N23 fix: use relative path to avoid leaking absolute filesystem paths
+  const relativeSkillDir = path.relative(projectRoot, skillDir);
+
+  // Check for evals.json
+  const evalsFile = path.join(skillDir, "evals", "evals.json");
+  if (!fs.existsSync(evalsFile)) {
+    return {
+      success: true,
+      skill: skillName,
+      status: "no_evals",
+      message: `No evals/evals.json found for skill "${skillName}". Create one using the skill-creator skill or manually.`,
+      path: relativeSkillDir,
+    };
+  }
+
+  // Load and validate evals
+  let evals;
+  try {
+    evals = JSON.parse(fs.readFileSync(evalsFile, "utf8"));
+  } catch (e) {
+    return {
+      success: false,
+      error: `Failed to parse evals.json: ${e.message}`,
+    };
+  }
+
+  // H4 fix: validate required fields unconditionally (not conditional on schema file)
+  if (!evals.skill_name || !evals.evals || !Array.isArray(evals.evals)) {
+    return {
+      success: false,
+      error:
+        "Invalid evals.json: missing required fields (skill_name, evals array)",
+    };
+  }
+
+  // N4 fix: validate minimum items and per-item required fields
+  if (evals.evals.length === 0) {
+    return {
+      success: false,
+      error:
+        "Invalid evals.json: evals array must contain at least one test case",
+    };
+  }
+  for (let i = 0; i < evals.evals.length; i++) {
+    const e = evals.evals[i];
+    if (e.id == null || e.id === "") {
+      return {
+        success: false,
+        error: `Invalid evals.json: eval[${i}] missing required field "id"`,
+      };
+    }
+    if (!e.prompt) {
+      return {
+        success: false,
+        error: `Invalid evals.json: eval[${i}] missing required field "prompt"`,
+      };
+    }
+  }
+
+  // Check for skill-creator scripts
+  const skillCreatorDir = path.join(
+    projectRoot,
+    ".merlin-core",
+    "skills",
+    "general",
+    "skill-creator",
+    "scripts",
+  );
+  const hasScripts = fs.existsSync(skillCreatorDir);
+
+  // H3 fix: return result instead of printing directly
+  return {
+    success: true,
+    skill: skillName,
+    path: relativeSkillDir,
+    eval_count: evals.evals.length,
+    has_scripts: hasScripts,
+    evals: evals.evals.map((e) => ({
+      id: e.id,
+      prompt:
+        e.prompt.length > 80 ? e.prompt.substring(0, 80) + "..." : e.prompt,
+      should_trigger: e.should_trigger !== false,
+      assertions: (e.assertions || []).length,
+    })),
+  };
+}
+
+/**
+ * Format result for human-readable output.
+ * @param {Object} result - The result from run()
+ * @returns {string}
+ */
+function formatHuman(result) {
+  if (!result) return "";
+  if (!result.success) return `Error: ${result.error}`;
+  if (result.status === "no_evals") {
+    return [
+      `Skill: ${result.skill}`,
+      `Path: ${result.path}`,
+      "",
+      "No evals found.",
+      "Create evals/evals.json in the skill directory to define test cases.",
+      "Use the skill-creator skill or create manually per skill-eval-schema.json.",
+    ].join("\n");
+  }
+
+  const lines = [
+    `Skill: ${result.skill}`,
+    `Path: ${result.path}`,
+    `Evals: ${result.eval_count} test cases`,
+    `Scripts: ${result.has_scripts ? "Available (skill-creator)" : "Not available"}`,
+    "",
+  ];
+
+  for (const e of result.evals) {
+    const trigger = e.should_trigger ? "SHOULD" : "SHOULD NOT";
+    lines.push(`  [${e.id}] ${trigger} trigger`);
+    lines.push(`      ${e.prompt}`);
+    if (e.assertions > 0) {
+      lines.push(`      ${e.assertions} assertion(s)`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,49 @@
+/**
+ * frontmatter -- Extract YAML frontmatter from markdown files
+ *
+ * Usage:
+ *   frontmatter <file>    Extract frontmatter as JSON
+ *
+ * @module tools/commands/frontmatter
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  parseFrontmatter,
+} = require("../../core/alkimia/memory/thoughts-indexer");
+
+async function run(_command, args, projectRoot) {
+  if (args.length === 0) {
+    throw new Error("Usage: frontmatter <file-path>");
+  }
+
+  const filePath = path.isAbsolute(args[0])
+    ? args[0]
+    : path.join(projectRoot, args[0]);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const { frontmatter, bodyStart } = parseFrontmatter(content);
+
+  return {
+    file: path.relative(projectRoot, filePath),
+    frontmatter,
+    bodyStartLine: bodyStart,
+  };
+}
+
+function formatHuman(result) {
+  const lines = [`File: ${result.file}`, ""];
+  for (const [key, value] of Object.entries(result.frontmatter || {})) {
+    lines.push(`  ${key}: ${JSON.stringify(value)}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,43 @@
+/**
+ * heartbeat -- run a single proactive heartbeat beat (v3.4)
+ *
+ * Drives the core HeartbeatEngine once and returns the beat outcome as JSON.
+ * Intended to be invoked by the dashboard scheduler (`merlin heartbeat run`)
+ * on a timer, but runnable manually for testing.
+ *
+ *   merlin heartbeat run
+ *
+ * @module tools/commands/heartbeat
+ */
+
+"use strict";
+
+const { HeartbeatEngine } = require("../../core/execution/heartbeat-engine");
+
+async function run(_command, args, projectRoot) {
+  const sub = args[0] || "run";
+
+  if (sub !== "run") {
+    return { success: false, error: `Unknown heartbeat subcommand: ${sub}` };
+  }
+
+  const engine = new HeartbeatEngine({ projectRoot });
+  const result = await engine.run();
+
+  return {
+    success: result.status !== "error",
+    status: result.status, // ok | alert | error
+    message: result.message || null,
+    severity: result.severity || null,
+    error: result.error || null,
+  };
+}
+
+function formatHuman(result) {
+  if (result.status === "ok") return "HEARTBEAT_OK (nothing to report)";
+  if (result.status === "alert")
+    return `ALERT [${result.severity}]: ${result.message}`;
+  return `HEARTBEAT ERROR: ${result.error}`;
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/index-thoughts.js

@@ -0,0 +1,35 @@
+/**
+ * index-thoughts -- Rebuild thoughts INDEX.json and INDEX.md
+ *
+ * Wraps the existing thoughts-indexer to provide a CLI interface.
+ *
+ * @module tools/commands/index-thoughts
+ */
+
+"use strict";
+
+const path = require("path");
+const { writeIndex } = require("../../core/alkimia/memory/thoughts-indexer");
+
+async function run(_command, _args, projectRoot) {
+  const thoughtsPath = path.join(projectRoot, ".merlin-core", "thoughts");
+  const index = writeIndex(thoughtsPath);
+
+  return {
+    success: true,
+    entries: index.entries.length,
+    indexJsonPath: path.join(thoughtsPath, "shared", "INDEX.json"),
+    indexMdPath: path.join(thoughtsPath, "shared", "INDEX.md"),
+  };
+}
+
+function formatHuman(result) {
+  if (!result.success) return `FAILED: ${result.error}`;
+  return [
+    `Indexed ${result.entries} documents`,
+    `  JSON: ${result.indexJsonPath}`,
+    `  MD:   ${result.indexMdPath}`,
+  ].join("\n");
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,184 @@
+/**
+ * install-remote-approve -- Opt-in wiring for the remote-approve hook bridge.
+ *
+ * Turns ON remote Approve/Deny for a project (Phase 2 APPROVE): writes a
+ * per-project token, adds the PreToolUse hook to the project's
+ * `.claude/settings.json`, and lists the routed tools in `permissions.allow`
+ * so no separate `ask` rule pre-empts the hook (the hook becomes the gate).
+ *
+ * Usage:
+ *   install-remote-approve [path]                 enable for <path> (default: cwd project)
+ *   install-remote-approve [path] --tools a,b,c   customise routed tools
+ *   install-remote-approve [path] --dashboard-url http://127.0.0.1:3939
+ *   install-remote-approve [path] --disable       turn it off (enabled=false)
+ *
+ * Conservative by design (Constitution VII/XI): remote approval is OFF until a
+ * human runs this; ABSOLUTE/destructive actions are never remote-approvable
+ * (the bridge forces them to interactive `ask`).
+ *
+ * @module tools/commands/install-remote-approve
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const DEFAULT_TOOLS = ["Bash", "Edit", "Write", "MultiEdit", "NotebookEdit"];
+const DEFAULT_DASHBOARD = "http://127.0.0.1:3939";
+const HOOK_REL = path.join(
+  ".merlin-core",
+  "hooks",
+  "pretooluse-remote-approve.js",
+);
+
+function parseArgs(args) {
+  const out = { path: null, tools: null, dashboardUrl: null, disable: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--disable") out.disable = true;
+    else if (a === "--tools")
+      out.tools = (args[++i] || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    else if (a === "--dashboard-url") out.dashboardUrl = args[++i];
+    else if (!a.startsWith("--") && !out.path) out.path = a;
+  }
+  return out;
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+
+/** Absolute path to the hook to reference: prefer the target's own copy. */
+function resolveHookPath(target) {
+  const local = path.join(target, HOOK_REL);
+  if (fs.existsSync(local)) return local;
+  // Fall back to the framework copy adjacent to this installer.
+  const framework = path.resolve(
+    __dirname,
+    "..",
+    "..",
+    "hooks",
+    "pretooluse-remote-approve.js",
+  );
+  return framework;
+}
+
+/** Append/replace our PreToolUse hook in a settings.json hooks block. */
+function upsertHook(settings, matcher, command) {
+  settings.hooks = settings.hooks || {};
+  const list = Array.isArray(settings.hooks.PreToolUse)
+    ? settings.hooks.PreToolUse
+    : [];
+  const isOurs = (entry) =>
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some(
+      (h) =>
+        typeof h.command === "string" &&
+        h.command.includes("pretooluse-remote-approve"),
+    );
+  const ours = { matcher, hooks: [{ type: "command", command }] };
+  const idx = list.findIndex(isOurs);
+  if (idx >= 0) list[idx] = ours;
+  else list.push(ours);
+  settings.hooks.PreToolUse = list;
+  return settings;
+}
+
+/** Union routed tool names into permissions.allow (bare names → hook is the gate). */
+function ensureAllow(settings, tools) {
+  settings.permissions = settings.permissions || {};
+  const allow = Array.isArray(settings.permissions.allow)
+    ? settings.permissions.allow
+    : [];
+  for (const t of tools) if (!allow.includes(t)) allow.push(t);
+  settings.permissions.allow = allow;
+  return settings;
+}
+
+async function run(_command, args, projectRoot) {
+  const opts = parseArgs(args);
+  const target = path.resolve(opts.path || projectRoot);
+  if (!fs.existsSync(target))
+    throw new Error(`target path does not exist: ${target}`);
+
+  const cfgFile = path.join(target, ".merlin", "remote-approve.json");
+  const settingsFile = path.join(target, ".claude", "settings.json");
+
+  if (opts.disable) {
+    const cfg = readJson(cfgFile, {});
+    cfg.enabled = false;
+    cfg.disabledAt = new Date().toISOString();
+    writeJson(cfgFile, cfg);
+    return {
+      success: true,
+      enabled: false,
+      target,
+      message: "Remote approve DISABLED (hook left in place, but inert).",
+    };
+  }
+
+  const tools = opts.tools && opts.tools.length ? opts.tools : DEFAULT_TOOLS;
+  const dashboardUrl = opts.dashboardUrl || DEFAULT_DASHBOARD;
+
+  // 1) Per-project token (reuse an existing one so re-running doesn't break a live install).
+  const existing = readJson(cfgFile, {});
+  const token = existing.token || crypto.randomBytes(32).toString("hex");
+  writeJson(cfgFile, {
+    enabled: true,
+    token,
+    dashboardUrl,
+    routedTools: tools,
+    installedAt: existing.installedAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  });
+
+  // 2) Wire the hook + permissions into .claude/settings.json.
+  const hookPath = resolveHookPath(target).replace(/\\/g, "/");
+  const command = `node "${hookPath}"`;
+  const matcher = tools.join("|");
+  let settings = readJson(settingsFile, {});
+  settings = upsertHook(settings, matcher, command);
+  settings = ensureAllow(settings, tools);
+  writeJson(settingsFile, settings);
+
+  return {
+    success: true,
+    enabled: true,
+    target,
+    token: token.slice(0, 8) + "…",
+    routedTools: tools,
+    dashboardUrl,
+    settingsFile,
+    configFile: cfgFile,
+    message:
+      "Remote approve ENABLED. Restart the Claude Code session so the hook loads. " +
+      "ABSOLUTE/destructive actions stay interactive-only.",
+  };
+}
+
+function formatHuman(result) {
+  if (result.message && result.success) {
+    const lines = [`✅ ${result.message}`, `   target: ${result.target}`];
+    if (result.routedTools)
+      lines.push(`   tools:  ${result.routedTools.join(", ")}`);
+    if (result.dashboardUrl) lines.push(`   panel:  ${result.dashboardUrl}`);
+    return lines.join("\n");
+  }
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = { run, formatHuman, parseArgs, upsertHook, ensureAllow };