groundwork-method 0.0.1 → 0.10.0

package/src/generators/flutter-app/docs/principles/stack/flutter/testing.md

@@ -0,0 +1,74 @@
+---
+title: Testing
+description: Unit, widget, and integration test taxonomy; headless Android emulator CI; Patrol for native boundaries; alchemist goldens; the prove-once rule.
+status: active
+last_reviewed: 2026-06-12
+---
+# Testing
+
+## TL;DR
+
+Three tiers: pure-Dart unit tests with fakes, widget tests as the bulk of coverage, and `integration_test` happy paths on a headless Android emulator as the CI-canonical loop. Patrol enters only when a flow crosses the Flutter/OS boundary. Goldens run via alchemist. Surface tests assert wiring, rendering, and interaction — they never re-prove business logic already proven at the core's contract.
+
+## Why this matters
+
+Flutter's first-party test harness is the reason Flutter is GroundWork's mobile pick: `flutter test` runs widget tests headless in seconds, and `integration_test` drives the real app on a headless emulator — the agent runs generate → boot → test → observe without a human holding a device. The agent-closable loop axis lives or dies in this file. Every choice below protects that loop: fakes over mocks keep unit tests refactor-stable, the emulator lane stays thin because surface tests are wiring-only, and iOS never gates CI because an iOS simulator needs macOS runners and hands.
+
+## The prove-once principle
+
+Capability behaviour is proven once, headless, at the core's contract. The Flutter surface proves only that it is **wired** to the core (the typed client is called with the right inputs), **renders** core state correctly, and **handles interaction** (commands fire, navigation moves, errors surface). A widget or integration test that re-asserts a business rule — price calculation, permission logic, validation semantics — is a review finding: it duplicates a proof that already exists at the contract and couples the surface suite to core internals. This is what keeps N surfaces affordable.
+
+## The tiers
+
+### Tier 1 — Unit tests (pure Dart)
+
+View models, repositories, mappers — anything with logic and no widget. Dependencies are substituted with **fakes, not mocks** (the official guide strongly recommends this): an in-memory `FakeUserRepository` implementing the abstract class survives refactors that stub-and-verify mocks break on, and it doubles as the fixture for widget tests. Riverpod's `ProviderContainer` with overrides is the seam (see [State management](state-management.md)).
+
+### Tier 2 — Widget tests (the bulk)
+
+Most coverage lives here. `testWidgets` pumps the feature's View inside a `ProviderScope` with fake repositories, then asserts rendering and interaction through the semantics tree:
+
+```dart
+testWidgets('renaming updates the profile header', (tester) async {
+  await tester.pumpWidget(ProviderScope(
+    overrides: [userRepositoryProvider.overrideWithValue(fakeRepo)],
+    child: const MaterialApp(home: ProfileView()),
+  ));
+  await tester.enterText(find.bySemanticsLabel('Name'), 'Ada');
+  await tester.tap(find.text('Save'));
+  await tester.pumpAndSettle();
+  expect(find.text('Ada'), findsOneWidget);
+  expect(fakeRepo.lastRename, 'Ada');
+});
+```
+
+Widget tests are fast, headless, and deterministic — they are the mobile analogue of the web stack's component tests, and they carry the rendering/interaction half of the surface proof. Find by semantics and visible text, not by widget type or internal keys, so tests assert what users perceive.
+
+### Tier 3 — `integration_test` (happy-path E2E, CI-canonical)
+
+A small set of happy-path flows through the real app binary — launch, sign in against a faked or staged core, exercise one flow per critical journey. These run **on a headless Android emulator in CI**: the standard pattern is `reactivecircus/android-emulator-runner@v2` (x86_64, `-no-window -gpu swiftshader_indirect -no-snapshot-load -no-snapshot-save`, KVM-enabled runner) executing `flutter test integration_test`.
+
+**Android is the CI gate; iOS is a local-only lane.** The headless Android emulator is cheap, scriptable, and agent-drivable; iOS simulators need macOS runners and routinely need hands — putting them in the gate trades the agent-closable loop for platform symmetry the wiring proof does not need. iOS-specific verification happens locally or on device farms (Firebase Test Lab, Codemagic) as an explicit, non-gating lane.
+
+Keep this tier thin. Every integration test is minutes of emulator time; if a widget test can carry the assertion, it does.
+
+### Patrol — only across the Flutter/OS boundary
+
+**Patrol** (LeanCode) is added only when a flow leaves Flutter for the OS: permission dialogs, push notifications, system sign-in sheets, WebViews, home-button/recents behaviour — surfaces `integration_test` structurally cannot touch. It also brings full test isolation and sharding. A Patrol suite duplicating pure-Flutter flows that `integration_test` already covers is scope creep; the boundary is the OS, not preference for its finder DSL.
+
+### Golden tests — alchemist
+
+Goldens guard design-system-level components (the token-projected theme made visible). Use **alchemist**, with its platform-test vs CI-test split — CI variants render text as blocks, killing the cross-platform font flakiness that made goldens a deletion candidate. `golden_toolkit` is discontinued — legacy; migrate, do not adopt. Golden scope is the component library, not full screens: screen-level goldens churn on every copy change and teach the team to rubber-stamp diffs.
+
+## Legacy
+
+`flutter_driver` (long deprecated for `integration_test`); `golden_toolkit`; Appium-first Flutter testing (a mixed-stack-org accommodation, not Flutter-native practice).
+
+## Anti-patterns
+
+- **Re-proving core logic on the surface.** The contract suite already proved it; the surface proves wiring.
+- **Mock-heavy unit tests.** Stub-and-verify mocks test the mock's script. Fakes test behaviour.
+- **iOS simulator as a CI gate.** It breaks the headless loop; keep it a local or device-farm lane.
+- **Fat integration suites.** Emulator minutes are the most expensive test currency in this stack; spend them on happy paths only.
+- **Finding by widget type or implementation keys.** Tests coupled to the widget tree break on refactor; semantics-based finds break on user-visible regressions only.
+- **`pumpAndSettle` as a sleep.** If a test needs settling tricks to pass, the awaited state is not modelled; assert on it explicitly.

package/src/generators/flutter-app/docs/principles/stack/flutter/widgets-and-composition.md

@@ -0,0 +1,69 @@
+---
+title: Widgets and Composition
+description: Composition over inheritance, const discipline, build purity, keys, token-projected theming, go_router navigation, and the accessibility baseline.
+status: active
+last_reviewed: 2026-06-12
+---
+# Widgets and Composition
+
+## TL;DR
+
+Widgets compose; they do not inherit. Build methods are pure, `const` is applied wherever the constructor allows, keys are used deliberately, and every colour, radius, and text style flows from a `ThemeData` module generated from the design system's brand tokens — never hand-rolled. Navigation is go_router with typed routes via `go_router_builder`. Accessibility is a merge gate, not a backlog item.
+
+## Why this matters
+
+Flutter's rendering model rewards exactly one style: small, pure, const-friendly widgets composed deeply. Every deviation — subclassed widgets, side effects in build, hardcoded colours — is a deviation an agent must special-case forever after. Keeping the widget layer mechanical is what keeps it cheap.
+
+## The principles
+
+### Composition over inheritance
+
+New UI is built by composing existing widgets, never by subclassing a widget to alter its behaviour. A "PrimaryButton" wraps and configures; it does not extend. Extract a widget when a build method's subtree is reused or when it can become `const` — extraction into widgets (not helper methods returning widgets) is what gives Flutter subtree-level rebuild isolation.
+
+### `const` discipline
+
+Every widget constructor that can be `const` is `const`, and every instantiation site that can use `const` does. A `const` widget is canonicalised and skipped during rebuilds — this is the cheapest performance work in Flutter, it is enforced by lints (`prefer_const_constructors` and friends in `flutter_lints`), and it costs nothing at authoring time.
+
+### Build purity
+
+`build` reads state and returns widgets. It never mutates state, fires requests, shows dialogs, or starts animations — Flutter may call build at any frequency, and an impure build turns rebuild cadence into behaviour. Side effects belong in view-model commands, lifecycle hooks, or listeners.
+
+### Keys are deliberate
+
+Keys appear in exactly three situations: reordering children in lists (`ValueKey` on the item id), preserving state when the tree shape changes around a stateful widget, and `GlobalKey` for the rare imperative handle (forms). A key sprinkled "to be safe" is noise; a missing key on a reorderable list is a state-corruption bug.
+
+### Theming is a projection, not an authoring surface
+
+A GroundWork app's theme module is **generated from `brand-tokens.json`** — the design system's token file projects into a Dart theme module exposing `ThemeData` (and any semantic extensions via `ThemeExtension`). Widgets consume `Theme.of(context)` and the generated extensions; they never declare `Color(0xFF...)`, raw `TextStyle`s, or magic paddings. This is the one-design-system-projection dividend of the capability-core model: the same tokens drive every surface, so cross-surface visual consistency is a build artifact, not a review hope. A hex literal in a widget file is a review finding.
+
+Note for planning: Material and Cupertino are frozen in the core framework as of Flutter 3.44, moving to standalone `material_ui`/`cupertino_ui` packages — theme code should expect that dependency shift.
+
+### Navigation is go_router, typed
+
+**go_router** (flutter.dev verified publisher, declared feature-complete — a stable platform piece, not a moving target) is the router:
+
+- **Typed routes via `go_router_builder`** — route paths and parameters as generated, compile-checked classes. Stringly-typed `context.go('/user/$id')` calls scattered through features are the navigation equivalent of hand-rolled JSON.
+- **`StatefulShellRoute`** for bottom-bar/tab scaffolds with per-tab navigation state.
+- **Centralised `redirect`** for auth guards — one function, not per-screen checks.
+- **Deep links fall out for free**: anything declared as a `GoRoute` is deep-linkable, which is also why the route is a first-class state container.
+
+Raw Navigator 1.0 push/pop survives only for trivial local flows (a dialog, a one-off modal). Hand-rolled Navigator 2.0 `RouterDelegate` code is legacy — it is the API go_router exists to hide.
+
+### Accessibility is a baseline
+
+Every interactive widget has a semantic label (`Semantics`, `Tooltip`, or the widget's built-in semantics), tap targets meet the 48dp minimum, contrast meets WCAG AA via the token palette (enforced at the design-system layer, inherited here), and dynamic type does not break layouts — test at large text scales. Flutter's semantics tree is also the test seam: widget tests find by semantics, so inaccessible UI is untestable UI. Accessibility failures block merges.
+
+## Anti-patterns we reject
+
+- **Helper methods returning widget subtrees.** `Widget _buildHeader()` defeats const canonicalisation and rebuild isolation. Extract a widget class.
+- **Hardcoded colours, text styles, or spacing.** The theme module is generated from tokens; literals fork the design system silently.
+- **`MediaQuery.of(context).size` for layout decisions.** Use `LayoutBuilder` — MediaQuery couples a widget to the screen, not its parent's constraints.
+- **Logic in build.** Conditionals that encode business rules belong in the view model; build renders state.
+- **Stringly-typed navigation.** Generated route classes exist; use them.
+- **GlobalKeys as state plumbing.** A GlobalKey reaching into another widget's state is a view model that wasn't written.
+
+## Further reading
+
+- [Flutter widget docs](https://docs.flutter.dev/ui) — the composition mental model.
+- [go_router](https://pub.dev/packages/go_router) and [go_router_builder](https://pub.dev/packages/go_router_builder) — routing and typed routes.
+- [Flutter accessibility](https://docs.flutter.dev/ui/accessibility-and-internationalization/accessibility) — the semantics tree and platform integrations.

package/src/generators/flutter-app/files/.gitignore.template

@@ -0,0 +1,30 @@
+# Dart / Flutter
+.dart_tool/
+.packages
+build/
+.flutter-plugins
+.flutter-plugins-dependencies
+pubspec.lock
+
+# Platform shells are bootstrapped (tool/flutter_exec.sh bootstrap) and then
+# owned by the repo — commit android/ and ios/ once they exist. Their build
+# intermediates stay out:
+android/.gradle/
+android/local.properties
+android/app/.cxx/
+ios/Pods/
+ios/.symlinks/
+ios/Flutter/ephemeral/
+
+# Signing material never enters git
+# (docs/principles/stack/flutter/releases-and-distribution.md)
+*.keystore
+*.jks
+key.properties
+*.p8
+*.p12
+*.mobileprovision
+
+# IDE
+.idea/
+*.iml

package/src/generators/flutter-app/files/README.md.template

@@ -0,0 +1,100 @@
+# <%= name %>
+
+A Flutter mobile surface scaffolded by GroundWork. It is a thin adapter over the
+workspace's capability core: business logic lives behind the promoted contracts
+and is proven there once; this app proves wiring, rendering, and interaction.
+The architecture is the official Flutter two-layer MVVM model — Riverpod for
+state and DI, go_router for navigation, a dio-based typed client as the
+core-access seam. Flutter is GroundWork's standard mobile pick per its
+surface-stack-selection principle (training-set fluency, the agent-closable
+loop, the platform capability ceiling); the engineering principles this app
+embodies live in `docs/principles/stack/flutter/`.
+
+## Toolchain
+
+The Flutter SDK is a **declared prerequisite, not an assumption**. Generation
+required no SDK; everything below does. Every Nx target runs through
+`tool/flutter_exec.sh`, which reports `flutter SDK not found — tier skipped`
+instead of failing cryptically when the SDK is missing.
+
+```bash
+npx nx run <%= fileName %>:bootstrap   # one-time: flutter create (android/ios shells) + pub get
+npx nx run <%= fileName %>:run         # flutter run against a device/emulator
+npx nx run <%= fileName %>:analyze     # flutter analyze
+npx nx run <%= fileName %>:test        # widget + unit tests (headless, fast)
+npx nx run <%= fileName %>:test-integration  # integration_test on an emulator
+npx nx run <%= fileName %>:build       # debug APK
+```
+
+This project lives on pubspec and the Dart toolchain, not npm — it is wired
+into the Nx workspace through `project.json` run-commands targets and does
+**not** join `docker-compose.yml` (a mobile app has no Docker boot; see the
+testing principles for what "boots" means here).
+
+## Structure
+
+```
+lib/
+├── main.dart                 # ProviderScope root
+├── app.dart                  # MaterialApp.router + theme projection
+├── router.dart               # go_router route table
+├── config/app_config.dart    # --dart-define configuration (API_BASE_URL)
+├── ui/                       # feature-first: one View + ViewModel per feature
+│   ├── core/theme/
+│   │   ├── brand_palette.dart   # GENERATED from brand-tokens.json — do not hand-edit
+│   │   └── app_theme.dart       # ThemeData built from the palette
+│   └── home/
+│       ├── home_view.dart       # widgets only
+│       └── home_view_model.dart # state + commands
+├── data/                     # type-first: shared across features
+│   ├── repositories/         # source of truth; abstract class + remote impl
+│   └── services/             # stateless wrappers; the contract client lives here
+└── domain/models/            # immutable models
+test/                         # unit + widget tests (the bulk of coverage)
+integration_test/             # happy-path smoke for the emulator lane
+```
+
+See `docs/principles/stack/flutter/architecture.md` for why each piece sits
+where it does.
+
+## Theme: a projection, not an authoring surface
+
+`lib/ui/core/theme/brand_palette.dart` is generated from
+`.groundwork/config/brand-tokens.json` (the design system's `visual` block —
+palette roles in both themes, typography families, base radius). Widgets
+consume `Theme.of(context)` and the `StatusColors` extension; they never
+declare `Color(0xFF...)` literals. Re-run the design system to evolve the
+brand, then regenerate the palette to match. To make the typography families
+render, bundle their font assets in `pubspec.yaml`.
+
+## The core-access seam (contract-client tooling)
+
+`lib/data/services/api_client.dart` is a **hand-rolled thin client** over the
+workspace gateway: one method per promoted-contract operation, typed models in
+`domain/models/`, repositories translating contract payloads into domain
+models. This is the lightest path that consumes the promoted contract directly
+and adds no JVM codegen dependency to the toolchain.
+
+**When the contract surface grows** past a handful of operations, switch to
+generated clients — `openapi_generator`'s `dart-dio` output against the
+promoted `openapi.yaml` — and keep the seam where it is: repositories consume
+the generated client, and nothing above the data layer changes. Re-implementing
+a large promoted contract by hand is the defect the principles warn about
+(`docs/principles/stack/flutter/architecture.md`).
+
+The gateway URL arrives via `--dart-define=API_BASE_URL=...`
+(default `http://localhost:4000`; the Android emulator reaches the host's
+localhost at `http://10.0.2.2:4000`).
+
+## Testing
+
+Three tiers, per `docs/principles/stack/flutter/testing.md`:
+
+1. **Unit** — pure Dart, fakes over mocks, `ProviderContainer` overrides.
+2. **Widget** (`test/`) — the bulk: rendering and interaction through the
+   semantics tree, repositories faked at the provider seam.
+3. **Integration** (`integration_test/`) — thin happy-path smoke; CI runs it
+   on a headless Android emulator. iOS is a local-only lane, never a CI gate.
+
+Surface tests never re-prove core business logic — that proof lives at the
+core's contract.

package/src/generators/flutter-app/files/analysis_options.yaml.template

@@ -0,0 +1,18 @@
+# Lint policy for this surface. flutter_lints carries the const discipline and
+# composition rules the stack principles require
+# (docs/principles/stack/flutter/widgets-and-composition.md).
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    prefer_const_constructors: true
+    prefer_const_declarations: true
+    prefer_final_locals: true
+    avoid_print: true
+    require_trailing_commas: true

package/src/generators/flutter-app/files/integration_test/app_test.dart.template

@@ -0,0 +1,30 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:<%= pubspecName %>/app.dart';
+import 'package:<%= pubspecName %>/data/repositories/status_repository.dart';
+
+import '../test/fakes/fake_status_repository.dart';
+
+/// Boot-tier smoke: the real app binary launches and renders home on a
+/// headless Android emulator — the CI-canonical loop. Keep this tier thin
+/// (happy paths only); emulator minutes are the most expensive test currency
+/// in this stack. The gateway is faked so the smoke proves boot + rendering,
+/// not network reachability (docs/principles/stack/flutter/testing.md).
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  testWidgets('the app boots to the home view', (tester) async {
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          statusRepositoryProvider.overrideWithValue(FakeStatusRepository()),
+        ],
+        child: const App(),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('Wired to the workspace gateway'), findsOneWidget);
+  });
+}

package/src/generators/flutter-app/files/lib/app.dart.template

@@ -0,0 +1,24 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'router.dart';
+import 'ui/core/theme/app_theme.dart';
+
+/// The application shell: theme projection + router. Nothing else lives here —
+/// features live under `ui/<feature>/`, data access under `data/`.
+class App extends ConsumerWidget {
+  const App({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    return MaterialApp.router(
+      title: '<%= name %>',
+      routerConfig: ref.watch(routerProvider),
+      // Both themes are built from the design system's projected brand tokens.
+      // Dual-theme support is a brand commitment, not an option.
+      theme: buildLightTheme(),
+      darkTheme: buildDarkTheme(),
+      themeMode: ThemeMode.system,
+    );
+  }
+}

package/src/generators/flutter-app/files/lib/config/app_config.dart

@@ -0,0 +1,15 @@
+/// Build-time configuration. Values arrive via --dart-define so no
+/// environment file ships inside the binary.
+abstract final class AppConfig {
+  /// Base URL of the workspace gateway this surface is wired to.
+  ///
+  /// Override per environment:
+  ///   flutter run --dart-define=API_BASE_URL=http://10.0.2.2:4000
+  ///
+  /// Note: the Android emulator reaches the host machine's localhost at
+  /// 10.0.2.2; the iOS simulator uses localhost directly.
+  static const String apiBaseUrl = String.fromEnvironment(
+    'API_BASE_URL',
+    defaultValue: 'http://localhost:4000',
+  );
+}

package/src/generators/flutter-app/files/lib/data/repositories/status_repository.dart

@@ -0,0 +1,36 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../domain/models/health_status.dart';
+import '../services/api_client.dart';
+
+/// Repositories are the data layer's source of truth: they own caching,
+/// retry, and the translation of contract payloads into domain models.
+/// View models depend on this abstract class, so tests substitute an
+/// in-memory fake without a mocking framework
+/// (docs/principles/stack/flutter/architecture.md).
+abstract class StatusRepository {
+  Future<HealthStatus> status();
+}
+
+/// The remote implementation consumes the typed client. Nothing above this
+/// layer knows the transport.
+class RemoteStatusRepository implements StatusRepository {
+  RemoteStatusRepository(this._client);
+
+  final ApiClient _client;
+
+  @override
+  Future<HealthStatus> status() async {
+    try {
+      return await _client.health();
+    } catch (_) {
+      // An unreachable gateway is a state the UI renders, not an exception
+      // the view model unwinds on.
+      return const HealthStatus.unreachable();
+    }
+  }
+}
+
+final statusRepositoryProvider = Provider<StatusRepository>(
+  (ref) => RemoteStatusRepository(ref.watch(apiClientProvider)),
+);

package/src/generators/flutter-app/files/lib/data/services/api_client.dart

@@ -0,0 +1,71 @@
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../config/app_config.dart';
+import '../../domain/models/health_status.dart';
+
+/// The core-access seam: a thin, typed dio client bound to the workspace
+/// gateway (docs/principles/stack/flutter/architecture.md).
+///
+/// Contract-client tooling stance (O8): this client is hand-rolled and stays
+/// deliberately thin — one method per promoted-contract operation, typed
+/// request/response models in domain/models. That is the lightest path while
+/// the contract surface is small, and it adds no JVM codegen dependency to the
+/// toolchain. When the promoted openapi.yaml grows past a handful of
+/// operations, switch to generated clients via openapi_generator's dart-dio
+/// output (build_runner) and keep this class as the seam the repositories
+/// consume — nothing above the data layer changes.
+class ApiClient {
+  ApiClient(this._dio);
+
+  final Dio _dio;
+
+  /// Probe the gateway's health endpoint — the wiring proof the home feature
+  /// renders. Replace and extend with the operations your promoted contract
+  /// defines.
+  ///
+  /// `/health` is what GroundWork's Go and Python cores serve. If this
+  /// surface fronts a Next.js BFF instead, its route is `/api/healthz` —
+  /// adjust the path to your gateway, not the other way around.
+  Future<HealthStatus> health() async {
+    final response = await _dio.get<Map<String, dynamic>>('/health');
+    return HealthStatus.fromJson(response.data ?? const <String, dynamic>{});
+  }
+}
+
+/// The auth seam: an async token supplier the request interceptor consults on
+/// every call. The default is unauthenticated — wire your identity provider
+/// (e.g. the Clerk session JWT on a Clerk-protected core) by overriding this
+/// provider; the core's `/health` route stays public either way.
+final authTokenProvider = Provider<Future<String?> Function()>(
+  (ref) => () async => null,
+);
+
+/// Builds the Authorization interceptor from a token supplier. Kept as a
+/// top-level function so tests exercise it without booting a widget tree.
+Interceptor authInterceptor(Future<String?> Function() token) {
+  return InterceptorsWrapper(
+    onRequest: (options, handler) async {
+      final value = await token();
+      if (value != null && value.isNotEmpty) {
+        options.headers['Authorization'] = 'Bearer $value';
+      }
+      handler.next(options);
+    },
+  );
+}
+
+/// The client is a provider like every other shared dependency, so tests
+/// override it (or the repositories above it) with fakes.
+final apiClientProvider = Provider<ApiClient>((ref) {
+  final dio = Dio(
+    BaseOptions(
+      baseUrl: AppConfig.apiBaseUrl,
+      connectTimeout: const Duration(seconds: 5),
+      receiveTimeout: const Duration(seconds: 10),
+      headers: const {'Accept': 'application/json'},
+    ),
+  );
+  dio.interceptors.add(authInterceptor(ref.read(authTokenProvider)));
+  return ApiClient(dio);
+});

package/src/generators/flutter-app/files/lib/domain/models/health_status.dart

@@ -0,0 +1,23 @@
+/// The gateway's health, as the home feature renders it.
+///
+/// Domain models are immutable. This one is a plain const class because it is
+/// trivial; once models carry real shape (unions, copyWith, JSON round-trips),
+/// introduce freezed — it earns its place at that point, not before
+/// (docs/principles/stack/flutter/architecture.md).
+class HealthStatus {
+  const HealthStatus({required this.reachable, this.status = ''});
+
+  factory HealthStatus.fromJson(Map<String, dynamic> json) {
+    return HealthStatus(
+      reachable: true,
+      status: json['status']?.toString() ?? 'ok',
+    );
+  }
+
+  const HealthStatus.unreachable()
+      : reachable = false,
+        status = 'unreachable';
+
+  final bool reachable;
+  final String status;
+}

package/src/generators/flutter-app/files/lib/main.dart

@@ -0,0 +1,11 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'app.dart';
+
+void main() {
+  // ProviderScope is the root of the provider graph — state management and
+  // dependency injection in one mechanism. Everything shared is a provider;
+  // see docs/principles/stack/flutter/state-management.md.
+  runApp(const ProviderScope(child: App()));
+}

package/src/generators/flutter-app/files/lib/router.dart

@@ -0,0 +1,23 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+
+import 'ui/home/home_view.dart';
+
+/// The route table. go_router makes every declared route deep-linkable, and
+/// the URL is a first-class state container — state the route already encodes
+/// is never duplicated in a provider.
+///
+/// As the table grows: adopt go_router_builder for compile-checked typed
+/// routes, StatefulShellRoute for tab scaffolds, and a centralized `redirect`
+/// for auth guards. See docs/principles/stack/flutter/widgets-and-composition.md.
+final routerProvider = Provider<GoRouter>((ref) {
+  return GoRouter(
+    routes: [
+      GoRoute(
+        path: '/',
+        name: 'home',
+        builder: (context, state) => const HomeView(),
+      ),
+    ],
+  );
+});

package/src/generators/flutter-app/files/lib/ui/core/theme/app_theme.dart

@@ -0,0 +1,110 @@
+import 'package:flutter/material.dart';
+
+import 'brand_palette.dart';
+
+/// Builds ThemeData from the generated BrandPalette projection.
+///
+/// Widgets consume Theme.of(context) and the [StatusColors] extension — never
+/// BrandPalette directly, and never Color(0xFF...) literals. A hex literal in
+/// a widget file is a review finding
+/// (docs/principles/stack/flutter/widgets-and-composition.md).
+ThemeData buildLightTheme() => _buildTheme(Brightness.light);
+
+ThemeData buildDarkTheme() => _buildTheme(Brightness.dark);
+
+ThemeData _buildTheme(Brightness brightness) {
+  final bool dark = brightness == Brightness.dark;
+
+  final ColorScheme scheme = ColorScheme.fromSeed(
+    seedColor: dark ? BrandPalette.primaryDark : BrandPalette.primaryLight,
+    brightness: brightness,
+  ).copyWith(
+    primary: dark ? BrandPalette.primaryDark : BrandPalette.primaryLight,
+    secondary: dark ? BrandPalette.accentDark : BrandPalette.accentLight,
+    surface: dark ? BrandPalette.surfaceDark : BrandPalette.surfaceLight,
+    surfaceContainerHighest:
+        dark ? BrandPalette.surfaceAltDark : BrandPalette.surfaceAltLight,
+    onSurface: dark ? BrandPalette.textBodyDark : BrandPalette.textBodyLight,
+    error: dark ? BrandPalette.errorDark : BrandPalette.errorLight,
+  );
+
+  final BorderRadius radius = BorderRadius.circular(BrandPalette.radiusBase);
+
+  final ThemeData base = ThemeData(
+    useMaterial3: true,
+    colorScheme: scheme,
+    scaffoldBackgroundColor: scheme.surface,
+  );
+
+  return base.copyWith(
+    textTheme: base.textTheme
+        .apply(fontFamily: BrandPalette.bodyFontFamily)
+        .copyWith(
+          headlineLarge: base.textTheme.headlineLarge?.copyWith(
+            fontFamily: BrandPalette.displayFontFamily,
+            fontWeight: FontWeight.values[
+                (BrandPalette.displayFontWeight ~/ 100 - 1).clamp(0, 8)],
+          ),
+          headlineMedium: base.textTheme.headlineMedium?.copyWith(
+            fontFamily: BrandPalette.displayFontFamily,
+            fontWeight: FontWeight.values[
+                (BrandPalette.displayFontWeight ~/ 100 - 1).clamp(0, 8)],
+          ),
+          titleLarge: base.textTheme.titleLarge?.copyWith(
+            fontFamily: BrandPalette.displayFontFamily,
+          ),
+        ),
+    cardTheme: base.cardTheme.copyWith(
+      shape: RoundedRectangleBorder(borderRadius: radius),
+    ),
+    filledButtonTheme: FilledButtonThemeData(
+      style: FilledButton.styleFrom(
+        shape: RoundedRectangleBorder(borderRadius: radius),
+      ),
+    ),
+    inputDecorationTheme: InputDecorationTheme(
+      border: OutlineInputBorder(borderRadius: radius),
+    ),
+    extensions: <ThemeExtension<dynamic>>[
+      StatusColors(
+        success: dark ? BrandPalette.successDark : BrandPalette.successLight,
+        warning: dark ? BrandPalette.warningDark : BrandPalette.warningLight,
+        info: dark ? BrandPalette.infoDark : BrandPalette.infoLight,
+      ),
+    ],
+  );
+}
+
+/// Semantic status colours the Material ColorScheme has no roles for.
+/// Read via `Theme.of(context).extension<StatusColors>()!`.
+@immutable
+class StatusColors extends ThemeExtension<StatusColors> {
+  const StatusColors({
+    required this.success,
+    required this.warning,
+    required this.info,
+  });
+
+  final Color success;
+  final Color warning;
+  final Color info;
+
+  @override
+  StatusColors copyWith({Color? success, Color? warning, Color? info}) {
+    return StatusColors(
+      success: success ?? this.success,
+      warning: warning ?? this.warning,
+      info: info ?? this.info,
+    );
+  }
+
+  @override
+  StatusColors lerp(StatusColors? other, double t) {
+    if (other == null) return this;
+    return StatusColors(
+      success: Color.lerp(success, other.success, t)!,
+      warning: Color.lerp(warning, other.warning, t)!,
+      info: Color.lerp(info, other.info, t)!,
+    );
+  }
+}