alepha 0.20.1 → 0.20.3

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

@@ -1,30 +1,38 @@
 export interface ApiIndexTsOptions {
   appName?: string;
-  auth?: boolean;
+  /**
+   * Include `AlephaApiUsers` (realms, sessions, registration, identities,
+   * password reset, email verification, admin endpoints) plus the local
+   * `RealmProvider` that declares `$realm({ ... })`.
+   */
+  saas?: boolean;
 }
 
 export const apiIndexTs = (options: ApiIndexTsOptions = {}) => {
-  const { appName = "app", auth = false } = options;
+  const { appName = "app", saas = false } = options;
 
-  const imports: string[] = ['import { $module } from "alepha";'];
-  const services: string[] = [];
+  if (saas) {
+    return `
+import { $module } from "alepha";
+import { AlephaApiUsers } from "alepha/api/users";
+import { HelloController } from "./controllers/HelloController.ts";
+import { RealmProvider } from "./providers/RealmProvider.ts";
 
-  if (auth) {
-    imports.push('import { AppSecurity } from "./AppSecurity.ts";');
-    services.push("AppSecurity");
+export const ApiModule = $module({
+  name: "${appName}.api",
+  services: [HelloController, RealmProvider],
+  imports: [AlephaApiUsers],
+});
+`.trim();
   }
 
-  imports.push(
-    'import { HelloController } from "./controllers/HelloController.ts";',
-  );
-  services.push("HelloController");
-
   return `
-${imports.join("\n")}
+import { $module } from "alepha";
+import { HelloController } from "./controllers/HelloController.ts";
 
 export const ApiModule = $module({
   name: "${appName}.api",
-  services: [${services.join(", ")}],
+  services: [HelloController],
 });
 `.trim();
 };

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

@@ -0,0 +1,39 @@
+/**
+ * `components.json` is the shadcn CLI's project config — it tells
+ * `shadcn add` where to drop primitives, which tailwind tokens to use,
+ * which icon library to wire up, and which custom registries to resolve.
+ *
+ * Aliases follow shadcn's defaults (`@/components`, `@/lib/utils`) so the
+ * CLI honors them across `init` + `add` calls. Alepha app code lives at
+ * `src/web/` (Home, AppRouter, …) and the shadcn primitives live at
+ * `src/components/` — kept separate to make the registry components
+ * trivially upgradable via `shadcn add --overwrite`.
+ *
+ * The `registries` block pre-wires the public Alepha registry — consumers
+ * can immediately run e.g. `shadcn add @alepha/auth-login`.
+ */
+export const componentsJsonTs = () =>
+  `{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/main.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide",
+  "registries": {
+    "@alepha": "https://alepha.dev/r/{name}.json"
+  }
+}
+`;

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

@@ -1,38 +1,4 @@
-export const mainCss = (opts: { ui?: boolean; tailwind?: boolean } = {}) => {
-  if (opts.ui) {
-    return `/**
- * Alepha UI - Based on Mantine component library
- * Mantine Docs: https://mantine.dev
- * Mantine LLM context: https://mantine.dev/llms.txt
- *
- * Switch theme index: alepha.set(alephaThemeAtom, { index: 1 })
- *
- * Custom themes (in src/web/index.ts):
- *
- *   import { alephaThemeListAtom } from "@alepha/ui";
- *
- *   export const WebModule = $module({
- *     name: "app.web",
- *     services: [AppRouter],
- *     register(alepha) {
- *       alepha.register(AppRouter);
- *       alepha.set(alephaThemeListAtom, [{
- *         name: "My Theme",
- *         description: "Custom theme",
- *         primaryColor: "blue",
- *         defaultColorScheme: "dark",
- *         // ...MantineThemeOverride options
- *       }]);
- *     },
- *   });
- *
- * Alternatives (remove the import below):
- * - Tailwind CSS: https://tailwindcss.com/docs/installation/using-vite
- * - Raw CSS: Write your own styles
- */
-@import "@alepha/ui/styles";`;
-  }
-
+export const mainCss = (opts: { tailwind?: boolean } = {}) => {
   if (opts.tailwind) {
     return `@import "tailwindcss";
 
@@ -44,8 +10,8 @@ export const mainCss = (opts: { ui?: boolean; tailwind?: boolean } = {}) => {
  * Global styles for your application.
  *
  * Options:
- * - @alepha/ui: Use \`alepha init --ui\` to add Mantine-based components
  * - Tailwind CSS: Use \`alepha init --tailwind\` to add Tailwind CSS
+ * - shadcn/ui: Use \`alepha init --shadcn\` to add shadcn/ui setup
  * - Raw CSS: Write your own styles below
  */
 

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

@@ -0,0 +1,77 @@
+/**
+ * SaaS admin layout — full AppShell on /admin with a sidebar, breadcrumbs,
+ * a Sonner toaster, and a confirm provider. The page list grows with
+ * whatever `admin-*` registry components the user adds.
+ *
+ * All UI primitives come from `src/components/*` where `shadcn add` drops
+ * them; alepha app code lives in `src/web/*` and references them via the
+ * `@/components/*` alias.
+ */
+export const saasAdminLayoutTsx = () =>
+  `import { AppShell } from "@/components/app-shell";
+import { Toaster } from "@/components/ui/sonner";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { ConfirmProvider } from "@/components/use-confirm";
+import { NestedView, useRouterState } from "alepha/react/router";
+import { ShieldCheck, Users } from "lucide-react";
+
+const NAV = [
+  {
+    label: "Identity",
+    items: [
+      { href: "/admin/users", label: "Users", icon: Users },
+      { href: "/admin/sessions", label: "Sessions", icon: ShieldCheck },
+    ],
+  },
+] as const;
+
+const findCrumbs = (pathname: string): { label: string; href?: string }[] => {
+  for (const group of NAV) {
+    const match = group.items.find((it) => it.href === pathname);
+    if (match) return [{ label: group.label }, { label: match.label }];
+  }
+  return [];
+};
+
+const AdminLayout = () => {
+  const state = useRouterState();
+  const crumbs = findCrumbs(state.url.pathname);
+
+  return (
+    <TooltipProvider>
+      <ConfirmProvider>
+        <AppShell
+          brand={
+            <a
+              href="/admin"
+              className="flex items-center gap-2 px-2 py-2 font-semibold group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0"
+            >
+              <span className="bg-primary text-primary-foreground flex size-7 shrink-0 items-center justify-center rounded">
+                α
+              </span>
+              <span className="truncate group-data-[collapsible=icon]:hidden">
+                Admin
+              </span>
+            </a>
+          }
+          nav={NAV.map((group) => ({
+            label: group.label,
+            items: group.items.map((it) => ({
+              href: it.href,
+              label: it.label,
+              icon: it.icon,
+              active: it.href === state.url.pathname,
+            })),
+          }))}
+          breadcrumbs={crumbs.length ? crumbs : undefined}
+        >
+          <NestedView />
+        </AppShell>
+        <Toaster />
+      </ConfirmProvider>
+    </TooltipProvider>
+  );
+};
+
+export default AdminLayout;
+`;

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/vitestConfigTs.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal Vitest config for a freshly scaffolded Alepha project.
+ *
+ * Defines `test.root` explicitly so Vitest doesn't walk up the directory
+ * tree and inherit a parent monorepo config (which can pull in unrelated
+ * setup files, database connections, etc.).
+ */
+export const vitestConfigTs = () =>
+  `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    root: ".",
+    globals: true,
+  },
+});
+`;

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

@@ -1,97 +1,26 @@
-export const webAppRouterTs = (options: {
+export interface WebAppRouterOptions {
   api?: boolean;
-  ui?: boolean;
-  auth?: boolean;
-  admin?: boolean;
-}) => {
-  const imports: string[] = [];
-  const classMembers: string[] = [];
-
-  // UI import and setup
-  if (options.ui) {
-    imports.push('import { $ui } from "@alepha/ui";');
-  }
+  saas?: boolean;
+}
 
-  // Auth import
-  if (options.auth) {
-    imports.push('import { $uiAuth } from "@alepha/ui/auth";');
-  }
-
-  // Admin imports
-  if (options.admin) {
-    imports.push('import { $uiAdmin } from "@alepha/ui/admin";');
-    imports.push('import { AdminUserRouter } from "@alepha/ui/admin-users";');
-    imports.push(
-      'import { AdminSessionRouter } from "@alepha/ui/admin-sessions";',
-    );
-    imports.push('import { $inject } from "alepha";');
-    imports.push(
-      'import { IconLayoutDashboard, IconUsers } from "@tabler/icons-react";',
-    );
+export const webAppRouterTs = (options: WebAppRouterOptions) => {
+  if (options.saas) {
+    return saasAppRouterTs();
   }
+  return basicAppRouterTs(options);
+};
 
-  // Page import
-  imports.push('import { $page } from "alepha/react/router";');
+const basicAppRouterTs = (options: WebAppRouterOptions) => {
+  const imports: string[] = ['import { $page } from "alepha/react/router";'];
+  const classMembers: string[] = [];
 
-  // API imports (only if api flag is set)
   if (options.api) {
     imports.push('import { $client } from "alepha/server/links";');
     imports.push(
       'import type { HelloController } from "../api/controllers/HelloController.ts";',
     );
     classMembers.push("  api = $client<HelloController>();");
-  }
 
-  // UI layout setup
-  if (options.ui) {
-    classMembers.push("  ui = $ui();");
-
-    if (options.auth) {
-      classMembers.push("  uiAuth = $uiAuth();");
-    }
-
-    if (options.admin) {
-      classMembers.push(`  // ── Admin Dashboard ─────────────────────────────
-  // Defined first so it can be referenced by the admin panel below.
-  // \`$uiAdmin\` auto-parents listed pages under the admin layout.
-  adminDashboard = $page({
-    path: "/",
-    label: "Dashboard",
-    icon: IconLayoutDashboard,
-    lazy: () => import("./components/AdminDashboard.tsx"),
-  });
-
-  // ── Admin Domain Routers ──────────────────────────
-  protected users = $inject(AdminUserRouter);
-  protected sessions = $inject(AdminSessionRouter);
-
-  // ── Admin Panel ─────────────────────────────────
-  admin = $uiAdmin({
-    pages: [
-      this.adminDashboard,
-      this.users.adminUsers,
-      this.users.adminUserLayout,
-      this.sessions.adminSessions,
-    ],
-    sidebarItems: [
-      this.adminDashboard,
-      {
-        label: "Identity",
-        icon: IconUsers,
-        children: [this.users.adminUsers, this.sessions.adminSessions],
-      },
-    ],
-  });`);
-    }
-
-    classMembers.push(`  layout = $page({
-      parent: this.ui.root,
-      children: () => [this.home],
-    });`);
-  }
-
-  // Home page - with or without loader
-  if (options.api) {
     classMembers.push(`  home = $page({
     path: "/",
     lazy: () => import("./components/Home.tsx"),
@@ -110,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";