alepha 0.19.0 → 0.19.2

package/src/cli/core/providers/ViteDevServerProvider.ts

@@ -1,10 +1,8 @@
-import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { __alephaRef, $inject, type Alepha, AlephaError } from "alepha";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
 import type { Plugin, ViteDevServer } from "vite";
-import { cliAssets } from "../assets.ts";
 import { ViteUtils } from "../services/ViteUtils.ts";
 import type { AppEntry } from "./AppEntryProvider.ts";
 
@@ -19,17 +17,20 @@ export interface DevServerOptions {
    */
   entry: AppEntry;
 
-  /**
-   * Disable devtools.
-   */
-  noDevtools?: boolean;
-
   /**
    * Disable Vite React plugin.
    */
   noViteReactPlugin?: boolean;
 }
 
+/**
+ * Hook called after Alepha is loaded during dev server init/reload.
+ */
+export type OnAlephaLoadedHook = (
+  alepha: Alepha,
+  server: ViteDevServer,
+) => Promise<void>;
+
 /**
  * Vite development server with Alepha integration.
  *
@@ -60,6 +61,33 @@ export class ViteDevServerProvider {
   protected isReloading = false;
   protected needsBrowserReload = false;
   protected currentReloadPromise: Promise<void> | null = null;
+  protected extraVitePlugins: Plugin[] = [];
+  protected alephaLoadedHooks: OnAlephaLoadedHook[] = [];
+
+  /**
+   * Register an additional Vite plugin.
+   * Must be called before init().
+   */
+  public addVitePlugin(plugin: Plugin): void {
+    this.extraVitePlugins.push(plugin);
+  }
+
+  /**
+   * Register a hook called after Alepha is loaded/reloaded.
+   */
+  public onAlephaLoaded(hook: OnAlephaLoadedHook): void {
+    this.alephaLoadedHooks.push(hook);
+  }
+
+  /**
+   * Trigger a full Alepha reload programmatically.
+   */
+  public reload(): void {
+    this.hasError = true;
+    this.needsBrowserReload = true;
+    this.changedFiles.add("__manual_reload__");
+    this.scheduleReload();
+  }
 
   /**
    * Initialize the dev server and load Alepha.
@@ -87,10 +115,10 @@ export class ViteDevServerProvider {
       await this.alepha?.start();
       await this.listen();
 
-      console.log("");
-      this.server.printUrls();
-      this.server.bindCLIShortcuts({ print: true });
-      console.log("");
+      const port = this.server.config.server.port ?? 5173;
+      const url = `http://localhost:${port}/`;
+      const log = this.alepha?.log ?? this.log;
+      log.info(`Listening on ${this.colors.set("CYAN", url)}`);
     } catch (err) {
       this.hasError = true;
       this.currentError = err instanceof Error ? err : new Error(String(err));
@@ -125,6 +153,7 @@ export class ViteDevServerProvider {
     if (viteReact && !this.options.noViteReactPlugin) plugins.push(viteReact());
     plugins.push(this.viteUtils.createTsconfigPathsPlugin());
     plugins.push(this.viteUtils.createSsrPreloadPlugin());
+    plugins.push(...this.extraVitePlugins);
     plugins.push(this.createAlephaPlugin());
 
     // DEFAULT PORT
@@ -143,6 +172,14 @@ export class ViteDevServerProvider {
       root: this.options.root,
       plugins,
       appType: "custom",
+      resolve: {
+        dedupe: [
+          "react",
+          "react-dom",
+          "react/jsx-runtime",
+          "react/jsx-dev-runtime",
+        ],
+      },
       server: {
         port,
       },
@@ -204,37 +241,6 @@ export class ViteDevServerProvider {
       name: "alepha",
 
       configureServer: (server) => {
-        // Devtools live reload via SSE
-        if (!this.options.noDevtools) {
-          server.middlewares.use(async (req, res, next) => {
-            const url = req.url || "/";
-
-            // Serve devtools HTML with reload script injected
-            if (
-              !url.startsWith("/__devtools") ||
-              !req.headers.accept?.includes("text/html")
-            ) {
-              return next();
-            }
-
-            const indexPath = join(cliAssets.devtools, "index.html");
-
-            try {
-              let html = await readFile(indexPath, "utf-8");
-              html = html.replace(
-                "<head>",
-                `<head><script type="module" src="/@vite/client"></script>`,
-              );
-
-              res.writeHead(200, { "content-type": "text/html" });
-              res.end(html);
-            } catch (err) {
-              this.log.error("Failed to serve devtools UI", err);
-              next();
-            }
-          });
-        }
-
         // Re-send error overlay when a new browser connects (e.g. page refresh during error state)
         server.hot.on("connection", () => {
           if (this.currentError) {
@@ -467,9 +473,8 @@ export class ViteDevServerProvider {
     // Expose Vite server to Alepha for Logger SSR stack trace fixing
     alepha.store.set("alepha.vite.server" as any, this.server);
 
-    if (!this.options.noDevtools) {
-      const mod = await this.server.ssrLoadModule("alepha/devtools");
-      alepha.with(mod.AlephaDevtools);
+    for (const hook of this.alephaLoadedHooks) {
+      await hook(alepha, this.server);
     }
 
     this.alepha = alepha;
@@ -698,11 +703,13 @@ export class ViteDevServerProvider {
   /**
    * Log a formatted error with stack trace.
    */
-  protected logError(title: string, _err: unknown): void {
+  protected logError(title: string, err: unknown): void {
     const c = this.colors;
 
     console.log();
     console.log(c.set("RED", `  ✗ ${title}`));
+    this.logErrorWithCause(err);
+    console.log();
     console.log(c.set("GREY_DARK", "    Waiting for file changes to retry..."));
     console.log();
   }

package/src/cli/core/services/PackageManagerUtils.ts

@@ -398,9 +398,14 @@ export class PackageManagerUtils {
       alepha: `^${version}`,
     };
 
-    const devDependencies: Record<string, string> = {
-      "drizzle-kit": alephaDeps["drizzle-kit"],
-    };
+    const devDependencies: Record<string, string> = {};
+
+    // Only include drizzle-kit when the project uses a database.
+    // React-only projects (--react without --api/--saas) don't need it.
+    const isReactOnly = modes.react && !modes.ui;
+    if (!isReactOnly) {
+      devDependencies["drizzle-kit"] = alephaDeps["drizzle-kit"];
+    }
 
     // Add biome/vitest only if not a workspace package (workspace root has them)
     if (!modes.isPackage) {

package/src/cli/core/services/ProjectScaffolder.ts

@@ -20,6 +20,7 @@ import { mainCss } from "../templates/mainCss.ts";
 import { mainServerTs } from "../templates/mainServerTs.ts";
 import { tsconfigJson } from "../templates/tsconfigJson.ts";
 import { viteConfigTs } from "../templates/viteConfigTs.ts";
+import { webAdminDashboardTsx } from "../templates/webAdminDashboardTsx.ts";
 import { webAppRouterTs } from "../templates/webAppRouterTs.ts";
 import { webHomeComponentTsx } from "../templates/webHomeComponentTsx.ts";
 import { webIndexTs } from "../templates/webIndexTs.ts";
@@ -356,6 +357,14 @@ export class ProjectScaffolder {
       webHomeComponentTsx({ api: opts.api }),
       opts.force,
     );
+    if (opts.admin) {
+      await this.ensureFile(
+        root,
+        "src/web/components/AdminDashboard.tsx",
+        webAdminDashboardTsx(),
+        opts.force,
+      );
+    }
     await this.ensureFile(
       root,
       "src/main.browser.ts",
@@ -407,8 +416,7 @@ export class ProjectScaffolder {
       api?: boolean;
       react?: boolean;
       ui?: boolean;
-      auth?: boolean;
-      admin?: boolean;
+      saas?: boolean;
       tailwind?: boolean;
       test?: boolean;
       force?: boolean;
@@ -420,11 +428,8 @@ export class ProjectScaffolder {
       await this.fs.mkdir(root, { force: true });
     }
 
-    // Flag cascading: --admin → --auth → --ui → --react, --api
-    if (flags.admin) {
-      flags.auth = true;
-    }
-    if (flags.auth) {
+    // Flag cascading: --saas → --api + --ui → --react
+    if (flags.saas) {
       flags.api = true;
       flags.ui = true;
     }
@@ -437,12 +442,7 @@ export class ProjectScaffolder {
 
     // When codegen flags are set, target directory must be empty (unless --force)
     const hasCodegenFlags =
-      flags.admin ||
-      flags.auth ||
-      flags.api ||
-      flags.ui ||
-      flags.react ||
-      flags.tailwind;
+      flags.saas || flags.api || flags.ui || flags.react || flags.tailwind;
     if (hasCodegenFlags && !flags.force) {
       const files = await this.fs.ls(root);
       // Allow a directory that only has package.json (common for monorepo packages)
@@ -466,8 +466,8 @@ export class ProjectScaffolder {
 
     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;
+    // Get git email for admin auto-promotion (if saas enabled)
+    const adminEmail = flags.saas ? await this.utils.getGitEmail() : undefined;
 
     const force = !!flags.force;
 
@@ -479,7 +479,7 @@ export class ProjectScaffolder {
           packageJson: { ...flags, isPackage: workspace.isPackage },
           // Skip workspace-level configs if they exist at workspace root
           tsconfigJson: !workspace.config.tsconfigJson,
-          biomeJson: !workspace.config.biomeJson,
+          biomeJson: true,
           editorconfig: !workspace.config.editorconfig,
           agentMd: agentType ? { type: agentType } : false,
         });
@@ -495,7 +495,7 @@ export class ProjectScaffolder {
         });
         if (flags.api) {
           await this.ensureApiProject(root, {
-            auth: !!flags.auth,
+            auth: !!flags.saas,
             adminEmail,
             force,
           });
@@ -504,8 +504,8 @@ export class ProjectScaffolder {
           await this.ensureWebProject(root, {
             api: !!flags.api,
             ui: !!flags.ui,
-            auth: !!flags.auth,
-            admin: !!flags.admin,
+            auth: !!flags.saas,
+            admin: !!flags.saas,
             tailwind: !!flags.tailwind,
             force,
           });
@@ -547,7 +547,7 @@ export class ProjectScaffolder {
 
     await run(`${pmName} run lint`, {
       alias: "running linter",
-      root: installRoot,
+      root,
     });
 
     // Initialize git repository if not in a workspace package

package/src/cli/core/tasks/BuildClientTask.ts

@@ -85,6 +85,14 @@ export class BuildClientTask extends BuildTask {
       define: {
         "process.env.NODE_ENV": '"production"',
       },
+      resolve: {
+        dedupe: [
+          "react",
+          "react-dom",
+          "react/jsx-runtime",
+          "react/jsx-dev-runtime",
+        ],
+      },
       publicDir: "public",
       build: {
         outDir: opts.dist,

package/src/cli/core/tasks/BuildServerTask.ts

@@ -46,6 +46,7 @@ export class BuildServerTask extends BuildTask {
       name: "build server",
       handler: async () => {
         await this.buildServer({
+          root: ctx.root,
           entry: ctx.entry.server,
           distDir,
           clientDir: clientBuilt ? publicDir : undefined,
@@ -64,6 +65,7 @@ export class BuildServerTask extends BuildTask {
   }
 
   protected async buildServer(opts: {
+    root: string;
     entry: string;
     distDir: string;
     clientDir?: string;
@@ -107,6 +109,14 @@ export class BuildServerTask extends BuildTask {
       define: {
         "process.env.NODE_ENV": '"production"',
       },
+      resolve: {
+        dedupe: [
+          "react",
+          "react-dom",
+          "react/jsx-runtime",
+          "react/jsx-dev-runtime",
+        ],
+      },
       publicDir: false,
       ssr: {
         noExternal: true,
@@ -158,7 +168,11 @@ export class BuildServerTask extends BuildTask {
 
     await this.generateExternals(opts.distDir, externals);
 
-    const entryFile = this.extractEntryFromBundle(opts.entry, result);
+    const entryFile = this.extractEntryFromBundle(
+      opts.root,
+      opts.entry,
+      result,
+    );
 
     let manifest = "";
     let manifestData:
@@ -296,15 +310,14 @@ export class BuildServerTask extends BuildTask {
   }
 
   protected extractEntryFromBundle(
+    root: string,
     entry: string,
     result:
       | vite.Rollup.RollupOutput
       | vite.Rollup.RollupOutput[]
       | vite.Rollup.RollupWatcher,
   ): string {
-    const entryFilePath = isAbsolute(entry)
-      ? entry
-      : join(process.cwd(), entry);
+    const entryFilePath = isAbsolute(entry) ? entry : join(root, entry);
 
     const normalizedEntryPath = entryFilePath.replace(/\\/g, "/");
 

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

@@ -17,12 +17,6 @@ export default defineConfig({
   //   runtime: "node",
   // },
   //
-  // platform: {
-  //   environments: {
-  //     production: { adapter: "cloudflare" },
-  //   },
-  // },
-  //
   // env: {
   //   VITE_BUILD_DATE: new Date().toISOString(),
   //   VITE_VERSION: pkg.version,

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

@@ -0,0 +1,17 @@
+export const webAdminDashboardTsx = () => {
+  return `import { Flex, Text } from "@alepha/ui";
+
+const AdminDashboard = () => {
+  return (
+    <Flex direction="column" align="center" justify="center" mih="60vh" gap="md">
+      <Text size="xl" fw={600}>
+        Admin Panel
+      </Text>
+      <Text c="dimmed">Welcome to the admin panel.</Text>
+    </Flex>
+  );
+};
+
+export default AdminDashboard;
+`;
+};

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

@@ -17,9 +17,30 @@ export const webAppRouterTs = (options: {
     imports.push('import { $uiAuth } from "@alepha/ui/auth";');
   }
 
-  // Admin import
+  // 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 { AdminAuditRouter } from "@alepha/ui/admin-audits";');
+    imports.push('import { AdminFileRouter } from "@alepha/ui/admin-files";');
+    imports.push(
+      'import { AdminParameterRouter } from "@alepha/ui/admin-parameters";',
+    );
+    imports.push('import { AdminJobRouter } from "@alepha/ui/admin-jobs";');
+    imports.push('import { AdminApiKeyRouter } from "@alepha/ui/admin-keys";');
+    imports.push(
+      'import { AdminNotificationRouter } from "@alepha/ui/admin-notifications";',
+    );
+    imports.push(
+      'import { AdminBillingRouter } from "@alepha/ui/admin-billing";',
+    );
+    imports.push('import { $inject } from "alepha";');
+    imports.push(
+      'import { IconLayoutDashboard, IconLockPassword, IconCreditCard } from "@tabler/icons-react";',
+    );
   }
 
   // Page import
@@ -43,7 +64,69 @@ export const webAppRouterTs = (options: {
     }
 
     if (options.admin) {
-      classMembers.push("  uiAdmin = $uiAdmin();");
+      classMembers.push(`  // ── Admin Domain Routers ──────────────────────────
+  protected users = $inject(AdminUserRouter);
+  protected sessions = $inject(AdminSessionRouter);
+  protected audits = $inject(AdminAuditRouter);
+  protected files = $inject(AdminFileRouter);
+  protected parameters = $inject(AdminParameterRouter);
+  protected jobs = $inject(AdminJobRouter);
+  protected apiKeys = $inject(AdminApiKeyRouter);
+  protected notifications = $inject(AdminNotificationRouter);
+  protected billing = $inject(AdminBillingRouter);
+
+  // ── Admin Panel ─────────────────────────────────
+  admin = $uiAdmin({
+    pages: [
+      this.users.adminUsers,
+      this.sessions.adminSessions,
+      this.audits.adminAudits,
+      this.files.adminFiles,
+      this.parameters.adminParameters,
+      this.jobs.adminJobs,
+      this.apiKeys.adminApiKeys,
+      this.notifications.adminNotifications,
+      this.billing.adminBilling,
+    ],
+    sidebarItems: [
+      {
+        label: "Security",
+        children: [
+          { label: "Identity", icon: IconLockPassword, children: [
+            this.users.adminUsers,
+            this.sessions.adminSessions,
+            this.apiKeys.adminApiKeys,
+          ]},
+          this.audits.adminAudits,
+        ],
+      },
+      {
+        label: "System",
+        children: [
+          this.files.adminFiles,
+          this.jobs.adminJobs,
+          this.notifications.adminNotifications,
+          this.parameters.adminParameters,
+        ],
+      },
+      {
+        label: "Commerce",
+        icon: IconCreditCard,
+        children: [
+          this.billing.adminBilling,
+        ],
+      },
+    ],
+  });
+
+  // ── Admin Dashboard ─────────────────────────────
+  adminDashboard = $page({
+    parent: this.admin.adminLayout,
+    path: "/",
+    label: "Dashboard",
+    icon: IconLayoutDashboard,
+    lazy: () => import("./components/AdminDashboard.tsx"),
+  });`);
     }
 
     classMembers.push(`  layout = $page({

package/src/cli/devtools/atoms/devtoolsOptions.ts

@@ -0,0 +1,26 @@
+import { $atom, type Static, t } from "alepha";
+
+/**
+ * Devtools configuration atom.
+ *
+ * Filled from the `devtools` section of `alepha.config.ts`.
+ */
+export const devtoolsOptions = $atom({
+  name: "alepha.cli.devtools.options",
+  description: "Devtools plugin configuration",
+  schema: t.optional(
+    t.object({
+      /**
+       * Hide the floating devtools button in the browser.
+       *
+       * The devtools UI is still accessible at `/__devtools/`.
+       */
+      hideButton: t.optional(t.boolean({ default: false })),
+    }),
+  ),
+});
+
+/**
+ * Type for devtools options.
+ */
+export type DevtoolsOptions = Static<typeof devtoolsOptions.schema>;