@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/alkimia/skill-importer.js

@@ -0,0 +1,440 @@
+/**
+ * Skill Importer — Import Agent Skills Standard compatible skills
+ *
+ * Imports community skills from external directories into Merlin's
+ * skill system. Validates against the Agent Skills Standard
+ * (agentskills.io) naming and metadata rules.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/alkimia/skill-importer
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs").promises;
+const path = require("path");
+const {
+  extractFrontmatter,
+  parseYamlScalar,
+  parseYamlMap,
+} = require("./utils/frontmatter");
+
+/**
+ * Standard subdirectories supported by Agent Skills Standard.
+ * @constant {string[]}
+ */
+const STANDARD_SUBDIRS = ["scripts", "references", "assets"];
+
+/**
+ * Target directory for imported skills.
+ * @constant {string}
+ */
+const IMPORT_TARGET = ".merlin-core/skills/general";
+
+/**
+ * SkillImporter — Import and manage Agent Skills Standard compatible skills.
+ */
+class SkillImporter {
+  /**
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} [options]
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.targetDir = path.join(projectRoot, IMPORT_TARGET);
+    this.options = { debug: false, ...options };
+  }
+
+  /**
+   * Validate a skill directory against Agent Skills Standard.
+   *
+   * Checks:
+   * - SKILL.md exists
+   * - `name` field present and valid format (lowercase, hyphens, max 64 chars)
+   * - `description` field present
+   *
+   * @param {string} skillPath - Path to skill directory
+   * @returns {Promise<{valid: boolean, errors: string[], warnings: string[], parsed: Object}>}
+   */
+  async validateSkill(skillPath) {
+    const errors = [];
+    const warnings = [];
+    const parsed = {};
+
+    // Check SKILL.md exists
+    const skillFile = path.join(skillPath, "SKILL.md");
+    try {
+      await fs.access(skillFile);
+    } catch {
+      errors.push("SKILL.md not found in skill directory");
+      return { valid: false, errors, warnings, parsed };
+    }
+
+    // Parse frontmatter using shared parser
+    const content = await fs.readFile(skillFile, "utf8");
+    const { raw } = extractFrontmatter(content);
+    if (!raw) {
+      errors.push("SKILL.md has no YAML frontmatter (missing --- delimiters)");
+      return { valid: false, errors, warnings, parsed };
+    }
+
+    // Extract name
+    const name = parseYamlScalar(raw, "name");
+    if (!name) {
+      errors.push("Required field 'name' is missing from frontmatter");
+    } else {
+      parsed.name = name;
+
+      // Validate name format
+      if (name.length > 64) {
+        errors.push(`Name exceeds 64-character limit (${name.length} chars)`);
+      }
+      if (name !== name.toLowerCase()) {
+        warnings.push(
+          "Name contains uppercase characters — standard requires lowercase",
+        );
+      }
+      if (/[^a-z0-9-]/.test(name)) {
+        warnings.push(
+          "Name contains non-standard characters (only a-z, 0-9, hyphens allowed)",
+        );
+      }
+      if (name.startsWith("-") || name.endsWith("-")) {
+        warnings.push("Name has leading/trailing hyphens");
+      }
+      if (/--/.test(name)) {
+        warnings.push("Name has consecutive hyphens");
+      }
+    }
+
+    // Extract description
+    const desc = parseYamlScalar(raw, "description");
+    if (!desc) {
+      errors.push("Required field 'description' is missing from frontmatter");
+    } else {
+      parsed.description = desc;
+      if (desc.length > 1024) {
+        warnings.push(
+          `Description exceeds 1024-character recommendation (${desc.length} chars)`,
+        );
+      }
+    }
+
+    // Check optional standard fields
+    const license = parseYamlScalar(raw, "license");
+    if (license) parsed.license = license;
+    const compatibility = parseYamlScalar(raw, "compatibility");
+    if (compatibility) parsed.compatibility = compatibility;
+
+    // Check subdirectories
+    parsed.subdirs = {};
+    for (const sub of STANDARD_SUBDIRS) {
+      const subPath = path.join(skillPath, sub);
+      try {
+        await fs.access(subPath);
+        parsed.subdirs[sub] = true;
+      } catch {
+        parsed.subdirs[sub] = false;
+      }
+    }
+
+    return { valid: errors.length === 0, errors, warnings, parsed };
+  }
+
+  /**
+   * Import a standard-format skill directory into Merlin's skill system.
+   *
+   * @param {string} sourcePath - Path to source skill directory
+   * @param {Object} [options]
+   * @param {string} [options.targetDir] - Override target directory
+   * @param {boolean} [options.force=false] - Overwrite existing skill
+   * @returns {Promise<{success: boolean, skillId: string, errors: string[], warnings: string[]}>}
+   */
+  async importFromDirectory(sourcePath, options = {}) {
+    // Validate first
+    const validation = await this.validateSkill(sourcePath);
+    if (!validation.valid) {
+      return {
+        success: false,
+        skillId: null,
+        errors: validation.errors,
+        warnings: validation.warnings,
+      };
+    }
+
+    const rawSkillId = validation.parsed.name || path.basename(sourcePath);
+    // H3 fix: sanitize skillId — reject path separators and traversal
+    // N24 fix: loop sanitization until stable (e.g. "...." -> ".." -> "")
+    let skillId = rawSkillId.replace(/[/\\]/g, "");
+    let prev;
+    do {
+      prev = skillId;
+      skillId = skillId.replace(/\.\./g, "");
+    } while (skillId !== prev);
+    if (!skillId || /[/\\]/.test(skillId) || skillId.includes("..")) {
+      return {
+        success: false,
+        skillId: null,
+        errors: ["Skill name contains invalid path characters"],
+        warnings: [],
+      };
+    }
+    const targetBase = options.targetDir || this.targetDir;
+    const targetPath = path.join(targetBase, skillId);
+    const resolvedTarget = path.resolve(targetBase);
+    const resolvedSkillPath = path.resolve(targetPath);
+    if (!resolvedSkillPath.startsWith(resolvedTarget + path.sep)) {
+      return {
+        success: false,
+        skillId: null,
+        errors: ["Path traversal detected in skill name"],
+        warnings: [],
+      };
+    }
+
+    // Check if already exists
+    try {
+      await fs.access(targetPath);
+      if (!options.force) {
+        return {
+          success: false,
+          skillId,
+          errors: [
+            `Skill "${skillId}" already exists. Use force: true to overwrite.`,
+          ],
+          warnings: validation.warnings,
+        };
+      }
+    } catch {
+      // Target doesn't exist — good
+    }
+
+    // Create target directory
+    await fs.mkdir(targetPath, { recursive: true });
+
+    // Copy SKILL.md with import metadata
+    const sourceSkillFile = path.join(sourcePath, "SKILL.md");
+    const content = await fs.readFile(sourceSkillFile, "utf8");
+    const updatedContent = this._addImportMetadata(content);
+    await fs.writeFile(
+      path.join(targetPath, "SKILL.md"),
+      updatedContent,
+      "utf8",
+    );
+
+    // Copy standard subdirectories
+    for (const sub of STANDARD_SUBDIRS) {
+      const subSource = path.join(sourcePath, sub);
+      try {
+        await fs.access(subSource);
+        await this._copyDir(subSource, path.join(targetPath, sub));
+      } catch {
+        // Subdirectory doesn't exist — skip
+      }
+    }
+
+    this._log(`Imported skill "${skillId}" from ${sourcePath}`);
+
+    return {
+      success: true,
+      skillId,
+      errors: [],
+      warnings: validation.warnings,
+    };
+  }
+
+  /**
+   * List all imported skills (those with metadata.imported: true).
+   *
+   * @returns {Promise<Array<{id: string, importedAt: string, path: string}>>}
+   */
+  async listImported() {
+    const imported = [];
+
+    try {
+      const entries = await fs.readdir(this.targetDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const skillFile = path.join(this.targetDir, entry.name, "SKILL.md");
+        try {
+          const content = await fs.readFile(skillFile, "utf8");
+          const { raw } = extractFrontmatter(content);
+          if (!raw) continue;
+
+          // Check for imported marker using shared parser
+          const meta = parseYamlMap(raw, "metadata");
+          if (meta.imported === "true") {
+            imported.push({
+              id: entry.name,
+              importedAt: meta["imported-at"] || "unknown",
+              path: path.join(this.targetDir, entry.name),
+            });
+          }
+        } catch {
+          // Can't read — skip
+        }
+      }
+    } catch {
+      // Directory doesn't exist
+    }
+
+    return imported;
+  }
+
+  /**
+   * Remove an imported skill.
+   *
+   * @param {string} skillName - Skill name to remove
+   * @returns {Promise<{success: boolean, error: string|null}>}
+   */
+  async removeImported(skillName) {
+    // C1 fix: Validate skill name contains no path separators or traversal
+    if (!skillName || /[/\\]/.test(skillName) || skillName.includes("..")) {
+      return {
+        success: false,
+        error:
+          "Invalid skill name — must not contain path separators or traversal",
+      };
+    }
+
+    const skillPath = path.join(this.targetDir, skillName);
+    const resolvedTarget = path.resolve(this.targetDir);
+    const resolvedSkill = path.resolve(skillPath);
+    if (!resolvedSkill.startsWith(resolvedTarget + path.sep)) {
+      return {
+        success: false,
+        error: "Path traversal detected — refusing to remove",
+      };
+    }
+
+    try {
+      await fs.access(skillPath);
+    } catch {
+      return { success: false, error: `Skill "${skillName}" not found` };
+    }
+
+    // Verify it's an imported skill using shared parser
+    const skillFile = path.join(skillPath, "SKILL.md");
+    try {
+      const content = await fs.readFile(skillFile, "utf8");
+      const { raw } = extractFrontmatter(content);
+      // N7 fix: refuse deletion when frontmatter is missing or has no imported marker
+      if (!raw) {
+        return {
+          success: false,
+          error: `Skill "${skillName}" has no frontmatter — cannot verify import status, refusing to remove`,
+        };
+      }
+      const meta = parseYamlMap(raw, "metadata");
+      if (meta.imported !== "true") {
+        return {
+          success: false,
+          error: `Skill "${skillName}" is not an imported skill — refusing to remove built-in skill`,
+        };
+      }
+    } catch {
+      return {
+        success: false,
+        error: `Cannot read SKILL.md for "${skillName}"`,
+      };
+    }
+
+    await fs.rm(skillPath, { recursive: true, force: true });
+    this._log(`Removed imported skill "${skillName}"`);
+
+    return { success: true, error: null };
+  }
+
+  /**
+   * Add import metadata to SKILL.md frontmatter.
+   *
+   * @param {string} content - Original SKILL.md content
+   * @returns {string} Updated content with import metadata
+   * @private
+   */
+  _addImportMetadata(content) {
+    // N10 fix: use extractFrontmatter for reliable boundary detection
+    const { raw, body } = extractFrontmatter(content);
+    if (!raw) return content;
+
+    // L4 fix: detect original line ending style and preserve it
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    let fm = raw;
+
+    // Check if metadata block exists
+    if (fm.includes("metadata:")) {
+      // Add imported fields under existing metadata
+      const lines = fm.split(/\r?\n/);
+      const metaIdx = lines.findIndex((l) => l.trim().startsWith("metadata:"));
+
+      // Find the last indented line under metadata
+      let insertIdx = metaIdx + 1;
+      while (insertIdx < lines.length && lines[insertIdx].match(/^\s+/)) {
+        insertIdx++;
+      }
+
+      lines.splice(
+        insertIdx,
+        0,
+        "  imported: true",
+        `  imported-at: "${new Date().toISOString()}"`,
+      );
+      fm = lines.join(eol);
+    } else {
+      // Add metadata block
+      fm += `${eol}metadata:${eol}  imported: true`;
+      fm += `${eol}  imported-at: "${new Date().toISOString()}"`;
+    }
+
+    // Reconstruct with consistent line endings
+    return `---${eol}${fm}${eol}---${eol}${body}`;
+  }
+
+  /**
+   * Recursively copy a directory with depth limit.
+   *
+   * @param {string} src - Source directory
+   * @param {string} dest - Destination directory
+   * @param {number} [depth=0] - Current recursion depth
+   * @private
+   */
+  async _copyDir(src, dest, depth = 0) {
+    // Guard against runaway recursion (hardlinks, deep nesting)
+    if (depth > 10) return;
+
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // H3 fix: refuse to follow symlinks
+      if (entry.isSymbolicLink()) continue;
+
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        await this._copyDir(srcPath, destPath, depth + 1);
+      } else if (entry.isFile()) {
+        await fs.copyFile(srcPath, destPath);
+      }
+    }
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message
+   * @private
+   */
+  _log(message) {
+    if (this.options.debug || process.env.MERLIN_DEBUG) {
+      console.log(`[SkillImporter] ${message}`);
+    }
+  }
+}
+
+module.exports = { SkillImporter, STANDARD_SUBDIRS, IMPORT_TARGET };

package/.merlin-core/core/alkimia/squads/default/.synapse/manifest

@@ -0,0 +1,17 @@
+name: default
+description: Default squad configuration mapping 14 agents into functional teams
+version: 1.0.0
+
+domains:
+  CORE:
+    agents: [architect, dev, qa]
+    description: Core development team — architecture, implementation, and quality
+  OPS:
+    agents: [devops, pm, sm]
+    description: Operations team — deployment, project management, and process
+  PRODUCT:
+    agents: [analyst, po, ux]
+    description: Product team — requirements, ownership, and user experience
+  DATA:
+    agents: [data-engineer, researcher, scout]
+    description: Data and research team — data pipelines, deep research, and file discovery