utils/gatelock
Krzysztof kuhy Rudnicki 3078d28fea Clear red CI: file length, gatelock gate, pin
gatelock 0.15.1: error_report split into _error_spool, no noqa,
INSTALLED holder replaces the module global. Dart app_errors tests
split under 250 lines. rtdb_relay dart pins crdt_sync_flutter 0.9.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:25:52 +01:00
..
docs Add the shared markdown-naming gate and migrate utils' own docs 2026-08-24 15:53:12 +02:00
gatelock Clear red CI: file length, gatelock gate, pin 2026-11-17 22:25:52 +01:00
scripts gatelock 0.13.0: locks stay clickable together 2026-11-11 12:49:40 +01:00
.pre-commit-config.yaml pylint 4.1.4, one job; focus_project deps 2026-11-16 08:58:01 +01:00
LICENSE Initial gatelock: shared lock-window + HMAC log-integrity backend 2026-06-19 17:39:44 +02:00
pyproject.toml Clear red CI: file length, gatelock gate, pin 2026-11-17 22:25:52 +01:00
README.md gatelock 0.15.0: error and slow-wait reporter 2026-11-17 21:51:18 +01:00
requirements.txt Bump deps; pnpm 12.21.0; sickdays 0.5.5 2026-11-16 08:58:01 +01:00

gatelock

Shared fullscreen lock-window + HMAC log-integrity backend, extracted from three personal automation tools that each independently implemented "lock the screen with a blocking overlay until a condition is met": diet_guard, wake_alarm, and screen-locker.

Why

All three reimplemented the same tkinter fullscreen mechanics (overrideredirect, input grab, VT-switch disable) at different levels of maturity, and the HMAC-signed-state module had already been hand-copied between two of them because they live in separate repos. gatelock is the one place that logic now lives.

Install

pip install "gatelock @ git+https://github.com/kuhyx/utils@gatelock-v0.1.1#subdirectory=gatelock"

Usage

import tkinter as tk
from gatelock import GateRoot, LockConfig, LockWindow

class MyGate:
    def __init__(self, *, demo_mode: bool) -> None:
        self.root = GateRoot()
        self.root.on_callback_error = self._handle_callback_error
        config = LockConfig(mode="soft" if demo_mode else "hard")
        self._lock = LockWindow(self.root, config, hooks=self)
        self._lock.setup()
        # ... build your widgets ...
        self._lock.grab_input()

    def on_focus_ready(self) -> None:
        self.my_entry.focus_force()

    def on_callback_error(self) -> None:
        self.close()

    def on_close(self) -> None:
        ...  # release any hardware/state held while locked

    def close(self) -> None:
        self._lock.close()

    def run(self) -> None:
        self._lock.run()

LockConfig's mode preset bundles the common combination ("soft" = topmost only, typeable, WM-escapable; "hard" = overrideredirect + global grab + VT-disable). overrideredirect and the grab=GrabPolicy(kind=..., disable_vt=..., retry_ms=...) axes can be set explicitly to reproduce a consumer's exact prior behavior where it diverges from the preset. Colours, type scale and spacing are the palette, typography and spacing records (gatelock.LockPalette etc.), overridden as a unit.

gatelock.log_integrity ports the HMAC-signed state module used by all three projects; DEFAULT_HMAC_KEY_FILE (/etc/workout-locker/hmac.key) is unchanged so existing signed history keeps verifying.

gatelock.morning_session.morning_skip is the one reader of wake-alarm's signed morning_session.json (the wake-early carrot: no lock until the signed exempt_until, 11:00 for a morning completed in time). screen-locker, leetcode-guard and book-guard all call it; the policy itself stays in wake-alarm. The arming run waits up to 180 s for a freshly booted PC's refresher (status paths never wait). Path and retry budget are arguments so each consumer's tests keep redirecting their own constant.

gatelock.corner_strip is the top-right always-on-top status strip for a gate that is stood down but not done (build_corner_strip, CornerStrip, StripContent, corner_rect, corner_geometry). It never grabs input; its tick ends when the owner's supply returns None.

gatelock.watch_credit(root, paths, is_done, on_credit, poll_ms=3000) lets an open lock window notice a credit that landed while it was up (a workout or meal logged elsewhere). One stat per path per poll on the Tk after loop; the owner's is_done() runs only on the first poll and when a path's (mtime, size, inode) changed; True calls on_credit (the window's normal close) and stops. A raising is_done/on_credit or an unreadable path is logged and retried (fail closed). Pass poll_ms of 3000 or less: an open window should notice inside ~10 s. Generalises screen-locker's _credit_watch.

gatelock.night_lockdown.evening_lockdown_today answers "has tonight's evening night-lockdown already happened?" from night-lockdown's /var/lib/night-lockdown/locked_at_epoch (local date today, local time

= 12:00; the 04:01 morning re-lock does not count). Earner gates (screen-locker's workout lock, leetcode-guard, book-guard) opt in and do not re-arm for the rest of such a day; diet-guard does not. Missing or garbage means "no lockdown" (garbage warns), so the gate locks as before.

gatelock.held_grabs(claims_dir=None) -> tuple[Claim, ...] answers "is a locker's X grab ACTUALLY held right now?": live claims (flock-proved) whose grab_held is true and whose declared grab is not none. grab_held turns true only after grab_set/grab_set_global succeeded, follows each recovery tick, and is cleared/restored around a deliberate release via LockWindow.report_grab_held(held=...) (or Arbiter.set_grab_held) -- leetcode-guard's study mode. It is rewritten in place under the owner's flock. A claim from a pre-0.11 writer has no key and reads as grab != "none". Root has no XDG_RUNTIME_DIR, so a root reader passes the user's dir (/run/user/1000/gatelock/claims).

LockWindow yields to a system credential prompt that holds the X grab. If the global grab stays unobtainable for more than 2 s AND a mapped window whose WM_CLASS is in gatelock._prompt_names.SYSTEM_PROMPT_CLASSES (gcr-prompter, pinentry*, polkit agents, ssh-askpass variants) is on screen, that prompt's top-level window is raised above the lock and the lock's periodic re-raise stops covering it while it stays mapped. The lock stays mapped, VT switching stays disabled and the grab keeps being retried; once the grab is taken the lock is back on top. Any other grab holder (a fullscreen game) never gets this. scripts/verify_prompt_yield.py proves it on a private Xvfb (never :0).

Lockers that start together do not fight. wait_for_turn waits STARTUP_GRACE_SECONDS (1.5 s) after publish() before its first check, so simultaneous starters see each other. An armed lock also steps back (_stepback) when a strictly higher-ranked, live claim that locks at least as firmly appears later: it hides, releases the grab and its holder lock (the claim stays, so lower ranks keep queueing), waits windowless, and re-arms fully once nothing outranks it. scripts/verify_all_lockers.py checks this with five real processes on a private Xvfb.

Error and slow-wait reporting

gatelock.error_report is the Python reporter of the shared app-errors pipeline (utils DOCS-app-errors.md). Call it once at start-up, then watch the Tk loop:

from gatelock import error_report

rep = error_report.install("leetcode-guard", "kuhyx/leetcode-guard")
error_report.watch_stalls(root, rep)       # a frozen loop over 1 s -> perf.slow
with rep.wait("coach.load"):               # or rep.begin(...).end() across callbacks
    ...

Uncaught, thread and Tk callback errors and waits over 1 s go to ~/.local/state/app-errors-spool/<app>.jsonl. The app-errors ingest timer turns them into board tickets. Nothing shows on screen.

Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest
pre-commit install && pre-commit install --hook-type pre-push