@gtkx/cli 1.0.0-rc.3 → 1.0.0

package/src/mcp/serialize-widget.ts

@@ -1,41 +1,91 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { SerializedWidget } from "@gtkx/mcp/internal";
+import { DEFAULT_SUBTREE_DEPTH, MAX_SUBTREE_WIDGETS, 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;
+    getWidgetText(widget: Gtk.Widget): string | null;
+};
+
+type PendingWidget = {
+    depth: number;
+    node: SerializedWidget;
+    widget: Gtk.Widget;
+};
+
+type Expansion = {
+    budget: number;
+    maxDepth: number;
+    pending: PendingWidget[];
+    resolveId: WidgetIdResolver;
+    testing: WidgetFormatting;
+};
+
+const getChildren = (widget: Gtk.Widget): Gtk.Widget[] => {
+    const children: Gtk.Widget[] = [];
+    let child = widget.getFirstChild();
+
+    while (child) {
+        children.push(child);
+        child = child.getNextSibling();
+    }
+
+    return children;
+};
+
+const createNode = (widget: Gtk.Widget, expansion: Expansion): SerializedWidget => ({
+    id: expansion.resolveId(widget),
+    type: widget.constructor.name,
+    role: expansion.testing.formatRole(widget.getAccessibleRole()),
+    name: widget.getName() || null,
+    text: expansion.testing.getWidgetText(widget),
+    isSensitive: widget.getSensitive(),
+    isVisible: widget.getVisible(),
+    cssClasses: widget.getCssClasses(),
+    children: [],
+});
+
+const expandNode = (expansion: Expansion, parent: PendingWidget): void => {
+    const children = getChildren(parent.widget);
+    const canDescend = parent.depth < expansion.maxDepth;
+    const shownCount = canDescend ? Math.min(children.length, expansion.budget) : 0;
+    expansion.budget -= shownCount;
+
+    for (const child of children.slice(0, shownCount)) {
+        const node = createNode(child, expansion);
+        parent.node.children.push(node);
+        expansion.pending.push({ depth: parent.depth + 1, node, widget: child });
+    }
+
+    if (shownCount < children.length) {
+        parent.node.hiddenChildren = children.length - shownCount;
+    }
 };
 
 const serializeWidget = (
     widget: Gtk.Widget,
     resolveId: WidgetIdResolver,
     testing: WidgetFormatting,
-    maxDepth = Infinity,
+    maxDepth = DEFAULT_SUBTREE_DEPTH,
 ): SerializedWidget => {
-    const children: SerializedWidget[] = [];
+    const expansion: Expansion = {
+        budget: MAX_SUBTREE_WIDGETS - 1,
+        maxDepth,
+        pending: [],
+        resolveId,
+        testing,
+    };
 
-    if (maxDepth > 0) {
-        let child = widget.getFirstChild();
+    const root = createNode(widget, expansion);
+    let parent: PendingWidget | undefined = { depth: 0, node: root, widget };
 
-        while (child) {
-            children.push(serializeWidget(child, resolveId, testing, maxDepth - 1));
-            child = child.getNextSibling();
-        }
+    while (parent !== undefined) {
+        expandNode(expansion, parent);
+        parent = expansion.pending.shift();
     }
 
-    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,
-    };
+    return root;
 };
 
 export { serializeWidget, type WidgetFormatting };

package/src/mcp/widget-properties.ts

@@ -0,0 +1,153 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import { propertyNotFoundError, type SerializedProperty } from "@gtkx/mcp/internal";
+import {
+    type ExternalObject,
+    getHandle,
+    getInstanceType,
+    type Handle,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    typeIsA,
+    typeName,
+} from "@gtkx/runtime";
+import { fromValue, getValueType } from "@gtkx/runtime/internal";
+import { camelCase, errorMessage, kebabCase } from "@gtkx/utils";
+import type { WidgetRegistry } from "./widget-registry.js";
+
+type PropertyRepresentation = Omit<SerializedProperty, "type">;
+type NativeProperty = { type: bigint; handle: ExternalObject<Handle> };
+
+const SCALAR_TYPES: Set<string> = new Set(["string", "number", "boolean"]);
+
+const canonicalName = (name: string): string => kebabCase(name).replaceAll("_", "-");
+const widgetTypeName = (widget: Gtk.Widget): string => typeName(getInstanceType(widget)) ?? widget.constructor.name;
+const byName = (left: string, right: string): number => left.localeCompare(right);
+
+const isScalar = (value: unknown): value is string | number | boolean | null =>
+    value === null || SCALAR_TYPES.has(typeof value);
+
+function prototypesFor(widget: Gtk.Widget): object[] {
+    const prototypes: object[] = [];
+    let prototype = Object.getPrototypeOf(widget) as object | null;
+
+    while (prototype !== null && prototype !== Object.prototype) {
+        prototypes.push(prototype);
+        prototype = Object.getPrototypeOf(prototype) as object | null;
+    }
+
+    return prototypes;
+}
+
+function getAccessor(widget: Gtk.Widget, member: string): PropertyDescriptor | undefined {
+    for (const prototype of prototypesFor(widget)) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, member);
+
+        if (descriptor !== undefined) {
+            return descriptor;
+        }
+    }
+
+    return undefined;
+}
+
+function getReadableNames(prototype: object): string[] {
+    const descriptors = Object.entries(Object.getOwnPropertyDescriptors(prototype));
+
+    return descriptors.filter(([, descriptor]) => descriptor.get !== undefined).map(([member]) => kebabCase(member));
+}
+
+function readablePropertyNames(widget: Gtk.Widget): string[] {
+    const names = prototypesFor(widget).flatMap((prototype) => getReadableNames(prototype));
+
+    return [...new Set(names)].toSorted(byName);
+}
+
+const requireReadableProperty = (widget: Gtk.Widget, property: string): void => {
+    if (getAccessor(widget, camelCase(property))?.get !== undefined) {
+        return;
+    }
+
+    throw propertyNotFoundError(widgetTypeName(widget), property, readablePropertyNames(widget));
+};
+
+function readNativeProperty(widget: Gtk.Widget, property: string): NativeProperty {
+    const value = new GObject.Value();
+    widget.getProperty(property, value);
+    const handle = getHandle(value);
+
+    return { type: getValueType(handle), handle };
+}
+
+function describeObjectValue(value: unknown, registry: WidgetRegistry): PropertyRepresentation {
+    if (typeof value !== "object" || value === null) {
+        return { value: String(value) };
+    }
+
+    const name = typeName(getInstanceType(value)) ?? value.constructor.name;
+
+    if (!(value instanceof Gtk.Widget)) {
+        return { value: name };
+    }
+
+    registry.register(value);
+
+    return { value: name, widgetId: registry.getOrCreateId(value) };
+}
+
+function representValue(value: unknown, registry: WidgetRegistry): PropertyRepresentation {
+    if (isScalar(value)) {
+        return { value };
+    }
+
+    if (typeof value === "bigint") {
+        return { value: value.toString() };
+    }
+
+    if (Array.isArray(value)) {
+        return { value: value.map(String) };
+    }
+
+    return describeObjectValue(value, registry);
+}
+
+function representNativeProperty(native: NativeProperty, registry: WidgetRegistry): PropertyRepresentation {
+    if (typeIsA(native.type, TYPE_ENUM)) {
+        return { value: GObject.enumToString(native.type, Number(fromValue(native.handle))) };
+    }
+
+    if (typeIsA(native.type, TYPE_FLAGS)) {
+        return { value: GObject.flagsToString(native.type, Number(fromValue(native.handle))) };
+    }
+
+    return representValue(fromValue(native.handle), registry);
+}
+
+function serializeProperty(widget: Gtk.Widget, property: string, registry: WidgetRegistry): SerializedProperty {
+    const native = readNativeProperty(widget, property);
+    const type = typeName(native.type) ?? String(native.type);
+
+    try {
+        return { type, ...representNativeProperty(native, registry) };
+    } catch (error) {
+        return { type, value: null, note: `cannot be represented over MCP: ${errorMessage(error)}` };
+    }
+}
+
+function readWidgetProperties(
+    widget: Gtk.Widget,
+    properties: string[],
+    registry: WidgetRegistry,
+): Record<string, SerializedProperty> {
+    const values: Record<string, SerializedProperty> = {};
+
+    for (const name of properties) {
+        const property = canonicalName(name);
+        requireReadableProperty(widget, property);
+        values[property] = serializeProperty(widget, property, registry);
+    }
+
+    return values;
+}
+
+export { readWidgetProperties };

package/src/refresh-runtime.ts

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

package/src/settings/compile.ts

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

package/src/settings/schema.ts

@@ -11,7 +11,7 @@ import { renderEnvModule } from "./render.js";
 
 type SchemaEnvResult = {
     path: string;
-    written: boolean;
+    isWritten: boolean;
 };
 
 const SCHEMA_SUFFIX = ".gschema.xml";
@@ -155,7 +155,7 @@ const emitSchemaEnv = (rootDir: string, dataDir: string | null): SchemaEnvResult
     const path = schemaEnvPath(rootDir);
     const isWritten = didWriteChanges(path, content);
 
-    return { path, written: isWritten };
+    return { path, isWritten };
 };
 
 export {

package/src/vite-plugins/asset-emitter.ts

@@ -0,0 +1,5 @@
+type AssetEmitter = {
+    emitFile: (file: { type: "asset"; fileName: string; source: Buffer }) => void;
+};
+
+export { type AssetEmitter };

package/src/vite-plugins/asset-extensions.ts

@@ -26,4 +26,4 @@ const ASSET_EXTENSIONS = [
 const ASSET_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})$`, "i");
 const ASSET_PATH_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})(?:\?.*)?$`, "i");
 
-export { ASSET_EXTENSIONS, ASSET_RE, ASSET_PATH_RE };
+export { ASSET_RE, ASSET_PATH_RE };

package/src/vite-plugins/built-url.ts

@@ -1,4 +1,20 @@
 import type { Plugin } from "vite";
+import { posix } from "node:path";
+
+const EXECUTABLE_URL_BASE = "`file://${process.execPath}`";
+const LEADING_SLASHES = /^\/+/;
+
+const executableRelativeUrl = (target: string): string => {
+    const specifier = JSON.stringify(target.replace(LEADING_SLASHES, "./"));
+
+    return `decodeURIComponent(new URL(${specifier}, ${EXECUTABLE_URL_BASE}).pathname)`;
+};
+
+const bundleRelativeUrl = (filename: string): string => {
+    const specifier = JSON.stringify(`./${filename}`);
+
+    return `decodeURIComponent(new URL(${specifier}, import.meta.url).pathname)`;
+};
 
 const renderAssetUrl = (
     filename: string,
@@ -9,21 +25,11 @@ const renderAssetUrl = (
         return undefined;
     }
 
-    if (assetBase) {
-        const executableDir = "require(\"path\").dirname(process.execPath)";
-
-        return {
-            runtime:
-                `require("path").join(${executableDir},` +
-                `${JSON.stringify(assetBase)},${JSON.stringify(filename)})`,
-        };
+    if (assetBase === undefined) {
+        return { runtime: bundleRelativeUrl(filename) };
     }
 
-    const filenameLiteral = JSON.stringify(`./${filename}`);
-
-    return {
-        runtime: `new URL(${filenameLiteral}, import.meta.url).pathname`,
-    };
+    return { runtime: executableRelativeUrl(posix.join(assetBase, filename)) };
 };
 
 function gtkxBuiltUrl(assetBase?: string): Plugin {

package/src/vite-plugins/ensure-store.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from "vite";
+import { ensureGenerated } from "../codegen/run-codegen.js";
+
+const TEST_MODE = "test";
+
+const gtkxEnsureStore = (): Plugin => ({
+    name: "gtkx:ensure-store",
+
+    async config() {
+        await ensureGenerated(process.cwd(), { shouldAnnounce: true, mode: TEST_MODE });
+    },
+});
+
+export { gtkxEnsureStore };

package/src/vite-plugins/icons.ts

@@ -2,6 +2,7 @@ import type { Plugin, UserConfig } from "vite";
 import { info } from "@gtkx/utils";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import type { AssetEmitter } from "./asset-emitter.js";
 import { prependBanner } from "../internal/banner.js";
 import { resolveDataDir } from "../internal/data-dir.js";
 import { type ListedFile, listFilesRecursive } from "../internal/list-files.js";
@@ -10,10 +11,6 @@ type PluginState = {
     iconsDir: string | null;
 };
 
-type PluginContext = {
-    emitFile: (file: { type: "asset"; fileName: string; source: Buffer }) => void;
-};
-
 const ICONS_DIR = "icons";
 
 const XDG_ENV_BANNER = [
@@ -33,7 +30,7 @@ const resolveIconsDir = (config: UserConfig): string | null => {
     return dataDir === null ? null : join(root, dataDir, ICONS_DIR);
 };
 
-const emitIcons = (ctx: PluginContext, icons: ListedFile[]): void => {
+const emitIcons = (ctx: AssetEmitter, icons: ListedFile[]): void => {
     for (const { absPath, rel } of icons) {
         ctx.emitFile({ type: "asset", fileName: join(ICONS_DIR, rel), source: readFileSync(absPath) });
     }

package/src/vite-plugins/react-compiler.ts

@@ -1,8 +1,9 @@
-import type { ResolvedReactCompilerOptions } from "@gtkx/config";
+import type { ConfigLoader } from "@gtkx/config";
+import type { ResolvedReactCompilerOptions } from "@gtkx/config/internal";
 import type { Plugin, ResolvedConfig, UserConfig } from "vite";
 import { transformAsync } from "@babel/core";
 import babelPresetTypescriptNs from "@babel/preset-typescript";
-import { type ConfigLoader, createConfigLoader } from "@gtkx/config/internal";
+import { createConfigLoader } from "@gtkx/config/internal";
 import babelPluginReactCompilerNs from "babel-plugin-react-compiler";
 
 type ReactCompilerState = {

package/src/vite-plugins/resources.ts

@@ -1,13 +1,14 @@
+import type { ConfigLoader } from "@gtkx/config";
 import type { Plugin, ResolvedConfig, UserConfig, ViteDevServer } from "vite";
-import { type ConfigLoader, createConfigLoader } from "@gtkx/config/internal";
-import { error, formatChildProcessError, info, sortStrings } from "@gtkx/utils";
-import { execFileSync } from "node:child_process";
+import { createConfigLoader } from "@gtkx/config/internal";
+import { error, info, sortStrings } from "@gtkx/utils";
 import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import type { AssetEmitter } from "./asset-emitter.js";
 import { DATA_IMPORT_PREFIX, resolveDataDir } from "../internal/data-dir.js";
 import { type ListedFile, listFilesRecursive } from "../internal/list-files.js";
-import { resolveCliTool } from "../internal/resolve-cli-tool.js";
+import { runCliTool } from "../internal/run-cli-tool.js";
 import { withStagingDir } from "../internal/staging-dir.js";
 import { ASSET_PATH_RE, ASSET_RE } from "./asset-extensions.js";
 import { renderInitModule } from "./resource-init-module.js";
@@ -83,17 +84,10 @@ const stageBundle = (dir: string, entries: Map<string, ResourceEntry>): string =
 };
 
 const runCompiler = (sourceDir: string, manifest: string, outputPath: string): Buffer => {
-    try {
-        execFileSync(resolveCliTool(RESOURCE_COMPILER), [
-            `--sourcedir=${sourceDir}`,
-            `--target=${outputPath}`,
-            manifest,
-        ]);
-    } catch (error) {
-        const details = formatChildProcessError(error);
-        const suffix = details ? `:\n${details}` : "";
-        throw new Error(`${RESOURCE_COMPILER} failed${suffix}`, { cause: error });
-    }
+    runCliTool({
+        tool: RESOURCE_COMPILER,
+        args: [`--sourcedir=${sourceDir}`, `--target=${outputPath}`, manifest],
+    });
 
     return readFileSync(outputPath);
 };
@@ -229,10 +223,7 @@ const loadAssetModule = (state: PluginState, virtualId: string): string => {
     ].join("\n");
 };
 
-const emitBuildBundle = (
-    ctx: { emitFile: (asset: { type: "asset"; fileName: string; source: Buffer }) => string },
-    state: PluginState,
-): void => {
+const emitBuildBundle = (ctx: AssetEmitter, state: PluginState): void => {
     if (!state.isBuild || state.entries.size === 0) {
         return;
     }

package/src/vite-plugins/settings.ts

@@ -3,6 +3,7 @@ import { error, errorMessage, info } from "@gtkx/utils";
 import { mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
+import type { AssetEmitter } from "./asset-emitter.js";
 import { prependBanner } from "../internal/banner.js";
 import { resolveDataDir } from "../internal/data-dir.js";
 import { removeTempDir, withStagingDir } from "../internal/staging-dir.js";
@@ -22,9 +23,8 @@ type PluginState = {
     cleanupProcessExit: (() => void) | null;
 };
 
-type PluginContext = {
+type PluginContext = AssetEmitter & {
     error: (message: string) => never;
-    emitFile: (file: { type: "asset"; fileName: string; source: Buffer }) => void;
 };
 
 const VIRTUAL_PREFIX = "\0gtkx-settings:";

package/src/vite-plugins/undeclared-library.ts

@@ -1,4 +1,4 @@
-import type { ConfigLoader } from "@gtkx/config/internal";
+import type { ConfigLoader } from "@gtkx/config";
 import type { Plugin, UserConfig } from "vite";
 import { discoverGirNamespaces, resolveGirPath } from "@gtkx/codegen";
 import { createConfigLoader } from "@gtkx/config/internal";