From c2df610d2edaca1787d8eb9bec242566feb34044 Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Thu, 9 Oct 2025 07:21:29 +0500 Subject: [PATCH] feat: Add version detection warnings for hot reload Add warnings in all commands that use hot_reload to inform users about the known limitation on Flutter stable <= 3.37.0. This helps users understand why hot reload may fail and provides clear guidance on workarounds (switching to Flutter main channel or manually restarting the app). Changes: - Updated /debug-app command to check Flutter version early and warn users about hot reload limitations - Added inline warnings in /create-app and /modify commands when hot_reload is used - Updated CHANGELOG.md to document this improvement Related to gemini-cli-extensions/flutter#15 --- CHANGELOG.md | 7 +++++++ commands/create-app.toml | 1 + commands/debug-app.toml | 11 ++++++++++- commands/modify.toml | 1 + 4 files changed, 19 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e8888c..07e4890 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## Unreleased + +- Added version detection warnings for hot reload on Flutter stable ≤ 3.37.0 + - Updated `/debug-app`, `/create-app`, and `/modify` commands to warn users about hot reload limitations + - Provides guidance to switch to Flutter main channel or manually restart apps when hot reload fails + - Related to [#15](https://github.com/gemini-cli-extensions/flutter/issues/15) + ## 0.3.0 - Removed the `flutter_launcher` MCP server because it has been integrated into diff --git a/commands/create-app.toml b/commands/create-app.toml index 94ae571..857684f 100644 --- a/commands/create-app.toml +++ b/commands/create-app.toml @@ -86,6 +86,7 @@ The implementation plan should specify after each phase that you should: - [ ] Use `git diff` to verify the changes that have been made, and create a suitable commit message for any changes, following any guidelines you have about commit messages. Be sure to properly escape dollar signs and backticks, and present the change message to the user for approval. - [ ] Wait for approval. Don't commit the changes or move on to the next phase of implementation until the user approves the commit. - [ ] After commiting the change, if the app is running, use the hot_reload tool to reload it. + - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. In the last phase of the plan, include steps to: diff --git a/commands/debug-app.toml b/commands/debug-app.toml index 01a96a3..3b06b9e 100644 --- a/commands/debug-app.toml +++ b/commands/debug-app.toml @@ -34,6 +34,13 @@ Next, collect additional information required for debugging. Ask the user one qu Before diving into the code, let's verify the project's dependencies and environment. - [ ] Run `flutter doctor` to get the Flutter and Dart SDK versions and check for any issues reported. +- [ ] Check the Flutter version output and determine if hot reload is supported: + - **IMPORTANT**: Hot reload through the Dart MCP server does not work reliably on Flutter stable ≤ 3.37.0 (see [issue #15](https://github.com/gemini-cli-extensions/flutter/issues/15)) + - If the user is on Flutter stable ≤ 3.37.0, warn them that hot reload may fail during this debugging session + - Suggest they either: + 1. Switch to Flutter main/master channel for full hot reload support, OR + 2. Manually restart the app after making code changes instead of using hot_reload + - If they choose to proceed with stable, acknowledge their choice and remind them about the limitation when using hot_reload later - [ ] Use the `pub` tool with the `outdated` command to look for outdated packages or dependency conflicts in `pubspec.yaml` and `pubspec.lock`. - Run the command `pub` tool with `upgrade` to upgrade to latest versions. - If that isn't sufficient, sometimes upgrading the package version to a new major version can help. The `pub` tool can't do this, so run the command `dart pub upgrade --major-versions` to do this. @@ -62,7 +69,9 @@ The debugging strategy should be chosen to yield the best results and may involv - **Logging and Tracing:** - Add strategic logging statements to the code to trace execution flow. Prefer `debugPrint()` over `print()` for cleaner, non-interfering output. - - Use `hot_reload` to apply logging changes quickly while preserving the app's state. If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. + - Use `hot_reload` to apply logging changes quickly while preserving the app's state. + - **Note**: If the user is on Flutter stable ≤ 3.37.0 and hot_reload fails, suggest they manually restart the app or switch to Flutter main channel + - If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. - **Flutter DevTools & UI Inspection:** - **For UI and layout bugs:** Use the `get_widget_tree` tool to inspect the widget hierarchy and properties. diff --git a/commands/modify.toml b/commands/modify.toml index 8d93f10..56f5843 100644 --- a/commands/modify.toml +++ b/commands/modify.toml @@ -73,6 +73,7 @@ The implementation plan should specify after each phase that you should: - [ ] Use `git diff` to verify the changes that have been made, and create a suitable commit message for any changes, following any guidelines you have about commit messages. Be sure to properly escape dollar signs and backticks, and present the change message to the user for approval. - [ ] Wait for approval. Don't commit the changes or move on to the next phase of implementation until the user approves the commit. - [ ] After commiting the change, if an app is running, use the hot_reload tool to reload it. + - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. In the last phase of the plan, include steps to: