@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/dev/supervisor.ts

@@ -3,6 +3,7 @@ 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";
+import { DEV_ENTRY_ENV } from "./entry-env.js";
 
 type SupervisedChild = {
     killed: boolean;
@@ -13,7 +14,7 @@ type SupervisedChild = {
     once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
 };
 
-type ForkRunner = (modulePath: string, args: string[], cwd: string) => SupervisedChild;
+type ForkRunner = (modulePath: string, args: string[], env: NodeJS.ProcessEnv, cwd: string) => SupervisedChild;
 
 type DevWatch = {
     paths: string[];
@@ -24,6 +25,7 @@ type SupervisorState = {
     runnerPath: string;
     entryPath: string;
     cwd: string;
+    args: string[];
     watch: DevWatch | undefined;
     watchers: FSWatcher[];
     fork: ForkRunner;
@@ -33,15 +35,45 @@ type SupervisorState = {
     capturedChildExit: number | undefined;
 };
 
+type DevSupervisorOptions = {
+    entryPath: string;
+    cwd: string;
+    args?: string[] | undefined;
+    watch?: DevWatch | undefined;
+    fork?: ForkRunner | 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 CONDITION_FLAG = /^(?:--conditions|-C)(?:=.*)?$/;
+const SPLIT_CONDITION_FLAG = /^(?:--conditions|-C)$/;
+
+const withoutConditions = (argv: string[]): string[] =>
+    argv.filter(
+        (argument, index) => !CONDITION_FLAG.test(argument) && !SPLIT_CONDITION_FLAG.test(argv[index - 1] ?? ""),
+    );
+
+const getNodeOptions = (env: NodeJS.ProcessEnv): string | undefined => {
+    const options = env.NODE_OPTIONS;
+
+    return options === undefined ? undefined : withoutConditions(options.split(/\s+/)).join(" ");
+};
 
-const defaultForkRunner: ForkRunner = (modulePath, args, cwd) =>
-    nodeFork(modulePath, [...args], { cwd, stdio: "inherit", detached: true });
+const defaultForkRunner: ForkRunner = (modulePath, args, env, cwd) => {
+    const nodeOptions = getNodeOptions(env);
+
+    return nodeFork(modulePath, args, {
+        cwd,
+        env: { ...env, ...(nodeOptions !== undefined && { NODE_OPTIONS: nodeOptions }) },
+        stdio: "inherit",
+        detached: true,
+        execArgv: withoutConditions(process.execArgv),
+    });
+};
 
 const forwardSignal = (child: SupervisedChild, signal: NodeJS.Signals): void => {
     if (!child.killed) {
@@ -93,7 +125,13 @@ const handleChildExit = (state: SupervisorState, code: number | null, signal: No
 };
 
 const launch = (state: SupervisorState): void => {
-    const child = state.fork(state.runnerPath, [state.entryPath], state.cwd);
+    const child = state.fork(
+        state.runnerPath,
+        state.args,
+        { ...process.env, [DEV_ENTRY_ENV]: state.entryPath },
+        state.cwd,
+    );
+
     state.child = child;
 
     child.on("exit", (code, signal) => {
@@ -247,16 +285,14 @@ const installShutdown = (state: SupervisorState): void => {
     });
 };
 
-const runDevSupervisor = async (
-    entryPath: string,
-    cwd: string,
-    watch?: DevWatch,
-    fork: ForkRunner = defaultForkRunner,
-): Promise<never> => {
+const runDevSupervisor = async (options: DevSupervisorOptions): Promise<never> => {
+    const { entryPath, cwd, args = [], watch, fork = defaultForkRunner } = options;
+
     const state: SupervisorState = {
         runnerPath: fileURLToPath(DEV_RUNNER_URL),
         entryPath,
         cwd,
+        args,
         watch,
         watchers: [],
         fork,
@@ -273,4 +309,8 @@ const runDevSupervisor = async (
     return new Promise<never>((): void => undefined);
 };
 
-export { RESTART_EXIT_CODE, defaultForkRunner, runDevSupervisor, type SupervisedChild, type ForkRunner, type DevWatch };
+export {
+    RESTART_EXIT_CODE,
+    runDevSupervisor,
+    type DevWatch,
+};

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

@@ -1,10 +1,13 @@
 import type { InlineConfig, Plugin } from "vite";
+import { join } from "node:path";
 
 type DevServerModule = object;
+type DevServerWatchEvent = "add" | "change" | "unlink";
 
 type DevServerChangedModule = DevServerModule & {
     importers: Iterable<DevServerModule>;
     ssrModule?: Record<string, unknown> | null;
+    ssrTransformResult?: object | null;
 };
 
 type DevServerModuleGraph = {
@@ -12,20 +15,62 @@ type DevServerModuleGraph = {
     invalidateModule(module: DevServerModule): void;
 };
 
+type DevServerConfig = {
+    configFile: string | undefined;
+    configFileDependencies: string[];
+    envDir: string | false;
+    mode: string;
+};
+
 type DevServer = {
     close(): Promise<void>;
+    config: DevServerConfig;
     moduleGraph: DevServerModuleGraph;
     ssrLoadModule(id: string): Promise<Record<string, unknown>>;
+    ssrFixStacktrace(cause: Error): void;
     watcher: {
-        on(event: "change", listener: (changedPath: string) => void): void;
+        on(event: DevServerWatchEvent, listener: (changedPath: string) => void): void;
     };
 };
 
+const WRITE_STABILITY_THRESHOLD_MS = 50;
+const WRITE_POLL_INTERVAL_MS = 10;
+const ENV_FILE_SUFFIXES = ["", ".local"];
+
+const envFilesForMode = (config: DevServerConfig): string[] => {
+    const envDir = config.envDir;
+
+    if (envDir === false) {
+        return [];
+    }
+
+    return ENV_FILE_SUFFIXES.flatMap((suffix) => [
+        join(envDir, `.env${suffix}`),
+        join(envDir, `.env.${config.mode}${suffix}`),
+    ]);
+};
+
+const isServerConfigFile = (config: DevServerConfig, changedPath: string): boolean => {
+    if (changedPath === config.configFile || config.configFileDependencies.includes(changedPath)) {
+        return true;
+    }
+
+    return envFilesForMode(config).includes(changedPath);
+};
+
 const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig => ({
     root,
     appType: "custom",
     plugins,
-    server: { middlewareMode: true },
+    server: {
+        middlewareMode: true,
+        watch: {
+            awaitWriteFinish: {
+                stabilityThreshold: WRITE_STABILITY_THRESHOLD_MS,
+                pollInterval: WRITE_POLL_INTERVAL_MS,
+            },
+        },
+    },
     optimizeDeps: { noDiscovery: true, include: [] },
     ssr: {
         external: true,
@@ -33,4 +78,10 @@ const createDevServerConfig = (root: string, plugins: Plugin[]): InlineConfig =>
     },
 });
 
-export { createDevServerConfig, type DevServer };
+export {
+    createDevServerConfig,
+    type DevServer,
+    type DevServerChangedModule,
+    type DevServerWatchEvent,
+    isServerConfigFile,
+};

package/src/internal/application-args.ts

@@ -0,0 +1,13 @@
+const APPLICATION_ARGS_SEPARATOR = "--";
+
+const splitApplicationArgs = (argv: string[]): { cliArgs: string[]; applicationArgs: string[] } => {
+    const separator = argv.indexOf(APPLICATION_ARGS_SEPARATOR);
+
+    if (separator === -1) {
+        return { cliArgs: argv, applicationArgs: [] };
+    }
+
+    return { cliArgs: argv.slice(0, separator), applicationArgs: argv.slice(separator + 1) };
+};
+
+export { splitApplicationArgs };

package/src/internal/entry-arg.ts

@@ -1,10 +1,10 @@
 import type { PositionalArgDef, StringArgDef } from "citty";
-import { existsSync } from "node:fs";
+import { statSync } 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_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js"];
+const DEFAULT_ENTRY_CANDIDATES = DEFAULT_ENTRY_EXTENSIONS.map((extension) => `${DEFAULT_ENTRY_BASE}${extension}`);
 const DEFAULT_ENTRY = `${DEFAULT_ENTRY_BASE}{${DEFAULT_ENTRY_EXTENSIONS.join(",")}}`;
 
 const cwdArg: { cwd: StringArgDef } = {
@@ -24,23 +24,37 @@ const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
 };
 
 const resolveCwd = (args: { cwd?: string }): string => (args.cwd ? resolve(args.cwd) : process.cwd());
+const isFile = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isFile() === true;
+
+const missingDefaultEntryError = (cwd: string): Error =>
+    new Error(
+        `No entry file found in ${cwd}. Looked for ${DEFAULT_ENTRY_CANDIDATES.join(", ")}; ` +
+        "pass the entry file as an argument.",
+    );
 
 const resolveDefaultEntry = (cwd: string): string => {
-    for (const extension of DEFAULT_ENTRY_EXTENSIONS) {
-        const candidate = resolve(cwd, `${DEFAULT_ENTRY_BASE}${extension}`);
+    for (const candidate of DEFAULT_ENTRY_CANDIDATES) {
+        const path = resolve(cwd, candidate);
 
-        if (existsSync(candidate)) {
-            return candidate;
+        if (isFile(path)) {
+            return path;
         }
     }
 
-    return resolve(cwd, `${DEFAULT_ENTRY_BASE}${DEFAULT_ENTRY_EXTENSION}`);
+    throw missingDefaultEntryError(cwd);
 };
 
-const resolveEntry = (args: { entry?: string; cwd?: string }): { cwd: string; entry: string } => {
-    const cwd = resolveCwd(args);
+const resolveGivenEntry = (cwd: string, entry: string): string => {
+    const path = resolve(cwd, entry);
+
+    if (!isFile(path)) {
+        throw new Error(`No entry file at ${path}.`);
+    }
 
-    return { cwd, entry: args.entry ? resolve(cwd, args.entry) : resolveDefaultEntry(cwd) };
+    return path;
 };
 
+const resolveEntry = (cwd: string, entry: string | undefined): string =>
+    entry ? resolveGivenEntry(cwd, entry) : resolveDefaultEntry(cwd);
+
 export { cwdArg, entryArg, resolveCwd, resolveEntry };

package/src/internal/errors.ts

@@ -33,4 +33,4 @@ const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDe
     };
 };
 
-export { printError, withErrorBoundary };
+export { withErrorBoundary };

package/src/internal/module-loads.ts

@@ -0,0 +1,32 @@
+type ModuleLoader = {
+    ssrLoadModule(id: string): Promise<Record<string, unknown>>;
+};
+
+const loadChains: WeakMap<object, Promise<void>> = new WeakMap();
+
+const settled = async (load: Promise<unknown>): Promise<void> => {
+    try {
+        await load;
+    } catch {
+        return;
+    }
+};
+
+const withExclusiveLoad = <T>(server: object, run: () => Promise<T>): Promise<T> => {
+    const pending = loadChains.get(server) ?? Promise.resolve();
+
+    const result = (async (): Promise<T> => {
+        await pending;
+
+        return run();
+    })();
+
+    loadChains.set(server, settled(result));
+
+    return result;
+};
+
+const loadModuleExclusively = (server: ModuleLoader, id: string): Promise<Record<string, unknown>> =>
+    withExclusiveLoad(server, () => server.ssrLoadModule(id));
+
+export { loadModuleExclusively, withExclusiveLoad };

package/src/internal/prepare-project.ts

@@ -0,0 +1,23 @@
+import { ensureGeneratedIn } from "../codegen/run-codegen.js";
+import { type CodegenContext, resolveCodegenContext } from "../codegen/store-resolver.js";
+import { resolveCwd, resolveEntry } from "./entry-arg.js";
+
+type ProjectArgs = { entry?: string; cwd?: string };
+type PreparedProject = { cwd: string; entry: string };
+type ResolvedProject = PreparedProject & { context: CodegenContext };
+
+const resolveProject = async (args: ProjectArgs, mode: string): Promise<ResolvedProject> => {
+    const cwd = resolveCwd(args);
+    const context = await resolveCodegenContext(cwd, mode);
+
+    return { cwd, entry: resolveEntry(cwd, args.entry), context };
+};
+
+const prepareProject = async (args: ProjectArgs, mode: string): Promise<PreparedProject> => {
+    const { cwd, entry, context } = await resolveProject(args, mode);
+    await ensureGeneratedIn(context, { shouldAnnounce: true, mode });
+
+    return { cwd, entry };
+};
+
+export { prepareProject, resolveProject };

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

@@ -0,0 +1,38 @@
+import { formatChildProcessError, resolveExecutable } from "@gtkx/utils";
+import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
+
+type CliToolInvocation = {
+    tool: string;
+    args: string[];
+    target?: string;
+    shouldStream?: boolean;
+    options?: ExecFileSyncOptions;
+};
+
+const streamingOptions = (options: ExecFileSyncOptions | undefined): ExecFileSyncOptions => ({
+    ...options,
+    stdio: "inherit",
+});
+
+const optionsFor = (shouldStream: boolean | undefined, options: ExecFileSyncOptions | undefined): ExecFileSyncOptions |
+    undefined => (shouldStream === true ? streamingOptions(options) : options);
+
+const failureMessage = (tool: string, target: string | undefined, error: unknown): string => {
+    const details = formatChildProcessError(error);
+    const suffix = details ? `:\n${details}` : "";
+    const subject = target === undefined ? "" : ` for ${target}`;
+
+    return `${tool} failed${subject}${suffix}`;
+};
+
+const runCliTool = ({ tool, args, target, shouldStream, options }: CliToolInvocation): void => {
+    const executable = resolveExecutable(tool);
+
+    try {
+        execFileSync(executable, args, optionsFor(shouldStream, options));
+    } catch (error) {
+        throw new Error(failureMessage(tool, target, error), { cause: error });
+    }
+};
+
+export { runCliTool };

package/src/internal/staging-dir.ts

@@ -2,12 +2,21 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+type RetainedStagingDir = {
+    getPath: () => string | null;
+    adopt: (dir: string) => string;
+    retain: () => string;
+    release: () => void;
+};
+
 const removeTempDir = (dir: string): void => {
     rmSync(dir, { recursive: true, force: true, maxRetries: 5 });
 };
 
+const createStagingDir = (prefix: string): string => mkdtempSync(join(tmpdir(), `gtkx-${prefix}-`));
+
 const withStagingDir = <T>(prefix: string, produce: (dir: string) => T): T => {
-    const dir = mkdtempSync(join(tmpdir(), `gtkx-${prefix}-`));
+    const dir = createStagingDir(prefix);
 
     try {
         return produce(dir);
@@ -16,4 +25,50 @@ const withStagingDir = <T>(prefix: string, produce: (dir: string) => T): T => {
     }
 };
 
-export { removeTempDir, withStagingDir };
+const createRetainedStagingDir = (prefix: string): RetainedStagingDir => {
+    let path: string | null = null;
+    let cleanupProcessExit: (() => void) | null = null;
+
+    const release = (): void => {
+        if (path !== null && cleanupProcessExit) {
+            removeTempDir(path);
+            process.removeListener("exit", cleanupProcessExit);
+            cleanupProcessExit = null;
+        }
+
+        path = null;
+    };
+
+    const retain = (): string => {
+        if (path !== null) {
+            return path;
+        }
+
+        const dir = createStagingDir(prefix);
+        path = dir;
+
+        cleanupProcessExit = (): void => {
+            removeTempDir(dir);
+        };
+
+        process.once("exit", cleanupProcessExit);
+
+        return dir;
+    };
+
+    const adopt = (dir: string): string => {
+        release();
+        path = dir;
+
+        return dir;
+    };
+
+    return {
+        getPath: () => path,
+        adopt,
+        retain,
+        release,
+    };
+};
+
+export { createRetainedStagingDir, removeTempDir, type RetainedStagingDir, withStagingDir };

package/src/mcp/client.ts

@@ -232,4 +232,4 @@ class McpClient {
     }
 }
 
-export { McpClient, type McpClientOptions };
+export { McpClient };