awesome-slash 2.4.3 → 2.5.0

package/plugins/ship/lib/platform/verify-tools.js

@@ -15,14 +15,19 @@ const { execFileSync, spawnSync, spawn } = require('child_process');
 // Detect Windows platform
 const isWindows = process.platform === 'win32';
 
+// Import shared deprecation utilities
+const { warnDeprecation, _resetDeprecationWarnings } = require('../utils/deprecation');
+
 /**
  * Checks if a tool is available and returns its version (sync)
  * Uses safe execution methods to avoid shell injection vulnerabilities
+ * @deprecated Use checkToolAsync() instead. Will be removed in v3.0.0.
  * @param {string} command - Command to check (e.g., 'git', 'node')
  * @param {string} versionFlag - Flag to get version (default: '--version')
  * @returns {Object} { available: boolean, version: string|null }
  */
 function checkTool(command, versionFlag = '--version') {
+  warnDeprecation('checkTool', 'checkToolAsync');
   // Validate command contains only safe characters (alphanumeric, underscore, hyphen)
   if (!/^[a-zA-Z0-9_-]+$/.test(command)) {
     return { available: false, version: null };
@@ -179,9 +184,11 @@ const TOOL_DEFINITIONS = [
 
 /**
  * Verifies all development tools (sync)
+ * @deprecated Use verifyToolsAsync() instead. Will be removed in v3.0.0.
  * @returns {Object} Tool availability map
  */
 function verifyTools() {
+  warnDeprecation('verifyTools', 'verifyToolsAsync');
   const result = {};
   for (const tool of TOOL_DEFINITIONS) {
     result[tool.name] = checkTool(tool.name, tool.flag);
@@ -231,5 +238,7 @@ module.exports = {
   verifyToolsAsync,
   checkTool,
   checkToolAsync,
-  TOOL_DEFINITIONS
+  TOOL_DEFINITIONS,
+  // Testing utilities (prefixed with _ to indicate internal use)
+  _resetDeprecationWarnings
 };

package/plugins/ship/lib/schemas/README.md

@@ -0,0 +1,195 @@
+# JSON Schema Definitions
+
+JSON Schema validation for plugin manifests and configuration files.
+
+## Overview
+
+This directory contains JSON Schema definitions and validators for:
+
+- **Plugin Manifest** (`plugin.json`) - Plugin metadata validation
+- Additional schemas can be added for other JSON config files
+
+## Files
+
+- `plugin-manifest.schema.json` - JSON Schema for plugin.json
+- `validator.js` - Schema validation utility
+- `README.md` - This file
+
+## Usage
+
+### Command Line
+
+Validate a plugin manifest:
+
+```bash
+# Validate default location
+node lib/schemas/validator.js
+
+# Validate specific file
+node lib/schemas/validator.js plugins/next-task/.claude-plugin/plugin.json
+
+# Output on success:
+# ✓ Manifest is valid
+#   Plugin: next-task v2.3.1
+#   Author: Avi Fenesh
+
+# Output on failure:
+# ✗ Manifest is invalid:
+#   - Missing required property: name
+#   - version: does not match pattern
+```
+
+### Programmatic Use
+
+```javascript
+const { validateManifestFile, SchemaValidator } = require('./lib/schemas/validator');
+
+// Validate a manifest file
+const result = validateManifestFile('.claude-plugin/plugin.json');
+if (result.valid) {
+  console.log('Valid!', result.manifest);
+} else {
+  console.error('Errors:', result.errors);
+}
+
+// Validate manifest object directly
+const manifest = {
+  name: "my-plugin",
+  version: "1.0.0",
+  description: "My awesome plugin",
+  author: { name: "John Doe" },
+  license: "MIT"
+};
+
+const validation = SchemaValidator.validatePluginManifest(manifest);
+if (!validation.valid) {
+  console.error(validation.errors);
+}
+```
+
+### Integration in Tests
+
+```javascript
+const { validateManifestFile } = require('./lib/schemas/validator');
+const path = require('path');
+
+describe('Plugin Manifest', () => {
+  it('should be valid', () => {
+    const result = validateManifestFile(
+      path.join(__dirname, '../.claude-plugin/plugin.json')
+    );
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should have required fields', () => {
+    const result = validateManifestFile(
+      path.join(__dirname, '../.claude-plugin/plugin.json')
+    );
+    expect(result.manifest.name).toBeTruthy();
+    expect(result.manifest.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});
+```
+
+## Schema Details
+
+### plugin-manifest.schema.json
+
+Validates `plugin.json` files with the following rules:
+
+**Required fields:**
+- `name` - Kebab-case identifier (e.g., "awesome-slash")
+- `version` - Semantic version (e.g., "1.0.0")
+- `description` - 10-500 characters
+- `author` - Object with `name` field
+- `license` - SPDX identifier (e.g., "MIT")
+
+**Optional fields:**
+- `homepage` - URL to plugin homepage
+- `repository` - URL to source repository
+- `keywords` - Array of search terms (1-20 items)
+- `minClaudeVersion` - Minimum required version
+- `dependencies` - Plugin dependencies
+- `config` - Plugin configuration
+
+**Constraints:**
+- `name` must be lowercase, kebab-case
+- `version` must follow semver (X.Y.Z)
+- `keywords` must be unique, 2-50 chars each
+- `author.email` must be valid email format
+- `author.url` must be valid URI format
+
+### Example Valid Manifest
+
+```json
+{
+  "name": "awesome-slash",
+  "version": "2.4.2",
+  "description": "Professional-grade slash commands for Claude Code",
+  "author": {
+    "name": "Avi Fenesh",
+    "email": "[email protected]",
+    "url": "https://github.com/avifenesh"
+  },
+  "homepage": "https://github.com/avifenesh/awesome-slash",
+  "repository": "https://github.com/avifenesh/awesome-slash",
+  "license": "MIT",
+  "keywords": ["workflow", "automation", "productivity"],
+  "minClaudeVersion": "1.0.0"
+}
+```
+
+## Validation Errors
+
+Common validation errors and fixes:
+
+### "Missing required property: name"
+**Fix:** Add `name` field to plugin.json
+
+### "name: does not match pattern"
+**Fix:** Use lowercase, kebab-case (e.g., "my-plugin" not "MyPlugin")
+
+### "version: does not match pattern"
+**Fix:** Use semantic version format: "1.0.0" not "v1.0" or "1.0"
+
+### "description: string too short"
+**Fix:** Provide description with at least 10 characters
+
+### "Unexpected property: xyz"
+**Fix:** Remove invalid field or update schema if it's a new field
+
+### "keywords: array too long"
+**Fix:** Use maximum 20 keywords
+
+## Adding New Schemas
+
+To add validation for other JSON files:
+
+1. Create `{name}.schema.json` in this directory
+2. Add validator method to `validator.js`:
+   ```javascript
+   static validate{Name}(data) {
+     const schema = this.loadSchema(path.join(__dirname, '{name}.schema.json'));
+     return this.validate(data, schema);
+   }
+   ```
+3. Export validation function
+4. Update this README
+
+## External Tools
+
+For more advanced validation, consider using:
+
+- [ajv](https://ajv.js.org/) - Production-grade JSON Schema validator
+- [json-schema-validator](https://www.jsonschemavalidator.net/) - Online validator
+- [VSCode JSON Schema](https://code.visualstudio.com/docs/languages/json#_json-schemas) - IDE integration
+
+## Related
+
+- **TypeScript Types**: `lib/types/` - TypeScript definitions for same structures
+- **Plugin Manifest Spec**: See `lib/types/README.md` for detailed type documentation
+
+## License
+
+MIT © Avi Fenesh

package/plugins/ship/lib/schemas/validator.js

@@ -0,0 +1,205 @@
+/**
+ * JSON Schema Validator
+ * Validates plugin manifests against JSON Schema
+ *
+ * @module lib/schemas/validator
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Simple JSON Schema validator (minimal implementation)
+ * For production use, consider using a library like ajv
+ */
+class SchemaValidator {
+  /**
+   * Load a JSON Schema from file
+   * @param {string} schemaPath - Path to schema file
+   * @returns {Object} Loaded schema
+   */
+  static loadSchema(schemaPath) {
+    const content = fs.readFileSync(schemaPath, 'utf8');
+    return JSON.parse(content);
+  }
+
+  /**
+   * Validate data against a schema
+   * @param {Object} data - Data to validate
+   * @param {Object} schema - JSON Schema
+   * @returns {{valid: boolean, errors: string[]}} Validation result
+   */
+  static validate(data, schema) {
+    const errors = [];
+
+    // Check type (handle arrays correctly)
+    if (schema.type) {
+      const actualType = Array.isArray(data) ? 'array' : typeof data;
+      if (actualType !== schema.type) {
+        errors.push(`Expected type ${schema.type}, got ${actualType}`);
+        return { valid: false, errors };
+      }
+    }
+
+    // Check required properties
+    if (schema.required && Array.isArray(schema.required)) {
+      for (const required of schema.required) {
+        if (!(required in data)) {
+          errors.push(`Missing required property: ${required}`);
+        }
+      }
+    }
+
+    // Check properties (guard against null)
+    if (schema.properties && typeof data === 'object' && data !== null) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in data) {
+          const propResult = this.validateProperty(data[key], propSchema, key);
+          errors.push(...propResult.errors);
+        }
+      }
+    }
+
+    // Check additional properties (guard against null, honor patternProperties)
+    if (schema.additionalProperties === false && typeof data === 'object' && data !== null) {
+      const allowedKeys = new Set(Object.keys(schema.properties || {}));
+
+      // Honor patternProperties - don't reject keys that match patterns
+      const patternProps = schema.patternProperties || {};
+      const patternRegexes = Object.keys(patternProps).map(p => new RegExp(p));
+
+      for (const key of Object.keys(data)) {
+        const matchesPattern = patternRegexes.some(regex => regex.test(key));
+        if (!allowedKeys.has(key) && !matchesPattern) {
+          errors.push(`Unexpected property: ${key}`);
+        }
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Validate a single property
+   * @param {*} value - Property value
+   * @param {Object} schema - Property schema
+   * @param {string} path - Property path for error messages
+   * @returns {{valid: boolean, errors: string[]}} Validation result
+   */
+  static validateProperty(value, schema, path) {
+    const errors = [];
+
+    // Type check
+    if (schema.type) {
+      const actualType = Array.isArray(value) ? 'array' : typeof value;
+      if (actualType !== schema.type) {
+        errors.push(`${path}: expected type ${schema.type}, got ${actualType}`);
+        return { valid: false, errors };
+      }
+    }
+
+    // String validations
+    if (schema.type === 'string' && typeof value === 'string') {
+      if (schema.minLength && value.length < schema.minLength) {
+        errors.push(`${path}: string too short (min ${schema.minLength})`);
+      }
+      if (schema.maxLength && value.length > schema.maxLength) {
+        errors.push(`${path}: string too long (max ${schema.maxLength})`);
+      }
+      if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+        errors.push(`${path}: does not match pattern ${schema.pattern}`);
+      }
+    }
+
+    // Array validations
+    if (schema.type === 'array' && Array.isArray(value)) {
+      if (schema.minItems && value.length < schema.minItems) {
+        errors.push(`${path}: array too short (min ${schema.minItems})`);
+      }
+      if (schema.maxItems && value.length > schema.maxItems) {
+        errors.push(`${path}: array too long (max ${schema.maxItems})`);
+      }
+      if (schema.uniqueItems) {
+        const seen = new Set();
+        for (const item of value) {
+          const key = JSON.stringify(item);
+          if (seen.has(key)) {
+            errors.push(`${path}: duplicate items not allowed`);
+            break;
+          }
+          seen.add(key);
+        }
+      }
+    }
+
+    // Object validations
+    if (schema.type === 'object' && typeof value === 'object' && value !== null) {
+      const result = this.validate(value, schema);
+      for (const error of result.errors) {
+        errors.push(`${path}.${error}`);
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Validate a plugin manifest
+   * @param {Object} manifest - Plugin manifest to validate
+   * @returns {{valid: boolean, errors: string[]}} Validation result
+   */
+  static validatePluginManifest(manifest) {
+    const schemaPath = path.join(__dirname, 'plugin-manifest.schema.json');
+    const schema = this.loadSchema(schemaPath);
+    return this.validate(manifest, schema);
+  }
+}
+
+/**
+ * Validate a plugin manifest file
+ * @param {string} manifestPath - Path to plugin.json
+ * @returns {{valid: boolean, errors: string[], manifest?: Object}} Validation result
+ */
+function validateManifestFile(manifestPath) {
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf8');
+    const manifest = JSON.parse(content);
+    const result = SchemaValidator.validatePluginManifest(manifest);
+    return { ...result, manifest };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`Failed to load manifest: ${error.message}`]
+    };
+  }
+}
+
+module.exports = {
+  SchemaValidator,
+  validateManifestFile
+};
+
+// CLI usage
+if (require.main === module) {
+  const manifestPath = process.argv[2] || '.claude-plugin/plugin.json';
+
+  console.log(`Validating: ${manifestPath}`);
+  const result = validateManifestFile(manifestPath);
+
+  if (result.valid) {
+    console.log('✓ Manifest is valid');
+    if (result.manifest) {
+      console.log(`  Plugin: ${result.manifest.name} v${result.manifest.version}`);
+      console.log(`  Author: ${result.manifest.author.name}`);
+    }
+    process.exit(0);
+  } else {
+    console.error('✗ Manifest is invalid:');
+    for (const error of result.errors) {
+      console.error(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+}

package/plugins/ship/lib/sources/custom-handler.js

@@ -0,0 +1,199 @@
+/**
+ * Custom Source Handler
+ * Handles follow-up questions and tool probing for custom sources
+ *
+ * @module lib/sources/custom-handler
+ */
+
+const { execFileSync } = require('child_process');
+const sourceCache = require('./source-cache');
+
+/**
+ * Validate tool name to prevent command injection
+ * Only allows alphanumeric, hyphens, and underscores
+ * @param {string} toolName - Tool name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidToolName(toolName) {
+  return /^[a-zA-Z0-9_-]+$/.test(toolName);
+}
+
+/**
+ * Source types for custom selection
+ */
+const SOURCE_TYPES = {
+  MCP: 'mcp',
+  CLI: 'cli',
+  SKILL: 'skill',
+  FILE: 'file'
+};
+
+/**
+ * Build follow-up questions for custom source
+ * Returns AskUserQuestion-compatible structure
+ * @returns {Object} Questions object for AskUserQuestion tool
+ */
+function getCustomTypeQuestion() {
+  return {
+    header: 'Source Type',
+    question: 'What type of source is this?',
+    options: [
+      { label: 'CLI Tool', description: 'Command-line tool (e.g., tea, glab, jira-cli)' },
+      { label: 'MCP Server', description: 'Model Context Protocol server' },
+      { label: 'Skill/Plugin', description: 'Claude Code skill or plugin' },
+      { label: 'File Path', description: 'Local file with tasks (markdown, JSON, etc.)' }
+    ],
+    multiSelect: false
+  };
+}
+
+/**
+ * Build name/path question based on type
+ * @param {string} type - Source type (mcp, cli, skill, file)
+ * @returns {Object} Questions object for AskUserQuestion tool
+ */
+function getCustomNameQuestion(type) {
+  const prompts = {
+    cli: { header: 'CLI Tool', question: 'What is the CLI tool name?', hint: 'e.g., tea, glab, jira' },
+    mcp: { header: 'MCP Server', question: 'What is the MCP server name?', hint: 'e.g., gitea-mcp, linear-mcp' },
+    skill: { header: 'Skill Name', question: 'What is the skill name?', hint: 'e.g., linear:list-issues' },
+    file: { header: 'File Path', question: 'What is the file path?', hint: 'e.g., ./backlog.md, /docs/tasks.json' }
+  };
+  return prompts[type] || prompts.cli;
+}
+
+/**
+ * Map user's type selection to internal type
+ * @param {string} selection - User's selection label
+ * @returns {string} Internal type (mcp, cli, skill, file)
+ */
+function mapTypeSelection(selection) {
+  const map = {
+    'CLI Tool': SOURCE_TYPES.CLI,
+    'MCP Server': SOURCE_TYPES.MCP,
+    'Skill/Plugin': SOURCE_TYPES.SKILL,
+    'File Path': SOURCE_TYPES.FILE
+  };
+  return map[selection] || SOURCE_TYPES.CLI;
+}
+
+/**
+ * Probe CLI tool for available commands
+ * @param {string} toolName - CLI tool name
+ * @returns {Object} Discovered capabilities
+ */
+function probeCLI(toolName) {
+  const capabilities = {
+    type: 'cli',
+    tool: toolName,
+    available: false,
+    features: [],
+    commands: {}
+  };
+
+  // Validate tool name to prevent command injection
+  if (!isValidToolName(toolName)) {
+    console.error(`Invalid tool name: ${toolName}`);
+    return capabilities;
+  }
+
+  try {
+    // Check if tool exists using execFileSync (prevents command injection)
+    execFileSync(toolName, ['--version'], { encoding: 'utf8', stdio: 'pipe' });
+    capabilities.available = true;
+  } catch {
+    return capabilities;
+  }
+
+  // Known CLI patterns
+  const knownPatterns = {
+    tea: {
+      features: ['issues', 'prs', 'reviews'],
+      commands: {
+        list_issues: 'tea issues list',
+        get_issue: 'tea issues view {id}',
+        create_pr: 'tea pulls create --title {title} --base {base} --head {head}',
+        list_prs: 'tea pulls list',
+        get_pr: 'tea pr {id}'
+      }
+    },
+    glab: {
+      features: ['issues', 'prs', 'ci'],
+      commands: {
+        list_issues: 'glab issue list',
+        get_issue: 'glab issue view {id}',
+        create_pr: 'glab mr create --title {title} --target-branch {base} --source-branch {head}',
+        list_prs: 'glab mr list',
+        get_pr: 'glab mr view {id}',
+        ci_status: 'glab ci status'
+      }
+    },
+    gh: {
+      features: ['issues', 'prs', 'ci'],
+      commands: {
+        list_issues: 'gh issue list',
+        get_issue: 'gh issue view {id}',
+        create_pr: 'gh pr create --title {title} --base {base} --head {head}',
+        list_prs: 'gh pr list',
+        get_pr: 'gh pr view {id}',
+        ci_status: 'gh pr checks {id}'
+      }
+    }
+  };
+
+  // Use known pattern if available
+  if (knownPatterns[toolName]) {
+    capabilities.features = knownPatterns[toolName].features;
+    capabilities.commands = knownPatterns[toolName].commands;
+    capabilities.pattern = 'known';
+  } else {
+    // Unknown tool - try to discover via help
+    capabilities.pattern = 'discovered';
+    capabilities.features = ['unknown'];
+    capabilities.commands = {
+      help: `${toolName} --help`
+    };
+  }
+
+  return capabilities;
+}
+
+/**
+ * Build complete custom source config and cache it
+ * @param {string} type - Source type
+ * @param {string} name - Tool name or path
+ * @returns {Object} Complete source configuration
+ */
+function buildCustomConfig(type, name) {
+  const config = {
+    source: 'custom',
+    type: type,
+    tool: name
+  };
+
+  // Probe capabilities for CLI tools
+  if (type === SOURCE_TYPES.CLI) {
+    const capabilities = probeCLI(name);
+    config.capabilities = capabilities;
+
+    // Cache capabilities for fast access
+    if (capabilities.available) {
+      sourceCache.saveToolCapabilities(name, capabilities);
+    }
+  }
+
+  // Save preference
+  sourceCache.savePreference(config);
+
+  return config;
+}
+
+module.exports = {
+  SOURCE_TYPES,
+  getCustomTypeQuestion,
+  getCustomNameQuestion,
+  mapTypeSelection,
+  probeCLI,
+  buildCustomConfig,
+  isValidToolName
+};