Skip to content

Latest commit

 

History

History
262 lines (217 loc) · 10.6 KB

AGENTS.md

File metadata and controls

262 lines (217 loc) · 10.6 KB

AGENTS.md

This file provides specialized guidance for AI agents working with the bgit codebase.

Project Architecture Summary

bgit is a sophisticated Git workflow automation tool built in Rust with a trait-based, step-driven architecture. The system orchestrates complex Git workflows through interactive steps while enforcing smart rules to prevent common Git mistakes.

Core Architecture Components

  1. Step-Based Execution Engine (src/step.rs + src/workflow_queue.rs)
  2. Rules Validation System (src/rules/)
  3. Atomic Git Events (src/events/)
  4. Cross-Platform Authentication (src/auth/ with SSH agent management)
  5. Two-Tier Configuration (local + global config system)
  6. Hook Execution Framework (platform-specific implementations)

Key Traits and Interfaces

Workflow Execution Traits

// Core step execution
pub(crate) trait ActionStep {
    fn execute(&self) -> Result<Step, Box<BGitError>>;
}

pub(crate) trait PromptStep {
    fn execute(&self) -> Result<Step, Box<BGitError>>;
}

// Git operations
pub(crate) trait AtomicEvent<'a> {
    fn execute(&self) -> Result<bool, Box<BGitError>>;
    fn pre_execute_hook(&self) -> Result<bool, Box<BGitError>>;
    fn post_execute_hook(&self) -> Result<bool, Box<BGitError>>;
}

// Validation rules
pub(crate) trait Rule {
    fn check(&self) -> Result<RuleOutput, Box<BGitError>>;
    fn try_fix(&self) -> Result<bool, Box<BGitError>>;
}

Development Patterns and Conventions

Naming Conventions

  • ActionSteps: ta##_descriptive_name.rs (e.g., ta01_is_git_repo.rs)
  • PromptSteps: pa##_ask_descriptive_action.rs (e.g., pa05_ask_to_add.rs)
  • Rules: a##_rule_description.rs (e.g., a12_no_secrets_staged.rs)
  • Events: git_operation.rs (e.g., git_commit.rs, git_push.rs)

File Structure Patterns

  • Each module typically has a single public struct implementing the relevant trait
  • Error handling uses BGitError with contextual information
  • Configuration access through BGitConfig and BGitGlobalConfig
  • Cross-platform implementations use conditional compilation (#[cfg(unix)], #[cfg(windows)])

Code Organization

src/
├── main.rs                          # Entry point and CLI routing
├── step.rs                          # Core execution model
├── workflow_queue.rs                # Workflow execution engine
├── bgit_error.rs                    # Structured error handling
├── rules.rs + rules/                # validation rules
├── events.rs + events/              # Git operations
├── auth/ + auth/ssh/                # Authentication and SSH management
├── config/                          # Two-tier configuration system
├── workflows/default/action/        # ActionStep implementations
├── workflows/default/prompt/        # PromptStep implementations
├── hook_executor/                   # Cross-platform hook execution
├── llm_tools/                       # AI integration components
└── cmd/                             # CLI command implementations

Implementation Guidelines for AI Agents

When Adding New Rules

  1. Rule Structure: Implement Rule trait in src/rules/aXX_rule_name.rs
  2. Error Handling: Use BGitError with appropriate workflow type
  3. Configuration: Add rule to WorkflowRules enum if configurable
  4. Auto-fixing: Implement try_fix() for recoverable failures
  5. Testing: Focus on edge cases and cross-platform compatibility

When Adding New Workflow Steps

  1. Step Type: Choose ActionStep (automated) vs PromptStep (interactive)
  2. Step Progression: Define clear next step logic in execute() return
  3. State Management: Use Git repository state to determine flow
  4. Error Recovery: Handle failures gracefully with appropriate error context
  5. User Experience: For prompts, provide clear choices and guidance

When Adding New Git Events

  1. Event Wrapper: Implement AtomicEvent trait with proper Git2 integration
  2. Rule Integration: Call appropriate rules in pre_execute_hook()
  3. Hook Support: Implement pre/post hook execution points
  4. Authentication: Integrate with existing auth system when needed
  5. Platform Support: Ensure cross-platform compatibility

Configuration System Usage

// Local configuration (repository-specific)
let config = BGitConfig::load()?;
let rule_level = config.workflow_rules.get_rule_level("default", "a12_no_secrets_staged");

// Global configuration (user-wide)
let global_config = BGitGlobalConfig::load_global()?;
let auth_preference = global_config.auth_preference;

Error Handling Patterns

// Structured error creation
BGitError::new(
    "Rule Check Failed".to_string(),
    format!("Secret detected in file: {}", file_path),
    BGitErrorWorkflowType::Rules,
    step_name.to_string(),
    NO_EVENT.to_string(),
    rule_name.to_string(),
)

// Rule execution with auto-fixing
match rule.check() {
    Ok(RuleOutput::Success) => Ok(true),
    Ok(RuleOutput::Exception(msg)) => {
        if rule.try_fix()? {
            rule.check() // Re-check after fix
        } else {
            Err(error)
        }
    }
    Err(e) => Err(e),
}

Secret Detection Implementation Notes

The a12_no_secrets_staged rule demonstrates sophisticated pattern matching:

  • Regex Detection: patterns for different secret types
  • Entropy Analysis: Statistical randomness measurement
  • Context Validation: Custom validators for specific secret formats
  • False Positive Reduction: Whitelist common words, detect patterns

SSH Management Implementation Notes

The SSH system (src/auth/ssh/) provides:

  • Agent Lifecycle: Automatic creation, key loading, cleanup
  • Cross-Platform: Unix sockets vs Windows named pipes
  • Key Discovery: Automatic ~/.ssh/id_* detection
  • Retry Logic: Configurable attempts with exponential backoff
  • Stale Cleanup: Process validation and socket cleanup

Testing Strategies

Unit Testing Focus Areas

  1. Rule Logic: Test detection, fixing, and edge cases
  2. Step Progression: Verify correct workflow routing
  3. Configuration: Test parsing, defaults, and overrides
  4. Cross-Platform: Validate platform-specific implementations
  5. Error Handling: Ensure proper error propagation and context

Integration Testing Patterns

  • Use tempfile for temporary Git repositories
  • Use assert_cmd for CLI testing
  • Mock external dependencies (SSH agents, remote repositories)
  • Test complete workflow scenarios end-to-end

Performance Considerations

Optimization Points

  1. Rule Execution: Cache expensive checks when possible
  2. Git Operations: Minimize repository state queries
  3. SSH Agent: Reuse connections, avoid redundant key loading
  4. Configuration: Load once and pass references
  5. Pattern Matching: Compile regex patterns once

Memory Management

  • Use Box<dyn Trait> for trait objects to enable dynamic dispatch
  • Prefer &str over String for temporary string operations
  • Use Arc<> for shared configuration data across threads

Security Considerations

Sensitive Data Handling

  1. Credentials: Base64 encode in configuration files
  2. Memory: Clear sensitive data after use when possible
  3. Logging: Never log credentials or secrets
  4. File Permissions: Respect SSH key file permissions
  5. Process Isolation: Clean up SSH agents and temporary files

Secret Detection Guidelines

  • Maintain high sensitivity for security rules
  • Balance false positives vs false negatives
  • Provide clear remediation guidance
  • Support whitelist mechanisms for known safe patterns

Common Development Tasks

Adding a New Authentication Method

  1. Implement auth strategy in src/auth/
  2. Update PreferredAuth enum
  3. Integrate with existing event system
  4. Add configuration options
  5. Test cross-platform compatibility

Extending the Rules System

  1. Create new rule file following naming convention
  2. Implement Rule trait with proper error handling
  3. Add to rule registry in src/rules.rs
  4. Update configuration schema if needed
  5. Add comprehensive tests

Adding New Git Operations

  1. Create event file in src/events/
  2. Implement AtomicEvent trait
  3. Integrate with rules system
  4. Add hook support points
  5. Update workflow steps as needed

AI Agent Specific Guidelines

Code Analysis Strategies

  1. Understand Traits First: Focus on understanding the core traits before diving into implementations
  2. Follow Data Flow: Trace how steps, rules, and events interact
  3. Check Cross-Platform Code: Pay attention to #[cfg] attributes for platform differences
  4. Review Error Paths: Understand how errors propagate through the system
  5. Study Configuration: Understand how behavior is customized through config

Code Generation Best Practices

  1. Follow Existing Patterns: Match naming conventions and code structure
  2. Implement Error Handling: Always include proper BGitError context
  3. Consider Cross-Platform: Use appropriate platform abstractions
  4. Add Documentation: Include clear docstrings for public interfaces
  5. Test Thoroughly: Consider edge cases and error conditions

Logging Conventions

  1. No Emoji Symbols: All logging output must be emoji-free for compatibility across terminals and systems
  2. Clear Status Messages: Use plain text for success/failure indicators
    • Use "Successfully" instead of "✓"
    • Use "Failed" instead of "✗"
    • Use "Warning" instead of "⚠"
  3. Debug vs User Output: Debug logs (debug!()) are for developers, user output (println!()) should be concise
  4. Consistent Formatting: Maintain consistent message structure across similar operations
  5. Cross-Platform Text: Ensure all text displays correctly on Unix, Windows, and different terminal emulators
// Good: Emoji-free logging
debug!("Successfully created persistent agent");
println!("SSH key '{}' added successfully!", key_name);

// Bad: Contains emoji symbols
debug!("✓ Successfully created persistent agent");
println!("✓ SSH key '{}' added successfully!", key_name);

Common Pitfalls to Avoid

  1. Ignoring Platform Differences: Not handling Windows vs Unix differences
  2. Poor Error Context: Generic error messages without proper context
  3. Rule Bypass: Forgetting to integrate rules into new operations
  4. Memory Leaks: Not properly cleaning up SSH agents or temporary resources
  5. Configuration Conflicts: Not respecting user configuration overrides

This guide should help AI agents understand the bgit codebase architecture and contribute effectively while maintaining the existing code quality and design patterns.