gitstow 0.1.0__py3-none-any.whl

gitstow/core/discovery.py

@@ -0,0 +1,116 @@
+"""Discovery — walk directory tree to find repos and reconcile with store.
+
+Supports two layout modes:
+  - structured: root/owner/repo/.git (two-level walk)
+  - flat: root/repo/.git (one-level walk)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from gitstow.core.git import is_git_repo, get_remote_url
+from gitstow.core.repo import Repo
+
+
+@dataclass
+class DiscoveredRepo:
+    """A git repo found on disk."""
+
+    key: str             # "owner/repo" (structured) or "repo" (flat)
+    owner: str           # "" for flat layout
+    name: str
+    path: Path
+    remote_url: str | None
+
+
+def discover_repos(root: Path, layout: str = "structured") -> list[DiscoveredRepo]:
+    """Walk a workspace directory looking for git repos.
+
+    Args:
+        root: The workspace path to scan.
+        layout: "structured" (root/owner/repo/.git) or "flat" (root/repo/.git).
+    """
+    if not root.is_dir():
+        return []
+
+    if layout == "flat":
+        return _discover_flat(root)
+    return _discover_structured(root)
+
+
+def _discover_structured(root: Path) -> list[DiscoveredRepo]:
+    """Two-level walk: root/owner/repo/.git. Skips hidden directories."""
+    found = []
+    for owner_dir in sorted(root.iterdir()):
+        if not owner_dir.is_dir() or owner_dir.name.startswith("."):
+            continue
+        for repo_dir in sorted(owner_dir.iterdir()):
+            if not repo_dir.is_dir() or repo_dir.name.startswith("."):
+                continue
+            if is_git_repo(repo_dir):
+                remote = get_remote_url(repo_dir)
+                found.append(DiscoveredRepo(
+                    key=f"{owner_dir.name}/{repo_dir.name}",
+                    owner=owner_dir.name,
+                    name=repo_dir.name,
+                    path=repo_dir,
+                    remote_url=remote,
+                ))
+    return found
+
+
+def _discover_flat(root: Path) -> list[DiscoveredRepo]:
+    """One-level walk: root/repo/.git. Skips hidden directories."""
+    found = []
+    for repo_dir in sorted(root.iterdir()):
+        if not repo_dir.is_dir() or repo_dir.name.startswith("."):
+            continue
+        if is_git_repo(repo_dir):
+            remote = get_remote_url(repo_dir)
+            found.append(DiscoveredRepo(
+                key=repo_dir.name,
+                owner="",
+                name=repo_dir.name,
+                path=repo_dir,
+                remote_url=remote,
+            ))
+    return found
+
+
+def reconcile(
+    on_disk: list[DiscoveredRepo],
+    in_store: dict[str, Repo],
+) -> dict:
+    """Compare disk vs store and return differences.
+
+    Returns:
+        {
+            "matched": list of keys that are in both,
+            "orphaned": list of dicts for repos on disk but not tracked,
+            "missing": list of keys for repos tracked but not on disk,
+        }
+    """
+    disk_keys = {r.key for r in on_disk}
+    store_keys = set(in_store.keys())
+
+    matched = sorted(disk_keys & store_keys)
+    orphaned_keys = sorted(disk_keys - store_keys)
+    missing_keys = sorted(store_keys - disk_keys)
+
+    disk_map = {r.key: r for r in on_disk}
+    orphaned = [
+        {
+            "key": key,
+            "path": str(disk_map[key].path),
+            "remote_url": disk_map[key].remote_url,
+        }
+        for key in orphaned_keys
+    ]
+
+    return {
+        "matched": matched,
+        "orphaned": orphaned,
+        "missing": missing_keys,
+    }

gitstow/core/git.py

@@ -0,0 +1,261 @@
+"""Git operations — thin wrappers around git subprocess calls.
+
+All git interaction goes through this module. Nothing else shells out to git.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class PullResult:
+    """Result of a git pull operation."""
+
+    success: bool
+    already_up_to_date: bool = False
+    error: str = ""
+    output: str = ""
+
+
+@dataclass
+class RepoStatus:
+    """Git status of a repository."""
+
+    branch: str = ""
+    dirty: int = 0            # Count of modified (unstaged) files
+    staged: int = 0           # Count of staged files
+    untracked: int = 0        # Count of untracked files
+    ahead: int = 0            # Commits ahead of upstream
+    behind: int = 0           # Commits behind upstream
+    has_upstream: bool = True  # Whether upstream is configured
+
+    @property
+    def clean(self) -> bool:
+        return self.dirty == 0 and self.staged == 0 and self.untracked == 0
+
+    @property
+    def status_symbol(self) -> str:
+        """Short status indicator: ✓ *+? etc."""
+        if self.clean:
+            return "✓"
+        parts = []
+        if self.dirty:
+            parts.append("*")
+        if self.staged:
+            parts.append("+")
+        if self.untracked:
+            parts.append("?")
+        return "".join(parts)
+
+    @property
+    def ahead_behind_str(self) -> str:
+        """Format ahead/behind as ↑3 ↓5 or —."""
+        parts = []
+        if self.ahead:
+            parts.append(f"↑{self.ahead}")
+        if self.behind:
+            parts.append(f"↓{self.behind}")
+        return " ".join(parts) if parts else "—"
+
+
+@dataclass
+class CommitInfo:
+    """Information about a single commit."""
+
+    hash: str = ""
+    message: str = ""
+    date: str = ""          # Relative date (e.g., "2 hours ago")
+    author: str = ""
+
+
+def _run_git(
+    args: list[str],
+    cwd: Path | None = None,
+    timeout: int = 60,
+) -> subprocess.CompletedProcess:
+    """Run a git command and return the result."""
+    cmd = ["git"] + args
+    return subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def is_git_installed() -> tuple[bool, str]:
+    """Check if git is installed and return version."""
+    try:
+        result = _run_git(["--version"])
+        if result.returncode == 0:
+            version = result.stdout.strip().replace("git version ", "")
+            return True, version
+        return False, ""
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False, ""
+
+
+def is_git_repo(path: Path) -> bool:
+    """Check if a path is a git repository."""
+    git_dir = path / ".git"
+    return git_dir.exists() and (git_dir.is_dir() or git_dir.is_file())
+
+
+def clone(
+    url: str,
+    target: Path,
+    shallow: bool = False,
+    branch: str | None = None,
+    recursive: bool = False,
+) -> tuple[bool, str]:
+    """Clone a repository.
+
+    Returns:
+        (success, error_message)
+    """
+    args = ["clone", "--progress"]
+    if shallow:
+        args.extend(["--depth", "1"])
+    if branch:
+        args.extend(["--branch", branch, "--single-branch"])
+    if recursive:
+        args.append("--recurse-submodules")
+    args.extend(["--", url, str(target)])
+
+    try:
+        result = _run_git(args, timeout=300)  # 5 min for large repos
+        if result.returncode == 0:
+            return True, ""
+        return False, result.stderr.strip()
+    except subprocess.TimeoutExpired:
+        return False, "Clone timed out (5 minutes)"
+
+
+def pull(repo_path: Path) -> PullResult:
+    """Pull latest changes (fast-forward only).
+
+    Returns PullResult with success/error status.
+    """
+    try:
+        result = _run_git(["pull", "--ff-only"], cwd=repo_path, timeout=120)
+        output = result.stdout.strip()
+        stderr = result.stderr.strip()
+
+        if result.returncode == 0:
+            up_to_date = "Already up to date" in output or "Already up-to-date" in output
+            return PullResult(
+                success=True,
+                already_up_to_date=up_to_date,
+                output=output,
+            )
+        else:
+            return PullResult(success=False, error=stderr or output)
+    except subprocess.TimeoutExpired:
+        return PullResult(success=False, error="Pull timed out (2 minutes)")
+
+
+def get_status(repo_path: Path) -> RepoStatus:
+    """Get full repository status in a single git call.
+
+    Uses `git status --porcelain=v2 --branch` which gives:
+    - Branch name and upstream tracking
+    - Ahead/behind counts
+    - Per-file status (modified, staged, untracked)
+
+    This is ONE subprocess call vs gita's 4-5 separate calls.
+    """
+    result = _run_git(["status", "--porcelain=v2", "--branch"], cwd=repo_path)
+    if result.returncode != 0:
+        # Fallback: just get the branch name
+        branch_result = _run_git(["branch", "--show-current"], cwd=repo_path)
+        return RepoStatus(branch=branch_result.stdout.strip() or "unknown")
+
+    status = RepoStatus()
+    for line in result.stdout.splitlines():
+        if line.startswith("# branch.head "):
+            status.branch = line.split(" ", 2)[2]
+        elif line.startswith("# branch.ab "):
+            # Format: # branch.ab +3 -5
+            parts = line.split()
+            if len(parts) >= 4:
+                status.ahead = int(parts[2].lstrip("+"))
+                status.behind = abs(int(parts[3]))
+        elif line.startswith("# branch.upstream "):
+            status.has_upstream = True
+        elif line.startswith("1 ") or line.startswith("2 "):
+            # Changed entry: 1 XY ... or 2 XY ...
+            # X = staged, Y = unstaged
+            xy = line.split(" ")[1]
+            if len(xy) >= 2:
+                if xy[0] != ".":
+                    status.staged += 1
+                if xy[1] != ".":
+                    status.dirty += 1
+        elif line.startswith("? "):
+            status.untracked += 1
+        elif line.startswith("u "):
+            # Unmerged entry — count as dirty
+            status.dirty += 1
+
+    # Detect if no upstream is set (branch.upstream line is absent)
+    if "# branch.upstream" not in result.stdout:
+        status.has_upstream = False
+
+    return status
+
+
+def get_remote_url(repo_path: Path) -> str | None:
+    """Get the remote origin URL."""
+    result = _run_git(["remote", "get-url", "origin"], cwd=repo_path)
+    if result.returncode == 0:
+        return result.stdout.strip()
+    return None
+
+
+def get_last_commit(repo_path: Path) -> CommitInfo:
+    """Get info about the last commit."""
+    result = _run_git(
+        ["log", "-1", "--format=%h%n%s%n%cd%n%an", "--date=relative"],
+        cwd=repo_path,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        return CommitInfo()
+
+    lines = result.stdout.strip().splitlines()
+    return CommitInfo(
+        hash=lines[0] if len(lines) > 0 else "",
+        message=lines[1] if len(lines) > 1 else "",
+        date=lines[2] if len(lines) > 2 else "",
+        author=lines[3] if len(lines) > 3 else "",
+    )
+
+
+def get_branch(repo_path: Path) -> str:
+    """Get the current branch name."""
+    result = _run_git(["branch", "--show-current"], cwd=repo_path)
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    # Detached HEAD — try to get the short hash
+    result = _run_git(["rev-parse", "--short", "HEAD"], cwd=repo_path)
+    return f"({result.stdout.strip()})" if result.returncode == 0 else "unknown"
+
+
+def get_disk_size(path: Path) -> int:
+    """Get total disk size of a directory in bytes."""
+    total = sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+    return total
+
+
+def format_size(size_bytes: int) -> str:
+    """Format bytes as human-readable size."""
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.0f} {unit}" if unit == "B" else f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"

gitstow/core/parallel.py

@@ -0,0 +1,85 @@
+"""Parallel execution — async operations with bounded concurrency.
+
+Uses asyncio with a semaphore to prevent SSH connection storms
+(gita's biggest complaint: 87 repos opens 87 SSH connections simultaneously).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class TaskResult:
+    """Result of a single parallel task."""
+
+    key: str                # Identifier (e.g., "owner/repo")
+    success: bool
+    data: Any = None        # The result value on success
+    error: str = ""         # Error message on failure
+
+
+async def _run_in_executor(
+    func: Callable,
+    *args,
+    **kwargs,
+) -> Any:
+    """Run a blocking function in the default thread pool executor."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, lambda: func(*args, **kwargs))
+
+
+async def run_parallel(
+    tasks: list[tuple[str, Callable]],
+    max_concurrent: int = 6,
+    on_progress: Callable[[str, bool, str], None] | None = None,
+) -> list[TaskResult]:
+    """Run tasks concurrently with bounded concurrency.
+
+    Args:
+        tasks: List of (key, callable) pairs. Each callable takes no args.
+        max_concurrent: Maximum concurrent operations (semaphore size).
+        on_progress: Optional callback(key, success, message) called after each task.
+
+    Returns:
+        List of TaskResult in the same order as input tasks.
+    """
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def bounded_task(key: str, func: Callable) -> TaskResult:
+        async with semaphore:
+            try:
+                result = await _run_in_executor(func)
+                task_result = TaskResult(key=key, success=True, data=result)
+            except Exception as e:
+                task_result = TaskResult(key=key, success=False, error=str(e))
+
+            if on_progress:
+                on_progress(
+                    key,
+                    task_result.success,
+                    task_result.error or "OK",
+                )
+            return task_result
+
+    gathered = await asyncio.gather(
+        *[bounded_task(key, func) for key, func in tasks],
+        return_exceptions=False,
+    )
+    return list(gathered)
+
+
+def run_parallel_sync(
+    tasks: list[tuple[str, Callable]],
+    max_concurrent: int = 6,
+    on_progress: Callable[[str, bool, str], None] | None = None,
+) -> list[TaskResult]:
+    """Synchronous wrapper for run_parallel.
+
+    Use this from non-async CLI code.
+    """
+    return asyncio.run(run_parallel(tasks, max_concurrent, on_progress))

gitstow/core/paths.py

@@ -0,0 +1,51 @@
+"""All path constants for gitstow."""
+
+from importlib.resources import files as pkg_files
+from pathlib import Path
+
+# App home — hidden config directory (always in home dir)
+APP_HOME = Path.home() / ".gitstow"
+CONFIG_FILE = APP_HOME / "config.yaml"
+
+# Central repos file — always in app home (since workspace support)
+REPOS_FILE = APP_HOME / "repos.yaml"
+
+# Legacy location: root/.gitstow/repos.yaml (pre-workspace, v0.2.0 era)
+# Migrated to central REPOS_FILE on first access.
+LEGACY_REPOS_FILE = REPOS_FILE  # alias for imports that used this name
+
+# Default root for repos (used when no workspaces configured)
+DEFAULT_ROOT = Path.home() / "opensource"
+
+# Claude Code skill installation paths
+CLAUDE_HOME = Path.home() / ".claude"
+CLAUDE_SKILLS_DIR = CLAUDE_HOME / "skills"
+SKILL_TARGET = CLAUDE_SKILLS_DIR / "gitstow"
+
+
+def get_repos_file(root: Path | None = None) -> Path:
+    """Get the repos.yaml path.
+
+    Since workspace support, repos.yaml is always central at ~/.gitstow/repos.yaml.
+    Auto-migrates from the old root/.gitstow/repos.yaml location if found.
+    """
+    # Auto-migrate from old per-root location
+    if root is not None:
+        old_path = root / ".gitstow" / "repos.yaml"
+        if old_path.exists() and not REPOS_FILE.exists():
+            REPOS_FILE.parent.mkdir(parents=True, exist_ok=True)
+            import shutil
+            shutil.copy2(old_path, REPOS_FILE)
+            old_path.rename(old_path.with_suffix(".yaml.migrated"))
+
+    return REPOS_FILE
+
+
+def get_skill_source_dir():
+    """Return path to bundled skill files in the package."""
+    return pkg_files("gitstow").joinpath("skill")
+
+
+def ensure_app_dirs() -> None:
+    """Create required app directories if they don't exist."""
+    APP_HOME.mkdir(parents=True, exist_ok=True)