@gtkx/cli 0.20.0 → 1.0.0-rc.1

package/src/mcp/client.ts

@@ -0,0 +1,177 @@
+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 { dispatch } from "./handlers.js";
+import { WidgetRegistry } from "./widget-registry.js";
+
+export type McpClientOptions = {
+    socketPath?: string;
+    applicationId: string;
+};
+
+const RECONNECT_DELAY_MS = 2000;
+const REGISTER_TIMEOUT_MS = 30000;
+
+export 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;
+    }
+
+    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);
+                },
+            );
+        });
+    }
+
+    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;
+    }
+
+    private attemptConnect(onSuccess?: () => void, onError?: (error: Error) => void): void {
+        let settled = false;
+
+        const settle = <T extends unknown[]>(callback: ((...args: T) => void) | undefined, ...args: T) => {
+            if (settled) return;
+            settled = true;
+            callback?.(...args);
+        };
+
+        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));
+                });
+        });
+
+        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();
+            },
+            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);
+            },
+        });
+        connection.on("request", (request) => {
+            this.handleRequest(request).catch((cause) => {
+                error("Error handling request:", cause);
+            });
+        });
+        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 handleRequest(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 (error) {
+            if (error instanceof ProtocolError) {
+                connection.write({ id, error: error.toErrorObject() });
+            } else {
+                connection.write({
+                    id,
+                    error: {
+                        code: ErrorCode.INTERNAL_ERROR,
+                        message: errorMessage(error),
+                    },
+                });
+            }
+        }
+    }
+}

package/src/mcp/handlers.ts

@@ -0,0 +1,156 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import * as Gtk from "@gtkx/gi/gtk";
+import {
+    invalidRequestError,
+    methodNotFoundError,
+    type ParamsSchema,
+    type ServerInitiatedMethod,
+    type ServerRequestParams,
+    ServerRequestParamsSchemas,
+    widgetNotFoundError,
+} from "@gtkx/mcp/internal";
+import { serializeWidget } from "./serialize-widget.js";
+import { loadTestingModule } from "./testing-loader.js";
+import type { WidgetRegistry } from "./widget-registry.js";
+
+export type HandlerContext = {
+    app: Gtk.Application;
+    registry: WidgetRegistry;
+};
+
+type ValidatedHandler = (ctx: HandlerContext, params: unknown) => Promise<unknown>;
+
+const 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 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 (
+    { app, registry }: HandlerContext,
+    params: ServerRequestParams<"widget.query">,
+): 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);
+            break;
+        }
+        case "text":
+            widgets = await testing.findAllByText(app, String(params.value), params.options);
+            break;
+        case "name":
+            widgets = await testing.findAllByName(app, String(params.value), params.options);
+            break;
+        case "labelText":
+            widgets = await testing.findAllByLabelText(app, String(params.value), params.options);
+            break;
+    }
+
+    return { widgets: widgets.map((w) => serializeWidget(w, (widget) => registry.idFor(widget), testing)) };
+};
+
+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 (
+    { 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 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),
+};
+
+const isServerInitiatedMethod = (method: string): method is ServerInitiatedMethod =>
+    Object.hasOwn(ServerRequestParamsSchemas, method);
+
+export const dispatch = async (method: string, params: unknown, ctx: HandlerContext): Promise<unknown> => {
+    if (!isServerInitiatedMethod(method)) {
+        throw methodNotFoundError(method);
+    }
+    return HANDLERS[method](ctx, params);
+};

package/src/mcp/index.ts

@@ -0,0 +1,22 @@
+import { McpClient } from "./client.js";
+
+let globalClient: McpClient | null = null;
+
+export const startMcpClient = async (applicationId: string): Promise<McpClient> => {
+    if (globalClient) {
+        return globalClient;
+    }
+
+    globalClient = new McpClient({ applicationId });
+
+    await globalClient.connect().catch(() => {});
+
+    return globalClient;
+};
+
+export const stopMcpClient = (): void => {
+    if (globalClient) {
+        globalClient.disconnect();
+        globalClient = null;
+    }
+};

package/src/mcp/serialize-widget.ts

@@ -0,0 +1,34 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { SerializedWidget } from "@gtkx/mcp/internal";
+
+type WidgetIdResolver = (widget: Gtk.Widget) => string;
+
+export type WidgetFormatting = {
+    formatRole(role: Gtk.AccessibleRole): string;
+    getWidgetNodeText(widget: Gtk.Widget): string | null;
+};
+
+export const serializeWidget = (
+    widget: Gtk.Widget,
+    idFor: WidgetIdResolver,
+    testing: WidgetFormatting,
+): SerializedWidget => {
+    const children: SerializedWidget[] = [];
+    let child = widget.getFirstChild();
+    while (child) {
+        children.push(serializeWidget(child, idFor, testing));
+        child = child.getNextSibling();
+    }
+
+    return {
+        id: idFor(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,
+    };
+};

package/src/mcp/testing-loader.ts

@@ -0,0 +1,32 @@
+type TestingModule = typeof import("@gtkx/testing");
+
+export type TestingModuleLoader = () => Promise<TestingModule>;
+
+const defaultLoader: TestingModuleLoader = () => import("@gtkx/testing");
+
+let loader: TestingModuleLoader = defaultLoader;
+let testingModule: TestingModule | null = null;
+let testingLoadError: Error | null = null;
+
+export const setTestingModuleLoader = (next: TestingModuleLoader | null): void => {
+    loader = next ?? defaultLoader;
+    testingModule = null;
+    testingLoadError = null;
+};
+
+export const loadTestingModule = async (): Promise<TestingModule> => {
+    if (testingModule) return testingModule;
+    if (testingLoadError) throw testingLoadError;
+
+    try {
+        testingModule = await loader();
+        return testingModule;
+    } catch (cause) {
+        testingLoadError = new Error(
+            "@gtkx/testing is not installed, install it to enable MCP widget interactions: " +
+                `pnpm add -D @gtkx/testing (import failed: ${String(cause)})`,
+            { cause },
+        );
+        throw testingLoadError;
+    }
+};

package/src/mcp/widget-registry.ts

@@ -0,0 +1,43 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+export class WidgetRegistry {
+    private idByWidget = new WeakMap<Gtk.Widget, string>();
+    private nextId = 0;
+    private widgetById = new Map<string, Gtk.Widget>();
+    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.idFor(widget);
+        this.widgetById.set(id, widget);
+        let child = widget.getFirstChild();
+        while (child) {
+            this.register(child);
+            child = child.getNextSibling();
+        }
+    }
+
+    idFor(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);
+    }
+}

package/src/refresh-runtime.ts

@@ -7,14 +7,11 @@ globalThis.$RefreshReg$ = () => {};
 globalThis.$RefreshSig$ = () => (type: unknown) => type;
 
 /**
- * Creates registration functions for a module's React components.
+ * Builds the per-module `$RefreshReg$` and `$RefreshSig$` hooks that React Refresh
+ * transformed code expects, scoping every registered component to the given module.
  *
- * 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
+ * @param moduleId Identifier used to namespace registered component types so they are unique across modules.
+ * @returns An object with `$RefreshReg$` and `$RefreshSig$` to install as module-local globals.
  */
 export function createModuleRegistration(moduleId: string): {
     $RefreshReg$: (type: ComponentType, id: string) => void;
@@ -28,36 +25,14 @@ export function createModuleRegistration(moduleId: string): {
     };
 }
 
-function isLikelyComponentType(value: unknown): boolean {
-    if (typeof value !== "function") {
-        return false;
-    }
-
-    const func = value as { $$typeof?: symbol };
-
-    if (func.$$typeof === Symbol.for("react.memo") || func.$$typeof === Symbol.for("react.forward_ref")) {
-        return true;
-    }
-
-    const name = (value as { name?: string }).name;
-    if (typeof name === "string" && /^[A-Z]/.test(name)) {
-        return true;
-    }
-
-    return false;
-}
-
 /**
- * Checks if a module's exports form a React Refresh boundary.
+ * Determines whether a module can act as a React Refresh boundary, meaning every one of
+ * its exports (ignoring `__esModule`) looks like a React component type.
  *
- * 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
+ * @param moduleExports The module's export object to inspect.
+ * @returns `true` when the module qualifies as a refresh boundary, `false` otherwise.
  */
-export function isReactRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
+export function isRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
     if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
         return true;
     }
@@ -69,20 +44,16 @@ export function isReactRefreshBoundary(moduleExports: Record<string, unknown>):
 
         const value = moduleExports[key];
 
-        if (!isLikelyComponentType(value)) {
+        if (!RefreshRuntime.isLikelyComponentType(value)) {
             return false;
         }
     }
 
-    return Object.keys(moduleExports).filter((k) => k !== "__esModule").length > 0;
+    return Object.keys(moduleExports).some((k) => k !== "__esModule");
 }
 
 /**
- * Triggers React Fast Refresh to re-render components.
- *
- * Called after module updates when all exports are React components.
- *
- * @internal
+ * Applies all pending React Refresh updates, re-rendering components whose modules have changed.
  */
 export function performRefresh(): void {
     RefreshRuntime.performReactRefresh();

package/src/settings/compile.ts

@@ -0,0 +1,19 @@
+import { execFileSync } from "node:child_process";
+import { formatChildProcessError } from "@gtkx/utils";
+import { resolveCliTool } from "../internal/resolve-cli-tool.js";
+
+const SCHEMA_COMPILER = "glib-compile-schemas";
+const SCHEMA_COMPILE_TIMEOUT_MS = 30_000;
+
+export const compileSchemas = (dir: string): void => {
+    try {
+        execFileSync(resolveCliTool(SCHEMA_COMPILER), ["--strict", dir], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: SCHEMA_COMPILE_TIMEOUT_MS,
+            encoding: "utf-8",
+        });
+    } catch (error) {
+        const details = formatChildProcessError(error);
+        throw new Error(`glib-compile-schemas failed for ${dir}${details ? `:\n${details}` : ""}`, { cause: error });
+    }
+};