@paths.design/caws-cli 7.0.2 → 7.0.3

package/dist/tool-loader.js

@@ -19,8 +19,13 @@ const { safeAsync } = require('./error-handler');
 class ToolLoader extends EventEmitter {
   constructor(options = {}) {
     super();
+    // Check new location first, fall back to legacy location
+    const newToolsDir = path.join(process.cwd(), '.caws/tools');
+    const legacyToolsDir = path.join(process.cwd(), 'apps/tools/caws');
+    const defaultToolsDir = fs.existsSync(newToolsDir) ? newToolsDir : legacyToolsDir;
+
     this.options = {
-      toolsDir: options.toolsDir || path.join(process.cwd(), 'apps/tools/caws'),
+      toolsDir: options.toolsDir || defaultToolsDir,
       cacheEnabled: options.cacheEnabled !== false,
       timeout: options.timeout || 10000,
       maxTools: options.maxTools || 50,

package/dist/tool-validator.js

@@ -15,9 +15,15 @@ const crypto = require('crypto');
  */
 class ToolValidator {
   constructor(options = {}) {
+    // Check new location first, fall back to legacy location
+    const newAllowlistPath = path.join(process.cwd(), '.caws/tools-allow.json');
+    const legacyAllowlistPath = path.join(process.cwd(), 'apps/tools/caws/tools-allow.json');
+    const defaultAllowlistPath = fs.existsSync(newAllowlistPath)
+      ? newAllowlistPath
+      : legacyAllowlistPath;
+
     this.options = {
-      allowlistPath:
-        options.allowlistPath || path.join(process.cwd(), 'apps/tools/caws/tools-allow.json'),
+      allowlistPath: options.allowlistPath || defaultAllowlistPath,
       strictMode: options.strictMode !== false,
       maxFileSize: options.maxFileSize || 1024 * 1024, // 1MB
       ...options,

package/dist/utils/detection.js

@@ -73,9 +73,10 @@ function detectCAWSSetup(cwd = process.cwd()) {
   const specFiles = files.filter((f) => f.endsWith('-spec.yaml'));
   const hasMultipleSpecs = specFiles.length > 1;
 
-  // Check for tools directory (enhanced setup)
-  const toolsDir = path.join(cwd, 'apps/tools/caws');
-  const hasTools = fs.existsSync(toolsDir);
+  // Check for tools directory (enhanced setup) - check new location first
+  const toolsDir = path.join(cwd, '.caws/tools');
+  const legacyToolsDir = path.join(cwd, 'apps/tools/caws');
+  const hasTools = fs.existsSync(toolsDir) || fs.existsSync(legacyToolsDir);
 
   // Determine setup type
   let setupType = 'basic';

package/dist/utils/git-lock.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Git Lock Detection Utilities
+ * Functions for detecting and handling git locks
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Check for git lock files
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Lock status information
+ */
+function checkGitLock(projectRoot) {
+  const lockFile = path.join(projectRoot, '.git', 'index.lock');
+  const headLockFile = path.join(projectRoot, '.git', 'HEAD.lock');
+
+  const result = {
+    locked: false,
+    stale: false,
+    lockFiles: [],
+    message: null,
+    suggestion: null,
+  };
+
+  // Check index.lock
+  if (fs.existsSync(lockFile)) {
+    const lockAge = Date.now() - fs.statSync(lockFile).mtimeMs;
+    const lockAgeMinutes = Math.floor(lockAge / 60000);
+
+    result.locked = true;
+    result.lockFiles.push({
+      path: '.git/index.lock',
+      age: lockAgeMinutes,
+      stale: lockAgeMinutes > 5,
+    });
+
+    if (lockAgeMinutes > 5) {
+      // Stale lock (older than 5 minutes)
+      result.stale = true;
+      result.message = `Stale git lock detected (${lockAgeMinutes} minutes old). This may indicate a crashed git process.`;
+      result.suggestion = 'Remove stale lock: rm .git/index.lock';
+    } else {
+      // Active lock
+      result.message =
+        'Git lock detected. Another git process may be running.';
+      result.suggestion =
+        'Wait for the other process to complete, or check for running git/editor processes';
+    }
+  }
+
+  // Check HEAD.lock
+  if (fs.existsSync(headLockFile)) {
+    const lockAge = Date.now() - fs.statSync(headLockFile).mtimeMs;
+    const lockAgeMinutes = Math.floor(lockAge / 60000);
+
+    result.locked = true;
+    result.lockFiles.push({
+      path: '.git/HEAD.lock',
+      age: lockAgeMinutes,
+      stale: lockAgeMinutes > 5,
+    });
+
+    if (lockAgeMinutes > 5) {
+      result.stale = true;
+      if (!result.message) {
+        result.message = `Stale git lock detected (${lockAgeMinutes} minutes old).`;
+        result.suggestion = 'Remove stale lock: rm .git/HEAD.lock';
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format git lock error message
+ * @param {Object} lockStatus - Lock status from checkGitLock
+ * @returns {string} Formatted error message
+ */
+function formatGitLockError(lockStatus) {
+  if (!lockStatus.locked) {
+    return null;
+  }
+
+  let message = '⚠️  Git lock detected\n';
+  message += `   ${lockStatus.message}\n`;
+
+  if (lockStatus.lockFiles.length > 0) {
+    message += '\n   Lock files:\n';
+    for (const lockFile of lockStatus.lockFiles) {
+      message += `   - ${lockFile.path} (${lockFile.age} minutes old)`;
+      if (lockFile.stale) {
+        message += ' [STALE]';
+      }
+      message += '\n';
+    }
+  }
+
+  if (lockStatus.suggestion) {
+    message += `\n   💡 ${lockStatus.suggestion}\n`;
+  }
+
+  if (lockStatus.stale) {
+    message +=
+      '\n   ⚠️  Warning: Removing stale locks may cause data loss if another process is actually running.\n';
+    message += '   Check for running git/editor processes before removing locks.\n';
+  }
+
+  return message;
+}
+
+module.exports = {
+  checkGitLock,
+  formatGitLockError,
+};
+

package/dist/utils/gitignore-updater.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Gitignore Updater Utility
+ * Updates .gitignore to properly handle CAWS runtime files vs source files
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * CAWS .gitignore entries
+ *
+ * Strategy: Track shared/collaborative files, ignore local-only runtime data
+ *
+ * TRACKED (shared with team):
+ * - .caws/working-spec.yaml (main spec)
+ * - .caws/specs/*.yaml (feature specs)
+ * - .caws/policy.yaml (team policy)
+ * - .caws/waivers/*.yaml (project-wide waivers)
+ * - .caws/provenance/ (audit trails for compliance)
+ * - .caws/changes/ (change tracking for team visibility)
+ * - .caws/archive/ (archived changes for history)
+ * - .caws/plans/*.md (implementation plans)
+ *
+ * IGNORED (local-only):
+ * - .agent/ (agent runtime tracking, local to each developer)
+ * - Temporary files (*.tmp, *.bak)
+ * - Logs (caws.log, debug logs)
+ * - Local overrides (caws.local.*)
+ */
+const CAWS_GITIGNORE_ENTRIES = `
+# CAWS Local Runtime Data (developer-specific, should not be tracked)
+# ====================================================================
+# Note: Specs, policy, waivers, provenance, and plans ARE tracked for team collaboration
+# Only local agent tracking, generated tools, and temporary files are ignored
+
+# Agent runtime tracking (local to each developer)
+.agent/
+
+# CAWS tools (now in .caws/tools/)
+.caws/tools/
+# Legacy location (for backward compatibility)
+apps/tools/caws/
+
+# Temporary CAWS files
+**/*.caws.tmp
+**/*.working-spec.bak
+.caws/*.tmp
+.caws/*.bak
+
+# CAWS logs (local debugging)
+caws-debug.log*
+**/caws.log
+.caws/*.log
+
+# Local development overrides (developer-specific)
+caws.local.*
+.caws/local.*
+`;
+
+/**
+ * Update .gitignore to include CAWS runtime file exclusions
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} options - Options
+ * @param {boolean} options.force - Force update even if entries exist
+ * @returns {Promise<boolean>} Whether .gitignore was updated
+ */
+async function updateGitignore(projectRoot, options = {}) {
+  const { force = false } = options;
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  try {
+    // Read existing .gitignore or create empty
+    let existingContent = '';
+    if (await fs.pathExists(gitignorePath)) {
+      existingContent = await fs.readFile(gitignorePath, 'utf8');
+    }
+
+    // Check if CAWS entries already exist (check for either old or new header)
+    const hasCawsEntries =
+      existingContent.includes('# CAWS Local Runtime Data') ||
+      existingContent.includes('# CAWS Runtime Data');
+
+    if (hasCawsEntries && !force) {
+      // Already has CAWS entries, skip
+      return false;
+    }
+
+    // If old entries exist, replace them with new ones
+    if (existingContent.includes('# CAWS Runtime Data') && force) {
+      // Remove old CAWS entries (between "# CAWS Runtime Data" and next major section)
+      const lines = existingContent.split('\n');
+      const startIndex = lines.findIndex((line) => line.includes('# CAWS Runtime Data'));
+      if (startIndex !== -1) {
+        // Find the end of CAWS section (next major section starting with #)
+        let endIndex = startIndex + 1;
+        while (
+          endIndex < lines.length &&
+          (lines[endIndex].trim() === '' ||
+            lines[endIndex].startsWith('#') ||
+            lines[endIndex].startsWith('.caws/') ||
+            lines[endIndex].startsWith('.agent/') ||
+            lines[endIndex].includes('caws') ||
+            lines[endIndex].includes('CAWS'))
+        ) {
+          endIndex++;
+        }
+        // Remove old section and insert new one
+        const before = lines.slice(0, startIndex).join('\n');
+        const after = lines.slice(endIndex).join('\n');
+        existingContent = [before, after].filter(Boolean).join('\n');
+      }
+    }
+
+    // Append CAWS entries
+    const updatedContent = existingContent.trim() + '\n' + CAWS_GITIGNORE_ENTRIES.trim() + '\n';
+
+    await fs.writeFile(gitignorePath, updatedContent, 'utf8');
+
+    return true;
+  } catch (error) {
+    console.warn(chalk.yellow(`⚠️  Could not update .gitignore: ${error.message}`));
+    return false;
+  }
+}
+
+/**
+ * Verify .gitignore has proper CAWS entries
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<boolean>} Whether .gitignore has CAWS entries
+ */
+async function verifyGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  if (!(await fs.pathExists(gitignorePath))) {
+    return false;
+  }
+
+  const content = await fs.readFile(gitignorePath, 'utf8');
+  return content.includes('# CAWS Local Runtime Data') || content.includes('# CAWS Runtime Data');
+}
+
+module.exports = {
+  updateGitignore,
+  verifyGitignore,
+  CAWS_GITIGNORE_ENTRIES,
+};

package/dist/utils/quality-gates.js

@@ -196,18 +196,58 @@ function checkHiddenTodos(stagedFiles) {
   console.log(`📁 Found ${supportedFiles.length} staged files to analyze for TODOs`);
 
   try {
-    // Check if TODO analyzer exists
-    const analyzerPath = path.join(process.cwd(), 'scripts/v3/analysis/todo_analyzer.py');
-    if (!fs.existsSync(analyzerPath)) {
+    // Find TODO analyzer .mjs file (preferred - no Python dependency)
+    const possiblePaths = [
+      // Published npm package (priority)
+      path.join(
+        process.cwd(),
+        'node_modules',
+        '@paths.design',
+        'quality-gates',
+        'todo-analyzer.mjs'
+      ),
+      // Legacy monorepo local copy
+      path.join(process.cwd(), 'node_modules', '@caws', 'quality-gates', 'todo-analyzer.mjs'),
+      // Monorepo structure (development)
+      path.join(process.cwd(), 'packages', 'quality-gates', 'todo-analyzer.mjs'),
+      // Local copy in scripts directory (if scaffolded)
+      path.join(process.cwd(), 'scripts', 'todo-analyzer.mjs'),
+      // Legacy Python analyzer (deprecated)
+      path.join(process.cwd(), 'scripts', 'v3', 'analysis', 'todo_analyzer.py'),
+    ];
+
+    let analyzerPath = null;
+    let usePython = false;
+
+    for (const testPath of possiblePaths) {
+      if (fs.existsSync(testPath)) {
+        analyzerPath = testPath;
+        usePython = testPath.endsWith('.py');
+        break;
+      }
+    }
+
+    if (!analyzerPath) {
       console.warn('⚠️  TODO analyzer not found - skipping TODO analysis');
+      console.warn(
+        '💡 Install @paths.design/quality-gates: npm install --save-dev @paths.design/quality-gates'
+      );
       return { todos: [], blocking: 0, total: 0 };
     }
 
+    if (usePython) {
+      console.warn('⚠️  Using legacy Python TODO analyzer (deprecated)');
+      console.warn(
+        '💡 Install @paths.design/quality-gates for Node.js version: npm install --save-dev @paths.design/quality-gates'
+      );
+    }
+
     // Run the TODO analyzer with staged files
-    const result = execSync(
-      `python3 ${analyzerPath} --staged-only --min-confidence ${CONFIG.todoConfidenceThreshold}`,
-      { encoding: 'utf8', cwd: process.cwd() }
-    );
+    const command = usePython
+      ? `python3 ${analyzerPath} --staged-only --min-confidence ${CONFIG.todoConfidenceThreshold}`
+      : `node ${analyzerPath} --staged-only --ci-mode --min-confidence ${CONFIG.todoConfidenceThreshold}`;
+
+    const result = execSync(command, { encoding: 'utf8', cwd: process.cwd() });
 
     // Parse the output to extract TODO count
     const lines = result.split('\n');

package/dist/utils/spec-resolver.js

@@ -108,7 +108,14 @@ async function resolveSpec(options = {}) {
       const specPath = path.join(SPECS_DIR, registry.specs[id].path);
       try {
         const content = await fs.readFile(specPath, 'utf8');
-        const spec = yaml.load(content);
+        let spec;
+        try {
+          spec = yaml.load(content);
+        } catch (yamlError) {
+          console.log(chalk.yellow(`   - ${id} (YAML syntax error: ${yamlError.message})`));
+          specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'YAML error' });
+          continue;
+        }
         const status = spec.status || 'draft';
         const type = spec.type || 'feature';
         const statusColor =
@@ -122,7 +129,7 @@ async function resolveSpec(options = {}) {
         );
         specsInfo.push({ id, type, status, title: spec.title || 'Untitled' });
       } catch (error) {
-        console.log(chalk.yellow(`   - ${id} (error loading details)`));
+        console.log(chalk.yellow(`   - ${id} (error loading details: ${error.message})`));
         specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'Error loading' });
       }
     }
@@ -363,7 +370,20 @@ async function checkScopeConflicts(specIds) {
 
     try {
       const content = await fs.readFile(specPath, 'utf8');
-      const spec = yaml.load(content);
+      let spec;
+      try {
+        spec = yaml.load(content);
+      } catch (yamlError) {
+        const relativePath = path.relative(process.cwd(), specPath);
+        throw new Error(
+          `Invalid YAML syntax in ${relativePath}: ${yamlError.message}\n` +
+            (yamlError.mark
+              ? `   Line ${yamlError.mark.line + 1}, Column ${yamlError.mark.column + 1}\n`
+              : '') +
+            (yamlError.mark?.snippet ? `   ${yamlError.mark.snippet}\n` : '') +
+            `💡 Fix YAML syntax errors or use 'caws specs create <id>' for proper structure`
+        );
+      }
 
       specScopes.push({
         id,

package/dist/utils/yaml-validation.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview YAML Validation Utilities
+ * Functions for validating YAML syntax and structure
+ * @author @darianrosebrook
+ */
+
+const yaml = require('js-yaml');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Validate YAML syntax for a file
+ * @param {string} filePath - Path to YAML file
+ * @returns {Object} Validation result with valid flag and error details
+ */
+function validateYamlSyntax(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return {
+        valid: false,
+        error: `File not found: ${filePath}`,
+        line: null,
+        column: null,
+      };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    yaml.load(content); // Will throw if invalid
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error.message,
+      line: error.mark?.line ? error.mark.line + 1 : null, // Convert to 1-based
+      column: error.mark?.column ? error.mark.column + 1 : null, // Convert to 1-based
+      snippet: error.mark?.snippet || null,
+    };
+  }
+}
+
+/**
+ * Validate YAML syntax for multiple files
+ * @param {string[]} filePaths - Array of file paths to validate
+ * @returns {Object} Validation results with summary
+ */
+function validateYamlFiles(filePaths) {
+  const results = {
+    valid: true,
+    files: [],
+    errors: [],
+  };
+
+  for (const filePath of filePaths) {
+    const validation = validateYamlSyntax(filePath);
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    results.files.push({
+      path: relativePath,
+      ...validation,
+    });
+
+    if (!validation.valid) {
+      results.valid = false;
+      results.errors.push({
+        file: relativePath,
+        error: validation.error,
+        line: validation.line,
+        column: validation.column,
+        snippet: validation.snippet,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find all YAML files in .caws directory
+ * @param {string} projectRoot - Project root directory
+ * @returns {string[]} Array of YAML file paths
+ */
+function findCawsYamlFiles(projectRoot) {
+  const cawsDir = path.join(projectRoot, '.caws');
+  const yamlFiles = [];
+
+  if (!fs.existsSync(cawsDir)) {
+    return yamlFiles;
+  }
+
+  function walkDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walkDir(fullPath);
+      } else if (
+        entry.isFile() &&
+        (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))
+      ) {
+        yamlFiles.push(fullPath);
+      }
+    }
+  }
+
+  walkDir(cawsDir);
+  return yamlFiles;
+}
+
+/**
+ * Validate all CAWS YAML files in project
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Validation results
+ */
+function validateAllCawsYamlFiles(projectRoot) {
+  const yamlFiles = findCawsYamlFiles(projectRoot);
+  return validateYamlFiles(yamlFiles);
+}
+
+/**
+ * Format validation error for display
+ * @param {Object} error - Error object from validateYamlSyntax
+ * @param {string} filePath - File path
+ * @returns {string} Formatted error message
+ */
+function formatYamlError(error, filePath) {
+  const relativePath = path.relative(process.cwd(), filePath);
+  let message = `❌ Invalid YAML in ${relativePath}\n`;
+  message += `   Error: ${error.error}\n`;
+
+  if (error.line !== null) {
+    message += `   Line: ${error.line}`;
+    if (error.column !== null) {
+      message += `, Column: ${error.column}`;
+    }
+    message += '\n';
+  }
+
+  if (error.snippet) {
+    message += `   ${error.snippet}\n`;
+  }
+
+  return message;
+}
+
+module.exports = {
+  validateYamlSyntax,
+  validateYamlFiles,
+  findCawsYamlFiles,
+  validateAllCawsYamlFiles,
+  formatYamlError,
+};
+

package/dist/validation/spec-validation.js

@@ -238,6 +238,42 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate scope.out doesn't contain glob patterns
+    if (spec.scope && spec.scope.out && Array.isArray(spec.scope.out)) {
+      const globPatterns = spec.scope.out.filter(
+        (pattern) => pattern.includes('*') || pattern.includes('?')
+      );
+      if (globPatterns.length > 0) {
+        errors.push({
+          instancePath: '/scope/out',
+          message: `Unsupported glob patterns in scope.out: ${globPatterns.join(', ')}`,
+          suggestion:
+            'Use directory paths only (e.g., __pycache__/ instead of *.pyc or **/*.pyc). Python cache files are already covered by __pycache__/',
+          canAutoFix: true,
+        });
+
+        // Auto-fix: remove glob patterns and keep only directory paths
+        if (autoFix) {
+          const fixedOut = spec.scope.out
+            .filter((pattern) => !pattern.includes('*') && !pattern.includes('?'))
+            .map((pattern) => {
+              // Ensure directory paths end with /
+              if (!pattern.includes('.') && !pattern.endsWith('/')) {
+                return pattern + '/';
+              }
+              return pattern;
+            });
+
+          fixes.push({
+            field: 'scope.out',
+            value: fixedOut,
+            description: `Removed glob patterns from scope.out: ${globPatterns.join(', ')}`,
+            reason: 'Glob patterns are not supported in scope.out',
+          });
+        }
+      }
+    }
+
     // Auto-fix missing scope.out
     if (spec.scope && !spec.scope.out) {
       fixes.push({
@@ -329,7 +365,7 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
         const suggestion = isChoreMode
           ? 'For infrastructure/setup work, add a minimal project_setup contract or create a waiver'
           : 'Add API contracts (OpenAPI, GraphQL, etc.) or change mode to "chore" for maintenance work';
-        
+
         errors.push({
           instancePath: '/contracts',
           message: `Contracts required for Tier ${spec.risk_tier} changes`,
@@ -341,7 +377,8 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
                   {
                     type: 'project_setup',
                     path: '.caws/working-spec.yaml',
-                    description: 'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+                    description:
+                      'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
                   },
                 ],
               }
@@ -392,6 +429,48 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate rollback format if present (for all tiers)
+    if (spec.rollback !== undefined) {
+      if (!Array.isArray(spec.rollback)) {
+        errors.push({
+          instancePath: '/rollback',
+          message: 'rollback must be an array of strings',
+          suggestion: 'Use format: ["Step 1", "Step 2", "Step 3"]',
+          canAutoFix: false,
+        });
+      } else {
+        // Check for duplicates
+        const uniqueSteps = [...new Set(spec.rollback)];
+        if (uniqueSteps.length !== spec.rollback.length) {
+          warnings.push({
+            instancePath: '/rollback',
+            message: 'Duplicate entries found in rollback array',
+            suggestion: 'Remove duplicate entries',
+          });
+
+          if (autoFix) {
+            fixes.push({
+              field: 'rollback',
+              value: uniqueSteps,
+              description: 'Removed duplicate rollback entries',
+              reason: 'Duplicate entries detected',
+            });
+          }
+        }
+
+        // Validate each entry is a string
+        const invalidEntries = spec.rollback.filter((entry) => typeof entry !== 'string');
+        if (invalidEntries.length > 0) {
+          errors.push({
+            instancePath: '/rollback',
+            message: `Invalid rollback entries (must be strings): ${invalidEntries.length}`,
+            suggestion: 'All rollback entries must be string descriptions',
+            canAutoFix: false,
+          });
+        }
+      }
+    }
+
     // Validate waiver_ids format if present
     if (spec.waiver_ids) {
       if (!Array.isArray(spec.waiver_ids)) {