@gtkx/cli 0.21.0 → 1.0.0-rc.1

package/src/dev/refresh-tracker.ts

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

package/src/dev/runner-deps.ts

@@ -0,0 +1,42 @@
+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 { 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";
+
+export const defaultDevRunnerDeps = (): DevRunnerDeps => ({
+    createServer,
+    getApplicationId: () => Gio.Application.getDefault()?.applicationId ?? null,
+    getConfiguredApplicationId: async (root: string) =>
+        (await loadConfig(root, { mode: DEV_MODE })).config.applicationId,
+    startMcpClient: (applicationId, loadAppModule) => {
+        setTestingModuleLoader(() => loadAppModule("@gtkx/testing") as Promise<typeof import("@gtkx/testing")>);
+        return startMcpClient(applicationId);
+    },
+    stopMcpClient,
+    watchApplicationShutdown: (onShutdown) => {
+        Gio.Application.getDefault()?.on("shutdown", onShutdown);
+    },
+    installShutdownHandlers: (onSignal) => {
+        installGracefulShutdown({ onSignal });
+    },
+    quitDefaultApplication: () => {
+        const application = Gio.Application.getDefault();
+        if (application) quitApplication(application as Gtk.Application);
+    },
+    performRefresh,
+    isRefreshBoundary,
+    plugins: () => [...gtkxVitePlugins(DEV_MODE), ...gtkxFastRefresh(), gtkxReactDomPrebundle()],
+    log: info,
+    exit: (code: number): never => process.exit(code),
+});

package/src/dev/runner-main.ts

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { error } from "@gtkx/utils";
+import { resolveDataDir } from "../internal/data-dir.js";
+import { prepareDevIconDir } from "./icon-dir.js";
+import { createDevRunner } from "./runner.js";
+import { prepareDevSchemaDir } from "./schema-dir.js";
+
+const ENTRY_ARG_INDEX = 2;
+
+export const main = async (): Promise<void> => {
+    if (process.channel) {
+        process.once("disconnect", () => {
+            process.exit(0);
+        });
+    }
+
+    const cwd = process.cwd();
+    const entryArg = process.argv[ENTRY_ARG_INDEX];
+
+    if (!entryArg) {
+        error("Missing entry argument");
+        process.exit(1);
+    }
+
+    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);
+};

package/src/dev/runner.ts

@@ -0,0 +1,126 @@
+import { error } from "@gtkx/utils";
+import type { InlineConfig, Plugin } from "vite";
+import { createRefreshTracker } 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 = {
+    createServer(config: InlineConfig): Promise<DevServer>;
+    getApplicationId(): string | null;
+    getConfiguredApplicationId(root: string): Promise<string | undefined>;
+    startMcpClient(
+        applicationId: string,
+        loadAppModule: (id: string) => Promise<Record<string, unknown>>,
+    ): Promise<unknown>;
+    stopMcpClient(): void;
+    watchApplicationShutdown(onShutdown: () => void): void;
+    installShutdownHandlers(onSignal: () => void | Promise<void>): void;
+    quitDefaultApplication(): void;
+    performRefresh(): void;
+    isRefreshBoundary(module: Record<string, unknown>): boolean;
+    plugins(): Plugin[];
+    log(message: string): void;
+    exit(code: number): never;
+};
+
+type DevRunner = {
+    run(entryPath: string): Promise<void>;
+};
+
+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}`);
+
+    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 refreshTracker = createRefreshTracker(deps.performRefresh);
+        const refreshTrackingDeps: DevRunnerDeps = { ...deps, performRefresh: refreshTracker.performRefresh };
+
+        let isShuttingDown = false;
+        const shutdown = async (quitApplication: () => void): Promise<void> => {
+            if (isShuttingDown) return;
+            isShuttingDown = true;
+            quitApplication();
+            deps.stopMcpClient();
+            await server.close();
+        };
+
+        deps.installShutdownHandlers(async () => {
+            if (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);
+            });
+        });
+
+        deps.log(`Loading entry: ${entryPath}`);
+        await server.ssrLoadModule(entryPath);
+
+        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();
+        if (liveApplicationId) {
+            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.");
+        }
+
+        deps.log("HMR enabled - watching for changes...");
+    },
+});

package/src/dev/schema-dir.ts

@@ -0,0 +1,11 @@
+import { prependSchemaDir, stageAndCompileProjectSchemas } from "../settings/schema.js";
+
+export const prepareDevSchemaDir = (root: string, dataDir: string | null): string | null => {
+    const dir = stageAndCompileProjectSchemas(root, dataDir);
+    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;
+};

package/src/dev/supervisor.ts

@@ -0,0 +1,178 @@
+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 = {
+    killed: boolean;
+    pid?: number | undefined;
+    exitCode: number | null;
+    kill(signal?: number | NodeJS.Signals): boolean;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+};
+
+export 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 = {
+    paths: string[];
+    regenerate: () => Promise<void>;
+};
+
+type SupervisorState = {
+    runnerPath: string;
+    entryPath: string;
+    cwd: string;
+    watch: DevWatch | undefined;
+    watchers: FSWatcher[];
+    fork: ForkRunner;
+    child: SupervisedChild | null;
+    shuttingDown: boolean;
+    restarting: boolean;
+    capturedChildExit: number | undefined;
+};
+
+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;
+    try {
+        process.kill(child.pid, "SIGKILL");
+    } catch {}
+};
+
+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));
+    });
+};
+
+const restart = async (state: SupervisorState): Promise<void> => {
+    if (state.restarting || state.shuttingDown || state.watch === undefined) 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);
+        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);
+        }
+    });
+    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 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);
+    }
+};
+
+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),
+        forceKillAfterMs: FORCE_KILL_TIMEOUT_MS,
+        exitCode: (signal, graceful) => state.capturedChildExit ?? (graceful ? 0 : exitCodeForSignal(signal)),
+    });
+};
+
+export const runDevSupervisor = async (
+    entryPath: string,
+    cwd: string,
+    watch?: DevWatch,
+    fork: ForkRunner = defaultForkRunner,
+): Promise<never> => {
+    const state: SupervisorState = {
+        runnerPath: fileURLToPath(DEV_RUNNER_URL),
+        entryPath,
+        cwd,
+        watch,
+        watchers: [],
+        fork,
+        child: null,
+        shuttingDown: false,
+        restarting: false,
+        capturedChildExit: undefined,
+    };
+
+    installConfigWatchers(state);
+    installShutdown(state);
+    launch(state);
+
+    return new Promise<never>(() => {});
+};

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

@@ -0,0 +1,34 @@
+import type { InlineConfig, Plugin } from "vite";
+
+type DevServerModule = object;
+
+type DevServerChangedModule = DevServerModule & {
+    importers: Iterable<DevServerModule>;
+    ssrModule?: Record<string, unknown> | null;
+};
+
+type DevServerModuleGraph = {
+    getModuleById(id: string): DevServerChangedModule | undefined;
+    invalidateModule(module: DevServerModule): void;
+};
+
+export type DevServer = {
+    close(): Promise<void>;
+    moduleGraph: DevServerModuleGraph;
+    ssrLoadModule(id: string): Promise<Record<string, unknown>>;
+    watcher: {
+        on(event: "change", listener: (changedPath: string) => void): void;
+    };
+};
+
+export const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig => ({
+    root,
+    appType: "custom",
+    plugins,
+    server: { middlewareMode: true },
+    optimizeDeps: { noDiscovery: true, include: [] },
+    ssr: {
+        external: true,
+        noExternal: [/^@gtkx\/(?!(?:native|gi|gl|runtime|utils|css)(?:\/|$))/, /[/\\]\.gtkx[/\\]/],
+    },
+});

package/src/internal/banner.ts

@@ -0,0 +1,9 @@
+import type { Rollup } from "vite";
+
+export const prependBanner = (options: Rollup.OutputOptions, banner: string): Rollup.OutputOptions => {
+    const existing = options.banner;
+    if (typeof existing === "function") {
+        return { ...options, banner: async (chunk) => `${banner}\n${await existing(chunk)}` };
+    }
+    return { ...options, banner: existing ? `${banner}\n${existing}` : banner };
+};

package/src/internal/data-dir.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const DATA_IMPORT_PREFIX = "#data";
+
+const DATA_IMPORT_KEY: string = `${DATA_IMPORT_PREFIX}/*`;
+
+const CONDITION_PRIORITY = ["default", "import", "node"] as const;
+
+const targetString = (entry: unknown): string | null => {
+    if (typeof entry === "string") return entry;
+    if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+        const conditions = entry as Record<string, unknown>;
+        for (const condition of CONDITION_PRIORITY) {
+            const value = conditions[condition];
+            if (typeof value === "string") return value;
+        }
+    }
+    return null;
+};
+
+const DATA_TARGET_PATTERN = /^\.?\/?(.+?)\/\*$/;
+
+const directoryFromTarget = (target: string): string | null => {
+    const match = DATA_TARGET_PATTERN.exec(target);
+    return match?.[1] ?? null;
+};
+
+export const resolveDataDir = (root: string): string | null => {
+    let manifest: { imports?: Record<string, unknown> };
+    try {
+        manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+    } catch {
+        return null;
+    }
+    const target = targetString(manifest.imports?.[DATA_IMPORT_KEY]);
+    if (target === null) return null;
+    return directoryFromTarget(target);
+};

package/src/internal/entry-arg.ts

@@ -0,0 +1,38 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { PositionalArgDef, StringArgDef } from "citty";
+
+const DEFAULT_ENTRY_BASE = "src/index";
+const DEFAULT_ENTRY_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js"];
+const DEFAULT_ENTRY = `${DEFAULT_ENTRY_BASE}{${DEFAULT_ENTRY_EXTENSIONS.join(",")}}`;
+
+export const cwdArg: { cwd: StringArgDef } = {
+    cwd: {
+        type: "string",
+        description: "Project root (default: current working directory)",
+    },
+};
+
+export const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
+    entry: {
+        type: "positional",
+        description: `Entry file (default: ${DEFAULT_ENTRY})`,
+        required: false,
+    },
+    ...cwdArg,
+};
+
+export const resolveCwd = (args: { cwd?: string }): string => (args.cwd ? resolve(args.cwd) : process.cwd());
+
+const resolveDefaultEntry = (cwd: string): string => {
+    for (const extension of DEFAULT_ENTRY_EXTENSIONS) {
+        const candidate = resolve(cwd, `${DEFAULT_ENTRY_BASE}${extension}`);
+        if (existsSync(candidate)) return candidate;
+    }
+    return resolve(cwd, `${DEFAULT_ENTRY_BASE}${DEFAULT_ENTRY_EXTENSIONS[0]}`);
+};
+
+export const resolveEntry = (args: { entry?: string; cwd?: string }): { cwd: string; entry: string } => {
+    const cwd = resolveCwd(args);
+    return { cwd, entry: args.entry ? resolve(cwd, args.entry) : resolveDefaultEntry(cwd) };
+};

package/src/internal/errors.ts

@@ -0,0 +1,28 @@
+import { logger } from "@gtkx/utils";
+import type { ArgsDef, CommandDef } from "citty";
+
+const ERROR_EXIT_CODE = 1;
+
+export const printError = (cause: unknown): never => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    logger.error(message);
+    if (cause instanceof Error && cause.stack !== undefined) {
+        logger.debug(cause.stack);
+    }
+    process.exit(ERROR_EXIT_CODE);
+};
+
+export const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDef<T> => {
+    const run = command.run;
+    if (run === undefined) return command;
+    return {
+        ...command,
+        run: async (context) => {
+            try {
+                return await run(context);
+            } catch (cause) {
+                printError(cause);
+            }
+        },
+    };
+};

package/src/internal/list-files.ts

@@ -0,0 +1,17 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export type ListedFile = {
+    absPath: string;
+    rel: string;
+};
+
+export const listFilesRecursive = (dir: string, predicate?: (name: string) => boolean): ListedFile[] => {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && (predicate === undefined || predicate(entry.name)))
+        .map((entry) => {
+            const absPath = join(entry.parentPath, entry.name);
+            return { absPath, rel: relative(dir, absPath) };
+        });
+};

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

@@ -0,0 +1,21 @@
+import { existsSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export const resolveCliTool = (() => {
+    const cache = new Map<string, string>();
+
+    return (executable: string): string => {
+        const cached = cache.get(executable);
+        if (cached) return cached;
+
+        const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+        for (const dir of dirs) {
+            const candidate = join(dir, executable);
+            if (existsSync(candidate) && statSync(candidate).isFile()) {
+                cache.set(executable, candidate);
+                return candidate;
+            }
+        }
+        throw new Error(`${executable} not found in PATH`);
+    };
+})();

package/src/internal/staging-dir.ts

@@ -0,0 +1,16 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const removeTempDir = (dir: string): void => {
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5 });
+};
+
+export const withStagingDir = <T>(prefix: string, produce: (dir: string) => T): T => {
+    const dir = mkdtempSync(join(tmpdir(), `gtkx-${prefix}-`));
+    try {
+        return produce(dir);
+    } finally {
+        removeTempDir(dir);
+    }
+};

package/src/internal/xdg-data-dirs.ts

@@ -0,0 +1,7 @@
+const XDG_DATA_DIRS_DEFAULT = "/usr/local/share:/usr/share";
+
+export const prependXdgDataDir = (dir: string, existing: string | undefined): string => {
+    const base = existing === undefined || existing.length === 0 ? XDG_DATA_DIRS_DEFAULT : existing;
+    if (base.split(":").includes(dir)) return base;
+    return `${dir}:${base}`;
+};