@paths.design/caws-cli 3.1.0 → 3.2.0

package/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/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/templates/.cursor/hooks/block-dangerous.sh

@@ -0,0 +1,77 @@
+#!/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
+HARD_BLOCKS=(
+  "rm -rf /"
+  "rm -rf /*"
+  "rm -rf ~"
+  "rm -rf $HOME"
+  "> /dev/sda"
+  "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
+ASK_PERMISSION=(
+  "rm -rf"
+  "git push --force"
+  "git reset --hard"
+  "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/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

package/templates/.cursor/hooks/caws-scope-guard.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# CAWS Scope Guard Hook
+# Prevents agents from accessing files outside CAWS-defined scope
+# @author @darianrosebrook
+
+set -e
+
+# Read input from Cursor
+INPUT=$(cat)
+ACTION=$(echo "$INPUT" | jq -r '.action // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
+
+# Check if CAWS is available and we have a working spec
+if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
+
+  # For file access actions, check scope
+  if [[ "$ACTION" == "read_file" ]] || [[ "$ACTION" == "edit_file" ]] || [[ -n "$FILE_PATH" ]]; then
+
+    # Get scope information from CAWS spec
+    SCOPE_CHECK=$(caws validate .caws/working-spec.yaml --scope-check "$FILE_PATH" 2>/dev/null || echo "unknown")
+
+    if [[ "$SCOPE_CHECK" == "out_of_scope" ]]; then
+      echo '{
+        "userMessage": "🚫 File access blocked by CAWS scope guard",
+        "agentMessage": "Cannot access '"$FILE_PATH"' - outside CAWS defined scope",
+        "block": true,
+        "suggestions": [
+          "Check CAWS working spec scope definition",
+          "Update scope in .caws/working-spec.yaml if needed",
+          "Create waiver for scope violation: caws waivers create --reason=scope_violation"
+        ]
+      }'
+      exit 1
+    elif [[ "$SCOPE_CHECK" == "scope_warning" ]]; then
+      echo '{
+        "userMessage": "⚠️ File access outside primary scope",
+        "agentMessage": "File '"$FILE_PATH"' is outside primary scope but allowed",
+        "suggestions": [
+          "Consider if this file should be in primary scope",
+          "Update .caws/working-spec.yaml scope if needed"
+        ]
+      }'
+    fi
+  fi
+
+  # For prompt submissions, check working spec compliance
+  if [[ "$ACTION" == "submit_prompt" ]]; then
+    PROMPT_CONTENT=$(echo "$INPUT" | jq -r '.prompt // ""')
+
+    # Check if prompt mentions files outside scope
+    if [[ -n "$PROMPT_CONTENT" ]]; then
+      MENTIONED_FILES=$(echo "$PROMPT_CONTENT" | grep -oE '\b[a-zA-Z0-9_/.-]+\.(js|ts|jsx|tsx|py|go|rs|java|yaml|json|md)\b' | sort | uniq || true)
+
+      OUT_OF_SCOPE=""
+      for file in $MENTIONED_FILES; do
+        if [[ -f "$file" ]] && ! caws validate .caws/working-spec.yaml --scope-check "$file" 2>/dev/null | grep -q "in_scope"; then
+          OUT_OF_SCOPE="$OUT_OF_SCOPE $file"
+        fi
+      done
+
+      if [[ -n "$OUT_OF_SCOPE" ]]; then
+        echo '{
+          "userMessage": "⚠️ Prompt references files outside CAWS scope",
+          "agentMessage": "Prompt mentions out-of-scope files: '"$OUT_OF_SCOPE"'",
+          "suggestions": [
+            "Focus on files within CAWS defined scope",
+            "Update working spec scope if additional files needed",
+            "Remove out-of-scope file references from prompt"
+          ]
+        }'
+      fi
+    fi
+  fi
+fi

package/templates/.cursor/hooks/caws-tool-validation.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# CAWS Tool Validation Hook
+# Validates MCP tool calls against CAWS security policies
+# @author @darianrosebrook
+
+set -e
+
+# Read input from Cursor
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+TOOL_ARGS=$(echo "$INPUT" | jq -r '.arguments // "{}"')
+
+# Only validate CAWS-related tools
+if [[ "$TOOL_NAME" =~ ^caws_ ]]; then
+
+  echo "🔍 Validating CAWS tool call: $TOOL_NAME" >&2
+
+  # Check if CAWS CLI is available
+  if ! command -v caws &> /dev/null; then
+    echo '{
+      "userMessage": "❌ CAWS CLI not available",
+      "agentMessage": "Cannot execute CAWS tools - CLI not installed",
+      "block": true,
+      "suggestions": [
+        "Install CAWS CLI: npm install -g @caws/cli",
+        "Check PATH includes CAWS CLI"
+      ]
+    }'
+    exit 1
+  fi
+
+  # Check if we're in a CAWS project
+  if [[ ! -f ".caws/working-spec.yaml" ]]; then
+    echo '{
+      "userMessage": "⚠️ Not in a CAWS project",
+      "agentMessage": "CAWS tools require .caws/working-spec.yaml",
+      "suggestions": [
+        "Initialize CAWS project: caws init",
+        "Create working spec: caws scaffold"
+      ]
+    }'
+  fi
+
+  # Validate tool-specific arguments
+  case "$TOOL_NAME" in
+    "caws_waiver_create")
+      # Check waiver creation permissions
+      IMPACT_LEVEL=$(echo "$TOOL_ARGS" | jq -r '.impactLevel // "low"')
+
+      if [[ "$IMPACT_LEVEL" == "critical" ]]; then
+        echo '{
+          "userMessage": "🚨 Critical waiver requires approval",
+          "agentMessage": "Critical impact waivers need human approval",
+          "block": false,
+          "warnings": [
+            "Critical waivers require code owner review",
+            "Waiver will be flagged for manual approval"
+          ]
+        }'
+      fi
+
+      # Check expiration time
+      EXPIRES_AT=$(echo "$TOOL_ARGS" | jq -r '.expiresAt // ""')
+      if [[ -n "$EXPIRES_AT" ]]; then
+        EXPIRE_TIME=$(date -j -f "%Y-%m-%dT%H:%M:%S%Z" "$EXPIRES_AT" +%s 2>/dev/null || echo "")
+        CURRENT_TIME=$(date +%s)
+        DAYS_DIFF=$(( (EXPIRE_TIME - CURRENT_TIME) / 86400 ))
+
+        if [[ $DAYS_DIFF -gt 90 ]]; then
+          echo '{
+            "userMessage": "⚠️ Waiver expiration too far in future",
+            "agentMessage": "Waivers cannot exceed 90 days expiration",
+            "suggestions": [
+              "Reduce expiration time to within 90 days",
+              "Consider shorter waiver periods for better security"
+            ]
+          }'
+        fi
+      fi
+      ;;
+
+    "caws_evaluate"|"caws_iterate")
+      # These are generally safe to run
+      echo '{"userMessage": "✅ CAWS quality tool validated", "agentMessage": "Tool execution approved"}'
+      ;;
+
+    *)
+      # Unknown CAWS tool - allow but warn
+      echo '{
+        "userMessage": "⚠️ Unknown CAWS tool",
+        "agentMessage": "Tool '"'"$TOOL_NAME"'"' not recognized - proceeding with caution",
+        "suggestions": [
+          "Verify tool name and arguments",
+          "Check CAWS CLI documentation"
+        ]
+      }'
+      ;;
+  esac
+
+elif [[ "$TOOL_NAME" =~ (exec|shell|run|terminal) ]]; then
+  # Generic shell execution - check for dangerous commands
+  COMMAND=$(echo "$TOOL_ARGS" | jq -r '.command // .cmd // ""')
+
+  DANGEROUS_COMMANDS=("rm -rf" "rm -rf /" "format" "mkfs" "dd" "fdisk" ">" "sudo" "chmod 777")
+
+  for dangerous in "${DANGEROUS_COMMANDS[@]}"; do
+    if [[ "$COMMAND" =~ $dangerous ]]; then
+      echo '{
+        "userMessage": "🚫 Dangerous command blocked",
+        "agentMessage": "Command contains dangerous operations: '"'"$dangerous"'"'",
+        "block": true,
+        "suggestions": [
+          "Avoid destructive operations",
+          "Use safer alternatives",
+          "Get explicit approval for dangerous commands"
+        ]
+      }'
+      exit 1
+    fi
+  done
+fi