alepha 0.15.2 → 0.15.4

package/src/command/providers/CliProvider.spec.ts

@@ -24,6 +24,36 @@ class TestCliProvider extends CliProvider {
   public testFindCommand = this.findCommand.bind(this);
   public testFindPreHooks = this.findPreHooks.bind(this);
   public testFindPostHooks = this.findPostHooks.bind(this);
+  public testGetEnumValues = this.getEnumValues.bind(this);
+  public testFormatFlagDescription = this.formatFlagDescription.bind(this);
+
+  /**
+   * Extract flag definitions from a command's flags schema (for testing printHelp logic).
+   */
+  public testExtractFlagDefs(flagsSchema: any) {
+    return Object.entries(flagsSchema.properties).map(([key, value]) => ({
+      key,
+      schema: value,
+      aliases: [
+        key,
+        ...((value as any).aliases ??
+          ((value as any).alias ? [(value as any).alias] : [])),
+      ],
+      description: (value as any).description,
+    }));
+  }
+
+  /**
+   * Format aliases array into flag string (e.g., "-t, --target").
+   * Sorts by length (shorter first).
+   */
+  public testFormatFlagStr(aliases: string[]): string {
+    return aliases
+      .slice()
+      .sort((a, b) => a.length - b.length)
+      .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
+      .join(", ");
+  }
 }
 
 describe("CliProvider", () => {
@@ -130,6 +160,128 @@ describe("CliProvider", () => {
         cli.testParseFlags(["--config", "{invalid}"], flagDefs),
       ).toThrow("Invalid JSON");
     });
+
+    it("should parse union(boolean, text) flag without value as true", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i"], flagDefs);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag with = value as string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i=1.3.4"], flagDefs);
+      expect(result.image).toBe("1.3.4");
+    });
+
+    it("should parse union(boolean, text) flag with space value as string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i", "1.3.4"], flagDefs);
+      expect(result.image).toBe("1.3.4");
+    });
+
+    it("should parse union(boolean, text) flag without value when followed by another flag", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["-i", "-v"], flagDefs);
+      expect(result.image).toBe(true);
+      expect(result.verbose).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag with long form without value", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["--image"], flagDefs);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag at end of argv without value", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["-v", "-i"], flagDefs);
+      expect(result.verbose).toBe(true);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) with empty = value as empty string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      // Note: --image= results in empty string value
+      const result = cli.testParseFlags(["--image="], flagDefs);
+      // Empty string is falsy, so it goes through the "no value" path → true
+      // This is expected behavior - use --image="" if you need empty string
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) with value containing special chars", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(
+        ["--image=my-org/my-app:v1.2.3-beta"],
+        flagDefs,
+      );
+      expect(result.image).toBe("my-org/my-app:v1.2.3-beta");
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────────
@@ -439,6 +591,56 @@ describe("CliProvider", () => {
       expect(result.has(0)).toBe(true); // --name=value
       expect(result.has(1)).toBe(false); // arg
     });
+
+    it("should consume value for union(boolean, text) when value is provided", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(
+        ["-i", "1.3.4", "arg"],
+        flagDefs,
+      );
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.has(1)).toBe(true); // 1.3.4 (consumed as value)
+      expect(result.has(2)).toBe(false); // arg
+    });
+
+    it("should not consume next arg for union(boolean, text) when next is a flag", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(["-i", "-v"], flagDefs);
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.has(1)).toBe(true); // -v (not consumed by -i, but by itself)
+    });
+
+    it("should not consume next arg for union(boolean, text) at end of argv", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(["-i"], flagDefs);
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.size).toBe(1);
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────────
@@ -932,6 +1134,129 @@ describe("CliProvider", () => {
       // Just verify it doesn't throw - hidden commands filtered in getTopLevelCommands
       expect(() => cli.printHelp()).not.toThrow();
     });
+
+    it("should include flag aliases in help output", () => {
+      const cli = createTestCli();
+
+      const flagsSchema = t.object({
+        target: t.optional(
+          t.enum(["bare", "docker", "vercel"], {
+            aliases: ["t"],
+            description: "Deployment target",
+          }),
+        ),
+        runtime: t.optional(
+          t.enum(["node", "bun"], {
+            alias: "r", // singular alias
+            description: "JavaScript runtime",
+          }),
+        ),
+        verbose: t.optional(
+          t.boolean({
+            description: "Verbose output",
+          }),
+        ),
+      });
+
+      const flagDefs = cli.testExtractFlagDefs(flagsSchema);
+
+      // target should have key + aliases array
+      const targetFlag = flagDefs.find((f) => f.key === "target");
+      expect(targetFlag?.aliases).toContain("target");
+      expect(targetFlag?.aliases).toContain("t");
+      expect(cli.testFormatFlagStr(targetFlag!.aliases)).toBe("-t, --target");
+
+      // runtime should have key + alias (singular)
+      const runtimeFlag = flagDefs.find((f) => f.key === "runtime");
+      expect(runtimeFlag?.aliases).toContain("runtime");
+      expect(runtimeFlag?.aliases).toContain("r");
+      expect(cli.testFormatFlagStr(runtimeFlag!.aliases)).toBe("-r, --runtime");
+
+      // verbose should only have key (no aliases defined)
+      const verboseFlag = flagDefs.find((f) => f.key === "verbose");
+      expect(verboseFlag?.aliases).toEqual(["verbose"]);
+      expect(cli.testFormatFlagStr(verboseFlag!.aliases)).toBe("--verbose");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getEnumValues
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getEnumValues", () => {
+    it("should extract values from t.enum schema", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["yarn", "npm", "pnpm", "bun"]);
+
+      const values = cli.testGetEnumValues(schema);
+
+      expect(values).toEqual(["yarn", "npm", "pnpm", "bun"]);
+    });
+
+    it("should return undefined for non-enum schemas", () => {
+      const cli = createTestCli();
+
+      expect(cli.testGetEnumValues(t.string())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.boolean())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.number())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.object({}))).toBeUndefined();
+    });
+
+    it("should return undefined for empty or undefined schema", () => {
+      const cli = createTestCli();
+
+      expect(cli.testGetEnumValues(undefined as any)).toBeUndefined();
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // formatFlagDescription
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("formatFlagDescription", () => {
+    it("should append enum values to description", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["yarn", "npm", "pnpm", "bun"]);
+
+      const result = cli.testFormatFlagDescription(
+        "Package manager to use",
+        schema,
+      );
+
+      expect(result).toContain("Package manager to use");
+      expect(result).toContain("yarn");
+      expect(result).toContain("npm");
+      expect(result).toContain("pnpm");
+      expect(result).toContain("bun");
+    });
+
+    it("should return only enum values when description is empty", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["a", "b", "c"]);
+
+      const result = cli.testFormatFlagDescription(undefined, schema);
+
+      expect(result).toContain("a");
+      expect(result).toContain("b");
+      expect(result).toContain("c");
+    });
+
+    it("should return original description for non-enum schemas", () => {
+      const cli = createTestCli();
+
+      expect(cli.testFormatFlagDescription("A string flag", t.string())).toBe(
+        "A string flag",
+      );
+      expect(cli.testFormatFlagDescription("A boolean flag", t.boolean())).toBe(
+        "A boolean flag",
+      );
+    });
+
+    it("should return empty string when no description and no enum", () => {
+      const cli = createTestCli();
+
+      expect(cli.testFormatFlagDescription(undefined, t.string())).toBe("");
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────────

package/src/command/providers/CliProvider.ts

@@ -10,6 +10,7 @@ import {
   type Static,
   type TObject,
   type TSchema,
+  type TUnion,
   TypeBoxError,
   t,
 } from "alepha";
@@ -658,8 +659,24 @@ export class CliProvider {
         continue;
       }
 
+      // Check if schema is a union containing boolean (allows flag without value)
+      const isUnionWithBoolean =
+        t.schema.isUnion(def.schema) &&
+        (def.schema as TUnion).anyOf.some((s) => t.schema.isBoolean(s));
+
       if (t.schema.isBoolean(def.schema)) {
         result[def.key] = true;
+      } else if (isUnionWithBoolean && !value) {
+        // Union with boolean: --flag without value → true
+        const nextArg = argv[i + 1];
+        if (nextArg && !nextArg.startsWith("-")) {
+          // Has a value after space: --flag value
+          result[def.key] = nextArg;
+          i++; // consume next arg
+        } else {
+          // No value: --flag → true
+          result[def.key] = true;
+        }
       } else if (value) {
         // Value provided via --flag=value syntax
         try {
@@ -713,8 +730,24 @@ export class CliProvider {
       const def = flagDefs.find((d) => d.aliases.includes(rawKey));
       if (!def) continue;
 
+      // Check if schema is a union containing boolean
+      const isUnionWithBoolean =
+        t.schema.isUnion(def.schema) &&
+        (def.schema as TUnion).anyOf.some((s) => t.schema.isBoolean(s));
+
       // If not a boolean flag and no = value, the next arg is consumed as the value
-      if (!t.schema.isBoolean(def.schema) && !hasEqualValue) {
+      // Exception: union with boolean can work without a value
+      if (
+        !t.schema.isBoolean(def.schema) &&
+        !isUnionWithBoolean &&
+        !hasEqualValue
+      ) {
+        const nextArg = argv[i + 1];
+        if (nextArg && !nextArg.startsWith("-")) {
+          consumed.add(i + 1);
+        }
+      } else if (isUnionWithBoolean && !hasEqualValue) {
+        // Union with boolean: check if next arg looks like a value (not a flag)
         const nextArg = argv[i + 1];
         if (nextArg && !nextArg.startsWith("-")) {
           consumed.add(i + 1);
@@ -928,7 +961,11 @@ export class CliProvider {
         ...Object.entries(command.flags.properties).map(([key, value]) => ({
           key,
           schema: value,
-          aliases: (value as any).alias ?? [key],
+          aliases: [
+            key,
+            ...((value as any).aliases ??
+              ((value as any).alias ? [(value as any).alias] : [])),
+          ],
           description: (value as any).description,
         })),
         // Add --mode flag if command has mode option enabled
@@ -941,6 +978,7 @@ export class CliProvider {
                   typeof command.options.mode === "string"
                     ? `Environment mode - loads .env.{mode} (default: ${command.options.mode})`
                     : "Environment mode (e.g., production, staging) - loads .env.{mode}",
+                schema: t.string() as TSchema,
               },
             ]
           : []),
@@ -951,13 +989,20 @@ export class CliProvider {
       ];
 
       const maxFlagLength = this.getMaxFlagLength(flags);
-      for (const { aliases, description } of flags) {
-        const flagStr = (Array.isArray(aliases) ? aliases : [aliases])
+      for (const flag of flags) {
+        const { aliases, description } = flag;
+        const schema = "schema" in flag ? (flag.schema as TSchema) : undefined;
+        // Sort aliases by length (shorter first: -t before --target)
+        const sortedAliases = (Array.isArray(aliases) ? aliases : [aliases])
+          .slice()
+          .sort((a, b) => a.length - b.length);
+        const flagStr = sortedAliases
           .map((a: string) => (a.length === 1 ? `-${a}` : `--${a}`))
           .join(", ");
         const coloredFlag = c.set("GREY_LIGHT", flagStr);
         const padding = " ".repeat(Math.max(0, maxFlagLength - flagStr.length));
-        this.log.info(`    ${coloredFlag}${padding}  ${description ?? ""}`);
+        const formattedDesc = this.formatFlagDescription(description, schema);
+        this.log.info(`    ${coloredFlag}${padding}  ${formattedDesc}`);
       }
 
       // Show environment variables if defined
@@ -1024,6 +1069,7 @@ export class CliProvider {
                 []),
             ],
             description: (value as any).description,
+            schema: value as TSchema,
           }))
         : [];
 
@@ -1032,13 +1078,14 @@ export class CliProvider {
         ...Object.values(this.getAllGlobalFlags()),
       ];
       const maxFlagLength = this.getMaxFlagLength(globalFlags);
-      for (const { aliases, description } of globalFlags) {
+      for (const { aliases, description, schema } of globalFlags) {
         const flagStr = aliases
           .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
           .join(", ");
         const coloredFlag = c.set("GREY_LIGHT", flagStr);
         const padding = " ".repeat(Math.max(0, maxFlagLength - flagStr.length));
-        this.log.info(`    ${coloredFlag}${padding}  ${description ?? ""}`);
+        const formattedDesc = this.formatFlagDescription(description, schema);
+        this.log.info(`    ${coloredFlag}${padding}  ${formattedDesc}`);
       }
     }
     this.log.info(""); // Newline
@@ -1159,4 +1206,67 @@ export class CliProvider {
       }),
     );
   }
+
+  /**
+   * Extract enum values from a schema if it represents an enum.
+   * Returns undefined if the schema is not an enum.
+   */
+  protected getEnumValues(schema: TSchema): string[] | undefined {
+    if (!schema) return undefined;
+
+    // Check if schema has an enum property (t.enum creates schemas with this)
+    if (
+      "enum" in schema &&
+      Array.isArray(schema.enum) &&
+      schema.enum.every((v) => typeof v === "string")
+    ) {
+      return schema.enum as string[];
+    }
+
+    // Also check for union of string literals (alternative enum representation)
+    if (t.schema.isUnion(schema)) {
+      const union = schema as TUnion;
+      const values: string[] = [];
+
+      for (const variant of union.anyOf) {
+        // Check if the variant is a string literal (has const property)
+        if (
+          t.schema.isString(variant) &&
+          "const" in variant &&
+          typeof variant.const === "string"
+        ) {
+          values.push(variant.const);
+        } else {
+          // Not all variants are string literals, not a simple enum
+          return undefined;
+        }
+      }
+
+      return values.length > 0 ? values : undefined;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Format flag description with enum values if applicable.
+   */
+  protected formatFlagDescription(
+    description: string | undefined,
+    schema: TSchema | undefined,
+  ): string {
+    const baseDesc = description ?? "";
+
+    if (!schema) return baseDesc;
+
+    const enumValues = this.getEnumValues(schema);
+    if (enumValues && enumValues.length > 0) {
+      const valuesStr = enumValues.join(", ");
+      const c = this.color;
+      const enumHint = c.set("GREY_DARK", `[${valuesStr}]`);
+      return baseDesc ? `${baseDesc} ${enumHint}` : enumHint;
+    }
+
+    return baseDesc;
+  }
 }

package/src/core/Alepha.ts

@@ -472,44 +472,51 @@ export class Alepha {
 
     this.starting = Promise.withResolvers();
 
-    const now = Date.now();
+    try {
+      const now = Date.now();
 
-    this.log?.info("Starting App...");
+      this.log?.info("Starting App...");
 
-    for (const [key] of this.substitutions.entries()) {
-      this.inject(key);
-    }
-
-    const target = this.store.get("alepha.target");
-    if (target) {
-      this.modules = [];
-      this.registry = new Map();
-      this.primitiveRegistry = new Map();
-      this.pendingInstantiations = [];
-      this.substitutions = new Map();
-      this.events.clear();
-      delete (target as any)[MODULE];
-      this.with(target);
       for (const [key] of this.substitutions.entries()) {
         this.inject(key);
       }
-    }
 
-    this.locked = true;
+      const target = this.store.get("alepha.target");
+      if (target) {
+        this.modules = [];
+        this.registry = new Map();
+        this.primitiveRegistry = new Map();
+        this.pendingInstantiations = [];
+        this.substitutions = new Map();
+        this.events.clear();
+        delete (target as any)[MODULE];
+        this.with(target);
+        for (const [key] of this.substitutions.entries()) {
+          this.inject(key);
+        }
+      }
 
-    await this.events.emit("configure", this, { log: true });
+      this.locked = true;
 
-    this.configured = true;
+      await this.events.emit("configure", this, { log: true });
 
-    await this.events.emit("start", this, { log: true });
+      this.configured = true;
 
-    this.started = true;
+      await this.events.emit("start", this, { log: true });
 
-    await this.events.emit("ready", this, { log: true });
+      this.started = true;
 
-    this.log?.info(`App is now ready [${Date.now() - now}ms]`);
+      await this.events.emit("ready", this, { log: true });
 
-    this.ready = true;
+      this.log?.info(`App is now ready [${Date.now() - now}ms]`);
+
+      this.ready = true;
+    } catch (error) {
+      this.starting.reject(error);
+      const promise = this.starting.promise;
+      this.starting = undefined;
+      return promise;
+    }
 
     this.starting.resolve(this);
     this.starting = undefined;

package/src/email/index.workerd.ts

@@ -0,0 +1,36 @@
+import { $module } from "alepha";
+import { $email } from "./primitives/$email.ts";
+import { EmailProvider } from "./providers/EmailProvider.ts";
+import { MemoryEmailProvider } from "./providers/MemoryEmailProvider.ts";
+import { WorkermailerEmailProvider } from "./providers/WorkermailerEmailProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./errors/EmailError.ts";
+export * from "./primitives/$email.ts";
+export * from "./providers/EmailProvider.ts";
+export * from "./providers/MemoryEmailProvider.ts";
+export * from "./providers/WorkermailerEmailProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaEmail = $module({
+  name: "alepha.email",
+  primitives: [$email],
+  services: [EmailProvider, MemoryEmailProvider, WorkermailerEmailProvider],
+  register: (alepha) => {
+    if (alepha.env.EMAIL_HOST) {
+      alepha.with({
+        optional: true,
+        provide: EmailProvider,
+        use: WorkermailerEmailProvider,
+      });
+    } else {
+      alepha.with({
+        optional: true,
+        provide: EmailProvider,
+        use: MemoryEmailProvider,
+      });
+    }
+  },
+});