scc-cli 1.5.3__py3-none-any.whl

scc_cli/services/git/__init__.py

@@ -0,0 +1,79 @@
+"""Git services - data operations without UI dependencies.
+
+This package contains pure data functions for git operations.
+UI rendering is handled separately in ui/git_render.py.
+"""
+
+from .branch import (
+    PROTECTED_BRANCHES,
+    get_current_branch,
+    get_default_branch,
+    get_display_branch,
+    get_uncommitted_files,
+    is_protected_branch,
+    list_branches_without_worktrees,
+    sanitize_branch_name,
+)
+from .core import (
+    check_git_available,
+    check_git_installed,
+    create_empty_initial_commit,
+    detect_workspace_root,
+    get_git_version,
+    has_commits,
+    has_remote,
+    init_repo,
+    is_file_ignored,
+    is_git_repo,
+)
+from .hooks import (
+    SCC_HOOK_MARKER,
+    install_pre_push_hook,
+    is_scc_hook,
+)
+from .worktree import (
+    WorktreeInfo,
+    find_main_worktree,
+    find_worktree_by_query,
+    get_workspace_mount_path,
+    get_worktree_main_repo,
+    get_worktree_status,
+    get_worktrees_data,
+    is_worktree,
+)
+
+__all__ = [
+    # Core
+    "check_git_available",
+    "check_git_installed",
+    "get_git_version",
+    "is_git_repo",
+    "is_file_ignored",
+    "has_commits",
+    "init_repo",
+    "create_empty_initial_commit",
+    "has_remote",
+    "detect_workspace_root",
+    # Branch
+    "PROTECTED_BRANCHES",
+    "is_protected_branch",
+    "get_current_branch",
+    "get_default_branch",
+    "sanitize_branch_name",
+    "get_display_branch",
+    "get_uncommitted_files",
+    "list_branches_without_worktrees",
+    # Worktree
+    "WorktreeInfo",
+    "get_worktrees_data",
+    "get_worktree_status",
+    "is_worktree",
+    "get_worktree_main_repo",
+    "get_workspace_mount_path",
+    "find_worktree_by_query",
+    "find_main_worktree",
+    # Hooks
+    "SCC_HOOK_MARKER",
+    "is_scc_hook",
+    "install_pre_push_hook",
+]

scc_cli/services/git/branch.py

@@ -0,0 +1,151 @@
+"""Branch operations - safety checks, naming, queries.
+
+Pure functions with no UI dependencies.
+"""
+
+import re
+from pathlib import Path
+
+from ...core.constants import WORKTREE_BRANCH_PREFIX
+from ...subprocess_utils import run_command, run_command_bool, run_command_lines
+
+PROTECTED_BRANCHES = ("main", "master", "develop", "production", "staging")
+
+
+def is_protected_branch(branch: str) -> bool:
+    """Check if branch is protected.
+
+    Protected branches are: main, master, develop, production, staging.
+    """
+    return branch in PROTECTED_BRANCHES
+
+
+def get_current_branch(path: Path) -> str | None:
+    """Get the current branch name."""
+    return run_command(["git", "-C", str(path), "branch", "--show-current"], timeout=5)
+
+
+def get_default_branch(path: Path) -> str:
+    """Get the default branch for worktree creation.
+
+    Resolution order:
+    1. Current branch (respects user's git init.defaultBranch config)
+    2. Remote origin HEAD (for cloned repositories)
+    3. Check if main or master exists locally
+    4. Fallback to "main"
+
+    This order ensures freshly initialized repos use their actual branch
+    name rather than assuming "main".
+    """
+    # Priority 1: Use current branch (best for local-only repos)
+    current = get_current_branch(path)
+    if current:
+        return current
+
+    # Priority 2: Try to get from remote HEAD (for cloned repos)
+    output = run_command(
+        ["git", "-C", str(path), "symbolic-ref", "refs/remotes/origin/HEAD"],
+        timeout=5,
+    )
+    if output:
+        return output.split("/")[-1]
+
+    # Priority 3: Check if main or master exists locally
+    for branch in ["main", "master"]:
+        if run_command_bool(
+            ["git", "-C", str(path), "rev-parse", "--verify", branch],
+            timeout=5,
+        ):
+            return branch
+
+    return "main"
+
+
+def sanitize_branch_name(name: str) -> str:
+    """Sanitize a name for use as a branch/directory name.
+
+    Converts input to a safe format for git branch names and filesystem directories.
+    Path separators (/ and \\) are replaced with hyphens to prevent collisions.
+
+    Examples:
+        >>> sanitize_branch_name("feature/auth")
+        'feature-auth'
+        >>> sanitize_branch_name("Feature Auth")
+        'feature-auth'
+    """
+    safe = name.lower()
+    # Replace path separators with hyphens FIRST (collision fix)
+    safe = safe.replace("/", "-").replace("\\", "-")
+    # Replace spaces with hyphens
+    safe = safe.replace(" ", "-")
+    # Remove invalid characters (only a-z, 0-9, - allowed)
+    safe = re.sub(r"[^a-z0-9-]", "", safe)
+    # Collapse multiple hyphens
+    safe = re.sub(r"-+", "-", safe)
+    # Strip leading/trailing hyphens
+    return safe.strip("-")
+
+
+def get_display_branch(branch: str) -> str:
+    """Get user-friendly branch name (strip worktree prefixes if present).
+
+    Strips both `scc/` (current) and `claude/` (legacy) prefixes for cleaner display.
+    This is display-only; matching rules still require `scc/` prefix for new branches.
+
+    Args:
+        branch: The full branch name.
+
+    Returns:
+        Branch name with worktree prefix stripped for display.
+    """
+    # Strip both current (scc/) and legacy (claude/) prefixes for display
+    for prefix in (WORKTREE_BRANCH_PREFIX, "claude/"):
+        if branch.startswith(prefix):
+            return branch[len(prefix) :]
+    return branch
+
+
+def get_uncommitted_files(path: Path) -> list[str]:
+    """Get list of uncommitted files in a repository."""
+    lines = run_command_lines(
+        ["git", "-C", str(path), "status", "--porcelain"],
+        timeout=5,
+    )
+    # Each line is "XY filename" where XY is 2-char status code
+    return [line[3:] for line in lines if len(line) > 3]
+
+
+def list_branches_without_worktrees(repo_path: Path) -> list[str]:
+    """List remote branches that don't have local worktrees.
+
+    Args:
+        repo_path: Path to the repository.
+
+    Returns:
+        List of branch names (without origin/ prefix) that have no worktrees.
+    """
+    from .worktree import get_worktrees_data
+
+    # Get all remote branches
+    remote_output = run_command(
+        ["git", "-C", str(repo_path), "branch", "-r", "--format", "%(refname:short)"],
+        timeout=10,
+    )
+    if not remote_output:
+        return []
+
+    remote_branches = set()
+    for line in remote_output.strip().split("\n"):
+        line = line.strip()
+        if line and not line.endswith("/HEAD"):
+            # Remove origin/ prefix
+            if "/" in line:
+                branch = line.split("/", 1)[1]
+                remote_branches.add(branch)
+
+    # Get worktree branches
+    worktrees = get_worktrees_data(repo_path)
+    worktree_branches = {wt.branch for wt in worktrees if wt.branch}
+
+    # Return branches without worktrees
+    return sorted(remote_branches - worktree_branches)

scc_cli/services/git/core.py

@@ -0,0 +1,216 @@
+"""Core git operations - detection, initialization, repository management.
+
+Pure functions with no UI dependencies.
+"""
+
+import shutil
+from pathlib import Path
+
+from ...core.errors import GitNotFoundError
+from ...subprocess_utils import run_command, run_command_bool
+
+
+def check_git_available() -> None:
+    """Check if Git is installed and available.
+
+    Raises:
+        GitNotFoundError: Git is not installed or not in PATH
+    """
+    if shutil.which("git") is None:
+        raise GitNotFoundError()
+
+
+def check_git_installed() -> bool:
+    """Check if Git is installed (boolean for doctor command)."""
+    return shutil.which("git") is not None
+
+
+def get_git_version() -> str | None:
+    """Get Git version string for display."""
+    # Returns something like "git version 2.40.0"
+    return run_command(["git", "--version"], timeout=5)
+
+
+def is_git_repo(path: Path) -> bool:
+    """Check if path is inside a git repository."""
+    return run_command_bool(["git", "-C", str(path), "rev-parse", "--git-dir"], timeout=5)
+
+
+def has_commits(path: Path) -> bool:
+    """Check if the git repository has at least one commit.
+
+    This is important for worktree operations, which require at least
+    one commit to function properly.
+
+    Args:
+        path: Path to the git repository.
+
+    Returns:
+        True if the repository has at least one commit, False otherwise.
+    """
+    if not is_git_repo(path):
+        return False
+    # rev-parse HEAD fails if there are no commits
+    return run_command_bool(["git", "-C", str(path), "rev-parse", "HEAD"], timeout=5)
+
+
+def init_repo(path: Path) -> bool:
+    """Initialize a new git repository.
+
+    Args:
+        path: Path where to initialize the repository.
+
+    Returns:
+        True if initialization succeeded, False otherwise.
+    """
+    result = run_command(["git", "-C", str(path), "init"], timeout=10)
+    return result is not None
+
+
+def create_empty_initial_commit(path: Path) -> tuple[bool, str | None]:
+    """Create an empty initial commit to enable worktree operations.
+
+    Worktrees require at least one commit to function. This creates a
+    minimal empty commit without staging any files, following the
+    principle of not mutating user files without consent.
+
+    Args:
+        path: Path to the git repository.
+
+    Returns:
+        Tuple of (success, error_message). If success is False,
+        error_message contains details (e.g., git identity not configured).
+    """
+    result = run_command(
+        [
+            "git",
+            "-C",
+            str(path),
+            "commit",
+            "--allow-empty",
+            "-m",
+            "Initial commit",
+        ],
+        timeout=10,
+    )
+    if result is None:
+        # Check if it's a git identity issue
+        name_check = run_command(["git", "-C", str(path), "config", "user.name"], timeout=5)
+        email_check = run_command(["git", "-C", str(path), "config", "user.email"], timeout=5)
+        if not name_check or not email_check:
+            return (
+                False,
+                "Git identity not configured. Run:\n"
+                "  git config --global user.name 'Your Name'\n"
+                "  git config --global user.email 'you@example.com'",
+            )
+        return (False, "Failed to create initial commit")
+    return (True, None)
+
+
+def has_remote(path: Path, remote_name: str = "origin") -> bool:
+    """Check if the repository has a specific remote configured.
+
+    This is used to determine whether fetch operations should be attempted.
+    Freshly initialized repositories have no remotes.
+
+    Args:
+        path: Path to the git repository.
+        remote_name: Name of the remote to check (default: "origin").
+
+    Returns:
+        True if the remote exists, False otherwise.
+    """
+    if not is_git_repo(path):
+        return False
+    result = run_command(
+        ["git", "-C", str(path), "remote", "get-url", remote_name],
+        timeout=5,
+    )
+    return result is not None
+
+
+def detect_workspace_root(start_dir: Path) -> tuple[Path | None, Path]:
+    """Detect the workspace root from a starting directory.
+
+    This function implements smart workspace detection for use cases where
+    the user runs `scc start` from a subdirectory or git worktree.
+
+    Resolution order:
+    1) git rev-parse --show-toplevel (works for subdirs + worktrees)
+    2) Parent-walk for .scc.yaml (repo root config marker)
+    3) Parent-walk for .git (directory OR file - worktree-safe)
+    4) None (no workspace detected)
+
+    Args:
+        start_dir: The directory to start detection from (usually cwd).
+
+    Returns:
+        Tuple of (root, start_cwd) where:
+        - root: The detected workspace root, or None if not found
+        - start_cwd: The original start_dir (preserved for container cwd)
+    """
+    start_dir = start_dir.resolve()
+
+    # Priority 1: Use git rev-parse --show-toplevel (handles subdirs + worktrees)
+    if check_git_installed():
+        toplevel = run_command(
+            ["git", "-C", str(start_dir), "rev-parse", "--show-toplevel"],
+            timeout=5,
+        )
+        if toplevel:
+            return (Path(toplevel.strip()), start_dir)
+
+    # Priority 2: Parent-walk for .scc.yaml (SCC project marker)
+    current = start_dir
+    while current != current.parent:
+        scc_config = current / ".scc.yaml"
+        if scc_config.is_file():
+            return (current, start_dir)
+        current = current.parent
+
+    # Priority 3: Parent-walk for .git (directory OR file - worktree-safe)
+    current = start_dir
+    while current != current.parent:
+        git_marker = current / ".git"
+        if git_marker.exists():  # Works for both directory and file
+            return (current, start_dir)
+        current = current.parent
+
+    # No workspace detected
+    return (None, start_dir)
+
+
+def is_file_ignored(file_path: str | Path, repo_root: Path | None = None) -> bool:
+    """Check if a file path is ignored by git.
+
+    Uses git check-ignore to determine if the file would be ignored.
+    Returns False if git is not available or not in a git repo (fail-open).
+
+    Args:
+        file_path: The file path to check.
+        repo_root: The repository root. If None, uses current directory.
+
+    Returns:
+        True if the file is ignored by git, False otherwise.
+    """
+    import subprocess
+
+    cwd = str(repo_root) if repo_root else None
+
+    # Check if we're actually in a git repo
+    if repo_root and not (repo_root / ".git").exists():
+        return False
+
+    try:
+        result = subprocess.run(
+            ["git", "check-ignore", "-q", str(file_path)],
+            capture_output=True,
+            cwd=cwd,
+            timeout=5,
+        )
+        # Exit code 0 means file IS ignored
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        # git not available or other error - fail silently (fail-open)
+        return False

scc_cli/services/git/hooks.py

@@ -0,0 +1,108 @@
+"""Git hooks management - installation and detection.
+
+Pure functions with no UI dependencies.
+"""
+
+from pathlib import Path
+
+SCC_HOOK_MARKER = "# SCC-MANAGED-HOOK"  # Identifies hooks we can safely update
+
+
+def is_scc_hook(hook_path: Path) -> bool:
+    """Check if hook file is managed by SCC (has SCC marker).
+
+    Returns:
+        True if hook exists and contains SCC_HOOK_MARKER, False otherwise.
+    """
+    if not hook_path.exists():
+        return False
+    try:
+        content = hook_path.read_text()
+        return SCC_HOOK_MARKER in content
+    except (OSError, PermissionError):
+        return False
+
+
+def install_pre_push_hook(repo_path: Path) -> tuple[bool, str]:
+    """Install repo-local pre-push hook with strict rules.
+
+    Installation conditions:
+    1. User said yes in `scc setup` (hooks.enabled=true in config)
+    2. Repo is recognized (has .git directory)
+
+    Never:
+    - Modify global git config
+    - Overwrite existing non-SCC hooks
+
+    Args:
+        repo_path: Path to the git repository root
+
+    Returns:
+        Tuple of (success, message) describing the outcome
+    """
+    from ...config import load_user_config
+
+    # Condition 1: Check if hooks are enabled in user config
+    config = load_user_config()
+    if not config.get("hooks", {}).get("enabled", False):
+        return (False, "Hooks not enabled in config")
+
+    # Condition 2: Check if repo is recognized (has .git directory)
+    git_dir = repo_path / ".git"
+    if not git_dir.exists():
+        return (False, "Not a git repository")
+
+    # Determine hooks directory (repo-local, NOT global)
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / "pre-push"
+
+    # Check for existing hook
+    if hook_path.exists():
+        if is_scc_hook(hook_path):
+            # Safe to update our own hook
+            _write_scc_hook(hook_path)
+            return (True, "Updated existing SCC hook")
+        else:
+            # DON'T overwrite user's hook
+            return (
+                False,
+                f"Will not overwrite existing user hook at {hook_path}. "
+                f"To manually add SCC protection, add '{SCC_HOOK_MARKER}' marker to your hook.",
+            )
+
+    # No existing hook - safe to create
+    _write_scc_hook(hook_path)
+    return (True, "Installed new SCC hook")
+
+
+def _write_scc_hook(hook_path: Path) -> None:
+    """Write SCC pre-push hook content.
+
+    The hook blocks pushes to protected branches (main, master, develop, production, staging).
+    """
+    hook_content = f"""#!/bin/bash
+{SCC_HOOK_MARKER}
+# SCC pre-push hook - blocks pushes to protected branches
+# This hook is managed by SCC. You can safely delete it to remove protection.
+
+branch=$(git rev-parse --abbrev-ref HEAD)
+protected_branches="main master develop production staging"
+
+for protected in $protected_branches; do
+    if [ "$branch" = "$protected" ]; then
+        echo ""
+        echo "❌ Direct push to '$branch' blocked by SCC"
+        echo ""
+        echo "Create a feature branch first:"
+        echo "  git checkout -b scc/your-feature"
+        echo "  git push -u origin scc/your-feature"
+        echo ""
+        exit 1
+    fi
+done
+
+exit 0
+"""
+    hook_path.write_text(hook_content)
+    hook_path.chmod(0o755)