@paths.design/caws-cli 10.2.0 → 11.0.0

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

@@ -1,299 +0,0 @@
-# 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
-- **Quality monitoring** after file edits
-
-## Hook Configuration
-
-The `hooks.json` file defines when each hook runs:
-
-```json
-{
-  "beforeShellExecution": ["block-dangerous.sh", "audit.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`
-
-### 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
-
-# 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
-- **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

@@ -1,55 +0,0 @@
-#!/bin/bash
-# Cursor Hook: Audit Trail
-# 
-# Purpose: Log all Cursor AI events for provenance tracking
-# Event: All (beforeShellExecution, 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

@@ -1,84 +0,0 @@
-#!/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
-  "git rebase"                   # Rewrites branch history; blocked while worktrees are active
-  "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

@@ -1,52 +0,0 @@
-#!/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 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 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 evaluate",
-            "agentMessage": "Quality gates failed: '"$FAILED_GATES"'",
-            "suggestions": [
-              "Run caws 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/dist/templates/.cursor/hooks/caws-scope-guard.sh

@@ -1,130 +0,0 @@
-#!/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
-
-  # AGENT GUARDRAILS - Prevent policy bypass attempts
-  if [[ "$ACTION" == "edit_file" ]] || [[ "$ACTION" == "create_file" ]]; then
-    if [[ "$FILE_PATH" == ".caws/policy.yaml" ]]; then
-      echo '{
-        "userMessage": "🚫 Policy file editing blocked by agent guardrails",
-        "agentMessage": "Agents cannot edit .caws/policy.yaml - requires human dual control",
-        "block": true,
-        "suggestions": [
-          "Policy changes must be approved by humans with Gatekeeper role",
-          "Create a separate PR for policy changes",
-          "For budget exceptions: caws waivers create --title=\"Budget exception\" --reason=architectural_refactor --gates=budget_limit",
-          "Contact @gatekeepers for policy modifications"
-        ]
-      }'
-      exit 1
-    fi
-
-    if [[ "$FILE_PATH" == "CODEOWNERS" ]]; then
-      echo '{
-        "userMessage": "🚫 CODEOWNERS editing blocked by agent guardrails",
-        "agentMessage": "Agents cannot modify CODEOWNERS - governance changes require approval",
-        "block": true,
-        "suggestions": [
-          "CODEOWNERS changes require governance review",
-          "Contact repository maintainers for ownership changes",
-          "For approval workflows: caws waivers create --reason=governance_change"
-        ]
-      }'
-      exit 1
-    fi
-
-    if [[ "$FILE_PATH" == ".caws/working-spec.yaml" ]]; then
-      # Check if trying to add change_budget
-      FILE_CONTENT=$(echo "$INPUT" | jq -r '.content // ""')
-      if echo "$FILE_CONTENT" | grep -q "change_budget"; then
-        echo '{
-          "userMessage": "🚫 Budget editing blocked by agent guardrails",
-          "agentMessage": "Agents cannot introduce change_budget fields - budgets are derived automatically",
-          "block": true,
-          "suggestions": [
-            "Check current budget status: caws burnup",
-            "For budget exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=budget_limit --expires-at=\"2025-12-31T23:59:59Z\"",
-            "Add waiver_ids to working spec instead: [\"WV-XXXX\"]",
-            "Validate waiver: caws validate .caws/working-spec.yaml"
-          ]
-        }'
-        exit 1
-      fi
-    fi
-  fi
-
-  # 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 current scope: caws validate .caws/working-spec.yaml",
-          "Update scope in working spec: edit .caws/working-spec.yaml scope.in array",
-          "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary --description=\"Need access to '"$FILE_PATH"' for implementation\"",
-          "Validate changes: caws validate .caws/working-spec.yaml"
-        ]
-      }'
-      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": [
-          "Check if needed in primary scope: edit .caws/working-spec.yaml scope.in",
-          "Consider scope implications: caws evaluate",
-          "Document scope decision in working spec invariants",
-          "Validate scope changes: caws validate .caws/working-spec.yaml"
-        ]
-      }'
-    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": [
-            "Check current scope definition: caws validate .caws/working-spec.yaml",
-            "Update working spec scope: edit .caws/working-spec.yaml scope.in array",
-            "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary",
-            "Refocus prompt on in-scope files or request scope update approval",
-            "Validate scope changes: caws validate .caws/working-spec.yaml"
-          ]
-        }'
-      fi
-    fi
-  fi
-fi

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

@@ -1,38 +0,0 @@
-#!/bin/bash
-# Cursor Hook: Auto-formatting
-# 
-# Purpose: Run formatters after file edits
-# Event: afterFileEdit
-# 
-# @author @darianrosebrook
-
-set -euo pipefail
-
-# Read input from Cursor
-INPUT=$(cat)
-
-# Extract file path
-FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
-
-# Only format source code files
-if [[ "$FILE_PATH" =~ \.(js|ts|jsx|tsx|json|md|yml|yaml)$ ]]; then
-  # Try prettier if available
-  if command -v prettier &> /dev/null; then
-    prettier --write "$FILE_PATH" 2>/dev/null || true
-  elif [ -f "node_modules/.bin/prettier" ]; then
-    node_modules/.bin/prettier --write "$FILE_PATH" 2>/dev/null || true
-  fi
-  
-  # Try eslint for JS/TS files
-  if [[ "$FILE_PATH" =~ \.(js|ts|jsx|tsx)$ ]]; then
-    if command -v eslint &> /dev/null; then
-      eslint --fix "$FILE_PATH" 2>/dev/null || true
-    elif [ -f "node_modules/.bin/eslint" ]; then
-      node_modules/.bin/eslint --fix "$FILE_PATH" 2>/dev/null || true
-    fi
-  fi
-fi
-
-# Always allow - formatting is non-blocking
-exit 0
-