alepha 0.15.0 → 0.15.2

package/src/cli/providers/ViteDevServerProvider.ts

@@ -0,0 +1,378 @@
+import { $inject, type Alepha, AlephaError } from "alepha";
+import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
+import { importVite, importViteReact, viteAlephaSsrPreload } from "alepha/vite";
+import type { InlineConfig, Plugin, ViteDevServer } from "vite";
+import { ViteUtils } from "../services/ViteUtils.ts";
+import type { AppEntry } from "./AppEntryProvider.ts";
+
+export interface ViteDevServerOptions {
+  /**
+   * Root directory of the project.
+   */
+  root: string;
+
+  /**
+   * Path to the server entry file.
+   */
+  entry: AppEntry;
+
+  /**
+   * Port to run the dev server on.
+   */
+  port?: number;
+
+  /**
+   * Host to bind the dev server to.
+   */
+  host?: string | boolean;
+}
+
+/**
+ * Vite development server with Alepha integration.
+ *
+ * Architecture:
+ * - Vite runs in middleware mode (no HTTP server)
+ * - Alepha is the HTTP server via server:onRequest event
+ * - Request flow: Page requests → Alepha SSR, Assets → Vite middleware
+ *
+ * HMR Strategy:
+ * - Browser-only changes (CSS, client components) → Vite HMR (React Fast Refresh)
+ * - Server-only changes → Restart Alepha → Full browser reload
+ * - Shared changes → Restart Alepha → Let Vite HMR propagate
+ *
+ * Features:
+ * - Automatic .env reload detection
+ * - Error recovery on next file change
+ * - Optimized module invalidation (only changed files + importers)
+ */
+export class ViteDevServerProvider {
+  protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly templateProvider = $inject(ViteUtils);
+  protected server!: ViteDevServer;
+  protected options!: ViteDevServerOptions;
+  protected alepha: Alepha | null = null;
+  protected hasError = false;
+  protected changedFiles = new Set<string>();
+
+  public async init(options: ViteDevServerOptions): Promise<Alepha> {
+    this.options = options;
+    await this.createViteServer();
+    return await this.loadAlepha(true);
+  }
+
+  public async start(): Promise<void> {
+    await this.alepha?.start();
+  }
+
+  /**
+   * Create the Vite server in middleware mode.
+   */
+  protected async createViteServer(): Promise<void> {
+    const { createServer } = await importVite();
+    const viteReact = await importViteReact();
+
+    const plugins: Plugin[] = [];
+    if (viteReact) plugins.push(viteReact());
+    plugins.push(viteAlephaSsrPreload());
+    plugins.push(this.createHmrPlugin());
+
+    this.server = await createServer({
+      root: this.options.root,
+      plugins,
+      server: { middlewareMode: true },
+      appType: "custom",
+      customLogger: {
+        info: () => {},
+        warn: this.log.warn.bind(this.log),
+        error: this.log.error.bind(this.log),
+        warnOnce: this.log.warn.bind(this.log),
+        clearScreen: () => {},
+        hasWarned: false,
+        hasErrorLogged: () => false,
+      },
+    } satisfies InlineConfig);
+
+    // Intercept .env changes (Vite calls restart() for .env files)
+    this.server.restart = async () => {
+      const startTime = Date.now();
+      try {
+        this.hasError = true; // Force full invalidation for env changes
+        await this.loadAlepha(false);
+        await this.alepha?.start();
+        this.log.debug(`Env reloaded in ${Date.now() - startTime}ms`);
+        this.sendBrowserReload();
+      } catch (err) {
+        this.hasError = true;
+        this.log.error("Reload failed", err);
+        this.log.warn("Waiting for file changes to retry...");
+        this.alepha = null;
+      }
+    };
+  }
+
+  /**
+   * Vite plugin to handle HMR for Alepha.
+   */
+  protected createHmrPlugin(): Plugin {
+    return {
+      name: "alepha-hmr",
+      handleHotUpdate: async (ctx) => {
+        if (ctx.file.includes("/.idea/")) return [];
+
+        const firstModule = ctx.modules[0] as any;
+        const isBrowserOnly = firstModule && !firstModule._ssrModule;
+        const isServerOnly = firstModule && !firstModule._clientModule;
+
+        // Browser-only: let Vite HMR handle it (React Fast Refresh)
+        if (isBrowserOnly) return;
+
+        // Server or shared change: restart Alepha
+        const startTime = Date.now();
+
+        try {
+          this.changedFiles.add(ctx.file);
+          await this.loadAlepha(false);
+          await this.alepha?.start();
+          this.log.debug(`Reloaded in ${Date.now() - startTime}ms`);
+
+          // Server-only: full browser reload
+          if (isServerOnly) {
+            this.sendBrowserReload();
+            return [];
+          }
+
+          // Shared: let HMR propagate to browser
+          return;
+        } catch (err) {
+          this.hasError = true;
+          this.log.error("Reload failed", err);
+          this.log.warn("Waiting for file changes to retry...");
+          this.alepha = null;
+          return [];
+        }
+      },
+    };
+  }
+
+  /**
+   * Send browser reload signal via custom event.
+   * Browser listens for 'alepha:reload' and does window.location.reload()
+   */
+  protected sendBrowserReload(): void {
+    this.server.ws.send({
+      type: "custom",
+      event: "alepha:reload",
+      data: {},
+    });
+  }
+
+  /**
+   * Setup environment variables for dev mode.
+   */
+  protected async setupEnvironment(): Promise<void> {
+    const { loadEnv } = await importVite();
+    const mode = process.env.NODE_ENV || "development";
+    const env = loadEnv(mode, this.options.root, "");
+
+    // Merge into process.env (only set if not already defined)
+    for (const [key, value] of Object.entries(env)) {
+      process.env[key] ??= value;
+    }
+
+    process.env.NODE_ENV ??= "development";
+    process.env.VITE_ALEPHA_DEV = "true";
+    process.env.SERVER_HOST ??= this.options.host?.toString() ?? "localhost";
+    process.env.SERVER_PORT ??= String(
+      this.options.port ??
+        (process.env.SERVER_PORT ? Number(process.env.SERVER_PORT) : 3000),
+    );
+  }
+
+  /**
+   * Load or reload the Alepha instance.
+   */
+  protected async loadAlepha(isInitialLoad = false): Promise<Alepha> {
+    if (this.alepha) {
+      await this.alepha
+        .stop()
+        .catch((err) => this.log.warn("Error stopping Alepha", err));
+      this.alepha = null;
+    }
+
+    if (isInitialLoad || this.hasError) {
+      this.server.moduleGraph.invalidateAll();
+    } else {
+      this.invalidateModulesWithImporters();
+    }
+    this.changedFiles.clear();
+
+    // Snapshot and restore process.env to isolate each reload
+    const envSnapshot = { ...process.env };
+    await this.setupEnvironment();
+
+    await this.server.ssrLoadModule(this.options.entry.server);
+
+    const alepha: Alepha = (globalThis as any).__alepha;
+    if (!alepha) {
+      throw new AlephaError(
+        "Alepha instance not found after loading entry module",
+      );
+    }
+
+    this.alepha = alepha;
+    await this.setupAlepha();
+
+    this.hasError = false;
+    process.env = envSnapshot;
+
+    return alepha;
+  }
+
+  public hasReact(): boolean {
+    try {
+      this.alepha?.inject("ReactServerProvider");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Setup Alepha instance with Vite middleware and template.
+   */
+  protected async setupAlepha(): Promise<void> {
+    if (!this.alepha || !this.hasReact()) {
+      return;
+    }
+
+    const template = await this.server.transformIndexHtml(
+      "/",
+      this.templateProvider.generateIndexHtml(this.options.entry),
+    );
+
+    this.alepha.store.set("alepha.react.server.template", template);
+
+    this.alepha.events.on("server:onRequest", {
+      priority: "first",
+      callback: async ({ request }) => {
+        const node = request.raw.node;
+        if (!node || this.isPageRequest(node.req)) return;
+
+        const handled = await this.runViteMiddleware(
+          node.req,
+          node.res,
+          request,
+        );
+        if (handled) {
+          request.reply.status = node.res.statusCode || 200;
+          request.reply.body = null;
+        }
+      },
+    });
+  }
+
+  /**
+   * Check if request is for an HTML page (not an asset).
+   */
+  protected isPageRequest(req: any): boolean {
+    const url = req.url || "/";
+
+    // Root and index.html are page requests
+    if (url === "/" || url === "/index.html") return true;
+
+    // Vite internal routes
+    if (url.startsWith("/@") || url.startsWith("/__vite")) return false;
+
+    // Files with extensions are assets
+    if (/\.\w+$/.test(url.split("?")[0])) return false;
+
+    return true;
+  }
+
+  /**
+   * Run Vite middleware and detect if it handled the request.
+   */
+  protected async runViteMiddleware(
+    req: any,
+    res: any,
+    ctx: { metadata: any },
+  ): Promise<boolean> {
+    // Skip if response already started
+    if (res.headersSent || res.writableEnded) {
+      return false;
+    }
+
+    return new Promise((resolve) => {
+      let resolved = false;
+
+      const done = (handled: boolean) => {
+        if (resolved) return;
+        resolved = true;
+        if (handled) ctx.metadata.vite = true;
+        resolve(handled);
+      };
+
+      // Wrap response to prevent writes after we've resolved
+      const originalSetHeader = res.setHeader.bind(res);
+      const originalWriteHead = res.writeHead?.bind(res);
+      const originalWrite = res.write.bind(res);
+      const originalEnd = res.end.bind(res);
+
+      const guardedCall = <T>(fn: (...args: any[]) => T, ...args: any[]): T => {
+        if (resolved && !ctx.metadata.vite) {
+          // Vite didn't handle this request, silently ignore late writes
+          return undefined as T;
+        }
+        return fn(...args);
+      };
+
+      res.setHeader = (...args: any[]) =>
+        guardedCall(originalSetHeader, ...args);
+      if (originalWriteHead) {
+        res.writeHead = (...args: any[]) =>
+          guardedCall(originalWriteHead, ...args);
+      }
+      res.write = (...args: any[]) => guardedCall(originalWrite, ...args);
+      res.end = (...args: any[]) => guardedCall(originalEnd, ...args);
+
+      res.on("finish", () => done(true));
+      res.on("close", () => res.headersSent && done(true));
+
+      this.server.middlewares(req, res, () => done(false));
+
+      // Check after microtask if Vite started writing (for async handlers)
+      setImmediate(() => {
+        if (res.headersSent || res.writableEnded) {
+          done(true);
+        }
+      });
+    });
+  }
+
+  /**
+   * Invalidate modules and all their importers.
+   */
+  protected invalidateModulesWithImporters(): void {
+    const invalidated = new Set<string>();
+    const queue: string[] = [...this.changedFiles];
+
+    while (queue.length > 0) {
+      const file = queue.pop()!;
+      if (invalidated.has(file)) continue;
+
+      const mod = this.server.moduleGraph.getModuleById(file);
+      if (!mod) continue;
+
+      this.server.moduleGraph.invalidateModule(mod);
+      invalidated.add(file);
+
+      for (const importer of mod.importers) {
+        if (importer.id && !invalidated.has(importer.id)) {
+          queue.push(importer.id);
+        }
+      }
+    }
+  }
+}

package/src/cli/services/AlephaCliUtils.ts

@@ -1,9 +1,12 @@
-import { spawn } from "node:child_process";
-import { $inject, Alepha, AlephaError } from "alepha";
+import { $inject, type Alepha } from "alepha";
 import { EnvUtils } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { boot } from "alepha/vite";
+import { FileSystemProvider, ShellProvider } from "alepha/system";
+import {
+  type AppEntry,
+  AppEntryProvider,
+} from "../providers/AppEntryProvider.ts";
+import { ViteUtils } from "./ViteUtils.ts";
 
 /**
  * Core utility service for CLI commands.
@@ -18,6 +21,9 @@ export class AlephaCliUtils {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly envUtils = $inject(EnvUtils);
+  protected readonly boot = $inject(AppEntryProvider);
+  protected readonly shell = $inject(ShellProvider);
+  protected readonly viteUtils = $inject(ViteUtils);
 
   // ===========================================
   // Command Execution
@@ -25,6 +31,11 @@ export class AlephaCliUtils {
 
   /**
    * Execute a command with inherited stdio.
+   *
+   * @param command - The command to execute
+   * @param options.root - Working directory
+   * @param options.env - Additional environment variables
+   * @param options.global - If true, run command directly without resolving from node_modules
    */
   public async exec(
     command: string,
@@ -34,56 +45,12 @@ export class AlephaCliUtils {
       global?: boolean;
     } = {},
   ): Promise<void> {
-    const root = options.root ?? process.cwd();
-    this.log.debug(`Executing command: ${command}`, { cwd: root });
-
-    const runExec = async (app: string, args: string[]) => {
-      const prog = spawn(app, args, {
-        stdio: "inherit",
-        cwd: root,
-        env: {
-          ...process.env,
-          ...options.env,
-        },
-      });
-
-      await new Promise<void>((resolve) =>
-        prog.on("exit", () => {
-          resolve();
-        }),
-      );
-    };
-
-    if (options.global) {
-      const [app, ...args] = command.split(" ");
-      await runExec(app, args);
-      return;
-    }
-
-    const suffix = process.platform === "win32" ? ".cmd" : "";
-    const [app, ...args] = command.split(" ");
-
-    // find executable inside project node_modules
-    let execPath = await this.checkFileExists(
-      root,
-      `node_modules/.bin/${app}${suffix}`,
-    );
-
-    // or, find executable inside alepha package node_modules (pnpm style)
-    if (!execPath) {
-      execPath = await this.checkFileExists(
-        root,
-        `node_modules/alepha/node_modules/.bin/${app}${suffix}`,
-      );
-    }
-
-    if (!execPath) {
-      throw new AlephaError(
-        `Could not find executable for command '${app}'. Make sure the package is installed.`,
-      );
-    }
-
-    await runExec(execPath, args);
+    await this.shell.run(command, {
+      root: options.root,
+      env: options.env,
+      resolve: !options.global,
+      capture: false,
+    });
   }
 
   /**
@@ -106,40 +73,22 @@ export class AlephaCliUtils {
     return path;
   }
 
-  /**
-   * Load Alepha instance from a server entry file.
-   */
   public async loadAlephaFromServerEntryFile(
-    rootDir?: string,
-    explicitEntry?: string,
-  ): Promise<{
-    alepha: Alepha;
-    entry: string;
-  }> {
-    process.env.ALEPHA_CLI_IMPORT = "true";
-
-    const entry = await boot.getServerEntry(rootDir, explicitEntry);
-
-    delete (global as any).__alepha;
-
-    const mod = await import(entry);
-
-    this.log.debug(`Load entry: ${entry}`);
-
-    // check if alepha is correctly exported
-    if (mod.default instanceof Alepha) {
-      return { alepha: mod.default, entry };
-    }
-
-    // else, try with global variable
-    const g: any = global;
-    if (g.__alepha) {
-      return { alepha: g.__alepha, entry };
+    opts: {
+      mode: "production" | "development";
+    } & ({ entry: AppEntry } | { root: string }),
+  ): Promise<Alepha> {
+    let entry: AppEntry;
+    if ("root" in opts) {
+      entry = await this.boot.getAppEntry(opts.root);
+    } else {
+      entry = opts.entry;
     }
 
-    throw new AlephaError(
-      `Could not find Alepha instance in entry file: ${entry}`,
-    );
+    return await this.viteUtils.runAlepha({
+      entry,
+      mode: opts.mode,
+    });
   }
 
   // ===========================================
@@ -190,13 +139,10 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     return this.fs.exists(this.fs.join(root, path));
   }
 
-  protected async checkFileExists(
-    root: string,
-    name: string,
-  ): Promise<string | undefined> {
-    const configPath = this.fs.join(root, name);
-    if (await this.fs.exists(configPath)) {
-      return configPath;
-    }
+  /**
+   * Check if a command is installed and available in the system PATH.
+   */
+  public isInstalledAsync(cmd: string): Promise<boolean> {
+    return this.shell.isInstalled(cmd);
   }
 }