Implement smart API client selection with fallback mechanism

[hossain-khan]

Problem

Current API client selection is entirely manual via local.properties:

• Users must explicitly choose implementation
• No auto-detection of available options
• No fallback if chosen implementation fails
• No dynamic switching based on conditions

Proposed Solution

Implement intelligent client selection with multiple strategies:

1. Auto-Detection Strategy

enum class ClientSelectionStrategy {
    MANUAL,           // User explicitly chooses (current behavior)
    AUTO,             // Auto-detect best available option
    PREFER_GH_CLI,    // Try GH CLI first, fallback to Retrofit
    PREFER_RETROFIT,  // Try Retrofit first, fallback to GH CLI
}

2. Auto-Selection Logic

fun autoSelectClient(): ApiClientType {
    return when {
        GhCliApiClient.isGhCliAvailable() && GhCliApiClient.isAuthenticated() -> {
            Log.i("Auto-selected GH CLI (authenticated and available)")
            ApiClientType.GH_CLI
        }
        hasValidAccessToken() -> {
            Log.i("Auto-selected Retrofit (access token configured)")
            ApiClientType.RETROFIT
        }
        else -> {
            throw IllegalStateException(
                "No API client available. Either:\n" +
                "1. Install and authenticate GH CLI: gh auth login\n" +
                "2. Configure access token in local.properties"
            )
        }
    }
}

3. Fallback on Failure

class FallbackApiClient(
    private val primary: GitHubApiClient,
    private val fallback: GitHubApiClient
) : GitHubApiClient {
    override suspend fun pullRequest(...): PullRequest {
        return try {
            primary.pullRequest(...)
        } catch (e: Exception) {
            Log.w("Primary client failed, using fallback: ${e.message}")
            fallback.pullRequest(...)
        }
    }
}

4. Dynamic Rate Limit Switching

Switch implementations when rate limits are hit:

• Use Retrofit until rate limited
• Switch to GH CLI (different rate limits)
• Resume Retrofit after cooldown

Configuration

# API client selection strategy
api_client_strategy=auto  # auto, manual, prefer_gh_cli, prefer_retrofit
api_client_type=retrofit  # Used when strategy=manual

Benefits

• Better user experience (less configuration needed)
• Resilience to failures
• Optimal use of available resources
• Smoother onboarding

Priority

Low - Nice quality-of-life improvement but not essential

Related Files

• src/main/kotlin/dev/hossain/githubstats/client/GitHubApiClientFactory.kt
• src/main/kotlin/dev/hossain/githubstats/util/PropertiesReader.kt