codevaultAI 1.1.2
GitHub-like version control system with AI-powered auto-updates and merge conflict resolution
Requires Python: >=3.8
Keywords: version-control git vcs ai merge-conflicts llm groq

# CodeVault - AI-Powered Version Control System

[![PyPI version](https://badge.fury.io/py/selfvcs.svg)](https://badge.fury.io/py/selfvcs)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight, GitHub-like version control system with **AI-powered merge conflict resolution**. Perfect for solo developers and small teams who want the power of version control without the complexity of Git.

## ✨ What's New in v1.1.0

🎉 **AI-Powered Merge Conflict Resolution** - When two people edit the same file, CodeVault uses AI to intelligently merge both changes automatically!

No more cryptic conflict markers. No more manual merging. Just smart, automatic resolution that preserves functionality from both versions.

## 🚀 Features

### Core Version Control
- **📦 Push**: Store code snapshots with automatic change detection
- **⬇️ Pull**: Restore code from any previous commit
- **🗑️ Delete**: Remove commits from history  
- **📜 Log**: View commit history with timestamps and insights
- **🏷️ Semantic Versioning**: Auto-bumps version based on change type

### AI Superpowers ✨
- **🤖 Auto-Commit Messages**: AI analyzes your code and generates professional commit messages
- **🔀 Smart Merge**: Automatically resolves conflicts when multiple people edit the same file
- **📊 Code Insights**: AI classifies changes (feat/fix/refactor) and risk level
- **🎯 Impact Analysis**: Identifies which functions/modules were affected

### Merge Conflict Resolution 🆕
- **Automatic Detection**: Knows when your changes conflict with the latest version
- **Three Strategies**:
  - `ai` - AI intelligently merges both versions (recommended)
  - `local` - Keep your changes
  - `remote` - Keep their changes
- **Safe Workflow**: Automatic backups before merging
- **Manual Fallback**: Traditional conflict markers if AI can't resolve

## 📦 Installation

```bash
pip install selfvcs
```

### Setup API Key (for AI features)

Get a free API key from [Groq Console](https://console.groq.com)

```bash
# Option 1: Environment variable
export GROQ_API_KEY="gsk_your_key_here"

# Option 2: Save to config (persistent)
codevault auth set gsk_your_key_here
```

## 🎯 Quick Start

### Basic Usage

```bash
# Initialize repository
codevault init

# Push code with AI-generated message
codevault push myfile.py --auto-detect

# Or use manual message
codevault push myfile.py -m "Add new feature"

# View history
codevault log

# Restore old version
codevault pull abc12345
```

### Handling Merge Conflicts

**Scenario**: You and a teammate both edited `app.py`

```bash
# Try to push - conflict detected!
codevault push app.py -m "My changes"
# ⚠ Merge conflicts detected in 1 file(s)

# Check what's conflicting
codevault check-conflicts app.py

# Let AI resolve it automatically
codevault auto-merge app.py --strategy ai
# ✓ AI resolved: app.py

# Review the merged code
cat app.py

# Push the merge
codevault push app.py -m "Merged changes"
```

## 📖 Complete Command Reference

### Repository Management
```bash
codevault init                    # Initialize repository
codevault status                  # Show repo status
codevault log -n 20              # Show last 20 commits
```

### Version Control
```bash
codevault push <files> -m "msg"         # Commit with message
codevault push <files> --auto-detect    # AI generates message
codevault push <files> --force          # Force push (skip conflict check)
codevault pull <commit-id>              # Restore commit
codevault delete <commit-id>            # Delete commit
```

### Merge Conflicts 🆕
```bash
codevault check-conflicts <files>           # Check for conflicts
codevault auto-merge <files> --strategy ai  # AI merge (default)
codevault auto-merge <files> --strategy local   # Keep local changes
codevault auto-merge <files> --strategy remote  # Keep remote changes
```

### Insights & Analytics
```bash
codevault insight <commit-id>    # View commit details
codevault changelog -n 50        # Generate changelog
```

### Configuration
```bash
codevault auth set <api-key>     # Set GROQ API key
```

## 💡 Real-World Example

### Problem: Two developers, same file

**Developer A** adds shipping logic:
```python
def calculate_total(items):
    total = sum(item.price * item.qty for item in items)
    shipping = 5.99 if total < 50 else 0
    return total + shipping
```

**Developer B** adds tax calculation:
```python
def calculate_total(items):
    total = sum(item.price * item.qty for item in items)
    tax = total * 0.08
    return total + tax
```

### Solution: AI Auto-Merge

```bash
# Developer A tries to push
codevault push app.py -m "Add shipping"
# ⚠ Merge conflicts detected

# AI resolves automatically
codevault auto-merge app.py --strategy ai
```

**Result**: AI merges BOTH features:
```python
def calculate_total(items):
    total = sum(item.price * item.qty for item in items)
    tax = total * 0.08
    shipping = 5.99 if total < 50 else 0
    return total + tax + shipping
```

✅ Both shipping AND tax preserved!  
✅ No manual editing needed!  
✅ Code works correctly!

## 🎨 Use Cases

- **Solo Developers**: Track your code history without Git complexity
- **Small Teams**: Collaborate without merge headaches
- **Learning**: Understand version control concepts
- **Prototyping**: Quick versioning for experiments
- **Code Reviews**: AI-assisted merging of feedback

## ⚙️ How AI Merge Works

1. **Detection**: Compares local file vs last commit, finds conflicts
2. **Analysis**: AI (Llama 70B) examines both versions for:
   - Function signatures and logic
   - Code semantics and intent
   - Style and formatting
3. **Resolution**: Generates merged version that:
   - Keeps functionality from both
   - Removes duplicates
   - Maintains consistency
4. **Safety**: Creates backup, writes merge, allows review

## 🔒 Safety Features

- **Automatic Backups**: Original files backed up before merge
- **Conflict Detection**: Won't let you overwrite accidentally  
- **Force Override**: Available but requires explicit `--force` flag
- **Manual Fallback**: Traditional markers if AI fails
- **Semantic Versioning**: Auto-tracks breaking vs non-breaking changes

## 🎓 Best Practices

1. **Check before pushing**
   ```bash
   codevault check-conflicts myfile.py
   ```

2. **Review AI merges**
   - Check merged file
   - Run tests
   - Then commit

3. **Small, frequent commits**
   - Easier to merge
   - Better AI performance

4. **Use auto-detect for messages**
   ```bash
   codevault push --auto-detect
   ```

5. **Choose the right strategy**
   - `ai` - When both changes matter
   - `local` - When you know yours is right
   - `remote` - When their version is better

## 🔧 Advanced Configuration

### Multiple Projects

Each project gets its own `.codevault/` directory:

```bash
cd project1
codevault init
codevault push src/ -m "Project 1 changes"

cd ../project2
codevault init
codevault push app/ -m "Project 2 changes"
```

### API Key Priority

CodeVault checks in this order:
1. `GROQ_API_KEY` environment variable
2. `CODEVAULT_GROQ_KEY` environment variable  
3. `~/.codevault/config.json` (from `auth set`)

### Custom Workflow

```python
from codevault import CodeVault

vault = CodeVault()

# Check conflicts programmatically
has_conflicts, conflicts = vault._detect_merge_conflicts(['app.py'])

if has_conflicts:
    # Auto-resolve
    result = vault.auto_merge(['app.py'], strategy='ai')
    print(result)
```

## 📁 Repository Structure

```
your-project/
├── .codevault/
│   ├── commits/           # All commit snapshots
│   │   └── abc12345/
│   │       ├── commit.json
│   │       └── file.snapshot
│   ├── merge/            # Backup files during merge
│   ├── metadata.json     # Repo metadata & history
│   └── index.json       # Staging area
└── your files...

~/.codevault/
└── config.json          # Global user config (API key)
```

## ❓ FAQ

**Q: Do I need Git?**  
A: No! CodeVault is standalone.

**Q: Can I use it without the AI features?**  
A: Yes! All commands work without an API key. Just use `--strategy local` or `--strategy remote` for merges.

**Q: Is my code sent to the cloud?**  
A: Only when using AI features (commit messages, merge). The code snippets sent to Groq are truncated (first ~4000 chars). All commits are stored locally.

**Q: What if AI merge fails?**  
A: CodeVault falls back to traditional conflict markers for manual resolution.

**Q: Can I use this in production?**  
A: CodeVault is great for personal projects and small teams. For large teams or critical production, we still recommend Git.

**Q: How much does it cost?**  
A: CodeVault is free. Groq offers a generous free tier for the AI features.

## 🐛 Troubleshooting

### "GROQ_API_KEY not set"
```bash
export GROQ_API_KEY="your_key"
# or
codevault auth set your_key
```

### "Merge conflicts detected"
```bash
# Check details
codevault check-conflicts file.py

# Auto-resolve
codevault auto-merge file.py --strategy ai
```

### "AI failed, added markers"
File now has conflict markers - manually edit and push:
```bash
# Edit file to resolve
nano file.py

# Push resolved version
codevault push file.py -m "Manual merge"
```

## 🤝 Contributing

Issues and pull requests welcome!

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit PR

## 📄 License

MIT License - see LICENSE file

## 🙏 Credits

- **Groq** for fast LLM inference
- **Llama 3** for intelligent code understanding
- Inspired by Git's version control system

## 📞 Support

- 📖 [Full Documentation](https://github.com/yourusername/codevault)
- 🐛 [Issue Tracker](https://github.com/yourusername/codevault/issues)
- 💬 [Discussions](https://github.com/yourusername/codevault/discussions)

---

**Made with ❤️ to make version control intelligent and accessible**

Give it a ⭐ if you find it useful!