@paths.design/caws-cli 3.1.0 → 3.2.0

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,
+};

package/dist/generators/working-spec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate working spec YAML with user input
+ * @param {Object} answers - User responses
+ * @returns {string} - Generated YAML content
+ */
+export function generateWorkingSpec(answers: any): string;
+/**
+ * Validate generated working spec against JSON schema
+ * @param {string} specContent - YAML spec content
+ * @param {Object} answers - User responses for error context
+ */
+export function validateGeneratedSpec(specContent: string, _answers: any): void;
+//# sourceMappingURL=working-spec.d.ts.map

package/dist/generators/working-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-spec.d.ts","sourceRoot":"","sources":["../../src/generators/working-spec.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,mDAFa,MAAM,CAqJlB;AAED;;;;GAIG;AACH,mDAHW,MAAM,uBA8BhB"}

package/dist/generators/working-spec.js

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Working Spec Generation Utilities
+ * Functions for generating and validating CAWS working specifications
+ * @author @darianrosebrook
+ */
+
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+
+// Import validation utilities
+const { validateWorkingSpec } = require('../validation/spec-validation');
+
+/**
+ * Generate working spec YAML with user input
+ * @param {Object} answers - User responses
+ * @returns {string} - Generated YAML content
+ */
+function generateWorkingSpec(answers) {
+  const template = {
+    id: answers.projectId,
+    title: answers.projectTitle,
+    risk_tier: answers.riskTier,
+    mode: answers.projectMode,
+    change_budget: {
+      max_files: answers.maxFiles,
+      max_loc: answers.maxLoc,
+    },
+    blast_radius: {
+      modules: answers.blastModules
+        .split(',')
+        .map((m) => m.trim())
+        .filter((m) => m),
+      data_migration: answers.dataMigration,
+    },
+    operational_rollback_slo: answers.rollbackSlo,
+    threats: (answers.projectThreats || '')
+      .split('\n')
+      .map((t) => t.trim())
+      .filter((t) => t && !t.startsWith('-') === false), // Allow lines starting with -
+    scope: {
+      in: (answers.scopeIn || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s),
+      out: (answers.scopeOut || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s),
+    },
+    invariants: (answers.projectInvariants || '')
+      .split('\n')
+      .map((i) => i.trim())
+      .filter((i) => i),
+    acceptance: answers.acceptanceCriteria
+      .split('\n')
+      .filter((a) => a.trim())
+      .map((criteria, index) => {
+        const id = `A${index + 1}`;
+        const upperCriteria = criteria.toUpperCase();
+
+        // Try different variations of the format
+        let given = '';
+        let when = '';
+        let then = '';
+
+        if (
+          upperCriteria.includes('GIVEN') &&
+          upperCriteria.includes('WHEN') &&
+          upperCriteria.includes('THEN')
+        ) {
+          given = criteria.split(/WHEN/i)[0]?.replace(/GIVEN/i, '').trim() || '';
+          const whenThen = criteria.split(/WHEN/i)[1];
+          when = whenThen?.split(/THEN/i)[0]?.trim() || '';
+          then = whenThen?.split(/THEN/i)[1]?.trim() || '';
+        } else {
+          // Fallback: just split by lines and create simple criteria
+          given = 'Current system state';
+          when = criteria.replace(/^(GIVEN|WHEN|THEN)/i, '').trim();
+          then = 'Expected behavior occurs';
+        }
+
+        return {
+          id,
+          given: given || 'Current system state',
+          when: when || criteria,
+          then: then || 'Expected behavior occurs',
+        };
+      }),
+    non_functional: {
+      a11y: answers.a11yRequirements
+        .split(',')
+        .map((a) => a.trim())
+        .filter((a) => a),
+      perf: { api_p95_ms: answers.perfBudget },
+      security: answers.securityRequirements
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s),
+    },
+    contracts: [
+      {
+        type: answers.contractType,
+        path: answers.contractPath,
+      },
+    ],
+    observability: {
+      logs: answers.observabilityLogs
+        .split(',')
+        .map((l) => l.trim())
+        .filter((l) => l),
+      metrics: answers.observabilityMetrics
+        .split(',')
+        .map((m) => m.trim())
+        .filter((m) => m),
+      traces: answers.observabilityTraces
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t),
+    },
+    migrations: (answers.migrationPlan || '')
+      .split('\n')
+      .map((m) => m.trim())
+      .filter((m) => m),
+    rollback: (answers.rollbackPlan || '')
+      .split('\n')
+      .map((r) => r.trim())
+      .filter((r) => r),
+    human_override: answers.needsOverride
+      ? {
+          enabled: true,
+          approver: answers.overrideApprover,
+          rationale: answers.overrideRationale,
+          waived_gates: answers.waivedGates,
+          approved_at: new Date().toISOString(),
+          expires_at: new Date(
+            Date.now() + answers.overrideExpiresDays * 24 * 60 * 60 * 1000
+          ).toISOString(),
+        }
+      : undefined,
+    experimental_mode: answers.isExperimental
+      ? {
+          enabled: true,
+          rationale: answers.experimentalRationale,
+          expires_at: new Date(
+            Date.now() + answers.experimentalExpiresDays * 24 * 60 * 60 * 1000
+          ).toISOString(),
+          sandbox_location: answers.experimentalSandbox,
+        }
+      : undefined,
+    ai_assessment: {
+      confidence_level: answers.aiConfidence,
+      uncertainty_areas: answers.uncertaintyAreas
+        .split(',')
+        .map((a) => a.trim())
+        .filter((a) => a),
+      complexity_factors: answers.complexityFactors
+        .split(',')
+        .map((f) => f.trim())
+        .filter((f) => f),
+      risk_factors: [], // Could be populated by AI analysis
+    },
+  };
+
+  return yaml.dump(template, { indent: 2 });
+}
+
+/**
+ * Validate generated working spec against JSON schema
+ * @param {string} specContent - YAML spec content
+ * @param {Object} answers - User responses for error context
+ */
+function validateGeneratedSpec(specContent, _answers) {
+  try {
+    const spec = yaml.load(specContent);
+
+    const isValid = validateWorkingSpec(spec);
+
+    if (!isValid) {
+      console.error(chalk.red('❌ Generated working spec failed validation:'));
+      validateWorkingSpec.errors.forEach((error) => {
+        console.error(`   - ${error.instancePath || 'root'}: ${error.message}`);
+      });
+
+      // Provide helpful guidance
+      console.log(chalk.blue('\n💡 Validation Tips:'));
+      console.log('   - Ensure risk_tier is 1, 2, or 3');
+      console.log('   - Check that scope.in is not empty');
+      console.log('   - Verify invariants and acceptance criteria are provided');
+      console.log('   - For tier 1 and 2, ensure contracts are specified');
+
+      process.exit(1);
+    }
+
+    console.log(chalk.green('✅ Generated working spec passed validation'));
+  } catch (error) {
+    console.error(chalk.red('❌ Error validating working spec:'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  generateWorkingSpec,
+  validateGeneratedSpec,
+};

package/dist/index.d.ts

@@ -1,14 +1,5 @@
 #!/usr/bin/env node
-/**
- * Generate working spec YAML with user input
- * @param {Object} answers - User responses
- * @returns {string} - Generated YAML content
- */
-export function generateWorkingSpec(answers: any): string;
-/**
- * Validate generated working spec against JSON schema
- * @param {string} specContent - YAML spec content
- * @param {Object} answers - User responses for error context
- */
-export function validateGeneratedSpec(specContent: string, _answers: any): void;
+import { generateWorkingSpec } from "./generators/working-spec";
+import { validateGeneratedSpec } from "./generators/working-spec";
+export { generateWorkingSpec, validateGeneratedSpec };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":";AAg5BA;;;;GAIG;AACH,mDAFa,MAAM,CAqJlB;AAED;;;;GAIG;AACH,mDAHW,MAAM,uBA8BhB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":""}