stigmergy 1.2.8 → 1.2.11

package/src/core/skills/StigmergySkillManager.js

@@ -0,0 +1,357 @@
+/**
+ * StigmergySkillManager - Unified Skill Manager
+ * 
+ * Integrates OpenSkills core functionality + Stigmergy cross-CLI routing
+ * 
+ * License: Apache 2.0
+ */
+
+import { SkillReader } from './embedded-openskills/SkillReader.js';
+import { SkillInstaller } from './embedded-openskills/SkillInstaller.js';
+import { SkillParser } from './embedded-openskills/SkillParser.js';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+export class StigmergySkillManager {
+    constructor(options = {}) {
+        this.skillsDir = options.skillsDir || path.join(os.homedir(), '.stigmergy/skills');
+        
+        // Create custom search paths (prioritize skillsDir)
+        const customSearchPaths = [
+            this.skillsDir,                                      // Stigmergy skills dir (highest priority)
+            path.join(process.cwd(), '.agent/skills'),          // Project universal
+            path.join(os.homedir(), '.agent/skills'),           // Global universal
+            path.join(process.cwd(), '.claude/skills'),         // Project Claude
+            path.join(os.homedir(), '.claude/skills'),          // Global Claude
+        ];
+        
+        this.reader = new SkillReader(customSearchPaths);
+        this.installer = new SkillInstaller(this.skillsDir);
+        this.parser = new SkillParser();
+    }
+
+    /**
+     * Install skills from GitHub repository
+     * @param {string} source - GitHub URL or owner/repo
+     * @param {Object} options - Installation options
+     * @returns {Promise<Array>} List of installed skills
+     */
+    async install(source, options = {}) {
+        console.log(`[INFO] Installing skills from ${source}...`);
+        
+        try {
+            const skills = await this.installer.installFromGitHub(source, options);
+            
+            console.log(`\n[OK] Successfully installed ${skills.length} skill(s)`);
+            
+            // Auto-sync to AGENTS.md (if enabled)
+            if (options.autoSync !== false) {
+                await this.sync();
+            }
+            
+            return skills;
+        } catch (err) {
+            console.error(`[X] Installation failed: ${err.message}`);
+            throw err;
+        }
+    }
+
+    /**
+     * Read skill content (output format compatible with OpenSkills)
+     * @param {string} name - Skill name
+     * @returns {Promise<Object>} Skill content
+     */
+    async read(name) {
+        try {
+            const skill = await this.reader.readSkill(name);
+            
+            // Output format compatible with OpenSkills
+            console.log(`Reading: ${skill.name}`);
+            console.log(`Base directory: ${skill.baseDir}`);
+            console.log('');
+            console.log(skill.content);
+            console.log('');
+            console.log(`Skill read: ${skill.name}`);
+            
+            return skill;
+        } catch (err) {
+            console.error(`[X] Error reading skill '${name}': ${err.message}`);
+            console.error('\nSearched paths:');
+            this.reader.searchPaths.forEach(p => console.error(`  - ${p}`));
+            console.error('\nInstall skills: stigmergy skill install <source>');
+            throw err;
+        }
+    }
+
+    /**
+     * List all installed skills
+     * @returns {Promise<Array>} List of skills
+     */
+    async list() {
+        try {
+            const skills = await this.reader.listSkills();
+            
+            if (skills.length === 0) {
+                console.log('No skills installed');
+                console.log('\nInstall skills: stigmergy skill install <source>');
+                console.log('Example: stigmergy skill install anthropics/skills');
+                return [];
+            }
+            
+            console.log(`\nInstalled skills (${skills.length}):\n`);
+            
+            // Group by location for display
+            const grouped = this.groupByLocation(skills);
+            
+            for (const [location, locationSkills] of Object.entries(grouped)) {
+                console.log(`${this.getLocationIcon(location)} ${location}:`);
+                locationSkills.forEach(skill => {
+                    console.log(`  • ${skill.name.padEnd(30)} ${skill.description}`);
+                });
+                console.log('');
+            }
+            
+            return skills;
+        } catch (err) {
+            console.error(`[X] Error listing skills: ${err.message}`);
+            throw err;
+        }
+    }
+
+    /**
+     * Sync skills to CLI configuration files
+     * @returns {Promise<void>}
+     */
+    async sync() {
+        console.log('[INFO] Syncing skills to CLI configuration files...');
+        
+        try {
+            const skills = await this.reader.listSkills();
+            
+            if (skills.length === 0) {
+                console.log('[INFO] No skills to sync');
+                return;
+            }
+            
+            // Generate <available_skills> XML
+            const skillsXml = this.generateSkillsXml(skills);
+            
+            // All CLI configuration files to update
+            const cliFiles = [
+                'AGENTS.md',      // Universal config
+                'claude.md',      // Claude CLI
+                'qwen.md',        // Qwen CLI
+                'gemini.md',      // Gemini CLI
+                'iflow.md',       // iFlow CLI
+                'qodercli.md',    // Qoder CLI
+                'codebuddy.md',   // CodeBuddy CLI
+                'copilot.md',     // Copilot CLI
+                'codex.md'        // Codex CLI
+            ];
+            
+            let syncedCount = 0;
+            let createdCount = 0;
+            let skippedCount = 0;
+            
+            // Iterate through all CLI configuration files
+            for (const fileName of cliFiles) {
+                const filePath = path.join(process.cwd(), fileName);
+                
+                try {
+                    const result = await this.syncToFile(filePath, fileName, skillsXml);
+                    if (result === 'synced') {
+                        syncedCount++;
+                    } else if (result === 'created') {
+                        createdCount++;
+                    }
+                } catch (err) {
+                    console.log(`[INFO] Skipped ${fileName}: ${err.message}`);
+                    skippedCount++;
+                }
+            }
+            
+            // Output sync result summary
+            console.log(`\n[OK] Sync completed:`);
+            console.log(`   - Updated: ${syncedCount} file(s)`);
+            if (createdCount > 0) {
+                console.log(`   - Created: ${createdCount} file(s)`);
+            }
+            if (skippedCount > 0) {
+                console.log(`   - Skipped: ${skippedCount} file(s)`);
+            }
+            console.log(`   - Skills: ${skills.length}`);
+        } catch (err) {
+            console.error(`[X] Sync failed: ${err.message}`);
+            throw err;
+        }
+    }
+    
+    /**
+     * Sync skills to a single file
+     * @private
+     * @param {string} filePath - Full file path
+     * @param {string} fileName - File name (for logging)
+     * @param {string} skillsXml - Skills XML content
+     * @returns {Promise<string>} 'synced' | 'created'
+     */
+    async syncToFile(filePath, fileName, skillsXml) {
+        try {
+            let content = await fs.readFile(filePath, 'utf-8');
+            
+            // Replace or insert skills section
+            if (content.includes('<!-- SKILLS_START -->')) {
+                content = content.replace(
+                    /<!-- SKILLS_START -->.*?<!-- SKILLS_END -->/s,
+                    `<!-- SKILLS_START -->\n${skillsXml}\n<!-- SKILLS_END -->`
+                );
+            } else {
+                // Add to end of file
+                content += `\n\n<!-- SKILLS_START -->\n${skillsXml}\n<!-- SKILLS_END -->\n`;
+            }
+            
+            await fs.writeFile(filePath, content, 'utf-8');
+            console.log(`   [OK] ${fileName}`);
+            return 'synced';
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                // File does not exist, create new file
+                const cliName = fileName.replace('.md', '');
+                const content = `# ${cliName.toUpperCase()} Configuration\n\n<!-- SKILLS_START -->\n${skillsXml}\n<!-- SKILLS_END -->\n`;
+                await fs.writeFile(filePath, content, 'utf-8');
+                console.log(`   [OK] ${fileName} (created)`);
+                return 'created';
+            } else {
+                throw err;
+            }
+        }
+    }
+
+    /**
+     * Generate <available_skills> XML
+     * @private
+     */
+    generateSkillsXml(skills) {
+        let xml = '<skills_system priority="1">\n\n';
+        xml += '## Stigmergy Skills\n\n';
+        xml += '<usage>\n';
+        xml += 'Load skills using Stigmergy skill manager:\n\n';
+        xml += 'Direct call (current CLI):\n';
+        xml += '  Bash("stigmergy skill read <skill-name>")\n\n';
+        xml += 'Cross-CLI call (specify CLI):\n';
+        xml += '  Bash("stigmergy use <cli-name> skill <skill-name>")\n\n';
+        xml += 'Smart routing (auto-select best CLI):\n';
+        xml += '  Bash("stigmergy call skill <skill-name>")\n\n';
+        xml += 'The skill content will load with detailed instructions.\n';
+        xml += 'Base directory will be provided for resolving bundled resources.\n';
+        xml += '</usage>\n\n';
+        xml += '<available_skills>\n\n';
+        
+        for (const skill of skills) {
+            xml += '<skill>\n';
+            xml += `<name>${skill.name}</name>\n`;
+            xml += `<description>${this.escapeXml(skill.description)}</description>\n`;
+            xml += `<location>${skill.location}</location>\n`;
+            xml += '</skill>\n\n';
+        }
+        
+        xml += '</available_skills>\n\n';
+        xml += '</skills_system>';
+        
+        return xml;
+    }
+
+    /**
+     * Remove skill
+     * @param {string} name - Skill name
+     * @returns {Promise<void>}
+     */
+    async remove(name) {
+        try {
+            await this.installer.uninstallSkill(name);
+            console.log(`[OK] Removed skill: ${name}`);
+            
+            // Auto-sync
+            await this.sync();
+        } catch (err) {
+            console.error(`[X] Failed to remove skill: ${err.message}`);
+            throw err;
+        }
+    }
+
+    /**
+     * Validate skill
+     * @param {string} pathOrName - Skill path or name
+     * @returns {Promise<Object>} Validation result
+     */
+    async validate(pathOrName) {
+        try {
+            let content;
+            
+            // Determine if path or name
+            if (pathOrName.includes('/') || pathOrName.includes('\\')) {
+                // Is a path
+                content = await fs.readFile(pathOrName, 'utf-8');
+            } else {
+                // Is a name
+                const skill = await this.reader.readSkill(pathOrName);
+                content = skill.content;
+            }
+            
+            const validation = this.parser.validateSkill(content);
+            
+            if (validation.valid) {
+                console.log('[OK] Skill validation passed');
+            } else {
+                console.log('[X] Skill validation failed:');
+                validation.errors.forEach(err => console.log(`   - ${err}`));
+            }
+            
+            return validation;
+        } catch (err) {
+            console.error(`[X] Validation error: ${err.message}`);
+            throw err;
+        }
+    }
+
+    /**
+     * Group by location
+     * @private
+     */
+    groupByLocation(skills) {
+        return skills.reduce((groups, skill) => {
+            const loc = skill.location || 'unknown';
+            if (!groups[loc]) groups[loc] = [];
+            groups[loc].push(skill);
+            return groups;
+        }, {});
+    }
+
+    /**
+     * Get location icon
+     * @private
+     */
+    getLocationIcon(location) {
+        const icons = {
+            'stigmergy': '[GLOBAL]',
+            'project': '[PROJECT]',
+            'global': '[HOME]',
+            'claude': '[CLAUDE]',
+            'universal': '[UNIVERSAL]'
+        };
+        return icons[location] || '[INFO]';
+    }
+
+    /**
+     * XML escape
+     * @private
+     */
+    escapeXml(str) {
+        return str
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+}

package/src/core/skills/__tests__/SkillInstaller.test.js

@@ -0,0 +1,275 @@
+/**
+ * SkillInstaller Tests - TDD Approach
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { SkillInstaller } from '../embedded-openskills/SkillInstaller.js';
+
+describe('SkillInstaller', () => {
+    let installer;
+    let testInstallDir;
+
+    beforeEach(async () => {
+        testInstallDir = path.join(os.tmpdir(), `test-install-${Date.now()}`);
+        await fs.mkdir(testInstallDir, { recursive: true });
+        
+        installer = new SkillInstaller(testInstallDir);
+    });
+
+    afterEach(async () => {
+        await fs.rm(testInstallDir, { recursive: true, force: true });
+    });
+
+    describe('parseGitHubUrl', () => {
+        it('should parse standard GitHub URL', () => {
+            // Arrange
+            const url = 'https://github.com/owner/repo';
+
+            // Act
+            const result = installer.parseGitHubUrl(url);
+
+            // Assert
+            expect(result.owner).toBe('owner');
+            expect(result.repo).toBe('repo');
+        });
+
+        it('should parse GitHub URL with .git suffix', () => {
+            // Arrange
+            const url = 'https://github.com/owner/repo.git';
+
+            // Act
+            const result = installer.parseGitHubUrl(url);
+
+            // Assert
+            expect(result.owner).toBe('owner');
+            expect(result.repo).toBe('repo');
+        });
+
+        it('should parse short format owner/repo', () => {
+            // Arrange
+            const url = 'owner/repo';
+
+            // Act
+            const result = installer.parseGitHubUrl(url);
+
+            // Assert
+            expect(result.owner).toBe('owner');
+            expect(result.repo).toBe('repo');
+        });
+
+        it('should throw error for invalid URL', () => {
+            // Arrange
+            const url = 'not-a-valid-url';
+
+            // Act & Assert
+            expect(() => installer.parseGitHubUrl(url))
+                .toThrow('Invalid GitHub URL');
+        });
+    });
+
+    describe('scanSkills', () => {
+        it('should find skills in directory', async () => {
+            // Arrange: Create test skill structure
+            const skill1Dir = path.join(testInstallDir, 'skill-1');
+            const skill2Dir = path.join(testInstallDir, 'skill-2');
+            
+            await fs.mkdir(skill1Dir, { recursive: true });
+            await fs.mkdir(skill2Dir, { recursive: true });
+            
+            await fs.writeFile(
+                path.join(skill1Dir, 'SKILL.md'),
+                '---\nname: skill-1\ndescription: First skill\n---\n'
+            );
+            await fs.writeFile(
+                path.join(skill2Dir, 'SKILL.md'),
+                '---\nname: skill-2\ndescription: Second skill\n---\n'
+            );
+
+            // Act
+            const skills = await installer.scanSkills(testInstallDir);
+
+            // Assert
+            expect(skills).toHaveLength(2);
+            expect(skills.map(s => s.name)).toContain('skill-1');
+            expect(skills.map(s => s.name)).toContain('skill-2');
+        });
+
+        it('should find nested skills', async () => {
+            // Arrange: Create nested structure
+            const nestedDir = path.join(testInstallDir, 'category', 'skill-nested');
+            await fs.mkdir(nestedDir, { recursive: true });
+            await fs.writeFile(
+                path.join(nestedDir, 'SKILL.md'),
+                '---\nname: skill-nested\n---\n'
+            );
+
+            // Act
+            const skills = await installer.scanSkills(testInstallDir);
+
+            // Assert
+            expect(skills).toHaveLength(1);
+            expect(skills[0].name).toBe('skill-nested');
+        });
+
+        it('should ignore directories without SKILL.md', async () => {
+            // Arrange
+            await fs.mkdir(path.join(testInstallDir, 'not-a-skill'));
+            const validDir = path.join(testInstallDir, 'valid-skill');
+            await fs.mkdir(validDir);
+            await fs.writeFile(
+                path.join(validDir, 'SKILL.md'),
+                '---\nname: valid-skill\n---\n'
+            );
+
+            // Act
+            const skills = await installer.scanSkills(testInstallDir);
+
+            // Assert
+            expect(skills).toHaveLength(1);
+            expect(skills[0].name).toBe('valid-skill');
+        });
+
+        it('should include skill metadata', async () => {
+            // Arrange
+            const skillDir = path.join(testInstallDir, 'meta-skill');
+            await fs.mkdir(skillDir);
+            await fs.writeFile(
+                path.join(skillDir, 'SKILL.md'),
+                '---\nname: meta-skill\ndescription: Has metadata\nversion: 2.0.0\n---\n'
+            );
+
+            // Act
+            const skills = await installer.scanSkills(testInstallDir);
+
+            // Assert
+            expect(skills[0].description).toBe('Has metadata');
+            expect(skills[0].version).toBe('2.0.0');
+        });
+    });
+
+    describe('installSkill', () => {
+        it('should copy skill to target directory', async () => {
+            // Arrange
+            const sourceDir = path.join(testInstallDir, 'source');
+            const skillDir = path.join(sourceDir, 'test-skill');
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(
+                path.join(skillDir, 'SKILL.md'),
+                '---\nname: test-skill\n---\n'
+            );
+
+            const targetDir = path.join(testInstallDir, 'target');
+            installer = new SkillInstaller(targetDir);
+
+            const skill = {
+                name: 'test-skill',
+                path: skillDir
+            };
+
+            // Act
+            await installer.installSkill(skill);
+
+            // Assert
+            const installed = await fs.access(
+                path.join(targetDir, 'test-skill', 'SKILL.md')
+            ).then(() => true).catch(() => false);
+            expect(installed).toBe(true);
+        });
+
+        it('should copy bundled resources', async () => {
+            // Arrange
+            const sourceDir = path.join(testInstallDir, 'source');
+            const skillDir = path.join(sourceDir, 'skill-with-resources');
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.mkdir(path.join(skillDir, 'scripts'));
+            await fs.mkdir(path.join(skillDir, 'references'));
+            
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), '---\nname: skill\n---\n');
+            await fs.writeFile(path.join(skillDir, 'scripts', 'helper.py'), 'print("hi")');
+            await fs.writeFile(path.join(skillDir, 'references', 'guide.md'), '# Guide');
+
+            const targetDir = path.join(testInstallDir, 'target');
+            installer = new SkillInstaller(targetDir);
+
+            const skill = {
+                name: 'skill-with-resources',
+                path: skillDir
+            };
+
+            // Act
+            await installer.installSkill(skill);
+
+            // Assert
+            const scriptExists = await fs.access(
+                path.join(targetDir, 'skill-with-resources', 'scripts', 'helper.py')
+            ).then(() => true).catch(() => false);
+            const refExists = await fs.access(
+                path.join(targetDir, 'skill-with-resources', 'references', 'guide.md')
+            ).then(() => true).catch(() => false);
+            
+            expect(scriptExists).toBe(true);
+            expect(refExists).toBe(true);
+        });
+
+        it('should not overwrite existing skill by default', async () => {
+            // Arrange
+            const targetDir = path.join(testInstallDir, 'target');
+            const existingSkillDir = path.join(targetDir, 'existing-skill');
+            await fs.mkdir(existingSkillDir, { recursive: true });
+            await fs.writeFile(
+                path.join(existingSkillDir, 'SKILL.md'),
+                'original content'
+            );
+
+            const sourceDir = path.join(testInstallDir, 'source', 'existing-skill');
+            await fs.mkdir(sourceDir, { recursive: true });
+            await fs.writeFile(
+                path.join(sourceDir, 'SKILL.md'),
+                'new content'
+            );
+
+            installer = new SkillInstaller(targetDir);
+            const skill = { name: 'existing-skill', path: sourceDir };
+
+            // Act & Assert
+            await expect(installer.installSkill(skill))
+                .rejects
+                .toThrow('already exists');
+        });
+    });
+
+    describe('calculateSize', () => {
+        it('should calculate directory size', async () => {
+            // Arrange
+            const dir = path.join(testInstallDir, 'size-test');
+            await fs.mkdir(dir);
+            await fs.writeFile(path.join(dir, 'file1.txt'), 'x'.repeat(100));
+            await fs.writeFile(path.join(dir, 'file2.txt'), 'y'.repeat(200));
+
+            // Act
+            const size = await installer.calculateSize(dir);
+
+            // Assert
+            expect(size).toBeGreaterThan(0);
+            expect(size).toBe(300); // 100 + 200 bytes
+        });
+
+        it('should include subdirectories in size', async () => {
+            // Arrange
+            const dir = path.join(testInstallDir, 'nested-size-test');
+            const subdir = path.join(dir, 'subdir');
+            await fs.mkdir(subdir, { recursive: true });
+            await fs.writeFile(path.join(dir, 'file1.txt'), 'x'.repeat(100));
+            await fs.writeFile(path.join(subdir, 'file2.txt'), 'y'.repeat(150));
+
+            // Act
+            const size = await installer.calculateSize(dir);
+
+            // Assert
+            expect(size).toBe(250); // 100 + 150 bytes
+        });
+    });
+});