compforge-repokit 0.15.0__py3-none-any.whl

repokit/forge/model.py

@@ -0,0 +1,380 @@
+"""Provider-neutral repository collaboration objects and operations."""
+
+from __future__ import annotations
+
+import abc
+import re
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Generic, TypeVar
+
+from harness_common import Repository
+
+
+def parse_pr_number(s: str) -> int | None:
+    """Extract a PR/MR number from a URL or a bare ref. Knows both forges' URL shapes
+    (GitHub `/pull/N`, GitLab `/merge_requests/N`) so callers (CLI scripts) don't carry
+    provider URL knowledge. Accepts a bare `N`, `#N`, or `!N` too."""
+    m = re.search(r"/(?:pull|merge_requests)/(\d+)", s) or re.fullmatch(r"[!#]?(\d+)", s.strip())
+    return int(m.group(1)) if m else None
+
+
+class ForgeError(Exception):
+    """Any forge transport/API failure."""
+
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class Page(Generic[T]):
+    """One page; next_cursor is an opaque continuation, not an inventory guarantee."""
+
+    items: tuple[T, ...]
+    next_cursor: str | None = None
+
+
+class ForgeOutcomeUnknown(ForgeError):
+    """A request may have taken effect; inspect remote state before retrying."""
+
+
+class ForgeAuthError(ForgeError):
+    """No usable token or insufficient permission (excluding rate limits)."""
+
+
+class ForgeRateLimited(ForgeError):
+    """Requests must wait until retry_at (UTC epoch seconds); never an auth failure."""
+
+    def __init__(self, resource: str, retry_at: float, *, secondary: bool = False):
+        self.resource = resource
+        self.retry_at = retry_at
+        self.secondary = secondary
+        super().__init__(f"forge rate limited: resource={resource}, retry_at={retry_at:.0f}")
+
+    def __str__(self) -> str:
+        return f"forge rate limited: resource={self.resource}, retry_at={self.retry_at:.0f}"
+
+
+class ForgeNotFound(ForgeError):
+    """404 from the API."""
+
+
+@dataclass(frozen=True)
+class PullRequestIdentity:
+    """Stable cross-repo identity for a PR/MR.
+
+    `source` is the origin host used as the `forges` config key; `repository`
+    is the provider-neutral path under that host.
+    """
+
+    source: str
+    repository: str
+    number: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "repository": self.repository,
+            "number": self.number,
+        }
+
+
+@dataclass
+class PullRequest:
+    """A code-review proposal returned by a forge — neutral across forges.
+
+    `number` is the per-repo sequential id (the number in the URL: GitLab `iid`,
+    GitHub PR number). `state` is normalized to 'open' | 'merged' | 'closed' by the
+    adapter (GitHub's open/closed + a `merged` flag collapses to these three). No
+    `provider` field — that's a repo-level fact (see module docstring); display labels
+    are built with `pr_label(provider, number)` at render time. 'inactive' (merged/closed)
+    is derived, never stored.
+    """
+
+    number: int
+    title: str = ""
+    state: str = ""  # neutral: "open" | "merged" | "closed"
+    source_branch: str = ""
+    target_branch: str = ""
+    web_url: str = ""
+    sha: str = ""  # source-branch tip the monitor ancestry-checks against HEAD
+    updated_at: str | None = None
+    source_repository: str = ""
+    target_repository: str = ""
+
+    @property
+    def inactive(self) -> bool:
+        return self.state in ("merged", "closed")
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the forge reports the proposal as open."""
+        return self.state == "open"
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> PullRequest:
+        return cls(
+            number=int(d["number"]),
+            title=d.get("title", ""),
+            state=d.get("state", ""),
+            source_branch=d.get("source_branch", ""),
+            target_branch=d.get("target_branch", ""),
+            web_url=d.get("web_url", ""),
+            sha=d.get("sha", ""),
+            updated_at=d.get("updated_at"),
+            source_repository=d.get("source_repository", ""),
+            target_repository=d.get("target_repository", ""),
+        )
+
+
+class CommentResolution(StrEnum):
+    """Resolution state of the provider interaction backing a top-level comment."""
+
+    UNSUPPORTED = "unsupported"
+    UNRESOLVED = "unresolved"
+    RESOLVED = "resolved"
+
+
+@dataclass
+class Comment:
+    """One top-level PR/MR comment, optionally backed by a replyable review interaction.
+
+    `replies` keeps provider threading inside the Forge adapter: callers consume one neutral
+    Comment whether GitHub supplied a review-comment thread or GitLab supplied a discussion.
+    `reply_ref` / `resolve_ref` are opaque adapter handles and must only be passed back to the
+    Forge that produced them.
+
+    Carries no label/finding vocabulary: `ccr:fp=` and `ccr:label=` remain review-layer body
+    conventions. The forge is the durable source of truth, so comment refs are never persisted
+    locally.
+    """
+
+    author: str = ""
+    body: str = ""
+    id: str = ""  # opaque, adapter-scoped; "" when the adapter can't supply one
+    path: str = ""  # diff anchor (new side); "" for plain conversation comments
+    line: int | None = None
+    created_at: str = ""
+    replies: list[Comment] = field(default_factory=list)
+    reply_ref: str = ""
+    resolve_ref: str = ""
+    resolution: CommentResolution = CommentResolution.UNSUPPORTED
+
+    @property
+    def replyable(self) -> bool:
+        return bool(self.reply_ref)
+
+
+@dataclass
+class Release:
+    """A published release returned by a forge — neutral across forges.
+
+    `tag` is the git tag the release points to; `target` is the commit-ish the tag was cut
+    at (a branch name or sha). Like `PullRequest` it carries no provider — the tag is created
+    server-side by the forge, so a release never requires a local `git push --tags`.
+    """
+
+    tag: str
+    name: str = ""
+    target: str = ""  # target_commitish (GitHub) / commit the tag resolved to (GitLab)
+    web_url: str = ""
+    created_at: str | None = None
+
+
+class MergeReadiness(StrEnum):
+    """Why a PR/MR can't be merged yet — the neutral form of GitLab's `detailed_merge_status`
+    / GitHub's `mergeable_state`. Forges surface one blocking reason at a time; plus READY and
+    UNKNOWN.
+
+    UNKNOWN is the *safe* value, and first-class on purpose: forges compute mergeability
+    ASYNCHRONOUSLY, so a just-pushed PR reads as "still checking" — that must never collapse to
+    READY or to a real blocker.
+
+    Fetched on demand via `Forge.merge_readiness` (a primitive, like `description`/`comments`),
+    deliberately NOT a `PullRequest` field: it's a derived verdict over the source×target tips
+    that goes stale the moment either branch moves (a merge into target can block YOUR PR with
+    your branch unchanged), so consumers should re-read it at the relevant decision boundary.
+    """
+
+    READY = "ready"
+    CONFLICT = "conflict"
+    DISCUSSIONS_UNRESOLVED = "discussions_unresolved"
+    CI_BLOCKED = "ci_blocked"
+    NEEDS_APPROVAL = "needs_approval"
+    DRAFT = "draft"
+    UNKNOWN = "unknown"
+
+
+class Forge(abc.ABC):
+    """Operations provided by a code-review host — defined in the domain's terms, NOT
+    mirroring any one SDK/REST surface. GitLab/GitHub adapters implement this as peers.
+
+    Methods return neutral PullRequest / Comment objects. Callers own workflow policy.
+    """
+
+    provider: str = ""
+
+    def list_repositories(
+        self, *, page_size: int | None = None, cursor: str | None = None
+    ) -> Page[Repository]:
+        """Read one page of repositories the authenticated account owns or participates in.
+
+        Default page_size is 50 (maximum 100). Resume with the same account and page size.
+        An inventory is not an atomic snapshot and does not cover every authored PR.
+        """
+        raise ForgeError("repository listing is not supported")
+
+    def repository(self) -> Repository:
+        """Read repository identity and optional direct same-Forge fork parent.
+
+        Missing provenance is not a failed lookup; transport errors propagate.
+        """
+        raise ForgeError("repository metadata is not supported")
+
+    def for_repository(self, path: str) -> Forge:
+        """Scope operations to a repository on this Forge instance.
+
+        PR numbers, queries and updates belong to path. No parent-selection policy.
+        """
+        raise ForgeError("repository scoping is not supported")
+
+    @abc.abstractmethod
+    def create(
+        self,
+        *,
+        source_repository: Repository,
+        source_branch: str,
+        target_repository: Repository,
+        target_branch: str,
+        title: str,
+        body: str = "",
+    ) -> PullRequest:
+        """Create from an explicit repository/branch pair on each side.
+
+        @spec Both repositories belong to this Forge instance; reject mismatch before I/O.
+        Repository scope on the client never overrides either explicit repository.
+        @link component://docs/pr.md
+        """
+        ...
+
+    def merge(self, number: int, *, expected_sha: str) -> PullRequest:
+        """Merge only the reviewed source tip; authorization belongs to the caller."""
+        raise ForgeError("merge is not supported")
+
+    @abc.abstractmethod
+    def get(self, number: int) -> PullRequest: ...
+
+    @abc.abstractmethod
+    def description(self, number: int) -> str:
+        """The PR/MR body text. A separate primitive rather than a `PullRequest` field:
+        bodies can be large, so they are fetched
+        only at the moment a caller syncs the description (see commit_flow)."""
+
+    @abc.abstractmethod
+    def update(self, number: int, **fields: str) -> PullRequest: ...
+
+    @abc.abstractmethod
+    def close(self, number: int) -> PullRequest:
+        """Close the PR/MR without merging. A distinct primitive, not `update(state=...)`: the
+        two forges spell it incompatibly (GitLab `state_event=close`, GitHub `state=closed`), so
+        the neutral verb hides that split instead of leaking either spelling into callers."""
+
+    @abc.abstractmethod
+    def prs_for_branch(
+        self, branch: str, *, source_repository: Repository | None = None
+    ) -> list[PullRequest]:
+        """All PRs whose source is `branch`, newest first (an old finished one + a new
+        open one can coexist after a branch is reused — callers pick).
+
+        Query this client's repository, filtering by the explicit source repository
+        (defaults to this repository). Target-branch selection belongs to the caller.
+        """
+
+    @abc.abstractmethod
+    def recent(self, limit: int) -> list[PullRequest]:
+        """The `limit` most-recently-created PRs in the repo, newest first."""
+
+    def open_pull_requests(self) -> list[PullRequest]:
+        """Complete open PR inventory sourced from this repository, newest first.
+
+        A failed page raises; partial inventories cannot establish absence. Foreign
+        source repositories are excluded, just as in prs_for_branch's default scope.
+        """
+        raise ForgeError(f"{self.provider}: open PR inventory is not supported")
+
+    def request_counts(self) -> dict[str, int]:
+        """Transport calls made by this client, including conditional validations."""
+        return {"requests": 0, "not_modified": 0}
+
+    @abc.abstractmethod
+    def default_branch(self) -> str:
+        """The repo's **forge-configured** default branch, e.g. 'main' / 'master' (one
+        repo-level GET). This is the remote source of truth, fresher and more reliable than
+        the local `refs/remotes/origin/HEAD` cache (which `git fetch` never updates). It is
+        NOT necessarily the branch a team merges into — a repo may default to `main` yet treat
+        `release` as trunk — so callers still layer a per-repo config override on top."""
+
+    @abc.abstractmethod
+    def create_release(self, *, tag: str, target: str, name: str = "", notes: str = "") -> Release:
+        """Publish a release `name` at `tag`, creating the tag at `target` (a branch name or
+        sha) on the server; this needs no local checkout or Git push.
+        GitHub uses target_commitish; GitLab uses ref.
+        A write primitive; version/increment policy lives in the release orchestrator, not here."""
+
+    @abc.abstractmethod
+    def latest_release(self) -> Release | None:
+        """The most recent published release, or None when the repo has none yet (its first
+        release). Read primitive — the orchestrator uses it to check the new version is an
+        increment; callers use the tag as the baseline for semantic release notes."""
+
+    @abc.abstractmethod
+    def comments(self, number: int) -> list[Comment]:
+        """Top-level human comments on PR/MR `number`, with review replies nested.
+
+        The adapter merges the provider's plain-comment and review surfaces. A replyable
+        review interaction is one Comment with `replies` and opaque action refs; callers do
+        not group flat provider notes or understand GitHub threads versus GitLab discussions.
+        System/bot activity notes are excluded.
+        """
+
+    @abc.abstractmethod
+    def comment(
+        self,
+        number: int,
+        body: str,
+        *,
+        replyable: bool = False,
+        path: str = "",
+        line: int | None = None,
+    ) -> None:
+        """Post one comment, optionally requiring a replyable provider interaction.
+
+        The default is a standalone GitHub issue comment / GitLab MR note. With
+        `replyable=True`, `path`/`line` optionally request a new-side diff anchor; adapters
+        raise when that shape is unsupported rather than silently publishing a standalone
+        comment. The caller owns any fallback policy.
+        """
+
+    def reply(self, number: int, target: Comment, body: str) -> None:
+        """Reply to a Comment returned by this Forge's `comments()`.
+
+        Adapters consume `target.reply_ref`. A standalone comment raises rather than silently
+        creating a detached response.
+        """
+        raise ForgeError(f"{self.provider or 'forge'}: replies not supported")
+
+    def resolve_comment(self, number: int, target: Comment) -> None:
+        """Resolve the review interaction backing `target` after its finding is handled.
+
+        Resolution is a separate, best-effort
+        forge transition. Adapters consume `target.resolve_ref`; unsupported comments raise so
+        callers keep the verdict while reporting that the merge blocker may remain.
+        """
+        raise ForgeError(f"{self.provider or 'forge'}: resolving comments not supported")
+
+    def merge_readiness(self, number: int) -> MergeReadiness:
+        """Why MR/PR `number` can't merge yet (CONFLICT / DISCUSSIONS_UNRESOLVED / …), or READY.
+        A fetch primitive (peer of `description`), NOT a `PullRequest` field — see `MergeReadiness`.
+        Concrete-with-default rather than abstract: an adapter that hasn't implemented it (today:
+        GitHub) inherits the safe UNKNOWN instead of being forced to lie; GitLab overrides."""
+        return MergeReadiness.UNKNOWN

repokit/forge/observation/__init__.py

@@ -0,0 +1,9 @@
+"""Persistent PR lifecycle queries and live local branch associations."""
+
+from .context import PullRequestContext as PullRequestContext
+from .model import BranchPullRequests as BranchPullRequests
+from .model import PullRequestKey as PullRequestKey
+from .model import PullRequestStatus as PullRequestStatus
+from .model import PullRequestStatusUnavailable as PullRequestStatusUnavailable
+from .service import PullRequestObserver as PullRequestObserver
+from .store import ObservationStorageError as ObservationStorageError

repokit/forge/observation/context.py

@@ -0,0 +1,255 @@
+"""PR association queries joined to live local branch and checkout topology."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from harness_common import Repository
+
+from ... import git_state
+from ...budget import operation
+from ...remote import remote
+from ..model import ForgeError, PullRequest
+from .model import BranchPullRequests, PullRequestKey
+from .service import PullRequestObserver, epoch, iso, key_from_json, key_json, repository_json
+from .store import JSON, digest
+
+
+class PullRequestContext:
+    """One local repository and explicit remote query scope; no workflow selection policy.
+
+    @spec An association is scoped by source repository, branch and target repositories.
+    @spec Multiple matching proposals remain ambiguous; detached checkouts have no branch.
+    @spec Git topology is read live and never persisted as authority to remove resources.
+    @link component://docs/pr.md
+    """
+
+    def __init__(
+        self,
+        observer: PullRequestObserver,
+        checkout: str | Path,
+        *,
+        source: Repository,
+        targets: tuple[Repository, ...],
+    ):
+        if not targets or any(repo.forge.name != observer.forge for repo in (source, *targets)):
+            raise ValueError("source and targets must belong to the observer Forge")
+        self.observer, self.checkout = observer, str(checkout)
+        self.source, self.targets = source, tuple(dict.fromkeys(targets))
+        self._remote = remote(self.checkout)
+
+    def _association_path(self, branch: str) -> Path:
+        observer = self.observer
+        identity = [
+            observer.connection,
+            repository_json(self.source),
+            branch,
+            [repository_json(repo) for repo in self.targets],
+        ]
+        return observer.store.root / "associations" / f"{digest(identity)}.json"
+
+    def _keys(self, branch: str, *, verify: bool) -> tuple[PullRequestKey, ...]:
+        observer = self.observer
+        path = self._association_path(branch)
+        with observer.store.locked(path) as owned:
+            record = observer.store.read(path)
+            if record and (
+                record.get("version") != 1
+                or not record.get("error")
+                and not isinstance(record.get("keys"), list)
+            ):
+                raise ForgeError("invalid PR association record")
+            try:
+                refresh_at = epoch(record.get("nextRefreshAt")) if record else 0
+                cached = (
+                    tuple(key_from_json(row) for row in cast(list[JSON], record["keys"]))
+                    if record and not record.get("error")
+                    else ()
+                )
+            except (KeyError, TypeError, ValueError) as exc:
+                raise ForgeError(f"invalid PR association record for {branch}: {exc}") from exc
+            if not verify and record and refresh_at > observer.now():
+                if record.get("error"):
+                    raise ForgeError(str(record["error"]))
+                return cached
+            keys: list[PullRequestKey] = []
+            try:
+                for target in self.targets:
+                    for pr in observer.reader.for_repository(target.path).prs_for_branch(
+                        branch, source_repository=self.source
+                    ):
+                        if (
+                            pr.source_repository != self.source.path
+                            or pr.target_repository != target.path
+                            or pr.source_branch != branch
+                        ):
+                            raise ForgeError("Forge returned a different branch association")
+                        keys.append(PullRequestKey(target, pr.number))
+            except (ForgeError, OSError) as exc:
+                if isinstance(exc, InterruptedError):
+                    raise
+                observer.store.write(
+                    path,
+                    {
+                        "version": 1,
+                        "error": str(exc),
+                        "nextRefreshAt": iso(observer.now() + observer.retry_interval),
+                    },
+                    owned,
+                )
+                raise
+            unique = tuple(dict.fromkeys(keys))
+            observer.store.write(
+                path,
+                {
+                    "version": 1,
+                    "keys": [key_json(key) for key in unique],
+                    "nextRefreshAt": iso(observer.now() + observer.open_interval),
+                },
+                owned,
+            )
+            return unique
+
+    def _branch(self, branch: str, *, verify: bool = False) -> BranchPullRequests:
+        with operation(timeout=self.observer.timeout, cancel=self.observer._stop):
+            heads = dict(git_state.list_local_branches(self.checkout))
+            if branch not in heads:
+                raise ValueError(f"local branch does not exist: {branch}")
+            head = heads[branch]
+            checkouts = tuple(
+                entry for entry in git_state.list_checkouts(self.checkout) if entry.branch == branch
+            )
+            candidates: list[PullRequest] = []
+            errors: list[str] = []
+            try:
+                keys = self._keys(branch, verify=verify)
+                for key in keys:
+                    try:
+                        pr = self.observer._snapshot(key, verify=verify)
+                        # Metadata belongs to the successful observation, not to a branch name.
+                        if not pr.source_repository or not pr.source_branch:
+                            raise ForgeError("observed PR source is unknown")
+                        if pr.source_branch != branch or pr.source_repository != self.source.path:
+                            continue
+                        candidates.append(pr)
+                    except (ForgeError, OSError) as exc:
+                        if isinstance(exc, InterruptedError):
+                            raise
+                        errors.append(str(exc))
+            except (ForgeError, OSError) as exc:
+                if isinstance(exc, InterruptedError):
+                    raise
+                errors.append(str(exc))
+            opens = [pr for pr in candidates if pr.is_open]
+            matching = list(opens)
+            if not opens:
+                for pr in candidates:
+                    try:
+                        if pr.sha and git_state.is_ancestor(self.checkout, pr.sha, head):
+                            matching.append(pr)
+                    except OSError as exc:
+                        if isinstance(exc, InterruptedError):
+                            raise
+                        errors.append(f"PR {pr.number} ancestry unavailable: {exc}")
+            return BranchPullRequests(
+                self.source,
+                branch,
+                head,
+                tuple(candidates),
+                checkouts,
+                matching[0] if len(matching) == 1 and not errors else None,
+                len(matching) > 1,
+                "; ".join(errors) or None,
+            )
+
+    def get_branch(self, branch: str) -> BranchPullRequests:
+        return self._branch(branch)
+
+    def get_checkout(self) -> BranchPullRequests | None:
+        branch = git_state.get_current_branch(self.checkout)
+        return self.get_branch(branch) if branch else None
+
+    def local_branches(self, *, limit: int = 20) -> tuple[BranchPullRequests, ...]:
+        """Bound cold discovery; oldest due associations progress independently of retries.
+
+        @spec Per-branch read failures preserve other results; cancellation aborts the round.
+        @case tests/test_pr_observation.py
+        """
+        if limit < 1:
+            raise ValueError("limit must be positive")
+        branches = git_state.list_local_branches(self.checkout)
+        checkouts = git_state.list_checkouts(self.checkout)
+        due = {}
+        unavailable: dict[str, str] = {}
+        for branch, _ in branches:
+            try:
+                record = self.observer.store.read(self._association_path(branch))
+                due[branch] = epoch(record.get("nextRefreshAt")) if record else 0
+            except (OSError, ValueError) as exc:
+                unavailable[branch] = str(exc)
+                due[branch] = float("inf")
+        selected = {
+            branch
+            for branch, at in sorted(due.items(), key=lambda item: (item[1], item[0]))
+            if at <= self.observer.now()
+        }
+        selected = set(sorted(selected, key=lambda branch: (due[branch], branch))[:limit])
+        results = []
+        with operation(timeout=self.observer.timeout, cancel=self.observer._stop):
+            from ...budget import current_budget
+
+            for branch, head in branches:
+                error = unavailable.get(branch)
+                try:
+                    current_budget(self.observer.timeout).remaining()
+                    if error:
+                        pass
+                    elif branch not in selected and due[branch] <= self.observer.now():
+                        error = "association discovery pending"
+                    else:
+                        results.append(self.get_branch(branch))
+                        continue
+                except TimeoutError:
+                    error = "association round timed out"
+                except (ForgeError, OSError, ValueError) as exc:
+                    if isinstance(exc, InterruptedError):
+                        raise
+                    error = str(exc)
+                results.append(
+                    BranchPullRequests(
+                        self.source,
+                        branch,
+                        head,
+                        (),
+                        tuple(c for c in checkouts if c.branch == branch),
+                        None,
+                        error=error,
+                    )
+                )
+        return tuple(results)
+
+    def for_pull_request(self, key: PullRequestKey) -> tuple[BranchPullRequests, ...]:
+        pr = self.observer._snapshot(key)
+        if key.repository not in self.targets or pr.source_repository != self.source.path:
+            return ()
+        if pr.source_branch not in dict(git_state.list_local_branches(self.checkout)):
+            return ()
+        branch = self.get_branch(pr.source_branch)
+        return (
+            (branch,)
+            if any(
+                p.number == key.number and p.target_repository == key.repository.path
+                for p in branch.candidates
+            )
+            else ()
+        )
+
+    def verify(self, previous: BranchPullRequests) -> BranchPullRequests:
+        """Recheck a decision's association and identity before the caller mutates resources."""
+        if remote(self.checkout) != self._remote:
+            raise ForgeError("source repository remote changed during PR decision")
+        current = self._branch(previous.branch, verify=True)
+        if current.head != previous.head or current.checkouts != previous.checkouts:
+            raise ForgeError("local branch or checkout changed during PR decision")
+        return current

repokit/forge/observation/model.py

@@ -0,0 +1,40 @@
+"""Public identities and query results, independent of local storage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from harness_common import Repository
+
+from ...git_state import CheckoutEntry
+from ..model import ForgeError, PullRequest
+
+
+@dataclass(frozen=True)
+class PullRequestKey:
+    repository: Repository
+    number: int
+
+
+@dataclass(frozen=True)
+class PullRequestStatus:
+    key: PullRequestKey
+    state: Literal["open", "closed", "merged"]
+    observed_at: str
+
+
+class PullRequestStatusUnavailable(ForgeError):
+    """No current lifecycle observation; an old snapshot is not a successful query."""
+
+
+@dataclass(frozen=True)
+class BranchPullRequests:
+    repository: Repository
+    branch: str
+    head: str
+    candidates: tuple[PullRequest, ...]
+    checkouts: tuple[CheckoutEntry, ...]
+    selected: PullRequest | None
+    ambiguous: bool = False
+    error: str | None = None