multi-forge 0.2.0__py3-none-any.whl

forge/session/worktree/cleanup.py

@@ -0,0 +1,262 @@
+"""Git worktree cleanup utilities.
+
+This module provides functions for safely removing git worktrees.
+Cleanup order:
+1. Try git worktree remove
+2. If dirty: remove untracked config files, retry
+3. git branch delete (with -D if force, else -d)
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..exceptions import (
+    BranchInUseError,
+    BranchNotMergedError,
+    DirtyWorktreeError,
+    GitWorktreeError,
+)
+from .config_copy import get_copied_config_files
+from .create import find_git_binary, get_main_repo_root, get_repo_root
+
+
+@dataclass
+class CleanupResult:
+    """Result of worktree cleanup."""
+
+    worktree_removed: bool = False
+    branch_deleted: bool = False
+    config_files_removed: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def is_worktree_dirty(worktree_path: Path) -> bool:
+    """Check if worktree has uncommitted changes.
+
+    Args:
+        worktree_path: Path to worktree.
+
+    Returns:
+        True if worktree has uncommitted changes.
+    """
+    git = find_git_binary()
+
+    result = subprocess.run(
+        [git, "status", "--porcelain"],
+        cwd=str(worktree_path),
+        capture_output=True,
+        text=True,
+    )
+
+    return bool(result.stdout.strip())
+
+
+def remove_config_files(worktree_path: Path) -> list[str]:
+    """Remove untracked config files from worktree.
+
+    Only removes files that are:
+    - In the allowlist AND
+    - NOT tracked by git
+
+    Called by cleanup_worktree() after a failed removal attempt to clear
+    untracked config files that make the worktree dirty.
+
+    Args:
+        worktree_path: Path to worktree.
+
+    Returns:
+        List of removed file paths (relative to worktree root).
+    """
+    removed: list[str] = []
+    config_files = get_copied_config_files(worktree_path)
+
+    for file_path in config_files:
+        try:
+            if file_path.is_dir():
+                shutil.rmtree(file_path)
+            else:
+                file_path.unlink()
+            try:
+                removed.append(str(file_path.relative_to(worktree_path)))
+            except ValueError:
+                removed.append(file_path.name)
+        except OSError:
+            pass  # Best effort
+
+    return removed
+
+
+def remove_worktree(
+    worktree_path: Path,
+    force: bool = False,
+    repo_root: Path | None = None,
+) -> bool:
+    """Remove a git worktree.
+
+    Args:
+        worktree_path: Path to worktree.
+        force: Force removal even if dirty.
+        repo_root: Main repository root (must be provided, not derived from worktree).
+
+    Returns:
+        True if worktree was removed.
+
+    Raises:
+        DirtyWorktreeError: If worktree is dirty and force=False.
+        GitWorktreeError: If removal fails for other reasons.
+    """
+    if not worktree_path.exists():
+        return False
+
+    if not force and is_worktree_dirty(worktree_path):
+        raise DirtyWorktreeError(str(worktree_path))
+
+    git = find_git_binary()
+
+    # Get the main repo root to run git worktree remove from there
+    # (git worktree remove needs to be run from the main repo, not from the worktree itself)
+    if repo_root is None:
+        repo_root = get_main_repo_root(worktree_path)
+
+    cmd = [git, "worktree", "remove", str(worktree_path)]
+    if force:
+        cmd.append("--force")
+
+    result = subprocess.run(
+        cmd,
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        if "contains modified or untracked files" in stderr.lower():
+            raise DirtyWorktreeError(str(worktree_path))
+        raise GitWorktreeError("remove", stderr, result.returncode)
+
+    return True
+
+
+def delete_branch(
+    branch: str,
+    cwd: Path | None = None,
+    force: bool = False,
+) -> bool:
+    """Delete a git branch.
+
+    Args:
+        branch: Branch name to delete.
+        cwd: Working directory (should be main repo, not the worktree).
+        force: Use -D (force delete) instead of -d.
+
+    Returns:
+        True if branch was deleted.
+
+    Raises:
+        BranchInUseError: If branch is checked out elsewhere.
+        BranchNotMergedError: If branch is not fully merged and force=False.
+        GitWorktreeError: If deletion fails for other reasons.
+    """
+    git = find_git_binary()
+    repo_root = get_repo_root(cwd)
+
+    flag = "-D" if force else "-d"
+    result = subprocess.run(
+        [git, "branch", flag, branch],
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip().lower()
+        stderr_orig = result.stderr.strip()
+
+        if "not found" in stderr:
+            return False
+
+        # Check for "checked out" or "used by worktree" - branch is in use
+        if "checked out" in stderr or "used by worktree" in stderr:
+            # Try to extract worktree path from error message
+            # Format: "error: Cannot delete branch 'X' checked out at '/path/to/worktree'"
+            # or: "error: cannot delete branch 'X' used by worktree at '/path/to/worktree'"
+            worktree = "another worktree"
+            if "at '" in stderr_orig:
+                try:
+                    worktree = stderr_orig.split("at '")[1].split("'")[0]
+                except IndexError:
+                    pass
+            raise BranchInUseError(branch, worktree)
+
+        if "not fully merged" in stderr:
+            raise BranchNotMergedError(branch)
+
+        raise GitWorktreeError("branch delete", stderr_orig, result.returncode)
+
+    return True
+
+
+def cleanup_worktree(
+    worktree_path: Path,
+    branch: str | None = None,
+    delete_branch_flag: bool = False,
+    force: bool = False,
+    repo_root: Path | None = None,
+) -> CleanupResult:
+    """Full cleanup of a worktree and optionally its branch.
+
+    Order:
+    1. Try removing worktree
+    2. If dirty: remove untracked config files, retry
+    3. Delete branch if requested
+
+    Args:
+        worktree_path: Path to worktree.
+        branch: Branch name (required if delete_branch_flag=True).
+        delete_branch_flag: Whether to delete the branch.
+        force: Force removal even if dirty, and use -D for branch.
+        repo_root: Main repository root (derived from worktree if not provided).
+
+    Returns:
+        CleanupResult with details of what was done.
+    """
+    result = CleanupResult()
+
+    # Get main repo root before removing worktree (so we can delete branch later)
+    # Must use get_main_repo_root to get the main repo, not the worktree itself
+    if repo_root is None and worktree_path.exists():
+        try:
+            repo_root = get_main_repo_root(worktree_path)
+        except GitWorktreeError:
+            pass  # Will fail to delete branch if repo not found
+
+    # 1. Try removing worktree first. If it fails due to untracked config
+    #    files making it dirty, remove those files and retry — this avoids
+    #    deleting config files when the removal will fail for other reasons.
+    try:
+        result.worktree_removed = remove_worktree(worktree_path, force=force, repo_root=repo_root)
+    except DirtyWorktreeError:
+        if worktree_path.exists():
+            result.config_files_removed = remove_config_files(worktree_path)
+        try:
+            result.worktree_removed = remove_worktree(worktree_path, force=force, repo_root=repo_root)
+        except (DirtyWorktreeError, GitWorktreeError) as e:
+            result.errors.append(str(e))
+            return result
+    except GitWorktreeError as e:
+        result.errors.append(str(e))
+        return result
+
+    # 3. Delete branch if requested
+    if delete_branch_flag and branch and repo_root:
+        try:
+            result.branch_deleted = delete_branch(branch, cwd=repo_root, force=force)
+        except (BranchInUseError, BranchNotMergedError, GitWorktreeError) as e:
+            result.errors.append(str(e))
+
+    return result

forge/session/worktree/config_copy.py

@@ -0,0 +1,203 @@
+"""Copy runtime configuration to worktree.
+
+This module handles safe copying of runtime config files (.env, .mcp.json, etc.)
+from the main repository to a new worktree. Safety rules:
+1. Only copy if file exists in source
+2. Only copy if file does NOT already exist in target
+3. Skip files that are tracked by git
+
+Entries support glob patterns (``**/`` prefix) for nested project structures.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .create import find_git_binary
+
+# Allowlist of runtime config files/directories to copy (relative to repo root).
+# Entries with glob metacharacters are resolved via Path.glob(); exact paths are
+# matched directly. ``**/X`` matches X at any depth including root.
+DEFAULT_CONFIG_ALLOWLIST: tuple[str, ...] = (
+    ".env",
+    ".env.local",
+    ".envrc",
+    "docker/certs",
+    "**/.claude/settings.json",
+    "**/.claude/settings.local.json",
+    "**/.mcp.json",
+    "**/.mcp.local.json",
+)
+
+
+@dataclass
+class ConfigCopyResult:
+    """Result of config copy operation."""
+
+    copied: list[str] = field(default_factory=list)
+    skipped_exists: list[str] = field(default_factory=list)  # Already exists in target
+    skipped_tracked: list[str] = field(default_factory=list)  # Tracked by git
+    skipped_not_found: list[str] = field(default_factory=list)  # Not in source
+    failed: list[tuple[str, str]] = field(default_factory=list)  # (file, error)
+
+
+def is_file_tracked(file_path: Path, cwd: Path) -> bool:
+    """Check if a file is tracked by git.
+
+    Uses `git ls-files --error-unmatch` to check if the file is tracked.
+
+    Args:
+        file_path: Path to the file (can be relative or absolute).
+        cwd: Working directory for git command.
+
+    Returns:
+        True if file is tracked by git.
+    """
+    git = find_git_binary()
+
+    if file_path.is_absolute():
+        try:
+            file_path = file_path.relative_to(cwd)
+        except ValueError:
+            # File is not under cwd, can't be tracked
+            return False
+
+    result = subprocess.run(
+        [git, "ls-files", "--error-unmatch", str(file_path)],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+    )
+
+    return result.returncode == 0
+
+
+def _is_glob_pattern(pattern: str) -> bool:
+    """Check if a pattern contains glob metacharacters."""
+    return any(c in pattern for c in ("*", "?", "["))
+
+
+def _resolve_glob(root: Path, pattern: str) -> list[Path]:
+    """Resolve a glob pattern relative to root.
+
+    Returns sorted relative paths matching the pattern.
+    """
+    return sorted(match.relative_to(root) for match in root.glob(pattern))
+
+
+def _copy_single(
+    source_root: Path,
+    worktree_path: Path,
+    filename: str,
+    result: ConfigCopyResult,
+) -> None:
+    """Copy a single file or directory from source to worktree with safety checks."""
+    source_path = source_root / filename
+    dest_path = worktree_path / filename
+
+    if source_path.is_dir():
+        if dest_path.exists():
+            result.skipped_exists.append(filename)
+            return
+        try:
+            shutil.copytree(source_path, dest_path)
+            result.copied.append(filename)
+        except OSError as e:
+            result.failed.append((filename, str(e)))
+        return
+
+    if not source_path.is_file():
+        result.skipped_not_found.append(filename)
+        return
+
+    if dest_path.exists():
+        result.skipped_exists.append(filename)
+        return
+
+    if is_file_tracked(Path(filename), worktree_path):
+        result.skipped_tracked.append(filename)
+        return
+
+    try:
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source_path, dest_path)
+        result.copied.append(filename)
+    except OSError as e:
+        result.failed.append((filename, str(e)))
+
+
+def copy_runtime_config(
+    source_root: Path,
+    worktree_path: Path,
+    allowlist: tuple[str, ...] | None = None,
+) -> ConfigCopyResult:
+    """Copy runtime configuration files to worktree.
+
+    Safely copies files from the allowlist, respecting:
+    - Only copy if file exists in source
+    - Only copy if file does NOT already exist in target
+    - Skip files that are tracked by git (they'll be in the worktree already)
+
+    Allowlist entries may be exact relative paths or glob patterns (containing
+    ``*``, ``?``, or ``[``). Glob patterns are resolved via ``Path.glob()``
+    with excluded directories filtered out (node_modules, .git, etc.).
+
+    Args:
+        source_root: Path to source repository.
+        worktree_path: Path to worktree.
+        allowlist: Files to copy (defaults to DEFAULT_CONFIG_ALLOWLIST).
+
+    Returns:
+        ConfigCopyResult with detailed status of each file.
+    """
+    result = ConfigCopyResult()
+    files_to_copy = allowlist if allowlist is not None else DEFAULT_CONFIG_ALLOWLIST
+
+    for entry in files_to_copy:
+        if _is_glob_pattern(entry):
+            resolved = _resolve_glob(source_root, entry)
+            if not resolved:
+                result.skipped_not_found.append(entry)
+                continue
+            for rel_path in resolved:
+                _copy_single(source_root, worktree_path, str(rel_path), result)
+        else:
+            _copy_single(source_root, worktree_path, entry, result)
+
+    return result
+
+
+def get_copied_config_files(worktree_path: Path) -> list[Path]:
+    """Get list of untracked config files in worktree that match allowlist.
+
+    Used for cleanup to identify which files can be safely removed.
+    Only returns files that are NOT tracked by git. Handles both exact
+    paths and glob patterns in the allowlist.
+
+    Args:
+        worktree_path: Path to worktree.
+
+    Returns:
+        List of existing untracked config file paths.
+    """
+    config_files: list[Path] = []
+
+    for entry in DEFAULT_CONFIG_ALLOWLIST:
+        if _is_glob_pattern(entry):
+            for rel_path in _resolve_glob(worktree_path, entry):
+                file_path = worktree_path / rel_path
+                if file_path.is_dir():
+                    config_files.append(file_path)
+                elif file_path.is_file() and not is_file_tracked(rel_path, worktree_path):
+                    config_files.append(file_path)
+        else:
+            file_path = worktree_path / entry
+            if file_path.is_dir():
+                config_files.append(file_path)
+            elif file_path.is_file() and not is_file_tracked(Path(entry), worktree_path):
+                config_files.append(file_path)
+
+    return config_files