@gtkx/cli 0.21.0 → 1.0.0-rc.2

package/src/babel-modules.d.ts

@@ -0,0 +1,11 @@
+declare module "babel-plugin-react-compiler" {
+    import type { PluginTarget } from "@babel/core";
+    const plugin: PluginTarget & { default?: PluginTarget };
+    export default plugin;
+}
+
+declare module "@babel/preset-typescript" {
+    import type { PresetTarget } from "@babel/core";
+    const preset: PresetTarget & { default?: PresetTarget };
+    export default preset;
+}

package/src/builder.ts

@@ -1,102 +1,47 @@
-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 { gtkxGSettings } from "./vite-plugin-gtkx-gsettings.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";
 
-/**
- * Options for building a GTKX application for production.
- */
-export type BuildOptions = {
-    /** Path to the entry file (e.g., "src/index.tsx") */
+type BuildOptions = {
     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;
 };
 
-/**
- * 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 BUILD_MODE = "production";
+
+const buildDefaults: InlineConfig = {
+    build: {
+        ssrEmitAssets: true,
+        outDir: "dist",
+        minify: true,
+        cssMinify: false,
+    },
+    define: {
+        "process.env.NODE_ENV": JSON.stringify(BUILD_MODE),
+    },
+};
+
+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 ?? []),
-            gtkxGSettings(),
-            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,
-            cssMinify: false,
-            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: InlineConfig = mergeConfig(mergeConfig(buildDefaults, viteConfig ?? {}), forced);
+    await viteBuild({ ...merged, ssr: { ...merged.ssr, noExternal: true } });
 };
+
+export { build, type BuildOptions };

package/src/cli.ts

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

package/src/codegen/freshness.ts

@@ -0,0 +1,65 @@
+import type { Config } from "@gtkx/config";
+import { resolveGirPath, resolveLibraries } from "@gtkx/codegen";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { type CodegenStore, resolveCodegenStore } from "./store-resolver.js";
+
+type CodegenInputs = {
+    girPath: string[];
+    libraries: string[];
+    store: CodegenStore;
+};
+
+const REACT_GENERATED_MODULES: string[] = ["metadata.js", join("gtk", "gtk.js")];
+
+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, store };
+};
+
+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 canResolveGiStoreLinks = (giStoreDir: string): boolean =>
+    existsSync(join(giStoreDir, "node_modules", "@gtkx", "gi", "package.json"));
+
+const isGiStoreStale = (store: CodegenStore, libraries: string[]): boolean => {
+    if (!existsSync(store.giLinkDir) || !existsSync(store.giStoreDir)) {
+        return true;
+    }
+
+    if (!canResolveGiStoreLinks(store.giStoreDir)) {
+        return true;
+    }
+
+    return libraries.some((library) => !existsSync(namespaceBarrelPath(store.giStoreDir, library)));
+};
+
+const isReactStoreStale = (store: CodegenStore): boolean => {
+    if (store.react === null) {
+        return false;
+    }
+
+    if (!existsSync(store.jsxLinkDir)) {
+        return true;
+    }
+
+    return REACT_GENERATED_MODULES.some((module) => !existsSync(join(store.jsxStoreDir, module)));
+};
+
+const isCodegenStale = (inputs: CodegenInputs): boolean => {
+    try {
+        return isGiStoreStale(inputs.store, inputs.libraries) || isReactStoreStale(inputs.store);
+    } catch {
+        return true;
+    }
+};
+
+export { resolveCodegenInputs, isCodegenStale, type CodegenInputs };

package/src/codegen/report.ts

@@ -0,0 +1,28 @@
+import type { RunCodegenResult } from "./run-codegen.js";
+
+const PREFIX = "codegen: ";
+
+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(
+        `${String(result.namespaces)} namespaces, ${String(result.intrinsicElements)} intrinsic elements ` +
+        `in ${String(result.duration)}ms (total ${String(totalMs)}ms)`,
+    );
+
+    return details.map((detail) => PREFIX + detail);
+};
+
+export { formatCodegenResult };

package/src/codegen/run-codegen.ts

@@ -0,0 +1,260 @@
+import { runCodegen as runCodegenCore } from "@gtkx/codegen";
+import { type Config, loadConfig } from "@gtkx/config";
+import { resolveLazyElements } from "@gtkx/config/internal";
+import { info } from "@gtkx/utils";
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+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";
+
+type RunCodegenOptions = {
+    cwd?: string;
+    mode?: string | undefined;
+    force?: boolean;
+    inputs?: CodegenInputs;
+    resolved?: LoadedConfig;
+};
+
+type LoadedConfig = {
+    config: Config;
+    configFile: string | undefined;
+};
+
+type RunCodegenResult = {
+    regenerated: boolean;
+    namespaces: number;
+    intrinsicElements: number;
+    duration: number;
+    girPath?: string[] | undefined;
+    configFile?: string | undefined;
+    libraries?: string[] | undefined;
+};
+
+type CodegenOptionsInput = {
+    store: CodegenStore;
+    libraries: string[];
+    girPath: string[];
+    elements: Config["elements"];
+};
+
+type PreparedCodegen = CodegenInputs & { force: boolean };
+
+type RunOptionsInput = {
+    root: string;
+    mode: string | undefined;
+    inputs: CodegenInputs | null;
+    resolved: LoadedConfig;
+};
+
+const GIR_PATH_MISSING_MESSAGE =
+    "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 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 });
+    }
+};
+
+const userModuleExports = (
+    elements: Config["elements"],
+    key: "component" | "props",
+): Record<string, { module: string; export: string }> =>
+    Object.fromEntries(
+        Object.entries(elements?.config ?? {}).flatMap(([type, entry]) => {
+            const ref = entry[key];
+
+            return ref === undefined ? [] : [[type, ref] as const];
+        }),
+    );
+
+const codegenOptions = ({ store, libraries, girPath, elements }: CodegenOptionsInput) => ({
+    libraries,
+    girPath,
+    gi: {
+        storeDir: store.giStoreDir,
+        linkDir: store.giLinkDir,
+        version: store.runtimeVersion,
+    },
+    jsx:
+        store.react === null
+            ? undefined
+            : {
+                    storeDir: store.jsxStoreDir,
+                    linkDir: store.jsxLinkDir,
+                    version: store.react.version,
+                },
+    reactSubexports: store.react?.subexports ?? [],
+    userComponents: userModuleExports(elements, "component"),
+    userProps: userModuleExports(elements, "props"),
+    userLazyElements: resolveLazyElements(elements),
+});
+
+const disabledCodegenResult = (configFile: string | undefined): RunCodegenResult => ({
+    regenerated: false,
+    namespaces: 0,
+    intrinsicElements: 0,
+    duration: 0,
+    girPath: [],
+    configFile,
+    libraries: [],
+});
+
+const clearGeneratedStores = (store: CodegenStore): void => {
+    for (const path of [store.giStoreDir, store.giLinkDir, store.jsxStoreDir, store.jsxLinkDir]) {
+        rmSync(path, { recursive: true, force: true });
+    }
+};
+
+const resolveLoadedConfig = async (options: RunCodegenOptions, cwd: string): Promise<LoadedConfig> =>
+    options.resolved ?? (await loadConfig(cwd, { mode: options.mode }));
+
+const prepareCodegen = (options: RunCodegenOptions, cwd: string, config: Config): PreparedCodegen => {
+    const { girPath, libraries, store } = options.inputs ?? resolveCodegenInputs(cwd, config);
+
+    if (girPath.length === 0) {
+        throw new Error(GIR_PATH_MISSING_MESSAGE);
+    }
+
+    const isForce = options.force === true || isCodegenStale({ girPath, libraries, store });
+
+    return { girPath, libraries, store, force: isForce };
+};
+
+const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenResult> => {
+    const cwd = options.cwd ?? process.cwd();
+    const { config, configFile } = await resolveLoadedConfig(options, cwd);
+
+    if (config.codegen === false) {
+        removeSharedStoreShadow(cwd);
+
+        return disabledCodegenResult(configFile);
+    }
+
+    const { girPath, libraries, store, force } = prepareCodegen(options, cwd, config);
+
+    if (options.force) {
+        clearGeneratedStores(store);
+    }
+
+    const result = await runCodegenCore({
+        ...codegenOptions({ store, libraries, girPath, elements: config.elements }),
+        force,
+    });
+
+    return {
+        regenerated: result.regenerated,
+        namespaces: result.namespaces,
+        intrinsicElements: result.intrinsicElements,
+        duration: result.duration,
+        girPath,
+        configFile,
+        libraries,
+    };
+};
+
+const isCodegenDisabled = async (cwd: string, mode?: string): Promise<boolean> => {
+    try {
+        const { config } = await loadConfig(cwd, { mode });
+
+        return config.codegen === false;
+    } catch {
+        return false;
+    }
+};
+
+const syncSchemaEnv = (cwd: string): void => {
+    emitSchemaEnv(cwd, resolveDataDir(cwd));
+};
+
+const resolveInputsOrNull = (cwd: string, config: Config): CodegenInputs | null => {
+    try {
+        return resolveCodegenInputs(cwd, config);
+    } catch {
+        return null;
+    }
+};
+
+const maybeAnnounceStale = (announce: boolean | undefined, inputs: CodegenInputs | null): void => {
+    if (!announce) {
+        return;
+    }
+
+    if (inputs === null || isCodegenStale(inputs)) {
+        info("generated bindings missing; running codegen...");
+    }
+};
+
+const getRunOptions = ({ root, mode, inputs, resolved }: RunOptionsInput): RunCodegenOptions => {
+    if (inputs === null) {
+        return { cwd: root, mode, resolved };
+    }
+
+    return { cwd: root, mode, inputs, resolved };
+};
+
+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);
+    maybeAnnounceStale(options.announce, inputs);
+    const resolved = { config: context.config, configFile: context.configFile };
+    const result = await runCodegen(getRunOptions({ root: context.root, mode: options.mode, inputs, resolved }));
+
+    return result.regenerated;
+};
+
+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 });
+        },
+    };
+};
+
+export {
+    runCodegen,
+    isCodegenDisabled,
+    syncSchemaEnv,
+    ensureGenerated,
+    resolveConfigWatch,
+    type RunCodegenOptions,
+    type RunCodegenResult,
+};

package/src/codegen/store-resolver.ts

@@ -0,0 +1,116 @@
+import { type Config, loadConfig } from "@gtkx/config";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+type CodegenStore = {
+    giStoreDir: string;
+    giLinkDir: string;
+    jsxStoreDir: string;
+    jsxLinkDir: string;
+    runtimeVersion: string;
+    react: CodegenReactPackage | null;
+};
+
+type CodegenReactPackage = {
+    version: string;
+    subexports: string[];
+};
+
+type ResolvedPackage = { dir: string; version: string };
+
+type CodegenContext = {
+    root: string;
+    config: Config;
+    configFile: string | undefined;
+};
+
+const readVersion = (packageJsonPath: string): string => {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: string };
+
+    return parsed.version ?? "0.0.0";
+};
+
+const readSubexports = (packageDir: string): string[] => {
+    const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")) as {
+        exports?: Record<string, unknown>;
+    };
+
+    return Object.keys(parsed.exports ?? {})
+        .filter((key) => key.startsWith("./") && key !== "./package.json")
+        .map((key) => key.slice(2));
+};
+
+/** Resolves the `@gtkx/react` subexport names for a project without requiring runtime/native to be installed. */
+const resolveReactSubexports = (dir: string): string[] => {
+    const require = createRequire(pathToFileURL(join(dir, "__gtkx_resolver__.js")).href);
+    const react = resolvePackage(require, dir, "@gtkx/react");
+
+    return react === null ? [] : readSubexports(react.dir);
+};
+
+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) };
+    }
+};
+
+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,
+                        subexports: readSubexports(react.dir),
+                    }
+                : null,
+    };
+};
+
+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 };
+};
+
+export { resolveReactSubexports, resolveCodegenStore, resolveCodegenContext, type CodegenStore, type CodegenContext };

package/src/commands/build.ts

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