alepha 0.15.0 → 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.
    */
@@ -89,14 +168,26 @@ export class PackageManagerUtils {
     return this.hasDependency(root, "expo");
   }
 
+  /**
+   * Check if React is present in the project.
+   */
+  public async hasReact(root: string): Promise<boolean> {
+    return this.hasDependency(root, "react");
+  }
+
   /**
    * 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,
@@ -104,17 +195,31 @@ 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) {
-      await options.run(cmd, { alias: `installing ${packageName}`, root });
+      await options.run(cmd, { alias: `add ${packageName}`, root });
     } else if (options.exec) {
       this.log.debug(`Installing ${packageName}`);
       await options.exec(cmd, { global: true, root });
@@ -247,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",
@@ -261,16 +376,19 @@ export class PackageManagerUtils {
       verify: "alepha verify",
     };
 
-    if (modes.admin) {
+    if (modes.test) {
+      scripts.test = "vitest run";
+    }
+
+    if (modes.ui) {
       dependencies["@alepha/ui"] = `^${version}`;
-      modes.web = true;
+      modes.react = 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";
+    if (modes.react) {
+      dependencies.react = alephaDeps.react;
+      dependencies["react-dom"] = alephaDeps["react-dom"];
+      devDependencies["@types/react"] = alephaDeps["@types/react"];
     }
 
     return {
@@ -295,7 +413,12 @@ export class PackageManagerUtils {
 }
 
 export interface DependencyModes {
-  web?: boolean;
-  admin?: boolean;
+  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 { 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 { 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.
@@ -54,15 +61,21 @@ export class ProjectScaffolder {
   public async ensureConfig(
     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(
@@ -75,24 +88,16 @@ export class ProjectScaffolder {
       );
     }
     if (opts.tsconfigJson) {
-      tasks.push(this.ensureTsConfig(root));
-    }
-    if (opts.indexHtml) {
-      tasks.push(this.ensureReactProject(root));
+      tasks.push(this.ensureTsConfig(root, { force }));
     }
     if (opts.biomeJson) {
-      tasks.push(this.ensureBiomeConfig(root));
+      tasks.push(this.ensureBiomeConfig(root, { force, checkWorkspace }));
     }
     if (opts.editorconfig) {
-      tasks.push(this.ensureEditorConfig(root));
+      tasks.push(this.ensureEditorConfig(root, { force, checkWorkspace }));
     }
-    if (opts.claudeMd) {
-      tasks.push(
-        this.ensureClaudeMd(
-          root,
-          typeof opts.claudeMd === "boolean" ? {} : opts.claudeMd,
-        ),
-      );
+    if (opts.agentMd) {
+      tasks.push(this.ensureAgentMd(root, { ...opts.agentMd, force }));
     }
 
     await Promise.all(tasks);
@@ -102,30 +107,111 @@ export class ProjectScaffolder {
   // Config Files
   // ===========================================
 
-  public async ensureTsConfig(root: string): Promise<void> {
+  public async ensureTsConfig(
+    root: string,
+    opts: { force?: boolean } = {},
+  ): Promise<void> {
     // Check if tsconfig.json exists in current or parent directories
-    if (await this.existsInParents(root, "tsconfig.json")) {
+    if (!opts.force && (await this.existsInParents(root, "tsconfig.json"))) {
       return;
     }
-    await this.fs.writeFile(this.fs.join(root, "tsconfig.json"), tsconfigJson);
+    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 ensureBiomeConfig(
+    root: string,
+    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): Promise<void> {
-    await this.ensureFileIfNotExists(root, ".editorconfig", editorconfig);
+  public async ensureEditorConfig(
+    root: string,
+    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 = {},
-  ): Promise<void> {
-    const path = this.fs.join(root, "CLAUDE.md");
-    if (!(await this.fs.exists(path))) {
-      await this.fs.writeFile(path, claudeMd(options));
+    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> {
+    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,
+    );
   }
 
   // ===========================================
@@ -133,22 +219,16 @@ 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)
    */
-  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;
-    }
-
+  public async ensureApiProject(
+    root: string,
+    opts: { force?: boolean } = {},
+  ): Promise<void> {
     const appName = this.getAppName(root);
 
     // Create directories
@@ -157,91 +237,75 @@ export class ProjectScaffolder {
     });
 
     // 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"),
+    await this.ensureFile(
+      root,
+      "src/api/index.ts",
       apiIndexTs({ appName }),
+      opts.force,
     );
-    await this.fs.writeFile(
-      this.fs.join(srcDir, "api/controllers/HelloController.ts"),
+    await this.ensureFile(
+      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:
-   * - index.html
-   * - 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(root: string): Promise<void> {
-    if (await this.fs.exists(this.fs.join(root, "index.html"))) {
-      return;
-    }
-
+  public async ensureWebProject(
+    root: string,
+    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,
     });
 
-    // index.html
-    await this.fs.writeFile(
-      this.fs.join(root, "index.html"),
-      indexHtml("src/main.browser.ts"),
-    );
-
-    // API structure
-    await this.ensureFileIfNotExists(
+    // src/main.css
+    await this.ensureFile(
       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 }),
+      "src/main.css",
+      mainCss({ ui: opts.ui }),
+      opts.force,
     );
 
     // Web structure
-    await this.ensureFileIfNotExists(
+    await this.ensureFile(
       root,
       "src/web/index.ts",
       webIndexTs({ appName }),
+      opts.force,
     );
-    await this.ensureFileIfNotExists(
+    await this.ensureFile(
       root,
       "src/web/AppRouter.ts",
-      webAppRouterTs(),
+      webAppRouterTs({ api: opts.api, ui: opts.ui }),
+      opts.force,
     );
-    await this.ensureFileIfNotExists(
+    await this.ensureFile(
       root,
       "src/web/components/Hello.tsx",
       webHelloComponentTsx(),
+      opts.force,
     );
-    await this.ensureFileIfNotExists(
+    await this.ensureFile(
       root,
       "src/main.browser.ts",
       mainBrowserTs(),
+      opts.force,
     );
   }
 
@@ -272,13 +336,17 @@ export class ProjectScaffolder {
   // Helpers
   // ===========================================
 
-  protected async ensureFileIfNotExists(
+  /**
+   * Write a file, optionally overriding if it exists.
+   */
+  protected async ensureFile(
     root: string,
     relativePath: string,
     content: string,
+    force?: boolean,
   ): Promise<void> {
     const fullPath = this.fs.join(root, relativePath);
-    if (!(await this.fs.exists(fullPath))) {
+    if (force || !(await this.fs.exists(fullPath))) {
       await this.fs.writeFile(fullPath, content);
     }
   }