@paths.design/caws-cli 7.0.2 → 7.0.3

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

@@ -0,0 +1,130 @@
+#!/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 agent 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/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

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

@@ -0,0 +1,38 @@
+#!/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
+

package/dist/templates/.cursor/hooks/naming-check.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Cursor Hook: Naming Conventions
+# 
+# Purpose: Enforce CAWS naming conventions (no enhanced-, -copy, etc.)
+# Event: afterFileEdit
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
+
+# Get just the filename
+FILENAME=$(basename "$FILE_PATH")
+
+# Check for banned naming patterns
+BANNED_PATTERNS=(
+  "enhanced-"
+  "-enhanced"
+  "unified-"
+  "-unified"
+  "better-"
+  "-better"
+  "new-"
+  "-new"
+  "next-"
+  "-next"
+  "final-"
+  "-final"
+  "-copy"
+  "copy-"
+  "-revamp"
+  "revamp-"
+  "-improved"
+  "improved-"
+)
+
+for pattern in "${BANNED_PATTERNS[@]}"; do
+  if [[ "$FILENAME" == *"$pattern"* ]]; then
+    # Extract the pattern for the message
+    echo '{"userMessage":"⚠️ Naming violation: File contains banned pattern '"'$pattern'"'. Use purpose-driven names instead.","agentMessage":"This file uses a generic naming pattern ('"$pattern"'). Please rename with a specific, purpose-driven name that describes what the file does."}' 2>/dev/null
+    exit 0
+  fi
+done
+
+# Check for duplicate module patterns (e.g., both processor.ts and enhanced-processor.ts)
+if [[ "$FILENAME" =~ ^(enhanced|unified|better|new|next|final|improved)- ]]; then
+  BASE_NAME=$(echo "$FILENAME" | sed -E 's/^(enhanced|unified|better|new|next|final|improved)-//')
+  DIR_PATH=$(dirname "$FILE_PATH")
+  
+  # Check if base file exists
+  if [ -f "$DIR_PATH/$BASE_NAME" ]; then
+    echo '{"userMessage":"⚠️ Duplicate module detected: Both '"$FILENAME"' and '"$BASE_NAME"' exist. Merge into canonical name.","agentMessage":"Found duplicate modules. Please merge '"$FILENAME"' into '"$BASE_NAME"' and remove the duplicate."}' 2>/dev/null
+    exit 0
+  fi
+fi
+
+# Allow by default
+exit 0
+

package/dist/templates/.cursor/hooks/scan-secrets.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Cursor Hook: Secret & PII Scanner
+# 
+# Purpose: Prevent reading files with secrets or sensitive information
+# Event: beforeReadFile
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Extract file path and content
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
+CONTENT=$(echo "$INPUT" | jq -r '.content // ""')
+
+# Block reading of environment files
+if [[ "$FILE_PATH" =~ \.(env|env\.local|env\.development|env\.production|env\.test)$ ]]; then
+  echo '{"permission":"deny","userMessage":"⚠️ Blocked: Environment files contain secrets. Use placeholder values instead."}' 2>/dev/null
+  exit 0
+fi
+
+# Block reading of key files
+if [[ "$FILE_PATH" =~ \.(pem|key|p12|pfx|cert|crt)$ ]]; then
+  echo '{"permission":"deny","userMessage":"⚠️ Blocked: Certificate/key files should not be read by AI."}' 2>/dev/null
+  exit 0
+fi
+
+# Scan content for common secret patterns
+if echo "$CONTENT" | grep -qiE "(api[_-]?key|secret[_-]?key|password|private[_-]?key|access[_-]?token|bearer\s+[A-Za-z0-9_\-\.]+|AKIA[0-9A-Z]{16})"; then
+  # Don't block, but warn
+  echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential secrets detected in file. Ensure they are not committed.","agentMessage":"This file may contain secrets. Use placeholder values or environment variables."}' 2>/dev/null
+  exit 0
+fi
+
+# Check for common PII patterns (SSN, credit card, etc.)
+if echo "$CONTENT" | grep -qE "([0-9]{3}-[0-9]{2}-[0-9]{4}|[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4})"; then
+  echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential PII detected. Ensure compliance with data protection policies.","agentMessage":"This file may contain PII (SSN, credit card). Use anonymized test data."}' 2>/dev/null
+  exit 0
+fi
+
+# Allow by default
+echo '{"permission":"allow"}' 2>/dev/null
+exit 0
+

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

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Cursor Hook: Scope Guard
+# 
+# Purpose: Check if files being worked on are within working-spec scope
+# Event: beforeSubmitPrompt
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Extract attachments
+ATTACHMENTS=$(echo "$INPUT" | jq -r '.attachments // []')
+
+# Only check if we have file attachments and a working spec
+if [ ! -f ".caws/working-spec.yaml" ] && [ ! -f ".caws/working-spec.yml" ]; then
+  # No spec file, allow by default
+  echo '{"continue":true}' 2>/dev/null
+  exit 0
+fi
+
+# Check if scope-guard tool exists
+if [ -f ".caws/tools/scope-guard.js" ]; then
+  # Extract file paths from attachments
+  FILE_PATHS=$(echo "$ATTACHMENTS" | jq -r '.[] | select(.type=="file") | .file_path' 2>/dev/null || echo "")
+  
+  if [ -n "$FILE_PATHS" ]; then
+    # Check each file against scope
+    OUT_OF_SCOPE=()
+    while IFS= read -r file; do
+      if [ -n "$file" ]; then
+        if ! node .caws/tools/scope-guard.js check "$file" 2>/dev/null; then
+          OUT_OF_SCOPE+=("$file")
+        fi
+      fi
+    done <<< "$FILE_PATHS"
+    
+    # If any files are out of scope, warn but don't block
+    if [ ${#OUT_OF_SCOPE[@]} -gt 0 ]; then
+      FILES_LIST=$(printf '%s\n' "${OUT_OF_SCOPE[@]}")
+      echo '{"continue":true,"userMessage":"⚠️ Warning: Some attached files may be outside working-spec scope:\n'"$FILES_LIST"'","agentMessage":"Some files are outside the defined scope in working-spec.yaml. Consider updating the scope or removing these files."}' 2>/dev/null
+      exit 0
+    fi
+  fi
+fi
+
+# Allow by default
+echo '{"continue":true}' 2>/dev/null
+exit 0
+

package/dist/templates/.cursor/hooks/validate-spec.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Cursor Hook: CAWS Spec Validation
+# 
+# Purpose: Validate working-spec.yaml when it's edited
+# Event: afterFileEdit
+# 
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read input from Cursor
+INPUT=$(cat)
+
+# Extract file path from input
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
+
+# Validate if any CAWS YAML file was edited (.caws/**/*.yaml or .caws/**/*.yml)
+if [[ "$FILE_PATH" == *".caws/"* ]] && ([[ "$FILE_PATH" == *.yaml ]] || [[ "$FILE_PATH" == *.yml ]]); then
+  echo "🔍 Validating CAWS spec file..." >&2
+
+  # First, validate YAML syntax
+  if command -v node >/dev/null 2>&1; then
+    # Check YAML syntax using Node.js
+    YAML_SYNTAX_VALID=$(node -e "
+      const yaml = require('js-yaml');
+      const fs = require('fs');
+      try {
+        const content = fs.readFileSync('$FILE_PATH', 'utf8');
+        yaml.load(content);
+        process.exit(0);
+      } catch (error) {
+        console.error('YAML syntax error:', error.message);
+        if (error.mark) {
+          console.error('Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+        }
+        process.exit(1);
+      }
+    " 2>&1)
+
+    if [ $? -ne 0 ]; then
+      echo '{
+        "userMessage": "⚠️ YAML syntax error detected",
+        "agentMessage": "The spec file has invalid YAML syntax. Fix syntax errors before continuing.",
+        "suggestions": [
+          "Check indentation (YAML uses 2 spaces)",
+          "Ensure all array items use consistent format",
+          "Remove duplicate keys",
+          "Consider using '\''caws specs create <id>'\'' instead of manual creation"
+        ]
+      }' 2>/dev/null
+      exit 0
+    fi
+  fi
+
+  # Check if CAWS CLI is available for semantic validation
+  if command -v caws &> /dev/null; then
+    # Run CAWS validation with suggestions
+    if VALIDATION=$(caws validate "$FILE_PATH" --quiet 2>&1); then
+      echo '{"userMessage":"✅ CAWS spec validation passed","agentMessage":"Specification is valid and complete."}' 2>/dev/null
+    else
+      # Get suggestions for fixing the spec
+      SUGGESTIONS=$(caws validate "$FILE_PATH" --suggestions 2>/dev/null | head -5 | tr '\n' '; ' | sed 's/; $//' || echo "Run caws validate --suggestions for details")
+
+      echo '{
+        "userMessage": "⚠️ CAWS spec validation failed. Run: caws validate --suggestions",
+        "agentMessage": "The spec file has validation errors. Please review and fix before continuing.",
+        "suggestions": [
+          "Run caws validate --suggestions for detailed error messages",
+          "Check required fields: id, title, risk_tier, mode",
+          "Ensure acceptance criteria are properly defined",
+          "Verify scope boundaries are appropriate",
+          "Consider using '\''caws specs create <id>'\'' for proper structure"
+        ]
+      }' 2>/dev/null
+    fi
+  else
+    echo '{"userMessage":"⚠️ CAWS CLI not available for validation","agentMessage":"Install CAWS CLI for automatic spec validation: npm install -g @caws/cli"}' 2>/dev/null
+  fi
+fi
+
+# Allow the edit
+exit 0
+

package/dist/templates/.cursor/hooks.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "./.cursor/hooks/block-dangerous.sh"
+      },
+      {
+        "command": "./.cursor/hooks/audit.sh"
+      }
+    ],
+    "beforeMCPExecution": [
+      {
+        "command": "./.cursor/hooks/audit.sh"
+      },
+      {
+        "command": "./.cursor/hooks/caws-tool-validation.sh"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "./.cursor/hooks/scan-secrets.sh"
+      },
+      {
+        "command": "./.cursor/hooks/caws-scope-guard.sh"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "./.cursor/hooks/format.sh"
+      },
+      {
+        "command": "./.cursor/hooks/naming-check.sh"
+      },
+      {
+        "command": "./.cursor/hooks/validate-spec.sh"
+      },
+      {
+        "command": "./.cursor/hooks/caws-quality-check.sh"
+      },
+      {
+        "command": "./.cursor/hooks/audit.sh"
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "./.cursor/hooks/caws-scope-guard.sh"
+      },
+      {
+        "command": "./.cursor/hooks/audit.sh"
+      }
+    ],
+    "stop": [
+      {
+        "command": "./.cursor/hooks/audit.sh"
+      }
+    ]
+  }
+}