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

package/hooks/lib/subagent-validator.sh

@@ -0,0 +1,407 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Subagent Validator Module for Subagent-Hook Integration
+#
+# This module provides comprehensive validation functionality for subagents,
+# including format validation, content validation, and security checks.
+
+# Include guard
+[[ -n "${_SUBAGENT_VALIDATOR_LOADED:-}" ]] && return 0
+_SUBAGENT_VALIDATOR_LOADED=1
+
+# Source required modules
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/config-constants.sh"
+source "$SCRIPT_DIR/file-utils.sh"
+source "$SCRIPT_DIR/error-handler.sh"
+source "$SCRIPT_DIR/field-validators.sh"
+source "$SCRIPT_DIR/validation-reporter.sh"
+
+##################################
+# Basic Validation Functions
+##################################
+
+validate_subagent_file() {
+    local subagent_file="$1"
+    local validation_mode="${2:-strict}"
+    
+    if [[ -z "$subagent_file" ]]; then
+        log_error "Subagent file path is required"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    log_debug "Validating subagent file: $subagent_file (mode: $validation_mode)"
+    
+    # Basic file validation
+    if ! validate_file_existence "$subagent_file"; then
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    if ! validate_file_security "$subagent_file"; then
+        return $EXIT_SECURITY_VIOLATION
+    fi
+    
+    if ! validate_file_format "$subagent_file"; then
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    if ! validate_yaml_frontmatter "$subagent_file"; then
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    if [[ "$validation_mode" == "strict" ]]; then
+        if ! validate_subagent_content "$subagent_file"; then
+            return $EXIT_VALIDATION_FAILED
+        fi
+        
+        if ! validate_subagent_metadata "$subagent_file"; then
+            return $EXIT_VALIDATION_FAILED
+        fi
+    fi
+    
+    log_debug "Subagent file validation passed: $subagent_file"
+    return $EXIT_SUCCESS
+}
+
+validate_file_existence() {
+    local file_path="$1"
+    
+    if [[ ! -f "$file_path" ]]; then
+        handle_missing_subagent "$(basename "$file_path" "$SUBAGENT_FILE_EXTENSION")"
+        return $EXIT_SUBAGENT_NOT_FOUND
+    fi
+    
+    if [[ ! -r "$file_path" ]]; then
+        log_error "Subagent file not readable: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    return $EXIT_SUCCESS
+}
+
+validate_file_security() {
+    local file_path="$1"
+    
+    # Validate file permissions
+    if ! validate_file_permissions "$file_path"; then
+        handle_security_violation "insecure_file_permissions" \
+            "File has insecure permissions" "$file_path"
+        return $EXIT_SECURITY_VIOLATION
+    fi
+    
+    # Validate path safety
+    if ! validate_path_safety "$file_path"; then
+        handle_security_violation "unsafe_file_path" \
+            "File path contains unsafe elements" "$file_path"
+        return $EXIT_SECURITY_VIOLATION
+    fi
+    
+    return $EXIT_SUCCESS
+}
+
+validate_file_format() {
+    local file_path="$1"
+    
+    # Check file extension
+    if ! file_has_extension "$file_path" "$SUBAGENT_FILE_EXTENSION"; then
+        log_error "Invalid file extension: $file_path (expected: $SUBAGENT_FILE_EXTENSION)"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Check file size
+    local file_content
+    if ! file_content=$(read_file_with_size_limit "$file_path"); then
+        log_error "File too large or unreadable: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Check if file appears to be binary
+    if file "$file_path" 2>/dev/null | grep -q "binary"; then
+        log_error "File appears to be binary: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    return $EXIT_SUCCESS
+}
+
+##################################
+# YAML Frontmatter Validation
+##################################
+
+validate_yaml_frontmatter() {
+    local file_path="$1"
+    
+    local content
+    if ! content=$(read_file_safely "$file_path"); then
+        log_error "Failed to read file for frontmatter validation: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Check for YAML frontmatter start
+    if ! echo "$content" | head -1 | grep -q "$YAML_FRONTMATTER_START"; then
+        log_error "Missing YAML frontmatter start marker in: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Find frontmatter end
+    local frontmatter_end_found=false
+    local line_count=0
+    
+    while IFS= read -r line; do
+        ((line_count++))
+        
+        # Skip first line (start marker)
+        if [[ $line_count -eq 1 ]]; then
+            continue
+        fi
+        
+        if [[ "$line" == "---" ]]; then
+            frontmatter_end_found=true
+            break
+        fi
+        
+        # Prevent infinite search
+        if [[ $line_count -gt 100 ]]; then
+            break
+        fi
+    done <<< "$content"
+    
+    if [[ "$frontmatter_end_found" != true ]]; then
+        log_error "Missing YAML frontmatter end marker in: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    log_debug "YAML frontmatter structure valid: $file_path"
+    return $EXIT_SUCCESS
+}
+
+extract_frontmatter_field() {
+    local file_path="$1"
+    local field_name="$2"
+    local required="${3:-false}"
+    
+    if [[ -z "$file_path" ]] || [[ -z "$field_name" ]]; then
+        log_error "File path and field name are required"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    local content
+    if ! content=$(read_file_safely "$file_path"); then
+        log_error "Failed to read file: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    local in_frontmatter=false
+    local field_value=""
+    
+    while IFS= read -r line; do
+        if [[ "$line" == "---" ]]; then
+            if [[ "$in_frontmatter" == true ]]; then
+                break  # End of frontmatter
+            else
+                in_frontmatter=true
+                continue
+            fi
+        fi
+        
+        if [[ "$in_frontmatter" == true ]]; then
+            if [[ "$line" =~ ^${field_name}:[[:space:]]*(.*)$ ]]; then
+                field_value="${BASH_REMATCH[1]}"
+                # Remove quotes if present
+                field_value="${field_value#\"}"
+                field_value="${field_value%\"}"
+                break
+            fi
+        fi
+    done <<< "$content"
+    
+    if [[ -z "$field_value" ]] && [[ "$required" == true ]]; then
+        log_error "Required field missing: $field_name in $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    echo "$field_value"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Content Validation Functions
+##################################
+
+validate_subagent_metadata() {
+    local file_path="$1"
+    
+    log_debug "Validating subagent metadata: $file_path"
+    
+    # Validate required fields
+    local required_fields=("name" "description")
+    local field
+    
+    for field in "${required_fields[@]}"; do
+        local field_value
+        if ! field_value=$(extract_frontmatter_field "$file_path" "$field" true); then
+            return $EXIT_VALIDATION_FAILED
+        fi
+        
+        case "$field" in
+            "name")
+                if ! validate_subagent_name_field "$field_value"; then
+                    log_error "Invalid name field in: $file_path"
+                    return $EXIT_VALIDATION_FAILED
+                fi
+                ;;
+            "description")
+                if ! validate_description_field "$field_value"; then
+                    log_error "Invalid description field in: $file_path"
+                    return $EXIT_VALIDATION_FAILED
+                fi
+                ;;
+        esac
+    done
+    
+    # Validate optional fields if present
+    local optional_fields=("version" "tools" "tags")
+    for field in "${optional_fields[@]}"; do
+        local field_value
+        if field_value=$(extract_frontmatter_field "$file_path" "$field" false); then
+            if [[ -n "$field_value" ]]; then
+                case "$field" in
+                    "version")
+                        validate_version_field "$field_value" || {
+                            log_warning "Invalid version field in: $file_path"
+                        }
+                        ;;
+                    "tools")
+                        validate_tools_field "$field_value" || {
+                            log_warning "Invalid tools field in: $file_path"
+                        }
+                        ;;
+                    "tags")
+                        validate_tags_field "$field_value" || {
+                            log_warning "Invalid tags field in: $file_path"
+                        }
+                        ;;
+                esac
+            fi
+        fi
+    done
+    
+    log_debug "Subagent metadata validation passed: $file_path"
+    return $EXIT_SUCCESS
+}
+
+validate_subagent_content() {
+    local file_path="$1"
+    
+    log_debug "Validating subagent content: $file_path"
+    
+    local content
+    if ! content=$(read_file_safely "$file_path"); then
+        log_error "Failed to read file for content validation: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Check for minimum content after frontmatter
+    local in_frontmatter=false
+    local frontmatter_ended=false
+    local content_lines=0
+    
+    while IFS= read -r line; do
+        if [[ "$line" == "---" ]]; then
+            if [[ "$in_frontmatter" == true ]]; then
+                frontmatter_ended=true
+            else
+                in_frontmatter=true
+            fi
+            continue
+        fi
+        
+        if [[ "$frontmatter_ended" == true ]]; then
+            # Count non-empty lines
+            if [[ -n "${line// }" ]]; then
+                ((content_lines++))
+            fi
+        fi
+    done <<< "$content"
+    
+    if [[ $content_lines -lt 3 ]]; then
+        log_error "Insufficient content after frontmatter in: $file_path"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    if ! validate_content_security "$content" "$file_path"; then
+        return $EXIT_SECURITY_VIOLATION
+    fi
+
+    log_debug "Subagent content validation passed: $file_path"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Field Validation Functions
+##################################
+# See: field-validators.sh
+
+##################################
+# Security Validation Functions
+##################################
+
+validate_content_security() {
+    local content="$1"
+    local file_path="$2"
+    
+    log_debug "Performing security validation on content"
+    
+    # Check for suspicious patterns (excluding legitimate markdown)
+    local suspicious_patterns=(
+        'rm\s+-rf\s+/'
+        'curl\s+.*\|\s*sh'
+        'wget\s+.*\|\s*sh'  
+        'eval\s*\$\('
+        '`[^`]*\$\([^`]*`'
+        'exec\s+["\047].*[;&]'
+    )
+    
+    local pattern
+    for pattern in "${suspicious_patterns[@]}"; do
+        if echo "$content" | grep -qE "$pattern"; then
+            handle_security_violation "suspicious_content" \
+                "Suspicious pattern detected: $pattern" "$file_path"
+            return $EXIT_SECURITY_VIOLATION
+        fi
+    done
+    
+    # Check for potential credential exposure
+    local credential_patterns=(
+        'password\s*[:=]\s*["\047]?[^"\047[:space:]]+["\047]?'
+        'token\s*[:=]\s*["\047]?[^"\047[:space:]]+["\047]?'
+        'api[_-]?key\s*[:=]\s*["\047]?[^"\047[:space:]]+["\047]?'
+        'secret\s*[:=]\s*["\047]?[^"\047[:space:]]+["\047]?'
+    )
+    
+    for pattern in "${credential_patterns[@]}"; do
+        if echo "$content" | grep -qiE "$pattern"; then
+            handle_security_violation "potential_credential_exposure" \
+                "Potential credential pattern detected: $pattern" "$file_path"
+            return $EXIT_SECURITY_VIOLATION
+        fi
+    done
+    
+    log_debug "Content security validation passed"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Batch Validation & Reporting
+##################################
+# See: validation-reporter.sh
+
+##################################
+# Initialization
+##################################
+
+initialize_subagent_validator() {
+    log_debug "Subagent validator module initialized"
+    return $EXIT_SUCCESS
+}

package/hooks/lib/validation-reporter.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Validation Reporter Module
+#
+# Provides validation reporting and batch validation functions
+# for subagent definitions.
+# Extracted from subagent-validator.sh.
+
+# Include guard
+[[ -n "${_VALIDATION_REPORTER_LOADED:-}" ]] && return 0
+_VALIDATION_REPORTER_LOADED=1
+
+# Source required modules
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/config-constants.sh"
+source "$SCRIPT_DIR/error-handler.sh"
+
+##################################
+# Batch Validation Functions
+##################################
+
+validate_all_subagents() {
+    local directory="${1:-$SUBAGENTS_DIR}"
+    local validation_mode="${2:-strict}"
+    local validation_results=()
+    local total_count=0
+    local passed_count=0
+    local failed_count=0
+
+    log_info "Validating all subagents in: $directory"
+
+    if [[ ! -d "$directory" ]]; then
+        log_error "Directory not found: $directory"
+        return $EXIT_GENERAL_ERROR
+    fi
+
+    find "$directory" -name "*$SUBAGENT_FILE_EXTENSION" -type f 2>/dev/null | while read -r file; do
+        ((total_count++))
+        local filename
+        filename=$(basename "$file")
+
+        if validate_subagent_file "$file" "$validation_mode" 2>/dev/null; then
+            ((passed_count++))
+            validation_results+=("PASS: $filename")
+            log_debug "Validation passed: $filename"
+        else
+            ((failed_count++))
+            validation_results+=("FAIL: $filename")
+            log_debug "Validation failed: $filename"
+        fi
+    done
+
+    # Output results
+    log_info "Validation Summary:"
+    log_info "  Total subagents: $total_count"
+    log_info "  Passed: $passed_count"
+    log_info "  Failed: $failed_count"
+
+    # Detailed results in debug mode
+    if is_debug_mode 2>/dev/null; then
+        for result in "${validation_results[@]}"; do
+            log_debug "  $result"
+        done
+    fi
+
+    if [[ $failed_count -gt 0 ]]; then
+        return $EXIT_VALIDATION_FAILED
+    fi
+
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Validation Reporting Functions
+##################################
+
+generate_validation_report() {
+    local directory="${1:-$SUBAGENTS_DIR}"
+    local output_format="${2:-text}"
+
+    log_info "Generating validation report for: $directory"
+
+    case "$output_format" in
+        "json")
+            generate_json_validation_report "$directory"
+            ;;
+        "text"|*)
+            generate_text_validation_report "$directory"
+            ;;
+    esac
+}
+
+generate_text_validation_report() {
+    local directory="$1"
+
+    echo "Subagent Validation Report"
+    echo "========================="
+    echo "Directory: $directory"
+    echo "Generated: $(date)"
+    echo ""
+
+    local total=0 passed=0 failed=0
+
+    find "$directory" -name "*$SUBAGENT_FILE_EXTENSION" -type f 2>/dev/null | while read -r file; do
+        ((total++))
+        local filename name
+        filename=$(basename "$file")
+        name=$(basename "$file" "$SUBAGENT_FILE_EXTENSION")
+
+        echo -n "Validating $name... "
+
+        if validate_subagent_file "$file" "strict" 2>/dev/null; then
+            ((passed++))
+            echo "PASSED"
+        else
+            ((failed++))
+            echo "FAILED"
+            validate_subagent_file "$file" "strict" 2>&1 | sed "s/^/  Error: /"
+        fi
+        echo ""
+    done
+
+    echo "Summary:"
+    echo "  Total: $total"
+    echo "  Passed: $passed"
+    echo "  Failed: $failed"
+
+    if [[ $failed -eq 0 ]]; then
+        echo "  Status: ALL VALID"
+    else
+        echo "  Status: ISSUES FOUND"
+    fi
+}