mirror of
https://github.com/kuhyx/diet-guard.git
synced 2026-11-21 18:42:17 +01:00
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
190 lines
9.7 KiB
Markdown
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)
|