@paulduvall/claude-dev-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.21

package/hooks/smell_types.py

@@ -0,0 +1,72 @@
+"""Shared types, thresholds, and helpers for code smell detection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# Thresholds
+# ---------------------------------------------------------------------------
+MAX_COMPLEXITY = 10
+MAX_FUNCTION_LINES = 20
+MAX_NESTING_DEPTH = 3
+MAX_PARAMETERS = 4
+MAX_FILE_LINES = 300
+DUPLICATE_MIN_LINES = 4
+DUPLICATE_MIN_OCCURRENCES = 2
+
+FIXES = {
+    "complexity": "Use extract-method, early returns, guard clauses, or lookup tables.",
+    "long_function": "Extract helper functions for distinct logical steps.",
+    "deep_nesting": "Use guard clauses and early returns to flatten control flow.",
+    "too_many_params": "Group related parameters into a dataclass or options object.",
+    "duplicate_block": "Extract repeated code into a shared helper function.",
+    "long_file": "Split into smaller modules with clear single responsibilities.",
+    "secrets": "Move secrets to environment variables or a secrets manager.",
+    "B101": "Remove assert from non-test code; use proper validation instead.",
+    "B102": "Replace exec/eval with safer alternatives.",
+    "B105": "Move hardcoded passwords to environment variables.",
+    "B106": "Move hardcoded passwords to environment variables.",
+    "B110": "Handle exceptions explicitly instead of using bare except-pass.",
+    "B301": "Avoid pickle for untrusted data; use json or safer serialization.",
+    "B602": "Avoid shell=True; pass command as a list to subprocess.",
+    "trojan_bidi": "Remove Unicode bidi override characters that can disguise code.",
+    "trojan_zero_width": "Remove zero-width Unicode characters that hide content.",
+    "ruff_lint": "Fix the ruff lint violation manually.",
+}
+
+
+@dataclass(frozen=True)
+class Smell:
+    """A single code-smell violation."""
+
+    kind: str
+    name: str
+    line: int
+    detail: str
+    fix: str
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+_DETAIL_TEMPLATES = {
+    "complexity": ("complexity={value} (max {max})", MAX_COMPLEXITY),
+    "long_function": ("{value} lines (max {max})", MAX_FUNCTION_LINES),
+    "deep_nesting": ("nesting depth {value} (max {max})", MAX_NESTING_DEPTH),
+    "too_many_params": ("{value} params (max {max})", MAX_PARAMETERS),
+}
+
+
+def make_smell(kind: str, name: str, line: int, value: int) -> Smell:
+    """Create a Smell with a formatted detail string."""
+    tpl, mx = _DETAIL_TEMPLATES[kind]
+    return Smell(kind, name, line, tpl.format(value=value, max=mx), FIXES[kind])
+
+
+def apply_threshold_checks(
+    name: str, line: int, checks: list[tuple[str, int, int]],
+) -> list[Smell]:
+    """Return Smell for each (kind, value, threshold) where value > threshold."""
+    return [make_smell(k, name, line, v) for k, v, t in checks if v > t]

package/hooks/subagent-trigger-simple.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Claude Code Hook: Simple Subagent Trigger  
+# 
+# Purpose: Lightweight trigger for delegating to any subagent
+# Usage: subagent-trigger-simple.sh <subagent-name> [event-type] [context]
+# Approach: Minimal orchestration - gather context and delegate to subagents
+#
+# This is the simplified version of the original 253-line subagent-trigger.sh,
+# focusing on clean delegation rather than complex orchestration.
+
+##################################
+# Load Shared Libraries
+##################################
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/lib"
+
+# Load only essential modules for lightweight operation
+source "$LIB_DIR/config-constants.sh"
+source "$LIB_DIR/file-utils.sh"
+source "$LIB_DIR/context-manager.sh"
+source "$LIB_DIR/error-handler.sh"
+
+##################################
+# Usage Information
+##################################
+show_usage() {
+    cat <<EOF
+Usage: subagent-trigger-simple.sh <subagent-name> [event-type] [additional-context]
+
+Lightweight subagent trigger for event-driven AI assistance.
+
+Arguments:
+  subagent-name     Name of the subagent to invoke (required)
+  event-type        Type of event (default: manual)  
+  additional-context Additional context information (optional)
+
+Examples:
+  subagent-trigger-simple.sh security-auditor pre_write
+  subagent-trigger-simple.sh style-enforcer pre_commit "Check Python files"
+  subagent-trigger-simple.sh debug-specialist on_error "ImportError in main.py"
+
+Available Events: ${SUPPORTED_EVENTS[*]}
+EOF
+}
+
+##################################
+# Simple Context Gathering
+##################################
+gather_simple_context() {
+    local subagent_name="$1"
+    local event_type="$2" 
+    local additional_context="$3"
+    
+    # Create lightweight context - much simpler than the original
+    local safe_name safe_event safe_ctx safe_user safe_wd safe_branch
+    safe_name=$(json_escape "$subagent_name")
+    safe_event=$(json_escape "$event_type")
+    safe_ctx=$(json_escape "$additional_context")
+    safe_user=$(json_escape "$USER")
+    safe_wd=$(json_escape "$(pwd)")
+    safe_branch=$(json_escape "$(git branch --show-current 2>/dev/null || echo 'not-in-git')")
+
+    local context_data
+    context_data=$(cat <<EOF
+{
+  "trigger": "simple_subagent_trigger",
+  "subagent": "$safe_name",
+  "event": "$safe_event",
+  "additional_context": "$safe_ctx",
+  "environment": {
+    "tool": "${CLAUDE_TOOL:-unknown}",
+    "file": "${CLAUDE_FILE:-none}",
+    "user": "$safe_user",
+    "working_directory": "$safe_wd",
+    "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+    "session_id": "${CLAUDE_SESSION_ID:-$$}"
+  },
+  "project": {
+    "git_branch": "$safe_branch"
+  }
+}
+EOF
+    )
+    
+    echo "$context_data"
+}
+
+##################################
+# Subagent Validation
+##################################
+validate_subagent_exists() {
+    local subagent_name="$1"
+    
+    # Simple existence check - leverage the existing validation if needed
+    local common_subagents=("security-auditor" "style-enforcer" "debug-specialist" "test-writer")
+    
+    for known_subagent in "${common_subagents[@]}"; do
+        if [[ "$subagent_name" == "$known_subagent" ]]; then
+            return 0
+        fi
+    done
+    
+    # If not a known subagent, still allow but warn
+    log_warning "Subagent '$subagent_name' not in known list, proceeding anyway"
+    return 0
+}
+
+##################################
+# Simple Delegation
+##################################
+delegate_to_subagent() {
+    local subagent_name="$1"
+    local event_type="$2"
+    local context="$3"
+    
+    log_info "Delegating to subagent: $subagent_name for event: $event_type"
+    
+    echo "🤖 SUBAGENT TRIGGER: Invoking $subagent_name"
+    echo ""
+    echo "Event: $event_type" 
+    echo "Triggered by: ${CLAUDE_TOOL:-manual}"
+    echo "Target: ${CLAUDE_FILE:-general}"
+    echo "Time: $(date)"
+    echo ""
+    echo "Context for $subagent_name:"
+    echo "$context" | jq . 2>/dev/null || echo "$context"
+    echo ""
+    echo "🎯 REQUEST:"
+    echo "Please handle this $event_type event with your specialized expertise."
+    echo "Analyze the context above and provide appropriate assistance."
+}
+
+##################################
+# Input Validation
+##################################
+validate_arguments() {
+    local subagent_name="$1"
+    local event_type="$2"
+    
+    # Basic argument validation
+    if [[ -z "$subagent_name" ]]; then
+        echo "ERROR: Subagent name is required" >&2
+        show_usage >&2
+        return 1
+    fi
+    
+    # Validate event type if provided
+    if [[ -n "$event_type" ]] && [[ "$event_type" != "manual" ]]; then
+        if ! is_supported_event "$event_type"; then
+            log_warning "Event type '$event_type' not in supported list"
+            log_info "Supported events: ${SUPPORTED_EVENTS[*]}"
+        fi
+    fi
+    
+    return 0
+}
+
+##################################
+# Main Logic (Simplified)
+##################################
+main() {
+    local subagent_name="${1:-}"
+    local event_type="${2:-manual}"
+    local additional_context="${3:-}"
+    
+    # Handle help request
+    if [[ "$subagent_name" == "--help" ]] || [[ "$subagent_name" == "-h" ]] || [[ -z "$subagent_name" ]]; then
+        show_usage
+        exit 0
+    fi
+    
+    # Initialize minimal error handling  
+    initialize_error_handling || {
+        echo "ERROR: Failed to initialize error handling" >&2
+        exit 1
+    }
+    
+    # Validate input arguments
+    if ! validate_arguments "$subagent_name" "$event_type"; then
+        exit 1
+    fi
+    
+    # Validate subagent exists (lenient check)
+    validate_subagent_exists "$subagent_name"
+    
+    # Gather context (much simpler than original)
+    local context
+    context=$(gather_simple_context "$subagent_name" "$event_type" "$additional_context")
+    
+    # Delegate to subagent (no complex execution engine needed)
+    delegate_to_subagent "$subagent_name" "$event_type" "$context"
+    
+    log_info "Simple trigger completed for: $subagent_name"
+    exit 0
+}
+
+##################################
+# Execute (Clean and Simple)
+##################################
+main "$@"

package/hooks/subagent-trigger.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Claude Code Hook: Subagent Event Trigger
+# 
+# Purpose: Bridge between Claude Code hooks and subagents, enabling event-driven subagent execution
+# Usage: subagent-trigger.sh [OPTIONS] <subagent-name> [event-type] [additional-context]
+#        subagent-trigger.sh [OPTIONS] --event <event-type>
+# Trigger: Can be used in PreToolUse, PostToolUse, or custom hook configurations
+#
+# This hook enables automatic invocation of specialized subagents based on
+# specific events, ensuring the right expertise is applied at the right time.
+
+##################################
+# Module Loading
+##################################
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/lib"
+
+# Source all required modules in dependency order
+source "$LIB_DIR/config-constants.sh"
+source "$LIB_DIR/file-utils.sh" 
+source "$LIB_DIR/error-handler.sh"
+source "$LIB_DIR/argument-parser.sh"
+source "$LIB_DIR/subagent-discovery.sh"
+source "$LIB_DIR/subagent-validator.sh"
+source "$LIB_DIR/context-manager.sh"
+source "$LIB_DIR/execution-engine.sh"
+
+##################################
+# Initialization
+##################################
+initialize_all_modules() {
+    log_debug "Initializing all modules"
+    
+    initialize_error_handling || {
+        echo "FATAL: Error handling initialization failed" >&2
+        exit $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_argument_parser || {
+        log_error "Argument parser initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_subagent_discovery || {
+        log_error "Subagent discovery initialization failed"  
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_subagent_validator || {
+        log_error "Subagent validator initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_context_manager || {
+        log_error "Context manager initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_execution_engine || {
+        log_error "Execution engine initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    log_debug "All modules initialized successfully"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Core Workflow Functions
+##################################
+execute_single_subagent() {
+    local subagent_name="$1"
+    local event_type="$2"
+    local additional_context="$3"
+    
+    log_info "Executing single subagent: $subagent_name for event: $event_type"
+    
+    # Find the subagent file
+    local subagent_file
+    if ! subagent_file=$(find_subagent "$subagent_name"); then
+        handle_missing_subagent "$subagent_name"
+        return $EXIT_SUBAGENT_NOT_FOUND
+    fi
+    
+    log_debug "Found subagent file: $subagent_file"
+    
+    # Validate the subagent
+    if ! validate_subagent_file "$subagent_file" "strict"; then
+        handle_validation_failure "$subagent_name" "file validation failed"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Create context file
+    if ! create_context_file "$subagent_name" "$event_type"; then
+        log_error "Failed to create context file"
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    local context_file
+    context_file=$(get_context_file)
+    
+    # Gather context information
+    if ! gather_complete_context "$event_type" "$subagent_name" "$additional_context" "false"; then
+        log_error "Failed to gather context"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Write context to file
+    if ! write_context_to_file "$context_file"; then
+        log_error "Failed to write context to file"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Determine execution mode and timeout
+    local execution_mode timeout
+    execution_mode=$(determine_execution_mode "$event_type" "$(get_parsed_execution_mode)")
+    timeout=$(get_timeout_for_execution "$event_type" "$subagent_name")
+    
+    # Check for dry run mode
+    if is_dry_run; then
+        execution_mode="dry-run"
+    fi
+    
+    # Execute the subagent
+    local execution_result
+    if ! execute_subagent "$subagent_file" "$context_file" "$execution_mode" "$timeout"; then
+        log_error "Subagent execution failed: $subagent_name"
+        cleanup_context_file
+        return $EXIT_EXECUTION_FAILED
+    fi
+    
+    # Clean up context file
+    cleanup_context_file
+    
+    log_info "Single subagent execution completed successfully: $subagent_name"
+    return $EXIT_SUCCESS
+}
+
+execute_event_based_subagents() {
+    local event_type="$1"
+    local additional_context="$2"
+    
+    log_info "Executing event-based subagents for event: $event_type"
+    
+    # Create shared context file for all subagents
+    if ! create_context_file "event-$event_type" "$event_type"; then
+        log_error "Failed to create context file for event execution"
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    local context_file
+    context_file=$(get_context_file)
+    
+    # Gather context information
+    if ! gather_complete_context "$event_type" "event-based" "$additional_context" "false"; then
+        log_error "Failed to gather context for event execution"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Write context to file
+    if ! write_context_to_file "$context_file"; then
+        log_error "Failed to write context to file for event execution"
+        cleanup_context_file  
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Determine execution mode
+    local execution_mode
+    execution_mode=$(determine_execution_mode "$event_type" "$(get_parsed_execution_mode)")
+    
+    # Execute all subagents for this event
+    local execution_result
+    if ! execute_multiple_subagents "$event_type" "$context_file" "$execution_mode"; then
+        log_error "Event-based subagent execution failed for event: $event_type"
+        cleanup_context_file
+        return $EXIT_EXECUTION_FAILED
+    fi
+    
+    # Clean up context file
+    cleanup_context_file
+    
+    log_info "Event-based subagent execution completed successfully: $event_type"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Main Hook Logic
+##################################
+main() {
+    # Initialize all modules
+    if ! initialize_all_modules; then
+        echo "FATAL: Module initialization failed" >&2
+        exit $EXIT_GENERAL_ERROR
+    fi
+    
+    # Parse arguments
+    if ! parse_arguments "$@"; then
+        # Error messages already logged by parser
+        safe_exit $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Handle help request
+    if is_help_requested; then
+        show_usage
+        safe_exit $EXIT_SUCCESS
+    fi
+    
+    # Log parsed arguments in debug mode
+    if is_debug_mode; then
+        log_parsed_arguments
+    fi
+    
+    # Get execution parameters
+    local subagent_name event_type additional_context execution_mode
+    subagent_name=$(get_parsed_subagent_name)
+    event_type=$(get_parsed_event_type)
+    additional_context=$(get_parsed_additional_context)
+    execution_mode=$(get_parsed_execution_mode)
+    
+    log_info "Starting subagent hook execution"
+    log_info "Mode: $execution_mode, Event: $event_type"
+    
+    # Execute based on mode
+    local exit_code
+    case "$execution_mode" in
+        "event-based")
+            execute_event_based_subagents "$event_type" "$additional_context"
+            exit_code=$?
+            ;;
+        *)
+            execute_single_subagent "$subagent_name" "$event_type" "$additional_context"
+            exit_code=$?
+            ;;
+    esac
+    
+    if [[ $exit_code -eq $EXIT_SUCCESS ]]; then
+        log_info "Subagent hook completed successfully"
+    else
+        log_error "Subagent hook failed with exit code: $exit_code"
+    fi
+    
+    safe_exit $exit_code
+}
+
+##################################
+# Execute Main Function
+##################################
+main "$@"

package/hooks/suppression.py

@@ -0,0 +1,82 @@
+"""Inline suppression parser for code smell and security hooks.
+
+Supports per-line suppression comments:
+  # smell: ignore[complexity,long_function]
+  # security: ignore[secrets,B101]
+
+Applies to the same line or the line immediately following the comment.
+No wildcards supported -- explicit check names required.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from smell_types import Smell
+
+_SUPPRESS_RE = re.compile(
+    r"#\s*(?P<ns>smell|security):\s*ignore\[(?P<names>[^\]]+)\]"
+)
+_MAX_SUPPRESSIONS_PER_FILE = 5
+
+
+def _parse_suppression(line: str) -> dict[str, set[str]]:
+    """Parse suppression directives from a single line.
+
+    Returns:
+        Dict mapping namespace to set of suppressed check names.
+    """
+    result: dict[str, set[str]] = {}
+    for match in _SUPPRESS_RE.finditer(line):
+        ns = match.group("ns")
+        names = {n.strip() for n in match.group("names").split(",")}
+        result.setdefault(ns, set()).update(names)
+    return result
+
+
+def _build_suppression_map(lines: list[str]) -> dict[int, dict[str, set[str]]]:
+    """Build a map of line numbers to their active suppressions.
+
+    A suppression on line N applies to line N and line N+1.
+    """
+    suppression_map: dict[int, dict[str, set[str]]] = {}
+    for lineno, line in enumerate(lines, start=1):
+        parsed = _parse_suppression(line)
+        if not parsed:
+            continue
+        for target_line in (lineno, lineno + 1):
+            existing = suppression_map.setdefault(target_line, {})
+            for ns, names in parsed.items():
+                existing.setdefault(ns, set()).update(names)
+    return suppression_map
+
+
+def _is_suppressed(smell: Smell, namespace: str, active: dict[str, set[str]]) -> bool:
+    """Check if a smell is suppressed by the active suppressions."""
+    names = active.get(namespace, set())
+    return smell.kind in names or smell.name in names
+
+
+def _warn_excessive(count: int, total_lines: int) -> None:
+    """Warn to stderr if too many suppressions are used."""
+    if count > _MAX_SUPPRESSIONS_PER_FILE:
+        print(
+            f"Warning: {count} suppression comments in file "
+            f"({_MAX_SUPPRESSIONS_PER_FILE} max recommended)",
+            file=sys.stderr,
+        )
+
+
+def filter_suppressed(
+    smells: list[Smell], lines: list[str], namespace: str,
+) -> list[Smell]:
+    """Remove smells covered by inline suppression comments."""
+    suppression_map = _build_suppression_map(lines)
+    _warn_excessive(len(suppression_map), len(lines))
+    result: list[Smell] = []
+    for smell in smells:
+        active = suppression_map.get(smell.line, {})
+        if not _is_suppressed(smell, namespace, active):
+            result.append(smell)
+    return result

package/hooks/tab-color.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# tab-color.sh - Sets iTerm2 tab color for Claude Code hook events
+# Usage: tab-color.sh [gray|blue|green|red|reset]
+#
+# gray  = session idle (no prompt running)
+# blue  = prompt in progress (working)
+# green = prompt complete (done) -- decays to gray after 3 minutes
+# red   = error
+# reset = restore default tab color
+#
+# Tab TITLE (directory name) is set by claude-wrapper.sh at launch.
+# This script only manages COLOR -- Claude Code overrides mid-session title changes.
+
+DECAY_SECONDS=180
+
+# Consume stdin (hook protocol sends JSON on stdin)
+cat > /dev/null
+
+# Per-session state file to prevent decay timer from overwriting blue
+get_state_file() {
+    local tty_id
+    tty_id=$(tty < /dev/tty 2>/dev/null | tr '/' '_' || echo "unknown")
+    echo "/tmp/claude-tab-state${tty_id}"
+}
+
+set_tab_color() {
+    printf "\033]6;1;bg;red;brightness;%s\a" "$1" > /dev/tty 2>/dev/null
+    printf "\033]6;1;bg;green;brightness;%s\a" "$2" > /dev/tty 2>/dev/null
+    printf "\033]6;1;bg;blue;brightness;%s\a" "$3" > /dev/tty 2>/dev/null
+}
+
+STATE_FILE=$(get_state_file)
+
+case "${1:-blue}" in
+    gray)
+        echo "gray" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 130 130 130
+        ;;
+    blue)
+        echo "blue" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 20 80 255
+        ;;
+    green)
+        echo "green" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 0 255 0
+        # Ring terminal bell -- triggers iTerm2 notification for background tabs
+        printf "\a" > /dev/tty 2>/dev/null
+        # Auto-decay to gray after 3 minutes (only if still green)
+        # Fully detach: redirect all fds so Claude Code doesn't wait for child
+        nohup bash -c "
+            sleep $DECAY_SECONDS
+            state_file='$STATE_FILE'
+            if [[ -f \"\$state_file\" && \"\$(cat \"\$state_file\" 2>/dev/null)\" == 'green' ]]; then
+                echo 'gray' > \"\$state_file\"
+                printf '\033]6;1;bg;red;brightness;130\a' > /dev/tty 2>/dev/null
+                printf '\033]6;1;bg;green;brightness;130\a' > /dev/tty 2>/dev/null
+                printf '\033]6;1;bg;blue;brightness;130\a' > /dev/tty 2>/dev/null
+            fi
+        " </dev/null >/dev/null 2>&1 &
+        ;;
+    red)
+        echo "red" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 220 0 0
+        printf "\a" > /dev/tty 2>/dev/null
+        ;;
+    reset)
+        rm -f "$STATE_FILE" 2>/dev/null
+        printf "\033]6;1;bg;*;default\a" > /dev/tty 2>/dev/null
+        ;;
+esac