alepha 0.14.3 → 0.15.0

package/src/cli/services/PackageManagerUtils.ts

@@ -0,0 +1,301 @@
+import { $inject, Alepha } from "alepha";
+import type { RunnerMethod } from "alepha/command";
+import { FileSystemProvider } from "alepha/file";
+import { $logger } from "alepha/logger";
+import { version } from "../version.ts";
+
+/**
+ * Utility service for package manager operations.
+ *
+ * Handles detection, installation, and cleanup for:
+ * - Yarn
+ * - npm
+ * - pnpm
+ * - Bun
+ */
+export class PackageManagerUtils {
+  protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly alepha = $inject(Alepha);
+
+  /**
+   * Detect the package manager used in the project.
+   */
+  public async getPackageManager(
+    root: string,
+    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 (this.alepha.isBun()) return "bun";
+    if (await this.fs.exists(this.fs.join(root, "bun.lock"))) return "bun";
+    if (await this.fs.exists(this.fs.join(root, "yarn.lock"))) return "yarn";
+    if (await this.fs.exists(this.fs.join(root, "pnpm-lock.yaml")))
+      return "pnpm";
+    return "npm";
+  }
+
+  /**
+   * Get the install command for a package.
+   */
+  public async getInstallCommand(
+    root: string,
+    packageName: string,
+    dev = true,
+  ): Promise<string> {
+    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;
+      case "bun":
+        cmd = `bun add ${dev ? "-d" : ""} ${packageName}`;
+        break;
+      default:
+        cmd = `npm install ${dev ? "--save-dev" : ""} ${packageName}`;
+    }
+
+    return cmd.replace(/\s+/g, " ").trim();
+  }
+
+  /**
+   * Check if a dependency is installed in the project.
+   */
+  public 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.
+   */
+  public async hasExpo(root: string): Promise<boolean> {
+    return this.hasDependency(root, "expo");
+  }
+
+  /**
+   * Install a dependency if it's missing from the project.
+   */
+  public async ensureDependency(
+    root: string,
+    packageName: string,
+    options: {
+      dev?: boolean;
+      run?: RunnerMethod;
+      exec?: (
+        cmd: string,
+        opts?: { global?: boolean; root?: string },
+      ) => Promise<void>;
+    } = {},
+  ): Promise<void> {
+    const { dev = true } = options;
+
+    if (await this.hasDependency(root, packageName)) {
+      this.log.debug(`Dependency '${packageName}' is already installed`);
+      return;
+    }
+
+    const cmd = await this.getInstallCommand(root, packageName, dev);
+
+    if (options.run) {
+      await options.run(cmd, { alias: `installing ${packageName}`, root });
+    } else if (options.exec) {
+      this.log.debug(`Installing ${packageName}`);
+      await options.exec(cmd, { global: true, root });
+    }
+  }
+
+  // ===========================================
+  // Package Manager Setup & Cleanup
+  // ===========================================
+
+  public async ensureYarn(root: string): Promise<void> {
+    const yarnrcPath = this.fs.join(root, ".yarnrc.yml");
+    if (!(await this.fs.exists(yarnrcPath))) {
+      await this.fs.writeFile(yarnrcPath, "nodeLinker: node-modules");
+    }
+    await this.removeAllPmFilesExcept(root, "yarn");
+  }
+
+  public async ensureBun(root: string): Promise<void> {
+    await this.removeAllPmFilesExcept(root, "bun");
+  }
+
+  public async ensurePnpm(root: string): Promise<void> {
+    await this.removeAllPmFilesExcept(root, "pnpm");
+  }
+
+  public async ensureNpm(root: string): Promise<void> {
+    await this.removeAllPmFilesExcept(root, "npm");
+  }
+
+  public async removeAllPmFilesExcept(
+    root: string,
+    except: string,
+  ): Promise<void> {
+    if (except !== "yarn") await this.removeYarn(root);
+    if (except !== "pnpm") await this.removePnpm(root);
+    if (except !== "npm") await this.removeNpm(root);
+    if (except !== "bun") await this.removeBun(root);
+  }
+
+  public async removeYarn(root: string): Promise<void> {
+    await this.removeFiles(root, [".yarn", ".yarnrc.yml", "yarn.lock"]);
+    await this.editPackageJson(root, (pkg) => {
+      delete pkg.packageManager;
+      return pkg;
+    });
+  }
+
+  public async removePnpm(root: string): Promise<void> {
+    await this.removeFiles(root, ["pnpm-lock.yaml", "pnpm-workspace.yaml"]);
+    await this.editPackageJson(root, (pkg) => {
+      delete pkg.packageManager;
+      return pkg;
+    });
+  }
+
+  public async removeNpm(root: string): Promise<void> {
+    await this.removeFiles(root, ["package-lock.json"]);
+  }
+
+  public async removeBun(root: string): Promise<void> {
+    await this.removeFiles(root, ["bun.lockb", "bun.lock"]);
+  }
+
+  // ===========================================
+  // Package.json utilities
+  // ===========================================
+
+  public async readPackageJson(root: string): Promise<Record<string, any>> {
+    const content = await this.fs
+      .createFile({ path: this.fs.join(root, "package.json") })
+      .text();
+    return JSON.parse(content);
+  }
+
+  public async writePackageJson(
+    root: string,
+    content: Record<string, any>,
+  ): Promise<void> {
+    await this.fs.writeFile(
+      this.fs.join(root, "package.json"),
+      JSON.stringify(content, null, 2),
+    );
+  }
+
+  public async editPackageJson(
+    root: string,
+    editFn: (pkg: Record<string, any>) => Record<string, any>,
+  ): Promise<void> {
+    try {
+      const pkg = await this.readPackageJson(root);
+      const updated = editFn(pkg);
+      await this.writePackageJson(root, updated);
+    } catch {
+      // package.json doesn't exist, skip
+    }
+  }
+
+  public async ensurePackageJson(
+    root: string,
+    modes: DependencyModes,
+  ): Promise<Record<string, any>> {
+    const packageJsonPath = this.fs.join(root, "package.json");
+
+    if (!(await this.fs.exists(packageJsonPath))) {
+      const content = this.generatePackageJsonContent(modes);
+      await this.writePackageJson(root, content);
+      return content;
+    }
+
+    const packageJson = await this.readPackageJson(root);
+    const newContent = this.generatePackageJsonContent(modes);
+
+    packageJson.type = "module";
+    packageJson.dependencies ??= {};
+    packageJson.devDependencies ??= {};
+    packageJson.scripts ??= {};
+
+    Object.assign(packageJson.dependencies, newContent.dependencies);
+    Object.assign(packageJson.devDependencies, newContent.devDependencies);
+    Object.assign(packageJson.scripts, newContent.scripts);
+
+    await this.writePackageJson(root, packageJson);
+    return packageJson;
+  }
+
+  public generatePackageJsonContent(modes: DependencyModes): {
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts: Record<string, string>;
+    type: "module";
+  } {
+    const dependencies: Record<string, string> = {
+      alepha: `^${version}`,
+    };
+
+    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.admin) {
+      dependencies["@alepha/ui"] = `^${version}`;
+      modes.web = true;
+    }
+
+    if (modes.web) {
+      dependencies["@alepha/react"] = `^${version}`;
+      dependencies.react = "^19.2.0";
+      dependencies["react-dom"] = "^19.2.0";
+      devDependencies["@types/react"] = "^19.2.0";
+    }
+
+    return {
+      type: "module",
+      dependencies,
+      devDependencies,
+      scripts,
+    };
+  }
+
+  // ===========================================
+  // Helper methods
+  // ===========================================
+
+  protected async removeFiles(root: string, files: string[]): Promise<void> {
+    await Promise.all(
+      files.map((file) =>
+        this.fs.rm(this.fs.join(root, file), { force: true, recursive: true }),
+      ),
+    );
+  }
+}
+
+export interface DependencyModes {
+  web?: boolean;
+  admin?: boolean;
+  expo?: boolean;
+}

package/src/cli/services/ProjectScaffolder.ts

@@ -0,0 +1,306 @@
+import { basename, dirname } from "node:path";
+import { $inject } from "alepha";
+import { FileSystemProvider } from "alepha/file";
+import { $logger } from "alepha/logger";
+import { apiHelloControllerTs } from "../assets/apiHelloControllerTs.ts";
+import { apiIndexTs } from "../assets/apiIndexTs.ts";
+import { biomeJson } from "../assets/biomeJson.ts";
+import { type ClaudeMdOptions, claudeMd } from "../assets/claudeMd.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 { mainServerTs } from "../assets/mainServerTs.ts";
+import { tsconfigJson } from "../assets/tsconfigJson.ts";
+import { webAppRouterTs } from "../assets/webAppRouterTs.ts";
+import { webHelloComponentTsx } from "../assets/webHelloComponentTsx.ts";
+import { webIndexTs } from "../assets/webIndexTs.ts";
+import {
+  type DependencyModes,
+  PackageManagerUtils,
+} from "./PackageManagerUtils.ts";
+
+/**
+ * Service for scaffolding new Alepha projects.
+ *
+ * Handles creation of:
+ * - Project structure (src/api, src/web)
+ * - Configuration files (tsconfig, biome, editorconfig)
+ * - Entry points (main.server.ts, main.browser.ts)
+ * - Example code (HelloController, Hello component)
+ */
+export class ProjectScaffolder {
+  protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly pm = $inject(PackageManagerUtils);
+
+  /**
+   * Get the app name from the directory name.
+   *
+   * Converts the directory name to a valid module name:
+   * - Converts to lowercase
+   * - Replaces spaces, dashes, underscores with nothing
+   * - Falls back to "app" if empty
+   */
+  public getAppName(root: string): string {
+    const dirName = basename(root);
+    const appName = dirName.toLowerCase().replace(/[\s\-_]/g, "");
+    return appName || "app";
+  }
+
+  /**
+   * Ensure all configuration files exist.
+   */
+  public async ensureConfig(
+    root: string,
+    opts: {
+      packageJson?: boolean | DependencyModes;
+      tsconfigJson?: boolean;
+      indexHtml?: boolean;
+      biomeJson?: boolean;
+      editorconfig?: boolean;
+      claudeMd?: boolean | ClaudeMdOptions;
+    },
+  ): Promise<void> {
+    const tasks: Promise<void>[] = [];
+
+    if (opts.packageJson) {
+      tasks.push(
+        this.pm
+          .ensurePackageJson(
+            root,
+            typeof opts.packageJson === "boolean" ? {} : opts.packageJson,
+          )
+          .then(() => {}),
+      );
+    }
+    if (opts.tsconfigJson) {
+      tasks.push(this.ensureTsConfig(root));
+    }
+    if (opts.indexHtml) {
+      tasks.push(this.ensureReactProject(root));
+    }
+    if (opts.biomeJson) {
+      tasks.push(this.ensureBiomeConfig(root));
+    }
+    if (opts.editorconfig) {
+      tasks.push(this.ensureEditorConfig(root));
+    }
+    if (opts.claudeMd) {
+      tasks.push(
+        this.ensureClaudeMd(
+          root,
+          typeof opts.claudeMd === "boolean" ? {} : opts.claudeMd,
+        ),
+      );
+    }
+
+    await Promise.all(tasks);
+  }
+
+  // ===========================================
+  // Config Files
+  // ===========================================
+
+  public async ensureTsConfig(root: string): Promise<void> {
+    // Check if tsconfig.json exists in current or parent directories
+    if (await this.existsInParents(root, "tsconfig.json")) {
+      return;
+    }
+    await this.fs.writeFile(this.fs.join(root, "tsconfig.json"), tsconfigJson);
+  }
+
+  public async ensureBiomeConfig(root: string): Promise<void> {
+    await this.ensureFileIfNotExists(root, "biome.json", biomeJson);
+  }
+
+  public async ensureEditorConfig(root: string): Promise<void> {
+    await this.ensureFileIfNotExists(root, ".editorconfig", editorconfig);
+  }
+
+  public async ensureClaudeMd(
+    root: string,
+    options: ClaudeMdOptions = {},
+  ): Promise<void> {
+    const path = this.fs.join(root, "CLAUDE.md");
+    if (!(await this.fs.exists(path))) {
+      await this.fs.writeFile(path, claudeMd(options));
+    }
+  }
+
+  // ===========================================
+  // API Project Structure
+  // ===========================================
+
+  /**
+   * Ensure src/main.server.ts exists with full API structure.
+   *
+   * Creates:
+   * - src/main.server.ts (entry point)
+   * - src/api/index.ts (API module)
+   * - src/api/controllers/HelloController.ts (example controller)
+   */
+  public async ensureApiProject(root: string): Promise<void> {
+    const srcDir = this.fs.join(root, "src");
+
+    // Don't overwrite existing content
+    if (await this.fs.exists(srcDir)) {
+      const files = await this.fs.ls(srcDir);
+      if (files.length > 0) return;
+    }
+
+    const appName = this.getAppName(root);
+
+    // Create directories
+    await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), {
+      recursive: true,
+    });
+
+    // Create files
+    await this.fs.writeFile(
+      this.fs.join(srcDir, "main.server.ts"),
+      mainServerTs(),
+    );
+    await this.fs.writeFile(
+      this.fs.join(srcDir, "api/index.ts"),
+      apiIndexTs({ appName }),
+    );
+    await this.fs.writeFile(
+      this.fs.join(srcDir, "api/controllers/HelloController.ts"),
+      apiHelloControllerTs(),
+    );
+  }
+
+  // ===========================================
+  // React Project Structure
+  // ===========================================
+
+  /**
+   * Ensure full React project structure exists.
+   *
+   * Creates:
+   * - index.html
+   * - src/main.server.ts, src/main.browser.ts
+   * - src/api/index.ts, src/api/controllers/HelloController.ts
+   * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
+   */
+  public async ensureReactProject(root: string): Promise<void> {
+    if (await this.fs.exists(this.fs.join(root, "index.html"))) {
+      return;
+    }
+
+    const appName = this.getAppName(root);
+
+    // Create directories
+    await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), {
+      recursive: true,
+    });
+    await this.fs.mkdir(this.fs.join(root, "src/web/components"), {
+      recursive: true,
+    });
+
+    // index.html
+    await this.fs.writeFile(
+      this.fs.join(root, "index.html"),
+      indexHtml("src/main.browser.ts"),
+    );
+
+    // API structure
+    await this.ensureFileIfNotExists(
+      root,
+      "src/api/index.ts",
+      apiIndexTs({ appName }),
+    );
+    await this.ensureFileIfNotExists(
+      root,
+      "src/api/controllers/HelloController.ts",
+      apiHelloControllerTs(),
+    );
+    await this.ensureFileIfNotExists(
+      root,
+      "src/main.server.ts",
+      mainServerTs({ react: true }),
+    );
+
+    // Web structure
+    await this.ensureFileIfNotExists(
+      root,
+      "src/web/index.ts",
+      webIndexTs({ appName }),
+    );
+    await this.ensureFileIfNotExists(
+      root,
+      "src/web/AppRouter.ts",
+      webAppRouterTs(),
+    );
+    await this.ensureFileIfNotExists(
+      root,
+      "src/web/components/Hello.tsx",
+      webHelloComponentTsx(),
+    );
+    await this.ensureFileIfNotExists(
+      root,
+      "src/main.browser.ts",
+      mainBrowserTs(),
+    );
+  }
+
+  // ===========================================
+  // Test Directory
+  // ===========================================
+
+  /**
+   * Ensure test directory exists with a dummy test file.
+   */
+  public async ensureTestDir(root: string): Promise<void> {
+    const testDir = this.fs.join(root, "test");
+    const dummyPath = this.fs.join(testDir, "dummy.spec.ts");
+
+    if (!(await this.fs.exists(testDir))) {
+      await this.fs.mkdir(testDir, { recursive: true });
+      await this.fs.writeFile(dummyPath, dummySpecTs());
+      return;
+    }
+
+    const files = await this.fs.ls(testDir);
+    if (files.length === 0) {
+      await this.fs.writeFile(dummyPath, dummySpecTs());
+    }
+  }
+
+  // ===========================================
+  // Helpers
+  // ===========================================
+
+  protected async ensureFileIfNotExists(
+    root: string,
+    relativePath: string,
+    content: string,
+  ): Promise<void> {
+    const fullPath = this.fs.join(root, relativePath);
+    if (!(await this.fs.exists(fullPath))) {
+      await this.fs.writeFile(fullPath, content);
+    }
+  }
+
+  /**
+   * Check if a file exists in the given directory or any parent directory.
+   */
+  protected async existsInParents(
+    root: string,
+    filename: string,
+  ): Promise<boolean> {
+    let current = root;
+    while (true) {
+      if (await this.fs.exists(this.fs.join(current, filename))) {
+        return true;
+      }
+      const parent = dirname(current);
+      if (parent === current) {
+        // Reached filesystem root
+        return false;
+      }
+      current = parent;
+    }
+  }
+}

package/src/command/helpers/Runner.spec.ts

@@ -109,7 +109,7 @@ describe("Runner", () => {
     await runner.run(`echo "Task 1"`);
     await runner.run("A slightly longer task name", () => {});
 
-    runner.summary();
+    runner.end();
 
     const logs = mockLogger.logs
       .slice(4)
@@ -118,7 +118,7 @@ describe("Runner", () => {
   });
 
   test("summary() should not print a table if no tasks were run", () => {
-    runner.summary();
+    runner.end();
 
     const logs = mockLogger.logs.map((l) => l.message);
     expect(logs.length).toBe(0);

package/src/command/helpers/Runner.ts

@@ -20,6 +20,11 @@ export interface RunOptions {
    * Rename the command for logging purposes.
    */
   alias?: string;
+
+  /**
+   * Root directory to execute the command in.
+   */
+  root?: string;
 }
 
 export interface RunnerMethod {
@@ -73,11 +78,14 @@ export class Runner {
 
       this.firstTaskStarted = true;
 
+      const root =
+        typeof options === "object" && options.root ? options.root : undefined;
+
       if (Array.isArray(cmd)) {
         return await this.execute(
           cmd.map((it) =>
             typeof it === "string"
-              ? { name: it, handler: () => this.exec(it) }
+              ? { name: it, handler: () => this.exec(it, { root }) }
               : it,
           ),
         );
@@ -89,7 +97,7 @@ export class Runner {
         typeof options === "function"
           ? options
           : typeof cmd === "string"
-            ? () => this.exec(cmd)
+            ? () => this.exec(cmd, { root })
             : cmd.handler;
 
       return await this.execute({
@@ -140,11 +148,15 @@ export class Runner {
     return runFn;
   }
 
-  protected async exec(cmd: string): Promise<string> {
+  protected async exec(
+    cmd: string,
+    opts: { root?: string } = {},
+  ): Promise<string> {
     return await new Promise<string>((resolve, reject) => {
       exec(
         cmd,
         {
+          cwd: opts.root,
           env: {
             ...process.env,
             LOG_FORMAT: "pretty",
@@ -179,7 +191,7 @@ export class Runner {
   /**
    * Prints a summary of all executed tasks and their durations.
    */
-  public summary(): void {
+  public end(): void {
     if (this.useDynamicLogger && this.firstTaskStarted) {
       this.prettyPrint.endCommand();
       return;

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

@@ -105,12 +105,6 @@ export interface CommandPrimitiveOptions<
    */
   args?: A;
 
-  /**
-   * If false, skip summary message at the end of the command execution.
-   * Summary will display only if ({ run }) method calls were made.
-   */
-  summary?: boolean;
-
   /**
    * Marks this command as the root command.
    * Equivalent to setting name to an empty string "".

package/src/command/providers/CliProvider.ts

@@ -237,9 +237,7 @@ export class CliProvider {
         await hook.options.handler(args as CommandHandlerArgs<TObject>);
       }
 
-      if (command.options.summary !== false) {
-        runner.summary();
-      }
+      runner.end();
 
       this.log.debug(`Command '${command.name}' executed successfully.`);
     });