feat(cli-forge): add sdk() method for programmatic CLI invocation

Add a new `sdk()` method to CLI that returns a typed, callable interface
for invoking CLI commands programmatically without argv parsing.

Features:
- Object-style args with TypeScript type safety (skips validation)
- String array args for CLI-style invocation (full validation pipeline)
- Nested subcommand access via property syntax (sdk.build.watch())
- Middleware execution for both invocation styles
- $args attached to object results for accessing parsed args
- Proper default value handling from option configs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: AgentEnder

packages/cli-forge/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';
@@ -523,6 +524,119 @@ 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[]) => {
+      // 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;
+    };
+
+    // 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(

packages/cli-forge/src/lib/public-api.ts

@@ -778,6 +778,38 @@ export interface CLI<
    */
   getParent(): TParent;
 
+  /**
+   * 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>;
+
   getBuilder<T extends ParsedArgs = ParsedArgs>(
     initialCli?: CLI<T, any, any>
   ):
@@ -910,6 +942,65 @@ 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.
+ */
+export type SDKResult<TArgs, THandlerReturn> = THandlerReturn extends object
+  ? THandlerReturn & { $args: TArgs }
+  : 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