@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/.agent/scripts-js/utils/process-manager.js

@@ -0,0 +1,148 @@
+/**
+ * Process Manager - Agent Skill Kit
+ * ==================================
+ * Cross-platform process management (PID files, process detection, termination)
+ * Replacement for Python os.kill + taskkill
+ */
+
+import { readFile, writeFile, unlink } from 'fs/promises';
+import { resolve } from 'path';
+
+/**
+ * Save PID to file
+ * @param {string} pidFile - Path to PID file
+ * @param {number} pid - Process ID
+ */
+export async function savePid(pidFile, pid) {
+    await writeFile(pidFile, pid.toString(), 'utf-8');
+}
+
+/**
+ * Load PID from file
+ * @param {string} pidFile - Path to PID file
+ * @returns {Promise<number|null>} - PID or null if file doesn't exist
+ */
+export async function loadPid(pidFile) {
+    try {
+        const content = await readFile(pidFile, 'utf-8');
+        const pid = parseInt(content.trim(), 10);
+        return isNaN(pid) ? null : pid;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Delete PID file
+ * @param {string} pidFile - Path to PID file
+ */
+export async function deletePidFile(pidFile) {
+    try {
+        await unlink(pidFile);
+    } catch {
+        // Ignore if file doesn't exist
+    }
+}
+
+/**
+ * Check if process is running
+ * @param {number} pid - Process ID
+ * @returns {boolean}
+ */
+export function isRunning(pid) {
+    try {
+        // Sending signal 0 checks existence without killing
+        process.kill(pid, 0);
+        return true;
+    } catch (err) {
+        // ESRCH = No such process
+        return err.code !== 'ESRCH';
+    }
+}
+
+/**
+ * Kill process tree (cross-platform)
+ * Uses tree-kill package for reliable process tree termination
+ * 
+ * @param {number} pid - Process ID
+ * @param {string} signal - Signal to send (default: SIGTERM)
+ * @returns {Promise<void>}
+ */
+export async function killProcess(pid, signal = 'SIGTERM') {
+    // For now, use native process.kill
+    // TODO: Add tree-kill package for better Windows support
+    return new Promise((resolve, reject) => {
+        try {
+            if (!isRunning(pid)) {
+                resolve();
+                return;
+            }
+
+            process.kill(pid, signal);
+
+            // Wait for process to die
+            const checkInterval = setInterval(() => {
+                if (!isRunning(pid)) {
+                    clearInterval(checkInterval);
+                    resolve();
+                }
+            }, 100);
+
+            // Timeout after 5 seconds, force kill
+            setTimeout(() => {
+                clearInterval(checkInterval);
+                try {
+                    if (isRunning(pid)) {
+                        process.kill(pid, 'SIGKILL');
+                    }
+                } catch {
+                    // Process already dead
+                }
+                resolve();
+            }, 5000);
+
+        } catch (err) {
+            if (err.code === 'ESRCH') {
+                // Process already dead
+                resolve();
+            } else {
+                reject(err);
+            }
+        }
+    });
+}
+
+/**
+ * Kill process tree using platform-specific commands
+ * Fallback when tree-kill is not available
+ * 
+ * @param {number} pid - Process ID
+ */
+export async function killProcessTree(pid) {
+    const { exec } = await import('child_process');
+    const { promisify } = await import('util');
+    const execAsync = promisify(exec);
+
+    if (process.platform === 'win32') {
+        // Windows: Use taskkill with /T (tree) flag
+        try {
+            await execAsync(`taskkill /F /T /PID ${pid}`);
+        } catch {
+            // Ignore errors (process might already be dead)
+        }
+    } else {
+        // Unix: Kill process group
+        try {
+            process.kill(-pid, 'SIGTERM');
+
+            // Wait 2s then SIGKILL if still alive
+            await new Promise(resolve => setTimeout(resolve, 2000));
+
+            if (isRunning(pid)) {
+                process.kill(-pid, 'SIGKILL');
+            }
+        } catch {
+            // Ignore errors
+        }
+    }
+}

package/.agent/scripts-js/utils/reporter.js

@@ -0,0 +1,168 @@
+/**
+ * Reporter - Agent Skill Kit
+ * ===========================
+ * Result formatting utilities (JSON, summary tables)
+ * Replacement for Python report formatting functions
+ */
+
+import { colors } from './colors.js';
+
+/**
+ * Format validation results as JSON
+ * 
+ * @param {Array} results - Array of check results
+ * @param {string} projectPath - Project path
+ * @param {string|null} url - URL if provided
+ * @param {Date} startTime - Start time
+ * @returns {string} JSON string
+ */
+export function formatJsonOutput(results, projectPath, url, startTime) {
+    const totalDuration = (Date.now() - startTime.getTime()) / 1000;
+
+    const output = {
+        version: '3.2.0',
+        timestamp: new Date().toISOString(),
+        project_path: projectPath,
+        url: url || null,
+        summary: {
+            total: results.length,
+            passed: results.filter(r => r.passed && !r.skipped).length,
+            failed: results.filter(r => !r.passed && !r.skipped).length,
+            skipped: results.filter(r => r.skipped).length,
+            duration: Math.round(totalDuration * 100) / 100
+        },
+        results: results.map(r => ({
+            name: r.name,
+            passed: r.passed,
+            skipped: r.skipped || false,
+            duration: r.duration || 0,
+            output: r.output || '',
+            error: r.error || ''
+        }))
+    };
+
+    return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Print summary of validation results
+ * 
+ * @param {Array} results - Array of check results
+ * @returns {boolean} - True if all passed
+ */
+export function printSummary(results) {
+    console.log(`\n${colors.bold}${colors.cyan}${'='.repeat(60)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'📊 CHECKLIST SUMMARY'.padStart(38)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'='.repeat(60)}${colors.reset}\n`);
+
+    const passedCount = results.filter(r => r.passed && !r.skipped).length;
+    const failedCount = results.filter(r => !r.passed && !r.skipped).length;
+    const skippedCount = results.filter(r => r.skipped).length;
+
+    console.log(`Total Checks: ${results.length}`);
+    console.log(`${colors.green}✅ Passed: ${passedCount}${colors.reset}`);
+    console.log(`${colors.red}❌ Failed: ${failedCount}${colors.reset}`);
+    console.log(`${colors.yellow}⏭️  Skipped: ${skippedCount}${colors.reset}\n`);
+
+    // Detailed results
+    for (const r of results) {
+        let status;
+        if (r.skipped) {
+            status = `${colors.yellow}⏭️ ${colors.reset}`;
+        } else if (r.passed) {
+            status = `${colors.green}✅${colors.reset}`;
+        } else {
+            status = `${colors.red}❌${colors.reset}`;
+        }
+        console.log(`${status} ${r.name}`);
+    }
+
+    console.log();
+
+    if (failedCount > 0) {
+        console.log(`${colors.red}❌ ${failedCount} check(s) FAILED - Please fix before proceeding${colors.reset}`);
+        return false;
+    } else {
+        console.log(`${colors.green}✅ All checks PASSED ✨${colors.reset}`);
+        return true;
+    }
+}
+
+/**
+ * Print comprehensive final report with category breakdown
+ * 
+ * @param {Array} results - Array of check results with category field
+ * @param {Date} startTime - Start time
+ * @returns {boolean} - True if all passed
+ */
+export function printFinalReport(results, startTime) {
+    const totalDuration = (Date.now() - startTime.getTime()) / 1000;
+
+    console.log(`\n${colors.bold}${colors.cyan}${'='.repeat(70)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'📊 FULL VERIFICATION REPORT'.padStart(48)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'='.repeat(70)}${colors.reset}\n`);
+
+    // Statistics
+    const total = results.length;
+    const passed = results.filter(r => r.passed && !r.skipped).length;
+    const failed = results.filter(r => !r.passed && !r.skipped).length;
+    const skipped = results.filter(r => r.skipped).length;
+
+    console.log(`Total Duration: ${totalDuration.toFixed(1)}s`);
+    console.log(`Total Checks: ${total}`);
+    console.log(`${colors.green}✅ Passed: ${passed}${colors.reset}`);
+    console.log(`${colors.red}❌ Failed: ${failed}${colors.reset}`);
+    console.log(`${colors.yellow}⏭️  Skipped: ${skipped}${colors.reset}\n`);
+
+    // Category breakdown
+    console.log(`${colors.bold}Results by Category:${colors.reset}`);
+    let currentCategory = null;
+
+    for (const r of results) {
+        // Print category header if changed
+        if (r.category && r.category !== currentCategory) {
+            currentCategory = r.category;
+            console.log(`\n${colors.bold}${colors.cyan}${currentCategory}:${colors.reset}`);
+        }
+
+        // Print result
+        let status;
+        if (r.skipped) {
+            status = `${colors.yellow}⏭️ ${colors.reset}`;
+        } else if (r.passed) {
+            status = `${colors.green}✅${colors.reset}`;
+        } else {
+            status = `${colors.red}❌${colors.reset}`;
+        }
+
+        const durationStr = !r.skipped && r.duration ? ` (${r.duration.toFixed(1)}s)` : '';
+        console.log(`  ${status} ${r.name}${durationStr}`);
+    }
+
+    console.log();
+
+    // Failed checks detail
+    if (failed > 0) {
+        console.log(`${colors.bold}${colors.red}❌ FAILED CHECKS:${colors.reset}`);
+        for (const r of results) {
+            if (!r.passed && !r.skipped) {
+                console.log(`\n${colors.red}✗ ${r.name}${colors.reset}`);
+                if (r.error) {
+                    const errorPreview = r.error.substring(0, 200);
+                    console.log(`  Error: ${errorPreview}`);
+                }
+            }
+        }
+        console.log();
+    }
+
+    // Final verdict
+    if (failed > 0) {
+        console.log(`${colors.red}❌ VERIFICATION FAILED - ${failed} check(s) need attention${colors.reset}`);
+        console.log(`\n${colors.yellow}💡 Tip: Fix critical (security, lint) issues first${colors.reset}\n`);
+        return false;
+    } else {
+        console.log(`${colors.green}✨ ALL CHECKS PASSED - Ready for deployment! ✨${colors.reset}\n`);
+        return true;
+    }
+}

package/.agent/scripts-js/utils/runner.js

@@ -0,0 +1,117 @@
+/**
+ * Script Runner - Agent Skill Kit
+ * ================================
+ * Replacement for Python subprocess.run()
+ * Executes scripts with timeout, output capture, and error handling.
+ */
+
+import { spawn } from 'child_process';
+import { resolve } from 'path';
+
+/**
+ * Run a script with timeout and output capture
+ * 
+ * @param {string} scriptPath - Path to script (relative or absolute)
+ * @param {string[]} args - Arguments to pass to script
+ * @param {Object} options - Execution options
+ * @param {number} options.timeout - Timeout in milliseconds (default: 300000 = 5 min)
+ * @param {string} options.cwd - Working directory
+ * @param {Object} options.env - Environment variables
+ * @returns {Promise<{code: number, stdout: string, stderr: string, passed: boolean}>}
+ */
+export async function runScript(scriptPath, args = [], options = {}) {
+    const {
+        timeout = 300000, // 5 minute default
+        cwd = process.cwd(),
+        env = process.env
+    } = options;
+
+    const fullPath = resolve(cwd, scriptPath);
+
+    // Determine command based on file extension
+    const extension = scriptPath.split('.').pop();
+    let command, commandArgs;
+
+    if (extension === 'js' || extension === 'mjs') {
+        command = 'node';
+        commandArgs = [fullPath, ...args];
+    } else if (extension === 'py') {
+        command = 'python';
+        commandArgs = [fullPath, ...args];
+    } else {
+        // Assume executable
+        command = fullPath;
+        commandArgs = args;
+    }
+
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, commandArgs, {
+            cwd,
+            env: { ...env },
+            shell: true, // Required for npm/node on Windows
+            windowsHide: true
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+
+        // Timeout handler
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            // Force kill after 2s if not terminated
+            setTimeout(() => {
+                if (!child.killed) {
+                    child.kill('SIGKILL');
+                }
+            }, 2000);
+        }, timeout);
+
+        // Capture output
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+
+        // Handle completion
+        child.on('close', (code) => {
+            clearTimeout(timer);
+
+            if (timedOut) {
+                reject(new Error(`Timeout: Script exceeded ${timeout}ms`));
+            } else {
+                resolve({
+                    code: code ?? 1,
+                    stdout,
+                    stderr,
+                    passed: code === 0
+                });
+            }
+        });
+
+        // Handle spawn errors
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+
+/**
+ * Check if a script file exists
+ * @param {string} scriptPath - Path to check
+ * @returns {Promise<boolean>}
+ */
+export async function scriptExists(scriptPath) {
+    const { access } = await import('fs/promises');
+    try {
+        await access(scriptPath);
+        return true;
+    } catch {
+        return false;
+    }
+}

package/.agent/scripts-js/verify-skills.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Skill Registry Verifier
+ * Validates all skills have required metadata and coordination mappings are valid.
+ * 
+ * Usage: node verify-skills.js
+ */
+
+import { readFile, readdir, stat } from 'fs/promises';
+import { join } from 'path';
+
+const SKILLS_DIR = join(process.cwd(), '.agent', 'skills');
+const REGISTRY_PATH = join(SKILLS_DIR, 'registry.json');
+
+const REQUIRED_METADATA = ['category', 'triggers', 'coordinates_with', 'success_metrics'];
+const VALID_CATEGORIES = ['core', 'framework', 'architecture', 'devops', 'testing', 'specialized'];
+
+const colors = {
+  green: '\x1b[92m',
+  red: '\x1b[91m',
+  yellow: '\x1b[93m',
+  cyan: '\x1b[96m',
+  reset: '\x1b[0m'
+};
+
+function log(type, msg) {
+  const icons = { pass: '✓', fail: '✗', warn: '⚠', info: '→' };
+  const colorMap = { pass: 'green', fail: 'red', warn: 'yellow', info: 'cyan' };
+  console.log(`${colors[colorMap[type]]}${icons[type]}${colors.reset} ${msg}`);
+}
+
+async function loadRegistry() {
+  const content = await readFile(REGISTRY_PATH, 'utf-8');
+  return JSON.parse(content);
+}
+
+async function getSkillDirs() {
+  const entries = await readdir(SKILLS_DIR);
+  const dirs = [];
+  
+  for (const entry of entries) {
+    const fullPath = join(SKILLS_DIR, entry);
+    try {
+      const stats = await stat(fullPath); // Follow junctions/symlinks
+      if (stats.isDirectory()) {
+        dirs.push(entry);
+      }
+    } catch {
+      // Ignore broken links or inaccessible items
+    }
+  }
+  
+  return dirs;
+}
+
+async function verifySkillFrontmatter(skillName) {
+  const skillPath = join(SKILLS_DIR, skillName, 'SKILL.md');
+  const issues = [];
+  
+  try {
+    const content = await readFile(skillPath, 'utf-8');
+    
+    // Check for triggers
+    if (!content.includes('Triggers on:')) {
+      issues.push('Missing "Triggers on:" in description');
+    }
+    
+    // Check for coordinates
+    if (!content.includes('Coordinates with:')) {
+      issues.push('Missing "Coordinates with:" in description');
+    }
+    
+    // Check for metadata block
+    if (!content.includes('success_metrics:')) {
+      issues.push('Missing success_metrics in metadata');
+    }
+    
+    if (!content.includes('category:')) {
+      issues.push('Missing category in metadata');
+    }
+    
+  } catch (err) {
+    issues.push(`Cannot read SKILL.md: ${err.message}`);
+  }
+  
+  return issues;
+}
+
+function verifyRegistrySkill(skill, allSkillNames) {
+  const issues = [];
+  
+  // Check required fields
+  for (const field of REQUIRED_METADATA) {
+    if (!skill[field]) {
+      issues.push(`Missing field: ${field}`);
+    }
+  }
+  
+  // Validate category
+  if (skill.category && !VALID_CATEGORIES.includes(skill.category)) {
+    issues.push(`Invalid category: ${skill.category}`);
+  }
+  
+  // Validate coordinates_with references exist
+  if (skill.coordinates_with) {
+    for (const coord of skill.coordinates_with) {
+      if (!allSkillNames.includes(coord)) {
+        issues.push(`Invalid coordination ref: ${coord}`);
+      }
+    }
+  }
+  
+  return issues;
+}
+
+function verifyChains(chains, allSkillNames) {
+  const issues = [];
+  
+  for (const [chainName, chain] of Object.entries(chains)) {
+    if (!chain.skills || !Array.isArray(chain.skills)) {
+      issues.push(`Chain "${chainName}": Missing skills array`);
+      continue;
+    }
+    
+    for (const skill of chain.skills) {
+      if (!allSkillNames.includes(skill)) {
+        issues.push(`Chain "${chainName}": Invalid skill ref: ${skill}`);
+      }
+    }
+    
+    if (!chain.trigger) {
+      issues.push(`Chain "${chainName}": Missing trigger phrase`);
+    }
+  }
+  
+  return issues;
+}
+
+async function main() {
+  console.log('\n🔍 Skill Registry Verification\n');
+  console.log('='.repeat(50));
+  
+  let errors = 0;
+  let warnings = 0;
+  
+  // Load registry
+  let registry;
+  try {
+    registry = await loadRegistry();
+    log('pass', `Registry loaded: ${registry.skills.length} skills`);
+  } catch (err) {
+    log('fail', `Cannot load registry: ${err.message}`);
+    process.exit(1);
+  }
+  
+  // Get filesystem skills
+  const fsDirs = await getSkillDirs();
+  const registrySkillNames = registry.skills.map(s => s.name);
+  
+  // Check for unregistered skills
+  console.log('\n📁 Filesystem vs Registry:');
+  let coordinationErrors = 0;
+  let implementationGaps = 0;
+  
+  for (const dir of fsDirs) {
+    if (!registrySkillNames.includes(dir)) {
+      log('warn', `Skill "${dir}" exists on disk but not in registry`);
+      warnings++;
+    }
+  }
+  
+  // Check for missing skills (FOLDERS)
+  for (const name of registrySkillNames) {
+    if (!fsDirs.includes(name)) {
+      log('fail', `Skill "${name}" in registry but folder missing on disk`);
+      errors++;
+      coordinationErrors++;
+    }
+  }
+  
+  if (coordinationErrors === 0) {
+    log('pass', 'All registry skills have matching folders');
+  }
+  
+  // Count implementation gaps (missing SKILL.md)
+  for (const skill of registry.skills) {
+    const skillPath = join(SKILLS_DIR, skill.name, 'SKILL.md');
+    try {
+      await readFile(skillPath, 'utf-8');
+    } catch {
+      implementationGaps++;
+    }
+  }
+  
+  if (implementationGaps > 0) {
+    log('warn', `${implementationGaps}/${registry.skills.length} skills missing SKILL.md (implementation incomplete)`);
+  } else {
+    log('pass', 'All skills have SKILL.md files');
+  }
+  
+  // Verify each skill
+  console.log('\n📋 Skill Validation:');
+  for (const skill of registry.skills) {
+    const regIssues = verifyRegistrySkill(skill, registrySkillNames);
+    const fsIssues = await verifySkillFrontmatter(skill.name);
+    const allIssues = [...regIssues, ...fsIssues];
+    
+    if (allIssues.length === 0) {
+      log('pass', skill.name);
+    } else {
+      log('fail', `${skill.name}: ${allIssues.length} issues`);
+      for (const issue of allIssues) {
+        console.log(`     - ${issue}`);
+      }
+      errors += allIssues.length;
+    }
+  }
+  
+  // Verify chains
+  if (registry.chains) {
+    console.log('\n🔗 Chain Validation:');
+    const chainIssues = verifyChains(registry.chains, registrySkillNames);
+    
+    if (chainIssues.length === 0) {
+      log('pass', `All ${Object.keys(registry.chains).length} chains valid`);
+    } else {
+      for (const issue of chainIssues) {
+        log('fail', issue);
+        errors++;
+      }
+    }
+  }
+  
+  // Summary
+  console.log('\n' + '='.repeat(50));
+  console.log(`📊 Summary: ${registry.skills.length} skills, ${Object.keys(registry.chains || {}).length} chains`);
+  
+  if (errors > 0) {
+    log('fail', `${errors} errors found`);
+    process.exit(1);
+  } else if (warnings > 0) {
+    log('warn', `${warnings} warnings (non-blocking)`);
+    log('pass', 'Verification passed with warnings');
+  } else {
+    log('pass', 'All validations passed!');
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});