@poolzin/pool-bot 2026.3.7 → 2026.3.9

package/dist/skills/parser.js

@@ -0,0 +1,461 @@
+/**
+ * SKILL.md parser with YAML frontmatter support
+ * Parses skill files into structured data
+ *
+ * @module skills/parser
+ */
+import { readFile } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { SkillError, } from "./types.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+const SECTION_REGEX = /^##\s+(.+)$/gm;
+const DEFAULT_MAX_FILE_SIZE = 1024 * 1024; // 1MB
+const VALID_CATEGORIES = [
+    "automation",
+    "integration",
+    "utility",
+    "development",
+    "communication",
+    "data",
+    "ai",
+    "custom",
+];
+// Required fields for agentskills.io format (strict mode)
+const REQUIRED_FIELDS = ["id", "name", "description", "version", "category"];
+// Required fields for PoolBot legacy format (lenient mode)
+const _LEGACY_REQUIRED_FIELDS = ["name", "description"];
+// ============================================================================
+// YAML Parser (lightweight, no external deps)
+// ============================================================================
+/**
+ * Parse simple YAML frontmatter
+ * Handles basic key-value pairs, arrays, and nested objects
+ * Also handles JSON-style metadata values (for PoolBot legacy format)
+ */
+function parseYaml(yaml) {
+    const result = {};
+    const lines = yaml.split("\n");
+    let currentArray = null;
+    let currentKey = null;
+    let multilineValue = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Skip empty lines and comments (but not inside multiline values)
+        if (!trimmed || trimmed.startsWith("#")) {
+            if (multilineValue.length > 0) {
+                multilineValue.push(line);
+            }
+            continue;
+        }
+        // Check for multiline value start (pipe | or greater-than >)
+        if (currentKey && (trimmed === "|" || trimmed === ">" || trimmed.startsWith("|-") || trimmed.startsWith(">-"))) {
+            multilineValue = [];
+            continue;
+        }
+        // Collect multiline value
+        if (currentKey && multilineValue.length > 0) {
+            // Check if next line is still part of multiline (indented or empty)
+            const nextLine = lines[i + 1];
+            if (nextLine !== undefined && (nextLine.startsWith(" ") || nextLine.startsWith("\t") || nextLine.trim() === "")) {
+                multilineValue.push(line);
+                continue;
+            }
+            else {
+                // End of multiline value
+                multilineValue.push(line);
+                result[currentKey] = multilineValue.join("\n").trim();
+                multilineValue = [];
+                currentKey = null;
+                continue;
+            }
+        }
+        // Check for array continuation
+        if (currentArray !== null && trimmed.startsWith("- ")) {
+            currentArray.push(trimmed.slice(2).trim());
+            continue;
+        }
+        // Reset array context if we see a new key
+        if (currentArray !== null && !trimmed.startsWith("- ")) {
+            currentArray = null;
+        }
+        // Parse key-value pair
+        const colonIndex = trimmed.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = trimmed.slice(0, colonIndex).trim();
+        let value = trimmed.slice(colonIndex + 1).trim();
+        // Store key for potential multiline value
+        currentKey = key;
+        // Handle JSON-style values (for PoolBot legacy format)
+        if (value.startsWith("{") && value.endsWith("}")) {
+            try {
+                result[key] = JSON.parse(value);
+                continue;
+            }
+            catch {
+                // Not valid JSON, treat as string
+            }
+        }
+        // Handle arrays
+        if (value === "" || value === "[]") {
+            // Check if next line starts array
+            currentArray = [];
+            result[key] = currentArray;
+            continue;
+        }
+        // Handle inline arrays
+        if (value.startsWith("[") && value.endsWith("]")) {
+            result[key] = value
+                .slice(1, -1)
+                .split(",")
+                .map((v) => v.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean);
+            continue;
+        }
+        // Handle multiline indicator
+        if (value === "|" || value === ">" || value.startsWith("|-") || value.startsWith(">-")) {
+            multilineValue = [];
+            continue;
+        }
+        // Handle quoted strings
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Handle booleans
+        if (value === "true") {
+            result[key] = true;
+        }
+        else if (value === "false") {
+            result[key] = false;
+        }
+        else if (/^\d+$/.test(value)) {
+            // Handle numbers
+            result[key] = parseInt(value, 10);
+        }
+        else {
+            result[key] = value;
+        }
+        currentKey = null;
+    }
+    // Handle any remaining multiline value
+    if (currentKey && multilineValue.length > 0) {
+        result[currentKey] = multilineValue.join("\n").trim();
+    }
+    return result;
+}
+// ============================================================================
+// Section Parser
+// ============================================================================
+/**
+ * Parse markdown body into sections
+ */
+function parseSections(body) {
+    const sections = new Map();
+    const matches = Array.from(body.matchAll(SECTION_REGEX));
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const sectionName = match[1].toLowerCase().trim();
+        const startIndex = match.index + match[0].length;
+        const endIndex = i < matches.length - 1 ? matches[i + 1].index : body.length;
+        const content = body.slice(startIndex, endIndex).trim();
+        sections.set(sectionName, content);
+    }
+    return sections;
+}
+// ============================================================================
+// Metadata Validation
+// ============================================================================
+/**
+ * Validate and transform raw frontmatter into SkillMetadata
+ * Supports both agentskills.io format and PoolBot legacy format
+ */
+function validateMetadata(frontmatter, options = {}) {
+    const required = options.requiredFields ?? REQUIRED_FIELDS;
+    const lenient = options.lenient ?? false;
+    // Detect format: agentskills.io has 'id', legacy has 'name' but no 'id'
+    const isLegacyFormat = !frontmatter.id && frontmatter.name;
+    // For legacy format, use name as id
+    let id;
+    if (isLegacyFormat) {
+        id = String(frontmatter.name).toLowerCase().replace(/\s+/g, "-");
+    }
+    else {
+        id = frontmatter.id;
+    }
+    // Check required fields (skip id check in lenient mode for legacy)
+    for (const field of required) {
+        if (field === "id" && lenient && isLegacyFormat)
+            continue;
+        if (field === "category" && lenient && isLegacyFormat)
+            continue;
+        if (field === "version" && lenient && isLegacyFormat)
+            continue;
+        if (!(field in frontmatter) || frontmatter[field] === undefined) {
+            throw new SkillError("INVALID_METADATA", `Missing required field: ${field}`, id);
+        }
+    }
+    // Validate category (use 'custom' as default for legacy)
+    let category;
+    if (isLegacyFormat && lenient && !frontmatter.category) {
+        category = "custom";
+    }
+    else {
+        category = frontmatter.category;
+    }
+    if (!VALID_CATEGORIES.includes(category)) {
+        if (!lenient) {
+            throw new SkillError("INVALID_METADATA", `Invalid category: ${category}. Must be one of: ${VALID_CATEGORIES.join(", ")}`, id);
+        }
+        category = "custom";
+    }
+    // Validate id format (kebab-case) - only for non-legacy
+    if (!isLegacyFormat && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) {
+        throw new SkillError("INVALID_METADATA", `Invalid skill ID: ${id}. Must be kebab-case (e.g., 'my-skill-name')`, id);
+    }
+    // Validate version (basic semver check) - use '1.0.0' as default for legacy
+    let version;
+    if (isLegacyFormat && lenient && !frontmatter.version) {
+        version = "1.0.0";
+    }
+    else {
+        version = frontmatter.version;
+    }
+    if (options.validateVersions !== false && !isLegacyFormat) {
+        if (!/^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/.test(version)) {
+            throw new SkillError("INVALID_METADATA", `Invalid version: ${version}. Must follow semver (e.g., '1.0.0')`, id);
+        }
+    }
+    // Parse dates
+    let createdAt;
+    let updatedAt;
+    if (frontmatter.createdAt) {
+        createdAt = new Date(frontmatter.createdAt);
+    }
+    if (frontmatter.updatedAt) {
+        updatedAt = new Date(frontmatter.updatedAt);
+    }
+    // Parse arrays
+    const tags = Array.isArray(frontmatter.tags)
+        ? frontmatter.tags
+        : frontmatter.tags
+            ? [String(frontmatter.tags)]
+            : [];
+    const dependencies = Array.isArray(frontmatter.dependencies)
+        ? frontmatter.dependencies
+        : frontmatter.dependencies
+            ? [String(frontmatter.dependencies)]
+            : undefined;
+    const externalTools = Array.isArray(frontmatter.externalTools)
+        ? frontmatter.externalTools
+        : frontmatter.externalTools
+            ? [String(frontmatter.externalTools)]
+            : undefined;
+    return {
+        id,
+        name: String(frontmatter.name),
+        description: String(frontmatter.description),
+        version,
+        author: frontmatter.author ? String(frontmatter.author) : undefined,
+        category: category,
+        tags,
+        minPoolBotVersion: frontmatter.minPoolBotVersion
+            ? String(frontmatter.minPoolBotVersion)
+            : undefined,
+        dependencies,
+        externalTools,
+        createdAt,
+        updatedAt,
+        license: frontmatter.license ? String(frontmatter.license) : undefined,
+        repository: frontmatter.repository
+            ? String(frontmatter.repository)
+            : undefined,
+        documentation: frontmatter.documentation
+            ? String(frontmatter.documentation)
+            : undefined,
+        enabledByDefault: frontmatter.enabledByDefault === true,
+    };
+}
+// ============================================================================
+// Content Extraction
+// ============================================================================
+/**
+ * Extract skill content from parsed sections
+ */
+function extractContent(sections) {
+    // Map section aliases
+    const quickstart = sections.get("quick start") ??
+        sections.get("quickstart") ??
+        sections.get("getting started");
+    const usage = sections.get("usage") ??
+        sections.get("how to use") ??
+        sections.get("using this skill") ??
+        "";
+    const configuration = sections.get("configuration") ??
+        sections.get("config") ??
+        sections.get("setup");
+    const environment = sections.get("environment") ??
+        sections.get("env") ??
+        sections.get("environment variables");
+    const examples = sections.get("examples") ??
+        sections.get("example") ??
+        sections.get("example usage");
+    const api = sections.get("api") ??
+        sections.get("api reference") ??
+        sections.get("reference");
+    const troubleshooting = sections.get("troubleshooting") ??
+        sections.get("troubleshoot") ??
+        sections.get("common issues");
+    return {
+        quickstart,
+        usage,
+        configuration,
+        environment,
+        examples,
+        api,
+        troubleshooting,
+    };
+}
+// ============================================================================
+// Linked Files Discovery
+// ============================================================================
+/**
+ * Discover linked files in skill directory
+ */
+async function discoverLinkedFiles(skillDir) {
+    const linkedFiles = [];
+    try {
+        const { readdir } = await import("node:fs/promises");
+        const entries = await readdir(skillDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.toLowerCase() !== "skill.md") {
+                linkedFiles.push({
+                    path: entry.name,
+                    description: undefined, // Could parse from a manifest
+                    required: false, // Could be determined by references in content
+                });
+            }
+        }
+    }
+    catch {
+        // Directory might not exist or be accessible
+    }
+    return linkedFiles;
+}
+// ============================================================================
+// Main Parser Functions
+// ============================================================================
+/**
+ * Parse a SKILL.md file into structured data
+ */
+export async function parseSkillFile(filePath, options = {}) {
+    const maxSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    // Read file
+    let content;
+    try {
+        const stats = await import("node:fs/promises").then((fs) => fs.stat(filePath));
+        if (stats.size > maxSize) {
+            throw new SkillError("PARSE_ERROR", `Skill file too large: ${stats.size} bytes (max: ${maxSize})`, undefined);
+        }
+        content = await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error instanceof SkillError)
+            throw error;
+        throw new SkillError("PARSE_ERROR", `Failed to read skill file: ${error}`, undefined, error);
+    }
+    // Parse frontmatter
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        throw new SkillError("PARSE_ERROR", "Invalid SKILL.md format: missing YAML frontmatter", undefined);
+    }
+    const [, yamlContent, bodyContent] = match;
+    // Parse YAML
+    let frontmatter;
+    try {
+        frontmatter = parseYaml(yamlContent);
+    }
+    catch (error) {
+        throw new SkillError("PARSE_ERROR", `Failed to parse YAML frontmatter: ${error}`, undefined, error);
+    }
+    // Parse sections
+    const sections = parseSections(bodyContent);
+    return {
+        frontmatter,
+        body: bodyContent,
+        sections,
+        sourcePath: filePath,
+    };
+}
+/**
+ * Parse and validate a complete skill
+ */
+export async function parseSkill(filePath, options = {}) {
+    // Parse the file
+    const parsed = await parseSkillFile(filePath, options);
+    // Validate metadata
+    const metadata = validateMetadata(parsed.frontmatter, options);
+    // Extract content
+    const content = extractContent(parsed.sections);
+    content.raw = parsed.body;
+    // Discover linked files
+    const skillDir = dirname(filePath.toString());
+    const linkedFiles = await discoverLinkedFiles(skillDir);
+    return {
+        metadata,
+        content,
+        linkedFiles,
+        sourcePath: filePath,
+        status: "installed",
+        verification: "unverified",
+        enabled: metadata.enabledByDefault,
+    };
+}
+/**
+ * Parse multiple skill files
+ */
+export async function parseSkills(filePaths, options = {}) {
+    const skills = [];
+    const errors = new Map();
+    await Promise.all(filePaths.map(async (path) => {
+        try {
+            const skill = await parseSkill(path, options);
+            skills.push(skill);
+        }
+        catch (error) {
+            errors.set(path, error);
+        }
+    }));
+    return { skills, errors };
+}
+/**
+ * Check if a file is a valid SKILL.md
+ */
+export async function isSkillFile(filePath) {
+    try {
+        const fileName = basename(filePath.toString()).toLowerCase();
+        if (fileName !== "skill.md")
+            return false;
+        const content = await readFile(filePath, "utf-8");
+        return FRONTMATTER_REGEX.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract skill ID from file path
+ */
+export function extractSkillId(filePath) {
+    const dir = dirname(filePath.toString());
+    const base = basename(dir);
+    return base.toLowerCase().replace(/\s+/g, "-");
+}
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { parseYaml, parseSections, validateMetadata, extractContent };