awesome-slash 2.4.3 → 2.5.0

package/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/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/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/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/lib/utils/context-optimizer.js

@@ -8,42 +8,11 @@
  * @license MIT
  */
 
-/**
- * Escape shell special characters for safe command interpolation
- * Handles all dangerous shell metacharacters including command injection vectors
- * @param {string} str - String to escape
- * @returns {string} Escaped string safe for shell use
- */
-function escapeShell(str) {
-  if (typeof str !== 'string') return '';
-  // Reject null bytes and newlines which could be used for injection
-  if (str.includes('\0') || str.includes('\n') || str.includes('\r')) {
-    throw new Error('Input contains invalid characters (null bytes or newlines)');
-  }
-  // Escape all shell metacharacters: " $ ` \ ! ; | & > < ( ) { } [ ] * ? ~ # ' space tab
-  return str.replace(/["\$`\\!;|&><(){}[\]*?~#'\s]/g, '\\$&');
-}
-
-/**
- * Escape single quotes for shell (replace ' with '\''
- * @param {string} str - String to escape
- * @returns {string} Escaped string safe for single-quoted shell use
- */
-function escapeSingleQuotes(str) {
-  if (typeof str !== 'string') return '';
-  return str.replace(/'/g, "'\\''");
-}
-
-/**
- * Validate and sanitize file extension
- * @param {string} ext - Extension to validate
- * @returns {string} Safe extension (alphanumeric only)
- */
-function sanitizeExtension(ext) {
-  if (typeof ext !== 'string') return 'ts';
-  const safe = ext.replace(/[^a-zA-Z0-9]/g, '');
-  return safe || 'ts';
-}
+const {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension
+} = require('./shell-escape');
 
 /**
  * Validate git branch name to prevent command injection

package/lib/utils/deprecation.js

@@ -0,0 +1,37 @@
+/**
+ * Deprecation Warning Utility
+ * Centralized utility for handling deprecation warnings across the codebase
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+// Track which functions have already shown deprecation warnings (once per function)
+const _deprecationWarned = new Set();
+
+/**
+ * Show deprecation warning for sync functions (once per function name)
+ * @param {string} funcName - Name of the deprecated sync function
+ * @param {string} asyncAlt - Name of the async alternative
+ */
+function warnDeprecation(funcName, asyncAlt) {
+  if (_deprecationWarned.has(funcName)) return;
+  _deprecationWarned.add(funcName);
+  console.warn(
+    `DEPRECATED: ${funcName}() is synchronous and blocks the event loop. ` +
+    `Use ${asyncAlt}() instead. Will be removed in v3.0.0.`
+  );
+}
+
+/**
+ * Reset deprecation warnings (for testing only)
+ * @private
+ */
+function _resetDeprecationWarnings() {
+  _deprecationWarned.clear();
+}
+
+module.exports = {
+  warnDeprecation,
+  _resetDeprecationWarnings
+};

package/lib/utils/shell-escape.js

@@ -0,0 +1,88 @@
+/**
+ * Shell Escaping Utilities
+ * Centralized string escaping functions for safe shell command construction
+ *
+ * @module lib/utils/shell-escape
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Escape shell special characters for safe command interpolation
+ * Handles all dangerous shell metacharacters including command injection vectors
+ * Optimized: uses single regex test instead of multiple .includes() calls
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for shell use
+ * @throws {Error} If string contains null bytes or newlines
+ */
+function escapeShell(str) {
+  if (typeof str !== 'string') return '';
+
+  // Reject null bytes and newlines which could be used for injection
+  // Optimized: single regex test instead of 3 separate .includes() scans
+  // Use \x00 instead of \0 for better portability across JS engines
+  if (/[\x00\n\r]/.test(str)) {
+    throw new Error('Input contains invalid characters (null bytes or newlines)');
+  }
+
+  // Escape all shell metacharacters: " $ ` \ ! ; | & > < ( ) { } [ ] * ? ~ # ' space tab
+  return str.replace(/["\$`\\!;|&><(){}[\]*?~#'\s]/g, '\\$&');
+}
+
+/**
+ * Escape single quotes for shell (replace ' with '\''
+ * Use this for strings that will be wrapped in single quotes
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for single-quoted shell use
+ */
+function escapeSingleQuotes(str) {
+  if (typeof str !== 'string') return '';
+  return str.replace(/'/g, "'\\''");
+}
+
+/**
+ * Validate and sanitize file extension
+ * Removes all non-alphanumeric characters
+ * @param {string} ext - Extension to validate
+ * @returns {string} Safe extension (alphanumeric only), defaults to 'ts' if empty
+ */
+function sanitizeExtension(ext) {
+  if (typeof ext !== 'string') return 'ts';
+  const safe = ext.replace(/[^a-zA-Z0-9]/g, '');
+  return safe || 'ts';
+}
+
+/**
+ * Escape a string for use in a double-quoted shell context
+ * More permissive than escapeShell but still safe
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for double-quoted shell use
+ */
+function escapeDoubleQuotes(str) {
+  if (typeof str !== 'string') return '';
+
+  // In double quotes, we need to escape: $ ` " \ and newlines
+  return str.replace(/[$`"\\\n]/g, '\\$&');
+}
+
+/**
+ * Quote a string for safe shell use
+ * Wraps in single quotes and escapes any embedded single quotes
+ * This is often safer than escapeShell for complex strings
+ * @param {string} str - String to quote
+ * @returns {string} Safely quoted string
+ */
+function quoteShell(str) {
+  if (typeof str !== 'string') return "''";
+
+  // Wrap in single quotes and escape any embedded single quotes
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+module.exports = {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension,
+  escapeDoubleQuotes,
+  quoteShell
+};