@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/alkimia/utils/frontmatter.js

@@ -0,0 +1,321 @@
+/**
+ * Shared Frontmatter Parser
+ * Unified YAML frontmatter parsing for Merlin Core.
+ *
+ * Replaces 3 independent parsers:
+ *   - L6 SkillLayer._parseSkillFrontmatter()
+ *   - SkillDispatcher._parseFrontmatter()
+ *   - SkillImporter.validateSkill() inline parser
+ *
+ * Handles: \r\n line endings, inline arrays [a, b], multi-line arrays (- item),
+ * nested maps, quoted strings, allowed-tools whitespace split.
+ *
+ * v3.0.0: Agent Skills Standard compliance — Merlin-specific attributes
+ * (auto_activate, tool_reminders, file_triggers) now read from BOTH top-level
+ * (legacy) and metadata.* (standard-compliant). Top-level takes precedence.
+ *
+ * @module frontmatter
+ * @since v3.0.0
+ */
+
+"use strict";
+
+/**
+ * Escape a string for safe interpolation into a RegExp.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract raw frontmatter block from content.
+ * @param {string} content - Full file content
+ * @returns {{ raw: string|null, body: string }}
+ */
+function extractFrontmatter(content) {
+  // L3 fix: support empty frontmatter (---\n---) by making inner content optional
+  const match = content.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---/);
+  if (!match) return { raw: null, body: content };
+
+  // Empty frontmatter (---\n---) returns null — callers treat null as "no metadata"
+  const raw = match[1] || null;
+  const body = content.slice(match[0].length).replace(/^\r?\n/, "");
+  return { raw, body };
+}
+
+/**
+ * Parse a YAML scalar field from frontmatter text.
+ * @param {string} frontmatter - Raw frontmatter text (between --- delimiters)
+ * @param {string} fieldName - YAML field name
+ * @returns {string|null}
+ */
+function parseYamlScalar(frontmatter, fieldName) {
+  // L1 fix: escape fieldName for safe regex interpolation
+  const match = frontmatter.match(
+    new RegExp(`^${escapeRegExp(fieldName)}:\\s*(.+)$`, "m"),
+  );
+  if (!match) return null;
+  // L2 fix: only strip balanced (matching) quotes
+  const v = match[1].trim();
+  if (
+    (v.startsWith('"') && v.endsWith('"')) ||
+    (v.startsWith("'") && v.endsWith("'"))
+  ) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * Parse a YAML array field from frontmatter text.
+ * Supports both inline `[a, b]` and multi-line `- a\n- b` formats.
+ * @param {string} frontmatter - Raw frontmatter text
+ * @param {string} fieldName - YAML field name
+ * @returns {string[]}
+ */
+function parseYamlArray(frontmatter, fieldName) {
+  // Bracket format: field: [a, b, c] — may span multiple lines
+  // L1 fix: escape fieldName for safe regex interpolation
+  const bracketMatch = frontmatter.match(
+    new RegExp(`${escapeRegExp(fieldName)}:\\s*\\[([\\s\\S]*?)\\]`),
+  );
+  if (bracketMatch) {
+    return bracketMatch[1]
+      .split(",")
+      .map((s) =>
+        s
+          .trim()
+          .replace(/[\r\n]/g, "")
+          .replace(/['"]/g, ""),
+      )
+      .filter(Boolean);
+  }
+
+  // Multi-line format: - item
+  const lines = frontmatter.split(/\r?\n/);
+  const fieldIdx = lines.findIndex((l) => l.trim().startsWith(`${fieldName}:`));
+  if (fieldIdx === -1) return [];
+
+  const items = [];
+  for (let i = fieldIdx + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith("- ")) {
+      items.push(
+        line
+          .substring(2)
+          .trim()
+          .replace(/^['"]|['"]$/g, ""),
+      );
+    } else if (line && !line.startsWith("#")) {
+      break;
+    }
+  }
+  return items;
+}
+
+/**
+ * Parse a YAML map field from frontmatter text.
+ * Supports indented key: value pairs under the parent field.
+ * @param {string} frontmatter - Raw frontmatter text
+ * @param {string} fieldName - YAML field name
+ * @returns {Object}
+ */
+function parseYamlMap(frontmatter, fieldName) {
+  const lines = frontmatter.split(/\r?\n/);
+  const fieldIdx = lines.findIndex((l) => l.trim().startsWith(`${fieldName}:`));
+  if (fieldIdx === -1) return {};
+
+  // Check if inline value exists (not a block map)
+  const inlineVal = lines[fieldIdx].replace(`${fieldName}:`, "").trim();
+  if (inlineVal && inlineVal !== "") return {};
+
+  const result = {};
+  for (let i = fieldIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.match(/^\s+/)) break;
+    const kvMatch = line.match(/^\s+([a-zA-Z0-9_-]+):\s*(.+)$/);
+    if (kvMatch) {
+      result[kvMatch[1]] = kvMatch[2].trim().replace(/^['"]|['"]$/g, "");
+    }
+  }
+  return result;
+}
+
+/**
+ * Parse all fields from a frontmatter block into a flat key-value object.
+ * Used by skill-dispatcher for generic metadata extraction.
+ * @param {string} frontmatter - Raw frontmatter text
+ * @returns {Object}
+ */
+function parseAllFields(frontmatter) {
+  const metadata = {};
+  const lines = frontmatter.split(/\r?\n/);
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    // Skip indented lines (nested map children)
+    if (line.match(/^\s+/)) continue;
+
+    let value = line.substring(colonIndex + 1).trim();
+
+    // Handle inline arrays: [a, b, c]
+    if (value.startsWith("[") && value.endsWith("]")) {
+      value = value
+        .slice(1, -1)
+        .split(",")
+        .map((v) => v.trim().replace(/['"]/g, ""));
+    }
+    // Handle quoted strings (L2 fix: balanced quotes only)
+    else if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    // N12 fix: skip fields with empty values (multi-line arrays/maps on next lines)
+    // to avoid overwriting typed parser results with "" when spread
+    if (value === "") continue;
+
+    metadata[key] = value;
+  }
+
+  return metadata;
+}
+
+/**
+ * Extract the raw text block under a YAML map field (e.g., "metadata:").
+ * Returns the indented sub-block as raw text so that parseYamlArray/parseYamlScalar
+ * can operate on nested fields like metadata.auto_activate.
+ *
+ * @param {string} frontmatter - Raw frontmatter text
+ * @param {string} fieldName - Parent map field name (e.g., "metadata")
+ * @returns {string} Raw text of the indented sub-block, with indentation removed.
+ *                   Returns "" if field not found or has inline value.
+ */
+function extractMapBlock(frontmatter, fieldName) {
+  const lines = frontmatter.split(/\r?\n/);
+  const fieldIdx = lines.findIndex((l) => l.trim().startsWith(`${fieldName}:`));
+  if (fieldIdx === -1) return "";
+
+  const inlineVal = lines[fieldIdx].replace(`${fieldName}:`, "").trim();
+  if (inlineVal && inlineVal !== "") return "";
+
+  const blockLines = [];
+  for (let i = fieldIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.match(/^\s+/)) break;
+    // Remove first level of indentation (2 spaces) to make it parseable as top-level YAML
+    blockLines.push(line.replace(/^\s{2}/, ""));
+  }
+  return blockLines.join("\n");
+}
+
+/**
+ * Parse skill-specific frontmatter fields with Merlin + Agent Skills Standard support.
+ *
+ * v3.0.0: Dual-source parsing for auto_activate, tool_reminders, file_triggers.
+ * Reads from top-level first (legacy), falls back to metadata.* (standard-compliant).
+ * Top-level takes precedence for backward compatibility.
+ *
+ * @param {string} content - Full SKILL.md content
+ * @returns {{ fields: Object, body: string }}
+ */
+function parseSkillFrontmatter(content) {
+  const empty = {
+    fields: {
+      name: null,
+      description: null,
+      autoActivate: [],
+      toolReminders: [],
+      fileTriggers: [],
+      license: null,
+      compatibility: null,
+      metadata: {},
+      allowedTools: [],
+    },
+    body: content,
+  };
+
+  const { raw, body } = extractFrontmatter(content);
+  if (!raw) return empty;
+
+  const name = parseYamlScalar(raw, "name");
+  const description = parseYamlScalar(raw, "description");
+  const license = parseYamlScalar(raw, "license");
+  const compatibility = parseYamlScalar(raw, "compatibility");
+  const metadata = parseYamlMap(raw, "metadata");
+
+  // Dual-source: top-level (legacy) takes precedence over metadata.* (v3 standard)
+  const metaBlock = extractMapBlock(raw, "metadata");
+
+  const topAutoActivate = parseYamlArray(raw, "auto_activate");
+  const autoActivate =
+    topAutoActivate.length > 0
+      ? topAutoActivate
+      : parseYamlArray(metaBlock, "auto_activate");
+
+  const topToolReminders = parseYamlArray(raw, "tool_reminders");
+  const toolReminders =
+    topToolReminders.length > 0
+      ? topToolReminders
+      : parseYamlArray(metaBlock, "tool_reminders");
+
+  const topFileTriggers = parseYamlArray(raw, "file_triggers");
+  const fileTriggers =
+    topFileTriggers.length > 0
+      ? topFileTriggers
+      : parseYamlArray(metaBlock, "file_triggers");
+
+  const allowedToolsRaw =
+    parseYamlScalar(raw, "allowed-tools") ||
+    parseYamlScalar(metaBlock, "allowed_tools");
+  const allowedTools = allowedToolsRaw
+    ? allowedToolsRaw.split(/\s+/).filter(Boolean)
+    : [];
+
+  return {
+    fields: {
+      name,
+      description,
+      autoActivate,
+      toolReminders,
+      fileTriggers,
+      license,
+      compatibility,
+      metadata,
+      allowedTools,
+    },
+    body,
+  };
+}
+
+/**
+ * Parse generic frontmatter from any markdown content.
+ * Used by skill-dispatcher for generic metadata extraction.
+ * @param {string} content - Full file content
+ * @returns {{ fields: Object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const { raw, body } = extractFrontmatter(content);
+  if (!raw) return { fields: {}, body: content };
+
+  return { fields: parseAllFields(raw), body };
+}
+
+module.exports = {
+  escapeRegExp,
+  extractFrontmatter,
+  extractMapBlock,
+  parseYamlScalar,
+  parseYamlArray,
+  parseYamlMap,
+  parseAllFields,
+  parseSkillFrontmatter,
+  parseFrontmatter,
+};

package/.merlin-core/core/alkimia/utils/tokens.js

@@ -0,0 +1,24 @@
+/**
+ * ALKIMIA Token Utilities
+ *
+ * Shared token estimation used by formatter and memory bridge.
+ *
+ * @module core/alkimia/utils/tokens
+ * @version 3.0.0
+ */
+
+"use strict";
+
+/**
+ * Estimate the number of tokens from a string.
+ *
+ * Uses the proven heuristic: tokens ~ string.length / 4
+ *
+ * @param {string} text - Text to estimate
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  return Math.ceil((text || "").length / 4);
+}
+
+module.exports = { estimateTokens };

package/.merlin-core/core/approval/README.md

@@ -0,0 +1,16 @@
+# Approval Engine
+
+The approval module manages human approval workflows with configurable stake levels (LOW, MEDIUM, HIGH). It supports multiple notification and interaction channels including CLI prompts and Slack integration, enabling transparent and traceable approval decisions.
+
+## Contents
+
+- **stake-levels/** - Configuration and logic for LOW, MEDIUM, HIGH approval requirements
+- **channels/cli/** - Command-line interface for approvals and decisions
+- **channels/slack/** - Slack integration for notifications and approval responses
+- **approval-manager.js** - Core approval workflow orchestrator
+- **policies.json** - Approval policies and escalation rules
+
+## Related
+
+- [Quality Gates](../quality-gates/README.md)
+- [Orchestration](../orchestration/README.md)