@paths.design/caws-cli 5.0.1 → 6.0.0

package/dist/commands/specs.js

@@ -9,6 +9,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { safeAsync, outputResult } = require('../error-handler');
+const { question, closeReadline } = require('../utils/promise-utils');
 const { SPEC_TYPES } = require('../constants/spec-types');
 
 // Import suggestFeatureBreakdown from spec-resolver
@@ -488,42 +489,40 @@ async function migrateFromLegacy(options = {}) {
  * @returns {Promise<string>} User's choice: 'cancel', 'rename', 'merge', 'override'
  */
 async function askConflictResolution() {
-  return new Promise((resolve) => {
-    const readline = require('readline');
-
-    console.log(chalk.blue('\n🔄 Conflict Resolution Options:'));
-    console.log(chalk.gray("   1. Cancel - Don't create the spec"));
-    console.log(chalk.gray('   2. Rename - Create with auto-generated name'));
-    console.log(chalk.gray('   3. Merge - Merge with existing spec (not implemented)'));
-    console.log(chalk.gray('   4. Override - Replace existing spec (use --force)'));
-
-    console.log(chalk.yellow('\nEnter your choice (1-4) or the option name:'));
-
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    rl.question('> ', (answer) => {
-      rl.close();
-
-      const trimmed = answer.trim().toLowerCase();
-
-      // Handle numeric choices
-      if (trimmed === '1' || trimmed === 'cancel') {
-        resolve('cancel');
-      } else if (trimmed === '2' || trimmed === 'rename') {
-        resolve('rename');
-      } else if (trimmed === '3' || trimmed === 'merge') {
-        resolve('merge');
-      } else if (trimmed === '4' || trimmed === 'override') {
-        resolve('override');
-      } else {
-        console.log(chalk.red('❌ Invalid choice. Defaulting to cancel.'));
-        resolve('cancel');
-      }
-    });
+  const readline = require('readline');
+
+  console.log(chalk.blue('\n🔄 Conflict Resolution Options:'));
+  console.log(chalk.gray("   1. Cancel - Don't create the spec"));
+  console.log(chalk.gray('   2. Rename - Create with auto-generated name'));
+  console.log(chalk.gray('   3. Merge - Merge with existing spec (not implemented)'));
+  console.log(chalk.gray('   4. Override - Replace existing spec (use --force)'));
+  console.log(chalk.yellow('\nEnter your choice (1-4) or the option name:'));
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
   });
+
+  try {
+    const answer = await question(rl, '> ');
+    const trimmed = answer.trim().toLowerCase();
+
+    // Handle numeric choices
+    if (trimmed === '1' || trimmed === 'cancel') {
+      return 'cancel';
+    } else if (trimmed === '2' || trimmed === 'rename') {
+      return 'rename';
+    } else if (trimmed === '3' || trimmed === 'merge') {
+      return 'merge';
+    } else if (trimmed === '4' || trimmed === 'override') {
+      return 'override';
+    } else {
+      console.log(chalk.red('❌ Invalid choice. Defaulting to cancel.'));
+      return 'cancel';
+    }
+  } finally {
+    await closeReadline(rl);
+  }
 }
 
 /**

package/dist/commands/status.js

@@ -9,6 +9,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { safeAsync, outputResult } = require('../error-handler');
+const { parallel } = require('../utils/async-utils');
 
 /**
  * Load working specification (legacy single file approach)
@@ -758,13 +759,15 @@ async function statusCommand(options = {}) {
       const modes = require('../config/modes');
       const currentMode = await modes.getCurrentMode();
 
-      // Load all status data
-      const spec = await loadWorkingSpec(options.spec || '.caws/working-spec.yaml');
-      const specs = await loadSpecsFromMultiSpec();
-      const hooks = await checkGitHooks();
-      const provenance = await loadProvenanceChain();
-      const waivers = await loadWaiverStatus();
-      const gates = await checkQualityGates();
+      // Load all status data in parallel for better performance
+      const [spec, specs, hooks, provenance, waivers, gates] = await parallel([
+        () => loadWorkingSpec(options.spec || '.caws/working-spec.yaml'),
+        () => loadSpecsFromMultiSpec(),
+        () => checkGitHooks(),
+        () => loadProvenanceChain(),
+        () => loadWaiverStatus(),
+        () => checkQualityGates(),
+      ]);
 
       // Display status (visual mode if requested)
       if (options.visual || options.json) {

package/dist/commands/tool.js

@@ -5,7 +5,7 @@
  */
 
 const path = require('path');
-const chalk = require('chalk');
+const { commandWrapper, Output } = require('../utils/command-wrapper');
 
 // Import tool system
 const ToolLoader = require('../tool-loader');
@@ -32,16 +32,19 @@ async function initializeToolSystem() {
     // Set up event listeners for tool system
     toolLoader.on('discovery:complete', ({ tools: _tools, count }) => {
       if (count > 0) {
-        console.log(chalk.blue(`🔧 Discovered ${count} tools`));
+        Output.info(`Discovered ${count} tools`);
       }
     });
 
     toolLoader.on('tool:loaded', ({ id, metadata }) => {
-      console.log(chalk.gray(`  ✓ Loaded tool: ${metadata.name} (${id})`));
+      // Only log in verbose mode or when not using JSON output
+      if (!process.env.CAWS_OUTPUT_FORMAT || process.env.CAWS_OUTPUT_FORMAT !== 'json') {
+        console.log(`  ✓ Loaded tool: ${metadata.name} (${id})`);
+      }
     });
 
     toolLoader.on('tool:error', ({ id, error }) => {
-      console.warn(chalk.yellow(`⚠️  Failed to load tool ${id}: ${error}`));
+      Output.warning(`Failed to load tool ${id}: ${error}`);
     });
 
     // Auto-discover tools on initialization
@@ -49,8 +52,10 @@ async function initializeToolSystem() {
 
     return toolLoader;
   } catch (error) {
-    console.warn(chalk.yellow('⚠️  Tool system initialization failed:'), error.message);
-    console.warn(chalk.blue('💡 Continuing without dynamic tools'));
+    Output.warning(
+      `Tool system initialization failed: ${error.message}`,
+      'Continuing without dynamic tools'
+    );
     return null;
   }
 }
@@ -61,75 +66,70 @@ async function initializeToolSystem() {
  * @param {Object} options - Command options
  */
 async function executeTool(toolId, options) {
-  try {
-    // Initialize tool system
-    const loader = await initializeToolSystem();
+  return commandWrapper(
+    async () => {
+      // Initialize tool system
+      const loader = await initializeToolSystem();
 
-    if (!loader) {
-      console.error(chalk.red('❌ Tool system not available'));
-      process.exit(1);
-    }
+      if (!loader) {
+        throw new Error('Tool system not available');
+      }
 
-    // Load all tools first
-    await loader.loadAllTools();
-    const tool = loader.getTool(toolId);
+      // Load all tools first
+      await loader.loadAllTools();
+      const tool = loader.getTool(toolId);
 
-    if (!tool) {
-      console.error(chalk.red(`❌ Tool '${toolId}' not found`));
-      console.log(chalk.blue('💡 Available tools:'));
-      const tools = loader.getAllTools();
-      for (const [id, t] of tools) {
-        console.log(`   - ${id}: ${t.metadata.name}`);
+      if (!tool) {
+        const tools = loader.getAllTools();
+        const availableTools = Array.from(tools, ([id, t]) => `${id}: ${t.metadata.name}`).join(
+          ', '
+        );
+        throw new Error(`Tool '${toolId}' not found.\n` + `Available tools: ${availableTools}`);
       }
-      process.exit(1);
-    }
 
-    // Validate tool before execution
-    const validation = await toolValidator.validateTool(tool);
-    if (!validation.valid) {
-      console.error(chalk.red('❌ Tool validation failed:'));
-      validation.errors.forEach((error) => {
-        console.error(`   ${chalk.red('✗')} ${error}`);
-      });
-      process.exit(1);
-    }
+      // Validate tool before execution
+      const validation = await toolValidator.validateTool(tool);
+      if (!validation.valid) {
+        throw new Error(
+          `Tool validation failed:\n` + validation.errors.map((e) => `  - ${e}`).join('\n')
+        );
+      }
 
-    // Parse parameters
-    let params = {};
-    if (options.params) {
-      try {
-        params = JSON.parse(options.params);
-      } catch (error) {
-        console.error(chalk.red('❌ Invalid JSON parameters:'), error.message);
-        process.exit(1);
+      // Parse parameters
+      let params = {};
+      if (options.params) {
+        try {
+          params = JSON.parse(options.params);
+        } catch (error) {
+          throw new Error(`Invalid JSON parameters: ${error.message}`);
+        }
       }
-    }
 
-    console.log(chalk.blue(`🚀 Executing tool: ${tool.metadata.name}`));
+      Output.progress(`Executing tool: ${tool.metadata.name}`);
 
-    // Execute tool
-    const result = await tool.module.execute(params, {
-      workingDirectory: process.cwd(),
-      timeout: options.timeout,
-    });
+      // Execute tool
+      const result = await tool.module.execute(params, {
+        workingDirectory: process.cwd(),
+        timeout: options.timeout,
+      });
 
-    // Display results
-    if (result.success) {
-      console.log(chalk.green('✅ Tool execution successful'));
-      if (result.output && typeof result.output === 'object') {
-        console.log(chalk.gray('Output:'), JSON.stringify(result.output, null, 2));
+      // Display results
+      if (result.success) {
+        Output.success('Tool execution successful', {
+          output: result.output,
+        });
+        return result;
+      } else {
+        throw new Error(
+          `Tool execution failed:\n` + result.errors.map((e) => `  - ${e}`).join('\n')
+        );
       }
-    } else {
-      console.error(chalk.red('❌ Tool execution failed'));
-      result.errors.forEach((error) => {
-        console.error(`   ${chalk.red('✗')} ${error}`);
-      });
-      process.exit(1);
+    },
+    {
+      commandName: `tool ${toolId}`,
+      context: { toolId, options },
     }
-  } catch (error) {
-    console.error(chalk.red(`❌ Error executing tool ${toolId}:`), error.message);
-    process.exit(1);
-  }
+  );
 }
 
 module.exports = {

package/dist/commands/waivers.js

@@ -14,6 +14,7 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
 const WaiversManager = require('../waivers-manager');
+const { commandWrapper, Output } = require('../utils/command-wrapper');
 
 const WAIVER_DIR = '.caws/waivers';
 
@@ -24,46 +25,44 @@ const WAIVER_DIR = '.caws/waivers';
  * @param {object} options - Command options
  */
 async function waiversCommand(subcommand = 'list', 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(', ')}`);
-    }
-
-    // Ensure waivers directory exists
-    const waiversDir = path.join(process.cwd(), WAIVER_DIR);
-    if (!fs.existsSync(waiversDir)) {
-      fs.mkdirSync(waiversDir, { recursive: true });
-    }
-
-    switch (subcommand) {
-      case 'create':
-        await createWaiver(options);
-        break;
-      case 'list':
-        await listWaivers(options);
-        break;
-      case 'show':
-        await showWaiver(options.id, options);
-        break;
-      case 'revoke':
-        await revokeWaiver(options.id, options);
-        break;
-      default:
-        console.error(chalk.red(`\n❌ Unknown waiver subcommand: ${subcommand}`));
-        console.log(chalk.yellow('\n💡 Available subcommands: create, list, show, revoke'));
-        process.exit(1);
+  return commandWrapper(
+    async () => {
+      Output.info('Detecting CAWS setup...');
+      const setup = initializeGlobalSetup();
+
+      if (setup.hasWorkingSpec) {
+        Output.success(`Detected ${setup.setupType} CAWS setup`, {
+          capabilities: setup.capabilities,
+        });
+      }
+
+      // Ensure waivers directory exists
+      const waiversDir = path.join(process.cwd(), WAIVER_DIR);
+      if (!fs.existsSync(waiversDir)) {
+        fs.mkdirSync(waiversDir, { recursive: true });
+      }
+
+      switch (subcommand) {
+        case 'create':
+          return await createWaiver(options);
+        case 'list':
+          return await listWaivers(options);
+        case 'show':
+          return await showWaiver(options.id, options);
+        case 'revoke':
+          return await revokeWaiver(options.id, options);
+        default:
+          throw new Error(
+            `Unknown waiver subcommand: ${subcommand}.\n` +
+            'Available subcommands: create, list, show, revoke'
+          );
+      }
+    },
+    {
+      commandName: `waivers ${subcommand}`,
+      context: { subcommand, options },
     }
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Waiver command failed: ${error.message}`));
-    if (options.verbose) {
-      console.error(error.stack);
-    }
-    process.exit(1);
-  }
+  );
 }
 
 /**

package/dist/index.js

@@ -114,6 +114,7 @@ program
   .option('--minimal', 'Only essential components', false)
   .option('--with-codemods', 'Include codemod scripts', false)
   .option('--with-oidc', 'Include OIDC trusted publisher setup', false)
+  .option('--with-quality-gates', 'Install quality gates package and scripts', false)
   .action(scaffoldProject);
 
 // Validate command

package/dist/policy/PolicyManager.js

@@ -54,51 +54,83 @@ class PolicyManager {
         }
       }
 
-      // Load from file
-      const policyPath = path.join(projectRoot, '.caws', 'policy.yaml');
-
-      try {
-        const content = await fs.readFile(policyPath, 'utf-8');
-        const policy = yaml.load(content);
+      // Load from file - check multiple locations for backward compatibility
+      const policyPaths = [
+        path.join(projectRoot, '.caws', 'policy.yaml'), // Preferred location
+        path.join(projectRoot, '.caws', 'policy', 'tier-policy.json'), // Legacy location
+      ];
+
+      let policyPath = null;
+      let policyContent = null;
+
+      // Try each path in order
+      for (const candidatePath of policyPaths) {
+        try {
+          if (await fs.pathExists(candidatePath)) {
+            policyPath = candidatePath;
+            const content = await fs.readFile(candidatePath, 'utf-8');
+
+            // Handle JSON format (legacy)
+            if (candidatePath.endsWith('.json')) {
+              policyContent = JSON.parse(content);
+            } else {
+              // Handle YAML format (preferred)
+              policyContent = yaml.load(content);
+            }
+            break;
+          }
+        } catch (error) {
+          // Continue to next path if this one fails
+          continue;
+        }
+      }
 
+      if (policyPath && policyContent) {
         // Validate policy structure
-        this.validatePolicy(policy);
+        this.validatePolicy(policyContent);
 
         // Update cache
         if (this.enableCaching) {
           this.policyCache.set(projectRoot, {
-            policy,
+            policy: policyContent,
             cachedAt: Date.now(),
             ttl: cacheTTL,
           });
         }
 
+        // Warn if using legacy location
+        if (policyPath.endsWith('.json')) {
+          console.warn(
+            '⚠️  Using legacy policy file location: .caws/policy/tier-policy.json\n' +
+              '   Migrate to .caws/policy.yaml for better compatibility\n' +
+              '   Run: caws init --migrate-policy'
+          );
+        }
+
         return {
-          ...policy,
+          ...policyContent,
           _cacheHit: false,
           _loadDuration: Date.now() - startTime,
+          _policyPath: policyPath,
         };
-      } catch (error) {
-        if (error.code === 'ENOENT') {
-          // Policy file doesn't exist - use default
-          const defaultPolicy = this.getDefaultPolicy();
-
-          if (this.enableCaching) {
-            this.policyCache.set(projectRoot, {
-              policy: defaultPolicy,
-              cachedAt: Date.now(),
-              ttl: cacheTTL,
-            });
-          }
+      } else {
+        // Policy file doesn't exist - use default
+        const defaultPolicy = this.getDefaultPolicy();
 
-          return {
-            ...defaultPolicy,
-            _isDefault: true,
-            _cacheHit: false,
-            _loadDuration: Date.now() - startTime,
-          };
+        if (this.enableCaching) {
+          this.policyCache.set(projectRoot, {
+            policy: defaultPolicy,
+            cachedAt: Date.now(),
+            ttl: cacheTTL,
+          });
         }
-        throw error;
+
+        return {
+          ...defaultPolicy,
+          _isDefault: true,
+          _cacheHit: false,
+          _loadDuration: Date.now() - startTime,
+        };
       }
     } catch (error) {
       throw new Error(`Policy load failed: ${error.message}`);

package/dist/scaffold/git-hooks.js

@@ -117,6 +117,7 @@ async function scaffoldGitHooks(projectDir, options = {}) {
 
 /**
  * Generate pre-commit hook content with staged file quality gates
+ * Implements fallback chain: Node script → CLI → Python scripts → Skip gracefully
  */
 function generatePreCommitHook(options) {
   const { qualityGates = true, stagedOnly = true } = options;
@@ -124,6 +125,7 @@ function generatePreCommitHook(options) {
   return `#!/bin/bash
 # CAWS Pre-commit Hook
 # Runs validation and quality checks before commits
+# Implements graceful fallback chain to avoid blocking commits
 
 set -e
 
@@ -136,39 +138,87 @@ if [ ! -d ".caws" ]; then
   exit 0
 fi
 
-# Run quality gates
-if command -v node >/dev/null 2>&1; then
-  if node scripts/quality-gates/run-quality-gates.js; then
-    echo "✅ Quality gates passed"
+# Fallback chain for quality gates:
+# 1. Try Node.js script (if exists)
+# 2. Try CAWS CLI
+# 3. Try Makefile target
+# 4. Try Python scripts
+# 5. Skip gracefully (warn only)
+
+QUALITY_GATES_RAN=false
+
+# Option 1: Node.js quality gates script
+if [ -f "scripts/quality-gates/run-quality-gates.js" ]; then
+  if command -v node >/dev/null 2>&1; then
+    echo "📁 Running Node.js quality gates script..."
+    if node scripts/quality-gates/run-quality-gates.js; then
+      echo "✅ Quality gates passed"
+      QUALITY_GATES_RAN=true
+    else
+      echo "❌ Quality gates failed - commit blocked"
+      echo "💡 Fix the violations above before committing"
+      exit 1
+    fi
+  fi
+# Option 2: CAWS CLI validation
+elif command -v caws >/dev/null 2>&1; then
+  echo "📋 Running CAWS CLI validation..."
+  if caws validate --quiet 2>/dev/null; then
+    echo "✅ CAWS validation passed"
+    QUALITY_GATES_RAN=true
   else
-    echo "❌ Quality gates failed - commit blocked"
-    echo "💡 Fix the violations above before committing"
-    echo "📖 See docs/refactoring.md for crisis response plan"
-    exit 1
+    echo "⚠️  CAWS validation failed, but allowing commit (non-blocking)"
+    echo "💡 Run 'caws validate' for details"
+    QUALITY_GATES_RAN=true
+  fi
+# Option 3: Makefile target
+elif [ -f "Makefile" ] && grep -q "caws-validate\\|caws-gates" Makefile; then
+  echo "🔧 Running Makefile quality gates..."
+  if make caws-validate >/dev/null 2>&1 || make caws-gates >/dev/null 2>&1; then
+    echo "✅ Makefile quality gates passed"
+    QUALITY_GATES_RAN=true
+  else
+    echo "⚠️  Makefile quality gates failed, but allowing commit (non-blocking)"
+    QUALITY_GATES_RAN=true
+  fi
+# Option 4: Python scripts
+elif [ -f "scripts/simple_gates.py" ] && command -v python3 >/dev/null 2>&1; then
+  echo "🐍 Running Python quality gates script..."
+  if python3 scripts/simple_gates.py all --tier 2 --profile backend-api >/dev/null 2>&1; then
+    echo "✅ Python quality gates passed"
+    QUALITY_GATES_RAN=true
+  else
+    echo "⚠️  Python quality gates failed, but allowing commit (non-blocking)"
+    QUALITY_GATES_RAN=true
   fi
+# Option 5: Skip gracefully
 else
-  echo "⚠️  Node.js not found - skipping quality gates"
-  echo "💡 Install Node.js to enable automatic quality checking"
-  exit 0
+  echo "⚠️  Quality gates not available - skipping"
+  echo "💡 Available options:"
+  echo "   • Install: npm install -g @paths.design/caws-cli"
+  echo "   • Use Python: python3 scripts/simple_gates.py"
+  echo "   • Use Makefile: make caws-gates"
+  QUALITY_GATES_RAN=true
 fi
 
-# Run hidden TODO analysis on staged files only
-echo "🔍 Checking for hidden TODOs in staged files..."
-if command -v python3 >/dev/null 2>&1; then
-  if python3 scripts/v3/analysis/todo_analyzer.py --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
-    echo "✅ No critical hidden TODOs found in staged files"
-  else
-    echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
-    echo "💡 Fix stub implementations and placeholder code before committing"
-    echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
-    echo ""
-    echo "🔍 Running detailed analysis on staged files..."
-    python3 scripts/v3/analysis/todo_analyzer.py --staged-only --min-confidence 0.8
-    exit 1
+# Run hidden TODO analysis on staged files only (if Python available)
+if [ "$QUALITY_GATES_RAN" = true ]; then
+  echo "🔍 Checking for hidden TODOs in staged files..."
+  if command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+    if python3 scripts/v3/analysis/todo_analyzer.py --staged-only --ci-mode --min-confidence 0.8 >/dev/null 2>&1; then
+      echo "✅ No critical hidden TODOs found in staged files"
+    else
+      echo "❌ Critical hidden TODOs detected in staged files - commit blocked"
+      echo "💡 Fix stub implementations and placeholder code before committing"
+      echo "📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification"
+      echo ""
+      echo "🔍 Running detailed analysis on staged files..."
+      python3 scripts/v3/analysis/todo_analyzer.py --staged-only --min-confidence 0.8
+      exit 1
+    fi
+  elif command -v python3 >/dev/null 2>&1; then
+    echo "⚠️  Python3 found but TODO analyzer not available - skipping"
   fi
-else
-  echo "⚠️  Python3 not found - skipping hidden TODO analysis"
-  echo "💡 Install Python3 to enable automatic TODO checking"
 fi
 
 echo "✅ All quality checks passed - proceeding with commit"
@@ -280,6 +330,18 @@ if [ -f "package.json" ]; then
       # Don't fail on warnings, just warn
     fi
   fi
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  # Python project security checks
+  if command -v pip-audit >/dev/null 2>&1; then
+    echo "🔍 Checking Python vulnerabilities..."
+    pip-audit --desc 2>/dev/null || echo "⚠️  Install pip-audit for vulnerability checks: pip install pip-audit"
+  fi
+elif [ -f "Cargo.toml" ]; then
+  # Rust project security checks
+  if command -v cargo-audit >/dev/null 2>&1; then
+    echo "🔍 Checking Rust vulnerabilities..."
+    cargo audit 2>/dev/null || echo "⚠️  Install cargo-audit for vulnerability checks: cargo install cargo-audit"
+  fi
 fi
 
 echo "🎉 Pre-push checks completed!"