# Project Plan: omni-dev CLI Git Tools

**Status:** Historical — describes the initial CLI design before Atlassian, MCP, and AI providers existed; kept for institutional memory.

## Overview

This project implements a CLI tool that provides the functionality of the existing `.claude/commands/twiddle-msg` bash script but with a Rust-based CLI interface. The tool will support two main subcommands:

- `omni-dev git commit message view [commit-range]` - Analyze git commits and output comprehensive repository information in YAML format
- `omni-dev git commit message amend <yaml-file>` - Amend commit messages based on a YAML configuration file

## Project Architecture

### Core Components

1. **CLI Interface Layer** (`src/cli/`)
   - Command line argument parsing using `clap`
   - Subcommand routing and validation
   - User input/output handling with colored terminal output

2. **Git Operations Layer** (`src/git/`)
   - Repository analysis and validation
   - Commit message extraction and modification
   - Working directory status checking
   - Remote branch detection and main branch identification
   - Interactive rebase operations for non-HEAD commits

3. **Data Processing Layer** (`src/data/`)
   - YAML parsing and generation
   - JSON intermediate processing
   - Commit analysis and conventional commit type detection
   - File change analysis and scope determination

4. **Core Application Layer** (`src/core/`)
   - Main application logic coordination
   - Error handling and validation
   - Configuration management

### Key Features to Implement

#### 1. Git Repository Analysis (`git commit message view` command)
- **Working Directory Status**: Check for uncommitted changes, untracked files
- **Remote Analysis**: Detect all remotes, identify main branches (main/master), get URLs
- **Commit Analysis**: For each commit in range:
  - Extract metadata (hash, author, date, original message)
  - Detect conventional commit type (feat, fix, docs, test, chore, etc.)
  - Analyze file changes to determine scope
  - Generate proposed commit messages
  - Check if commit exists in remote main branches
  - Provide detailed file change statistics

#### 2. Commit Amendment (`git commit message amend` command)
- **YAML Processing**: Parse amendment files with commit hash → message mapping
- **Safety Checks**: 
  - Validate working directory is clean
  - Prevent amendment of commits already in remote main branches
  - Skip merge commits and empty commits
- **Amendment Operations**:
  - Simple HEAD amendment for latest commits
  - Interactive rebase for older commits in history
  - Preserve commit metadata and trailers

#### 3. Data Output Format
- **Structured YAML Output**: Comprehensive repository information including:
  - Field explanations and documentation
  - Working directory status
  - Remote repository information
  - Per-commit analysis with conventional commit suggestions
  - File change details and diff summaries

### Technical Specifications

#### Dependencies
```toml
clap = { version = "4.0", features = ["derive", "color"] }
git2 = "0.18"
serde = { version = "1.0", features = ["derive"] }
serde_yaml = "0.9"
serde_json = "1.0"
termcolor = "1.1"
anyhow = "1.0"
chrono = { version = "0.4", features = ["serde"] }
```

#### CLI Interface Structure
```
omni-dev git commit message <subcommand> [options] [args...]

Subcommands:
  view [commit-range]    Output commit analysis in YAML format
  amend <yaml-file>      Amend commits with messages from YAML file

Examples:
  omni-dev git commit message view HEAD~3..HEAD
  omni-dev git commit message amend amendments.yml
```

#### YAML Amendment File Format
```yaml
amendments:
  - commit: "full-40-character-sha1-hash"
    message: "New commit message"
  - commit: "another-full-commit-hash"
    message: "Another new commit message"
```

### Implementation Plan

#### Phase 1: Foundation
1. **Project Structure Setup**
   - Update `Cargo.toml` with required dependencies
   - Create modular directory structure (`cli/`, `git/`, `data/`)
   - Set up basic CLI interface with `clap`

2. **Core Git Operations**
   - Implement repository detection and validation
   - Create git repository wrapper with basic operations
   - Add working directory status checking

#### Phase 2: Repository Analysis
1. **Remote Detection**
   - Implement remote repository enumeration
   - Add main branch detection logic (main/master/develop)
   - Create remote information structures

2. **Commit Analysis Engine**
   - Build commit metadata extraction
   - Implement file change analysis
   - Add conventional commit type detection
   - Create scope analysis based on file paths

#### Phase 3: Data Processing
1. **YAML Output Generation**
   - Implement structured data output with field documentation
   - Add comprehensive commit information formatting
   - Create working directory and remote status reporting

2. **YAML Input Processing**
   - Build YAML amendment file parser
   - Add validation for commit hashes and message format
   - Implement safety checks for amendment operations

#### Phase 4: Amendment Operations
1. **Simple Amendment**
   - Implement HEAD commit message amendment
   - Add commit metadata preservation

2. **Complex Amendment (Rebase)**
   - Build interactive rebase wrapper
   - Implement multi-commit amendment with proper ordering
   - Add robust error handling and recovery

#### Phase 5: Testing and Validation
1. **Unit Testing**
   - Test all core functionality modules
   - Validate git operations in various repository states
   - Test YAML parsing and generation

2. **Integration Testing**
   - Test complete workflows with real git repositories
   - Validate amendment operations don't corrupt repository
   - Test error handling and edge cases

### Error Handling Strategy

#### Validation Levels
1. **Input Validation**
   - CLI argument validation
   - File existence and format checking
   - Git repository validation

2. **Operation Safety**
   - Working directory cleanliness checks
   - Remote branch ancestry validation
   - Commit existence verification

3. **Recovery Mechanisms**
   - Graceful failure for invalid operations
   - Clear error messages with suggested fixes
   - Automatic cleanup for failed rebase operations

### Security Considerations

1. **Git Repository Safety**
   - Never modify repositories with uncommitted changes
   - Refuse to amend commits already in remote main branches
   - Validate all commit hashes before operations

2. **Input Validation**
   - Sanitize YAML input to prevent injection
   - Validate file paths and commit ranges
   - Limit resource usage for large repositories

### Performance Considerations

1. **Git Operations**
   - Use libgit2 for efficient repository access
   - Minimize git command executions
   - Cache expensive operations (remote branch detection)

2. **Data Processing**
   - Stream processing for large commit ranges
   - Efficient YAML/JSON serialization
   - Memory-conscious file change analysis

### Compatibility

1. **Git Versions**
   - Support git 2.0+ repositories
   - Handle various remote URL formats (SSH, HTTPS)
   - Compatible with GitHub, GitLab, and other Git hosting

2. **Operating Systems**
   - Cross-platform Rust implementation
   - Handle platform-specific path separators
   - Terminal color support detection

### Future Enhancements

1. **Additional Features**
   - Configuration file support
   - Custom commit type detection rules
   - Integration with commit message templates

2. **Performance Optimizations**
   - Parallel processing for multiple commits
   - Incremental analysis caching
   - Background remote branch updates

### Success Criteria

1. **Functional Parity**
   - Complete replacement for bash script functionality
   - Identical YAML output format
   - Same amendment operation safety

2. **Improved User Experience**
   - Faster execution than shell script
   - Better error messages and validation
   - Cross-platform compatibility

3. **Code Quality**
   - Comprehensive test coverage (>90%)
   - Clean, maintainable Rust code
   - Proper error handling throughout

### Timeline Estimate

- **Phase 1 (Foundation)**: 2-3 days
- **Phase 2 (Analysis)**: 3-4 days  
- **Phase 3 (Data Processing)**: 2-3 days
- **Phase 4 (Amendment)**: 4-5 days
- **Phase 5 (Testing)**: 2-3 days

**Total Estimated Time**: 13-18 days

### Risks and Mitigation

1. **Git2 Library Complexity**
   - Risk: libgit2 binding complexity
   - Mitigation: Start with simple operations, expand gradually

2. **Interactive Rebase Challenges**
   - Risk: Complex rebase operations may fail
   - Mitigation: Implement robust error handling and recovery

3. **Cross-platform Compatibility**
   - Risk: Platform-specific git behaviors
   - Mitigation: Extensive testing on multiple platforms

This comprehensive plan provides a roadmap for implementing a robust, safe, and efficient replacement for the existing bash script while maintaining full compatibility and adding improvements in performance and user experience.