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

glab_cli_extras/__init__.py

@@ -0,0 +1,3 @@
+"""Extra commands for the GitLab CLI (glab)."""
+
+__version__ = "0.1.0"

glab_cli_extras/artifacts/job_logs.py

@@ -0,0 +1,95 @@
+"""Job logs, fetched once after a job ends.
+
+On GitLab 19.0 and later the trace endpoint takes `byte_offset` and `byte_limit` (at most 500 KB), so a large log is
+read as its last 500 KB only. The size comes from the job's trace artifact. Older versions get the full trace.
+A log already in the shared cache is reused, so two sessions watching the same pipeline download it once.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from glab_cli_extras.gitlab.client import GitLabClient, encode_project
+from glab_cli_extras.paths import project_dir, sanitize_part
+
+LogsMode = Literal["failed", "all", "none"]
+LOGS_MODES: tuple[LogsMode, ...] = ("failed", "all", "none")
+TAIL_BYTES = 500 * 1024
+"""GitLab's `Gitlab::Ci::Trace::Stream::LIMIT_SIZE`, the largest `byte_limit` it accepts."""
+BYTE_OFFSET_MIN_VERSION = (19, 0)
+
+
+def merge_logs_modes(modes: list[LogsMode]) -> LogsMode:
+    if "all" in modes:
+        return "all"
+    if "failed" in modes:
+        return "failed"
+    return "none"
+
+
+def wants_log(mode: LogsMode, status: str) -> bool:
+    if mode == "all":
+        return status in ("success", "failed", "canceled")
+    if mode == "failed":
+        return status == "failed"
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class FetchedLog:
+    path: Path
+    truncated: bool
+    size: int | None
+    reused: bool
+
+
+def log_path(cache_root: Path, host: str, project: str, job_id: int, job_name: str) -> Path:
+    return project_dir(cache_root, host, project) / "jobs" / f"{job_id}-{sanitize_part(job_name)[:80]}.log"
+
+
+def _trace_size(job: Any) -> int | None:
+    if not isinstance(job, dict):
+        return None
+    for artifact in job.get("artifacts") or []:
+        if (
+            isinstance(artifact, dict)
+            and artifact.get("file_type") == "trace"
+            and isinstance(artifact.get("size"), int)
+        ):
+            return int(artifact["size"])
+    return None
+
+
+async def fetch_job_log(
+    client: GitLabClient,
+    cache_root: Path,
+    project: str,
+    job_id: int,
+    job_name: str,
+    known_size: int | None,
+) -> FetchedLog:
+    """Download the job's log (or its tail) into the shared cache, unless it is already there."""
+    path = log_path(cache_root, client.host, project, job_id, job_name)
+    if path.is_file():
+        return FetchedLog(path, path.read_bytes().startswith(b"[glab-watch: last "), known_size, True)
+    encoded = encode_project(project)
+    version = await client.version()
+    tail_supported = version is not None and version >= BYTE_OFFSET_MIN_VERSION
+    size = known_size
+    if size is None and tail_supported:
+        size = _trace_size(await client.get_json(f"projects/{encoded}/jobs/{job_id}", kind="job"))
+    params: dict[str, str | int] = {}
+    truncated = False
+    if tail_supported and size is not None and size > TAIL_BYTES:
+        params = {"byte_offset": size - TAIL_BYTES, "byte_limit": TAIL_BYTES}
+        truncated = True
+    response = await client.get(f"projects/{encoded}/jobs/{job_id}/trace", params, kind="trace")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    header = f"[glab-watch: last {TAIL_BYTES} of {size} bytes]\n".encode() if truncated else b""
+    tmp.write_bytes(header + response.body)
+    os.replace(tmp, path)
+    return FetchedLog(path, truncated, size, False)

glab_cli_extras/artifacts/threads.py

@@ -0,0 +1,147 @@
+"""One markdown file per MR discussion thread, in the format glab-discussion uses.
+
+A file is rewritten only when its rendered content changed, so its mtime says when the thread last changed. The
+`.meta.json` next to the files maps each discussion id to its file name and content hash.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from glab_cli_extras.paths import sanitize_part
+
+META_FILE = ".meta.json"
+
+
+def _endpoint(old_line: Any, new_line: Any) -> str:
+    parts = []
+    if new_line is not None:
+        parts.append(f"new:{new_line}")
+    if old_line is not None:
+        parts.append(f"old:{old_line}")
+    return " / ".join(parts)
+
+
+def _position_lines(position: Mapping[str, Any]) -> list[str]:
+    lines = [f"File: {position.get('new_path') or position.get('old_path')}"]
+    line_range = position.get("line_range")
+    if isinstance(line_range, dict) and line_range.get("start") and line_range.get("end"):
+        start, end = line_range["start"], line_range["end"]
+        lines.append(
+            f"Lines: {_endpoint(start.get('old_line'), start.get('new_line'))}"
+            f" to {_endpoint(end.get('old_line'), end.get('new_line'))}"
+        )
+    else:
+        line = _endpoint(position.get("old_line"), position.get("new_line"))
+        if line:
+            lines.append(f"Line: {line}")
+    if position.get("head_sha"):
+        lines.append(f"Commit: {position['head_sha']}")
+    return lines
+
+
+def is_system_discussion(discussion: Mapping[str, Any]) -> bool:
+    notes = discussion.get("notes") or []
+    return bool(notes) and all(n.get("system") for n in notes)
+
+
+def render_discussion(discussion: Mapping[str, Any], mr_url: str) -> str:
+    """Render a REST discussion object as text: a header, then one block per note."""
+    notes: list[Mapping[str, Any]] = list(discussion.get("notes") or [])
+    first = notes[0] if notes else {}
+    lines = [f"Discussion: {discussion.get('id')}"]
+    position = first.get("position")
+    if first.get("type") == "DiffNote" and isinstance(position, dict):
+        lines.append("Type: DiffNote")
+        lines.extend(_position_lines(position))
+    else:
+        lines.append("Type: General")
+    resolvable = [n for n in notes if n.get("resolvable")]
+    if resolvable:
+        lines.append(f"Resolved: {'yes' if all(n.get('resolved') for n in resolvable) else 'no'}")
+    if first.get("id") is not None:
+        lines.append(f"URL: {mr_url}#note_{first['id']}")
+    lines.append("---")
+    for note in notes:
+        author = (note.get("author") or {}).get("username", "unknown")
+        timestamp = str(note.get("created_at", "")).replace("T", " ").split(".")[0].removesuffix("Z")
+        lines.append(f"[{timestamp}] @{author} (note:{note.get('id')}):")
+        lines.append(str(note.get("body", "")))
+        lines.append("")
+    return "\n".join(lines)
+
+
+def thread_filename(discussion: Mapping[str, Any]) -> str:
+    """`<created, to the minute>-<author>-<id prefix>.md`, so a directory listing sorts threads by start time."""
+    notes = discussion.get("notes") or [{}]
+    first = notes[0]
+    created = sanitize_part(str(first.get("created_at", ""))[:16].replace(":", "-")) or "unknown"
+    author = sanitize_part(str((first.get("author") or {}).get("username", "unknown")))
+    short_id = sanitize_part(str(discussion.get("id", ""))[:12])
+    return f"{created}-{author}-{short_id}.md"
+
+
+def _hash(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+class ThreadStore:
+    def __init__(self, directory: Path, mr_url: str) -> None:
+        self.directory = directory
+        self.mr_url = mr_url
+        self._meta_path = directory / META_FILE
+        self._meta: dict[str, dict[str, str]] = self._load_meta()
+
+    def _load_meta(self) -> dict[str, dict[str, str]]:
+        try:
+            raw = json.loads(self._meta_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        if not isinstance(raw, dict):
+            return {}
+        return {str(k): v for k, v in raw.items() if isinstance(v, dict)}
+
+    def _save_meta(self) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        tmp = self._meta_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(self._meta, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        os.replace(tmp, self._meta_path)
+
+    def path_for(self, discussion_id: str) -> Path | None:
+        entry = self._meta.get(discussion_id)
+        return self.directory / entry["filename"] if entry else None
+
+    def write(self, discussion: Mapping[str, Any]) -> tuple[Path, bool]:
+        """Write the thread's file if its content changed. Return the path and whether it was written."""
+        discussion_id = str(discussion["id"])
+        content = render_discussion(discussion, self.mr_url)
+        filename = thread_filename(discussion)
+        path = self.directory / filename
+        digest = _hash(content)
+        old = self._meta.get(discussion_id)
+        if old and old.get("hash") == digest and old.get("filename") == filename and path.is_file():
+            return path, False
+        self.directory.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(content, encoding="utf-8")
+        os.replace(tmp, path)
+        if old and old.get("filename") and old["filename"] != filename:
+            with contextlib.suppress(OSError):
+                (self.directory / old["filename"]).unlink()
+        self._meta[discussion_id] = {"filename": filename, "hash": digest}
+        self._save_meta()
+        return path, True
+
+    def remove(self, discussion_id: str) -> None:
+        entry = self._meta.pop(discussion_id, None)
+        if entry is None:
+            return
+        with contextlib.suppress(OSError):
+            (self.directory / entry["filename"]).unlink()
+        self._save_meta()

glab_cli_extras/cli/watch.py

@@ -0,0 +1,426 @@
+"""`glab-watch`: report changes to a merge request, a pipeline, a project's merge requests, or a branch."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+
+from glab_cli_extras import __version__
+from glab_cli_extras.artifacts.job_logs import LOGS_MODES, LogsMode
+from glab_cli_extras.daemon.lifecycle import daemon_running, stop_daemon
+from glab_cli_extras.daemon.transport import DaemonFiles, DaemonUnavailable, request
+from glab_cli_extras.events import GROUPS, KINDS_BY_RESOURCE, LIFECYCLE_KINDS, FilterError, resolve_filter
+from glab_cli_extras.gitlab.glab import GlabNotFoundError
+from glab_cli_extras.gitlab.refs import RefError, ResourceRef, parse_id_ref, parse_repo_ref
+from glab_cli_extras.paths import default_changelog_root, user_cache_dir
+from glab_cli_extras.watch.changelog import Changelog
+from glab_cli_extras.watch.client import Backend, BackendError, Watcher, WatchSettings, default_backend
+from glab_cli_extras.watch.sinks import Sink, StatusOutput
+from glab_cli_extras.watch.streams import MESSAGE_PRIORITIES, STREAM_MODES, StreamError, open_stream
+
+EXIT_USAGE = 2
+
+app = typer.Typer(
+    name="glab-watch",
+    help=(
+        "Watch a GitLab merge request, pipeline, project or branch and report each change as a JSON event. "
+        "Uses the glab CLI for every request; a shared background daemon keeps many watchers cheap on the API."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode=None,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+daemon_app = typer.Typer(help="Inspect or stop the shared polling daemon.", no_args_is_help=True)
+app.add_typer(daemon_app, name="daemon")
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"glab-watch {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=_version, is_eager=True, help="Print the version and exit.")
+    ] = False,
+) -> None:
+    pass
+
+
+EventsOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--events",
+        help="Report only these event kinds or groups, comma-separated (groups: status, comments, push, pipeline).",
+    ),
+]
+ExcludeOpt = Annotated[
+    list[str] | None,
+    typer.Option("--exclude-events", help="Do not report these event kinds or groups, comma-separated."),
+]
+StreamOpt = Annotated[
+    str,
+    typer.Option(
+        "--events-stream",
+        help="auto picks claude-message inside a Claude Code session that accepts messages, else stdout.",
+    ),
+]
+ChangelogOpt = Annotated[
+    Path | None, typer.Option("--changelog-dir", help="Root dir of the events.jsonl and state.json files.")
+]
+UntilOpt = Annotated[str | None, typer.Option("--until", help="Stop after the first event of this kind.")]
+TimeoutOpt = Annotated[
+    str | None, typer.Option("--timeout", help="Stop after this long, for example 90s, 30m, 2h, 1h30m.")
+]
+NoDaemonOpt = Annotated[
+    bool, typer.Option("--no-daemon", help="Poll inside this process with a private budget, without the daemon.")
+]
+PriorityOpt = Annotated[
+    str,
+    typer.Option(
+        "--message-priority",
+        help="claude-message only: now or next deliver into the running turn, later waits until the session is idle.",
+    ),
+]
+LogsOpt = Annotated[str, typer.Option("--logs", help="Which finished jobs get their log fetched: failed, all or none.")]
+
+_DURATION_RE = re.compile(r"^(?:(?P<h>\d+)h)?(?:(?P<m>\d+)m)?(?:(?P<s>\d+)s)?$")
+
+
+def parse_duration(value: str) -> float:
+    text = value.strip().lower()
+    if text.replace(".", "", 1).isdigit():
+        return float(text)
+    match = _DURATION_RE.match(text)
+    if not text or not match or not any(match.groupdict().values()):
+        raise ValueError(f"cannot read the duration {value!r}; use for example 90s, 30m, 2h or 1h30m")
+    parts = {k: int(v) if v else 0 for k, v in match.groupdict().items()}
+    return float(parts["h"] * 3600 + parts["m"] * 60 + parts["s"])
+
+
+def _fail(message: str, code: int = EXIT_USAGE) -> NoReturn:
+    StatusOutput(sys.stderr).line(f"error: {message}")
+    raise typer.Exit(code)
+
+
+def restart_ref(ref: ResourceRef) -> str:
+    """The resource as a command-line argument that resolves without the cwd."""
+    base = f"https://{ref.host}/{ref.project}"
+    if ref.kind == "mr":
+        return f"{base}/-/merge_requests/{ref.id}"
+    if ref.kind == "pipeline":
+        return f"{base}/-/pipelines/{ref.id}"
+    if ref.kind == "branch":
+        return f"{base} {ref.branch}"
+    return base
+
+
+def print_header(
+    status: StatusOutput,
+    ref: ResourceRef,
+    sink: Sink,
+    changelog: Changelog,
+    events: frozenset[str],
+    logs: LogsMode | None,
+    backend: Backend,
+    until: str | None,
+    timeout: str | None,
+    fallback: str | None = None,
+) -> None:
+    """The startup header: what is watched, how events are delivered, and how to restart with other options."""
+    tracked = KINDS_BY_RESOURCE[ref.kind]
+    subscribed = [k for k in tracked if k in events]
+    ignored = [k for k in tracked if k not in events]
+    status.line(f"resource: {ref.key}")
+    status.line(f"stream: {sink.describe()}")
+    if fallback:
+        status.line(f"stream fallback: not messaging the Claude Code session: {fallback}")
+    status.line(f"changelog: {changelog.events_path}")
+    status.line(f"events: {','.join(subscribed) or '(none)'} (always: {','.join(LIFECYCLE_KINDS)})")
+    status.line(f"ignored: {','.join(ignored) or '(none)'}")
+    if logs is not None:
+        status.line(f"logs: {logs}")
+    if until or timeout:
+        status.line(
+            f"ends: {'on ' + until if until else ''}{' or ' if until and timeout else ''}"
+            f"{'after ' + timeout if timeout else ''}"
+        )
+    status.line(f"daemon: {backend.describe()}")
+    groups = ", ".join(f"{name}" for name in GROUPS if name != "lifecycle" and set(GROUPS[name]) & set(tracked))
+    options = "--events=<kinds|groups> --exclude-events=<kinds|groups>"
+    if logs is not None:
+        options += " --logs=failed|all|none"
+    status.line(f"restart with: glab-watch {ref.kind} {restart_ref(ref)} {options} (groups: {groups})")
+
+
+def run_watch(
+    resolve: Callable[[], ResourceRef],
+    kind: str,
+    *,
+    events: list[str] | None,
+    exclude_events: list[str] | None,
+    events_stream: str,
+    changelog_dir: Path | None,
+    until: str | None,
+    timeout: str | None,
+    no_daemon: bool,
+    message_priority: str,
+    logs: str | None,
+) -> None:
+    if events_stream not in STREAM_MODES:
+        _fail(f"--events-stream must be one of {', '.join(STREAM_MODES)}")
+    if message_priority not in MESSAGE_PRIORITIES:
+        _fail(f"--message-priority must be one of {', '.join(MESSAGE_PRIORITIES)}")
+    if logs is not None and logs not in LOGS_MODES:
+        _fail(f"--logs must be one of {', '.join(LOGS_MODES)}")
+    try:
+        selected = resolve_filter(kind, events, exclude_events)
+    except FilterError as exc:
+        _fail(str(exc))
+    if until is not None and until not in KINDS_BY_RESOURCE[kind]:
+        _fail(f"--until: a {kind} watch never produces {until!r}")
+    if until is not None and until not in selected:
+        _fail(f"--until={until} is filtered out by --events/--exclude-events")
+    try:
+        timeout_s = parse_duration(timeout) if timeout else None
+    except ValueError as exc:
+        _fail(str(exc))
+    try:
+        ref = resolve()
+    except (RefError, GlabNotFoundError) as exc:
+        _fail(str(exc))
+
+    status = StatusOutput()
+    try:
+        stream = open_stream(events_stream, ref, message_priority, changelog_dir, default_changelog_root(), status)
+    except StreamError as exc:
+        _fail(str(exc))
+    changelog = stream.changelog
+    logs_mode: LogsMode = logs if logs in LOGS_MODES else "failed"
+    try:
+        backend = default_backend(no_daemon, user_cache_dir())
+    except (DaemonUnavailable, TimeoutError) as exc:
+        _fail(f"cannot start the daemon: {exc}; retry with --no-daemon to poll without it", 1)
+    print_header(
+        status,
+        ref,
+        stream.sink,
+        changelog,
+        selected,
+        logs if logs is not None else None,
+        backend,
+        until,
+        timeout,
+        stream.fallback,
+    )
+    watcher = Watcher(
+        WatchSettings(ref, selected, logs_mode, until, timeout_s), backend, stream.sink, changelog, status
+    )
+    try:
+        code = watcher.run()
+    finally:
+        backend.close()
+    raise typer.Exit(code)
+
+
+@app.command()
+def mr(
+    ref: Annotated[str, typer.Argument(help="group/project!123, !123, 123 (repo from the cwd), or the MR URL.")],
+    events: EventsOpt = None,
+    exclude_events: ExcludeOpt = None,
+    logs: LogsOpt = "failed",
+    until: UntilOpt = None,
+    timeout: TimeoutOpt = None,
+    events_stream: StreamOpt = "auto",
+    changelog_dir: ChangelogOpt = None,
+    message_priority: PriorityOpt = "next",
+    no_daemon: NoDaemonOpt = False,
+) -> None:
+    """Watch one merge request: state, pushes, approvals, threads, and its head pipeline. Ends when merged or closed."""
+    run_watch(
+        lambda: parse_id_ref("mr", ref),
+        "mr",
+        events=events,
+        exclude_events=exclude_events,
+        events_stream=events_stream,
+        changelog_dir=changelog_dir,
+        until=until,
+        timeout=timeout,
+        no_daemon=no_daemon,
+        message_priority=message_priority,
+        logs=logs,
+    )
+
+
+@app.command()
+def pipeline(
+    ref: Annotated[str, typer.Argument(help="group/project!4567, !4567, 4567 (repo from the cwd), or the URL.")],
+    events: EventsOpt = None,
+    exclude_events: ExcludeOpt = None,
+    logs: LogsOpt = "failed",
+    until: UntilOpt = None,
+    timeout: TimeoutOpt = None,
+    events_stream: StreamOpt = "auto",
+    changelog_dir: ChangelogOpt = None,
+    message_priority: PriorityOpt = "next",
+    no_daemon: NoDaemonOpt = False,
+) -> None:
+    """Watch one pipeline and its downstream pipelines. Ends when it finishes and the wanted logs are fetched."""
+    run_watch(
+        lambda: parse_id_ref("pipeline", ref),
+        "pipeline",
+        events=events,
+        exclude_events=exclude_events,
+        events_stream=events_stream,
+        changelog_dir=changelog_dir,
+        until=until,
+        timeout=timeout,
+        no_daemon=no_daemon,
+        message_priority=message_priority,
+        logs=logs,
+    )
+
+
+@app.command()
+def mrs(
+    repo: Annotated[str | None, typer.Argument(help="group/project or a project URL; default: the cwd's repo.")] = None,
+    events: EventsOpt = None,
+    exclude_events: ExcludeOpt = None,
+    until: UntilOpt = None,
+    timeout: TimeoutOpt = None,
+    events_stream: StreamOpt = "auto",
+    changelog_dir: ChangelogOpt = None,
+    message_priority: PriorityOpt = "next",
+    no_daemon: NoDaemonOpt = False,
+) -> None:
+    """Watch every merge request of a project: opened, updated, merged, closed, reopened. Runs until stopped."""
+    run_watch(
+        lambda: parse_repo_ref("mrs", repo),
+        "mrs",
+        events=events,
+        exclude_events=exclude_events,
+        events_stream=events_stream,
+        changelog_dir=changelog_dir,
+        until=until,
+        timeout=timeout,
+        no_daemon=no_daemon,
+        message_priority=message_priority,
+        logs=None,
+    )
+
+
+@app.command()
+def branch(
+    args: Annotated[list[str], typer.Argument(metavar="[REPO] BRANCH", help="The branch, optionally after the repo.")],
+    events: EventsOpt = None,
+    exclude_events: ExcludeOpt = None,
+    until: UntilOpt = None,
+    timeout: TimeoutOpt = None,
+    events_stream: StreamOpt = "auto",
+    changelog_dir: ChangelogOpt = None,
+    message_priority: PriorityOpt = "next",
+    no_daemon: NoDaemonOpt = False,
+) -> None:
+    """Watch a branch: pushes, force-pushes, creation, deletion, and its pipelines. Runs until stopped."""
+    if len(args) not in (1, 2):
+        _fail("expected [REPO] BRANCH")
+    repo, name = (None, args[0]) if len(args) == 1 else (args[0], args[1])
+    run_watch(
+        lambda: parse_repo_ref("branch", repo, name),
+        "branch",
+        events=events,
+        exclude_events=exclude_events,
+        events_stream=events_stream,
+        changelog_dir=changelog_dir,
+        until=until,
+        timeout=timeout,
+        no_daemon=no_daemon,
+        message_priority=message_priority,
+        logs=None,
+    )
+
+
+@daemon_app.command("status")
+def daemon_status(
+    as_json: Annotated[bool, typer.Option("--json", help="Print the raw status object.")] = False,
+) -> None:
+    """Show the daemon's subscriptions, resources, budgets and request counts."""
+    files = DaemonFiles.default()
+    try:
+        response = request(files, {"op": "status"}, timeout=5)
+    except DaemonUnavailable:
+        running = daemon_running(files)
+        typer.echo("daemon: not running" if not running else "daemon: running but not answering; see daemon logs")
+        raise typer.Exit(0 if not running else 1) from None
+    if as_json:
+        typer.echo(json.dumps(response, indent=2))
+        return
+    _print_status(response, files)
+
+
+def _print_status(status: dict[str, Any], files: DaemonFiles) -> None:
+    typer.echo(
+        f"daemon: pid {status['pid']}, version {status['version']}, protocol {status['protocol']}, "
+        f"up {status['uptime_s']} s, endpoint {files.describe_endpoint()}"
+    )
+    for sub in status.get("subscriptions", []):
+        typer.echo(
+            f"subscription {sub['id'][:8]} client {sub['client_id'][:8]} {sub['resource']} "
+            f"(lease idle {sub['idle_s']} s, logs {sub['logs']})"
+        )
+    for res in status.get("resources", []):
+        state = "ended" if res["ended"] else (f"degraded: {res['degraded']}" if res["degraded"] else "active")
+        typer.echo(
+            f"resource {res['resource']}: {state}, {res['polls']} polls, seq {res['seq']}, "
+            f"next poll in {res['next_poll_in_s']} s"
+        )
+    for host, info in status.get("hosts", {}).items():
+        requests, budget = info["requests"], info["budget"]
+        typer.echo(
+            f"host {host}: {requests['requests']} requests ({requests['not_modified']} not modified), "
+            f"budget {budget['rate_per_minute']}/min, remaining {budget['remaining']}"
+        )
+
+
+@daemon_app.command("stop")
+def daemon_stop() -> None:
+    """Stop the daemon. Running watchers start a new one on their next poll."""
+    files = DaemonFiles.default()
+    try:
+        stopped = stop_daemon(files)
+    except DaemonUnavailable as exc:
+        _fail(str(exc), 1)
+    typer.echo("daemon: stopped" if stopped else "daemon: not running")
+
+
+@daemon_app.command("logs")
+def daemon_logs(
+    lines: Annotated[int, typer.Option("--lines", "-n", help="How many lines from the end.")] = 50,
+) -> None:
+    """Print the end of the daemon's log file."""
+    files = DaemonFiles.default()
+    try:
+        content = files.log.read_text(encoding="utf-8", errors="replace").splitlines()
+    except FileNotFoundError:
+        typer.echo(f"no daemon log at {files.log}")
+        return
+    typer.echo(f"==> {files.log}")
+    for line in content[-lines:]:
+        typer.echo(line)
+
+
+def main() -> None:
+    try:
+        app()
+    except (BackendError, DaemonUnavailable) as exc:
+        StatusOutput(sys.stderr).line(f"error: {exc}")
+        sys.exit(1)

glab_cli_extras/daemon/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m glab_cli_extras.daemon`: the daemon process. Clients start it; it is not meant to be run by hand."""
+
+from __future__ import annotations
+
+import sys
+
+from glab_cli_extras.daemon.lifecycle import run_daemon
+
+if __name__ == "__main__":
+    sys.exit(run_daemon())