@paths.design/caws-cli 3.3.1 → 3.5.0

package/dist/commands/workflow.js

@@ -0,0 +1,243 @@
+/**
+ * CAWS Workflow Command
+ *
+ * Provides workflow-specific guidance for development tasks.
+ * Supports TDD, refactor, and feature development workflows.
+ *
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Workflow templates with steps and guidance
+ */
+const WORKFLOW_TEMPLATES = {
+  tdd: {
+    name: 'Test-Driven Development',
+    steps: [
+      'Define requirements and acceptance criteria',
+      'Write failing test',
+      'Implement minimal code to pass test',
+      'Run CAWS validation',
+      'Refactor while maintaining tests',
+      'Repeat for next requirement',
+    ],
+    guidance: {
+      1: 'Start by clearly defining what the code should do. Use CAWS working spec to document requirements.',
+      2: 'Write a test that captures the desired behavior but will initially fail.',
+      3: 'Implement only the minimal code needed to make the test pass.',
+      4: 'Run CAWS evaluation to ensure quality standards are maintained.',
+      5: 'Improve code structure while keeping all tests passing.',
+      6: 'Move to the next requirement and repeat the cycle.',
+    },
+    recommendations: {
+      1: ['caws evaluate --feedback-only', 'Ensure spec completeness'],
+      2: ['Write failing test first', 'caws validate for basic checks'],
+      3: ['Implement minimal solution', 'Run tests to verify'],
+      4: ['caws evaluate', 'Address any quality issues'],
+      5: ['Refactor safely', 'Re-run CAWS validation'],
+      6: ['caws iterate for next steps', 'Continue TDD cycle'],
+    },
+  },
+  refactor: {
+    name: 'Refactoring Workflow',
+    steps: [
+      'Establish baseline quality metrics',
+      'Apply refactoring changes',
+      'Run comprehensive validation',
+      'Address any quality gate failures',
+      'Document changes and rationale',
+    ],
+    guidance: {
+      1: 'Run CAWS evaluation to establish current quality baseline.',
+      2: 'Make your refactoring changes incrementally.',
+      3: 'Run full CAWS validation to ensure no quality degradation.',
+      4: 'Address any failing quality gates with waivers if necessary.',
+      5: 'Update documentation and provenance records.',
+    },
+    recommendations: {
+      1: ['caws evaluate', 'Establish quality baseline'],
+      2: ['Apply changes incrementally', 'caws validate frequently'],
+      3: ['caws evaluate', 'Full quality assessment'],
+      4: ['Create waivers if needed', 'Document rationale'],
+      5: ['Update provenance', 'caws provenance update'],
+    },
+  },
+  feature: {
+    name: 'Feature Development',
+    steps: [
+      'Create working specification',
+      'Design and plan implementation',
+      'Implement core functionality',
+      'Add comprehensive testing',
+      'Run full quality validation',
+      'Prepare for integration',
+    ],
+    guidance: {
+      1: 'Define clear requirements, acceptance criteria, and risk assessment.',
+      2: 'Break down the feature into manageable tasks.',
+      3: 'Implement core functionality with error handling.',
+      4: 'Add unit, integration, and contract tests.',
+      5: 'Run complete CAWS validation and address issues.',
+      6: 'Ensure documentation and provenance are complete.',
+    },
+    recommendations: {
+      1: ['caws init --interactive', 'Create comprehensive spec'],
+      2: ['caws iterate', 'Get implementation guidance'],
+      3: ['caws evaluate', 'Validate progress'],
+      4: ['Add comprehensive tests', 'Run test suite'],
+      5: ['caws validate', 'Final quality gates'],
+      6: ['caws provenance update', 'Prepare for integration'],
+    },
+  },
+};
+
+/**
+ * Generate workflow guidance
+ *
+ * @param {string} workflowType - Type of workflow (tdd, refactor, feature)
+ * @param {number} currentStep - Current step number (1-based)
+ * @param {object} context - Optional context information
+ * @returns {object} Workflow guidance
+ */
+function generateWorkflowGuidance(workflowType, currentStep, context = {}) {
+  const template = WORKFLOW_TEMPLATES[workflowType];
+
+  if (!template) {
+    return {
+      error: `Unknown workflow type: ${workflowType}`,
+      available_types: Object.keys(WORKFLOW_TEMPLATES),
+    };
+  }
+
+  const step = parseInt(currentStep, 10);
+  if (isNaN(step) || step < 1 || step > template.steps.length) {
+    return {
+      error: `Invalid step number: ${currentStep}. Must be between 1 and ${template.steps.length}`,
+      total_steps: template.steps.length,
+    };
+  }
+
+  const currentGuidance = template.guidance[step] || 'Continue with the next logical step.';
+  const nextStep = step < template.steps.length ? step + 1 : null;
+
+  return {
+    workflow_type: workflowType,
+    workflow_name: template.name,
+    current_step: step,
+    total_steps: template.steps.length,
+    step_description: template.steps[step - 1] || 'Unknown step',
+    guidance: currentGuidance,
+    next_step: nextStep,
+    next_step_description: nextStep ? template.steps[nextStep - 1] : null,
+    all_steps: template.steps,
+    caws_recommendations: template.recommendations[step] || ['caws evaluate'],
+    context: context.description || null,
+  };
+}
+
+/**
+ * Workflow command handler
+ *
+ * @param {string} workflowType - Type of workflow
+ * @param {object} options - Command options
+ */
+async function workflowCommand(workflowType, options = {}) {
+  try {
+    const step = parseInt(options.step || '1', 10);
+    let context = {};
+
+    // Parse context if provided
+    if (options.currentState) {
+      try {
+        context =
+          typeof options.currentState === 'string'
+            ? JSON.parse(options.currentState)
+            : options.currentState;
+      } catch (e) {
+        console.warn(chalk.yellow('⚠️  Invalid context JSON, ignoring'));
+      }
+    }
+
+    // Generate guidance
+    const guidance = generateWorkflowGuidance(workflowType, step, context);
+
+    // Handle errors
+    if (guidance.error) {
+      console.error(chalk.red(`\n❌ ${guidance.error}`));
+      if (guidance.available_types) {
+        console.log(chalk.blue('\n💡 Available workflow types:'));
+        guidance.available_types.forEach((type) => {
+          console.log(chalk.blue(`   • ${type}`));
+        });
+      }
+      if (guidance.total_steps) {
+        console.log(chalk.blue(`\n💡 Valid steps: 1-${guidance.total_steps}`));
+      }
+      process.exit(1);
+    }
+
+    // Display guidance
+    console.log(chalk.bold('\n🔄 CAWS Workflow Guidance\n'));
+    console.log('─'.repeat(60));
+    console.log(chalk.bold(`\nWorkflow: ${guidance.workflow_name} (${guidance.workflow_type})`));
+    console.log(
+      chalk.bold(
+        `Step ${guidance.current_step}/${guidance.total_steps}: ${guidance.step_description}`
+      )
+    );
+
+    if (guidance.context) {
+      console.log(chalk.gray(`\nContext: ${guidance.context}`));
+    }
+
+    console.log(chalk.bold('\n📋 Guidance:\n'));
+    console.log(`   ${guidance.guidance}`);
+
+    console.log(chalk.bold('\n✅ CAWS Recommendations:\n'));
+    guidance.caws_recommendations.forEach((rec) => {
+      console.log(chalk.blue(`   • ${rec}`));
+    });
+
+    // Show next step if available
+    if (guidance.next_step) {
+      console.log(chalk.bold('\n⏭️  Next Step:\n'));
+      console.log(chalk.gray(`   Step ${guidance.next_step}: ${guidance.next_step_description}`));
+      console.log(
+        chalk.gray(`\n   Run: caws workflow ${workflowType} --step ${guidance.next_step}`)
+      );
+    } else {
+      console.log(chalk.bold('\n🎉 Workflow Complete!\n'));
+      console.log(chalk.green('   All steps in this workflow have been completed.'));
+      console.log(chalk.blue('\n   💡 Run: caws evaluate to check final quality'));
+    }
+
+    // Show all steps for reference
+    console.log(chalk.bold('\n📊 All Steps:\n'));
+    guidance.all_steps.forEach((stepDesc, idx) => {
+      const stepNum = idx + 1;
+      const icon =
+        stepNum === guidance.current_step ? '▶️ ' : stepNum < guidance.current_step ? '✅ ' : '⬜ ';
+      const color =
+        stepNum === guidance.current_step
+          ? chalk.bold
+          : stepNum < guidance.current_step
+            ? chalk.green
+            : chalk.gray;
+      console.log(color(`   ${icon}${stepNum}. ${stepDesc}`));
+    });
+
+    console.log('\n' + '─'.repeat(60) + '\n');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Workflow guidance failed: ${error.message}`));
+    console.error(chalk.gray(error.stack));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  workflowCommand,
+  generateWorkflowGuidance,
+  WORKFLOW_TEMPLATES,
+};

package/dist/error-handler.d.ts

@@ -5,6 +5,8 @@ export class CAWSError extends Error {
     constructor(message: any, category?: any, suggestions?: any[]);
     category: any;
     suggestions: any[];
+    timestamp: Date;
+    executionTime: any;
 }
 export namespace ERROR_CATEGORIES {
     let VALIDATION: string;
@@ -16,6 +18,17 @@ export namespace ERROR_CATEGORIES {
     let DEPENDENCY: string;
     let UNKNOWN: string;
 }
+/**
+ * Execution timing utilities
+ */
+export class ExecutionTimer {
+    startTime: bigint;
+    endTime: bigint;
+    start(): void;
+    end(): number;
+    getDuration(): number;
+    formatDuration(): string;
+}
 /**
  * Get error category from error object or message
  * @param {Error|string} error - Error object or message
@@ -23,12 +36,21 @@ export namespace ERROR_CATEGORIES {
  */
 export function getErrorCategory(error: Error | string): string;
 /**
- * Wrap async operations with consistent error handling
+ * Wrap async operations with consistent error handling and timing
  * @param {Function} operation - Async operation to wrap
  * @param {string} context - Context for error messages
+ * @param {boolean} includeTiming - Whether to include timing in results
  * @returns {Promise<any>} Operation result or throws handled error
  */
-export function safeAsync(operation: Function, context?: string): Promise<any>;
+export function safeAsync(operation: Function, context?: string, includeTiming?: boolean): Promise<any>;
+/**
+ * Wrap sync operations with timing
+ * @param {Function} operation - Sync operation to wrap
+ * @param {string} context - Context for error messages
+ * @param {boolean} includeTiming - Whether to include timing in results
+ * @returns {any} Operation result or throws handled error
+ */
+export function safeSync(operation: Function, context?: string, includeTiming?: boolean): any;
 /**
  * Handle CLI errors with consistent formatting and user guidance
  * @param {Error} error - Error to handle
@@ -72,4 +94,71 @@ export const COMMAND_SUGGESTIONS: {
     'template not found': () => string[];
     'not a caws project': () => string[];
 };
+/**
+ * JSON output formatter for programmatic use
+ * @param {Object} data - Data to format as JSON
+ * @param {boolean} pretty - Whether to pretty-print (default: true)
+ */
+export function formatJsonOutput(data: any, pretty?: boolean): string;
+/**
+ * Check if user requested JSON output
+ * @returns {boolean} True if --json flag is present
+ */
+export function isJsonOutput(): boolean;
+/**
+ * Output data in appropriate format (JSON or human-readable)
+ * @param {Object} data - Data to output
+ * @param {boolean} success - Whether this is a success response
+ */
+export function outputResult(data: any, success?: boolean): any;
+/**
+ * Troubleshooting guide system
+ */
+export const TROUBLESHOOTING_GUIDES: {
+    'coverage-report-not-found': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'mutation-report-not-found': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'working-spec-validation': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'monorepo-detection': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+};
+/**
+ * Get troubleshooting guide for a specific issue
+ * @param {string} issueKey - Key for the troubleshooting guide
+ * @returns {Object|null} Troubleshooting guide or null if not found
+ */
+export function getTroubleshootingGuide(issueKey: string): any | null;
+/**
+ * Get all available troubleshooting guides
+ * @returns {Object} All troubleshooting guides
+ */
+export function getAllTroubleshootingGuides(): any;
+/**
+ * Suggest troubleshooting guide based on error message
+ * @param {string} errorMessage - Error message to analyze
+ * @returns {string|null} Issue key if match found, null otherwise
+ */
+export function suggestTroubleshootingGuide(errorMessage: string): string | null;
 //# sourceMappingURL=error-handler.d.ts.map

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

@@ -1 +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;AA4ND;;;;;GAKG;AACH,sCAJW,KAAK,wBAEL,OAAO,QAsBjB;AAED;;;GAGG;AACH,2CAqBC;AAtJD;;;;;;GAMG;AACH,8CALW,KAAK,YACL,MAAM,kBAEJ,MAAM,EAAE,CAwDpB;AAED;;;;;GAKG;AACH,+CAJW,MAAM,kBAEJ,MAAM,CA4BlB;AAxJD;;;;;GAKG;AACH,0CAJW,MAAM,iBACN,MAAM,EAAE,GACN,MAAM,GAAC,IAAI,CAiBvB;AArFD;;GAEG;AACH;;;;;EA2DE"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.js"],"names":[],"mappings":"AA0GA;;GAEG;AACH;IACE,+DAOC;IAJC,cAAqD;IACrD,mBAA2F;IAC3F,gBAA2B;IAC3B,mBAAyB;CAE5B;;;;;;;;;;;AAED;;GAEG;AACH;IAEI,kBAAqB;IACrB,gBAAmB;IAGrB,cAEC;IAED,cAGC;IAED,sBAIC;IAED,yBAMC;CACF;AAjHD;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA+DlB;AAiDD;;;;;;GAMG;AACH,yDAJW,MAAM,kBACN,OAAO,GACL,OAAO,CAAC,GAAG,CAAC,CA8BxB;AAED;;;;;;GAMG;AACH,wDAJW,MAAM,kBACN,OAAO,GACL,GAAG,CA8Bf;AAgSD;;;;;GAKG;AACH,sCAJW,KAAK,wBAEL,OAAO,QAmDjB;AA0JD;;;GAGG;AACH,2CAqBC;AAnXD;;;;;;GAMG;AACH,8CALW,KAAK,YACL,MAAM,kBAEJ,MAAM,EAAE,CAwDpB;AAED;;;;;GAKG;AACH,+CAJW,MAAM,kBAEJ,MAAM,CA4BlB;AAxJD;;;;;GAKG;AACH,0CAJW,MAAM,iBACN,MAAM,EAAE,GACN,MAAM,GAAC,IAAI,CAiBvB;AAjHD;;GAEG;AACH;;;;;EAuFE;AA4JF;;;;GAIG;AACH,qDAFW,OAAO,UAIjB;AAED;;;GAGG;AACH,gCAFa,OAAO,CAQnB;AAED;;;;GAIG;AACH,kDAFW,OAAO,OAcjB;AA2DD;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0GE;AAEF;;;;GAIG;AACH,kDAHW,MAAM,GACJ,MAAO,IAAI,CAIvB;AAED;;;GAGG;AACH,mDAEC;AAED;;;;GAIG;AACH,0DAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB"}