safeword 0.2.2 → 0.2.4

package/framework/scripts/setup-quality.sh

@@ -0,0 +1,477 @@
+#!/bin/bash
+################################################################################
+# Claude Code Quality Review Hook Setup Script
+#
+# This script configures quality review hooks to automatically trigger
+# when Claude Code makes or proposes changes to your project files.
+#
+# Usage:
+#   bash setup-quality.sh
+#
+# What it does:
+# - Creates auto-quality-review.sh (Stop hook - detects changes)
+# - Creates run-quality-review.sh (quality review prompt)
+# - Creates /quality-review slash command
+# - Updates .claude/settings.json with Stop hook
+#
+# All files are created project-local (no global dependencies).
+################################################################################
+
+set -e  # Exit on error
+
+VERSION="v1.0.0"
+
+# Version header for generated files
+# Note: This script is project-local; the header records the generator name.
+VERSION_HEADER="# Generated by setup-quality.sh $VERSION
+# To upgrade: Re-run setup script in this project
+#"
+
+echo "================================="
+echo "Claude Code Quality Review Setup"
+echo "Version: $VERSION"
+echo "================================="
+echo ""
+
+# Check if we're in a directory where we can write
+if [ ! -w "." ]; then
+  echo "ERROR: Cannot write to current directory. Please cd to your project root."
+  exit 1
+fi
+
+PROJECT_ROOT="$(pwd)"
+echo "Setting up quality review in: $PROJECT_ROOT"
+echo ""
+
+# ============================================================================
+# Step 1: Check dependencies
+# ============================================================================
+echo "[1/4] Checking dependencies..."
+
+# Check if jq is available (REQUIRED for settings.json merging)
+if ! command -v jq &> /dev/null; then
+  echo "ERROR: jq is required for settings.json merging."
+  echo "Install it:"
+  echo "  • macOS: brew install jq"
+  echo "  • Ubuntu/Debian: sudo apt-get install jq"
+  echo "  • Other: https://jqlang.github.io/jq/download/"
+  exit 1
+fi
+
+echo "  ✓ Dependencies checked"
+echo ""
+
+# ============================================================================
+# Step 2: Create .claude directory structure
+# ============================================================================
+echo "[2/4] Creating directory structure..."
+
+mkdir -p .claude/hooks
+mkdir -p .claude/commands
+
+echo "  ✓ Created .claude/hooks and .claude/commands"
+echo ""
+
+# ============================================================================
+# Step 3: Generate hook files
+# ============================================================================
+echo "[3/4] Generating quality review hooks..."
+
+# Create auto-quality-review.sh (Stop hook)
+{
+  echo '#!/bin/bash'
+  echo "$VERSION_HEADER"
+  cat << 'EOF'
+# Auto Quality Review Stop Hook
+# Triggers quality review when changes are proposed or made
+# Only runs for projects with SAFEWORD.md or CLAUDE.md (searches upward)
+# Looks for {"proposedChanges": ..., "madeChanges": ...} JSON blob
+
+# Debug logging (persistent across reboots, user-specific)
+DEBUG_DIR="$HOME/.cache/claude-hooks"
+mkdir -p "$DEBUG_DIR" 2>/dev/null || DEBUG_DIR="/tmp"
+DEBUG_LOG="$DEBUG_DIR/auto-quality-review-debug.log"
+echo "=== Hook triggered at $(date) ===" >> "$DEBUG_LOG"
+echo "PWD: $PWD" >> "$DEBUG_LOG"
+
+# Read hook input from stdin
+input=$(cat)
+echo "Input: $input" >> "$DEBUG_LOG"
+
+# Check for project-level SAFEWORD.md or CLAUDE.md
+# Search upward from current directory (supports monorepos)
+current_dir="$PWD"
+echo "Searching for SAFEWORD.md or CLAUDE.md..." >> "$DEBUG_LOG"
+while true; do
+  if [ -f "$current_dir/SAFEWORD.md" ] || [ -f "$current_dir/CLAUDE.md" ]; then
+    echo "Found context file in: $current_dir" >> "$DEBUG_LOG"
+    break  # Found context file
+  fi
+
+  # Reached root without finding context file
+  if [ "$current_dir" = "/" ]; then
+    echo "No SAFEWORD.md or CLAUDE.md found, exiting" >> "$DEBUG_LOG"
+    exit 0
+  fi
+
+  current_dir=$(dirname "$current_dir")
+done
+
+# Read project config (defaults: enabled=true, ask_questions=true)
+config_file="$current_dir/.auto-quality-review.config"
+enabled=true
+ask_questions=true
+
+if [ -f "$config_file" ]; then
+  while IFS='=' read -r key value; do
+    # Skip empty lines and comments
+    [[ -z "$key" || "$key" =~ ^# ]] && continue
+    # Trim whitespace
+    key=$(echo "$key" | xargs)
+    value=$(echo "$value" | xargs)
+
+    case "$key" in
+      enabled)
+        enabled="$value"
+        ;;
+      ask_questions)
+        ask_questions="$value"
+        ;;
+    esac
+  done < "$config_file"
+fi
+
+# Exit if disabled for this project
+echo "Config: enabled=$enabled, ask_questions=$ask_questions" >> "$DEBUG_LOG"
+if [ "$enabled" != "true" ]; then
+  echo "Hook disabled for this project, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Get transcript path
+if ! transcript_path=$(echo "$input" | jq -r '.transcript_path // empty' 2>/dev/null); then
+  echo "ERROR: jq failed to extract transcript_path from hook input." >&2
+  echo "ERROR: jq failed to parse input" >> "$DEBUG_LOG"
+  exit 2
+fi
+
+echo "Transcript path: $transcript_path" >> "$DEBUG_LOG"
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  echo "No transcript or file doesn't exist, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Extract last assistant message from transcript
+# Transcript is JSONL format - each line is a message
+last_assistant_msg=$(grep '"role":"assistant"' "$transcript_path" | tail -1)
+
+echo "Last assistant message length: ${#last_assistant_msg}" >> "$DEBUG_LOG"
+if [ -z "$last_assistant_msg" ]; then
+  # Normal case: No assistant messages yet
+  echo "No assistant messages found, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Extract the text content from the message
+# Looking for the final JSON blob: {"proposedChanges": ..., "madeChanges": ...}
+if ! msg_text=$(echo "$last_assistant_msg" | jq -r '.message.content[]? | select(.type == "text") | .text' 2>/dev/null); then
+  echo "ERROR: jq failed to parse assistant message structure. Transcript format may have changed." >&2
+  echo "DEBUG: Message structure: $(echo "$last_assistant_msg" | jq -r '.message.content[].type' 2>/dev/null)" >> "$DEBUG_LOG"
+  exit 2
+fi
+
+if [ -z "$msg_text" ]; then
+  # Normal case: Message has no text content
+  exit 0
+fi
+
+# Extract the JSON blob from the end of the message
+# Pattern: {"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
+json_blob=$(echo "$msg_text" | grep -oE '\{"proposedChanges":\s*(true|false)\s*,\s*"madeChanges":\s*(true|false)\s*,\s*"askedQuestion":\s*(true|false)\s*\}' | tail -1)
+
+echo "JSON blob: $json_blob" >> "$DEBUG_LOG"
+if [ -z "$json_blob" ]; then
+  # Check if this looks like a substantive response (>100 chars)
+  # If so, remind agent to include JSON payload
+  msg_length=${#msg_text}
+  echo "No JSON blob found, message length: $msg_length" >> "$DEBUG_LOG"
+
+  if [ "$msg_length" -gt 100 ]; then
+    echo "Substantive response without JSON payload, sending reminder" >> "$DEBUG_LOG"
+    echo "Missing required JSON response format. Please include: {\"proposedChanges\": bool, \"madeChanges\": bool, \"askedQuestion\": bool}" >&2
+    exit 2
+  fi
+
+  # Short message without JSON is fine (acknowledgments, etc)
+  echo "Short message without JSON, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Parse the boolean values
+if ! proposed_changes=$(echo "$json_blob" | jq -r '.proposedChanges // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse proposedChanges field from JSON blob." >&2
+  exit 2
+fi
+
+if ! made_changes=$(echo "$json_blob" | jq -r '.madeChanges // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse madeChanges field from JSON blob." >&2
+  exit 2
+fi
+
+if ! asked_question=$(echo "$json_blob" | jq -r '.askedQuestion // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse askedQuestion field from JSON blob." >&2
+  exit 2
+fi
+
+# If asked question, skip quality review (waiting for user response)
+echo "proposedChanges=$proposed_changes, madeChanges=$made_changes, askedQuestion=$asked_question" >> "$DEBUG_LOG"
+if [ "$asked_question" = "true" ]; then
+  echo "Agent asked question, skipping quality review" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# If either proposed or made changes, trigger quality review
+if [ "$proposed_changes" = "true" ] || [ "$made_changes" = "true" ]; then
+  # Block and request quality review
+  echo "TRIGGERING QUALITY REVIEW" >> "$DEBUG_LOG"
+
+  # Find the shared quality review script (same directory as this hook)
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  # Call shared quality review script
+  if [ "$ask_questions" = "true" ]; then
+    exec "$SCRIPT_DIR/run-quality-review.sh"
+  else
+    exec "$SCRIPT_DIR/run-quality-review.sh" --no-questions
+  fi
+fi
+
+# No changes proposed or made - allow continuation
+exit 0
+EOF
+} > .claude/hooks/auto-quality-review.sh
+
+chmod +x .claude/hooks/auto-quality-review.sh
+
+# Create run-quality-review.sh (quality review prompt)
+{
+  echo '#!/bin/bash'
+  echo "$VERSION_HEADER"
+  cat << 'EOF'
+# Shared Quality Review Script
+#
+# Prompts for a quality review with configurable questions.
+# Used by both Stop hooks and manual /quality-review command.
+#
+# Usage:
+#   run-quality-review.sh               # With questions enabled
+#   run-quality-review.sh --no-questions  # Without "ask me" prompt
+#
+# Environment variables:
+#   CLAUDE_PROJECT_DIR - Project root (for finding config and prompts)
+
+# Default: ask questions enabled
+ask_questions=true
+
+# Parse command line arguments
+for arg in "$@"; do
+  case "$arg" in
+    --no-questions)
+      ask_questions=false
+      ;;
+  esac
+done
+
+# Try to read project config if CLAUDE_PROJECT_DIR is set
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then
+  config_file="$CLAUDE_PROJECT_DIR/.auto-quality-review.config"
+
+  if [ -f "$config_file" ]; then
+    while IFS='=' read -r key value; do
+      # Skip empty lines and comments
+      [[ -z "$key" || "$key" =~ ^# ]] && continue
+      # Trim whitespace
+      key=$(echo "$key" | xargs)
+      value=$(echo "$value" | xargs)
+
+      case "$key" in
+        ask_questions)
+          ask_questions="$value"
+          ;;
+      esac
+    done < "$config_file"
+  fi
+fi
+
+# Try to read prompt from .safeword/prompts/quality-review.md
+PROMPT_FILE=""
+if [ -n "$CLAUDE_PROJECT_DIR" ] && [ -f "$CLAUDE_PROJECT_DIR/.safeword/prompts/quality-review.md" ]; then
+  PROMPT_FILE="$CLAUDE_PROJECT_DIR/.safeword/prompts/quality-review.md"
+fi
+
+if [ -n "$PROMPT_FILE" ]; then
+  # Read prompt from file, skip the header line
+  tail -n +3 "$PROMPT_FILE" >&2
+else
+  # Fallback to hardcoded prompt
+  echo "Double check and critique your work just in case." >&2
+  echo "" >&2
+  echo "- Is it correct?" >&2
+  echo "- Is it elegant?" >&2
+  echo "- Does it adhere to the latest documentation and best practices for the relevant stack items, UX principles, domain requirements, and testing practices?" >&2
+
+  if [ "$ask_questions" = "true" ]; then
+    echo "- Ask me any non-obvious questions you can't research yourself in the codebase or online." >&2
+  fi
+
+  echo "- Think hard." >&2
+  echo "- Avoid bloat." >&2
+fi
+
+# Exit with code 2 to block (Stop hook behavior)
+exit 2
+EOF
+} > .claude/hooks/run-quality-review.sh
+
+chmod +x .claude/hooks/run-quality-review.sh
+
+echo "  ✓ Created auto-quality-review.sh (Stop hook)"
+echo "  ✓ Created run-quality-review.sh (quality review prompt)"
+
+# Create quality-review slash command
+cat > .claude/commands/quality-review.md << 'EOF'
+Trigger a quality review to double-check your work.
+
+Execute:
+```bash
+bash .claude/hooks/run-quality-review.sh
+```
+
+This will prompt you to:
+- Verify correctness
+- Check elegance
+- Validate against latest docs and best practices
+- Consider asking clarifying questions
+- Think deeply and avoid bloat
+EOF
+
+echo "  ✓ Created quality-review slash command"
+
+# Create version-check SessionStart hook
+{
+  echo '#!/bin/bash'
+  echo "$VERSION_HEADER"
+  cat << 'EOF'
+# SAFE WORD Claude Config - SessionStart Hook
+# Injects version and status into Claude's context (silent - not displayed to user)
+
+echo "SAFE WORD Claude Config v1.0.0 installed - auto-linting and quality review active"
+
+exit 0
+EOF
+} > .claude/hooks/version-check.sh
+
+chmod +x .claude/hooks/version-check.sh
+
+echo "  ✓ Created version-check SessionStart hook"
+
+# Create inject-timestamp UserPromptSubmit hook
+{
+  echo '#!/bin/bash'
+  echo "$VERSION_HEADER"
+  cat << 'EOF'
+# Inject Timestamp - UserPromptSubmit Hook
+# Outputs current Unix timestamp for Claude's context awareness
+# Helps with accurate ticket timestamps and time-based reasoning
+
+echo "Current time: $(date +%s) ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
+EOF
+} > .claude/hooks/inject-timestamp.sh
+
+chmod +x .claude/hooks/inject-timestamp.sh
+
+echo "  ✓ Created inject-timestamp UserPromptSubmit hook"
+echo ""
+
+# ============================================================================
+# Step 4: Update settings.json
+# ============================================================================
+echo "[4/4] Updating .claude/settings.json..."
+
+# Create base settings.json if doesn't exist
+if [ ! -f .claude/settings.json ]; then
+  echo '{"hooks": {}}' > .claude/settings.json
+  echo "  ✓ Created .claude/settings.json"
+fi
+
+# Check if auto-quality-review hook already exists in Stop
+if jq -e '.hooks.Stop[]?.hooks[]? | select(.command == "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-quality-review.sh")' .claude/settings.json > /dev/null 2>&1; then
+  echo "  ✓ Stop hook already exists (skipped)"
+else
+  # Append to Stop array (or create if doesn't exist)
+  jq '.hooks.Stop = (.hooks.Stop // []) + [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-quality-review.sh"}]}]' \
+    .claude/settings.json > .claude/settings.json.tmp
+  mv .claude/settings.json.tmp .claude/settings.json
+  echo "  ✓ Added Stop hook to settings.json"
+fi
+
+# Check if version-check hook already exists in SessionStart
+if jq -e '.hooks.SessionStart[]?.hooks[]? | select(.command == "$CLAUDE_PROJECT_DIR/.claude/hooks/version-check.sh")' .claude/settings.json > /dev/null 2>&1; then
+  echo "  ✓ SessionStart hook already exists (skipped)"
+else
+  # Append to SessionStart array (or create if doesn't exist)
+  jq '.hooks.SessionStart = (.hooks.SessionStart // []) + [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/version-check.sh"}]}]' \
+    .claude/settings.json > .claude/settings.json.tmp
+  mv .claude/settings.json.tmp .claude/settings.json
+  echo "  ✓ Added SessionStart hook to settings.json"
+fi
+
+# Check if inject-timestamp hook already exists in UserPromptSubmit
+if jq -e '.hooks.UserPromptSubmit[]?.hooks[]? | select(.command == "$CLAUDE_PROJECT_DIR/.claude/hooks/inject-timestamp.sh")' .claude/settings.json > /dev/null 2>&1; then
+  echo "  ✓ UserPromptSubmit hook already exists (skipped)"
+else
+  # Append to UserPromptSubmit array (or create if doesn't exist)
+  jq '.hooks.UserPromptSubmit = (.hooks.UserPromptSubmit // []) + [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/inject-timestamp.sh"}]}]' \
+    .claude/settings.json > .claude/settings.json.tmp
+  mv .claude/settings.json.tmp .claude/settings.json
+  echo "  ✓ Added UserPromptSubmit hook to settings.json"
+fi
+echo ""
+
+echo "================================="
+echo "✓ Setup Complete!"
+echo "================================="
+echo ""
+echo "What was configured:"
+echo "  • Quality review hooks installed (triggers on changes)"
+echo "  • Version display on session start"
+echo "  • Timestamp injection on every prompt"
+echo "  • /quality-review command available"
+echo "  • All files are project-local and standalone"
+echo ""
+echo "⚠ IMPORTANT:"
+echo "  • COMMIT .safeword/ and .claude/ to your repo for team consistency"
+echo "  • Claude Code will read @./.safeword/SAFEWORD.md via SAFEWORD.md or CLAUDE.md reference"
+echo "  • No external dependencies - project is fully portable"
+echo ""
+echo "Hook behavior:"
+echo "  • Only runs in projects with SAFEWORD.md or CLAUDE.md"
+echo "  • Triggers when Claude proposes or makes changes"
+echo "  • Skips if Claude asks a question (waits for your answer)"
+echo "  • Can be disabled per-project: create .auto-quality-review.config"
+echo ""
+echo "To customize:"
+echo "  • Edit .claude/hooks/run-quality-review.sh for review prompt"
+echo "  • Edit .claude/hooks/auto-quality-review.sh for trigger logic"
+echo "  • Edit .claude/settings.json for hook configuration"
+echo ""
+echo "Test it:"
+echo "  • Ask Claude to create or modify a file"
+echo "  • Watch for quality review prompt after the change"
+echo ""
+
+
+
+
+
+