@bdayadev/flutter-ultra-mcp 0.0.0 → 1.0.1

package/shared/state-store/README.md

@@ -1,66 +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).
+# @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

@@ -1,60 +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"
-  }
-}
+{
+  "name": "@flutter-ultra/state-store",
+  "version": "0.0.1",
+  "private": true,
+  "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

@@ -1,135 +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).
+# @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

@@ -1,62 +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"
-  }
-}
+{
+  "name": "@flutter-ultra/vm-service-client",
+  "version": "0.0.1",
+  "private": true,
+  "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"
+  }
+}