pendify 0.1.0__py3-none-any.whl

pendify/watcher.py

@@ -0,0 +1,348 @@
+"""The watcher of the game client: the loop of S:728-800 as a class.
+
+Everything that touches the world is injected: the credentials reader, the address builder, the HTTP
+getter and poster, the clock, the wall clock, the sleep, the random delay, the alert and the console.
+Its `alert` is an Alerter: snapshot() reads its last_ping(). One step() is one turn of the script's loop
+and answers the pause before the next; run() is the loop around it. The script's 15 s sleep after a ready
+check (S:778, S:793) is a hold on the injected clock, so a stop never waits for it. The arrival of
+InProgress after a read of another phase is the loading screen: it beeps on the PC only, once per game, and
+starts a watch that asks the game's own loopback port its clock at most once a second. The clock above zero
+is the match's true start: a beep and match_started. A game that never answers its clock is announced after
+120 s of the watch with InProgress read; a read of a boundary phase, or 120 s with no client, ends the watch
+with no alert. A reconnect is the same game. The console gets fixed lines only: no phase, no port, no clock,
+no token.
+
+pause() and resume() come from the page's thread and only set or clear an event; the loop honors it on its own
+thread. While paused run() makes no step, so nothing reads the client's files or process, its port or the game's
+port; the first paused turn forgets the client, the watch, the hold and the start latch, and the first turn after
+a resume is a fresh connection, so a game already under way then alerts nothing. Each pause is counted, and the loop
+rests for every count it has not honored, so a pause and a resume that both land inside one sleep or one step still
+rest it once. A pause that lands inside a step posts no accept after the delay and starts no alert, and its started
+line is not said. The pause lives in memory only: every start is active.
+
+The log (lane pclog): a ring of the last LOG_LINES events, each (seq, at, kind, detail), noted where the console line
+of the same moment is said, the ping's result through the Alerter's listen at the ping's own time; seq rises by one
+from 1 and never repeats in a run. events() answers a copy for the page. It lives in memory only, as the pause does.
+"""
+import collections
+import json
+import random
+import threading
+import time
+
+from . import client, worker
+
+IN_PROGRESS, READY_CHECK, RECONNECT = "InProgress", "ReadyCheck", "Reconnect"
+# The phases that end or precede a game: only a read of one of them resets the start latch.
+GAME_BOUNDARY_PHASES = frozenset({"None", "Lobby", "Matchmaking", READY_CHECK, "ChampSelect", "EndOfGame",
+                                  "PreEndOfGame", "WaitingForStats"})
+ACCEPT_DELAY = (1.0, 2.5)  # S:136
+HOLD_SECONDS = 15.0  # S:778, S:793
+STEP_PAUSE = 0.3  # S:799
+NO_CLIENT_PAUSE = 3.0  # S:739
+LIVE_POLL_SECONDS = 1.0  # the game's clock is asked at most once a second during the watch
+LIVE_FALLBACK_SECONDS = 120.0  # restarted by each clock not above zero, the wait announces a game giving no clock
+QUEUE_FOUND, MATCH_STARTED = worker.KINDS
+LOG_LINES = 50  # the events the log keeps, the newest
+
+CONNECTED_LINE = "connected to the game client"
+LOST_LINE = "lost the game client, looking for it again"
+ACCEPTING_LINE = "match found: accepting"
+ACCEPTED_LINE = "match found: accepted"
+DRY_LINE = "match found: not accepting (--dry)"
+STEP_FAILED_LINE = "watcher: a step failed ({}), looking for the game client again"
+LOADING_LINE = "loading screen: waiting for the match to start"
+STARTED_LINE = "match started: alerting"
+STARTED_ON_WAIT_LINE = "match started: the game gave no clock, alerting on the wait"
+PAUSED_LINE = "paused: not reading the game client"
+RESUMED_LINE = "resumed: looking for the game client again"
+
+WAITING, CONNECTED = "waiting", "connected"
+_ALERT_NAMES = {QUEUE_FOUND: "queue", MATCH_STARTED: "started"}
+LOADING = "loading"  # the last alert's name at the loading screen, said on the PC only
+
+
+def accept_delay():
+    """A delay drawn inside the script's two bounds (S:780)."""
+    return random.uniform(*ACCEPT_DELAY)
+
+
+def _print(line):
+    print(line, flush=True)
+
+
+def _phase(raw):
+    """The phase the client answered, a JSON string, or None for anything else."""
+    try:
+        phase = json.loads(raw.decode("utf-8"))
+    except ValueError:  # a body that is not JSON; UnicodeDecodeError is a ValueError
+        return None
+    return phase if isinstance(phase, str) else None
+
+
+class Watcher:
+    def __init__(self, credentials, alert, *, accept=True, addresses=client.real_addresses, get=client.get,
+                 post=client.post, clock=time.monotonic, wall=time.time, sleep=None, delay=accept_delay,
+                 log=None, stop=None, live=client.real_live_address, game_clock=client.game_clock):
+        self._credentials, self._alert, self._accept = credentials, alert, accept
+        self._addresses, self._get, self._post = addresses, get, post
+        self._live, self._game_clock = live, game_clock
+        self._clock, self._wall, self._delay = clock, wall, delay
+        self._stop = stop if stop is not None else threading.Event()
+        self._sleep = sleep if sleep is not None else self._stop.wait
+        self._log = log if log is not None else _print
+        self._lock = threading.Lock()
+        self._found = None
+        self._last_phase = None
+        self._start_alerted = False
+        self._hold_until = None
+        self._client_state = WAITING
+        self._last_alert = None
+        self._watch_since = None  # the injected clock when the loading screen opened; None with no watch on
+        self._next_live = None  # the injected clock from which the game's clock may be asked again
+        self._paused = threading.Event()  # set and cleared by the page's thread, read by the loop
+        self._pauses = 0  # every pause counted by the page's thread, under the lock; the loop compares it
+        self._honored = 0  # the count of the last pause the loop has rested for; read and written by it only
+        self._resting = False  # the loop's own record that it has acted on a pause; read and written by it only
+        self._events = collections.deque(maxlen=LOG_LINES)  # the log, (seq, at, kind, detail); under the lock
+        self._seq = 0  # the last event's seq, under the lock; never reset in a run of the program
+        self._ran = False  # run() has noted the start; read and written by the loop only
+        self._waiting_due = True  # the next turn with no client notes waiting: after the start and after a resume
+        listen = getattr(alert, "listen", None)
+        if callable(listen):  # an Alerter tells each ping's result; the tests' plain fakes have no listen
+            listen(self._on_ping)
+
+    def stop(self):
+        self._stop.set()
+
+    def pause(self):
+        """Stop reading the game; callable from any thread, honored by the loop at its next turn. The event is set
+        before the count moves, so a loop that reads the new count reads the event of this pause or of a later
+        resume."""
+        self._paused.set()
+        with self._lock:
+            self._pauses += 1
+
+    def resume(self):
+        """Read the game again from the next turn, as a fresh connection; callable from any thread."""
+        self._paused.clear()
+
+    @property
+    def paused(self):
+        return self._paused.is_set()
+
+    def run(self):
+        """The loop: a step, then its pause, until stopped. A step that breaks is said by its type and the
+        client is looked for again, so the watcher never ends while the page says it runs."""
+        while not self._stop.is_set():
+            if not self._ran:
+                self._ran = True
+                self._note("started")
+            with self._lock:
+                pauses = self._pauses
+            paused = self._paused.is_set()
+            # A pause not yet honored rests the loop even when a resume has already cleared the event.
+            if (paused or pauses != self._honored) and not self._resting:
+                self._rest()
+            self._honored = pauses
+            if paused:  # no step: nothing is read while paused
+                pause = STEP_PAUSE
+            else:
+                if self._resting:
+                    self._resting = False
+                    self._log(RESUMED_LINE)
+                    self._note("resumed")
+                    self._waiting_due = True
+                try:
+                    pause = self.step()
+                except Exception as failure:
+                    connected = self._found is not None  # the log says lost only of a client this turn had
+                    self._log(STEP_FAILED_LINE.format(type(failure).__name__))
+                    if connected:
+                        self._note("lost")
+                    self._forget()
+                    pause = NO_CLIENT_PAUSE
+            if self._stop.is_set():
+                break
+            self._sleep(pause)
+
+    def step(self):
+        """One turn of S:733-799; the pause before the next turn."""
+        if self._hold_until is not None:
+            if self._clock() < self._hold_until:
+                return STEP_PAUSE
+            self._hold_until = None
+        if self._found is None:
+            found = self._credentials.read()
+            if found is None:
+                if self._waiting_due:  # once per waiting period; never right after lost, whose line says the search
+                    self._waiting_due = False
+                    self._note(WAITING)
+                self._watch(None)  # the watch outlives a lost client
+                return NO_CLIENT_PAUSE
+            self._found = found
+            self._set_client(CONNECTED)
+            self._log(CONNECTED_LINE)
+            self._note(CONNECTED)
+            self._waiting_due = False
+        base = self._addresses(self._found.port)
+        token = self._found.token
+        phase = None
+        try:
+            status, raw = self._get(base + client.PHASE_PATH, token, client.CLIENT_TIMEOUT)
+            if status == 200:
+                phase = _phase(raw)
+                if phase is None:  # requests raises a RequestException on a body that is not JSON (S:750)
+                    raise client.ClientUnreachable("ValueError")
+                self._on_phase(phase, base, token)
+        except client.ClientUnreachable:  # S:796-798
+            self._log(LOST_LINE)
+            self._note("lost")
+            self._forget()
+            phase = None
+        self._watch(phase)
+        return STEP_PAUSE
+
+    def snapshot(self):
+        """The watcher's state in plain values: the client waiting or connected, the last phase read as the
+        client names it (None before any), the last alert and when, and the last ping's result and when."""
+        ping, ping_at = self._alert.last_ping()
+        with self._lock:
+            name, at = self._last_alert or (None, None)
+            return {"client": self._client_state, "phase": self._last_phase, "alert": name, "at": at,
+                    "pingResult": ping, "pingAt": ping_at, "paused": self._paused.is_set()}
+
+    def events(self):
+        """The log: the last LOG_LINES events of this run, oldest first, as (seq, at, kind, detail) in a list the
+        caller may keep or change."""
+        with self._lock:
+            return list(self._events)
+
+    def _note(self, kind, detail=None, at=None):
+        """One event in the log: the next seq, the wall time unless the event brings its own, the kind and its
+        detail; under the lock events() reads with, since a ping is noted from the Alerter's thread."""
+        at = self._wall() if at is None else at
+        with self._lock:
+            self._seq += 1
+            self._events.append((self._seq, at, kind, detail))
+
+    def _on_ping(self, name, at):
+        """The Alerter's listener: a ping's result name and its own time."""
+        self._note("ping", name, at)
+
+    def _on_phase(self, phase, base, token):
+        # An arrival is InProgress after a read of another phase. The first read is not one: an alert for a game
+        # already under way says nothing (S:755-757). A first read of InProgress or of Reconnect is such a game, so
+        # it sets the latch, and the InProgress that follows (after a Reconnect of that same game, or the one the
+        # Reconnect ends in) says nothing either. Reconnect, InProgress or an unknown phase keeps the latch.
+        # A boundary ends a watch with no alert; a first read of InProgress or Reconnect leaves a running one on.
+        # The log notes a phase that differs from the last read, before what it leads to (the accept, the loading).
+        if phase != self._last_phase:
+            self._note("phase", phase)
+        if phase in GAME_BOUNDARY_PHASES:
+            self._start_alerted = False
+            self._watch_since = None
+        elif self._last_phase is None and phase in (IN_PROGRESS, RECONNECT):
+            self._start_alerted = True
+        elif self._last_phase not in (None, IN_PROGRESS) and not self._start_alerted:
+            self._start_alerted = True  # before the alert: an alert that breaks is not made again for this game
+            self._loading()
+        with self._lock:
+            self._last_phase = phase
+        if phase == READY_CHECK:
+            self._ready_check(base, token)
+
+    def _ready_check(self, base, token):
+        if not self._accept:  # the script's --dry (S:773-777)
+            self._log(DRY_LINE)
+            self._fire(QUEUE_FOUND)  # S:776
+            self._hold()
+            return
+        wait = self._delay() if ACCEPT_DELAY[1] else 0
+        self._log(ACCEPTING_LINE)
+        if wait:
+            self._sleep(wait)
+        if self._stop.is_set():  # stopped during the delay: the script's Ctrl+C posts nothing either
+            return
+        if self._paused.is_set():  # paused during the delay: no accept, and the next turn rests
+            return
+        status = self._post(base + client.ACCEPT_PATH, token, client.CLIENT_TIMEOUT)
+        if status in (200, 204):
+            self._log(ACCEPTED_LINE)
+            self._note("accepted")
+            self._fire(QUEUE_FOUND)  # S:790
+            self._hold()
+
+    def _loading(self):
+        """The loading screen, said on the PC only; the watch for the true start begins, its first read due now.
+        Nothing while paused."""
+        if self._paused.is_set():
+            return
+        self._alert.sound()
+        with self._lock:
+            self._last_alert = (LOADING, self._wall())
+        self._log(LOADING_LINE)
+        self._note(LOADING)
+        self._watch_since = self._next_live = self._clock()
+
+    def _watch(self, phase):
+        """One turn of the watch: the game's clock asked when due, its value above zero the start and any other
+        number a restart of the wait; then the wait, which fires on a step whose phase read was InProgress and ends
+        with no alert with no client."""
+        if self._watch_since is None:
+            return
+        now = self._clock()
+        if now >= self._next_live:
+            self._next_live = now + LIVE_POLL_SECONDS
+            seconds = self._game_clock(self._live())
+            if seconds is not None and seconds > 0:
+                self._watch_since = None
+                self._fire(MATCH_STARTED, STARTED_LINE)
+                return
+            if seconds is not None:
+                self._watch_since = now
+        if now >= self._watch_since + LIVE_FALLBACK_SECONDS:
+            if phase == IN_PROGRESS:
+                self._watch_since = None
+                self._fire(MATCH_STARTED, STARTED_ON_WAIT_LINE)
+            elif self._found is None:
+                self._watch_since = None
+
+    def _hold(self):
+        self._hold_until = self._clock() + HOLD_SECONDS
+
+    def _fire(self, kind, line=None):
+        """The alert of `kind`, its console `line` said first when one is given; nothing, the line included,
+        while paused."""
+        if self._paused.is_set():  # an alert handed to the Alerter before the pause is delivered; none starts in it
+            return
+        if line is not None:
+            self._log(line)
+        if kind == MATCH_STARTED:  # noted on the kind, so a start fired with no line is still in the log
+            self._note("match_started")
+        with self._lock:
+            self._last_alert = (_ALERT_NAMES[kind], self._wall())
+        self._alert(kind)
+
+    def _forget(self):
+        # S:755-757 is per connection: a fresh client already InProgress at its first read alerts nothing.
+        # A running watch is left on: the game's clock is proof by itself.
+        self._found = None
+        with self._lock:
+            self._last_phase = None
+        self._set_client(WAITING)
+
+    def _rest(self):
+        """The first paused turn: the client, the watch, the hold and the start latch are dropped, so the turn
+        after a resume is a fresh connection."""
+        self._resting = True
+        self._forget()
+        self._watch_since = self._next_live = None
+        self._hold_until = None
+        self._start_alerted = False
+        self._log(PAUSED_LINE)
+        self._note("paused")
+
+    def _set_client(self, value):
+        with self._lock:
+            self._client_state = value

pendify/worker.py

@@ -0,0 +1,159 @@
+"""The Worker's two unauthenticated link routes, check (design P5) and ping (S:282-308), on urllib only.
+
+Nothing either function prints, logs or raises carries the secret or the link id: failures are named by
+an HTTP status or an exception type, results hide their values from repr, and a refused input is refused
+with a fixed sentence before any call.
+"""
+import importlib.metadata
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+
+from . import codes
+
+# The host of the ping address the owner's script uses (S:84).
+BASE_URL = "https://followapp-ai-proxy.niklerk23.workers.dev"
+CHECK_PATH = "/v1/link-check"
+PING_PATH = "/v1/link-ping"
+TIMEOUT_SECONDS = 5
+# The two kinds this program sends, the contract with the Worker; the only place they are written.
+KINDS = ("lol_queue_found", "lol_match_started")
+_MAX_ANSWER_BYTES = 64 * 1024
+_LOOPBACK_HOSTS = ("127.0.0.1", "localhost")
+
+
+def _user_agent():
+    try:
+        version = importlib.metadata.version("pendify")
+    except Exception:  # never stop the import: not installed (the tests, a checkout) or a half-written dist-info
+        version = None
+    # The fallback when the lookup failed or read no version (None or blank from a broken dist-info).
+    return f"pendify/{version.strip()}" if isinstance(version, str) and version.strip() else "pendify/source"
+
+
+# The program names itself in every request: the edge in front of the Worker refuses urllib's default
+# signature (Python-urllib/<version>) with error 1010 before the Worker reads the request.
+USER_AGENT = _user_agent()
+
+
+@dataclass(frozen=True)
+class Linked:
+    link_id: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class Refused:
+    pass
+
+
+@dataclass(frozen=True)
+class Throttled:
+    pass
+
+
+@dataclass(frozen=True)
+class Failed:
+    reason: str
+
+
+@dataclass(frozen=True)
+class Sent:
+    pass
+
+
+@dataclass(frozen=True)
+class NotDelivered:
+    status: int
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """A redirect answer is returned as it is (an HTTPError), never followed."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def loopback_base(value):
+    """A replacement Worker address for test runs: only http://127.0.0.1:<port> or http://localhost:<port>."""
+    parts = urllib.parse.urlsplit(value) if isinstance(value, str) else None
+    try:
+        port = parts.port if parts else None
+    except ValueError:
+        port = None
+    if (parts is None or parts.scheme != "http" or parts.hostname not in _LOOPBACK_HOSTS or port is None
+            or parts.username is not None or parts.path not in ("", "/") or parts.query or parts.fragment
+            or parts.netloc != f"{parts.hostname}:{port}"):
+        raise ValueError("a replacement Worker address must be http://127.0.0.1:<port> or http://localhost:<port>")
+    return f"http://{parts.hostname}:{port}"
+
+
+def _post(base, path, payload, timeout):
+    """(status, answer dict or None), or a Failed naming the exception type."""
+    request = urllib.request.Request(
+        base + path, data=json.dumps(payload, separators=(",", ":")).encode("utf-8"), method="POST",
+        headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": USER_AGENT})
+    handlers = [_NoRedirect()]
+    if urllib.parse.urlsplit(base).hostname in _LOOPBACK_HOSTS:
+        handlers.append(urllib.request.ProxyHandler({}))  # a loopback address never goes through a proxy
+    opener = urllib.request.build_opener(*handlers)
+    try:
+        with opener.open(request, timeout=timeout) as response:
+            status, raw = response.status, response.read(_MAX_ANSWER_BYTES)
+    except urllib.error.HTTPError as answer:
+        with answer:
+            status, raw = answer.code, answer.read(_MAX_ANSWER_BYTES)
+    except urllib.error.URLError as failure:
+        reason = failure.reason
+        return Failed(type(reason).__name__ if isinstance(reason, BaseException) else type(failure).__name__)
+    except (OSError, ValueError) as failure:  # a timeout while reading, a reset, a malformed answer
+        return Failed(type(failure).__name__)
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except ValueError:
+        body = None
+    return status, body if isinstance(body, dict) else None
+
+
+def _error_code(body):
+    error = body.get("error") if body else None
+    return error.get("code") if isinstance(error, dict) else None
+
+
+def check(secret, *, base=BASE_URL, timeout=TIMEOUT_SECONDS):
+    """POST {secret} to the link check: Linked(link id), Refused, Throttled or Failed."""
+    normal = codes.normalize(secret)
+    if normal is None:
+        raise ValueError("the secret is not twelve symbols")
+    answer = _post(base, CHECK_PATH, {"secret": normal}, timeout)
+    if isinstance(answer, Failed):
+        return answer
+    status, body = answer
+    link_id = body.get("linkId") if body else None
+    if status == 200 and isinstance(link_id, str) and codes.normalize(link_id) == link_id:
+        return Linked(link_id)
+    code = _error_code(body)
+    if code == "link_refused":
+        return Refused()
+    if code == "throttled":
+        return Throttled()
+    return Failed(f"HTTP {status}")
+
+
+def ping(link_id, secret, kind, *, base=BASE_URL, timeout=TIMEOUT_SECONDS):
+    """POST {linkId, secret, kind} to the link ping: Sent, Refused, NotDelivered(status) or Failed."""
+    if kind not in KINDS:
+        raise ValueError("the kind is not one of the two this program sends")
+    normal_link_id, normal_secret = codes.normalize(link_id), codes.normalize(secret)
+    if normal_link_id is None or normal_secret is None:
+        raise ValueError("the stored pair is not two values of twelve symbols")
+    answer = _post(base, PING_PATH, {"linkId": normal_link_id, "secret": normal_secret, "kind": kind}, timeout)
+    if isinstance(answer, Failed):
+        return answer
+    status, body = answer
+    if 200 <= status < 400 and body and body.get("sent"):
+        return Sent()
+    if _error_code(body) == "link_refused":
+        return Refused()
+    return NotDelivered(status)

pendify-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pendify
+Version: 0.1.0
+Summary: Pairs this PC with a phone account by a QR on a loopback page and sends it two kinds of alerts.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ElkinDev/PendiFy
+Project-URL: Source, https://github.com/ElkinDev/PendiFy
+Keywords: notifications,alerts,phone,qr,pairing,windows
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PendiFy
+
+## Español
+
+Un programa pequeño para Windows que avisa en tu teléfono cuando se encuentra tu partida y cuando empieza.
+Se enlaza una sola vez con tu cuenta de Pendi leyendo un código QR, sin crear ninguna cuenta nueva.
+Es gratis, no pide permisos de administrador y solo usa Python.
+
+### Instalar
+
+Pulsa Windows + R, pega esta línea completa y pulsa Enter. También sirve en PowerShell o en el Símbolo del sistema.
+
+    powershell -NoExit -NoProfile -ExecutionPolicy Bypass -Command "ri ~\pendify-install.ps1 -ea 0; irm https://raw.githubusercontent.com/ElkinDev/PendiFy/main/install.ps1 -OutFile ~\pendify-install.ps1; ~\pendify-install.ps1"
+
+La línea guarda el instalador como `pendify-install.ps1` en tu carpeta de usuario y lo ejecuta desde ahí; puedes borrar ese archivo cuando termine.
+
+La ventana queda abierta al terminar para que leas el resultado; ciérrala cuando acabe.
+
+Si Windows dice que no puede acceder al archivo o el antivirus detiene la línea, no se instaló nada: actualiza las definiciones del antivirus y vuelve a intentarlo, o descarga `install.ps1` desde la página del repositorio, haz clic en él con el botón derecho y elige «Ejecutar con PowerShell».
+
+Si ves "'irm' no se reconoce como un comando interno o externo", pegaste solo la parte corta en el Símbolo del sistema: usa la línea completa de arriba.
+
+El instalador busca Python 3.10 o más nuevo; si no lo hay lo instala con winget solo para tu usuario, o te indica https://www.python.org/downloads/ cuando winget no existe. Después instala PendiFy con pip, deja un acceso directo `PendiFy` en el Escritorio y en el menú Inicio, y lo inicia.
+
+En PowerShell: para ver qué haría sin cambiar nada: `$env:PENDIFY_DRYRUN = "1"` antes de pegar la línea. Para no iniciarlo al final: `$env:PENDIFY_NOSTART = "1"`.
+
+Otra forma, sin ejecutar ningún script: si el PC ya tiene Python 3.10 o más nuevo, o si en él no se permite ejecutar scripts, instálalo con pip e inícialo:
+
+    python -m pip install --upgrade pendify
+    python -m pendify
+
+Si Windows responde que no encuentra `python`, usa `py` en su lugar: `py -m pip install --upgrade pendify` y `py -m pendify`.
+
+Así no se crean los accesos directos en el Escritorio ni en el menú Inicio, y el inicio con Windows queda en el interruptor de la página. Para actualizar, pulsa «Salir» en la página, ejecuta otra vez la misma línea de pip y vuelve a iniciarlo. Para quitarlo, apaga primero el interruptor «Iniciar con Windows» en la página, pulsa «Salir» y después ejecuta `python -m pip uninstall pendify`. La configuración en `%APPDATA%\pendify`, con el enlace con el teléfono, se queda; puedes borrar esa carpeta a mano.
+
+### Enlazar
+
+Al iniciarse, el navegador abre una página local con un código QR. Escanéalo con la cámara del teléfono: se abre la app Pendi y te pide confirmar el enlace. La página muestra cuando el enlace quedó hecho.
+
+El código QR y la clave se muestran durante un minuto al pulsar «Mostrar el código» y luego se ocultan de nuevo.
+
+El botón de arriba a la derecha cambia entre el tema claro y el oscuro, y el programa guarda la elección para la próxima vez.
+
+### Iniciar, detener, desinstalar
+
+- Iniciar: el acceso directo `PendiFy`, o `pythonw -m pendify`, que es lo que ejecuta el acceso directo; sin consola, si ya está abierto o no puede iniciarse te lo dice en una ventana. Para verlo en una consola: `python -m pendify`.
+- Detener: pulsa «Salir» en la página del programa; si no la tienes abierta, iniciarlo otra vez la abre. Como último recurso, cierra el proceso `pythonw.exe` en el Administrador de tareas.
+- Pausar: «Pausar avisos», en la tarjeta «Este PC» de la página, deja de leer el cliente del juego: no acepta partidas ni avisa a tu teléfono, y la página sigue abierta. «Reanudar avisos» vuelve a leerlo. La pausa no se guarda: cada vez que el programa se inicia, empieza activo.
+- Iniciar con Windows: el interruptor «Iniciar con Windows», en la misma tarjeta, está apagado hasta que lo enciendas. Encendido, el programa empieza solo al iniciar sesión en Windows, solo para tu usuario y sin abrir el navegador ni la página.
+- Actividad: la tarjeta «Actividad» de la página lista lo que el programa hizo desde que empezó: el cliente del juego encontrado y perdido, cada fase, la partida aceptada y el aviso enviado. Guarda las últimas 50 líneas, solo en memoria.
+- Idioma: la página sigue el idioma del navegador hasta que eliges ES o EN con el selector de arriba, y la elección se guarda para este PC.
+- Desinstalar: pega `powershell -NoExit -NoProfile -ExecutionPolicy Bypass -Command "ri ~\pendify-uninstall.ps1 -ea 0; irm https://raw.githubusercontent.com/ElkinDev/PendiFy/main/uninstall.ps1 -OutFile ~\pendify-uninstall.ps1; ~\pendify-uninstall.ps1"` igual que la línea de instalación; deja `pendify-uninstall.ps1` en tu carpeta de usuario, que puedes borrar. Quita el paquete del mismo Python que lo instaló, comprueba que ya no está, quita los dos accesos directos y quita el inicio con Windows si estaba encendido; la configuración en `%APPDATA%\pendify` se queda y te dice dónde está.
+- Actualizar: pulsa «Salir» en la página y vuelve a pegar la línea de instalación; instala la última versión y conserva la configuración y el enlace.
+
+### Qué envía y a quién
+
+Solo envía, al servicio de enlace de Pendi, el tipo de aviso (partida encontrada o partida empezada) junto con el identificador del enlace y el secreto de este PC, que viven en `%APPDATA%\pendify\config.json`. El servicio lo entrega a la cuenta que enlazaste. No envía tu nombre, tus partidas ni nada más del juego. Para saber cuándo empieza la partida lee el reloj del juego en este mismo PC, y no lo guarda ni lo envía.
+
+### `--dry`
+
+Con `--dry` el programa solo avisa y no acepta la partida por ti.
+
+Licencia: MIT
+
+## English
+
+A small Windows program that alerts your phone when your match is found and when it starts.
+It links once to your Pendi account by scanning a QR code, with no new account of any kind.
+It is free, needs no administrator rights and only uses Python.
+
+### Install
+
+Press Windows + R, paste this whole line and press Enter. It also works in PowerShell or the Command Prompt.
+
+    powershell -NoExit -NoProfile -ExecutionPolicy Bypass -Command "ri ~\pendify-install.ps1 -ea 0; irm https://raw.githubusercontent.com/ElkinDev/PendiFy/main/install.ps1 -OutFile ~\pendify-install.ps1; ~\pendify-install.ps1"
+
+The line saves the installer as `pendify-install.ps1` in your user folder and runs it from there; you can delete that file when it is done.
+
+The window stays open at the end so you can read the result; close it when it is done.
+
+If Windows says it cannot access the file or the antivirus stops the line, nothing was installed: update the antivirus definitions and try again, or download `install.ps1` from the repository page, click it with the right button and choose "Run with PowerShell".
+
+If you see "'irm' is not recognized as an internal or external command", you pasted only the short part into the Command Prompt: use the whole line above.
+
+The installer looks for Python 3.10 or newer; when there is none it installs it with winget for your user only, or points you to https://www.python.org/downloads/ when winget is missing. Then it installs PendiFy with pip, leaves a `PendiFy` shortcut on the Desktop and in the Start menu, and starts it.
+
+In PowerShell: to see what it would do without changing anything, set `$env:PENDIFY_DRYRUN = "1"` before pasting the line. To leave it stopped at the end, set `$env:PENDIFY_NOSTART = "1"`.
+
+Another way, with no script at all: on a PC that already has Python 3.10 or newer, or where scripts are not allowed, install it with pip and start it:
+
+    python -m pip install --upgrade pendify
+    python -m pendify
+
+If Windows answers that `python` was not found, use `py` in its place: `py -m pip install --upgrade pendify` and `py -m pendify`.
+
+This way leaves no shortcut on the Desktop or in the Start menu, and the start with Windows is the switch on the page. To update, press «Quit» on the page, run the same pip line again and start it again. To remove it, first turn off the «Start with Windows» switch on the page, press «Quit», then run `python -m pip uninstall pendify`. The configuration in `%APPDATA%\pendify`, with the link to the phone, stays; you can delete that folder by hand.
+
+### Link
+
+When it starts, the browser opens a local page with a QR code. Scan it with the phone's camera: the Pendi app opens and asks you to confirm the link. The page shows when the link is done.
+
+The QR code and the key show for a minute when «Show the code» is pressed, and then hide again.
+
+The button at the top right switches between the light and the dark theme, and the program keeps the choice for the next time.
+
+### Start, stop, uninstall
+
+- Start: the `PendiFy` shortcut, or `pythonw -m pendify`, which is what the shortcut runs; with no console, it tells you in a window when it is already running or cannot start. To see it in a console: `python -m pendify`.
+- Stop: press «Quit» on the program's page; if it is not open, starting the program again opens it. As a last resort, end the `pythonw.exe` process in Task Manager.
+- Pause: «Pause alerts», on the page's «This PC» card, stops reading the game client: it accepts no match and sends no alert to your phone, and the page stays open. «Resume alerts» reads it again. The pause is not kept: every start of the program is active again.
+- Start with Windows: the «Start with Windows» switch, on the same card, is off until you turn it on. When it is on, the program starts by itself when you sign in to Windows, for your user only, without opening the browser or the page.
+- Activity: the page's «Activity» card lists what the program did since it started: the game client found and lost, each phase, the match accepted and the alert sent. It keeps the last 50 lines, in memory only.
+- Language: the page follows the browser's language until you choose ES or EN with the switch at the top, and the choice is kept for this PC.
+- Uninstall: paste `powershell -NoExit -NoProfile -ExecutionPolicy Bypass -Command "ri ~\pendify-uninstall.ps1 -ea 0; irm https://raw.githubusercontent.com/ElkinDev/PendiFy/main/uninstall.ps1 -OutFile ~\pendify-uninstall.ps1; ~\pendify-uninstall.ps1"` the same way as the install line; it leaves `pendify-uninstall.ps1` in your user folder, which you can delete. It removes the package from the same Python that installed it, checks that it is gone, removes both shortcuts and removes the start with Windows when it is on; the configuration in `%APPDATA%\pendify` stays, and it tells you where it is.
+- Update: press "Quit" on the page and paste the install line again; it installs the latest version and keeps the configuration and the link.
+
+### What it sends and to whom
+
+It only sends, to Pendi's link service, the alert kind (match found or match started) together with the link id and this PC's secret, which live in `%APPDATA%\pendify\config.json`. The service delivers it to the account you linked. It sends no name, no match history and nothing else from the game. To tell when the match starts it reads the game's clock on this same PC, and neither keeps nor sends it.
+
+### `--dry`
+
+With `--dry` the program only alerts and never accepts the match for you.
+
+License: MIT
+
+## Developer commands
+
+    python -m pendify
+    python -m pendify ping <kind>
+
+The first loads the config, starts the page and opens it in the default browser, paired or not.
+It also watches the game client on this PC: when a match is found it accepts after a short random delay, beeps, and sends the found-match alert; when the loading screen starts it beeps, and when the match itself starts it beeps and sends the started alert.
+Add `--dry` to watch and alert without accepting. Add `--quiet` for the start by the system at logon, the line the start with Windows switch writes (`pythonw -m pendify --quiet`): it never opens the browser, a start that ends well shows no window, and a second quiet start prints `already running` and exits. One copy runs per config folder: a second start opens the page of the one that runs and exits. Ctrl+C stops the page and the watcher together.
+The second sends one alert with the stored pair and prints one line with the answer.
+
+Both commands take `--data-dir <dir>`, used instead of `%APPDATA%` (the config file lives in a folder under it), and `--worker <address>`, used instead of the pairing service's address and accepted only as `http://127.0.0.1:<port>` or `http://localhost:<port>`, so a test run never reaches the real service. `--client-lockfile <file>` replaces the game client's lockfile, with no read of the running processes, and the client it names is reached over plain http on 127.0.0.1, so a test run never reaches a real client.
+
+    python -m unittest discover -s tests -v