glp-companion/BUILD_STATE.md

Build Execution Ledger

Active Target

• Current Milestone: Phase 6: Cross-Platform Hardening, Integration Tests & Forgejo CI/CD — COMPLETE
• Status: Phase 6 Complete (release-ready: all phases 1–6 done)

Phase Checklist

• Phase 1: Foundation & Identity (Passwordless SSO & Encrypted Drift DB)
• Phase 2: Medication Domain, Injection Rotation, Serum Modeling
• Phase 3: Nutrition, Protein Target Tracking, HealthGateway Sync
• Phase 4: Recipe Web Scraper Engine & Meal Planning Calendar
• Phase 5: Pantry Delta Engine & Auto-Shopping Generator
• Phase 6: Hardening, Native Desktop/Web Polish, CI/CD

Phase 2 Deliverables (2026-10-16)

• Domain: DoseEntry entity, 12-quadrant InjectionSite rotation model, Glp1Compound value object (Sema 168h / Tirze 120h / Lira 13h), IMedicationRepository contract.
• Domain: CalculateSerumLevel use case implementing C(t) = Σ D_i · 0.5^((t − t_i)/t_half).
• Data: injection-history CRUD on AppDatabase + drift-backed MedicationRepository (record ↔ entity mapping).
• Presentation: MedicationController (Riverpod StateNotifier) with serum estimation, least-recently-used site rotation, and reminder scheduling; refactored MedicationScreen (serum card, rotation suggestion, interactive log dialog, history with delete).
• Platform: INotificationService / PlatformNotificationService (flutter_local_notifications 17.x; Android/iOS/macOS scheduled reminders, graceful no-op on Web/Windows/Linux); Android boot-receiver manifest entries; timezone dependency added.
• Regression fix: SupabaseAuthService now resolves its client lazily (baseline widget test no longer throws when Supabase is uninitialized).
• Tests: 33 new unit/widget-fake tests (PK calculator, rotation policy, repository w/ in-memory drift, controller); baseline smoke test green.

Post-Phase-2 Additions

• Development auth bypass (2026-10-16): debug-only "Continue Without Signing In" button on the login screen (kDebugMode-gated, in-memory devAuthBypassProvider) lets reviewers enter the app without a Supabase session; the router guard honors the flag and the shell shows an orange "Development mode - not signed in" banner while active. Covered by test/features/auth/dev_auth_bypass_test.dart (3 tests).

Phase 3 Deliverables (2026-10-16)

• Domain: FoodLogEntry (+ MealType enum), HydrationLogEntry, BiometricEntry (+ BiometricSource enum), INutritionRepository, IHealthSyncRepository — all pure Dart.
• Data: AppDatabase schema v2 (+ migration for v1 installs) with FoodLogsTable, HydrationLogsTable, BiometricLogsTable, range-filtered watch/get/CRUD helpers, clearSyncedRange for idempotent re-syncs; drift-backed NutritionRepository and HealthSyncRepository (record ↔ entity mapping).
• Platform: HealthGateway rewrite — IHealthGateway + conditional-import factory; mobile impl (health_gateway_mobile.dart) wraps package:health for WEIGHT (kg→lb normalization) and ACTIVE_ENERGY_BURNED (joule→kcal) with double-guarded try/catch; fallback impl (health_gateway_fallback.dart) for Web/Windows/macOS never touches platform channels (reads served from the drift cache, writes via manual entry).
• Presentation: NutritionController (Riverpod AsyncNotifier; today's logs, 100 g protein / 96 oz water targets, meal grouping, quick-add water) and BiometricController (weight history, 7/30-day deltas, manual entry, native sync with per-day active-energy aggregation); LogFoodDialog and LogWeightDialog.
• Presentation: NutritionScreen upgraded — interactive protein/hydration progress meters, +8/+16/+24 oz quick-add buttons, meal-grouped food diary with delete, weight tracker card (latest weight, 7/30-day trend chips, latest active burn) whose "Log Weight / Sync" button runs HealthGateway sync on Android/iOS and opens the manual dialog on Windows/Web; status snackbars via ref.listen.
• Tests: 23 new tests — nutrition repository (in-memory drift: CRUD, day-range filter, watch, MealType round-trip), nutrition controller (targets, grouping, validation, quick-add, delete, failure retention), biometric controller (manual entry, deltas, fallback short-circuit, permission denial, weight+energy sync idempotency).
• Regression fix: none required — existing 37 tests untouched and green.

Phase 4 Deliverables (2026-10-16)

• Domain: Recipe (+ MacroProfile), RecipeIngredient (quantity/unit/item parsing: decimals, ASCII + unicode + mixed fractions, known-unit vocabulary), MealPlanSlot (reuses nutrition MealType), IRecipeRepository, IMealPlanRepository — all pure Dart; core/utils/uuid.dart v4 generator (no new dependency).
• Domain: ScrapeRecipeFromUrl use case — package:http download (injectable RecipeHtmlFetcher for tests), package:html DOM parse, JSON-LD @graph/root/array/@type-list navigation, HowToStep/HowToSection instruction flattening, ISO-8601 prepTime/cookTime, recipeYield, regex nutrition parsing (calories, proteinContent, carbohydrateContent, fatContent), image list/object unwrap, OpenGraph fallback (og:title/og:image/og:description), typed RecipeScrapeException.
• Data: AppDatabase schema v3 (migration for v1/v2 installs) with RecipesTable (UUID PK, JSON ingredient/instruction columns, macros, createdAt) and MealPlanSlotsTable (UUID PK, plannedDate, mealType, nullable recipeId FK with ON DELETE SET NULL, customNotes, isCompleted); drift-backed DriftRecipeRepository (URL-deduplicated importRecipe, createdAt preserved on re-import) and DriftMealPlanRepository (half-open [from, to) window, upsert-by-id).
• Presentation: RecipeImportController (Riverpod Notifier; URL submit → loading → preview modal state, live catalog watch stream, confirm-save/dismiss/delete) and MealPlanCalendarController (Monday–Sunday window, next/previous/today navigation, slot assign/upsert/clear, prepared toggle, per-day protein rollup against the nutrition 100 g target, deleted-recipe slot normalization, stale-window refresh guard).
• Presentation: MealPlannerScreen refactor — URL import bar with spinner, RecipePreviewDialog (image, meta chips, macro tiles, ingredients, steps, save with error surface), SavedRecipesTray (draggable cards with thumbnail + protein badge + quick-assign), WeeklyCalendarView (≥900 dp: 7-column grid; below: tabbed pager) with DragTarget meal slots, prepared checkboxes, clear menu, per-day protein indicator (progress bar vs. target), AssignSlotDialog (saved-recipe dropdown or custom description), week navigation header.
• Tests: 25 new tests — recipe_scraper_test.dart (JSON-LD @graph/root/array/list-@type extraction, macro/ingredient/instruction/duration/yield parsing, malformed-JSON fallthrough, OpenGraph fallback, execute() URL validation & error mapping) and meal_plan_repository_test.dart (startOfWeek, recipe CRUD/URL-dedup/watch, slot window filter/upsert/delete, calendar rollup/assignment/navigation/custom entries/prepared toggles/recipe-deletion normalization, import-controller empty-URL guard).
• Regression fix: HowToSection flattening now recurses into itemListElement before using the section name (parser ordering bug caught by the new test).

Post-Phase-4 Additions

• Desktop resize overflow fix (2026-10-16): the hatched yellow/black stripes (RenderFlex overflow) shown when shrinking the Windows window are gone — wide-mode day columns now scroll vertically (matching the compact pager), and a LayoutBuilder in MealPlannerScreen collapses the page into a single scrollable column (with a fixed-height calendar) whenever the body is shorter than ~520 dp. Covered by test/features/meal_planner/meal_planner_screen_test.dart (4 widget tests pumping the screen at short-compact, short-wide, tall, and extremely-short window sizes; overflow errors fail widget tests, so green proves no stripes).

Phase 5 Deliverables (2026-10-16)

• Domain: PantryItem (+ PantryCategory aisle enum with infer() keyword heuristic, ExpirationStatus warning buckets), ShoppingListItem, IPantryRepository, and two pure-Dart value objects — ingredient_name.dart (lowercase, paren-stripped, plural-folded canonical keys: eggs → egg) and measurement_units.dart (mass/volume/count dimensions with lb↔oz↔g↔kg and ml/l/tsp/tbsp/cup conversion).
• Domain: CalculateShoppingDelta use case — aggregates the active 7-day MealPlanSlot window's Recipe ingredient manifests by canonical name, applies deficit = totalRequired − currentPantryQuantity in dimension base units (dominant recipe unit wins display, 2-decimal rounding), upserts isAutoGenerated rows with sourceRecipeTitles (stable ids, checked-state kept only while the requirement is unchanged), clears stale auto rows (satisfied by stock or superseded by a manual row), and never modifies or removes manual rows.
• Data: AppDatabase schema v4 (migration for v1–v3 installs) with PantryItemsTable (UUID PK, canonical name, quantity/unit, aisle key, nullable expirationDate, lastUpdated) and ShoppingListItemsTable (UUID PK, required quantity/unit, purchased/auto flags, JSON sourceNotes for recipe titles); drift-backed DriftPantryRepository (watch/get/upsert/delete for both lists, enum/JSON mapping).
• Presentation: PantryInventoryController (live watch stream, quick ± stock steps clamped at zero, aisle-grouping vs. expiration-sort modes) and ShoppingListController (manual add, All/To Buy/Checked filter, check-off with "Add to Pantry?" prompt performing a unit-converting stock merge or aisle-inferred row creation, syncWithMealPlan reading the planner's Monday–Sunday window + recipe catalog).
• Presentation: PantryScreen refactor — Inventory/Shopping tab header with remaining-count badge, Aisles/Expiration segmented control, categorized tiles with +/− counters and Expired/expiring badges, swipe-to-delete on both lists, prominent "Sync with Meal Plan" banner with run summary + snackbar, auto-row "From: " origin chips, filter segments, check-off → pantry prompt, and Add Pantry Item / Add Shopping Item dialogs.
• Tests: 10 new tests in test/features/pantry/delta_calculator_test.dart — the three required scenarios (300 g vs 800 g → +500 g entry; sufficient stock → no entry; manual rows preserved across repeated syncs) plus stale auto cleanup, cross-recipe plural/unit normalization (4 eggs + 2 egg − 2 → +4 egg), lb/oz scale unification (0.75 lb), check-off → pantry transfer (merge + aisle-inferred create), end-to-end syncWithMealPlan, and inventory canonicalization/quick-adjust clamp.

Phase 6 Deliverables (2026-10-16)

• Platform: HealthGateway hardened — IHealthGateway factory now accepts an ILocalBiometricReader (core contract); mobile driver guards with kIsWeb + defaultTargetPlatform + dart:io cross-check, probes Health Connect SDK availability (getHealthConnectSdkStatus) and degrades with a debug warning when missing/disabled, validates READ_WEIGHT/READ_STEPS/READ_TOTAL_CALORIES_BURNED/READ_ACTIVE_CALORIES_BURNED permissions via hasPermissions/requestAuthorization before every read, and keeps all HealthKit entitlement failures inside try/catch (false + warning, never an unhandled exception).
• Platform: fallback driver (health_gateway_fallback.dart) now serves locally logged biometrics through an injected ILocalBiometricReader (wired to the drift cache by DriftLocalBiometricReader in the health_sync controller) and emits a debug warning instead of attempting native SDK calls; Android manifest declares the four Health Connect READ_* permissions matching the gateway request set.
• Security: CryptoManager platform-safe vault config — Android AndroidOptions(encryptedSharedPreferences: true), iOS/macOS KeychainAccessibility.first_unlock (Darwin Keychain options), Windows DPAPI-sealed file, Linux libsecret; vault failures degrade to an ephemeral in-memory SQLCipher key instead of crashing.
• Testability: isAuthenticatedProvider extracted in app_router.dart so integration tests can simulate authenticated/unauthenticated sessions without booting Supabase.
• Tests: test/features/medication/serum_calculator_test.dart (11 tests — semaglutide 168 h / tirzepatide 120 h weekly steady-state peaks/troughs vs. closed-form geometric series, monotonic accumulation, peak-to-trough fluctuation ratios, multi-dose superposition, brand-alias resolution, titration ladder, washout).
• Tests: recipe_scraper_test.dart extended with real-world fixtures (test/fixtures/recipes/bbc_good_food_style.html root-level payload, allrecipes_style.html multi-script complex @graph with HowToSection nesting, list-valued yield/image) — 2 new fixture tests.
• Tests: delta_calculator_test.dart extended with a unit-conversion group (kg+g dominant-unit reporting, l+ml volume unification, mass/volume dimension-mismatch guard, unit-synonym/plural canonicalization with cross-dimension stock refusal) — 4 new tests.
• Tests: test/integration/app_navigation_test.dart (4 tests — navigation-rail switching across /medication, /nutrition, /meal-planner, /pantry under authenticated and dev-bypass conditions, mobile bottom-bar switching, unauthenticated bounce to /login) and test/features/nutrition/nutrition_widget_test.dart (3 tests — protein/hydration LinearProgressIndicator values and labels updating reactively on food/water logs, goal-met chips).
• CI/CD: .forgejo/workflows/ci.yml for git.kellsupport.com/mtkell/glp-companion (GitHub Actions-compatible syntax for Forgejo Actions) — push to main + all PRs in ghcr.io/cirruslabs/flutter:stable; checkout → mock .env → flutter pub get → dart run build_runner build --delete-conflicting-outputs → flutter analyze --fatal-infos → flutter test --coverage → flutter build bundle + flutter build web.
• Cleanup: dead lib/features/recipes/data/recipe_scraper.dart (unreferenced Phase-0 scaffold superseded by ScrapeRecipeFromUrl) removed with its empty directory; zero TODO/FIXME markers in lib/ or test/.
• Docs: README.md rewritten (architectural overview + directory layout, local dev prerequisites incl. VS Code/Cline setup and .env configuration via new .env.example, SQLCipher AES-256 key lifecycle, CI pipeline details); BUILD_STATE.md Phase 1–6 checkboxes complete.

Active Verification Gates (Phase 6, 2026-10-16)

• dart run build_runner build --delete-conflicting-outputs (44 outputs written)
• flutter analyze --fatal-infos (Zero issues — No issues found!)
• flutter test (123/123 passing)
• flutter build web --no-tree-shake-icons (conditional import keeps package:health/dart:io out of the web bundle)