release.yml

name: release

on:
  push:
    tags:
      - v*
  workflow_dispatch:
    inputs:
      tag:
        description: Release tag to publish, for example v1.0.0
        required: true
        type: string
      ref:
        description: Git ref to build for a manual release
        required: false
        default: master
        type: string

concurrency:
  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
  cancel-in-progress: false

permissions:
  contents: write

env:
  CONFIGURATION: Release
  DOTNET_NOLOGO: true
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
  DOTNET_CLI_TELEMETRY_OPTOUT: 1
  NUGET_SOURCE: https://api.nuget.org/v3/index.json
  RELEASE_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.ref }}
  RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
  SOLUTION_FILE: StemCode.CrossPlatform.slnx

jobs:
  validate:
    name: Validate release build
    runs-on: ubuntu-24.04
    outputs:
      release_version: ${{ steps.release_version.outputs.release_version }}

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
          cache: true
          cache-dependency-path: |
            StemCode/packages.lock.json
            StemCode.CLI/packages.lock.json
            StemCode.Desktop/packages.lock.json
            StemCode.Tests/packages.lock.json
            StemCode.Voice/packages.lock.json

      - name: Restore
        run: dotnet restore ${{ env.SOLUTION_FILE }} --locked-mode

      - name: Resolve release version
        id: release_version
        shell: bash
        run: |
          set -euo pipefail

          version="${RELEASE_TAG#v}"
          version="${version#V}"

          if [[ -z "$version" ]]; then
            echo "Release tag '$RELEASE_TAG' did not contain a version." >&2
            exit 1
          fi

          if [[ ! "$version" =~ ^[0-9]+(\.[0-9]+){1,3}(-[0-9A-Za-z][0-9A-Za-z.-]*)?(\+[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]; then
            echo "Release tag '$RELEASE_TAG' is not a valid .NET version after removing the v/V prefix." >&2
            exit 1
          fi

          echo "release_version=$version" >> "$GITHUB_OUTPUT"

      - name: Build
        run: >
          dotnet build ${{ env.SOLUTION_FILE }}
          --configuration ${{ env.CONFIGURATION }}
          --no-restore
          /p:Version=${{ steps.release_version.outputs.release_version }}
          /p:InformationalVersion=${{ env.RELEASE_TAG }}

      - name: Test
        run: >
          dotnet test ${{ env.SOLUTION_FILE }}
          --configuration ${{ env.CONFIGURATION }}
          --no-restore
          /p:Version=${{ steps.release_version.outputs.release_version }}
          /p:InformationalVersion=${{ env.RELEASE_TAG }}
          --logger "trx;LogFileName=release-test-results.trx"
          --results-directory ./artifacts/test-results

      - name: Upload validation test results
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: release-test-results
          path: artifacts/test-results
          if-no-files-found: warn
          retention-days: 14

  pack-nuget:
    name: Pack StemCode NuGet package
    needs: validate
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    env:
      RELEASE_VERSION: ${{ needs.validate.outputs.release_version }}

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
          cache: true
          cache-dependency-path: |
            StemCode/packages.lock.json
            StemCode.CLI/packages.lock.json
            StemCode.Desktop/packages.lock.json
            StemCode.Tests/packages.lock.json
            StemCode.Voice/packages.lock.json

      - name: Restore
        run: dotnet restore ${{ env.SOLUTION_FILE }} --locked-mode

      - name: Pack StemCode NuGet package
        run: |
          dotnet pack StemCode/StemCode.csproj \
            --configuration ${{ env.CONFIGURATION }} \
            --no-restore \
            --output ./artifacts/packages/nuget \
            /p:Version=${{ env.RELEASE_VERSION }} \
            /p:InformationalVersion=${{ env.RELEASE_TAG }}

      - name: Upload StemCode NuGet package
        uses: actions/upload-artifact@v6
        with:
          name: nuget-packages
          path: |
            ./artifacts/packages/nuget/StemCode.*.nupkg
            ./artifacts/packages/nuget/StemCode.*.snupkg
          if-no-files-found: error
          retention-days: 14

  publish:
    name: Publish ${{ matrix.display_name }} ${{ matrix.rid }}
    needs: validate
    runs-on: ${{ matrix.runner }}
    env:
      RELEASE_VERSION: ${{ needs.validate.outputs.release_version }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - display_name: CLI
            app_id: cli
            package_name: StemCode.CLI
            project: StemCode.CLI/StemCode.CLI.csproj
            runner: windows-2025
            rid: win-x64
            artifact_name: cli-win-x64

          - display_name: CLI
            app_id: cli
            package_name: StemCode.CLI
            project: StemCode.CLI/StemCode.CLI.csproj
            runner: ubuntu-24.04
            rid: linux-x64
            artifact_name: cli-linux-x64

          - display_name: CLI
            app_id: cli
            package_name: StemCode.CLI
            project: StemCode.CLI/StemCode.CLI.csproj
            runner: ubuntu-24.04-arm
            rid: linux-arm64
            artifact_name: cli-linux-arm64

          - display_name: CLI
            app_id: cli
            package_name: StemCode.CLI
            project: StemCode.CLI/StemCode.CLI.csproj
            runner: macos-15-intel
            rid: osx-x64
            artifact_name: cli-osx-x64

          - display_name: CLI
            app_id: cli
            package_name: StemCode.CLI
            project: StemCode.CLI/StemCode.CLI.csproj
            runner: macos-15
            rid: osx-arm64
            artifact_name: cli-osx-arm64

          - display_name: Desktop
            app_id: desktop
            package_name: StemCode.Desktop
            project: StemCode.Desktop/StemCode.Desktop.csproj
            runner: windows-2025
            rid: win-x64
            artifact_name: desktop-win-x64

          - display_name: Desktop
            app_id: desktop
            package_name: StemCode.Desktop
            project: StemCode.Desktop/StemCode.Desktop.csproj
            runner: ubuntu-24.04
            rid: linux-x64
            artifact_name: desktop-linux-x64

          - display_name: Desktop
            app_id: desktop
            package_name: StemCode.Desktop
            project: StemCode.Desktop/StemCode.Desktop.csproj
            runner: ubuntu-24.04-arm
            rid: linux-arm64
            artifact_name: desktop-linux-arm64

          - display_name: Desktop
            app_id: desktop
            package_name: StemCode.Desktop
            project: StemCode.Desktop/StemCode.Desktop.csproj
            runner: macos-15-intel
            rid: osx-x64
            artifact_name: desktop-osx-x64

          - display_name: Desktop
            app_id: desktop
            package_name: StemCode.Desktop
            project: StemCode.Desktop/StemCode.Desktop.csproj
            runner: macos-15
            rid: osx-arm64
            artifact_name: desktop-osx-arm64

          - display_name: Voice
            app_id: voice
            package_name: StemCode.Voice
            project: StemCode.Voice/StemCode.Voice.csproj
            runner: windows-2025
            rid: win-x64
            artifact_name: voice-win-x64

          - display_name: Voice
            app_id: voice
            package_name: StemCode.Voice
            project: StemCode.Voice/StemCode.Voice.csproj
            runner: ubuntu-24.04
            rid: linux-x64
            artifact_name: voice-linux-x64

          - display_name: Voice
            app_id: voice
            package_name: StemCode.Voice
            project: StemCode.Voice/StemCode.Voice.csproj
            runner: ubuntu-24.04-arm
            rid: linux-arm64
            artifact_name: voice-linux-arm64

          - display_name: Voice
            app_id: voice
            package_name: StemCode.Voice
            project: StemCode.Voice/StemCode.Voice.csproj
            runner: macos-15-intel
            rid: osx-x64
            artifact_name: voice-osx-x64

          - display_name: Voice
            app_id: voice
            package_name: StemCode.Voice
            project: StemCode.Voice/StemCode.Voice.csproj
            runner: macos-15
            rid: osx-arm64
            artifact_name: voice-osx-arm64

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
          cache: true
          cache-dependency-path: |
            StemCode/packages.lock.json
            StemCode.CLI/packages.lock.json
            StemCode.Desktop/packages.lock.json
            StemCode.Tests/packages.lock.json
            StemCode.Voice/packages.lock.json

      - name: Prepare artifact directories
        shell: pwsh
        run: |
          New-Item -ItemType Directory -Force -Path `
            "$env:GITHUB_WORKSPACE/artifacts/publish/${{ matrix.app_id }}", `
            "$env:GITHUB_WORKSPACE/artifacts/packages" | Out-Null

      - name: Publish ${{ matrix.display_name }} app
        run: >
          dotnet publish ${{ matrix.project }}
          --configuration ${{ env.CONFIGURATION }}
          --runtime ${{ matrix.rid }}
          --self-contained true
          /p:Version=${{ env.RELEASE_VERSION }}
          /p:InformationalVersion=${{ env.RELEASE_TAG }}
          --output ./artifacts/publish/${{ matrix.app_id }}/${{ matrix.rid }}

      - name: Package published output on Windows
        if: runner.os == 'Windows'
        shell: pwsh
        run: |
          $archivePath = Join-Path $env:GITHUB_WORKSPACE "artifacts/packages/${{ matrix.package_name }}-${{ matrix.rid }}.zip"

          if (Test-Path $archivePath) {
            Remove-Item $archivePath -Force
          }

          Compress-Archive `
            -Path "$env:GITHUB_WORKSPACE/artifacts/publish/${{ matrix.app_id }}/${{ matrix.rid }}/*" `
            -DestinationPath $archivePath

      - name: Build Windows desktop installer
        if: runner.os == 'Windows' && matrix.app_id == 'desktop'
        shell: pwsh
        run: |
          choco install innosetup --no-progress --yes

          $version = $env:RELEASE_VERSION
          if ([string]::IsNullOrWhiteSpace($version)) {
            $version = "0.0.0"
          }

          $scriptPath = Join-Path $env:RUNNER_TEMP "StemCode.Desktop.iss"
          $publishDir = (Join-Path $env:GITHUB_WORKSPACE "artifacts/publish/${{ matrix.app_id }}/${{ matrix.rid }}").Replace('\', '\\')
          $outputDir = (Join-Path $env:GITHUB_WORKSPACE "artifacts/packages").Replace('\', '\\')
          $setupIconFile = (Join-Path $env:GITHUB_WORKSPACE "StemCode.Desktop/Assets/logo.ico").Replace('\', '\\')

          @"
          #define MyAppName "StemCode Desktop"
          #define MyAppVersion "$version"
          #define MyAppPublisher "StemCode"
          #define MyAppExeName "StemCode.Desktop.exe"

          [Setup]
          AppId={{99F60D6D-6C4D-4CB8-934F-03CBF59D34BC}
          AppName={#MyAppName}
          AppVersion={#MyAppVersion}
          AppPublisher={#MyAppPublisher}
          DefaultDirName={autopf}\StemCode Desktop
          DefaultGroupName=StemCode Desktop
          DisableProgramGroupPage=yes
          OutputDir=$outputDir
          OutputBaseFilename=StemCode.Desktop-${{ matrix.rid }}-setup
          SetupIconFile=$setupIconFile
          Compression=lzma
          SolidCompression=yes
          WizardStyle=modern
          ArchitecturesAllowed=x64compatible
          ArchitecturesInstallIn64BitMode=x64compatible

          [Files]
          Source: "$publishDir\\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs

          [Icons]
          Name: "{autoprograms}\StemCode Desktop"; Filename: "{app}\{#MyAppExeName}"
          Name: "{autodesktop}\StemCode Desktop"; Filename: "{app}\{#MyAppExeName}"; Tasks: desktopicon

          [Tasks]
          Name: "desktopicon"; Description: "Create a desktop shortcut"; GroupDescription: "Additional icons:"; Flags: unchecked

          [Run]
          Filename: "{app}\{#MyAppExeName}"; Description: "Launch StemCode Desktop"; Flags: nowait postinstall skipifsilent
          "@ | Set-Content -Path $scriptPath -Encoding UTF8

          & "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" $scriptPath

      - name: Package published output on Linux and macOS
        if: runner.os != 'Windows'
        shell: bash
        run: |
          archive_path="$GITHUB_WORKSPACE/artifacts/packages/${{ matrix.package_name }}-${{ matrix.rid }}.zip"
          publish_dir="$GITHUB_WORKSPACE/artifacts/publish/${{ matrix.app_id }}/${{ matrix.rid }}"

          cd "$publish_dir"
          zip -r "$archive_path" .

      - name: Upload packaged artifact
        uses: actions/upload-artifact@v6
        with:
          name: ${{ matrix.artifact_name }}
          path: ./artifacts/packages/${{ matrix.package_name }}-${{ matrix.rid }}*
          if-no-files-found: error
          retention-days: 14

  publish-nuget:
    name: Publish StemCode NuGet package
    needs: pack-nuget
    environment:
      name: production-release
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json

      - name: Download NuGet packages
        uses: actions/download-artifact@v5
        with:
          name: nuget-packages
          path: ./artifacts/packages/nuget

      - name: NuGet login (OIDC -> temp API key)
        id: nuget_login
        uses: NuGet/login@v1
        with:
          user: ${{ secrets.NUGET_USER || vars.NUGET_USER || github.repository_owner }}

      - name: Publish StemCode package to NuGet.org
        shell: bash
        run: |
          set -euo pipefail

          shopt -s nullglob
          packages=(./artifacts/packages/nuget/StemCode.[0-9]*.nupkg)
          symbols=(./artifacts/packages/nuget/StemCode.[0-9]*.snupkg)

          if [[ "${#packages[@]}" -eq 0 ]]; then
            echo "No StemCode NuGet packages were produced." >&2
            exit 1
          fi

          for package_path in "${packages[@]}"; do
            dotnet nuget push "$package_path" \
              --api-key "${{ steps.nuget_login.outputs.NUGET_API_KEY }}" \
              --source "${{ env.NUGET_SOURCE }}" \
              --skip-duplicate
          done

          for symbol_path in "${symbols[@]}"; do
            dotnet nuget push "$symbol_path" \
              --api-key "${{ steps.nuget_login.outputs.NUGET_API_KEY }}" \
              --source "${{ env.NUGET_SOURCE }}" \
              --skip-duplicate
          done

  publish-release:
    name: Publish GitHub release
    needs:
      - publish
      - publish-nuget
    runs-on: ubuntu-24.04
    permissions:
      attestations: write
      contents: write
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}
          fetch-depth: 0

      - name: Download packaged artifacts
        uses: actions/download-artifact@v5
        with:
          path: ./artifacts/release

      - name: Stage release assets
        shell: bash
        run: |
          set -euo pipefail

          release_dir="$GITHUB_WORKSPACE/artifacts/release-assets"
          mkdir -p "$release_dir"

          while IFS= read -r asset_path; do
            asset_name="$(basename "$asset_path")"
            destination="$release_dir/$asset_name"

            if [[ -e "$destination" ]]; then
              echo "Duplicate release asset name detected: $asset_name" >&2
              exit 1
            fi

            cp "$asset_path" "$destination"
          done < <(
            find "$GITHUB_WORKSPACE/artifacts/release" -type f \( -name '*.zip' -o -name '*.exe' -o -name '*.nupkg' \) |
              sort
          )

          asset_count="$(find "$release_dir" -maxdepth 1 -type f | wc -l | tr -d ' ')"
          if [[ "$asset_count" -eq 0 ]]; then
            echo "No release assets were found." >&2
            exit 1
          fi

      - name: Create SHA256 checksums
        shell: bash
        run: |
          set -euo pipefail

          release_dir="$GITHUB_WORKSPACE/artifacts/release-assets"

          (
            cd "$release_dir"
            find . -maxdepth 1 -type f ! -name SHA256SUMS -printf '%P\0' |
              sort -z |
              xargs -0 sha256sum
          ) > "$release_dir/SHA256SUMS"

      - name: Attest release artifacts
        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
        with:
          subject-checksums: ./artifacts/release-assets/SHA256SUMS

      - name: Create release notes
        id: release_notes
        shell: bash
        run: |
          set -euo pipefail

          notes_file="$RUNNER_TEMP/release-notes.md"
          previous_tag="$(git tag --sort=-creatordate | grep -Fxv "$RELEASE_TAG" | head -n 1 || true)"

          if [[ -n "$previous_tag" ]]; then
            commit_lines="$(git log "${previous_tag}..HEAD" --pretty=format:'- %s (%h)' --no-merges)"
          else
            commit_lines="$(git log HEAD --pretty=format:'- %s (%h)' --no-merges)"
          fi

          asset_lines="$(
            find "$GITHUB_WORKSPACE/artifacts/release-assets" -maxdepth 1 -type f |
              sort |
              while IFS= read -r asset_path; do
                printf -- '- %s\n' "$(basename "$asset_path")"
              done
          )"

          {
            echo "# StemCode $RELEASE_TAG"
            echo
            echo "## Release assets"
            echo
            echo "${asset_lines:-- No release assets were produced.}"
            echo
            echo "## Verification"
            echo
            echo "- SHA256 hashes are published in SHA256SUMS."
            echo "- The install scripts verify downloaded CLI archives against SHA256SUMS when it is available."
            echo "- GitHub artifact attestations establish SLSA build provenance for the checksummed release assets."
            echo
            echo "## Commit messages"
            echo
            echo "${commit_lines:-- Initial release.}"
          } > "$notes_file"

          echo "path=$notes_file" >> "$GITHUB_OUTPUT"

      - name: Create or update GitHub release
        shell: bash
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail

          tag="$RELEASE_TAG"
          title="StemCode $tag"
          target_sha="$(git rev-parse HEAD)"
          mapfile -t assets < <(find "$GITHUB_WORKSPACE/artifacts/release-assets" -maxdepth 1 -type f | sort)

          if [[ "${#assets[@]}" -eq 0 ]]; then
            echo "No release assets were found." >&2
            exit 1
          fi

          if gh release view "$tag" >/dev/null 2>&1; then
            gh release upload "$tag" "${assets[@]}" --clobber
            gh release edit "$tag" --title "$title" --notes-file "${{ steps.release_notes.outputs.path }}"
          else
            gh release create "$tag" "${assets[@]}" \
              --title "$title" \
              --notes-file "${{ steps.release_notes.outputs.path }}" \
              --target "$target_sha"
          fi

  publish-npm:
    name: Publish npm package (${{ matrix.package_name }})
    needs:
      - validate
      - publish-release
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        include:
          - package_name: stemcode
            package_dir: packaging/npm
          - package_name: "stemcode-sdk"
            package_dir: js
    environment:
      name: production-release
    permissions:
      contents: read
      id-token: write
    env:
      RELEASE_VERSION: ${{ needs.validate.outputs.release_version }}

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          package-manager-cache: false

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
          
      - name: Setup npm
        run: npm install --global npm@latest

      - name: Verify npm OIDC requirements
        run: |
          node --version
          npm --version
          
      - name: Install package dependencies
        working-directory: ${{ matrix.package_dir }}
        run: npm ci

      - name: Set package version
        working-directory: ${{ matrix.package_dir }}
        run: npm version "$RELEASE_VERSION" --no-git-tag-version --allow-same-version

      - name: Publish ${{ matrix.package_name }} to npm
        working-directory: ${{ matrix.package_dir }}
        run: |          
          npm publish --access public

  publish-python:
    name: Publish Python package (stemcode-sdk)
    needs:
      - validate
      - publish-release
    runs-on: ubuntu-24.04
    environment:
      name: production-release
      url: https://pypi.org/p/stemcode-sdk
    permissions:
      contents: read
      id-token: write
    env:
      RELEASE_VERSION: ${{ needs.validate.outputs.release_version }}

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          ref: ${{ env.RELEASE_REF }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
          cache: true
          cache-dependency-path: |
            StemCode/packages.lock.json

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: python/pyproject.toml

      - name: Install package tools
        run: python -m pip install --upgrade build twine

      - name: Set Python package version
        shell: bash
        run: |
          python - <<'PY'
          from pathlib import Path
          import os
          import re

          path = Path("python/pyproject.toml")
          text = path.read_text(encoding="utf-8")
          replacement = f'version = "{os.environ["RELEASE_VERSION"]}"'
          text, count = re.subn(r'(?m)^version = "[^"]+"$', replacement, text, count=1)
          if count != 1:
              raise SystemExit("Expected exactly one project version in python/pyproject.toml.")
          path.write_text(text, encoding="utf-8")
          PY

      - name: Build wheel and source distribution
        working-directory: python
        run: python -m build

      - name: Check distributions
        working-directory: python
        run: python -m twine check dist/*

      - name: Publish stemcode-sdk to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: python/dist