skill-validator 1.0.0

package/PUBLISHING.md

@@ -0,0 +1,313 @@
+# Publishing Guide
+
+This document explains how to publish **skill-validator** to npm and prepare it for sale on Gumroad.
+
+## Prerequisites
+
+1. npm account at https://www.npmjs.com/signup
+2. Verified email address on npm
+3. Two-factor authentication enabled (recommended)
+4. GitHub account with repo access
+
+## Step 1: Create npm Account
+
+If you don't have an npm account:
+
+```bash
+npm adduser
+```
+
+You'll be prompted for:
+- Username: `bagalobsta`
+- Password: (your npm password)
+- Email: (your email address)
+
+Verify your email address at https://www.npmjs.com.
+
+## Step 2: Prepare for Publication
+
+### Update Version Number
+
+Before publishing, update the version in `package.json`:
+
+```json
+{
+  "version": "1.0.0"
+}
+```
+
+For updates, use semantic versioning:
+- `1.0.1` - Patch (bug fixes)
+- `1.1.0` - Minor (new features)
+- `2.0.0` - Major (breaking changes)
+
+### Run Quality Checks
+
+```bash
+npm test          # Run all tests
+npm run lint      # Run linter (if configured)
+```
+
+### Create GitHub Release
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+gh release create v1.0.0 --generate-notes
+```
+
+## Step 3: Publish to npm
+
+### First Time Publishing
+
+```bash
+npm publish
+```
+
+This publishes the package publicly at https://www.npmjs.com/package/skill-validator
+
+### Publishing Updates
+
+```bash
+# Update version in package.json
+npm version patch  # 1.0.1
+
+# Publish update
+npm publish
+
+# Push to GitHub
+git push origin main
+git push origin --tags
+```
+
+## Step 4: Verify Publication
+
+Check that the package is published:
+
+```bash
+npm info skill-validator
+npm view skill-validator
+```
+
+Install it globally to test:
+
+```bash
+npm install -g skill-validator@latest
+skill-validator --version
+```
+
+## Step 5: Selling on Gumroad
+
+### Create Gumroad Product
+
+1. Go to https://gumroad.com
+2. Sign in to your account
+3. Click "Upload Product"
+
+### Product Details
+
+**Title:** `Skill Validator CLI - OpenClaw Skill Documentation Validator`
+
+**Description:**
+```
+Professional CLI tool for validating OpenClaw skill.md files.
+
+✅ Security audit - detects hardcoded credentials and dangerous patterns
+✅ Documentation checks - ensures complete documentation
+✅ Best practices validation - error handling, permissions, input validation
+✅ JSON & terminal output - for automation and readability
+
+Perfect for:
+- OpenClaw developers validating skills
+- Teams ensuring code quality
+- CI/CD automation pipelines
+- Documentation enforcement
+
+Features:
+- Fast single file or directory scanning
+- Colorized terminal reports with severity levels
+- JSON export for parsing and tooling
+- 17 comprehensive validation rules
+- Zero dependencies (just Node.js)
+
+Install: npm install -g skill-validator
+```
+
+**Product Type:** Software
+
+**Price Options:**
+- Free version: Offer on npm (free)
+- Premium version: Sell on Gumroad (€9-15)
+
+**Consider for Premium:**
+- Advanced security scanning rules
+- Custom validation rules
+- Report generation (HTML/PDF)
+- Integration helpers
+
+### Gumroad License Key
+
+If you want to add a license key mechanism for premium features:
+
+```javascript
+// lib/validator.js - add premium features
+class PremiumSkillValidator extends SkillValidator {
+  validateLicense(key) {
+    // License validation logic
+  }
+}
+```
+
+### Files to Provide
+
+Upload to Gumroad:
+1. `skill-validator-1.0.0.tar.gz` (packaged source)
+2. `INSTALL.md` - Setup instructions
+3. `EXAMPLES.pdf` - Usage examples and screenshots
+
+```bash
+# Create distribution
+cd /tmp/skill-validator
+tar -czf skill-validator-1.0.0.tar.gz \
+  --exclude=.git \
+  --exclude=node_modules \
+  --exclude=.env \
+  .
+```
+
+### Distribution License
+
+Add a note about the open source license:
+
+```
+This tool is published on npm under the MIT License and can be freely used.
+This premium package includes additional features, examples, and support.
+```
+
+## Step 6: Marketing
+
+### npm Package Page
+
+Your npm page is automatically created and will show:
+- Installation instructions
+- README
+- Version history
+- Download stats
+
+Make it stand out by:
+- Adding quality metadata
+- Writing clear README
+- Including examples
+- Maintaining regular updates
+
+### Gumroad Benefits
+
+Selling on Gumroad provides:
+- Premium content (advanced rules, extensions)
+- Direct customer support channel
+- Email marketing to customers
+- License key management
+- Revenue tracking
+
+### Promotion Ideas
+
+1. **Blog Post**: "How to Validate OpenClaw Skills"
+2. **GitHub Discussions**: Announce release
+3. **Twitter/Social**: "New tool for skill validation"
+4. **Communities**: Share in OpenClaw forums
+5. **Documentation**: Link from your portfolio
+
+## Step 7: Maintenance
+
+### Version Updates
+
+When releasing new versions:
+
+```bash
+# Make changes
+git add -A
+git commit -m "feat: add new validation rules"
+
+# Bump version
+npm version minor
+
+# Publish
+npm publish
+
+# Push to GitHub
+git push origin main --tags
+```
+
+### Keep npm Fresh
+
+- Fix issues promptly
+- Update dependencies monthly
+- Add new validation rules
+- Improve documentation
+
+## npm Dashboard
+
+Monitor your package at:
+- https://www.npmjs.com/package/skill-validator
+- https://www.npmjs.com/settings/bagalobsta/packages
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Re-authenticate
+npm logout
+npm adduser
+
+# Check auth
+npm whoami
+cat ~/.npmrc
+```
+
+### Publishing Fails
+
+```bash
+# Check package name isn't taken
+npm view skill-validator
+
+# Verify version isn't already published
+npm view skill-validator versions
+
+# Run prepublish checks
+npm run prepublishOnly
+```
+
+### Update npm
+
+```bash
+npm install -g npm@latest
+```
+
+## Success Checklist
+
+- [ ] npm account created and verified
+- [ ] GitHub repo public
+- [ ] All tests passing
+- [ ] Version bumped
+- [ ] Published to npm
+- [ ] Package installable globally
+- [ ] Gumroad account created
+- [ ] Premium features added (if applicable)
+- [ ] Product listed on Gumroad
+- [ ] GitHub releases created
+- [ ] Social media announced
+- [ ] Documentation complete
+
+## Support & Feedback
+
+After publishing:
+- Monitor npm page for issues
+- Respond to GitHub issues
+- Track Gumroad customer feedback
+- Keep dependencies updated
+- Plan feature releases quarterly
+
+---
+
+Good luck! 🚀

package/README.md

@@ -0,0 +1,375 @@
+# 🔍 Skill Validator
+
+A powerful CLI tool for validating OpenClaw `skill.md` files. Automatically checks for **security issues**, **missing documentation**, and **best practices**.
+
+```
+$ skill-validator validate examples/good-skill.md
+
+📋 Skill Validator Report
+════════════════════════════════════════════════════
+
+File: examples/good-skill.md
+Status: ✓ PASSED
+
+Summary:
+  Total Issues:     0
+  🔴 Critical:      0
+  🟡 Warnings:      0
+  🔵 Info:          0
+
+✨ No issues found! Your skill is well documented.
+
+════════════════════════════════════════════════════
+```
+
+## Features
+
+✅ **Security Checks**
+- Detects hardcoded passwords, API keys, tokens, and secrets
+- Flags dangerous functions (eval, exec)
+- Warns about unencrypted HTTP URLs
+- Identifies credential exposure patterns
+
+✅ **Documentation Validation**
+- Ensures required sections (Overview, Parameters, Returns, Examples, Error Handling)
+- Checks for code examples
+- Validates completeness
+
+✅ **Best Practices**
+- Error handling documentation
+- Permission/authentication requirements
+- Input validation guidance
+- Usage warnings and notes
+- Properly specified code blocks
+
+✅ **Multiple Output Formats**
+- Colorized terminal reports
+- JSON for automation
+- File export support
+
+## Installation
+
+```bash
+npm install -g skill-validator
+```
+
+Or use directly:
+
+```bash
+npx skill-validator@latest validate skill.md
+```
+
+## Usage
+
+### Validate a Single File
+
+```bash
+skill-validator validate path/to/skill.md
+```
+
+**Options:**
+- `-j, --json` - Output as JSON instead of formatted report
+- `-o, --output <file>` - Write report to file
+
+**Examples:**
+
+```bash
+# Terminal report
+skill-validator validate my-skill.md
+
+# JSON output
+skill-validator validate my-skill.md --json
+
+# Save to file
+skill-validator validate my-skill.md --output report.txt
+```
+
+### Scan a Directory
+
+```bash
+skill-validator scan path/to/skills/
+```
+
+Recursively scans all `skill.md` files in a directory.
+
+**Options:**
+- `-j, --json` - Output as JSON summary
+- `-o, --output <file>` - Write report to file
+
+**Examples:**
+
+```bash
+# Scan all skills
+skill-validator scan ./skills/
+
+# JSON summary
+skill-validator scan ./skills/ --json
+
+# Export scan results
+skill-validator scan ./skills/ --output scan-report.json --json
+```
+
+## Output Examples
+
+### Terminal Report
+
+```
+📋 Skill Validator Report
+════════════════════════════════════════════════════
+
+File: my-skill.md
+Status: ✗ FAILED
+
+Summary:
+  Total Issues:     3
+  🔴 Critical:      1
+  🟡 Warnings:      2
+  🔵 Info:          0
+
+Issues:
+════════════════════════════════════════════════════
+
+🔒 Security Issues:
+  1. 🔴 CRITICAL Potential hardcoded password detected
+     Context: "password = "secret123""
+
+📚 Documentation Issues:
+  1. 🟡 WARNING Missing or unclear "Error Handling" section
+  2. 🟡 WARNING Missing or unclear "Parameters" section
+
+════════════════════════════════════════════════════
+```
+
+### JSON Output
+
+```json
+{
+  "filepath": "my-skill.md",
+  "passed": false,
+  "issueCount": 3,
+  "criticalCount": 1,
+  "warningCount": 2,
+  "infoCount": 0,
+  "issues": [
+    {
+      "type": "security",
+      "severity": "critical",
+      "message": "Potential hardcoded password detected",
+      "context": "password = \"secret123\""
+    },
+    {
+      "type": "documentation",
+      "severity": "warning",
+      "message": "Missing or unclear \"Error Handling\" section"
+    },
+    {
+      "type": "documentation",
+      "severity": "warning",
+      "message": "Missing or unclear \"Parameters\" section"
+    }
+  ]
+}
+```
+
+## Rules & Validation Checks
+
+### 🔒 Security Rules
+
+| Issue | Severity | Description |
+|-------|----------|-------------|
+| Hardcoded Password | 🔴 Critical | `password = "..."` patterns |
+| Hardcoded API Key | 🔴 Critical | `api_key = "..."`, `apiKey = "..."` |
+| Hardcoded Secret | 🔴 Critical | `secret = "..."` patterns |
+| Hardcoded Token | 🔴 Critical | Bearer tokens, auth tokens |
+| eval() Usage | 🔴 Critical | Dynamic code execution |
+| exec() Without Validation | 🟡 Warning | Shell command execution |
+| HTTP URLs | 🟡 Warning | Unencrypted connections |
+
+### 📚 Documentation Rules
+
+| Issue | Severity |
+|-------|----------|
+| Missing Overview section | 🟡 Warning |
+| Missing Parameters section | 🟡 Warning |
+| Missing Returns/Output section | 🟡 Warning |
+| Missing Examples | 🟡 Warning |
+| Missing Error Handling section | 🟡 Warning |
+| No code examples (```...```) | 🟡 Warning |
+| Very short documentation (<10 lines) | 🔵 Info |
+| No YAML front matter | 🔵 Info |
+
+### 💡 Best Practices Rules
+
+| Issue | Severity |
+|--------|----------|
+| No error handling documentation | 🟡 Warning |
+| No permission/auth documentation | 🟡 Warning |
+| Code blocks without language | 🔵 Info |
+| No usage warnings/notes | 🔵 Info |
+| No input validation documentation | 🔵 Info |
+| No external documentation links | 🔵 Info |
+
+## Example Skills
+
+The `examples/` directory contains:
+
+- **good-skill.md** - A well-documented, secure skill (passes validation)
+- **bad-skill.md** - A poorly documented skill with security issues (fails validation)
+
+Try them:
+
+```bash
+skill-validator validate examples/good-skill.md
+skill-validator validate examples/bad-skill.md
+```
+
+## Exit Codes
+
+- **0** - Validation passed (no critical issues)
+- **1** - Validation failed (critical issues found) or error occurred
+
+Useful for CI/CD pipelines:
+
+```bash
+skill-validator validate my-skill.md && echo "✅ Ready for production" || echo "❌ Fix issues first"
+```
+
+## Integration with CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Validate Skills
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      - run: npm install -g skill-validator
+      - run: skill-validator scan ./skills/ --json --output report.json
+      - uses: actions/upload-artifact@v2
+        if: always()
+        with:
+          name: validation-report
+          path: report.json
+```
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+skill-validator scan . || exit 1
+```
+
+## API Usage
+
+Use skill-validator programmatically:
+
+```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, 'my-skill.md');
+
+console.log(`Issues found: ${report.issueCount}`);
+console.log(`Critical: ${report.criticalCount}`);
+console.log(`Passed: ${report.passed}`);
+
+// Get detailed issues
+report.issues.forEach(issue => {
+  console.log(`[${issue.type}] ${issue.message}`);
+});
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/bagalobsta/skill-validator.git
+cd skill-validator
+npm install
+```
+
+### Run Tests
+
+```bash
+npm test
+npm run test:watch  # Watch mode
+```
+
+### Test Coverage
+
+```bash
+npm test -- --coverage
+```
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Write tests for new features
+4. Run `npm test` to ensure all tests pass
+5. Submit a pull request
+
+## Project Structure
+
+```
+skill-validator/
+├── bin/
+│   └── skill-validator.js       # CLI entry point
+├── lib/
+│   ├── validator.js             # Core validation logic
+│   └── formatter.js             # Output formatting
+├── tests/
+│   └── validator.test.js        # Test suite
+├── examples/
+│   ├── good-skill.md            # Example: valid skill
+│   └── bad-skill.md             # Example: invalid skill
+├── README.md                    # This file
+├── package.json                 # Project metadata
+└── LICENSE                      # MIT License
+```
+
+## Roadmap
+
+- [ ] Config file support (.skillvalidatorrc)
+- [ ] Custom rule definitions
+- [ ] Integration with skill templates
+- [ ] VS Code extension
+- [ ] Performance benchmarks
+- [ ] Extended test coverage
+- [ ] Support for YAML/JSON skill formats
+
+## License
+
+MIT License © 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 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
+
+## Support
+
+- 📖 [Documentation](https://github.com/bagalobsta/skill-validator#readme)
+- 🐛 [Report Issues](https://github.com/bagalobsta/skill-validator/issues)
+- 💬 [Discussions](https://github.com/bagalobsta/skill-validator/discussions)
+- 🌐 [Website](https://bagalobsta.com)
+
+## Author
+
+**Bagalobsta** - [GitHub](https://github.com/bagalobsta) | [Email](mailto:bagalobsta@protonmail.com)
+
+---
+
+Built with ❤️ for OpenClaw developers