@gtkx/cli 0.21.0 → 1.0.0-rc.2

package/src/commands/codegen.ts

@@ -0,0 +1,49 @@
+import { info } from "@gtkx/utils";
+import { defineCommand } from "citty";
+import { formatCodegenResult } from "../codegen/report.js";
+import { ensureGenerated, isCodegenDisabled, runCodegen, syncSchemaEnv } from "../codegen/run-codegen.js";
+import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
+
+const codegen = defineCommand({
+    meta: {
+        name: "codegen",
+        description: "Generate TypeScript bindings for the GIR libraries declared in gtkx.config.ts",
+    },
+    args: {
+        force: {
+            type: "boolean",
+            description: "Wipe the generated store and regenerate unconditionally (recover a corrupted store)",
+            default: false,
+        },
+        ...cwdArg,
+    },
+    async run({ args }) {
+        const cwd = resolveCwd(args);
+
+        if (await isCodegenDisabled(cwd)) {
+            await runCodegen({ cwd });
+            syncSchemaEnv(cwd);
+            info("codegen: disabled for this project; reusing an installed binding store");
+
+            return;
+        }
+
+        if (!args.force) {
+            const isRan = await ensureGenerated(cwd);
+            info(isRan ? "codegen: regenerated stale bindings" : "codegen: bindings up to date");
+
+            return;
+        }
+
+        const startedAt = Date.now();
+        const result = await runCodegen({ cwd, force: true });
+        syncSchemaEnv(cwd);
+        const lines = formatCodegenResult(result, Date.now() - startedAt);
+
+        for (const line of lines) {
+            info(line);
+        }
+    },
+});
+
+export { codegen };

package/src/commands/dev.ts

@@ -0,0 +1,24 @@
+import { defineCommand } from "citty";
+import { ensureGenerated, resolveConfigWatch } from "../codegen/run-codegen.js";
+import { type DevWatch, runDevSupervisor } from "../dev/supervisor.js";
+import { entryArg, resolveEntry } from "../internal/entry-arg.js";
+
+const DEV_MODE = "development";
+
+const dev = defineCommand({
+    meta: {
+        name: "dev",
+        description: "Start development server with HMR",
+    },
+    args: {
+        ...entryArg,
+    },
+    async run({ args }) {
+        const { cwd, entry: entryPath } = resolveEntry(args);
+        await ensureGenerated(cwd, { announce: true, mode: DEV_MODE });
+        const watch: DevWatch | undefined = await resolveConfigWatch(cwd, DEV_MODE);
+        await runDevSupervisor(entryPath, cwd, watch);
+    },
+});
+
+export { dev };

package/src/commands/docs.ts

@@ -0,0 +1,95 @@
+import { type ElementProps, readBuiltinElements, resolveGirPath, resolveLibraries, writeDocs } from "@gtkx/codegen";
+import { loadConfig } from "@gtkx/config";
+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";
+
+const docs = defineCommand({
+    meta: {
+        name: "docs",
+        description:
+            "Generate markdown reference pages for the JSX elements of the GIR libraries declared in gtkx.config.ts",
+    },
+    args: {
+        out: {
+            type: "string",
+            description: "Output directory for the generated markdown pages, relative to the project root",
+            default: "docs/reference",
+        },
+        "base-path": {
+            type: "string",
+            description: "URL base path used for links between generated pages",
+            default: "/reference",
+        },
+        force: {
+            type: "boolean",
+            description: "Regenerate even when the pages are up to date with the GIR libraries",
+            default: false,
+        },
+        ...cwdArg,
+    },
+    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`.",
+            );
+        }
+
+        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.",
+            );
+        }
+
+        const libraries = resolveLibraries(config.libraries, girPath);
+        const startedAt = Date.now();
+        const outDir = resolve(cwd, args.out);
+
+        const { regenerated, namespaces } = writeDocs({
+            libraries,
+            girPath,
+            outDir,
+            basePath: args["base-path"],
+            props: await resolveDocsProps(cwd),
+            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 ${String(count)} element pages across ${String(namespaces.length)} namespaces ` +
+            `to ${outDir} in ${String(Date.now() - startedAt)}ms`,
+        );
+    },
+});
+
+const resolveDocsProps = async (cwd: string): Promise<ElementProps> => {
+    const giStoreDir = join(cwd, "node_modules", ".gtkx", "gi");
+
+    if (!existsSync(giStoreDir)) {
+        return {};
+    }
+
+    const { props } = await readBuiltinElements(resolveReactSubexports(cwd), giStoreDir);
+
+    return props;
+};
+
+export { docs };

package/src/dev/icon-dir.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { prependXdgDataDir } from "../internal/xdg-data-dirs.js";
+
+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;
+    }
+
+    process.env.XDG_DATA_DIRS = prependXdgDataDir(shareDir, process.env.XDG_DATA_DIRS);
+
+    return shareDir;
+};
+
+export { prepareDevIconDir };

package/src/dev/refresh-tracker.ts

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

package/src/dev/runner-deps.ts

@@ -0,0 +1,65 @@
+import { loadConfig } from "@gtkx/config";
+import * as Gio from "@gtkx/gi/gio";
+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";
+
+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;
+};
+
+const defaultDevRunnerDeps = (): DevRunnerDeps => ({
+    createServer,
+    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,
+    watchApplicationShutdown: (onShutdown) => {
+        Gio.Application.getDefault()?.on("shutdown", onShutdown);
+    },
+    installShutdownHandlers: (onSignal) => {
+        installGracefulShutdown({ onSignal });
+    },
+    quitDefaultApplication: () => {
+        const application = Gio.Application.getDefault();
+
+        if (application) {
+            quitApplication(application);
+        }
+    },
+    performRefresh,
+    isRefreshBoundary,
+    plugins: () => [...gtkxVitePlugins(DEV_MODE), ...gtkxFastRefresh(), gtkxReactDomPrebundle()],
+    log: info,
+    exit: (code: number): never => process.exit(code),
+});
+
+export { defaultDevRunnerDeps };

package/src/dev/runner-main.ts

@@ -0,0 +1,34 @@
+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";
+import { prepareDevSchemaDir } from "./schema-dir.js";
+
+const ENTRY_ARG_INDEX = 2;
+
+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);
+};
+
+export { main };

package/src/dev/runner.ts

@@ -0,0 +1,185 @@
+import type { InlineConfig, Plugin } from "vite";
+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";
+
+type DevRunnerDeps = {
+    createServer(config: InlineConfig): Promise<DevServer>;
+    waitForApplicationId(timeoutMs: number): Promise<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>;
+};
+
+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}`);
+    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);
+};
+
+const createShutdownController = (server: DevServer, deps: DevRunnerDeps): ShutdownController => {
+    let isShuttingDown = false;
+
+    return {
+        isShuttingDown: () => isShuttingDown,
+        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);
+        };
+
+const onShutdownSignal =
+    (deps: DevRunnerDeps, controller: ShutdownController): (() => Promise<void>) =>
+        async () => {
+            if (controller.isShuttingDown()) {
+                return;
+            }
+
+            deps.log("Received shutdown signal - stopping dev runner...");
+
+            await controller.shutdown(() => {
+                deps.quitDefaultApplication();
+            });
+        };
+
+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;
+            }
+
+            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...");
+            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));
+        } else {
+            deps.log("Entry did not mount an application - MCP client not started.");
+        }
+
+        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

@@ -0,0 +1,16 @@
+import { prependSchemaDir, stageAndCompileProjectSchemas } from "../settings/schema.js";
+
+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;
+};
+
+export { prepareDevSchemaDir };