alepha 0.19.1 → 0.19.3

package/src/cli/core/commands/dev.ts

@@ -1,4 +1,7 @@
-import { $inject, $use, Alepha, t } from "alepha";
+import { spawn } from "node:child_process";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { $inject, $state, Alepha, t } from "alepha";
 import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
@@ -18,48 +21,180 @@ export class DevCommand {
   protected readonly alepha = $inject(Alepha);
   protected readonly viteDevServer = $inject(ViteDevServerProvider);
   protected readonly boot = $inject(AppEntryProvider);
-  protected readonly options = $use(devOptions);
+  protected readonly options = $state(devOptions);
 
   /**
    * Will run the project in watch mode.
+   *
+   * When run from a workspace root (with apps/ directory), spawns all apps in parallel.
+   * When run from an app directory, starts a single Vite dev server.
    */
   public readonly dev = $command({
     name: "dev",
     mode: true,
     description: "Run the project in development mode",
     flags: t.object({
-      "no-devtools": t.optional(
-        t.boolean({
-          description: "Disable devtools",
-        }),
-      ),
-      "no-vite-react-plugin": t.optional(
-        t.boolean({
-          description: "Disable Vite React plugin",
+      only: t.optional(
+        t.string({
+          description:
+            "Run only specific apps (comma-separated: --only api,companion)",
         }),
       ),
     }),
     handler: async ({ root, flags }) => {
-      await this.scaffolder.ensureConfig(root, {
-        tsconfigJson: true,
-      });
-
-      const entry = await this.boot.getAppEntry(root);
-      this.log.debug("Entry file found", { entry });
-
-      const options = this.options;
-
-      // -> here, we assume we use Vite as runner (api or fullstack)
-      // but it's planned to support Bun runner in the future as well
-      await this.viteDevServer.init({
-        root,
-        entry,
-        noDevtools: flags["no-devtools"] ?? options.noDevtools ?? false,
-        noViteReactPlugin:
-          flags["no-vite-react-plugin"] ?? options.noViteReactPlugin ?? false,
-      });
-
-      await this.viteDevServer.start();
+      const apps = await this.discoverApps(root);
+
+      if (apps.length > 0) {
+        await this.runMultiple(root, apps, flags);
+      } else {
+        await this.runSingle(root);
+      }
     },
   });
+
+  /**
+   * Discover apps in the workspace root.
+   *
+   * Looks for directories under apps/ that contain a package.json.
+   * Supports scoped directories (e.g., apps/@passeo/api).
+   * Returns empty array if not in a workspace root.
+   */
+  protected async discoverApps(
+    root: string,
+  ): Promise<Array<{ name: string; path: string }>> {
+    const appsDir = join(root, "apps");
+
+    if (!(await this.fs.exists(appsDir))) {
+      return [];
+    }
+
+    const entries = await readdir(appsDir);
+    const apps: Array<{ name: string; path: string }> = [];
+
+    for (const entry of entries) {
+      const appPath = join(appsDir, entry);
+      const pkgPath = join(appPath, "package.json");
+
+      if (await this.fs.exists(pkgPath)) {
+        apps.push({ name: entry, path: appPath });
+        continue;
+      }
+
+      // Check scoped directories (e.g., apps/@passeo/api)
+      const entryStat = await stat(appPath).catch(() => null);
+      if (entryStat?.isDirectory()) {
+        const scopedEntries = await readdir(appPath);
+        for (const scopedEntry of scopedEntries) {
+          const scopedPath = join(appPath, scopedEntry);
+          const scopedPkgPath = join(scopedPath, "package.json");
+
+          if (await this.fs.exists(scopedPkgPath)) {
+            apps.push({ name: scopedEntry, path: scopedPath });
+          }
+        }
+      }
+    }
+
+    return apps;
+  }
+
+  /**
+   * Run a single app (existing behavior).
+   */
+  protected async runSingle(root: string): Promise<void> {
+    await this.scaffolder.ensureConfig(root, {
+      tsconfigJson: true,
+    });
+
+    const entry = await this.boot.getAppEntry(root);
+    this.log.debug("Entry file found", { entry });
+
+    const options = this.options;
+
+    await this.viteDevServer.init({
+      root,
+      entry,
+      noViteReactPlugin: options.noViteReactPlugin ?? false,
+    });
+
+    await this.viteDevServer.start();
+  }
+
+  /**
+   * Run multiple apps in parallel with colored prefixed output.
+   */
+  protected async runMultiple(
+    _root: string,
+    apps: Array<{ name: string; path: string }>,
+    flags: Record<string, unknown>,
+  ): Promise<void> {
+    const only = flags.only as string | undefined;
+
+    if (only) {
+      const filter = only.split(",").map((s) => s.trim().toLowerCase());
+      apps = apps.filter((app) => filter.includes(app.name.toLowerCase()));
+    }
+
+    if (apps.length === 0) {
+      this.log.warn("No apps found to run");
+      return;
+    }
+
+    this.log.debug(
+      `Starting ${apps.length} apps: ${apps.map((a) => a.name).join(", ")}`,
+    );
+
+    const basePort = 5173;
+    const processes = apps.map((app, i) => this.spawnApp(app, basePort + i));
+
+    // Handle graceful shutdown
+    const cleanup = () => {
+      for (const proc of processes) {
+        proc.kill("SIGTERM");
+      }
+    };
+
+    process.once("SIGINT", cleanup);
+    process.once("SIGTERM", cleanup);
+
+    // Wait for all processes (they run until killed)
+    await Promise.allSettled(
+      processes.map(
+        (proc) =>
+          new Promise<void>((resolve) => {
+            proc.on("exit", () => resolve());
+          }),
+      ),
+    );
+  }
+
+  /**
+   * Spawn a single app process with inherited stdio.
+   *
+   * Each child process gets APP_NAME set, so the Alepha logger
+   * handles prefixing automatically.
+   */
+  protected spawnApp(
+    app: { name: string; path: string },
+    port: number,
+  ): ReturnType<typeof spawn> {
+    const proc = spawn("yarn", ["alepha", "dev"], {
+      cwd: app.path,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        APP_NAME: app.name.toUpperCase(),
+        SERVER_PORT: String(port),
+        FORCE_COLOR: "1",
+      },
+    });
+
+    proc.on("exit", (code) => {
+      if (code !== 0 && code !== null) {
+        this.log.error(`${app.name} exited with code ${code}`);
+      }
+    });
+
+    return proc;
+  }
 }

package/src/cli/core/commands/gen/changelog.ts

@@ -1,6 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { $inject, $use, t } from "alepha";
+import { $inject, $state, t } from "alepha";
 import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
 import { changelogOptions } from "../../atoms/changelogOptions.ts";
@@ -64,7 +64,7 @@ export class ChangelogCommand {
   protected readonly log = $logger();
   protected readonly git = $inject(GitProvider);
   protected readonly parser = $inject(GitMessageParser);
-  protected readonly config = $use(changelogOptions);
+  protected readonly config = $state(changelogOptions);
 
   // ---------------------------------------------------------------------------
   // FORMATTING

package/src/cli/core/commands/init.ts

@@ -43,15 +43,10 @@ export class InitCommand {
             "Include @alepha/ui (components, auth portal, admin portal)",
         }),
       ),
-      auth: t.optional(
+      saas: t.optional(
         t.boolean({
           description:
-            "Include authentication (AppSecurity, $uiAuth). Implies --api --ui --react",
-        }),
-      ),
-      admin: t.optional(
-        t.boolean({
-          description: "Include admin portal ($uiAdmin). Implies --auth",
+            "Include authentication, admin portal, API, UI, and React. Everything you need for a SaaS app.",
         }),
       ),
       tailwind: t.optional(

package/src/cli/core/commands/verify.ts

@@ -25,7 +25,6 @@ export class VerifyCommand {
     description: "Verify the Alepha project",
     handler: async ({ root, run }) => {
       await run("alepha clean");
-      await run("alepha format");
       await run("alepha lint");
 
       await run("alepha typecheck");

package/src/cli/core/providers/AppEntryProvider.ts

@@ -1,4 +1,4 @@
-import { $inject, $use, AlephaError } from "alepha";
+import { $inject, $state, AlephaError } from "alepha";
 import { FileSystemProvider } from "alepha/system";
 import { appEntryOptions } from "../atoms/appEntryOptions.ts";
 
@@ -9,7 +9,7 @@ import { appEntryOptions } from "../atoms/appEntryOptions.ts";
  */
 export class AppEntryProvider {
   protected readonly fs = $inject(FileSystemProvider);
-  protected readonly options = $use(appEntryOptions);
+  protected readonly options = $state(appEntryOptions);
 
   protected readonly serverEntries = [
     "main.server.ts",

package/src/cli/core/providers/ViteDevServerProvider.ts

@@ -1,6 +1,4 @@
-import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { __alephaRef, $inject, type Alepha, AlephaError } from "alepha";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
@@ -19,17 +17,20 @@ export interface DevServerOptions {
    */
   entry: AppEntry;
 
-  /**
-   * Disable devtools.
-   */
-  noDevtools?: boolean;
-
   /**
    * Disable Vite React plugin.
    */
   noViteReactPlugin?: boolean;
 }
 
+/**
+ * Hook called after Alepha is loaded during dev server init/reload.
+ */
+export type OnAlephaLoadedHook = (
+  alepha: Alepha,
+  server: ViteDevServer,
+) => Promise<void>;
+
 /**
  * Vite development server with Alepha integration.
  *
@@ -60,7 +61,33 @@ export class ViteDevServerProvider {
   protected isReloading = false;
   protected needsBrowserReload = false;
   protected currentReloadPromise: Promise<void> | null = null;
-  protected devtoolsAssetsPath: string | undefined;
+  protected extraVitePlugins: Plugin[] = [];
+  protected alephaLoadedHooks: OnAlephaLoadedHook[] = [];
+
+  /**
+   * Register an additional Vite plugin.
+   * Must be called before init().
+   */
+  public addVitePlugin(plugin: Plugin): void {
+    this.extraVitePlugins.push(plugin);
+  }
+
+  /**
+   * Register a hook called after Alepha is loaded/reloaded.
+   */
+  public onAlephaLoaded(hook: OnAlephaLoadedHook): void {
+    this.alephaLoadedHooks.push(hook);
+  }
+
+  /**
+   * Trigger a full Alepha reload programmatically.
+   */
+  public reload(): void {
+    this.hasError = true;
+    this.needsBrowserReload = true;
+    this.changedFiles.add("__manual_reload__");
+    this.scheduleReload();
+  }
 
   /**
    * Initialize the dev server and load Alepha.
@@ -88,10 +115,10 @@ export class ViteDevServerProvider {
       await this.alepha?.start();
       await this.listen();
 
-      console.log("");
-      this.server.printUrls();
-      this.server.bindCLIShortcuts({ print: true });
-      console.log("");
+      const port = this.server.config.server.port ?? 5173;
+      const url = `http://localhost:${port}/`;
+      const log = this.alepha?.log ?? this.log;
+      log.info(`Listening on ${this.colors.set("CYAN", url)}`);
     } catch (err) {
       this.hasError = true;
       this.currentError = err instanceof Error ? err : new Error(String(err));
@@ -126,6 +153,7 @@ export class ViteDevServerProvider {
     if (viteReact && !this.options.noViteReactPlugin) plugins.push(viteReact());
     plugins.push(this.viteUtils.createTsconfigPathsPlugin());
     plugins.push(this.viteUtils.createSsrPreloadPlugin());
+    plugins.push(...this.extraVitePlugins);
     plugins.push(this.createAlephaPlugin());
 
     // DEFAULT PORT
@@ -144,6 +172,14 @@ export class ViteDevServerProvider {
       root: this.options.root,
       plugins,
       appType: "custom",
+      resolve: {
+        dedupe: [
+          "react",
+          "react-dom",
+          "react/jsx-runtime",
+          "react/jsx-dev-runtime",
+        ],
+      },
       server: {
         port,
       },
@@ -205,51 +241,6 @@ export class ViteDevServerProvider {
       name: "alepha",
 
       configureServer: (server) => {
-        // Resolve @alepha/devtools assets path (if installed)
-        if (!this.options.noDevtools) {
-          try {
-            const require = createRequire(import.meta.url);
-            const pkgPath = require.resolve("@alepha/devtools/package.json");
-            this.devtoolsAssetsPath = join(dirname(pkgPath), "assets/ui");
-            process.env.VITE_ALEPHA_DEVTOOLS = "true";
-          } catch {
-            this.log.debug("@alepha/devtools not installed, skipping devtools");
-          }
-        }
-
-        // Devtools live reload via SSE
-        if (this.devtoolsAssetsPath) {
-          const assetsPath = this.devtoolsAssetsPath;
-
-          server.middlewares.use(async (req, res, next) => {
-            const url = req.url || "/";
-
-            // Serve devtools HTML with reload script injected
-            if (
-              !url.startsWith("/__devtools") ||
-              !req.headers.accept?.includes("text/html")
-            ) {
-              return next();
-            }
-
-            const indexPath = join(assetsPath, "index.html");
-
-            try {
-              let html = await readFile(indexPath, "utf-8");
-              html = html.replace(
-                "<head>",
-                `<head><script type="module" src="/@vite/client"></script>`,
-              );
-
-              res.writeHead(200, { "content-type": "text/html" });
-              res.end(html);
-            } catch (err) {
-              this.log.error("Failed to serve devtools UI", err);
-              next();
-            }
-          });
-        }
-
         // Re-send error overlay when a new browser connects (e.g. page refresh during error state)
         server.hot.on("connection", () => {
           if (this.currentError) {
@@ -257,6 +248,26 @@ export class ViteDevServerProvider {
           }
         });
 
+        // Readiness endpoint: responds only when Alepha is fully loaded
+        server.middlewares.use(async (req, res, next) => {
+          if (req.url !== "/__alepha/ready") {
+            next();
+            return;
+          }
+
+          if (this.currentReloadPromise) {
+            await this.currentReloadPromise;
+          }
+
+          if (this.alepha?.isReady()) {
+            res.writeHead(200, { "content-type": "text/plain" });
+            res.end("ok");
+          } else {
+            res.writeHead(503, { "content-type": "text/plain" });
+            res.end("not ready");
+          }
+        });
+
         // Return function to run AFTER Vite's built-in middleware
         return () => {
           server.middlewares.use(async (req, res, next) => {
@@ -267,6 +278,11 @@ export class ViteDevServerProvider {
               return;
             }
 
+            // Wait for in-progress reload to complete before serving
+            if (this.currentReloadPromise) {
+              await this.currentReloadPromise;
+            }
+
             // In error state, serve a minimal HTML shell so the browser
             // can connect to Vite's HMR and display the error overlay
             if (this.hasError && !this.alepha) {
@@ -341,11 +357,10 @@ export class ViteDevServerProvider {
 
   /**
    * Send full browser reload via Vite's HMR.
+   * Uses a custom event so the client can poll for readiness before reloading.
    */
   protected sendBrowserReload(): void {
-    this.server.hot.send({
-      type: "full-reload",
-    });
+    this.server.hot.send("alepha:reload", {});
   }
 
   /**
@@ -482,13 +497,8 @@ export class ViteDevServerProvider {
     // Expose Vite server to Alepha for Logger SSR stack trace fixing
     alepha.store.set("alepha.vite.server" as any, this.server);
 
-    if (this.devtoolsAssetsPath) {
-      try {
-        const mod = await this.server.ssrLoadModule("@alepha/devtools");
-        alepha.with(mod.AlephaDevtools);
-      } catch (err) {
-        this.log.warn("Failed to load @alepha/devtools", err);
-      }
+    for (const hook of this.alephaLoadedHooks) {
+      await hook(alepha, this.server);
     }
 
     this.alepha = alepha;
@@ -565,6 +575,24 @@ export class ViteDevServerProvider {
     if (preamble) {
       tags.push(preamble);
     }
+
+    // Reload handler: polls /__alepha/ready before reloading to avoid
+    // hitting the server while it's still restarting.
+    tags.push(`<script type="module">
+if (import.meta.hot) {
+  import.meta.hot.on("alepha:reload", async () => {
+    for (let i = 0; i < 50; i++) {
+      try {
+        const res = await fetch("/__alepha/ready");
+        if (res.ok) { window.location.reload(); return; }
+      } catch {}
+      await new Promise(r => setTimeout(r, 200));
+    }
+    window.location.reload();
+  });
+}
+</script>`);
+
     if (style) {
       tags.push(`<link rel="stylesheet" href="/${style}">`);
     }
@@ -717,11 +745,13 @@ export class ViteDevServerProvider {
   /**
    * Log a formatted error with stack trace.
    */
-  protected logError(title: string, _err: unknown): void {
+  protected logError(title: string, err: unknown): void {
     const c = this.colors;
 
     console.log();
     console.log(c.set("RED", `  ✗ ${title}`));
+    this.logErrorWithCause(err);
+    console.log();
     console.log(c.set("GREY_DARK", "    Waiting for file changes to retry..."));
     console.log();
   }

package/src/cli/core/services/PackageManagerUtils.ts

@@ -399,9 +399,16 @@ export class PackageManagerUtils {
     };
 
     const devDependencies: Record<string, string> = {
-      "drizzle-kit": alephaDeps["drizzle-kit"],
+      vite: alephaDeps.vite,
     };
 
+    // Only include drizzle-kit when the project uses a database.
+    // React-only projects (--react without --api/--saas) don't need it.
+    const isReactOnly = modes.react && !modes.ui;
+    if (!isReactOnly) {
+      devDependencies["drizzle-kit"] = alephaDeps["drizzle-kit"];
+    }
+
     // Add biome/vitest only if not a workspace package (workspace root has them)
     if (!modes.isPackage) {
       devDependencies["@biomejs/biome"] = alephaDeps["@biomejs/biome"];

package/src/cli/core/services/ProjectScaffolder.ts

@@ -5,7 +5,7 @@ import type { RunnerMethod } from "alepha/command";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
 import { cliAssets } from "../assets.ts";
-import { type AgentMdType, agentMd } from "../templates/agentMd.ts";
+import { type AgentMdOptions, agentMd } from "../templates/agentMd.ts";
 import { alephaConfigTs } from "../templates/alephaConfigTs.ts";
 import { apiAppSecurityTs } from "../templates/apiAppSecurityTs.ts";
 import { apiHelloControllerTs } from "../templates/apiHelloControllerTs.ts";
@@ -20,6 +20,7 @@ import { mainCss } from "../templates/mainCss.ts";
 import { mainServerTs } from "../templates/mainServerTs.ts";
 import { tsconfigJson } from "../templates/tsconfigJson.ts";
 import { viteConfigTs } from "../templates/viteConfigTs.ts";
+import { webAdminDashboardTsx } from "../templates/webAdminDashboardTsx.ts";
 import { webAppRouterTs } from "../templates/webAppRouterTs.ts";
 import { webHomeComponentTsx } from "../templates/webHomeComponentTsx.ts";
 import { webIndexTs } from "../templates/webIndexTs.ts";
@@ -74,7 +75,7 @@ export class ProjectScaffolder {
       tsconfigJson?: boolean;
       biomeJson?: boolean;
       editorconfig?: boolean;
-      agentMd?: false | { type: AgentMdType };
+      agentMd?: false | AgentMdOptions;
     },
   ): Promise<void> {
     const tasks: Promise<void>[] = [];
@@ -186,10 +187,10 @@ export class ProjectScaffolder {
 
   public async ensureAgentMd(
     root: string,
-    options: { type: AgentMdType; force?: boolean },
+    options: AgentMdOptions & { force?: boolean },
   ): Promise<void> {
     const filename = options.type === "claude" ? "CLAUDE.md" : "AGENTS.md";
-    await this.ensureFile(root, filename, agentMd(options.type), options.force);
+    await this.ensureFile(root, filename, agentMd(options), options.force);
   }
 
   /**
@@ -356,6 +357,14 @@ export class ProjectScaffolder {
       webHomeComponentTsx({ api: opts.api }),
       opts.force,
     );
+    if (opts.admin) {
+      await this.ensureFile(
+        root,
+        "src/web/components/AdminDashboard.tsx",
+        webAdminDashboardTsx(),
+        opts.force,
+      );
+    }
     await this.ensureFile(
       root,
       "src/main.browser.ts",
@@ -407,8 +416,7 @@ export class ProjectScaffolder {
       api?: boolean;
       react?: boolean;
       ui?: boolean;
-      auth?: boolean;
-      admin?: boolean;
+      saas?: boolean;
       tailwind?: boolean;
       test?: boolean;
       force?: boolean;
@@ -420,11 +428,8 @@ export class ProjectScaffolder {
       await this.fs.mkdir(root, { force: true });
     }
 
-    // Flag cascading: --admin → --auth → --ui → --react, --api
-    if (flags.admin) {
-      flags.auth = true;
-    }
-    if (flags.auth) {
+    // Flag cascading: --saas → --api + --ui → --react
+    if (flags.saas) {
       flags.api = true;
       flags.ui = true;
     }
@@ -437,12 +442,7 @@ export class ProjectScaffolder {
 
     // When codegen flags are set, target directory must be empty (unless --force)
     const hasCodegenFlags =
-      flags.admin ||
-      flags.auth ||
-      flags.api ||
-      flags.ui ||
-      flags.react ||
-      flags.tailwind;
+      flags.saas || flags.api || flags.ui || flags.react || flags.tailwind;
     if (hasCodegenFlags && !flags.force) {
       const files = await this.fs.ls(root);
       // Allow a directory that only has package.json (common for monorepo packages)
@@ -466,8 +466,8 @@ export class ProjectScaffolder {
 
     const isExpo = await this.pm.hasExpo(root);
 
-    // Get git email for admin auto-promotion (if auth enabled)
-    const adminEmail = flags.auth ? await this.utils.getGitEmail() : undefined;
+    // Get git email for admin auto-promotion (if saas enabled)
+    const adminEmail = flags.saas ? await this.utils.getGitEmail() : undefined;
 
     const force = !!flags.force;
 
@@ -481,7 +481,7 @@ export class ProjectScaffolder {
           tsconfigJson: !workspace.config.tsconfigJson,
           biomeJson: true,
           editorconfig: !workspace.config.editorconfig,
-          agentMd: agentType ? { type: agentType } : false,
+          agentMd: agentType ? { type: agentType, ui: !!flags.ui } : false,
         });
 
         // Create alepha.config.ts with documented options
@@ -495,7 +495,7 @@ export class ProjectScaffolder {
         });
         if (flags.api) {
           await this.ensureApiProject(root, {
-            auth: !!flags.auth,
+            auth: !!flags.saas,
             adminEmail,
             force,
           });
@@ -504,8 +504,8 @@ export class ProjectScaffolder {
           await this.ensureWebProject(root, {
             api: !!flags.api,
             ui: !!flags.ui,
-            auth: !!flags.auth,
-            admin: !!flags.admin,
+            auth: !!flags.saas,
+            admin: !!flags.saas,
             tailwind: !!flags.tailwind,
             force,
           });