Module source 

Source repository management

This module manages source repositories that contain Claude Code resources (agents, snippets, etc.). Sources are Git repositories that are cloned/cached locally for efficient access and installation. The module provides secure, efficient, and cross-platform repository handling with comprehensive caching and authentication support.

Architecture Overview

The source management system is built around two main components:

• Source - Represents an individual repository with metadata and caching information
• SourceManager - Manages multiple sources with operations for syncing, verification, and caching

Source Configuration

Sources can be defined in two locations with different purposes:

1. Project manifest (agpm.toml) - Committed to version control, shared with team

   [sources]
   community = "https://github.com/example/agpm-community.git"
   official = "https://github.com/example/agpm-official.git"

2. Global config (~/.agpm/config.toml) - User-specific with authentication tokens

   [sources]
   private = "https://oauth2:ghp_xxxx@github.com/company/private-agpm.git"

Source Priority and Security

When sources are defined in both locations with the same name:

• Global sources are loaded first (contain authentication tokens)
• Local sources override global ones (for project-specific customization)
• Authentication tokens are kept separate from version control for security

Caching Architecture

The caching system provides efficient repository management:

Cache Directory Structure

~/.agpm/cache/
└── sources/
    ├── owner1_repo1/          # Cached repository
    │   ├── .git/              # Git metadata
    │   ├── agents/            # Resource files
    │   └── snippets/
    └── owner2_repo2/
        └── ...

Cache Naming Convention

Cache directories are named using the pattern {owner}_{repository} parsed from the Git URL. For invalid URLs, falls back to unknown_{source_name}.

Caching Strategy

• First Access: Repository is cloned to cache directory
• Subsequent Access: Use cached copy, fetch updates if needed
• Validation: Cache integrity is verified before use
• Cleanup: Invalid cache directories are automatically removed and re-cloned

Authentication Integration

Authentication is handled transparently through the global configuration:

• Public repositories: No authentication required
• Private repositories: Authentication tokens embedded in URLs in global config
• Security: Tokens never stored in project manifests or committed to version control
• Format: Standard Git URL format with embedded credentials

Supported Authentication Methods

• OAuth tokens: https://oauth2:token@github.com/repo.git
• Personal access tokens: https://username:token@github.com/repo.git
• SSH keys: git@github.com:owner/repo.git (uses system SSH configuration)

Repository Types

The module supports multiple repository types:

Remote Repositories

• HTTPS: https://github.com/owner/repo.git
• SSH: git@github.com:owner/repo.git

Local Repositories

• Absolute paths: /path/to/local/repo
• Relative paths: ../local-repo or ./local-repo
• File URLs: file:///absolute/path/to/repo

Synchronization Operations

Synchronization ensures local caches are up-to-date with remote repositories:

Sync Operations

• Clone: First-time repository retrieval
• Fetch: Update remote references without merging
• Validation: Verify repository integrity and accessibility
• Parallel: Multiple repositories can be synced concurrently

Offline Capabilities

• Cached repositories can be used offline
• Sync operations gracefully handle network failures
• Local repositories work without network access

Error Handling

The module provides comprehensive error handling for common scenarios:

• Network failures: Graceful degradation with cached repositories
• Authentication failures: Clear error messages with resolution hints
• Invalid repositories: Automatic cleanup and re-cloning
• Path issues: Cross-platform path handling and validation

Performance Considerations

Optimization Strategies

• Lazy loading: Sources are only cloned when needed
• Incremental updates: Only fetch changes, not full re-clone
• Parallel operations: Multiple repositories synced concurrently
• Cache reuse: Minimize redundant network operations

Resource Management

• Memory efficient: Repositories are accessed on-demand
• Disk usage: Cache cleanup for removed sources
• Network optimization: Minimal data transfer through Git’s efficient protocol

Cross-Platform Compatibility

Full support for Windows, macOS, and Linux:

• Path handling: Correct path separators and absolute path resolution
• Git command: Uses system git with platform-specific optimizations
• File permissions: Proper handling across different filesystems
• Authentication: Works with platform-specific credential managers

Usage Examples

Basic Source Management

use agpm_cli::source::{Source, SourceManager};
use agpm_cli::manifest::Manifest;
use std::path::Path;

// Load from manifest with global config integration
let manifest = Manifest::load(Path::new("agpm.toml"))?;
let mut manager = SourceManager::from_manifest_with_global(&manifest).await?;

// Sync a specific source
let repo = manager.sync("community").await?;
println!("Repository ready at: {:?}", repo.path());

// List all available sources
for source in manager.list() {
    println!("Source: {} -> {}", source.name, source.url);
}

Progress Monitoring

use agpm_cli::source::SourceManager;
use indicatif::ProgressBar;

let progress = ProgressBar::new(100);
progress.set_message("Syncing repositories...");

// Sync all sources
manager.sync_all().await?;

progress.finish_with_message("All sources synced successfully");

Direct URL Operations

use agpm_cli::source::SourceManager;

// Sync a repository by URL (for direct dependencies)
let repo = manager.sync_by_url(
    "https://github.com/example/dependency.git"
).await?;

// Access the cached repository
let cache_path = manager.get_cached_path(
    "https://github.com/example/dependency.git"
)?;

Structs

Source

Represents a Git repository source containing Claude Code resources.

SourceManager

Manages multiple source repositories with caching, synchronization, and verification.