@gtkx/cli 1.0.0-rc.1 → 1.0.0-rc.3

package/src/mcp/client.ts

@@ -1,20 +1,58 @@
-import * as net from "node:net";
 import * as Gio from "@gtkx/gi/gio";
 import * as Gtk from "@gtkx/gi/gtk";
 import { DEFAULT_SOCKET_PATH, ErrorCode, ProtocolConnection, ProtocolError, type Request } from "@gtkx/mcp/internal";
 import { error, errorMessage, info, normalizeError, warn } from "@gtkx/utils";
+import * as net from "node:net";
 import { dispatch } from "./handlers.js";
 import { WidgetRegistry } from "./widget-registry.js";
 
-export type McpClientOptions = {
+type McpClientOptions = {
     socketPath?: string;
     applicationId: string;
 };
 
+type ConnectCallbacks = {
+    onSuccess?: (() => void) | undefined;
+    onError?: ((error: Error) => void) | undefined;
+};
+
+type ConnectSettler = {
+    succeed: () => void;
+    fail: (error: Error) => void;
+};
+
 const RECONNECT_DELAY_MS = 2000;
-const REGISTER_TIMEOUT_MS = 30000;
+const REGISTER_TIMEOUT_MS = 30_000;
+const DISCONNECT_ERROR_CODES: Set<string> = new Set(["ENOENT", "ECONNREFUSED", "EPIPE", "ECONNRESET"]);
+
+const toResponseError = (error: unknown): { code: number; message: string; data?: unknown } =>
+    error instanceof ProtocolError
+        ? error.toErrorObject()
+        : { code: ErrorCode.INTERNAL_ERROR, message: errorMessage(error) };
+
+const connectSettler = (callbacks: ConnectCallbacks): ConnectSettler => {
+    let isSettled = false;
+
+    const settle = (notify: () => void): void => {
+        if (isSettled) {
+            return;
+        }
+
+        isSettled = true;
+        notify();
+    };
+
+    return {
+        succeed: () => {
+            settle(() => callbacks.onSuccess?.());
+        },
+        fail: (failure) => {
+            settle(() => callbacks.onError?.(failure));
+        },
+    };
+};
 
-export class McpClient {
+class McpClient {
     private socket: net.Socket | null = null;
     private connection: ProtocolConnection | null = null;
     private socketPath: string;
@@ -30,92 +68,61 @@ export class McpClient {
         this.applicationId = options.applicationId;
     }
 
-    async connect(): Promise<void> {
-        return new Promise<void>((resolve, reject) => {
-            this.pendingConnectReject = reject;
-            this.attemptConnect(
-                () => {
-                    this.pendingConnectReject = null;
-                    resolve();
-                },
-                (error) => {
-                    this.pendingConnectReject = null;
-                    reject(error);
-                },
-            );
-        });
+    private handleClose(): void {
+        if (this.hasConnected) {
+            info("Disconnected from MCP server");
+            this.hasConnected = false;
+        }
+
+        this.socket = null;
+        this.connection = null;
+        this.scheduleReconnect();
     }
 
-    disconnect(): void {
-        this.isStopping = true;
-        if (this.pendingConnectReject) {
-            this.pendingConnectReject(new Error("Client disconnected before connection registered"));
-            this.pendingConnectReject = null;
-        }
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
-        }
-        this.connection?.rejectPending(new Error("Client disconnected"));
-        if (this.socket) {
-            this.connection?.write({ id: crypto.randomUUID(), method: "app.unregister" });
-            this.socket.destroy();
-            this.socket = null;
+    private handleSocketError(socketError: Error): void {
+        const code = (socketError as NodeJS.ErrnoException).code;
+
+        if (code !== undefined && DISCONNECT_ERROR_CODES.has(code)) {
+            this.scheduleReconnect();
+        } else {
+            error("Socket error:", socketError.message);
         }
-        this.connection = null;
-        this.hasConnected = false;
     }
 
-    private attemptConnect(onSuccess?: () => void, onError?: (error: Error) => void): void {
-        let settled = false;
+    private async registerWithServer(settle: ConnectSettler): Promise<void> {
+        try {
+            await this.register();
+            info("Registered with MCP server");
+            settle.succeed();
+        } catch (registerError) {
+            error("Failed to register with MCP server:", errorMessage(registerError));
+            settle.fail(normalizeError(registerError));
+        }
+    }
 
-        const settle = <T extends unknown[]>(callback: ((...args: T) => void) | undefined, ...args: T) => {
-            if (settled) return;
-            settled = true;
-            callback?.(...args);
-        };
+    private attemptConnect(callbacks: ConnectCallbacks = {}): void {
+        const settle = connectSettler(callbacks);
 
         const socket = net.createConnection(this.socketPath, () => {
             info(`Connected to MCP server at ${this.socketPath}`);
             this.hasConnected = true;
-            this.register()
-                .then(() => {
-                    info("Registered with MCP server");
-                    settle(onSuccess);
-                })
-                .catch((cause) => {
-                    error("Failed to register with MCP server:", cause.message);
-                    settle(onError, normalizeError(cause));
-                });
+            void this.registerWithServer(settle);
         });
 
         const connection = ProtocolConnection.fromSocket(socket, {
             onClose: () => {
-                if (this.hasConnected) {
-                    info("Disconnected from MCP server");
-                    this.hasConnected = false;
-                }
-                this.socket = null;
-                this.connection = null;
-                this.scheduleReconnect();
+                this.handleClose();
             },
             onError: (socketError) => {
-                const code = (socketError as NodeJS.ErrnoException).code;
-                const isDisconnectError =
-                    code === "ENOENT" || code === "ECONNREFUSED" || code === "EPIPE" || code === "ECONNRESET";
-                if (isDisconnectError) {
-                    this.scheduleReconnect();
-                } else {
-                    error("Socket error:", socketError.message);
-                }
-                settle(onError, socketError);
+                this.handleSocketError(socketError);
+                settle.fail(socketError);
             },
         });
+
         connection.on("request", (request) => {
-            this.handleRequest(request).catch((cause) => {
-                error("Error handling request:", cause);
-            });
+            void this.handleRequest(request);
         });
+
         connection.on("invalid", ({ error: parseError }) => {
             warn(`Received invalid JSON from MCP server: ${parseError.message}`);
         });
@@ -125,7 +132,10 @@ export class McpClient {
     }
 
     private scheduleReconnect(): void {
-        if (this.reconnectTimer || this.isStopping) return;
+        if (this.reconnectTimer || this.isStopping) {
+            return;
+        }
+
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             this.attemptConnect();
@@ -136,6 +146,7 @@ export class McpClient {
         if (!this.connection) {
             return Promise.reject(new Error("Connection not initialized"));
         }
+
         return this.connection.send(
             "app.register",
             {
@@ -147,31 +158,78 @@ export class McpClient {
         );
     }
 
-    private async handleRequest(request: Request): Promise<void> {
+    private async respondToRequest(request: Request): Promise<void> {
         const { id, method, params } = request;
         const connection = this.connection;
-        if (!connection) return;
+
+        if (!connection) {
+            return;
+        }
 
         try {
             const defaultApp = Gio.Application.getDefault();
+
             if (!(defaultApp instanceof Gtk.Application)) {
                 throw new TypeError("Application not initialized");
             }
+
             this.registry.refresh();
             const result = await dispatch(method, params, { app: defaultApp, registry: this.registry });
             connection.write({ id, result });
-        } catch (error) {
-            if (error instanceof ProtocolError) {
-                connection.write({ id, error: error.toErrorObject() });
-            } else {
-                connection.write({
-                    id,
-                    error: {
-                        code: ErrorCode.INTERNAL_ERROR,
-                        message: errorMessage(error),
-                    },
-                });
-            }
+        } catch (dispatchError) {
+            connection.write({ id, error: toResponseError(dispatchError) });
         }
     }
+
+    private async handleRequest(request: Request): Promise<void> {
+        try {
+            await this.respondToRequest(request);
+        } catch (requestError) {
+            error("Error handling request:", requestError);
+        }
+    }
+
+    async connect(): Promise<void> {
+        return new Promise<void>((resolve, reject) => {
+            this.pendingConnectReject = reject;
+
+            this.attemptConnect({
+                onSuccess: () => {
+                    this.pendingConnectReject = null;
+                    resolve();
+                },
+                onError: (connectError) => {
+                    this.pendingConnectReject = null;
+                    reject(connectError);
+                },
+            });
+        });
+    }
+
+    disconnect(): void {
+        this.isStopping = true;
+
+        if (this.pendingConnectReject) {
+            this.pendingConnectReject(new Error("Client disconnected before connection registered"));
+            this.pendingConnectReject = null;
+        }
+
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+
+        this.connection?.rejectPending(new Error("Client disconnected"));
+
+        if (this.socket) {
+            this.connection?.write({ id: crypto.randomUUID(), method: "app.unregister" });
+            this.socket.destroy();
+            this.socket = null;
+        }
+
+        this.connection = null;
+        this.hasConnected = false;
+    }
 }
+
+export { McpClient, type McpClientOptions };

package/src/mcp/handlers.ts

@@ -1,5 +1,3 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
 import * as Gtk from "@gtkx/gi/gtk";
 import {
     invalidRequestError,
@@ -10,147 +8,206 @@ import {
     ServerRequestParamsSchemas,
     widgetNotFoundError,
 } from "@gtkx/mcp/internal";
-import { serializeWidget } from "./serialize-widget.js";
-import { loadTestingModule } from "./testing-loader.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import type { WidgetRegistry } from "./widget-registry.js";
+import { serializeWidget } from "./serialize-widget.js";
+import { loadTestingModule, type TestingModule } from "./testing-loader.js";
 
-export type HandlerContext = {
+type HandlerContext = {
     app: Gtk.Application;
     registry: WidgetRegistry;
 };
 
 type ValidatedHandler = (ctx: HandlerContext, params: unknown) => Promise<unknown>;
+type WidgetTarget = { testing: TestingModule; widget: Gtk.Widget };
 
-const validated = <Params>(
+const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
+    "app.getWindows": validated(ServerRequestParamsSchemas["app.getWindows"], ({ registry }) =>
+        Promise.resolve({
+            windows: registry.toplevels().map((window) => ({
+                id: registry.getOrCreateId(window),
+                title: window.getTitle(),
+            })),
+        })),
+    "widget.getTree": validated(ServerRequestParamsSchemas["widget.getTree"], async ({ app, registry }, params) => {
+        const testing = await loadTestingModule();
+        const container = params.rootId === undefined ? app : requireWidget(registry, params.rootId);
+
+        return {
+            tree: testing.prettyWidget(container, {
+                getId: (w) => registry.getOrCreateId(w),
+                highlight: false,
+                ...((params.maxDepth !== undefined) && { maxDepth: params.maxDepth }),
+            }),
+        };
+    }),
+    "widget.query": validated(ServerRequestParamsSchemas["widget.query"], handleQuery),
+    "widget.getProps": validated(ServerRequestParamsSchemas["widget.getProps"], async ({ registry }, params) => {
+        const { testing, widget } = await widgetTarget(registry, params.widgetId);
+
+        return serializeWidget(widget, (target) => registry.getOrCreateId(target), testing);
+    }),
+    "widget.click": validated(ServerRequestParamsSchemas["widget.click"], async ({ registry }, params) => {
+        const { testing, widget } = await widgetTarget(registry, params.widgetId);
+        await testing.userEvent.click(widget);
+
+        return { success: true };
+    }),
+    "widget.type": validated(ServerRequestParamsSchemas["widget.type"], async ({ registry }, params) => {
+        const { testing, widget } = await widgetTarget(registry, params.widgetId);
+
+        if (params.clear) {
+            await testing.userEvent.clear(widget);
+        }
+
+        await testing.userEvent.type(widget, params.text);
+
+        return { success: true };
+    }),
+    "widget.fireEvent": validated(ServerRequestParamsSchemas["widget.fireEvent"], async ({ registry }, params) => {
+        const { testing, widget } = await widgetTarget(registry, params.widgetId);
+        const signalArgs = (params.args ?? []).map((arg) => extractSignalArg(arg));
+        await testing.fireEvent(widget, params.signal, ...signalArgs);
+
+        return { success: true };
+    }),
+    "widget.screenshot": validated(ServerRequestParamsSchemas["widget.screenshot"], handleScreenshot),
+};
+
+function validated<Params>(
     schema: ParamsSchema<Params>,
     handler: (ctx: HandlerContext, params: Params) => Promise<unknown>,
-): ValidatedHandler => {
+): ValidatedHandler {
     return (ctx, params) => {
         const parsed = schema.safeParse(params ?? {});
+
         if (!parsed.success) {
             throw invalidRequestError(parsed.error.message);
         }
+
         return handler(ctx, parsed.data);
     };
-};
+}
+
+const widgetTarget = async (registry: WidgetRegistry, widgetId: string | undefined): Promise<WidgetTarget> => ({
+    testing: await loadTestingModule(),
+    widget: requireWidget(registry, widgetId),
+});
 
 const requireWidget = (registry: WidgetRegistry, widgetId: string | undefined): Gtk.Widget => {
     if (widgetId === undefined) {
         throw widgetNotFoundError("undefined");
     }
+
     const widget = registry.get(widgetId);
+
     if (!widget) {
         throw widgetNotFoundError(widgetId);
     }
+
     return widget;
 };
 
 const extractSignalArg = (arg: unknown): unknown => {
     const isTypedArg = typeof arg === "object" && arg !== null && "type" in arg && "value" in arg;
+
     return isTypedArg ? (arg as { value: unknown }).value : arg;
 };
 
-const handleQuery = async (
+const resolveRole = (value: string | number): Gtk.AccessibleRole | undefined => {
+    if (typeof value === "number") {
+        return value;
+    }
+
+    const resolved = Gtk.AccessibleRole[value.toUpperCase() as keyof typeof Gtk.AccessibleRole];
+
+    return typeof resolved === "number" ? resolved : undefined;
+};
+
+const matchesOrEmpty = async (find: () => Promise<Gtk.Widget[]>): Promise<Gtk.Widget[]> => {
+    try {
+        return await find();
+    } catch {
+        return [];
+    }
+};
+
+async function handleQuery(
     { app, registry }: HandlerContext,
     params: ServerRequestParams<"widget.query">,
-): Promise<unknown> => {
+): Promise<unknown> {
     const testing = await loadTestingModule();
     let widgets: Gtk.Widget[] = [];
 
     switch (params.by) {
         case "role": {
-            const roleValue =
-                typeof params.value === "string"
-                    ? Gtk.AccessibleRole[params.value as keyof typeof Gtk.AccessibleRole]
-                    : params.value;
-            widgets = await testing.findAllByRole(app, roleValue as Gtk.AccessibleRole, params.options);
+            const roleValue = resolveRole(params.value);
+
+            if (roleValue === undefined) {
+                throw invalidRequestError(
+                    `Unknown accessible role "${String(params.value)}"; use the lowercase role shown in the ` +
+                    "widget tree, e.g. \"button\", \"list\", \"list_item\", or \"checkbox\".",
+                );
+            }
+
+            widgets = await matchesOrEmpty(() => testing.findAllByRole(app, roleValue, params.options));
             break;
         }
-        case "text":
-            widgets = await testing.findAllByText(app, String(params.value), params.options);
+        case "text": {
+            widgets = await matchesOrEmpty(() => testing.findAllByText(app, String(params.value), params.options));
             break;
-        case "name":
-            widgets = await testing.findAllByName(app, String(params.value), params.options);
+        }
+        case "name": {
+            widgets = await matchesOrEmpty(() => testing.findAllByName(app, String(params.value), params.options));
             break;
-        case "labelText":
-            widgets = await testing.findAllByLabelText(app, String(params.value), params.options);
+        }
+        case "labelText": {
+            widgets = await matchesOrEmpty(() => testing.findAllByLabelText(app, String(params.value), params.options));
             break;
+        }
     }
 
-    return { widgets: widgets.map((w) => serializeWidget(w, (widget) => registry.idFor(widget), testing)) };
-};
+    return { widgets: widgets.map((w) => serializeWidget(w, (widget) => registry.getOrCreateId(widget), testing, 0)) };
+}
 
 const defaultScreenshotTarget = (registry: WidgetRegistry): Gtk.Widget => {
     const [toplevel] = registry.toplevels();
+
     if (!toplevel) {
         throw new Error("No windows available for screenshot");
     }
+
     return toplevel;
 };
 
-const handleScreenshot = async (
+async function handleScreenshot(
     { registry }: HandlerContext,
     params: ServerRequestParams<"widget.screenshot">,
-): Promise<unknown> => {
+): Promise<unknown> {
     const testing = await loadTestingModule();
     const target = params.windowId ? requireWidget(registry, params.windowId) : defaultScreenshotTarget(registry);
     const result = await testing.screenshot(target);
+
     if (params.path) {
         mkdirSync(dirname(params.path), { recursive: true });
         writeFileSync(params.path, Buffer.from(result.data, "base64"));
+
         return { data: result.data, mimeType: result.mimeType, savedPath: params.path };
     }
-    return { data: result.data, mimeType: result.mimeType };
-};
 
-const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
-    "app.getWindows": validated(ServerRequestParamsSchemas["app.getWindows"], async ({ registry }) => ({
-        windows: registry.toplevels().map((window) => ({
-            id: registry.idFor(window),
-            title: window.getTitle(),
-        })),
-    })),
-    "widget.getTree": validated(ServerRequestParamsSchemas["widget.getTree"], async ({ app, registry }) => {
-        const testing = await loadTestingModule();
-        return { tree: testing.prettyWidget(app, { getId: (w) => registry.idFor(w), highlight: false }) };
-    }),
-    "widget.query": validated(ServerRequestParamsSchemas["widget.query"], handleQuery),
-    "widget.getProps": validated(ServerRequestParamsSchemas["widget.getProps"], async ({ registry }, params) => {
-        const testing = await loadTestingModule();
-        const widget = requireWidget(registry, params.widgetId);
-        return serializeWidget(widget, (target) => registry.idFor(target), testing);
-    }),
-    "widget.click": validated(ServerRequestParamsSchemas["widget.click"], async ({ registry }, params) => {
-        const testing = await loadTestingModule();
-        const widget = requireWidget(registry, params.widgetId);
-        await testing.userEvent.click(widget);
-        return { success: true };
-    }),
-    "widget.type": validated(ServerRequestParamsSchemas["widget.type"], async ({ registry }, params) => {
-        const testing = await loadTestingModule();
-        const widget = requireWidget(registry, params.widgetId);
-        if (params.clear) {
-            await testing.userEvent.clear(widget);
-        }
-        await testing.userEvent.type(widget, params.text);
-        return { success: true };
-    }),
-    "widget.fireEvent": validated(ServerRequestParamsSchemas["widget.fireEvent"], async ({ registry }, params) => {
-        const testing = await loadTestingModule();
-        const widget = requireWidget(registry, params.widgetId);
-        const signalArgs = (params.args ?? []).map(extractSignalArg);
-        await testing.fireEvent(widget, params.signal, ...signalArgs);
-        return { success: true };
-    }),
-    "widget.screenshot": validated(ServerRequestParamsSchemas["widget.screenshot"], handleScreenshot),
-};
+    return { data: result.data, mimeType: result.mimeType };
+}
 
 const isServerInitiatedMethod = (method: string): method is ServerInitiatedMethod =>
     Object.hasOwn(ServerRequestParamsSchemas, method);
 
-export const dispatch = async (method: string, params: unknown, ctx: HandlerContext): Promise<unknown> => {
+const dispatch = async (method: string, params: unknown, ctx: HandlerContext): Promise<unknown> => {
     if (!isServerInitiatedMethod(method)) {
         throw methodNotFoundError(method);
     }
+
     return HANDLERS[method](ctx, params);
 };
+
+export { dispatch, type HandlerContext };

package/src/mcp/index.ts

@@ -1,22 +1,46 @@
 import { McpClient } from "./client.js";
 
-let globalClient: McpClient | null = null;
+type McpClientController = {
+    start: (applicationId: string) => Promise<McpClient>;
+    stop: () => void;
+};
+
+const { start: startMcpClient, stop: stopMcpClient } = createMcpClientController();
 
-export const startMcpClient = async (applicationId: string): Promise<McpClient> => {
-    if (globalClient) {
-        return globalClient;
+async function connectQuietly(client: McpClient): Promise<boolean> {
+    try {
+        await client.connect();
+
+        return true;
+    } catch {
+        return false;
     }
+}
 
-    globalClient = new McpClient({ applicationId });
+function createMcpClientController(): McpClientController {
+    let current: McpClient | null = null;
 
-    await globalClient.connect().catch(() => {});
+    return {
+        start: async (applicationId: string): Promise<McpClient> => {
+            if (current) {
+                return current;
+            }
 
-    return globalClient;
-};
+            const client = new McpClient({ applicationId });
+            current = client;
+            await connectQuietly(client);
 
-export const stopMcpClient = (): void => {
-    if (globalClient) {
-        globalClient.disconnect();
-        globalClient = null;
-    }
-};
+            return client;
+        },
+        stop: (): void => {
+            if (!current) {
+                return;
+            }
+
+            current.disconnect();
+            current = null;
+        },
+    };
+}
+
+export { startMcpClient, stopMcpClient };