feat(cli-forge): enhance makeComposableBuilder to track children types

Updates makeComposableBuilder to properly track child commands added
by the builder function via a new TChildren2 type parameter.

Adds new exported types:
- ComposableBuilder<TArgs2, TAddedChildren>: Type for composable builder functions
- ExtractChildren<T>: Extracts TChildren from a CLI type
- ExtractArgs<T>: Extracts TArgs from a CLI type

The enhanced type tracking allows chain() to properly accumulate
child command types when composing multiple builders together.

🤖 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/index.ts

@@ -3,5 +3,10 @@ export * from './lib/public-api';
 export { default } from './lib/public-api';
 export { chain } from '@cli-forge/parser';
 export { makeComposableBuilder } from './lib/composable-builder';
+export type {
+  ComposableBuilder,
+  ExtractArgs,
+  ExtractChildren,
+} from './lib/composable-builder';
 export type { ArgumentsOf } from './lib/utils';
 export { ConfigurationProviders } from './lib/configuration-providers';

packages/cli-forge/src/lib/composable-builder.ts

@@ -1,9 +1,57 @@
 import { ParsedArgs } from '@cli-forge/parser';
 import { CLI } from './public-api';
 
-export function makeComposableBuilder<T2 extends ParsedArgs>(
-  fn: (init: CLI<ParsedArgs>) => CLI<T2>
+/**
+ * Extracts the TChildren type parameter from a CLI type.
+ */
+export type ExtractChildren<T> = T extends CLI<any, any, infer C, any>
+  ? C
+  : never;
+
+/**
+ * Extracts the TArgs type parameter from a CLI type.
+ */
+export type ExtractArgs<T> = T extends CLI<infer A, any, any, any> ? A : never;
+
+/**
+ * Type for a composable builder function that transforms a CLI.
+ * Used with `chain` to compose multiple builders.
+ */
+export type ComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TAddedChildren = {}
+> = <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+  init: CLI<TInit, THandlerReturn, TChildren, TParent>
+) => CLI<TInit & TArgs2, THandlerReturn, TChildren & TAddedChildren, TParent>;
+
+/**
+ * Creates a composable builder function that can be used with `chain`.
+ * Can be used to add options, commands, or any other CLI modifications.
+ * Children added by the builder function are properly tracked in the type.
+ *
+ * @typeParam TArgs2 - The args type after the builder runs
+ * @typeParam TChildren2 - The children type added by the builder
+ */
+export function makeComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TChildren2 = {}
+>(
+  fn: (
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    init: CLI<ParsedArgs, any, {}, any>
+  ) => CLI<TArgs2, any, TChildren2, any>
 ) {
-  return <TInit extends ParsedArgs>(init: CLI<TInit>) =>
-    fn(init) as CLI<TInit & T2>;
+  return <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+    init: CLI<TInit, THandlerReturn, TChildren, TParent>
+  ) =>
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    fn(init as unknown as CLI<ParsedArgs, any, {}, any>) as unknown as CLI<
+      TInit & TArgs2,
+      THandlerReturn,
+      TChildren & TChildren2,
+      TParent
+    >;
 }
+