{
  "mcpServers": {
    "dart": {
      "command": "dart",
      "args": [
        "mcp-server",
        "--force-roots-fallback"
      ],
      "env": {}
    }
  }
}

# Start Flutter on your target device/emulator and print the DTD connection URI
flutter run --print-dtd

# Example output:
# The Dart Tooling Daemon is listening on ws://127.0.0.1:58432/AbCdEfGhIjKl=/
# Your agent passes this URI to the `connect_dart_tooling_daemon` MCP tool!

# AGENTS.md | Flutter & Dart Engineering Constitution

These architectural and verification rules are mandatory across all files in this repository.

## 1. Strict Layered Architecture & Dependency Rule
- `lib/domain/`: Pure Dart only. Contains immutable entities, value objects, `sealed class Result<T>`, and `abstract interface class` repository contracts.
  - FORBIDDEN in `lib/domain/`: Never import `package:flutter/...`, `package:flutter_bloc/...`, HTTP clients, or JSON serialization packages.
- `lib/application/`: State management (`Cubit` / `Bloc`) and use-case orchestration.
  - Every state hierarchy MUST be a `sealed class` with `final class` subtypes (`Initial`, `Loading`, `Loaded`, `Error`).
- `lib/main.dart` & `lib/presentation/`: Flutter widgets consuming `Cubit`/`Bloc` states via exhaustive Dart 3 `switch` expressions.
  - Widgets MUST NOT instantiate repositories directly or perform raw I/O inside `build()`.

## 2. Error Handling & Type Safety Invariants
- Never throw raw strings or swallow exceptions with empty `catch (_) {}` blocks.
- All repository methods that can fail MUST return `Future<Result<T>>` (`Success<T>` or `Failure<T>` with `message` and `code`).
- Always use `const` constructors wherever possible and enable `prefer_const_constructors`.

## 3. UI Design Tokens & Accessibility
- Surface Primary: `Color(0xFF070A13)` | Surface Card: `Color(0xFF0F1424)` | Border: `Color(0xFF202B46)`
- Accent Cyan: `Color(0xFF00B0FF)` | Accent Blue: `Color(0xFF02569B)`
- Status Nominal: `Color(0xFF10B981)` | Degraded: `Color(0xFFF59E0B)` | Critical: `Color(0xFFEF4444)`
- Zero gradients: use solid fills and crisp `1px` borders (`Border.all(color: Color(0xFF202B46))`).
- Every interactive `IconButton` or action button MUST include a stable `Key(...)` for deterministic widget testing and a descriptive `tooltip`.

## 4. Mandatory MCP & Verification Workflow
1. Before adding any dependency, query `pub_dev_search` via the Dart MCP server.
2. After creating or modifying any Dart file, run the `analyze_files` MCP tool (or `flutter analyze --fatal-infos`).
3. Never report a task as finished until `flutter analyze --fatal-infos` and `flutter test` pass with 0 warnings and 0 failures.

---
name: flutter-clean-feature
description: Step-by-step playbook for scaffolding, wiring, and widget-testing a layered Flutter feature with pure Dart domain models, Cubit state management, and exhaustive switch expressions. Use whenever creating or refactoring a Flutter feature.
---

# Flutter Clean Feature Scaffolding Playbook

Follow these exact steps in order whenever asked to create or update a feature:

## Step 1: Pure Domain Layer (`lib/domain/<feature>.dart`)
1. Define immutable entities with `final` fields, `const` constructors, and `copyWith`.
2. Compute derived domain properties (such as `HealthStatus`) via pure getters on the entity.
3. Define repository contracts as `abstract interface class` returning `Future<Result<T>>`.
4. Verify zero `package:flutter/` imports in this file.

## Step 2: Application State & Cubit (`lib/application/<feature>_cubit.dart`)
1. Declare a `sealed class <Feature>State` with `const` constructor.
2. Create four `final class` subtypes: `Initial`, `Loading`, `Loaded`, and `Error`.
3. In the `Cubit`, emit `Loading`, await the repository's `Result<T>`, and use an exhaustive `switch (result)` with pattern destructuring (`case Success(:final value):`, `case Failure(:final message, :final code):`).

## Step 3: Presentation Layer (`lib/main.dart` or `lib/presentation/`)
1. Inject the `Cubit` via `BlocProvider` and render state via `BlocBuilder`.
2. Use an exhaustive `switch (state)` expression inside `BlocBuilder.builder`.
3. Attach explicit `const Key('...')` identifiers to loading indicators, status badges, and action buttons.

## Step 4: Mandatory Verification
1. Write a `testWidgets` test in `test/<feature>_widget_test.dart` covering both the nominal `Loaded` path and the `Error` recovery path.
2. Call `analyze_files` via the Dart MCP server and run `flutter test`.

name: agentic_telemetry_demo
description: Deterministic Flutter feature governed by AGENTS.md, Skills, and Dart MCP.
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.8.0

dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^9.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true

// lib/domain/telemetry_snapshot.dart
// Pure Dart domain layer: zero Flutter UI or platform imports allowed.

sealed class Result<T> {
  const Result();
}

final class Success<T> extends Result<T> {
  final T value;
  const Success(this.value);
}

final class Failure<T> extends Result<T> {
  final String message;
  final String code;
  const Failure({required this.message, required this.code});
}

enum HealthStatus { nominal, degraded, critical }

final class TelemetrySnapshot {
  final String nodeId;
  final int latencyMs;
  final double memoryUsageMb;
  final int activeIsolates;
  final DateTime recordedAt;

  const TelemetrySnapshot({
    required this.nodeId,
    required this.latencyMs,
    required this.memoryUsageMb,
    required this.activeIsolates,
    required this.recordedAt,
  });

  HealthStatus get status {
    if (latencyMs >= 500 || memoryUsageMb >= 512.0) {
      return HealthStatus.critical;
    }
    if (latencyMs >= 200 || memoryUsageMb >= 256.0) {
      return HealthStatus.degraded;
    }
    return HealthStatus.nominal;
  }

  TelemetrySnapshot copyWith({
    String? nodeId,
    int? latencyMs,
    double? memoryUsageMb,
    int? activeIsolates,
    DateTime? recordedAt,
  }) {
    return TelemetrySnapshot(
      nodeId: nodeId ?? this.nodeId,
      latencyMs: latencyMs ?? this.latencyMs,
      memoryUsageMb: memoryUsageMb ?? this.memoryUsageMb,
      activeIsolates: activeIsolates ?? this.activeIsolates,
      recordedAt: recordedAt ?? this.recordedAt,
    );
  }
}

abstract interface class TelemetryRepository {
  Future<Result<TelemetrySnapshot>> fetchLatestSnapshot({
    required String nodeId,
  });
}

// lib/application/telemetry_cubit.dart
import 'package:flutter_bloc/flutter_bloc.dart';
import '../domain/telemetry_snapshot.dart';

sealed class TelemetryState {
  const TelemetryState();
}

final class TelemetryInitial extends TelemetryState {
  const TelemetryInitial();
}

final class TelemetryLoading extends TelemetryState {
  const TelemetryLoading();
}

final class TelemetryLoaded extends TelemetryState {
  final TelemetrySnapshot snapshot;
  const TelemetryLoaded(this.snapshot);
}

final class TelemetryError extends TelemetryState {
  final String message;
  final String code;
  const TelemetryError({required this.message, required this.code});
}

class InMemoryTelemetryRepository implements TelemetryRepository {
  bool simulateFailure;
  final Duration latency;

  InMemoryTelemetryRepository({
    this.simulateFailure = false,
    this.latency = const Duration(milliseconds: 120),
  });

  @override
  Future<Result<TelemetrySnapshot>> fetchLatestSnapshot({
    required String nodeId,
  }) async {
    await Future<void>.delayed(latency);
    if (simulateFailure) {
      return const Failure<TelemetrySnapshot>(
        message: 'Telemetry node unreachable over local socket.',
        code: 'ERR_NODE_TIMEOUT',
      );
    }
    return Success<TelemetrySnapshot>(
      TelemetrySnapshot(
        nodeId: nodeId,
        latencyMs: 42,
        memoryUsageMb: 118.4,
        activeIsolates: 3,
        recordedAt: DateTime.utc(2026, 10, 28, 12, 0),
      ),
    );
  }
}

class TelemetryCubit extends Cubit<TelemetryState> {
  final TelemetryRepository _repository;

  TelemetryCubit(this._repository) : super(const TelemetryInitial());

  Future<void> refreshSnapshot({String nodeId = 'edge-node-kampala-01'}) async {
    emit(const TelemetryLoading());
    final result = await _repository.fetchLatestSnapshot(nodeId: nodeId);
    switch (result) {
      case Success<TelemetrySnapshot>(:final value):
        emit(TelemetryLoaded(value));
      case Failure<TelemetrySnapshot>(:final message, :final code):
        emit(TelemetryError(message: message, code: code));
    }
  }
}

// lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'application/telemetry_cubit.dart';
import 'domain/telemetry_snapshot.dart';

void main() {
  final repository = InMemoryTelemetryRepository();
  runApp(AgenticTelemetryApp(repository: repository));
}

class AgenticTelemetryApp extends StatelessWidget {
  final InMemoryTelemetryRepository repository;

  const AgenticTelemetryApp({super.key, required this.repository});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Agentic Telemetry Monitor',
      debugShowCheckedModeBanner: false,
      theme: ThemeData.dark().copyWith(
        scaffoldBackgroundColor: const Color(0xFF070A13),
        colorScheme: const ColorScheme.dark(
          primary: Color(0xFF00B0FF),
          secondary: Color(0xFF02569B),
          surface: Color(0xFF0F1424),
        ),
      ),
      home: BlocProvider<TelemetryCubit>(
        create: (_) => TelemetryCubit(repository)..refreshSnapshot(),
        child: TelemetryDashboardScreen(repository: repository),
      ),
    );
  }
}

class TelemetryDashboardScreen extends StatelessWidget {
  final InMemoryTelemetryRepository repository;

  const TelemetryDashboardScreen({super.key, required this.repository});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: const Color(0xFF0F1424),
        title: const Text('Edge Telemetry Monitor'),
        actions: [
          IconButton(
            key: const Key('toggle_failure_btn'),
            tooltip: 'Toggle simulated socket failure',
            icon: const Icon(Icons.bug_report_outlined),
            onPressed: () {
              repository.simulateFailure = !repository.simulateFailure;
              context.read<TelemetryCubit>().refreshSnapshot();
            },
          ),
          IconButton(
            key: const Key('refresh_telemetry_btn'),
            tooltip: 'Refresh telemetry snapshot',
            icon: const Icon(Icons.refresh),
            onPressed: () => context.read<TelemetryCubit>().refreshSnapshot(),
          ),
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(24),
        child: BlocBuilder<TelemetryCubit, TelemetryState>(
          builder: (context, state) {
            return switch (state) {
              TelemetryInitial() => const Center(
                child: Text('Ready to query telemetry node.'),
              ),
              TelemetryLoading() => const Center(
                child: CircularProgressIndicator(
                  key: Key('telemetry_loading_indicator'),
                ),
              ),
              TelemetryLoaded(:final snapshot) => _TelemetryMetricView(
                snapshot: snapshot,
              ),
              TelemetryError(:final message, :final code) => _TelemetryErrorView(
                message: message,
                code: code,
                onRetry: () {
                  repository.simulateFailure = false;
                  context.read<TelemetryCubit>().refreshSnapshot();
                },
              ),
            };
          },
        ),
      ),
    );
  }
}

class _TelemetryMetricView extends StatelessWidget {
  final TelemetrySnapshot snapshot;

  const _TelemetryMetricView({required this.snapshot});

  @override
  Widget build(BuildContext context) {
    final statusColor = switch (snapshot.status) {
      HealthStatus.nominal => const Color(0xFF10B981),
      HealthStatus.degraded => const Color(0xFFF59E0B),
      HealthStatus.critical => const Color(0xFFEF4444),
    };

    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        Container(
          padding: const EdgeInsets.all(16),
          decoration: BoxDecoration(
            color: const Color(0xFF0F1424),
            border: Border.all(color: const Color(0xFF202B46)),
            borderRadius: BorderRadius.circular(12),
          ),
          child: Row(
            mainAxisAlignment: MainAxisAlignment.spaceBetween,
            children: [
              Text(
                'Node: ${snapshot.nodeId}',
                style: const TextStyle(
                  fontSize: 16,
                  fontWeight: FontWeight.w600,
                ),
              ),
              Container(
                padding: const EdgeInsets.symmetric(
                  horizontal: 12,
                  vertical: 4,
                ),
                decoration: BoxDecoration(
                  color: statusColor.withValues(alpha: 0.15),
                  border: Border.all(color: statusColor),
                  borderRadius: BorderRadius.circular(999),
                ),
                child: Text(
                  snapshot.status.name.toUpperCase(),
                  key: const Key('health_status_badge'),
                  style: TextStyle(
                    color: statusColor,
                    fontWeight: FontWeight.w700,
                    fontSize: 12,
                  ),
                ),
              ),
            ],
          ),
        ),
        const SizedBox(height: 16),
        Row(
          children: [
            Expanded(
              child: _MetricTile(
                label: 'Latency',
                value: '${snapshot.latencyMs} ms',
              ),
            ),
            const SizedBox(width: 16),
            Expanded(
              child: _MetricTile(
                label: 'Heap RAM',
                value: '${snapshot.memoryUsageMb.toStringAsFixed(1)} MB',
              ),
            ),
            const SizedBox(width: 16),
            Expanded(
              child: _MetricTile(
                label: 'Isolates',
                value: '${snapshot.activeIsolates}',
              ),
            ),
          ],
        ),
      ],
    );
  }
}

class _MetricTile extends StatelessWidget {
  final String label;
  final String value;

  const _MetricTile({required this.label, required this.value});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(16),
      decoration: BoxDecoration(
        color: const Color(0xFF0F1424),
        border: Border.all(color: const Color(0xFF202B46)),
        borderRadius: BorderRadius.circular(12),
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            label,
            style: const TextStyle(color: Color(0xFF94A3B8), fontSize: 13),
          ),
          const SizedBox(height: 8),
          Text(
            value,
            style: const TextStyle(
              color: Color(0xFFF8FAFC),
              fontSize: 20,
              fontWeight: FontWeight.w700,
            ),
          ),
        ],
      ),
    );
  }
}

class _TelemetryErrorView extends StatelessWidget {
  final String message;
  final String code;
  final VoidCallback onRetry;

  const _TelemetryErrorView({
    required this.message,
    required this.code,
    required this.onRetry,
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(16),
      decoration: BoxDecoration(
        color: const Color(0xFF0F1424),
        border: Border.all(color: const Color(0xFFEF4444)),
        borderRadius: BorderRadius.circular(12),
      ),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            'Error [$code]',
            style: const TextStyle(
              color: Color(0xFFEF4444),
              fontWeight: FontWeight.w700,
              fontSize: 16,
            ),
          ),
          const SizedBox(height: 8),
          Text(message),
          const SizedBox(height: 16),
          ElevatedButton(
            key: const Key('retry_telemetry_btn'),
            onPressed: onRetry,
            child: const Text('Retry Connection'),
          ),
        ],
      ),
    );
  }
}

// tools/architecture_mcp_server.dart
// Run with: dart run tools/architecture_mcp_server.dart
import 'dart:convert';
import 'dart:io';
import 'package:genkit/genkit.dart';
import 'package:genkit_mcp/genkit_mcp.dart';
import 'package:schemantic/schemantic.dart';

void main() async {
  final ai = Genkit();

  // 1. Expose an MCP Tool that audits lib/domain/ for layer boundary violations
  ai.defineTool(
    name: 'checkLayerImports',
    description:
        'Scans lib/domain/ to verify zero package:flutter, flutter_bloc, or data-layer imports.',
    inputSchema: SchemanticType.map(
      SchemanticType.string(),
      SchemanticType.dynamicSchema(),
    ),
    fn: (input, _) async {
      final domainPath = (input['domainPath'] as String?) ?? 'lib/domain';
      final dir = Directory(domainPath);
      if (!dir.existsSync()) {
        return jsonEncode({
          'status': 'error',
          'message': 'Directory $domainPath does not exist.',
        });
      }

      final violations = <String>[];
      final forbiddenPatterns = [
        'package:flutter/',
        'package:flutter_bloc/',
        '/data/',
        '/presentation/',
      ];

      await for (final entity in dir.list(recursive: true)) {
        if (entity is File && entity.path.endsWith('.dart')) {
          final lines = await entity.readAsLines();
          for (var i = 0; i < lines.length; i++) {
            final line = lines[i].trim();
            if (line.startsWith('import ')) {
              for (final pattern in forbiddenPatterns) {
                if (line.contains(pattern)) {
                  violations.add('${entity.path}:${i + 1} -> $line');
                }
              }
            }
          }
        }
      }

      return jsonEncode({
        'status': violations.isEmpty ? 'passed' : 'failed',
        'checkedDirectory': domainPath,
        'violationCount': violations.length,
        'violations': violations,
      });
    },
  );

  // 2. Expose an MCP Resource serving canonical UI design tokens
  ai.defineResource(
    name: 'design-tokens',
    uri: 'project://design-tokens',
    fn: (_, _) async => ResourceOutput(
      content: [
        TextPart(
          text: jsonEncode({
            'surfacePrimary': '#070A13',
            'surfaceCard': '#0F1424',
            'borderColor': '#202B46',
            'accentCyan': '#00B0FF',
            'accentBlue': '#02569B',
            'statusNominal': '#10B981',
            'statusDegraded': '#F59E0B',
            'statusCritical': '#EF4444',
          }),
        ),
      ],
    ),
  );

  // 3. Start the MCP Server over stdio transport
  final server = createMcpServer(
    ai,
    McpServerOptions(name: 'flutter-arch-guard', version: '1.0.0'),
  );
  await server.start();
}

{
  "mcpServers": {
    "dart": {
      "command": "dart",
      "args": ["mcp-server", "--force-roots-fallback"]
    },
    "flutter-arch-guard": {
      "command": "dart",
      "args": ["run", "tools/architecture_mcp_server.dart"]
    }
  }
}

// test/telemetry_widget_test.dart
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:agentic_telemetry_demo/application/telemetry_cubit.dart';
import 'package:agentic_telemetry_demo/main.dart';

void main() {
  testWidgets(
    'renders nominal telemetry metrics and recovers from simulated failure',
    (WidgetTester tester) async {
      final repository = InMemoryTelemetryRepository(
        latency: const Duration(milliseconds: 10),
      );

      await tester.pumpWidget(AgenticTelemetryApp(repository: repository));

      // Initially loading while async repository resolves
      expect(
        find.byKey(const Key('telemetry_loading_indicator')),
        findsOneWidget,
      );

      await tester.pumpAndSettle();

      // Verify nominal loaded state
      expect(find.text('Node: edge-node-kampala-01'), findsOneWidget);
      expect(find.byKey(const Key('health_status_badge')), findsOneWidget);
      expect(find.text('NOMINAL'), findsOneWidget);
      expect(find.text('42 ms'), findsOneWidget);
      expect(find.text('118.4 MB'), findsOneWidget);

      // Trigger simulated failure via the app bar action button
      await tester.tap(find.byKey(const Key('toggle_failure_btn')));
      await tester.pumpAndSettle();

      expect(find.text('Error [ERR_NODE_TIMEOUT]'), findsOneWidget);
      expect(
        find.text('Telemetry node unreachable over local socket.'),
        findsOneWidget,
      );

      // Recover by tapping Retry Connection
      await tester.tap(find.byKey(const Key('retry_telemetry_btn')));
      await tester.pumpAndSettle();

      expect(find.text('NOMINAL'), findsOneWidget);
    },
  );
}

# macOS / Linux / Git Bash
dart format --output=none --set-exit-if-changed lib test && \
flutter analyze --fatal-infos && \
flutter test --reporter expanded

# Windows PowerShell
dart format --output=none --set-exit-if-changed lib test; if ($LASTEXITCODE -eq 0) { flutter analyze --fatal-infos }; if ($LASTEXITCODE -eq 0) { flutter test --reporter expanded }