@bdayadev/flutter-ultra-mcp 1.11.7 → 1.12.0

package/skills/apply-architecture-best-practices/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: apply-architecture-best-practices
+description: Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability.
+---
+
+# Architecting Flutter Applications
+
+## Contents
+
+- [Architectural Layers](#architectural-layers)
+- [Project Structure](#project-structure)
+- [Workflow: Implementing a New Feature](#workflow-implementing-a-new-feature)
+- [Examples](#examples)
+
+## Architectural Layers
+
+Enforce strict Separation of Concerns by dividing the application into distinct layers.
+
+### UI Layer (Presentation)
+
+Implement the MVVM (Model-View-ViewModel) pattern.
+
+- **Views:** Reusable, lean widgets. Restrict logic to UI-specific operations.
+- **ViewModels:** Manage UI state. Extend `ChangeNotifier`. Expose immutable state snapshots. Inject Repositories via constructor.
+
+### Data Layer
+
+Implement the Repository pattern for a single source of truth.
+
+- **Services:** Stateless classes wrapping external APIs. Return raw API models or `Result` wrappers.
+- **Repositories:** Consume Services. Transform raw models into Domain Models. Handle caching and retry logic.
+
+### Logic Layer (Domain - Optional)
+
+- **Use Cases:** Only if complex business logic clutters the ViewModel, or logic must be reused across ViewModels.
+
+## Project Structure
+
+```text
+lib/
+├── data/
+│   ├── models/         # API models
+│   ├── repositories/   # Repository implementations
+│   └── services/       # API clients, local storage wrappers
+├── domain/
+│   ├── models/         # Clean domain models
+│   └── use_cases/      # Optional business logic classes
+└── ui/
+    ├── core/           # Shared widgets, themes, typography
+    └── features/
+        └── [feature_name]/
+            ├── view_models/
+            └── views/
+```
+
+## Workflow: Implementing a New Feature
+
+### Task Progress
+
+- [ ] **Step 1:** Define Domain Models (immutable data classes).
+- [ ] **Step 2:** Implement Services (external API communication).
+- [ ] **Step 3:** Implement Repositories (consume Services, return Domain Models).
+- [ ] **Step 4:** Apply Conditional Logic:
+  - Complex data transformation or cross-repository logic: Create a Use Case.
+  - Simple CRUD: Skip to Step 5.
+- [ ] **Step 5:** Implement the ViewModel (extend `ChangeNotifier`, inject Repositories).
+- [ ] **Step 6:** Implement the View (use `ListenableBuilder` to listen to ViewModel).
+- [ ] **Step 7:** Inject Dependencies (register in DI container).
+- [ ] **Step 8:** Run tests. Feedback Loop: Run -> Review -> Fix -> Re-run.
+
+## Examples
+
+### Data Layer: Service and Repository
+
+```dart
+class ApiClient {
+  Future<UserApiModel> fetchUser(String id) async { /* ... */ }
+}
+
+class UserRepository {
+  UserRepository({required ApiClient apiClient}) : _apiClient = apiClient;
+  final ApiClient _apiClient;
+  User? _cachedUser;
+
+  Future<User> getUser(String id) async {
+    if (_cachedUser != null) return _cachedUser!;
+    final apiModel = await _apiClient.fetchUser(id);
+    _cachedUser = User(id: apiModel.id, name: apiModel.fullName);
+    return _cachedUser!;
+  }
+}
+```
+
+### UI Layer: ViewModel and View
+
+```dart
+class ProfileViewModel extends ChangeNotifier {
+  ProfileViewModel({required UserRepository userRepository})
+      : _userRepository = userRepository;
+  final UserRepository _userRepository;
+
+  User? _user;
+  User? get user => _user;
+  bool _isLoading = false;
+  bool get isLoading => _isLoading;
+
+  Future<void> loadProfile(String id) async {
+    _isLoading = true;
+    notifyListeners();
+    try {
+      _user = await _userRepository.getUser(id);
+    } finally {
+      _isLoading = false;
+      notifyListeners();
+    }
+  }
+}
+
+class ProfileView extends StatelessWidget {
+  const ProfileView({super.key, required this.viewModel});
+  final ProfileViewModel viewModel;
+
+  @override
+  Widget build(BuildContext context) {
+    return ListenableBuilder(
+      listenable: viewModel,
+      builder: (context, _) {
+        if (viewModel.isLoading) return const Center(child: CircularProgressIndicator());
+        final user = viewModel.user;
+        if (user == null) return const Center(child: Text('User not found'));
+        return Column(children: [
+          Text(user.name),
+          ElevatedButton(
+            onPressed: () => viewModel.loadProfile(user.id),
+            child: const Text('Refresh'),
+          ),
+        ]);
+      },
+    );
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+Use these tools to audit and validate architectural decisions:
+
+- `mcp__plugin_flutter_flutter-ultra-build__list_projects` — Discover all projects in the workspace
+- `mcp__plugin_flutter_flutter-ultra-build__project_info` — Get project structure, dependencies, and entry points
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Run static analysis to catch architectural violations
+- `mcp__plugin_flutter_flutter-ultra-build__pub_deps` — Review dependency graph for layering issues
+
+---
+
+> **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/build-cli-app/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: build-cli-app
+description: Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications.
+---
+
+# Building Dart CLI Applications
+
+## Contents
+
+- [Project Setup & Architecture](#project-setup--architecture)
+- [Argument Parsing & Command Routing](#argument-parsing--command-routing)
+- [Execution & Error Handling](#execution--error-handling)
+- [Testing CLI Applications](#testing-cli-applications)
+- [Compilation & Distribution](#compilation--distribution)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Project Setup & Architecture
+
+Initialize new CLI projects using the official Dart template to ensure standard directory structures.
+
+- Run `dart create -t cli <project_name>` to scaffold a console application with basic argument parsing.
+- Place executable entry points (files containing `main()`) exclusively in the `bin/` directory.
+- Place internal implementation logic in `lib/src/` and expose public APIs via `lib/<project_name>.dart`.
+- Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist.
+
+## Argument Parsing & Command Routing
+
+Import the `args` package to manage command-line arguments, flags, and subcommands.
+
+- If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`).
+- If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand.
+- Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`.
+- Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text.
+- **Validate Help Text Accuracy**: Ensure the help text provides all necessary information to run the tool.
+
+## Execution & Error Handling
+
+Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools.
+
+- Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`).
+- Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input.
+- Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains.
+- Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user.
+- **Do not swallow exceptions** in lower-level logic unless recovery is possible. Let them bubble up.
+- **Fail fast and with non-zero exit codes**: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes.
+
+## Testing CLI Applications
+
+Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI.
+
+- Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`).
+- Create the mock filesystem before execution using `await d.Descriptor.create()`.
+- Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`.
+- Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`).
+- Assert the final exit code using `await process.shouldExit(0)`.
+- Validate resulting filesystem mutations using `await d.Descriptor.validate()`.
+
+## Compilation & Distribution
+
+Select the appropriate compilation target based on your distribution requirements.
+
+- **If testing locally during development:** Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration.
+- **If bundling code assets and dynamic libraries:** Use `dart build cli`.
+- **If distributing a standalone native executable:** Use `dart compile exe bin/cli.dart -o <output_path>`.
+- **If distributing multiple apps with strict disk space limits:** Use `dart compile aot-snapshot bin/cli.dart`.
+
+## Workflows
+
+### Task Progress: Implement a New CLI Command
+
+- [ ] Create a new class extending `Command` in `lib/src/commands/`.
+- [ ] Define the `name` and `description` properties.
+- [ ] Register command-specific flags in the constructor using `argParser.addFlag()` or `argParser.addOption()`.
+- [ ] Implement the `run()` method with the core logic.
+- [ ] Register the new command in the `CommandRunner` instance in `bin/cli.dart` using `addCommand()`.
+- [ ] Create tests for the new command in the `test/` directory.
+- [ ] Run validator -> Execute `dart run bin/cli.dart help <command_name>` to verify help text generation.
+- [ ] Verify final UX: Compile the application using `dart compile exe` and run the resulting executable.
+
+### Task Progress: Compile and Release Native Executable
+
+- [ ] Run validator -> Execute `dart format . --set-exit-if-changed` to ensure code formatting.
+- [ ] Run validator -> Execute `dart analyze` to ensure no static analysis errors.
+- [ ] Run validator -> Execute `dart test` to pass all integration tests.
+- [ ] Compile for host OS: `dart compile exe bin/cli.dart -o build/cli-host`
+
+## Examples
+
+### Example: CommandRunner Implementation
+
+```dart
+import 'dart:io';
+import 'package:args/command_runner.dart';
+import 'package:stack_trace/stack_trace.dart';
+
+class CommitCommand extends Command {
+  @override
+  final String name = 'commit';
+  @override
+  final String description = 'Record changes to the repository.';
+
+  CommitCommand() {
+    argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files.');
+  }
+
+  @override
+  Future<void> run() async {
+    final commitAll = argResults?['all'] as bool? ?? false;
+    print('Committing... (All: $commitAll)');
+  }
+}
+
+void main(List<String> args) {
+  Chain.capture(() async {
+    final runner = CommandRunner('dgit', 'Distributed version control.')
+      ..addCommand(CommitCommand());
+
+    await runner.run(args);
+  }, onError: (error, chain) {
+    if (error is UsageException) {
+      stderr.writeln(error.message);
+      stderr.writeln(error.usage);
+      exit(64);
+    } else {
+      stderr.writeln('Fatal error: $error');
+      stderr.writeln(chain.terse);
+      exit(1);
+    }
+  });
+}
+```
+
+### Example: Integration Testing with Subprocesses
+
+```dart
+import 'package:test/test.dart';
+import 'package:test_process/test_process.dart';
+import 'package:test_descriptor/test_descriptor.dart' as d;
+
+void main() {
+  test('CLI formats output correctly and modifies filesystem', () async {
+    await d.dir('project', [
+      d.file('config.json', '{"key": "value"}')
+    ]).create();
+
+    final process = await TestProcess.start(
+      'dart',
+      ['run', 'bin/cli.dart', 'process', '--path', '${d.sandbox}/project']
+    );
+
+    await expectLater(process.stdout, emitsThrough('Processing complete.'));
+    await process.shouldExit(0);
+
+    await d.dir('project', [
+      d.file('config.json', '{"key": "value"}'),
+      d.file('output.log', 'Success')
+    ]).validate();
+  });
+}
+```
+
+## Flutter Ultra Integration
+
+Use these tools to validate the CLI app structure:
+
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Static analysis on the CLI project
+- `mcp__plugin_flutter_flutter-ultra-build__pub_deps` — Review dependency tree
+
+---
+
+> **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/build-responsive-layout/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: build-responsive-layout
+description: Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors.
+---
+
+# Implementing Adaptive Layouts
+
+## Contents
+
+- [Space Measurement Guidelines](#space-measurement-guidelines)
+- [Widget Sizing and Constraints](#widget-sizing-and-constraints)
+- [Device and Orientation Behaviors](#device-and-orientation-behaviors)
+- [Workflow: Constructing an Adaptive Layout](#workflow-constructing-an-adaptive-layout)
+- [Workflow: Optimizing for Large Screens](#workflow-optimizing-for-large-screens)
+- [Examples](#examples)
+
+## Space Measurement Guidelines
+
+- **Use `MediaQuery.sizeOf(context)`** to get the size of the entire app window.
+- **Use `LayoutBuilder`** to make layout decisions based on the parent widget's allocated space.
+- **Do not use `MediaQuery.orientationOf` or `OrientationBuilder`** near the top of the widget tree. Device orientation does not accurately reflect available space.
+- **Do not check for hardware types** ("phone" vs. "tablet"). Base all decisions strictly on available window space.
+
+## Widget Sizing and Constraints
+
+- **`Expanded`**: Force a child to fill all remaining available space.
+- **`Flexible`**: Allow a child to size itself up to a limit while expanding/contracting. Use `flex` factor for sibling ratios.
+- **Constrain Width**: Wrap widgets in `ConstrainedBox` with `maxWidth` on large screens.
+- **Lazy Rendering**: Use `ListView.builder` or `GridView.builder` for long/unknown-length lists.
+
+## Device and Orientation Behaviors
+
+- **Do not lock screen orientation.** Causes severe layout issues on foldable devices.
+- **Support Multiple Inputs:** Implement support for mice, trackpads, and keyboard shortcuts.
+
+## Workflow: Constructing an Adaptive Layout
+
+**Task Progress:**
+
+- [ ] Identify the target widget.
+- [ ] Wrap in a `LayoutBuilder`.
+- [ ] Extract `constraints.maxWidth`.
+- [ ] Define breakpoint (e.g., `600`).
+- [ ] If `maxWidth > breakpoint`: Return large-screen layout (e.g., `Row` with sidebar).
+- [ ] If `maxWidth <= breakpoint`: Return small-screen layout.
+- [ ] Resize the app window -> review transitions -> fix overflow errors.
+
+## Workflow: Optimizing for Large Screens
+
+**Task Progress:**
+
+- [ ] Identify full-width components.
+- [ ] **Lists**: Convert `ListView.builder` to `GridView.builder` with `SliverGridDelegateWithMaxCrossAxisExtent`.
+- [ ] **Forms/text**: Wrap in `ConstrainedBox` with `BoxConstraints(maxWidth: ...)`.
+- [ ] Wrap in `Center` to keep constrained content centered.
+- [ ] Test on desktop/tablet -> review horizontal stretching.
+
+## Examples
+
+### Adaptive Layout using LayoutBuilder
+
+```dart
+import 'package:flutter/material.dart';
+
+const double largeScreenMinWidth = 600.0;
+
+class AdaptiveLayout extends StatelessWidget {
+  const AdaptiveLayout({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        if (constraints.maxWidth > largeScreenMinWidth) {
+          return Row(
+            children: [
+              const SizedBox(width: 250, child: Placeholder(color: Colors.blue)),
+              const VerticalDivider(width: 1),
+              Expanded(child: const Placeholder(color: Colors.green)),
+            ],
+          );
+        } else {
+          return const Placeholder(color: Colors.green);
+        }
+      },
+    );
+  }
+}
+```
+
+### Constraining Width on Large Screens
+
+```dart
+class ConstrainedContent extends StatelessWidget {
+  const ConstrainedContent({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: ConstrainedBox(
+          constraints: const BoxConstraints(maxWidth: 800.0),
+          child: ListView.builder(
+            itemCount: 50,
+            itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+After building the layout, verify responsiveness across breakpoints:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__audit_responsive` — Automated responsive audit at multiple viewport sizes
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — Capture screenshots at each breakpoint
+- `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — Inspect render tree for constraint issues
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — Check for overflow errors at different sizes
+
+---
+
+> **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/collect-coverage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: collect-coverage
+description: Collect coverage using the coverage package and create an LCOV report
+---
+
+# Implementing Dart and Flutter Test Coverage
+
+## Contents
+
+- [Testing Fundamentals](#testing-fundamentals)
+- [Coverage Directives](#coverage-directives)
+- [Workflow: Configuring and Generating Coverage Reports](#workflow-configuring-and-generating-coverage-reports)
+- [Workflow: Advanced Manual Coverage Collection](#workflow-advanced-manual-coverage-collection)
+- [Examples](#examples)
+
+## Testing Fundamentals
+
+Structure your test suites using the standard Dart testing paradigms. Use `package:test` for Dart projects and `flutter_test` for Flutter projects.
+
+- **Unit Tests:** Verify individual functions, methods, or classes.
+- **Component/Widget Tests:** Verify component behavior, layout, and interaction using mock objects (`package:mockito`).
+- **Integration Tests:** Verify entire app flows on simulated or real devices.
+
+## Coverage Directives
+
+Exclude specific lines, blocks, or entire files from coverage metrics using inline comments. Pass the `--check-ignore` flag during formatting to enforce these directives.
+
+- Ignore a single line: `// coverage:ignore-line`
+- Ignore a block of code: `// coverage:ignore-start` and `// coverage:ignore-end`
+- Ignore an entire file: `// coverage:ignore-file`
+
+## Workflow: Configuring and Generating Coverage Reports
+
+Follow this sequential workflow to add the coverage package, execute tests, and generate an LCOV report.
+
+**Task Progress Checklist:**
+
+- [ ] 1. Add `coverage` as a `dev_dependency`.
+- [ ] 2. Execute the automated coverage script.
+- [ ] 3. Validate the LCOV output.
+
+### 1. Add Dependencies
+
+Add the `coverage` package as a `dev_dependency` to your project. Do not add it to standard dependencies.
+
+If working in a standard Dart project:
+
+```bash
+dart pub add dev:coverage
+```
+
+If working in a Flutter project:
+
+```bash
+flutter pub add dev:coverage
+```
+
+### 2. Collect Coverage and Generate LCOV
+
+Use the bundled `test_with_coverage` script. This script automatically runs all tests, collects the JSON coverage data from the Dart VM, and formats it into an LCOV report.
+
+```bash
+dart run coverage:test_with_coverage
+```
+
+### 3. Feedback Loop: Validate Output
+
+1. Verify that the `coverage/` directory was created in the project root.
+2. Ensure `coverage/coverage.json` (raw data) and `coverage/lcov.info` (formatted report) exist.
+3. If coverage is missing for specific files, ensure they are imported and executed by your test files, or add `// coverage:ignore-file` if they are intentionally excluded.
+
+## Workflow: Advanced Manual Coverage Collection
+
+If you require granular control over the VM service, isolate pausing, or need branch/function-level coverage, use the manual collection workflow.
+
+**Task Progress Checklist:**
+
+- [ ] 1. Run tests with VM service enabled.
+- [ ] 2. Collect raw JSON coverage.
+- [ ] 3. Format JSON to LCOV.
+
+### 1. Run Tests with VM Service
+
+Execute tests while pausing isolates on exit and exposing the VM service on a specific port (e.g., 8181).
+
+```bash
+dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test &
+```
+
+### 2. Collect Raw Coverage
+
+Extract the coverage data from the running VM service and output it to a JSON file.
+
+```bash
+dart run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates
+```
+
+### 3. Format to LCOV
+
+Convert the raw JSON data into the standard LCOV format.
+
+```bash
+dart run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info --check-ignore
+```
+
+## Examples
+
+### Example: `pubspec.yaml` Configuration
+
+```yaml
+name: my_dart_app
+environment:
+  sdk: ^3.0.0
+
+dependencies:
+  path: ^1.8.0
+
+dev_dependencies:
+  test: ^1.24.0
+  coverage: ^1.15.0
+```
+
+### Example: Applying Ignore Directives
+
+```dart
+// coverage:ignore-file
+import 'package:meta/meta.dart';
+
+class SystemConfig {
+  final String env;
+
+  SystemConfig(this.env);
+
+  // coverage:ignore-start
+  void legacyInit() {
+    print('Deprecated initialization');
+  }
+  // coverage:ignore-end
+
+  bool isProduction() {
+    if (env == 'prod') return true;
+    return false; // coverage:ignore-line
+  }
+}
+```
+
+## Flutter Ultra Integration
+
+Collect coverage directly via the test runner:
+
+- `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` — Run tests with `coverage: true` to collect LCOV data
+- `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` — Get results including coverage report path
+
+---
+
+> **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.