@gtkx/cli 0.18.1 → 0.18.2

package/src/cli.tsx

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import "./refresh-runtime.js";
+
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { events } from "@gtkx/ffi";
+import type * as Gio from "@gtkx/ffi/gio";
+import { render } from "@gtkx/react";
+import { defineCommand, runMain } from "citty";
+import { build } from "./builder.js";
+import { createApp } from "./create.js";
+import { createDevServer } from "./dev-server.js";
+import { startMcpClient, stopMcpClient } from "./mcp-client.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json") as { version: string };
+
+interface AppModule {
+    default: () => React.ReactNode;
+    appId?: string;
+    appFlags?: Gio.ApplicationFlags;
+}
+
+const dev = defineCommand({
+    meta: {
+        name: "dev",
+        description: "Start development server with HMR",
+    },
+    args: {
+        entry: {
+            type: "positional",
+            description: "Entry file (e.g., src/app.tsx)",
+            required: true,
+        },
+    },
+    async run({ args }) {
+        const entryPath = resolve(process.cwd(), args.entry);
+        console.log(`[gtkx] Starting dev server for ${entryPath}`);
+
+        const server = await createDevServer({
+            entry: entryPath,
+            vite: {
+                root: process.cwd(),
+            },
+        });
+
+        const mod = (await server.ssrLoadModule(entryPath)) as AppModule;
+        const App = mod.default;
+        const appId = mod.appId ?? "org.gtkx.dev";
+        const appFlags = mod.appFlags;
+
+        if (typeof App !== "function") {
+            console.error("[gtkx] Entry file must export a default function component");
+            process.exit(1);
+        }
+
+        console.log(`[gtkx] Rendering app with ID: ${appId}`);
+        render(<App />, appId, appFlags);
+
+        await startMcpClient(appId);
+        events.on("stop", () => {
+            stopMcpClient();
+        });
+
+        console.log("[gtkx] HMR enabled - watching for changes...");
+    },
+});
+
+const buildCmd = defineCommand({
+    meta: {
+        name: "build",
+        description: "Build application for production",
+    },
+    args: {
+        entry: {
+            type: "positional",
+            description: "Entry file (default: src/index.tsx)",
+            required: false,
+        },
+        "asset-base": {
+            type: "string",
+            description: "Asset base path relative to executable directory (e.g., ../share/my-app)",
+        },
+    },
+    async run({ args }) {
+        const entry = resolve(process.cwd(), args.entry ?? "src/index.tsx");
+        console.log(`[gtkx] Building ${entry}`);
+
+        await build({
+            entry,
+            assetBase: args["asset-base"],
+            vite: {
+                root: process.cwd(),
+            },
+        });
+
+        console.log("[gtkx] Build complete: dist/bundle.js");
+    },
+});
+
+const create = defineCommand({
+    meta: {
+        name: "create",
+        description: "Create a new GTKX application",
+    },
+    args: {
+        name: {
+            type: "positional",
+            description: "Project name",
+            required: false,
+        },
+        "app-id": {
+            type: "string",
+            description: "App ID (e.g., com.example.myapp)",
+        },
+        pm: {
+            type: "string",
+            description: "Package manager (pnpm, npm, yarn)",
+        },
+        testing: {
+            type: "string",
+            description: "Testing setup (vitest, none)",
+        },
+        "claude-skills": {
+            type: "boolean",
+            description: "Include Claude Code skills for AI assistance",
+        },
+    },
+    async run({ args }) {
+        await createApp({
+            name: args.name,
+            appId: args["app-id"],
+            packageManager: args.pm as "pnpm" | "npm" | "yarn" | undefined,
+            testing: args.testing as "vitest" | "none" | undefined,
+            claudeSkills: args["claude-skills"],
+        });
+    },
+});
+
+const main = defineCommand({
+    meta: {
+        name: "gtkx",
+        version,
+        description: "CLI for GTKX - create and develop GTK4 React applications",
+    },
+    subCommands: {
+        dev,
+        build: buildCmd,
+        create,
+    },
+});
+
+runMain(main);

package/src/create.ts

@@ -0,0 +1,310 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { renderFile, type TemplateContext } from "./templates.js";
+
+/**
+ * Supported package managers for GTKX projects.
+ */
+export type PackageManager = "pnpm" | "npm" | "yarn";
+
+/**
+ * Whether to include testing setup in GTKX projects.
+ */
+export type TestingOption = "vitest" | "none";
+
+/**
+ * Options for creating a new GTKX project.
+ *
+ * All options are optional; missing values will be prompted interactively.
+ */
+export type CreateOptions = {
+    name?: string;
+    appId?: string;
+    packageManager?: PackageManager;
+    testing?: TestingOption;
+    claudeSkills?: boolean;
+};
+
+const DEPENDENCIES = ["@gtkx/css", "@gtkx/ffi", "@gtkx/react", "react"];
+
+const DEV_DEPENDENCIES = ["@gtkx/cli", "@types/react", "typescript", "vite"];
+
+const TESTING_DEV_DEPENDENCIES = ["@gtkx/testing", "@gtkx/vitest", "vitest"];
+
+const createTemplateContext = (name: string, appId: string, testing: TestingOption): TemplateContext => {
+    const title = name
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+
+    return { name, appId, title, testing };
+};
+
+export const getAddCommand = (pm: PackageManager, deps: string[], dev: boolean): string => {
+    const devFlag = dev ? (pm === "npm" ? "--save-dev" : "-D") : "";
+    const parts = [devFlag, ...deps].filter(Boolean).join(" ");
+
+    switch (pm) {
+        case "npm":
+            return `npm install ${parts}`;
+        case "yarn":
+            return `yarn add ${parts}`;
+        case "pnpm":
+            return `pnpm add ${parts}`;
+    }
+};
+
+export const getRunCommand = (pm: PackageManager): string => {
+    switch (pm) {
+        case "npm":
+            return "npm run dev";
+        case "yarn":
+            return "yarn dev";
+        case "pnpm":
+            return "pnpm dev";
+    }
+};
+
+export const isValidProjectName = (name: string): boolean => {
+    return /^[a-z0-9-]+$/.test(name);
+};
+
+export const isValidAppId = (appId: string): boolean => {
+    return /^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)+$/.test(appId);
+};
+
+const runCommand = (command: string, cwd: string): Promise<void> => {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, { cwd, stdio: "pipe", shell: true });
+        proc.on("close", (code) =>
+            code === 0 ? resolve() : reject(new Error(`Command failed with exit code ${code}`)),
+        );
+        proc.on("error", reject);
+    });
+};
+
+const suggestAppId = (name: string): string => {
+    const sanitized = name.replace(/-/g, "");
+    return `com.${sanitized}.app`;
+};
+
+type ResolvedOptions = {
+    name: string;
+    appId: string;
+    packageManager: PackageManager;
+    testing: TestingOption;
+    claudeSkills: boolean;
+};
+
+const checkCancelled = <T>(value: T | symbol): T => {
+    if (p.isCancel(value)) {
+        p.cancel("Operation cancelled");
+        process.exit(0);
+    }
+    return value as T;
+};
+
+const promptForOptions = async (options: CreateOptions): Promise<ResolvedOptions> => {
+    const name =
+        options.name ??
+        checkCancelled(
+            await p.text({
+                message: "Project name",
+                placeholder: "my-app",
+                validate: (value) => {
+                    if (!value) return "Project name is required";
+                    if (!isValidProjectName(value)) {
+                        return "Project name must be lowercase letters, numbers, and hyphens only";
+                    }
+                    if (existsSync(resolve(process.cwd(), value))) {
+                        return `Directory "${value}" already exists`;
+                    }
+                },
+            }),
+        );
+
+    const defaultAppId = suggestAppId(name);
+
+    const appId =
+        options.appId ??
+        checkCancelled(
+            await p.text({
+                message: "App ID",
+                placeholder: defaultAppId,
+                initialValue: defaultAppId,
+                validate: (value) => {
+                    if (!value) return "App ID is required";
+                    if (!isValidAppId(value)) {
+                        return "App ID must be reverse domain notation (e.g., com.example.myapp)";
+                    }
+                },
+            }),
+        );
+
+    const packageManager =
+        options.packageManager ??
+        checkCancelled(
+            await p.select({
+                message: "Package manager",
+                options: [
+                    { value: "pnpm", label: "pnpm", hint: "recommended" },
+                    { value: "npm", label: "npm" },
+                    { value: "yarn", label: "yarn" },
+                ],
+                initialValue: "pnpm",
+            }),
+        );
+
+    const testing: TestingOption =
+        options.testing ??
+        (checkCancelled(
+            await p.confirm({
+                message: "Include testing setup (Vitest)?",
+                initialValue: true,
+            }),
+        )
+            ? "vitest"
+            : "none");
+
+    const claudeSkills =
+        options.claudeSkills ??
+        checkCancelled(
+            await p.confirm({
+                message: "Include Claude Code skills?",
+                initialValue: true,
+            }),
+        );
+
+    return { name, appId, packageManager, testing, claudeSkills };
+};
+
+const scaffoldProject = (projectPath: string, resolved: ResolvedOptions): void => {
+    const { name, appId, testing, claudeSkills } = resolved;
+    const context = createTemplateContext(name, appId, testing);
+
+    mkdirSync(projectPath, { recursive: true });
+    mkdirSync(join(projectPath, "src"), { recursive: true });
+
+    if (testing !== "none") {
+        mkdirSync(join(projectPath, "tests"), { recursive: true });
+    }
+
+    writeFileSync(join(projectPath, "package.json"), renderFile("package.json.ejs", context));
+    writeFileSync(join(projectPath, "tsconfig.json"), renderFile("tsconfig.json.ejs", context));
+    writeFileSync(join(projectPath, "src", "app.tsx"), renderFile("src/app.tsx.ejs", context));
+    writeFileSync(join(projectPath, "src", "dev.tsx"), renderFile("src/dev.tsx.ejs", context));
+    writeFileSync(join(projectPath, "src", "index.tsx"), renderFile("src/index.tsx.ejs", context));
+    writeFileSync(join(projectPath, "src", "vite-env.d.ts"), renderFile("src/vite-env.d.ts.ejs", context));
+    writeFileSync(join(projectPath, ".gitignore"), renderFile("gitignore.ejs", context));
+
+    if (claudeSkills) {
+        const skillsDir = join(projectPath, ".claude", "skills", "developing-gtkx-apps");
+        mkdirSync(skillsDir, { recursive: true });
+        writeFileSync(join(skillsDir, "SKILL.md"), renderFile("claude/SKILL.md.ejs", context));
+        writeFileSync(join(skillsDir, "WIDGETS.md"), renderFile("claude/WIDGETS.md.ejs", context));
+        writeFileSync(join(skillsDir, "EXAMPLES.md"), renderFile("claude/EXAMPLES.md.ejs", context));
+    }
+
+    if (testing === "vitest") {
+        writeFileSync(join(projectPath, "vitest.config.ts"), renderFile("config/vitest.config.ts.ejs", context));
+        writeFileSync(join(projectPath, "tests", "app.test.tsx"), renderFile("tests/app.test.tsx.ejs", context));
+    }
+};
+
+const getDevDependencies = (testing: TestingOption): string[] => {
+    const devDeps = [...DEV_DEPENDENCIES];
+    if (testing === "vitest") {
+        devDeps.push(...TESTING_DEV_DEPENDENCIES);
+    }
+    return devDeps;
+};
+
+const installDependencies = async (
+    projectPath: string,
+    name: string,
+    packageManager: PackageManager,
+    devDeps: string[],
+): Promise<void> => {
+    const installSpinner = p.spinner();
+    installSpinner.start("Installing dependencies...");
+
+    try {
+        const addCmd = getAddCommand(packageManager, DEPENDENCIES, false);
+        await runCommand(addCmd, projectPath);
+
+        const addDevCmd = getAddCommand(packageManager, devDeps, true);
+        await runCommand(addDevCmd, projectPath);
+
+        installSpinner.stop("Dependencies installed!");
+    } catch (error) {
+        installSpinner.stop("Failed to install dependencies");
+        p.log.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        p.log.info("You can install dependencies manually by running:");
+        p.log.info(`  cd ${name}`);
+        p.log.info(`  ${getAddCommand(packageManager, DEPENDENCIES, false)}`);
+        p.log.info(`  ${getAddCommand(packageManager, devDeps, true)}`);
+    }
+};
+
+const printNextSteps = (name: string, packageManager: PackageManager, testing: TestingOption): void => {
+    const runCmd = getRunCommand(packageManager);
+    const nextSteps = `cd ${name}\n${runCmd}`;
+
+    const testingNote =
+        testing !== "none"
+            ? `
+
+To run tests, you need xvfb installed:
+  Fedora: sudo dnf install xorg-x11-server-Xvfb
+  Ubuntu: sudo apt install xvfb`
+            : "";
+
+    p.note(`${nextSteps}${testingNote}`, "Next steps");
+};
+
+/**
+ * Creates a new GTKX project with interactive prompts.
+ *
+ * Scaffolds a complete project structure including:
+ * - TypeScript configuration
+ * - React component template
+ * - Development server entry point
+ * - Optional testing setup
+ * - Optional Claude Code skills
+ *
+ * @param options - Pre-filled options to skip prompts
+ *
+ * @example
+ * ```tsx
+ * import { createApp } from "@gtkx/cli";
+ *
+ * // Interactive mode
+ * await createApp();
+ *
+ * // With pre-filled options
+ * await createApp({
+ *   name: "my-app",
+ *   appId: "com.example.myapp",
+ *   packageManager: "pnpm",
+ *   testing: "vitest",
+ * });
+ * ```
+ */
+export const createApp = async (options: CreateOptions = {}): Promise<void> => {
+    p.intro("Create GTKX App");
+
+    const resolved = await promptForOptions(options);
+    const projectPath = resolve(process.cwd(), resolved.name);
+
+    const s = p.spinner();
+    s.start("Creating project structure...");
+    scaffoldProject(projectPath, resolved);
+    s.stop("Project structure created!");
+
+    const devDeps = getDevDependencies(resolved.testing);
+    await installDependencies(projectPath, resolved.name, resolved.packageManager, devDeps);
+
+    printNextSteps(resolved.name, resolved.packageManager, resolved.testing);
+};

package/src/dev-server.tsx

@@ -0,0 +1,162 @@
+import { events } from "@gtkx/ffi";
+import { setHotReloading, update } from "@gtkx/react";
+import { createServer, type InlineConfig, type ViteDevServer } from "vite";
+import { isReactRefreshBoundary, performRefresh } from "./refresh-runtime.js";
+import { gtkxAssets } from "./vite-plugin-gtkx-assets.js";
+import { gtkxRefresh } from "./vite-plugin-gtkx-refresh.js";
+import { swcSsrRefresh } from "./vite-plugin-swc-ssr-refresh.js";
+
+/**
+ * Options for the GTKX development server.
+ */
+export type DevServerOptions = {
+    /** Path to the entry file (e.g., "src/dev.tsx") */
+    entry: string;
+    /** Additional Vite configuration */
+    vite?: InlineConfig;
+};
+
+type AppModule = {
+    default: () => React.ReactNode;
+};
+
+/**
+ * Creates a Vite-based development server with hot module replacement.
+ *
+ * Provides fast refresh for React components and full reload for other changes.
+ * The server watches for file changes and automatically updates the running
+ * GTK application.
+ *
+ * @param options - Server configuration including entry point and Vite options
+ * @returns A Vite development server instance
+ *
+ * @example
+ * ```tsx
+ * import { createDevServer } from "@gtkx/cli";
+ * import { render } from "@gtkx/react";
+ *
+ * const server = await createDevServer({
+ * entry: "./src/dev.tsx",
+ * });
+ *
+ * const mod = await server.ssrLoadModule("./src/dev.tsx");
+ * render(<mod.default />, mod.appId);
+ * ```
+ *
+ * @see {@link DevServerOptions} for configuration options
+ */
+export const createDevServer = async (options: DevServerOptions): Promise<ViteDevServer> => {
+    const { entry, vite: viteConfig } = options;
+
+    const moduleExports = new Map<string, Record<string, unknown>>();
+
+    const server = await createServer({
+        ...viteConfig,
+        appType: "custom",
+        plugins: [
+            gtkxAssets(),
+            swcSsrRefresh(),
+            gtkxRefresh(),
+            {
+                name: "gtkx:remove-react-dom-optimized",
+                enforce: "post",
+                config(config) {
+                    config.optimizeDeps ??= {};
+                    config.optimizeDeps.include = config.optimizeDeps.include?.filter(
+                        (dep) => dep !== "react-dom" && !dep.startsWith("react-dom/"),
+                    );
+                },
+            },
+        ],
+        server: {
+            ...viteConfig?.server,
+            middlewareMode: true,
+        },
+        optimizeDeps: {
+            ...viteConfig?.optimizeDeps,
+            noDiscovery: true,
+            include: [],
+        },
+        ssr: {
+            ...viteConfig?.ssr,
+            external: true,
+        },
+    });
+
+    const loadModule = async (): Promise<AppModule> => {
+        const mod = (await server.ssrLoadModule(entry)) as AppModule;
+        moduleExports.set(entry, { ...mod });
+        return mod;
+    };
+
+    const invalidateAllModules = (): void => {
+        for (const module of server.moduleGraph.idToModuleMap.values()) {
+            server.moduleGraph.invalidateModule(module);
+        }
+    };
+
+    const invalidateModuleAndImporters = (filePath: string): void => {
+        const module = server.moduleGraph.getModuleById(filePath);
+
+        if (module) {
+            server.moduleGraph.invalidateModule(module);
+
+            for (const importer of module.importers) {
+                server.moduleGraph.invalidateModule(importer);
+            }
+        }
+    };
+
+    events.on("stop", () => {
+        server.close();
+    });
+
+    server.watcher.on("change", async (changedPath) => {
+        try {
+            const module = server.moduleGraph.getModuleById(changedPath);
+
+            if (!module) {
+                return;
+            }
+
+            console.log(`[gtkx] File changed: ${changedPath}`);
+
+            invalidateModuleAndImporters(changedPath);
+
+            const newMod = (await server.ssrLoadModule(changedPath)) as Record<string, unknown>;
+            moduleExports.set(changedPath, { ...newMod });
+
+            if (isReactRefreshBoundary(newMod)) {
+                console.log("[gtkx] Fast refreshing...");
+                performRefresh();
+                console.log("[gtkx] Fast refresh complete");
+                return;
+            }
+
+            console.log("[gtkx] Full reload...");
+            invalidateAllModules();
+
+            const mod = await loadModule();
+            const App = mod.default;
+
+            if (typeof App !== "function") {
+                console.error("[gtkx] Entry file must export a default function component");
+                return;
+            }
+
+            setHotReloading(true);
+            try {
+                await update(<App />);
+            } finally {
+                setHotReloading(false);
+            }
+            console.log("[gtkx] Full reload complete");
+        } catch (error) {
+            console.error("[gtkx] Hot reload failed:", error);
+        }
+    });
+
+    return server;
+};
+
+export type { ViteDevServer };

package/src/global.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    var $RefreshReg$: (type: unknown, id: string) => void;
+    var $RefreshSig$: () => (type: unknown) => unknown;
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,3 @@
+export { type BuildOptions, build } from "./builder.js";
+export { createApp } from "./create.js";
+export { createDevServer, type DevServerOptions } from "./dev-server.js";