wake-alarm/CLAUDE.md

# CLAUDE.md — wake_alarm

## What this does

A weekend wake alarm: on alarm days (`ALARM_DAYS` in `_constants.py` — Mon,
Fri, Sat, Sun), the machine hibernates overnight and wakes itself via
`rtcwake` at the configured alarm time. `wake-alarm.service` then opens a
fullscreen Tk window that must be dismissed (with a typed challenge — see
`_challenges.py`), ramps fans to 100% via `wake-alarm-fans.sh`, plays audio
through whatever sink comes up after the monitor wakes, and optionally
toggles a TP-Link Tapo P110 smart plug via `python-kasa`.

## Scheduling — a per-minute timer, with hibernate as the fallback

The PC is **always on**. The alarm time comes from the phone, which can change
it at any hour, so nothing about the schedule may be baked in ahead of time.

**Primary path — `wake-alarm-trigger.timer`:**

1. The timer ticks every minute (`OnCalendar=*:*:00`, `Persistent=true`) and
   runs `python -m wake_alarm._trigger` — a short, stateless check-and-fire.
2. `_trigger` resolves the alarm via `_sync.get_alarm()`, builds today's fire
   instant in **local** time, and fires iff `now` is in
   `[fire_time, fire_time + TRIGGER_CATCHUP_MINUTES)`. The catch-up window is
   what makes a suspended or just-booted machine still fire.
3. Firing = `systemctl --user start morning-routine.service`. **Never**
   `wake-alarm.service` directly — see the orchestrator section below.
   Starting an already-active unit is a no-op, so an alarm on screen needs no
   extra dedupe state; the `was_alarm_dismissed_today()` /
   `was_workout_logged_today()` gates cover the rest.

A timer, not a resident daemon: each tick is a fresh process, so there is no
long-lived scheduler to die silently and no wall-clock jump to handle across
suspend/resume.

**Fallback path — hibernate (only when the PC really is powered down):**

`shutdown-wrapper.sh` (installed to `/usr/local/bin/shutdown`, shadowing
`/usr/bin/shutdown` via PATH order) still intercepts shutdown/poweroff, reads
the same synced alarm, and sets `rtcwake`. `sleep-hook.sh` (in
`/usr/lib/systemd/system-sleep/`) fires on resume (`$1 == post`) and starts
`morning-routine.service`. This is now a backstop, not the main mechanism.

If you change `WAKE_AFTER_HOURS` in `_constants.py`, you must also update the
duplicate constant in `shutdown-wrapper.sh` (`WAKE_AFTER_HOURS=8`) — they are
not wired together, by design (the shell wrapper has no Python runtime
available at the point it intercepts `shutdown`). The same duplication applies
to the token search order: `SYNC_CONFIG_FILE` / `SYNC_TOKEN_FALLBACK_FILES` in
`_constants.py` are mirrored by `read_sync_token()` in the wrapper.

## `wake-alarm.service` must never auto-start

`wake-alarm.service` deliberately has **no `[Install]` section** and nothing
starts it automatically. `_should_run_alarm()` gates on day / dismissed /
workout-logged but has **no time gate**, so a
`WantedBy=graphical-session.target` there fires the alarm at *login* time on
any alarm day — which is every day now that the machine no longer reboots into
the alarm. `install.sh` explicitly runs `systemctl --user disable
wake-alarm.service` to clear the stale symlink from older installs.

The unit survives only as a manual test handle. Do not "fix" its missing
auto-start.

## Reading the phone's alarm

`_sync.py` is the Python reader; `shutdown-wrapper.sh` is a second, jq-based
reader of the **same file**. Keep their parse and token order in step.

- Source of truth: `wake-alarm-sync/devices/phone/alarm.json` in the private
  `kuhyx/syncs` repo, written by `phone_app/` as a `crdt_sync` log. The value
  lives at `.alarm.fields.alarm_hour[0]` / `.alarm_minute[0]`.
- Token: `~/.config/wake_alarm/sync.json` key `token`, else a sibling app's
  raw `~/.config/{diet_guard,screen_locker}/sync_token`. Needs `repo` scope —
  the repo is private, and a token without access returns **404, not 403**.
- `_sync` is **stdlib-only** (`urllib.request`) on purpose: the service runs
  `/usr/bin/python`, so every dependency is a production install-path hazard.
- Resolution chain in `get_alarm()`: fresh cache (< 5 min) → live fetch →
  stale cache → `FALLBACK_ALARM_HOUR`. The cache
  (`~/.config/wake_alarm/alarm_cache.json`) is what bounds GitHub reads to
  ~288/day despite the per-minute tick, and what keeps a network blip from
  costing a wake-up.
- **Degraded reads log at INFO, not WARNING.** `get_alarm()` runs every minute,
  so a persistent condition logged loudly is 1440 identical journal lines a
  day. `_trigger` emits the single WARNING that matters: it is firing *now* on
  a non-phone alarm time.

Check what the PC currently resolves: `python -m wake_alarm._sync --show`.
Check what it would do right now: `python -m wake_alarm._trigger --dry-run`.

## Cross-repo coupling — not a bug

`_constants.py`'s `WORKOUT_LOG_FILE` points at
`~/screen-locker/screen_locker/workout_log.json` — a file owned by the
separate, already-standalone `screen-locker` repo
(https://github.com/kuhyx/screen-locker). This is intentional: the alarm
reads whether today's workout was already logged by screen-locker to decide
whether the morning routine should also lock the workout screen. If this
path ever raises `ModuleNotFoundError`-style confusion, the bug is almost
certainly in the **orchestrator** (`morning_routine` in testsAndMisc), not
here — see the next section.

## The morning_routine orchestrator lives elsewhere

`morning_routine._orchestrator` (in `testsAndMisc/python_pkg/morning_routine/`)
runs this package and `screen_locker` as two sequential subprocesses. When
either package is extracted to its own repo, **the orchestrator's module
reference must be updated in the same change** — this exact mistake
(orchestrator left pointing at `python_pkg.screen_locker.screen_lock` after
screen-locker's extraction on 2026-05-28) caused a month-long silent
production failure where the alarm fired and dismissed correctly but the
workout lock crashed with `ModuleNotFoundError` on every run. Once both
`wake_alarm` and `screen_locker` are pip-installed system-wide, the
orchestrator needs no `PYTHONPATH`/`cwd` plumbing — plain
`subprocess.run([sys.executable, "-m", module, "--production"])` resolves
both.

## Production dependency installation — read this before adding any dependency

`wake-alarm.service` runs `/usr/bin/python` directly — **not** a venv. Any
new non-stdlib dependency (this package itself, `gatelock`, `python-kasa`,
anything added later) must be installed into system Python's *user*
site-packages:

```bash
/usr/bin/python3 -m pip install --user --break-system-packages -e .
```

**Always run `install.sh` (or `pip install -e`) from a durable clone, not a
scratch directory.** `install.sh` does `pip install -e "$REPO_DIR"` —
editable, so a later `git pull` in that same clone updates the running
production code with no reinstall needed. The clone must live somewhere
permanent (this repo's convention: `~/wake-alarm`, mirroring `~/screen-locker`
for the screen-locker package) — if you `pip install -e` from `/tmp/...` or
run `pip install "wake_alarm @ git+https://..."` as a one-off, you get a
non-editable snapshot frozen at that commit, and the next `git push` here
silently does **not** reach the running service.

`install.sh` already does this. **If you add a dependency and only install it
into a dev venv, the production service will silently fail with
`ModuleNotFoundError` on its next run** — this exact gap caused a 3-day
diet_guard production outage (2026-06-19 to 2026-06-22) for the sibling
`gatelock` migration. Always verify against
`/usr/bin/python3 -c "import <new_dep>"`, not just the dev venv, before
considering a dependency change done.

## Operational gotchas

- **`python-kasa` is optional at runtime** (`_smart_plug.py` catches
  `ImportError` and disables smart-plug control with a warning log), but it
  *is* a hard dependency for this repo's own tooling (mypy/pylint/tests need
  it importable) — see `pyproject.toml`/`requirements.txt`.
- **The `wave` module needs special pylint handling.** `_audio.py` opens WAV
  files in write mode; pylint's stdlib stub infers the read-mode overload and
  wrongly flags `setnchannels`/`setsampwidth`/`setframerate`/`writeframes` as
  missing. See the `generated-members` list in `pyproject.toml`'s
  `[tool.pylint.typecheck]` — don't remove it if pylint starts complaining
  about `wave.Wave_write`.
- **`wake_state.json` is runtime state, not tracked.** It holds the
  HMAC-signed dismissal record for the current alarm day. It used to be
  accidentally committed in the monorepo; it is gitignored here and must
  stay that way.

## Commands

- Run tests: `python -m pytest wake_alarm/tests/ --cov=wake_alarm --cov-branch --cov-fail-under=100`
- Lint: `pre-commit run --all-files`
- Test the lock manually (safe, closeable): `python -m wake_alarm._alarm --demo`
- Show the resolved alarm: `python -m wake_alarm._sync --show` (add
  `--no-cache` to force a live GitHub read)
- Show what the next tick would do: `python -m wake_alarm._trigger --dry-run`
- Watch it live: `journalctl --user -fu wake-alarm-trigger.service`
- Install for production: `bash install.sh`

Note the dev venv lacks `gatelock`, so anything importing `_state` (including
`_trigger`) must be run with `/usr/bin/python3`, not `.venv/bin/python`.

## Do NOT

- Don't add a dependency without doing the production install-path check
  above. `_sync.py` is stdlib-only for exactly this reason — don't "improve"
  it to `requests`.
- Don't forget the orchestrator when changing this package's module path or
  invocation — see "The morning_routine orchestrator lives elsewhere" above.
- Don't give `wake-alarm.service` an `[Install]` section or enable it. It
  fires at login time, not alarm time — see the section above.
- Don't make the trigger start `wake-alarm.service`; it must start
  `morning-routine.service` so the workout lock still runs.
- Don't raise the log level of the routine degraded-read paths in `_sync` —
  the per-minute tick turns any WARNING there into journal spam.
- Don't commit `wake_state.json`.