@gtkx/cli 0.18.0 → 0.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/cli",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "CLI for GTKX - create and develop GTK4 React applications",
   "keywords": [
     "gtkx",
@@ -50,9 +50,11 @@
   "bin": {
     "gtkx": "bin/gtkx.js"
   },
+  "sideEffects": false,
   "files": [
     "bin",
     "dist",
+    "src",
     "templates"
   ],
   "dependencies": {
@@ -62,19 +64,19 @@
     "ejs": "^4.0.1",
     "react-refresh": "^0.18.0",
     "vite": "^7.3.1",
-    "@gtkx/ffi": "0.18.0",
-    "@gtkx/mcp": "0.18.0",
-    "@gtkx/react": "0.18.0"
+    "@gtkx/ffi": "0.18.2",
+    "@gtkx/mcp": "0.18.2",
+    "@gtkx/react": "0.18.2"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/react-refresh": "^0.14.7",
     "memfs": "^4.56.10",
-    "@gtkx/testing": "0.18.0"
+    "@gtkx/testing": "0.18.2"
   },
   "peerDependencies": {
     "react": "^19",
-    "@gtkx/testing": "0.18.0"
+    "@gtkx/testing": "0.18.2"
   },
   "peerDependenciesMeta": {
     "@gtkx/testing": {

package/src/builder.ts

@@ -0,0 +1,94 @@
+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";
+
+/**
+ * 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;
+};
+
+/**
+ * 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)],
+        build: {
+            ...viteConfig?.build,
+            ssr: entry,
+            ssrEmitAssets: true,
+            assetsInlineLimit: 0,
+            outDir: viteConfig?.build?.outDir ?? "dist",
+            minify: true,
+            rollupOptions: {
+                ...viteConfig?.build?.rollupOptions,
+                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,
+        },
+    });
+};

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);
+};