@paths.design/caws-cli 4.0.0 → 5.0.0

package/dist/config/modes.js

@@ -0,0 +1,321 @@
+/**
+ * @fileoverview CAWS Complexity Modes Configuration
+ * Defines different tiers of CAWS complexity for different project needs
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+/**
+ * CAWS Complexity Tiers
+ */
+const COMPLEXITY_TIERS = {
+  simple: {
+    name: 'Simple',
+    description: 'Minimal CAWS for small projects and quick prototyping',
+    color: chalk.green,
+    icon: '🟢',
+    features: {
+      workingSpec: true,
+      basicValidation: true,
+      statusDisplay: true,
+      noQualityGates: true,
+      noProvenance: true,
+      noWaivers: true,
+      noChangeBudgets: true,
+      noMultiSpec: false, // Can use multi-spec but simplified
+    },
+    qualityRequirements: {
+      testCoverage: 70,
+      mutationScore: 30,
+      contracts: 'optional',
+    },
+    riskTiers: ['T3'], // Only T3 supported
+    commands: {
+      init: true,
+      validate: true,
+      status: true,
+      specs: true, // Basic specs support
+      // No: diagnose, evaluate, iterate, provenance, waivers, hooks, archive
+    },
+  },
+
+  standard: {
+    name: 'Standard',
+    description: 'Balanced CAWS with change management and quality gates',
+    color: chalk.yellow,
+    icon: '🟡',
+    features: {
+      workingSpec: true,
+      fullValidation: true,
+      statusDisplay: true,
+      qualityGates: true,
+      provenance: true,
+      waivers: true,
+      changeBudgets: true,
+      multiSpec: true,
+      changeFolders: true,
+    },
+    qualityRequirements: {
+      testCoverage: 80,
+      mutationScore: 50,
+      contracts: 'required',
+    },
+    riskTiers: ['T1', 'T2', 'T3'],
+    commands: {
+      init: true,
+      validate: true,
+      status: true,
+      specs: true,
+      diagnose: true,
+      evaluate: true,
+      iterate: true,
+      provenance: true,
+      waivers: true,
+      hooks: true,
+      archive: true,
+    },
+  },
+
+  enterprise: {
+    name: 'Enterprise',
+    description: 'Full CAWS with comprehensive audit trails and compliance',
+    color: chalk.red,
+    icon: '🔴',
+    features: {
+      workingSpec: true,
+      fullValidation: true,
+      statusDisplay: true,
+      qualityGates: true,
+      provenance: true,
+      waivers: true,
+      changeBudgets: true,
+      multiSpec: true,
+      changeFolders: true,
+      auditTrails: true,
+      compliance: true,
+      advancedMonitoring: true,
+    },
+    qualityRequirements: {
+      testCoverage: 90,
+      mutationScore: 70,
+      contracts: 'required',
+    },
+    riskTiers: ['T1', 'T2', 'T3'],
+    commands: {
+      init: true,
+      validate: true,
+      status: true,
+      specs: true,
+      diagnose: true,
+      evaluate: true,
+      iterate: true,
+      provenance: true,
+      waivers: true,
+      hooks: true,
+      archive: true,
+      troubleshoot: true,
+      testAnalysis: true,
+      qualityMonitor: true,
+    },
+  },
+};
+
+/**
+ * Get tier information
+ * @param {string} tier - Tier name
+ * @returns {Object} Tier configuration
+ */
+function getTier(tier) {
+  return COMPLEXITY_TIERS[tier] || COMPLEXITY_TIERS.standard;
+}
+
+/**
+ * Get available tiers
+ * @returns {string[]} Array of tier names
+ */
+function getAvailableTiers() {
+  return Object.keys(COMPLEXITY_TIERS);
+}
+
+/**
+ * Check if a command is available in the current tier
+ * @param {string} command - Command name
+ * @param {string} tier - Tier name
+ * @returns {boolean} Whether command is available
+ */
+function isCommandAvailable(command, tier = 'standard') {
+  const tierConfig = getTier(tier);
+  return tierConfig.commands[command] === true;
+}
+
+/**
+ * Check if a feature is enabled in the current tier
+ * @param {string} feature - Feature name
+ * @param {string} tier - Tier name
+ * @returns {boolean} Whether feature is enabled
+ */
+function isFeatureEnabled(feature, tier = 'standard') {
+  const tierConfig = getTier(tier);
+  return tierConfig.features[feature] === true;
+}
+
+/**
+ * Get quality requirements for a tier
+ * @param {string} tier - Tier name
+ * @returns {Object} Quality requirements
+ */
+function getQualityRequirements(tier = 'standard') {
+  const tierConfig = getTier(tier);
+  return tierConfig.qualityRequirements;
+}
+
+/**
+ * Get supported risk tiers for a complexity tier
+ * @param {string} tier - Tier name
+ * @returns {string[]} Supported risk tiers
+ */
+function getSupportedRiskTiers(tier = 'standard') {
+  const tierConfig = getTier(tier);
+  return tierConfig.riskTiers;
+}
+
+/**
+ * Validate if a risk tier is supported in the current complexity tier
+ * @param {string} riskTier - Risk tier to validate
+ * @param {string} complexityTier - Complexity tier
+ * @returns {boolean} Whether risk tier is supported
+ */
+function isRiskTierSupported(riskTier, complexityTier = 'standard') {
+  const supportedTiers = getSupportedRiskTiers(complexityTier);
+  return supportedTiers.includes(riskTier);
+}
+
+/**
+ * Display tier comparison
+ */
+function displayTierComparison() {
+  console.log(chalk.bold.cyan('\n📊 CAWS Complexity Tiers'));
+  console.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+
+  // Header
+  console.log(
+    chalk.bold(
+      'Tier'.padEnd(12) +
+        'Features'.padEnd(15) +
+        'Coverage'.padEnd(10) +
+        'Commands'.padEnd(12) +
+        'Use Case'
+    )
+  );
+  console.log(chalk.gray('─'.repeat(90)));
+
+  Object.entries(COMPLEXITY_TIERS).forEach(([tierName, tier]) => {
+    const tierColor = tier.color;
+    const icon = tier.icon;
+
+    const features = Object.entries(tier.features)
+      .filter(([, enabled]) => enabled)
+      .map(([feature]) => feature.replace(/([A-Z])/g, ' $1').toLowerCase())
+      .slice(0, 3)
+      .join(', ');
+
+    const commands = Object.keys(tier.commands).filter((cmd) => tier.commands[cmd]).length;
+
+    console.log(
+      `${icon} ${tierColor(tierName.padEnd(10))} ${features.padEnd(13)} ${tier.qualityRequirements.testCoverage}%${' '.padEnd(8)}${commands}${' '.padEnd(10)}${tier.description}`
+    );
+  });
+
+  console.log('');
+}
+
+/**
+ * Get current mode from configuration
+ * @returns {Promise<string>} Current mode
+ */
+async function getCurrentMode() {
+  const fs = require('fs-extra');
+  const MODE_CONFIG = '.caws/mode.json';
+
+  try {
+    if (!(await fs.pathExists(MODE_CONFIG))) {
+      return 'standard'; // Default to standard mode
+    }
+
+    const config = JSON.parse(await fs.readFile(MODE_CONFIG, 'utf8'));
+    return config.current || 'standard';
+  } catch (error) {
+    return 'standard'; // Default to standard mode on error
+  }
+}
+
+/**
+ * Set current mode in configuration
+ * @param {string} mode - Mode to set
+ * @returns {Promise<boolean>} Success status
+ */
+async function setCurrentMode(mode) {
+  const fs = require('fs-extra');
+  const path = require('path');
+  const MODE_CONFIG = '.caws/mode.json';
+
+  if (!getAvailableTiers().includes(mode)) {
+    return false;
+  }
+
+  try {
+    await fs.ensureDir(path.dirname(MODE_CONFIG));
+    const config = {
+      current: mode,
+      initialized: true,
+      lastChanged: new Date().toISOString(),
+    };
+    await fs.writeFile(MODE_CONFIG, JSON.stringify(config, null, 2));
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get tier recommendation based on project characteristics
+ * @param {Object} projectInfo - Project information
+ * @returns {string} Recommended tier
+ */
+function getTierRecommendation(projectInfo = {}) {
+  const { size = 'medium', teamSize = 1, compliance = false, auditRequired = false } = projectInfo;
+
+  // Enterprise tier for compliance/audit requirements
+  if (compliance || auditRequired) {
+    return 'enterprise';
+  }
+
+  // Enterprise for large teams or projects
+  if (teamSize > 5 || size === 'large') {
+    return 'enterprise';
+  }
+
+  // Standard for medium teams/projects
+  if (teamSize > 1 || size === 'medium') {
+    return 'standard';
+  }
+
+  // Simple for solo/small projects
+  return 'simple';
+}
+
+module.exports = {
+  COMPLEXITY_TIERS,
+  getTier,
+  getAvailableTiers,
+  getCurrentMode,
+  setCurrentMode,
+  isCommandAvailable,
+  isFeatureEnabled,
+  getQualityRequirements,
+  getSupportedRiskTiers,
+  isRiskTierSupported,
+  displayTierComparison,
+  getTierRecommendation,
+};

package/dist/constants/spec-types.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Spec Types Constants
+ * Defines spec types and their metadata for consistent display
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Spec types and their metadata
+ */
+const SPEC_TYPES = {
+  feature: {
+    color: chalk.green,
+    icon: '🚀',
+    description: 'New feature development',
+  },
+  fix: {
+    color: chalk.red,
+    icon: '🔧',
+    description: 'Bug fixes and patches',
+  },
+  refactor: {
+    color: chalk.blue,
+    icon: '♻️',
+    description: 'Code refactoring and improvements',
+  },
+  chore: {
+    color: chalk.gray,
+    icon: '🧹',
+    description: 'Maintenance and cleanup',
+  },
+  docs: {
+    color: chalk.cyan,
+    icon: '📚',
+    description: 'Documentation updates',
+  },
+};
+
+module.exports = {
+  SPEC_TYPES,
+};

package/dist/index.js

@@ -41,7 +41,13 @@ const { iterateCommand } = require('./commands/iterate');
 const { waiversCommand } = require('./commands/waivers');
 const { workflowCommand } = require('./commands/workflow');
 const { qualityMonitorCommand } = require('./commands/quality-monitor');
+const { qualityGatesCommand } = require('./commands/quality-gates');
 const { troubleshootCommand } = require('./commands/troubleshoot');
+const { archiveCommand } = require('./commands/archive');
+const { specsCommand } = require('./commands/specs');
+const { modeCommand } = require('./commands/mode');
+const { tutorialCommand } = require('./commands/tutorial');
+const { planCommand } = require('./commands/plan');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -113,22 +119,216 @@ program
 // Validate command
 program
   .command('validate')
-  .description('Validate CAWS working spec with suggestions')
-  .argument('[spec-file]', 'Path to working spec file (default: .caws/working-spec.yaml)')
+  .description('Validate CAWS spec with suggestions')
+  .argument('[spec-file]', 'Path to spec file (optional, uses spec resolution)')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth, FEAT-001)')
+  .option('-i, --interactive', 'Interactive spec selection when multiple specs exist', false)
   .option('-q, --quiet', 'Suppress suggestions and warnings', false)
   .option('--auto-fix', 'Automatically fix safe validation issues', false)
   .option('--dry-run', 'Preview auto-fixes without applying them', false)
   .option('--format <format>', 'Output format (text, json)', 'text')
   .action(validateCommand);
 
+// Quality Gates command
+program
+  .command('quality-gates')
+  .description('Run comprehensive quality gates (naming, duplication, god objects, documentation)')
+  .option('--ci', 'CI mode - exit with error code if violations found', false)
+  .option('--json', 'Output machine-readable JSON to stdout', false)
+  .option(
+    '--gates <gates>',
+    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,documentation)',
+    ''
+  )
+  .option('--fix', 'Attempt automatic fixes (experimental)', false)
+  .option('--help', 'Show detailed help and usage examples', false)
+  .action(async (options) => {
+    // Handle --help flag
+    if (options.help) {
+      console.log(`
+CAWS Quality Gates - Enterprise Code Quality Enforcement
+
+USAGE:
+  caws quality-gates [options]
+
+DESCRIPTION:
+  Runs comprehensive quality gates to maintain code quality standards.
+  Supports selective gate execution, JSON output, and CI/CD integration.
+
+OPTIONS:
+  --ci              CI mode - exit with error code if violations found
+  --json            Output machine-readable JSON to stdout
+  --gates=<gates>   Run only specific gates (comma-separated)
+  --fix             Attempt automatic fixes (experimental)
+  --help            Show this help message
+
+VALID GATES:
+  naming           Check naming conventions and banned modifiers
+  code_freeze      Enforce code freeze compliance
+  duplication      Detect functional duplication
+  god_objects      Prevent oversized files
+  documentation    Check documentation quality
+
+EXAMPLES:
+  # Run all gates in development mode
+  caws quality-gates
+
+  # Run only specific gates
+  caws quality-gates --gates=naming,duplication
+
+  # CI mode with JSON output
+  caws quality-gates --ci --json
+
+  # Show detailed help
+  caws quality-gates --help
+
+OUTPUT:
+  - Console: Human-readable results with enforcement levels
+  - JSON: Machine-readable structured data (--json flag)
+  - Artifacts: docs-status/quality-gates-report.json
+  - GitHub Actions: Automatic step summaries when GITHUB_STEP_SUMMARY is set
+
+For more information, see: packages/quality-gates/README.md
+`);
+      process.exit(0);
+    }
+
+    // Call the actual quality gates runner
+    await qualityGatesCommand(options);
+  });
+
 // Status command
 program
   .command('status')
   .description('Show project health overview')
-  .option('-s, --spec <path>', 'Path to working spec file', '.caws/working-spec.yaml')
-  .option('--json', 'Output in JSON format', false)
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-s, --spec <path>', 'Path to spec file (explicit override)')
+  .option('--visual', 'Enhanced visual output with progress bars', false)
+  .option('--json', 'Output in JSON format for automation', false)
   .action(statusCommand);
 
+// Archive command
+program
+  .command('archive <change-id>')
+  .description('Archive completed change')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-f, --force', 'Force archive even if criteria not met', false)
+  .option('--dry-run', 'Preview archive without performing it', false)
+  .action(archiveCommand);
+
+// Specs command group
+const specsCmd = program.command('specs').description('Manage multiple CAWS spec files');
+
+// Specs subcommands
+specsCmd
+  .command('list')
+  .description('List all available specs')
+  .action(() => specsCommand('list', {}));
+
+specsCmd
+  .command('create <id>')
+  .description('Create a new spec (with conflict resolution)')
+  .option('-t, --type <type>', 'Spec type (feature, fix, refactor, chore, docs)', 'feature')
+  .option('--title <title>', 'Spec title')
+  .option('--tier <tier>', 'Risk tier (T1, T2, T3)', 'T3')
+  .option('--mode <mode>', 'Development mode', 'development')
+  .option('-f, --force', 'Override existing specs without confirmation', false)
+  .option('-i, --interactive', 'Ask for confirmation on conflicts', false)
+  .action((id, options) => specsCommand('create', { id, ...options }));
+
+specsCmd
+  .command('show <id>')
+  .description('Show detailed spec information')
+  .action((id) => specsCommand('show', { id }));
+
+specsCmd
+  .command('update <id>')
+  .description('Update spec properties')
+  .option('-s, --status <status>', 'Spec status (draft, active, completed)')
+  .option('--title <title>', 'Spec title')
+  .option('--description <desc>', 'Spec description')
+  .action((id, options) => specsCommand('update', { id, ...options }));
+
+specsCmd
+  .command('delete <id>')
+  .description('Delete a spec')
+  .action((id) => specsCommand('delete', { id }));
+
+specsCmd
+  .command('conflicts')
+  .description('Check for scope conflicts between specs')
+  .action(() => specsCommand('conflicts', {}));
+
+specsCmd
+  .command('migrate')
+  .description('Migrate from legacy working-spec.yaml to feature-specific specs')
+  .option('-i, --interactive', 'Interactive feature selection', false)
+  .option('-f, --features <features>', 'Comma-separated list of features to migrate', (value) =>
+    value.split(',')
+  )
+  .action((options) => specsCommand('migrate', options));
+
+specsCmd
+  .command('types')
+  .description('Show available spec types')
+  .action(() => specsCommand('types', {}));
+
+// Mode command group
+const modeCmd = program.command('mode').description('Manage CAWS complexity tiers');
+
+// Mode subcommands
+modeCmd
+  .command('current')
+  .description('Show current CAWS mode')
+  .action(() => modeCommand('current', {}));
+
+modeCmd
+  .command('set <mode>')
+  .description('Set CAWS complexity tier')
+  .action((mode) => modeCommand('set', { mode }));
+
+modeCmd
+  .command('set')
+  .description('Set CAWS complexity tier (interactive)')
+  .option('-i, --interactive', 'Interactive mode selection', false)
+  .option('-m, --mode <mode>', 'Specific mode to set')
+  .action((options) => modeCommand('set', options));
+
+modeCmd
+  .command('compare')
+  .description('Compare all available tiers')
+  .action(() => modeCommand('compare', {}));
+
+modeCmd
+  .command('recommend')
+  .description('Get tier recommendation for your project')
+  .option('--size <size>', 'Project size (small, medium, large)', 'medium')
+  .option('--team-size <size>', 'Team size (number)', '1')
+  .option('--compliance <required>', 'Compliance requirements (true/false)', 'false')
+  .option('--audit <required>', 'Audit requirements (true/false)', 'false')
+  .option('--details', 'Show detailed recommendation', false)
+  .action((options) => modeCommand('recommend', options));
+
+modeCmd
+  .command('details <mode>')
+  .description('Show detailed information about a specific tier')
+  .action((mode) => modeCommand('details', { mode }));
+
+// Tutorial command
+program
+  .command('tutorial [type]')
+  .description('Interactive guided learning for CAWS')
+  .action(tutorialCommand);
+
+// Plan command
+program
+  .command('plan <action>')
+  .description('Generate implementation plans')
+  .option('--spec-id <id>', 'Spec ID to generate plan for')
+  .option('--spec <id>', 'Alias for --spec-id')
+  .option('--output <path>', 'Output file path for the plan')
+  .action((action, options) => planCommand(action, options));
+
 // Templates command
 program
   .command('templates [subcommand]')
@@ -140,6 +340,7 @@ program
 program
   .command('diagnose')
   .description('Run health checks and suggest fixes')
+  .option('--spec-id <id>', 'Feature-specific spec ID')
   .option('--fix', 'Apply automatic fixes', false)
   .action(diagnoseCommand);
 
@@ -147,13 +348,15 @@ program
 program
   .command('evaluate [spec-file]')
   .description('Evaluate work against CAWS quality standards')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('-v, --verbose', 'Show detailed error information', false)
   .action(evaluateCommand);
 
 // Iterate command
 program
   .command('iterate [spec-file]')
-  .description('Get iterative development guidance based on current progress')
+  .description('Get iterative development guidance')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--current-state <json>', 'Current implementation state as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
   .action(iterateCommand);
@@ -202,7 +405,8 @@ waiversCmd
 // Workflow command group
 const workflowCmd = program
   .command('workflow <type>')
-  .description('Get workflow-specific guidance for development tasks')
+  .description('Get workflow-specific guidance')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--step <number>', 'Current step in workflow', '1')
   .option('--current-state <json>', 'Current implementation state as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
@@ -212,6 +416,7 @@ const workflowCmd = program
 program
   .command('quality-monitor <action>')
   .description('Monitor code quality impact in real-time')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--files <files>', 'Files affected (comma-separated)')
   .option('--context <json>', 'Additional context as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
@@ -236,13 +441,12 @@ program
 // Test Analysis command
 program
   .command('test-analysis <subcommand> [options...]')
-  .description('Statistical analysis for budget prediction and test optimization')
+  .description('Statistical analysis for budget prediction')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .action(testAnalysisCommand);
 
 // Provenance command group
-const provenanceCmd = program
-  .command('provenance')
-  .description('Manage CAWS provenance tracking and audit trails');
+const provenanceCmd = program.command('provenance').description('Manage CAWS provenance tracking');
 
 // Subcommands
 provenanceCmd
@@ -380,6 +584,11 @@ program.exitOverride((err) => {
       'validate',
       'scaffold',
       'status',
+      'archive',
+      'specs',
+      'mode',
+      'tutorial',
+      'plan',
       'templates',
       'diagnose',
       'evaluate',
@@ -475,6 +684,12 @@ if (require.main === module) {
         'init',
         'validate',
         'scaffold',
+        'status',
+        'archive',
+        'specs',
+        'mode',
+        'tutorial',
+        'plan',
         'provenance',
         'hooks',
         'burnup',