alepha 0.14.0 → 0.14.1

package/src/cli/commands/DrizzleCommands.ts

@@ -3,7 +3,11 @@ import { join } from "node:path";
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
-import type { DrizzleKitProvider, RepositoryProvider } from "alepha/orm";
+import type {
+  DatabaseProvider,
+  DrizzleKitProvider,
+  RepositoryProvider,
+} from "alepha/orm";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 
 const drizzleCommandFlags = t.object({
@@ -29,7 +33,7 @@ export class DrizzleCommands {
    * Check if database migrations are up to date.
    */
   check = $command({
-    name: "db:check-migrations",
+    name: "check-migrations",
     description: "Check if database migration files are up to date",
     args: t.optional(
       t.text({
@@ -134,7 +138,7 @@ export class DrizzleCommands {
    * - Invokes Drizzle Kit's CLI to generate migration files based on the current schema.
    */
   generate = $command({
-    name: "db:generate",
+    name: "generate",
     description: "Generate migration files based on current database schema",
     summary: false,
     args: t.optional(
@@ -178,7 +182,7 @@ export class DrizzleCommands {
    * - Invokes Drizzle Kit's push command to apply schema changes directly.
    */
   push = $command({
-    name: "db:push",
+    name: "push",
     description: "Push database schema changes directly to the database",
     summary: false,
     args: t.optional(
@@ -210,7 +214,7 @@ export class DrizzleCommands {
    * - Invokes Drizzle Kit's migrate command to apply pending migrations.
    */
   migrate = $command({
-    name: "db:migrate",
+    name: "migrate",
     description: "Apply pending database migrations",
     summary: false,
     args: t.optional(
@@ -242,7 +246,7 @@ export class DrizzleCommands {
    * - Invokes Drizzle Kit's studio command to launch the web-based database browser.
    */
   studio = $command({
-    name: "db:studio",
+    name: "studio",
     description: "Launch Drizzle Studio database browser",
     summary: false,
     args: t.optional(
@@ -265,6 +269,18 @@ export class DrizzleCommands {
     },
   });
 
+  /**
+   * Parent command for database operations.
+   */
+  db = $command({
+    name: "db",
+    description: "Database management commands",
+    children: [this.check, this.generate, this.push, this.migrate, this.studio],
+    handler: async ({ help }) => {
+      help();
+    },
+  });
+
   /**
    * Run a drizzle-kit command for all database providers in an Alepha instance.
    *
@@ -289,7 +305,7 @@ export class DrizzleCommands {
       envFiles.push(`.env.${options.env}`);
     }
 
-    await this.utils.loadEnvFile(rootDir, envFiles);
+    await this.utils.loadEnv(rootDir, envFiles);
 
     this.log.debug(`Using project root: ${rootDir}`);
 
@@ -358,7 +374,7 @@ export class DrizzleCommands {
    */
   public async prepareDrizzleConfig(options: {
     kit: any;
-    provider: any;
+    provider: DatabaseProvider;
     providerName: string;
     providerUrl: string;
     dialect: string;
@@ -387,6 +403,10 @@ export class DrizzleCommands {
       },
     };
 
+    if (options.provider.schema) {
+      config.schemaFilter = options.provider.schema;
+    }
+
     if (options.providerName === "d1") {
       config.driver = "d1-http";
     }

package/src/cli/commands/ViteCommands.ts

@@ -122,11 +122,6 @@ export class ViteCommands {
           description: "Generate sitemap.xml with base URL",
         }),
       ),
-      prerender: t.optional(
-        t.boolean({
-          description: "Pre-render static pages",
-        }),
-      ),
     }),
     handler: async ({ flags, args, run, root }) => {
       // Tell viteAlephaBuild plugin to skip - CLI handles all tasks
@@ -165,7 +160,7 @@ export class ViteCommands {
       );
       const viteAlephaBuildOptions = alephaPlugin?.[OPTIONS] || {};
 
-      await this.utils.loadEnvFile(root, [".env", ".env.production"]);
+      await this.utils.loadEnv(root, [".env", ".env.production"]);
 
       const stats = flags.stats ?? viteAlephaBuildOptions.stats ?? false;
       const hasServer = viteAlephaBuildOptions.serverEntry !== false;
@@ -254,7 +249,7 @@ export class ViteCommands {
         }
 
         // Pre-render static pages
-        const shouldPrerender = flags.prerender ?? clientOptions.prerender;
+        const shouldPrerender = clientOptions.prerender;
 
         if (shouldPrerender) {
           await run({
@@ -322,7 +317,24 @@ export class ViteCommands {
   public readonly test = $command({
     name: "test",
     description: "Run tests using Vitest",
-    handler: async ({ root }) => {
+    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,
@@ -331,7 +343,9 @@ export class ViteCommands {
       // Ensure vitest is installed before running
       await this.utils.ensureDependency(root, "vitest");
 
-      await this.utils.exec(`vitest run ${this.env.VITEST_ARGS}`);
+      const config = flags.config ? `--config=${flags.config}` : "";
+
+      await this.utils.exec(`vitest run ${config} ${env.VITEST_ARGS}`);
     },
   });
 }

package/src/cli/defineConfig.ts

@@ -0,0 +1,15 @@
+import type { Alepha } from "alepha";
+import type { CommandPrimitive } from "alepha/command";
+
+export type AlephaCliConfig = (alepha: Alepha) => {
+  commands?: Record<string, CommandPrimitive>;
+};
+
+export const defineConfig = (config: AlephaCliConfig) => {
+  return (alepha: Alepha) => {
+    const { commands } = config(alepha);
+    return {
+      ...commands,
+    };
+  };
+};

package/src/cli/index.ts

@@ -1,9 +1,12 @@
 export * from "./apps/AlephaCli.ts";
 export * from "./apps/AlephaPackageBuilderCli.ts";
 export * from "./commands/BiomeCommands.ts";
+export * from "./commands/ChangelogCommands.ts";
 export * from "./commands/CoreCommands.ts";
+export * from "./commands/DeployCommands.ts";
 export * from "./commands/DrizzleCommands.ts";
 export * from "./commands/VerifyCommands.ts";
 export * from "./commands/ViteCommands.ts";
+export * from "./defineConfig.ts";
 export * from "./services/AlephaCliUtils.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/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;
 }