@bdayadev/flutter-ultra-mcp 1.12.0 → 1.13.0

package/skills/setup-localization/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: setup-localization
 description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.
+  last_modified: Tue, 21 Apr 2026 21:27:35 GMT
 ---
 
 # Internationalizing Flutter Applications
@@ -15,46 +16,67 @@ description: Add `flutter_localizations` and `intl` dependencies, enable "genera
 
 ## Core Concepts
 
-Flutter handles i18n/l10n via `flutter_localizations` and `intl`. Uses App Resource Bundle (`.arb`) files compiled into a generated `AppLocalizations` class for type-safe access.
+Flutter handles internationalization (i18n) and localization (l10n) via the `flutter_localizations` and `intl` packages. The standard approach uses App Resource Bundle (`.arb`) files to define localized strings, which are then compiled into a generated `AppLocalizations` class for type-safe access within the widget tree.
 
 ## Setup Workflow
 
-- [ ] 1. Add dependencies to `pubspec.yaml`.
-- [ ] 2. Enable the `generate` flag.
-- [ ] 3. Create the `l10n.yaml` configuration file.
-- [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
+Copy and track this checklist when initializing internationalization in a Flutter project:
+
+- [ ] **Task Progress**
+  - [ ] 1. Add dependencies to `pubspec.yaml`.
+  - [ ] 2. Enable the `generate` flag.
+  - [ ] 3. Create the `l10n.yaml` configuration file.
+  - [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
 
 ### 1. Add Dependencies
 
+Add the required localization packages to the project. Execute the following commands in the terminal:
+
 ```bash
 flutter pub add flutter_localizations --sdk=flutter
 flutter pub add intl:any
 ```
 
+Verify your `pubspec.yaml` includes the following under `dependencies`:
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  intl: any
+```
+
 ### 2. Enable Code Generation
 
+Open `pubspec.yaml` and enable the `generate` flag within the `flutter` section to automate localization tasks:
+
 ```yaml
-# pubspec.yaml
 flutter:
   generate: true
 ```
 
 ### 3. Create Configuration File
 
+Create a new file named `l10n.yaml` in the root directory of the Flutter project. Define the input directory, template file, and output file:
+
 ```yaml
-# l10n.yaml
 arb-dir: lib/l10n
 template-arb-file: app_en.arb
 output-localization-file: app_localizations.dart
 synthetic-package: true
 ```
 
-### 4. Configure App Entry Point
+### 4. Configure the App Entry Point
+
+Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`.
 
 ```dart
 import 'package:flutter_localizations/flutter_localizations.dart';
-import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Adjust path if synthetic-package is false
 
+// ... inside build method
 return MaterialApp(
   localizationsDelegates: const [
     AppLocalizations.delegate,
@@ -62,16 +84,22 @@ return MaterialApp(
     GlobalWidgetsLocalizations.delegate,
     GlobalCupertinoLocalizations.delegate,
   ],
-  supportedLocales: const [Locale('en'), Locale('es')],
+  supportedLocales: const [
+    Locale('en'), // English
+    Locale('es'), // Spanish
+  ],
   home: const MyHomePage(),
 );
 ```
 
 ## Implementation Workflow
 
+Follow this workflow when adding or modifying localized content.
+
 ### 1. Define ARB Files
 
-**Template (`lib/l10n/app_en.arb`):**
+- **If creating NEW content:** Add the base string to the template file (`lib/l10n/app_en.arb`). Include a description for context.
+- **If EDITING existing content:** Locate the key in all supported `.arb` files and update the values.
 
 ```json
 {
@@ -82,59 +110,98 @@ return MaterialApp(
 }
 ```
 
-**Other locales (`lib/l10n/app_es.arb`):**
+Create corresponding files for other locales (e.g., `app_es.arb`):
 
 ```json
 {
-  "helloWorld": "!Hola Mundo!"
+  "helloWorld": "¡Hola Mundo!"
 }
 ```
 
 ### 2. Generate Localization Classes
 
+Run the following command to trigger code generation:
+
 ```bash
 flutter pub get
 ```
 
+_Feedback Loop:_ Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run `flutter pub get`.
+
 ### 3. Consume Localized Strings
 
+Access the localized strings in your widget tree using `AppLocalizations.of(context)`. Ensure the widget calling this is a descendant of `MaterialApp`.
+
 ```dart
 Text(AppLocalizations.of(context)!.helloWorld)
 ```
 
 ## Advanced Formatting
 
+Use placeholders for dynamic data, plurals, and conditional selects.
+
 ### Placeholders
 
+Define parameters within curly braces and specify their type in the metadata object.
+
 ```json
 "hello": "Hello {userName}",
 "@hello": {
+  "description": "A message with a single parameter",
   "placeholders": {
-    "userName": { "type": "String", "example": "Bob" }
+    "userName": {
+      "type": "String",
+      "example": "Bob"
+    }
   }
 }
 ```
 
 ### Plurals
 
+Use the `plural` syntax to handle quantity-based string variations. The `other` case is mandatory.
+
 ```json
 "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
 "@nWombats": {
-  "placeholders": { "count": { "type": "num", "format": "compact" } }
+  "description": "A plural message",
+  "placeholders": {
+    "count": {
+      "type": "num",
+      "format": "compact"
+    }
+  }
 }
 ```
 
 ### Selects
 
+Use the `select` syntax for conditional strings, such as gendered text.
+
 ```json
 "pronoun": "{gender, select, male{he} female{she} other{they}}",
 "@pronoun": {
-  "placeholders": { "gender": { "type": "String" } }
+  "description": "A gendered message",
+  "placeholders": {
+    "gender": {
+      "type": "String"
+    }
+  }
 }
 ```
 
 ## Examples
 
+### Complete `l10n.yaml`
+
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: true
+use-escaping: true
+```
+
 ### Complete Widget Implementation
 
 ```dart
@@ -154,10 +221,13 @@ class GreetingWidget extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final l10n = AppLocalizations.of(context)!;
-    return Column(children: [
-      Text(l10n.hello(userName)),
-      Text(l10n.nWombats(notificationCount)),
-    ]);
+
+    return Column(
+      children: [
+        Text(l10n.hello(userName)),
+        Text(l10n.nWombats(notificationCount)),
+      ],
+    );
   }
 }
 ```

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

@@ -1,6 +1,7 @@
 ---
 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
@@ -15,56 +16,82 @@ description: Use the `http` package to execute GET, POST, PUT, or DELETE request
 
 ## Configuration & Permissions
 
-1. Add the `http` package: `flutter pub add http`
-2. Import: `import 'package:http/http.dart' as http;`
-3. **Android**: Add `<uses-permission android:name="android.permission.INTERNET" />` to `AndroidManifest.xml`.
-4. **macOS**: Add `com.apple.security.network.client` = `true` to both entitlements files.
+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
 
-- **URIs:** Always use `Uri.parse('your_url')`.
-- **Headers:** Inject via the `headers` parameter map.
-- **Payloads:** For POST/PUT, encode body with `jsonEncode()`.
-- **Status Validation:** Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success.
-- **Error Handling:** Throw explicit exceptions on non-success codes. Never return `null`.
-- **Deserialization:** `jsonDecode(response.body)` then map to model's `fromJson`.
+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
 
-For large payloads (>16ms parse time), use `compute()` from `package:flutter/foundation.dart` to parse in a background isolate. The parsing function must be top-level or static.
+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 strongly typed Dart model with `fromJson`.
-- [ ] 2. Implement network request method returning `Future<Model>`.
-- [ ] 3. Apply conditional logic:
-  - **GET**: Append query parameters to URI.
-  - **POST/PUT**: Set `Content-Type: application/json; charset=UTF-8`, attach `jsonEncode` body.
-  - **DELETE**: Return empty model instance on success.
-- [ ] 4. Validate `statusCode` and throw `Exception` on failure.
-- [ ] 5. Integrate into UI using `FutureBuilder`.
-- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, default to `CircularProgressIndicator`.
-- [ ] 7. Run app -> trigger request -> review console for exceptions -> fix.
+- [ ] 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
 
-### Fetching and Parsing in the Background
+### 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'),
@@ -75,18 +102,24 @@ Future<List<Photo>> fetchPhotos() async {
   );
 
   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});
+  const Photo({
+    required this.id,
+    required this.title,
+    required this.thumbnailUrl,
+  });
 
   factory Photo.fromJson(Map<String, dynamic> json) {
     return Photo(
@@ -97,8 +130,10 @@ class Photo {
   }
 }
 
+// 4. UI Integration
 class PhotoGallery extends StatefulWidget {
   const PhotoGallery({super.key});
+
   @override
   State<PhotoGallery> createState() => _PhotoGalleryState();
 }
@@ -109,6 +144,7 @@ class _PhotoGalleryState extends State<PhotoGallery> {
   @override
   void initState() {
     super.initState();
+    // Initialize Future once to prevent re-fetching on rebuilds
     _futurePhotos = fetchPhotos();
   }
 
@@ -129,6 +165,8 @@ class _PhotoGalleryState extends State<PhotoGallery> {
         } else if (snapshot.hasError) {
           return Center(child: Text('Error: ${snapshot.error}'));
         }
+
+        // Default loading state
         return const Center(child: CircularProgressIndicator());
       },
     );

package/skills/use-pattern-matching/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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
@@ -15,60 +16,82 @@ description: Use switch expressions and pattern matching where appropriate
 
 ## Pattern Selection Strategy
 
-- **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns.
-- **If handling multiple return values:** Use Record patterns.
-- **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns with `sealed` classes.
-- **If matching numeric ranges or conditions:** Use Relational and Logical-and patterns.
-- **If multiple cases share logic:** Use Logical-or (`||`) patterns.
-- **If ignoring specific values:** Use the Wildcard pattern (`_`).
+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
 
-- **If producing a value:** Use a **switch expression**. Syntax: `switch (value) { pattern => expression, }`. Must be exhaustive.
-- **If executing statements or side effects:** Use a **switch statement**. Empty cases fall through. Non-empty cases implicitly break.
+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
 
-- **Logical-or (`||`):** Both branches must define the exact same set of variables.
-- **Logical-and (`&&`):** Branches must _not_ define overlapping variables.
+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`):** Throws if the value does not match the type.
-- **Null-check (`?`):** Fails the match if the value is null.
-- **Null-assert (`!`):** Throws if the value is null.
-- **Variable:** `var name` or `Type name`. Binds the matched value.
+- **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 (`...`) is used.
-- **Map:** `{"key": pattern}`. Matches maps containing the specified keys.
-- **Record:** `(pattern1, named: pattern2)`. Use `:var name` to infer the getter name.
-- **Object:** `ClassName(field: pattern)`. Use `:var field` to infer the getter name.
+- **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
 
-- [ ] Identify the data structure being evaluated.
-- [ ] Select the appropriate switch construct.
-- [ ] Define the required patterns.
-- [ ] Extract required data using Variable patterns.
+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`.
+- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
 - [ ] Run exhaustiveness validator.
 
 ### Feedback Loop: Exhaustiveness Checking
 
-1. Execute `dart analyze`.
-2. Look for "The type 'X' is not exhaustively matched" errors.
-3. Add the missing Object patterns for unhandled subtypes, or add a Wildcard case.
+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 {
@@ -78,6 +101,10 @@ if (data case {'user': [String name, int age]}) {
 
 ### Algebraic Data Types (Sealed Classes)
 
+Use Object patterns with switch expressions to handle family types exhaustively.
+
+**Implementation:**
+
 ```dart
 sealed class Shape {}
 
@@ -91,6 +118,7 @@ class Circle implements Shape {
   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,
@@ -99,15 +127,24 @@ double calculateArea(Shape shape) => switch (shape) {
 
 ### 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: