alepha 0.13.6 → 0.13.8

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.
    *
@@ -157,6 +196,14 @@ export class AlephaCliUtils {
 
     const devDependencies: Record<string, string> = {};
 
+    const scripts: Record<string, string> = {
+      dev: "alepha dev",
+      build: "alepha build",
+      lint: "alepha lint",
+      typecheck: "alepha typecheck",
+      verify: "alepha verify",
+    };
+
     if (modes.ui) {
       dependencies["@alepha/ui"] = `^${version}`;
       modes.react = true;
@@ -173,11 +220,7 @@ export class AlephaCliUtils {
       type: "module",
       dependencies,
       devDependencies,
-      scripts: {
-        dev: "alepha dev",
-        build: "alepha build",
-        verify: "alepha verify",
-      },
+      scripts,
     };
   }
 
@@ -195,16 +238,14 @@ export class AlephaCliUtils {
   public async ensurePackageJson(
     root: string,
     modes: DependencyModes,
-  ): Promise<void> {
+  ): Promise<object> {
     const packageJsonPath = join(root, "package.json");
     try {
       await access(packageJsonPath);
     } catch (error) {
-      await writeFile(
-        packageJsonPath,
-        JSON.stringify(this.generatePackageJsonContent(modes), null, 2),
-      );
-      return;
+      const obj = this.generatePackageJsonContent(modes);
+      await writeFile(packageJsonPath, JSON.stringify(obj, null, 2));
+      return obj;
     }
 
     const content = await readFile(packageJsonPath, "utf8");
@@ -222,6 +263,8 @@ export class AlephaCliUtils {
     Object.assign(packageJson.scripts, newPackageJson.scripts);
 
     await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
+
+    return packageJson;
   }
 
   public async ensureConfig(
@@ -232,9 +275,10 @@ export class AlephaCliUtils {
       viteConfigTs?: boolean;
       indexHtml?: boolean;
       biomeJson?: boolean;
+      editorconfig?: boolean;
     },
-  ) {
-    const tasks: Promise<void>[] = [];
+  ): Promise<Array<void | object>> {
+    const tasks: Promise<void | object>[] = [];
 
     if (opts.packageJson) {
       tasks.push(
@@ -256,8 +300,11 @@ export class AlephaCliUtils {
     if (opts.biomeJson) {
       tasks.push(this.ensureBiomeConfig(root));
     }
+    if (opts.editorconfig) {
+      tasks.push(this.ensureEditorConfig(root));
+    }
 
-    await Promise.all(tasks);
+    return await Promise.all(tasks);
   }
 
   /**
@@ -353,6 +400,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 +643,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 +653,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 +708,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,9 +774,84 @@ ${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;
+    }
+  }
+
+  /**
+   * Check if Expo is present in the project.
+   *
+   * @param root - The root directory of the project
+   * @returns True if expo is in dependencies or devDependencies
+   */
+  async hasExpo(root: string): Promise<boolean> {
+    return this.hasDependency(root, "expo");
+  }
+
+  /**
+   * 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 {
   react?: boolean;
   ui?: boolean;
+  expo?: boolean;
 }

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}`;
   }
 }

package/src/command/providers/CliProvider.ts

@@ -169,8 +169,23 @@ export class CliProvider {
           root: process.cwd(),
         };
 
+        // Execute pre-hooks
+        const preHooks = this.findPreHooks(command.name);
+        for (const hook of preHooks) {
+          this.log.debug(`Executing pre-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
+        // Execute main command
         await command.options.handler(args as CommandHandlerArgs<TObject>);
 
+        // Execute post-hooks
+        const postHooks = this.findPostHooks(command.name);
+        for (const hook of postHooks) {
+          this.log.debug(`Executing post-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
         if (command.options.summary !== false) {
           runner.summary();
         }
@@ -185,11 +200,25 @@ export class CliProvider {
   }
 
   protected findCommand(name: string): CommandPrimitive<TObject> | undefined {
-    return this.commands.find(
+    return this.commands.findLast(
       (command) => command.name === name || command.aliases.includes(name),
     );
   }
 
+  /**
+   * Find all pre-hooks for a command.
+   */
+  protected findPreHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `pre${commandName}`);
+  }
+
+  /**
+   * Find all post-hooks for a command.
+   */
+  protected findPostHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `post${commandName}`);
+  }
+
   /**
    * Get all global flags including those from the root command (name === "")
    */
@@ -464,8 +493,8 @@ export class CliProvider {
       const maxCmdLength = this.getMaxCmdLength(this.commands);
 
       for (const command of this.commands) {
-        // skip root command in list
-        if (command.name === "") {
+        // skip root command and hooks in list
+        if (command.name === "" || command.options.hide) {
           continue;
         }
 
@@ -495,11 +524,13 @@ export class CliProvider {
 
   private getMaxCmdLength(commands: CommandPrimitive[]): number {
     return Math.max(
-      ...commands.map((c) => {
-        const cmdStr = [c.name, ...c.aliases].join(", ");
-        const argsUsage = this.generateArgsUsage(c.options.args);
-        return `${cmdStr}${argsUsage}`.length;
-      }),
+      ...commands
+        .filter((c) => !c.options.hide && c.name !== "")
+        .map((c) => {
+          const cmdStr = [c.name, ...c.aliases].join(", ");
+          const argsUsage = this.generateArgsUsage(c.options.args);
+          return `${cmdStr}${argsUsage}`.length;
+        }),
     );
   }