code_healer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea19c38b242524da0c2be758ff00108c1cbc277c976b818539487bb6279d33af
-  data.tar.gz: a93de9e58f4cae2a75f074515a3ffe3fc9973d64d05961e32b6ed34193090fd9
+  metadata.gz: d2732ef0363299ed27dfb68eb98922fe769ca68392cccdd556a458aab023f2eb
+  data.tar.gz: 6136efb1ddfa6849ebdd6d6f6088f6aab13120bb2f3ae4f27c717969b4bfb5bd
 SHA512:
-  metadata.gz: c7e457626092026ee1511022848c068a828fdab577e55ee3f2e3096c3b41191a7c97ad27b01c291a0485a3cd2d8d7e85e1649953efa4380e71800c2edde1f91e
-  data.tar.gz: e5edefe5097f704dee5969d86135a22ed19b35c1391c385fc2fd849559ca689a4390eba45b6f6a084861cd5395c525b22d47ef365de2443f701bfe0a4cbb7608
+  metadata.gz: 99e160254ef12aaa403dc36ff9b286b094df4ffd54a4d300d2612fb58f59d2bc3093bb87e08c9708879506a259d23ae53c1241c5041713b3ebbe50669e283cf5
+  data.tar.gz: c50f91788ca4144d8b0bc232d9fe57ae7d4bc4b45e6c79697aecfbc4d0cb3be879713ffeb79fb15a9512f84c79071feb929757b37f518adb831b6883b862ffad

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2025-01-14
+
+### Changed
+- **Significantly improved README documentation**
+- Enhanced setup instructions with interactive bash script guidance
+- Added comprehensive configuration explanations for all 50+ options
+- Included detailed markdown file creation guide for business context
+- Added best practices and troubleshooting sections
+- Improved installation and configuration examples
+- Enhanced advanced configuration strategies documentation
+
+### Fixed
+- Updated repository URLs in gemspec to point to correct GitHub repo
+- Fixed executable path configuration in gemspec
+
 ## [Unreleased]
 
 ### Added

data/README.md

@@ -30,9 +30,9 @@ CodeHealer requires the following gems:
 
 ## Installation
 
-### 1. Interactive Installation (Recommended)
+### 🚀 Quick Start with Interactive Setup (Recommended)
 
-The easiest way to get started is using our interactive setup script:
+The easiest way to get started is using our **interactive bash script** that guides you through the entire setup process:
 
 ```bash
 # Install the gem
@@ -42,14 +42,20 @@ gem install code_healer
 code_healer-setup
 ```
 
-The setup script will:
-- ✅ Add CodeHealer to your Gemfile
-- 🔑 Collect your OpenAI API key and GitHub token
-- 📝 Create configuration files
-- 💼 Set up business context
-- 📦 Install dependencies
+The interactive setup script will:
+- ✅ **Automatically add** CodeHealer to your Gemfile
+- 🔑 **Securely collect** your OpenAI API key and GitHub token
+- 📝 **Generate** all necessary configuration files
+- 💼 **Set up** business context and rules
+- 📦 **Install** all required dependencies
+- 🎯 **Configure** Git operations and PR creation
+- ⚙️ **Customize** healing strategies for your project
+- 📚 **Create sample markdown files** for business context
+- 🔧 **Set up directory structure** for documentation
 
-### 2. Manual Installation
+### 📋 Manual Installation
+
+If you prefer manual setup:
 
 ```bash
 # Add to your Gemfile
@@ -59,7 +65,7 @@ gem 'code_healer'
 bundle install
 ```
 
-### 3. Environment Variables
+### 🔑 Environment Variables
 
 CodeHealer requires several environment variables to function properly:
 
@@ -100,7 +106,108 @@ You have several options for loading these variables:
 
 ## ⚙️ Configuration
 
-### Environment Variables
+### 🔧 Configuration File
+
+The setup script automatically creates `config/code_healer.yml`, or you can create it manually. Here's a comprehensive overview of all available configuration options:
+
+```yaml
+---
+# CodeHealer Configuration
+enabled: true  # Master switch to enable/disable the entire system
+
+# 🎯 Class Control
+allowed_classes:
+  - User          # Classes that are allowed to evolve
+  - Order         # Add your model classes here
+  - PaymentProcessor
+  - Api::UserController  # Controllers are also supported
+
+excluded_classes:
+  - ApplicationController  # Classes that should NEVER evolve
+  - ApplicationRecord      # Core Rails classes
+  - ApplicationJob
+  - ApplicationMailer
+
+# 🚨 Error Type Filtering
+allowed_error_types:
+  - ArgumentError      # Invalid arguments passed to methods
+  - NameError          # Undefined variables or methods
+  - NoMethodError      # Method doesn't exist on object
+  - TypeError          # Wrong type of object
+  - ValidationError    # Custom validation errors
+
+# 🤖 Evolution Strategy
+evolution_strategy:
+  method: "api"                    # Options: "api", "claude_code_terminal", "hybrid"
+  fallback_to_api: true            # If Claude Code fails, fall back to API
+
+# 🧠 Claude Code Terminal (Local AI Agent)
+claude_code:
+  enabled: true                    # Enable Claude Code integration
+  timeout: 300                     # 5 minutes timeout for AI responses
+  max_file_changes: 10             # Maximum files Claude can modify
+  include_tests: true              # Include test files in analysis
+  command_template: "claude --print '{prompt}' --output-format text --permission-mode acceptEdits --allowedTools Edit"
+  business_context_sources:        # Sources for business context
+    - "config/business_rules.yml"
+    - "docs/business_logic.md"
+    - "spec/business_context_specs.rb"
+
+# 💼 Business Context & Domain Knowledge
+business_context:
+  enabled: true                    # Enable business context integration
+  
+  User:                           # Class-specific business rules
+    domain: "User Management"
+    key_rules:
+      - "Email must be unique and valid"
+      - "Password must meet security requirements"
+      - "User data must be validated"
+    validation_patterns:
+      - "Email format validation"
+      - "Password strength requirements"
+      - "Data integrity checks"
+  
+  Order:                          # Another class example
+    domain: "E-commerce Order Processing"
+    key_rules:
+      - "Orders must have valid customer information"
+      - "Payment validation is required"
+      - "Inventory must be checked before processing"
+
+# 🌐 OpenAI API Configuration
+api:
+  provider: "openai"              # AI provider (currently OpenAI)
+  model: "gpt-4"                  # AI model to use
+  max_tokens: 2000                # Maximum tokens in response
+  temperature: 0.1                # Creativity vs. consistency (0.0 = deterministic, 1.0 = creative)
+
+# 📝 Git Operations
+git:
+  auto_commit: true               # Automatically commit fixes
+  auto_push: true                 # Push to remote repository
+  branch_prefix: "evolve"         # Branch naming: evolve/classname-methodname-timestamp
+  commit_message_template: 'Fix {class_name}##{method_name}: {error_type}'
+  pr_target_branch: "main"        # Target branch for pull requests
+
+# 🔀 Pull Request Configuration
+pull_request:
+  enabled: true                   # Enable automatic PR creation
+  auto_create: true               # Create PRs automatically
+  title_template: 'Fix {class_name}##{method_name}: Handle {error_type}'
+  labels:                         # Labels to add to PRs
+    - "auto-fix"
+    - "self-evolving"
+    - "bug-fix"
+
+# ⚡ Sidekiq Background Processing
+sidekiq:
+  queue: "evolution"              # Queue name for healing jobs
+  retry: 3                        # Number of retry attempts
+  backtrace: true                 # Include backtraces in job data
+```
+
+### 🔑 Environment Variables
 
 Create a `.env` file in your Rails app root:
 
@@ -116,38 +223,6 @@ GITHUB_REPOSITORY=username/repo
 REDIS_URL=redis://localhost:6379/0
 ```
 
-### Configuration File
-
-The setup script creates `config/code_healer.yml` automatically, or you can create it manually:
-
-```yaml
-enabled: true
-
-# Allowed classes for healing
-allowed_classes:
-  - User
-  - Order
-  - PaymentProcessor
-
-# Evolution strategy
-evolution_strategy:
-  method: api  # Options: api, claude_code_terminal, hybrid
-  fallback_to_api: true
-
-# OpenAI API configuration
-api:
-  provider: openai
-  model: gpt-4
-  max_tokens: 2000
-  temperature: 0.1
-
-# Git operations
-git:
-  auto_commit: true
-  auto_push: true
-  branch_prefix: "heal"
-```
-
 ## 🏥 How It Works
 
 1. **Error Detection**: CodeHealer catches runtime errors using Rails error reporting
@@ -197,35 +272,220 @@ Check your Sidekiq dashboard at `http://localhost:3000/sidekiq` to see healing j
 
 ## 🔧 Advanced Configuration
 
-### Business Context
+### 🎯 Interactive Setup Script
+
+The `code_healer-setup` script provides an interactive, guided setup experience:
+
+```bash
+$ code_healer-setup
+
+🏥 Welcome to CodeHealer Setup!
+================================
+
+This interactive setup will configure CodeHealer for your Rails application.
+
+📋 What we'll set up:
+- OpenAI API configuration
+- GitHub integration
+- Business context rules
+- Git operations
+- Healing strategies
+- Sidekiq configuration
+
+🔑 Step 1: OpenAI Configuration
+Enter your OpenAI API key: ****************
+✅ OpenAI API key configured successfully!
+
+🔗 Step 2: GitHub Integration
+Enter your GitHub personal access token: ****************
+Enter your GitHub repository (username/repo): deepan-g2/myapp
+✅ GitHub integration configured successfully!
+
+💼 Step 3: Business Context
+Would you like to set up business context rules? (y/n): y
+Enter business domain for User class: User Management
+Enter key business rules (comma-separated): Email validation, Password security, Data integrity
+✅ Business context configured successfully!
+
+⚙️ Step 4: Healing Strategy
+Choose evolution method:
+1. API (OpenAI) - Cloud-based, reliable
+2. Claude Code Terminal - Local AI agent, full codebase access
+3. Hybrid - Best of both worlds
+Enter choice (1-3): 2
+✅ Claude Code Terminal strategy selected!
+
+📝 Step 5: Git Configuration
+Enter branch prefix for fixes: evolve
+Enter target branch for PRs: main
+✅ Git configuration completed!
+
+🎉 Setup complete! CodeHealer is now configured for your application.
+```
+
+### 💼 Business Context Integration
+
+CodeHealer can read business context from **Markdown (.md) files** to provide domain-specific knowledge for better AI fixes. These files help the AI understand your business rules, validation patterns, and domain logic.
 
-Create `docs/business_rules.md` to provide domain-specific context:
+#### 📁 Creating Business Context Files
 
+Create markdown files in your project to define business rules:
+
+**`docs/business_rules.md`** - General business rules:
 ```markdown
-# Business Rules
+# Business Rules & Standards
 
-## Error Handling
+## Error Handling Principles
 - All errors should be logged for audit purposes
-- User-facing errors should be user-friendly
-- Critical errors should trigger alerts
+- User-facing errors should be user-friendly and actionable
+- Critical errors should trigger immediate alerts
+- Security errors should never expose sensitive information
+
+## Data Validation Standards
+- All user inputs must be validated before processing
+- Business rules must be enforced at the model level
+- Invalid data should be rejected with clear, helpful error messages
+- Data integrity must be maintained across all operations
+
+## Security Guidelines
+- Never log sensitive information (passwords, tokens, PII)
+- Input sanitization is mandatory for all user-provided data
+- Rate limiting should be applied to prevent abuse
+- Authentication must be verified for all protected operations
+```
+
+**`docs/user_management.md`** - Domain-specific rules:
+```markdown
+# User Management Domain
+
+## User Registration
+- Email addresses must be unique across the system
+- Password strength: minimum 8 characters, mixed case, numbers
+- Email verification is required before account activation
+- Username must be alphanumeric, 3-20 characters
+
+## User Authentication
+- Failed login attempts are limited to 5 per hour
+- Password reset tokens expire after 1 hour
+- Session timeout after 24 hours of inactivity
+- Multi-factor authentication for admin accounts
+
+## Data Privacy
+- User data is encrypted at rest
+- GDPR compliance for EU users
+- Right to data deletion must be honored
+- Audit trail for all data modifications
+```
 
-## Data Validation
-- All user inputs must be validated
-- Business rules must be enforced
-- Invalid data should be rejected with clear messages
+**`docs/order_processing.md`** - Another domain example:
+```markdown
+# Order Processing Domain
+
+## Order Validation
+- Customer information must be complete and verified
+- Payment method must be valid and authorized
+- Inventory must be available before order confirmation
+- Shipping address must be deliverable
+
+## Business Rules
+- Orders cannot be cancelled after shipping
+- Refunds processed within 30 days
+- Bulk orders get 10% discount
+- Free shipping for orders over $50
+
+## Error Handling
+- Insufficient inventory: suggest alternatives
+- Payment failure: retry up to 3 times
+- Invalid address: prompt for correction
+- System errors: queue for manual review
 ```
 
-### Custom Healing Strategies
+#### 🔧 Configuration for Markdown Files
+
+Update your `config/code_healer.yml` to include these files:
 
 ```yaml
-# Use Claude Code Terminal for local development
+business_context:
+  enabled: true
+  
+  # Sources for business context (markdown files)
+  sources:
+    - "docs/business_rules.md"
+    - "docs/user_management.md"
+    - "docs/order_processing.md"
+    - "README.md"  # Project documentation
+    - "docs/API.md"  # API documentation
+
+claude_code:
+  business_context_sources:
+    - "docs/business_rules.md"
+    - "docs/user_management.md"
+    - "docs/order_processing.md"
+    - "config/business_rules.yml"  # YAML format also supported
+```
+
+#### 📝 Markdown File Best Practices
+
+1. **Use clear headings** (`#`, `##`, `###`) for structure
+2. **Include specific examples** of valid/invalid data
+3. **Document error scenarios** and expected responses
+4. **Keep it concise** but comprehensive
+5. **Update regularly** as business rules evolve
+6. **Use consistent formatting** for better AI parsing
+
+#### 🎯 How AI Uses Markdown Context
+
+When CodeHealer encounters an error, it:
+1. **Reads relevant markdown files** based on the error context
+2. **Extracts business rules** that apply to the failing code
+3. **Generates fixes** that respect your business logic
+4. **Ensures compliance** with your domain standards
+5. **Maintains consistency** with existing code patterns
+
+### 🤖 Custom Healing Strategies
+
+#### API Strategy (OpenAI)
+```yaml
 evolution_strategy:
-  method: claude_code_terminal
+  method: "api"
+  fallback_to_api: false  # No fallback needed
+
+api:
+  provider: "openai"
+  model: "gpt-4"
+  max_tokens: 3000        # Increase for complex fixes
+  temperature: 0.05       # More deterministic
+```
+
+#### Claude Code Terminal Strategy
+```yaml
+evolution_strategy:
+  method: "claude_code_terminal"
+  fallback_to_api: true   # Fallback if Claude fails
+
+claude_code:
+  enabled: true
+  timeout: 600             # 10 minutes for complex fixes
+  max_file_changes: 15     # Allow more file modifications
+  include_tests: true      # Include test files in analysis
+```
+
+#### Hybrid Strategy
+```yaml
+evolution_strategy:
+  method: "hybrid"
   fallback_to_api: true
 
+# Claude Code for local development
 claude_code:
   enabled: true
-  command_template: "claude --print '{prompt}' --output-format text"
+  timeout: 300
+
+# OpenAI API for production/fallback
+api:
+  provider: "openai"
+  model: "gpt-4"
+  max_tokens: 2000
 ```
 
 ## 🛠️ Development
@@ -245,6 +505,56 @@ gem build code_healer.gemspec
 bundle exec rspec
 ```
 
+## ⚠️ Configuration Best Practices
+
+### 🎯 Class Selection
+- **Start conservative**: Only allow classes you're comfortable with auto-evolving
+- **Exclude core classes**: Never allow `ApplicationController`, `ApplicationRecord`, etc.
+- **Test thoroughly**: Verify allowed classes work as expected before production
+
+### 🔐 Security Considerations
+- **API keys**: Store in environment variables, never in code
+- **GitHub tokens**: Use minimal required permissions (`repo`, `workflow`)
+- **Business context**: Be careful with sensitive business rules in markdown files
+
+### 🚀 Performance Optimization
+- **Claude Code timeout**: Set appropriate timeouts (300-600 seconds)
+- **Max file changes**: Limit to prevent excessive modifications
+- **Sidekiq queue**: Use dedicated queue for evolution jobs
+
+### 🔧 Troubleshooting Common Issues
+
+#### "No backtrace available" Error
+```yaml
+# Ensure backtrace is enabled in Sidekiq config
+sidekiq:
+  backtrace: true
+```
+
+#### Pull Request Creation Fails
+```yaml
+# Verify GitHub token has correct permissions
+# Check target branch exists
+git:
+  pr_target_branch: "main"  # Must exist in remote
+```
+
+#### Claude Code Not Responding
+```yaml
+# Increase timeout and verify command template
+claude_code:
+  timeout: 600
+  command_template: "claude --print '{prompt}' --output-format text"
+```
+
+#### Business Context Not Loading
+```yaml
+# Ensure markdown files exist and are readable
+business_context:
+  enabled: true
+  # Check file paths are correct
+```
+
 ## 📚 Documentation
 
 - [Installation Guide](docs/INSTALLATION.md)

data/lib/code_healer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CodeHealer
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: code_healer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Deepan Kumar