alepha 0.15.3 → 0.15.5

package/src/cli/commands/db.ts

@@ -9,6 +9,7 @@ import type {
 import { FileSystemProvider } from "alepha/system";
 import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 
 const drizzleCommandFlags = t.object({
   provider: t.optional(
@@ -29,6 +30,7 @@ export class DbCommand {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly utils = $inject(AlephaCliUtils);
+  protected readonly pm = $inject(PackageManagerUtils);
   protected readonly entryProvider = $inject(AppEntryProvider);
 
   /**
@@ -316,6 +318,13 @@ export class DbCommand {
       this.log.info("");
       this.log.info(options.logMessage(providerName, dialect));
 
+      if (dialect === "sqlite") {
+        await this.pm.ensureDependency(options.root, "better-sqlite3", {
+          dev: true,
+          exec: (cmd, opts) => this.utils.exec(cmd, opts),
+        });
+      }
+
       const drizzleConfigJsPath = await this.prepareDrizzleConfig({
         kit: drizzleKitProvider,
         provider,

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

@@ -316,7 +316,7 @@ describe("alepha init", () => {
 
       expect(fs.wasWritten("/project/src/web/index.ts")).toBe(true);
       expect(fs.wasWritten("/project/src/web/AppRouter.ts")).toBe(true);
-      expect(fs.wasWritten("/project/src/web/components/Hello.tsx")).toBe(true);
+      expect(fs.wasWritten("/project/src/web/components/Home.tsx")).toBe(true);
     });
 
     it("should create main.browser.ts for client-side entry", async () => {
@@ -331,28 +331,13 @@ describe("alepha init", () => {
       ).toBe(true);
     });
 
-    it("should create main.css with base styles", async () => {
+    it("should create main.css", async () => {
       const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
 
       await cli.run(cmd.init, { argv: "--react", root: "/project" });
 
       expect(fs.wasWritten("/project/src/main.css")).toBe(true);
-      expect(fs.wasWrittenMatching("/project/src/main.css", /box-sizing/)).toBe(
-        true,
-      );
-    });
-
-    it("should create main.css with @alepha/ui import when --ui", async () => {
-      const { fs, cli, cmd, json } = createTestEnv();
-      await setupProject(fs, json);
-
-      await cli.run(cmd.init, { argv: "--react --ui", root: "/project" });
-
-      expect(fs.wasWritten("/project/src/main.css")).toBe(true);
-      expect(
-        fs.wasWrittenMatching("/project/src/main.css", /@alepha\/ui\/styles/),
-      ).toBe(true);
     });
 
     it("should not create api structure without --api flag", async () => {

package/src/cli/commands/init.ts

@@ -1,11 +1,14 @@
 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);
@@ -106,6 +109,11 @@ export class InitCommand {
 
       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({
@@ -113,9 +121,9 @@ export class InitCommand {
         handler: async () => {
           await this.scaffolder.ensureConfig(root, {
             force,
-            tsconfigJson: !workspace.config.tsconfigJson,
             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
@@ -132,6 +140,7 @@ export class InitCommand {
           if (flags.api) {
             await this.scaffolder.ensureApiProject(root, {
               auth: !!flags.auth,
+              adminEmail,
               force,
             });
           }
@@ -196,6 +205,33 @@ export class InitCommand {
           });
         }
       }
+
+      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("");
     },
   });
 }

package/src/cli/providers/ViteDevServerProvider.ts

@@ -219,6 +219,9 @@ export class ViteDevServerProvider {
       );
     }
 
+    // expose Vite server to Alepha for Logger SSR Fix stack traces
+    alepha.store.set("alepha.vite.server" as any, this.server);
+
     this.alepha = alepha;
     await this.setupAlepha();
 
@@ -245,6 +248,11 @@ export class ViteDevServerProvider {
       return;
     }
 
+    // Generate dev head content using Vite's transformIndexHtml
+    // This lets Vite and all plugins (React, etc.) inject their scripts
+    const devHead = await this.generateDevHead();
+    this.alepha.store.set("alepha.react.ssr.manifest" as any, { devHead });
+
     this.alepha.events.on("server:onRequest", {
       priority: "first",
       callback: async ({ request }) => {
@@ -264,6 +272,32 @@ export class ViteDevServerProvider {
     });
   }
 
+  /**
+   * Generate dev head content by transforming a minimal HTML through Vite.
+   * This lets Vite and all plugins inject their scripts (HMR client, React Fast Refresh, etc.).
+   */
+  protected async generateDevHead(): Promise<string> {
+    const { browser, style } = this.options.entry;
+
+    // Build minimal HTML with entry points
+    const scripts: string[] = [];
+    if (style) {
+      scripts.push(`<link rel="stylesheet" href="/${style}">`);
+    }
+    if (browser) {
+      scripts.push(`<script type="module" src="/${browser}"></script>`);
+    }
+
+    const minimalHtml = `<!DOCTYPE html><html><head>${scripts.join("\n")}</head><body></body></html>`;
+
+    // Transform through Vite to inject all plugin scripts
+    const transformed = await this.server.transformIndexHtml("/", minimalHtml);
+
+    // Extract head content
+    const headMatch = transformed.match(/<head>([\s\S]*?)<\/head>/i);
+    return headMatch?.[1]?.trim() ?? "";
+  }
+
   /**
    * Check if request is for an HTML page (not an asset).
    */
@@ -312,8 +346,8 @@ export class ViteDevServerProvider {
       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
+        if (resolved && ctx.metadata.vite) {
+          // Vite already handled this request, ignore late writes from framework
           return undefined as T;
         }
         return fn(...args);

package/src/cli/services/AlephaCliUtils.ts

@@ -161,4 +161,21 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       return "unknown";
     }
   }
+
+  /**
+   * Get the user's email from git config.
+   *
+   * @returns The git user email or undefined if not configured
+   */
+  public async getGitEmail(): Promise<string | undefined> {
+    try {
+      const result = await this.shell.run("git config user.email", {
+        capture: true,
+      });
+      const email = result.trim();
+      return email || undefined;
+    } catch {
+      return undefined;
+    }
+  }
 }

package/src/cli/services/PackageManagerUtils.ts

@@ -48,6 +48,7 @@ export class PackageManagerUtils {
 
   /**
    * Detect the package manager used in the project.
+   * Checks current directory first, then workspace root if in a monorepo.
    */
   public async getPackageManager(
     root: string,
@@ -55,10 +56,21 @@ export class PackageManagerUtils {
   ): Promise<"yarn" | "pnpm" | "npm" | "bun"> {
     if (pm) return pm;
     if (this.alepha.isBun()) return "bun";
+
+    // Check current directory first
     if (await this.fs.exists(this.fs.join(root, "bun.lock"))) return "bun";
     if (await this.fs.exists(this.fs.join(root, "yarn.lock"))) return "yarn";
     if (await this.fs.exists(this.fs.join(root, "pnpm-lock.yaml")))
       return "pnpm";
+    if (await this.fs.exists(this.fs.join(root, "package-lock.json")))
+      return "npm";
+
+    // Check workspace root (for monorepo packages like apps/blog)
+    const workspace = await this.getWorkspaceContext(root);
+    if (workspace.packageManager) {
+      return workspace.packageManager;
+    }
+
     return "npm";
   }
 
@@ -358,7 +370,9 @@ export class PackageManagerUtils {
       alepha: `^${version}`,
     };
 
-    const devDependencies: Record<string, string> = {};
+    const devDependencies: Record<string, string> = {
+      vite: alephaDeps.vite,
+    };
 
     // Add biome/vitest only if not a workspace package (workspace root has them)
     if (!modes.isPackage) {

package/src/cli/services/ProjectScaffolder.ts

@@ -19,7 +19,7 @@ import { mainCss } from "../templates/mainCss.ts";
 import { mainServerTs } from "../templates/mainServerTs.ts";
 import { tsconfigJson } from "../templates/tsconfigJson.ts";
 import { webAppRouterTs } from "../templates/webAppRouterTs.ts";
-import { webHelloComponentTsx } from "../templates/webHelloComponentTsx.ts";
+import { webHomeComponentTsx } from "../templates/webHomeComponentTsx.ts";
 import { webIndexTs } from "../templates/webIndexTs.ts";
 import { AlephaCliUtils } from "./AlephaCliUtils.ts";
 import {
@@ -34,7 +34,7 @@ import {
  * - Project structure (src/api, src/web)
  * - Configuration files (tsconfig, biome, editorconfig)
  * - Entry points (main.server.ts, main.browser.ts)
- * - Example code (HelloController, Hello component)
+ * - Example code (HelloController, Home component)
  */
 export class ProjectScaffolder {
   protected readonly log = $logger();
@@ -228,7 +228,7 @@ export class ProjectScaffolder {
    */
   public async ensureApiProject(
     root: string,
-    opts: { auth?: boolean; force?: boolean } = {},
+    opts: { auth?: boolean; adminEmail?: string; force?: boolean } = {},
   ): Promise<void> {
     const appName = this.getAppName(root);
 
@@ -256,7 +256,7 @@ export class ProjectScaffolder {
       await this.ensureFile(
         root,
         "src/api/AppSecurity.ts",
-        apiAppSecurityTs(),
+        apiAppSecurityTs({ adminEmail: opts.adminEmail }),
         opts.force,
       );
     }
@@ -272,7 +272,7 @@ export class ProjectScaffolder {
    * Creates:
    * - src/main.browser.ts
    * - src/main.css
-   * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
+   * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Home.tsx
    */
   public async ensureWebProject(
     root: string,
@@ -292,12 +292,7 @@ export class ProjectScaffolder {
     });
 
     // src/main.css
-    await this.ensureFile(
-      root,
-      "src/main.css",
-      mainCss({ ui: opts.ui }),
-      opts.force,
-    );
+    await this.ensureFile(root, "src/main.css", mainCss(), opts.force);
 
     // Web structure
     await this.ensureFile(
@@ -319,8 +314,8 @@ export class ProjectScaffolder {
     );
     await this.ensureFile(
       root,
-      "src/web/components/Hello.tsx",
-      webHelloComponentTsx({ auth: opts.auth }),
+      "src/web/components/Home.tsx",
+      webHomeComponentTsx(),
       opts.force,
     );
     await this.ensureFile(

package/src/cli/templates/agentMd.ts

@@ -27,6 +27,7 @@ This file provides guidance to AI coding assistants when working with this Aleph
 
 ### Pages with \`$page\`
 \`\`\`tsx
+import { t } from "alepha";
 import { $page } from "alepha/react/router";
 import { $client } from "alepha/server/links";
 import type { UserController } from "./UserController.ts";
@@ -196,31 +197,6 @@ class AppRouter {
 }
 \`\`\`
 
-### Modules with \`$module\`
-\`\`\`typescript
-// src/api/index.ts - Groups all API services
-import { $module } from "alepha";
-
-export const ApiModule = $module({
-  name: "app.api",
-  services: [
-    UserController,
-    OrderController,
-    UserService,
-  ],
-});
-
-// src/web/index.ts - Groups all web services (React only)
-export const WebModule = $module({
-  name: "app.web",
-  services: [AppRouter, Toaster],
-  register(alepha) {
-    // Optional: configure additional services
-    alepha.with(SomeLibrary);
-  },
-});
-\`\`\`
-
 ### Environment Variables
 \`\`\`typescript
 import { $env, t } from "alepha";
@@ -268,6 +244,7 @@ describe("UserService", () => {
   it("should create user", async () => {
     const alepha = Alepha.create().with(UserService);
     const service = alepha.inject(UserService);
+    await alepha.start();
 
     const user = await service.create({ email: "test@example.com" });
     expect(user.email).toBe("test@example.com");

package/src/cli/templates/apiAppSecurityTs.ts

@@ -1,10 +1,45 @@
-export const apiAppSecurityTs = () => {
+export const apiAppSecurityTs = (opts: { adminEmail?: string } = {}) => {
+  const adminEmailsValue = opts.adminEmail ? `["${opts.adminEmail}"]` : "[]";
+
   return `
 import { $realm } from "alepha/api/users";
 
 export class AppSecurity {
   users = $realm({
-    // configure your realm here
+    settings: {
+      // Auto-promote these users to admin on login
+      adminEmails: ${adminEmailsValue},
+      adminUsernames: [],
+
+      // Registration & login options
+      registrationAllowed: true,
+      emailEnabled: true,
+      emailRequired: true,
+      usernameEnabled: false,
+      usernameRequired: false,
+      phoneEnabled: false,
+      phoneRequired: false,
+
+      // Verification (requires notifications feature)
+      verifyEmailRequired: false,
+      verifyPhoneRequired: false,
+      resetPasswordAllowed: false,
+    },
+    features: {
+      // Enable additional features
+      notifications: false,
+      audits: false,
+      apiKeys: false,
+      jobs: false,
+      files: false,
+      parameters: false,
+    },
+    identities: {
+      // Enable authentication providers
+      credentials: true,
+      // google: true,
+      // github: true,
+    },
   });
 }
 `.trim();

package/src/cli/templates/mainCss.ts

@@ -1,33 +1,3 @@
-export interface MainCssOptions {
-  ui?: boolean;
-}
-
-export const mainCss = (options: MainCssOptions = {}) => {
-  if (options.ui) {
-    return `@import "@alepha/ui/styles";`;
-  }
-
-  return `
-* {
-  box-sizing: border-box;
-  margin: 0;
-  padding: 0;
-}
-
-html,
-body {
-  height: 100%;
-}
-
-body {
-  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
-    "Helvetica Neue", Arial, sans-serif;
-  line-height: 1.5;
-  -webkit-font-smoothing: antialiased;
-}
-
-#root {
-  height: 100%;
-}
-`.trim();
+export const mainCss = () => {
+  return `@import "@alepha/ui/styles";`;
 };

package/src/cli/templates/webAppRouterTs.ts

@@ -47,22 +47,22 @@ export const webAppRouterTs = (options: {
     }
 
     classMembers.push(`  layout = $page({
-    parent: this.ui.root,
-    children: () => [this.home],
-  });`);
+      parent: this.ui.root,
+      children: () => [this.home],
+    });`);
   }
 
   // Home page - with or without loader
   if (options.api) {
     classMembers.push(`  home = $page({
     path: "/",
-    lazy: () => import("./components/Hello.tsx"),
+    lazy: () => import("./components/Home.tsx"),
     loader: () => this.api.hello(),
   });`);
   } else {
     classMembers.push(`  home = $page({
     path: "/",
-    lazy: () => import("./components/Hello.tsx"),
+    lazy: () => import("./components/Home.tsx"),
   });`);
   }
 

package/src/cli/templates/webHomeComponentTsx.ts

@@ -0,0 +1,10 @@
+export const webHomeComponentTsx = () => {
+  return `import { GettingStarted } from "alepha/react/intro";
+
+const Home = () => {
+  return <GettingStarted />;
+};
+
+export default Home;
+`;
+};

package/src/command/helpers/Runner.ts

@@ -34,11 +34,19 @@ export interface RunnerMethod {
   ): Promise<string>;
   rm: (glob: string | string[], options?: RunOptions) => Promise<string>;
   cp: (source: string, dest: string, options?: RunOptions) => Promise<string>;
+
+  /**
+   * Ends the runner and prints a summary of executed tasks.
+   *
+   * > This is automatically called at the end of command execution.
+   * > But can be called manually if needed to print more stuff before the command ends.
+   */
+  end: () => void;
 }
 
 export class Runner {
   protected readonly log = $logger();
-  protected readonly timers: Timer[] = [];
+  protected timers: Timer[] = [];
   protected readonly startTime: number = Date.now();
   protected readonly prettyPrint = $inject(PrettyPrint);
   protected readonly alepha = $inject(Alepha);
@@ -149,6 +157,8 @@ export class Runner {
       );
     };
 
+    runFn.end = () => this.end();
+
     return runFn;
   }
 
@@ -189,6 +199,9 @@ export class Runner {
     const totalTime = ((Date.now() - this.startTime) / 1000).toFixed(1);
     this.log.info(`Total time: ${totalTime}s`);
     this.log.info(``);
+
+    // clear timers after rendering
+    this.timers = [];
   }
 
   protected async executeTask(task: Task): Promise<string> {

package/src/command/index.ts

@@ -19,9 +19,9 @@ export * from "./providers/CliProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | tooling | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.6.0 | node, bun|
  *
  * Declarative CLI command framework.
  *

package/src/core/helpers/primitive.ts

@@ -47,11 +47,6 @@ export abstract class Primitive<T extends object = {}> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type PrimitiveFactory<TPrimitive extends Primitive = Primitive> = {
-  (options: TPrimitive["options"]): TPrimitive;
-  [KIND]: InstantiableClass<TPrimitive>;
-};
-
 export type PrimitiveFactoryLike<T extends object = any> = {
   (options: T): any;
   [KIND]: any;

package/src/core/index.ts

@@ -23,9 +23,9 @@ export * from "./index.shared.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | tooling | epic | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd, browser, expo|
  *
  * Foundation of the entire framework with dependency injection and lifecycle management.
  *

package/src/datetime/index.ts

@@ -8,9 +8,9 @@ export * from "./providers/DateTimeProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | tooling | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.10.0 | node, bun, workerd, browser, expo|
  *
  * Date and time operations.
  *

package/src/email/index.ts

@@ -36,9 +36,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.4.0 | node, bun, workerd|
  *
  * Email delivery with template support.
  *

package/src/email/index.workerd.ts

@@ -0,0 +1,36 @@
+import { $module } from "alepha";
+import { $email } from "./primitives/$email.ts";
+import { EmailProvider } from "./providers/EmailProvider.ts";
+import { MemoryEmailProvider } from "./providers/MemoryEmailProvider.ts";
+import { WorkermailerEmailProvider } from "./providers/WorkermailerEmailProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./errors/EmailError.ts";
+export * from "./primitives/$email.ts";
+export * from "./providers/EmailProvider.ts";
+export * from "./providers/MemoryEmailProvider.ts";
+export * from "./providers/WorkermailerEmailProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaEmail = $module({
+  name: "alepha.email",
+  primitives: [$email],
+  services: [EmailProvider, MemoryEmailProvider, WorkermailerEmailProvider],
+  register: (alepha) => {
+    if (alepha.env.EMAIL_HOST) {
+      alepha.with({
+        optional: true,
+        provide: EmailProvider,
+        use: WorkermailerEmailProvider,
+      });
+    } else {
+      alepha.with({
+        optional: true,
+        provide: EmailProvider,
+        use: MemoryEmailProvider,
+      });
+    }
+  },
+});