skill-tree 0.2.0 → 0.3.0

package/dist/chunk-MBIGW6KU.mjs

@@ -0,0 +1,644 @@
+// src/agents/sync.ts
+import * as fs from "fs";
+import * as path from "path";
+
+// src/agents/types.ts
+var DEFAULT_AGENTS_CONFIG = {
+  format: "xml",
+  includeIds: true,
+  includeVersions: true,
+  groupByTags: false
+};
+
+// src/agents/generator.ts
+var AgentsGenerator = class {
+  constructor(config) {
+    this.config = { ...DEFAULT_AGENTS_CONFIG, ...config };
+  }
+  /**
+   * Generate AGENTS.md content from a skill bank
+   */
+  async generate(storage) {
+    let skills = await storage.listSkills({
+      status: this.config.filter?.status || ["active"]
+    });
+    skills = this.filterSkills(skills, this.config.filter);
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    const sections = [];
+    if (this.config.header) {
+      sections.push(this.config.header);
+    } else {
+      sections.push(this.generateDefaultHeader());
+    }
+    if (this.config.groupByTags) {
+      sections.push(this.generateGroupedSkills(skills));
+    } else {
+      sections.push(this.generateSkillsList(skills));
+    }
+    if (this.config.footer) {
+      sections.push(this.config.footer);
+    }
+    return sections.join("\n\n");
+  }
+  /**
+   * Generate content for a single skill
+   */
+  generateSkill(skill) {
+    switch (this.config.format) {
+      case "xml":
+        return this.generateXmlSkill(skill);
+      case "markdown":
+        return this.generateMarkdownSkill(skill);
+      case "json":
+        return this.generateJsonSkill(skill);
+      default:
+        return this.generateXmlSkill(skill);
+    }
+  }
+  /**
+   * Generate skills list
+   */
+  generateSkillsList(skills) {
+    return skills.map((skill) => this.generateSkill(skill)).join("\n\n");
+  }
+  /**
+   * Generate skills grouped by tags
+   */
+  generateGroupedSkills(skills) {
+    const tagGroups = /* @__PURE__ */ new Map();
+    const untagged = [];
+    for (const skill of skills) {
+      if (skill.tags.length === 0) {
+        untagged.push(skill);
+      } else {
+        const primaryTag = skill.tags[0];
+        if (!tagGroups.has(primaryTag)) {
+          tagGroups.set(primaryTag, []);
+        }
+        tagGroups.get(primaryTag).push(skill);
+      }
+    }
+    const sections = [];
+    const sortedTags = Array.from(tagGroups.keys()).sort();
+    for (const tag of sortedTags) {
+      const tagSkills = tagGroups.get(tag);
+      sections.push(`## ${this.formatTagName(tag)}
+
+${this.generateSkillsList(tagSkills)}`);
+    }
+    if (untagged.length > 0) {
+      sections.push(`## Other
+
+${this.generateSkillsList(untagged)}`);
+    }
+    return sections.join("\n\n");
+  }
+  /**
+   * Generate XML format skill (Claude Code native format)
+   */
+  generateXmlSkill(skill) {
+    const lines = [];
+    const attrs = [];
+    if (this.config.includeIds) {
+      attrs.push(`id="${this.escapeXml(skill.id)}"`);
+    }
+    if (this.config.includeVersions) {
+      attrs.push(`version="${this.escapeXml(skill.version)}"`);
+    }
+    const attrStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+    lines.push(`<skill${attrStr}>`);
+    lines.push(`  <name>${this.escapeXml(skill.name)}</name>`);
+    if (skill.description) {
+      lines.push(`  <description>${this.escapeXml(skill.description)}</description>`);
+    }
+    if (skill.instructions) {
+      lines.push(`  <content>
+${this.indentContent(skill.instructions, 4)}
+  </content>`);
+    }
+    if (skill.tags.length > 0) {
+      lines.push(`  <tags>${skill.tags.map((t) => this.escapeXml(t)).join(", ")}</tags>`);
+    }
+    lines.push("</skill>");
+    return lines.join("\n");
+  }
+  /**
+   * Generate Markdown format skill
+   */
+  generateMarkdownSkill(skill) {
+    const lines = [];
+    const idSuffix = this.config.includeIds ? ` {#${skill.id}}` : "";
+    const versionSuffix = this.config.includeVersions ? ` (v${skill.version})` : "";
+    lines.push(`### ${skill.name}${versionSuffix}${idSuffix}`);
+    lines.push("");
+    if (skill.description) {
+      lines.push(`*${skill.description}*`);
+      lines.push("");
+    }
+    if (skill.instructions) {
+      lines.push(skill.instructions);
+      lines.push("");
+    }
+    if (skill.tags.length > 0) {
+      lines.push(`Tags: ${skill.tags.map((t) => `\`${t}\``).join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Generate JSON format skill
+   */
+  generateJsonSkill(skill) {
+    const obj = {
+      name: skill.name,
+      description: skill.description
+    };
+    if (this.config.includeIds) {
+      obj.id = skill.id;
+    }
+    if (this.config.includeVersions) {
+      obj.version = skill.version;
+    }
+    if (skill.instructions) {
+      obj.instructions = skill.instructions;
+    }
+    if (skill.tags.length > 0) {
+      obj.tags = skill.tags;
+    }
+    return "```json\n" + JSON.stringify(obj, null, 2) + "\n```";
+  }
+  /**
+   * Filter skills based on selector
+   */
+  filterSkills(skills, filter) {
+    if (!filter) return skills;
+    let result = skills;
+    if (filter.ids && filter.ids.length > 0) {
+      result = result.filter((s) => filter.ids.includes(s.id));
+    }
+    if (filter.tags && filter.tags.length > 0) {
+      result = result.filter((s) => s.tags.some((t) => filter.tags.includes(t)));
+    }
+    if (filter.limit) {
+      result = result.slice(0, filter.limit);
+    }
+    return result;
+  }
+  /**
+   * Generate default header
+   */
+  generateDefaultHeader() {
+    return `# Agent Skills
+
+This file contains skills for the AI agent. Each skill describes a pattern for solving a specific type of problem.
+
+---`;
+  }
+  /**
+   * Format tag name for section header
+   */
+  formatTagName(tag) {
+    return tag.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  }
+  /**
+   * Escape XML special characters
+   */
+  escapeXml(str) {
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  }
+  /**
+   * Indent content
+   */
+  indentContent(content, spaces) {
+    const indent = " ".repeat(spaces);
+    return content.split("\n").map((line) => indent + line).join("\n");
+  }
+};
+function createAgentsGenerator(config) {
+  return new AgentsGenerator(config);
+}
+
+// src/agents/parser.ts
+var AgentsParser = class {
+  /**
+   * Parse AGENTS.md content
+   */
+  parse(content) {
+    const warnings = [];
+    const skills = [];
+    const xmlSkills = this.parseXmlSkills(content);
+    if (xmlSkills.length > 0) {
+      skills.push(...xmlSkills);
+    }
+    const mdSkills = this.parseMarkdownSkills(content, xmlSkills);
+    if (mdSkills.length > 0) {
+      const existingNames = new Set(skills.map((s) => s.name.toLowerCase()));
+      for (const skill of mdSkills) {
+        if (!existingNames.has(skill.name.toLowerCase())) {
+          skills.push(skill);
+        }
+      }
+    }
+    const header = this.extractHeader(content, skills);
+    const footer = this.extractFooter(content, skills);
+    if (skills.length === 0) {
+      warnings.push("No skills found in AGENTS.md");
+    }
+    return { header, skills, footer, warnings };
+  }
+  /**
+   * Convert parsed skill to Skill type
+   */
+  toSkill(parsed, defaults) {
+    const now = /* @__PURE__ */ new Date();
+    const id = parsed.id || this.generateId(parsed.name);
+    let instructions = parsed.instructions || "";
+    if (!instructions) {
+      const instructionParts = [];
+      if (parsed.problem) instructionParts.push(parsed.problem);
+      if (parsed.solution) instructionParts.push(parsed.solution);
+      if (parsed.verification) instructionParts.push(parsed.verification);
+      if (parsed.notes) instructionParts.push(parsed.notes);
+      instructions = instructionParts.length > 0 ? instructionParts.join("\n\n") : "";
+    }
+    return {
+      id,
+      name: parsed.name,
+      version: parsed.version || "1.0.0",
+      description: parsed.description || "",
+      instructions,
+      author: defaults?.author || "imported",
+      tags: parsed.tags || [],
+      createdAt: defaults?.createdAt || now,
+      updatedAt: now,
+      status: "active",
+      source: {
+        type: "imported",
+        location: "AGENTS.md",
+        importedAt: now
+      },
+      ...defaults
+    };
+  }
+  /**
+   * Parse XML format skills
+   */
+  parseXmlSkills(content) {
+    const skills = [];
+    const skillRegex = /<skill([^>]*)>([\s\S]*?)<\/skill>/gi;
+    let match;
+    while ((match = skillRegex.exec(content)) !== null) {
+      const attrs = match[1];
+      const body = match[2];
+      const skill = {
+        rawContent: match[0],
+        name: this.extractXmlTag(body, "name") || "Unnamed Skill",
+        description: this.extractXmlTag(body, "description") || ""
+      };
+      const idMatch = /id="([^"]+)"/.exec(attrs);
+      if (idMatch) {
+        skill.id = idMatch[1];
+      }
+      const versionMatch = /version="([^"]+)"/.exec(attrs);
+      if (versionMatch) {
+        skill.version = versionMatch[1];
+      }
+      const contentTag = this.extractXmlTag(body, "content");
+      if (contentTag) {
+        skill.instructions = contentTag;
+      } else {
+        skill.problem = this.extractXmlTag(body, "problem");
+        skill.solution = this.extractXmlTag(body, "solution");
+        skill.verification = this.extractXmlTag(body, "verification");
+        skill.notes = this.extractXmlTag(body, "notes");
+      }
+      const tagsStr = this.extractXmlTag(body, "tags");
+      if (tagsStr) {
+        skill.tags = tagsStr.split(",").map((t) => t.trim()).filter((t) => t);
+      }
+      skills.push(skill);
+    }
+    return skills;
+  }
+  /**
+   * Parse Markdown format skills
+   */
+  parseMarkdownSkills(content, existingSkills) {
+    const skills = [];
+    const sections = content.split(/(?=^###\s)/m);
+    for (const section of sections) {
+      const headerMatch = /^###\s+(.+?)(?:\s+\(v([\d.]+)\))?(?:\s+\{#([^}]+)\})?\s*$/m.exec(section);
+      if (!headerMatch) continue;
+      const name = headerMatch[1].trim();
+      const version = headerMatch[2];
+      const id = headerMatch[3];
+      if (existingSkills.some((s) => s.name.toLowerCase() === name.toLowerCase())) {
+        continue;
+      }
+      const skill = {
+        rawContent: section,
+        name,
+        description: ""
+      };
+      if (version) skill.version = version;
+      if (id) skill.id = id;
+      const descMatch = /^\*([^*]+)\*$/m.exec(section);
+      if (descMatch) {
+        skill.description = descMatch[1];
+      }
+      const bodyStart = section.indexOf("\n", section.indexOf(headerMatch[0]) + headerMatch[0].length);
+      if (bodyStart >= 0) {
+        let bodyContent = section.slice(bodyStart).trim();
+        bodyContent = bodyContent.replace(/^\*[^*]+\*\s*\n?/, "").trim();
+        bodyContent = bodyContent.replace(/\nTags:\s*.+$/m, "").trim();
+        if (bodyContent) {
+          skill.instructions = bodyContent;
+        }
+      }
+      if (!skill.instructions) {
+        skill.problem = this.extractMarkdownSection(section, "Problem");
+        skill.solution = this.extractMarkdownSection(section, "Solution");
+        skill.verification = this.extractMarkdownSection(section, "Verification");
+        skill.notes = this.extractMarkdownSection(section, "Notes");
+      }
+      const tagsMatch = /Tags:\s*(.+)$/m.exec(section);
+      if (tagsMatch) {
+        skill.tags = tagsMatch[1].split(",").map((t) => t.replace(/`/g, "").trim()).filter((t) => t);
+      }
+      skills.push(skill);
+    }
+    return skills;
+  }
+  /**
+   * Extract content from XML tag
+   */
+  extractXmlTag(body, tagName) {
+    const regex = new RegExp(`<${tagName}>([\\s\\S]*?)<\\/${tagName}>`, "i");
+    const match = regex.exec(body);
+    if (match) {
+      return this.unescapeXml(match[1].trim());
+    }
+    return void 0;
+  }
+  /**
+   * Extract CDATA content
+   */
+  extractCData(body, tagName) {
+    const regex = new RegExp(`<${tagName}><!\\[CDATA\\[([\\s\\S]*?)\\]\\]><\\/${tagName}>`, "i");
+    const match = regex.exec(body);
+    if (match) {
+      return match[1];
+    }
+    return void 0;
+  }
+  /**
+   * Unescape XML entities
+   */
+  unescapeXml(str) {
+    return str.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+  }
+  /**
+   * Extract a markdown section by header
+   */
+  extractMarkdownSection(content, header) {
+    const regex = new RegExp(`\\*\\*${header}:\\*\\*\\s*([\\s\\S]*?)(?=\\*\\*|Tags:|$)`, "i");
+    const match = regex.exec(content);
+    if (match) {
+      return match[1].trim();
+    }
+    return void 0;
+  }
+  /**
+   * Generate ID from skill name
+   */
+  generateId(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  }
+  /**
+   * Extract header content
+   */
+  extractHeader(content, skills) {
+    if (skills.length === 0) return content.trim() || void 0;
+    const firstSkill = skills[0];
+    const idx = content.indexOf(firstSkill.rawContent);
+    if (idx > 0) {
+      return content.slice(0, idx).trim() || void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Extract footer content
+   */
+  extractFooter(content, skills) {
+    if (skills.length === 0) return void 0;
+    const lastSkill = skills[skills.length - 1];
+    const idx = content.indexOf(lastSkill.rawContent);
+    if (idx >= 0) {
+      const afterIdx = idx + lastSkill.rawContent.length;
+      const footer = content.slice(afterIdx).trim();
+      return footer || void 0;
+    }
+    return void 0;
+  }
+};
+function createAgentsParser() {
+  return new AgentsParser();
+}
+
+// src/agents/sync.ts
+var AgentsSync = class {
+  constructor() {
+    this.generator = new AgentsGenerator();
+    this.parser = new AgentsParser();
+  }
+  /**
+   * Sync AGENTS.md with skill bank
+   */
+  async sync(agentsPath, storage, options) {
+    const result = {
+      added: [],
+      updated: [],
+      removed: [],
+      unchanged: [],
+      warnings: []
+    };
+    switch (options.direction) {
+      case "import":
+        await this.importFromAgents(agentsPath, storage, options, result);
+        break;
+      case "export":
+        await this.exportToAgents(agentsPath, storage, options, result);
+        break;
+      case "bidirectional":
+        await this.bidirectionalSync(agentsPath, storage, options, result);
+        break;
+    }
+    return result;
+  }
+  /**
+   * Import skills from AGENTS.md to skill bank
+   */
+  async importFromAgents(agentsPath, storage, options, result) {
+    if (!fs.existsSync(agentsPath)) {
+      result.warnings.push(`AGENTS.md not found at ${agentsPath}`);
+      return;
+    }
+    const content = fs.readFileSync(agentsPath, "utf-8");
+    const parsed = this.parser.parse(content);
+    result.warnings.push(...parsed.warnings);
+    const existingSkills = await storage.listSkills();
+    const existingById = new Map(existingSkills.map((s) => [s.id, s]));
+    const existingByName = new Map(existingSkills.map((s) => [s.name.toLowerCase(), s]));
+    const processedIds = /* @__PURE__ */ new Set();
+    for (const parsedSkill of parsed.skills) {
+      const skill = this.parser.toSkill(parsedSkill);
+      processedIds.add(skill.id);
+      let existing = existingById.get(skill.id);
+      if (!existing) {
+        existing = existingByName.get(skill.name.toLowerCase());
+      }
+      if (existing) {
+        const shouldUpdate = this.resolveConflict(existing, skill, options.conflictStrategy);
+        if (shouldUpdate) {
+          if (!options.dryRun) {
+            const merged = this.mergeSkills(existing, skill);
+            await storage.saveSkill(merged);
+          }
+          result.updated.push(skill.id);
+        } else {
+          result.unchanged.push(skill.id);
+        }
+      } else {
+        if (!options.dryRun) {
+          await storage.saveSkill(skill);
+        }
+        result.added.push(skill.id);
+      }
+    }
+    if (options.removeOrphans) {
+      for (const existing of existingSkills) {
+        if (!processedIds.has(existing.id)) {
+          if (!options.dryRun) {
+            await storage.deleteSkill(existing.id);
+          }
+          result.removed.push(existing.id);
+        }
+      }
+    }
+  }
+  /**
+   * Export skills from skill bank to AGENTS.md
+   */
+  async exportToAgents(agentsPath, storage, options, result) {
+    const generator = new AgentsGenerator(options.generatorConfig);
+    const content = await generator.generate(storage);
+    let existingContent = "";
+    if (fs.existsSync(agentsPath)) {
+      existingContent = fs.readFileSync(agentsPath, "utf-8");
+    }
+    const existingParsed = this.parser.parse(existingContent);
+    const existingIds = new Set(existingParsed.skills.map((s) => s.id || s.name.toLowerCase()));
+    const skills = await storage.listSkills({
+      status: options.generatorConfig?.filter?.status || ["active"]
+    });
+    for (const skill of skills) {
+      if (existingIds.has(skill.id) || existingIds.has(skill.name.toLowerCase())) {
+        result.updated.push(skill.id);
+      } else {
+        result.added.push(skill.id);
+      }
+    }
+    if (!options.dryRun) {
+      const dir = path.dirname(agentsPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(agentsPath, content);
+    }
+  }
+  /**
+   * Bidirectional sync
+   */
+  async bidirectionalSync(agentsPath, storage, options, result) {
+    await this.importFromAgents(agentsPath, storage, { ...options, removeOrphans: false }, result);
+    const exportResult = {
+      added: [],
+      updated: [],
+      removed: [],
+      unchanged: [],
+      warnings: []
+    };
+    await this.exportToAgents(agentsPath, storage, options, exportResult);
+    for (const id of exportResult.added) {
+      if (!result.added.includes(id) && !result.updated.includes(id)) {
+        result.added.push(id);
+      }
+    }
+  }
+  /**
+   * Resolve conflict between existing and new skill
+   */
+  resolveConflict(existing, incoming, strategy) {
+    switch (strategy) {
+      case "bank-wins":
+        return false;
+      case "agents-wins":
+        return true;
+      case "newer-wins":
+        return incoming.updatedAt > existing.updatedAt;
+      case "skip":
+      default:
+        return false;
+    }
+  }
+  /**
+   * Merge skills, preserving important data from existing
+   */
+  mergeSkills(existing, incoming) {
+    return {
+      ...incoming,
+      id: existing.id,
+      // Keep existing ID
+      createdAt: existing.createdAt,
+      // Preserve creation date
+      source: incoming.source || existing.source,
+      parentVersion: existing.version
+      // Track update lineage
+    };
+  }
+};
+function createAgentsSync() {
+  return new AgentsSync();
+}
+async function generateAgentsMd(storage, config) {
+  const generator = new AgentsGenerator(config);
+  return generator.generate(storage);
+}
+async function writeAgentsMd(storage, filePath, config) {
+  const content = await generateAgentsMd(storage, config);
+  const dir = path.dirname(filePath);
+  if (dir && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, content);
+}
+async function importFromAgentsMd(filePath, storage, options) {
+  const sync = new AgentsSync();
+  return sync.sync(filePath, storage, {
+    direction: "import",
+    conflictStrategy: options?.conflictStrategy || "skip",
+    dryRun: options?.dryRun
+  });
+}
+
+export {
+  DEFAULT_AGENTS_CONFIG,
+  AgentsGenerator,
+  createAgentsGenerator,
+  AgentsParser,
+  createAgentsParser,
+  AgentsSync,
+  createAgentsSync,
+  generateAgentsMd,
+  writeAgentsMd,
+  importFromAgentsMd
+};