glab-cli-extras 0.1.0__py3-none-any.whl

glab_cli_extras/gitlab/refs.py

@@ -0,0 +1,151 @@
+"""Watched resources: the `ResourceRef` type and parsing of the command-line forms.
+
+Repository names are resolved by glab itself (`glab repo view [repo] -F json`), so `group/project`,
+`host/group/project` and an omitted repo (the cwd's git remotes) mean exactly what they mean to glab.
+URLs carry their host and project, so they need no request.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+from urllib.parse import urlsplit
+
+from glab_cli_extras.gitlab.glab import ProcessResult, run_glab_sync, stderr_message
+
+ResourceKind = Literal["mr", "pipeline", "mrs", "branch"]
+RESOURCE_KINDS: tuple[ResourceKind, ...] = ("mr", "pipeline", "mrs", "branch")
+
+_URL_RE = re.compile(r"^https?://(?P<host>[^/]+)/(?P<project>.+?)/-/(?P<what>merge_requests|pipelines)/(?P<id>\d+)")
+_ID_RE = re.compile(r"^(?:(?P<repo>.*)!)?(?P<id>\d+)$")
+
+
+class RefError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceRef:
+    kind: ResourceKind
+    host: str
+    project: str
+    id: int | None = None
+    """MR iid for `mr`, pipeline id for `pipeline`."""
+    branch: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.kind in ("mr", "pipeline") and self.id is None:
+            raise RefError(f"a {self.kind} reference needs an id")
+        if self.kind == "branch" and not self.branch:
+            raise RefError("a branch reference needs a branch name")
+
+    @property
+    def key(self) -> str:
+        """A stable identity, also used as the `resource` field of events: `mr gitlab.com/group/project!123`."""
+        return f"{self.kind} {self.short}"
+
+    @property
+    def short(self) -> str:
+        """The reference without the kind: `gitlab.com/group/project!123`."""
+        base = f"{self.host}/{self.project}"
+        if self.kind in ("mr", "pipeline"):
+            return f"{base}!{self.id}"
+        if self.kind == "branch":
+            return f"{base}:{self.branch}"
+        return base
+
+    def to_wire(self) -> dict[str, Any]:
+        wire: dict[str, Any] = {"kind": self.kind, "host": self.host, "project": self.project}
+        if self.id is not None:
+            wire["id"] = self.id
+        if self.branch is not None:
+            wire["branch"] = self.branch
+        return wire
+
+    @classmethod
+    def from_wire(cls, data: Any) -> ResourceRef:
+        if not isinstance(data, dict):
+            raise RefError("resource must be an object")
+        kind = data.get("kind")
+        if kind not in RESOURCE_KINDS:
+            raise RefError(f"unknown resource kind: {kind!r}")
+        host, project = data.get("host"), data.get("project")
+        if not isinstance(host, str) or not host or not isinstance(project, str) or not project:
+            raise RefError("resource needs host and project")
+        raw_id, branch = data.get("id"), data.get("branch")
+        if raw_id is not None and not isinstance(raw_id, int):
+            raise RefError("resource id must be an integer")
+        if branch is not None and not isinstance(branch, str):
+            raise RefError("resource branch must be a string")
+        return cls(cast(ResourceKind, kind), host, project, raw_id, branch)
+
+
+@dataclass(frozen=True, slots=True)
+class Repo:
+    host: str
+    project: str
+
+
+SyncRunner = Callable[[Sequence[str]], ProcessResult]
+
+
+def _default_runner(args: Sequence[str]) -> ProcessResult:
+    return run_glab_sync(args, timeout=30)
+
+
+def resolve_repo(spec: str | None, runner: SyncRunner = _default_runner) -> Repo:
+    """Resolve a repo name the way glab does, through `glab repo view [spec] -F json`. Costs one API request."""
+    args = ["repo", "view"] + ([spec] if spec else []) + ["-F", "json"]
+    result = runner(args)
+    try:
+        payload = json.loads(result.stdout or b"null")
+    except ValueError:
+        payload = None
+    if not isinstance(payload, dict) or "error" in payload or "web_url" not in payload:
+        detail = ""
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            detail = str(payload["error"].get("message", ""))
+        what = f"repository {spec!r}" if spec else "the repository of the current directory"
+        raise RefError(f"glab could not resolve {what}: {detail or stderr_message(result)}")
+    host = urlsplit(str(payload["web_url"])).netloc
+    project = str(payload.get("path_with_namespace") or "")
+    if not host or not project:
+        raise RefError(f"glab returned no host or project path for {spec or 'the current directory'}")
+    return Repo(host, project)
+
+
+def parse_id_ref(kind: Literal["mr", "pipeline"], arg: str, runner: SyncRunner = _default_runner) -> ResourceRef:
+    """Parse `<repo>!<id>`, `!<id>`, `<id>`, or a merge request or pipeline URL."""
+    arg = arg.strip()
+    url_match = _URL_RE.match(arg)
+    if url_match:
+        what = "merge_requests" if kind == "mr" else "pipelines"
+        if url_match.group("what") != what:
+            raise RefError(f"{arg} is not a {'merge request' if kind == 'mr' else 'pipeline'} URL")
+        return ResourceRef(kind, url_match.group("host"), url_match.group("project"), int(url_match.group("id")))
+    id_match = _ID_RE.match(arg)
+    if not id_match:
+        example = "group/project!123" if kind == "mr" else "group/project!4567"
+        raise RefError(f"cannot read {arg!r}: expected {example}, !<id>, <id>, or a URL")
+    repo = resolve_repo(id_match.group("repo") or None, runner)
+    return ResourceRef(kind, repo.host, repo.project, int(id_match.group("id")))
+
+
+def parse_repo_ref(
+    kind: Literal["mrs", "branch"],
+    repo_arg: str | None,
+    branch: str | None = None,
+    runner: SyncRunner = _default_runner,
+) -> ResourceRef:
+    """Parse the repo argument of `mrs` and `branch`. A project URL is accepted as well as a glab repo name."""
+    if repo_arg and repo_arg.startswith(("http://", "https://")):
+        parts = urlsplit(repo_arg)
+        project = parts.path.strip("/").split("/-/")[0].removesuffix(".git")
+        if not parts.netloc or not project:
+            raise RefError(f"cannot read the project from {repo_arg}")
+        return ResourceRef(kind, parts.netloc, project, branch=branch)
+    repo = resolve_repo(repo_arg, runner)
+    return ResourceRef(kind, repo.host, repo.project, branch=branch)

glab_cli_extras/paths.py

@@ -0,0 +1,79 @@
+"""Filesystem locations: the shared artifact cache, the daemon state dir, and the default changelog dir.
+
+Each location can be overridden by an environment variable, which the tests use to stay inside tmp dirs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+CACHE_DIR_ENV = "GLAB_CLI_EXTRAS_CACHE_DIR"
+STATE_DIR_ENV = "GLAB_CLI_EXTRAS_STATE_DIR"
+APP = "glab-cli-extras"
+
+
+def sanitize_part(value: str) -> str:
+    """Make one path component safe: no separators, no traversal, no characters Windows rejects."""
+    cleaned = re.sub(r"[^A-Za-z0-9._-]", "-", value).strip(".")
+    cleaned = cleaned.replace("..", "-")
+    return cleaned or "unknown"
+
+
+def project_dir(root: Path, host: str, project: str) -> Path:
+    """`<root>/<host>/<group>/<sub>/<project>`, each component sanitized."""
+    path = root / sanitize_part(host)
+    for part in project.split("/"):
+        path = path / sanitize_part(part)
+    return path
+
+
+def _uid_suffix() -> str:
+    getuid = getattr(os, "getuid", None)
+    return str(getuid()) if getuid is not None else (os.environ.get("USERNAME") or "user")
+
+
+def user_cache_dir() -> Path:
+    override = os.environ.get(CACHE_DIR_ENV)
+    if override:
+        return Path(override)
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+        return base / APP / "cache"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / APP
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".cache") / APP
+
+
+def daemon_state_dir() -> Path:
+    """The per-user dir holding the daemon's lock, socket (or port file) and log."""
+    override = os.environ.get(STATE_DIR_ENV)
+    if override:
+        return Path(override)
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+        return base / APP / "run"
+    if sys.platform == "darwin":
+        tmpdir = os.environ.get("TMPDIR")
+        if tmpdir:
+            return Path(tmpdir) / APP
+    else:
+        runtime = os.environ.get("XDG_RUNTIME_DIR")
+        if runtime and Path(runtime).is_dir():
+            return Path(runtime) / APP
+    return Path(tempfile.gettempdir()) / f"{APP}-{_uid_suffix()}"
+
+
+def ensure_private_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    if os.name != "nt":
+        os.chmod(path, 0o700)
+    return path
+
+
+def default_changelog_root() -> Path:
+    return Path(tempfile.gettempdir()) / f"glab-watch-{_uid_suffix()}"

glab_cli_extras/resources/__init__.py

@@ -0,0 +1,19 @@
+"""One poller per resource kind."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from glab_cli_extras.resources.base import Poller
+from glab_cli_extras.resources.branch import BranchPoller
+from glab_cli_extras.resources.mr import MrPoller
+from glab_cli_extras.resources.mr_list import MrListPoller
+from glab_cli_extras.resources.pipeline import PipelinePoller
+
+POLLERS: Mapping[str, type[Poller[Any]]] = {
+    "mr": MrPoller,
+    "pipeline": PipelinePoller,
+    "mrs": MrListPoller,
+    "branch": BranchPoller,
+}

glab_cli_extras/resources/base.py

@@ -0,0 +1,146 @@
+"""What every resource poller has in common.
+
+A poller owns one watched resource. Each `poll()` fetches what changed, diffs it against the previous snapshot and
+returns the events. The diff itself lives in a pure function per resource, so it can be tested without any I/O.
+The daemon decides when to call `poll()`, using `next_delay()`, `expected_cost()` and the host's budget.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar, Generic, TypeVar
+
+from glab_cli_extras.artifacts.job_logs import LogsMode
+from glab_cli_extras.events import RawEvent
+from glab_cli_extras.gitlab.client import ApiError, GitLabClient, encode_project
+from glab_cli_extras.gitlab.refs import ResourceKind, ResourceRef
+from glab_cli_extras.serde import from_jsonable, stable_hash, to_jsonable
+
+
+def gid_to_int(gid: Any) -> int:
+    """`gid://gitlab/Ci::Pipeline/123` → 123."""
+    return int(str(gid).rsplit("/", 1)[-1])
+
+
+def lower(value: Any) -> str:
+    return str(value).lower() if value is not None else ""
+
+
+async def is_force_push(client: GitLabClient, project: str, old_sha: str, new_sha: str) -> tuple[bool, str | None]:
+    """Whether moving a ref from `old_sha` to `new_sha` rewrote history. Costs one `merge_base` request.
+
+    The push is a fast-forward exactly when the merge base of the two commits is the old head. If GitLab no longer
+    has the old commit (pruned after a force-push), the push is reported as forced, with the reason.
+    """
+    try:
+        base = await client.get_json(
+            f"projects/{encode_project(project)}/repository/merge_base?refs[]={old_sha}&refs[]={new_sha}",
+            kind="merge_base",
+        )
+    except ApiError as exc:
+        if exc.status not in (400, 404):
+            raise
+        return True, "the previous head is no longer in the repository"
+    return (not isinstance(base, dict) or base.get("id") != old_sha), None
+
+
+@dataclass(frozen=True, slots=True)
+class PollerOptions:
+    """What the subscribers of a resource need, as the union over all of them."""
+
+    events: frozenset[str]
+    logs: LogsMode = "failed"
+
+    def wants(self, *kinds: str) -> bool:
+        return any(kind in self.events for kind in kinds)
+
+
+@dataclass
+class PushFeedCache:
+    """One `GET /projects/:id/events?action=pushed` call serves every watched branch of a project."""
+
+    max_age: float = 15.0
+    _entries: dict[tuple[str, str], tuple[float, list[Any]]] = field(default_factory=dict)
+
+    def get(self, host: str, project: str, now: float) -> list[Any] | None:
+        entry = self._entries.get((host, project))
+        if entry is None or now - entry[0] > self.max_age:
+            return None
+        return entry[1]
+
+    def put(self, host: str, project: str, now: float, events: list[Any]) -> None:
+        self._entries[(host, project)] = (now, events)
+
+
+@dataclass
+class PollContext:
+    client: GitLabClient
+    cache_root: Path
+    clock: Callable[[], float] = time.time
+    push_feeds: PushFeedCache = field(default_factory=PushFeedCache)
+
+
+S = TypeVar("S")
+
+
+class Poller(ABC, Generic[S]):
+    kind: ClassVar[ResourceKind]
+    snapshot_type: ClassVar[type[Any]]
+
+    def __init__(self, ref: ResourceRef, ctx: PollContext, options: PollerOptions) -> None:
+        self.ref = ref
+        self.ctx = ctx
+        self.options = options
+        self.snapshot: S | None = None
+        self.terminal_reason: str | None = None
+        self.terminal_data: dict[str, Any] = {}
+
+    def set_options(self, options: PollerOptions) -> None:
+        self.options = options
+
+    def seed(self, data: Any) -> bool:
+        """Start from a snapshot a client kept from an earlier daemon, so the first poll reports what changed."""
+        if self.snapshot is not None or data is None:
+            return False
+        try:
+            self.snapshot = from_jsonable(self.snapshot_type, data)
+        except ValueError:
+            return False
+        return True
+
+    @abstractmethod
+    async def poll(self) -> list[RawEvent]:
+        """Fetch, diff, update the snapshot. The first poll without a seed is the baseline and returns no events."""
+
+    @abstractmethod
+    def next_delay(self) -> float:
+        """Base seconds until the next poll, before the daemon stretches it under budget pressure."""
+
+    def expected_cost(self) -> float:
+        """Average requests per poll, for the budget's demand estimate."""
+        return 1.0
+
+    @abstractmethod
+    def summary(self) -> dict[str, Any]:
+        """A compact description of the current snapshot, sent in `watch_started`."""
+
+    def children(self) -> frozenset[ResourceRef]:
+        """Other resources whose events this one relays (an MR relays its head pipeline)."""
+        return frozenset()
+
+    def child_options(self, child: ResourceRef) -> PollerOptions | None:
+        return None
+
+    @property
+    def terminal(self) -> bool:
+        return self.terminal_reason is not None
+
+    def snapshot_json(self) -> Any:
+        return to_jsonable(self.snapshot) if self.snapshot is not None else None
+
+    def snapshot_hash(self) -> str | None:
+        return stable_hash(self.snapshot) if self.snapshot is not None else None

glab_cli_extras/resources/branch.py

@@ -0,0 +1,265 @@
+"""Branch watching: pushes from the project's push-event feed, pipelines through the GraphQL ETag cache.
+
+- Pushes come from `GET /projects/:id/events?action=pushed`, shared by every watched branch of the project and read
+  every 30 s. Push events carry no "forced" flag, so a push costs one `merge_base` request to tell a force-push.
+  A bulk push (more refs than GitLab's push-event limit) has no ref or SHAs; the branch endpoint fills the gap.
+- Pipelines come from one GraphQL query keyed on `project_pipelines/<project id>`, probed every 10 s. GitLab
+  touches that key on any pipeline change in the project, and answers an unchanged key with a free 304.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field, replace
+from typing import Any, ClassVar
+from urllib.parse import quote
+
+from glab_cli_extras.events import RawEvent
+from glab_cli_extras.gitlab import queries
+from glab_cli_extras.gitlab.client import NotFound, encode_project
+from glab_cli_extras.resources.base import Poller, gid_to_int, is_force_push, lower
+from glab_cli_extras.resources.pipeline import FINAL_PIPELINE_STATUSES
+
+PUSH_INTERVAL = 30.0
+PIPELINE_INTERVAL = 10.0
+FEED_PAGE_SIZE = 20
+MAX_FEED_PAGES = 5
+MERGE_TITLE_RE = re.compile(r"^Merge (branch|remote-tracking branch|pull request) ")
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineEntry:
+    id: int
+    status: str
+    sha: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class BranchSnapshot:
+    project: str
+    branch: str
+    exists: bool
+    head_sha: str | None
+    last_event_id: int
+    project_id: int | None = None
+    pipelines: tuple[PipelineEntry, ...] = field(default_factory=tuple)
+
+
+def diff_pipelines(prev: tuple[PipelineEntry, ...], cur: tuple[PipelineEntry, ...], web: str) -> list[RawEvent]:
+    known = {p.id: p for p in prev}
+    events = []
+    for pipeline in sorted(cur, key=lambda p: p.id):
+        old = known.get(pipeline.id)
+        data = {
+            "pipeline_id": pipeline.id,
+            "status": pipeline.status,
+            "sha": pipeline.sha,
+            "web_url": f"{web}/-/pipelines/{pipeline.id}",
+        }
+        if old is None:
+            events.append(RawEvent("pipeline_created", data))
+            if pipeline.status in FINAL_PIPELINE_STATUSES:
+                events.append(RawEvent("pipeline_finished", data))
+        elif pipeline.status in FINAL_PIPELINE_STATUSES and old.status not in FINAL_PIPELINE_STATUSES:
+            events.append(RawEvent("pipeline_finished", data))
+    return events
+
+
+def new_branch_pushes(feed: list[Any], branch: str, after_id: int) -> tuple[list[dict[str, Any]], bool]:
+    """Push events newer than `after_id` for the branch, oldest first, plus whether a bulk push is among them."""
+    relevant = []
+    bulk = False
+    for event in feed:
+        if not isinstance(event, dict) or int(event.get("id", 0)) <= after_id:
+            continue
+        push = event.get("push_data") or {}
+        if push.get("ref") is None and push.get("ref_type") in (None, "branch") and push.get("ref_count"):
+            bulk = True
+        elif push.get("ref_type") == "branch" and push.get("ref") == branch:
+            relevant.append(event)
+    return sorted(relevant, key=lambda e: int(e["id"])), bulk
+
+
+class BranchPoller(Poller[BranchSnapshot]):
+    kind: ClassVar = "branch"
+    snapshot_type: ClassVar = BranchSnapshot
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._etag: str | None = None
+        self._last_feed_check = 0.0
+
+    @property
+    def _branch(self) -> str:
+        assert self.ref.branch is not None
+        return self.ref.branch
+
+    @property
+    def _encoded(self) -> str:
+        return encode_project(self.ref.project)
+
+    @property
+    def _web(self) -> str:
+        return f"https://{self.ref.host}/{self.ref.project}"
+
+    async def _branch_head(self) -> str | None:
+        try:
+            data = await self.ctx.client.get_json(
+                f"projects/{self._encoded}/repository/branches/{quote(self._branch, safe='')}", kind="branch"
+            )
+        except NotFound:
+            return None
+        return str((data.get("commit") or {}).get("id")) if isinstance(data, dict) else None
+
+    async def _feed(self, after_id: int | None) -> list[Any]:
+        """Push events, newest first, reaching back to `after_id`. None means the newest page is enough."""
+        now = self.ctx.clock()
+        cached = self.ctx.push_feeds.get(self.ref.host, self.ref.project, now)
+        if cached is not None and (
+            after_id is None or len(cached) < FEED_PAGE_SIZE or min(int(e.get("id", 0)) for e in cached) <= after_id
+        ):
+            return cached
+        events: list[Any] = []
+        for page in range(1, MAX_FEED_PAGES + 1):
+            batch = await self.ctx.client.get_json(
+                f"projects/{self._encoded}/events",
+                {"action": "pushed", "sort": "desc", "per_page": FEED_PAGE_SIZE, "page": page},
+                kind="push_events",
+            )
+            if not isinstance(batch, list):
+                break
+            events.extend(batch)
+            if after_id is None or len(batch) < FEED_PAGE_SIZE or (batch and int(batch[-1].get("id", 0)) <= after_id):
+                break
+        self.ctx.push_feeds.put(self.ref.host, self.ref.project, now, events)
+        return events
+
+    async def _pipelines(self, snap: BranchSnapshot | None) -> tuple[int | None, tuple[PipelineEntry, ...] | None]:
+        project_id = snap.project_id if snap else None
+        result = await self.ctx.client.graphql(
+            queries.load("branch_pipelines"),
+            {"project": self.ref.project, "ref": self._branch},
+            etag_resource=f"project_pipelines/{project_id}" if project_id else None,
+            if_none_match=self._etag if project_id else None,
+            kind="branch_pipelines",
+        )
+        if result.not_modified:
+            return project_id, None
+        project = (result.data or {}).get("project")
+        if not project:
+            raise NotFound(f"project {self.ref.project} not found", 404)
+        self._etag = result.etag if project_id else None
+        nodes = (project.get("pipelines") or {}).get("nodes") or []
+        entries = tuple(
+            sorted(
+                (PipelineEntry(gid_to_int(n["id"]), lower(n.get("status")), n.get("sha")) for n in nodes),
+                key=lambda p: p.id,
+            )
+        )
+        return gid_to_int(project["id"]), entries
+
+    async def _baseline(self) -> list[RawEvent]:
+        head = await self._branch_head()
+        feed = await self._feed(None)
+        last_id = max((int(e.get("id", 0)) for e in feed if isinstance(e, dict)), default=0)
+        project_id, pipelines = await self._pipelines(None)
+        self._last_feed_check = self.ctx.clock()
+        self.snapshot = BranchSnapshot(
+            self.ref.project, self._branch, head is not None, head, last_id, project_id, pipelines or ()
+        )
+        return []
+
+    async def poll(self) -> list[RawEvent]:
+        if self.snapshot is None:
+            return await self._baseline()
+        snap = self.snapshot
+        events: list[RawEvent] = []
+        if self.options.wants("pipeline_created", "pipeline_finished"):
+            project_id, pipelines = await self._pipelines(snap)
+            if pipelines is not None:
+                events.extend(diff_pipelines(snap.pipelines, pipelines, self._web))
+                snap = replace(snap, project_id=project_id, pipelines=pipelines)
+        now = self.ctx.clock()
+        if now - self._last_feed_check >= PUSH_INTERVAL:
+            push_events, snap = await self._push_events(snap)
+            events.extend(push_events)
+            self._last_feed_check = now
+        self.snapshot = snap
+        return events
+
+    async def _push_events(self, snap: BranchSnapshot) -> tuple[list[RawEvent], BranchSnapshot]:
+        feed = await self._feed(snap.last_event_id)
+        pushes, bulk = new_branch_pushes(feed, self._branch, snap.last_event_id)
+        newest = max((int(e.get("id", 0)) for e in feed if isinstance(e, dict)), default=snap.last_event_id)
+        events: list[RawEvent] = []
+        head, exists = snap.head_sha, snap.exists
+        for push in pushes:
+            data = push.get("push_data") or {}
+            action = data.get("action")
+            author = push.get("author_username")
+            if action == "created":
+                events.append(RawEvent("created", {"sha": data.get("commit_to"), "author": author}))
+                head, exists = data.get("commit_to"), True
+            elif action == "removed":
+                events.append(RawEvent("deleted", {"sha": data.get("commit_from"), "author": author}))
+                head, exists = None, False
+            else:
+                event = await self._push_event(data.get("commit_from"), data.get("commit_to"), author, data)
+                events.append(event)
+                head, exists = data.get("commit_to"), True
+        if bulk and not pushes:
+            current = await self._branch_head()
+            if current != head:
+                if current is None:
+                    events.append(RawEvent("deleted", {"sha": head, "bulk_push": True}))
+                elif head is None:
+                    events.append(RawEvent("created", {"sha": current, "bulk_push": True}))
+                else:
+                    event = await self._push_event(head, current, None, {"bulk_push": True})
+                    events.append(event)
+                head, exists = current, current is not None
+        return events, replace(snap, head_sha=head, exists=exists, last_event_id=max(newest, snap.last_event_id))
+
+    async def _push_event(self, old: Any, new: Any, author: Any, push_data: dict[str, Any]) -> RawEvent:
+        data: dict[str, Any] = {"from": old, "to": new, "author": author}
+        for key in ("commit_count", "commit_title", "bulk_push"):
+            if push_data.get(key) is not None:
+                data[key] = push_data[key]
+        forced = False
+        if old and new and self.options.wants("force_pushed", "pushed"):
+            forced, reason = await is_force_push(self.ctx.client, self.ref.project, str(old), str(new))
+            if reason:
+                data["forced_reason"] = reason
+        title = str(push_data.get("commit_title") or "")
+        if not forced and new and MERGE_TITLE_RE.match(title):
+            data["merge_commit"] = True
+            merged = await self.ctx.client.get_json(
+                f"projects/{self._encoded}/repository/commits/{new}/merge_requests", kind="commit_mrs"
+            )
+            iids = [m.get("iid") for m in merged or [] if isinstance(m, dict) and m.get("state") == "merged"]
+            if iids:
+                data["merged_mr_iid"] = iids[0]
+        return RawEvent("force_pushed" if forced else "pushed", data)
+
+    def next_delay(self) -> float:
+        if self.options.wants("pipeline_created", "pipeline_finished"):
+            return PIPELINE_INTERVAL
+        return PUSH_INTERVAL
+
+    def expected_cost(self) -> float:
+        if self.options.wants("pipeline_created", "pipeline_finished"):
+            # A 304 probe every 10 s, plus one feed request every third poll.
+            return 0.1 + 1.0 / 3
+        return 1.0
+
+    def summary(self) -> dict[str, Any]:
+        snap = self.snapshot
+        if snap is None:
+            return {}
+        latest = max(snap.pipelines, key=lambda p: p.id) if snap.pipelines else None
+        return {
+            "branch": snap.branch,
+            "exists": snap.exists,
+            "head_sha": snap.head_sha,
+            "latest_pipeline": {"id": latest.id, "status": latest.status} if latest else None,
+        }