@gtkx/cli 0.21.0 → 1.0.0-rc.2

package/src/dev/supervisor.ts

@@ -0,0 +1,276 @@
+import { error, exitCodeForSignal, info, installGracefulShutdown } from "@gtkx/utils";
+import { fork as nodeFork } from "node:child_process";
+import { type FSWatcher, watch as watchFs } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type SupervisedChild = {
+    killed: boolean;
+    pid?: number | undefined;
+    exitCode: number | null;
+    kill(signal?: number | NodeJS.Signals): boolean;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+};
+
+type ForkRunner = (modulePath: string, args: string[], cwd: string) => SupervisedChild;
+
+type DevWatch = {
+    paths: string[];
+    regenerate: () => Promise<void>;
+};
+
+type SupervisorState = {
+    runnerPath: string;
+    entryPath: string;
+    cwd: string;
+    watch: DevWatch | undefined;
+    watchers: FSWatcher[];
+    fork: ForkRunner;
+    child: SupervisedChild | null;
+    shuttingDown: boolean;
+    restarting: boolean;
+    capturedChildExit: number | undefined;
+};
+
+type DebounceTimer = { handle: NodeJS.Timeout | null };
+
+const DEV_RUNNER_URL = new URL("../../bin/gtkx-dev-runner.js", import.meta.url);
+const FORCE_KILL_TIMEOUT_MS = 5000;
+const CONFIG_DEBOUNCE_MS = 150;
+const RESTART_EXIT_CODE = 75;
+
+const defaultForkRunner: ForkRunner = (modulePath, args, cwd) =>
+    nodeFork(modulePath, [...args], { cwd, stdio: "inherit", detached: true });
+
+const forwardSignal = (child: SupervisedChild, signal: NodeJS.Signals): void => {
+    if (!child.killed) {
+        child.kill(signal);
+    }
+};
+
+const didForceKillChild = (child: SupervisedChild | null): boolean => {
+    if (!child?.pid || child.exitCode !== null || child.killed) {
+        return false;
+    }
+
+    try {
+        return process.kill(child.pid, "SIGKILL");
+    } catch {
+        return false;
+    }
+};
+
+const captureShutdownExit = (state: SupervisorState, code: number | null, signal: NodeJS.Signals | null): void => {
+    if (code !== null) {
+        state.capturedChildExit = code;
+    } else if (signal) {
+        state.capturedChildExit = exitCodeForSignal(signal);
+    }
+};
+
+const handleChildExit = (state: SupervisorState, code: number | null, signal: NodeJS.Signals | null): void => {
+    state.child = null;
+
+    if (state.restarting) {
+        return;
+    }
+
+    if (state.shuttingDown) {
+        captureShutdownExit(state, code, signal);
+
+        return;
+    }
+
+    if (code === RESTART_EXIT_CODE) {
+        info("Restarting dev runner...");
+        launch(state);
+
+        return;
+    }
+
+    process.exit(code ?? exitCodeForSignal(signal));
+};
+
+const launch = (state: SupervisorState): void => {
+    const child = state.fork(state.runnerPath, [state.entryPath], state.cwd);
+    state.child = child;
+
+    child.on("exit", (code, signal) => {
+        handleChildExit(state, code, signal);
+    });
+};
+
+const isRestartBlocked = (state: SupervisorState): boolean => state.restarting || state.shuttingDown;
+
+const relaunchAfterExit = (state: SupervisorState): void => {
+    state.restarting = false;
+
+    if (state.shuttingDown) {
+        return;
+    }
+
+    info("Restarting dev runner...");
+    launch(state);
+};
+
+const restart = async (state: SupervisorState): Promise<void> => {
+    const watch = state.watch;
+
+    if (watch === undefined || isRestartBlocked(state)) {
+        return;
+    }
+
+    state.restarting = true;
+    info("gtkx.config.ts changed; regenerating bindings...");
+
+    try {
+        await watch.regenerate();
+    } catch (error_) {
+        error("Codegen failed; keeping the current dev runner. Fix the error and save again.", error_);
+        state.restarting = false;
+
+        return;
+    }
+
+    if (state.shuttingDown) {
+        state.restarting = false;
+
+        return;
+    }
+
+    const current = state.child;
+
+    if (current === null) {
+        state.restarting = false;
+        launch(state);
+
+        return;
+    }
+
+    current.once("exit", () => {
+        relaunchAfterExit(state);
+    });
+
+    forwardSignal(current, "SIGTERM");
+};
+
+const scheduleRestart = (state: SupervisorState, timer: DebounceTimer): void => {
+    if (timer.handle !== null) {
+        clearTimeout(timer.handle);
+    }
+
+    timer.handle = setTimeout(() => void restart(state), CONFIG_DEBOUNCE_MS);
+};
+
+const isWatchedChange = (state: SupervisorState, names: Set<string>, filename: string | Buffer | null): boolean => {
+    if (filename === null || state.shuttingDown) {
+        return false;
+    }
+
+    return names.has(basename(filename.toString()));
+};
+
+const groupWatchNamesByDirectory = (paths: string[]): Map<string, Set<string>> => {
+    const namesByDirectory: Map<string, Set<string>> = new Map();
+
+    for (const path of paths) {
+        const directory = dirname(path);
+        const names = namesByDirectory.get(directory) ?? new Set<string>();
+        names.add(basename(path));
+        namesByDirectory.set(directory, names);
+    }
+
+    return namesByDirectory;
+};
+
+const watchConfigDirectory = (
+    state: SupervisorState,
+    directory: string,
+    names: Set<string>,
+    timer: DebounceTimer,
+): void => {
+    const watcher = watchFs(directory, (_event, filename) => {
+        if (isWatchedChange(state, names, filename)) {
+            scheduleRestart(state, timer);
+        }
+    });
+
+    watcher.on("error", (): void => undefined);
+    state.watchers.push(watcher);
+};
+
+const installConfigWatchers = (state: SupervisorState): void => {
+    const watch = state.watch;
+
+    if (watch === undefined || watch.paths.length === 0) {
+        return;
+    }
+
+    const timer: DebounceTimer = { handle: null };
+
+    for (const [directory, names] of groupWatchNamesByDirectory(watch.paths)) {
+        watchConfigDirectory(state, directory, names, timer);
+    }
+};
+
+const closeWatchers = (state: SupervisorState): void => {
+    for (const watcher of state.watchers) {
+        watcher.close();
+    }
+};
+
+const shutdownOnSignal = (state: SupervisorState, signal: NodeJS.Signals): Promise<void> =>
+    new Promise<void>((resolve) => {
+        state.shuttingDown = true;
+        closeWatchers(state);
+
+        if (!state.child) {
+            resolve();
+
+            return;
+        }
+
+        state.child.once("exit", () => {
+            resolve();
+        });
+
+        forwardSignal(state.child, signal);
+    });
+
+const installShutdown = (state: SupervisorState): void => {
+    installGracefulShutdown({
+        onSignal: (signal) => shutdownOnSignal(state, signal),
+        onForce: () => didForceKillChild(state.child),
+        forceKillAfterMs: FORCE_KILL_TIMEOUT_MS,
+        exitCode: (signal, graceful) => state.capturedChildExit ?? (graceful ? 0 : exitCodeForSignal(signal)),
+    });
+};
+
+const runDevSupervisor = async (
+    entryPath: string,
+    cwd: string,
+    watch?: DevWatch,
+    fork: ForkRunner = defaultForkRunner,
+): Promise<never> => {
+    const state: SupervisorState = {
+        runnerPath: fileURLToPath(DEV_RUNNER_URL),
+        entryPath,
+        cwd,
+        watch,
+        watchers: [],
+        fork,
+        child: null,
+        shuttingDown: false,
+        restarting: false,
+        capturedChildExit: undefined,
+    };
+
+    installConfigWatchers(state);
+    installShutdown(state);
+    launch(state);
+
+    return new Promise<never>((): void => undefined);
+};
+
+export { RESTART_EXIT_CODE, defaultForkRunner, runDevSupervisor, type SupervisedChild, type ForkRunner, type DevWatch };

package/src/dev/vite-dev-server.ts

@@ -0,0 +1,36 @@
+import type { InlineConfig, Plugin } from "vite";
+
+type DevServerModule = object;
+
+type DevServerChangedModule = DevServerModule & {
+    importers: Iterable<DevServerModule>;
+    ssrModule?: Record<string, unknown> | null;
+};
+
+type DevServerModuleGraph = {
+    getModuleById(id: string): DevServerChangedModule | undefined;
+    invalidateModule(module: DevServerModule): void;
+};
+
+type DevServer = {
+    close(): Promise<void>;
+    moduleGraph: DevServerModuleGraph;
+    ssrLoadModule(id: string): Promise<Record<string, unknown>>;
+    watcher: {
+        on(event: "change", listener: (changedPath: string) => void): void;
+    };
+};
+
+const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig => ({
+    root,
+    appType: "custom",
+    plugins,
+    server: { middlewareMode: true },
+    optimizeDeps: { noDiscovery: true, include: [] },
+    ssr: {
+        external: true,
+        noExternal: [/^@gtkx\/(?!(?:native|gi|gl|runtime|utils|css)(?:\/|$))/, /[/\\]\.gtkx[/\\]/],
+    },
+});
+
+export { createDevServerConfig, type DevServer };

package/src/internal/banner.ts

@@ -0,0 +1,13 @@
+import type { Rollup } from "vite";
+
+const prependBanner = (options: Rollup.OutputOptions, banner: string): Rollup.OutputOptions => {
+    const existing = options.banner;
+
+    if (typeof existing === "function") {
+        return { ...options, banner: async (chunk) => `${banner}\n${await existing(chunk)}` };
+    }
+
+    return { ...options, banner: existing ? `${banner}\n${existing}` : banner };
+};
+
+export { prependBanner };

package/src/internal/data-dir.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const DATA_IMPORT_PREFIX = "#data";
+const DATA_IMPORT_KEY = `${DATA_IMPORT_PREFIX}/*`;
+const CONDITION_PRIORITY = ["default", "import", "node"] as const;
+const DATA_TARGET_PATTERN = /^\.?\/?(.+?)\/\*$/;
+
+const isConditionMap = (entry: unknown): entry is Record<string, unknown> =>
+    entry !== null && typeof entry === "object" && !Array.isArray(entry);
+
+const conditionTarget = (conditions: Record<string, unknown>): string | null => {
+    for (const condition of CONDITION_PRIORITY) {
+        const value = conditions[condition];
+
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+
+    return null;
+};
+
+const targetString = (entry: unknown): string | null => {
+    if (typeof entry === "string") {
+        return entry;
+    }
+
+    if (isConditionMap(entry)) {
+        return conditionTarget(entry);
+    }
+
+    return null;
+};
+
+const directoryFromTarget = (target: string): string | null => {
+    const match = DATA_TARGET_PATTERN.exec(target);
+
+    return match?.[1] ?? null;
+};
+
+const resolveDataDir = (root: string): string | null => {
+    let manifest: unknown;
+
+    try {
+        manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    } catch {
+        return null;
+    }
+
+    if (!isConditionMap(manifest)) {
+        return null;
+    }
+
+    const imports = manifest.imports;
+
+    if (!isConditionMap(imports)) {
+        return null;
+    }
+
+    const target = targetString(imports[DATA_IMPORT_KEY]);
+
+    if (target === null) {
+        return null;
+    }
+
+    return directoryFromTarget(target);
+};
+
+export { DATA_IMPORT_PREFIX, resolveDataDir };

package/src/internal/entry-arg.ts

@@ -0,0 +1,46 @@
+import type { PositionalArgDef, StringArgDef } from "citty";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const DEFAULT_ENTRY_BASE = "src/index";
+const DEFAULT_ENTRY_EXTENSION = ".tsx";
+const DEFAULT_ENTRY_EXTENSIONS = [DEFAULT_ENTRY_EXTENSION, ".jsx", ".ts", ".js"];
+const DEFAULT_ENTRY = `${DEFAULT_ENTRY_BASE}{${DEFAULT_ENTRY_EXTENSIONS.join(",")}}`;
+
+const cwdArg: { cwd: StringArgDef } = {
+    cwd: {
+        type: "string",
+        description: "Project root (default: current working directory)",
+    },
+};
+
+const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
+    entry: {
+        type: "positional",
+        description: `Entry file (default: ${DEFAULT_ENTRY})`,
+        required: false,
+    },
+    ...cwdArg,
+};
+
+const resolveCwd = (args: { cwd?: string }): string => (args.cwd ? resolve(args.cwd) : process.cwd());
+
+const resolveDefaultEntry = (cwd: string): string => {
+    for (const extension of DEFAULT_ENTRY_EXTENSIONS) {
+        const candidate = resolve(cwd, `${DEFAULT_ENTRY_BASE}${extension}`);
+
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+
+    return resolve(cwd, `${DEFAULT_ENTRY_BASE}${DEFAULT_ENTRY_EXTENSION}`);
+};
+
+const resolveEntry = (args: { entry?: string; cwd?: string }): { cwd: string; entry: string } => {
+    const cwd = resolveCwd(args);
+
+    return { cwd, entry: args.entry ? resolve(cwd, args.entry) : resolveDefaultEntry(cwd) };
+};
+
+export { cwdArg, entryArg, resolveCwd, resolveEntry };

package/src/internal/errors.ts

@@ -0,0 +1,36 @@
+import type { ArgsDef, CommandDef } from "citty";
+import { logger } from "@gtkx/utils";
+
+const ERROR_EXIT_CODE = 1;
+
+const printError = (cause: unknown): never => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    logger.error(message);
+
+    if (cause instanceof Error && cause.stack !== undefined) {
+        logger.debug(cause.stack);
+    }
+
+    process.exit(ERROR_EXIT_CODE);
+};
+
+const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDef<T> => {
+    const run = command.run;
+
+    if (run === undefined) {
+        return command;
+    }
+
+    return {
+        ...command,
+        run: async (context): Promise<unknown> => {
+            try {
+                return await run(context);
+            } catch (error) {
+                return printError(error);
+            }
+        },
+    };
+};
+
+export { printError, withErrorBoundary };

package/src/internal/list-files.ts

@@ -0,0 +1,23 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+type ListedFile = {
+    absPath: string;
+    rel: string;
+};
+
+const listFilesRecursive = (dir: string, shouldInclude?: (name: string) => boolean): ListedFile[] => {
+    if (!existsSync(dir)) {
+        return [];
+    }
+
+    return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && (shouldInclude === undefined || shouldInclude(entry.name)))
+        .map((entry) => {
+            const absPath = join(entry.parentPath, entry.name);
+
+            return { absPath, rel: relative(dir, absPath) };
+        });
+};
+
+export { listFilesRecursive, type ListedFile };

package/src/internal/resolve-cli-tool.ts

@@ -0,0 +1,37 @@
+import { existsSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+const resolveCliTool = (() => {
+    const cache: Map<string, string> = new Map();
+
+    return (executable: string): string => {
+        const cached = cache.get(executable);
+
+        if (cached) {
+            return cached;
+        }
+
+        const resolved = findInPath(executable);
+        cache.set(executable, resolved);
+
+        return resolved;
+    };
+})();
+
+const isExecutableFile = (candidate: string): boolean => existsSync(candidate) && statSync(candidate).isFile();
+
+const findInPath = (executable: string): string => {
+    const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+
+    for (const dir of dirs) {
+        const candidate = join(dir, executable);
+
+        if (isExecutableFile(candidate)) {
+            return candidate;
+        }
+    }
+
+    throw new Error(`${executable} not found in PATH`);
+};
+
+export { resolveCliTool };

package/src/internal/staging-dir.ts

@@ -0,0 +1,19 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const removeTempDir = (dir: string): void => {
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5 });
+};
+
+const withStagingDir = <T>(prefix: string, produce: (dir: string) => T): T => {
+    const dir = mkdtempSync(join(tmpdir(), `gtkx-${prefix}-`));
+
+    try {
+        return produce(dir);
+    } finally {
+        removeTempDir(dir);
+    }
+};
+
+export { removeTempDir, withStagingDir };

package/src/internal/xdg-data-dirs.ts

@@ -0,0 +1,13 @@
+const XDG_DATA_DIRS_DEFAULT = "/usr/local/share:/usr/share";
+
+const prependXdgDataDir = (dir: string, existing: string | undefined): string => {
+    const base = existing === undefined || existing.length === 0 ? XDG_DATA_DIRS_DEFAULT : existing;
+
+    if (base.split(":").includes(dir)) {
+        return base;
+    }
+
+    return `${dir}:${base}`;
+};
+
+export { prependXdgDataDir };