@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/dist/skills/registry.js

@@ -0,0 +1,394 @@
+/**
+ * Skills registry
+ * Manages skill discovery, storage, and lifecycle
+ *
+ * @module skills/registry
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { EventEmitter } from "node:events";
+import { SkillError, } from "./types.js";
+import { parseSkill, isSkillFile } from "./parser.js";
+import { scanSkill } from "./security.js";
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    localPaths: [],
+    autoScan: true,
+    strictSecurity: false,
+    cacheTtlMs: 5 * 60 * 1000, // 5 minutes
+};
+// ============================================================================
+// Skills Registry
+// ============================================================================
+export class SkillsRegistry extends EventEmitter {
+    skills = new Map();
+    config;
+    scanCache = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ========================================================================
+    // Event Handling
+    // ========================================================================
+    emitEvent(type, skillId, data) {
+        const event = {
+            type,
+            skillId,
+            timestamp: new Date(),
+            data,
+        };
+        this.emit(type, event);
+    }
+    onSkillEvent(type, handler) {
+        this.on(type, handler);
+    }
+    // ========================================================================
+    // Skill Discovery
+    // ========================================================================
+    /**
+     * Scan all configured paths for skills
+     */
+    async scan() {
+        const errors = [];
+        let loaded = 0;
+        for (const path of this.config.localPaths) {
+            try {
+                const result = await this.scanPath(path);
+                loaded += result.loaded;
+                errors.push(...result.errors);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        return { loaded, errors };
+    }
+    /**
+     * Scan a single path for skills
+     */
+    async scanPath(basePath) {
+        const errors = [];
+        let loaded = 0;
+        try {
+            const entries = await readdir(basePath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillPath = join(basePath.toString(), entry.name, "SKILL.md");
+                try {
+                    if (await isSkillFile(skillPath)) {
+                        const skill = await parseSkill(skillPath);
+                        // Run security scan if auto-scan enabled
+                        if (this.config.autoScan) {
+                            skill.securityReport = await scanSkill(skill);
+                            skill.verification = skill.securityReport.result;
+                            // Auto-disable if strict security and failed
+                            if (this.config.strictSecurity && skill.verification === "failed") {
+                                skill.enabled = false;
+                                skill.status = "disabled";
+                            }
+                        }
+                        this.skills.set(skill.metadata.id, skill);
+                        this.emitEvent("skill:loaded", skill.metadata.id);
+                        loaded++;
+                    }
+                }
+                catch (error) {
+                    errors.push(new SkillError("LOAD_ERROR", `Failed to load skill from ${skillPath}: ${error}`, entry.name, error));
+                }
+            }
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        return { loaded, errors };
+    }
+    /**
+     * Watch for skill changes (placeholder for future implementation)
+     */
+    async watch() {
+        // TODO: Implement file watching for hot-reload
+        // This would use fs.watch or chokidar
+        throw new SkillError("CONFIG_ERROR", "Watch mode not yet implemented");
+    }
+    // ========================================================================
+    // Skill CRUD
+    // ========================================================================
+    /**
+     * Get a skill by ID
+     */
+    get(id) {
+        return this.skills.get(id);
+    }
+    /**
+     * Get all skills
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Get skill reference (lightweight)
+     */
+    getRef(id) {
+        const skill = this.skills.get(id);
+        if (!skill)
+            return undefined;
+        return {
+            id: skill.metadata.id,
+            name: skill.metadata.name,
+            description: skill.metadata.description,
+            category: skill.metadata.category,
+            tags: skill.metadata.tags,
+            version: skill.metadata.version,
+            status: skill.status,
+            verification: skill.verification,
+            enabled: skill.enabled,
+        };
+    }
+    /**
+     * Get all skill references
+     */
+    getAllRefs() {
+        return this.getAll().map((skill) => ({
+            id: skill.metadata.id,
+            name: skill.metadata.name,
+            description: skill.metadata.description,
+            category: skill.metadata.category,
+            tags: skill.metadata.tags,
+            version: skill.metadata.version,
+            status: skill.status,
+            verification: skill.verification,
+            enabled: skill.enabled,
+        }));
+    }
+    /**
+     * Add or update a skill
+     */
+    async add(skill) {
+        const exists = this.skills.has(skill.metadata.id);
+        this.skills.set(skill.metadata.id, skill);
+        this.emitEvent(exists ? "skill:updated" : "skill:loaded", skill.metadata.id);
+    }
+    /**
+     * Remove a skill
+     */
+    remove(id) {
+        const existed = this.skills.delete(id);
+        if (existed) {
+            this.emitEvent("skill:unloaded", id);
+        }
+        return existed;
+    }
+    /**
+     * Check if skill exists
+     */
+    has(id) {
+        return this.skills.has(id);
+    }
+    // ========================================================================
+    // Skill State Management
+    // ========================================================================
+    /**
+     * Enable a skill
+     */
+    enable(id) {
+        const skill = this.skills.get(id);
+        if (!skill)
+            return false;
+        if (skill.verification === "failed" && this.config.strictSecurity) {
+            throw new SkillError("SECURITY_VIOLATION", `Cannot enable skill ${id}: failed security scan`, id);
+        }
+        skill.enabled = true;
+        skill.status = "installed";
+        this.emitEvent("skill:enabled", id);
+        return true;
+    }
+    /**
+     * Disable a skill
+     */
+    disable(id) {
+        const skill = this.skills.get(id);
+        if (!skill)
+            return false;
+        skill.enabled = false;
+        skill.status = "disabled";
+        this.emitEvent("skill:disabled", id);
+        return true;
+    }
+    /**
+     * Toggle skill enabled state
+     */
+    toggle(id) {
+        const skill = this.skills.get(id);
+        if (!skill)
+            return false;
+        return skill.enabled ? this.disable(id) : this.enable(id);
+    }
+    // ========================================================================
+    // Search
+    // ========================================================================
+    /**
+     * Search skills with filters
+     */
+    search(filters = {}, page = 1, pageSize = 20) {
+        let results = this.getAll();
+        // Apply filters
+        if (filters.category) {
+            results = results.filter((s) => s.metadata.category === filters.category);
+        }
+        if (filters.tags?.length) {
+            results = results.filter((s) => filters.tags.some((tag) => s.metadata.tags.includes(tag)));
+        }
+        if (filters.status) {
+            results = results.filter((s) => s.status === filters.status);
+        }
+        if (filters.verification) {
+            results = results.filter((s) => s.verification === filters.verification);
+        }
+        if (filters.enabledOnly) {
+            results = results.filter((s) => s.enabled);
+        }
+        if (filters.query) {
+            const query = filters.query.toLowerCase();
+            results = results.filter((s) => s.metadata.name.toLowerCase().includes(query) ||
+                s.metadata.description.toLowerCase().includes(query) ||
+                s.metadata.tags.some((t) => t.toLowerCase().includes(query)));
+        }
+        // Pagination
+        const total = results.length;
+        const start = (page - 1) * pageSize;
+        const paginated = results.slice(start, start + pageSize);
+        return {
+            skills: paginated.map((s) => ({
+                id: s.metadata.id,
+                name: s.metadata.name,
+                description: s.metadata.description,
+                category: s.metadata.category,
+                tags: s.metadata.tags,
+                version: s.metadata.version,
+                status: s.status,
+                verification: s.verification,
+                enabled: s.enabled,
+            })),
+            total,
+            page,
+            pageSize,
+        };
+    }
+    /**
+     * Find skills by tag
+     */
+    findByTag(tag) {
+        return this.getAllRefs().filter((s) => s.tags.includes(tag));
+    }
+    /**
+     * Find skills by category
+     */
+    findByCategory(category) {
+        return this.getAllRefs().filter((s) => s.category === category);
+    }
+    // ========================================================================
+    // Statistics
+    // ========================================================================
+    /**
+     * Get registry statistics
+     */
+    getStats() {
+        const skills = this.getAll();
+        const byCategory = {};
+        const byVerification = {};
+        for (const skill of skills) {
+            // Count by category
+            byCategory[skill.metadata.category] = (byCategory[skill.metadata.category] || 0) + 1;
+            // Count by verification
+            byVerification[skill.verification] = (byVerification[skill.verification] || 0) + 1;
+        }
+        return {
+            total: skills.length,
+            enabled: skills.filter((s) => s.enabled).length,
+            disabled: skills.filter((s) => !s.enabled).length,
+            byCategory,
+            byVerification,
+        };
+    }
+    // ========================================================================
+    // Import/Export
+    // ========================================================================
+    /**
+     * Export all skills to JSON
+     */
+    export() {
+        const data = this.getAll().map((skill) => ({
+            metadata: skill.metadata,
+            status: skill.status,
+            verification: skill.verification,
+            enabled: skill.enabled,
+            userConfig: skill.userConfig,
+        }));
+        return JSON.stringify(data, null, 2);
+    }
+    /**
+     * Import skills from JSON
+     */
+    async import(json) {
+        const data = JSON.parse(json);
+        for (const partial of data) {
+            if (!partial.metadata?.id)
+                continue;
+            // Try to reload from source
+            const existing = this.skills.get(partial.metadata.id);
+            if (existing) {
+                // Update state only
+                if (partial.enabled !== undefined) {
+                    existing.enabled = partial.enabled;
+                }
+                if (partial.userConfig) {
+                    existing.userConfig = partial.userConfig;
+                }
+            }
+        }
+    }
+    // ========================================================================
+    // Cleanup
+    // ========================================================================
+    /**
+     * Clear all skills
+     */
+    clear() {
+        for (const id of this.skills.keys()) {
+            this.emitEvent("skill:unloaded", id);
+        }
+        this.skills.clear();
+        this.scanCache.clear();
+    }
+    /**
+     * Dispose of registry resources
+     */
+    dispose() {
+        this.clear();
+        this.removeAllListeners();
+    }
+}
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+let globalRegistry = null;
+/**
+ * Get or create global registry instance
+ */
+export function getRegistry(config) {
+    if (!globalRegistry) {
+        globalRegistry = new SkillsRegistry(config);
+    }
+    return globalRegistry;
+}
+/**
+ * Reset global registry (useful for testing)
+ */
+export function resetRegistry() {
+    globalRegistry?.dispose();
+    globalRegistry = null;
+}

package/dist/skills/security.js

@@ -0,0 +1,312 @@
+/**
+ * Skill security scanner
+ * Detects potential security issues in skill files
+ *
+ * @module skills/security
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const SCANNER_VERSION = "1.0.0";
+// Patterns that indicate potential security issues
+const PATTERNS = [
+    // Prompt injection attempts
+    {
+        type: "prompt_injection",
+        severity: "critical",
+        pattern: /ignore\s+(?:previous|above|prior)|disregard\s+(?:instructions?|prompt)|system\s*:\s*you\s+are|new\s+instructions?\s*:/i,
+        description: "Potential prompt injection attempt detected",
+        remediation: "Review skill content for malicious instruction overrides",
+    },
+    {
+        type: "prompt_injection",
+        severity: "high",
+        pattern: /\[\s*system\s*\]|\(\s*system\s*\)|\{\s*system\s*\}|\bDAN\b|do\s+anything\s+now/i,
+        description: "Suspicious system role reference",
+        remediation: "Verify skill doesn't attempt to override system behavior",
+    },
+    // Command injection
+    {
+        type: "command_injection",
+        severity: "critical",
+        pattern: /(?:bash|sh|zsh|cmd|powershell)\s+-c\s+["']|exec\s*\(|eval\s*\(|system\s*\(/i,
+        description: "Potential command injection pattern",
+        remediation: "Avoid executing arbitrary shell commands from skill content",
+    },
+    {
+        type: "command_injection",
+        severity: "high",
+        pattern: /`[^`]*(?:rm|del|format|mkfs|dd|wget|curl|fetch)[^`]*`|\$\([^)]*(?:rm|del|wget|curl)[^)]*\)/i,
+        description: "Dangerous command in template literal",
+        remediation: "Review shell command usage for safety",
+    },
+    // Path traversal
+    {
+        type: "path_traversal",
+        severity: "high",
+        pattern: /\.\.[/\\]|\.\.%2f|\.\.%5c|%2e%2e[/\\]/i,
+        description: "Path traversal attempt detected",
+        remediation: "Validate and sanitize all file paths",
+    },
+    // Suspicious patterns
+    {
+        type: "suspicious_pattern",
+        severity: "medium",
+        pattern: /(?:password|secret|token|key|credential)\s*=\s*["'][^"']{8,}["']/i,
+        description: "Hardcoded credential-like pattern",
+        remediation: "Use environment variables or secure secret storage",
+    },
+    {
+        type: "suspicious_pattern",
+        severity: "medium",
+        pattern: /base64\s*\(\s*["'][^"']{20,}["']\s*\)|atob\s*\(|btoa\s*\(/i,
+        description: "Suspicious encoding/decoding pattern",
+        remediation: "Verify encoding is not used to obfuscate malicious content",
+    },
+    // External dependencies
+    {
+        type: "external_dependency",
+        severity: "low",
+        pattern: /(?:npm|pip|gem|cargo|go\s+get)\s+install/i,
+        description: "External package installation mentioned",
+        remediation: "Verify all external dependencies are trustworthy",
+    },
+    // Permission requests
+    {
+        type: "permission_request",
+        severity: "medium",
+        pattern: /(?:sudo|administrator|root|elevated|privileged)\s*(?:access|permission|required|needed)/i,
+        description: "Elevated permissions mentioned",
+        remediation: "Ensure elevated permissions are truly necessary",
+    },
+    // Network access
+    {
+        type: "network_access",
+        severity: "low",
+        pattern: /(?:http|https|ftp|ssh|telnet):\/\/|(?:fetch|axios|request|curl)\s*\(/i,
+        description: "Network access pattern detected",
+        remediation: "Verify all network requests are legitimate",
+    },
+    // File system access
+    {
+        type: "file_system_access",
+        severity: "low",
+        pattern: /(?:fs\.|file|readFile|writeFile|appendFile|unlink|mkdir|rmdir)\s*\(/i,
+        description: "File system access pattern detected",
+        remediation: "Validate file operations are scoped appropriately",
+    },
+];
+// Content limits
+const MAX_CONTENT_LENGTH = 1024 * 1024; // 1MB
+const MAX_LINE_LENGTH = 1000;
+// ============================================================================
+// Scanner Implementation
+// ============================================================================
+/**
+ * Scan skill content for security issues
+ */
+export async function scanSkill(skill) {
+    const startTime = Date.now();
+    const findings = [];
+    // Combine all content for scanning
+    const contentToScan = [
+        skill.metadata.name,
+        skill.metadata.description,
+        skill.content.usage,
+        skill.content.quickstart,
+        skill.content.configuration,
+        skill.content.environment,
+        skill.content.examples,
+        skill.content.api,
+        skill.content.troubleshooting,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    // Check content size
+    if (contentToScan.length > MAX_CONTENT_LENGTH) {
+        findings.push({
+            type: "suspicious_pattern",
+            severity: "medium",
+            description: `Skill content exceeds maximum size (${contentToScan.length} > ${MAX_CONTENT_LENGTH})`,
+            location: "content",
+            remediation: "Consider splitting large skills into smaller modules",
+        });
+    }
+    // Scan line by line for better location reporting
+    const lines = contentToScan.split("\n");
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+        const line = lines[lineNum];
+        // Check line length
+        if (line.length > MAX_LINE_LENGTH) {
+            findings.push({
+                type: "suspicious_pattern",
+                severity: "low",
+                description: `Line ${lineNum + 1} exceeds maximum length`,
+                location: `line:${lineNum + 1}`,
+                remediation: "Break long lines for readability and safety",
+            });
+        }
+        // Check against patterns
+        for (const { type, severity, pattern, description, remediation } of PATTERNS) {
+            if (pattern.test(line)) {
+                findings.push({
+                    type,
+                    severity,
+                    description,
+                    location: `line:${lineNum + 1}`,
+                    remediation,
+                    evidence: line.trim().slice(0, 100), // First 100 chars
+                });
+            }
+        }
+    }
+    // Check linked files
+    for (const linkedFile of skill.linkedFiles) {
+        // Flag executable files
+        if (/\.(exe|bat|cmd|sh|bin|app)$/i.test(linkedFile.path)) {
+            findings.push({
+                type: "suspicious_pattern",
+                severity: "high",
+                description: `Linked executable file detected: ${linkedFile.path}`,
+                location: `linked:${linkedFile.path}`,
+                remediation: "Review executable content before execution",
+            });
+        }
+        // Flag scripts
+        if (/\.(js|ts|py|rb|pl|php)$/i.test(linkedFile.path)) {
+            findings.push({
+                type: "external_dependency",
+                severity: "low",
+                description: `Linked script file: ${linkedFile.path}`,
+                location: `linked:${linkedFile.path}`,
+                remediation: "Review script content for safety",
+            });
+        }
+    }
+    // Determine overall result
+    const hasCritical = findings.some((f) => f.severity === "critical");
+    const hasHigh = findings.some((f) => f.severity === "high");
+    const hasWarnings = findings.some((f) => f.severity === "medium" || f.severity === "low");
+    let result;
+    if (hasCritical) {
+        result = "failed";
+    }
+    else if (hasHigh) {
+        result = "failed";
+    }
+    else if (hasWarnings) {
+        result = "warning";
+    }
+    else {
+        result = "verified";
+    }
+    const durationMs = Date.now() - startTime;
+    return {
+        scannedAt: new Date(),
+        result,
+        findings,
+        durationMs,
+        scannerVersion: SCANNER_VERSION,
+    };
+}
+/**
+ * Quick scan for critical issues only
+ */
+export async function quickSecurityCheck(skill) {
+    const criticalPatterns = PATTERNS.filter((p) => p.severity === "critical" || p.severity === "high");
+    const contentToScan = [
+        skill.metadata.name,
+        skill.metadata.description,
+        skill.content.usage,
+        skill.content.quickstart,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    for (const { pattern } of criticalPatterns) {
+        if (pattern.test(contentToScan)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Get security summary for display
+ */
+export function getSecuritySummary(report) {
+    const counts = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+    };
+    for (const finding of report.findings) {
+        counts[finding.severity]++;
+    }
+    let status;
+    let color;
+    let summary;
+    switch (report.result) {
+        case "verified":
+            status = "✓ Verified";
+            color = "green";
+            summary = "No security issues found";
+            break;
+        case "warning":
+            status = "⚠ Warning";
+            color = "yellow";
+            summary = `${counts.medium + counts.low} warning(s) found`;
+            break;
+        case "failed":
+            status = "✗ Failed";
+            color = "red";
+            summary = `${counts.critical + counts.high} critical issue(s) found`;
+            break;
+        default:
+            status = "? Unverified";
+            color = "gray";
+            summary = "Not yet scanned";
+    }
+    return { status, color, summary, counts };
+}
+/**
+ * Format security findings for display
+ */
+export function formatFindings(findings) {
+    if (findings.length === 0) {
+        return ["No security issues found."];
+    }
+    const lines = [];
+    // Group by severity
+    const bySeverity = {
+        critical: [],
+        high: [],
+        medium: [],
+        low: [],
+        info: [],
+    };
+    for (const finding of findings) {
+        bySeverity[finding.severity].push(finding);
+    }
+    for (const severity of ["critical", "high", "medium", "low", "info"]) {
+        const group = bySeverity[severity];
+        if (group.length === 0)
+            continue;
+        lines.push(`\n${severity.toUpperCase()} (${group.length}):`);
+        for (const finding of group) {
+            lines.push(`  [${finding.type}] ${finding.description}`);
+            lines.push(`    Location: ${finding.location}`);
+            if (finding.evidence) {
+                lines.push(`    Evidence: ${finding.evidence}`);
+            }
+            if (finding.remediation) {
+                lines.push(`    Fix: ${finding.remediation}`);
+            }
+        }
+    }
+    return lines;
+}
+// ============================================================================
+// Export patterns for testing
+// ============================================================================
+export { PATTERNS };