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

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

package/src/dev/supervisor.ts

@@ -1,16 +1,10 @@
+import { error, exitCodeForSignal, info, installGracefulShutdown } from "@gtkx/utils";
 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 { error, exitCodeForSignal, info, installGracefulShutdown } from "@gtkx/utils";
-
-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;
-
-export const RESTART_EXIT_CODE = 75;
 
-export type SupervisedChild = {
+type SupervisedChild = {
     killed: boolean;
     pid?: number | undefined;
     exitCode: number | null;
@@ -19,12 +13,9 @@ export type SupervisedChild = {
     once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
 };
 
-export type ForkRunner = (modulePath: string, args: string[], cwd: string) => SupervisedChild;
+type ForkRunner = (modulePath: string, args: string[], cwd: string) => SupervisedChild;
 
-export const defaultForkRunner: ForkRunner = (modulePath, args, cwd) =>
-    nodeFork(modulePath, [...args], { cwd, stdio: "inherit", detached: true });
-
-export type DevWatch = {
+type DevWatch = {
     paths: string[];
     regenerate: () => Promise<void>;
 };
@@ -42,116 +33,221 @@ type SupervisorState = {
     capturedChildExit: number | 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 defaultForkRunner: ForkRunner = (modulePath, args, cwd) =>
+    nodeFork(modulePath, [...args], { cwd, stdio: "inherit", detached: true });
+
 const forwardSignal = (child: SupervisedChild, signal: NodeJS.Signals): void => {
     if (!child.killed) {
         child.kill(signal);
     }
 };
 
-const forceKillChild = (child: SupervisedChild | null): void => {
-    if (!child?.pid || child.exitCode !== null || child.killed) return;
+const didForceKillChild = (child: SupervisedChild | null): boolean => {
+    if (!child?.pid || child.exitCode !== null || child.killed) {
+        return false;
+    }
+
     try {
-        process.kill(child.pid, "SIGKILL");
-    } catch {}
+        return process.kill(child.pid, "SIGKILL");
+    } catch {
+        return false;
+    }
+};
+
+const captureShutdownExit = (state: SupervisorState, code: number | null, signal: NodeJS.Signals | null): void => {
+    if (code !== null) {
+        state.capturedChildExit = code;
+    } else if (signal) {
+        state.capturedChildExit = exitCodeForSignal(signal);
+    }
+};
+
+const handleChildExit = (state: SupervisorState, code: number | null, signal: NodeJS.Signals | null): void => {
+    state.child = null;
+
+    if (state.restarting) {
+        return;
+    }
+
+    if (state.shuttingDown) {
+        captureShutdownExit(state, code, signal);
+
+        return;
+    }
+
+    if (code === RESTART_EXIT_CODE) {
+        info("Restarting dev runner...");
+        launch(state);
+
+        return;
+    }
+
+    process.exit(code ?? exitCodeForSignal(signal));
 };
 
 const launch = (state: SupervisorState): void => {
     const child = state.fork(state.runnerPath, [state.entryPath], state.cwd);
     state.child = child;
+
     child.on("exit", (code, signal) => {
-        state.child = null;
-        if (state.restarting) return;
-        if (state.shuttingDown) {
-            if (code !== null) {
-                state.capturedChildExit = code;
-            } else if (signal) {
-                state.capturedChildExit = exitCodeForSignal(signal);
-            }
-            return;
-        }
-        if (code === RESTART_EXIT_CODE) {
-            info("Restarting dev runner...");
-            launch(state);
-            return;
-        }
-        process.exit(code ?? exitCodeForSignal(signal));
+        handleChildExit(state, code, signal);
     });
 };
 
+const isRestartBlocked = (state: SupervisorState): boolean => state.restarting || state.shuttingDown;
+
+const relaunchAfterExit = (state: SupervisorState): void => {
+    state.restarting = false;
+
+    if (state.shuttingDown) {
+        return;
+    }
+
+    info("Restarting dev runner...");
+    launch(state);
+};
+
 const restart = async (state: SupervisorState): Promise<void> => {
-    if (state.restarting || state.shuttingDown || state.watch === undefined) return;
+    const watch = state.watch;
+
+    if (watch === undefined || isRestartBlocked(state)) {
+        return;
+    }
+
     state.restarting = true;
     info("gtkx.config.ts changed; regenerating bindings...");
+
     try {
-        await state.watch.regenerate();
-    } catch (cause) {
-        error("Codegen failed; keeping the current dev runner. Fix the error and save again.", cause);
+        await watch.regenerate();
+    } catch (error_) {
+        error("Codegen failed; keeping the current dev runner. Fix the error and save again.", error_);
         state.restarting = false;
+
         return;
     }
+
     if (state.shuttingDown) {
         state.restarting = false;
+
         return;
     }
+
     const current = state.child;
+
     if (current === null) {
         state.restarting = false;
         launch(state);
+
         return;
     }
+
     current.once("exit", () => {
-        state.restarting = false;
-        if (!state.shuttingDown) {
-            info("Restarting dev runner...");
-            launch(state);
-        }
+        relaunchAfterExit(state);
     });
+
     forwardSignal(current, "SIGTERM");
 };
 
-const installConfigWatchers = (state: SupervisorState): void => {
-    const watch = state.watch;
-    if (watch === undefined || watch.paths.length === 0) return;
-    let timer: NodeJS.Timeout | null = null;
-    const namesByDirectory = new Map<string, Set<string>>();
-    for (const path of watch.paths) {
+const scheduleRestart = (state: SupervisorState, timer: DebounceTimer): void => {
+    if (timer.handle !== null) {
+        clearTimeout(timer.handle);
+    }
+
+    timer.handle = setTimeout(() => void restart(state), CONFIG_DEBOUNCE_MS);
+};
+
+const isWatchedChange = (state: SupervisorState, names: Set<string>, filename: string | Buffer | null): boolean => {
+    if (filename === null || state.shuttingDown) {
+        return false;
+    }
+
+    return names.has(basename(filename.toString()));
+};
+
+const groupWatchNamesByDirectory = (paths: string[]): Map<string, Set<string>> => {
+    const namesByDirectory: Map<string, Set<string>> = new Map();
+
+    for (const path of paths) {
         const directory = dirname(path);
         const names = namesByDirectory.get(directory) ?? new Set<string>();
         names.add(basename(path));
         namesByDirectory.set(directory, names);
     }
-    for (const [directory, names] of namesByDirectory) {
-        const watcher = watchFs(directory, (_event, filename) => {
-            if (state.shuttingDown) return;
-            if (filename === null || !names.has(basename(filename.toString()))) return;
-            if (timer !== null) clearTimeout(timer);
-            timer = setTimeout(() => void restart(state), CONFIG_DEBOUNCE_MS);
-        });
-        watcher.on("error", () => {});
-        state.watchers.push(watcher);
+
+    return namesByDirectory;
+};
+
+const watchConfigDirectory = (
+    state: SupervisorState,
+    directory: string,
+    names: Set<string>,
+    timer: DebounceTimer,
+): void => {
+    const watcher = watchFs(directory, (_event, filename) => {
+        if (isWatchedChange(state, names, filename)) {
+            scheduleRestart(state, timer);
+        }
+    });
+
+    watcher.on("error", (): void => undefined);
+    state.watchers.push(watcher);
+};
+
+const installConfigWatchers = (state: SupervisorState): void => {
+    const watch = state.watch;
+
+    if (watch === undefined || watch.paths.length === 0) {
+        return;
+    }
+
+    const timer: DebounceTimer = { handle: null };
+
+    for (const [directory, names] of groupWatchNamesByDirectory(watch.paths)) {
+        watchConfigDirectory(state, directory, names, timer);
     }
 };
 
+const closeWatchers = (state: SupervisorState): void => {
+    for (const watcher of state.watchers) {
+        watcher.close();
+    }
+};
+
+const shutdownOnSignal = (state: SupervisorState, signal: NodeJS.Signals): Promise<void> =>
+    new Promise<void>((resolve) => {
+        state.shuttingDown = true;
+        closeWatchers(state);
+
+        if (!state.child) {
+            resolve();
+
+            return;
+        }
+
+        state.child.once("exit", () => {
+            resolve();
+        });
+
+        forwardSignal(state.child, signal);
+    });
+
 const installShutdown = (state: SupervisorState): void => {
     installGracefulShutdown({
-        onSignal: (signal) =>
-            new Promise<void>((resolve) => {
-                state.shuttingDown = true;
-                for (const watcher of state.watchers) watcher.close();
-                if (!state.child) {
-                    resolve();
-                    return;
-                }
-                state.child.once("exit", () => resolve());
-                forwardSignal(state.child, signal);
-            }),
-        onForce: () => forceKillChild(state.child),
+        onSignal: (signal) => shutdownOnSignal(state, signal),
+        onForce: () => didForceKillChild(state.child),
         forceKillAfterMs: FORCE_KILL_TIMEOUT_MS,
         exitCode: (signal, graceful) => state.capturedChildExit ?? (graceful ? 0 : exitCodeForSignal(signal)),
     });
 };
 
-export const runDevSupervisor = async (
+const runDevSupervisor = async (
     entryPath: string,
     cwd: string,
     watch?: DevWatch,
@@ -174,5 +270,7 @@ export const runDevSupervisor = async (
     installShutdown(state);
     launch(state);
 
-    return new Promise<never>(() => {});
+    return new Promise<never>((): void => undefined);
 };
+
+export { RESTART_EXIT_CODE, defaultForkRunner, runDevSupervisor, type SupervisedChild, type ForkRunner, type DevWatch };

package/src/dev/vite-dev-server.ts

@@ -12,7 +12,7 @@ type DevServerModuleGraph = {
     invalidateModule(module: DevServerModule): void;
 };
 
-export type DevServer = {
+type DevServer = {
     close(): Promise<void>;
     moduleGraph: DevServerModuleGraph;
     ssrLoadModule(id: string): Promise<Record<string, unknown>>;
@@ -21,7 +21,7 @@ export type DevServer = {
     };
 };
 
-export const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig => ({
+const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig => ({
     root,
     appType: "custom",
     plugins,
@@ -32,3 +32,5 @@ export const createDevServerConfig = (root: string, plugins: Plugin[]): InlineCo
         noExternal: [/^@gtkx\/(?!(?:native|gi|gl|runtime|utils|css)(?:\/|$))/, /[/\\]\.gtkx[/\\]/],
     },
 });
+
+export { createDevServerConfig, type DevServer };