alepha 0.13.6 → 0.13.7

package/src/api-verifications/index.ts

@@ -1,6 +1,7 @@
 import { $module } from "alepha";
 import { VerificationController } from "./controllers/VerificationController.ts";
 import { VerificationJobs } from "./jobs/VerificationJobs.ts";
+import { VerificationParameters } from "./parameters/VerificationParameters.ts";
 import { VerificationService } from "./services/VerificationService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -25,5 +26,10 @@ export * from "./services/VerificationService.ts";
  */
 export const AlephaApiVerification = $module({
   name: "alepha.api.verifications",
-  services: [VerificationController, VerificationJobs, VerificationService],
+  services: [
+    VerificationController,
+    VerificationJobs,
+    VerificationService,
+    VerificationParameters,
+  ],
 });

package/src/bin/index.ts

@@ -5,6 +5,7 @@ import { AlephaCli, version } from "alepha/cli";
 
 const alepha = Alepha.create({
   env: {
+    APP_NAME: "CLI",
     LOG_LEVEL: "alepha.core:warn,info",
     LOG_FORMAT: "raw",
     CLI_NAME: "alepha",

package/src/cli/assets/biomeJson.ts

@@ -11,7 +11,7 @@ export const biomeJson = `
   },
   "formatter": {
     "enabled": true,
-    "indentStyle": "space"
+    "useEditorconfig": true
   },
   "linter": {
     "enabled": true,

package/src/cli/assets/dummySpecTs.ts

@@ -0,0 +1,7 @@
+export const dummySpecTs = () => `
+import { test, expect } from "vitest";
+
+test("dummy test", () => {
+  expect(1 + 1).toBe(2);
+});
+`.trim();

package/src/cli/assets/editorconfig.ts

@@ -0,0 +1,13 @@
+export const editorconfig = `
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+`.trim();

package/src/cli/assets/mainTs.ts

@@ -0,0 +1,14 @@
+export const mainTs = () => `
+import { Alepha, run } from "alepha";
+import { $logger } from "alepha/logger";
+
+const alepha = Alepha.create();
+
+alepha.with(() => {
+  const log = $logger();
+
+  log.info("Hello from Alepha!");
+});
+
+run(alepha);
+`.trim();

package/src/cli/commands/BiomeCommands.ts

@@ -12,6 +12,7 @@ export class BiomeCommands {
     description: "Format the codebase using Biome",
     handler: async ({ root }) => {
       await this.utils.ensureConfig(root, { biomeJson: true });
+      await this.utils.ensureDependency(root, "@biomejs/biome");
       await this.utils.exec(`biome format --fix`);
     },
   });
@@ -21,6 +22,7 @@ export class BiomeCommands {
     description: "Run linter across the codebase using Biome",
     handler: async ({ root }) => {
       await this.utils.ensureConfig(root, { biomeJson: true });
+      await this.utils.ensureDependency(root, "@biomejs/biome");
       await this.utils.exec(`biome check --formatter-enabled=false --fix`);
     },
   });

package/src/cli/commands/CoreCommands.ts

@@ -58,6 +58,8 @@ 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" })),
+      npm: t.optional(t.boolean({ description: "Use npm package manager" })),
+      bun: t.optional(t.boolean({ description: "Use Bun package manager" })),
       // choose which dependencies to add
       react: t.optional(
         t.boolean({ description: "Include Alepha React dependencies" }),
@@ -65,6 +67,9 @@ export class CoreCommands {
       ui: t.optional(
         t.boolean({ description: "Include Alepha UI dependencies" }),
       ),
+      test: t.optional(
+        t.boolean({ description: "Include Vitest and create test directory" }),
+      ),
     }),
     handler: async ({ run, flags, root }) => {
       if (flags.ui) {
@@ -72,31 +77,45 @@ export class CoreCommands {
       }
 
       await run({
-        name: "Ensuring configuration files",
+        name: "ensuring configuration files",
         handler: async () => {
           await this.utils.ensureConfig(root, {
             tsconfigJson: true,
             packageJson: flags,
             biomeJson: true,
             viteConfigTs: true,
+            editorconfig: true,
             indexHtml: !!flags.react,
           });
+
+          // Create src/main.ts if src directory is empty or doesn't exist
+          if (!flags.react) {
+            await this.utils.ensureSrcMain(root);
+          }
         },
       });
 
       // TODO: check if all alepha dependencies are same version
 
-      const guessedPm = await this.utils.getPackageManager(root);
-
-      if (flags.yarn || guessedPm === "yarn") {
+      const pm = await this.utils.getPackageManager(root, flags);
+      if (pm === "yarn") {
         await this.utils.ensureYarn(root);
         await run("yarn set version stable");
-        await run("yarn install", {
-          alias: "Installing dependencies with Yarn",
-        });
+      } else if (pm === "pnpm") {
+        await this.utils.ensurePnpm(root);
       } else {
-        await run("npm install", {
-          alias: "Installing dependencies with npm",
+        await this.utils.ensureNpm(root);
+      }
+
+      await run(`${pm} install`, {
+        alias: `installing dependencies with ${pm}`,
+      });
+
+      // Install vitest and create test directory if --test flag is set
+      if (flags.test) {
+        await this.utils.ensureTestDir(root);
+        await run(`${pm} ${pm === "yarn" ? "add" : "install"} -D vitest`, {
+          alias: "setup testing with Vitest",
         });
       }
     },

package/src/cli/commands/VerifyCommands.ts

@@ -48,7 +48,8 @@ export class VerifyCommands {
   public readonly typecheck = $command({
     name: "typecheck",
     description: "Check TypeScript types across the codebase",
-    handler: async () => {
+    handler: async ({ root }) => {
+      await this.utils.ensureDependency(root, "typescript");
       await this.utils.exec("tsc --noEmit");
     },
   });

package/src/cli/commands/ViteCommands.ts

@@ -75,6 +75,8 @@ export class ViteCommands {
         return;
       }
 
+      // Ensure vite is installed before running
+      await this.utils.ensureDependency(root, "vite");
       await this.utils.exec(`vite`);
     },
   });
@@ -132,6 +134,10 @@ export class ViteCommands {
       const distDir = "dist";
       const clientDir = "public";
 
+      await this.utils.ensureDependency(root, "vite", {
+        run,
+      });
+
       await run.rm("dist", {
         alias: "clean dist",
       });
@@ -301,15 +307,8 @@ export class ViteCommands {
         viteConfigTs: true,
       });
 
-      // check if vitest is installed
-      try {
-        await import("vitest");
-      } catch {
-        this.log.error(
-          "Vitest is not installed. Please install it with `npm install -D vitest` or `yarn add -D vitest`.",
-        );
-        process.exit(1);
-      }
+      // Ensure vitest is installed before running
+      await this.utils.ensureDependency(root, "vitest");
 
       await this.utils.exec(`vitest run ${this.env.VITEST_ARGS}`);
     },

package/src/cli/services/AlephaCliUtils.ts

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { $inject, Alepha, AlephaError } from "alepha";
+import type { RunnerMethod } from "alepha/command";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import type { DrizzleKitProvider, RepositoryProvider } from "alepha/orm";
@@ -9,8 +10,11 @@ import { boot } from "alepha/vite";
 import { tsImport } from "tsx/esm/api";
 import { appRouterTs } from "../assets/appRouterTs.ts";
 import { biomeJson } from "../assets/biomeJson.ts";
+import { dummySpecTs } from "../assets/dummySpecTs.ts";
+import { editorconfig } from "../assets/editorconfig.ts";
 import { indexHtml } from "../assets/indexHtml.ts";
 import { mainBrowserTs } from "../assets/mainBrowserTs.ts";
+import { mainTs } from "../assets/mainTs.ts";
 import { tsconfigJson } from "../assets/tsconfigJson.ts";
 import { viteConfigTs } from "../assets/viteConfigTs.ts";
 import { version } from "../version.ts";
@@ -32,10 +36,6 @@ export class AlephaCliUtils {
   /**
    * Execute a command using npx with inherited stdio.
    *
-   * @param command - The command to execute (will be passed to npx)
-   * @param env - Optional environment variables to set for the command
-   * @returns Promise that resolves when the process exits
-   *
    * @example
    * ```ts
    * const runner = alepha.inject(ProcessRunner);
@@ -44,40 +44,63 @@ export class AlephaCliUtils {
    */
   public async exec(
     command: string,
-    env: Record<string, string> = {},
+    options: {
+      env?: Record<string, string>;
+      global?: boolean;
+    } = {},
   ): Promise<void> {
     const root = process.cwd();
     this.log.debug(`Executing command: ${command}`, { cwd: root });
 
+    const runExec = async (app: string, args: string[]) => {
+      const prog = spawn(app, args, {
+        stdio: "inherit",
+        cwd: root,
+        env: {
+          ...process.env,
+          ...options.env,
+        },
+      });
+
+      await new Promise<void>((resolve) =>
+        prog.on("exit", () => {
+          resolve();
+        }),
+      );
+    };
+
+    if (options.global) {
+      const [app, ...args] = command.split(" ");
+      await runExec(app, args);
+      return;
+    }
+
     const suffix = process.platform === "win32" ? ".cmd" : "";
     const [app, ...args] = command.split(" ");
-    const execPath = await this.checkFileExists(
+
+    // find executable inside project node_modules
+    let execPath = await this.checkFileExists(
       root,
       `node_modules/.bin/${app}${suffix}`,
       true,
     );
 
+    // or, find executable inside alepha package node_modules (pnpm style)
+    if (!execPath) {
+      execPath = await this.checkFileExists(
+        root,
+        `node_modules/alepha/node_modules/.bin/${app}${suffix}`,
+        true,
+      );
+    }
+
     if (!execPath) {
       throw new AlephaError(
         `Could not find executable for command '${app}'. Make sure the package is installed.`,
       );
     }
 
-    const prog = spawn(execPath, args, {
-      stdio: "inherit",
-      cwd: root,
-      env: {
-        ...process.env,
-        ...env,
-        //  NODE_OPTIONS: "--import tsx",
-      },
-    });
-
-    await new Promise<void>((resolve) =>
-      prog.on("exit", () => {
-        resolve();
-      }),
-    );
+    await runExec(execPath, args);
   }
 
   /**
@@ -139,6 +162,22 @@ export class AlephaCliUtils {
     await this.fs.rm(join(root, "pnpm-lock.yaml"), { force: true });
   }
 
+  public async ensurePnpm(root: string): Promise<void> {
+    // remove lock files from other package managers
+    await this.fs.rm(join(root, "package-lock.json"), { force: true });
+    await this.fs.rm(join(root, "yarn.lock"), { force: true });
+    await this.fs.rm(join(root, ".yarn"), { force: true, recursive: true });
+    await this.fs.rm(join(root, ".yarnrc.yml"), { force: true });
+  }
+
+  public async ensureNpm(root: string): Promise<void> {
+    // remove lock files from other package managers
+    await this.fs.rm(join(root, "pnpm-lock.yaml"), { force: true });
+    await this.fs.rm(join(root, "yarn.lock"), { force: true });
+    await this.fs.rm(join(root, ".yarn"), { force: true, recursive: true });
+    await this.fs.rm(join(root, ".yarnrc.yml"), { force: true });
+  }
+
   /**
    * Generate package.json content with Alepha dependencies.
    *
@@ -232,6 +271,7 @@ export class AlephaCliUtils {
       viteConfigTs?: boolean;
       indexHtml?: boolean;
       biomeJson?: boolean;
+      editorconfig?: boolean;
     },
   ) {
     const tasks: Promise<void>[] = [];
@@ -256,6 +296,9 @@ export class AlephaCliUtils {
     if (opts.biomeJson) {
       tasks.push(this.ensureBiomeConfig(root));
     }
+    if (opts.editorconfig) {
+      tasks.push(this.ensureEditorConfig(root));
+    }
 
     await Promise.all(tasks);
   }
@@ -353,6 +396,17 @@ export class AlephaCliUtils {
     await this.ensureFileExists(root, "biome.json", biomeJson, true);
   }
 
+  /**
+   * Ensure .editorconfig exists in the project.
+   *
+   * Creates a standard .editorconfig if none exists.
+   *
+   * @param root - The root directory of the project
+   */
+  public async ensureEditorConfig(root: string): Promise<void> {
+    await this.ensureFileExists(root, ".editorconfig", editorconfig, true);
+  }
+
   // ===================================================================================================================
   // Drizzle ORM & Kit Utilities
   // ===================================================================================================================
@@ -585,7 +639,9 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       await this.exec(
         `drizzle-kit ${options.command} --config=${drizzleConfigJsPath}${flags}`,
         {
-          NODE_OPTIONS: "--import tsx",
+          env: {
+            NODE_OPTIONS: "--import tsx",
+          },
         },
       );
     }
@@ -593,7 +649,20 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
 
   public async getPackageManager(
     root: string,
-  ): Promise<"yarn" | "pnpm" | "npm"> {
+    flags?: { yarn?: boolean; pnpm?: boolean; npm?: boolean; bun?: boolean },
+  ): Promise<"yarn" | "pnpm" | "npm" | "bun"> {
+    if (flags?.yarn) {
+      return "yarn";
+    }
+    if (flags?.pnpm) {
+      return "pnpm";
+    }
+    if (flags?.npm) {
+      return "npm";
+    }
+    if (flags?.bun) {
+      return "bun";
+    }
     if (await this.checkFileExists(root, "yarn.lock", true)) {
       return "yarn";
     }
@@ -635,6 +704,64 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     return this.fs.exists(join(root, dirName));
   }
 
+  /**
+   * Ensure src/main.ts exists with a minimal Alepha bootstrap.
+   *
+   * Creates the src directory and main.ts file if the src directory
+   * doesn't exist or is empty.
+   *
+   * @param root - The root directory of the project
+   */
+  public async ensureSrcMain(root: string): Promise<void> {
+    const srcDir = join(root, "src");
+    const mainPath = join(srcDir, "main.ts");
+
+    // Check if src directory exists
+    const srcExists = await this.fs.exists(srcDir);
+
+    if (!srcExists) {
+      // Create src directory and main.ts
+      await this.fs.mkdir(srcDir, { recursive: true });
+      await this.fs.writeFile(mainPath, mainTs());
+      return;
+    }
+
+    // Check if src directory is empty
+    const files = await this.fs.ls(srcDir);
+    if (files.length === 0) {
+      await this.fs.writeFile(mainPath, mainTs());
+    }
+  }
+
+  /**
+   * Ensure test directory exists with a dummy test file.
+   *
+   * Creates the test directory and a dummy.spec.ts file if the test directory
+   * doesn't exist or is empty.
+   *
+   * @param root - The root directory of the project
+   */
+  public async ensureTestDir(root: string): Promise<void> {
+    const testDir = join(root, "test");
+    const dummyPath = join(testDir, "dummy.spec.ts");
+
+    // Check if test directory exists
+    const testExists = await this.fs.exists(testDir);
+
+    if (!testExists) {
+      // Create test directory and dummy.spec.ts
+      await this.fs.mkdir(testDir, { recursive: true });
+      await this.fs.writeFile(dummyPath, dummySpecTs());
+      return;
+    }
+
+    // Check if test directory is empty
+    const files = await this.fs.ls(testDir);
+    if (files.length === 0) {
+      await this.fs.writeFile(dummyPath, dummySpecTs());
+    }
+  }
+
   async readPackageJson(root: string): Promise<Record<string, any>> {
     const packageJson = await this.fs
       .createFile({
@@ -643,6 +770,70 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
       .text();
     return JSON.parse(packageJson);
   }
+
+  /**
+   * Check if a dependency is installed in the project.
+   *
+   * @param root - The root directory of the project
+   * @param packageName - The name of the package to check
+   * @returns True if the package is in dependencies or devDependencies
+   */
+  async hasDependency(root: string, packageName: string): Promise<boolean> {
+    try {
+      const pkg = await this.readPackageJson(root);
+      return !!(
+        pkg.dependencies?.[packageName] || pkg.devDependencies?.[packageName]
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Install a dependency if it's missing from the project.
+   *
+   * Automatically detects the package manager (yarn, pnpm, npm) and installs
+   * the package as a dev dependency if not already present.
+   */
+  async ensureDependency(
+    root: string,
+    packageName: string,
+    options: { dev?: boolean; run?: RunnerMethod } = {},
+  ): Promise<void> {
+    const { dev = true } = options;
+
+    if (await this.hasDependency(root, packageName)) {
+      this.log.debug(`Dependency '${packageName}' is already installed`);
+      return;
+    }
+
+    const pm = await this.getPackageManager(root);
+    let cmd: string;
+
+    switch (pm) {
+      case "yarn":
+        cmd = `yarn add ${dev ? "-D" : ""} ${packageName}`;
+        break;
+      case "pnpm":
+        cmd = `pnpm add ${dev ? "-D" : ""} ${packageName}`;
+        break;
+      default:
+        cmd = `npm install ${dev ? "--save-dev" : ""} ${packageName}`;
+    }
+
+    cmd = cmd.replace(/\s+/g, " ").trim();
+
+    if (options.run) {
+      // if it's during a Runner flow, just use the runner's run method
+      await options.run(cmd, {
+        alias: `installing ${packageName}`,
+      });
+    } else {
+      // else, run directly with our util exec method
+      this.log.debug(`Installing ${packageName}`);
+      await this.exec(cmd, { global: true });
+    }
+  }
 }
 
 export interface DependencyModes {

package/src/command/helpers/Asker.ts

@@ -40,7 +40,6 @@ export interface AskOptions<T extends TSchema = TString> {
 }
 
 export interface AskMethod {
-  // biome-ignore lint/style/useShorthandFunctionType: .
   <T extends TSchema = TString>(
     question: string,
     options?: AskOptions<T>,

package/src/command/primitives/$command.ts

@@ -82,6 +82,61 @@ export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
    * Equivalent to setting name to an empty string "".
    */
   root?: boolean;
+
+  /**
+   * Run this command's handler BEFORE the specified target command.
+   *
+   * Pre-hooks are not listed in help and cannot be called directly.
+   * They receive the same parsed flags and args as the target command.
+   *
+   * @example
+   * ```ts
+   * class BuildCommands {
+   *   prebuild = $command({
+   *     pre: "build",
+   *     handler: async ({ run }) => {
+   *       await run("cleaning dist folder...", () => fs.rm("dist"));
+   *     }
+   *   });
+   *
+   *   build = $command({
+   *     name: "build",
+   *     handler: async () => { ... }
+   *   });
+   * }
+   * ```
+   */
+  pre?: string;
+
+  /**
+   * Run this command's handler AFTER the specified target command.
+   *
+   * Post-hooks are not listed in help and cannot be called directly.
+   * They receive the same parsed flags and args as the target command.
+   *
+   * @example
+   * ```ts
+   * class BuildCommands {
+   *   build = $command({
+   *     name: "build",
+   *     handler: async () => { ... }
+   *   });
+   *
+   *   postbuild = $command({
+   *     post: "build",
+   *     handler: async ({ run }) => {
+   *       await run("generating checksums...", generateChecksums);
+   *     }
+   *   });
+   * }
+   * ```
+   */
+  post?: string;
+
+  /**
+   * If true, this command will be hidden from the help output.
+   */
+  hide?: boolean;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -93,10 +148,22 @@ export class CommandPrimitive<
   public readonly flags = this.options.flags ?? t.object({});
   public readonly aliases = this.options.aliases ?? [];
 
+  protected onInit() {
+    if (this.options.pre || this.options.post) {
+      this.options.hide ??= true;
+    }
+  }
+
   public get name(): string {
     if (this.options.root) {
       return "";
     }
+    if (this.options.pre) {
+      return `pre${this.options.pre}`;
+    }
+    if (this.options.post) {
+      return `post${this.options.post}`;
+    }
     return this.options.name ?? `${this.config.propertyKey}`;
   }
 }