@gtkx/cli 1.0.0-rc.4 → 1.0.0

package/src/cli.ts

@@ -1,8 +1,10 @@
 import { packageVersion } from "@gtkx/utils";
 import { defineCommand, runMain } from "citty";
+import { splitApplicationArgs } from "./internal/application-args.js";
 import { withErrorBoundary } from "./internal/errors.js";
 
-const version = packageVersion(import.meta.url);
+const version = packageVersion(import.meta.url, "../package.json");
+const { cliArgs } = splitApplicationArgs(process.argv.slice(2));
 
 const main = defineCommand({
     meta: {
@@ -39,4 +41,4 @@ const main = defineCommand({
     },
 });
 
-await runMain(main);
+await runMain(main, { rawArgs: cliArgs });

package/src/codegen/freshness.ts

@@ -27,8 +27,6 @@ const namespaceBarrelPath = (giStoreDir: string, library: string): string => {
     return join(giStoreDir, namespace, "index.js");
 };
 
-// The manifest is what makes the store resolvable as a package, and npm's prune of a generated store
-// removes the link while leaving the directory behind, so both have to be checked.
 const hasManifest = (storeDir: string): boolean => existsSync(join(storeDir, "package.json"));
 
 const isGiStoreStale = (store: CodegenStore, libraries: string[]): boolean => {

package/src/codegen/run-codegen.ts

@@ -200,6 +200,7 @@ const getRunOptions = ({ root, mode, inputs, resolved }: RunOptionsInput): RunCo
     return { cwd: root, mode, inputs, resolved };
 };
 
+/* eslint-disable-next-line unicorn/consistent-boolean-name -- the boolean reports whether codegen ran */
 const ensureGenerated = async (
     cwd: string,
     options: { shouldAnnounce?: boolean; mode?: string } = {},
@@ -245,6 +246,5 @@ export {
     syncSchemaEnv,
     ensureGenerated,
     resolveConfigWatch,
-    type RunCodegenOptions,
     type RunCodegenResult,
 };

package/src/codegen/store-resolver.ts

@@ -83,4 +83,4 @@ const resolveCodegenContext = async (cwd: string, mode?: string): Promise<Codege
     return { root: cwd, config, configFile };
 };
 
-export { resolveCodegenStore, resolveCodegenContext, type CodegenStore, type CodegenContext };
+export { resolveCodegenStore, resolveCodegenContext, type CodegenStore };

package/src/commands/dev.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from "citty";
 import { ensureGenerated, resolveConfigWatch } from "../codegen/run-codegen.js";
 import { type DevWatch, runDevSupervisor } from "../dev/supervisor.js";
+import { splitApplicationArgs } from "../internal/application-args.js";
 import { entryArg, resolveEntry } from "../internal/entry-arg.js";
 
 const DEV_MODE = "development";
@@ -17,7 +18,8 @@ const dev = defineCommand({
         const { cwd, entry: entryPath } = resolveEntry(args);
         await ensureGenerated(cwd, { shouldAnnounce: true, mode: DEV_MODE });
         const watch: DevWatch | undefined = await resolveConfigWatch(cwd, DEV_MODE);
-        await runDevSupervisor(entryPath, cwd, watch);
+        const { applicationArgs } = splitApplicationArgs(process.argv.slice(2));
+        await runDevSupervisor({ entryPath, cwd, args: applicationArgs, watch });
     },
 });
 

package/src/dev/entry-env.ts

@@ -0,0 +1,3 @@
+const DEV_ENTRY_ENV = "GTKX_DEV_ENTRY";
+
+export { DEV_ENTRY_ENV };

package/src/dev/runner-deps.ts

@@ -45,6 +45,7 @@ const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     watchApplicationShutdown: (onShutdown) => {
         Gio.Application.getDefault()?.on("shutdown", onShutdown);
     },
+    isApplicationRegistered: () => Gio.Application.getDefault()?.getIsRegistered() === true,
     installShutdownHandlers: (onSignal) => {
         installGracefulShutdown({ onSignal });
     },

package/src/dev/runner-main.ts

@@ -1,12 +1,11 @@
 import { error } from "@gtkx/utils";
 import { resolve } from "node:path";
 import { resolveDataDir } from "../internal/data-dir.js";
+import { DEV_ENTRY_ENV } from "./entry-env.js";
 import { prepareDevIconDir } from "./icon-dir.js";
 import { createDevRunner } from "./runner.js";
 import { prepareDevSchemaDir } from "./schema-dir.js";
 
-const ENTRY_ARG_INDEX = 2;
-
 const main = async (): Promise<void> => {
     if (process.channel) {
         process.once("disconnect", () => {
@@ -15,10 +14,10 @@ const main = async (): Promise<void> => {
     }
 
     const cwd = process.cwd();
-    const entryArg = process.argv[ENTRY_ARG_INDEX];
+    const entryArg = process.env[DEV_ENTRY_ENV];
 
     if (!entryArg) {
-        error("Missing entry argument");
+        error(`Missing ${DEV_ENTRY_ENV}`);
         process.exit(1);
     }
 

package/src/dev/runner.ts

@@ -14,6 +14,7 @@ type DevRunnerDeps = {
     ): Promise<unknown>;
     stopMcpClient(): void;
     watchApplicationShutdown(onShutdown: () => void): void;
+    isApplicationRegistered(): boolean;
     installShutdownHandlers(onSignal: () => void | Promise<void>): void;
     quitDefaultApplication(): void;
     performRefresh: () => void;
@@ -126,7 +127,11 @@ const onShutdownSignal =
             });
         };
 
-const closeAndExit = async (deps: DevRunnerDeps, controller: ShutdownController): Promise<never> => {
+const closeAndExit = async (
+    deps: DevRunnerDeps,
+    controller: ShutdownController,
+    code = 0,
+): Promise<never> => {
     try {
         await controller.shutdown((): void => undefined);
     } catch (error_) {
@@ -135,7 +140,7 @@ const closeAndExit = async (deps: DevRunnerDeps, controller: ShutdownController)
         return deps.exit(1);
     }
 
-    return deps.exit(0);
+    return deps.exit(code);
 };
 
 const onApplicationShutdown =
@@ -155,6 +160,42 @@ const onApplicationShutdown =
             void closeAndExit(deps, controller);
         };
 
+const refusedExitCode = (): number => (process.exitCode === undefined ? 1 : Number(process.exitCode));
+
+const connectApplication = async (
+    deps: DevRunnerDeps,
+    server: DevServer,
+    liveApplicationId: string,
+    tracked: { refreshTracker: RefreshTracker; controller: ShutdownController },
+): Promise<void> => {
+    deps.watchApplicationShutdown(onApplicationShutdown(deps, tracked.refreshTracker, tracked.controller));
+    const applicationId = (await deps.getConfiguredApplicationId(process.cwd())) ?? liveApplicationId;
+    deps.log(`Connected application ID: ${applicationId}`);
+    await deps.startMcpClient(applicationId, (id) => server.ssrLoadModule(id));
+};
+
+const attachApplication = async (
+    deps: DevRunnerDeps,
+    server: DevServer,
+    tracked: { refreshTracker: RefreshTracker; controller: ShutdownController },
+): Promise<void> => {
+    const liveApplicationId = await deps.waitForApplicationId(APPLICATION_MOUNT_TIMEOUT_MS);
+
+    if (liveApplicationId === null) {
+        deps.log("Entry did not mount an application - MCP client not started.");
+
+        return;
+    }
+
+    if (!deps.isApplicationRegistered()) {
+        deps.log("Application refused its command line - stopping dev runner...");
+
+        return closeAndExit(deps, tracked.controller, refusedExitCode());
+    }
+
+    await connectApplication(deps, server, liveApplicationId, tracked);
+};
+
 const createDevRunner = (deps: DevRunnerDeps): DevRunner => ({
     async run(entryPath: string): Promise<void> {
         const root = process.cwd();
@@ -166,17 +207,7 @@ const createDevRunner = (deps: DevRunnerDeps): DevRunner => ({
         server.watcher.on("change", onFileChange(server, refreshTrackingDeps, controller));
         deps.log(`Loading entry: ${entryPath}`);
         await server.ssrLoadModule(entryPath);
-        const liveApplicationId = await deps.waitForApplicationId(APPLICATION_MOUNT_TIMEOUT_MS);
-
-        if (liveApplicationId) {
-            deps.watchApplicationShutdown(onApplicationShutdown(deps, refreshTracker, controller));
-            const applicationId = (await deps.getConfiguredApplicationId(root)) ?? liveApplicationId;
-            deps.log(`Connected application ID: ${applicationId}`);
-            await deps.startMcpClient(applicationId, (id) => server.ssrLoadModule(id));
-        } else {
-            deps.log("Entry did not mount an application - MCP client not started.");
-        }
-
+        await attachApplication(deps, server, { refreshTracker, controller });
         deps.log("HMR enabled - watching for changes...");
     },
 });

package/src/dev/supervisor.ts

@@ -3,6 +3,7 @@ import { fork as nodeFork } from "node:child_process";
 import { type FSWatcher, watch as watchFs } from "node:fs";
 import { basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEV_ENTRY_ENV } from "./entry-env.js";
 
 type SupervisedChild = {
     killed: boolean;
@@ -13,7 +14,7 @@ type SupervisedChild = {
     once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
 };
 
-type ForkRunner = (modulePath: string, args: string[], cwd: string) => SupervisedChild;
+type ForkRunner = (modulePath: string, args: string[], env: NodeJS.ProcessEnv, cwd: string) => SupervisedChild;
 
 type DevWatch = {
     paths: string[];
@@ -24,6 +25,7 @@ type SupervisorState = {
     runnerPath: string;
     entryPath: string;
     cwd: string;
+    args: string[];
     watch: DevWatch | undefined;
     watchers: FSWatcher[];
     fork: ForkRunner;
@@ -33,15 +35,45 @@ type SupervisorState = {
     capturedChildExit: number | undefined;
 };
 
+type DevSupervisorOptions = {
+    entryPath: string;
+    cwd: string;
+    args?: string[] | undefined;
+    watch?: DevWatch | undefined;
+    fork?: ForkRunner | undefined;
+};
+
 type DebounceTimer = { handle: NodeJS.Timeout | null };
 
 const DEV_RUNNER_URL = new URL("../../bin/gtkx-dev-runner.js", import.meta.url);
 const FORCE_KILL_TIMEOUT_MS = 5000;
 const CONFIG_DEBOUNCE_MS = 150;
 const RESTART_EXIT_CODE = 75;
+const CONDITION_FLAG = /^(?:--conditions|-C)(?:=.*)?$/;
+const SPLIT_CONDITION_FLAG = /^(?:--conditions|-C)$/;
+
+const withoutConditions = (argv: string[]): string[] =>
+    argv.filter(
+        (argument, index) => !CONDITION_FLAG.test(argument) && !SPLIT_CONDITION_FLAG.test(argv[index - 1] ?? ""),
+    );
+
+const getNodeOptions = (env: NodeJS.ProcessEnv): string | undefined => {
+    const options = env.NODE_OPTIONS;
+
+    return options === undefined ? undefined : withoutConditions(options.split(/\s+/)).join(" ");
+};
 
-const defaultForkRunner: ForkRunner = (modulePath, args, cwd) =>
-    nodeFork(modulePath, [...args], { cwd, stdio: "inherit", detached: true });
+const defaultForkRunner: ForkRunner = (modulePath, args, env, cwd) => {
+    const nodeOptions = getNodeOptions(env);
+
+    return nodeFork(modulePath, args, {
+        cwd,
+        env: { ...env, ...(nodeOptions !== undefined && { NODE_OPTIONS: nodeOptions }) },
+        stdio: "inherit",
+        detached: true,
+        execArgv: withoutConditions(process.execArgv),
+    });
+};
 
 const forwardSignal = (child: SupervisedChild, signal: NodeJS.Signals): void => {
     if (!child.killed) {
@@ -93,7 +125,13 @@ const handleChildExit = (state: SupervisorState, code: number | null, signal: No
 };
 
 const launch = (state: SupervisorState): void => {
-    const child = state.fork(state.runnerPath, [state.entryPath], state.cwd);
+    const child = state.fork(
+        state.runnerPath,
+        state.args,
+        { ...process.env, [DEV_ENTRY_ENV]: state.entryPath },
+        state.cwd,
+    );
+
     state.child = child;
 
     child.on("exit", (code, signal) => {
@@ -247,16 +285,14 @@ const installShutdown = (state: SupervisorState): void => {
     });
 };
 
-const runDevSupervisor = async (
-    entryPath: string,
-    cwd: string,
-    watch?: DevWatch,
-    fork: ForkRunner = defaultForkRunner,
-): Promise<never> => {
+const runDevSupervisor = async (options: DevSupervisorOptions): Promise<never> => {
+    const { entryPath, cwd, args = [], watch, fork = defaultForkRunner } = options;
+
     const state: SupervisorState = {
         runnerPath: fileURLToPath(DEV_RUNNER_URL),
         entryPath,
         cwd,
+        args,
         watch,
         watchers: [],
         fork,
@@ -273,4 +309,11 @@ const runDevSupervisor = async (
     return new Promise<never>((): void => undefined);
 };
 
-export { RESTART_EXIT_CODE, defaultForkRunner, runDevSupervisor, type SupervisedChild, type ForkRunner, type DevWatch };
+export {
+    RESTART_EXIT_CODE,
+    defaultForkRunner,
+    runDevSupervisor,
+    type DevWatch,
+    type ForkRunner,
+    type SupervisedChild,
+};

package/src/internal/application-args.ts

@@ -0,0 +1,13 @@
+const APPLICATION_ARGS_SEPARATOR = "--";
+
+const splitApplicationArgs = (argv: string[]): { cliArgs: string[]; applicationArgs: string[] } => {
+    const separator = argv.indexOf(APPLICATION_ARGS_SEPARATOR);
+
+    if (separator === -1) {
+        return { cliArgs: argv, applicationArgs: [] };
+    }
+
+    return { cliArgs: argv.slice(0, separator), applicationArgs: argv.slice(separator + 1) };
+};
+
+export { splitApplicationArgs };

package/src/internal/errors.ts

@@ -33,4 +33,4 @@ const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDe
     };
 };
 
-export { printError, withErrorBoundary };
+export { withErrorBoundary };

package/src/internal/run-cli-tool.ts

@@ -0,0 +1,22 @@
+import { formatChildProcessError, resolveExecutable } from "@gtkx/utils";
+import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
+
+type CliToolInvocation = {
+    tool: string;
+    args: string[];
+    target?: string;
+    options?: ExecFileSyncOptions;
+};
+
+const runCliTool = ({ tool, args, target, options }: CliToolInvocation): void => {
+    try {
+        execFileSync(resolveExecutable(tool), args, options);
+    } catch (error) {
+        const details = formatChildProcessError(error);
+        const suffix = details ? `:\n${details}` : "";
+        const subject = target === undefined ? "" : ` for ${target}`;
+        throw new Error(`${tool} failed${subject}${suffix}`, { cause: error });
+    }
+};
+
+export { runCliTool };

package/src/internal.ts

@@ -0,0 +1,2 @@
+export { dispatch } from "./mcp/handlers.js";
+export { WidgetRegistry } from "./mcp/widget-registry.js";

package/src/mcp/client.ts

@@ -232,4 +232,4 @@ class McpClient {
     }
 }
 
-export { McpClient, type McpClientOptions };
+export { McpClient };

package/src/mcp/handlers.ts

@@ -8,11 +8,10 @@ import {
     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";
+import { readWidgetProperties } from "./widget-properties.js";
 
 type HandlerContext = {
     app: Gtk.Application;
@@ -21,6 +20,11 @@ type HandlerContext = {
 
 type ValidatedHandler = (ctx: HandlerContext, params: unknown) => Promise<unknown>;
 type WidgetTarget = { testing: TestingModule; widget: Gtk.Widget };
+type WidgetParams = { widgetId?: string | undefined };
+type TargetedHandler<Params> = (ctx: HandlerContext, target: WidgetTarget, params: Params) => Promise<unknown>;
+type QueryParams = ServerRequestParams<"widget.query">;
+type QueryBy = QueryParams["by"];
+type QueryRunner = (testing: TestingModule, app: Gtk.Application, params: QueryParams) => Promise<Gtk.Widget[]>;
 
 const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
     "app.getWindows": validated(ServerRequestParamsSchemas["app.getWindows"], ({ registry }) =>
@@ -43,20 +47,22 @@ const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
         };
     }),
     "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);
+    "widget.getProps": targeted(
+        ServerRequestParamsSchemas["widget.getProps"],
+        ({ registry }, { testing, widget }, params) =>
+            Promise.resolve({
+                ...(params.properties !== undefined && {
+                    properties: readWidgetProperties(widget, params.properties, registry),
+                }),
+                ...serializeWidget(widget, (target) => registry.getOrCreateId(target), testing, params.maxDepth),
+            }),
+    ),
+    "widget.click": targeted(ServerRequestParamsSchemas["widget.click"], async (_ctx, { testing, widget }) => {
         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);
-
+    "widget.type": targeted(ServerRequestParamsSchemas["widget.type"], async (_ctx, { testing, widget }, params) => {
         if (params.clear) {
             await testing.userEvent.clear(widget);
         }
@@ -65,16 +71,43 @@ const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
 
         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.fireEvent": targeted(
+        ServerRequestParamsSchemas["widget.fireEvent"],
+        async (_ctx, { testing, widget }, params) => {
+            const signalArgs = (params.args ?? []).map((arg) => extractSignalArg(arg));
+            const isRealized = widget.getRealized();
+            const isMapped = widget.getMapped();
+            const isSensitive = widget.getSensitive();
+            await testing.fireEvent(widget, params.signal, ...signalArgs);
+
+            return {
+                signal: params.signal,
+                isRealized,
+                isMapped,
+                isSensitive,
+                note: emissionNote(isRealized, isMapped),
+            };
+        },
+    ),
     "widget.screenshot": validated(ServerRequestParamsSchemas["widget.screenshot"], handleScreenshot),
 };
 
+const QUERY_RUNNERS: Record<QueryBy, QueryRunner> = {
+    role: runRoleQuery,
+    text: runTextQuery,
+    name: runNameQuery,
+    labelText: runLabelTextQuery,
+};
+
+const SEARCHED_BY: Record<QueryBy, string> = {
+    role: "the accessible role, narrowed by any options given",
+    text: "the text the widget renders",
+    name:
+        "the widget name (gtk_widget_get_name, which reports the GType name such as \"GtkButton\" when no name " +
+        "was set), the accessible label, and the text the widget renders",
+    labelText: "the accessible label, the labelled-by relation, and the label whose mnemonic targets the widget",
+};
+
 function validated<Params>(
     schema: ParamsSchema<Params>,
     handler: (ctx: HandlerContext, params: Params) => Promise<unknown>,
@@ -90,6 +123,14 @@ function validated<Params>(
     };
 }
 
+function targeted<Params extends WidgetParams>(
+    schema: ParamsSchema<Params>,
+    handler: TargetedHandler<Params>,
+): ValidatedHandler {
+    return validated(schema, async (ctx, params) =>
+        handler(ctx, await widgetTarget(ctx.registry, params.widgetId), params));
+}
+
 const widgetTarget = async (registry: WidgetRegistry, widgetId: string | undefined): Promise<WidgetTarget> => ({
     testing: await loadTestingModule(),
     widget: requireWidget(registry, widgetId),
@@ -115,6 +156,21 @@ const extractSignalArg = (arg: unknown): unknown => {
     return isTypedArg ? (arg as { value: unknown }).value : arg;
 };
 
+const emissionNote = (isRealized: boolean, isMapped: boolean): string => {
+    if (isRealized && isMapped) {
+        return (
+            "The signal was emitted. Default handlers that animate, such as a button activate, settle " +
+            "asynchronously, so read the widget again rather than assuming the effect has landed."
+        );
+    }
+
+    return (
+        "The signal was emitted on a widget that is not realized and mapped, so a default handler that " +
+        "requires a drawn widget does nothing. Present the containing window or open the containing " +
+        "popover first, then fire the signal again."
+    );
+};
+
 const resolveRole = (value: string | number): Gtk.AccessibleRole | undefined => {
     if (typeof value === "number") {
         return value;
@@ -133,42 +189,56 @@ const matchesOrEmpty = async (find: () => Promise<Gtk.Widget[]>): Promise<Gtk.Wi
     }
 };
 
-async function handleQuery(
-    { app, registry }: HandlerContext,
-    params: ServerRequestParams<"widget.query">,
-): Promise<unknown> {
-    const testing = await loadTestingModule();
-    let widgets: Gtk.Widget[] = [];
+function runRoleQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    const roleValue = resolveRole(params.value);
 
-    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\".",
+        );
+    }
 
-            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\".",
-                );
-            }
+    return matchesOrEmpty(() => testing.findAllByRole(app, roleValue, params.options));
+}
 
-            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;
-        }
-    }
+function runTextQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    return matchesOrEmpty(() => testing.findAllByText(app, String(params.value), params.options));
+}
 
-    return { widgets: widgets.map((w) => serializeWidget(w, (widget) => registry.getOrCreateId(widget), testing, 0)) };
+function runLabelTextQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    return matchesOrEmpty(() => testing.findAllByLabelText(app, String(params.value), params.options));
+}
+
+async function runNameQuery(
+    testing: TestingModule,
+    app: Gtk.Application,
+    params: QueryParams,
+): Promise<Gtk.Widget[]> {
+    const matches = await Promise.all([
+        matchesOrEmpty(() => testing.findAllByName(app, String(params.value), params.options)),
+        runLabelTextQuery(testing, app, params),
+        runTextQuery(testing, app, params),
+    ]);
+
+    return [...new Set(matches.flat())];
+}
+
+const emptyQueryHint = (params: QueryParams): string =>
+    `Nothing matched by:"${params.by}" value:"${String(params.value)}", which compared ${SEARCHED_BY[params.by]}. ` +
+    "Call gtkx_get_widget_tree to see what is mounted; by:\"name\" is the widest match, and by:\"role\" accepts " +
+    "options.name to match the accessible name of a known role.";
+
+async function handleQuery({ app, registry }: HandlerContext, params: QueryParams): Promise<unknown> {
+    const testing = await loadTestingModule();
+    const widgets = await QUERY_RUNNERS[params.by](testing, app, params);
+    const resolveId = (widget: Gtk.Widget): string => registry.getOrCreateId(widget);
+
+    return {
+        widgets: widgets.map((widget) => serializeWidget(widget, resolveId, testing, 0)),
+        searched: SEARCHED_BY[params.by],
+        ...(widgets.length === 0 && { hint: emptyQueryHint(params) }),
+    };
 }
 
 const defaultScreenshotTarget = (registry: WidgetRegistry): Gtk.Widget => {
@@ -187,12 +257,9 @@ async function handleScreenshot(
 ): Promise<unknown> {
     const testing = await loadTestingModule();
     const target = params.windowId ? requireWidget(registry, params.windowId) : defaultScreenshotTarget(registry);
-    const result = await testing.screenshot(target);
+    const result = await testing.screenshot(target, { path: params.path });
 
     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 };
     }
 
@@ -210,4 +277,4 @@ const dispatch = async (method: string, params: unknown, ctx: HandlerContext): P
     return HANDLERS[method](ctx, params);
 };
 
-export { dispatch, type HandlerContext };
+export { dispatch };

package/src/mcp/index.ts

@@ -7,6 +7,7 @@ type McpClientController = {
 
 const { start: startMcpClient, stop: stopMcpClient } = createMcpClientController();
 
+/* eslint-disable-next-line unicorn/consistent-boolean-name -- the boolean reports whether connecting succeeded */
 async function connectQuietly(client: McpClient): Promise<boolean> {
     try {
         await client.connect();