Merge remote-tracking branch 'upstream/main' into codex/fix-asio-println

Author: wellwei

.github/workflows/deploy-site.yml

@@ -10,6 +10,11 @@ on:
     paths:
       - 'pkgs/**'
       - '.xpkgindex.json'
+      # The plugin decides how every package reads, the docs are rendered as
+      # site pages, and the cache is what an offline build renders from — a
+      # change to any of them changes the site as much as a descriptor does.
+      - '.xpkgindex/**'
+      - 'docs/**'
       - '.github/workflows/deploy-site.yml'
   workflow_dispatch:
 
@@ -30,13 +35,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          # The growth curve, the history line and the contributor list are
+          # replayed from the git log. xpkgindex detects a shallow clone and
+          # skips all three with a warning, so the default depth of 1 was
+          # quietly shipping a site with no curve at all.
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
       - name: Install xpkgindex
         run: pip install git+https://github.com/openxlings/xpkgindex.git
       - name: Generate static site
         env:
+          # Raises the API rate limit and enables the author -> login mapping
+          # that merges one person's several git identities. The build works
+          # without it, with fewer avatars and less merging.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # xpkgindex >= Apr 2026 surfaces these on the About page.
           XPKGINDEX_BUILD_TIME:       ${{ github.event.head_commit.timestamp }}
           XPKGINDEX_BUILD_COMMIT:     ${{ github.sha }}

.github/workflows/refresh-site-cache.yml

@@ -0,0 +1,56 @@
+name: refresh-site-cache
+
+# Manual refresh of the data the site cannot read from `pkgs/` alone:
+# upstream repo metadata (stars, avatars, contributor logins) and, for Form A
+# packages, the upstream `mcpp.toml` that actually holds their build
+# information.
+#
+# Deliberately manual. The normal `deploy-site` build reads the committed
+# cache and touches no network, so a rendered page never depends on GitHub
+# being reachable at deploy time; this job is how new data gets in.
+#
+# Run it after adding a package or bumping one to a new upstream tag — the
+# cache is keyed by URL and a manifest URL contains the release tag, so a
+# bumped package fetches fresh while everything else is reused.
+
+on:
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Why (shows up in the commit message)"
+        required: false
+        default: "manual refresh"
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # same reason as deploy-site: history replay
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install xpkgindex
+        run: pip install git+https://github.com/openxlings/xpkgindex.git
+
+      - name: Refresh cache
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: xpkgindex generate . --output /tmp/site --refresh
+
+      - name: Commit if anything changed
+        run: |
+          if git diff --quiet -- .xpkgindex/cache; then
+            echo "cache unchanged"
+            exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .xpkgindex/cache
+          git commit -m "chore(site): refresh upstream cache (${{ inputs.reason }})"
+          git push

.github/workflows/site-check.yml

@@ -0,0 +1,66 @@
+name: site-check
+
+# Builds the site on a pull request without publishing it. `validate.yml`
+# proves the packages compile; this proves they still render — a descriptor
+# that parses fine can still collide with another package's URL, and the
+# plugin reads fields no compiler checks.
+#
+# Deliberately offline: a pull request should not spend the API rate limit,
+# and the result should depend only on what is in the repository.
+
+on:
+  pull_request:
+    paths:
+      - 'pkgs/**'
+      - '.xpkgindex.json'
+      - '.xpkgindex/**'
+      - 'docs/**'
+      - '.github/workflows/site-check.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0        # --strict checks the replayed history against the tree
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install xpkgindex
+        run: pip install git+https://github.com/openxlings/xpkgindex.git
+
+      - name: Build the site
+        # --strict turns the growth reconciliation warning into an error: if
+        # the replayed history disagrees with the tree, the curve on the site
+        # would be wrong, and that is worth failing a pull request over.
+        run: xpkgindex generate . --output /tmp/site --offline --strict | tee /tmp/build.log
+
+      - name: No warnings
+        # A duplicate slug or an unparsable descriptor already fails above.
+        # Everything else the build is unhappy about arrives as a warning, and
+        # a warning nobody reads is a warning that becomes permanent.
+        run: |
+          if grep -q 'warning:' /tmp/build.log; then
+            echo "::error::the site build reported warnings"
+            grep 'warning:' /tmp/build.log
+            exit 1
+          fi
+
+      - name: The pages a reader lands on exist
+        run: |
+          set -e
+          for f in index.html index.json stats/index.html contributors/index.html \
+                   about/index.html docs/quick-start/index.html \
+                   zh/index.html zh-Hant/index.html; do
+            test -s "/tmp/site/$f" || { echo "::error::missing $f"; exit 1; }
+          done
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: site
+          path: /tmp/site
+          retention-days: 7

.github/workflows/validate.yml

@@ -404,7 +404,65 @@ jobs:
                      "$1" "$2" "$3" "$4" "$5" "$6" "$i" "$7"
             done
           }
-          if [ "$full" = 1 ]; then ln=3; mn=1; wn=2; else ln=1; mn=1; wn=1; fi
+          # Shard count follows the WORK, per platform, measured.
+          #
+          # It used to be binary — full run: linux 3 / macos 1 / windows 2,
+          # anything else: 1 each — which asserts two things that are not
+          # true. "A partial run is small": touching a widely consumed
+          # descriptor selects every member that consumes it, and this PR's
+          # `pkgs/c/compat.openssl.lua` selected four; one linux shard took
+          # grpc-codegen (3563s) and grpc-module (1701s) back to back and was
+          # cancelled at exactly 1h30m, the job cap. "A full macOS run fits in
+          # one shard": at 6922s measured it does not — it fit only while the
+          # total sat just under the cap, and the run that added grpc-codegen
+          # (1715s on macOS) pushed it to 1h30m20s.
+          #
+          # Sharding is not only a wall-clock lever. Each shard is its own job
+          # with its own `timeout-minutes`, so it is also how the work is made
+          # to FIT. That is the half the "macOS concurrency is 1, so extra
+          # shards run back to back" note above left out: back to back is fine
+          # when the alternative is not finishing.
+          #
+          # tests/member-timings.tsv already holds every member's measured
+          # cost and plan_shards.lua already packs by it (LPT), so the fan-out
+          # comes from the same table: sum this run's members for that
+          # platform and take one shard per ~70 minutes, which leaves ~20
+          # minutes of headroom under the 90-minute cap for a cold cache.
+          #
+          # The caps are where runner concurrency comes back in: linux 3 (the
+          # measured concurrency — a 4th shard would queue), macOS 2, windows
+          # 2. Past those, more shards buy fit that is already there and pay
+          # another checkout + mcpp download + cache restore.
+          #
+          # Full run, from the table: linux 13570s over 3 -> ~75min/shard
+          # (observed slowest 77), macOS 6922s over 2 -> ~57, windows 8043s
+          # over 2 -> ~67. linux is the tight one — its cap binds before the
+          # ~70-minute target does, so it is the first place to look if a
+          # cold full run starts brushing 90 again. The levers, in order:
+          # raise the linux cap to 4 (costs a queued runner), then the job
+          # timeout.
+          shards_for() {   # platform cap -> shard count
+            local secs
+            secs=$(XPLAT="$1" lua5.4 -e '
+              local plat = os.getenv("XPLAT")
+              local sel, all = {}, (os.getenv("MEMBERS") == "__ALL__")
+              if not all then
+                for m in (os.getenv("MEMBERS") or ""):gmatch("%S+") do sel[m] = true end
+              end
+              local total = 0
+              for line in io.lines("tests/member-timings.tsv") do
+                local p, m, s = line:match("^(%S+)\t(%S+)\t(%d+)$")
+                if p == plat and m and (all or sel[m]) then total = total + tonumber(s) end
+              end
+              print(total)')
+            local n=$(( secs / 4200 + 1 ))
+            [ "$n" -gt "$2" ] && n="$2"
+            echo "$1 work: ${secs}s (measured) -> $n shard(s)" >&2
+            echo "$n"
+          }
+          ln=$(shards_for linux 3)
+          mn=$(shards_for macos 2)
+          wn=$(shards_for windows 2)
           {
             printf '{"include":['
             emit linux   ubuntu-latest  linux-x86_64   tar.gz bin/mcpp     registry/bin/xlings     "$ln"

.gitignore

@@ -11,3 +11,6 @@ tests/examples/*/imgui.ini
 
 # 本地 git worktree(逐包验证时开的),不属于索引内容
 .worktrees/
+
+# plugin bytecode
+.xpkgindex/plugins/__pycache__/