feat: add append-only GitHub package updates (#543)

Declare automatic updates for 82 GitHub-direct descriptors and pin the merged xpkgindex-update Action. Validate shared version resources and exact candidate locks while preserving every published version and mirror.

All 52 candidate jobs and 13 existing-consumer shards passed. Includes explicit, user-approved reporting for the unavailable MySQL source.

Author: Sunrisepeak

.agents/docs/2026-10-19-xpkgindex-update-design.md

@@ -1499,6 +1499,19 @@ jobs:
         run: |
           "$MCPP" index update
 
+      - name: Report temporarily untestable consumers of the unavailable MySQL source
+        shell: bash
+        run: |
+          if [[ "$RUNNER_OS" == Windows ]]; then
+            python tests/autoupdate/source_outage.py members
+          else
+            python3 tests/autoupdate/source_outage.py members
+          fi
+
+      - name: Install nanodbc macOS development headers
+        if: runner.os == 'macOS' && contains(format(' {0} ', env.MEMBERS), ' nanodbc ')
+        run: brew install libiodbc
+
       - name: mcpp test (workspace or affected members)
         shell: bash
         env:

.github/workflows/validate.yml

@@ -0,0 +1,214 @@
+name: xpkgindex-update
+
+on:
+  pull_request:
+    paths:
+      - 'pkgs/**/*.lua'
+      - 'tests/autoupdate/**'
+      - '.github/xpkgindex-update.yml'
+      - '.github/workflows/xpkgindex-update.yml'
+  workflow_dispatch:
+    inputs:
+      package:
+        description: "Optional namespace:name; empty scans all declared packages"
+        type: string
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: xpkgindex-update-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUTF8: '1'
+  MCPP_VERSION: '2026.10.1.2'
+  MCPP_INDEX_MIRROR: GLOBAL
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    outputs:
+      matrix: ${{ steps.matrix.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/checkout@v4
+        with:
+          repository: openxlings/xpkgindex-update
+          ref: 23c5e04948c55e606bc56ee2c649ddd4849b7ec6
+          path: .updater
+          persist-credentials: false
+      - name: Use the pinned updater source
+        run: echo "PYTHONPATH=$PWD/.updater/src" >> "$GITHUB_ENV"
+      - name: All GitHub-direct descriptors are declared; published versions are unchanged
+        id: coverage
+        env:
+          BASE: ${{ github.event.pull_request.base.sha || 'origin/main' }}
+        run: |
+          python -m unittest discover -s tests/autoupdate -p 'test_*.py'
+          python tests/autoupdate/ci.py audit --base "$BASE" --output coverage.json
+          python tests/autoupdate/ci.py selection --base "$BASE" --output selected-package.txt
+          echo "package=$(cat selected-package.txt)" >> "$GITHUB_OUTPUT"
+      - name: Discover and download real upstream candidates
+        id: scan
+        continue-on-error: true # The mandatory gate below accepts only the approved source outage.
+        uses: openxlings/xpkgindex-update@23c5e04948c55e606bc56ee2c649ddd4849b7ec6
+        with:
+          mode: check
+          token: ${{ github.token }}
+          package: ${{ inputs.package || steps.coverage.outputs.package }}
+      - name: Reject all scan failures except the approved unavailable source
+        if: always()
+        env:
+          PLAN: ${{ steps.scan.outputs.plan }}
+          OUTCOME: ${{ steps.scan.outcome }}
+        run: python tests/autoupdate/source_outage.py scan-gate --plan "$PLAN" --outcome "$OUTCOME"
+      - name: Plan actual candidate build/run jobs
+        id: matrix
+        if: always() && steps.scan.outputs.plan != ''
+        env:
+          PLAN: ${{ steps.scan.outputs.plan }}
+          BASE: ${{ github.event.pull_request.base.sha || 'origin/main' }}
+        run: |
+          python tests/autoupdate/ci.py matrix --plan "$PLAN" --base "$BASE" --output matrix.json
+          echo "matrix=$(cat matrix.json)" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: xpkgindex-update-build-plan
+          path: build-plan.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: xpkgindex-update-coverage
+          path: |
+            coverage.json
+            matrix.json
+
+  candidate:
+    name: candidate (${{ matrix.id }} ${{ matrix.candidate }}, ${{ matrix.platform }}, ${{ matrix.toolchain }})
+    needs: scan
+    if: >-
+      always() && !cancelled() && needs.scan.outputs.matrix != '' && needs.scan.outputs.matrix != '{"include": []}'
+    strategy:
+      fail-fast: false
+      max-parallel: 8
+      matrix: ${{ fromJSON(needs.scan.outputs.matrix) }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/checkout@v4
+        with:
+          repository: openxlings/xpkgindex-update
+          ref: 23c5e04948c55e606bc56ee2c649ddd4849b7ec6
+          path: .updater
+          persist-credentials: false
+      - uses: actions/download-artifact@v4
+        with:
+          name: xpkgindex-update-build-plan
+          path: .candidate-plan
+      - name: Use the pinned updater and a standalone consumer
+        shell: bash
+        run: |
+          if [[ "$RUNNER_OS" == Windows ]]; then
+            echo "PYTHONPATH=$(cygpath -m "$PWD/.updater/src")" >> "$GITHUB_ENV"
+            echo "CONSUMER=$(cygpath -m "$RUNNER_TEMP/candidate-consumer")" >> "$GITHUB_ENV"
+          else
+            echo "PYTHONPATH=$PWD/.updater/src" >> "$GITHUB_ENV"
+            echo "CONSUMER=$RUNNER_TEMP/candidate-consumer" >> "$GITHUB_ENV"
+          fi
+      - name: Append the candidate and prepare its existing consumer test
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PACKAGE: ${{ matrix.id }}
+        run: |
+          python -m xpkgindex_update apply --plan .candidate-plan/build-plan.json --package "$PACKAGE"
+          python tests/autoupdate/ci.py prepare --plan .candidate-plan/build-plan.json --package "$PACKAGE" --output "$CONSUMER"
+          git diff -- pkgs
+      - uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.mcpp/registry
+            !~/.mcpp/registry/data/xim-pkgindex
+            !~/.mcpp/registry/data/mcpplibs
+          key: candidate-${{ runner.os }}-${{ matrix.toolchain }}-${{ env.MCPP_VERSION }}-${{ github.run_id }}
+          restore-keys: |
+            mcpp-registry-${{ runner.os }}-${{ matrix.toolchain }}-${{ env.MCPP_VERSION }}-
+      - name: Install the same mcpp release as index validation
+        shell: bash
+        env:
+          SUFFIX: ${{ matrix.suffix }}
+          EXT: ${{ matrix.ext }}
+        run: |
+          root="mcpp-${MCPP_VERSION}-${SUFFIX}"
+          archive="$RUNNER_TEMP/$root.$EXT"
+          curl -fsSL --retry 2 -o "$archive" "https://github.com/mcpp-community/mcpp/releases/download/v${MCPP_VERSION}/$root.$EXT"
+          if [[ "$EXT" == zip ]]; then
+            powershell -NoProfile -Command "Expand-Archive -Force -Path '$archive' -DestinationPath '$RUNNER_TEMP'"
+          else
+            tar -xzf "$archive" -C "$RUNNER_TEMP"
+          fi
+          root="$RUNNER_TEMP/$root"
+          mkdir -p "$HOME/.mcpp/registry"
+          cp -a "$root/registry/." "$HOME/.mcpp/registry/"
+          echo "MCPP_HOME=$HOME/.mcpp" >> "$GITHUB_ENV"
+          if [[ "$RUNNER_OS" == Windows ]]; then
+            echo "MCPP=$(cygpath -m "$root/bin/mcpp.exe")" >> "$GITHUB_ENV"
+          else
+            echo "MCPP=$root/bin/mcpp" >> "$GITHUB_ENV"
+          fi
+      - name: Install macOS ODBC development headers
+        if: runner.os == 'macOS' && matrix.id == 'compat:nanodbc'
+        run: brew install libiodbc
+      - name: Resolve, build and run the actual candidate
+        shell: bash
+        env:
+          TOOLCHAIN: ${{ matrix.toolchain }}
+          PACKAGE: ${{ matrix.id }}
+        run: |
+          "$MCPP" index update
+          if [[ "$TOOLCHAIN" != default ]]; then
+            "$MCPP" toolchain install "$TOOLCHAIN"
+            "$MCPP" toolchain default "$TOOLCHAIN"
+          fi
+          cd "$CONSUMER"
+          "$MCPP" test --verbose 2>&1 | tee candidate.log
+      - name: The lockfile proves the candidate was selected
+        shell: bash
+        env:
+          PACKAGE: ${{ matrix.id }}
+        run: python tests/autoupdate/ci.py verify --plan .candidate-plan/build-plan.json --package "$PACKAGE" --consumer "$CONSUMER"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: candidate-${{ strategy.job-index }}
+          path: |
+            ${{ env.CONSUMER }}/candidate.log
+            ${{ env.CONSUMER }}/mcpp.lock
+            ${{ env.CONSUMER }}/mcpp.toml
+      - name: Collect compiler and linker evidence
+        if: always()
+        shell: bash
+        run: python tests/autoupdate/ci.py diagnostics --consumer "$CONSUMER" --output candidate-diagnostics
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: candidate-diagnostics-${{ strategy.job-index }}
+          path: candidate-diagnostics
+          if-no-files-found: ignore

.github/workflows/xpkgindex-update.yml

@@ -0,0 +1,3 @@
+version: 1
+adapter: mcpp-index
+max_prs: 3

.github/xpkgindex-update.yml

@@ -86,6 +86,13 @@ package = {
     repo        = "https://github.com/boost-ext/ut",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "v${version}",
+            url = "https://github.com/boost-ext/ut/archive/refs/tags/${tag}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["2.3.1"] = {

pkgs/b/boost-ext.ut.lua

@@ -9,6 +9,13 @@ package = {
     repo        = "https://github.com/mcpplibs/cmp",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "v${version}",
+            url = "https://github.com/mcpplibs/cmp/releases/download/${tag}/cmp-${version}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["0.1.0"] = {

pkgs/c/cmp.lua

@@ -16,6 +16,13 @@ package = {
     repo        = "https://github.com/AprilRobotics/apriltag",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "v${version}",
+            url = "https://github.com/AprilRobotics/apriltag/archive/refs/tags/${tag}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["3.4.5"] = {

pkgs/c/compat.apriltag.lua

@@ -15,6 +15,13 @@ package = {
     repo        = "https://github.com/boostorg/align",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "boost-${version}",
+            url = "https://github.com/boostorg/align/archive/refs/tags/${tag}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["1.92.0"] = {

pkgs/c/compat.boost-align.lua

@@ -7,6 +7,13 @@ package = {
     repo        = "https://github.com/boostorg/any",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "boost-${version}",
+            url = "https://github.com/boostorg/any/archive/refs/tags/${tag}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["1.92.0"] = {

pkgs/c/compat.boost-any.lua

@@ -46,6 +46,13 @@ package = {
     repo        = "https://github.com/boostorg/asio",
     type        = "package",
 
+    extensions = {
+        autoupdate = {
+            tag = "boost-${version}",
+            url = "https://github.com/boostorg/asio/archive/refs/tags/${tag}.tar.gz",
+        },
+    },
+
     xpm = {
         linux = {
             ["1.92.0"] = {