alepha 0.15.4 → 0.15.5

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

@@ -0,0 +1,107 @@
+import { Alepha } from "alepha";
+import { AlephaApiJobs } from "alepha/api/jobs";
+import { $repository, AlephaOrm } from "alepha/orm";
+import { describe, test } from "vitest";
+import { sessions } from "../entities/sessions.ts";
+import { users } from "../entities/users.ts";
+import { UserJobs } from "./UserJobs.ts";
+
+describe("UserJobs", () => {
+  describe("purgeExpiredSessions", () => {
+    test("should delete expired sessions", async ({ expect }) => {
+      const alepha = Alepha.create().with(AlephaOrm).with(AlephaApiJobs);
+
+      class TestRepositories {
+        userRepository = $repository(users);
+        sessionRepository = $repository(sessions);
+      }
+
+      const userJobs = alepha.inject(UserJobs);
+      const repos = alepha.inject(TestRepositories);
+      await alepha.start();
+
+      // Create a test user
+      const user = await repos.userRepository.create({
+        email: "test@example.com",
+      });
+
+      // Create expired sessions (expiresAt in the past)
+      const pastDate = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(); // 1 day ago
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: pastDate,
+      });
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: pastDate,
+      });
+
+      // Create a valid session (expiresAt in the future)
+      const futureDate = new Date(
+        Date.now() + 24 * 60 * 60 * 1000,
+      ).toISOString(); // 1 day from now
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: futureDate,
+      });
+
+      // Verify we have 3 sessions
+      const sessionsBefore = await repos.sessionRepository.findMany();
+      expect(sessionsBefore).toHaveLength(3);
+
+      // Trigger the job
+      await userJobs.purgeExpiredSessions.trigger();
+
+      // Verify only the valid session remains
+      const sessionsAfter = await repos.sessionRepository.findMany();
+      expect(sessionsAfter).toHaveLength(1);
+      expect(new Date(sessionsAfter[0].expiresAt).getTime()).toBeGreaterThan(
+        Date.now(),
+      );
+    });
+
+    test("should handle case when no expired sessions exist", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create().with(AlephaOrm).with(AlephaApiJobs);
+
+      class TestRepositories {
+        userRepository = $repository(users);
+        sessionRepository = $repository(sessions);
+      }
+
+      const userJobs = alepha.inject(UserJobs);
+      const repos = alepha.inject(TestRepositories);
+      await alepha.start();
+
+      // Create a test user
+      const user = await repos.userRepository.create({
+        email: "test2@example.com",
+      });
+
+      // Create only valid sessions
+      const futureDate = new Date(
+        Date.now() + 24 * 60 * 60 * 1000,
+      ).toISOString();
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: futureDate,
+      });
+
+      // Verify we have 1 session
+      const sessionsBefore = await repos.sessionRepository.findMany();
+      expect(sessionsBefore).toHaveLength(1);
+
+      // Trigger the job - should not throw
+      await userJobs.purgeExpiredSessions.trigger();
+
+      // Session should still exist
+      const sessionsAfter = await repos.sessionRepository.findMany();
+      expect(sessionsAfter).toHaveLength(1);
+    });
+  });
+});

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

@@ -0,0 +1,62 @@
+import { $inject } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import { sessions } from "../entities/sessions.ts";
+
+/**
+ * User-specific jobs wrapper service.
+ *
+ * This service handles user-related scheduled jobs such as:
+ * - Session purge (cleaning up expired sessions)
+ * - Verification code cleanup
+ * - Inactive user notifications
+ *
+ * It is lazy-loaded when the `jobs` feature is enabled in the realm.
+ */
+export class UserJobs {
+  protected readonly log = $logger();
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly sessionRepository = $repository(sessions);
+
+  /**
+   * Purge expired sessions from the database.
+   *
+   * This job runs daily at 3:00 AM and removes all sessions
+   * where the `expiresAt` timestamp has passed.
+   */
+  public readonly purgeExpiredSessions = $job({
+    name: "users.purgeExpiredSessions",
+    description: "Remove expired user sessions from the database",
+    cron: "0 3 * * *", // Daily at 3:00 AM
+    handler: async () => {
+      const now = this.dateTimeProvider.nowISOString();
+
+      this.log.info("Starting expired sessions purge", { cutoffTime: now });
+
+      const expiredSessions = await this.sessionRepository.findMany({
+        where: {
+          expiresAt: { lt: now },
+        },
+      });
+
+      if (expiredSessions.length === 0) {
+        this.log.info("No expired sessions found");
+        return;
+      }
+
+      this.log.info("Found expired sessions", {
+        count: expiredSessions.length,
+      });
+
+      const deletedIds = await this.sessionRepository.deleteMany({
+        expiresAt: { lt: now },
+      });
+
+      this.log.info("Expired sessions purged successfully", {
+        deletedCount: deletedIds.length,
+      });
+    },
+  });
+}

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

@@ -0,0 +1,23 @@
+import { $config } from "alepha/api/parameters";
+import { realmAuthSettingsAtom } from "../atoms/realmAuthSettingsAtom.ts";
+
+/**
+ * User-specific configuration service.
+ *
+ * This service wraps the core ConfigStore to provide realm settings management.
+ * It is lazy-loaded when the `parameters` feature is enabled in the realm.
+ */
+export class UserParameters {
+  /**
+   * Realm authentication settings configuration.
+   *
+   * Controls user registration, login methods, verification requirements,
+   * and password policies for the realm.
+   */
+  public readonly realmSettings = $config({
+    name: "alepha.api.users.realmSettings",
+    description: "Realm authentication and registration settings",
+    schema: realmAuthSettingsAtom.schema,
+    default: realmAuthSettingsAtom.options.default,
+  });
+}

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

@@ -1,23 +1,38 @@
-import { $inject } from "alepha";
-import { AuditService } from "alepha/api/audits";
+import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $logger } from "alepha/logger";
 import { type Page, parseQueryString } from "alepha/orm";
 import { BadRequestError } from "alepha/server";
 import { $client } from "alepha/server/links";
 import type { UserEntity } from "../entities/users.ts";
-import { UserNotifications } from "../notifications/UserNotifications.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { CreateUser } from "../schemas/createUserSchema.ts";
 import type { UpdateUser } from "../schemas/updateUserSchema.ts";
 import type { UserQuery } from "../schemas/userQuerySchema.ts";
+import { UserAudits } from "./UserAudits.ts";
+import { UserNotifications } from "./UserNotifications.ts";
 
 export class UserService {
+  protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly verificationController = $client<VerificationController>();
-  protected readonly userNotifications = $inject(UserNotifications);
   protected readonly realmProvider = $inject(RealmProvider);
-  protected readonly auditService = $inject(AuditService);
+
+  protected userAudits(realmName?: string) {
+    const realm = this.realmProvider.getRealm(realmName);
+    if (realm.features.audits) {
+      return this.alepha.inject(UserAudits);
+    }
+    return undefined;
+  }
+
+  protected userNotifications(realmName?: string) {
+    const realm = this.realmProvider.getRealm(realmName);
+    if (realm.features.notifications) {
+      return this.alepha.inject(UserNotifications);
+    }
+    return undefined;
+  }
 
   public users(userRealmName?: string) {
     return this.realmProvider.userRepository(userRealmName);
@@ -79,21 +94,23 @@ export class UserService {
           ? `${verifyUrl}${url.search}`
           : url.pathname + url.search;
 
-        await this.userNotifications.emailVerificationLink.push({
-          contact: email,
-          variables: {
-            email,
-            verifyUrl: fullVerifyUrl,
-            expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+        await this.userNotifications(userRealmName)?.emailVerificationLink.push(
+          {
+            contact: email,
+            variables: {
+              email,
+              verifyUrl: fullVerifyUrl,
+              expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+            },
           },
-        });
+        );
 
         this.log.debug("Email verification link sent", {
           email,
           userId: user.id,
         });
       } else {
-        await this.userNotifications.emailVerification.push({
+        await this.userNotifications(userRealmName)?.emailVerification.push({
           contact: email,
           variables: {
             email,
@@ -158,7 +175,7 @@ export class UserService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("update", {
+    await this.userAudits(userRealmName)?.recordUser("update", {
       userId: user.id,
       userEmail: email,
       userRealm: realm.name,
@@ -314,7 +331,7 @@ export class UserService {
       email: user.email,
     });
 
-    await this.auditService.recordUser("create", {
+    await this.userAudits(userRealmName)?.recordUser("create", {
       userRealm: realm.name,
       resourceId: user.id,
       description: "User created",
@@ -357,7 +374,7 @@ export class UserService {
       data.roles !== undefined &&
       JSON.stringify(before.roles) !== JSON.stringify(data.roles);
 
-    await this.auditService.recordUser(
+    await this.userAudits(userRealmName)?.recordUser(
       isRoleChange ? "role_change" : "update",
       {
         userRealm: realm.name,
@@ -384,7 +401,7 @@ export class UserService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("delete", {
+    await this.userAudits(userRealmName)?.recordUser("delete", {
       userRealm: realm.name,
       resourceId: id,
       severity: "warning",

package/src/api/verifications/index.ts

@@ -18,9 +18,9 @@ export * from "./services/VerificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.13.0 | node, bun, workerd|
  *
  * Email and phone verification workflows.
  *

package/src/batch/index.ts

@@ -10,9 +10,9 @@ export * from "./providers/BatchProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.8.0 | node, bun|
  *
  * Batch accumulation and processing.
  *

package/src/bucket/index.ts

@@ -43,9 +43,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.9.0 | node, bun, workerd|
  *
  * Unified file storage abstraction across multiple backends.
  *

package/src/cache/core/index.ts

@@ -12,9 +12,9 @@ export * from "./providers/MemoryCacheProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.9.0 | node, bun, workerd|
  *
  * Type-safe caching with TTL support.
  *

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();
 
@@ -343,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(