alepha 0.15.1 → 0.15.3

package/src/command/providers/CliProvider.ts

@@ -10,6 +10,7 @@ import {
   type Static,
   type TObject,
   type TSchema,
+  type TUnion,
   TypeBoxError,
   t,
 } from "alepha";
@@ -77,7 +78,37 @@ declare module "alepha" {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+/**
+ * CLI provider for parsing and executing commands.
+ *
+ * Handles:
+ * - Command resolution (simple, nested, colon-notation)
+ * - Flag and argument parsing
+ * - Environment variable validation
+ * - Help generation
+ * - Pre/post command hooks
+ *
+ * @example
+ * ```typescript
+ * // Define a command
+ * class MyCommands {
+ *   build = $command({
+ *     name: "build",
+ *     description: "Build the project",
+ *     flags: t.object({ watch: t.optional(t.boolean()) }),
+ *     handler: async ({ flags }) => { ... }
+ *   });
+ * }
+ *
+ * // CLI automatically discovers and executes commands
+ * const alepha = Alepha.create().with(MyCommands);
+ * ```
+ */
 export class CliProvider {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Dependencies
+  // ─────────────────────────────────────────────────────────────────────────────
+
   protected readonly env = $env(envSchema);
   protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
@@ -85,9 +116,12 @@ export class CliProvider {
   protected readonly runner = $inject(Runner);
   protected readonly asker = $inject(Asker);
   protected readonly envUtils = $inject(EnvUtils);
-
   protected readonly options = $use(cliOptions);
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Configuration
+  // ─────────────────────────────────────────────────────────────────────────────
+
   protected get name(): string {
     return this.options.name || this.env.CLI_NAME;
   }
@@ -103,6 +137,9 @@ export class CliProvider {
     );
   }
 
+  /**
+   * Global flags available to all commands.
+   */
   protected readonly globalFlags = {
     help: {
       aliases: ["h", "help"],
@@ -111,6 +148,14 @@ export class CliProvider {
     },
   };
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Lifecycle
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Main entry point - resolves and executes the command from process.argv.
+   * This is the production execution path with full lifecycle support.
+   */
   protected readonly onReady = $hook({
     on: "ready",
     handler: async () => {
@@ -119,7 +164,7 @@ export class CliProvider {
       // Extract positional arguments (potential command path)
       const positionalArgs = argv.filter((arg) => !arg.startsWith("-"));
 
-      // Resolve command using the new resolution logic
+      // Resolve command using space-separated or colon-notation
       const { command, consumedArgs } = this.resolveCommand(positionalArgs);
 
       const globalFlags = this.parseFlags(
@@ -128,6 +173,7 @@ export class CliProvider {
           key,
           ...value,
         })),
+        { strict: false }, // Don't throw for command-specific flags
       );
 
       if (globalFlags.help) {
@@ -166,7 +212,15 @@ export class CliProvider {
   });
 
   /**
-   * Execute a command with the given argv.
+   * Execute a command with full lifecycle support.
+   *
+   * This is the production execution path that includes:
+   * - Mode-based .env file loading
+   * - Pre/post command hooks
+   * - Runner session for pretty CLI output
+   * - Alepha context wrapper for proper scoping
+   *
+   * @see run() for a lightweight test-only alternative
    */
   protected async executeCommand(
     command: CommandPrimitive<TObject>,
@@ -186,7 +240,9 @@ export class CliProvider {
       await this.loadModeEnv(root, modeValue);
     }
 
-    const commandFlags = this.parseCommandFlags(argv, command.flags);
+    const commandFlags = this.parseCommandFlags(argv, command.flags, {
+      modeEnabled: !!command.options.mode,
+    });
     const commandArgs = this.parseCommandArgs(
       argv,
       command.options.args,
@@ -244,7 +300,7 @@ export class CliProvider {
   }
 
   /**
-   * Remove consumed command path arguments from argv.
+   * Remove consumed command path arguments from argv (keeps flags and remaining args).
    */
   protected removeConsumedArgs(
     argv: string[],
@@ -327,33 +383,113 @@ export class CliProvider {
     return { command: currentCommand, consumedArgs };
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Public API
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get all registered commands in the application.
+   */
   public get commands(): CommandPrimitive<any>[] {
     return this.alepha.primitives($command);
   }
 
+  /**
+   * Execute a command handler with given arguments.
+   *
+   * This is a **lightweight test helper** that directly invokes the command handler
+   * without the full production lifecycle. It intentionally skips:
+   * - Pre/post command hooks
+   * - Runner session (pretty CLI output)
+   * - Alepha context wrapper
+   * - .env.{mode} file loading
+   *
+   * For production execution, the `onReady` hook uses `executeCommand()` which
+   * provides the full lifecycle. Merging them would either make this method too
+   * heavy for simple testing or require many optional parameters to toggle behaviors.
+   *
+   * @example
+   * ```typescript
+   * // In tests
+   * const cli = alepha.inject(CliProvider);
+   * const cmd = alepha.inject(InitCommand);
+   *
+   * await cli.run(cmd.init, "--agent --pm=yarn");
+   * await cli.run(cmd.init, { argv: "--agent", root: "/project" });
+   * ```
+   */
+  public async run<T extends TObject, A extends TSchema>(
+    command: CommandPrimitive<T, A>,
+    options:
+      | string
+      | string[]
+      | { argv?: string | string[]; root?: string } = {},
+  ): Promise<void> {
+    const opts =
+      typeof options === "string" || Array.isArray(options)
+        ? { argv: options }
+        : options;
+    const args =
+      typeof opts.argv === "string"
+        ? opts.argv.split(" ").filter(Boolean)
+        : (opts.argv ?? []);
+    const root = opts.root ?? process.cwd();
+
+    const commandFlags = this.parseCommandFlags(args, command.flags, {
+      modeEnabled: !!command.options.mode,
+    });
+    const commandArgs = this.parseCommandArgs(
+      args,
+      command.options.args,
+      true,
+      command.flags,
+    );
+    const commandEnv = this.parseCommandEnv(command.env, command.name);
+
+    let modeValue: string | undefined;
+    if (command.options.mode) {
+      modeValue = this.parseModeFlag(args);
+      if (modeValue === undefined && typeof command.options.mode === "string") {
+        modeValue = command.options.mode;
+      }
+    }
+
+    await command.options.handler({
+      flags: commandFlags,
+      args: commandArgs,
+      env: commandEnv,
+      run: this.runner.run,
+      ask: this.asker.ask,
+      fs,
+      glob,
+      root,
+      help: () => this.printHelp(command),
+      mode: modeValue,
+    } as CommandHandlerArgs<T, A>);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Command Resolution
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Find a command by name or alias */
   protected findCommand(name: string): CommandPrimitive<TObject> | undefined {
     return this.commands.findLast(
       (command) => command.name === name || command.aliases.includes(name),
     );
   }
 
-  /**
-   * Find all pre-hooks for a command.
-   */
+  /** Find all pre-hooks for a command (commands named `pre{commandName}`) */
   protected findPreHooks(commandName: string): CommandPrimitive<TObject>[] {
     return this.commands.filter((cmd) => cmd.name === `pre${commandName}`);
   }
 
-  /**
-   * Find all post-hooks for a command.
-   */
+  /** Find all post-hooks for a command (commands named `post{commandName}`) */
   protected findPostHooks(commandName: string): CommandPrimitive<TObject>[] {
     return this.commands.filter((cmd) => cmd.name === `post${commandName}`);
   }
 
-  /**
-   * Get global flags (help only, root command flags are NOT global).
-   */
+  /** Get global flags (help only, root command flags are NOT global) */
   protected getAllGlobalFlags(): Record<
     string,
     { aliases: string[]; description?: string; schema: TSchema }
@@ -361,10 +497,17 @@ export class CliProvider {
     return { ...this.globalFlags };
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Parsing (Flags, Args, Env)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Parse command flags from argv using the command's flag schema */
   protected parseCommandFlags(
     argv: string[],
     schema: TObject,
+    options: { modeEnabled?: boolean } = {},
   ): Record<string, any> {
+    const { modeEnabled = false } = options;
     const flagDefs = Object.entries(schema.properties).map(([key, value]) => ({
       key,
       aliases: [
@@ -377,8 +520,21 @@ export class CliProvider {
       schema: value,
     }));
 
+    // Add mode flags if mode is enabled (they're parsed elsewhere by parseModeFlag)
+    if (modeEnabled) {
+      flagDefs.push({
+        key: "__mode__",
+        aliases: ["mode", "m"],
+        description: undefined,
+        schema: t.string(),
+      });
+    }
+
     const parsed = this.parseFlags(argv, flagDefs);
 
+    // Remove the mode flag from parsed result (it's handled separately)
+    delete parsed.__mode__;
+
     // apply manually defaults for optional properties that have defaults
     for (const [key, value] of Object.entries(schema.properties)) {
       if (!(key in parsed) && t.schema.isOptional(value)) {
@@ -401,6 +557,7 @@ export class CliProvider {
     }
   }
 
+  /** Parse and validate environment variables using the command's env schema */
   protected parseCommandEnv(
     schema: TObject,
     commandName: string,
@@ -442,9 +599,7 @@ export class CliProvider {
     }
   }
 
-  /**
-   * Parse --mode or -m flag from argv.
-   */
+  /** Parse --mode or -m flag from argv for environment file loading */
   protected parseModeFlag(argv: string[]): string | undefined {
     for (let i = 0; i < argv.length; i++) {
       const arg = argv[i];
@@ -467,9 +622,7 @@ export class CliProvider {
     return undefined;
   }
 
-  /**
-   * Load environment files based on mode.
-   */
+  /** Load .env and .env.{mode} files into process.env */
   protected async loadModeEnv(
     root: string,
     mode: string | undefined,
@@ -482,10 +635,13 @@ export class CliProvider {
     await this.envUtils.loadEnv(root, envFiles);
   }
 
+  /** Low-level flag parser - extracts flag values from argv based on definitions */
   protected parseFlags(
     argv: string[],
     flagDefs: { key: string; aliases: string[]; schema: TSchema }[],
+    options: { strict?: boolean } = {},
   ): Record<string, any> {
+    const { strict = true } = options;
     const result: Record<string, any> = {};
 
     for (let i = 0; i < argv.length; i++) {
@@ -496,10 +652,31 @@ export class CliProvider {
       let value = valueParts.join("=");
 
       const def = flagDefs.find((d) => d.aliases.includes(rawKey));
-      if (!def) continue;
+      if (!def) {
+        if (strict) {
+          throw new CommandError(`Unknown flag: --${rawKey}`);
+        }
+        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 {
@@ -534,9 +711,7 @@ export class CliProvider {
     return result;
   }
 
-  /**
-   * Get indices of argv elements that are consumed by flags (including space-separated values).
-   */
+  /** Get indices of argv elements consumed by flags (for separating args from flags) */
   protected getFlagConsumedIndices(
     argv: string[],
     flagDefs: { key: string; aliases: string[]; schema: TSchema }[],
@@ -555,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);
@@ -638,6 +829,7 @@ export class CliProvider {
     }
   }
 
+  /** Convert a string argument value to the appropriate type based on schema */
   protected parseArgumentValue(value: string, schema: TSchema): any {
     if (t.schema.isString(schema)) {
       return value;
@@ -665,6 +857,11 @@ export class CliProvider {
     return value;
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Help Generation
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Generate usage string for command arguments (e.g., "<path>" or "[path]") */
   protected generateArgsUsage(schema?: TSchema): string {
     if (!schema) {
       return "";
@@ -694,6 +891,7 @@ export class CliProvider {
     return ` <${key}${typeName}>`;
   }
 
+  /** Get display type name for a schema (e.g., ": number", ": boolean") */
   protected getTypeName(schema: TSchema): string {
     if (!schema) return "";
 
@@ -706,6 +904,12 @@ export class CliProvider {
     return "";
   }
 
+  /**
+   * Print help for a specific command or general CLI help.
+   *
+   * @param command - If provided, shows help for this specific command.
+   *                  If omitted, shows general CLI help with all commands.
+   */
   public printHelp(command?: CommandPrimitive<any>): void {
     const cliName = this.name || "cli";
     const c = this.color;
@@ -757,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
@@ -770,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,
               },
             ]
           : []),
@@ -780,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
@@ -853,6 +1069,7 @@ export class CliProvider {
                 []),
             ],
             description: (value as any).description,
+            schema: value as TSchema,
           }))
         : [];
 
@@ -861,21 +1078,20 @@ 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
   }
 
-  /**
-   * Generate colored args usage string for help display.
-   */
+  /** Generate colored usage string for command arguments (for help display) */
   protected generateColoredArgsUsage(schema?: TSchema): string {
     if (!schema) {
       return "";
@@ -907,9 +1123,7 @@ export class CliProvider {
     return ` ${c.set("CYAN", `<${key}${typeName}>`)}`;
   }
 
-  /**
-   * Get the full command path (e.g., "deploy vercel" for a child command).
-   */
+  /** Get the full command path (e.g., "deploy vercel" for a nested command) */
   protected getCommandPath(command: CommandPrimitive<any>): string {
     const path: string[] = [command.name];
     let current = command;
@@ -925,9 +1139,7 @@ export class CliProvider {
     return path.join(" ");
   }
 
-  /**
-   * Find the parent command of a given command.
-   */
+  /** Find the parent command of a nested command */
   protected findParentCommand(
     command: CommandPrimitive<any>,
   ): CommandPrimitive<any> | undefined {
@@ -939,9 +1151,7 @@ export class CliProvider {
     return undefined;
   }
 
-  /**
-   * Get top-level commands (commands that are not children of other commands).
-   */
+  /** Get top-level commands (commands that are not children of other commands) */
   protected getTopLevelCommands(): CommandPrimitive<any>[] {
     const allChildren = new Set<CommandPrimitive<any>>();
 
@@ -956,9 +1166,7 @@ export class CliProvider {
     return this.commands.filter((cmd) => !allChildren.has(cmd));
   }
 
-  /**
-   * Get max length for child command display.
-   */
+  /** Calculate max display length for child commands (for help alignment) */
   protected getMaxChildCmdLength(children: CommandPrimitive<any>[]): number {
     return Math.max(
       ...children
@@ -972,6 +1180,7 @@ export class CliProvider {
     );
   }
 
+  /** Calculate max display length for commands (for help alignment) */
   protected getMaxCmdLength(commands: CommandPrimitive[]): number {
     return Math.max(
       ...commands
@@ -986,7 +1195,8 @@ export class CliProvider {
     );
   }
 
-  private getMaxFlagLength(flags: { aliases: string[] }[]): number {
+  /** Calculate max display length for flags (for help alignment) */
+  protected getMaxFlagLength(flags: { aliases: string[] }[]): number {
     return Math.max(
       ...flags.map((f) => {
         const aliases = Array.isArray(f.aliases) ? f.aliases : [f.aliases];
@@ -996,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;
+  }
 }