@bdayadev/flutter-ultra-mcp 1.11.7 → 1.12.0

package/skills/fix-layout-issues/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: fix-layout-issues
+description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
+---
+
+# Resolving Flutter Layout Errors
+
+## Contents
+
+- [Constraint Violation Diagnostics](#constraint-violation-diagnostics)
+- [Layout Error Resolution Workflow](#layout-error-resolution-workflow)
+- [Examples](#examples)
+
+## Constraint Violation Diagnostics
+
+Flutter layout operates on: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails.
+
+- **"Vertical viewport was given unbounded height"**: Scrollable widget (`ListView`, `GridView`) inside unconstrained vertical parent (`Column`).
+- **"An InputDecorator...cannot have an unbounded width"**: `TextField` inside unconstrained horizontal parent (`Row`).
+- **"RenderFlex overflowed"**: Child of `Row` or `Column` requests more size than available. Yellow and black warning stripes.
+- **"Incorrect use of ParentData widget"**: `ParentDataWidget` not a direct descendant of required ancestor (e.g., `Expanded` outside a `Flex`).
+- **"RenderBox was not laid out"**: Cascading side-effect. Look further up the stack trace for the primary violation.
+
+## Layout Error Resolution Workflow
+
+### Task Progress
+
+- [ ] Run the application in debug mode to capture the exception.
+- [ ] Identify the primary error message (ignore cascading errors).
+- [ ] Apply the conditional fix:
+  - **"Unbounded height"**: Wrap scrollable child in `Expanded` or `SizedBox`.
+  - **"Unbounded width"**: Wrap `TextField` in `Expanded` or `Flexible`.
+  - **"RenderFlex overflowed"**: Wrap overflowing child in `Expanded` or `Flexible`.
+  - **"Incorrect ParentData"**: Move the widget to be a direct child of its required parent.
+- [ ] Execute Flutter hot reload.
+- [ ] Verify the error screen or overflow stripes are resolved. Repeat if new errors appear.
+
+## Examples
+
+### Fixing Unbounded Height (ListView in Column)
+
+**Before (Error):**
+
+```dart
+Column(
+  children: <Widget>[
+    const Text('Header'),
+    ListView(
+      children: const <Widget>[
+        ListTile(title: Text('Item 1')),
+        ListTile(title: Text('Item 2')),
+      ],
+    ),
+  ],
+)
+```
+
+**After (Fixed):**
+
+```dart
+Column(
+  children: <Widget>[
+    const Text('Header'),
+    Expanded(
+      child: ListView(
+        children: const <Widget>[
+          ListTile(title: Text('Item 1')),
+          ListTile(title: Text('Item 2')),
+        ],
+      ),
+    ),
+  ],
+)
+```
+
+### Fixing Unbounded Width (TextField in Row)
+
+**Before:** `Row(children: [Icon(Icons.search), TextField()])`
+
+**After:** `Row(children: [Icon(Icons.search), Expanded(child: TextField())])`
+
+### Fixing RenderFlex Overflow
+
+**Before:** `Row(children: [Icon(Icons.info), Text('Very long text...')])`
+
+**After:** `Row(children: [Icon(Icons.info), Expanded(child: Text('Very long text...'))])`
+
+## Flutter Ultra Integration
+
+Diagnose and verify layout fixes with live app inspection:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — Fetch current runtime errors including RenderFlex overflows
+- `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — Inspect render tree to see constraint propagation
+- `mcp__plugin_flutter_flutter-ultra-runtime__toggle_debug_paint` — Toggle debug paint to visualize layout boundaries
+- `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload` — Hot reload after applying fix to verify immediately
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — Capture before/after screenshots of the fix
+
+---
+
+> **Attribution:** This skill is vendored from [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/fix-runtime-errors/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: fix-runtime-errors
+description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
+---
+
+# Resolving Dart Static Analysis Errors
+
+## Contents
+
+- [Core Concepts & Guidelines](#core-concepts--guidelines)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Core Concepts & Guidelines
+
+### Type System & Soundness
+
+Enforce Dart's sound type system to prevent runtime invalid states.
+
+- **Method Overrides:** Maintain sound return types (covariant) and parameter types (contravariant). Never tighten a parameter type in a subclass unless explicitly marked with the `covariant` keyword.
+- **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List<T>`, `Map<K, V>`). Never assign a `List<dynamic>` to a typed list.
+- **Downcasting:** Avoid implicit downcasts from `dynamic`. Use explicit casts (e.g., `as List<Cat>`) when necessary, but ensure the underlying runtime type matches to prevent `TypeError` exceptions.
+- **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting.
+
+### Null Safety
+
+Eliminate static errors related to null safety by correctly managing variable initialization and nullability.
+
+- **Modifiers:** Apply `?` for nullable types, `!` for null assertions, and `required` for named parameters that cannot be null.
+- **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use.
+- **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters.
+
+### Error Handling
+
+Distinguish between recoverable exceptions and unrecoverable errors.
+
+- **Catching:** Catch `Exception` subtypes for recoverable failures.
+- **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught.
+- **Rethrowing:** Use `rethrow` inside a `catch` block to propagate an exception while preserving its original stack trace.
+
+## Workflows
+
+### Workflow: Static Analysis Resolution
+
+**Task Progress:**
+
+- [ ] 1. Run static analyzer.
+- [ ] 2. Apply automated fixes.
+- [ ] 3. Resolve remaining errors manually.
+- [ ] 4. Verify fixes (Feedback Loop).
+
+**1. Run static analyzer**
+
+```bash
+dart analyze . --fatal-infos
+```
+
+**2. Apply automated fixes**
+
+```bash
+dart fix --dry-run
+dart fix --apply
+```
+
+**3. Resolve remaining errors manually**
+
+- **If Null Safety issue:** Verify if the variable can logically be null. Use `?.` or `??` if yes, `late` if initialization is guaranteed elsewhere.
+- **If Type Mismatch:** Add explicit generic type annotations to the instantiation.
+- **If Invalid Override:** Widen the parameter type or add `covariant`.
+
+**4. Verify fixes (Feedback Loop)**
+
+```bash
+dart analyze .
+dart test
+```
+
+## Examples
+
+### Fixing Dynamic List Assignments
+
+**Input (Fails):**
+
+```dart
+void printInts(List<int> a) => print(a);
+
+void main() {
+  final list = []; // Inferred as List<dynamic>
+  list.add(1);
+  printInts(list); // Error
+}
+```
+
+**Output (Passes):**
+
+```dart
+void printInts(List<int> a) => print(a);
+
+void main() {
+  final list = <int>[]; // Explicitly typed
+  list.add(1);
+  printInts(list);
+}
+```
+
+### Fixing Null Safety with `late`
+
+**Input (Fails):**
+
+```dart
+class Thermometer {
+  String temperature; // Error: Non-nullable must be initialized
+  void read() { temperature = '20C'; }
+}
+```
+
+**Output (Passes):**
+
+```dart
+class Thermometer {
+  late String temperature;
+  void read() { temperature = '20C'; }
+}
+```
+
+## Flutter Ultra Integration
+
+Diagnose and fix runtime errors in the live app:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — Fetch active stack traces from the running app
+- `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` — Evaluate expressions in the running isolate
+- `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload` — Hot reload after applying fix to verify immediately
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_logs` — View recent log output for context
+
+---
+
+> **Attribution:** This skill is vendored from [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/generate-test-mocks/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: generate-test-mocks
+description: Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases.
+---
+
+# Testing and Mocking Dart Applications
+
+## Contents
+
+- [Structuring Code for Testability](#structuring-code-for-testability)
+- [Managing Dependencies](#managing-dependencies)
+- [Generating Mocks](#generating-mocks)
+- [Implementing Unit Tests](#implementing-unit-tests)
+- [Workflow: Creating and Running Mocked Tests](#workflow-creating-and-running-mocked-tests)
+- [Examples](#examples)
+
+## Structuring Code for Testability
+
+Design Dart classes to support dependency injection. Isolate complex external dependencies so they can be replaced with mock objects during testing.
+
+- Inject external services (e.g., `http.Client`) through class constructors.
+- Represent URLs strictly as `Uri` objects using `Uri.parse(string)`.
+
+## Managing Dependencies
+
+Configure the `pubspec.yaml` file with the necessary testing and code generation packages.
+
+- Add runtime dependencies (e.g., `package:http`) using `dart pub add http`.
+- Add testing dependencies using `dart pub add dev:test dev:mockito dev:build_runner`.
+- Import HTTP libraries with a prefix: `import 'package:http/http.dart' as http;`.
+
+## Generating Mocks
+
+Use `package:mockito` and `build_runner` to automatically generate mock classes.
+
+- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks`).
+- Place the annotation in the test file, passing a list of `MockSpec<Type>()` objects.
+- Import the generated file using the `.mocks.dart` extension.
+- Execute `build_runner` to generate the mock files: `dart run build_runner build`.
+
+## Implementing Unit Tests
+
+Isolate the system under test using the generated mock objects.
+
+- **Stubbing:** Use `when(mock.method()).thenReturn(value)` for synchronous methods.
+- **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
+- **Verification:** Use `verify(mock.method()).called(1)` to check exact invocation counts.
+
+## Workflow: Creating and Running Mocked Tests
+
+### Task Progress
+
+- [ ] 1. Identify the external dependency to mock.
+- [ ] 2. Inject the dependency into the target class constructor.
+- [ ] 3. Create a test file and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
+- [ ] 4. Add the import directive for the generated `.mocks.dart` file.
+- [ ] 5. Run `dart run build_runner build` to generate the mock classes.
+- [ ] 6. Write the test cases using `group()` and `test()`.
+- [ ] 7. Stub required behaviors using `when()`.
+- [ ] 8. Execute the target method.
+- [ ] 9. Verify interactions using `verify()` and assert outcomes using `expect()`.
+- [ ] 10. Run the test suite using `dart test`.
+
+## Examples
+
+### High-Fidelity Mocking and Testing Example
+
+**System Under Test (`lib/api_service.dart`):**
+
+```dart
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+
+class ApiService {
+  final http.Client client;
+  ApiService(this.client);
+
+  Future<String> fetchData(String urlString) async {
+    final uri = Uri.parse(urlString);
+    final response = await client.get(uri);
+    if (response.statusCode == 200) {
+      return jsonDecode(response.body)['data'];
+    } else {
+      throw Exception('Failed to load data');
+    }
+  }
+}
+```
+
+**Test Implementation (`test/api_service_test.dart`):**
+
+```dart
+import 'package:test/test.dart';
+import 'package:mockito/annotations.dart';
+import 'package:mockito/mockito.dart';
+import 'package:http/http.dart' as http;
+import 'package:my_app/api_service.dart';
+
+@GenerateNiceMocks([MockSpec<http.Client>()])
+import 'api_service_test.mocks.dart';
+
+void main() {
+  group('ApiService', () {
+    late ApiService apiService;
+    late MockClient mockHttpClient;
+
+    setUp(() {
+      mockHttpClient = MockClient();
+      apiService = ApiService(mockHttpClient);
+    });
+
+    test('returns data if the http call completes successfully', () async {
+      when(mockHttpClient.get(any)).thenAnswer(
+        (_) async => http.Response('{"data": "Success"}', 200),
+      );
+
+      final result = await apiService.fetchData('https://api.example.com/data');
+      expect(result, 'Success');
+      verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1);
+    });
+
+    test('throws an exception if the http call completes with an error', () {
+      when(mockHttpClient.get(any)).thenAnswer(
+        (_) async => http.Response('Not Found', 404),
+      );
+
+      expect(
+        apiService.fetchData('https://api.example.com/data'),
+        throwsException,
+      );
+    });
+  });
+}
+```
+
+## Flutter Ultra Integration
+
+Run build_runner to generate mock classes:
+
+- `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` — Run build_runner to generate \*.mocks.dart files
+- `mcp__plugin_flutter_flutter-ultra-build__poll_build_runner_job` — Monitor generation progress
+- `mcp__plugin_flutter_flutter-ultra-build__get_build_runner_result` — Check for generation errors
+
+---
+
+> **Attribution:** This skill is vendored from [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/implement-json-serialization/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: implement-json-serialization
+description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
+---
+
+# Serializing JSON Manually in Flutter
+
+## Contents
+
+- [Core Guidelines](#core-guidelines)
+- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model)
+- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json)
+- [Examples](#examples)
+
+## Core Guidelines
+
+- **Import `dart:convert`**: Use `jsonEncode` and `jsonDecode`.
+- **Enforce Type Safety**: Cast `jsonDecode()` result to `Map<String, dynamic>` or `List<dynamic>`.
+- **Encapsulate Logic**: Define `fromJson` factory constructor and `toJson` method in model classes.
+- **Handle Background Parsing**: If parsing takes >16ms, use `compute()` to prevent UI jank.
+- **Throw on Failure**: Throw an exception on non-success HTTP status codes. Do not return `null`.
+
+## Workflow: Implementing a Serializable Model
+
+**Task Progress:**
+
+- [ ] Define the plain model class with `final` properties.
+- [ ] Implement `factory Model.fromJson(Map<String, dynamic> json)`.
+- [ ] Implement `Map<String, dynamic> toJson()`.
+- [ ] Write unit tests for both methods.
+- [ ] Run validator -> review type mismatch errors -> fix casting logic.
+
+## Workflow: Fetching and Parsing JSON
+
+**Task Progress:**
+
+- [ ] Execute the HTTP request.
+- [ ] Validate the response status code.
+- [ ] Determine parsing strategy:
+  - **Small payload**: Parse synchronously on the main thread.
+  - **Large payload**: Use `compute(parseFunction, response.body)`.
+- [ ] Decode and map the JSON to the model.
+
+## Examples
+
+### Model Implementation
+
+```dart
+import 'dart:convert';
+
+class User {
+  final int id;
+  final String name;
+  final String email;
+
+  const User({required this.id, required this.name, required this.email});
+
+  factory User.fromJson(Map<String, dynamic> json) {
+    return switch (json) {
+      {'id': int id, 'name': String name, 'email': String email} =>
+        User(id: id, name: name, email: email),
+      _ => throw const FormatException('Failed to load User.'),
+    };
+  }
+
+  Map<String, dynamic> toJson() => {'id': id, 'name': name, 'email': email};
+}
+```
+
+### Background Parsing (Large Payload)
+
+```dart
+import 'dart:convert';
+import 'package:flutter/foundation.dart';
+import 'package:http/http.dart' as http;
+
+List<User> parseUsers(String responseBody) {
+  final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
+  return parsed.map<User>((json) => User.fromJson(json)).toList();
+}
+
+Future<List<User>> fetchUsers(http.Client client) async {
+  final response = await client.get(Uri.parse('https://api.example.com/users'));
+  if (response.statusCode == 200) {
+    return compute(parseUsers, response.body);
+  } else {
+    throw Exception('Failed to load users');
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+If using code generation (json_serializable), run the build runner:
+
+- `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` — Run build_runner to generate serialization code
+- `mcp__plugin_flutter_flutter-ultra-build__poll_build_runner_job` — Monitor code generation progress
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Verify generated code has no analysis errors
+
+---
+
+> **Attribution:** This skill is vendored from [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/migrate-to-checks-package/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: migrate-to-checks-package
+description: Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
+---
+
+# Migrating Dart Tests to Package Checks
+
+## Contents
+
+- [Dependency Management](#dependency-management)
+- [Syntax Migration Guidelines](#syntax-migration-guidelines)
+- [Migration Workflow](#migration-workflow)
+- [Examples](#examples)
+
+## Dependency Management
+
+- Add `package:checks` as a `dev_dependency` using `dart pub add dev:checks`.
+- Remove `package:matcher` if it is explicitly listed in the `pubspec.yaml` (note: it is often transitively included by `package:test`, which is fine).
+- Import `package:checks/checks.dart` in all test files undergoing migration.
+
+## Syntax Migration Guidelines
+
+Transition test assertions from the `package:matcher` syntax to the literate API provided by `package:checks`.
+
+- **Basic Equality:** Replace `expect(actual, equals(expected))` with `check(actual).equals(expected)`.
+- **Type Checking:** Replace `expect(actual, isA<Type>())` with `check(actual).isA<Type>()`.
+- **Property Extraction:** Replace `expect(actual.property, expected)` with `check(actual).has((a) => a.property, 'property name').equals(expected)`.
+- **Cascades for Multiple Checks:** Use Dart's cascade operator (`..`) to chain multiple expectations on a single subject.
+- **Asynchronous Expectations:**
+  - If checking a `Future`, `await` the `check` call: `await check(someFuture).completes((r) => r.equals(expected));`.
+  - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks.
+
+## Migration Workflow
+
+- [ ] Add `package:checks` as a dev dependency.
+- [ ] Identify all test files using `package:matcher` (`expect` calls).
+- [ ] Import `package:checks/checks.dart` in target test files.
+- [ ] Rewrite all `expect(...)` statements to `check(...)` statements.
+- [ ] Run static analyzer.
+- [ ] Run tests.
+
+### Feedback Loop: Static Analysis
+
+1. Run the analyzer on the modified test directories.
+2. Review any static analysis warnings or errors.
+3. Fix the warnings.
+4. Repeat until zero issues.
+
+### Feedback Loop: Test Validation
+
+1. Run the tests.
+2. If tests fail, review the failure output. `package:checks` provides detailed context.
+3. Adjust the `check()` expectations or the underlying code.
+4. Repeat until all tests pass.
+
+## Examples
+
+### Basic Assertions
+
+**Input (`matcher`):**
+
+```dart
+expect(someList.length, 1);
+expect(someString, startsWith('a'));
+expect(someObject, isA<Map>());
+```
+
+**Output (`checks`):**
+
+```dart
+check(someList).length.equals(1);
+check(someString).startsWith('a');
+check(someObject).isA<Map>();
+```
+
+### Composed Expectations
+
+**Input (`matcher`):**
+
+```dart
+expect('foo,bar,baz', allOf([
+  contains('foo'),
+  isNot(startsWith('bar')),
+  endsWith('baz')
+]));
+```
+
+**Output (`checks`):**
+
+```dart
+check('foo,bar,baz')
+  ..contains('foo')
+  ..not((s) => s.startsWith('bar'))
+  ..endsWith('baz');
+```
+
+### Asynchronous Futures
+
+**Input (`matcher`):**
+
+```dart
+expect(Future.value(10), completion(equals(10)));
+expect(Future.error('oh no'), throwsA(equals('oh no')));
+```
+
+**Output (`checks`):**
+
+```dart
+await check(Future.value(10)).completes((it) => it.equals(10));
+await check(Future.error('oh no')).throws<String>().equals('oh no');
+```
+
+## Flutter Ultra Integration
+
+Validate the migration with static analysis and tests:
+
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Check for type errors after migration
+- `mcp__plugin_flutter_flutter-ultra-build__fix` — Apply automated fixes for simple migrations
+- `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` — Run tests to verify migration didn't break assertions
+
+---
+
+> **Attribution:** This skill is vendored from [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.