Gate the companion app in the push hook, and document it properly
Some checks are pending
pre-commit / pre-commit (push) Waiting to run
Tests / test (3.10) (push) Waiting to run
Tests / test (3.11) (push) Waiting to run
Tests / test (3.12) (push) Waiting to run

`ci_mirror.sh` -- the pre-push gate -- ran only the Python side: a clean-venv
pytest and `pre-commit --all-files`. Nothing ran the app's suite, and
`.pre-commit-config.yaml` has no Dart hooks at all, so a red `app/` could be
pushed with a fully green gate. It now runs `flutter analyze` and
`flutter test` too, and *fails* rather than skips when `app/` exists but
flutter is missing: a gate that quietly passes without its toolchain is the
same as no gate. Verified by breaking a Dart file on purpose and watching the
push gate refuse it.

app/README.md was still the stock "A new Flutter project" template. It now
says what the two targets are, why there is no `linux/`, what the wrapper
owns, why the port and Chrome profile are fixed, and which behaviours the
desktop genuinely gives up.

Drops MIGRATION_PROMPT.md, whose content now lives in CLAUDE.md and the
migration commits.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-07-20 17:01:40 +02:00
parent 2231850bfc
commit 50f311b6b8
2 changed files with 94 additions and 11 deletions

View File

@ -1,17 +1,75 @@
# diet_guard_app
A new Flutter project.
Companion app for `diet_guard`: log meals on the phone, and on the Linux
desktop, sharing one food log through GitHub-backed sync.
## Getting Started
## Two targets, and only two
This project is a starting point for a Flutter application.
| Target | What it is |
|---|---|
| Android | a normal Flutter app (`flutter build apk`) |
| Linux desktop | the Flutter **web** build, served by a local wrapper and shown in a Chrome `--app` window |
A few resources to get you started if this is your first Flutter project:
There is no `linux/` directory. Flutter's GTK embedder manages ~20fps at
3840x2160 -- measured on a stock `flutter create` counter app, so it is the
toolkit rather than this code -- where the same Dart rendered by Chrome
sustains ~144fps (`~/todo/docs/desktop-performance-findings.md`). Running
`flutter create --platforms linux` here would silently restore the slow path.
- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
## Commands
For help getting started with Flutter development, view the
[online documentation](https://docs.flutter.dev/), which offers tutorials,
samples, guidance on mobile development, and a full API reference.
```bash
flutter test # the app's suite
flutter analyze
bash run.sh # build the web bundle and launch the desktop app
bash install_arch.sh # build + install the pacman package and .desktop entry
flutter build apk --release # the phone build
adb install -r build/app/outputs/flutter-apk/app-release.apk
```
Never `adb uninstall` or `pm clear` this package: both wipe the on-device log.
## The desktop wrapper
`bin/diet_guard_desktop.dart` is the other half of the desktop app, because a
browser cannot touch the filesystem. It:
- serves the built web assets from `build/web` (or `/opt/diet-guard-app/web`
once packaged);
- keeps an on-disk copy of every document and photo under
`~/.local/share/diet-guard-desktop/`, which is what makes a wiped Chrome
profile recoverable -- for photos it is the *only* copy, since they never
sync;
- holds the GitHub token (`~/.config/diet_guard_app/sync_token`, falling back
to the PC gate's `~/.config/diet_guard/sync_token`) and proxies
`api.github.com` plus the device flow, whose endpoints send no CORS headers
and so cannot be called from a page at all.
**The port (8732) and the Chrome `--user-data-dir` must stay fixed.**
IndexedDB is keyed by origin and lives inside that profile, so changing either
looks to the app like a device with no history.
## Platform seams
`dart:io` does not fail a web *compile*; it becomes a stub that throws at
runtime, so the symptom of a missed seam is a blank white window rather than a
build error. Every platform edge is a conditional export -- `document_store*`,
`blob_store*`, `background_tasks*`, `notification_backend*`, `token_vault*`,
`github_client_factory*`, `attached_image*`. Branch on `kIsWeb` *before* any
`Platform.is…`, which itself throws on web.
What the desktop genuinely loses, by design rather than omission:
- **Background reminders.** A browser runs nothing once its window is closed,
so the due-slot check runs in-page every 5 minutes while the window is open.
On the PC the real backstop is `diet-guard-gate.timer`, which locks the
screen.
- **Camera capture.** The browser picker is a file input.
- **Photo sharing between devices** -- unchanged: `imagePath` was always
stripped before push.
## Sync identity
Three devices push under `diet-guard-sync/devices/`: `pc` (the Python gate),
`phone`, and `desktop`. Each must keep its own id -- two devices sharing one
would overwrite each other's pushed log on every tick.

View File

@ -13,7 +13,12 @@
# `pip install -r requirements.txt`), rebuilt only when requirements.txt
# changes (hash-gated so day-to-day pushes stay fast);
# 2. `pre-commit run --all-files` (mirrors the pre-commit workflow);
# 3. `python -m pytest` inside that clean venv (mirrors Tests).
# 3. `python -m pytest` inside that clean venv (mirrors Tests);
# 4. `flutter analyze` + `flutter test` for the companion app in app/.
#
# The app is gated here rather than only by pre-commit because pre-commit has
# no Dart hooks at all: without this, the app's tests were never run by
# anything automatic, and a red app/ could be pushed with a green gate.
#
# Wired as the pre-push hook, so a red result blocks the push before CI ever
# sees it. Escape hatch for genuine emergencies: `git push --no-verify`.
@ -29,6 +34,7 @@ ROOT="$(git rev-parse --show-toplevel)"
readonly ROOT
cd "$ROOT"
readonly APP_DIR="$ROOT/app"
readonly VENV_DIR="$ROOT/.ci-mirror-venv"
readonly HASH_FILE="$VENV_DIR/.requirements.sha256"
readonly REQ_PATH="$ROOT/$REQUIREMENTS_FILE"
@ -82,11 +88,30 @@ run_pytest_clean_venv() {
"$VENV_DIR/bin/python" -m pytest "$@" || fail "pytest (clean requirements.txt venv)"
}
# Gate the Flutter companion app the same way: analyze (pre-commit has no Dart
# hooks) then the full test suite. Deliberately fails rather than skips when
# flutter is missing -- a gate that quietly passes on a machine without the
# toolchain is the same as no gate.
run_flutter_gates() {
if [[ ! -f "$APP_DIR/pubspec.yaml" ]]; then
log "no app/pubspec.yaml — skipping the Flutter gates"
return
fi
if ! command -v flutter >/dev/null 2>&1; then
fail "flutter is not on PATH but app/ exists (cannot verify the app)"
fi
log "flutter analyze (app/)"
(cd "$APP_DIR" && flutter analyze) || fail "flutter analyze"
log "flutter test (app/)"
(cd "$APP_DIR" && flutter test) || fail "flutter test"
}
main() {
require_file
ensure_venv
run_precommit_all_files
run_pytest_clean_venv "$@"
run_flutter_gates
log "all CI gates passed locally — safe to push"
}