refactor: implement URI-based provider configuration

This commit introduces a major refactoring of the provider system to support
flexible URI-based configuration. Providers can now be specified as simple
names (e.g., "keyring") or as URIs with configuration (e.g., "1password://vault").

Key changes:
- Add ProviderRegistry with centralized provider info and creation
- Convert all providers to support URI-based configuration
- Add config structs for each provider with from_uri() methods
- Support provider URIs like:
  - 1password://account@vault
  - 1password+token://service-account-token@vault
  - dotenv:/path/to/.env
  - lastpass://folder
- Update CLI to show provider examples in selection menu
- Add comprehensive tests for URI parsing and provider creation
- Remove stateful provider instances from SecretSpec

This enables more flexible provider configuration while maintaining
backward compatibility with simple provider names.

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

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

Author: domenkozar

Cargo.lock

@@ -31,6 +31,7 @@ secretspec-derive = { path = "./secretspec-derive", optional = true }
 secretspec-types = { path = "./secretspec-types" }
 serde_json = "1.0"
 tempfile = "3.0"
+http = "1.0"
 
 [features]
 default = ["macros"]

Cargo.toml

@@ -47,11 +47,11 @@ This separation enables:
 
 ## Features
 
-- **Declarative Configuration**: Define your secrets in `secretspec.toml` with descriptions and requirements
-- **Multiple Provider Backends**: [Keyring](https://docs.rs/keyring/latest/keyring/) (system credential store), [.env](https://www.dotenv.org/), and environment variable support
-- **Type-Safe Rust SDK**: Generate strongly-typed structs from your `secretspec.toml` for compile-time safety
-- **Profile Support**: Override secret requirements and defaults per profile (development, production, etc.)
-- **Configuration Inheritance**: Extend and override shared configurations using the `extends` feature
+- **[Declarative Configuration](https://secretspec.dev/docs/reference/configuration/)**: Define your secrets in `secretspec.toml` with descriptions and requirements
+- **[Multiple Provider Backends](https://secretspec.dev/docs/concepts/providers/)**: [Keyring](https://docs.rs/keyring/latest/keyring/) (system credential store), [.env](https://www.dotenv.org/), and environment variable support
+- **[Type-Safe Rust SDK](https://secretspec.dev/docs/sdk/rust/)**: Generate strongly-typed structs from your `secretspec.toml` for compile-time safety
+- **[Profile Support](https://secretspec.dev/docs/concepts/profiles/)**: Override secret requirements and defaults per profile (development, production, etc.)
+- **[Configuration Inheritance](https://secretspec.dev/docs/concepts/inheritance/)**: Extend and override shared configurations using the `extends` feature
 - **Discovery**: `secretspec init` to discover secrets from existing `.env` files
 
 ## Quick Start
@@ -258,12 +258,14 @@ SecretSpec provider can be configured through three methods (in order of precede
 SecretSpec includes five built-in provider backends:
 
 - **keyring** - Secure system credential store integration
-- **dotenv** - Local .env file storage
+- **dotenv** - Local .env file storage (e.g., `dotenv:/path/to/.env`)
 - **env** - Read-only environment variable access
-- **lastpass** - LastPass password manager integration
-- **1password** - 1Password secrets management
+- **lastpass** - LastPass password manager integration (e.g., `lastpass://folder`)
+- **1password** - 1Password secrets management (e.g., `1password://vault`, `1password://work@Production`)
 
-*Additional provider backends are welcome!**
+Providers can be specified as simple names (`keyring`) or as URIs with configuration (`1password://vault`).
+
+*Additional provider backends are welcome!*
 
 ### Keyring Provider (Recommended)
 
@@ -450,12 +452,13 @@ The macro generates several types based on your `secretspec.toml`:
 
 ## Adding a New Provider Backend
 
-To implement a new provider backend in this repository:
+To implement a new provider backend:
 
 1. **Create a new backend module** in `src/provider/your_backend.rs`:
    ```rust
-   use crate::Result;
-   use super::Provider;
+   use crate::{Result, SecretSpecError};
+   use crate::provider::Provider;
+   use http::Uri;
 
    pub struct YourBackendProvider {
        // Your backend-specific configuration
@@ -467,6 +470,22 @@ To implement a new provider backend in this repository:
                // Initialize your configuration
            }
        }
+       
+       pub fn from_uri(uri: &Uri) -> Result<Self> {
+           let scheme = uri.scheme_str()
+               .ok_or_else(|| SecretSpecError::ProviderOperationFailed("URI must have a scheme".to_string()))?;
+               
+           if scheme != "your_backend" {
+               return Err(SecretSpecError::ProviderOperationFailed(
+                   format!("Invalid scheme '{}' for your_backend provider", scheme)
+               ));
+           }
+           
+           // Parse any configuration from the URI
+           // e.g., authority, path, query parameters
+           
+           Ok(Self::new())
+       }
    }
 
    impl Provider for YourBackendProvider {
@@ -493,22 +512,44 @@ To implement a new provider backend in this repository:
    }
    ```
 
-2. **Register your backend** in `src/provider/mod.rs`:
+2. **Add your provider to the registry** in `src/provider/registry.rs`:
+   ```rust
+   impl ProviderRegistry {
+       pub fn providers() -> Vec<ProviderInfo> {
+           vec![
+               // ... existing providers ...
+               ProviderInfo {
+                   name: "your_backend",
+                   description: "Your backend description",
+                   examples: vec!["your_backend://example"],
+               },
+           ]
+       }
+       
+       pub fn create_from_string(s: &str) -> Result<Box<dyn Provider>> {
+           // ... existing code ...
+           match scheme {
+               // ... existing providers ...
+               "your_backend" => Ok(Box::new(YourBackendProvider::from_uri(&uri)?)),
+               // ...
+           }
+       }
+   }
+   ```
+
+3. **Export your module** in `src/provider/mod.rs`:
    ```rust
-   // Add to module exports
    pub mod your_backend;
    pub use your_backend::YourBackendProvider;
-
-   // Add to ProviderRegistry::new()
-   backends.insert(
-       "your_backend".to_string(),
-       Box::new(YourBackendProvider::new()) as Box<dyn Provider>,
-   );
    ```
 
-3. **Use your new backend**:
+4. **Use your new backend**:
    ```bash
+   # Simple usage
    $ secretspec set SECRET_NAME --provider your_backend
+   
+   # With URI configuration
+   $ secretspec set SECRET_NAME --provider "your_backend://config"
    ```
 
 ## License

README.md

@@ -160,15 +160,13 @@ pub fn generate_toml_with_comments(config: &ProjectConfig) -> Result<String> {
 }
 
 pub struct SecretSpec {
-    registry: ProviderRegistry,
     config: ProjectConfig,
     global_config: Option<GlobalConfig>,
 }
 
 impl SecretSpec {
     pub fn new(config: ProjectConfig, global_config: Option<GlobalConfig>) -> Self {
         Self {
-            registry: ProviderRegistry::new(),
             config,
             global_config,
         }
@@ -204,9 +202,9 @@ impl SecretSpec {
     fn get_provider_backend(
         &self,
         provider_arg: Option<String>,
-    ) -> Result<(String, &Box<dyn ProviderTrait>)> {
-        let provider_name = if let Some(name) = provider_arg {
-            name
+    ) -> Result<(String, Box<dyn ProviderTrait>)> {
+        let provider_spec = if let Some(spec) = provider_arg {
+            spec
         } else if let Some(global_config) = &self.global_config {
             global_config
                 .projects
@@ -217,10 +215,10 @@ impl SecretSpec {
             return Err(SecretSpecError::NoProviderConfigured);
         };
 
-        let backend = self
-            .registry
-            .get(&provider_name)
-            .ok_or_else(|| SecretSpecError::ProviderNotFound(provider_name.clone()))?;
+        let backend = ProviderRegistry::create_from_string(&provider_spec)?;
+
+        // Extract the provider name for display purposes
+        let provider_name = backend.name().to_string();
 
         Ok((provider_name, backend))
     }

src/lib.rs

@@ -173,16 +173,10 @@ fn main() -> Result<()> {
                 use inquire::Select;
                 use secretspec::provider::ProviderRegistry;
 
-                // Get providers from registry
-                let registry = ProviderRegistry::new();
-                let mut providers = registry.list_providers();
-                // Sort providers by name for consistent display
-                providers.sort_by_key(|(name, _)| *name);
-
-                // Create provider choices with descriptions
-                let provider_choices: Vec<String> = providers
-                    .iter()
-                    .map(|(name, provider)| format!("{}: {}", name, provider.description()))
+                // Get provider choices from the centralized registry
+                let provider_choices: Vec<String> = ProviderRegistry::providers()
+                    .into_iter()
+                    .map(|info| info.display_with_examples())
                     .collect();
 
                 let selected_choice =

src/main.rs

@@ -1,25 +1,72 @@
 use super::Provider;
-use crate::Result;
+use crate::{Result, SecretSpecError};
+use http::Uri;
+use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::fs;
 use std::path::PathBuf;
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DotEnvConfig {
+    pub path: PathBuf,
+}
+
+impl Default for DotEnvConfig {
+    fn default() -> Self {
+        Self {
+            path: PathBuf::from(".env"),
+        }
+    }
+}
+
+impl DotEnvConfig {
+    pub fn from_uri(uri: &Uri) -> Result<Self> {
+        let scheme = uri.scheme_str().ok_or_else(|| {
+            SecretSpecError::ProviderOperationFailed("URI must have a scheme".to_string())
+        })?;
+
+        if scheme != "dotenv" {
+            return Err(SecretSpecError::ProviderOperationFailed(format!(
+                "Invalid scheme '{}' for dotenv provider",
+                scheme
+            )));
+        }
+
+        // Extract path from URI, default to .env if not specified
+        let path = uri.path().trim_start_matches('/');
+        let path = if path.is_empty() || path == "/" {
+            ".env"
+        } else {
+            path
+        };
+
+        Ok(Self {
+            path: PathBuf::from(path),
+        })
+    }
+}
+
 pub struct DotEnvProvider {
-    dotenv_path: PathBuf,
+    config: DotEnvConfig,
 }
 
 impl DotEnvProvider {
-    pub fn new(dotenv_path: PathBuf) -> Self {
-        Self { dotenv_path }
+    pub fn new(config: DotEnvConfig) -> Self {
+        Self { config }
+    }
+
+    pub fn from_uri(uri: &Uri) -> Result<Self> {
+        let config = DotEnvConfig::from_uri(uri)?;
+        Ok(Self::new(config))
     }
 
     fn load_env_vars(&self) -> Result<HashMap<String, String>> {
-        if !self.dotenv_path.exists() {
+        if !self.config.path.exists() {
             return Ok(HashMap::new());
         }
 
         let mut vars = HashMap::new();
-        let env_vars = dotenvy::from_path_iter(&self.dotenv_path)?;
+        let env_vars = dotenvy::from_path_iter(&self.config.path)?;
         for item in env_vars {
             let (key, value) = item?;
             vars.insert(key, value);
@@ -32,7 +79,7 @@ impl DotEnvProvider {
         for (key, value) in vars {
             content.push_str(&format!("{}={}\n", key, value));
         }
-        fs::write(&self.dotenv_path, content)?;
+        fs::write(&self.config.path, content)?;
         Ok(())
     }
 }

src/provider/dotenv.rs

@@ -1,12 +1,41 @@
 use super::Provider;
-use crate::Result;
+use crate::{Result, SecretSpecError};
+use http::Uri;
+use serde::{Deserialize, Serialize};
 use std::env;
 
-pub struct EnvProvider;
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct EnvConfig {}
+
+impl EnvConfig {
+    pub fn from_uri(uri: &Uri) -> Result<Self> {
+        let scheme = uri.scheme_str().ok_or_else(|| {
+            SecretSpecError::ProviderOperationFailed("URI must have a scheme".to_string())
+        })?;
+
+        if scheme != "env" {
+            return Err(SecretSpecError::ProviderOperationFailed(format!(
+                "Invalid scheme '{}' for env provider",
+                scheme
+            )));
+        }
+
+        Ok(Self::default())
+    }
+}
+
+pub struct EnvProvider {
+    _config: EnvConfig,
+}
 
 impl EnvProvider {
-    pub fn new() -> Self {
-        Self
+    pub fn new(config: EnvConfig) -> Self {
+        Self { _config: config }
+    }
+
+    pub fn from_uri(uri: &Uri) -> Result<Self> {
+        let config = EnvConfig::from_uri(uri)?;
+        Ok(Self::new(config))
     }
 }