alepha 0.15.0 → 0.15.1

package/src/cli/providers/AppEntryProvider.ts

@@ -0,0 +1,131 @@
+import { $inject, $use, AlephaError } from "alepha";
+import { FileSystemProvider } from "alepha/file";
+import { appEntryOptions } from "../atoms/appEntryOptions.ts";
+
+/**
+ * Service for locating entry files in Alepha projects.
+ *
+ * Originally in alepha/vite, moved to CLI to avoid cli -> vite dependency.
+ */
+export class AppEntryProvider {
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly options = $use(appEntryOptions);
+
+  protected readonly serverEntries = [
+    "main.server.ts",
+    "main.server.tsx",
+    "main.ts",
+    "main.tsx",
+  ] as const;
+
+  protected readonly browserEntries = [
+    "main.browser.ts",
+    "main.browser.tsx",
+    "main.ts",
+    "main.tsx",
+  ] as const;
+
+  protected readonly styleEntries = [
+    "main.css",
+    "styles.css",
+    "style.css",
+  ] as const;
+
+  /**
+   * Get application entry points.
+   *
+   * Server entry is required, an error is thrown if not found.
+   * Browser entry is optional.
+   *
+   * It will first check for custom entries in options, see appEntryOptions.
+   */
+  public async getAppEntry(root: string): Promise<AppEntry> {
+    const appEntry: AppEntry = {
+      root,
+      server: "",
+    };
+
+    if (this.options.server) {
+      const serverExists = await this.fs.exists(
+        this.fs.join(root, this.options.server),
+      );
+      if (!serverExists) {
+        throw new AlephaError(
+          `Custom server entry "${this.options.server}" not found.`,
+        );
+      }
+      appEntry.server = this.options.server;
+    }
+
+    if (this.options.browser) {
+      const browserExists = await this.fs.exists(
+        this.fs.join(root, this.options.browser),
+      );
+      if (!browserExists) {
+        throw new AlephaError(
+          `Custom browser entry "${this.options.browser}" not found.`,
+        );
+      }
+      appEntry.browser = this.options.browser;
+    }
+
+    if (this.options.style) {
+      const styleExists = await this.fs.exists(
+        this.fs.join(root, this.options.style),
+      );
+      if (!styleExists) {
+        throw new AlephaError(
+          `Custom style entry "${this.options.style}" not found.`,
+        );
+      }
+      appEntry.style = this.options.style;
+    }
+
+    const srcFiles = await this.fs.ls(this.fs.join(root, "src"));
+
+    if (!appEntry.server) {
+      // find in conventional locations
+      for (const entry of this.serverEntries) {
+        if (srcFiles.includes(entry)) {
+          appEntry.server = this.fs.join("src", entry);
+          break;
+        }
+      }
+    }
+
+    if (!appEntry.server) {
+      throw new AlephaError(
+        "No server entry found. Please, add a main.server.ts file in the src/ directory or configure a custom entry in alepha.config.ts.",
+      );
+    }
+
+    if (!appEntry.browser) {
+      // find in conventional locations
+      for (const entry of this.browserEntries) {
+        if (srcFiles.includes(entry)) {
+          appEntry.browser = this.fs.join("src", entry);
+          break;
+        }
+      }
+    }
+
+    if (!appEntry.style) {
+      // find in conventional locations
+      for (const entry of this.styleEntries) {
+        if (srcFiles.includes(entry)) {
+          appEntry.style = this.fs.join("src", entry);
+          break;
+        }
+      }
+    }
+
+    return appEntry;
+  }
+}
+
+export interface AppEntry {
+  root: string;
+  server: string;
+  browser?: string;
+  style?: string;
+}

package/src/cli/providers/ViteBuildProvider.ts

@@ -0,0 +1,82 @@
+import { $hook, $inject, type Alepha, AlephaError } from "alepha";
+import { importVite } from "alepha/vite";
+import type { InlineConfig, ViteDevServer } from "vite";
+import type { AppEntry } from "./AppEntryProvider.ts";
+import { ViteTemplateProvider } from "./ViteTemplateProvider.ts";
+
+export class ViteBuildProvider {
+  protected alepha?: Alepha;
+  protected appEntry?: AppEntry;
+  protected viteDevServer?: ViteDevServer;
+  protected readonly templateProvider = $inject(ViteTemplateProvider);
+
+  /**
+   * We need to close the Vite dev server after build is done.
+   */
+  protected onReady = $hook({
+    on: "ready",
+    priority: "last",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+  protected onStop = $hook({
+    on: "stop",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+
+  public async init(opts: { entry: AppEntry }) {
+    const { createServer } = await importVite();
+
+    process.env.ALEPHA_CLI_IMPORT = "true"; // signal Alepha App about CLI import, run(alepha) won't start server
+    process.env.NODE_ENV = "production"; // force Alepha App in production mode for getting "production" metadata
+    process.env.LOG_LEVEL ??= "warn"; // reduce log noise
+
+    /**
+     * 01/26 Vite 7
+     * "runnerImport" doesn't work as expected here. (e.g. build docs fail)
+     * -> We still use devServer and ssrLoadModule for now.
+     * -> This is clearly a bad stuff, we need to find better way.
+     */
+    this.viteDevServer = await createServer({
+      server: { middlewareMode: true },
+      appType: "custom",
+      logLevel: "silent",
+    } satisfies InlineConfig);
+
+    await this.viteDevServer.ssrLoadModule(opts.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;
+    this.appEntry = opts.entry;
+
+    return alepha;
+  }
+
+  public hasClient(): boolean {
+    if (!this.alepha) {
+      throw new AlephaError("ViteBuildProvider not initialized");
+    }
+    try {
+      this.alepha.inject("ReactServerProvider");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public generateIndexHtml(): string {
+    if (!this.appEntry) {
+      throw new AlephaError("ViteBuildProvider not initialized");
+    }
+    return this.templateProvider.generateIndexHtml(this.appEntry);
+  }
+}

package/src/cli/providers/ViteDevServerProvider.ts

@@ -0,0 +1,350 @@
+import { $inject, type Alepha, AlephaError } from "alepha";
+import { FileSystemProvider } from "alepha/file";
+import { $logger } from "alepha/logger";
+import { importVite, importViteReact, viteAlephaSsrPreload } from "alepha/vite";
+import type { InlineConfig, Plugin, ViteDevServer } from "vite";
+import type { AppEntry } from "./AppEntryProvider.ts";
+import { ViteTemplateProvider } from "./ViteTemplateProvider.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(ViteTemplateProvider);
+  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, "");
+
+    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),
+    );
+
+    // Merge into process.env (only set if not already defined)
+    for (const [key, value] of Object.entries(env)) {
+      process.env[key] ??= value;
+    }
+  }
+
+  /**
+   * 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> {
+    return new Promise((resolve) => {
+      let resolved = false;
+
+      const done = (handled: boolean) => {
+        if (resolved) return;
+        resolved = true;
+        if (handled) ctx.metadata.vite = true;
+        resolve(handled);
+      };
+
+      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/providers/ViteTemplateProvider.ts

@@ -0,0 +1,27 @@
+import { $inject } from "alepha";
+import { FileSystemProvider } from "alepha/file";
+import type { AppEntry } from "./AppEntryProvider.ts";
+
+export class ViteTemplateProvider {
+  protected readonly fs = $inject(FileSystemProvider);
+
+  public generateIndexHtml(entry: AppEntry): string {
+    const style = entry.style;
+    const browser = entry.browser ?? entry.server;
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>App</title>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/${browser}"></script>
+</body>
+</html>
+`.trim();
+  }
+}

package/src/cli/services/AlephaCliUtils.ts

@@ -3,7 +3,7 @@ import { $inject, Alepha, AlephaError } from "alepha";
 import { EnvUtils } from "alepha/command";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { boot } from "alepha/vite";
+import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 
 /**
  * Core utility service for CLI commands.
@@ -18,6 +18,7 @@ export class AlephaCliUtils {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly envUtils = $inject(EnvUtils);
+  protected readonly boot = $inject(AppEntryProvider);
 
   // ===========================================
   // Command Execution
@@ -77,6 +78,21 @@ export class AlephaCliUtils {
       );
     }
 
+    // check if parent folder (monorepo) has the executable (check 3 times)
+    if (!execPath) {
+      let parentDir = this.fs.join(root, "..");
+      for (let i = 0; i < 3; i++) {
+        execPath = await this.checkFileExists(
+          parentDir,
+          `node_modules/.bin/${app}${suffix}`,
+        );
+        if (execPath) {
+          break;
+        }
+        parentDir = this.fs.join(parentDir, "..");
+      }
+    }
+
     if (!execPath) {
       throw new AlephaError(
         `Could not find executable for command '${app}'. Make sure the package is installed.`,
@@ -118,7 +134,22 @@ export class AlephaCliUtils {
   }> {
     process.env.ALEPHA_CLI_IMPORT = "true";
 
-    const entry = await boot.getServerEntry(rootDir, explicitEntry);
+    const root = rootDir ?? process.cwd();
+    let entry: string;
+
+    if (explicitEntry) {
+      // Explicit entry provided
+      entry = this.fs.join(root, explicitEntry);
+      if (!(await this.fs.exists(entry))) {
+        throw new AlephaError(
+          `Explicit server entry file "${explicitEntry}" not found.`,
+        );
+      }
+    } else {
+      // Auto-discover entry
+      const appEntry = await this.boot.getAppEntry(root);
+      entry = this.fs.join(root, appEntry.server);
+    }
 
     delete (global as any).__alepha;
 

package/src/cli/services/PackageManagerUtils.ts

@@ -89,6 +89,13 @@ export class PackageManagerUtils {
     return this.hasDependency(root, "expo");
   }
 
+  /**
+   * Check if React is present in the project.
+   */
+  public async hasReact(root: string): Promise<boolean> {
+    return this.hasDependency(root, "react");
+  }
+
   /**
    * Install a dependency if it's missing from the project.
    */
@@ -114,7 +121,7 @@ export class PackageManagerUtils {
     const cmd = await this.getInstallCommand(root, packageName, dev);
 
     if (options.run) {
-      await options.run(cmd, { alias: `installing ${packageName}`, root });
+      await options.run(cmd, { alias: `add ${packageName}`, root });
     } else if (options.exec) {
       this.log.debug(`Installing ${packageName}`);
       await options.exec(cmd, { global: true, root });
@@ -261,12 +268,12 @@ export class PackageManagerUtils {
       verify: "alepha verify",
     };
 
-    if (modes.admin) {
+    if (modes.ui) {
       dependencies["@alepha/ui"] = `^${version}`;
-      modes.web = true;
+      modes.react = true;
     }
 
-    if (modes.web) {
+    if (modes.react) {
       dependencies["@alepha/react"] = `^${version}`;
       dependencies.react = "^19.2.0";
       dependencies["react-dom"] = "^19.2.0";
@@ -295,7 +302,7 @@ export class PackageManagerUtils {
 }
 
 export interface DependencyModes {
-  web?: boolean;
-  admin?: boolean;
+  react?: boolean;
+  ui?: boolean;
   expo?: boolean;
 }