release.yml

name: MSUF
run-name: Publish ${{ inputs.tag_name || github.ref_name }}

on:
  push:
    tags:
      - "[0-9]*"
      - "v[0-9]*"
      - "MSUF_[0-9]*"
  workflow_dispatch:
    inputs:
      tag_name:
        description: Release tag to publish
        required: true
        type: string
      prerelease:
        description: Publish as alpha/beta on GitHub or CurseForge; Wago rejects prerelease tags
        required: true
        default: false
        type: boolean
      release_name:
        description: Display name for GitHub, Wago, and CurseForge
        required: false
        type: string
      publish_target:
        description: Publish destination
        required: true
        default: github
        type: choice
        options:
          - all
          - github
          - wago
          - curseforge
          - wago+curseforge

permissions:
  contents: write

jobs:
  build:
    if: github.repository == 'Mapkov2/MidnightSimpleUnitFrames'
    runs-on: ubuntu-latest
    env:
      RELEASE_VERSION: ${{ inputs.tag_name || github.ref_name }}
      RELEASE_IS_PRERELEASE: ${{ inputs.prerelease }}
      RELEASE_NAME_INPUT: ${{ inputs.release_name }}
      RELEASE_PUBLISH_TARGET_INPUT: ${{ inputs.publish_target }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ inputs.tag_name || github.ref_name }}
          fetch-depth: 0

      # A bulk `git push --tags` can surface forgotten local beta tags months
      # later. Prerelease tags are publishable only when they point at the
      # current main commit; stale alpha/beta/RC refs fail before any package or
      # external upload is created.
      - name: Reject stale prerelease tags
        shell: pwsh
        run: |
          function Test-PrereleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            $v = $value.Trim()
            return (
              ($v -match '(?i)(alpha|beta|rc|pre|preview)') -or
              ($v -match '(?i)\d+(?:\.\d+)*[AB]\d+(?:$|[^A-Za-z0-9])') -or
              ($v -match '(?i)(^|[^A-Za-z0-9])[AB]\d+(?:$|[^A-Za-z0-9])')
            )
          }

          $tag = $env:RELEASE_VERSION
          if (Test-PrereleaseSignal $tag) {
            git fetch --no-tags origin "+refs/heads/main:refs/remotes/origin/main"
            if ($LASTEXITCODE -ne 0) {
              throw "Could not resolve origin/main for prerelease freshness validation."
            }

            $tagCommit = (git rev-list -n 1 "refs/tags/$tag" 2>$null)
            if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($tagCommit)) {
              throw "Could not resolve prerelease tag '$tag' to a commit."
            }
            $mainCommit = (git rev-parse "refs/remotes/origin/main" 2>$null)
            if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($mainCommit)) {
              throw "Could not resolve origin/main to a commit."
            }

            $tagCommit = $tagCommit.Trim()
            $mainCommit = $mainCommit.Trim()
            if ($tagCommit -ne $mainCommit) {
              throw "Refusing stale prerelease tag '$tag' at $tagCommit; current origin/main is $mainCommit. Push only the intended current release tag, never 'git push --tags'."
            }
            Write-Host "Prerelease tag '$tag' is current at origin/main $mainCommit."
          }

      # Verification (static checks, core smokes, search-index check) is
      # local-only and deliberately absent from the repo, so this workflow
      # packages and publishes without re-running it. Run the suite on the
      # dev machine before tagging.

      - name: Resolve publish target
        id: publish
        shell: pwsh
        run: |
          $target = $env:RELEASE_PUBLISH_TARGET_INPUT
          $tag = $env:RELEASE_VERSION
          $tagContents = ""
          if (-not [string]::IsNullOrWhiteSpace($tag)) {
            $tagRef = "refs/tags/$tag"
            git fetch --force origin "$($tagRef):$($tagRef)" 2>$null
            if ($LASTEXITCODE -ne 0) {
              Write-Warning "Could not fetch tag annotation for '$tag'. Falling back to workflow input/default publish target."
            }
            $tagContentLines = @(git for-each-ref $tagRef --format='%(contents)' 2>$null)
            if ($LASTEXITCODE -ne 0) {
              $tagContents = ""
            } else {
              $tagContents = $tagContentLines -join [Environment]::NewLine
            }
          }
          # A manual dispatch is an explicit recovery/routing instruction and
          # takes precedence over the immutable release tag annotation.
          if ($env:GITHUB_EVENT_NAME -ne "workflow_dispatch" -and
              -not [string]::IsNullOrWhiteSpace($tagContents)) {
            $match = [regex]::Match($tagContents, '(?im)^\s*publish-target\s*:\s*(all|github|wago|curseforge|wago\+curseforge)\s*$')
            if ($match.Success) {
              $target = $match.Groups[1].Value
            }
          }

          # Fail closed: an unannotated tag may create a GitHub release, but it
          # must never upload to Wago or CurseForge implicitly.
          if ([string]::IsNullOrWhiteSpace($target)) {
            $target = "github"
          }
          $target = $target.Trim().ToLowerInvariant()
          if ($target -notin @("all", "github", "wago", "curseforge", "wago+curseforge")) {
            throw "Invalid publish target '$target'. Use all, github, wago, curseforge, or wago+curseforge."
          }

          $isPrereleaseTag = (
            ($tag -match '(?i)(alpha|beta|rc|pre|preview)') -or
            ($tag -match '(?i)\d+(?:\.\d+)*[AB]\d+(?:$|[^A-Za-z0-9])') -or
            ($tag -match '(?i)(^|[^A-Za-z0-9])[AB]\d+(?:$|[^A-Za-z0-9])')
          )
          if ($isPrereleaseTag -and $target -in @("all", "wago")) {
            throw "Wago prerelease publishing is disabled. Tag '$tag' must use publish-target: curseforge or publish-target: github."
          }

          $publishToGitHub = $target -eq "all" -or $target -eq "github"
          $publishToWago = $target -eq "all" -or $target -eq "wago" -or $target -eq "wago+curseforge"
          $publishToCurseForge = $target -eq "all" -or $target -eq "curseforge" -or $target -eq "wago+curseforge"

          "PUBLISH_TARGET=$target" >> $env:GITHUB_ENV
          "PUBLISH_TO_GITHUB=$($publishToGitHub.ToString().ToLowerInvariant())" >> $env:GITHUB_ENV
          "PUBLISH_TO_WAGO=$($publishToWago.ToString().ToLowerInvariant())" >> $env:GITHUB_ENV
          "PUBLISH_TO_CURSEFORGE=$($publishToCurseForge.ToString().ToLowerInvariant())" >> $env:GITHUB_ENV
          "target=$target" >> $env:GITHUB_OUTPUT
          "publish_to_github=$($publishToGitHub.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
          "publish_to_wago=$($publishToWago.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
          "publish_to_curseforge=$($publishToCurseForge.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
          Write-Host "Publish target: $target. GitHub=$publishToGitHub Wago=$publishToWago CurseForge=$publishToCurseForge."

      - name: Validate publishing config
        shell: pwsh
        env:
          WAGO_API_TOKEN: ${{ secrets.WAGO_API_TOKEN }}
          CF_API_KEY: ${{ secrets.CF_API_KEY || secrets.CURSEFORGE }}
        run: |
          $expectedRepository = "Mapkov2/MidnightSimpleUnitFrames"
          if ($env:GITHUB_REPOSITORY -ne $expectedRepository) {
            throw "Publishing is only allowed from '$expectedRepository'. Current repository is '$($env:GITHUB_REPOSITORY)'."
          }

          $missing = @()
          if ($env:PUBLISH_TO_WAGO -eq "true" -and [string]::IsNullOrWhiteSpace($env:WAGO_API_TOKEN)) {
            $missing += "secret WAGO_API_TOKEN"
          }
          if ($env:PUBLISH_TO_CURSEFORGE -eq "true" -and [string]::IsNullOrWhiteSpace($env:CF_API_KEY)) {
            $missing += "secret CF_API_KEY"
          }
          if ($missing.Count -gt 0) {
            throw "Missing release publishing config: $($missing -join ', ')"
          }

      - name: Resolve release channel
        id: channel
        shell: pwsh
        run: |
          function Test-AlphaReleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            $v = $value.Trim()
            return (
              ($v -match '(?i)alpha') -or
              ($v -match '(?i)\d+(?:\.\d+)*A\d+(?:$|[^A-Za-z0-9])') -or
              ($v -match '(?i)(^|[^A-Za-z0-9])A\d+(?:$|[^A-Za-z0-9])')
            )
          }

          function Test-BetaReleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            $v = $value.Trim()
            return (
              ($v -match '(?i)beta') -or
              ($v -match '(?i)\d+(?:\.\d+)*B\d+(?:$|[^A-Za-z0-9])') -or
              ($v -match '(?i)(^|[^A-Za-z0-9])B\d+(?:$|[^A-Za-z0-9])')
            )
          }

          function Test-PrereleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            return ((Test-AlphaReleaseSignal $value) -or (Test-BetaReleaseSignal $value) -or ($value.Trim() -match '(?i)(rc|pre|preview)'))
          }

          function Normalize-ReleaseInput([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return "" }
            $v = $value.Trim()
            $v = $v -replace '^refs/tags/', ''
            $v = $v -replace '(?i)^MSUF[\s._-]*', ''
            $v = $v -replace '^v(?=\d)', ''
            return $v
          }

          function Get-FileFirstLine([string]$path) {
            if (-not (Test-Path -LiteralPath $path)) { return "" }
            $line = Get-Content -LiteralPath $path | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -First 1
            if ($line) { return $line.Trim() }
            return ""
          }

          function Get-TocVersion([string]$path) {
            if (-not (Test-Path -LiteralPath $path)) { return "" }
            $content = Get-Content -LiteralPath $path -Raw
            $match = [regex]::Match($content, '(?m)^##\s+Version:\s*(.+?)\s*$')
            if ($match.Success) { return $match.Groups[1].Value.Trim() }
            return ""
          }

          function Convert-AlphaTagToReleaseName([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return "" }
            $v = Normalize-ReleaseInput $value
            if ($v -match '^(?<base>\d+(?:\.\d+)*)(?:[\s._-]*(?:alpha|a)[\s._-]*(?<number>\d+(?:\.\d+)*))\s*$') {
              $base = (($Matches["base"] -split '\.') | ForEach-Object { [int]$_ }) -join "."
              $number = (($Matches["number"] -split '\.') | ForEach-Object { [int]$_ }) -join "."
              return "MSUF_${base}A$number"
            }
            return ""
          }

          $tag = $env:RELEASE_VERSION
          $eventIsPrerelease = $env:RELEASE_IS_PRERELEASE -eq "true"
          $tagContents = ""
          $tagContentLines = @(git for-each-ref "refs/tags/$tag" --format='%(contents)' 2>$null)
          if ($LASTEXITCODE -eq 0) {
            $tagContents = $tagContentLines -join [Environment]::NewLine
          }
          $tagRequestsCurseForgeBeta = -not [string]::IsNullOrWhiteSpace($tagContents) -and
            [regex]::IsMatch($tagContents, '(?im)^\s*curseforge-channel\s*:\s*beta\s*$')
          $curseForgeGameVersion = ""
          if (-not [string]::IsNullOrWhiteSpace($tagContents)) {
            $gameVersionMatches = [regex]::Matches($tagContents, '(?im)^\s*curseforge-game-version\s*:\s*(\d+\.\d+\.\d+)\s*$')
            if ($gameVersionMatches.Count -gt 1) {
              throw "Release tag '$tag' declares curseforge-game-version more than once."
            }
            if ($gameVersionMatches.Count -eq 1) {
              $curseForgeGameVersion = $gameVersionMatches[0].Groups[1].Value
            }
          }
          $releaseName = $env:RELEASE_NAME_INPUT
          if ([string]::IsNullOrWhiteSpace($releaseName)) {
            $tagSubject = git for-each-ref "refs/tags/$tag" --format='%(contents:subject)' 2>$null
            if ($LASTEXITCODE -eq 0 -and -not [string]::IsNullOrWhiteSpace($tagSubject)) {
              $releaseName = $tagSubject.Trim()
            }
          }
          if ([string]::IsNullOrWhiteSpace($releaseName)) {
            $alphaReleaseName = Convert-AlphaTagToReleaseName $tag
            if (-not [string]::IsNullOrWhiteSpace($alphaReleaseName)) {
              $releaseName = $alphaReleaseName
            } else {
              $displayVersion = Normalize-ReleaseInput $tag
              if ($displayVersion -match '^(?<base>\d+(?:\.\d+)*)(?:[\s._-]*(?<channel>alpha|beta|rc|pre|a|b)[\s._-]*(?<number>\d+(?:\.\d+)*))?\s*$') {
                $base = (($Matches["base"] -split '\.') | ForEach-Object { [int]$_ }) -join "."
                if ([string]::IsNullOrWhiteSpace($Matches["channel"])) {
                  $displayVersion = $base
                } else {
                  $number = ""
                  if (-not [string]::IsNullOrWhiteSpace($Matches["number"])) {
                    $number = " " + ((($Matches["number"] -split '\.') | ForEach-Object { [int]$_ }) -join ".")
                  }
                  $channelKey = $Matches["channel"].ToLowerInvariant()
                  if ($channelKey -eq "a") { $channelKey = "alpha" }
                  if ($channelKey -eq "b") { $channelKey = "beta" }
                  $channel = (Get-Culture).TextInfo.ToTitleCase($channelKey) -replace '\bRc\b', 'RC'
                  $displayVersion = ($base + " " + $channel + $number).Trim()
                }
              } else {
                $displayVersion = $displayVersion -replace '(?i)[\-_]?beta[\-_.]?(\d+)', ' Beta $1'
                $displayVersion = $displayVersion -replace '(?i)[\-_]?alpha[\-_.]?(\d+)', ' Alpha $1'
                $displayVersion = $displayVersion -replace '(?i)[\-_]?rc[\-_.]?(\d+)', ' RC $1'
                $displayVersion = $displayVersion -replace '[-_]+', ' '
                $displayVersion = ($displayVersion -replace '\s+', ' ').Trim()
              }
              $releaseName = "MSUF $displayVersion"
            }
          }
          $releaseName = ($releaseName -replace '[\r\n]+', ' ').Trim()

          # CurseForge file labels follow the compact project convention and
          # must never inherit a descriptive annotated-tag subject. Stability
          # is carried separately by CF_RELEASE_TYPE.
          $curseForgeVersion = Normalize-ReleaseInput $tag
          if ($curseForgeVersion -notmatch '^[0-9][0-9A-Za-z._-]*$') {
            throw "Cannot derive a safe CurseForge display version from tag '$tag'."
          }
          $curseForgeDisplayName = "MSUF_$curseForgeVersion"

          $versionFileValue = Get-FileFirstLine "VERSION"
          $tocVersionValue = Get-TocVersion "MidnightSimpleUnitFrames/MidnightSimpleUnitFrames.toc"
          $releaseSignals = @($tag, $releaseName, $versionFileValue, $tocVersionValue)
          $hasAlphaSignal = @($releaseSignals | Where-Object { Test-AlphaReleaseSignal $_ } | Select-Object -First 1).Count -gt 0
          $hasPrereleaseSignal = @($releaseSignals | Where-Object { Test-PrereleaseSignal $_ } | Select-Object -First 1).Count -gt 0
          $isPrerelease = $eventIsPrerelease -or $hasPrereleaseSignal

          if ($hasAlphaSignal) {
            $wagoStability = "alpha"
            $curseForgeType = "alpha"
          } elseif ($isPrerelease) {
            $wagoStability = "beta"
            $curseForgeType = "beta"
          } else {
            $wagoStability = "stable"
            $curseForgeType = if ($tagRequestsCurseForgeBeta) { "beta" } else { "release" }
          }

          "RELEASE_IS_PRERELEASE=$($isPrerelease.ToString().ToLowerInvariant())" >> $env:GITHUB_ENV
          "WAGO_STABILITY=$wagoStability" >> $env:GITHUB_ENV
          "CF_RELEASE_TYPE=$curseForgeType" >> $env:GITHUB_ENV
          "RELEASE_NAME=$releaseName" >> $env:GITHUB_ENV
          "CURSEFORGE_DISPLAY_NAME=$curseForgeDisplayName" >> $env:GITHUB_ENV
          "CURSEFORGE_GAME_VERSION=$curseForgeGameVersion" >> $env:GITHUB_ENV
          "release_is_prerelease=$($isPrerelease.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
          "github_make_latest=$(if ($isPrerelease) { 'false' } else { 'true' })" >> $env:GITHUB_OUTPUT
          "release_name=$releaseName" >> $env:GITHUB_OUTPUT
          "curseforge_display_name=$curseForgeDisplayName" >> $env:GITHUB_OUTPUT
          $curseForgeGameVersionLabel = if ($curseForgeGameVersion) { $curseForgeGameVersion } else { "highest declared TOC interface" }
          Write-Host "Release $tag uses name '$releaseName', CurseForge name '$curseForgeDisplayName', Wago stability '$wagoStability', CurseForge type '$curseForgeType', and CurseForge game version '$curseForgeGameVersionLabel' (CurseForge beta override=$tagRequestsCurseForgeBeta)."

      - name: Enforce prerelease channels for prerelease tags
        shell: pwsh
        run: |
          function Test-AlphaReleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            $v = $value.Trim()
            return (
              ($v -match '(?i)alpha') -or
              ($v -match '(?i)\d+(?:\.\d+)*A\d+(?:$|[^A-Za-z0-9])') -or
              ($v -match '(?i)(^|[^A-Za-z0-9])A\d+(?:$|[^A-Za-z0-9])')
            )
          }

          function Test-BetaReleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            $v = $value.Trim()
            return (
              ($v -match '(?i)beta') -or
              ($v -match '(?i)\d+(?:\.\d+)*B\d+(?:$|[^A-Za-z0-9])') -or
              ($v -match '(?i)(^|[^A-Za-z0-9])B\d+(?:$|[^A-Za-z0-9])')
            )
          }

          function Test-PrereleaseSignal([AllowNull()][string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return $false }
            return ((Test-AlphaReleaseSignal $value) -or (Test-BetaReleaseSignal $value) -or ($value.Trim() -match '(?i)(rc|pre|preview)'))
          }

          function Get-FileFirstLine([string]$path) {
            if (-not (Test-Path -LiteralPath $path)) { return "" }
            $line = Get-Content -LiteralPath $path | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -First 1
            if ($line) { return $line.Trim() }
            return ""
          }

          function Get-TocVersion([string]$path) {
            if (-not (Test-Path -LiteralPath $path)) { return "" }
            $content = Get-Content -LiteralPath $path -Raw
            $match = [regex]::Match($content, '(?m)^##\s+Version:\s*(.+?)\s*$')
            if ($match.Success) { return $match.Groups[1].Value.Trim() }
            return ""
          }

          $alphaSignals = @(
            $env:RELEASE_VERSION,
            $env:RELEASE_NAME,
            (Get-FileFirstLine "VERSION"),
            (Get-TocVersion "MidnightSimpleUnitFrames/MidnightSimpleUnitFrames.toc")
          ) | Where-Object { Test-AlphaReleaseSignal $_ }

          $prereleaseSignals = @(
            $env:RELEASE_VERSION,
            $env:RELEASE_NAME,
            (Get-FileFirstLine "VERSION"),
            (Get-TocVersion "MidnightSimpleUnitFrames/MidnightSimpleUnitFrames.toc")
          ) | Where-Object { Test-PrereleaseSignal $_ }

          if ($alphaSignals) {
            if ($env:WAGO_STABILITY -ne "alpha" -or $env:CF_RELEASE_TYPE -ne "alpha") {
              throw "Alpha signal '$($alphaSignals[0])' must publish as alpha. Got Wago '$env:WAGO_STABILITY' and CurseForge '$env:CF_RELEASE_TYPE'."
            }
          }
          if ($prereleaseSignals) {
            if ($env:WAGO_STABILITY -eq "stable" -or $env:CF_RELEASE_TYPE -eq "release") {
              throw "Prerelease signal '$($prereleaseSignals[0])' must not publish as stable/release. Got Wago '$env:WAGO_STABILITY' and CurseForge '$env:CF_RELEASE_TYPE'."
            }
            if ($env:PUBLISH_TO_WAGO -eq "true") {
              throw "Wago prerelease publishing is disabled. Refusing '$($prereleaseSignals[0])'."
            }
          }

      # The authoritative Assistant release gate is part of the local-only
      # verification suite and no longer runs here. Run it on the dev machine
      # before tagging a stable release, where the Assistant is promised to be
      # complete.

      - name: Build AddOns zip
        shell: pwsh
        run: |
          # Fail-closed helper stages MidnightSimpleUnitFrames plus MidnightSimpleUnitFrames_Assistant.
          & "./.github/scripts/build_release_package.ps1" -ReleaseVersion $env:RELEASE_VERSION -OutputDirectory "dist"

      - name: Write GitHub release notes
        shell: pwsh
        run: |
          function Normalize-Key([string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return "" }
            $v = $value.Trim()
            $v = $v -replace '^refs/tags/', ''
            $v = $v -replace '(?i)^MSUF[\s._-]*', ''
            $v = $v -replace '^v(?=\d)', ''
            if ($v -match '^(?<base>\d+(?:\.\d+)*)(?:[\s._-]*(?<channel>alpha|beta|rc|pre|a|b)[\s._-]*(?<number>\d+(?:\.\d+)*))?\s*$') {
              $base = (($Matches["base"] -split '\.') | ForEach-Object { [int]$_ }) -join "x"
              if ([string]::IsNullOrWhiteSpace($Matches["channel"])) { return $base }
              $channel = $Matches["channel"].ToLowerInvariant()
              if ($channel -eq "a") { $channel = "alpha" }
              if ($channel -eq "b") { $channel = "beta" }
              $number = ""
              if (-not [string]::IsNullOrWhiteSpace($Matches["number"])) {
                $number = (($Matches["number"] -split '\.') | ForEach-Object { [int]$_ }) -join "x"
              }
              return ($base + $channel + $number)
            }
            return (($v.ToLowerInvariant()) -replace '[^a-z0-9]+', '')
          }

          function Get-PrereleaseFallbackKey([string]$value) {
            if ([string]::IsNullOrWhiteSpace($value)) { return "" }
            $v = $value.Trim()
            $v = $v -replace '^refs/tags/', ''
            $v = $v -replace '(?i)^MSUF[\s._-]*', ''
            $v = $v -replace '^v(?=\d)', ''
            if ($v -match '^(?<base>\d+(?:\.\d+)*)(?:[\s._-]*(?<channel>alpha|beta|rc|pre|a|b)[\s._-]*(?<number>\d+)\.\d+(?:\.\d+)*)\s*$') {
              $base = (($Matches["base"] -split '\.') | ForEach-Object { [int]$_ }) -join "."
              $channel = $Matches["channel"].ToLowerInvariant()
              if ($channel -eq "a") { $channel = "alpha" }
              if ($channel -eq "b") { $channel = "beta" }
              return Normalize-Key ($base + " " + $channel + " " + $Matches["number"])
            }
            return ""
          }

          function Convert-TagToDisplay([string]$tag) {
            $display = $tag -replace '^refs/tags/', ''
            $display = $display -replace '(?i)^MSUF[\s._-]*', ''
            $display = $display -replace '^v(?=\d)', ''
            if ($display -match '^(?<base>\d+(?:\.\d+)*)(?:[\s._-]*(?<channel>alpha|beta|rc|pre|a|b)[\s._-]*(?<number>\d+(?:\.\d+)*))?\s*$') {
              $base = (($Matches["base"] -split '\.') | ForEach-Object { [int]$_ }) -join "."
              if ([string]::IsNullOrWhiteSpace($Matches["channel"])) { return $base }
              $number = ""
              if (-not [string]::IsNullOrWhiteSpace($Matches["number"])) {
                $number = " " + ((($Matches["number"] -split '\.') | ForEach-Object { [int]$_ }) -join ".")
              }
              $channelKey = $Matches["channel"].ToLowerInvariant()
              if ($channelKey -eq "a") { $channelKey = "alpha" }
              if ($channelKey -eq "b") { $channelKey = "beta" }
              $channel = (Get-Culture).TextInfo.ToTitleCase($channelKey) -replace '\bRc\b', 'RC'
              return ($base + " " + $channel + $number).Trim()
            }
            $display = $display -replace '(?i)[\-_]?beta[\-_.]?(\d+)', ' Beta $1'
            $display = $display -replace '(?i)[\-_]?alpha[\-_.]?(\d+)', ' Alpha $1'
            $display = $display -replace '(?i)[\-_]?rc[\-_.]?(\d+)', ' RC $1'
            $display = $display -replace '(?i)[\-_]?pre[\-_.]?(\d+)', ' Pre $1'
            $display = $display -replace '[-_]+', ' '
            return (($display -replace '\s+', ' ').Trim())
          }

          $tag = $env:RELEASE_VERSION
          $display = Convert-TagToDisplay $tag
          $wanted = @(
            (Normalize-Key $tag),
            (Normalize-Key $display),
            (Get-PrereleaseFallbackKey $tag),
            (Get-PrereleaseFallbackKey $display)
          ) | Where-Object { $_ } | Select-Object -Unique
          # Distribution pages always receive only this version's patch notes.
          # The long-form migration/archive document is never a publish source.
          $lines = [regex]::Split((Get-Content -LiteralPath "CHANGELOG.md" -Raw), "\r?\n")
          $start = -1
          $end = $lines.Count

          for ($i = 0; $i -lt $lines.Count; $i++) {
            if ($lines[$i] -match '^##\s+(.+?)(?:\s+-\s+\d{4}-\d{2}-\d{2})?\s*$') {
              if ($wanted -contains (Normalize-Key $Matches[1])) {
                $start = $i
                for ($j = $i + 1; $j -lt $lines.Count; $j++) {
                  if ($lines[$j] -match '^##\s+') {
                    $end = $j
                    break
                  }
                }
                break
              }
            }
          }

          if ($start -lt 0) {
            throw "Could not find CHANGELOG.md section for release '$tag' ('$display')."
          }

          # msuf-menu-link comments are private metadata for the interactive
          # in-game changelog. Discord and distribution sites do not all honor
          # HTML comments, so never include them in public release notes.
          $notes = [string[]]@($lines[$start..($end - 1)] | Where-Object {
            $_ -notmatch '^\s*<!--\s*msuf-menu-link:\s*(?:\{.*\}|none)\s*-->\s*$'
          })

          function Close-List {
            if ($script:InList) {
              $script:HtmlLines += "</ul>"
              $script:InList = $false
            }
          }

          function Add-HtmlLine([string]$line) {
            $trimmed = $line.Trim()
            if ($trimmed -match '^<!--\s*msuf-menu-link:') {
              return
            }
            if ([string]::IsNullOrWhiteSpace($trimmed)) {
              Close-List
              return
            }

            if ($trimmed -match '^#\s+(.+?)\s*$') {
              Close-List
              $script:HtmlLines += ("<h1>" + [System.Net.WebUtility]::HtmlEncode($Matches[1].Trim()) + "</h1>")
              return
            }

            if ($trimmed -match '^###\s+(.+?)\s*$') {
              Close-List
              $script:HtmlLines += ("<h3>" + [System.Net.WebUtility]::HtmlEncode($Matches[1].Trim()) + "</h3>")
              return
            }

            if ($trimmed -match '^##\s+(.+?)(?:\s+-\s+(\d{4}-\d{2}-\d{2}))?\s*$') {
              Close-List
              $title = [System.Net.WebUtility]::HtmlEncode($Matches[1].Trim())
              if ($Matches.ContainsKey(2) -and -not [string]::IsNullOrWhiteSpace($Matches[2])) {
                $title += " - " + [System.Net.WebUtility]::HtmlEncode($Matches[2].Trim())
              }
              $script:HtmlLines += ("<h2>" + $title + "</h2>")
              return
            }

            if ($trimmed -match '^\-\s+(.+?)\s*$') {
              if (-not $script:InList) {
                $script:HtmlLines += "<ul>"
                $script:InList = $true
              }
              $script:HtmlLines += ("<li>" + [System.Net.WebUtility]::HtmlEncode($Matches[1].Trim()) + "</li>")
              return
            }

            Close-List
            $script:HtmlLines += ("<p>" + [System.Net.WebUtility]::HtmlEncode($trimmed) + "</p>")
          }

          New-Item -ItemType Directory -Force -Path "dist" | Out-Null
          [System.IO.File]::WriteAllText("dist/RELEASE_NOTES.md", (($notes -join [Environment]::NewLine).TrimEnd() + [Environment]::NewLine), [System.Text.UTF8Encoding]::new($false))

          $script:HtmlLines = @()
          $script:InList = $false
          foreach ($line in $notes) {
            Add-HtmlLine $line
          }
          Close-List
          [System.IO.File]::WriteAllText("dist/RELEASE_NOTES_CF.html", (($script:HtmlLines -join [Environment]::NewLine).TrimEnd() + [Environment]::NewLine), [System.Text.UTF8Encoding]::new($false))

      - name: Upload to GitHub Release
        if: steps.publish.outputs.publish_to_github == 'true'
        uses: softprops/action-gh-release@v3
        with:
          tag_name: ${{ env.RELEASE_VERSION }}
          name: ${{ steps.channel.outputs.release_name }}
          files: dist/*.zip
          body_path: dist/RELEASE_NOTES.md
          fail_on_unmatched_files: true
          overwrite_files: true
          prerelease: ${{ steps.channel.outputs.release_is_prerelease }}
          make_latest: ${{ steps.channel.outputs.github_make_latest }}

      # Wago runs only for an explicit stable `publish-target: wago|all|wago+curseforge` tag
      # annotation or workflow_dispatch target. Alpha, beta, RC, pre and preview
      # builds are rejected before packaging and again inside this upload step.
      - name: Upload to Wago
        if: steps.publish.outputs.publish_to_wago == 'true'
        shell: pwsh
        env:
          WAGO_API_TOKEN: ${{ secrets.WAGO_API_TOKEN }}
        run: |
          function Get-TocField {
            param(
              [Parameter(Mandatory = $true)][string]$Content,
              [Parameter(Mandatory = $true)][string]$Name
            )

            $match = [regex]::Match($Content, "(?m)^##\s+$([regex]::Escape($Name)):\s*(.+?)\s*$")
            if ($match.Success) {
              return $match.Groups[1].Value.Trim()
            }

            return $null
          }

          function Convert-RetailInterfaceToPatch {
            param([Parameter(Mandatory = $true)][int]$Interface)

            if ($Interface -lt 100000) {
              throw "Retail interface value must be six digits. Got: $Interface"
            }

            $major = [math]::Floor($Interface / 10000)
            $minor = [math]::Floor(($Interface % 10000) / 100)
            $patch = $Interface % 100
            return "$major.$minor.$patch"
          }

          $zip = Get-ChildItem -Path dist -Filter "*.zip" | Select-Object -First 1
          if (-not $zip) {
            throw "No release zip found in dist."
          }

          if ([string]::IsNullOrWhiteSpace($env:WAGO_API_TOKEN)) {
            throw "WAGO_API_TOKEN is missing."
          }

          if ($env:WAGO_STABILITY -notin @("stable", "beta", "alpha")) {
            throw "Invalid Wago stability '$env:WAGO_STABILITY'."
          }

          # Second lock: Wago must always be an explicit publish destination.
          if ($env:PUBLISH_TARGET -notin @("all", "wago", "wago+curseforge")) {
            throw "Refusing Wago upload for publish target '$env:PUBLISH_TARGET'."
          }

          $tocContent = Get-Content -LiteralPath "MidnightSimpleUnitFrames/MidnightSimpleUnitFrames.toc" -Raw
          $projectId = Get-TocField -Content $tocContent -Name "X-Wago-ID"
          if ([string]::IsNullOrWhiteSpace($projectId)) {
            throw "No Wago project id found in TOC."
          }

          $tocVersion = Get-TocField -Content $tocContent -Name "Version"
          $versionFileValue = ""
          if (Test-Path -LiteralPath "VERSION") {
            $versionFileValue = Get-Content -LiteralPath "VERSION" | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -First 1
          }
          $alphaSignals = @($env:RELEASE_VERSION, $env:RELEASE_NAME, $versionFileValue, $tocVersion) | Where-Object {
            if ([string]::IsNullOrWhiteSpace($_)) {
              $false
            } else {
              $v = $_.Trim()
              (
                ($v -match '(?i)alpha') -or
                ($v -match '(?i)\d+(?:\.\d+)*A\d+(?:$|[^A-Za-z0-9])') -or
                ($v -match '(?i)(^|[^A-Za-z0-9])A\d+(?:$|[^A-Za-z0-9])')
              )
            }
          }
          if ($alphaSignals -and $env:WAGO_STABILITY -ne "alpha") {
            throw "Alpha signal '$($alphaSignals[0])' must upload to Wago as alpha. Got '$env:WAGO_STABILITY'."
          }

          $prereleaseSignals = @($env:RELEASE_VERSION, $env:RELEASE_NAME, $versionFileValue, $tocVersion) | Where-Object {
            if ([string]::IsNullOrWhiteSpace($_)) {
              $false
            } else {
              $v = $_.Trim()
              (
                ($v -match '(?i)(alpha|beta|rc|pre|preview)') -or
                ($v -match '(?i)\d+(?:\.\d+)*[AB]\d+(?:$|[^A-Za-z0-9])') -or
                ($v -match '(?i)(^|[^A-Za-z0-9])[AB]\d+(?:$|[^A-Za-z0-9])')
              )
            }
          }
          if ($prereleaseSignals -and $env:WAGO_STABILITY -eq "stable") {
            throw "Prerelease signal '$($prereleaseSignals[0])' must not upload to Wago as stable."
          }
          if ($prereleaseSignals) {
            throw "Wago prerelease publishing is disabled. Refusing '$($prereleaseSignals[0])'."
          }

          $releaseNotesPath = "dist/RELEASE_NOTES.md"
          if (-not (Test-Path -LiteralPath $releaseNotesPath)) {
            throw "Current release notes are missing: $releaseNotesPath"
          }

          $interfaceField = Get-TocField -Content $tocContent -Name "Interface"
          $interfaces = $interfaceField -split ',' |
            ForEach-Object { $_.Trim() } |
            Where-Object { $_ -match '^\d+$' } |
            ForEach-Object { [int]$_ }
          if (-not $interfaces) {
            throw "No numeric retail interface found in TOC."
          }

          $retailPatch = Convert-RetailInterfaceToPatch -Interface (($interfaces | Measure-Object -Maximum).Maximum)
          $metadata = [ordered]@{
            label = $env:RELEASE_NAME
            stability = $env:WAGO_STABILITY
            changelog = Get-Content -LiteralPath $releaseNotesPath -Raw
            supported_retail_patch = $retailPatch
          } | ConvertTo-Json -Depth 5 -Compress

          $headers = @{
            Authorization = "Bearer $env:WAGO_API_TOKEN"
            Accept = "application/json"
          }
          $form = @{
            metadata = $metadata
            file = Get-Item -LiteralPath $zip.FullName
          }
          Invoke-RestMethod -Method Post -Uri "https://addons.wago.io/api/projects/$projectId/version" -Headers $headers -Form $form | Out-Null
          Write-Host "Uploaded $($zip.FullName) to Wago project $projectId as $env:RELEASE_NAME / $env:RELEASE_VERSION ($env:WAGO_STABILITY, retail $retailPatch)."

      - name: Upload to CurseForge
        if: steps.publish.outputs.publish_to_curseforge == 'true'
        shell: pwsh
        env:
          CF_API_KEY: ${{ secrets.CF_API_KEY || secrets.CURSEFORGE }}
        run: |
          function Get-TocField {
            param(
              [Parameter(Mandatory = $true)][string]$Content,
              [Parameter(Mandatory = $true)][string]$Name
            )

            $match = [regex]::Match($Content, "(?m)^##\s+$([regex]::Escape($Name)):\s*(.+?)\s*$")
            if ($match.Success) {
              return $match.Groups[1].Value.Trim()
            }

            return $null
          }

          function Convert-RetailInterfaceToPatch {
            param([Parameter(Mandatory = $true)][int]$Interface)

            if ($Interface -lt 100000) {
              throw "Retail interface value must be six digits. Got: $Interface"
            }

            $major = [math]::Floor($Interface / 10000)
            $minor = [math]::Floor(($Interface % 10000) / 100)
            $patch = $Interface % 100
            return "$major.$minor.$patch"
          }

          $zip = Get-ChildItem -Path dist -Filter "*.zip" | Select-Object -First 1
          if (-not $zip) {
            throw "No release zip found in dist."
          }

          if ([string]::IsNullOrWhiteSpace($env:CF_API_KEY)) {
            throw "CF_API_KEY is missing."
          }

          if ($env:CF_RELEASE_TYPE -notin @("release", "beta", "alpha")) {
            throw "Invalid CurseForge release type '$env:CF_RELEASE_TYPE'."
          }

          $tocContent = Get-Content -LiteralPath "MidnightSimpleUnitFrames/MidnightSimpleUnitFrames.toc" -Raw
          $projectId = Get-TocField -Content $tocContent -Name "X-Curse-Project-ID"
          if ([string]::IsNullOrWhiteSpace($projectId)) {
            throw "No CurseForge project id found in TOC."
          }

          $interfaceField = Get-TocField -Content $tocContent -Name "Interface"
          $interfaces = $interfaceField -split ',' |
            ForEach-Object { $_.Trim() } |
            Where-Object { $_ -match '^\d+$' } |
            ForEach-Object { [int]$_ }
          if (-not $interfaces) {
            throw "No numeric retail interface found in TOC."
          }
          $declaredRetailPatches = @($interfaces | ForEach-Object { Convert-RetailInterfaceToPatch -Interface $_ })
          $retailPatch = Convert-RetailInterfaceToPatch -Interface (($interfaces | Measure-Object -Maximum).Maximum)
          if (-not [string]::IsNullOrWhiteSpace($env:CURSEFORGE_GAME_VERSION)) {
            $requestedRetailPatch = $env:CURSEFORGE_GAME_VERSION.Trim()
            if ($requestedRetailPatch -notin $declaredRetailPatches) {
              throw "CurseForge game version '$requestedRetailPatch' is absent from the declared TOC interfaces [$($declaredRetailPatches -join ', ')]."
            }
            $retailPatch = $requestedRetailPatch
          }

          $changelogPath = "dist/RELEASE_NOTES_CF.html"
          $changelogType = "html"
          if (-not (Test-Path -LiteralPath $changelogPath)) {
            $changelogPath = "dist/RELEASE_NOTES.md"
            $changelogType = "markdown"
          }

          $metadata = [ordered]@{
            changelog = Get-Content -LiteralPath $changelogPath -Raw
            changelogType = $changelogType
            displayName = $env:CURSEFORGE_DISPLAY_NAME
            gameVersionNames = @($retailPatch)
            releaseType = $env:CF_RELEASE_TYPE
          } | ConvertTo-Json -Depth 5 -Compress

          $headers = @{
            "X-Api-Token" = $env:CF_API_KEY
            Accept = "application/json"
          }
          $form = @{
            metadata = $metadata
            file = Get-Item -LiteralPath $zip.FullName
          }
          $result = Invoke-RestMethod -Method Post -Uri "https://wow.curseforge.com/api/projects/$projectId/upload-file" -Headers $headers -Form $form
          $fileId = if ($result -and $result.id) { $result.id } else { "(unknown file id)" }
          Write-Host "Uploaded $($zip.FullName) to CurseForge project $projectId as $env:CURSEFORGE_DISPLAY_NAME / $env:RELEASE_VERSION ($env:CF_RELEASE_TYPE, retail $retailPatch, file $fileId)."