alepha 0.20.2 → 0.20.3

package/dist/cli/core/index.js

@@ -37,7 +37,20 @@ const buildOptions = $atom({
 	name: "alepha.cli.build.options",
 	description: "Build configuration options",
 	schema: t.object({
+		/**
+		* Generate build stats report.
+		*
+		* - `true` - Generate a static HTML report
+		* - `"json"` - Generate a JSON report
+		*/
 		stats: t.optional(t.union([t.boolean(), t.enum(["json"])])),
+		/**
+		* Deployment target for the build output.
+		*
+		* - `docker` - Generate Dockerfile for containerized deployment
+		* - `vercel` - Generate Vercel deployment configuration (forces node runtime)
+		* - `cloudflare` - Generate Cloudflare Workers configuration (forces workerd runtime)
+		*/
 		target: t.optional(t.enum([
 			"bare",
 			"docker",
@@ -45,15 +58,45 @@ const buildOptions = $atom({
 			"cloudflare",
 			"static"
 		])),
+		/**
+		* JavaScript runtime for the build output.
+		*
+		* - `node` - Node.js runtime (default)
+		* - `bun` - Bun runtime (uses bun export conditions)
+		* - `workerd` - Cloudflare Workers runtime (auto-set with cloudflare target)
+		*
+		* Note: Some targets force a specific runtime:
+		* - `cloudflare` always uses `workerd`
+		* - `vercel` always uses `node`
+		*/
 		runtime: t.optional(t.enum([
 			"node",
 			"bun",
 			"workerd"
 		])),
+		/**
+		* Output directory configuration.
+		*/
 		output: t.optional(t.object({
+			/**
+			* Root dist directory.
+			*
+			* @default "dist"
+			*/
 			dist: t.optional(t.string({ default: "dist" })),
+			/**
+			* Public/client subdirectory.
+			*
+			* @default "public"
+			*/
 			public: t.optional(t.string({ default: "public" }))
 		})),
+		/**
+		* Vercel-specific deployment configuration.
+		*
+		* Note: Set `target: "vercel"` to enable Vercel deployment.
+		* This object is only for additional configuration.
+		*/
 		vercel: t.optional(t.object({
 			projectName: t.optional(t.string()),
 			orgId: t.optional(t.string()),
@@ -63,31 +106,143 @@ const buildOptions = $atom({
 				schedule: t.string()
 			}))) }))
 		})),
+		/**
+		* Cloudflare-specific deployment configuration.
+		*
+		* Note: Set `target: "cloudflare"` to enable Cloudflare deployment.
+		* This object is only for additional configuration.
+		*/
 		cloudflare: t.optional(t.object({ config: t.optional(t.json()) })),
+		/**
+		* Docker-specific deployment configuration.
+		*
+		* Note: Set `target: "docker"` to enable Docker deployment.
+		* This object is only for additional configuration.
+		*/
 		docker: t.optional(t.object({
+			/**
+			* Base image for the Dockerfile (FROM instruction).
+			*
+			* @default "node:24-alpine" for node runtime
+			* @default "oven/bun:alpine" for bun runtime
+			*/
 			from: t.optional(t.string()),
+			/**
+			* Command to run in the Docker container.
+			*
+			* @default "node" for node runtime
+			* @default "bun" for bun runtime
+			*/
 			command: t.optional(t.string()),
+			/**
+			* Docker build options (used when --image flag is passed).
+			*/
 			image: t.optional(t.object({
+				/**
+				* Default image tag (name without version).
+				*
+				* Used when --image is provided without a full override:
+				* - `--image` → `tag:latest`
+				* - `--image=1.3.4` → `tag:1.3.4`
+				* - `--image=other/img:v1` → `other/img:v1` (full override)
+				*
+				* @example "myproject/myapp"
+				* @example "ghcr.io/myorg/myapp"
+				*/
 				tag: t.string(),
+				/**
+				* Additional arguments to pass to `docker build`.
+				*
+				* @example '--platform linux/amd64 --no-cache'
+				*/
 				args: t.optional(t.string()),
+				/**
+				* Auto-add OCI standard labels (revision, created, version).
+				*
+				* Adds:
+				* - org.opencontainers.image.revision (git commit SHA)
+				* - org.opencontainers.image.created (build timestamp)
+				* - org.opencontainers.image.version (from image tag)
+				*/
 				oci: t.optional(t.boolean())
 			}))
 		})),
-		static: t.optional(t.object({ domain: t.optional(t.string()) })),
+		/**
+		* Static site deployment configuration.
+		*
+		* Note: Set `target: "static"` to enable static site generation.
+		*/
+		static: t.optional(t.object({ 
+		/**
+		* Surge domain for deployment.
+		*
+		* If set, a CNAME file is written to dist/public/.
+		* If not set, a domain is auto-generated from package.json name.
+		*
+		* @example "my-app.surge.sh"
+		* @example "my-custom-domain.com"
+		*/
+domain: t.optional(t.string()) })),
+		/**
+		* PWA (Progressive Web App) configuration.
+		*
+		* Generates a web app manifest and enables installability.
+		* Requires a client-side bundle (React).
+		*/
 		pwa: t.optional(t.object({
+			/**
+			* Full application name displayed on the splash screen
+			* and in the OS app switcher.
+			*/
 			name: t.string(),
+			/**
+			* Short name displayed on the home screen icon.
+			* Falls back to `name` if omitted.
+			*/
 			shortName: t.optional(t.string()),
+			/**
+			* Theme color used for the browser toolbar and OS chrome.
+			*
+			* @default "#ffffff"
+			*/
 			themeColor: t.optional(t.string()),
+			/**
+			* Background color for the splash screen.
+			*
+			* @default "#ffffff"
+			*/
 			backgroundColor: t.optional(t.string()),
+			/**
+			* Display mode for the installed PWA.
+			*
+			* - `standalone` - Looks like a native app (default)
+			* - `fullscreen` - Uses entire screen (games, immersive)
+			* - `minimal-ui` - Like standalone with minimal browser UI
+			* - `browser` - Standard browser tab
+			*
+			* @default "standalone"
+			*/
 			display: t.optional(t.enum([
 				"standalone",
 				"fullscreen",
 				"minimal-ui",
 				"browser"
 			])),
+			/**
+			* Enable offline support via service worker.
+			*
+			* TODO: Not yet implemented.
+			*/
 			offline: t.optional(t.boolean())
 		})),
-		sitemap: t.optional(t.object({ hostname: t.string() }))
+		/**
+		* Sitemap generation configuration.
+		*/
+		sitemap: t.optional(t.object({ 
+		/**
+		* Base URL for sitemap entries.
+		*/
+hostname: t.string() }))
 	}),
 	default: {}
 });
@@ -102,7 +257,11 @@ const buildOptions = $atom({
 const devOptions = $atom({
 	name: "alepha.cli.dev.options",
 	description: "Dev configuration options",
-	schema: t.object({ noViteReactPlugin: t.optional(t.boolean({ default: false })) }),
+	schema: t.object({ 
+	/**
+	* Disable Vite React plugin.
+	*/
+noViteReactPlugin: t.optional(t.boolean({ default: false })) }),
 	default: {}
 });
 //#endregion
@@ -598,7 +757,7 @@ var AlephaCliUtils = class {
 };
 //#endregion
 //#region ../../package.json
-var version$1 = "0.20.2";
+var version$1 = "0.20.3";
 //#endregion
 //#region ../../src/cli/core/alephaPackageJson.ts
 const alephaPackageJson = {
@@ -627,18 +786,19 @@ const alephaPackageJson = {
 		"drizzle-orm": "^0.45.2",
 		"postgres": "^3.4.9",
 		"tsx": "^4.21.0",
-		"typebox": "^1.1.23",
-		"typescript": "^6.0.2",
-		"vite-bundle-analyzer": "^1.3.7",
+		"typebox": "^1.1.34",
+		"typescript": "^6.0.3",
+		"vite-bundle-analyzer": "^1.3.8",
 		"ws": "^8.20.0"
 	},
 	devDependencies: {
-		"@biomejs/biome": "^2.4.12",
-		"@electric-sql/pglite": "^0.4.4",
+		"@biomejs/biome": "^2.4.13",
+		"@electric-sql/pglite": "^0.4.5",
 		"@faker-js/faker": "^10.4.0",
+		"@tailwindcss/vite": "^4.2.4",
 		"@testing-library/dom": "^10.4.1",
 		"@testing-library/react": "^16.3.2",
-		"@types/bun": "^1.3.12",
+		"@types/bun": "^1.3.13",
 		"@types/node": "^25.6.0",
 		"@types/nodemailer": "^8.0.0",
 		"@types/react": "^19.2.14",
@@ -646,17 +806,19 @@ const alephaPackageJson = {
 		"@types/ws": "^8.18.1",
 		"cron-schedule": "^6.0.0",
 		"drizzle-kit": "^0.31.10",
-		"jose": "^6.2.2",
-		"jsdom": "^29.0.2",
-		"nodemailer": "^8.0.5",
-		"openid-client": "^6.8.3",
+		"jose": "^6.2.3",
+		"jsdom": "^29.1.0",
+		"nodemailer": "^8.0.7",
+		"openid-client": "^6.8.4",
 		"prom-client": "^15.1.3",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5",
-		"swagger-ui-dist": "^5.32.4",
-		"tsdown": "^0.21.8",
-		"vite": "^8.0.8",
-		"vitest": "^4.1.4"
+		"shadcn": "^4.6.0",
+		"swagger-ui-dist": "^5.32.5",
+		"tailwindcss": "^4.2.4",
+		"tsdown": "^0.21.10",
+		"vite": "^8.0.10",
+		"vitest": "^4.1.5"
 	},
 	peerDependencies: {
 		"react": "^19",
@@ -1285,14 +1447,14 @@ var PackageManagerUtils = class {
 			"yarn.lock"
 		]);
 		await this.editPackageJson(root, (pkg) => {
-			delete pkg.packageManager;
+			pkg.packageManager = void 0;
 			return pkg;
 		});
 	}
 	async removePnpm(root) {
 		await this.removeFiles(root, ["pnpm-lock.yaml", "pnpm-workspace.yaml"]);
 		await this.editPackageJson(root, (pkg) => {
-			delete pkg.packageManager;
+			pkg.packageManager = void 0;
 			return pkg;
 		});
 	}
@@ -1342,7 +1504,7 @@ var PackageManagerUtils = class {
 		const alephaDeps = alephaPackageJson.devDependencies;
 		const dependencies = { alepha: `^${version}` };
 		const devDependencies = { vite: alephaDeps.vite };
-		if (!modes.react) devDependencies["drizzle-kit"] = alephaDeps["drizzle-kit"];
+		if (!modes.react || modes.saas) devDependencies["drizzle-kit"] = alephaDeps["drizzle-kit"];
 		if (!modes.isPackage) {
 			devDependencies["@biomejs/biome"] = alephaDeps["@biomejs/biome"];
 			if (modes.test) devDependencies.vitest = alephaDeps.vitest;
@@ -1356,9 +1518,10 @@ var PackageManagerUtils = class {
 		};
 		if (modes.test) scripts.test = "vitest run";
 		if (modes.tailwind) {
-			devDependencies.tailwindcss = "^4.2.0";
-			devDependencies["@tailwindcss/vite"] = "^4.2.0";
+			devDependencies.tailwindcss = alephaDeps.tailwindcss;
+			devDependencies["@tailwindcss/vite"] = alephaDeps["@tailwindcss/vite"];
 		}
+		if (modes.shadcn) devDependencies.shadcn = alephaDeps.shadcn;
 		if (modes.react) {
 			dependencies.react = alephaDeps.react;
 			dependencies["react-dom"] = alephaDeps["react-dom"];
@@ -1472,7 +1635,19 @@ export type HelloResponse = Static<typeof helloResponseSchema>;
 //#endregion
 //#region ../../src/cli/core/templates/apiIndexTs.ts
 const apiIndexTs = (options = {}) => {
-	const { appName = "app" } = options;
+	const { appName = "app", saas = false } = options;
+	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";
+
+export const ApiModule = $module({
+  name: "${appName}.api",
+  services: [HelloController, RealmProvider],
+  imports: [AlephaApiUsers],
+});
+`.trim();
 	return `
 import { $module } from "alepha";
 import { HelloController } from "./controllers/HelloController.ts";
@@ -1519,6 +1694,46 @@ const biomeJson = () => `
 }
 `.trim();
 //#endregion
+//#region ../../src/cli/core/templates/componentsJsonTs.ts
+/**
+* `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`.
+*/
+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"
+  }
+}
+`;
+//#endregion
 //#region ../../src/cli/core/templates/dummySpecTs.ts
 const dummySpecTs = () => `
 import { test, expect } from "vitest";
@@ -1660,6 +1875,7 @@ const mainCss = (opts = {}) => {
  *
  * Options:
  * - 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
  */
 
@@ -1690,6 +1906,225 @@ run(alepha);
 `.trim();
 };
 //#endregion
+//#region ../../src/cli/core/templates/saasAdminLayoutTsx.ts
+/**
+* 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.
+*/
+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;
+`;
+//#endregion
+//#region ../../src/cli/core/templates/saasAdminPagesTsx.ts
+/**
+* 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.
+*/
+const saasAdminUsersTsx = () => `import { AdminUsers } from "@/components/admin/admin-users";
+
+const AdminUsersPage = () => {
+  return <AdminUsers />;
+};
+
+export default AdminUsersPage;
+`;
+const saasAdminSessionsTsx = () => `import { AdminSessions } from "@/components/admin/admin-sessions";
+
+const AdminSessionsPage = () => {
+  return <AdminSessions />;
+};
+
+export default AdminSessionsPage;
+`;
+//#endregion
+//#region ../../src/cli/core/templates/saasAuthLayoutTsx.ts
+/**
+* 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.
+*/
+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;
+`;
+//#endregion
+//#region ../../src/cli/core/templates/saasAuthPagesTsx.ts
+/**
+* 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).
+*/
+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;
+`;
+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;
+`;
+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;
+`;
+const saasAuthVerifyEmailTsx = () => `import { AuthVerifyEmail } from "@/components/auth/auth-verify-email";
+
+const AuthVerifyEmailPage = () => {
+  return <AuthVerifyEmail />;
+};
+
+export default AuthVerifyEmailPage;
+`;
+//#endregion
+//#region ../../src/cli/core/templates/saasRealmProviderTs.ts
+/**
+* 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.
+*/
+const saasRealmProviderTs = (options = {}) => {
+	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,
+    },
+  });
+}
+`;
+};
+//#endregion
 //#region ../../src/cli/core/templates/tsconfigJson.ts
 const tsconfigJson = () => `
 {
@@ -1733,6 +2168,10 @@ export default defineConfig({
 //#endregion
 //#region ../../src/cli/core/templates/webAppRouterTs.ts
 const webAppRouterTs = (options) => {
+	if (options.saas) return saasAppRouterTs();
+	return basicAppRouterTs(options);
+};
+const basicAppRouterTs = (options) => {
 	const imports = ["import { $page } from \"alepha/react/router\";"];
 	const classMembers = [];
 	if (options.api) {
@@ -1754,6 +2193,95 @@ 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 });
+}
+`;
 //#endregion
 //#region ../../src/cli/core/templates/webHomeComponentTsx.ts
 const webHomeComponentTsx = (options = {}) => {
@@ -1782,7 +2310,19 @@ export default Home;
 //#endregion
 //#region ../../src/cli/core/templates/webIndexTs.ts
 const webIndexTs = (options = {}) => {
-	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";
@@ -1808,6 +2348,7 @@ var ProjectScaffolder = class {
 	log = $logger();
 	colors = $inject(ConsoleColorProvider);
 	fs = $inject(FileSystemProvider);
+	shell = $inject(ShellProvider);
 	pm = $inject(PackageManagerUtils);
 	utils = $inject(AlephaCliUtils);
 	/**
@@ -1829,7 +2370,10 @@ var ProjectScaffolder = class {
 		const force = opts.force ?? false;
 		const checkWorkspace = opts.checkWorkspace ?? false;
 		if (opts.packageJson) tasks.push(this.pm.ensurePackageJson(root, typeof opts.packageJson === "boolean" ? {} : opts.packageJson).then(() => {}));
-		if (opts.tsconfigJson) tasks.push(this.ensureTsConfig(root, { force }));
+		if (opts.tsconfigJson) tasks.push(this.ensureTsConfig(root, {
+			force,
+			localOnly: opts.tsconfigJson === "local"
+		}));
 		if (opts.biomeJson) tasks.push(this.ensureBiomeConfig(root, {
 			force,
 			checkWorkspace
@@ -1845,7 +2389,8 @@ var ProjectScaffolder = class {
 		await Promise.all(tasks);
 	}
 	async ensureTsConfig(root, opts = {}) {
-		if (!opts.force && await this.existsInParents(root, "tsconfig.json")) return;
+		const exists = opts.localOnly ? await this.fs.exists(this.fs.join(root, "tsconfig.json")) : await this.existsInParents(root, "tsconfig.json");
+		if (!opts.force && exists) return;
 		await this.fs.writeFile(this.fs.join(root, "tsconfig.json"), tsconfigJson());
 	}
 	async ensureBiomeConfig(root, opts = {}) {
@@ -1904,9 +2449,32 @@ var ProjectScaffolder = class {
 		const appName = this.getAppName(root);
 		await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), { recursive: true });
 		await this.fs.mkdir(this.fs.join(root, "src/api/schemas"), { recursive: true });
-		await this.ensureFile(root, "src/api/index.ts", apiIndexTs({ appName }), opts.force);
+		await this.ensureFile(root, "src/api/index.ts", apiIndexTs({
+			appName,
+			saas: opts.saas
+		}), opts.force);
 		await this.ensureFile(root, "src/api/controllers/HelloController.ts", apiHelloControllerTs({ appName }), opts.force);
 		await this.ensureFile(root, "src/api/schemas/helloResponseSchema.ts", apiHelloResponseSchemaTs(), opts.force);
+		if (opts.saas) {
+			await this.fs.mkdir(this.fs.join(root, "src/api/providers"), { recursive: true });
+			const adminEmail = await this.detectGitEmail();
+			await this.ensureFile(root, "src/api/providers/RealmProvider.ts", saasRealmProviderTs({ adminEmail }), opts.force);
+		}
+	}
+	/**
+	* Best-effort lookup for the developer's git email (used as the seeded
+	* `adminEmails` entry in the SaaS realm). Returns undefined if git isn't
+	* available or if `user.email` isn't configured — the template falls back
+	* to `admin@example.com` in that case.
+	*/
+	async detectGitEmail() {
+		try {
+			const email = (await this.shell.run("git config --get user.email", { capture: true }) ?? "").trim();
+			if (!email || !email.includes("@")) return void 0;
+			return email;
+		} catch {
+			return;
+		}
 	}
 	/**
 	* Ensure web/React project structure exists.
@@ -1919,14 +2487,35 @@ var ProjectScaffolder = class {
 	async ensureWebProject(root, opts = {}) {
 		const appName = this.getAppName(root);
 		await this.fs.mkdir(this.fs.join(root, "src/web/components"), { recursive: true });
+		if (opts.saas) {
+			await this.fs.mkdir(this.fs.join(root, "src/web/components/auth"), { recursive: true });
+			await this.fs.mkdir(this.fs.join(root, "src/web/components/admin"), { recursive: true });
+		}
 		await this.fs.mkdir(this.fs.join(root, "public"), { recursive: true });
 		await this.ensureFile(root, "public/favicon.svg", logoSvg, opts.force);
 		await this.ensureFile(root, "src/main.css", mainCss({ tailwind: opts.tailwind }), opts.force);
 		if (opts.tailwind) await this.ensureFile(root, "vite.config.ts", viteConfigTs(), opts.force);
-		await this.ensureFile(root, "src/web/index.ts", webIndexTs({ appName }), opts.force);
-		await this.ensureFile(root, "src/web/AppRouter.ts", webAppRouterTs({ api: opts.api }), opts.force);
+		if (opts.shadcn) await this.ensureFile(root, "components.json", componentsJsonTs(), opts.force);
+		await this.ensureFile(root, "src/web/index.ts", webIndexTs({
+			appName,
+			saas: opts.saas
+		}), opts.force);
+		await this.ensureFile(root, "src/web/AppRouter.ts", webAppRouterTs({
+			api: opts.api,
+			saas: opts.saas
+		}), opts.force);
 		await this.ensureFile(root, "src/web/components/Home.tsx", webHomeComponentTsx({ api: opts.api }), opts.force);
 		await this.ensureFile(root, "src/main.browser.ts", mainBrowserTs(), opts.force);
+		if (opts.saas) {
+			await this.ensureFile(root, "src/web/components/auth/AuthLayout.tsx", saasAuthLayoutTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/auth/Login.tsx", saasAuthLoginTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/auth/Register.tsx", saasAuthRegisterTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/auth/ResetPassword.tsx", saasAuthResetPasswordTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/auth/VerifyEmail.tsx", saasAuthVerifyEmailTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/admin/AdminLayout.tsx", saasAdminLayoutTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/admin/Users.tsx", saasAdminUsersTsx(), opts.force);
+			await this.ensureFile(root, "src/web/components/admin/Sessions.tsx", saasAdminSessionsTsx(), opts.force);
+		}
 	}
 	/**
 	* Ensure test directory exists with a dummy test file + a self-contained
@@ -1953,8 +2542,17 @@ var ProjectScaffolder = class {
 			root = this.fs.join(root, args);
 			await this.fs.mkdir(root, { force: true });
 		}
+		const shadcnPreset = typeof flags.saas === "string" && flags.saas || typeof flags.shadcn === "string" && flags.shadcn || "b0";
+		const f = flags;
+		f.shadcn = !!flags.shadcn;
+		f.saas = !!flags.saas;
+		if (f.saas) {
+			f.shadcn = true;
+			f.api = true;
+		}
+		if (f.shadcn) f.tailwind = true;
 		if (flags.tailwind) flags.react = true;
-		if ((flags.api || flags.react || flags.tailwind) && !flags.force) {
+		if ((flags.api || flags.react || flags.tailwind || flags.shadcn || flags.saas) && !flags.force) {
 			if ((await this.fs.ls(root)).filter((f) => f !== "package.json").length > 0) throw new AlephaError(`Target directory is not empty (${root}). Use --force to overwrite existing files.`);
 		}
 		const workspace = await this.pm.getWorkspaceContext(root);
@@ -1968,10 +2566,10 @@ var ProjectScaffolder = class {
 				await this.ensureConfig(root, {
 					force,
 					packageJson: {
-						...flags,
+						...f,
 						isPackage: workspace.isPackage
 					},
-					tsconfigJson: !workspace.config.tsconfigJson,
+					tsconfigJson: f.shadcn ? "local" : !workspace.config.tsconfigJson,
 					biomeJson: true,
 					editorconfig: !workspace.config.editorconfig,
 					agentMd: agentType ? { type: agentType } : false
@@ -1982,10 +2580,15 @@ var ProjectScaffolder = class {
 					react: !!flags.react && !isExpo,
 					force
 				});
-				if (flags.api) await this.ensureApiProject(root, { force });
+				if (flags.api) await this.ensureApiProject(root, {
+					saas: !!flags.saas,
+					force
+				});
 				if (flags.react && !isExpo) await this.ensureWebProject(root, {
 					api: !!flags.api,
 					tailwind: !!flags.tailwind,
+					shadcn: !!flags.shadcn,
+					saas: !!flags.saas,
 					force
 				});
 			}
@@ -2003,10 +2606,26 @@ var ProjectScaffolder = class {
 			root: installRoot
 		});
 		if (flags.test) await this.ensureTestDir(root);
-		await run(`${pmName} run lint`, {
-			alias: "running linter",
+		const exec = pmExecPrefix(pmName);
+		if (flags.shadcn) {
+			await run(`${exec} shadcn init --no-monorepo --base radix -t vite --yes --force --reinstall --preset ${escapeShellArg(shadcnPreset)}`, {
+				alias: `running shadcn init (preset ${shadcnPreset})`,
+				root
+			});
+			await this.fs.writeFile(this.fs.join(root, "components.json"), componentsJsonTs());
+		}
+		if (flags.saas) await run(`${exec} shadcn add @alepha/saas --yes --overwrite`, {
+			alias: "adding alepha saas registry bundle",
 			root
 		});
+		try {
+			await run(`${pmName} run lint`, {
+				alias: "running linter",
+				root
+			});
+		} catch (err) {
+			this.log.warn("Linter reported issues during init — continuing. Run `lint` again later to inspect.", { error: err instanceof Error ? err.message : String(err) });
+		}
 		if (!workspace.isPackage) {
 			if (await this.ensureGitRepo(root, { force })) await run("git add .", {
 				alias: "staging generated files",
@@ -2045,6 +2664,30 @@ var ProjectScaffolder = class {
 		}
 	}
 };
+/**
+* Map a package manager name to the command that runs a project-local binary.
+*
+* - npm:  `npx`
+* - yarn: `yarn` (yarn auto-resolves binary names; `yarn shadcn ...` works)
+* - pnpm: `pnpm exec`
+* - bun:  `bunx`
+*
+* Used to invoke `shadcn init` / `shadcn add` regardless of the user's PM —
+* `npm shadcn ...` is invalid (it tries to run a script named `shadcn`).
+*/
+/** Quote a value so it survives shell parsing. */
+const escapeShellArg = (value) => {
+	if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, "'\\''")}'`;
+};
+const pmExecPrefix = (pmName) => {
+	switch (pmName) {
+		case "npm": return "npx";
+		case "pnpm": return "pnpm exec";
+		case "bun": return "bunx";
+		default: return "yarn";
+	}
+};
 //#endregion
 //#region ../../src/cli/core/tasks/BuildTask.ts
 /**
@@ -2456,7 +3099,7 @@ var BuildCompressTask = class extends BuildTask {
 *
 * Creates:
 * - Dockerfile with configurable base image
-* - Copies drizzle migrations if they exist
+* - Copies migrations directory if it exists
 * - Builds Docker image when `--image` flag is provided
 */
 var BuildDockerTask = class extends BuildTask {
@@ -2471,15 +3114,15 @@ var BuildDockerTask = class extends BuildTask {
 		await ctx.run({
 			name: "generate deploy config (docker)",
 			handler: async () => {
-				await this.copyDrizzleMigrations(ctx.root, distDir);
+				await this.copyMigrations(ctx.root, distDir);
 				await this.writeDockerfile(ctx.root, distDir, dockerFrom, dockerCommand);
 			}
 		});
 		if (ctx.flags?.image) await this.buildDockerImage(ctx, distDir);
 	}
-	async copyDrizzleMigrations(root, distDir) {
-		const drizzleDir = this.fs.join(root, "drizzle");
-		if (await this.fs.exists(drizzleDir)) await this.fs.cp(drizzleDir, this.fs.join(root, distDir, "drizzle"));
+	async copyMigrations(root, distDir) {
+		const migrationsDir = this.fs.join(root, "migrations");
+		if (await this.fs.exists(migrationsDir)) await this.fs.cp(migrationsDir, this.fs.join(root, distDir, "migrations"));
 	}
 	async writeDockerfile(root, distDir, image, command) {
 		const dockerfile = `# This file was automatically generated. DO NOT MODIFY.
@@ -2740,6 +3383,10 @@ var BuildServerTask = class extends BuildTask {
 						chunkFileNames: "[hash].js",
 						assetFileNames: "[hash][extname]",
 						format: "esm",
+						codeSplitting: { groups: [{
+							name: "react",
+							test: /node_modules\/react(\/|-dom\/)/
+						}] },
 						minify: {
 							mangle: { keepNames: true },
 							compress: { keepNames: {
@@ -4280,7 +4927,12 @@ const DEFAULT_IGNORE = [
 */
 const changelogOptions = $atom({
 	name: "alepha.cli.changelog.options",
-	schema: t.object({ ignore: t.optional(t.array(t.string())) }),
+	schema: t.object({ 
+	/**
+	* Scopes to ignore (e.g., "project", "release", "chore").
+	* Commits like `feat(chore): ...` will be excluded from changelog.
+	*/
+ignore: t.optional(t.array(t.string())) }),
 	default: { ignore: DEFAULT_IGNORE }
 });
 //#endregion
@@ -4422,10 +5074,20 @@ var ChangelogCommand = class {
 		name: "changelog",
 		description: "Generate changelog from conventional commits (outputs to stdout)",
 		flags: t.object({
+			/**
+			* Show changes from this ref (tag, commit, branch).
+			* Defaults to the latest version tag.
+			* Example: --from=1.0.0
+			*/
 			from: t.optional(t.string({
 				aliases: ["f"],
 				description: "Starting ref (default: latest tag)"
 			})),
+			/**
+			* Show changes up to this ref (tag, commit, branch).
+			* Defaults to HEAD.
+			* Example: --to=main
+			*/
 			to: t.optional(t.string({
 				aliases: ["t"],
 				description: "Ending ref (default: HEAD)"
@@ -4588,6 +5250,8 @@ var InitCommand = class {
 				description: "Include React dependencies and web module (src/web/)"
 			})),
 			tailwind: t.optional(t.boolean({ description: "Include Tailwind CSS with Vite plugin. Implies --react" })),
+			shadcn: t.optional(t.union([t.boolean(), t.text()], { description: "Set up shadcn/ui (components.json, cn helper, theme tokens, alepha registry). Pass an optional preset id (default: b0). Implies --react and --tailwind" })),
+			saas: t.optional(t.union([t.boolean(), t.text()], { description: "Scaffold a SaaS starter: auth (login/register/reset/verify) + admin panel (/admin AppShell with users/sessions/api-keys/parameters/audits). Pass an optional preset id (default: b0). Implies --shadcn and --api" })),
 			test: t.optional(t.boolean({ description: "Include Vitest and create test directory" })),
 			force: t.optional(t.boolean({
 				aliases: ["f"],