InstallHelper.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using Microsoft.PowerShell.PSResourceGet.UtilClasses;
using NuGet.Frameworks;
using NuGet.Protocol.Core.Types;
using NuGet.Versioning;
using System;
using System.Collections;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Diagnostics;
using System.Globalization;
using System.IO;
using System.IO.Compression;
using System.Linq;
using System.Management.Automation;
using System.Management.Automation.Language;
using System.Net;
using System.Runtime.InteropServices;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.PowerShell.PSResourceGet.Cmdlets
{
    /// <summary>
    /// Install helper class
    /// </summary>
    internal class InstallHelper
    {
        #region Members

        public const string PSDataFileExt = ".psd1";
        public const string PSScriptFileExt = ".ps1";
        private const string MsgRepositoryNotTrusted = "Untrusted repository";
        private const string MsgInstallUntrustedPackage = "You are installing the modules from an untrusted repository. If you trust this repository, change its Trusted value by running the Set-PSResourceRepository cmdlet. Are you sure you want to install the PSResource from '{0}'?";
        private const string ScriptPATHWarning = "The installation path for the script does not currently appear in the {0} path environment variable. To make the script discoverable, add the script installation path, {1}, to the environment PATH variable.";
        private CancellationToken _cancellationToken;
        private readonly PSCmdlet _cmdletPassedIn;
        private List<string> _pathsToInstallPkg;
        private VersionRange _versionRange;
        private NuGetVersion _nugetVersion;
        private VersionType _versionType;
        private string _versionString;
        private bool _prerelease;
        private bool _acceptLicense;
        private bool _quiet;
        private bool _reinstall;
        private bool _force;
        private bool _trustRepository;
        private bool _asNupkg;
        private bool _includeXml;
        private bool _noClobber;
        private bool _authenticodeCheck;
        private bool _savePkg;
        private string _runtimeIdentifier;
        private string _targetFramework;
        List<string> _pathsToSearch;
        List<string> _pkgNamesToInstall;
        private string _tmpPath;
        private NetworkCredential _networkCredential;
        private HashSet<string> _packagesOnMachine;
        private FindHelper _findHelper;

        #endregion

        #region Public Methods

        public InstallHelper(PSCmdlet cmdletPassedIn, NetworkCredential networkCredential)
        {
            CancellationTokenSource source = new();
            _cancellationToken = source.Token;
            _cmdletPassedIn = cmdletPassedIn;
            _networkCredential = networkCredential;

            _findHelper = new FindHelper(_cancellationToken, _cmdletPassedIn, _networkCredential);
        }

        /// <summary>
        /// This method calls is the starting point for install processes and is called by Install, Update and Save cmdlets.
        /// </summary>
        public IEnumerable<PSResourceInfo> BeginInstallPackages(
            string[] names,
            VersionRange versionRange,
            NuGetVersion nugetVersion,
            VersionType versionType,
            string versionString,
            bool prerelease,
            string[] repository,
            bool acceptLicense,
            bool quiet,
            bool reinstall,
            bool force,
            bool trustRepository,
            bool noClobber,
            bool asNupkg,
            bool includeXml,
            bool skipDependencyCheck,
            bool authenticodeCheck,
            bool savePkg,
            List<string> pathsToInstallPkg,
            ScopeType? scope,
            string tmpPath,
            HashSet<string> pkgsInstalled,
            string runtimeIdentifier = null,
            string targetFramework = null)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::BeginInstallPackages()");
            _cmdletPassedIn.WriteDebug(string.Format("Parameters passed in >>> Name: '{0}'; VersionRange: '{1}'; NuGetVersion: '{2}'; VersionType: '{3}'; Version: '{4}'; Prerelease: '{5}'; Repository: '{6}'; " +
                "AcceptLicense: '{7}'; Quiet: '{8}'; Reinstall: '{9}'; TrustRepository: '{10}'; NoClobber: '{11}'; AsNupkg: '{12}'; IncludeXml '{13}'; SavePackage '{14}'; TemporaryPath '{15}'; SkipDependencyCheck: '{16}'; " +
                "AuthenticodeCheck: '{17}'; PathsToInstallPkg: '{18}'; Scope '{19}'",
                string.Join(",", names),
                versionRange != null ? (versionRange.OriginalString != null ? versionRange.OriginalString : string.Empty) : string.Empty,
                nugetVersion != null ? nugetVersion.ToString() : string.Empty,
                versionType.ToString(),
                versionString != null ? versionString : String.Empty,
                prerelease.ToString(),
                repository != null ? string.Join(",", repository) : string.Empty,
                acceptLicense.ToString(),
                quiet.ToString(),
                reinstall.ToString(),
                trustRepository.ToString(),
                noClobber.ToString(),
                asNupkg.ToString(),
                includeXml.ToString(),
                savePkg.ToString(),
                tmpPath ?? string.Empty,
                skipDependencyCheck,
                authenticodeCheck,
                pathsToInstallPkg != null ? string.Join(",", pathsToInstallPkg) : string.Empty,
                scope?.ToString() ?? string.Empty));

            _versionRange = versionRange;
            _nugetVersion = nugetVersion;
            _versionType = versionType;
            _versionString = versionString ?? String.Empty;
            _prerelease = prerelease;
            _acceptLicense = acceptLicense || force;
            _authenticodeCheck = authenticodeCheck;
            _quiet = quiet;
            _reinstall = reinstall;
            _force = force;
            _trustRepository = trustRepository || force;
            _noClobber = noClobber;
            _asNupkg = asNupkg;
            _includeXml = includeXml;
            _savePkg = savePkg;
            _runtimeIdentifier = runtimeIdentifier;
            _targetFramework = targetFramework;
            _pathsToInstallPkg = pathsToInstallPkg;
            _tmpPath = tmpPath ?? Path.GetTempPath();

            if (_versionRange == VersionRange.All)
            {
                _versionType = VersionType.NoVersion;
            }

            // Create list of installation paths to search.
            _pathsToSearch = new List<string>();
            _pkgNamesToInstall = names.ToList();
            _packagesOnMachine = pkgsInstalled;

            // _pathsToInstallPkg will only contain the paths specified within the -Scope param (if applicable)
            // _pathsToSearch will contain all resource package subdirectories within _pathsToInstallPkg path locations
            // e.g.:
            // ./InstallPackagePath1/PackageA
            // ./InstallPackagePath1/PackageB
            // ./InstallPackagePath2/PackageC
            // ./InstallPackagePath3/PackageD
            foreach (var path in _pathsToInstallPkg)
            {
                _pathsToSearch.AddRange(Utils.GetSubDirectories(path));
            }

            // Go through the repositories and see which is the first repository to have the pkg version available
            List<PSResourceInfo> installedPkgs = ProcessRepositories(
                repository: repository,
                trustRepository: _trustRepository,
                skipDependencyCheck: skipDependencyCheck,
                scope: scope ?? ScopeType.CurrentUser);

            return installedPkgs;
        }

        #endregion

        #region Private methods

        /// <summary>
        /// This method calls iterates through repositories (by priority order) to search for the packages to install.
        /// It calls HTTP or NuGet API based install helper methods, according to repository type.
        /// </summary>
        private List<PSResourceInfo> ProcessRepositories(
            string[] repository,
            bool trustRepository,
            bool skipDependencyCheck,
            ScopeType scope)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::ProcessRepositories()");
            List<PSResourceInfo> allPkgsInstalled = new();
            if (repository != null && repository.Length != 0)
            {
                // Write error and disregard repository entries containing wildcards.
                repository = Utils.ProcessNameWildcards(repository, removeWildcardEntries: false, out string[] errorMsgs, out _);
                foreach (string error in errorMsgs)
                {
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                        new PSInvalidOperationException(error),
                        "ErrorFilteringNamesForUnsupportedWildcards",
                        ErrorCategory.InvalidArgument,
                        _cmdletPassedIn));
                }

                // If repository entries includes wildcards and non-wildcard names, write terminating error
                // Ex: -Repository *Gallery, localRepo
                bool containsWildcard = false;
                bool containsNonWildcard = false;
                foreach (string repoName in repository)
                {
                    if (repoName.Contains("*"))
                    {
                        containsWildcard = true;
                    }
                    else
                    {
                        containsNonWildcard = true;
                    }
                }

                if (containsNonWildcard && containsWildcard)
                {
                    _cmdletPassedIn.ThrowTerminatingError(new ErrorRecord(
                        new PSInvalidOperationException("Repository name with wildcard is not allowed when another repository without wildcard is specified."),
                        "RepositoryNamesWithWildcardsAndNonWildcardUnsupported",
                        ErrorCategory.InvalidArgument,
                        _cmdletPassedIn));
                }
            }

            // Get repositories to search.
            List<PSRepositoryInfo> repositoriesToSearch;
            try
            {
                repositoriesToSearch = RepositorySettings.Read(repository, out string[] errorList);
                if (repositoriesToSearch != null && repositoriesToSearch.Count == 0)
                {
                    _cmdletPassedIn.ThrowTerminatingError(new ErrorRecord(
                        new PSArgumentException("Cannot resolve -Repository name. Run 'Get-PSResourceRepository' to view all registered repositories."),
                        "RepositoryNameIsNotResolved",
                        ErrorCategory.InvalidArgument,
                        _cmdletPassedIn));
                }

                foreach (string error in errorList)
                {
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                        new PSInvalidOperationException(error),
                        "ErrorRetrievingSpecifiedRepository",
                        ErrorCategory.InvalidOperation,
                        _cmdletPassedIn));
                }
            }
            catch (Exception e)
            {
                _cmdletPassedIn.ThrowTerminatingError(new ErrorRecord(
                    new PSInvalidOperationException(e.Message),
                    "ErrorLoadingRepositoryStoreFile",
                    ErrorCategory.InvalidArgument,
                    _cmdletPassedIn));

                return allPkgsInstalled;
            }

            var listOfRepositories = RepositorySettings.Read(repository, out string[] _);
            var yesToAll = false;
            var noToAll = false;

            var findHelper = new FindHelper(_cancellationToken, _cmdletPassedIn, _networkCredential);
            List<string> repositoryNamesToSearch = new();
            bool sourceTrusted = false;

            // Loop through all the repositories provided (in priority order) until there no more packages to install.
            for (int i = 0; i < listOfRepositories.Count && _pkgNamesToInstall.Count > 0; i++)
            {
                PSRepositoryInfo currentRepository = listOfRepositories[i];

                bool isAllowed = GroupPolicyRepositoryEnforcement.IsRepositoryAllowed(currentRepository.Uri);

                if (!isAllowed)
                {
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                        new PSInvalidOperationException($"Repository '{currentRepository.Name}' is not allowed by Group Policy."),
                        "RepositoryNotAllowedByGroupPolicy",
                        ErrorCategory.PermissionDenied,
                        this));

                    continue;
                }

                string repoName = currentRepository.Name;
                sourceTrusted = currentRepository.Trusted || trustRepository;

                // Set network credentials via passed in credentials, AzArtifacts CredentialProvider, or SecretManagement.
                _networkCredential = currentRepository.SetNetworkCredentials(_networkCredential, _cmdletPassedIn);

                ServerApiCall currentServer = ServerFactory.GetServer(currentRepository, _cmdletPassedIn, _networkCredential);

                if (currentServer == null)
                {
                    // this indicates that PSRepositoryInfo.APIVersion = PSRepositoryInfo.APIVersion.unknown
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                        new PSInvalidOperationException($"Repository '{currentRepository.Name}' is not a known repository type that is supported. Please file an issue for support at https://github.com/PowerShell/PSResourceGet/issues"),
                        "RepositoryApiVersionUnknown",
                        ErrorCategory.InvalidArgument,
                        _cmdletPassedIn));

                    continue;
                }

                ResponseUtil currentResponseUtil = ResponseUtilFactory.GetResponseUtil(currentRepository);
                bool installDepsForRepo = skipDependencyCheck;

                // If no more packages to install, then return
                if (_pkgNamesToInstall.Count == 0)
                {
                    return allPkgsInstalled;
                }

                _cmdletPassedIn.WriteVerbose($"Attempting to search for packages in '{repoName}'");

                if (currentRepository.Trusted == false && !trustRepository && !_force)
                {
                    _cmdletPassedIn.WriteVerbose("Checking if untrusted repository should be used");

                    if (!(yesToAll || noToAll))
                    {
                        // Prompt for installation of package from untrusted repository
                        var message = string.Format(CultureInfo.InvariantCulture, MsgInstallUntrustedPackage, repoName);
                        sourceTrusted = _cmdletPassedIn.ShouldContinue(message, MsgRepositoryNotTrusted, true, ref yesToAll, ref noToAll);
                    }
                }

                if (!sourceTrusted && !yesToAll)
                {
                    continue;
                }

                repositoryNamesToSearch.Add(repoName);

                List<PSResourceInfo> installedPkgs = InstallPackages(_pkgNamesToInstall.ToArray(), currentRepository, currentServer, currentResponseUtil, scope, skipDependencyCheck, findHelper);
                foreach (PSResourceInfo pkg in installedPkgs)
                {
                    _pkgNamesToInstall.RemoveAll(x => x.Equals(pkg.Name, StringComparison.InvariantCultureIgnoreCase));
                }

                allPkgsInstalled.AddRange(installedPkgs);
            }

            if ((!_cmdletPassedIn.MyInvocation.BoundParameters.ContainsKey("WhatIf") || (SwitchParameter)_cmdletPassedIn.MyInvocation.BoundParameters["WhatIf"] == false) && _pkgNamesToInstall.Count > 0)
            {
                string repositoryWording = repositoryNamesToSearch.Count > 1 ? "registered repositories" : "repository";
                _cmdletPassedIn.WriteError(new ErrorRecord(
                    new ResourceNotFoundException($"Package(s) '{string.Join(", ", _pkgNamesToInstall)}' could not be installed from {repositoryWording} '{String.Join(", ", repositoryNamesToSearch)}'."),
                    "InstallPackageFailure",
                    ErrorCategory.InvalidData,
                    _cmdletPassedIn));
            }

            return allPkgsInstalled;
        }

        /// <summary>
        /// Deletes temp directory and is called at end of install process.
        /// </summary>
        private bool TryDeleteDirectory(
            string tempInstallPath,
            out ErrorRecord errorMsg)
        {
            errorMsg = null;

            try
            {
                Utils.DeleteDirectory(tempInstallPath);
            }
            catch (Exception e)
            {
                errorMsg = new ErrorRecord(
                    exception: e,
                    "errorDeletingTempInstallPath",
                    ErrorCategory.InvalidResult,
                    _cmdletPassedIn);

                return false;
            }

            return true;
        }

        /// <summary>
        /// Moves file from the temp install path to destination path for install.
        /// </summary>
        private void MoveFilesIntoInstallPath(
            PSResourceInfo pkgInfo,
            bool isModule,
            bool isLocalRepo,
            string dirNameVersion,
            string tempInstallPath,
            string installPath,
            string newVersion,
            string moduleManifestVersion,
            string scriptPath,
            bool mergeFilteredContent)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::MoveFilesIntoInstallPath()");
            // Creating the proper installation path depending on whether pkg is a module or script
            var newPathParent = isModule ? Path.Combine(installPath, pkgInfo.Name) : installPath;
            var finalModuleVersionDir = isModule ? Path.Combine(installPath, pkgInfo.Name, moduleManifestVersion) : installPath;

            // If script, just move the files over, if module, move the version directory over
            var tempModuleVersionDir = (!isModule || isLocalRepo) ? dirNameVersion
                : Path.Combine(tempInstallPath, pkgInfo.Name, newVersion);

            _cmdletPassedIn.WriteVerbose($"Installation source path is: '{tempModuleVersionDir}'");
            _cmdletPassedIn.WriteVerbose($"Installation destination path is: '{finalModuleVersionDir}'");

            if (isModule)
            {
                // If new path does not exist
                if (!Directory.Exists(newPathParent))
                {
                    _cmdletPassedIn.WriteVerbose($"Attempting to move '{tempModuleVersionDir}' to '{finalModuleVersionDir}'");
                    Directory.CreateDirectory(newPathParent);
                    Utils.MoveDirectory(tempModuleVersionDir, finalModuleVersionDir);
                }
                else if (mergeFilteredContent && Directory.Exists(finalModuleVersionDir))
                {
                    // Copy only new TFM/RID content into the existing install
                    _cmdletPassedIn.WriteVerbose($"Merging additional platform content from '{tempModuleVersionDir}' into '{finalModuleVersionDir}'");
                    Utils.MergeDirContents(tempModuleVersionDir, finalModuleVersionDir);
                    Utils.DeleteDirectory(tempModuleVersionDir);
                }
                else
                {
                    _cmdletPassedIn.WriteVerbose($"Temporary module version directory is: '{tempModuleVersionDir}'");

                    if (Directory.Exists(finalModuleVersionDir))
                    {
                        // Delete the directory path before replacing it with the new module.
                        // If deletion fails (usually due to binary file in use), then attempt restore so that the currently
                        // installed module is not corrupted.
                        _cmdletPassedIn.WriteVerbose($"Attempting to delete with restore on failure. '{finalModuleVersionDir}'");
                        Utils.DeleteDirectoryWithRestore(finalModuleVersionDir);
                    }

                    _cmdletPassedIn.WriteVerbose($"Attempting to move '{tempModuleVersionDir}' to '{finalModuleVersionDir}'");
                    Utils.MoveDirectory(tempModuleVersionDir, finalModuleVersionDir);
                }
            }
            else if (_asNupkg)
            {
                foreach (string file in Directory.GetFiles(tempInstallPath))
                {
                    string fileName = Path.GetFileName(file);
                    string newFileName = string.Equals(Path.GetExtension(file), ".zip", StringComparison.OrdinalIgnoreCase) ?
                        $"{Path.GetFileNameWithoutExtension(file)}.nupkg" : fileName;

                    Utils.MoveFiles(Path.Combine(tempInstallPath, fileName), Path.Combine(installPath, newFileName));
                }
            }
            else
            {
                string scriptInfoFolderPath = Path.Combine(installPath, "InstalledScriptInfos");
                string scriptXML = pkgInfo.Name + "_InstalledScriptInfo.xml";
                string scriptXmlFilePath = Path.Combine(scriptInfoFolderPath, scriptXML);
                if (!_savePkg)
                {
                    // Need to ensure "InstalledScriptInfos directory exists
                    if (!Directory.Exists(scriptInfoFolderPath))

                    {
                        _cmdletPassedIn.WriteVerbose($"Created '{scriptInfoFolderPath}' path for scripts");
                        Directory.CreateDirectory(scriptInfoFolderPath);
                    }

                    // Need to delete old xml files because there can only be 1 per script
                    _cmdletPassedIn.WriteVerbose(string.Format("Checking if path '{0}' exists: '{1}'", scriptXmlFilePath, File.Exists(scriptXmlFilePath)));
                    if (File.Exists(scriptXmlFilePath))
                    {
                        _cmdletPassedIn.WriteVerbose("Deleting script metadata XML");
                        File.Delete(Path.Combine(scriptInfoFolderPath, scriptXML));

                    }

                    _cmdletPassedIn.WriteVerbose(string.Format("Moving '{0}' to '{1}'", Path.Combine(dirNameVersion, scriptXML), Path.Combine(installPath, "InstalledScriptInfos", scriptXML)));
                    Utils.MoveFiles(Path.Combine(dirNameVersion, scriptXML), Path.Combine(installPath, "InstalledScriptInfos", scriptXML));

                    // Need to delete old script file, if that exists
                    _cmdletPassedIn.WriteVerbose(string.Format("Checking if path '{0}' exists: ", File.Exists(Path.Combine(finalModuleVersionDir, pkgInfo.Name + PSScriptFileExt))));
                    if (File.Exists(Path.Combine(finalModuleVersionDir, pkgInfo.Name + PSScriptFileExt)))
                    {
                        _cmdletPassedIn.WriteVerbose("Deleting script file");
                        File.Delete(Path.Combine(finalModuleVersionDir, pkgInfo.Name + PSScriptFileExt));
                    }
                }
                else
                {
                    if (_includeXml)
                    {
                        _cmdletPassedIn.WriteVerbose(string.Format("Moving '{0}' to '{1}'", Path.Combine(dirNameVersion, scriptXML), Path.Combine(installPath, scriptXML)));
                        Utils.MoveFiles(Path.Combine(dirNameVersion, scriptXML), Path.Combine(installPath, scriptXML));
                    }
                }

                _cmdletPassedIn.WriteVerbose(string.Format("Moving '{0}' to '{1}'", scriptPath, Path.Combine(finalModuleVersionDir, pkgInfo.Name + PSScriptFileExt)));
                Utils.MoveFiles(scriptPath, Path.Combine(finalModuleVersionDir, pkgInfo.Name + PSScriptFileExt));
            }
        }


        /// <summary>
        /// Iterates through package names passed in and calls method to install each package and their dependencies.
        /// </summary>
        private List<PSResourceInfo> InstallPackages(
            string[] pkgNamesToInstall,
            PSRepositoryInfo repository,
            ServerApiCall currentServer,
            ResponseUtil currentResponseUtil,
            ScopeType scope,
            bool skipDependencyCheck,
            FindHelper findHelper)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::InstallPackages()");

            List<PSResourceInfo> pkgsSuccessfullyInstalled = new();

            // ---------- Phase 1 (pipeline thread): resolve each parent package and evaluate ShouldProcess ----------
            // ShouldProcess / -WhatIf / -Confirm and Write* must run on the pipeline thread, so all gating happens
            // here, before any parallel download work begins. Packages that pass the gate become work items.
            List<ParentInstallWorkItem> workItems = new();
            foreach (var parentPackage in pkgNamesToInstall)
            {
                PSResourceInfo pkgToInstall = FindParentPackage(
                    searchVersionType: _versionType,
                    specificVersion: _nugetVersion,
                    versionRange: _versionRange,
                    pkgNameToInstall: parentPackage,
                    repository: repository,
                    currentServer: currentServer,
                    currentResponseUtil: currentResponseUtil,
                    pkgVersion: out string pkgVersion,
                    errRecord: out ErrorRecord findErrRecord);

                if (findErrRecord != null)
                {
                    if (findErrRecord.FullyQualifiedErrorId.Equals("PackageNotFound"))
                    {
                        _cmdletPassedIn.WriteVerbose(findErrRecord.Exception.Message);
                    }
                    else
                    {
                        _cmdletPassedIn.WriteError(findErrRecord);
                    }

                    continue;
                }

                if (pkgToInstall == null)
                {
                    continue;
                }

                bool mergeFilteredContent = false;

                // Check to see if the pkg is already installed (unless -Reinstall was specified).
                if (!_reinstall && _packagesOnMachine.Contains($"{pkgToInstall.Name}{pkgVersion}"))
                {
                    // When -TargetFramework or -RuntimeIdentifier is explicitly specified, allow re-download
                    // to merge the additional TFM/RID content into the existing install directory.
                    bool hasExplicitOverride = !string.IsNullOrEmpty(_targetFramework) || !string.IsNullOrEmpty(_runtimeIdentifier);
                    if (hasExplicitOverride)
                    {
                        _cmdletPassedIn.WriteVerbose($"Resource '{pkgToInstall.Name}' with version '{pkgVersion}' is already installed. " +
                            $"Proceeding to merge additional platform content (TargetFramework='{_targetFramework}', RuntimeIdentifier='{_runtimeIdentifier}').");
                        mergeFilteredContent = true;
                    }
                    else
                    {
                        _cmdletPassedIn.WriteWarning($"Resource '{pkgToInstall.Name}' with version '{pkgVersion}' is already installed.  If you would like to reinstall, please run the cmdlet again with the -Reinstall parameter");

                        // Remove from tracking list of packages to install.
                        _pkgNamesToInstall.RemoveAll(x => x.Equals(pkgToInstall.Name, StringComparison.InvariantCultureIgnoreCase));

                        continue;
                    }
                }

                // ShouldProcess gate (handles -WhatIf / -Confirm) on the pipeline thread.
                string shouldProcessTarget = _savePkg
                    ? $"Package to save: '{pkgToInstall.Name}', version: '{pkgVersion}'"
                    : $"Package to install: '{pkgToInstall.Name}', version: '{pkgVersion}'";
                if (!_cmdletPassedIn.ShouldProcess(shouldProcessTarget))
                {
                    continue;
                }

                workItems.Add(new ParentInstallWorkItem
                {
                    PkgToInstall = pkgToInstall,
                    PkgVersion = pkgVersion,
                    TempInstallPath = CreateInstallationTempPath(),
                    MergeFilteredContent = mergeFilteredContent
                });
            }

            if (workItems.Count == 0)
            {
                return pkgsSuccessfullyInstalled;
            }

            // ---------- Phase 2 (parallel): download each parent + its dependencies to its own temp path ----------
            // This is network-bound work. No pipeline-thread calls are made here; all host messages are queued
            // per work item and drained in Phase 3. Each work item downloads into its own temp path and its own
            // packagesHash, so there is no shared mutable state between parents.
            int processorCount = Environment.ProcessorCount;
            if (workItems.Count > 1)
            {
                int maxDegreeOfParallelism = processorCount * 4;
                Parallel.ForEach(workItems, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism }, workItem =>
                {
                    workItem.PackagesHash = DownloadParentAndDeps(
                        workItem.PkgToInstall, workItem.PkgVersion, workItem.TempInstallPath, repository,
                        currentServer, currentResponseUtil, skipDependencyCheck,
                        workItem.ErrorMsgs, workItem.WarningMsgs, workItem.DebugMsgs, workItem.VerboseMsgs,
                        out bool succeeded);
                    workItem.Succeeded = succeeded;
                });
            }
            else
            {
                ParentInstallWorkItem workItem = workItems[0];
                workItem.PackagesHash = DownloadParentAndDeps(
                    workItem.PkgToInstall, workItem.PkgVersion, workItem.TempInstallPath, repository,
                    currentServer, currentResponseUtil, skipDependencyCheck,
                    workItem.ErrorMsgs, workItem.WarningMsgs, workItem.DebugMsgs, workItem.VerboseMsgs,
                    out bool succeeded);
                workItem.Succeeded = succeeded;
            }

            // ---------- Phase 3 (pipeline thread): drain messages, move content to final location, record results ----------
            // If a single dependency fails to install, roll back that parent by deleting its temp directory.
            foreach (ParentInstallWorkItem workItem in workItems)
            {
                try
                {
                    Utils.WriteOutConcurrentQueue(_cmdletPassedIn, workItem.ErrorMsgs, workItem.WarningMsgs, workItem.DebugMsgs, workItem.VerboseMsgs);

                    if (!workItem.Succeeded || workItem.PackagesHash == null || workItem.PackagesHash.Count == 0)
                    {
                        continue;
                    }

                    // Parent package and dependencies are now installed to temp directory.
                    // Try to move all package directories from temp directory to final destination.
                    if (!TryMoveInstallContent(
                        workItem.TempInstallPath,
                        scope,
                        workItem.PackagesHash,
                        workItem.MergeFilteredContent))
                    {
                        _cmdletPassedIn.WriteError(new ErrorRecord(
                            new InvalidOperationException(),
                            "InstallPackageTryMoveContentFailure",
                            ErrorCategory.InvalidOperation,
                            _cmdletPassedIn));
                    }
                    else
                    {
                        foreach (string pkgName in workItem.PackagesHash.Keys)
                        {
                            Hashtable pkgInfo = workItem.PackagesHash[pkgName] as Hashtable;
                            pkgsSuccessfullyInstalled.Add(pkgInfo["psResourceInfoPkg"] as PSResourceInfo);

                            // Add each pkg to _packagesOnMachine (ie pkgs fully installed on the machine).
                            _packagesOnMachine.Add($"{pkgName}{pkgInfo["pkgVersion"]}");
                        }
                    }
                }
                catch (Exception e)
                {
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                            e,
                            "InstallPackageFailure",
                            ErrorCategory.InvalidOperation,
                            _cmdletPassedIn));

                    throw;
                }
                finally
                {
                    DeleteInstallationTempPath(workItem.TempInstallPath);
                }
            }

            return pkgsSuccessfullyInstalled;
        }

        /// <summary>
        /// Tracks the per-parent state used to parallelize parent-package installation across the three phases.
        /// Each parent has its own temp path, result hash, and message queues so there is no shared mutable state
        /// during the parallel download phase.
        /// </summary>
        private sealed class ParentInstallWorkItem
        {
            public PSResourceInfo PkgToInstall;
            public string PkgVersion;
            public string TempInstallPath;
            public ConcurrentDictionary<string, Hashtable> PackagesHash;
            public bool Succeeded;
            public bool MergeFilteredContent;
            public readonly ConcurrentQueue<ErrorRecord> ErrorMsgs = new();
            public readonly ConcurrentQueue<string> WarningMsgs = new();
            public readonly ConcurrentQueue<string> DebugMsgs = new();
            public readonly ConcurrentQueue<string> VerboseMsgs = new();
        }

        /// <summary>
        /// Resolves the parent package to install (find + version selection). Must run on the pipeline thread.
        /// </summary>
        private PSResourceInfo FindParentPackage(
            VersionType searchVersionType,
            NuGetVersion specificVersion,
            VersionRange versionRange,
            string pkgNameToInstall,
            PSRepositoryInfo repository,
            ServerApiCall currentServer,
            ResponseUtil currentResponseUtil,
            out string pkgVersion,
            out ErrorRecord errRecord)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::FindParentPackage()");
            FindResults responses = null;
            pkgVersion = null;
            errRecord = null;

            // Find the parent package that needs to be installed
            switch (searchVersionType)
            {
                case VersionType.VersionRange:
                    responses = currentServer.FindVersionGlobbing(pkgNameToInstall, versionRange, _prerelease, ResourceType.None, getOnlyLatest: true, out ErrorRecord findVersionGlobbingErrRecord);
                    // Server level globbing API will not populate errRecord for empty response, so must check for empty response and early out
                    if (findVersionGlobbingErrRecord != null || responses.IsFindResultsEmpty())
                    {
                        errRecord = findVersionGlobbingErrRecord;
                        return null;
                    }

                    break;

                case VersionType.SpecificVersion:
                    string nugetVersionString = specificVersion.ToNormalizedString(); // 3.0.17-beta

                    responses = currentServer.FindVersion(pkgNameToInstall, nugetVersionString, ResourceType.None, out ErrorRecord findVersionErrRecord);
                    if (findVersionErrRecord != null)
                    {
                        errRecord = findVersionErrRecord;
                        return null;
                    }

                    break;

                default:
                    // VersionType.NoVersion
                    responses = currentServer.FindName(pkgNameToInstall, _prerelease, ResourceType.None, out ErrorRecord findNameErrRecord);
                    if (findNameErrRecord != null)
                    {
                        errRecord = findNameErrRecord;
                        return null;
                    }

                    break;
            }

            // Convert parent package to PSResourceInfo
            PSResourceInfo pkgToInstall = null;
            foreach (PSResourceResult currentResult in currentResponseUtil.ConvertToPSResourceResult(responses))
            {
                if (currentResult.exception != null && !currentResult.exception.Message.Equals(string.Empty))
                {
                    errRecord = new ErrorRecord(
                        currentResult.exception,
                        "FindConvertToPSResourceFailure",
                        ErrorCategory.ObjectNotFound,
                        _cmdletPassedIn);
                }
                else if (searchVersionType == VersionType.VersionRange)
                {
                    // Check to see if version falls within version range
                    PSResourceInfo foundPkg = currentResult.returnedObject;
                    string versionStr = $"{foundPkg.Version}";
                    if (foundPkg.IsPrerelease)
                    {
                        versionStr += $"-{foundPkg.Prerelease}";
                    }

                    if (NuGetVersion.TryParse(versionStr, out NuGetVersion version)
                           && _versionRange.Satisfies(version))
                    {
                        pkgToInstall = foundPkg;

                        break;
                    }
                }
                else
                {
                    pkgToInstall = currentResult.returnedObject;

                    break;
                }
            }

            if (pkgToInstall == null)
            {
                return null;
            }

            pkgToInstall.RepositorySourceLocation = repository.Uri.ToString();
            pkgToInstall.AdditionalMetadata.TryGetValue("NormalizedVersion", out pkgVersion);
            if (pkgVersion == null)
            {
                // Not all NuGet providers (e.g. Artifactory, possibly others) send NormalizedVersion in NuGet package responses.
                // If they don't, we need to manually construct the combined version+prerelease from pkgToInstall.Version and the prerelease string.
                pkgVersion = pkgToInstall.Version.ToString();
                if (!String.IsNullOrEmpty(pkgToInstall.Prerelease))
                {
                    pkgVersion += $"-{pkgToInstall.Prerelease}";
                }
            }

            // For most repositories/providers the server will use the normalized version, which pkgVersion originally reflects
            // However, for container registries the version must exactly match what was in the artifact manifest and then reflected in PSResourceInfo.Version.ToString()
            if (currentServer.Repository.ApiVersion == PSRepositoryInfo.APIVersion.ContainerRegistry)
            {
                pkgVersion = String.IsNullOrEmpty(pkgToInstall.Prerelease) ? pkgToInstall.Version.ToString() : $"{pkgToInstall.Version.ToString()}-{pkgToInstall.Prerelease}";
            }
            
            // Check to see if the pkg is already installed (ie the pkg is installed and the version satisfies the version range provided via param)
            // Note: the already-installed check and ShouldProcess gate are handled by the caller on the pipeline thread.
            return pkgToInstall;
        }

        /// <summary>
        /// Downloads the parent package and its dependencies to the temporary path. Safe to run on worker threads:
        /// all host messages are routed to the provided queues and drained by the caller on the pipeline thread.
        /// </summary>
        private ConcurrentDictionary<string, Hashtable> DownloadParentAndDeps(
            PSResourceInfo pkgToInstall,
            string pkgVersion,
            string tempInstallPath,
            PSRepositoryInfo repository,
            ServerApiCall currentServer,
            ResponseUtil currentResponseUtil,
            bool skipDependencyCheck,
            ConcurrentQueue<ErrorRecord> errorMsgs,
            ConcurrentQueue<string> warningMsgs,
            ConcurrentQueue<string> debugMsgs,
            ConcurrentQueue<string> verboseMsgs,
            out bool success)
        {
            debugMsgs.Enqueue("In InstallHelper::DownloadParentAndDeps()");
            ConcurrentDictionary<string, Hashtable> packagesHash = new ConcurrentDictionary<string, Hashtable>(StringComparer.InvariantCultureIgnoreCase);

            List<PSResourceInfo> parentAndDeps = new List<PSResourceInfo>();
            if (!skipDependencyCheck)
            {
                // List returned only includes dependencies, so we'll add the parent pkg to this list to pass on to installation method.
                parentAndDeps.AddRange(_findHelper.FindDependencyPackages(currentServer, currentResponseUtil, pkgToInstall, repository, errorMsgs, warningMsgs, debugMsgs, verboseMsgs));
                debugMsgs.Enqueue("In InstallHelper::DownloadParentAndDeps(), found all dependencies");
            }

            parentAndDeps.Add(pkgToInstall);

            ConcurrentDictionary<string, Hashtable> updatedPackagesHash = InstallParentAndDependencyPackages(
                parentAndDeps, currentServer, tempInstallPath, packagesHash, packagesHash, pkgToInstall,
                errorMsgs, warningMsgs, debugMsgs, verboseMsgs);

            success = errorMsgs.IsEmpty;
            return updatedPackagesHash;
        }

        private ConcurrentDictionary<string, Hashtable> InstallParentAndDependencyPackages(
            List<PSResourceInfo> parentAndDeps,
            ServerApiCall currentServer,
            string tempInstallPath,
            ConcurrentDictionary<string, Hashtable> packagesHash,
            ConcurrentDictionary<string, Hashtable> updatedPackagesHash,
            PSResourceInfo pkgToInstall,
            ConcurrentQueue<ErrorRecord> errorMsgs,
            ConcurrentQueue<string> warningMsgs,
            ConcurrentQueue<string> debugMsgs,
            ConcurrentQueue<string> verboseMsgs)
        {
            // TODO: figure out a good threshold and parallel count
            int processorCount = Environment.ProcessorCount;
            debugMsgs.Enqueue($"parentAndDeps.Count is {parentAndDeps.Count}, processor count is: {processorCount}");
            if (parentAndDeps.Count > processorCount)
            {
                 debugMsgs.Enqueue($"parentAndDeps.Count is greater than processor count");
                // Set the maximum degree of parallelism to 32? (Invoke-Command has default of 32, that's where we got this number from)
                // If installing more than 3 packages, do so concurrently
                // If the number of dependencies is very small (e.g., ≤ CPU cores), parallelism may add overhead instead of improving speed.
                int maxDegreeOfParallelism = processorCount * 4;
                Parallel.ForEach(parentAndDeps, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism }, depPkg =>
                {
                    var depPkgName = depPkg.Name;
                    var depPkgVersion = depPkg.Version.ToString();

                    verboseMsgs.Enqueue($"Installing package '{depPkgName}' version '{depPkgVersion}'");
                    //Stream responseStream = currentServer.InstallPackage(depPkgName, depPkgVersion, true, out ErrorRecord installNameErrRecord);
                    // add async
                    Stream responseStream = currentServer.InstallPackageAsync(depPkgName, depPkgVersion, true, errorMsgs, warningMsgs, debugMsgs, verboseMsgs).GetAwaiter().GetResult();

                    if (!errorMsgs.IsEmpty)
                    {
                        verboseMsgs.Enqueue($"Error installing package '{depPkgName}'");
                    }
                    else {
                        ErrorRecord tempSaveErrRecord = null, tempInstallErrRecord = null;
                        bool installedToTempPathSuccessfully = _asNupkg ? TrySaveNupkgToTempPath(responseStream, tempInstallPath, depPkgName, depPkgVersion, depPkg, packagesHash, out updatedPackagesHash, errorMsgs, warningMsgs, debugMsgs, verboseMsgs) :
                            TryInstallToTempPath(responseStream, tempInstallPath, depPkgName, depPkgVersion, depPkg, packagesHash, out updatedPackagesHash, errorMsgs, warningMsgs, debugMsgs, verboseMsgs);

                        if (!installedToTempPathSuccessfully)
                        {
                            verboseMsgs.Enqueue($"Failed to install '{depPkgName}' to temp path");
                            Utils.EnqueueIfNotNull(errorMsgs, (tempSaveErrRecord ?? tempInstallErrRecord));
                        }
                        else
                        {
                            verboseMsgs.Enqueue($"Successfully installed '{depPkgName}' version '{depPkgVersion}' to temp path");
                        }
                    }
                });

                if (!errorMsgs.IsEmpty)
                {
                    return packagesHash;
                }
                
                return updatedPackagesHash;
            }
            else
            {
                // Install the good old fashioned way
                foreach (var pkgToBeInstalled in parentAndDeps)
                {
                    var pkgToInstallName = pkgToBeInstalled.Name;
                    var pkgToInstallVersion = Utils.GetFullVersionString(pkgToBeInstalled.Version.ToString(), pkgToBeInstalled.Prerelease);
                    // Runs on worker threads when parent installs are parallelized; use the async overload to avoid cross-thread cmdlet stream writes.
                    Stream responseStream = currentServer.InstallPackageAsync(pkgToInstallName, pkgToInstallVersion, true, errorMsgs, warningMsgs, debugMsgs, verboseMsgs).GetAwaiter().GetResult();

                    if (!errorMsgs.IsEmpty)
                    {
                        return packagesHash;
                    }

                    bool installedToTempPathSuccessfully = _asNupkg ? TrySaveNupkgToTempPath(responseStream, tempInstallPath, pkgToInstallName, pkgToInstallVersion, pkgToBeInstalled, packagesHash, out updatedPackagesHash, errorMsgs, warningMsgs, debugMsgs, verboseMsgs) :
                        TryInstallToTempPath(responseStream, tempInstallPath, pkgToInstallName, pkgToInstallVersion, pkgToBeInstalled, packagesHash, out updatedPackagesHash, errorMsgs, warningMsgs, debugMsgs, verboseMsgs);

                    if (!installedToTempPathSuccessfully)
                    {
                        return packagesHash;
                    }
                }

                return updatedPackagesHash;
            }
        }

        /// <summary>
        /// Creates a temporary path used for installation before moving package to its final location.
        /// </summary>
        private string CreateInstallationTempPath()
        {
            var tempInstallPath = Path.Combine(_tmpPath, Guid.NewGuid().ToString());

            try
            {
                var dir = Directory.CreateDirectory(tempInstallPath);  // should check it gets created properly
                                                                       // To delete file attributes from the existing ones get the current file attributes first and use AND (&) operator
                                                                       // with a mask (bitwise complement of desired attributes combination).
                                                                       // TODO: check the attributes and if it's read only then set it
                                                                       // attribute may be inherited from the parent
                                                                       // TODO:  are there Linux accommodations we need to consider here?
                dir.Attributes &= ~FileAttributes.ReadOnly;
            }
            catch (Exception e)
            {
                // catch more specific exception first
                _cmdletPassedIn.ThrowTerminatingError(new ErrorRecord(
                    new ArgumentException($"Temporary folder for installation could not be created or set due to: {e.Message}"),
                    "TempFolderCreationError",
                    ErrorCategory.InvalidOperation,
                    _cmdletPassedIn));
            }

            return tempInstallPath;
        }

        /// <summary>
        /// Deletes the temporary path used for intermediary installation.
        /// </summary>
        private void DeleteInstallationTempPath(string tempInstallPath)
        {
            if (Directory.Exists(tempInstallPath))
            {
                // Delete the temp directory and all its contents
                _cmdletPassedIn.WriteVerbose($"Attempting to delete '{tempInstallPath}'");
                if (!TryDeleteDirectory(tempInstallPath, out ErrorRecord errorMsg))
                {
                    _cmdletPassedIn.WriteError(errorMsg);
                }
                else
                {
                    _cmdletPassedIn.WriteVerbose($"Successfully deleted '{tempInstallPath}'");
                }
            }
        }

        /// <summary>
        /// Attempts to take installed HTTP response content and move it into a temporary install path on the machine.
        /// </summary>
        private bool TryInstallToTempPath(
            Stream responseStream,
            string tempInstallPath,
            string pkgName,
            string normalizedPkgVersion,
            PSResourceInfo pkgToInstall,
            ConcurrentDictionary<string, Hashtable> packagesHash,
            out ConcurrentDictionary<string, Hashtable> updatedPackagesHash,
            ConcurrentQueue<ErrorRecord> errorMsgs,
            ConcurrentQueue<string> warningMsgs,
            ConcurrentQueue<string> debugMsgs,
            ConcurrentQueue<string> verboseMsgs)
        {
            updatedPackagesHash = packagesHash;
            try
            {
                var pathToFile = Path.Combine(tempInstallPath, $"{pkgName}.{normalizedPkgVersion}.zip");
                using var fs = File.Create(pathToFile);
                if (responseStream == null)
                {
                    errorMsgs.Enqueue(new ErrorRecord(
                            new ArgumentNullException("Response stream is null."),
                            "NullResponseError",
                            ErrorCategory.InvalidResult,
                            _cmdletPassedIn));

                            return false;
                }
                responseStream.Seek(0, System.IO.SeekOrigin.Begin);
                responseStream.CopyTo(fs);
                fs.Close();

                // Expand the zip file
                var pkgVersion = pkgToInstall.Version.ToString();
                var tempDirNameVersion = Path.Combine(tempInstallPath, pkgName, pkgVersion);
                Directory.CreateDirectory(tempDirNameVersion);

                if (!TryExtractToDirectory(pathToFile, tempDirNameVersion, out ErrorRecord error))
                {
                    Utils.EnqueueIfNotNull(errorMsgs, error);
                    return false;
                }

                File.Delete(pathToFile);

                var moduleManifest = Path.Combine(tempDirNameVersion, pkgName + PSDataFileExt);
                var scriptPath = Path.Combine(tempDirNameVersion, pkgName + PSScriptFileExt);

                bool isModule = File.Exists(moduleManifest);
                bool isScript = File.Exists(scriptPath);

                if (!isModule && !isScript)
                {
                    scriptPath = "";
                }

                // TODO: add pkg validation when we figure out consistent/defined way to do so
                if (_authenticodeCheck && !AuthenticodeSignature.CheckAuthenticodeSignature(
                    pkgName,
                    tempDirNameVersion,
                    _cmdletPassedIn,
                    errorMsgs,
                    warningMsgs))
                {
                    return false;
                }

                string installPath = string.Empty;
                if (isModule)
                {
                    installPath = _pathsToInstallPkg.Find(path => path.EndsWith("Modules", StringComparison.InvariantCultureIgnoreCase));

                    if (!File.Exists(moduleManifest))
                    {
                        errorMsgs.Enqueue(new ErrorRecord(
                            new ArgumentException("Package '{pkgName}' could not be installed: Module manifest file: {moduleManifest} does not exist. This is not a valid PowerShell module."),
                            "PSDataFileNotExistError",
                            ErrorCategory.ReadError,
                            _cmdletPassedIn));

                            return false;
                        }

                    if (!Utils.TryReadManifestFile(
                        manifestFilePath: moduleManifest,
                        manifestInfo: out Hashtable parsedMetadataHashtable,
                        error: out Exception manifestReadError))
                    {
                        errorMsgs.Enqueue(new ErrorRecord(
                            manifestReadError,
                            "ManifestFileReadParseError",
                            ErrorCategory.ReadError,
                            _cmdletPassedIn));

                            return false;
                    }

                    // Accept License verification
                    if (!CallAcceptLicense(pkgToInstall, moduleManifest, tempInstallPath, pkgVersion, out error))
                    {
                        _pkgNamesToInstall.RemoveAll(x => x.Equals(pkgToInstall.Name, StringComparison.InvariantCultureIgnoreCase));
                        Utils.EnqueueIfNotNull(errorMsgs, error);
                        return false;
                    }

                    // If NoClobber is specified, ensure command clobbering does not happen
                    if (_noClobber && DetectClobber(pkgName, parsedMetadataHashtable, out error))
                    {
                        _pkgNamesToInstall.RemoveAll(x => x.Equals(pkgName, StringComparison.InvariantCultureIgnoreCase));
                        Utils.EnqueueIfNotNull(errorMsgs, error);
                        return false;
                    }
                }
                else if (isScript)
                {
                    installPath = _pathsToInstallPkg.Find(path => path.EndsWith("Scripts", StringComparison.InvariantCultureIgnoreCase));

                    // is script
                    if (!PSScriptFileInfo.TryTestPSScriptFileInfo(
                        scriptFileInfoPath: scriptPath,
                        parsedScript: out PSScriptFileInfo scriptToInstall,
                        out ErrorRecord[] parseScriptFileErrors,
                        out string[] verboseMessages))
                    {
                        foreach (ErrorRecord err in parseScriptFileErrors)
                        {
                            Utils.EnqueueIfNotNull(errorMsgs, err);
                        }
                        
                        foreach (var msg in verboseMessages)
                        {
                            Utils.EnqueueIfNotNull(verboseMsgs, msg);
                        }
                        return false;
                    }
                }
                else
                {
                    // This package is not a PowerShell package (eg a resource from the NuGet Gallery).
                    installPath = _pathsToInstallPkg.Find(path => path.EndsWith("Modules", StringComparison.InvariantCultureIgnoreCase));

                        // TODO: pass in ConcurrentQueue to write out verbose message.
                        // _cmdletPassedIn.WriteVerbose($"This resource is not a PowerShell package and will be installed to the modules path: {installPath}.");
                        isModule = true;
                }

                installPath = _savePkg ? _pathsToInstallPkg.First() : installPath;

                DeleteExtraneousFiles(pkgName, tempDirNameVersion);

                if (_includeXml)
                {
                    if (!CreateMetadataXMLFile(tempDirNameVersion, installPath, pkgToInstall, isModule, out error))
                    {
                        return false;
                    }
                }

                if (!updatedPackagesHash.ContainsKey(pkgName))
                {
                    // Add pkg info to hashtable.
                    updatedPackagesHash.TryAdd(pkgName, new Hashtable(StringComparer.InvariantCultureIgnoreCase)
                    {
                        { "isModule", isModule },
                        { "isScript", isScript },
                        { "psResourceInfoPkg", pkgToInstall },
                        { "tempDirNameVersionPath", tempDirNameVersion },
                        { "pkgVersion", pkgVersion },
                        { "scriptPath", scriptPath  },
                        { "installPath", installPath }
                    });
                }

                return true;
            }
            catch (Exception e)
            {
                errorMsgs.Enqueue(new ErrorRecord(
                    new PSInvalidOperationException(
                    message: $"Unable to successfully install package '{pkgName}': '{e.Message}' to temporary installation path.",
                    innerException: e),
                    "InstallPackageFailed",
                    ErrorCategory.InvalidOperation,
                    _cmdletPassedIn));

                return false;
            }
        }

        /// <summary>
        /// Attempts to take Http response content and move the .nupkg into a temporary install path on the machine.
        /// </summary>
        private bool TrySaveNupkgToTempPath(
            Stream responseStream,
            string tempInstallPath,
            string pkgName,
            string normalizedPkgVersion,
            PSResourceInfo pkgToInstall,
            ConcurrentDictionary<string, Hashtable> packagesHash,
            out ConcurrentDictionary<string, Hashtable> updatedPackagesHash,
            ConcurrentQueue<ErrorRecord> errorMsgs,
            ConcurrentQueue<string> warningMsgs,
            ConcurrentQueue<string> debugMsgs,
            ConcurrentQueue<string> verboseMsgs)
        {
            debugMsgs.Enqueue("In InstallHelper::TrySaveNupkgToTempPath()");
            updatedPackagesHash = packagesHash;

            try
            {
                var pathToFile = Path.Combine(tempInstallPath, $"{pkgName}.{normalizedPkgVersion}.zip");
                using var fs = File.Create(pathToFile);
                responseStream.Seek(0, System.IO.SeekOrigin.Begin);
                responseStream.CopyTo(fs);
                fs.Close();

                string installPath = _pathsToInstallPkg.First();
                if (_includeXml)
                {
                    if (!CreateMetadataXMLFile(tempInstallPath, installPath, pkgToInstall, isModule: true, out ErrorRecord error))
                    {
                        Utils.EnqueueIfNotNull(errorMsgs, error);
                        return false;
                    }
                }

                if (!updatedPackagesHash.ContainsKey(pkgName))
                {
                    // Add pkg info to hashtable.
                    updatedPackagesHash.TryAdd(pkgName, new Hashtable(StringComparer.InvariantCultureIgnoreCase)
                    {
                        { "isModule", "" },
                        { "isScript", "" },
                        { "psResourceInfoPkg", pkgToInstall },
                        { "tempDirNameVersionPath", tempInstallPath },
                        { "pkgVersion", "" },
                        { "scriptPath", ""  },
                        { "installPath", installPath }
                    });
                }

                return true;
            }
            catch (Exception e)
            {
                errorMsgs.Enqueue(new ErrorRecord(
                    new PSInvalidOperationException(
                            message: $"Unable to successfully save .nupkg '{pkgName}': '{e.Message}' to temporary installation path.",
                            innerException: e),
                    "SaveNupkgFailed",
                    ErrorCategory.InvalidOperation,
                    this));

                return false;
            }
        }

        /// <summary>
        /// Extracts files from .nupkg with platform-aware filtering.
        /// Similar functionality as System.IO.Compression.ZipFile.ExtractToDirectory,
        /// but while ExtractToDirectory cannot overwrite files, this method can.
        /// Additionally filters:
        /// - Root-level RID folder entries (e.g., win-x64/) based on the current platform's RID
        /// - lib/{tfm}/ entries to only extract the best matching Target Framework Moniker
        /// </summary>
        private bool TryExtractToDirectory(string zipPath, string extractPath, out ErrorRecord error)
        {
            error = null;
            // Normalize the path
            extractPath = Path.GetFullPath(extractPath);

            // Ensures that the last character on the extraction path is the directory separator char.
            // Without this, a malicious zip file could try to traverse outside of the expected extraction path.
            if (!extractPath.EndsWith(Path.DirectorySeparatorChar.ToString(), StringComparison.Ordinal))
            {
                extractPath += Path.DirectorySeparatorChar;
            }

            try
            {
                using (ZipArchive archive = ZipFile.OpenRead(zipPath))
                {
                    // Determine best TFM for lib/ folder filtering
                    // If user specified -TargetFramework, use that; otherwise auto-detect
                    NuGetFramework bestLibFramework;
                    if (!string.IsNullOrEmpty(_targetFramework))
                    {
                        bestLibFramework = NuGetFramework.ParseFolder(_targetFramework);
                        if (bestLibFramework == null || bestLibFramework.IsUnsupported)
                        {
                            _cmdletPassedIn.WriteDebug($"Could not parse specified TargetFramework '{_targetFramework}', falling back to auto-detection.");
                            bestLibFramework = GetBestLibFramework(archive);
                        }
                        else
                        {
                            _cmdletPassedIn.WriteDebug($"Using user-specified TargetFramework: {bestLibFramework.GetShortFolderName()}");
                        }
                    }
                    else
                    {
                        bestLibFramework = GetBestLibFramework(archive);
                    }

                    // Warn if TFM filtering is skipping assemblies for a different .NET lineage
                    // (e.g., installing on PS7/.NET 8 but package also has net472 for WinPS 5.1)
                    if (bestLibFramework != null)
                    {
                        WarnIfCrossLineageTfmSkipped(archive, bestLibFramework);
                    }

                    foreach (ZipArchiveEntry entry in archive.Entries.Where(entry => entry.CompressedLength > 0))
                    {
                        // RID filtering: skip entries under incompatible platform RID folders
                        {
                            bool includeEntry = !string.IsNullOrEmpty(_runtimeIdentifier)
                                ? RuntimePackageHelper.ShouldIncludeEntry(entry.FullName, _runtimeIdentifier)
                                : RuntimePackageHelper.ShouldIncludeEntry(entry.FullName);

                            if (!includeEntry)
                            {
                                _cmdletPassedIn.WriteDebug($"Skipping runtime entry not matching target platform: {entry.FullName}");
                                continue;
                            }
                        }

                        // TFM filtering: for lib/ entries, only extract the best matching TFM
                        if (bestLibFramework != null && !ShouldIncludeLibEntry(entry.FullName, bestLibFramework))
                        {
                            _cmdletPassedIn.WriteDebug($"Skipping lib entry not matching target framework: {entry.FullName}");
                            continue;
                        }

                        // If a file has one or more parent directories.
                        if (entry.FullName.Contains(Path.DirectorySeparatorChar) || entry.FullName.Contains(Path.AltDirectorySeparatorChar))
                        {
                            // Create the parent directories if they do not already exist
                            var lastPathSeparatorIdx = entry.FullName.Contains(Path.DirectorySeparatorChar) ?
                                entry.FullName.LastIndexOf(Path.DirectorySeparatorChar) : entry.FullName.LastIndexOf(Path.AltDirectorySeparatorChar);
                            var parentDirs = entry.FullName.Substring(0, lastPathSeparatorIdx);
                            var destinationDirectory = Path.Combine(extractPath, parentDirs);
                            if (!Directory.Exists(destinationDirectory))
                            {
                                Directory.CreateDirectory(destinationDirectory);
                            }
                        }

                        // Gets the full path to ensure that relative segments are removed.
                        string destinationPath = Path.GetFullPath(Path.Combine(extractPath, entry.FullName));

                        // Validate that the resolved output path starts with the resolved destination directory.
                        // For example, if a zip file contains a file entry ..\sneaky-file, and the zip file is extracted to the directory c:\output,
                        // then naively combining the paths would result in an output file path of c:\output\..\sneaky-file, which would cause the file to be written to c:\sneaky-file.
                        if (destinationPath.StartsWith(extractPath, StringComparison.Ordinal))
                        {
                            entry.ExtractToFile(destinationPath, overwrite: true);
                        }
                    }

                    // Warn if an explicitly specified TFM or RID had no matching entries in the package
                    if (!string.IsNullOrEmpty(_targetFramework) && bestLibFramework != null)
                    {
                        bool hasMatchingLib = archive.Entries.Any(e =>
                        {
                            string n = e.FullName.Replace('\\', '/');
                            if (!n.StartsWith("lib/", StringComparison.OrdinalIgnoreCase)) return false;
                            string[] s = n.Split('/');
                            if (s.Length < 3 || string.IsNullOrEmpty(s[1])) return false;
                            NuGetFramework fw = NuGetFramework.ParseFolder(s[1]);
                            return fw != null && !fw.IsUnsupported && fw.Equals(bestLibFramework);
                        });

                        if (!hasMatchingLib)
                        {
                            var availableTfms = archive.Entries
                                .Select(e => e.FullName.Replace('\\', '/'))
                                .Where(n => n.StartsWith("lib/", StringComparison.OrdinalIgnoreCase))
                                .Select(n => n.Split('/'))
                                .Where(s => s.Length >= 3 && !string.IsNullOrEmpty(s[1]))
                                .Select(s => s[1])
                                .Distinct(StringComparer.OrdinalIgnoreCase);
                            string available = string.Join(", ", availableTfms);
                            _cmdletPassedIn.WriteWarning(
                                $"The specified TargetFramework '{_targetFramework}' was not found in this package. " +
                                $"No lib/ assemblies were installed. Available TFMs: {(string.IsNullOrEmpty(available) ? "none" : available)}");
                        }
                    }

                    if (!string.IsNullOrEmpty(_runtimeIdentifier))
                    {
                        IReadOnlyList<string> availableRids = RuntimePackageHelper.GetAvailableRidsFromArchive(archive);
                        bool hasMatchingRid = availableRids.Any(rid =>
                            RuntimeIdentifierHelper.IsCompatibleRid(rid, _runtimeIdentifier));

                        if (!hasMatchingRid)
                        {
                            string available = string.Join(", ", availableRids);
                            _cmdletPassedIn.WriteWarning(
                                $"The specified RuntimeIdentifier '{_runtimeIdentifier}' was not found in this package. " +
                                $"No platform-specific assets were installed. Available RIDs: {(string.IsNullOrEmpty(available) ? "none" : available)}");
                        }
                    }
                }
            }
            catch (Exception e)
            {
                error = new ErrorRecord(
                    new Exception($"Error occurred while extracting .nupkg: '{e.Message}'"),
                    "ErrorExtractingNupkg",
                    ErrorCategory.OperationStopped,
                    _cmdletPassedIn);

                return false;
            }

            return true;
        }

        /// <summary>
        /// Determines the best matching Target Framework Moniker (TFM) from the lib/ folder entries in a zip archive.
        /// Uses NuGet.Frameworks.FrameworkReducer to select the nearest compatible framework.
        /// </summary>
        /// <param name="archive">The zip archive to analyze.</param>
        /// <returns>The best matching NuGetFramework, or null if no lib/ folders exist or no match is found.</returns>
        private NuGetFramework GetBestLibFramework(ZipArchive archive)
        {
            // Collect all TFMs from lib/ folder entries
            var libFrameworks = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
            foreach (ZipArchiveEntry entry in archive.Entries)
            {
                string normalizedName = entry.FullName.Replace('\\', '/');
                if (normalizedName.StartsWith("lib/", StringComparison.OrdinalIgnoreCase))
                {
                    string[] segments = normalizedName.Split('/');
                    if (segments.Length >= 3 && !string.IsNullOrEmpty(segments[1]))
                    {
                        libFrameworks.Add(segments[1]);
                    }
                }
            }

            if (libFrameworks.Count <= 1)
            {
                // Zero or one TFM — no filtering needed
                return null;
            }

            try
            {
                // Detect the current runtime's target framework
                NuGetFramework currentFramework = GetCurrentFramework();

                // Parse all discovered TFMs
                var parsedFrameworks = new List<NuGetFramework>();
                foreach (string tfm in libFrameworks)
                {
                    NuGetFramework parsed = NuGetFramework.ParseFolder(tfm);
                    if (parsed != null && !parsed.IsUnsupported)
                    {
                        parsedFrameworks.Add(parsed);
                    }
                }

                if (parsedFrameworks.Count == 0)
                {
                    return null;
                }

                // Use FrameworkReducer to find the best match
                var reducer = new FrameworkReducer();
                NuGetFramework bestMatch = reducer.GetNearest(currentFramework, parsedFrameworks);

                if (bestMatch != null)
                {
                    _cmdletPassedIn.WriteDebug($"Selected best matching TFM: {bestMatch.GetShortFolderName()} (from {string.Join(", ", libFrameworks)})");
                }

                return bestMatch;
            }
            catch (Exception e)
            {
                _cmdletPassedIn.WriteDebug($"TFM selection failed, extracting all lib/ folders: {e.Message}");
                return null;
            }
        }

        /// <summary>
        /// Determines if a zip entry from the lib/ folder should be included based on the best matching TFM.
        /// Non-lib entries are always included.
        /// </summary>
        /// <param name="entryFullName">The full name of the zip entry.</param>
        /// <param name="bestFramework">The best matching framework from GetBestLibFramework.</param>
        /// <returns>True if the entry should be extracted.</returns>
        private static bool ShouldIncludeLibEntry(string entryFullName, NuGetFramework bestFramework)
        {
            string normalizedName = entryFullName.Replace('\\', '/');

            // Only filter entries inside lib/
            if (!normalizedName.StartsWith("lib/", StringComparison.OrdinalIgnoreCase))
            {
                return true;
            }

            string[] segments = normalizedName.Split('/');
            if (segments.Length < 3 || string.IsNullOrEmpty(segments[1]))
            {
                // lib/ root files (uncommon) — include them
                return true;
            }

            string entryTfm = segments[1];
            NuGetFramework entryFramework = NuGetFramework.ParseFolder(entryTfm);

            if (entryFramework == null || entryFramework.IsUnsupported)
            {
                // Can't parse TFM, include to be safe
                return true;
            }

            // Only include entries matching the best framework
            return entryFramework.Equals(bestFramework);
        }

        /// <summary>
        /// Gets the NuGetFramework for the current runtime environment.
        /// Since this assembly is compiled as net472, it must detect the actual host runtime
        /// by parsing RuntimeInformation.FrameworkDescription rather than using Environment.Version
        /// (which returns 4.0.30319.x even when running on .NET 8+ via compatibility shims).
        /// </summary>
        private static NuGetFramework GetCurrentFramework()
        {
            string runtimeDescription = RuntimeInformation.FrameworkDescription;

            if (runtimeDescription.StartsWith(".NET Framework", StringComparison.OrdinalIgnoreCase))
            {
                // Windows PowerShell 5.1 — .NET Framework 4.x
                return NuGetFramework.ParseFolder("net472");
            }

            // PowerShell 7+ on .NET Core/.NET 5+
            // RuntimeInformation.FrameworkDescription format examples:
            //   ".NET Core 3.1.0"  -> netcoreapp3.1
            //   ".NET 6.0.5"       -> net6.0
            //   ".NET 8.0.1"       -> net8.0
            //   ".NET 9.0.0"       -> net9.0
            try
            {
                string versionPart = runtimeDescription;

                // Strip prefix to get just the version number
                if (versionPart.StartsWith(".NET Core ", StringComparison.OrdinalIgnoreCase))
                {
                    versionPart = versionPart.Substring(".NET Core ".Length);
                }
                else if (versionPart.StartsWith(".NET ", StringComparison.OrdinalIgnoreCase))
                {
                    versionPart = versionPart.Substring(".NET ".Length);
                }

                if (Version.TryParse(versionPart, out Version parsedVersion))
                {
                    return new NuGetFramework(".NETCoreApp", new Version(parsedVersion.Major, parsedVersion.Minor));
                }
            }
            catch
            {
                // Fall through to default
            }

            // Fallback: default to netstandard2.0 which is broadly compatible
            return NuGetFramework.ParseFolder("netstandard2.0");
        }

        /// <summary>
        /// Emits a warning if TFM filtering will skip assemblies for a different .NET lineage.
        /// For example, when installing on PowerShell 7 (.NET Core), if the package also contains
        /// .NET Framework assemblies (net472), those will be skipped — which means the module
        /// won't work if later used on Windows PowerShell 5.1.
        /// </summary>
        private void WarnIfCrossLineageTfmSkipped(ZipArchive archive, NuGetFramework bestFramework)
        {
            try
            {
                bool bestIsNetCore = bestFramework.Framework.Equals(".NETCoreApp", StringComparison.OrdinalIgnoreCase);
                bool bestIsNetFramework = bestFramework.Framework.Equals(".NETFramework", StringComparison.OrdinalIgnoreCase);

                // Only warn when we're on one lineage and skipping the other
                if (!bestIsNetCore && !bestIsNetFramework)
                {
                    return;
                }

                // Scan lib/ folders for a TFM from the other lineage
                var skippedLineageTfms = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
                foreach (ZipArchiveEntry entry in archive.Entries)
                {
                    string normalizedName = entry.FullName.Replace('\\', '/');
                    if (normalizedName.StartsWith("lib/", StringComparison.OrdinalIgnoreCase))
                    {
                        string[] segments = normalizedName.Split('/');
                        if (segments.Length >= 3 && !string.IsNullOrEmpty(segments[1]))
                        {
                            NuGetFramework entryFw = NuGetFramework.ParseFolder(segments[1]);
                            if (entryFw != null && !entryFw.IsUnsupported && !entryFw.Equals(bestFramework))
                            {
                                bool entryIsNetCore = entryFw.Framework.Equals(".NETCoreApp", StringComparison.OrdinalIgnoreCase);
                                bool entryIsNetFramework = entryFw.Framework.Equals(".NETFramework", StringComparison.OrdinalIgnoreCase);

                                // Detect cross-lineage: we're on Core and skipping Framework, or vice versa
                                if ((bestIsNetCore && entryIsNetFramework) || (bestIsNetFramework && entryIsNetCore))
                                {
                                    skippedLineageTfms.Add(segments[1]);
                                }
                            }
                        }
                    }
                }

                if (skippedLineageTfms.Count > 0)
                {
                    string skippedList = string.Join(", ", skippedLineageTfms);
                    string otherHost = bestIsNetCore ? "Windows PowerShell 5.1" : "PowerShell 7+";
                    string skippedTfm = skippedLineageTfms.First();
                    _cmdletPassedIn.WriteWarning(
                        $"This package contains assemblies for {skippedList} which were not installed because " +
                        $"the current runtime selected {bestFramework.GetShortFolderName()}. " +
                        $"If you also use this module on {otherHost}, run: Install-PSResource -Name <ModuleName> -TargetFramework '{skippedTfm}'");
                }
            }
            catch
            {
                // Non-critical warning — don't let it fail the install
            }
        }

        /// <summary>
        /// Moves package files/directories from the temp install path into the final install path location.
        /// </summary>
        private bool TryMoveInstallContent(
            string tempInstallPath,
            ScopeType scope,
            ConcurrentDictionary<string, Hashtable> packagesHash,
            bool mergeFilteredContent)
        {
            _cmdletPassedIn.WriteDebug("In InstallHelper::TryMoveInstallContent()");
            foreach (string pkgName in packagesHash.Keys)
            {
                Hashtable pkgInfo = packagesHash[pkgName] as Hashtable;
                bool isModule = (pkgInfo["isModule"] as bool?) ?? false;
                bool isScript = (pkgInfo["isScript"] as bool?) ?? false;
                PSResourceInfo pkgToInstall = pkgInfo["psResourceInfoPkg"] as PSResourceInfo;
                string tempDirNameVersion = pkgInfo["tempDirNameVersionPath"] as string;
                string pkgVersion = pkgInfo["pkgVersion"] as string;
                string scriptPath = pkgInfo["scriptPath"] as string;
                string installPath = pkgInfo["installPath"] as string;

                try
                {
                    MoveFilesIntoInstallPath(
                        pkgToInstall,
                        isModule,
                        isLocalRepo: false, // false for HTTP repo
                        tempDirNameVersion,
                        tempInstallPath,
                        installPath,
                        newVersion: pkgVersion, // would not have prerelease label in this string
                        moduleManifestVersion: pkgVersion,
                        scriptPath,
                        mergeFilteredContent);

                    _cmdletPassedIn.WriteVerbose($"Successfully installed package '{pkgName}' to location '{installPath}'");

                    if (!_savePkg && isScript)
                    {
                        string installPathwithBackSlash = installPath + "\\";
                        string envPATHVarValue = String.Empty;
                        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
                        {
                            envPATHVarValue = Environment.GetEnvironmentVariable("PATH",
                            scope == ScopeType.CurrentUser ? EnvironmentVariableTarget.User : EnvironmentVariableTarget.Machine);
                        }
                        else
                        {
                            // .NET on Unix-based systems does not support per-user and per-machine environment variables, only EnvironmentVariableTarget.Process successfully store an environment variable to the process environment block.
                            envPATHVarValue = Environment.GetEnvironmentVariable("PATH", EnvironmentVariableTarget.Process);
                        }

                        if (!String.IsNullOrEmpty(envPATHVarValue) && !envPATHVarValue.Contains(installPath) && !envPATHVarValue.Contains(installPathwithBackSlash))
                        {
                            _cmdletPassedIn.WriteWarning(String.Format(ScriptPATHWarning, scope, installPath));
                        }
                    }
                }
                catch (Exception e)
                {
                    _cmdletPassedIn.WriteError(new ErrorRecord(
                        new PSInvalidOperationException(
                            message: $"Unable to successfully install package '{pkgName}': '{e.Message}'",
                            innerException: e),
                        "InstallPackageFailed",
                        ErrorCategory.InvalidOperation,
                        _cmdletPassedIn));
                    
                    return false;
                }
            }

            return true;
        }

        /// <summary>
        /// If the package requires license to be accepted, checks if the user has accepted it.
        /// </summary>
        private bool CallAcceptLicense(PSResourceInfo p, string moduleManifest, string tempInstallPath, string newVersion, out ErrorRecord error)
        {
            error = null;
            var requireLicenseAcceptance = false;

            if (File.Exists(moduleManifest))
            {
                using (StreamReader sr = new(moduleManifest))
                {
                    var text = sr.ReadToEnd();

                    var pattern = "RequireLicenseAcceptance\\s*=\\s*\\$true";
                    var patternToSkip1 = "#\\s*RequireLicenseAcceptance\\s*=\\s*\\$true";
                    var patternToSkip2 = "\\*\\s*RequireLicenseAcceptance\\s*=\\s*\\$true";

                    Regex rgx = new(pattern);
                    Regex rgxComment1 = new(patternToSkip1);
                    Regex rgxComment2 = new(patternToSkip2);
                    if (rgx.IsMatch(text) && !rgxComment1.IsMatch(text) && !rgxComment2.IsMatch(text))
                    {
                        requireLicenseAcceptance = true;
                    }
                }

                // License agreement processing
                if (requireLicenseAcceptance)
                {
                    // If module requires license acceptance and -AcceptLicense is not passed in, display prompt
                    if (!_acceptLicense)
                    {
                        var PkgTempInstallPath = Path.Combine(tempInstallPath, p.Name, newVersion);
                        if (!Directory.Exists(PkgTempInstallPath))
                        {
                            error = new ErrorRecord(
                                new ArgumentException($"Package '{p.Name}' could not be installed: Temporary installation path does not exist."),
                                "TempPathNotFound",
                                ErrorCategory.ObjectNotFound,
                                _cmdletPassedIn);

                            return false;
                        }

                        string[] files = Directory.GetFiles(PkgTempInstallPath);

                        bool foundLicense = false;
                        string LicenseFilePath = string.Empty;
                        foreach (string file in files)
                        {
                            if (string.Equals(Path.GetFileName(file), "License.txt", StringComparison.OrdinalIgnoreCase))
                            {
                                foundLicense = true;
                                LicenseFilePath = Path.GetFullPath(file);
                                break;
                            }
                        }

                        if (!foundLicense)
                        {
                            error = new ErrorRecord(
                                new ArgumentException($"Package '{p.Name}' could not be installed: License.txt not found. License.txt must be provided when user license acceptance is required."),
                                "LicenseTxtNotFound",
                                ErrorCategory.ObjectNotFound,
                                _cmdletPassedIn);

                            return false;
                        }

                        // Otherwise read LicenseFile
                        string licenseText = File.ReadAllText(LicenseFilePath);
                        var acceptanceLicenseQuery = $"Do you accept the license terms for module '{p.Name}'?";
                        var message = licenseText + "\r\n" + acceptanceLicenseQuery;

                        var title = "License Acceptance";
                        var yesToAll = false;
                        var noToAll = false;
                        var shouldContinueResult = _cmdletPassedIn.ShouldContinue(message, title, true, ref yesToAll, ref noToAll);

                        if (shouldContinueResult || yesToAll)
                        {
                            _acceptLicense = true;
                        }
                    }

                    // Check if user agreed to license terms, if they didn't then throw error, otherwise continue to install
                    if (!_acceptLicense)
                    {
                        error = new ErrorRecord(
                            new ArgumentException($"Package '{p.Name}' could not be installed: License Acceptance is required for module '{p.Name}'. Please specify '-AcceptLicense' to perform this operation."),
                            "ForceAcceptLicense",
                            ErrorCategory.InvalidArgument,
                            _cmdletPassedIn);

                        return false;
                    }
                }
            }

            return true;
        }

        /// <summary>
        /// If the option for no clobber is specified, ensures that commands or cmdlets are not being clobbered.
        /// </summary>
        private bool DetectClobber(string pkgName, Hashtable parsedMetadataHashtable, out ErrorRecord error)
        {
            // TODO: pass in ConcurrentQueue to write out debug message.
            //_cmdletPassedIn.WriteDebug("In InstallHelper::DetectClobber()");
            error = null;
            bool foundClobber = false;

            // Get installed modules, then get all possible paths
            // selectPrereleaseOnly is false because even if Prerelease is true we want to include both stable and prerelease, would never select prerelease only.
            GetHelper getHelper = new(_cmdletPassedIn);
            IEnumerable<PSResourceInfo> pkgsAlreadyInstalled = getHelper.GetPackagesFromPath(
                name: new string[] { "*" },
                versionRange: VersionRange.All,
                pathsToSearch: _pathsToSearch,
                selectPrereleaseOnly: false);

            List<string> listOfCmdlets = new();
            if (parsedMetadataHashtable.ContainsKey("CmdletsToExport"))
            {
                if (parsedMetadataHashtable["CmdletsToExport"] is object[] cmdletsToExport)
                {
                    foreach (var cmdletName in cmdletsToExport)
                    {
                        listOfCmdlets.Add(cmdletName as string);
                    }
                }
            }

            foreach (var pkg in pkgsAlreadyInstalled)
            {
                List<string> duplicateCmdlets = new();
                List<string> duplicateCmds = new();
                // See if any of the cmdlets or commands in the pkg we're trying to install exist within a package that's already installed
                if (pkg.Includes.Cmdlet != null && pkg.Includes.Cmdlet.Length != 0)
                {
                    duplicateCmdlets = listOfCmdlets.Where(cmdlet => pkg.Includes.Cmdlet.Contains(cmdlet)).ToList();
                }

                if (pkg.Includes.Command != null && pkg.Includes.Command.Any())
                {
                    duplicateCmds = listOfCmdlets.Where(commands => pkg.Includes.Command.Contains(commands, StringComparer.InvariantCultureIgnoreCase)).ToList();
                }

                if (duplicateCmdlets.Count != 0 || duplicateCmds.Count != 0)
                {
                    duplicateCmdlets.AddRange(duplicateCmds);

                    error = new ErrorRecord(
                        new ArgumentException($"'{pkgName}' package could not be installed with error: The following commands are already available on this system: '{String.Join(", ", duplicateCmdlets)}'. " +
                            $"This module '{pkgName}' may override the existing commands. If you still want to install this module '{pkgName}', remove the -NoClobber parameter."),
                        "CommandAlreadyExists",
                        ErrorCategory.ResourceExists,
                        _cmdletPassedIn);
                    foundClobber = true;

                    return foundClobber;
                }
            }

            return foundClobber;
        }

        /// <summary>
        /// Creates metadata XML file for either module or script package.
        /// </summary>
        private bool CreateMetadataXMLFile(string dirNameVersion, string installPath, PSResourceInfo pkg, bool isModule, out ErrorRecord error)
        {
            error = null;
            bool success = true;
            // Script will have a metadata file similar to:  "TestScript_InstalledScriptInfo.xml"
            // Modules will have the metadata file: "PSGetModuleInfo.xml"
            var metadataXMLPath = isModule ? Path.Combine(dirNameVersion, "PSGetModuleInfo.xml")
                : Path.Combine(dirNameVersion, (pkg.Name + "_InstalledScriptInfo.xml"));

            pkg.InstalledDate = DateTime.Now;
            pkg.InstalledLocation = installPath;

            // Write all metadata into metadataXMLPath
            if (!pkg.TryWrite(metadataXMLPath, out string writeError))
            {
                error = new ErrorRecord(
                    new ArgumentException($"{pkg.Name} package could not be installed with error: Error parsing metadata into XML: '{writeError}'"),
                    "ErrorParsingMetadata",
                    ErrorCategory.ParserError,
                    _cmdletPassedIn);
                success = false;
            }

            return success;
        }

        /// <summary>
        /// Clean up and delete extraneous files found from the package during install.
        /// </summary>
        private void DeleteExtraneousFiles(string packageName, string dirNameVersion)
        {
            // TODO: pass in ConcurrentQueue to write out debug message.
           // _cmdletPassedIn.WriteDebug("In InstallHelper::DeleteExtraneousFiles()");
            // Deleting .nupkg SHA file, .nuspec, and .nupkg after unpacking the module
            // since we download as .zip for HTTP calls, we shouldn't have .nupkg* files
            // var nupkgSHAToDelete = Path.Combine(dirNameVersion, pkgIdString + ".nupkg.sha512");
            // var nupkgToDelete = Path.Combine(dirNameVersion, pkgIdString + ".nupkg");
            // var nupkgMetadataToDelete =  Path.Combine(dirNameVersion, ".nupkg.metadata");
            var nuspecToDelete = Path.Combine(dirNameVersion, packageName + ".nuspec");
            var contentTypesToDelete = Path.Combine(dirNameVersion, "[Content_Types].xml");
            var relsDirToDelete = Path.Combine(dirNameVersion, "_rels");
            var packageDirToDelete = Path.Combine(dirNameVersion, "package");

            if (File.Exists(nuspecToDelete))
            {
                File.Delete(nuspecToDelete);
            }
            if (File.Exists(contentTypesToDelete))
            {
                File.Delete(contentTypesToDelete);
            }
            if (Directory.Exists(relsDirToDelete))
            {
                Utils.DeleteDirectory(relsDirToDelete);
            }
            if (Directory.Exists(packageDirToDelete))
            {
                Utils.DeleteDirectory(packageDirToDelete);
            }
        }

        #endregion
    }
}