Python_Manager.ps1

<# 
Python Manager v1.0
Windows 10/11, Windows PowerShell 5.x, PowerShell 7.x
#>

Set-StrictMode -Version 2.0
$ErrorActionPreference = 'Stop'

$Script:ProjectRoot = if (-not [string]::IsNullOrWhiteSpace($PSScriptRoot)) {
    $PSScriptRoot
} else {
    Split-Path -Parent $MyInvocation.MyCommand.Path
}

#region UI

function Write-Color {
    param(
        [Parameter(Mandatory = $true)][string]$Text,
        [ConsoleColor]$Color = [ConsoleColor]::Gray,
        [switch]$NoNewLine
    )

    if ($NoNewLine) {
        Write-Host $Text -ForegroundColor $Color -NoNewline
    } else {
        Write-Host $Text -ForegroundColor $Color
    }
}

function Write-Result {
    param(
        [ValidateSet('OK', 'WARNING', 'ERROR', 'RUN', 'TIMEOUT', 'CANCELLED')][string]$Status,
        [string]$Message
    )

    $color = [ConsoleColor]::Green
    if ($Status -eq 'WARNING') { $color = [ConsoleColor]::Yellow }
    if ($Status -eq 'ERROR') { $color = [ConsoleColor]::Red }
    if ($Status -eq 'RUN') { $color = [ConsoleColor]::Cyan }
    if ($Status -eq 'TIMEOUT') { $color = [ConsoleColor]::Yellow }
    if ($Status -eq 'CANCELLED') { $color = [ConsoleColor]::DarkYellow }

    Write-Color ("[ {0} ] " -f $Status) $color -NoNewLine
    Write-Host $Message
}

function ShowDivider {
    param(
        [string]$Char = '=',
        [ConsoleColor]$Color = [ConsoleColor]::Cyan
    )

    Write-Color ($Char * 56) $Color
}

function ShowSectionTitle {
    param([Parameter(Mandatory = $true)][string]$Text)

    Write-Host ''
    Write-Color ('  ' + $Text) Cyan
    Write-Color ('  ' + ('-' * $Text.Length)) DarkCyan
    Write-Host ''
}

function Write-InfoLine {
    param(
        [Parameter(Mandatory = $true)][string]$Label,
        [object]$Value,
        [ConsoleColor]$ValueColor = [ConsoleColor]::Gray
    )

    Write-Color ('  {0,-30}' -f ($Label + ':')) DarkCyan -NoNewLine
    Write-Color (Format-Value $Value) $ValueColor
}

function Write-StatusLine {
    param(
        [Parameter(Mandatory = $true)][string]$Label,
        [Parameter(Mandatory = $true)][string]$Status,
        [string]$Location,
        [ConsoleColor]$StatusColor = [ConsoleColor]::Gray
    )

    Write-Color ('  {0,-18}' -f ($Label + ':')) DarkCyan -NoNewLine
    Write-Color ('{0,-14}' -f (Format-Value $Status)) $StatusColor -NoNewLine
    Write-Color (Format-Value $Location) Gray
}

function Write-MenuItem {
    param(
        [Parameter(Mandatory = $true)][string]$Number,
        [Parameter(Mandatory = $true)][string]$Title,
        [string]$Description
    )

    Write-Color ('[{0}] ' -f $Number) Yellow -NoNewLine
    Write-Color $Title White
    if (-not [string]::IsNullOrWhiteSpace($Description)) {
        Write-Color ('    ' + $Description) DarkGray
    }
    Write-Host ''
}

function Get-StateColor {
    param([string]$Value)

    if ($Value -eq 'OK') { return [ConsoleColor]::Green }
    if ($Value -eq 'ERROR') { return [ConsoleColor]::Red }
    if ($Value -eq 'RUN') { return [ConsoleColor]::Cyan }
    if ($Value -eq 'TIMEOUT') { return [ConsoleColor]::Yellow }
    if ($Value -eq 'CANCELLED') { return [ConsoleColor]::DarkYellow }
    if ($Value -like 'WARNING*') { return [ConsoleColor]::Yellow }
    return [ConsoleColor]::Gray
}

function Pause {
    Write-Host ''
    Write-Color 'Нажмите Enter для продолжения...' DarkGray -NoNewLine
    [void][Console]::ReadLine()
}

function ShowHeader {
    Clear-Host
    ShowDivider '=' Cyan
    Write-Color '                 Python Manager v1.0' Yellow
    ShowDivider '=' Cyan
    Write-Host ''
}

function Format-Value {
    param([object]$Value)

    if ($null -eq $Value) { return 'Не найдено' }
    if ([string]::IsNullOrWhiteSpace([string]$Value)) { return 'Не найдено' }
    return [string]$Value
}

function Get-VenvStatusText {
    param([Parameter(Mandatory = $true)][object]$Venv)

    if ($Venv.Healthy) { return 'OK' }
    if ($Venv.Exists) { return 'WARNING - требуется пересоздание' }
    return 'ERROR - требуется создание'
}

function Show-BrokenVenvExplanation {
    param(
        [Parameter(Mandatory = $true)][object]$Venv,
        [string]$Context = 'Install'
    )

    Write-Result 'WARNING' 'Обнаружено поврежденное или перенесенное виртуальное окружение.'
    Write-Host ''
    Write-Color '  Причина:' Cyan
    if ($Venv.Exists) {
        Write-Color '  venv был создан с Python, которого нет на этом компьютере.' Gray
        if (-not [string]::IsNullOrWhiteSpace($Venv.Home)) {
            Write-InfoLine 'Старый Python' $Venv.Home
        }
        if (-not [string]::IsNullOrWhiteSpace($Venv.Executable)) {
            Write-InfoLine 'Старый executable' $Venv.Executable
        }
    } else {
        Write-Color '  Папка project venv отсутствует.' Gray
    }

    Write-Host ''
    Write-Color '  Что делать:' Cyan
    Write-Color '  Пересоздать только папку venv на основе рабочего Python этого компьютера.' Gray
    Write-Color '  Системный Python и файлы проекта удалять не нужно.' Gray
    Write-Color '  После успешного пересоздания venv можно установить зависимости проекта.' Gray
    Write-Color '  До исправления venv установка зависимостей не должна начинаться.' Gray
    if ($Context -eq 'FirstRun') {
        Write-Color '  Мастер сначала покажет план, а изменения выполнит только после подтверждения.' DarkGray
    }
}

function ShowStatus {
    $python = FindPython
    $pip = FindPip
    $pyLauncher = FindPyLauncher
    $winget = FindWinget
    $pathInfo = FindPath
    $venv = FindVenv
    $internet = Test-Internet
    $admin = Test-Administrator

    ShowSectionTitle 'Система'
    Write-InfoLine 'Windows' ([Environment]::OSVersion.VersionString)
    Write-InfoLine 'OS architecture' ([Runtime.InteropServices.RuntimeInformation]::OSArchitecture)
    Write-InfoLine 'Process architecture' ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture)
    Write-InfoLine 'PowerShell' $PSVersionTable.PSVersion

    ShowSectionTitle 'Основной Python'
    Write-InfoLine 'Версия' $python.DefaultVersion
    Write-InfoLine 'Полный путь' $python.DefaultPath
    Write-InfoLine 'Тип' $python.DefaultType
    Write-InfoLine 'Источник' $python.DefaultSource
    Write-InfoLine 'Причина выбора' $python.DefaultReason

    ShowSectionTitle 'Pip'
    Write-InfoLine 'Версия' $pip.Version
    Write-InfoLine 'Команда' $pip.Path
    Write-InfoLine 'Python для pip' $pip.PythonPath

    ShowSectionTitle 'Py Launcher'
    Write-InfoLine 'Полный путь' $pyLauncher.Path

    ShowSectionTitle 'Найденные версии Python'
    Write-InfoLine 'Количество' $python.All.Count Yellow
    Write-Color '  Список найденных версий:' DarkCyan
    if ($python.All.Count -eq 0) {
        Write-Color '  Не найдено' Red
    } else {
        foreach ($item in $python.All) {
            Write-Color ('  {0,-12}' -f (Format-Value $item.Version)) Green -NoNewLine
            Write-Color ('{0}  [{1}; {2}]' -f (Format-Value $item.Path), (Format-Value $item.Type), (Format-Value $item.Source)) Gray
            if (-not $item.IsUsable -or $item.IsVenv -or $item.IsStoreAlias) {
                Write-Color ('    reason: {0}' -f (Format-Value $item.Reason)) DarkGray
            }
        }
    }

    ShowSectionTitle 'Системное состояние'
    $wingetState = Format-Bool $winget.Found
    $internetState = Format-Bool $internet
    $adminState = Format-Bool $admin
    $venvState = if ($venv.Exists -and -not $venv.Healthy) { 'WARNING' } else { Format-Bool $venv.Available }
    $userName = [Environment]::UserName
    Write-StatusLine 'Winget' $wingetState $winget.Path (Get-StateColor $wingetState)
    Write-StatusLine 'Internet' $internetState 'python.org, pypi.org, files.pythonhosted.org' (Get-StateColor $internetState)
    Write-StatusLine 'Administrator' $adminState $userName (Get-StateColor $adminState)
    Write-StatusLine 'PATH' $pathInfo.Status 'User: HKCU:\Environment\Path' (Get-StateColor $pathInfo.Status)
    Write-Color '  PATH Machine:     ' DarkCyan -NoNewLine
    Write-Color 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\Path' Gray
    Write-Color '  PATH Process:     ' DarkCyan -NoNewLine
    Write-Color 'Текущий процесс PowerShell/CMD; участвует в поиске Python' Gray
    $venvLocation = $venv.DefaultPath
    if ($venv.Exists -and -not $venv.Healthy) { $venvLocation = 'требуется пересоздание project venv' }
    Write-StatusLine 'venv' $venvState $venvLocation (Get-StateColor $venvState)
    Write-Host ''
    ShowDivider '=' Cyan
    Write-Host ''
}

function ShowMenu {
    Write-Color '  Главное меню' Cyan
    Write-Color '  -----------' DarkCyan
    Write-Host ''
    Write-MenuItem '1' 'Первый запуск на новом ПК' 'Пошаговая диагностика Python, venv и зависимостей проекта.'
    Write-MenuItem '2' 'Проверка' 'Диагностика без изменений системы.'
    Write-MenuItem '3' 'Обслуживание' 'Backup, очистка, обновление pip и финальная проверка.'
    Write-MenuItem '4' 'Зависимости' 'Пакеты pip, requirements.txt и виртуальные окружения.'
    Write-MenuItem '5' 'Переустановка Python' 'Отдельное действие на случай проблем с установленным Python.'
    Write-MenuItem '0' 'Выход' 'Закрыть Python Manager.'
    Write-Color 'Выбор: ' Yellow -NoNewLine
    return [Console]::ReadLine()
}

function ShowDependencyMenu {
    ShowHeader
    Write-Color '  Зависимости Python' Cyan
    Write-Color '  ------------------' DarkCyan
    Write-Host ''
    Write-Color '  Здесь находятся действия с pip-пакетами и окружениями проекта.' Gray
    Write-Color '  Если вы не уверены, сначала сделайте Backup, потом обновляйте или восстанавливайте.' Gray
    ShowDependencyStatus
    ShowLearningLibrariesStatus
    Write-Host ''
    Write-MenuItem '1' 'Обновить установленные пакеты' 'Проверяет pip-пакеты и обновляет устаревшие версии.'
    Write-MenuItem '2' 'Список пакетов для сохранения (Backup)' 'Показывает текущие пакеты через pip freeze. Систему не меняет.'
    Write-MenuItem '3' 'Восстановить пакеты из requirements.txt (Restore)' 'Устанавливает пакеты из файла requirements.txt.'
    Write-MenuItem '4' 'Виртуальное окружение проекта (venv)' 'Отдельная папка с пакетами для проекта, без смешивания с системным Python.'
    Write-MenuItem '5' 'Установить Python в PATH' 'Добавляет python.exe и Scripts, чтобы команды python и pip работали из консоли.'
    Write-MenuItem '6' 'Учебные библиотеки' 'Requests, Flask, Telegram Bot API и PyQt6: статус и установка в venv.'
    Write-MenuItem '0' 'Назад' 'Вернуться в главное меню.'
    Write-Color 'Выбор: ' Yellow -NoNewLine
    return [Console]::ReadLine()
}

function ShowLearningLibrariesMenu {
    ShowHeader
    Write-Color '  Учебные библиотеки Python' Cyan
    Write-Color '  -------------------------' DarkCyan
    Write-Host ''
    Write-Color '  Эти библиотеки не входят в стандартный Python.' Gray
    Write-Color '  Менеджер проверяет и устанавливает их в проектное виртуальное окружение venv.' Gray
    Write-Color '  Если venv ещё нет, он будет создан перед установкой.' Gray
    ShowLearningLibrariesStatus
    Write-Host ''
    Write-MenuItem '1' 'Установить Requests' 'Запросы в интернет, HTTP и работа с API.'
    Write-MenuItem '2' 'Установить Flask' 'Мини-фреймворк для создания веб-сайтов и API.'
    Write-MenuItem '3' 'Установить Telegram Bot API' 'Пакет python-telegram-bot для разработки Telegram-ботов.'
    Write-MenuItem '4' 'Установить PyQt6' 'Библиотека для создания desktop-приложений с графическим интерфейсом.'
    Write-MenuItem '5' 'Установить все' 'Поставить все учебные библиотеки в venv.'
    Write-MenuItem '0' 'Назад' 'Вернуться в меню зависимостей.'
    Write-Color 'Выбор: ' Yellow -NoNewLine
    return [Console]::ReadLine()
}

function ShowVenvMenu {
    ShowHeader
    Write-Color '  Виртуальное окружение проекта (venv)' Cyan
    Write-Color '  -----------------------------------' DarkCyan
    Write-Host ''
    Write-Color '  venv - это отдельная папка Python для проекта.' Gray
    Write-Color '  Пакеты внутри venv не засоряют основной Python Windows.' Gray
    Write-Color '  Обычный порядок: создать venv, затем импортировать requirements.txt или ставить пакеты pip.' Gray
    Write-Color '  Активация в PowerShell: .\venv\Scripts\Activate.ps1' DarkGray
    Write-Color '  Если запуск скриптов запрещён: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned' DarkGray
    ShowVenvStatus
    Write-Host ''
    Write-MenuItem '1' 'Создать venv' 'Создаёт отдельное окружение в текущей папке или по указанному пути.'
    Write-MenuItem '2' 'Удалить venv' 'Удаляет только папку виртуального окружения. Основной Python не трогает.'
    Write-MenuItem '3' 'Сохранить список пакетов в requirements.txt' 'Записывает установленные пакеты в файл requirements.txt.'
    Write-MenuItem '4' 'Установить пакеты из requirements.txt' 'Ставит пакеты из requirements.txt через pip install -r.'
    Write-MenuItem '0' 'Назад' 'Вернуться в меню зависимостей.'
    Write-Color 'Выбор: ' Yellow -NoNewLine
    return [Console]::ReadLine()
}

#endregion

#region Detection

function Format-Bool {
    param([bool]$Value)

    if ($Value) { return 'OK' }
    return 'ERROR'
}

function ConvertTo-CleanOutput {
    param([object[]]$Output)

    $clean = New-Object System.Collections.Generic.List[string]
    foreach ($line in @($Output)) {
        $text = [string]$line
        if ([string]::IsNullOrWhiteSpace($text)) { continue }

        $text = $text -replace '[\u0000-\u001F\u007F-\u009F]', ''
        $text = $text -replace '[\u2580-\u259F\u2800-\u28FF]', ''
        $text = $text.Trim()

        if ([string]::IsNullOrWhiteSpace($text)) { continue }
        if ($text -match '^[\|\-\\\/\s]+$') { continue }

        [void]$clean.Add($text)
    }

    return $clean.ToArray()
}

function Get-FriendlyWingetError {
    param([object[]]$Output)

    $clean = @(ConvertTo-CleanOutput -Output $Output)
    if ($clean.Count -eq 0) {
        return 'winget завершился с ошибкой, но не вернул читаемое сообщение.'
    }

    foreach ($line in $clean) {
        if ($line -match 'No applicable|No package|not found|already installed|newer version|failed|error|0x[0-9A-Fa-f]+') {
            return $line
        }
    }

    return ($clean | Select-Object -Last 1)
}

function Format-Elapsed {
    param([TimeSpan]$Duration)

    if ($Duration.TotalHours -ge 1) { return $Duration.ToString('hh\:mm\:ss') }
    return $Duration.ToString('mm\:ss')
}

function ConvertTo-NativeArgumentString {
    param([string[]]$Arguments = @())

    $quoted = New-Object System.Collections.Generic.List[string]
    foreach ($arg in $Arguments) {
        if ($null -eq $arg) { continue }
        $text = [string]$arg
        if ($text -match '[\s"]') {
            $text = '"' + ($text -replace '"', '\"') + '"'
        }
        [void]$quoted.Add($text)
    }
    return ($quoted -join ' ')
}

function Stop-ProcessTreeSafe {
    param([Parameter(Mandatory = $true)][int]$ProcessId)

    try {
        $children = @(Get-CimInstance Win32_Process -Filter ("ParentProcessId={0}" -f $ProcessId) -ErrorAction SilentlyContinue)
    } catch {
        $children = @()
        try { $children = @(Get-WmiObject Win32_Process -Filter ("ParentProcessId={0}" -f $ProcessId) -ErrorAction SilentlyContinue) } catch {}
    }

    foreach ($child in $children) {
        Stop-ProcessTreeSafe -ProcessId ([int]$child.ProcessId)
    }

    try {
        $target = Get-Process -Id $ProcessId -ErrorAction Stop
        if (-not $target.HasExited) { Stop-Process -Id $ProcessId -Force -ErrorAction Stop }
    } catch {
    }
}

function Invoke-Native {
    param(
        [Parameter(Mandatory = $true)][string]$FilePath,
        [string[]]$Arguments = @(),
        [string]$OperationName,
        [int]$TimeoutSeconds = 0,
        [int]$HeartbeatSeconds = 15,
        [switch]$Quiet
    )

    $output = @()
    $stdout = @()
    $stderr = @()
    $exitCode = 1
    $status = 'ERROR'
    $timedOut = $false
    $duration = [TimeSpan]::Zero

    try {
        $stopwatch = [Diagnostics.Stopwatch]::StartNew()
        $process = New-Object Diagnostics.Process
        $process.StartInfo = New-Object Diagnostics.ProcessStartInfo
        $process.StartInfo.FileName = $FilePath
        $process.StartInfo.Arguments = ConvertTo-NativeArgumentString -Arguments $Arguments
        $process.StartInfo.UseShellExecute = $false
        $process.StartInfo.RedirectStandardOutput = $true
        $process.StartInfo.RedirectStandardError = $true
        $process.StartInfo.CreateNoWindow = $true

        if (-not $Quiet) {
            $name = if ([string]::IsNullOrWhiteSpace($OperationName)) { (Split-Path -Leaf $FilePath) } else { $OperationName }
            Write-Result 'RUN' $name
        }

        [void]$process.Start()
        $stdoutTask = $process.StandardOutput.ReadToEndAsync()
        $stderrTask = $process.StandardError.ReadToEndAsync()
        $nextHeartbeat = [Math]::Max(1, $HeartbeatSeconds)

        while (-not $process.WaitForExit(1000)) {
            $elapsedSeconds = [int][Math]::Floor($stopwatch.Elapsed.TotalSeconds)
            if ($TimeoutSeconds -gt 0 -and $elapsedSeconds -ge $TimeoutSeconds) {
                $timedOut = $true
                Stop-ProcessTreeSafe -ProcessId $process.Id
                break
            }

            if (-not $Quiet -and $elapsedSeconds -ge $nextHeartbeat) {
                $name = if ([string]::IsNullOrWhiteSpace($OperationName)) { (Split-Path -Leaf $FilePath) } else { $OperationName }
                Write-Color ('  [{0}] {1}: процесс выполняется...' -f (Format-Elapsed $stopwatch.Elapsed), $name) Cyan
                $nextHeartbeat += [Math]::Max(1, $HeartbeatSeconds)
            }
        }

        if ($timedOut) {
            [void]$process.WaitForExit(5000)
        } else {
            $process.WaitForExit()
        }
        $stopwatch.Stop()
        $duration = $stopwatch.Elapsed
        $stdoutText = ''
        $stderrText = ''
        try {
            if ($stdoutTask.Wait(1000)) { $stdoutText = $stdoutTask.Result }
        } catch {}
        try {
            if ($stderrTask.Wait(1000)) { $stderrText = $stderrTask.Result }
        } catch {}
        if (-not [string]::IsNullOrEmpty($stdoutText)) { $stdout = @($stdoutText -split "`r?`n" | Where-Object { $_ -ne '' }) }
        if (-not [string]::IsNullOrEmpty($stderrText)) { $stderr = @($stderrText -split "`r?`n" | Where-Object { $_ -ne '' }) }
        $output = @($stdout + $stderr)
        $exitCode = if ($timedOut) { -1 } else { $process.ExitCode }
        if ($timedOut) {
            $status = 'TIMEOUT'
        } elseif ($exitCode -eq 0) {
            $status = 'SUCCESS'
        } else {
            $status = 'ERROR'
        }

        if (-not $Quiet -and ($status -eq 'TIMEOUT')) {
            Write-Result 'TIMEOUT' ('{0} остановлен по timeout {1} сек.' -f $OperationName, $TimeoutSeconds)
        }
    } catch {
        $output = @($_.Exception.Message)
        $stderr = @($_.Exception.Message)
        $exitCode = 1
        $status = 'ERROR'
    }

    return [pscustomobject]@{
        ExitCode = $exitCode
        Output = @($output | ForEach-Object { [string]$_ })
        StdOut = @($stdout | ForEach-Object { [string]$_ })
        StdErr = @($stderr | ForEach-Object { [string]$_ })
        Success = ($exitCode -eq 0)
        Status = $status
        TimedOut = $timedOut
        Duration = $duration
    }
}

function Get-CommandPath {
    param([Parameter(Mandatory = $true)][string]$Name)

    try {
        $command = Get-Command $Name -ErrorAction Stop | Select-Object -First 1
        return $command.Source
    } catch {
        return $null
    }
}

function Get-ObjectPropertyValue {
    param(
        [Parameter(Mandatory = $true)][object]$Object,
        [Parameter(Mandatory = $true)][string]$Name
    )

    $property = $Object.PSObject.Properties[$Name]
    if ($null -eq $property) { return $null }
    return $property.Value
}

function Test-PathSafe {
    param(
        [string]$Path,
        [switch]$Literal
    )

    if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
    try {
        if ($Literal) { return (Test-Path -LiteralPath $Path -ErrorAction Stop) }
        return (Test-Path $Path -ErrorAction Stop)
    } catch {
        return $false
    }
}

function Get-PythonVersionFromExecutable {
    param([Parameter(Mandatory = $true)][string]$Path)

    if (-not (Test-PathSafe -Path $Path -Literal)) { return $null }
    $result = Invoke-Native -FilePath $Path -Arguments @('--version') -Quiet -TimeoutSeconds 10
    $text = ($result.Output -join ' ').Trim()
    if ($text -match 'Python\s+([0-9]+(\.[0-9]+){1,3})') { return $matches[1] }
    return $null
}

function Normalize-PythonVersion {
    param([string]$Version)

    if ([string]::IsNullOrWhiteSpace($Version)) { return $null }
    $text = $Version.Trim()
    if ($text -match '^([0-9]+)\.([0-9]+)\.([0-9]+)(?:\.([0-9]+))?$') {
        $major = [int]$matches[1]
        $minor = [int]$matches[2]
        $patch = [int]$matches[3]

        if ($patch -ge 1000) {
            $patch = [int][Math]::Floor($patch / 1000)
        }

        return ('{0}.{1}.{2}' -f $major, $minor, $patch)
    }

    return $text
}

function Get-PythonVersionFromText {
    param([string]$Text)

    if ([string]::IsNullOrWhiteSpace($Text)) { return $null }
    if ($Text -match 'Python\s+([0-9]+(\.[0-9]+){1,3})') {
        return (Normalize-PythonVersion $matches[1])
    }
    if ($Text -match '([0-9]+(\.[0-9]+){1,3})') {
        return (Normalize-PythonVersion $matches[1])
    }
    return $null
}

function Get-VersionKey {
    param([string]$Version)

    $normalized = Normalize-PythonVersion $Version
    if ([string]::IsNullOrWhiteSpace($normalized)) { return [version]'0.0' }
    try { return [version]$normalized } catch { return [version]'0.0' }
}

function Get-PathEntries {
    $entries = New-Object System.Collections.Generic.List[string]

    foreach ($scope in @('Machine', 'User', 'Process')) {
        $value = [Environment]::GetEnvironmentVariable('Path', $scope)
        if (-not [string]::IsNullOrWhiteSpace($value)) {
            foreach ($entry in ($value -split ';')) {
                if (-not [string]::IsNullOrWhiteSpace($entry)) {
                    $expanded = [Environment]::ExpandEnvironmentVariables($entry.Trim())
                    if (-not [string]::IsNullOrWhiteSpace($expanded) -and -not $entries.Contains($expanded)) {
                        [void]$entries.Add($expanded)
                    }
                }
            }
        }
    }

    return $entries.ToArray()
}

function Get-PythonRuntimeInfo {
    param([Parameter(Mandatory = $true)][string]$Path)

    if (-not (Test-PathSafe -Path $Path -Literal)) { return $null }
    $code = 'import sys,platform; print("executable="+sys.executable); print("prefix="+sys.prefix); print("base_prefix="+getattr(sys,"base_prefix",sys.prefix)); print("arch="+platform.machine())'
    $result = Invoke-Native -FilePath $Path -Arguments @('-c', $code) -Quiet -TimeoutSeconds 10
    if (-not $result.Success) { return $null }

    $map = @{}
    foreach ($line in $result.Output) {
        if ($line -match '^([^=]+)=(.*)$') { $map[$matches[1]] = $matches[2] }
    }

    return [pscustomobject]@{
        Executable = $map['executable']
        Prefix = $map['prefix']
        BasePrefix = $map['base_prefix']
        Architecture = $map['arch']
    }
}

function Get-PythonCandidate {
    param(
        [Parameter(Mandatory = $true)][string]$Path,
        [Parameter(Mandatory = $true)][string]$Source
    )

    if (-not (Test-PathSafe -Path $Path -Literal)) { return $null }
    $resolved = (Resolve-Path -LiteralPath $Path).Path
    $lowerPath = $resolved.ToLowerInvariant()
    $projectVenvPath = (Join-Path $Script:ProjectRoot 'venv\Scripts\python.exe').ToLowerInvariant()
    $isStoreAlias = ($lowerPath -like '*\microsoft\windowsapps\python*.exe')
    $version = $null
    $runtime = $null
    if (-not $isStoreAlias) {
        $version = Get-PythonVersionFromExecutable -Path $resolved
        $runtime = Get-PythonRuntimeInfo -Path $resolved
    }
    $isVenvByPath = ($lowerPath -like '*\venv\scripts\python.exe') -or ($lowerPath -like '*\.venv\scripts\python.exe')
    $isVenvByRuntime = $false
    if ($runtime -and -not [string]::IsNullOrWhiteSpace($runtime.Prefix) -and -not [string]::IsNullOrWhiteSpace($runtime.BasePrefix)) {
        $isVenvByRuntime = ($runtime.Prefix -ne $runtime.BasePrefix)
    }
    $isVenv = $isVenvByPath -or $isVenvByRuntime
    $isProjectVenv = ($lowerPath -eq $projectVenvPath)
    $isThirdPartyVenv = ($isVenv -and -not $isProjectVenv)

    $type = 'Unknown'
    $usable = $false
    $reason = 'Кандидат не выбран автоматически.'
    if ($isStoreAlias) {
        $type = 'Microsoft Store alias'
        $reason = 'Store alias не считается установленным CPython.'
    } elseif ($isProjectVenv) {
        $type = 'Project venv'
        $reason = 'Проектный venv не используется как основной системный Python.'
    } elseif ($isThirdPartyVenv) {
        $type = 'Third-party venv'
        $reason = 'Сторонний venv не используется как основной системный Python.'
    } elseif ($Source -eq 'Registry') {
        $type = 'Installed CPython'
        $usable = (-not [string]::IsNullOrWhiteSpace($version))
        $reason = 'Установленный CPython из registry.'
    } elseif ($Source -eq 'PyLauncher') {
        $type = 'Py launcher target'
        $usable = (-not [string]::IsNullOrWhiteSpace($version))
        $reason = 'Цель py launcher после проверки executable.'
    } elseif ($Source -eq 'PATH' -or $Source -eq 'Default') {
        $type = 'PATH CPython'
        $usable = (-not [string]::IsNullOrWhiteSpace($version))
        $reason = 'CPython из PATH после исключения venv и alias.'
    } else {
        $usable = (-not [string]::IsNullOrWhiteSpace($version))
    }

    return [pscustomobject]@{
        Version = (Normalize-PythonVersion $version)
        Path = $resolved
        Source = $Source
        Type = $type
        Architecture = $(if ($runtime) { $runtime.Architecture } else { $null })
        IsVenv = $isVenv
        IsProjectVenv = $isProjectVenv
        IsThirdPartyVenv = $isThirdPartyVenv
        IsStoreAlias = $isStoreAlias
        IsUsable = $usable
        Reason = $reason
    }
}

function FindPythonInRegistry {
    $items = New-Object System.Collections.Generic.List[object]
    $roots = @(
        'HKLM:\SOFTWARE\Python\PythonCore',
        'HKLM:\SOFTWARE\WOW6432Node\Python\PythonCore',
        'HKCU:\SOFTWARE\Python\PythonCore'
    )

    foreach ($root in $roots) {
        if (-not (Test-PathSafe -Path $root)) { continue }
        foreach ($versionKey in (Get-ChildItem $root -ErrorAction SilentlyContinue)) {
            $installPathKey = Join-Path $versionKey.PSPath 'InstallPath'
            if (-not (Test-PathSafe -Path $installPathKey)) { continue }
            try {
                $installPathItem = Get-Item -Path $installPathKey -ErrorAction Stop
                $installPath = $installPathItem.GetValue('')
                if ([string]::IsNullOrWhiteSpace($installPath)) { $installPath = $installPathItem.GetValue('InstallPath') }
                if (-not [string]::IsNullOrWhiteSpace($installPath)) {
                    $exe = Join-Path $installPath 'python.exe'
                    if (Test-PathSafe -Path $exe -Literal) {
                        [void]$items.Add([pscustomobject]@{
                            Version = $versionKey.PSChildName
                            Path = (Resolve-Path -LiteralPath $exe).Path
                            Source = 'Registry'
                        })
                    }
                }
            } catch {
            }
        }
    }

    return $items.ToArray()
}

function FindPythonInPath {
    $items = New-Object System.Collections.Generic.List[object]
    foreach ($entry in (Get-PathEntries)) {
        foreach ($name in @('python.exe', 'python3.exe')) {
            $candidate = Join-Path $entry $name
            if (Test-PathSafe -Path $candidate -Literal) {
                $resolved = (Resolve-Path -LiteralPath $candidate).Path
                [void]$items.Add([pscustomobject]@{
                    Path = $resolved
                    Source = 'PATH'
                })
            }
        }
    }

    return $items.ToArray()
}

function FindPythonWithPyLauncher {
    $items = New-Object System.Collections.Generic.List[object]
    $py = FindPyLauncher
    if (-not $py.Found) { return $items.ToArray() }

    $result = Invoke-Native -FilePath $py.Path -Arguments @('-0p') -Quiet -TimeoutSeconds 10
    if (-not $result.Success) { return $items.ToArray() }

    foreach ($line in $result.Output) {
        if ($line -match '((?:[A-Za-z]:|\\\\)[^\r\n]*?python(?:3)?\.exe)') {
            [void]$items.Add([pscustomobject]@{
                Version = $null
                Path = $matches[1].Trim()
                Source = 'PyLauncher'
            })
        }
    }

    return $items.ToArray()
}

function FindPython {
    $items = New-Object System.Collections.Generic.List[object]
    foreach ($item in (FindPythonInRegistry)) { [void]$items.Add($item) }
    foreach ($item in (FindPythonWithPyLauncher)) { [void]$items.Add($item) }
    foreach ($item in (FindPythonInPath)) { [void]$items.Add($item) }

    $defaultPath = Get-CommandPath 'python.exe'
    if ($defaultPath) {
        [void]$items.Add([pscustomobject]@{
            Path = $defaultPath
            Source = 'Default'
        })
    }

    $sourcePriority = @{
        Registry = 0
        PyLauncher = 1
        PATH = 2
        Default = 3
    }
    $preferredByPath = @{}
    foreach ($item in @($items | Where-Object { -not [string]::IsNullOrWhiteSpace($_.Path) })) {
        try {
            $resolvedKey = (Resolve-Path -LiteralPath $item.Path -ErrorAction Stop).Path.ToLowerInvariant()
        } catch {
            $resolvedKey = $item.Path.ToLowerInvariant()
        }

        $newPriority = if ($sourcePriority.ContainsKey($item.Source)) { $sourcePriority[$item.Source] } else { 9 }
        if (-not $preferredByPath.ContainsKey($resolvedKey)) {
            $preferredByPath[$resolvedKey] = $item
        } else {
            $old = $preferredByPath[$resolvedKey]
            $oldPriority = if ($sourcePriority.ContainsKey($old.Source)) { $sourcePriority[$old.Source] } else { 9 }
            if ($newPriority -lt $oldPriority) { $preferredByPath[$resolvedKey] = $item }
        }
    }
    $preferredItems = @($preferredByPath.Values)

    $candidates = New-Object System.Collections.Generic.List[object]
    foreach ($item in $preferredItems) {
        $candidate = Get-PythonCandidate -Path $item.Path -Source $item.Source
        if ($candidate) { [void]$candidates.Add($candidate) }
    }

    $unique = @($candidates.ToArray() | Sort-Object Path -Unique)
    $default = $null
    $usable = @($unique | Where-Object { $_.IsUsable })
    if ($usable.Count -gt 0) {
        $default = $usable | Sort-Object `
            @{Expression = { if ($_.Source -eq 'Registry') { 0 } elseif ($_.Source -eq 'PyLauncher') { 1 } elseif ($_.Source -eq 'PATH') { 2 } elseif ($_.Source -eq 'Default') { 3 } else { 9 } }; Ascending = $true }, `
            @{Expression = { Get-VersionKey $_.Version }; Descending = $true }, `
            Path | Select-Object -First 1
    }

    return [pscustomobject]@{
        DefaultPath = $(if ($default) { $default.Path } else { $null })
        DefaultVersion = $(if ($default) { $default.Version } else { $null })
        DefaultType = $(if ($default) { $default.Type } else { $null })
        DefaultSource = $(if ($default) { $default.Source } else { $null })
        DefaultReason = $(if ($default) { $default.Reason } else { $null })
        All = @($unique | Sort-Object @{Expression = { Get-VersionKey $_.Version }; Descending = $true }, Path)
    }
}

function FindPip {
    $python = FindPython
    $pipPath = $null
    $version = $null
    $pythonPath = $python.DefaultPath

    if ($pythonPath) {
        $result = Invoke-Native -FilePath $pythonPath -Arguments @('-m', 'pip', '--version') -Quiet -TimeoutSeconds 20
        $text = ($result.Output -join ' ').Trim()
        if ($text -match 'pip\s+([^\s]+)') { $version = $matches[1] }
        if ($result.Success) { $pipPath = ('"{0}" -m pip' -f $pythonPath) }
    }

    return [pscustomobject]@{
        Path = $pipPath
        Version = $version
        PythonPath = $pythonPath
    }
}

function FindPyLauncher {
    $path = Get-CommandPath 'py.exe'
    return [pscustomobject]@{ Path = $path; Found = ($null -ne $path) }
}

function FindWinget {
    $path = Get-CommandPath 'winget.exe'
    return [pscustomobject]@{ Path = $path; Found = ($null -ne $path) }
}

function FindPath {
    $allEntries = @()
    foreach ($scope in @('Machine', 'User', 'Process')) {
        $value = [Environment]::GetEnvironmentVariable('Path', $scope)
        if ([string]::IsNullOrWhiteSpace($value)) { continue }
        foreach ($entry in ($value -split ';')) {
            $trimmed = $entry.Trim()
            if ([string]::IsNullOrWhiteSpace($trimmed)) { continue }
            $expanded = [Environment]::ExpandEnvironmentVariables($trimmed)
            $exists = Test-PathSafe -Path $expanded -Literal
            $allEntries += [pscustomobject]@{
                Scope = $scope
                Raw = $trimmed
                Expanded = $expanded
                Exists = $exists
            }
        }
    }

    $broken = @($allEntries | Where-Object { -not $_.Exists })
    $status = 'OK'
    if ($broken.Count -gt 0) { $status = ('WARNING ({0} битых записей)' -f $broken.Count) }

    return [pscustomobject]@{
        Status = $status
        Entries = @($allEntries)
        Broken = @($broken)
    }
}

function Get-VenvHealth {
    param([Parameter(Mandatory = $true)][string]$VenvPath)

    $pyvenvCfg = Join-Path $VenvPath 'pyvenv.cfg'
    $venvPython = Get-VenvPythonPath -VenvPath $VenvPath
    $exists = Test-PathSafe -Path $VenvPath -Literal
    $ready = $exists -and (Test-PathSafe -Path $pyvenvCfg -Literal) -and (Test-PathSafe -Path $venvPython -Literal)
    $healthy = $ready
    $reason = if ($exists) { 'venv найден.' } else { 'venv не найден.' }
    $venvHome = $null
    $executable = $null

    if ($exists -and -not $ready) {
        $healthy = $false
        $reason = 'Папка venv есть, но pyvenv.cfg или Scripts\python.exe отсутствует.'
    }

    if ($ready) {
        try {
            foreach ($line in (Get-Content -LiteralPath $pyvenvCfg -ErrorAction Stop)) {
                if ($line -match '^home\s*=\s*(.+)$') { $venvHome = $matches[1].Trim() }
                if ($line -match '^executable\s*=\s*(.+)$') { $executable = $matches[1].Trim() }
            }

            if (-not [string]::IsNullOrWhiteSpace($venvHome) -and -not (Test-PathSafe -Path $venvHome -Literal)) {
                $healthy = $false
                $reason = ('venv перенесен или поврежден: home не найден ({0}).' -f $venvHome)
            } elseif (-not [string]::IsNullOrWhiteSpace($executable) -and -not (Test-PathSafe -Path $executable -Literal)) {
                $healthy = $false
                $reason = ('venv перенесен или поврежден: executable не найден ({0}).' -f $executable)
            } else {
                $reason = 'venv выглядит здоровым.'
            }
        } catch {
            $healthy = $false
            $reason = $_.Exception.Message
        }
    }

    return [pscustomobject]@{
        Exists = $exists
        Ready = $ready
        Healthy = $healthy
        Reason = $reason
        Path = $VenvPath
        PythonPath = $venvPython
        Home = $venvHome
        Executable = $executable
    }
}

function FindVenv {
    $python = FindPython
    $available = $false
    if ($python.DefaultPath) {
        $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'venv', '--help') -Quiet -TimeoutSeconds 20
        $available = $result.Success
    }
    $defaultPath = Join-Path $Script:ProjectRoot 'venv'
    $health = Get-VenvHealth -VenvPath $defaultPath

    return [pscustomobject]@{
        Available = $available
        DefaultPath = $defaultPath
        Exists = $health.Exists
        Ready = $health.Ready
        Healthy = $health.Healthy
        Reason = $health.Reason
    }
}

function Test-Administrator {
    try {
        $identity = [Security.Principal.WindowsIdentity]::GetCurrent()
        $principal = New-Object Security.Principal.WindowsPrincipal($identity)
        return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
    } catch {
        return $false
    }
}

function Test-Internet {
    $targets = @(
        'https://www.python.org/',
        'https://pypi.org/',
        'https://files.pythonhosted.org/'
    )

    foreach ($target in $targets) {
        try {
            $request = [System.Net.WebRequest]::Create($target)
            $request.Method = 'HEAD'
            $request.Timeout = 5000
            $response = $request.GetResponse()
            $response.Close()
        } catch {
            return $false
        }
    }

    return $true
}

function Get-NetworkDiagnostics {
    $items = New-Object System.Collections.Generic.List[object]
    foreach ($target in @('https://www.python.org/', 'https://pypi.org/', 'https://files.pythonhosted.org/')) {
        $ok = $true
        $message = 'OK'
        try {
            $request = [System.Net.WebRequest]::Create($target)
            $request.Method = 'HEAD'
            $request.Timeout = 5000
            $response = $request.GetResponse()
            $response.Close()
        } catch {
            $ok = $false
            $message = $_.Exception.Message
        }

        [void]$items.Add([pscustomobject]@{
            Url = $target
            OK = $ok
            Message = $message
        })
    }

    return $items.ToArray()
}

function Get-ProxyDiagnostics {
    $names = @('HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'REQUESTS_CA_BUNDLE', 'SSL_CERT_FILE')
    $items = New-Object System.Collections.Generic.List[object]
    foreach ($name in $names) {
        $value = [Environment]::GetEnvironmentVariable($name, 'Process')
        if ([string]::IsNullOrWhiteSpace($value)) { $value = [Environment]::GetEnvironmentVariable($name, 'User') }
        if ([string]::IsNullOrWhiteSpace($value)) { $value = [Environment]::GetEnvironmentVariable($name, 'Machine') }
        [void]$items.Add([pscustomobject]@{
            Name = $name
            Value = $(if ([string]::IsNullOrWhiteSpace($value)) { 'не задано' } else { $value })
        })
    }

    return $items.ToArray()
}

function Get-PipConfigDiagnostics {
    $python = FindPython
    if (-not $python.DefaultPath) { return @('Python не найден, pip config недоступен.') }
    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'pip', 'config', 'list') -Quiet -TimeoutSeconds 30
    if (-not $result.Success) { return @('pip config list недоступен: ' + (($result.Output | Select-Object -Last 1) -join ' ')) }
    if ($result.Output.Count -eq 0) { return @('pip config пуст.') }
    return @($result.Output)
}

function Test-PythonModule {
    param(
        [Parameter(Mandatory = $true)][string]$PythonPath,
        [Parameter(Mandatory = $true)][string]$ModuleName
    )

    $result = Invoke-Native -FilePath $PythonPath -Arguments @('-c', "import $ModuleName") -Quiet -TimeoutSeconds 20
    return $result.Success
}

#endregion

#region Service

function Invoke-Step {
    param(
        [int]$Number,
        [int]$Total,
        [string]$Name,
        [scriptblock]$Action
    )

    Write-Host ''
    Write-Color ("[{0}/{1}] {2}" -f $Number, $Total, $Name) Cyan
    try {
        & $Action
        Write-Result 'OK' $Name
        return $true
    } catch {
        Write-Result 'ERROR' ($Name + ': ' + $_.Exception.Message)
        return $false
    }
}

function Assert-Operation {
    param(
        [Parameter(Mandatory = $true)][bool]$Result,
        [Parameter(Mandatory = $true)][string]$Message
    )

    if (-not $Result) { throw $Message }
}

function BackupPackages {
    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден, pip freeze недоступен.'
        return $false
    }

    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'pip', 'freeze') -OperationName 'pip freeze' -TimeoutSeconds 120
    if ($result.Success) {
        if ($result.Output.Count -gt 0) {
            $result.Output | ForEach-Object { Write-Host $_ }
        } else {
            Write-Host 'Установленные pip-пакеты не найдены.'
        }
        Write-Result 'OK' 'Backup пакетов выведен на экран.'
        return $true
    }

    Write-Result 'ERROR' (($result.Output -join ' ').Trim())
    return $false
}

function Get-UninstallRegistryItems {
    $paths = @(
        'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall',
        'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall',
        'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'
    )

    $items = New-Object System.Collections.Generic.List[object]
    foreach ($path in $paths) {
        if (-not (Test-PathSafe -Path $path)) { continue }
        foreach ($key in (Get-ChildItem $path -ErrorAction SilentlyContinue)) {
            try {
                $prop = Get-ItemProperty $key.PSPath -ErrorAction Stop
                $displayName = Get-ObjectPropertyValue -Object $prop -Name 'DisplayName'
                if ([string]::IsNullOrWhiteSpace($displayName)) { continue }
                if ($displayName -match '^Python\s+[0-9]' -or $displayName -match '^Python Launcher') {
                    [void]$items.Add([pscustomobject]@{
                        DisplayName = $displayName
                        DisplayVersion = Get-ObjectPropertyValue -Object $prop -Name 'DisplayVersion'
                        UninstallString = Get-ObjectPropertyValue -Object $prop -Name 'UninstallString'
                        QuietUninstallString = Get-ObjectPropertyValue -Object $prop -Name 'QuietUninstallString'
                        KeyPath = $key.PSPath
                    })
                }
            } catch {
            }
        }
    }

    return $items.ToArray()
}

function Get-WingetPythonPackageFromLine {
    param([string]$Line)

    if ([string]::IsNullOrWhiteSpace($Line)) { return $null }
    $idMatch = [regex]::Match($Line, '(?<!\S)(Python\.Python\.3(?:\.[0-9]+)?)(?!\S)')
    if (-not $idMatch.Success) { return $null }

    $id = $idMatch.Groups[1].Value
    if ($id -eq 'Python.PythonInstallManager' -or $id -eq 'Python.Launcher') { return $null }
    if ($id -notmatch '^Python\.Python\.3(?:\.[0-9]+)?$') { return $null }

    $tail = $Line.Substring($idMatch.Index + $id.Length)
    $version = $null
    if ($tail -match '(?<![0-9])([0-9]+(?:\.[0-9]+){1,3})(?![0-9])') {
        $version = Normalize-PythonVersion $matches[1]
    } elseif ($id -match '^Python\.Python\.([0-9]+(?:\.[0-9]+)?)$') {
        $version = Normalize-PythonVersion $matches[1]
        if ($version -match '^[0-9]+\.[0-9]+$') { $version = ($version + '.0') }
    }

    if ([string]::IsNullOrWhiteSpace($version)) { return $null }
    $name = $Line.Substring(0, $idMatch.Index).Trim()
    if ([string]::IsNullOrWhiteSpace($name)) { $name = $id }

    return [pscustomobject]@{
        Id = $id
        Version = $version
        Name = $name
    }
}

function Get-InstalledPythonProducts {
    $items = New-Object System.Collections.Generic.List[object]
    $componentPattern = '(?i)\b(Add to Path|Core Interpreter|Development Libraries|Documentation|pip Bootstrap|Executable installer|Test Suite|Utility Scripts|Tcl/Tk Support|PrependPath)\b'
    foreach ($py in (FindPython).All) {
        if (-not $py.IsUsable -or $py.IsVenv -or $py.IsStoreAlias) { continue }
        [void]$items.Add([pscustomobject]@{
            Version = (Normalize-PythonVersion $py.Version)
            Path = $py.Path
            Source = $py.Source
            DisplayName = ('Python {0}' -f (Normalize-PythonVersion $py.Version))
            WingetId = $null
            UninstallString = $null
            Type = $py.Type
            IsVenv = $py.IsVenv
            IsStoreAlias = $py.IsStoreAlias
            IsUsable = $py.IsUsable
        })
    }

    foreach ($reg in (Get-UninstallRegistryItems)) {
        if ($reg.DisplayName -match '^Python Launcher' -or $reg.DisplayName -match 'Install Manager') { continue }
        if ($reg.DisplayName -match $componentPattern) { continue }
        $version = Get-PythonVersionFromText $reg.DisplayName
        if ([string]::IsNullOrWhiteSpace($version)) { $version = Normalize-PythonVersion $reg.DisplayVersion }
        $quiet = $reg.QuietUninstallString
        if ([string]::IsNullOrWhiteSpace($quiet)) { $quiet = $reg.UninstallString }
        [void]$items.Add([pscustomobject]@{
            Version = $version
            Path = $null
            Source = 'Registry'
            DisplayName = $reg.DisplayName
            WingetId = $null
            UninstallString = $quiet
            Type = 'Installed CPython'
            IsVenv = $false
            IsStoreAlias = $false
            IsUsable = $true
        })
    }

    $winget = FindWinget
    if ($winget.Found) {
        $list = Invoke-Native -FilePath $winget.Path -Arguments @('list', 'Python') -OperationName 'winget list Python' -TimeoutSeconds 120
        foreach ($line in $list.Output) {
            $package = Get-WingetPythonPackageFromLine -Line $line
            if ($package) {
                [void]$items.Add([pscustomobject]@{
                    Version = $package.Version
                    Path = $null
                    Source = 'Winget'
                    DisplayName = $package.Name
                    WingetId = $package.Id
                    UninstallString = $null
                    Type = 'Installed CPython'
                    IsVenv = $false
                    IsStoreAlias = $false
                    IsUsable = $true
                })
            }
        }
    }

    return @($items.ToArray() | Where-Object { -not [string]::IsNullOrWhiteSpace($_.Version) } | Sort-Object DisplayName, Version -Unique)
}

function Get-InstalledLatestPythonVersion {
    $products = @(Get-InstalledPythonProducts)
    if ($products.Count -eq 0) { return $null }

    $latest = $products | Sort-Object @{Expression = { Get-VersionKey $_.Version }; Descending = $true } | Select-Object -First 1
    return (Normalize-PythonVersion $latest.Version)
}

function Invoke-UninstallString {
    param([Parameter(Mandatory = $true)][string]$CommandLine)

    $cmd = $CommandLine.Trim()
    if ([string]::IsNullOrWhiteSpace($cmd)) { return $false }

    if ($cmd -match 'MsiExec\.exe.*\{([^}]+)\}') {
        $productCode = '{' + $matches[1] + '}'
        $result = Invoke-Native -FilePath 'msiexec.exe' -Arguments @('/x', $productCode, '/qn', '/norestart') -OperationName 'msiexec uninstall Python' -TimeoutSeconds 900
        return $result.Success
    }

    if ($cmd.StartsWith('"')) {
        $end = $cmd.IndexOf('"', 1)
        if ($end -gt 1) {
            $exe = $cmd.Substring(1, $end - 1)
            $argsText = $cmd.Substring($end + 1).Trim()
            $args = @()
            if (-not [string]::IsNullOrWhiteSpace($argsText)) { $args = @($argsText -split '\s+') }
            if (($args -notcontains '/quiet') -and ($args -notcontains '/qn')) { $args += '/quiet' }
            if ($args -notcontains '/norestart') { $args += '/norestart' }
        $result = Invoke-Native -FilePath $exe -Arguments $args -OperationName 'uninstall Python' -TimeoutSeconds 900
            return $result.Success
        }
    }

    $parts = @($cmd -split '\s+')
    if ($parts.Count -eq 0) { return $false }
    $file = $parts[0]
    $args2 = @()
    if ($parts.Count -gt 1) { $args2 = $parts[1..($parts.Count - 1)] }
    if (($args2 -notcontains '/quiet') -and ($args2 -notcontains '/qn')) { $args2 += '/quiet' }
    if ($args2 -notcontains '/norestart') { $args2 += '/norestart' }
    $result2 = Invoke-Native -FilePath $file -Arguments $args2 -OperationName 'uninstall Python' -TimeoutSeconds 900
    return $result2.Success
}

function RemoveOldPython {
    $products = @(Get-InstalledPythonProducts | Where-Object { $_.IsUsable -and -not $_.IsVenv -and -not $_.IsStoreAlias -and ($_.DisplayName -notmatch 'Launcher|Install Manager') })
    if ($products.Count -eq 0) {
        Write-Result 'WARNING' 'Установленные версии Python не найдены.'
        return $true
    }

    $latestVersion = Normalize-PythonVersion (($products | Sort-Object @{Expression = { Get-VersionKey $_.Version }; Descending = $true } | Select-Object -First 1).Version)
    $oldProducts = @($products | Where-Object { (Get-VersionKey $_.Version) -lt (Get-VersionKey $latestVersion) })
    $currentProducts = @($products | Where-Object { (Get-VersionKey $_.Version) -eq (Get-VersionKey $latestVersion) })

    Write-Host ('Последняя установленная версия: {0}' -f $latestVersion)
    foreach ($product in $currentProducts) {
        Write-Result 'OK' ('Не удаляется актуальная версия: {0} {1}' -f $product.DisplayName, (Normalize-PythonVersion $product.Version))
    }

    if ($oldProducts.Count -eq 0) {
        Write-Result 'OK' 'Старые версии Python не найдены.'
        return $true
    }

    $winget = FindWinget
    foreach ($product in $oldProducts) {
        Write-Host ''
        Write-Result 'WARNING' ('Найдена старая версия: {0} {1}' -f $product.DisplayName, $product.Version)
        Write-InfoLine 'Путь' $product.Path
        Write-InfoLine 'Источник' $product.Source
        Write-InfoLine 'Тип' $product.Type
        Write-InfoLine 'IsVenv' $product.IsVenv
        Write-InfoLine 'IsStoreAlias' $product.IsStoreAlias
        Write-InfoLine 'IsUsable' $product.IsUsable
        Write-InfoLine 'Winget ID' $product.WingetId
        Write-InfoLine 'Причина' ('Есть более новая найденная версия: {0}' -f $latestVersion)
        if ($product.IsVenv -or $product.IsStoreAlias -or -not $product.IsUsable -or ($product.DisplayName -match 'Launcher|Install Manager')) {
            Write-Result 'ERROR' 'Удаление заблокировано: запись не является установленным CPython.'
            continue
        }
        Write-Color '  Старый Python может использоваться другим проектом. Автоматическое удаление запрещено.' Yellow
        Write-Color '  Чтобы удалить именно эту запись, введите DELETE. Любой другой ввод пропустит удаление.' DarkGray
        Write-Color '  Подтверждение: ' DarkCyan -NoNewLine
        $confirm = [Console]::ReadLine()
        if ($confirm -ne 'DELETE') {
            Write-Result 'WARNING' ('Удаление пропущено: {0}' -f $product.DisplayName)
            continue
        }

        $removed = $false

        if ($winget.Found -and -not [string]::IsNullOrWhiteSpace($product.WingetId)) {
            $result = Invoke-Native -FilePath $winget.Path -Arguments @('uninstall', '--id', $product.WingetId, '--silent', '--accept-source-agreements') -OperationName ('winget uninstall {0}' -f $product.WingetId) -TimeoutSeconds 900
            $removed = $result.Success
        }

        if (-not $removed -and -not [string]::IsNullOrWhiteSpace($product.UninstallString)) {
            $removed = Invoke-UninstallString -CommandLine $product.UninstallString
        }

        if ($removed) {
            Write-Result 'OK' ('Удалено: {0}' -f $product.DisplayName)
        } else {
            Write-Result 'WARNING' ('Не удалось автоматически удалить: {0}' -f $product.DisplayName)
        }
    }

    return $true
}

function Get-CleanPathValue {
    param([string]$Value)

    if ([string]::IsNullOrWhiteSpace($Value)) { return '' }
    $clean = New-Object System.Collections.Generic.List[string]
    foreach ($entry in ($Value -split ';')) {
        $trimmed = $entry.Trim()
        if ([string]::IsNullOrWhiteSpace($trimmed)) { continue }
        $expanded = [Environment]::ExpandEnvironmentVariables($trimmed)
        if ((Test-PathSafe -Path $expanded -Literal) -and -not $clean.Contains($trimmed)) {
            [void]$clean.Add($trimmed)
        }
    }
    return ($clean -join ';')
}

function RepairPath {
    $found = $false
    foreach ($scope in @('User', 'Machine')) {
        if ($scope -eq 'Machine' -and -not (Test-Administrator)) {
            Write-Result 'WARNING' 'Machine PATH пропущен: требуются права администратора.'
            continue
        }

        $current = [Environment]::GetEnvironmentVariable('Path', $scope)
        $clean = Get-CleanPathValue -Value $current
        if ($clean -ne $current) {
            $found = $true
            Write-Result 'WARNING' ('PATH {0}: найдены записи, которые сейчас недоступны. Автоочистка отключена.' -f $scope)
            Write-Color '  Проверьте их вручную: путь может быть сетевым, временно отключенным диском или SDK.' DarkGray
        }
    }

    if (-not $found) {
        Write-Result 'OK' 'Битые записи PATH не найдены.'
    }

    return $true
}

function Add-PathEntries {
    param(
        [Parameter(Mandatory = $true)][string[]]$Entries,
        [ValidateSet('User', 'Machine')][string]$Scope = 'User'
    )

    if ($Scope -eq 'Machine' -and -not (Test-Administrator)) {
        Write-Result 'ERROR' 'Machine PATH требует права администратора.'
        return $false
    }

    $current = [Environment]::GetEnvironmentVariable('Path', $Scope)
    $parts = New-Object System.Collections.Generic.List[string]
    if (-not [string]::IsNullOrWhiteSpace($current)) {
        foreach ($entry in ($current -split ';')) {
            $trimmed = $entry.Trim()
            if (-not [string]::IsNullOrWhiteSpace($trimmed) -and -not $parts.Contains($trimmed)) {
                [void]$parts.Add($trimmed)
            }
        }
    }

    $changed = $false
    foreach ($entry in $Entries) {
        if ([string]::IsNullOrWhiteSpace($entry)) { continue }
        $resolved = $entry.Trim()
        if (-not (Test-PathSafe -Path $resolved -Literal)) {
            Write-Result 'WARNING' ('PATH запись пропущена, папка не найдена: {0}' -f $resolved)
            continue
        }

        $exists = $false
        foreach ($part in $parts) {
            if ([string]::Equals([Environment]::ExpandEnvironmentVariables($part), $resolved, [StringComparison]::OrdinalIgnoreCase)) {
                $exists = $true
                break
            }
        }

        if ($exists) {
            Write-Result 'OK' ('PATH уже содержит: {0}' -f $resolved)
        } else {
            [void]$parts.Add($resolved)
            $changed = $true
            Write-Result 'OK' ('PATH добавлен: {0}' -f $resolved)
        }
    }

    if ($changed) {
        $newValue = ($parts.ToArray() -join ';')
        Write-Result 'WARNING' ('Будет изменен {0} PATH.' -f $Scope)
        foreach ($entry in $Entries) {
            Write-InfoLine 'Добавить' $entry
        }
        Write-Color '  Для записи PATH введите APPLY. Любой другой ввод отменит изменение.' DarkGray
        Write-Color '  Подтверждение: ' DarkCyan -NoNewLine
        $confirm = [Console]::ReadLine()
        if ($confirm -ne 'APPLY') {
            Write-Result 'WARNING' 'PATH оставлен без изменений.'
            return $false
        }
        [Environment]::SetEnvironmentVariable('Path', $newValue, $Scope)
        $processPath = [Environment]::GetEnvironmentVariable('Path', 'Process')
        if ([string]::IsNullOrWhiteSpace($processPath)) { $processPath = '' }
        foreach ($entry in $Entries) {
            if ((Test-PathSafe -Path $entry -Literal) -and ($processPath -notlike ('*' + $entry + '*'))) {
                if ([string]::IsNullOrWhiteSpace($processPath)) {
                    $processPath = $entry
                } else {
                    $processPath = ($processPath.TrimEnd(';') + ';' + $entry)
                }
            }
        }
        [Environment]::SetEnvironmentVariable('Path', $processPath, 'Process')
        Write-Result 'OK' ('User PATH сохранен: HKCU:\Environment\Path')
    } else {
        Write-Result 'OK' 'PATH не изменен.'
    }

    return $true
}

function InstallPythonPath {
    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден, PATH установить невозможно.'
        return $false
    }

    $pythonDir = Split-Path -Path $python.DefaultPath -Parent
    $scriptsDir = Join-Path $pythonDir 'Scripts'
    Write-Host ('Python: {0}' -f $python.DefaultPath)
    Write-Host ('User PATH хранится: HKCU:\Environment\Path')
    Write-Host ('Machine PATH хранится: HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\Path')

    return (Add-PathEntries -Entries @($pythonDir, $scriptsDir) -Scope 'User')
}

function Clear-AppExecutionAliases {
    $windowsApps = Join-Path $env:LOCALAPPDATA 'Microsoft\WindowsApps'
    if (-not (Test-PathSafe -Path $windowsApps -Literal)) {
        Write-Result 'OK' 'WindowsApps не найден, очистка aliases не требуется.'
        return $true
    }

    $aliasNames = @('python.exe', 'python3.exe', 'pip.exe', 'pip3.exe')
    $changed = $false
    foreach ($name in $aliasNames) {
        $path = Join-Path $windowsApps $name
        if (-not (Test-PathSafe -Path $path -Literal)) { continue }
        try {
            $item = Get-Item -LiteralPath $path -ErrorAction Stop
            if ($item.Length -eq 0) {
                Write-Result 'WARNING' ('Найден App Execution Alias: {0}' -f $path)
                Write-Color '  Чтобы удалить этот alias, введите DELETE. Любой другой ввод пропустит удаление.' DarkGray
                Write-Color '  Подтверждение: ' DarkCyan -NoNewLine
                $confirm = [Console]::ReadLine()
                if ($confirm -ne 'DELETE') {
                    Write-Result 'WARNING' ('Alias оставлен без изменений: {0}' -f $path)
                    continue
                }
                Remove-Item -LiteralPath $path -Force -ErrorAction Stop
                Write-Result 'OK' ('Удален безопасный alias: {0}' -f $path)
                $changed = $true
            } else {
                Write-Result 'WARNING' ('Alias не удален, файл не похож на безопасный нулевой alias: {0}' -f $path)
            }
        } catch {
            Write-Result 'WARNING' ('Alias не очищен: {0}' -f $path)
        }
    }

    if (-not $changed) {
        Write-Result 'OK' 'Безопасно удаляемые App Execution Aliases не найдены.'
    }
    return $true
}

function Get-LatestStablePythonWingetId {
    $winget = FindWinget
    if (-not $winget.Found) { return $null }

    $candidates = New-Object System.Collections.Generic.List[object]
    foreach ($query in @('Python.Python.3')) {
        $result = Invoke-Native -FilePath $winget.Path -Arguments @('search', $query, '--accept-source-agreements') -OperationName ('winget search {0}' -f $query) -TimeoutSeconds 120
        if (-not $result.Success) { continue }

        foreach ($line in $result.Output) {
            $package = Get-WingetPythonPackageFromLine -Line $line
            if (-not $package) { continue }
            $versionKey = Get-VersionKey $package.Version
            if ($versionKey.Major -ge 3) {
                [void]$candidates.Add([pscustomobject]@{ Id = $package.Id; Version = $package.Version })
            }
        }
    }

    if ($candidates.Count -eq 0) { return $null }
    return ($candidates.ToArray() | Sort-Object @{Expression = { Get-VersionKey $_.Version }; Descending = $true } | Select-Object -First 1)
}

function InstallLatestPython {
    $latest = Get-LatestStablePythonWingetId
    if ($null -eq $latest) {
        Write-Result 'WARNING' 'winget не вернул стабильные версии Python 3. Установка пропущена.'
        return $true
    }

    Write-Host ('Последняя стабильная версия winget: {0} ({1})' -f $latest.Version, $latest.Id)
    $installedVersion = Get-InstalledLatestPythonVersion

    if (-not [string]::IsNullOrWhiteSpace($installedVersion)) {
        Write-Host ('Последняя установленная версия: {0}' -f $installedVersion)
        if ((Get-VersionKey $installedVersion) -ge (Get-VersionKey $latest.Version)) {
            Write-Result 'OK' ('Установка пропущена: установленная версия актуальна ({0}).' -f $installedVersion)
            return $true
        }
    }

    $winget = FindWinget
    $result = Invoke-Native -FilePath $winget.Path -Arguments @('install', '--id', $latest.Id, '--silent', '--disable-interactivity', '--accept-package-agreements', '--accept-source-agreements') -OperationName ('winget install {0}' -f $latest.Id) -TimeoutSeconds 1800
    if (-not $result.Success) { throw (Get-FriendlyWingetError -Output $result.Output) }
    return $true
}

function ReinstallPython {
    $latest = Get-LatestStablePythonWingetId
    if ($null -eq $latest) {
        Write-Result 'ERROR' 'winget не вернул стабильные версии Python 3. Переустановка невозможна.'
        return $false
    }

    $installedVersion = Get-InstalledLatestPythonVersion
    if (-not [string]::IsNullOrWhiteSpace($installedVersion)) {
        Write-Host ('Текущая установленная версия: {0}' -f $installedVersion)
    }
    Write-Host ('Переустановка через winget: {0} {1}' -f $latest.Id, $latest.Version)

    $winget = FindWinget
    $result = Invoke-Native -FilePath $winget.Path -Arguments @('install', '--id', $latest.Id, '--silent', '--force', '--disable-interactivity', '--accept-package-agreements', '--accept-source-agreements') -OperationName ('winget reinstall {0}' -f $latest.Id) -TimeoutSeconds 1800
    if ($result.Success) {
        Write-Result 'OK' ('Python переустановлен: {0} {1}' -f $latest.Id, $latest.Version)
        return $true
    }

    Write-Result 'ERROR' ('winget не смог выполнить переустановку: {0}' -f (Get-FriendlyWingetError -Output $result.Output))
    return $false
}

function Invoke-PythonModuleCommand {
    param([Parameter(Mandatory = $true)][string[]]$Arguments)

    $python = FindPython
    if (-not $python.DefaultPath) { throw 'Python не найден.' }
    $name = ($Arguments -join ' ')
    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments $Arguments -OperationName $name -TimeoutSeconds 900
    if (-not $result.Success) { throw (($result.Output -join ' ').Trim()) }
    if ($result.Output.Count -gt 0) { $result.Output | ForEach-Object { Write-Host $_ } }
    return $true
}

function Invoke-EnsurePip {
    Invoke-PythonModuleCommand -Arguments @('-m', 'ensurepip', '--upgrade')
}

function UpgradePip {
    Invoke-PythonModuleCommand -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '--upgrade', 'pip')
}

function UpgradeSetuptools {
    Invoke-PythonModuleCommand -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '--upgrade', 'setuptools')
}

function UpgradeWheel {
    Invoke-PythonModuleCommand -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '--upgrade', 'wheel')
}

function Invoke-Service {
    ShowHeader
    $total = 12

    [void](Invoke-Step 1 $total 'Backup пакетов' { Assert-Operation -Result (BackupPackages) -Message 'Backup пакетов не выполнен.' })
    [void](Invoke-Step 2 $total 'Поиск всех Python' {
        $items = (FindPython).All
        if ($items.Count -eq 0) { throw 'Python не найден.' }
        $items | ForEach-Object { Write-Host ('{0}  {1}' -f $_.Version, $_.Path) }
    })
    [void](Invoke-Step 3 $total 'Определение последней установленной версии' {
        $products = @(Get-InstalledPythonProducts)
        if ($products.Count -eq 0) { throw 'Установленные версии Python не найдены.' }
        $latest = $products | Sort-Object @{Expression = { Get-VersionKey $_.Version }; Descending = $true } | Select-Object -First 1
        Write-Host ('Последняя установленная версия: {0}' -f $latest.Version)
    })
    Write-Result 'WARNING' 'Удаление старых версий вынесено из общего обслуживания. Запускайте его только вручную после проверки.'
    [void](Invoke-Step 4 $total 'Очистка PATH' { Assert-Operation -Result (RepairPath) -Message 'Очистка PATH не выполнена.' })
    [void](Invoke-Step 5 $total 'Очистка App Execution Aliases' { Assert-Operation -Result (Clear-AppExecutionAliases) -Message 'Очистка aliases не выполнена.' })
    [void](Invoke-Step 6 $total 'Получение последней стабильной версии' {
        $latest = Get-LatestStablePythonWingetId
        if ($null -eq $latest) {
            Write-Result 'WARNING' 'winget не вернул стабильные версии Python 3. Установка будет пропущена.'
        } else {
            Write-Host ('{0} {1}' -f $latest.Id, $latest.Version)
        }
    })
    [void](Invoke-Step 7 $total 'Установка Python при необходимости' { [void](InstallLatestPython) })
    [void](Invoke-Step 8 $total 'ensurepip' { [void](Invoke-EnsurePip) })
    [void](Invoke-Step 9 $total 'Upgrade pip' { [void](UpgradePip) })
    [void](Invoke-Step 10 $total 'Upgrade setuptools' { [void](UpgradeSetuptools) })
    [void](Invoke-Step 11 $total 'Upgrade wheel' { [void](UpgradeWheel) })
    [void](Invoke-Step 12 $total 'Финальная проверка' { Invoke-Check -NoPause })

    Pause
}

#endregion

#region Dependencies

function Get-PipPackageCount {
    param([string]$PythonPath)

    if ([string]::IsNullOrWhiteSpace($PythonPath)) {
        $targetPython = Get-DependencyPythonPath
    } else {
        $targetPython = $PythonPath
    }

    if ([string]::IsNullOrWhiteSpace($targetPython)) { return $null }

    $result = Invoke-Native -FilePath $targetPython -Arguments @('-m', 'pip', 'list', '--format=json') -Quiet -TimeoutSeconds 120
    if (-not $result.Success) { return $null }

    $jsonText = ($result.Output -join "`n").Trim()
    if ([string]::IsNullOrWhiteSpace($jsonText)) { return 0 }

    try {
        $packages = $jsonText | ConvertFrom-Json
        if ($null -eq $packages) { return 0 }
        if ($packages -is [array]) { return $packages.Length }
        return @($packages).Count
    } catch {
        return $null
    }
}

function Get-DependencyPythonPath {
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    if ($venv.Healthy -and (Test-PathSafe -Path $venv.PythonPath -Literal)) { return $venv.PythonPath }

    $python = FindPython
    return $python.DefaultPath
}

function Get-LearningLibraries {
    return @(
        [pscustomobject]@{
            Key = 'requests'
            DisplayName = 'Requests'
            PackageName = 'requests'
            ImportName = 'requests'
            RequiredSpec = '>=2.34.0'
            Purpose = 'HTTP-запросы, интернет и API'
        },
        [pscustomobject]@{
            Key = 'flask'
            DisplayName = 'Flask'
            PackageName = 'flask'
            ImportName = 'flask'
            RequiredSpec = '>=3.1'
            Purpose = 'Веб-сайты и API'
        },
        [pscustomobject]@{
            Key = 'telegram'
            DisplayName = 'Telegram Bot API'
            PackageName = 'python-telegram-bot'
            ImportName = 'telegram'
            RequiredSpec = '>=22'
            Purpose = 'Telegram-боты'
        },
        [pscustomobject]@{
            Key = 'pyqt'
            DisplayName = 'PyQt6'
            PackageName = 'PyQt6'
            ImportName = 'PyQt6'
            RequiredSpec = '>=6'
            Purpose = 'Desktop-приложения'
        }
    )
}

function Get-LearningLibraryByKey {
    param([Parameter(Mandatory = $true)][string]$Key)

    return (Get-LearningLibraries | Where-Object { $_.Key -eq $Key } | Select-Object -First 1)
}

function Normalize-PackageName {
    param([string]$Name)

    if ([string]::IsNullOrWhiteSpace($Name)) { return '' }
    return ($Name.Trim().ToLowerInvariant() -replace '[-_.]+', '-')
}

function Get-RequirementSpecForPackage {
    param([Parameter(Mandatory = $true)][string]$PackageName)

    $requirementsPath = Join-Path $Script:ProjectRoot 'requirements.txt'
    if (-not (Test-PathSafe -Path $requirementsPath -Literal)) { return $null }

    $target = Normalize-PackageName $PackageName
    foreach ($line in (Get-Content -LiteralPath $requirementsPath -ErrorAction SilentlyContinue)) {
        $text = $line.Trim()
        if ([string]::IsNullOrWhiteSpace($text) -or $text.StartsWith('#')) { continue }
        if ($text -match '^\s*([A-Za-z0-9_.-]+)\s*(==|>=|<=|>|<)\s*([A-Za-z0-9_.!+\-]+)') {
            if ((Normalize-PackageName $matches[1]) -eq $target) {
                return ('{0}{1}' -f $matches[2], $matches[3])
            }
        }
    }

    return $null
}

function Get-EffectiveRequiredSpec {
    param([Parameter(Mandatory = $true)][object]$Library)

    $fromRequirements = Get-RequirementSpecForPackage -PackageName $Library.PackageName
    if (-not [string]::IsNullOrWhiteSpace($fromRequirements)) { return $fromRequirements }
    return $Library.RequiredSpec
}

function Compare-PackageVersions {
    param(
        [string]$Left,
        [string]$Right
    )

    $leftParts = @($Left -split '[^0-9]+' | Where-Object { $_ -ne '' })
    $rightParts = @($Right -split '[^0-9]+' | Where-Object { $_ -ne '' })
    $max = [Math]::Max($leftParts.Count, $rightParts.Count)
    for ($i = 0; $i -lt $max; $i++) {
        $l = 0
        $r = 0
        if ($i -lt $leftParts.Count) { $l = [int]$leftParts[$i] }
        if ($i -lt $rightParts.Count) { $r = [int]$rightParts[$i] }
        if ($l -lt $r) { return -1 }
        if ($l -gt $r) { return 1 }
    }

    return 0
}

function Test-VersionSatisfiesSpec {
    param(
        [string]$Version,
        [string]$Spec
    )

    if ([string]::IsNullOrWhiteSpace($Version)) { return $false }
    if ([string]::IsNullOrWhiteSpace($Spec)) { return $true }
    if ($Spec -notmatch '^(==|>=|<=|>|<)\s*(.+)$') { return $true }

    $operator = $matches[1]
    $required = $matches[2].Trim()
    $cmp = Compare-PackageVersions -Left $Version -Right $required

    switch ($operator) {
        '==' { return ($cmp -eq 0) }
        '>=' { return ($cmp -ge 0) }
        '<=' { return ($cmp -le 0) }
        '>' { return ($cmp -gt 0) }
        '<' { return ($cmp -lt 0) }
    }

    return $true
}

function Get-LearningLibraryInstallPlan {
    param(
        [Parameter(Mandatory = $true)][object]$Library,
        [Parameter(Mandatory = $true)][string]$PythonPath
    )

    $requiredSpec = Get-EffectiveRequiredSpec -Library $Library
    $installedVersion = Get-PythonPackageVersion -PythonPath $PythonPath -PackageName $Library.PackageName -ImportName $Library.ImportName
    $action = 'INSTALL'
    if (-not [string]::IsNullOrWhiteSpace($installedVersion)) {
        if (Test-VersionSatisfiesSpec -Version $installedVersion -Spec $requiredSpec) {
            $action = 'SKIP'
        } else {
            $action = 'UPDATE'
        }
    }

    return [pscustomobject]@{
        Library = $Library
        Package = $Library.DisplayName
        PackageName = $Library.PackageName
        InstalledVersion = $installedVersion
        RequiredSpec = $requiredSpec
        Action = $action
    }
}

function Show-LearningLibraryPlan {
    param([Parameter(Mandatory = $true)][object[]]$Plans)

    ShowSectionTitle 'План учебных библиотек'
    Write-Color ('  {0,-22} {1,-14} {2,-12} {3}' -f 'Пакет', 'Версия', 'Требуется', 'Действие') DarkCyan
    foreach ($plan in $Plans) {
        $version = if ([string]::IsNullOrWhiteSpace($plan.InstalledVersion)) { '-' } else { $plan.InstalledVersion }
        $color = [ConsoleColor]::Yellow
        if ($plan.Action -eq 'SKIP') { $color = [ConsoleColor]::Green }
        if ($plan.Action -eq 'UPDATE') { $color = [ConsoleColor]::Cyan }
        Write-Color ('  {0,-22} {1,-14} {2,-12} {3}' -f $plan.Package, $version, (Format-Value $plan.RequiredSpec), $plan.Action) $color
    }
}

function Get-PythonPackageVersion {
    param(
        [Parameter(Mandatory = $true)][string]$PythonPath,
        [Parameter(Mandatory = $true)][string]$PackageName,
        [Parameter(Mandatory = $true)][string]$ImportName
    )

    if (-not (Test-PathSafe -Path $PythonPath -Literal)) { return $null }

    $result = Invoke-Native -FilePath $PythonPath -Arguments @('-m', 'pip', 'show', $PackageName) -Quiet -TimeoutSeconds 60
    if (-not $result.Success) { return $null }

    foreach ($line in $result.Output) {
        if ($line -match '^Version:\s*(.+)$') {
            return $matches[1].Trim()
        }
    }

    return 'version unknown'
}

function ShowLearningLibrariesStatus {
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    $venvPython = $venv.PythonPath
    $venvReady = $venv.Healthy

    ShowSectionTitle 'Учебные библиотеки'
    Write-InfoLine 'Цель установки' $venvPath
    if ($venvReady) {
        Write-InfoLine 'venv готов' 'OK' Green
    } else {
        Write-InfoLine 'venv готов' 'ERROR' Red
        Write-Color '  Требуется создать или пересоздать project venv перед установкой библиотек.' DarkGray
    }

    foreach ($library in (Get-LearningLibraries)) {
        $status = 'ERROR'
        $version = $null
        $spec = Get-EffectiveRequiredSpec -Library $library
        if ($venvReady) {
            $version = Get-PythonPackageVersion -PythonPath $venvPython -PackageName $library.PackageName -ImportName $library.ImportName
            if (-not [string]::IsNullOrWhiteSpace($version)) { $status = 'OK' }
        }

        $value = $status
        if ($status -eq 'OK') { $value = ('OK ({0})' -f $version) }
        Write-InfoLine $library.DisplayName $value (Get-StateColor $status)
        Write-Color ('    pip: {0} | требуется: {1} | import: {2} | {3}' -f $library.PackageName, (Format-Value $spec), $library.ImportName, $library.Purpose) DarkGray
    }
}

function EnsureDefaultVenv {
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    $venvPython = $venv.PythonPath

    if ($venv.Healthy -and (Test-PathSafe -Path $venvPython -Literal)) {
        Write-Result 'OK' ('venv готов: {0}' -f $venvPath)
        return $true
    }

    if ($venv.Exists -and -not $venv.Healthy) {
        Write-Result 'WARNING' $venv.Reason
        Write-Color '  Такой venv не используется автоматически. Удалите или пересоздайте его через меню venv после проверки.' Yellow
        return $false
    }

    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден, venv создать невозможно.'
        return $false
    }

    Write-Host ('Создание venv: {0}' -f $venvPath)
    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'venv', $venvPath) -OperationName 'create project venv' -TimeoutSeconds 300
    if ($result.Success -and (Test-PathSafe -Path $venvPython -Literal)) {
        Write-Result 'OK' ('venv создан: {0}' -f $venvPath)
        return $true
    }

    Write-Result 'ERROR' (($result.Output -join ' ').Trim())
    return $false
}

function RecreateProjectVenvForLibraries {
    $venvPath = Get-DefaultVenvPath
    $venvPython = Get-VenvPythonPath -VenvPath $venvPath
    $python = FindPython

    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Рабочий системный Python не найден, venv пересоздать невозможно.'
        return $null
    }

    $expectedVenvPath = [System.IO.Path]::GetFullPath((Join-Path $Script:ProjectRoot 'venv'))
    $actualVenvPath = [System.IO.Path]::GetFullPath($venvPath)
    if ($actualVenvPath.TrimEnd('\') -ne $expectedVenvPath.TrimEnd('\')) {
        Write-Result 'ERROR' ('Небезопасный путь project venv: {0}' -f $venvPath)
        return $null
    }

    $venvExists = Test-PathSafe -Path $venvPath -Literal
    if ($venvExists) {
        Write-Result 'WARNING' 'Будет пересоздан project venv.'
    } else {
        Write-Result 'WARNING' 'Project venv отсутствует и будет создан заново.'
    }
    Write-InfoLine 'Системный Python' $python.DefaultPath
    Write-InfoLine 'Версия' $python.DefaultVersion
    Write-InfoLine 'Project venv' $venvPath

    if ($venvExists) {
        Write-Color '  Для удаления только этой папки project venv введите DELETE.' Yellow
        Write-Color '  Подтверждение: ' DarkCyan -NoNewLine
        $confirm = [Console]::ReadLine()
        if ($confirm -ne 'DELETE') {
            Write-Result 'WARNING' 'Пересоздание venv отменено.'
            return $null
        }

        try {
            Remove-Item -LiteralPath $venvPath -Recurse -Force
            Write-Result 'OK' ('Удален старый project venv: {0}' -f $venvPath)
        } catch {
            Write-Result 'ERROR' ('Не удалось удалить project venv: {0}' -f $_.Exception.Message)
            return $null
        }
    } else {
        Write-Color '  Для создания нового project venv введите CREATE.' Yellow
        Write-Color '  Подтверждение: ' DarkCyan -NoNewLine
        $confirm = [Console]::ReadLine()
        if ($confirm -ne 'CREATE') {
            Write-Result 'WARNING' 'Создание venv отменено.'
            return $null
        }
    }

    $create = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'venv', $venvPath) -OperationName 'create project venv' -TimeoutSeconds 300
    if (-not $create.Success) {
        Write-Result 'ERROR' ('venv не создан. Exit code: {0}' -f $create.ExitCode)
        $create.StdErr | Select-Object -Last 8 | ForEach-Object { Write-Color ('  ' + $_) Red }
        return $null
    }

    $health = Get-VenvHealth -VenvPath $venvPath
    if (-not $health.Healthy) {
        Write-Result 'ERROR' ('Новый venv не прошел проверку: {0}' -f $health.Reason)
        return $null
    }

    $upgrade = Invoke-Native -FilePath $venvPython -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '--upgrade', 'pip') -OperationName 'venv upgrade pip' -TimeoutSeconds 900
    if (-not $upgrade.Success) {
        Write-Result 'ERROR' ('pip в новом venv не обновлен. Exit code: {0}' -f $upgrade.ExitCode)
        $upgrade.StdErr | Select-Object -Last 8 | ForEach-Object { Write-Color ('  ' + $_) Red }
        return $null
    }

    return [pscustomobject]@{
        PythonPath = $venvPython
        Kind = 'Project venv'
        Description = $venvPath
    }
}

function Resolve-LearningLibraryPythonTarget {
    return (Resolve-ProjectVenvPythonTarget -Purpose 'установки учебных библиотек')
}

function Resolve-ProjectVenvPythonTarget {
    param([string]$Purpose = 'работы с зависимостями проекта')

    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath

    if ($venv.Healthy -and (Test-PathSafe -Path $venv.PythonPath -Literal)) {
        return [pscustomobject]@{
            PythonPath = $venv.PythonPath
            Kind = 'Project venv'
            Description = $venvPath
        }
    }

    $python = FindPython
    Show-BrokenVenvExplanation -Venv $venv -Context 'Install'

    if ($python.DefaultPath) {
        Write-InfoLine 'Найден рабочий системный Python' $python.DefaultPath
        Write-InfoLine 'Версия' $python.DefaultVersion
    } else {
        Write-InfoLine 'Найден рабочий системный Python' 'Не найден' Red
        Write-Result 'ERROR' 'Создать project venv невозможно без рабочего системного Python.'
        return $null
    }

    Write-Host ''
    Write-Color ('Действие требуется для: {0}' -f $Purpose) DarkGray
    Write-Color '[1] Пересоздать venv на базе найденного рабочего системного Python' Yellow
    Write-Color '[0] Отмена' Yellow
    Write-Host ''
    Write-Color 'Выбор: ' Yellow -NoNewLine
    $choice = [Console]::ReadLine()

    switch ($choice) {
        '1' { return (RecreateProjectVenvForLibraries) }
        default {
            Write-Result 'WARNING' 'Установка отменена. Библиотеки не устанавливались.'
            return $null
        }
    }
}

function InstallLearningLibraryToTarget {
    param(
        [Parameter(Mandatory = $true)][object]$Library,
        [Parameter(Mandatory = $true)][object]$Target
    )

    $plan = Get-LearningLibraryInstallPlan -Library $Library -PythonPath $Target.PythonPath
    if ($plan.Action -eq 'SKIP') {
        Write-Result 'OK' ('{0} {1} уже установлен и соответствует требованиям - пропуск.' -f $Library.DisplayName, $plan.InstalledVersion)
        return [pscustomobject]@{
            Package = $Library.DisplayName
            Status = 'SKIPPED'
            ExitCode = $null
            PythonTarget = $Target.PythonPath
            Command = $null
            StdErr = @()
            Version = $plan.InstalledVersion
        }
    }

    $packageSpec = $Library.PackageName
    if (-not [string]::IsNullOrWhiteSpace($plan.RequiredSpec)) {
        $packageSpec = ('{0}{1}' -f $Library.PackageName, $plan.RequiredSpec)
    }

    $arguments = @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3')
    if ($plan.Action -eq 'UPDATE') { $arguments += '--upgrade' }
    $arguments += $packageSpec
    $command = ('"{0}" {1}' -f $Target.PythonPath, ($arguments -join ' '))
    Write-InfoLine 'Python target' $Target.PythonPath
    Write-InfoLine 'Команда' $command

    $result = Invoke-Native -FilePath $Target.PythonPath -Arguments $arguments -OperationName ('pip install {0}' -f $Library.PackageName) -TimeoutSeconds 900
    if ($result.Success) {
        $version = Get-PythonPackageVersion -PythonPath $Target.PythonPath -PackageName $Library.PackageName -ImportName $Library.ImportName
        if ([string]::IsNullOrWhiteSpace($version)) { $version = 'version unknown' }
        $status = if ($plan.Action -eq 'UPDATE') { 'UPDATED' } else { 'INSTALLED' }
        Write-Result 'OK' ('{0}: {1} {2}' -f $status, $Library.DisplayName, $version)
        return [pscustomobject]@{
            Package = $Library.DisplayName
            Status = $status
            ExitCode = $result.ExitCode
            PythonTarget = $Target.PythonPath
            Command = $command
            StdErr = @($result.StdErr)
            Version = $version
        }
    }

    Write-Result 'ERROR' ('Не установлено: {0}' -f $Library.DisplayName)
    Write-InfoLine 'Пакет' $Library.PackageName
    Write-InfoLine 'Python target' $Target.PythonPath
    Write-InfoLine 'Команда' $command
    Write-InfoLine 'Exit code' $result.ExitCode
    $result.StdErr | Select-Object -Last 10 | ForEach-Object { Write-Color ('  ' + $_) Red }
    return [pscustomobject]@{
        Package = $Library.DisplayName
        Status = 'FAILED'
        ExitCode = $result.ExitCode
        PythonTarget = $Target.PythonPath
        Command = $command
        StdErr = @($result.StdErr)
        Version = $plan.InstalledVersion
    }
}

function InstallLearningLibrary {
    param([Parameter(Mandatory = $true)][string]$Key)

    $library = Get-LearningLibraryByKey -Key $Key
    if ($null -eq $library) {
        Write-Result 'ERROR' ('Неизвестная библиотека: {0}' -f $Key)
        return $false
    }

    $target = Resolve-LearningLibraryPythonTarget
    if ($null -eq $target) { return $false }
    $summary = InstallLearningLibraryToTarget -Library $library -Target $target
    return (@('INSTALLED', 'UPDATED', 'SKIPPED') -contains $summary.Status)
}

function InstallAllLearningLibraries {
    $libraries = @(Get-LearningLibraries)
    $target = Resolve-LearningLibraryPythonTarget
    $summaries = New-Object System.Collections.Generic.List[object]

    if ($null -eq $target) {
        foreach ($library in $libraries) {
            [void]$summaries.Add([pscustomobject]@{
                Package = $library.DisplayName
                Status = 'SKIPPED'
                ExitCode = $null
                PythonTarget = $null
                Command = $null
                StdErr = @()
                Version = $null
            })
        }
        ShowLearningLibraryInstallSummary -Summaries $summaries.ToArray()
        return $false
    }

    Write-InfoLine 'Выбранный target' ('{0}: {1}' -f $target.Kind, $target.PythonPath)
    $plans = @($libraries | ForEach-Object { Get-LearningLibraryInstallPlan -Library $_ -PythonPath $target.PythonPath })
    Show-LearningLibraryPlan -Plans $plans
    $index = 0
    foreach ($library in $libraries) {
        $index++
        Write-Host ''
        Write-Color ('[{0}/{1}] {2}' -f $index, $libraries.Count, $library.DisplayName) Cyan
        [void]$summaries.Add((InstallLearningLibraryToTarget -Library $library -Target $target))
    }

    ShowLearningLibraryInstallSummary -Summaries $summaries.ToArray()
    return (@($summaries | Where-Object { @('INSTALLED', 'UPDATED', 'SKIPPED') -notcontains $_.Status }).Count -eq 0)
}

function ShowLearningLibraryInstallSummary {
    param([object[]]$Summaries)

    ShowSectionTitle 'Итог установки библиотек'
    foreach ($item in $Summaries) {
        $status = $item.Status
        $color = [ConsoleColor]::Green
        if ($status -eq 'FAILED') { $color = [ConsoleColor]::Red }
        if ($status -eq 'SKIPPED') { $color = [ConsoleColor]::Yellow }
        $value = $status
        if ($status -eq 'SKIPPED' -and -not [string]::IsNullOrWhiteSpace($item.Version)) {
            $value = ('SKIPPED - {0} уже актуален' -f $item.Version)
        }
        Write-InfoLine $item.Package $value $color
    }
}

function ShowDependencyStatus {
    $python = FindPython
    $pip = FindPip
    $packageCount = Get-PipPackageCount
    $requirementsPath = Join-Path $Script:ProjectRoot 'requirements.txt'
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    $requirementsState = 'ERROR'
    $venvState = 'ERROR'

    if (Test-PathSafe -Path $requirementsPath -Literal) { $requirementsState = 'OK' }
    if ($venv.Healthy) { $venvState = 'OK' } elseif ($venv.Exists) { $venvState = 'WARNING' }

    ShowSectionTitle 'Статус зависимостей'
    Write-InfoLine 'Папка проекта' $Script:ProjectRoot
    Write-InfoLine 'Python' $python.DefaultVersion
    Write-InfoLine 'Python путь' $python.DefaultPath
    Write-InfoLine 'pip' $pip.Version
    Write-InfoLine 'pip путь' $pip.Path
    Write-InfoLine 'Установлено pip-пакетов' $packageCount Yellow
    Write-InfoLine 'requirements.txt' $requirementsState (Get-StateColor $requirementsState)
    Write-InfoLine 'venv' $venvState (Get-StateColor $venvState)
    Write-InfoLine 'venv путь' $venvPath
    Write-InfoLine 'venv диагностика' $venv.Reason
}

function ShowVenvStatus {
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    $state = 'ERROR'
    if ($venv.Healthy) {
        $state = 'OK'
    } elseif ($venv.Exists) {
        $state = 'WARNING'
    }

    ShowSectionTitle 'Текущее окружение'
    Write-InfoLine 'Статус venv' $state (Get-StateColor $state)
    Write-InfoLine 'Папка venv' $venvPath
    Write-InfoLine 'Python внутри venv' $venv.PythonPath
    Write-InfoLine 'Диагностика' $venv.Reason
}

function UpgradePackages {
    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден.'
        return $false
    }

    $outdated = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'pip', 'list', '--outdated', '--format=json') -OperationName 'pip list outdated' -TimeoutSeconds 180
    if (-not $outdated.Success) {
        Write-Result 'ERROR' (($outdated.Output -join ' ').Trim())
        return $false
    }

    $jsonText = ($outdated.Output -join "`n").Trim()
    if ([string]::IsNullOrWhiteSpace($jsonText) -or $jsonText -eq '[]') {
        Write-Result 'OK' 'Устаревшие пакеты не найдены.'
        return $true
    }

    try {
        $packages = $jsonText | ConvertFrom-Json
    } catch {
        Write-Result 'ERROR' 'Не удалось разобрать JSON pip list.'
        return $false
    }

    if ($null -eq $packages -or @($packages).Count -eq 0) {
        Write-Result 'OK' 'Устаревшие пакеты не найдены.'
        return $true
    }

    foreach ($package in $packages) {
        $name = [string]$package.name
        if ([string]::IsNullOrWhiteSpace($name)) { continue }
        Write-Host ('Обновление пакета: {0}' -f $name)
        $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '--upgrade', $name) -OperationName ('pip upgrade {0}' -f $name) -TimeoutSeconds 900
        if ($result.Success) {
            Write-Result 'OK' ('Обновлен: {0}' -f $name)
        } else {
            Write-Result 'WARNING' ('Не обновлен: {0}. {1}' -f $name, (($result.Output -join ' ').Trim()))
        }
    }

    Write-Result 'OK' 'Обновление пакетов завершено.'
    return $true
}

function RestorePackages {
    Write-Host 'Restore устанавливает пакеты из requirements.txt в текущий Python.'
    Write-Host 'Укажите путь к файлу или вернитесь назад пустым вводом.'
    Write-Host ''
    $path = Read-PathFromUser -Prompt 'Путь к requirements.txt'
    if ([string]::IsNullOrWhiteSpace($path)) {
        Write-Result 'WARNING' 'Операция отменена.'
        return $false
    }
    return ImportRequirements -RequirementsPath $path
}

function Read-PathFromUser {
    param([Parameter(Mandatory = $true)][string]$Prompt)

    Write-Color ($Prompt + ': ') Yellow -NoNewLine
    return [Console]::ReadLine()
}

function Get-DefaultVenvPath {
    return (Join-Path $Script:ProjectRoot 'venv')
}

function Get-VenvPythonPath {
    param([string]$VenvPath)

    return (Join-Path $VenvPath 'Scripts\python.exe')
}

function CreateVenv {
    Write-Host 'Будет создана отдельная папка окружения Python для проекта.'
    Write-Host 'Обычно используют путь venv в текущей папке. Чтобы выбрать его, просто нажмите Enter.'
    Write-Host ''
    $path = Read-PathFromUser -Prompt ('Путь к окружению venv [{0}]' -f (Get-DefaultVenvPath))
    if ([string]::IsNullOrWhiteSpace($path)) { $path = Get-DefaultVenvPath }

    if (Test-PathSafe -Path $path -Literal) {
        $health = Get-VenvHealth -VenvPath $path
        Write-Result 'WARNING' ('venv уже существует: {0}' -f $path)
        Write-InfoLine 'Диагностика' $health.Reason
        return $true
    }

    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден.'
        return $false
    }

    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'venv', $path) -OperationName 'create venv' -TimeoutSeconds 300
    if ($result.Success) {
        Write-Result 'OK' ('venv создан: {0}' -f $path)
        return $true
    }

    Write-Result 'ERROR' (($result.Output -join ' ').Trim())
    return $false
}

function RemoveVenv {
    Write-Host 'Будет удалена только папка виртуального окружения.'
    Write-Host 'Основной Python, PATH и установленные версии Python не изменяются.'
    Write-Host ''
    $path = Read-PathFromUser -Prompt ('Путь к окружению venv [{0}]' -f (Get-DefaultVenvPath))
    if ([string]::IsNullOrWhiteSpace($path)) { $path = Get-DefaultVenvPath }

    if (-not (Test-PathSafe -Path $path -Literal)) {
        Write-Result 'WARNING' ('venv не найден: {0}' -f $path)
        return $true
    }

    $pyvenvCfg = Join-Path $path 'pyvenv.cfg'
    $venvPython = Get-VenvPythonPath -VenvPath $path
    if (-not (Test-PathSafe -Path $pyvenvCfg -Literal) -or -not (Test-PathSafe -Path $venvPython -Literal)) {
        Write-Result 'ERROR' 'Папка не похожа на виртуальное окружение Python, удаление остановлено.'
        return $false
    }

    try {
        Remove-Item -LiteralPath $path -Recurse -Force
        Write-Result 'OK' ('venv удален: {0}' -f $path)
        return $true
    } catch {
        Write-Result 'ERROR' $_.Exception.Message
        return $false
    }
}

function ExportRequirements {
    Write-Host 'Export сохраняет список установленных pip-пакетов в requirements.txt.'
    Write-Host 'Этот файл удобно переносить в другой проект или использовать для восстановления пакетов.'
    Write-Host ''
    $path = Read-PathFromUser -Prompt ('Куда сохранить requirements.txt [{0}]' -f (Join-Path $Script:ProjectRoot 'requirements.txt'))
    if ([string]::IsNullOrWhiteSpace($path)) { $path = Join-Path $Script:ProjectRoot 'requirements.txt' }

    $python = FindPython
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Python не найден.'
        return $false
    }

    $result = Invoke-Native -FilePath $python.DefaultPath -Arguments @('-m', 'pip', 'freeze') -OperationName 'pip freeze' -TimeoutSeconds 120
    if (-not $result.Success) {
        Write-Result 'ERROR' (($result.Output -join ' ').Trim())
        return $false
    }

    try {
        [IO.File]::WriteAllLines($path, [string[]]$result.Output, [Text.Encoding]::UTF8)
        Write-Result 'OK' ('requirements экспортирован: {0}' -f $path)
        return $true
    } catch {
        Write-Result 'ERROR' $_.Exception.Message
        return $false
    }
}

function ImportRequirements {
    param([string]$RequirementsPath)

    $path = $RequirementsPath
    if ([string]::IsNullOrWhiteSpace($path)) {
        Write-Host 'Import устанавливает pip-пакеты из requirements.txt.'
        Write-Host 'Если файл лежит в текущей папке, просто нажмите Enter.'
        Write-Host ''
        $path = Read-PathFromUser -Prompt ('Откуда взять requirements.txt [{0}]' -f (Join-Path $Script:ProjectRoot 'requirements.txt'))
        if ([string]::IsNullOrWhiteSpace($path)) { $path = Join-Path $Script:ProjectRoot 'requirements.txt' }
    }

    if (-not (Test-PathSafe -Path $path -Literal)) {
        Write-Result 'ERROR' ('Файл не найден: {0}' -f $path)
        return $false
    }

    $target = Resolve-ProjectVenvPythonTarget -Purpose 'импорта requirements.txt'
    if ($null -eq $target) {
        Write-Result 'WARNING' 'Import requirements отменен. Project venv не выбран.'
        return $false
    }

    Write-InfoLine 'Python target' $target.PythonPath
    $result = Invoke-Native -FilePath $target.PythonPath -Arguments @('-m', 'pip', 'install', '--timeout', '60', '--retries', '3', '-r', $path) -OperationName 'pip install requirements' -TimeoutSeconds 1200
    if ($result.Success) {
        $result.Output | ForEach-Object { Write-Host $_ }
        Write-Result 'OK' ('requirements импортирован: {0}' -f $path)
        return $true
    }

    Write-Result 'ERROR' (($result.Output -join ' ').Trim())
    return $false
}

function Invoke-DependenciesMenu {
    while ($true) {
        $choice = ShowDependencyMenu
        switch ($choice) {
            '1' { ShowHeader; [void](UpgradePackages); Pause }
            '2' { ShowHeader; [void](BackupPackages); Pause }
            '3' { ShowHeader; [void](RestorePackages); Pause }
            '4' { Invoke-VenvMenu }
            '5' { ShowHeader; [void](InstallPythonPath); Pause }
            '6' { Invoke-LearningLibrariesMenu }
            '0' { return }
            default { Write-Result 'WARNING' 'Неверный пункт меню.'; Pause }
        }
    }
}

function Invoke-LearningLibrariesMenu {
    while ($true) {
        $choice = ShowLearningLibrariesMenu
        switch ($choice) {
            '1' { ShowHeader; [void](InstallLearningLibrary -Key 'requests'); Pause }
            '2' { ShowHeader; [void](InstallLearningLibrary -Key 'flask'); Pause }
            '3' { ShowHeader; [void](InstallLearningLibrary -Key 'telegram'); Pause }
            '4' { ShowHeader; [void](InstallLearningLibrary -Key 'pyqt'); Pause }
            '5' { ShowHeader; [void](InstallAllLearningLibraries); Pause }
            '0' { return }
            default { Write-Result 'WARNING' 'Неверный пункт меню.'; Pause }
        }
    }
}

function Invoke-VenvMenu {
    while ($true) {
        $choice = ShowVenvMenu
        switch ($choice) {
            '1' { ShowHeader; [void](CreateVenv); Pause }
            '2' { ShowHeader; [void](RemoveVenv); Pause }
            '3' { ShowHeader; [void](ExportRequirements); Pause }
            '4' { ShowHeader; [void](ImportRequirements); Pause }
            '0' { return }
            default { Write-Result 'WARNING' 'Неверный пункт меню.'; Pause }
        }
    }
}

#endregion

function Invoke-Check {
    param([switch]$NoPause)

    ShowHeader

    $python = FindPython
    $pip = FindPip
    $pyLauncher = FindPyLauncher
    $winget = FindWinget
    $pathInfo = FindPath

    Write-Result 'OK' ('Windows: {0}' -f ([Environment]::OSVersion.VersionString))
    Write-Result 'OK' ('PowerShell: {0}' -f $PSVersionTable.PSVersion)

    if (Test-Administrator) { Write-Result 'OK' 'Administrator: да' } else { Write-Result 'WARNING' 'Administrator: нет' }
    if (Test-Internet) { Write-Result 'OK' 'Internet/PyPI: доступен' } else { Write-Result 'ERROR' 'Internet/PyPI: недоступен' }
    foreach ($net in (Get-NetworkDiagnostics)) {
        if ($net.OK) {
            Write-Result 'OK' ('Network: {0}' -f $net.Url)
        } else {
            Write-Result 'WARNING' ('Network: {0} - {1}' -f $net.Url, $net.Message)
        }
    }
    if ($winget.Found) { Write-Result 'OK' ('Winget: {0}' -f $winget.Path) } else { Write-Result 'ERROR' 'Winget не найден.' }

    if ($pathInfo.Broken.Count -eq 0) {
        Write-Result 'OK' 'PATH: битые записи не найдены.'
    } else {
        Write-Result 'WARNING' ('PATH: найдено битых записей: {0}' -f $pathInfo.Broken.Count)
        $pathInfo.Broken | ForEach-Object { Write-Host ('{0}: {1}' -f $_.Scope, $_.Raw) }
    }
    Write-Host 'User PATH: HKCU:\Environment\Path'
    Write-Host 'Machine PATH: HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\Path'
    Write-Host 'Process PATH: текущий процесс PowerShell/CMD; участвует в поиске Python'

    foreach ($proxy in (Get-ProxyDiagnostics)) {
        Write-Result 'OK' ('{0}: {1}' -f $proxy.Name, $proxy.Value)
    }
    Write-Color 'pip config:' White
    foreach ($line in (Get-PipConfigDiagnostics)) {
        Write-Host ('  {0}' -f $line)
    }

    if ($python.DefaultPath) {
        Write-Result 'OK' ('Python по умолчанию: {0}  {1}' -f $python.DefaultVersion, $python.DefaultPath)
    } else {
        Write-Result 'ERROR' 'Python не найден.'
    }

    if ($pyLauncher.Found) { Write-Result 'OK' ('py.exe: {0}' -f $pyLauncher.Path) } else { Write-Result 'WARNING' 'py.exe не найден.' }
    if ($pip.Path) { Write-Result 'OK' ('pip: {0}  {1}' -f $pip.Version, $pip.Path) } else { Write-Result 'ERROR' 'pip не найден.' }

    if ($python.DefaultPath) {
        foreach ($module in @('ssl', 'sqlite3', 'tkinter', 'venv')) {
            if (Test-PythonModule -PythonPath $python.DefaultPath -ModuleName $module) {
                Write-Result 'OK' ('Модуль {0}: доступен' -f $module)
            } else {
                Write-Result 'ERROR' ('Модуль {0}: недоступен' -f $module)
            }
        }
    }

    Write-Host ''
    Write-Color 'Все найденные версии Python:' White
    if ($python.All.Count -eq 0) {
        Write-Host 'Не найдено'
    } else {
        foreach ($item in $python.All) {
            Write-Host ('{0}  {1}  {2}  {3}' -f (Format-Value $item.Version), (Format-Value $item.Path), (Format-Value $item.Source), (Format-Value $item.Type))
            Write-Host ('    {0}' -f (Format-Value $item.Reason))
        }
    }

    if (-not $NoPause) { Pause }
}

function Test-ProjectImports {
    param([Parameter(Mandatory = $true)][string]$PythonPath)

    $modules = @('requests', 'flask', 'telegram', 'PyQt6')
    $allOk = $true
    foreach ($module in $modules) {
        $result = Invoke-Native -FilePath $PythonPath -Arguments @('-c', ('import {0}' -f $module)) -Quiet -TimeoutSeconds 30
        if ($result.Success) {
            Write-Result 'OK' ('import {0}' -f $module)
        } else {
            Write-Result 'ERROR' ('import {0}' -f $module)
            $allOk = $false
        }
    }

    return $allOk
}

function Invoke-FirstRunWizard {
    ShowHeader
    Write-Color '  Первый запуск на новом ПК' Cyan
    Write-Color '  ------------------------' DarkCyan
    Write-Host ''
    Write-Color '  Мастер сначала выполняет диагностику и показывает план.' Gray
    Write-Color '  Изменения выполняются только после подтверждения APPLY.' Gray

    ShowSectionTitle 'Шаг 1. Проверка системы'
    Write-InfoLine 'Windows' ([Environment]::OSVersion.VersionString)
    Write-InfoLine 'OS architecture' ([Runtime.InteropServices.RuntimeInformation]::OSArchitecture)
    Write-InfoLine 'PowerShell' $PSVersionTable.PSVersion
    $winget = FindWinget
    Write-InfoLine 'winget' $(if ($winget.Found) { $winget.Path } else { 'Не найден' }) $(if ($winget.Found) { [ConsoleColor]::Green } else { [ConsoleColor]::Yellow })
    Write-InfoLine 'Сеть/PyPI' $(if (Test-Internet) { 'OK' } else { 'ERROR' }) $(if (Test-Internet) { [ConsoleColor]::Green } else { [ConsoleColor]::Red })

    ShowSectionTitle 'Шаг 2. Проверка Python'
    $python = FindPython
    Write-InfoLine 'Рабочий системный Python' $python.DefaultPath
    Write-InfoLine 'Версия' $python.DefaultVersion
    if (-not $python.DefaultPath) {
        Write-Result 'ERROR' 'Рабочий системный Python не найден. Сначала установите Python.'
        Pause
        return $false
    }

    ShowSectionTitle 'Шаг 3. Проверка venv'
    $venvPath = Get-DefaultVenvPath
    $venv = Get-VenvHealth -VenvPath $venvPath
    Write-InfoLine 'Project venv' $venvPath
    Write-InfoLine 'Статус' (Get-VenvStatusText -Venv $venv) (Get-StateColor $(if ($venv.Healthy) { 'OK' } elseif ($venv.Exists) { 'WARNING' } else { 'ERROR' }))
    if (-not $venv.Healthy) {
        Show-BrokenVenvExplanation -Venv $venv -Context 'FirstRun'
    }

    ShowSectionTitle 'Шаг 4. Проверка зависимостей'
    $plans = @()
    if ($venv.Healthy -and (Test-PathSafe -Path $venv.PythonPath -Literal)) {
        $plans = @(Get-LearningLibraries | ForEach-Object { Get-LearningLibraryInstallPlan -Library $_ -PythonPath $venv.PythonPath })
        Show-LearningLibraryPlan -Plans $plans
    } else {
        Write-Result 'WARNING' 'План зависимостей будет рассчитан после создания здорового project venv.'
    }

    ShowSectionTitle 'План действий'
    if (-not $venv.Healthy) {
        Write-Color '  1. Создать или пересоздать project venv.' Yellow
        Write-Color '  2. Обновить pip внутри project venv.' Yellow
        Write-Color '  3. Проверить и установить только необходимые учебные библиотеки.' Yellow
    } else {
        Write-Color '  1. Использовать существующий здоровый project venv.' Green
        if (@($plans | Where-Object { $_.Action -ne 'SKIP' }).Count -eq 0) {
            Write-Color '  2. Учебные библиотеки уже актуальны, установка не нужна.' Green
        } else {
            Write-Color '  2. Выполнить только действия INSTALL/UPDATE из плана.' Yellow
        }
    }
    Write-Color '  4. Выполнить финальный тест импортов.' Yellow

    Write-Host ''
    Write-Color 'Для выполнения плана введите APPLY. Любой другой ввод вернет в меню: ' Yellow -NoNewLine
    $confirm = [Console]::ReadLine()
    if ($confirm -ne 'APPLY') {
        Write-Result 'WARNING' 'Мастер завершен без изменений.'
        Pause
        return $false
    }

    $target = Resolve-ProjectVenvPythonTarget -Purpose 'мастера первого запуска'
    if ($null -eq $target) {
        Write-Result 'ERROR' 'Project venv не подготовлен.'
        Pause
        return $false
    }

    [void](InstallAllLearningLibraries)

    ShowSectionTitle 'Финальный тест'
    $version = Invoke-Native -FilePath $target.PythonPath -Arguments @('--version') -Quiet -TimeoutSeconds 30
    if ($version.Success) { Write-Result 'OK' (($version.Output -join ' ').Trim()) } else { Write-Result 'ERROR' 'python --version failed' }
    $pip = Invoke-Native -FilePath $target.PythonPath -Arguments @('-m', 'pip', '--version') -Quiet -TimeoutSeconds 30
    if ($pip.Success) { Write-Result 'OK' (($pip.Output -join ' ').Trim()) } else { Write-Result 'ERROR' 'pip --version failed' }
    $importsOk = Test-ProjectImports -PythonPath $target.PythonPath

    if ($version.Success -and $pip.Success -and $importsOk) {
        Write-Result 'OK' 'ГОТОВО К РАБОТЕ'
    } else {
        Write-Result 'ERROR' 'ТРЕБУЕТСЯ ИСПРАВЛЕНИЕ: проверьте ошибки финального теста выше.'
    }

    Pause
    return ($version.Success -and $pip.Success -and $importsOk)
}

function Invoke-Main {
    while ($true) {
        ShowHeader
        ShowStatus
        $choice = ShowMenu
        switch ($choice) {
            '1' { [void](Invoke-FirstRunWizard) }
            '2' { Invoke-Check }
            '3' { Invoke-Service }
            '4' { Invoke-DependenciesMenu }
            '5' {
                ShowHeader
                try {
                    [void](ReinstallPython)
                } catch {
                    Write-Result 'ERROR' $_.Exception.Message
                }
                Pause
            }
            '0' { return }
            default { Write-Result 'WARNING' 'Неверный пункт меню.'; Pause }
        }
    }
}

Invoke-Main