@paths.design/caws-cli 3.0.0 → 3.1.1

package/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/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/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/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 "apps/tools/caws/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 apps/tools/caws/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/templates/.cursor/hooks/validate-spec.sh

@@ -0,0 +1,38 @@
+#!/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 // ""')
+
+# Only validate if working-spec.yaml was edited
+if [[ "$FILE_PATH" == *"working-spec.yaml"* ]] || [[ "$FILE_PATH" == *"working-spec.yml"* ]]; then
+  # Run CAWS validation
+  if [ -f "apps/tools/caws/validate.js" ]; then
+    if ! node apps/tools/caws/validate.js --quiet 2>/dev/null; then
+      echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors. Please review and fix before continuing."}' 2>/dev/null
+      exit 0
+    fi
+  else
+    # Fallback: try caws CLI
+    if command -v caws &> /dev/null; then
+      if ! caws validate --quiet 2>/dev/null; then
+        echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors."}' 2>/dev/null
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# Allow the edit
+exit 0
+

package/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"
+      }
+    ]
+  }
+}

package/templates/.github/copilot/instructions.md

@@ -0,0 +1,311 @@
+# CAWS Integration Instructions for GitHub Copilot
+
+These instructions help Copilot understand and work with CAWS (Coding Agent Workflow System) quality assurance processes.
+
+## Overview
+
+CAWS provides structured quality assurance for AI-assisted development. When working on CAWS-enabled projects, follow these guidelines to maintain quality standards and leverage CAWS tools effectively.
+
+## CAWS Project Detection
+
+**Check if current project uses CAWS:**
+- Look for `.caws/working-spec.yaml` file
+- Check for `caws` commands in package.json scripts
+- Verify CAWS CLI availability: `caws --version`
+
+## Working with CAWS Working Specifications
+
+**Working specs define project requirements and constraints:**
+
+```yaml
+id: PROJ-001
+title: "Feature implementation"
+risk_tier: 2  # 1=Critical, 2=Standard, 3=Low risk
+mode: feature  # feature|refactor|fix|chore
+change_budget:
+  max_files: 25
+  max_loc: 1000
+scope:
+  in: ["src/", "tests/"]
+  out: ["node_modules/", "dist/"]
+```
+
+**Always validate working specs:**
+```bash
+caws validate .caws/working-spec.yaml
+```
+
+## Quality Assurance Workflow
+
+### 1. Pre-Implementation
+```
+# Get CAWS guidance before starting
+caws agent iterate --current-state "About to implement X"
+
+# CAWS will provide:
+# - Implementation suggestions
+# - Quality requirements
+# - Risk considerations
+```
+
+### 2. During Implementation
+```
+# Regular quality checks
+caws agent evaluate --quiet
+
+# Address any issues immediately
+# Create waivers only when justified
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+### 3. Pre-Commit Validation
+```
+# Comprehensive validation before commits
+caws validate
+caws agent evaluate
+
+# Fix any quality gate failures
+```
+
+## CAWS Quality Gates
+
+### Code Quality Gates
+- **Linting**: ESLint, Prettier formatting
+- **Type Checking**: TypeScript strict mode
+- **Security**: Dependency scanning, secret detection
+- **Performance**: Bundle size, runtime budgets
+
+### Testing Gates
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: Component interaction
+- **Contract Tests**: API contract validation
+- **E2E Tests**: Full workflow testing
+- **Mutation Tests**: Test effectiveness validation
+
+### Analysis Gates
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Complexity**: Maintainability metrics
+- **Coverage**: Test coverage thresholds
+
+## Waiver Management
+
+**Create waivers only for justified exceptions:**
+
+```bash
+# Example: Emergency security fix
+caws waivers create \
+  --title "Critical security vulnerability fix" \
+  --reason emergency_hotfix \
+  --gates coverage_threshold,contract_tests \
+  --expires-at "2025-11-01T00:00:00Z" \
+  --approved-by "security-team" \
+  --impact-level critical \
+  --mitigation-plan "Manual testing completed, security review passed"
+```
+
+**Waiver reasons:**
+- `emergency_hotfix` - Critical production issues
+- `legacy_integration` - Third-party compatibility
+- `experimental_feature` - Sandbox/prototype code
+- `performance_critical` - Hot path optimizations
+- `infrastructure_limitation` - Platform constraints
+
+## Scope Management
+
+**Respect CAWS-defined scope boundaries:**
+
+- **In scope**: Files listed in `scope.in` - full quality requirements apply
+- **Out of scope**: Files in `scope.out` - no CAWS restrictions
+- **Scope warnings**: Files outside primary scope but allowed
+
+**Check scope compliance:**
+```bash
+caws validate --scope-check path/to/file.js
+```
+
+## Risk Tier Considerations
+
+### Tier 1 (Critical) - Highest Quality Standards
+- 90%+ test coverage
+- All security scans pass
+- Performance budgets strictly enforced
+- Manual review required
+- Zero waivers allowed for core gates
+
+### Tier 2 (Standard) - Balanced Quality
+- 80%+ test coverage
+- Security scans pass
+- Performance budgets monitored
+- Peer review recommended
+- Limited waivers allowed
+
+### Tier 3 (Low Risk) - Flexible Development
+- 70%+ test coverage
+- Basic security checks
+- Relaxed performance budgets
+- Self-review acceptable
+- Waivers freely allowed
+
+## Common Patterns
+
+### Feature Development
+1. Update working spec with feature requirements
+2. Get CAWS implementation guidance
+3. Implement with regular quality checks
+4. Create comprehensive tests
+5. Validate all quality gates pass
+6. Generate provenance report
+
+### Bug Fixes
+1. Assess risk tier and impact
+2. Create minimal reproduction
+3. Implement fix with tests
+4. Run quality validation
+5. Create waiver if emergency fix
+6. Update working spec if scope changes
+
+### Refactoring
+1. Establish baseline quality metrics
+2. Create refactoring plan
+3. Implement changes incrementally
+4. Maintain test suite passing
+5. Run comprehensive validation
+6. Update documentation
+
+## Error Handling
+
+### Quality Gate Failures
+```
+❌ CAWS validation failed
+✅ Solution: Run caws validate --suggestions
+✅ Fix identified issues
+✅ Re-run validation
+```
+
+### Scope Violations
+```
+❌ File outside CAWS scope
+✅ Solution: Update .caws/working-spec.yaml scope
+✅ Or create waiver if justified
+```
+
+### Waiver Required
+```
+⚠️ High-risk change detected
+✅ Solution: caws waivers create with justification
+✅ Include mitigation plan
+✅ Get appropriate approval
+```
+
+## Best Practices
+
+### Code Quality
+- Follow established patterns and conventions
+- Write comprehensive tests with new code
+- Maintain existing test coverage
+- Address linting issues immediately
+
+### Documentation
+- Update working specs when requirements change
+- Document waiver justifications thoroughly
+- Keep provenance records current
+- Update API documentation for public interfaces
+
+### Collaboration
+- Communicate waiver needs early
+- Share quality gate results with team
+- Review high-risk changes together
+- Maintain collective code ownership
+
+### Performance
+- Monitor performance budgets during development
+- Optimize hot paths identified by CAWS
+- Address performance regressions immediately
+- Include performance tests for critical paths
+
+## Emergency Procedures
+
+### Production Hotfix
+1. Assess severity and business impact
+2. Create emergency waiver immediately
+3. Implement minimal fix with safety measures
+4. Add comprehensive tests post-fix
+5. Schedule follow-up quality improvements
+
+### Security Vulnerability
+1. Create critical waiver with security approval
+2. Implement minimal security fix
+3. Add security tests and monitoring
+4. Conduct security review
+5. Plan comprehensive fix for next release
+
+## Integration with Other Tools
+
+### Git Workflow
+- Pre-commit hooks run fast CAWS checks
+- Pre-push hooks run comprehensive validation
+- Post-commit hooks update provenance
+- Branch protection requires CAWS validation
+
+### CI/CD Pipeline
+- Automated CAWS quality gates
+- Tier-based conditional execution
+- Waiver validation and auditing
+- Provenance report generation
+
+### IDE Integration
+- Real-time quality feedback
+- Scope boundary enforcement
+- Automatic waiver suggestions
+- Quality dashboard visualization
+
+## Troubleshooting
+
+### CAWS CLI Issues
+```bash
+# Check installation
+caws --version
+
+# Update to latest version
+npm install -g @caws/cli@latest
+
+# Check working spec syntax
+caws validate --suggestions
+```
+
+### Quality Gate Failures
+```bash
+# Get detailed feedback
+caws agent evaluate
+
+# Check specific gate
+caws validate --gate linting
+
+# View waiver options
+caws waivers list --expiring-soon
+```
+
+### Performance Issues
+```bash
+# Skip heavy checks for urgent fixes
+caws validate --skip performance,mutation
+
+# Run fast checks only
+caws agent evaluate --quick
+```
+
+## Support
+
+### Getting Help
+- Run `caws --help` for command reference
+- Check `caws validate --suggestions` for specific issues
+- Review working spec documentation
+- Consult team CAWS guidelines
+
+### Common Issues
+- **Working spec invalid**: Fix YAML syntax and required fields
+- **Scope violations**: Update scope or create waiver
+- **Quality gate failures**: Address root cause, don't just waive
+- **Performance regressions**: Optimize or adjust budgets
+
+Remember: CAWS is designed to maintain quality while enabling development velocity. Use waivers judiciously and always prioritize code quality and security.

package/templates/.idea/runConfigurations/CAWS_Evaluate.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="CAWS: Evaluate Quality" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="agent evaluate .caws/working-spec.yaml">
+    <method v="2" />
+  </configuration>
+</component>

package/templates/.idea/runConfigurations/CAWS_Validate.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="CAWS: Validate" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="validate .caws/working-spec.yaml">
+    <method v="2" />
+  </configuration>
+</component>

package/templates/.vscode/launch.json

@@ -0,0 +1,56 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run CAWS Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension"],
+      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
+    },
+    {
+      "name": "Run CAWS Extension (Host Workspace)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension", "${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
+    },
+    {
+      "name": "Debug CAWS Extension",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-vscode-extension/out/extension.js",
+      "args": ["--inspect=6009"],
+      "env": {
+        "CAWS_DEBUG": "true"
+      },
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:compile"
+    },
+    {
+      "name": "Debug MCP Server",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-mcp-server/index.js",
+      "args": [],
+      "env": {
+        "NODE_ENV": "development",
+        "CAWS_DEBUG": "true"
+      },
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Debug CAWS CLI",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-cli/src/index.js",
+      "args": ["validate", ".caws/working-spec.yaml"],
+      "env": {
+        "NODE_ENV": "development",
+        "CAWS_DEBUG": "true"
+      },
+      "console": "integratedTerminal"
+    }
+  ]
+}