Refine ConfigKey/OptionalConfigKey API for improved ergonomics

- Change envPrefix default from "BUSHEL" to nil for cleaner defaults
- Remove 'base' argument label for more concise syntax
- Add bushelPrefixed: convenience initializers for BUSHEL-prefixed keys
- Remove redundant .screamingSnakeCaseNoPrefix case
- Deprecate .boolDefault property (use .defaultValue instead)
- Add CustomDebugStringConvertible conformance for better debugging
- Add clarifying documentation for boolean empty string handling

Breaking Changes:
- All ConfigKey/OptionalConfigKey call sites must remove 'base:' label
- Keys requiring "BUSHEL" prefix should use bushelPrefixed: initializer
- .screamingSnakeCaseNoPrefix removed (use .screamingSnakeCase(prefix: nil))

Migration:
- ConfigKey<Bool>(base: "sync.verbose") → ConfigKey<Bool>(bushelPrefixed: "sync.verbose")
- ConfigKey<String>(base: "cloudkit.key_id", envPrefix: nil, ...) → ConfigKey<String>("cloudkit.key_id", envPrefix: nil, ...)

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

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

Author: leogdion

Sources/BushelCloudKit/Configuration/ConfigurationKeys.swift

@@ -16,18 +16,18 @@ internal enum ConfigurationKeys {
   internal enum CloudKit {
     // Using base key with auto-generation (no prefix for CloudKit ENV vars)
     internal static let containerID = ConfigKey<String>(
-      base: "cloudkit.container_id",
+      "cloudkit.container_id",
       envPrefix: nil,  // Generates: CLI="cloudkit.container_id", ENV="CLOUDKIT_CONTAINER_ID"
       default: "iCloud.com.brightdigit.Bushel"
     )
 
     internal static let keyID = OptionalConfigKey<String>(
-      base: "cloudkit.key_id",
+      "cloudkit.key_id",
       envPrefix: nil
     )
 
     internal static let privateKeyPath = OptionalConfigKey<String>(
-      base: "cloudkit.private_key_path",
+      "cloudkit.private_key_path",
       envPrefix: nil
     )
   }
@@ -37,7 +37,7 @@ internal enum ConfigurationKeys {
   /// VirtualBuddy TSS API configuration keys
   internal enum VirtualBuddy {
     internal static let apiKey = OptionalConfigKey<String>(
-      base: "virtualbuddy.api_key",
+      "virtualbuddy.api_key",
       envPrefix: nil  // Generates: ENV="VIRTUALBUDDY_API_KEY"
     )
   }
@@ -47,8 +47,7 @@ internal enum ConfigurationKeys {
   /// Fetch throttling configuration keys
   internal enum Fetch {
     internal static let intervalGlobal = OptionalConfigKey<Double>(
-      base: "fetch.interval_global",
-      envPrefix: "BUSHEL"  // Generates: ENV="BUSHEL_FETCH_INTERVAL_GLOBAL"
+      bushelPrefixed: "fetch.interval_global"  // Generates: ENV="BUSHEL_FETCH_INTERVAL_GLOBAL"
     )
 
     /// Generate per-source interval key dynamically
@@ -57,7 +56,7 @@ internal enum ConfigurationKeys {
     internal static func intervalKey(for source: String) -> OptionalConfigKey<Double> {
       let normalized = source.replacingOccurrences(of: ".", with: "_")
       return OptionalConfigKey<Double>(
-        base: "fetch.interval.\(normalized)",
+        "fetch.interval.\(normalized)",
         envPrefix: nil  // CLI: "fetch.interval.appledb_dev", ENV: "FETCH_INTERVAL_APPLEDB_DEV"
       )
     }
@@ -67,51 +66,51 @@ internal enum ConfigurationKeys {
 
   /// Sync command configuration keys (using base key with BUSHEL prefix)
   internal enum Sync {
-    internal static let dryRun = ConfigKey<Bool>(base: "sync.dry_run")
-    internal static let restoreImagesOnly = ConfigKey<Bool>(base: "sync.restore_images_only")
-    internal static let xcodeOnly = ConfigKey<Bool>(base: "sync.xcode_only")
-    internal static let swiftOnly = ConfigKey<Bool>(base: "sync.swift_only")
-    internal static let noBetas = ConfigKey<Bool>(base: "sync.no_betas")
-    internal static let noAppleWiki = ConfigKey<Bool>(base: "sync.no_apple_wiki")
-    internal static let verbose = ConfigKey<Bool>(base: "sync.verbose")
-    internal static let force = ConfigKey<Bool>(base: "sync.force")
-    internal static let minInterval = OptionalConfigKey<Int>(base: "sync.min_interval")
-    internal static let source = OptionalConfigKey<String>(base: "sync.source")
+    internal static let dryRun = ConfigKey<Bool>(bushelPrefixed: "sync.dry_run")
+    internal static let restoreImagesOnly = ConfigKey<Bool>(bushelPrefixed: "sync.restore_images_only")
+    internal static let xcodeOnly = ConfigKey<Bool>(bushelPrefixed: "sync.xcode_only")
+    internal static let swiftOnly = ConfigKey<Bool>(bushelPrefixed: "sync.swift_only")
+    internal static let noBetas = ConfigKey<Bool>(bushelPrefixed: "sync.no_betas")
+    internal static let noAppleWiki = ConfigKey<Bool>(bushelPrefixed: "sync.no_apple_wiki")
+    internal static let verbose = ConfigKey<Bool>(bushelPrefixed: "sync.verbose")
+    internal static let force = ConfigKey<Bool>(bushelPrefixed: "sync.force")
+    internal static let minInterval = OptionalConfigKey<Int>(bushelPrefixed: "sync.min_interval")
+    internal static let source = OptionalConfigKey<String>(bushelPrefixed: "sync.source")
   }
 
   // MARK: - Export Command Configuration
 
   /// Export command configuration keys
   internal enum Export {
-    internal static let output = OptionalConfigKey<String>(base: "export.output")
-    internal static let pretty = ConfigKey<Bool>(base: "export.pretty")
-    internal static let signedOnly = ConfigKey<Bool>(base: "export.signed_only")
-    internal static let noBetas = ConfigKey<Bool>(base: "export.no_betas")
-    internal static let verbose = ConfigKey<Bool>(base: "export.verbose")
+    internal static let output = OptionalConfigKey<String>(bushelPrefixed: "export.output")
+    internal static let pretty = ConfigKey<Bool>(bushelPrefixed: "export.pretty")
+    internal static let signedOnly = ConfigKey<Bool>(bushelPrefixed: "export.signed_only")
+    internal static let noBetas = ConfigKey<Bool>(bushelPrefixed: "export.no_betas")
+    internal static let verbose = ConfigKey<Bool>(bushelPrefixed: "export.verbose")
   }
 
   // MARK: - Status Command Configuration
 
   /// Status command configuration keys
   internal enum Status {
-    internal static let errorsOnly = ConfigKey<Bool>(base: "status.errors_only")
-    internal static let detailed = ConfigKey<Bool>(base: "status.detailed")
+    internal static let errorsOnly = ConfigKey<Bool>(bushelPrefixed: "status.errors_only")
+    internal static let detailed = ConfigKey<Bool>(bushelPrefixed: "status.detailed")
   }
 
   // MARK: - List Command Configuration
 
   /// List command configuration keys
   internal enum List {
-    internal static let restoreImages = ConfigKey<Bool>(base: "list.restore_images")
-    internal static let xcodeVersions = ConfigKey<Bool>(base: "list.xcode_versions")
-    internal static let swiftVersions = ConfigKey<Bool>(base: "list.swift_versions")
+    internal static let restoreImages = ConfigKey<Bool>(bushelPrefixed: "list.restore_images")
+    internal static let xcodeVersions = ConfigKey<Bool>(bushelPrefixed: "list.xcode_versions")
+    internal static let swiftVersions = ConfigKey<Bool>(bushelPrefixed: "list.swift_versions")
   }
 
   // MARK: - Clear Command Configuration
 
   /// Clear command configuration keys
   internal enum Clear {
-    internal static let yes = ConfigKey<Bool>(base: "clear.yes")
-    internal static let verbose = ConfigKey<Bool>(base: "clear.verbose")
+    internal static let yes = ConfigKey<Bool>(bushelPrefixed: "clear.yes")
+    internal static let verbose = ConfigKey<Bool>(bushelPrefixed: "clear.verbose")
   }
 }

Sources/BushelCloudKit/Configuration/ConfigurationLoader.swift

@@ -103,7 +103,16 @@ public actor ConfigurationLoader {
   }
 
   /// Read a boolean value with enhanced ENV variable parsing
-  /// Returns non-optional since ConfigKey has a required default
+  ///
+  /// Returns non-optional since ConfigKey has a required default.
+  ///
+  /// Boolean parsing rules:
+  /// - CLI: Flag presence indicates true (e.g., --verbose)
+  /// - ENV: Accepts "true", "1", "yes" (case-insensitive)
+  /// - Empty string in ENV is treated as absent (falls back to default)
+  ///
+  /// - Parameter key: Configuration key with boolean type
+  /// - Returns: Boolean value from CLI/ENV or the key's default
   private func read(_ key: ConfigKeyKit.ConfigKey<Bool>) -> Bool {
     // Try CLI first (presence-based for flags)
     if let cliKey = key.key(for: .commandLine),

Sources/ConfigKeyKit/ConfigurationKey.swift

@@ -36,9 +36,6 @@ public enum StandardNamingStyle: NamingStyle, Sendable {
   /// Screaming snake case with prefix (e.g., "BUSHEL_CLOUDKIT_CONTAINER_ID")
   case screamingSnakeCase(prefix: String?)
 
-  /// Screaming snake case without prefix (e.g., "CLOUDKIT_CONTAINER_ID")
-  case screamingSnakeCaseNoPrefix
-
   public func transform(_ base: String) -> String {
     switch self {
     case .dotSeparated:
@@ -50,9 +47,6 @@ public enum StandardNamingStyle: NamingStyle, Sendable {
         return "\(prefix)_\(snakeCase)"
       }
       return snakeCase
-
-    case .screamingSnakeCaseNoPrefix:
-      return base.uppercased().replacingOccurrences(of: ".", with: "_")
     }
   }
 }
@@ -119,9 +113,9 @@ public struct ConfigKey<Value: Sendable>: ConfigurationKey, Sendable {
   /// Convenience initializer with standard naming conventions and required default
   /// - Parameters:
   ///   - base: Base key string (e.g., "cloudkit.container_id")
-  ///   - envPrefix: Prefix for environment variable (defaults to "BUSHEL")
+  ///   - envPrefix: Prefix for environment variable (defaults to nil)
   ///   - defaultVal: Required default value
-  public init(base: String, envPrefix: String? = "BUSHEL", default defaultVal: Value) {
+  public init(_ base: String, envPrefix: String? = nil, default defaultVal: Value) {
     self.baseKey = base
     self.styles = [
       .commandLine: StandardNamingStyle.dotSeparated,
@@ -146,6 +140,26 @@ public struct ConfigKey<Value: Sendable>: ConfigurationKey, Sendable {
   }
 }
 
+extension ConfigKey: CustomDebugStringConvertible {
+  public var debugDescription: String {
+    let cliKey = key(for: .commandLine) ?? "nil"
+    let envKey = key(for: .environment) ?? "nil"
+    return "ConfigKey(cli: \(cliKey), env: \(envKey), default: \(defaultValue))"
+  }
+}
+
+// MARK: - Convenience Initializers for BUSHEL Prefix
+
+extension ConfigKey {
+  /// Convenience initializer for keys with BUSHEL prefix
+  /// - Parameters:
+  ///   - base: Base key string (e.g., "sync.dry_run")
+  ///   - defaultVal: Required default value
+  public init(bushelPrefixed base: String, default defaultVal: Value) {
+    self.init(base, envPrefix: "BUSHEL", default: defaultVal)
+  }
+}
+
 // MARK: - Optional Configuration Key
 
 /// Configuration key for optional values without defaults
@@ -190,8 +204,8 @@ public struct OptionalConfigKey<Value: Sendable>: ConfigurationKey, Sendable {
   /// Convenience initializer with standard naming conventions (no default)
   /// - Parameters:
   ///   - base: Base key string (e.g., "cloudkit.key_id")
-  ///   - envPrefix: Prefix for environment variable (defaults to "BUSHEL")
-  public init(base: String, envPrefix: String? = "BUSHEL") {
+  ///   - envPrefix: Prefix for environment variable (defaults to nil)
+  public init(_ base: String, envPrefix: String? = nil) {
     self.baseKey = base
     self.styles = [
       .commandLine: StandardNamingStyle.dotSeparated,
@@ -215,6 +229,24 @@ public struct OptionalConfigKey<Value: Sendable>: ConfigurationKey, Sendable {
   }
 }
 
+extension OptionalConfigKey: CustomDebugStringConvertible {
+  public var debugDescription: String {
+    let cliKey = key(for: .commandLine) ?? "nil"
+    let envKey = key(for: .environment) ?? "nil"
+    return "OptionalConfigKey(cli: \(cliKey), env: \(envKey))"
+  }
+}
+
+// MARK: - Convenience Initializers for BUSHEL Prefix
+
+extension OptionalConfigKey {
+  /// Convenience initializer for keys with BUSHEL prefix
+  /// - Parameter base: Base key string (e.g., "sync.min_interval")
+  public init(bushelPrefixed base: String) {
+    self.init(base, envPrefix: "BUSHEL")
+  }
+}
+
 // MARK: - Specialized Initializers for Booleans
 
 extension ConfigKey where Value == Bool {
@@ -236,9 +268,9 @@ extension ConfigKey where Value == Bool {
   /// Initialize a boolean configuration key from base string
   /// - Parameters:
   ///   - base: Base key string (e.g., "sync.verbose")
-  ///   - envPrefix: Prefix for environment variable (defaults to "BUSHEL")
+  ///   - envPrefix: Prefix for environment variable (defaults to nil)
   ///   - defaultVal: Default value (defaults to false)
-  public init(base: String, envPrefix: String? = "BUSHEL", default defaultVal: Bool = false) {
+  public init(_ base: String, envPrefix: String? = nil, default defaultVal: Bool = false) {
     self.baseKey = base
     self.styles = [
       .commandLine: StandardNamingStyle.dotSeparated,
@@ -249,7 +281,20 @@ extension ConfigKey where Value == Bool {
   }
 
   /// Non-optional default value accessor for booleans
+  @available(*, deprecated, message: "Use defaultValue directly instead")
   public var boolDefault: Bool {
     defaultValue  // Already non-optional!
   }
 }
+
+// MARK: - BUSHEL Prefix Convenience
+
+extension ConfigKey where Value == Bool {
+  /// Convenience initializer for boolean keys with BUSHEL prefix
+  /// - Parameters:
+  ///   - base: Base key string (e.g., "sync.verbose")
+  ///   - defaultVal: Default value (defaults to false)
+  public init(bushelPrefixed base: String, default defaultVal: Bool = false) {
+    self.init(base, envPrefix: "BUSHEL", default: defaultVal)
+  }
+}

Tests/ConfigKeyKitTests/ConfigKeyKitTests.swift

@@ -21,7 +21,7 @@ struct ConfigKeyTests {
 
   @Test("ConfigKey with base string and default prefix")
   func baseStringWithDefaultPrefix() {
-    let key = ConfigKey<String>(base: "cloudkit.container_id", default: "iCloud.com.example.App")
+    let key = ConfigKey<String>(bushelPrefixed: "cloudkit.container_id", default: "iCloud.com.example.App")
 
     #expect(key.key(for: .commandLine) == "cloudkit.container_id")
     #expect(key.key(for: .environment) == "BUSHEL_CLOUDKIT_CONTAINER_ID")
@@ -30,7 +30,7 @@ struct ConfigKeyTests {
 
   @Test("ConfigKey with base string and no prefix")
   func baseStringNoPrefix() {
-    let key = ConfigKey<String>(base: "cloudkit.container_id", envPrefix: nil, default: "iCloud.com.example.App")
+    let key = ConfigKey<String>("cloudkit.container_id", envPrefix: nil, default: "iCloud.com.example.App")
 
     #expect(key.key(for: .commandLine) == "cloudkit.container_id")
     #expect(key.key(for: .environment) == "CLOUDKIT_CONTAINER_ID")
@@ -46,9 +46,8 @@ struct ConfigKeyTests {
 
   @Test("Boolean ConfigKey with default")
   func booleanDefaultValue() {
-    let key = ConfigKey<Bool>(base: "sync.verbose", default: false)
+    let key = ConfigKey<Bool>(bushelPrefixed: "sync.verbose", default: false)
 
-    #expect(key.boolDefault == false)
     #expect(key.defaultValue == false)
   }
 }
@@ -69,7 +68,7 @@ struct NamingStyleTests {
 
   @Test("Screaming snake case without prefix")
   func screamingSnakeCaseNoPrefix() {
-    let style = StandardNamingStyle.screamingSnakeCaseNoPrefix
+    let style = StandardNamingStyle.screamingSnakeCase(prefix: nil)
     #expect(style.transform("cloudkit.container_id") == "CLOUDKIT_CONTAINER_ID")
   }
 
@@ -103,40 +102,40 @@ struct OptionalConfigKeyTests {
 
   @Test("OptionalConfigKey with base string and default prefix")
   func baseStringWithDefaultPrefix() {
-    let key = OptionalConfigKey<String>(base: "cloudkit.key_id")
+    let key = OptionalConfigKey<String>(bushelPrefixed: "cloudkit.key_id")
 
     #expect(key.key(for: .commandLine) == "cloudkit.key_id")
     #expect(key.key(for: .environment) == "BUSHEL_CLOUDKIT_KEY_ID")
   }
 
   @Test("OptionalConfigKey with base string and no prefix")
   func baseStringNoPrefix() {
-    let key = OptionalConfigKey<String>(base: "cloudkit.key_id", envPrefix: nil)
+    let key = OptionalConfigKey<String>("cloudkit.key_id", envPrefix: nil)
 
     #expect(key.key(for: .commandLine) == "cloudkit.key_id")
     #expect(key.key(for: .environment) == "CLOUDKIT_KEY_ID")
   }
 
   @Test("OptionalConfigKey and ConfigKey generate identical keys")
   func keyGenerationParity() {
-    let optional = OptionalConfigKey<String>(base: "test.key")
-    let withDefault = ConfigKey<String>(base: "test.key", default: "default")
+    let optional = OptionalConfigKey<String>(bushelPrefixed: "test.key")
+    let withDefault = ConfigKey<String>(bushelPrefixed: "test.key", default: "default")
 
     #expect(optional.key(for: .commandLine) == withDefault.key(for: .commandLine))
     #expect(optional.key(for: .environment) == withDefault.key(for: .environment))
   }
 
   @Test("OptionalConfigKey for Int type")
   func intOptionalKey() {
-    let key = OptionalConfigKey<Int>(base: "sync.min_interval")
+    let key = OptionalConfigKey<Int>(bushelPrefixed: "sync.min_interval")
 
     #expect(key.key(for: .commandLine) == "sync.min_interval")
     #expect(key.key(for: .environment) == "BUSHEL_SYNC_MIN_INTERVAL")
   }
 
   @Test("OptionalConfigKey for Double type")
   func doubleOptionalKey() {
-    let key = OptionalConfigKey<Double>(base: "fetch.interval_global")
+    let key = OptionalConfigKey<Double>(bushelPrefixed: "fetch.interval_global")
 
     #expect(key.key(for: .commandLine) == "fetch.interval_global")
     #expect(key.key(for: .environment) == "BUSHEL_FETCH_INTERVAL_GLOBAL")