alepha 0.13.8 → 0.14.1

package/src/cli/services/AlephaCliUtils.ts

@@ -2,10 +2,9 @@ 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 type { DrizzleKitProvider, RepositoryProvider } from "alepha/orm";
 import { boot } from "alepha/vite";
 import { tsImport } from "tsx/esm/api";
 import { appRouterTs } from "../assets/appRouterTs.ts";
@@ -32,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.
@@ -495,160 +495,16 @@ ${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")
   }
 
   /**
-   * Prepare Drizzle configuration files for a database provider.
+   * Load environment variables from a .env file.
    *
-   * Creates temporary entities.js and drizzle.config.js files needed
-   * for Drizzle Kit commands to run properly.
-   *
-   * @param options - Configuration options including kit, provider info, and paths
-   * @returns Path to the generated drizzle.config.js file
+   * Reads the .env file in the specified root directory and sets
+   * the environment variables in process.env.
    */
-  public async prepareDrizzleConfig(options: {
-    kit: any;
-    provider: any;
-    providerName: string;
-    providerUrl: string;
-    dialect: string;
-    entry: string;
-    rootDir: string;
-  }): Promise<string> {
-    const models = Object.keys(options.kit.getModels(options.provider));
-    const entitiesJs = this.generateEntitiesJs(
-      options.entry,
-      options.providerName,
-      models,
-    );
-
-    const entitiesJsPath = await this.writeConfigFile(
-      "entities.js",
-      entitiesJs,
-      options.rootDir,
-    );
-
-    const config: Record<string, any> = {
-      schema: entitiesJsPath,
-      out: `./migrations/${options.providerName}`,
-      dialect: options.dialect,
-      dbCredentials: {
-        url: options.providerUrl,
-      },
-    };
-
-    if (options.dialect === "sqlite") {
-      let url = options.providerUrl;
-      url = url.replace("sqlite://", "").replace("file://", "");
-      url = join(options.rootDir, url);
-
-      config.dbCredentials = {
-        url,
-      };
-    }
-
-    if (options.providerName === "pglite") {
-      config.driver = "pglite";
-    }
-
-    const drizzleConfigJs = `export default ${JSON.stringify(config, null, 2)}`;
-
-    return await this.writeConfigFile(
-      "drizzle.config.js",
-      drizzleConfigJs,
-      options.rootDir,
-    );
-  }
-
-  public async loadEnvFile(root: string): Promise<void> {
-    const envPath = join(root, ".env");
-    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 .env file found at ${envPath}, skipping load.`);
-    }
-  }
-
-  /**
-   * Run a drizzle-kit command for all database providers in an Alepha instance.
-   *
-   * Iterates through all repository providers, prepares Drizzle config for each,
-   * and executes the specified drizzle-kit command.
-   *
-   * @param options - Configuration including command to run, flags, and logging
-   */
-  public async runDrizzleKitCommand(options: {
-    root: string;
-    args?: string;
-    command: string;
-    commandFlags?: string;
-    provider?: string;
-    logMessage: (providerName: string, dialect: string) => string;
-  }): Promise<void> {
-    const rootDir = options.root;
-
-    await this.loadEnvFile(rootDir);
-
-    this.log.debug(`Using project root: ${rootDir}`);
-
-    const { alepha, entry } = await this.loadAlephaFromServerEntryFile(
-      rootDir,
-      options.args,
-    );
-
-    const drizzleKitProvider =
-      alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
-    const repositoryProvider =
-      alepha.inject<RepositoryProvider>("RepositoryProvider");
-    const accepted = new Set<string>([]);
-
-    for (const primitive of repositoryProvider.getRepositories()) {
-      const provider = primitive.provider;
-      const providerName = provider.name;
-      const dialect = provider.dialect;
-
-      if (accepted.has(providerName)) {
-        continue;
-      }
-      accepted.add(providerName);
-
-      // Skip if provider filter is set and doesn't match
-      if (options.provider && options.provider !== providerName) {
-        this.log.debug(
-          `Skipping provider '${providerName}' (filter: ${options.provider})`,
-        );
-        continue;
-      }
-
-      this.log.info("");
-      this.log.info(options.logMessage(providerName, dialect));
-
-      const drizzleConfigJsPath = await this.prepareDrizzleConfig({
-        kit: drizzleKitProvider,
-        provider,
-        providerName,
-        providerUrl: provider.url,
-        dialect,
-        entry,
-        rootDir,
-      });
-
-      const flags = options.commandFlags ? ` ${options.commandFlags}` : "";
-      await this.exec(
-        `drizzle-kit ${options.command} --config=${drizzleConfigJsPath}${flags}`,
-        {
-          env: {
-            NODE_OPTIONS: "--import tsx",
-          },
-        },
-      );
-    }
+  public async loadEnv(
+    root: string,
+    files: string[] = [".env"],
+  ): Promise<void> {
+    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/ChangelogCommands.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],
 });
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/command/primitives/$command.ts

@@ -19,17 +19,29 @@ import type { RunnerMethod } from "../helpers/Runner.ts";
  * This primitive allows you to define a command, its flags, and its handler
  * within your Alepha application structure.
  */
-export const $command = <T extends TObject, A extends TSchema>(
-  options: CommandPrimitiveOptions<T, A>,
-) => createPrimitive(CommandPrimitive<T, A>, options);
+export const $command = <
+  T extends TObject,
+  A extends TSchema,
+  E extends TObject,
+>(
+  options: CommandPrimitiveOptions<T, A, E>,
+) => createPrimitive(CommandPrimitive<T, A, E>, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
+export interface CommandPrimitiveOptions<
+  T extends TObject,
+  A extends TSchema,
+  E extends TObject = TObject,
+> {
   /**
    * The handler function to execute when the command is matched.
+   *
+   * For parent commands with children, the handler is called when:
+   * - The parent command is invoked without a subcommand
+   * - The parent command is invoked with --help (to show available subcommands)
    */
-  handler: (args: CommandHandlerArgs<T, A>) => Async<void>;
+  handler: (args: CommandHandlerArgs<T, A, E>) => Async<void>;
 
   /**
    * The name of the command. If omitted, the property key is used.
@@ -53,6 +65,28 @@ export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
    */
   flags?: T;
 
+  /**
+   * A TypeBox object schema defining required environment variables.
+   *
+   * Environment variables are validated before the handler runs (fail fast).
+   * They are displayed in the help output under "Env:" section.
+   *
+   * @example
+   * ```ts
+   * $command({
+   *   env: t.object({
+   *     VERCEL_TOKEN: t.text({ description: "Vercel API token" }),
+   *     VERCEL_ORG_ID: t.optional(t.text({ description: "Organization ID" })),
+   *   }),
+   *   handler: async ({ env }) => {
+   *     // env.VERCEL_TOKEN is typed & guaranteed to exist
+   *     console.log(env.VERCEL_TOKEN);
+   *   }
+   * })
+   * ```
+   */
+  env?: E;
+
   /**
    * An optional TypeBox schema defining the arguments for the command.
    *
@@ -137,6 +171,86 @@ export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
    * If true, this command will be hidden from the help output.
    */
   hide?: boolean;
+
+  /**
+   * Adds a `--mode, -m` flag to load environment files.
+   *
+   * When enabled:
+   * - Loads `.env` and `.env.local` by default
+   * - With `--mode production`, also loads `.env.production` and `.env.production.local`
+   * - The mode value is exposed in the handler as `mode: string | undefined`
+   *
+   * Set to `true` to enable with no default, or a string to set a default mode.
+   *
+   * This follows Vite's environment loading convention.
+   * @see https://vite.dev/guide/env-and-mode
+   *
+   * @example
+   * ```ts
+   * // No default mode
+   * build = $command({
+   *   mode: true,
+   *   handler: async ({ mode }) => {
+   *     console.log(`Building for ${mode ?? 'development'}...`);
+   *   }
+   * });
+   *
+   * // Default mode "production"
+   * deploy = $command({
+   *   mode: "production",
+   *   handler: async ({ mode }) => {
+   *     console.log(`Deploying for ${mode}...`); // always defined
+   *   }
+   * });
+   * ```
+   *
+   * Usage:
+   * - `cli build` - loads .env (mode = undefined)
+   * - `cli build --mode production` - loads .env and .env.production
+   * - `cli deploy` - loads .env and .env.production (default mode)
+   * - `cli deploy --mode staging` - loads .env and .env.staging
+   */
+  mode?: boolean | string;
+
+  /**
+   * Child commands (subcommands) for this command.
+   *
+   * When children are defined, the command becomes a parent command that
+   * can be invoked with space-separated subcommands:
+   *
+   * @example
+   * ```ts
+   * class DeployCommands {
+   *   // Subcommands
+   *   vercel = $command({
+   *     description: "Deploy to Vercel",
+   *     handler: async () => { ... }
+   *   });
+   *
+   *   cloudflare = $command({
+   *     description: "Deploy to Cloudflare",
+   *     handler: async () => { ... }
+   *   });
+   *
+   *   // Parent command with children
+   *   deploy = $command({
+   *     description: "Deploy the application",
+   *     children: [this.vercel, this.cloudflare],
+   *     handler: async () => {
+   *       // Called when "deploy" is invoked without subcommand
+   *       console.log("Available: deploy vercel, deploy cloudflare");
+   *     }
+   *   });
+   * }
+   * ```
+   *
+   * This allows CLI usage like:
+   * - `cli deploy vercel` - runs the vercel subcommand
+   * - `cli deploy cloudflare` - runs the cloudflare subcommand
+   * - `cli deploy` - runs the parent handler (shows available subcommands)
+   * - `cli deploy --help` - shows help with all available subcommands
+   */
+  children?: CommandPrimitive<any, any>[];
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -144,8 +258,10 @@ export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
 export class CommandPrimitive<
   T extends TObject = TObject,
   A extends TSchema = TSchema,
-> extends Primitive<CommandPrimitiveOptions<T, A>> {
+  E extends TObject = TObject,
+> extends Primitive<CommandPrimitiveOptions<T, A, E>> {
   public readonly flags = this.options.flags ?? t.object({});
+  public readonly env = this.options.env ?? t.object({});
   public readonly aliases = this.options.aliases ?? [];
 
   protected onInit() {
@@ -166,6 +282,29 @@ export class CommandPrimitive<
     }
     return this.options.name ?? `${this.config.propertyKey}`;
   }
+
+  /**
+   * Get the child commands (subcommands) for this command.
+   */
+  public get children(): CommandPrimitive<any, any>[] {
+    return this.options.children ?? [];
+  }
+
+  /**
+   * Check if this command has child commands (is a parent command).
+   */
+  public get hasChildren(): boolean {
+    return this.children.length > 0;
+  }
+
+  /**
+   * Find a child command by name or alias.
+   */
+  public findChild(name: string): CommandPrimitive<any, any> | undefined {
+    return this.children.find(
+      (child) => child.name === name || child.aliases.includes(name),
+    );
+  }
 }
 
 $command[KIND] = CommandPrimitive;
@@ -175,9 +314,11 @@ $command[KIND] = CommandPrimitive;
 export interface CommandHandlerArgs<
   T extends TObject,
   A extends TSchema = TSchema,
+  E extends TObject = TObject,
 > {
   flags: Static<T>;
   args: A extends TSchema ? Static<A> : Array<string>;
+  env: Static<E>;
   run: RunnerMethod;
   ask: AskMethod;
   glob: typeof glob;
@@ -187,4 +328,29 @@ export interface CommandHandlerArgs<
    * The root directory where the command is executed.
    */
   root: string;
+
+  /**
+   * Display help for the current command.
+   *
+   * Useful for parent commands with children to show available subcommands
+   * when invoked without a specific subcommand.
+   *
+   * @example
+   * ```ts
+   * deploy = $command({
+   *   children: [this.vercel, this.cloudflare],
+   *   handler: async ({ help }) => {
+   *     help(); // Shows available subcommands
+   *   }
+   * });
+   * ```
+   */
+  help: () => void;
+
+  /**
+   * The current execution mode (e.g., "development", "production", "staging").
+   *
+   * Use --mode flag to set this value when running the command.
+   */
+  mode?: string;
 }