@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/commands/iterate.js

@@ -1,417 +0,0 @@
-/**
- * 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 chalk = require('chalk');
-const { initializeGlobalSetup } = require('../config');
-
-// Import spec resolution system
-const { resolveSpec } = require('../utils/spec-resolver');
-// EVLOG-002 Phase 2 read flip: iterate reads from the event log instead of
-// the state layer. loadStateFromEvents matches loadState's contract exactly
-// (returns null for specs with no events), so the `workingState &&` guard
-// below stays correct without code changes.
-const { loadStateFromEvents } = require('../utils/event-renderer');
-
-/**
- * Iterate command handler
- *
- * @param {string} specFile - Path to working spec file
- * @param {object} options - Command options
- */
-async function iterateCommand(specFile, options = {}) {
-  try {
-    // Resolve spec using priority system
-    const resolved = await resolveSpec({
-      specId: options.specId,
-      specFile: specFile || undefined,
-      warnLegacy: false,
-    });
-
-    const { spec } = resolved;
-
-    console.log('Detecting CAWS setup...');
-    const setup = initializeGlobalSetup();
-
-    if (setup.hasWorkingSpec) {
-      console.log(`Detected ${setup.type} CAWS setup`);
-      console.log(`   Capabilities: ${setup.capabilities.join(', ')}`);
-    }
-
-    // Parse current state from options
-    let currentState = {};
-    if (options.currentState) {
-      try {
-        currentState = JSON.parse(options.currentState);
-      } catch {
-        console.error('Invalid JSON in --current-state. Using defaults.');
-      }
-    }
-    const stateDescription = currentState.description || 'Starting implementation';
-
-    console.log(chalk.blue('\nIterative 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`);
-
-    // Load working state for evidence-based guidance (EVLOG-002: from event log)
-    let workingState = null;
-    try { workingState = loadStateFromEvents(spec.id); } catch { /* non-fatal */ }
-
-    // Analyze progress based on mode
-    const guidance = generateGuidance(spec, currentState, options);
-
-    // If working state exists, overlay evidence-based data
-    if (workingState && workingState.phase !== 'not-started') {
-      guidance.phase = formatPhase(workingState.phase);
-
-      // Build evidence-based completed steps
-      const evidence = [];
-      if (workingState.validation && workingState.validation.passed) {
-        evidence.push(`Validation passed (Grade ${workingState.validation.grade || '?'})`);
-      }
-      if (workingState.evaluation) {
-        evidence.push(`Evaluation: ${workingState.evaluation.percentage}% (Grade ${workingState.evaluation.grade})`);
-      }
-      if (workingState.gates && workingState.gates.passed) {
-        evidence.push(`All gates passing (last run: ${workingState.gates.context} context)`);
-      }
-      if (workingState.acceptance_criteria) {
-        const ac = workingState.acceptance_criteria;
-        evidence.push(`AC verification: ${ac.pass}/${ac.total} pass, ${ac.fail} fail, ${ac.unchecked} unchecked`);
-      }
-      if (workingState.files_touched && workingState.files_touched.length > 0) {
-        evidence.push(`${workingState.files_touched.length} file(s) touched`);
-      }
-      if (evidence.length > 0) {
-        guidance.completed = evidence;
-      }
-
-      // Overlay blockers and next actions from state
-      if (workingState.blockers && workingState.blockers.length > 0) {
-        guidance.blockers = workingState.blockers.map(b => b.message);
-      }
-      if (workingState.next_actions && workingState.next_actions.length > 0) {
-        guidance.nextActions = workingState.next_actions;
-      }
-    }
-
-    // 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(`   [done] ${step}`));
-    });
-
-    console.log(chalk.blue('\nNext Actions:\n'));
-    guidance.nextActions.forEach((action, index) => {
-      console.log(chalk.yellow(`   ${index + 1}. ${action}`));
-    });
-
-    if (guidance.blockers.length > 0) {
-      console.log(chalk.red('\nBlockers:\n'));
-      guidance.blockers.forEach((blocker) => {
-        console.log(chalk.red(`   ${blocker}`));
-      });
-
-      // Show quality gap summary if sidecars available
-      try {
-        const { diagnoseQualityGaps } = require('../sidecars');
-        if (workingState) {
-          const gapResult = diagnoseQualityGaps(workingState, spec);
-          if (gapResult.data && gapResult.data.gaps && gapResult.data.gaps.length > 0) {
-            console.log(chalk.yellow(`\n   Quality gaps: ${gapResult.data.summary}`));
-            console.log(chalk.yellow('   Run: caws sidecar gaps --spec-id ' + spec.id));
-          }
-        }
-      } catch { /* sidecars not available — non-fatal */ }
-    }
-
-    console.log(chalk.blue('\nRecommendations:\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('\nAcceptance 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('\nQuality Gates (Risk Tier ' + spec.risk_tier + '):\n'));
-    const gates = getQualityGates(spec.risk_tier);
-    gates.forEach((gate) => {
-      console.log(`   □ ${gate}`);
-    });
-
-    console.log(chalk.blue('\nUseful 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(`\nIteration 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];
-}
-
-/**
- * Format phase slug into human-readable label
- */
-function formatPhase(phase) {
-  const labels = {
-    'not-started': 'Not Started',
-    'spec-authoring': 'Spec Authoring',
-    'implementation': 'Implementation',
-    'verification': 'Verification',
-    'complete': 'Complete',
-  };
-  return labels[phase] || phase;
-}
-
-module.exports = { iterateCommand };

package/dist/commands/mode.js

@@ -1,269 +0,0 @@
-/**
- * @fileoverview CAWS Mode Command
- * Manage CAWS complexity tiers and switch between modes
- * @author @darianrosebrook
- */
-
-const chalk = require('chalk');
-const { safeAsync, outputResult } = require('../error-handler');
-
-const {
-  getTier,
-  getAvailableTiers,
-  getCurrentMode,
-  setCurrentMode,
-  displayTierComparison,
-  getTierRecommendation,
-} = require('../config/modes');
-
-/**
- * Display current mode status
- * @param {string} currentMode - The current mode to display
- */
-function displayCurrentMode(currentMode) {
-  const tier = getTier(currentMode);
-
-  console.log(chalk.bold.cyan('\nCAWS Current Mode'));
-  console.log(chalk.cyan('==============================================\n'));
-
-  console.log(chalk.bold(`Active Mode: ${tier.icon} ${tier.color(currentMode)}`));
-  console.log(chalk.gray(`Description: ${tier.description}`));
-  console.log('');
-
-  // Quality requirements
-  console.log(chalk.bold('Quality Requirements:'));
-  console.log(chalk.gray(`   Test Coverage: ≥${tier.qualityRequirements.testCoverage}%`));
-  console.log(chalk.gray(`   Mutation Score: ≥${tier.qualityRequirements.mutationScore}%`));
-  console.log(chalk.gray(`   Contracts: ${tier.qualityRequirements.contracts}`));
-  console.log('');
-
-  // Risk tiers supported
-  console.log(chalk.bold('Supported Risk Tiers:'));
-  tier.riskTiers.forEach((riskTier) => {
-    const riskColor =
-      riskTier === 'T1' ? chalk.red : riskTier === 'T2' ? chalk.yellow : chalk.green;
-    console.log(chalk.gray(`   ${riskColor(riskTier)}`));
-  });
-  console.log('');
-}
-
-/**
- * Display mode details
- * @param {string} mode - Mode to display
- */
-function displayModeDetails(mode) {
-  const tier = getTier(mode);
-  const tierColor = tier.color;
-  const icon = tier.icon;
-
-  console.log(chalk.bold.cyan(`\n${icon} ${tierColor(tier.name)} Mode Details`));
-  console.log(chalk.cyan('=================================================================\n'));
-
-  console.log(`${tierColor(tier.name)} - ${tier.description}\n`);
-
-  // Quality Requirements
-  console.log(chalk.bold('Quality Requirements:'));
-  console.log(chalk.gray(`   Test Coverage: ${tier.qualityRequirements.testCoverage}%`));
-  console.log(chalk.gray(`   Mutation Score: ${tier.qualityRequirements.mutationScore}%`));
-  console.log(chalk.gray(`   Contracts: ${tier.qualityRequirements.contracts}\n`));
-
-  // Supported Risk Tiers
-  console.log(chalk.bold('Supported Risk Tiers:'));
-  tier.riskTiers.forEach((riskTier) => {
-    const riskColor =
-      riskTier === 'T1' ? chalk.red : riskTier === 'T2' ? chalk.yellow : chalk.green;
-    console.log(chalk.gray(`   ${riskColor(riskTier)}`));
-  });
-  console.log('');
-
-  // Available Commands
-  console.log(chalk.bold('Available Commands:'));
-  Object.entries(tier.commands)
-    .filter(([, available]) => available)
-    .forEach(([command]) => {
-      console.log(chalk.gray(`   caws ${command}`));
-    });
-
-  const disabledCommands = Object.entries(tier.commands)
-    .filter(([, available]) => !available)
-    .map(([command]) => command);
-
-  if (disabledCommands.length > 0) {
-    console.log(chalk.bold('\nDisabled Commands:'));
-    disabledCommands.forEach((command) => {
-      console.log(chalk.gray(`   caws ${command}`));
-    });
-  }
-
-  console.log('');
-}
-
-/**
- * Interactive mode selection
- * @returns {Promise<string>} Selected mode
- */
-async function interactiveModeSelection() {
-  const readline = require('readline');
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    console.log(chalk.bold.cyan('\nSelect CAWS Complexity Tier'));
-    console.log(chalk.cyan('==============================================\n'));
-
-    const tiers = getAvailableTiers();
-    tiers.forEach((tier, index) => {
-      const tierConfig = getTier(tier);
-      const tierColor = tierConfig.color;
-      const icon = tierConfig.icon;
-      console.log(`${index + 1}. ${icon} ${tierColor(tier)} - ${tierConfig.description}`);
-    });
-
-    console.log('\nEnter your choice (1-3): ');
-
-    rl.on('line', (input) => {
-      const choice = parseInt(input.trim());
-      if (choice >= 1 && choice <= tiers.length) {
-        rl.close();
-        resolve(tiers[choice - 1]);
-      } else {
-        console.log(chalk.red('Invalid choice. Please enter 1-3:'));
-      }
-    });
-  });
-}
-
-/**
- * Mode command handler
- * @param {string} action - Action to perform (current, set, compare, recommend)
- * @param {Object} options - Command options
- */
-async function modeCommand(action, options = {}) {
-  return safeAsync(
-    async () => {
-      switch (action) {
-        case 'current': {
-          const currentMode = await getCurrentMode();
-          displayCurrentMode(currentMode);
-
-          return outputResult({
-            command: 'mode current',
-            mode: currentMode,
-            tier: getTier(currentMode),
-          });
-        }
-
-        case 'set': {
-          let targetMode;
-
-          if (options.mode) {
-            targetMode = options.mode;
-          } else if (options.interactive) {
-            targetMode = await interactiveModeSelection();
-          } else {
-            throw new Error('Mode not specified. Use --mode <mode> or --interactive');
-          }
-
-          if (!getAvailableTiers().includes(targetMode)) {
-            throw new Error(
-              `Invalid mode: ${targetMode}. Available: ${getAvailableTiers().join(', ')}`
-            );
-          }
-
-          const success = await setCurrentMode(targetMode);
-          if (!success) {
-            throw new Error(`Failed to set mode to ${targetMode}`);
-          }
-
-          console.log(
-            chalk.green(
-              `Successfully switched to ${getTier(targetMode).icon} ${getTier(targetMode).color(targetMode)} mode`
-            )
-          );
-
-          return outputResult({
-            command: 'mode set',
-            mode: targetMode,
-          });
-        }
-
-        case 'compare': {
-          displayTierComparison();
-
-          return outputResult({
-            command: 'mode compare',
-            tiers: getAvailableTiers(),
-          });
-        }
-
-        case 'recommend': {
-          const projectInfo = {};
-
-          if (options.size) projectInfo.size = options.size;
-          if (options.teamSize) projectInfo.teamSize = parseInt(options.teamSize);
-          if (options.compliance) projectInfo.compliance = options.compliance === 'true';
-          if (options.audit) projectInfo.auditRequired = options.audit === 'true';
-
-          const recommendation = getTierRecommendation(projectInfo);
-          const recommendedTier = getTier(recommendation);
-
-          console.log(chalk.bold.cyan('\nRecommended CAWS Tier'));
-          console.log(chalk.cyan('==============================================\n'));
-
-          console.log(
-            `${recommendedTier.icon} ${recommendedTier.color(recommendedTier.name)} - ${recommendedTier.description}`
-          );
-          console.log(
-            chalk.gray(
-              `Quality: ${recommendedTier.qualityRequirements.testCoverage}% coverage, ${recommendedTier.qualityRequirements.mutationScore}% mutation`
-            )
-          );
-
-          if (options.details) {
-            console.log('');
-            displayModeDetails(recommendation);
-          }
-
-          return outputResult({
-            command: 'mode recommend',
-            recommendation,
-            tier: recommendedTier,
-            projectInfo,
-          });
-        }
-
-        case 'details': {
-          if (!options.mode) {
-            throw new Error('Mode not specified. Use --mode <mode>');
-          }
-
-          displayModeDetails(options.mode);
-
-          return outputResult({
-            command: 'mode details',
-            mode: options.mode,
-          });
-        }
-
-        default:
-          throw new Error(
-            `Unknown mode action: ${action}. Use: current, set, compare, recommend, details`
-          );
-      }
-    },
-    `mode ${action}`,
-    true
-  );
-}
-
-module.exports = {
-  modeCommand,
-  getCurrentMode,
-  setCurrentMode,
-  displayCurrentMode,
-  displayModeDetails,
-  interactiveModeSelection,
-};