@paths.design/caws-cli 8.0.1 → 8.2.0

package/templates/.claude/hooks/naming-check.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# CAWS Naming Convention Check Hook for Claude Code
+# Validates file naming against CAWS conventions
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract file path from PostToolUse input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only check Write tool (new files)
+if [[ "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Get filename
+FILENAME=$(basename "$FILE_PATH")
+
+# Banned modifiers that indicate incomplete/temporary naming
+BANNED_MODIFIERS=(
+  "enhanced"
+  "unified"
+  "simplified"
+  "better"
+  "new"
+  "next"
+  "final"
+  "copy"
+  "revamp"
+  "improved"
+  "alt"
+  "tmp"
+  "scratch"
+  "wip"
+  "test-"
+  "-test"
+  "_test"
+  "temp"
+  "old"
+  "backup"
+)
+
+# Convert filename to lowercase for checking
+FILENAME_LOWER=$(echo "$FILENAME" | tr '[:upper:]' '[:lower:]')
+
+# Check for banned modifiers
+for modifier in "${BANNED_MODIFIERS[@]}"; do
+  if [[ "$FILENAME_LOWER" == *"$modifier"* ]]; then
+    # Special case: allow test files that follow conventions
+    if [[ "$modifier" == "test-" ]] || [[ "$modifier" == "-test" ]] || [[ "$modifier" == "_test" ]]; then
+      if [[ "$FILENAME_LOWER" =~ \.(test|spec)\.(js|ts|jsx|tsx|py|go|rs)$ ]]; then
+        continue
+      fi
+    fi
+
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains the modifier '\'''"$modifier"''\'' which may indicate temporary or non-canonical naming. Consider using a more descriptive, permanent name. See CAWS naming conventions in .caws/canonical-map.yaml or run '\''caws naming check'\''."
+      }
+    }'
+    exit 0
+  fi
+done
+
+# Check for version suffixes (e.g., file-v2.js, file_v3.ts)
+if [[ "$FILENAME_LOWER" =~ [-_]v[0-9]+\. ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a version suffix. Version control should be handled by git, not file names. Consider removing the version suffix."
+    }
+  }'
+  exit 0
+fi
+
+# Check for date stamps (e.g., file-2024-01-15.js)
+if [[ "$FILENAME_LOWER" =~ [0-9]{4}[-_][0-9]{2}[-_][0-9]{2} ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a date stamp. Version control should be handled by git, not file names. Consider removing the date."
+    }
+  }'
+  exit 0
+fi
+
+# File naming is OK
+exit 0

package/templates/.claude/hooks/quality-check.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# CAWS Quality Check Hook for Claude Code
+# Runs CAWS quality validation after file edits
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract file info from PostToolUse input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only run on Write/Edit of source files
+if [[ "$TOOL_NAME" != "Write" ]] && [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Skip non-source files and node_modules/dist
+if [[ ! "$FILE_PATH" =~ \.(js|ts|jsx|tsx|py|go|rs|java|mjs|cjs)$ ]] || \
+   [[ "$FILE_PATH" =~ node_modules ]] || \
+   [[ "$FILE_PATH" =~ dist/ ]] || \
+   [[ "$FILE_PATH" =~ build/ ]]; then
+  exit 0
+fi
+
+# Determine project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Check if we're in a CAWS project
+if [[ ! -f "$PROJECT_DIR/.caws/working-spec.yaml" ]]; then
+  exit 0
+fi
+
+# Check if CAWS CLI is available
+if ! command -v caws &> /dev/null; then
+  # Suggest installing CAWS
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @caws/cli"
+    }
+  }'
+  exit 0
+fi
+
+# Run CAWS quality gates in quiet mode for quick feedback
+if caws quality-gates --context=commit --quiet 2>/dev/null; then
+  # Quality check passed - provide positive feedback
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Quality gates passed for this change."
+    }
+  }'
+else
+  # Quality check failed - provide feedback to Claude
+  # Run again to get violations summary
+  VIOLATIONS=$(caws quality-gates --context=commit --json 2>/dev/null | jq -r '.violations[:3] | .[] | "- \(.gate): \(.message)"' 2>/dev/null || echo "Run 'caws quality-gates' for details")
+
+  echo '{
+    "decision": "block",
+    "reason": "Quality gate violations detected. Please address the following issues before continuing:\n'"$VIOLATIONS"'\n\nRun '\''caws quality-gates'\'' for full details."
+  }'
+fi
+
+exit 0

package/templates/.claude/hooks/scan-secrets.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# CAWS Secret Scanner for Claude Code
+# Warns when reading files that may contain secrets
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Get just the filename for pattern matching
+FILENAME=$(basename "$FILE_PATH")
+
+# Files that commonly contain secrets
+SECRET_FILE_PATTERNS=(
+  '.env'
+  '.env.local'
+  '.env.production'
+  '.env.development'
+  '.env.*'
+  'credentials.json'
+  'service-account.json'
+  'secrets.yaml'
+  'secrets.yml'
+  'secrets.json'
+  '.netrc'
+  '.npmrc'
+  '.pypirc'
+  'id_rsa'
+  'id_ed25519'
+  'id_ecdsa'
+  '*.pem'
+  '*.key'
+  '*.p12'
+  '*.pfx'
+  'htpasswd'
+  'shadow'
+)
+
+# Directories that commonly contain secrets
+SECRET_DIRS=(
+  '.ssh'
+  '.aws'
+  '.azure'
+  '.gcloud'
+  '.kube'
+  '.gnupg'
+)
+
+# Check if file matches secret patterns
+for pattern in "${SECRET_FILE_PATTERNS[@]}"; do
+  if [[ "$FILENAME" == $pattern ]]; then
+    # Output JSON with warning for Claude
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "WARNING: This file may contain secrets. Do not include sensitive values in your response. If you need to reference credentials, use placeholders like <API_KEY> instead of actual values."
+      }
+    }'
+    exit 0
+  fi
+done
+
+# Check if file is in a sensitive directory
+for dir in "${SECRET_DIRS[@]}"; do
+  if [[ "$FILE_PATH" == *"/$dir/"* ]] || [[ "$FILE_PATH" == *"/$dir" ]]; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "WARNING: This file is in a sensitive directory that may contain secrets. Do not include any sensitive values in your response."
+      }
+    }'
+    exit 0
+  fi
+done
+
+# Allow the read
+exit 0

package/templates/.claude/hooks/scope-guard.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# CAWS Scope Guard Hook for Claude Code
+# Validates file edits against the working spec's scope boundaries
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract file path from PreToolUse input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only check Write/Edit operations
+if [[ "$TOOL_NAME" != "Write" ]] && [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+SPEC_FILE="$PROJECT_DIR/.caws/working-spec.yaml"
+SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
+
+# Check if spec file or scope.json exists
+if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]]; then
+  exit 0
+fi
+
+# Get relative path from project root (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Lite mode: check scope.json if no working-spec.yaml
+if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
+  if command -v node >/dev/null 2>&1; then
+    LITE_CHECK=$(node -e "
+      const fs = require('fs');
+      const path = require('path');
+      try {
+        const scope = JSON.parse(fs.readFileSync('$SCOPE_FILE', 'utf8'));
+        const filePath = '$REL_PATH';
+        const dirs = scope.allowedDirectories || [];
+        const banned = scope.bannedPatterns || {};
+
+        // Check banned file patterns
+        const basename = path.basename(filePath);
+        const bannedFiles = banned.files || [];
+        for (const pattern of bannedFiles) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(basename)) {
+            console.log('banned:' + pattern);
+            process.exit(0);
+          }
+        }
+
+        // Check banned doc patterns
+        const bannedDocs = banned.docs || [];
+        for (const pattern of bannedDocs) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(basename)) {
+            console.log('banned:' + pattern);
+            process.exit(0);
+          }
+        }
+
+        // Check allowed directories
+        if (dirs.length > 0) {
+          const normalized = filePath.replace(/\\\\\\\\/g, '/');
+          let found = false;
+          for (const dir of dirs) {
+            const d = dir.replace(/\\/$/, '');
+            if (normalized.startsWith(d + '/') || normalized === d) { found = true; break; }
+          }
+          // Allow root-level files and .caws/ directory
+          if (!normalized.includes('/') || normalized.startsWith('.caws/')) found = true;
+          if (!found) {
+            console.log('not_allowed');
+            process.exit(0);
+          }
+        }
+        console.log('allowed');
+      } catch (error) {
+        console.log('error:' + error.message);
+      }
+    " 2>&1)
+
+    if [[ "$LITE_CHECK" == banned:* ]]; then
+      PATTERN="${LITE_CHECK#banned:}"
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PreToolUse",
+          "permissionDecision": "ask",
+          "permissionDecisionReason": "This file ('"$REL_PATH"') matches a banned pattern ('"$PATTERN"') in .caws/scope.json. Creating files with this pattern is blocked to prevent file sprawl."
+        }
+      }'
+      exit 0
+    fi
+
+    if [[ "$LITE_CHECK" == "not_allowed" ]]; then
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PreToolUse",
+          "permissionDecision": "ask",
+          "permissionDecisionReason": "This file ('"$REL_PATH"') is outside the allowed directories in .caws/scope.json. Please confirm this edit is intentional."
+        }
+      }'
+      exit 0
+    fi
+
+    # File is allowed - exit normally
+    exit 0
+  fi
+fi
+
+# Use Node.js to parse YAML and check scope
+if command -v node >/dev/null 2>&1; then
+  SCOPE_CHECK=$(node -e "
+    const yaml = require('js-yaml');
+    const fs = require('fs');
+    const path = require('path');
+
+    try {
+      const spec = yaml.load(fs.readFileSync('$SPEC_FILE', 'utf8'));
+      const filePath = '$REL_PATH';
+
+      // Check if file is explicitly out of scope
+      const outOfScope = spec.scope?.out || [];
+      for (const pattern of outOfScope) {
+        // Simple glob-like matching
+        const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+        if (regex.test(filePath)) {
+          console.log('out_of_scope:' + pattern);
+          process.exit(0);
+        }
+      }
+
+      // Check if file is in scope (if scope is explicitly defined)
+      const inScope = spec.scope?.in || [];
+      if (inScope.length > 0) {
+        let found = false;
+        for (const pattern of inScope) {
+          const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+          if (regex.test(filePath)) {
+            found = true;
+            break;
+          }
+        }
+        if (!found) {
+          console.log('not_in_scope');
+          process.exit(0);
+        }
+      }
+
+      console.log('in_scope');
+    } catch (error) {
+      console.log('error:' + error.message);
+    }
+  " 2>&1)
+
+  if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
+    PATTERN="${SCOPE_CHECK#out_of_scope:}"
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "This file ('"$REL_PATH"') is marked as out-of-scope in the working spec (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
+      }
+    }'
+    exit 0
+  fi
+
+  if [[ "$SCOPE_CHECK" == "not_in_scope" ]]; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "This file ('"$REL_PATH"') is not in the defined scope of the working spec. Editing it may cause scope creep. Please confirm this edit is intentional."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# File is in scope or scope couldn't be checked - allow
+exit 0

package/templates/.claude/hooks/simplification-guard.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# CAWS Simplification Guard Hook
+# Detects when files are being stubbed out (large deletions + stub content)
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Edit operations (modifications to existing files)
+if [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Get relative path (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Only check code files
+case "$REL_PATH" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs|*.py|*.rs|*.go|*.java|*.kt|*.swift|*.rb|*.php|*.c|*.cpp|*.h)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Check if the file exists in git (skip new files)
+if ! git show "HEAD:$REL_PATH" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Compare staged version with HEAD
+if command -v node >/dev/null 2>&1; then
+  SIMP_CHECK=$(node -e "
+    const { execFileSync } = require('child_process');
+    try {
+      const headContent = execFileSync('git', ['show', 'HEAD:$REL_PATH'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const currentContent = require('fs').readFileSync('$FILE_PATH', 'utf8');
+
+      const countLOC = (c) => c.split('\\n').filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('#')).length;
+      const headLOC = countLOC(headContent);
+      const currentLOC = countLOC(currentContent);
+
+      if (headLOC < 10) { console.log('ok'); process.exit(0); }
+
+      const decrease = (headLOC - currentLOC) / headLOC;
+
+      // Check for stub patterns in new content
+      const stubPatterns = [/^\\s*pass\\s*$/m, /^\\s*\\.\\.\\.\\s*$/m, /raise\\s+NotImplementedError/,
+        /throw\\s+new\\s+Error.*not implemented/i, /\\/\\/\\s*TODO\\s*$/m, /#\\s*TODO\\s*$/m];
+      const hasStubs = stubPatterns.some(p => p.test(currentContent));
+
+      if (decrease >= 0.3 && hasStubs) {
+        console.log('simplified:' + Math.round(decrease * 100) + ':' + headLOC + ':' + currentLOC);
+      } else {
+        console.log('ok');
+      }
+    } catch (error) {
+      console.log('ok');
+    }
+  " 2>&1)
+
+  if [[ "$SIMP_CHECK" == simplified:* ]]; then
+    IFS=':' read -r _ PERCENT OLD_LOC NEW_LOC <<< "$SIMP_CHECK"
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "WARNING: This edit would reduce '"$REL_PATH"' by '"$PERCENT"'% ('"$OLD_LOC"' → '"$NEW_LOC"' LOC) and introduces stub patterns (pass, TODO, NotImplementedError). This looks like a simplification — implementations should be modified, not replaced with stubs. Please confirm this is intentional."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# Allow the edit
+exit 0

package/templates/.claude/hooks/validate-spec.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# CAWS Spec Validation Hook for Claude Code
+# Validates working-spec.yaml when it's edited
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract file path from PostToolUse input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only validate CAWS YAML files
+if [[ "$FILE_PATH" != *".caws/"* ]] || ([[ "$FILE_PATH" != *.yaml ]] && [[ "$FILE_PATH" != *.yml ]]); then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# First, validate YAML syntax using Node.js if available
+if command -v node >/dev/null 2>&1; then
+  YAML_CHECK=$(node -e "
+    try {
+      const yaml = require('js-yaml');
+      const fs = require('fs');
+      const content = fs.readFileSync('$FILE_PATH', 'utf8');
+      yaml.load(content);
+      console.log('valid');
+    } catch (error) {
+      console.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 '{
+      "decision": "block",
+      "reason": "YAML syntax error in spec file:\n'"$YAML_CHECK"'\n\nPlease fix the syntax before continuing. Common issues:\n- Check indentation (YAML uses 2 spaces)\n- Ensure arrays use consistent format\n- Remove duplicate keys"
+    }'
+    exit 0
+  fi
+fi
+
+# Run CAWS CLI validation if available
+if command -v caws &> /dev/null; then
+  if VALIDATION=$(caws validate "$FILE_PATH" --quiet 2>&1); then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Spec validation passed. The specification is valid and complete."
+      }
+    }'
+  else
+    # Get suggestions
+    SUGGESTIONS=$(caws validate "$FILE_PATH" --suggestions 2>/dev/null | head -5 | tr '\n' ' ' || echo "Run 'caws validate --suggestions' for details")
+
+    echo '{
+      "decision": "block",
+      "reason": "Spec validation failed:\n'"$VALIDATION"'\n\nSuggestions:\n'"$SUGGESTIONS"'"
+    }'
+  fi
+else
+  # Basic validation without CAWS CLI
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "CAWS CLI not available for full spec validation. Install with: npm install -g @caws/cli"
+    }
+  }'
+fi
+
+exit 0