Module installer 

Shared installation utilities for AGPM resources.

This module provides common functionality for installing resources from lockfile entries to the project directory. It’s shared between the install and update commands to avoid code duplication. The module includes both installation logic and automatic cleanup of removed or relocated artifacts.

SHA-Based Parallel Installation Architecture

The installer uses SHA-based worktrees for optimal parallel resource installation:

• SHA-based worktrees: Each unique commit gets one worktree for maximum deduplication
• Pre-resolved SHAs: All versions resolved to SHAs before installation begins
• Concurrency control: Direct parallelism control via –max-parallel flag
• Context-aware logging: Each operation includes dependency name for debugging
• Efficient cleanup: Worktrees are managed by the cache layer for reuse
• Pre-warming: Worktrees created upfront to minimize installation latency
• Automatic artifact cleanup: Removes old files when paths change or dependencies are removed

Installation Process

1. SHA validation: Ensures all resources have valid 40-character commit SHAs
2. Worktree pre-warming: Creates SHA-based worktrees for all unique commits
3. Parallel processing: Installs multiple resources concurrently using dedicated worktrees
4. Content validation: Validates markdown format and structure
5. Atomic installation: Files are written atomically to prevent corruption
6. Progress tracking: Real-time progress updates during parallel operations
7. Artifact cleanup: Automatically removes old files from previous installations when paths change

Artifact Cleanup (v0.3.18+)

The module provides automatic cleanup of obsolete artifacts when:

• Dependencies are removed: Files from removed dependencies are deleted
• Paths are relocated: Old files are removed when installed_at paths change
• Structure changes: Empty parent directories are cleaned up recursively

The cleanup process:

1. Compares old and new lockfiles to identify removed artifacts
2. Removes files that exist in the old lockfile but not in the new one
3. Recursively removes empty parent directories up to .claude/
4. Reports the number of cleaned artifacts to the user

See cleanup_removed_artifacts() for implementation details.

Performance Characteristics

• SHA-based deduplication: Multiple refs to same commit share one worktree
• Parallel processing: Multiple dependencies installed simultaneously
• Pre-warming optimization: Worktrees created upfront to minimize latency
• Parallelism-controlled: User controls concurrency via –max-parallel flag
• Atomic operations: Fast, safe file installation with proper error handling
• Reduced disk usage: No duplicate worktrees for identical commits
• Efficient cleanup: Minimal overhead for artifact cleanup operations

Re-exports

pub use project_lock::ProjectLock;

Modules

project_lock

Project-level file locking for cross-process coordination.

Structs

ConfigValidation

Result of configuration validation.

InstallContext

Installation context containing common parameters for resource installation.

InstallationResults

Results from a successful installation operation.

Enums

ResourceFilter

Filtering options for resource installation operations.

Functions

cleanup_removed_artifacts

Removes artifacts that are no longer needed based on lockfile comparison.

finalize_installation

Finalize installation by configuring hooks, MCP servers, and updating lockfiles.

find_parent_resources

Find parent resources that depend on the given resource.

install_resource

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

install_resource_with_progress

Install a single resource with progress bar updates for user feedback.

install_resources

install_updated_resources

Install only specific updated resources in parallel (selective installation).

validate_config

Validate project configuration for AGPM.