Metadata-Version: 2.4
Name: gitspectre
Version: 0.1.0
Summary: AI-powered Git CLI tool
Author: Haris Naeem
Author-email: harisnaeem612@outlook.com
License: MIT
Project-URL: Homepage, https://github.com/predat-r/GitSpectre
Project-URL: Repository, https://github.com/predat-r/GitSpectre
Project-URL: Issues, https://github.com/predat-r/GitSpectre/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GitPython==3.1.40
Requires-Dist: requests==2.31.0
Requires-Dist: anthropic>=0.25.0
Requires-Dist: python-dotenv==1.0.0
Requires-Dist: click==8.1.7
Requires-Dist: colorama==0.4.6
Requires-Dist: yaspin==3.0.1
Requires-Dist: rich==13.7.1
Dynamic: author
Dynamic: author-email
Dynamic: license-file
Dynamic: requires-python

 # GitSpectre

A production-ready, cross-platform CLI tool that uses AI to interpret natural language Git commands, answer questions, execute operations, and handle complex code modifications with intelligent conflict resolution.

## Prerequisites

- Python 3.6 or higher
- pip (Python package installer, comes with Python)
- Git repository (for most operations)

## Installation

### Option 1: Local Installation (Recommended for Development)

1. Clone the repository:
   ```bash
   git clone https://github.com/predat-r/GitSpectre.git
   cd GitSpectre
   ```

2. Install locally:
   ```bash
   pip install -e .
   ```

   This installs the package in development mode, allowing you to modify the code.

### Option 2: Global Installation

1. Install directly from GitHub:
   ```bash
   pip install git+https://github.com/yourusername/GitSpectre.git
   ```

   Or if you have the code locally:
   ```bash
   pip install .
   ```

   This makes `spectre` available system-wide.

### Cross-Platform Notes

The installation works identically on:
- **Windows**: Use Command Prompt, PowerShell, or Git Bash
- **macOS**: Use Terminal or iTerm
- **Linux**: Use your preferred terminal

## Setup

You can use either OpenRouter (free options available) or Anthropic (Claude) as the AI provider.

### Option 1: OpenRouter (Default - Free Options Available)

1. **Get an API Key**:
   - Visit [OpenRouter.ai](https://openrouter.ai/)
   - Sign up and get your API key
   - This powers the AI functionality with various free models

2. **Configure GitSpectre**:
   ```bash
   spectre config set api_key your_openrouter_api_key_here
   ```

### Option 2: Anthropic (Claude)

1. **Get an API Key**:
   - Visit [Anthropic Console](https://console.anthropic.com/)
   - Sign up and get your API key
   - Provides full access to Claude models

2. **Configure GitSpectre**:
   ```bash
   spectre --config
   ```
   Select option 4 to set provider to "anthropic", then option 1 to set your Anthropic API key.

### Continue Setup

3. **Navigate to a Git Repository**:
   ```bash
   cd /path/to/your/git/repo
   ```

4. **Run Commands**:
   ```bash
   spectre your natural language command
   ```

   For help: `spectre --help`

## Features

### Core AI Capabilities
- **Natural Language Git Commands**: Execute complex Git workflows using plain English (e.g., "push my code but resolve any conflicts first")
- **Intelligent Code Analysis**: Reads, modifies, and validates code files with syntax checking
- **Conversational Interface**: Ask questions about Git, get explanations, and receive guidance

### Advanced Git Operations
- **Repository Management**: Init, clone, status, branches, commits, merges, diffs
- **Conflict Resolution**: Automatic detection, analysis, and resolution with user options (keep ours/theirs/merge)
- **Stashing & Tagging**: Full support for Git stashing, tagging, and advanced operations
- **Remote Operations**: Push, pull, fetch with conflict handling
- **History & Logs**: Commit history, blame, log analysis

### Code Modification Tools
- **File Operations**: Read, write, search-replace files with path validation
- **Syntax Validation**: Python AST parsing for code safety
- **Diff Analysis**: Intelligent conflict diffing and resolution suggestions

### Configuration & Security
- **Git Config Management**: Set user.name, user.email, and other Git configs
- **API Key Management**: Secure storage of OpenRouter API keys
- **Path Validation**: Ensures all operations stay within repository boundaries
- **Command Sanitization**: Prevents dangerous shell commands

### User Experience
- **Verbose Mode**: `--verbose` flag shows tool calls, commands, and internal processing
- **Colored Output**: Syntax highlighting for code, status colors for operations
- **Progress Indicators**: Spinners and status updates during long operations
- **Error Handling**: Comprehensive error messages and recovery suggestions
- **Async Processing**: Non-blocking operations for better responsiveness

### Technical Features
- **Modular Architecture**: Clean separation of CLI, agent, and tools
- **Async/Await**: Full async support for API calls and long-running tasks
- **Logging**: Configurable logging levels with file output
- **Cross-Platform**: Works identically on Windows, macOS, Linux
- **Extensible**: Plugin-like tool system for adding new capabilities

## Installation

### Prerequisites
- Python 3.6+
- Git repository (for Git operations)
- OpenRouter or Anthropic API key (for AI functionality)

### Install from Source
```bash
git clone https://github.com/yourusername/GitSpectre.git
cd GitSpectre
pip install -e .
```

### Get API Key

**OpenRouter** (default, free options):
1. Visit [OpenRouter.ai](https://openrouter.ai/)
2. Sign up and get your API key
3. Set it: `spectre config set api_key your_key_here`

**Anthropic** (Claude):
1. Visit [Anthropic Console](https://console.anthropic.com/)
2. Sign up and get your API key
3. Set it: `spectre --config` and follow the prompts

## Usage

### Command Line Options
```bash
spectre --help                    # Show help
spectre --verbose <command>       # Show detailed tool calls and processing
spectre config set <key> <value>  # Set configuration
spectre config get <key>          # Get configuration
spectre <natural language>        # Execute AI-powered Git commands
```

### Examples

#### Basic Git Operations
```bash
spectre commit my changes with message 'update readme'
spectre create a new branch called feature-x
spectre merge main into current branch
spectre push my changes to origin
spectre what is my current branch?
spectre show me the status
```

#### Conflict Resolution
```bash
spectre push my code  # Detects conflicts and explains them
spectre resolve conflicts in my files  # Interactive resolution
spectre merge feature-branch  # Handles conflicts automatically
```

#### Code Operations
```bash
spectre read the main.py file
spectre search for 'TODO' in all files
spectre validate syntax of utils.py
spectre show diff between branches
```

#### Configuration
```bash
# OpenRouter (default)
spectre config set api_key your_openrouter_key

# Anthropic - use interactive config
spectre --config

# Set Git config
spectre config set user.name "Your Name"
spectre config set user.email "your.email@example.com"
```

#### Advanced Operations
```bash
spectre stash my changes with message 'work in progress'
spectre create a tag v1.0 with message 'Release version 1.0'
spectre show diff between HEAD and HEAD~3
spectre reset files to last commit
spectre what changed in the last commit?
```

## Architecture

### Core Components
- **CLI Layer** (`cli.py`): Click-based command interface
- **Agent Layer** (`agent.py`): OpenRouter AI integration with tool calling
- **Tool Layer** (`tools/`): Modular Git and file operation functions
- **Config Layer** (`config.py`): Settings and API key management
- **Utils Layer** (`utils.py`): Logging, validation, formatting

### Tool System
GitSpectre uses a comprehensive tool-calling system with 31+ tools:

#### Git Tools (22 tools)
- Repository: `get_repo_status`, `init_repo`, `clone_repo`
- Branches: `get_branches`, `switch_branch`, `create_branch`
- Commits: `create_commit`, `get_commit_history`, `amend_commit`
- Merging: `merge_branch`, `detect_conflicts`, `resolve_conflicts`, `abort_merge`
- Remotes: `push_changes`, `pull_changes`
- Advanced: `stash_changes`, `apply_stash`, `create_tag`, `reset_files`, `get_diff`

#### File Tools (6 tools)
- Operations: `read_file`, `write_file`, `search_replace`
- Analysis: `validate_code`, `analyze_conflicts`, `apply_conflict_resolution`, `get_file_info`

#### Utility Tools (3 tools)
- Config: `get_git_config_tool`, `set_git_config_tool`, `list_git_configs`

### AI Integration
GitSpectre supports two AI providers:

#### OpenRouter (Default)
- **Models**: GPT-4o-mini, Claude 3.5 Sonnet, and many others
- Many free models available
- Use: `spectre config set api_key your_openrouter_key`

#### Anthropic (Claude)
- **Models**: Claude Sonnet 4, Claude Opus 4, Claude 3.5
- Full access to Claude models
- Use: `spectre --config` to set provider and API key

- **Tool Calling**: Function calling for programmatic Git/file operations
- **Context Awareness**: Repository state passed to AI for informed decisions
- **Safety**: Command validation and path restrictions

## Development

### Project Structure
```
gitspectre/
├── __init__.py
├── main.py          # Entry point
├── cli.py           # Command-line interface
├── agent.py         # AI agent and tool calling
├── config.py        # Configuration management
├── utils.py         # Utilities and logging
├── prompts.json     # AI system prompts
└── tools/
    ├── git_tools.py     # Git operations
    ├── file_tools.py    # File operations
    └── utility_tools.py # Configuration tools
```

### Adding New Tools
1. Create function in appropriate `tools/*.py` file
2. Add tool schema to `*_TOOLS` list
3. Update `ALL_TOOLS` in `agent.py`
4. Test with verbose mode

### Testing
```bash
# Run with verbose output
spectre --verbose "test command"

# Check logs
tail ~/.gitspectre/gitspectre.log
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure verbose mode works for debugging
5. Submit a pull request

## Publishing & Distribution

GitSpectre can be installed via multiple package managers:

### PyPI (pip)

**Automatic Publishing**: Releases are automatically published to PyPI via GitHub Actions.

**Manual Installation**:
```bash
pip install gitspectre
```

### Homebrew (macOS/Linux)

**Automatic Updates**: Homebrew formulas are automatically updated via GitHub Actions when new releases are published.

**Installation**:
```bash
brew install gitspectre
```

**Manual Formula**: The Homebrew formula is maintained in the `gitspectre.rb` file in this repository.

### Development Installation

For contributors and developers:

```bash
# Clone and install in development mode
git clone https://github.com/predat-r/GitSpectre.git
cd GitSpectre
pip install -e .
```

## CI/CD Workflows

This project uses GitHub Actions for automated publishing:

- **`.github/workflows/publish-pypi.yml`**: Builds and publishes to PyPI on release
- **`.github/workflows/update-homebrew.yml`**: Updates Homebrew formula on release

### Release Process

1. Create a new release on GitHub with a version tag (e.g., `v0.1.1`)
2. GitHub Actions automatically:
   - Builds the Python package
   - Publishes to PyPI
   - Updates the Homebrew formula
3. Users can install the new version via `pip install --upgrade gitspectre` or `brew upgrade gitspectre`

## License

MIT License - see LICENSE file for details.

## Changelog

### v0.1.0 (Current)
- Complete rewrite with modular architecture
- 31+ AI-powered tools for Git and file operations
- Intelligent conflict resolution
- Async processing and robust error handling
- Verbose mode for debugging
- Production-ready code with comprehensive documentation
