cli-forge 0.11.0 → 1.0.0

package/src/lib/internal-cli.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/ban-types */
 import {
   ArgvParser,
   EnvOptionConfig,
@@ -10,7 +11,14 @@ 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,
+  SDKCommand,
+} from './public-api';
 import { readOptionGroupsForCLI } from './cli-option-groups';
 import { formatHelp } from './format-help';
 
@@ -33,19 +41,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 +119,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 +149,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 +165,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 +261,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 +273,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 +286,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);
@@ -211,7 +309,7 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
 
   option<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(name: TOption, config: TOptionConfig) {
     this.parser.option(name, config);
     // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
@@ -220,58 +318,65 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
 
   positional<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(name: TOption, config: TOptionConfig) {
     this.parser.positional(name, config);
     // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
     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 +396,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 +419,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 +440,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 +450,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 +481,171 @@ 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():
+    | (<TInit extends ParsedArgs, TInitHandlerReturn, TInitChildren, TInitParent>(
+        parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>
+      ) => CLI<TInit & TArgs, TInitHandlerReturn, TInitChildren & TChildren, TInitParent>)
+    | undefined {
+    const builder = this.configuration?.builder;
+    if (!builder) return undefined;
+    // Return a composable builder that preserves input types
+    return ((parser: CLI<any, any, any, any>) => builder(parser)) 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;
+  }
+
+  sdk(): SDKCommand<TArgs, THandlerReturn, TChildren> {
+    return this.buildSDKProxy(this) as SDKCommand<
+      TArgs,
+      THandlerReturn,
+      TChildren
+    >;
+  }
+
+  private buildSDKProxy(targetCmd: InternalCLI<any, any, any, any>): unknown {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+
+    const invoke = async (
+      argsOrArgv?: Record<string, unknown> | string[]
+    ): Promise<THandlerReturn & { $args?: TArgs }> => {
+      // Clone the target command to avoid mutating the original
+      const cmd = targetCmd.clone();
+
+      const handler = cmd._configuration?.handler;
+      if (!handler) {
+        throw new Error(`Command '${cmd.name}' has no handler`);
+      }
+
+      let parsedArgs: any;
+
+      if (Array.isArray(argsOrArgv)) {
+        // String array: full pipeline (parse → validate → middleware)
+        // Run the builder first if present
+        if (cmd._configuration?.builder) {
+          cmd._configuration.builder(cmd as any);
+        }
+        parsedArgs = cmd.parser.parse(argsOrArgv);
+      } else {
+        // Object args: skip validation, apply defaults, run middleware
+        // Run the builder first to register options and get defaults
+        if (cmd._configuration?.builder) {
+          cmd._configuration.builder(cmd as any);
+        }
+        // Build defaults from configured options
+        const defaults: Record<string, unknown> = {};
+        for (const [key, config] of Object.entries(
+          cmd.parser.configuredOptions
+        )) {
+          if (config.default !== undefined) {
+            defaults[key] = config.default;
+          }
+        }
+        parsedArgs = {
+          ...defaults,
+          ...argsOrArgv,
+          unmatched: [],
+        };
+      }
+
+      // Collect and run middleware from the command chain
+      const middlewares = self.collectMiddlewareChain(targetCmd);
+      for (const mw of middlewares) {
+        const middlewareResult = await mw(parsedArgs);
+        if (
+          middlewareResult !== void 0 &&
+          typeof middlewareResult === 'object'
+        ) {
+          parsedArgs = middlewareResult;
+        }
+      }
+
+      // Execute handler
+      const context: CLIHandlerContext<any, any> = {
+        command: cmd as unknown as CLI<any, any, any, any>,
+      };
+      const result = await handler(parsedArgs, context);
+
+      // Try to attach $args to the result (fails silently for primitives)
+      if (result !== null && typeof result === 'object') {
+        try {
+          (result as any).$args = parsedArgs;
+        } catch {
+          // Cannot attach to frozen objects or primitives, return as-is
+        }
+      }
+
+      return result as any as THandlerReturn & { $args?: TArgs };
+    };
+
+    // Ensure builder has run to register all subcommands
+    if (targetCmd._configuration?.builder) {
+      targetCmd._configuration.builder(targetCmd as any);
+    }
+
+    // Create proxy that is both callable and has child properties
+    return new Proxy(invoke, {
+      get(_, prop: string) {
+        // Handle special properties
+        if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+          // Don't intercept Promise methods - this prevents issues with await
+          return undefined;
+        }
+
+        const child = targetCmd.registeredCommands[prop];
+        if (child) {
+          return self.buildSDKProxy(child);
+        }
+        return undefined;
+      },
+    });
+  }
+
+  private collectMiddlewareChain(
+    cmd: InternalCLI<any, any, any, any>
+  ): Array<(args: any) => unknown | Promise<unknown>> {
+    const chain: InternalCLI<any, any, any, any>[] = [];
+    let current: InternalCLI<any, any, any, any> | undefined = cmd;
+    while (current) {
+      chain.unshift(current);
+      current = current._parent;
+    }
+    return chain.flatMap((c) => c.registeredMiddleware);
+  }
+
+  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 +653,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 +692,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 +704,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 +719,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 +754,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 +774,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 +793,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;