alepha 0.18.2 → 0.18.3

package/src/api/users/services/SessionService.spec.ts

@@ -13,7 +13,7 @@ import {
   UserService,
 } from "../index.ts";
 
-const setup = async (options?: { usernameEnabled?: boolean }) => {
+const setup = async (options?: { username?: "optional" | "required" }) => {
   const alepha = Alepha.create({
     env: { LOG_LEVEL: "error" },
   });
@@ -27,11 +27,11 @@ const setup = async (options?: { usernameEnabled?: boolean }) => {
   const sessionService = alepha.inject(SessionService);
 
   // Configure realm settings if provided
-  if (options?.usernameEnabled) {
+  if (options?.username) {
     const realmProvider = alepha.inject(RealmProvider);
     realmProvider.register("default", {
       settings: {
-        usernameEnabled: true,
+        username: options.username,
       } as never,
     });
   }
@@ -247,7 +247,7 @@ describe("alepha/api/users - SessionService.login", () => {
 
   it("should handle different providers correctly", async ({ expect }) => {
     const { sessionService, userService, cryptoProvider, identities } =
-      await setup({ usernameEnabled: true });
+      await setup({ username: "optional" });
 
     const user = await userService.users().create({
       username: "multiprovideruser",

package/src/api/users/services/SessionService.ts

@@ -125,7 +125,7 @@ export class SessionService {
 
       where.realm = name;
 
-      if (settings.usernameEnabled !== false && isUsername) {
+      if (settings.username !== "none" && isUsername) {
         // validate username format if regex is provided
         if (settings.usernameRegExp) {
           const regex = new RegExp(settings.usernameRegExp);
@@ -146,9 +146,9 @@ export class SessionService {
           }
         }
         where.username = username;
-      } else if (settings.emailEnabled !== false && isEmail) {
+      } else if (settings.email !== "none" && isEmail) {
         where.email = username;
-      } else if (settings.phoneEnabled === true && isPhone) {
+      } else if (settings.phoneNumber !== "none" && isPhone) {
         where.phoneNumber = username;
       } else {
         this.log.warn("Invalid login identifier format", {

package/src/cli/{core → config}/defineConfig.ts

@@ -1,11 +1,14 @@
 import type { Alepha } from "alepha";
-import type { CommandPrimitive } from "alepha/command";
 import {
   type AppEntryOptions,
   appEntryOptions,
-} from "./atoms/appEntryOptions.ts";
-import { type BuildOptions, buildOptions } from "./atoms/buildOptions.ts";
-import { type DevOptions, devOptions } from "./atoms/devOptions.ts";
+  type BuildOptions,
+  buildOptions,
+  type DevOptions,
+  devOptions,
+} from "alepha/cli";
+import { type PlatformOptions, platformOptions } from "alepha/cli/platform";
+import type { CommandPrimitive } from "alepha/command";
 
 export interface AlephaCliConfig {
   entry?: AppEntryOptions;
@@ -38,24 +41,15 @@ export interface AlephaCliConfig {
    * Always use .env files by default, this is only for dynamic values.
    */
   env?: Record<string, unknown>;
+
+  /**
+   * Platform deployment configuration.
+   */
+  platform?: PlatformOptions;
 }
 
 export type AlephaCliConfigFn = (alepha: Alepha) => AlephaCliConfig;
 
-type ConfigProcessor = (alepha: Alepha, config: AlephaCliConfig) => void;
-
-const configProcessors: ConfigProcessor[] = [];
-
-/**
- * Register a processor that runs during config resolution.
- *
- * Used by submodules (e.g. platform) to handle their own config keys
- * without core needing to know about them.
- */
-export function registerConfigProcessor(processor: ConfigProcessor) {
-  configProcessors.push(processor);
-}
-
 // ---------------------------------------------------------------------------------------------------------------------
 
 export const defineConfig = (
@@ -89,8 +83,8 @@ export const defineConfig = (
       alepha.set(appEntryOptions, config.entry);
     }
 
-    for (const processor of configProcessors) {
-      processor(alepha, config);
+    if (config.platform) {
+      alepha.set(platformOptions, config.platform);
     }
 
     return {

package/src/cli/config/index.ts

@@ -0,0 +1 @@
+export * from "./defineConfig.ts";

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

@@ -179,8 +179,72 @@ export class DbCommand {
         description: "Path to the Alepha server entry file",
       }),
     ),
-    flags: drizzleCommandFlags,
+    flags: t.extend(drizzleCommandFlags, {
+      dryRun: t.optional(
+        t.boolean({
+          description: "Preview SQL statements without executing them",
+        }),
+      ),
+    }),
     handler: async ({ root, args, flags }) => {
+      if (flags.dryRun) {
+        const entry = await this.entryProvider.getAppEntry(root);
+        const alepha = await this.utils.loadAlephaFromServerEntryFile({
+          mode: "development",
+          entry,
+        });
+
+        const drizzleKitProvider =
+          alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
+        const repositoryProvider =
+          alepha.inject<RepositoryProvider>("RepositoryProvider");
+        const accepted = new Set<string>([]);
+
+        for (const primitive of repositoryProvider.getRepositories()) {
+          const provider = primitive.provider;
+          const providerName = provider.name;
+
+          if (accepted.has(providerName)) continue;
+          accepted.add(providerName);
+
+          if (flags.provider && flags.provider !== providerName) continue;
+
+          this.log.info("");
+          this.log.info(
+            `Dry run for '${providerName}' (${provider.dialect}) ...`,
+          );
+
+          await (provider as any).connect();
+
+          try {
+            const result = await drizzleKitProvider.dryRunPush(provider);
+
+            if (result.statements.length === 0) {
+              this.log.info("No changes detected.");
+            } else {
+              if (result.hasDataLoss) {
+                this.log.warn("WARNING: These changes would cause data loss!");
+                for (const warning of result.warnings) {
+                  this.log.warn(`  ${warning}`);
+                }
+              }
+
+              this.log.info("");
+              this.log.info(
+                `${result.statements.length} statement(s) would be executed:`,
+              );
+              this.log.info("");
+              for (const stmt of result.statements) {
+                this.log.info(stmt);
+              }
+            }
+          } finally {
+            await (provider as any).close();
+          }
+        }
+        return;
+      }
+
       await this.runDrizzleKitCommand({
         root,
         args,

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

@@ -58,6 +58,7 @@ export class DevCommand {
         noViteReactPlugin:
           flags["no-vite-react-plugin"] ?? options.noViteReactPlugin ?? false,
       });
+
       await this.viteDevServer.start();
     },
   });

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

@@ -1,18 +1,9 @@
-import { $inject, AlephaError, t } from "alepha";
+import { $inject, t } from "alepha";
 import { $command } from "alepha/command";
-import { $logger, ConsoleColorProvider } from "alepha/logger";
-import { FileSystemProvider } from "alepha/system";
-import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
-import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
 
 export class InitCommand {
-  protected readonly log = $logger();
-  protected readonly colors = $inject(ConsoleColorProvider);
-  protected readonly utils = $inject(AlephaCliUtils);
-  protected readonly pm = $inject(PackageManagerUtils);
   protected readonly scaffolder = $inject(ProjectScaffolder);
-  protected readonly fs = $inject(FileSystemProvider);
 
   /**
    * Ensure the project has the necessary Alepha configuration files.
@@ -79,188 +70,7 @@ export class InitCommand {
       ),
     }),
     handler: async ({ run, flags, root, args }) => {
-      if (args) {
-        root = this.fs.join(root, args);
-        await this.fs.mkdir(root, { force: true });
-      }
-
-      // Flag cascading: --admin → --auth → --ui → --react, --api
-      if (flags.admin) {
-        flags.auth = true;
-      }
-      if (flags.auth) {
-        flags.api = true;
-        flags.ui = true;
-      }
-      if (flags.ui) {
-        flags.react = true;
-      }
-      if (flags.tailwind) {
-        flags.react = true;
-      }
-
-      // 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;
-      if (hasCodegenFlags && !flags.force) {
-        const files = await this.fs.ls(root);
-        // Allow a directory that only has package.json (common for monorepo packages)
-        const meaningful = files.filter((f) => f !== "package.json");
-        if (meaningful.length > 0) {
-          throw new AlephaError(
-            `Target directory is not empty (${root}). Use --force to overwrite existing files.`,
-          );
-        }
-      }
-
-      // Detect workspace context (are we inside packages/ or apps/ of a monorepo?)
-      const workspace = await this.pm.getWorkspaceContext(root);
-
-      // Detect agent type: claude CLI → CLAUDE.md, else → AGENTS.md
-      let agentType: "claude" | "agents" | false = false;
-      if (!workspace.isPackage) {
-        const hasClaudeCli = await this.utils.isInstalledAsync("claude");
-        agentType = hasClaudeCli ? "claude" : "agents";
-      }
-
-      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;
-
-      const force = !!flags.force;
-
-      await run({
-        name: "ensuring configuration files",
-        handler: async () => {
-          await this.scaffolder.ensureConfig(root, {
-            force,
-            packageJson: { ...flags, isPackage: workspace.isPackage },
-            // Skip workspace-level configs if they exist at workspace root
-            tsconfigJson: !workspace.config.tsconfigJson,
-            biomeJson: !workspace.config.biomeJson,
-            editorconfig: !workspace.config.editorconfig,
-            agentMd: agentType ? { type: agentType } : false,
-          });
-
-          // Create alepha.config.ts with documented options
-          await this.scaffolder.ensureAlephaConfig(root, { force });
-
-          // Create project structure based on flags
-          await this.scaffolder.ensureMainServerTs(root, {
-            api: !!flags.api,
-            react: !!flags.react && !isExpo,
-            force,
-          });
-          if (flags.api) {
-            await this.scaffolder.ensureApiProject(root, {
-              auth: !!flags.auth,
-              adminEmail,
-              force,
-            });
-          }
-          if (flags.react && !isExpo) {
-            await this.scaffolder.ensureWebProject(root, {
-              api: !!flags.api,
-              ui: !!flags.ui,
-              auth: !!flags.auth,
-              admin: !!flags.admin,
-              tailwind: !!flags.tailwind,
-              force,
-            });
-          }
-        },
-      });
-
-      // Use workspace PM if detected, otherwise detect from current root
-      const pmName = await this.pm.getPackageManager(
-        workspace.workspaceRoot ?? root,
-        flags.pm ?? workspace.packageManager ?? undefined,
-      );
-
-      // Only setup PM files if not in a workspace package
-      if (!workspace.isPackage) {
-        if (pmName === "yarn") {
-          await this.pm.ensureYarn(root);
-          await run("yarn set version stable", { root });
-        } else if (pmName === "bun") {
-          await this.pm.ensureBun(root);
-        } else if (pmName === "pnpm") {
-          await this.pm.ensurePnpm(root);
-        } else {
-          await this.pm.ensureNpm(root);
-        }
-      }
-
-      // Run install from workspace root if in a package, otherwise from current root
-      const installRoot = workspace.workspaceRoot ?? root;
-      await run(`${pmName} install`, {
-        alias: `installing dependencies with ${pmName}`,
-        root: installRoot,
-      });
-
-      // Create test directory if --test flag is set (vitest is in package.json)
-      if (flags.test) {
-        await this.scaffolder.ensureTestDir(root);
-      }
-
-      await run(`${pmName} run lint`, {
-        alias: "running linter",
-        root: installRoot,
-      });
-
-      // Initialize git repository if not in a workspace package
-      if (!workspace.isPackage) {
-        const gitInitialized = await this.scaffolder.ensureGitRepo(root, {
-          force,
-        });
-        if (gitInitialized) {
-          await run("git add .", {
-            alias: "staging generated files",
-            root,
-          });
-        }
-      }
-
-      // Don't show success message if no path arg, e.g. just "alepha init" to re-configure current dir
-      if (!args) {
-        return;
-      }
-
-      // We must end the run context in order to log success message
-      run.end();
-
-      // Success message
-      const projectName = args || ".";
-      const pmRun = pmName === "npm" ? "npm run" : pmName;
-      const c = this.colors;
-
-      this.log.info("");
-      this.log.info(`  ${c.set("GREEN", "✓")} Project ready!`);
-      this.log.info("");
-      this.log.info(
-        `  ${c.set("GREY_DARK", "$")} cd ${c.set("CYAN", projectName)}`,
-      );
-      this.log.info(
-        `  ${c.set("GREY_DARK", "$")} ${c.set("CYAN", `${pmRun} dev`)}`,
-      );
-
-      if (adminEmail) {
-        this.log.info("");
-        this.log.info(`  Admin email: ${c.set("GREEN", adminEmail)}`);
-        this.log.info(
-          `  ${c.set("GREY_DARK", "(from git config, change in src/api/AppSecurity.ts)")}`,
-        );
-      }
-
-      this.log.info("");
+      await this.scaffolder.init({ run, flags, root, args });
     },
   });
 }

package/src/cli/core/index.ts

@@ -1,9 +1,16 @@
 import { $module } from "alepha";
+import { appEntryOptions } from "./atoms/appEntryOptions.ts";
+import { buildOptions } from "./atoms/buildOptions.ts";
+import { devOptions } from "./atoms/devOptions.ts";
 import { BuildCommand } from "./commands/build.ts";
 import { CleanCommand } from "./commands/clean.ts";
 import { DbCommand } from "./commands/db.ts";
 import { DevCommand } from "./commands/dev.ts";
-import { GitMessageParser, GitProvider } from "./commands/gen/changelog.ts";
+import {
+  changelogOptions,
+  GitMessageParser,
+  GitProvider,
+} from "./commands/gen/changelog.ts";
 import { GenCommand } from "./commands/gen.ts";
 import { InitCommand } from "./commands/init.ts";
 import { LintCommand } from "./commands/lint.ts";
@@ -48,7 +55,6 @@ export * from "./commands/root.ts";
 export * from "./commands/test.ts";
 export * from "./commands/typecheck.ts";
 export * from "./commands/verify.ts";
-export * from "./defineConfig.ts";
 export * from "./providers/AlephaCliExtensionProvider.ts";
 export * from "./providers/AppEntryProvider.ts";
 export * from "./providers/ViteBuildProvider.ts";
@@ -56,6 +62,7 @@ export * from "./providers/ViteDevServerProvider.ts";
 export * from "./services/AlephaCliUtils.ts";
 export * from "./services/GitMessageParser.ts";
 export * from "./services/PackageManagerUtils.ts";
+export * from "./services/ProjectScaffolder.ts";
 export * from "./services/ViteUtils.ts";
 export * from "./tasks/BuildAssetsTask.ts";
 export * from "./tasks/BuildClientTask.ts";
@@ -72,13 +79,36 @@ export * from "./version.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export const AlephaCli = $module({
-  name: "alepha.cli",
+/**
+ * Services, providers, and build tasks — no commands.
+ * Use this module when you need CLI utilities without registering commands.
+ */
+export const AlephaCliServices = $module({
+  name: "alepha.cli.services",
   services: [
+    // Services & providers
     AlephaCliUtils,
     PackageManagerUtils,
     ViteUtils,
     ProjectScaffolder,
+    AppEntryProvider,
+    GitMessageParser,
+    GitProvider,
+    ViteDevServerProvider,
+    ViteBuildProvider,
+  ],
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Full CLI module — all services and commands.
+ */
+export const AlephaCli = $module({
+  name: "alepha.cli",
+  atoms: [appEntryOptions, buildOptions, changelogOptions, devOptions],
+  services: [
+    AlephaCliExtensionProvider,
     // Commands
     BuildCommand,
     CleanCommand,
@@ -91,13 +121,6 @@ export const AlephaCli = $module({
     TypecheckCommand,
     VerifyCommand,
     GenCommand,
-    // Support services
-    AlephaCliExtensionProvider,
-    AppEntryProvider,
-    GitMessageParser,
-    GitProvider,
-    ViteDevServerProvider,
-    ViteBuildProvider,
     // Build tasks
     BuildAssetsTask,
     BuildClientTask,

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

@@ -51,7 +51,7 @@ export class ViteDevServerProvider {
 
   protected server!: ViteDevServer;
   protected options!: DevServerOptions;
-  protected alepha: Alepha | null = null;
+  public alepha: Alepha | null = null;
   protected hasError = false;
   protected currentError: Error | null = null;
   protected changedFiles = new Set<string>();
@@ -59,6 +59,7 @@ export class ViteDevServerProvider {
   protected reloadDebounceTimer: ReturnType<typeof setTimeout> | null = null;
   protected isReloading = false;
   protected needsBrowserReload = false;
+  protected currentReloadPromise: Promise<void> | null = null;
 
   /**
    * Initialize the dev server and load Alepha.
@@ -122,6 +123,7 @@ export class ViteDevServerProvider {
 
     const plugins: Plugin[] = [];
     if (viteReact && !this.options.noViteReactPlugin) plugins.push(viteReact());
+    plugins.push(this.viteUtils.createTsconfigPathsPlugin());
     plugins.push(this.viteUtils.createSsrPreloadPlugin());
     plugins.push(this.createAlephaPlugin());
 
@@ -233,6 +235,13 @@ export class ViteDevServerProvider {
           });
         }
 
+        // Re-send error overlay when a new browser connects (e.g. page refresh during error state)
+        server.hot.on("connection", () => {
+          if (this.currentError) {
+            setTimeout(() => this.sendErrorOverlay(this.currentError!), 50);
+          }
+        });
+
         // Return function to run AFTER Vite's built-in middleware
         return () => {
           server.middlewares.use(async (req, res, next) => {
@@ -243,8 +252,16 @@ export class ViteDevServerProvider {
               return;
             }
 
-            // In error state, let Vite serve its error overlay
+            // 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) {
+              if (req.headers.accept?.includes("text/html")) {
+                res.writeHead(200, { "content-type": "text/html" });
+                res.end(
+                  '<!DOCTYPE html><html><head><script type="module" src="/@vite/client"></script></head><body></body></html>',
+                );
+                return;
+              }
               next();
               return;
             }
@@ -287,10 +304,15 @@ export class ViteDevServerProvider {
         // Queue Alepha reload for server-side invalidation
         this.changedFiles.add(ctx.file);
 
-        // React components (.tsx/.jsx): restart Alepha silently,
-        // let Vite HMR handle the browser update (React Fast Refresh)
+        // React components (.tsx/.jsx): reload Alepha BEFORE letting
+        // Vite HMR reach the browser, to prevent 503 errors from
+        // components that fetch data on mount during server reload.
         if (/\.(tsx|jsx)$/.test(ctx.file)) {
-          this.scheduleReload();
+          if (this.reloadDebounceTimer) {
+            clearTimeout(this.reloadDebounceTimer);
+            this.reloadDebounceTimer = null;
+          }
+          await this.performReload();
           return;
         }
 
@@ -350,19 +372,34 @@ export class ViteDevServerProvider {
   }
 
   /**
-   * Perform the actual reload after debounce.
+   * Perform the actual reload.
+   * Returns a promise that callers can await to know when reload is done.
+   * If a reload is already in progress, returns that promise.
    */
-  protected async performReload(): Promise<void> {
-    if (this.isReloading || this.changedFiles.size === 0) {
-      return;
+  protected performReload(): Promise<void> {
+    if (this.changedFiles.size === 0) {
+      return this.currentReloadPromise ?? Promise.resolve();
+    }
+
+    if (this.isReloading) {
+      return this.currentReloadPromise ?? Promise.resolve();
     }
 
+    this.currentReloadPromise = this.executeReload();
+    return this.currentReloadPromise;
+  }
+
+  /**
+   * Execute the reload work.
+   */
+  protected async executeReload(): Promise<void> {
     this.isReloading = true;
 
     // Snapshot files to process and clear immediately
     // New files arriving during reload will go to fresh set
     const filesToInvalidate = new Set(this.changedFiles);
     const sendReload = this.needsBrowserReload;
+    const wasInError = this.hasError;
     this.changedFiles.clear();
     this.needsBrowserReload = false;
 
@@ -375,7 +412,7 @@ export class ViteDevServerProvider {
       await this.alepha?.start();
 
       this.currentError = null;
-      if (sendReload) {
+      if (sendReload || wasInError) {
         this.sendBrowserReload();
       }
     } catch (err) {
@@ -386,6 +423,7 @@ export class ViteDevServerProvider {
       this.sendErrorOverlay(this.currentError);
     } finally {
       this.isReloading = false;
+      this.currentReloadPromise = null;
 
       // If more files changed during reload, schedule another
       if (this.changedFiles.size > 0) {
@@ -597,6 +635,8 @@ export class ViteDevServerProvider {
           this.waitingForRetry = false;
           this.currentError = null;
           this.server.watcher.off("change", onFileChange);
+          this.server.watcher.off("add", onFileChange);
+          this.sendBrowserReload();
           resolve(alepha);
         } catch (err) {
           this.hasError = true;
@@ -609,6 +649,7 @@ export class ViteDevServerProvider {
       };
 
       this.server.watcher.on("change", onFileChange);
+      this.server.watcher.on("add", onFileChange);
     });
   }
 
@@ -657,13 +698,11 @@ 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();
   }