cli-forge 1.0.2 → 1.2.0

package/src/lib/internal-cli.ts

@@ -2,6 +2,8 @@
 import {
   ArgvParser,
   EnvOptionConfig,
+  LocalizationDictionary,
+  LocalizationFunction,
   OptionConfig,
   ParsedArgs,
   ValidationFailedError,
@@ -9,7 +11,8 @@ import {
   hideBin,
   type ConfigurationFiles,
 } from '@cli-forge/parser';
-import { getCallingFile, getParentPackageJson } from './utils';
+import { readOptionGroupsForCLI } from './cli-option-groups';
+import { formatHelp } from './format-help';
 import { INTERACTIVE_SHELL, InteractiveShell } from './interactive-shell';
 import {
   CLI,
@@ -19,8 +22,7 @@ import {
   ErrorHandler,
   SDKCommand,
 } from './public-api';
-import { readOptionGroupsForCLI } from './cli-option-groups';
-import { formatHelp } from './format-help';
+import { getCallingFile, getParentPackageJson } from './utils';
 
 /**
  * The base class for a CLI application. This class is used to define the structure of the CLI.
@@ -83,7 +85,13 @@ export class InternalCLI<
     },
   ];
 
-  private registeredMiddleware: Array<(args: TArgs) => void> = [];
+  private registeredMiddleware = new Set<
+    (args: TArgs) => void | unknown | Promise<void> | Promise<unknown>
+  >();
+
+  private registeredInitHooks: Array<
+    (cli: any, args: TArgs) => Promise<void> | void
+  > = [];
 
   /**
    * A list of option groups that have been registered with the CLI. Grouped Options are displayed together in the help text.
@@ -167,7 +175,7 @@ export class InternalCLI<
     configuration: CLICommandOptions<TArgs, TRootCommandArgs>
   ): InternalCLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration = configuration;
-    this.requiresCommand = false;
+    this.requiresCommand = configuration.handler ? false : 'IMPLICIT';
     return this;
   }
 
@@ -266,7 +274,18 @@ export class InternalCLI<
         key
       ).withRootCommandConfiguration(options as any);
       cmd._parent = this;
+
+      // Get localized command name
+      const localizedKey = this.getLocalizedCommandName(key);
+
+      // Register under the default key
       this.registeredCommands[key] = cmd;
+
+      // If localized name is different, also register under localized name as an alias
+      if (localizedKey !== key) {
+        this.registeredCommands[localizedKey] = cmd;
+      }
+
       if (options.alias) {
         for (const alias of options.alias) {
           this.registeredCommands[alias] = cmd;
@@ -274,6 +293,10 @@ export class InternalCLI<
       }
     } else if (keyOrCommand instanceof InternalCLI) {
       const cmd = keyOrCommand;
+      if (cmd.name === '$0') {
+        this.withRootCommandConfiguration(cmd.configuration as any);
+        return this as any;
+      }
       cmd._parent = this;
       this.registeredCommands[cmd.name] = cmd;
       if (cmd.configuration?.alias) {
@@ -293,17 +316,7 @@ export class InternalCLI<
   commands(...a0: Command[] | Command[][]): any {
     const commands = a0.flat();
     for (const val of commands) {
-      if (val instanceof InternalCLI) {
-        val._parent = this;
-        this.registeredCommands[val.name] = val;
-        // Include any options that were defined via cli(...).option() instead of via builder
-        this.parser.augment(val.parser);
-      } else {
-        const { name, ...configuration } = val as {
-          name: string;
-        } & CLICommandOptions<any, any>;
-        this.command(name, configuration);
-      }
+      this.command(val);
     }
     return this;
   }
@@ -355,11 +368,37 @@ export class InternalCLI<
     return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
+  localize(
+    dictionaryOrFn: LocalizationDictionary | LocalizationFunction,
+    locale?: string
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
+    if (typeof dictionaryOrFn === 'function') {
+      this.parser.localize(dictionaryOrFn);
+    } else {
+      this.parser.localize(dictionaryOrFn, locale);
+    }
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  }
+
+  /**
+   * Gets the localized display name for a command key.
+   * @param key The command key
+   * @returns The localized command name, or the original key if not localized
+   */
+  getLocalizedCommandName(key: string): string {
+    return this.parser.getDisplayKey(key);
+  }
+
   demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.requiresCommand = 'EXPLICIT';
     return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
+  strict(enable = true): CLI<TArgs, THandlerReturn, TChildren, TParent> {
+    this.parser.options.strict = enable;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  }
+
   usage(usageText: string): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration ??= {};
     this.configuration.usage = usageText;
@@ -396,34 +435,48 @@ export class InternalCLI<
   }
 
   middleware<TArgs2>(
-    callback: (args: TArgs) => TArgs2 | Promise<TArgs2>
+    callback: (args: TArgs) => TArgs2 | Promise<TArgs2> | void | Promise<void>
   ): CLI<
     TArgs2 extends void ? TArgs : TArgs & TArgs2,
     THandlerReturn,
     TChildren,
     TParent
   > {
-    this.registeredMiddleware.push(callback);
+    this.registeredMiddleware.add(callback);
     // If middleware returns void, TArgs doesn't change...
     // If it returns something, we need to merge it into TArgs...
     // that's not here though, its where we apply the middleware results.
     return this as any;
   }
 
+  init(
+    callback: (
+      cli: CLI<TArgs, THandlerReturn, TChildren, TParent>,
+      args: TArgs
+    ) => Promise<void> | void
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
+    this.registeredInitHooks.push(callback);
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  }
+
   /**
    * Runs the current command.
    * @param cmd The command to run.
    * @param args The arguments to pass to the command.
    */
-  async runCommand<T extends ParsedArgs>(args: T, originalArgV: string[]) {
-    const middlewares: Array<(args: any) => void> = [
-      ...this.registeredMiddleware,
-    ];
+  async runCommand<T extends ParsedArgs>(
+    args: T,
+    originalArgV: string[],
+    executedMiddleware?: Set<(args: any) => void>
+  ): Promise<T> {
+    const middlewares = new Set<(args: any) => void>(this.registeredMiddleware);
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     let cmd: InternalCLI<any, any, any, any> = this;
     for (const command of this.commandChain) {
       cmd = cmd.registeredCommands[command];
-      middlewares.push(...cmd.registeredMiddleware);
+      for (const mw of cmd.registeredMiddleware) {
+        middlewares.add(mw);
+      }
     }
     try {
       if (cmd.requiresCommand) {
@@ -433,7 +486,8 @@ export class InternalCLI<
       }
       if (cmd.configuration?.handler) {
         for (const middleware of middlewares) {
-          const middlewareResult = await middleware(args);
+          if (executedMiddleware?.has(middleware)) continue;
+          const middlewareResult = await middleware(args as any);
           if (
             middlewareResult !== void 0 &&
             typeof middlewareResult === 'object'
@@ -441,15 +495,25 @@ export class InternalCLI<
             args = middlewareResult as T;
           }
         }
-        return cmd.configuration.handler(args, {
+        await cmd.configuration.handler(args, {
           command: cmd as any,
         });
+        return args;
       } else {
         // We can treat a command as a subshell if it has subcommands
         if (Object.keys(cmd.registeredCommands).length > 0) {
           if (!process.stdout.isTTY) {
             // If we're not in a TTY, we can't run an interactive shell...
             // Maybe we should warn here?
+          } else if (args.unmatched.length > 0) {
+            // If there are unmatched args, we don't run an interactive shell...
+            // this could represent a user misspelling a subcommand so it gets rather confusing.
+            console.warn(
+              `Warning: Unrecognized command or arguments: ${args.unmatched.join(
+                ' '
+              )}`
+            );
+            cmd.printHelp();
           } else if (!INTERACTIVE_SHELL) {
             const tui = new InteractiveShell(
               this as unknown as InternalCLI<any>,
@@ -480,6 +544,7 @@ export class InternalCLI<
       console.error(e);
       this.printHelp();
     }
+    return args;
   }
 
   getChildren(): TChildren {
@@ -500,9 +565,19 @@ export class InternalCLI<
   }
 
   getBuilder():
-    | (<TInit extends ParsedArgs, TInitHandlerReturn, TInitChildren, TInitParent>(
+    | (<
+        TInit extends ParsedArgs,
+        TInitHandlerReturn,
+        TInitChildren,
+        TInitParent
+      >(
         parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>
-      ) => CLI<TInit & TArgs, TInitHandlerReturn, TInitChildren & TChildren, TInitParent>)
+      ) => CLI<
+        TInit & TArgs,
+        TInitHandlerReturn,
+        TInitChildren & TChildren,
+        TInitParent
+      >)
     | undefined {
     const builder = this.configuration?.builder;
     if (!builder) return undefined;
@@ -643,7 +718,13 @@ export class InternalCLI<
       chain.unshift(current);
       current = current._parent;
     }
-    return chain.flatMap((c) => c.registeredMiddleware);
+    const seen = new Set<(args: any) => unknown | Promise<unknown>>();
+    for (const c of chain) {
+      for (const mw of c.registeredMiddleware) {
+        seen.add(mw);
+      }
+    }
+    return [...seen];
   }
 
   enableInteractiveShell(): CLI<TArgs, THandlerReturn, TChildren, TParent> {
@@ -703,7 +784,7 @@ export class InternalCLI<
   group(
     labelOrConfigObject:
       | string
-      | { label: string; keys: (keyof TArgs)[]; sortOrder: number },
+      | { label: string; keys: (keyof TArgs)[]; sortOrder?: number },
     keys?: (keyof TArgs)[]
   ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     const config =
@@ -712,14 +793,17 @@ export class InternalCLI<
         : {
             label: labelOrConfigObject,
             keys: keys as (keyof TArgs)[],
-            sortOrder: Object.keys(this.registeredOptionGroups).length,
           };
 
     if (!config.keys) {
       throw new Error('keys must be provided when calling `group`.');
     }
 
-    this.registeredOptionGroups.push(config);
+    this.registeredOptionGroups.push({
+      ...config,
+      sortOrder:
+        config.sortOrder ?? Object.keys(this.registeredOptionGroups).length,
+    });
     return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
@@ -733,32 +817,128 @@ export class InternalCLI<
   }
 
   /**
-   * Parses argv and executes the CLI
+   * Parses argv and executes the CLI.
+   *
+   * Execution proceeds in two phases:
+   *
+   * **Discovery loop** (per command level): builder → parse (non-strict,
+   * no validation) → merge → middleware → init hooks → find next
+   * subcommand in unmatched tokens → repeat.
+   *
+   * **Final parse + execution**: parse (with validation, seeded with
+   * accumulated args) → help/version check → handler. Middleware that
+   * already ran during discovery is skipped.
+   *
    * @param args argv. Defaults to process.argv.slice(2)
    * @returns Promise that resolves when the handler completes.
    */
   forge = (args: string[] = hideBin(process.argv)) =>
     this.withErrorHandlers(async () => {
-      // Parsing the args does two things:
-      // - builds argv to pass to handler
-      // - fills the command chain + registers commands
       let argv: TArgs & { help?: boolean; version?: boolean };
       let validationFailedError: ValidationFailedError<TArgs> | undefined;
+
+      // Run root builder (may register options, init hooks, commands)
+      this.configuration?.builder?.(this as any);
+
+      // Merge helper: accumulate defined values without overwriting
+      const mergeNew = (target: any, source: any) => {
+        for (const [key, value] of Object.entries(source)) {
+          if (key !== 'unmatched' && value !== undefined && target[key] === undefined) {
+            target[key] = value;
+          }
+        }
+      };
+
+      // Iterative command discovery with init hooks.
+      // Each level: non-strict parse filtered args → run middleware
+      // → run init hooks → find next command in unmatched tokens
+      // → filter down. Builders stay lazy.
+      let currentArgs = [...args];
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      let currentCmd: InternalCLI<any, any, any, any> = this;
+      const mergedArgs: any = {};
+      const executedMiddleware = new Set<(args: any) => void>();
+
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        // Non-strict parse to get current arg values for init hooks.
+        // Seeded with mergedArgs so required options parsed at earlier
+        // levels satisfy validation.
+        const parsed = this.parser
+          .clone({
+            ...this.parser.options,
+            unmatchedParser: () => false,
+            strict: false,
+            validate: false,
+          })
+          .parse(currentArgs, mergedArgs) as any;
+
+        mergeNew(mergedArgs, parsed);
+
+        // Run middleware for this command level before init hooks,
+        // so init hooks can see middleware-transformed args.
+        for (const mw of currentCmd.registeredMiddleware) {
+          if (!executedMiddleware.has(mw)) {
+            executedMiddleware.add(mw);
+            const result = await mw(mergedArgs);
+            if (result !== void 0 && typeof result === 'object') {
+              Object.assign(mergedArgs, result);
+            }
+          }
+        }
+
+        // Run init hooks with the full accumulated args
+        for (const hook of currentCmd.registeredInitHooks) {
+          await hook(currentCmd as any, mergedArgs);
+        }
+
+        // Find the next command in unmatched tokens
+        const unmatched: string[] = parsed.unmatched ?? [];
+        let nextCmd: InternalCLI<any, any, any, any> | null = null;
+        const remainingArgs: string[] = [];
+
+        for (const token of unmatched) {
+          if (!nextCmd && !token.startsWith('-')) {
+            const cmd = currentCmd.registeredCommands[token];
+            if (cmd && cmd.configuration) {
+              cmd.parser = this.parser;
+              cmd.configuration.builder?.(cmd as any);
+              this.commandChain.push(token);
+              nextCmd = cmd;
+              continue;
+            }
+          }
+          remainingArgs.push(token);
+        }
+
+        if (!nextCmd) {
+          currentArgs = unmatched;
+          break;
+        }
+        currentArgs = remainingArgs;
+        currentCmd = nextCmd;
+      }
+
+      // All builders and init hooks have run. The parser now has
+      // all options registered. Parse the remaining unmatched tokens
+      // seeded with the accumulated values from the discovery loop.
+      // The alreadyParsed values ensure proper required-option
+      // validation and prevent positional re-consumption.
       try {
-        argv = this.parser.parse(args);
+        argv = this.parser
+          .clone({
+            ...this.parser.options,
+            unmatchedParser: () => false,
+          })
+          .parse(currentArgs, mergedArgs) as any;
       } catch (e) {
         if (e instanceof ValidationFailedError) {
-          argv = e.partialArgV as TArgs;
+          argv = e.partialArgV as any;
           validationFailedError = e;
         } else {
           throw e;
         }
       }
-      // eslint-disable-next-line @typescript-eslint/no-this-alias
-      let currentCommand: InternalCLI<any, any, any, any> = this;
-      for (const command of this.commandChain) {
-        currentCommand = currentCommand.registeredCommands[command];
-      }
 
       if (argv.version) {
         this.versionHandler();
@@ -772,16 +952,7 @@ export class InternalCLI<
         throw validationFailedError;
       }
 
-      const finalArgV =
-        this.commandChain.length === 0 && this.configuration?.builder
-          ? (
-              this.configuration.builder?.(
-                this as any
-              ) as unknown as InternalCLI<TArgs, any, any, any>
-            ).parser.parse(args)
-          : argv;
-
-      await this.runCommand(finalArgV, args);
+      const finalArgV = await this.runCommand(argv, args, executedMiddleware);
       return finalArgV as TArgs;
     });
 

package/src/lib/public-api.ts

@@ -1,18 +1,20 @@
 /* eslint-disable @typescript-eslint/ban-types */
 import {
+  ArrayOptionConfig,
+  BooleanOptionConfig,
   type ConfigurationFiles,
+  EnvOptionConfig,
+  LocalizationDictionary,
+  LocalizationFunction,
+  MakeUndefinedPropertiesOptional,
+  NumberOptionConfig,
+  ObjectOptionConfig,
   OptionConfig,
   OptionConfigToType,
   ParsedArgs,
-  EnvOptionConfig,
-  ObjectOptionConfig,
-  StringOptionConfig,
-  NumberOptionConfig,
-  BooleanOptionConfig,
-  ArrayOptionConfig,
   ResolveProperties,
+  StringOptionConfig,
   WithOptional,
-  MakeUndefinedPropertiesOptional,
 } from '@cli-forge/parser';
 
 import { InternalCLI } from './internal-cli';
@@ -651,6 +653,51 @@ export interface CLI<
 
   env(options: EnvOptionConfig): CLI<TArgs, THandlerReturn, TChildren, TParent>;
 
+  /**
+   * Sets up localization for option keys and other text.
+   * When localization is enabled, option keys will be displayed in the specified locale in help text and documentation,
+   * and both the default and localized keys will be accepted when parsing arguments.
+   *
+   * @param dictionary The localization dictionary mapping keys to their translations
+   * @param locale The target locale (defaults to system locale if not provided)
+   * @returns Updated CLI instance for chaining
+   *
+   * @example
+   * ```ts
+   * cli('myapp')
+   *   .localize({
+   *     name: { default: 'name', 'es-ES': 'nombre' },
+   *     port: { default: 'port', 'es-ES': 'puerto' }
+   *   }, 'es-ES')
+   *   .option('name', { type: 'string' })
+   *   .option('port', { type: 'number' });
+   * ```
+   */
+  localize(
+    dictionary: LocalizationDictionary,
+    locale?: string
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  /**
+   * Sets up localization using a custom function for translating keys.
+   * This allows integration with existing localization libraries like i18next.
+   *
+   * @param fn A function that takes a key and returns its localized value
+   * @returns Updated CLI instance for chaining
+   *
+   * @example
+   * ```ts
+   * import i18next from 'i18next';
+   *
+   * cli('myapp')
+   *   .localize((key) => i18next.t(key))
+   *   .option('name', { type: 'string' })
+   *   .option('port', { type: 'number' });
+   * ```
+   */
+  localize(
+    fn: LocalizationFunction
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+
   /**
    * Sets a group of options as mutually exclusive. If more than one option is provided, there will be a validation error.
    * @param options The options that should be mutually exclusive.
@@ -676,6 +723,15 @@ export interface CLI<
    */
   demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent>;
 
+  /**
+   * Enables or disables strict mode. When strict mode is enabled, the parser throws a validation error
+   * when unmatched arguments are encountered. Unmatched arguments are those that don't match any
+   * configured option or positional argument.
+   * @param enable Whether to enable strict mode. Defaults to true.
+   * @returns Updated CLI instance.
+   */
+  strict(enable?: boolean): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+
   /**
    * Sets the usage text for the CLI. This text will be displayed in place of the default usage text
    * @param usageText Text displayed in place of the default usage text for `--help` and in generated docs.
@@ -709,7 +765,7 @@ export interface CLI<
   }: {
     label: string;
     keys: (keyof TArgs)[];
-    sortOrder: number;
+    sortOrder?: number;
   }): CLI<TArgs, THandlerReturn, TChildren, TParent>;
   group(
     label: string,
@@ -725,6 +781,21 @@ export interface CLI<
     TParent
   >;
 
+  /**
+   * Registers an init hook that runs before command resolution.
+   * Init hooks receive partially-parsed args (from currently-registered options)
+   * and can modify the CLI (register commands, options, middleware) before the
+   * full parse runs. This enables plugin loading from config files.
+   *
+   * @param callback Async function receiving (args, cli). Mutate cli to add commands/options.
+   */
+  init(
+    callback: (
+      cli: CLI<TArgs, THandlerReturn, TChildren, TParent>,
+      args: TArgs
+    ) => Promise<void> | void
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+
   /**
    * Parses argv and executes the CLI
    * @param args argv. Defaults to process.argv.slice(2)
@@ -853,7 +924,7 @@ export interface CLICommandOptions<
    * The type of the arguments that are registered after `builder` is invoked, and the type that is passed to the handler.
    */
   TArgs extends TInitial = TInitial,
-  THandlerReturn = void,
+  THandlerReturn = void | Promise<void>,
   /**
    * The children commands that exist before the builder runs.
    */