"""Git source sync for import_docs (phase 28).

clone_or_pull(url, dest) clones ``url`` into ``dest`` (shallow, depth 1)
the first time, or fast-forwards an existing checkout with ``git pull
--ff-only`` on subsequent runs.

Auth: nothing special — an ``https://…`` URL uses the OS credential
helper / prompts; a ``git@host:repo.git`` URL uses the machine's SSH key.
No credentials are stored here; whatever the URL/SSH config supplies is
used.

This module is the only place the ``git`` CLI is invoked (A11: stdlib
``subprocess`` only, no new packages) — every git command goes through
:func:`run_git`: the clone/pull in :func:`clone_or_pull` and the
docs-push sequence in :mod:`app.core.docs_push` (phase 59).
"""
from __future__ import annotations

import subprocess
from pathlib import Path

__all__ = ["GitSyncError", "clone_or_pull", "run_git"]


class GitSyncError(RuntimeError):
    """A git clone/pull failed (or git is missing); carries git's stderr."""


def clone_or_pull(url: str, dest: Path | str) -> Path:
    """Clone ``url`` into ``dest`` (shallow, first run) or fast-forward it.

    - dest without a ``.git`` (or absent) → ``git clone --depth 1 url dest``
      (shallow: the KB is re-imported incrementally anyway).
    - dest with a ``.git`` → ``git pull --ff-only`` (refuses to merge
      unrelated histories — a broken checkout fails loudly rather than
      producing a dirty index).

    Returns the destination path. Raises :class:`GitSyncError` when git is
    missing or a git invocation exits non-zero (with git's stderr in the
    message, so the caller can name the failing repo + reason).
    """
    dest = Path(dest)
    if not dest.exists() or not (dest / ".git").exists():
        dest.parent.mkdir(parents=True, exist_ok=True)
        run_git(["git", "clone", "--depth", "1", url, str(dest)], cwd=dest.parent)
    else:
        run_git(["git", "pull", "--ff-only"], cwd=dest)
    return dest


def run_git(argv: list[str], cwd: Path) -> str:
    """Run one git command, capturing output; raise GitSyncError on failure.

    The single ``git`` invocation point for the whole app (A11). Every
    step of :func:`clone_or_pull` and of the docs-push sequence
    (:mod:`app.core.docs_push`, phase 59) goes through here, so error
    handling stays uniform: captured stdout on success, and
    :class:`GitSyncError` carrying git's stderr on a non-zero exit (or
    when the git binary is missing from PATH).
    """
    try:
        proc = subprocess.run(argv, cwd=cwd, capture_output=True, text=True)
    except FileNotFoundError:
        raise GitSyncError("git was not found on PATH — install git and retry") from None
    if proc.returncode != 0:
        raise GitSyncError(
            f"git {' '.join(argv[1:])} failed (exit {proc.returncode}): "
            f"{proc.stderr.strip()}"
        )
    return proc.stdout