@paths.design/caws-cli 7.0.2 → 7.0.3

package/dist/scaffold/index.js

@@ -14,6 +14,7 @@ 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;
@@ -31,20 +32,20 @@ const CLI_VERSION = require('../../package.json').version;
 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;
 }
 
@@ -301,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)) {
@@ -457,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
@@ -601,12 +635,14 @@ async function scaffoldProject(options) {
           try {
             // 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.yellow(`⚠️  Created empty ${enhancement.description} (template not found)`)
+              );
               console.log(chalk.gray(`   Template expected at: ${sourcePath}`));
             } else {
               // Create directory for directory-like enhancements
@@ -698,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.
+

package/dist/templates/.cursor/README.md

@@ -0,0 +1,311 @@
+# CAWS Cursor IDE Integration
+
+This directory contains Cursor IDE hooks that provide real-time CAWS quality assurance integration during development.
+
+## Overview
+
+Cursor hooks enable seamless integration between CAWS and the Cursor IDE, providing:
+
+- **Real-time quality validation** as you code
+- **Automatic spec validation** when editing working specs
+- **Scope enforcement** preventing out-of-scope file access
+- **Tool validation** for safe MCP execution
+- **Quality monitoring** after file edits
+
+## Hook Configuration
+
+The `hooks.json` file defines when each hook runs:
+
+```json
+{
+  "beforeShellExecution": ["block-dangerous.sh", "audit.sh"],
+  "beforeMCPExecution": ["audit.sh", "caws-tool-validation.sh"],
+  "beforeReadFile": ["scan-secrets.sh", "caws-scope-guard.sh"],
+  "afterFileEdit": ["format.sh", "naming-check.sh", "validate-spec.sh", "caws-quality-check.sh", "audit.sh"],
+  "beforeSubmitPrompt": ["caws-scope-guard.sh", "audit.sh"],
+  "stop": ["audit.sh"]
+}
+```
+
+## Available Hooks
+
+### CAWS-Specific Hooks
+
+#### `caws-quality-check.sh`
+- **Trigger**: `afterFileEdit`
+- **Purpose**: Runs CAWS quality evaluation after code changes
+- **Blocks**: No (provides warnings and suggestions)
+- **Fallback**: Graceful degradation if CAWS CLI unavailable
+
+#### `caws-scope-guard.sh`
+- **Trigger**: `beforeReadFile`, `beforeSubmitPrompt`
+- **Purpose**: Prevents access to files outside CAWS-defined scope
+- **Blocks**: Yes (for out-of-scope file access)
+- **Requires**: `.caws/working-spec.yaml`
+
+#### `caws-tool-validation.sh`
+- **Trigger**: `beforeMCPExecution`
+- **Purpose**: Validates CAWS MCP tool calls for security
+- **Blocks**: Yes (for dangerous operations or invalid waivers)
+- **Validates**: Waiver creation, tool permissions, command safety
+
+### General Security Hooks
+
+#### `block-dangerous.sh`
+- **Trigger**: `beforeShellExecution`
+- **Purpose**: Prevents execution of dangerous shell commands
+- **Blocks**: `rm -rf /`, `sudo`, destructive operations
+
+#### `scan-secrets.sh`
+- **Trigger**: `beforeReadFile`
+- **Purpose**: Scans for potential secrets before file access
+- **Blocks**: Files containing password/token patterns
+
+### Code Quality Hooks
+
+#### `format.sh`
+- **Trigger**: `afterFileEdit`
+- **Purpose**: Auto-formats code using Prettier/ESLint
+- **Blocks**: No (formats in background)
+
+#### `naming-check.sh`
+- **Trigger**: `afterFileEdit`
+- **Purpose**: Enforces CAWS naming conventions
+- **Blocks**: No (provides warnings)
+
+#### `validate-spec.sh`
+- **Trigger**: `afterFileEdit`
+- **Purpose**: Validates CAWS working specs in real-time
+- **Blocks**: No (shows validation errors)
+
+### Audit Hooks
+
+#### `audit.sh`
+- **Trigger**: Multiple events
+- **Purpose**: Logs all hook executions for debugging
+- **Blocks**: No (passive logging)
+
+## Installation
+
+### Automatic Setup
+
+```bash
+# CAWS init automatically sets up Cursor hooks
+caws init my-project --interactive
+
+# Or manually scaffold hooks
+caws scaffold
+```
+
+### Manual Setup
+
+1. Copy `.cursor/` directory to your project root
+2. Ensure hook scripts are executable: `chmod +x .cursor/hooks/*.sh`
+3. Restart Cursor IDE
+4. Verify hooks are active in Cursor settings
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Enable debug logging
+export CURSOR_HOOKS_DEBUG=1
+
+# CAWS CLI path override
+export CAWS_CLI_PATH=/custom/path/to/caws
+
+# Disable specific hooks
+export CURSOR_DISABLE_HOOKS=audit.sh,format.sh
+```
+
+### Hook Customization
+
+Modify `hooks.json` to customize hook behavior:
+
+```json
+{
+  "afterFileEdit": [
+    {
+      "command": "./.cursor/hooks/caws-quality-check.sh",
+      "timeout": 5000,
+      "background": true
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### Hooks Not Running
+
+```bash
+# Check hook permissions
+ls -la .cursor/hooks/
+
+# Verify Cursor hooks are enabled
+# Cursor Settings → Hooks → Enable hooks
+
+# Check Cursor logs
+# Help → Toggle Developer Tools → Console
+```
+
+### CAWS CLI Not Found
+
+```bash
+# Install CAWS CLI
+npm install -g @caws/cli
+
+# Or use bundled version (VS Code extension)
+code --install-extension caws.caws-vscode-extension
+
+# Verify PATH
+which caws
+```
+
+### False Positives
+
+```bash
+# Temporarily disable hooks
+export CURSOR_DISABLE_HOOKS=caws-scope-guard.sh
+
+# Or modify hook logic
+vim .cursor/hooks/caws-scope-guard.sh
+```
+
+### Performance Issues
+
+```bash
+# Run hooks in background
+# Edit hooks.json to add "background": true
+
+# Increase timeouts
+# Edit hooks.json to add "timeout": 10000
+
+# Disable slow hooks
+export CURSOR_DISABLE_HOOKS=format.sh,naming-check.sh
+```
+
+## Development
+
+### Creating New Hooks
+
+1. **Create script** in `.cursor/hooks/`
+2. **Make executable**: `chmod +x .cursor/hooks/your-hook.sh`
+3. **Add to configuration** in `hooks.json`
+4. **Test manually**: `echo '{}' | ./cursor/hooks/your-hook.sh`
+
+### Hook Script Template
+
+```bash
+#!/bin/bash
+# CAWS Hook: Description
+# @author @darianrosebrook
+
+set -e
+
+# Read Cursor input
+INPUT=$(cat)
+DATA=$(echo "$INPUT" | jq -r '.data // ""')
+
+# Your hook logic here
+if [[ -n "$DATA" ]]; then
+  # Process data
+  echo '{"userMessage": "Hook executed", "agentMessage": "Details"}'
+fi
+
+exit 0
+```
+
+### Testing Hooks
+
+```bash
+# Test with sample input
+echo '{"action": "edit_file", "file_path": "test.js"}' | ./cursor/hooks/caws-quality-check.sh
+
+# Test error conditions
+echo '{}' | ./cursor/hooks/caws-scope-guard.sh
+
+# Debug with verbose output
+export CURSOR_HOOKS_DEBUG=1
+```
+
+## Integration with CAWS Ecosystem
+
+### Relationship to Other Tools
+
+```
+Cursor Hooks ←→ CAWS CLI ←→ VS Code Extension
+     ↓              ↓              ↓
+  Real-time      Command-line    Rich IDE
+  Validation     Interface       Integration
+```
+
+### Complementary Tools
+
+- **Git Hooks**: `.git/hooks/` for commit/push validation
+- **VS Code Extension**: Rich UI for CAWS operations
+- **MCP Server**: Agent tool integration
+- **CAWS CLI**: Core functionality
+
+### Data Flow
+
+```
+File Edit → Cursor Hook → CAWS CLI → Quality Check → User Feedback
+                             ↓
+                      Audit Log → Provenance Tracking
+```
+
+## Security Considerations
+
+### Safe Execution
+
+- Hooks run in isolated processes
+- No access to sensitive Cursor data
+- Input validation on all hook data
+- Timeout protection against hanging hooks
+
+### Privacy Protection
+
+- File contents not sent to external services
+- Local CAWS CLI execution only
+- No telemetry or data collection
+- User-controlled hook execution
+
+## Performance Optimization
+
+### Hook Design Principles
+
+1. **Fast Execution**: < 2 seconds for real-time feedback
+2. **Background Processing**: Non-blocking operations
+3. **Selective Running**: Only run relevant hooks
+4. **Caching**: Avoid redundant operations
+
+### Optimization Strategies
+
+- **Debounced execution** for file edit hooks
+- **Incremental validation** for large codebases
+- **Parallel processing** for independent checks
+- **Result caching** for repeated operations
+
+## Contributing
+
+### Hook Development Guidelines
+
+- **Clear naming**: `caws-*` prefix for CAWS-specific hooks
+- **Comprehensive logging**: Debug-friendly output
+- **Error handling**: Graceful failure modes
+- **Documentation**: Inline comments and README updates
+- **Testing**: Manual and automated test coverage
+
+### Pull Request Process
+
+1. **Test locally** in Cursor IDE
+2. **Update documentation** in this README
+3. **Add configuration examples** if needed
+4. **Consider performance impact** on large codebases
+5. **Test with different project types** (CAWS/non-CAWS)
+
+## License
+
+MIT License - see main project LICENSE file.

package/dist/templates/.cursor/hooks/audit.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Cursor Hook: Audit Trail
+# 
+# Purpose: Log all Cursor AI events for provenance tracking
+# Event: All (beforeShellExecution, beforeMCPExecution, beforeReadFile, 
+#        afterFileEdit, beforeSubmitPrompt, stop)
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Create log directory if it doesn't exist
+LOG_DIR=".cursor/logs"
+mkdir -p "$LOG_DIR"
+
+# Log file with date rotation
+LOG_FILE="$LOG_DIR/audit-$(date +%Y-%m-%d).log"
+
+# Extract key information
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')
+CONVERSATION_ID=$(echo "$INPUT" | jq -r '.conversation_id // "none"')
+GENERATION_ID=$(echo "$INPUT" | jq -r '.generation_id // "none"')
+
+# Create audit entry
+AUDIT_ENTRY=$(cat <<EOF
+{
+  "timestamp": "$TIMESTAMP",
+  "event": "$HOOK_EVENT",
+  "conversation_id": "$CONVERSATION_ID",
+  "generation_id": "$GENERATION_ID",
+  "details": $INPUT
+}
+EOF
+)
+
+# Append to audit log
+echo "$AUDIT_ENTRY" >> "$LOG_FILE"
+
+# Try to update CAWS provenance if available
+if [ -f "apps/tools/caws/provenance.js" ]; then
+  node apps/tools/caws/provenance.js log-event \
+    --event="$HOOK_EVENT" \
+    --conversation="$CONVERSATION_ID" \
+    --generation="$GENERATION_ID" \
+    2>/dev/null || true
+fi
+
+# Always allow - this is observation only
+echo '{"permission":"allow"}' 2>/dev/null || true
+exit 0
+

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

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Cursor Hook: Dangerous Command Blocker
+# 
+# Purpose: Block or ask permission for risky shell commands
+# Event: beforeShellExecution
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Extract command and cwd
+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:"
+  "del /f /s /q"
+  "DROP DATABASE"
+  "TRUNCATE TABLE"
+)
+
+for blocked in "${HARD_BLOCKS[@]}"; do
+  if [[ "$COMMAND" == *"$blocked"* ]]; then
+    echo '{"permission":"deny","userMessage":"⚠️ BLOCKED: Dangerous command detected. This operation could cause data loss.","agentMessage":"This command is blocked for safety. If you need to perform this operation, run it manually."}' 2>/dev/null
+    exit 0
+  fi
+done
+
+# Ask permission for risky operations
+# Note: git commands moved to HARD_BLOCKS after catastrophic data loss incident
+ASK_PERMISSION=(
+  "rm -rf"
+  "npm publish"
+  "docker rmi"
+  "docker system prune"
+  "kubectl delete"
+  "terraform destroy"
+  "DROP TABLE"
+  "DELETE FROM"
+  "UPDATE.*SET"
+)
+
+for risky in "${ASK_PERMISSION[@]}"; do
+  if echo "$COMMAND" | grep -qiE "$risky"; then
+    echo '{"permission":"ask","userMessage":"⚠️ Risky operation: '"$COMMAND"'. Approve to continue.","agentMessage":"This is a potentially destructive operation. User approval required."}' 2>/dev/null
+    exit 0
+  fi
+done
+
+# Block git operations that skip hooks
+if echo "$COMMAND" | grep -qE "(--no-verify|--no-gpg-sign)"; then
+  echo '{"permission":"ask","userMessage":"⚠️ This command skips git hooks. Approve to continue.","agentMessage":"Skipping hooks bypasses quality gates. Use with caution."}' 2>/dev/null
+  exit 0
+fi
+
+# Block force push to main/master
+if echo "$COMMAND" | grep -qE "git push.*(--force|-f).*\s+(origin\s+)?(main|master)"; then
+  echo '{"permission":"deny","userMessage":"⚠️ BLOCKED: Force push to main/master is not allowed.","agentMessage":"Force pushing to main/master can cause data loss for other developers."}' 2>/dev/null
+  exit 0
+fi
+
+# Allow by default
+echo '{"permission":"allow"}' 2>/dev/null
+exit 0
+

package/dist/templates/.cursor/hooks/caws-quality-check.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# CAWS Quality Check Hook
+# Runs CAWS quality validation after file edits
+# @author @darianrosebrook
+
+set -e
+
+# Read input from Cursor
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
+
+# Only run on source files
+if [[ "$FILE_PATH" =~ \.(js|ts|jsx|tsx|py|go|rs|java)$ ]] && [[ ! "$FILE_PATH" =~ node_modules ]] && [[ ! "$FILE_PATH" =~ dist ]]; then
+
+  # Check if CAWS is available
+  if command -v caws &> /dev/null; then
+
+    # Check if we're in a CAWS project
+    if [[ -f ".caws/working-spec.yaml" ]]; then
+
+      echo "🔍 Running CAWS quality check..." >&2
+
+      # Run CAWS evaluation in quiet mode for fast feedback
+      if caws agent evaluate .caws/working-spec.yaml --quiet 2>/dev/null; then
+        echo '{"userMessage": "✅ CAWS quality check passed", "agentMessage": "Quality standards maintained"}'
+      else
+        # Get detailed feedback
+        EVALUATION=$(caws agent evaluate .caws/working-spec.yaml --json 2>/dev/null || echo '{"success": false, "error": "Evaluation failed"}')
+
+        # Parse the evaluation result
+        SUCCESS=$(echo "$EVALUATION" | jq -r '.success // false')
+        SCORE=$(echo "$EVALUATION" | jq -r '.evaluation.quality_score // 0')
+
+        if [[ "$SUCCESS" == "true" ]] && (( $(echo "$SCORE > 0.75" | bc -l) )); then
+          echo '{"userMessage": "✅ CAWS quality standards met", "agentMessage": "Code meets quality requirements"}'
+        else
+          FAILED_GATES=$(echo "$EVALUATION" | jq -r '.evaluation.criteria[] | select(.status == "failed") | .name' | tr '\n' ', ' | sed 's/, $//')
+
+          echo '{
+            "userMessage": "⚠️ CAWS quality issues detected. Run: caws agent evaluate",
+            "agentMessage": "Quality gates failed: '"$FAILED_GATES"'",
+            "suggestions": [
+              "Run caws agent evaluate for detailed feedback",
+              "Consider creating a waiver if justified: caws waivers create",
+              "Address failing quality gates before proceeding"
+            ]
+          }'
+        fi
+      fi
+    fi
+  fi
+fi