@bdayadev/flutter-ultra-mcp 1.11.7 → 1.13.0

package/skills/run-static-analysis/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: run-static-analysis
+description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
+  last_modified: Fri, 24 Apr 2026 15:09:34 GMT
+---
+
+# Analyzing and Fixing Dart Code
+
+## Contents
+
+- [Analysis Configuration](#analysis-configuration)
+- [Diagnostic Suppression](#diagnostic-suppression)
+- [Workflow: Executing Static Analysis](#workflow-executing-static-analysis)
+- [Workflow: Applying Automated Fixes](#workflow-applying-automated-fixes)
+- [Examples](#examples)
+
+## Analysis Configuration
+
+Configure the Dart analyzer using the `analysis_options.yaml` file located at the package root.
+
+- **Base Configuration:** Always include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`) using the `include:` directive.
+- **Strict Type Checks:** Enable strict type checks under the `analyzer: language:` node to prevent implicit downcasts and dynamic inferences. Set `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true`.
+- **Linter Rules:** Explicitly enable or disable specific rules under the `linter: rules:` node. Use a key-value map (`rule_name: true/false`) when overriding included rules, or a list (`- rule_name`) when defining a fresh set. Do not mix list and map syntax in the same `rules` block.
+- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` (default 80) and `trailing_commas` (`automate` or `preserve`).
+- **Analyzer Plugins:** Enable custom diagnostics by adding plugins under the `analyzer: plugins:` node. Ensure the plugin package is added as a `dev_dependency` in `pubspec.yaml`.
+
+## Diagnostic Suppression
+
+When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly.
+
+- **File-level Exclusion:** Use the `analyzer: exclude:` node in `analysis_options.yaml` to exclude entire files or directories (e.g., `**/*.g.dart`) using glob patterns.
+- **File-level Suppression:** Add `// ignore_for_file: <diagnostic_code>` at the top of a Dart file to suppress specific diagnostics for the entire file. Use `// ignore_for_file: type=lint` to suppress all linter rules.
+- **Line-level Suppression:** Add `// ignore: <diagnostic_code>` on the line directly above the offending code, or appended to the end of the offending line.
+- **Pubspec Suppression:** Add `# ignore: <diagnostic_code>` above the offending line in `pubspec.yaml` files (e.g., `# ignore: sort_pub_dependencies`).
+- **Plugin Diagnostics:** Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g., `// ignore: some_plugin/some_code`).
+
+## Workflow: Executing Static Analysis
+
+Use this workflow to identify type-related bugs, style violations, and potential runtime errors.
+
+**Task Progress:**
+
+- [ ] 1. Verify `analysis_options.yaml` exists at the project root.
+- [ ] 2. Run the analyzer using the `analyze_files` MCP tool (if available) or the CLI command `dart analyze <target_directory>`.
+- [ ] 3. Review the diagnostic output.
+- [ ] 4. If info-level issues must be treated as failures, append the `--fatal-infos` flag.
+- [ ] 5. Resolve reported errors manually or proceed to the Automated Fixes workflow.
+
+## Workflow: Applying Automated Fixes
+
+Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations).
+
+**Task Progress:**
+
+- [ ] 1. Execute a dry run to preview proposed changes using the `dart_fix` MCP tool or CLI command `dart fix --dry-run`.
+- [ ] 2. Review the proposed fixes to ensure they align with the intended architecture.
+- [ ] 3. If additional fixes are required, verify that the corresponding linter rules are enabled in `analysis_options.yaml`.
+- [ ] 4. Apply the fixes using the `dart_fix` MCP tool or CLI command `dart fix --apply`.
+- [ ] 5. Format the modified code using the `dart_format` MCP tool or CLI command `dart format .`.
+- [ ] 6. Run the static analysis workflow to verify all diagnostics are resolved.
+
+## Examples
+
+### Comprehensive `analysis_options.yaml`
+
+```yaml
+include: package:flutter_lints/recommended.yaml
+
+analyzer:
+  exclude:
+    - '**/*.g.dart'
+    - 'lib/generated/**'
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  errors:
+    todo: ignore
+    invalid_assignment: warning
+    missing_return: error
+
+linter:
+  rules:
+    avoid_shadowing_type_parameters: false
+    await_only_futures: true
+    use_super_parameters: true
+
+formatter:
+  page_width: 100
+  trailing_commas: preserve
+```
+
+### Inline Diagnostic Suppression
+
+```dart
+// Suppress for the entire file
+// ignore_for_file: unused_local_variable, dead_code
+
+void processData() {
+  // Suppress for a specific line
+  // ignore: invalid_assignment
+  int x = '';
+
+  const y = 10; // ignore: constant_identifier_names
+}
+```
+
+## Flutter Ultra Integration
+
+Run analysis and auto-fix via flutter-ultra tools:
+
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Run dart analyze with full diagnostics
+- `mcp__plugin_flutter_flutter-ultra-build__fix` — Apply dart fix --apply for automated lint fixes
+- `mcp__plugin_flutter_flutter-ultra-build__fix_preview` — Preview fixes before applying
+- `mcp__plugin_flutter_flutter-ultra-build__format` — Format code after fixes
+
+---
+
+> **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/setup-declarative-routing/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: setup-declarative-routing
+description: Configure `MaterialApp.router` using a package like `go_router` for advanced URL-based navigation. Use when developing web applications or mobile apps that require specific deep linking and browser history support.
+  last_modified: Tue, 21 Apr 2026 21:08:03 GMT
+---
+
+# Implementing Routing and Deep Linking
+
+## Contents
+
+- [Core Concepts](#core-concepts)
+- [Workflow: Initializing the Application and Router](#workflow-initializing-the-application-and-router)
+- [Workflow: Configuring Platform Deep Linking](#workflow-configuring-platform-deep-linking)
+- [Workflow: Implementing Nested Navigation](#workflow-implementing-nested-navigation)
+- [Examples](#examples)
+
+## Core Concepts
+
+Use the `go_router` package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation.
+
+- **GoRouter**: The central configuration object defining the application's route tree.
+- **GoRoute**: A standard route mapping a URL path to a Flutter screen.
+- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., a `BottomNavigationBar`). `StatefulShellRoute` maintains the state of parallel navigation branches.
+- **Path URL Strategy**: Removes the default `#` fragment from web URLs, essential for clean deep linking across platforms.
+
+## Workflow: Initializing the Application and Router
+
+Follow this workflow to bootstrap a new Flutter application with `go_router` and configure the root routing mechanism.
+
+### Task Progress
+
+- [ ] Create the Flutter application.
+- [ ] Add the `go_router` dependency.
+- [ ] Configure the URL strategy for web/deep linking.
+- [ ] Implement the `GoRouter` configuration.
+- [ ] Bind the router to `MaterialApp.router`.
+
+### 1. Scaffold the Application
+
+Run the following commands to create the app and add the required routing package:
+
+```bash
+flutter create <app-name>
+cd <app-name>
+flutter pub add go_router
+```
+
+### 2. Configure the Router
+
+Define a top-level `GoRouter` instance. Handle authentication or state-based routing using the `redirect` parameter.
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:flutter_web_plugins/url_strategy.dart';
+
+void main() {
+  // Use path URL strategy to remove the '#' from web URLs
+  usePathUrlStrategy();
+  runApp(const MyApp());
+}
+
+final GoRouter _router = GoRouter(
+  initialLocation: '/',
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => const HomeScreen(),
+      routes: [
+        GoRoute(
+          path: 'details/:id',
+          builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
+        ),
+      ],
+    ),
+  ],
+  errorBuilder: (context, state) => ErrorScreen(error: state.error),
+);
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      routerConfig: _router,
+      title: 'Routing App',
+    );
+  }
+}
+```
+
+## Workflow: Configuring Platform Deep Linking
+
+Configure the native platforms to intercept specific URLs and route them into the Flutter application.
+
+### Task Progress
+
+- [ ] Determine target platforms (iOS, Android, or both).
+- [ ] Apply conditional configuration for Android (Manifest + Asset Links).
+- [ ] Apply conditional configuration for iOS (Plist + Entitlements + AASA).
+- [ ] Run validator -> review errors -> fix.
+
+### If configuring for Android:
+
+1. **Modify `AndroidManifest.xml`**: Add the intent filter inside the `<activity>` tag for `.MainActivity`.
+
+```xml
+<intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="http" android:host="yourdomain.com" />
+    <data android:scheme="https" />
+</intent-filter>
+```
+
+2. **Host `assetlinks.json`**: Serve the following JSON at `https://yourdomain.com/.well-known/assetlinks.json`.
+
+```json
+[
+  {
+    "relation": ["delegate_permission/common.handle_all_urls"],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "com.yourcompany.yourapp",
+      "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
+    }
+  }
+]
+```
+
+### If configuring for iOS:
+
+1. **Modify `Info.plist`**: Opt-in to Flutter's default deep link handler.
+   _Note: If using a third-party deep linking plugin (e.g., `app_links`), set this to `NO` to prevent conflicts._
+
+```xml
+<key>FlutterDeepLinkingEnabled</key>
+<true/>
+```
+
+2. **Modify `Runner.entitlements`**: Add the associated domain.
+
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+  <string>applinks:yourdomain.com</string>
+</array>
+```
+
+3. **Host `apple-app-site-association`**: Serve the following JSON (without a `.json` extension) at `https://yourdomain.com/.well-known/apple-app-site-association`.
+
+```json
+{
+  "applinks": {
+    "apps": [],
+    "details": [
+      {
+        "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
+        "paths": ["*"],
+        "components": [{ "/": "/*" }]
+      }
+    ]
+  }
+}
+```
+
+### Validation Loop
+
+Run validator -> review errors -> fix.
+
+- **Android**: Test using ADB.
+  ```bash
+  adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp
+  ```
+- **iOS**: Test using `xcrun` on a booted simulator.
+  ```bash
+  xcrun simctl openurl booted https://yourdomain.com/details/123
+  ```
+
+## Workflow: Implementing Nested Navigation
+
+Use `StatefulShellRoute` to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes.
+
+### Task Progress
+
+- [ ] Define `StatefulShellRoute.indexedStack` in the `GoRouter` configuration.
+- [ ] Create `StatefulShellBranch` instances for each navigation tab.
+- [ ] Implement the shell widget using `StatefulNavigationShell`.
+
+```dart
+final GoRouter _router = GoRouter(
+  initialLocation: '/home',
+  routes: [
+    StatefulShellRoute.indexedStack(
+      builder: (context, state, navigationShell) {
+        return ScaffoldWithNavBar(navigationShell: navigationShell);
+      },
+      branches: [
+        StatefulShellBranch(
+          routes: [
+            GoRoute(
+              path: '/home',
+              builder: (context, state) => const HomeScreen(),
+            ),
+          ],
+        ),
+        StatefulShellBranch(
+          routes: [
+            GoRoute(
+              path: '/settings',
+              builder: (context, state) => const SettingsScreen(),
+            ),
+          ],
+        ),
+      ],
+    ),
+  ],
+);
+```
+
+## Examples
+
+### High-Fidelity Shell Widget Implementation
+
+Implement the UI shell that consumes the `StatefulNavigationShell` to handle branch switching.
+
+```dart
+class ScaffoldWithNavBar extends StatelessWidget {
+  const ScaffoldWithNavBar({
+    required this.navigationShell,
+    super.key,
+  });
+
+  final StatefulNavigationShell navigationShell;
+
+  void _goBranch(int index) {
+    navigationShell.goBranch(
+      index,
+      // Support navigating to the initial location when tapping the active tab.
+      initialLocation: index == navigationShell.currentIndex,
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: navigationShell,
+      bottomNavigationBar: NavigationBar(
+        selectedIndex: navigationShell.currentIndex,
+        onDestinationSelected: _goBranch,
+        destinations: const [
+          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
+          NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
+        ],
+      ),
+    );
+  }
+}
+```
+
+### Programmatic Navigation
+
+Use the `context.go()` and `context.push()` extension methods provided by `go_router`.
+
+```dart
+// Replaces the current route stack with the target route (Declarative)
+context.go('/details/123');
+
+// Pushes the target route onto the existing stack (Imperative)
+context.push('/details/123');
+
+// Navigates using a named route and path parameters
+context.goNamed('details', pathParameters: {'id': '123'});
+
+// Pops the current route
+context.pop();
+```
+
+## Flutter Ultra Integration
+
+After configuring routes, test navigation in the running app:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` — Launch the app to test routing
+- `mcp__plugin_flutter_flutter-ultra-browser__navigate` — Navigate to specific routes in the browser (web targets)
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — Capture each route for visual verification
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — Check for routing errors (missing routes, redirect loops)
+
+---
+
+> **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/setup-localization/SKILL.md

@@ -0,0 +1,247 @@
+---
+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
+
+## Contents
+
+- [Core Concepts](#core-concepts)
+- [Setup Workflow](#setup-workflow)
+- [Implementation Workflow](#implementation-workflow)
+- [Advanced Formatting](#advanced-formatting)
+- [Examples](#examples)
+
+## Core Concepts
+
+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
+
+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
+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
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: true
+```
+
+### 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'; // Adjust path if synthetic-package is false
+
+// ... inside build method
+return MaterialApp(
+  localizationsDelegates: const [
+    AppLocalizations.delegate,
+    GlobalMaterialLocalizations.delegate,
+    GlobalWidgetsLocalizations.delegate,
+    GlobalCupertinoLocalizations.delegate,
+  ],
+  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
+
+- **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
+{
+  "helloWorld": "Hello World!",
+  "@helloWorld": {
+    "description": "The conventional newborn programmer greeting"
+  }
+}
+```
+
+Create corresponding files for other locales (e.g., `app_es.arb`):
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
+### 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": {
+  "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": {
+  "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
+import 'package:flutter/material.dart';
+import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+
+class GreetingWidget extends StatelessWidget {
+  final String userName;
+  final int notificationCount;
+
+  const GreetingWidget({
+    super.key,
+    required this.userName,
+    required this.notificationCount,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final l10n = AppLocalizations.of(context)!;
+
+    return Column(
+      children: [
+        Text(l10n.hello(userName)),
+        Text(l10n.nWombats(notificationCount)),
+      ],
+    );
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+Generate and validate localization files with these tools:
+
+- `mcp__plugin_flutter_flutter-ultra-build__flutter_gen_l10n` — Generate localization Dart code from ARB files
+- `mcp__plugin_flutter_flutter-ultra-build__list_missing_translations` — Find missing translation keys across locales
+- `mcp__plugin_flutter_flutter-ultra-build__arb_add_key` — Add a new translation key to all ARB files
+- `mcp__plugin_flutter_flutter-ultra-build__arb_diff` — Compare ARB files to find drift between locales
+
+---
+
+> **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.