"""What is running here, what is available, and how to get from one to the other.

## Why this exists

Updating meant a shell on the box. That is fine for whoever built it and wrong
for everybody else: an instance somebody installed from `deploy/install.sh` and
handed over has an administrator who can configure every part of it and cannot
tell whether it is three releases behind.

So this answers three questions — what is running, what is on the branch, and
what changed between — and offers a button for the fourth.

## The button cannot do the work, and that is the design

The service runs as an unprivileged account. It cannot restart itself, it cannot
write outside its own prefix, and it should not be able to: a web application
that can restart its own service is one whose worst day is much worse.

So the button **writes a file**, and an opt-in systemd `.path` unit watching that
file runs `deploy/update.sh` as root. Three things follow, and all three are
deliberate:

- **The request file carries nothing.** No branch, no ref, no arguments. The
  helper runs the update script with the branch *it* was configured with, so an
  administrator of the web UI cannot choose what gets deployed — only *that* the
  configured branch gets deployed.
- **It is opt-in.** Without the helper the page says so and shows the command,
  which is the honest degradation and the same shape the SSH and search extras
  already have. Installing it is a decision with a consequence worth stating:
  anybody who can administer the web UI can then deploy whatever is on that
  branch.
- **Nothing here runs a shell.** Every subprocess is a fixed argv with
  `shell=False`, and the only variable in any of them is the branch, which comes
  from the environment rather than from a request.

## On "nothing executes on this machine"

That rule is about *agent chats* — a model's commands, on a host somebody chose.
This is an administrator pressing a button to run `git`, with no model anywhere
near it and no input from a request in the argv. Worth stating rather than
leaving somebody to notice the tension.
"""

from __future__ import annotations

import logging
import subprocess
from dataclasses import dataclass, field
from pathlib import Path

from lembas import __version__
from lembas.config import settings

log = logging.getLogger(__name__)

# Long enough for a fetch over a slow link, short enough that a page does not
# appear to hang. A fetch that takes longer than this is a network problem, and
# saying so is more use than waiting.
GIT_TIMEOUT = 30.0

# The file the button writes. Inside the data directory, which is the one place
# the service account can write, and named so that finding it in a backup says
# what it was.
REQUEST_NAME = "update-requested"

# Written by `install.sh` when the helper is installed. A marker rather than
# asking systemd, because `systemctl is-enabled` means a subprocess on every
# page render to answer a question that changes once.
MARKER_NAME = ".update-helper"


@dataclass(frozen=True)
class Commit:
    sha: str
    subject: str
    when: str = ""

    @property
    def short(self) -> str:
        return self.sha[:7]


@dataclass(frozen=True)
class State:
    """Everything the page shows, resolved in one go."""

    version: str = __version__
    checkout: str = ""
    branch: str = "main"
    head: Commit | None = None
    remote: Commit | None = None
    behind: list[Commit] = field(default_factory=list)
    dirty: bool = False
    helper: bool = False
    requested: bool = False
    error: str = ""

    @property
    def is_git(self) -> bool:
        return bool(self.checkout)

    @property
    def up_to_date(self) -> bool:
        return bool(self.head and self.remote and self.head.sha == self.remote.sha)


def checkout_dir() -> Path | None:
    """The git checkout this is running from, or None.

    `src/lembas/__init__.py` upwards twice is the repository root for an editable
    install, which is what every deployment here is. A wheel installed into
    site-packages has no `.git` above it and answers None, which the page reads
    as "this was not installed from a checkout" rather than as an error.
    """
    root = Path(__file__).resolve().parents[3]
    return root if (root / ".git").exists() else None


def _git(args: list[str], *, cwd: Path, timeout: float = GIT_TIMEOUT) -> tuple[int, str]:
    """One git command, with no shell anywhere near it.

    `shell=False` and a fixed argv, so nothing here can be made to run something
    else by what it is given. Returns the code and the output together because
    every caller wants both and none of them wants an exception: git failing is
    a thing to report on the page, not a 500.
    """
    try:
        done = subprocess.run(  # noqa: S603 - fixed argv, no shell, admin-only
            ["git", *args],
            cwd=str(cwd),
            capture_output=True,
            text=True,
            timeout=timeout,
            check=False,
        )
    except FileNotFoundError:
        return 127, "git is not installed on this machine."
    except subprocess.TimeoutExpired:
        return 124, f"git took longer than {int(timeout)}s."
    except Exception as exc:  # noqa: BLE001 - a broken git is a message, not a crash
        log.debug("git %s failed", args, exc_info=True)
        return 1, str(exc)
    return done.returncode, (done.stdout or done.stderr or "").strip()


def _commit(line: str) -> Commit | None:
    """One line of `--format=%H\\x1f%s\\x1f%cI`.

    Split on a unit separator rather than a space: a commit subject contains
    spaces, and every other separator anybody reaches for is one a subject may
    also contain.
    """
    parts = line.split("\x1f")
    if len(parts) < 2 or not parts[0]:
        return None
    return Commit(sha=parts[0], subject=parts[1], when=parts[2] if len(parts) > 2 else "")


FORMAT = "--format=%H\x1f%s\x1f%cI"


def branch_name() -> str:
    return settings.update_branch or "main"


def helper_installed() -> bool:
    return (settings.data_dir / MARKER_NAME).exists()


def request_path() -> Path:
    return settings.data_dir / REQUEST_NAME


def pending() -> bool:
    return request_path().exists()


def read(*, fetch: bool = False) -> State:
    """What is running and what is available.

    `fetch` is the network half and is off by default: this is called to render a
    page, and a page that made a network request on every load would be one
    somebody stops opening. The Check button passes it.
    """
    branch = branch_name()
    root = checkout_dir()
    base = State(branch=branch, helper=helper_installed(), requested=pending())
    if root is None:
        return base

    code, head_line = _git(["log", "-1", FORMAT], cwd=root)
    if code != 0:
        return State(**{**base.__dict__, "checkout": str(root), "error": head_line})

    code, status = _git(["status", "--porcelain"], cwd=root)
    dirty = bool(status.strip()) if code == 0 else False

    error = ""
    if fetch:
        code, output = _git(["fetch", "--quiet", "origin", branch], cwd=root)
        if code != 0:
            error = f"Could not reach the remote: {output}"

    remote_line = ""
    code, output = _git(["log", "-1", FORMAT, f"origin/{branch}"], cwd=root)
    if code == 0:
        remote_line = output

    behind: list[Commit] = []
    if remote_line:
        code, output = _git(["log", FORMAT, f"HEAD..origin/{branch}"], cwd=root)
        if code == 0 and output:
            behind = [c for line in output.splitlines() if (c := _commit(line))]

    return State(
        checkout=str(root),
        branch=branch,
        head=_commit(head_line),
        remote=_commit(remote_line) if remote_line else None,
        behind=behind,
        dirty=dirty,
        helper=helper_installed(),
        requested=pending(),
        error=error,
    )


def request_update(who: str = "") -> str:
    """Ask the helper to update. Returns a message fit to show.

    The file is written with the requester's email in it **for the log**, and
    that is all it carries. Nothing in it reaches the helper's command line: the
    helper runs the update script with its own configured branch, so being able
    to press this button is not being able to choose what is deployed.
    """
    path = request_path()
    try:
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(f"requested by {who or 'an administrator'}\n", encoding="utf-8")
    except OSError as exc:
        log.warning("could not write the update request: %s", exc)
        return f"Could not write {path}: {exc}"
    log.info("update requested by %s", who or "an administrator")
    return ""


def clear_request() -> None:
    """Forget a request. For the page's Cancel, and for tests."""
    request_path().unlink(missing_ok=True)


def manual_command() -> str:
    """What to run by hand when the helper is not installed."""
    root = checkout_dir()
    return f"sudo {root}/deploy/update.sh" if root else "sudo ./deploy/update.sh"


__all__ = [
    "GIT_TIMEOUT",
    "MARKER_NAME",
    "REQUEST_NAME",
    "Commit",
    "State",
    "branch_name",
    "checkout_dir",
    "clear_request",
    "helper_installed",
    "manual_command",
    "pending",
    "read",
    "request_path",
    "request_update",
]