skill-validator 1.0.0

package/bin/skill-validator.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const fs = require('fs');
+const path = require('path');
+const { SkillValidator } = require('../lib/validator');
+const { formatTerminalReport, formatJsonReport } = require('../lib/formatter');
+
+program
+  .name('skill-validator')
+  .description('Validate OpenClaw skill.md files for security, documentation, and best practices')
+  .version('1.0.0');
+
+program
+  .command('validate <filepath>')
+  .description('Validate a single skill.md file')
+  .option('-j, --json', 'Output as JSON instead of formatted terminal output')
+  .option('-o, --output <file>', 'Write report to file (supports .json and .txt)')
+  .action(async (filepath, options) => {
+    try {
+      if (!fs.existsSync(filepath)) {
+        console.error(`✗ File not found: ${filepath}`);
+        process.exit(1);
+      }
+
+      const content = fs.readFileSync(filepath, 'utf-8');
+      const validator = new SkillValidator();
+      const report = validator.validate(content, filepath);
+
+      let output;
+      if (options.json) {
+        output = formatJsonReport(report);
+        console.log(JSON.stringify(JSON.parse(output), null, 2));
+      } else {
+        output = formatTerminalReport(report);
+        console.log(output);
+      }
+
+      if (options.output) {
+        fs.writeFileSync(options.output, output);
+        console.log(`\n📄 Report written to: ${options.output}`);
+      }
+
+      if (!report.passed) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error('✗ Validation error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('scan <directory>')
+  .description('Scan all skill.md files in a directory')
+  .option('-j, --json', 'Output as JSON')
+  .option('-o, --output <file>', 'Write report to file')
+  .action(async (directory, options) => {
+    try {
+      if (!fs.existsSync(directory)) {
+        console.error(`✗ Directory not found: ${directory}`);
+        process.exit(1);
+      }
+
+      const validator = new SkillValidator();
+      const results = [];
+      let totalIssues = 0;
+      let totalPassed = 0;
+
+      const walkDir = (dir) => {
+        const files = fs.readdirSync(dir);
+        files.forEach(file => {
+          const fullPath = path.join(dir, file);
+          const stat = fs.statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            walkDir(fullPath);
+          } else if (file === 'skill.md' || file.endsWith('.skill.md')) {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const report = validator.validate(content, fullPath);
+            results.push(report);
+            totalIssues += report.issues.length;
+            if (report.passed) totalPassed++;
+          }
+        });
+      };
+
+      walkDir(directory);
+
+      const summary = {
+        filesScanned: results.length,
+        filePassed: totalPassed,
+        fileFailed: results.length - totalPassed,
+        totalIssues,
+        results
+      };
+
+      let output;
+      if (options.json) {
+        output = JSON.stringify(summary, null, 2);
+      } else {
+        output = formatScanReport(summary);
+      }
+
+      console.log(output);
+
+      if (options.output) {
+        fs.writeFileSync(options.output, output);
+        console.log(`\n📄 Report written to: ${options.output}`);
+      }
+
+      if (totalIssues > 0) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error('✗ Scan error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();
+
+function formatScanReport(summary) {
+  const chalk = require('chalk');
+  let output = chalk.bold(`\n📊 Skill Validator Scan Report\n`);
+  output += chalk.gray('─'.repeat(50)) + '\n\n';
+  output += `Files scanned:  ${summary.filesScanned}\n`;
+  output += chalk.green(`Passed:         ${summary.filePassed}\n`);
+  output += chalk.red(`Failed:         ${summary.fileFailed}\n`);
+  output += chalk.yellow(`Total issues:   ${summary.totalIssues}\n\n`);
+
+  summary.results.forEach(result => {
+    const icon = result.passed ? chalk.green('✓') : chalk.red('✗');
+    output += `${icon} ${result.filepath}\n`;
+    if (result.issues.length > 0) {
+      result.issues.forEach(issue => {
+        const levelColor = issue.severity === 'critical' ? chalk.red : 
+                          issue.severity === 'warning' ? chalk.yellow : chalk.blue;
+        output += `  ${levelColor(`[${issue.severity.toUpperCase()}]`)} ${issue.message}\n`;
+      });
+    }
+  });
+
+  return output;
+}

package/lib/formatter.js

@@ -0,0 +1,103 @@
+let chalk;
+try {
+  chalk = require('chalk').default || require('chalk');
+} catch (e) {
+  chalk = require('chalk');
+}
+
+function formatTerminalReport(report) {
+  let output = '';
+
+  // Header
+  output += '\n' + chalk.bold.cyan('📋 Skill Validator Report\n');
+  output += chalk.gray('═'.repeat(60)) + '\n\n';
+
+  // File info
+  output += chalk.gray(`File: ${report.filepath}\n`);
+
+  // Status badge
+  const statusIcon = report.passed ? chalk.green('✓ PASSED') : chalk.red('✗ FAILED');
+  output += `Status: ${statusIcon}\n\n`;
+
+  // Summary stats
+  output += chalk.bold('Summary:\n');
+  output += `  Total Issues:     ${report.issueCount}\n`;
+  output += `  ${chalk.red('Critical:')}      ${report.criticalCount}\n`;
+  output += `  ${chalk.yellow('Warnings:')}      ${report.warningCount}\n`;
+  output += `  ${chalk.blue('Info:')}           ${report.infoCount}\n\n`;
+
+  // Issues grouped by category
+  if (report.issues.length > 0) {
+    output += chalk.bold('Issues:\n');
+    output += chalk.gray('─'.repeat(60)) + '\n\n';
+
+    const grouped = {
+      security: [],
+      documentation: [],
+      bestPractices: []
+    };
+
+    report.issues.forEach(issue => {
+      if (grouped[issue.type]) {
+        grouped[issue.type].push(issue);
+      }
+    });
+
+    // Security issues
+    if (grouped.security.length > 0) {
+      output += chalk.bold.red('🔒 Security Issues:\n');
+      grouped.security.forEach((issue, idx) => {
+        const severityBadge = getSeverityBadge(issue.severity);
+        output += `  ${idx + 1}. ${severityBadge} ${issue.message}\n`;
+        if (issue.context) {
+          output += chalk.gray(`     Context: "${issue.context}"\n`);
+        }
+      });
+      output += '\n';
+    }
+
+    // Documentation issues
+    if (grouped.documentation.length > 0) {
+      output += chalk.bold.yellow('📚 Documentation Issues:\n');
+      grouped.documentation.forEach((issue, idx) => {
+        const severityBadge = getSeverityBadge(issue.severity);
+        output += `  ${idx + 1}. ${severityBadge} ${issue.message}\n`;
+      });
+      output += '\n';
+    }
+
+    // Best practices issues
+    if (grouped.bestPractices.length > 0) {
+      output += chalk.bold.cyan('💡 Best Practices:\n');
+      grouped.bestPractices.forEach((issue, idx) => {
+        const severityBadge = getSeverityBadge(issue.severity);
+        output += `  ${idx + 1}. ${severityBadge} ${issue.message}\n`;
+      });
+      output += '\n';
+    }
+  } else {
+    output += chalk.green.bold('✨ No issues found! Your skill is well documented.\n\n');
+  }
+
+  output += chalk.gray('═'.repeat(60)) + '\n';
+
+  return output;
+}
+
+function formatJsonReport(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+function getSeverityBadge(severity) {
+  const badges = {
+    critical: chalk.red('🔴 CRITICAL'),
+    warning: chalk.yellow('🟡 WARNING'),
+    info: chalk.blue('🔵 INFO')
+  };
+  return badges[severity] || chalk.gray('○');
+}
+
+module.exports = {
+  formatTerminalReport,
+  formatJsonReport
+};

package/lib/validator.js

@@ -0,0 +1,253 @@
+/**
+ * SkillValidator - Validates OpenClaw skill.md files
+ */
+
+class SkillValidator {
+  constructor() {
+    this.rules = {
+      security: this.getSecurityRules(),
+      documentation: this.getDocumentationRules(),
+      bestPractices: this.getBestPracticesRules()
+    };
+  }
+
+  validate(content, filepath = 'skill.md') {
+    const issues = [];
+    const checks = {
+      securityIssues: this.checkSecurity(content),
+      documentationIssues: this.checkDocumentation(content),
+      bestPracticesIssues: this.checkBestPractices(content)
+    };
+
+    issues.push(...checks.securityIssues);
+    issues.push(...checks.documentationIssues);
+    issues.push(...checks.bestPracticesIssues);
+
+    return {
+      filepath,
+      passed: issues.filter(i => i.severity === 'critical').length === 0,
+      issueCount: issues.length,
+      criticalCount: issues.filter(i => i.severity === 'critical').length,
+      warningCount: issues.filter(i => i.severity === 'warning').length,
+      infoCount: issues.filter(i => i.severity === 'info').length,
+      issues: issues.sort((a, b) => {
+        const severityOrder = { critical: 0, warning: 1, info: 2 };
+        return severityOrder[a.severity] - severityOrder[b.severity];
+      })
+    };
+  }
+
+  checkSecurity(content) {
+    const issues = [];
+    const securityPatterns = [
+      {
+        pattern: /password\s*[=:]\s*['"]/gi,
+        message: 'Potential hardcoded password detected',
+        severity: 'critical'
+      },
+      {
+        pattern: /api[_-]?key\s*[=:]\s*['"]/gi,
+        message: 'Potential hardcoded API key detected',
+        severity: 'critical'
+      },
+      {
+        pattern: /secret\s*[=:]\s*['"]/gi,
+        message: 'Potential hardcoded secret detected',
+        severity: 'critical'
+      },
+      {
+        pattern: /token\s*[=:]\s*['"]/gi,
+        message: 'Potential hardcoded token detected',
+        severity: 'critical'
+      },
+      {
+        pattern: /Bearer\s+[A-Za-z0-9_\-\.]+/g,
+        message: 'Potential hardcoded bearer token in example code',
+        severity: 'critical'
+      },
+      {
+        pattern: /eval\s*\(/gi,
+        message: 'Use of eval() is dangerous and should be avoided',
+        severity: 'critical'
+      },
+      {
+        pattern: /exec\s*\(/gi,
+        message: 'Use of exec() without proper sanitization is dangerous',
+        severity: 'warning'
+      },
+      {
+        pattern: /child_process.*exec/gi,
+        message: 'Shell execution without input validation detected',
+        severity: 'warning'
+      },
+      {
+        pattern: /http:\/\//gi,
+        message: 'Unencrypted HTTP URL detected - should use HTTPS',
+        severity: 'warning'
+      }
+    ];
+
+    securityPatterns.forEach(rule => {
+      let match;
+      const regex = new RegExp(rule.pattern);
+      while ((match = regex.exec(content)) !== null) {
+        issues.push({
+          type: 'security',
+          severity: rule.severity,
+          message: rule.message,
+          context: match[0]
+        });
+      }
+    });
+
+    return issues;
+  }
+
+  checkDocumentation(content) {
+    const issues = [];
+
+    // Check for required sections
+    const requiredSections = [
+      { name: 'Overview', patterns: [/^#+\s+Overview/m, /^#+\s+Description/m] },
+      { name: 'Parameters/Arguments', patterns: [/^#+\s+(Parameters|Arguments|Inputs)/m] },
+      { name: 'Returns/Output', patterns: [/^#+\s+(Returns|Output|Outputs)/m] },
+      { name: 'Examples', patterns: [/^#+\s+Examples?/m, /```/m] },
+      { name: 'Error Handling', patterns: [/^#+\s+(Error|Errors|Exception)/m] }
+    ];
+
+    requiredSections.forEach(section => {
+      const found = section.patterns.some(pattern => pattern.test(content));
+      if (!found) {
+        issues.push({
+          type: 'documentation',
+          severity: 'warning',
+          message: `Missing or unclear "${section.name}" section`
+        });
+      }
+    });
+
+    // Check for code examples
+    const codeBlockCount = (content.match(/```/g) || []).length / 2;
+    if (codeBlockCount === 0) {
+      issues.push({
+        type: 'documentation',
+        severity: 'warning',
+        message: 'No code examples found - at least one example is recommended'
+      });
+    }
+
+    // Check if file is too short (likely incomplete)
+    const lines = content.split('\n').length;
+    if (lines < 10) {
+      issues.push({
+        type: 'documentation',
+        severity: 'info',
+        message: 'Documentation appears very brief - consider adding more detail'
+      });
+    }
+
+    // Check for front matter or metadata
+    if (!content.startsWith('---') && !content.startsWith('#')) {
+      issues.push({
+        type: 'documentation',
+        severity: 'info',
+        message: 'Consider adding YAML front matter for metadata'
+      });
+    }
+
+    return issues;
+  }
+
+  checkBestPractices(content) {
+    const issues = [];
+
+    // Check for error handling
+    if (!/(try|catch|error|Error|exception|throw|throws)/m.test(content)) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'warning',
+        message: 'No error handling documentation or examples found'
+      });
+    }
+
+    // Check for permission/auth documentation
+    if (!/(permission|auth|authentication|authorize|access|role)/mi.test(content)) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'warning',
+        message: 'Missing documentation on permissions or authentication requirements'
+      });
+    }
+
+    // Check for usage/warning notes
+    if (!/⚠️|warning|caution|important|note/mi.test(content)) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'info',
+        message: 'Consider adding usage warnings or important notes'
+      });
+    }
+
+    // Check for validation documentation
+    if (!/validat|check|sanitiz|sanitize/mi.test(content)) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'info',
+        message: 'Consider documenting input validation'
+      });
+    }
+
+    // Check for proper code block language specification
+    const unspecifiedBlocks = (content.match(/```\n/g) || []).length;
+    if (unspecifiedBlocks > 0) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'info',
+        message: `Found ${unspecifiedBlocks} code blocks without language specification`
+      });
+    }
+
+    // Check for links to documentation
+    const linkCount = (content.match(/\[.*?\]\(.*?\)/g) || []).length;
+    if (linkCount === 0) {
+      issues.push({
+        type: 'bestPractices',
+        severity: 'info',
+        message: 'No external documentation links found'
+      });
+    }
+
+    return issues;
+  }
+
+  getSecurityRules() {
+    return [
+      'No hardcoded credentials',
+      'No dangerous functions (eval, exec without validation)',
+      'HTTPS URLs preferred',
+      'Input validation documented'
+    ];
+  }
+
+  getDocumentationRules() {
+    return [
+      'Overview/Description section',
+      'Parameters/Arguments documented',
+      'Returns/Output documented',
+      'Examples provided',
+      'Error handling documented'
+    ];
+  }
+
+  getBestPracticesRules() {
+    return [
+      'Error handling examples',
+      'Permission/auth requirements documented',
+      'Input validation documented',
+      'Usage warnings included',
+      'Code blocks have language specified'
+    ];
+  }
+}
+
+module.exports = { SkillValidator };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "skill-validator",
+  "version": "1.0.0",
+  "description": "Validate OpenClaw skill.md files for security, documentation, and best practices",
+  "main": "lib/validator.js",
+  "bin": {
+    "skill-validator": "bin/skill-validator.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "validate": "node bin/skill-validator.js validate",
+    "scan": "node bin/skill-validator.js scan",
+    "lint": "eslint lib tests",
+    "prepublishOnly": "npm test && npm run lint"
+  },
+  "keywords": [
+    "openclaw",
+    "skill",
+    "validator",
+    "security",
+    "documentation",
+    "cli"
+  ],
+  "author": "Bagalobsta <bagalobsta@protonmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bagalobsta/skill-validator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bagalobsta/skill-validator/issues"
+  },
+  "homepage": "https://github.com/bagalobsta/skill-validator#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ],
+    "collectCoverageFrom": [
+      "lib/**/*.js"
+    ]
+  }
+}