agpm_cli/cli/

install.rs

//! Install Claude Code resources from manifest dependencies.
//!
//! This module provides the `install` command which reads dependencies from the
//! `agpm.toml` manifest file, resolves them, and installs the resource files
//! to the project directory. The command supports both fresh installations and
//! updates to existing installations with advanced parallel processing capabilities.
//!
//! # Features
//!
//! - **Dependency Resolution**: Resolves all dependencies defined in the manifest
//! - **Transitive Dependencies**: Automatically discovers and installs dependencies declared in resource files
//! - **Lockfile Management**: Generates and maintains `agpm.lock` for reproducible builds
//! - **Worktree-Based Parallel Installation**: Uses Git worktrees for safe concurrent resource installation
//! - **Multi-Phase Progress Tracking**: Shows detailed progress with phase transitions and real-time updates
//! - **Resource Validation**: Validates markdown files and content during installation
//! - **Cache Support**: Advanced cache with instance-level optimizations and worktree management
//! - **Concurrency Control**: User-configurable parallelism via `--max-parallel` flag
//! - **Cycle Detection**: Prevents circular dependency loops in transitive dependency graphs
//!
//! # Examples
//!
//! Install all dependencies from manifest:
//! ```bash
//! agpm install
//! ```
//!
//! Force reinstall all dependencies:
//! ```bash
//! agpm install --force
//! ```
//!
//! Install without creating lockfile:
//! ```bash
//! agpm install --no-lock
//! ```
//!
//! Use frozen lockfile (CI/production):
//! ```bash
//! agpm install --frozen
//! ```
//!
//! Disable cache and clone fresh:
//! ```bash
//! agpm install --no-cache
//! ```
//!
//! Install only direct dependencies (skip transitive):
//! ```bash
//! agpm install --no-transitive
//! ```
//!
//! Preview installation without making changes:
//! ```bash
//! agpm install --dry-run
//! ```
//!
//! # Installation Process
//!
//! 1. **Manifest Loading**: Reads `agpm.toml` to understand dependencies
//! 2. **Source Synchronization**: Clones/fetches Git repositories for all sources
//! 3. **Dependency Resolution**: Resolves versions and creates dependency graph
//! 4. **Transitive Discovery**: Extracts dependencies from resource files (YAML/JSON metadata)
//! 5. **Cycle Detection**: Validates dependency graph for circular references
//! 6. **Worktree Preparation**: Pre-creates Git worktrees for optimal parallel access
//! 7. **Parallel Resource Installation**: Installs resources concurrently using isolated worktrees
//! 8. **Progress Coordination**: Updates multi-phase progress tracking throughout installation
//! 9. **Configuration Updates**: Updates hooks and MCP server configurations as needed
//! 10. **Lockfile Generation**: Creates or updates `agpm.lock` with checksums and metadata
//! 11. **Artifact Cleanup**: Removes old artifacts from removed or relocated dependencies
//!
//! # Error Conditions
//!
//! - No manifest file found in project
//! - Invalid manifest syntax or structure
//! - Dependency resolution conflicts
//! - Circular dependency loops detected
//! - Invalid transitive dependency metadata (malformed YAML/JSON)
//! - Network or Git access issues
//! - File system permissions or disk space issues
//! - Invalid resource file format
//!
//! # Performance
//!
//! The install command is optimized for maximum performance:
//! - **Worktree-based parallelism**: Each dependency gets its own isolated Git worktree
//! - **Instance-level caching**: Optimized worktree reuse within command execution
//! - **Configurable concurrency**: `--max-parallel` flag controls dependency-level parallelism
//! - **Pre-warming strategy**: Creates all needed worktrees upfront for optimal parallel access
//! - **Atomic file operations**: Safe, corruption-resistant file installation
//! - **Multi-phase progress**: Real-time progress updates with phase transitions
//!
//! # Optimization Tiers
//!
//! The install command uses a tiered optimization strategy for repeated installations:
//!
//! 1. **Fast Path** (skip resolution): When the manifest hash matches and all dependencies
//!    are immutable (Git-based with tags/SHAs), the entire resolution phase is skipped.
//!    The lockfile is used directly as the installation plan.
//!    - Triggered by: `manifest_hash` match + `has_mutable_deps = false` + valid `resource_count`
//!    - Saves: Network fetches, version resolution, transitive dependency discovery
//!
//! 2. **Ultra-Fast Path** (skip checksum computation): For each resource being installed,
//!    if all content-affecting inputs match the previous lockfile entry (commit, path,
//!    patches, template vars) and the file exists, skip reading and hashing the file.
//!    - Triggered by: `trust_lockfile_checksums = true` + all inputs match old entry
//!    - Saves: File I/O, SHA-256 computation (significant for large files)
//!
//! 3. **Trust Mode**: Within ultra-fast path, when a resource's inputs match exactly,
//!    the previous checksum is reused without verification. This is safe because
//!    immutable Git dependencies (tags/SHAs) guarantee identical content.
//!
//! # Security Considerations
//!
//! Trust mode assumes:
//! - Upstream repositories have not been compromised (tag force-push attacks)
//! - The local cache (`~/.agpm/cache/`) has not been tampered with
//!
//! For security-sensitive environments, consider:
//! - Using `--no-cache` to always fetch fresh content
//! - Modifying the manifest to force re-resolution (e.g., bumping version)
//! - Regularly auditing installed resources against known-good checksums

use anyhow::Result;
use clap::Args;
use std::path::{Path, PathBuf};

use crate::cache::Cache;
use crate::constants::{FALLBACK_CORE_COUNT, MIN_PARALLELISM, PARALLELISM_CORE_MULTIPLIER};
use crate::core::{OperationContext, ResourceIterator};
use crate::lockfile::LockFile;
use crate::manifest::{ResourceDependency, find_manifest_with_optional};
use crate::resolver::DependencyResolver;

/// Check if the fast path can be used to skip dependency resolution.
///
/// The fast path allows skipping resolution entirely when:
/// - Not in frozen mode (frozen uses lockfile as-is, different path)
/// - An existing lockfile exists with matching manifest hash
/// - All dependencies are immutable (no branches or local files)
/// - The lockfile resource count matches the stored count (integrity check)
///
/// # Arguments
///
/// * `existing_lockfile` - Optional reference to the existing lockfile
/// * `current_manifest_hash` - Hash of the current manifest dependencies
/// * `has_mutable_deps` - Whether the manifest has any mutable dependencies
/// * `frozen` - Whether running in frozen mode
///
/// # Returns
///
/// `true` if fast path can be used (skip resolution), `false` otherwise.
fn can_use_fast_path(
    existing_lockfile: Option<&LockFile>,
    current_manifest_hash: &str,
    has_mutable_deps: bool,
    frozen: bool,
) -> bool {
    // Frozen mode uses the lockfile as-is through a different code path
    if frozen {
        return false;
    }

    let Some(existing) = existing_lockfile else {
        return false;
    };

    // Lockfile must have valid fast-path metadata (both manifest_hash and has_mutable_deps)
    // Older lockfiles without these fields require full resolution
    if !existing.has_valid_fast_path_metadata() {
        tracing::debug!("Fast path disabled: lockfile missing fast-path metadata fields");
        return false;
    }

    // Validate manifest_hash format to catch corrupted/manually edited lockfiles
    if !existing.has_valid_manifest_hash_format() {
        tracing::debug!("Fast path disabled: lockfile has invalid manifest_hash format");
        return false;
    }

    // Manifest hash must match (no dependency changes)
    // This is the primary check - if the manifest hash matches, we know the
    // dependency specifications are identical. This includes direct deps,
    // pattern expansions, and transitive dependency declarations.
    let hash_matches = existing.manifest_hash.as_ref() == Some(&current_manifest_hash.to_string());
    if !hash_matches {
        return false;
    }

    // Both lockfile and manifest must agree on no mutable deps
    let no_mutable_deps = existing.has_mutable_deps == Some(false) && !has_mutable_deps;
    if !no_mutable_deps {
        return false;
    }

    // Validate resource count matches (detects manually edited lockfiles)
    if !existing.has_valid_resource_count() {
        tracing::debug!(
            "Fast path disabled: resource count mismatch (stored: {:?}, actual: {})",
            existing.resource_count,
            existing.all_resources().len()
        );
        return false;
    }

    true
}

/// Command to install Claude Code resources from manifest dependencies.
///
/// This command reads the project's `agpm.toml` manifest file, resolves all dependencies,
/// and installs the resource files to the appropriate directories. It generates or updates
/// a `agpm.lock` lockfile to ensure reproducible installations.
///
/// # Behavior
///
/// 1. Locates and loads the project manifest (`agpm.toml`)
/// 2. Resolves dependencies using the dependency resolver
/// 3. Downloads or updates Git repository sources as needed
/// 4. Installs resource files to target directories
/// 5. Generates or updates the lockfile (`agpm.lock`)
/// 6. Provides progress feedback during installation
///
/// # Examples
///
/// ```rust,no_run
/// use agpm_cli::cli::install::InstallCommand;
///
/// // Standard installation
/// let cmd = InstallCommand {
///     no_lock: false,
///     frozen: false,
///     no_cache: false,
///     max_parallel: None,
///     quiet: false,
///     no_progress: false,
///     verbose: false,
///     no_transitive: false,
///     dry_run: false,
///     yes: false,
/// };
///
/// // CI/Production installation (frozen lockfile)
/// let cmd = InstallCommand {
///     no_lock: false,
///     frozen: true,
///     no_cache: false,
///     max_parallel: Some(2),
///     quiet: false,
///     no_progress: false,
///     verbose: false,
///     no_transitive: false,
///     dry_run: false,
///     yes: false,
/// };
/// ```
#[derive(Args)]
pub struct InstallCommand {
    /// Don't write lockfile after installation
    ///
    /// Prevents the command from creating or updating the `agpm.lock` file.
    /// This is useful for development scenarios where you don't want to
    /// commit lockfile changes.
    #[arg(long)]
    pub no_lock: bool,

    /// Verify checksums from existing lockfile
    ///
    /// Uses the existing lockfile as-is without updating dependencies.
    /// This mode ensures reproducible installations and is recommended
    /// for CI/CD pipelines and production deployments.
    #[arg(long)]
    pub frozen: bool,

    /// Don't use cache, clone fresh repositories
    ///
    /// Disables the local Git repository cache and clones repositories
    /// to temporary locations. This increases installation time but ensures
    /// completely fresh downloads.
    #[arg(long)]
    pub no_cache: bool,

    /// Maximum number of parallel operations (default: max(MIN_PARALLELISM, PARALLELISM_CORE_MULTIPLIER × CPU cores))
    ///
    /// Controls the level of parallelism during installation. The default value
    /// is calculated as `max(MIN_PARALLELISM, PARALLELISM_CORE_MULTIPLIER × CPU cores)` to provide good performance
    /// while avoiding resource exhaustion. Higher values can speed up installation
    /// of many dependencies but may strain system resources or hit API rate limits.
    ///
    /// # Performance Impact
    ///
    /// - **Low values (1-4)**: Conservative approach, slower but more reliable
    /// - **Default values (10-16)**: Balanced performance for most systems
    /// - **High values (>20)**: May overwhelm system resources or trigger rate limits
    ///
    /// # Examples
    ///
    /// - `--max-parallel 1`: Sequential installation (debugging)
    /// - `--max-parallel 4`: Conservative parallel installation
    /// - `--max-parallel 20`: Aggressive parallel installation (powerful systems)
    #[arg(long, value_name = "NUM")]
    pub max_parallel: Option<usize>,

    /// Suppress non-essential output
    ///
    /// When enabled, only errors and essential information will be printed.
    /// Progress bars and status messages will be hidden.
    #[arg(short, long)]
    pub quiet: bool,

    /// Disable progress bars (for programmatic use, not exposed as CLI arg)
    #[arg(skip)]
    pub no_progress: bool,

    /// Enable verbose output (for programmatic use, not exposed as CLI arg)
    ///
    /// This flag is populated from the global --verbose flag via execute_with_config
    #[arg(skip)]
    pub verbose: bool,

    /// Don't resolve transitive dependencies
    ///
    /// When enabled, only direct dependencies from the manifest will be installed.
    /// Transitive dependencies declared within resource files (via YAML frontmatter
    /// or JSON fields) will be ignored. This can be useful for faster installations
    /// when you know transitive dependencies are already satisfied or for debugging
    /// dependency issues.
    #[arg(long)]
    pub no_transitive: bool,

    /// Preview installation without making changes
    ///
    /// Shows what would be installed, including new dependencies and lockfile changes,
    /// but doesn't modify any files. Useful for reviewing changes before applying them,
    /// especially in CI/CD pipelines to detect when dependencies would change.
    ///
    /// When enabled:
    /// - Resolves all dependencies normally
    /// - Shows what resources would be installed
    /// - Shows lockfile changes (new entries, version updates)
    /// - Does NOT write the lockfile
    /// - Does NOT install any resources
    ///
    /// Exit codes:
    /// - 0: No changes would be made
    /// - 1: Changes would be made (useful for CI checks)
    #[arg(long)]
    pub dry_run: bool,

    /// Automatically accept migration prompts
    ///
    /// When set, automatically accepts migration prompts for legacy CCPM files
    /// or legacy AGPM format without requiring user interaction. Useful for
    /// CI/CD pipelines and automated scripts.
    #[arg(short = 'y', long)]
    pub yes: bool,
}

impl Default for InstallCommand {
    fn default() -> Self {
        Self::new()
    }
}

impl InstallCommand {
    /// Creates a default `InstallCommand` for programmatic use.
    ///
    /// This constructor creates an `InstallCommand` with standard settings:
    /// - Lockfile generation enabled
    /// - Fresh dependency resolution (not frozen)
    /// - Cache enabled for performance
    /// - Default parallelism (see `--max-parallel` for formula)
    /// - Progress output enabled
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use agpm_cli::cli::install::InstallCommand;
    ///
    /// let cmd = InstallCommand::new();
    /// // cmd can now be executed with execute_from_path()
    /// ```
    #[allow(dead_code)] // Used by Default impl and in tests
    pub const fn new() -> Self {
        Self {
            no_lock: false,
            frozen: false,
            no_cache: false,
            max_parallel: None,
            quiet: false,
            no_progress: false,
            verbose: false,
            no_transitive: false,
            dry_run: false,
            yes: false,
        }
    }

    /// Creates an `InstallCommand` configured for quiet operation.
    ///
    /// This constructor creates an `InstallCommand` with quiet mode enabled,
    /// which suppresses progress bars and non-essential output. Useful for
    /// automated scripts or CI/CD environments where minimal output is desired.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use agpm_cli::cli::install::InstallCommand;
    ///
    /// let cmd = InstallCommand::new_quiet();
    /// // cmd will execute without progress bars or status messages
    /// ```
    #[allow(dead_code)] // Used in integration tests for quiet mode testing
    pub const fn new_quiet() -> Self {
        Self {
            no_lock: false,
            frozen: false,
            no_cache: false,
            max_parallel: None,
            quiet: true,
            no_progress: true,
            verbose: false,
            no_transitive: false,
            dry_run: false,
            yes: false,
        }
    }

    /// Executes the install command with automatic manifest discovery.
    ///
    /// This method provides convenient manifest file discovery, searching for
    /// `agpm.toml` in the current directory and parent directories if no specific
    /// path is provided. It's the standard entry point for CLI usage.
    ///
    /// # Arguments
    ///
    /// * `manifest_path` - Optional explicit path to `agpm.toml`. If `None`,
    ///   the method searches for `agpm.toml` starting from the current directory
    ///   and walking up the directory tree.
    ///
    /// # Manifest Discovery
    ///
    /// When `manifest_path` is `None`, the search process:
    /// 1. Checks current directory for `agpm.toml`
    /// 2. Walks up parent directories until `agpm.toml` is found
    /// 3. Stops at filesystem root if no manifest found
    /// 4. Returns an error with helpful guidance if no manifest exists
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use agpm_cli::cli::install::InstallCommand;
    /// use std::path::PathBuf;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let cmd = InstallCommand::new();
    ///
    /// // Auto-discover manifest in current directory or parents
    /// cmd.execute_with_manifest_path(None).await?;
    ///
    /// // Use specific manifest file
    /// cmd.execute_with_manifest_path(Some(PathBuf::from("./my-project/agpm.toml"))).await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - No `agpm.toml` file found in search path
    /// - Specified manifest path doesn't exist
    /// - Manifest file contains invalid TOML syntax
    /// - Dependencies cannot be resolved
    /// - Installation process fails
    ///
    /// # Error Messages
    ///
    /// When no manifest is found, the error includes helpful guidance:
    /// ```text
    /// No agpm.toml found in current directory or any parent directory.
    ///
    /// To get started, create a agpm.toml file with your dependencies:
    ///
    /// [sources]
    /// official = "https://github.com/example-org/agpm-official.git"
    ///
    /// [agents]
    /// my-agent = { source = "official", path = "agents/my-agent.md", version = "v1.0.0" }
    /// ```
    pub async fn execute_with_manifest_path(self, manifest_path: Option<PathBuf>) -> Result<()> {
        // Find manifest file
        let manifest_path = if let Ok(path) = find_manifest_with_optional(manifest_path) {
            path
        } else {
            // Check if legacy CCPM files exist and offer interactive migration
            match crate::cli::common::handle_legacy_ccpm_migration(None, self.yes).await {
                Ok(Some(path)) => path,
                Ok(None) => {
                    return Err(anyhow::anyhow!(
                        "No agpm.toml found in current directory or any parent directory.\n\n\
                        To get started, create a agpm.toml file with your dependencies:\n\n\
                        [sources]\n\
                        official = \"https://github.com/example-org/agpm-official.git\"\n\n\
                        [agents]\n\
                        my-agent = {{ source = \"official\", path = \"agents/my-agent.md\", version = \"v1.0.0\" }}"
                    ));
                }
                Err(e) => return Err(e),
            }
        };

        self.execute_from_path(Some(&manifest_path)).await
    }

    pub async fn execute_from_path(&self, path: Option<&Path>) -> Result<()> {
        use crate::installer::{ResourceFilter, install_resources};
        use crate::manifest::Manifest;
        use crate::utils::progress::{InstallationPhase, MultiPhaseProgress};
        use std::sync::Arc;

        let manifest_path = if let Some(p) = path {
            p.to_path_buf()
        } else {
            std::env::current_dir()?.join("agpm.toml")
        };

        if !manifest_path.exists() {
            return Err(anyhow::anyhow!("No agpm.toml found at {}", manifest_path.display()));
        }

        let (mut manifest, _patch_conflicts) = Manifest::load_with_private(&manifest_path)?;

        // Note: Private patches silently override project patches when they conflict.
        // This allows users to customize their local configuration without modifying
        // the team-wide project configuration.

        // Create command context for using enhanced lockfile loading
        let project_dir = manifest_path.parent().unwrap_or_else(|| Path::new("."));
        let mut command_context =
            crate::cli::common::CommandContext::new(manifest.clone(), project_dir.to_path_buf())?;

        // In --frozen mode, check for corruption and security issues only
        let lockfile_path = project_dir.join("agpm.lock");

        if self.frozen && lockfile_path.exists() {
            // In frozen mode, we should NOT regenerate - fail hard if lockfile is invalid
            match LockFile::load(&lockfile_path) {
                Ok(lockfile) => {
                    if let Some(reason) = lockfile.validate_against_manifest(&manifest, false)? {
                        return Err(anyhow::anyhow!(
                            "Lockfile has critical issues in --frozen mode:\n\n\
                             {reason}\n\n\
                             Hint: Fix the issue or remove --frozen flag."
                        ));
                    }
                }
                Err(e) => {
                    // In frozen mode, provide enhanced error message with beta notice
                    return Err(anyhow::anyhow!(
                        "Cannot proceed in --frozen mode due to invalid lockfile.\n\n\
                         Error: {}\n\n\
                         In --frozen mode, the lockfile must be valid.\n\
                         Fix the lockfile manually or remove the --frozen flag to allow regeneration.\n\n\
                         Note: The lockfile format is not yet stable as this is beta software.",
                        e
                    ));
                }
            }
        }
        let total_deps = manifest.all_dependencies().len();

        // Initialize multi-phase progress for all progress tracking
        let multi_phase = Arc::new(MultiPhaseProgress::new(!self.quiet && !self.no_progress));

        // Show initial status

        let actual_project_dir =
            manifest_path.parent().ok_or_else(|| anyhow::anyhow!("Invalid manifest path"))?;

        // Check for existing lockfile
        let lockfile_path = actual_project_dir.join("agpm.lock");

        // Use enhanced lockfile loading with automatic regeneration for non-frozen mode
        let existing_lockfile = if !self.frozen {
            command_context.load_lockfile_with_regeneration(true, "install")?
        } else {
            // In frozen mode, use the original loading logic (already validated above)
            if lockfile_path.exists() {
                let mut lockfile = LockFile::load(&lockfile_path)?;
                // Also load and merge private lockfile if it exists
                if let Ok(Some(private_lock)) =
                    crate::lockfile::PrivateLockFile::load(actual_project_dir)
                {
                    lockfile.merge_private(&private_lock);
                }
                Some(lockfile)
            } else {
                None
            }
        };

        // Check for legacy format migration (old paths → agpm/ subdirectory)
        // Only check if we have an existing lockfile (indicates prior installation)
        let existing_lockfile = if existing_lockfile.is_some() && !self.frozen {
            let migrated =
                crate::cli::common::handle_legacy_format_migration(actual_project_dir, self.yes)
                    .await?;
            if migrated {
                // Reload manifest after migration since tools config may have changed
                command_context.reload_manifest()?;
                // Update local manifest variable to use reloaded manifest
                manifest = command_context.manifest.clone();
                // Reload lockfile after migration since paths have changed
                command_context.load_lockfile_with_regeneration(true, "install")?
            } else {
                existing_lockfile
            }
        } else {
            existing_lockfile
        };

        // Initialize cache (always needed now, even with --no-cache)
        let cache = Cache::new()?;

        // Calculate max concurrency (used for both resolution and installation)
        let max_concurrency = self.max_parallel.unwrap_or_else(|| {
            let cores = std::thread::available_parallelism()
                .map(std::num::NonZero::get)
                .unwrap_or(FALLBACK_CORE_COUNT);
            std::cmp::max(MIN_PARALLELISM, cores * PARALLELISM_CORE_MULTIPLIER)
        });

        // Create operation context for warning deduplication
        let operation_context = Arc::new(OperationContext::new());

        // Resolution phase
        let mut resolver = DependencyResolver::new_with_global_concurrency(
            manifest.clone(),
            cache.clone(),
            Some(max_concurrency),
            Some(operation_context.clone()),
        )
        .await?;

        // Pre-sync sources phase (if not frozen and we have remote deps)
        let has_remote_deps =
            manifest.all_dependencies().iter().any(|(_, dep)| dep.get_source().is_some());

        // Fast path detection: check if we can skip resolution entirely
        let current_manifest_hash = manifest.compute_dependency_hash();
        let has_mutable = manifest.has_mutable_dependencies();

        let use_fast_path = can_use_fast_path(
            existing_lockfile.as_ref(),
            &current_manifest_hash,
            has_mutable,
            self.frozen,
        );

        // Skip pre-sync if using fast path (worktrees already exist from previous install)
        if !self.frozen && has_remote_deps && !use_fast_path {
            // Get all dependencies for pre-syncing (filtering out disabled tools)
            let deps: Vec<(String, ResourceDependency)> = manifest
                .all_dependencies_with_types()
                .into_iter()
                .map(|(name, dep, _resource_type)| (name.to_string(), dep.into_owned()))
                .collect();

            // Pre-sync all required sources (performs actual Git operations)
            // Progress tracking for "Syncing sources" phase is handled internally with windowed display
            let progress = if !self.quiet && !self.no_progress {
                Some(multi_phase.clone())
            } else {
                None
            };
            resolver.pre_sync_sources(&deps, progress).await?;
        } else if use_fast_path && !self.quiet && !self.no_progress {
            // Skip syncing phase entirely for fast path
            multi_phase.start_phase(InstallationPhase::SyncingSources, None);
            multi_phase.complete_phase(Some("Sources up to date"));
        }

        let mut lockfile = if let Some(existing) = existing_lockfile {
            if self.frozen {
                // Use existing lockfile as-is
                if !self.quiet {
                    println!("✓ Using frozen lockfile ({total_deps} dependencies)");
                }
                existing
            } else if use_fast_path {
                // Fast path: manifest unchanged with immutable deps - skip resolution entirely
                tracing::info!(
                    "Fast path: manifest unchanged with immutable deps, using cached lockfile"
                );
                if !self.quiet && !self.no_progress {
                    multi_phase.start_phase(
                        InstallationPhase::ResolvingDependencies,
                        Some(&format!("({total_deps} dependencies)")),
                    );
                    multi_phase
                        .complete_phase(Some(&format!("Resolved {total_deps} dependencies")));
                }
                existing
            } else {
                // Update lockfile with any new dependencies
                let progress = if !self.quiet && !self.no_progress {
                    Some(multi_phase.clone())
                } else {
                    None
                };
                resolver.update(&existing, None, progress).await?
            }
        } else {
            // Fresh resolution with windowed progress tracking
            let progress = if !self.quiet && !self.no_progress {
                Some(multi_phase.clone())
            } else {
                None
            };
            resolver.resolve_with_options(!self.no_transitive, progress).await?
        };

        // Store fast-path metadata in lockfile for next run's detection
        lockfile.manifest_hash = Some(current_manifest_hash);
        lockfile.has_mutable_deps = Some(has_mutable);
        lockfile.resource_count = Some(lockfile.all_resources().len());

        // Check for tag movement if we have both old and new lockfiles (skip in frozen mode)
        let old_lockfile = if !self.frozen && lockfile_path.exists() {
            // Load the old lockfile for comparison
            if let Ok(old) = LockFile::load(&lockfile_path) {
                detect_tag_movement(&old, &lockfile, self.quiet);
                Some(old)
            } else {
                None
            }
        } else {
            None
        };

        // Handle dry-run mode: show what would be installed without making changes
        if self.dry_run {
            return crate::cli::common::display_dry_run_results(
                &lockfile,
                old_lockfile.as_ref(),
                self.quiet,
            );
        }

        // Acquire resource lock for cross-process coordination during file writes
        // Resolution has completed above (outside lock), now we serialize file operations
        let _resource_lock =
            crate::installer::ProjectLock::acquire(actual_project_dir, "resource").await?;

        let total_resources = ResourceIterator::count_total_resources(&lockfile);

        // Track installation error to return later
        let mut installation_error = None;

        // Track counts for finalizing phase
        let mut hook_count = 0;
        let mut server_count = 0;

        // Ultra-fast path: If we can use fast path AND all installed files exist,
        // skip the entire installation phase (don't even iterate through resources)
        //
        // Note: There's a TOCTOU (time-of-check-to-time-of-use) race here where files
        // could be deleted between this check and actual use. This is accepted as low
        // risk since user-initiated deletion during install is rare, and the worst case
        // is that a subsequent tool invocation fails to find the file (easily fixed by
        // running `agpm install` again).
        let all_files_exist = use_fast_path
            && lockfile.all_resources().iter().all(|res| {
                // Only check files that should be installed (install != false)
                if res.install == Some(false) {
                    return true; // Content-only deps don't need file check
                }
                if res.installed_at.is_empty() {
                    return true; // No install path = nothing to check
                }
                actual_project_dir.join(&res.installed_at).exists()
            });

        let installed_count = if total_resources == 0 {
            0
        } else if all_files_exist {
            // Ultra-fast path: all files exist, skip installation entirely
            if !self.quiet && !self.no_progress {
                multi_phase.start_phase(
                    InstallationPhase::Installing,
                    Some(&format!("({total_resources} resources)")),
                );
                multi_phase.complete_phase(Some("All up to date"));
            }
            tracing::info!(
                "Ultra-fast path: all {} files exist, skipping installation",
                total_resources
            );
            0 // No files actually installed (they all exist)
        } else {
            // Start installation phase
            if !self.quiet && !self.no_progress {
                multi_phase.start_phase(
                    InstallationPhase::Installing,
                    Some(&format!("({total_resources} resources)")),
                );
            }

            // Install resources using the main installation function
            // (max_concurrency calculated earlier and used for both resolution and installation)
            // We need to wrap in Arc for the call, but we'll apply updates to the mutable version
            let lockfile_for_install = Arc::new(lockfile.clone());

            // Compute effective token warning threshold: manifest overrides global config
            let global_config = crate::config::GlobalConfig::load().await.unwrap_or_default();
            let token_warning_threshold =
                manifest.token_warning_threshold.unwrap_or(global_config.token_warning_threshold);

            match install_resources(
                ResourceFilter::All,
                &lockfile_for_install,
                &manifest,
                actual_project_dir,
                cache.clone(),
                self.no_cache,
                Some(max_concurrency),
                Some(multi_phase.clone()),
                self.verbose,
                old_lockfile.as_ref(), // Pass old lockfile for early-exit optimization
                use_fast_path,         // Trust lockfile checksums in fast path mode
                Some(token_warning_threshold),
            )
            .await
            {
                Ok(results) => {
                    // Apply installation results to lockfile
                    lockfile.apply_installation_results(
                        results.checksums,
                        results.context_checksums,
                        results.applied_patches,
                        results.token_counts,
                    );

                    results.installed_count
                }
                Err(e) => {
                    // Save the error to return immediately - don't continue with hooks/mcp/finalization
                    installation_error = Some(e);
                    0
                }
            }
        };

        // Only proceed with hooks, MCP, and finalization if installation succeeded
        if installation_error.is_none() {
            // Start finalizing phase
            if !self.quiet && !self.no_progress && installed_count > 0 {
                multi_phase.start_phase(InstallationPhase::Finalizing, None);
            }

            // Call shared finalization function
            let (hook_count_result, server_count_result) = crate::installer::finalize_installation(
                &mut lockfile,
                &manifest,
                actual_project_dir,
                &cache,
                old_lockfile.as_ref(),
                self.quiet,
                self.no_lock,
            )
            .await?;

            hook_count = hook_count_result;
            server_count = server_count_result;

            // Complete finalizing phase
            if !self.quiet && !self.no_progress && installed_count > 0 {
                multi_phase.complete_phase(Some("Installation finalized"));
            }
        }

        // Return the installation error if there was one
        if let Some(error) = installation_error {
            return Err(error);
        }

        // Validate project configuration and offer to add missing gitignore entries
        if !self.quiet && installed_count > 0 {
            let validation =
                crate::installer::validate_config(project_dir, &lockfile, manifest.gitignore).await;

            // Print any Claude settings warnings
            if let Some(warning) = &validation.claude_settings_warning {
                eprintln!("\n{}", warning);
            }

            // Handle missing gitignore entries interactively
            if !validation.missing_gitignore_entries.is_empty() {
                // Ignore errors - gitignore is a convenience feature
                let _ = crate::cli::common::handle_missing_gitignore_entries(
                    &validation,
                    project_dir,
                    self.yes,
                )
                .await;
            }
        }

        // Only show "no dependencies" message if nothing was installed AND no progress shown
        if self.no_progress
            && !self.quiet
            && installed_count == 0
            && hook_count == 0
            && server_count == 0
        {
            crate::cli::common::display_no_changes(
                crate::cli::common::OperationMode::Install,
                self.quiet,
            );
        }

        Ok(())
    }
}

/// Detects if any tags have moved between the old and new lockfiles.
///
/// Tags in Git are supposed to be immutable, so if a tag points to a different
/// commit than before, this is potentially problematic and worth warning about.
///
/// Branches are expected to move, so we don't warn about those.
fn detect_tag_movement(old_lockfile: &LockFile, new_lockfile: &LockFile, quiet: bool) {
    use crate::core::ResourceType;

    // Helper function to check if a version looks like a tag (not a branch or SHA)
    fn is_tag_like(version: &str) -> bool {
        // Skip if it looks like a SHA
        if version.len() >= 7 && version.chars().all(|c| c.is_ascii_hexdigit()) {
            return false;
        }

        // Skip if it's a known branch name
        if matches!(
            version,
            "main" | "master" | "develop" | "dev" | "staging" | "production" | "HEAD"
        ) || version.starts_with("release/")
            || version.starts_with("feature/")
            || version.starts_with("hotfix/")
            || version.starts_with("bugfix/")
        {
            return false;
        }

        // Likely a tag if it starts with 'v' or looks like a version
        version.starts_with('v')
            || version.starts_with("release-")
            || version.parse::<semver::Version>().is_ok()
            || version.contains('.') // Likely a version number
    }

    // Helper to check resources of a specific type
    fn check_resources(
        old_resources: &[crate::lockfile::LockedResource],
        new_resources: &[crate::lockfile::LockedResource],
        resource_type: ResourceType,
        quiet: bool,
    ) {
        for new_resource in new_resources {
            // Skip if no version or resolved commit
            let Some(ref new_version) = new_resource.version else {
                continue;
            };
            let Some(ref new_commit) = new_resource.resolved_commit else {
                continue;
            };

            // Skip if not a tag
            if !is_tag_like(new_version) {
                continue;
            }

            // Find the corresponding old resource
            if let Some(old_resource) =
                old_resources.iter().find(|r| r.display_name() == new_resource.display_name())
                && let (Some(old_version), Some(old_commit)) =
                    (&old_resource.version, &old_resource.resolved_commit)
            {
                // Check if the same tag now points to a different commit
                if old_version == new_version && old_commit != new_commit && !quiet {
                    eprintln!(
                        "⚠️  Warning: Tag '{}' for {} '{}' has moved from {} to {}",
                        new_version,
                        resource_type,
                        new_resource.display_name(),
                        &old_commit[..8.min(old_commit.len())],
                        &new_commit[..8.min(new_commit.len())]
                    );
                    eprintln!(
                        "   Tags should be immutable. This may indicate the upstream repository force-pushed the tag."
                    );
                }
            }
        }
    }

    // Check all resource types
    check_resources(&old_lockfile.agents, &new_lockfile.agents, ResourceType::Agent, quiet);
    check_resources(&old_lockfile.snippets, &new_lockfile.snippets, ResourceType::Snippet, quiet);
    check_resources(&old_lockfile.commands, &new_lockfile.commands, ResourceType::Command, quiet);
    check_resources(&old_lockfile.scripts, &new_lockfile.scripts, ResourceType::Script, quiet);
    check_resources(&old_lockfile.hooks, &new_lockfile.hooks, ResourceType::Hook, quiet);
    check_resources(
        &old_lockfile.mcp_servers,
        &new_lockfile.mcp_servers,
        ResourceType::McpServer,
        quiet,
    );
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::lockfile::{LockFile, LockedResource};
    use crate::manifest::{DetailedDependency, Manifest, ResourceDependency};

    use std::fs;
    use tempfile::TempDir;

    #[tokio::test]
    async fn test_install_command_no_manifest() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");

        let cmd = InstallCommand::new();
        let result = cmd.execute_from_path(Some(&manifest_path)).await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("agpm.toml"));
        Ok(())
    }

    #[tokio::test]
    async fn test_install_with_empty_manifest() -> Result<()> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        Manifest::new().save(&manifest_path)?;

        let cmd = InstallCommand::new();
        cmd.execute_from_path(Some(&manifest_path)).await?;

        let lockfile_path = temp.path().join("agpm.lock");
        assert!(lockfile_path.exists());
        let lockfile = LockFile::load(&lockfile_path)?;
        assert!(lockfile.agents.is_empty());
        assert!(lockfile.snippets.is_empty());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_command_new_defaults() {
        let cmd = InstallCommand::new();
        assert!(!cmd.no_lock);
        assert!(!cmd.frozen);
        assert!(!cmd.no_cache);
        assert!(cmd.max_parallel.is_none());
        assert!(!cmd.quiet);
    }

    #[tokio::test]
    async fn test_install_respects_no_lock_flag() -> anyhow::Result<()> {
        let temp = TempDir::new().unwrap();
        let manifest_path = temp.path().join("agpm.toml");
        Manifest::new().save(&manifest_path).unwrap();

        let cmd = InstallCommand {
            no_lock: true,
            frozen: false,
            no_cache: false,
            max_parallel: None,
            quiet: false,
            no_progress: false,
            verbose: false,
            no_transitive: false,
            dry_run: false,
            yes: false,
        };

        cmd.execute_from_path(Some(&manifest_path)).await?;
        assert!(!temp.path().join("agpm.lock").exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_with_local_dependency() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let local_file = temp.path().join("local-agent.md");
        fs::write(
            &local_file,
            "# Local Agent
This is a test agent.",
        )?;

        let mut manifest = Manifest::new();
        manifest.agents.insert(
            "local-agent".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "local-agent.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let cmd = InstallCommand::new();
        cmd.execute_from_path(Some(&manifest_path)).await?;
        assert!(temp.path().join(".claude/agents/agpm/local-agent.md").exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_with_invalid_manifest_syntax() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        fs::write(&manifest_path, "[invalid toml")?;

        let cmd = InstallCommand::new();
        let err = cmd.execute_from_path(Some(temp.path())).await.unwrap_err();
        // The actual error will be about parsing the invalid TOML
        let err_str = err.to_string();
        assert!(
            err_str.contains("File operation failed")
                || err_str.contains("Failed reading file")
                || err_str.contains("Cannot read manifest")
                || err_str.contains("unclosed")
                || err_str.contains("parse")
                || err_str.contains("expected")
                || err_str.contains("invalid"),
            "Unexpected error message: {}",
            err_str
        );
        Ok(())
    }

    #[tokio::test]
    async fn test_install_uses_existing_lockfile_when_frozen() -> anyhow::Result<()> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let lockfile_path = temp.path().join("agpm.lock");

        let local_file = temp.path().join("test-agent.md");
        fs::write(
            &local_file,
            "# Test Agent
Body",
        )?;

        let mut manifest = Manifest::new();
        manifest.agents.insert(
            "test-agent".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "test-agent.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        LockFile {
            version: 1,
            sources: vec![],
            commands: vec![],
            agents: vec![LockedResource {
                name: "test-agent".into(),
                source: None,
                url: None,
                path: "test-agent.md".into(),
                version: None,
                resolved_commit: None,
                checksum: String::new(),
                installed_at: ".claude/agents/test-agent.md".into(),
                dependencies: vec![],
                resource_type: crate::core::ResourceType::Agent,
                tool: Some("claude-code".to_string()),
                manifest_alias: None,
                context_checksum: None,
                applied_patches: std::collections::BTreeMap::new(),
                install: None,
                variant_inputs: crate::resolver::lockfile_builder::VariantInputs::default(),
                is_private: false,
                approximate_token_count: None,
            }],
            snippets: vec![],
            mcp_servers: vec![],
            scripts: vec![],
            hooks: vec![],
            skills: vec![],
            manifest_hash: None,
            has_mutable_deps: None,
            resource_count: None,
        }
        .save(&lockfile_path)?;

        let cmd = InstallCommand {
            no_lock: false,
            frozen: true,
            no_cache: false,
            max_parallel: None,
            quiet: false,
            no_progress: false,
            verbose: false,
            no_transitive: false,
            dry_run: false,
            yes: false,
        };

        cmd.execute_from_path(Some(&manifest_path)).await?;
        assert!(temp.path().join(".claude/agents/test-agent.md").exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_errors_when_local_file_missing() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");

        let mut manifest = Manifest::new();
        manifest.agents.insert(
            "missing".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "missing.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let err = InstallCommand::new().execute_from_path(Some(&manifest_path)).await.unwrap_err();
        let err_string = err.to_string();
        // After converting warnings to errors, missing local files fail with resource fetch error
        assert!(
            err_string.contains("Failed to fetch resource")
                || err_string.contains("local file")
                || err_string.contains("Failed to install 1 resources:"),
            "Error should indicate resource fetch failure, got: {}",
            err_string
        );
        Ok(())
    }

    #[tokio::test]
    async fn test_install_single_resource_paths() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let snippet_file = temp.path().join("single-snippet.md");
        fs::write(
            &snippet_file,
            "# Snippet
Body",
        )?;

        let mut manifest = Manifest::new();
        manifest.snippets.insert(
            "single".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "single-snippet.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let cmd = InstallCommand::new();
        cmd.execute_from_path(Some(&manifest_path)).await?;

        let lockfile = LockFile::load(&temp.path().join("agpm.lock"))?;
        assert_eq!(lockfile.snippets.len(), 1);
        let installed_path = temp.path().join(&lockfile.snippets[0].installed_at);
        assert!(installed_path.exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_single_command_resource() -> anyhow::Result<()> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let command_file = temp.path().join("single-command.md");
        fs::write(
            &command_file,
            "# Command
Body",
        )?;

        let mut manifest = Manifest::new();
        manifest.commands.insert(
            "cmd".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "single-command.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let cmd = InstallCommand::new();
        cmd.execute_from_path(Some(&manifest_path)).await?;

        let lockfile = LockFile::load(&temp.path().join("agpm.lock"))?;
        assert_eq!(lockfile.commands.len(), 1);
        assert!(temp.path().join(&lockfile.commands[0].installed_at).exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_dry_run_mode() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let lockfile_path = temp.path().join("agpm.lock");
        let agent_file = temp.path().join("test-agent.md");

        // Create a local file for the agent
        fs::write(&agent_file, "# Test Agent\nBody")?;

        let mut manifest = Manifest::new();
        manifest.agents.insert(
            "test-agent".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "test-agent.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let cmd = InstallCommand {
            no_lock: false,
            frozen: false,
            no_cache: false,
            max_parallel: None,
            quiet: true, // Suppress output in test
            no_progress: true,
            verbose: false,
            no_transitive: false,
            dry_run: true,
            yes: false,
        };

        // In dry-run mode, this should return an error indicating changes would be made
        let result = cmd.execute_from_path(Some(&manifest_path)).await;

        // Should return an error because changes would be made
        assert!(result.is_err());
        let err_msg = result.unwrap_err().to_string();
        assert!(err_msg.contains("Dry-run detected changes"));

        // Lockfile should NOT be created in dry-run mode
        assert!(!lockfile_path.exists());
        // Resource should NOT be installed
        assert!(!temp.path().join(".claude/agents/test-agent.md").exists());
        Ok(())
    }

    #[tokio::test]
    async fn test_install_summary_with_mcp_servers() -> Result<(), anyhow::Error> {
        let temp = TempDir::new()?;
        let manifest_path = temp.path().join("agpm.toml");
        let agent_file = temp.path().join("summary-agent.md");
        fs::write(&agent_file, "# Agent\nBody")?;

        let mcp_dir = temp.path().join("mcp");
        fs::create_dir_all(&mcp_dir)?;
        fs::write(mcp_dir.join("test-mcp.json"), "{\"name\":\"test\"}")?;

        let mut manifest = Manifest::new();
        manifest.agents.insert(
            "summary".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "summary-agent.md".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.add_mcp_server(
            "test-mcp".into(),
            ResourceDependency::Detailed(Box::new(DetailedDependency {
                source: None,
                path: "mcp/test-mcp.json".into(),
                version: None,
                branch: None,
                rev: None,
                command: None,
                args: None,
                target: None,
                filename: None,
                dependencies: None,
                tool: Some("claude-code".to_string()),
                flatten: None,
                install: None,

                template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
            })),
        );
        manifest.save(&manifest_path)?;

        let cmd = InstallCommand::new();
        cmd.execute_from_path(Some(&manifest_path)).await?;
        Ok(())
    }
}