cli-forge 0.12.0 → 1.0.1

package/src/lib/internal-cli.ts

@@ -17,6 +17,7 @@ import {
   CLIHandlerContext,
   Command,
   ErrorHandler,
+  SDKCommand,
 } from './public-api';
 import { readOptionGroupsForCLI } from './cli-option-groups';
 import { formatHelp } from './format-help';
@@ -170,22 +171,19 @@ export class InternalCLI<
     return this;
   }
 
-  command<TCommandArgs extends TArgs>(
-    cmd: Command<TArgs, TCommandArgs>
+  command<TCommandArgs extends TArgs, TCmdName extends string>(
+    cmd: Command<TArgs, TCommandArgs, TCmdName>
   ): CLI<
     TArgs,
     THandlerReturn,
-    TChildren &
-      (typeof cmd extends Command<TArgs, infer TCmdArgs, infer TCmdName>
-        ? {
-            [key in TCmdName]: CLI<
-              TCmdArgs,
-              void,
-              {},
-              CLI<TArgs, THandlerReturn, TChildren, TParent>
-            >;
-          }
-        : {}),
+    TChildren & {
+      [key in TCmdName]: CLI<
+        TCommandArgs,
+        void,
+        {},
+        CLI<TArgs, THandlerReturn, TChildren, TParent>
+      >;
+    },
     TParent
   >;
   command<
@@ -308,7 +306,7 @@ export class InternalCLI<
 
   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 🤔
@@ -317,7 +315,7 @@ export class InternalCLI<
 
   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 🤔
@@ -497,13 +495,15 @@ export class InternalCLI<
     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>)
+  getBuilder():
+    | (<TInit extends ParsedArgs, TInitHandlerReturn, TInitChildren, TInitParent>(
+        parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>
+      ) => CLI<TInit & TArgs, TInitHandlerReturn, TInitChildren & TChildren, TInitParent>)
     | undefined {
-    return this.configuration?.builder as any;
+    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():
@@ -523,6 +523,125 @@ export class InternalCLI<
       ) 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(

package/src/lib/public-api.ts

@@ -13,7 +13,6 @@ import {
   ResolveProperties,
   WithOptional,
   MakeUndefinedPropertiesOptional,
-  WithAdditionalProperties,
 } from '@cli-forge/parser';
 
 import { InternalCLI } from './internal-cli';
@@ -90,22 +89,19 @@ export interface CLI<
   TChildren = {},
   TParent = undefined
 > {
-  command<TCommandArgs extends TArgs>(
-    cmd: Command<TArgs, TCommandArgs>
+  command<TCommandArgs extends TArgs, TCmdName extends string>(
+    cmd: Command<TArgs, TCommandArgs, TCmdName>
   ): CLI<
     TArgs,
     THandlerReturn,
-    TChildren &
-      (typeof cmd extends Command<TArgs, infer TCommandArgs, infer TCmdName>
-        ? {
-            [key in TCmdName]: CLI<
-              TCommandArgs,
-              void,
-              {},
-              CLI<TArgs, THandlerReturn, TChildren, TParent>
-            >;
-          }
-        : {}),
+    TChildren & {
+      [key in TCmdName]: CLI<
+        TCommandArgs,
+        void,
+        {},
+        CLI<TArgs, THandlerReturn, TChildren, TParent>
+      >;
+    },
     TParent
   >;
 
@@ -127,7 +123,7 @@ export interface CLI<
       TArgs,
       TCommandArgs,
       TChildHandlerReturn,
-      any,
+      TChildren,
       CLI<TArgs, THandlerReturn, TChildren, TParent>,
       TChildChildren
     >
@@ -436,22 +432,16 @@ export interface CLI<
   option<
     TOption extends string,
     TCoerce,
-    const TProps extends Record<string, { type: string }>,
-    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+    const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+    config: ObjectOptionConfig<TCoerce, TProps>
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
         [key in TOption]: WithOptional<
-          unknown extends TCoerce
-            ? WithAdditionalProperties<
-                ResolveProperties<TProps>,
-                TAdditionalProps
-              >
-            : TCoerce,
-          ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,
+          ObjectOptionConfig<TCoerce, TProps>
         >;
       }>,
     THandlerReturn,
@@ -525,7 +515,7 @@ export interface CLI<
   // Generic fallback overload
   option<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
     config: TOptionConfig
@@ -552,22 +542,16 @@ export interface CLI<
   positional<
     TOption extends string,
     TCoerce,
-    const TProps extends Record<string, { type: string }>,
-    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+    const TProps extends Record<string, { type: string }>
   >(
     name: TOption,
-    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+    config: ObjectOptionConfig<TCoerce, TProps>
   ): CLI<
     TArgs &
       MakeUndefinedPropertiesOptional<{
         [key in TOption]: WithOptional<
-          unknown extends TCoerce
-            ? WithAdditionalProperties<
-                ResolveProperties<TProps>,
-                TAdditionalProps
-              >
-            : TCoerce,
-          ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,
+          ObjectOptionConfig<TCoerce, TProps>
         >;
       }>,
     THandlerReturn,
@@ -641,7 +625,7 @@ export interface CLI<
   // Generic fallback overload
   positional<
     TOption extends string,
-    const TOptionConfig extends OptionConfig<any, any, any, any>
+    const TOptionConfig extends OptionConfig<any, any, any>
   >(
     name: TOption,
     config: TOptionConfig
@@ -778,10 +762,64 @@ export interface CLI<
    */
   getParent(): TParent;
 
-  getBuilder<T extends ParsedArgs = ParsedArgs>(
-    initialCli?: CLI<T, any, any>
-  ):
-    | ((parser: CLI<T, any, any>) => CLI<TArgs, THandlerReturn, TChildren>)
+  /**
+   * Returns a programmatic SDK for invoking this CLI and its subcommands.
+   * The SDK provides typed function calls instead of argv parsing.
+   *
+   * @example
+   * ```ts
+   * const myCLI = cli('my-app')
+   *   .option('verbose', { type: 'boolean' })
+   *   .command('build', {
+   *     builder: (cmd) => cmd.option('watch', { type: 'boolean' }),
+   *     handler: (args) => ({ success: true, files: ['a.js'] })
+   *   });
+   *
+   * const sdk = myCLI.sdk();
+   *
+   * // Invoke root command (if it has a handler)
+   * await sdk({ verbose: true });
+   *
+   * // Invoke subcommand with typed args
+   * const result = await sdk.build({ watch: true });
+   * console.log(result.files);       // ['a.js']
+   * console.log(result.$args.watch); // true
+   *
+   * // Use CLI-style args for -- support
+   * await sdk.build(['--watch', '--', 'extra-arg']);
+   * ```
+   *
+   * @returns An SDK object that is callable (if this command has a handler)
+   *          and has properties for each subcommand.
+   */
+  sdk(): SDKCommand<TArgs, THandlerReturn, TChildren>;
+
+  /**
+   * Returns the builder function for this command as a composable builder.
+   * The returned function can be used with `chain` to compose multiple builders.
+   *
+   * @example
+   * ```ts
+   * const siblings = args.getParent().getChildren();
+   * const withBuildArgs = siblings.build.getBuilder()!;
+   * const withServeArgs = siblings.serve.getBuilder()!;
+   * return chain(args, withBuildArgs, withServeArgs);
+   * ```
+   */
+  getBuilder():
+    | (<
+        TInit extends ParsedArgs,
+        TInitHandlerReturn,
+        TInitChildren,
+        TInitParent
+      >(
+        parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>
+      ) => CLI<
+        TInit & TArgs,
+        TInitHandlerReturn,
+        TInitChildren & TChildren,
+        TInitParent
+      >)
     | undefined;
   getHandler():
     | ((args: Omit<TArgs, keyof ParsedArgs>) => THandlerReturn)
@@ -910,6 +948,67 @@ export type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (
   args: TArgs
 ) => TArgs2 | Promise<TArgs2>;
 
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+/**
+ * Result type that conditionally includes $args.
+ * Only attaches $args when result is an object type.
+ * Uses `Awaited<T>` to handle async handlers that return `Promise<U>`.
+ */
+export type SDKResult<TArgs, THandlerReturn> =
+  Awaited<THandlerReturn> extends object
+    ? Awaited<THandlerReturn> & { $args: TArgs }
+    : Awaited<THandlerReturn>;
+
+/**
+ * The callable signature for a command with a handler.
+ * Supports both object-style args (typed, skips validation) and
+ * string array args (CLI-style, full validation pipeline).
+ */
+export type SDKInvokable<TArgs, THandlerReturn> = {
+  /**
+   * Invoke the command with typed object args.
+   * Skips validation (TypeScript handles it), applies defaults, runs middleware.
+   */
+  (args?: Partial<Omit<TArgs, 'unmatched' | '--'>>): Promise<
+    SDKResult<TArgs, THandlerReturn>
+  >;
+  /**
+   * Invoke the command with CLI-style string args.
+   * Runs full pipeline: parse → validate → middleware → handler.
+   * Use this when you need to pass `--` extra args.
+   */
+  (args: string[]): Promise<SDKResult<TArgs, THandlerReturn>>;
+};
+
+/**
+ * Recursively builds SDK type from TChildren.
+ * Each child command becomes a property on the SDK object.
+ */
+export type SDKChildren<TChildren> = {
+  [K in keyof TChildren]: TChildren[K] extends CLI<
+    infer A,
+    infer R,
+    infer C,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    infer _P
+  >
+    ? SDKCommand<A, R, C>
+    : never;
+};
+
+/**
+ * A single SDK command - callable if it has a handler, with nested children as properties.
+ * Container commands (no handler) are not callable but still provide access to children.
+ */
+export type SDKCommand<TArgs, THandlerReturn, TChildren> =
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  // THandlerReturn extends void | undefined
+  // ? SDKChildren<TChildren> // No handler = just children (not callable)
+  SDKInvokable<TArgs, THandlerReturn> & SDKChildren<TChildren>;
+
 /**
  * Constructs a CLI instance. See {@link CLI} for more information.
  * @param name Name for the top level CLI