alepha 0.20.2 → 0.20.3

package/src/cli/core/templates/saasAdminPagesTsx.ts

@@ -0,0 +1,26 @@
+/**
+ * Admin pages — each is a thin wrapper around the matching `admin-*`
+ * registry component (placed at `src/components/admin/*`). The starter
+ * ships with Users + Sessions; add more by `shadcn add @alepha/admin-…`
+ * and a matching `$page(...)` in AppRouter.
+ */
+
+export const saasAdminUsersTsx = () =>
+  `import { AdminUsers } from "@/components/admin/admin-users";
+
+const AdminUsersPage = () => {
+  return <AdminUsers />;
+};
+
+export default AdminUsersPage;
+`;
+
+export const saasAdminSessionsTsx = () =>
+  `import { AdminSessions } from "@/components/admin/admin-sessions";
+
+const AdminSessionsPage = () => {
+  return <AdminSessions />;
+};
+
+export default AdminSessionsPage;
+`;

package/src/cli/core/templates/saasAuthLayoutTsx.ts

@@ -0,0 +1,20 @@
+/**
+ * SaaS auth layout — wraps every /auth/* page with a centered card.
+ * Routes (login, register, reset-password, verify-email) are mounted as
+ * children so they share this shell.
+ */
+export const saasAuthLayoutTsx = () =>
+  `import { NestedView } from "alepha/react/router";
+
+const AuthLayout = () => {
+  return (
+    <div className="bg-background flex min-h-screen items-center justify-center p-4">
+      <div className="w-full max-w-md">
+        <NestedView />
+      </div>
+    </div>
+  );
+};
+
+export default AuthLayout;
+`;

package/src/cli/core/templates/saasAuthPagesTsx.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-page wrapper around the registry components. The registry component
+ * receives the realm config from the page loader; the page itself stays a
+ * thin shell so apps can layer their branding around it.
+ *
+ * Registry components land at `src/components/auth/*` (shadcn defaults).
+ */
+
+export const saasAuthLoginTsx = () =>
+  `import { AuthLogin } from "@/components/auth/auth-login";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthLoginPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthLoginPage = (props: AuthLoginPageProps) => {
+  return <AuthLogin realmConfig={props.realmConfig} />;
+};
+
+export default AuthLoginPage;
+`;
+
+export const saasAuthRegisterTsx = () =>
+  `import { AuthRegister } from "@/components/auth/auth-register";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthRegisterPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthRegisterPage = (props: AuthRegisterPageProps) => {
+  return <AuthRegister realmConfig={props.realmConfig} />;
+};
+
+export default AuthRegisterPage;
+`;
+
+export const saasAuthResetPasswordTsx = () =>
+  `import { AuthResetPassword } from "@/components/auth/auth-reset-password";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthResetPasswordPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthResetPasswordPage = (props: AuthResetPasswordPageProps) => {
+  return <AuthResetPassword realmConfig={props.realmConfig} />;
+};
+
+export default AuthResetPasswordPage;
+`;
+
+export const saasAuthVerifyEmailTsx = () =>
+  `import { AuthVerifyEmail } from "@/components/auth/auth-verify-email";
+
+const AuthVerifyEmailPage = () => {
+  return <AuthVerifyEmail />;
+};
+
+export default AuthVerifyEmailPage;
+`;

package/src/cli/core/templates/saasRealmProviderTs.ts

@@ -0,0 +1,46 @@
+export interface SaasRealmProviderOptions {
+  /**
+   * Email seeded as the default admin. Detected from `git config user.email`
+   * at init time; falls through to `admin@example.com` if git isn't configured.
+   */
+  adminEmail?: string;
+}
+
+/**
+ * Realm provider scaffolded by `alepha init --saas`.
+ *
+ * Minimal hello-world setup: credentials login with email, one admin seeded
+ * with the developer's git email at scaffold time, and an `admin:ui`
+ * permission used by the AppRouter to gate `/admin/*`. The default `admin`
+ * role grants `*` (so it inherits `admin:ui`); the default `user` role
+ * excludes `admin:*` (so non-admins get a 403 before the shell renders).
+ *
+ * Add `$env`, more permissions, or stricter settings as the project grows.
+ */
+export const saasRealmProviderTs = (options: SaasRealmProviderOptions = {}) => {
+  const adminEmail = options.adminEmail ?? "admin@example.com";
+  return `import { $realm } from "alepha/api/users";
+import { $permission } from "alepha/security";
+
+export class RealmProvider {
+  /**
+   * Permission required to open the admin UI. Wired into AppRouter.adminLayout
+   * via \`$secure({ permissions: ["admin:ui"] })\`.
+   */
+  adminUi = $permission({
+    group: "admin",
+    name: "ui",
+    description: "Access to the admin UI shell",
+  });
+
+  realm = $realm({
+    settings: {
+      adminEmails: [${JSON.stringify(adminEmail)}],
+    },
+    identities: {
+      credentials: true,
+    },
+  });
+}
+`;
+};

package/src/cli/core/templates/webAppRouterTs.ts

@@ -1,4 +1,16 @@
-export const webAppRouterTs = (options: { api?: boolean }) => {
+export interface WebAppRouterOptions {
+  api?: boolean;
+  saas?: boolean;
+}
+
+export const webAppRouterTs = (options: WebAppRouterOptions) => {
+  if (options.saas) {
+    return saasAppRouterTs();
+  }
+  return basicAppRouterTs(options);
+};
+
+const basicAppRouterTs = (options: WebAppRouterOptions) => {
   const imports: string[] = ['import { $page } from "alepha/react/router";'];
   const classMembers: string[] = [];
 
@@ -27,3 +39,94 @@ export class AppRouter {
 ${classMembers.join("\n\n")}
 }`;
 };
+
+/**
+ * SaaS router wires three trees onto the app:
+ *   /            → Home
+ *   /auth/*      → AuthLayout + login / register / reset / verify
+ *   /admin/*     → AdminLayout + users / sessions / api-keys / parameters / audits
+ *
+ * Each auth page resolves the realm config from its loader, so the registry
+ * components render with everything they need on first paint.
+ */
+const saasAppRouterTs =
+  () => `import type { RealmController } from "alepha/api/users";
+import { $page, NotFound } from "alepha/react/router";
+import { $secure } from "alepha/security";
+import { $client } from "alepha/server/links";
+import type { HelloController } from "../api/controllers/HelloController.ts";
+
+export class AppRouter {
+  protected readonly api = $client<HelloController>();
+  protected readonly realmApi = $client<RealmController>();
+
+  home = $page({
+    path: "/",
+    lazy: () => import("./components/Home.tsx"),
+    loader: () => this.api.hello(),
+  });
+
+  // ── /auth — login, register, reset, verify ─────────────────────────────
+  authLayout = $page({
+    path: "/auth",
+    lazy: () => import("./components/auth/AuthLayout.tsx"),
+  });
+
+  login = $page({
+    parent: this.authLayout,
+    path: "/login",
+    name: "login",
+    head: { title: "Sign in" },
+    lazy: () => import("./components/auth/Login.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  register = $page({
+    parent: this.authLayout,
+    path: "/register",
+    name: "register",
+    head: { title: "Sign up" },
+    lazy: () => import("./components/auth/Register.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  resetPassword = $page({
+    parent: this.authLayout,
+    path: "/reset-password",
+    head: { title: "Reset password" },
+    lazy: () => import("./components/auth/ResetPassword.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  verifyEmail = $page({
+    parent: this.authLayout,
+    path: "/verify-email",
+    head: { title: "Verify email" },
+    lazy: () => import("./components/auth/VerifyEmail.tsx"),
+  });
+
+  // ── /admin — gated by 'admin:ui' permission, declared in RealmProvider.
+  // Children inherit the gate via the parent chain.
+  adminLayout = $page({
+    path: "/admin",
+    use: [$secure({ permissions: ["admin:ui"] })],
+    lazy: () => import("./components/admin/AdminLayout.tsx"),
+  });
+
+  adminUsers = $page({
+    parent: this.adminLayout,
+    path: "/users",
+    head: { title: "Users" },
+    lazy: () => import("./components/admin/Users.tsx"),
+  });
+
+  adminSessions = $page({
+    parent: this.adminLayout,
+    path: "/sessions",
+    head: { title: "Sessions" },
+    lazy: () => import("./components/admin/Sessions.tsx"),
+  });
+
+  notFound = $page({ path: "/*", component: NotFound });
+}
+`;

package/src/cli/core/templates/webIndexTs.ts

@@ -1,9 +1,31 @@
 export interface WebIndexTsOptions {
   appName?: string;
+  /**
+   * SaaS bundle: auth pages need `useAuth()` (ReactAuth) which lives in the
+   * `alepha.react.auth` module. Importing it here registers ReactAuth in the
+   * container so the auth-* registry components can inject it.
+   */
+  saas?: boolean;
 }
 
 export const webIndexTs = (options: WebIndexTsOptions = {}) => {
-  const { appName = "app" } = options;
+  const { appName = "app", saas = false } = options;
+
+  if (saas) {
+    return `
+import { $module } from "alepha";
+import { AlephaReactAuth } from "alepha/react/auth";
+import { AlephaReactI18n } from "alepha/react/i18n";
+import { AppRouter } from "./AppRouter.ts";
+
+export const WebModule = $module({
+  name: "${appName}.web",
+  services: [AppRouter],
+  imports: [AlephaReactAuth, AlephaReactI18n],
+});
+`.trim();
+  }
+
   return `
 import { $module } from "alepha";
 import { AppRouter } from "./AppRouter.ts";

package/src/cli/platform/__tests__/SecretsCommand.spec.ts

@@ -252,8 +252,10 @@ describe("SecretsCommand", () => {
 
       const output = writes.join("");
       expect(output).toContain("env:");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: GitHub Actions `${{ ... }}` syntax in plain string
       expect(output).toContain("API_KEY: ${{ secrets.API_KEY }}");
       expect(output).toContain(
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: GitHub Actions `${{ ... }}` syntax in plain string
         "GITHUB_CLIENT_ID: ${{ secrets.APP_GITHUB_CLIENT_ID }}",
       );
     });

package/src/command/providers/CliProvider.ts

@@ -555,7 +555,7 @@ export class CliProvider {
     const parsed = this.parseFlags(argv, flagDefs);
 
     // Remove the mode flag from parsed result (it's handled separately)
-    delete parsed.__mode__;
+    parsed.__mode__ = undefined;
 
     // apply manually defaults for optional properties that have defaults
     for (const [key, value] of Object.entries(schema.properties)) {

package/src/core/interfaces/Service.ts

@@ -8,7 +8,9 @@ export type Service<T extends object = any> =
   | AbstractClass<T>
   | RunFunction<T>;
 
-export type RunFunction<T extends object = any> = (...args: any[]) => T | void;
+export type RunFunction<T extends object = any> = (
+  ...args: any[]
+) => T | undefined;
 
 export type InstantiableClass<T extends object = any> = new (
   ...args: any[]

package/src/core/providers/TypeProvider.ts

@@ -447,7 +447,7 @@ export class TypeProvider {
   /**
    * Create a schema that maps all properties of an object schema to nullable.
    */
-  public nullify = <T extends TSchema>(schema: T, options?: TObjectOptions) =>
+  public nullify = (schema: TSchema, options?: TObjectOptions): TSchema =>
     Type.Mapped(
       Type.Identifier("K"),
       Type.KeyOf(schema),

package/src/logger/services/Logger.ts

@@ -146,7 +146,7 @@ export class Logger implements LoggerInterface {
     }
 
     let _data: object | Error | undefined;
-    if (typeof data === "object" && !!data) {
+    if (typeof data === "object" && data) {
       _data = data;
     } else if (typeof message === "object" && message) {
       _data = message;

package/src/mcp/__tests__/$resource.spec.ts

@@ -364,7 +364,7 @@ describe("$resource primitive", () => {
         uri: "protected://resource",
         handler: async ({ context }) => {
           const authHeader = context?.headers?.authorization;
-          if (!authHeader || !authHeader.toString().startsWith("Bearer ")) {
+          if (!authHeader?.toString().startsWith("Bearer ")) {
             throw new Error("Unauthorized");
           }
           return { text: "Secret content" };

package/src/mcp/__tests__/$tool.spec.ts

@@ -379,7 +379,7 @@ describe("$tool primitive", () => {
         },
         handler: async ({ context }) => {
           const authHeader = context?.headers?.authorization;
-          if (!authHeader || !authHeader.toString().startsWith("Bearer ")) {
+          if (!authHeader?.toString().startsWith("Bearer ")) {
             throw new Error("Unauthorized");
           }
           return "Access granted";

package/src/mcp/__tests__/McpServerProvider.spec.ts

@@ -751,7 +751,7 @@ describe("McpServerProvider", () => {
           schema: { result: t.text() },
           handler: async ({ context }) => {
             const auth = context?.headers?.authorization;
-            if (!auth || !auth.toString().startsWith("Bearer ")) {
+            if (!auth?.toString().startsWith("Bearer ")) {
               throw new Error("Unauthorized");
             }
             return "Access granted";

package/src/orm/__tests__/$repository-tests.ts

@@ -1014,6 +1014,7 @@ export const testTransactionThrowsWhenUnsupported = async (alepha: Alepha) => {
         original,
       );
     } else {
+      // biome-ignore lint/performance/noDelete: setting to undefined fails because the prototype has a getter
       delete provider.supportsTransactions;
     }
   }

package/src/orm/__tests__/orm-next-tests.ts

@@ -1,8 +1,8 @@
-import { type Alepha, AlephaError, t } from "alepha";
+import { type Alepha, t } from "alepha";
 import { sql } from "drizzle-orm";
 import { expect } from "vitest";
 import { PG_GENERATED } from "../core/constants/PG_SYMBOLS.ts";
-import { $entity, $repository, $view, db, pgAttr } from "../core/index.ts";
+import { $entity, $repository, db, pgAttr } from "../core/index.ts";
 
 // ============================================================================
 // Shared entity definitions
@@ -425,68 +425,3 @@ export const testQueryCacheCustomKey = async (alepha: Alepha) => {
   );
   expect(cached).toHaveLength(1);
 };
-
-// ============================================================================
-// Feature 8: Database Views
-// ============================================================================
-
-export const testViewReadOnly = async (alepha: Alepha) => {
-  // Create the underlying table
-  const itemEntity = $entity({
-    name: "view_items",
-    schema: t.object({
-      id: db.primaryKey(),
-      name: t.text(),
-      price: t.number(),
-    }),
-  });
-
-  // Create a view
-  const itemView = $view({
-    name: "view_items_summary",
-    schema: t.object({
-      id: t.integer(),
-      name: t.text(),
-      price: t.number(),
-    }),
-    query: sql`SELECT id, name, price FROM view_items`,
-  });
-
-  class App {
-    items = $repository(itemEntity);
-    summary = $repository(itemView);
-  }
-
-  const app = alepha.inject(App);
-  await alepha.start();
-
-  // Verify the repository detects it's a view
-  expect(app.summary.isReadOnly).toBe(true);
-  expect(app.items.isReadOnly).toBe(false);
-
-  // Write operations should throw on views
-  await expect(
-    app.summary.create({ id: 1, name: "test", price: 10 } as any),
-  ).rejects.toThrow(AlephaError);
-};
-
-export const testViewRefreshThrowsForNonMaterialized = async (
-  alepha: Alepha,
-) => {
-  const view = $view({
-    name: "non_mat_view",
-    schema: t.object({
-      id: t.integer(),
-    }),
-    query: sql`SELECT 1 as id`,
-  });
-
-  class App {
-    repo = $repository(view);
-  }
-
-  const app = alepha.inject(App);
-  await alepha.start();
-
-  await expect(app.repo.refresh()).rejects.toThrow(AlephaError);
-};

package/src/orm/__tests__/orm-next.spec.ts

@@ -14,8 +14,6 @@ import {
   testPartialIndex,
   testQueryCache,
   testQueryCacheCustomKey,
-  testViewReadOnly,
-  testViewRefreshThrowsForNonMaterialized,
 } from "./orm-next-tests.ts";
 
 const sqlite = () =>
@@ -119,22 +117,3 @@ describe("query caching", () => {
     await testQueryCacheCustomKey(postgres());
   });
 });
-
-// =============================================================================
-// Feature 8: Database Views
-// =============================================================================
-
-describe("database views", () => {
-  it("should block writes on view repositories (sqlite)", async () => {
-    await testViewReadOnly(sqlite());
-  });
-  it("should block writes on view repositories (postgres)", async () => {
-    await testViewReadOnly(postgres());
-  });
-  it("should throw on refresh for non-materialized view (sqlite)", async () => {
-    await testViewRefreshThrowsForNonMaterialized(sqlite());
-  });
-  it("should throw on refresh for non-materialized view (postgres)", async () => {
-    await testViewRefreshThrowsForNonMaterialized(postgres());
-  });
-});

package/src/orm/core/index.shared.ts

@@ -12,13 +12,11 @@ export * from "./errors/DbEntityNotFoundError.ts";
 export * from "./errors/DbForeignKeyError.ts";
 export * from "./errors/DbNotNullError.ts";
 export * from "./errors/DbTableNotFoundError.ts";
-export * from "./helpers/parseQueryString.ts";
 export * from "./helpers/pgAttr.ts";
 export * from "./interfaces/AggregateQuery.ts";
 export * from "./interfaces/FilterOperators.ts";
 export * from "./interfaces/PgQuery.ts";
 export * from "./interfaces/PgQueryWhere.ts";
 export * from "./primitives/$entity.ts";
-export * from "./primitives/$view.ts";
 export * from "./providers/DatabaseTypeProvider.ts";
 export * from "./schemas/legacyIdSchema.ts";

package/src/orm/core/index.ts

@@ -4,7 +4,6 @@ import type { PgTransaction } from "drizzle-orm/pg-core";
 import { DbMigrationMode } from "./modes/DbMigrationMode.ts";
 import { $entity } from "./primitives/$entity.ts";
 import { $sequence } from "./primitives/$sequence.ts";
-import { $view } from "./primitives/$view.ts";
 import { DrizzleKitProvider } from "./providers/DrizzleKitProvider.ts";
 import { BunSqliteProvider } from "./providers/drivers/BunSqliteProvider.ts";
 import { CloudflareD1Provider } from "./providers/drivers/CloudflareD1Provider.ts";
@@ -102,7 +101,7 @@ export const SqliteProvider = NodeSqliteProvider;
 
 export const AlephaOrm = $module({
   name: "alepha.orm",
-  primitives: [$sequence, $entity, $view],
+  primitives: [$sequence, $entity],
   imports: [AlephaDateTime],
   services: [
     SqliteModelBuilder,

package/src/orm/core/primitives/$repository.ts

@@ -2,17 +2,14 @@ import { $context, $inject, type TObject } from "alepha";
 import { RepositoryProvider } from "../providers/RepositoryProvider.ts";
 import type { Repository } from "../services/Repository.ts";
 import type { EntityPrimitive } from "./$entity.ts";
-import type { ViewPrimitive } from "./$view.ts";
 
 /**
- * Get the repository for the given entity or view.
+ * Get the repository for the given entity.
  */
 export const $repository = <T extends TObject>(
-  entity: EntityPrimitive<T> | ViewPrimitive<T>,
+  entity: EntityPrimitive<T>,
 ): Repository<T> => {
   const { alepha } = $context();
   const repositoryProvider = alepha.inject(RepositoryProvider);
-  return $inject(
-    repositoryProvider.createClassRepository(entity as EntityPrimitive<T>),
-  );
+  return $inject(repositoryProvider.createClassRepository(entity));
 };

package/src/orm/core/providers/drivers/DatabaseProvider.ts

@@ -22,7 +22,6 @@ import type {
   SchemaToTableConfig,
 } from "../../primitives/$entity.ts";
 import type { SequencePrimitive } from "../../primitives/$sequence.ts";
-import type { ViewPrimitive } from "../../primitives/$view.ts";
 import { databaseEnvSchema } from "../../schemas/databaseEnvSchema.ts";
 import type { ModelBuilder } from "../../services/ModelBuilder.ts";
 import { DrizzleKitProvider } from "../DrizzleKitProvider.ts";
@@ -156,10 +155,6 @@ export abstract class DatabaseProvider {
     this.builder.buildTable(entity, this);
   }
 
-  public registerView(view: ViewPrimitive) {
-    this.builder.buildView(view, this);
-  }
-
   public registerSequence(sequence: SequencePrimitive) {
     this.sequencePrimitives.push(sequence);
     this.builder.buildSequence(sequence, this);

package/src/orm/core/providers/drivers/NodeSqliteProvider.ts

@@ -1,5 +1,4 @@
 import { mkdir } from "node:fs/promises";
-import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import type { DatabaseSync } from "node:sqlite";
 import {
@@ -12,7 +11,11 @@ import {
   type Static,
   t,
 } from "alepha";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import { BetterSQLiteSession } from "drizzle-orm/better-sqlite3/session";
 import type { PgDatabase } from "drizzle-orm/pg-core";
+import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core/db";
+import { SQLiteSyncDialect } from "drizzle-orm/sqlite-core/dialect";
 import { databaseEnvSchema } from "../../schemas/databaseEnvSchema.ts";
 import { SqliteModelBuilder } from "../../services/SqliteModelBuilder.ts";
 import { DatabaseProvider, type SQLLike } from "./DatabaseProvider.ts";
@@ -162,7 +165,7 @@ export class NodeSqliteProvider extends DatabaseProvider {
   protected readonly onStart = $hook({
     on: "start",
     handler: async () => {
-      const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+      const { DatabaseSync } = await import("node:sqlite");
 
       const filepath = this.url.replace("sqlite://", "").replace("sqlite:", "");
 
@@ -323,13 +326,6 @@ export class NodeSqliteProvider extends DatabaseProvider {
   protected initDrizzle(): void {
     this.shimDatabaseSync();
 
-    const require = createRequire(import.meta.url);
-    const {
-      BetterSQLiteSession,
-    } = require("drizzle-orm/better-sqlite3/session");
-    const { SQLiteSyncDialect } = require("drizzle-orm/sqlite-core/dialect");
-    const { BaseSQLiteDatabase } = require("drizzle-orm/sqlite-core/db");
-
     const dialect = new SQLiteSyncDialect();
     const session = new BetterSQLiteSession(this.sqlite, dialect, undefined, {
       logger: {
@@ -339,14 +335,16 @@ export class NodeSqliteProvider extends DatabaseProvider {
       },
     });
 
-    this.drizzleDb = new BaseSQLiteDatabase("sync", dialect, session);
+    this.drizzleDb = new BaseSQLiteDatabase(
+      "sync",
+      dialect,
+      session,
+      undefined,
+    );
     this.log.debug("Using node:sqlite with sync driver");
   }
 
   protected async executeMigrations(migrationsFolder: string): Promise<void> {
-    const { migrate } = createRequire(import.meta.url)(
-      "drizzle-orm/better-sqlite3/migrator",
-    );
     migrate(this.drizzleDb, { migrationsFolder });
   }
 }