diet-guard/CLAUDE.md

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

A sync tick 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.

On the PC, sync is event-driven — there is no periodic timer. The old diet-guard-sync.timer (~15 min) was deleted: it paid a network round-trip on every idle tick to approximate the two moments state actually changes here.

• Before a lock — _cli_gate._should_lock runs the cheap local gate_is_due() first and pulls only when a lock is otherwise due, so a meal just logged on the phone clears the lock and a not-due tick never touches the network.

• After a meal is logged — _sync_events.publish_after_log, called from all three write paths (_cli, _cli_gate, _mcp). This is what stops the phone nagging for a slot already logged on the PC.

• The gate's publish lives in cmd_gate after MealGate.run() returns, never in the unlock handler: that runs on the Tk thread with the window still up, so a hanging network call would keep the user locked in behind a successful log. It also covers the "Synced from another device" unlock, which hooking log_meal would miss.

• Accepted trade: a PC that is on but neither logging nor locking does not pull, so an inbound phone edit lands at the next log or lock rather than within 15 min. Bounded by slot spacing — an unlogged day raises a lock.

• gate --demo publishes too. The call sits after the finally, so it runs in demo as well. "Safe, closeable" means it cannot trap you at the keyboard — not that it is offline: demo already writes real entries through log_meal (only the slot is synthetic), so publishing them is consistent rather than a new leak.

• pull_shared_log() is misnamed: it runs a full tick (pull, merge, re-sign, persist, push, plus budget and both food banks), not just a pull.

• Every test that logs a meal would otherwise hit the network through these new call sites; conftest._isolate_state patches publish_after_log at each of the three call sites (not on _sync_events, so a direct test still exercises the real helper).

• 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:

/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 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
• Architecture, lint rules, state and data
• Code generation, testing and theming
• UI: theming, layout and overlays
• Colour, type, documentation and accessibility