@paths.design/caws-cli 7.0.1 → 7.0.3

package/dist/scaffold/git-hooks.js

@@ -138,6 +138,100 @@ if [ ! -d ".caws" ]; then
   exit 0
 fi
 
+# Check for git locks before proceeding
+if [ -f ".git/index.lock" ]; then
+  LOCK_AGE=$(($(date +%s) - $(stat -f %m .git/index.lock 2>/dev/null || stat -c %Y .git/index.lock 2>/dev/null || echo 0)))
+  LOCK_AGE_MINUTES=$((LOCK_AGE / 60))
+  
+  if [ $LOCK_AGE_MINUTES -gt 5 ]; then
+    echo "⚠️  Stale git lock detected (${LOCK_AGE_MINUTES} minutes old)"
+    echo "💡 This may indicate a crashed git process"
+    echo "💡 Remove stale lock: rm .git/index.lock"
+    echo "⚠️  Warning: Check for running git/editor processes before removing"
+    exit 1
+  else
+    echo "⚠️  Git lock detected (${LOCK_AGE_MINUTES} minutes old)"
+    echo "💡 Another git process may be running"
+    echo "💡 Wait for the other process to complete, or check for running processes"
+    exit 1
+  fi
+fi
+
+# Validate YAML syntax for all CAWS spec files
+echo "🔍 Validating YAML syntax for CAWS spec files..."
+YAML_VALIDATION_FAILED=false
+
+# Find all staged .yaml/.yml files in .caws directory
+STAGED_YAML_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.caws/.*\.(yaml|yml)$' || true)
+
+if [ -n "$STAGED_YAML_FILES" ]; then
+  # Use Node.js to validate YAML if available
+  if command -v node >/dev/null 2>&1; then
+    # Try to use CAWS CLI for validation
+    if command -v caws >/dev/null 2>&1; then
+      for file in $STAGED_YAML_FILES; do
+        if [ -f "$file" ]; then
+          # Use Node.js to validate YAML syntax
+          if ! node -e "
+            const yaml = require('js-yaml');
+            const fs = require('fs');
+            try {
+              const content = fs.readFileSync('$file', 'utf8');
+              yaml.load(content);
+              process.exit(0);
+            } catch (error) {
+              console.error('❌ Invalid YAML in $file');
+              console.error('   Error:', error.message);
+              if (error.mark) {
+                console.error('   Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+                if (error.mark.snippet) console.error('   ' + error.mark.snippet);
+              }
+              process.exit(1);
+            }
+          " 2>&1; then
+            YAML_VALIDATION_FAILED=true
+          fi
+        fi
+      done
+    else
+      # Fallback: use node directly with js-yaml
+      for file in $STAGED_YAML_FILES; do
+        if [ -f "$file" ]; then
+          if ! node -e "
+            const yaml = require('js-yaml');
+            const fs = require('fs');
+            try {
+              const content = fs.readFileSync('$file', 'utf8');
+              yaml.load(content);
+              process.exit(0);
+            } catch (error) {
+              console.error('❌ Invalid YAML in $file');
+              console.error('   Error:', error.message);
+              if (error.mark) {
+                console.error('   Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+                if (error.mark.snippet) console.error('   ' + error.mark.snippet);
+              }
+              process.exit(1);
+            }
+          " 2>&1; then
+            YAML_VALIDATION_FAILED=true
+          fi
+        fi
+      done
+    fi
+  else
+    echo "⚠️  Node.js not available - skipping YAML validation"
+    echo "💡 Install Node.js to enable YAML syntax validation"
+  fi
+fi
+
+if [ "$YAML_VALIDATION_FAILED" = true ]; then
+  echo "❌ YAML syntax validation failed - commit blocked"
+  echo "💡 Fix YAML syntax errors above before committing"
+  echo "💡 Consider using 'caws specs create <id>' instead of manual creation"
+  exit 1
+fi
+
 # Fallback chain for quality gates:
 # 1. Try Node.js script (if exists)
 # 2. Try CAWS CLI
@@ -231,38 +325,41 @@ fi
 # Run hidden TODO analysis on staged files only (if available)
 if [ "$QUALITY_GATES_RAN" = true ]; then
   echo "🔍 Checking for hidden TODOs in staged files..."
-  # Try quality gates package TODO analyzer first (published package)
+  
+  # Find TODO analyzer .mjs file (preferred - no Python dependency)
+  TODO_ANALYZER=""
+  
+  # Try quality gates package TODO analyzer (published package)
   if [ -f "node_modules/@paths.design/quality-gates/todo-analyzer.mjs" ]; then
-    if command -v node >/dev/null 2>&1; then
-      if node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --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..."
-        node node_modules/@paths.design/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
-        exit 1
-      fi
-    fi
+    TODO_ANALYZER="node_modules/@paths.design/quality-gates/todo-analyzer.mjs"
   # Try quality gates package TODO analyzer (monorepo/local copy)
   elif [ -f "node_modules/@caws/quality-gates/todo-analyzer.mjs" ]; then
-    if command -v node >/dev/null 2>&1; then
-      if node node_modules/@caws/quality-gates/todo-analyzer.mjs --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..."
-        node node_modules/@caws/quality-gates/todo-analyzer.mjs --staged-only --min-confidence 0.8
-        exit 1
-      fi
+    TODO_ANALYZER="node_modules/@caws/quality-gates/todo-analyzer.mjs"
+  # Try monorepo structure (development)
+  elif [ -f "packages/quality-gates/todo-analyzer.mjs" ]; then
+    TODO_ANALYZER="packages/quality-gates/todo-analyzer.mjs"
+  # Try local copy in scripts directory (if scaffolded)
+  elif [ -f "scripts/todo-analyzer.mjs" ]; then
+    TODO_ANALYZER="scripts/todo-analyzer.mjs"
+  fi
+  
+  # Run TODO analyzer if found
+  if [ -n "$TODO_ANALYZER" ] && command -v node >/dev/null 2>&1; then
+    if node "$TODO_ANALYZER" --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..."
+      node "$TODO_ANALYZER" --staged-only --min-confidence 0.8
+      exit 1
     fi
-  # Fallback to legacy Python analyzer
+  # Fallback to legacy Python analyzer (deprecated - will be removed)
   elif command -v python3 >/dev/null 2>&1 && [ -f "scripts/v3/analysis/todo_analyzer.py" ]; then
+    echo "⚠️  Using legacy Python TODO analyzer (deprecated)"
+    echo "💡 Install @paths.design/quality-gates for Node.js version: npm install --save-dev @paths.design/quality-gates"
     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
@@ -274,8 +371,9 @@ if [ "$QUALITY_GATES_RAN" = true ]; then
       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"
+  else
+    echo "⚠️  TODO analyzer not available - skipping hidden TODO check"
+    echo "💡 Install @paths.design/quality-gates for TODO analysis: npm install --save-dev @paths.design/quality-gates"
   fi
 fi
 
@@ -364,12 +462,71 @@ fi
 # Run full validation suite
 if command -v caws >/dev/null 2>&1; then
   echo "📋 Running comprehensive CAWS validation..."
-  if caws validate --quiet; then
+  
+  # Run validation and capture output
+  VALIDATION_OUTPUT=$(caws validate 2>&1)
+  VALIDATION_EXIT=$?
+  
+  if [ $VALIDATION_EXIT -eq 0 ]; then
     echo "✅ CAWS validation passed"
   else
     echo "❌ CAWS validation failed"
-    echo "💡 Fix issues locally, then push again"
-    echo "💡 You can commit fixes with: git commit --no-verify"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Validation Errors:"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "$VALIDATION_OUTPUT" | grep -E "(❌|error|Error|Missing|required)" || echo "$VALIDATION_OUTPUT"
+    echo ""
+    
+    # Check for contract-related errors
+    if echo "$VALIDATION_OUTPUT" | grep -qi "contract"; then
+      echo "💡 Contract Requirements:"
+      echo "   • Tier 1 & 2 changes require at least one contract"
+      echo "   • For infrastructure/setup work, use 'chore' mode or add a minimal contract:"
+      echo ""
+      echo "   Example minimal contract (.caws/working-spec.yaml):"
+      echo "   contracts:"
+      echo "     - type: 'project_setup'"
+      echo "       path: '.caws/working-spec.yaml'"
+      echo "       description: 'Project-level CAWS configuration'"
+      echo ""
+      echo "   Or change mode to 'chore' for maintenance work:"
+      echo "   mode: chore"
+      echo ""
+    fi
+    
+    # Check for active waivers
+    echo "🔍 Checking for active waivers..."
+    if command -v caws >/dev/null 2>&1 && caws waivers list --status=active --format=count 2>/dev/null | grep -q "[1-9]"; then
+      ACTIVE_WAIVERS=$(caws waivers list --status=active 2>/dev/null)
+      echo "⚠️  Active waivers found:"
+      echo "$ACTIVE_WAIVERS" | head -5
+      echo ""
+      echo "💡 Note: Waivers may not cover all validation failures"
+      echo "   Review waiver coverage: caws waivers list --status=active"
+    else
+      echo "   No active waivers found"
+      echo ""
+      echo "💡 If this is infrastructure/setup work, you can create a waiver:"
+      echo "   caws waivers create \\"
+      echo "     --title='Initial CAWS setup' \\"
+      echo "     --reason=infrastructure_limitation \\"
+      echo "     --gates=contracts \\"
+      echo "     --expires-at='2024-12-31T23:59:59Z' \\"
+      echo "     --approved-by='@your-team' \\"
+      echo "     --impact-level=low \\"
+      echo "     --mitigation-plan='Contracts will be added as features are developed'"
+    fi
+    
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Next Steps:"
+    echo "   1. Review errors above"
+    echo "   2. Fix issues in .caws/working-spec.yaml"
+    echo "   3. Run: caws validate (to verify fixes)"
+    echo "   4. Commit fixes: git commit --no-verify (allowed)"
+    echo "   5. Push again: git push"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
     exit 1
   fi
 fi

package/dist/scaffold/index.js

@@ -9,11 +9,12 @@ const path = require('path');
 const chalk = require('chalk');
 
 // Import detection utilities
-const { detectCAWSSetup } = require('../utils/detection');
+const { detectCAWSSetup, findPackageRoot } = require('../utils/detection');
 const { detectsPublishing } = require('../utils/project-analysis');
 
 // Import git hooks scaffolding
 const { scaffoldGitHooks } = require('./git-hooks');
+const { updateGitignore } = require('../utils/gitignore-updater');
 
 // CLI version from package.json
 const CLI_VERSION = require('../../package.json').version;
@@ -23,8 +24,33 @@ const CLI_VERSION = require('../../package.json').version;
  * @param {string} targetDir - Target directory for scaffolding
  * @param {Object} options - Scaffold options
  */
+/**
+ * Find the template directory using robust path resolution
+ * Works in both development and global install scenarios
+ * @returns {string|null} Template directory path or null
+ */
+function findTemplateDir() {
+  // Find package root using shared utility
+  const packageRoot = findPackageRoot(__dirname);
+
+  // Try templates relative to package root first (works in both dev and global install)
+  const possiblePaths = [
+    path.join(packageRoot, 'templates'),
+    path.resolve(__dirname, '../../templates'), // Dev fallback
+    path.resolve(__dirname, '../templates'), // Legacy fallback
+  ];
+
+  for (const testPath of possiblePaths) {
+    if (fs.existsSync(testPath)) {
+      return testPath;
+    }
+  }
+
+  return null;
+}
+
 async function scaffoldIDEIntegrations(targetDir, options) {
-  const templateDir = path.join(__dirname, '../../templates');
+  const templateDir = findTemplateDir() || path.join(__dirname, '../../templates');
 
   console.log(chalk.cyan('🎨 Setting up IDE integrations...'));
 
@@ -192,19 +218,24 @@ async function scaffoldProject(options) {
       setup.templateDir = cawsSetup.templateDir;
       setup.hasTemplateDir = true;
     } else if (!setup.templateDir) {
-      // Try to find template directory using absolute paths that work in CI
+      // Try to find template directory using robust path resolution
       const possiblePaths = [
-        // 1. Bundled templates in CLI package (for global installs) - CHECK THIS FIRST!
+        // 1. Use the helper function to find templates (works in dev and global install)
+        findTemplateDir(),
+        // 2. Bundled templates relative to package root
+        path.join(findPackageRoot(__dirname), 'templates'),
+        // 3. Legacy fallback paths
         path.join(__dirname, '../../templates'),
-        // 2. CI paths
+        path.join(__dirname, '../templates'),
+        // 4. CI paths
         '/home/runner/work/coding-agent-working-standard/coding-agent-working-standard/packages/caws-template',
         '/workspace/packages/caws-template',
         '/caws/packages/caws-template',
-        // 3. Monorepo relative paths
+        // 5. Monorepo relative paths
         path.resolve(process.cwd(), '../../../packages/caws-template'),
         path.resolve(process.cwd(), '../../packages/caws-template'),
         path.resolve(process.cwd(), '../packages/caws-template'),
-      ];
+      ].filter(Boolean); // Remove null values
 
       for (const testPath of possiblePaths) {
         if (fs.existsSync(testPath)) {
@@ -271,12 +302,32 @@ async function scaffoldProject(options) {
     // Determine what enhancements to add based on setup type and options
     const enhancements = [];
 
-    // Add CAWS tools directory structure (matches test expectations)
+    // Add CAWS tools to .caws/ directory (keeps all CAWS files together)
     enhancements.push({
-      name: 'apps/tools/caws',
+      name: '.caws/tools',
       description: 'CAWS tools directory',
       required: true,
     });
+    enhancements.push({
+      name: '.caws/schemas',
+      description: 'CAWS JSON schemas',
+      required: true,
+    });
+    enhancements.push({
+      name: '.caws/templates',
+      description: 'CAWS templates',
+      required: true,
+    });
+    enhancements.push({
+      name: '.caws/waivers.yml',
+      description: 'CAWS waivers configuration',
+      required: false,
+    });
+    enhancements.push({
+      name: '.caws/tools-allow.json',
+      description: 'CAWS tools allowlist',
+      required: false,
+    });
 
     // Add codemods if requested or not minimal
     if (options.withCodemods || (!options.minimal && !options.withCodemods)) {
@@ -427,6 +478,19 @@ async function scaffoldProject(options) {
             console.log(
               chalk.gray('   For now, quality gates will work via CAWS CLI or local scripts')
             );
+
+            // Copy todo-analyzer.mjs locally as fallback if available
+            const qualityGatesPath = path.resolve(__dirname, '../../../quality-gates');
+            const todoAnalyzerSource = path.join(qualityGatesPath, 'todo-analyzer.mjs');
+            if (fs.existsSync(todoAnalyzerSource)) {
+              const scriptsDir = path.join(currentDir, 'scripts');
+              await fs.ensureDir(scriptsDir);
+              const todoAnalyzerDest = path.join(scriptsDir, 'todo-analyzer.mjs');
+              await fs.copy(todoAnalyzerSource, todoAnalyzerDest);
+              console.log(
+                chalk.green('✅ Copied todo-analyzer.mjs to scripts/ directory (local fallback)')
+              );
+            }
           }
         } else {
           // No package.json - suggest global install or manual setup
@@ -567,10 +631,24 @@ async function scaffoldProject(options) {
             console.warn(chalk.yellow(`⚠️  Failed to add ${enhancement.name}:`), copyError.message);
           }
         } else {
-          // If source doesn't exist in template, create the directory structure
+          // If source doesn't exist in template, check if it should be a file or directory
           try {
-            await fs.ensureDir(destPath);
-            console.log(chalk.green(`✅ Created ${enhancement.description}`));
+            // Check if the enhancement name looks like a file (has extension)
+            const hasExtension = path.extname(enhancement.name).length > 0;
+
+            if (hasExtension) {
+              // Create an empty file for file-like enhancements
+              await fs.ensureDir(path.dirname(destPath));
+              await fs.writeFile(destPath, '');
+              console.log(
+                chalk.yellow(`⚠️  Created empty ${enhancement.description} (template not found)`)
+              );
+              console.log(chalk.gray(`   Template expected at: ${sourcePath}`));
+            } else {
+              // Create directory for directory-like enhancements
+              await fs.ensureDir(destPath);
+              console.log(chalk.green(`✅ Created ${enhancement.description}`));
+            }
             addedCount++;
             addedFiles.push(enhancement.name);
           } catch (createError) {
@@ -629,19 +707,19 @@ async function scaffoldProject(options) {
         console.log('3. Push to trigger automated publishing');
         console.log('4. Your existing CAWS tools remain unchanged');
       } else {
-        console.log('2. Customize your working spec in .caws/working-spec.yaml');
-        console.log('3. Run validation: caws validate --suggestions');
+        console.log('2. Run: caws validate (verify setup)');
+        console.log('3. Run: caws diagnose (check project health)');
+        console.log('4. Customize .caws/working-spec.yaml for your project');
+        console.log('5. Optional: Create .caws/policy.yaml for tier-specific budgets');
         if (!qualityGatesAdded && !options.minimal) {
           console.log(
-            chalk.gray('4. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
+            chalk.gray('6. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
           );
           console.log(
             chalk.gray(
               '   Add --with-quality-gates flag if you want local scripts without global CLI'
             )
           );
-        } else {
-          console.log('4. Your existing CAWS tools remain unchanged');
         }
       }
     }
@@ -656,6 +734,16 @@ async function scaffoldProject(options) {
       console.log(chalk.yellow('\n⚠️  Force mode was used - review changes carefully'));
     }
 
+    // Update .gitignore to exclude CAWS local runtime files
+    const gitignoreUpdated = await updateGitignore(targetDir);
+    if (gitignoreUpdated) {
+      console.log(chalk.green('\n✅ Updated .gitignore to exclude CAWS local runtime files'));
+      console.log(
+        chalk.gray('   Tracked: Specs, policy, waivers, provenance, plans (shared with team)')
+      );
+      console.log(chalk.gray('   Ignored: Agent runtime, temp files, logs (local-only)'));
+    }
+
     // Save provenance manifest if tools are available
     const tools = loadProvenanceTools && loadProvenanceTools();
     if (tools && typeof tools.saveProvenance === 'function') {

package/dist/templates/.caws/tools/README.md

@@ -0,0 +1,20 @@
+# CAWS Tools
+
+This directory contains CAWS-specific tools that aren't available in the CLI.
+
+## scope-guard.js
+
+Enforces that experimental code stays within designated sandbox areas. Used by Cursor hooks for scope validation.
+
+```bash
+# Validate experimental code containment
+node .caws/tools/scope-guard.js validate
+
+# Check containment status
+node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+```
+
+**Usage in Cursor Hooks:**
+
+The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
+