alepha 0.15.1 → 0.15.2

package/src/cli/commands/init.ts

@@ -1,6 +1,6 @@
 import { $inject, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
@@ -29,23 +29,32 @@ export class InitCommand {
       agent: t.optional(
         t.boolean({
           aliases: ["a"],
-          description: "Add CLAUDE.md for Claude Code AI assistant",
+          description:
+            "Add AI agent instructions (CLAUDE.md if claude CLI installed, else AGENTS.md)",
+        }),
+      ),
+      pm: t.optional(
+        t.enum(["yarn", "npm", "pnpm", "bun"], {
+          description: "Package manager to use",
+        }),
+      ),
+      // choose which modules to scaffold
+      api: t.optional(
+        t.boolean({
+          description: "Include API module structure (src/api/)",
         }),
       ),
-      // 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({
           aliases: ["r"],
-          description: "Include Alepha React dependencies",
+          description: "Include React dependencies and web module (src/web/)",
         }),
       ),
       ui: t.optional(
-        t.boolean({ description: "Include Alepha UI dependencies" }),
+        t.boolean({
+          description:
+            "Include @alepha/ui (components, auth portal, admin portal)",
+        }),
       ),
       test: t.optional(
         t.boolean({ description: "Include Vitest and create test directory" }),
@@ -58,15 +67,25 @@ export class InitCommand {
       ),
     }),
     handler: async ({ run, flags, root, args }) => {
-      if (flags.react) {
-        flags.ui = true;
-      }
-
       if (args) {
         root = this.fs.join(root, args);
         await this.fs.mkdir(root);
       }
 
+      if (flags.ui) {
+        flags.react = true;
+      }
+
+      // Detect workspace context (are we inside packages/ or apps/ of a monorepo?)
+      const workspace = await this.pm.getWorkspaceContext(root);
+
+      // Detect agent type: claude CLI → CLAUDE.md, else → AGENTS.md
+      let agentType: "claude" | "agents" | false = false;
+      if (flags.agent) {
+        const hasClaudeCli = await this.utils.isInstalledAsync("claude");
+        agentType = hasClaudeCli ? "claude" : "agents";
+      }
+
       const isExpo = await this.pm.hasExpo(root);
 
       const force = !!flags.force;
@@ -76,69 +95,84 @@ export class InitCommand {
         handler: async () => {
           await this.scaffolder.ensureConfig(root, {
             force,
-            tsconfigJson: true,
-            packageJson: flags,
-            biomeJson: true,
-            editorconfig: true,
-            indexHtml: !!flags.react && !isExpo,
-            claudeMd: flags.agent
-              ? { react: !!flags.react, ui: !!flags.ui }
+            tsconfigJson: !workspace.config.tsconfigJson,
+            packageJson: { ...flags, isPackage: workspace.isPackage },
+            // Skip workspace-level configs if they exist at workspace root
+            biomeJson: !workspace.config.biomeJson,
+            editorconfig: !workspace.config.editorconfig,
+            agentMd: agentType
+              ? { type: agentType, react: !!flags.react, ui: !!flags.ui }
               : false,
           });
 
-          // Create API project structure if not React
-          if (!flags.react) {
+          // Create project structure based on flags
+          await this.scaffolder.ensureMainServerTs(root, {
+            api: !!flags.api,
+            react: !!flags.react && !isExpo,
+            force,
+          });
+          if (flags.api) {
             await this.scaffolder.ensureApiProject(root, { force });
           }
+          if (flags.react && !isExpo) {
+            await this.scaffolder.ensureWebProject(root, {
+              api: !!flags.api,
+              ui: !!flags.ui,
+              force,
+            });
+          }
         },
       });
 
-      // TODO: check if all alepha dependencies are same version
+      // Use workspace PM if detected, otherwise detect from current root
+      const pmName = await this.pm.getPackageManager(
+        workspace.workspaceRoot ?? root,
+        flags.pm ?? workspace.packageManager ?? undefined,
+      );
 
-      const pmName = await this.pm.getPackageManager(root, flags);
-      if (pmName === "yarn") {
-        await this.pm.ensureYarn(root);
-        await run("yarn set version stable", { root });
-      } else if (pmName === "bun") {
-        await this.pm.ensureBun(root);
-      } else if (pmName === "pnpm") {
-        await this.pm.ensurePnpm(root);
-      } else {
-        await this.pm.ensureNpm(root);
+      // Only setup PM files if not in a workspace package
+      if (!workspace.isPackage) {
+        if (pmName === "yarn") {
+          await this.pm.ensureYarn(root);
+          await run("yarn set version stable", { root });
+        } else if (pmName === "bun") {
+          await this.pm.ensureBun(root);
+        } else if (pmName === "pnpm") {
+          await this.pm.ensurePnpm(root);
+        } else {
+          await this.pm.ensureNpm(root);
+        }
       }
 
+      // Run install from workspace root if in a package, otherwise from current root
+      const installRoot = workspace.workspaceRoot ?? root;
       await run(`${pmName} install`, {
         alias: `installing dependencies with ${pmName}`,
-        root,
+        root: installRoot,
       });
 
-      if (!isExpo) {
-        await this.pm.ensureDependency(root, "vite", {
-          run,
-          exec: (cmd, opts) => this.utils.exec(cmd, opts),
-        });
-      }
-
-      await this.pm.ensureDependency(root, "@biomejs/biome", {
-        run,
-        exec: (cmd, opts) => this.utils.exec(cmd, opts),
-      });
-
-      // Install vitest and create test directory if --test flag is set
+      // Create test directory if --test flag is set (vitest is in package.json)
       if (flags.test) {
         await this.scaffolder.ensureTestDir(root);
-        await run(
-          `${pmName} ${pmName === "yarn" ? "add" : "install"} -D vitest`,
-          {
-            alias: "setup testing with Vitest",
-          },
-        );
       }
 
       await run(`${pmName} run lint`, {
         alias: "running linter",
-        root,
+        root: installRoot,
       });
+
+      // Initialize git repository if not in a workspace package
+      if (!workspace.isPackage) {
+        const gitInitialized = await this.scaffolder.ensureGitRepo(root, {
+          force,
+        });
+        if (gitInitialized) {
+          await run("git add .", {
+            alias: "staging generated files",
+            root,
+          });
+        }
+      }
     },
   });
 }

package/src/cli/commands/lint.ts

@@ -13,10 +13,16 @@ export class LintCommand {
     name: "lint",
     description: "Run linter across the codebase using Biome",
     handler: async ({ root }) => {
-      await this.scaffolder.ensureConfig(root, { biomeJson: true });
+      await this.scaffolder.ensureConfig(root, {
+        biomeJson: true,
+        checkWorkspace: true,
+      });
+
       await this.pm.ensureDependency(root, "@biomejs/biome", {
+        checkWorkspace: true,
         exec: (cmd, opts) => this.utils.exec(cmd, opts),
       });
+
       await this.utils.exec("biome check --fix");
     },
   });

package/src/cli/commands/typecheck.ts

@@ -3,11 +3,13 @@ import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
+import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
 
 export class TypecheckCommand {
   protected readonly utils = $inject(AlephaCliUtils);
   protected readonly pm = $inject(PackageManagerUtils);
   protected readonly log = $logger();
+  protected readonly scaffolder = $inject(ProjectScaffolder);
 
   /**
    * Run TypeScript type checking across the codebase with no emit.
@@ -18,10 +20,19 @@ export class TypecheckCommand {
     description: "Check TypeScript types across the codebase",
     handler: async ({ root }) => {
       this.log.info("Starting TypeScript type checking...");
+
+      await this.scaffolder.ensureConfig(root, {
+        tsconfigJson: true,
+        checkWorkspace: true,
+      });
+
       await this.pm.ensureDependency(root, "typescript", {
+        checkWorkspace: true,
         exec: (cmd, opts) => this.utils.exec(cmd, opts),
       });
+
       await this.utils.exec("tsc --noEmit");
+
       this.log.info("TypeScript type checking completed successfully.");
     },
   });

package/src/cli/providers/AppEntryProvider.ts

@@ -1,5 +1,5 @@
 import { $inject, $use, AlephaError } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { appEntryOptions } from "../atoms/appEntryOptions.ts";
 
 /**

package/src/cli/providers/ViteBuildProvider.ts

@@ -1,59 +1,17 @@
-import { $hook, $inject, type Alepha, AlephaError } from "alepha";
-import { importVite } from "alepha/vite";
-import type { InlineConfig, ViteDevServer } from "vite";
+import { $inject, type Alepha, AlephaError } from "alepha";
+import { ViteUtils } from "../services/ViteUtils.ts";
 import type { AppEntry } from "./AppEntryProvider.ts";
-import { ViteTemplateProvider } from "./ViteTemplateProvider.ts";
 
 export class ViteBuildProvider {
   protected alepha?: Alepha;
   protected appEntry?: AppEntry;
-  protected viteDevServer?: ViteDevServer;
-  protected readonly templateProvider = $inject(ViteTemplateProvider);
-
-  /**
-   * 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();
-    },
-  });
+  protected readonly viteUtils = $inject(ViteUtils);
 
   public async init(opts: { entry: AppEntry }) {
-    const { createServer } = await importVite();
-
-    process.env.ALEPHA_CLI_IMPORT = "true"; // signal Alepha App about CLI import, run(alepha) won't start server
-    process.env.NODE_ENV = "production"; // force Alepha App in production mode for getting "production" metadata
-    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",
-      );
-    }
+    const alepha = await this.viteUtils.runAlepha({
+      entry: opts.entry,
+      mode: "production",
+    });
 
     this.alepha = alepha;
     this.appEntry = opts.entry;
@@ -77,6 +35,6 @@ export class ViteBuildProvider {
     if (!this.appEntry) {
       throw new AlephaError("ViteBuildProvider not initialized");
     }
-    return this.templateProvider.generateIndexHtml(this.appEntry);
+    return this.viteUtils.generateIndexHtml(this.appEntry);
   }
 }

package/src/cli/providers/ViteDevServerProvider.ts

@@ -1,10 +1,10 @@
 import { $inject, type Alepha, AlephaError } from "alepha";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { importVite, importViteReact, viteAlephaSsrPreload } from "alepha/vite";
 import type { InlineConfig, Plugin, ViteDevServer } from "vite";
+import { ViteUtils } from "../services/ViteUtils.ts";
 import type { AppEntry } from "./AppEntryProvider.ts";
-import { ViteTemplateProvider } from "./ViteTemplateProvider.ts";
 
 export interface ViteDevServerOptions {
   /**
@@ -49,7 +49,7 @@ export interface ViteDevServerOptions {
 export class ViteDevServerProvider {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
-  protected readonly templateProvider = $inject(ViteTemplateProvider);
+  protected readonly templateProvider = $inject(ViteUtils);
   protected server!: ViteDevServer;
   protected options!: ViteDevServerOptions;
   protected alepha: Alepha | null = null;
@@ -176,6 +176,11 @@ export class ViteDevServerProvider {
     const mode = process.env.NODE_ENV || "development";
     const env = loadEnv(mode, this.options.root, "");
 
+    // Merge into process.env (only set if not already defined)
+    for (const [key, value] of Object.entries(env)) {
+      process.env[key] ??= value;
+    }
+
     process.env.NODE_ENV ??= "development";
     process.env.VITE_ALEPHA_DEV = "true";
     process.env.SERVER_HOST ??= this.options.host?.toString() ?? "localhost";
@@ -183,11 +188,6 @@ export class ViteDevServerProvider {
       this.options.port ??
         (process.env.SERVER_PORT ? Number(process.env.SERVER_PORT) : 3000),
     );
-
-    // Merge into process.env (only set if not already defined)
-    for (const [key, value] of Object.entries(env)) {
-      process.env[key] ??= value;
-    }
   }
 
   /**
@@ -299,6 +299,11 @@ export class ViteDevServerProvider {
     res: any,
     ctx: { metadata: any },
   ): Promise<boolean> {
+    // Skip if response already started
+    if (res.headersSent || res.writableEnded) {
+      return false;
+    }
+
     return new Promise((resolve) => {
       let resolved = false;
 
@@ -309,6 +314,29 @@ export class ViteDevServerProvider {
         resolve(handled);
       };
 
+      // Wrap response to prevent writes after we've resolved
+      const originalSetHeader = res.setHeader.bind(res);
+      const originalWriteHead = res.writeHead?.bind(res);
+      const originalWrite = res.write.bind(res);
+      const originalEnd = res.end.bind(res);
+
+      const guardedCall = <T>(fn: (...args: any[]) => T, ...args: any[]): T => {
+        if (resolved && !ctx.metadata.vite) {
+          // Vite didn't handle this request, silently ignore late writes
+          return undefined as T;
+        }
+        return fn(...args);
+      };
+
+      res.setHeader = (...args: any[]) =>
+        guardedCall(originalSetHeader, ...args);
+      if (originalWriteHead) {
+        res.writeHead = (...args: any[]) =>
+          guardedCall(originalWriteHead, ...args);
+      }
+      res.write = (...args: any[]) => guardedCall(originalWrite, ...args);
+      res.end = (...args: any[]) => guardedCall(originalEnd, ...args);
+
       res.on("finish", () => done(true));
       res.on("close", () => res.headersSent && done(true));
 

package/src/cli/services/AlephaCliUtils.ts

@@ -1,9 +1,12 @@
-import { spawn } from "node:child_process";
-import { $inject, Alepha, AlephaError } from "alepha";
+import { $inject, type Alepha } from "alepha";
 import { EnvUtils } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
+import { FileSystemProvider, ShellProvider } from "alepha/system";
+import {
+  type AppEntry,
+  AppEntryProvider,
+} from "../providers/AppEntryProvider.ts";
+import { ViteUtils } from "./ViteUtils.ts";
 
 /**
  * Core utility service for CLI commands.
@@ -19,6 +22,8 @@ export class AlephaCliUtils {
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly envUtils = $inject(EnvUtils);
   protected readonly boot = $inject(AppEntryProvider);
+  protected readonly shell = $inject(ShellProvider);
+  protected readonly viteUtils = $inject(ViteUtils);
 
   // ===========================================
   // Command Execution
@@ -26,6 +31,11 @@ export class AlephaCliUtils {
 
   /**
    * Execute a command with inherited stdio.
+   *
+   * @param command - The command to execute
+   * @param options.root - Working directory
+   * @param options.env - Additional environment variables
+   * @param options.global - If true, run command directly without resolving from node_modules
    */
   public async exec(
     command: string,
@@ -35,71 +45,12 @@ export class AlephaCliUtils {
       global?: boolean;
     } = {},
   ): Promise<void> {
-    const root = options.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(" ");
-
-    // find executable inside project node_modules
-    let execPath = await this.checkFileExists(
-      root,
-      `node_modules/.bin/${app}${suffix}`,
-    );
-
-    // 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}`,
-      );
-    }
-
-    // check if parent folder (monorepo) has the executable (check 3 times)
-    if (!execPath) {
-      let parentDir = this.fs.join(root, "..");
-      for (let i = 0; i < 3; i++) {
-        execPath = await this.checkFileExists(
-          parentDir,
-          `node_modules/.bin/${app}${suffix}`,
-        );
-        if (execPath) {
-          break;
-        }
-        parentDir = this.fs.join(parentDir, "..");
-      }
-    }
-
-    if (!execPath) {
-      throw new AlephaError(
-        `Could not find executable for command '${app}'. Make sure the package is installed.`,
-      );
-    }
-
-    await runExec(execPath, args);
+    await this.shell.run(command, {
+      root: options.root,
+      env: options.env,
+      resolve: !options.global,
+      capture: false,
+    });
   }
 
   /**
@@ -122,55 +73,22 @@ export class AlephaCliUtils {
     return path;
   }
 
-  /**
-   * Load Alepha instance from a server entry file.
-   */
   public async loadAlephaFromServerEntryFile(
-    rootDir?: string,
-    explicitEntry?: string,
-  ): Promise<{
-    alepha: Alepha;
-    entry: string;
-  }> {
-    process.env.ALEPHA_CLI_IMPORT = "true";
-
-    const root = rootDir ?? process.cwd();
-    let entry: string;
-
-    if (explicitEntry) {
-      // Explicit entry provided
-      entry = this.fs.join(root, explicitEntry);
-      if (!(await this.fs.exists(entry))) {
-        throw new AlephaError(
-          `Explicit server entry file "${explicitEntry}" not found.`,
-        );
-      }
+    opts: {
+      mode: "production" | "development";
+    } & ({ entry: AppEntry } | { root: string }),
+  ): Promise<Alepha> {
+    let entry: AppEntry;
+    if ("root" in opts) {
+      entry = await this.boot.getAppEntry(opts.root);
     } else {
-      // Auto-discover entry
-      const appEntry = await this.boot.getAppEntry(root);
-      entry = this.fs.join(root, appEntry.server);
-    }
-
-    delete (global as any).__alepha;
-
-    const mod = await import(entry);
-
-    this.log.debug(`Load entry: ${entry}`);
-
-    // check if alepha is correctly exported
-    if (mod.default instanceof Alepha) {
-      return { alepha: mod.default, entry };
-    }
-
-    // else, try with global variable
-    const g: any = global;
-    if (g.__alepha) {
-      return { alepha: g.__alepha, entry };
+      entry = opts.entry;
     }
 
-    throw new AlephaError(
-      `Could not find Alepha instance in entry file: ${entry}`,
-    );
+    return await this.viteUtils.runAlepha({
+      entry,
+      mode: opts.mode,
+    });
   }
 
   // ===========================================
@@ -221,13 +139,10 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
     return this.fs.exists(this.fs.join(root, path));
   }
 
-  protected async checkFileExists(
-    root: string,
-    name: string,
-  ): Promise<string | undefined> {
-    const configPath = this.fs.join(root, name);
-    if (await this.fs.exists(configPath)) {
-      return configPath;
-    }
+  /**
+   * Check if a command is installed and available in the system PATH.
+   */
+  public isInstalledAsync(cmd: string): Promise<boolean> {
+    return this.shell.isInstalled(cmd);
   }
 }