alepha 0.15.2 → 0.15.4

package/src/cli/commands/build.ts

@@ -12,7 +12,11 @@ import {
   generateVercel,
   prerenderPages,
 } from "alepha/vite";
-import { buildOptions } from "../atoms/buildOptions.ts";
+import {
+  type BuildRuntime,
+  type BuildTarget,
+  buildOptions,
+} from "../atoms/buildOptions.ts";
 import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 import { ViteBuildProvider } from "../providers/ViteBuildProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
@@ -29,6 +33,41 @@ export class BuildCommand {
   protected readonly viteBuildProvider = $inject(ViteBuildProvider);
   protected readonly options = $use(buildOptions);
 
+  /**
+   * Resolve the effective runtime based on target and explicit runtime flag.
+   *
+   * Some targets force a specific runtime:
+   * - `cloudflare` always uses `workerd`
+   * - `vercel` always uses `node`
+   * - `docker` and bare deployments respect the runtime flag
+   *
+   * @throws {AlephaError} If an incompatible runtime is specified for a target
+   */
+  protected resolveRuntime(
+    target: BuildTarget | undefined,
+    runtime: BuildRuntime | undefined,
+  ): BuildRuntime {
+    if (target === "cloudflare") {
+      if (runtime && runtime !== "workerd") {
+        throw new AlephaError(
+          `Target 'cloudflare' requires 'workerd' runtime, got '${runtime}'`,
+        );
+      }
+      return "workerd";
+    }
+
+    if (target === "vercel") {
+      if (runtime && runtime !== "node") {
+        throw new AlephaError(
+          `Target 'vercel' requires 'node' runtime, got '${runtime}'`,
+        );
+      }
+      return "node";
+    }
+
+    return runtime ?? "node";
+  }
+
   public readonly build = $command({
     name: "build",
     mode: "production",
@@ -39,19 +78,23 @@ export class BuildCommand {
           description: "Generate build stats report",
         }),
       ),
-      vercel: t.optional(
-        t.boolean({
-          description: "Generate Vercel deployment configuration",
+      target: t.optional(
+        t.enum(["bare", "docker", "vercel", "cloudflare"], {
+          aliases: ["t"],
+          description: "Deployment target",
         }),
       ),
-      cloudflare: t.optional(
-        t.boolean({
-          description: "Generate Cloudflare Workers configuration",
+      runtime: t.optional(
+        t.enum(["node", "bun", "workerd"], {
+          aliases: ["r"],
+          description: "JavaScript runtime",
         }),
       ),
-      docker: t.optional(
-        t.boolean({
-          description: "Generate Docker configuration",
+      image: t.optional(
+        t.union([t.boolean(), t.text()], {
+          aliases: ["i"],
+          description:
+            "Build Docker image. Use -i for latest, -i=<version> for specific version",
         }),
       ),
       sitemap: t.optional(
@@ -59,11 +102,6 @@ export class BuildCommand {
           description: "Generate sitemap.xml with base URL",
         }),
       ),
-      bun: t.optional(
-        t.boolean({
-          description: "Prioritize .bun.ts entry files for Bun runtime",
-        }),
-      ),
     }),
     handler: async ({ flags, run, root }) => {
       process.env.NODE_ENV = "production";
@@ -88,6 +126,22 @@ export class BuildCommand {
       const options = this.options;
       await this.utils.loadEnv(root, [".env", ".env.production"]);
 
+      // Resolve target and runtime
+      const target = flags.target ?? options.target;
+      const runtime = this.resolveRuntime(
+        target,
+        flags.runtime ?? options.runtime,
+      );
+
+      // Validate --image requires --target=docker
+      if (flags.image && target !== "docker") {
+        throw new AlephaError(
+          `Flag '--image' requires '--target=docker', got '${target ?? "bare"}'`,
+        );
+      }
+
+      this.log.trace("Build configuration", { target, runtime });
+
       const stats = flags.stats ?? options.stats ?? false;
       let template = "";
       let hasClient = false;
@@ -140,20 +194,11 @@ export class BuildCommand {
           const clientIndexPath = `${distDir}/${publicDir}/index.html`;
           const clientBuilt = await this.fs.exists(clientIndexPath);
 
+          // Set export conditions based on runtime
           const conditions: string[] = [];
-
-          // bun:
-          // - alepha
-          // - react-dom
-
-          if (flags.bun) {
+          if (runtime === "bun") {
             conditions.push("bun");
-          }
-
-          // workerd:
-          // - react-dom
-          // - postgres
-          if (options.cloudflare) {
+          } else if (runtime === "workerd") {
             conditions.push("workerd");
           }
 
@@ -204,8 +249,8 @@ export class BuildCommand {
         });
       }
 
-      // Generate deployment configurations
-      if (flags.vercel || options.vercel) {
+      // Generate deployment configuration based on target
+      if (target === "vercel") {
         await run({
           name: "add Vercel config",
           handler: () =>
@@ -217,26 +262,99 @@ export class BuildCommand {
         });
       }
 
-      if (flags.cloudflare || options.cloudflare) {
+      if (target === "cloudflare") {
         await run({
           name: "add Cloudflare config",
           handler: () =>
             generateCloudflare({
               distDir,
               config: options.cloudflare?.config,
+              alepha: alepha!,
             }),
         });
       }
 
-      if (flags.docker || options.docker) {
+      if (target === "docker") {
+        // Auto-configure Docker based on runtime
+        const dockerFrom =
+          options.docker?.from ??
+          (runtime === "bun" ? "oven/bun:alpine" : "node:24-alpine");
+        const dockerCommand =
+          options.docker?.command ?? (runtime === "bun" ? "bun" : "node");
+
         await run({
           name: "add Docker config",
           handler: () =>
             generateDocker({
               distDir,
-              ...options.docker,
+              image: dockerFrom,
+              command: dockerCommand,
             }),
         });
+
+        // Build Docker image if --image flag is provided
+        if (flags.image) {
+          const imageConfig = options.docker?.image;
+          const flagValue =
+            typeof flags.image === "string" ? flags.image : null;
+
+          let imageTag: string;
+          let version: string;
+
+          if (!flagValue) {
+            // -i (no value) → use config tag:latest
+            if (!imageConfig?.tag) {
+              throw new AlephaError(
+                "Flag '--image' requires 'build.docker.image.tag' in config",
+              );
+            }
+            version = "latest";
+            imageTag = `${imageConfig.tag}:${version}`;
+          } else if (flagValue.startsWith(":")) {
+            // -i=:1.3.4 → version only, prepend config tag
+            if (!imageConfig?.tag) {
+              throw new AlephaError(
+                "Flag '--image=:version' requires 'build.docker.image.tag' in config",
+              );
+            }
+            version = flagValue.slice(1); // remove leading ":"
+            imageTag = `${imageConfig.tag}:${version}`;
+          } else if (flagValue.includes(":")) {
+            // -i=toto:1.3.4 → full image with version
+            imageTag = flagValue;
+            version = flagValue.split(":")[1];
+          } else {
+            // -i=toto → image name without version → add :latest
+            imageTag = `${flagValue}:latest`;
+            version = "latest";
+          }
+
+          const args: string[] = [];
+
+          // Add custom args
+          if (imageConfig?.args) {
+            args.push(imageConfig.args);
+          }
+
+          // Add OCI labels if enabled
+          if (imageConfig?.oci) {
+            const revision = await this.utils.getGitRevision();
+            const created = new Date().toISOString();
+
+            args.push(
+              `--label "org.opencontainers.image.revision=${revision}"`,
+            );
+            args.push(`--label "org.opencontainers.image.created=${created}"`);
+            args.push(`--label "org.opencontainers.image.version=${version}"`);
+          }
+
+          const argsStr = args.length > 0 ? `${args.join(" ")} ` : "";
+          const dockerCmd = `docker build ${argsStr}-t ${imageTag} ${distDir}`;
+
+          await run(dockerCmd, {
+            alias: `docker build ${imageTag}`,
+          });
+        }
       }
     },
   });

package/src/cli/commands/db.ts

@@ -405,20 +405,18 @@ export class DbCommand {
         }
 
         const url = options.providerUrl;
-        if (!url.startsWith("cloudflare-d1://")) {
-          throw new AlephaError(
-            "D1 provider URL must start with 'cloudflare-d1://'.",
-          );
+        if (!url.startsWith("d1://")) {
+          throw new AlephaError("D1 provider URL must start with 'd1://'.");
         }
 
         const [, databaseId] = url
-          .replace("cloudflare-d1://", "")
-          .replace("cloudflare-d1:", "")
+          .replace("d1://", "")
+          .replace("d1:", "")
           .split(":");
 
         if (!databaseId) {
           throw new AlephaError(
-            "Database ID is missing in the D1 provider URL. Cloudflare D1 URL format: cloudflare-d1://<database_name>:<database_id>",
+            "Database ID is missing in the D1 provider URL. Cloudflare D1 URL format: d1://<database_name>:<database_id>",
           );
         }
 

package/src/cli/commands/init.spec.ts

@@ -76,16 +76,16 @@ describe("alepha init", () => {
   });
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // Agent Files (--agent flag)
+  // AI Agent Files (--ai flag)
   // ─────────────────────────────────────────────────────────────────────────────
 
-  describe("--agent flag", () => {
+  describe("--ai flag", () => {
     it("should create CLAUDE.md when claude CLI is installed", async () => {
       const { fs, shell, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
       shell.installedCommands.add("claude");
 
-      await cli.run(cmd.init, { argv: "--agent", root: "/project" });
+      await cli.run(cmd.init, { argv: "--ai", root: "/project" });
 
       expect(fs.wasWritten("/project/CLAUDE.md")).toBe(true);
       expect(fs.wasWritten("/project/AGENTS.md")).toBe(false);
@@ -95,7 +95,7 @@ describe("alepha init", () => {
       const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
 
-      await cli.run(cmd.init, { argv: "--agent", root: "/project" });
+      await cli.run(cmd.init, { argv: "--ai", root: "/project" });
 
       expect(fs.wasWritten("/project/AGENTS.md")).toBe(true);
       expect(fs.wasWritten("/project/CLAUDE.md")).toBe(false);
@@ -105,7 +105,7 @@ describe("alepha init", () => {
       const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
 
-      await cli.run(cmd.init, { argv: "--agent", root: "/project" });
+      await cli.run(cmd.init, { argv: "--ai", root: "/project" });
 
       expect(fs.wasWrittenMatching("/project/AGENTS.md", /Alepha/)).toBe(true);
       expect(fs.wasWrittenMatching("/project/AGENTS.md", /alepha lint/)).toBe(
@@ -113,7 +113,7 @@ describe("alepha init", () => {
       );
     });
 
-    it("should not create agent files without --agent flag", async () => {
+    it("should not create agent files without --ai flag", async () => {
       const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
 
@@ -180,6 +180,50 @@ describe("alepha init", () => {
       expect(shell.wasCalled("npm install")).toBe(true);
       expect(shell.wasCalled("yarn install")).toBe(false);
     });
+
+    it("should accept --pm=yarn", async () => {
+      const { fs, shell, cli, cmd, json } = createTestEnv();
+      await setupProject(fs, json);
+
+      await cli.run(cmd.init, { argv: "--pm=yarn", root: "/project" });
+
+      expect(shell.wasCalled("yarn install")).toBe(true);
+    });
+
+    it("should accept --pm=pnpm", async () => {
+      const { fs, shell, cli, cmd, json } = createTestEnv();
+      await setupProject(fs, json);
+
+      await cli.run(cmd.init, { argv: "--pm=pnpm", root: "/project" });
+
+      expect(shell.wasCalled("pnpm install")).toBe(true);
+    });
+
+    it("should accept --pm=bun", async () => {
+      const { fs, shell, cli, cmd, json } = createTestEnv();
+      await setupProject(fs, json);
+
+      await cli.run(cmd.init, { argv: "--pm=bun", root: "/project" });
+
+      expect(shell.wasCalled("bun install")).toBe(true);
+    });
+
+    it("should reject invalid --pm value", async () => {
+      const { fs, cli, cmd, json } = createTestEnv();
+      await setupProject(fs, json);
+
+      await expect(
+        cli.run(cmd.init, { argv: "--pm=invalid", root: "/project" }),
+      ).rejects.toThrowError(/Invalid flag/);
+    });
+
+    it("should show enum values in help for --pm flag", async () => {
+      const { alepha, cli, cmd } = createTestEnv();
+      await alepha.start();
+
+      // Verify printHelp works with the init command (which has an enum flag)
+      expect(() => cli.printHelp(cmd.init)).not.toThrow();
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────────

package/src/cli/commands/init.ts

@@ -26,9 +26,8 @@ export class InitCommand {
       }),
     ),
     flags: t.object({
-      agent: t.optional(
+      ai: t.optional(
         t.boolean({
-          aliases: ["a"],
           description:
             "Add AI agent instructions (CLAUDE.md if claude CLI installed, else AGENTS.md)",
         }),
@@ -56,6 +55,17 @@ export class InitCommand {
             "Include @alepha/ui (components, auth portal, admin portal)",
         }),
       ),
+      auth: t.optional(
+        t.boolean({
+          description:
+            "Include authentication (AppSecurity, $uiAuth). Implies --api --ui --react",
+        }),
+      ),
+      admin: t.optional(
+        t.boolean({
+          description: "Include admin portal ($uiAdmin). Implies --auth",
+        }),
+      ),
       test: t.optional(
         t.boolean({ description: "Include Vitest and create test directory" }),
       ),
@@ -69,9 +79,17 @@ export class InitCommand {
     handler: async ({ run, flags, root, args }) => {
       if (args) {
         root = this.fs.join(root, args);
-        await this.fs.mkdir(root);
+        await this.fs.mkdir(root, { force: true });
       }
 
+      // Flag cascading: --admin → --auth → --ui → --react, --api
+      if (flags.admin) {
+        flags.auth = true;
+      }
+      if (flags.auth) {
+        flags.api = true;
+        flags.ui = true;
+      }
       if (flags.ui) {
         flags.react = true;
       }
@@ -81,7 +99,7 @@ export class InitCommand {
 
       // Detect agent type: claude CLI → CLAUDE.md, else → AGENTS.md
       let agentType: "claude" | "agents" | false = false;
-      if (flags.agent) {
+      if (flags.ai) {
         const hasClaudeCli = await this.utils.isInstalledAsync("claude");
         agentType = hasClaudeCli ? "claude" : "agents";
       }
@@ -112,12 +130,17 @@ export class InitCommand {
             force,
           });
           if (flags.api) {
-            await this.scaffolder.ensureApiProject(root, { force });
+            await this.scaffolder.ensureApiProject(root, {
+              auth: !!flags.auth,
+              force,
+            });
           }
           if (flags.react && !isExpo) {
             await this.scaffolder.ensureWebProject(root, {
               api: !!flags.api,
               ui: !!flags.ui,
+              auth: !!flags.auth,
+              admin: !!flags.admin,
               force,
             });
           }

package/src/cli/providers/ViteDevServerProvider.ts

@@ -3,7 +3,6 @@ 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";
 
 export interface ViteDevServerOptions {
@@ -49,7 +48,6 @@ export interface ViteDevServerOptions {
 export class ViteDevServerProvider {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
-  protected readonly templateProvider = $inject(ViteUtils);
   protected server!: ViteDevServer;
   protected options!: ViteDevServerOptions;
   protected alepha: Alepha | null = null;
@@ -240,19 +238,17 @@ export class ViteDevServerProvider {
   }
 
   /**
-   * Setup Alepha instance with Vite middleware and template.
+   * Setup Alepha instance with Vite middleware.
    */
   protected async setupAlepha(): Promise<void> {
     if (!this.alepha || !this.hasReact()) {
       return;
     }
 
-    const template = await this.server.transformIndexHtml(
-      "/",
-      this.templateProvider.generateIndexHtml(this.options.entry),
-    );
-
-    this.alepha.store.set("alepha.react.server.template", template);
+    // Generate dev head content using Vite's transformIndexHtml
+    // This lets Vite and all plugins (React, etc.) inject their scripts
+    const devHead = await this.generateDevHead();
+    this.alepha.store.set("alepha.react.ssr.manifest" as any, { devHead });
 
     this.alepha.events.on("server:onRequest", {
       priority: "first",
@@ -273,6 +269,32 @@ export class ViteDevServerProvider {
     });
   }
 
+  /**
+   * Generate dev head content by transforming a minimal HTML through Vite.
+   * This lets Vite and all plugins inject their scripts (HMR client, React Fast Refresh, etc.).
+   */
+  protected async generateDevHead(): Promise<string> {
+    const { browser, style } = this.options.entry;
+
+    // Build minimal HTML with entry points
+    const scripts: string[] = [];
+    if (style) {
+      scripts.push(`<link rel="stylesheet" href="/${style}">`);
+    }
+    if (browser) {
+      scripts.push(`<script type="module" src="/${browser}"></script>`);
+    }
+
+    const minimalHtml = `<!DOCTYPE html><html><head>${scripts.join("\n")}</head><body></body></html>`;
+
+    // Transform through Vite to inject all plugin scripts
+    const transformed = await this.server.transformIndexHtml("/", minimalHtml);
+
+    // Extract head content
+    const headMatch = transformed.match(/<head>([\s\S]*?)<\/head>/i);
+    return headMatch?.[1]?.trim() ?? "";
+  }
+
   /**
    * Check if request is for an HTML page (not an asset).
    */

package/src/cli/services/AlephaCliUtils.ts

@@ -145,4 +145,20 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
   public isInstalledAsync(cmd: string): Promise<boolean> {
     return this.shell.isInstalled(cmd);
   }
+
+  /**
+   * Get the current git revision (commit SHA).
+   *
+   * @returns The short commit SHA or "unknown" if not in a git repo
+   */
+  public async getGitRevision(): Promise<string> {
+    try {
+      const result = await this.shell.run("git rev-parse --short HEAD", {
+        capture: true,
+      });
+      return result.trim();
+    } catch {
+      return "unknown";
+    }
+  }
 }

package/src/cli/services/PackageManagerUtils.ts

@@ -388,6 +388,8 @@ export class PackageManagerUtils {
     if (modes.react) {
       dependencies.react = alephaDeps.react;
       dependencies["react-dom"] = alephaDeps["react-dom"];
+      devDependencies["@vitejs/plugin-react"] =
+        alephaDeps["@vitejs/plugin-react"];
       devDependencies["@types/react"] = alephaDeps["@types/react"];
     }
 

package/src/cli/services/ProjectScaffolder.spec.ts

@@ -0,0 +1,97 @@
+import { Alepha } from "alepha";
+import {
+  FileSystemProvider,
+  MemoryFileSystemProvider,
+  MemoryShellProvider,
+  ShellProvider,
+} from "alepha/system";
+import { describe, expect, it } from "vitest";
+import { ProjectScaffolder } from "./ProjectScaffolder.ts";
+
+describe("ProjectScaffolder", () => {
+  const createTestEnv = () => {
+    const alepha = Alepha.create()
+      .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider })
+      .with({ provide: ShellProvider, use: MemoryShellProvider });
+
+    const scaffolder = alepha.inject(ProjectScaffolder);
+
+    return { alepha, scaffolder };
+  };
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getAppName
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getAppName", () => {
+    it("should return lowercase directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/MyApp")).toBe("myapp");
+    });
+
+    it("should remove dashes from directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/my-cool-app")).toBe("mycoolapp");
+    });
+
+    it("should remove underscores from directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/my_cool_app")).toBe("mycoolapp");
+    });
+
+    it("should remove spaces from directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/my cool app")).toBe("mycoolapp");
+    });
+
+    it("should remove dots from directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/my.cool.app")).toBe("mycoolapp");
+    });
+
+    it("should remove digits from directory name", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/app123")).toBe("app");
+      expect(scaffolder.getAppName("/project/my2app")).toBe("myapp");
+      expect(scaffolder.getAppName("/project/v2-app")).toBe("vapp");
+    });
+
+    it("should handle combination of special characters", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/my-cool_app.v2")).toBe(
+        "mycoolappv",
+      );
+      expect(scaffolder.getAppName("/project/test_app-2.0")).toBe("testapp");
+    });
+
+    it("should fallback to 'app' when all characters are removed", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/project/123")).toBe("app");
+      expect(scaffolder.getAppName("/project/---")).toBe("app");
+      expect(scaffolder.getAppName("/project/1.2.3")).toBe("app");
+      expect(scaffolder.getAppName("/project/_-._")).toBe("app");
+    });
+
+    it("should handle deeply nested paths", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/workspace/packages/apps/my-app")).toBe(
+        "myapp",
+      );
+    });
+
+    it("should handle root-level directories", () => {
+      const { scaffolder } = createTestEnv();
+
+      expect(scaffolder.getAppName("/myapp")).toBe("myapp");
+    });
+  });
+});