alepha 0.13.0 → 0.13.2

package/src/cli/commands/CoreCommands.ts

@@ -57,15 +57,13 @@ export class CoreCommands {
       // }),
       // choose package manager
       yarn: t.optional(t.boolean({ description: "Use Yarn package manager" })),
+      pnpm: t.optional(t.boolean({ description: "Use pnpm package manager" })),
       // choose which dependencies to add
-      api: t.optional(
-        t.boolean({ description: "Include Alepha Server dependencies" }),
-      ),
       react: t.optional(
         t.boolean({ description: "Include Alepha React dependencies" }),
       ),
-      orm: t.optional(
-        t.boolean({ description: "Include Alepha ORM dependencies" }),
+      admin: t.optional(
+        t.boolean({ description: "Include Alepha admin panel dependencies" }),
       ),
     }),
     handler: async ({ run, flags, root }) => {
@@ -75,6 +73,8 @@ export class CoreCommands {
           await this.utils.ensureConfig(root, {
             tsconfigJson: true,
             packageJson: flags,
+            biomeJson: true,
+            viteConfigTs: true,
             indexHtml: !!flags.react,
           });
         },
@@ -86,6 +86,7 @@ export class CoreCommands {
 
       if (flags.yarn || guessedPm === "yarn") {
         await this.utils.ensureYarn(root);
+        await run("yarn set version stable");
         await run("yarn install", {
           alias: "Installing dependencies with Yarn",
         });

package/src/cli/commands/DrizzleCommands.ts

@@ -1,9 +1,9 @@
 import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import { join } from "node:path";
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
+import type { DrizzleKitProvider, RepositoryProvider } from "alepha/orm";
 import { ProcessRunner } from "../services/ProcessRunner.ts";
 import { ProjectUtils } from "../services/ProjectUtils.ts";
 
@@ -25,7 +25,7 @@ export class DrizzleCommands {
    * Check if database migrations are up to date.
    */
   check = $command({
-    name: "db:migrate:check",
+    name: "db:check-migrations",
     description: "Check if database migration files are up to date",
     args: t.optional(
       t.text({
@@ -34,81 +34,89 @@ export class DrizzleCommands {
       }),
     ),
     flags: drizzleCommandFlags,
-    handler: async ({ args, flags, root }) => {
+    handler: async ({ args, root }) => {
       const rootDir = root;
       this.log.debug(`Using project root: ${rootDir}`);
+
       const { alepha } = await this.utils.loadAlephaFromServerEntryFile(
         rootDir,
         args,
       );
 
-      const models: any[] = [];
-      const repositories = alepha.descriptors("repository") as any[];
-      const kit = createRequire(import.meta.url)("drizzle-kit/api");
-      const migrationDir = join(rootDir, "migrations");
+      const repositoryProvider =
+        alepha.inject<RepositoryProvider>("RepositoryProvider");
+      const drizzleKitProvider =
+        alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
+      const accepted = new Set<string>([]);
 
-      const journalFile = await readFile(
-        `${migrationDir}/meta/_journal.json`,
-        "utf-8",
-      ).catch(() => null);
-
-      if (!journalFile) {
-        this.log.info(`No migration journal found.`);
-        return;
-      }
+      for (const primitive of repositoryProvider.getRepositories()) {
+        const provider = primitive.provider;
+        const providerName = provider.name;
+        if (accepted.has(providerName)) {
+          continue;
+        }
 
-      const journal = JSON.parse(journalFile);
+        accepted.add(providerName);
 
-      const lastMigration = journal.entries[journal.entries.length - 1];
+        const migrationDir = join(rootDir, "migrations", providerName);
 
-      const lastSnapshot = JSON.parse(
-        await readFile(
-          `${migrationDir}/meta/${String(lastMigration.idx).padStart(4, "0")}_snapshot.json`,
+        const journalFile = await readFile(
+          `${migrationDir}/meta/_journal.json`,
           "utf-8",
-        ),
-      );
+        ).catch(() => null);
 
-      for (const repository of repositories) {
-        if (!models.includes(repository.table)) {
-          models.push(repository.table);
+        if (!journalFile) {
+          this.log.info(`No migration journal found.`);
+          return;
         }
-      }
 
-      const now = kit.generateDrizzleJson(models, lastSnapshot.id);
+        const journal = JSON.parse(journalFile);
+        const lastMigration = journal.entries[journal.entries.length - 1];
+        const lastSnapshot = JSON.parse(
+          await readFile(
+            `${migrationDir}/meta/${String(lastMigration.idx).padStart(4, "0")}_snapshot.json`,
+            "utf-8",
+          ),
+        );
 
-      const migrationStatements = await new Promise<Array<any>>((resolve) => {
-        (async () => {
-          const timer = setTimeout(() => {
-            resolve([{ message: "Migration generation timed out." }]);
-          }, 5000);
-          const statements = await kit.generateMigration(lastSnapshot, now);
-          clearTimeout(timer);
-          resolve(statements);
-        })();
-      });
+        const models = drizzleKitProvider.getModels(provider);
+        const kit = drizzleKitProvider.importDrizzleKit();
+        const now = kit.generateDrizzleJson(models, lastSnapshot.id);
 
-      if (migrationStatements.length === 0) {
-        this.log.info("No changes detected.");
-        return;
-      }
+        const migrationStatements = await new Promise<Array<any>>((resolve) => {
+          (async () => {
+            const timer = setTimeout(() => {
+              resolve([{ message: "Migration generation timed out." }]);
+            }, 5000);
+            const statements = await kit.generateMigration(lastSnapshot, now);
+            clearTimeout(timer);
+            resolve(statements);
+          })();
+        });
 
-      this.log.info("");
-      this.log.info("Detected migration statements:");
-      this.log.info("");
-      for (const stmt of migrationStatements) {
-        this.log.info(stmt);
-      }
-      this.log.info("");
+        if (migrationStatements.length === 0) {
+          this.log.info("No changes detected.");
+          return;
+        }
 
-      this.log.info(
-        `At least ${migrationStatements.length} change(s) detected.`,
-      );
-      this.log.info(
-        "Please, run 'alepha db:generate' to update the migration files.",
-      );
-      this.log.info("");
+        this.log.info("");
+        this.log.info("Detected migration statements:");
+        this.log.info("");
+        for (const stmt of migrationStatements) {
+          this.log.info(stmt);
+        }
+        this.log.info("");
 
-      throw new AlephaError("Database migrations are not up to date.");
+        this.log.info(
+          `At least ${migrationStatements.length} change(s) detected.`,
+        );
+        this.log.info(
+          "Please, run 'alepha db:generate' to update the migration files.",
+        );
+        this.log.info("");
+
+        throw new AlephaError("Database migrations are not up to date.");
+      }
     },
   });
 
@@ -116,7 +124,7 @@ export class DrizzleCommands {
    * Generate database migration files
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions based on the current database schema.
    * - Writes these definitions to a temporary schema file. (node_modules/.db/entities.ts)
    * - Invokes Drizzle Kit's CLI to generate migration files based on the current schema.
@@ -159,7 +167,7 @@ export class DrizzleCommands {
    * Push database schema changes directly to the database
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's push command to apply schema changes directly.
    */
@@ -190,7 +198,7 @@ export class DrizzleCommands {
    * Apply pending database migrations
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's migrate command to apply pending migrations.
    */
@@ -221,7 +229,7 @@ export class DrizzleCommands {
    * Launch Drizzle Studio database browser
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's studio command to launch the web-based database browser.
    */

package/src/cli/commands/VerifyCommands.ts

@@ -35,8 +35,8 @@ export class VerifyCommands {
         await run("alepha test");
       }
 
-      if (await this.utils.hasDir(root, "migrations")) {
-        await run("alepha db:migrate:check");
+      if (await this.utils.exists(root, "migrations")) {
+        await run("alepha db:check-migrations");
       }
 
       await run("alepha build");

package/src/cli/commands/ViteCommands.ts

@@ -68,7 +68,12 @@ export class ViteCommands {
         await access(join(root, "index.html"));
       } catch {
         this.log.trace("No index.html found, running entry file with tsx");
-        await this.runner.exec(`tsx watch ${entry}`);
+        let cmd = "tsx --watch";
+        if (await this.utils.exists(root, ".env")) {
+          cmd += ` --env-file=./.env`;
+        }
+        cmd += ` ${entry}`;
+        await this.runner.exec(cmd);
         return;
       }
 

package/src/cli/services/ProjectUtils.ts

@@ -3,11 +3,13 @@ import { join } from "node:path";
 import { $inject, Alepha, AlephaError } from "alepha";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import type { RepositoryProvider } from "alepha/orm";
+import type { DrizzleKitProvider, RepositoryProvider } from "alepha/orm";
 import { boot } from "alepha/vite";
 import { tsImport } from "tsx/esm/api";
+import { appRouterTs } from "../assets/appRouterTs.ts";
 import { biomeJson } from "../assets/biomeJson.ts";
 import { indexHtml } from "../assets/indexHtml.ts";
+import { mainBrowserTs } from "../assets/mainBrowserTs.ts";
 import { tsconfigJson } from "../assets/tsconfigJson.ts";
 import { viteConfigTs } from "../assets/viteConfigTs.ts";
 import { version } from "../version.ts";
@@ -40,18 +42,16 @@ export class ProjectUtils {
    * @param root - The root directory of the project
    */
   public async ensureYarn(root: string): Promise<void> {
-    const yarnrcPath = join(root, ".yarnrc.yml");
-    try {
-      await access(yarnrcPath);
-    } catch {
-      await writeFile(yarnrcPath, "nodeLinker: node-modules");
-    }
+    await this.ensureFileExists(
+      root,
+      ".yarnrc.yml",
+      "nodeLinker: node-modules",
+      false,
+    );
 
     // remove lock files from other package managers
-    const npmLockPath = join(root, "package-lock.json");
-    const pnpmLockPath = join(root, "pnpm-lock.yaml");
-    await this.fs.rm(npmLockPath, { force: true });
-    await this.fs.rm(pnpmLockPath, { force: true });
+    await this.fs.rm(join(root, "package-lock.json"), { force: true });
+    await this.fs.rm(join(root, "pnpm-lock.yaml"), { force: true });
   }
 
   /**
@@ -74,8 +74,13 @@ export class ProjectUtils {
 
     if (modes.react) {
       dependencies["@alepha/react"] = `^${version}`;
-      dependencies.react = "19.1.0";
-      devDependencies["@types/react"] = "19.1.0";
+      dependencies.react = "^19.2.0";
+      dependencies["react-dom"] = "^19.2.0";
+      devDependencies["@types/react"] = "^19.2.0";
+    }
+
+    if (modes.admin) {
+      dependencies["@alepha/ui"] = `^${version}`;
     }
 
     return {
@@ -85,6 +90,7 @@ export class ProjectUtils {
       scripts: {
         dev: "alepha dev",
         build: "alepha build",
+        verify: "alepha verify",
       },
     };
   }
@@ -353,22 +359,6 @@ export class ProjectUtils {
     );
   }
 
-  /**
-   * Get DrizzleKitProvider from an Alepha instance.
-   *
-   * Searches the Alepha registry for the DrizzleKitProvider instance.
-   *
-   * @param alepha - The Alepha instance to search
-   * @returns The DrizzleKitProvider instance
-   */
-  public getKitFromAlepha(alepha: Alepha): any {
-    // biome-ignore lint/complexity/useLiteralKeys: private key
-    return alepha["registry"]
-      .values()
-      .find((it: any) => it.instance.constructor.name === "DrizzleKitProvider")
-      ?.instance;
-  }
-
   /**
    * Generate JavaScript code for Drizzle entities export.
    *
@@ -439,6 +429,16 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       },
     };
 
+    if (options.dialect === "sqlite") {
+      let url = options.providerUrl;
+      url = url.replace("sqlite://", "").replace("file://", "");
+      url = join(options.rootDir, url);
+
+      config.dbCredentials = {
+        url,
+      };
+    }
+
     if (options.providerName === "pglite") {
       config.driver = "pglite";
     }
@@ -452,6 +452,24 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     );
   }
 
+  public async loadEnvFile(root: string): Promise<void> {
+    const envPath = join(root, ".env");
+    try {
+      const envContent = await readFile(envPath, "utf8");
+      const lines = envContent.split("\n");
+      for (const line of lines) {
+        const [key, ...rest] = line.split("=");
+        if (key) {
+          const value = rest.join("=");
+          process.env[key.trim()] = value.trim();
+        }
+      }
+      this.log.debug(`Loaded environment variables from ${envPath}`);
+    } catch {
+      this.log.debug(`No .env file found at ${envPath}, skipping load.`);
+    }
+  }
+
   /**
    * Run a drizzle-kit command for all database providers in an Alepha instance.
    *
@@ -469,6 +487,9 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     logMessage: (providerName: string, dialect: string) => string;
   }): Promise<void> {
     const rootDir = options.root;
+
+    await this.loadEnvFile(rootDir);
+
     this.log.debug(`Using project root: ${rootDir}`);
 
     const { alepha, entry } = await this.loadAlephaFromServerEntryFile(
@@ -476,13 +497,14 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       options.args,
     );
 
-    const kit = this.getKitFromAlepha(alepha);
+    const drizzleKitProvider =
+      alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
     const repositoryProvider =
       alepha.inject<RepositoryProvider>("RepositoryProvider");
     const accepted = new Set<string>([]);
 
-    for (const descriptor of repositoryProvider.getRepositories()) {
-      const provider = descriptor.provider;
+    for (const primitive of repositoryProvider.getRepositories()) {
+      const provider = primitive.provider;
       const providerName = provider.name;
       const dialect = provider.dialect;
 
@@ -503,7 +525,7 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       this.log.info(options.logMessage(providerName, dialect));
 
       const drizzleConfigJsPath = await this.prepareDrizzleConfig({
-        kit,
+        kit: drizzleKitProvider,
         provider,
         providerName,
         providerUrl: provider.url,
@@ -536,14 +558,30 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       return;
     }
 
-    const entry = await boot.getServerEntry(root).catch(() => null);
-    await this.fs.writeFile(
-      join(root, "index.html"),
-      indexHtml(entry ? entry.replace(root, "") : undefined),
-    );
+    const serverEntry = "src/main.server.ts";
+    const browserEntry = "src/main.browser.ts";
+    const appRouter = "src/AppRouter.ts";
+
+    await this.fs.writeFile(join(root, "index.html"), indexHtml(browserEntry));
+
+    try {
+      await this.fs.mkdir(join(root, "src"), { recursive: true });
+    } catch {}
+
+    if (!(await this.fs.exists(join(root, browserEntry)))) {
+      await this.fs.writeFile(join(root, browserEntry), mainBrowserTs());
+    }
+
+    if (!(await this.fs.exists(join(root, serverEntry)))) {
+      await this.fs.writeFile(join(root, serverEntry), mainBrowserTs());
+    }
+
+    if (!(await this.fs.exists(join(root, appRouter)))) {
+      await this.fs.writeFile(join(root, appRouter), appRouterTs());
+    }
   }
 
-  public async hasDir(root: string, dirName: string): Promise<boolean> {
+  public async exists(root: string, dirName: string): Promise<boolean> {
     return this.fs.exists(join(root, dirName));
   }
 
@@ -559,6 +597,5 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
 
 export interface DependencyModes {
   react?: boolean;
-  // testing?: boolean;
-  // ui?: boolean;
+  admin?: boolean;
 }

package/src/command/index.ts

@@ -1,33 +1,33 @@
 import { $module } from "alepha";
-import { $command } from "./descriptors/$command.ts";
 import { Asker } from "./helpers/Asker.ts";
 import { PrettyPrint } from "./helpers/PrettyPrint.ts";
 import { Runner } from "./helpers/Runner.ts";
+import { $command } from "./primitives/$command.ts";
 import { CliProvider } from "./providers/CliProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$command.ts";
 export * from "./errors/CommandError.ts";
 export * from "./helpers/Asker.ts";
 export * from "./helpers/PrettyPrint.ts";
 export * from "./helpers/Runner.ts";
+export * from "./primitives/$command.ts";
 export * from "./providers/CliProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
  * This module provides a powerful way to build command-line interfaces
- * directly within your Alepha application, using declarative descriptors.
+ * directly within your Alepha application, using declarative primitives.
  *
- * It allows you to define commands using the `$command` descriptor.
+ * It allows you to define commands using the `$command` primitive.
  *
  * @see {@link $command}
  * @module alepha.command
  */
 export const AlephaCommand = $module({
   name: "alepha.command",
-  descriptors: [$command],
+  primitives: [$command],
   services: [CliProvider, Runner, Asker, PrettyPrint],
 });
 

package/src/command/{descriptors → primitives}/$command.ts

@@ -2,9 +2,9 @@ import type * as fs from "node:fs/promises";
 import type { glob } from "node:fs/promises";
 import {
   type Async,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Static,
   type TObject,
   type TSchema,
@@ -16,19 +16,16 @@ import type { RunnerMethod } from "../helpers/Runner.ts";
 /**
  * Declares a CLI command.
  *
- * This descriptor allows you to define a command, its flags, and its handler
+ * This primitive allows you to define a command, its flags, and its handler
  * within your Alepha application structure.
  */
 export const $command = <T extends TObject, A extends TSchema>(
-  options: CommandDescriptorOptions<T, A>,
-) => createDescriptor(CommandDescriptor<T, A>, options);
+  options: CommandPrimitiveOptions<T, A>,
+) => createPrimitive(CommandPrimitive<T, A>, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface CommandDescriptorOptions<
-  T extends TObject,
-  A extends TSchema,
-> {
+export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
   /**
    * The handler function to execute when the command is matched.
    */
@@ -89,10 +86,10 @@ export interface CommandDescriptorOptions<
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class CommandDescriptor<
+export class CommandPrimitive<
   T extends TObject = TObject,
   A extends TSchema = TSchema,
-> extends Descriptor<CommandDescriptorOptions<T, A>> {
+> extends Primitive<CommandPrimitiveOptions<T, A>> {
   public readonly flags = this.options.flags ?? t.object({});
   public readonly aliases = this.options.aliases ?? [];
 
@@ -104,7 +101,7 @@ export class CommandDescriptor<
   }
 }
 
-$command[KIND] = CommandDescriptor;
+$command[KIND] = CommandPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/command/providers/CliProvider.ts

@@ -14,14 +14,14 @@ import {
   t,
 } from "alepha";
 import { $logger } from "alepha/logger";
-import {
-  $command,
-  type CommandDescriptor,
-  type CommandHandlerArgs,
-} from "../descriptors/$command.ts";
 import { CommandError } from "../errors/CommandError.ts";
 import { Asker } from "../helpers/Asker.ts";
 import { Runner } from "../helpers/Runner.ts";
+import {
+  $command,
+  type CommandHandlerArgs,
+  type CommandPrimitive,
+} from "../primitives/$command.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -176,11 +176,11 @@ export class CliProvider {
     },
   });
 
-  public get commands(): CommandDescriptor<any>[] {
-    return this.alepha.descriptors($command);
+  public get commands(): CommandPrimitive<any>[] {
+    return this.alepha.primitives($command);
   }
 
-  protected findCommand(name: string): CommandDescriptor<TObject> | undefined {
+  protected findCommand(name: string): CommandPrimitive<TObject> | undefined {
     return this.commands.find(
       (command) => command.name === name || command.aliases.includes(name),
     );
@@ -408,7 +408,7 @@ export class CliProvider {
     return "";
   }
 
-  public printHelp(command?: CommandDescriptor<any>): void {
+  public printHelp(command?: CommandPrimitive<any>): void {
     const cliName = this.name || "cli";
     this.log.info(""); // Newline
 
@@ -485,7 +485,7 @@ export class CliProvider {
     this.log.info(""); // Newline
   }
 
-  private getMaxCmdLength(commands: CommandDescriptor[]): number {
+  private getMaxCmdLength(commands: CommandPrimitive[]): number {
     return Math.max(
       ...commands.map((c) => {
         const cmdStr = [c.name, ...c.aliases].join(", ");