Struct Workspace 

pub struct Workspace { /* private fields */ }

workspace path resolver providing centralized access to workspace-relative paths

the workspace struct encapsulates workspace root detection and provides methods for resolving standard directory paths and joining workspace-relative paths safely.

Implementations

impl Workspace

pub fn new<P: Into<PathBuf>>(root: P) -> Self

create workspace from a given root path

Arguments

• root - the root directory path for the workspace

Examples

use workspace_tools ::Workspace;
use std ::path ::PathBuf;

let workspace = Workspace ::new( PathBuf ::from( "/path/to/workspace" ) );

pub fn resolve() -> Result<Self>

resolve workspace from environment variables

reads the WORKSPACE_PATH environment variable set by cargo configuration and validates that the workspace root exists.

errors

returns error if :

• WORKSPACE_PATH environment variable is not set
• the path specified by WORKSPACE_PATH does not exist

examples

use workspace_tools ::Workspace;

let workspace = Workspace ::resolve()?;
println!( "workspace root: {}", workspace.root().display() );

Errors

Returns an error if the workspace path environment variable is not set or the path doesn’t exist.

pub fn resolve_with_extended_fallbacks() -> Self

resolve workspace with extended fallback strategies

tries multiple strategies to find workspace root, including user-configured locations for installed CLI applications:

1. cargo workspace detection (developer context)
2. WORKSPACE_PATH environment variable (cargo operations)
3. git repository root with Cargo.toml (developer context)
4. $PRO environment variable (user-configured project root)
5. $HOME directory (universal fallback)
6. current working directory (last resort)

this method is designed for CLI applications that need to work both during development (via cargo run) and after installation (via cargo install).

examples

use workspace_tools ::Workspace;

// this will always succeed with some workspace root
let workspace = Workspace ::resolve_with_extended_fallbacks();

resolution priority

developer contexts (cargo operations):

• from_cargo_workspace() → finds cargo workspace via metadata
• resolve() → uses WORKSPACE_PATH from .cargo/config.toml
• from_git_root() → searches upward for .git + Cargo.toml

user contexts (installed binaries):

• from_pro_env() → uses $PRO environment variable
• from_home_dir() → uses $HOME or %USERPROFILE%

fallback:

• from_cwd() → current working directory

pub fn resolve_or_fallback() -> Self

👎Deprecated since 0.8.0: use resolve_with_extended_fallbacks() for installed CLI app support

resolve workspace with fallback strategies

deprecated

use resolve_with_extended_fallbacks() instead. this method lacks support for installed CLI application contexts ($PRO and $HOME fallbacks).

migration

// old:
let ws = Workspace ::resolve_or_fallback();

// new:
let ws = Workspace ::resolve_with_extended_fallbacks();

examples

use workspace_tools ::Workspace;

// this will always succeed with some workspace root
let workspace = Workspace ::resolve_or_fallback();

pub fn from_current_dir() -> Result<Self>

create workspace from current working directory

Errors

returns error if current directory cannot be accessed

pub fn from_git_root() -> Result<Self>

create workspace from git repository root

searches upward from current directory for .git directory

Errors

returns error if current directory cannot be accessed or no .git directory found

pub fn from_cwd() -> Self

create workspace from current working directory (infallible)

this method will not fail - it uses current directory or root as fallback

pub fn from_pro_env() -> Result<Self>

create workspace from $PRO environment variable

intended for users who organize projects under a common root directory. the $PRO environment variable should point to the projects root.

setup

# linux/mac
export PRO=~/pro
echo 'export PRO=~/pro' >> ~/.bashrc

# windows
set PRO=%USERPROFILE%\pro
setx PRO "%USERPROFILE%\pro"

examples

use workspace_tools ::Workspace;

// user has: export PRO=~/pro
let workspace = Workspace ::from_pro_env().unwrap();
// workspace.root() → /home/user/pro

Errors

returns error if:

• $PRO environment variable is not set
• path specified by $PRO does not exist

use cases

• installed CLI tools needing workspace-level secrets
• multi-project users with organized directory structure
• CI/CD environments with standardized project layouts

pub fn from_home_dir() -> Result<Self>

create workspace from user home directory

universal fallback using the standard home directory location. works cross-platform by checking both unix ($HOME) and windows (%USERPROFILE%).

examples

use workspace_tools ::Workspace;

let workspace = Workspace ::from_home_dir().unwrap();
// linux/mac: workspace.root() → /home/user
// windows:   workspace.root() → C:\Users\user

Errors

returns error if:

• neither $HOME nor %USERPROFILE% environment variables are set
• resolved path does not exist

use cases

• simple secret storage in ~/secret/ directory
• casual users without complex project organization
• minimal configuration requirement for CLI tools

pub fn root(&self) -> &Path

get workspace root directory

Path Normalization Guarantees

the returned path is guaranteed to be:

• absolute (not relative)
• normalized (no /./ or trailing /.)
• preserves symlinks (does not resolve to canonical path)

examples

use workspace_tools ::workspace;

let ws = workspace()?;
let root = ws.root();

// always absolute
assert!( root.is_absolute() );

// never contains "/./"
assert!( !root.to_string_lossy().contains( "/./" ) );

// never ends with "/."
assert!( !root.to_string_lossy().ends_with( "/." ) );

// clean path joining
let secret_dir = root.join( "secret" );
// produces: "/path/to/workspace/secret" not "/path/to/workspace/./secret"

pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf

join path components relative to workspace root

examples

use workspace_tools ::workspace;

let ws = workspace()?;
let config_file = ws.join( "config/app.toml" );

pub fn config_dir(&self) -> PathBuf

get standard configuration directory

returns workspace_root/config

pub fn data_dir(&self) -> PathBuf

get standard data directory

returns workspace_root/data

pub fn logs_dir(&self) -> PathBuf

get standard logs directory

returns workspace_root/logs

pub fn docs_dir(&self) -> PathBuf

get standard documentation directory

returns workspace_root/docs

pub fn tests_dir(&self) -> PathBuf

get standard tests directory

returns workspace_root/tests

pub fn workspace_dir(&self) -> PathBuf

get workspace metadata directory

returns workspace_root/.workspace

pub fn cargo_toml(&self) -> PathBuf

get path to workspace cargo.toml

returns workspace_root/Cargo.toml

pub fn readme(&self) -> PathBuf

get path to workspace readme

returns workspace_root/readme.md

pub fn validate(&self) -> Result<()>

validate workspace structure

checks that workspace root exists and is accessible

Errors

returns error if workspace root is not accessible or is not a directory

pub fn is_workspace_file<P: AsRef<Path>>(&self, path: P) -> bool

check if a path is within workspace boundaries

examples

use workspace_tools ::workspace;

let ws = workspace()?;
let config_path = ws.join( "config/app.toml" );

assert!( ws.is_workspace_file( &config_path ) );
assert!( !ws.is_workspace_file( "/etc/passwd" ) );

pub fn normalize_path<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

normalize path for cross-platform compatibility

resolves symbolic links and canonicalizes the path

Errors

returns error if path cannot be canonicalized or does not exist

pub fn find_config(&self, name: &str) -> Result<PathBuf>

find configuration file by name

searches for configuration files in standard locations :

• config/{name}.toml
• config/{name}.yaml
• config/{name}.json
• .{name}.toml (dotfile in workspace root)

Errors

returns error if no configuration file with the given name is found

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// looks for config/database.toml, config/database.yaml, etc.
if let Ok( config_path ) = ws.find_config( "database" )
{
    println!( "found config at: {}", config_path.display() );
}

impl Workspace

pub fn find_resources(&self, pattern: &str) -> Result<Vec<PathBuf>>

find files matching a glob pattern within the workspace

Errors

returns error if the glob pattern is invalid or if there are errors reading the filesystem

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// find all rust source files
let rust_files = ws.find_resources( "src/**/*.rs" )?;

// find all configuration files
let configs = ws.find_resources( "config/**/*.toml" )?;

impl Workspace

pub fn secret_dir(&self) -> PathBuf

get secrets directory path

returns workspace_root/secret

pub fn secret_file(&self, name: &str) -> PathBuf

get path to secret configuration file

returns workspace_root/secret/{name}

pub fn load_secrets_from_file( &self, filename: &str, ) -> Result<HashMap<String, String>>

load secrets from a file in the workspace secrets directory

supports shell script format (KEY=value lines) and loads secrets from filenames within the workspace secret/ directory

Path Resolution

Files are resolved as: workspace_root/secret/{filename}

Important : This method expects a filename, not a path. If you need to load from a path, use load_secrets_from_path() instead.

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// ✅ Correct usage - simple filenames only
// let secrets = ws.load_secrets_from_file( "-secrets.sh" )?;      // -> secret/-secrets.sh
// let dev = ws.load_secrets_from_file( "development.env" )?;      // -> secret/development.env

// ❌ Common mistake - using paths (will emit warning)
// let secrets = ws.load_secrets_from_file( "config/secrets.env" )?; // DON'T DO THIS

// ✅ For paths, use the path-specific method instead
// let path_secrets = ws.load_secrets_from_path( "config/secrets.env" )?; // -> workspace/config/secrets.env

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secret_key(&self, key_name: &str, filename: &str) -> Result<String>

load a specific secret key with fallback to environment

tries to load from secret file first, then falls back to environment variable this method uses filename-based resolution (looks in secret/ directory)

Path Resolution

Files are resolved as: workspace_root/secret/{filename}

Fallback Strategy

1. First attempts to load from secrets file
2. If key not found in file or file doesn’t exist, checks environment variables
3. If neither source contains the key, returns error

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// ✅ Correct usage - filename only
match ws.load_secret_key( "API_KEY", "-secrets.sh" )  // -> secret/-secrets.sh
{
    Ok( key ) => println!( "loaded api key from file or environment" ),
    Err( e ) => println!( "api key not found: {}", e ),
}

// ❌ Common mistake - using paths (will emit warning)
// let key = ws.load_secret_key( "API_KEY", "config/secrets.env" )?; // DON'T DO THIS

Errors

returns error if the key is not found in either the secret file or environment variables

pub fn list_secrets_files(&self) -> Result<Vec<String>>

list available secrets files in the secrets directory

returns vector of filenames (not full paths) found in secret/ directory

examples

use workspace_tools ::workspace;

let ws = workspace()?;
let files = ws.list_secrets_files()?;
println!( "Available secret files: {:?}", files );

Errors

returns error if the secrets directory cannot be read

pub fn secrets_file_exists(&self, secret_file_name: &str) -> bool

check if a secrets file exists

returns true if the file exists in the secrets directory

examples

use workspace_tools ::workspace;

let ws = workspace()?;

if ws.secrets_file_exists( "-secrets.sh" )
{
    println!( "secrets file found" );
}

pub fn resolve_secrets_path(&self, secret_file_name: &str) -> PathBuf

get resolved path for secrets file (for debugging)

returns the full path where the secrets file would be located

examples

use workspace_tools ::workspace;

let ws = workspace()?;
let path = ws.resolve_secrets_path( "-secrets.sh" );
println!( "Secrets file would be at: {}", path.display() );

pub fn load_secrets_from_path( &self, relative_path: &str, ) -> Result<HashMap<String, String>>

load secrets from workspace-relative path

loads secrets from a file specified as a path relative to the workspace root use this method when you need to load secrets from custom locations

Path Resolution

Files are resolved as: workspace_root/{relative_path}

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// load from config/secrets.env (workspace_root/config/secrets.env)
// let secrets = ws.load_secrets_from_path( "config/secrets.env" )?;

// load from nested directory
// let nested = ws.load_secrets_from_path( "lib/project/secret/api.env" )?;

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secrets_from_absolute_path( &self, absolute_path: &Path, ) -> Result<HashMap<String, String>>

load secrets from absolute path

loads secrets from a file specified as an absolute filesystem path use this method when you need to load secrets from locations outside the workspace

examples

use workspace_tools ::workspace;
use std ::path ::Path;

let ws = workspace()?;

// load from absolute path
let absolute_path = Path ::new( "/etc/secrets/production.env" );
// let secrets = ws.load_secrets_from_absolute_path( absolute_path )?;

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secrets_with_debug( &self, secret_file_name: &str, ) -> Result<HashMap<String, String>>

load secrets with verbose debug information

provides detailed path resolution and validation information for debugging use this method when troubleshooting secret loading issues

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// load with debug output
match ws.load_secrets_with_debug( "-secrets.sh" )
{
    Ok( secrets ) => println!( "Loaded {} secrets", secrets.len() ),
    Err( e ) => println!( "Failed to load secrets: {}", e ),
}

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

impl Workspace

pub fn load_secrets_secure( &self, filename: &str, ) -> Result<HashMap<String, SecretString>>

load secrets from a file in the workspace secrets directory with memory-safe handling

returns secrets as SecretString types for enhanced security supports shell script format (KEY=value lines) and loads secrets from filenames within the workspace secret/ directory

Path Resolution

Files are resolved as: workspace_root/secret/{filename}

Important : This method expects a filename, not a path. If you need to load from a path, use load_secrets_from_path_secure() instead.

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;

let ws = workspace()?;

// ✅ Correct usage - simple filenames only
// let secrets = ws.load_secrets_secure( "-secrets.sh" )?;         // -> secret/-secrets.sh
// let dev = ws.load_secrets_secure( "development.env" )?;         // -> secret/development.env

// Access secret values (requires explicit expose_secret() call)
// if let Some( api_key ) = secrets.get( "API_KEY" )
// {
//     println!( "loaded api key: {}", api_key.expose_secret() );
// }

// ❌ Common mistake - using paths (will emit warning)
// let secrets = ws.load_secrets_secure( "config/secrets.env" )?; // DON'T DO THIS

// ✅ For paths, use the path-specific method instead
// let path_secrets = ws.load_secrets_from_path_secure( "config/secrets.env" )?;

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secret_key_secure( &self, key_name: &str, filename: &str, ) -> Result<SecretString>

load a specific secret key with memory-safe handling and fallback to environment

tries to load from secret file first, then falls back to environment variable returns SecretString for enhanced security

Errors

returns error if the key is not found in either the secret file or environment variables

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;

let ws = workspace()?;

// looks for API_KEY in secret/-secrets.sh, then in environment
match ws.load_secret_key_secure( "API_KEY", "-secrets.sh" )
{
    Ok( key ) => println!( "loaded api key: {}", key.expose_secret() ),
    Err( _ ) => println!( "api key not found" ),
}

pub fn env_secret(&self, key: &str) -> Option<SecretString>

get environment variable as SecretString for memory-safe handling

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;

let ws = workspace()?;

if let Some( token ) = ws.env_secret( "GITHUB_TOKEN" )
{
    println!( "using secure token: {}", token.expose_secret() );
}

pub fn validate_secret(&self, secret: &str) -> Result<()>

validate secret strength and security requirements

checks for common security issues like weak passwords, common patterns, etc.

Errors

returns error if the secret does not meet minimum security requirements

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// this will fail - too weak
assert!( ws.validate_secret( "123" ).is_err() );

// this will pass - strong secret
assert!( ws.validate_secret( "super-strong-secret-2024!" ).is_ok() );

pub fn load_config_with_secret_injection( &self, config_file: &str, secret_file: &str, ) -> Result<String>

load configuration with automatic secret injection

replaces ${VAR_NAME} placeholders in configuration with values from secret files

Errors

returns error if configuration file cannot be read or secret injection fails

examples

use workspace_tools ::workspace;

let ws = workspace()?;

// loads config.toml and replaces ${SECRET} with values from secrets.sh
let config = ws.load_config_with_secret_injection( "config.toml", "secrets.sh" )?;

pub fn load_config_with_secrets<T: SecretInjectable>( &self, config: T, secret_file: &str, ) -> Result<T>

load configuration with automatic secret injection using SecretInjectable trait

loads secrets from file and injects them into the configuration type

Errors

returns error if secret loading or injection fails

examples

use workspace_tools :: { workspace, SecretInjectable };

#[ derive(Debug) ]
struct AppConfig {
    database_url: String,
    api_key: String,
}

impl SecretInjectable for AppConfig
{
  fn inject_secret(&mut self, key: &str, value: String) -> workspace_tools ::Result< () >
  {
    match key
    {
            "DATABASE_URL" => self.database_url = value,
            "API_KEY" => self.api_key = value,
            _ => return Err(workspace_tools ::WorkspaceError::SecretInjectionError(
                format!("unknown secret key: {}", key)
)),
}
        Ok(())
}

    fn validate_secrets( &self ) -> workspace_tools ::Result< () > {
 if self.api_key.is_empty() {
            return Err(workspace_tools ::WorkspaceError::SecretValidationError(
                "api_key cannot be empty".to_string()
));
}
        Ok(())
}
}

let ws = workspace()?;
let mut config = AppConfig { database_url: String ::new(), api_key: String ::new() };

// config gets secrets injected from secret/-config.sh
config = ws.load_config_with_secrets( config, "-config.sh" )?;

pub fn load_secrets_from_path_secure( &self, relative_path: &str, ) -> Result<HashMap<String, SecretString>>

load secrets from workspace-relative path with memory-safe handling

loads secrets from a file specified as a path relative to the workspace root returns secrets as SecretString types for enhanced security

Path Resolution

Files are resolved as: workspace_root/{relative_path}

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;

let ws = workspace()?;

// load from config/secrets.env (workspace_root/config/secrets.env)
// let secrets = ws.load_secrets_from_path_secure( "config/secrets.env" )?;

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secrets_from_absolute_path_secure( &self, absolute_path: &Path, ) -> Result<HashMap<String, SecretString>>

load secrets from absolute path with memory-safe handling

loads secrets from a file specified as an absolute filesystem path returns secrets as SecretString types for enhanced security

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;
use std ::path ::Path;

let ws = workspace()?;

// load from absolute path
// let absolute_path = Path ::new( "/etc/secrets/production.env" );
// let secrets = ws.load_secrets_from_absolute_path_secure( absolute_path )?;

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

pub fn load_secrets_with_debug_secure( &self, secret_file_name: &str, ) -> Result<HashMap<String, SecretString>>

load secrets with verbose debug information and memory-safe handling

provides detailed path resolution and validation information for debugging returns secrets as SecretString types for enhanced security

examples

use workspace_tools ::workspace;
use secrecy ::ExposeSecret;

let ws = workspace()?;

// load with debug output
match ws.load_secrets_with_debug_secure( "-secrets.sh" )
{
    Ok( secrets ) => println!( "Loaded {} secrets", secrets.len() ),
    Err( e ) => println!( "Failed to load secrets: {}", e ),
}

Errors

returns error if the file cannot be read, doesn’t exist, or contains invalid format

impl Workspace

pub fn from_cargo_workspace() -> Result<Self>

create workspace from cargo workspace root (auto-detected)

traverses up directory tree looking for Cargo.toml with [workspace] section or workspace member that references a workspace root

Errors

returns error if no cargo workspace is found or if cargo.toml cannot be parsed

examples

use workspace_tools ::Workspace;

let workspace = Workspace ::from_cargo_workspace()?;
println!( "cargo workspace root: {}", workspace.root().display() );

pub fn from_cargo_manifest<P: AsRef<Path>>(manifest_path: P) -> Result<Self>

create workspace from specific cargo.toml path

Errors

returns error if the manifest path does not exist or cannot be parsed

pub fn cargo_metadata(&self) -> Result<CargoMetadata>

get cargo metadata for this workspace

Errors

returns error if cargo metadata command fails or workspace is not a cargo workspace

pub fn is_cargo_workspace(&self) -> bool

check if this workspace is a cargo workspace

pub fn workspace_members(&self) -> Result<Vec<PathBuf>>

get workspace members (if cargo workspace)

Errors

returns error if not a cargo workspace or cargo metadata fails

impl Workspace

pub fn load_config<T>(&self, name: &str) -> Result<T>

where T: DeserializeOwned,

load configuration with automatic format detection

Errors

returns error if configuration file is not found or cannot be deserialized

examples

use workspace_tools ::workspace;
use serde ::Deserialize;

#[ derive( Deserialize ) ]
struct AppConfig
{
    name: String,
    port: u16,
}

let ws = workspace()?;
// looks for config/app.toml, config/app.yaml, config/app.json
let config: AppConfig = ws.load_config( "app" )?;

pub fn load_config_from<T, P>(&self, path: P) -> Result<T>

where T: DeserializeOwned, P: AsRef<Path>,

load configuration from specific file

Errors

returns error if file cannot be read or deserialized

pub fn save_config<T>(&self, name: &str, config: &T) -> Result<()>

where T: Serialize,

save configuration with format matching the original

Errors

returns error if configuration cannot be serialized or written to file

pub fn save_config_to<T, P>(&self, path: P, config: &T) -> Result<()>

where T: Serialize, P: AsRef<Path>,

save configuration to specific file with format detection

Errors

returns error if configuration cannot be serialized or written to file

pub fn load_config_layered<T>(&self, names: &[&str]) -> Result<T>

where T: DeserializeOwned + ConfigMerge,

load and merge multiple configuration layers

Errors

returns error if any configuration file cannot be loaded or merged

pub fn update_config<T, U>(&self, name: &str, updates: U) -> Result<T>

where T: DeserializeOwned + Serialize, U: Serialize,

update configuration partially

Errors

returns error if configuration cannot be loaded, updated, or saved

impl Workspace

pub fn load_config_with_validation<T>(&self, name: &str) -> Result<T>

where T: DeserializeOwned + JsonSchema,

load and validate configuration against a json schema

Errors

returns error if configuration cannot be loaded, schema is invalid, or validation fails

examples

use workspace_tools ::workspace;
use serde :: { Deserialize };
use schemars ::JsonSchema;

#[ derive( Deserialize, JsonSchema ) ]
struct AppConfig
{
    name: String,
    port: u16,
}

let ws = workspace()?;
let config: AppConfig = ws.load_config_with_validation( "app" )?;

pub fn load_config_with_schema<T>( &self, name: &str, schema: &Validator, ) -> Result<T>

where T: DeserializeOwned,

load and validate configuration against a provided json schema

Errors

returns error if configuration cannot be loaded or validation fails

pub fn load_config_from_with_schema<T, P>( &self, path: P, schema: &Validator, ) -> Result<T>

where T: DeserializeOwned, P: AsRef<Path>,

load and validate configuration from specific file with schema

Errors

returns error if file cannot be read, parsed, or validated

pub fn validate_config_content( content: &str, schema: &Validator, format: &str, ) -> Result<()>

validate configuration content against schema without loading

Errors

returns error if content cannot be parsed or validation fails

Trait Implementations

impl Clone for Workspace

fn clone(&self) -> Workspace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Workspace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.