cfbtui 1.13.1__tar.gz

cfbtui-1.13.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bill Kane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfbtui-1.13.1/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: cfbtui
+Version: 1.13.1
+Summary: College football scoreboard for your terminal. Live scores, rankings and scoring plays.
+Author: Bill Kane
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/WPTK/cfbtui
+Project-URL: Issues, https://github.com/WPTK/cfbtui/issues
+Project-URL: Changelog, https://github.com/WPTK/cfbtui/blob/main/CHANGELOG.md
+Keywords: college football,scoreboard,tui,terminal,textual,espn
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual<9,>=8.2
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: tomli-w<2,>=1
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pyinstaller<7,>=6.22; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Provides-Extra: binary
+Requires-Dist: tzdata>=2024.1; extra == "binary"
+Dynamic: license-file
+
+# cfbtui
+
+[![Latest release](https://img.shields.io/github/v/release/WPTK/cfbtui)](https://github.com/WPTK/cfbtui/releases/latest)
+
+cfbtui is a terminal scoreboard for FBS and FCS college football. It reads ESPN's unofficial public JSON endpoints (no API key) and renders live scores, rankings, scoring plays and news in a [Textual](https://textual.textualize.io/) interface.
+
+![The scoreboard](docs/img/grid.png)
+
+- Games for the week, live ones first. Scores refresh every 20 seconds while you are at the computer and every 2 minutes once you step away.
+- Live cards show the clock, down and distance, and who has the ball, and flash on a score.
+- A card gets a yellow border and an UPSET label when a ranked team is losing, or lost, to a worse-ranked or unranked team.
+- Game detail has every scoring play and win probability. AP and Coaches polls switch to the CFP ranking once the committee releases it.
+- ESPN's college football news opens in the app.
+- You can star favorites, filter, pick a conference, switch between cards and a list, and open any week including Bowls and the Playoff.
+- You can copy a game, or the whole board, for pasting into Discord.
+
+## Prerequisites
+
+- A terminal with color and Unicode: Windows Terminal, iTerm2, Terminal.app or a current Linux terminal. The old Windows Command Prompt window does not qualify.
+- To run the standalone binary: Windows, macOS (Apple silicon or Intel), Linux x86_64 or Linux arm64 with glibc 2.31 or newer (Ubuntu 20.04, Debian 11, Fedora 32, RHEL 9).
+- To run from source or the wheel: Python 3.13 or newer.
+- For Discord copy on Linux: `xclip` (X11) or `wl-clipboard` (Wayland).
+- For the default icon style: a [Nerd Font](https://www.nerdfonts.com/) set as the terminal font. Without one, start with `--glyphs unicode`.
+
+## Quickstart
+
+Standalone binary:
+
+1. Download the file for your system from the [latest release](https://github.com/WPTK/cfbtui/releases/latest): `cfbtui-windows-x86_64.exe`, `cfbtui-macos-arm64`, `cfbtui-macos-x86_64`, `cfbtui-linux-x86_64` or `cfbtui-linux-arm64`.
+2. On macOS and Linux, make it executable. On macOS, also remove the quarantine flag (the binary is not notarized):
+
+   ```sh
+   chmod +x cfbtui-macos-arm64
+   xattr -d com.apple.quarantine cfbtui-macos-arm64
+   ```
+
+3. Run it. On Windows the exe is not code-signed, so if SmartScreen warns, choose More info, then Run anyway.
+
+   ```sh
+   ./cfbtui-macos-arm64
+   ```
+
+   ```powershell
+   .\cfbtui-windows-x86_64.exe
+   ```
+
+From source:
+
+1. Clone the repository and create a virtual environment:
+
+   ```sh
+   git clone https://github.com/WPTK/cfbtui.git
+   cd cfbtui
+   python3 -m venv .venv
+   ```
+
+2. Install the package. On Windows use `.venv\Scripts\python`; on macOS and Linux use `.venv/bin/python`:
+
+   ```sh
+   .venv/bin/python -m pip install -e .
+   ```
+
+3. Run it:
+
+   ```sh
+   .venv/bin/python -m cfbtui
+   ```
+
+Expected result: the current week's games appear as cards within a few seconds. Press `?` for every key and `q` to quit. If you see "Could not reach ESPN", check your connection; cfbtui keeps retrying.
+
+To verify a download, see [docs/verify.md](docs/verify.md).
+
+## Configuration
+
+Settings come from three layers. Command-line flags override the settings file for that run only. The settings file overrides the defaults. A bad value is ignored with a warning.
+
+### Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--week N` | current week | Start on week 1-15, or `bowls` or `playoff`. |
+| `--group fbs\|fcs` | `fbs` | Start on the FBS or FCS board. |
+| `--glyphs NAME` | `nerd` | Icon style: `ascii`, `unicode`, `emoji` or `nerd`. |
+| `--layout grid\|list` | `grid` | Cards, or one line per game. |
+| `--config PATH` | platform default | Read and save this settings file. |
+| `--no-config` | off | Ignore the settings file and never write it. |
+| `--no-update-check` | off | Skip the release check and the download. |
+| `--version` | | Print the version and exit. |
+
+### Settings file
+
+cfbtui creates the file the first time you star a team or change a setting. Edit it in any text editor.
+
+| System | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\cfbtui\config.toml` |
+| macOS | `~/Library/Application Support/cfbtui/config.toml` |
+| Linux | `~/.config/cfbtui/config.toml`, or under `$XDG_CONFIG_HOME` |
+
+| Key | Default | Description |
+|---|---|---|
+| `[poll] live` | `20` | Seconds between updates while you are at the computer. |
+| `[poll] idle` | `120` | Seconds between updates once you have walked away. |
+| `[poll] away_after` | `300` | Seconds without keyboard or mouse input before you count as away. |
+| `[poll] backoff_max` | `120` | Longest wait in seconds between retries after failed requests. |
+| `[view] glyph_set` | `"nerd"` | `ascii`, `unicode`, `emoji` or `nerd`. |
+| `[view] layout` | `"grid"` | `grid` or `list`. |
+| `[view] week` | current week | 1-15, 16 for Bowls, 17 for the Playoff. |
+| `[view] group` | `"fbs"` | `fbs` or `fcs`. |
+| `[favorites] team_ids` | `[]` | ESPN team ids, such as `["251"]`. The `1` and `2` keys fill this in. |
+| `[favorites] abbreviations` | `[]` | Teams by abbreviation, such as `["TEX"]`. |
+| `[alerts] enabled` | `true` | Pulse a card on Red Zone, Upset Watch, Overtime or Final. |
+| `[updates] check` | `true` | Look for a newer release at startup. |
+| `[updates] auto` | `true` | Download new minor and patch versions (standalone binaries only). |
+
+Update behavior is in [docs/updating.md](docs/updating.md).
+
+## Usage and controls
+
+Arrow keys move between cards, `Enter` opens one and `?` lists every key.
+
+![Game detail](docs/img/detail.png)
+
+| Key | Action |
+|---|---|
+| arrow keys | Move between games. |
+| `Enter` | Open the game: every scoring play and win probability. |
+| `R` | Rankings. Press `c` there to copy the polls for Discord, one poll per press. |
+| `N` | News. `Enter` reads a story, `o` opens the original in your browser, `r` refreshes. |
+| `[` `]` | Previous or next week. After week 15 come Bowls and the Playoff. |
+| `t` | Back to this week. |
+| `f` | Switch between FBS and FCS. |
+| `l` | Filter: all games, Top 25, live only, favorites. |
+| `o` | Pick a conference. |
+| `v` | Switch between cards and a list. |
+| `S` | Settings. Changes save as you make them. |
+| `1` `2` | Star the away or home team. Starred games move to a Favorites section at the top. |
+| `c` | Copy the selected game for Discord, with the winner in bold. |
+| `C` | Copy the board as a code block. Discord caps messages at 2,000 characters, so a big Saturday copies one part per press. |
+| `r` | Refresh now. |
+| `g` | Cycle the icon style. |
+| `Tab`, then `Up` or `Down` | Move through the ticker. `Enter` or a click shows that game. |
+| `Esc` | Close a screen. |
+| `q` | Quit. |
+
+Once the College Football Playoff committee releases its first ranking, `R` shows only the CFP ranking for the rest of the season. The FCS board shows the FCS Coaches poll.
+
+![Rankings](docs/img/rankings.png)
+
+## Troubleshooting
+
+- Icons show as empty boxes: set a Nerd Font as the terminal font, or press `g` to cycle to another icon style.
+- "Could not reach ESPN": check your connection. If the rest of the internet works, ESPN's service may be down. cfbtui retries with growing waits.
+- No games listed: the week may have no games, or a filter or conference is hiding them. Press `l` until the bottom bar says all games, then `t`.
+- `c` reports no clipboard on Linux: install `xclip` or `wl-clipboard`.
+
+## Data and privacy
+
+Scores and news come from ESPN's public, unofficial and undocumented endpoints, which can change or disappear without notice. cfbtui is an independent project and has no affiliation with ESPN or the NCAA.
+
+The news list refreshes every 10 minutes while you are at the computer and stops once you step away (on Windows; on other systems cfbtui cannot detect this and assumes you are there). A story's text is fetched only when you open it, kept in memory for the last 20 stories and never written to disk. Stories show ESPN's name as the source, and `o` opens the original. ESPN's content falls under Disney's [terms of use](https://disneytermsofuse.com/english/), which grant a personal, noncommercial licence and restrict automated access and copying. Fetching a story only when you ask lowers that risk and does not remove it. This is not legal advice.
+
+At startup cfbtui requests the latest release from GitHub. The request reveals your IP address and nothing else. Turn it off with `--no-update-check` or `check = false`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

cfbtui-1.13.1/README.md

@@ -0,0 +1,167 @@
+# cfbtui
+
+[![Latest release](https://img.shields.io/github/v/release/WPTK/cfbtui)](https://github.com/WPTK/cfbtui/releases/latest)
+
+cfbtui is a terminal scoreboard for FBS and FCS college football. It reads ESPN's unofficial public JSON endpoints (no API key) and renders live scores, rankings, scoring plays and news in a [Textual](https://textual.textualize.io/) interface.
+
+![The scoreboard](docs/img/grid.png)
+
+- Games for the week, live ones first. Scores refresh every 20 seconds while you are at the computer and every 2 minutes once you step away.
+- Live cards show the clock, down and distance, and who has the ball, and flash on a score.
+- A card gets a yellow border and an UPSET label when a ranked team is losing, or lost, to a worse-ranked or unranked team.
+- Game detail has every scoring play and win probability. AP and Coaches polls switch to the CFP ranking once the committee releases it.
+- ESPN's college football news opens in the app.
+- You can star favorites, filter, pick a conference, switch between cards and a list, and open any week including Bowls and the Playoff.
+- You can copy a game, or the whole board, for pasting into Discord.
+
+## Prerequisites
+
+- A terminal with color and Unicode: Windows Terminal, iTerm2, Terminal.app or a current Linux terminal. The old Windows Command Prompt window does not qualify.
+- To run the standalone binary: Windows, macOS (Apple silicon or Intel), Linux x86_64 or Linux arm64 with glibc 2.31 or newer (Ubuntu 20.04, Debian 11, Fedora 32, RHEL 9).
+- To run from source or the wheel: Python 3.13 or newer.
+- For Discord copy on Linux: `xclip` (X11) or `wl-clipboard` (Wayland).
+- For the default icon style: a [Nerd Font](https://www.nerdfonts.com/) set as the terminal font. Without one, start with `--glyphs unicode`.
+
+## Quickstart
+
+Standalone binary:
+
+1. Download the file for your system from the [latest release](https://github.com/WPTK/cfbtui/releases/latest): `cfbtui-windows-x86_64.exe`, `cfbtui-macos-arm64`, `cfbtui-macos-x86_64`, `cfbtui-linux-x86_64` or `cfbtui-linux-arm64`.
+2. On macOS and Linux, make it executable. On macOS, also remove the quarantine flag (the binary is not notarized):
+
+   ```sh
+   chmod +x cfbtui-macos-arm64
+   xattr -d com.apple.quarantine cfbtui-macos-arm64
+   ```
+
+3. Run it. On Windows the exe is not code-signed, so if SmartScreen warns, choose More info, then Run anyway.
+
+   ```sh
+   ./cfbtui-macos-arm64
+   ```
+
+   ```powershell
+   .\cfbtui-windows-x86_64.exe
+   ```
+
+From source:
+
+1. Clone the repository and create a virtual environment:
+
+   ```sh
+   git clone https://github.com/WPTK/cfbtui.git
+   cd cfbtui
+   python3 -m venv .venv
+   ```
+
+2. Install the package. On Windows use `.venv\Scripts\python`; on macOS and Linux use `.venv/bin/python`:
+
+   ```sh
+   .venv/bin/python -m pip install -e .
+   ```
+
+3. Run it:
+
+   ```sh
+   .venv/bin/python -m cfbtui
+   ```
+
+Expected result: the current week's games appear as cards within a few seconds. Press `?` for every key and `q` to quit. If you see "Could not reach ESPN", check your connection; cfbtui keeps retrying.
+
+To verify a download, see [docs/verify.md](docs/verify.md).
+
+## Configuration
+
+Settings come from three layers. Command-line flags override the settings file for that run only. The settings file overrides the defaults. A bad value is ignored with a warning.
+
+### Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--week N` | current week | Start on week 1-15, or `bowls` or `playoff`. |
+| `--group fbs\|fcs` | `fbs` | Start on the FBS or FCS board. |
+| `--glyphs NAME` | `nerd` | Icon style: `ascii`, `unicode`, `emoji` or `nerd`. |
+| `--layout grid\|list` | `grid` | Cards, or one line per game. |
+| `--config PATH` | platform default | Read and save this settings file. |
+| `--no-config` | off | Ignore the settings file and never write it. |
+| `--no-update-check` | off | Skip the release check and the download. |
+| `--version` | | Print the version and exit. |
+
+### Settings file
+
+cfbtui creates the file the first time you star a team or change a setting. Edit it in any text editor.
+
+| System | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\cfbtui\config.toml` |
+| macOS | `~/Library/Application Support/cfbtui/config.toml` |
+| Linux | `~/.config/cfbtui/config.toml`, or under `$XDG_CONFIG_HOME` |
+
+| Key | Default | Description |
+|---|---|---|
+| `[poll] live` | `20` | Seconds between updates while you are at the computer. |
+| `[poll] idle` | `120` | Seconds between updates once you have walked away. |
+| `[poll] away_after` | `300` | Seconds without keyboard or mouse input before you count as away. |
+| `[poll] backoff_max` | `120` | Longest wait in seconds between retries after failed requests. |
+| `[view] glyph_set` | `"nerd"` | `ascii`, `unicode`, `emoji` or `nerd`. |
+| `[view] layout` | `"grid"` | `grid` or `list`. |
+| `[view] week` | current week | 1-15, 16 for Bowls, 17 for the Playoff. |
+| `[view] group` | `"fbs"` | `fbs` or `fcs`. |
+| `[favorites] team_ids` | `[]` | ESPN team ids, such as `["251"]`. The `1` and `2` keys fill this in. |
+| `[favorites] abbreviations` | `[]` | Teams by abbreviation, such as `["TEX"]`. |
+| `[alerts] enabled` | `true` | Pulse a card on Red Zone, Upset Watch, Overtime or Final. |
+| `[updates] check` | `true` | Look for a newer release at startup. |
+| `[updates] auto` | `true` | Download new minor and patch versions (standalone binaries only). |
+
+Update behavior is in [docs/updating.md](docs/updating.md).
+
+## Usage and controls
+
+Arrow keys move between cards, `Enter` opens one and `?` lists every key.
+
+![Game detail](docs/img/detail.png)
+
+| Key | Action |
+|---|---|
+| arrow keys | Move between games. |
+| `Enter` | Open the game: every scoring play and win probability. |
+| `R` | Rankings. Press `c` there to copy the polls for Discord, one poll per press. |
+| `N` | News. `Enter` reads a story, `o` opens the original in your browser, `r` refreshes. |
+| `[` `]` | Previous or next week. After week 15 come Bowls and the Playoff. |
+| `t` | Back to this week. |
+| `f` | Switch between FBS and FCS. |
+| `l` | Filter: all games, Top 25, live only, favorites. |
+| `o` | Pick a conference. |
+| `v` | Switch between cards and a list. |
+| `S` | Settings. Changes save as you make them. |
+| `1` `2` | Star the away or home team. Starred games move to a Favorites section at the top. |
+| `c` | Copy the selected game for Discord, with the winner in bold. |
+| `C` | Copy the board as a code block. Discord caps messages at 2,000 characters, so a big Saturday copies one part per press. |
+| `r` | Refresh now. |
+| `g` | Cycle the icon style. |
+| `Tab`, then `Up` or `Down` | Move through the ticker. `Enter` or a click shows that game. |
+| `Esc` | Close a screen. |
+| `q` | Quit. |
+
+Once the College Football Playoff committee releases its first ranking, `R` shows only the CFP ranking for the rest of the season. The FCS board shows the FCS Coaches poll.
+
+![Rankings](docs/img/rankings.png)
+
+## Troubleshooting
+
+- Icons show as empty boxes: set a Nerd Font as the terminal font, or press `g` to cycle to another icon style.
+- "Could not reach ESPN": check your connection. If the rest of the internet works, ESPN's service may be down. cfbtui retries with growing waits.
+- No games listed: the week may have no games, or a filter or conference is hiding them. Press `l` until the bottom bar says all games, then `t`.
+- `c` reports no clipboard on Linux: install `xclip` or `wl-clipboard`.
+
+## Data and privacy
+
+Scores and news come from ESPN's public, unofficial and undocumented endpoints, which can change or disappear without notice. cfbtui is an independent project and has no affiliation with ESPN or the NCAA.
+
+The news list refreshes every 10 minutes while you are at the computer and stops once you step away (on Windows; on other systems cfbtui cannot detect this and assumes you are there). A story's text is fetched only when you open it, kept in memory for the last 20 stories and never written to disk. Stories show ESPN's name as the source, and `o` opens the original. ESPN's content falls under Disney's [terms of use](https://disneytermsofuse.com/english/), which grant a personal, noncommercial licence and restrict automated access and copying. Fetching a story only when you ask lowers that risk and does not remove it. This is not legal advice.
+
+At startup cfbtui requests the latest release from GitHub. The request reveals your IP address and nothing else. Turn it off with `--no-update-check` or `check = false`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

cfbtui-1.13.1/cfbtui/__init__.py

@@ -0,0 +1,4 @@
+"""cfbtui: a colorful college football scoreboard for the terminal."""
+
+# FibVer. Do not edit by hand; use `python -m cfbtui.version bump <part> --write`.
+__version__ = "1.13.1"

cfbtui-1.13.1/cfbtui/__main__.py

@@ -0,0 +1,223 @@
+"""Command-line entry point: ``python -m cfbtui`` or the ``cfbtui`` console script.
+
+Flags override the config file for this run only and are never written back.
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import subprocess
+import sys
+from functools import partial
+from pathlib import Path
+
+from cfbtui import __version__
+from cfbtui.config import GROUPS, LAYOUTS, Config, LoadResult, apply_overrides, default_path, load_config
+from cfbtui.espn.periods import LAST_REGULAR_WEEK, MAX_WEEK, MIN_WEEK, NAMED
+from cfbtui.ui.glyphs import GLYPH_SET_NAMES
+
+
+def _week(text: str) -> int:
+    if text.strip().lower() in NAMED:
+        return NAMED[text.strip().lower()]
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a week number, 'bowls' or 'playoff'") from None
+    if not MIN_WEEK <= value <= MAX_WEEK:
+        raise argparse.ArgumentTypeError(f"week must be {MIN_WEEK} to {MAX_WEEK} (16 = bowls, 17 = playoff)")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cfbtui",
+        description="A colorful college football scoreboard for the terminal.",
+    )
+    parser.add_argument("--version", action="version", version=f"cfbtui {__version__}")
+    parser.add_argument(
+        "--week",
+        type=_week,
+        metavar="N",
+        help=f"start on week N ({MIN_WEEK}-{LAST_REGULAR_WEEK}), 'bowls' or 'playoff' instead of the current week",
+    )
+    parser.add_argument("--group", type=str.lower, choices=sorted(GROUPS), help="FBS or FCS board")
+    parser.add_argument(
+        "--glyphs",
+        type=str.lower,
+        choices=GLYPH_SET_NAMES,
+        metavar="NAME",
+        help=f"glyph set: {', '.join(GLYPH_SET_NAMES)}",
+    )
+    parser.add_argument("--layout", type=str.lower, choices=LAYOUTS, help="card grid or one line per game")
+    parser.add_argument("--config", type=Path, metavar="PATH", help=f"config file (default: {default_path()})")
+    parser.add_argument("--no-config", action="store_true", help="ignore the config file and do not save to it")
+    parser.add_argument("--selftest", action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("--update-test", choices=("apply", "restart"), help=argparse.SUPPRESS)
+    parser.add_argument("--no-update-check", action="store_true", help="do not look for a newer release")
+    return parser
+
+
+def resolve(argv: list[str] | None = None) -> tuple[Config, LoadResult, Path | None]:
+    """Parse flags, load the file, and layer the flags on top.
+
+    Returns the effective config, the raw load result (for its warnings) and
+    the path favorites will be saved to (``None`` under ``--no-config``).
+    """
+    args = build_parser().parse_args(argv)
+    if args.no_config:
+        loaded = LoadResult(Config())
+        save_path = None
+    else:
+        save_path = args.config if args.config is not None else default_path()
+        loaded = load_config(save_path)
+    config = apply_overrides(
+        loaded.config,
+        week=args.week,
+        group=args.group,
+        glyph_set=args.glyphs,
+        layout=args.layout,
+        check_updates=False if args.no_update_check else None,
+    )
+    return config, loaded, save_path
+
+
+def selftest() -> int:
+    """Start the app headless against an empty board, so a frozen build proves its imports, CSS and tzdata."""
+    import asyncio
+    from zoneinfo import ZoneInfo
+
+    from cfbtui.app import CfbApp
+    from cfbtui.espn.models import Scoreboard, Summary
+
+    class EmptyBoard:
+        async def scoreboard(self, *, week: int | None = None, group: int = 80) -> Scoreboard:
+            return Scoreboard()
+
+        async def rankings(self) -> tuple:
+            return ()
+
+        async def summary(self, event_id: str) -> Summary:
+            raise NotImplementedError  # the selftest never opens a game
+
+        async def news(self, limit: int = 30) -> tuple:
+            return ()
+
+        async def story(self, url: str) -> str:
+            raise NotImplementedError  # the selftest never opens a story
+
+    async def run() -> None:
+        app = CfbApp(client=EmptyBoard(), config=Config())
+        async with app.run_test(size=(100, 30)) as pilot:
+            await pilot.pause()
+
+    ZoneInfo("America/New_York")
+    asyncio.run(run())
+    print("selftest ok")
+    return 0
+
+
+def restart(target: Path, args: list[str], execve=os.execve, call=subprocess.call) -> None:
+    """Start the installed binary again with the same arguments and a clean PyInstaller environment.
+
+    Windows has no exec, so it waits for the child.
+    """
+    from cfbtui.selfupdate import child_env
+
+    if sys.platform == "win32":
+        raise SystemExit(call([str(target), *args], env=child_env()))
+    execve(target, [str(target), *args], child_env())
+
+
+def install_update(updater, staged, app) -> bool:
+    """Swap the staged binary in after the app has exited, or discard it. Returns whether it was installed.
+
+    A staged update is installed only if cfbtui exited normally and auto-update is still on (or the user chose
+    Restart now). A failure leaves the old version in place and says why on stderr.
+    """
+    from cfbtui.selfupdate import UpdateError
+
+    if app.return_code not in (0, None) or not (app.config.updates.auto or app.restart_requested):
+        staged.discard()
+        return False
+    try:
+        updater.apply(staged)
+    except UpdateError as exc:  # RollbackError says how to recover by hand
+        print(f"cfbtui: the update was not installed: {exc}", file=sys.stderr)
+        return False
+    return True
+
+
+def update_test(mode: str, updater, argv: list[str]) -> int:
+    """Run the update path with no TUI (the end-to-end workflow cannot drive one): check, stage and probe
+    a newer release, install it, and for "restart" start the new binary. Exit 1 when the update fails."""
+    import asyncio
+    from types import SimpleNamespace
+
+    from cfbtui.selfupdate import UpdateError
+    from cfbtui.update import asset_name, check_for_update, decide
+
+    info = asyncio.run(check_for_update(__version__))
+    if info is None:
+        print(f"cfbtui {__version__}: up to date")
+        return 0
+    if decide(updater.kind, auto=True, no_config=False, current=__version__, info=info,
+              asset=asset_name()) != "download":
+        print("cfbtui: this release would not be downloaded", file=sys.stderr)
+        return 2
+    try:
+        staged = updater.stage(info)
+    except UpdateError as exc:
+        print(f"cfbtui: could not download {info.version}: {exc}", file=sys.stderr)
+        return 1
+    app = SimpleNamespace(return_code=0, config=Config(), restart_requested=mode == "restart")
+    if not install_update(updater, staged, app):
+        return 1
+    print(f"cfbtui {info.version} installed")
+    if mode == "restart":
+        restart(updater.target, argv)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None and "--selftest" in sys.argv[1:]:
+        return selftest()
+    config, loaded, save_path = resolve(argv)
+
+    # Imported lazily so `--version` stays instant and never touches the terminal.
+    from cfbtui.app import CfbApp
+    from cfbtui.selfupdate import Updater, cleanup_old, sweep
+    from cfbtui.update import check_for_update
+
+    update_check = partial(check_for_update, __version__) if config.updates.check else None
+    updater = Updater.detect(__version__)
+    if updater.kind == "binary":
+        with contextlib.suppress(Exception):
+            cleanup_old(updater.target)  # drop the previous version, or restore it after a crashed swap
+            sweep(updater.target.parent)  # and any download an earlier run left behind
+    mode = build_parser().parse_args(argv).update_test
+    if mode is not None:
+        if updater.kind != "binary":
+            print("cfbtui: --update-test needs a standalone binary", file=sys.stderr)
+            return 2
+        return update_test(mode, updater, sys.argv[1:] if argv is None else argv)
+    app_updater = None if update_check is None else updater  # --no-update-check: no checking and no downloading
+    app = CfbApp(
+        config=config,
+        file_config=loaded.config,
+        config_path=save_path,
+        warnings=loaded.warnings,
+        update_check=update_check,
+        updater=app_updater,
+    )
+    app.run()
+    if app.staged is not None and app_updater is not None:
+        installed = install_update(app_updater, app.staged, app)
+        if installed and app.restart_requested:
+            restart(app_updater.target, sys.argv[1:] if argv is None else argv)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())