diet-guard/CLAUDE.md
Krzysztof kuhy Rudnicki 17a2c62f26 Automate CLAUDE.md's structural rules, then cut it to 189 lines
CLAUDE.md was 1101 lines and loaded into every session in this repo. Three
passes, in order: automate what a gate can check, rewrite what is left as
instructions rather than rationale, extract what still does not fit.

Automated. Five prohibitions were enforced by nothing but a paragraph asking a
future reader not to do something; they are now repo_invariants_test.dart:

  - no app/linux/ (a GTK embedder target manages ~20fps at 4K)
  - dart:io only in *_io.dart seams and lib/desktop/ -- this one is why the
    test exists at all, since dart:io does not fail a web *compile*. It throws
    at runtime, so a bad import is a blank white window that the widget tests
    happily pass through.
  - no meal builder / repeat-last-meal / reward prompt
  - no image_picker, no CAMERA permission
  - wrapper port 8732 and the diet-guard-desktop Chrome profile, both pinned
    because IndexedDB is keyed by origin and moving either hides the whole
    local food log

Each guard was canary-tested by breaking the invariant and confirming the
suite goes red -- a guard that cannot fail is decoration.

Rules whose behaviour was already covered (budget epoch seeding, sync merge,
food bank) shrink to a pointer at the test that owns them.

Where a rule's entire value was its rationale ("the removal is the feature"),
the why moved into the name and reason string of the gate that now enforces
it, so it lives somewhere executable instead of somewhere quotable.

Extracted. The vendored flutter/flutter rules were 789 of the 1101 lines --
72% of the file, none of it about this repo. Split into five docs/ topic files
under the cap and linked. Verified content-complete: 664 non-blank lines in,
664 out, zero missing.

Python 692 tests / 100% coverage unchanged; Flutter 548 -> 555 (+7 new).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MK3HCZrM75sRHL1gL8usve
2026-08-15 16:39:57 +02:00

190 lines
9.7 KiB
Markdown

# CLAUDE.md — diet_guard
A log-to-unlock gate. Every ~30 min `diet-guard-gate.timer` checks whether a
meal slot (08:00, 12:00, 16:00, 20:00) elapsed unlogged; if so it opens a
fullscreen Tk window that blocks the desktop until the user logs what they
ate. It also tracks a daily calorie/macro budget, seeded from biometrics at
`init` and freely editable afterward on either device. A History tab
(`_gatelock_calendar.py`) and the phone's Calendar screen show adherence,
streaks, a YTD tally and weekly/monthly averages, all derived from
`_daystatus.py` / `day_status_service.dart` and `_averages.py` /
`average_service.dart`.
`docs/design.md` holds the original spec (slot timing, the Tue/Wed/Thu
catch-up rule).
## Commands
- Tests: `python -m pytest diet_guard/tests/ --cov=diet_guard --cov-branch --cov-fail-under=100`
- Lint: `pre-commit run --all-files`
- Test the lock (safe, closeable): `python -m diet_guard gate --demo`
- One sync tick: `python -m diet_guard sync`
- Averages: `python -m diet_guard averages`
- Install for production: `bash install.sh`
- App tests: `cd app && flutter test`
- Desktop app: `cd app && bash run.sh`
- Install desktop app: `cd app && bash install_arch.sh`
- Phone build: `cd app && flutter build apk --release`
## Scheduling
`diet-guard-gate.timer` is wall-clock (`OnCalendar=*-*-* *:00/30:00`,
`Persistent=true`), not boot-relative — a boot-relative timer collided with
fullscreen games grabbing input. `diet-guard-gate.service` is `Type=oneshot`
and exits 0 immediately when no lock is due. It needs `DISPLAY`/`XAUTHORITY`;
see the unit file's comments and `wait_for_display()`.
## Cross-device sync
`diet-guard-sync.timer` runs `python -m diet_guard sync` every ~15 min,
headless. It pulls every other device's log from `kuhyx/syncs`
(`diet-guard-sync/`, dumb file storage via the REST Contents API), merges
(`_sync_merge.merge_logs`: union by `id`, tombstone wins, legacy
`(time, desc)` dedup), **re-signs every persisted entry**, rebuilds the food
bank, pushes back.
- **Re-sign on every merge, not just phone-origin entries.** `_entry_is_valid()`
drops unsigned entries once a machine has the HMAC key, and the phone never
holds that key — skipping the re-sign loses every phone-logged meal on the
next read.
- **The phone's periodic tick syncs unconditionally.** Do not re-gate it on
`due.isNotEmpty` (`due_slot_check.dart`); logging promptly means nothing is
ever due, so the phone never publishes and the PC nags for logged slots.
Publish first, then compute due slots from the merged result.
- **WorkManager background isolates must call `initSyncDeviceId()` themselves.**
A fresh isolate has its own static state; without it `currentSyncDeviceId`
falls back to the compile-time role constant and publishes to
`devices/phone/`. Guarded by `background_sync_service_test.dart`.
- **Catch `RemoteSyncError`, never `GitHubSyncError`.** `FirebaseSyncError`/
`FirebaseAuthError` are siblings, not subclasses. `ConfigError` subclasses
`Exception` directly and is covered by neither — `_client_for_run` translates
it to `SyncError`.
- Needs **one** backend, not both: `~/.config/crdt-sync/` (Firebase, primary)
or a PAT at `~/.config/diet_guard/sync_token`, mode 600. Neither → the tick
logs `sync not configured` and no-ops.
- **Both halves of the food bank sync.** The derived bank (`food_bank.json`)
merges by **`count`** (max-count-wins, idempotent — the right merge for a
derived counter). The curated bank (`food_bank_manual.json`) is one CRDT
record per normalized name, LWW by `editedAt`.
## Production dependency installation
`diet-guard-gate.service` runs `/usr/bin/python`, **not** a venv. Any new
non-stdlib dependency must go into system Python's user site-packages:
```bash
/usr/bin/python3 -m pip install --user --break-system-packages -e .
```
Verify against `/usr/bin/python3 -c "import <dep>"`, not the dev venv.
Installing only into `.venv` caused a 3-day production outage (2026-06-19).
Run `install.sh` from a **durable** clone (`~/diet-guard`), never a scratch
dir — it does `pip install -e`, so the clone must persist for `git pull` to
reach the running service.
## Operational gotchas
- **The budget is a plain, freely-editable synced file.** No seal, no signing —
this deliberately replaced a `chattr +i` mechanism so the value is editable
from either device. Do not reintroduce the seal as a "fix"; the removal is
the feature. Every write stamps an edit timestamp; `budget.json` resolves
concurrent edits LWW.
- **Past days are judged against the budget that applied then.**
`_budget_history.py` / `budget_schedule.dart` is a forward-only list of
`(effective_from, kcal)`. `write_budget` / `saveDailyKcalGoal` must seed the
pre-write value to `1970-01-01` **before** recording today's — reversing that
makes every past day adopt the new budget. Covered by
`test_budget_history.py`; it syncs as `hist:<YYYY-MM-DD>` fields on the
existing `budget` record, so devices predating the feature relay them
untouched.
- **Biometrics are used once and discarded** — only the computed budget is
persisted.
- **PC and phone share one source of truth for everything**: food log, budget,
budget history, body weight (`w`), curated food bank. If you add a stored
field, sync it or comment why it physically cannot be.
- **State lives entirely under `~/.local/share/diet_guard/`** — no cross-repo
file coupling. Exception: the sync timer touches `kuhyx/syncs` and
`~/.config/diet_guard/sync_token`.
- **Every device pushes under a persisted per-install uuid**, not a role
constant. `_device.py` / `sync_device_id.dart` (`crdt.nodeId`). The old role
constant survives as the legacy id so `devices/<legacy>/` is skipped as this
device's own — dropping it makes every tick re-merge our own pre-migration
log. The app resolves it asynchronously in `main.dart` before
`LogStorageService.init()`; don't move that call later. Tests must redirect
`_device.SYNC_DEVICE_ID_FILE` (conftest does).
## The companion app's desktop target is a web build
`app/` builds for **Android** and **web** only. There is no `app/linux/` —
Flutter's GTK embedder manages ~20fps at 3840x2160 where the same Dart in
Chrome sustains ~144fps (`~/todo/docs/desktop-performance-findings.md`). The
desktop app is the web build served by `bin/diet_guard_desktop.dart` in a
Chrome `--app` window.
Enforced by `app/test/repo_invariants_test.dart`: no `app/linux/`, `dart:io`
only in `*_io.dart` seams and `lib/desktop/`, port 8732 and the
`diet-guard-desktop` Chrome profile pinned (IndexedDB is keyed by origin, so
changing either hides the entire local food log).
- Branch on `kIsWeb` *before* any `Platform.is…`, which itself throws on web.
`dart:io` does not fail a web compile — it throws at runtime, so the symptom
is a blank white window, not a build error.
- The wrapper holds the GitHub token, not the browser, and proxies
`api.github.com` plus the CORS-less device flow (`lib/desktop/github_proxy.dart`).
- Desktop reminders only exist while the window is open; the PC's real backstop
is `diet-guard-gate.timer`.
- Never run `flutter create --platforms linux` in `app/`.
## Averages (`_averages.py` / `average_service.dart`)
Three load-bearing rules; changing any silently changes what "under budget"
means:
- **Denominator is logged days, not elapsed days.** An unlogged day is not a
zero-kcal day.
- **The yardstick is the mean of the per-day budgets over those same logged
days**, resolved through `BudgetSchedule` — never `daily_budget()`.
- **Today is excluded**; every period ends at `last_complete_day()`. "This
week" is empty on a Monday, and reports `no logged days yet` rather than a
fake average.
Band boundaries reuse `_daystatus.OVER_BUDGET_YELLOW_CEILING` /
`kOverBudgetYellowCeiling` **by import, not by copy**. The MCP `get_averages`
tool drops `avg_budget` (budget secrecy on the network only); the CLI, gate and
phone show both.
## Do NOT
- Don't relax the meal-slot logic without re-reading `docs/design.md`. The
off-hours clamp in `slot_for_log`/`slotForLog` (before 08:00 → 08:00, after
22:00 → 20:00) must stay byte-identical across Python and Dart; do NOT widen
`elapsed_slots`, which would make every slot fall due at 23:00.
- Don't re-add the meal builder, "repeat last meal", the reward prompt, or
**meal photos** — all removed deliberately, enforced by
`app/test/repo_invariants_test.dart`. Photos also took `image_picker`, the
blob stores, the `/blobs/` route and the `CAMERA` permission; re-adding them
means syncing image blobs too.
- Don't strip the `components` field: nothing writes it, but historical
composite entries and the food bank read it, and it is part of the sync wire
format.
- Don't add a dependency without the production install-path check above.
- Don't reintroduce a seal/`chattr +i` on the budget file.
- Don't re-add a Linux embedder target, and don't change the wrapper's port or
Chrome profile path.
- Don't exceed **250 lines** in any file. Enforced by the `file-length`
pre-commit hook and `.github/workflows/file-length.yml`; the cap and its
exemptions live in `~/utils/file_length/config.py`.
## Flutter/Dart AI rules
_Vendored from [flutter/flutter docs/rules/rules.md](https://github.com/flutter/flutter/blob/main/docs/rules/rules.md)
via `~/.claude/CLAUDE.md` Flutter AI tooling setup. Re-fetch periodically.
Split across five files to stay under the 250-line cap._
- [Language, style and architecture](docs/flutter-rules-language.md)
- [Architecture, lint rules, state and data](docs/flutter-rules-state-and-data.md)
- [Code generation, testing and theming](docs/flutter-rules-testing-and-assets.md)
- [UI: theming, layout and overlays](docs/flutter-rules-ui.md)
- [Colour, type, documentation and accessibility](docs/flutter-rules-design.md)