@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,52 @@
+/**
+ * license -- inspect or refresh the local Merlin license (v3.5)
+ *
+ *   merlin license             Show the cached license status (offline, never throws)
+ *   merlin license --refresh   Send one heartbeat to the license server now
+ *
+ * `--refresh` is what the gate's grace-expired message points users at
+ * (gate.js:117). It ships INSIDE the npm package.
+ *
+ * @module tools/commands/license
+ */
+
+"use strict";
+
+async function run(_command, args, _projectRoot, deps = {}) {
+  const activation =
+    deps.activation || require("../../core/licensing/activation");
+  const publicKeyHex =
+    deps.publicKeyHex || require("../../core/licensing/license").PUBLIC_KEY_HEX;
+
+  if (args.includes("--refresh")) {
+    try {
+      const result = await activation.heartbeat({ publicKeyHex });
+      return { success: true, refreshed: true, ...result };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  // Offline status — never throws.
+  const result = await activation.status({ publicKeyHex });
+  return { success: true, ...result };
+}
+
+function formatHuman(result) {
+  if (!result.success) return `LICENSE: ${result.error}`;
+  if (result.refreshed) {
+    return `Heartbeat sent — status: ${result.status}.${
+      result.message_to_user ? ` ${result.message_to_user}` : ""
+    }`;
+  }
+  if (!result.valid) {
+    return `No valid license: ${result.reason || "invalid"}.`;
+  }
+  const exp = result.expires_at
+    ? new Date(result.expires_at * 1000).toISOString().slice(0, 10)
+    : "?";
+  const last = result.last_status ? `, last status: ${result.last_status}` : "";
+  return `License #${result.serial} valid (expires ${exp}${last}).`;
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,125 @@
+/**
+ * list -- List agents or skills from the framework
+ *
+ * Usage:
+ *   list-agents    List all registered agents
+ *   list-skills    List all skills with activation keywords
+ *
+ * @module tools/commands/list
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  parseFrontmatter,
+} = require("../../core/alkimia/memory/thoughts-indexer");
+
+function listAgents(projectRoot) {
+  const agentsDir = path.join(
+    projectRoot,
+    ".merlin-core",
+    "development",
+    "agents",
+  );
+  const agents = [];
+
+  if (!fs.existsSync(agentsDir)) return agents;
+
+  const files = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md"));
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(agentsDir, file), "utf8");
+      const { frontmatter } = parseFrontmatter(content);
+      agents.push({
+        id: frontmatter.name || path.basename(file, ".md"),
+        display_name: frontmatter.display_name || frontmatter.name || file,
+        description: frontmatter.description || "",
+        model: frontmatter.model || "opus",
+        tools: frontmatter.tools || [],
+        auto_activate: frontmatter.auto_activate || [],
+      });
+    } catch {
+      // Skip unparseable files
+    }
+  }
+
+  return agents;
+}
+
+function listSkills(projectRoot) {
+  const skillDirs = [
+    path.join(projectRoot, ".merlin-core", "skills", "general"),
+    path.join(projectRoot, ".merlin-core", "skills", "domain"),
+  ];
+  const skills = [];
+
+  for (const dir of skillDirs) {
+    if (!fs.existsSync(dir)) continue;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const skillFile = path.join(dir, entry.name, "SKILL.md");
+      if (!fs.existsSync(skillFile)) continue;
+
+      try {
+        const content = fs.readFileSync(skillFile, "utf8");
+        const { frontmatter } = parseFrontmatter(content);
+        const category = dir.includes("general") ? "general" : "domain";
+
+        skills.push({
+          name: frontmatter.name || entry.name,
+          description: frontmatter.description || "",
+          auto_activate: frontmatter.auto_activate || [],
+          version: frontmatter.version || "0.0.0",
+          category,
+        });
+      } catch {
+        // Skip unparseable files
+      }
+    }
+  }
+
+  return skills;
+}
+
+async function run(command, _args, projectRoot) {
+  if (command === "list-agents") {
+    const agents = listAgents(projectRoot);
+    return { count: agents.length, agents };
+  }
+
+  if (command === "list-skills") {
+    const skills = listSkills(projectRoot);
+    return { count: skills.length, skills };
+  }
+
+  throw new Error(`Unknown list command: ${command}`);
+}
+
+function formatHuman(result) {
+  if (result.agents) {
+    const header = `${result.count} agents:\n`;
+    const rows = result.agents.map(
+      (a) => `  ${a.id.padEnd(16)} ${a.display_name.padEnd(35)} [${a.model}]`,
+    );
+    return header + rows.join("\n");
+  }
+
+  if (result.skills) {
+    const header = `${result.count} skills:\n`;
+    const rows = result.skills.map(
+      (s) =>
+        `  ${s.name.padEnd(22)} ${s.category.padEnd(8)} keywords: ${(s.auto_activate || []).join(", ")}`,
+    );
+    return header + rows.join("\n");
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/migrate-alkimia.js

@@ -0,0 +1,271 @@
+/**
+ * migrate-alkimia -- Migration script for Synapse → Alkimia rebrand.
+ *
+ * Renames .synapse/ domain directories to .alkimia/ in managed projects
+ * and updates any manifest references. Safe to run multiple times (idempotent).
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js migrate-alkimia [project-path]
+ *   node .merlin-core/tools/merlin-tools.js migrate-alkimia --all
+ *   node .merlin-core/tools/merlin-tools.js migrate-alkimia --dry-run
+ *
+ * @module tools/commands/migrate-alkimia
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+/**
+ * Load managed projects from project-config.yaml (simple parser).
+ */
+function loadManagedProjects(projectRoot) {
+  const configPath = path.join(
+    projectRoot,
+    ".merlin-core",
+    "project-config.yaml",
+  );
+  if (!fs.existsSync(configPath)) return [];
+
+  const content = fs.readFileSync(configPath, "utf8");
+  const projects = [];
+  const pathRegex = /path:\s*['"]?([^'"#\n]+)['"]?/g;
+  let match;
+
+  while ((match = pathRegex.exec(content)) !== null) {
+    const p = match[1].trim();
+    if (p && fs.existsSync(p)) projects.push(p);
+  }
+
+  return projects;
+}
+
+/**
+ * Scan a project for .synapse/ directories (root and squads/).
+ */
+function findSynapseDirs(projectPath) {
+  const found = [];
+
+  // Root-level .synapse/
+  const rootSynapse = path.join(projectPath, ".synapse");
+  if (fs.existsSync(rootSynapse) && fs.statSync(rootSynapse).isDirectory()) {
+    found.push({ path: rootSynapse, location: "root" });
+  }
+
+  // Squads-level .synapse/ directories
+  const squadsDir = path.join(projectPath, "squads");
+  if (fs.existsSync(squadsDir)) {
+    try {
+      const entries = fs.readdirSync(squadsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const squadSynapse = path.join(squadsDir, entry.name, ".synapse");
+        if (
+          fs.existsSync(squadSynapse) &&
+          fs.statSync(squadSynapse).isDirectory()
+        ) {
+          found.push({ path: squadSynapse, location: `squads/${entry.name}` });
+        }
+      }
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Rename a .synapse/ directory to .alkimia/ using git mv if in a repo, else fs.rename.
+ */
+function renameDirectory(synapsePath, dryRun) {
+  const parentDir = path.dirname(synapsePath);
+  const alkimiaPath = path.join(parentDir, ".alkimia");
+
+  if (fs.existsSync(alkimiaPath)) {
+    return {
+      status: "skipped",
+      reason: ".alkimia/ already exists",
+      from: synapsePath,
+      to: alkimiaPath,
+    };
+  }
+
+  if (dryRun) {
+    return { status: "would-rename", from: synapsePath, to: alkimiaPath };
+  }
+
+  // Try git mv first (preserves history)
+  try {
+    execSync(`git mv "${synapsePath}" "${alkimiaPath}"`, {
+      cwd: parentDir,
+      stdio: "pipe",
+    });
+    return { status: "renamed-git", from: synapsePath, to: alkimiaPath };
+  } catch {
+    // Fallback to fs rename
+    try {
+      fs.renameSync(synapsePath, alkimiaPath);
+      return { status: "renamed-fs", from: synapsePath, to: alkimiaPath };
+    } catch (err) {
+      return { status: "error", from: synapsePath, error: err.message };
+    }
+  }
+}
+
+/**
+ * Update manifest file references from synapse to alkimia.
+ */
+function updateManifestRefs(alkimiaPath, dryRun) {
+  const manifestPath = path.join(alkimiaPath, "manifest");
+  if (!fs.existsSync(manifestPath)) return null;
+
+  const content = fs.readFileSync(manifestPath, "utf8");
+  if (!content.includes("synapse") && !content.includes("Synapse")) return null;
+
+  const updated = content.replace(/synapse/gi, (match) => {
+    if (match === "synapse") return "alkimia";
+    if (match === "Synapse") return "Alkimia";
+    if (match === "SYNAPSE") return "ALKIMIA";
+    return "alkimia";
+  });
+
+  if (dryRun) {
+    return { status: "would-update", file: manifestPath };
+  }
+
+  fs.writeFileSync(manifestPath, updated, "utf8");
+  return { status: "updated", file: manifestPath };
+}
+
+/**
+ * Main migration runner.
+ */
+async function run(command, args, projectRoot) {
+  const dryRun = args.includes("--dry-run");
+  const migrateAll = args.includes("--all");
+  const targetPaths = args.filter((a) => !a.startsWith("--"));
+
+  let projectPaths = [];
+
+  if (migrateAll) {
+    projectPaths = loadManagedProjects(projectRoot);
+    // Also include the framework itself
+    projectPaths.unshift(projectRoot);
+  } else if (targetPaths.length > 0) {
+    projectPaths = targetPaths.map((p) => path.resolve(p));
+  } else {
+    // Default: just the current framework
+    projectPaths = [projectRoot];
+  }
+
+  const results = {
+    dryRun,
+    projects: [],
+    summary: { scanned: 0, renamed: 0, skipped: 0, errors: 0 },
+  };
+
+  for (const projectPath of projectPaths) {
+    if (!fs.existsSync(projectPath)) {
+      results.projects.push({
+        path: projectPath,
+        status: "not-found",
+        directories: [],
+      });
+      continue;
+    }
+
+    results.summary.scanned++;
+    const synapseDirs = findSynapseDirs(projectPath);
+    const projectResult = {
+      path: projectPath,
+      name: path.basename(projectPath),
+      directoriesFound: synapseDirs.length,
+      actions: [],
+    };
+
+    if (synapseDirs.length === 0) {
+      projectResult.status = "clean";
+      projectResult.message =
+        "No .synapse/ directories found — already migrated or never used";
+    } else {
+      projectResult.status = "migrated";
+      for (const dir of synapseDirs) {
+        const renameResult = renameDirectory(dir.path, dryRun);
+        projectResult.actions.push(renameResult);
+
+        if (renameResult.status.startsWith("renamed")) {
+          results.summary.renamed++;
+          // Update manifest refs in the new .alkimia/ directory
+          const manifestResult = updateManifestRefs(renameResult.to, dryRun);
+          if (manifestResult) projectResult.actions.push(manifestResult);
+        } else if (renameResult.status === "would-rename") {
+          results.summary.renamed++;
+        } else if (renameResult.status === "skipped") {
+          results.summary.skipped++;
+        } else if (renameResult.status === "error") {
+          results.summary.errors++;
+        }
+      }
+    }
+
+    results.projects.push(projectResult);
+  }
+
+  return results;
+}
+
+function formatHuman(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(`  Alkimia Migration ${result.dryRun ? "(DRY RUN)" : ""}`);
+  lines.push("  " + "=".repeat(45));
+  lines.push("");
+
+  for (const project of result.projects) {
+    const icon =
+      project.status === "clean"
+        ? "[ok]"
+        : project.status === "migrated"
+          ? "[>>]"
+          : "[!!]";
+    lines.push(`  ${icon} ${project.name || project.path}`);
+
+    if (project.message) {
+      lines.push(`      ${project.message}`);
+    }
+
+    for (const action of project.actions || []) {
+      if (
+        action.status.includes("renamed") ||
+        action.status === "would-rename"
+      ) {
+        lines.push(`      .synapse/ -> .alkimia/ (${action.status})`);
+      } else if (
+        action.status === "updated" ||
+        action.status === "would-update"
+      ) {
+        lines.push(`      manifest refs updated (${action.status})`);
+      } else if (action.status === "skipped") {
+        lines.push(`      skipped: ${action.reason}`);
+      } else if (action.status === "error") {
+        lines.push(`      ERROR: ${action.error}`);
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push("  Summary:");
+  lines.push(`    Scanned:  ${result.summary.scanned} projects`);
+  lines.push(`    Renamed:  ${result.summary.renamed} directories`);
+  lines.push(`    Skipped:  ${result.summary.skipped}`);
+  lines.push(`    Errors:   ${result.summary.errors}`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,68 @@
+/**
+ * modules -- List + validate the Merlin Modules catalog.
+ *
+ * Thin CommonJS bridge to the ESM registry (modules-catalog.mjs): walks
+ * `.merlin-core/modules/<id>/module.json`, validates each against the schema,
+ * and reports framework-face refs (skills/agents/commands/checklists) that do
+ * not resolve on disk.
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js modules            (JSON)
+ *   node .merlin-core/tools/merlin-tools.js modules --human    (table)
+ *
+ * Exit-code semantics live in modules-catalog.mjs's own CLI; this command
+ * always returns the catalog object (the dispatcher prints it and exits 0).
+ *
+ * @module tools/commands/modules
+ */
+
+"use strict";
+
+const path = require("path");
+const { pathToFileURL } = require("url");
+
+async function run(_command, _args, _projectRoot) {
+  // Import the sibling ESM registry by file URL (Windows-safe).
+  const catalogUrl = pathToFileURL(
+    path.join(__dirname, "..", "modules-catalog.mjs"),
+  ).href;
+  const { loadCatalog } = await import(catalogUrl);
+  const catalog = loadCatalog();
+
+  return {
+    count: catalog.modules.length,
+    invalid: catalog.invalid,
+    integrity: catalog.integrity,
+    ok: catalog.invalid.length === 0 && catalog.integrity.length === 0,
+    modules: catalog.modules.map((m) => ({
+      id: m.id,
+      name: m.name,
+      kind: m.kind,
+      deploy_kind: m.deploy_kind,
+      tier_min: m.tier_min,
+      version: m.version,
+    })),
+  };
+}
+
+function formatHuman(result) {
+  const lines = [
+    `${result.count} module(s) — ${result.invalid.length} invalid, ${result.integrity.length} with missing refs:`,
+  ];
+  for (const m of result.modules) {
+    lines.push(
+      `  ✓ ${m.id.padEnd(16)} ${m.kind.padEnd(20)} ${m.deploy_kind.padEnd(16)} tier:${String(m.tier_min).padEnd(8)} v${m.version}`,
+    );
+  }
+  for (const bad of result.invalid) {
+    lines.push(`  ✗ ${bad.dir}`);
+    for (const err of bad.errors) lines.push(`      ${err}`);
+  }
+  for (const issue of result.integrity) {
+    lines.push(`  ⚠ ${issue.id} — framework refs not found on disk:`);
+    for (const ref of issue.missing) lines.push(`      ${ref}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

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

@@ -0,0 +1,83 @@
+/**
+ * provision -- Provision (unlock) a Merlin Module.
+ *
+ * CommonJS bridge to the ESM orchestrator (provision-module.mjs). Dispatches by
+ * `deploy_kind`: `framework-skill` executes (writes config/modules.enabled[] on
+ * --apply); cloud deploy_kinds plan-emit via the default PlanOnlyDeployer.
+ * Dry-run by default.
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js provision --module=<id> [--apply]
+ *   node .merlin-core/tools/merlin-tools.js provision --module=<id> \
+ *        --workspace=<ws> --tier=time --firebase-project=<fp> [--apply]
+ *
+ * @module tools/commands/provision
+ */
+
+"use strict";
+
+const path = require("path");
+const { pathToFileURL } = require("url");
+
+function val(args, flag) {
+  const eq = args.find((a) => a.startsWith(`${flag}=`));
+  if (eq) return eq.split("=").slice(1).join("=");
+  const i = args.indexOf(flag);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")
+    ? args[i + 1]
+    : undefined;
+}
+
+async function run(_command, args, projectRoot) {
+  const url = pathToFileURL(
+    path.join(__dirname, "..", "provision-module.mjs"),
+  ).href;
+  const { provisionModule } = await import(url);
+  return provisionModule({
+    projectRoot,
+    moduleId: val(args, "--module"),
+    workspace: val(args, "--workspace"),
+    tier: val(args, "--tier"),
+    firebaseProject: val(args, "--firebase-project"),
+    apply: args.includes("--apply"),
+    log: (m) => console.log(m),
+  });
+}
+
+function formatHuman(result) {
+  if (!result.ok) {
+    return `✗ provision failed${result.moduleId ? ` (${result.moduleId})` : ""}: ${result.error}`;
+  }
+  const lines = [
+    `module: ${result.moduleId}  deploy_kind: ${result.deploy_kind}  applied: ${result.applied}`,
+    `entitlement (${result.entitlement.basis}): ${result.entitlement.entitled ? "granted" : "warn"} — ${result.entitlement.reason}`,
+  ];
+  if (result.missingDeps && result.missingDeps.length) {
+    lines.push(`⚠ missing deps: ${result.missingDeps.join(", ")}`);
+  }
+  if (result.verify) {
+    lines.push(
+      `verify: ${result.verify.ok ? "pass" : result.verify.planned ? "planned" : "FAIL"}`,
+    );
+    for (const c of result.verify.checks || []) {
+      lines.push(`    ${c.ok ? "✓" : "·"} ${c.name} — ${c.detail}`);
+    }
+  }
+  if (result.deploy_kind === "framework-skill" && result.activation) {
+    lines.push(
+      result.activation.changed
+        ? `activation: ${result.applied ? "enabled" : "would enable"} modules.enabled += ${result.moduleId}`
+        : `activation: already enabled (no-op)`,
+    );
+  }
+  if (result.steps) {
+    lines.push(
+      `plan (${result.steps.length} steps, executed: ${result.applied}):`,
+    );
+    for (const s of result.steps) lines.push(`    ${s.name}: ${s.command}`);
+    if (result.note) lines.push(`note: ${result.note}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };