phpup.ps1

# =======================================================================
#  phpup — Windows 11 x64 a bare-metal PHP local development environment
#  Inspired by the simplicity of getphp.org - this script is so much more
#  Github: https://github.com/DaFa66/phpup
#  Author: Simon Field (aka - DaFa)
#  License: MIT
#  Date: 2026-10-22
#  Version: 2.5.0
# =======================================================================

param(
    [switch]$Offline,          # Skip URL resolution — use pre-downloaded zips

    # ---- CLI mode (see .junk/cli-contract.md) ----
    # No $Command = today's interactive dashboard, unchanged.
    [Parameter(Position=0)]
    [string]$Command,
    [switch]$Json,             # payload on stdout
    [switch]$Fast,             # status: skip prerequisites + OS caption
    [switch]$Quiet,            # suppress human output
    [switch]$NoColor,          # no-op: CLI output is never coloured
    [int]$Watch = 0            # status: repeat every N seconds (NDJSON)
)

# ---- Config -----------------------------------------------------------
$DEFAULT_BASE = "C:\phpup"
$BASE = $DEFAULT_BASE
$DOWNLOAD_CACHE  = "$BASE\downloads"

# ---- Shared constants --------------------------------------------------
$UA_STRING        = "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
$VC_MIN_VERSION   = [version]"14.51.36231"   # required by Apache Lounge VS18 + MariaDB 12.x
# OS caption is resolved lazily (Get-PlatformCaption): the CIM query measured
# at ~1.1s and CLI status is polled. See the CLI section below.
$script:OS_CAPTION_CACHE = $null

# ---- Banner -----------------------------------------------------------
$BANNER_ART = @'
┌─────────────────────────────┐
│    ____  _   _ ____         │
│   |  _ \| | | |  _ \  /\    │
│   | |_) | |_| | |_) | || |  │
│   |  __/|  _  |  __/| || |  │
│   |_|   |_| |_|_|    ||_|   │
│         ▲ ▲ ▲               │
│         phpup               │
└─────────────────────────────┘
'@

# Pinned fallback URLs — used when live scraping/API resolution fails.
$FALLBACK_URLS = @{
    Redist     = "https://aka.ms/vc14/vc_redist.x64.exe"
    Apache     = "https://www.apachelounge.com/download/VS18/binaries/httpd-2.4.69-261002-Win64-VS18.zip"
    PHP        = "https://windows.php.net/downloads/releases/php-8.5.12-Win32-vs17-x64.zip"
    MariaDB    = "https://archive.mariadb.org/mariadb-13.0.2/winx64-packages/mariadb-13.0.2-winx64.zip"
    phpMyAdmin = "https://files.phpmyadmin.net/phpMyAdmin/5.2.3/phpMyAdmin-5.2.3-all-languages.zip"
}

# ---- File helpers ---------------------------------------------------
function Remove-Tree([string]$Path) {
    # Remove-Item -Recurse renders a progress bar over the dashboard
    # ("Removed X of Y files"); suppress it around the destructive call.
    $prevProgress = $ProgressPreference
    $ProgressPreference = 'SilentlyContinue'
    Remove-Item $Path -Recurse -Force -ErrorAction SilentlyContinue
    $ProgressPreference = $prevProgress
}

# ---- Colours -------------------------------------------------------
function Write-Ok($msg)    { Write-Host "[  OK  ]  $msg" -ForegroundColor Green }
function Write-Err($msg)   { Write-Host "[ Error ]  $msg" -ForegroundColor Red }
function Write-Info($msg)  { Write-Host $msg -ForegroundColor Cyan }
function Write-Warn($msg)  { Write-Host $msg -ForegroundColor Yellow }
function Write-Bold($msg)  { Write-Host $msg -ForegroundColor White }

# ---- Detection Helpers -------------------------------------
function Test-ApacheInstalled  { return [System.IO.File]::Exists("$APACHE_PATH\bin\httpd.exe") }
function Test-PhpInstalled     { return [System.IO.File]::Exists("$PHP_PATH\php.exe") }
function Test-MariaDbInstalled { return [System.IO.File]::Exists("$MARIADB_PATH\bin\mysqld.exe") -or [System.IO.File]::Exists("$MARIADB_PATH\bin\mariadbd.exe") }
function Test-PhpMyAdminInstalled { return [System.IO.File]::Exists("$PHPMYADMIN_PATH\index.php") }

function Get-ApacheVersion {
    if (Test-ApacheInstalled) {
        $out = & "$APACHE_PATH\bin\httpd.exe" -v 2>&1 | Out-String
        if ($out -match "Apache/([\d.]+)") { return $matches[1] }
    }
    return $null
}

function Get-PhpVersionRaw {
# Single php.exe -v capture shared by Get-PhpVersion / Get-PhpVersionLabel.
    if (Test-PhpInstalled) {
        return & "$PHP_PATH\php.exe" -v 2>&1 | Select-Object -First 1
    }
    return $null
}

function Get-PhpVersion {
    $out = Get-PhpVersionRaw
    if ($out -match "PHP\s+([\d.]+)") { return $matches[1] }
    return $null
}

function Get-PhpVersionLabel {
# Installed PHP version including pre-release suffix, e.g. "8.6.0 beta1".
# Display-only: keeps numeric Get-PhpVersion for version comparisons.
    $out = Get-PhpVersionRaw
    if ($out -match "PHP\s+([\d.]+[a-zA-Z0-9]*)") {
        $raw = $matches[1]
        if ($raw -match '^([\d.]+)(RC\d+|alpha\d+|beta\d+)$') {
            return "$($matches[1]) $($matches[2])"
        }
        return $raw
    }
    return $null
}

function Test-PhpIsPreRelease([string]$label) {
# True when a PHP display label carries a pre-release suffix (alpha/beta/RC).
    return ($label -match ' (RC\d+|alpha\d+|beta\d+)$')
}

function Get-MariaDbVersion {
    if (Test-MariaDbInstalled) {
        $exe = if (Test-Path "$MARIADB_PATH\bin\mariadbd.exe") { "$MARIADB_PATH\bin\mariadbd.exe" } else { "$MARIADB_PATH\bin\mysqld.exe" }
        $out = & $exe --version 2>&1 | Out-String
        if ($out -match "([\d]+\.[\d]+\.[\d]+)") { return $matches[1] }
    }
    return $null
}

function Get-PhpMyAdminVersion {
    # phpMyAdmin stores its version in the README file (e.g. "Version 5.2.3")
    if (-not (Test-PhpMyAdminInstalled)) { return $null }
    $readme = "$PHPMYADMIN_PATH\README"
    if (Test-Path $readme) {
        $content = (Get-Content $readme -First 5 -ErrorAction SilentlyContinue) -join "`n"
        if ($content -match "Version\s+([\d.]+)") {
            return $matches[1]
        }
    }
    return "unknown"
}

function Get-ProcessesByName {
    # .NET rather than Get-Process -Name: Windows PowerShell 5.1 writes
    # "Exception of type 'System.OutOfMemoryException' was thrown" to the error
    # stream when a name matches nothing, which surfaced as noise in the panel.
    param([string[]]$Names)
    $found = @()
    foreach ($name in $Names) {
        foreach ($proc in [System.Diagnostics.Process]::GetProcessesByName($name)) {
            $found += $proc
        }
    }
    return $found
}

function Test-ApacheRunning {
    return (@(Get-ProcessesByName -Names @('httpd')).Count -gt 0)
}

function Test-MariaDbRunning {
    return (@(Get-ProcessesByName -Names @('mysqld', 'mariadbd')).Count -gt 0)
}

function Test-StackComplete {
    return (Test-ApacheInstalled) -and (Test-PhpInstalled) -and (Test-MariaDbInstalled) -and (Test-PhpMyAdminInstalled)
}

function Test-PartialStack {
    # True when the stack is incomplete but at least one component exists —
    # distinguishes "fresh machine" from "broken/partial install worth recovering".
    $present = 0
    if (Test-ApacheInstalled)    { $present++ }
    if (Test-PhpInstalled)       { $present++ }
    if (Test-MariaDbInstalled)   { $present++ }
    if (Test-PhpMyAdminInstalled){ $present++ }
    return ($present -gt 0) -and -not (Test-StackComplete)
}

function Get-VersionTag([string]$candidate, [string]$installed) {
# Tag a candidate version relative to the installed one: " (newer)" yellow,
# " (older)" dark gray, " (current)" green. Returns @{ Tag; Color } — or
# @{ Tag = ''; Color = 'Cyan' } when either side is unparseable/absent.
    if (-not $installed) { return @{ Tag = ''; Color = 'Cyan' } }
    try {
        if ([version]$candidate -gt [version]$installed) { return @{ Tag = ' (newer)'; Color = 'Yellow' } }
        if ([version]$candidate -lt [version]$installed) { return @{ Tag = ' (older)'; Color = 'DarkGray' } }
        return @{ Tag = ' (current)'; Color = 'Green' }
    }
    catch { return @{ Tag = ''; Color = 'Cyan' } }
}

function Set-IniDirective($ini, [string]$directive, [string]$value) {
# Set-or-append a php.ini directive in a Get-Content line array: replace the
# (optionally commented) matching line in place, or append a new one when
# absent. Returns the updated array (same shape as the input).
    $pattern = ';?' + [regex]::Escape($directive) + '\s*=\s*\S*'
    if ($ini -match $pattern) {
        return ($ini -replace $pattern, "$directive = $value")
    }
    return ($ini + "`n$directive = $value")
}

# Extract version string from a download URL
function Get-VersionFromUrl([string]$url, [string]$component) {
    switch ($component) {
        'apache'     { if ($url -match 'httpd-([\d.]+)-\d+-') { return $matches[1] } }
        'php'        { if ($url -match 'php-([\d.]+)-Win32-')  { return $matches[1] } }
        'mariadb'    { if ($url -match 'mariadb-([\d.]+)-winx64') { return $matches[1] } }
        'phpmyadmin' { if ($url -match 'phpMyAdmin-([\d.]+)-all-languages') { return $matches[1] } }
    }
    return $null
}

# Extract version string from a cached zip filename (offline mode)
function Get-VersionFromZipName([string]$filename, [string]$component) {
    $ver = $null
    switch ($component) {
        'apache'     { if ($filename -match 'httpd-([\d.]+)-') { $ver = $matches[1] } }
        'php'        { if ($filename -match 'php-([\d.]+)(?:RC\d+|alpha\d+|beta\d+)?-')  { $ver = $matches[1] } }
        'mariadb'    { if ($filename -match 'mariadb-([\d.]+)-') { $ver = $matches[1] } }
        'phpmyadmin' { if ($filename -match 'phpMyAdmin-([\d.]+)') { $ver = $matches[1] } }
    }
    if ($ver) {
        # Normalize to at least 3 version parts (e.g. 6.0 → 6.0.0)
        $parts = $ver -split '\.'
        while ($parts.Count -lt 3) { $parts += '0' }
        return ($parts -join '.')
    }
    return $null
}

function Get-PhpZipLabel([string]$filename) {
# Human-readable PHP version label including pre-release suffix, e.g.
# php-8.6.0alpha3-Win32-vs18-x64.zip → "8.6.0 alpha3". Stable builds
# return the plain version ("8.5.9").
    if ($filename -match 'php-([\d.]+)(RC\d+|alpha\d+|beta\d+)?-') {
        if ($matches[2]) { return "$($matches[1]) $($matches[2])" }
        return $matches[1]
    }
    return $filename
}

function Get-PhpPreReleaseRank($pv) {
# Release-cycle rank for sorting same-numeric-version builds:
# stable (1) < alpha (2) < beta (3) < RC (4) — newest wins on a tie.
    if ($pv.Label -match ' RC')   { return 4 }
    if ($pv.Label -match ' beta') { return 3 }
    if ($pv.Label -match ' alpha'){ return 2 }
    return 1
}

# ---- Config Persistence --------------------------------------

$CONFIG_FILE_LEGACY = "$env:APPDATA\phpup\config.json"

function Get-ConfigFilePath {
    # Canonical location: inside the stack folder so the config travels
    # with the install. $BASE is re-pointed by Get-Config when the stack
    # lives elsewhere (custom/moved install path).
    return "$BASE\config.json"
}

function Read-ConfigFile([string]$path) {
    if (-not (Test-Path $path)) { return $null }
    try {
        $config = Get-Content $path -Raw -Encoding UTF8 | ConvertFrom-Json
        if ($config.install_path) { return $config }
    }
    catch {
        # Corrupted config — treat as missing
    }
    return $null
}

function Get-Config {
    # Canonical probe: stack folder. If its install_path differs from the
    # current $BASE, re-point $BASE and re-read (covers a moved/custom stack).
    $canonical = Get-ConfigFilePath
    $config = Read-ConfigFile $canonical
    if ($config -and $config.install_path -and ([string]$config.install_path -ne $BASE)) {
        $script:BASE = [string]$config.install_path
        $config = Read-ConfigFile (Get-ConfigFilePath)
    }
    if ($config) { return $config }

    # Discovery pointer (pre-1.2.0 location, kept fresh by Save-Config):
    # tells us where the stack lives when $BASE is wrong/unknown. If it still
    # holds a full pre-1.2.0 config (no canonical yet), migrate it over.
    if (Test-Path $CONFIG_FILE_LEGACY) {
        $legacy = Read-ConfigFile $CONFIG_FILE_LEGACY
        if ($legacy -and $legacy.install_path) {
            $script:BASE = [string]$legacy.install_path
            $canonical = Get-ConfigFilePath
            if (-not (Test-Path $canonical)) {
                $configDir = Split-Path $canonical -Parent
                if (-not (Test-Path $configDir)) {
                    New-Item -ItemType Directory -Force -Path $configDir | Out-Null
                }
                Copy-Item $CONFIG_FILE_LEGACY $canonical -Force
                Write-Info "Migrated phpup config to $canonical"
            }
            $result = Read-ConfigFile $canonical
            if ($result) { return $result }
            # Canonical exists but is corrupt — fall back to the pointer's copy
            return $legacy
        }
    }
    return $null
}

function Save-Config {
    param(
        [Parameter(Mandatory=$true)]
        [string]$InstallPath,

        $Versions,

        [string[]]$PathEntries,

        [bool]$ServicesRegistered = $false,

        # Pass the current fu download floor to avoid re-reading the config
        # just to preserve it. When omitted, an existing value is preserved
        # (fallback for old callers) and the 8.2 default persists otherwise.
        [string]$MinSeries = $null
    )

    $configFile = Get-ConfigFilePath
    $configDir = Split-Path $configFile -Parent
    if (-not (Test-Path $configDir)) {
        New-Item -ItemType Directory -Force -Path $configDir | Out-Null
    }

    # Preserve the fu download floor (php_min_series): keep an existing
    # user-set value, else persist the 8.2 default so it is visible/editable.
    $minSeries = $MinSeries
    if (-not $minSeries) {
        $existingConfig = Get-Config
        if ($existingConfig -and $existingConfig.php_min_series) {
            $minSeries = [string]$existingConfig.php_min_series
        }
        else {
            $minSeries = '8.2'
        }
    }

    # Start with base structure (always fresh)
    $config = [ordered]@{
        install_path        = $InstallPath
        installed_at        = (Get-Date -Format "yyyy-MM-ddTHH:mm:ss")
        services_registered = $ServicesRegistered
        php_min_series      = $minSeries
        paths               = @{
            apache     = "$InstallPath\apache"
            php        = "$InstallPath\php"
            mariadb    = "$InstallPath\mariadb"
            www        = "$InstallPath\www"
            phpmyadmin = "$InstallPath\phpmyadmin"
        }
    }

    if ($Versions) {
        if ($Versions -is [hashtable]) {
            $config.versions = [PSCustomObject]$Versions
        }
        else {
            # Convert from PSCustomObject (JSON round-trip)
            $v = @{}
            foreach ($prop in $Versions.PSObject.Properties) {
                $v[$prop.Name] = $prop.Value
            }
            $config.versions = [PSCustomObject]$v
        }
    }
    if ($PathEntries) { $config.path_entries = $PathEntries }

    $config | ConvertTo-Json -Depth 4 | Out-File $configFile -Encoding UTF8

    # Keep the discovery pointer fresh so a moved/custom stack is still
    # findable when $BASE is wrong on a future run. Only needed for
    # non-default install paths — the default C:\phpup is probed directly.
    if ($InstallPath -ne $DEFAULT_BASE) {
        $legacyDir = Split-Path $CONFIG_FILE_LEGACY -Parent
        if (-not (Test-Path $legacyDir)) {
            New-Item -ItemType Directory -Force -Path $legacyDir | Out-Null
        }
        @{ install_path = $InstallPath } | ConvertTo-Json | Out-File $CONFIG_FILE_LEGACY -Encoding UTF8
    }
}

function Clear-Config {
    if (Test-Path (Get-ConfigFilePath)) {
        Remove-Item (Get-ConfigFilePath) -Force
    }
    if (Test-Path $CONFIG_FILE_LEGACY) {
        Remove-Item $CONFIG_FILE_LEGACY -Force
    }
}

# ---- PATH Management -----------------------------------------

function Add-ToPath {
    <#
    .SYNOPSIS
    Adds PHP and MariaDB bin directories to the user PATH.
    Removes any previous webstack entries stored in config first.
    #>
    $phpBin    = "$BASE\php"
    $mariadbBin = "$BASE\mariadb\bin"

    $currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
    $entries = if ($currentPath) { $currentPath -split ';' | Where-Object { $_ } } else { @() }

    # Remove old webstack entries (from previous install at a different path)
    $oldEntries = @()
    $savedConfig = Get-Config
    if ($savedConfig -and $savedConfig.path_entries) {
        $oldEntries = $savedConfig.path_entries
        $entries = $entries | Where-Object { $oldEntries -notcontains $_ }
    }

    # Build list of new entries to add (avoid duplicates)
    $toAdd = @()
    foreach ($p in @($phpBin, $mariadbBin)) {
        if ($entries -notcontains $p) {
            $toAdd += $p
            Write-Ok "Added to PATH: $p"
        }
    }

    if ($toAdd.Count -eq 0) {
        Write-Info "PATH entries already present"
        return @()
    }

    $newPath = (@($entries) + @($toAdd)) -join ';'
    [Environment]::SetEnvironmentVariable("PATH", $newPath, "User")

    # Also update the current session
    $env:PATH = $newPath

    return $toAdd
}

function Remove-FromPath {
    <#
    .SYNOPSIS
    Removes webstack PATH entries (PHP + MariaDB bin) from the user PATH.
    #>
    $toRemove = @("$BASE\php", "$BASE\mariadb\bin")

    $currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
    if (-not $currentPath) { return }

    $entries = $currentPath -split ';' | Where-Object { $_ } | Where-Object { $toRemove -notcontains $_ }
    $newPath = $entries -join ';'

    [Environment]::SetEnvironmentVariable("PATH", $newPath, "User")
    $env:PATH = $newPath

    Write-Ok "Webstack entries removed from PATH"
}

# ---- VC++ Redistributable Check ------------------------------

function Test-VcRedistInstalled {
# Checks whether Visual C++ Redistributable 14.51+ (VS 2017-2026) x64 is installed.
# Required by Apache Lounge VS18 and MariaDB 12.x.
    $minVersion = $VC_MIN_VERSION

    $uninstallPaths = @(
        "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
        "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
    )

    foreach ($path in $uninstallPaths) {
        $items = Get-ItemProperty -Path $path -ErrorAction SilentlyContinue |
            Where-Object { $_.DisplayName -match "Microsoft Visual C\+\+ .*Redistributable.*x64" }

        foreach ($item in $items) {
            if ($item.DisplayVersion) {
                try {
                    $ver = [version]$item.DisplayVersion
                    if ($ver -ge $minVersion) {
                        return $true
                    }
                }
                catch {
                    # Version string couldn't be parsed — skip this entry
                }
            }
        }
    }
    return $false
}

function Get-VcRedistVersion {
# Returns the installed VC++ Redistributable version, or $null if not found.
    $uninstallPaths = @(
        "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
        "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
    )
    $latest = [version]"0.0.0.0"
    foreach ($path in $uninstallPaths) {
        $items = Get-ItemProperty -Path $path -ErrorAction SilentlyContinue |
            Where-Object { $_.DisplayName -match "Microsoft Visual C\+\+ .*Redistributable.*x64" }
        foreach ($item in $items) {
            if ($item.DisplayVersion) {
                try {
                    $ver = [version]$item.DisplayVersion
                    if ($ver -gt $latest) { $latest = $ver }
                } catch { }
            }
        }
    }
    if ($latest -eq [version]"0.0.0.0") { return $null }
    return $latest
}

function Install-VcRedist {
# Installs or upgrades the Visual C++ Redistributable (VS 2017-2026) x64.
# Uses winget (handles upgrades correctly where the direct installer skips them).
    if (Test-VcRedistInstalled) {
        Write-Ok "Visual C++ Redistributable already meets minimum version requirement"
        return
    }

    Write-Info "Installing/upgrading Visual C++ Redistributable (VS 2017-2026) x64..."

    # winget handles upgrades correctly (direct installer skips when already present).
    # The stack is x64-only, so force x64 even on ARM64 hosts (x64 binaries run
    # under emulation there and still need the x64 runtime — the arm64 redist is
    # for native ARM64 apps, which this stack has none of).
    $winget = Get-Command winget.exe -ErrorAction SilentlyContinue
    if ($winget) {
        $proc = Start-Process -FilePath 'winget.exe' -ArgumentList @(
            'install', '--id', 'Microsoft.VCRedist.2015+.x64',
            '--architecture', 'x64',
            '--exact', '--silent', '--accept-package-agreements', '--accept-source-agreements'
        ) -Wait -PassThru -NoNewWindow

        if ($proc.ExitCode -eq 0) {
            Write-Ok "Visual C++ Redistributable installed/upgraded via winget"
            return
        }
        Write-Warn "winget exited with code $($proc.ExitCode). Trying direct download..."
    }

    # Fallback: direct download (for systems without winget)
    $installer = "$DOWNLOAD_CACHE\vc_redist.x64.exe"
    New-Item -ItemType Directory -Force -Path $DOWNLOAD_CACHE | Out-Null

    if (Test-Path $installer) {
        Write-Ok "VC++ Redistributable installer already cached — using $installer"
    }
    else {
        try {
            Invoke-WebRetry -Uri $FALLBACK_URLS.Redist -OutFile $installer -MaxRetries 3 -RetryDelay 5
        }
        catch {
            Write-Err "Failed to download VC++ Redistributable after 3 attempts: $_"
            Write-Info "Install manually: $($FALLBACK_URLS.Redist)"
            return
        }
    }

    Write-Info "Running installer (silent -- this may take a moment)..."
    $proc = Start-Process -FilePath $installer -ArgumentList "/install", "/quiet", "/norestart" -Wait -PassThru
    if ($proc.ExitCode -eq 0 -or $proc.ExitCode -eq 3010) {
        Write-Ok "Visual C++ Redistributable installed successfully"
    }
    else {
        Write-Warn "Installer exited with code $($proc.ExitCode). Install manually:"
        Write-Info "  $($FALLBACK_URLS.Redist)"
    }
}

# ---- Network helpers ------------------------------------------------
# Retry wrappers around Invoke-WebRequest / Invoke-RestMethod. Set TLS12,
# retry with a delay, and throw after the final attempt so callers keep
# their own terminal behaviour (fallback URL, cached-only, hard failure).
function Invoke-WebRetry {
    param(
        [string]$Uri,
        [hashtable]$Headers = @{},
        [string]$OutFile = '',
        [int]$MaxRetries = 3,
        [int]$RetryDelay = 5
    )
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    for ($attempt = 1; $attempt -le $MaxRetries; $attempt++) {
        try {
            if ($attempt -gt 1) { Write-Info "  Retry $attempt of $MaxRetries..." }
            if ($OutFile) {
                # Try with progress first; fall back when IE parsing is unavailable
                try {
                    Invoke-WebRequest -Uri $Uri -OutFile $OutFile -Headers $Headers -ErrorAction Stop
                }
                catch [System.Management.Automation.MethodInvocationException] {
                    Invoke-WebRequest -Uri $Uri -OutFile $OutFile -UseBasicParsing -Headers $Headers -ErrorAction Stop
                }
                return
            }
            return Invoke-WebRequest -Uri $Uri -UseBasicParsing -Headers $Headers -ErrorAction Stop
        }
        catch {
            if ($attempt -lt $MaxRetries) {
                Write-Warn "  Attempt $attempt failed: $($_.Exception.Message)"
                Write-Info "  Retrying in $RetryDelay seconds..."
                if ($OutFile) {
                    # Drop the partial download so the next attempt starts clean
                    [System.GC]::Collect()
                    [System.GC]::WaitForPendingFinalizers()
                    Remove-Item $OutFile -Force -ErrorAction SilentlyContinue
                }
                Start-Sleep -Seconds $RetryDelay
            }
            else {
                throw
            }
        }
    }
}

function Invoke-RestRetry {
    param(
        [string]$Uri,
        [int]$MaxRetries = 3,
        [int]$RetryDelay = 5
    )
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    for ($attempt = 1; $attempt -le $MaxRetries; $attempt++) {
        try {
            return Invoke-RestMethod -Uri $Uri -ErrorAction Stop
        }
        catch {
            if ($attempt -lt $MaxRetries) {
                Write-Warn "Attempt $attempt failed: $($_.Exception.Message)"
                Write-Info "  Retrying in $RetryDelay seconds..."
                Start-Sleep -Seconds $RetryDelay
            }
            else {
                throw
            }
        }
    }
}

# ============================================================
#  URL RESOLUTION — Latest Stable Versions
# ============================================================

function Get-LatestApacheUrl {
    Write-Info "Resolving Apache (Apache Lounge - latest VS18 x64 build)..."

    try {
        $html = Invoke-WebRetry -Uri "https://www.apachelounge.com/download/" -Headers @{ "User-Agent" = $UA_STRING } -MaxRetries 3 -RetryDelay 5

        $bestScore = $null
        $bestUrl   = $null

        # Match Apache Lounge download links: /download/VS##/binaries/httpd-X.Y.Z-BUILD-Win64-VS##.zip
        $pattern = 'href="(/download/VS(\d+)/binaries/httpd-([\d.]+)-(\d+)-Win64-VS\d+\.zip)"'
        $rxMatches = [regex]::Matches($html.Content, $pattern)

        foreach ($m in $rxMatches) {
            $vsVer    = [int]$m.Groups[2].Value
            $httpdVer = $m.Groups[3].Value
            $build    = [int]$m.Groups[4].Value

            # Prefer VS18 (VS2022), fall back to VS17
            $score = ($vsVer * 1000000) + ([version]$httpdVer).Major * 10000 + ([version]$httpdVer).Minor * 100 + $build

            if ($null -eq $bestScore -or $score -gt $bestScore) {
                $bestScore = $score
                $bestUrl   = "https://www.apachelounge.com" + $m.Groups[1].Value
            }
        }

        if ($bestUrl) {
            Write-Ok "Apache -> $bestUrl"
            return $bestUrl
        }

        throw "No Apache Lounge VS18 x64 download found"
    }
    catch {
        Write-Warn "Live resolution failed after 3 attempts."
        if ($FALLBACK_URLS.Apache) {
            Write-Info "  Falling back to pinned Apache URL: $($FALLBACK_URLS.Apache)"
            return $FALLBACK_URLS.Apache
        }
        Write-Err "Failed to resolve Apache URL and no fallback URL is configured."
        Write-Info "  Check https://www.apachelounge.com/ or try again later."
        throw
    }
}

function Get-LatestPhpUrl {
    Write-Info "Resolving PHP (latest 8.x stable, thread-safe x64 - preferring VS17)..."

    try {
        $json = Invoke-RestRetry -Uri "https://windows.php.net/downloads/releases/releases.json" -MaxRetries 3 -RetryDelay 5

        $latestVs17Version = $null
        $latestVs17File    = $null
        $latestVs16Version = $null
        $latestVs16File    = $null

        foreach ($key in $json.PSObject.Properties.Name) {
            $entry = $json.$key

            if (-not $entry.version) { continue }
            if ($entry.version -notmatch '^8\.\d+\.\d+$') { continue }

            # Check VS17 thread-safe x64 (newer PHP 8.5+)
            if ($entry.'ts-vs17-x64') {
                $ver = [version]$entry.version
                if ($null -eq $latestVs17Version -or $ver -gt $latestVs17Version) {
                    $latestVs17Version = $ver
                    $latestVs17File    = $entry.'ts-vs17-x64'.zip.path
                }
            }

            # Check VS16 thread-safe x64 (fallback)
            if ($entry.'ts-vs16-x64') {
                $ver = [version]$entry.version
                if ($null -eq $latestVs16Version -or $ver -gt $latestVs16Version) {
                    $latestVs16Version = $ver
                    $latestVs16File    = $entry.'ts-vs16-x64'.zip.path
                }
            }
        }

        # Prefer VS17, fall back to VS16
        if ($latestVs17File) {
            $url = "https://windows.php.net/downloads/releases/$latestVs17File"
            Write-Ok "PHP $latestVs17Version (VS17) -> $url"
            return $url
        }
        elseif ($latestVs16File) {
            $url = "https://windows.php.net/downloads/releases/$latestVs16File"
            Write-Ok "PHP $latestVs16Version (VS16) -> $url"
            return $url
        }

        throw "No compatible PHP 8.x TS x64 build found (VS17 or VS16)"
    }
    catch {
        Write-Warn "Live resolution failed after 3 attempts."
        if ($FALLBACK_URLS.PHP) {
            Write-Info "  Falling back to pinned PHP URL: $($FALLBACK_URLS.PHP)"
            return $FALLBACK_URLS.PHP
        }
        Write-Err "Failed to resolve PHP URL and no fallback URL is configured."
        Write-Info "  Check https://windows.php.net/ or try again later."
        throw
    }
}

function Get-PhpReleasesJson {
# Fetches windows.php.net releases.json once. Returns $null if unreachable.
    try {
        return Invoke-RestRetry -Uri "https://windows.php.net/downloads/releases/releases.json" -MaxRetries 3 -RetryDelay 5
    }
    catch {
        Write-Warn "Could not reach windows.php.net — running with cached versions only."
        return $null
    }
}

function Resolve-PhpSeriesUrl($json, [string]$series) {
# Returns the latest stable TS x64 zip for one PHP series (e.g. "8.4")
# from an already-fetched releases.json. Prefers VS17, falls back to VS16,
# then VC15 (the toolchain used for 7.x builds). Returns $null if the series
# has no stable build.
    $entry = $json.$series
    if (-not $entry -or -not $entry.version) { return $null }
    if ($entry.version -notmatch '^\d+\.\d+\.\d+$') { return $null }  # not a stable patch

    # Prefer VS17, fall back to VS16, then VC15 (7.x)
    foreach ($key in @('ts-vs17-x64', 'ts-vs16-x64', 'ts-vc15-x64')) {
        if ($entry.$key -and $entry.$key.zip) {
            $path = $entry.$key.zip.path
            return @{
                Version = $entry.version
                Url     = "https://windows.php.net/downloads/releases/$path"
                File    = $path
            }
        }
    }
    return $null
}

function Get-LatestMariadbUrl {
    Write-Info "Resolving MariaDB (latest stable, Windows x64)..."

    try {
        $json = Invoke-RestRetry -Uri "https://downloads.mariadb.org/rest-api/mariadb/" -MaxRetries 5 -RetryDelay 8

        $candidates = $json.major_releases | Where-Object { $_.release_status -eq "Stable" }

        if (-not $candidates) {
            throw "No Stable MariaDB releases found"
        }

        # Prefer Rolling, then LTS, then others; pick newest
        $best = $candidates |
            Sort-Object @{
                Expression = {
                    if ($_.release_support_type -eq "Rolling") { 2 }
                    elseif ($_.release_support_type -like "*Long Term Support*") { 1 }
                    else { 0 }
                }
            }, @{ Expression = { [version]$_.release_id } } -Descending |
            Select-Object -First 1

        $version = $best.release_id
        Write-Info "Selected MariaDB $version ($($best.release_support_type))"

        # Fetch version details
        $detail = Invoke-RestRetry -Uri "https://downloads.mariadb.org/rest-api/mariadb/$version/" -MaxRetries 5 -RetryDelay 8

        $releaseKeys = $detail.releases.PSObject.Properties.Name |
            Sort-Object { [version]$_ } -Descending

        foreach ($key in $releaseKeys) {
            $release = $detail.releases.$key
            foreach ($file in $release.files) {
                $name = $file.file_name.ToLower()
                if ($name -like "*winx64*" -and $name -like "*.zip" -and $name -notlike "*debugsymbols*") {
                    # Construct direct archive URL — bypass REST API redirector
                    $archiveUrl = "https://archive.mariadb.org/mariadb-$version/winx64-packages/$($file.file_name)"
                    Write-Ok "MariaDB -> $archiveUrl"
                    return $archiveUrl
                }
            }
        }

        throw "Could not resolve MariaDB Windows x64 download URL"
    }
    catch {
        Write-Warn "Live resolution failed after 5 attempts."
        if ($FALLBACK_URLS.MariaDB) {
            Write-Info "  Falling back to pinned MariaDB URL: $($FALLBACK_URLS.MariaDB)"
            return $FALLBACK_URLS.MariaDB
        }
        Write-Err "Failed to resolve MariaDB URL and no fallback URL is configured."
        Write-Info "  Check https://mariadb.org/download/ or try again later."
        throw
    }
}

function Get-LatestPhpMyAdminUrl {
    Write-Info "Resolving phpMyAdmin (latest stable, all-languages)..."

    try {
        $html = Invoke-WebRetry -Uri "https://www.phpmyadmin.net/downloads/" -Headers @{ "User-Agent" = $UA_STRING } -MaxRetries 3 -RetryDelay 5

        $bestVersion = $null
        $bestUrl     = $null

        # Match stable releases only (not snapshots)
        $pattern = 'href="(https://files\.phpmyadmin\.net/phpMyAdmin/([\d.]+)/phpMyAdmin-[\d.]+-all-languages\.zip)"'
        $rxMatches = [regex]::Matches($html.Content, $pattern)

        foreach ($m in $rxMatches) {
            $url = $m.Groups[1].Value
            $ver = $m.Groups[2].Value

            # Skip snapshots
            if ($url -match "snapshot") { continue }

            if ($null -eq $bestVersion -or [version]$ver -gt [version]$bestVersion) {
                $bestVersion = $ver
                $bestUrl     = $url
            }
        }

        if ($bestUrl) {
            Write-Ok "phpMyAdmin $bestVersion -> $bestUrl"
            return $bestUrl
        }

        throw "No phpMyAdmin stable download found"
    }
    catch {
        Write-Warn "Live resolution failed after 3 attempts."
        if ($FALLBACK_URLS.phpMyAdmin) {
            Write-Info "  Falling back to pinned phpMyAdmin URL: $($FALLBACK_URLS.phpMyAdmin)"
            return $FALLBACK_URLS.phpMyAdmin
        }
        Write-Err "Failed to resolve phpMyAdmin URL and no fallback URL is configured."
        Write-Info "  Check https://www.phpmyadmin.net/ or try again later."
        throw
    }
}

# ============================================================
#  DOWNLOAD & EXTRACT
# ============================================================

function Invoke-DownloadToCache($url, $label) {
# Downloads a zip into the download cache without extracting (used by fu).
# Returns the full cache path, or $null on failure. Uses the cached copy if present.
    New-Item -ItemType Directory -Force -Path $DOWNLOAD_CACHE | Out-Null
    $filename = [IO.Path]::GetFileName($url)
    $zipPath  = Join-Path $DOWNLOAD_CACHE $filename

    if (Test-Path $zipPath) {
        Write-Ok "$label zip already cached — using $filename"
        return $zipPath
    }

    try {
        Invoke-WebRetry -Uri $url -OutFile $zipPath -Headers @{ "User-Agent" = $UA_STRING } -MaxRetries 3 -RetryDelay 5
        Write-Ok "Downloaded $label -> $filename"
        return $zipPath
    }
    catch {
        Write-Err "Download failed for $label after 3 attempts: $($_.Exception.Message)"
        return $null
    }
}

function Invoke-DownloadAndExtract($url, $dest, $label) {
    Write-Host ""
    Write-Host "Downloading $label..." -ForegroundColor Yellow
    Write-Info "  $url"

    New-Item -ItemType Directory -Force -Path $DOWNLOAD_CACHE | Out-Null
    New-Item -ItemType Directory -Force -Path $dest | Out-Null

    $filename = [IO.Path]::GetFileName($url)
    $zipPath  = Join-Path $DOWNLOAD_CACHE $filename

    # Check if we already have this exact version cached
    if (Test-Path $zipPath) {
        Write-Ok "$label zip already cached — using $filename"
        Write-Info "Extracting to $dest..."
        # Expand-Archive renders progress ("Expanding X of Y files") that
        # flashes over the dashboard; downloads keep theirs.
        $prevProgress = $ProgressPreference
        $ProgressPreference = 'SilentlyContinue'
        try {
            Expand-Archive -Path $zipPath -DestinationPath $dest -Force -ErrorAction Stop
        }
        catch {
            $ProgressPreference = $prevProgress
            throw "$label extraction failed (files locked by a running service?): $($_.Exception.Message)"
        }
        $ProgressPreference = $prevProgress
    } else {
        try {
            Invoke-WebRetry -Uri $url -OutFile $zipPath -Headers @{ "User-Agent" = $UA_STRING } -MaxRetries 3 -RetryDelay 5
        }
        catch {
            Write-Progress -Activity "Downloading $label" -Completed
            throw "Download failed for $label after 3 attempts: $($_.Exception.Message)"
        }

        if (-not (Test-Path $zipPath)) {
            throw "Download failed - file not found: $zipPath"
        }

        Write-Info "Extracting to $dest..."
        $prevProgress = $ProgressPreference
        $ProgressPreference = 'SilentlyContinue'
        try {
            Expand-Archive -Path $zipPath -DestinationPath $dest -Force -ErrorAction Stop
        }
        catch {
            $ProgressPreference = $prevProgress
            throw "$label extraction failed (files locked by a running service?): $($_.Exception.Message)"
        }
        $ProgressPreference = $prevProgress
    }

    # Flatten wrapper folder if present.
    # Apache Lounge = Apache24/  |  PHP = php-8.x.x-Win32-vs17-x64/
    # MariaDB = mariadb-12.x.x-winx64/  |  phpMyAdmin = phpMyAdmin-x.x.x-all-languages/
    $allItems = @(Get-ChildItem $dest -Force)
    $dirsOnly = @($allItems | Where-Object { $_ -is [System.IO.DirectoryInfo] })
    $filesOnly = @($allItems | Where-Object { $_ -is [System.IO.FileInfo] })

    # Strategy: if there's exactly one directory and no loose files, flatten it
    if ($dirsOnly.Count -eq 1 -and $filesOnly.Count -eq 0) {
        $inner = $dirsOnly[0].FullName
        Write-Info "Flattening wrapper folder: $($dirsOnly[0].Name)"
        Get-ChildItem $inner -Force | ForEach-Object {
            Move-Item $_.FullName $dest -Force -ErrorAction SilentlyContinue
        }
        Remove-Tree $inner
    }
    elseif ($dirsOnly.Count -ge 1) {
        # Multiple directories or mixed files/dirs — try to find known wrapper patterns
        $knownWrappers = @('Apache24', 'php-*', 'mariadb-*', 'phpMyAdmin-*')
        foreach ($pattern in $knownWrappers) {
            $match = @($dirsOnly | Where-Object { $_.Name -like $pattern })
            if ($match.Count -eq 1) {
                $inner = $match[0].FullName
                Write-Info "Flattening wrapper folder: $($match[0].Name)"
                Get-ChildItem $inner -Force | ForEach-Object {
                    Move-Item $_.FullName $dest -Force -ErrorAction SilentlyContinue
                }
                Remove-Tree $inner
                break
            }
        }
    }

    if (-not (Get-ChildItem $dest -Force -ErrorAction SilentlyContinue | Select-Object -First 1)) {
        throw "$label extraction produced no files in $dest"
    }

    Write-Ok "$label extracted"
}

# Offline-only: extract a pre-downloaded zip directly (no download step).
function Invoke-ExtractZip($zipPath, $dest, $label) {
    $prevProgress = $ProgressPreference
    $ProgressPreference = 'SilentlyContinue'

    Write-Host ""
    Write-Info "Extracting $label from $zipPath..."
    # -ErrorAction Stop matters: Expand-Archive's failure is NON-terminating by
    # default, so a locked file (a running httpd holding php8ts.dll and the
    # loaded extension DLLs) used to sail straight through to "[ OK ] extracted"
    # and leave a half-old/half-new tree behind.
    try {
        Expand-Archive -Path $zipPath -DestinationPath $dest -Force -ErrorAction Stop
    }
    catch {
        $ProgressPreference = $prevProgress
        Write-Err "$label extraction FAILED: $($_.Exception.Message)"
        Write-Info "  A partial extract usually means files were locked by a running service."
        Write-Info "  Stop the stack, then re-run the install."
        return $false
    }

    if (-not (Get-ChildItem $dest -Force -ErrorAction SilentlyContinue | Select-Object -First 1)) {
        $ProgressPreference = $prevProgress
        Write-Err "$label extraction produced no files in $dest"
        return $false
    }

    # Flatten wrapper folder if present
    $allItems = @(Get-ChildItem $dest -Force)
    $dirsOnly = @($allItems | Where-Object { $_ -is [System.IO.DirectoryInfo] })
    $filesOnly = @($allItems | Where-Object { $_ -is [System.IO.FileInfo] })

    if ($dirsOnly.Count -eq 1 -and $filesOnly.Count -eq 0) {
        $inner = $dirsOnly[0].FullName
        Write-Info "Flattening wrapper folder: $($dirsOnly[0].Name)"
        Get-ChildItem $inner -Force | ForEach-Object {
            Move-Item $_.FullName $dest -Force -ErrorAction SilentlyContinue
        }
        Remove-Item $inner -Recurse -Force -ErrorAction SilentlyContinue
    }
    elseif ($dirsOnly.Count -ge 1) {
        # Multiple directories or mixed files/dirs — try known wrapper patterns
        $knownWrappers = @('Apache24', 'php-*', 'mariadb-*', 'phpMyAdmin-*')
        foreach ($pattern in $knownWrappers) {
            $match = @($dirsOnly | Where-Object { $_.Name -like $pattern })
            if ($match.Count -eq 1) {
                $inner = $match[0].FullName
                Write-Info "Flattening wrapper folder: $($match[0].Name)"
                Get-ChildItem $inner -Force | ForEach-Object {
                    Move-Item $_.FullName $dest -Force -ErrorAction SilentlyContinue
                }
                Remove-Item $inner -Recurse -Force -ErrorAction SilentlyContinue
                break
            }
        }
    }

    $ProgressPreference = $prevProgress
    Write-Ok "$label extracted"
    return $true
}

# ============================================================
#  CONFIGURATION
# ============================================================

function Get-PhpApacheModuleName([string]$version = (Get-PhpVersion)) {
# Apache module DLL for a PHP major version: php7apache2_4.dll for 7.x,
# php8apache2_4.dll for 8.x (the file name differs per major).
    if ($version -match '^7\.') { return 'php7apache2_4.dll' }
    return 'php8apache2_4.dll'
}

function Get-PhpApacheModuleSymbol([string]$version = (Get-PhpVersion)) {
# LoadModule directive name for a PHP major version. Apache matches the
# directive name to the symbol exported by the module DLL, and the exports
# differ: php7apache2_4.dll exports php7_module, php8apache2_4.dll exports
# php_module (that is the symbol the official docs use for PHP 8+).
    if ($version -match '^7\.') { return 'php7_module' }
    return 'php_module'
}

function Test-PhpApacheModuleWired {
# True when httpd.conf references the PHP LoadModule line for the CURRENT
# installed PHP major AND the DLL it points at exists. Catches a broken
# version switch: php.exe may exist while the LoadModule line still names
# the previous major's DLL (or a path that no longer exists).
    $confPath = "$APACHE_PATH\conf\httpd.conf"
    if (-not (Test-Path $confPath)) { return $false }
    $conf = Get-Content $confPath -Raw -ErrorAction SilentlyContinue
    if (-not $conf) { return $false }
    $symbol = Get-PhpApacheModuleSymbol
    if ($conf -match "LoadModule\s+$symbol\s+`"([^`"]+)`"") {
        return Test-Path $matches[1]
    }
    return $false
}

function Invoke-ConfigureApache {
    Write-Host ""
    Write-Warn "Configuring Apache..."

    $confPath = "$APACHE_PATH\conf\httpd.conf"

    if (-not (Test-Path $confPath)) {
        Write-Err "httpd.conf not found at $confPath"
        return
    }

    # Backup original
    Copy-Item $confPath "$confPath.bak" -Force

    $conf = Get-Content $confPath -Raw

    # Normalise line endings — .NET (?m)$ only matches before \n, not \r\n
    $conf = $conf -replace "`r`n", "`n"

    $wwwUnix  = $WWW_PATH -replace '\\', '/'
    $apacheUnix = $APACHE_PATH -replace '\\', '/'

    # 1. Set ServerRoot and SRVROOT
    $newSrvRoot = "Define SRVROOT `"$apacheUnix`""
    if ($conf -match '(?m)^Define SRVROOT') {
        $conf = $conf -replace '(?m)^Define SRVROOT ".*"$', $newSrvRoot
    }
    else {
        $conf = $newSrvRoot + "`r`n" + $conf
    }

    # Also fix literal ServerRoot (some configs don't use ${SRVROOT})
    $conf = $conf -replace '(?m)^ServerRoot\s+".*"', "ServerRoot `"$apacheUnix`""
    Write-Ok "ServerRoot configured"

    # 2. Listen on port 80 — exactly one directive
    # Remove every existing Listen line, then append a single Listen 80.
    # Idempotent AND self-healing: a file with duplicate Listen lines (e.g.
    # from an older buggy run) is collapsed to one on the next configure.
    $conf = [regex]::Replace($conf, '(?m)^Listen\s+\d+[^\r\n]*(?:\r\n|\n|$)', '')
    $conf += "`r`nListen 80`r`n"
    Write-Ok "Port 80 configured"

    # 2b. Set ServerName to suppress AH00558 warnings
    $conf = $conf -replace '(?m)^#ServerName\s+.*$', 'ServerName localhost:80'
    Write-Ok "ServerName set to localhost:80"

    # 3. DocumentRoot
    $oldDocRoot = ''
    if ($conf -match 'DocumentRoot\s+"([^"]*)"') { $oldDocRoot = $Matches[1] }
    $conf = $conf -replace 'DocumentRoot\s+".*"', "DocumentRoot `"$wwwUnix`""
    Write-Ok "DocumentRoot set to $WWW_PATH"

    # 4. Directory block for www — rewrite ONLY the old DocumentRoot's own
    # <Directory> block. A blanket '<Directory\s+"…">' replace rewrites EVERY
    # quoted Directory block (cgi-bin, and phpMyAdmin's on a re-run), which
    # orphans phpMyAdmin's grant → 403 (Apache 2.4 "Require all denied").
    if ($oldDocRoot) {
        $oldDocEscaped = [regex]::Escape($oldDocRoot)
        $conf = $conf -replace "<Directory\s+`"$oldDocEscaped`">", "<Directory `"$wwwUnix`">"
    }

    # 5. DirectoryIndex - PHP first
    $conf = $conf -replace '(DirectoryIndex\s+)index\.html', '${1}index.php index.html'
    Write-Ok "DirectoryIndex: index.php before index.html"

    # 6. Enable mod_rewrite (handle both "#LoadModule" and "# LoadModule" variants)
    $conf = $conf -replace '#\s*LoadModule rewrite_module modules/mod_rewrite\.so', 'LoadModule rewrite_module modules/mod_rewrite.so'
    Write-Ok "mod_rewrite enabled"

    # 7. AllowOverride All
    $conf = $conf -replace 'AllowOverride None', 'AllowOverride All'
    Write-Ok "AllowOverride All"

    # 7b. Ensure Options FollowSymLinks (required for mod_rewrite in .htaccess)
    # The default Apache Lounge config has this, but some variants may set Options None
    $wwwBlockStart = [regex]::Escape("<Directory `"$wwwUnix`">")
    $optionsPattern = "$wwwBlockStart[\s\S]*?Options\s+"
    $newConf = $conf -replace "($optionsPattern)\S+", '${1}Indexes FollowSymLinks'
    if ($newConf -ne $conf) {
        $conf = $newConf
        Write-Ok "Options Indexes FollowSymLinks set"
    }

    # 8. PHP integration — module DLL name AND LoadModule symbol depend on the
    # PHP major version (7.x: php7apache2_4.dll/php7_module; 8.x: php8apache2_4.dll/
    # php_module). Rewrite the existing line when present so version switches
    # keep Apache loadable.
    $phpModuleName   = Get-PhpApacheModuleName
    $phpModuleSymbol = Get-PhpApacheModuleSymbol
    $phpModuleUnix   = "$($PHP_PATH -replace '\\','/')/$phpModuleName"
    $phpIniUnix      = $PHP_PATH -replace '\\','/'

    $newConf = $conf -replace 'LoadModule\s+php\d*_module\s+"[^"]*"', "LoadModule $phpModuleSymbol `"$phpModuleUnix`""
    if ($newConf -ne $conf) {
        $conf = $newConf
        Write-Ok "PHP module updated to $phpModuleName ($phpModuleSymbol)"
    }
    elseif ($conf -notmatch 'php\d*_module') {
        $phpBlock = @"

# PHP integration (phpup)
LoadModule $phpModuleSymbol "$phpModuleUnix"
AddHandler application/x-httpd-php .php
PHPIniDir "$phpIniUnix"
"@
        $conf += $phpBlock
        Write-Ok "PHP module loaded"
    }
    else {
        Write-Ok "PHP module already configured"
    }

    # 9. phpMyAdmin Alias + access grant (self-healing)
    #    The Alias alone is not enough on Apache 2.4 — a matching <Directory>
    #    block with "Require all granted" is required, or the root "Require all
    #    denied" applies and phpMyAdmin 403s. Add whichever piece is missing.
    $pmaUnix = $PHPMYADMIN_PATH -replace '\\', '/'
    if ($conf -notmatch 'Alias /phpmyadmin') {
        $conf += "`r`n# phpMyAdmin (phpup)`r`nAlias /phpmyadmin `"$pmaUnix`"`r`n"
    }
    if ($conf -notmatch "<Directory\s+`"$pmaUnix`">") {
        $conf += "<Directory `"$pmaUnix`">`r`n    Options Indexes FollowSymLinks MultiViews`r`n    AllowOverride All`r`n    Require all granted`r`n</Directory>`r`n"
    }
    Write-Ok "phpMyAdmin alias configured"

    # 10. Error/access logs in logs folder
    $logsUnix = $LOGS_PATH -replace '\\', '/'
    $conf = $conf -replace 'ErrorLog\s+".*"', "ErrorLog `"$logsUnix/apache_error.log`""
    $conf = $conf -replace 'CustomLog\s+".*"\s+common', "CustomLog `"$logsUnix/apache_access.log`" common"
    Write-Ok "Log files directed to $LOGS_PATH"

    Set-Content -Path $confPath -Value $conf
    Write-Ok "Apache configuration complete"
}

function Invoke-ConfigurePhp {
    Write-Host ""
    Write-Warn "Configuring PHP..."

    $iniDev = Get-ChildItem "$PHP_PATH" -Filter "php.ini-development" -ErrorAction SilentlyContinue | Select-Object -First 1
    $iniProd = Get-ChildItem "$PHP_PATH" -Filter "php.ini-production" -ErrorAction SilentlyContinue | Select-Object -First 1

    $iniSrc = if ($iniDev) { $iniDev.FullName } elseif ($iniProd) { $iniProd.FullName } else { $null }

    if (-not $iniSrc) {
        Write-Err "No php.ini-development or php.ini-production found in $PHP_PATH"
        return
    }

    $iniPath = "$PHP_PATH\php.ini"
    Copy-Item $iniSrc $iniPath -Force

    $ini = Get-Content $iniPath

    # Set extension_dir
    $extDir = "$PHP_PATH\ext"
    $ini = $ini -replace ';?\s*extension_dir\s*=\s*".*"', "extension_dir = `"$extDir`""

    # Enable essential extensions
    # Note: pdo_sqlite + sqlite3 require Invoke-FixSqliteDll to replace
    # the bundled libsqlite3.dll (VS17 builds have an incompatible version).
    $extensions = @(
        'extension=curl',
        'extension=fileinfo',
        'extension=gd',
        'extension=intl',
        'extension=mbstring',
        'extension=mysqli',
        'extension=openssl',
        'extension=pdo_mysql',
        'extension=pdo_sqlite',
        'extension=sodium', 
        'extension=sqlite3'
    )

    foreach ($ext in $extensions) {
        $ini = $ini -replace ";$ext", $ext
    }

    # Development-friendly settings
    $ini = $ini -replace 'display_errors\s*=\s*Off', 'display_errors = On'
    $ini = $ini -replace 'display_startup_errors\s*=\s*Off', 'display_startup_errors = On'
    $ini = $ini -replace 'error_reporting\s*=\s*E_ALL & ~E_DEPRECATED & ~E_STRICT', 'error_reporting = E_ALL'

    # Enable PHP error logging to file
    $errorLogPath = "$LOGS_PATH\php_errors.log"
    $errorLogPathUnix = $errorLogPath -replace '\\', '/'
    if ($ini -match ';?error_log\s*=') {
        $ini = $ini -replace ';?error_log\s*=\s*.*', "error_log = `"$errorLogPathUnix`""
    }
    Write-Ok "PHP error_log -> $errorLogPath"

    # Enable OPCache for performance
    $ini = $ini -replace ';?opcache\.enable\s*=\s*\d', 'opcache.enable=1'
    $ini = $ini -replace ';?opcache\.enable_cli\s*=\s*\d', 'opcache.enable_cli=0'
    $ini = $ini -replace ';?opcache\.memory_consumption\s*=\s*\d+', 'opcache.memory_consumption=256'
    $ini = $ini -replace ';?opcache\.interned_strings_buffer\s*=\s*\d+', 'opcache.interned_strings_buffer=16'
    $ini = $ini -replace ';?opcache\.max_accelerated_files\s*=\s*\d+', 'opcache.max_accelerated_files=20000'
    $ini = $ini -replace ';?opcache\.validate_timestamps\s*=\s*\d', 'opcache.validate_timestamps=1'
    $ini = $ini -replace ';?opcache\.revalidate_freq\s*=\s*\d+', 'opcache.revalidate_freq=2'

    # Enable JIT compilation (these directives aren't in default php.ini — append if missing)
    $ini = Set-IniDirective $ini 'opcache.jit' 'tracing'
    $ini = Set-IniDirective $ini 'opcache.jit_buffer_size' '100M'
    Write-Ok "OPCache enabled (256 MB, JIT tracing, production-ready)"

    # File upload limits (50 MB import for phpMyAdmin, etc.)
    $ini = Set-IniDirective $ini 'upload_max_filesize' '50M'
    $ini = Set-IniDirective $ini 'post_max_size' '55M'
    $ini = Set-IniDirective $ini 'max_execution_time' '300'
    $ini = Set-IniDirective $ini 'max_input_time' '300'
    Write-Ok "Upload limits set: 50 MB files, 300s timeout"

    # Session GC lifetime (match PMA LoginCookieValidity)
    $ini = Set-IniDirective $ini 'session.gc_maxlifetime' '14400'
    Write-Ok "Session GC lifetime: 4 hours"

    Set-Content -Path $iniPath -Value $ini
    Write-Ok "PHP extensions enabled: curl, fileinfo, gd, intl, mbstring, mysqli, openssl, pdo_mysql, pdo_sqlite, sodium, sqlite3"
}

function Invoke-FixSqliteDll {
    Write-Host ""
    Write-Warn "Checking SQLite3 DLL..."

    $dllPath = "$PHP_PATH\libsqlite3.dll"

    # Scrape sqlite.org for the latest x64 DLL
    try {
        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
        $ua = $UA_STRING
        $html = Invoke-WebRequest "https://www.sqlite.org/download.html" -UseBasicParsing -Headers @{ "User-Agent" = $ua }

        # Find the x64 DLL zip path — sqlite.org changed their page layout.
        # The path is now embedded in a CSV line or JS call, e.g.:
        #   PRODUCT,3.53.1,2026/sqlite-dll-win-x64-3530100.zip,...
        #   d391('a11','2026/sqlite-dll-win-x64-3530100.zip');
        if ($html.Content -match 'PRODUCT,\d+\.\d+\.\d+,(\d{4}/sqlite-dll-win-x64-\d+\.zip)') {
            $zipPath = $matches[1]
            $url = "https://www.sqlite.org/$zipPath"
            $zipFile = "$DOWNLOAD_CACHE\sqlite3_dll.zip"

            Write-Info "Syncing latest SQLite3 DLL..."
            if (-not (Test-Path $zipFile)) {
                Invoke-WebRequest $url -OutFile $zipFile -UseBasicParsing -Headers @{ "User-Agent" = $ua }
            }

            $extractDir = "$DOWNLOAD_CACHE\sqlite3_dll_extract"
            New-Item -ItemType Directory -Force -Path $extractDir | Out-Null
            Expand-Archive $zipFile $extractDir -Force

            $srcDll = Get-ChildItem $extractDir -Filter "sqlite3.dll" -Recurse | Select-Object -First 1
            if ($srcDll) {
                Copy-Item $srcDll.FullName $dllPath -Force
                # Also copy to Apache bin — Windows DLL search starts from httpd.exe's dir
                Copy-Item $srcDll.FullName "$APACHE_PATH\bin\libsqlite3.dll" -Force
                Write-Ok "SQLite3 DLL updated (PHP root + Apache bin)"
            }
            else {
                Write-Warn "Could not find sqlite3.dll in downloaded archive - skipping"
            }

            Remove-Tree $extractDir
        }
        else {
            Write-Warn "Could not resolve latest SQLite3 DLL URL - skipping"
        }
    }
    catch {
        Write-Warn "SQLite3 DLL update failed ($($_.Exception.Message)) - pdo_sqlite may not load"
    }
}

function Invoke-CopyPhpDlls {
    Write-Host ""
    Write-Warn "Copying PHP dependency DLLs to Apache bin..."

    $phpDlls = @(Get-ChildItem "$PHP_PATH\icu*.dll" -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
    $phpDlls += @('libssh2.dll', 'nghttp2.dll', 'libsodium.dll')

    foreach ($dll in $phpDlls) {
        $src = "$PHP_PATH\$dll"
        $dst = "$APACHE_PATH\bin\$dll"
        if (Test-Path $src) {
            # A running httpd maps these DLLs, and Copy-Item's failure is
            # NON-terminating: the stale file stays in apache\bin and PHP's
            # extensions then load against a mismatched dependency, which surfaces
            # as "The specified procedure could not be found". Verify instead of
            # assuming the copy landed.
            try {
                Copy-Item $src $dst -Force -ErrorAction Stop
            }
            catch {
                Write-Err "Could not copy $dll into Apache bin: $($_.Exception.Message)"
                Write-Info "  Stop the stack first - httpd holds these DLLs open."
                continue
            }
            if ((Get-Item $src).Length -ne (Get-Item $dst).Length) {
                Write-Err "$dll did not copy cleanly (size mismatch) - Apache bin still has a stale copy"
                continue
            }
            Write-Ok "Copied $dll"
        }
    }
}

function Test-PhpRuntimeHealthy {
# Post-extract sanity check for PHP. A version-mismatched ext/ folder loads the
# core happily but fails on the extensions that depend on external DLLs
# (openssl, curl, fileinfo, gd, intl, mbstring) - which is exactly how an 8.5.12
# update broke this stack in Oct 2026. Returns @{ Ok = $bool; Detail = '...' }.
    $exe = "$PHP_PATH\php.exe"
    if (-not (Test-Path $exe)) {
        return @{ Ok = $false; Detail = "php.exe is missing from $PHP_PATH" }
    }

    $out = (& $exe -v 2>&1 | Out-String)
    # Two distinct wordings both mean a mismatched tree:
    #   "Unable to load dynamic library 'x' ... The specified procedure could not
    #    be found" — same module API, different build (8.5.11 ext over 8.5.12 core)
    #   "x: Unable to initialize module ... compiled with module API=N" — different
    #    minor (e.g. 8.4 extension files left behind by 8.5)
    if ($out -match 'Unable to load dynamic library|Unable to initialize module|compiled with module API') {
        $bad = @()
        $bad += @([regex]::Matches($out, "dynamic library '([^']+)'") | ForEach-Object { $_.Groups[1].Value })
        $bad += @([regex]::Matches($out, 'PHP Startup:\s+([A-Za-z0-9_]+): Unable to initialize module') | ForEach-Object { $_.Groups[1].Value })
        $bad = @($bad | Select-Object -Unique)
        $detail = if ($bad.Count -gt 0) { $bad -join ', ' } else { 'see PHP startup warnings' }
        return @{ Ok = $false; Detail = "extensions failed to load: $detail" }
    }

    if ($out -notmatch 'PHP\s+(\d+\.\d+\.\d+)') {
        return @{ Ok = $false; Detail = "php.exe did not report a version: $($out.Trim())" }
    }

    return @{ Ok = $true; Detail = $matches[1] }
}

function Start-PhpupService($Name) {
# Start one phpup Windows service and say WHY it failed.
# Start-Service's own message is unhelpful ("Cannot start service 'X' on computer
# '.'") and callers used to swallow it with -ErrorAction SilentlyContinue. The two
# things that actually happen: the start type is Disabled (so it can never start),
# or the start is slow and the service is still StartPending when we sample it.
# Handle both, and poll instead of trusting a fixed sleep.
    $svc = Get-Service -Name $Name -ErrorAction SilentlyContinue
    if (-not $svc) { Write-Err "$Name service is not registered"; return $false }

    if ($svc.StartType -eq 'Disabled') {
        Write-Warn "$Name is set to Disabled - setting it back to Automatic"
        Set-Service -Name $Name -StartupType Automatic -ErrorAction SilentlyContinue
        $svc.Refresh()
        if ($svc.StartType -eq 'Disabled') {
            Write-Err "$Name is still Disabled. Fix it in services.msc, or run: sc.exe config $Name start= auto"
            return $false
        }
    }

    if ($svc.Status -eq 'Running') { return $true }

    try {
        Start-Service -Name $Name -ErrorAction Stop
    }
    catch {
        Write-Err "$Name could not be started: $($_.Exception.Message)"
        return $false
    }

    $sw = [System.Diagnostics.Stopwatch]::StartNew()
    while ($sw.Elapsed.TotalSeconds -lt 15) {
        $svc.Refresh()
        if ($svc.Status -eq 'Running') { return $true }
        if ($svc.Status -eq 'Stopped') { break }
        Start-Sleep -Milliseconds 250
    }

    $svc.Refresh()
    if ($svc.Status -eq 'Running') { return $true }
    Write-Err "$Name did not reach Running (current status: $($svc.Status))"
    return $false
}

function Invoke-ConfigureMariaDb {
    Write-Host ""
    Write-Warn "Configuring MariaDB..."

    $dataDir = "$MARIADB_PATH\data"
    $logsUnix = $LOGS_PATH -replace '\\', '/'

    # Write my.ini with log-error (always, even if data dir exists)
    $myIniPath = "$MARIADB_PATH\my.ini"
    $myIni = @"
[mysqld]
datadir=$dataDir
log-error=$logsUnix/mariadb_error.log

[client]
plugin-dir=$MARIADB_PATH\lib\plugin
"@
    if (-not (Test-Path $myIniPath) -or (Get-Content $myIniPath -Raw) -notmatch 'log-error') {
        Set-Content -Path $myIniPath -Value $myIni
        Write-Ok "MariaDB my.ini written (log-error -> $LOGS_PATH\mariadb_error.log)"
    }

    # Check if already initialised
    if (Test-Path $dataDir) {
        Write-Info "MariaDB data directory already exists - skipping initialisation"
        return
    }

    Write-Info "Initialising MariaDB data directory..."

    # Try mariadb-install-db first (MariaDB 10.5+), fall back to mysqld --initialize-insecure
    $installDb = "$MARIADB_PATH\bin\mariadb-install-db.exe"
    $mysqld    = if (Test-Path "$MARIADB_PATH\bin\mariadbd.exe") { "$MARIADB_PATH\bin\mariadbd.exe" } else { "$MARIADB_PATH\bin\mysqld.exe" }

    if (Test-Path $installDb) {
        # Newer MariaDB: use mariadb-install-db
        Write-Info "  Using mariadb-install-db..."
        & $installDb --datadir="$dataDir" --password= 2>&1 | ForEach-Object { Write-Host "  $_" -ForegroundColor DarkGray }
    }
    elseif (Test-Path $mysqld) {
        # Older / MySQL-compatible: --initialize-insecure creates root with no password
        Write-Info "  Using mysqld --initialize-insecure..."
        & $mysqld --initialize-insecure "--datadir=$dataDir" --console 2>&1 | ForEach-Object { Write-Host "  $_" -ForegroundColor DarkGray }
    }
    else {
        Write-Err "No MariaDB server executable found in $MARIADB_PATH\bin"
        Write-Err "Check that the MariaDB zip was extracted and flattened correctly."
        return
    }

    if (Test-Path $dataDir) {
        Write-Ok "MariaDB data directory initialised (root password is blank)"
    }
    else {
        Write-Err "MariaDB initialisation failed - check output above for details"
        Write-Info "Common causes: missing Visual C++ Redistributable, or permission denied."
    }
}

function Invoke-ConfigurePhpMyAdmin {
    Write-Host ""
    Write-Warn "Configuring phpMyAdmin & Test Script..."

    $configPath = "$PHPMYADMIN_PATH\config.inc.php"

    if (Test-Path $configPath) {
        Write-Info "phpMyAdmin config already exists - skipping"
        return
    }

    # Generate a random blowfish secret
    $chars = 48..57 + 65..90 + 97..122
    $blowfishSecret = -join ($chars | Get-Random -Count 32 | ForEach-Object { [char]$_ })

    $config = @"
<?php
/* phpup - phpMyAdmin configuration */
`$i = 1;
`$cfg['blowfish_secret'] = '$blowfishSecret';
`$cfg['Servers'][`$i]['host']          = '127.0.0.1';
`$cfg['Servers'][`$i]['port']          = '3306';
`$cfg['Servers'][`$i]['connect_type']  = 'tcp';
`$cfg['Servers'][`$i]['auth_type']     = 'config';
`$cfg['Servers'][`$i]['user']          = 'root';
`$cfg['Servers'][`$i]['password']      = '';
`$cfg['Servers'][`$i]['AllowNoPassword'] = true;
`$cfg['UploadDir'] = '';
`$cfg['SaveDir']   = '';
`$cfg['DefaultConnectionCollation'] = 'utf8mb4_general_ci';
`$cfg['VersionCheck'] = false;
`$cfg['SendErrorReports'] = 'never';
`$cfg['LoginCookieValidity'] = 14400;
`$cfg['TempDir'] = '$PHPMYADMIN_PATH/tmp';
"@

    Set-Content -Path $configPath -Value $config
    Write-Ok "phpMyAdmin configured (root / blank password)"

    # Ensure tmp directory for Twig template cache
    $pmaTmp = "$PHPMYADMIN_PATH\tmp"
    if (-not (Test-Path $pmaTmp)) {
        New-Item -ItemType Directory -Path $pmaTmp -Force | Out-Null
        Write-Ok "phpMyAdmin tmp directory created"
    }
}

function Invoke-ConfigurePmaStorage {
# Creates the phpmyadmin config storage database and imports the schema.
# Enables bookmarks, query history, table tracking, designer, etc.

    # Check if already configured
    $testResult = & "$MARIADB_PATH\bin\mariadb.exe" -u root --skip-password -e "SELECT 1 FROM information_schema.TABLES WHERE TABLE_SCHEMA='pma' AND TABLE_NAME='pma__bookmark'" 2>&1
    if ($LASTEXITCODE -eq 0 -and $testResult -match '1') {
        Write-Ok "phpMyAdmin storage already configured — skipping"
        # Still ensure config.inc.php has the storage directives
        $configPath = "$PHPMYADMIN_PATH\config.inc.php"
        if (Test-Path $configPath) {
            $existing = Get-Content $configPath -Raw -Encoding UTF8
            if ($existing -notmatch "pmadb") {
                $storageConfig = Get-PmaStorageConfig
                Add-Content -Path $configPath -Value $storageConfig -Encoding UTF8
                Write-Ok "Storage config added to config.inc.php"
            }
        }
        return
    }

    # Find create_tables.sql
    $sqlFile = $null
    foreach ($candidate in @("$PHPMYADMIN_PATH\sql\create_tables.sql", "$PHPMYADMIN_PATH\examples\create_tables.sql")) {
        if (Test-Path $candidate) { $sqlFile = $candidate; break }
    }
    if (-not $sqlFile) {
        Write-Warn "create_tables.sql not found in phpMyAdmin. Storage features unavailable."
        return
    }

    # Create database and import schema
    Write-Info "Creating phpMyAdmin storage database (pma)..."
    & "$MARIADB_PATH\bin\mariadb.exe" -u root --skip-password -e "CREATE DATABASE IF NOT EXISTS pma" 2>&1 | Out-Null
    if ($LASTEXITCODE -ne 0) {
        Write-Err "Failed to create pma database"
        return
    }

    Write-Info "Importing phpMyAdmin storage schema..."
    Get-Content $sqlFile | & "$MARIADB_PATH\bin\mariadb.exe" -u root --skip-password pma 2>&1 | Out-Null
    if ($LASTEXITCODE -ne 0) {
        Write-Err "Failed to import storage schema"
        return
    }

    # Append storage config to config.inc.php
    $configPath = "$PHPMYADMIN_PATH\config.inc.php"
    $storageConfig = Get-PmaStorageConfig
    Add-Content -Path $configPath -Value $storageConfig -Encoding UTF8

    Write-Ok "phpMyAdmin storage configured (bookmarks, history, designer, etc.)"
}

function Get-PmaStorageConfig {
# Returns the phpMyAdmin storage configuration block for config.inc.php
# Table list mirrors phpup.sh configure_phpmyadmin (brew path) — keep both
# in sync with phpMyAdmin's upstream sql/create_tables.sql.
    return @"

/* phpMyAdmin configuration storage */
`$cfg['Servers'][`$i]['pmadb']           = 'pma';
`$cfg['Servers'][`$i]['bookmarktable']   = 'pma__bookmark';
`$cfg['Servers'][`$i]['relation']        = 'pma__relation';
`$cfg['Servers'][`$i]['table_info']      = 'pma__table_info';
`$cfg['Servers'][`$i]['table_coords']    = 'pma__table_coords';
`$cfg['Servers'][`$i]['pdf_pages']       = 'pma__pdf_pages';
`$cfg['Servers'][`$i]['column_info']     = 'pma__column_info';
`$cfg['Servers'][`$i]['history']         = 'pma__history';
`$cfg['Servers'][`$i]['table_uiprefs']   = 'pma__table_uiprefs';
`$cfg['Servers'][`$i]['tracking']        = 'pma__tracking';
`$cfg['Servers'][`$i]['userconfig']      = 'pma__userconfig';
`$cfg['Servers'][`$i]['recent']          = 'pma__recent';
`$cfg['Servers'][`$i]['favorite']        = 'pma__favorite';
`$cfg['Servers'][`$i]['users']           = 'pma__users';
`$cfg['Servers'][`$i]['usergroups']      = 'pma__usergroups';
`$cfg['Servers'][`$i]['navigationhiding'] = 'pma__navigationhiding';
`$cfg['Servers'][`$i]['savedsearches']   = 'pma__savedsearches';
`$cfg['Servers'][`$i]['central_columns'] = 'pma__central_columns';
`$cfg['Servers'][`$i]['designer_settings'] = 'pma__designer_settings';
`$cfg['Servers'][`$i]['export_templates'] = 'pma__export_templates';
"@
}

# ============================================================
#  SERVICE MANAGEMENT
# ============================================================

function Test-TcpPortListening {
    param([int]$Port)
    # Enumerate listeners via .NET (~60ms measured) instead of
    # Get-NetTCPConnection (~3.8s measured: the NetTCPIP module autoloads on
    # every fresh process, and every CLI invocation is a fresh process).
    try {
        foreach ($ep in [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().GetActiveTcpListeners()) {
            if ([int]$ep.Port -eq $Port) { return $true }
        }
        return $false
    }
    catch {
        # Fallback for older systems: parse netstat -ano output
        $n = netstat -ano 2>$null | Select-String ":$Port\s" | Select-String "LISTENING"
        return [bool]$n
    }
}

function Get-PortHolderName {
    param([int]$Port)
    $line = netstat -ano 2>$null | Select-String ":$Port\s" | Select-String "LISTENING" | Select-Object -First 1
    if ($line) {
        $pidStr = ($line.ToString().Trim() -split '\s+')[-1]
        $proc = Get-Process -Id ([int]$pidStr) -ErrorAction SilentlyContinue
        if ($proc) { return "$($proc.ProcessName) (PID $pidStr)" }
    }
    return "unknown (run: netstat -ano | findstr :$Port)"
}

function Assert-StackPortsFree {
    # Refuse to start into ports another stack is holding (IIS, Docker,
    # XAMPP, a second MariaDB/MySQL...). phpup's OWN running components are
    # exempt, so restart over a live phpup stack passes.
    $busy = $false
    if ((Test-TcpPortListening -Port 80) -and -not (Test-ApacheRunning)) {
        Write-Err "Port 80 is in use by another stack — $(Get-PortHolderName -Port 80)"
        $busy = $true
    }
    if ((Test-TcpPortListening -Port 3306) -and -not (Test-MariaDbRunning)) {
        Write-Err "Port 3306 is in use by another stack — $(Get-PortHolderName -Port 3306)"
        $busy = $true
    }
    if ($busy) {
        Write-Info "Stop the other stack first, then run R or S to try again."
    }
    return (-not $busy)
}

function Start-WebStackServices {
    # Refuse to start into ports another stack is holding.
    if (-not (Assert-StackPortsFree)) { return }
    Write-Host ""
    Write-Warn "Starting services..."

    $apacheAsService  = Get-Service -Name $SERVICE_APACHE -ErrorAction SilentlyContinue
    $mariadbAsService = Get-Service -Name $SERVICE_MARIADB -ErrorAction SilentlyContinue

    # Apache
    if (Test-ApacheRunning) {
        Write-Info "Apache is already running"
    }
    elseif ($apacheAsService) {
        # Registered as a Windows service — use service control
        if (Start-PhpupService $SERVICE_APACHE) {
            Write-Ok "Apache started (Windows service)"
        }
        else {
            Write-Err "Apache service failed to start — see the message above"
        }
    }
    else {
        # Process mode: quick syntax check before daemonizing
        $testResult = & "$APACHE_PATH\bin\httpd.exe" -t 2>&1 | Out-String
        if ($LASTEXITCODE -ne 0) {
            Write-Err "Apache configuration error:"
            Write-Host $testResult -ForegroundColor DarkGray
            Write-Info "If the error mentions missing DLLs (VCRUNTIME, MSVCP, etc.),"
            Write-Info "install the Visual C++ Redistributable from:"
            Write-Info "  $($FALLBACK_URLS.Redist)"
            return
        }

        # Remove stale pid file from previous unclean shutdown
        $pidFile = "$APACHE_PATH\logs\httpd.pid"
        if (Test-Path $pidFile) { Remove-Item $pidFile -Force -ErrorAction SilentlyContinue }

        Start-Process -FilePath "$APACHE_PATH\bin\httpd.exe" -WindowStyle Hidden
        Start-Sleep -Seconds 2
        if (Test-ApacheRunning) {
            Write-Ok "Apache started"
        }
        else {
            Write-Err "Apache failed to start - check apache_error.log in $LOGS_PATH"
            Write-Info "Common causes: port 80 in use, missing VC++ Redistributable, or config error."
        }
    }

    # MariaDB
    if (Test-MariaDbRunning) {
        Write-Info "MariaDB is already running"
    }
    elseif ($mariadbAsService) {
        if (Start-PhpupService $SERVICE_MARIADB) {
            Write-Ok "MariaDB started (Windows service, root password is blank)"
        }
        else {
            Write-Err "MariaDB service failed to start — see the message above"
        }
    }
    else {
        $dataDir = "$MARIADB_PATH\data"
        $mysqld  = if (Test-Path "$MARIADB_PATH\bin\mariadbd.exe") { "$MARIADB_PATH\bin\mariadbd.exe" } else { "$MARIADB_PATH\bin\mysqld.exe" }
        $logsUnix = $LOGS_PATH -replace '\\', '/'

        Start-Process -FilePath $mysqld `
            -ArgumentList "--datadir=`"$dataDir`" --log-error=`"$logsUnix/mariadb_error.log`"" `
            -WindowStyle Hidden `
            -PassThru | Out-Null

        Start-Sleep -Seconds 3
        if (Test-MariaDbRunning) {
            Write-Ok "MariaDB started (root password is blank)"
        }
        else {
            Write-Err "MariaDB failed to start - check console output"
        }
    }
}

function Stop-WebStackServices {
    Write-Host ""
    Write-Warn "Stopping services..."

    $stopped = $false

    $apacheAsService  = Get-Service -Name $SERVICE_APACHE -ErrorAction SilentlyContinue
    $mariadbAsService = Get-Service -Name $SERVICE_MARIADB -ErrorAction SilentlyContinue

    # Apache
    if ($apacheAsService -and (Get-Service $SERVICE_APACHE).Status -ne "Stopped") {
        Stop-Service $SERVICE_APACHE -ErrorAction SilentlyContinue -WarningAction SilentlyContinue
        Start-Sleep -Seconds 2
        Write-Ok "Apache service stopped"
        $stopped = $true
    }
    elseif (Test-ApacheRunning) {
        # Process mode: try graceful shutdown first, fall back to force kill
        & "$APACHE_PATH\bin\httpd.exe" -k stop 2>&1 | Out-Null
        Start-Sleep -Seconds 2
        if (Test-ApacheRunning) {
            Get-ProcessesByName -Names @('httpd') | Stop-Process -Force -ErrorAction SilentlyContinue
            Start-Sleep -Seconds 1
        }
        Write-Ok "Apache stopped"
        $stopped = $true
    }
    else {
        Write-Info "Apache not running"
    }

    # MariaDB
    if ($mariadbAsService -and (Get-Service $SERVICE_MARIADB).Status -ne "Stopped") {
        Stop-Service $SERVICE_MARIADB -ErrorAction SilentlyContinue -WarningAction SilentlyContinue
        Start-Sleep -Seconds 2
        Write-Ok "MariaDB service stopped"
        $stopped = $true
    }
    elseif (Test-MariaDbRunning) {
        Get-ProcessesByName -Names @('mysqld', 'mariadbd') | Stop-Process -Force -ErrorAction SilentlyContinue
        Start-Sleep -Seconds 2
        Write-Ok "MariaDB stopped"
        $stopped = $true
    }
    else {
        Write-Info "MariaDB not running"
    }

    if (-not $stopped) {
        Write-Info "No services were running"
    }
}

# ---- Windows Service Helpers ---------------------------------

$SERVICE_APACHE  = "phpup_Apache"
$SERVICE_MARIADB = "phpup_MariaDB"

function Test-ServicesInstalled {
    $service = Get-Service -Name $SERVICE_APACHE -ErrorAction SilentlyContinue
    return $null -ne $service
}

function Install-AsServices {
    Write-Host ""
    Write-Info "Registering Windows services (auto-start on boot)..."

    # Stop any running process-mode instances first
    if ((Test-ApacheRunning) -or (Test-MariaDbRunning)) {
        Stop-WebStackServices
    }

    # --- Apache ---
    if (Get-Service -Name $SERVICE_APACHE -ErrorAction SilentlyContinue) {
        Write-Info "$SERVICE_APACHE service already exists — skipping"
    }
    else {
        & "$APACHE_PATH\bin\httpd.exe" -k install -n $SERVICE_APACHE 2>&1 | Out-Null
        if ($LASTEXITCODE -eq 0) {
            # Set to auto-start
            Set-Service -Name $SERVICE_APACHE -StartupType Automatic -ErrorAction SilentlyContinue
            Write-Ok "$SERVICE_APACHE service installed"
        }
        else {
            Write-Err "Failed to install $SERVICE_APACHE service"
        }
    }

    # --- MariaDB ---
    if (Get-Service -Name $SERVICE_MARIADB -ErrorAction SilentlyContinue) {
        Write-Info "$SERVICE_MARIADB service already exists — skipping"
    }
    else {
        $mysqld  = if (Test-Path "$MARIADB_PATH\bin\mariadbd.exe") { "$MARIADB_PATH\bin\mariadbd.exe" } else { "$MARIADB_PATH\bin\mysqld.exe" }
        $dataDir = "$MARIADB_PATH\data"
        & $mysqld --install $SERVICE_MARIADB --datadir="$dataDir" --log-error="$LOGS_PATH\mariadb_error.log" 2>&1 | Out-Null
        if ($LASTEXITCODE -eq 0) {
            Set-Service -Name $SERVICE_MARIADB -StartupType Automatic -ErrorAction SilentlyContinue
            Write-Ok "$SERVICE_MARIADB service installed"
        }
        else {
            Write-Err "Failed to install $SERVICE_MARIADB service"
        }
    }

    # Start services
    Start-Sleep -Seconds 1
    Start-WebStackServices
}

function Remove-Services {
    Write-Host ""
    Write-Info "Removing Windows services..."

    # Stop only the services that are actually running (avoid duplicate banner)
    $apacheSvc  = Get-Service -Name $SERVICE_APACHE -ErrorAction SilentlyContinue
    $mariadbSvc = Get-Service -Name $SERVICE_MARIADB -ErrorAction SilentlyContinue

    if ($apacheSvc -and $apacheSvc.Status -ne "Stopped") {
        Stop-Service $SERVICE_APACHE -ErrorAction SilentlyContinue -WarningAction SilentlyContinue
        Start-Sleep -Seconds 2
    }
    if ($mariadbSvc -and $mariadbSvc.Status -ne "Stopped") {
        Stop-Service $SERVICE_MARIADB -ErrorAction SilentlyContinue -WarningAction SilentlyContinue
        Start-Sleep -Seconds 2
    }

    if ($apacheSvc) {
        & "$env:SystemRoot\System32\sc.exe" delete $SERVICE_APACHE 2>&1 | Out-Null
        Write-Ok "$SERVICE_APACHE service removed"
    }
    if ($mariadbSvc) {
        & "$env:SystemRoot\System32\sc.exe" delete $SERVICE_MARIADB 2>&1 | Out-Null
        Write-Ok "$SERVICE_MARIADB service removed"
    }
}

# ============================================================
#  INSTALL
# ============================================================

function Invoke-InstallWebStack {
    Write-Host ""
    Write-Bold "========================================"
    Write-Bold "  Installing PHP Web Stack on Windows"
    Write-Bold "========================================"

    # Pre-flight: VC++ Redistributable check (required by Apache VS18 + MariaDB 12.x)
    Write-Host ""
    $vcVer = Get-VcRedistVersion
    if ($vcVer) {
        $minVc = [version]"14.51.36231"
        if ($vcVer -ge $minVc) {
            Write-Ok "Visual C++ Redistributable x64 — $vcVer (meets minimum $minVc)"
        }
        else {
            Write-Warn "Visual C++ Redistributable x64 — $vcVer (BELOW minimum $minVc)"
            Write-Info "  This is required by Apache Lounge VS18 and MariaDB 12.x."
            Write-Host ""
            Write-Bold "  An updated Visual C++ Redistributable must be installed to continue."
            $choice = Read-Host "  Install it now? [Y/n]"
            if ($choice -eq "" -or $choice -match "^[Yy]") {
                Install-VcRedist
                if (-not (Test-VcRedistInstalled)) {
                    Write-Err "VC++ Redistributable upgrade failed or requires reboot. Aborting."
                    return
                }
            }
            else {
                Write-Err "VC++ Redistributable is required. Aborting installation."
                return
            }
        }
    }
    else {
        Write-Warn "Visual C++ Redistributable x64 is NOT installed."
        Write-Info "  This is required by Apache Lounge VS18 and MariaDB 12.x."
        Write-Host ""
        $choice = Read-Host "  Install it now? [Y/n]"
        if ($choice -eq "" -or $choice -match "^[Yy]") {
            Install-VcRedist
            if (-not (Test-VcRedistInstalled)) {
                Write-Err "VC++ Redistributable installation failed or requires reboot. Aborting."
                return
            }
        }
        else {
            Write-Err "VC++ Redistributable is required. Aborting installation."
            return
        }
    }
    Write-Host ""

    # Create base directories
    New-Item -ItemType Directory -Force -Path $BASE | Out-Null
    New-Item -ItemType Directory -Force -Path $WWW_PATH | Out-Null
    New-Item -ItemType Directory -Force -Path $LOGS_PATH | Out-Null
    New-Item -ItemType Directory -Force -Path $DOWNLOAD_CACHE | Out-Null

    # Resolve URLs (or use local zips in offline mode)
    Write-Host ""
    if ($Offline) {
        Write-Bold "Offline mode — using pre-downloaded zips from: $DOWNLOAD_CACHE"
        Write-Host ""

        $zipFiles = Get-ChildItem -Path $DOWNLOAD_CACHE -Filter "*.zip" -ErrorAction SilentlyContinue
        if (-not $zipFiles -or $zipFiles.Count -lt 4) {
            Write-Err "Offline mode requires 4 zip files in $DOWNLOAD_CACHE (Apache, PHP, MariaDB, phpMyAdmin)."
            Write-Info "  Run the script online once to download them, or place them manually."
            return
        }

        Write-Ok "Found $($zipFiles.Count) zip files — skipping URL resolution and download."

        foreach ($zip in $zipFiles) {
            $name = $zip.BaseName.ToLower()
            if ($name -like "*httpd*" -or $name -like "*apache*") {
                $apacheZip = $zip.FullName
            }
            elseif ($name -like "*php-*" -and $name -notlike "*phpmyadmin*") {
                $phpZip = $zip.FullName
            }
            elseif ($name -like "*mariadb*") {
                $mariadbZip = $zip.FullName
            }
            elseif ($name -like "*phpmyadmin*") {
                $pmaZip = $zip.FullName
            }
        }

        # Extract directly. Stop the stack and clear each destination first, for
        # the same reason the online path does (see the replaceApache/replacePhp
        # note below): a live httpd holds php8ts.dll and the loaded extension
        # DLLs, so the overwrite is skipped without an error.
        if ($apacheZip -or $phpZip) {
            Stop-WebStackServices
            Start-Sleep -Seconds 1
        }
        if ($apacheZip)   { Remove-Tree $APACHE_PATH; Invoke-ExtractZip $apacheZip   $APACHE_PATH      "Apache" }
        if ($phpZip)      { Remove-Tree $PHP_PATH;    Invoke-ExtractZip $phpZip      $PHP_PATH         "PHP" }
        if ($mariadbZip)  {
            # Same protection as the online upgrade path: if an existing
            # install is being overwritten, stop + back up data first.
            if (Test-MariaDbInstalled) {
                Stop-WebStackServices
                Backup-MariaDbData
                Remove-Tree $MARIADB_PATH
            }
            Invoke-ExtractZip $mariadbZip  $MARIADB_PATH     "MariaDB"
            if (Test-Path "$BASE\data_backup_update") { Restore-MariaDbData }
        }
        if ($pmaZip)      { Invoke-ExtractZip $pmaZip      $PHPMYADMIN_PATH  "phpMyAdmin" }

        if (-not $apacheZip -or -not $phpZip -or -not $mariadbZip) {
            Write-Err "Could not identify all required zips by filename convention."
            Write-Info "  Expected: *httpd* or *apache*, *php-* (not phpmyadmin), *mariadb*, *phpmyadmin*"
            return
        }
    }
    else {
        Write-Bold "Resolving latest stable versions..."
        Write-Host ""

        try {
            $apacheUrl  = Get-LatestApacheUrl
            $phpUrl     = Get-LatestPhpUrl
            $mariadbUrl = Get-LatestMariadbUrl
            $pmaUrl     = Get-LatestPhpMyAdminUrl
        }
        catch {
            Write-Err "Failed to resolve one or more download URLs. Aborting."
            return
        }

        # Download and extract (Apache, PHP, MariaDB only — PMA deferred).
        # Skip components already at the latest version.
        $resolvedApacheVer  = Get-VersionFromUrl $apacheUrl  'apache'
        $resolvedPhpVer     = Get-VersionFromUrl $phpUrl     'php'
        $resolvedMariadbVer = Get-VersionFromUrl $mariadbUrl 'mariadb'

        $installedApacheVer  = Get-ApacheVersion
        $installedPhpVer     = Get-PhpVersion
        $installedMariadbVer = Get-MariaDbVersion

        # Replacing a component that a running service has memory-mapped fails on
        # Windows with a NON-terminating error: the write is skipped, the extract
        # is still reported as "[ OK ] extracted", and the directory is left
        # half-old/half-new. That is what happened in Oct 2026: six extensions
        # (openssl, curl, fileinfo, gd, intl, mbstring) failed with "The specified
        # procedure could not be found" - the DLL was present but an imported
        # symbol was missing, i.e. the extension files and the libraries they were
        # built against came from different builds. Apache then refused to serve
        # and the update looked like an Apache failure.
        # MariaDB already stops and wipes for this exact reason; Apache and PHP must too.
        $replaceApache = -not ($installedApacheVer -and $resolvedApacheVer -and ([version]$resolvedApacheVer -le [version]$installedApacheVer))
        $replacePhp    = -not ($installedPhpVer    -and $resolvedPhpVer    -and ([version]$resolvedPhpVer    -le [version]$installedPhpVer))
        if ($replaceApache -or $replacePhp) {
            Stop-WebStackServices
            Start-Sleep -Seconds 1
        }

        if ($installedApacheVer -and $resolvedApacheVer -and ([version]$resolvedApacheVer -le [version]$installedApacheVer)) {
            Write-Ok "Apache $installedApacheVer already installed — skipping download"
        } else {
            if ($installedApacheVer) { Write-Info "Apache $installedApacheVer -> $resolvedApacheVer" }
            Remove-Tree $APACHE_PATH
            Invoke-DownloadAndExtract $apacheUrl  $APACHE_PATH  "Apache"
        }

        if ($installedPhpVer -and $resolvedPhpVer -and ([version]$resolvedPhpVer -le [version]$installedPhpVer)) {
            Write-Ok "PHP $installedPhpVer already installed — skipping download"
        } else {
            if ($installedPhpVer) { Write-Info "PHP $installedPhpVer -> $resolvedPhpVer" }
            Remove-Tree $PHP_PATH
            Invoke-DownloadAndExtract $phpUrl     $PHP_PATH     "PHP"
        }

        if ($installedMariadbVer -and $resolvedMariadbVer -and ([version]$resolvedMariadbVer -le [version]$installedMariadbVer)) {
            Write-Ok "MariaDB $installedMariadbVer already installed — skipping download"
        } else {
            if ($installedMariadbVer) {
                Write-Info "MariaDB $installedMariadbVer -> $resolvedMariadbVer"
                # Upgrading a live install: stop the server first so the
                # binaries are not locked, then back up the data directory
                # before touching the installation. Data survives the
                # version swap and is restored below.
                Stop-WebStackServices
                Backup-MariaDbData
                Remove-Tree $MARIADB_PATH
            }
            Invoke-DownloadAndExtract $mariadbUrl $MARIADB_PATH "MariaDB"
            if ($installedMariadbVer) { Restore-MariaDbData }
        }
    }

    # Copy PHP dependency DLLs to Apache bin (ICU, curl deps, etc.)
    # Windows DLL search starts from httpd.exe's directory, not PHP's.
    Invoke-CopyPhpDlls

    # Configure
    Invoke-ConfigureApache
    Invoke-ConfigurePhp

    Invoke-FixSqliteDll

    # Verify the extracted PHP actually runs AND can load every extension php.ini
    # enables, before anything tries to serve with it.
    $phpHealth = Test-PhpRuntimeHealthy
    if ($phpHealth.Ok) {
        Write-Ok "PHP $($phpHealth.Detail) verified - core and extensions load"
    }
    else {
        Write-Err "PHP verification FAILED: $($phpHealth.Detail)"
        Write-Info "  That is a mismatched PHP tree, not an Apache problem."
        Write-Info "  Stop the stack and re-run the install so PHP extracts cleanly."
    }

    # Check for orphaned database backup from a previous install
    $backupDir = "$BASE\data_backup"
    if ((Test-Path $backupDir) -and (Get-ChildItem $backupDir -ErrorAction SilentlyContinue)) {
        Write-Host ""
        Write-Warn "Found database backup from a previous install: $backupDir"
        $restore = Read-Host "Restore previous databases? [Y/n]"
        if ($restore -eq "" -or $restore -match "^[Yy]") {
            $dataDir = "$MARIADB_PATH\data"
            New-Item -ItemType Directory -Force -Path $dataDir | Out-Null
            Get-ChildItem $backupDir | ForEach-Object {
                Move-Item $_.FullName $dataDir -Force
            }
            Remove-Item $backupDir -Force
            Write-Ok "Previous databases restored to $dataDir"
        }
        else {
            Write-Info "Skipping restore — backup remains at $backupDir"
        }
    }

    Invoke-ConfigureMariaDb

    if (-not $Offline) {
        # ── phpMyAdmin ──────────────────────────────────────────
        # Skip if already installed and at/above the resolved version
        # (matches the Apache/PHP/MariaDB skip logic above).
        $installedPmaVer = Get-PhpMyAdminVersion
        if ($installedPmaVer -and $pmaUrl -and ([version](Get-VersionFromUrl $pmaUrl 'phpmyadmin') -le [version]$installedPmaVer)) {
            Write-Ok "phpMyAdmin $installedPmaVer already installed — skipping download"
        } else {
            if ($installedPmaVer) { Write-Info "phpMyAdmin $installedPmaVer -> $(Get-VersionFromUrl $pmaUrl 'phpmyadmin')" }
            Invoke-DownloadAndExtract $pmaUrl $PHPMYADMIN_PATH "phpMyAdmin"
        }
    }
    Invoke-ConfigurePhpMyAdmin

    # Restore config files from previous install if available
    $configBackupDir = "$BASE\config_backup"
    if (Test-Path $configBackupDir) {
        Write-Host ""
        Write-Info "Found config backup from previous install:"
        $restored = @()
        $configMap = @(
            @{ Src = "$configBackupDir\httpd.conf";    Dst = "$APACHE_PATH\conf\httpd.conf" },
            @{ Src = "$configBackupDir\php.ini";        Dst = "$PHP_PATH\php.ini" },
            @{ Src = "$configBackupDir\my.ini";         Dst = "$MARIADB_PATH\my.ini" },
            @{ Src = "$configBackupDir\config.inc.php"; Dst = "$PHPMYADMIN_PATH\config.inc.php" }
        )
        foreach ($cfg in $configMap) {
            if (Test-Path $cfg.Src) {
                Copy-Item $cfg.Src $cfg.Dst -Force
                $restored += [System.IO.Path]::GetFileName($cfg.Dst)
            }
        }
        if ($restored.Count -gt 0) {
            Write-Ok "Restored: $($restored -join ', ')"
        }
        Remove-Tree $configBackupDir
    }

    # Create test file
    "<?php phpinfo(); ?>" | Out-File -FilePath "$WWW_PATH\phpinfo.php" -Encoding ASCII
    Write-Ok "Created $WWW_PATH\phpinfo.php"

    # Capture installed versions
    $versions = @{
        apache     = Get-ApacheVersion
        php        = Get-PhpVersion
        mariadb    = Get-MariaDbVersion
        phpmyadmin = (Get-PhpMyAdminVersion)
    }
    Write-Host ""
    Write-Warn "Configuring paths (this may take a moment)..."
    # Add PHP + MariaDB to user PATH (removes old entries from previous install)
    $pathEntries = Add-ToPath

    Write-Host ""
    # Ask about Windows services BEFORE starting (avoids start-stop-restart cycle)
    if (-not (Test-ServicesInstalled)) {
        $svcChoice = Read-Host "Install as Windows services (auto-start on boot)? [y/N]"
        if ($svcChoice -match "^[Yy]") {
            Install-AsServices
        }
        else {
            Write-Info "Services will run as processes (started via this script)."
        }
    }

    # Start services (uses service control if registered, process mode otherwise)
    Start-WebStackServices

    # phpMyAdmin configuration storage (bookmarks, history, designer, etc.)
    Invoke-ConfigurePmaStorage

    Write-Host ""
    Write-Bold "========================================"
    Write-Bold "  Installation Complete!"
    Write-Bold "========================================"
    Write-Host ""
    Write-Info "  Website root:  $WWW_PATH"
    Write-Info "  PHP test:      http://localhost/phpinfo.php"
    Write-Info "  phpMyAdmin:    http://localhost/phpmyadmin"
    Write-Info "  MariaDB login: root / [blank password]"
    Write-Host ""
    Write-Info "  PHP + MariaDB added to user PATH (new terminals only)"
    Write-Host ""

    # Save config with final state (including service registration decision)
    Save-Config -InstallPath $BASE -Versions $versions -PathEntries $pathEntries -ServicesRegistered:(Test-ServicesInstalled)
}

# ============================================================
#  UPDATE
# ============================================================

function Backup-MariaDbData {
    $dataDir = "$MARIADB_PATH\data"
    $backupDir = "$BASE\data_backup_update"
    if (Test-Path $dataDir) {
        Write-Info "Backing up databases before MariaDB update..."
        if (Test-Path $backupDir) {
            Remove-Tree $backupDir
        }
        New-Item -ItemType Directory -Force -Path $backupDir | Out-Null
        Get-ChildItem $dataDir | ForEach-Object {
            Move-Item $_.FullName $backupDir -Force
        }
        Write-Ok "Databases backed up"
    }
}

function Restore-MariaDbData {
    $backupDir = "$BASE\data_backup_update"
    if (Test-Path $backupDir) {
        $newDataDir = "$MARIADB_PATH\data"
        New-Item -ItemType Directory -Force -Path $newDataDir | Out-Null
        Get-ChildItem $backupDir | ForEach-Object {
            Move-Item $_.FullName $newDataDir -Force
        }
        Remove-Item $backupDir -Force
        Write-Ok "Databases restored"
    }
}

function Save-PostUpdateConfig {
    $existingConfig = Get-Config
    $versions = @{
        apache     = Get-ApacheVersion
        php        = Get-PhpVersionLabel
        mariadb    = Get-MariaDbVersion
        phpmyadmin = Get-PhpMyAdminVersion
    }
    $pathEntries = $existingConfig.path_entries
    $minSeries = if ($existingConfig -and $existingConfig.php_min_series) { [string]$existingConfig.php_min_series } else { $null }

    if (-not (Test-ServicesInstalled)) {
        Write-Host ""
        $svcChoice = Read-Host "Install as Windows services (auto-start on boot)? [y/N]"
        if ($svcChoice -match "^[Yy]") {
            Install-AsServices
        }
    }

    Save-Config -InstallPath $BASE -Versions $versions -PathEntries $pathEntries -ServicesRegistered:(Test-ServicesInstalled) -MinSeries $minSeries
}

function Invoke-UpdateWebStack {
    Write-Host ""
    Write-Warn "Checking for newer versions..."

    # Resolve latest URLs
    $latestApacheUrl  = Get-LatestApacheUrl -ErrorAction SilentlyContinue
    $latestPhpUrl     = Get-LatestPhpUrl -ErrorAction SilentlyContinue
    $latestMariadbUrl = Get-LatestMariadbUrl -ErrorAction SilentlyContinue
    $latestPmaUrl     = Get-LatestPhpMyAdminUrl -ErrorAction SilentlyContinue

    # Extract latest version strings from URLs
    $latestApacheVer  = Get-VersionFromUrl $latestApacheUrl  'apache'
    $latestPhpVer     = Get-VersionFromUrl $latestPhpUrl     'php'
    $latestMariadbVer = Get-VersionFromUrl $latestMariadbUrl 'mariadb'
    $latestPmaVer     = Get-VersionFromUrl $latestPmaUrl     'phpmyadmin'

    # Get installed versions
    $currentApacheVer  = Get-ApacheVersion
    $currentPhpVer     = Get-PhpVersion
    $currentMariadbVer = Get-MariaDbVersion
    $currentPmaVer     = Get-PhpMyAdminVersion

    # Compare and build outdated list
    $outdated = @()
    if ($currentApacheVer -and $latestApacheVer -and ([version]$latestApacheVer -gt [version]$currentApacheVer)) {
        $outdated += "Apache  ($currentApacheVer -> $latestApacheVer)"
    }
    if ($currentPhpVer -and $latestPhpVer -and ([version]$latestPhpVer -gt [version]$currentPhpVer)) {
        $outdated += "PHP     ($currentPhpVer -> $latestPhpVer)"
    }
    if ($currentMariadbVer -and $latestMariadbVer -and ([version]$latestMariadbVer -gt [version]$currentMariadbVer)) {
        $outdated += "MariaDB ($currentMariadbVer -> $latestMariadbVer)"
    }
    if ($currentPmaVer -and $latestPmaVer -and ($currentPmaVer -ne 'unknown') -and ([version]$latestPmaVer -gt [version]$currentPmaVer)) {
        $outdated += "phpMyAdmin ($currentPmaVer -> $latestPmaVer)"
    }

    Write-Host ""
    if ($outdated.Count -eq 0) {
        Write-Ok "Stack is up to date. Nothing to update."
        Write-Info "  Apache:     $currentApacheVer"
        Write-Info "  PHP:        $currentPhpVer"
        Write-Info "  MariaDB:    $currentMariadbVer"
        Write-Info "  phpMyAdmin: $currentPmaVer"
        return
    }

    Write-Warn "Updates available:"
    foreach ($item in $outdated) {
        Write-Info "  * $item"
    }

    $confirm = Read-Host "`nInstall these updates? [y/N]"

    if ($confirm -notmatch '^[yY]') {
        Write-Info "Update cancelled."
        return
    }

    $needsApache  = ($currentApacheVer -and $latestApacheVer -and ([version]$latestApacheVer -gt [version]$currentApacheVer))
    $needsPhp     = ($currentPhpVer -and $latestPhpVer -and ([version]$latestPhpVer -gt [version]$currentPhpVer))
    $needsMariadb = ($currentMariadbVer -and $latestMariadbVer -and ([version]$latestMariadbVer -gt [version]$currentMariadbVer))
    $needsPma     = ($currentPmaVer -and $latestPmaVer -and ($currentPmaVer -ne 'unknown') -and ([version]$latestPmaVer -gt [version]$currentPmaVer))

    Stop-WebStackServices
    Start-Sleep -Seconds 2

    Write-Host ""
    Write-Warn "Removing outdated installations..."

    if ($needsApache) {
        Remove-Tree $APACHE_PATH
        Invoke-DownloadAndExtract $latestApacheUrl $APACHE_PATH "Apache"
        Invoke-ConfigureApache
    }
    if ($needsPhp) {
        Remove-Tree $PHP_PATH
        Invoke-DownloadAndExtract $latestPhpUrl $PHP_PATH "PHP"
        Invoke-ConfigurePhp
        Invoke-FixSqliteDll
        Invoke-CopyPhpDlls
    }
    if ($needsMariadb) {
        Backup-MariaDbData

        Remove-Tree $MARIADB_PATH
        Invoke-DownloadAndExtract $latestMariadbUrl $MARIADB_PATH "MariaDB"

        Restore-MariaDbData

        Invoke-ConfigureMariaDb
    }
    if ($needsPma) {
        Remove-Tree $PHPMYADMIN_PATH
        Invoke-DownloadAndExtract $latestPmaUrl $PHPMYADMIN_PATH "phpMyAdmin"
        Invoke-ConfigurePhpMyAdmin
    }

    Start-WebStackServices

    # phpMyAdmin storage: reconfigure if phpMyAdmin was updated
    if ($needsPma) { Invoke-ConfigurePmaStorage }

    Write-Ok "Update complete"

    Save-PostUpdateConfig
}

# ============================================================
#  FORCED UPDATE (offline — scans $DOWNLOAD_CACHE only)
# ============================================================

function Show-PhpSwitchMenu {
# Series-aware PHP version switcher for fu.
#
# Lists cached PHP zips grouped by series (8.2 → newest stable), with:
#   - pre-release labels (8.6.0 alpha3, 8.6.0 beta1)
#   - newer/older/current tags vs the installed version
#   - stale hints when a newer patch exists ("8.2.32 (older → 8.2.33 is available)")
#   - '*' on entries whose series has multiple cached variants
#   - offers to download & install series that are missing from the cache
#
# Selecting an entry with multiple variants opens a sub-menu where each
# variant can be installed or deleted ([d] delete). Selecting a stale entry
# offers to install the newer patch (download + delete-or-keep the old) or
# use the cached one as-is.
#
# Returns $null if nothing chosen, otherwise a hashtable:
#   @{ Chosen = $true; Version = '8.5.9'; Path = 'C:\...zip' }            — install cached
#   @{ Chosen = $true; Version = '8.2.33'; Download = 'https://...'; PruneOld = 'C:\...\8.2.32.zip' } — download then install
    param(
        [object[]]$PhpVersions,
        [string]$Installed
    )

    # 1. Resolve latest stable per series (online only; offline = cached-only hints)
    $latestBySeries = @{}
    $phpJson = $null
    if (-not $Offline) {
        $phpJson = Get-PhpReleasesJson
        if ($phpJson) {
            # releases.json arrives as PSCustomObject (Invoke-RestMethod); accept
            # hashtable-shaped test doubles too.
            if ($phpJson -is [System.Collections.IDictionary]) {
                $seriesKeys = @($phpJson.Keys)
            } else {
                $seriesKeys = @($phpJson.PSObject.Properties.Name)
            }
            # Optional floor from config (php_min_series, default 8.2) — series
            # below it are never offered as download candidates.
            $minSeries = [version]'8.2'
            $config = Get-Config
            if ($config -and $config.php_min_series) {
                try { $minSeries = [version]$config.php_min_series } catch { }
            }
            foreach ($key in $seriesKeys) {
                # Any N.M series (7.4, 8.0, ...) that the JSON actually lists;
                # the config floor (php_min_series) is the only gate below.
                if ($key -match '^\d+\.\d+$' -and ([version]$key -ge $minSeries)) {
                    $resolved = Resolve-PhpSeriesUrl $phpJson $key
                    if ($resolved) { $latestBySeries[$key] = $resolved }
                }
            }
        }
    }

    # 2. Series for each cached zip: "8.5.9" → "8.5"
    function Get-PhpSeries([string]$version) {
        if ($version -match '^(\d+\.\d+)\.') { return $matches[1] }
        return $version
    }

    # 3. Group cached by series (descending version), keep labels
    $seriesMap = @{}
    foreach ($pv in $PhpVersions) {
        $series = Get-PhpSeries $pv.Version
        if (-not $seriesMap.ContainsKey($series)) { $seriesMap[$series] = @() }
        $seriesMap[$series] += $pv
    }

    # 4. Determine candidate series: every cached series + every stable series with a resolved latest
    $allSeries = @()
    foreach ($s in $seriesMap.Keys) { $allSeries += $s }
    foreach ($s in $latestBySeries.Keys) { $allSeries += $s }
    $allSeries = @($allSeries | Sort-Object { [version]$_ } -Descending | Select-Object -Unique)

    # 5. Build menu rows — ONE row per series (newest cached variant as the
    #    label, '*' when the series has multiple cached variants).
    $rows = @()   # @{ Series; Kind='cached'|'missing'; Label; Version; Path; Latest; Stale; Variants }
    foreach ($series in $allSeries) {
        $latest = $null
        if ($latestBySeries.ContainsKey($series)) { $latest = $latestBySeries[$series] }

        $cached = @()
        if ($seriesMap.ContainsKey($series)) { $cached = @($seriesMap[$series]) }
        if ($cached.Count -gt 0) {
            # Newest cached variant: version desc, then pre-release rank desc
            # (RC > beta > alpha) for same-numeric-version builds.
            $newest = @($cached | Sort-Object @{ Expression = { [version]$_.Version }; Descending = $true }, @{ Expression = { Get-PhpPreReleaseRank $_ }; Descending = $true })[0]

            $stale = $false
            if ($latest) {
                try { $stale = ([version]$newest.Version -lt [version]$latest.Version) } catch { }
            }
            $rows += @{
                Series    = $series
                Kind      = 'cached'
                Label     = if ($newest.Label) { $newest.Label } else { $newest.Version }
                Version   = $newest.Version
                Path      = $newest.Path
                Latest    = if ($latest) { $latest.Version } else { $null }
                LatestUrl = if ($latest) { $latest.Url } else { $null }
                Stale     = $stale
                Variants  = $cached.Count
            }
        }
        elseif ($latest) {
            # Series has a stable target but nothing cached → offer to download & install
            $rows += @{
                Series    = $series
                Kind      = 'missing'
                Label     = $latest.Version
                Version   = $latest.Version
                Path      = $null
                Latest    = $latest.Version
                LatestUrl = $latest.Url
                Stale     = $false
                Variants  = 0
            }
        }
    }

    if ($rows.Count -eq 0) {
        Write-Info "No PHP versions cached and nothing to download."
        return $null
    }

    # 6. Render menu
    Write-Host ""
    Write-Host "PHP:" -ForegroundColor White
    for ($i = 0; $i -lt $rows.Count; $i++) {
        $r = $rows[$i]
        $tag = ""
        $tagColor = "Cyan"

        if ($r.Kind -eq 'missing') {
            $tag = " (not cached — download & install)"
            $tagColor = "Yellow"
        }
        else {
            # Tag relative to the newest cached patch
            if ($Installed) {
                $vt = Get-VersionTag $r.Version $Installed
                $tag = $vt.Tag; $tagColor = $vt.Color
            }
            # The installed build lives in this series but is not the newest
            # cached patch — keep the "current" visible in the list.
            if ($Installed -and (Get-PhpSeries $Installed) -eq $r.Series) {
                try {
                    if ([version]$r.Version -eq [version]$Installed) {
                        $tag = " (current)"; $tagColor = "Green"
                    }
                    elseif ($tag -notmatch 'current') {
                        $tag += " — current: $Installed"
                    }
                } catch { }
            }
            if ($r.Stale -and $r.Latest) {
                $tag += " → $($r.Latest) is available"
                # Keep "(current)" green even when a newer patch is hinted
                if ($tag -notmatch 'current') { $tagColor = "Yellow" }
            }
            if ($r.Variants -gt 1) { $tag += " *" }
        }

        Write-Host "  [$($i + 1)] $($r.Label)" -NoNewline -ForegroundColor Cyan
        if ($tag) { Write-Host $tag -ForegroundColor $tagColor } else { Write-Host "" }
    }
    Write-Host "  [S] skip" -ForegroundColor DarkGray

    # 7. Selection — strict: only a plain number is accepted (rejects "2d" etc.)
    $choice = Read-Host "  Choose"
    if ($choice -match '^[Ss]$' -or [string]::IsNullOrWhiteSpace($choice)) { return $null }
    if ($choice -notmatch '^\d+$') { Write-Warn "  Invalid choice — skipping PHP"; return $null }
    $idx = [int]$choice - 1
    if ($idx -lt 0 -or $idx -ge $rows.Count) { Write-Warn "  Invalid choice — skipping PHP"; return $null }

    $row = $rows[$idx]

    # 8a. Missing series → download & install
    if ($row.Kind -eq 'missing') {
        return @{ Chosen = $true; Version = $row.Version; Download = $row.LatestUrl }
    }

    # 8b. Multiple variants in this series → sub-menu
    if ($row.Variants -gt 1) {
        $sub = Show-PhpVariantSubMenu -Series $row.Series -Variants @($seriesMap[$row.Series]) -LatestVersion $row.Latest -LatestUrl $row.LatestUrl -Installed $Installed
        if (-not $sub) { return $null }
        return $sub
    }

    # 8c. Single cached entry, stale → offer newer patch
    if ($row.Stale -and $row.Latest) {
        Write-Host ""
        Write-Info "$($row.Latest) is available for PHP $($row.Series)."
        $ans = Read-Host "  [I]nstall latest / [U]se existing ($($row.Version))"
        if ($ans -match '^[Ii]$') {
            Write-Host ""
            $del = Read-Host "  Delete cached $($row.Version)? [Y]es/[N]o (keep both)"
            $prune = $null
            if ($del -match '^[Yy]$') { $prune = $row.Path }
            return @{ Chosen = $true; Version = $row.Latest; Download = $row.LatestUrl; PruneOld = $prune }
        }
        # fall through → use existing
    }

    # Selecting the already-installed build is a no-op
    if ($Installed) {
        try {
            if ([version]$row.Version -eq [version]$Installed) {
                Write-Info "$($row.Version) is already installed — no changes made."
                return $null
            }
        } catch { }
    }

    # 8d. Single cached entry (or user chose "use existing")
    return @{ Chosen = $true; Version = $row.Version; Path = $row.Path }
}

function Show-PhpVariantList {
# Renders the variant sub-menu list (shared by the initial render and the
# re-render after a delete, so both obey the same rules: pre-release labels,
# newer/older/current tags, no delete on the installed build, and the
# "newer — download" row only when the latest patch is NOT already cached).
    param(
        [string]$Series,
        [object[]]$Sorted,
        [string]$LatestVersion,
        [string]$Installed
    )

    Write-Host ""
    Write-Host "PHP $Series — variants:" -ForegroundColor White
    for ($i = 0; $i -lt $Sorted.Count; $i++) {
        $v = $Sorted[$i]
        $vLabel = if ($v.Label) { $v.Label } else { $v.Version }
        $tag = ""
        $tagColor = "Cyan"
        if ($Installed) {
            $vt = Get-VersionTag $v.Version $Installed
            $tag = $vt.Tag; $tagColor = $vt.Color
        }
        Write-Host "  [$($i + 1)] $vLabel" -NoNewline -ForegroundColor Cyan
        if ($tag) { Write-Host $tag -ForegroundColor $tagColor } else { Write-Host "" }
        # Never offer to delete the currently installed build
        $isCurrent = $false
        if ($Installed) {
            try { $isCurrent = ([version]$v.Version -eq [version]$Installed) } catch { }
        }
        if (-not $isCurrent) {
            Write-Host "        [d] delete this cached copy" -ForegroundColor DarkGray
        }
    }

    # Offer a download row only when the series' latest patch is NOT already cached
    $latestCached = $false
    if ($LatestVersion) {
        foreach ($v in $Sorted) {
            try { if ([version]$v.Version -eq [version]$LatestVersion) { $latestCached = $true } } catch { }
        }
    }
    if ($LatestVersion -and -not $latestCached) {
        Write-Host "  [$($Sorted.Count + 1)] $LatestVersion (newer — download)" -ForegroundColor Yellow
    }
    Write-Host "  [S] skip" -ForegroundColor DarkGray
}

function Show-PhpVariantSubMenu {
# Sub-menu for a PHP series with multiple cached variants. Each variant can be
# installed (by number) or deleted ([d] delete with Yes/No confirm). If a newer
# patch is available it is offered as an extra option.
    param(
        [string]$Series,
        [object[]]$Variants,
        [string]$LatestVersion,
        [string]$LatestUrl,
        [string]$Installed
    )

    $sorted = @($Variants | Sort-Object @{ Expression = { [version]$_.Version }; Descending = $true }, @{ Expression = { Get-PhpPreReleaseRank $_ }; Descending = $true })

    Show-PhpVariantList -Series $Series -Sorted $sorted -LatestVersion $LatestVersion -Installed $Installed

    $anyDelete = $false

    while ($true) {
        $choice = Read-Host "  Choose"
        if ($choice -match '^[Ss]$' -or [string]::IsNullOrWhiteSpace($choice)) {
            if ($anyDelete) { return @{ Refresh = $true } }
            return $null
        }

        # Bare "d" — explain the delete format
        if ($choice -match '^[Dd]$') {
            Write-Info "  To delete a cached copy, type d<number> — e.g. d2 deletes variant [2]."
            continue
        }

        # Delete action: "d2" or "2d" (bare "d" explains the format)
        $deleteRow = -1
        if ($choice -match '^[Dd](\d+)$')    { $deleteRow = [int]$matches[1] - 1 }
        elseif ($choice -match '^(\d+)[Dd]$') { $deleteRow = [int]$matches[1] - 1 }
        if ($deleteRow -ge 0) {
            if ($deleteRow -ge $sorted.Count) {
                Write-Warn "  Invalid delete choice."
                continue
            }
            $dIdx = $deleteRow
            $target = $sorted[$dIdx]
            $targetLabel = if ($target.Label) { $target.Label } else { $target.Version }
            # Never delete the currently installed build
            $targetIsCurrent = $false
            if ($Installed) {
                try { $targetIsCurrent = ([version]$target.Version -eq [version]$Installed) } catch { }
            }
            if ($targetIsCurrent) {
                Write-Warn "  $targetLabel is the installed build — cannot delete it."
                continue
            }
            Write-Host ""
            $confirm = Read-Host "  Delete $targetLabel from cache? [Y]es/[N]o"
            if ($confirm -match '^[Yy]$') {
                Remove-Item $target.Path -Force -ErrorAction SilentlyContinue
                Write-Ok "Deleted $targetLabel from cache."
                $anyDelete = $true
                # Rebuild list
                $sorted = @($sorted | Where-Object { $_.Path -ne $target.Path })
                if ($sorted.Count -eq 0) {
                    Write-Info "No PHP variants left for $Series."
                    return @{ Refresh = $true }
                }
                # If nothing actionable remains (only the installed build left),
                # bounce back to the version-switch menu instead of a dead end.
                $actionable = $false
                foreach ($v in $sorted) {
                    if (-not $Installed) { $actionable = $true; break }
                    try {
                        if ([version]$v.Version -ne [version]$Installed) { $actionable = $true; break }
                    } catch { $actionable = $true; break }
                }
                if (-not $actionable) {
                    Write-Info "Only the installed build remains for PHP $Series — returning to the version list."
                    return @{ Refresh = $true }
                }
                Show-PhpVariantList -Series $Series -Sorted $sorted -LatestVersion $LatestVersion -Installed $Installed
                continue
            }
            Write-Info "Keeping $($target.Version)."
            continue
        }

        # Install choice — strict: only a plain number is accepted. This
        # rejects garbage like "2d" that [int] would silently parse as 2.
        if ($choice -notmatch '^\d+$') {
            Write-Warn "  Invalid choice."
            continue
        }
        $idx = [int]$choice - 1
        if ($idx -lt 0 -or $idx -ge $sorted.Count) {
            # "newer — download" row, only valid when the latest is not cached
            $latestCached2 = $false
            if ($LatestVersion) {
                foreach ($v in $sorted) {
                    if ([version]$v.Version -eq [version]$LatestVersion) { $latestCached2 = $true; break }
                }
            }
            if ($LatestVersion -and -not $latestCached2 -and $idx -eq ($sorted.Count)) {
                return @{ Chosen = $true; Version = $LatestVersion; Download = $LatestUrl }
            }
            Write-Warn "  Invalid choice."
            continue
        }

        $target = $sorted[$idx]

        # Selecting the already-installed build is a no-op
        if ($Installed) {
            try {
                if ([version]$target.Version -eq [version]$Installed) {
                    Write-Info "$($target.Version) is already installed — no changes made."
                    return $null
                }
            } catch { }
        }

        # Stale variant → offer the newer patch
        if ($LatestVersion) {
            try {
                if ([version]$target.Version -lt [version]$LatestVersion) {
                    Write-Host ""
                    Write-Info "$($LatestVersion) is available for PHP $Series."
                    $ans = Read-Host "  [I]nstall latest / [U]se existing ($($target.Version))"
                    if ($ans -match '^[Ii]$') {
                        # If the latest is already cached, install it from cache
                        $latestZip = $null
                        foreach ($v in $sorted) {
                            if ([version]$v.Version -eq [version]$LatestVersion) { $latestZip = $v; break }
                        }
                        if ($latestZip) {
                            Write-Host ""
                            $del = Read-Host "  Delete cached $($target.Version)? [Y]es/[N]o (keep both)"
                            $prune = $null
                            if ($del -match '^[Yy]$') { $prune = $target.Path }
                            return @{ Chosen = $true; Version = $LatestVersion; Path = $latestZip.Path; PruneOld = $prune }
                        }
                        Write-Host ""
                        $del = Read-Host "  Delete cached $($target.Version)? [Y]es/[N]o (keep both)"
                        $prune = $null
                        if ($del -match '^[Yy]$') { $prune = $target.Path }
                        return @{ Chosen = $true; Version = $LatestVersion; Download = $LatestUrl; PruneOld = $prune }
                    }
                }
            } catch { }
        }
        return @{ Chosen = $true; Version = $target.Version; Path = $target.Path }
    }
}

function Get-CachedPhpVersions {
# Scans the download cache for PHP TS builds, sorted by version descending
# then pre-release rank (RC > beta > alpha). Skips NTS builds. Used both for
# the initial fu listing and to re-scan after a variant delete.
    $result = @()
    foreach ($zip in (Get-ChildItem -Path $DOWNLOAD_CACHE -Filter "*.zip" -ErrorAction SilentlyContinue)) {
        $name = $zip.BaseName
        if ($name -like "*php-*" -and $name -notlike "*phpmyadmin*") {
            if ($name -like "*-nts-*") {
                Write-Info "Skipping non-thread-safe (NTS) PHP build (incompatible with Apache): $($zip.Name)"
                Write-Host ""
                continue
            }
            $ver = Get-VersionFromZipName $name 'php'
            if ($ver) { $result += @{ Path = $zip.FullName; Version = $ver; Label = Get-PhpZipLabel $name } }
        }
    }
    return @($result | Sort-Object @{ Expression = { [version]$_.Version }; Descending = $true }, @{ Expression = { Get-PhpPreReleaseRank $_ }; Descending = $true })
}

function Invoke-ForcedUpdate {
    Write-Host ""
    Write-Warn "PHP version switching — scanning $DOWNLOAD_CACHE for cached versions..."
    Write-Host ""

    $zipFiles = Get-ChildItem -Path $DOWNLOAD_CACHE -Filter "*.zip" -ErrorAction SilentlyContinue
    if (-not $zipFiles) {
        Write-Err "No cached zip files found in $DOWNLOAD_CACHE"
        return
    }

    # Collect ALL cached versions per component (not just the newest)
    $apacheVersions  = @()
    $phpVersions     = @()
    $mariadbVersions = @()
    $pmaVersions     = @()

    foreach ($zip in $zipFiles) {
        $name = $zip.BaseName
        if ($name -like "*httpd*" -or $name -like "*apache*") {
            $ver = Get-VersionFromZipName $name 'apache'
            if ($ver) { $apacheVersions += @{ Path = $zip.FullName; Version = $ver } }
        }
        elseif ($name -like "*php-*" -and $name -notlike "*phpmyadmin*") {
            if ($name -like "*-nts-*") {
                Write-Info "Skipping non-thread-safe (NTS) PHP build (incompatible with Apache): $($zip.Name)"
                Write-Host ""
                continue
            }
            $ver = Get-VersionFromZipName $name 'php'
            if ($ver) { $phpVersions += @{ Path = $zip.FullName; Version = $ver; Label = Get-PhpZipLabel $name } }
        }
        elseif ($name -like "*mariadb*") {
            $ver = Get-VersionFromZipName $name 'mariadb'
            if ($ver) { $mariadbVersions += @{ Path = $zip.FullName; Version = $ver } }
        }
        elseif ($name -like "*phpmyadmin*") {
            $ver = Get-VersionFromZipName $name 'phpmyadmin'
            if ($ver) { $pmaVersions += @{ Path = $zip.FullName; Version = $ver } }
        }
    }

    # Sort each by version descending
    $apacheVersions  = @($apacheVersions  | Sort-Object { [version]$_.Version } -Descending)
    # PHP: break numeric-version ties by pre-release rank (RC > beta > alpha)
    $phpVersions     = @($phpVersions | Sort-Object @{ Expression = { [version]$_.Version }; Descending = $true }, @{ Expression = { Get-PhpPreReleaseRank $_ }; Descending = $true })
    $mariadbVersions = @($mariadbVersions | Sort-Object { [version]$_.Version } -Descending)
    $pmaVersions     = @($pmaVersions     | Sort-Object { [version]$_.Version } -Descending)

    # Get installed versions
    $currentApacheVer  = Get-ApacheVersion
    $currentPhpVer     = Get-PhpVersion
    $currentMariadbVer = Get-MariaDbVersion
    $currentPmaVer     = Get-PhpMyAdminVersion

    # ---- Summary ----
    Write-Host "Cached versions in $DOWNLOAD_CACHE`:" -ForegroundColor White
    Write-Host ""

    function Show-ComponentSummary($label, $installed, $cachedList) {
        Write-Host "$label" -NoNewline -ForegroundColor White
        Write-Host " — installed: " -NoNewline
        if ($installed) {
            # Flag pre-release builds (newer than the latest stable)
            if (Test-PhpIsPreRelease $installed) {
                Write-Host "$installed (pre-release)".PadRight(20) -NoNewline -ForegroundColor Yellow
            } else {
                Write-Host $installed.PadRight(7) -NoNewline -ForegroundColor Green
            }
        } else {
            Write-Host "none    " -NoNewline -ForegroundColor DarkGray
        }
        Write-Host " |  cache: " -NoNewline
        if ($cachedList.Count -eq 0) {
            Write-Host "none" -ForegroundColor DarkGray
        } else {
            $labels = @($cachedList | ForEach-Object { if ($_.Label) { $_.Label } else { $_.Version } })
            Write-Host ($labels -join ", ") -ForegroundColor Cyan
        }
    }

    Show-ComponentSummary "Apache    " $currentApacheVer  $apacheVersions
    Show-ComponentSummary "PHP       " (Get-PhpVersionLabel) $phpVersions
    Show-ComponentSummary "MariaDB   " $currentMariadbVer $mariadbVersions
    Show-ComponentSummary "phpMyAdmin" $currentPmaVer     $pmaVersions

    # ---- Interactive selection ----
    # PHP gets its own series-aware menu; the other three keep the flat list.
    $selectedApache  = $null
    $selectedPhp     = $null
    $selectedMariadb = $null
    $selectedPma     = $null

    $anyChoice = $false

    # --- PHP: series-aware version switching (loop: variant deletes refresh
    # the listing, since the cache changed under us) ---
    while ($true) {
        $phpMenu = Show-PhpSwitchMenu -PhpVersions $phpVersions -Installed $currentPhpVer
        if ($phpMenu -and $phpMenu.Refresh) {
            # A variant was deleted from the cache — re-scan and re-show the menu
            $phpVersions = @(Get-CachedPhpVersions)
            continue
        }
        if ($phpMenu -and $phpMenu.Chosen) {
            $selectedPhp = $phpMenu
            $anyChoice = $true
            Write-Ok "PHP → $($phpMenu.Version)"
        }
        break
    }
    Write-Host ""

    # --- Apache / MariaDB / phpMyAdmin: flat cached list ---
    $components = @(
        @{ Name = 'Apache';     Installed = $currentApacheVer;  Cached = $apacheVersions;  Var = 'selectedApache' }
        @{ Name = 'MariaDB';    Installed = $currentMariadbVer; Cached = $mariadbVersions; Var = 'selectedMariadb' }
        @{ Name = 'phpMyAdmin'; Installed = $currentPmaVer;     Cached = $pmaVersions;     Var = 'selectedPma' }
    )

    foreach ($comp in $components) {
        if ($comp.Cached.Count -eq 0) { continue }

        # If only one cached version and it matches installed, skip
        if ($comp.Cached.Count -eq 1 -and $comp.Installed -and $comp.Cached[0].Version -eq $comp.Installed) {
            continue
        }

        Write-Host "$($comp.Name):" -ForegroundColor White

        for ($i = 0; $i -lt $comp.Cached.Count; $i++) {
            $v = $comp.Cached[$i].Version
            $tag = ""
            $tagColor = "Cyan"
            if ($comp.Installed) {
                $vt = Get-VersionTag $v $comp.Installed
                $tag = $vt.Tag; $tagColor = $vt.Color
            }
            Write-Host "  [$($i + 1)] $v" -NoNewline -ForegroundColor Cyan
            if ($tag) {
                Write-Host $tag -ForegroundColor $tagColor
            } else {
                Write-Host ""
            }
        }
        Write-Host "  [S] skip" -ForegroundColor DarkGray

        $choice = Read-Host "  Choose"
        if ($choice -match '^[Ss]$' -or [string]::IsNullOrWhiteSpace($choice)) {
            continue
        }
        try {
            $idx = [int]$choice - 1
            if ($idx -ge 0 -and $idx -lt $comp.Cached.Count) {
                Set-Variable -Name $comp.Var -Value $comp.Cached[$idx]
                $anyChoice = $true
                Write-Ok "$($comp.Name) → $($comp.Cached[$idx].Version)"
            } else {
                Write-Warn "  Invalid choice — skipping $($comp.Name)"
            }
        } catch {
            Write-Warn "  Invalid choice — skipping $($comp.Name)"
        }
    }

    if (-not $anyChoice) {
        Write-Host ""
        Write-Info "Nothing selected — no changes made."
        return
    }

    # ---- Apply ----
    $needsApache  = ($null -ne $selectedApache)
    $needsPhp     = ($null -ne $selectedPhp)
    $needsMariadb = ($null -ne $selectedMariadb)
    $needsPma     = ($null -ne $selectedPma)

    # If PHP chose a fresh download, fetch it into the cache before stopping services
    if ($needsPhp -and $selectedPhp.Download) {
        Write-Host ""
        Write-Info "Downloading PHP $($selectedPhp.Version)..."
        $zipPath = Invoke-DownloadToCache $selectedPhp.Download "PHP $($selectedPhp.Version)"
        if (-not $zipPath) {
            Write-Err "PHP download failed — aborting."
            return
        }
        $selectedPhp.Path = $zipPath
        if ($selectedPhp.PruneOld) {
            Write-Ok "Deleted old cached zip: $($selectedPhp.PruneOld)"
            Remove-Item $selectedPhp.PruneOld -Force -ErrorAction SilentlyContinue
            $selectedPhp.PruneOld = $null
        }
    }

    Stop-WebStackServices
    Start-Sleep -Seconds 2

    Write-Host ""
    Write-Warn "Applying selected versions..."

    $prevProgress = $ProgressPreference
    $ProgressPreference = 'SilentlyContinue'

    if ($needsApache) {
        Remove-Item $APACHE_PATH -Recurse -Force -ErrorAction SilentlyContinue
        Invoke-ExtractZip $selectedApache.Path $APACHE_PATH "Apache"
        Invoke-ConfigureApache
        Write-Host ""
    }
    if ($needsPhp) {
        Remove-Item $PHP_PATH -Recurse -Force -ErrorAction SilentlyContinue
        Invoke-ExtractZip $selectedPhp.Path $PHP_PATH "PHP"
        Invoke-ConfigurePhp
        Invoke-FixSqliteDll
        Invoke-CopyPhpDlls
        # PHP major may have changed (e.g. 8.x → 7.x): the Apache module DLL
        # name follows the major version, so re-point httpd.conf at it.
        Invoke-ConfigureApache

        # Fail loudly here rather than letting Apache take the blame later.
        $phpHealth = Test-PhpRuntimeHealthy
        if ($phpHealth.Ok) {
            Write-Ok "PHP $($phpHealth.Detail) verified - core and extensions load"
        }
        else {
            Write-Err "PHP verification FAILED: $($phpHealth.Detail)"
            Write-Info "  That is a mismatched PHP tree, not an Apache problem."
        }
        Write-Host ""
    }
    if ($needsMariadb) {
        Backup-MariaDbData

        Remove-Item $MARIADB_PATH -Recurse -Force -ErrorAction SilentlyContinue
        Invoke-ExtractZip $selectedMariadb.Path $MARIADB_PATH "MariaDB"

        Restore-MariaDbData

        Invoke-ConfigureMariaDb
    }
    if ($needsPma) {
        Remove-Item $PHPMYADMIN_PATH -Recurse -Force -ErrorAction SilentlyContinue
        Invoke-ExtractZip $selectedPma.Path $PHPMYADMIN_PATH "phpMyAdmin"
        Invoke-ConfigurePhpMyAdmin
    }

    Start-WebStackServices
    $ProgressPreference = $prevProgress

    if ($needsPma) { Invoke-ConfigurePmaStorage }

    Write-Host ""
    Write-Host "Forced update complete"

    Save-PostUpdateConfig
}

# ============================================================
#  DELETE
# ============================================================

function Invoke-DeleteWebStack {
    Write-Host ""
    Write-Host "========================================" -ForegroundColor Red
    Write-Host "  DELETE PHP WEB STACK" -ForegroundColor Red
    Write-Host "========================================" -ForegroundColor Red
    Write-Host ""
    Write-Warn "The following WILL be deleted:"
    Write-Warn "  - Apache  ($APACHE_PATH)"
    Write-Warn "  - PHP     ($PHP_PATH)"
    Write-Warn "  - MariaDB binaries ($MARIADB_PATH\bin)"
    Write-Warn "  - phpMyAdmin ($PHPMYADMIN_PATH)"
    Write-Warn "  - Log files ($LOGS_PATH)"
    Write-Host ""
    Write-Info "The following will NOT be deleted:"
    Write-Info "  - Your website files in $WWW_PATH"
    Write-Info "  - Your databases in $MARIADB_PATH\data (moved to $BASE\data_backup)"
    Write-Info "  - Your config files (moved to $BASE\config_backup)"
    Write-Info "  - Cached downloads in $DOWNLOAD_CACHE"
    Write-Host ""

    $confirm = Read-Host "Type 'DELETE' to confirm"

    if ($confirm -cne "DELETE") {
        Write-Info "Nothing was deleted."
        return
    }

    Stop-WebStackServices

    # Preserve MariaDB data before removing
    $dataDir = "$MARIADB_PATH\data"
    $backupDir = "$BASE\data_backup"
    if (Test-Path $dataDir) {
        # If a previous backup already exists, timestamp it to avoid collision
        if (Test-Path $backupDir) {
            $ts = Get-Date -Format "yyyyMMdd_HHmmss"
            $oldBackup = "$BASE\data_backup_$ts"
            Write-Warn "Existing data_backup found — renaming to data_backup_$ts"
            Rename-Item $backupDir $oldBackup
        }
        Write-Host ""
        Write-Info "Backing up database data to $backupDir ..."
        New-Item -ItemType Directory -Force -Path $backupDir | Out-Null
        Get-ChildItem $dataDir | ForEach-Object {
            Move-Item $_.FullName $backupDir -Force
        }
        Write-Ok "Database data preserved at $backupDir"
        Write-Host ""
    }

    # Backup config files before removal
    $configBackupDir = "$BASE\config_backup"
    New-Item -ItemType Directory -Force -Path $configBackupDir | Out-Null
    $configs = @(
        @{ Src = "$APACHE_PATH\conf\httpd.conf";   Name = "httpd.conf" },
        @{ Src = "$PHP_PATH\php.ini";               Name = "php.ini" },
        @{ Src = "$MARIADB_PATH\my.ini";             Name = "my.ini" },
        @{ Src = "$PHPMYADMIN_PATH\config.inc.php";  Name = "config.inc.php" }
    )
    foreach ($cfg in $configs) {
        if (Test-Path $cfg.Src) {
            Copy-Item $cfg.Src "$configBackupDir\$($cfg.Name)" -Force
        }
    }
    Write-Ok "Config files backed up to $configBackupDir"

    Remove-Tree $APACHE_PATH
    Write-Ok "Apache removed"

    Remove-Tree $PHP_PATH
    Write-Ok "PHP removed"

    Remove-Tree $MARIADB_PATH
    Write-Ok "MariaDB removed"

    Remove-Tree $PHPMYADMIN_PATH
    Write-Ok "phpMyAdmin removed"

    Remove-Tree $LOGS_PATH
    Write-Ok "Log files removed"
    Write-Host ""

    # Unregister Windows services if present
    Remove-Services

    # Remove webstack from user PATH
    Remove-FromPath

    # Clear saved config so next run prompts for a fresh location
    Clear-Config
    Write-Info "Installer config cleared — next run will prompt for a new path."

    Write-Host ""
    Write-Host "========================================" -ForegroundColor White
    Write-Host "  Stack Deleted — Cleanup Complete" -ForegroundColor White
    Write-Host "========================================" -ForegroundColor White
    Write-Host ""
    Write-Info "Website files preserved: $WWW_PATH"
    Write-Info "Database backup:         $backupDir"
    Write-Info "Config backup:           $configBackupDir"
    Write-Info "Download cache:          $DOWNLOAD_CACHE"
    Write-Host ""
}

# ============================================================
#  DASHBOARD
# ============================================================

# ============================================================
#  CLI — machine-readable status + non-interactive control
# ============================================================
# Contract: .junk/cli-contract.md (promotes to docs/CLI.md when shipped).
# Rules: stdout carries the payload only, nothing prompts, nothing writes.
# Write-Host lands on the information stream, so callers suppress it with
# `6>$null` and the piped payload stays clean (verified behaviour).
# This file MUST keep its UTF-8 BOM: PowerShell 5.1 decodes it as ANSI
# without one and the em dashes above break string literals.

$script:STATUS_SCHEMA  = 1
$script:VERSION_CACHE  = $null

function Get-ScriptVersion {
    # The header comment owns the version when the script is a file on disk.
    # A streamed run (`irm ... | iex`) has no file, so the literal below is the
    # fallback and must be bumped together with the header.
    if ($script:VERSION_CACHE) { return $script:VERSION_CACHE }
    $script:VERSION_CACHE = '2.5.0'
    if ($PSCommandPath -and (Test-Path -LiteralPath $PSCommandPath)) {
        foreach ($line in (Get-Content $PSCommandPath -TotalCount 12 -ErrorAction SilentlyContinue)) {
            if ($line -match '^#\s*Version:\s*(\S+)') { $script:VERSION_CACHE = $matches[1]; break }
        }
    }
    return $script:VERSION_CACHE
}

function Get-PlatformCaption {
    # Registry first (~2ms), CIM only as a fallback (~530ms measured). The
    # dashboard pays this too, so it matters beyond CLI polling.
    if ($null -eq $script:OS_CAPTION_CACHE) {
        $caption = $null
        try {
            $key = Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion' -ErrorAction Stop
            if ($key.ProductName) {
                $caption = [string]$key.ProductName
                # Windows 11 still ships ProductName "Windows 10 Pro" in the
                # registry. Build 22000 is the first Windows 11 build, so trust
                # the build number and correct the name.
                $build = 0
                if ($key.CurrentBuildNumber) {
                    if ([int]::TryParse([string]$key.CurrentBuildNumber, [ref]$build) -and $build -ge 22000) {
                        $caption = $caption -replace '^Windows 10', 'Windows 11'
                    }
                }
                if ($key.DisplayVersion) { $caption = "$caption $($key.DisplayVersion)" }
            }
        }
        catch { }
        if (-not $caption) {
            $caption = (Get-CimInstance Win32_OperatingSystem -ErrorAction SilentlyContinue).Caption
        }
        $script:OS_CAPTION_CACHE = $caption
    }
    return $script:OS_CAPTION_CACHE
}

function Initialize-Paths {
    # Single source of truth for every derived path, shared by the dashboard
    # flow and by CLI verbs. $BASE must already be resolved via Get-Config.
    $script:APACHE_PATH     = "$BASE\apache"
    $script:PHP_PATH        = "$BASE\php"
    $script:MARIADB_PATH    = "$BASE\mariadb"
    $script:WWW_PATH        = "$BASE\www"
    $script:LOGS_PATH       = "$BASE\logs"
    $script:PHPMYADMIN_PATH = "$BASE\phpmyadmin"
    # Re-derived from the resolved $BASE: the line-18 default pointed at
    # C:\phpup\downloads even when the stack lived elsewhere.
    $script:DOWNLOAD_CACHE  = "$BASE\downloads"
}

function Get-ListeningPorts {
    # One managed enumeration (~60ms) for every port we care about.
    $set = @{}
    try {
        foreach ($ep in [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().GetActiveTcpListeners()) {
            $set[[int]$ep.Port] = $true
        }
    }
    catch { }
    return $set
}

function Get-PortOwner {
    # netstat is consulted ONLY when a port is held by something that is not
    # us, so the happy path never pays its ~220ms.
    param([int]$Port)
    $line = netstat -ano 2>$null | Select-String ":$Port\s" | Select-String "LISTENING" | Select-Object -First 1
    if (-not $line) { return $null }
    $ownerPid = ($line.ToString().Trim() -split '\s+')[-1]
    $proc = Get-Process -Id ([int]$ownerPid) -ErrorAction SilentlyContinue
    if ($proc) { return "$($proc.ProcessName) (PID $ownerPid)" }
    return "PID $ownerPid"
}

function Get-ServicePid {
    # sc.exe queryex reports the service PID without elevation, WMI or CIM
    # (measured ~20ms vs ~1.1s for the equivalent CIM query).
    param([string]$ServiceName)
    if (-not $ServiceName) { return $null }
    try {
        foreach ($line in (& sc.exe queryex "$ServiceName" 2>$null)) {
            if ($line -match 'PID\s*:\s*(\d+)') { return [int]$matches[1] }
        }
    }
    catch { }
    return $null
}

function Get-ComponentPids {
    # PIDs are filtered by install path so a foreign Apache/MariaDB (XAMPP,
    # another phpup checkout) is never reported as ours. ExecutablePath is
    # only readable for our own processes, so service PIDs come from
    # Get-ServicePid instead — never "no PIDs" just because we are unelevated.
    param([string[]]$Names)
    $found = @()
    foreach ($proc in @(Get-ProcessesByName -Names $Names)) {
        $exe = $null
        try { $exe = $proc.ExecutablePath } catch { }
        if ($exe -and ($exe -like "$BASE\*")) { $found += [int]$proc.Id }
    }
    return $found
}

function Resolve-ComponentPids {
    # Fast path: process table only (~25ms). Full path: exact PID from the
    # SCM when the component runs as a service, else a path-filtered scan.
    # sc queryex costs ~70ms per call, which is 40% of a poll tick.
    param([string[]]$Names, [string]$ServiceName, [bool]$ServiceRunning, [switch]$Fast)

    $pids = @()
    if ($Fast) {
        foreach ($proc in @(Get-ProcessesByName -Names $Names)) {
            if ($proc) { $pids += [int]$proc.Id }
        }
        return ,@($pids | Sort-Object -Unique)
    }
    if ($ServiceRunning) {
        $svcPid = Get-ServicePid $ServiceName
        if ($svcPid) { $pids += [int]$svcPid }
    }
    if ($pids.Count -eq 0) {
        foreach ($item in @(Get-ComponentPids -Names $Names)) {
            if ($null -ne $item) { $pids += [int]$item }
        }
    }
    return ,@($pids | Sort-Object -Unique)
}

function Test-CliIsAdmin {
    return ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")
}

function Get-CliStatus {
    param([switch]$Fast)

    $config = Get-Config
    Initialize-Paths

    $apacheInstalled = Test-ApacheInstalled
    $phpInstalled    = Test-PhpInstalled
    $mariaInstalled  = Test-MariaDbInstalled
    $pmaInstalled    = Test-PhpMyAdminInstalled
    $complete        = $apacheInstalled -and $phpInstalled -and $mariaInstalled -and $pmaInstalled

    $state = 'absent'
    if ($apacheInstalled -or $phpInstalled -or $mariaInstalled -or $pmaInstalled) {
        $state = if ($complete) { 'complete' } else { 'partial' }
    }

    $apacheRunning = Test-ApacheRunning
    $mariaRunning  = Test-MariaDbRunning

    # Versions come from config.json, which install/update and
    # Save-PostUpdateConfig write from the live filesystem. Probing the
    # binaries costs ~900ms (httpd -v alone is 579ms), so it is a fallback
    # for a component whose config entry is missing, never the default.
    $cfgVersions = if ($config) { $config.versions } else { $null }
    $vApache  = if ($cfgVersions -and $cfgVersions.apache)     { [string]$cfgVersions.apache }     else { $null }
    $phpLabel = if ($cfgVersions -and $cfgVersions.php)        { [string]$cfgVersions.php }        else { $null }
    $vMaria   = if ($cfgVersions -and $cfgVersions.mariadb)    { [string]$cfgVersions.mariadb }    else { $null }
    $vPma     = if ($cfgVersions -and $cfgVersions.phpmyadmin) { [string]$cfgVersions.phpmyadmin } else { $null }
    $probed   = $false
    if (-not $Fast) {
        if (-not $vApache)  { $vApache  = Get-ApacheVersion;     $probed = $true }
        if (-not $phpLabel) { $phpLabel = Get-PhpVersionLabel;   $probed = $true }
        if (-not $vMaria)   { $vMaria   = Get-MariaDbVersion;    $probed = $true }
        if (-not $vPma)     { $vPma     = Get-PhpMyAdminVersion; $probed = $true }
    }
    $versionSource = if ($probed) { 'mixed' } else { 'config' }
    $vPhp  = if ($phpLabel) { ([string]$phpLabel -split ' ')[0] } else { $null }
    $phpPre = Test-PhpIsPreRelease ([string]$phpLabel)

    # ---- Services ----
    $apacheSvc = Get-Service -Name $SERVICE_APACHE  -ErrorAction SilentlyContinue
    $mariaSvc  = Get-Service -Name $SERVICE_MARIADB -ErrorAction SilentlyContinue
    $svcItems  = @()
    $autostart = $true
    foreach ($pair in @(@{ Name = $SERVICE_APACHE; Svc = $apacheSvc }, @{ Name = $SERVICE_MARIADB; Svc = $mariaSvc })) {
        $isReg   = $null -ne $pair.Svc
        $enabled = $false
        if ($isReg) {
            try { $enabled = ($pair.Svc.StartType -eq 'Automatic') } catch { $enabled = $false }
            if (-not $enabled) { $autostart = $false }
        }
        $svcItems += [ordered]@{ name = $pair.Name; registered = $isReg; enabled = $enabled }
    }
    $registered   = ($null -ne $apacheSvc) -and ($null -ne $mariaSvc)
    if (-not $registered) { $autostart = $false }

    $apacheSvcRunning = ($null -ne $apacheSvc) -and ($apacheSvc.Status -eq 'Running')
    $mariaSvcRunning  = ($null -ne $mariaSvc)  -and ($mariaSvc.Status  -eq 'Running')
    $mode = 'none'
    if ($apacheRunning -or $mariaRunning) {
        if ($apacheSvcRunning -and $mariaSvcRunning) { $mode = 'service' }
        elseif ($apacheSvcRunning -or $mariaSvcRunning) { $mode = 'mixed' }
        else { $mode = 'process' }
    }

    # ---- PIDs and ports ----
    $apachePids = if ($apacheRunning) { @(Resolve-ComponentPids -Names @('httpd') -ServiceName $SERVICE_APACHE -ServiceRunning $apacheSvcRunning -Fast:$Fast) } else { @() }
    $mariaPids  = if ($mariaRunning)  { @(Resolve-ComponentPids -Names @('mysqld', 'mariadbd') -ServiceName $SERVICE_MARIADB -ServiceRunning $mariaSvcRunning -Fast:$Fast) } else { @() }

    $listening = Get-ListeningPorts
    $portRows  = @()
    foreach ($p in @(80, 3306)) {
        $isUp = [bool]$listening[$p]
        $ours = $false
        if ($isUp) { $ours = if ($p -eq 80) { $apacheRunning } else { $mariaRunning } }
        $owner = $null
        if ($isUp -and $ours) {
            $firstPid = if ($p -eq 80) { $apachePids | Select-Object -First 1 } else { $mariaPids | Select-Object -First 1 }
            $owner = if ($firstPid) { "$(if ($p -eq 80) { 'httpd' } else { 'mariadbd' }) (PID $firstPid)" }
                     else { "phpup (PID unknown)" }
        }
        elseif ($isUp) {
            $owner = Get-PortOwner -Port $p
        }
        $portRows += [ordered]@{ port = $p; listening = $isUp; ours = $ours; owner = $owner }
    }
    $apachePorts = [array]@()
    $mariaPorts  = [array]@()
    foreach ($row in $portRows) {
        if (-not $row.ours) { continue }
        if ($row.port -eq 80) { $apachePorts = [array]@(80) } else { $mariaPorts = [array]@(3306) }
    }

    # ---- Prerequisites (full status only) ----
    $prereq = $null
    if (-not $Fast) {
        # One registry pass, not two: Get-VcRedistVersion already enumerates
        # the same Uninstall keys Test-VcRedistInstalled scans (~400ms each).
        $vcVersionObj = Get-VcRedistVersion
        $vcOk = [bool]($vcVersionObj -and ($vcVersionObj -ge $VC_MIN_VERSION))
        $prereq = [ordered]@{
            vc_redist = [ordered]@{
                ok      = $vcOk
                version = if ($vcVersionObj) { [string]$vcVersionObj } else { $null }
                minimum = [string]$VC_MIN_VERSION
            }
        }
    }

    # ---- Platform ----
    $arch = $env:PROCESSOR_ARCHITECTURE
    if ($arch -eq 'AMD64') { $arch = 'x86_64' }
    # Cost is one registry read (~2ms), so this belongs in the fast path too:
    # the panel displays it, and a null there just looks broken.
    $caption = Get-PlatformCaption
    if ($caption -match '(?:Microsoft )?Windows (.*)') { $caption = $matches[1] }
    $distro = $caption

    $sapi = $null
    $cliOnPath = $false
    if ($phpInstalled) {
        $sapi = if (Test-PhpApacheModuleWired) { 'apache2handler' } else { 'cli' }
        # PATH membership without spawning Get-Command (~20ms per poll).
        $cliOnPath = @($env:PATH -split ';' | Where-Object { $_ -and ($_.TrimEnd('\') -ieq $PHP_PATH) }).Count -gt 0
    }

    $urlRoot = 'http://localhost/'
    $urlPma  = 'http://localhost/phpmyadmin'

    # ---- Warnings ----
    $warnings = @()
    foreach ($row in $portRows) {
        if ($row.listening -and -not $row.ours) {
            $warnings += [ordered]@{
                code      = 'port_conflict'
                component = if ($row.port -eq 80) { 'apache' } else { 'mariadb' }
                message   = "Port $($row.port) is held by $($row.owner) — phpup cannot start this component"
            }
        }
    }
    if ($state -eq 'partial') {
        $warnings += [ordered]@{ code = 'stack_partial'; component = $null; message = 'The stack is partially installed' }
    }
    if (($apacheRunning -or $mariaRunning) -and -not $registered) {
        $warnings += [ordered]@{ code = 'services_not_registered'; component = $null; message = 'Running as processes, not Windows services (no auto-start on boot)' }
    }
    if ($phpPre) {
        $warnings += [ordered]@{ code = 'php_prerelease'; component = 'php'; message = "PHP $phpLabel is a pre-release build" }
    }
    if ($prereq -and -not $prereq.vc_redist.ok) {
        $warnings += [ordered]@{ code = 'vc_redist_missing'; component = $null; message = "VC++ Redistributable $VC_MIN_VERSION or newer is required" }
    }
    if ($phpInstalled -and -not $cliOnPath) {
        $warnings += [ordered]@{ code = 'php_not_on_path'; component = 'php'; message = 'php.exe is not on PATH' }
    }

    return [ordered]@{
        schema       = $script:STATUS_SCHEMA
        generated_at = (Get-Date).ToString('yyyy-MM-ddTHH:mm:sszzz')
        phpup        = [ordered]@{ version = (Get-ScriptVersion); script = 'ps1' }
        platform     = [ordered]@{ os = 'windows'; arch = $arch; backend = 'direct'; distro = $distro }
        install      = [ordered]@{ path = $BASE; state = $state; config_file = (Get-ConfigFilePath) }
        services     = [ordered]@{ mode = $mode; registered = $registered; autostart = $autostart; items = [array]$svcItems }
        components   = [ordered]@{
            apache     = [ordered]@{
                installed = $apacheInstalled; version = $vApache; running = $apacheRunning;
                pids = $apachePids; ports = $apachePorts; service = $SERVICE_APACHE;
                owned_by_phpup = $apacheRunning; notes = $null
            }
            php        = [ordered]@{
                installed = $phpInstalled; version = $vPhp; label = $phpLabel; prerelease = $phpPre;
                running = $null; pids = [array]@(); ports = [array]@();
                sapi = $sapi; cli_on_path = $cliOnPath;
                series_floor = if ($config -and $config.php_min_series) { [string]$config.php_min_series } else { '8.2' };
                notes = $null; version_source = $versionSource
            }
            mariadb    = [ordered]@{
                installed = $mariaInstalled; version = $vMaria; running = $mariaRunning;
                pids = $mariaPids; ports = $mariaPorts; service = $SERVICE_MARIADB;
                owned_by_phpup = $mariaRunning; notes = $null
            }
            phpmyadmin = [ordered]@{
                installed = $pmaInstalled; version = $vPma; running = $null;
                pids = [array]@(); ports = [array]@(); url = $urlPma; notes = $null
            }
        }
        urls         = [ordered]@{ root = $urlRoot; phpmyadmin = $urlPma; phpinfo = 'http://localhost/phpinfo.php' }
        paths        = [ordered]@{ www = $WWW_PATH; logs = $LOGS_PATH; downloads = $DOWNLOAD_CACHE }
        logs         = [ordered]@{
            apache_error  = "$LOGS_PATH\apache_error.log"
            apache_access = "$LOGS_PATH\apache_access.log"
            php_errors    = "$LOGS_PATH\php_errors.log"
            mariadb_error = "$LOGS_PATH\mariadb_error.log"
        }
        prerequisites = $prereq
        ports         = [array]$portRows
        warnings      = [array]$warnings
        errors        = [array]@()
    }
}

function Get-CliPortConflict {
    # Returns a human description of the first foreign-held stack port, or $null.
    $listening = Get-ListeningPorts
    foreach ($pair in @(@{ Port = 80; Running = (Test-ApacheRunning) }, @{ Port = 3306; Running = (Test-MariaDbRunning) })) {
        if ($listening[$pair.Port] -and -not $pair.Running) {
            $owner = Get-PortOwner -Port $pair.Port
            return "Port $($pair.Port) is held by $owner"
        }
    }
    return $null
}

function Write-CliHumanStatus {
    param($Status)
    $comp = $Status.components
    Write-Output "phpup $($Status.phpup.version) | $($Status.platform.os) $($Status.platform.arch) | $($Status.install.state) | $($Status.install.path)"
    Write-Output "Services: $($Status.services.mode) | registered: $($Status.services.registered) | autostart: $($Status.services.autostart)"
    Write-Output ""
    foreach ($name in @('apache', 'php', 'mariadb', 'phpmyadmin')) {
        $c = $comp.$name
        $bits = @($name.PadRight(11), ([string]$c.version).PadRight(10))
        if ($c.installed) {
            if ($c.running -eq $true) {
                $bits += 'running'
                if ($c.pids.Count -gt 0) { $bits += "PID $($c.pids -join ',')" }
                if ($c.ports.Count -gt 0) { $bits += ":$($c.ports -join ',')" }
            }
            elseif ($c.installed -and $c.running -eq $false) { $bits += 'stopped' }
            elseif ($name -eq 'php') { $bits += "sapi: $($c.sapi)"; $bits += "cli: $($c.cli_on_path)" }
            elseif ($c.url) { $bits += $c.url }
        }
        else { $bits += 'not installed' }
        Write-Output ($bits -join '  ')
    }
    if ($Status.warnings.Count -gt 0) {
        Write-Output ""
        foreach ($w in $Status.warnings) { Write-Output "  ! $($w.code): $($w.message)" }
    }
}

function Write-CliJson {
    param($Payload)
    Write-Output ($Payload | ConvertTo-Json -Depth 6 -Compress)
}

function Write-CliUsage {
    Write-Output @'
phpup — Power tools for local PHP development

Usage:
  phpup.ps1                          interactive dashboard
  phpup.ps1 status [-Fast] [-Json]   report stack state
  phpup.ps1 start|stop|restart       control services (idempotent)
  phpup.ps1 version                  print version
  phpup.ps1 help                     this text

Flags:
  -Json    payload on stdout (stderr/host output suppressed)
  -Fast    status only: skip prerequisites and OS caption (polling)
  -Watch N status only: repeat every N seconds as NDJSON
  -Quiet   suppress human output

Exit codes: 0 ok, 1 failed, 2 usage, 3 not installed, 4 elevation required, 5 port conflict
'@
}

function Invoke-CliLifecycle {
    param([string]$Action, [switch]$Json, [switch]$Quiet)

    # Resolve config and derived paths first: Test-StackComplete reads
    # $APACHE_PATH and friends, which are only set by Initialize-Paths.
    $null = Get-Config
    Initialize-Paths

    if (-not (Test-StackComplete)) {
        return @{ code = 3; payload = [ordered]@{ schema = $script:STATUS_SCHEMA; ok = $false; code = 'not_installed'; action = $Action; changed = $false; components = [ordered]@{}; warnings = [array]@(); errors = [array]@( 'The web stack is not installed.' ) } }
    }
    if ((Test-ServicesInstalled) -and -not (Test-CliIsAdmin)) {
        return @{ code = 4; payload = [ordered]@{ schema = $script:STATUS_SCHEMA; ok = $false; code = 'elevation_required'; action = $Action; changed = $false; components = [ordered]@{}; warnings = [array]@(); errors = [array]@( 'phpup services are registered — Administrator rights are required to control them.' ) } }
    }

    if ($Action -eq 'start' -or $Action -eq 'restart') {
        $conflict = Get-CliPortConflict
        if ($conflict) {
            return @{ code = 5; payload = [ordered]@{ schema = $script:STATUS_SCHEMA; ok = $false; code = 'port_conflict'; action = $Action; changed = $false; components = [ordered]@{}; warnings = [array]@( $conflict ); errors = [array]@() } }
        }
    }

    $before = Get-CliStatus -Fast 6>$null

    # $null = keeps anything the start/stop helpers emit on the success stream
    # out of the captured result; Write-Host output still reaches the user.
    if ($Json) {
        switch ($Action) {
            'start'   { $null = Start-WebStackServices 6>$null }
            'stop'    { $null = Stop-WebStackServices  6>$null }
            'restart' { $null = Stop-WebStackServices  6>$null; Start-Sleep -Seconds 2; $null = Start-WebStackServices 6>$null }
        }
    }
    else {
        switch ($Action) {
            'start'   { $null = Start-WebStackServices }
            'stop'    { $null = Stop-WebStackServices }
            'restart' { $null = Stop-WebStackServices; Start-Sleep -Seconds 2; $null = Start-WebStackServices }
        }
    }

    $after = Get-CliStatus -Fast 6>$null
    $changed = ($before.components.apache.running -ne $after.components.apache.running) -or
               ($before.components.mariadb.running -ne $after.components.mariadb.running)

    $ok = if ($Action -eq 'stop') {
        (-not $after.components.apache.running) -and (-not $after.components.mariadb.running)
    }
    else {
        $after.components.apache.running -and $after.components.mariadb.running
    }

    return @{
        code    = if ($ok) { 0 } else { 1 }
        payload = [ordered]@{
            schema     = $script:STATUS_SCHEMA
            ok         = $ok
            code       = if ($ok) { $null } else { 'action_failed' }
            action     = $Action
            changed    = $changed
            components = $after.components
            warnings   = $after.warnings
            errors     = [array]@()
        }
    }
}

function Invoke-CliVerb {
    param([string]$Verb, [switch]$Json, [switch]$Fast, [switch]$Quiet, [int]$Watch)

    # The exit code travels in a script variable, not the return value: the
    # payload goes out on the success stream and capturing both in one
    # assignment would swallow the payload.
    $script:CliExitCode = 0
    $verb = $Verb.ToLower()

    switch ($verb) {
        'status' {
            if ($Watch -gt 0) {
                # One long-lived process, one NDJSON line per interval: process
                # startup (~450ms) would otherwise dominate every poll.
                while ($true) {
                    $payload = Get-CliStatus -Fast 6>$null
                    [Console]::Out.WriteLine(($payload | ConvertTo-Json -Depth 6 -Compress))
                    [Console]::Out.Flush()
                    Start-Sleep -Seconds $Watch
                }
            }
            $payload = Get-CliStatus -Fast:$Fast 6>$null
            if ($Json) { Write-CliJson $payload }
            elseif (-not $Quiet) { Write-CliHumanStatus $payload }
            return
        }
        'version' {
            if ($Json) { Write-CliJson ([ordered]@{ schema = $script:STATUS_SCHEMA; version = (Get-ScriptVersion); script = 'ps1' }) }
            elseif (-not $Quiet) { Write-Output "phpup $(Get-ScriptVersion) (phpup.ps1)" }
            return
        }
        'help' {
            if (-not $Quiet) { Write-CliUsage }
            return
        }
        { $_ -in 'start', 'stop', 'restart' } {
            $result = Invoke-CliLifecycle -Action $verb -Json:$Json -Quiet:$Quiet
            if ($Json) { Write-CliJson $result.payload }
            elseif (-not $Quiet) {
                $p = $result.payload
                $state = if ($p.ok) { 'ok' } else { "failed: $(if ($p.code) { $p.code } else { 'unknown' })" }
                Write-Output ("{0}: {1} (changed: {2})" -f $p.action, $state, $p.changed)
            }
            $script:CliExitCode = $result.code
            return
        }
        default {
            [Console]::Error.WriteLine("Unknown command: $Verb")
            if (-not $Quiet) { [Console]::Error.WriteLine("Run 'phpup.ps1 help' for usage.") }
            $script:CliExitCode = 2
            return
        }
    }
}

function Show-Dashboard {
    Clear-Host

    $stackComplete = Test-StackComplete

    Write-Host ""
    # Render banner with multi-colour: white text, coloured arrows, cyan "phpup"
    $bannerLines = $BANNER_ART -split "`n"
    foreach ($line in $bannerLines) {
        if ($line -match '^\│\s+▲') {
            Write-Host "│         " -NoNewline -ForegroundColor White
            Write-Host "▲" -NoNewline -ForegroundColor Yellow
            Write-Host " " -NoNewline -ForegroundColor White
            Write-Host "▲" -NoNewline -ForegroundColor Green
            Write-Host " " -NoNewline -ForegroundColor White
            Write-Host "▲" -NoNewline -ForegroundColor Cyan
            Write-Host "               │" -ForegroundColor White
        }
        elseif ($line -match 'phpup') {
            Write-Host "│         " -NoNewline -ForegroundColor White
            # Default foreground: Blue maps to dark blue, which is unreadable on
            # dark console themes, so the wordmark relies on weight, not hue.
            $verLabel = "v" + (Get-ScriptVersion)
            Write-Host ("phpup " + $verLabel) -NoNewline
            $pad = 29 - 9 - ("phpup " + $verLabel).Length
            if ($pad -lt 1) { $pad = 1 }
            Write-Host ((" " * $pad) + "│") -ForegroundColor White
        }
        else {
            Write-Host $line -ForegroundColor White
        }
    }
    Write-Host ""

    # ---- Architecture / OS line ----
    $arch = $env:PROCESSOR_ARCHITECTURE
    if ($arch -eq "AMD64") { $arch = "x86_64" }
    $osCaption = Get-PlatformCaption
    if ($osCaption -match '(?:Microsoft )?Windows (.*)') { $osCaption = $matches[1] }
    Write-Host "Architecture: " -NoNewline
    Write-Host "$arch" -ForegroundColor Cyan -NoNewline
    Write-Host " | Windows: " -NoNewline
    Write-Host "$osCaption" -ForegroundColor Cyan
    Write-Host ""

    # ---- System Prerequisites ----
    Write-Host "System Prerequisites:" -ForegroundColor White
    Write-Host "~~~~~~~~~~~~~~~~~~~~~"
    Write-Host "VC++ Redist --> " -NoNewline
    $vcVer = Get-VcRedistVersion
    if ($vcVer) {
        $minVc = [version]"14.51.36231"
        if ($vcVer -ge $minVc) {
            Write-Host "$vcVer" -ForegroundColor Green
        }
        else {
            Write-Host "$vcVer (update recommended -- press V)" -ForegroundColor Yellow
        }
    }
    else {
        Write-Host "not installed (press V to install)" -ForegroundColor Red
    }

    # ---- Stack Status ----
    Write-Host ""
    Write-Host "Your Web Stack:" -ForegroundColor White
    Write-Host "~~~~~~~~~~~~~~~"

    Write-Host "Apache -------> " -NoNewline
    if (Test-ApacheInstalled) {
        Write-Host (Get-ApacheVersion) -ForegroundColor Green
    }
    else {
        Write-Host "not installed" -ForegroundColor Red
    }

    Write-Host "MariaDB ------> " -NoNewline
    if (Test-MariaDbInstalled) {
        Write-Host (Get-MariaDbVersion) -ForegroundColor Green
    }
    else {
        Write-Host "not installed" -ForegroundColor Red
    }

    Write-Host "PHP ----------> " -NoNewline
    if (Test-PhpInstalled) {
        $phpInstalledLabel = Get-PhpVersionLabel
        if (Test-PhpIsPreRelease $phpInstalledLabel) {
            Write-Host "$phpInstalledLabel (pre-release)" -ForegroundColor Yellow
        }
        else {
            Write-Host $phpInstalledLabel -ForegroundColor Green
        }
    }
    else {
        Write-Host "not installed" -ForegroundColor Red
    }

    Write-Host "phpMyAdmin ---> " -NoNewline
    if (Test-PhpMyAdminInstalled) {
        Write-Host (Get-PhpMyAdminVersion) -ForegroundColor Green
    }
    else {
        Write-Host "not installed" -ForegroundColor Red
    }

    # ---- Process Status ----
    Write-Host ""
    Write-Host "Process Status:" -ForegroundColor White
    Write-Host "~~~~~~~~~~~~~~~"

    Write-Host "Apache -------> " -NoNewline
    if (Test-ApacheRunning) {
        Write-Host "running" -ForegroundColor Green
    }
    else {
        Write-Host "stopped" -ForegroundColor Red
    }

    Write-Host "mod_php ------> " -NoNewline
    if (Test-PhpInstalled) {
        if (Test-PhpApacheModuleWired) {
            if (Test-ApacheRunning) {
                Write-Host "active" -ForegroundColor Green
            }
            else {
                Write-Host "stopped" -ForegroundColor Red
            }
        }
        else {
            Write-Host "not wired" -ForegroundColor Yellow
        }
    }
    else {
        Write-Host "not installed" -ForegroundColor Red
    }

    Write-Host "MariaDB ------> " -NoNewline
    if (Test-MariaDbRunning) {
        Write-Host "running" -ForegroundColor Green
    }
    else {
        Write-Host "stopped" -ForegroundColor Red
    }

    # Windows Services (always shown when stack is complete)
    Write-Host ""
    Write-Host "Windows Services:" -ForegroundColor White
    Write-Host "~~~~~~~~~~~~~~~~"
    $svcRegistered = Test-ServicesInstalled
    Write-Host "phpup_Apache   " -NoNewline
    if ($svcRegistered) {
        Write-Host "registered" -ForegroundColor Green
    }
    else {
        Write-Host "not registered" -ForegroundColor DarkGray
    }
    Write-Host "phpup_MariaDB  " -NoNewline
    if ($svcRegistered) {
        Write-Host "registered" -ForegroundColor Green
    }
    else {
        Write-Host "not registered" -ForegroundColor DarkGray
    }

    # ---- Info ----
    if ($stackComplete) {
        Write-Host ""
        Write-Host "Where to put website files?  " -NoNewline
        Write-Host $WWW_PATH -ForegroundColor Cyan
        Write-Host "How to test your PHP setup?  " -NoNewline
        Write-Host "http://localhost/phpinfo.php" -ForegroundColor Cyan
        Write-Host "Where to access phpMyAdmin?  " -NoNewline
        Write-Host "http://localhost/phpmyadmin" -ForegroundColor Cyan
        Write-Host "How to log into phpMyAdmin?  " -NoNewline
        Write-Host "Username: root | Password: [blank]" -ForegroundColor Cyan
        Write-Host "Where is the download cache? " -NoNewline
        Write-Host $DOWNLOAD_CACHE -ForegroundColor Cyan
    }

    # ---- Partial-stack recovery notice ----
    # A component went missing (failed fu apply, manual deletion, partial
    # install). Tell the user Install recovers it without touching the rest.
    if (-not $stackComplete -and (Test-PartialStack)) {
        Write-Host ""
        Write-Warn "A partial web stack was detected — one or more components are missing."
        Write-Info "  Install (I) will recover the missing components only."
        Write-Info "  Your websites, databases and settings are preserved."
    }

    # ---- Commands ----
    Write-Host ""
    Write-Host "Stack Commands:" -ForegroundColor White
    Write-Host "~~~~~~~~~~~~~~~"

    if (-not $stackComplete) {
        Write-Host "I  Install the web stack (recovers missing components)" -ForegroundColor Cyan
    }
    else {
        Write-Host "U  Update all components" -ForegroundColor Cyan
        Write-Host "R  Restart all services" -ForegroundColor Cyan
        Write-Host "S  Start / Stop services" -NoNewline -ForegroundColor Cyan
        if (-not (Test-ServicesInstalled)) {
            Write-Host " (add service registration)" -ForegroundColor DarkGray
        }
        else {
            Write-Host ""
        }
        Write-Host "D  Delete the web stack" -ForegroundColor Cyan
    }
    Write-Host "Q  Quit" -ForegroundColor Cyan
    Write-Host ""
}

# ============================================================
#  MAIN LOOP
# ============================================================

# ---- CLI dispatch ----------------------------------------------------
# Runs before the admin gate, the VC++ preflight and the dashboard, so verbs
# stay fast, prompt-free and elevation-agnostic. No $Command = unchanged.
if (-not [string]::IsNullOrWhiteSpace($Command)) {
    [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false
    $OutputEncoding = New-Object System.Text.UTF8Encoding $false
    $script:CliExitCode = 0
    Invoke-CliVerb -Verb $Command -Json:$Json -Fast:$Fast -Quiet:$Quiet -Watch $Watch
    exit $script:CliExitCode
}

# Ensure we're running as Admin
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")

if (-not $isAdmin) {
    Write-Host ""
    Write-Err "This script requires Administrator privileges."
    Write-Info "Please right-click PowerShell and select 'Run as Administrator',"
    Write-Info "then re-run this script."
    Write-Host ""
    Pause
    exit 1
}

# CPU architecture check.
# 32-bit Windows cannot run this stack at all — hard block.
if (-not [Environment]::Is64BitOperatingSystem) {
    Write-Err "A 64-bit version of Windows is required."
    exit 1
}

# ARM64 is not natively supported: Apache Lounge, PHP and MariaDB ship no
# ARM64 Windows binaries, so the x64 stack runs under Windows-on-ARM
# emulation (Prism). Warn and continue — it usually works, but it is
# untested territory and slower than native x64.
$cpu_arch = $env:PROCESSOR_ARCHITECTURE

if ($cpu_arch -ne 'AMD64') {
    Write-Host ""
    Write-Warn "Architecture: $cpu_arch — not natively supported."
    Write-Info "phpup's stack is x64-only (Apache Lounge, PHP, MariaDB ship no"
    Write-Info "native ARM64 Windows binaries). On ARM64 it runs under x64"
    Write-Info "emulation: expected to work, but untested and slower than x64."
    Write-Host ""
}

# ---- VC++ Redistributable: system prerequisite (BLOCKING) ----

while (-not (Test-VcRedistInstalled)) {
    Write-Warn "Visual C++ Redistributable (VS 2017-2026) x64 is required."
    Write-Info "  Minimum version: 14.51.36231"
    $vcVer = Get-VcRedistVersion
    if ($vcVer) {
        Write-Info "  Installed version: $vcVer (outdated -- update required)"
    }
    else {
        Write-Info "  Status: not installed"
    }
    Write-Info "  This is required by Apache Lounge VS18 and MariaDB 12.x."
    Write-Info "  Without it, Apache and MariaDB cannot start."
    Write-Host ""
    $choice = Read-Host "  Install/update now? [Y/n] (n = exit)"
    if ($choice -eq "" -or $choice -match "^[Yy]") {
        $vcBefore = Get-VcRedistVersion
        Install-VcRedist
        if (-not (Test-VcRedistInstalled)) {
            $vcAfter = Get-VcRedistVersion
            if ($vcAfter -eq $vcBefore) {
                # Installer succeeded but version didn't change — reboot required
                Write-Host ""
                Write-Warn "The installer completed but a reboot is required to finish the update."
                Write-Info "  The new VC++ files are queued for replacement on next boot."
                Write-Host ""
                $rebootChoice = Read-Host "  Reboot now? [Y/n] (n = exit)"
                if ($rebootChoice -eq "" -or $rebootChoice -match "^[Yy]") {
                    Write-Info "Rebooting..."
                    Restart-Computer -Force
                }
                else {
                    Write-Err "Cannot proceed without updated VC++ Redistributable. Exiting."
                    Write-Info "  Re-run this script after reboot."
                    Pause
                    exit 1
                }
            }
        }
    }
    else {
        Write-Host ""
        Write-Err "VC++ Redistributable is required. Exiting."
        Write-Host ""
        Pause
        exit 1
    }
}
Write-Host ""
Write-Ok "Visual C++ Redistributable — OK"

# ---- Install location (config-aware) -------------------------

$config = Get-Config

if ($config) {
    # Previous run detected — use saved path
    $BASE = $config.install_path
    Write-Host ""
    Write-Info "Stack location: $BASE"

    # Validate the saved path is usable
    if ($BASE -match '\s') {
        Write-Err "Saved path contains spaces — this is unsupported."
        Write-Info "Delete the config and re-run: Remove-Item '$(Get-ConfigFilePath)'"
        Write-Host ""
        Pause
        exit 1
    }
}
else {
    # First run — prompt for install location
    Write-Host ""
    Write-Host "========================================" -ForegroundColor Cyan
    Write-Host "  phpup Install Location" -ForegroundColor Cyan
    Write-Host "========================================" -ForegroundColor Cyan
    Write-Host ""
    Write-Info "Where should the web stack be installed?"
    Write-Info "Press Enter to accept the default, or type a custom path."
    Write-Host ""

    $userPath = Read-Host "Install path [C:\phpup]"

    if ([string]::IsNullOrWhiteSpace($userPath)) {
        $BASE = "C:\phpup"
    }
    else {
        # Strip trailing backslash if present
        $BASE = $userPath.TrimEnd('\')

        # Reject paths with spaces (can break mysqld --datadir)
        if ($BASE -match '\s') {
            Write-Err "Paths containing spaces are not supported (can cause issues with MariaDB)."
            Write-Info "Please use a path without spaces, e.g. C:\phpup"
            Write-Host ""
            Pause
            exit 1
        }
    }

    # Save for future runs so we skip this prompt next time
    Save-Config -InstallPath $BASE
    Write-Host ""
    Write-Ok "Web stack will be installed to: $BASE"
}

# Derive all paths from $BASE
Initialize-Paths

if (-not $config) {
    Write-Info "  Websites:  $WWW_PATH"
    Write-Info "  phpMyAdmin: http://localhost/phpmyadmin"
}


# ---- Sync config service state with reality ----
if ($config -and (Test-StackComplete)) {
    $actualRegistered = Test-ServicesInstalled
    $configRegistered  = if ($config.PSObject.Properties.Name -contains 'services_registered') {
        $config.services_registered
    } else {
        $false
    }
    if ($actualRegistered -ne $configRegistered) {
        Save-Config -InstallPath $BASE -ServicesRegistered:$actualRegistered -Versions $config.versions -PathEntries $config.path_entries
    }
}

while ($true) {
    Show-Dashboard

    $stackComplete = Test-StackComplete
    $cmd = Read-Host "==> Enter command"

    switch ($cmd.ToLower()) {
        "i" {
            if (-not $stackComplete) {
                Invoke-InstallWebStack
            }
            else {
                Write-Err "Stack is already installed. Use 'U' to update or 'D' to delete first."
            }
        }
        "u" {
            if ($stackComplete) { Invoke-UpdateWebStack }
            else { Write-Err "Stack not installed. Use 'I' to install." }
        }
        "r" {
            if ($stackComplete) {
                Stop-WebStackServices
                Start-Sleep -Seconds 2
                Start-WebStackServices
                Write-Ok "Services restarted"
            }
            else { Write-Err "Stack not installed." }
        }
        "s" {
            if ($stackComplete) {
                if ((Test-ApacheRunning) -or (Test-MariaDbRunning)) {
                    # Services are running — stop them
                    Stop-WebStackServices
                    if (Test-ServicesInstalled) {
                        $choice = Read-Host "Remove Windows service registration? [y/N]"
                        if ($choice -match "^[Yy]") {
                            Remove-Services
                            Save-Config -InstallPath $BASE -ServicesRegistered:$false -Versions $config.versions -PathEntries $config.path_entries
                            Write-Ok "Windows services removed"
                        }
                    }
                    else {
                        Write-Info "Not registered as Windows services — press S again to register"
                    }
                }
                else {
                    # Services are stopped — start them
                    if (-not (Test-ServicesInstalled)) {
                        Write-Host ""
                        Write-Warn "Services are not registered as Windows services."
                        Write-Info "  Without service registration, Apache and MariaDB won't auto-start on boot."
                        Write-Info "  You'll need to run this script and press 'S' after every reboot."
                        $choice = Read-Host "Register as Windows services now? [y/N]"
                        if ($choice -match "^[Yy]") {
                            Install-AsServices
                            Save-Config -InstallPath $BASE -ServicesRegistered:$true -Versions $config.versions -PathEntries $config.path_entries
                        }
                        else {
                            Start-WebStackServices
                        }
                    }
                    else {
                        Start-WebStackServices
                    }
                }
            }
            else { Write-Err "Stack not installed." }
        }
        "d" {
            if ($stackComplete) { Invoke-DeleteWebStack }
            else { Write-Err "Stack not installed." }
        }
        "q" {
            Write-Host ""
            Write-Ok "Goodbye!"
            Write-Host ""
            return
        }
        "fu" {
            if ($stackComplete) { Invoke-ForcedUpdate }
            else { Write-Err "Stack not installed. Use 'I' to install first." }
        }
        default {
            Write-Err "Command not recognised."
        }
    }

    Write-Host ""
    Pause
}