Function install_resource 

pub async fn install_resource(
    entry: &LockedResource,
    project_dir: &Path,
    resource_dir: &str,
    cache: &Cache,
    force_refresh: bool,
) -> Result<(bool, String)>

Install a single resource from a lock entry using worktrees for parallel safety.

This function installs a resource specified by a lockfile entry to the project directory. It uses Git worktrees through the cache layer to enable safe parallel operations without conflicts between concurrent installations.

Arguments

• entry - The locked resource to install containing source and version info
• project_dir - The root project directory where resources should be installed
• resource_dir - The subdirectory name for this resource type (e.g., “agents”)
• cache - The cache instance for managing Git repositories and worktrees

Returns

Returns Ok((installed, checksum)) where:

• installed is true if the resource was actually installed (new or updated), false if the resource already existed and was unchanged
• checksum is the SHA-256 hash of the installed file content

Worktree Usage

For remote resources, this function:

1. Uses cache.get_or_clone_source_worktree_with_context() to get a worktree
2. Each dependency gets its own isolated worktree for parallel safety
3. Worktrees are automatically managed and reused by the cache layer
4. Context (dependency name) is provided for debugging parallel operations

Installation Process

1. Path resolution: Determines destination based on installed_at or defaults
2. Repository access: Gets worktree from cache (for remote) or validates local path
3. Content validation: Verifies markdown format and structure
4. Atomic write: Installs file atomically to prevent corruption

Examples

use agpm_cli::installer::install_resource;
use agpm_cli::lockfile::LockedResource;
use agpm_cli::cache::Cache;
use agpm_cli::core::ResourceType;
use std::path::Path;

let cache = Cache::new()?;
let entry = LockedResource {
    name: "example-agent".to_string(),
    source: Some("community".to_string()),
    url: Some("https://github.com/example/repo.git".to_string()),
    path: "agents/example.md".to_string(),
    version: Some("v1.0.0".to_string()),
    resolved_commit: Some("abc123".to_string()),
    checksum: "sha256:...".to_string(),
    installed_at: ".claude/agents/example.md".to_string(),
    dependencies: vec![],
    resource_type: ResourceType::Agent,
    tool: "claude-code".to_string(),
};

let (installed, checksum) = install_resource(&entry, Path::new("."), "agents", &cache, false).await?;
if installed {
    println!("Resource was installed with checksum: {}", checksum);
} else {
    println!("Resource already existed and was unchanged");
}

Error Handling

Returns an error if:

• The source repository cannot be accessed or cloned
• The specified file path doesn’t exist in the repository
• The file is not valid markdown format
• File system operations fail (permissions, disk space)
• Worktree creation fails due to Git issues