get-aspire-cli-pr.ps1

#!/usr/bin/env pwsh

<#
.SYNOPSIS
    Download and unpack the Aspire CLI from a specific PR's build artifacts

.DESCRIPTION
    Downloads and installs the Aspire CLI from a specific pull request's latest successful build.
    Automatically detects the current platform (OS and architecture) and downloads the appropriate artifact.

    The script queries the GitHub API to find the latest successful run of the 'ci.yml' workflow
    for the specified PR, then downloads and extracts the CLI archive for your platform using 'gh run download'.

    Alternatively, you can specify a workflow run ID directly to download from a specific build.

.PARAMETER PRNumber
    Pull request number (required)

.PARAMETER WorkflowRunId
    Workflow run ID to download from (optional)

.PARAMETER LocalDir
    Use pre-downloaded artifacts from a local directory instead of downloading from GitHub.
    Mutually exclusive with PRNumber and WorkflowRunId. The directory is auto-detected:
    if it contains an aspire-cli-*.tar.gz / .zip archive the archive flow is used; otherwise
    it is treated as raw 'dotnet build' / 'dotnet publish' output and the contained
    'aspire' or 'aspire.exe' executable is installed directly. NuGet packages (*.nupkg)
    in the directory are always installed into the hive.

.PARAMETER HiveLabel
    Override the NuGet hive label (default: pr-PRNUMBER, run-RUNID, or local for LocalDir).

.PARAMETER InstallPath
    Directory prefix to install (default: $HOME/.aspire on Unix, %USERPROFILE%\.aspire on Windows)
    CLI will be installed to InstallPath\bin (or InstallPath/bin on Unix) when installing from archives
    or as a dotnet tool with --tool-path.
    NuGet packages will be installed to InstallPath\hives\pr-PRNUMBER\packages.
    Alias: -i

.PARAMETER InstallMode
    How to install the CLI: 'Archive' (default) installs from the cli-native-archives-<rid>
    artifact, 'Tool' installs the Aspire.Cli dotnet tool from the PR's RID-specific NuGet artifact,
    'WinGet' installs from the generated WinGet manifest artifact, and 'Homebrew' installs from
    the generated Homebrew cask artifact.
    Alias: -m

.PARAMETER Force
    Tool mode only: run dotnet tool update instead of install to move an existing Aspire.Cli tool
    to the exact PR package version (allows downgrades).

.PARAMETER OS
    Override OS detection (win, linux, linux-musl, osx)

.PARAMETER Architecture
    Override architecture detection (x64, arm64)

.PARAMETER HiveOnly
    For installs from archives only: only install NuGet packages to the hive, skip CLI download

.PARAMETER SkipPath
    Do not add the install path to PATH environment variable (useful for portable installs)

.PARAMETER KeepArchive
    Keep downloaded archive files after installation

.PARAMETER Help
    Show this help message

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -WorkflowRunId 12345678

.EXAMPLE
    .\get-aspire-cli-pr.ps1 -LocalDir "C:\path\to\artifacts"

.EXAMPLE
    .\get-aspire-cli-pr.ps1 -LocalDir "C:\path\to\artifacts" -HiveLabel my-build

.EXAMPLE
    .\get-aspire-cli-pr.ps1 -LocalDir "artifacts\bin\Aspire.Cli\Debug\net10.0"

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -InstallPath "C:\my-aspire"

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -OS linux -Architecture arm64 -Verbose

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -HiveOnly

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -WhatIf

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -SkipExtension

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -UseInsiders

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -SkipPath

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -InstallMode Tool

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -InstallMode Tool -Force

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -InstallMode Homebrew

.EXAMPLE
    .\get-aspire-cli-pr.ps1 1234 -InstallMode WinGet

.EXAMPLE
    .\get-aspire-cli-pr.ps1 -LocalDir "C:\path\to\artifacts" -InstallMode Tool

.EXAMPLE
    Piped execution
    iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } <PR_NUMBER>

.NOTES
    Requires GitHub CLI (gh) to be installed and authenticated
    Requires appropriate permissions to download artifacts from target repository
    VS Code extension installation requires VS Code CLI (code) to be available in PATH

.PARAMETER ASPIRE_REPO (environment variable)
    Override repository (owner/name). Default: microsoft/aspire
    Example: $env:ASPIRE_REPO = 'myfork/aspire'
#>

[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Position = 0, HelpMessage = "Pull request number")]
    [ValidateRange(1, [int]::MaxValue)]
    [int]$PRNumber,

    [Parameter(HelpMessage = "Workflow run ID to download from")]
    [ValidateRange(1, [long]::MaxValue)]
    [long]$WorkflowRunId,

    [Parameter(HelpMessage = "Use pre-downloaded artifacts from a local directory instead of downloading from GitHub")]
    [string]$LocalDir = "",

    [Parameter(HelpMessage = "Override the NuGet hive label (default: pr-<PR>, run-<RUN_ID>, or local for --LocalDir)")]
    [string]$HiveLabel = "",

    [Parameter(HelpMessage = "Directory prefix to install")]
    [Alias("i")]
    [string]$InstallPath = "",

    [Parameter(HelpMessage = "How to install the CLI: 'Archive' (default), 'Tool', 'WinGet', or 'Homebrew'")]
    [Alias("m")]
    [ValidateSet("Archive", "Tool", "WinGet", "Homebrew")]
    [string]$InstallMode = "Archive",

    [Parameter(HelpMessage = "Tool mode updates an existing Aspire.Cli tool; WinGet mode allows replacing an existing Microsoft.Aspire install")]
    [switch]$Force,

    [Parameter(HelpMessage = "Override OS detection")]
    [ValidateSet("", "win", "linux", "linux-musl", "osx")]
    [string]$OS = "",

    [Parameter(HelpMessage = "Override architecture detection")]
    [ValidateSet("", "x64", "arm64")]
    [string]$Architecture = "",

    [Parameter(HelpMessage = "For installs from archives only: only install NuGet packages to the hive, skip CLI download")]
    [switch]$HiveOnly,

    [Parameter(HelpMessage = "Skip VS Code extension download and installation")]
    [switch]$SkipExtension,

    [Parameter(HelpMessage = "Install extension to VS Code Insiders instead of VS Code")]
    [switch]$UseInsiders,

    [Parameter(HelpMessage = "Do not add the install path to PATH environment variable (useful for portable installs)")]
    [switch]$SkipPath,

    [Parameter(HelpMessage = "Keep downloaded archive files after installation")]
    [switch]$KeepArchive,

    [Parameter(HelpMessage = "Show help information")]
    [switch]$Help
)

# Global constants
$Script:BuiltNugetsArtifactName = "built-nugets"
$Script:BuiltNugetsRidArtifactName = "built-nugets-for"
$Script:CliArchiveArtifactNamePrefix = "cli-native-archives"
$Script:AspireCliArtifactNamePrefix = "aspire-cli"
$Script:ExtensionArtifactName = "aspire-extension"
$Script:WinGetManifestArtifactName = "winget-manifests-prerelease"
$Script:HomebrewCaskArtifactName = "homebrew-cask-prerelease"
$Script:IsModernPowerShell = $PSVersionTable.PSVersion.Major -ge 6 -and $PSVersionTable.PSEdition -eq "Core"
$Script:HostOS = "unset"
$Script:Repository = if ($env:ASPIRE_REPO -and $env:ASPIRE_REPO.Trim()) { $env:ASPIRE_REPO.Trim() } else { 'microsoft/aspire' }
$Script:GHReposBase = "repos/$($Script:Repository)"

# True if the script is executed from a file (pwsh -File … or .\get-aspire-cli-pr.ps1)
# False if the body is piped / dot‑sourced / iex'd into the current session.
$InvokedFromFile = -not [string]::IsNullOrEmpty($PSCommandPath)

# =============================================================================
# START: Shared code
# =============================================================================

# Consolidated output function with fallback for platforms that don't support Write-Host
function Write-Message {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [string]$Message,

        [Parameter()]
        [ValidateSet("Verbose", "Info", "Success", "Warning", "Error")]
        [string]$Level = "Info"
    )

    $hasWriteHost = Get-Command Write-Host -ErrorAction SilentlyContinue

    switch ($Level) {
        "Verbose" {
            if ($VerbosePreference -ne "SilentlyContinue") {
                Write-Verbose $Message
            }
        }
        "Info" {
            if ($hasWriteHost) {
                Write-Host $Message -ForegroundColor White
            } else {
                Write-Output $Message
            }
        }
        "Success" {
            if ($hasWriteHost) {
                Write-Host $Message -ForegroundColor Green
            } else {
                Write-Output "SUCCESS: $Message"
            }
        }
        "Warning" {
            Write-Warning $Message
        }
        "Error" {
            Write-Error $Message
        }
    }
}

# Helper function for PowerShell version-specific operations
function Invoke-WithPowerShellVersion {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [scriptblock]$ModernAction,

        [Parameter(Mandatory = $true)]
        [scriptblock]$LegacyAction
    )

    if ($Script:IsModernPowerShell) {
        & $ModernAction
    } else {
        & $LegacyAction
    }
}

# Function to detect OS
function Get-OperatingSystem {
    [CmdletBinding()]
    [OutputType([string])]
    param()

    Write-Message "Detecting OS" -Level Verbose
    try {
        return Invoke-WithPowerShellVersion -ModernAction {
            if ($IsWindows) {
                return "win"
            }
            elseif ($IsLinux) {
                try {
                    $lddOutput = & ldd --version 2>&1 | Out-String
                    return if ($lddOutput -match "musl") { "linux-musl" } else { "linux" }
                }
                catch { return "linux" }
            }
            elseif ($IsMacOS) {
                return "osx"
            }
            else {
                return "unsupported"
            }
        } -LegacyAction {
            # PowerShell 5.1 and earlier - more reliable Windows detection
            if ($env:OS -eq "Windows_NT" -or [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
                return "win"
            }

            $platform = [System.Environment]::OSVersion.Platform
            switch ($platform) {
                { $_ -in @([System.PlatformID]::Unix, 4, 6) } { return "linux" }
                { $_ -in @([System.PlatformID]::MacOSX, 128) } { return "osx" }
                default { return "unsupported" }
            }
        }
    }
    catch {
        Write-Message "Failed to detect operating system: $($_.Exception.Message)" -Level Warning
        return "unsupported"
    }
}

# Enhanced function for cross-platform architecture detection
function Get-MachineArchitecture {
    [CmdletBinding()]
    [OutputType([string])]
    param()

    Write-Message "Detecting machine architecture" -Level Verbose

    try {
        # On Windows PowerShell, use environment variables
        if (-not $Script:IsModernPowerShell -or $IsWindows) {
            # On PS x86, PROCESSOR_ARCHITECTURE reports x86 even on x64 systems.
            # To get the correct architecture, we need to use PROCESSOR_ARCHITEW6432.
            # PS x64 doesn't define this, so we fall back to PROCESSOR_ARCHITECTURE.
            # Possible values: amd64, x64, x86, arm64, arm
            if ( $null -ne $ENV:PROCESSOR_ARCHITEW6432 ) {
                return $ENV:PROCESSOR_ARCHITEW6432
            }

            try {
                $osInfo = Get-CimInstance -ClassName CIM_OperatingSystem -ErrorAction Stop
                if ($osInfo.OSArchitecture -like "ARM*") {
                    if ([Environment]::Is64BitOperatingSystem) {
                        return "arm64"
                    }
                    return "arm"
                }
            }
            catch {
                Write-Message "Failed to get CIM instance: $($_.Exception.Message)" -Level Verbose
            }

            if ( $null -ne $ENV:PROCESSOR_ARCHITECTURE ) {
                return $ENV:PROCESSOR_ARCHITECTURE
            }
        }

        # For PowerShell 6+ on Unix systems, use .NET runtime information
        if ($Script:IsModernPowerShell) {
            try {
                $runtimeArch = [System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture
                switch ($runtimeArch) {
                    "X64" { return "x64" }
                    "Arm64" { return "arm64" }
                    default {
                        Write-Message "Unknown runtime architecture: $runtimeArch" -Level Verbose
                        # Fall back to uname if available
                        if (Get-Command uname -ErrorAction SilentlyContinue) {
                            $unameArch = & uname -m
                            switch ($unameArch) {
                                { @("x86_64", "amd64") -contains $_ } { return "x64" }
                                { @("aarch64", "arm64") -contains $_ } { return "arm64" }
                                default {
                                    throw "Architecture '$unameArch' not supported. If you think this is a bug, report it at https://github.com/microsoft/aspire/issues"
                                }
                            }
                        } else {
                            throw "Architecture '$runtimeArch' not supported (uname unavailable). If you think this is a bug, report it at https://github.com/microsoft/aspire/issues"
                        }
                    }
                }
            }
            catch {
                throw "Architecture detection failed: $($_.Exception.Message)"
            }
        }

        throw "Architecture detection failed (no supported detection path). If you think this is a bug, report it at https://github.com/microsoft/aspire/issues"
    }
    catch {
        throw "Architecture detection failed: $($_.Exception.Message)"
    }
}

# Convert architecture to CLI architecture format
function Get-CLIArchitectureFromArchitecture {
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$Architecture
    )

    if ($Architecture -eq "<auto>") {
        $Architecture = Get-MachineArchitecture
    }

    $normalizedArch = $Architecture.ToLowerInvariant()
    switch ($normalizedArch) {
        { @("amd64", "x64") -contains $_ } {
            return "x64"
        }
        { $_ -eq "arm64" } {
            return "arm64"
        }
        default {
            throw "Architecture '$Architecture' not supported. If you think this is a bug, report it at https://github.com/microsoft/aspire/issues"
        }
    }
}

function Get-RuntimeIdentifier {
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [string]$_OS,
        [string]$_Architecture
    )

    # Determine OS and architecture (either detected or user-specified)
    $computedTargetOS = if ([string]::IsNullOrWhiteSpace($_OS)) { $Script:HostOS } else { $_OS }

    # Check for unsupported OS
    if ($computedTargetOS -eq "unsupported") {
        throw "Unsupported operating system. Current platform: $([System.Environment]::OSVersion.Platform)"
    }

    $computedTargetArch = if ([string]::IsNullOrWhiteSpace($_Architecture)) { Get-CLIArchitectureFromArchitecture "<auto>" } else { Get-CLIArchitectureFromArchitecture $_Architecture }

    return "${computedTargetOS}-${computedTargetArch}"
}

# Function to get the CLI executable path based on host OS
function Get-CliExecutablePath {
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory = $true)]
        [string]$DestinationPath
    )

    $exeName = if ($Script:HostOS -eq "win") { "aspire.exe" } else { "aspire" }
    return Join-Path $DestinationPath $exeName
}

# Function to back up an existing CLI executable before overwriting it.
# This matches self-update semantics by deleting stale *.old.* backups first.
# On Windows, a running process can still block the rename.
function Backup-ExistingCliExecutable {
    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([string])]
    param(
        [Parameter(Mandatory = $true)]
        [string]$TargetExePath
    )

    if (Test-Path $TargetExePath) {
        $unixTimestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
        $backupPath = "$TargetExePath.old.$unixTimestamp"

        if ($PSCmdlet.ShouldProcess($TargetExePath, "Backup to $backupPath")) {
            Write-Message "Backing up existing CLI: $TargetExePath -> $backupPath" -Level Verbose

            Remove-OldCliBackupFiles -TargetExePath $TargetExePath

            # Rename existing executable to .old.[timestamp]
            try {
                Move-Item -Path $TargetExePath -Destination $backupPath -Force -ErrorAction Stop
            }
            catch {
                throw "Failed to back up existing CLI at '$TargetExePath'. The file may be in use by another process. Please close any running Aspire CLI instances and try again. Error: $($_.Exception.Message)"
            }
            return $backupPath
        }
    }

    return $null
}

# Function to restore CLI executable from backup if installation fails
function Restore-CliExecutableFromBackup {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$BackupPath,

        [Parameter(Mandatory = $true)]
        [string]$TargetExePath
    )

    if ($PSCmdlet.ShouldProcess($BackupPath, "Restore to $TargetExePath")) {
        Write-Message "Restoring CLI from backup: $BackupPath -> $TargetExePath" -Level Warning

        if (Test-Path $TargetExePath) {
            Remove-Item -Path $TargetExePath -Force -ErrorAction SilentlyContinue
        }

        Move-Item -Path $BackupPath -Destination $TargetExePath -Force -ErrorAction Stop
    }
}

# Function to clean up old backup files (aspire.exe.old.* or aspire.old.*)
function Remove-OldCliBackupFiles {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$TargetExePath
    )

    $directory = Split-Path -Parent $TargetExePath
    if ([string]::IsNullOrEmpty($directory)) {
        return
    }

    $exeName = Split-Path -Leaf $TargetExePath
    $searchPattern = "$exeName.old.*"

    $oldBackupFiles = Get-ChildItem -Path $directory -Filter $searchPattern -ErrorAction SilentlyContinue
    foreach ($backupFile in $oldBackupFiles) {
        if ($PSCmdlet.ShouldProcess($backupFile.FullName, "Delete old backup")) {
            try {
                Remove-Item -Path $backupFile.FullName -Force -ErrorAction Stop
                Write-Message "Deleted old backup file: $($backupFile.FullName)" -Level Verbose
            }
            catch {
                Write-Message "Failed to delete old backup file: $($backupFile.FullName) - $($_.Exception.Message)" -Level Verbose
            }
        }
    }
}

function Expand-AspireCliArchive {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [string]$ArchiveFile,
        [string]$DestinationPath
    )

    if (-not $PSCmdlet.ShouldProcess($DestinationPath, "Expand archive $ArchiveFile to $DestinationPath")) {
        return
    }

    Write-Message "Unpacking archive to: $DestinationPath" -Level Verbose

    # Get the target executable path using shared function
    $targetExePath = Get-CliExecutablePath -DestinationPath $DestinationPath
    $backupPath = $null

    try {
        # Create destination directory if it doesn't exist
        if (-not (Test-Path $DestinationPath)) {
            Write-Message "Creating destination directory: $DestinationPath" -Level Verbose
            New-Item -ItemType Directory -Path $DestinationPath -Force -ErrorAction Stop | Out-Null
        }
        else {
            # Back up the existing executable before extraction.
            # On Windows, this can still fail if the file is locked by a running process.
            $backupPath = Backup-ExistingCliExecutable -TargetExePath $targetExePath
        }

        Write-Message "Extracting archive: $ArchiveFile" -Level Verbose
        # Check archive format based on file extension and extract accordingly
        if ($ArchiveFile -match "\.zip$") {
            # Use Expand-Archive for ZIP files
            if (-not (Get-Command Expand-Archive -ErrorAction SilentlyContinue)) {
                throw "Expand-Archive cmdlet not found. Please use PowerShell 5.0 or later to extract ZIP files."
            }

            Expand-Archive -Path $ArchiveFile -DestinationPath $DestinationPath -Force -ErrorAction Stop
        }
        elseif ($ArchiveFile -match "\.tar\.gz$") {
            # Use tar for tar.gz files
            if (-not (Get-Command tar -ErrorAction SilentlyContinue)) {
                throw "tar command not found. Please install tar to extract tar.gz files."
            }

            $currentLocation = Get-Location
            try {
                Set-Location $DestinationPath
                $tarOutput = & tar -xzf $ArchiveFile 2>&1
                if ($LASTEXITCODE -ne 0) {
                    $tarMessage = ($tarOutput | ForEach-Object { $_.ToString() } | Out-String).Trim()
                    if ([string]::IsNullOrWhiteSpace($tarMessage)) {
                        throw "Failed to extract tar.gz archive: $ArchiveFile. tar command returned exit code $LASTEXITCODE"
                    }

                    throw "Failed to extract tar.gz archive: $ArchiveFile. tar command returned exit code $LASTEXITCODE`: $tarMessage"
                }
            }
            finally {
                Set-Location $currentLocation
            }
        }
        else {
            throw "Unsupported archive format: $ArchiveFile. Only .zip and .tar.gz files are supported."
        }

        # Clean up old backup files on successful extraction
        if (Test-Path $targetExePath) {
            Remove-OldCliBackupFiles -TargetExePath $targetExePath
        }

        Write-Message "Successfully unpacked archive" -Level Verbose
    }
    catch {
        $unpackErrorMessage = $_.Exception.Message

        # If anything goes wrong and we have a backup, restore it
        if ($backupPath -and (Test-Path $backupPath)) {
            try {
                Restore-CliExecutableFromBackup -BackupPath $backupPath -TargetExePath $targetExePath
            }
            catch {
                throw "Failed to unpack archive: $unpackErrorMessage. Restore from backup also failed: $($_.Exception.Message)"
            }
        }

        throw "Failed to unpack archive: $unpackErrorMessage"
    }
}

# Simplified installation path determination
function Get-DefaultInstallPrefix {
    [CmdletBinding()]
    [OutputType([string])]
    param()

    # Get home directory cross-platform
    $homeDirectory = Invoke-WithPowerShellVersion -ModernAction {
        if ($env:HOME) {
            $env:HOME
        } elseif ($IsWindows -and $env:USERPROFILE) {
            $env:USERPROFILE
        } elseif ($env:USERPROFILE) {
            $env:USERPROFILE
        } else {
            $null
        }
    } -LegacyAction {
        if ($env:USERPROFILE) {
            $env:USERPROFILE
        } elseif ($env:HOME) {
            $env:HOME
        } else {
            $null
        }
    }

    if ([string]::IsNullOrWhiteSpace($homeDirectory)) {
        throw "Unable to determine user home directory. Please specify -InstallPath parameter."
    }

    $defaultPath = Join-Path $homeDirectory ".aspire"
    return [System.IO.Path]::GetFullPath($defaultPath)
}

# Simplified PATH environment update
function Test-PathContainsDirectory {
    [CmdletBinding()]
    [OutputType([bool])]
    param(
        [AllowEmptyString()]
        [string]$PathValue,

        [Parameter(Mandatory = $true)]
        [string]$Directory
    )

    if ([string]::IsNullOrEmpty($PathValue)) {
        return $false
    }

    return $PathValue.Split([System.IO.Path]::PathSeparator, [StringSplitOptions]::RemoveEmptyEntries) -contains $Directory
}

function Update-PathEnvironment {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$CliBinDir
    )

    $pathSeparator = [System.IO.Path]::PathSeparator

    if (Test-PathContainsDirectory -PathValue $env:PATH -Directory $CliBinDir) {
        Write-Message "Path $CliBinDir already exists in PATH, skipping addition" -Level Info
    } else {
        # Update current session PATH
        $currentPathArray = if ($env:PATH) { $env:PATH.Split($pathSeparator, [StringSplitOptions]::RemoveEmptyEntries) } else { @() }
        if ($PSCmdlet.ShouldProcess("PATH environment variable", "Add $CliBinDir to current session")) {
            $env:PATH = (@($CliBinDir) + $currentPathArray) -join $pathSeparator
            Write-Message "Added $CliBinDir to PATH for current session" -Level Info
        }
    }

    # Update persistent PATH for Windows.
    # PR installs deliberately skip the persistent user PATH write: a PR build is a per-session
    # dogfood activation. Writing it into HKCU\Environment would silently demote a developer's
    # daily/stable install on every new shell until they hunt down the stale entry. The
    # activation hint printed elsewhere shows how to opt in manually.
    $isPrPath = $CliBinDir -match '[/\\]dogfood[/\\]pr-[^/\\]+[/\\]bin$'
    if ($Script:HostOS -eq "win" -and -not $isPrPath) {
        try {
            $userPath = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User)
            if (-not $userPath) { $userPath = "" }
            $userPathArray = if ($userPath) { $userPath.Split($pathSeparator, [StringSplitOptions]::RemoveEmptyEntries) } else { @() }
            if ($userPathArray -notcontains $CliBinDir) {
                if ($PSCmdlet.ShouldProcess("User PATH environment variable", "Add $CliBinDir")) {
                    $newUserPath = (@($CliBinDir) + $userPathArray) -join $pathSeparator
                    [Environment]::SetEnvironmentVariable("PATH", $newUserPath, [EnvironmentVariableTarget]::User)
                    Write-Message "Added $CliBinDir to user PATH environment variable" -Level Info
                }
            }

            Write-Message "" -Level Info
            Write-Message "The aspire cli is now available for use in this and new sessions." -Level Success
        }
        catch {
            Write-Message "Failed to update persistent PATH environment variable: $($_.Exception.Message)" -Level Warning
            Write-Message "You may need to manually add $CliBinDir to your PATH environment variable" -Level Info
        }
    } elseif ($Script:HostOS -eq "win" -and $isPrPath) {
        Write-Message "PR install: leaving user PATH untouched; the activation hint below shows the PATH line to use." -Level Info
    }

    # GitHub Actions support
    if ($env:GITHUB_ACTIONS -eq "true" -and $env:GITHUB_PATH) {
        try {
            if ($PSCmdlet.ShouldProcess("GITHUB_PATH environment variable", "Add $CliBinDir to GITHUB_PATH")) {
                Add-Content -Path $env:GITHUB_PATH -Value $CliBinDir
                Write-Message "Added $CliBinDir to GITHUB_PATH for GitHub Actions" -Level Success
            }
        }
        catch {
            Write-Message "Failed to update GITHUB_PATH: $($_.Exception.Message)" -Level Warning
        }
    }
}

# Function to create a temporary directory with conflict resolution
function New-TempDirectory {
    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([string])]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$Prefix
    )

    if ($PSCmdlet.ShouldProcess("temporary directory", "Create temporary directory with prefix '$Prefix'")) {
        # Create a temporary directory for downloads with conflict resolution
        $tempBaseName = "$Prefix-$([System.Guid]::NewGuid().ToString("N").Substring(0, 8))"
        $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) $tempBaseName

        # Handle potential conflicts
        $attempt = 1
        while (Test-Path $tempDir) {
            $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "$tempBaseName-$attempt"
            $attempt++
            if ($attempt -gt 10) {
                throw "Unable to create temporary directory after 10 attempts"
            }
        }

        Write-Message "Creating temporary directory: $tempDir" -Level Verbose
        try {
            New-Item -ItemType Directory -Path $tempDir -Force -ErrorAction Stop | Out-Null
            return $tempDir
        }
        catch {
            throw "Failed to create temporary directory: $tempDir - $($_.Exception.Message)"
        }
    }
    else {
        # Return a WhatIf path when -WhatIf is used
        return Join-Path ([System.IO.Path]::GetTempPath()) "$Prefix-whatif"
    }
}

# Cleanup function for temporary directory
function Remove-TempDirectory {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter()]
        [string]$TempDir
    )

    if (-not [string]::IsNullOrWhiteSpace($TempDir) -and (Test-Path $TempDir)) {
        if (-not $KeepArchive) {
            Write-Message "Cleaning up temporary files..." -Level Verbose
            try {
                if ($PSCmdlet.ShouldProcess($TempDir, "Remove temporary directory")) {
                    Remove-Item $TempDir -Recurse -Force -ErrorAction Stop
                }
            }
            catch {
                Write-Message "Failed to clean up temporary directory: $TempDir - $($_.Exception.Message)" -Level Warning
            }
        }
        else {
            Write-Message "Archive files kept in: $TempDir" -Level Info
        }
    }
}

# =============================================================================
# END: Shared code
# =============================================================================

# Function to check if gh command is available
function Test-GitHubCLIDependency {
    [CmdletBinding()]
    param()

    if (-not (Get-Command gh -ErrorAction SilentlyContinue)) {
        Write-Message "GitHub CLI (gh) is required but not installed. Please install it first." -Level Error
        Write-Message "Installation instructions: https://cli.github.com/" -Level Info
        throw "GitHub CLI (gh) dependency not met"
    }

    $ghVersion = & gh --version 2>&1
    if ($LASTEXITCODE -ne 0) {
        throw "GitHub CLI (gh) command failed with exit code $LASTEXITCODE`: $ghVersion"
    } else {
        $firstLine = ($ghVersion | Select-Object -First 1)
        Write-Message "GitHub CLI (gh) found: $firstLine" -Level Verbose
    }
}

# Function to check VS Code CLI dependency
function Test-VSCodeCLIDependency {
    [CmdletBinding()]
    param(
        [switch]$UseInsiders
    )

    $vscodeCmd = if ($UseInsiders) { "code-insiders" } else { "code" }
    $vscodeName = if ($UseInsiders) { "VS Code Insiders" } else { "VS Code" }

    if (-not (Get-Command $vscodeCmd -ErrorAction SilentlyContinue)) {
        Write-Message "$vscodeName CLI ($vscodeCmd) is not available in PATH. Extension installation will be skipped." -Level Warning
        Write-Message "To install $vscodeName extensions, ensure $vscodeName is installed and the '$vscodeCmd' command is available." -Level Info
        return $false
    }

    Write-Message "$vscodeName CLI ($vscodeCmd) found" -Level Verbose
    return $true
}

# Simplified installation path determination
function Get-InstallPrefix {
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter()]
        [string]$InstallPrefix
    )

    if (-not [string]::IsNullOrWhiteSpace($InstallPrefix)) {
        # Validate that the path is not just whitespace and can be created
        try {
            $resolvedPath = [System.IO.Path]::GetFullPath($InstallPrefix)
            return $resolvedPath
        }
        catch {
            throw "Invalid installation path: $InstallPrefix - $($_.Exception.Message)"
        }
    }

    return Get-DefaultInstallPrefix
}

# Function to make GitHub API calls with proper error handling
function Invoke-GitHubAPICall {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Endpoint,

        [Parameter()]
        [string]$JqFilter = "",

        [Parameter()]
        [string]$ErrorMessage = "Failed to call GitHub API"
    )

    $ghCommand = @("gh", "api", $Endpoint)

    if (-not [string]::IsNullOrWhiteSpace($JqFilter)) {
        $ghCommand += @("--jq", $JqFilter)
    }

    Write-Message "Calling GitHub API: $($ghCommand -join ' ')" -Level Verbose

    $output = & $ghCommand[0] $ghCommand[1..($ghCommand.Length-1)] 2>&1

    if ($LASTEXITCODE -ne 0) {
        throw "$ErrorMessage (API endpoint: $Endpoint): $output"
    }

    return $output
}

# Function to get PR head SHA
function Get-PRHeadSHA {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [int]$PRNumber
    )

    Write-Message "Getting HEAD SHA for PR #$PRNumber" -Level Verbose

    if ($Script:Repository -notmatch '^([^/]+)/([^/]+)$') {
        throw "Invalid repository format '$Script:Repository'. Expected 'owner/name'."
    }
    $owner = $Matches[1]
    $name = $Matches[2]

    $graphqlQuery = 'query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { headRefOid } } }'
    $ghCommand = @(
        "gh", "api", "graphql",
        "-f", "query=$graphqlQuery",
        "-f", "owner=$owner",
        "-f", "name=$name",
        "-F", "number=$PRNumber",
        "--jq", ".data.repository.pullRequest.headRefOid"
    )

    Write-Message "Calling GitHub API: $($ghCommand -join ' ')" -Level Verbose

    $graphQlError = $null
    try {
        $headSha = & $ghCommand[0] $ghCommand[1..($ghCommand.Length-1)] 2>$null
        if ($LASTEXITCODE -ne 0) {
            $graphQlError = "gh exited with code $LASTEXITCODE"
        } elseif ([string]::IsNullOrWhiteSpace($headSha) -or $headSha -eq "null") {
            $graphQlError = "GraphQL returned empty or null result"
        } else {
            # Normalize to a single trimmed string in case of unexpected multi-line output
            $headSha = ($headSha | Select-Object -First 1).Trim()
        }
    }
    catch {
        $graphQlError = $_.Exception.Message
    }

    if ($graphQlError) {
        Write-Message "GraphQL PR head lookup failed, falling back to REST API: $graphQlError" -Level Verbose
        try {
            $headSha = Invoke-GitHubAPICall -Endpoint "$Script:GHReposBase/pulls/$PRNumber" -JqFilter ".head.sha" -ErrorMessage "Failed to get HEAD SHA for PR #$PRNumber using REST fallback"
        }
        catch {
            throw "Failed to get HEAD SHA for PR #$PRNumber with GraphQL query: $graphQlError`nREST fallback error: $($_.Exception.Message)"
        }
    }

    if ([string]::IsNullOrWhiteSpace($headSha) -or $headSha -eq "null") {
        Write-Message "This could mean:" -Level Info
        Write-Message "  - The PR number does not exist" -Level Info
        Write-Message "  - You don't have access to the repository" -Level Info
        throw "Could not retrieve HEAD SHA for PR #$PRNumber"
    }

    Write-Message "PR #$PRNumber HEAD SHA: $headSha" -Level Verbose
    return $headSha.Trim()
}

# Function to extract version suffix from downloaded NuGet packages
function Get-VersionSuffixFromPackages {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$DownloadDir
    )

    if ($WhatIfPreference) {
        # Return a non-PR-shaped sentinel so the -LocalDir auto-detect regex at the
        # call site (^pr\.(\d+)\.[0-9a-g]+$) does NOT match and the caller falls
        # through to hive_label="local". A "pr.<N>.gSHA"-shaped mock would always
        # match and force hive_label="pr-1234" in every -WhatIf run, regardless of
        # what is actually in -LocalDir.
        return "local"
    }

    # Look for any .nupkg file and extract version from its name
    $nupkgFiles = Get-ChildItem -Path $DownloadDir -Filter "*.nupkg" -Recurse | Select-Object -First 1

    if (-not $nupkgFiles) {
        Write-Message "No .nupkg files found to extract version from" -Level Verbose
        throw "No NuGet packages found to extract version information from"
    }

    $filename = $nupkgFiles.Name
    Write-Message "Extracting version from package: $filename" -Level Verbose

    # Extract version from package name using a more robust approach
    # Remove .nupkg extension first, then look for the specific version pattern
    $baseName = $filename -replace '\.nupkg$', ''

    # Look for semantic version pattern with PR suffix (more specific and robust)
    if ($baseName -match '.*\.(\d+\.\d+\.\d+-pr\.\d+\.[0-9a-g]+)$') {
        $version = $Matches[1]
        Write-Message "Extracted version: $version" -Level Verbose

        # Extract just the PR suffix part using more specific regex
        if ($version -match '(pr\.[0-9]+\.[0-9a-g]+)') {
            $versionSuffix = $Matches[1]
            Write-Message "Extracted version suffix: $versionSuffix" -Level Verbose
            return $versionSuffix
        } else {
            Write-Message "Package version does not contain PR suffix: $version" -Level Verbose
            throw "Package version does not contain expected PR suffix format"
        }
    } else {
        Write-Message "Could not extract version from package name: $filename" -Level Verbose
        throw "Could not extract version from package name: $filename"
    }
}

# =============================================================================
# Tool-mode helpers (installing the Aspire.Cli dotnet tool)
# =============================================================================

# Verify that 'dotnet' is available in PATH (required for tool mode).
function Test-DotnetDependency {
    [CmdletBinding()]
    param()

    if (-not (Get-Command dotnet -ErrorAction SilentlyContinue)) {
        Write-Message "The .NET SDK 'dotnet' command is required for -InstallMode Tool but was not found in PATH." -Level Error
        Write-Message "Install the .NET SDK from https://dotnet.microsoft.com/download and ensure 'dotnet' is on your PATH." -Level Info
        throw ".NET SDK 'dotnet' dependency not met"
    }

    Write-Message "dotnet found: $((& dotnet --version 2>&1 | Select-Object -First 1))" -Level Verbose
}

# Find the unique Aspire.Cli.<version>.nupkg in the given directory and return its exact version.
# Throws if zero or more than one matching package is present.
function Find-AspireCliPackageVersion {
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$SearchDir
    )

    if ($WhatIfPreference -and -not (Test-Path $SearchDir)) {
        Write-Message "[WhatIf] Would discover Aspire.Cli package version under: $SearchDir" -Level Info
        return "13.3.0-pr.1234.a1b2c3d4"
    }

    if (-not (Test-Path $SearchDir -PathType Container)) {
        throw "Cannot find Aspire.Cli package: directory does not exist: $SearchDir"
    }

    $packageMatches = @(
        Get-ChildItem -Path $SearchDir -Filter "Aspire.Cli.*.nupkg" -Recurse -File |
            Where-Object {
                $_.Name -notmatch '\.symbols\.nupkg$' -and
                $_.Name -notmatch '\.snupkg$' -and
                $_.Name -notmatch '^Aspire\.Cli\.(win|linux|linux-musl|osx)-(x64|arm64)\.' -and
                $_.Name -match '^Aspire\.Cli\.([0-9A-Za-z.-]+)\.nupkg$'
            }
    )

    if ($packageMatches.Count -eq 0) {
        throw "No Aspire.Cli.<version>.nupkg package found under: $SearchDir. Tool mode requires the Aspire.Cli dotnet tool package to be present in the package source."
    }
    if ($packageMatches.Count -gt 1) {
        $listing = ($packageMatches | ForEach-Object { "  $($_.FullName)" }) -join [Environment]::NewLine
        throw "Multiple Aspire.Cli.<version>.nupkg packages found (expected exactly one):`n$listing"
    }

    $name = $packageMatches[0].Name
    if ($name -notmatch '^Aspire\.Cli\.(.+)\.nupkg$') {
        throw "Failed to parse version from Aspire.Cli package filename: $name"
    }
    return $Matches[1]
}

# Install or update the Aspire.Cli dotnet tool from the populated hive.
function Install-AspireCliTool {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$HiveDir,

        [Parameter()]
        [string]$ToolPath
    )

    $version = Find-AspireCliPackageVersion -SearchDir $HiveDir

    $installLocationArgs = if ([string]::IsNullOrWhiteSpace($ToolPath)) {
        @("--global")
    } else {
        @("--tool-path", $ToolPath)
    }

    $cmdArgs = if ($Force) {
        @("tool", "update") + $installLocationArgs + @("Aspire.Cli", "--version", $version, "--add-source", $HiveDir, "--allow-downgrade")
    } else {
        @("tool", "install") + $installLocationArgs + @("Aspire.Cli", "--version", $version, "--add-source", $HiveDir)
    }

    $description = "$($cmdArgs[1]) Aspire.Cli dotnet tool from $HiveDir (version $version)"
    if (-not $PSCmdlet.ShouldProcess("Aspire.Cli", $description)) {
        Write-Message "[WhatIf] Would run: dotnet $($cmdArgs -join ' ')" -Level Info
        return
    }

    Write-Message "Installing Aspire.Cli dotnet tool (version $version) from $HiveDir" -Level Info
    Write-Message "Running: dotnet $($cmdArgs -join ' ')" -Level Verbose

    & dotnet @cmdArgs
    if ($LASTEXITCODE -ne 0) {
        if (-not $Force) {
            Write-Message "If Aspire.Cli is already installed or this PR version needs to replace an existing install, re-run with -Force." -Level Info
        }
        throw "Failed to $($cmdArgs[1]) Aspire.Cli dotnet tool from $HiveDir (exit code: $LASTEXITCODE)"
    }

    Write-Message "Aspire.Cli dotnet tool installed (version $version)" -Level Success
}

function Test-ToolModeRuntimeIdentifier {
    [CmdletBinding()]
    param()

    $targetOS = if ([string]::IsNullOrWhiteSpace($OS)) { $Script:HostOS } else { $OS }
    $targetArch = if ([string]::IsNullOrWhiteSpace($Architecture)) { Get-CLIArchitectureFromArchitecture "<auto>" } else { Get-CLIArchitectureFromArchitecture $Architecture }
    $hostArch = Get-CLIArchitectureFromArchitecture "<auto>"

    if ($targetOS -ne $Script:HostOS -or $targetArch -ne $hostArch) {
        # Split the message across Write-Message + throw so the second sentence isn't
        # truncated by PowerShell 7's ConciseView when the exception is rendered. See
        # the parallel Bash twin in get-aspire-cli-pr.sh which uses say_error + say_info,
        # and the same pattern used elsewhere in this script (e.g. -HiveOnly + -InstallMode Tool).
        Write-Message "-InstallMode Tool cannot target $targetOS-$targetArch from this $($Script:HostOS)-$hostArch host." -Level Error
        Write-Message "dotnet tool install resolves RID-specific packages for the current host. Run tool mode on the target machine, or use archive mode for cross-RID downloads." -Level Info
        throw "-InstallMode Tool cannot target $targetOS-$targetArch from this $($Script:HostOS)-$hostArch host."
    }
}

# Function to find workflow run for SHA
function Find-WorkflowRun {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$HeadSHA
    )

    Write-Message "Finding ci.yml workflow run for SHA: $HeadSHA" -Level Verbose

    $runId = Invoke-GitHubAPICall -Endpoint "$Script:GHReposBase/actions/workflows/ci.yml/runs?event=pull_request&head_sha=$HeadSHA" -JqFilter ".workflow_runs | sort_by(.created_at, .updated_at) | reverse | .[0].id" -ErrorMessage "Failed to query workflow runs for SHA: $HeadSHA"

    if ([string]::IsNullOrWhiteSpace($runId) -or $runId -eq "null") {
        throw "No ci.yml workflow run found for PR SHA: $HeadSHA. This could mean no workflow has been triggered for this SHA $HeadSHA . Check at https://github.com/microsoft/aspire/actions/workflows/ci.yml"
    }

    Write-Message "Found workflow run ID: $runId" -Level Verbose
    return $runId.Trim()
}

# Function to download artifact using gh run download
function Invoke-ArtifactDownload {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$RunId,

        [Parameter(Mandatory = $true)]
        [string]$ArtifactName,

        [Parameter(Mandatory = $true)]
        [string]$DownloadDirectory
    )

    $downloadCommand = @("gh", "run", "download", $RunId, "-R", $Script:Repository, "--name", $ArtifactName, "-D", $DownloadDirectory)

    if ($PSCmdlet.ShouldProcess($ArtifactName, "Download $ArtifactName with $($downloadCommand -join ' ')")) {
        Write-Message "Downloading with: $($downloadCommand -join ' ')" -Level Verbose

        & $downloadCommand[0] $downloadCommand[1..($downloadCommand.Length-1)]

        if ($LASTEXITCODE -ne 0) {
            Write-Message "gh run download command failed with exit code $LASTEXITCODE . Command: $($downloadCommand -join ' ')" -Level Verbose
            throw "Failed to download artifact '$ArtifactName' from run: $RunId . If the workflow is still running then the artifact named '$ArtifactName' may not be available yet. Check at https://github.com/microsoft/aspire/actions/runs/$RunId#artifacts"
        }
    }
}

# Function to download VS Code extension artifact
function Get-AspireExtensionFromArtifact {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$RunId,

        [Parameter(Mandatory = $true)]
        [string]$TempDir
    )

    $downloadDir = Join-Path $TempDir "extension"
    Write-Message "Downloading VS Code extension from GitHub - $Script:ExtensionArtifactName ..." -Level Info

    try {
        Invoke-ArtifactDownload -RunId $RunId -ArtifactName $Script:ExtensionArtifactName -DownloadDirectory $downloadDir
        return $downloadDir
    }
    catch {
        Write-Message "Failed to download VS Code extension artifact: $($_.Exception.Message)" -Level Warning
        Write-Message "This could mean the extension artifact is not available for this build." -Level Info
        return $null
    }
}

# Function to install VS Code extension
function Install-AspireExtensionFromDownload {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$DownloadDir,

        [switch]$UseInsiders
    )

    $vscodeCmd = if ($UseInsiders) { "code-insiders" } else { "code" }
    $vscodeName = if ($UseInsiders) { "VS Code Insiders" } else { "VS Code" }

    if (!$PSCmdlet.ShouldProcess($vscodeName, "Installing Aspire extension")) {
        return
    }

    # Find the .vsix file directly (the artifact contains the .vsix file, not a zip)
    $vsixFile = Get-ChildItem -Path $DownloadDir -Filter "*.vsix" -Recurse | Select-Object -First 1

    if (-not $vsixFile) {
        Write-Message "No .vsix file found in downloaded artifact" -Level Warning
        Write-Message "Files found in download directory:" -Level Verbose
        Get-ChildItem -Path $DownloadDir -Recurse | ForEach-Object { Write-Message "  $($_.Name)" -Level Verbose }
        return
    }

    try {
        # Install the extension using VS Code CLI
        Write-Message "Installing $vscodeName extension: $($vsixFile.Name)" -Level Info
        $installCommand = @($vscodeCmd, "--install-extension", $vsixFile.FullName)

        & $installCommand[0] $installCommand[1..($installCommand.Length-1)]

        if ($LASTEXITCODE -eq 0) {
            Write-Message "$vscodeName extension successfully installed" -Level Success
        } else {
            Write-Message "Failed to install $vscodeName extension (exit code: $LASTEXITCODE)" -Level Warning
        }
    }
    catch {
        Write-Message "Failed to install $vscodeName extension: $($_.Exception.Message)" -Level Warning
    }
}

# Function to download built-nugets artifact
function Get-BuiltNugets {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$RunId,

        [Parameter(Mandatory = $true)]
        [string]$RID,

        [Parameter(Mandatory = $true)]
        [string]$TempDir
    )

    $downloadDir = Join-Path $TempDir $Script:BuiltNugetsArtifactName
    Write-Message "Downloading built nugets artifact - $Script:BuiltNugetsArtifactName ..." -Level Info
    Invoke-ArtifactDownload -RunId $RunId -ArtifactName $Script:BuiltNugetsArtifactName -DownloadDirectory $downloadDir

    $builtNugetRidName = "$($Script:BuiltNugetsRidArtifactName)-$RID"
    Write-Message "Downloading rid specific built nugets artifact - $builtNugetRidName ..." -Level Info
    Invoke-ArtifactDownload -RunId $RunId -ArtifactName $builtNugetRidName -DownloadDirectory $downloadDir

    return $downloadDir
}

function Install-BuiltNugets {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$DownloadDir,

        [Parameter(Mandatory = $true)]
        [string]$NugetHiveDir
    )

    if (!$PSCmdlet.ShouldProcess($NugetHiveDir, "Copying built nugets")) {
        return
    }

    # Remove and recreate the target directory to ensure clean state
    if (Test-Path $NugetHiveDir) {
        Write-Message "Removing existing nuget directory: $NugetHiveDir" -Level Verbose
        if ($PSCmdlet.ShouldProcess($NugetHiveDir, "Remove existing directory")) {
            Remove-Item $NugetHiveDir -Recurse -Force -ErrorAction Stop
        }
    }

    if ($PSCmdlet.ShouldProcess($NugetHiveDir, "Create directory")) {
        New-Item -ItemType Directory -Path $NugetHiveDir -Force -ErrorAction Stop | Out-Null
    }

    Write-Message "Copying nugets from $DownloadDir to $NugetHiveDir" -Level Verbose

    # Copy all .nupkg files from the artifact directory to the target directory
    try {
        $nupkgFiles = Get-ChildItem -Path $DownloadDir -Filter "*.nupkg" -Recurse

        if ($nupkgFiles.Count -eq 0) {
            Write-Message "No .nupkg files found in downloaded artifact" -Level Warning
            return
        }

        foreach ($file in $nupkgFiles) {
            if ($PSCmdlet.ShouldProcess($file.FullName, "Copy to $NugetHiveDir")) {
                Copy-Item $file.FullName -Destination $NugetHiveDir -ErrorAction Stop
            }
        }

        Write-Message "Successfully installed nuget packages to: $NugetHiveDir" -Level Verbose
        Write-Message "NuGet packages successfully installed to: $NugetHiveDir" -Level Success
    }
    catch {
        Write-Message "Failed to copy nuget artifact files: $($_.Exception.Message)" -Level Error
        throw
    }
}

# Function to download Aspire CLI artifact
function Get-AspireCliFromArtifact {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$RunId,

        [Parameter(Mandatory = $true)]
        [string]$RID,

        [Parameter(Mandatory = $true)]
        [string]$TempDir
    )

    $cliArchiveName = "$($Script:CliArchiveArtifactNamePrefix)-$RID"
    $downloadDir = Join-Path $TempDir "cli"
    Write-Message "Downloading CLI from GitHub - $cliArchiveName ..." -Level Info

    Invoke-ArtifactDownload -RunId $RunId -ArtifactName $cliArchiveName -DownloadDirectory $downloadDir

    return $downloadDir
}

function Test-InstallerMode {
    return $InstallMode -eq 'WinGet' -or $InstallMode -eq 'Homebrew'
}

function Test-ScriptManagesCliPath {
    return $InstallMode -eq 'Archive' -or ($InstallMode -eq 'Tool' -and $script:InstallPathExplicit)
}

function Get-InstallerArtifactName {
    switch ($InstallMode) {
        'WinGet' { return $Script:WinGetManifestArtifactName }
        'Homebrew' { return $Script:HomebrewCaskArtifactName }
        default { throw "Install mode '$InstallMode' does not use an installer artifact." }
    }
}

function Get-InstallerArchiveRids {
    switch ($InstallMode) {
        'WinGet' { return @('win-x64', 'win-arm64') }
        'Homebrew' { return @('osx-arm64', 'osx-x64') }
        default { throw "Install mode '$InstallMode' does not use native installer archives." }
    }
}

function Get-InstallerArtifacts {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$RunId,

        [Parameter(Mandatory = $true)]
        [string]$TempDir
    )

    $installerArtifactName = Get-InstallerArtifactName
    $installerArtifactDir = Join-Path $TempDir "installer-$($InstallMode.ToLowerInvariant())"
    $archiveRoot = Join-Path $TempDir "installer-native-archives"

    Invoke-ArtifactDownload -RunId $RunId -ArtifactName $installerArtifactName -DownloadDirectory $installerArtifactDir

    foreach ($rid in Get-InstallerArchiveRids) {
        Invoke-ArtifactDownload -RunId $RunId -ArtifactName "$($Script:CliArchiveArtifactNamePrefix)-$rid" -DownloadDirectory $archiveRoot
    }

    return [pscustomobject]@{
        ArtifactDir = $installerArtifactDir
        ArchiveRoot = $archiveRoot
    }
}

function Find-InstallerDogfoodScript {
    param(
        [Parameter(Mandatory = $true)]
        [string]$ArtifactDir
    )

    $scriptName = switch ($InstallMode) {
        'WinGet' { 'dogfood.ps1' }
        'Homebrew' { 'dogfood.sh' }
        default { throw "Install mode '$InstallMode' does not use a dogfood script." }
    }

    $companionPattern = switch ($InstallMode) {
        'WinGet' { '*.installer.yaml' }
        'Homebrew' { 'aspire.rb' }
        default { throw "Install mode '$InstallMode' does not use a dogfood script." }
    }

    $matchedItems = @(
        Get-ChildItem -Path $ArtifactDir -File -Recurse -Filter $scriptName -ErrorAction SilentlyContinue |
            Where-Object {
                Get-ChildItem -Path $_.Directory.FullName -File -Filter $companionPattern -ErrorAction SilentlyContinue |
                    Select-Object -First 1
            } |
            Sort-Object FullName
    )

    if ($matchedItems.Count -eq 0) {
        throw "Could not find $scriptName co-located with $companionPattern under: $ArtifactDir"
    }

    if ($matchedItems.Count -gt 1) {
        $matchList = ($matchedItems | ForEach-Object { "  $($_.FullName)" }) -join [Environment]::NewLine
        throw "Found multiple $scriptName files co-located with $companionPattern under ${ArtifactDir}:$([Environment]::NewLine)$matchList"
    }

    return $matchedItems[0].FullName
}

function Install-AspireCliWithInstallerArtifact {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$ArtifactDir,

        [Parameter(Mandatory = $true)]
        [string]$ArchiveRoot
    )

    switch ($InstallMode) {
        'WinGet' {
            $dogfoodScript = if ($WhatIfPreference -and -not (Test-Path $ArtifactDir)) {
                Join-Path $ArtifactDir 'dogfood.ps1'
            } else {
                Find-InstallerDogfoodScript -ArtifactDir $ArtifactDir
            }
            $command = @('pwsh', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $dogfoodScript, '-ArchiveRoot', $ArchiveRoot)
            if ($Force) {
                $command += '-Force'
            }

            if ($PSCmdlet.ShouldProcess($dogfoodScript, "Install Aspire CLI with WinGet artifact: $($command -join ' ')")) {
                & $command[0] $command[1..($command.Length - 1)]
                if ($LASTEXITCODE -ne 0) {
                    throw "WinGet dogfood installer failed with exit code $LASTEXITCODE"
                }
            }
            break
        }
        'Homebrew' {
            $dogfoodScript = if ($WhatIfPreference -and -not (Test-Path $ArtifactDir)) {
                Join-Path $ArtifactDir 'dogfood.sh'
            } else {
                Find-InstallerDogfoodScript -ArtifactDir $ArtifactDir
            }
            $command = @('bash', $dogfoodScript, '--archive-root', $ArchiveRoot)
            if ($PSCmdlet.ShouldProcess($dogfoodScript, "Install Aspire CLI with Homebrew artifact: $($command -join ' ')")) {
                & $command[0] $command[1..($command.Length - 1)]
                if ($LASTEXITCODE -ne 0) {
                    throw "Homebrew dogfood installer failed with exit code $LASTEXITCODE"
                }
            }
            break
        }
        default {
            throw "Unsupported installer mode: $InstallMode"
        }
    }
}

function Test-InstallerModeEnvironment {
    if ($WhatIfPreference) {
        return
    }

    switch ($InstallMode) {
        'WinGet' {
            if ($Script:HostOS -ne 'win') {
                throw "-InstallMode WinGet can only be executed on Windows. Use -WhatIf to preview downloads from another OS."
            }
            if (-not (Get-Command pwsh -ErrorAction SilentlyContinue)) {
                throw "-InstallMode WinGet requires PowerShell (pwsh) to run the WinGet dogfood installer."
            }
            if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
                throw "-InstallMode WinGet requires WinGet to install the generated manifest artifact."
            }
        }
        'Homebrew' {
            if ($Script:HostOS -ne 'osx') {
                throw "-InstallMode Homebrew can only be executed on macOS. Use -WhatIf to preview downloads from another OS."
            }
            if (-not (Get-Command brew -ErrorAction SilentlyContinue)) {
                throw "-InstallMode Homebrew requires Homebrew (brew) to install the generated cask artifact."
            }
        }
    }
}

# Writes the PR-source install-source sidecar (.aspire-install.json) next to
# the installed binary. Under -WhatIf, prints the target path and skips the
# write so a real user's sidecar is never overwritten by a describe pass.
# Authorship contract: docs/specs/install-sources.md.
function Write-PRSourceSidecar {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$InstallPrefix,

        [Parameter(Mandatory = $true)]
        [int]$PRNumber
    )

    $sidecarDir = Join-Path (Join-Path (Join-Path $InstallPrefix "dogfood") "pr-$PRNumber") "bin"
    $sidecarPath = Join-Path $sidecarDir '.aspire-install.json'
    $sidecarContent = "{""source"":""pr""}`n"

    if ($PSCmdlet.ShouldProcess($sidecarPath, "Write source sidecar")) {
        [System.IO.Directory]::CreateDirectory($sidecarDir) | Out-Null
        [System.IO.File]::WriteAllText($sidecarPath, $sidecarContent)
    }
    else {
        Write-Host "What if: Source sidecar would be written to: $sidecarPath"
    }
}

# Function to install downloaded Aspire CLI
function Install-AspireCliFromDownload {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$DownloadDir,

        [Parameter(Mandatory = $true)]
        [string]$CliBinDir
    )

    if (!$PSCmdlet.ShouldProcess($CliBinDir, "Installing Aspire CLI to $CliBinDir")) {
        # Honor the -WhatIf / dry-run contract: describe-but-do-not-do. Emit the
        # install path as an informational message that tests can parse, instead of
        # touching the filesystem.
        $binaryName = if ($Script:HostOS -eq 'win') { 'aspire.exe' } else { 'aspire' }
        $binaryPath = Join-Path $CliBinDir $binaryName
        Write-Host "What if: Aspire CLI binary would be installed to: $binaryPath"
        return
    }

    $cliFiles = Get-ChildItem -Path $DownloadDir -File -Recurse | Where-Object { $_.Name -match "^$Script:AspireCliArtifactNamePrefix-.*\.(tar\.gz|zip)$" }

    if ($cliFiles.Count -eq 0) {
        Write-Message "No CLI archive found. Expected a single $(${Script:AspireCliArtifactNamePrefix})-*.tar.gz or $(${Script:AspireCliArtifactNamePrefix})-*.zip file in artifact root: $DownloadDir" -Level Error
        Write-Message "Candidate files present (root only):" -Level Info
        Get-ChildItem -Path $DownloadDir -File -Recurse | Select-Object -First 20 | ForEach-Object { Write-Message "  $($_.Name)" -Level Info }
        throw "CLI archive not found"
    }
    elseif ($cliFiles.Count -gt 1) {
        Write-Message "Multiple CLI archives found (expected exactly one):" -Level Error
        $cliFiles | ForEach-Object { Write-Message "  $($_.FullName)" -Level Error }
        throw "Multiple CLI archives found"
    }

    $cliArchivePath = $cliFiles[0].FullName

    # Install the archive
    Expand-AspireCliArchive -ArchiveFile $cliArchivePath -DestinationPath $CliBinDir

    # Check which aspire executable exists and set the path accordingly
    $aspireExePath = Join-Path $CliBinDir "aspire.exe"
    $aspirePath = Join-Path $CliBinDir "aspire"

    if (Test-Path $aspireExePath) {
        $cliPath = $aspireExePath
    }
    elseif (Test-Path $aspirePath) {
        $cliPath = $aspirePath
    }
    else {
        throw "Neither aspire.exe nor aspire executable found in $CliBinDir"
    }

    Write-Message "Aspire CLI successfully installed to: $cliPath" -Level Success
}

# Function to install a raw 'dotnet build' / 'dotnet publish' CLI binary tree.
# Used by the auto-detect raw-build branch of Start-InstallFromLocalDir to bypass the
# archive (.tar.gz/.zip) search & extraction. Searches recursively under $SourceDir for
# 'aspire' or 'aspire.exe' and copies the containing directory's files into $CliBinDir.
function Install-AspireCliFromLocalBinary {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$SourceDir,

        [Parameter(Mandatory = $true)]
        [string]$CliBinDir
    )

    if (!$PSCmdlet.ShouldProcess($CliBinDir, "Installing raw Aspire CLI binary tree from $SourceDir")) {
        return
    }

    $exeFiles = Get-ChildItem -Path $SourceDir -File -Recurse -ErrorAction SilentlyContinue |
        Where-Object { $_.Name -eq "aspire" -or $_.Name -eq "aspire.exe" } |
        Sort-Object FullName

    if ($exeFiles.Count -eq 0) {
        Write-Message "No 'aspire' or 'aspire.exe' executable found in: $SourceDir" -Level Error
        Write-Message "Expected raw 'dotnet build' or 'dotnet publish' output containing the aspire executable." -Level Info
        Get-ChildItem -Path $SourceDir -File -Recurse -ErrorAction SilentlyContinue |
            Select-Object -First 25 |
            ForEach-Object { Write-Message "  $($_.FullName)" -Level Info }
        throw "aspire executable not found"
    }

    $exeFile = $null
    if ($exeFiles.Count -eq 1) {
        $exeFile = $exeFiles[0]
    }
    else {
        # When multiple matches exist (e.g. both build and publish outputs are present),
        # prefer the 'publish' directory because it carries the full set of runtime deps.
        $exeFile = $exeFiles | Where-Object { $_.FullName -match '[\\/]publish[\\/]' } | Select-Object -First 1
        if (-not $exeFile) {
            Write-Message "Multiple aspire executables found under $SourceDir (specify a more precise -LocalDir):" -Level Error
            $exeFiles | ForEach-Object { Write-Message "  $($_.FullName)" -Level Error }
            throw "Multiple aspire executables found"
        }
        Write-Message "Multiple aspire executables found; preferring publish output: $($exeFile.FullName)" -Level Verbose
    }

    $exeDir = $exeFile.Directory.FullName
    Write-Message "Installing raw CLI binary tree from: $exeDir" -Level Verbose

    if (-not (Test-Path $CliBinDir -PathType Container)) {
        Write-Message "Creating install directory: $CliBinDir" -Level Verbose
        New-Item -ItemType Directory -Path $CliBinDir -Force | Out-Null
    }

    # Copy the contents of the exe's directory (binary + runtime deps + config) into the install dir.
    Copy-Item -Path (Join-Path $exeDir '*') -Destination $CliBinDir -Recurse -Force

    $installedExe = Join-Path $CliBinDir $exeFile.Name
    Write-Message "Aspire CLI successfully installed from raw build to: $installedExe" -Level Success
}

# Main function to install from a local directory of pre-built artifacts
function Start-InstallFromLocalDir {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$LocalDirPath
    )

    if (-not (Test-Path $LocalDirPath -PathType Container)) {
        Write-Message "Local directory does not exist: $LocalDirPath" -Level Error
        throw "Local directory not found"
    }

    Write-Message "Installing from local directory: $LocalDirPath" -Level Info

    # Set installation paths.
    # PR-source installs are isolated under <prefix>/dogfood/pr-<N>/bin so they don't
    # collide with the script-source prefix or with other PR installs. Hives remain shared
    # under <prefix>/hives/<label>/packages.
    $cliBinDir = if ($PRNumber -gt 0) {
        Join-Path (Join-Path (Join-Path $resolvedInstallPrefix "dogfood") "pr-$PRNumber") "bin"
    } else {
        Join-Path $resolvedInstallPrefix "bin"
    }
    $resolvedHiveLabel = if ($HiveLabel) {
        $HiveLabel
    } else {
        # Auto-detect PR identity from .nupkg filenames (e.g. "13.4.0-pr.16820.g3703c5c4")
        # so PR-built packages land in the same hive the CLI's CliExecutionContext.Channel
        # resolves to ("pr-<N>"). Falls back to "local" for true local-dev builds.
        $detectedLabel = "local"
        try {
            $detectedSuffix = Get-VersionSuffixFromPackages -DownloadDir $LocalDirPath
            if ($detectedSuffix -match '^pr\.(\d+)\.[0-9a-g]+$') {
                $detectedLabel = "pr-$($Matches[1])"
            }
        }
        catch {
            # No PR-style packages in the local dir; keep "local".
        }
        $detectedLabel
    }
    $nugetHiveDir = Join-Path $resolvedInstallPrefix "hives" $resolvedHiveLabel "packages"

    Write-Message "Using hive label: $resolvedHiveLabel" -Level Info

    $rid = Get-RuntimeIdentifier $OS $Architecture

    # Install CLI from local directory: auto-detect archive vs. raw 'dotnet build'/'dotnet publish' output.
    if ($HiveOnly) {
        Write-Message "Skipping CLI installation due to -HiveOnly flag" -Level Info
    } elseif ($InstallMode -eq 'Tool') {
        Write-Message "Skipping CLI archive lookup in local directory (install mode: Tool)" -Level Verbose
    } elseif (Test-InstallerMode) {
        Install-AspireCliWithInstallerArtifact -ArtifactDir $LocalDirPath -ArchiveRoot $LocalDirPath
    } else {
        $archiveMatch = Get-ChildItem -Path $LocalDirPath -File -Recurse -ErrorAction SilentlyContinue |
            Where-Object { $_.Name -match "^$Script:AspireCliArtifactNamePrefix-.*\.(tar\.gz|zip)$" } |
            Select-Object -First 1

        if ($archiveMatch) {
            Install-AspireCliFromDownload -DownloadDir $LocalDirPath -CliBinDir $cliBinDir
        }
        else {
            $rawExe = Get-ChildItem -Path $LocalDirPath -File -Recurse -ErrorAction SilentlyContinue |
                Where-Object { $_.Name -eq "aspire" -or $_.Name -eq "aspire.exe" } |
                Select-Object -First 1
            if ($rawExe) {
                Write-Message "No CLI archive found; detected raw aspire executable at: $($rawExe.FullName) (raw-build flow)" -Level Verbose
                Install-AspireCliFromLocalBinary -SourceDir $LocalDirPath -CliBinDir $cliBinDir
            }
            else {
                Write-Message "No CLI archive ($Script:AspireCliArtifactNamePrefix-*.tar.gz or .zip) and no 'aspire'/'aspire.exe' executable found in: $LocalDirPath" -Level Error
                Write-Message "Expected either a published CLI archive or a 'dotnet build'/'dotnet publish' output directory." -Level Info
                Get-ChildItem -Path $LocalDirPath -File -Recurse -ErrorAction SilentlyContinue |
                    Select-Object -First 25 |
                    ForEach-Object { Write-Message "  $($_.FullName)" -Level Info }
                throw "CLI archive or aspire executable not found"
            }
        }
    }

    # Populate the hive from the local directory. In tool mode this gives `aspire
    # new` the PR/local Aspire.AppHost.Sdk + Aspire.Hosting + Aspire.ProjectTemplates
    # so the generated project can build against the dogfood build.
    Install-BuiltNugets -DownloadDir $LocalDirPath -NugetHiveDir $nugetHiveDir

    # Extract and print the version suffix from packages
    try {
        $versionSuffix = Get-VersionSuffixFromPackages -DownloadDir $LocalDirPath
        Write-Message "Package version suffix: $versionSuffix" -Level Info
    }
    catch {
        Write-Message "Could not extract version suffix from local packages: $($_.Exception.Message)" -Level Warning
    }

    # In tool mode, install/update the dotnet tool from the populated hive (durable
    # `--add-source` for any future `dotnet tool update`).
    if (-not $HiveOnly -and $InstallMode -eq 'Tool') {
        $toolPath = if ($script:InstallPathExplicit) { $cliBinDir } else { $null }
        Install-AspireCliTool -HiveDir $nugetHiveDir -ToolPath $toolPath
    }

    # PR installs from archives get a sidecar; --local-dir installs are unmanaged,
    # and dotnet-tool packages embed their own source=dotnet-tool sidecar.
    if (-not $HiveOnly -and $InstallMode -eq 'Archive' -and $PRNumber -gt 0) {
        Write-PRSourceSidecar -InstallPrefix $resolvedInstallPrefix -PRNumber $PRNumber
    }

    # Update PATH environment variables
    if (-not $HiveOnly) {
        if (Test-ScriptManagesCliPath) {
            if ($SkipPath) {
                Write-Message "Skipping PATH configuration due to -SkipPath flag" -Level Info
            } else {
                Update-PathEnvironment -CliBinDir $cliBinDir
            }
        }
    }
}

# Main function to download and install from PR or workflow run ID
function Start-DownloadAndInstall {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$TempDir
    )

    if ($WorkflowRunId) {
        # When workflow ID is provided, use it directly
        if ($PRNumber -gt 0) {
            Write-Message "Starting download and installation for PR #$PRNumber with workflow run ID: $WorkflowRunId" -Level Info
        } else {
            Write-Message "Starting download and installation for workflow run ID: $WorkflowRunId" -Level Info
        }
        $runId = $WorkflowRunId.ToString()
    }
    else {
        # When only PR number is provided, find the workflow run
        Write-Message "Starting download and installation for PR #$PRNumber" -Level Info

        # Get the PR head SHA
        $headSha = Get-PRHeadSHA -PRNumber $PRNumber

        # Find the workflow run
        $runId = Find-WorkflowRun -HeadSHA $headSha
    }

    Write-Message "Using workflow run https://github.com/$Script:Repository/actions/runs/$runId" -Level Info

    # Set installation paths.
    # PR-source installs are isolated under <prefix>/dogfood/pr-<N>/bin so they don't
    # collide with the script-source prefix or with other PR installs. Hives remain shared
    # under <prefix>/hives/<label>/packages.
    $cliBinDir = if ($PRNumber -gt 0) {
        Join-Path (Join-Path (Join-Path $resolvedInstallPrefix "dogfood") "pr-$PRNumber") "bin"
    } else {
        Join-Path $resolvedInstallPrefix "bin"
    }
    $resolvedHiveLabel = if ($HiveLabel) {
        $HiveLabel
    } elseif ($PRNumber -gt 0) {
        "pr-$PRNumber"
    } else {
        # The installed CLI's identity (CliExecutionContext.Channel) is baked at build
        # time via AspireCliChannel — one of pr-<N>/staging/daily/local. There is no
        # 'run-<id>' channel, so packages dropped into hives/run-<id>/packages would
        # be invisible to the CLI. Reject early with actionable guidance instead of
        # silently producing an unusable layout.
        throw "Cannot determine hive label from -WorkflowRunId alone. The installed CLI's package channel is baked at build time (pr-<N>/staging/daily/local) and will not look in a 'run-<id>' hive. Re-run with -PRNumber <N> (preferred) or -HiveLabel <label> matching the CLI's baked AspireCliChannel."
    }
    $nugetHiveDir = Join-Path $resolvedInstallPrefix "hives" $resolvedHiveLabel "packages"

    $rid = Get-RuntimeIdentifier $OS $Architecture

    # First, download artifacts
    if ($HiveOnly) {
        Write-Message "Skipping CLI download due to -HiveOnly flag" -Level Info
    } elseif ($InstallMode -eq 'Tool') {
        Write-Message "Skipping CLI native archive download (install mode: Tool)" -Level Verbose
    } elseif (Test-InstallerMode) {
        $installerArtifacts = Get-InstallerArtifacts -RunId $runId -TempDir $TempDir
    } else {
        $cliDownloadDir = Get-AspireCliFromArtifact -RunId $runId -RID $rid -TempDir $TempDir
    }
    # Both modes need the cross-platform built-nugets (for the hive: Aspire.Hosting,
    # Aspire.AppHost.Sdk, Aspire.ProjectTemplates, ...) and the RID-specific one
    # (CLI archive in archive mode, or Aspire.Cli.<rid> tool pack in tool mode).
    # Get-BuiltNugets fetches both into the same temp directory.
    $nugetDownloadDir = Get-BuiltNugets -RunId $runId -RID $rid -TempDir $TempDir

    # Extract and print the version suffix from downloaded packages
    try {
        $versionSuffix = Get-VersionSuffixFromPackages -DownloadDir $nugetDownloadDir
        Write-Message "Package version suffix: $versionSuffix" -Level Info
    }
    catch {
        Write-Message "Could not extract version suffix from downloaded packages: $($_.Exception.Message)" -Level Warning
    }

    # Download VS Code extension if not skipped
    $extensionDownloadDir = $null
    if (-not $SkipExtension) {
        $extensionDownloadDir = Get-AspireExtensionFromArtifact -RunId $runId -TempDir $TempDir
    } else {
        Write-Message "Skipping VS Code extension download due to -SkipExtension flag" -Level Info
    }

    # Then, install artifacts
    Write-Message "Installing artifacts..." -Level Info
    if ($HiveOnly) {
        Write-Message "Skipping CLI installation due to -HiveOnly flag" -Level Info
    } elseif ($InstallMode -eq 'Tool') {
        Write-Message "Skipping CLI archive installation (install mode: Tool)" -Level Verbose
    } elseif (Test-InstallerMode) {
        Install-AspireCliWithInstallerArtifact -ArtifactDir $installerArtifacts.ArtifactDir -ArchiveRoot $installerArtifacts.ArchiveRoot
    } else {
        Install-AspireCliFromDownload -DownloadDir $cliDownloadDir -CliBinDir $cliBinDir
    }
    # Populate the PR hive with both cross-platform and RID-specific nupkgs.
    # In tool mode the hive is what `aspire new` discovers so it picks the PR
    # version of Aspire.AppHost.Sdk / Aspire.Hosting / Aspire.ProjectTemplates.
    Install-BuiltNugets -DownloadDir $nugetDownloadDir -NugetHiveDir $nugetHiveDir

    # In tool mode, install/update the dotnet tool from the populated hive.
    # Using the hive directory (rather than the temp download dir) gives `dotnet
    # tool install --add-source` a durable source, which matters if the user later
    # runs `dotnet tool update Aspire.Cli` against the same `-ToolPath`.
    if (-not $HiveOnly -and $InstallMode -eq 'Tool') {
        $toolPath = if ($script:InstallPathExplicit) { $cliBinDir } else { $null }
        Install-AspireCliTool -HiveDir $nugetHiveDir -ToolPath $toolPath
    }

    # Install VS Code extension if downloaded
    if ($extensionDownloadDir -and -not $SkipExtension) {
        if (Test-VSCodeCLIDependency -UseInsiders:$UseInsiders) {
            Install-AspireExtensionFromDownload -DownloadDir $extensionDownloadDir -UseInsiders:$UseInsiders
        }
    }

    if (-not $HiveOnly -and $InstallMode -eq 'Archive' -and $PRNumber -gt 0) {
        Write-PRSourceSidecar -InstallPrefix $resolvedInstallPrefix -PRNumber $PRNumber
    }

    # Update PATH environment variables
    if (-not $HiveOnly) {
        if (Test-ScriptManagesCliPath) {
            if ($SkipPath) {
                Write-Message "Skipping PATH configuration due to -SkipPath flag" -Level Info
            } else {
                Update-PathEnvironment -CliBinDir $cliBinDir
            }
        }
    }

    # Print PATH activation hint for PR installs.
    # Uses Write-Host so the hint is visible on the host stream (not stderr) in normal output.
    # Printed in success path (after install completes) and also under -WhatIf.
    # The OS path separator is used so the line is valid on both Windows (;) and Unix (:).
    # The new-PATH expression is emitted with double quotes so PowerShell expands `$env:PATH`
    # when the user pastes the line into their profile — single quotes would assign the literal
    # text "$env:PATH" and clobber the existing PATH.
    if (-not $HiveOnly -and $PRNumber -gt 0 -and (Test-ScriptManagesCliPath)) {
        $pathSep = [System.IO.Path]::PathSeparator
        Write-Host "Add to your shell profile: `$env:PATH = `"$cliBinDir$pathSep`$env:PATH`";"
    }
}

# =============================================================================
# Main Execution
# =============================================================================

try {
    # Show help if requested
    if ($Help) {
        Write-Message @"
Aspire CLI PR Download Script

DESCRIPTION:
    Downloads and installs the Aspire CLI from a specific pull request's latest successful build.
    Automatically detects the current platform and architecture.

Usage:
    get-aspire-cli-pr.ps1 <PRNumber> [OPTIONS]
    get-aspire-cli-pr.ps1 -WorkflowRunId <RunId> [OPTIONS]
    get-aspire-cli-pr.ps1 -LocalDir <Path> [OPTIONS]
    iex "& { `$(irm <url>/get-aspire-cli-pr.ps1) } <PRNumber> [OPTIONS]"

OPTIONS:
    -PRNumber <int>         Pull request number (required, positional)
    -WorkflowRunId <long>   Workflow run ID to download from (optional)
    -LocalDir <string>      Use pre-downloaded artifacts from a local directory
    -HiveLabel <string>     Override the NuGet hive label
    -InstallPath <string>   Directory prefix to install
    -InstallMode <string>   How to install the CLI: 'Archive' (default), 'Tool', 'WinGet', or 'Homebrew'
    -Force                  Tool mode updates the existing tool; WinGet mode allows replacing an existing install
    -OS <string>            Override OS detection (win, linux, linux-musl, osx)
    -Architecture <string>  Override architecture detection (x64, arm64)
    -HiveOnly               For installs from archives only: only install NuGet packages to the hive, skip CLI download
    -SkipExtension          Skip VS Code extension download and installation
    -UseInsiders            Install extension to VS Code Insiders instead of VS Code
    -SkipPath               Do not add the install path to PATH environment variable
    -KeepArchive            Keep downloaded archive files after installation
    -Help                   Show this help information
"@ -Level Info
        if ($InvokedFromFile) { exit 0 } else { return 0 }
    }

    # Validate PRNumber is provided when not showing help or using --local-dir
    if ($LocalDir) {
        if ($PRNumber -gt 0 -or $WorkflowRunId -gt 0) {
            Write-Message "Error: -LocalDir is mutually exclusive with -PRNumber and -WorkflowRunId" -Level Error
            if ($InvokedFromFile) { exit 1 } else { return 1 }
        }
    } elseif ($PRNumber -le 0 -and $WorkflowRunId -le 0) {
        Write-Message "Error: PRNumber, -WorkflowRunId, or -LocalDir parameter is required" -Level Error
        Write-Message "Use -Help for usage information" -Level Info
        if ($InvokedFromFile) { exit 1 } else { return 1 }
    }

    # Set host OS for PATH environment updates
    $script:HostOS = Get-OperatingSystem

    $InstallMode = switch ($InstallMode.ToLowerInvariant()) {
        'archive' { 'Archive' }
        'tool' { 'Tool' }
        'winget' { 'WinGet' }
        'homebrew' { 'Homebrew' }
    }

    if ($HiveOnly -and $InstallMode -ne 'Archive') {
        Write-Message "Error: -HiveOnly cannot be combined with -InstallMode ${InstallMode}: -HiveOnly skips the CLI install, but this install mode installs Aspire CLI through a package or tool manager." -Level Error
        Write-Message "Drop one of the two flags. All install modes populate the hive." -Level Info
        if ($InvokedFromFile) { exit 1 } else { return 1 }
    }

    if ($InstallMode -ne 'Tool' -and $InstallMode -ne 'WinGet' -and $Force) {
        Write-Message "Error: -Force can only be combined with -InstallMode Tool or -InstallMode WinGet." -Level Error
        Write-Message "Use -InstallMode Tool/WinGet with -Force, or drop -Force." -Level Info
        if ($InvokedFromFile) { exit 1 } else { return 1 }
    }

    $script:InstallPathExplicit = $PSBoundParameters.ContainsKey('InstallPath') -and -not [string]::IsNullOrWhiteSpace($InstallPath)
    if ($InstallMode -eq 'Tool') {
        Test-ToolModeRuntimeIdentifier
        Test-DotnetDependency
    }

    if (Test-InstallerMode) {
        Test-InstallerModeEnvironment
    }

    # Check gh dependency (not needed for -LocalDir mode)
    if (-not $LocalDir) {
        Test-GitHubCLIDependency
    }

    # Set default install prefix if not provided
    $resolvedInstallPrefix = Get-InstallPrefix -InstallPrefix $InstallPath

    # Create a temporary directory for downloads
    $tempDir = New-TempDirectory -Prefix "aspire-cli-pr-download"

    try {
        # Download and install from PR/workflow run ID, or install from local directory
        if ($LocalDir) {
            Start-InstallFromLocalDir -LocalDirPath $LocalDir
        } else {
            Start-DownloadAndInstall -TempDir $tempDir
        }

        $exitCode = 0
    }
    finally {
        # Clean up temporary directory
        Remove-TempDirectory -TempDir $tempDir
    }
}
catch {
    Write-Message "Error: $($_.Exception.Message)" -Level Error
    if ($VerbosePreference -ne 'SilentlyContinue') {
        Write-Message "StackTrace: $($_.Exception.StackTrace)" -Level Verbose
    }
    $exitCode = 1
}

if ($InvokedFromFile) {
    exit $exitCode
}
else {
    if ($exitCode -ne 0) {
        return $exitCode
    }
}