@gtkx/cli 0.20.0 → 1.0.0-rc.1

package/src/builder.ts

@@ -1,94 +1,46 @@
-import { type InlineConfig, build as viteBuild } from "vite";
-import { gtkxAssets } from "./vite-plugin-gtkx-assets.js";
-import { gtkxBuiltUrl } from "./vite-plugin-gtkx-built-url.js";
-import { gtkxNative } from "./vite-plugin-gtkx-native.js";
+import { type InlineConfig, mergeConfig, build as viteBuild } from "vite";
+import { gtkxBuiltUrl } from "./vite-plugins/built-url.js";
+import { gtkxVitePlugins } from "./vite-plugins/index.js";
+import { gtkxNative } from "./vite-plugins/native.js";
+
+const BUILD_MODE = "production";
 
-/**
- * Options for building a GTKX application for production.
- */
 export type BuildOptions = {
-    /** Path to the entry file (e.g., "src/index.tsx") */
     entry: string;
-    /**
-     * Base path for resolving asset imports at runtime, relative to the
-     * executable directory.
-     *
-     * When set, asset imports resolve to
-     * `path.join(path.dirname(process.execPath), assetBase, filename)`.
-     * This is useful for FHS-compliant packaging where assets live under
-     * a `share/` directory rather than next to the binary.
-     *
-     * When omitted, assets resolve relative to the bundle via
-     * `import.meta.url`, which works when assets are co-located with
-     * the executable (e.g., in `bin/assets/`).
-     *
-     * @example
-     * ```ts
-     * await build({
-     *     entry: "./src/index.tsx",
-     *     assetBase: "../share/my-app",
-     * });
-     * ```
-     */
-    assetBase?: string;
-    /** Additional Vite configuration */
-    vite?: InlineConfig;
+    assetBase?: string | undefined;
+    vite?: InlineConfig | undefined;
+};
+
+const buildDefaults: InlineConfig = {
+    build: {
+        ssrEmitAssets: true,
+        outDir: "dist",
+        minify: true,
+        cssMinify: false,
+    },
+    define: {
+        "process.env.NODE_ENV": JSON.stringify(BUILD_MODE),
+    },
 };
 
-/**
- * Builds a GTKX application for production using Vite's SSR build mode.
- *
- * Produces a single minified ESM bundle at `dist/bundle.js` with all
- * dependencies inlined. The native `.node` binary is copied into the
- * output directory as `gtkx.node`, making the bundle fully self-contained
- * with no `node_modules` dependency at runtime.
- *
- * @param options - Build configuration including entry point and Vite options
- *
- * @example
- * ```ts
- * import { build } from "@gtkx/cli";
- *
- * await build({
- *     entry: "./src/index.tsx",
- *     vite: { root: process.cwd() },
- * });
- * ```
- *
- * @see {@link BuildOptions} for configuration options
- */
 export const build = async (options: BuildOptions): Promise<void> => {
     const { entry, assetBase, vite: viteConfig } = options;
     const root = viteConfig?.root ?? process.cwd();
 
-    await viteBuild({
-        ...viteConfig,
-        plugins: [...(viteConfig?.plugins ?? []), gtkxAssets(), gtkxBuiltUrl(assetBase), gtkxNative(root)],
+    const forced: InlineConfig = {
+        plugins: [...gtkxVitePlugins(BUILD_MODE), gtkxBuiltUrl(assetBase), gtkxNative(root)],
         build: {
-            ...viteConfig?.build,
             ssr: entry,
-            ssrEmitAssets: true,
             assetsInlineLimit: 0,
-            outDir: viteConfig?.build?.outDir ?? "dist",
-            minify: true,
-            rollupOptions: {
-                ...viteConfig?.build?.rollupOptions,
+            rolldownOptions: {
                 output: {
-                    ...((viteConfig?.build?.rollupOptions?.output ?? {}) as Record<string, unknown>),
                     entryFileNames: "bundle.js",
                 },
             },
         },
-        define: {
-            ...viteConfig?.define,
-            "process.env.NODE_ENV": JSON.stringify("production"),
-        },
-        ssr: {
-            ...viteConfig?.ssr,
-            noExternal: true,
-        },
-        experimental: {
-            ...viteConfig?.experimental,
-        },
-    });
+    };
+
+    const merged = mergeConfig(mergeConfig(buildDefaults, viteConfig ?? {}), forced);
+
+    await viteBuild({ ...merged, ssr: { ...merged.ssr, noExternal: true } });
 };

package/src/cli.ts

@@ -0,0 +1,22 @@
+import { packageVersion } from "@gtkx/utils";
+import { defineCommand, runMain } from "citty";
+import { withErrorBoundary } from "./internal/errors.js";
+
+const version = packageVersion(import.meta.url);
+
+export const main = defineCommand({
+    meta: {
+        name: "gtkx",
+        version,
+        description: "CLI for GTKX: create and develop GTK4 React applications",
+    },
+    subCommands: {
+        dev: () => import("./commands/dev.js").then((m) => withErrorBoundary(m.dev)),
+        build: () => import("./commands/build.js").then((m) => withErrorBoundary(m.build)),
+        codegen: () => import("./commands/codegen.js").then((m) => withErrorBoundary(m.codegen)),
+        docs: () => import("./commands/docs.js").then((m) => withErrorBoundary(m.docs)),
+        create: () => import("create-gtkx").then((m) => withErrorBoundary(m.createCommand)),
+    },
+});
+
+await runMain(main);

package/src/codegen/freshness.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveGirPath, resolveLibraries } from "@gtkx/codegen";
+import type { Config, ElementProp } from "@gtkx/config";
+import { type CodegenStore, resolveCodegenStore } from "./store-resolver.js";
+
+export type CodegenInputs = {
+    girPath: string[];
+    libraries: string[];
+    elementProps: Record<string, ElementProp[]>;
+    store: CodegenStore;
+};
+
+export const resolveCodegenInputs = (cwd: string, config: Config): CodegenInputs => {
+    const girPath = resolveGirPath(config.girPath);
+    const libraries = resolveLibraries(config.libraries, girPath);
+    const store = resolveCodegenStore(cwd);
+    return { girPath, libraries, elementProps: config.elementProps ?? {}, store };
+};
+
+const REACT_GENERATED_MODULES: string[] = ["metadata.js", join("gtk", "gtk.js")];
+
+const namespaceBarrelPath = (giStoreDir: string, library: string): string => {
+    const separator = library.indexOf("-");
+    const namespace = (separator === -1 ? library : library.slice(0, separator)).toLowerCase();
+    return join(giStoreDir, namespace, "index.js");
+};
+
+const giStoreLinksResolve = (giStoreDir: string): boolean =>
+    existsSync(join(giStoreDir, "node_modules", "@gtkx", "gi", "package.json"));
+
+export const isCodegenStale = (inputs: CodegenInputs): boolean => {
+    try {
+        const { store, libraries } = inputs;
+        if (!existsSync(store.giLinkDir) || !existsSync(store.giStoreDir)) {
+            return true;
+        }
+        if (!giStoreLinksResolve(store.giStoreDir)) {
+            return true;
+        }
+        if (libraries.some((library) => !existsSync(namespaceBarrelPath(store.giStoreDir, library)))) {
+            return true;
+        }
+        if (store.react !== null) {
+            if (!existsSync(store.jsxLinkDir)) return true;
+            if (REACT_GENERATED_MODULES.some((module) => !existsSync(join(store.jsxStoreDir, module)))) return true;
+        }
+        return false;
+    } catch {
+        return true;
+    }
+};

package/src/codegen/report.ts

@@ -0,0 +1,20 @@
+import type { RunCodegenResult } from "./run-codegen.js";
+
+const PREFIX = "codegen: ";
+
+export const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[] => {
+    const details: string[] = [];
+    if (result.configFile) {
+        details.push(`config=${result.configFile}`);
+    }
+    if (result.libraries) {
+        details.push(`libraries=${result.libraries.join(", ")}`);
+    }
+    if (result.girPath) {
+        details.push(`girPath=${result.girPath.join(":")}`);
+    }
+    details.push(
+        `${result.namespaces} namespaces, ${result.intrinsicElements} intrinsic elements in ${result.duration}ms (total ${totalMs}ms)`,
+    );
+    return details.map((detail) => PREFIX + detail);
+};

package/src/codegen/run-codegen.ts

@@ -0,0 +1,185 @@
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { runCodegen as runCodegenCore } from "@gtkx/codegen";
+import { type Config, type ElementProp, loadConfig } from "@gtkx/config";
+import { info } from "@gtkx/utils";
+import { resolveDataDir } from "../internal/data-dir.js";
+import { emitSchemaEnv } from "../settings/schema.js";
+import { type CodegenInputs, isCodegenStale, resolveCodegenInputs } from "./freshness.js";
+import { type CodegenStore, resolveCodegenContext } from "./store-resolver.js";
+
+export type RunCodegenOptions = {
+    cwd?: string;
+    mode?: string | undefined;
+    force?: boolean;
+    inputs?: CodegenInputs;
+    resolved?: LoadedConfig;
+};
+
+type LoadedConfig = {
+    config: Config;
+    configFile: string | undefined;
+};
+
+export type RunCodegenResult = {
+    regenerated: boolean;
+    namespaces: number;
+    intrinsicElements: number;
+    duration: number;
+    girPath?: string[] | undefined;
+    configFile?: string | undefined;
+    libraries?: string[] | undefined;
+};
+
+const removeSharedStoreShadow = (cwd: string): void => {
+    for (const path of [
+        resolve(cwd, "node_modules/.gtkx/gi"),
+        resolve(cwd, "node_modules/.gtkx/jsx"),
+        resolve(cwd, "node_modules/@gtkx/gi"),
+        resolve(cwd, "node_modules/@gtkx/jsx"),
+    ]) {
+        rmSync(path, { recursive: true, force: true });
+    }
+};
+
+type CodegenOptionsInput = {
+    store: CodegenStore;
+    libraries: string[];
+    girPath: string[];
+    elementProps: Record<string, ElementProp[]>;
+};
+
+const codegenOptions = ({ store, libraries, girPath, elementProps }: CodegenOptionsInput) => ({
+    libraries,
+    girPath,
+    elementProps,
+    gi: {
+        storeDir: store.giStoreDir,
+        linkDir: store.giLinkDir,
+        version: store.runtimeVersion,
+    },
+    jsx:
+        store.react !== null
+            ? {
+                  storeDir: store.jsxStoreDir,
+                  linkDir: store.jsxLinkDir,
+                  version: store.react.version,
+              }
+            : undefined,
+});
+
+export const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenResult> => {
+    const cwd = options.cwd ?? process.cwd();
+
+    const { config, configFile } = options.resolved ?? (await loadConfig(cwd, { mode: options.mode }));
+
+    if (config.codegen === false) {
+        removeSharedStoreShadow(cwd);
+        return {
+            regenerated: false,
+            namespaces: 0,
+            intrinsicElements: 0,
+            duration: 0,
+            girPath: [],
+            configFile,
+            libraries: [],
+        };
+    }
+
+    const { girPath, libraries, elementProps, store } = options.inputs ?? resolveCodegenInputs(cwd, config);
+
+    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 force = options.force === true || isCodegenStale({ girPath, libraries, elementProps, store });
+    if (options.force) {
+        for (const path of [store.giStoreDir, store.giLinkDir, store.jsxStoreDir, store.jsxLinkDir]) {
+            rmSync(path, { recursive: true, force: true });
+        }
+    }
+
+    const result = await runCodegenCore({
+        ...codegenOptions({ store, libraries, girPath, elementProps }),
+        force,
+    });
+
+    return {
+        regenerated: result.regenerated,
+        namespaces: result.namespaces,
+        intrinsicElements: result.intrinsicElements,
+        duration: result.duration,
+        girPath,
+        configFile,
+        libraries,
+    };
+};
+
+export const isCodegenDisabled = async (cwd: string, mode?: string): Promise<boolean> => {
+    try {
+        const { config } = await loadConfig(cwd, { mode });
+        return config.codegen === false;
+    } catch {
+        return false;
+    }
+};
+
+export const syncSchemaEnv = (cwd: string): void => {
+    const dataDir = resolveDataDir(cwd);
+    if (dataDir === null) return;
+    emitSchemaEnv(cwd, dataDir);
+};
+
+const resolveInputsOrNull = (cwd: string, config: Config): CodegenInputs | null => {
+    try {
+        return resolveCodegenInputs(cwd, config);
+    } catch {
+        return null;
+    }
+};
+
+export const ensureGenerated = async (
+    cwd: string,
+    options: { announce?: boolean; mode?: string } = {},
+): Promise<boolean> => {
+    if (options.announce && process.env.GTKX_DISABLE_PREFLIGHT === "1") {
+        return false;
+    }
+
+    const context = await resolveCodegenContext(cwd, options.mode);
+    if (!context) {
+        return false;
+    }
+    syncSchemaEnv(cwd);
+    if (context.config.codegen === false) {
+        removeSharedStoreShadow(context.root);
+        return false;
+    }
+    const inputs = resolveInputsOrNull(context.root, context.config);
+    if (options.announce && (inputs === null || isCodegenStale(inputs))) {
+        info("generated bindings missing; running codegen...");
+    }
+    const resolved = { config: context.config, configFile: context.configFile };
+    const result = await runCodegen(
+        inputs === null
+            ? { cwd: context.root, mode: options.mode, resolved }
+            : { cwd: context.root, mode: options.mode, inputs, resolved },
+    );
+    return result.regenerated;
+};
+
+export const resolveConfigWatch = async (
+    cwd: string,
+    mode?: string,
+): Promise<{ paths: string[]; regenerate: () => Promise<void> } | undefined> => {
+    const { configFile, root } = await loadConfig(cwd, { mode });
+    if (configFile === undefined) return undefined;
+    return {
+        paths: [resolve(root, configFile)],
+        regenerate: async () => {
+            await runCodegen({ cwd: root, mode });
+        },
+    };
+};

package/src/codegen/store-resolver.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { type Config, loadConfig } from "@gtkx/config";
+
+export type CodegenStore = {
+    giStoreDir: string;
+    giLinkDir: string;
+    jsxStoreDir: string;
+    jsxLinkDir: string;
+    runtimeVersion: string;
+    react: CodegenReactPackage | null;
+};
+
+type CodegenReactPackage = {
+    version: string;
+};
+
+type ResolvedPackage = { dir: string; version: string };
+
+const readVersion = (packageJsonPath: string): string => {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: string };
+    return parsed.version ?? "0.0.0";
+};
+
+const resolvePackage = (require: NodeJS.Require, dir: string, packageName: string): ResolvedPackage | null => {
+    try {
+        const real = realpathSync(require.resolve(`${packageName}/package.json`));
+        return { dir: dirname(real), version: readVersion(real) };
+    } catch {
+        const unscoped = packageName.replace(/^@[^/]+\//, "");
+        const workspacePkg = join(dir, "packages", unscoped, "package.json");
+        if (!existsSync(workspacePkg)) return null;
+        const real = realpathSync(workspacePkg);
+        return { dir: dirname(real), version: readVersion(real) };
+    }
+};
+
+export const resolveCodegenStore = (dir: string): CodegenStore => {
+    const require = createRequire(pathToFileURL(join(dir, "__gtkx_resolver__.js")).href);
+
+    const runtime = resolvePackage(require, dir, "@gtkx/runtime");
+    if (runtime === null) {
+        throw new Error("Cannot resolve @gtkx/runtime from the project; is it installed?");
+    }
+    const native = resolvePackage(require, dir, "@gtkx/native");
+    if (native === null) {
+        throw new Error("Cannot resolve @gtkx/native from the project; is it installed?");
+    }
+    const react = resolvePackage(require, dir, "@gtkx/react");
+    const reactRuntime = resolvePackage(require, dir, "react");
+
+    const nodeModules = join(dir, "node_modules");
+    return {
+        giStoreDir: join(nodeModules, ".gtkx", "gi"),
+        giLinkDir: join(nodeModules, "@gtkx", "gi"),
+        jsxStoreDir: join(nodeModules, ".gtkx", "jsx"),
+        jsxLinkDir: join(nodeModules, "@gtkx", "jsx"),
+        runtimeVersion: runtime.version,
+        react: react !== null && reactRuntime !== null ? { version: react.version } : null,
+    };
+};
+
+export type CodegenContext = {
+    root: string;
+    config: Config;
+    configFile: string | undefined;
+};
+
+export const resolveCodegenContext = async (cwd: string, mode?: string): Promise<CodegenContext | null> => {
+    const { config, configFile } = await loadConfig(cwd, { mode });
+    if (configFile === undefined) return null;
+    return { root: cwd, config, configFile };
+};

package/src/commands/build.ts

@@ -0,0 +1,37 @@
+import { info } from "@gtkx/utils";
+import { defineCommand } from "citty";
+import { build as buildApp } from "../builder.js";
+import { ensureGenerated } from "../codegen/run-codegen.js";
+import { entryArg, resolveEntry } from "../internal/entry-arg.js";
+
+const BUILD_MODE = "production";
+
+export const build = defineCommand({
+    meta: {
+        name: "build",
+        description: "Build application for production",
+    },
+    args: {
+        ...entryArg,
+        "asset-base": {
+            type: "string",
+            description: "Asset base path relative to executable directory (e.g., ../share/my-app)",
+        },
+    },
+    async run({ args }) {
+        const { cwd, entry } = resolveEntry(args);
+        info(`Building ${entry}`);
+
+        await ensureGenerated(cwd, { announce: true, mode: BUILD_MODE });
+
+        await buildApp({
+            entry,
+            assetBase: args["asset-base"],
+            vite: {
+                root: cwd,
+            },
+        });
+
+        info("Build complete: dist/bundle.js");
+    },
+});

package/src/commands/codegen.ts

@@ -0,0 +1,44 @@
+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";
+
+export 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 ran = await ensureGenerated(cwd);
+            info(ran ? "codegen: regenerated stale bindings" : "codegen: bindings up to date");
+            return;
+        }
+
+        const startedAt = Date.now();
+        const result = await runCodegen({ cwd, force: true });
+        syncSchemaEnv(cwd);
+
+        for (const line of formatCodegenResult(result, Date.now() - startedAt)) {
+            info(line);
+        }
+    },
+});

package/src/commands/dev.ts

@@ -0,0 +1,25 @@
+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";
+
+export 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);
+    },
+});

package/src/commands/docs.ts

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { resolveGirPath, resolveLibraries, writeDocs } from "@gtkx/codegen";
+import { loadConfig } from "@gtkx/config";
+import { info } from "@gtkx/utils";
+import { defineCommand } from "citty";
+import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
+
+export 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"],
+            elementProps: config.elementProps ?? {},
+            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`,
+        );
+    },
+});

package/src/dev/icon-dir.ts

@@ -0,0 +1,11 @@
+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 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;
+};