@paths.design/caws-cli 3.3.1 → 3.5.0

package/dist/commands/iterate.js

@@ -0,0 +1,341 @@
+/**
+ * CAWS Iterate Command
+ *
+ * Provides iterative development guidance based on current progress
+ * and working spec state.
+ *
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const { initializeGlobalSetup } = require('../config');
+
+/**
+ * Iterate command handler
+ *
+ * @param {string} specFile - Path to working spec file
+ * @param {object} options - Command options
+ */
+async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}) {
+  try {
+    console.log('🔍 Detecting CAWS setup...');
+    const setup = initializeGlobalSetup();
+
+    if (setup.hasWorkingSpec) {
+      console.log(`✅ Detected ${setup.setupType} CAWS setup`);
+      console.log(`   Capabilities: ${setup.capabilities.join(', ')}`);
+    }
+
+    // Load working spec
+    const specPath = path.isAbsolute(specFile) ? specFile : path.join(process.cwd(), specFile);
+
+    if (!fs.existsSync(specPath)) {
+      console.error(chalk.red(`\n❌ Working spec not found: ${specFile}`));
+      console.error(chalk.yellow('💡 Run: caws init to create a working spec'));
+      process.exit(1);
+    }
+
+    const specContent = fs.readFileSync(specPath, 'utf8');
+    const spec = yaml.load(specContent);
+
+    // Parse current state from options
+    const currentState = options.currentState ? JSON.parse(options.currentState) : {};
+    const stateDescription = currentState.description || 'Starting implementation';
+
+    console.log(chalk.blue('\n🔄 Iterative Development Guidance\n'));
+    console.log('─'.repeat(60));
+    console.log(chalk.bold(`\nProject: ${spec.title}`));
+    console.log(`ID: ${spec.id} | Tier: ${spec.risk_tier} | Mode: ${spec.mode}`);
+    console.log(`Current State: ${stateDescription}\n`);
+
+    // Analyze progress based on mode
+    const guidance = generateGuidance(spec, currentState, options);
+
+    // Display guidance
+    console.log(chalk.blue('📋 Current Phase:\n'));
+    console.log(`   ${guidance.phase}\n`);
+
+    console.log(chalk.blue('✅ Completed Steps:\n'));
+    guidance.completed.forEach((step) => {
+      console.log(chalk.green(`   ✓ ${step}`));
+    });
+
+    console.log(chalk.blue('\n🎯 Next Actions:\n'));
+    guidance.nextActions.forEach((action, index) => {
+      console.log(chalk.yellow(`   ${index + 1}. ${action}`));
+    });
+
+    if (guidance.blockers.length > 0) {
+      console.log(chalk.red('\n⚠️  Blockers:\n'));
+      guidance.blockers.forEach((blocker) => {
+        console.log(chalk.red(`   ⚠️  ${blocker}`));
+      });
+    }
+
+    console.log(chalk.blue('\n💡 Recommendations:\n'));
+    guidance.recommendations.forEach((rec) => {
+      console.log(chalk.blue(`   • ${rec}`));
+    });
+
+    // Acceptance criteria checklist with detailed progress
+    if (spec.acceptance && spec.acceptance.length > 0) {
+      console.log(chalk.blue('\n📊 Acceptance Criteria Progress:\n'));
+
+      let totalTestsWritten = 0;
+      let totalTestsPassing = 0;
+      let totalCoverage = 0;
+      let criteriaWithProgress = 0;
+
+      spec.acceptance.forEach((criterion, _index) => {
+        // Support both old format (boolean completed) and new format (detailed progress)
+        let status = '⬜';
+        let progressInfo = '';
+
+        if (criterion.status) {
+          // New detailed format
+          switch (criterion.status) {
+            case 'completed':
+              status = '✅';
+              break;
+            case 'in_progress':
+              status = '🔄';
+              break;
+            case 'pending':
+            default:
+              status = '⬜';
+              break;
+          }
+
+          // Show detailed progress if available
+          if (criterion.tests) {
+            const written = criterion.tests.written || 0;
+            const passing = criterion.tests.passing || 0;
+            progressInfo = ` (${passing}/${written} tests passing`;
+
+            if (criterion.coverage !== undefined) {
+              progressInfo += `, ${criterion.coverage.toFixed(1)}% coverage`;
+            }
+            progressInfo += ')';
+
+            totalTestsWritten += written;
+            totalTestsPassing += passing;
+            if (criterion.coverage !== undefined) {
+              totalCoverage += criterion.coverage;
+              criteriaWithProgress++;
+            }
+          }
+
+          if (criterion.last_updated) {
+            const lastUpdate = new Date(criterion.last_updated).toLocaleDateString();
+            progressInfo += ` - updated ${lastUpdate}`;
+          }
+        } else if (criterion.completed) {
+          // Backward compatibility with old boolean format
+          status = '✅';
+        }
+
+        console.log(`   ${status} ${criterion.id}: ${criterion.then}`);
+        if (progressInfo) {
+          console.log(chalk.gray(`      ${progressInfo}`));
+        }
+      });
+
+      // Calculate overall progress
+      const completed = spec.acceptance.filter(
+        (a) => a.status === 'completed' || a.completed
+      ).length;
+      const inProgress = spec.acceptance.filter((a) => a.status === 'in_progress').length;
+      const total = spec.acceptance.length;
+      const completionProgress = Math.round((completed / total) * 100);
+
+      console.log(
+        chalk.bold(
+          `\n   Overall Progress: ${completed}/${total} completed (${completionProgress}%)`
+        )
+      );
+      if (inProgress > 0) {
+        console.log(chalk.yellow(`   In Progress: ${inProgress} criteria`));
+      }
+
+      // Show test progress if available
+      if (totalTestsWritten > 0) {
+        const testProgress = Math.round((totalTestsPassing / totalTestsWritten) * 100);
+        console.log(
+          `   Test Progress: ${totalTestsPassing}/${totalTestsWritten} tests passing (${testProgress}%)`
+        );
+      }
+
+      // Show coverage progress if available
+      if (criteriaWithProgress > 0) {
+        const avgCoverage = totalCoverage / criteriaWithProgress;
+        console.log(`   Average Coverage: ${avgCoverage.toFixed(1)}%`);
+      }
+    }
+
+    // Quality gates reminder
+    console.log(chalk.blue('\n🔒 Quality Gates (Risk Tier ' + spec.risk_tier + '):\n'));
+    const gates = getQualityGates(spec.risk_tier);
+    gates.forEach((gate) => {
+      console.log(`   □ ${gate}`);
+    });
+
+    console.log(chalk.blue('\n📚 Useful Commands:\n'));
+    console.log('   caws evaluate       - Check quality score');
+    console.log('   caws validate       - Validate working spec');
+    console.log('   caws status         - View project health');
+    console.log('   caws diagnose       - Run health checks');
+    console.log('   npm test            - Run test suite');
+    console.log('   npm run coverage    - Check test coverage\n');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Iteration guidance failed: ${error.message}`));
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Generate guidance based on spec and current state
+ */
+function generateGuidance(spec, _currentState, _options) {
+  const mode = spec.mode;
+  const riskTier = spec.risk_tier;
+
+  // Default guidance structure
+  const guidance = {
+    phase: 'Implementation',
+    completed: [],
+    nextActions: [],
+    blockers: [],
+    recommendations: [],
+  };
+
+  // Mode-specific guidance
+  if (mode === 'feature') {
+    guidance.phase = 'Feature Development';
+    guidance.completed = ['Working specification created', 'Acceptance criteria defined'];
+    guidance.nextActions = [
+      'Write failing tests for first acceptance criterion',
+      'Implement minimum code to pass tests',
+      'Refactor and ensure all tests pass',
+      'Move to next acceptance criterion',
+    ];
+    guidance.recommendations = [
+      'Follow TDD cycle: Red → Green → Refactor',
+      'Keep changes within scope boundaries',
+      'Update working spec as requirements evolve',
+      `Maintain ${riskTier === 1 ? '90%+' : riskTier === 2 ? '80%+' : '70%+'} test coverage`,
+    ];
+  } else if (mode === 'refactor') {
+    guidance.phase = 'Refactoring';
+    guidance.completed = ['Working specification created', 'Baseline tests established'];
+    guidance.nextActions = [
+      'Ensure all existing tests pass',
+      'Make small, incremental refactoring changes',
+      'Run tests after each change',
+      'Update documentation as needed',
+    ];
+    guidance.recommendations = [
+      'No behavior changes - tests must still pass',
+      'Use codemod scripts for large-scale changes',
+      'Generate semantic diff report',
+      'Keep commits small and atomic',
+    ];
+    guidance.blockers = [
+      !spec.contracts?.length ? 'No contracts defined to prove unchanged behavior' : null,
+    ].filter(Boolean);
+  } else if (mode === 'fix') {
+    guidance.phase = 'Bug Fix';
+    guidance.completed = ['Working specification created', 'Bug reproduced'];
+    guidance.nextActions = [
+      'Write failing test that reproduces the bug',
+      'Implement minimal fix',
+      'Verify test passes',
+      'Add regression tests',
+    ];
+    guidance.recommendations = [
+      'Keep fix scope minimal',
+      'Document root cause in working spec',
+      'Add edge case tests to prevent recurrence',
+      'Consider if similar bugs exist elsewhere',
+    ];
+  } else if (mode === 'doc') {
+    guidance.phase = 'Documentation';
+    guidance.completed = ['Working specification created'];
+    guidance.nextActions = [
+      'Update README with current information',
+      'Add code examples and usage snippets',
+      'Update API documentation',
+      'Review and update troubleshooting guides',
+    ];
+    guidance.recommendations = [
+      'Use Mermaid for diagrams',
+      'Include code examples that actually work',
+      'Keep docs in sync with code',
+      'Add links to related documentation',
+    ];
+  } else if (mode === 'chore') {
+    guidance.phase = 'Maintenance';
+    guidance.completed = ['Working specification created'];
+    guidance.nextActions = [
+      'Update dependencies to latest versions',
+      'Run tests to ensure compatibility',
+      'Update CI/CD configurations',
+      'Commit changes with descriptive message',
+    ];
+    guidance.recommendations = [
+      'Review changelogs for breaking changes',
+      'Test locally before committing',
+      'Update lockfiles',
+      'Document any configuration changes',
+    ];
+  }
+
+  // Check for common blockers
+  if (!fs.existsSync(path.join(process.cwd(), 'package.json'))) {
+    guidance.blockers.push('No package.json found');
+  }
+
+  if (spec.change_budget && !spec.change_budget.max_files) {
+    guidance.blockers.push('Change budget not defined');
+  }
+
+  return guidance;
+}
+
+/**
+ * Get quality gates for risk tier
+ */
+function getQualityGates(riskTier) {
+  const gates = {
+    1: [
+      'Branch coverage ≥ 90%',
+      'Mutation score ≥ 70%',
+      'All contract tests passing',
+      'Manual code review completed',
+      'No SAST/secret scan violations',
+      'Performance budgets met',
+    ],
+    2: [
+      'Branch coverage ≥ 80%',
+      'Mutation score ≥ 50%',
+      'Contract tests passing (if external APIs)',
+      'E2E smoke tests passing',
+      'No security violations',
+    ],
+    3: [
+      'Branch coverage ≥ 70%',
+      'Mutation score ≥ 30%',
+      'Integration happy-path tests passing',
+      'Linting passing',
+    ],
+  };
+
+  return gates[riskTier] || gates[2];
+}
+
+module.exports = { iterateCommand };

package/dist/commands/quality-monitor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Quality monitor command handler
+ *
+ * @param {string} action - Type of action to monitor
+ * @param {object} options - Command options
+ */
+export function qualityMonitorCommand(action: string, options?: object): Promise<void>;
+/**
+ * Analyze quality impact of an action
+ *
+ * @param {string} action - Type of action (file_saved, code_edited, test_run)
+ * @param {array} files - Files affected by the action
+ * @param {object} context - Additional context information
+ * @returns {object} Quality analysis
+ */
+export function analyzeQualityImpact(action: string, files?: any[], context?: object): object;
+//# sourceMappingURL=quality-monitor.d.ts.map

package/dist/commands/quality-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-monitor.d.ts","sourceRoot":"","sources":["../../src/commands/quality-monitor.js"],"names":[],"mappings":"AAoIA;;;;;GAKG;AACH,8CAHW,MAAM,YACN,MAAM,iBA2HhB;AArPD;;;;;;;GAOG;AACH,6CALW,MAAM,2BAEN,MAAM,GACJ,MAAM,CA8GlB"}

package/dist/commands/quality-monitor.js

@@ -0,0 +1,265 @@
+/**
+ * CAWS Quality Monitor Command
+ *
+ * Monitors code quality impact in real-time based on development actions.
+ * Provides actionable recommendations for maintaining quality standards.
+ *
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Analyze quality impact of an action
+ *
+ * @param {string} action - Type of action (file_saved, code_edited, test_run)
+ * @param {array} files - Files affected by the action
+ * @param {object} context - Additional context information
+ * @returns {object} Quality analysis
+ */
+function analyzeQualityImpact(action, files = [], context = {}) {
+  const analysis = {
+    action,
+    files_affected: files?.length || 0,
+    quality_impact: 'unknown',
+    recommendations: [],
+    risk_level: 'low',
+    timestamp: new Date().toISOString(),
+  };
+
+  // Analyze based on action type
+  switch (action) {
+    case 'file_saved':
+      analysis.quality_impact = 'code_change';
+      analysis.recommendations = [
+        'Run CAWS validation: caws evaluate',
+        'Check for linting issues',
+        'Verify test coverage if applicable',
+      ];
+      break;
+
+    case 'code_edited':
+      analysis.quality_impact = 'implementation_change';
+      analysis.recommendations = [
+        'Run unit tests for affected files',
+        'Check CAWS quality gates',
+        'Update documentation if public APIs changed',
+      ];
+      analysis.risk_level = files?.length > 5 ? 'medium' : 'low';
+
+      // Add file-specific recommendations
+      if (files.length > 0) {
+        const hasTests = files.some((f) => f.includes('test') || f.includes('spec'));
+        const hasConfig = files.some((f) => f.includes('config') || f.includes('.json'));
+
+        if (hasTests) {
+          analysis.recommendations.push('Run full test suite to ensure consistency');
+        }
+        if (hasConfig) {
+          analysis.risk_level = 'high';
+          analysis.recommendations.unshift('Configuration changed - validate carefully');
+        }
+      }
+      break;
+
+    case 'test_run':
+      analysis.quality_impact = 'validation_complete';
+      analysis.recommendations = [
+        'Review test results',
+        'Address any failing tests',
+        'Update CAWS working spec if needed',
+      ];
+      break;
+
+    default:
+      analysis.quality_impact = 'unknown_action';
+      analysis.recommendations = ['Run CAWS evaluation to assess impact'];
+  }
+
+  // Load working spec to check risk tier
+  try {
+    const specPath = path.join(process.cwd(), '.caws/working-spec.yaml');
+    if (fs.existsSync(specPath)) {
+      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+      const projectTier = spec.risk_tier;
+
+      analysis.project_tier = projectTier;
+
+      // Add context-specific recommendations for high-risk projects
+      if (projectTier <= 2) {
+        analysis.recommendations.unshift(
+          'High-risk project (Tier ' + projectTier + '): Run comprehensive validation'
+        );
+        if (analysis.risk_level === 'low') {
+          analysis.risk_level = 'medium';
+        } else if (analysis.risk_level === 'medium') {
+          analysis.risk_level = 'high';
+        }
+      }
+
+      // Add tier-specific quality gates
+      if (projectTier === 1) {
+        analysis.quality_gates = [
+          'Branch coverage ≥ 90%',
+          'Mutation score ≥ 70%',
+          'All contract tests passing',
+          'Manual code review required',
+        ];
+      } else if (projectTier === 2) {
+        analysis.quality_gates = [
+          'Branch coverage ≥ 80%',
+          'Mutation score ≥ 50%',
+          'Contract tests passing (if applicable)',
+        ];
+      } else {
+        analysis.quality_gates = ['Branch coverage ≥ 70%', 'Mutation score ≥ 30%'];
+      }
+    }
+  } catch (error) {
+    // Ignore if we can't load spec
+  }
+
+  // Add context-based recommendations
+  if (context.project_tier) {
+    analysis.project_tier = context.project_tier;
+  }
+
+  return analysis;
+}
+
+/**
+ * Quality monitor command handler
+ *
+ * @param {string} action - Type of action to monitor
+ * @param {object} options - Command options
+ */
+async function qualityMonitorCommand(action, options = {}) {
+  try {
+    // Parse files if provided
+    let files = [];
+    if (options.files) {
+      files =
+        typeof options.files === 'string'
+          ? options.files.split(',').map((f) => f.trim())
+          : options.files;
+    }
+
+    // Parse context if provided
+    let context = {};
+    if (options.context) {
+      try {
+        context =
+          typeof options.context === 'string' ? JSON.parse(options.context) : options.context;
+      } catch (e) {
+        console.warn(chalk.yellow('⚠️  Invalid context JSON, ignoring'));
+      }
+    }
+
+    // Validate action
+    const validActions = ['file_saved', 'code_edited', 'test_run'];
+    if (!validActions.includes(action)) {
+      console.error(chalk.red(`\n❌ Invalid action: ${action}`));
+      console.log(chalk.blue('\n💡 Valid actions:'));
+      validActions.forEach((a) => {
+        console.log(chalk.blue(`   • ${a}`));
+      });
+      process.exit(1);
+    }
+
+    // Analyze quality impact
+    const analysis = analyzeQualityImpact(action, files, context);
+
+    // Display results
+    console.log(chalk.bold('\n🔍 CAWS Quality Monitor\n'));
+    console.log('─'.repeat(60));
+
+    // Action info
+    console.log(chalk.bold(`\nAction: ${action}`));
+    console.log(chalk.gray(`Time: ${new Date(analysis.timestamp).toLocaleString()}`));
+
+    if (analysis.files_affected > 0) {
+      console.log(chalk.bold(`\nFiles Affected: ${analysis.files_affected}`));
+      if (files.length > 0 && files.length <= 10) {
+        files.forEach((file) => {
+          console.log(chalk.gray(`   • ${file}`));
+        });
+      } else if (files.length > 10) {
+        files.slice(0, 10).forEach((file) => {
+          console.log(chalk.gray(`   • ${file}`));
+        });
+        console.log(chalk.gray(`   ... and ${files.length - 10} more`));
+      }
+    }
+
+    // Quality impact
+    const impactColor =
+      analysis.quality_impact === 'validation_complete'
+        ? chalk.green
+        : analysis.quality_impact === 'code_change'
+          ? chalk.yellow
+          : chalk.blue;
+
+    console.log(chalk.bold('\n📊 Quality Impact:'));
+    console.log(impactColor(`   ${analysis.quality_impact}`));
+
+    // Risk level
+    const riskColor =
+      analysis.risk_level === 'high'
+        ? chalk.red
+        : analysis.risk_level === 'medium'
+          ? chalk.yellow
+          : chalk.green;
+
+    console.log(chalk.bold('\n⚠️  Risk Level:'));
+    console.log(riskColor(`   ${analysis.risk_level.toUpperCase()}`));
+
+    // Project tier
+    if (analysis.project_tier) {
+      console.log(chalk.bold(`\n🎯 Project Tier: ${analysis.project_tier}`));
+    }
+
+    // Quality gates
+    if (analysis.quality_gates && analysis.quality_gates.length > 0) {
+      console.log(chalk.bold('\n🚪 Quality Gates to Check:\n'));
+      analysis.quality_gates.forEach((gate) => {
+        console.log(chalk.gray(`   □ ${gate}`));
+      });
+    }
+
+    // Recommendations
+    console.log(chalk.bold('\n💡 Recommendations:\n'));
+    analysis.recommendations.forEach((rec, idx) => {
+      const icon = idx === 0 ? '⚡' : '  •';
+      console.log(chalk.blue(`   ${icon} ${rec}`));
+    });
+
+    // Suggested commands
+    console.log(chalk.bold('\n📚 Suggested Commands:\n'));
+    switch (action) {
+      case 'file_saved':
+      case 'code_edited':
+        console.log(chalk.gray('   caws evaluate       - Check quality score'));
+        console.log(chalk.gray('   caws validate       - Run validation'));
+        console.log(chalk.gray('   caws diagnose       - Health check'));
+        break;
+      case 'test_run':
+        console.log(chalk.gray('   caws status         - Project status'));
+        console.log(chalk.gray('   caws iterate        - Next steps'));
+        break;
+    }
+
+    console.log('\n' + '─'.repeat(60) + '\n');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Quality monitoring failed: ${error.message}`));
+    console.error(chalk.gray(error.stack));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  qualityMonitorCommand,
+  analyzeQualityImpact,
+};

package/dist/commands/status.d.ts

@@ -2,7 +2,7 @@
  * Status command handler
  * @param {Object} options - Command options
  */
-export function statusCommand(options?: any): Promise<void>;
+export function statusCommand(options?: any): Promise<any>;
 /**
  * Load working specification
  * @param {string} specPath - Path to working spec
@@ -19,6 +19,11 @@ export function checkGitHooks(): Promise<any>;
  * @returns {Promise<Object>} Provenance status
  */
 export function loadProvenanceChain(): Promise<any>;
+/**
+ * Load waiver status
+ * @returns {Promise<Object>} Waiver status
+ */
+export function loadWaiverStatus(): Promise<any>;
 /**
  * Check quality gates status (simplified)
  * @returns {Promise<Object>} Quality gates status

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

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.js"],"names":[],"mappings":"AAiPA;;;GAGG;AACH,4DAoBC;AA9PD;;;;GAIG;AACH,2CAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAahC;AAED;;;GAGG;AACH,iCAFa,OAAO,KAAQ,CAgC3B;AAED;;;GAGG;AACH,uCAFa,OAAO,KAAQ,CA+B3B;AAED;;;GAGG;AACH,qCAFa,OAAO,KAAQ,CAS3B;AAwBD;;;GAGG;AACH,+CAyEC;AAED;;;;GAIG;AACH,gDAFa,MAAM,EAAE,CAsBpB"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.js"],"names":[],"mappings":"AAuUA;;;GAGG;AACH,2DAiCC;AAhWD;;;;GAIG;AACH,2CAHW,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAahC;AAED;;;GAGG;AACH,iCAFa,OAAO,KAAQ,CAgC3B;AAED;;;GAGG;AACH,uCAFa,OAAO,KAAQ,CA+B3B;AAED;;;GAGG;AACH,oCAFa,OAAO,KAAQ,CA0D3B;AAED;;;GAGG;AACH,qCAFa,OAAO,KAAQ,CAS3B;AAwBD;;;GAGG;AACH,+CAgGC;AAED;;;;GAIG;AACH,gDAFa,MAAM,EAAE,CAsBpB"}