alepha 0.15.1 → 0.15.3

package/src/cli/atoms/buildOptions.ts

@@ -1,11 +1,29 @@
 import { type Static, t } from "alepha";
 import { $atom } from "../../core/primitives/$atom.ts";
 
+/**
+ * Deployment target for the build output.
+ *
+ * - `docker` - Generate Dockerfile for containerized deployment
+ * - `vercel` - Generate Vercel deployment configuration (forces node runtime)
+ * - `cloudflare` - Generate Cloudflare Workers configuration (forces workerd runtime)
+ */
+export type BuildTarget = "bare" | "docker" | "vercel" | "cloudflare";
+
+/**
+ * JavaScript runtime for the build output.
+ *
+ * - `node` - Node.js runtime (default)
+ * - `bun` - Bun runtime (uses bun export conditions)
+ * - `workerd` - Cloudflare Workers runtime (auto-set with cloudflare target)
+ */
+export type BuildRuntime = "node" | "bun" | "workerd";
+
 /**
  * Build options atom for CLI build command.
  *
  * Defines the available build configuration options with their defaults.
- * Options can be overridden via vite.config.ts or CLI flags.
+ * Options can be overridden via alepha.config.ts or CLI flags.
  */
 export const buildOptions = $atom({
   name: "alepha.cli.build.options",
@@ -17,7 +35,32 @@ export const buildOptions = $atom({
     stats: t.optional(t.boolean({ default: false })),
 
     /**
-     * Vercel deployment configuration.
+     * Deployment target for the build output.
+     *
+     * - `docker` - Generate Dockerfile for containerized deployment
+     * - `vercel` - Generate Vercel deployment configuration (forces node runtime)
+     * - `cloudflare` - Generate Cloudflare Workers configuration (forces workerd runtime)
+     */
+    target: t.optional(t.enum(["bare", "docker", "vercel", "cloudflare"])),
+
+    /**
+     * JavaScript runtime for the build output.
+     *
+     * - `node` - Node.js runtime (default)
+     * - `bun` - Bun runtime (uses bun export conditions)
+     * - `workerd` - Cloudflare Workers runtime (auto-set with cloudflare target)
+     *
+     * Note: Some targets force a specific runtime:
+     * - `cloudflare` always uses `workerd`
+     * - `vercel` always uses `node`
+     */
+    runtime: t.optional(t.enum(["node", "bun", "workerd"])),
+
+    /**
+     * Vercel-specific deployment configuration.
+     *
+     * Note: Set `target: "vercel"` to enable Vercel deployment.
+     * This object is only for additional configuration.
      */
     vercel: t.optional(
       t.object({
@@ -40,7 +83,10 @@ export const buildOptions = $atom({
     ),
 
     /**
-     * Cloudflare Workers deployment configuration.
+     * Cloudflare-specific deployment configuration.
+     *
+     * Note: Set `target: "cloudflare"` to enable Cloudflare deployment.
+     * This object is only for additional configuration.
      */
     cloudflare: t.optional(
       t.object({
@@ -49,21 +95,65 @@ export const buildOptions = $atom({
     ),
 
     /**
-     * Docker deployment configuration.
+     * Docker-specific deployment configuration.
+     *
+     * Note: Set `target: "docker"` to enable Docker deployment.
+     * This object is only for additional configuration.
      */
     docker: t.optional(
       t.object({
         /**
-         * Docker image name to use in the Dockerfile.
-         * @default "node:24-alpine"
+         * Base image for the Dockerfile (FROM instruction).
+         *
+         * @default "node:24-alpine" for node runtime
+         * @default "oven/bun:alpine" for bun runtime
          */
-        image: t.optional(t.string({ default: "node:24-alpine" })),
+        from: t.optional(t.string()),
 
         /**
          * Command to run in the Docker container.
-         * @default "node"
+         *
+         * @default "node" for node runtime
+         * @default "bun" for bun runtime
+         */
+        command: t.optional(t.string()),
+
+        /**
+         * Docker build options (used when --image flag is passed).
          */
-        command: t.optional(t.string({ default: "node" })),
+        image: t.optional(
+          t.object({
+            /**
+             * Default image tag (name without version).
+             *
+             * Used when --image is provided without a full override:
+             * - `--image` → `tag:latest`
+             * - `--image=1.3.4` → `tag:1.3.4`
+             * - `--image=other/img:v1` → `other/img:v1` (full override)
+             *
+             * @example "myproject/myapp"
+             * @example "ghcr.io/myorg/myapp"
+             */
+            tag: t.string(),
+
+            /**
+             * Additional arguments to pass to `docker build`.
+             *
+             * @example '--platform linux/amd64 --no-cache'
+             */
+            args: t.optional(t.string()),
+
+            /**
+             * Auto-add OCI standard labels (revision, created, version).
+             *
+             * Adds:
+             * - org.opencontainers.image.revision (git commit SHA)
+             * - org.opencontainers.image.created (build timestamp)
+             * - org.opencontainers.image.version (from image tag)
+             */
+            oci: t.optional(t.boolean()),
+          }),
+        ),
       }),
     ),
 

package/src/cli/commands/build.ts

@@ -1,7 +1,7 @@
 import { $inject, $use, type Alepha, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import {
   buildClient,
   buildServer,
@@ -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";
@@ -83,15 +121,27 @@ export class BuildCommand {
       const distDir = "dist";
       const publicDir = "public";
 
-      await this.pm.ensureDependency(root, "vite", {
-        run,
-        exec: (cmd, opts) => this.utils.exec(cmd, opts),
-      });
       await run.rm("dist", { alias: "clean dist" });
 
       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;
@@ -144,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");
           }
 
@@ -208,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: () =>
@@ -221,7 +262,7 @@ export class BuildCommand {
         });
       }
 
-      if (flags.cloudflare || options.cloudflare) {
+      if (target === "cloudflare") {
         await run({
           name: "add Cloudflare config",
           handler: () =>
@@ -232,15 +273,87 @@ export class BuildCommand {
         });
       }
 
-      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

@@ -1,12 +1,13 @@
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import type {
   DatabaseProvider,
   DrizzleKitProvider,
   RepositoryProvider,
 } from "alepha/orm";
+import { FileSystemProvider } from "alepha/system";
+import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 
 const drizzleCommandFlags = t.object({
@@ -28,6 +29,7 @@ export class DbCommand {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly utils = $inject(AlephaCliUtils);
+  protected readonly entryProvider = $inject(AppEntryProvider);
 
   /**
    * Check if database migrations are up to date.
@@ -46,10 +48,11 @@ export class DbCommand {
       const rootDir = root;
       this.log.debug(`Using project root: ${rootDir}`);
 
-      const { alepha } = await this.utils.loadAlephaFromServerEntryFile(
-        rootDir,
-        args,
-      );
+      const entry = await this.entryProvider.getAppEntry(root);
+      const alepha = await this.utils.loadAlephaFromServerEntryFile({
+        mode: "development",
+        entry,
+      });
 
       const repositoryProvider =
         alepha.inject<RepositoryProvider>("RepositoryProvider");
@@ -276,10 +279,11 @@ export class DbCommand {
 
     this.log.debug(`Using project root: ${rootDir}`);
 
-    const { alepha, entry } = await this.utils.loadAlephaFromServerEntryFile(
-      rootDir,
-      options.args,
-    );
+    const entry = await this.entryProvider.getAppEntry(rootDir);
+    const alepha = await this.utils.loadAlephaFromServerEntryFile({
+      mode: "development",
+      entry,
+    });
 
     const drizzleKitProvider =
       alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
@@ -319,7 +323,7 @@ export class DbCommand {
         providerUrl: provider.url,
         providerDriver: provider.driver,
         dialect,
-        entry,
+        entry: this.fs.join(rootDir, entry.server),
         rootDir,
       });
 
@@ -328,7 +332,9 @@ export class DbCommand {
         `drizzle-kit ${options.command} --config=${drizzleConfigJsPath}${flags}`,
         {
           env: {
-            NODE_OPTIONS: "--import tsx",
+            NODE_OPTIONS: [process.env.NODE_OPTIONS, "--import tsx"]
+              .filter(Boolean)
+              .join(" "),
           },
         },
       );
@@ -399,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/deploy.ts

@@ -1,7 +1,7 @@
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 

package/src/cli/commands/dev.ts

@@ -1,7 +1,7 @@
 import { $inject, Alepha } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 import { ViteDevServerProvider } from "../providers/ViteDevServerProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
@@ -20,39 +20,20 @@ export class DevCommand {
 
   /**
    * Will run the project in watch mode.
-   *
-   * - If an index.html file is found in the project root, it will run Vite in dev mode.
-   * - Otherwise, it will look for a server entry file and run it with tsx in watch mode.
    */
   public readonly dev = $command({
     name: "dev",
     description: "Run the project in development mode",
     handler: async ({ root }) => {
-      const [expo, react] = await Promise.all([
-        this.pm.hasExpo(root),
-        this.pm.hasReact(root),
-      ]);
-
       await this.scaffolder.ensureConfig(root, {
         tsconfigJson: true,
       });
 
-      if (expo) {
-        await this.utils.exec("expo start");
-        return;
-      }
-
       const entry = await this.boot.getAppEntry(root);
       this.log.debug("Entry file found", { entry });
 
       // -> here, we assume we use Vite as runner (api or fullstack)
       // but it's planned to support Bun runner in the future as well
-
-      // Ensure vite is installed before running
-      await this.pm.ensureDependency(root, "vite", {
-        exec: (cmd, opts) => this.utils.exec(cmd, opts),
-      });
-
       await this.viteDevServer.init({ root, entry });
       await this.viteDevServer.start();
     },

package/src/cli/commands/gen/env.ts

@@ -1,7 +1,7 @@
 import { $inject, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { AlephaCliUtils } from "../../services/AlephaCliUtils.ts";
 
 export class GenEnvCommand {
@@ -21,7 +21,10 @@ export class GenEnvCommand {
       ),
     }),
     handler: async ({ root, flags }) => {
-      const { alepha } = await this.utils.loadAlephaFromServerEntryFile(root);
+      const alepha = await this.utils.loadAlephaFromServerEntryFile({
+        root,
+        mode: "development",
+      });
 
       try {
         const { env } = alepha.dump();

package/src/cli/commands/gen/openapi.ts

@@ -1,8 +1,8 @@
 import { $inject, t } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { ServerSwaggerProvider } from "alepha/server/swagger";
+import { FileSystemProvider } from "alepha/system";
 import { AlephaCliUtils } from "../../services/AlephaCliUtils.ts";
 
 export class OpenApiCommand {
@@ -22,7 +22,10 @@ export class OpenApiCommand {
       ),
     }),
     handler: async ({ root, flags }) => {
-      const { alepha } = await this.utils.loadAlephaFromServerEntryFile(root);
+      const alepha = await this.utils.loadAlephaFromServerEntryFile({
+        root,
+        mode: "development",
+      });
 
       try {
         const openapiProvider = alepha.inject(