slab-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{slab_cli-0.5.0 → slab_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal.
 Author: dev_jeb
 Requires-Dist: slab-schemas>=0.1.0
@@ -56,11 +56,32 @@ to see a group's verbs.
 
 ## Configuration reference
 
-| Env var         | Purpose                                    | Default                          |
-| --------------- | ------------------------------------------ | -------------------------------- |
-| `SLAB_API_KEY`  | API key for authentication (**required**)  | —                                |
-| `SLAB_API_URL`  | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
-| `SLAB_COLLECTOR`| Active collector UUID, reused per command  | —                                |
+| Env var                | Purpose                                    | Default                          |
+| ---------------------- | ------------------------------------------ | -------------------------------- |
+| `SLAB_API_KEY`         | API key for authentication (**required**)  | —                                |
+| `SLAB_API_URL`         | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
+| `SLAB_COLLECTOR`       | Active collector UUID, reused per command  | —                                |
+| `SLAB_NO_UPDATE_CHECK` | Set to `1` to silence update checks        | —                                |
+
+## Staying up to date
+
+Nothing updates itself. At most once a day the CLI asks PyPI (in the background, while your command
+runs) whether there's a newer release, and if so prints one line after the output:
+
+```
+▍ slab-cli 0.7.0 is available — you have 0.6.0
+  Update when you like: slab update
+```
+
+```bash
+slab --version         # what you have
+slab update check      # ask PyPI right now; installs nothing
+slab update            # upgrade, after showing the command and asking
+```
+
+`slab update` runs the upgrade that matches how you installed slab — `pipx upgrade`,
+`uv tool upgrade`, or `pip install --upgrade` — and prints it first, so you can decline and run it
+yourself. To turn the whole thing off: `export SLAB_NO_UPDATE_CHECK=1`.
 
 ## What it depends on
 

{slab_cli-0.5.0 → slab_cli-0.6.0}/README.md

@@ -44,11 +44,32 @@ to see a group's verbs.
 
 ## Configuration reference
 
-| Env var         | Purpose                                    | Default                          |
-| --------------- | ------------------------------------------ | -------------------------------- |
-| `SLAB_API_KEY`  | API key for authentication (**required**)  | —                                |
-| `SLAB_API_URL`  | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
-| `SLAB_COLLECTOR`| Active collector UUID, reused per command  | —                                |
+| Env var                | Purpose                                    | Default                          |
+| ---------------------- | ------------------------------------------ | -------------------------------- |
+| `SLAB_API_KEY`         | API key for authentication (**required**)  | —                                |
+| `SLAB_API_URL`         | Base URL of the slab API                   | `https://api.slab.dev-jeb.com`   |
+| `SLAB_COLLECTOR`       | Active collector UUID, reused per command  | —                                |
+| `SLAB_NO_UPDATE_CHECK` | Set to `1` to silence update checks        | —                                |
+
+## Staying up to date
+
+Nothing updates itself. At most once a day the CLI asks PyPI (in the background, while your command
+runs) whether there's a newer release, and if so prints one line after the output:
+
+```
+▍ slab-cli 0.7.0 is available — you have 0.6.0
+  Update when you like: slab update
+```
+
+```bash
+slab --version         # what you have
+slab update check      # ask PyPI right now; installs nothing
+slab update            # upgrade, after showing the command and asking
+```
+
+`slab update` runs the upgrade that matches how you installed slab — `pipx upgrade`,
+`uv tool upgrade`, or `pip install --upgrade` — and prints it first, so you can decline and run it
+yourself. To turn the whole thing off: `export SLAB_NO_UPDATE_CHECK=1`.
 
 ## What it depends on
 

{slab_cli-0.5.0 → slab_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slab-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal."
 readme = "README.md"
 authors = [{name = "dev_jeb"}]

{slab_cli-0.5.0 → slab_cli-0.6.0}/src/slab_cli/commands/registry.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass, field
 from difflib import get_close_matches
 from typing import Callable
 
-from . import breaks, catalog, collection, custom_sets, export, lots, pricing, setup
+from . import breaks, catalog, collection, custom_sets, export, lots, pricing, setup, update
 
 Handler = Callable[[list[str]], None]
 
@@ -106,6 +106,12 @@ GROUPS: list[Group] = [
     Group("collector", "your identity", [
         Command("current", "Show the active collector", setup.cmd_whoami),
     ]),
+    # Bare `slab update` upgrades (the verb the update nudge tells people to run); `slab update
+    # check` is the look-don't-touch half. Nothing installs without a confirmation either way.
+    Group("update", "keep the CLI current", [
+        Command("install", "Upgrade slab-cli to the newest published version", update.cmd_install),
+        Command("check", "Check PyPI for a newer version (installs nothing)", update.cmd_check),
+    ], default="install"),
 ]
 
 # --- Lookup + suggestion (used by dispatch) ----------------------------------------------------

slab_cli-0.6.0/src/slab_cli/commands/update.py

@@ -0,0 +1,124 @@
+"""`slab update` — the explicit half of update handling: check PyPI now, then upgrade on confirm.
+
+The nudge after other commands is passive and cache-backed (`slab_cli.updates`); everything here is
+synchronous and asks first. Nothing is ever installed without a yes, and the exact command is printed
+before it runs — so a user who'd rather run it themselves (or in another environment) can just copy it.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from ..flags import FlagError
+from ..prompts import confirm
+from ..theme import console
+from .. import updates
+
+
+def _say(markup: str) -> None:
+    """Print markup with Rich's number highlighting off — "0.5.0" is one version token, not three
+    numbers to paint cyan."""
+    console.print(markup, highlight=False)
+
+
+def _no_args(args: list[str], usage: str) -> None:
+    """These commands take nothing — say so loudly rather than ignoring a typo'd flag."""
+    if args:
+        raise FlagError(f"`{usage}` takes no arguments (got: {' '.join(args)}).")
+
+
+def _versions() -> tuple[str, str] | None:
+    """(current, latest) from a live PyPI check, or None after explaining why we can't tell."""
+    current = updates.current_version()
+    if current is None:
+        _say("[yellow]This slab isn't an installed package.[/yellow]")
+        _say("  [slab.dim]It's running from a source checkout, which has no published "
+             "version to compare against — update it with git, not pip.[/]")
+        return None
+
+    with console.status("[slab.dim]Checking PyPI for a newer slab-cli…[/]", spinner="dots"):
+        latest = updates.check_now()
+
+    if latest is None:
+        _say("[yellow]Couldn't reach PyPI to check for a newer version.[/yellow]")
+        _say(f"  [slab.dim]You have slab-cli {current}. Check your connection, or upgrade "
+             f"manually:[/] [slab.value]{' '.join(updates.upgrade_command())}[/]")
+        return None
+    return current, latest
+
+
+def _report(current: str, latest: str) -> bool:
+    """Print where you stand. True when an upgrade is actually available."""
+    if updates.is_newer(current, latest):
+        # Ahead of PyPI — an unreleased build (a dev install, a pre-release). Don't call that
+        # "up to date", which would imply the two versions match.
+        _say(f"[slab.gain]You're ahead of PyPI[/] [slab.dim]— you have slab-cli {current}; "
+             f"the newest published is {latest}.[/]")
+        return False
+    if not updates.is_newer(latest, current):
+        _say(f"[slab.gain]You're up to date[/] [slab.dim]— slab-cli {current} is the "
+             f"newest published version.[/]")
+        return False
+    _say(f"[slab.foil]slab-cli {latest} is available[/] [slab.dim]— you have {current}[/]")
+    return True
+
+
+def cmd_check(args: list[str]) -> None:
+    """Ask PyPI whether a newer slab-cli exists, and print the upgrade command — install nothing.
+
+    This is the same lookup `slab update` does, minus the install. It bypasses the once-a-day cache
+    behind the "an update is available" nudge, so it always reflects PyPI as of right now."""
+    _no_args(args, "slab update check")
+    pair = _versions()
+    if pair is None:
+        return
+    current, latest = pair
+    if _report(current, latest):
+        _say(f"  [slab.dim]Install it with[/] [slab.value]slab update[/] "
+             f"[slab.dim]— or run[/] [slab.value]{' '.join(updates.upgrade_command())}[/] "
+             f"[slab.dim]yourself.[/]")
+
+
+def cmd_install(args: list[str]) -> None:
+    """Upgrade slab-cli to the newest version published on PyPI.
+
+    Checks PyPI live, then — only if you confirm — runs the upgrade the way this slab was installed:
+    `pipx upgrade`, `uv tool upgrade`, or `pip install --upgrade` for a plain venv. The command is
+    printed before it runs, so you can decline and run it yourself instead.
+
+    Updates are never automatic: other commands only ever print a one-line nudge (silence the whole
+    thing with SLAB_NO_UPDATE_CHECK=1)."""
+    _no_args(args, "slab update")
+    pair = _versions()
+    if pair is None:
+        return
+    current, latest = pair
+    if not _report(current, latest):
+        return
+
+    command = updates.upgrade_command()
+    _say(f"  [slab.dim]Upgrade command:[/] [slab.value]{' '.join(command)}[/]")
+    if not confirm("Run it now?", default=True):
+        _say("  [slab.dim]Nothing installed — run the command above whenever you're ready.[/]")
+        return
+
+    console.print()
+    try:
+        # Inherit stdio so pip/pipx/uv progress streams straight through — a silent install that
+        # takes 20 seconds looks hung.
+        code = subprocess.call(command)
+    except (OSError, subprocess.SubprocessError) as e:
+        _say(f"[red]Couldn't run the upgrade: {e}[/red]")
+        _say(f"  [slab.dim]Run it yourself:[/] [slab.value]{' '.join(command)}[/]")
+        return
+
+    if code != 0:
+        _say(f"\n[red]The upgrade command exited with status {code}.[/red]")
+        _say("  [slab.dim]Its output is above. Nothing about your collection is affected — "
+             "this only replaces the CLI.[/]")
+        return
+
+    # The running process still has the OLD version imported, so confirm from a fresh one rather
+    # than reporting a version we can't actually see yet.
+    _say(f"\n[slab.gain]Upgraded to slab-cli {latest}.[/] "
+         f"[slab.dim]Confirm with[/] [slab.value]slab --version[/]")

{slab_cli-0.5.0 → slab_cli-0.6.0}/src/slab_cli/help.py

@@ -14,6 +14,7 @@ import inspect
 from .banner import BANNER
 from .commands.registry import GROUPS, Command, Group
 from .theme import console, heading
+from .updates import current_version
 
 _CONFIG = "SLAB_API_URL · SLAB_API_KEY · SLAB_COLLECTOR"
 
@@ -100,4 +101,8 @@ def render_root_help() -> None:
         console.print(heading(group.name, group.blurb))
         console.print(_group_table(group))
         console.print()
-    console.print(Text.from_markup(f"  [slab.label]Config[/]  [slab.dim]{_CONFIG}[/]\n"))
+    console.print(Text.from_markup(f"  [slab.label]Config[/]   [slab.dim]{_CONFIG}[/]"))
+    # The installed version, right where people look for it. Whether it's the NEWEST version is the
+    # update nudge's job (printed after any command from a cached daily check) — not restated here.
+    version = current_version() or "source checkout"
+    console.print(Text.from_markup(f"  [slab.label]Version[/]  [slab.dim]slab-cli {version}[/]\n"))

{slab_cli-0.5.0 → slab_cli-0.6.0}/src/slab_cli/main.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import re
 import sys
 
+from . import updates
 from .client import ApiConnectionError, ApiError
 from .commands.registry import get_command, get_group, suggest_group, suggest_verb
 from .context import MissingCollector
@@ -19,6 +20,7 @@ from .flags import FlagError
 from .help import render_command_help, render_group_help, render_root_help
 
 _HELP_FLAGS = ("-h", "--help", "help")
+_VERSION_FLAGS = ("-V", "--version")
 
 # assert_owned's 404 detail for an unknown/unowned collector is exactly "collector <uuid> not found".
 # Distinct from copy/break/lot not-found details ("copy X not found for collector Y"), which name a
@@ -31,12 +33,24 @@ def _is_missing_collector(detail: str | None) -> bool:
     return bool(detail and _MISSING_COLLECTOR_RE.match(detail))
 
 
+def _print_version() -> None:
+    """`slab --version` — the installed version. Instant: no network, and if a newer release is
+    already known from the cached daily check, the usual nudge follows it. `slab update check` is
+    the one that asks PyPI live."""
+    version = updates.current_version() or "(source checkout — no installed version)"
+    console.print(f"slab-cli {version}", highlight=False)  # a version is one token, not numbers to color
+
+
 def _run(args: list[str]) -> int:
     """Resolve `args` against the registry and run the command. Returns a process exit code."""
     if not args or args[0] in _HELP_FLAGS:
         render_root_help()
         return 0
 
+    if args[0] in _VERSION_FLAGS:
+        _print_version()
+        return 0
+
     group_name = args[0]
     group = get_group(group_name)
     if group is None:
@@ -75,23 +89,27 @@ def _run(args: list[str]) -> int:
     return 0
 
 
-def main() -> None:
+def _dispatch(args: list[str]) -> int:
+    """Run the command, turning every expected failure into an exit code + a plain-English message
+    (never a traceback). Split out of `main` so the update nudge can be printed on the way out of
+    *any* path — success, cancel, or error — exactly once."""
     try:
-        sys.exit(_run(sys.argv[1:]))
+        return _run(args)
     except KeyboardInterrupt:
         console.print("\n[dim]Cancelled.[/dim]")
+        return 0
     except FlagError as e:
         console.print(f"[red]{e}[/red]")
-        sys.exit(2)
+        return 2
     except MissingCollector:
         console.print("[red]No collector resolved for this API key.[/red]")
         console.print("  Your collector is created when you sign up in the portal.")
         console.print("  Grab its UUID there, then: export SLAB_COLLECTOR=<uuid>")
-        sys.exit(1)
+        return 1
     except ApiConnectionError as e:
         console.print(f"\n[red]{e}[/red]")
         console.print("[dim]  Check that the API is running and SLAB_API_URL is correct.[/dim]")
-        sys.exit(1)
+        return 1
     except ApiError as e:
         if e.status == 404 and _is_missing_collector(e.detail):
             # The active collector (SLAB_COLLECTOR) doesn't resolve to a live collector on this
@@ -106,7 +124,21 @@ def main() -> None:
             console.print("[red]Unauthorized — check your SLAB_API_KEY.[/red]")
         else:
             console.print(f"[red]API error: {e}[/red]")
-        sys.exit(1)
+        return 1
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    # Kick the once-a-day PyPI check off first so it overlaps the command's own work in a daemon
+    # thread; the nudge itself is printed from cache, last, so it's the line left on screen and it
+    # never delays anything. `slab update` reports its own version state — don't tail it with a nudge.
+    updates.start_background_check()
+    try:
+        code = _dispatch(args)
+    finally:
+        if args[:1] != ["update"]:
+            updates.print_notice()
+    sys.exit(code)
 
 
 if __name__ == "__main__":

slab_cli-0.6.0/src/slab_cli/updates.py

@@ -0,0 +1,242 @@
+"""Update awareness — tell the user when a newer `slab-cli` is on PyPI, never force one on them.
+
+The rule this module exists to keep: **checking for updates must be invisible unless there IS one.**
+So it never blocks a command and never fails one:
+
+- The nudge printed after a command comes from a small cache file (`~/.slab/update-check.json`),
+  so it normally costs no network at all.
+- The cache is refreshed at most once a day, in a **daemon thread started at the top of `main()`** —
+  it runs alongside the command's own API calls, so it's usually done before the command is. On the
+  way out we wait at most `FINISH_GRACE_S` for it (see `_await_check`): without that grace a fast
+  command like `slab --version` exits first and the check never lands at all. Writes are atomic
+  (tmp + rename) because the thread can still be killed at exit.
+- Every failure path — offline, PyPI 500, junk JSON, unwritable home — resolves to "say nothing".
+  A version check is never worth breaking `slab card price` over.
+- A failed refresh still stamps `checked_at`, so an offline user isn't retried on every command.
+
+`slab update` (`commands/update.py`) is the explicit counterpart: it bypasses the cache, checks
+synchronously, and runs the upgrade — after asking. Set `SLAB_NO_UPDATE_CHECK=1` to silence the
+whole mechanism (both the nudge and the background fetch).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import threading
+import time
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+from pathlib import Path
+
+import httpx
+from rich.text import Text
+
+from .theme import console
+
+PACKAGE = "slab-cli"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{PACKAGE}/json"
+
+CACHE_PATH = Path.home() / ".slab" / "update-check.json"
+CHECK_INTERVAL_S = 24 * 60 * 60  # once a day is plenty — releases aren't hourly
+BACKGROUND_TIMEOUT_S = 3.0       # nobody is waiting on this one
+FOREGROUND_TIMEOUT_S = 10.0      # `slab update` — the user asked and is watching
+FINISH_GRACE_S = 1.0             # most we'll delay exit for an in-flight check (PyPI answers in ~0.2s)
+
+
+# --- Versions (pure) -------------------------------------------------------------------------------
+
+# PEP 440-lite: a dotted release, optionally followed by a pre-release marker. Long alternatives
+# come first so `alpha`/`beta`/`preview` win over `a`/`b`/`pre`.
+_VERSION_RE = re.compile(
+    r"^\s*v?(\d+(?:\.\d+)*)"
+    r"(?:[-_.]?(dev|alpha|beta|preview|pre|rc|a|b|c)[-_.]?(\d*))?",
+    re.IGNORECASE,
+)
+
+# Pre-release ranks sort BELOW a final release (4), so 0.6.0rc1 < 0.6.0.
+_PRE_RANK = {"dev": 0, "a": 1, "alpha": 1, "b": 2, "beta": 2, "c": 3, "rc": 3, "pre": 3, "preview": 3}
+
+
+def parse_version(v: str) -> tuple:
+    """A sortable key for a version string — the ONE definition of 'newer' in the CLI.
+
+    Compares numerically (so `0.10.0` beats `0.9.0`, which a string compare gets backwards), pads
+    the release to four segments (so `0.6` == `0.6.0`), and ranks pre-releases below their final.
+    Anything unparseable sorts lowest, which makes an odd string on PyPI a no-op rather than a
+    bogus "update available"."""
+    m = _VERSION_RE.match(v or "")
+    if not m:
+        return ((0,), -1, 0)
+    release = tuple(int(p) for p in m.group(1).split("."))
+    if len(release) < 4:
+        release += (0,) * (4 - len(release))
+    label = (m.group(2) or "").lower()
+    return (release, _PRE_RANK.get(label, 4), int(m.group(3) or 0))
+
+
+def is_newer(latest: str | None, current: str | None) -> bool:
+    """True when `latest` is a strictly newer version than `current`."""
+    if not latest or not current:
+        return False
+    return parse_version(latest) > parse_version(current)
+
+
+def current_version() -> str | None:
+    """The installed `slab-cli` version, or None when there is no dist metadata — i.e. the CLI is
+    being run straight from a source checkout. None means "don't check": a git working copy has no
+    published version to compare against, and every run would claim to be out of date."""
+    try:
+        return _dist_version(PACKAGE)
+    except PackageNotFoundError:
+        return None
+
+
+def upgrade_command(prefix: str | None = None) -> list[str]:
+    """The upgrade command for HOW this slab was installed, inferred from the environment root.
+
+    `pipx install slab-cli` lands in `…/pipx/venvs/slab-cli`, `uv tool install` in `…/uv/tools/slab-cli`
+    — both manage their own venvs and must be upgraded through their own tool, not pip. Anything else
+    (a plain venv, `pip install --user`) upgrades with the running interpreter's pip."""
+    parts = {p.lower() for p in Path(prefix or sys.prefix).parts}
+    if "pipx" in parts:
+        return ["pipx", "upgrade", PACKAGE]
+    if "uv" in parts and "tools" in parts:
+        return ["uv", "tool", "upgrade", PACKAGE]
+    return [sys.executable, "-m", "pip", "install", "--upgrade", PACKAGE]
+
+
+def notice_text(current: str | None, latest: str | None) -> str | None:
+    """The nudge as markup, or None when there's nothing to say. Pure — the whole decision of
+    *whether* to nag lives here, so the wording and the condition are testable together."""
+    if not is_newer(latest, current):
+        return None
+    return (
+        f"\n[slab.foil]▍ slab-cli {latest} is available[/] [slab.dim]— you have {current}[/]\n"
+        f"  [slab.dim]Update when you like:[/] [slab.value]slab update[/]"
+    )
+
+
+# --- Cache (the nudge's only data source) ----------------------------------------------------------
+
+def read_cache(path: Path = CACHE_PATH) -> dict:
+    """The cached check as a dict, or `{}` for missing/corrupt/unreadable — never raises."""
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_cache(latest: str | None, path: Path = CACHE_PATH, *, now: float | None = None) -> None:
+    """Record a completed check. Written tmp-then-rename so the background thread being killed
+    mid-write can't leave a half-parsed file behind. `latest=None` still stamps the time (a failed
+    check counts as checked, so an offline user isn't retried every command)."""
+    payload = {"checked_at": now if now is not None else time.time(), "latest": latest}
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(path.name + ".tmp")
+        tmp.write_text(json.dumps(payload))
+        tmp.replace(path)
+    except OSError:
+        pass  # a read-only home is not an error worth surfacing
+
+
+def is_due(cache: dict, now: float, interval: float = CHECK_INTERVAL_S) -> bool:
+    """True when the cached check is older than `interval` (or absent)."""
+    checked_at = cache.get("checked_at")
+    if not isinstance(checked_at, (int, float)):
+        return True
+    return (now - checked_at) >= interval
+
+
+# --- Fetching --------------------------------------------------------------------------------------
+
+def fetch_latest(timeout: float = BACKGROUND_TIMEOUT_S) -> str | None:
+    """The newest published version per PyPI's JSON API, or None on ANY failure.
+
+    `info.version` is PyPI's own "latest release" (yanked releases excluded), so no client-side
+    sorting is needed. The blanket except is deliberate: a version check must never turn into a
+    traceback in front of a user who was trying to price a card."""
+    try:
+        response = httpx.get(PYPI_JSON_URL, timeout=timeout, follow_redirects=True)
+        response.raise_for_status()
+        latest = response.json()["info"]["version"]
+    except Exception:
+        return None
+    return latest if isinstance(latest, str) else None
+
+
+def check_now(timeout: float = FOREGROUND_TIMEOUT_S) -> str | None:
+    """Check PyPI right now, bypassing the daily cache, and record the result. `slab update`'s
+    lookup — an explicit command should never answer from a day-old cache."""
+    latest = fetch_latest(timeout)
+    write_cache(latest or read_cache().get("latest"))
+    return latest
+
+
+# --- The two hooks main() calls --------------------------------------------------------------------
+
+def checks_disabled() -> bool:
+    """SLAB_NO_UPDATE_CHECK — one switch that silences the nudge AND the background fetch."""
+    return bool(os.environ.get("SLAB_NO_UPDATE_CHECK", "").strip())
+
+
+# The in-flight check, process-wide: one CLI run performs at most one. `_fetched` lets this run's
+# nudge use a result that arrived just now, so discovering a release doesn't wait until tomorrow.
+_thread: threading.Thread | None = None
+_fetched: dict[str, str | None] = {}
+_awaited = False
+
+
+def start_background_check() -> None:
+    """Refresh the cache in a daemon thread when a check is due. Returns immediately — the command
+    runs while PyPI answers. Call once, at the top of `main()`."""
+    global _thread
+    if checks_disabled() or current_version() is None or _thread is not None:
+        return
+    if not is_due(read_cache(), time.time()):
+        return
+    _thread = threading.Thread(target=_refresh, name="slab-update-check", daemon=True)
+    _thread.start()
+
+
+def _refresh() -> None:
+    latest = fetch_latest() or read_cache().get("latest")
+    _fetched["latest"] = latest if isinstance(latest, str) else None
+    write_cache(_fetched["latest"])
+
+
+def _await_check(grace: float = FINISH_GRACE_S) -> None:
+    """Wait a beat for an in-flight check, at most `grace`, and only ever once. Needed because a
+    short command (`slab --version`, a help screen) finishes in ~30ms and would exit before the fetch
+    completed — leaving the cache permanently empty and the nudge permanently silent. Paid only on the
+    once-a-day run that actually checks; a slower check is abandoned (it's a daemon thread)."""
+    global _awaited
+    if _thread is None or _awaited:
+        return
+    _awaited = True
+    _thread.join(grace)
+
+
+def pending_notice() -> str | None:
+    """The nudge for this run — from this run's own check if it landed, else the cache. No network."""
+    if checks_disabled():
+        return None
+    latest = _fetched["latest"] if "latest" in _fetched else read_cache().get("latest")
+    return notice_text(current_version(), latest if isinstance(latest, str) else None)
+
+
+def print_notice() -> None:
+    """Print the nudge, if there is one. Call last, on the way out of `main()`.
+
+    The wait happens even when nothing will be printed, so a piped run still refreshes the cache for
+    the next interactive one. Printing itself is terminal-only: appended to redirected output the
+    nudge would be noise in someone's file, not a helpful hint."""
+    _await_check()
+    if not console.is_terminal:
+        return
+    notice = pending_notice()
+    if notice:
+        console.print(Text.from_markup(notice))