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

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 };

package/src/mcp/serialize-widget.ts

@@ -3,25 +3,30 @@ import type { SerializedWidget } from "@gtkx/mcp/internal";
 
 type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
-export type WidgetFormatting = {
+type WidgetFormatting = {
     formatRole(role: Gtk.AccessibleRole): string;
     getWidgetNodeText(widget: Gtk.Widget): string | null;
 };
 
-export const serializeWidget = (
+const serializeWidget = (
     widget: Gtk.Widget,
-    idFor: WidgetIdResolver,
+    resolveId: WidgetIdResolver,
     testing: WidgetFormatting,
+    maxDepth = Infinity,
 ): SerializedWidget => {
     const children: SerializedWidget[] = [];
-    let child = widget.getFirstChild();
-    while (child) {
-        children.push(serializeWidget(child, idFor, testing));
-        child = child.getNextSibling();
+
+    if (maxDepth > 0) {
+        let child = widget.getFirstChild();
+
+        while (child) {
+            children.push(serializeWidget(child, resolveId, testing, maxDepth - 1));
+            child = child.getNextSibling();
+        }
     }
 
     return {
-        id: idFor(widget),
+        id: resolveId(widget),
         type: widget.constructor.name,
         role: testing.formatRole(widget.getAccessibleRole()),
         name: widget.getName() || null,
@@ -32,3 +37,5 @@ export const serializeWidget = (
         children,
     };
 };
+
+export { serializeWidget, type WidgetFormatting };

package/src/mcp/testing-loader.ts

@@ -1,32 +1,73 @@
 type TestingModule = typeof import("@gtkx/testing");
+type TestingModuleLoader = () => Promise<TestingModule>;
 
-export 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 defaultLoader: TestingModuleLoader = () => import("@gtkx/testing");
+const { setLoader: setTestingModuleLoader, load: loadTestingModule } = createTestingModuleCache();
 
-let loader: TestingModuleLoader = defaultLoader;
-let testingModule: TestingModule | null = null;
-let testingLoadError: Error | null = null;
+function defaultLoader(): Promise<TestingModule> {
+    return import("@gtkx/testing");
+}
 
-export const setTestingModuleLoader = (next: TestingModuleLoader | null): void => {
-    loader = next ?? defaultLoader;
-    testingModule = null;
-    testingLoadError = null;
-};
+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 },
+    );
+}
 
-export const loadTestingModule = async (): Promise<TestingModule> => {
-    if (testingModule) return testingModule;
-    if (testingLoadError) throw testingLoadError;
+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 {
-        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;
+        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

@@ -1,14 +1,15 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
-export class WidgetRegistry {
-    private idByWidget = new WeakMap<Gtk.Widget, string>();
+class WidgetRegistry {
+    private idByWidget: WeakMap<Gtk.Widget, string> = new WeakMap();
     private nextId = 0;
-    private widgetById = new Map<string, Gtk.Widget>();
+    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);
         }
@@ -19,21 +20,24 @@ export class WidgetRegistry {
     }
 
     register(widget: Gtk.Widget): void {
-        const id = this.idFor(widget);
+        const id = this.getOrCreateId(widget);
         this.widgetById.set(id, widget);
         let child = widget.getFirstChild();
+
         while (child) {
             this.register(child);
             child = child.getNextSibling();
         }
     }
 
-    idFor(widget: Gtk.Widget): string {
+    getOrCreateId(widget: Gtk.Widget): string {
         let id = this.idByWidget.get(widget);
+
         if (!id) {
             id = String(this.nextId++);
             this.idByWidget.set(widget, id);
         }
+
         return id;
     }
 
@@ -41,3 +45,5 @@ export class WidgetRegistry {
         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,
+});

package/src/refresh-runtime.ts

@@ -1,11 +1,8 @@
 import RefreshRuntime from "react-refresh/runtime";
+import "./refresh-globals.js";
 
 type ComponentType = (...args: unknown[]) => unknown;
 
-RefreshRuntime.injectIntoGlobalHook(globalThis);
-globalThis.$RefreshReg$ = () => {};
-globalThis.$RefreshSig$ = () => (type: unknown) => type;
-
 /**
  * Builds the per-module `$RefreshReg$` and `$RefreshSig$` hooks that React Refresh
  * transformed code expects, scoping every registered component to the given module.
@@ -13,7 +10,7 @@ globalThis.$RefreshSig$ = () => (type: unknown) => type;
  * @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): {
+function createModuleRegistration(moduleId: string): {
     $RefreshReg$: (type: ComponentType, id: string) => void;
     $RefreshSig$: typeof RefreshRuntime.createSignatureFunctionForTransform;
 } {
@@ -32,21 +29,26 @@ export function createModuleRegistration(moduleId: string): {
  * @param moduleExports The module's export object to inspect.
  * @returns `true` when the module qualifies as a refresh boundary, `false` otherwise.
  */
-export function isRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
-    if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
-        return true;
-    }
+const isComponentExport = (key: string, value: unknown): boolean =>
+    key === "__esModule" || RefreshRuntime.isLikelyComponentType(value);
 
+const areAllExportsComponents = (moduleExports: Record<string, unknown>): boolean => {
     for (const key in moduleExports) {
-        if (key === "__esModule") {
-            continue;
+        if (!isComponentExport(key, moduleExports[key])) {
+            return false;
         }
+    }
 
-        const value = moduleExports[key];
+    return true;
+};
 
-        if (!RefreshRuntime.isLikelyComponentType(value)) {
-            return false;
-        }
+function isRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
+    if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
+        return true;
+    }
+
+    if (!areAllExportsComponents(moduleExports)) {
+        return false;
     }
 
     return Object.keys(moduleExports).some((k) => k !== "__esModule");
@@ -55,6 +57,8 @@ export function isRefreshBoundary(moduleExports: Record<string, unknown>): boole
 /**
  * Applies all pending React Refresh updates, re-rendering components whose modules have changed.
  */
-export function performRefresh(): void {
+function performRefresh(): void {
     RefreshRuntime.performReactRefresh();
 }
+
+export { createModuleRegistration, isRefreshBoundary, performRefresh };

package/src/settings/compile.ts

@@ -1,19 +1,22 @@
-import { execFileSync } from "node:child_process";
 import { formatChildProcessError } from "@gtkx/utils";
+import { execFileSync } from "node:child_process";
 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 => {
+const compileSchemas = (dir: string): void => {
     try {
         execFileSync(resolveCliTool(SCHEMA_COMPILER), ["--strict", dir], {
             stdio: ["ignore", "pipe", "pipe"],
             timeout: SCHEMA_COMPILE_TIMEOUT_MS,
-            encoding: "utf-8",
+            encoding: "utf8",
         });
     } catch (error) {
         const details = formatChildProcessError(error);
-        throw new Error(`glib-compile-schemas failed for ${dir}${details ? `:\n${details}` : ""}`, { cause: error });
+        const suffix = details ? `:\n${details}` : "";
+        throw new Error(`glib-compile-schemas failed for ${dir}${suffix}`, { cause: error });
     }
 };
+
+export { compileSchemas };