Struct GlobalConfig 

pub struct GlobalConfig {
    pub sources: HashMap<String, String>,
    pub upgrade: UpgradeConfig,
    pub max_content_file_size: u64,
    pub token_warning_threshold: u64,
}

Global configuration structure for AGPM.

This structure represents the global user configuration file stored at ~/.agpm/config.toml. It contains user-wide settings including authentication credentials for private Git repositories.

Security Considerations

• Never commit this configuration to version control
• Store only in the user’s home directory or secure location
• Contains sensitive data like authentication tokens
• Should have restricted file permissions (600 on Unix systems)

Structure

Currently contains only source definitions, but designed to be extensible for future configuration options like:

• Default author information
• Preferred Git configuration
• Cache settings
• Proxy configuration

Examples

use agpm_cli::config::GlobalConfig;
use std::collections::HashMap;

// Create new configuration
let mut config = GlobalConfig::default();

// Add authenticated source
config.add_source(
    "company".to_string(),
    "https://oauth2:token@github.com/company/agpm.git".to_string()
);

assert!(config.has_source("company"));

Fields

sources: HashMap<String, String>

Global Git repository sources with optional authentication.

Maps source names to Git repository URLs. These URLs may contain authentication credentials and are kept separate from project manifests for security.

Authentication URL Formats

• https://oauth2:token@github.com/owner/repo.git - GitHub personal access token
• https://gitlab-ci-token:token@gitlab.com/group/repo.git - GitLab deploy token
• git@github.com:owner/repo.git - SSH authentication
• https://user:pass@server.com/repo.git - Basic auth (not recommended)

Security Notes

• URLs with credentials are never logged in plain text
• The sources field is skipped during serialization if empty
• Authentication details should use tokens rather than passwords when possible

upgrade: UpgradeConfig

Upgrade configuration settings.

Controls the behavior of the self-upgrade functionality including update checks, backup preferences, and verification settings.

max_content_file_size: u64

Maximum file size in bytes for file operations.

Default: 1 MB (1,048,576 bytes)

This limit prevents memory exhaustion when reading or embedding files. Currently used by template content filter, may be used by other operations in the future.

Configuration

Set in ~/.agpm/config.toml:

max_content_file_size = 2097152  # 2 MB

token_warning_threshold: u64

Token count warning threshold.

Default: 100,000 tokens (Claude’s context window is ~200k)

Resources exceeding this threshold will emit a warning during installation. This helps identify resources that may consume significant context.

Configuration

Set in ~/.agpm/config.toml:

token_warning_threshold = 50000  # 50k tokens

Implementations

impl GlobalConfig

pub async fn load() -> Result<Self>

Load global configuration from the default platform-specific location.

Attempts to load the configuration file from the default path. If the file doesn’t exist, returns a default (empty) configuration instead of an error.

Default Locations

• Unix/macOS: ~/.agpm/config.toml
• Windows: %LOCALAPPDATA%\agpm\config.toml
• Override: Set AGPM_CONFIG_PATH environment variable

Examples

use agpm_cli::config::GlobalConfig;

let config = GlobalConfig::load().await?;
println!("Loaded {} global sources", config.sources.len());

Errors

Returns an error if:

• The default path cannot be determined
• The file exists but cannot be read
• The file contains invalid TOML syntax

pub async fn load_with_optional(path: Option<PathBuf>) -> Result<Self>

Load global configuration from an optional path.

If a path is provided, loads from that path. Otherwise, loads from the default location (~/.agpm/config.toml or platform equivalent).

Parameters

• path: Optional path to the configuration file

Returns

Returns the loaded configuration or a default configuration if the file doesn’t exist.

Errors

Returns an error if:

• The file exists but cannot be read
• The file contains invalid TOML syntax

pub async fn load_from(path: &Path) -> Result<Self>

Load global configuration from a specific file path.

This method is primarily used for testing or when a custom configuration location is needed.

Parameters

• path: Path to the configuration file to load

Examples

use agpm_cli::config::GlobalConfig;
use std::path::Path;

let config = GlobalConfig::load_from(Path::new("/custom/config.toml")).await?;

Errors

Returns an error if:

• The file cannot be read (permissions, not found, etc.)
• The file contains invalid TOML syntax
• The TOML structure doesn’t match the expected schema

pub async fn save(&self) -> Result<()>

Save global configuration to the default platform-specific location.

Saves the current configuration to the default path, creating parent directories as needed. The file is written atomically to prevent corruption during the write process.

File Permissions

The configuration file should be created with restricted permissions since it may contain sensitive authentication tokens.

Examples

use agpm_cli::config::GlobalConfig;

let mut config = GlobalConfig::load().await?;
config.add_source(
    "new".to_string(),
    "https://github.com/owner/repo.git".to_string()
);
config.save().await?;

Errors

Returns an error if:

• The default path cannot be determined
• Parent directories cannot be created
• The file cannot be written (permissions, disk space, etc.)
• Serialization to TOML fails

pub async fn save_to(&self, path: &Path) -> Result<()>

Save global configuration to a specific file path.

Creates parent directories as needed and writes the configuration as pretty-formatted TOML.

Parameters

• path: Path where the configuration file should be saved

Examples

use agpm_cli::config::GlobalConfig;
use std::path::Path;

let config = GlobalConfig::default();
config.save_to(Path::new("/tmp/test-config.toml")).await?;

Errors

Returns an error if:

• Parent directories cannot be created
• The file cannot be written
• Serialization to TOML fails

pub fn default_path() -> Result<PathBuf>

Get the default file path for global configuration.

Returns the platform-appropriate path for storing global configuration. This location is chosen to be secure and follow platform conventions.

Path Resolution

• Windows: %LOCALAPPDATA%\agpm\config.toml
• Unix/macOS: ~/.agpm/config.toml

Note: Environment variable overrides are deprecated. Use the load_with_optional() method with an explicit path instead for better thread safety.

Examples

use agpm_cli::config::GlobalConfig;

let path = GlobalConfig::default_path()?;
println!("Global config path: {}", path.display());

Errors

Returns an error if:

• The home directory cannot be determined
• The local data directory cannot be determined (Windows)

pub fn merge_sources( &self, local_sources: &HashMap<String, String>, ) -> HashMap<String, String>

Merge global sources with project manifest sources.

Combines the global configuration sources with sources from a project manifest, with project sources taking precedence over global sources. This allows users to maintain private authentication in global config while projects can override with public sources.

Merge Strategy

1. Start with all global sources (may include authentication)
2. Add/override with local sources from project manifest
3. Local sources win in case of name conflicts

Parameters

• local_sources: Sources from project manifest (agpm.toml)

Returns

Combined source map with local sources taking precedence.

Examples

use agpm_cli::config::GlobalConfig;
use std::collections::HashMap;

let mut global = GlobalConfig::default();
global.add_source(
    "private".to_string(),
    "https://token@private.com/repo.git".to_string()
);

let mut local = HashMap::new();
local.insert(
    "public".to_string(),
    "https://github.com/public/repo.git".to_string()
);

let merged = global.merge_sources(&local);
assert_eq!(merged.len(), 2);
assert!(merged.contains_key("private"));
assert!(merged.contains_key("public"));

Security Note

The merged result may contain authentication credentials from global sources. Handle with care and never log or expose in version control.

pub fn add_source(&mut self, name: String, url: String)

Add or update a source in the global configuration.

Adds a new source or updates an existing one with the given name and URL. The URL may contain authentication credentials.

Parameters

• name: Unique name for the source (used in manifests)
• url: Git repository URL, optionally with authentication

Examples

use agpm_cli::config::GlobalConfig;

let mut config = GlobalConfig::default();

// Add source with authentication
config.add_source(
    "private".to_string(),
    "https://oauth2:token@github.com/company/repo.git".to_string()
);

// Update existing source
config.add_source(
    "private".to_string(),
    "git@github.com:company/repo.git".to_string()
);

assert!(config.has_source("private"));

Security Note

URLs containing credentials should use tokens rather than passwords when possible.

pub fn remove_source(&mut self, name: &str) -> bool

Remove a source from the global configuration.

Removes the source with the given name if it exists.

Parameters

• name: Name of the source to remove

Returns

• true if the source was found and removed
• false if the source didn’t exist

Examples

use agpm_cli::config::GlobalConfig;

let mut config = GlobalConfig::default();
config.add_source("test".to_string(), "https://example.com/repo.git".to_string());

assert!(config.remove_source("test"));
assert!(!config.remove_source("test")); // Already removed

pub fn has_source(&self, name: &str) -> bool

Check if a source exists in the global configuration.

Parameters

• name: Name of the source to check

Returns

• true if the source exists
• false if the source doesn’t exist

Examples

use agpm_cli::config::GlobalConfig;

let mut config = GlobalConfig::default();
assert!(!config.has_source("test"));

config.add_source("test".to_string(), "https://example.com/repo.git".to_string());
assert!(config.has_source("test"));

pub fn get_source(&self, name: &str) -> Option<&String>

Get a source URL by name.

Returns a reference to the URL for the specified source name.

Parameters

• name: Name of the source to retrieve

Returns

• Some(&String) with the URL if the source exists
• None if the source doesn’t exist

Examples

use agpm_cli::config::GlobalConfig;

let mut config = GlobalConfig::default();
config.add_source(
    "test".to_string(),
    "https://example.com/repo.git".to_string()
);

assert_eq!(
    config.get_source("test"),
    Some(&"https://example.com/repo.git".to_string())
);
assert_eq!(config.get_source("missing"), None);

Security Note

The returned URL may contain authentication credentials. Handle with care.

pub fn init_example() -> Self

Create a global configuration with example content.

Creates a new configuration populated with example sources to demonstrate the expected format. Useful for initial setup or documentation.

Returns

A new GlobalConfig with example private source configuration.

Examples

use agpm_cli::config::GlobalConfig;

let config = GlobalConfig::init_example();
assert!(config.has_source("private"));

// The example uses a placeholder token
let url = config.get_source("private").unwrap();
assert!(url.contains("YOUR_TOKEN"));

Note

The example configuration contains placeholder values that must be replaced with actual authentication credentials before use.

Trait Implementations

impl Clone for GlobalConfig

fn clone(&self) -> GlobalConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for GlobalConfig

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

Formats the value using the given formatter.

impl Default for GlobalConfig

fn default() -> GlobalConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GlobalConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for GlobalConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.