bamboo-coding 0.1.0__py3-none-any.whl

git_utils.py

@@ -0,0 +1,2238 @@
+"""
+Git Operations Utility Module
+
+This module provides a centralized interface for all Git operations used by the application.
+It wraps GitPython library calls with validation, error handling, and caching.
+
+Security:
+- All paths are validated to prevent directory traversal attacks
+- Repository paths must be within configured allowed directories
+- Write operations (branch management) include validation and confirmation
+
+Performance:
+- File tree results are cached with 60-second TTL
+- Diff context is limited to prevent memory issues with large files
+"""
+
+import os
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Any
+from functools import wraps
+
+try:
+    from git import Repo, InvalidGitRepositoryError, GitCommandError, NoSuchPathError
+    from git.exc import BadName
+except ImportError:
+    raise ImportError("GitPython is required. Install with: pip install gitpython")
+
+
+# Custom Exceptions
+class GitPermissionError(Exception):
+    """Raised when Git operation fails due to permission issues."""
+    pass
+
+
+class GitCorruptionError(Exception):
+    """Raised when repository appears to be corrupted."""
+    pass
+
+
+class GitConflictError(Exception):
+    """Raised when a merge operation results in conflicts."""
+    pass
+
+
+# Caching decorator with TTL
+_cache = {}
+
+
+def clear_cache():
+    """Clear all cached data. Useful for testing or when you need fresh data."""
+    global _cache
+    _cache.clear()
+
+
+def ttl_cache(ttl_seconds: int = 60):
+    """Simple TTL cache decorator for expensive operations."""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Create cache key from function name and arguments
+            cache_key = (func.__name__, str(args), str(sorted(kwargs.items())))
+            current_time = time.time()
+            
+            # Check if cached and not expired
+            if cache_key in _cache:
+                result, timestamp = _cache[cache_key]
+                if current_time - timestamp < ttl_seconds:
+                    return result
+            
+            # Call function and cache result
+            result = func(*args, **kwargs)
+            _cache[cache_key] = (result, current_time)
+            return result
+        return wrapper
+    return decorator
+
+
+def _normalize_path(path: str) -> Path:
+    """
+    Normalize and resolve a file path.
+    
+    Args:
+        path: Path string to normalize
+        
+    Returns:
+        Resolved Path object
+        
+    Raises:
+        ValueError: If path contains traversal sequences
+    """
+    if ".." in path:
+        raise ValueError("Path traversal detected")
+    
+    return Path(path).resolve()
+
+
+def is_valid_repository(repo_path: str) -> bool:
+    """
+    Check if a directory is a valid Git repository.
+    
+    Args:
+        repo_path: Path to potential Git repository
+        
+    Returns:
+        True if valid Git repository, False otherwise
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        
+        # Check if directory exists
+        if not normalized_path.exists() or not normalized_path.is_dir():
+            return False
+        
+        # Try to create Repo object
+        Repo(str(normalized_path))
+        return True
+        
+    except (InvalidGitRepositoryError, ValueError, NoSuchPathError):
+        return False
+    except PermissionError:
+        return False
+
+
+@ttl_cache(ttl_seconds=5)
+def get_file_tree(repo_path: str, changed_only: bool = True) -> Dict[str, Any]:
+    """
+    Get hierarchical file structure of the repository.
+    
+    Args:
+        repo_path: Path to Git repository
+        changed_only: If True, return only changed files (modified, staged, added, deleted, untracked).
+                     If False, return all files in repository. Default is True for performance.
+        
+    Returns:
+        Dictionary with file tree structure and file statuses
+        
+    Raises:
+        InvalidGitRepositoryError: If path is not a valid Git repository
+        GitPermissionError: If permission denied accessing repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Get tracked files from git ls-tree
+        tracked_files = []
+        if not changed_only:
+            # Only load all files if explicitly requested
+            try:
+                for item in repo.head.commit.tree.traverse():
+                    if item.type == 'blob':  # Only files, not trees
+                        tracked_files.append({
+                            'path': item.path,
+                            'type': 'file',
+                            'size': item.size,
+                            'status': 'unmodified'
+                        })
+            except (ValueError, BadName):
+                # Empty repository or no commits
+                pass
+        
+        # Get file statuses
+        status_map = {}
+        
+        # First, get staged changes (index vs HEAD)
+        # repo.index.diff('HEAD') compares: index (a) to HEAD (b)
+        try:
+            for item in repo.index.diff('HEAD'):
+                # a_blob = index, b_blob = HEAD
+                if item.a_blob is not None and item.b_blob is None:
+                    # File exists in index but not in HEAD = newly added file
+                    status_map[item.a_path] = 'added'
+                elif item.a_blob is None and item.b_blob is not None:
+                    # File doesn't exist in index but exists in HEAD = staged deleted file
+                    # Use 'deleted-staged' to distinguish from unstaged deleted files
+                    status_map[item.a_path or item.b_path] = 'deleted-staged'
+                elif item.a_blob is not None and item.b_blob is not None:
+                    # File exists in both = modified file
+                    status_map[item.a_path] = 'staged'
+        except (ValueError, BadName):
+            # Empty repository or no commits yet
+            pass
+        
+        # Then, get unstaged changes (working tree vs index)
+        # These take precedence over staged status
+        for item in repo.index.diff(None):
+            if item.change_type == 'M':
+                status_map[item.a_path] = 'modified'
+            elif item.change_type == 'D':
+                # Unstaged deleted file (working tree deleted, still in index)
+                status_map[item.a_path] = 'deleted'
+            elif item.change_type in ('A', 'R', 'T'):
+                # These are unlikely for unstaged changes, but handle them
+                status_map[item.a_path] = 'modified'
+        
+        # Add untracked files
+        for item in repo.untracked_files:
+            status_map[item] = 'untracked'
+        
+        if changed_only:
+            # Only return changed files
+            for path, status in status_map.items():
+                # Try to get file size for tracked files
+                file_size = 0
+                try:
+                    if status != 'untracked':
+                        item = repo.head.commit.tree / path
+                        if item.type == 'blob':
+                            file_size = item.size
+                except (KeyError, ValueError, BadName):
+                    pass
+                
+                tracked_files.append({
+                    'path': path,
+                    'type': 'file',
+                    'size': file_size,
+                    'status': status
+                })
+        else:
+            # Update statuses for all files
+            for file_info in tracked_files:
+                if file_info['path'] in status_map:
+                    file_info['status'] = status_map[file_info['path']]
+            
+            # Add untracked files
+            for untracked in repo.untracked_files:
+                tracked_files.append({
+                    'path': untracked,
+                    'type': 'file',
+                    'size': 0,
+                    'status': 'untracked'
+                })
+        
+        # Build tree structure
+        tree = {
+            'files': tracked_files,
+            'branch': repo.active_branch.name if not repo.head.is_detached else repo.head.commit.hexsha[:7],
+            'is_detached': repo.head.is_detached,
+            'changed_only': changed_only
+        }
+        
+        return tree
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def browse_directory(repo_path: str, dir_path: str) -> Dict[str, Any]:
+    """
+    Get contents of a specific directory within the repository.
+    
+    Args:
+        repo_path: Path to Git repository
+        dir_path: Directory path relative to repository root (e.g., '/', 'src/components')
+        
+    Returns:
+        Dictionary with directory contents:
+        {
+            'path': str,
+            'contents': [
+                {
+                    'name': str,
+                    'path': str,
+                    'type': 'file' | 'directory',
+                    'size': int (for files),
+                    'status': str (for files),
+                    'has_changes': bool (for directories)
+                }
+            ]
+        }
+        
+    Raises:
+        InvalidGitRepositoryError: If path is not a valid Git repository
+        GitPermissionError: If permission denied accessing repository
+        ValueError: If path is invalid or contains traversal patterns
+        FileNotFoundError: If directory does not exist
+    """
+    try:
+        # Validate and normalize the directory path
+        if '..' in dir_path or dir_path.startswith('/..'):
+            raise ValueError("Invalid path: directory traversal detected")
+        
+        # Normalize directory path
+        dir_path = dir_path.strip('/')
+        if dir_path and not dir_path.endswith('/'):
+            dir_path += '/'
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Get file statuses for the entire repository
+        status_map = {}
+        
+        # Unstaged changes (working tree vs index)
+        for item in repo.index.diff(None):
+            if item.change_type == 'M':
+                status_map[item.a_path] = 'modified'
+            elif item.change_type == 'D':
+                # Unstaged deleted file
+                status_map[item.a_path] = 'deleted'
+        
+        # Staged changes (index vs HEAD)
+        # repo.index.diff('HEAD') compares: index (a) to HEAD (b)
+        for item in repo.index.diff('HEAD'):
+            if item.a_path in status_map:
+                # If file has unstaged changes, keep that status (it takes precedence)
+                continue
+            # a_blob = index, b_blob = HEAD
+            if item.a_blob is not None and item.b_blob is None:
+                status_map[item.a_path] = 'added'
+            elif item.a_blob is None and item.b_blob is not None:
+                # Staged deleted file
+                status_map[item.a_path or item.b_path] = 'deleted-staged'
+            else:
+                status_map[item.a_path] = 'staged'
+        
+        # Untracked files
+        for item in repo.untracked_files:
+            status_map[item] = 'untracked'
+        
+        contents = []
+        seen_dirs = set()
+        
+        # Browse tracked files
+        try:
+            if dir_path:
+                # Navigate to the specific directory in the tree
+                try:
+                    tree_obj = repo.head.commit.tree / dir_path.rstrip('/')
+                    if tree_obj.type != 'tree':
+                        raise ValueError("Path is not a directory")
+                except KeyError:
+                    # Directory doesn't exist in tree, might be new/untracked
+                    pass
+                else:
+                    for item in tree_obj:
+                        if item.type == 'tree':
+                            # It's a subdirectory
+                            subdir_path = f"{dir_path}{item.name}/"
+                            has_changes = any(p.startswith(subdir_path) for p in status_map.keys())
+                            contents.append({
+                                'name': item.name,
+                                'path': subdir_path.rstrip('/'),
+                                'type': 'directory',
+                                'has_changes': has_changes
+                            })
+                            seen_dirs.add(item.name)
+                        elif item.type == 'blob':
+                            # It's a file
+                            file_path = f"{dir_path}{item.name}"
+                            contents.append({
+                                'name': item.name,
+                                'path': file_path,
+                                'type': 'file',
+                                'size': item.size,
+                                'status': status_map.get(file_path, 'unmodified')
+                            })
+            else:
+                # Root directory
+                for item in repo.head.commit.tree:
+                    if item.type == 'tree':
+                        subdir_path = f"{item.name}/"
+                        has_changes = any(p.startswith(subdir_path) for p in status_map.keys())
+                        contents.append({
+                            'name': item.name,
+                            'path': item.name,
+                            'type': 'directory',
+                            'has_changes': has_changes
+                        })
+                        seen_dirs.add(item.name)
+                    elif item.type == 'blob':
+                        file_path = item.name
+                        contents.append({
+                            'name': item.name,
+                            'path': file_path,
+                            'type': 'file',
+                            'size': item.size,
+                            'status': status_map.get(file_path, 'unmodified')
+                        })
+        except (ValueError, BadName):
+            # Empty repository or no commits
+            pass
+        
+        # Add untracked files/directories in this directory
+        for untracked in repo.untracked_files:
+            # Check if untracked file is in the current directory
+            if dir_path:
+                if untracked.startswith(dir_path):
+                    relative_path = untracked[len(dir_path):]
+                    if '/' in relative_path:
+                        # It's in a subdirectory
+                        dir_name = relative_path.split('/')[0]
+                        if dir_name not in seen_dirs:
+                            contents.append({
+                                'name': dir_name,
+                                'path': f"{dir_path}{dir_name}",
+                                'type': 'directory',
+                                'has_changes': True
+                            })
+                            seen_dirs.add(dir_name)
+                    else:
+                        # It's a file in this directory
+                        contents.append({
+                            'name': relative_path,
+                            'path': untracked,
+                            'type': 'file',
+                            'size': 0,
+                            'status': 'untracked'
+                        })
+            else:
+                # Root directory
+                if '/' in untracked:
+                    dir_name = untracked.split('/')[0]
+                    if dir_name not in seen_dirs:
+                        contents.append({
+                            'name': dir_name,
+                            'path': dir_name,
+                            'type': 'directory',
+                            'has_changes': True
+                        })
+                        seen_dirs.add(dir_name)
+                else:
+                    contents.append({
+                        'name': untracked,
+                        'path': untracked,
+                        'type': 'file',
+                        'size': 0,
+                        'status': 'untracked'
+                    })
+        
+        # Sort contents: directories first, then files, alphabetically
+        contents.sort(key=lambda x: (x['type'] == 'file', x['name'].lower()))
+        
+        return {
+            'path': dir_path.rstrip('/') if dir_path else '/',
+            'contents': contents
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def _build_untracked_file_diff(full_file_path: Path, file_path: str) -> Dict[str, Any]:
+    """Build a synthetic added-file diff for an untracked working tree file."""
+    file_size = full_file_path.stat().st_size
+    sample_size = min(8192, file_size)
+    with open(full_file_path, 'rb') as file_obj:
+        sample = file_obj.read(sample_size)
+
+    if not is_text_file(str(full_file_path), sample):
+        return {
+            'is_binary': True,
+            'file_path': file_path,
+            'size': file_size
+        }
+
+    content = full_file_path.read_text(encoding='utf-8', errors='replace')
+    lines = content.splitlines()
+    diff_lines = [f"@@ -0,0 +1,{len(lines)} @@"] if lines else ['@@ -0,0 +0,0 @@']
+    diff_lines.extend(f'+{line}' for line in lines)
+    diff_text = '\n'.join(diff_lines)
+    if lines or content.endswith('\n'):
+        diff_text += '\n'
+
+    return {
+        'is_binary': False,
+        'diff': diff_text,
+        'additions': len(lines),
+        'deletions': 0,
+        'file_path': file_path,
+        'change_type': 'A'
+    }
+
+
+def get_file_diff(repo_path: str, file_path: str, staged: bool = False, context_lines: int = 3) -> Dict[str, Any]:
+    """
+    Get diff for a specific file.
+    
+    Args:
+        repo_path: Path to Git repository
+        file_path: Path to file within repository (relative to repo root)
+        staged: If True, get staged diff (index vs HEAD), else unstaged (working vs index)
+        context_lines: Number of context lines around changes
+        
+    Returns:
+        Dictionary with diff information including:
+        - is_binary: Whether file is binary
+        - diff: Unified diff string
+        - additions: Number of lines added
+        - deletions: Number of lines deleted
+        
+    Raises:
+        FileNotFoundError: If file doesn't exist in repository
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Validate file path
+        file_path = file_path.lstrip('/')
+        full_file_path = normalized_path / file_path
+        
+        if not full_file_path.exists():
+            # Check if it's a deleted file
+            pass
+        
+        # Get diff
+        if staged:
+            # Staged changes: index vs HEAD (use R=True to show additions correctly)
+            diffs = repo.index.diff('HEAD', paths=file_path, create_patch=True, unified=context_lines, R=True)
+        else:
+            # Unstaged changes: working tree vs index
+            diffs = repo.index.diff(None, paths=file_path, create_patch=True, unified=context_lines)
+            
+            # If no unstaged diff found, check if it's a new file that's staged
+            # In this case, show the staged diff so users can see the content
+            if not diffs:
+                staged_diffs = repo.index.diff('HEAD', paths=file_path, create_patch=True, unified=context_lines, R=True)
+                if staged_diffs:
+                    # Check if it's a new file (with R=True: a_blob is HEAD, b_blob is index)
+                    # For new files: a_blob (HEAD) is None, b_blob (index) exists
+                    diff_item = staged_diffs[0]
+                    if diff_item.a_blob is None and diff_item.b_blob is not None:
+                        diffs = staged_diffs
+
+            if not diffs and file_path in repo.untracked_files and full_file_path.exists():
+                return _build_untracked_file_diff(full_file_path, file_path)
+        
+        if not diffs:
+            return {
+                'is_binary': False,
+                'diff': '',
+                'additions': 0,
+                'deletions': 0,
+                'file_path': file_path
+            }
+        
+        diff_item = diffs[0]
+        
+        # Check if binary
+        if diff_item.a_blob and diff_item.a_blob.size > 0:
+            # Simple heuristic: check for null bytes
+            try:
+                if diff_item.a_blob:
+                    sample = diff_item.a_blob.data_stream.read(8192)
+                    if b'\x00' in sample:
+                        return {
+                            'is_binary': True,
+                            'file_path': file_path,
+                            'size': diff_item.a_blob.size if diff_item.a_blob else 0
+                        }
+            except:
+                pass
+        
+        # Get diff text
+        diff_text = diff_item.diff.decode('utf-8', errors='replace') if diff_item.diff else ''
+        
+        # Count additions/deletions
+        additions = 0
+        deletions = 0
+        for line in diff_text.split('\n'):
+            if line.startswith('+') and not line.startswith('+++'):
+                additions += 1
+            elif line.startswith('-') and not line.startswith('---'):
+                deletions += 1
+        
+        return {
+            'is_binary': False,
+            'diff': diff_text,
+            'additions': additions,
+            'deletions': deletions,
+            'file_path': file_path,
+            'change_type': diff_item.change_type
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing file: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def get_commit_history(repo_path: str, limit: int = 50, offset: int = 0) -> List[Dict[str, Any]]:
+    """
+    Get commit history with pagination.
+    
+    Args:
+        repo_path: Path to Git repository
+        limit: Maximum number of commits to return
+        offset: Number of commits to skip
+        
+    Returns:
+        List of commit dictionaries with hash, author, date, and message
+        
+    Raises:
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        commits = []
+        for i, commit in enumerate(repo.iter_commits()):
+            if i < offset:
+                continue
+            if len(commits) >= limit:
+                break
+                
+            commits.append({
+                'hash': commit.hexsha,
+                'short_hash': commit.hexsha[:7],
+                'author': str(commit.author),
+                'author_email': commit.author.email,
+                'date': commit.committed_datetime.isoformat(),
+                'message': commit.message.strip(),
+                'parent_count': len(commit.parents)
+            })
+        
+        return commits
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def get_commit_details(repo_path: str, commit_hash: str) -> Dict[str, Any]:
+    """
+    Get detailed information about a specific commit including changed files and diffs.
+    
+    Args:
+        repo_path: Path to Git repository
+        commit_hash: Full or abbreviated commit hash
+        
+    Returns:
+        Dictionary with commit metadata, changed files, and diffs
+        
+    Raises:
+        ValueError: If commit hash is invalid or commit not found
+        InvalidGitRepositoryError: If path is not a valid Git repository
+        GitPermissionError: If permission denied accessing repository
+    """
+    try:
+        # Validate hash format (at least 4 hex characters)
+        if not commit_hash or len(commit_hash) < 4:
+            raise ValueError("Commit hash too short (minimum 4 characters)")
+        if not all(c in '0123456789abcdefABCDEF' for c in commit_hash):
+            raise ValueError("Invalid commit hash format")
+        
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Resolve abbreviated hash to full commit
+        try:
+            commit = repo.commit(commit_hash)
+        except (BadName, ValueError):
+            raise ValueError(f"Commit not found: {commit_hash}")
+        
+        # Get commit metadata
+        result = {
+            'hash': commit.hexsha,
+            'short_hash': commit.hexsha[:7],
+            'author_name': str(commit.author),
+            'author_email': commit.author.email,
+            'committed_date': commit.committed_datetime.isoformat(),
+            'message': commit.message.strip(),
+            'parents': [p.hexsha for p in commit.parents],
+            'files': []
+        }
+        
+        # Get parent for diff comparison (use empty tree for initial commit)
+        if commit.parents:
+            parent = commit.parents[0]
+            diffs = parent.diff(commit, create_patch=True)
+        else:
+            # Initial commit - diff against empty tree (4b825dc... is Git's empty tree hash)
+            diffs = commit.diff('4b825dc642cb6eb9a060e54bf8d69288fbee4904', create_patch=True)
+        
+        # Process each changed file
+        for diff in diffs:
+            file_info = {
+                'path': diff.b_path or diff.a_path,
+                'status': _get_diff_status(diff),
+                'additions': 0,
+                'deletions': 0,
+                'is_binary': diff.b_blob and diff.b_blob.mime_type and not diff.b_blob.mime_type.startswith('text/'),
+                'diff': None
+            }
+            
+            # Handle renamed files
+            if diff.renamed:
+                file_info['old_path'] = diff.a_path
+                file_info['new_path'] = diff.b_path
+            
+            # Generate diff for text files only
+            if not file_info['is_binary'] and diff.diff:
+                try:
+                    diff_text = diff.diff.decode('utf-8')
+                    file_info['diff'] = diff_text
+                    
+                    # Count additions/deletions
+                    for line in diff_text.split('\n'):
+                        if line.startswith('+') and not line.startswith('+++'):
+                            file_info['additions'] += 1
+                        elif line.startswith('-') and not line.startswith('---'):
+                            file_info['deletions'] += 1
+                except UnicodeDecodeError:
+                    file_info['is_binary'] = True
+            
+            result['files'].append(file_info)
+        
+        return result
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def _get_diff_status(diff) -> str:
+    """Get human-readable status from git diff object."""
+    if diff.new_file:
+        return 'added'
+    elif diff.deleted_file:
+        return 'deleted'
+    elif diff.renamed:
+        return 'renamed'
+    elif diff.copied_file:
+        return 'copied'
+    else:
+        return 'modified'
+
+
+def get_repo_status(repo_path: str) -> Dict[str, Any]:
+    """
+    Get current repository status.
+    
+    Args:
+        repo_path: Path to Git repository
+        
+    Returns:
+        Dictionary with:
+        - branch: Current branch name or commit hash if detached
+        - is_detached: Whether HEAD is detached
+        - modified: List of modified files
+        - added: List of added files
+        - deleted: List of deleted files
+        - untracked: List of untracked files
+        - ahead: Number of commits ahead of remote
+        - behind: Number of commits behind remote
+        
+    Raises:
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Get branch info
+        if repo.head.is_detached:
+            branch_name = repo.head.commit.hexsha[:7]
+            is_detached = True
+        else:
+            branch_name = repo.active_branch.name
+            is_detached = False
+        
+        # Get file statuses
+        modified = []
+        added = []
+        deleted = []
+        
+        # Unstaged changes (working tree vs index)
+        for item in repo.index.diff(None):
+            if item.change_type == 'M':
+                modified.append(item.a_path)
+            elif item.change_type == 'D':
+                deleted.append(item.a_path)
+        
+        # Staged changes (index vs HEAD)
+        # Use blob checking for reliable detection
+        for item in repo.index.diff('HEAD'):
+            # Skip if already in unstaged (unstaged takes precedence)
+            if item.a_path in modified or item.a_path in deleted:
+                continue
+            
+            # a_blob = index, b_blob = HEAD
+            if item.a_blob is not None and item.b_blob is None:
+                # File exists in index but not in HEAD = newly added file
+                added.append(item.a_path)
+            elif item.a_blob is None and item.b_blob is not None:
+                # File doesn't exist in index but exists in HEAD = deleted file
+                deleted.append(item.a_path or item.b_path)
+            elif item.a_blob is not None and item.b_blob is not None:
+                # File exists in both = modified file
+                modified.append(item.a_path)
+        
+        untracked = list(repo.untracked_files)
+        
+        # Get ahead/behind info
+        ahead = 0
+        behind = 0
+        if not is_detached:
+            try:
+                tracking_branch = repo.active_branch.tracking_branch()
+                if tracking_branch:
+                    ahead = len(list(repo.iter_commits(f'{tracking_branch.name}..{branch_name}')))
+                    behind = len(list(repo.iter_commits(f'{branch_name}..{tracking_branch.name}')))
+            except:
+                pass
+        
+        return {
+            'branch': branch_name,
+            'is_detached': is_detached,
+            'modified': modified,
+            'added': added,
+            'deleted': deleted,
+            'untracked': untracked,
+            'ahead': ahead,
+            'behind': behind
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def validate_branch_name(branch_name: str) -> bool:
+    """
+    Validate branch name according to Git naming rules.
+    
+    Args:
+        branch_name: Branch name to validate
+        
+    Returns:
+        True if valid
+        
+    Raises:
+        ValueError: If branch name is invalid with descriptive message
+    """
+    if not branch_name or not branch_name.strip():
+        raise ValueError("Branch name cannot be empty")
+    
+    # Check for invalid characters
+    invalid_chars = [' ', '..', '~', '^', ':', '?', '*', '[', '\\', '\x7f']
+    for char in invalid_chars:
+        if char in branch_name:
+            raise ValueError(f"Branch name cannot contain '{char}'")
+    
+    # Check invalid patterns
+    if branch_name.startswith('-'):
+        raise ValueError("Branch name cannot start with '-'")
+    if branch_name.endswith('.'):
+        raise ValueError("Branch name cannot end with '.'")
+    if branch_name.endswith('.lock'):
+        raise ValueError("Branch name cannot end with '.lock'")
+    if branch_name == '/':
+        raise ValueError("Branch name cannot be just '/'")
+    
+    return True
+
+
+def list_branches(repo_path: str) -> Dict[str, Any]:
+    """
+    List all branches in the repository.
+    
+    Args:
+        repo_path: Path to Git repository
+        
+    Returns:
+        Dictionary with local and remote branches:
+        {
+            'local': [{'name': str, 'commit': str, 'message': str, ...}],
+            'remote': [{'name': str, 'commit': str, ...}],
+            'current': str or None
+        }
+        
+    Raises:
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        local_branches = []
+        current_branch = None
+        
+        # Get current branch
+        if not repo.head.is_detached:
+            current_branch = repo.active_branch.name
+        
+        # Get local branches
+        for branch in repo.heads:
+            branch_info = {
+                'name': branch.name,
+                'commit': branch.commit.hexsha,
+                'short_commit': branch.commit.hexsha[:7],
+                'message': branch.commit.message.strip().split('\n')[0],
+                'author': str(branch.commit.author),
+                'date': branch.commit.committed_datetime.isoformat(),
+                'is_current': branch.name == current_branch
+            }
+            
+            # Check if merged into current branch
+            if current_branch and branch.name != current_branch:
+                try:
+                    merge_base = repo.merge_base(branch.commit, repo.active_branch.commit)
+                    branch_info['is_merged'] = merge_base and merge_base[0] == branch.commit
+                except:
+                    branch_info['is_merged'] = False
+            else:
+                branch_info['is_merged'] = False
+            
+            local_branches.append(branch_info)
+        
+        # Get remote branches
+        remote_branches = []
+        for ref in repo.remotes.origin.refs if repo.remotes else []:
+            if ref.name != 'origin/HEAD':
+                remote_branches.append({
+                    'name': ref.name,
+                    'commit': ref.commit.hexsha,
+                    'short_commit': ref.commit.hexsha[:7],
+                    'message': ref.commit.message.strip().split('\n')[0],
+                    'author': str(ref.commit.author),
+                    'date': ref.commit.committed_datetime.isoformat()
+                })
+        
+        return {
+            'local': local_branches,
+            'remote': remote_branches,
+            'current': current_branch
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied accessing repository: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def create_branch(repo_path: str, branch_name: str, start_point: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Create a new branch.
+    
+    Args:
+        repo_path: Path to Git repository
+        branch_name: Name for the new branch
+        start_point: Commit/branch/tag to start from (default: HEAD)
+        
+    Returns:
+        Dictionary with new branch details
+        
+    Raises:
+        ValueError: If branch name is invalid or already exists
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        validate_branch_name(branch_name)
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Check if branch already exists
+        if branch_name in [b.name for b in repo.heads]:
+            raise ValueError(f"Branch '{branch_name}' already exists")
+        
+        # Create branch
+        if start_point:
+            try:
+                commit = repo.commit(start_point)
+                new_branch = repo.create_head(branch_name, commit)
+            except BadName:
+                raise ValueError(f"Invalid start point: {start_point}")
+        else:
+            new_branch = repo.create_head(branch_name)
+        
+        return {
+            'name': new_branch.name,
+            'commit': new_branch.commit.hexsha,
+            'short_commit': new_branch.commit.hexsha[:7],
+            'message': new_branch.commit.message.strip()
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied creating branch: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def switch_branch(repo_path: str, branch_name: str) -> Dict[str, Any]:
+    """
+    Switch to a different branch (checkout).
+    
+    Args:
+        repo_path: Path to Git repository
+        branch_name: Name of branch to switch to
+        
+    Returns:
+        Dictionary with switched branch details and status
+        
+    Raises:
+        ValueError: If branch doesn't exist
+        GitPermissionError: If there are uncommitted changes that would be overwritten
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Check if branch exists
+        if branch_name not in [b.name for b in repo.heads]:
+            # Check if it's a remote branch
+            remote_branch = f"origin/{branch_name}"
+            if repo.remotes and remote_branch in [ref.name for ref in repo.remotes.origin.refs]:
+                # Create local tracking branch
+                new_branch = repo.create_head(branch_name, repo.remotes.origin.refs[branch_name])
+                new_branch.set_tracking_branch(repo.remotes.origin.refs[branch_name])
+                repo.heads[branch_name].checkout()
+            else:
+                raise ValueError(f"Branch '{branch_name}' not found")
+        else:
+            # Check for uncommitted changes
+            if repo.is_dirty(untracked_files=False):
+                modified_files = [item.a_path for item in repo.index.diff(None)]
+                raise GitPermissionError(
+                    f"Uncommitted changes would be overwritten: {', '.join(modified_files[:5])}"
+                )
+            
+            # Switch branch
+            repo.heads[branch_name].checkout()
+        
+        # Return new status
+        return get_repo_status(repo_path)
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied switching branch: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+    except GitCommandError as e:
+        raise GitPermissionError(f"Failed to switch branch: {e}")
+
+
+def delete_branch(repo_path: str, branch_name: str, force: bool = False) -> Dict[str, str]:
+    """
+    Delete a branch.
+    
+    Args:
+        repo_path: Path to Git repository
+        branch_name: Name of branch to delete
+        force: If True, delete even if not fully merged
+        
+    Returns:
+        Dictionary with success message
+        
+    Raises:
+        ValueError: If trying to delete current branch or branch doesn't exist
+        GitPermissionError: If branch has unmerged commits and force=False
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Check if branch exists
+        if branch_name not in [b.name for b in repo.heads]:
+            raise ValueError(f"Branch '{branch_name}' not found")
+        
+        # Check if it's the current branch
+        if not repo.head.is_detached and repo.active_branch.name == branch_name:
+            raise ValueError("Cannot delete current branch")
+        
+        branch = repo.heads[branch_name]
+        
+        # Check if branch is merged (unless force=True)
+        if not force and not repo.head.is_detached:
+            try:
+                merge_base = repo.merge_base(branch.commit, repo.active_branch.commit)
+                if not (merge_base and merge_base[0] == branch.commit):
+                    raise ValueError(
+                        f"Branch '{branch_name}' has unmerged commits. Use force=True to delete anyway."
+                    )
+            except:
+                pass
+        
+        # Delete branch
+        repo.delete_head(branch, force=force)
+        
+        return {
+            'message': f"Branch '{branch_name}' deleted successfully",
+            'deleted': branch_name
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied deleting branch: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def merge_branch(repo_path: str, source_branch: str, message: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Merge a branch into the current branch.
+    
+    Args:
+        repo_path: Path to Git repository
+        source_branch: Name of branch to merge from
+        message: Optional custom merge commit message
+        
+    Returns:
+        Dictionary with merge details
+        
+    Raises:
+        ValueError: If source branch doesn't exist
+        GitConflictError: If merge results in conflicts
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        
+        # Check if source branch exists
+        if source_branch not in [b.name for b in repo.heads]:
+            raise ValueError(f"Source branch '{source_branch}' not found")
+        
+        current_branch = repo.active_branch.name if not repo.head.is_detached else None
+        source = repo.heads[source_branch]
+        
+        # Attempt merge
+        try:
+            merge_base = repo.merge_base(repo.head.commit, source.commit)
+            
+            # Check if it's a fast-forward merge
+            if merge_base and merge_base[0] == repo.head.commit:
+                # Fast-forward merge
+                repo.head.reference = source.commit
+                repo.head.reset(index=True, working_tree=True)
+                
+                return {
+                    'type': 'fast-forward',
+                    'message': f"Fast-forward merge of '{source_branch}' into '{current_branch}'",
+                    'commit': source.commit.hexsha,
+                    'short_commit': source.commit.hexsha[:7]
+                }
+            else:
+                # Three-way merge
+                merge_msg = message or f"Merge branch '{source_branch}' into '{current_branch}'"
+                repo.index.merge_tree(source.commit, base=merge_base[0] if merge_base else None)
+                
+                # Check for conflicts
+                unmerged = repo.index.unmerged_blobs()
+                if unmerged:
+                    # Abort merge
+                    repo.index.reset(repo.head.commit)
+                    conflicted_files = list(unmerged.keys())
+                    raise GitConflictError(
+                        f"Merge conflict in files: {', '.join(conflicted_files[:10])}"
+                    )
+                
+                # Commit merge
+                repo.index.commit(
+                    merge_msg,
+                    parent_commits=(repo.head.commit, source.commit)
+                )
+                
+                return {
+                    'type': 'three-way',
+                    'message': f"Merged '{source_branch}' into '{current_branch}'",
+                    'commit': repo.head.commit.hexsha,
+                    'short_commit': repo.head.commit.hexsha[:7]
+                }
+                
+        except GitCommandError as e:
+            # Abort merge on any error
+            try:
+                repo.git.merge('--abort')
+            except:
+                pass
+            raise GitConflictError(f"Merge failed: {str(e)}")
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied during merge: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def is_text_file(file_path: str, sample_data: Optional[bytes] = None) -> bool:
+    """
+    Determine if a file is a text file that can be displayed in an editor.
+    
+    Args:
+        file_path: Path to the file
+        sample_data: Optional first bytes of file for content-based detection
+        
+    Returns:
+        True if file appears to be text, False if binary
+    """
+    # Common text file extensions
+    text_extensions = {
+        '.txt', '.md', '.markdown', '.rst',
+        '.py', '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte',
+        '.html', '.htm', '.xml', '.svg',
+        '.css', '.scss', '.sass', '.less',
+        '.json', '.yaml', '.yml', '.toml', '.ini', '.conf', '.config',
+        '.sh', '.bash', '.zsh', '.fish', '.bat', '.ps1',
+        '.c', '.h', '.cpp', '.hpp', '.cc', '.cxx',
+        '.java', '.kt', '.scala', '.groovy',
+        '.rb', '.php', '.pl', '.lua', '.r',
+        '.go', '.rs', '.swift', '.m', '.mm',
+        '.sql', '.graphql', '.proto',
+        '.env', '.gitignore', '.gitattributes', '.dockerignore',
+        '.dockerfile', '.editorconfig', '.prettierrc', '.eslintrc'
+    }
+    
+    # Common binary file extensions
+    binary_extensions = {
+        '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.svg',
+        '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+        '.zip', '.tar', '.gz', '.bz2', '.xz', '.7z', '.rar',
+        '.exe', '.dll', '.so', '.dylib', '.bin',
+        '.mp3', '.mp4', '.avi', '.mov', '.wav', '.flac',
+        '.pyc', '.pyo', '.class', '.o', '.a', '.lib',
+        '.ttf', '.otf', '.woff', '.woff2', '.eot'
+    }
+    
+    # Check extension
+    file_ext = Path(file_path).suffix.lower()
+    
+    if file_ext in text_extensions:
+        return True
+    
+    if file_ext in binary_extensions:
+        return False
+    
+    # Content-based detection if sample provided
+    if sample_data:
+        # Check for null bytes (strong indicator of binary file)
+        if b'\x00' in sample_data:
+            return False
+        
+        # Try to decode as UTF-8
+        try:
+            sample_data.decode('utf-8')
+            return True
+        except UnicodeDecodeError:
+            return False
+    
+    # Default to text for unknown extensions (can be refined)
+    return file_ext in ['', '.cfg', '.log', '.dat'] or not file_ext
+
+
+def read_file_content(repo_path: str, file_path: str, max_size_bytes: int = 2 * 1024 * 1024) -> Dict[str, Any]:
+    """
+    Read file content from repository for display in editor.
+    
+    Args:
+        repo_path: Path to Git repository
+        file_path: Path to file relative to repository root
+        max_size_bytes: Maximum file size to read (default 2MB)
+        
+    Returns:
+        Dictionary with file content and metadata:
+        {
+            'file_path': str,
+            'content': str (if text file),
+            'encoding': str,
+            'size': int,
+            'mime_type': str,
+            'is_binary': bool,
+            'message': str (if binary or too large)
+        }
+        
+    Raises:
+        ValueError: If file path is invalid or contains traversal patterns
+        FileNotFoundError: If file doesn't exist
+        GitPermissionError: If permission denied
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        # Validate paths
+        if '..' in file_path or file_path.startswith('/..'):
+            raise ValueError("Invalid file path: directory traversal detected")
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Clean file path
+        file_path = file_path.lstrip('/')
+        full_file_path = normalized_repo_path / file_path
+        
+        # Validate file is within repository bounds
+        try:
+            full_file_path.relative_to(normalized_repo_path)
+        except ValueError:
+            raise ValueError("Access denied: file outside repository")
+        
+        # Check if file exists
+        if not full_file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        
+        # Check if it's a file (not a directory)
+        if not full_file_path.is_file():
+            raise ValueError("Path is not a file")
+        
+        # Get file size
+        file_size = full_file_path.stat().st_size
+        
+        # Check size limit
+        if file_size > max_size_bytes:
+            return {
+                'file_path': file_path,
+                'size': file_size,
+                'is_binary': False,
+                'encoding': None,
+                'mime_type': 'application/octet-stream',
+                'message': f'File too large for editor (max {max_size_bytes // (1024 * 1024)}MB)'
+            }
+        
+        # Read first 8KB for binary detection
+        sample_size = min(8192, file_size)
+        with open(full_file_path, 'rb') as f:
+            sample = f.read(sample_size)
+        
+        # Determine if text file
+        if not is_text_file(str(full_file_path), sample):
+            # Binary file - determine MIME type
+            mime_type = 'application/octet-stream'
+            file_ext = full_file_path.suffix.lower()
+            
+            # Common MIME types
+            mime_types = {
+                '.png': 'image/png',
+                '.jpg': 'image/jpeg',
+                '.jpeg': 'image/jpeg',
+                '.gif': 'image/gif',
+                '.pdf': 'application/pdf',
+                '.zip': 'application/zip',
+                '.tar': 'application/x-tar',
+                '.gz': 'application/gzip'
+            }
+            mime_type = mime_types.get(file_ext, mime_type)
+            
+            return {
+                'file_path': file_path,
+                'size': file_size,
+                'is_binary': True,
+                'encoding': None,
+                'mime_type': mime_type,
+                'message': 'Binary file cannot be displayed in editor'
+            }
+        
+        # Read full text file content
+        try:
+            with open(full_file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            encoding = 'utf-8'
+        except UnicodeDecodeError:
+            # Try other encodings
+            for enc in ['latin-1', 'cp1252', 'iso-8859-1']:
+                try:
+                    with open(full_file_path, 'r', encoding=enc) as f:
+                        content = f.read()
+                    encoding = enc
+                    break
+                except UnicodeDecodeError:
+                    continue
+            else:
+                # Fallback: treat as binary
+                return {
+                    'file_path': file_path,
+                    'size': file_size,
+                    'is_binary': True,
+                    'encoding': None,
+                    'mime_type': 'application/octet-stream',
+                    'message': 'File encoding not supported'
+                }
+        
+        # Determine MIME type based on extension
+        file_ext = full_file_path.suffix.lower()
+        mime_types = {
+            '.js': 'text/javascript',
+            '.jsx': 'text/javascript',
+            '.ts': 'text/typescript',
+            '.tsx': 'text/typescript',
+            '.py': 'text/x-python',
+            '.html': 'text/html',
+            '.css': 'text/css',
+            '.json': 'application/json',
+            '.xml': 'text/xml',
+            '.md': 'text/markdown',
+            '.txt': 'text/plain',
+            '.yaml': 'text/yaml',
+            '.yml': 'text/yaml',
+            '.sh': 'text/x-sh',
+            '.sql': 'text/x-sql'
+        }
+        mime_type = mime_types.get(file_ext, 'text/plain')
+        
+        return {
+            'file_path': file_path,
+            'content': content,
+            'encoding': encoding,
+            'size': file_size,
+            'mime_type': mime_type,
+            'is_binary': False
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def write_file_content(repo_path: str, file_path: str, content: str, encoding: str = 'utf-8') -> Dict[str, Any]:
+    """
+    Write content to a file in the repository.
+    
+    Args:
+        repo_path: Path to Git repository
+        file_path: Path to file relative to repository root
+        content: Content to write to file
+        encoding: Text encoding to use (default: utf-8)
+        
+    Returns:
+        Dictionary with success information:
+        {
+            'file_path': str,
+            'size': int,
+            'message': str
+        }
+        
+    Raises:
+        ValueError: If file path is invalid or contains traversal patterns
+        GitPermissionError: If permission denied
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        # Validate paths
+        if '..' in file_path or file_path.startswith('/..'):
+            raise ValueError("Invalid file path: directory traversal detected")
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Clean file path
+        file_path = file_path.lstrip('/')
+        full_file_path = normalized_repo_path / file_path
+        
+        # Validate file is within repository bounds
+        try:
+            full_file_path.relative_to(normalized_repo_path)
+        except ValueError:
+            raise ValueError("Access denied: file outside repository")
+        
+        # Create parent directories if they don't exist
+        full_file_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Write content to file
+        with open(full_file_path, 'w', encoding=encoding) as f:
+            f.write(content)
+        
+        # Get file size
+        file_size = full_file_path.stat().st_size
+        
+        return {
+            'file_path': file_path,
+            'size': file_size,
+            'message': 'File saved successfully'
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def stage_file(repo_path: str, file_path: str) -> Dict[str, Any]:
+    """
+    Stage a single file for commit.
+    
+    Args:
+        repo_path: Path to Git repository
+        file_path: Path to file relative to repository root
+        
+    Returns:
+        Dictionary with success status and file details
+        
+    Raises:
+        ValueError: If file path is invalid or contains traversal patterns
+        FileNotFoundError: If file doesn't exist and is not deleted
+        GitPermissionError: If permission denied
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        # Validate paths
+        if '..' in file_path or file_path.startswith('/..'):
+            raise ValueError("Invalid file path: directory traversal detected")
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Clean file path
+        file_path = file_path.lstrip('/')
+        full_file_path = normalized_repo_path / file_path
+        
+        # Check if file exists or is deleted
+        file_exists = full_file_path.exists()
+        is_deleted = False
+        is_untracked = file_path in repo.untracked_files
+        
+        # Check if file is already staged
+        is_already_staged = False
+        for item in repo.index.diff('HEAD'):
+            if item.a_path == file_path or item.b_path == file_path:
+                is_already_staged = True
+                break
+        
+        if not file_exists:
+            # Check if it's a deleted file in Git
+            try:
+                repo.head.commit.tree / file_path
+                is_deleted = True
+            except (KeyError, ValueError, BadName):
+                raise FileNotFoundError(f"File not found: {file_path}")
+        
+        # Stage the file (if not already staged)
+        if not is_already_staged:
+            if is_deleted:
+                # For deleted files, use git command directly since GitPython's add() checks file existence
+                try:
+                    repo.git.add(file_path)
+                except GitCommandError as e:
+                    raise ValueError(f"Failed to stage deleted file: {e}")
+            else:
+                # For added/modified files, use index.add
+                repo.index.add([file_path])
+        
+        # Determine new status
+        if is_deleted:
+            new_status = 'deleted'
+        elif is_untracked:
+            # File was untracked before staging
+            new_status = 'added'
+        else:
+            # Check if file exists in HEAD (to distinguish 'added' from 'staged')
+            try:
+                repo.head.commit.tree / file_path
+                # File exists in HEAD = modified file
+                new_status = 'staged'
+            except (KeyError, ValueError, BadName):
+                # File doesn't exist in HEAD = newly added file
+                new_status = 'added'
+        
+        return {
+            'success': True,
+            'file_path': file_path,
+            'status': new_status,
+            'message': f'File staged: {file_path}'
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def stage_all_files(repo_path: str) -> Dict[str, Any]:
+    """
+    Stage all changed files in the repository.
+    
+    Args:
+        repo_path: Path to Git repository
+        
+    Returns:
+        Dictionary with success status and count of staged files
+        
+    Raises:
+        GitPermissionError: If permission denied
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Get all changed and untracked files
+        changed_files = []
+        deleted_files = []
+        
+        # Modified and deleted files
+        for item in repo.index.diff(None):
+            if item.change_type == 'D':
+                deleted_files.append(item.a_path)
+            else:
+                changed_files.append(item.a_path)
+        
+        # Untracked files
+        changed_files.extend(repo.untracked_files)
+        
+        if not changed_files and not deleted_files:
+            return {
+                'success': True,
+                'staged_count': 0,
+                'files': [],
+                'message': 'No changes to stage'
+            }
+        
+        # Stage all non-deleted files
+        if changed_files:
+            repo.index.add(changed_files)
+        
+        # Stage deleted files using git command
+        if deleted_files:
+            for deleted_file in deleted_files:
+                try:
+                    repo.git.add(deleted_file)
+                except GitCommandError:
+                    # File might already be staged, ignore
+                    pass
+        
+        total_staged = len(changed_files) + len(deleted_files)
+        all_files = changed_files + deleted_files
+        
+        return {
+            'success': True,
+            'staged_count': total_staged,
+            'files': all_files,
+            'message': f'Staged {total_staged} file(s)'
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def unstage_file(repo_path: str, file_path: str) -> Dict[str, Any]:
+    """
+    Remove a file from the staging area.
+    
+    Args:
+        repo_path: Path to Git repository
+        file_path: Path to file relative to repository root
+        
+    Returns:
+        Dictionary with success status
+        
+    Raises:
+        ValueError: If file path is invalid or contains traversal patterns
+        GitPermissionError: If permission denied
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        # Validate paths
+        if '..' in file_path or file_path.startswith('/..'):
+            raise ValueError("Invalid file path: directory traversal detected")
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Clean file path
+        file_path = file_path.lstrip('/')
+        
+        # Check if file is in index
+        try:
+            # Use git reset HEAD for unstaging (works for all file types including deleted)
+            repo.git.reset('HEAD', file_path)
+            was_staged = True
+        except GitCommandError as e:
+            # File was not staged or other error
+            was_staged = False
+        
+        return {
+            'success': True,
+            'file_path': file_path,
+            'was_staged': was_staged,
+            'message': f'File unstaged: {file_path}' if was_staged else 'File was not staged'
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def create_commit(repo_path: str, message: str, author_name: Optional[str] = None, 
+                 author_email: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Create a Git commit with staged changes.
+    
+    Args:
+        repo_path: Path to Git repository
+        message: Commit message
+        author_name: Optional author name (uses Git config if not provided)
+        author_email: Optional author email (uses Git config if not provided)
+        
+    Returns:
+        Dictionary with commit details
+        
+    Raises:
+        ValueError: If message is empty, too long, or no changes staged
+        GitPermissionError: If permission denied or repository locked
+        GitCommandError: If commit hook fails
+        InvalidGitRepositoryError: If path is not a valid Git repository
+    """
+    try:
+        # Validate commit message
+        if not message or not message.strip():
+            raise ValueError("Commit message cannot be empty")
+        
+        if len(message) > 5000:
+            raise ValueError("Commit message too long (max 5000 characters)")
+        
+        # Validate email format if provided
+        if author_email and '@' not in author_email:
+            raise ValueError("Invalid email format")
+        
+        normalized_repo_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_repo_path))
+        
+        # Check if there are staged changes
+        try:
+            staged_diff = repo.index.diff('HEAD')
+            if not staged_diff:
+                raise ValueError("No changes staged for commit")
+        except (ValueError, BadName):
+            # Empty repository - check if there are files in index
+            if not repo.index.entries:
+                raise ValueError("No changes staged for commit")
+        
+        # Prepare author if provided
+        actor = None
+        if author_name and author_email:
+            from git import Actor
+            actor = Actor(author_name, author_email)
+        
+        # Create commit
+        try:
+            if actor:
+                commit = repo.index.commit(message, author=actor, committer=actor)
+            else:
+                commit = repo.index.commit(message)
+        except GitCommandError as e:
+            if 'hook' in str(e).lower():
+                raise GitCommandError(f"Commit hook failed: {e}", 1)
+            elif 'lock' in str(e).lower():
+                raise GitPermissionError("Repository is locked by another operation")
+            else:
+                raise
+        
+        return {
+            'success': True,
+            'commit_hash': commit.hexsha,
+            'short_hash': commit.hexsha[:7],
+            'message': commit.message.strip(),
+            'author': str(commit.author),
+            'author_email': commit.author.email,
+            'date': commit.committed_datetime.isoformat()
+        }
+        
+    except PermissionError as e:
+        raise GitPermissionError(f"Permission denied: {e}")
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+
+
+def list_remotes(repo_path: str) -> Dict[str, Any]:
+    """List all configured remotes with their fetch/push URLs."""
+    try:
+        normalized_path = _normalize_path(repo_path)
+        repo = Repo(str(normalized_path))
+        remotes: List[Dict[str, Any]] = []
+        for remote in repo.remotes:
+            try:
+                urls = list(remote.urls)
+            except GitCommandError:
+                urls = []
+            config_reader = remote.config_reader
+            try:
+                push_url = config_reader.get('pushurl')
+            except Exception:
+                push_url = None
+            remotes.append({
+                'name': remote.name,
+                'url': urls[0] if urls else '',
+                'fetch_url': urls[0] if urls else '',
+                'push_url': push_url or (urls[0] if urls else ''),
+            })
+        return {'remotes': remotes}
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+
+
+def add_remote(repo_path: str, name: str, url: str) -> Dict[str, Any]:
+    """Add a new remote by name/URL. Raises ValueError if the name already exists."""
+    if not name or not name.strip():
+        raise ValueError("Remote name cannot be empty")
+    if not url or not url.strip():
+        raise ValueError("Remote URL cannot be empty")
+    normalized_path = _normalize_path(repo_path)
+    try:
+        repo = Repo(str(normalized_path))
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+    name = name.strip()
+    url = url.strip()
+    if name in [remote.name for remote in repo.remotes]:
+        raise ValueError(f"Remote '{name}' already exists")
+    try:
+        remote = repo.create_remote(name, url)
+    except GitCommandError as exc:
+        raise GitCommandError(f"Failed to add remote: {exc}", 1)
+    return {
+        'success': True,
+        'name': remote.name,
+        'url': url,
+        'message': f"Remote '{name}' added",
+    }
+
+
+def remove_remote(repo_path: str, name: str) -> Dict[str, Any]:
+    """Remove a remote by name."""
+    if not name:
+        raise ValueError("Remote name cannot be empty")
+    normalized_path = _normalize_path(repo_path)
+    try:
+        repo = Repo(str(normalized_path))
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+    if name not in [remote.name for remote in repo.remotes]:
+        raise ValueError(f"Remote '{name}' not found")
+    try:
+        from git.remote import Remote as _Remote
+        _Remote.remove(repo, name)
+    except GitCommandError as exc:
+        raise GitCommandError(f"Failed to remove remote: {exc}", 1)
+    return {'success': True, 'name': name, 'message': f"Remote '{name}' removed"}
+
+
+def _summarize_push_info(push_info_list) -> List[Dict[str, Any]]:
+    summaries: List[Dict[str, Any]] = []
+    for info in push_info_list or []:
+        try:
+            flags = int(getattr(info, 'flags', 0) or 0)
+        except Exception:
+            flags = 0
+        summaries.append({
+            'local_ref': getattr(getattr(info, 'local_ref', None), 'name', None),
+            'remote_ref': getattr(info, 'remote_ref_string', None) or getattr(getattr(info, 'remote_ref', None), 'name', None),
+            'summary': str(getattr(info, 'summary', '') or '').strip(),
+            'flags': flags,
+            'rejected': bool(flags & 64) if flags else False,
+            'error': bool(flags & 1024) if flags else False,
+        })
+    return summaries
+
+
+def _summarize_fetch_info(fetch_info_list) -> List[Dict[str, Any]]:
+    summaries: List[Dict[str, Any]] = []
+    for info in fetch_info_list or []:
+        try:
+            flags = int(getattr(info, 'flags', 0) or 0)
+        except Exception:
+            flags = 0
+        ref = getattr(info, 'ref', None)
+        summaries.append({
+            'ref': getattr(ref, 'name', None),
+            'note': str(getattr(info, 'note', '') or '').strip(),
+            'flags': flags,
+            'commit': getattr(getattr(info, 'commit', None), 'hexsha', None),
+        })
+    return summaries
+
+
+def push_to_remote(
+    repo_path: str,
+    remote_name: str,
+    local_branch: Optional[str] = None,
+    remote_branch: Optional[str] = None,
+    set_upstream: bool = False,
+    force: bool = False,
+) -> Dict[str, Any]:
+    """Push ``local_branch`` to ``remote_branch`` on ``remote_name``."""
+    if not remote_name:
+        raise ValueError("Remote name cannot be empty")
+    normalized_path = _normalize_path(repo_path)
+    try:
+        repo = Repo(str(normalized_path))
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+    if remote_name not in [remote.name for remote in repo.remotes]:
+        raise ValueError(f"Remote '{remote_name}' not found")
+
+    if not local_branch:
+        if repo.head.is_detached:
+            raise ValueError("HEAD is detached; specify local_branch explicitly")
+        local_branch = repo.active_branch.name
+    if not remote_branch:
+        remote_branch = local_branch
+
+    remote = repo.remote(remote_name)
+    refspec = f"{local_branch}:{remote_branch}"
+    kwargs = {}
+    if set_upstream:
+        kwargs['set_upstream'] = True
+    if force:
+        kwargs['force'] = True
+    try:
+        push_infos = remote.push(refspec=refspec, **kwargs)
+    except GitCommandError as exc:
+        raise GitCommandError(f"Push failed: {exc}", 1)
+    summaries = _summarize_push_info(push_infos)
+    rejected = [entry for entry in summaries if entry.get('rejected') or entry.get('error')]
+    success = not rejected
+    message = 'Push completed' if success else 'Push rejected'
+    return {
+        'success': success,
+        'remote': remote_name,
+        'local_branch': local_branch,
+        'remote_branch': remote_branch,
+        'refspec': refspec,
+        'results': summaries,
+        'message': message,
+    }
+
+
+def pull_from_remote(
+    repo_path: str,
+    remote_name: str,
+    local_branch: Optional[str] = None,
+    remote_branch: Optional[str] = None,
+    rebase: bool = False,
+) -> Dict[str, Any]:
+    """Pull ``remote_branch`` from ``remote_name`` into ``local_branch``.
+
+    Uses a fast-forward pull by default; pass ``rebase=True`` to rebase local
+    commits on top of the remote branch.
+    """
+    if not remote_name:
+        raise ValueError("Remote name cannot be empty")
+    normalized_path = _normalize_path(repo_path)
+    try:
+        repo = Repo(str(normalized_path))
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {repo_path}")
+    if remote_name not in [remote.name for remote in repo.remotes]:
+        raise ValueError(f"Remote '{remote_name}' not found")
+
+    if not local_branch:
+        if repo.head.is_detached:
+            raise ValueError("HEAD is detached; specify local_branch explicitly")
+        local_branch = repo.active_branch.name
+    if not remote_branch:
+        remote_branch = local_branch
+
+    current = repo.active_branch.name if not repo.head.is_detached else None
+    if current != local_branch:
+        raise ValueError(
+            f"Cannot pull into '{local_branch}': current branch is '{current or 'detached HEAD'}'. "
+            f"Switch to it first."
+        )
+
+    remote = repo.remote(remote_name)
+    refspec = f"{remote_branch}:{local_branch}" if remote_branch != local_branch else remote_branch
+    kwargs = {}
+    if rebase:
+        kwargs['rebase'] = True
+    try:
+        fetch_infos = remote.pull(refspec=refspec, **kwargs)
+    except GitCommandError as exc:
+        raise GitCommandError(f"Pull failed: {exc}", 1)
+    return {
+        'success': True,
+        'remote': remote_name,
+        'local_branch': local_branch,
+        'remote_branch': remote_branch,
+        'refspec': refspec,
+        'results': _summarize_fetch_info(fetch_infos),
+        'message': 'Pull completed',
+    }
+
+
+def is_git_repository_path(path: str) -> bool:
+    """Return True when the path is a Git repository or is inside one."""
+    try:
+        normalized_path = _normalize_path(path)
+        candidate = normalized_path if normalized_path.is_dir() else normalized_path.parent
+        repo = Repo(str(candidate), search_parent_directories=True)
+        return bool(repo.working_tree_dir)
+    except (InvalidGitRepositoryError, NoSuchPathError, ValueError):
+        return False
+
+
+
+def resolve_git_repository_path(path: str) -> str:
+    """Resolve any path inside a repository to the repository working tree root."""
+    normalized_path = _normalize_path(path)
+    candidate = normalized_path if normalized_path.is_dir() else normalized_path.parent
+    try:
+        repo = Repo(str(candidate), search_parent_directories=True)
+    except InvalidGitRepositoryError:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {path}")
+    if not repo.working_tree_dir:
+        raise InvalidGitRepositoryError(f"Not a valid Git repository: {path}")
+    return str(Path(repo.working_tree_dir).resolve())
+
+
+
+def browse_workspace(path: str) -> Dict[str, Any]:
+    """Browse a file or directory without requiring a Git repository."""
+    normalized_path = _normalize_path(path)
+    target = Path(normalized_path)
+    if not target.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+    if target.is_file():
+        return {
+            'path': str(target),
+            'kind': 'file',
+            'entries': [],
+            'is_git_repo': is_git_repository_path(str(target)),
+        }
+
+    entries = []
+    for child in sorted(target.iterdir(), key=lambda item: (item.is_file(), item.name.lower())):
+        item = {
+            'name': child.name,
+            'path': str(child.resolve()),
+            'type': 'file' if child.is_file() else 'directory',
+        }
+        if child.is_file():
+            item['size'] = child.stat().st_size
+        entries.append(item)
+    return {
+        'path': str(target),
+        'kind': 'directory',
+        'entries': entries,
+        'is_git_repo': is_git_repository_path(str(target)),
+    }
+
+
+
+def get_workspace_tree(path: str, include_nested: bool = True) -> Dict[str, Any]:
+    """Return a file listing for a file or directory without requiring a Git repository."""
+    normalized_path = _normalize_path(path)
+    target = Path(normalized_path)
+    if not target.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+
+    files = []
+    if target.is_file():
+        files.append({'path': str(target), 'type': 'file', 'size': target.stat().st_size})
+    else:
+        iterator = target.rglob('*') if include_nested else target.iterdir()
+        for child in iterator:
+            if child.is_file():
+                files.append({'path': str(child.resolve()), 'type': 'file', 'size': child.stat().st_size})
+    return {
+        'root': str(target),
+        'files': files,
+        'is_git_repo': is_git_repository_path(str(target)),
+    }
+
+
+
+def read_workspace_file(path: str, max_size_bytes: int = 2 * 1024 * 1024) -> Dict[str, Any]:
+    """Read a text file by absolute path without requiring a Git repository."""
+    normalized_path = _normalize_path(path)
+    file_path = Path(normalized_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    if not file_path.is_file():
+        raise ValueError("Path is not a file")
+
+    file_size = file_path.stat().st_size
+    if file_size > max_size_bytes:
+        return {
+            'path': str(file_path),
+            'size': file_size,
+            'is_binary': False,
+            'encoding': None,
+            'mime_type': 'application/octet-stream',
+            'message': f'File too large for editor (max {max_size_bytes // (1024 * 1024)}MB)',
+        }
+
+    sample_size = min(8192, file_size)
+    sample = file_path.read_bytes()[:sample_size]
+    if not is_text_file(str(file_path), sample):
+        return {
+            'path': str(file_path),
+            'size': file_size,
+            'is_binary': True,
+            'encoding': None,
+            'mime_type': 'application/octet-stream',
+            'message': 'Binary file cannot be displayed in editor',
+        }
+
+    content = file_path.read_text(encoding='utf-8')
+    return {
+        'path': str(file_path),
+        'content': content,
+        'encoding': 'utf-8',
+        'size': file_size,
+        'mime_type': 'text/plain',
+        'is_binary': False,
+    }
+
+
+
+def read_workspace_file_bytes(path: str, max_size_bytes: int = 25 * 1024 * 1024) -> Dict[str, Any]:
+    """Read an arbitrary file as raw bytes encoded in base64.
+
+    Used by the frontend to preview images/videos/PDFs without needing the
+    controller and the client to share a filesystem.
+    """
+    import base64
+    import mimetypes
+
+    normalized_path = _normalize_path(path)
+    file_path = Path(normalized_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    if not file_path.is_file():
+        raise ValueError("Path is not a file")
+
+    file_size = file_path.stat().st_size
+    if file_size > max_size_bytes:
+        return {
+            'path': str(file_path),
+            'size': file_size,
+            'too_large': True,
+            'max_size': max_size_bytes,
+            'mime_type': mimetypes.guess_type(str(file_path))[0] or 'application/octet-stream',
+            'message': f'File too large for preview (max {max_size_bytes // (1024 * 1024)}MB)',
+        }
+
+    raw = file_path.read_bytes()
+    mime_type = mimetypes.guess_type(str(file_path))[0] or 'application/octet-stream'
+    return {
+        'path': str(file_path),
+        'size': file_size,
+        'mime_type': mime_type,
+        'base64_content': base64.b64encode(raw).decode('ascii'),
+    }
+
+
+def write_workspace_file(path: str, content: str, encoding: str = 'utf-8') -> Dict[str, Any]:
+    """Write a text file by absolute path without requiring a Git repository."""
+    normalized_path = _normalize_path(path)
+    file_path = Path(normalized_path)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content, encoding=encoding)
+    return {
+        'path': str(file_path),
+        'size': file_path.stat().st_size,
+        'message': 'File saved successfully',
+    }
+
+
+def create_workspace_folder(path: str, exist_ok: bool = True) -> Dict[str, Any]:
+    """Create a directory (recursively) by absolute path.
+
+    Raises FileExistsError when ``exist_ok`` is False and the folder already exists.
+    """
+    normalized_path = _normalize_path(path)
+    folder = Path(normalized_path)
+    if folder.exists() and not folder.is_dir():
+        raise FileExistsError(f'Path exists and is not a directory: {normalized_path}')
+    folder.mkdir(parents=True, exist_ok=exist_ok)
+    return {
+        'path': str(folder),
+        'message': 'Folder created successfully',
+    }
+
+
+def delete_workspace_path(path: str, recursive: bool = False) -> Dict[str, Any]:
+    """Delete a file or directory by absolute path.
+
+    For directories, ``recursive`` must be True unless the directory is empty.
+    Raises FileNotFoundError if the path does not exist.
+    """
+    import shutil
+
+    normalized_path = _normalize_path(path)
+    target = Path(normalized_path)
+    if not target.exists() and not target.is_symlink():
+        raise FileNotFoundError(f'Path not found: {normalized_path}')
+
+    if target.is_symlink() or target.is_file():
+        target.unlink()
+        kind = 'file'
+    elif target.is_dir():
+        if recursive:
+            shutil.rmtree(target)
+        else:
+            try:
+                target.rmdir()
+            except OSError as exc:
+                raise OSError(
+                    f'Folder is not empty (pass recursive=true to delete): {normalized_path}'
+                ) from exc
+        kind = 'folder'
+    else:
+        raise OSError(f'Unsupported path type: {normalized_path}')
+
+    return {
+        'path': str(target),
+        'type': kind,
+        'message': f'{kind.capitalize()} deleted successfully',
+    }
+
+
+def rename_workspace_path(path: str, new_path: str) -> Dict[str, Any]:
+    """Rename or move a filesystem path. Both ``path`` and ``new_path`` must be absolute.
+
+    Raises FileNotFoundError if the source does not exist.
+    Raises FileExistsError if the destination already exists.
+    """
+    normalized_src = _normalize_path(path)
+    normalized_dst = _normalize_path(new_path)
+    src = Path(normalized_src)
+    dst = Path(normalized_dst)
+
+    if not src.exists() and not src.is_symlink():
+        raise FileNotFoundError(f'Path not found: {normalized_src}')
+    if dst.exists():
+        raise FileExistsError(f'Destination already exists: {normalized_dst}')
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    src.rename(dst)
+
+    return {
+        'path': str(dst),
+        'previous_path': str(src),
+        'message': 'Path renamed successfully',
+    }