Struct Cache 

pub struct Cache { /* private fields */ }

Git repository cache for efficient resource management.

Manages repository cloning, updating, version management, and resource copying. Multiple instances can safely operate on same cache via CacheLock.

Implementations

impl Cache

pub fn new() -> Result<Self>

Creates cache instance with default platform-specific directory.

Linux/macOS: ~/.agpm/cache/, Windows: %LOCALAPPDATA%\agpm\cache\. Override with AGPM_CACHE_DIR environment variable.

pub fn with_dir(dir: PathBuf) -> Result<Self>

Creates cache instance with custom directory (useful for testing).

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

Ensures cache directory exists, creating if necessary. Safe to call multiple times.

pub fn cache_dir(&self) -> &Path

Returns path to cache directory.

pub fn get_worktree_path(&self, url: &str, sha: &str) -> Result<PathBuf>

Constructs worktree path for URL and SHA (does not check existence or create).

pub async fn get_or_clone_source( &self, name: &str, url: &str, version: Option<&str>, ) -> Result<PathBuf>

Gets or clones source repository to cache.

Handles cloning new repos and updating existing ones with file-based locking. Concurrent calls with same name block; different names run in parallel.

Arguments

• name - Source identifier for cache directory and locking
• url - Git repository URL (HTTPS, SSH, or local)
• version - Optional Git ref (tag, branch, commit, or None for default)

pub async fn cleanup_worktree(&self, worktree_path: &Path) -> Result<()>

Removes worktree using git worktree remove to properly clean up metadata.

This ensures both the worktree directory AND the bare repo’s metadata are cleaned up, preventing “missing but already registered worktree” errors on subsequent creation.

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

Removes all worktrees from cache and prunes bare repo references.

pub async fn get_or_create_worktree_for_sha( &self, name: &str, url: &str, sha: &str, context: Option<&str>, ) -> Result<PathBuf>

Gets or creates SHA-based worktree with notification coordination.

First thread creates worktree, others wait on notification. SHA-based ensures maximum reuse and deterministic installations.

Arguments

• sha - Full 40-character commit SHA (pre-resolved)

pub async fn copy_resource( &self, source_dir: &Path, source_path: &str, target_path: &Path, ) -> Result<()>

Copies resource file from cached repository to project (silent).

Uses copy-based approach (not symlinks) for cross-platform compatibility and Git integration. Creates parent directories automatically.

Arguments

• source_dir - Cached repository path
• source_path - Relative path within repository
• target_path - Absolute installation path

pub async fn copy_resource_with_output( &self, source_dir: &Path, source_path: &str, target_path: &Path, show_output: bool, ) -> Result<()>

Copies resource file with optional installation output.

Same as copy_resource but optionally displays “✅ Installed” messages.

Arguments

• show_output - Whether to display installation progress

pub async fn clean_unused(&self, active_sources: &[String]) -> Result<usize>

Removes cached repositories not in active sources list.

Returns count of removed directories. Displays progress messages.

Arguments

• active_sources - Source names to preserve

pub async fn get_cache_size(&self) -> Result<u64>

Calculates total cache size in bytes (recursive, returns 0 if not exists).

pub fn get_cache_location(&self) -> &Path

Returns cache directory path (may not exist, use ensure_cache_dir to create).

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

Removes entire cache directory (destructive, requires re-cloning repos).

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.