@bdayadev/flutter-ultra-mcp 1.11.7 → 1.13.0

package/skills/use-http-package/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: use-http-package
+description: Use the `http` package to execute GET, POST, PUT, or DELETE requests. Use when you need to fetch from or send data to a REST API.
+  last_modified: Tue, 21 Apr 2026 21:36:42 GMT
+---
+
+# Implementing Flutter Networking
+
+## Contents
+
+- [Configuration & Permissions](#configuration--permissions)
+- [Request Execution & Response Handling](#request-execution--response-handling)
+- [Background Parsing](#background-parsing)
+- [Workflow: Executing Network Operations](#workflow-executing-network-operations)
+- [Examples](#examples)
+
+## Configuration & Permissions
+
+Configure the environment and platform-specific permissions required for network access.
+
+1. Add the `http` package dependency via the terminal:
+   ```bash
+   flutter pub add http
+   ```
+2. Import the package in your Dart files:
+   ```dart
+   import 'package:http/http.dart' as http;
+   ```
+3. Configure Android permissions by adding the Internet permission to `android/app/src/main/AndroidManifest.xml`:
+   ```xml
+   <uses-permission android:name="android.permission.INTERNET" />
+   ```
+4. Configure macOS entitlements by adding the network client key to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:
+   ```xml
+   <key>com.apple.security.network.client</key>
+   <true/>
+   ```
+
+## Request Execution & Response Handling
+
+Execute HTTP operations and map responses to strongly typed Dart objects.
+
+- **URIs:** Always parse URL strings using `Uri.parse('your_url')`.
+- **Headers:** Inject authorization and content-type headers via the `headers` parameter map. Use `HttpHeaders.authorizationHeader` for auth tokens.
+- **Payloads:** For POST and PUT requests, encode the body using `jsonEncode()` from `dart:convert`.
+- **Status Validation:** Evaluate `response.statusCode`. Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success.
+- **Error Handling:** Throw explicit exceptions for non-success status codes. Never return `null` on failure, as this prevents `FutureBuilder` from triggering its error state and causes infinite loading indicators.
+- **Deserialization:** Parse the raw string using `jsonDecode(response.body)` and map it to a custom Dart object using a factory constructor (e.g., `fromJson`).
+
+## Background Parsing
+
+Offload expensive JSON parsing to a separate Isolate to prevent UI jank (frame drops).
+
+- Import `package:flutter/foundation.dart`.
+- Use the `compute()` function to run the parsing logic in a background isolate.
+- Ensure the parsing function passed to `compute()` is a top-level function or a static method, as closures or instance methods cannot be passed across isolates.
+
+## Workflow: Executing Network Operations
+
+Use the following checklist to implement and validate network operations.
+
+**Task Progress:**
+
+- [ ] 1. Define the strongly typed Dart model with a `fromJson` factory constructor.
+- [ ] 2. Implement the network request method returning a `Future<Model>`.
+- [ ] 3. Apply conditional logic based on the operation type:
+  - **If fetching data (GET):** Append query parameters to the URI.
+  - **If mutating data (POST/PUT):** Set `'Content-Type': 'application/json; charset=UTF-8'` and attach the `jsonEncode` body.
+  - **If deleting data (DELETE):** Return an empty model instance on success (`200 OK`).
+- [ ] 4. Validate the `statusCode` and throw an `Exception` on failure.
+- [ ] 5. Integrate the `Future` into the UI using `FutureBuilder`.
+- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, and default to a `CircularProgressIndicator`.
+- [ ] 7. **Feedback Loop:** Run the app -> trigger the network request -> review console for unhandled exceptions -> fix parsing or permission errors.
+
+## Examples
+
+### High-Fidelity Implementation: Fetching and Parsing in the Background
+
+```dart
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:http/http.dart' as http;
+
+// 1. Top-level parsing function for Isolate
+List<Photo> parsePhotos(String responseBody) {
+  final parsed = (jsonDecode(responseBody) as List<Object?>)
+      .cast<Map<String, Object?>>();
+  return parsed.map<Photo>(Photo.fromJson).toList();
+}
+
+// 2. Network execution with background parsing
+Future<List<Photo>> fetchPhotos() async {
+  final response = await http.get(
+    Uri.parse('https://jsonplaceholder.typicode.com/photos'),
+    headers: {
+      HttpHeaders.authorizationHeader: 'Bearer your_token_here',
+      HttpHeaders.acceptHeader: 'application/json',
+    },
+  );
+
+  if (response.statusCode == 200) {
+    // Offload heavy parsing to a background isolate
+    return compute(parsePhotos, response.body);
+  } else {
+    throw Exception('Failed to load photos. Status: ${response.statusCode}');
+  }
+}
+
+// 3. Strongly typed model
+class Photo {
+  final int id;
+  final String title;
+  final String thumbnailUrl;
+
+  const Photo({
+    required this.id,
+    required this.title,
+    required this.thumbnailUrl,
+  });
+
+  factory Photo.fromJson(Map<String, dynamic> json) {
+    return Photo(
+      id: json['id'] as int,
+      title: json['title'] as String,
+      thumbnailUrl: json['thumbnailUrl'] as String,
+    );
+  }
+}
+
+// 4. UI Integration
+class PhotoGallery extends StatefulWidget {
+  const PhotoGallery({super.key});
+
+  @override
+  State<PhotoGallery> createState() => _PhotoGalleryState();
+}
+
+class _PhotoGalleryState extends State<PhotoGallery> {
+  late Future<List<Photo>> _futurePhotos;
+
+  @override
+  void initState() {
+    super.initState();
+    // Initialize Future once to prevent re-fetching on rebuilds
+    _futurePhotos = fetchPhotos();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return FutureBuilder<List<Photo>>(
+      future: _futurePhotos,
+      builder: (context, snapshot) {
+        if (snapshot.hasData) {
+          final photos = snapshot.data!;
+          return ListView.builder(
+            itemCount: photos.length,
+            itemBuilder: (context, index) => ListTile(
+              leading: Image.network(photos[index].thumbnailUrl),
+              title: Text(photos[index].title),
+            ),
+          );
+        } else if (snapshot.hasError) {
+          return Center(child: Text('Error: ${snapshot.error}'));
+        }
+
+        // Default loading state
+        return const Center(child: CircularProgressIndicator());
+      },
+    );
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+Monitor and debug HTTP calls in the running app:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__start_http_capture` — Start capturing HTTP traffic
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_http_events` — View captured HTTP requests and responses
+- `mcp__plugin_flutter_flutter-ultra-runtime__stop_http_capture` — Stop HTTP capture
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — Check for unhandled HTTP exceptions
+
+---
+
+> **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/use-pattern-matching/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: use-pattern-matching
+description: Use switch expressions and pattern matching where appropriate
+  last_modified: Fri, 24 Apr 2026 15:08:55 GMT
+---
+
+# Implementing Dart Patterns
+
+## Contents
+
+- [Pattern Selection Strategy](#pattern-selection-strategy)
+- [Switch Statements vs. Expressions](#switch-statements-vs-expressions)
+- [Core Pattern Implementations](#core-pattern-implementations)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Pattern Selection Strategy
+
+Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines:
+
+- **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs.
+- **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables.
+- **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness.
+- **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns.
+- **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause.
+- **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections.
+
+## Switch Statements vs. Expressions
+
+Select the appropriate switch construct based on the execution context:
+
+- **If producing a value:** Use a **switch expression**.
+  - Syntax: `switch (value) { pattern => expression, }`
+  - Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive.
+- **If executing statements or side effects:** Use a **switch statement**.
+  - Syntax: `switch (value) { case pattern: statements; }`
+  - Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required).
+
+## Core Pattern Implementations
+
+Implement patterns using the following syntax and rules:
+
+- **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables.
+- **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must _not_ define overlapping variables.
+- **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression.
+- **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring.
+- **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type.
+- **Null-assert (`!`):** `pattern!`. Throws if the value is null.
+- **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable.
+- **Wildcard (`_`):** Matches any value and discards it.
+- **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used.
+- **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys.
+- **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name.
+- **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name.
+
+## Workflows
+
+### Task Progress: Implementing Pattern Matching
+
+Copy this checklist to track progress when implementing complex pattern matching logic:
+
+- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum).
+- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects).
+- [ ] Define the required patterns (Object, Map, List, Record).
+- [ ] Extract required data using Variable patterns (`var x`, `:var y`).
+- [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns.
+- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
+- [ ] Run exhaustiveness validator.
+
+### Feedback Loop: Exhaustiveness Checking
+
+When switching over `sealed` classes or enums, you must ensure all subtypes are handled.
+
+1. **Run validator:** Execute `dart analyze`.
+2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors.
+3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable.
+
+## Examples
+
+### JSON Validation and Destructuring
+
+Use Map and List patterns to validate structure and extract data in a single step.
+
+**Input:**
+
+```dart
+var data = {
+  'user': ['Lily', 13],
+};
+```
+
+**Implementation:**
+
+```dart
+if (data case {'user': [String name, int age]}) {
+  print('User $name is $age years old.');
+} else {
+  print('Invalid JSON structure.');
+}
+```
+
+### Algebraic Data Types (Sealed Classes)
+
+Use Object patterns with switch expressions to handle family types exhaustively.
+
+**Implementation:**
+
+```dart
+sealed class Shape {}
+
+class Square implements Shape {
+  final double length;
+  Square(this.length);
+}
+
+class Circle implements Shape {
+  final double radius;
+  Circle(this.radius);
+}
+
+// Switch expression guarantees exhaustiveness due to `sealed` modifier.
+double calculateArea(Shape shape) => switch (shape) {
+  Square(length: var l) => l * l,
+  Circle(:var radius)   => math.pi * radius * radius,
+};
+```
+
+### Variable Swapping and Destructuring
+
+Use variable assignment patterns to swap values or extract record fields without temporary variables.
+
+**Implementation:**
+
+```dart
+var (a, b) = ('left', 'right');
+(b, a) = (a, b); // Swap values
+
+// Destructuring a function return
+var (name, age) = getUserInfo();
+```
+
+### Guard Clauses and Logical-or
+
+Use `when` to evaluate arbitrary conditions after a pattern matches.
+
+**Implementation:**
+
+```dart
+switch (shape) {
+  case Square(size: var s) || Circle(size: var s) when s > 0:
+    print('Valid symmetric shape with size $s');
+  case Square() || Circle():
+    print('Invalid or empty shape');
+  default:
+    print('Unknown shape');
+}
+```
+
+## Flutter Ultra Integration
+
+Validate pattern matching usage with analysis:
+
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Check for exhaustiveness and type errors
+- `mcp__plugin_flutter_flutter-ultra-build__fix` — Apply automated pattern matching migrations
+
+---
+
+> **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.