alepha 0.13.1 → 0.13.3

package/src/cli/services/ProjectUtils.ts

@@ -72,6 +72,11 @@ export class ProjectUtils {
 
     const devDependencies: Record<string, string> = {};
 
+    if (modes.ui) {
+      dependencies["@alepha/ui"] = `^${version}`;
+      modes.react = true;
+    }
+
     if (modes.react) {
       dependencies["@alepha/react"] = `^${version}`;
       dependencies.react = "^19.2.0";
@@ -79,10 +84,6 @@ export class ProjectUtils {
       devDependencies["@types/react"] = "^19.2.0";
     }
 
-    if (modes.admin) {
-      dependencies["@alepha/ui"] = `^${version}`;
-    }
-
     return {
       type: "module",
       dependencies,
@@ -174,33 +175,6 @@ export class ProjectUtils {
     await Promise.all(tasks);
   }
 
-  /**
-   * Ensure package.json exists and is configured as ES module.
-   *
-   * Similar to ensurePackageJson but only validates/sets the "type": "module" field.
-   * Throws an error if no package.json exists.
-   *
-   * @param root - The root directory of the project
-   * @throws {AlephaError} If no package.json is found
-   */
-  public async ensurePackageJsonModule(root: string): Promise<void> {
-    const packageJsonPath = join(root, "package.json");
-    try {
-      await access(packageJsonPath);
-    } catch (error) {
-      throw new AlephaError(
-        "No package.json found in project root. Run 'npx alepha init' to create one.",
-      );
-    }
-
-    const content = await readFile(packageJsonPath, "utf8");
-    const packageJson = JSON.parse(content);
-    if (!packageJson.type || packageJson.type !== "module") {
-      packageJson.type = "module";
-      await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
-    }
-  }
-
   /**
    * Ensure tsconfig.json exists in the project.
    *
@@ -217,25 +191,30 @@ export class ProjectUtils {
    *
    * Creates a standard Alepha vite.config.ts if none exists.
    */
-  public async ensureViteConfig(root: string): Promise<void> {
-    await this.ensureFileExists(root, "vite.config.ts", viteConfigTs(), false);
+  public async ensureViteConfig(
+    root: string,
+    serverEntry?: string,
+  ): Promise<void> {
+    await this.ensureFileExists(
+      root,
+      "vite.config.ts",
+      viteConfigTs(serverEntry),
+      false,
+    );
   }
 
-  protected async ensureFileExists(
+  protected async checkFileExists(
     root: string,
     name: string,
-    content: string,
     checkParentDirectories: boolean = false,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const configPath = join(root, name);
-
     if (!checkParentDirectories) {
       try {
         await access(configPath);
-        return;
+        return true;
       } catch {
-        await writeFile(configPath, content);
-        return;
+        return false;
       }
     }
 
@@ -259,8 +238,23 @@ export class ProjectUtils {
       level += 1;
     }
 
+    return found;
+  }
+
+  protected async ensureFileExists(
+    root: string,
+    name: string,
+    content: string,
+    checkParentDirectories: boolean = false,
+  ): Promise<void> {
+    const found = await this.checkFileExists(
+      root,
+      name,
+      checkParentDirectories,
+    );
+
     if (!found) {
-      await writeFile(configPath, content);
+      await writeFile(join(root, name), content);
     }
   }
 
@@ -277,35 +271,6 @@ export class ProjectUtils {
     await this.ensureFileExists(root, "biome.json", biomeJson, true);
   }
 
-  // ===================================================================================================================
-  // Vite Configuration
-  // ===================================================================================================================
-
-  /**
-   * Get the path to Vite configuration file.
-   *
-   * Looks for an existing vite.config.ts in the project root, or creates one if it doesn't exist.
-   *
-   * @param root - The root directory of the project (defaults to process.cwd())
-   * @param serverEntry - Optional path to the server entry file to include in the config
-   * @returns Absolute path to the vite.config.ts file
-   */
-  public async getViteConfigPath(
-    root: string,
-    serverEntry?: string,
-  ): Promise<string> {
-    try {
-      const viteConfigPath = join(root, "vite.config.ts");
-      await access(viteConfigPath);
-      return viteConfigPath;
-    } catch {
-      return this.runner.writeConfigFile(
-        "vite.config.ts",
-        viteConfigTs(serverEntry),
-      );
-    }
-  }
-
   // ===================================================================================================================
   // Drizzle ORM & Kit Utilities
   // ===================================================================================================================
@@ -429,6 +394,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";
     }
@@ -442,6 +417,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.
    *
@@ -459,6 +452,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(
@@ -472,8 +468,8 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       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;
 
@@ -513,13 +509,13 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
   public async getPackageManager(
     root: string,
   ): Promise<"yarn" | "pnpm" | "npm"> {
-    if (await this.fs.exists(join(root, "yarn.lock"))) {
+    if (await this.checkFileExists(root, "yarn.lock", true)) {
       return "yarn";
-    } else if (await this.fs.exists(join(root, "pnpm-lock.yaml"))) {
+    }
+    if (await this.checkFileExists(root, "pnpm-lock.yaml", true)) {
       return "pnpm";
-    } else {
-      return "npm";
     }
+    return "npm";
   }
 
   public async ensureIndexHtml(root: string) {
@@ -550,7 +546,7 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     }
   }
 
-  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));
   }
 
@@ -566,5 +562,5 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
 
 export interface DependencyModes {
   react?: boolean;
-  admin?: boolean;
+  ui?: boolean;
 }

package/src/command/helpers/Asker.ts

@@ -7,6 +7,7 @@ import {
   type Static,
   type TSchema,
   type TString,
+  t,
 } from "alepha";
 import { $logger } from "alepha/logger";
 
@@ -44,6 +45,8 @@ export interface AskMethod {
     question: string,
     options?: AskOptions<T>,
   ): Promise<Static<T>>;
+
+  permission: (question: string) => Promise<boolean>;
 }
 
 export class Asker {
@@ -63,6 +66,13 @@ export class Asker {
       return await this.prompt<T>(question, options);
     };
 
+    askFn.permission = async (question: string) => {
+      const response = await this.prompt(`${question} [Y/n]`, {
+        schema: t.enum(["Y", "y", "n", "no", "yes"], { default: "Y" }),
+      });
+      return response.charAt(0).toLowerCase() === "y";
+    };
+
     return askFn;
   }
 

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(", ");

package/src/core/Alepha.ts

@@ -2,13 +2,11 @@ import type { Static, TObject } from "typebox";
 import { KIND } from "./constants/KIND.ts";
 import { MODULE } from "./constants/MODULE.ts";
 import { OPTIONS } from "./constants/OPTIONS.ts";
-import type { InjectOptions } from "./descriptors/$inject.ts";
-import { Module, type WithModule } from "./descriptors/$module.ts";
 import { AlephaError } from "./errors/AlephaError.ts";
 import { CircularDependencyError } from "./errors/CircularDependencyError.ts";
 import { ContainerLockedError } from "./errors/ContainerLockedError.ts";
 import { TooLateSubstitutionError } from "./errors/TooLateSubstitutionError.ts";
-import { Descriptor } from "./helpers/descriptor.ts";
+import { Primitive } from "./helpers/primitive.ts";
 import { __alephaRef } from "./helpers/ref.ts";
 import type { Async } from "./interfaces/Async.ts";
 import type { LoggerInterface } from "./interfaces/LoggerInterface.ts";
@@ -19,6 +17,8 @@ import {
   type Service,
   type ServiceEntry,
 } from "./interfaces/Service.ts";
+import type { InjectOptions } from "./primitives/$inject.ts";
+import { Module, type WithModule } from "./primitives/$module.ts";
 import { AlsProvider } from "./providers/AlsProvider.ts";
 import { CodecManager } from "./providers/CodecManager.ts";
 import { EventManager } from "./providers/EventManager.ts";
@@ -82,7 +82,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * // You can access the environment variables using alepha.env
  * console.log(alepha.env.MY_VAR); // "value"
  *
- * // But you should use $env() descriptor to get typed values from the environment.
+ * // But you should use $env() primitive to get typed values from the environment.
  * class App {
  *   env = $env(
  *     t.object({
@@ -95,7 +95,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * ### Modules
  *
  * Modules are a way to group services together.
- * You can register a module using the `$module` descriptor.
+ * You can register a module using the `$module` primitive.
  *
  * ```ts
  * import { $module } from "alepha";
@@ -113,7 +113,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * ### Hooks
  *
  * Hooks are a way to run async functions from all registered providers/services.
- * You can register a hook using the `$hook` descriptor.
+ * You can register a hook using the `$hook` primitive.
  *
  * ```ts
  * import { $hook } from "alepha";
@@ -187,7 +187,7 @@ export class Alepha {
         // ignore
       }
 
-      alepha.state
+      alepha.store
         .set("alepha.test.beforeAll", beforeAll)
         .set("alepha.test.afterAll", afterAll)
         .set("alepha.test.afterEach", afterEach)
@@ -257,12 +257,9 @@ export class Alepha {
   protected substitutions = new Map<Service, { use: Service }>();
 
   /**
-   * Registry of descriptors.
+   * Registry of primitives.
    */
-  protected descriptorRegistry = new Map<
-    Service<Descriptor>,
-    Array<Descriptor>
-  >();
+  protected primitiveRegistry = new Map<Service<Primitive>, Array<Primitive>>();
 
   /**
    *  List of all services + how they are provided.
@@ -294,7 +291,7 @@ export class Alepha {
   /**
    * State manager to store arbitrary values.
    */
-  public get state(): StateManager<State> {
+  public get store(): StateManager<State> {
     this.events; // ensure events is initialized first (TODO: move this to constructor?)
     return this.inject(StateManager, {
       args: [this.init],
@@ -314,14 +311,14 @@ export class Alepha {
    * Get logger instance.
    */
   public get log(): LoggerInterface | undefined {
-    return this.state.get("alepha.logger");
+    return this.store.get("alepha.logger");
   }
 
   /**
    * The environment variables for the App.
    */
   public get env(): Readonly<Env> {
-    return this.state.get("env") ?? {};
+    return this.store.get("env") ?? {};
   }
 
   constructor(init: Partial<State> = {}) {
@@ -442,7 +439,7 @@ export class Alepha {
    * Starts the App.
    *
    * - Lock any further changes to the container.
-   * - Run "configure" hook for all services. Descriptors will be processed.
+   * - Run "configure" hook for all services. Primitives will be processed.
    * - Run "start" hook for all services. Providers will connect/listen/...
    * - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
    *
@@ -472,10 +469,10 @@ export class Alepha {
       this.inject(key);
     }
 
-    const target = this.state.get("alepha.target");
+    const target = this.store.get("alepha.target");
     if (target) {
       this.registry = new Map();
-      this.descriptorRegistry = new Map();
+      this.primitiveRegistry = new Map();
       this.with(target);
     }
 
@@ -878,28 +875,28 @@ export class Alepha {
   }
 
   /**
-   * Get all descriptors of the specified type.
+   * Get all primitives of the specified type.
    */
-  public descriptors<TDescriptor extends Descriptor>(
+  public primitives<TPrimitive extends Primitive>(
     factory:
       | {
-          [KIND]: InstantiableClass<TDescriptor>;
+          [KIND]: InstantiableClass<TPrimitive>;
         }
       | string,
-  ): Array<TDescriptor> {
+  ): Array<TPrimitive> {
     if (typeof factory === "string") {
       const key1 = factory.toLowerCase().replace("$", "");
-      const key2 = `${key1}descriptor`;
-      for (const [key, value] of this.descriptorRegistry.entries()) {
+      const key2 = `${key1}primitive`;
+      for (const [key, value] of this.primitiveRegistry.entries()) {
         const name = key.name.toLowerCase();
         if (name === key1 || name === key2) {
-          return value as Array<TDescriptor>;
+          return value as Array<TPrimitive>;
         }
       }
       return [];
     }
-    return (this.descriptorRegistry.get(factory[KIND]) ??
-      []) as Array<TDescriptor>;
+    return (this.primitiveRegistry.get(factory[KIND]) ??
+      []) as Array<TPrimitive>;
   }
 
   // -------------------------------------------------------------------------------------------------------------------
@@ -922,8 +919,8 @@ export class Alepha {
 
     const obj = instance as unknown as Record<string, any>;
     for (const [key, value] of Object.entries(obj)) {
-      if (value instanceof Descriptor) {
-        this.processDescriptor(value, key);
+      if (value instanceof Primitive) {
+        this.processPrimitive(value, key);
       }
       if (
         typeof value === "object" &&
@@ -933,7 +930,7 @@ export class Alepha {
       ) {
         const getter = value[OPTIONS].getter as keyof State;
         Object.defineProperty(obj, key, {
-          get: () => this.state.get(getter),
+          get: () => this.store.get(getter),
         });
       }
     }
@@ -951,13 +948,13 @@ export class Alepha {
     return instance;
   }
 
-  protected processDescriptor(value: Descriptor, propertyKey = "") {
+  protected processPrimitive(value: Primitive, propertyKey = "") {
     value.config.propertyKey = propertyKey;
     (value as any).onInit();
 
     const kind = value.constructor as Service;
-    const list = this.descriptorRegistry.get(kind) ?? [];
-    this.descriptorRegistry.set(kind, [...list, value]);
+    const list = this.primitiveRegistry.get(kind) ?? [];
+    this.primitiveRegistry.set(kind, [...list, value]);
   }
 }
 

package/src/core/constants/KIND.ts

@@ -1,5 +1,5 @@
 /**
- * Used for identifying descriptors.
+ * Used for identifying primitives.
  *
  * @internal
  */

package/src/core/constants/OPTIONS.ts

@@ -1,5 +1,5 @@
 /**
- * Used for descriptors options.
+ * Used for primitives options.
  *
  * @internal
  */