skill-validator 1.0.0

package/API.md

@@ -0,0 +1,387 @@
+# API Documentation
+
+## Using Skill Validator as a Library
+
+You can use skill-validator programmatically in your Node.js applications.
+
+## Installation
+
+```bash
+npm install skill-validator
+```
+
+## SkillValidator Class
+
+### Constructor
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+
+const validator = new SkillValidator();
+```
+
+### Methods
+
+#### `validate(content, filepath?)`
+
+Validates skill.md content and returns a detailed report.
+
+**Parameters:**
+- `content` (string, required) - The skill.md file content to validate
+- `filepath` (string, optional) - File path for identification in report (defaults to 'skill.md')
+
+**Returns:** Report object (see Report Structure below)
+
+**Example:**
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+const fs = require('fs');
+
+const validator = new SkillValidator();
+const skillContent = fs.readFileSync('my-skill.md', 'utf-8');
+
+const report = validator.validate(skillContent, 'skills/my-skill.md');
+
+console.log(`Validation: ${report.passed ? 'PASSED' : 'FAILED'}`);
+console.log(`Issues found: ${report.issueCount}`);
+```
+
+## Report Structure
+
+The validate method returns an object with this structure:
+
+```javascript
+{
+  // File identification
+  filepath: string,           // Path provided to validate()
+
+  // Overall status
+  passed: boolean,            // true if no critical issues
+  issueCount: number,         // Total number of issues
+  criticalCount: number,      // Number of critical issues
+  warningCount: number,       // Number of warnings
+  infoCount: number,          // Number of info messages
+
+  // Detailed issues
+  issues: Issue[]             // Array of Issue objects
+}
+```
+
+### Issue Object
+
+```javascript
+{
+  type: 'security' | 'documentation' | 'bestPractices',
+  severity: 'critical' | 'warning' | 'info',
+  message: string,            // Human-readable message
+  context?: string            // Code snippet or context (for security issues)
+}
+```
+
+## Validation Rules
+
+### Security Issues
+
+Detects:
+- Hardcoded passwords, API keys, tokens, secrets
+- Dangerous functions (eval, exec without validation)
+- Unencrypted HTTP URLs
+- Bearer token patterns
+
+**Severity:** Mostly `critical`, some `warning`
+
+### Documentation Issues
+
+Checks for required sections:
+- Overview/Description
+- Parameters/Arguments
+- Returns/Output
+- Examples
+- Error Handling
+
+**Severity:** `warning`
+
+### Best Practices Issues
+
+Validates:
+- Error handling documentation
+- Permission/authentication documentation
+- Input validation documentation
+- Usage warnings
+- Code block language specification
+
+**Severity:** `warning` and `info`
+
+## Complete Example
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+const fs = require('fs');
+const path = require('path');
+
+function validateSkills(directory) {
+  const validator = new SkillValidator();
+  const results = [];
+
+  // Recursive directory walk
+  function 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);
+      }
+    });
+  }
+
+  walkDir(directory);
+
+  // Generate summary
+  const summary = {
+    total: results.length,
+    passed: results.filter(r => r.passed).length,
+    failed: results.filter(r => !r.passed).length,
+    criticalIssues: results.reduce((sum, r) => sum + r.criticalCount, 0),
+    details: results
+  };
+
+  return summary;
+}
+
+// Usage
+const report = validateSkills('./skills');
+console.log(JSON.stringify(report, null, 2));
+
+// Filter for critical issues only
+const critical = report.details
+  .filter(r => r.criticalCount > 0)
+  .map(r => ({ file: r.filepath, issues: r.issues.filter(i => i.severity === 'critical') }));
+
+console.log('Critical Issues:', critical);
+```
+
+## Integration Examples
+
+### Express.js Middleware
+
+```javascript
+const express = require('express');
+const { SkillValidator } = require('skill-validator');
+
+const app = express();
+const validator = new SkillValidator();
+
+app.post('/validate-skill', express.text({ type: 'text/markdown' }), (req, res) => {
+  try {
+    const report = validator.validate(req.body);
+    res.json({
+      success: report.passed,
+      report: report
+    });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.listen(3000);
+```
+
+### CI/CD Integration
+
+```javascript
+// scripts/validate-skills.js
+const { SkillValidator } = require('skill-validator');
+const fs = require('fs');
+
+const validator = new SkillValidator();
+let exitCode = 0;
+
+// Validate all skills
+const files = fs.readdirSync('./skills').filter(f => f.endsWith('.md'));
+
+files.forEach(file => {
+  const content = fs.readFileSync(`./skills/${file}`, 'utf-8');
+  const report = validator.validate(content, file);
+
+  if (!report.passed) {
+    console.error(`❌ ${file}: ${report.criticalCount} critical issues`);
+    exitCode = 1;
+  } else {
+    console.log(`✅ ${file}: OK`);
+  }
+});
+
+process.exit(exitCode);
+```
+
+Use in `package.json`:
+```json
+{
+  "scripts": {
+    "validate-skills": "node scripts/validate-skills.js"
+  }
+}
+```
+
+### Test Suite
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+
+describe('Skill Validation', () => {
+  const validator = new SkillValidator();
+
+  test('should pass well-documented skill', () => {
+    const content = `
+# Overview
+Complete documentation
+
+## Parameters
+- input: string
+
+## Returns
+- output: string
+
+## Examples
+\`\`\`javascript
+const result = await skill();
+\`\`\`
+
+## Error Handling
+Errors are caught.
+
+## Permissions
+No special permissions needed.
+    `;
+
+    const report = validator.validate(content);
+    expect(report.passed).toBe(true);
+    expect(report.criticalCount).toBe(0);
+  });
+
+  test('should detect security issues', () => {
+    const content = `
+# Skill
+password = "secret123"
+    `;
+
+    const report = validator.validate(content);
+    expect(report.passed).toBe(false);
+    expect(report.criticalCount).toBeGreaterThan(0);
+  });
+});
+```
+
+## Error Handling
+
+The `validate()` method doesn't throw errors - it captures them in the report:
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+
+try {
+  const validator = new SkillValidator();
+  const report = validator.validate(null); // Invalid input
+  
+  if (!report.passed) {
+    console.log('Validation failed:');
+    console.log(report.issues);
+  }
+} catch (error) {
+  console.error('Unexpected error:', error);
+}
+```
+
+## Performance
+
+The validator is optimized for:
+- **Single file validation:** <5ms
+- **Typical skill.md:** <1ms
+- **Large directory scan:** <100ms for 100 files
+
+No external API calls or network overhead.
+
+## Advanced Usage
+
+### Custom Rule Implementation
+
+Create extensions by subclassing:
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+
+class CustomValidator extends SkillValidator {
+  checkCustomRules(content) {
+    const issues = [];
+    
+    // Add your custom validation logic
+    if (!content.includes('License')) {
+      issues.push({
+        type: 'documentation',
+        severity: 'info',
+        message: 'Missing License section'
+      });
+    }
+    
+    return issues;
+  }
+
+  validate(content, filepath) {
+    const baseReport = super.validate(content, filepath);
+    const customIssues = this.checkCustomRules(content);
+    
+    baseReport.issues.push(...customIssues);
+    baseReport.issueCount = baseReport.issues.length;
+    
+    return baseReport;
+  }
+}
+
+const validator = new CustomValidator();
+const report = validator.validate(skillContent);
+```
+
+## Troubleshooting
+
+### Invalid input types
+
+```javascript
+// ❌ Wrong
+validator.validate(123);           // String expected
+validator.validate(Buffer.from()); // String expected
+
+// ✅ Correct
+validator.validate('# Skill\nContent');
+validator.validate(fs.readFileSync('skill.md', 'utf-8'));
+```
+
+### Always check the report
+
+```javascript
+const report = validator.validate(content);
+
+// Check if validation passed
+if (report.passed) {
+  console.log('✅ Ready for production');
+} else {
+  // Handle critical issues
+  const critical = report.issues.filter(i => i.severity === 'critical');
+  console.error('❌ Fix these issues:', critical);
+}
+```
+
+## License
+
+skill-validator is MIT licensed. Use freely in your applications.
+
+---
+
+For CLI usage, see [README.md](./README.md)

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-01-01
+
+### Added
+- Initial release of skill-validator CLI tool
+- Security checks for hardcoded credentials, dangerous functions, and unencrypted URLs
+- Documentation validation for required sections (Overview, Parameters, Returns, Examples, Error Handling)
+- Best practices validation for error handling, permissions, input validation, and code blocks
+- Support for single file validation with `validate` command
+- Support for directory scanning with `scan` command
+- Colorized terminal reports with severity levels
+- JSON output format for automation and tooling
+- Comprehensive test suite with 17 passing tests
+- Full API documentation for programmatic usage
+- Example skills (good and bad) for testing
+- MIT License
+- GitHub Actions CI/CD setup
+- npm package publication support
+
+### Features
+- Fast validation (<5ms per file)
+- Zero external dependencies
+- Exit code support for CI/CD pipelines
+- File output support for reports
+- Recursive directory scanning
+- Comprehensive validation rule set
+
+## Future Releases
+
+### [1.1.0] (Planned)
+- Config file support (.skillvalidatorrc)
+- Custom rule definitions
+- HTML report generation
+- Integration with skill templates
+- Performance benchmarks
+
+### [2.0.0] (Planned)
+- VS Code extension
+- GitHub Action for CI/CD
+- Extended test coverage
+- Support for YAML/JSON skill formats
+- Advanced security scanning rules
+- Custom validation rule marketplace
+
+---
+
+## Version History
+
+| Version | Release Date | Status |
+|---------|------------|--------|
+| 1.0.0 | 2024-01-01 | Released |
+
+## Support
+
+For issues and feature requests, visit:
+https://github.com/bagalobsta/skill-validator/issues

package/DEPLOYMENT.md

@@ -0,0 +1,238 @@
+# 🚀 Deployment & Quick Start
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+npm install -g skill-validator
+```
+
+### From source
+
+```bash
+git clone https://github.com/bagalobsta/skill-validator.git
+cd skill-validator
+npm install
+npm run validate examples/good-skill.md
+```
+
+## Quick Start
+
+### Validate a Single File
+
+```bash
+skill-validator validate my-skill.md
+```
+
+**Example Output:**
+```
+📋 Skill Validator Report
+════════════════════════════════════════════════════
+
+File: my-skill.md
+Status: ✓ PASSED
+
+Summary:
+  Total Issues:     0
+  Critical:      0
+  Warnings:      0
+  Info:           0
+
+✨ No issues found! Your skill is well documented.
+
+════════════════════════════════════════════════════
+```
+
+### Scan a Directory
+
+```bash
+skill-validator scan ./skills/
+```
+
+### Get JSON Output
+
+```bash
+skill-validator validate my-skill.md --json
+```
+
+### Save Report to File
+
+```bash
+skill-validator validate my-skill.md --output report.txt
+skill-validator validate my-skill.md --json --output report.json
+```
+
+## GitHub Actions Integration
+
+Add to `.github/workflows/validate-skills.yml`:
+
+```yaml
+name: Validate Skills
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - run: npm install -g skill-validator
+      
+      - run: skill-validator scan ./skills/
+      
+      - run: skill-validator scan ./skills/ --json --output report.json
+      
+      - uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: validation-report
+          path: report.json
+```
+
+## Docker
+
+Create a `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+RUN npm install -g skill-validator
+COPY . .
+CMD ["skill-validator", "scan", "."]
+```
+
+Build and run:
+
+```bash
+docker build -t skill-validator .
+docker run skill-validator
+```
+
+## Pre-commit Hook
+
+Create `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/bash
+skill-validator scan . || {
+    echo "❌ Skill validation failed. Fix issues before committing."
+    exit 1
+}
+```
+
+Make it executable:
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+## CI/CD Pipeline Examples
+
+### GitLab CI
+
+```yaml
+validate-skills:
+  image: node:18
+  script:
+    - npm install -g skill-validator
+    - skill-validator scan ./skills/ --json --output report.json
+  artifacts:
+    paths:
+      - report.json
+```
+
+### Jenkins
+
+```groovy
+stage('Validate Skills') {
+    steps {
+        sh 'npm install -g skill-validator'
+        sh 'skill-validator scan ./skills/'
+    }
+}
+```
+
+## Programmatic Usage
+
+See [API.md](./API.md) for detailed examples.
+
+Quick example:
+
+```javascript
+const { SkillValidator } = require('skill-validator');
+const fs = require('fs');
+
+const validator = new SkillValidator();
+const content = fs.readFileSync('skill.md', 'utf-8');
+const report = validator.validate(content);
+
+if (report.passed) {
+  console.log('✅ Skill is valid');
+} else {
+  console.log(`❌ Found ${report.issueCount} issues`);
+  report.issues.forEach(issue => {
+    console.log(`  [${issue.severity}] ${issue.message}`);
+  });
+}
+```
+
+## Exit Codes
+
+- `0` - Validation passed (no critical issues)
+- `1` - Validation failed (critical issues found)
+
+Perfect for CI/CD:
+
+```bash
+skill-validator validate skill.md && echo "✅ Ready!" || echo "❌ Fix issues"
+```
+
+## Troubleshooting
+
+### Command not found
+
+```bash
+# Install globally
+npm install -g skill-validator
+
+# Or use with npx
+npx skill-validator --version
+```
+
+### Permission denied
+
+```bash
+# Update npm permissions
+npm install -g --unsafe-perm skill-validator
+```
+
+### Update to latest version
+
+```bash
+npm install -g skill-validator@latest
+```
+
+## Support
+
+- 📖 [GitHub Repo](https://github.com/bagalobsta/skill-validator)
+- 🐛 [Report Issues](https://github.com/bagalobsta/skill-validator/issues)
+- 💬 [Discussions](https://github.com/bagalobsta/skill-validator/discussions)
+- 📧 [Email Support](mailto:bagalobsta@protonmail.com)
+
+## Next Steps
+
+1. ✅ Install skill-validator
+2. ✅ Validate your skills
+3. ✅ Fix any issues found
+4. ✅ Integrate into CI/CD
+5. ✅ Share with your team
+
+---
+
+Ready to ship! 🚀

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bagalobsta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.