gitstow 0.1.0__py3-none-any.whl

gitstow/__init__.py

@@ -0,0 +1,3 @@
+"""gitstow — a git repository library manager."""
+
+__version__ = "0.1.0"

gitstow/__main__.py

@@ -0,0 +1,11 @@
+"""Allow running as `python -m gitstow`.
+
+Useful on Windows when the Scripts directory is not on PATH:
+
+    python -m gitstow onboard
+    python -m gitstow add owner/repo
+"""
+
+from gitstow.cli.main import app
+
+app()

gitstow/cli/__init__.py

@@ -0,0 +1 @@
+"""gitstow CLI — Typer command layer."""

gitstow/cli/add.py

@@ -0,0 +1,262 @@
+"""gitstow add — clone repos into the organized structure."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from gitstow.core.config import load_config
+from gitstow.core.url_parser import parse_git_url
+from gitstow.core.git import clone as git_clone, is_git_repo, get_remote_url
+from gitstow.core.repo import Repo, RepoStore
+from gitstow.cli.helpers import resolve_workspaces
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def add(
+    ctx: typer.Context,
+    urls: list[str] = typer.Argument(
+        default=None,
+        help="Git URLs or owner/repo shorthand. Reads from stdin if omitted.",
+    ),
+    shallow: bool = typer.Option(
+        False, "--shallow", "-s", help="Shallow clone (--depth 1)."
+    ),
+    branch: Optional[str] = typer.Option(
+        None, "--branch", "-b", help="Clone specific branch."
+    ),
+    update: bool = typer.Option(
+        False, "--update", "-u", help="Pull if repo already exists."
+    ),
+    tag: Optional[list[str]] = typer.Option(
+        None, "--tag", "-t", help="Tag(s) to apply to added repos."
+    ),
+    recursive: bool = typer.Option(
+        False, "--recursive", "-r", help="Initialize submodules after clone."
+    ),
+    ssh: bool = typer.Option(
+        False, "--ssh", help="Force SSH clone URL."
+    ),
+    retry: int = typer.Option(
+        0, "--retry", help="Retry failed clones N times."
+    ),
+    output_json: bool = typer.Option(
+        False, "--json", "-j", help="JSON output."
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Suppress progress messages."
+    ),
+) -> None:
+    """[bold green]Add[/bold green] repos — clone into organized structure.
+
+    Accepts full URLs, SSH URLs, or shorthand (owner/repo assumes GitHub).
+    Uses the default workspace unless -w is specified.
+
+    \b
+    Examples:
+      gitstow add anthropic/claude-code
+      gitstow add https://github.com/facebook/react
+      gitstow add -w active anthropic/claude-code
+      cat urls.txt | gitstow add
+    """
+    settings = load_config()
+    store = RepoStore()
+    ws_label = ctx.obj.get("workspace") if ctx.obj else None
+    ws_list = resolve_workspaces(settings, ws_label)
+    ws = ws_list[0]  # Use the specified or default workspace
+    root = ws.get_path()
+    tags = list(tag or []) + list(ws.auto_tags)
+
+    # Read from stdin if no URLs provided and stdin is piped
+    if not urls:
+        if sys.stdin.isatty():
+            err_console.print("[red]Error:[/red] No URLs provided. Pass URLs as arguments or pipe via stdin.")
+            raise typer.Exit(code=1)
+        urls = [line.strip() for line in sys.stdin if line.strip() and not line.startswith("#")]
+
+    if not urls:
+        err_console.print("[red]Error:[/red] No URLs to add.")
+        raise typer.Exit(code=1)
+
+    # Parse all URLs first (fail fast on bad input)
+    parsed_urls = []
+    for url in urls:
+        try:
+            parsed = parse_git_url(
+                url,
+                default_host=settings.default_host,
+                prefer_ssh=ssh or settings.prefer_ssh,
+            )
+            parsed_urls.append(parsed)
+        except ValueError as e:
+            err_console.print(f"[red]Error:[/red] {e}")
+            if output_json:
+                json.dump({"success": False, "error": str(e), "url": url}, sys.stdout, indent=2)
+            raise typer.Exit(code=1)
+
+    results = []
+
+    for parsed in parsed_urls:
+        # Determine target path based on workspace layout
+        if ws.layout == "flat":
+            target = root / parsed.repo
+            repo_owner = ""  # Flat layout stores no owner in path
+        else:
+            target = root / parsed.owner / parsed.repo
+            repo_owner = parsed.owner
+
+        repo_key = f"{repo_owner}/{parsed.repo}" if repo_owner else parsed.repo
+        existing = store.get(repo_key, workspace=ws.label)
+
+        # Already tracked in this workspace
+        if existing:
+            if update:
+                if not quiet:
+                    console.print(f"  [dim]Updating[/dim] {repo_key}...")
+                from gitstow.core.git import pull as git_pull
+                pull_result = git_pull(target)
+                if pull_result.success:
+                    from datetime import datetime
+                    store.update(repo_key, workspace=ws.label, last_pulled=datetime.now().isoformat())
+                    results.append({"repo": repo_key, "status": "updated"})
+                    if not quiet:
+                        console.print(f"  [green]✓[/green] {repo_key} updated")
+                else:
+                    results.append({"repo": repo_key, "status": "error", "error": pull_result.error})
+                    if not quiet:
+                        err_console.print(f"  [red]✗[/red] {repo_key}: {pull_result.error}")
+            else:
+                results.append({"repo": repo_key, "status": "exists"})
+                if not quiet:
+                    console.print(f"  [yellow]○[/yellow] {repo_key} already tracked. Use --update to pull.")
+            continue
+
+        # Path exists on disk but not tracked
+        if target.exists() and is_git_repo(target):
+            remote = get_remote_url(target)
+            if remote:
+                repo = Repo(
+                    owner=repo_owner,
+                    name=parsed.repo,
+                    remote_url=remote,
+                    workspace=ws.label,
+                    tags=list(tags),
+                )
+                store.add(repo)
+                results.append({"repo": repo_key, "status": "registered"})
+                if not quiet:
+                    console.print(f"  [green]✓[/green] {repo_key} registered (already on disk)")
+                continue
+
+        # Path exists but is not a git repo
+        if target.exists() and not is_git_repo(target):
+            results.append({"repo": repo_key, "status": "error", "error": "Path exists but is not a git repo"})
+            if not quiet:
+                err_console.print(f"  [red]✗[/red] {repo_key}: path exists but is not a git repo")
+            continue
+
+        # Clone (with retry)
+        if not quiet:
+            console.print(f"  [dim]Cloning[/dim] {repo_key} → {ws.label}...")
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        success, error = False, ""
+        for attempt in range(1 + retry):
+            if attempt > 0:
+                # Clean up partial clone before retrying
+                import shutil
+                if target.exists():
+                    shutil.rmtree(target, ignore_errors=True)
+                if not quiet:
+                    err_console.print(f"    [dim]Retry {attempt}/{retry}...[/dim]")
+            success, error = git_clone(
+                url=parsed.clone_url,
+                target=target,
+                shallow=shallow,
+                branch=branch,
+                recursive=recursive,
+            )
+            if success:
+                break
+
+        if success:
+            from datetime import datetime
+            repo = Repo(
+                owner=repo_owner,
+                name=parsed.repo,
+                remote_url=parsed.clone_url,
+                workspace=ws.label,
+                tags=list(tags),
+                last_pulled=datetime.now().isoformat(),
+            )
+            store.add(repo)
+            results.append({"repo": repo_key, "status": "cloned"})
+            if not quiet:
+                console.print(f"  [green]✓[/green] {repo_key} cloned")
+        else:
+            results.append({"repo": repo_key, "status": "error", "error": error})
+            if not quiet:
+                err_console.print(f"  [red]✗[/red] {repo_key}: {error}")
+                hint = _clone_error_hint(error)
+                if hint:
+                    err_console.print(f"      [dim]{hint}[/dim]")
+
+    # Summary
+    if output_json:
+        cloned = sum(1 for r in results if r["status"] == "cloned")
+        registered = sum(1 for r in results if r["status"] == "registered")
+        errors = sum(1 for r in results if r["status"] == "error")
+        json.dump(
+            {
+                "total": len(results),
+                "cloned": cloned,
+                "registered": registered,
+                "errors": errors,
+                "results": results,
+            },
+            sys.stdout,
+            indent=2,
+        )
+        print()
+    elif not quiet and len(results) > 1:
+        cloned = sum(1 for r in results if r["status"] == "cloned")
+        registered = sum(1 for r in results if r["status"] == "registered")
+        existed = sum(1 for r in results if r["status"] == "exists")
+        errors = sum(1 for r in results if r["status"] == "error")
+        console.print()
+        parts = []
+        if cloned:
+            parts.append(f"[green]{cloned} cloned[/green]")
+        if registered:
+            parts.append(f"[green]{registered} registered[/green]")
+        if existed:
+            parts.append(f"[yellow]{existed} already tracked[/yellow]")
+        if errors:
+            parts.append(f"[red]{errors} failed[/red]")
+        console.print(f"  Done: {' | '.join(parts)}")
+
+    if any(r["status"] == "error" for r in results):
+        raise typer.Exit(code=1)
+
+
+def _clone_error_hint(error: str) -> str:
+    """Return a user-friendly hint based on common clone error patterns."""
+    err = error.lower()
+    if "permission denied (publickey)" in err:
+        return "Hint: SSH key not configured. Try --ssh=false or check ssh-add -l"
+    if "repository not found" in err or "does not exist" in err:
+        return "Hint: Check the URL. If this is a private repo, ensure you have access."
+    if "timed out" in err:
+        return "Hint: Try --shallow for large repos, or check your network connection."
+    if "could not resolve host" in err:
+        return "Hint: DNS resolution failed. Check your network connection."
+    if "already exists and is not an empty directory" in err:
+        return "Hint: Target directory already exists. Use --update to pull instead."
+    return ""

gitstow/cli/config_cmd.py

@@ -0,0 +1,235 @@
+"""gitstow config — view and modify settings."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+from gitstow.core.config import load_config, save_config
+from gitstow.core.paths import CONFIG_FILE, REPOS_FILE
+from gitstow.core.repo import RepoStore
+
+config_app = typer.Typer(
+    help="View and modify gitstow settings.",
+    no_args_is_help=True,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+@config_app.command("show")
+def config_show(
+    output_json: bool = typer.Option(False, "--json", "-j", help="JSON output."),
+) -> None:
+    """Show current configuration."""
+    settings = load_config()
+    store = RepoStore()
+
+    if output_json:
+        data = settings.to_dict()
+        data["config_file"] = str(CONFIG_FILE)
+        data["repos_file"] = str(REPOS_FILE)
+        data["repos_tracked"] = store.count()
+        json.dump(data, sys.stdout, indent=2)
+        print()
+        return
+
+    console.print("\n  [bold]gitstow config[/bold]\n")
+
+    rows = [
+        ("default_host", settings.default_host),
+        ("prefer_ssh", str(settings.prefer_ssh).lower()),
+        ("parallel_limit", str(settings.parallel_limit)),
+    ]
+
+    max_label = max(len(r[0]) for r in rows)
+    for label, value in rows:
+        console.print(f"    {label.ljust(max_label + 2)}{value}")
+
+    console.print()
+
+    # Show workspaces
+    workspaces = settings.get_workspaces()
+    console.print(f"    [bold]Workspaces ({len(workspaces)}):[/bold]")
+    ws_counts = store.all_workspaces()
+    for ws in workspaces:
+        count = ws_counts.get(ws.label, 0)
+        tags_str = f"  auto_tags: [{', '.join(ws.auto_tags)}]" if ws.auto_tags else ""
+        console.print(f"      [cyan]{ws.label}[/cyan] — {ws.path} ({ws.layout}, {count} repos){tags_str}")
+
+    console.print()
+    console.print(f"    [dim]Config file:   {CONFIG_FILE}[/dim]")
+    console.print(f"    [dim]Repos file:    {REPOS_FILE}[/dim]")
+    console.print(f"    [dim]Repos tracked: {store.count()}[/dim]")
+    console.print()
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(help="Setting key (root_path, default_host, prefer_ssh, parallel_limit)."),
+    value: str = typer.Argument(help="New value."),
+) -> None:
+    """Set a configuration value.
+
+    \b
+    Examples:
+      gitstow config set root_path ~/labs/OSS
+      gitstow config set default_host gitlab.com
+      gitstow config set prefer_ssh true
+      gitstow config set parallel_limit 8
+    """
+    settings = load_config()
+
+    valid_keys = {"default_host", "prefer_ssh", "parallel_limit"}
+    if key not in valid_keys:
+        err_console.print(
+            f"[red]Error:[/red] Unknown key '{key}'. Valid keys: {', '.join(sorted(valid_keys))}\n"
+            f"  [dim]Use 'gitstow workspace add/remove' to manage workspace paths.[/dim]"
+        )
+        raise typer.Exit(code=1)
+
+    if key == "prefer_ssh":
+        if value.lower() in ("true", "yes", "1"):
+            setattr(settings, key, True)
+        elif value.lower() in ("false", "no", "0"):
+            setattr(settings, key, False)
+        else:
+            err_console.print("[red]Error:[/red] prefer_ssh must be true or false.")
+            raise typer.Exit(code=1)
+    elif key == "parallel_limit":
+        try:
+            setattr(settings, key, int(value))
+        except ValueError:
+            err_console.print("[red]Error:[/red] parallel_limit must be a number.")
+            raise typer.Exit(code=1)
+    else:
+        setattr(settings, key, value)
+
+    save_config(settings)
+    console.print(f"  [green]✓[/green] {key} = {value}")
+
+
+@config_app.command("path")
+def config_path() -> None:
+    """Show the config file path."""
+    console.print(str(CONFIG_FILE))
+
+
+@config_app.command("migrate-root")
+def config_migrate_root(
+    new_root: str = typer.Argument(help="New root path for repos."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+    copy: bool = typer.Option(False, "--copy", help="Copy instead of move (keeps old root)."),
+) -> None:
+    """Move all repos to a new root directory.
+
+    Moves (or copies) every repo from the current root to the new root,
+    preserving the owner/repo structure, and updates the config.
+
+    \b
+    Examples:
+      gitstow config migrate-root ~/new-location
+      gitstow config migrate-root ~/new-location --copy
+    """
+    import shutil
+    from pathlib import Path
+
+    from gitstow.core.git import is_git_repo
+
+    settings = load_config()
+    store = RepoStore()
+    old_root = settings.get_root()
+    new_root_path = Path(new_root).expanduser().resolve()
+
+    if old_root == new_root_path:
+        console.print("  [dim]New root is the same as current root. Nothing to do.[/dim]")
+        return
+
+    repos = store.list_all()
+    if not repos:
+        # No repos — just update the pointer
+        settings.root_path = str(new_root_path)
+        save_config(settings)
+        new_root_path.mkdir(parents=True, exist_ok=True)
+        console.print(f"  [green]✓[/green] Root updated to {new_root_path} (no repos to move).")
+        return
+
+    # Show what will happen
+    action = "Copy" if copy else "Move"
+    console.print(f"\n  [bold]{action} {len(repos)} repos[/bold]\n")
+    console.print(f"    From: {old_root}")
+    console.print(f"    To:   {new_root_path}\n")
+
+    # Check which repos actually exist on disk
+    movable = []
+    missing = []
+    for repo in repos:
+        src = repo.get_path(old_root)
+        if src.exists() and is_git_repo(src):
+            movable.append(repo)
+        else:
+            missing.append(repo)
+
+    if missing:
+        console.print(f"  [yellow]⚠ {len(missing)} repos not found on disk (will update config only):[/yellow]")
+        for r in missing:
+            console.print(f"    {r.key}")
+        console.print()
+
+    console.print(f"  {len(movable)} repos to {action.lower()}")
+
+    if not yes:
+        if not typer.confirm(f"\n  Proceed with {action.lower()}?"):
+            console.print("  [dim]Cancelled.[/dim]")
+            raise typer.Exit()
+
+    # Create new root
+    new_root_path.mkdir(parents=True, exist_ok=True)
+
+    # Move/copy each repo
+    succeeded = 0
+    failed = 0
+    for repo in movable:
+        src = repo.get_path(old_root)
+        dst = repo.get_path(new_root_path)
+        dst.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            if dst.exists():
+                console.print(f"  [yellow]⚠[/yellow] {repo.key}: target already exists, skipping")
+                continue
+
+            if copy:
+                shutil.copytree(src, dst, symlinks=True)
+            else:
+                try:
+                    src.rename(dst)
+                except OSError:
+                    # Cross-device: copy + delete
+                    shutil.copytree(src, dst, symlinks=True)
+                    shutil.rmtree(src)
+
+            succeeded += 1
+            console.print(f"  [green]✓[/green] {repo.key}")
+        except Exception as e:
+            failed += 1
+            err_console.print(f"  [red]✗[/red] {repo.key}: {e}")
+
+    # Update config
+    settings.root_path = str(new_root_path)
+    save_config(settings)
+
+    # Clean up empty owner dirs in old root (if moved, not copied)
+    if not copy and old_root.exists():
+        for owner_dir in old_root.iterdir():
+            if owner_dir.is_dir() and not any(owner_dir.iterdir()):
+                owner_dir.rmdir()
+
+    console.print(f"\n  Done: {succeeded} {action.lower()}d", end="")
+    if failed:
+        console.print(f", [red]{failed} failed[/red]", end="")
+    console.print(f"\n  Root updated to: {new_root_path}\n")

gitstow/cli/doctor.py

@@ -0,0 +1,163 @@
+"""gitstow doctor — health check."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+from gitstow import __version__
+from gitstow.core.config import load_config
+from gitstow.core.paths import APP_HOME, CONFIG_FILE, get_repos_file
+from gitstow.core.git import is_git_installed
+from gitstow.core.repo import RepoStore
+from gitstow.core.discovery import discover_repos, reconcile
+
+console = Console()
+
+
+def doctor(
+    output_json: bool = typer.Option(False, "--json", "-j", help="JSON output."),
+) -> None:
+    """[bold]Check[/bold] system health — git, config, and repo integrity."""
+    settings = load_config()
+    store = RepoStore()
+    workspaces = settings.get_workspaces()
+
+    checks: dict = {}
+
+    # 1. System
+    git_ok, git_version = is_git_installed()
+    checks["system"] = {
+        "git_installed": git_ok,
+        "git_version": git_version,
+        "gitstow_version": __version__,
+    }
+
+    # 2. Configuration
+    repos_file = get_repos_file()
+    checks["config"] = {
+        "app_dir_exists": APP_HOME.exists(),
+        "config_file_exists": CONFIG_FILE.exists(),
+        "repos_file_exists": repos_file.exists(),
+        "repos_file_path": str(repos_file),
+        "workspaces": len(workspaces),
+        "repos_tracked": store.count(),
+    }
+
+    # 3. Per-workspace repo integrity
+    checks["workspaces"] = {}
+    total_on_disk = 0
+    total_orphaned = []
+    total_missing = []
+
+    for ws in workspaces:
+        root = ws.get_path()
+        ws_check: dict = {"path": str(root), "layout": ws.layout, "exists": root.exists()}
+
+        if root.exists():
+            on_disk = discover_repos(root, layout=ws.layout)
+            tracked = store.list_by_workspace(ws.label)
+            tracked_map = {r.key: r for r in tracked}
+            reconciled = reconcile(on_disk, tracked_map)
+
+            ws_check["on_disk"] = len(on_disk)
+            ws_check["tracked"] = len(tracked)
+            ws_check["matched"] = len(reconciled["matched"])
+            ws_check["orphaned"] = [r["key"] for r in reconciled["orphaned"]]
+            ws_check["missing"] = reconciled["missing"]
+
+            total_on_disk += len(on_disk)
+            total_orphaned.extend([(ws.label, r["key"]) for r in reconciled["orphaned"]])
+            total_missing.extend([(ws.label, k) for k in reconciled["missing"]])
+        else:
+            ws_check["error"] = "Directory does not exist"
+
+        checks["workspaces"][ws.label] = ws_check
+
+    if output_json:
+        json.dump(checks, sys.stdout, indent=2)
+        print()
+        return
+
+    # Human output
+    console.print("\n  [bold]gitstow doctor[/bold]\n")
+
+    # System
+    console.print("  [bold]1. System[/bold]\n")
+    git_status = f"[green]{git_version}[/green]" if git_ok else "[red]not installed[/red]"
+    console.print(f"     git:        {git_status}")
+    console.print(f"     gitstow:    v{__version__}")
+
+    # Config
+    console.print("\n  [bold]2. Configuration[/bold]\n")
+    _check("App directory", APP_HOME.exists())
+    _check("Config file", CONFIG_FILE.exists())
+    _check("Repos file", repos_file.exists(), str(repos_file))
+    console.print(f"     Workspaces:    {len(workspaces)}")
+    console.print(f"     Repos tracked: {store.count()}")
+
+    if not CONFIG_FILE.exists():
+        console.print("\n     [yellow]Run [bold]gitstow onboard[/bold] to set up.[/yellow]")
+
+    # Per-workspace health
+    console.print("\n  [bold]3. Workspace Health[/bold]\n")
+    for ws in workspaces:
+        ws_info = checks["workspaces"].get(ws.label, {})
+        exists = ws_info.get("exists", False)
+        status_str = "[green]OK[/green]" if exists else "[red]Missing[/red]"
+        console.print(f"     [cyan]{ws.label}[/cyan] ({ws.layout}) — {status_str}")
+        console.print(f"       Path: {ws.path}")
+
+        if exists and "error" not in ws_info:
+            console.print(f"       On disk: {ws_info.get('on_disk', 0)}  Tracked: {ws_info.get('tracked', 0)}")
+
+    if total_orphaned:
+        console.print(f"\n     [yellow]⚠ {len(total_orphaned)} untracked repos on disk:[/yellow]")
+        for ws_name, key in total_orphaned:
+            console.print(f"       [{ws_name}] {key}")
+
+    if total_missing:
+        console.print(f"\n     [yellow]⚠ {len(total_missing)} tracked but missing from disk:[/yellow]")
+        for ws_name, key in total_missing:
+            console.print(f"       [{ws_name}] {key}")
+
+    if not total_orphaned and not total_missing:
+        console.print(f"\n     [green]✓ All repos in sync across {len(workspaces)} workspace(s)[/green]")
+
+    # 4. SSH connectivity hint
+    ssh_repos = [r for r in store.list_all() if r.remote_url and r.remote_url.startswith("git@")]
+    if ssh_repos:
+        console.print("\n  [bold]4. SSH Connectivity[/bold]\n")
+        ssh_ok = _check_ssh_connectivity()
+        if ssh_ok:
+            console.print("     [green]✓[/green] SSH connection to github.com works")
+        else:
+            console.print("     [yellow]⚠ SSH connection to github.com failed[/yellow]")
+            console.print("       [dim]You have SSH repos but ssh-agent may not be running.[/dim]")
+            console.print("       [dim]Check: ssh -T git@github.com[/dim]")
+
+    console.print()
+
+
+def _check_ssh_connectivity() -> bool:
+    """Quick check if SSH to github.com works (exit code 1 = auth ok, 255 = failure)."""
+    import subprocess
+    try:
+        result = subprocess.run(
+            ["ssh", "-T", "-o", "ConnectTimeout=5", "git@github.com"],
+            capture_output=True, text=True, timeout=10,
+        )
+        # GitHub returns exit code 1 with "successfully authenticated" on success
+        return result.returncode == 1 and "successfully authenticated" in result.stderr
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def _check(label: str, ok: bool, detail: str = "") -> None:
+    """Print a check result."""
+    status = "[green]OK[/green]" if ok else "[red]Missing[/red]"
+    detail_str = f" [dim]({detail})[/dim]" if detail else ""
+    console.print(f"     {label}: {status}{detail_str}")