alepha 0.15.1 → 0.15.2

package/src/cli/services/PackageManagerUtils.ts

@@ -1,9 +1,37 @@
 import { $inject, Alepha } from "alepha";
 import type { RunnerMethod } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import alephaPackageJson from "alepha/package.json" with { type: "json" };
+import { FileSystemProvider } from "alepha/system";
 import { version } from "../version.ts";
 
+/**
+ * Context information about a workspace root.
+ * Used when initializing a package inside a monorepo.
+ */
+export interface WorkspaceContext {
+  /**
+   * Whether we're inside a workspace package.
+   */
+  isPackage: boolean;
+  /**
+   * The workspace root directory (e.g., ../.. from packages/my-pkg).
+   */
+  workspaceRoot: string | null;
+  /**
+   * Package manager detected at workspace root.
+   */
+  packageManager: "yarn" | "pnpm" | "npm" | "bun" | null;
+  /**
+   * Config files present at workspace root.
+   */
+  config: {
+    biomeJson: boolean;
+    editorconfig: boolean;
+    tsconfigJson: boolean;
+  };
+}
+
 /**
  * Utility service for package manager operations.
  *
@@ -23,12 +51,9 @@ export class PackageManagerUtils {
    */
   public async getPackageManager(
     root: string,
-    flags?: { yarn?: boolean; pnpm?: boolean; npm?: boolean; bun?: boolean },
+    pm?: "yarn" | "pnpm" | "npm" | "bun",
   ): 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 (pm) return pm;
     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";
@@ -37,6 +62,60 @@ export class PackageManagerUtils {
     return "npm";
   }
 
+  /**
+   * Detect workspace context when inside a monorepo package.
+   *
+   * Checks if we're inside a workspace package (e.g., packages/my-pkg or apps/my-app)
+   * by looking 2 levels up for workspace indicators like lockfiles and config files.
+   *
+   * @param root - The current package directory
+   * @returns Workspace context with root path, PM, and config presence
+   */
+  public async getWorkspaceContext(root: string): Promise<WorkspaceContext> {
+    // Workspace root is 2 levels up (e.g., packages/my-pkg → ..)
+    const workspaceRoot = this.fs.join(root, "..", "..");
+
+    // Check for lockfiles to detect PM
+    const [hasYarnLock, hasPnpmLock, hasNpmLock, hasBunLock] =
+      await Promise.all([
+        this.fs.exists(this.fs.join(workspaceRoot, "yarn.lock")),
+        this.fs.exists(this.fs.join(workspaceRoot, "pnpm-lock.yaml")),
+        this.fs.exists(this.fs.join(workspaceRoot, "package-lock.json")),
+        this.fs.exists(this.fs.join(workspaceRoot, "bun.lock")),
+      ]);
+
+    // Check for config files
+    const [hasBiome, hasEditorConfig, hasTsConfig, hasWorkspacePackageJson] =
+      await Promise.all([
+        this.fs.exists(this.fs.join(workspaceRoot, "biome.json")),
+        this.fs.exists(this.fs.join(workspaceRoot, ".editorconfig")),
+        this.fs.exists(this.fs.join(workspaceRoot, "tsconfig.json")),
+        this.fs.exists(this.fs.join(workspaceRoot, "package.json")),
+      ]);
+
+    // Determine if this looks like a workspace root
+    const hasLockfile = hasYarnLock || hasPnpmLock || hasNpmLock || hasBunLock;
+    const isPackage = hasLockfile && hasWorkspacePackageJson;
+
+    // Detect package manager from lockfile
+    let packageManager: "yarn" | "pnpm" | "npm" | "bun" | null = null;
+    if (hasYarnLock) packageManager = "yarn";
+    else if (hasPnpmLock) packageManager = "pnpm";
+    else if (hasBunLock) packageManager = "bun";
+    else if (hasNpmLock) packageManager = "npm";
+
+    return {
+      isPackage,
+      workspaceRoot: isPackage ? workspaceRoot : null,
+      packageManager,
+      config: {
+        biomeJson: hasBiome,
+        editorconfig: hasEditorConfig,
+        tsconfigJson: hasTsConfig,
+      },
+    };
+  }
+
   /**
    * Get the install command for a package.
    */
@@ -98,12 +177,17 @@ export class PackageManagerUtils {
 
   /**
    * Install a dependency if it's missing from the project.
+   * Optionally checks workspace root for the dependency in monorepo setups.
    */
   public async ensureDependency(
     root: string,
     packageName: string,
     options: {
       dev?: boolean;
+      /**
+       * Also check workspace root for the dependency (for monorepo setups).
+       */
+      checkWorkspace?: boolean;
       run?: RunnerMethod;
       exec?: (
         cmd: string,
@@ -111,13 +195,27 @@ export class PackageManagerUtils {
       ) => Promise<void>;
     } = {},
   ): Promise<void> {
-    const { dev = true } = options;
+    const { dev = true, checkWorkspace = false } = options;
 
+    // Check current package
     if (await this.hasDependency(root, packageName)) {
       this.log.debug(`Dependency '${packageName}' is already installed`);
       return;
     }
 
+    // Check workspace root (for monorepo setups)
+    if (checkWorkspace) {
+      const workspace = await this.getWorkspaceContext(root);
+      if (workspace.workspaceRoot) {
+        if (await this.hasDependency(workspace.workspaceRoot, packageName)) {
+          this.log.debug(
+            `Dependency '${packageName}' is already installed in workspace root`,
+          );
+          return;
+        }
+      }
+    }
+
     const cmd = await this.getInstallCommand(root, packageName, dev);
 
     if (options.run) {
@@ -254,12 +352,22 @@ export class PackageManagerUtils {
     scripts: Record<string, string>;
     type: "module";
   } {
+    const alephaDeps = alephaPackageJson.devDependencies;
+
     const dependencies: Record<string, string> = {
       alepha: `^${version}`,
     };
 
     const devDependencies: Record<string, string> = {};
 
+    // Add biome/vitest only if not a workspace package (workspace root has them)
+    if (!modes.isPackage) {
+      devDependencies["@biomejs/biome"] = alephaDeps["@biomejs/biome"];
+      if (modes.test) {
+        devDependencies.vitest = alephaDeps.vitest;
+      }
+    }
+
     const scripts: Record<string, string> = {
       dev: "alepha dev",
       build: "alepha build",
@@ -268,16 +376,19 @@ export class PackageManagerUtils {
       verify: "alepha verify",
     };
 
+    if (modes.test) {
+      scripts.test = "vitest run";
+    }
+
     if (modes.ui) {
       dependencies["@alepha/ui"] = `^${version}`;
       modes.react = true;
     }
 
     if (modes.react) {
-      dependencies["@alepha/react"] = `^${version}`;
-      dependencies.react = "^19.2.0";
-      dependencies["react-dom"] = "^19.2.0";
-      devDependencies["@types/react"] = "^19.2.0";
+      dependencies.react = alephaDeps.react;
+      dependencies["react-dom"] = alephaDeps["react-dom"];
+      devDependencies["@types/react"] = alephaDeps["@types/react"];
     }
 
     return {
@@ -305,4 +416,9 @@ export interface DependencyModes {
   react?: boolean;
   ui?: boolean;
   expo?: boolean;
+  test?: boolean;
+  /**
+   * Skip biome/vitest when inside a workspace package (they're at root).
+   */
+  isPackage?: boolean;
 }

package/src/cli/services/ProjectScaffolder.ts

@@ -1,20 +1,26 @@
 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 { mainBrowserTs } from "../assets/mainBrowserTs.ts";
-import { mainCss } from "../assets/mainCss.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 { FileSystemProvider } from "alepha/system";
+import {
+  type AgentMdOptions,
+  type AgentMdType,
+  agentMd,
+} from "../templates/agentMd.ts";
+import { apiHelloControllerTs } from "../templates/apiHelloControllerTs.ts";
+import { apiIndexTs } from "../templates/apiIndexTs.ts";
+import { biomeJson } from "../templates/biomeJson.ts";
+import { dummySpecTs } from "../templates/dummySpecTs.ts";
+import { editorconfig } from "../templates/editorconfig.ts";
+import { gitignore } from "../templates/gitignore.ts";
+import { mainBrowserTs } from "../templates/mainBrowserTs.ts";
+import { mainCss } from "../templates/mainCss.ts";
+import { mainServerTs } from "../templates/mainServerTs.ts";
+import { tsconfigJson } from "../templates/tsconfigJson.ts";
+import { webAppRouterTs } from "../templates/webAppRouterTs.ts";
+import { webHelloComponentTsx } from "../templates/webHelloComponentTsx.ts";
+import { webIndexTs } from "../templates/webIndexTs.ts";
+import { AlephaCliUtils } from "./AlephaCliUtils.ts";
 import {
   type DependencyModes,
   PackageManagerUtils,
@@ -33,6 +39,7 @@ export class ProjectScaffolder {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly pm = $inject(PackageManagerUtils);
+  protected readonly utils = $inject(AlephaCliUtils);
 
   /**
    * Get the app name from the directory name.
@@ -55,16 +62,20 @@ export class ProjectScaffolder {
     root: string,
     opts: {
       force?: boolean;
+      /**
+       * Check workspace root for existing config files.
+       */
+      checkWorkspace?: boolean;
       packageJson?: boolean | DependencyModes;
       tsconfigJson?: boolean;
-      indexHtml?: boolean;
       biomeJson?: boolean;
       editorconfig?: boolean;
-      claudeMd?: boolean | ClaudeMdOptions;
+      agentMd?: false | (AgentMdOptions & { type: AgentMdType });
     },
   ): Promise<void> {
     const tasks: Promise<void>[] = [];
     const force = opts.force ?? false;
+    const checkWorkspace = opts.checkWorkspace ?? false;
 
     if (opts.packageJson) {
       tasks.push(
@@ -79,24 +90,14 @@ export class ProjectScaffolder {
     if (opts.tsconfigJson) {
       tasks.push(this.ensureTsConfig(root, { force }));
     }
-    if (opts.indexHtml) {
-      tasks.push(this.ensureReactProject(root, { force }));
-    }
     if (opts.biomeJson) {
-      tasks.push(this.ensureBiomeConfig(root, { force }));
+      tasks.push(this.ensureBiomeConfig(root, { force, checkWorkspace }));
     }
     if (opts.editorconfig) {
-      tasks.push(this.ensureEditorConfig(root, { force }));
+      tasks.push(this.ensureEditorConfig(root, { force, checkWorkspace }));
     }
-    if (opts.claudeMd) {
-      tasks.push(
-        this.ensureClaudeMd(
-          root,
-          typeof opts.claudeMd === "boolean"
-            ? { force }
-            : { ...opts.claudeMd, force },
-        ),
-      );
+    if (opts.agentMd) {
+      tasks.push(this.ensureAgentMd(root, { ...opts.agentMd, force }));
     }
 
     await Promise.all(tasks);
@@ -122,23 +123,95 @@ export class ProjectScaffolder {
 
   public async ensureBiomeConfig(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { force?: boolean; checkWorkspace?: boolean } = {},
   ): Promise<void> {
+    if (
+      !opts.force &&
+      opts.checkWorkspace &&
+      (await this.existsInParents(root, "biome.json"))
+    ) {
+      return;
+    }
     await this.ensureFile(root, "biome.json", biomeJson(), opts.force);
   }
 
   public async ensureEditorConfig(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { force?: boolean; checkWorkspace?: boolean } = {},
   ): Promise<void> {
+    if (
+      !opts.force &&
+      opts.checkWorkspace &&
+      (await this.existsInParents(root, ".editorconfig"))
+    ) {
+      return;
+    }
     await this.ensureFile(root, ".editorconfig", editorconfig(), opts.force);
   }
 
-  public async ensureClaudeMd(
+  /**
+   * Ensure git repository is initialized with .gitignore.
+   *
+   * @returns true if git was initialized, false if already exists or git unavailable
+   */
+  public async ensureGitRepo(
     root: string,
-    options: ClaudeMdOptions & { force?: boolean } = {},
+    opts: { force?: boolean } = {},
+  ): Promise<boolean> {
+    const gitDir = this.fs.join(root, ".git");
+
+    // Skip if .git already exists
+    if (!opts.force && (await this.fs.exists(gitDir))) {
+      return false;
+    }
+
+    // Check if git is available
+    const hasGit = await this.utils.isInstalledAsync("git");
+    if (!hasGit) {
+      return false;
+    }
+
+    // Initialize git repository
+    await this.utils.exec("git init", { root, global: true });
+
+    // Write .gitignore
+    await this.ensureFile(root, ".gitignore", gitignore(), opts.force);
+
+    return true;
+  }
+
+  public async ensureAgentMd(
+    root: string,
+    options: AgentMdOptions & { type: AgentMdType; force?: boolean },
   ): Promise<void> {
-    await this.ensureFile(root, "CLAUDE.md", claudeMd(options), options.force);
+    const filename = options.type === "claude" ? "CLAUDE.md" : "AGENTS.md";
+    await this.ensureFile(
+      root,
+      filename,
+      agentMd(options.type, options),
+      options.force,
+    );
+  }
+
+  // ===========================================
+  // Minimal Project Structure
+  // ===========================================
+
+  /**
+   * Ensure src/main.server.ts exists with correct module imports.
+   */
+  public async ensureMainServerTs(
+    root: string,
+    opts: { api?: boolean; react?: boolean; force?: boolean } = {},
+  ): Promise<void> {
+    const srcDir = this.fs.join(root, "src");
+    await this.fs.mkdir(srcDir, { recursive: true });
+    await this.ensureFile(
+      srcDir,
+      "main.server.ts",
+      mainServerTs({ api: opts.api, react: opts.react }),
+      opts.force,
+    );
   }
 
   // ===========================================
@@ -146,10 +219,9 @@ export class ProjectScaffolder {
   // ===========================================
 
   /**
-   * Ensure src/main.server.ts exists with full API structure.
+   * Ensure API module structure exists.
    *
    * Creates:
-   * - src/main.server.ts (entry point)
    * - src/api/index.ts (API module)
    * - src/api/controllers/HelloController.ts (example controller)
    */
@@ -157,14 +229,6 @@ export class ProjectScaffolder {
     root: string,
     opts: { force?: boolean } = {},
   ): Promise<void> {
-    const srcDir = this.fs.join(root, "src");
-
-    // Don't overwrite existing content unless force is set
-    if (!opts.force && (await this.fs.exists(srcDir))) {
-      const files = await this.fs.ls(srcDir);
-      if (files.length > 0) return;
-    }
-
     const appName = this.getAppName(root);
 
     // Create directories
@@ -173,67 +237,48 @@ export class ProjectScaffolder {
     });
 
     // Create files
-    await this.ensureFile(srcDir, "main.server.ts", mainServerTs(), opts.force);
     await this.ensureFile(
-      srcDir,
-      "api/index.ts",
+      root,
+      "src/api/index.ts",
       apiIndexTs({ appName }),
       opts.force,
     );
     await this.ensureFile(
-      srcDir,
-      "api/controllers/HelloController.ts",
+      root,
+      "src/api/controllers/HelloController.ts",
       apiHelloControllerTs(),
       opts.force,
     );
   }
 
   // ===========================================
-  // React Project Structure
+  // Web Project Structure
   // ===========================================
 
   /**
-   * Ensure full React project structure exists.
+   * Ensure web/React project structure exists.
    *
    * Creates:
-   * - src/main.server.ts, src/main.browser.ts
-   * - src/api/index.ts, src/api/controllers/HelloController.ts
+   * - src/main.browser.ts
+   * - src/main.css
    * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
    */
-  public async ensureReactProject(
+  public async ensureWebProject(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { api?: boolean; ui?: boolean; force?: boolean } = {},
   ): Promise<void> {
     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,
     });
 
     // src/main.css
-    await this.ensureFile(root, "src/main.css", mainCss(), opts.force);
-
-    // API structure
-    await this.ensureFile(
-      root,
-      "src/api/index.ts",
-      apiIndexTs({ appName }),
-      opts.force,
-    );
-    await this.ensureFile(
-      root,
-      "src/api/controllers/HelloController.ts",
-      apiHelloControllerTs(),
-      opts.force,
-    );
     await this.ensureFile(
       root,
-      "src/main.server.ts",
-      mainServerTs({ react: true }),
+      "src/main.css",
+      mainCss({ ui: opts.ui }),
       opts.force,
     );
 
@@ -247,7 +292,7 @@ export class ProjectScaffolder {
     await this.ensureFile(
       root,
       "src/web/AppRouter.ts",
-      webAppRouterTs(),
+      webAppRouterTs({ api: opts.api, ui: opts.ui }),
       opts.force,
     );
     await this.ensureFile(

package/src/cli/services/ViteUtils.ts

@@ -0,0 +1,82 @@
+import { $hook, $inject, type Alepha, AlephaError } from "alepha";
+import { importVite } from "alepha/vite";
+import type { InlineConfig, ViteDevServer } from "vite";
+import { FileSystemProvider } from "../../system/index.ts";
+import type { AppEntry } from "../providers/AppEntryProvider.ts";
+
+export class ViteUtils {
+  protected readonly fs = $inject(FileSystemProvider);
+  protected viteDevServer?: ViteDevServer;
+
+  public generateIndexHtml(entry: AppEntry): string {
+    const style = entry.style;
+    const browser = entry.browser ?? entry.server;
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>App</title>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/${browser}"></script>
+</body>
+</html>
+`.trim();
+  }
+
+  /**
+   * We need to close the Vite dev server after build is done.
+   */
+  protected onReady = $hook({
+    on: "ready",
+    priority: "last",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+
+  protected onStop = $hook({
+    on: "stop",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+
+  public async runAlepha(opts: {
+    entry: AppEntry;
+    mode: "production" | "development";
+  }): Promise<Alepha> {
+    const { createServer } = await importVite();
+
+    process.env.NODE_ENV = opts.mode;
+    process.env.ALEPHA_CLI_IMPORT = "true"; // signal Alepha App about CLI import, run(alepha) won't start server
+    process.env.LOG_LEVEL ??= "warn"; // reduce log noise
+
+    /**
+     * 01/26 Vite 7
+     * "runnerImport" doesn't work as expected here. (e.g. build docs fail)
+     * -> We still use devServer and ssrLoadModule for now.
+     * -> This is clearly a bad stuff, we need to find better way.
+     */
+    this.viteDevServer = await createServer({
+      server: { middlewareMode: true },
+      appType: "custom",
+      logLevel: "silent",
+    } satisfies InlineConfig);
+
+    await this.viteDevServer.ssrLoadModule(opts.entry.server);
+
+    const alepha: Alepha = (globalThis as any).__alepha;
+    if (!alepha) {
+      throw new AlephaError(
+        "Alepha instance not found after loading entry module",
+      );
+    }
+
+    return alepha;
+  }
+}