moai-adk 0.32.8__py3-none-any.whl → 0.41.2__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-worktree/modules/worktree-management.md

@@ -1,782 +0,0 @@
-# Worktree Management Module
-
-Purpose: Core architecture and management patterns for Git worktree operations including registry management, lifecycle control, and resource optimization.
-
-Version: 1.0.0
-Last Updated: 2025-11-29
-
----
-
-## Quick Reference (30 seconds)
-
-Core Components:
-- Registry - Central worktree database and metadata tracking
-- Manager - Core operations (create, sync, remove, cleanup)
-- Models - Data structures for worktree metadata
-- Lifecycle - Worktree creation, maintenance, and removal patterns
-
-Key Patterns:
-- Automatic registration and tracking
-- Atomic operations with rollback
-- Resource optimization and cleanup
-- Conflict detection and resolution
-
----
-
-## Registry Architecture
-
-### Worktree Registry Structure
-
-The registry is the central database that tracks all worktrees and their metadata.
-
-Registry File: `~/.worktrees/{PROJECT_NAME}/.moai-worktree-registry.json`
-
-Complete Registry Schema:
-```json
-{
- "version": "1.0.0",
- "created_at": "2025-11-29T20:00:00Z",
- "last_updated": "2025-11-29T22:00:00Z",
- "config": {
- "worktree_root": "/Users/goos/worktrees/MoAI-ADK",
- "auto_sync": true,
- "cleanup_merged": true,
- "default_base": "main",
- "sync_strategy": "merge",
- "registry_type": "local",
- "max_worktrees": 50
- },
- "worktrees": {
- "SPEC-001": {
- "id": "SPEC-001",
- "description": "User Authentication System",
- "path": "/Users/goos/worktrees/MoAI-ADK/SPEC-001",
- "branch": "feature/SPEC-001-user-auth",
- "base_branch": "main",
- "status": "active",
- "created_at": "2025-11-29T20:00:00Z",
- "last_accessed": "2025-11-29T22:00:00Z",
- "last_sync": "2025-11-29T22:30:00Z",
- "git_info": {
- "commits_ahead": 5,
- "commits_behind": 0,
- "uncommitted_changes": true,
- "branch_status": "ahead",
- "merge_conflicts": false
- },
- "metadata": {
- "template": "backend",
- "developer": "alice",
- "priority": "high",
- "estimated_size": "125MB",
- "tags": ["authentication", "security", "api"]
- },
- "operations": {
- "total_syncs": 15,
- "total_conflicts": 2,
- "last_operation": "sync",
- "last_operation_status": "success"
- }
- }
- },
- "statistics": {
- "total_worktrees": 3,
- "active_worktrees": 2,
- "merged_worktrees": 1,
- "total_disk_usage": "500MB",
- "last_cleanup": "2025-11-28T10:00:00Z"
- }
-}
-```
-
-### Registry Management Patterns
-
-Atomic Registry Operations:
-```python
-class RegistryManager:
- def update_worktree(self, spec_id: str, updates: dict) -> bool:
- """Atomic registry update with backup and rollback."""
-
- # 1. Create backup
- backup_path = self.registry_path.with_suffix('.backup.json')
- shutil.copy2(self.registry_path, backup_path)
-
- try:
- # 2. Load current registry
- registry = self.load_registry()
-
- # 3. Validate updates
- self.validate_worktree_updates(registry, spec_id, updates)
-
- # 4. Apply updates atomically
- registry['worktrees'][spec_id].update(updates)
- registry['last_updated'] = datetime.utcnow().isoformat()
-
- # 5. Write to temporary file first
- temp_path = self.registry_path.with_suffix('.tmp.json')
- self.save_registry(registry, temp_path)
-
- # 6. Atomic rename
- temp_path.replace(self.registry_path)
-
- # 7. Cleanup backup
- backup_path.unlink()
-
- return True
-
- except Exception as e:
- # Rollback on failure
- if backup_path.exists():
- backup_path.replace(self.registry_path)
- raise RegistryError(f"Failed to update registry: {e}")
-```
-
-Concurrent Access Protection:
-```python
-import fcntl
-import time
-
-class ConcurrentRegistryManager:
- def with_registry_lock(self, operation_func):
- """Execute operation with file-based locking."""
-
- lock_path = self.registry_path.with_suffix('.lock')
-
- with open(lock_path, 'w') as lock_file:
- # Acquire exclusive lock (with timeout)
- try:
- fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
- except IOError:
- # Lock held by another process, wait with timeout
- for _ in range(30): # 30 second timeout
- time.sleep(1)
- try:
- fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
- break
- except IOError:
- continue
- else:
- raise RegistryError("Registry lock timeout")
-
- try:
- # Execute operation with lock held
- return operation_func()
- finally:
- # Release lock
- fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
- lock_path.unlink()
-```
-
-### Registry Validation and Integrity
-
-Schema Validation:
-```python
-import jsonschema
-from typing import Dict, Any
-
-class RegistryValidator:
- REGISTRY_SCHEMA = {
- "type": "object",
- "required": ["version", "created_at", "last_updated", "config", "worktrees"],
- "properties": {
- "version": {"type": "string"},
- "config": {
- "type": "object",
- "required": ["worktree_root", "default_base"],
- "properties": {
- "worktree_root": {"type": "string"},
- "auto_sync": {"type": "boolean"},
- "cleanup_merged": {"type": "boolean"},
- "default_base": {"type": "string"}
- }
- },
- "worktrees": {
- "type": "object",
- "patternProperties": {
- "^SPEC-[0-9]+$": {
- "type": "object",
- "required": ["id", "path", "branch", "status", "created_at"],
- "properties": {
- "id": {"type": "string"},
- "path": {"type": "string"},
- "branch": {"type": "string"},
- "status": {"enum": ["active", "merged", "stale", "error"]},
- "created_at": {"type": "string", "format": "date-time"}
- }
- }
- }
- }
- }
- }
-
- def validate_registry(self, registry: Dict[str, Any]) -> bool:
- """Validate registry schema and integrity."""
-
- try:
- jsonschema.validate(registry, self.REGISTRY_SCHEMA)
- except jsonschema.ValidationError as e:
- raise RegistryError(f"Registry schema validation failed: {e}")
-
- # Additional integrity checks
- self._validate_worktree_paths(registry)
- self._validate_unique_paths(registry)
- self._validate_git_repositories(registry)
-
- return True
-
- def _validate_worktree_paths(self, registry: Dict[str, Any]) -> None:
- """Validate that all worktree paths exist and are Git repositories."""
-
- for spec_id, worktree in registry['worktrees'].items():
- path = Path(worktree['path'])
-
- if not path.exists():
- raise RegistryError(f"Worktree path does not exist: {path}")
-
- if not (path / '.git').exists():
- raise RegistryError(f"Worktree is not a Git repository: {path}")
-
- def _validate_unique_paths(self, registry: Dict[str, Any]) -> None:
- """Ensure no duplicate worktree paths."""
-
- paths = [wt['path'] for wt in registry['worktrees'].values()]
- duplicates = set([p for p in paths if paths.count(p) > 1])
-
- if duplicates:
- raise RegistryError(f"Duplicate worktree paths detected: {duplicates}")
-```
-
----
-
-## Manager Architecture
-
-### WorktreeManager Core Operations
-
-Manager Class Structure:
-```python
-class WorktreeManager:
- def __init__(self, repo_path: Path, worktree_root: Path):
- self.repo_path = Path(repo_path).resolve()
- self.worktree_root = Path(worktree_root).resolve()
- self.registry = RegistryManager(self.worktree_root)
- self.git_manager = GitManager(self.repo_path)
-
- # Core Operations
- def create_worktree(self, spec_id: str, description: str = "", options) -> WorktreeInfo
- def sync_worktree(self, spec_id: str, options) -> SyncResult
- def remove_worktree(self, spec_id: str, options) -> RemoveResult
- def switch_worktree(self, spec_id: str, options) -> SwitchResult
- def cleanup_worktrees(self, options) -> CleanupResult
-
- # Query Operations
- def list_worktrees(self, filters) -> List[WorktreeInfo]
- def get_worktree(self, spec_id: str) -> Optional[WorktreeInfo]
- def get_current_worktree(self) -> Optional[WorktreeInfo]
- def get_worktree_status(self, spec_id: str) -> WorktreeStatus
-```
-
-### Worktree Creation Patterns
-
-Complete Creation Workflow:
-```python
-def create_worktree(self, spec_id: str, description: str = "", options) -> WorktreeInfo:
- """Create a new worktree with comprehensive validation and setup."""
-
- # 1. Validate input
- self._validate_spec_id(spec_id)
- self._validate_worktree_doesnt_exist(spec_id)
-
- # 2. Determine configuration
- branch = options.get('branch') or self._generate_branch_name(spec_id, description)
- base_branch = options.get('base') or self.config.default_base
- template = options.get('template')
-
- # 3. Create worktree path
- worktree_path = self.worktree_root / spec_id
-
- try:
- # 4. Create Git worktree
- self.git_manager.create_worktree(
- worktree_path=worktree_path,
- branch=branch,
- base_branch=base_branch,
- force=options.get('force', False)
- )
-
- # 5. Apply template if specified
- if template:
- self._apply_template(worktree_path, template)
-
- # 6. Register worktree
- worktree_info = WorktreeInfo(
- id=spec_id,
- description=description,
- path=str(worktree_path),
- branch=branch,
- base_branch=base_branch,
- status=WorktreeStatus.ACTIVE,
- created_at=datetime.utcnow(),
- metadata=options.get('metadata', {})
- )
-
- self.registry.register_worktree(worktree_info)
-
- # 7. Post-creation hooks
- self._run_creation_hooks(worktree_info)
-
- return worktree_info
-
- except Exception as e:
- # Cleanup on failure
- if worktree_path.exists():
- shutil.rmtree(worktree_path, ignore_errors=True)
- raise WorktreeCreationError(f"Failed to create worktree {spec_id}: {e}")
-
-def _apply_template(self, worktree_path: Path, template_name: str) -> None:
- """Apply worktree template for initial setup."""
- import shlex
-
- template_config = self._load_template_config(template_name)
-
- # Execute setup commands safely (shell=False to prevent command injection CWE-78)
- for command in template_config.get('setup_commands', []):
- # Parse command string into list for safe execution
- cmd_list = shlex.split(command) if isinstance(command, str) else command
- result = subprocess.run(
- cmd_list,
- cwd=worktree_path,
- capture_output=True,
- text=True
- )
-
- if result.returncode != 0:
- raise TemplateError(f"Template command failed: {command}\n{result.stderr}")
-
- # Create template files
- for file_path, content in template_config.get('files', {}).items():
- full_path = worktree_path / file_path
- full_path.parent.mkdir(parents=True, exist_ok=True)
- full_path.write_text(content)
-
- # Set environment variables
- for key, value in template_config.get('env_vars', {}).items():
- env_file = worktree_path / '.env.local'
- with open(env_file, 'a') as f:
- f.write(f"{key}={value}\n")
-```
-
-### Synchronization Patterns
-
-Smart Synchronization Strategy:
-```python
-def sync_worktree(self, spec_id: str, options) -> SyncResult:
- """Synchronize worktree with base branch using intelligent strategies."""
-
- worktree = self.get_worktree(spec_id)
- if not worktree:
- raise WorktreeNotFoundError(f"Worktree not found: {spec_id}")
-
- sync_strategy = options.get('strategy', self.config.sync_strategy)
-
- try:
- # 1. Check for uncommitted changes
- if self._has_uncommitted_changes(worktree.path) and not options.get('force'):
- raise UncommittedChangesError("Worktree has uncommitted changes")
-
- # 2. Fetch latest changes
- self.git_manager.fetch_updates(worktree.path)
-
- # 3. Analyze synchronization needs
- sync_analysis = self._analyze_sync_needs(worktree)
-
- if not sync_analysis.needs_sync:
- return SyncResult(skipped=True, reason="Already up to date")
-
- # 4. Execute synchronization based on strategy
- if sync_strategy == "merge":
- result = self._merge_sync(worktree, sync_analysis, options)
- elif sync_strategy == "rebase":
- result = self._rebase_sync(worktree, sync_analysis, options)
- elif sync_strategy == "squash":
- result = self._squash_sync(worktree, sync_analysis, options)
- else:
- raise ValueError(f"Unknown sync strategy: {sync_strategy}")
-
- # 5. Update registry
- self._update_sync_timestamp(spec_id)
-
- # 6. Post-sync hooks
- self._run_sync_hooks(worktree, result)
-
- return result
-
- except Exception as e:
- self._update_sync_timestamp(spec_id, status="error")
- raise SynchronizationError(f"Sync failed for {spec_id}: {e}")
-
-def _merge_sync(self, worktree: WorktreeInfo, analysis: SyncAnalysis, options: dict) -> SyncResult:
- """Perform merge-based synchronization."""
-
- worktree_path = Path(worktree.path)
-
- # Check for conflicts
- if analysis.has_conflicts:
- if options.get('auto_resolve'):
- self._auto_resolve_conflicts(worktree_path, analysis.conflicts)
- elif options.get('interactive'):
- self._interactive_resolve_conflicts(worktree_path, analysis.conflicts)
- else:
- raise MergeConflictError(f"Merge conflicts detected in {worktree.id}")
-
- # Perform merge
- merge_result = self.git_manager.merge_branch(
- worktree_path=worktree_path,
- source_branch=worktree.base_branch,
- target_branch=worktree.branch,
- strategy=options.get('merge_strategy', 'recursive')
- )
-
- return SyncResult(
- strategy="merge",
- files_changed=merge_result.files_changed,
- conflicts_resolved=len(analysis.conflicts) if analysis.has_conflicts else 0,
- commits_merged=analysis.commits_behind
- )
-```
-
-### Cleanup and Optimization Patterns
-
-Intelligent Cleanup Strategy:
-```python
-def cleanup_worktrees(self, options) -> CleanupResult:
- """Perform intelligent cleanup of worktrees based on various criteria."""
-
- cleanup_candidates = []
-
- # 1. Find merged worktrees
- if options.get('merged_only', False):
- merged_worktrees = self._find_merged_worktrees()
- cleanup_candidates.extend(merged_worktrees)
-
- # 2. Find stale worktrees
- if options.get('stale', False):
- stale_threshold = options.get('days', 30)
- stale_worktrees = self._find_stale_worktrees(stale_threshold)
- cleanup_candidates.extend(stale_worktrees)
-
- # 3. Find large worktrees
- if options.get('large_only', False):
- size_threshold = options.get('size_threshold', '1GB')
- large_worktrees = self._find_large_worktrees(size_threshold)
- cleanup_candidates.extend(large_worktrees)
-
- # 4. Remove duplicates and sort by priority
- cleanup_candidates = list(set(cleanup_candidates))
- cleanup_candidates.sort(key=lambda w: self._cleanup_priority(w), reverse=True)
-
- # 5. Interactive selection if requested
- if options.get('interactive'):
- cleanup_candidates = self._interactive_cleanup_selection(cleanup_candidates)
-
- # 6. Perform cleanup
- removed_count = 0
- total_size_freed = 0
-
- for worktree in cleanup_candidates:
- try:
- result = self.remove_worktree(
- worktree.id,
- backup=options.get('backup', False),
- force=options.get('force', False)
- )
-
- removed_count += 1
- total_size_freed += result.size_freed
-
- except Exception as e:
- logger.warning(f"Failed to remove worktree {worktree.id}: {e}")
-
- return CleanupResult(
- worktrees_removed=removed_count,
- size_freed=total_size_freed,
- candidates=len(cleanup_candidates)
- )
-
-def _find_merged_worktrees(self) -> List[WorktreeInfo]:
- """Find worktrees whose branches have been merged to base."""
-
- merged_worktrees = []
-
- for worktree in self.list_worktrees(status='active'):
- if self.git_manager.is_branch_merged(
- branch=worktree.branch,
- into=worktree.base_branch,
- repo_path=worktree.path
- ):
- merged_worktrees.append(worktree)
-
- return merged_worktrees
-
-def _find_stale_worktrees(self, days_threshold: int) -> List[WorktreeInfo]:
- """Find worktrees not accessed in specified days."""
-
- threshold_date = datetime.utcnow() - timedelta(days=days_threshold)
- stale_worktrees = []
-
- for worktree in self.list_worktrees():
- last_accessed = datetime.fromisoformat(worktree.last_accessed)
- if last_accessed < threshold_date:
- stale_worktrees.append(worktree)
-
- return stale_worktrees
-```
-
----
-
-## Resource Optimization
-
-### Disk Space Management
-
-Disk Usage Analysis:
-```python
-def analyze_disk_usage(self) -> DiskUsageReport:
- """Analyze disk usage of all worktrees."""
-
- total_size = 0
- worktree_sizes = {}
-
- for worktree in self.list_worktrees():
- size = self._calculate_worktree_size(worktree.path)
- worktree_sizes[worktree.id] = size
- total_size += size
-
- # Find size anomalies
- large_worktrees = [
- (wid, size) for wid, size in worktree_sizes.items()
- if size > self._get_size_threshold(wid)
- ]
-
- return DiskUsageReport(
- total_size=total_size,
- worktree_sizes=worktree_sizes,
- large_worktrees=large_worktrees,
- optimization_suggestions=self._generate_optimization_suggestions(worktree_sizes)
- )
-
-def _calculate_worktree_size(self, worktree_path: str) -> int:
- """Calculate total size of worktree in bytes."""
-
- total_size = 0
- worktree_path = Path(worktree_path)
-
- for file_path in worktree_path.rglob('*'):
- if file_path.is_file():
- total_size += file_path.stat().st_size
-
- return total_size
-
-def optimize_disk_usage(self, aggressive: bool = False) -> OptimizationResult:
- """Optimize disk usage across worktrees."""
-
- optimizations = []
- total_freed = 0
-
- # 1. Remove unnecessary files
- for worktree in self.list_worktrees():
- worktree_path = Path(worktree.path)
-
- # Remove build artifacts
- build_artifacts = self._find_build_artifacts(worktree_path)
- if build_artifacts:
- freed = self._remove_files(build_artifacts)
- optimizations.append(f"Removed {len(build_artifacts)} build artifacts from {worktree.id}")
- total_freed += freed
-
- # Clean Git garbage
- if aggressive:
- git_freed = self._git_gc(worktree_path)
- optimizations.append(f"Git GC freed {git_freed} from {worktree.id}")
- total_freed += git_freed
-
- # 2. Compress old worktrees
- if aggressive:
- old_worktrees = self._find_old_worktrees(days=90)
- for worktree in old_worktrees:
- compressed = self._compress_worktree(worktree)
- if compressed:
- optimizations.append(f"Compressed {worktree.id}")
- total_freed += compressed
-
- return OptimizationResult(
- optimizations=optimizations,
- total_freed=total_freed
- )
-```
-
-### Memory and Performance Optimization
-
-Memory-Efficient Operations:
-```python
-class MemoryOptimizedManager:
- def __init__(self, repo_path: Path, worktree_root: Path):
- self.repo_path = repo_path
- self.worktree_root = worktree_root
- self._registry_cache = None
- self._cache_timestamp = None
- self._cache_ttl = timedelta(minutes=5)
-
- @property
- def registry(self) -> Dict[str, Any]:
- """Lazy-loaded registry with caching."""
-
- now = datetime.utcnow()
-
- if (self._registry_cache is None or
- self._cache_timestamp is None or
- now - self._cache_timestamp > self._cache_ttl):
-
- self._registry_cache = self._load_registry()
- self._cache_timestamp = now
-
- return self._registry_cache
-
- def list_worktrees_streaming(self, filters: Dict[str, Any] = None) -> Iterator[WorktreeInfo]:
- """Stream worktrees without loading entire registry."""
-
- registry_path = self.worktree_root / ".moai-worktree-registry.json"
-
- if not registry_path.exists():
- return
-
- # Stream JSON parsing for large registries
- import ijson
-
- with open(registry_path, 'rb') as f:
- worktrees = ijson.items(f, 'worktrees.item')
-
- for worktree_data in worktrees:
- worktree = WorktreeInfo.from_dict(worktree_data)
-
- if self._matches_filters(worktree, filters):
- yield worktree
-```
-
----
-
-## Error Handling and Recovery
-
-### Comprehensive Error Handling
-
-Error Hierarchy and Recovery:
-```python
-class WorktreeError(Exception):
- """Base class for worktree-related errors."""
- pass
-
-class WorktreeCreationError(WorktreeError):
- """Errors during worktree creation."""
- def __init__(self, message: str, partial_worktree: Optional[Path] = None):
- super().__init__(message)
- self.partial_worktree = partial_worktree
-
-class SynchronizationError(WorktreeError):
- """Errors during synchronization."""
- def __init__(self, message: str, sync_state: Optional[Dict] = None):
- super().__init__(message)
- self.sync_state = sync_state
-
-class RecoveryManager:
- def recover_from_creation_failure(self, error: WorktreeCreationError) -> RecoveryResult:
- """Recover from worktree creation failure."""
-
- if error.partial_worktree:
- # Clean up partial worktree
- if error.partial_worktree.exists():
- shutil.rmtree(error.partial_worktree, ignore_errors=True)
-
- # Remove any registry entries
- self.registry.remove_worktree(error.spec_id, ignore_missing=True)
-
- return RecoveryResult(success=True, message="Cleanup completed")
-
- def recover_from_sync_failure(self, error: SynchronizationError) -> RecoveryResult:
- """Recover from synchronization failure."""
-
- worktree_id = error.worktree_id
-
- # Reset worktree to last known good state
- if error.sync_state and 'backup_ref' in error.sync_state:
- self.git_manager.reset_to_ref(
- worktree_id=worktree_id,
- ref=error.sync_state['backup_ref']
- )
-
- # Mark worktree as needing manual intervention
- self.registry.update_worktree(worktree_id, {
- 'status': 'error',
- 'last_error': str(error),
- 'needs_manual_intervention': True
- })
-
- return RecoveryResult(
- success=True,
- message=f"Worktree {worktree_id} reset to safe state"
- )
-```
-
----
-
-## Monitoring and Analytics
-
-### Worktree Analytics
-
-Usage Analytics:
-```python
-class WorktreeAnalytics:
- def generate_usage_report(self, period: timedelta = timedelta(days=30)) -> UsageReport:
- """Generate comprehensive usage report."""
-
- end_date = datetime.utcnow()
- start_date = end_date - period
-
- worktrees = self.list_worktrees()
-
- # Calculate metrics
- metrics = {
- 'total_worktrees_created': len([
- w for w in worktrees
- if datetime.fromisoformat(w.created_at) >= start_date
- ]),
- 'average_sync_frequency': self._calculate_average_sync_frequency(worktrees, period),
- 'most_active_worktree': self._find_most_active_worktree(worktrees, period),
- 'conflict_rate': self._calculate_conflict_rate(worktrees, period),
- 'storage_growth': self._calculate_storage_growth(worktrees, period)
- }
-
- # Generate recommendations
- recommendations = self._generate_recommendations(metrics, worktrees)
-
- return UsageReport(
- period=period,
- metrics=metrics,
- recommendations=recommendations,
- generated_at=end_date
- )
-
- def _calculate_average_sync_frequency(self, worktrees: List[WorktreeInfo], period: timedelta) -> float:
- """Calculate average sync frequency per worktree."""
-
- if not worktrees:
- return 0.0
-
- total_syncs = sum(w.operations.total_syncs for w in worktrees)
- days_in_period = period.days
-
- return total_syncs / (len(worktrees) * days_in_period)
-```
-
----
-
-Version: 1.0.0
-Last Updated: 2025-11-29
-Module: Core worktree management architecture with registry, lifecycle, and optimization patterns