@bdayadev/flutter-ultra-mcp 0.0.0 → 1.0.1

package/shared/device-router/README.md

@@ -1,51 +1,51 @@
-# @flutter-ultra/device-router
-
-Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.
-
-## Usage
-
-```typescript
-import { DeviceRouter } from '@flutter-ultra/device-router';
-
-const router = new DeviceRouter();
-
-// List available devices (local + WSL distros + SSH hosts)
-const devices = await router.listAvailable();
-
-// Connect to a WSL distro
-const { device, probe } = await router.connect({ kind: 'wsl', distro: 'Ubuntu-22.04' });
-
-// Run a command on the device
-const result = await device.exec(['flutter', 'build', 'linux', '--release']);
-
-// Forward a TCP port from the remote device to local
-const fwd = await device.forwardTcpPort('localhost', 8080);
-console.log(`VM service available at ws://localhost:${fwd.localPort}/ws`);
-
-// Clean up
-await fwd.close();
-await router.disconnect(device.id);
-```
-
-## Device types
-
-| Kind    | Transport             | Platform    | Use case                                |
-| ------- | --------------------- | ----------- | --------------------------------------- |
-| `local` | `child_process`       | Host OS     | Default — same machine                  |
-| `wsl`   | `wsl.exe -d <distro>` | Linux       | Flutter Linux builds/tests from Windows |
-| `ssh`   | SSH ControlMaster     | Linux/macOS | Flutter macOS builds via remote Mac     |
-
-## Legacy adapter
-
-Existing code using worker-J's v1 Device shape (`label/isLocal/exec/uploadFile/fileExists/openRpcStream`) can use the `LegacyDeviceAdapter`:
-
-```typescript
-import { LegacyDeviceAdapter } from '@flutter-ultra/device-router';
-
-const legacy = new LegacyDeviceAdapter(device);
-// legacy.label, legacy.isLocal, legacy.exec(), legacy.fileExists(), legacy.openRpcStream()
-```
-
-## License
-
-Apache-2.0
+# @flutter-ultra/device-router
+
+Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.
+
+## Usage
+
+```typescript
+import { DeviceRouter } from '@flutter-ultra/device-router';
+
+const router = new DeviceRouter();
+
+// List available devices (local + WSL distros + SSH hosts)
+const devices = await router.listAvailable();
+
+// Connect to a WSL distro
+const { device, probe } = await router.connect({ kind: 'wsl', distro: 'Ubuntu-22.04' });
+
+// Run a command on the device
+const result = await device.exec(['flutter', 'build', 'linux', '--release']);
+
+// Forward a TCP port from the remote device to local
+const fwd = await device.forwardTcpPort('localhost', 8080);
+console.log(`VM service available at ws://localhost:${fwd.localPort}/ws`);
+
+// Clean up
+await fwd.close();
+await router.disconnect(device.id);
+```
+
+## Device types
+
+| Kind    | Transport             | Platform    | Use case                                |
+| ------- | --------------------- | ----------- | --------------------------------------- |
+| `local` | `child_process`       | Host OS     | Default — same machine                  |
+| `wsl`   | `wsl.exe -d <distro>` | Linux       | Flutter Linux builds/tests from Windows |
+| `ssh`   | SSH ControlMaster     | Linux/macOS | Flutter macOS builds via remote Mac     |
+
+## Legacy adapter
+
+Existing code using worker-J's v1 Device shape (`label/isLocal/exec/uploadFile/fileExists/openRpcStream`) can use the `LegacyDeviceAdapter`:
+
+```typescript
+import { LegacyDeviceAdapter } from '@flutter-ultra/device-router';
+
+const legacy = new LegacyDeviceAdapter(device);
+// legacy.label, legacy.isLocal, legacy.exec(), legacy.fileExists(), legacy.openRpcStream()
+```
+
+## License
+
+Apache-2.0

package/shared/device-router/package.json

@@ -1,62 +1,62 @@
-{
-  "name": "@flutter-ultra/device-router",
-  "version": "0.0.1",
-  "private": false,
-  "description": "Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.",
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/device-router",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
-    "directory": "shared/device-router"
-  },
-  "bugs": {
-    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
-  },
-  "keywords": [
-    "flutter",
-    "mcp",
-    "device",
-    "wsl",
-    "ssh",
-    "remote"
-  ],
-  "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": {
-    "execa": "^9.5.1",
-    "ssh-config": "^5.0.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "rimraf": "^6.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@flutter-ultra/device-router",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/device-router",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/device-router"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "flutter",
+    "mcp",
+    "device",
+    "wsl",
+    "ssh",
+    "remote"
+  ],
+  "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": {
+    "execa": "^9.5.1",
+    "ssh-config": "^5.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/shared/keyring/README.md

@@ -1,7 +1,7 @@
-# @flutter-ultra/keyring
-
-OS-keyring-backed secret storage for plugin-managed credentials: signing certs, OIDC tokens, Sentry DSNs.
-
-**Status:** scaffold stub. Implementation owner: shared infra (wave 2).
-
-Cross-platform via native APIs — Windows Credential Manager, macOS Keychain, Linux Secret Service. Plain-filesystem fallback is intentionally absent to preserve the plan §19 security guarantee.
+# @flutter-ultra/keyring
+
+OS-keyring-backed secret storage for plugin-managed credentials: signing certs, OIDC tokens, Sentry DSNs.
+
+**Status:** scaffold stub. Implementation owner: shared infra (wave 2).
+
+Cross-platform via native APIs — Windows Credential Manager, macOS Keychain, Linux Secret Service. Plain-filesystem fallback is intentionally absent to preserve the plan §19 security guarantee.

package/shared/keyring/package.json

@@ -1,24 +1,24 @@
-{
-  "name": "@flutter-ultra/keyring",
-  "version": "0.0.0",
-  "private": true,
-  "description": "OS-keyring-backed secret storage for plugin-managed credentials (signing certs, OIDC tokens, Sentry DSNs).",
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -b",
-    "lint": "eslint src",
-    "test": "vitest run",
-    "typecheck": "tsc -b --noEmit",
-    "clean": "rimraf dist .turbo *.tsbuildinfo"
-  },
-  "dependencies": {
-    "@napi-rs/keyring": "^1.3.0"
-  }
-}
+{
+  "name": "@flutter-ultra/keyring",
+  "version": "0.0.0",
+  "private": true,
+  "description": "OS-keyring-backed secret storage for plugin-managed credentials (signing certs, OIDC tokens, Sentry DSNs).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  }
+}

package/shared/mcp-runtime/README.md

@@ -1,116 +1,116 @@
-# @flutter-ultra/mcp-runtime
-
-Shared MCP server scaffolding for the flutter-ultra-mcp plugin's 8 servers.
-Encapsulates the recurring patterns — stdio transport boot, Zod-validated
-tools, watchdog/timeout enforcement, keep-alive against
-[Claude Code #58004](https://github.com/anthropics/claude-code/issues/58004),
-the cross-server session model, and the canonical FinderSpec for widget
-lookups — so each server's `src/index.ts` stays focused on its tool catalogue.
-
-## Quick start
-
-```ts
-import { createServer } from '@flutter-ultra/mcp-runtime';
-import { z } from 'zod';
-
-const server = createServer({
-  info: { name: 'flutter-ultra-runtime', version: '0.0.1' },
-});
-
-server.defineTool(
-  {
-    name: 'list_sessions',
-    description: 'List active Flutter sessions attached by this server.',
-    timeoutClass: 'instant',
-    annotations: { readOnlyHint: true, idempotentHint: true },
-  },
-  async () => ({
-    sessions: [
-      /* ... */
-    ],
-  }),
-);
-
-server.defineTool(
-  {
-    name: 'hot_reload',
-    description: 'Trigger a hot reload on the given session.',
-    inputShape: { sessionId: z.string().min(8) },
-    timeoutClass: 'quick',
-    ceilingMs: 60_000,
-  },
-  async ({ sessionId }, { signal, sendProgress }) => {
-    sendProgress({ progress: 0, message: 'Sending reloadSources to VM service' });
-    // ... handler body with signal-aware aborts
-    return { ok: true, sessionId };
-  },
-);
-
-await server.start();
-process.on('SIGTERM', () => server.stop());
-```
-
-## Components
-
-| Module         | Exports                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------ |
-| `server.ts`    | `createServer`, `defineTool` — high-level builder over `@modelcontextprotocol/sdk`                     |
-| `watchdog.ts`  | `runWithWatchdog`, `TimeoutClass`, `DEFAULT_CEILINGS_MS` — per-tool hard cap + AbortSignal propagation |
-| `keepAlive.ts` | `startKeepAlive` — periodic `notifications/message` debug ping (plan §17.9)                            |
-| `logger.ts`    | `createLogger` — JSON-lines stderr logger with per-tool child loggers                                  |
-| `session.ts`   | `Session`, `SessionResource`, `SessionsFile` — cross-server session model                              |
-| `finder.ts`    | `FinderSchema`, `FinderSpec`, `matchesText` — shared discriminated union for widget lookups            |
-| `errors.ts`    | `ToolWatchdogTimeoutError`, `SessionNotFoundError`, etc.                                               |
-
-## Timeout classes (plan §17.2)
-
-| Class      | Ceiling | When to use                                                        |
-| ---------- | ------- | ------------------------------------------------------------------ |
-| `instant`  | 10 s    | < 1 s p95: `list_sessions`, `get_widget_tree` on small trees       |
-| `quick`    | 30 s    | 1–5 s p95: `hot_reload`, `screenshot`, `tap`                       |
-| `long`     | 55 s    | 5–55 s p95: `dump_render_tree`, `wait_for` (always emit progress)  |
-| `marathon` | 55 s    | > 55 s: MUST be split-tool (`start_*` / `poll_*` / `get_*_result`) |
-
-Per-tool override via env var: `FLUTTER_ULTRA_TOOL_TIMEOUT_<NAME_UPPER>=120000`.
-
-## Session model
-
-Sessions live as JSON in `${CLAUDE_PLUGIN_DATA}/state/sessions.json` (path
-resolved by `@flutter-ultra/state-store`). The runtime server is the sole
-writer; gesture / devtools / patrol read-only. Each session carries:
-
-```
-{ id, uri, source, clientName, attachedAt, lastSeenAt,
-  status, pid?, projectRoot?, device?, isolateIds?, appName? }
-```
-
-`SessionResource<T>` reference-counts an expensive per-session resource
-(e.g. the `VmServiceClient` WebSocket) so multiple parallel tool calls
-share one connection per plan §17.10.
-
-## FinderSpec
-
-Discriminated union used by both runtime (`widget_exists`, `find_widget`)
-and gesture (`tap`, `enter_text`, `wait_for`) so an agent's "is the widget
-in the tree?" check uses the exact same matcher as the subsequent tap:
-
-```ts
-type FinderSpec =
-  | { kind: 'key'; value: string }
-  | {
-      kind: 'text';
-      value: string;
-      matchType?: 'exact' | 'contains' | 'regex';
-      caseInsensitive?: boolean;
-    }
-  | { kind: 'type'; value: string }
-  | { kind: 'coords'; x: number; y: number }
-  | { kind: 'semanticsLabel'; value: string; matchType?: 'exact' | 'contains' | 'regex' }
-  | { kind: 'tooltip'; value: string; matchType?: 'exact' | 'contains' | 'regex' };
-```
-
-`matchesText(candidate, spec)` is the shared comparator both consumers use.
-
-## License
-
-Apache-2.0. See [LICENSE](../../LICENSE).
+# @flutter-ultra/mcp-runtime
+
+Shared MCP server scaffolding for the flutter-ultra-mcp plugin's 8 servers.
+Encapsulates the recurring patterns — stdio transport boot, Zod-validated
+tools, watchdog/timeout enforcement, keep-alive against
+[Claude Code #58004](https://github.com/anthropics/claude-code/issues/58004),
+the cross-server session model, and the canonical FinderSpec for widget
+lookups — so each server's `src/index.ts` stays focused on its tool catalogue.
+
+## Quick start
+
+```ts
+import { createServer } from '@flutter-ultra/mcp-runtime';
+import { z } from 'zod';
+
+const server = createServer({
+  info: { name: 'flutter-ultra-runtime', version: '0.0.1' },
+});
+
+server.defineTool(
+  {
+    name: 'list_sessions',
+    description: 'List active Flutter sessions attached by this server.',
+    timeoutClass: 'instant',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+  },
+  async () => ({
+    sessions: [
+      /* ... */
+    ],
+  }),
+);
+
+server.defineTool(
+  {
+    name: 'hot_reload',
+    description: 'Trigger a hot reload on the given session.',
+    inputShape: { sessionId: z.string().min(8) },
+    timeoutClass: 'quick',
+    ceilingMs: 60_000,
+  },
+  async ({ sessionId }, { signal, sendProgress }) => {
+    sendProgress({ progress: 0, message: 'Sending reloadSources to VM service' });
+    // ... handler body with signal-aware aborts
+    return { ok: true, sessionId };
+  },
+);
+
+await server.start();
+process.on('SIGTERM', () => server.stop());
+```
+
+## Components
+
+| Module         | Exports                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------ |
+| `server.ts`    | `createServer`, `defineTool` — high-level builder over `@modelcontextprotocol/sdk`                     |
+| `watchdog.ts`  | `runWithWatchdog`, `TimeoutClass`, `DEFAULT_CEILINGS_MS` — per-tool hard cap + AbortSignal propagation |
+| `keepAlive.ts` | `startKeepAlive` — periodic `notifications/message` debug ping (plan §17.9)                            |
+| `logger.ts`    | `createLogger` — JSON-lines stderr logger with per-tool child loggers                                  |
+| `session.ts`   | `Session`, `SessionResource`, `SessionsFile` — cross-server session model                              |
+| `finder.ts`    | `FinderSchema`, `FinderSpec`, `matchesText` — shared discriminated union for widget lookups            |
+| `errors.ts`    | `ToolWatchdogTimeoutError`, `SessionNotFoundError`, etc.                                               |
+
+## Timeout classes (plan §17.2)
+
+| Class      | Ceiling | When to use                                                        |
+| ---------- | ------- | ------------------------------------------------------------------ |
+| `instant`  | 10 s    | < 1 s p95: `list_sessions`, `get_widget_tree` on small trees       |
+| `quick`    | 30 s    | 1–5 s p95: `hot_reload`, `screenshot`, `tap`                       |
+| `long`     | 55 s    | 5–55 s p95: `dump_render_tree`, `wait_for` (always emit progress)  |
+| `marathon` | 55 s    | > 55 s: MUST be split-tool (`start_*` / `poll_*` / `get_*_result`) |
+
+Per-tool override via env var: `FLUTTER_ULTRA_TOOL_TIMEOUT_<NAME_UPPER>=120000`.
+
+## Session model
+
+Sessions live as JSON in `${CLAUDE_PLUGIN_DATA}/state/sessions.json` (path
+resolved by `@flutter-ultra/state-store`). The runtime server is the sole
+writer; gesture / devtools / patrol read-only. Each session carries:
+
+```
+{ id, uri, source, clientName, attachedAt, lastSeenAt,
+  status, pid?, projectRoot?, device?, isolateIds?, appName? }
+```
+
+`SessionResource<T>` reference-counts an expensive per-session resource
+(e.g. the `VmServiceClient` WebSocket) so multiple parallel tool calls
+share one connection per plan §17.10.
+
+## FinderSpec
+
+Discriminated union used by both runtime (`widget_exists`, `find_widget`)
+and gesture (`tap`, `enter_text`, `wait_for`) so an agent's "is the widget
+in the tree?" check uses the exact same matcher as the subsequent tap:
+
+```ts
+type FinderSpec =
+  | { kind: 'key'; value: string }
+  | {
+      kind: 'text';
+      value: string;
+      matchType?: 'exact' | 'contains' | 'regex';
+      caseInsensitive?: boolean;
+    }
+  | { kind: 'type'; value: string }
+  | { kind: 'coords'; x: number; y: number }
+  | { kind: 'semanticsLabel'; value: string; matchType?: 'exact' | 'contains' | 'regex' }
+  | { kind: 'tooltip'; value: string; matchType?: 'exact' | 'contains' | 'regex' };
+```
+
+`matchesText(candidate, spec)` is the shared comparator both consumers use.
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/shared/mcp-runtime/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@flutter-ultra/mcp-runtime",
-  "version": "0.0.1",
-  "private": false,
-  "description": "Shared MCP server scaffolding: stdio transport, watchdog/timeout, structured logging, session model, finder spec.",
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/mcp-runtime",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
-    "directory": "shared/mcp-runtime"
-  },
-  "bugs": {
-    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "flutter-ultra"
-  ],
-  "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": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "rimraf": "^6.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@flutter-ultra/mcp-runtime",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Shared MCP server scaffolding: stdio transport, watchdog/timeout, structured logging, session model, finder spec.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/mcp-runtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/mcp-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "flutter-ultra"
+  ],
+  "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": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}