groundwork-method 0.0.1 → 0.11.0

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)!,
+    );
+  }
+}

package/src/generators/flutter-app/files/lib/ui/home/home_view.dart

@@ -0,0 +1,89 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../core/theme/app_theme.dart';
+import 'home_view_model.dart';
+
+/// The home View: widgets only — layout, rendering, and command dispatch.
+/// All state lives in HomeViewModel; all colours and shapes come from the
+/// theme. Replace this screen as your first feature lands.
+class HomeView extends ConsumerWidget {
+  const HomeView({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(homeViewModelProvider);
+
+    return Scaffold(
+      appBar: AppBar(
+        title: state.maybeWhen(
+          data: (home) => Text(home.appName),
+          orElse: () => const SizedBox.shrink(),
+        ),
+      ),
+      body: Center(
+        child: state.when(
+          loading: () => const CircularProgressIndicator(),
+          error: (error, _) => _StatusCard(
+            label: 'Something went wrong',
+            detail: '$error',
+            ok: false,
+          ),
+          data: (home) => _StatusCard(
+            label: home.gateway.reachable
+                ? 'Wired to the workspace gateway'
+                : 'Gateway unreachable',
+            detail: home.gateway.status,
+            ok: home.gateway.reachable,
+          ),
+        ),
+      ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: () => ref.read(homeViewModelProvider.notifier).refresh(),
+        tooltip: 'Refresh gateway status',
+        child: const Icon(Icons.refresh),
+      ),
+    );
+  }
+}
+
+class _StatusCard extends StatelessWidget {
+  const _StatusCard({
+    required this.label,
+    required this.detail,
+    required this.ok,
+  });
+
+  final String label;
+  final String detail;
+  final bool ok;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    final status = theme.extension<StatusColors>()!;
+
+    return Semantics(
+      label: 'Gateway status: $detail',
+      child: Card(
+        child: Padding(
+          padding: const EdgeInsets.all(24),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Icon(
+                ok ? Icons.check_circle_outline : Icons.cloud_off_outlined,
+                size: 48,
+                color: ok ? status.success : theme.colorScheme.error,
+              ),
+              const SizedBox(height: 16),
+              Text(label, style: theme.textTheme.titleLarge),
+              const SizedBox(height: 4),
+              Text(detail, style: theme.textTheme.bodyMedium),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

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

@@ -0,0 +1,38 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../data/repositories/status_repository.dart';
+import '../../domain/models/health_status.dart';
+
+/// The home feature's UI state. Immutable, derived from repository data —
+/// never mutated in place.
+class HomeState {
+  const HomeState({required this.appName, required this.gateway});
+
+  final String appName;
+  final HealthStatus gateway;
+}
+
+/// One ViewModel per feature view (MVVM, per the official architecture guide).
+/// It transforms repository data into [HomeState] and exposes commands for
+/// user events. It never touches widgets, and the view never touches
+/// repositories.
+class HomeViewModel extends AsyncNotifier<HomeState> {
+  @override
+  Future<HomeState> build() async {
+    final gateway = await ref.watch(statusRepositoryProvider).status();
+    return HomeState(appName: '<%= name %>', gateway: gateway);
+  }
+
+  /// Command: re-probe the gateway. Views call commands; they never reach
+  /// into repositories themselves.
+  Future<void> refresh() async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      final gateway = await ref.read(statusRepositoryProvider).status();
+      return HomeState(appName: '<%= name %>', gateway: gateway);
+    });
+  }
+}
+
+final homeViewModelProvider =
+    AsyncNotifierProvider<HomeViewModel, HomeState>(HomeViewModel.new);

package/src/generators/flutter-app/files/project.json.template

@@ -0,0 +1,51 @@
+{
+  "name": "<%= fileName %>",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "services/<%= fileName %>/lib",
+  "tags": ["surface:mobile", "stack:flutter"],
+  "targets": {
+    "bootstrap": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh bootstrap",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "run": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh run",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh build",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "analyze": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh analyze",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh test",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "test-integration": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/flutter_exec.sh test-integration",
+        "cwd": "services/<%= fileName %>"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+name: <%= pubspecName %>
+description: >-
+  <%= name %> — a GroundWork mobile surface. A thin Flutter adapter over the
+  workspace's capability core, following the official two-layer MVVM
+  architecture (see docs/principles/stack/flutter/architecture.md).
+publish_to: "none"
+version: 0.1.0+1
+
+environment:
+  sdk: ^3.12.0
+  flutter: ">=3.44.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+
+  # State management + dependency injection: the provider graph IS the DI graph.
+  # Pinned to 3.x per the stack principles — Riverpod's experimental persistence
+  # API stays out of load-bearing paths.
+  flutter_riverpod: ^3.0.3
+
+  # Navigation: URL-based declarative routing, deep-linkable by construction.
+  # Adopt go_router_builder typed routes as the route table grows.
+  go_router: ^17.3.0
+
+  # HTTP client for the core-access seam (interceptors, base config,
+  # cancellation). See lib/data/services/api_client.dart for the O8 stance on
+  # contract-client tooling.
+  dio: ^5.7.0
+
+  cupertino_icons: ^1.0.8
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  integration_test:
+    sdk: flutter
+  flutter_lints: ^6.0.0
+
+flutter:
+  uses-material-design: true
+  # Bundle the design system's font families here when their assets are added,
+  # so BrandPalette's typography projection takes effect:
+  # fonts:
+  #   - family: Inter
+  #     fonts:
+  #       - asset: assets/fonts/Inter-Regular.ttf

package/src/generators/flutter-app/files/test/api_client_test.dart.template

@@ -0,0 +1,63 @@
+// Proves the core-access seam's request shape without any network: a stub
+// adapter captures what dio would send. The auth seam contract is exact —
+// a supplied token becomes `Authorization: Bearer <token>` on every request,
+// and the unauthenticated default adds no header at all.
+import 'dart:typed_data';
+
+import 'package:dio/dio.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:<%= pubspecName %>/data/services/api_client.dart';
+
+class _CaptureAdapter implements HttpClientAdapter {
+  RequestOptions? last;
+
+  @override
+  Future<ResponseBody> fetch(
+    RequestOptions options,
+    Stream<Uint8List>? requestStream,
+    Future<void>? cancelFuture,
+  ) async {
+    last = options;
+    return ResponseBody.fromString(
+      '{"status":"ok"}',
+      200,
+      headers: {
+        Headers.contentTypeHeader: [Headers.jsonContentType],
+      },
+    );
+  }
+
+  @override
+  void close({bool force = false}) {}
+}
+
+Dio _dioWith(_CaptureAdapter adapter, Future<String?> Function() token) {
+  final dio = Dio(BaseOptions(baseUrl: 'http://core.test'));
+  dio.httpClientAdapter = adapter;
+  dio.interceptors.add(authInterceptor(token));
+  return dio;
+}
+
+void main() {
+  test('a supplied token rides every request as a Bearer header', () async {
+    final adapter = _CaptureAdapter();
+    final client = ApiClient(_dioWith(adapter, () async => 'jwt-123'));
+
+    final status = await client.health();
+
+    expect(adapter.last?.headers['Authorization'], 'Bearer jwt-123');
+    expect(status.reachable, isTrue);
+    expect(status.status, 'ok');
+  });
+
+  test('the unauthenticated default sends no Authorization header', () async {
+    final adapter = _CaptureAdapter();
+    final client = ApiClient(_dioWith(adapter, () async => null));
+
+    await client.health();
+
+    expect(adapter.last?.headers.containsKey('Authorization'), isFalse);
+    expect(adapter.last?.path, '/health');
+  });
+}

package/src/generators/flutter-app/files/test/fakes/fake_status_repository.dart.template

@@ -0,0 +1,19 @@
+import 'package:<%= pubspecName %>/data/repositories/status_repository.dart';
+import 'package:<%= pubspecName %>/domain/models/health_status.dart';
+
+/// Fakes over mocks (the official guide's strong recommendation): an
+/// in-memory implementation of the abstract repository survives refactors
+/// that stub-and-verify mocks break on, and serves unit and widget tests
+/// alike (docs/principles/stack/flutter/testing.md).
+class FakeStatusRepository implements StatusRepository {
+  FakeStatusRepository({this.result = const HealthStatus(reachable: true, status: 'ok')});
+
+  HealthStatus result;
+  int calls = 0;
+
+  @override
+  Future<HealthStatus> status() async {
+    calls++;
+    return result;
+  }
+}

package/src/generators/flutter-app/files/test/home_view_test.dart.template

@@ -0,0 +1,58 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:<%= pubspecName %>/data/repositories/status_repository.dart';
+import 'package:<%= pubspecName %>/domain/models/health_status.dart';
+import 'package:<%= pubspecName %>/ui/core/theme/app_theme.dart';
+import 'package:<%= pubspecName %>/ui/home/home_view.dart';
+
+import 'fakes/fake_status_repository.dart';
+
+/// Widget tests carry the bulk of surface coverage: they prove rendering and
+/// interaction through the semantics tree, with the repository faked at the
+/// provider seam. They never re-prove core business logic — that proof lives
+/// at the core's contract (docs/principles/stack/flutter/testing.md).
+void main() {
+  Widget harness(StatusRepository fake) {
+    return ProviderScope(
+      overrides: [statusRepositoryProvider.overrideWithValue(fake)],
+      child: MaterialApp(theme: buildLightTheme(), home: const HomeView()),
+    );
+  }
+
+  testWidgets('renders the gateway status when the core is reachable',
+      (tester) async {
+    final fake = FakeStatusRepository();
+
+    await tester.pumpWidget(harness(fake));
+    await tester.pumpAndSettle();
+
+    expect(find.text('Wired to the workspace gateway'), findsOneWidget);
+    expect(find.bySemanticsLabel('Gateway status: ok'), findsOneWidget);
+    expect(fake.calls, 1);
+  });
+
+  testWidgets('renders the unreachable state without crashing',
+      (tester) async {
+    final fake = FakeStatusRepository(
+      result: const HealthStatus.unreachable(),
+    );
+
+    await tester.pumpWidget(harness(fake));
+    await tester.pumpAndSettle();
+
+    expect(find.text('Gateway unreachable'), findsOneWidget);
+  });
+
+  testWidgets('the refresh command re-probes the gateway', (tester) async {
+    final fake = FakeStatusRepository();
+
+    await tester.pumpWidget(harness(fake));
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byTooltip('Refresh gateway status'));
+    await tester.pumpAndSettle();
+
+    expect(fake.calls, 2);
+  });
+}

package/src/generators/flutter-app/files/tool/flutter_exec.sh.template

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Toolchain guard for every Nx target of this app. The Flutter SDK is a
+# declared prerequisite, not an assumption: when it is missing, the affected
+# tier reports skipped-with-reason instead of failing cryptically — the same
+# way ./dev degrades when the Docker daemon is absent.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+if ! command -v flutter >/dev/null 2>&1; then
+  echo "flutter SDK not found — tier skipped." >&2
+  echo "Install the Flutter SDK (https://docs.flutter.dev/get-started/install)," >&2
+  echo "then run: npx nx run <%= fileName %>:bootstrap" >&2
+  exit 1
+fi
+
+ensure_platforms() {
+  if [ ! -d android ] && [ ! -d ios ]; then
+    echo "Platform directories missing — run the bootstrap target first:" >&2
+    echo "  npx nx run <%= fileName %>:bootstrap" >&2
+    exit 1
+  fi
+}
+
+case "${1:-}" in
+  bootstrap)
+    # Generation shipped only the Dart-level app (no SDK required). Bootstrap
+    # materializes the platform shells and resolves packages.
+    if [ ! -d android ] && [ ! -d ios ]; then
+      # --empty keeps `flutter create` from adding its counter-app sample
+      # files (test/widget_test.dart references a MyApp this scaffold does not
+      # have); existing scaffold files are never overwritten either way.
+      flutter create . --empty --platforms android,ios --org "<%= org %>" --project-name "<%= pubspecName %>"
+    fi
+    flutter pub get
+    ;;
+  run)
+    ensure_platforms
+    flutter run "${@:2}"
+    ;;
+  build)
+    ensure_platforms
+    flutter build apk --debug "${@:2}"
+    ;;
+  analyze)
+    flutter analyze "${@:2}"
+    ;;
+  test)
+    flutter test "${@:2}"
+    ;;
+  test-integration)
+    ensure_platforms
+    # Runs on a device or emulator; CI uses a headless Android emulator
+    # (docs/principles/stack/flutter/testing.md).
+    flutter test integration_test "${@:2}"
+    ;;
+  *)
+    echo "Usage: tool/flutter_exec.sh {bootstrap|run|build|analyze|test|test-integration}" >&2
+    exit 2
+    ;;
+esac