build.yml

name: TianshanOS Build

on:
  push:
    branches: [main, develop]
    tags:
      - 'v*'  # 版本标签触发
  pull_request:
    branches: [main, develop]
  release:
    types: [published]  # 手动发布 Release 时也自动构建并上传 bin
  workflow_dispatch:  # 允许手动触发

permissions:
  contents: read

concurrency:
  group: firmware-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

env:
  IDF_VERSION: v5.5.2
  TARGET: esp32s3

jobs:
  changes:
    name: Check scope
    runs-on: ubuntu-latest
    outputs:
      run_full: ${{ steps.scope.outputs.run_full }}
      publish_release: ${{ steps.scope.outputs.publish_release }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: python3 -m unittest discover -s tests/ci -p 'test_*.py'
      - run: python3 tests/release/test_release.py
      - run: python3 tests/release/test_security_profile.py
      - run: python3 tests/release/test_serial_upgrade.py
      - name: Select checks and release eligibility
        id: scope
        run: python3 tools/ci/check_profile.py

  web-tests:
    needs: changes
    if: needs.changes.outputs.run_full == 'true'
    name: WebUI regression tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: tests/prompts/package-lock.json
      - run: npm ci --prefix tests/prompts
      - run: npm test --prefix tests/prompts
      - run: python3 tests/release/test_web_minify.py
      - name: Fetch matching ESP-IDF sources for browser Origin regression
        run: |
          export IDF_PATH="$RUNNER_TEMP/web-idf"
          echo "IDF_PATH=$IDF_PATH" >> "$GITHUB_ENV"
          git clone --depth 1 --branch "$IDF_VERSION" --filter=blob:none --sparse https://github.com/espressif/esp-idf.git "$IDF_PATH"
          git -C "$IDF_PATH" sparse-checkout set components/esp_http_server
      - name: Install Chrome for actual-page regressions
        working-directory: tests/prompts
        run: npx playwright install --with-deps chrome
      - run: npm run test:browser --prefix tests/prompts
        env:
          TS_TEST_WEB_TLS: '1'
          NODE_PATH: ${{ github.workspace }}/tests/prompts/node_modules
      - name: Offline xterm and vendor regressions
        run: npm run test:xterm --prefix tests/prompts
        env:
          OFFLINE_RESULTS: ${{ runner.temp }}/xterm-source

  runtime-tests:
    needs: [changes, build]
    if: needs.changes.outputs.run_full == 'true'
    name: Runtime and fan regression tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python3 -m pip install -r tests/certificate/requirements.txt 'Flask>=2.0.0' 'flask-cors>=3.0.0'
      - name: Local OTA download regressions
        run: python3 -m unittest discover -s tools/ota_server -p test_ota_server.py
      - name: Fetch matching ESP-IDF host-test dependencies
        run: |
          export IDF_PATH="$RUNNER_TEMP/runtime-idf"
          echo "IDF_PATH=$IDF_PATH" >> "$GITHUB_ENV"
          git clone --depth 1 --branch "$IDF_VERSION" --filter=blob:none --sparse https://github.com/espressif/esp-idf.git "$IDF_PATH"
          git -C "$IDF_PATH" sparse-checkout set components/json components/mbedtls components/nvs_flash components/console components/soc components/bootloader_support components/esp_app_format components/esp_http_server components/esp_https_server components/http_parser components/esp_http_client components/esp_system components/esp-tls components/tcp_transport components/spiffs components/vfs components/lwip components/esp_netif
          git -C "$IDF_PATH" submodule update --init --recursive --depth 1 components/json/cJSON components/mbedtls/mbedtls
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Fetch the managed WebSocket source from this exact build
        uses: actions/download-artifact@v4
        with:
          name: runtime-dependencies-${{ github.sha }}
          path: managed_components/espressif__esp_websocket_client
      - run: bash tests/runtime/run_all.sh
      - run: bash tests/ws_subscriptions/run_operation_adapter.sh
      - name: Current WebSocket and lifecycle regressions
        run: |
          bash tests/ws_subscriptions/run_host.sh
          bash tests/ws_subscriptions/run_reviewer.sh
          bash tests/ws_subscriptions/run_f1_f2.sh
      - run: bash tests/fan_monitor/run_host.sh
      - name: Fan output and decay regressions
        run: |
          python3 tests/fan_review/run_host.py --check --cjson-dir "$IDF_PATH/components/json/cJSON" --output "$RUNNER_TEMP/fan-review.jsonl"
          node tests/fan_review/test_ui.cjs "$RUNNER_TEMP/fan-review.jsonl"
          python3 tests/fan_decay/run_host.py --csv "$RUNNER_TEMP/fan-decay.csv"
          node tests/fan_decay/test_ui.cjs
      - name: Certificate and current service-stop regressions
        run: |
          cmake -S "$IDF_PATH/components/mbedtls/mbedtls" -B "$RUNNER_TEMP/mbedtls" -DENABLE_TESTING=OFF -DENABLE_PROGRAMS=OFF
          cmake --build "$RUNNER_TEMP/mbedtls" --parallel 2
          CERT_TEST_PYTHON=python3 CERT_TEST_BUILD="$RUNNER_TEMP/certificate-tests" CERT_MBEDTLS_BUILD="$RUNNER_TEMP/mbedtls" bash tests/certificate/run_host.sh

  build:
    needs: changes
    if: needs.changes.outputs.run_full == 'true'
    name: Build ESP32-S3 Firmware
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
      commit: ${{ steps.version.outputs.commit }}
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 完整历史用于版本号生成

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Cache ESP-IDF
        uses: actions/cache@v4
        id: cache-idf
        with:
          path: |
            ~/esp/esp-idf
            ~/.espressif/tools
            ~/.espressif/dist
          # Python virtual environments embed runner/interpreter paths. Cache
          # reusable tools only; create the active Python environment per run.
          key: esp-idf-tools-${{ env.IDF_VERSION }}-${{ runner.os }}-v1
          restore-keys: |
            esp-idf-tools-${{ env.IDF_VERSION }}-${{ runner.os }}-

      - name: Install ESP-IDF tools and matching Python environment
        run: |
          mkdir -p ~/esp
          if [ ! -d ~/esp/esp-idf ]; then
            git clone -b ${{ env.IDF_VERSION }} --depth 1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf
          fi
          cd ~/esp/esp-idf
          # Cached tools may have been installed with a different Python.
          # install.sh creates/checks the environment for the active Python.
          ./install.sh ${{ env.TARGET }}

      - name: Setup ESP-IDF environment
        run: |
          source ~/esp/esp-idf/export.sh
          echo "IDF_PATH=$IDF_PATH" >> $GITHUB_ENV
          echo "$IDF_PATH/tools" >> $GITHUB_PATH

      - name: Cache build directory
        uses: actions/cache@v4
        with:
          path: build
          key: build-${{ env.TARGET }}-${{ hashFiles('**/CMakeLists.txt', '**/Kconfig*', 'sdkconfig.defaults') }}
          restore-keys: |
            build-${{ env.TARGET }}-

      - name: Set target
        run: |
          source ~/esp/esp-idf/export.sh
          # The repository tracks release artifacts under build/, but that
          # checkout is not a complete CMake build tree. Remove it before
          # idf.py set-target, otherwise ESP-IDF refuses its implicit fullclean.
          rm -rf build
          idf.py set-target ${{ env.TARGET }}

      - name: Build firmware
        run: |
          source ~/esp/esp-idf/export.sh
          # 使用 --fresh 确保版本号更新
          rm -f build/CMakeCache.txt
          idf.py build

      - name: Preserve the exact managed source used by runtime fixtures
        uses: actions/upload-artifact@v4
        with:
          name: runtime-dependencies-${{ github.sha }}
          path: managed_components/espressif__esp_websocket_client/
          include-hidden-files: true
          if-no-files-found: error
          retention-days: 7

      - name: Get version info
        id: version
        run: |
          python3 - <<'PYTHON'
          import json, os, subprocess
          from pathlib import Path
          version = json.loads(Path('build/project_description.json').read_text())['project_version']
          if not version:
              raise ValueError('Build version is empty')
          commit = subprocess.check_output(['git', 'rev-parse', 'HEAD'], text=True).strip()
          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
              output.write(f'version={version}\ncommit={commit}\n')
          print('Build version:', version, 'commit:', commit)
          PYTHON

      - name: Print build size
        run: |
          source ~/esp/esp-idf/export.sh
          idf.py size

      - name: Verify this build flashes its Web image
        run: python3 tools/ci/check_web_artifacts.py --build-dir build

      - name: Upload built Web resources
        uses: actions/upload-artifact@v4
        with:
          name: web-assets-${{ github.sha }}
          path: build/esp-idf/ts_webui/web_optimized/
          if-no-files-found: error
          retention-days: 7

      - name: Bind security build policy to this firmware
        run: python3 tools/check_release.py --seal-build build

      - name: Package USB / serial partition upgrade
        run: python3 tools/serial_upgrade.py package --build-dir build --output "build/tianshanos-serial-v$(cat version.txt)"

      - name: Normalize public firmware filename
        run: |
          python3 - <<'PYTHON'
          import json
          from pathlib import Path
          root = Path('build')
          (root / 'TianShanOS.bin').rename(root / 'TianshanOS.bin')
          args = root / 'flasher_args.json'
          data = json.loads(args.read_text())
          data['app']['file'] = 'TianshanOS.bin'
          data['flash_files'] = {address: 'TianshanOS.bin' if name == 'TianShanOS.bin' else name for address, name in data['flash_files'].items()}
          args.write_text(json.dumps(data, indent=2) + '\n')
          evidence = root / 'security-artifact.json'
          artifact = json.loads(evidence.read_text())
          if artifact['binary'] != 'TianShanOS.bin':
              raise ValueError('Unexpected sealed firmware filename')
          artifact['binary'] = 'TianshanOS.bin'
          evidence.write_text(json.dumps(artifact, indent=2) + '\n')
          PYTHON

      - name: Upload firmware artifacts
        uses: actions/upload-artifact@v4
        with:
          name: tianshanos-firmware-${{ steps.version.outputs.version || github.sha }}
          path: |
            build/*.bin
            build/bootloader/bootloader.bin
            build/partition_table/partition-table.bin
            build/flasher_args.json
            build/tianshanos-serial-*.zip
            build/security-build.json
            build/security-artifact.json
          retention-days: 30

      - name: Upload full build (for debugging)
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: build-debug-${{ github.sha }}
          path: |
            build/compile_commands.json
            build/project_description.json
            build/config/sdkconfig.h
          retention-days: 7

  web-artifacts:
    name: Built WebUI smoke test
    needs: [changes, build]
    if: needs.changes.outputs.run_full == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: tests/prompts/package-lock.json
      - run: npm ci --prefix tests/prompts
      - name: Set emitted Web directory
        run: echo "PROJECT_WEB_ROOT=$RUNNER_TEMP/built-web" >> "$GITHUB_ENV"
      - uses: actions/download-artifact@v4
        with:
          name: web-assets-${{ github.sha }}
          path: ${{ runner.temp }}/built-web
      - run: python3 tools/ci/check_web_artifacts.py --web-root "$PROJECT_WEB_ROOT"
      - name: Install Chrome
        working-directory: tests/prompts
        run: npx playwright install --with-deps chrome
      - name: Load the emitted WebUI and verify resource failures block it
        run: node --test tests/prompts/xterm-offline.test.cjs tests/ci/test_web_resource_failure.cjs
        env:
          OFFLINE_RESULTS: ${{ runner.temp }}/xterm-built

  ci-gate:
    name: CI Gate
    needs: [changes, web-tests, runtime-tests, build, web-artifacts]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Decide using the selected results
        if: ${{ always() && !cancelled() }}
        run: python3 tools/ci/check_gate.py
        env:
          NEEDS_JSON: ${{ toJSON(needs) }}
          RUN_CANCELLED: 'false'
      - name: Reject cancellation at the final decision
        if: ${{ always() && cancelled() }}
        run: |
          echo "CI Gate failed: workflow cancelled at the final decision" >&2
          exit 1

  # main keeps automatic version-based publication; PR/dispatch/fork never publish.
  release:
    name: Create or Update Release
    needs: [changes, build, ci-gate]
    if: ${{ !cancelled() && needs.changes.outputs.publish_release == 'true' && needs.build.result == 'success' && needs['ci-gate'].result == 'success' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.build.outputs.commit }}
          fetch-depth: 0
      - uses: actions/download-artifact@v4
        with:
          name: tianshanos-firmware-${{ needs.build.outputs.version }}
          path: firmware
      - name: Validate version, release state and this build's tag
        id: preflight
        run: python3 tools/ci/check_release_state.py
        env:
          GH_TOKEN: ${{ github.token }}
          BUILD_VERSION: ${{ needs.build.outputs.version }}
          BUILD_COMMIT: ${{ needs.build.outputs.commit }}
      - name: Update existing release assets
        if: steps.preflight.outputs.existing_release == 'true'
        run: |
          python3 - <<'PYTHON'
          import os, subprocess
          from pathlib import Path
          groups = [sorted(Path('firmware').glob(pattern)) for pattern in ('**/*.bin', '**/flasher_args.json', '**/*.zip')]
          if any(not files for files in groups):
              raise SystemExit('A required release asset pattern matched no files')
          subprocess.run(['gh', 'release', 'upload', os.environ['RELEASE_TAG'],
                          *[str(path) for files in groups for path in files],
                          '--clobber', '--repo', os.environ['GITHUB_REPOSITORY']], check=True)
          PYTHON
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ steps.preflight.outputs.tag }}

      - name: Create the first release for a new version
        if: steps.preflight.outputs.existing_release == 'false'
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ steps.preflight.outputs.tag }}
          name: TianshanOS ${{ steps.preflight.outputs.tag }}
          files: |
            firmware/**/*.bin
            firmware/**/flasher_args.json
            firmware/**/*.zip
          fail_on_unmatched_files: true
          target_commitish: ${{ needs.build.outputs.commit }}
          body_path: docs/releases/${{ steps.preflight.outputs.tag }}.md
          generate_release_notes: false
          overwrite_files: "true"
          make_latest: "true"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}