@bdayadev/flutter-ultra-mcp 0.0.0

package/shared/state-store/README.md

@@ -0,0 +1,66 @@
+# @flutter-ultra/state-store
+
+File-based IPC for the flutter-ultra-mcp plugin's 8 servers. Atomic
+read-modify-write of JSON state files via [`proper-lockfile`](https://www.npmjs.com/package/proper-lockfile),
+plus an append-only JSONL writer for streams (log tails, screencast frames).
+
+## Why files, not a daemon
+
+Each MCP server is a separate process spawned by Claude Code. A daemon would
+add another moving part with its own failure surface; the file model means:
+
+- **No bootstrap order**: servers start independently.
+- **Survives restarts**: state persists when a single server crashes and is
+  re-spawned.
+- **Cross-tool inspection**: `cat ${CLAUDE_PLUGIN_DATA}/state/sessions.json`
+  works as a debugging primitive.
+
+## Storage layout
+
+```
+${CLAUDE_PLUGIN_DATA}/state/
+  sessions.json              ← runtime server writes, others read
+  jobs/<jobId>.json          ← split-tool job state (build_runner_build, etc.)
+  streams/<streamId>.jsonl   ← append-only event streams (tail_logs, etc.)
+  locks/                     ← proper-lockfile metadata
+```
+
+`CLAUDE_PLUGIN_DATA` is set by Claude Code; otherwise we fall back to
+`%LOCALAPPDATA%/flutter-ultra-mcp` (Windows),
+`~/Library/Application Support/flutter-ultra-mcp` (macOS),
+`$XDG_DATA_HOME/flutter-ultra-mcp` (Linux).
+
+## API
+
+```ts
+import { stateUpdate, stateRead, sessionsFilePath } from '@flutter-ultra/state-store';
+import { SessionsFileSchema, emptySessionsFile } from '@flutter-ultra/mcp-runtime';
+
+// Read with default fallback
+const file = await stateRead(sessionsFilePath(), emptySessionsFile(), SessionsFileSchema);
+
+// Lock-guarded mutation
+await stateUpdate(sessionsFilePath(), emptySessionsFile(), SessionsFileSchema, (current) => ({
+  ...current,
+  sessions: [...current.sessions, newSession],
+}));
+```
+
+For continuous streams (log tails):
+
+```ts
+import { appendJsonl, readJsonl, streamFilePath } from '@flutter-ultra/state-store';
+
+await appendJsonl(
+  streamFilePath('s1'),
+  { ts: Date.now(), level: 'info', msg: '…' },
+  { maxLines: 10_000 },
+);
+
+// Reader polls with a cursor
+const { entries, cursor } = await readJsonl(streamFilePath('s1'), (raw) => raw, /*afterCursor*/ 0);
+```
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/shared/state-store/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@flutter-ultra/state-store",
+  "version": "0.0.1",
+  "private": false,
+  "description": "File-based IPC for cross-server shared state. Atomic read-modify-write via proper-lockfile.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/state-store",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/state-store"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "flutter-ultra",
+    "ipc",
+    "state"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/proper-lockfile": "^4.1.4",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/shared/vm-service-client/README.md

@@ -0,0 +1,135 @@
+# @flutter-ultra/vm-service-client
+
+TypeScript Dart VM Service client with DDS multi-client coordination. Backs the
+`flutter-ultra-runtime`, `flutter-ultra-gesture`, `flutter-ultra-devtools`, and
+`flutter-ultra-patrol` MCP servers in the [flutter-ultra-mcp](https://github.com/Bdaya-Dev/flutter-ultra-mcp)
+plugin.
+
+Ports the subset of [`package:vm_service`](https://pub.dev/packages/vm_service)
+those servers actually call (~15 methods) plus the two DDS extensions that make
+coexistence with VS Code's Dart debugger safe.
+
+## Install
+
+```bash
+npm install @flutter-ultra/vm-service-client
+```
+
+## Quick start
+
+```ts
+import { VmServiceClient } from '@flutter-ultra/vm-service-client';
+
+const client = new VmServiceClient('ws://127.0.0.1:8181/abc/ws', {
+  // DDS multi-client identity. Format recommendation: flutter-ultra/<server>/<pid>
+  clientName: `flutter-ultra/runtime/${process.pid}`,
+});
+
+await client.connect();
+
+const vm = await client.getVM();
+console.log(`pid=${vm.pid} isolates=${vm.isolates.length}`);
+
+await client.streamListen('Logging');
+client.on('loggingEvent', (event) => {
+  console.log('log:', event);
+});
+
+await client.dispose();
+```
+
+Connection target also accepts `{host, port, ws_path}`:
+
+```ts
+const client = new VmServiceClient({ host: '127.0.0.1', port: 8181, ws_path: 'abc/ws' });
+```
+
+## Ported method surface
+
+| Group            | RPCs                                                                          |
+| ---------------- | ----------------------------------------------------------------------------- |
+| Inspection       | `getVM`, `getIsolate`, `getObject`, `getFlagList`, `getInstances`, `getStack` |
+| Evaluation       | `evaluate`, `evaluateInFrame`, `callServiceExtension`                         |
+| Streams          | `streamListen`, `streamCancel`                                                |
+| Execution        | `pause`, `resume`, `setLibraryDebuggable`                                     |
+| DDS coordination | `setClientName`, `getStreamHistory`                                           |
+
+Plus typed event subscriptions:
+
+- `client.on('isolateEvent' | 'extensionEvent' | 'loggingEvent' | 'stdoutEvent' | 'stderrEvent' | 'vmEvent' | 'debugEvent' | 'serviceEvent' | 'timelineEvent', (event) => …)`
+- `for await (const event of client.onIsolateEvent()) { … }` (AsyncIterable)
+- Catch-all: `client.on('event', (streamId, event) => …)`
+
+## DDS coexistence (plan §7.2)
+
+The client is designed to share a DDS instance with VS Code's Dart debugger
+without conflict. Two rules:
+
+1. Always set `clientName` to something unique-per-process. DDS uses the name
+   to identify cooperating clients for resume coordination.
+2. **Never** call `requirePermissionToResume(...)` — VS Code's debugger must
+   remain the sole resume authority. This client deliberately does NOT expose
+   that DDS RPC.
+
+## Polymorphic responses
+
+`evaluate` and `evaluateInFrame` return one of three shapes — narrow on
+`result.type`:
+
+```ts
+const result = await client.evaluate(isolateId, targetId, 'someExpression');
+switch (result.type) {
+  case '@Instance':
+    console.log('value =', result.valueAsString);
+    break;
+  case '@Error':
+    console.log('eval failed:', result.message);
+    break;
+  case 'Sentinel':
+    console.log('isolate state changed:', result.kind);
+    break;
+}
+```
+
+`getIsolate` / `getObject` throw `SentinelException` instead of returning a
+sentinel union, since the caller almost always wants to re-discover and retry
+rather than handle the sentinel inline.
+
+## Reconnect
+
+Auto-reconnect is on by default with exponential backoff
+(`[500, 1000, 2000, 4000, 8000, 14500] ms`). Tune via:
+
+```ts
+new VmServiceClient(uri, {
+  autoReconnect: true,
+  reconnectDelaysMs: [500, 1_000, 2_000, 5_000],
+});
+```
+
+Pending in-flight requests reject with `ConnectionDisposedError` on disconnect;
+listen for the `disconnect` event on the client (and the `reconnected` event
+on `client.transport`) to drive a retry loop in your tool layer.
+
+## Error model
+
+| Class                     | Thrown on                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `RpcError`                | JSON-RPC error response (carries `code`, `message`, optional `data`, originating method name) |
+| `SentinelException`       | `getIsolate` / `getObject` got back a `Sentinel` instead of the requested type                |
+| `ConnectionDisposedError` | Transport closed before the request completed                                                 |
+| `ConnectionTimeoutError`  | WS connect or per-request timeout fired                                                       |
+
+`RpcErrorCode` exports the documented VM service + DDS error codes
+(`-32601` `MethodNotFound`, `106` `IsolateMustBePaused`, etc.).
+
+## Strict typing
+
+All response shapes are validated at runtime via Zod (`.strict()` everywhere,
+no `z.any()`/`z.record()` in the schema graph), then surfaced as inferred
+TypeScript types. Schema drift in the VM service protocol fails loudly rather
+than silently corrupting downstream consumers.
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/shared/vm-service-client/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@flutter-ultra/vm-service-client",
+  "version": "0.0.1",
+  "private": false,
+  "description": "TypeScript Dart VM Service client with DDS multi-client coordination. Backs the runtime, gesture, devtools, and patrol MCP servers.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/vm-service-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/vm-service-client"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "dart",
+    "flutter",
+    "vm-service",
+    "dds",
+    "debugger",
+    "mcp"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/_internal-on-tool-failure/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: _internal-on-tool-failure
+description: Internal skill invoked by the PostToolUse hook when a flutter-ultra tool returns isError. Captures structured remediation context. Not for direct user invocation.
+disable-model-invocation: true
+---
+
+# Internal: On Tool Failure (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §12).
+
+Triggered by the `PostToolUse` hook when an `mcp__flutter-ultra-*__*` tool returns `isError: true`. Reads the failure event from `state/tool-events.jsonl`, formats a one-line remediation summary, and appends it to the conversation as a system reminder.
+
+Not advertised in the user-facing skill list.

package/skills/_internal-session-bootstrap/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: _internal-session-bootstrap
+description: Internal skill invoked by the SessionStart hook to detect Flutter context and warm cached state. Not for direct user invocation.
+disable-model-invocation: true
+---
+
+# Internal: Session Bootstrap (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §12).
+
+Triggered by the `SessionStart` hook. Performs:
+
+- Project root detection (`pubspec.yaml` walk)
+- Cached session discovery refresh
+- Plugin-doctor self-check
+- Initial telemetry frame written to `state/tool-events.jsonl`
+
+Not advertised in the user-facing skill list.

package/skills/debug/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: debug
+description: Attaching to a running Flutter app and triaging an error from the stack trace, widget tree, render tree, and recent screenshot. Use when the user reports a runtime exception, layout overflow, or unexpected behaviour and you need to inspect live state.
+---
+
+# Debug (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.3, §12).
+
+## Workflow
+
+- `mcp__flutter-ultra-runtime__discover_sessions` and pick the target app.
+- Pull recent errors with `mcp__flutter-ultra-runtime__get_runtime_errors`.
+- Cross-reference frames with `mcp__flutter-ultra-runtime__get_widget_tree` and `dump_render_tree`.
+- Capture a screenshot for context.
+- Propose a fix inline; do not edit code unless asked.
+
+## See also
+
+- Plan §8.3

package/skills/devtools/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: devtools
+description: Wiring up the Flutter DevTools panel for this plugin so the user can see live MCP activity inside their IDE. Use when the user wants to inspect the plugin's recent tool calls, attached sessions, or activity timeline.
+disable-model-invocation: true
+---
+
+# DevTools (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.6, §12).
+
+User-triggered only — installing a dev dependency and editing pubspec is opinionated.
+
+## Workflow
+
+- Detect `ultra_flutter_devtools` in `dev_dependencies`; add via `mcp__flutter-ultra-build__pub_add` if missing.
+- Start the panel WebSocket via `mcp__flutter-ultra-devtools__start_panel_server`.
+- Print the DevTools URL with the `flutter-ultra` tab anchor.
+
+## See also
+
+- Plan §8.6, §6.2

package/skills/drive/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: drive
+description: Driving multi-step user flows in a running Flutter app via gestures and assertions. Use when reproducing a bug across several screens, validating an onboarding flow, or running an ad-hoc end-to-end scenario without writing a patrol test.
+---
+
+# Drive (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.2, §12).
+
+## Workflow
+
+- Enumerate interactive elements via `mcp__flutter-ultra-gesture__interactive_elements`.
+- Tap or enter text using key-based finders.
+- Verify intermediate state via `mcp__flutter-ultra-runtime__get_widget_tree`.
+- For OAuth/popups: delegate to `mcp__flutter-ultra-browser__*` (web) or `mcp__flutter-ultra-native-mobile__*` (mobile).
+
+## See also
+
+- Plan §8.2
+- Sibling skill: `test` for orchestrated patrol runs

package/skills/scaffold/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: scaffold
+description: Scaffolding new Flutter projects or features following the conventions detected in the existing codebase. Use when starting a fresh app, adding a feature module, or generating boilerplate that should match an existing project's structure.
+disable-model-invocation: true
+---
+
+# Scaffold (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.4, §12).
+
+This skill is opinionated and destructive (creates files), so it is **not** auto-invocable. The user must trigger it explicitly with `/flutter:scaffold`.
+
+## Workflow
+
+- Project mode: `flutter create` via shell with detected channel + org.
+- Feature mode: read the existing structure via `mcp__flutter-ultra-build__project_info`, then create files that match.
+
+## See also
+
+- Plan §8.4
+- Sibling skill: `setup` for plugging the plugin into an existing codebase

package/skills/setup/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: setup
+description: Bootstrapping flutter-ultra-mcp into an existing Flutter codebase end-to-end. Use when the user wants the plugin enabled for the first time on a project, or when re-running after a clean install. Idempotent.
+disable-model-invocation: true
+---
+
+# Setup (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.7, §12).
+
+User-triggered only — patches pubspec, entry points, and `.vscode/launch.json`.
+
+## Workflow (target)
+
+1. Detect project layout via `mcp__flutter-ultra-build__project_info` (entry points, existing bindings, Sentry usage, patrol).
+2. Add `ultra_flutter` to `dev_dependencies`; if Sentry detected, show the direct `// ignore: implementation_imports` binding pattern.
+3. Patch entry point(s) with AST-aware edits to mix in `UltraFlutterBinding` under `kDebugMode`.
+4. Optional: add a launch.json profile pre-applying dart-defines for session discovery.
+5. Detect existing patrol setup and offer the `run_patrol_web` wrapper.
+6. Generate per-project `.flutter-ultra.config.yaml`.
+7. Run a smoke launch + screenshot + detach.
+8. Emit `SETUP-REPORT.md` at project root.
+
+## See also
+
+- Plan §8.7

package/skills/test/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: test
+description: Orchestrating Flutter unit, widget, and patrol E2E tests with focused reporting. Use when the user asks to run tests, validate a fix, or check coverage on a Flutter project.
+---
+
+# Test (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.5, §12).
+
+## Workflow
+
+- `mcp__flutter-ultra-build__analyze` first; fail fast on lint errors.
+- `mcp__flutter-ultra-build__run_unit_tests` / `run_widget_tests` per the input pattern.
+- `mcp__flutter-ultra-patrol__*` for E2E.
+- Report failures with file:line + a screenshot snapshot when available.
+
+## See also
+
+- Plan §8.5

package/skills/tour/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: tour
+description: Running route-by-route screenshot tours of a Flutter app. Use when capturing visual state across many app routes, doing pre-release visual regression sweeps, or documenting a feature's UI for review.
+---
+
+# Route Tour (stub)
+
+**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.1, §12).
+
+## Quick start
+
+1. Identify the active session via `mcp__flutter-ultra-runtime__discover_sessions`.
+2. For each route in the input list:
+   - Navigate (web: browser navigate, mobile/desktop: GoRouter evaluate)
+   - Wait for the root widget key
+   - Take a screenshot, save to `.omc/research/tour-<date>/<route-slug>.png`
+3. Write `tour-report.md` summarizing route to screenshot mapping.
+
+## See also
+
+- Plan §8.1
+- Sibling skill: `drive` for multi-step interaction flows