name: build firmware

on:
  push:
    branches: [ "master" ]

# A release run deletes and re-creates a tag, then force-pushes the
# firmware-dist branch. Two overlapping runs would race on both, and the loser
# could leave firmware-dist pointing at a half-published set.
#
# Queue rather than cancel: `create-release` deletes the existing release before
# creating the replacement, so cancelling a run mid-flight can leave the repo
# with no release at all for that version.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

# Default for jobs that do not declare their own. create-release and
# publish-catalog override this with contents: write. Same-run artifact
# upload/download uses the Actions runtime token, not GITHUB_TOKEN, so it needs
# no scope here.
permissions:
  contents: read

env:
  zephyr_sdk: 1.0.1
  python_version: 3.12
  toolchains: arm-zephyr-eabi:xtensa-espressif_esp32s3_zephyr-elf:xtensa-espressif_esp32_zephyr-elf:riscv64-zephyr-elf

  # Mark the GitHub release as a pre-release AND skip the Mesh America catalog
  # publish. Set to "true" for a release that should not reach ordinary users
  # through apps.meshamerica.com's browser flasher; set back to "false" for a
  # normal release.
  #
  # Two separate effects, both driven from here so they cannot drift apart:
  #   - the release is created with prerelease: true, so GitHub does not mark it
  #     "Latest" and it is excluded from the /releases/latest API.
  #   - publish-catalog is skipped entirely, so the firmware-dist branch and its
  #     catalog.json are left ALONE — the configurator keeps offering whatever
  #     the last non-prerelease build published. Nothing is unpublished or
  #     rolled back; that branch is simply not force-pushed this time.
  # Release artifacts are still built and attached, so a manual download and
  # flash works exactly as usual.
  #
  # "false" is the normal state. It is easy to leave this on "true" and then
  # silently keep shipping nothing to the configurator, so check it when cutting
  # a release rather than assuming.
  prerelease: "false"

jobs:
  # Populates the west-modules cache once so the five build jobs do not each pay
  # for a cold `west update` plus a blob download. Compiles nothing, which is why
  # ccache is switched off here — otherwise the action would write an empty
  # 512 MB cache entry every run for no benefit.
  #
  # This job is also the ONLY writer of the modules cache. The build jobs are
  # restore-only, so a tree that a build has patched in place can never be saved
  # back — the cached modules stay pristine-plus-blobs.
  setup-zephyr:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'

    # Keyed on the manifest, NOT on github.sha. zephcore/west.yml pins the Zephyr
    # revision and Zephyr's own manifest is imported from it, so the manifest
    # hash captures the full transitive module set. The old per-SHA key meant a
    # fresh multi-GB entry on every push that was never read again, and that
    # churn is a large part of what evicted everything else out of the repo's
    # 10 GB cache budget.
    #
    # Deliberately no restore-keys: a near-miss would restore modules pinned to
    # DIFFERENT revisions, and `west update` then has to move HEAD in a tree our
    # patches may have dirtied. An exact hit or a clean fetch, nothing between.
    #
    # Restored BEFORE the Zephyr setup so a hit makes `west update` a no-op. The
    # matching save runs as this job's post-step, i.e. after the blob fetches
    # below, so the cached tree carries the blobs with it.
    - uses: actions/cache@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        enable-ccache: 'false'

    # Both vendor BLE controller blobs, fetched here so they ride along in the
    # modules cache above. `west blobs fetch` compares each blob's sha256 and
    # skips the ones already present (zephyr/scripts/west_commands/blobs.py), so
    # this is a cheap no-op on a cache hit — no need for a second cache layer or
    # a cache-hit conditional.
    - name: Download vendor BLE controller blobs
      run: |
        west blobs fetch hal_espressif
        west blobs fetch hal_silabs

  build-nrf:
    needs: setup-zephyr
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'
    - run: pip install -r requirements.txt

    # Soft dependency: a miss here is self-healing, because `west update` in the
    # next step just does the work itself. Contrast with the firmware handoff at
    # the end of this job, which is NOT self-healing and therefore uses an
    # artifact.
    - uses: actions/cache/restore@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    # ccache-cache-key is per-job. The action's default is the literal string
    # "default" and its restore-keys is a bare `ccache-<key>-` prefix, so leaving
    # it unset put all six jobs in one namespace: build-nrf would restore
    # whatever build-esp32-companions saved last (arm objects vs xtensa objects —
    # a near-zero hit rate), and each job's 512 MB save overwrote the previous
    # one's useful content. The key also embeds a timestamp, so every job writes
    # a NEW entry every run; six of those per push is up to ~3 GB against a 10 GB
    # repo budget, which is what evicted the SDK, pip and module caches.
    # Namespacing fixes both halves.
    #
    # Size knob if hit rates look poor: ccache-max-size (default 512MB).
    # build-nrf compiles ~40 board/role combos and will churn inside that cap.
    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        ccache-cache-key: ${{ github.job }}

    - name: build firmwares
      run: bash build.sh nrf

    # Hit rate is the entire point of the per-job ccache namespace above, but the
    # action only prints stats at SETUP time — it runs `ccache -z -s -vv`, which
    # reports the restored cache and then zeroes the counters. Without a stats
    # call here the run ends with no record of whether ccache did anything at
    # all. Read Hits/Misses to decide whether ccache-max-size needs raising.
    - name: ccache stats
      if: always()
      run: ccache -s -vv

    # Job-to-job handoff is an artifact, not a cache. actions/cache/restore
    # defaults to fail-on-cache-miss: false, so an entry evicted between this job
    # and create-release made the release publish a SILENTLY incomplete firmware
    # set — and publish-catalog force-push a matching incomplete catalog.json to
    # the live Mesh America configurator feed. Artifacts are scoped to the run,
    # cannot be evicted mid-run, and if-no-files-found: error fails loudly.
    - uses: actions/upload-artifact@v7
      with:
        name: firmware-part-${{ github.job }}
        path: firmware
        if-no-files-found: error
        # Consumed within this run; the merged set is re-uploaded by
        # create-release and attached to the release itself.
        retention-days: 1
        # Lets a failed run be re-run without tripping "artifact already exists".
        overwrite: true

  build-esp32-repeaters:
    needs: setup-zephyr
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'
    - run: pip install -r requirements.txt

    - uses: actions/cache/restore@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        ccache-cache-key: ${{ github.job }}

    # No-op when the modules cache hit (the blobs came with it); the safety net
    # for when it missed.
    - name: Download Espressif BLE controller blobs
      run: west blobs fetch hal_espressif

    - name: build firmwares
      run: bash build.sh esp32 repeaters

    - name: ccache stats
      if: always()
      run: ccache -s -vv

    - uses: actions/upload-artifact@v7
      with:
        name: firmware-part-${{ github.job }}
        path: firmware
        if-no-files-found: error
        retention-days: 1
        overwrite: true

  build-linux:
    needs: setup-zephyr
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'
    - run: pip install -r requirements.txt

    - uses: actions/cache/restore@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        ccache-cache-key: ${{ github.job }}

    # native_sim presets are cross-compiled for the target SBC architecture:
    # femtofox = ARMv7-A (32-bit), rak6421 / rak6421_pi5 = aarch64 (64-bit).
    - name: Install cross-compile toolchains
      run: |
        sudo apt-get update
        sudo apt-get install -y \
          gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf \
          gcc-aarch64-linux-gnu   g++-aarch64-linux-gnu

    - name: build firmwares
      run: bash build.sh linux

    - name: ccache stats
      if: always()
      run: ccache -s -vv

    - uses: actions/upload-artifact@v7
      with:
        name: firmware-part-${{ github.job }}
        path: firmware
        if-no-files-found: error
        retention-days: 1
        overwrite: true

  # SWD-only ARM platforms: nRF54L15, EFR32MG24 and STM32WL. None of these SoCs
  # has a USB device peripheral, so all three publish a bare zephyr.hex and are
  # download-only tiles in the catalog. Grouped into one job because the board
  # count is small (4 boards x 2 roles) and they share the arm-zephyr-eabi
  # toolchain that `toolchains` already installs.
  build-swd:
    needs: setup-zephyr
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'
    - run: pip install -r requirements.txt

    - uses: actions/cache/restore@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        ccache-cache-key: ${{ github.job }}

    # MG24 only: the Silabs BLE controller is a binary blob, without which the
    # xiao_mg24 companion cannot link. No-op when the modules cache hit.
    - name: Download Silicon Labs BLE controller blobs
      run: west blobs fetch hal_silabs

    - name: build firmwares
      run: |
        bash build.sh nrf54l
        bash build.sh mg24
        bash build.sh stm32wl

    - name: ccache stats
      if: always()
      run: ccache -s -vv

    - uses: actions/upload-artifact@v7
      with:
        name: firmware-part-${{ github.job }}
        path: firmware
        if-no-files-found: error
        retention-days: 1
        overwrite: true

  build-esp32-companions:
    needs: setup-zephyr
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'
        cache: 'pip'
    - run: pip install -r requirements.txt

    - uses: actions/cache/restore@v5
      with:
        path: modules
        key: zephyr-modules-${{ runner.os }}-${{ hashFiles('zephcore/west.yml') }}

    - name: Setup Zephyr project
      uses: zephyrproject-rtos/action-zephyr-setup@v1
      with:
        app-path: zephcore
        toolchains: ${{ env.toolchains }}
        sdk-version: ${{ env.zephyr_sdk }}
        ccache-cache-key: ${{ github.job }}

    - name: Download Espressif BLE controller blobs
      run: west blobs fetch hal_espressif

    - name: build firmwares
      run: bash build.sh esp32 companions

    - name: ccache stats
      if: always()
      run: ccache -s -vv

    - uses: actions/upload-artifact@v7
      with:
        name: firmware-part-${{ github.job }}
        path: firmware
        if-no-files-found: error
        retention-days: 1
        overwrite: true

  create-release:
    needs: [build-nrf, build-esp32-companions, build-esp32-repeaters, build-linux,
            build-swd]
    runs-on: ubuntu-latest
    # Needs write to create the release AND to delete/replace an existing one for
    # the same version (see the "replace existing release" step below).
    permissions:
      contents: write
    outputs:
      release_tag: ${{ steps.tag.outputs.release_tag }}
      # Re-exported as a job output because the `env` context is NOT available
      # in a job-level `if:` — publish-catalog cannot read env.prerelease
      # directly and has to gate on this instead.
      prerelease: ${{ env.prerelease }}

    steps:
    - uses: actions/checkout@v6

    # Tag the release with the firmware version string itself (the single source
    # of truth in zephcore/CMakeLists.txt), NOT a build timestamp. The same value
    # becomes the Mesh America catalog's version key, so the configurator can
    # compare a running device's reported firmware against the catalog and know
    # it's up to date. A timestamp tag could never match what the device reports.
    #
    # NOTE: the tag is only unique per version — pushing master again without
    # bumping ZEPHCORE_FIRMWARE_VERSION updates the existing release in place
    # rather than cutting a new one. Bump the version to cut a new release.
    - name: derive release tag from firmware version
      id: tag
      run: |
        version=$(sed -n 's/^set(ZEPHCORE_FIRMWARE_VERSION "\(.*\)")/\1/p' zephcore/CMakeLists.txt)
        if [ -z "$version" ]; then
          echo "::error::Could not read ZEPHCORE_FIRMWARE_VERSION from zephcore/CMakeLists.txt"
          exit 1
        fi
        echo "Release tag / catalog version: $version"
        echo "release_tag=$version" >> $GITHUB_OUTPUT

    # Pull every build job's output back into a single firmware/ directory.
    # merge-multiple flattens all five parts into that one path, which is what
    # the release upload and gen_provider_catalog.py both expect.
    - uses: actions/download-artifact@v7
      with:
        pattern: firmware-part-*
        merge-multiple: true
        path: firmware

    - name: verify firmware set arrived
      run: |
        count=$(find firmware -type f 2>/dev/null | wc -l)
        echo "Collected $count firmware files"
        if [ "$count" -eq 0 ]; then
          echo "::error::No firmware files downloaded — the build artifacts did not arrive"
          exit 1
        fi
        ls -la firmware

    - name: upload firmware artifacts
      uses: actions/upload-artifact@v7
      with:
        name: firmware-${{ steps.tag.outputs.release_tag }}
        path: firmware
        if-no-files-found: error
        overwrite: true

    # Publish releasenotes/RELEASE_NOTES_<version>.md as the release body. The
    # filename matches the firmware version string exactly (= the release tag), so
    # this is a direct lookup with no name munging. Write the notes for a version
    # before bumping to it; a missing file only warns (empty body), never fails
    # the release.
    - name: resolve release notes
      id: notes
      run: |
        notes="releasenotes/RELEASE_NOTES_${{ steps.tag.outputs.release_tag }}.md"
        if [ -f "$notes" ]; then
          echo "Using release notes: $notes"
          echo "notes_path=$notes" >> $GITHUB_OUTPUT
        else
          echo "::warning::No release notes at $notes — publishing with an empty body"
          : > "${RUNNER_TEMP}/empty_notes.md"
          echo "notes_path=${RUNNER_TEMP}/empty_notes.md" >> $GITHUB_OUTPUT
        fi

    # Replace any existing release for this version instead of piling onto it.
    # Since the tag is the firmware version, re-pushing master without a bump
    # reuses the tag. action-gh-release only overwrites assets with the SAME
    # name, but our firmware filenames embed the commit hash — so a rebuild would
    # ADD ~100 new assets beside the old ones and leave the tag pinned to the old
    # commit. Deleting first (with the tag) makes each build a clean replacement:
    # current assets only, tag re-created on the building commit.
    # `|| true` — the first release of a version has nothing to delete.
    - name: replace existing release for this version
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        tag="${{ steps.tag.outputs.release_tag }}"
        if gh release view "$tag" >/dev/null 2>&1; then
          echo "Existing release $tag found — deleting it (and its tag) so this build replaces it"
          gh release delete "$tag" --yes --cleanup-tag || true
        else
          echo "No existing release for $tag — creating a new one"
        fi

    - name: create release
      uses: softprops/action-gh-release@v2
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        tag_name: ${{ steps.tag.outputs.release_tag }}
        name: Firmware ${{ steps.tag.outputs.release_tag }}
        body_path: ${{ steps.notes.outputs.notes_path }}
        target_commitish: ${{ github.sha }}
        draft: false
        prerelease: ${{ env.prerelease }}
        files: firmware/*

  # Publish firmware + provider catalog for the Mesh America configurator
  # (apps.meshamerica.com). GitHub Release assets have no CORS header, so the
  # browser flasher cannot fetch them; instead we force-push the firmware and a
  # generated catalog.json to the `firmware-dist` orphan branch, served from
  # CORS-clean hosts (firmware via jsDelivr, catalog via raw.githubusercontent).
  # The stable catalog URL registered with Mesh America is:
  #   https://raw.githubusercontent.com/<owner>/<repo>/firmware-dist/catalog.json
  #
  # Skipped entirely on a pre-release (see the `prerelease` env at the top).
  # This branch is force-pushed, so skipping is the whole mechanism: the
  # previous release's firmware and catalog.json stay exactly as they are and
  # the configurator keeps offering that version.
  publish-catalog:
    needs: create-release
    if: needs.create-release.outputs.prerelease != 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: '${{ env.python_version }}'

    # Pull every board's firmware back into a single firmware/ directory. This
    # branch is force-pushed, so an incomplete set here silently DELETES boards
    # from the live configurator feed — which is exactly why this handoff must
    # not be a cache that can be evicted between jobs.
    - uses: actions/download-artifact@v7
      with:
        pattern: firmware-part-*
        merge-multiple: true
        path: firmware

    - name: verify firmware set arrived
      run: |
        count=$(find firmware -type f 2>/dev/null | wc -l)
        echo "Collected $count firmware files"
        if [ "$count" -eq 0 ]; then
          echo "::error::No firmware files downloaded — refusing to force-push an empty firmware-dist"
          exit 1
        fi

    - name: generate provider catalog
      run: |
        python gen_provider_catalog.py --firmware-dir firmware \
          --url-base "https://cdn.jsdelivr.net/gh/${{ github.repository }}@firmware-dist" \
          --version "${{ needs.create-release.outputs.release_tag }}" \
          --out catalog.json

    - name: publish firmware + catalog to firmware-dist branch
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        tag="${{ needs.create-release.outputs.release_tag }}"
        work="$(mktemp -d)"
        cp catalog.json "$work/"
        cp firmware/* "$work/"
        {
          echo "# ZephCore firmware-dist"
          echo
          echo "Auto-generated distribution branch for the Mesh America device"
          echo "configurator. Force-pushed by the \`build firmware\` workflow each"
          echo "release -- do not edit by hand."
          echo
          echo "- Catalog (register this URL): https://raw.githubusercontent.com/${{ github.repository }}/firmware-dist/catalog.json"
          echo "- Firmware (jsDelivr): https://cdn.jsdelivr.net/gh/${{ github.repository }}@firmware-dist/"
          echo "- Built from release: $tag"
        } > "$work/README.md"
        cd "$work"
        git init -q -b firmware-dist
        git config user.name "github-actions[bot]"
        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
        git add -A
        git commit -q -m "firmware-dist: $tag"
        git push -f "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" firmware-dist