Add TConfig generic parameter to createCLI for type-safe custom config

[vlavrynovych]

Problem

The Firebase adapter team has FirebaseConfig extends Config, but createCLI doesn't support config generics. This forces type casting in the extendFlags callback, making it inconvenient and error-prone.

Current code (Firebase adapter):

interface FirebaseConfig extends Config {
  databaseUrl: string;
  applicationCredentials: string;
  connectionTimeout?: number;
}

const program = createCLI({
  addCustomOptions: (program) => {
    program.option('--database-url <url>', 'Firebase Database URL');
  },
  
  extendFlags: (config, flags) => {
    // ❌ config is typed as Config, not FirebaseConfig
    // Must cast to access FirebaseConfig properties
    (config as FirebaseConfig).databaseUrl = flags.databaseUrl;
    (config as FirebaseConfig).applicationCredentials = flags.credentials;
  },
  
  createExecutor: async (config) => {
    // ❌ config is typed as Config, not FirebaseConfig
    return FirebaseAdapter.getInstance({ config: config as FirebaseConfig });
  }
});

---

Proposed Solution

Add TConfig generic parameter to createCLI (same pattern as THandler in #138 and TConfig in #144).

After fix:

const program = createCLI<IFirebaseDB, FirebaseAdapter, FirebaseConfig>({
  addCustomOptions: (program) => {
    program.option('--database-url <url>', 'Firebase Database URL');
  },
  
  extendFlags: (config, flags) => {
    // ✅ config is typed as FirebaseConfig - full IntelliSense!
    config.databaseUrl = flags.databaseUrl;
    config.applicationCredentials = flags.credentials;
    config.connectionTimeout = flags.timeout ? parseInt(flags.timeout, 10) : undefined;
  },
  
  createExecutor: async (config) => {
    // ✅ config is typed as FirebaseConfig
    return FirebaseAdapter.getInstance({ config });
  }
});

---

Implementation

1. Update CLIOptions interface (createCLI.ts)

export interface CLIOptions<
  DB extends IDB,
  TExecutor extends MigrationScriptExecutor<DB> = MigrationScriptExecutor<DB>,
  TConfig extends Config = Config  // NEW: Add TConfig generic
> {
  createExecutor: (config: TConfig) => TExecutor | Promise<TExecutor>;
  
  config?: Partial<TConfig>;  // Update type
  
  configLoader?: IConfigLoader<TConfig>;  // Already exists from #144
  
  extendFlags?: (config: TConfig, flags: CLIFlags) => void;  // Update type
  
  // ... other fields unchanged
}

2. Update createCLI function signature

export function createCLI<
  DB extends IDB,
  TExecutor extends MigrationScriptExecutor<DB> = MigrationScriptExecutor<DB>,
  TConfig extends Config = Config  // NEW: Add TConfig generic
>(
  options: CLIOptions<DB, TExecutor, TConfig>
): Command {
  // Implementation stays mostly the same
  // TypeScript will infer TConfig throughout
}

3. Update internal usage

The createExecutorWithFlags factory function already uses options.configLoader which is typed as IConfigLoader<TConfig> from #144, so it should work seamlessly.

---

Benefits

• ✅ Type Safety: No casting needed in extendFlags and createExecutor
• ✅ IntelliSense: Full autocomplete for custom config properties
• ✅ Consistency: Same pattern as THandler (Add handler generic type parameter to MigrationScriptExecutor #138) and executor TConfig (Feature Request: Generic Config Type in IExecutorOptions #144)
• ✅ Backward Compatible: Default TConfig = Config maintains existing behavior
• ✅ Firebase Team Unblocked: Can use FirebaseConfig without casts

---

Testing

Add tests to test/unit/cli/createCLI.test.ts:

• Test with custom config type (e.g., FirebaseConfig)
• Verify extendFlags receives typed config
• Verify createExecutor receives typed config
• Ensure backward compatibility (no generic = Config)

---

Related Issues

• Add handler generic type parameter to MigrationScriptExecutor #138 - Added THandler generic for type-safe handler access
• Feature Request: Generic Config Type in IExecutorOptions #144 - Added TConfig generic to executor interfaces
• Support adapter-specific CLI flags in createCLI #151 - Added addCustomOptions and extendFlags callbacks (v0.8.3)

This completes the type safety story started in v0.8.0-v0.8.3.

---

Acceptance Criteria

• CLIOptions has TConfig generic parameter with Config default
• createCLI has TConfig generic parameter with Config default
• extendFlags callback receives TConfig (not Config)
• createExecutor callback receives TConfig (not Config)
• options.config typed as Partial<TConfig>
• All existing tests pass (backward compatibility)
• New tests added for custom config type
• 100% test coverage maintained
• Build succeeds with no TypeScript errors
• Documentation updated with Firebase example

[vlavrynovych]

Implementation Complete ✅

Added TConfig generic parameter to createCLI for type-safe custom configuration types.

Changes

Core Implementation:

• CLIOptions interface: Added TConfig extends Config = Config generic parameter
• createCLI function: Added TConfig generic with default type
• extendFlags callback: Config parameter now typed as TConfig
• createExecutor callback: Config parameter now typed as TConfig
• Internal ConfigLoader: Updated to use TConfig generic

Benefits:

• ✅ No type casting needed in extendFlags and createExecutor
• ✅ Full IntelliSense for custom config properties
• ✅ Consistent with THandler (Add handler generic type parameter to MigrationScriptExecutor #138) and executor TConfig (Feature Request: Generic Config Type in IExecutorOptions #144)
• ✅ Unblocks Firebase adapter development

Documentation:

• Added Firebase example with TConfig usage in cli-adapter-development.md
• Before/after comparison showing type safety improvements
• Integration example with addCustomOptions/extendFlags (v0.8.3)

Testing:

• Added 4 comprehensive tests for custom config type support
• Test: extendFlags receives custom config type
• Test: createExecutor receives custom config type
• Test: Backward compatibility without TConfig generic
• Test: Custom config with async executor

Results:

• 1572 tests passing (+4 new tests)
• 100% coverage maintained (2815/1450/581/2713)
• Fully backward compatible with default TConfig = Config

Usage Example

interface FirebaseConfig extends Config {
  databaseUrl: string;
  applicationCredentials: string;
}

const program = createCLI<IFirebaseDB, FirebaseAdapter, FirebaseConfig>({
  extendFlags: (config, flags) => {
    // ✅ config is typed as FirebaseConfig - no casting needed!
    config.databaseUrl = flags.databaseUrl as string;
    config.applicationCredentials = flags.credentials as string;
  },
  
  createExecutor: async (config) => {
    // ✅ config.databaseUrl is fully typed!
    return FirebaseAdapter.getInstance({ config });
  }
});

Released in v0.8.4