@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/tool-interface.js

@@ -1,314 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview CAWS Tool Interface - Base classes and contracts for tool implementation
- * Defines the standard interface that all CAWS tools must implement
- * @author @darianrosebrook
- */
-
-/**
- * Standard tool execution result
- * @typedef {Object} ToolExecutionResult
- * @property {boolean} success - Whether execution succeeded
- * @property {number} duration - Execution duration in milliseconds
- * @property {Object} output - Tool-specific output data
- * @property {Array<string>} errors - Error messages if execution failed
- * @property {Object} metadata - Additional execution metadata
- */
-
-/**
- * Tool metadata structure
- * @typedef {Object} ToolMetadata
- * @property {string} id - Unique tool identifier
- * @property {string} name - Human-readable tool name
- * @property {string} version - Tool version (semver)
- * @property {string} description - Tool description
- * @property {Array<string>} capabilities - Tool capabilities (e.g., ['validation', 'security'])
- * @property {string} author - Tool author
- * @property {string} license - Tool license
- * @property {Array<string>} dependencies - Required Node.js dependencies
- */
-
-/**
- * Tool execution context
- * @typedef {Object} ToolExecutionContext
- * @property {string} workingDirectory - Current working directory
- * @property {Object} environment - Environment variables
- * @property {Object} config - CAWS configuration
- * @property {Object} workingSpec - Current working specification
- * @property {number} timeout - Execution timeout in milliseconds
- */
-
-/**
- * Base Tool class - All CAWS tools should extend this class
- */
-class BaseTool {
-  constructor() {
-    this.metadata = this.getMetadata();
-  }
-
-  /**
-   * Execute the tool with given parameters
-   * @param {Object} parameters - Tool-specific execution parameters
-   * @param {ToolExecutionContext} context - Execution context
-   * @returns {Promise<ToolExecutionResult>} Execution result
-   */
-  async execute(parameters = {}, context = {}) {
-    const startTime = Date.now();
-
-    try {
-      // Validate parameters
-      this.validateParameters(parameters);
-
-      // Execute tool logic
-      const result = await this.executeImpl(parameters, context);
-
-      // Ensure result conforms to interface
-      const executionResult = this.normalizeResult(result, Date.now() - startTime);
-
-      return executionResult;
-    } catch (error) {
-      return this.createErrorResult(error, Date.now() - startTime);
-    }
-  }
-
-  /**
-   * Get tool metadata
-   * @returns {ToolMetadata} Tool metadata
-   */
-  getMetadata() {
-    throw new Error('Tool must implement getMetadata() method');
-  }
-
-  /**
-   * Validate tool parameters
-   * @param {Object} _parameters - Parameters to validate
-   * @throws {Error} If parameters are invalid
-   */
-  validateParameters(_parameters) {
-    // Default implementation - override in subclasses
-    return true;
-  }
-
-  /**
-   * Execute tool implementation (must be overridden by subclasses)
-   * @param {Object} _parameters - Tool parameters
-   * @param {ToolExecutionContext} _context - Execution context
-   * @returns {Promise<Object>} Tool-specific result
-   */
-  async executeImpl(_parameters, _context) {
-    throw new Error('Tool must implement executeImpl() method');
-  }
-
-  /**
-   * Normalize execution result to standard format
-   * @private
-   * @param {Object} result - Raw tool result
-   * @param {number} duration - Execution duration
-   * @returns {ToolExecutionResult} Normalized result
-   */
-  normalizeResult(result, duration) {
-    return {
-      success: result.success !== false,
-      duration,
-      output: result.output || result,
-      errors: Array.isArray(result.errors) ? result.errors : [],
-      metadata: result.metadata || {},
-    };
-  }
-
-  /**
-   * Create error result
-   * @private
-   * @param {Error} error - Execution error
-   * @param {number} duration - Execution duration
-   * @returns {ToolExecutionResult} Error result
-   */
-  createErrorResult(error, duration) {
-    return {
-      success: false,
-      duration,
-      output: null,
-      errors: [error.message],
-      metadata: {
-        errorType: error.constructor.name,
-        stack: error.stack,
-      },
-    };
-  }
-}
-
-/**
- * Validation Tool base class - For tools that perform validation checks
- */
-class ValidationTool extends BaseTool {
-  constructor() {
-    super();
-    this.capabilities = ['validation'];
-  }
-
-  /**
-   * Execute validation
-   * @param {Object} parameters - Validation parameters
-   * @param {ToolExecutionContext} context - Execution context
-   * @returns {Promise<ToolExecutionResult>} Validation result
-   */
-  async executeImpl(parameters, context) {
-    const validationResult = await this.validate(parameters, context);
-
-    return {
-      success: validationResult.valid,
-      output: validationResult,
-      errors: validationResult.errors || [],
-      metadata: {
-        checksRun: validationResult.checks?.length || 0,
-        score: validationResult.score || 0,
-      },
-    };
-  }
-
-  /**
-   * Perform validation (must be implemented by subclasses)
-   * @param {Object} parameters - Validation parameters
-   * @param {ToolExecutionContext} context - Execution context
-   * @returns {Promise<Object>} Validation result
-   */
-  async validate(_parameters, _context) {
-    throw new Error('ValidationTool must implement validate() method');
-  }
-}
-
-/**
- * Quality Gate Tool base class - For tools that enforce quality standards
- */
-class QualityGateTool extends ValidationTool {
-  constructor() {
-    super();
-    this.capabilities = ['validation', 'quality-gates'];
-  }
-
-  /**
-   * Get quality gate thresholds for current tier
-   * @param {number} tier - Risk tier (1-3)
-   * @returns {Object} Threshold configuration
-   */
-  getTierThresholds(tier) {
-    const thresholds = {
-      1: {
-        // Tier 1 - Highest rigor
-        coverage: 0.9,
-        mutation: 0.7,
-        contracts: true,
-        manualReview: true,
-      },
-      2: {
-        // Tier 2 - Standard rigor
-        coverage: 0.8,
-        mutation: 0.5,
-        contracts: true,
-        manualReview: false,
-      },
-      3: {
-        // Tier 3 - Low rigor
-        coverage: 0.7,
-        mutation: 0.3,
-        contracts: false,
-        manualReview: false,
-      },
-    };
-
-    return thresholds[tier] || thresholds[2];
-  }
-}
-
-/**
- * Security Tool base class - For tools that perform security checks
- */
-class SecurityTool extends ValidationTool {
-  constructor() {
-    super();
-    this.capabilities = ['validation', 'security'];
-  }
-
-  /**
-   * Check for security violations
-   * @param {Object} target - Target to check (file, code, etc.)
-   * @returns {Promise<Array<Object>>} Array of security violations
-   */
-  async checkSecurityViolations(target) {
-    const violations = [];
-
-    // Check for common security patterns
-    const patterns = [
-      { name: 'hardcoded_secrets', pattern: /password|token|key|secret/i, severity: 'high' },
-      { name: 'unsafe_eval', pattern: /eval\(|Function\(/, severity: 'high' },
-      { name: 'dangerous_modules', pattern: /child_process|fs-extra/, severity: 'medium' },
-    ];
-
-    for (const { name, pattern, severity } of patterns) {
-      if (pattern.test(target)) {
-        violations.push({ name, severity, message: `${name} pattern detected` });
-      }
-    }
-
-    return violations;
-  }
-}
-
-/**
- * Utility functions for tool development
- */
-const ToolUtils = {
-  /**
-   * Create standardized success result
-   * @param {Object} output - Tool output
-   * @param {Object} metadata - Additional metadata
-   * @returns {ToolExecutionResult} Success result
-   */
-  createSuccessResult(output = {}, metadata = {}) {
-    return {
-      success: true,
-      duration: 0, // Will be set by BaseTool
-      output,
-      errors: [],
-      metadata,
-    };
-  },
-
-  /**
-   * Create standardized error result
-   * @param {string} message - Error message
-   * @param {string} errorType - Error type
-   * @returns {ToolExecutionResult} Error result
-   */
-  createErrorResult(message, errorType = 'ToolError') {
-    return {
-      success: false,
-      duration: 0, // Will be set by BaseTool
-      output: null,
-      errors: [message],
-      metadata: { errorType },
-    };
-  },
-
-  /**
-   * Validate required parameters
-   * @param {Object} _params - Parameters object
-   * @param {Array<string>} _required - Required parameter names
-   * @throws {Error} If required parameters are missing
-   */
-  validateRequired(_params, _required) {
-    const missing = _required.filter((key) => !_params[key]);
-    if (missing.length > 0) {
-      throw new Error(`Missing required parameters: ${missing.join(', ')}`);
-    }
-  },
-};
-
-module.exports = {
-  BaseTool,
-  ValidationTool,
-  QualityGateTool,
-  SecurityTool,
-  ToolUtils,
-};

package/dist/tool-loader.js

@@ -1,303 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview CAWS Tool Loader - Dynamic tool discovery and loading system
- * Provides secure, sandboxed loading of tools from apps/tools/caws/ directory
- * @author @darianrosebrook
- */
-
-const fs = require('fs');
-const path = require('path');
-const { EventEmitter } = require('events');
-const { setTimeout, clearTimeout } = require('timers');
-const { safeAsync } = require('./error-handler');
-
-/**
- * Tool Loader - Discovers, validates, and loads CAWS tools dynamically
- * @extends EventEmitter
- */
-class ToolLoader extends EventEmitter {
-  constructor(options = {}) {
-    super();
-    // Check new location first, fall back to legacy location
-    const newToolsDir = path.join(process.cwd(), '.caws/tools');
-    const legacyToolsDir = path.join(process.cwd(), 'apps/tools/caws');
-    const defaultToolsDir = fs.existsSync(newToolsDir) ? newToolsDir : legacyToolsDir;
-
-    this.options = {
-      toolsDir: options.toolsDir || defaultToolsDir,
-      cacheEnabled: options.cacheEnabled !== false,
-      timeout: options.timeout || 10000,
-      maxTools: options.maxTools || 50,
-      ...options,
-    };
-
-    this.loadedTools = new Map();
-    this.discoveredTools = new Set();
-    this.loadingState = 'idle'; // idle, discovering, loading, ready, error
-  }
-
-  /**
-   * Discover available tools in the tools directory
-   * @returns {Promise<Array<string>>} Array of tool file paths
-   */
-  async discoverTools() {
-    return safeAsync(async () => {
-      this.loadingState = 'discovering';
-      this.emit('discovery:start');
-
-      // Check if tools directory exists
-      if (!fs.existsSync(this.options.toolsDir)) {
-        this.emit('discovery:complete', { tools: [], reason: 'directory_not_found' });
-        this.loadingState = 'ready';
-        return [];
-      }
-
-      // Read directory contents
-      const files = await fs.promises.readdir(this.options.toolsDir);
-
-      // Filter for valid tool files
-      const toolFiles = files
-        .filter((file) => {
-          // Must be .js file
-          if (!file.endsWith('.js')) return false;
-
-          // Must not be hidden or backup file
-          if (file.startsWith('.') || file.includes('.backup')) return false;
-
-          // Must not be test file (unless explicitly allowed)
-          if (file.includes('.test.') && !this.options.includeTests) return false;
-
-          return true;
-        })
-        .map((file) => path.join(this.options.toolsDir, file))
-        .filter((filePath) => {
-          // Validate file exists and is readable
-          try {
-            const stats = fs.statSync(filePath);
-            return stats.isFile() && stats.size > 0 && stats.size < 1024 * 1024; // < 1MB
-          } catch (error) {
-            this.emit('discovery:warning', { file: filePath, error: error.message });
-            return false;
-          }
-        })
-        .slice(0, this.options.maxTools); // Limit number of tools
-
-      this.discoveredTools = new Set(toolFiles);
-      this.emit('discovery:complete', { tools: toolFiles, count: toolFiles.length });
-      this.loadingState = 'idle';
-
-      return toolFiles;
-    }, 'Tool discovery failed');
-  }
-
-  /**
-   * Load a specific tool module
-   * @param {string} toolPath - Path to tool file
-   * @returns {Promise<Object>} Loaded tool module
-   */
-  async loadTool(toolPath) {
-    return safeAsync(async () => {
-      const toolId = path.basename(toolPath, '.js');
-
-      // Check cache first
-      if (this.loadedTools.has(toolId) && this.options.cacheEnabled) {
-        return this.loadedTools.get(toolId);
-      }
-
-      this.emit('tool:loading', { id: toolId, path: toolPath });
-
-      // Validate tool file before loading
-      await this.validateToolFile(toolPath);
-
-      // Load the module with timeout
-      const toolModule = await this.loadModuleWithTimeout(toolPath);
-
-      // Validate tool interface
-      await this.validateToolInterface(toolModule, toolId);
-
-      // Cache the loaded tool
-      const tool = {
-        module: toolModule,
-        path: toolPath,
-        loadedAt: new Date(),
-        metadata: toolModule.getMetadata ? toolModule.getMetadata() : {},
-      };
-
-      this.loadedTools.set(toolId, tool);
-      this.emit('tool:loaded', { id: toolId, metadata: tool.metadata });
-
-      return tool;
-    }, 'Tool loading failed');
-  }
-
-  /**
-   * Load all discovered tools
-   * @returns {Promise<Map<string, Object>>} Map of loaded tools
-   */
-  async loadAllTools() {
-    this.loadingState = 'loading';
-    this.emit('loading:start');
-
-    const toolPaths = await this.discoverTools();
-    const results = new Map();
-
-    for (const toolPath of toolPaths) {
-      try {
-        const tool = await this.loadTool(toolPath);
-        results.set(path.basename(toolPath, '.js'), tool);
-      } catch (error) {
-        // Log error but continue loading other tools
-        this.emit('loading:warning', { path: toolPath, error: error.message });
-      }
-    }
-
-    this.loadingState = 'ready';
-    this.emit('loading:complete', { loaded: results.size, total: toolPaths.length });
-
-    return results;
-  }
-
-  /**
-   * Get a loaded tool by ID
-   * @param {string} toolId - Tool identifier
-   * @returns {Object|null} Tool object or null if not found
-   */
-  getTool(toolId) {
-    return this.loadedTools.get(toolId) || null;
-  }
-
-  /**
-   * Get all loaded tools
-   * @returns {Map<string, Object>} Map of loaded tools
-   */
-  getAllTools() {
-    return new Map(this.loadedTools);
-  }
-
-  /**
-   * Unload a tool (remove from cache)
-   * @param {string} toolId - Tool identifier
-   * @returns {boolean} True if tool was unloaded
-   */
-  unloadTool(toolId) {
-    const unloaded = this.loadedTools.delete(toolId);
-    if (unloaded) {
-      this.emit('tool:unloaded', { id: toolId });
-    }
-    return unloaded;
-  }
-
-  /**
-   * Validate tool file before loading
-   * @private
-   * @param {string} toolPath - Path to tool file
-   */
-  async validateToolFile(toolPath) {
-    // Basic file validation
-    const stats = await fs.promises.stat(toolPath);
-    if (stats.size === 0) {
-      throw new Error('Tool file is empty');
-    }
-
-    if (stats.size > 1024 * 1024) {
-      // 1MB limit
-      throw new Error('Tool file too large (>1MB)');
-    }
-
-    // Read first few lines to check for shebang and basic structure
-    const fd = await fs.promises.open(toolPath, 'r');
-    try {
-      const buffer = Buffer.alloc(512);
-      const { bytesRead } = await fd.read(buffer, 0, 512, 0);
-      const content = buffer.toString('utf8', 0, bytesRead);
-
-      // Check for shebang
-      if (!content.startsWith('#!/usr/bin/env node') && !content.startsWith('#!')) {
-        throw new Error('Tool file missing shebang');
-      }
-
-      // Basic syntax check - look for module.exports or ES modules
-      const hasExports = content.includes('module.exports') || content.includes('export ');
-      if (!hasExports) {
-        throw new Error('Tool file does not export anything');
-      }
-    } finally {
-      await fd.close();
-    }
-  }
-
-  /**
-   * Load module with timeout protection
-   * @private
-   * @param {string} toolPath - Path to tool file
-   */
-  async loadModuleWithTimeout(toolPath) {
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(new Error(`Tool loading timeout after ${this.options.timeout}ms`));
-      }, this.options.timeout);
-
-      try {
-        // Clear require cache to ensure fresh load
-        delete require.cache[require.resolve(toolPath)];
-
-        const module = require(toolPath);
-        clearTimeout(timeout);
-        resolve(module);
-      } catch (error) {
-        clearTimeout(timeout);
-        reject(error);
-      }
-    });
-  }
-
-  /**
-   * Validate tool interface compliance
-   * @private
-   * @param {Object} toolModule - Loaded tool module
-   * @param {string} toolId - Tool identifier
-   */
-  async validateToolInterface(toolModule, toolId) {
-    const requiredMethods = ['execute', 'getMetadata'];
-
-    for (const method of requiredMethods) {
-      if (typeof toolModule[method] !== 'function') {
-        throw new Error(`Tool ${toolId} missing required method: ${method}`);
-      }
-    }
-
-    // Validate metadata structure
-    if (toolModule.getMetadata) {
-      const metadata = toolModule.getMetadata();
-      const requiredFields = ['id', 'name', 'version'];
-
-      for (const field of requiredFields) {
-        if (!metadata[field]) {
-          throw new Error(`Tool ${toolId} metadata missing required field: ${field}`);
-        }
-      }
-
-      // Validate metadata types
-      if (typeof metadata.id !== 'string' || typeof metadata.name !== 'string') {
-        throw new Error(`Tool ${toolId} metadata has invalid types`);
-      }
-    }
-  }
-
-  /**
-   * Get loader statistics
-   * @returns {Object} Statistics object
-   */
-  getStats() {
-    return {
-      discovered: this.discoveredTools.size,
-      loaded: this.loadedTools.size,
-      state: this.loadingState,
-      cacheEnabled: this.options.cacheEnabled,
-      toolsDir: this.options.toolsDir,
-    };
-  }
-}
-
-module.exports = ToolLoader;