@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/validate-recipes.js

@@ -0,0 +1,218 @@
+/**
+ * validate-recipes — Validate the start-here skill's recipes.json.
+ *
+ * Runs:
+ *   1. JSON Schema validation against recipes.schema.json (ajv draft 2020-12)
+ *   2. Duplicate ID detection
+ *   3. Cross-reference: each commands[] entry must map to a real bridged
+ *      command (COMMAND_MAP value OR existing .claude/commands/*.md file)
+ *   4. Cross-reference: each related_agents[] entry must exist in
+ *      .merlin-core/development/agents/
+ *   5. Cross-reference: each related_skills[] entry must exist in
+ *      .merlin-core/skills/general/ or .merlin-core/skills/domain/
+ *
+ * Usage:
+ *   node merlin-tools.js validate-recipes [--human]
+ *
+ * @module tools/commands/validate-recipes
+ * @version 1.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { COMMAND_MAP } = require("./sync-bridges");
+
+/**
+ * Lazy ajv loader — returns the constructor when available, or null if the
+ * dependency is missing (e.g., running inside an installed project that has
+ * no node_modules). Schema validation is skipped when null; cross-reference
+ * checks still run.
+ */
+function tryLoadAjv() {
+  try {
+    return require("ajv/dist/2020");
+  } catch {
+    return null;
+  }
+}
+
+const SKILL_DIR_REL = path.join(
+  ".merlin-core",
+  "skills",
+  "general",
+  "start-here",
+);
+
+function buildValidCommandSet(projectRoot) {
+  const set = new Set();
+  for (const bridged of Object.values(COMMAND_MAP)) {
+    set.add("/" + bridged.replace(/\.md$/, ""));
+  }
+  const bridgeDir = path.join(projectRoot, ".claude", "commands");
+  if (fs.existsSync(bridgeDir)) {
+    for (const f of fs.readdirSync(bridgeDir)) {
+      if (f.endsWith(".md")) set.add("/" + f.replace(/\.md$/, ""));
+    }
+  }
+  return set;
+}
+
+function buildValidAgentSet(projectRoot) {
+  const set = new Set();
+  const dir = path.join(projectRoot, ".merlin-core", "development", "agents");
+  if (!fs.existsSync(dir)) return set;
+  for (const f of fs.readdirSync(dir)) {
+    if (f.endsWith(".md") && f !== "README.md") {
+      set.add(f.replace(/\.md$/, ""));
+    }
+  }
+  return set;
+}
+
+function buildValidSkillSet(projectRoot) {
+  const set = new Set();
+  for (const sub of ["general", "domain"]) {
+    const dir = path.join(projectRoot, ".merlin-core", "skills", sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(dir, entry.name, "SKILL.md");
+      if (fs.existsSync(skillFile)) set.add(entry.name);
+    }
+  }
+  return set;
+}
+
+async function run(_command, _args, projectRoot) {
+  const recipesPath = path.join(projectRoot, SKILL_DIR_REL, "recipes.json");
+  const schemaPath = path.join(
+    projectRoot,
+    SKILL_DIR_REL,
+    "recipes.schema.json",
+  );
+
+  const errors = [];
+
+  if (!fs.existsSync(recipesPath)) {
+    return {
+      valid: false,
+      count: 0,
+      errors: [
+        `recipes.json not found at ${path.relative(projectRoot, recipesPath)}`,
+      ],
+    };
+  }
+  if (!fs.existsSync(schemaPath)) {
+    return {
+      valid: false,
+      count: 0,
+      errors: [
+        `recipes.schema.json not found at ${path.relative(projectRoot, schemaPath)}`,
+      ],
+    };
+  }
+
+  let recipes;
+  let schema;
+  try {
+    recipes = JSON.parse(fs.readFileSync(recipesPath, "utf8"));
+  } catch (e) {
+    return {
+      valid: false,
+      count: 0,
+      errors: [`recipes.json parse error: ${e.message}`],
+    };
+  }
+  try {
+    schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+  } catch (e) {
+    return {
+      valid: false,
+      count: 0,
+      errors: [`recipes.schema.json parse error: ${e.message}`],
+    };
+  }
+
+  const Ajv2020 = tryLoadAjv();
+  let schemaSkipped = false;
+  if (Ajv2020) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const validate = ajv.compile(schema);
+    if (!validate(recipes)) {
+      for (const err of validate.errors || []) {
+        errors.push(
+          `schema: ${err.instancePath || "(root)"} ${err.message} ${
+            err.params ? JSON.stringify(err.params) : ""
+          }`.trim(),
+        );
+      }
+    }
+  } else {
+    schemaSkipped = true;
+  }
+
+  const count = Array.isArray(recipes) ? recipes.length : 0;
+  if (count > 0) {
+    const seen = new Set();
+    for (const r of recipes) {
+      if (!r || typeof r.id !== "string") continue;
+      if (seen.has(r.id)) errors.push(`duplicate id: '${r.id}'`);
+      seen.add(r.id);
+    }
+
+    const validCommands = buildValidCommandSet(projectRoot);
+    const validAgents = buildValidAgentSet(projectRoot);
+    const validSkills = buildValidSkillSet(projectRoot);
+
+    for (const r of recipes) {
+      if (!r || typeof r !== "object") continue;
+      const id = r.id || "(no-id)";
+      for (const cmd of r.commands || []) {
+        if (!validCommands.has(cmd)) {
+          errors.push(`recipe '${id}': unknown command '${cmd}'`);
+        }
+      }
+      for (const a of r.related_agents || []) {
+        if (!validAgents.has(a)) {
+          errors.push(`recipe '${id}': unknown agent '${a}'`);
+        }
+      }
+      for (const s of r.related_skills || []) {
+        if (!validSkills.has(s)) {
+          errors.push(`recipe '${id}': unknown skill '${s}'`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    count,
+    errors,
+    schemaSkipped,
+  };
+}
+
+function formatHuman(result) {
+  const suffix = result.schemaSkipped
+    ? " (schema check skipped — ajv unavailable; cross-refs OK)"
+    : "";
+  if (result.valid) {
+    return `✓ recipes.json valid (${result.count} recipes)${suffix}`;
+  }
+  const lines = [
+    `✗ recipes.json INVALID (${result.count} recipes, ${result.errors.length} issues)${suffix}:`,
+  ];
+  for (const e of result.errors) lines.push(`  • ${e}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  run,
+  formatHuman,
+  buildValidCommandSet,
+  buildValidAgentSet,
+  buildValidSkillSet,
+};

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

@@ -0,0 +1,159 @@
+/**
+ * validate -- Validate files against Merlin schemas
+ *
+ * Usage:
+ *   validate skill <file>       Validate SKILL.md against skill-schema.json
+ *   validate agent <file>       Validate agent .md against agent-schema.json
+ *   validate command <file>     Validate command .md against command-schema.json
+ *   validate workflow <file>    Check workflow YAML structure
+ *
+ * @module tools/commands/validate
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  parseFrontmatter,
+} = require("../../core/alkimia/memory/thoughts-indexer");
+
+function loadSchema(projectRoot, schemaName) {
+  const schemaPath = path.join(
+    projectRoot,
+    ".merlin-core",
+    "schemas",
+    schemaName,
+  );
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Schema not found: ${schemaPath}`);
+  }
+  return JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+}
+
+function validateAgainstSchema(data, schema) {
+  const errors = [];
+
+  // Check required fields
+  const required = schema.required || [];
+  for (const field of required) {
+    if (data[field] === undefined || data[field] === null) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Check property types and constraints
+  const props = schema.properties || {};
+  for (const [key, spec] of Object.entries(props)) {
+    if (data[key] === undefined) continue;
+
+    const value = data[key];
+
+    // Type check
+    if (spec.type === "string" && typeof value !== "string") {
+      errors.push(`${key}: expected string, got ${typeof value}`);
+    }
+    if (spec.type === "array" && !Array.isArray(value)) {
+      errors.push(`${key}: expected array, got ${typeof value}`);
+    }
+
+    // String constraints
+    if (spec.type === "string" && typeof value === "string") {
+      if (spec.minLength && value.length < spec.minLength) {
+        errors.push(
+          `${key}: min length ${spec.minLength}, got ${value.length}`,
+        );
+      }
+      if (spec.pattern) {
+        const regex = new RegExp(spec.pattern);
+        if (!regex.test(value)) {
+          errors.push(`${key}: does not match pattern ${spec.pattern}`);
+        }
+      }
+      if (spec.enum && !spec.enum.includes(value)) {
+        errors.push(
+          `${key}: must be one of [${spec.enum.join(", ")}], got "${value}"`,
+        );
+      }
+    }
+
+    // Array constraints
+    if (spec.type === "array" && Array.isArray(value)) {
+      if (spec.minItems && value.length < spec.minItems) {
+        errors.push(`${key}: min items ${spec.minItems}, got ${value.length}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+async function run(_command, args, projectRoot) {
+  if (args.length < 2) {
+    throw new Error(
+      "Usage: validate <type> <file-path>\nTypes: skill, agent, command, workflow",
+    );
+  }
+
+  const [type, rawPath] = args;
+  const filePath = path.isAbsolute(rawPath)
+    ? rawPath
+    : path.join(projectRoot, rawPath);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const parsed = parseFrontmatter(content);
+  const frontmatter = parsed.frontmatter || {};
+
+  const schemaMap = {
+    skill: "skill-schema.json",
+    agent: "agent-schema.json",
+    command: "command-schema.json",
+    workflow: "workflow-schema.json",
+    process: "process-schema.json", // v3.3.1: first ENFORCED thought-type schema (PROCESSO)
+  };
+
+  const schemaFile = schemaMap[type];
+  if (!schemaFile) {
+    throw new Error(
+      `Unknown type: ${type}. Must be one of: ${Object.keys(schemaMap).join(", ")}`,
+    );
+  }
+
+  const schema = loadSchema(projectRoot, schemaFile);
+
+  // Some schemas expect { frontmatter: { ... } } wrapper,
+  // others validate the frontmatter directly. Check which pattern.
+  const hasNestedFrontmatter = schema.properties?.frontmatter;
+  const dataToValidate = hasNestedFrontmatter ? { frontmatter } : frontmatter;
+  const schemaToValidate = hasNestedFrontmatter
+    ? schema
+    : schema.properties?.frontmatter || schema;
+
+  const errors = validateAgainstSchema(dataToValidate, schemaToValidate);
+
+  return {
+    file: path.relative(projectRoot, filePath),
+    type,
+    schema: schemaFile,
+    valid: errors.length === 0,
+    errors,
+    frontmatter,
+  };
+}
+
+function formatHuman(result) {
+  const status = result.valid ? "VALID" : "INVALID";
+  const lines = [`${status}: ${result.file} (${result.type})`];
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      lines.push(`  - ${err}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman, validateAgainstSchema };

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

@@ -0,0 +1,82 @@
+/**
+ * yolo -- Toggle YOLO (autonomous) execution mode
+ *
+ * Usage:
+ *   yolo           Show current YOLO mode state
+ *   yolo on        Enable YOLO mode (auto-approve MEDIUM actions)
+ *   yolo off       Disable YOLO mode (restore normal approvals)
+ *
+ * YOLO mode auto-approves LOW and MEDIUM stake actions.
+ * HIGH stake actions always require human approval (Article VII).
+ *
+ * @module tools/commands/yolo
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function getBridgePath(projectRoot) {
+  return path.join(projectRoot, '.merlin', 'context-bridge.json');
+}
+
+function readBridge(projectRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(getBridgePath(projectRoot), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeBridge(projectRoot, data) {
+  const bridgePath = getBridgePath(projectRoot);
+  const dir = path.dirname(bridgePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(bridgePath, JSON.stringify(data, null, 2));
+}
+
+async function run(_command, args, projectRoot) {
+  if (args.length === 0) {
+    // Show current state
+    const bridge = readBridge(projectRoot);
+    return {
+      yolo_mode: bridge.yolo_mode === true,
+      message: bridge.yolo_mode ? 'YOLO mode is ON' : 'YOLO mode is OFF',
+    };
+  }
+
+  const action = args[0].toLowerCase();
+
+  if (action === 'on') {
+    const bridge = readBridge(projectRoot);
+    bridge.yolo_mode = true;
+    bridge.yolo_enabled_at = new Date().toISOString();
+    writeBridge(projectRoot, bridge);
+    return {
+      success: true,
+      yolo_mode: true,
+      message: 'YOLO mode enabled. MEDIUM actions will auto-approve. HIGH actions still require human approval.',
+    };
+  }
+
+  if (action === 'off') {
+    const bridge = readBridge(projectRoot);
+    bridge.yolo_mode = false;
+    bridge.yolo_disabled_at = new Date().toISOString();
+    writeBridge(projectRoot, bridge);
+    return {
+      success: true,
+      yolo_mode: false,
+      message: 'YOLO mode disabled. Normal approval flow restored.',
+    };
+  }
+
+  throw new Error('Usage: yolo [on|off]');
+}
+
+function formatHuman(result) {
+  return result.message || JSON.stringify(result, null, 2);
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/compose-rules.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * compose-rules.mjs — generic Firestore rules composer (v3.5, net-new).
+ *
+ * Composes a base `firestore.rules` with per-module fragments (`rules/<id>.rules`)
+ * for `in-platform` modules that share one rules file (research §7.1). Blind
+ * concatenation is unsafe (two `match` on the same collection → last-wins →
+ * over-permit / lock-out), so this ALWAYS runs collection-overlap detection
+ * (pure, no deps). An optional emulator-backed positive/negative test gate runs
+ * only when @firebase/rules-unit-testing + a Firestore emulator are present; else
+ * it is skipped-with-warning (decided 2026-06-20). Overlap detection is the
+ * always-on safety net.
+ *
+ * Overlap heuristic (documented limit): every `match /<seg>/…` first-segment a
+ * fragment declares is treated as a collection it touches (nested matches count
+ * too — over-approximates, errs safe). The emulator gate is the precise check.
+ *
+ *   node compose-rules.mjs --base <f> --fragments-dir <d> --enabled a,b --out <f>
+ *
+ * @module tools/compose-rules
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Collection names a rules fragment touches (first segment of each `match /x/`). */
+export function extractCollections(content) {
+  const out = new Set();
+  const re = /\bmatch\s+\/([A-Za-z0-9_]+)/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    if (m[1] !== "databases") out.add(m[1]);
+  }
+  return [...out];
+}
+
+/**
+ * Detect collections claimed by more than one ENABLED fragment.
+ * @param {Array<{id, content, enabled}>} fragments
+ * @returns {Array<{collection, modules: string[]}>}
+ */
+export function detectOverlaps(fragments) {
+  const byCollection = new Map();
+  for (const f of fragments) {
+    if (!f.enabled) continue;
+    for (const col of extractCollections(f.content)) {
+      if (!byCollection.has(col)) byCollection.set(col, []);
+      byCollection.get(col).push(f.id);
+    }
+  }
+  const overlaps = [];
+  for (const [collection, modules] of byCollection) {
+    if (modules.length > 1) overlaps.push({ collection, modules });
+  }
+  return overlaps.sort((a, b) => a.collection.localeCompare(b.collection));
+}
+
+/**
+ * Compose base + enabled fragments into one rules string (delimited blocks).
+ * @returns {{generated: string, overlaps: Array}}
+ */
+export function composeRules({ baseRules = "", fragments = [] }) {
+  const enabled = fragments.filter((f) => f.enabled);
+  const blocks = enabled.map(
+    (f) => `// >>> module:${f.id}\n${f.content.trim()}\n// <<< module:${f.id}`,
+  );
+  const generated =
+    [baseRules.trim(), ...blocks].filter(Boolean).join("\n\n") + "\n";
+  return { generated, overlaps: detectOverlaps(fragments) };
+}
+
+async function canImport(spec) {
+  try {
+    await import(spec);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Optional positive/negative test gate. Runs only when @firebase/rules-unit-testing
+ * AND an emulator are reachable; otherwise returns {status:"skipped"}.
+ * Probes are injectable (`_available`, `_reachable`) so the gate is testable
+ * without a real emulator.
+ * @returns {Promise<{status:"skipped"|"ran"|"failed", reason?, results?}>}
+ */
+export async function testGate(fragments, opts = {}) {
+  const available =
+    opts._available !== undefined
+      ? opts._available
+      : await canImport("@firebase/rules-unit-testing");
+  const reachable =
+    opts._reachable !== undefined
+      ? opts._reachable
+      : Boolean(opts.emulatorHost || process.env.FIRESTORE_EMULATOR_HOST);
+
+  if (!available || !reachable) {
+    return {
+      status: "skipped",
+      reason: !available
+        ? "@firebase/rules-unit-testing not installed"
+        : "no Firestore emulator reachable (set FIRESTORE_EMULATOR_HOST)",
+    };
+  }
+
+  // Each fragment may ship a `spec` (a function asserting positive+negative access).
+  const results = [];
+  for (const f of fragments.filter(
+    (x) => x.enabled && typeof x.spec === "function",
+  )) {
+    try {
+      await f.spec();
+      results.push({ id: f.id, ok: true });
+    } catch (e) {
+      results.push({ id: f.id, ok: false, error: e.message });
+    }
+  }
+  const failed = results.filter((r) => !r.ok);
+  return { status: failed.length ? "failed" : "ran", results };
+}
+
+/** Read fragments from a dir given an `enabled` id list. */
+function loadFragmentsFromDir(dir, enabledIds) {
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith(".rules"));
+  return files.map((file) => {
+    const id = file.replace(/\.rules$/, "");
+    return {
+      id,
+      content: readFileSync(join(dir, file), "utf8"),
+      enabled: enabledIds.includes(id),
+    };
+  });
+}
+
+// --- CLI ---
+if (process.argv[1] && process.argv[1].endsWith("compose-rules.mjs")) {
+  const args = process.argv.slice(2);
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const apply = args.includes("--apply");
+  const basePath = get("--base");
+  const fragmentsDir = get("--fragments-dir");
+  const enabledIds = (get("--enabled") || "").split(",").filter(Boolean);
+  const out = get("--out");
+
+  const baseRules =
+    basePath && existsSync(basePath) ? readFileSync(basePath, "utf8") : "";
+  const fragments = fragmentsDir
+    ? loadFragmentsFromDir(fragmentsDir, enabledIds)
+    : [];
+  const { generated, overlaps } = composeRules({ baseRules, fragments });
+  const gate = await testGate(fragments);
+
+  console.log(
+    `\ncompose-rules — ${fragments.filter((f) => f.enabled).length} enabled fragment(s)`,
+  );
+  if (overlaps.length) {
+    console.log("  ⚠ collection overlaps (blind merge unsafe):");
+    for (const o of overlaps)
+      console.log(`      ${o.collection} ← ${o.modules.join(", ")}`);
+  } else {
+    console.log("  ✓ no collection overlaps");
+  }
+  console.log(
+    `  test gate: ${gate.status}${gate.reason ? ` (${gate.reason})` : ""}`,
+  );
+
+  if (apply && out) {
+    writeFileSync(out, generated);
+    console.log(`  wrote ${out}`);
+  } else {
+    console.log("\n----- generated (dry-run) -----\n" + generated);
+  }
+  process.exit(overlaps.length > 0 || gate.status === "failed" ? 1 : 0);
+}