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

package/src/commands/docs.ts

@@ -1,11 +1,22 @@
-import { resolve } from "node:path";
-import { resolveGirPath, resolveLibraries, writeDocs } from "@gtkx/codegen";
+import {
+    type ElementProps,
+    mergeOmitProps,
+    type OmittedProps,
+    readBuiltinElements,
+    resolveGirPath,
+    resolveLibraries,
+    writeDocs,
+} from "@gtkx/codegen";
 import { loadConfig } from "@gtkx/config";
+import { resolveOmitProps } from "@gtkx/config/internal";
 import { info } from "@gtkx/utils";
 import { defineCommand } from "citty";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveReactSubexports } from "../codegen/store-resolver.js";
 import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
 
-export const docs = defineCommand({
+const docs = defineCommand({
     meta: {
         name: "docs",
         description:
@@ -32,35 +43,64 @@ export const docs = defineCommand({
     async run({ args }) {
         const cwd = resolveCwd(args);
         const { config } = await loadConfig(cwd);
+
         if (config.codegen === false) {
             throw new Error(
-                "codegen is disabled for this project, so there are no GIR libraries to document. Remove `codegen: false` from gtkx.config.ts to use `gtkx docs`.",
+                "codegen is disabled for this project, so there are no GIR libraries to document. " +
+                "Remove `codegen: false` from gtkx.config.ts to use `gtkx docs`.",
             );
         }
+
         const girPath = resolveGirPath(config.girPath);
+
         if (girPath.length === 0) {
             throw new Error(
-                "No GIR search paths available. Install gobject-introspection (Linux: `sudo dnf install gobject-introspection-devel` or `sudo apt install libgirepository1.0-dev`), or set `girPath` in gtkx.config.ts.",
+                "No GIR search paths available. Install gobject-introspection " +
+                "(Linux: `sudo dnf install gobject-introspection-devel` or " +
+                "`sudo apt install libgirepository1.0-dev`), or set `girPath` in gtkx.config.ts.",
             );
         }
+
         const libraries = resolveLibraries(config.libraries, girPath);
         const startedAt = Date.now();
         const outDir = resolve(cwd, args.out);
+        const builtin = await resolveDocsElements(cwd);
+
         const { regenerated, namespaces } = writeDocs({
             libraries,
             girPath,
             outDir,
             basePath: args["base-path"],
-            elementProps: config.elementProps ?? {},
+            props: builtin.props,
+            omitProps: mergeOmitProps(builtin.omitProps, resolveOmitProps(config.elements)),
             force: args.force,
         });
+
         if (!regenerated) {
             info(`docs: pages in ${outDir} are up to date`);
+
             return;
         }
+
         const count = namespaces.reduce((total, namespace) => total + namespace.elements.length, 0);
+
         info(
-            `docs: wrote ${count} element pages across ${namespaces.length} namespaces to ${outDir} in ${Date.now() - startedAt}ms`,
+            `docs: wrote ${String(count)} element pages across ${String(namespaces.length)} namespaces ` +
+            `to ${outDir} in ${String(Date.now() - startedAt)}ms`,
         );
     },
 });
+
+const resolveDocsElements = async (cwd: string): Promise<{ props: ElementProps; omitProps: OmittedProps }> => {
+    const giStoreDir = join(cwd, "node_modules", ".gtkx", "gi");
+
+    if (!existsSync(giStoreDir)) {
+        return { props: {}, omitProps: {} };
+    }
+
+    const { props, omitProps } = await readBuiltinElements(resolveReactSubexports(cwd), giStoreDir);
+
+    return { props, omitProps };
+};
+
+export { docs };

package/src/dev/icon-dir.ts

@@ -2,10 +2,20 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { prependXdgDataDir } from "../internal/xdg-data-dirs.js";
 
-export const prepareDevIconDir = (root: string, dataDir: string | null): string | null => {
-    if (dataDir === null) return null;
+const prepareDevIconDir = (root: string, dataDir: string | null): string | null => {
+    if (dataDir === null) {
+        return null;
+    }
+
     const shareDir = join(root, dataDir);
-    if (!existsSync(join(shareDir, "icons"))) return null;
+
+    if (!existsSync(join(shareDir, "icons"))) {
+        return null;
+    }
+
     process.env.XDG_DATA_DIRS = prependXdgDataDir(shareDir, process.env.XDG_DATA_DIRS);
+
     return shareDir;
 };
+
+export { prepareDevIconDir };

package/src/dev/refresh-tracker.ts

@@ -1,21 +1,25 @@
-export type RefreshTracker = {
-    performRefresh(): void;
-    isRefreshing(): boolean;
+type RefreshTracker = {
+    performRefresh: () => void;
+    isRefreshing: () => boolean;
 };
 
-export const createRefreshTracker = (performRefresh: () => void): RefreshTracker => {
-    let refreshing = false;
+const createRefreshTracker = (performRefresh: () => void): RefreshTracker => {
+    let isRefreshing = false;
+
     return {
         performRefresh: () => {
-            refreshing = true;
+            isRefreshing = true;
+
             try {
                 performRefresh();
             } finally {
                 setTimeout(() => {
-                    refreshing = false;
+                    isRefreshing = false;
                 }, 0);
             }
         },
-        isRefreshing: () => refreshing,
+        isRefreshing: () => isRefreshing,
     };
 };
+
+export { createRefreshTracker, type RefreshTracker };

package/src/dev/runner-deps.ts

@@ -1,26 +1,44 @@
 import { loadConfig } from "@gtkx/config";
 import * as Gio from "@gtkx/gi/gio";
-import type * as Gtk from "@gtkx/gi/gtk";
 import { quitApplication } from "@gtkx/runtime";
 import { info, installGracefulShutdown } from "@gtkx/utils";
 import { createServer } from "vite";
+import type { DevRunnerDeps } from "./runner.js";
 import { startMcpClient, stopMcpClient } from "../mcp/index.js";
 import { setTestingModuleLoader } from "../mcp/testing-loader.js";
 import { isRefreshBoundary, performRefresh } from "../refresh-runtime.js";
 import { gtkxFastRefresh } from "../vite-plugins/fast-refresh/swc-refresh.js";
 import { gtkxVitePlugins } from "../vite-plugins/index.js";
 import { gtkxReactDomPrebundle } from "../vite-plugins/react-dom-prebundle.js";
-import type { DevRunnerDeps } from "./runner.js";
 
 const DEV_MODE = "development";
+const APPLICATION_POLL_INTERVAL_MS = 50;
+
+const currentApplicationId = (): string | null => Gio.Application.getDefault()?.applicationId ?? null;
+
+const waitForApplicationId = async (timeoutMs: number): Promise<string | null> => {
+    const deadline = Date.now() + timeoutMs;
+    let applicationId = currentApplicationId();
+
+    while (applicationId === null && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, APPLICATION_POLL_INTERVAL_MS));
+        applicationId = currentApplicationId();
+    }
+
+    return applicationId;
+};
 
-export const defaultDevRunnerDeps = (): DevRunnerDeps => ({
+const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     createServer,
-    getApplicationId: () => Gio.Application.getDefault()?.applicationId ?? null,
-    getConfiguredApplicationId: async (root: string) =>
-        (await loadConfig(root, { mode: DEV_MODE })).config.applicationId,
+    waitForApplicationId,
+    getConfiguredApplicationId: async (root: string) => {
+        const loaded = await loadConfig(root, { mode: DEV_MODE });
+
+        return loaded.config.applicationId;
+    },
     startMcpClient: (applicationId, loadAppModule) => {
         setTestingModuleLoader(() => loadAppModule("@gtkx/testing") as Promise<typeof import("@gtkx/testing")>);
+
         return startMcpClient(applicationId);
     },
     stopMcpClient,
@@ -32,7 +50,10 @@ export const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     },
     quitDefaultApplication: () => {
         const application = Gio.Application.getDefault();
-        if (application) quitApplication(application as Gtk.Application);
+
+        if (application) {
+            quitApplication(application);
+        }
     },
     performRefresh,
     isRefreshBoundary,
@@ -40,3 +61,5 @@ export const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     log: info,
     exit: (code: number): never => process.exit(code),
 });
+
+export { defaultDevRunnerDeps };

package/src/dev/runner-main.ts

@@ -1,5 +1,5 @@
-import { resolve } from "node:path";
 import { error } from "@gtkx/utils";
+import { resolve } from "node:path";
 import { resolveDataDir } from "../internal/data-dir.js";
 import { prepareDevIconDir } from "./icon-dir.js";
 import { createDevRunner } from "./runner.js";
@@ -7,7 +7,7 @@ import { prepareDevSchemaDir } from "./schema-dir.js";
 
 const ENTRY_ARG_INDEX = 2;
 
-export const main = async (): Promise<void> => {
+const main = async (): Promise<void> => {
     if (process.channel) {
         process.once("disconnect", () => {
             process.exit(0);
@@ -25,9 +25,10 @@ export const main = async (): Promise<void> => {
     const dataDir = resolveDataDir(cwd);
     prepareDevSchemaDir(cwd, dataDir);
     prepareDevIconDir(cwd, dataDir);
-
     const entryPath = resolve(cwd, entryArg);
     const { defaultDevRunnerDeps } = await import("./runner-deps.js");
     const runner = createDevRunner(defaultDevRunnerDeps());
     await runner.run(entryPath);
 };
+
+export { main };

package/src/dev/runner.ts

@@ -1,14 +1,12 @@
-import { error } from "@gtkx/utils";
 import type { InlineConfig, Plugin } from "vite";
-import { createRefreshTracker } from "./refresh-tracker.js";
+import { error } from "@gtkx/utils";
+import { createRefreshTracker, type RefreshTracker } from "./refresh-tracker.js";
 import { RESTART_EXIT_CODE } from "./supervisor.js";
 import { createDevServerConfig, type DevServer } from "./vite-dev-server.js";
 
-export type { DevServer } from "./vite-dev-server.js";
-
-export type DevRunnerDeps = {
+type DevRunnerDeps = {
     createServer(config: InlineConfig): Promise<DevServer>;
-    getApplicationId(): string | null;
+    waitForApplicationId(timeoutMs: number): Promise<string | null>;
     getConfiguredApplicationId(root: string): Promise<string | undefined>;
     startMcpClient(
         applicationId: string,
@@ -18,7 +16,7 @@ export type DevRunnerDeps = {
     watchApplicationShutdown(onShutdown: () => void): void;
     installShutdownHandlers(onSignal: () => void | Promise<void>): void;
     quitDefaultApplication(): void;
-    performRefresh(): void;
+    performRefresh: () => void;
     isRefreshBoundary(module: Record<string, unknown>): boolean;
     plugins(): Plugin[];
     log(message: string): void;
@@ -29,91 +27,149 @@ type DevRunner = {
     run(entryPath: string): Promise<void>;
 };
 
+type ShutdownController = {
+    isShuttingDown: () => boolean;
+    shutdown: (quitApplication: () => void) => Promise<void>;
+};
+
+const APPLICATION_MOUNT_TIMEOUT_MS = 10_000;
+
 const requestRestart = async (server: DevServer, deps: DevRunnerDeps): Promise<never> => {
     deps.log("Full restart (process restart)");
     await server.close();
+
     return deps.exit(RESTART_EXIT_CODE);
 };
 
 const handleFileChange = async (server: DevServer, deps: DevRunnerDeps, changedPath: string): Promise<void> => {
     const module = server.moduleGraph.getModuleById(changedPath);
-    if (!module) return;
 
-    deps.log(`File changed: ${changedPath}`);
+    if (!module) {
+        return;
+    }
 
+    deps.log(`File changed: ${changedPath}`);
     const loadedExports = module.ssrModule;
+
     if (loadedExports && !deps.isRefreshBoundary(loadedExports)) {
         await requestRestart(server, deps);
+
         return;
     }
 
     server.moduleGraph.invalidateModule(module);
+
     for (const importer of module.importers) {
         server.moduleGraph.invalidateModule(importer);
     }
 
     const newMod = await server.ssrLoadModule(changedPath);
+
     if (deps.isRefreshBoundary(newMod)) {
         deps.log("Running Fast Refresh...");
         deps.performRefresh();
         deps.log("Fast Refresh complete");
+
         return;
     }
 
     await requestRestart(server, deps);
 };
 
-export const createDevRunner = (deps: DevRunnerDeps): DevRunner => ({
-    async run(entryPath: string): Promise<void> {
-        const root = process.cwd();
-        const server = await deps.createServer(createDevServerConfig(root, deps.plugins()));
+const createShutdownController = (server: DevServer, deps: DevRunnerDeps): ShutdownController => {
+    let isShuttingDown = false;
 
-        const refreshTracker = createRefreshTracker(deps.performRefresh);
-        const refreshTrackingDeps: DevRunnerDeps = { ...deps, performRefresh: refreshTracker.performRefresh };
+    return {
+        isShuttingDown: () => isShuttingDown,
+        shutdown: async (quitApplication: () => void): Promise<void> => {
+            if (isShuttingDown) {
+                return;
+            }
 
-        let isShuttingDown = false;
-        const shutdown = async (quitApplication: () => void): Promise<void> => {
-            if (isShuttingDown) return;
             isShuttingDown = true;
             quitApplication();
             deps.stopMcpClient();
             await server.close();
+        },
+    };
+};
+
+const reloadChangedFile = async (server: DevServer, deps: DevRunnerDeps, changedPath: string): Promise<void> => {
+    try {
+        await handleFileChange(server, deps, changedPath);
+    } catch (error_) {
+        error("Hot reload failed:", error_);
+    }
+};
+
+const onFileChange =
+    (server: DevServer, deps: DevRunnerDeps, controller: ShutdownController): ((changedPath: string) => void) =>
+        (changedPath) => {
+            if (controller.isShuttingDown()) {
+                return;
+            }
+
+            void reloadChangedFile(server, deps, changedPath);
         };
 
-        deps.installShutdownHandlers(async () => {
-            if (isShuttingDown) return;
+const onShutdownSignal =
+    (deps: DevRunnerDeps, controller: ShutdownController): (() => Promise<void>) =>
+        async () => {
+            if (controller.isShuttingDown()) {
+                return;
+            }
+
             deps.log("Received shutdown signal - stopping dev runner...");
-            await shutdown(() => deps.quitDefaultApplication());
-        });
 
-        server.watcher.on("change", (changedPath) => {
-            if (isShuttingDown) return;
-            handleFileChange(server, refreshTrackingDeps, changedPath).catch((cause) => {
-                error("Hot reload failed:", cause);
+            await controller.shutdown(() => {
+                deps.quitDefaultApplication();
             });
-        });
+        };
 
-        deps.log(`Loading entry: ${entryPath}`);
-        await server.ssrLoadModule(entryPath);
+const closeAndExit = async (deps: DevRunnerDeps, controller: ShutdownController): Promise<never> => {
+    try {
+        await controller.shutdown((): void => undefined);
+    } catch (error_) {
+        error("Error closing server:", error_);
+
+        return deps.exit(1);
+    }
+
+    return deps.exit(0);
+};
+
+const onApplicationShutdown =
+    (deps: DevRunnerDeps, refreshTracker: RefreshTracker, controller: ShutdownController): (() => void) =>
+        () => {
+            if (controller.isShuttingDown()) {
+                return;
+            }
 
-        deps.watchApplicationShutdown(() => {
-            if (isShuttingDown) return;
             if (refreshTracker.isRefreshing()) {
                 deps.log("Application unmounted during Fast Refresh - restarting dev runner...");
+
                 return deps.exit(RESTART_EXIT_CODE);
             }
+
             deps.log("Application quit - stopping dev runner...");
-            shutdown(() => {}).then(
-                () => deps.exit(0),
-                (cause: unknown) => {
-                    error("Error closing server:", cause);
-                    return deps.exit(1);
-                },
-            );
-        });
-
-        const liveApplicationId = deps.getApplicationId();
+            void closeAndExit(deps, controller);
+        };
+
+const createDevRunner = (deps: DevRunnerDeps): DevRunner => ({
+    async run(entryPath: string): Promise<void> {
+        const root = process.cwd();
+        const server = await deps.createServer(createDevServerConfig(root, deps.plugins()));
+        const refreshTracker = createRefreshTracker(deps.performRefresh);
+        const refreshTrackingDeps: DevRunnerDeps = { ...deps, performRefresh: refreshTracker.performRefresh };
+        const controller = createShutdownController(server, deps);
+        deps.installShutdownHandlers(onShutdownSignal(deps, controller));
+        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));
@@ -124,3 +180,6 @@ export const createDevRunner = (deps: DevRunnerDeps): DevRunner => ({
         deps.log("HMR enabled - watching for changes...");
     },
 });
+
+export type { DevServer } from "./vite-dev-server.js";
+export { createDevRunner, type DevRunnerDeps };

package/src/dev/schema-dir.ts

@@ -1,11 +1,16 @@
 import { prependSchemaDir, stageAndCompileProjectSchemas } from "../settings/schema.js";
 
-export const prepareDevSchemaDir = (root: string, dataDir: string | null): string | null => {
+const prepareDevSchemaDir = (root: string, dataDir: string | null): string | null => {
     const dir = stageAndCompileProjectSchemas(root, dataDir);
-    if (dir === null) return null;
+
+    if (dir === null) {
+        return null;
+    }
 
     process.env.GTKX_DEV_SCHEMA_DIR = dir;
     process.env.GSETTINGS_SCHEMA_DIR = prependSchemaDir(dir, process.env.GSETTINGS_SCHEMA_DIR);
 
     return dir;
 };
+
+export { prepareDevSchemaDir };