feat: implement builder pattern for SecretSpec with deferred conversions

- Add SecretSpecBuilder generated by define_secrets\! macro
- Builder methods accept TryInto<Uri> for providers and TryInto<Profile> for profiles
- All conversions and error handling deferred to load() and load_profile() methods
- Remove old load_as_profile() static method in favor of builder.load_profile()
- Store unresolved conversions as closures until load time
- Update documentation and examples to use new builder pattern

BREAKING CHANGE: SecretSpec::load_as_profile() removed, use SecretSpec::builder().load_profile() instead

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

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

Author: domenkozar

Cargo.lock

@@ -21,11 +21,11 @@ Basic example:
 secretspec::define_secrets!("secretspec.toml");
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Load secrets with type-safe struct
-    let secretspec = SecretSpec::load(
-        Some(secretspec::Provider::Keyring),
-        None  // Use default profile
-    )?;
+    // Load secrets using the builder pattern
+    let secretspec = SecretSpec::builder()
+        .with_provider("keyring")  // Can use provider name or URI like "dotenv:/path/to/.env"
+        .with_profile("development")  // Can use string or Profile enum
+        .load()?;  // All conversions and errors are handled here
 
     // Access secrets (field names are lowercased)
     println!("Database: {}", secretspec.secrets.database_url);  // DATABASE_URL → database_url
@@ -46,19 +46,19 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-## Loading with Profile Information
+## Loading with Profile-Specific Types
 
-The `load_as_profile` method provides profile-specific types for your secrets:
+The `load_profile()` method on the builder provides profile-specific types for your secrets:
 
 ```rust
 secretspec::define_secrets!("secretspec.toml");
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Load secrets with profile-specific types
-    let secretspec = SecretSpec::load_as_profile(
-        Some(secretspec::Provider::Keyring),
-        Some(Profile::Production)
-    )?;
+    let secretspec = SecretSpec::builder()
+        .with_provider("keyring")
+        .with_profile(Profile::Production)
+        .load_profile()?;
 
     // Access profile and provider information
     println!("Loaded profile: {}", secretspec.profile);

docs/src/content/docs/sdk/rust.md

@@ -4,4 +4,5 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-secretspec = { path = "../..", features = ["macros"] }
+secretspec = { path = "../..", features = ["macros"] }
+http = "1.0"

examples/derive/Cargo.toml

@@ -8,12 +8,12 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Create a .env file for testing
     std::fs::write(
         ".env",
-        "DATABASE_URL=postgres://localhost/testdb\nAPI_KEY=test-key-123\n",
+        "DATABASE_URL=postgres://localhost/testdb\nAPI_KEY=test-key-123\nREDIS_URL=redis://localhost:6379\n",
     )?;
 
-    // Example 1: Load with union types (safe for any profile)
-    println!("1. Loading secrets with union types:");
-    match SecretSpec::load(Some(Provider::Dotenv), None) {
+    // Example 1: Load with builder pattern
+    println!("1. Loading secrets with builder pattern:");
+    match SecretSpec::builder().with_provider("dotenv").load() {
         Ok(result) => {
             println!(
                 "   ✓ Loaded successfully using provider: {:?}, profile: {}",
@@ -40,51 +40,72 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         }
     }
 
-    // Example 2: Load development profile with exact types
-    println!("\n2. Loading development profile:");
-    match SecretSpec::load_as_profile(Some(Provider::Dotenv), Some(Profile::Development)) {
+    // Example 2: Load with specific profile
+    println!("\n2. Loading with specific profile:");
+    match SecretSpec::builder()
+        .with_provider("dotenv")
+        .with_profile(Profile::Development)
+        .load()
+    {
         Ok(result) => {
             println!(
                 "   ✓ Loaded using provider: {:?}, profile: {}",
                 result.provider, result.profile
             );
-            match result.secrets {
-                SecretSpecProfile::Development {
-                    database_url,
-                    api_key,
-                    redis_url,
-                    log_level,
-                } => {
-                    println!("   ✓ Got development profile");
-                    // In development profile, both database_url and api_key have defaults
-                    if let Some(url) = database_url {
-                        println!("   - Database URL: {}", url);
-                    }
-                    if let Some(key) = api_key {
-                        println!("   - API Key: {}", key);
-                    }
-                    if let Some(url) = redis_url {
-                        println!("   - Redis URL: {}", url);
-                    }
-                    if let Some(level) = log_level {
-                        println!("   - Log Level: {}", level);
-                    }
-                }
-                SecretSpecProfile::Default { .. } => {
-                    println!("   ✗ Got default profile instead of development");
-                }
-                SecretSpecProfile::Production { .. } => {
-                    println!("   ✗ Got production profile instead of development");
-                }
+            let secrets = &result.secrets;
+            if let Some(database_url) = &secrets.database_url {
+                println!("   - Database URL: {}", database_url);
+            }
+            if let Some(api_key) = &secrets.api_key {
+                println!("   - API Key: {} (found)", api_key);
+            } else {
+                println!("   - API Key: None");
+            }
+            if let Some(redis_url) = &secrets.redis_url {
+                println!("   - Redis URL: {}", redis_url);
+            }
+            if let Some(log_level) = &secrets.log_level {
+                println!("   - Log Level: {}", log_level);
             }
         }
         Err(e) => {
             println!("   ✗ Failed to load development profile: {}", e);
         }
     }
 
-    println!("\n3. Setting secrets as environment variables:");
-    if let Ok(result) = SecretSpec::load(Some(Provider::Dotenv), None) {
+    // Example 3: Using string profile
+    println!("\n3. Loading with string profile:");
+    match SecretSpec::builder()
+        .with_provider("dotenv")
+        .with_profile("production")
+        .load()
+    {
+        Ok(result) => {
+            println!("   ✓ Loaded with string profile successfully");
+            println!(
+                "   - Provider: {:?}, Profile: {}",
+                result.provider, result.profile
+            );
+        }
+        Err(e) => {
+            println!("   ✗ Failed to load with string profile: {}", e);
+        }
+    }
+
+    // Example 4: Using provider URIs
+    println!("\n4. Loading with provider URI:");
+    match SecretSpec::builder().with_provider("dotenv:.env").load() {
+        Ok(result) => {
+            println!("   ✓ Loaded with URI successfully");
+            println!("   - Provider: {:?}", result.provider);
+        }
+        Err(e) => {
+            println!("   ✗ Failed to load with URI: {}", e);
+        }
+    }
+
+    println!("\n5. Setting secrets as environment variables:");
+    if let Ok(result) = SecretSpec::builder().with_provider("dotenv").load() {
         result.secrets.set_as_env_vars();
         println!("   ✓ Set all secrets as environment variables");
 
@@ -96,6 +117,33 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         println!("   - API_KEY env: {:?}", std::env::var("API_KEY").ok());
     }
 
+    // Example 6: Loading profile-specific types
+    println!("\n6. Loading profile-specific types:");
+    match SecretSpec::builder()
+        .with_provider("dotenv")
+        .with_profile("production")
+        .load_profile()
+    {
+        Ok(result) => {
+            println!("   ✓ Loaded profile-specific types");
+            match result.secrets {
+                SecretSpecProfile::Production {
+                    database_url,
+                    api_key,
+                    ..
+                } => {
+                    println!("   - Production secrets are strongly typed");
+                    println!("   - Database URL: {}", database_url); // String, not Option<String>
+                    println!("   - API Key: {}", api_key); // String, not Option<String>
+                }
+                _ => println!("   - Got different profile"),
+            }
+        }
+        Err(e) => {
+            println!("   ✗ Failed to load profile: {}", e);
+        }
+    }
+
     // Clean up
     std::fs::remove_file(".env").ok();
 

examples/derive/src/main.rs

@@ -17,4 +17,5 @@ secretspec-types = { path = "../secretspec-types" }
 [dev-dependencies]
 trybuild = "1.0"
 secretspec = { path = ".." }
-insta = "1.34"
+insta = "1.34"
+http = "1.0"