sync.py

#!/usr/bin/env python3
"""
Sync homelab knowledge base repositories as submodules.

Usage:
    uv run sync.py [--dry-run]

This script manages git submodules for homelab infrastructure and media stack
repositories based on an allowlist.
- Adds new submodules for repos in the allowlist that aren't present
- Removes submodules for repos not in the allowlist
- Updates all submodules (pinned repos checkout their ref, unpinned get latest)
"""

import argparse
import os
import shutil
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path

from rich.console import Console
from rich.panel import Panel
from rich.progress import Progress, SpinnerColumn, TextColumn
from rich.table import Table
from rich.text import Text

# =============================================================================
# ALLOWLIST CONFIGURATION
# =============================================================================
# Add or remove repositories here to manage which repos are synced.
#
# Format:
#   "org/repo-name"                        -> Track latest default branch
#   ("org/repo-name", "v1.2.3")            -> Pin to a tag
#   ("org/repo-name", "abc123")            -> Pin to a commit SHA
#   ("org/repo-name", "v1.2.3", "alias")   -> Pin to a tag with custom local dir name
#   ("org/repo-name", None, "alias")        -> Track latest with custom local dir name
# =============================================================================

ALLOWED_REPOS: list[str | tuple[str, ...]] = [
    # =========================================================================
    # Infrastructure & Tools
    # =========================================================================
    ("ansible/ansible", "v2.20.2"),
    ("docker/compose", "v5.0.2"),

    # =========================================================================
    # Linting & Code Quality
    # =========================================================================
    ("suo/lintrunner", "v0.13.0"),
    ("justinchuby/lintrunner-adapters", "v0.13.0"),

    # =========================================================================
    # Web Frameworks
    # =========================================================================
    ("tornadoweb/tornado", "v6.5.5"),

    # =========================================================================
    # Databases
    # =========================================================================
    ("postgres/postgres", "REL_16_15"),
    ("MagicStack/asyncpg", "v0.31.0"),

    # =========================================================================
    # Reverse Proxy
    # =========================================================================
    ("nginx/nginx", "release-1.29.5"),
    ("traefik/traefik", "v3.6.13"),

    # =========================================================================
    # Container Management
    # =========================================================================
    ("portainer/portainer", "2.33.7"),
    ("containrrr/watchtower", "v1.7.1"),

    # =========================================================================
    # Home Automation
    # =========================================================================
    ("home-assistant/core", "2026.2.2", "homeassistant"),
    ("eclipse-mosquitto/mosquitto", "v2.1.2"),
    ("iprak/winix", "v1.3.1"),

    # =========================================================================
    # Monitoring Stack
    # =========================================================================
    ("prometheus/prometheus", "v3.9.1"),
    ("prometheus/node_exporter", "v1.10.2"),
    ("prometheus/client_python", "v0.25.0"),
    ("google/cadvisor", "v0.56.2"),
    ("grafana/grafana", "v12.3.3"),
    ("grafana/loki", "v3.6.6"),               # Includes Promtail
    ("binwiederhier/ntfy", "v2.17.0"),
    ("onedr0p/exportarr", "v2.3.0"),

    # =========================================================================
    # Firewall
    # =========================================================================
    ("opnsense/core", None, "opnsense-core"),
    ("opnsense/plugins", None, "opnsense-plugins"),

    # =========================================================================
    # Networking / VPN
    # =========================================================================
    ("juanfont/headscale", "v0.28.0"),
    "theonemule/no-ip",
    ("tailscale/tailscale", "v1.94.2"),

    # =========================================================================
    # Media Stack - VPN & Downloads
    # =========================================================================
    ("qdm12/gluetun", "v3.41.1"),
    ("qbittorrent/qBittorrent", "release-5.1.4"),
    ("sabnzbd/sabnzbd", "4.5.5"),

    # =========================================================================
    # Media Stack - Automation (*arr)
    # =========================================================================
    ("Prowlarr/Prowlarr", "v2.3.0.5236"),
    ("Sonarr/Sonarr", "v4.0.16.2944"),
    ("Radarr/Radarr", "v6.0.4.10291"),
    ("Lidarr/Lidarr", "v3.1.0.4875"),
    ("morpheus65535/bazarr", "v1.5.5"),

    # =========================================================================
    # Media Stack - Quality Profiles & Guides
    # =========================================================================
    ("recyclarr/recyclarr", "v8.4.0"),
    "TRaSH-Guides/Guides",

    # =========================================================================
    # Media Stack - Authenticity / Quality Analysis
    # =========================================================================
    ("Guillain-RDCDE/FLAC_Detective", "v1.7.0"),

    # =========================================================================
    # Media Stack - Requests & Discovery
    # =========================================================================
    ("seerr-team/seerr", "v3.1.0"),

    # =========================================================================
    # Media Stack - Transcoding & Playback
    # =========================================================================
    "HaveAGitGat/Tdarr",
    "plexinc/pms-docker",

    # =========================================================================
    # Media Stack - Jellyfin
    # =========================================================================
    ("jellyfin/jellyfin-web", "v10.11.6"),
    ("jellyfin/jellyfin-ffmpeg", "v7.1.3-3"),
    "jellyfin/jellyfin-meta",
    ("jellyfin/jellyfin-chromecast", "v1.2.0"),
    ("jellyfin/jellyfin-androidtv", "v0.19.7"),
    ("jellyfin/jellyfin-ios", "v1.7.0.8"),
    ("jellyfin/Swiftfin", "1.4"),
    ("jellyfin/jellyfin-sdk-typescript", "v0.13.0"),
    ("jellyfin/jellyfin-android", "v2.6.3"),
    "CyferShepard/Jellystat",

    # =========================================================================
    # Graph Visualization
    # =========================================================================
    ("pydot/pydot", "v4.0.1"),
    ("graphp/graphviz", "v0.2.2"),
]


# =============================================================================
# Configuration
# =============================================================================


@dataclass
class RepoConfig:
    """Configuration for a repository."""

    name: str  # Local name (used for submodule path under repos/)
    ref: str | None = None  # None means track latest
    org: str = ""  # GitHub organization
    repo_name: str | None = None  # GitHub repo name (if different from local name)

    @property
    def is_pinned(self) -> bool:
        return self.ref is not None

    @property
    def github_url(self) -> str:
        return f"https://github.com/{self.org}/{self.repo_name or self.name}.git"


def parse_repo_config(entry: str | tuple[str, ...]) -> RepoConfig:
    """Parse an allowlist entry into a RepoConfig."""
    if isinstance(entry, str):
        org, name = entry.split("/", 1)
        return RepoConfig(name=name, org=org)
    repo_part = entry[0]
    ref = entry[1] if len(entry) > 1 else None
    local_name = entry[2] if len(entry) > 2 else None
    org, name = repo_part.split("/", 1)
    return RepoConfig(name=local_name or name, ref=ref, org=org, repo_name=name)


def get_repo_configs() -> list[RepoConfig]:
    """Get parsed repo configurations from the allowlist."""
    return [parse_repo_config(entry) for entry in ALLOWED_REPOS]


SUBMODULE_DIR = Path("repos")

console = Console()


def run_git(
    *args: str, check: bool = True, capture: bool = False
) -> subprocess.CompletedProcess:
    """Run a git command."""
    cmd = ["git", *args]
    return subprocess.run(
        cmd,
        check=check,
        capture_output=capture,
        text=True,
    )


def get_existing_submodules() -> dict[str, Path]:
    """Get a mapping of submodule names to their paths."""
    result = run_git("submodule", "status", capture=True, check=False)
    submodules = {}

    if result.returncode != 0:
        return submodules

    for line in result.stdout.strip().split("\n"):
        if not line.strip():
            continue
        # Format: " <sha> <path> (<describe>)" or "-<sha> <path>" for uninitialized
        parts = line.strip().split()
        if len(parts) >= 2:
            # Remove leading +/- status indicators from sha
            path = Path(parts[1])
            # Extract repo name from path (repos/agent -> agent)
            if path.parent == SUBMODULE_DIR:
                submodules[path.name] = path

    return submodules


def add_submodule(config: RepoConfig, dry_run: bool = False) -> tuple[str, bool, str]:
    """Add a submodule. Returns (repo_name, success, message)."""
    url = config.github_url
    path = SUBMODULE_DIR / config.name

    if path.exists() and any(path.iterdir()):
        return (config.name, False, "already exists")

    if dry_run:
        return (config.name, True, "would add")

    try:
        # Remove empty directory if it exists (leftover from failed attempt)
        if path.exists():
            shutil.rmtree(path)

        subprocess.run(
            ["git", "submodule", "add", url, str(path)],
            check=True,
            capture_output=True,
            text=True,
        )
        return (config.name, True, "added")
    except subprocess.CalledProcessError as e:
        return (config.name, False, e.stderr.strip() or str(e))


def add_submodules(
    configs: list[RepoConfig], dry_run: bool = False
) -> list[tuple[str, bool, str]]:
    """Add submodules sequentially with progress display."""
    results: list[tuple[str, bool, str]] = []

    if not configs:
        return results

    sorted_configs = sorted(configs, key=lambda c: c.name)

    with Progress(
        SpinnerColumn(),
        TextColumn("[progress.description]{task.description}"),
        console=console,
    ) as progress:
        for config in sorted_configs:
            progress.update(
                progress.add_task(f"[cyan]Adding {config.org}/{config.name}...", total=None),
            )
            result = add_submodule(config, dry_run)
            results.append(result)

    return results


def remove_submodule(
    repo_name: str, path: Path, dry_run: bool = False
) -> tuple[str, bool, str]:
    """Remove a submodule that's no longer in the allowlist."""
    if dry_run:
        return (repo_name, True, "would remove")

    try:
        # Deinitialize the submodule
        run_git("submodule", "deinit", "-f", str(path), check=False, capture=True)

        # Remove from git index
        run_git("rm", "-f", str(path), check=False, capture=True)

        # Clean up .git/modules directory
        git_modules_path = Path(".git/modules") / path
        if git_modules_path.exists():
            shutil.rmtree(git_modules_path)

        # Remove the directory if it still exists
        if path.exists():
            shutil.rmtree(path)

        return (repo_name, True, "removed")
    except Exception as e:
        return (repo_name, False, str(e))


def update_submodule(
    config: RepoConfig, dry_run: bool = False
) -> tuple[str, bool, str]:
    """Update a single submodule. Returns (repo_name, success, message)."""
    path = SUBMODULE_DIR / config.name

    if not path.exists():
        return (config.name, False, "not found")

    if dry_run:
        if config.is_pinned:
            return (config.name, True, f"would checkout {config.ref}")
        return (config.name, True, "would pull latest")

    try:
        if config.is_pinned and config.ref is not None:
            # Checkout the specific ref
            subprocess.run(
                ["git", "-C", str(path), "fetch", "--all", "--tags"],
                check=True,
                capture_output=True,
                text=True,
            )
            subprocess.run(
                ["git", "-C", str(path), "checkout", config.ref],
                check=True,
                capture_output=True,
                text=True,
            )
            return (config.name, True, f"@ {config.ref}")
        else:
            # Pull latest from default branch
            subprocess.run(
                ["git", "-C", str(path), "pull", "origin", "HEAD"],
                check=True,
                capture_output=True,
                text=True,
            )
            return (config.name, True, "latest")
    except subprocess.CalledProcessError as e:
        return (config.name, False, e.stderr.strip() or str(e))


def update_submodules(
    configs: list[RepoConfig], dry_run: bool = False
) -> list[tuple[str, bool, str]]:
    """Update all submodules based on their config."""
    results: list[tuple[str, bool, str]] = []

    if not configs:
        return results

    # First, ensure all submodules are initialized (suppress output)
    if not dry_run:
        jobs = os.cpu_count() or 4
        try:
            run_git(
                "submodule",
                "update",
                "--init",
                "--recursive",
                "--jobs",
                str(jobs),
                capture=True,
            )
        except subprocess.CalledProcessError:
            pass  # Continue anyway, individual updates will report errors

    # Then update each based on its config
    for config in configs:
        result = update_submodule(config, dry_run)
        results.append(result)

    return results


def ensure_repos_dir() -> None:
    """Ensure the repos directory exists."""
    SUBMODULE_DIR.mkdir(exist_ok=True)


def print_results_table(
    title: str, results: list[tuple[str, bool, str]], action: str = "Status"
) -> None:
    """Print a styled results table."""
    table = Table(title=title, show_header=True, header_style="bold magenta")
    table.add_column("Repository", style="cyan")
    table.add_column(action, justify="left")

    for repo_name, success, message in sorted(results, key=lambda x: x[0]):
        if success:
            status = Text(message, style="green")
        else:
            status = Text(message, style="red")
        table.add_row(repo_name, status)

    console.print(table)
    console.print()


def sync(dry_run: bool = False) -> int:
    """Main sync logic."""
    # Header
    title = Text()
    title.append("Homelab Knowledge Base", style="bold cyan")
    title.append(" - ", style="dim")
    title.append("Repository Sync", style="bold white")

    if dry_run:
        title.append(" [DRY RUN]", style="bold yellow")

    console.print(Panel(title, border_style="cyan"))
    console.print()

    # Ensure we're in a git repository
    result = run_git("rev-parse", "--git-dir", capture=True, check=False)
    if result.returncode != 0:
        console.print(
            "[red]Error:[/red] Not a git repository. Please run 'git init' first."
        )
        return 1

    ensure_repos_dir()

    # Parse repo configurations
    configs = get_repo_configs()
    config_by_name = {c.name: c for c in configs}

    # Get current state
    existing = get_existing_submodules()
    allowed_names = {c.name for c in configs}
    existing_set = set(existing.keys())

    # Determine what to add and remove
    to_add = allowed_names - existing_set
    to_remove = existing_set - allowed_names

    # Count pinned repos
    pinned_count = sum(1 for c in configs if c.is_pinned)

    # Status summary
    status_table = Table(show_header=False, box=None, padding=(0, 2))
    status_table.add_column("Label", style="dim")
    status_table.add_column("Value", style="bold")

    status_table.add_row("Allowlist", f"{len(configs)} repos ({pinned_count} pinned)")
    status_table.add_row("Existing", f"{len(existing)} submodules")
    status_table.add_row(
        "To add", Text(str(len(to_add)), style="green" if to_add else "dim")
    )
    status_table.add_row(
        "To remove", Text(str(len(to_remove)), style="red" if to_remove else "dim")
    )

    console.print(status_table)
    console.print()

    # Add new submodules
    if to_add:
        configs_to_add = [config_by_name[name] for name in to_add]
        results = add_submodules(configs_to_add, dry_run)
        print_results_table("Added Repositories", results, "Status")

    # Remove old submodules
    if to_remove:
        remove_results = []
        for repo_name in sorted(to_remove):
            result = remove_submodule(repo_name, existing[repo_name], dry_run)
            remove_results.append(result)

        print_results_table("Removed Repositories", remove_results, "Status")

    # Update all submodules (pinned to their ref, unpinned to latest)
    if configs:
        with console.status("[cyan]Updating submodules...", spinner="dots"):
            update_results = update_submodules(configs, dry_run)

        print_results_table("Updated Repositories", update_results, "Version")

    # Final summary
    console.print(Panel("[bold green]Done![/bold green]", border_style="green"))

    return 0


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Sync homelab knowledge base repositories as submodules.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
    uv run sync.py              # Add missing submodules and update all
    uv run sync.py --dry-run    # Preview changes without making them
        """,
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Preview changes without making them",
    )

    args = parser.parse_args()
    return sync(dry_run=args.dry_run)


if __name__ == "__main__":
    sys.exit(main())