@paths.design/caws-cli 5.0.1 → 6.0.0

package/dist/scaffold/index.js

@@ -330,6 +330,31 @@ async function scaffoldProject(options) {
       required: false,
     });
 
+    // Install quality gates package if requested
+    if (options.withQualityGates) {
+      console.log(chalk.blue('\n📦 Installing quality gates package...'));
+      try {
+        const { execSync } = require('child_process');
+        const npmCommand = fs.existsSync(path.join(currentDir, 'package.json'))
+          ? 'npm install --save-dev @paths.design/quality-gates'
+          : 'npm install -g @paths.design/quality-gates';
+
+        console.log(chalk.gray(`   Running: ${npmCommand}`));
+        execSync(npmCommand, {
+          cwd: currentDir,
+          stdio: 'inherit',
+        });
+        console.log(chalk.green('✅ Quality gates package installed'));
+        console.log(chalk.blue('💡 You can now use: caws quality-gates'));
+      } catch (error) {
+        console.log(chalk.yellow(`⚠️  Failed to install quality gates package: ${error.message}`));
+        console.log(
+          chalk.gray('   You can install manually: npm install -g @paths.design/quality-gates')
+        );
+        console.log(chalk.gray('   Or use Python scripts: python3 scripts/simple_gates.py'));
+      }
+    }
+
     // Add commit conventions for setups that don't have them
     if (!setup.hasTemplates || !fs.existsSync(path.join(currentDir, 'COMMIT_CONVENTIONS.md'))) {
       enhancements.push({

package/dist/utils/async-utils.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Async Operation Utilities
+ * Provides consistent patterns for async operations, parallel execution, and resource cleanup
+ * @author @darianrosebrook
+ */
+
+/**
+ * Execute multiple async operations in parallel
+ * @param {Array<Promise>} promises - Array of promises to execute
+ * @param {Object} options - Options
+ * @param {boolean} [options.failFast=true] - Stop on first error
+ * @returns {Promise<Array>} Array of results
+ */
+async function parallel(promises, options = {}) {
+  const { failFast = true } = options;
+
+  if (failFast) {
+    return Promise.all(promises);
+  } else {
+    // Wait for all promises, collecting both successes and failures
+    return Promise.allSettled(promises).then((results) => {
+      return results.map((result) => {
+        if (result.status === 'fulfilled') {
+          return { success: true, value: result.value };
+        } else {
+          return { success: false, error: result.reason };
+        }
+      });
+    });
+  }
+}
+
+/**
+ * Execute async operations sequentially
+ * @param {Array<Function>} operations - Array of async functions to execute
+ * @param {Object} options - Options
+ * @param {boolean} [options.stopOnError=true] - Stop on first error
+ * @returns {Promise<Array>} Array of results
+ */
+async function sequential(operations, options = {}) {
+  const { stopOnError = true } = options;
+  const results = [];
+
+  for (const operation of operations) {
+    try {
+      const result = await operation();
+      results.push({ success: true, value: result });
+    } catch (error) {
+      if (stopOnError) {
+        throw error;
+      }
+      results.push({ success: false, error });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ * @param {Function} operation - Async function to retry
+ * @param {Object} options - Retry options
+ * @param {number} [options.maxRetries=3] - Maximum number of retries
+ * @param {number} [options.initialDelay=1000] - Initial delay in ms
+ * @param {number} [options.maxDelay=10000] - Maximum delay in ms
+ * @param {Function} [options.shouldRetry] - Function to determine if error should be retried
+ * @returns {Promise<any>} Operation result
+ */
+async function retry(operation, options = {}) {
+  const {
+    maxRetries = 3,
+    initialDelay = 1000,
+    maxDelay = 10000,
+    shouldRetry = () => true,
+  } = options;
+
+  let lastError;
+  let delay = initialDelay;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxRetries || !shouldRetry(error)) {
+        throw error;
+      }
+
+      // Wait before retrying with exponential backoff
+      // eslint-disable-next-line no-undef
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay = Math.min(delay * 2, maxDelay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Execute operation with timeout
+ * @param {Promise} promise - Promise to execute
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @param {string} [errorMessage] - Custom error message
+ * @returns {Promise<any>} Operation result
+ */
+async function withTimeout(promise, timeoutMs, errorMessage = 'Operation timed out') {
+  const timeoutPromise = new Promise((_, reject) => {
+    // eslint-disable-next-line no-undef
+    setTimeout(() => {
+      reject(new Error(`${errorMessage} (${timeoutMs}ms)`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]);
+}
+
+/**
+ * Execute operation with resource cleanup
+ * @param {Function} operation - Async operation to execute
+ * @param {Function} cleanup - Cleanup function (called in finally)
+ * @returns {Promise<any>} Operation result
+ */
+async function withCleanup(operation, cleanup) {
+  try {
+    return await operation();
+  } finally {
+    await cleanup();
+  }
+}
+
+/**
+ * Execute multiple operations and collect all errors
+ * @param {Array<Function>} operations - Array of async functions
+ * @returns {Promise<{successes: Array, errors: Array}>} Results and errors
+ */
+async function collectResults(operations) {
+  const results = await Promise.allSettled(
+    operations.map((op) => op())
+  );
+
+  const successes = [];
+  const errors = [];
+
+  results.forEach((result, index) => {
+    if (result.status === 'fulfilled') {
+      successes.push({ index, value: result.value });
+    } else {
+      errors.push({ index, error: result.reason });
+    }
+  });
+
+  return { successes, errors };
+}
+
+/**
+ * Execute operation with cancellation support
+ * @param {Function} operation - Async operation to execute
+ * @param {AbortSignal} signal - Abort signal for cancellation
+ * @returns {Promise<any>} Operation result
+ */
+async function withCancellation(operation, signal) {
+  if (signal.aborted) {
+    throw new Error('Operation cancelled');
+  }
+
+  return new Promise((resolve, reject) => {
+    signal.addEventListener('abort', () => {
+      reject(new Error('Operation cancelled'));
+    });
+
+    operation()
+      .then(resolve)
+      .catch(reject);
+  });
+}
+
+module.exports = {
+  parallel,
+  sequential,
+  retry,
+  withTimeout,
+  withCleanup,
+  collectResults,
+  withCancellation,
+};
+
+

package/dist/utils/command-wrapper.js

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Unified Command Wrapper
+ * Provides consistent error handling and output formatting for all CLI commands
+ * @author @darianrosebrook
+ */
+
+const { safeAsync, handleCliError, outputResult, isJsonOutput } = require('../error-handler');
+const chalk = require('chalk');
+
+/**
+ * Unified command wrapper that provides:
+ * - Consistent error handling
+ * - Standardized output formatting
+ * - Execution timing
+ * - JSON output support
+ *
+ * @param {Function} commandFn - Async command function to execute
+ * @param {Object} options - Command options
+ * @param {string} options.commandName - Name of the command (for error context)
+ * @param {boolean} [options.includeTiming=true] - Include execution timing
+ * @param {boolean} [options.exitOnError=true] - Exit process on error
+ * @param {Object} [options.context={}] - Additional context for error handling
+ * @returns {Promise<any>} Command result
+ */
+async function commandWrapper(commandFn, options = {}) {
+  const {
+    commandName = 'command',
+    includeTiming = true,
+    exitOnError = true,
+    context = {},
+  } = options;
+
+  return safeAsync(
+    async () => {
+      try {
+        const result = await commandFn();
+        return result;
+      } catch (error) {
+        // Enhance error with command context
+        error.commandName = commandName;
+        error.context = { ...context, ...error.context };
+
+        // Handle error with unified handler
+        handleCliError(
+          error,
+          {
+            command: commandName,
+            ...context,
+          },
+          exitOnError
+        );
+
+        // If exitOnError is false, rethrow for caller to handle
+        if (!exitOnError) {
+          throw error;
+        }
+      }
+    },
+    commandName,
+    includeTiming
+  );
+}
+
+/**
+ * Unified output utilities for consistent formatting
+ */
+const Output = {
+  /**
+   * Output success message
+   * @param {string} message - Success message
+   * @param {Object} [data] - Additional data to output
+   */
+  success(message, data = {}) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          success: true,
+          message,
+          ...data,
+        },
+        true
+      );
+    } else {
+      console.log(chalk.green(`✅ ${message}`));
+      if (Object.keys(data).length > 0 && !isJsonOutput()) {
+        console.log(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+  },
+
+  /**
+   * Output error message
+   * @param {string} message - Error message
+   * @param {string[]} [suggestions] - Recovery suggestions
+   */
+  error(message, suggestions = []) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          success: false,
+          error: {
+            message,
+            suggestions,
+          },
+        },
+        false
+      );
+    } else {
+      console.error(chalk.red(`❌ ${message}`));
+      if (suggestions.length > 0) {
+        console.error(chalk.yellow('\n💡 Suggestions:'));
+        suggestions.forEach((suggestion) => {
+          console.error(chalk.yellow(`   ${suggestion}`));
+        });
+      }
+    }
+  },
+
+  /**
+   * Output warning message
+   * @param {string} message - Warning message
+   * @param {string} [suggestion] - Optional suggestion
+   */
+  warning(message, suggestion = null) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          warning: true,
+          message,
+          suggestion,
+        },
+        true
+      );
+    } else {
+      console.warn(chalk.yellow(`⚠️  ${message}`));
+      if (suggestion) {
+        console.warn(chalk.blue(`   💡 ${suggestion}`));
+      }
+    }
+  },
+
+  /**
+   * Output info message
+   * @param {string} message - Info message
+   * @param {Object} [data] - Additional data
+   */
+  info(message, data = {}) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          info: true,
+          message,
+          ...data,
+        },
+        true
+      );
+    } else {
+      console.log(chalk.blue(`ℹ️  ${message}`));
+      if (Object.keys(data).length > 0) {
+        console.log(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+  },
+
+  /**
+   * Output data in JSON format
+   * @param {Object} data - Data to output
+   * @param {boolean} [success=true] - Whether operation was successful
+   */
+  json(data, success = true) {
+    outputResult(data, success);
+  },
+
+  /**
+   * Output progress message
+   * @param {string} message - Progress message
+   */
+  progress(message) {
+    if (!isJsonOutput()) {
+      console.log(chalk.blue(`🔄 ${message}`));
+    }
+  },
+
+  /**
+   * Output section header
+   * @param {string} title - Section title
+   */
+  section(title) {
+    if (!isJsonOutput()) {
+      console.log(chalk.bold(`\n${title}`));
+      console.log('─'.repeat(Math.min(title.length, 60)));
+    }
+  },
+};
+
+module.exports = {
+  commandWrapper,
+  Output,
+  isJsonOutput,
+};

package/dist/utils/promise-utils.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Promise Utilities
+ * Utilities for converting callback-based APIs to promises
+ * @author @darianrosebrook
+ */
+
+/**
+ * Convert readline question to promise
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @returns {Promise<string>} User's answer
+ */
+function question(rl, questionText) {
+  return new Promise((resolve) => {
+    rl.question(questionText, (answer) => {
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Close readline interface and return promise
+ * @param {readline.Interface} rl - Readline interface
+ * @returns {Promise<void>}
+ */
+function closeReadline(rl) {
+  return new Promise((resolve) => {
+    rl.once('close', resolve);
+    rl.close();
+  });
+}
+
+/**
+ * Create a promise that resolves when event fires
+ * @param {EventEmitter} emitter - Event emitter
+ * @param {string} event - Event name
+ * @param {Object} options - Options
+ * @param {number} [options.timeout] - Timeout in ms
+ * @returns {Promise<any>} Event data
+ */
+function once(emitter, event, options = {}) {
+  return new Promise((resolve, reject) => {
+    const { timeout } = options;
+
+    const timeoutId = timeout
+      ? // eslint-disable-next-line no-undef
+        setTimeout(() => {
+          emitter.removeListener(event, handler);
+          reject(new Error(`Event '${event}' timed out after ${timeout}ms`));
+        }, timeout)
+      : null;
+
+    const handler = (...args) => {
+      if (timeoutId) {
+        // eslint-disable-next-line no-undef
+        clearTimeout(timeoutId);
+      }
+      emitter.removeListener(event, handler);
+      resolve(args.length === 1 ? args[0] : args);
+    };
+
+    emitter.once(event, handler);
+  });
+}
+
+module.exports = {
+  question,
+  closeReadline,
+  once,
+};
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "5.0.1",
+  "version": "6.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {

package/templates/.cursor/hooks/block-dangerous.sh

@@ -16,12 +16,19 @@ COMMAND=$(echo "$INPUT" | jq -r '.command // ""')
 CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
 
 # Hard blocks - never allow these
+# CRITICAL: These commands can cause catastrophic data loss
+# git init, git reset --hard, and git push --force were added after an incident
+# where an agent panicked at quality gates and wiped thousands of lines of work
 HARD_BLOCKS=(
   "rm -rf /"
   "rm -rf /*"
   "rm -rf ~"
   "rm -rf $HOME"
   "> /dev/sda"
+  "git init"                    # Can wipe entire git history and stashed changes
+  "git commit --amend --no-edit" # Can rewrite commit history destructively
+  "git reset --hard"            # Can lose uncommitted work and stashed changes
+  "git push --force"             # Can overwrite remote repository history
   "dd if="
   "mkfs"
   "format c:"
@@ -38,10 +45,9 @@ for blocked in "${HARD_BLOCKS[@]}"; do
 done
 
 # Ask permission for risky operations
+# Note: git commands moved to HARD_BLOCKS after catastrophic data loss incident
 ASK_PERMISSION=(
   "rm -rf"
-  "git push --force"
-  "git reset --hard"
   "npm publish"
   "docker rmi"
   "docker system prune"

package/templates/.cursor/rules/README.md

@@ -17,13 +17,11 @@ This directory contains modular rule files that Cursor uses to guide development
 - `06-typescript-conventions.mdc` - TypeScript/JS conventions and best practices
 - `07-process-ops.mdc` - Process discipline and server management
 - `08-solid-and-architecture.mdc` - SOLID principles and architectural patterns
-- `09-docstrings.mdc` - Language-specific docstring formats and standards
-- `10-authorship-and-attribution.mdc` - File headers and authorship standards
-- `16-documentation-quality-standards.mdc` - Engineering-grade documentation standards
-- `17-scope-management-waivers.mdc` - Scope management, change budgets, and emergency waiver procedures
-- `18-implementation-completeness.mdc` - Anti-fake implementation guardrails and completeness verification
-- `19-language-agnostic-standards.mdc` - Universal engineering standards across all programming languages
-- `20-sophisticated-todo-detection.mdc` - Advanced TODO detection patterns and hidden implementation analysis
+- `09-docstrings.mdc` - Language-specific docstring formats, standards, and file headers
+- `10-documentation-quality-standards.mdc` - Engineering-grade documentation standards
+- `11-scope-management-waivers.mdc` - Scope management, change budgets, and emergency waiver procedures
+- `12-implementation-completeness.mdc` - Anti-fake implementation guardrails with sophisticated TODO detection
+- `13-language-agnostic-standards.mdc` - Universal engineering standards (conditional - applies to code files only)
 
 ## How MDC Works
 

package/templates/scripts/v3/analysis/todo_analyzer.py

@@ -453,6 +453,29 @@ class HiddenTodoAnalyzer:
             # Console and logging
             r'console\.(log|warn|error|info)',
             r'\blogging\s+implementation\b',
+            
+            # TODO system documentation (false positives when documenting TODO system itself)
+            r'\btodo\s+template\s+system\b',
+            r'\btodo\s+template\b',
+            r'\btodo\s+instance\b',
+            r'\btodo\s+step\b',
+            r'\btodo\s+integration\b',
+            r'\btodo\s+system\b',
+            r'\btodotemplate\b',
+            r'\btodoinstance\b',
+            r'\btodostep\b',
+            r'\btodointegration\b',
+            r'\btodotemplatesystem\b',
+            r'\btodoprogress\b',
+            r'\btododependency\b',
+            r'\btodoqualityenforcer\b',
+            r'\btodoworkflowhooks\b',
+            r'\btodostatus\b',
+            r'\btodopriority\b',
+            r'\btodosteptype\b',
+            # Rust doc comment patterns when mentioning TODO system types
+            r'^\s*//[!]/.*\btodo\b.*(template|instance|step|integration|system)\b',
+            r'^\s*///.*\btodo\b.*(template|instance|step|integration|system)\b',
         ]
 
         # Engineering-grade TODO template patterns (for suggestions)
@@ -612,6 +635,30 @@ class HiddenTodoAnalyzer:
         for indicator in self.documentation_indicators:
             if re.search(indicator, comment, re.IGNORECASE):
                 return True
+        
+        # Check for Rust doc comments (//! and ///) that mention TODO system types
+        todo_system_types = [
+            r'todo\s+template',
+            r'todo\s+instance',
+            r'todo\s+step',
+            r'todo\s+integration',
+            r'todo\s+system',
+            r'todotemplate',
+            r'todoinstance',
+            r'todostep',
+            r'todointegration',
+            r'todotemplatesystem',
+            r'todoprogress',
+            r'tododependency',
+        ]
+        
+        # If comment mentions TODO system types and appears to be documentation, exclude it
+        if any(re.search(pattern, comment, re.IGNORECASE) for pattern in todo_system_types):
+            # Check if it's describing the system rather than a TODO item
+            # If it contains "TODO:" followed by a colon, it's likely a real TODO
+            if not re.search(r'\bTODO\s*:\s*', comment, re.IGNORECASE):
+                return True
+        
         return False
 
     def has_todo_indicators(self, comment: str) -> bool:
@@ -1522,7 +1569,7 @@ class HiddenTodoAnalyzer:
                     'blocking_analysis': {}
                 }
             
-            print(f"📁 Found {len(staged_files)} staged files to analyze")
+            print(f"Found {len(staged_files)} staged files to analyze")
             
             # Analyze staged files
             analysis_results = self.analyze_files(staged_files, min_confidence)

package/templates/.cursor/rules/10-authorship-and-attribution.mdc

@@ -1,15 +0,0 @@
----
-description: File headers and authorship
-globs:
-alwaysApply: false
----
-
-# File Header & Attribution
-
-For top-of-file documentation, include author signature:
-
-```
-Author: @darianrosebrook
-```
-
-Only in source files with public entrypoints or non-trivial modules.