@gtkx/cli 0.11.1 → 0.12.0

package/dist/cli.js

@@ -3,10 +3,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import "./refresh-runtime.js";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
+import { events } from "@gtkx/ffi";
 import { render } from "@gtkx/react";
 import { defineCommand, runMain } from "citty";
 import { createApp } from "./create.js";
 import { createDevServer } from "./dev-server.js";
+import { startMcpClient, stopMcpClient } from "./mcp-client.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const dev = defineCommand({
@@ -40,6 +42,10 @@ const dev = defineCommand({
         }
         console.log(`[gtkx] Rendering app with ID: ${appId}`);
         render(_jsx(App, {}), appId, appFlags);
+        await startMcpClient(appId);
+        events.on("stop", () => {
+            stopMcpClient();
+        });
         console.log("[gtkx] HMR enabled - watching for changes...");
     },
 });

package/dist/mcp-client.d.ts

@@ -0,0 +1,30 @@
+type McpClientOptions = {
+    socketPath?: string;
+    appId: string;
+};
+declare class McpClient {
+    private socket;
+    private buffer;
+    private socketPath;
+    private appId;
+    private reconnectTimer;
+    private hasConnected;
+    private isStopping;
+    private pendingRequests;
+    constructor(options: McpClientOptions);
+    connect(): Promise<void>;
+    private attemptConnect;
+    private scheduleReconnect;
+    disconnect(): void;
+    private rejectPendingRequests;
+    private register;
+    private send;
+    private sendRequest;
+    private handleData;
+    private processMessage;
+    private handleRequest;
+    private executeMethod;
+}
+export declare const startMcpClient: (appId: string) => Promise<McpClient>;
+export declare const stopMcpClient: () => void;
+export {};

package/dist/mcp-client.js

@@ -0,0 +1,401 @@
+import * as net from "node:net";
+import { getNativeId, getNativeObject } from "@gtkx/ffi";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { DEFAULT_SOCKET_PATH, IpcRequestSchema, IpcResponseSchema, McpError, McpErrorCode, methodNotFoundError, widgetNotFoundError, } from "@gtkx/mcp";
+import { getApplication } from "@gtkx/react";
+let testingModule = null;
+let testingLoadError = null;
+const loadTestingModule = async () => {
+    if (testingModule)
+        return testingModule;
+    if (testingLoadError)
+        throw testingLoadError;
+    try {
+        testingModule = await import("@gtkx/testing");
+        return testingModule;
+    }
+    catch (cause) {
+        testingLoadError = new Error("@gtkx/testing is not installed. Install it to enable MCP widget interactions: pnpm add -D @gtkx/testing", { cause });
+        throw testingLoadError;
+    }
+};
+const RECONNECT_DELAY_MS = 2000;
+const REQUEST_TIMEOUT_MS = 30000;
+const formatRole = (role) => {
+    if (role === undefined)
+        return "UNKNOWN";
+    return Gtk.AccessibleRole[role] ?? String(role);
+};
+const getWidgetText = (widget) => {
+    const role = widget.getAccessibleRole();
+    if (role === undefined)
+        return null;
+    switch (role) {
+        case Gtk.AccessibleRole.BUTTON:
+        case Gtk.AccessibleRole.LINK:
+        case Gtk.AccessibleRole.TAB:
+            return widget.getLabel?.() ?? widget.getLabel?.() ?? null;
+        case Gtk.AccessibleRole.TOGGLE_BUTTON:
+            return widget.getLabel?.() ?? null;
+        case Gtk.AccessibleRole.CHECKBOX:
+        case Gtk.AccessibleRole.RADIO:
+            return widget.getLabel?.() ?? null;
+        case Gtk.AccessibleRole.LABEL:
+            return widget.getLabel?.() ?? widget.getText?.() ?? null;
+        case Gtk.AccessibleRole.TEXT_BOX:
+        case Gtk.AccessibleRole.SEARCH_BOX:
+        case Gtk.AccessibleRole.SPIN_BUTTON:
+            return getNativeObject(widget.handle, Gtk.Editable).getText() ?? null;
+        case Gtk.AccessibleRole.GROUP:
+            return widget.getLabel?.() ?? null;
+        case Gtk.AccessibleRole.WINDOW:
+        case Gtk.AccessibleRole.DIALOG:
+        case Gtk.AccessibleRole.ALERT_DIALOG:
+            return widget.getTitle() ?? null;
+        default:
+            return null;
+    }
+};
+const serializeWidget = (widget) => {
+    const children = [];
+    let child = widget.getFirstChild();
+    while (child) {
+        children.push(serializeWidget(child));
+        child = child.getNextSibling();
+    }
+    const text = getWidgetText(widget);
+    return {
+        id: String(getNativeId(widget.handle)),
+        type: widget.constructor.name,
+        role: formatRole(widget.getAccessibleRole()),
+        name: widget.getName() || null,
+        label: text,
+        text,
+        sensitive: widget.getSensitive(),
+        visible: widget.getVisible(),
+        cssClasses: widget.getCssClasses() ?? [],
+        children,
+    };
+};
+const widgetRegistry = new Map();
+const registerWidgets = (widget) => {
+    const idStr = String(getNativeId(widget.handle));
+    widgetRegistry.set(idStr, widget);
+    let child = widget.getFirstChild();
+    while (child) {
+        registerWidgets(child);
+        child = child.getNextSibling();
+    }
+};
+const getWidgetById = (id) => {
+    return widgetRegistry.get(id);
+};
+const refreshWidgetRegistry = () => {
+    widgetRegistry.clear();
+    const app = getApplication();
+    if (!app)
+        return;
+    const windows = app.getWindows();
+    for (const window of windows) {
+        registerWidgets(window);
+    }
+};
+class McpClient {
+    socket = null;
+    buffer = "";
+    socketPath;
+    appId;
+    reconnectTimer = null;
+    hasConnected = false;
+    isStopping = false;
+    pendingRequests = new Map();
+    constructor(options) {
+        this.socketPath = options.socketPath ?? DEFAULT_SOCKET_PATH;
+        this.appId = options.appId;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            this.attemptConnect(resolve, reject);
+        });
+    }
+    attemptConnect(onSuccess, onError) {
+        let settled = false;
+        const settle = (callback, ...args) => {
+            if (settled)
+                return;
+            settled = true;
+            callback?.(...args);
+        };
+        this.socket = net.createConnection(this.socketPath, () => {
+            console.log(`[gtkx] Connected to MCP server at ${this.socketPath}`);
+            this.hasConnected = true;
+            this.register()
+                .then(() => {
+                console.log("[gtkx] Registered with MCP server");
+                settle(onSuccess);
+            })
+                .catch((error) => {
+                console.error("[gtkx] Failed to register with MCP server:", error.message);
+                settle(onError, error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+        this.socket.on("data", (data) => this.handleData(data));
+        this.socket.on("close", () => {
+            if (this.hasConnected) {
+                console.log("[gtkx] Disconnected from MCP server");
+                this.hasConnected = false;
+            }
+            this.socket = null;
+            this.rejectPendingRequests(new Error("Connection closed"));
+            this.scheduleReconnect();
+        });
+        this.socket.on("error", (error) => {
+            const code = error.code;
+            const isDisconnectError = code === "ENOENT" || code === "ECONNREFUSED" || code === "EPIPE" || code === "ECONNRESET";
+            if (isDisconnectError) {
+                this.scheduleReconnect();
+            }
+            else {
+                console.error("[gtkx] Socket error:", error.message);
+            }
+            settle(onError, error);
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || this.isStopping)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.attemptConnect();
+        }, RECONNECT_DELAY_MS);
+    }
+    disconnect() {
+        this.isStopping = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.rejectPendingRequests(new Error("Client disconnected"));
+        if (this.socket) {
+            this.send({ id: crypto.randomUUID(), method: "app.unregister" });
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.hasConnected = false;
+    }
+    rejectPendingRequests(error) {
+        for (const pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+    async register() {
+        await this.sendRequest("app.register", {
+            appId: this.appId,
+            pid: process.pid,
+        });
+    }
+    send(message) {
+        if (!this.socket || !this.socket.writable)
+            return;
+        this.socket.write(`${JSON.stringify(message)}\n`);
+    }
+    sendRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this.socket.writable) {
+                reject(new Error("Socket not connected"));
+                return;
+            }
+            const id = crypto.randomUUID();
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timed out: ${method}`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timeout });
+            this.send({ id, method, params });
+        });
+    }
+    handleData(data) {
+        this.buffer += data.toString();
+        let newlineIndex = this.buffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.buffer.slice(0, newlineIndex);
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            if (line.trim()) {
+                this.processMessage(line);
+            }
+            newlineIndex = this.buffer.indexOf("\n");
+        }
+    }
+    processMessage(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            console.warn("[gtkx] Received invalid JSON from MCP server");
+            return;
+        }
+        const responseResult = IpcResponseSchema.safeParse(parsed);
+        if (responseResult.success) {
+            const response = responseResult.data;
+            const pending = this.pendingRequests.get(response.id);
+            if (pending) {
+                clearTimeout(pending.timeout);
+                this.pendingRequests.delete(response.id);
+                if (response.error) {
+                    pending.reject(new Error(response.error.message));
+                }
+                else {
+                    pending.resolve(response.result);
+                }
+                return;
+            }
+        }
+        const requestResult = IpcRequestSchema.safeParse(parsed);
+        if (!requestResult.success) {
+            return;
+        }
+        this.handleRequest(requestResult.data).catch((error) => {
+            console.error("[gtkx] Error handling request:", error);
+        });
+    }
+    async handleRequest(request) {
+        const { id, method, params } = request;
+        try {
+            const result = await this.executeMethod(method, params);
+            this.send({ id, result });
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                this.send({ id, error: error.toIpcError() });
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                this.send({
+                    id,
+                    error: {
+                        code: McpErrorCode.INTERNAL_ERROR,
+                        message,
+                    },
+                });
+            }
+        }
+    }
+    async executeMethod(method, params) {
+        const app = getApplication();
+        if (!app) {
+            throw new Error("Application not initialized");
+        }
+        refreshWidgetRegistry();
+        switch (method) {
+            case "widget.getTree": {
+                const testing = await loadTestingModule();
+                return { tree: testing.prettyWidget(app, { includeIds: true, highlight: false }) };
+            }
+            case "widget.query": {
+                const testing = await loadTestingModule();
+                const p = params;
+                let widgets = [];
+                switch (p.queryType) {
+                    case "role":
+                        widgets = await testing.findAllByRole(app, p.value, p.options);
+                        break;
+                    case "text":
+                        widgets = await testing.findAllByText(app, String(p.value), p.options);
+                        break;
+                    case "testId":
+                        widgets = await testing.findAllByTestId(app, String(p.value), p.options);
+                        break;
+                    case "labelText":
+                        widgets = await testing.findAllByLabelText(app, String(p.value), p.options);
+                        break;
+                    default:
+                        throw new Error(`Unknown query type: ${p.queryType}`);
+                }
+                return { widgets: widgets.map((w) => serializeWidget(w)) };
+            }
+            case "widget.getProps": {
+                const p = params;
+                const widget = getWidgetById(p.widgetId);
+                if (!widget) {
+                    throw widgetNotFoundError(p.widgetId);
+                }
+                return serializeWidget(widget);
+            }
+            case "widget.click": {
+                const testing = await loadTestingModule();
+                const p = params;
+                const widget = getWidgetById(p.widgetId);
+                if (!widget) {
+                    throw widgetNotFoundError(p.widgetId);
+                }
+                await testing.userEvent.click(widget);
+                return { success: true };
+            }
+            case "widget.type": {
+                const testing = await loadTestingModule();
+                const p = params;
+                const widget = getWidgetById(p.widgetId);
+                if (!widget) {
+                    throw widgetNotFoundError(p.widgetId);
+                }
+                if (p.clear) {
+                    await testing.userEvent.clear(widget);
+                }
+                await testing.userEvent.type(widget, p.text);
+                return { success: true };
+            }
+            case "widget.fireEvent": {
+                const testing = await loadTestingModule();
+                const p = params;
+                const widget = getWidgetById(p.widgetId);
+                if (!widget) {
+                    throw widgetNotFoundError(p.widgetId);
+                }
+                const signalArgs = (p.args ?? []);
+                await testing.fireEvent(widget, p.signal, ...signalArgs);
+                return { success: true };
+            }
+            case "widget.screenshot": {
+                const testing = await loadTestingModule();
+                const p = params;
+                let targetWindow;
+                if (p.windowId) {
+                    const widget = getWidgetById(p.windowId);
+                    if (!widget) {
+                        throw widgetNotFoundError(p.windowId);
+                    }
+                    targetWindow = widget;
+                }
+                else {
+                    const windows = app.getWindows();
+                    if (windows.length === 0) {
+                        throw new Error("No windows available for screenshot");
+                    }
+                    targetWindow = windows[0];
+                }
+                const result = await testing.screenshot(targetWindow);
+                return { data: result.data, mimeType: result.mimeType };
+            }
+            default:
+                throw methodNotFoundError(method);
+        }
+    }
+}
+let globalClient = null;
+export const startMcpClient = async (appId) => {
+    if (globalClient) {
+        return globalClient;
+    }
+    globalClient = new McpClient({ appId });
+    await globalClient.connect().catch(() => { });
+    return globalClient;
+};
+export const stopMcpClient = () => {
+    if (globalClient) {
+        globalClient.disconnect();
+        globalClient = null;
+    }
+};

package/dist/refresh-runtime.d.ts

@@ -1,9 +1,36 @@
 import RefreshRuntime from "react-refresh/runtime";
 type ComponentType = (...args: unknown[]) => unknown;
+/**
+ * Creates registration functions for a module's React components.
+ *
+ * Used internally by the Vite plugin to register components
+ * for React Fast Refresh.
+ *
+ * @param moduleId - Unique identifier for the module
+ * @returns Registration functions for the module
+ * @internal
+ */
 export declare function createModuleRegistration(moduleId: string): {
     $RefreshReg$: (type: ComponentType, id: string) => void;
     $RefreshSig$: typeof RefreshRuntime.createSignatureFunctionForTransform;
 };
+/**
+ * Checks if a module's exports form a React Refresh boundary.
+ *
+ * A module is a refresh boundary if all its exports are React components,
+ * allowing for fast refresh without full page reload.
+ *
+ * @param moduleExports - The module's exports object
+ * @returns `true` if the module can be fast-refreshed
+ * @internal
+ */
 export declare function isReactRefreshBoundary(moduleExports: Record<string, unknown>): boolean;
+/**
+ * Triggers React Fast Refresh to re-render components.
+ *
+ * Called after module updates when all exports are React components.
+ *
+ * @internal
+ */
 export declare function performRefresh(): void;
 export {};

package/dist/refresh-runtime.js

@@ -2,6 +2,16 @@ import RefreshRuntime from "react-refresh/runtime";
 RefreshRuntime.injectIntoGlobalHook(globalThis);
 globalThis.$RefreshReg$ = () => { };
 globalThis.$RefreshSig$ = () => (type) => type;
+/**
+ * Creates registration functions for a module's React components.
+ *
+ * Used internally by the Vite plugin to register components
+ * for React Fast Refresh.
+ *
+ * @param moduleId - Unique identifier for the module
+ * @returns Registration functions for the module
+ * @internal
+ */
 export function createModuleRegistration(moduleId) {
     return {
         $RefreshReg$: (type, id) => {
@@ -24,6 +34,16 @@ function isLikelyComponentType(value) {
     }
     return false;
 }
+/**
+ * Checks if a module's exports form a React Refresh boundary.
+ *
+ * A module is a refresh boundary if all its exports are React components,
+ * allowing for fast refresh without full page reload.
+ *
+ * @param moduleExports - The module's exports object
+ * @returns `true` if the module can be fast-refreshed
+ * @internal
+ */
 export function isReactRefreshBoundary(moduleExports) {
     if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
         return true;
@@ -39,6 +59,13 @@ export function isReactRefreshBoundary(moduleExports) {
     }
     return Object.keys(moduleExports).filter((k) => k !== "__esModule").length > 0;
 }
+/**
+ * Triggers React Fast Refresh to re-render components.
+ *
+ * Called after module updates when all exports are React components.
+ *
+ * @internal
+ */
 export function performRefresh() {
     RefreshRuntime.performReactRefresh();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/cli",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "CLI for GTKX - create and develop GTK4 React applications",
   "keywords": [
     "gtkx",
@@ -58,16 +58,24 @@
     "ejs": "^3.1.10",
     "react-refresh": "^0.18.0",
     "vite": "^7.3.0",
-    "@gtkx/ffi": "0.11.1",
-    "@gtkx/react": "0.11.1"
+    "@gtkx/mcp": "0.12.0",
+    "@gtkx/ffi": "0.12.0",
+    "@gtkx/react": "0.12.0"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/react-refresh": "^0.14.7",
-    "memfs": "^4.51.1"
+    "memfs": "^4.51.1",
+    "@gtkx/testing": "0.12.0"
   },
   "peerDependencies": {
-    "react": "^19"
+    "react": "^19",
+    "@gtkx/testing": "0.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@gtkx/testing": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -b",