@paths.design/caws-cli 4.0.0 → 5.0.0

package/dist/commands/archive.js

@@ -0,0 +1,353 @@
+/**
+ * @fileoverview CAWS Archive Command
+ * Archive completed changes with lifecycle management (multi-spec aware)
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const { safeAsync, outputResult } = require('../error-handler');
+
+// Import spec resolution system
+const { resolveSpec } = require('../utils/spec-resolver');
+
+/**
+ * Load change folder structure
+ * @param {string} changeId - Change identifier
+ * @returns {Promise<Object|null>} Change data or null
+ */
+async function loadChange(changeId) {
+  const changesDir = '.caws/changes';
+  const changePath = path.join(changesDir, changeId);
+
+  if (!(await fs.pathExists(changePath))) {
+    return null;
+  }
+
+  try {
+    const metadataPath = path.join(changePath, 'metadata.yaml');
+    const workingSpecPath = path.join(changePath, 'working-spec.yaml');
+
+    const metadata = (await fs.pathExists(metadataPath))
+      ? yaml.load(await fs.readFile(metadataPath, 'utf8'))
+      : {};
+
+    const workingSpec = (await fs.pathExists(workingSpecPath))
+      ? yaml.load(await fs.readFile(workingSpecPath, 'utf8'))
+      : null;
+
+    return {
+      id: changeId,
+      path: changePath,
+      metadata,
+      workingSpec,
+      exists: true,
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Validate all acceptance criteria are met
+ * @param {Object} workingSpec - Working specification
+ * @returns {Promise<Object>} Validation result
+ */
+async function validateAcceptanceCriteria(workingSpec) {
+  if (!workingSpec || !workingSpec.acceptance_criteria) {
+    return {
+      valid: false,
+      message: 'No acceptance criteria found in working spec',
+    };
+  }
+
+  const criteria = workingSpec.acceptance_criteria;
+  const incomplete = [];
+
+  for (const criterion of criteria) {
+    if (!criterion.completed) {
+      incomplete.push(criterion.id || 'unknown');
+    }
+  }
+
+  if (incomplete.length > 0) {
+    return {
+      valid: false,
+      message: `Incomplete acceptance criteria: ${incomplete.join(', ')}`,
+    };
+  }
+
+  return {
+    valid: true,
+    message: `All ${criteria.length} acceptance criteria completed`,
+  };
+}
+
+/**
+ * Validate change meets quality gates
+ * @param {string} changeId - Change identifier
+ * @returns {Promise<Object>} Quality gate result
+ */
+async function validateQualityGates(_changeId) {
+  // For now, return success - in full implementation would run actual gate checks
+  return {
+    valid: true,
+    message: 'Quality gates passed (implementation pending)',
+    gates: ['test-coverage', 'linting', 'type-checking'],
+  };
+}
+
+/**
+ * Generate change summary for archival
+ * @param {Object} change - Change data
+ * @returns {Promise<string>} Summary text
+ */
+async function generateChangeSummary(change) {
+  const { workingSpec, metadata } = change;
+
+  let summary = `# Change Summary: ${change.id}\n\n`;
+
+  if (workingSpec) {
+    summary += `**Title**: ${workingSpec.title || 'Untitled'}\n`;
+    summary += `**Risk Tier**: ${workingSpec.risk_tier || 'Unknown'}\n`;
+    summary += `**Mode**: ${workingSpec.mode || 'Unknown'}\n\n`;
+
+    if (workingSpec.acceptance_criteria) {
+      const total = workingSpec.acceptance_criteria.length;
+      const completed = workingSpec.acceptance_criteria.filter((c) => c.completed).length;
+      summary += `**Acceptance Criteria**: ${completed}/${total} completed\n\n`;
+    }
+  }
+
+  if (metadata.created_at) {
+    summary += `**Created**: ${new Date(metadata.created_at).toISOString()}\n`;
+  }
+
+  if (metadata.completed_at) {
+    summary += `**Completed**: ${new Date(metadata.completed_at).toISOString()}\n`;
+  }
+
+  summary += `\n**Files Changed**: ${metadata.files_changed || 0}\n`;
+  summary += `**Lines Added**: ${metadata.lines_added || 0}\n`;
+  summary += `**Lines Removed**: ${metadata.lines_removed || 0}\n`;
+
+  return summary;
+}
+
+/**
+ * Archive change folder to archive directory
+ * @param {Object} change - Change data
+ * @returns {Promise<void>}
+ */
+async function archiveChange(change) {
+  const archiveDir = '.caws/archive';
+  const archivePath = path.join(archiveDir, change.id);
+
+  // Ensure archive directory exists
+  await fs.ensureDir(archiveDir);
+
+  // Move change folder to archive
+  await fs.move(change.path, archivePath);
+
+  console.log(chalk.green(`   ✅ Moved to: ${archivePath}`));
+}
+
+/**
+ * Update provenance with completion
+ * @param {Object} change - Change data
+ * @returns {Promise<void>}
+ */
+async function updateProvenance(change) {
+  const provenanceDir = '.caws/provenance';
+  const chainPath = path.join(provenanceDir, 'chain.json');
+
+  try {
+    let chain = [];
+
+    if (await fs.pathExists(chainPath)) {
+      chain = JSON.parse(await fs.readFile(chainPath, 'utf8'));
+    }
+
+    // Add completion entry
+    const completionEntry = {
+      timestamp: new Date().toISOString(),
+      action: 'change_completed',
+      change_id: change.id,
+      metadata: {
+        title: change.workingSpec?.title,
+        risk_tier: change.workingSpec?.risk_tier,
+        files_changed: change.metadata?.files_changed || 0,
+        lines_added: change.metadata?.lines_added || 0,
+        lines_removed: change.metadata?.lines_removed || 0,
+      },
+    };
+
+    chain.push(completionEntry);
+
+    await fs.ensureDir(provenanceDir);
+    await fs.writeFile(chainPath, JSON.stringify(chain, null, 2));
+
+    console.log(chalk.green(`   ✅ Provenance updated: ${chain.length} total entries`));
+  } catch (error) {
+    console.log(chalk.yellow(`   ⚠️  Could not update provenance: ${error.message}`));
+  }
+}
+
+/**
+ * Display archive results
+ * @param {Object} change - Change data
+ * @param {Object} validation - Validation result
+ * @param {Object} qualityGates - Quality gates result
+ */
+function displayArchiveResults(change, validation, qualityGates) {
+  console.log(chalk.bold.cyan(`\n📦 Archiving Change: ${change.id}`));
+  console.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+
+  // Validation status
+  if (validation.valid) {
+    console.log(chalk.green('✅ Acceptance Criteria'));
+    console.log(chalk.gray(`   ${validation.message}`));
+  } else {
+    console.log(chalk.red('❌ Acceptance Criteria'));
+    console.log(chalk.gray(`   ${validation.message}`));
+  }
+
+  console.log('');
+
+  // Quality gates status
+  if (qualityGates.valid) {
+    console.log(chalk.green('✅ Quality Gates'));
+    console.log(chalk.gray(`   ${qualityGates.message}`));
+  } else {
+    console.log(chalk.red('❌ Quality Gates'));
+    console.log(chalk.gray(`   ${qualityGates.message}`));
+  }
+
+  console.log('');
+
+  // Archive action
+  console.log(chalk.blue('📂 Archive Actions:'));
+  console.log(chalk.gray('   • Moving change folder to archive'));
+  console.log(chalk.gray('   • Updating provenance chain'));
+  console.log(chalk.gray('   • Generating change summary'));
+
+  console.log('');
+}
+
+/**
+ * Archive command handler
+ * @param {string} changeId - Change identifier to archive
+ * @param {Object} options - Command options
+ */
+async function archiveCommand(changeId, options = {}) {
+  return safeAsync(
+    async () => {
+      if (!changeId) {
+        throw new Error('Change ID is required. Usage: caws archive <change-id>');
+      }
+
+      // Load change data
+      const change = await loadChange(changeId);
+      if (!change) {
+        throw new Error(`Change '${changeId}' not found in .caws/changes/`);
+      }
+
+      // Resolve spec using priority system
+      let workingSpec = change.workingSpec;
+      if (!workingSpec && options.specId) {
+        // If change doesn't have a working spec but spec-id is provided, load it
+        try {
+          const resolved = await resolveSpec({
+            specId: options.specId,
+            warnLegacy: false,
+          });
+          workingSpec = resolved.spec;
+        } catch (error) {
+          console.log(
+            chalk.yellow(`⚠️  Could not load spec '${options.specId}': ${error.message}`)
+          );
+        }
+      }
+
+      // Validate acceptance criteria
+      const validation = await validateAcceptanceCriteria(workingSpec);
+
+      // Validate quality gates
+      const qualityGates = await validateQualityGates(changeId);
+
+      // Display results
+      displayArchiveResults(change, validation, qualityGates);
+
+      // Check if we should proceed with archival
+      if (!validation.valid) {
+        console.log(chalk.yellow('⚠️  Cannot archive: Incomplete acceptance criteria'));
+        if (!options.force) {
+          console.log(chalk.yellow('💡 Use --force to archive anyway'));
+          return outputResult({
+            command: 'archive',
+            change: changeId,
+            archived: false,
+            reason: 'incomplete_criteria',
+          });
+        }
+      }
+
+      if (!qualityGates.valid) {
+        console.log(chalk.yellow('⚠️  Cannot archive: Quality gates not met'));
+        if (!options.force) {
+          console.log(chalk.yellow('💡 Use --force to archive anyway'));
+          return outputResult({
+            command: 'archive',
+            change: changeId,
+            archived: false,
+            reason: 'quality_gates_failed',
+          });
+        }
+      }
+
+      // Perform archival
+      console.log(chalk.blue('🔄 Performing archival...'));
+
+      // Update metadata with completion timestamp
+      change.metadata.completed_at = new Date().toISOString();
+      change.metadata.archived = true;
+
+      // Generate and save summary
+      const summary = await generateChangeSummary(change);
+      const summaryPath = path.join(change.path, 'archive-summary.md');
+      await fs.writeFile(summaryPath, summary);
+
+      // Archive the change
+      await archiveChange(change);
+
+      // Update provenance
+      await updateProvenance(change);
+
+      console.log(chalk.green(`\n🎉 Successfully archived change: ${changeId}`));
+
+      return outputResult({
+        command: 'archive',
+        change: changeId,
+        archived: true,
+        validation: validation.valid,
+        qualityGates: qualityGates.valid,
+        summary: summary,
+      });
+    },
+    'archive change',
+    true
+  );
+}
+
+module.exports = {
+  archiveCommand,
+  loadChange,
+  validateAcceptanceCriteria,
+  validateQualityGates,
+  generateChangeSummary,
+  archiveChange,
+  updateProvenance,
+  displayArchiveResults,
+};

package/dist/commands/iterate.js

@@ -9,10 +9,12 @@
 
 const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
 
+// Import spec resolution system
+const { resolveSpec } = require('../utils/spec-resolver');
+
 /**
  * Iterate command handler
  *
@@ -21,6 +23,15 @@ const { initializeGlobalSetup } = require('../config');
  */
 async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}) {
   try {
+    // Resolve spec using priority system
+    const resolved = await resolveSpec({
+      specId: options.specId,
+      specFile,
+      warnLegacy: false,
+    });
+
+    const { spec } = resolved;
+
     console.log('🔍 Detecting CAWS setup...');
     const setup = initializeGlobalSetup();
 
@@ -29,18 +40,6 @@ async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}
       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';

package/dist/commands/mode.js

@@ -0,0 +1,259 @@
+/**
+ * @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
+ */
+function displayCurrentMode() {
+  console.log(chalk.bold.cyan('\n🔧 CAWS Current Mode'));
+  console.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+
+  // This will be implemented when we load the current mode
+  console.log(chalk.yellow('Mode display will be implemented...'));
+  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('\n🔧 Select 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();
+
+          const tier = getTier(currentMode);
+          console.log(chalk.bold(`Current Mode: ${tier.icon} ${tier.color(currentMode)}`));
+          console.log(chalk.gray(`Description: ${tier.description}`));
+          console.log(
+            chalk.gray(
+              `Quality: ${tier.qualityRequirements.testCoverage}% coverage, ${tier.qualityRequirements.mutationScore}% mutation`
+            )
+          );
+
+          return outputResult({
+            command: 'mode current',
+            mode: currentMode,
+            tier: tier,
+          });
+        }
+
+        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('\n🎯 Recommended 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,
+};