OpenCode Shadow Git

Sistema de checkpoints automáticos usando Shadow Git Repository, similar ao Cursor

🎯 O que é?

Uma biblioteca TypeScript que implementa checkpoints automáticos para seus projetos usando um Shadow Git Repository. Permite criar pontos de restauração sem interferir com o Git principal do projeto.

Features

• ✅ Checkpoints automáticos em cada edição
• ✅ Restaurar para qualquer ponto no tempo
• ✅ Não interfere com o Git do projeto
• ✅ Cleanup automático de checkpoints antigos
• ✅ API TypeScript completa e tipada
• ✅ Zero runtime dependencies
• ✅ Performance otimizada (<200ms por operação)

🚀 Quick Start

# Install
npm install opencode-shadowgit

# Use in your code
import { ShadowGitManager } from 'opencode-shadowgit';

const manager = new ShadowGitManager('/path/to/your/project');
await manager.init();

// Create checkpoint
const checkpoint = await manager.createCheckpoint('manual', 'my-work', 'Completed feature X');

// List checkpoints
const checkpoints = await manager.listCheckpoints();

// Restore
await manager.restoreCheckpoint(checkpoint.id);

→ Full API Documentation

🏗️ How it Works

Shadow Repository Pattern

your-project/
├── .git/                    # Your main Git (untouched)
├── .opencode/
│   └── checkpoints/         # Shadow Git Repository
│       ├── .git/            # Separate Git for checkpoints
│       ├── checkpoints.json # Checkpoint metadata
│       └── .gitignore       # Excluded patterns
└── src/                     # Your source code

Key concept: The shadow Git repo uses core.worktree config to track files from your project root without interfering with your main Git repository.

📦 Features

Core Functionality

• ShadowGitManager: Main class for checkpoint management

  • init() - Initialize shadow repository
  • createCheckpoint() - Create new checkpoint
  • listCheckpoints() - List all checkpoints
  • restoreCheckpoint() - Restore to a checkpoint
  • getDiff() - Show differences
  • cleanup() - Remove old checkpoints
  • getStatus() - Get system status

• Debouncer: Smart debouncing to prevent excessive commits

• MetadataStore: Persistent checkpoint metadata storage

• TypeScript Types: Full type definitions included

⚙️ Configuration

Default configuration with sensible defaults:

const manager = new ShadowGitManager('/path/to/project', {
  enabled: true,
  
  auto: {
    enabled: true,
    debounceMs: 5000,          // Wait 5s after last edit
    onEvents: ['file.edited'],
    excludePatterns: [
      'node_modules/**',
      '.git/**',
      '*.log'
    ]
  },
  
  retention: {
    maxAutoCheckpoints: 50,    // Keep last 50 auto checkpoints
    maxManualCheckpoints: 100, // Keep up to 100 manual checkpoints
    maxAgeDays: 7,             // Delete auto checkpoints older than 7 days
    maxTotalSizeMB: 500,       // Max 500 MB total storage
    preserveNamed: true        // Always keep manual checkpoints
  },
  
  performance: {
    enableCompression: true,   // Git compression
    enableDelta: true,         // Delta compression
    maxConcurrentOps: 1        // Sequential operations
  }
});

🧪 Testing

# Build the project
npm run build

# Run proof of concept
npx tsx src/poc.ts

# Run full example
node dist/example.js

Tests included:

• ✓ Shadow repository initialization
• ✓ Checkpoint creation (auto, manual, emergency)
• ✓ Checkpoint listing
• ✓ Checkpoint restoration
• ✓ Diff generation
• ✓ Cleanup algorithm
• ✓ Status reporting

📈 Performance

Benchmarks

Init shadow repo:      ~50ms
Create checkpoint:     ~100ms
List checkpoints:      ~5ms
Restore checkpoint:    ~150ms
Cleanup:               ~300ms (with git gc)

Optimizations

• Debouncing: Groups rapid edits (5s default)
• Git Compression: Level 9 (maximum)
• Delta Compression: Stores only changes
• Auto-cleanup: Removes old checkpoints automatically
• Efficient metadata: JSON-based persistence

🔄 Comparação com Cursor

| Feature | Cursor | OpenCode Plugin | Status | |---------|--------|-----------------|--------| | Auto-checkpoints | ✅ | ✅ | Implementado | | Manual checkpoints | ✅ | ✅ | Implementado | | Restore com preview | ✅ | ✅ | Implementado | | Cleanup automático | ✅ | ✅ | Implementado | | UI visual | ✅ | ⚠️ CLI only | Futuro | | Timeline view | ✅ | ❌ | Planejado | | Diff viewer | ✅ | ⚠️ Text only | Futuro |

📚 Documentation

• USAGE.md - Complete API documentation
• SPEC.md - Technical specification
• VIABILITY.md - Feasibility analysis
• IMPLEMENTATION.md - Implementation summary
• DONE.md - Project completion report

🛣️ Roadmap

v1.0 (MVP) - ✅ Complete

• [x] Shadow repository setup
• [x] Checkpoint creation (auto, manual, emergency)
• [x] List and restore checkpoints
• [x] Diff generation
• [x] Cleanup algorithm
• [x] Debouncing
• [x] TypeScript types
• [x] Documentation

v1.1 (Future)

• [ ] OpenCode plugin integration
• [ ] Custom tools for OpenCode
• [ ] CLI commands
• [ ] Visual UI in TUI

v2.0 (Planned)

• [ ] Timeline view
• [ ] Branch-aware checkpoints
• [ ] Export/import checkpoints
• [ ] Sync between machines

🤝 Contributing

Contributions are welcome! This is an open source project.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "Add: my feature"
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

📝 License

MIT License - Feel free to use and modify!

🔗 Links

• OpenCode
• OpenCode Docs
• Plugin API

Built for the OpenCode community 🚀