cli-forge 0.11.0 → 0.12.0

package/src/lib/internal-cli.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/ban-types */
 import {
   ArgvParser,
   EnvOptionConfig,
@@ -10,7 +11,13 @@ import {
 } from '@cli-forge/parser';
 import { getCallingFile, getParentPackageJson } from './utils';
 import { INTERACTIVE_SHELL, InteractiveShell } from './interactive-shell';
-import { CLI, CLICommandOptions, Command, ErrorHandler } from './public-api';
+import {
+  CLI,
+  CLICommandOptions,
+  CLIHandlerContext,
+  Command,
+  ErrorHandler,
+} from './public-api';
 import { readOptionGroupsForCLI } from './cli-option-groups';
 import { formatHelp } from './format-help';
 
@@ -33,19 +40,30 @@ import { formatHelp } from './format-help';
  *   }).forge();
  * ```
  */
-export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
-  implements CLI<TArgs>
+export class InternalCLI<
+  TArgs extends ParsedArgs = ParsedArgs,
+  THandlerReturn = void,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TChildren = {},
+  TParent = undefined
+> implements CLI<TArgs, THandlerReturn, TChildren, TParent>
 {
   /**
    * For internal use only. Stick to properties available on {@link CLI}.
    */
-  registeredCommands: Record<string, InternalCLI<any>> = {};
+  registeredCommands: Record<string, InternalCLI<any, any, any, any>> = {};
 
   /**
    * For internal use only. Stick to properties available on {@link CLI}.
    */
   commandChain: string[] = [];
 
+  /**
+   * Reference to the parent CLI instance, if this command was registered as a subcommand.
+   * For internal use only. Use `getParent()` instead.
+   */
+  private _parent?: InternalCLI<any, any, any, any>;
+
   private requiresCommand: 'IMPLICIT' | 'EXPLICIT' | false = 'IMPLICIT';
 
   private _configuration?: CLICommandOptions<any, any>;
@@ -100,14 +118,14 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
   parser = new ArgvParser<TArgs>({
     unmatchedParser: (arg) => {
       // eslint-disable-next-line @typescript-eslint/no-this-alias
-      let currentCommand: InternalCLI<any> = this;
+      let currentCommand: InternalCLI<any, any, any, any> = this;
       for (const command of this.commandChain) {
         currentCommand = currentCommand.registeredCommands[command];
       }
       const command = currentCommand.registeredCommands[arg];
       if (command && command.configuration) {
         command.parser = this.parser;
-        command.configuration.builder?.(command);
+        command.configuration.builder?.(command as any);
         this.commandChain.push(arg);
         return true;
       }
@@ -130,10 +148,15 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
    */
   constructor(
     public name: string,
-    rootCommandConfiguration?: CLICommandOptions<TArgs>
+    rootCommandConfiguration?: CLICommandOptions<
+      TArgs,
+      any,
+      THandlerReturn,
+      TChildren
+    >
   ) {
     if (rootCommandConfiguration) {
-      this.withRootCommandConfiguration(rootCommandConfiguration);
+      this.withRootCommandConfiguration(rootCommandConfiguration as any);
     } else {
       this.requiresCommand = 'IMPLICIT';
     }
@@ -141,16 +164,87 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
 
   withRootCommandConfiguration<TRootCommandArgs extends TArgs>(
     configuration: CLICommandOptions<TArgs, TRootCommandArgs>
-  ): InternalCLI<TArgs> {
+  ): InternalCLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration = configuration;
     this.requiresCommand = false;
     return this;
   }
 
   command<TCommandArgs extends TArgs>(
-    keyOrCommand: string | Command<TArgs, TCommandArgs>,
-    options?: CLICommandOptions<TArgs, TCommandArgs>
-  ): CLI<TArgs> {
+    cmd: Command<TArgs, TCommandArgs>
+  ): CLI<
+    TArgs,
+    THandlerReturn,
+    TChildren &
+      (typeof cmd extends Command<TArgs, infer TCmdArgs, infer TCmdName>
+        ? {
+            [key in TCmdName]: CLI<
+              TCmdArgs,
+              void,
+              {},
+              CLI<TArgs, THandlerReturn, TChildren, TParent>
+            >;
+          }
+        : {}),
+    TParent
+  >;
+  command<
+    TCommandArgs extends TArgs,
+    TChildHandlerReturn = void,
+    TCommandName extends string = string
+  >(
+    key: TCommandName,
+    options: CLICommandOptions<TArgs, TCommandArgs, TChildHandlerReturn>
+  ): CLI<
+    TArgs,
+    THandlerReturn,
+    TChildren & {
+      [key in TCommandName]: CLI<
+        TCommandArgs,
+        TChildHandlerReturn,
+        {},
+        CLI<TArgs, THandlerReturn, TChildren, TParent>
+      >;
+    },
+    TParent
+  >;
+  command<
+    TCommandArgs extends TArgs,
+    TChildHandlerReturn = void,
+    TCommandName extends string = string
+  >(
+    keyOrCommand: TCommandName | Command<TArgs, TCommandArgs>,
+    options?: CLICommandOptions<TArgs, TCommandArgs, TChildHandlerReturn>
+  ): CLI<
+    TArgs,
+    THandlerReturn,
+    TChildren &
+      (typeof keyOrCommand extends string
+        ? {
+            [key in typeof keyOrCommand]: CLI<
+              TCommandArgs,
+              TChildHandlerReturn,
+              {},
+              CLI<TArgs, THandlerReturn, TChildren, TParent>
+            >;
+          }
+        : typeof keyOrCommand extends Command<
+            TArgs,
+            infer TCmdArgs,
+            infer TCmdName
+          >
+        ? {
+            [key in TCmdName]: CLI<
+              TCmdArgs,
+              void,
+              {},
+              CLI<TArgs, THandlerReturn, TChildren, TParent>
+            >;
+          }
+        : // eslint-disable-next-line @typescript-eslint/ban-types
+          {}),
+    TParent
+  > {
     if (typeof keyOrCommand === 'string') {
       const key = keyOrCommand;
       if (!options) {
@@ -166,9 +260,10 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
           description: options.description,
         });
       }
-      const cmd = new InternalCLI<TArgs>(key).withRootCommandConfiguration(
-        options
-      );
+      const cmd = new InternalCLI<TArgs, TChildHandlerReturn>(
+        key
+      ).withRootCommandConfiguration(options as any);
+      cmd._parent = this;
       this.registeredCommands[key] = cmd;
       if (options.alias) {
         for (const alias of options.alias) {
@@ -177,6 +272,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       }
     } else if (keyOrCommand instanceof InternalCLI) {
       const cmd = keyOrCommand;
+      cmd._parent = this;
       this.registeredCommands[cmd.name] = cmd;
       if (cmd.configuration?.alias) {
         for (const alias of cmd.configuration.alias) {
@@ -189,13 +285,14 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       } & CLICommandOptions<TArgs, TCommandArgs>;
       this.command<TCommandArgs>(name, configuration);
     }
-    return this;
+    return this as any;
   }
 
-  commands(...a0: Command[] | Command[][]): CLI<TArgs> {
+  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);
@@ -227,51 +324,58 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     return this as any;
   }
 
-  conflicts(...args: [string, string, ...string[]]): CLI<TArgs> {
+  conflicts(
+    ...args: [string, string, ...string[]]
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.parser.conflicts(...args);
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
-  implies(option: string, ...impliedOptions: string[]): CLI<TArgs> {
+  implies(
+    option: string,
+    ...impliedOptions: string[]
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.parser.implies(option, ...impliedOptions);
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   env(
     a0: string | EnvOptionConfig | undefined = fromCamelOrDashedCaseToConstCase(
       this.name
     )
-  ) {
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     if (typeof a0 === 'string') {
       this.parser.env(a0);
     } else {
       a0.prefix ??= fromCamelOrDashedCaseToConstCase(this.name);
       this.parser.env(a0);
     }
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
-  demandCommand() {
+  demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.requiresCommand = 'EXPLICIT';
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
-  usage(usageText: string) {
+  usage(usageText: string): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration ??= {};
     this.configuration.usage = usageText;
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
-  examples(...examples: string[]) {
+  examples(
+    ...examples: string[]
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration ??= {};
     this.configuration.examples ??= [];
     this.configuration.examples.push(...examples);
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
-  version(version?: string) {
+  version(version?: string): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this._versionOverride = version;
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   /**
@@ -291,7 +395,12 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
 
   middleware<TArgs2>(
     callback: (args: TArgs) => TArgs2 | Promise<TArgs2>
-  ): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2> {
+  ): CLI<
+    TArgs2 extends void ? TArgs : TArgs & TArgs2,
+    THandlerReturn,
+    TChildren,
+    TParent
+  > {
     this.registeredMiddleware.push(callback);
     // If middleware returns void, TArgs doesn't change...
     // If it returns something, we need to merge it into TArgs...
@@ -309,7 +418,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       ...this.registeredMiddleware,
     ];
     // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let cmd: InternalCLI<any> = this;
+    let cmd: InternalCLI<any, any, any, any> = this;
     for (const command of this.commandChain) {
       cmd = cmd.registeredCommands[command];
       middlewares.push(...cmd.registeredMiddleware);
@@ -330,8 +439,8 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
             args = middlewareResult as T;
           }
         }
-        await cmd.configuration.handler(args, {
-          command: cmd,
+        return cmd.configuration.handler(args, {
+          command: cmd as any,
         });
       } else {
         // We can treat a command as a subshell if it has subcommands
@@ -340,9 +449,12 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
             // If we're not in a TTY, we can't run an interactive shell...
             // Maybe we should warn here?
           } else if (!INTERACTIVE_SHELL) {
-            const tui = new InteractiveShell(this, {
-              prependArgs: originalArgV,
-            });
+            const tui = new InteractiveShell(
+              this as unknown as InternalCLI<any>,
+              {
+                prependArgs: originalArgV,
+              }
+            );
             await new Promise<void>((res) => {
               ['SIGINT', 'SIGTERM', 'SIGQUIT'].forEach((s) =>
                 process.on(s, () => {
@@ -368,7 +480,50 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     }
   }
 
-  enableInteractiveShell() {
+  getChildren(): TChildren {
+    // Return a copy of registered commands, excluding aliases (same command registered under different keys)
+    const children: Record<string, InternalCLI<any, any, any, any>> = {};
+    const seen = new Set<InternalCLI<any, any, any, any>>();
+    for (const [key, cmd] of Object.entries(this.registeredCommands)) {
+      if (!seen.has(cmd)) {
+        seen.add(cmd);
+        children[key] = cmd;
+      }
+    }
+    return children as TChildren;
+  }
+
+  getParent(): TParent {
+    return this._parent as TParent;
+  }
+
+  getBuilder<T extends ParsedArgs = { unmatched: string[]; '--'?: string[] }>(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- This is used to help TS infer T correctly
+    _?: CLI<T, any, any> | undefined
+  ):
+    | ((parser: CLI<T, any, any>) => CLI<TArgs, THandlerReturn, TChildren>)
+    | undefined {
+    return this.configuration?.builder as any;
+  }
+
+  getHandler():
+    | ((args: Omit<TArgs, keyof ParsedArgs>) => THandlerReturn)
+    | undefined {
+    const context: CLIHandlerContext<TChildren, TParent> = {
+      command: this as unknown as CLI<any, any, TChildren, TParent>,
+    };
+    const handler = this._configuration?.handler;
+    if (!handler) {
+      return undefined;
+    }
+    return (args: Omit<TArgs, keyof ParsedArgs>) =>
+      handler(
+        args as TArgs,
+        context as CLIHandlerContext<any, any>
+      ) as THandlerReturn;
+  }
+
+  enableInteractiveShell(): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     if (this.requiresCommand === 'EXPLICIT') {
       throw new Error(
         'Interactive shell is not supported for commands that require a command.'
@@ -376,7 +531,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     } else if (process.stdout.isTTY) {
       this.requiresCommand = false;
     }
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   private versionHandler() {
@@ -415,9 +570,11 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     }
   }
 
-  errorHandler(handler: ErrorHandler) {
+  errorHandler(
+    handler: ErrorHandler
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.registeredErrorHandlers.unshift(handler);
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   group(
@@ -425,7 +582,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       | string
       | { label: string; keys: (keyof TArgs)[]; sortOrder: number },
     keys?: (keyof TArgs)[]
-  ): CLI<TArgs> {
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     const config =
       typeof labelOrConfigObject === 'object'
         ? labelOrConfigObject
@@ -440,16 +597,16 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     }
 
     this.registeredOptionGroups.push(config);
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   config(
     provider: ConfigurationFiles.ConfigurationProvider<TArgs>
-  ): CLI<TArgs> {
+  ): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.parser.config(
       provider as ConfigurationFiles.ConfigurationProvider<any>
     );
-    return this;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
   /**
@@ -475,7 +632,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
         }
       }
       // eslint-disable-next-line @typescript-eslint/no-this-alias
-      let currentCommand: InternalCLI<any> = this;
+      let currentCommand: InternalCLI<any, any, any, any> = this;
       for (const command of this.commandChain) {
         currentCommand = currentCommand.registeredCommands[command];
       }
@@ -495,7 +652,9 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       const finalArgV =
         this.commandChain.length === 0 && this.configuration?.builder
           ? (
-              this.configuration.builder?.(this as any) as InternalCLI<TArgs>
+              this.configuration.builder?.(
+                this as any
+              ) as unknown as InternalCLI<TArgs, any, any, any>
             ).parser.parse(args)
           : argv;
 
@@ -512,15 +671,16 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
   }
 
   clone() {
-    const clone = new InternalCLI<TArgs>(this.name);
+    const clone = new InternalCLI<TArgs, THandlerReturn, TChildren, TParent>(
+      this.name
+    );
     clone.parser = this.parser.clone(clone.parser.options) as any;
     if (this.configuration) {
       clone.withRootCommandConfiguration(this.configuration);
     }
     clone.registeredCommands = {};
     for (const command in this.registeredCommands ?? {}) {
-      clone.command(this.registeredCommands[command].clone());
-      // this.registeredCommands[command].clone();
+      clone.command(this.registeredCommands[command].clone() as any);
     }
     clone.commandChain = [...this.commandChain];
     clone.requiresCommand = this.requiresCommand;