alepha 0.14.0 → 0.14.2

package/src/cli/commands/deploy.ts

@@ -0,0 +1,118 @@
+import { join } from "node:path";
+import { $inject, AlephaError, t } from "alepha";
+import { $command } from "alepha/command";
+import { $logger } from "alepha/logger";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class DeployCommand {
+  protected readonly log = $logger();
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  /**
+   * Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)
+   *
+   * Deploy command can be overridden by creating a alepha.config.ts in the project root:
+   *
+   * ```ts
+   * import { defineConfig } from "alepha/cli";
+   *
+   * export default defineConfig({
+   *   commands: {
+   *     deploy: {
+   *       handler: async ({ root, mode, flags }) => {
+   *         // Custom deployment logic here
+   *       },
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  public readonly deploy = $command({
+    name: "deploy",
+    description:
+      "Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)",
+    mode: true,
+    flags: t.object({
+      build: t.boolean({
+        description: "Build the project before deployment",
+        default: false,
+      }),
+      migrate: t.boolean({
+        description:
+          "Run database migrations before deployment (if applicable)",
+        default: false,
+      }),
+    }),
+    env: t.object({
+      VERCEL_TOKEN: t.optional(
+        t.text({
+          description: "Vercel API token (e.g., xxxxxxxxxxxxxxxxxxxx)",
+        }),
+      ),
+      VERCEL_ORG_ID: t.optional(
+        t.text({
+          description: "Vercel organization ID (e.g., team_abc123...)",
+        }),
+      ),
+      VERCEL_PROJECT_ID: t.optional(
+        t.text({ description: "Vercel project ID (e.g., prj_abc123...)" }),
+      ),
+      CLOUDFLARE_API_TOKEN: t.optional(
+        t.text({
+          description: "Cloudflare API token (e.g., xxxx-xxxx-xxxx-xxxx)",
+        }),
+      ),
+      CLOUDFLARE_ACCOUNT_ID: t.optional(
+        t.text({
+          description: "Cloudflare account ID (e.g., abc123def456...)",
+        }),
+      ),
+    }),
+    handler: async ({ root, mode, flags }) => {
+      if (flags.build) {
+        await this.utils.exec("alepha build");
+      }
+
+      // Vercel deployment
+      if (await this.utils.exists(root, "dist/vercel.json")) {
+        if (flags.migrate) {
+          this.log.debug("Running database migrations before deployment...");
+          await this.utils.exec(`alepha db migrate --mode=${mode}`);
+        }
+        await this.utils.ensureDependency(root, "vercel", { dev: true });
+        const command =
+          `vercel . --cwd=dist ${mode === "production" ? "--prod" : ""}`.trim();
+        this.log.debug(`Deploying to Vercel with command: ${command}`);
+        await this.utils.exec(command);
+        return;
+      }
+
+      // Cloudflare deployment
+      if (await this.utils.exists(root, "dist/wrangler.jsonc")) {
+        if (flags.migrate) {
+          this.log.debug("Running database migrations before deployment...");
+          await this.utils.exec(`alepha db migrate --mode=${mode}`);
+        }
+        await this.utils.ensureDependency(root, "wrangler", { dev: true });
+        const command =
+          `wrangler deploy ${mode === "production" ? "" : "--env preview"} --config=dist/wrangler.jsonc`.trim();
+        this.log.info(`Deploying to Cloudflare with command: ${command}`);
+        await this.utils.exec(command);
+        return;
+      }
+
+      // Surge deployment
+      if (await this.utils.exists(root, "dist/public/404.html")) {
+        await this.utils.ensureDependency(root, "surge", { dev: true });
+        const distPath = join(root, "dist/public");
+        this.log.debug(`Deploying to Surge from directory: ${distPath}`);
+        await this.utils.exec(`surge ${distPath}`);
+        return;
+      }
+
+      throw new AlephaError(
+        "No deployment configuration found in the dist folder.",
+      );
+    },
+  });
+}

package/src/cli/commands/dev.ts

@@ -0,0 +1,57 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { $inject, t } from "alepha";
+import { $command } from "alepha/command";
+import { $logger } from "alepha/logger";
+import { boot } from "alepha/vite";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class DevCommand {
+  protected readonly log = $logger();
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  /**
+   * 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",
+    args: t.optional(t.text({ title: "path", description: "Filepath to run" })),
+    handler: async ({ args, root }) => {
+      const expo = await this.utils.hasExpo(root);
+
+      await this.utils.ensureConfig(root, {
+        viteConfigTs: !expo,
+        tsconfigJson: true,
+      });
+
+      if (expo) {
+        await this.utils.exec("expo start");
+        return;
+      }
+
+      const entry = await boot.getServerEntry(root, args);
+      this.log.trace("Entry file found", { entry });
+
+      try {
+        await access(join(root, "index.html"));
+      } catch {
+        this.log.trace("No index.html found, running entry file with tsx");
+        let cmd = "tsx --watch";
+        if (await this.utils.exists(root, ".env")) {
+          cmd += " --env-file=./.env";
+        }
+        cmd += ` ${entry}`;
+        await this.utils.exec(cmd);
+        return;
+      }
+
+      // Ensure vite is installed before running
+      await this.utils.ensureDependency(root, "vite");
+      await this.utils.exec("vite");
+    },
+  });
+}

package/src/cli/commands/format.ts

@@ -0,0 +1,17 @@
+import { $inject } from "alepha";
+import { $command } from "alepha/command";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class FormatCommand {
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  public readonly format = $command({
+    name: "format",
+    description: "Format the codebase using Biome",
+    handler: async ({ root }) => {
+      await this.utils.ensureConfig(root, { biomeJson: true });
+      await this.utils.ensureDependency(root, "@biomejs/biome");
+      await this.utils.exec("biome format --fix");
+    },
+  });
+}

package/src/cli/commands/{CoreCommands.ts → init.ts}

@@ -1,48 +1,10 @@
 import { $inject, t } from "alepha";
-import { $command, CliProvider } from "alepha/command";
-import { $logger } from "alepha/logger";
+import { $command } from "alepha/command";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
-import { version } from "../version.ts";
 
-export class CoreCommands {
-  protected readonly log = $logger();
-  protected readonly cli = $inject(CliProvider);
+export class InitCommand {
   protected readonly utils = $inject(AlephaCliUtils);
 
-  /**
-   * Called when no command is provided
-   */
-  public readonly root = $command({
-    root: true,
-    flags: t.object({
-      version: t.optional(
-        t.boolean({
-          description: "Show Alepha CLI version",
-          aliases: ["v"],
-        }),
-      ),
-    }),
-    handler: async ({ flags }) => {
-      if (flags.version) {
-        this.log.info(version);
-        return;
-      }
-
-      this.cli.printHelp();
-    },
-  });
-
-  /**
-   * Clean the project, removing the "dist" directory
-   */
-  public readonly clean = $command({
-    name: "clean",
-    description: "Clean the project",
-    handler: async ({ run }) => {
-      await run.rm("./dist");
-    },
-  });
-
   /**
    * Ensure the project has the necessary Alepha configuration files.
    * Add the correct dependencies to package.json and install them.

package/src/cli/commands/lint.ts

@@ -0,0 +1,17 @@
+import { $inject } from "alepha";
+import { $command } from "alepha/command";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class LintCommand {
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  public readonly lint = $command({
+    name: "lint",
+    description: "Run linter across the codebase using Biome",
+    handler: async ({ root }) => {
+      await this.utils.ensureConfig(root, { biomeJson: true });
+      await this.utils.ensureDependency(root, "@biomejs/biome");
+      await this.utils.exec("biome check --formatter-enabled=false --fix");
+    },
+  });
+}

package/src/cli/commands/root.ts

@@ -0,0 +1,32 @@
+import { $inject, t } from "alepha";
+import { $command, CliProvider } from "alepha/command";
+import { $logger } from "alepha/logger";
+import { version } from "../version.ts";
+
+export class RootCommand {
+  protected readonly log = $logger();
+  protected readonly cli = $inject(CliProvider);
+
+  /**
+   * Called when no command is provided
+   */
+  public readonly root = $command({
+    root: true,
+    flags: t.object({
+      version: t.optional(
+        t.boolean({
+          description: "Show Alepha CLI version",
+          aliases: ["v"],
+        }),
+      ),
+    }),
+    handler: async ({ flags }) => {
+      if (flags.version) {
+        this.log.info(version);
+        return;
+      }
+
+      this.cli.printHelp();
+    },
+  });
+}

package/src/cli/commands/run.ts

@@ -0,0 +1,24 @@
+import { $inject, t } from "alepha";
+import { $command } from "alepha/command";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class RunCommand {
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  public readonly run = $command({
+    name: "run",
+    hide: true,
+    description: "Run a TypeScript file directly",
+    flags: t.object({
+      watch: t.optional(
+        t.boolean({ description: "Watch file for changes", alias: "w" }),
+      ),
+    }),
+    summary: false,
+    args: t.text({ title: "path", description: "Filepath to run" }),
+    handler: async ({ args, flags, root }) => {
+      await this.utils.ensureTsConfig(root);
+      await this.utils.exec(`tsx ${flags.watch ? "watch " : ""}${args}`);
+    },
+  });
+}

package/src/cli/commands/test.ts

@@ -0,0 +1,42 @@
+import { $inject, t } from "alepha";
+import { $command } from "alepha/command";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class TestCommand {
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  public readonly test = $command({
+    name: "test",
+    description: "Run tests using Vitest",
+    flags: t.object({
+      config: t.optional(
+        t.string({
+          description: "Path to Vitest config file",
+          alias: "c",
+        }),
+      ),
+    }),
+    env: t.object({
+      VITEST_ARGS: t.optional(
+        t.string({
+          default: "",
+          description:
+            "Additional arguments to pass to Vitest. E.g., --coverage",
+        }),
+      ),
+    }),
+    handler: async ({ root, flags, env }) => {
+      await this.utils.ensureConfig(root, {
+        tsconfigJson: true,
+        viteConfigTs: true,
+      });
+
+      // Ensure vitest is installed before running
+      await this.utils.ensureDependency(root, "vitest");
+
+      const config = flags.config ? `--config=${flags.config}` : "";
+
+      await this.utils.exec(`vitest run ${config} ${env.VITEST_ARGS}`);
+    },
+  });
+}

package/src/cli/commands/typecheck.ts

@@ -0,0 +1,19 @@
+import { $inject } from "alepha";
+import { $command } from "alepha/command";
+import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+
+export class TypecheckCommand {
+  protected readonly utils = $inject(AlephaCliUtils);
+
+  /**
+   * Run TypeScript type checking across the codebase with no emit.
+   */
+  public readonly typecheck = $command({
+    name: "typecheck",
+    description: "Check TypeScript types across the codebase",
+    handler: async ({ root }) => {
+      await this.utils.ensureDependency(root, "typescript");
+      await this.utils.exec("tsc --noEmit");
+    },
+  });
+}

package/src/cli/commands/{VerifyCommands.ts → verify.ts}

@@ -2,7 +2,7 @@ import { $inject } from "alepha";
 import { $command } from "alepha/command";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 
-export class VerifyCommands {
+export class VerifyCommand {
   protected readonly utils = $inject(AlephaCliUtils);
 
   /**
@@ -44,16 +44,4 @@ export class VerifyCommands {
       await run("alepha clean");
     },
   });
-
-  /**
-   * Run TypeScript type checking across the codebase with no emit.
-   */
-  public readonly typecheck = $command({
-    name: "typecheck",
-    description: "Check TypeScript types across the codebase",
-    handler: async ({ root }) => {
-      await this.utils.ensureDependency(root, "typescript");
-      await this.utils.exec("tsc --noEmit");
-    },
-  });
 }

package/src/cli/defineConfig.ts

@@ -0,0 +1,24 @@
+import type { Alepha } from "alepha";
+import type { CommandPrimitive } from "alepha/command";
+
+export type AlephaCliConfig = (alepha: Alepha) => {
+  commands?: Record<string, CommandPrimitive>;
+  services?: Array<any>;
+};
+
+export const defineConfig = (config: AlephaCliConfig) => {
+  return (alepha: Alepha) => {
+    const { commands, services = [] } = config(alepha);
+    for (const it of services) {
+      alepha.with(it);
+    }
+    return {
+      ...commands,
+    };
+  };
+};
+
+/**
+ * @alias defineConfig
+ */
+export const defineAlephaConfig = defineConfig;

package/src/cli/index.ts

@@ -1,9 +1,21 @@
 export * from "./apps/AlephaCli.ts";
 export * from "./apps/AlephaPackageBuilderCli.ts";
-export * from "./commands/BiomeCommands.ts";
-export * from "./commands/CoreCommands.ts";
-export * from "./commands/DrizzleCommands.ts";
-export * from "./commands/VerifyCommands.ts";
-export * from "./commands/ViteCommands.ts";
+export * from "./atoms/changelogOptions.ts";
+export * from "./commands/build.ts";
+export * from "./commands/changelog.ts";
+export * from "./commands/clean.ts";
+export * from "./commands/db.ts";
+export * from "./commands/deploy.ts";
+export * from "./commands/dev.ts";
+export * from "./commands/format.ts";
+export * from "./commands/init.ts";
+export * from "./commands/lint.ts";
+export * from "./commands/root.ts";
+export * from "./commands/run.ts";
+export * from "./commands/test.ts";
+export * from "./commands/typecheck.ts";
+export * from "./commands/verify.ts";
+export * from "./defineConfig.ts";
 export * from "./services/AlephaCliUtils.ts";
+export * from "./services/GitMessageParser.ts";
 export * from "./version.ts";

package/src/cli/services/AlephaCliUtils.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { $inject, Alepha, AlephaError } from "alepha";
-import type { RunnerMethod } from "alepha/command";
+import { EnvUtils, type RunnerMethod } from "alepha/command";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { boot } from "alepha/vite";
@@ -31,6 +31,7 @@ import { version } from "../version.ts";
 export class AlephaCliUtils {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
+  protected readonly envUtils = $inject(EnvUtils);
 
   /**
    * Execute a command using npx with inherited stdio.
@@ -499,29 +500,11 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
    * Reads the .env file in the specified root directory and sets
    * the environment variables in process.env.
    */
-  public async loadEnvFile(
+  public async loadEnv(
     root: string,
     files: string[] = [".env"],
   ): Promise<void> {
-    for (const it of files) {
-      for (const file of [it, `${it}.local`]) {
-        const envPath = join(root, file);
-        try {
-          const envContent = await readFile(envPath, "utf8");
-          const lines = envContent.split("\n");
-          for (const line of lines) {
-            const [key, ...rest] = line.split("=");
-            if (key) {
-              const value = rest.join("=");
-              process.env[key.trim()] = value.trim();
-            }
-          }
-          this.log.debug(`Loaded environment variables from ${envPath}`);
-        } catch {
-          this.log.debug(`No ${file} file found at ${envPath}, skipping load.`);
-        }
-      }
-    }
+    await this.envUtils.loadEnv(root, files);
   }
 
   public async getPackageManager(

package/src/cli/services/GitMessageParser.ts

@@ -0,0 +1,77 @@
+import { $logger } from "alepha/logger";
+import {
+  type ChangelogOptions,
+  DEFAULT_IGNORE,
+} from "../atoms/changelogOptions.ts";
+import type { Commit } from "../commands/changelog.ts";
+
+/**
+ * Service for parsing git commit messages into structured format.
+ *
+ * Only parses **conventional commits with a scope**:
+ * - `feat(scope): description` → feature
+ * - `fix(scope): description` → bug fix
+ * - `feat(scope)!: description` → breaking change
+ *
+ * Commits without scope are ignored, allowing developers to commit
+ * work-in-progress changes without polluting release notes:
+ * - `cli: work in progress` → ignored (no type)
+ * - `fix: quick patch` → ignored (no scope)
+ * - `feat(cli): add command` → included
+ */
+export class GitMessageParser {
+  protected readonly log = $logger();
+
+  /**
+   * Parse a git commit line into a structured Commit object.
+   *
+   * **Format:** `type(scope): description` or `type(scope)!: description`
+   *
+   * **Supported types:** feat, fix, docs, refactor, perf, revert
+   *
+   * **Breaking changes:** Use `!` before `:` (e.g., `feat(api)!: remove endpoint`)
+   *
+   * @returns Commit object or null if not matching/ignored
+   */
+  parseCommit(line: string, config: ChangelogOptions): Commit | null {
+    // Extract hash and message from git log --oneline format
+    const match = line.match(/^([a-f0-9]+)\s+(.+)$/);
+    if (!match) return null;
+
+    const [, hash, message] = match;
+    const ignore = config.ignore ?? DEFAULT_IGNORE;
+
+    // Conventional commit with REQUIRED scope: type(scope): description
+    // The `!` before `:` marks a breaking change
+    const conventionalMatch = message.match(
+      /^(feat|fix|docs|refactor|perf|revert)\(([^)]+)\)(!)?:\s*(.+)$/i,
+    );
+
+    if (!conventionalMatch) {
+      // No match - commit doesn't follow required format
+      return null;
+    }
+
+    const [, type, scope, breakingMark, description] = conventionalMatch;
+
+    // Check if scope should be ignored
+    const baseScope = scope.split("/")[0];
+    if (ignore.includes(baseScope) || ignore.includes(scope)) {
+      return null;
+    }
+
+    // Breaking change detection:
+    // 1. Explicit `!` marker: feat(api)!: change
+    // 2. Word "breaking" in description: feat(api): breaking change to auth
+    const breaking =
+      breakingMark === "!" || description.toLowerCase().includes("breaking");
+
+    return {
+      hash: hash.substring(0, 8),
+      type: type.toLowerCase(),
+      scope,
+      description: description.trim(),
+      breaking,
+    };
+  }
+}

package/src/command/helpers/EnvUtils.ts

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { $logger } from "alepha/logger";
+
+export class EnvUtils {
+  protected readonly log = $logger();
+
+  /**
+   * Load environment variables from .env files into process.env.
+   * By default, it loads from ".env" and ".env.local".
+   * You can specify additional files to load, e.g. [".env", ".env.production"].
+   */
+  public async loadEnv(
+    root: string,
+    files: string[] = [".env"],
+  ): Promise<void> {
+    for (const it of files) {
+      for (const file of [it, `${it}.local`]) {
+        const envPath = join(root, file);
+        try {
+          const envContent = await readFile(envPath, "utf8");
+          const lines = envContent.split("\n");
+          for (const line of lines) {
+            const [key, ...rest] = line.split("=");
+            if (key) {
+              const value = rest.join("=");
+              process.env[key.trim()] = value.trim();
+            }
+          }
+          this.log.debug(`Loaded environment variables from ${envPath}`);
+        } catch {
+          this.log.debug(`No ${file} file found at ${envPath}, skipping load.`);
+        }
+      }
+    }
+  }
+}

package/src/command/index.ts

@@ -1,5 +1,6 @@
 import { $module } from "alepha";
 import { Asker } from "./helpers/Asker.ts";
+import { EnvUtils } from "./helpers/EnvUtils.ts";
 import { PrettyPrint } from "./helpers/PrettyPrint.ts";
 import { Runner } from "./helpers/Runner.ts";
 import { $command } from "./primitives/$command.ts";
@@ -9,6 +10,7 @@ import { CliProvider } from "./providers/CliProvider.ts";
 
 export * from "./errors/CommandError.ts";
 export * from "./helpers/Asker.ts";
+export * from "./helpers/EnvUtils.ts";
 export * from "./helpers/PrettyPrint.ts";
 export * from "./helpers/Runner.ts";
 export * from "./primitives/$command.ts";
@@ -28,7 +30,7 @@ export * from "./providers/CliProvider.ts";
 export const AlephaCommand = $module({
   name: "alepha.command",
   primitives: [$command],
-  services: [CliProvider, Runner, Asker, PrettyPrint],
+  services: [CliProvider, Runner, Asker, PrettyPrint, EnvUtils],
 });
 
 // ---------------------------------------------------------------------------------------------------------------------