alissa-tools-github-devloop 0.1.0__py3-none-any.whl

alissa/tools/github/devloop/ghclient.py

@@ -0,0 +1,406 @@
+"""GitHub access via `gh api`.
+
+Note: this targets gh 2.4.0, which predates `gh search`. Every query goes
+through `gh api` against the REST v3 endpoints instead.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+from dataclasses import dataclass
+
+from . import proc
+
+log = logging.getLogger(__name__)
+
+# Origin-task convention: the session that files a devloop issue leaves an
+# `Alissa-Task: TASK-<n>` trailer line in the body. An anchored trailer match
+# wins outright; the loose first-TASK-<n> scan is only the fallback for bodies
+# that never wrote the trailer.
+# `[ \t]*` rather than `\s*`: the trailer's ref must sit on the SAME line --
+# `\s` matches newlines, which would let a dangling `Alissa-Task:` reach
+# across blank lines into unrelated prose and claim someone else's TASK ref.
+TASK_TRAILER_RE = re.compile(r"^Alissa-Task:[ \t]*TASK-(\d+)", re.MULTILINE)
+TASK_REF_RE = re.compile(r"TASK-(\d+)")
+
+# linked_open_prs walks the issue timeline page by page (a long pre-label
+# discussion can push the PR cross-reference past any single page), stopping
+# at the first short page, with a hard ceiling so a pathological timeline
+# cannot turn one liveness probe into an unbounded request storm. 5 pages =
+# 500 events; past that the probe gives up and reports what it saw -- a
+# known limit, same spirit as search_issues' 100-result window.
+TIMELINE_PAGE_SIZE = 100
+TIMELINE_MAX_PAGES = 5
+
+
+def parse_task_ref(body: str) -> int | None:
+    """Origin Alissa task number from an issue body, or None if absent.
+
+    Precedence: a line-anchored `Alissa-Task: TASK-<n>` trailer wins wherever
+    it sits in the body, so prose mentions of other tasks earlier in the text
+    cannot outrank it. Only when no trailer line exists does the loose scan
+    run, and there the first TASK-<n> wins.
+    """
+    text = body or ""
+    match = TASK_TRAILER_RE.search(text) or TASK_REF_RE.search(text)
+    return int(match.group(1)) if match else None
+
+
+@dataclass(frozen=True)
+class Issue:
+    owner: str
+    repo: str
+    number: int
+    state: str
+    title: str
+    body: str
+    url: str
+    assignees: tuple[str, ...]
+    labels: tuple[str, ...]
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+    @property
+    def issue_slug(self) -> str:
+        # Named issue_slug, not slug: the ledger's `repo_slug` key wants
+        # `full_name` (owner/repo), and a property called plain `slug` made
+        # `record_spawn(repo_slug=issue.slug, ...)` read natural but wrong.
+        return f"{self.owner}/{self.repo}#{self.number}"
+
+
+class RateLimited(RuntimeError):
+    pass
+
+
+class IdentityMismatch(RuntimeError):
+    """Configured developer identity disagrees with the gh token."""
+
+
+class AssignmentRejected(RuntimeError):
+    """`assign_self` returned 2xx but the login is not on the issue.
+
+    GitHub silently drops assignees that lack push access on the repo and
+    still answers with the (unchanged) issue. Left unchecked, the server-side
+    in-flight marker never lands: nothing on GitHub tells humans or other
+    daemons the issue is being worked, and a lost ledger would respawn a
+    developer against it immediately. This is a permanent, operator-fixable
+    condition (grant the account push access or drop the repo from the
+    allowlist), not a retry-later one."""
+
+
+# Actual rate-limit signals in `gh` stderr. A bare HTTP 403 is NOT one:
+# GitHub answers permission failures (token scope, SAML, fine-grained PAT
+# restrictions) with 403 too, and those are permanent operator errors that
+# must surface as CommandError, not as a transient retry-later signal.
+_RATE_LIMIT_MARKERS = (
+    "rate limit",  # covers "API rate limit exceeded" and "secondary rate limit"
+    "x-ratelimit-remaining: 0",
+    "retry-after",
+)
+
+
+def _is_rate_limited(exc: proc.CommandError) -> bool:
+    blob = exc.stderr.lower()
+    return any(marker in blob for marker in _RATE_LIMIT_MARKERS)
+
+
+class GitHub:
+    def __init__(self, login: str | None = None):
+        self._login = login
+
+    def token_login(self) -> str:
+        """Who the gh token actually belongs to. `gh api --jq` prints scalars
+        raw (unquoted), so this is deliberately not parsed as JSON -- which is
+        why it cannot go through `_api`, but it shares the same rate-limit
+        classification."""
+        try:
+            return proc.run(["gh", "api", "user", "--jq", ".login"]).strip()
+        except proc.CommandError as exc:
+            if _is_rate_limited(exc):
+                raise RateLimited(exc.stderr.strip()[:300]) from exc
+            raise
+
+    @property
+    def login(self) -> str:
+        if self._login is None:
+            self._login = self.token_login()
+        return self._login
+
+    def verify_identity(self) -> str:
+        """`assign_self` posts `self.login` as assignee, but that request is
+        authorized by the gh token. If a configured developer_login disagrees
+        with the token, the daemon would assign the token's account while
+        evaluate() looks for the configured one -- its own in-flight work
+        would read as foreign-assigned and wedge shut, and the in-flight
+        marker would break. Fail loudly instead."""
+        actual = self.token_login()
+        if self._login is not None and self._login != actual:
+            raise IdentityMismatch(
+                f"configured developer_login={self._login!r} but the gh token "
+                f"belongs to {actual!r}. Assignment follows the token, so the "
+                f"in-flight marker would break. Fix developer_login (or set it "
+                f"to null to auto-detect), or re-authenticate gh."
+            )
+        self._login = actual
+        return actual
+
+    def _api(self, *args: str, timeout: int = 60):
+        try:
+            return proc.run_json(["gh", "api", *args], timeout=timeout)
+        except proc.CommandError as exc:
+            if _is_rate_limited(exc):
+                raise RateLimited(exc.stderr.strip()[:300]) from exc
+            raise
+
+    SEARCH_PER_PAGE = 100
+
+    def search_issues(
+        self, label: str, repos: tuple[str, ...] = ()
+    ) -> list[tuple[str, str, int, tuple[str, ...] | None]]:
+        """Open issues carrying the trigger label across the watched repos,
+        as `(owner, repo, number, assignee_logins)` hits.
+
+        Deliberately NO `no:assignee` qualifier: the search returns assigned
+        issues so the daemon re-sees its own in-flight work on every poll --
+        that is what lets evaluate() age a stale spawn, re-enqueue it, and
+        escalate a cap-out. Assignment-based filtering happens in evaluate()
+        via the issue() re-fetch instead (foreign assignee → skip; fresh
+        self-spawn → in-flight). The label is quoted because it contains a
+        colon (`alissa:develop`).
+
+        `assignee_logins` is the search payload's OWN assignee data, surfaced
+        so the caller can cheaply pre-skip issues that are visibly someone
+        else's without paying the issue() re-fetch for them (issues parked on
+        a human otherwise cost one re-fetch per poll, forever). It is None --
+        unknown, not unassigned -- when the item carried no parseable
+        assignee list. Caveat: search results can lag the live issue, so this
+        is only ever a pre-filter for the FOREIGN case; the authoritative
+        re-fetch guard stays in evaluate() for everything the daemon might
+        act on, and a stale mis-skip self-heals on a later poll once the
+        index catches up.
+
+        Fails closed on an empty allowlist: without `repo:` qualifiers the
+        query would run against ALL of GitHub, and the caller self-assigns
+        and spawns developers against whatever comes back. An empty `repos`
+        therefore means "watch nothing", never "watch everything".
+        """
+        # Empty/whitespace ENTRIES fail closed too, not just an empty
+        # container: ("",) is truthy, and a bare `repo:` qualifier from a
+        # degenerate entry would put the unscoped-search blocker back on
+        # upstream leniency this client cannot verify.
+        repos = tuple(r.strip() for r in repos if r and r.strip())
+        if not repos:
+            log.warning(
+                "search_issues: repo allowlist is empty -- nothing is watched. "
+                "An unscoped search would match all of GitHub, so this fails "
+                "closed; configure `repos` to watch something."
+            )
+            return []
+
+        query = f'is:issue is:open label:"{label}"'
+        for full_name in repos:
+            query += f" repo:{full_name}"
+
+        payload = self._api(
+            "-X",
+            "GET",
+            "search/issues",
+            "-f",
+            f"q={query}",
+            "-f",
+            f"per_page={self.SEARCH_PER_PAGE}",
+        )
+        items = (payload or {}).get("items", [])
+        if len(items) == self.SEARCH_PER_PAGE:
+            log.warning(
+                "search_issues: got exactly %d items -- results are likely "
+                "truncated. Pagination is deliberately not implemented, so %d "
+                "results per poll is a hard ceiling, and the window only "
+                "drains as issues CLOSE or lose the trigger label (assignment "
+                "no longer removes them from this query) -- a backlog past "
+                "the ceiling keeps its tail invisible until it shrinks. This "
+                "warning is the visibility mechanism.",
+                self.SEARCH_PER_PAGE,
+                self.SEARCH_PER_PAGE,
+            )
+
+        out: list[tuple[str, str, int, tuple[str, ...] | None]] = []
+        for item in items:
+            # repository_url looks like https://api.github.com/repos/<owner>/<repo>
+            parts = item.get("repository_url", "").rstrip("/").split("/")
+            if len(parts) < 2:
+                log.warning("could not parse repo from %s", item.get("repository_url"))
+                continue
+            try:
+                number = int(item["number"])
+            except (KeyError, TypeError, ValueError):
+                log.warning("could not parse issue number from %r", item.get("number"))
+                continue
+            # None means UNKNOWN (no parseable assignee data on the item),
+            # never unassigned -- absence of evidence must fall through to
+            # the issue() re-fetch, not read as "free to take".
+            raw = item.get("assignees")
+            assignees: tuple[str, ...] | None
+            if isinstance(raw, list):
+                assignees = tuple(
+                    a["login"]
+                    for a in raw
+                    if isinstance(a, dict) and a.get("login")
+                )
+            else:
+                assignees = None
+            out.append((parts[-2], parts[-1], number, assignees))
+        return out
+
+    def issue(self, owner: str, repo: str, number: int) -> Issue:
+        # `or {}`: run_json returns None on empty stdout, and the siblings
+        # (search_issues, assign_self) already guard the same way.
+        data = self._api(f"repos/{owner}/{repo}/issues/{number}") or {}
+        return Issue(
+            owner=owner,
+            repo=repo,
+            number=number,
+            state=data.get("state", ""),
+            title=data.get("title", ""),
+            body=data.get("body") or "",
+            url=data.get("html_url", ""),
+            assignees=tuple(
+                (a.get("login") or "") for a in (data.get("assignees") or [])
+            ),
+            labels=tuple(
+                (lb.get("name") or "") if isinstance(lb, dict) else str(lb)
+                for lb in (data.get("labels") or [])
+            ),
+        )
+
+    def linked_open_prs(self, owner: str, repo: str, number: int) -> list[str]:
+        """URLs of OPEN same-repo pull requests linked to the issue -- the
+        external liveness signal behind the stale-retry decision.
+
+        Source: the issue's timeline, filtered to `cross-referenced` events
+        whose source is an open pull request IN THIS REPO. A cross-referenced
+        event is produced by ANY mention of the issue anywhere on GitHub -- a
+        comment on an unrelated PR, a "related to #<n>" in another repo's PR
+        body, a bot linking issues -- not only by the PR implementing it, so
+        the source's html_url must live under
+        `https://github.com/{owner}/{repo}/pull/`; without that filter, any
+        open PR anywhere that once mentioned the issue would defer the retry
+        for as long as it stays open. (A PR whose body carries `Closes #<n>`
+        cross-references the issue the moment it is opened, so the developer
+        sessions this daemon spawns always produce the event -- and their PRs
+        are same-repo by construction.) The timeline is the cheapest liveness
+        signal available: a handful of authenticated GETs (usually one) with
+        no extra token scope,
+        and -- unlike probing the developer's tmux session -- it does not
+        couple the daemon to whatever host the session runs on.
+        Closed/merged PRs are deliberately excluded: abandoned work must
+        not keep deferring the retry.
+
+        The timeline is walked in pages: ascending chronological order puts
+        everything that happened on the issue BEFORE the PR was opened --
+        comments, labeled/assigned/mentioned events, bot noise -- ahead of
+        the cross-reference, so a long pre-label discussion can push it past
+        the first page, and a first-page-only probe would mis-read live work
+        as dead (and respawn over it). The walk is bounded: it stops at the
+        first short page (the timeline is exhausted) and hard-caps at
+        TIMELINE_MAX_PAGES pages (TIMELINE_MAX_PAGES * TIMELINE_PAGE_SIZE
+        events) -- a cross-reference past that ceiling is invisible to the
+        probe: a documented limit, same spirit as search_issues' 100-result
+        window. NOT gh's `--paginate`: gh 2.4.0 concatenates the pages'
+        JSON arrays (`[...][...]`), which run_json cannot parse -- an
+        explicit `page=` loop is the safe shape for this client. Malformed
+        events are skipped, never fatal -- one odd timeline entry must not
+        wedge the staleness decision.
+        """
+        same_repo_pull = f"https://github.com/{owner}/{repo}/pull/"
+        urls: list[str] = []
+        for page in range(1, TIMELINE_MAX_PAGES + 1):
+            events = (
+                self._api(
+                    "-X",
+                    "GET",
+                    f"repos/{owner}/{repo}/issues/{number}/timeline",
+                    "-f",
+                    f"per_page={TIMELINE_PAGE_SIZE}",
+                    "-f",
+                    f"page={page}",
+                )
+                or []
+            )
+            if not isinstance(events, list):
+                break
+            for event in events:
+                if (
+                    not isinstance(event, dict)
+                    or event.get("event") != "cross-referenced"
+                ):
+                    continue
+                source = event.get("source")
+                src = source.get("issue") if isinstance(source, dict) else None
+                if not isinstance(src, dict):
+                    continue
+                if not src.get("pull_request"):
+                    continue  # the cross-reference came from a plain issue
+                if src.get("state") != "open":
+                    continue
+                url = src.get("html_url") or ""
+                if not url.startswith(same_repo_pull):
+                    continue  # a mention from another repo says nothing here
+                urls.append(url)
+            if len(events) < TIMELINE_PAGE_SIZE:
+                break  # short page: the timeline is exhausted
+        # One PR can cross-reference the issue more than once (body edit,
+        # comment mention); report it once.
+        return list(dict.fromkeys(urls))
+
+    def assign_self(self, owner: str, repo: str, number: int) -> None:
+        """Assign the token identity -- the server-side in-flight marker.
+
+        gh 2.4.0 has no `-f key[]=value` array syntax (that landed later) and
+        the endpoint wants `{"assignees": [...]}`, so the body goes through
+        `--input <file>` instead.
+
+        The endpoint does NOT fail loudly when the assignment is rejected:
+        GitHub drops assignees lacking push access and still returns 2xx with
+        the issue unchanged. The response body is therefore checked and
+        `AssignmentRejected` raised when the login did not land.
+        """
+        payload = json.dumps({"assignees": [self.login]})
+        fd, body_path = tempfile.mkstemp(prefix="devloop-assign-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w") as handle:
+                handle.write(payload)
+            data = self._api(
+                "-X",
+                "POST",
+                f"repos/{owner}/{repo}/issues/{number}/assignees",
+                "--input",
+                body_path,
+            )
+        finally:
+            os.unlink(body_path)
+
+        landed = tuple(
+            (a.get("login") or "") for a in ((data or {}).get("assignees") or [])
+        )
+        if self.login not in landed:
+            raise AssignmentRejected(
+                f"{owner}/{repo}#{number}: GitHub accepted the request but "
+                f"{self.login!r} is not among the issue assignees {landed!r} -- "
+                f"the account likely lacks push access on {owner}/{repo}, so "
+                f"the in-flight marker cannot land. Grant access or remove the "
+                f"repo from the allowlist."
+            )
+
+    def comment(self, owner: str, repo: str, number: int, body: str) -> None:
+        self._api(
+            f"repos/{owner}/{repo}/issues/{number}/comments",
+            "-f",
+            f"body={body}",
+        )