@paths.design/caws-cli 3.0.0 → 3.1.1

package/dist/tool-interface.d.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * Standard tool execution result
+ */
+export type ToolExecutionResult = {
+    /**
+     * - Whether execution succeeded
+     */
+    success: boolean;
+    /**
+     * - Execution duration in milliseconds
+     */
+    duration: number;
+    /**
+     * - Tool-specific output data
+     */
+    output: any;
+    /**
+     * - Error messages if execution failed
+     */
+    errors: Array<string>;
+    /**
+     * - Additional execution metadata
+     */
+    metadata: any;
+};
+/**
+ * Tool metadata structure
+ */
+export type ToolMetadata = {
+    /**
+     * - Unique tool identifier
+     */
+    id: string;
+    /**
+     * - Human-readable tool name
+     */
+    name: string;
+    /**
+     * - Tool version (semver)
+     */
+    version: string;
+    /**
+     * - Tool description
+     */
+    description: string;
+    /**
+     * - Tool capabilities (e.g., ['validation', 'security'])
+     */
+    capabilities: Array<string>;
+    /**
+     * - Tool author
+     */
+    author: string;
+    /**
+     * - Tool license
+     */
+    license: string;
+    /**
+     * - Required Node.js dependencies
+     */
+    dependencies: Array<string>;
+};
+/**
+ * Tool execution context
+ */
+export type ToolExecutionContext = {
+    /**
+     * - Current working directory
+     */
+    workingDirectory: string;
+    /**
+     * - Environment variables
+     */
+    environment: any;
+    /**
+     * - CAWS configuration
+     */
+    config: any;
+    /**
+     * - Current working specification
+     */
+    workingSpec: any;
+    /**
+     * - Execution timeout in milliseconds
+     */
+    timeout: number;
+};
+/**
+ * @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
+ */
+export class BaseTool {
+    metadata: ToolMetadata;
+    /**
+     * Execute the tool with given parameters
+     * @param {Object} parameters - Tool-specific execution parameters
+     * @param {ToolExecutionContext} context - Execution context
+     * @returns {Promise<ToolExecutionResult>} Execution result
+     */
+    execute(parameters?: any, context?: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Get tool metadata
+     * @returns {ToolMetadata} Tool metadata
+     */
+    getMetadata(): ToolMetadata;
+    /**
+     * Validate tool parameters
+     * @param {Object} _parameters - Parameters to validate
+     * @throws {Error} If parameters are invalid
+     */
+    validateParameters(_parameters: any): boolean;
+    /**
+     * Execute tool implementation (must be overridden by subclasses)
+     * @param {Object} _parameters - Tool parameters
+     * @param {ToolExecutionContext} _context - Execution context
+     * @returns {Promise<Object>} Tool-specific result
+     */
+    executeImpl(_parameters: any, _context: ToolExecutionContext): Promise<any>;
+    /**
+     * Normalize execution result to standard format
+     * @private
+     * @param {Object} result - Raw tool result
+     * @param {number} duration - Execution duration
+     * @returns {ToolExecutionResult} Normalized result
+     */
+    private normalizeResult;
+    /**
+     * Create error result
+     * @private
+     * @param {Error} error - Execution error
+     * @param {number} duration - Execution duration
+     * @returns {ToolExecutionResult} Error result
+     */
+    private createErrorResult;
+}
+/**
+ * Validation Tool base class - For tools that perform validation checks
+ */
+export class ValidationTool extends BaseTool {
+    capabilities: string[];
+    /**
+     * Execute validation
+     * @param {Object} parameters - Validation parameters
+     * @param {ToolExecutionContext} context - Execution context
+     * @returns {Promise<ToolExecutionResult>} Validation result
+     */
+    executeImpl(parameters: any, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Perform validation (must be implemented by subclasses)
+     * @param {Object} parameters - Validation parameters
+     * @param {ToolExecutionContext} context - Execution context
+     * @returns {Promise<Object>} Validation result
+     */
+    validate(_parameters: any, _context: any): Promise<any>;
+}
+/**
+ * Quality Gate Tool base class - For tools that enforce quality standards
+ */
+export class QualityGateTool extends ValidationTool {
+    /**
+     * Get quality gate thresholds for current tier
+     * @param {number} tier - Risk tier (1-3)
+     * @returns {Object} Threshold configuration
+     */
+    getTierThresholds(tier: number): any;
+}
+/**
+ * Security Tool base class - For tools that perform security checks
+ */
+export class SecurityTool extends ValidationTool {
+    /**
+     * Check for security violations
+     * @param {Object} target - Target to check (file, code, etc.)
+     * @returns {Promise<Array<Object>>} Array of security violations
+     */
+    checkSecurityViolations(target: any): Promise<Array<any>>;
+}
+export namespace ToolUtils {
+    /**
+     * Create standardized success result
+     * @param {Object} output - Tool output
+     * @param {Object} metadata - Additional metadata
+     * @returns {ToolExecutionResult} Success result
+     */
+    function createSuccessResult(output?: any, metadata?: any): ToolExecutionResult;
+    /**
+     * Create standardized error result
+     * @param {string} message - Error message
+     * @param {string} errorType - Error type
+     * @returns {ToolExecutionResult} Error result
+     */
+    function createErrorResult(message: string, errorType?: string): ToolExecutionResult;
+    /**
+     * Validate required parameters
+     * @param {Object} _params - Parameters object
+     * @param {Array<string>} _required - Required parameter names
+     * @throws {Error} If required parameters are missing
+     */
+    function validateRequired(_params: any, _required: Array<string>): void;
+}
+//# sourceMappingURL=tool-interface.d.ts.map

package/dist/tool-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-interface.d.ts","sourceRoot":"","sources":["../src/tool-interface.js"],"names":[],"mappings":";;;;;;;;aAWc,OAAO;;;;cACP,MAAM;;;;;;;;YAEN,KAAK,CAAC,MAAM,CAAC;;;;;;;;;;;;;QAOb,MAAM;;;;UACN,MAAM;;;;aACN,MAAM;;;;iBACN,MAAM;;;;kBACN,KAAK,CAAC,MAAM,CAAC;;;;YACb,MAAM;;;;aACN,MAAM;;;;kBACN,KAAK,CAAC,MAAM,CAAC;;;;;;;;;sBAMb,MAAM;;;;;;;;;;;;;;;;aAIN,MAAM;;AApCpB;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AACH;IAEI,uBAAkC;IAGpC;;;;;OAKG;IACH,oCAHW,oBAAoB,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAmBxC;IAED;;;OAGG;IACH,eAFa,YAAY,CAIxB;IAED;;;;OAIG;IACH,8CAGC;IAED;;;;;OAKG;IACH,wCAHW,oBAAoB,GAClB,OAAO,KAAQ,CAI3B;IAED;;;;;;OAMG;IACH,wBAQC;IAED;;;;;;OAMG;IACH,0BAWC;CACF;AAED;;GAEG;AACH;IAGI,uBAAkC;IAGpC;;;;;OAKG;IACH,sCAHW,oBAAoB,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAcxC;IAED;;;;;OAKG;IACH,2CAFa,OAAO,KAAQ,CAI3B;CACF;AAED;;GAEG;AACH;IAME;;;;OAIG;IACH,wBAHW,MAAM,OA6BhB;CACF;AAED;;GAEG;AACH;IAME;;;;OAIG;IACH,sCAFa,OAAO,CAAC,KAAK,KAAQ,CAAC,CAmBlC;CACF;;IAMC;;;;;OAKG;IACH,4DAFa,mBAAmB,CAU/B;IAED;;;;;OAKG;IACH,oCAJW,MAAM,cACN,MAAM,GACJ,mBAAmB,CAU/B;IAED;;;;;OAKG;IACH,mDAHW,KAAK,CAAC,MAAM,CAAC,QAQvB"}

package/dist/tool-interface.js

@@ -0,0 +1,314 @@
+#!/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.d.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+export = ToolLoader;
+/**
+ * Tool Loader - Discovers, validates, and loads CAWS tools dynamically
+ * @extends EventEmitter
+ */
+declare class ToolLoader extends EventEmitter<[never]> {
+    constructor(options?: {});
+    options: {
+        toolsDir: any;
+        cacheEnabled: boolean;
+        timeout: any;
+        maxTools: any;
+    };
+    loadedTools: Map<any, any>;
+    discoveredTools: Set<any>;
+    loadingState: string;
+    /**
+     * Discover available tools in the tools directory
+     * @returns {Promise<Array<string>>} Array of tool file paths
+     */
+    discoverTools(): Promise<Array<string>>;
+    /**
+     * Load a specific tool module
+     * @param {string} toolPath - Path to tool file
+     * @returns {Promise<Object>} Loaded tool module
+     */
+    loadTool(toolPath: string): Promise<any>;
+    /**
+     * Load all discovered tools
+     * @returns {Promise<Map<string, Object>>} Map of loaded tools
+     */
+    loadAllTools(): Promise<Map<string, any>>;
+    /**
+     * Get a loaded tool by ID
+     * @param {string} toolId - Tool identifier
+     * @returns {Object|null} Tool object or null if not found
+     */
+    getTool(toolId: string): any | null;
+    /**
+     * Get all loaded tools
+     * @returns {Map<string, Object>} Map of loaded tools
+     */
+    getAllTools(): Map<string, any>;
+    /**
+     * Unload a tool (remove from cache)
+     * @param {string} toolId - Tool identifier
+     * @returns {boolean} True if tool was unloaded
+     */
+    unloadTool(toolId: string): boolean;
+    /**
+     * Validate tool file before loading
+     * @private
+     * @param {string} toolPath - Path to tool file
+     */
+    private validateToolFile;
+    /**
+     * Load module with timeout protection
+     * @private
+     * @param {string} toolPath - Path to tool file
+     */
+    private loadModuleWithTimeout;
+    /**
+     * Validate tool interface compliance
+     * @private
+     * @param {Object} toolModule - Loaded tool module
+     * @param {string} toolId - Tool identifier
+     */
+    private validateToolInterface;
+    /**
+     * Get loader statistics
+     * @returns {Object} Statistics object
+     */
+    getStats(): any;
+}
+import { EventEmitter } from "events";
+//# sourceMappingURL=tool-loader.d.ts.map

package/dist/tool-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loader.d.ts","sourceRoot":"","sources":["../src/tool-loader.js"],"names":[],"mappings":";;AAcA;;;GAGG;AACH;IACE,0BAaC;IAXC;;;;;MAMC;IAED,2BAA4B;IAC5B,0BAAgC;IAChC,qBAA0B;IAG5B;;;OAGG;IACH,iBAFa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAkDlC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,KAAQ,CAmC3B;IAED;;;OAGG;IACH,gBAFa,OAAO,CAAC,GAAG,CAAC,MAAM,MAAS,CAAC,CAuBxC;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,MAAO,IAAI,CAIvB;IAED;;;OAGG;IACH,eAFa,GAAG,CAAC,MAAM,MAAS,CAI/B;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,CAQnB;IAED;;;;OAIG;IACH,yBAgCC;IAED;;;;OAIG;IACH,8BAkBC;IAED;;;;;OAKG;IACH,8BAyBC;IAED;;;OAGG;IACH,gBAQC;CACF"}