awesome-slash 2.4.3 → 2.5.0

package/plugins/deslop-around/lib/types/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Plugin Interface Type Definitions
+ * Centralized type definitions for all plugin components
+ *
+ * @module lib/types
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+// Re-export all types
+export * from './plugin-manifest';
+export * from './command-frontmatter';
+export * from './agent-frontmatter';
+export * from './skill-frontmatter';
+export * from './hook-frontmatter';
+
+/**
+ * Plugin component types union
+ */
+export type PluginComponentType = 'command' | 'agent' | 'skill' | 'hook';
+
+/**
+ * Plugin directory structure
+ */
+export interface PluginStructure {
+  /** Plugin root directory */
+  root: string;
+
+  /** Plugin manifest (plugin.json) */
+  manifest: string;
+
+  /** Commands directory */
+  commands?: string;
+
+  /** Agents directory */
+  agents?: string;
+
+  /** Skills directory */
+  skills?: string;
+
+  /** Hooks directory */
+  hooks?: string;
+
+  /** Shared library directory */
+  lib?: string;
+
+  /** Tests directory */
+  tests?: string;
+}
+
+/**
+ * Plugin validation result
+ */
+export interface PluginValidationResult {
+  /** Whether plugin is valid */
+  valid: boolean;
+
+  /** Validation errors (if any) */
+  errors: string[];
+
+  /** Validation warnings (if any) */
+  warnings: string[];
+
+  /** Detected components */
+  components: {
+    commands: number;
+    agents: number;
+    skills: number;
+    hooks: number;
+  };
+}
+
+/**
+ * Standard plugin directory structure
+ */
+export const PLUGIN_STRUCTURE: Readonly<Record<string, string>> = {
+  MANIFEST: '.claude-plugin/plugin.json',
+  COMMANDS: 'commands',
+  AGENTS: 'agents',
+  SKILLS: 'skills',
+  HOOKS: 'hooks',
+  LIB: 'lib',
+  TESTS: 'tests'
+} as const;

package/plugins/deslop-around/lib/types/plugin-manifest.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Plugin Manifest Type Definitions
+ * Defines the structure of plugin.json files
+ *
+ * @module lib/types/plugin-manifest
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Author information for plugin manifest
+ */
+export interface PluginAuthor {
+  /** Author's full name */
+  name: string;
+  /** Author's email address (optional) */
+  email?: string;
+  /** Author's website or GitHub profile URL (optional) */
+  url?: string;
+}
+
+/**
+ * Plugin manifest structure
+ * Required fields for all Claude Code plugins
+ */
+export interface PluginManifest {
+  /** Unique plugin identifier (kebab-case, lowercase) */
+  name: string;
+
+  /** Semantic version (MAJOR.MINOR.PATCH) */
+  version: string;
+
+  /** Short description of plugin functionality */
+  description: string;
+
+  /** Author information */
+  author: PluginAuthor;
+
+  /** Plugin homepage URL (optional) */
+  homepage?: string;
+
+  /** Repository URL (optional) */
+  repository?: string;
+
+  /** License identifier (SPDX format, e.g., "MIT", "Apache-2.0") */
+  license: string;
+
+  /** Search keywords for discoverability (optional) */
+  keywords?: string[];
+
+  /** Minimum Claude Code version required (optional) */
+  minClaudeVersion?: string;
+
+  /** Plugin dependencies (optional) */
+  dependencies?: {
+    [pluginName: string]: string; // version constraint
+  };
+
+  /** Plugin configuration schema (optional) */
+  config?: {
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Type guard to check if an object is a valid PluginManifest
+ */
+export function isPluginManifest(obj: unknown): obj is PluginManifest {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const manifest = obj as Partial<PluginManifest>;
+
+  return (
+    typeof manifest.name === 'string' &&
+    /^[a-z0-9-]+$/.test(manifest.name) &&
+    typeof manifest.version === 'string' &&
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/.test(manifest.version) &&
+    typeof manifest.description === 'string' &&
+    typeof manifest.author === 'object' &&
+    manifest.author !== null &&
+    typeof manifest.author.name === 'string' &&
+    typeof manifest.license === 'string'
+  );
+}
+
+/**
+ * Validates a plugin manifest against the schema
+ * @throws {Error} If manifest is invalid
+ */
+export function validatePluginManifest(manifest: unknown): asserts manifest is PluginManifest {
+  if (!isPluginManifest(manifest)) {
+    throw new Error('Invalid plugin manifest: missing required fields or invalid format');
+  }
+
+  // Additional validations
+  if (manifest.keywords && !Array.isArray(manifest.keywords)) {
+    throw new Error('Invalid plugin manifest: keywords must be an array');
+  }
+
+  if (manifest.dependencies && typeof manifest.dependencies !== 'object') {
+    throw new Error('Invalid plugin manifest: dependencies must be an object');
+  }
+}

package/plugins/deslop-around/lib/types/skill-frontmatter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Skill Frontmatter Type Definitions
+ * Defines the structure of YAML frontmatter in skill markdown files
+ *
+ * @module lib/types/skill-frontmatter
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Skill frontmatter structure
+ * YAML metadata at the top of skill markdown files
+ */
+export interface SkillFrontmatter {
+  /** Skill unique identifier (kebab-case) */
+  skill: string;
+
+  /** Short description of skill purpose */
+  description: string;
+
+  /** Skill category for organization */
+  category?: string;
+
+  /** When this skill should be invoked (triggering conditions) */
+  'when-to-use'?: string[];
+
+  /** Example usage scenarios */
+  examples?: string[];
+
+  /** Preferred model for this skill (sonnet, opus, haiku) */
+  model?: 'sonnet' | 'opus' | 'haiku';
+
+  /** Whether skill requires user approval before running */
+  requiresApproval?: boolean;
+
+  /** Tags for searchability */
+  tags?: string[];
+
+  /** Related commands or skills */
+  related?: string[];
+}
+
+/**
+ * Type guard to check if an object is valid SkillFrontmatter
+ */
+export function isSkillFrontmatter(obj: unknown): obj is SkillFrontmatter {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const fm = obj as Partial<SkillFrontmatter>;
+
+  return (
+    typeof fm.skill === 'string' &&
+    fm.skill.length > 0 &&
+    typeof fm.description === 'string' &&
+    fm.description.length > 0
+  );
+}
+
+/**
+ * Validates skill frontmatter
+ * @throws {Error} If frontmatter is invalid
+ */
+export function validateSkillFrontmatter(
+  frontmatter: unknown
+): asserts frontmatter is SkillFrontmatter {
+  if (!isSkillFrontmatter(frontmatter)) {
+    throw new Error('Invalid skill frontmatter: missing required fields');
+  }
+
+  // Additional validations
+  if (frontmatter.model && !['sonnet', 'opus', 'haiku'].includes(frontmatter.model)) {
+    throw new Error('Invalid skill frontmatter: model must be sonnet, opus, or haiku');
+  }
+
+  if (frontmatter['when-to-use'] && !Array.isArray(frontmatter['when-to-use'])) {
+    throw new Error('Invalid skill frontmatter: when-to-use must be an array');
+  }
+
+  if (frontmatter.examples && !Array.isArray(frontmatter.examples)) {
+    throw new Error('Invalid skill frontmatter: examples must be an array');
+  }
+
+  if (frontmatter.tags && !Array.isArray(frontmatter.tags)) {
+    throw new Error('Invalid skill frontmatter: tags must be an array');
+  }
+
+  if (frontmatter.related && !Array.isArray(frontmatter.related)) {
+    throw new Error('Invalid skill frontmatter: related must be an array');
+  }
+}

package/plugins/deslop-around/lib/utils/cache-manager.js

@@ -0,0 +1,154 @@
+/**
+ * Cache Manager
+ * Centralized caching abstraction with TTL and size limits
+ *
+ * @module lib/utils/cache-manager
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Cache manager with TTL and size limits
+ */
+class CacheManager {
+  /**
+   * Create a new cache manager
+   * @param {Object} options - Cache configuration
+   * @param {number} options.maxSize - Maximum number of entries (default: 100)
+   * @param {number} options.ttl - Time-to-live in milliseconds (default: 60000)
+   * @param {number} options.maxValueSize - Maximum size per value in bytes (default: null - unlimited)
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 60000; // 1 minute default
+    this.maxValueSize = options.maxValueSize || null;
+
+    // Use Map for insertion-order guarantee (FIFO eviction)
+    this._cache = new Map();
+    this._timestamps = new Map();
+  }
+
+  /**
+   * Get a value from cache
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined if not found/expired
+   */
+  get(key) {
+    if (!this._cache.has(key)) {
+      return undefined;
+    }
+
+    // Check if expired
+    const timestamp = this._timestamps.get(key);
+    if (Date.now() - timestamp > this.ttl) {
+      this.delete(key);
+      return undefined;
+    }
+
+    return this._cache.get(key);
+  }
+
+  /**
+   * Set a value in cache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @returns {boolean} True if cached, false if value too large
+   */
+  set(key, value) {
+    // Check value size if limit set
+    if (this.maxValueSize !== null && typeof value === 'string') {
+      if (value.length > this.maxValueSize) {
+        return false; // Value too large, don't cache
+      }
+    }
+
+    // Update or add entry
+    this._cache.set(key, value);
+    this._timestamps.set(key, Date.now());
+
+    // Enforce size limit with FIFO eviction
+    this._enforceMaxSize();
+
+    return true;
+  }
+
+  /**
+   * Check if key exists and is not expired
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key exists and is valid
+   */
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  /**
+   * Delete a key from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key existed
+   */
+  delete(key) {
+    this._timestamps.delete(key);
+    return this._cache.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    this._cache.clear();
+    this._timestamps.clear();
+  }
+
+  /**
+   * Get current cache size
+   * @returns {number} Number of entries
+   */
+  get size() {
+    return this._cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {Object} Stats object with size, ttl, maxSize
+   */
+  getStats() {
+    return {
+      size: this._cache.size,
+      maxSize: this.maxSize,
+      ttl: this.ttl,
+      maxValueSize: this.maxValueSize
+    };
+  }
+
+  /**
+   * Enforce maximum cache size using FIFO eviction
+   * @private
+   */
+  _enforceMaxSize() {
+    // Map maintains insertion order - first key is oldest
+    while (this._cache.size > this.maxSize) {
+      const firstKey = this._cache.keys().next().value;
+      this.delete(firstKey);
+    }
+  }
+
+  /**
+   * Remove expired entries (useful for long-running processes)
+   * @returns {number} Number of entries removed
+   */
+  prune() {
+    let removed = 0;
+    const now = Date.now();
+
+    for (const [key, timestamp] of this._timestamps.entries()) {
+      if (now - timestamp > this.ttl) {
+        this.delete(key);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+}
+
+module.exports = { CacheManager };

package/plugins/deslop-around/lib/utils/context-optimizer.js

@@ -8,36 +8,83 @@
  * @license MIT
  */
 
+const {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension
+} = require('./shell-escape');
+
 /**
- * Escape shell special characters for safe command interpolation
- * @param {string} str - String to escape
- * @returns {string} Escaped string safe for shell use
+ * Validate git branch name to prevent command injection
+ * @param {string} branch - Branch name to validate
+ * @returns {string} Validated branch name
+ * @throws {Error} If branch name contains invalid characters
  */
-function escapeShell(str) {
-  if (typeof str !== 'string') return '';
-  // Escape characters that have special meaning in shell
-  return str.replace(/["$`\\!]/g, '\\$&');
+function validateBranchName(branch) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new Error('Branch name must be a non-empty string');
+  }
+  if (branch.length > 255) {
+    throw new Error('Branch name too long (max 255 characters)');
+  }
+  // Allow alphanumeric, underscore, hyphen, forward slash, and dot
+  if (!/^[a-zA-Z0-9/_.-]+$/.test(branch)) {
+    throw new Error('Branch name contains invalid characters');
+  }
+  // Prevent git option injection
+  if (branch.startsWith('-')) {
+    throw new Error('Branch name cannot start with hyphen');
+  }
+  return branch;
 }
 
 /**
- * Escape single quotes for shell (replace ' with '\''
- * @param {string} str - String to escape
- * @returns {string} Escaped string safe for single-quoted shell use
+ * Validate git reference to prevent command injection
+ * @param {string} ref - Git reference to validate
+ * @returns {string} Validated reference
+ * @throws {Error} If reference contains invalid characters
  */
-function escapeSingleQuotes(str) {
-  if (typeof str !== 'string') return '';
-  return str.replace(/'/g, "'\\''");
+function validateGitRef(ref) {
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new Error('Git reference must be a non-empty string');
+  }
+  if (ref.length > 255) {
+    throw new Error('Git reference too long (max 255 characters)');
+  }
+  // Allow alphanumeric, tilde, caret, dot, hyphen, underscore, forward slash
+  if (!/^[a-zA-Z0-9~^._/-]+$/.test(ref)) {
+    throw new Error('Git reference contains invalid characters');
+  }
+  // Prevent git option injection
+  if (ref.startsWith('-')) {
+    throw new Error('Git reference cannot start with hyphen');
+  }
+  return ref;
 }
 
 /**
- * Validate and sanitize file extension
- * @param {string} ext - Extension to validate
- * @returns {string} Safe extension (alphanumeric only)
+ * Validate numeric limit parameter
+ * @param {number} limit - Limit value to validate
+ * @param {number} max - Maximum allowed value (default: 1000)
+ * @returns {number} Validated limit
+ * @throws {Error} If limit is invalid
  */
-function sanitizeExtension(ext) {
-  if (typeof ext !== 'string') return 'ts';
-  const safe = ext.replace(/[^a-zA-Z0-9]/g, '');
-  return safe || 'ts';
+function validateLimit(limit, max = 1000) {
+  // Strict type check - must be number or numeric string
+  if (typeof limit === 'string') {
+    // Only allow pure numeric strings
+    if (!/^\d+$/.test(limit)) {
+      throw new Error('Limit must be a positive integer');
+    }
+  }
+  const num = typeof limit === 'number' ? limit : parseInt(limit, 10);
+  if (!Number.isInteger(num) || num < 1) {
+    throw new Error('Limit must be a positive integer');
+  }
+  if (num > max) {
+    throw new Error(`Limit cannot exceed ${max}`);
+  }
+  return num;
 }
 
 /**
@@ -49,8 +96,10 @@ const contextOptimizer = {
    * @param {number} limit - Number of commits to retrieve (default: 10)
    * @returns {string} Git command
    */
-  recentCommits: (limit = 10) =>
-    `git log --oneline --no-decorate -${limit} --format="%h %s"`,
+  recentCommits: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git log --oneline --no-decorate -${safeLimit} --format="%h %s"`;
+  },
 
   /**
    * Get compact git status (untracked files excluded)
@@ -64,8 +113,10 @@ const contextOptimizer = {
    * @param {string} ref - Reference to compare from (default: 'HEAD~5')
    * @returns {string} Git command
    */
-  fileChanges: (ref = 'HEAD~5') =>
-    `git diff ${ref}..HEAD --name-status`,
+  fileChanges: (ref = 'HEAD~5') => {
+    const safeRef = validateGitRef(ref);
+    return `git diff ${safeRef}..HEAD --name-status`;
+  },
 
   /**
    * Get current branch name
@@ -102,11 +153,15 @@ const contextOptimizer = {
    * @returns {string} Git command
    */
   lineAge: (file, line) => {
-    // Validate line is a positive integer
+    // Validate line is a positive integer with reasonable bounds
     const lineNum = parseInt(line, 10);
+    const MAX_LINE_NUMBER = 10000000; // 10 million lines - reasonable upper bound
     if (!Number.isInteger(lineNum) || lineNum < 1) {
       throw new Error('Line must be a positive integer');
     }
+    if (lineNum > MAX_LINE_NUMBER) {
+      throw new Error(`Line number cannot exceed ${MAX_LINE_NUMBER}`);
+    }
     // Escape file path for safe shell usage
     const safeFile = escapeShell(file);
     return `git blame -L ${lineNum},${lineNum} "${safeFile}" --porcelain | grep '^committer-time' | cut -d' ' -f2`;
@@ -127,8 +182,10 @@ const contextOptimizer = {
    * @param {string} ref - Reference to compare from (default: 'HEAD~5')
    * @returns {string} Git command
    */
-  diffStat: (ref = 'HEAD~5') =>
-    `git diff ${ref}..HEAD --stat | head -20`,
+  diffStat: (ref = 'HEAD~5') => {
+    const safeRef = validateGitRef(ref);
+    return `git diff ${safeRef}..HEAD --stat | head -20`;
+  },
 
   /**
    * Get contributors list (limited to top 10)
@@ -156,24 +213,30 @@ const contextOptimizer = {
    * @param {number} limit - Number of branches (default: 10)
    * @returns {string} Git command
    */
-  branches: (limit = 10) =>
-    `git branch --format='%(refname:short)' | head -${limit}`,
+  branches: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git branch --format='%(refname:short)' | head -${safeLimit}`;
+  },
 
   /**
    * Get tags list (limited)
    * @param {number} limit - Number of tags (default: 10)
    * @returns {string} Git command
    */
-  tags: (limit = 10) =>
-    `git tag --sort=-creatordate | head -${limit}`,
+  tags: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git tag --sort=-creatordate | head -${safeLimit}`;
+  },
 
   /**
    * Get count of commits on current branch since branching from main
    * @param {string} mainBranch - Main branch name (default: 'main')
    * @returns {string} Git command
    */
-  commitsSinceBranch: (mainBranch = 'main') =>
-    `git rev-list --count ${mainBranch}..HEAD`,
+  commitsSinceBranch: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git rev-list --count ${safeBranch}..HEAD`;
+  },
 
   /**
    * Check if working directory is clean
@@ -187,16 +250,20 @@ const contextOptimizer = {
    * @param {string} mainBranch - Main branch name (default: 'main')
    * @returns {string} Git command
    */
-  mergeBase: (mainBranch = 'main') =>
-    `git merge-base ${mainBranch} HEAD`,
+  mergeBase: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git merge-base ${safeBranch} HEAD`;
+  },
 
   /**
    * Get files modified in current branch (since branching)
    * @param {string} mainBranch - Main branch name (default: 'main')
    * @returns {string} Git command
    */
-  branchChangedFiles: (mainBranch = 'main') =>
-    `git diff ${mainBranch}...HEAD --name-only`,
+  branchChangedFiles: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git diff ${safeBranch}...HEAD --name-only`;
+  },
 
   /**
    * Get commit count by author
@@ -219,4 +286,15 @@ const contextOptimizer = {
   }
 };
 
+// Export main API
 module.exports = contextOptimizer;
+
+// Export internal functions for testing
+module.exports._internal = {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension,
+  validateBranchName,
+  validateGitRef,
+  validateLimit
+};