feat(cli): add daily PyPI update-check notice

- best-effort update notice on stderr, throttled once/day via ~/.webskrap cache
- stdlib only (urllib + importlib.metadata), no new dependency
- skips on WEBSKRAP_NO_UPDATE_CHECK, CI, and non-tty; never touches stdout
- bump version 0.5.7

Author: kacigaya

README.md

@@ -389,6 +389,11 @@ webskrap fetch https://amiunique.org/fr/fingerprint \
 
 Use repeated `--launch-arg=...` options for advanced browser flags.
 
+The CLI checks PyPI once a day (best-effort) and prints an "update available"
+notice to stderr when a newer `webskrap` is released. Set
+`WEBSKRAP_NO_UPDATE_CHECK=1` to disable it; it is also skipped under `CI` and when
+stderr is not a TTY.
+
 ## MCP server
 
 WebSkrap ships an optional Model Context Protocol server so MCP clients (Claude

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webskrap"
-version = "0.5.6"
+version = "0.5.7"
 description = "A Playwright-based Python scraping framework with coherent browser profiles and session controls."
 readme = "README.md"
 requires-python = ">=3.11"

src/webskrap/cli.py

@@ -2,8 +2,12 @@
 
 import asyncio
 import json
+import os
 import subprocess
 import sys
+import time
+import urllib.request
+from importlib import metadata
 from pathlib import Path
 from typing import Annotated, Literal
 
@@ -32,6 +36,69 @@
     (sys.executable, "-m", "playwright", "install", "chromium"),
     (sys.executable, "-m", "patchright", "install", "chromium"),
 )
+UPDATE_CHECK_URL = "https://pypi.org/pypi/webskrap/json"
+UPDATE_CHECK_INTERVAL = 86_400  # once per day
+UPDATE_CHECK_CACHE = Path.home() / ".webskrap" / "update-check.json"
+# ponytail: ~/.webskrap not XDG/APPDATA-aware; swap to platformdirs if that matters
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    # ponytail: naive X.Y.Z compare; swap to packaging.version if pre-release tags ever ship
+    try:
+        return tuple(map(int, latest.split("."))) > tuple(map(int, current.split(".")))
+    except ValueError:
+        return False
+
+
+def _check_for_update() -> None:
+    """Best-effort 'update available' notice. Never raises, never touches stdout."""
+    try:
+        if (
+            os.environ.get("WEBSKRAP_NO_UPDATE_CHECK")
+            or os.environ.get("CI")
+            or not sys.stderr.isatty()
+        ):
+            return
+
+        current = metadata.version("webskrap")
+        latest: str | None = None
+
+        try:
+            cached = json.loads(UPDATE_CHECK_CACHE.read_text())
+            if time.time() - cached["checked_at"] < UPDATE_CHECK_INTERVAL:
+                latest = cached["latest"]
+        except Exception:
+            latest = None
+
+        if latest is None:
+            fetched: str | None = None
+            try:
+                with urllib.request.urlopen(UPDATE_CHECK_URL, timeout=2) as response:
+                    fetched = json.load(response)["info"]["version"]
+            except Exception:
+                fetched = None
+            # Stamp the attempt either way so a PyPI outage can't cause hammering.
+            latest = fetched or current
+            try:
+                UPDATE_CHECK_CACHE.parent.mkdir(parents=True, exist_ok=True)
+                UPDATE_CHECK_CACHE.write_text(
+                    json.dumps({"checked_at": time.time(), "latest": latest})
+                )
+            except Exception:
+                pass
+
+        if _is_newer(latest, current):
+            Console(stderr=True, highlight=False).print(
+                f"[yellow]webskrap {latest} available[/] (you have {current}) — "
+                "upgrade: [bold]pip install -U webskrap[/]"
+            )
+    except Exception:
+        return
+
+
+@app.callback()
+def _main() -> None:
+    _check_for_update()
 
 
 @app.command("install")

tests/test_cli.py

@@ -210,3 +210,65 @@ def fake_run(command: tuple[str, ...], **_kwargs: Any) -> subprocess.CompletedPr
     assert "patchright" in result.output
     assert "install" in result.output
     assert "chromium" in result.output
+
+
+class _FakeResponse:
+    def __init__(self, version: str) -> None:
+        self._version = version
+
+    def __enter__(self) -> _FakeResponse:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return json.dumps({"info": {"version": self._version}}).encode()
+
+
+def test_is_newer_truth_table() -> None:
+    assert cli._is_newer("0.6.0", "0.5.6") is True
+    assert cli._is_newer("0.5.7", "0.5.6") is True
+    assert cli._is_newer("0.5.6", "0.5.6") is False
+    assert cli._is_newer("0.5.5", "0.5.6") is False
+    assert cli._is_newer("1.0.0rc1", "0.5.6") is False  # malformed -> False
+
+
+def _enable_update_check(monkeypatch: Any, tmp_path: Any) -> None:
+    monkeypatch.delenv("WEBSKRAP_NO_UPDATE_CHECK", raising=False)
+    monkeypatch.delenv("CI", raising=False)
+    monkeypatch.setattr(cli.sys.stderr, "isatty", lambda: True, raising=False)
+    monkeypatch.setattr(cli, "UPDATE_CHECK_CACHE", tmp_path / "update-check.json")
+    monkeypatch.setattr(cli.metadata, "version", lambda _name: "0.5.6")
+
+
+def test_update_check_opt_out_skips_network(monkeypatch: Any, tmp_path: Any) -> None:
+    _enable_update_check(monkeypatch, tmp_path)
+    monkeypatch.setenv("WEBSKRAP_NO_UPDATE_CHECK", "1")
+
+    def boom(*_a: Any, **_k: Any) -> Any:
+        raise AssertionError("network must not be called")
+
+    monkeypatch.setattr(cli.urllib.request, "urlopen", boom)
+    cli._check_for_update()  # no raise = pass
+
+
+def test_update_check_notifies_and_caches(monkeypatch: Any, tmp_path: Any, capsys: Any) -> None:
+    _enable_update_check(monkeypatch, tmp_path)
+    calls = {"n": 0}
+
+    def fake_urlopen(*_a: Any, **_k: Any) -> _FakeResponse:
+        calls["n"] += 1
+        return _FakeResponse("0.9.9")
+
+    monkeypatch.setattr(cli.urllib.request, "urlopen", fake_urlopen)
+
+    cli._check_for_update()
+    err = capsys.readouterr().err
+    assert "0.9.9 available" in err
+    assert "0.5.6" in err
+    assert (tmp_path / "update-check.json").exists()
+
+    # Fresh cache -> no second network call.
+    cli._check_for_update()
+    assert calls["n"] == 1