sharefetch 1.0.0__py3-none-any.whl

sharefetch/gui.py

@@ -0,0 +1,1170 @@
+"""The tkinter front end: one window over one :func:`sharefetch.engine.run`.
+
+The engine runs on a worker thread and reaches the window only by putting an
+event on a :class:`queue.Queue`. The main thread drains that queue under
+``root.after``, so every Tk call in this module runs on the thread that created
+the widget and no network call runs on it. Tk is not thread safe and a
+widget touched from the engine thread produces a corruption that appears
+intermittently and far from its cause, so the queue is the only channel.
+
+Three objects cross the thread boundary and nothing else does.
+
+``_QueueSink``
+    The :class:`~sharefetch.events.EventSink` the engine emits through. Its
+    ``emit`` puts the event on the queue and returns.
+
+``_QueueLogHandler``
+    A :class:`logging.Handler` on the ``sharefetch`` logger. It formats a record
+    once, wraps it in a :class:`~sharefetch.events.LogRecord` and puts it on the
+    same queue, so the log pane receives exactly the records a log file would
+    receive with no second formatting path. It carries
+    :class:`~sharefetch.graph.RedactingFilter`, so a credential never reaches
+    the pane.
+
+``App._publish``
+    Called once on the worker thread to hand the main thread the run's
+    :class:`~sharefetch.auth.TokenProvider` and :class:`~sharefetch.engine.Engine`
+    under a lock, which is how Cancel, Pause, Resume and Stop reach a run that
+    is already in flight. It touches no widget.
+
+Every option the window offers is validated by the boundary validators in
+:mod:`sharefetch.config`, so this front end and the command-line front end
+cannot diverge on what a legal value is.
+
+The device code and the verification URI are displayed by design and are never
+logged. No token material is displayed or logged anywhere.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+import time
+import tkinter as tk
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from tkinter import filedialog, ttk
+from tkinter import font as tkfont
+from typing import Any
+
+from .auth import TokenProvider
+from .config import (
+    CHUNK_KIB_BOUNDS,
+    CONNECTIONS_BOUNDS,
+    DEFAULT_CHUNK_KIB,
+    DEFAULT_CONNECTIONS,
+    DEFAULT_DELAY_SECONDS,
+    DELAY_BOUNDS,
+    GUI_DRAIN_INTERVAL_MS,
+    GUI_LOG_MAX_LINES,
+    GUI_STOP_JOIN_SECONDS,
+    STATUS_COMPLETE,
+    STATUS_FAILED,
+    STATUS_SKIPPED,
+    Settings,
+    check_chunk_kib,
+    check_connections,
+    check_delay,
+    check_dest,
+    check_limit_rate,
+)
+from .engine import Engine
+from .errors import SharefetchError, ValidationError
+from .events import (
+    DeviceCodeCompleted,
+    DeviceCodeRequested,
+    EnumerationComplete,
+    EnumerationProgress,
+    FileFinished,
+    FileProgress,
+    FileStarted,
+    LogRecord,
+    Reconciled,
+    Resolved,
+    RunFinished,
+    Throttled,
+)
+from .graph import RedactingFilter
+from .paths import sanitise_segment
+from .urls import ShareRef, SitePathRef
+from .urls import parse as parse_url
+
+logger = logging.getLogger(__name__)
+
+PACKAGE_LOGGER_NAME = "sharefetch"
+
+# Constants the window needs that config.py does not hold. Each one lives
+# beside the only code that reads it, with the reason it exists.
+
+# How many queued items one drain pass consumes. A large transfer emits one
+# FileProgress per chunk, and an unbounded drain would let a burst hold the
+# main thread long enough to drop a redraw. At the 100 ms drain interval this
+# cap still clears 2000 items a second, which is far above the rate any
+# rate-limited transfer produces.
+DRAIN_BATCH_LIMIT = 200
+
+# The upper stop of the rate-limit spinbox arrows. config.py bounds the rate
+# ceiling below and leaves it unbounded above, so the arrows need a stop that
+# the validator does not supply. Typed input is still read through
+# config.check_limit_rate, which remains the authority on what is accepted.
+RATE_SPINBOX_CEILING_KBPS = 1_000_000
+
+# 0 in the rate spinbox means no ceiling, which is how config.Settings spells it
+# as ``limit_rate_kbps=None``. The spinbox cannot hold None.
+RATE_OFF = 0
+
+# Point size of the device code label. The code is read off the screen and
+# typed into a browser on another device, so it is set well above the interface
+# font rather than inheriting it.
+DEVICE_CODE_FONT_SIZE = 22
+
+DELAY_SPIN_INCREMENT = 0.1
+CHUNK_SPIN_INCREMENT_KIB = 64
+RATE_SPIN_INCREMENT_KBPS = 64
+
+BYTES_PER_UNIT = 1024.0
+BYTE_UNITS = ("B", "KiB", "MiB", "GiB", "TiB", "PiB")
+
+# Progressbar values are doubles and a byte total is an exact integer, so the
+# bars are driven in permille of the total and never in raw bytes.
+PROGRESS_SCALE = 1000
+
+_STATE_IDLE = "idle"
+_STATE_RUNNING = "running"
+_STATE_PAUSED = "paused"
+_STATE_STOPPING = "stopping"
+
+# A graphical front end's exit code is rarely read, but the two front ends
+# report the same outcome with the same number.
+EXIT_OK = 0
+EXIT_FAILURES = 1
+EXIT_FATAL = 2
+
+_ERROR_COLOUR = "#b00020"
+_LINK_COLOUR = "#0645ad"
+
+
+# ----------------------------------------------------------------------
+# Objects that cross the thread boundary
+# ----------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _RunFailed:
+    """A fatal error ended the run. Put on the queue by the worker thread."""
+
+    message: str
+
+
+@dataclass(frozen=True)
+class _RunEnded:
+    """The worker thread is about to exit, whatever the outcome was."""
+
+
+class _QueueSink:
+    """The event sink the engine emits through. Puts and returns, never blocks.
+
+    Implements :class:`~sharefetch.events.EventSink`. The queue is unbounded, so
+    a slow drain never stalls a transfer and a main thread blocked in a join can
+    never deadlock against an engine thread trying to emit.
+    """
+
+    def __init__(self, events: queue.Queue[Any]) -> None:
+        self._events = events
+
+    def emit(self, event: Any) -> None:
+        self._events.put(event)
+
+
+class _QueueLogHandler(logging.Handler):
+    """Turns each log record into a ``LogRecord`` event on the window's queue.
+
+    Attached to the ``sharefetch`` logger, so the pane shows exactly what a log
+    file would hold. The record is formatted here, on whichever thread logged
+    it, and only the finished string crosses to the main thread.
+    """
+
+    def __init__(self, events: queue.Queue[Any]) -> None:
+        super().__init__()
+        self._events = events
+        self.addFilter(RedactingFilter())
+        self.setFormatter(logging.Formatter("%(asctime)s %(levelname)-8s %(name)s %(message)s"))
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            self._events.put(LogRecord(level=record.levelname, message=self.format(record)))
+        except Exception:
+            self.handleError(record)
+
+
+# ----------------------------------------------------------------------
+# Option reading, through the config validators and nothing else
+# ----------------------------------------------------------------------
+
+
+def _whole_number(name: str, text: str) -> int:
+    """Read a spinbox's text as an integer, or reject it in the validators' style."""
+    candidate = (text or "").strip()
+    try:
+        return int(candidate)
+    except ValueError as exc:
+        raise ValidationError(f"{name} must be a whole number, received {candidate!r}") from exc
+
+
+def _decimal_number(name: str, text: str) -> float:
+    """Read a spinbox's text as a float, or reject it in the validators' style."""
+    candidate = (text or "").strip()
+    try:
+        return float(candidate)
+    except ValueError as exc:
+        raise ValidationError(f"{name} must be a number, received {candidate!r}") from exc
+
+
+def _read_connections(text: str) -> int:
+    return check_connections(_whole_number("connections", text))
+
+
+def _read_delay(text: str) -> float:
+    return check_delay(_decimal_number("delay", text))
+
+
+def _read_chunk_kib(text: str) -> int:
+    return check_chunk_kib(_whole_number("chunk size in KiB", text))
+
+
+def _read_limit_rate(text: str) -> int | None:
+    """``RATE_OFF`` means no ceiling. Every other value goes through the validator."""
+    value = _whole_number("rate limit in KB/s", text)
+    if value == RATE_OFF:
+        return None
+    return check_limit_rate(value)
+
+
+@dataclass
+class _BoundedField:
+    """One spinbox, its reader and the last value that reader accepted.
+
+    A value the reader refuses is reverted to ``last_good`` on focus-out, so the
+    window never holds an option the engine would reject and the operator sees
+    the validator's own message rather than a failure at Start.
+    """
+
+    name: str
+    var: tk.StringVar
+    read: Callable[[str], Any]
+    last_good: str
+
+    def value(self) -> Any:
+        return self.read(self.var.get())
+
+
+def _format_bytes(count: int) -> str:
+    """Render a byte count in binary units, to one decimal above bytes."""
+    size = float(max(0, count))
+    for unit in BYTE_UNITS:
+        if size < BYTES_PER_UNIT or unit == BYTE_UNITS[-1]:
+            return f"{int(size)} {unit}" if unit == BYTE_UNITS[0] else f"{size:.1f} {unit}"
+        size /= BYTES_PER_UNIT
+    return f"{size:.1f} {BYTE_UNITS[-1]}"
+
+
+def _describe_source(reference: SitePathRef | ShareRef) -> str:
+    """One line describing what the pasted URL addresses, without a network call.
+
+    A site path carries its host and its path segments. Which leading segments
+    name the site and which segment names the library is decided by the probe in
+    :mod:`sharefetch.resolve`, which needs a signed-in Graph call, so the line
+    states the path as given and the ``Resolved`` event replaces it with the
+    authoritative site, library and folder once the run resolves.
+    """
+    if isinstance(reference, ShareRef):
+        return (
+            f"host {reference.host}, sharing link; site, library and folder resolve after sign-in"
+        )
+    path = "/".join(reference.path_segments)
+    folder = reference.path_segments[-1]
+    return (
+        f"host {reference.host}, path /{path}, folder {folder}; "
+        f"site and library confirmed on resolve"
+    )
+
+
+def _default_folder_name(reference: SitePathRef | ShareRef) -> str | None:
+    """The destination folder name the URL implies, or ``None`` where it implies none."""
+    if isinstance(reference, ShareRef):
+        return None
+    name, _changed = sanitise_segment(reference.path_segments[-1])
+    return name or None
+
+
+# ----------------------------------------------------------------------
+# The window
+# ----------------------------------------------------------------------
+
+
+class App:
+    """The single window the front end presents.
+
+    Every method on this class runs on the Tk main thread except
+    :meth:`_run_engine` and :meth:`_publish`, which run on the worker thread and
+    touch no widget. That split is the whole of the threading contract.
+    """
+
+    def __init__(self, root: tk.Tk) -> None:
+        self._root = root
+        self._events: queue.Queue[Any] = queue.Queue()
+
+        # Handed over by the worker thread through _publish, read under the
+        # lock by the Cancel, Stop and close handlers.
+        self._control = threading.Lock()
+        self._provider: TokenProvider | None = None
+        self._engine: Engine | None = None
+        self._cancel_pending = False
+        self._stop_pending = False
+        self._worker: threading.Thread | None = None
+
+        self._drain_job: str | None = None
+        self._closing = False
+        self._log_handler: _QueueLogHandler | None = None
+        self._package_logger = logging.getLogger(PACKAGE_LOGGER_NAME)
+        self._previous_propagate = self._package_logger.propagate
+        self._previous_level = self._package_logger.level
+
+        # Run tallies, reset by _reset_run_display.
+        self._total_bytes = 0
+        self._overall_bytes = 0
+        self._inflight: dict[str, int] = {}
+        self._current: str | None = None
+        self._transferred = 0
+        self._skipped = 0
+        self._failed = 0
+        self._exit_code = EXIT_OK
+
+        self._build()
+        self._set_state(_STATE_IDLE)
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def _build(self) -> None:
+        root = self._root
+        root.title("sharefetch")
+        root.minsize(760, 620)
+        root.columnconfigure(0, weight=1)
+        root.rowconfigure(5, weight=1)
+
+        self._build_source(root)
+        self._build_options(root)
+        self._build_device_panel(root)
+        self._build_progress(root)
+        self._build_controls(root)
+        self._build_log(root)
+
+    def _build_source(self, root: tk.Tk) -> None:
+        frame = ttk.LabelFrame(root, text="Source", padding=8)
+        frame.grid(row=0, column=0, sticky="ew", padx=8, pady=(8, 4))
+        frame.columnconfigure(1, weight=1)
+
+        ttk.Label(frame, text="URL").grid(row=0, column=0, sticky="w", padx=(0, 6))
+        self._url_var = tk.StringVar()
+        self._url_entry = ttk.Entry(frame, textvariable=self._url_var)
+        self._url_entry.grid(row=0, column=1, columnspan=2, sticky="ew")
+        self._url_entry.bind("<FocusOut>", self._on_url_focus_out)
+        self._url_entry.bind("<Return>", self._on_url_focus_out)
+
+        self._source_var = tk.StringVar(value="paste a URL, then leave the field")
+        ttk.Label(frame, textvariable=self._source_var, wraplength=700).grid(
+            row=1, column=0, columnspan=3, sticky="w", pady=(4, 0)
+        )
+        self._url_error_var = tk.StringVar()
+        ttk.Label(
+            frame,
+            textvariable=self._url_error_var,
+            wraplength=700,
+            foreground=_ERROR_COLOUR,
+        ).grid(row=2, column=0, columnspan=3, sticky="w", pady=(2, 0))
+
+        ttk.Label(frame, text="Destination").grid(
+            row=3, column=0, sticky="w", padx=(0, 6), pady=(6, 0)
+        )
+        self._dest_var = tk.StringVar()
+        self._dest_auto = ""
+        ttk.Entry(frame, textvariable=self._dest_var).grid(
+            row=3, column=1, sticky="ew", pady=(6, 0)
+        )
+        ttk.Button(frame, text="Browse", command=self._on_browse).grid(
+            row=3, column=2, sticky="e", padx=(6, 0), pady=(6, 0)
+        )
+
+    def _build_options(self, root: tk.Tk) -> None:
+        frame = ttk.LabelFrame(root, text="Transfer options", padding=8)
+        frame.grid(row=1, column=0, sticky="ew", padx=8, pady=4)
+
+        self._fields: dict[str, _BoundedField] = {}
+        self._fields["connections"] = self._spinbox(
+            frame,
+            column=0,
+            label="Connections",
+            name="connections",
+            initial=str(DEFAULT_CONNECTIONS),
+            low=CONNECTIONS_BOUNDS[0],
+            high=CONNECTIONS_BOUNDS[1],
+            increment=1,
+            read=_read_connections,
+        )
+        self._fields["delay"] = self._spinbox(
+            frame,
+            column=1,
+            label="Delay (s)",
+            name="delay",
+            initial=str(DEFAULT_DELAY_SECONDS),
+            low=DELAY_BOUNDS[0],
+            high=DELAY_BOUNDS[1],
+            increment=DELAY_SPIN_INCREMENT,
+            read=_read_delay,
+        )
+        self._fields["limit_rate"] = self._spinbox(
+            frame,
+            column=2,
+            label=f"Rate (KB/s, {RATE_OFF} is off)",
+            name="rate limit",
+            initial=str(RATE_OFF),
+            low=RATE_OFF,
+            high=RATE_SPINBOX_CEILING_KBPS,
+            increment=RATE_SPIN_INCREMENT_KBPS,
+            read=_read_limit_rate,
+        )
+        self._fields["chunk"] = self._spinbox(
+            frame,
+            column=3,
+            label="Chunk (KiB)",
+            name="chunk size",
+            initial=str(DEFAULT_CHUNK_KIB),
+            low=CHUNK_KIB_BOUNDS[0],
+            high=CHUNK_KIB_BOUNDS[1],
+            increment=CHUNK_SPIN_INCREMENT_KIB,
+            read=_read_chunk_kib,
+        )
+
+        self._options_error_var = tk.StringVar()
+        ttk.Label(
+            frame,
+            textvariable=self._options_error_var,
+            wraplength=700,
+            foreground=_ERROR_COLOUR,
+        ).grid(row=2, column=0, columnspan=4, sticky="w", pady=(4, 0))
+
+    def _spinbox(
+        self,
+        parent: ttk.LabelFrame,
+        *,
+        column: int,
+        label: str,
+        name: str,
+        initial: str,
+        low: float,
+        high: float,
+        increment: float,
+        read: Callable[[str], Any],
+    ) -> _BoundedField:
+        """Build one bounded spinbox and the field object that guards it.
+
+        ``low`` and ``high`` come from the ``config`` bounds pairs the
+        command-line front end enforces, so the arrows stop where the validator
+        stops. ``read`` is the validator itself, applied to typed input.
+        """
+        ttk.Label(parent, text=label).grid(row=0, column=column, sticky="w", padx=(0, 12))
+        var = tk.StringVar(value=initial)
+        spin = ttk.Spinbox(
+            parent,
+            textvariable=var,
+            from_=low,
+            to=high,
+            increment=increment,
+            width=12,
+        )
+        spin.grid(row=1, column=column, sticky="w", padx=(0, 12))
+        field = _BoundedField(name=name, var=var, read=read, last_good=initial)
+        spin.bind("<FocusOut>", lambda _event, f=field: self._on_field_focus_out(f))
+        return field
+
+    def _build_device_panel(self, root: tk.Tk) -> None:
+        self._device_panel = ttk.LabelFrame(root, text="Sign in", padding=8)
+        self._device_panel.grid(row=2, column=0, sticky="ew", padx=8, pady=4)
+        self._device_panel.columnconfigure(0, weight=1)
+
+        ttk.Label(
+            self._device_panel,
+            text="Open the verification page and enter this code:",
+        ).grid(row=0, column=0, columnspan=3, sticky="w")
+
+        code_font = tkfont.nametofont("TkFixedFont").copy()
+        code_font.configure(size=DEVICE_CODE_FONT_SIZE)
+        self._code_var = tk.StringVar()
+        # A read-only Entry rather than a Label, because the code has to be
+        # selectable and is shown preselected.
+        self._code_entry = tk.Entry(
+            self._device_panel,
+            textvariable=self._code_var,
+            font=code_font,
+            state="readonly",
+            justify="center",
+            width=14,
+            relief="flat",
+        )
+        self._code_entry.grid(row=1, column=0, sticky="w", pady=(4, 4))
+        ttk.Button(self._device_panel, text="Copy", command=self._on_copy_code).grid(
+            row=1, column=1, sticky="w", padx=(8, 0)
+        )
+        ttk.Button(self._device_panel, text="Cancel", command=self._on_cancel_sign_in).grid(
+            row=1, column=2, sticky="w", padx=(8, 0)
+        )
+
+        link_font = tkfont.nametofont("TkDefaultFont").copy()
+        link_font.configure(underline=True)
+        self._uri_var = tk.StringVar()
+        self._uri_label = ttk.Label(
+            self._device_panel,
+            textvariable=self._uri_var,
+            foreground=_LINK_COLOUR,
+            cursor="hand2",
+            font=link_font,
+        )
+        self._uri_label.grid(row=2, column=0, columnspan=3, sticky="w")
+        self._uri_label.bind("<Button-1>", self._on_open_verification_uri)
+
+        self._expiry_var = tk.StringVar()
+        ttk.Label(self._device_panel, textvariable=self._expiry_var).grid(
+            row=3, column=0, columnspan=3, sticky="w", pady=(2, 0)
+        )
+        self._device_panel.grid_remove()
+
+    def _build_progress(self, root: tk.Tk) -> None:
+        frame = ttk.LabelFrame(root, text="Progress", padding=8)
+        frame.grid(row=3, column=0, sticky="ew", padx=8, pady=4)
+        frame.columnconfigure(0, weight=1)
+
+        self._overall_bar = ttk.Progressbar(frame, maximum=PROGRESS_SCALE, value=0)
+        self._overall_bar.grid(row=0, column=0, sticky="ew")
+        self._overall_var = tk.StringVar(value="overall: nothing enumerated yet")
+        ttk.Label(frame, textvariable=self._overall_var).grid(row=1, column=0, sticky="w")
+
+        self._file_bar = ttk.Progressbar(frame, maximum=PROGRESS_SCALE, value=0)
+        self._file_bar.grid(row=2, column=0, sticky="ew", pady=(6, 0))
+        self._file_var = tk.StringVar(value="current file: none")
+        ttk.Label(frame, textvariable=self._file_var, wraplength=700).grid(
+            row=3, column=0, sticky="w"
+        )
+
+        self._counts_var = tk.StringVar()
+        ttk.Label(frame, textvariable=self._counts_var).grid(
+            row=4, column=0, sticky="w", pady=(4, 0)
+        )
+        self._status_var = tk.StringVar(value="idle")
+        ttk.Label(frame, textvariable=self._status_var, wraplength=700).grid(
+            row=5, column=0, sticky="w"
+        )
+        self._summary_var = tk.StringVar()
+        ttk.Label(frame, textvariable=self._summary_var, wraplength=700).grid(
+            row=6, column=0, sticky="w", pady=(2, 0)
+        )
+        self._refresh_counts()
+
+    def _build_controls(self, root: tk.Tk) -> None:
+        frame = ttk.Frame(root, padding=(8, 0))
+        frame.grid(row=4, column=0, sticky="ew")
+        self._start_button = ttk.Button(frame, text="Start", command=self._on_start)
+        self._start_button.grid(row=0, column=0, padx=(0, 6))
+        self._pause_button = ttk.Button(frame, text="Pause", command=self._on_pause)
+        self._pause_button.grid(row=0, column=1, padx=6)
+        self._resume_button = ttk.Button(frame, text="Resume", command=self._on_resume)
+        self._resume_button.grid(row=0, column=2, padx=6)
+        self._stop_button = ttk.Button(frame, text="Stop", command=self._on_stop)
+        self._stop_button.grid(row=0, column=3, padx=6)
+
+    def _build_log(self, root: tk.Tk) -> None:
+        frame = ttk.LabelFrame(root, text="Log", padding=8)
+        frame.grid(row=5, column=0, sticky="nsew", padx=8, pady=(4, 8))
+        frame.columnconfigure(0, weight=1)
+        frame.rowconfigure(0, weight=1)
+
+        self._log = tk.Text(frame, height=14, wrap="none", state="disabled")
+        self._log.grid(row=0, column=0, sticky="nsew")
+        scroll = ttk.Scrollbar(frame, orient="vertical", command=self._log.yview)
+        scroll.grid(row=0, column=1, sticky="ns")
+        self._log.configure(yscrollcommand=scroll.set)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Arm the window: install the log handler, the close protocol and the drain.
+
+        Separate from the Start button, which begins a run. This prepares the
+        window to receive one.
+        """
+        self._log_handler = _QueueLogHandler(self._events)
+        self._package_logger.addHandler(self._log_handler)
+        self._package_logger.setLevel(logging.INFO)
+        # The package logger's records terminate at the pane. Without this a
+        # record reaching a root logger with no handler falls through to
+        # logging.lastResort, which writes to a stderr a windowed process may
+        # not have.
+        self._package_logger.propagate = False
+        self._root.protocol("WM_DELETE_WINDOW", self._on_close)
+        self._schedule_drain()
+        logger.info("the sharefetch window is ready")
+
+    @property
+    def exit_code(self) -> int:
+        """The exit code the last run earned."""
+        return self._exit_code
+
+    def _schedule_drain(self) -> None:
+        if self._closing:
+            return
+        self._drain_job = self._root.after(GUI_DRAIN_INTERVAL_MS, self._drain)
+
+    def _drain(self) -> None:
+        """Consume queued events on the main thread. The only place Tk is touched."""
+        try:
+            for _ in range(DRAIN_BATCH_LIMIT):
+                item = self._events.get_nowait()
+                self._handle(item)
+        except queue.Empty:
+            pass
+        finally:
+            self._schedule_drain()
+
+    def _handle(self, item: Any) -> None:
+        """Dispatch one queued item, absorbing any failure so the drain survives it."""
+        try:
+            self._dispatch(item)
+        except Exception:
+            logger.exception("the window could not handle a %s event", type(item).__name__)
+
+    def _dispatch(self, item: Any) -> None:
+        if isinstance(item, LogRecord):
+            self._append_log(item.message)
+        elif isinstance(item, FileProgress):
+            self._on_file_progress(item)
+        elif isinstance(item, FileStarted):
+            self._on_file_started(item)
+        elif isinstance(item, FileFinished):
+            self._on_file_finished(item)
+        elif isinstance(item, Resolved):
+            self._source_var.set(
+                f"site {item.site_web_url}, library {item.drive_name}, "
+                f"folder {item.folder_path or '/'}"
+            )
+        elif isinstance(item, DeviceCodeRequested):
+            self._show_device_code(item)
+        elif isinstance(item, DeviceCodeCompleted):
+            self._hide_device_panel()
+            # The account identifier the event carries is not displayed, so no
+            # user principal name reaches the window or the log.
+            self._status_var.set("signed in")
+        elif isinstance(item, EnumerationProgress):
+            self._status_var.set(
+                f"enumerating: {item.folders} folder(s), {item.files} file(s), "
+                f"{_format_bytes(item.total_bytes)}"
+            )
+        elif isinstance(item, EnumerationComplete):
+            self._total_bytes = item.total_bytes
+            self._status_var.set(
+                f"enumeration complete: {item.files} file(s) in {item.folders} folder(s), "
+                f"{_format_bytes(item.total_bytes)}"
+            )
+            self._refresh_overall()
+        elif isinstance(item, Reconciled):
+            counts = ", ".join(f"{name} {value}" for name, value in sorted(item.counts.items()))
+            self._status_var.set(f"reconciled: {counts or 'nothing'}")
+        elif isinstance(item, Throttled):
+            self._status_var.set(f"throttled for {item.seconds:.1f} s ({item.reason})")
+        elif isinstance(item, RunFinished):
+            self._on_run_finished(item)
+        elif isinstance(item, _RunFailed):
+            self._exit_code = EXIT_FATAL
+            self._summary_var.set(f"the run ended with an error: {item.message}")
+        elif isinstance(item, _RunEnded):
+            self._on_run_ended()
+        else:
+            logger.warning("an unrecognised item of type %s was queued", type(item).__name__)
+
+    # ------------------------------------------------------------------
+    # Event handling
+    # ------------------------------------------------------------------
+
+    def _show_device_code(self, event: DeviceCodeRequested) -> None:
+        """Reveal the panel and preselect the code. Neither the code nor the URI is logged."""
+        self._code_var.set(event.user_code)
+        self._uri_var.set(event.verification_uri)
+        if event.expires_at > 0:
+            self._expiry_var.set(
+                "the code expires at " + time.strftime("%H:%M:%S", time.localtime(event.expires_at))
+            )
+        else:
+            self._expiry_var.set("")
+        self._device_panel.grid()
+        self._code_entry.selection_range(0, tk.END)
+        self._code_entry.focus_set()
+        self._status_var.set("waiting for the sign-in to complete")
+        logger.info("a device code was issued and the sign-in panel is showing it")
+
+    def _hide_device_panel(self) -> None:
+        self._device_panel.grid_remove()
+        self._code_var.set("")
+        self._uri_var.set("")
+        self._expiry_var.set("")
+
+    def _on_file_started(self, event: FileStarted) -> None:
+        # Bytes already in the .part file count towards the tree, because the
+        # run does not fetch them again.
+        self._overall_bytes += max(0, event.resume_from)
+        self._inflight[event.drive_path] = max(0, event.resume_from)
+        self._current = event.drive_path
+        self._refresh_file(event.drive_path, event.resume_from, event.size)
+        self._refresh_overall()
+
+    def _on_file_progress(self, event: FileProgress) -> None:
+        previous = self._inflight.get(event.drive_path, 0)
+        if event.bytes_written > previous:
+            self._overall_bytes += event.bytes_written - previous
+            self._inflight[event.drive_path] = event.bytes_written
+        if self._current is None:
+            self._current = event.drive_path
+        if event.drive_path == self._current:
+            self._refresh_file(event.drive_path, event.bytes_written, event.size)
+        self._refresh_overall()
+
+    def _on_file_finished(self, event: FileFinished) -> None:
+        self._inflight.pop(event.drive_path, None)
+        if event.status == STATUS_COMPLETE:
+            self._transferred += 1
+        elif event.status == STATUS_SKIPPED:
+            self._skipped += 1
+        elif event.status == STATUS_FAILED:
+            self._failed += 1
+        if self._current == event.drive_path:
+            self._current = next(iter(self._inflight), None)
+            if self._current is None:
+                self._file_bar.configure(value=0)
+                self._file_var.set("current file: none")
+        self._refresh_counts()
+        note = self._verification_note(event.verification)
+        if event.error:
+            self._status_var.set(f"{event.drive_path}: {event.status}, {event.error}")
+        elif note:
+            self._status_var.set(f"{event.drive_path}: {event.status}, verification {note}")
+
+    def _verification_note(self, verification: Any) -> str:
+        """Summarise a verification result read duck-typed.
+
+        ``FileFinished.verification`` is annotated ``Any`` because
+        :mod:`sharefetch.events` depends on no other module, so the attributes
+        are read rather than the type imported.
+        """
+        if verification is None:
+            return ""
+        status = getattr(verification, "status", None)
+        if not isinstance(status, str):
+            return ""
+        reason = getattr(verification, "reason", None)
+        warnings = getattr(verification, "warnings", ()) or ()
+        note = status
+        if reason:
+            note = f"{note} ({reason})"
+        if warnings:
+            note = f"{note}, warnings: {', '.join(str(item) for item in warnings)}"
+        return note
+
+    def _on_run_finished(self, event: RunFinished) -> None:
+        summary = event.summary
+        self._exit_code = EXIT_FAILURES if (summary.failed or summary.skipped) else EXIT_OK
+        manifest = str(event.manifest_path) if event.manifest_path else "not written"
+        self._summary_var.set(
+            f"transferred {summary.transferred}, skipped {summary.skipped}, "
+            f"failed {summary.failed}, already present {summary.already_present}, "
+            f"verified {summary.verified}, {_format_bytes(summary.bytes_transferred)} moved; "
+            f"manifest: {manifest}"
+        )
+        self._status_var.set("run finished")
+
+    def _on_run_ended(self) -> None:
+        """The worker thread has exited. Release the run's objects and re-arm Start."""
+        with self._control:
+            self._provider = None
+            self._engine = None
+            self._cancel_pending = False
+            self._stop_pending = False
+        self._hide_device_panel()
+        self._current = None
+        self._inflight.clear()
+        self._file_bar.configure(value=0)
+        self._file_var.set("current file: none")
+        self._set_state(_STATE_IDLE)
+
+    # ------------------------------------------------------------------
+    # Display helpers
+    # ------------------------------------------------------------------
+
+    def _refresh_overall(self) -> None:
+        moved = self._overall_bytes
+        total = self._total_bytes
+        if total > 0:
+            fraction = min(1.0, moved / total)
+            self._overall_bar.configure(value=fraction * PROGRESS_SCALE)
+            self._overall_var.set(
+                f"overall: {_format_bytes(moved)} of {_format_bytes(total)} enumerated"
+            )
+        else:
+            self._overall_bar.configure(value=0)
+            self._overall_var.set(f"overall: {_format_bytes(moved)}")
+
+    def _refresh_file(self, drive_path: str, written: int, size: int) -> None:
+        if size > 0:
+            fraction = min(1.0, max(0, written) / size)
+            self._file_bar.configure(value=fraction * PROGRESS_SCALE)
+        else:
+            self._file_bar.configure(value=0)
+        self._file_var.set(
+            f"current file: {drive_path} ({_format_bytes(written)} of {_format_bytes(size)})"
+        )
+
+    def _refresh_counts(self) -> None:
+        self._counts_var.set(
+            f"transferred {self._transferred}, skipped {self._skipped}, failed {self._failed}"
+        )
+
+    def _append_log(self, message: str) -> None:
+        """Append one already-formatted, already-redacted record and trim the pane."""
+        self._log.configure(state="normal")
+        try:
+            self._log.insert("end", message + "\n")
+            lines = int(str(self._log.index("end-1c")).split(".")[0])
+            if lines > GUI_LOG_MAX_LINES:
+                self._log.delete("1.0", f"{lines - GUI_LOG_MAX_LINES + 1}.0")
+            self._log.see("end")
+        finally:
+            self._log.configure(state="disabled")
+
+    def _reset_run_display(self) -> None:
+        self._total_bytes = 0
+        self._overall_bytes = 0
+        self._inflight.clear()
+        self._current = None
+        self._transferred = 0
+        self._skipped = 0
+        self._failed = 0
+        self._exit_code = EXIT_OK
+        self._overall_bar.configure(value=0)
+        self._file_bar.configure(value=0)
+        self._overall_var.set("overall: nothing enumerated yet")
+        self._file_var.set("current file: none")
+        self._summary_var.set("")
+        self._status_var.set("starting")
+        self._refresh_counts()
+        while True:
+            try:
+                self._events.get_nowait()
+            except queue.Empty:
+                break
+
+    def _set_state(self, state: str) -> None:
+        running = state == _STATE_RUNNING
+        paused = state == _STATE_PAUSED
+        idle = state == _STATE_IDLE
+        self._start_button.configure(state="normal" if idle else "disabled")
+        self._pause_button.configure(state="normal" if running else "disabled")
+        self._resume_button.configure(state="normal" if paused else "disabled")
+        self._stop_button.configure(state="normal" if (running or paused) else "disabled")
+        if idle:
+            self._status_var.set(self._status_var.get() or "idle")
+
+    # ------------------------------------------------------------------
+    # Widget callbacks, main thread
+    # ------------------------------------------------------------------
+
+    def _on_url_focus_out(self, _event: Any = None) -> None:
+        """Parse the pasted URL locally. No network call is made here."""
+        text = self._url_var.get().strip()
+        if not text:
+            self._source_var.set("paste a URL, then leave the field")
+            self._url_error_var.set("")
+            return
+        try:
+            reference = parse_url(text)
+        except ValidationError as exc:
+            self._source_var.set("")
+            self._url_error_var.set(str(exc))
+            self._start_button.configure(state="disabled")
+            logger.warning("the pasted URL was refused: %s", exc)
+            return
+        self._url_error_var.set("")
+        self._source_var.set(_describe_source(reference))
+        self._fill_default_destination(reference)
+        if self._worker is None or not self._worker.is_alive():
+            self._start_button.configure(state="normal")
+
+    def _fill_default_destination(self, reference: SitePathRef | ShareRef) -> None:
+        """Offer a destination named after the addressed folder, without overwriting."""
+        name = _default_folder_name(reference)
+        if name is None:
+            return
+        current = self._dest_var.get().strip()
+        if current and current != self._dest_auto:
+            return
+        proposed = str(Path.cwd() / name)
+        self._dest_var.set(proposed)
+        self._dest_auto = proposed
+
+    def _on_browse(self) -> None:
+        chosen = filedialog.askdirectory(title="Choose the destination directory")
+        if chosen:
+            self._dest_var.set(str(Path(chosen)))
+            self._dest_auto = ""
+
+    def _on_field_focus_out(self, field: _BoundedField) -> None:
+        """Refuse an out-of-range value: restore the last accepted one and say why."""
+        try:
+            field.value()
+        except ValidationError as exc:
+            self._options_error_var.set(str(exc))
+            field.var.set(field.last_good)
+            logger.warning("the %s value was refused: %s", field.name, exc)
+            return
+        field.last_good = field.var.get()
+        self._options_error_var.set("")
+
+    def _on_copy_code(self) -> None:
+        code = self._code_var.get()
+        if not code:
+            return
+        self._root.clipboard_clear()
+        self._root.clipboard_append(code)
+        self._status_var.set("the device code was copied to the clipboard")
+        logger.info("the device code was copied to the clipboard")
+
+    def _on_open_verification_uri(self, _event: Any = None) -> None:
+        uri = self._uri_var.get().strip()
+        if not uri:
+            return
+        opened = webbrowser.open(uri)
+        if opened:
+            self._status_var.set("the verification page was opened in the default browser")
+            logger.info("the verification page was opened in the default browser")
+        else:
+            self._status_var.set("no browser could be opened; enter the URL shown above by hand")
+            logger.warning("no browser could be opened for the verification page")
+
+    def _on_cancel_sign_in(self) -> None:
+        """Cancel the device flow. The provider owns the event."""
+        with self._control:
+            provider = self._provider
+            if provider is None:
+                # The click beat the worker thread to building the provider. The
+                # flag is applied in _publish, which pre-empts the request.
+                self._cancel_pending = True
+        if provider is not None:
+            provider.cancel()
+        self._hide_device_panel()
+        self._status_var.set("the sign-in was cancelled")
+
+    def _on_start(self) -> None:
+        if self._worker is not None and self._worker.is_alive():
+            logger.warning("a run is already in progress, the Start button was ignored")
+            return
+        try:
+            settings = self._collect_settings()
+        except ValidationError as exc:
+            self._options_error_var.set(str(exc))
+            logger.error("the run was refused before it started: %s", exc)
+            return
+        self._options_error_var.set("")
+        self._reset_run_display()
+        with self._control:
+            self._provider = None
+            self._engine = None
+            self._cancel_pending = False
+            self._stop_pending = False
+        self._worker = threading.Thread(
+            target=self._run_engine,
+            args=(settings,),
+            name="sharefetch-engine",
+            daemon=True,
+        )
+        self._set_state(_STATE_RUNNING)
+        self._worker.start()
+        logger.info("a run was started against %s", settings.dest)
+
+    def _collect_settings(self) -> Settings:
+        """Build the run's settings, refusing every value the validators refuse."""
+        url = self._url_var.get().strip()
+        parse_url(url)
+        dest = check_dest(self._dest_var.get())
+        return Settings(
+            url=url,
+            dest=dest,
+            connections=self._fields["connections"].value(),
+            delay=self._fields["delay"].value(),
+            limit_rate_kbps=self._fields["limit_rate"].value(),
+            chunk_kib=self._fields["chunk"].value(),
+        )
+
+    def _on_pause(self) -> None:
+        with self._control:
+            engine = self._engine
+        if engine is None:
+            logger.warning("there is no run to pause")
+            return
+        engine.pause()
+        self._set_state(_STATE_PAUSED)
+        self._status_var.set("pausing at the next chunk boundary")
+
+    def _on_resume(self) -> None:
+        with self._control:
+            engine = self._engine
+        if engine is None:
+            logger.warning("there is no run to resume")
+            return
+        engine.resume()
+        self._set_state(_STATE_RUNNING)
+        self._status_var.set("resuming")
+
+    def _on_stop(self) -> None:
+        self._request_stop()
+        self._set_state(_STATE_STOPPING)
+        self._status_var.set("stopping after the file in flight")
+
+    def _request_stop(self) -> None:
+        """End the run: stop the engine and abandon any sign-in still pending.
+
+        The sign-in is cancelled as well as the engine stopped, because a run
+        waiting at the device prompt is blocked inside msal's polling loop and
+        ``Engine.stop`` alone would not reach it. The provider is discarded with
+        the run, so cancelling it never affects a later one.
+        """
+        with self._control:
+            engine = self._engine
+            provider = self._provider
+            if engine is None:
+                self._stop_pending = True
+            if provider is None:
+                self._cancel_pending = True
+        if engine is not None:
+            engine.stop()
+        if provider is not None:
+            provider.cancel()
+
+    def _on_close(self) -> None:
+        """Stop the run, wait for the engine to flush its state, then destroy the window.
+
+        The join is what guarantees the state file on disk describes the run
+        that just ended: ``Engine.run`` flushes the store before it returns, so
+        a joined thread has written it. Where the join times out, the state on
+        disk is still valid, because the store flushes on its own interval and
+        the ``.part`` sizes are authoritative.
+        """
+        worker = self._worker
+        if worker is not None and worker.is_alive():
+            self._set_state(_STATE_STOPPING)
+            self._status_var.set(
+                f"stopping and writing the state file, up to {GUI_STOP_JOIN_SECONDS:.0f} s"
+            )
+            self._root.update_idletasks()
+            self._request_stop()
+            worker.join(GUI_STOP_JOIN_SECONDS)
+            if worker.is_alive():
+                logger.warning(
+                    "the engine thread did not end within %.0f s; the state file holds the last "
+                    "flush and the .part sizes remain authoritative",
+                    GUI_STOP_JOIN_SECONDS,
+                )
+            else:
+                logger.info("the engine thread ended and its state file is written")
+        self._teardown()
+        self._root.destroy()
+
+    def _teardown(self) -> None:
+        """Cancel the drain and detach the log handler, leaving logging as it was."""
+        self._closing = True
+        if self._drain_job is not None:
+            self._root.after_cancel(self._drain_job)
+            self._drain_job = None
+        if self._log_handler is not None:
+            self._package_logger.removeHandler(self._log_handler)
+            self._log_handler.close()
+            self._log_handler = None
+        self._package_logger.propagate = self._previous_propagate
+        self._package_logger.setLevel(self._previous_level)
+
+    # ------------------------------------------------------------------
+    # Worker thread. Nothing below this line touches a widget.
+    # ------------------------------------------------------------------
+
+    def _run_engine(self, settings: Settings) -> None:
+        """Run the engine. Executes on the worker thread and makes no Tk call.
+
+        Every outcome reaches the window as a queued item: the engine's own
+        events, a ``_RunFailed`` for a fatal error, and a ``_RunEnded`` that
+        always arrives last.
+        """
+        sink = _QueueSink(self._events)
+        try:
+            provider = TokenProvider(
+                settings.client_id,
+                settings.tenant,
+                sink,
+                reauth=settings.reauth,
+            )
+            engine = Engine(settings, sink, tokens=provider)
+            self._publish(provider, engine)
+            engine.run()
+        except SharefetchError as exc:
+            logger.error("the run ended with %s: %s", type(exc).__name__, exc)
+            self._events.put(_RunFailed(message=f"{type(exc).__name__}: {exc}"))
+        except Exception as exc:
+            logger.exception("the run ended with an unexpected error")
+            self._events.put(_RunFailed(message=f"{type(exc).__name__}: {exc}"))
+        finally:
+            self._events.put(_RunEnded())
+
+    def _publish(self, provider: TokenProvider, engine: Engine) -> None:
+        """Hand the main thread this run's provider and engine. Touches no widget.
+
+        A Cancel or a Stop that arrived before the objects existed is applied
+        here, under the same lock that published them, so neither is lost to the
+        race between the click and the thread starting.
+        """
+        with self._control:
+            self._provider = provider
+            self._engine = engine
+            cancel = self._cancel_pending
+            stop = self._stop_pending
+        if cancel:
+            provider.cancel()
+        if stop:
+            engine.stop()
+
+
+def main() -> int:
+    """Open the window and run it to completion.
+
+    Returns 0 where the last run completed cleanly, 1 where it finished with
+    failed or skipped items, and 2 where no display is available, matching the
+    command-line exit codes.
+    """
+    try:
+        root = tk.Tk()
+    except tk.TclError as exc:
+        logger.error("the graphical interface needs a display: %s", exc)
+        return EXIT_FATAL
+    app = App(root)
+    app.start()
+    root.mainloop()
+    return app.exit_code