diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7aa1a07..33dd5f2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,11 +7,11 @@ Guidance for Claude Code working in the `fluttersdk_telescope` repo. Path-scoped ## Stack -Flutter SDK package (Dart 3.4+, Flutter 3.22+). Plugin of `fluttersdk_artisan ^0.0.6`: contributes +Flutter SDK package (Dart 3.4+, Flutter 3.22+). Plugin of `fluttersdk_artisan ^0.0.8`: contributes `TelescopeArtisanProvider` with 6 CLI commands plus 9 MCP tools backed by 11 `ext.telescope.*` VM Service extensions. -Production deps are hosted only (no `pubspec_overrides.yaml`): `fluttersdk_artisan ^0.0.6`, `logging ^1.2.0`, +Production deps are hosted only (no `pubspec_overrides.yaml`): `fluttersdk_artisan ^0.0.8`, `logging ^1.2.0`, `meta ^1.16.0`. Dev deps: `flutter_test`, `flutter_lints ^5.0.0`. Debug-only at the consumer call site: the consumer wraps `TelescopePlugin.install()` in `if (kDebugMode)` so release builds tree-shake the subsystem. diff --git a/CHANGELOG.md b/CHANGELOG.md index ae1789f..9b8bae4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,19 +8,20 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0. ## [Unreleased] -### Fixed - -- **`telescope:install` no longer injects the `magic_devtools` import when `lib/main.dart` has no `await Magic.init(` anchor.** Previously, the magic-side wiring block fired for any project that listed `magic_devtools` in pubspec regardless of whether the app called `Magic.init`. On a vanilla Flutter app this left an unused import that broke `dart analyze` in the consumer. The block is now gated on `hasMagicInit && _hasMagicDevtoolsDep()` so the import and `MagicTelescopeIntegration.install()` call are only injected for Magic-stack apps that actually call `Magic.init`. The existing try/catch around `injectAfterMagicInit` is retained as a defensive backstop. +## [0.0.4] - 2026-06-17 ### Changed -- **`telescope:install` now injects `import 'package:magic_devtools/telescope.dart';` and gates the Magic-stack wiring on the `magic_devtools` dependency** instead of the removed `package:magic/telescope_integration.dart`. Coordinated with the `magic_devtools` extraction that moved `MagicTelescopeIntegration` out of the magic core package. The injected `MagicTelescopeIntegration.install()` call and all other wiring are unchanged. +- **`fluttersdk_artisan` constraint bumped `^0.0.6` -> `^0.0.8`.** Required for co-installability with `fluttersdk_dusk` 0.0.7, which declares `fluttersdk_artisan: ^0.0.8`. Without this bump, a downstream package listing both `fluttersdk_dusk: ^0.0.7` and `fluttersdk_telescope` would fail pub dependency resolution. No public API change; constraint only. +- **`telescope:install` now injects `import 'package:magic_devtools/telescope.dart';` and gates the Magic-stack wiring on the `magic_devtools` dependency** instead of the removed `package:magic/telescope_integration.dart`. Coordinated with the `magic_devtools` extraction that moved `MagicTelescopeIntegration` (plus the 5 Magic watchers and `MagicHttpFacadeAdapter`) out of the magic core package. The injected `MagicTelescopeIntegration.install()` call and all other wiring are unchanged. -## [0.0.4] - 2026-06-17 +### Fixed -### Changed +- **`telescope:install` no longer injects the `magic_devtools` import when `lib/main.dart` has no `await Magic.init(` anchor.** Previously, the magic-side wiring block fired for any project that listed `magic_devtools` in pubspec regardless of whether the app called `Magic.init`. On a vanilla Flutter app this left an unused import that broke `dart analyze` in the consumer. The block is now gated on `hasMagicInit && _hasMagicDevtoolsDep()` so the import and `MagicTelescopeIntegration.install()` call are only injected for Magic-stack apps that actually call `Magic.init`. The existing try/catch around `injectAfterMagicInit` is retained as a defensive backstop. -- **`fluttersdk_artisan` constraint bumped `^0.0.6` -> `^0.0.8`.** Required for co-installability with `fluttersdk_dusk` 0.0.7, which declares `fluttersdk_artisan: ^0.0.8`. Without this bump, a downstream package listing both `fluttersdk_dusk: ^0.0.7` and `fluttersdk_telescope` would fail pub dependency resolution. No public API change; constraint only. +### Documentation + +- Synced docs, skill files, `README.md`, and `CLAUDE.md` to the `magic_devtools` extraction and the `fluttersdk_artisan ^0.0.8` bump. The Magic-stack telescope adapter is now documented as shipping in `magic_devtools` (imported via `package:magic_devtools/telescope.dart`, added as a dev_dependency); the installation / quickstart / watchers pages, the MCP setup snippet, and the skill (`SKILL.md` + references) reflect the `magic_devtools` dependency gate and import. Dependency-version pins bumped from `^0.0.3` to `^0.0.4` across `README.md`, `doc/getting-started/installation.md`, `doc/getting-started/quickstart.md`, and `doc/mcp/setup.md`; skill version stamp bumped to 0.0.4. ## [0.0.3] - 2026-05-28 diff --git a/CLAUDE.md b/CLAUDE.md index 7aa1a07..33dd5f2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,11 +7,11 @@ Guidance for Claude Code working in the `fluttersdk_telescope` repo. Path-scoped ## Stack -Flutter SDK package (Dart 3.4+, Flutter 3.22+). Plugin of `fluttersdk_artisan ^0.0.6`: contributes +Flutter SDK package (Dart 3.4+, Flutter 3.22+). Plugin of `fluttersdk_artisan ^0.0.8`: contributes `TelescopeArtisanProvider` with 6 CLI commands plus 9 MCP tools backed by 11 `ext.telescope.*` VM Service extensions. -Production deps are hosted only (no `pubspec_overrides.yaml`): `fluttersdk_artisan ^0.0.6`, `logging ^1.2.0`, +Production deps are hosted only (no `pubspec_overrides.yaml`): `fluttersdk_artisan ^0.0.8`, `logging ^1.2.0`, `meta ^1.16.0`. Dev deps: `flutter_test`, `flutter_lints ^5.0.0`. Debug-only at the consumer call site: the consumer wraps `TelescopePlugin.install()` in `if (kDebugMode)` so release builds tree-shake the subsystem. diff --git a/README.md b/README.md index 5b55a0e..2625d52 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ After install, the consumer gets the artisan fast-cli at `./bin/fsa` (native AOT | 🔌 | **Adapter Contract** | `TelescopeHttpAdapter` (abstract, 3-method shape) for plugging any HTTP client; ships `DioHttpAdapter` for vanilla Dio | | 📋 | **9 Record Types** | Immutable: `HttpRequestRecord`, `LogRecordEntry`, `ExceptionRecord`, `MagicModelRecord`, `MagicCacheRecord`, `EventRecord`, `GateRecord`, `DumpRecord`, `QueryRecord` | | 📡 | **VM Service Extensions** | 11 extensions: `ext.telescope.requests`, `.console`, `.exceptions`, `.events`, `.gates`, `.dumps`, `.queries`, `.caches`, `.clear`, `.pause`, `.resume` | -| ✨ | **Magic Integration** | `MagicTelescopeIntegration.install()` wires Http facade adapter + model/cache/event/gate watchers in one call | +| ✨ | **Magic Integration** | `MagicTelescopeIntegration.install()` wires Http facade adapter + model/cache/event/gate watchers in one call (ships in the `magic_devtools` dev_dependency) | | 🔒 | **Debug-only Gate** | Consumer wraps install inside `if (kDebugMode)`; release builds tree-shake the entire telescope branch on all platforms | | 🔄 | **Idempotent Install** | Every `registerExtension` call routes through `registerExtensionIdempotent`; hot-restart safe, no `ArgumentError` on re-registration | @@ -86,7 +86,7 @@ For everyday repeat usage, the consumer's `./bin/fsa` (artisan native AOT binary ```yaml # pubspec.yaml dependencies: - fluttersdk_telescope: ^0.0.3 + fluttersdk_telescope: ^0.0.4 ``` #### 2. Install in `main.dart` @@ -96,6 +96,7 @@ Install Telescope before `Magic.init()` (or before `runApp` for plain Flutter). ```dart import 'package:flutter/foundation.dart'; import 'package:fluttersdk_telescope/telescope.dart'; +import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only) void main() async { WidgetsFlutterBinding.ensureInitialized(); @@ -114,6 +115,8 @@ void main() async { await Magic.init(configFactories: [...]); if (kDebugMode) { + // MagicTelescopeIntegration ships in magic_devtools (not magic core). + // Add magic_devtools to dev_dependencies in pubspec.yaml. MagicTelescopeIntegration.install(); } diff --git a/doc/getting-started/index.md b/doc/getting-started/index.md index e2298d3..5ab6061 100644 --- a/doc/getting-started/index.md +++ b/doc/getting-started/index.md @@ -52,7 +52,7 @@ Out of the box after `telescope:install`, Telescope captures: - **Exceptions**: uncaught errors via `ExceptionWatcher` (opt-in, chain-preserves Sentry/Bugsnag). - **debugPrint output**: via `DumpWatcher` (opt-in, chain-preserves prior override). -With the Magic stack (`MagicTelescopeIntegration.install()`): +With the Magic stack (`MagicTelescopeIntegration.install()` from `magic_devtools`): - **HTTP traffic** through the Magic `Http` facade. - **Model lifecycle**: create, save, delete events on Magic Eloquent models. diff --git a/doc/getting-started/installation.md b/doc/getting-started/installation.md index 2d146ce..439bec3 100644 --- a/doc/getting-started/installation.md +++ b/doc/getting-started/installation.md @@ -42,10 +42,11 @@ The command performs three operations in order: if it is missing. This is a no-op when the harness is already present. 2. Runs `plugin:install fluttersdk_telescope`, which registers `TelescopeArtisanProvider` in `.artisan/plugins.json` and refreshes the codegen barrel. -3. Patches `lib/main.dart` to call `TelescopePlugin.install()` before `runApp`. When using - the Magic framework, the patch places the call before `Magic.init()` so the Http facade - is wired before MagicTelescopeIntegration runs. The patch is wrapped in a `kDebugMode` - guard automatically. +3. Patches `lib/main.dart` to call `TelescopePlugin.install()` before `runApp`. When the + consumer's `pubspec.yaml` lists `magic_devtools:` (as a dependency or dev_dependency) and + `lib/main.dart` contains `await Magic.init(`, the patch also injects + `import 'package:magic_devtools/telescope.dart';` plus a `MagicTelescopeIntegration.install()` + block after `Magic.init()`. All patches are wrapped in a `kDebugMode` guard automatically. The command is idempotent. Re-running it when the files are already patched is safe. @@ -71,11 +72,17 @@ patch cannot locate the correct anchor in `lib/main.dart`. ### 1. Add the dependency -Add `fluttersdk_telescope` to `pubspec.yaml`: +Add `fluttersdk_telescope` to `pubspec.yaml`. For Magic-stack apps, also add `magic_devtools` +to `dev_dependencies`: that package ships `MagicTelescopeIntegration` and the 5 Magic-specific +watchers (previously part of the `magic` core package). ```yaml dependencies: - fluttersdk_telescope: ^0.0.3 + fluttersdk_telescope: ^0.0.4 + +# Magic-stack apps only: +dev_dependencies: + magic_devtools: any ``` Then fetch dependencies: @@ -93,6 +100,7 @@ MagicTelescopeIntegration runs: ```dart import 'package:flutter/foundation.dart'; import 'package:fluttersdk_telescope/telescope.dart'; +import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only) void main() async { WidgetsFlutterBinding.ensureInitialized(); @@ -112,7 +120,8 @@ void main() async { if (kDebugMode) { // 4. Magic-specific adapters resolve framework internals from the IoC container; - // they must run after Magic.init(). + // they must run after Magic.init(). MagicTelescopeIntegration ships in + // magic_devtools; add it to dev_dependencies alongside fluttersdk_telescope. MagicTelescopeIntegration.install(); } diff --git a/doc/getting-started/quickstart.md b/doc/getting-started/quickstart.md index 5f807ac..ec86631 100644 --- a/doc/getting-started/quickstart.md +++ b/doc/getting-started/quickstart.md @@ -27,13 +27,17 @@ looks like: ``` [plugin:install] registered TelescopeArtisanProvider [main.dart] injected TelescopePlugin.install() before framework init -[main.dart] injected MagicTelescopeIntegration.install() after Magic.init() (when using Magic framework) +[main.dart] injected import 'package:magic_devtools/telescope.dart'; +[main.dart] injected MagicTelescopeIntegration.install() after Magic.init() (when magic_devtools is in pubspec) telescope:install done ``` -When using the Magic framework, `MagicTelescopeIntegration.install()` is also injected after -`Magic.init()` so all 9 watchers activate automatically. On a vanilla Flutter app only -the core watchers (`LogWatcher`, plus any you opt into manually) are wired. +When the consumer's `pubspec.yaml` lists `magic_devtools:` and `lib/main.dart` contains +`await Magic.init(`, the install command also injects the `package:magic_devtools/telescope.dart` +import and a `MagicTelescopeIntegration.install()` block after `Magic.init()` so all 9 watchers +activate automatically. `MagicTelescopeIntegration` ships in the `magic_devtools` package (not in +the `magic` core). On a vanilla Flutter app only the core watchers (`LogWatcher`, plus any you opt +into manually) are wired. Verify the provider registered correctly. From now on, the artisan fast-cli at `./bin/fsa` (native AOT, ~110ms warm) is the recommended entry point for every subsequent command: @@ -146,7 +150,9 @@ are needed between queries; the buffers update passively as the app runs. --- -All three steps above use only the `fluttersdk_telescope ^0.0.3` package and its +All three steps above use only the `fluttersdk_telescope ^0.0.4` package and its `fluttersdk_artisan` dependency. No additional packages are required for the core -watcher surface. Magic-specific watchers activate automatically when the Magic stack -is present and `MagicTelescopeIntegration.install()` is called. +watcher surface. Magic-specific watchers activate automatically when `magic_devtools` +is in `dev_dependencies` and `MagicTelescopeIntegration.install()` is called after +`Magic.init()`. `MagicTelescopeIntegration` ships in `magic_devtools`, not in the +`magic` core package. diff --git a/doc/mcp/setup.md b/doc/mcp/setup.md index 2cbfd40..a11fa80 100644 --- a/doc/mcp/setup.md +++ b/doc/mcp/setup.md @@ -18,7 +18,7 @@ because `TelescopePlugin` is imported by `lib/main.dart`): ```yaml # pubspec.yaml dependencies: - fluttersdk_telescope: ^0.0.3 + fluttersdk_telescope: ^0.0.4 ``` Run `dart pub get` after editing. @@ -46,14 +46,19 @@ the call before `Magic.init()` so the Http facade is wired in time: ```dart import 'package:flutter/foundation.dart'; import 'package:fluttersdk_telescope/telescope.dart'; +import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only) Future main() async { if (kDebugMode) { TelescopePlugin.install(); - // Optional: when using the Magic framework, register its adapters and watchers. - // Call MagicTelescopeIntegration.install() after Magic.init(). } await Magic.init(...); + if (kDebugMode) { + // Optional: when using the Magic framework, register its adapters and watchers. + // Call MagicTelescopeIntegration.install() after Magic.init(). Ships in the + // magic_devtools dev_dependency (import 'package:magic_devtools/telescope.dart'). + MagicTelescopeIntegration.install(); + } runApp(MagicApplication()); } ``` diff --git a/doc/watchers/index.md b/doc/watchers/index.md index e4615ae..f0bd5f7 100644 --- a/doc/watchers/index.md +++ b/doc/watchers/index.md @@ -231,9 +231,12 @@ matching by call order. `pendingCount` returns the current length of the in-flight FIFO, surfaced into `TelescopeStore.pendingHttpCount` for Dusk's network-idle detection. -Registration (via `MagicTelescopeIntegration`, the only documented entry point): +Registration (via `MagicTelescopeIntegration`, the only documented entry point; ships in +`magic_devtools` via `import 'package:magic_devtools/telescope.dart'`): ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // registers MagicHttpFacadeAdapter + 5 watchers @@ -247,9 +250,10 @@ if (kDebugMode) { ## Magic-stack watchers -These five watchers are shipped inside the `magic` package via `MagicTelescopeIntegration`. They -are not part of the `fluttersdk_telescope` core. All five are registered by a single -`MagicTelescopeIntegration.install()` call. +These five watchers are shipped inside the `magic_devtools` package via `MagicTelescopeIntegration`. +They are not part of the `fluttersdk_telescope` core and are not part of the `magic` core package. +All five are registered by a single `MagicTelescopeIntegration.install()` call. Add `magic_devtools` +to `dev_dependencies` and import `package:magic_devtools/telescope.dart` to use them. ### MagicModelWatcher @@ -257,6 +261,7 @@ are not part of the `fluttersdk_telescope` core. All five are registered by a si |---|---| | Contract | `TelescopeWatcher` | | Name | `magic_model` | +| Package | `magic_devtools` (import `package:magic_devtools/telescope.dart`) | | Auto-install | Yes (via `MagicTelescopeIntegration.install()`) | | Ring buffer | `TelescopeStore._models` | | VM extension | `ext.telescope.requests` (via models key; MCP tool: `telescope_models`) | @@ -270,6 +275,8 @@ and `attributes` (snapshot of `model.attributes` at capture time). Registration: ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // MagicModelWatcher is included @@ -287,6 +294,7 @@ clean dispatcher call `EventDispatcher.instance.clear()` in their `setUp`. |---|---| | Contract | `TelescopeWatcher` | | Name | `magic_cache` | +| Package | `magic_devtools` (import `package:magic_devtools/telescope.dart`) | | Auto-install | Yes (via `MagicTelescopeIntegration.install()`) | | Ring buffer | `TelescopeStore._caches` | | VM extension | `ext.telescope.caches` | @@ -300,6 +308,8 @@ Subscribes to five cache lifecycle events emitted by Magic's `CacheManager`: `Ca Registration: ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // MagicCacheWatcher is included @@ -316,6 +326,7 @@ if (kDebugMode) { |---|---| | Contract | `TelescopeWatcher` | | Name | `magic_event` | +| Package | `magic_devtools` (import `package:magic_devtools/telescope.dart`) | | Auto-install | Yes (via `MagicTelescopeIntegration.install()`) | | Ring buffer | `TelescopeStore._events` | | VM extension | `ext.telescope.events` | @@ -333,6 +344,8 @@ follow-up release while the `EventRecord` wire shape stabilises. Registration: ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // MagicEventWatcher is included @@ -349,6 +362,7 @@ if (kDebugMode) { |---|---| | Contract | `TelescopeWatcher` | | Name | `magic_gate` | +| Package | `magic_devtools` (import `package:magic_devtools/telescope.dart`) | | Auto-install | Yes (via `MagicTelescopeIntegration.install()`) | | Ring buffer | `TelescopeStore._gates` | | VM extension | `ext.telescope.gates` | @@ -369,6 +383,8 @@ anything else falls back to `toString()`. Registration: ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // MagicGateWatcher is included @@ -385,6 +401,7 @@ if (kDebugMode) { |---|---| | Contract | `TelescopeWatcher` | | Name | `magic_query` | +| Package | `magic_devtools` (import `package:magic_devtools/telescope.dart`) | | Auto-install | Yes (via `MagicTelescopeIntegration.install()`) | | Ring buffer | `TelescopeStore._queries` | | VM extension | `ext.telescope.queries` | @@ -400,6 +417,8 @@ Surfaced via the `telescope:queries` CLI command and the `telescope_queries` MCP Registration: ```dart +import 'package:magic_devtools/telescope.dart'; + if (kDebugMode) { TelescopePlugin.install(); MagicTelescopeIntegration.install(); // MagicQueryWatcher is included diff --git a/skills/fluttersdk-telescope/SKILL.md b/skills/fluttersdk-telescope/SKILL.md index 450a704..007df48 100644 --- a/skills/fluttersdk-telescope/SKILL.md +++ b/skills/fluttersdk-telescope/SKILL.md @@ -1,11 +1,11 @@ --- name: fluttersdk-telescope description: "fluttersdk_telescope: passive runtime inspector for Flutter apps. Lets an LLM agent read what the app captured (HTTP traffic, structured logs, uncaught exceptions, debug dumps, in-app events, gate checks, DB queries, Magic Cache ops) by calling 9 MCP tools (`telescope_*`) or 6 CLI commands (`./bin/fsa telescope:*`). Records land in 9 in-memory ring buffers (500 entries each, FIFO eviction) backed by `ext.telescope.*` VM Service extensions. Pairs with fluttersdk_dusk: dusk drives the app, telescope reads the side effects. TRIGGER when: any `telescope_*` MCP tool call, any `telescope:*` CLI command, the user asks the agent to inspect HTTP / logs / exceptions / events / queries / cache / dump output from a running Flutter app, the user mentions ring buffer / TelescopeStore / ext.telescope, or the conversation pairs with dusk for state verification after a gesture. DO NOT TRIGGER when: only authoring flutter_test widget tests, only driving the UI without reading captured state (use fluttersdk-dusk), or only modifying Dart source without running it." -version: 0.0.3 +version: 0.0.4 when_to_use: "Any task that reads runtime state from a running Flutter app via telescope: calling `telescope_*` MCP tools to inspect HTTP / logs / exceptions / events / gates / dumps / queries / caches, invoking `./bin/fsa telescope:*` from a shell, pairing with dusk to verify side effects after a gesture, filtering logs by minimum level (FINE/INFO/WARNING/SEVERE/SHOUT), or clearing buffers before a repro." --- - + # fluttersdk_telescope @@ -37,7 +37,9 @@ restart, and verify with `./bin/fsa telescope:tail`. Magic-stack apps must additionally call `MagicTelescopeIntegration.install()` after `Magic.init()` to populate the HTTP, events, gates, queries, and magic-cache buffers - (and to expose `pendingCount` for dusk's network-idle gate). When + (and to expose `pendingCount` for dusk's network-idle gate). + `MagicTelescopeIntegration` ships in the `magic_devtools` package + (import `package:magic_devtools/telescope.dart`), not in `magic` core. When `telescope_requests` returns `{"records": []}` on a known-active app, suspect a missing adapter, not a quiet app. The CLI gives the same hint inline: `"No HTTP records (register a TelescopeHttpAdapter)."`, @@ -237,9 +239,16 @@ dart run fluttersdk_telescope telescope:install ``` `telescope:install` injects the following into `lib/main.dart`, all gated -by `if (kDebugMode)` so release builds tree-shake the entire block: +by `if (kDebugMode)` so release builds tree-shake the entire block. The +`package:magic_devtools/telescope.dart` import and the +`MagicTelescopeIntegration.install()` block are injected only for +Magic-stack projects (detected when `magic_devtools` is in pubspec and +`lib/main.dart` has an `await Magic.init(` anchor); a vanilla Flutter app +gets only the `TelescopePlugin` block: ```dart +import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency + if (kDebugMode) { TelescopePlugin.install(); TelescopePlugin.registerWatcher(ExceptionWatcher()); @@ -249,7 +258,7 @@ if (kDebugMode) { await Magic.init([...]); if (kDebugMode) { - MagicTelescopeIntegration.install(); // only when magic is in pubspec + MagicTelescopeIntegration.install(); // only when magic_devtools is in pubspec } ``` diff --git a/skills/fluttersdk-telescope/references/cli-commands.md b/skills/fluttersdk-telescope/references/cli-commands.md index 664de1f..5487ce5 100644 --- a/skills/fluttersdk-telescope/references/cli-commands.md +++ b/skills/fluttersdk-telescope/references/cli-commands.md @@ -53,9 +53,10 @@ re-run. TelescopePlugin.registerWatcher(ExceptionWatcher()); TelescopePlugin.registerWatcher(DumpWatcher()); ``` - - When pubspec contains `magic:` and `lib/main.dart` contains - `await Magic.init(`, also injects - `MagicTelescopeIntegration.install();` inside a second + - When pubspec contains `magic_devtools:` (as a dependency or + dev_dependency) and `lib/main.dart` contains `await Magic.init(`, + also injects `import 'package:magic_devtools/telescope.dart';` + plus `MagicTelescopeIntegration.install();` inside a second `kDebugMode` block after `Magic.init()` completes. All three sub-steps check for a string anchor before inserting, so the @@ -76,6 +77,7 @@ $ dart run fluttersdk_telescope telescope:install [ok] Plugin registered. [info] Patching lib/main.dart... [ok] TelescopePlugin.install() injected before await Magic.init(...). +[ok] import 'package:magic_devtools/telescope.dart' injected. [ok] MagicTelescopeIntegration.install() injected after Magic.init(...). [ok] Done. ``` diff --git a/skills/fluttersdk-telescope/references/community.md b/skills/fluttersdk-telescope/references/community.md index d858bcf..2b5efdc 100644 --- a/skills/fluttersdk-telescope/references/community.md +++ b/skills/fluttersdk-telescope/references/community.md @@ -43,7 +43,7 @@ A genuine telescope-side bug per SKILL.md Section 8. Before drafting, re-check t - `{"records": []}` from `telescope_requests` when no `TelescopeHttpAdapter` is registered (the CLI even hints this inline: "No HTTP records (register a TelescopeHttpAdapter)."). - `{"caches": []}` always: documented placeholder, Magic does not yet emit `CacheHit / CacheMiss / CachePut / CacheForget / CacheFlush` events. -- `{"queries": []}` / `{"events": []}` / `{"gates": []}` when `MagicTelescopeIntegration.install()` was not called after `Magic.init()`, or the relevant `Magic*Watcher` is not installed. +- `{"queries": []}` / `{"events": []}` / `{"gates": []}` when `MagicTelescopeIntegration.install()` (from `magic_devtools`) was not called after `Magic.init()`, or the relevant `Magic*Watcher` is not installed. - A swallowed `try / catch` not appearing in `telescope_exceptions`: documented, that buffer captures uncaught only (`FlutterError.onError` + `PlatformDispatcher.instance.onError`). - Consumer-app exception text surfaced through `telescope_exceptions`: telescope only captured it, the bug lives in the consumer's code. - Raw `dart:io HttpClient` traffic missing from `telescope_requests`: only adapter-routed traffic is captured by design. diff --git a/skills/fluttersdk-telescope/references/workflows.md b/skills/fluttersdk-telescope/references/workflows.md index 84ec15f..bc6edf6 100644 --- a/skills/fluttersdk-telescope/references/workflows.md +++ b/skills/fluttersdk-telescope/references/workflows.md @@ -250,7 +250,8 @@ telescope_requests { limit: 1 } If the response is `{"records": []}` on a known-active app, the adapter is the missing piece. Fix by ensuring -`MagicTelescopeIntegration.install()` runs after `Magic.init()` in +`MagicTelescopeIntegration.install()` (from `magic_devtools`, import +`package:magic_devtools/telescope.dart`) runs after `Magic.init()` in `lib/main.dart`. For non-Magic apps, register `DioHttpAdapter` manually: