@paths.design/caws-cli 3.0.0 → 3.1.1

package/dist/commands/tool.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Tool Command Handler
+ * Handles tool execution commands for CAWS CLI
+ * @author @darianrosebrook
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+
+// Import tool system
+const ToolLoader = require('../tool-loader');
+const ToolValidator = require('../tool-validator');
+
+// Tool system state
+let toolLoader = null;
+let toolValidator = null;
+
+/**
+ * Initialize tool system
+ * @returns {Promise<ToolLoader|null>} Initialized tool loader or null if failed
+ */
+async function initializeToolSystem() {
+  if (toolLoader) return toolLoader;
+
+  try {
+    toolLoader = new ToolLoader({
+      toolsDir: path.join(process.cwd(), 'apps/tools/caws'),
+    });
+
+    toolValidator = new ToolValidator();
+
+    // Set up event listeners for tool system
+    toolLoader.on('discovery:complete', ({ tools: _tools, count }) => {
+      if (count > 0) {
+        console.log(chalk.blue(`🔧 Discovered ${count} tools`));
+      }
+    });
+
+    toolLoader.on('tool:loaded', ({ id, metadata }) => {
+      console.log(chalk.gray(`  ✓ Loaded tool: ${metadata.name} (${id})`));
+    });
+
+    toolLoader.on('tool:error', ({ id, error }) => {
+      console.warn(chalk.yellow(`⚠️  Failed to load tool ${id}: ${error}`));
+    });
+
+    // Auto-discover tools on initialization
+    await toolLoader.discoverTools();
+
+    return toolLoader;
+  } catch (error) {
+    console.warn(chalk.yellow('⚠️  Tool system initialization failed:'), error.message);
+    console.warn(chalk.blue('💡 Continuing without dynamic tools'));
+    return null;
+  }
+}
+
+/**
+ * Execute tool command handler
+ * @param {string} toolId - ID of the tool to execute
+ * @param {Object} options - Command options
+ */
+async function executeTool(toolId, options) {
+  try {
+    // Initialize tool system
+    const loader = await initializeToolSystem();
+
+    if (!loader) {
+      console.error(chalk.red('❌ Tool system not available'));
+      process.exit(1);
+    }
+
+    // Load all tools first
+    await loader.loadAllTools();
+    const tool = loader.getTool(toolId);
+
+    if (!tool) {
+      console.error(chalk.red(`❌ Tool '${toolId}' not found`));
+      console.log(chalk.blue('💡 Available tools:'));
+      const tools = loader.getAllTools();
+      for (const [id, t] of tools) {
+        console.log(`   - ${id}: ${t.metadata.name}`);
+      }
+      process.exit(1);
+    }
+
+    // Validate tool before execution
+    const validation = await toolValidator.validateTool(tool);
+    if (!validation.valid) {
+      console.error(chalk.red('❌ Tool validation failed:'));
+      validation.errors.forEach((error) => {
+        console.error(`   ${chalk.red('✗')} ${error}`);
+      });
+      process.exit(1);
+    }
+
+    // Parse parameters
+    let params = {};
+    if (options.params) {
+      try {
+        params = JSON.parse(options.params);
+      } catch (error) {
+        console.error(chalk.red('❌ Invalid JSON parameters:'), error.message);
+        process.exit(1);
+      }
+    }
+
+    console.log(chalk.blue(`🚀 Executing tool: ${tool.metadata.name}`));
+
+    // Execute tool
+    const result = await tool.module.execute(params, {
+      workingDirectory: process.cwd(),
+      timeout: options.timeout,
+    });
+
+    // Display results
+    if (result.success) {
+      console.log(chalk.green('✅ Tool execution successful'));
+      if (result.output && typeof result.output === 'object') {
+        console.log(chalk.gray('Output:'), JSON.stringify(result.output, null, 2));
+      }
+    } else {
+      console.error(chalk.red('❌ Tool execution failed'));
+      result.errors.forEach((error) => {
+        console.error(`   ${chalk.red('✗')} ${error}`);
+      });
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`❌ Error executing tool ${toolId}:`), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  initializeToolSystem,
+  executeTool,
+};

package/dist/commands/validate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate command handler
+ * @param {string} specFile - Path to spec file
+ * @param {Object} options - Command options
+ */
+export function validateCommand(specFile: string, options: any): Promise<void>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,0CAHW,MAAM,+BA2DhB"}

package/dist/commands/validate.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Validate Command Handler
+ * Handles validation commands for CAWS CLI
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+
+// Import validation functionality
+const { validateWorkingSpecWithSuggestions } = require('../validation/spec-validation');
+
+/**
+ * Validate command handler
+ * @param {string} specFile - Path to spec file
+ * @param {Object} options - Command options
+ */
+async function validateCommand(specFile, options) {
+  try {
+    let specPath = specFile || path.join('.caws', 'working-spec.yaml');
+
+    if (!fs.existsSync(specPath)) {
+      console.error(chalk.red(`❌ Spec file not found: ${specPath}`));
+      console.error(chalk.blue('💡 Run "caws init" first to create a working spec'));
+      process.exit(1);
+    }
+
+    const specContent = fs.readFileSync(specPath, 'utf8');
+    const spec = yaml.load(specContent);
+
+    console.log(chalk.cyan('🔍 Validating CAWS working spec...'));
+
+    const result = validateWorkingSpecWithSuggestions(spec, {
+      autoFix: options.autoFix,
+      suggestions: !options.quiet,
+      checkBudget: true,
+      projectRoot: path.dirname(specPath),
+    });
+
+    if (result.valid) {
+      console.log(chalk.green('✅ Working spec validation passed'));
+      if (!options.quiet) {
+        console.log(chalk.gray(`   Risk tier: ${spec.risk_tier}`));
+        console.log(chalk.gray(`   Mode: ${spec.mode}`));
+        if (spec.title) {
+          console.log(chalk.gray(`   Title: ${spec.title}`));
+        }
+      }
+    } else {
+      console.log(chalk.red('❌ Working spec validation failed'));
+
+      // Show errors
+      result.errors.forEach((error, index) => {
+        console.log(`   ${index + 1}. ${chalk.red(error.message)}`);
+        if (error.suggestion) {
+          console.log(`      ${chalk.blue('💡 ' + error.suggestion)}`);
+        }
+      });
+
+      // Show warnings
+      if (result.warnings && result.warnings.length > 0) {
+        console.log(chalk.yellow('\n⚠️  Warnings:'));
+        result.warnings.forEach((warning, index) => {
+          console.log(`   ${index + 1}. ${chalk.yellow(warning.message)}`);
+        });
+      }
+
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red('❌ Error during validation:'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  validateCommand,
+};

package/dist/config/index.d.ts

@@ -0,0 +1,29 @@
+import CLI_VERSION_1 = require("../../package.json");
+import CLI_VERSION = CLI_VERSION_1.version;
+/**
+ * Initialize global setup detection
+ * @returns {Object} Setup configuration
+ */
+export function initializeGlobalSetup(): any;
+/**
+ * Load provenance tools dynamically
+ * @returns {Object|null} Provenance tools or null if not available
+ */
+export function loadProvenanceTools(): any | null;
+/**
+ * Initialize language support tools
+ * @returns {Object|null} Language support tools or null if not available
+ */
+export function initializeLanguageSupport(): any | null;
+/**
+ * Get global CAWS setup
+ * @returns {Object} CAWS setup configuration
+ */
+export function getGlobalCAWSSetup(): any;
+/**
+ * Set global CAWS setup (for testing or override)
+ * @param {Object} setup - Setup configuration
+ */
+export function setGlobalCAWSSetup(setup: any): void;
+export { CLI_VERSION };
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.js"],"names":[],"mappings":";mCAakD,OAAO;AAOzD;;;GAGG;AACH,6CAkBC;AAED;;;GAGG;AACH,uCAFa,MAAO,IAAI,CAqBvB;AAED;;;GAGG;AACH,6CAFa,MAAO,IAAI,CAmCvB;AAED;;;GAGG;AACH,0CAEC;AAED;;;GAGG;AACH,qDAEC"}

package/dist/config/index.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview CAWS Configuration Module
+ * Global configuration and provenance tools management
+ * @author @darianrosebrook
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+
+// Import detection utilities
+const { detectCAWSSetup } = require('../utils/detection');
+
+// CLI version from package.json
+const CLI_VERSION = require('../../package.json').version;
+
+// Global state
+let provenanceTools = null;
+let cawsSetup = null;
+let languageSupport = null;
+
+/**
+ * Initialize global setup detection
+ * @returns {Object} Setup configuration
+ */
+function initializeGlobalSetup() {
+  if (cawsSetup) return cawsSetup;
+
+  try {
+    cawsSetup = detectCAWSSetup();
+  } catch (error) {
+    console.warn(chalk.yellow('⚠️  Failed to detect CAWS setup:'), error.message);
+    cawsSetup = {
+      type: 'unknown',
+      hasCAWSDir: false,
+      cawsDir: null,
+      capabilities: [],
+      hasTemplateDir: false,
+      templateDir: null,
+    };
+  }
+
+  return cawsSetup;
+}
+
+/**
+ * Load provenance tools dynamically
+ * @returns {Object|null} Provenance tools or null if not available
+ */
+function loadProvenanceTools() {
+  if (provenanceTools) return provenanceTools; // Already loaded
+
+  try {
+    const setup = cawsSetup || initializeGlobalSetup();
+    if (setup?.hasTemplateDir && setup?.templateDir) {
+      const { generateProvenance, saveProvenance } = require(
+        path.join(setup.templateDir, 'apps/tools/caws/provenance.js')
+      );
+      provenanceTools = { generateProvenance, saveProvenance };
+      console.log('✅ Loaded provenance tools from:', setup.templateDir);
+    }
+  } catch (error) {
+    // Fallback for environments without template
+    provenanceTools = null;
+    console.warn('⚠️  Provenance tools not available:', error.message);
+  }
+
+  return provenanceTools;
+}
+
+/**
+ * Initialize language support tools
+ * @returns {Object|null} Language support tools or null if not available
+ */
+function initializeLanguageSupport() {
+  if (languageSupport) return languageSupport;
+
+  try {
+    // Try multiple possible locations for language support
+    const possiblePaths = [
+      path.join(__dirname, '../../../caws-template/apps/tools/caws/language-support.js'),
+      path.join(__dirname, '../../../../caws-template/apps/tools/caws/language-support.js'),
+      path.join(process.cwd(), 'packages/caws-template/apps/tools/caws/language-support.js'),
+      path.join(process.cwd(), 'caws-template/apps/tools/caws/language-support.js'),
+    ];
+
+    for (const testPath of possiblePaths) {
+      try {
+        languageSupport = require(testPath);
+        // Only log if not running version command
+        if (!process.argv.includes('--version') && !process.argv.includes('-V')) {
+          console.log(`✅ Loaded language support from: ${testPath}`);
+        }
+        break;
+      } catch (pathError) {
+        // Continue to next path
+      }
+    }
+  } catch (error) {
+    console.warn(chalk.yellow('⚠️  Language support tools not available'));
+    console.warn(chalk.blue('💡 This may limit language-specific configuration features'));
+    console.warn(
+      chalk.blue('💡 For full functionality, ensure caws-template package is available')
+    );
+  }
+
+  return languageSupport;
+}
+
+/**
+ * Get global CAWS setup
+ * @returns {Object} CAWS setup configuration
+ */
+function getGlobalCAWSSetup() {
+  return cawsSetup || initializeGlobalSetup();
+}
+
+/**
+ * Set global CAWS setup (for testing or override)
+ * @param {Object} setup - Setup configuration
+ */
+function setGlobalCAWSSetup(setup) {
+  cawsSetup = setup;
+}
+
+module.exports = {
+  CLI_VERSION,
+  initializeGlobalSetup,
+  loadProvenanceTools,
+  initializeLanguageSupport,
+  getGlobalCAWSSetup,
+  setGlobalCAWSSetup,
+};

package/dist/error-handler.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Enhanced error class with category and recovery suggestions
+ */
+export class CAWSError extends Error {
+    constructor(message: any, category?: any, suggestions?: any[]);
+    category: any;
+    suggestions: any[];
+}
+export namespace ERROR_CATEGORIES {
+    let VALIDATION: string;
+    let PERMISSION: string;
+    let FILESYSTEM: string;
+    let NETWORK: string;
+    let CONFIGURATION: string;
+    let USER_INPUT: string;
+    let DEPENDENCY: string;
+    let UNKNOWN: string;
+}
+/**
+ * Get error category from error object or message
+ * @param {Error|string} error - Error object or message
+ * @returns {string} Error category
+ */
+export function getErrorCategory(error: Error | string): string;
+/**
+ * Wrap async operations with consistent error handling
+ * @param {Function} operation - Async operation to wrap
+ * @param {string} context - Context for error messages
+ * @returns {Promise<any>} Operation result or throws handled error
+ */
+export function safeAsync(operation: Function, context?: string): Promise<any>;
+/**
+ * Handle CLI errors with consistent formatting and user guidance
+ * @param {Error} error - Error to handle
+ * @param {boolean} exit - Whether to exit the process (default: true)
+ */
+export function handleCliError(error: Error, exit?: boolean): void;
+/**
+ * Validate required environment and dependencies
+ * @returns {Object} Validation result with any errors
+ */
+export function validateEnvironment(): any;
+/**
+ * Get recovery suggestions based on error category
+ * @param {Error} error - Original error
+ * @param {string} category - Error category
+ * @returns {string[]} Array of recovery suggestions
+ */
+export function getRecoverySuggestions(error: Error, category: string): string[];
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.js"],"names":[],"mappings":"AA0GA;;GAEG;AACH;IACE,+DAKC;IAFC,cAAqD;IACrD,mBAA2F;CAE9F;;;;;;;;;;;AA9ED;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA+DlB;AAcD;;;;;GAKG;AACH,yDAHW,MAAM,GACJ,OAAO,CAAC,GAAG,CAAC,CAexB;AAkDD;;;;GAIG;AACH,sCAHW,KAAK,SACL,OAAO,QAyBjB;AAED;;;GAGG;AACH,2CAqBC;AAvGD;;;;;GAKG;AACH,8CAJW,KAAK,YACL,MAAM,GACJ,MAAM,EAAE,CA0CpB"}

package/dist/error-handler.js

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview CAWS CLI Error Handler - Centralized error handling utilities
+ * Provides consistent error categorization, formatting, and recovery suggestions
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Error categories for better user experience
+ */
+const ERROR_CATEGORIES = {
+  VALIDATION: 'validation',
+  PERMISSION: 'permission',
+  FILESYSTEM: 'filesystem',
+  NETWORK: 'network',
+  CONFIGURATION: 'configuration',
+  USER_INPUT: 'user_input',
+  DEPENDENCY: 'dependency',
+  UNKNOWN: 'unknown',
+};
+
+/**
+ * Error code mappings for common system errors
+ */
+const ERROR_CODES = {
+  EACCES: ERROR_CATEGORIES.PERMISSION,
+  EPERM: ERROR_CATEGORIES.PERMISSION,
+  ENOENT: ERROR_CATEGORIES.FILESYSTEM,
+  ENOTFOUND: ERROR_CATEGORIES.NETWORK,
+  ECONNREFUSED: ERROR_CATEGORIES.NETWORK,
+  ETIMEDOUT: ERROR_CATEGORIES.NETWORK,
+  ENOSPC: ERROR_CATEGORIES.FILESYSTEM,
+  EEXIST: ERROR_CATEGORIES.FILESYSTEM,
+  EISDIR: ERROR_CATEGORIES.FILESYSTEM,
+  ENOTDIR: ERROR_CATEGORIES.FILESYSTEM,
+};
+
+/**
+ * Get error category from error object or message
+ * @param {Error|string} error - Error object or message
+ * @returns {string} Error category
+ */
+function getErrorCategory(error) {
+  const errorMessage = typeof error === 'string' ? error : error.message;
+  const errorCode = typeof error === 'object' && error.code ? error.code : null;
+
+  // Check error codes first
+  if (errorCode && ERROR_CODES[errorCode]) {
+    return ERROR_CODES[errorCode];
+  }
+
+  // Check message patterns
+  const lowerMessage = errorMessage.toLowerCase();
+
+  if (
+    lowerMessage.includes('validation') ||
+    lowerMessage.includes('invalid') ||
+    lowerMessage.includes('required')
+  ) {
+    return ERROR_CATEGORIES.VALIDATION;
+  }
+
+  if (
+    lowerMessage.includes('permission') ||
+    lowerMessage.includes('access') ||
+    lowerMessage.includes('denied')
+  ) {
+    return ERROR_CATEGORIES.PERMISSION;
+  }
+
+  if (
+    lowerMessage.includes('file') ||
+    lowerMessage.includes('directory') ||
+    lowerMessage.includes('path')
+  ) {
+    return ERROR_CATEGORIES.FILESYSTEM;
+  }
+
+  if (
+    lowerMessage.includes('network') ||
+    lowerMessage.includes('connection') ||
+    lowerMessage.includes('timeout')
+  ) {
+    return ERROR_CATEGORIES.NETWORK;
+  }
+
+  if (
+    lowerMessage.includes('config') ||
+    lowerMessage.includes('setting') ||
+    lowerMessage.includes('option')
+  ) {
+    return ERROR_CATEGORIES.CONFIGURATION;
+  }
+
+  if (
+    lowerMessage.includes('input') ||
+    lowerMessage.includes('prompt') ||
+    lowerMessage.includes('answer')
+  ) {
+    return ERROR_CATEGORIES.USER_INPUT;
+  }
+
+  return ERROR_CATEGORIES.UNKNOWN;
+}
+
+/**
+ * Enhanced error class with category and recovery suggestions
+ */
+class CAWSError extends Error {
+  constructor(message, category = null, suggestions = []) {
+    super(message);
+    this.name = 'CAWSError';
+    this.category = category || getErrorCategory(message);
+    this.suggestions = Array.isArray(suggestions) ? suggestions : [suggestions].filter(Boolean);
+  }
+}
+
+/**
+ * Wrap async operations with consistent error handling
+ * @param {Function} operation - Async operation to wrap
+ * @param {string} context - Context for error messages
+ * @returns {Promise<any>} Operation result or throws handled error
+ */
+async function safeAsync(operation, context = '') {
+  try {
+    return await operation();
+  } catch (error) {
+    const category = getErrorCategory(error);
+    const enhancedError = new CAWSError(
+      `${context}: ${error.message}`,
+      category,
+      getRecoverySuggestions(error, category)
+    );
+    enhancedError.originalError = error;
+    throw enhancedError;
+  }
+}
+
+/**
+ * Get recovery suggestions based on error category
+ * @param {Error} error - Original error
+ * @param {string} category - Error category
+ * @returns {string[]} Array of recovery suggestions
+ */
+function getRecoverySuggestions(error, category) {
+  const suggestions = [];
+
+  switch (category) {
+    case ERROR_CATEGORIES.PERMISSION:
+      suggestions.push('Try running the command with elevated privileges (sudo)');
+      suggestions.push('Check file/directory permissions with `ls -la`');
+      break;
+
+    case ERROR_CATEGORIES.FILESYSTEM:
+      if (error.code === 'ENOENT') {
+        suggestions.push('Verify the file/directory path exists');
+        suggestions.push('Check for typos in file names');
+      } else if (error.code === 'EEXIST') {
+        suggestions.push('The file/directory already exists');
+        suggestions.push('Use a different name or remove the existing item');
+      }
+      break;
+
+    case ERROR_CATEGORIES.VALIDATION:
+      suggestions.push('Run `caws validate --suggestions` for detailed validation help');
+      suggestions.push('Check your working spec format against the documentation');
+      break;
+
+    case ERROR_CATEGORIES.CONFIGURATION:
+      suggestions.push('Run `caws init --interactive` to reconfigure your project');
+      suggestions.push('Check your .caws directory and configuration files');
+      break;
+
+    case ERROR_CATEGORIES.NETWORK:
+      suggestions.push('Check your internet connection');
+      suggestions.push('Verify the URL/service is accessible');
+      break;
+
+    default:
+      suggestions.push('Run the command with --help for usage information');
+      suggestions.push('Check the CAWS documentation at docs/README.md');
+  }
+
+  return suggestions;
+}
+
+/**
+ * Handle CLI errors with consistent formatting and user guidance
+ * @param {Error} error - Error to handle
+ * @param {boolean} exit - Whether to exit the process (default: true)
+ */
+function handleCliError(error, exit = true) {
+  const category = error.category || getErrorCategory(error);
+  const suggestions = error.suggestions || getRecoverySuggestions(error, category);
+
+  // Format error output
+  console.error(chalk.red(`\n❌ Error (${category}): ${error.message}`));
+
+  if (suggestions && suggestions.length > 0) {
+    console.error(chalk.yellow('\n💡 Suggestions:'));
+    suggestions.forEach((suggestion) => {
+      console.error(chalk.yellow(`   • ${suggestion}`));
+    });
+  }
+
+  console.error(
+    chalk.gray(
+      '\n📖 For more help, visit: https://github.com/Paths-Design/coding-agent-working-standard'
+    )
+  );
+
+  if (exit) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Validate required environment and dependencies
+ * @returns {Object} Validation result with any errors
+ */
+function validateEnvironment() {
+  const errors = [];
+  const warnings = [];
+
+  // Check Node.js version
+  const nodeVersion = process.versions.node;
+  const majorVersion = parseInt(nodeVersion.split('.')[0], 10);
+  if (majorVersion < 18) {
+    errors.push(`Node.js version ${nodeVersion} is not supported. Minimum required: 18.0.0`);
+  }
+
+  // Check if running in supported environment
+  if (!process.cwd()) {
+    errors.push('Unable to determine current working directory');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+module.exports = {
+  CAWSError,
+  ERROR_CATEGORIES,
+  getErrorCategory,
+  safeAsync,
+  handleCliError,
+  validateEnvironment,
+  getRecoverySuggestions,
+};