@gtkx/cli 0.21.0 → 1.0.0-rc.2

package/src/mcp/client.ts

@@ -0,0 +1,235 @@
+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";
+
+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 = 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));
+        },
+    };
+};
+
+class McpClient {
+    private socket: net.Socket | null = null;
+    private connection: ProtocolConnection | null = null;
+    private socketPath: string;
+    private applicationId: string;
+    private reconnectTimer: NodeJS.Timeout | null = null;
+    private hasConnected = false;
+    private isStopping = false;
+    private pendingConnectReject: ((error: Error) => void) | null = null;
+    private registry = new WidgetRegistry();
+
+    constructor(options: McpClientOptions) {
+        this.socketPath = options.socketPath ?? DEFAULT_SOCKET_PATH;
+        this.applicationId = options.applicationId;
+    }
+
+    private handleClose(): void {
+        if (this.hasConnected) {
+            info("Disconnected from MCP server");
+            this.hasConnected = false;
+        }
+
+        this.socket = null;
+        this.connection = null;
+        this.scheduleReconnect();
+    }
+
+    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);
+        }
+    }
+
+    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));
+        }
+    }
+
+    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;
+            void this.registerWithServer(settle);
+        });
+
+        const connection = ProtocolConnection.fromSocket(socket, {
+            onClose: () => {
+                this.handleClose();
+            },
+            onError: (socketError) => {
+                this.handleSocketError(socketError);
+                settle.fail(socketError);
+            },
+        });
+
+        connection.on("request", (request) => {
+            void this.handleRequest(request);
+        });
+
+        connection.on("invalid", ({ error: parseError }) => {
+            warn(`Received invalid JSON from MCP server: ${parseError.message}`);
+        });
+
+        this.socket = socket;
+        this.connection = connection;
+    }
+
+    private scheduleReconnect(): void {
+        if (this.reconnectTimer || this.isStopping) {
+            return;
+        }
+
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.attemptConnect();
+        }, RECONNECT_DELAY_MS);
+    }
+
+    private register(): Promise<unknown> {
+        if (!this.connection) {
+            return Promise.reject(new Error("Connection not initialized"));
+        }
+
+        return this.connection.send(
+            "app.register",
+            {
+                applicationId: this.applicationId,
+                pid: process.pid,
+                projectRoot: process.cwd(),
+            },
+            REGISTER_TIMEOUT_MS,
+        );
+    }
+
+    private async respondToRequest(request: Request): Promise<void> {
+        const { id, method, params } = request;
+        const connection = this.connection;
+
+        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 (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

@@ -0,0 +1,213 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import {
+    invalidRequestError,
+    methodNotFoundError,
+    type ParamsSchema,
+    type ServerInitiatedMethod,
+    type ServerRequestParams,
+    ServerRequestParamsSchemas,
+    widgetNotFoundError,
+} from "@gtkx/mcp/internal";
+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";
+
+type HandlerContext = {
+    app: Gtk.Application;
+    registry: WidgetRegistry;
+};
+
+type ValidatedHandler = (ctx: HandlerContext, params: unknown) => Promise<unknown>;
+type WidgetTarget = { testing: TestingModule; widget: Gtk.Widget };
+
+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 {
+    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 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> {
+    const testing = await loadTestingModule();
+    let widgets: Gtk.Widget[] = [];
+
+    switch (params.by) {
+        case "role": {
+            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 matchesOrEmpty(() => testing.findAllByText(app, String(params.value), params.options));
+            break;
+        }
+        case "name": {
+            widgets = await matchesOrEmpty(() => testing.findAllByName(app, String(params.value), params.options));
+            break;
+        }
+        case "labelText": {
+            widgets = await matchesOrEmpty(() => testing.findAllByLabelText(app, String(params.value), params.options));
+            break;
+        }
+    }
+
+    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;
+};
+
+async function handleScreenshot(
+    { registry }: HandlerContext,
+    params: ServerRequestParams<"widget.screenshot">,
+): 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 isServerInitiatedMethod = (method: string): method is ServerInitiatedMethod =>
+    Object.hasOwn(ServerRequestParamsSchemas, method);
+
+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

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

package/src/mcp/serialize-widget.ts

@@ -0,0 +1,41 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { SerializedWidget } from "@gtkx/mcp/internal";
+
+type WidgetIdResolver = (widget: Gtk.Widget) => string;
+
+type WidgetFormatting = {
+    formatRole(role: Gtk.AccessibleRole): string;
+    getWidgetNodeText(widget: Gtk.Widget): string | null;
+};
+
+const serializeWidget = (
+    widget: Gtk.Widget,
+    resolveId: WidgetIdResolver,
+    testing: WidgetFormatting,
+    maxDepth = Infinity,
+): SerializedWidget => {
+    const children: SerializedWidget[] = [];
+
+    if (maxDepth > 0) {
+        let child = widget.getFirstChild();
+
+        while (child) {
+            children.push(serializeWidget(child, resolveId, testing, maxDepth - 1));
+            child = child.getNextSibling();
+        }
+    }
+
+    return {
+        id: resolveId(widget),
+        type: widget.constructor.name,
+        role: testing.formatRole(widget.getAccessibleRole()),
+        name: widget.getName() || null,
+        text: testing.getWidgetNodeText(widget),
+        sensitive: widget.getSensitive(),
+        visible: widget.getVisible(),
+        cssClasses: widget.getCssClasses(),
+        children,
+    };
+};
+
+export { serializeWidget, type WidgetFormatting };

package/src/mcp/testing-loader.ts

@@ -0,0 +1,73 @@
+type TestingModule = typeof import("@gtkx/testing");
+type TestingModuleLoader = () => Promise<TestingModule>;
+
+type TestingModuleCache = {
+    setLoader: (next: TestingModuleLoader | null) => void;
+    load: () => Promise<TestingModule>;
+};
+
+type TestingModuleState = {
+    loader: TestingModuleLoader;
+    testingModule: TestingModule | null;
+    testingLoadError: Error | null;
+};
+
+const { setLoader: setTestingModuleLoader, load: loadTestingModule } = createTestingModuleCache();
+
+function defaultLoader(): Promise<TestingModule> {
+    return import("@gtkx/testing");
+}
+
+function missingTestingPackageError(cause: unknown): Error {
+    return new Error(
+        "@gtkx/testing is not installed, install it to enable MCP widget interactions: " +
+        `pnpm add -D @gtkx/testing (import failed: ${String(cause)})`,
+        { cause },
+    );
+}
+
+function replaceLoader(state: TestingModuleState, next: TestingModuleLoader | null): void {
+    state.loader = next ?? defaultLoader;
+    state.testingModule = null;
+    state.testingLoadError = null;
+}
+
+async function importTestingModule(state: TestingModuleState): Promise<TestingModule> {
+    try {
+        state.testingModule = await state.loader();
+
+        return state.testingModule;
+    } catch (error) {
+        state.testingLoadError = missingTestingPackageError(error);
+        throw state.testingLoadError;
+    }
+}
+
+function loadCachedTestingModule(state: TestingModuleState): Promise<TestingModule> {
+    if (state.testingModule) {
+        return Promise.resolve(state.testingModule);
+    }
+
+    if (state.testingLoadError) {
+        return Promise.reject(state.testingLoadError);
+    }
+
+    return importTestingModule(state);
+}
+
+function createTestingModuleCache(): TestingModuleCache {
+    const state: TestingModuleState = {
+        loader: defaultLoader,
+        testingModule: null,
+        testingLoadError: null,
+    };
+
+    return {
+        setLoader: (next: TestingModuleLoader | null): void => {
+            replaceLoader(state, next);
+        },
+        load: (): Promise<TestingModule> => loadCachedTestingModule(state),
+    };
+}
+
+export { setTestingModuleLoader, loadTestingModule, type TestingModule, type TestingModuleLoader };

package/src/mcp/widget-registry.ts

@@ -0,0 +1,49 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+class WidgetRegistry {
+    private idByWidget: WeakMap<Gtk.Widget, string> = new WeakMap();
+    private nextId = 0;
+    private widgetById: Map<string, Gtk.Widget> = new Map();
+    private toplevelWindows: Gtk.Window[] = [];
+
+    refresh(): void {
+        this.widgetById.clear();
+        this.toplevelWindows = Gtk.Window.listToplevels() as Gtk.Window[];
+
+        for (const window of this.toplevelWindows) {
+            this.register(window);
+        }
+    }
+
+    toplevels(): Gtk.Window[] {
+        return this.toplevelWindows;
+    }
+
+    register(widget: Gtk.Widget): void {
+        const id = this.getOrCreateId(widget);
+        this.widgetById.set(id, widget);
+        let child = widget.getFirstChild();
+
+        while (child) {
+            this.register(child);
+            child = child.getNextSibling();
+        }
+    }
+
+    getOrCreateId(widget: Gtk.Widget): string {
+        let id = this.idByWidget.get(widget);
+
+        if (!id) {
+            id = String(this.nextId++);
+            this.idByWidget.set(widget, id);
+        }
+
+        return id;
+    }
+
+    get(id: string): Gtk.Widget | undefined {
+        return this.widgetById.get(id);
+    }
+}
+
+export { WidgetRegistry };

package/src/refresh-globals.ts

@@ -0,0 +1,10 @@
+import RefreshRuntime from "react-refresh/runtime";
+
+const identity = (type: unknown): unknown => type;
+
+RefreshRuntime.injectIntoGlobalHook(globalThis);
+
+Object.assign(globalThis, {
+    $RefreshReg$: (): void => undefined,
+    $RefreshSig$: () => identity,
+});