refactor: derive remaining provider registries and correct authoring docs (#2686)

* refactor: derive config validation capabilities

* refactor: derive provider log categories

* refactor: derive menu metric capabilities

* build: derive provider manifest order

* fix: preserve provider bootstrap order

* test: derive credential gatekeeper coverage

* docs: document provider registration truth

---------

Co-authored-by: Peter Steinberger <steipete@mac-studio-sf2.local>

Author: steipete

Scripts/regenerate-provider-manifests.sh

@@ -9,6 +9,7 @@ IMPLEMENTATION_DIR="${ROOT_DIR}/Sources/CodexBar/Providers"
 DESCRIPTOR_OUTPUT="${DESCRIPTOR_DIR}/ProviderManifest.swift"
 IMPLEMENTATION_OUTPUT="${IMPLEMENTATION_DIR}/Shared/ProviderImplementationManifest.swift"
 INSTANCE_ID_OUTPUT="${DESCRIPTOR_DIR}/ProviderInstanceIDAliases.generated.swift"
+PROVIDER_IDS_OUTPUT="${ROOT_DIR}/docs/provider-ids.md"
 MODE="${1:-write}"
 
 case "$MODE" in
@@ -24,105 +25,17 @@ case "$MODE" in
     ;;
 esac
 
-# Canonical first-party bootstrap order. This single declaration generates both manifests and the
-# ProviderInstanceID aliases; provider types are discovered from their provider-owned declarations.
-PROVIDERS=(
-  codex
-  openai
-  azureopenai
-  claude
-  clinepass
-  cursor
-  opencode
-  opencodego
-  alibaba
-  alibabatokenplan
-  qwencloud
-  factory
-  gemini
-  antigravity
-  copilot
-  devin
-  zai
-  minimax
-  manus
-  kimi
-  kilo
-  kiro
-  vertexai
-  augment
-  jetbrains
-  moonshot
-  amp
-  t3chat
-  ollama
-  synthetic
-  openrouter
-  elevenlabs
-  warp
-  windsurf
-  zed
-  perplexity
-  mimo
-  doubao
-  sakana
-  abacus
-  mistral
-  deepseek
-  deepinfra
-  codebuff
-  crof
-  venice
-  commandcode
-  qoder
-  stepfun
-  bedrock
-  grok
-  groq
-  llmproxy
-  litellm
-  deepgram
-  poe
-  chutes
-  neuralwatt
-  clawrouter
-  longcat
-  sub2api
-  wayfinder
-  zenmux
-  aiand
-  zoommate
-  xai
-  notion
-)
-
-ENUM_PROVIDERS=()
+# UsageProvider is the canonical first-party bootstrap order. Provider types are discovered from
+# their provider-owned declarations; this parsed order generates both manifests and the aliases.
+PROVIDERS=()
 while IFS= read -r provider; do
-  ENUM_PROVIDERS+=("$provider")
+  PROVIDERS+=("$provider")
 done < <(sed -nE '/public enum UsageProvider:/,/^}/s/^[[:space:]]*case ([a-z0-9]+)$/\1/p' "$PROVIDERS_FILE")
 
-contains_provider() {
-  local needle="$1"
-  shift
-  local candidate
-  for candidate in "$@"; do
-    [[ "$candidate" == "$needle" ]] && return 0
-  done
-  return 1
-}
-
-for provider in "${ENUM_PROVIDERS[@]}"; do
-  if ! contains_provider "$provider" "${PROVIDERS[@]}"; then
-    echo "error: UsageProvider '${provider}' is missing from the canonical PROVIDERS order in ${BASH_SOURCE[0]#${ROOT_DIR}/}" >&2
-    exit 1
-  fi
-done
-for provider in "${PROVIDERS[@]}"; do
-  if ! contains_provider "$provider" "${ENUM_PROVIDERS[@]}"; then
-    echo "error: canonical provider '${provider}' has no UsageProvider case in ${PROVIDERS_FILE#${ROOT_DIR}/}" >&2
-    exit 1
-  fi
-done
+if [[ "${#PROVIDERS[@]}" -eq 0 ]]; then
+  echo "error: no UsageProvider cases found in ${PROVIDERS_FILE#${ROOT_DIR}/}" >&2
+  exit 1
+fi
 
 DESCRIPTOR_TYPES=()
 IMPLEMENTATION_TYPES=()
@@ -215,6 +128,22 @@ SWIFT
 SWIFT
 }
 
+render_provider_ids() {
+  cat <<'MARKDOWN'
+<!-- Generated by Scripts/regenerate-provider-manifests.sh. Do not edit by hand. -->
+
+# Provider IDs
+
+MARKDOWN
+  local separator=""
+  local provider
+  for provider in "${PROVIDERS[@]}"; do
+    printf '%s`%s`' "$separator" "$provider"
+    separator=", "
+  done
+  printf '.\n'
+}
+
 check_or_write() {
   local output="$1"
   local renderer="$2"
@@ -242,6 +171,7 @@ check_or_write() {
 check_or_write "$DESCRIPTOR_OUTPUT" render_descriptors
 check_or_write "$IMPLEMENTATION_OUTPUT" render_implementations
 check_or_write "$INSTANCE_ID_OUTPUT" render_instance_ids
+check_or_write "$PROVIDER_IDS_OUTPUT" render_provider_ids
 if [[ "$CHECK_ONLY" -eq 1 ]]; then
   echo "Provider manifests are current (${#PROVIDERS[@]} providers)"
 fi

Sources/CodexBar/CopilotTokenStore.swift

@@ -22,7 +22,7 @@ enum CopilotTokenStoreError: LocalizedError {
 }
 
 struct KeychainCopilotTokenStore: CopilotTokenStoring {
-    private static let log = CodexBarLog.logger(LogCategories.copilotTokenStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.copilot, scope: "token-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "copilot-api-token"

Sources/CodexBar/CursorLoginRunner.swift

@@ -123,7 +123,7 @@ final class CursorLoginRunner {
     private let accountChooser: AccountChooser?
     private let timeout: TimeInterval
     private let pollInterval: TimeInterval
-    private let logger = CodexBarLog.logger(LogCategories.cursorLogin)
+    private let logger = CodexBarLog.logger(LogCategories.provider(.cursor, scope: "login"))
 
     static let authURL = URL(string: "https://authenticator.cursor.sh/")!
 

Sources/CodexBar/KimiTokenStore.swift

@@ -22,7 +22,7 @@ enum KimiTokenStoreError: LocalizedError {
 }
 
 struct KeychainKimiTokenStore: KimiTokenStoring {
-    private static let log = CodexBarLog.logger(LogCategories.kimiTokenStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.kimi, scope: "token-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "kimi-auth-token"

Sources/CodexBar/MiniMaxAPITokenStore.swift

@@ -22,7 +22,7 @@ enum MiniMaxAPITokenStoreError: LocalizedError {
 }
 
 struct KeychainMiniMaxAPITokenStore: MiniMaxAPITokenStoring {
-    private static let log = CodexBarLog.logger(LogCategories.minimaxAPITokenStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.minimax, scope: "api-token-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "minimax-api-token"

Sources/CodexBar/MiniMaxCookieStore.swift

@@ -22,7 +22,7 @@ enum MiniMaxCookieStoreError: LocalizedError {
 }
 
 struct KeychainMiniMaxCookieStore: MiniMaxCookieStoring {
-    private static let log = CodexBarLog.logger(LogCategories.minimaxCookieStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.minimax, scope: "cookie-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "minimax-cookie"

Sources/CodexBar/SettingsStore+MenuPreferences.swift

@@ -201,112 +201,36 @@ extension SettingsStore {
     }
 
     func menuBarMetricPreference(for provider: UsageProvider) -> MenuBarMetricPreference {
-        if Self.isBalanceOnlyProvider(provider), provider != .mistral {
-            return .automatic
-        }
-        if provider == .mistral {
-            let raw = self.menuBarMetricPreferencesRaw[provider.rawValue] ?? ""
-            let preference = MenuBarMetricPreference(rawValue: raw) ?? .automatic
-            switch preference {
-            case .automatic, .monthlyPlan:
-                return preference
-            case .primary, .secondary, .primaryAndSecondary, .tertiary, .extraUsage, .average:
-                return .automatic
-            }
-        }
-        if provider == .openrouter {
-            let raw = self.menuBarMetricPreferencesRaw[provider.rawValue] ?? ""
-            let preference = MenuBarMetricPreference(rawValue: raw) ?? .automatic
-            switch preference {
-            case .automatic, .primary:
-                return preference
-            case .secondary, .primaryAndSecondary, .average, .tertiary, .extraUsage, .monthlyPlan:
-                return .automatic
-            }
-        }
         let raw = self.menuBarMetricPreferencesRaw[provider.rawValue] ?? ""
         let preference = MenuBarMetricPreference(rawValue: raw) ?? .automatic
-        if preference == .average, !self.menuBarMetricSupportsAverage(for: provider) {
-            return .automatic
-        }
-        if preference == .primaryAndSecondary, !self.menuBarMetricSupportsPrimaryAndSecondary(for: provider) {
-            return .automatic
-        }
-        if preference == .tertiary, !self.menuBarMetricSupportsTertiary(for: provider) {
-            return .automatic
-        }
-        if preference == .extraUsage, !self.menuBarMetricSupportsExtraUsage(for: provider) {
-            return .automatic
-        }
-        if preference == .monthlyPlan {
-            return .automatic
-        }
-        return preference
+        return self.menuBarMetricSupports(preference, for: provider) ? preference : .automatic
     }
 
     func setMenuBarMetricPreference(_ preference: MenuBarMetricPreference, for provider: UsageProvider) {
-        if Self.isBalanceOnlyProvider(provider), provider != .mistral {
-            self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            return
-        }
-        if provider == .mistral {
-            switch preference {
-            case .automatic, .monthlyPlan:
-                self.menuBarMetricPreferencesRaw[provider.rawValue] = preference.rawValue
-            case .primary, .secondary, .primaryAndSecondary, .tertiary, .extraUsage, .average:
-                self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            }
-            return
-        }
-        if provider == .openrouter {
-            switch preference {
-            case .automatic, .primary:
-                self.menuBarMetricPreferencesRaw[provider.rawValue] = preference.rawValue
-            case .secondary, .primaryAndSecondary, .average, .tertiary, .extraUsage, .monthlyPlan:
-                self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            }
-            return
-        }
-        if preference == .primaryAndSecondary, !self.menuBarMetricSupportsPrimaryAndSecondary(for: provider) {
-            self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            return
-        }
-        if preference == .tertiary, !self.menuBarMetricSupportsTertiary(for: provider) {
-            self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            return
-        }
-        if preference == .extraUsage, !self.menuBarMetricSupportsExtraUsage(for: provider) {
-            self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            return
-        }
-        if preference == .monthlyPlan {
-            self.menuBarMetricPreferencesRaw[provider.rawValue] = MenuBarMetricPreference.automatic.rawValue
-            return
-        }
-        self.menuBarMetricPreferencesRaw[provider.rawValue] = preference.rawValue
+        let resolved = self.menuBarMetricSupports(preference, for: provider) ? preference : .automatic
+        self.menuBarMetricPreferencesRaw[provider.rawValue] = resolved.rawValue
     }
 
     func menuBarMetricSupportsAverage(for provider: UsageProvider) -> Bool {
-        provider == .gemini
+        self.menuBarMetricCapabilities(for: provider).supports(.average)
     }
 
     func menuBarMetricSupportsPrimaryAndSecondary(for provider: UsageProvider) -> Bool {
-        provider == .codex || provider == .claude
+        self.menuBarMetricCapabilities(for: provider).supports(.primaryAndSecondary)
     }
 
     func menuBarMetricSupportsTertiary(for provider: UsageProvider) -> Bool {
-        provider == .cursor || provider == .perplexity
+        self.menuBarMetricCapabilities(for: provider).supports(.tertiary)
     }
 
     func menuBarMetricSupportsTertiary(for provider: UsageProvider, snapshot: UsageSnapshot?) -> Bool {
-        if provider == .cursor {
-            return snapshot?.tertiary != nil
-        }
-        return self.menuBarMetricSupportsTertiary(for: provider)
+        let capabilities = self.menuBarMetricCapabilities(for: provider)
+        guard capabilities.supports(.tertiary) else { return false }
+        return !capabilities.tertiaryRequiresWindow || snapshot?.tertiary != nil
     }
 
     func menuBarMetricSupportsExtraUsage(for provider: UsageProvider) -> Bool {
-        provider == .cursor || provider == .claude
+        self.menuBarMetricCapabilities(for: provider).supports(.extraUsage)
     }
 
     func menuBarMetricSupportsExtraUsage(for provider: UsageProvider, snapshot: UsageSnapshot?) -> Bool {
@@ -340,7 +264,26 @@ extension SettingsStore {
         self.resetTimesShowAbsolute ? .absolute : .countdown
     }
 
-    static func isBalanceOnlyProvider(_ provider: UsageProvider) -> Bool {
-        ProviderDescriptorRegistry.descriptor(for: provider).metadata.balanceOnly
+    private func menuBarMetricCapabilities(for provider: UsageProvider) -> ProviderMenuBarMetricCapabilities {
+        ProviderDescriptorRegistry.descriptor(for: provider).menuBarMetrics
+    }
+
+    private func menuBarMetricSupports(_ preference: MenuBarMetricPreference, for provider: UsageProvider) -> Bool {
+        self.menuBarMetricCapabilities(for: provider).supports(preference.providerMetric)
+    }
+}
+
+extension MenuBarMetricPreference {
+    fileprivate var providerMetric: ProviderMenuBarMetric {
+        switch self {
+        case .automatic: .automatic
+        case .primary: .primary
+        case .secondary: .secondary
+        case .primaryAndSecondary: .primaryAndSecondary
+        case .tertiary: .tertiary
+        case .extraUsage: .extraUsage
+        case .average: .average
+        case .monthlyPlan: .monthlyPlan
+        }
     }
 }

Sources/CodexBar/SyntheticTokenStore.swift

@@ -22,7 +22,7 @@ enum SyntheticTokenStoreError: LocalizedError {
 }
 
 struct KeychainSyntheticTokenStore: SyntheticTokenStoring {
-    private static let log = CodexBarLog.logger(LogCategories.syntheticTokenStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.synthetic, scope: "token-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "synthetic-api-key"

Sources/CodexBar/UsageStore.swift

@@ -313,9 +313,9 @@ final class UsageStore {
     @ObservationIgnored let pluginApprovalStore = ProviderPluginApprovalStore()
     @ObservationIgnored let sessionQuotaNotifier: any SessionQuotaNotifying
     @ObservationIgnored let sessionQuotaLogger = CodexBarLog.logger(LogCategories.sessionQuota)
-    @ObservationIgnored let openAIWebLogger = CodexBarLog.logger(LogCategories.openAIWeb)
+    @ObservationIgnored let openAIWebLogger = CodexBarLog.logger(LogCategories.provider(.openai, scope: "web"))
     @ObservationIgnored private let tokenCostLogger = CodexBarLog.logger(LogCategories.tokenCost)
-    @ObservationIgnored let augmentLogger = CodexBarLog.logger(LogCategories.augment)
+    @ObservationIgnored let augmentLogger = CodexBarLog.logger(LogCategories.provider(.augment))
     @ObservationIgnored let providerLogger = CodexBarLog.logger(LogCategories.providers)
     @ObservationIgnored let adaptiveRefreshLogger = CodexBarLog.logger(LogCategories.adaptiveRefresh)
     @ObservationIgnored var openAIWebDebugLines: [String] = []

Sources/CodexBar/ZaiTokenStore.swift

@@ -22,7 +22,7 @@ enum ZaiTokenStoreError: LocalizedError {
 }
 
 struct KeychainZaiTokenStore: ZaiTokenStoring {
-    private static let log = CodexBarLog.logger(LogCategories.zaiTokenStore)
+    private static let log = CodexBarLog.logger(LogCategories.provider(.zai, scope: "token-store"))
 
     private let service = "com.steipete.CodexBar"
     private let account = "zai-api-token"