up-cli 0.2.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

up/git/utils.py

@@ -0,0 +1,270 @@
+"""Shared Git utilities for up-cli.
+
+This module provides common Git operations used across the codebase,
+eliminating duplication between worktree.py and agent.py.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Optional, List, Tuple
+
+# Standard branch prefix for all agent/worktree operations
+BRANCH_PREFIX = "agent"
+
+# Default timeout for git operations (seconds)
+DEFAULT_GIT_TIMEOUT = 60
+
+
+# =============================================================================
+# Exceptions
+# =============================================================================
+
+class GitError(Exception):
+    """Base exception for Git operations."""
+    pass
+
+
+class GitNotInstalledError(GitError):
+    """Git is not installed or not in PATH."""
+    pass
+
+
+class GitTimeoutError(GitError):
+    """Git command timed out."""
+    
+    def __init__(self, message: str, timeout: int):
+        super().__init__(message)
+        self.timeout = timeout
+
+
+class GitCommandError(GitError):
+    """Git command failed with non-zero exit code."""
+    
+    def __init__(self, message: str, returncode: int, stderr: str = ""):
+        super().__init__(message)
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+# =============================================================================
+# Core Functions
+# =============================================================================
+
+
+def is_git_repo(path: Optional[Path] = None) -> bool:
+    """Check if path is inside a Git repository.
+
+    Args:
+        path: Directory to check (defaults to cwd)
+
+    Returns:
+        True if path is in a Git repository
+        
+    Note:
+        Returns False if git is not installed (does not raise).
+    """
+    try:
+        result = run_git("rev-parse", "--git-dir", cwd=path, timeout=10)
+        return result.returncode == 0
+    except (GitNotInstalledError, GitTimeoutError, GitError):
+        return False
+    except Exception:
+        return False
+
+
+def get_current_branch(path: Optional[Path] = None) -> str:
+    """Get current Git branch name.
+
+    Args:
+        path: Repository path (defaults to cwd)
+
+    Returns:
+        Current branch name
+        
+    Raises:
+        GitNotInstalledError: If git is not installed
+        GitTimeoutError: If command times out
+    """
+    result = run_git("rev-parse", "--abbrev-ref", "HEAD", cwd=path)
+    return result.stdout.strip()
+
+
+def count_commits_since(path: Path, base: str = "main") -> int:
+    """Count commits since branching from base.
+
+    Args:
+        path: Repository path
+        base: Base branch to compare against
+
+    Returns:
+        Number of commits since base (0 if error)
+    """
+    try:
+        result = run_git("rev-list", "--count", f"{base}..HEAD", cwd=path)
+        return int(result.stdout.strip())
+    except (GitError, ValueError):
+        return 0
+
+
+def get_repo_root(path: Optional[Path] = None) -> Optional[Path]:
+    """Get the root directory of the Git repository.
+
+    Args:
+        path: Starting path (defaults to cwd)
+
+    Returns:
+        Repository root path or None if not in a repo
+    """
+    try:
+        result = run_git("rev-parse", "--show-toplevel", cwd=path)
+        if result.returncode == 0:
+            return Path(result.stdout.strip())
+        return None
+    except GitError:
+        return None
+
+
+def make_branch_name(name: str) -> str:
+    """Create a standardized branch name.
+
+    Args:
+        name: Agent or task name
+
+    Returns:
+        Branch name with standard prefix
+    """
+    return f"{BRANCH_PREFIX}/{name}"
+
+
+def run_git(
+    *args, 
+    cwd: Optional[Path] = None, 
+    check: bool = False,
+    timeout: int = DEFAULT_GIT_TIMEOUT
+) -> subprocess.CompletedProcess:
+    """Run a git command with standard options.
+
+    Args:
+        *args: Git command arguments
+        cwd: Working directory
+        check: Raise exception on failure
+        timeout: Command timeout in seconds
+
+    Returns:
+        CompletedProcess result
+        
+    Raises:
+        GitNotInstalledError: If git is not installed
+        GitTimeoutError: If command times out
+        GitCommandError: If check=True and command fails
+    """
+    cmd = ["git"] + list(args)
+    cmd_str = " ".join(cmd)
+    
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd or Path.cwd(),
+            capture_output=True,
+            text=True,
+            timeout=timeout
+        )
+        if check and result.returncode != 0:
+            raise GitCommandError(
+                f"Git command failed: {cmd_str}\n{result.stderr}",
+                returncode=result.returncode,
+                stderr=result.stderr
+            )
+        return result
+    except FileNotFoundError:
+        raise GitNotInstalledError(
+            "Git is not installed or not in PATH. "
+            "Please install git: https://git-scm.com/downloads"
+        )
+    except subprocess.TimeoutExpired:
+        raise GitTimeoutError(
+            f"Git command timed out after {timeout}s: {cmd_str}",
+            timeout=timeout
+        )
+
+
+# Legacy branch prefix for migration
+LEGACY_BRANCH_PREFIX = "worktree"
+
+
+def migrate_legacy_branch(name: str, cwd: Optional[Path] = None) -> bool:
+    """Migrate a legacy worktree/ branch to agent/ prefix.
+
+    Args:
+        name: Branch name without prefix
+        cwd: Repository path
+
+    Returns:
+        True if migration successful or not needed
+    """
+    old_branch = f"{LEGACY_BRANCH_PREFIX}/{name}"
+    new_branch = make_branch_name(name)
+
+    # Check if old branch exists
+    result = run_git("branch", "--list", old_branch, cwd=cwd)
+    if not result.stdout.strip():
+        return True  # No migration needed
+
+    # Check if new branch already exists
+    result = run_git("branch", "--list", new_branch, cwd=cwd)
+    if result.stdout.strip():
+        return True  # Already migrated
+
+    # Rename branch
+    result = run_git("branch", "-m", old_branch, new_branch, cwd=cwd)
+    return result.returncode == 0
+
+
+def preview_merge(
+    source_branch: str,
+    target_branch: str = "main",
+    cwd: Optional[Path] = None
+) -> Tuple[bool, List[str]]:
+    """Preview merge to check for conflicts before actual merge.
+
+    Args:
+        source_branch: Branch to merge from
+        target_branch: Branch to merge into
+        cwd: Repository path
+
+    Returns:
+        Tuple of (can_merge, conflicting_files)
+    """
+    workspace = cwd or Path.cwd()
+
+    # Save current branch
+    original_branch = get_current_branch(workspace)
+
+    # Checkout target branch
+    result = run_git("checkout", target_branch, cwd=workspace)
+    if result.returncode != 0:
+        return False, [f"Cannot checkout {target_branch}"]
+
+    # Try merge with --no-commit --no-ff
+    result = run_git(
+        "merge", "--no-commit", "--no-ff", source_branch,
+        cwd=workspace
+    )
+
+    conflicts = []
+    can_merge = result.returncode == 0
+
+    if not can_merge:
+        # Get list of conflicting files
+        status_result = run_git("status", "--porcelain", cwd=workspace)
+        for line in status_result.stdout.strip().split("\n"):
+            if line.startswith("UU ") or line.startswith("AA "):
+                conflicts.append(line[3:])
+
+    # Always abort the merge attempt
+    run_git("merge", "--abort", cwd=workspace)
+
+    # Return to original branch
+    run_git("checkout", original_branch, cwd=workspace)
+
+    return can_merge, conflicts

up/git/worktree.py

@@ -0,0 +1,331 @@
+"""Git worktree management for parallel task execution.
+
+This module provides utilities for creating, managing, and merging
+Git worktrees - enabling parallel AI task execution.
+"""
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from up.git.utils import (
+    is_git_repo,
+    get_current_branch,
+    count_commits_since,
+    make_branch_name,
+    run_git,
+    BRANCH_PREFIX,
+)
+
+
+@dataclass
+class WorktreeState:
+    """State of a task worktree."""
+    task_id: str
+    task_title: str
+    branch: str
+    path: str
+    status: str = "created"  # created, executing, verifying, passed, failed, merged
+    phase: str = "INIT"
+    started: str = field(default_factory=lambda: datetime.now().isoformat())
+    checkpoints: list = field(default_factory=list)
+    ai_invocations: list = field(default_factory=list)
+    verification: dict = field(default_factory=lambda: {
+        "tests_passed": None,
+        "lint_passed": None,
+        "type_check_passed": None
+    })
+    error: Optional[str] = None
+    
+    def save(self, worktree_path: Path):
+        """Save state to worktree."""
+        state_file = worktree_path / ".agent_state.json"
+        state_file.write_text(json.dumps(asdict(self), indent=2))
+    
+    @classmethod
+    def load(cls, worktree_path: Path) -> "WorktreeState":
+        """Load state from worktree."""
+        state_file = worktree_path / ".agent_state.json"
+        if state_file.exists():
+            data = json.loads(state_file.read_text())
+            return cls(**data)
+        raise FileNotFoundError(f"No state file in {worktree_path}")
+
+
+def create_worktree(
+    task_id: str,
+    task_title: str = "",
+    base_branch: str = "main"
+) -> tuple[Path, WorktreeState]:
+    """Create an isolated worktree for a task.
+    
+    Args:
+        task_id: Unique task identifier (e.g., "US-004")
+        task_title: Human-readable task title
+        base_branch: Branch to base the worktree on
+    
+    Returns:
+        Tuple of (worktree_path, state)
+    """
+    branch = make_branch_name(task_id)
+    worktree_dir = Path(".worktrees")
+    worktree_path = worktree_dir / task_id
+    
+    # Ensure .worktrees directory exists
+    worktree_dir.mkdir(exist_ok=True)
+    
+    # Check if worktree already exists
+    if worktree_path.exists():
+        try:
+            state = WorktreeState.load(worktree_path)
+            return worktree_path, state
+        except FileNotFoundError:
+            # Corrupt state, remove and recreate
+            remove_worktree(task_id)
+    
+    # Create branch and worktree
+    result = subprocess.run(
+        ["git", "worktree", "add", "-b", branch, str(worktree_path), base_branch],
+        capture_output=True,
+        text=True
+    )
+    
+    if result.returncode != 0:
+        # Branch might already exist, try without -b
+        result = subprocess.run(
+            ["git", "worktree", "add", str(worktree_path), branch],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to create worktree: {result.stderr}")
+    
+    # Copy environment files
+    env_files = [".env", ".env.local", ".env.development"]
+    for env_file in env_files:
+        if Path(env_file).exists():
+            shutil.copy(env_file, worktree_path / env_file)
+    
+    # Initialize state
+    state = WorktreeState(
+        task_id=task_id,
+        task_title=task_title or task_id,
+        branch=branch,
+        path=str(worktree_path),
+        status="created"
+    )
+    state.save(worktree_path)
+    
+    return worktree_path, state
+
+
+def remove_worktree(task_id: str, force: bool = False):
+    """Remove a worktree and its branch.
+    
+    Args:
+        task_id: Task identifier
+        force: Force removal even if changes exist
+    """
+    worktree_path = Path(f".worktrees/{task_id}")
+    branch = make_branch_name(task_id)
+    
+    # Remove worktree
+    if worktree_path.exists():
+        cmd = ["git", "worktree", "remove", str(worktree_path)]
+        if force:
+            cmd.append("--force")
+        subprocess.run(cmd, capture_output=True)
+    
+    # Delete branch
+    subprocess.run(
+        ["git", "branch", "-D" if force else "-d", branch],
+        capture_output=True
+    )
+
+
+def list_worktrees() -> list[dict]:
+    """List all active worktrees with their state.
+    
+    Returns:
+        List of worktree info dicts
+    """
+    result = subprocess.run(
+        ["git", "worktree", "list", "--porcelain"],
+        capture_output=True,
+        text=True
+    )
+    
+    worktrees = []
+    current = {}
+    
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            if current and ".worktrees" in current.get("worktree", ""):
+                # Load state if available
+                wt_path = Path(current["worktree"])
+                try:
+                    state = WorktreeState.load(wt_path)
+                    current["state"] = asdict(state)
+                except FileNotFoundError:
+                    current["state"] = None
+                worktrees.append(current)
+            current = {}
+        elif line.startswith("worktree "):
+            current["worktree"] = line[9:]
+        elif line.startswith("HEAD "):
+            current["head"] = line[5:]
+        elif line.startswith("branch "):
+            current["branch"] = line[7:]
+    
+    # Don't forget last entry
+    if current and ".worktrees" in current.get("worktree", ""):
+        wt_path = Path(current["worktree"])
+        try:
+            state = WorktreeState.load(wt_path)
+            current["state"] = asdict(state)
+        except FileNotFoundError:
+            current["state"] = None
+        worktrees.append(current)
+    
+    return worktrees
+
+
+def merge_worktree(
+    task_id: str,
+    target_branch: str = "main",
+    squash: bool = True,
+    message: str = None
+) -> bool:
+    """Merge worktree changes into target branch.
+    
+    Args:
+        task_id: Task identifier
+        target_branch: Branch to merge into
+        squash: Whether to squash commits
+        message: Custom commit message
+    
+    Returns:
+        True if merge successful
+    """
+    branch = make_branch_name(task_id)
+    worktree_path = Path(f".worktrees/{task_id}")
+    
+    # Load state for commit message
+    try:
+        state = WorktreeState.load(worktree_path)
+        default_message = f"feat({task_id}): {state.task_title}"
+    except FileNotFoundError:
+        default_message = f"feat({task_id}): Implement task"
+    
+    commit_message = message or default_message
+    
+    # Checkout target branch
+    result = subprocess.run(
+        ["git", "checkout", target_branch],
+        capture_output=True,
+        text=True
+    )
+    if result.returncode != 0:
+        return False
+    
+    # Merge
+    if squash:
+        # Squash merge - combines all commits into staging
+        result = subprocess.run(
+            ["git", "merge", "--squash", branch],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            return False
+        
+        # Commit the squashed changes
+        result = subprocess.run(
+            ["git", "commit", "-m", commit_message],
+            capture_output=True,
+            text=True
+        )
+    else:
+        # Regular merge
+        result = subprocess.run(
+            ["git", "merge", branch, "-m", commit_message],
+            capture_output=True,
+            text=True
+        )
+    
+    if result.returncode != 0:
+        return False
+    
+    # Cleanup worktree
+    remove_worktree(task_id)
+    
+    return True
+
+
+# Standard checkpoint tag prefix (matches checkpoint.py)
+CHECKPOINT_TAG_PREFIX = "up-checkpoint"
+
+
+def create_checkpoint(worktree_path: Path, name: str = None) -> str:
+    """Create a checkpoint (commit + tag) in a worktree.
+    
+    Args:
+        worktree_path: Path to worktree
+        name: Optional checkpoint name
+    
+    Returns:
+        Checkpoint identifier
+    """
+    checkpoint_name = name or f"cp-{datetime.now().strftime('%H%M%S')}"
+    
+    # Stage all changes
+    subprocess.run(
+        ["git", "add", "-A"],
+        cwd=worktree_path,
+        capture_output=True
+    )
+    
+    # Check if there are changes to commit
+    result = subprocess.run(
+        ["git", "status", "--porcelain"],
+        cwd=worktree_path,
+        capture_output=True,
+        text=True
+    )
+    
+    if result.stdout.strip():
+        # Commit changes
+        subprocess.run(
+            ["git", "commit", "-m", f"checkpoint: {checkpoint_name}"],
+            cwd=worktree_path,
+            capture_output=True
+        )
+    
+    # Create lightweight tag with standard prefix
+    subprocess.run(
+        ["git", "tag", f"{CHECKPOINT_TAG_PREFIX}/{checkpoint_name}"],
+        cwd=worktree_path,
+        capture_output=True
+    )
+    
+    return checkpoint_name
+
+
+def reset_to_checkpoint(worktree_path: Path, checkpoint: str = None):
+    """Reset worktree to a checkpoint.
+    
+    Args:
+        worktree_path: Path to worktree
+        checkpoint: Checkpoint name (defaults to HEAD)
+    """
+    target = f"{CHECKPOINT_TAG_PREFIX}/{checkpoint}" if checkpoint else "HEAD"
+    
+    subprocess.run(
+        ["git", "reset", "--hard", target],
+        cwd=worktree_path,
+        capture_output=True
+    )