# Git Integration Architecture
## Overview
This document describes the consolidated git integration architecture for mcp_gas, which eliminates code duplication across all file operation tools.
## Problem Statement
Previously, each tool (edit, aider, mv, cp, rm, etc) would need to duplicate ~200-300 lines of git integration logic:
- Path resolution
- Feature branch management
- Local commits
- Remote sync
- Hook validation
- Atomic rollback
**Total duplication**: ~1,700 lines across 8 tools
## Solution: Layered Architecture
```
┌─────────────────────────────────────────────────────┐
│ Layer 5: Tools (Thin Wrappers - 50-100 lines each)│
│ EditTool, AiderTool, MvTool, CpTool, RmTool, Cat │
└──────────────────┬──────────────────────────────────┘
│ delegates to
┌──────────────────▼──────────────────────────────────┐
│ Layer 4: GitOperationManager │
│ - Orchestrates entire git workflow │
│ - Path resolution → branch → commit → sync → roll │
└──────────────────┬──────────────────────────────────┘
│ uses
┌──────────┴──────────┐
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ Layer 3: │ │ Layer 3: │
│ Operation │ │ Sync │
│ Strategies │ │ Strategies │
│ │ │ │
│ - Edit │ │ - Simple │
│ - Aider │ │ - Bidirectional │
│ - Move │ │ - LocalOnly │
│ - Copy │ │ │
│ - Delete │ │ │
└───────┬────────┘ └────────┬────────┘
│ │
└──────────┬─────────┘
│ uses
┌──────────────────▼──────────────────────────────────┐
│ Layer 2: Core Git Utilities (Already Exist) │
│ - ensureFeatureBranch() │
│ - writeLocalAndValidateWithHooks() │
│ - revertGitCommit() │
│ - hasUncommittedChanges() │
└──────────────────┬──────────────────────────────────┘
│ uses
┌──────────────────▼──────────────────────────────────┐
│ Layer 1: Infrastructure (Already Exists) │
│ - LocalFileManager │
│ - GASClient │
│ - Git commands (execAsync) │
└─────────────────────────────────────────────────────┘
```
## Core Components
### 1. GitOperationManager
**Location**: `src/core/git/GitOperationManager.ts`
**Responsibility**: Central orchestrator for ALL git operations
**Workflow**:
1. Path resolution (considers .git/config.gs breadcrumbs)
2. Feature branch management (auto-create if needed)
3. Pre-operation sync (if bidirectional mode)
4. Operation execution (delegates to strategy)
5. Local commit with hook validation
6. Post-operation sync (push to remote)
7. Atomic rollback on failure
**Usage**:
```typescript
const manager = new GitOperationManager(resolver, factory, client);
await manager.executeWithGit(
new EditOperationStrategy(params),
{ scriptId, files: ['test.gs'], changeReason: 'Fix bug' }
);
```
### 2. GitPathResolver
**Location**: `src/core/git/GitPathResolver.ts`
**Responsibility**: Resolve local git repository paths
**Strategy**:
1. Check for .git/config.gs breadcrumb in GAS
2. Use configured localPath if exists
3. Fall back to LocalFileManager default
**Benefits**:
- Ensures ALL tools use SAME local path
- Consistent with local_sync tool
- Supports polyrepo (nested projects)
**Usage**:
```typescript
const resolver = new GitPathResolver();
const localPath = await resolver.resolve(scriptId, projectPath);
// Returns: ~/gas-repos/project-abc123 or custom path from breadcrumb
```
### 3. Sync Strategies
**Location**: `src/core/git/strategies/`
Three strategies for different sync modes:
#### SimpleSyncStrategy
- **When**: No .git/config.gs breadcrumb
- **Workflow**: Local commit + push (no pull)
- **Use Case**: Default mode for most operations
#### BidirectionalSyncStrategy
- **When**: .git/config.gs breadcrumb exists
- **Workflow**: Pull → merge → push (like local_sync)
- **Use Case**: Coordinated with local_sync tool
#### LocalOnlySyncStrategy
- **When**: Explicitly requested
- **Workflow**: No remote sync at all
- **Use Case**: Testing, offline development
### 4. FileOperationStrategy Interface
**Location**: `src/core/git/operations/FileOperationStrategy.ts`
**Responsibility**: Define file operation behavior
**Methods**:
- `execute()` - Perform the file operation
- `rollback()` - Revert the operation
- `getAffectedFiles()` - List of modified files
- `getModifiedContent()` - Content for git commit
- `getType()` - Operation type (for commit messages)
**Implementations** (to be created):
- EditOperationStrategy
- AiderOperationStrategy
- MoveOperationStrategy
- CopyOperationStrategy
- DeleteOperationStrategy
## File Structure
```
src/
├── core/
│ └── git/
│ ├── GitOperationManager.ts # ✅ Core orchestrator (400 lines)
│ ├── GitPathResolver.ts # ✅ Path resolution (200 lines)
│ ├── SyncStrategyFactory.ts # ✅ Factory (50 lines)
│ ├── strategies/
│ │ ├── SyncStrategy.ts # ✅ Interface
│ │ ├── SimpleSyncStrategy.ts # ✅ Simple mode (80 lines)
│ │ ├── BidirectionalSyncStrategy.ts # ✅ Bidirectional (150 lines)
│ │ └── LocalOnlySyncStrategy.ts # ✅ Local-only (50 lines)
│ └── operations/
│ ├── FileOperationStrategy.ts # ✅ Interface
│ ├── EditOperationStrategy.ts # 🔜 TODO
│ ├── AiderOperationStrategy.ts # 🔜 TODO
│ ├── MoveOperationStrategy.ts # 🔜 TODO
│ ├── CopyOperationStrategy.ts # 🔜 TODO
│ └── DeleteOperationStrategy.ts # 🔜 TODO
├── utils/
│ ├── gitAutoCommit.ts # ✅ Already exists
│ └── hookIntegration.ts # ✅ Already exists
└── tools/
├── edit.ts # 🔜 TODO: Refactor to 60 lines
├── aider.ts # 🔜 TODO: Refactor to 60 lines
├── filesystem/
│ ├── WriteTool.ts # 🔜 TODO: Refactor
│ ├── MvTool.ts # 🔜 TODO: Refactor to 70 lines
│ ├── CpTool.ts # 🔜 TODO: Refactor to 70 lines
│ └── RmTool.ts # 🔜 TODO: Refactor to 60 lines
└── gitSync.ts # 🔜 TODO: Refactor to use strategies
```
## Benefits
### Code Reuse
- **Before**: ~1,700 lines of duplicated git logic
- **After**: ~400 lines in core + thin wrappers
- **Savings**: 76% reduction
### Maintainability
- **One place** to fix git bugs
- **One place** to add features (e.g., new sync mode)
- **One place** to improve error handling
### Testability
```typescript
// Mock GitOperationManager for tool tests
describe('EditTool', () => {
it('should delegate to git manager', async () => {
const mockManager = createMockGitManager();
tool.gitManager = mockManager;
await tool.execute({...});
expect(mockManager.executeWithGit).toHaveBeenCalled();
});
});
```
### Extensibility
```typescript
// Adding new tool is trivial
export class BatchEditTool extends BaseTool {
async execute(params: BatchEditParams) {
const operation = new BatchEditOperationStrategy(params);
return await this.gitManager.executeWithGit(operation, {...});
}
}
```
## Implementation Status
### ✅ Phase 1: Core Infrastructure (Completed)
- [x] GitOperationManager (with critical fixes)
- [x] GitPathResolver (with accessToken support)
- [x] SyncStrategy interface
- [x] SimpleSyncStrategy
- [x] ~~BidirectionalSyncStrategy~~ (removed - too complex/risky)
- [x] LocalOnlySyncStrategy
- [x] SyncStrategyFactory (updated for 2 strategies)
- [x] FileOperationStrategy interface
### ✅ Phase 2: Operation Strategies (Completed)
- [x] EditOperationStrategy (268 lines)
- [x] AiderOperationStrategy (248 lines)
- [x] MoveOperationStrategy (190 lines)
- [x] CopyOperationStrategy (194 lines)
- [x] DeleteOperationStrategy (148 lines)
### 🔜 Phase 3: Tool Refactoring (Next)
- [ ] Refactor EditTool to use GitOperationManager + EditOperationStrategy
- [ ] Refactor AiderTool to use GitOperationManager + AiderOperationStrategy
- [ ] Refactor WriteTool to use GitOperationManager (optional for consistency)
- [ ] Refactor MvTool to use GitOperationManager + MoveOperationStrategy
- [ ] Refactor CpTool to use GitOperationManager + CopyOperationStrategy
- [ ] Refactor RmTool to use GitOperationManager + DeleteOperationStrategy
- [ ] Add git integration to CatTool (sync variant with changeReason)
### 🔜 Phase 4: Testing (After Phase 3)
- [ ] Unit tests for GitOperationManager
- [ ] Unit tests for each operation strategy
- [ ] Unit tests for each sync strategy
- [ ] Integration tests for full workflow
- [ ] Performance benchmarks
- [ ] End-to-end tests with local_sync coordination
## Phase 1 & 2 Summary (Completed)
### Code Created
- **Core Infrastructure**: ~1,100 lines
- GitOperationManager: 314 lines
- GitPathResolver: 206 lines
- SyncStrategyFactory: 43 lines
- SyncStrategy interface: 50 lines
- SimpleSyncStrategy: 88 lines
- LocalOnlySyncStrategy: 52 lines
- **Operation Strategies**: ~1,048 lines
- FileOperationStrategy interface: 120 lines
- EditOperationStrategy: 268 lines
- AiderOperationStrategy: 248 lines
- MoveOperationStrategy: 190 lines
- CopyOperationStrategy: 194 lines
- DeleteOperationStrategy: 148 lines
- **Total New Code**: ~2,148 lines
### Critical Fixes Applied
1. Missing closing brace in GitOperationManager (line 191)
2. Wrong property name: `gitStatus.isNew` → `gitStatus.isNewRepo`
3. Created missing SyncStrategy.ts interface file
4. Fixed GASFile type mismatch in SimpleSyncStrategy
5. Added accessToken null check in GitPathResolver
### Architecture Decisions
1. **Removed BidirectionalSyncStrategy**: Too risky with destructive git operations
- Users should call local_sync explicitly for bidirectional workflows
- Keeps architecture simple and predictable
2. **Two Sync Modes Only**:
- Simple: Default mode, local commit + push (no pull)
- LocalOnly: For testing/offline, no remote sync
3. **Atomic Rollback**: All strategies implement rollback() for failure recovery
4. **Token Efficiency**: Edit/Aider strategies maintain ~95% token savings
## Next Steps
1. **Phase 3 - Tool Refactoring** (Highest Priority)
- Start with EditTool (most used, highest impact)
- Pattern: Tool delegates to GitOperationManager with operation strategy
- Verify end-to-end: edit → local commit → remote push → local_sync compatible
2. **Testing Strategy**
- Create integration test for EditTool + GitOperationManager
- Verify git commits created correctly
- Verify hook validation works
- Verify atomic rollback on failure
- Test coordination with local_sync
3. **Performance Benchmarks**
- Measure overhead of GitOperationManager workflow
- Target: < 500ms total overhead
- Optimize if needed
4. **Documentation**
- Update tool documentation with git integration details
- Add examples of changeReason parameter
- Document coordination with local_sync
## Coordination with local_sync
The new architecture ensures coordination with local_sync:
1. **Same Local Path**: GitPathResolver checks breadcrumbs (like local_sync)
2. **Same Git Repo**: All tools commit to same local repository
3. **Compatible Workflows**:
- write/edit → creates local commits
- local_sync → pulls/merges/pushes these commits
4. **No Conflicts**: Both use git merge for conflict resolution
## Migration Strategy
Tools will be migrated incrementally:
1. Edit/Aider first (high priority)
2. Mv/Cp/Rm next (file operations)
3. Cat sync variant
4. WriteTool refactor (optional, for consistency)
Old code paths kept as fallback until all testing complete.
## Performance
Expected overhead: < 500ms per operation
- Path resolution: ~10ms
- Feature branch check: ~50ms
- Hook validation: ~100ms
- Commit creation: ~200ms
- Sync operations: ~100ms
Total: ~460ms (within target)
