Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

ci(hyprland-plugin): requalify the plugin for every Hyprland build (#4910)

Francesco Bonaccidc86ceb93bea
diff --git a/.github/workflows/ci-hyprland-plugin.yml b/.github/workflows/ci-hyprland-plugin.yml
index cc55d60aef..e785676062 100644
--- a/.github/workflows/ci-hyprland-plugin.yml
+++ b/.github/workflows/ci-hyprland-plugin.yml
@@ -54,6 +54,8 @@ jobs:
bash -n packaging/release/PKGBUILD.in
- name: Check lifecycle runner cleanup
run: python3 -m unittest discover -s tests -p '*_test.py' -v
+ - name: Check the requalification automation (unit and dry-run)
+ run: python3 -m unittest discover -s requalify -p 'test_*.py' -v
- name: Check pinned source-release contracts
run: python3 -m unittest discover -s packaging/release -p 'test_*.py' -v
# No real Hyprland headers, module load, or desktop certification in this job.
diff --git a/.github/workflows/nightly-hyprland-plugin-requalify.yml b/.github/workflows/nightly-hyprland-plugin-requalify.yml
new file mode 100644
index 0000000000..4f844f4d49
--- /dev/null
+++ b/.github/workflows/nightly-hyprland-plugin-requalify.yml
@@ -0,0 +1,253 @@
+name: "Nightly: Hyprland plugin requalification"
+
+# Rebuilds and requalifies the Cua Hyprland plugin for every Hyprland build
+# Omarchy or Arch can ship (#4909, refs #4216):
+#
+# detect the tracked packages (hyprland, aquamarine, hyprutils, hyprlang,
+# hyprcursor, hyprgraphics, glibc, gcc, libgcc, libstdc++,
+# libxkbcommon, wayland) by version AND package SHA-256 in Arch
+# core/extra and in Omarchy edge, rc and stable, plus the latest
+# upstream Hyprland GitHub release. A same-version Arch rebuild
+# is a new build. Plugin sources: main, the latest Driver tag,
+# and the Driver source each Omarchy channel packages.
+# requalify per new (Hyprland build, plugin tree): an Arch container on that
+# channel's mirrors builds the plugin with the production options
+# against the exact headers, runs CTest, records the Hyprland
+# binary, header-inventory, compiler and module hashes, then loads
+# the module into a headless Hyprland on vkms and runs the
+# window-targeted background input smoke.
+# report merges the results into compatibility.json (Hyprland build ->
+# plugin build -> status) and matrix.md, uploads both as an
+# artifact, and on scheduled/dispatched main runs commits them to
+# the hyprland-plugin-compat branch, the stable URL Omarchy reads.
+# A failure opens or updates one tracking issue.
+#
+# It never publishes a package, kit or release and never touches an Omarchy
+# repository. CI requalification is not native certification.
+
+on:
+ schedule:
+ # Daily 06:41 UTC, after Omarchy edge's usual overnight package builds.
+ - cron: "41 6 * * *"
+ workflow_dispatch:
+ inputs:
+ force:
+ description: "Rebuild every combination, even ones already in the manifest"
+ type: boolean
+ default: false
+ publish_manifest:
+ description: "Commit the manifest to the hyprland-plugin-compat branch"
+ type: boolean
+ default: true
+ pull_request:
+ paths:
+ - "libs/cua-driver/hyprland-plugin/requalify/**"
+ - ".github/workflows/nightly-hyprland-plugin-requalify.yml"
+
+permissions:
+ contents: read
+
+concurrency:
+ group: hyprland-plugin-requalify-${{ github.ref }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+ CUA_TELEMETRY: "0"
+ DO_NOT_TRACK: "1"
+ REQUALIFY: libs/cua-driver/hyprland-plugin/requalify
+ COMPAT_BRANCH: hyprland-plugin-compat
+ # The same pinned base as libs/images/omarchy; every run upgrades it from
+ # the channel's own mirrors.
+ ARCH_IMAGE: archlinux:base-20260920.0.596911@sha256:f3691b4dde62ba4c4b6f0ae2c1fbf28e8c0c8c4b9a35c7e06dc1f70e21aa29f6
+
+jobs:
+ detect:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ outputs:
+ matrix: ${{ steps.plan.outputs.matrix }}
+ count: ${{ steps.plan.outputs.count }}
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+ - name: Previous manifest
+ run: |
+ set -euo pipefail
+ mkdir -p detect
+ if git fetch --quiet origin "$COMPAT_BRANCH" 2>/dev/null; then
+ git show FETCH_HEAD:compatibility.json >detect/previous.json
+ fi
+ - name: Detect Hyprland builds
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: python3 "$REQUALIFY/channels.py" detect --output detect/snapshot.json
+ - name: Plan the matrix
+ id: plan
+ env:
+ FORCE: ${{ github.event_name == 'pull_request' || inputs.force == true }}
+ run: |
+ set -euo pipefail
+ python3 "$REQUALIFY/channels.py" sources --snapshot detect/snapshot.json \
+ --head "$GITHUB_SHA" --output detect/sources.json
+ args=(--snapshot detect/snapshot.json --sources detect/sources.json --output detect/plan.json)
+ [ -f detect/previous.json ] && args+=(--manifest detect/previous.json)
+ [ "$FORCE" = true ] && args+=(--force)
+ python3 "$REQUALIFY/channels.py" plan "${args[@]}"
+ {
+ echo "matrix=$(cat detect/plan.json)"
+ echo "count=$(python3 -c 'import json,sys; print(len(json.load(open(sys.argv[1]))["include"]))' detect/plan.json)"
+ } >>"$GITHUB_OUTPUT"
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ with:
+ name: requalify-detect
+ path: detect/
+ retention-days: 30
+
+ requalify:
+ needs: detect
+ if: needs.detect.outputs.count != '0'
+ name: ${{ matrix.channel }} hyprland ${{ matrix.hyprland }}, plugin ${{ matrix.ref }}
+ runs-on: ubuntu-24.04
+ timeout-minutes: 60
+ strategy:
+ fail-fast: false
+ max-parallel: 6
+ matrix: ${{ fromJSON(needs.detect.outputs.matrix) }}
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+ - name: Plugin source at ${{ matrix.ref }}
+ env:
+ COMMIT: ${{ matrix.commit }}
+ JOB: ${{ toJSON(matrix) }}
+ run: |
+ set -euo pipefail
+ mkdir -p "$RUNNER_TEMP/source" "$RUNNER_TEMP/out"
+ git archive "$COMMIT" libs/cua-driver/hyprland-plugin | tar -x -C "$RUNNER_TEMP/source"
+ printf '%s' "$JOB" >"$RUNNER_TEMP/job.json"
+ - name: Virtual DRM device (vkms) for the headless session
+ run: |
+ # Without it the build and CTest still run; load and smoke report n/a.
+ if ! sudo modprobe vkms 2>/dev/null; then
+ sudo apt-get update -qq
+ sudo apt-get install -y -qq "linux-modules-extra-$(uname -r)" >/dev/null 2>&1 || true
+ sudo modprobe vkms || echo "::warning::vkms unavailable on this runner"
+ fi
+ ls -l /dev/dri 2>/dev/null || true
+ - name: Build and requalify in an Arch container
+ run: |
+ set -euo pipefail
+ docker run --rm --privileged \
+ -v "$GITHUB_WORKSPACE/libs/cua-driver/hyprland-plugin:/tooling:ro" \
+ -v "$RUNNER_TEMP/source/libs/cua-driver/hyprland-plugin:/source:ro" \
+ -v "$RUNNER_TEMP/job.json:/job.json:ro" \
+ -v "$RUNNER_TEMP/out:/out" \
+ -v /run/udev:/run/udev:ro \
+ "$ARCH_IMAGE" sh -euc '
+ pacman-key --init >/dev/null
+ pacman-key --populate archlinux >/dev/null
+ pacman -Syu --noconfirm --needed python >/dev/null
+ exec python3 /tooling/requalify/qualify.py --job /job.json --source /source --out /out'
+ sudo chown -R "$(id -u):$(id -g)" "$RUNNER_TEMP/out"
+ status=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["status"])' "$RUNNER_TEMP/out/result.json")
+ echo "status: $status"
+ [ "$status" != fail ] || { echo "::error::requalification failed; see result.json and the logs"; exit 1; }
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ if: always()
+ with:
+ name: requalify-result-${{ matrix.id }}
+ path: |
+ ${{ runner.temp }}/out/*.log
+ ${{ runner.temp }}/out/result.json
+ ${{ runner.temp }}/out/session/*.json
+ ${{ runner.temp }}/out/session/*.log
+ ${{ runner.temp }}/out/session/*.lua
+ if-no-files-found: warn
+ retention-days: 90
+
+ report:
+ needs: [detect, requalify]
+ if: always() && needs.detect.result == 'success'
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ permissions:
+ contents: write
+ issues: write
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+ with:
+ name: requalify-detect
+ path: detect
+ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+ with:
+ pattern: requalify-result-*
+ path: results
+ - name: Merge the compatibility manifest
+ id: merge
+ run: |
+ set -euo pipefail
+ mkdir -p results
+ args=(--snapshot detect/snapshot.json --results results --out compat
+ --run-url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID")
+ [ -f detect/previous.json ] && args+=(--previous detect/previous.json)
+ python3 "$REQUALIFY/manifest.py" "${args[@]}"
+ cat compat/matrix.md >>"$GITHUB_STEP_SUMMARY"
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ with:
+ name: hyprland-plugin-compat
+ path: compat/
+ retention-days: 90
+ - name: Commit the manifest to the ${{ env.COMPAT_BRANCH }} branch
+ if: >-
+ github.repository == 'trycua/cua' && github.ref == 'refs/heads/main' &&
+ (github.event_name == 'schedule' ||
+ (github.event_name == 'workflow_dispatch' && inputs.publish_manifest))
+ run: |
+ set -euo pipefail
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ if git fetch --quiet origin "$COMPAT_BRANCH" 2>/dev/null; then
+ git worktree add --quiet compat-branch FETCH_HEAD
+ git -C compat-branch checkout --quiet -B "$COMPAT_BRANCH"
+ else
+ git worktree add --quiet --detach compat-branch
+ git -C compat-branch checkout --quiet --orphan "$COMPAT_BRANCH"
+ git -C compat-branch rm -rfq .
+ fi
+ # Commit only when something besides the timestamp and run URL changed.
+ same=false
+ if [ -f compat-branch/compatibility.json ]; then
+ jq -S 'del(.generated_at, .run_url)' compat-branch/compatibility.json >old.json
+ jq -S 'del(.generated_at, .run_url)' compat/compatibility.json >new.json
+ cmp -s old.json new.json && same=true
+ fi
+ if [ "$same" = true ]; then
+ echo "Manifest unchanged; nothing to commit."
+ exit 0
+ fi
+ cp compat/compatibility.json compat/matrix.md compat-branch/
+ cp "$REQUALIFY/COMPAT-BRANCH.md" compat-branch/README.md
+ git -C compat-branch add compatibility.json matrix.md README.md
+ git -C compat-branch commit --quiet -m "Hyprland plugin requalification: $(date -u +%Y-%m-%dT%H:%MZ)" \
+ -m "Run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+ git -C compat-branch push --quiet origin "HEAD:refs/heads/$COMPAT_BRANCH"
+ - name: Open or update the tracking issue
+ if: steps.merge.outputs.failed == 'true' || needs.requalify.result == 'failure' || needs.requalify.result == 'cancelled'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ # Pull requests exercise the reporter without filing anything.
+ DRY_RUN: ${{ github.event_name == 'pull_request' && '1' || '0' }}
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+ REQUALIFY_RESULT: ${{ needs.requalify.result }}
+ run: |
+ if [ ! -s compat/failures.md ]; then
+ echo "- A requalify job ended $REQUALIFY_RESULT before writing a result; see the run logs." >compat/failures.md
+ fi
+ "$REQUALIFY/report_failure.sh" "$RUN_URL" compat/failures.md compat/matrix.md
+ echo "::error::Hyprland plugin requalification failed; see the matrix in the summary."
+ exit 1
diff --git a/libs/cua-driver/hyprland-plugin/README.md b/libs/cua-driver/hyprland-plugin/README.md
index 3ed42fd71f..74d25736a6 100644
--- a/libs/cua-driver/hyprland-plugin/README.md
+++ b/libs/cua-driver/hyprland-plugin/README.md
@@ -116,6 +116,18 @@ Rebuild it against the upgraded Hyprland package instead. The local Arch recipe
in `packaging/arch/` installs a version-pinned development package without
changing Hyprland configuration.
+### Requalification for each Hyprland build
+
+[`nightly-hyprland-plugin-requalify.yml`](../../../.github/workflows/nightly-hyprland-plugin-requalify.yml)
+runs daily and can also be dispatched by hand. It detects new Hyprland builds
+in Arch and in the Omarchy edge, rc and stable channels, keyed by package
+version and package hash. For each new build it rebuilds this plugin against
+the exact headers in an Arch container, runs CTest, records the header hashes,
+and loads the module into a headless Hyprland for a window-targeted input
+smoke. The results go to the `hyprland-plugin-compat` branch as
+`compatibility.json`. See [`requalify/COMPAT-BRANCH.md`](requalify/COMPAT-BRANCH.md).
+This is CI evidence. It is not a kit or native certification.
+
## Load, inspect, and unload
Loading is always an explicit operator action. For a local build, substitute
diff --git a/libs/cua-driver/hyprland-plugin/requalify/COMPAT-BRANCH.md b/libs/cua-driver/hyprland-plugin/requalify/COMPAT-BRANCH.md
new file mode 100644
index 0000000000..9953571c5e
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/COMPAT-BRANCH.md
@@ -0,0 +1,48 @@
+# Cua Hyprland plugin compatibility manifest
+
+This branch is written by the
+[`nightly-hyprland-plugin-requalify.yml`](https://github.com/trycua/cua/blob/main/.github/workflows/nightly-hyprland-plugin-requalify.yml)
+workflow ([#4909](https://github.com/trycua/cua/issues/4909)). Do not edit it by hand.
+
+- `compatibility.json` is the machine-readable manifest:
+ <https://raw.githubusercontent.com/trycua/cua/hyprland-plugin-compat/compatibility.json>
+- `matrix.md` is the same data as a table.
+
+Each daily run reads the tracked packages in Arch `core`/`extra` and in Omarchy
+edge, rc and stable. The tracked packages are `hyprland`, `aquamarine`,
+`hyprutils`, `hyprlang`, `hyprcursor`, `hyprgraphics`, `glibc`, `gcc`,
+`libgcc`, `libstdc++`, `libxkbcommon` and `wayland`. A **Hyprland build** is
+identified by `abi_key`, a hash over each package's version *and* package
+SHA-256. A same-version Arch rebuild therefore gets a new key. For every new
+key, the run takes each plugin source (`main`, the latest Driver tag, and the
+Driver source each Omarchy channel packages) and does the following:
+
+- builds it in an Arch container against that channel's exact packages and headers;
+- runs CTest;
+- loads the module into a headless Hyprland session;
+- runs a window-targeted background input smoke over `cua-input-v3`.
+
+## Reading it
+
+- `channels.<channel>.abi_key` is the channel's current Hyprland build.
+- `current.<channel>.<plugin ref>.status` is the result for that build and plugin source. For example, `current["omarchy-edge"]["cua-driver-rs-v0.32.0"].status` is the result for the source behind Omarchy's `cua-hyprland-plugin 0.32.0-*`.
+- `channels.<channel>.omarchy_plugin.installable` is `false` when the channel's packages no longer satisfy the exact pins of Omarchy's packaged plugin, so `pacman -Syu` would refuse the update.
+- `entries[]` holds the full records:
+ - Hyprland package and header versions;
+ - the Hyprland binary SHA-256 and header-inventory SHA-256 (the same method as `profile_verify.py`);
+ - the GCC version;
+ - runtime packages;
+ - the plugin tree, refs and module SHA-256;
+ - per-check results.
+
+Statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `pass` | Built against the exact headers, CTest passed, loaded with a matching ABI, and the input smoke passed. |
+| `build-only` | Built and CTest passed, but no headless session was available on the runner. |
+| `fail` | A build, test, load or smoke step failed. A tracking issue is opened. |
+
+This is CI requalification, not native certification. It does not produce a
+package or kit. A packaged plugin still needs a reviewed profile and kit
+(docs/omarchy-edge-20261004-validation.md, "Rebuild and requalification").
diff --git a/libs/cua-driver/hyprland-plugin/requalify/channels.py b/libs/cua-driver/hyprland-plugin/requalify/channels.py
new file mode 100644
index 0000000000..7755541358
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/channels.py
@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""Detect Hyprland builds that need plugin requalification, and plan the matrix.
+
+A build is keyed by every tracked package's version and package SHA-256, so a
+same-version Arch rebuild (a pkgrel bump, or a rebuilt file under the same
+version) is a new build. A matching Hyprland version string alone is not
+sufficient (docs/omarchy-edge-20261004-validation.md).
+
+This only reads public package databases and the Hyprland release API. It
+never publishes anything.
+"""
+
+import argparse
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tarfile
+import time
+import urllib.error
+import urllib.request
+
+# The plugin's exact ABI pins as Omarchy packages them (omacom/omarchy-pkgs#772),
+# plus the compiler. A change to any of them can break the module ABI or make
+# the pinned package uninstallable.
+TRACKED = (
+ "hyprland", "aquamarine", "hyprutils", "hyprlang", "hyprcursor", "hyprgraphics",
+ "glibc", "gcc", "libgcc", "libstdc++", "libxkbcommon", "wayland",
+)
+ARCH_MIRROR = "https://geo.mirror.pkgbuild.com/$repo/os/$arch"
+
+# Repository order matters: rc and stable list [omarchy] first, edge last
+# (omacom/omarchy default/pacman/pacman-*.conf).
+CHANNELS = {
+ "arch": {
+ "description": "Arch Linux core/extra (live)",
+ "repos": [("core", ARCH_MIRROR), ("extra", ARCH_MIRROR)],
+ },
+ "omarchy-edge": {
+ "description": "Omarchy edge (mirror.omarchy.org + pkgs.omarchy.org/edge)",
+ "repos": [("core", "https://mirror.omarchy.org/$repo/os/$arch"),
+ ("extra", "https://mirror.omarchy.org/$repo/os/$arch"),
+ ("omarchy", "https://pkgs.omarchy.org/edge/$arch")],
+ },
+ "omarchy-rc": {
+ "description": "Omarchy rc (rc-mirror.omarchy.org + pkgs.omarchy.org/rc)",
+ "repos": [("omarchy", "https://pkgs.omarchy.org/rc/$arch"),
+ ("core", "https://rc-mirror.omarchy.org/$repo/os/$arch"),
+ ("extra", "https://rc-mirror.omarchy.org/$repo/os/$arch")],
+ },
+ "omarchy-stable": {
+ "description": "Omarchy stable (stable-mirror.omarchy.org + pkgs.omarchy.org/stable)",
+ "repos": [("omarchy", "https://pkgs.omarchy.org/stable/$arch"),
+ ("core", "https://stable-mirror.omarchy.org/$repo/os/$arch"),
+ ("extra", "https://stable-mirror.omarchy.org/$repo/os/$arch")],
+ },
+}
+PLUGIN_PACKAGE = "cua-hyprland-plugin"
+DRIVER_PACKAGE = "cua-driver-bin"
+HYPRLAND_RELEASES = "https://api.github.com/repos/hyprwm/Hyprland/releases?per_page=10"
+STABLE_TAG = re.compile(r"v?([0-9]+\.[0-9]+\.[0-9]+)")
+
+
+def repo_url(server, repo, arch="x86_64"):
+ return server.replace("$repo", repo).replace("$arch", arch)
+
+
+def fetch(url, attempts=5, delay=2.0, opener=urllib.request.urlopen, sleep=time.sleep, headers=None):
+ """GET with exponential backoff on network errors, 429 and 5xx."""
+ request = urllib.request.Request(url, headers={"User-Agent": "cua-hyprland-requalify", **(headers or {})})
+ for attempt in range(attempts):
+ try:
+ with opener(request, timeout=60) as response:
+ return response.read()
+ except urllib.error.HTTPError as error:
+ retryable = error.code in (403, 429) or error.code >= 500
+ if not retryable or attempt == attempts - 1:
+ raise
+ except (urllib.error.URLError, TimeoutError, ConnectionError):
+ if attempt == attempts - 1:
+ raise
+ sleep(delay * (2 ** attempt))
+ raise RuntimeError("unreachable")
+
+
+ZSTD_MAGIC = b"\x28\xb5\x2f\xfd"
+
+
+def decompress(data):
+ """Pacman databases are gzip (Arch) or zstd (Omarchy); tarfile reads only the former."""
+ if not data.startswith(ZSTD_MAGIC):
+ return data
+ try:
+ from compression import zstd # Python 3.14+
+ return zstd.decompress(data)
+ except ImportError:
+ return subprocess.run(["zstd", "-dc"], input=data, capture_output=True, check=True).stdout
+
+
+def parse_db(data):
+ """Return {name: {version, sha256, builddate, depends}} from a pacman sync database."""
+ data = decompress(data)
+ packages = {}
+ with tarfile.open(fileobj=io.BytesIO(data), mode="r:*") as archive:
+ for member in archive:
+ if not member.isfile() or not member.name.endswith("/desc"):
+ continue
+ fields, key = {}, None
+ for line in archive.extractfile(member).read().decode().splitlines():
+ if line.startswith("%") and line.endswith("%"):
+ key = line.strip("%")
+ fields[key] = []
+ elif line and key:
+ fields[key].append(line)
+ name = fields.get("NAME", [None])[0]
+ if not name:
+ continue
+ packages[name] = {
+ "version": fields["VERSION"][0],
+ "sha256": fields.get("SHA256SUM", [""])[0],
+ "builddate": int(fields.get("BUILDDATE", ["0"])[0]),
+ "depends": fields.get("DEPENDS", []),
+ "filename": fields.get("FILENAME", [""])[0],
+ }
+ return packages
+
+
+def exact_pins(depends):
+ """Exact name=version pins from a DEPENDS list (no ranges, no soname provides)."""
+ pins = {}
+ for entry in depends:
+ match = re.fullmatch(r"([^<>=]+)=([^<>=]+)", entry)
+ if match and ".so" not in match[1]:
+ pins[match[1]] = match[2]
+ return pins
+
+
+def resolve_channel(name, databases):
+ """First repository in pacman order wins, as pacman resolves it."""
+ resolved = {}
+ for repo, _ in CHANNELS[name]["repos"]:
+ for package, info in databases[repo].items():
+ if package in TRACKED and package not in resolved:
+ resolved[package] = dict(version=info["version"], sha256=info["sha256"], repo=repo)
+ missing = sorted(set(TRACKED) - set(resolved))
+ if missing:
+ raise ValueError(f"{name}: tracked packages missing: {', '.join(missing)}")
+ entry = {"packages": {package: resolved[package] for package in TRACKED}}
+ omarchy = databases.get("omarchy", {})
+ if PLUGIN_PACKAGE in omarchy:
+ plugin = omarchy[PLUGIN_PACKAGE]
+ pins = exact_pins(plugin["depends"])
+ # Pins the channel no longer satisfies make `pacman -Syu` refuse the update.
+ broken = {name: {"pinned": version, "channel": resolved[name]["version"]}
+ for name, version in sorted(pins.items())
+ if name in resolved and resolved[name]["version"] != version}
+ entry["omarchy_plugin"] = {"version": plugin["version"], "pins": pins,
+ "installable": not broken, "broken_pins": broken}
+ if DRIVER_PACKAGE in omarchy:
+ entry["omarchy_driver"] = {"version": omarchy[DRIVER_PACKAGE]["version"]}
+ # An [omarchy] override of a tracked package needs that repository in the build.
+ entry["needs_omarchy_repo"] = any(info["repo"] == "omarchy" for info in resolved.values())
+ entry["abi_key"] = abi_key(entry["packages"])
+ return entry
+
+
+def abi_key(packages):
+ identity = {name: [info["version"], info["sha256"]] for name, info in sorted(packages.items())}
+ return hashlib.sha256(json.dumps(identity, sort_keys=True).encode()).hexdigest()[:16]
+
+
+def header_version(package_version):
+ """'0.56.2-4' -> '0.56.2' (epoch and pkgrel removed)."""
+ return package_version.split(":", 1)[-1].rsplit("-", 1)[0]
+
+
+def version_tuple(value):
+ return tuple(int(part) for part in value.split("."))
+
+
+def detect(channels=None, fetcher=fetch, token=None):
+ snapshot = {"schema": 1, "detected_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "tracked": list(TRACKED), "channels": {}, "errors": {}}
+ for name in channels or CHANNELS:
+ try:
+ databases = {repo: parse_db(fetcher(repo_url(server, repo) + f"/{repo}.db"))
+ for repo, server in CHANNELS[name]["repos"]}
+ snapshot["channels"][name] = resolve_channel(name, databases)
+ except Exception as error: # A down mirror is recorded, not fatal for other channels.
+ snapshot["errors"][name] = f"{type(error).__name__}: {error}"
+ try:
+ headers = {"Authorization": f"Bearer {token}"} if token else None
+ releases = json.loads(fetcher(HYPRLAND_RELEASES, headers=headers) if headers else fetcher(HYPRLAND_RELEASES))
+ stable = [r for r in releases if not r.get("draft") and not r.get("prerelease")
+ and STABLE_TAG.fullmatch(r.get("tag_name", ""))]
+ if stable:
+ latest = max(stable, key=lambda r: version_tuple(STABLE_TAG.fullmatch(r["tag_name"])[1]))
+ snapshot["upstream"] = {"tag": latest["tag_name"], "version": STABLE_TAG.fullmatch(latest["tag_name"])[1],
+ "published_at": latest.get("published_at"), "url": latest.get("html_url")}
+ except Exception as error:
+ snapshot["errors"]["hyprland-github"] = f"{type(error).__name__}: {error}"
+ return snapshot
+
+
+def versions(channel_info):
+ return {name: info["version"] for name, info in channel_info["packages"].items()}
+
+
+def plan(snapshot, sources, manifest=None, force=False):
+ """Build matrix: one job per (distinct ABI key, distinct plugin tree).
+
+ A combination that already passed is skipped unless forced. build-only and
+ fail are retried, so a persistent failure is reported on every run and a
+ transient one clears itself. Channels sharing an ABI key share one build.
+ """
+ done = {}
+ for entry in (manifest or {}).get("entries", []):
+ if entry.get("status") == "pass":
+ done[(entry["abi_key"], entry["plugin"]["tree"])] = entry["status"]
+ builds = {}
+ for channel, info in sorted(snapshot["channels"].items()):
+ build = builds.setdefault(info["abi_key"], {
+ "abi_key": info["abi_key"], "channels": [], "channel": channel,
+ "hyprland": info["packages"]["hyprland"]["version"],
+ "needs_omarchy_repo": info["needs_omarchy_repo"], "expected_packages": versions(info)})
+ build["channels"].append(channel)
+ # Prefer a configuration that does not need the Omarchy repository.
+ if build["needs_omarchy_repo"] and not info["needs_omarchy_repo"]:
+ build.update(channel=channel, needs_omarchy_repo=False, expected_packages=versions(info))
+ trees = {}
+ for source in sources:
+ trees.setdefault(source["tree"], {**source, "refs": []})["refs"].append(source["ref"])
+ include = []
+ for build in builds.values():
+ for tree in trees.values():
+ if not force and (build["abi_key"], tree["tree"]) in done:
+ continue
+ include.append({
+ "id": f"{build['abi_key']}-{tree['tree'][:12]}",
+ "abi_key": build["abi_key"], "channel": build["channel"], "channels": build["channels"],
+ "hyprland": build["hyprland"], "needs_omarchy_repo": build["needs_omarchy_repo"],
+ "expected_packages": build["expected_packages"],
+ "ref": tree["ref"], "refs": tree["refs"], "tree": tree["tree"], "commit": tree.get("commit", ""),
+ "driver_version": tree.get("driver_version", ""),
+ })
+ return include
+
+
+def upstream_status(snapshot):
+ """Is upstream Hyprland ahead of every packaged channel?"""
+ upstream = snapshot.get("upstream")
+ if not upstream:
+ return None
+ packaged = [header_version(c["packages"]["hyprland"]["version"]) for c in snapshot["channels"].values()]
+ ahead = all(version_tuple(upstream["version"]) > version_tuple(v) for v in packaged) if packaged else True
+ return {**upstream, "ahead_of_packages": ahead}
+
+
+PLUGIN_PATH = "libs/cua-driver/hyprland-plugin"
+NON_BUILD = re.compile(r"(requalify|docs)/|[^/]+\.md$")
+DRIVER_TAG = re.compile(r"cua-driver-rs-v([0-9]+\.[0-9]+\.[0-9]+)")
+
+
+def git(repo, *args):
+ return subprocess.check_output(["git", "-C", str(repo), *args], text=True).strip()
+
+
+def plugin_sources(repo, snapshot, head="HEAD"):
+ """main, the latest stable Driver tag, and each Omarchy channel's packaged Driver source."""
+ tags = [t for t in git(repo, "tag", "-l", "cua-driver-rs-v*").splitlines() if DRIVER_TAG.fullmatch(t)]
+ tags.sort(key=lambda t: version_tuple(DRIVER_TAG.fullmatch(t)[1]))
+ wanted = [("main", head, "")]
+ if tags:
+ wanted.append((tags[-1], tags[-1], DRIVER_TAG.fullmatch(tags[-1])[1]))
+ for channel in snapshot["channels"].values():
+ plugin = channel.get("omarchy_plugin")
+ if plugin:
+ version = header_version(plugin["version"])
+ tag = f"cua-driver-rs-v{version}"
+ if tag in tags:
+ wanted.append((tag, tag, version))
+ sources, seen = [], set()
+ for label, ref, version in wanted:
+ if label in seen:
+ continue
+ seen.add(label)
+ commit = git(repo, "rev-parse", f"{ref}^{{commit}}")
+ sources.append({"ref": label, "commit": commit, "driver_version": version,
+ "tree": source_id(repo, commit)})
+ return sources
+
+
+def source_id(repo, commit):
+ """Content ID of the plugin's build inputs at a commit.
+
+ Documentation and this requalification tooling (which lives under the
+ plugin directory) do not change the module, so they do not make a new
+ plugin build.
+ """
+ listing = git(repo, "ls-tree", "-r", commit, "--", PLUGIN_PATH).splitlines()
+ inputs = [line for line in listing if not NON_BUILD.match(line.split("\t", 1)[1][len(PLUGIN_PATH) + 1:])]
+ return hashlib.sha1("\n".join(inputs).encode()).hexdigest()
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ sub = parser.add_subparsers(dest="command", required=True)
+ d = sub.add_parser("detect", help="write a snapshot of every channel's tracked packages")
+ d.add_argument("--output", type=Path, required=True)
+ d.add_argument("--channel", action="append", choices=sorted(CHANNELS))
+ s = sub.add_parser("sources", help="write the plugin sources to build")
+ s.add_argument("--snapshot", type=Path, required=True)
+ s.add_argument("--repo", type=Path, default=Path("."))
+ s.add_argument("--head", default="HEAD")
+ s.add_argument("--output", type=Path, required=True)
+ p = sub.add_parser("plan", help="write the build matrix for new combinations")
+ p.add_argument("--snapshot", type=Path, required=True)
+ p.add_argument("--sources", type=Path, required=True, help="JSON list of {ref, tree, driver_version}")
+ p.add_argument("--manifest", type=Path, help="previous compatibility manifest")
+ p.add_argument("--force", action="store_true")
+ p.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ if args.command == "detect":
+ snapshot = detect(args.channel, token=os.environ.get("GITHUB_TOKEN"))
+ snapshot["upstream"] = upstream_status(snapshot)
+ args.output.write_text(json.dumps(snapshot, indent=2, sort_keys=True) + "\n")
+ for name, error in snapshot["errors"].items():
+ print(f"::warning::{name}: {error}")
+ if not snapshot["channels"]:
+ sys.exit("no channel could be read")
+ elif args.command == "sources":
+ found = plugin_sources(args.repo, json.loads(args.snapshot.read_text()), args.head)
+ args.output.write_text(json.dumps(found, indent=2) + "\n")
+ for source in found:
+ print(f"{source['ref']}: {source['commit'][:12]} tree {source['tree'][:12]}")
+ else:
+ snapshot = json.loads(args.snapshot.read_text())
+ manifest = json.loads(args.manifest.read_text()) if args.manifest and args.manifest.is_file() else None
+ include = plan(snapshot, json.loads(args.sources.read_text()), manifest, args.force)
+ args.output.write_text(json.dumps({"include": include}) + "\n")
+ print(f"{len(include)} build(s) planned")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/cua-driver/hyprland-plugin/requalify/headless.py b/libs/cua-driver/hyprland-plugin/requalify/headless.py
new file mode 100644
index 0000000000..db49dc239c
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/headless.py
@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Load a built plugin into an owned headless Hyprland session and smoke-test input.
+
+Runs as an unprivileged user with XDG_RUNTIME_DIR set (qualify.py arranges it).
+Load: Hyprland starts on the container's DRM device, `hyprctl plugin load`
+must answer ok, and `hyprctl -j cua:status` must report a matching ABI, the
+input v3 state and a ready transport.
+
+Smoke: the window-targeted background input check from the Omarchy validation
+record, reduced to native Wayland clients. A holder window keeps primary focus
+while background-seat KEY input over cua-input-v3 types into a separate target
+window; the target application's own output is the oracle, and primary focus
+must not move.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import socket
+import subprocess
+import time
+
+TARGET_CLASS = "cua-requalify-target"
+HOLDER_CLASS = "cua-requalify-holder"
+# evdev codes: c u a Enter.
+KEYS = (46, 22, 30, 28)
+TYPED = "cua"
+CONFIG = """hl.config({
+ plugin = { cua = { enabled = true } },
+ input = { kb_rules = "evdev", kb_model = "pc105", kb_layout = "us",
+ kb_variant = "", kb_options = "", numlock_by_default = false },
+ ecosystem = { no_update_news = true, no_donation_nag = true },
+})
+"""
+
+
+def wait_for(check, timeout, what):
+ deadline = time.monotonic() + timeout
+ last = None
+ while time.monotonic() < deadline:
+ try:
+ value = check()
+ if value:
+ return value
+ except (subprocess.CalledProcessError, json.JSONDecodeError, KeyError, OSError) as error:
+ last = error
+ time.sleep(0.25)
+ raise TimeoutError(f"{what} (last error: {last})" if last else what)
+
+
+class Session:
+ def __init__(self, out, binary="Hyprland"):
+ self.out = out
+ self.binary = binary
+ self.process = None
+ self.instance = None
+ self.clients = []
+ self.config = out / "hyprland.lua"
+ self.config.write_text(CONFIG)
+ self.log = (out / "compositor.log").open("a")
+
+ def ctl(self, *args, timeout=10):
+ return subprocess.check_output(["hyprctl", "-i", self.instance, *args], text=True, timeout=timeout).strip()
+
+ def json(self, *args):
+ return json.loads(self.ctl("-j", *args))
+
+ def start(self):
+ env = dict(os.environ)
+ env.pop("HYPRLAND_INSTANCE_SIGNATURE", None)
+ env.pop("WAYLAND_DISPLAY", None)
+ self.process = subprocess.Popen([self.binary, "--config", str(self.config)], env=env,
+ stdout=self.log, stderr=subprocess.STDOUT)
+
+ def instance():
+ if self.process.poll() is not None:
+ raise RuntimeError(f"Hyprland exited with {self.process.returncode}")
+ listed = json.loads(subprocess.check_output(["hyprctl", "-j", "instances"], text=True, timeout=10))
+ match = [i for i in listed if i["pid"] == self.process.pid]
+ return match[0] if match else None
+
+ info = wait_for(instance, 60, "Hyprland did not register an instance")
+ self.instance, self.wayland = info["instance"], info["wl_socket"]
+ wait_for(lambda: self.json("version"), 30, "Hyprland did not answer hyprctl")
+ if not wait_for_monitors(self, 10):
+ self.ctl("output", "create", "headless", "CUA-REQUALIFY-1")
+ wait_for(lambda: self.json("monitors"), 20, "no monitor after creating a headless output")
+ return info
+
+ def spawn(self, app_id, *command):
+ env = dict(os.environ, WAYLAND_DISPLAY=self.wayland, HYPRLAND_INSTANCE_SIGNATURE=self.instance)
+ process = subprocess.Popen(["foot", f"--app-id={app_id}", "--", *command], env=env,
+ stdout=self.log, stderr=subprocess.STDOUT)
+ self.clients.append(process)
+
+ def mapped():
+ if process.poll() is not None:
+ raise RuntimeError(f"{app_id} exited with {process.returncode}")
+ found = [c for c in self.json("clients") if c.get("class") == app_id and c.get("mapped", True)]
+ return found[0] if found else None
+
+ return wait_for(mapped, 30, f"{app_id} window did not map")
+
+ def stop(self):
+ for process in self.clients:
+ if process.poll() is None:
+ process.terminate()
+ if self.process and self.process.poll() is None:
+ self.process.terminate()
+ try:
+ self.process.wait(timeout=15)
+ except subprocess.TimeoutExpired:
+ self.process.kill()
+ self.log.close()
+
+
+def wait_for_monitors(session, timeout):
+ try:
+ return wait_for(lambda: session.json("monitors"), timeout, "no monitors")
+ except TimeoutError:
+ return None
+
+
+def load(session, module):
+ answer = session.ctl("plugin", "load", str(module))
+ if answer != "ok":
+ raise RuntimeError(f"plugin load answered {answer!r}")
+ session.ctl("reload")
+ status = wait_for(lambda: (lambda s: s if s["transport"]["ready"] else None)(session.json("cua:status")),
+ 30, "cua:status transport never became ready")
+ checks = {
+ "abi_match": status["abi"]["match"] is True,
+ "input_v3_state": status.get("state") == "input_v3_candidate",
+ "transport_ready": status["transport"]["ready"] is True,
+ "compositor_epoch": status.get("compositor_epoch", 0) != 0,
+ "keyboard_layout_independent": status.get("keyboard_layout_independent") is True,
+ }
+ return status, checks
+
+
+class InputLane:
+ """Minimal cua-input-v3 client (protocol/cua-input-v3.md)."""
+
+ def __init__(self, path):
+ self.socket = socket.socket(socket.AF_UNIX, socket.SOCK_SEQPACKET)
+ self.socket.settimeout(10)
+ self.socket.connect(str(path))
+ self.sequence = 0
+ self.transcript = []
+
+ def request(self, packet):
+ self.socket.send(packet.encode())
+ reply = json.loads(self.socket.recv(4096).decode())
+ self.transcript.append({"request": packet, "reply": reply})
+ return reply
+
+ def target(self, client, capability=2):
+ return self.request(f"TARGET {client['pid']} {client['address'].removeprefix('0x')} {capability}")
+
+ def key(self, target, key, modifiers=0):
+ self.sequence += 1
+ return self.request(f"KEY {self.sequence} {target['target']} {target['revision']} {key} {modifiers}")
+
+ def close(self):
+ self.socket.close()
+
+
+def smoke(session):
+ typed = session.out / "typed.txt"
+ target = session.spawn(TARGET_CLASS, "sh", "-c", f'IFS= read -r line && printf %s "$line" > "{typed}"')
+ holder = session.spawn(HOLDER_CLASS, "sleep", "600")
+ focused = wait_for(lambda: (lambda a: a if a.get("address") == holder["address"] else None)(session.json("activewindow")),
+ 10, "the holder window did not take primary focus")
+ time.sleep(1) # Let the target's shell reach its read.
+ path = Path(os.environ["XDG_RUNTIME_DIR"]) / "hypr" / session.instance / "cua-input-v3.sock"
+ lane = InputLane(path)
+ checks, observations = {}, {}
+ try:
+ hello = lane.request("HELLO")
+ checks["hello_protocol_3"] = hello.get("ok") is True and hello.get("protocol") == 3
+ checks["claim"] = lane.request("CLAIM").get("ok") is True
+ # Informational: the plugin refuses a target whose client holds the primary
+ # seat's keyboard or pointer focus, but a headless seat has no keyboard or
+ # pointer device, so Hyprland's active window need not hold either.
+ refused = lane.target(holder)
+ observations["focused_holder_target"] = refused
+ delivered = []
+ for key in KEYS:
+ grant = lane.target(target)
+ if not grant.get("ok"):
+ raise RuntimeError(f"TARGET refused: {grant}")
+ delivered.append(lane.key(grant, key))
+ checks["keys_acknowledged"] = all(d.get("ok") and d.get("route") == "synthetic_events" for d in delivered)
+ finally:
+ lane.close()
+ try:
+ text = wait_for(lambda: typed.read_text() if typed.exists() else None, 10, "target wrote nothing")
+ except TimeoutError:
+ text = None
+ checks["application_received_text"] = text == TYPED
+ checks["primary_focus_unchanged"] = session.json("activewindow").get("address") == focused["address"]
+ return {"target": {k: target[k] for k in ("address", "pid", "class")},
+ "holder": {k: holder[k] for k in ("address", "pid", "class")},
+ "typed": text, "checks": checks, "observations": observations, "transcript": lane.transcript}
+
+
+def tail(path, lines=60):
+ try:
+ return path.read_text(errors="replace").splitlines()[-lines:]
+ except OSError:
+ return []
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--module", type=Path, required=True)
+ parser.add_argument("--out", type=Path, required=True)
+ args = parser.parse_args()
+ result = {"load": {"status": "fail"}, "smoke": {"status": "unavailable", "reason": "plugin did not load"}}
+ session = Session(args.out)
+ try:
+ try:
+ result["load"]["instance"] = session.start()
+ except Exception as error:
+ # No compositor on this runner's device is an environment limit, not a plugin failure.
+ result["load"] = {"status": "unavailable", "reason": f"headless Hyprland did not start: {error}",
+ "compositor_log_tail": tail(args.out / "compositor.log")}
+ result["smoke"]["reason"] = "no compositor"
+ return
+ try:
+ status, checks = load(session, args.module)
+ result["load"] = {"status": "pass" if all(checks.values()) else "fail",
+ "checks": checks, "cua_status": status}
+ except Exception as error:
+ result["load"] = {"status": "fail", "reason": str(error),
+ "compositor_log_tail": tail(args.out / "compositor.log")}
+ return
+ if result["load"]["status"] != "pass":
+ return
+ try:
+ evidence = smoke(session)
+ result["smoke"] = {"status": "pass" if all(evidence["checks"].values()) else "fail", **evidence}
+ except Exception as error:
+ result["smoke"] = {"status": "fail", "reason": f"{type(error).__name__}: {error}",
+ "compositor_log_tail": tail(args.out / "compositor.log")}
+ finally:
+ session.stop()
+ (args.out / "result.json").write_text(json.dumps(result, indent=2, sort_keys=True) + "\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/cua-driver/hyprland-plugin/requalify/manifest.py b/libs/cua-driver/hyprland-plugin/requalify/manifest.py
new file mode 100644
index 0000000000..b3bf40b166
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/manifest.py
@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Merge requalification results into the compatibility manifest and matrix.
+
+The manifest maps each Hyprland build (an ABI key over the tracked packages'
+versions and package hashes) and plugin source tree to a status:
+
+- pass: built against the exact headers, CTest passed, loaded into a headless
+ Hyprland session and passed the window-targeted input smoke;
+- build-only: built and CTest passed, but no headless session was available;
+- fail: any build, test, load or smoke failure.
+
+Statuses are CI requalification, not native certification or a kit.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import time
+
+SCHEMA = 1
+HISTORY_LIMIT = 200
+NOTE = ("CI requalification of the Cua Hyprland plugin per Hyprland build. Not native "
+ "certification and not a package: the reviewed kit/profile process stays the release gate.")
+
+
+def entry_from(record, run_url):
+ job, measured = record["job"], record.get("measured", {})
+ return {
+ "abi_key": job["abi_key"],
+ "channels": job["channels"],
+ "built_from_channel": job["channel"],
+ "hyprland": measured.get("hyprland", {"package_version": job["hyprland"]}),
+ "compiler": measured.get("compiler"),
+ "tracked_packages": measured.get("tracked_packages", job.get("expected_packages")),
+ "runtime": measured.get("runtime"),
+ "detection_drift": measured.get("detection_drift", {}),
+ "plugin": {"tree": job["tree"], "refs": job["refs"], "driver_version": job.get("driver_version", ""),
+ "module_sha256": record["build"].get("module_sha256"), "options": record["build"].get("options")},
+ "checks": {
+ "build": summary(record["build"]),
+ "ctest": summary(record.get("ctest", {"status": "unavailable", "reason": "not built"})),
+ "load": summary(record["load"]),
+ "smoke": summary(record["smoke"]),
+ },
+ "error": record.get("error"),
+ "status": record["status"],
+ "checked_at": record.get("finished_at"),
+ "run_url": run_url,
+ }
+
+
+def summary(check):
+ keep = ("status", "step", "reason", "total", "failed", "failures", "checks")
+ return {key: check[key] for key in keep if key in check}
+
+
+def merge(previous, snapshot, records, run_url, now=None):
+ entries = {(e["abi_key"], e["plugin"]["tree"]): e for e in (previous or {}).get("entries", [])}
+ fresh = [entry_from(record, run_url) for record in records]
+ for entry in fresh:
+ entries[(entry["abi_key"], entry["plugin"]["tree"])] = entry
+ ordered = sorted(entries.values(), key=lambda e: e.get("checked_at") or "", reverse=True)[:HISTORY_LIMIT]
+ channels = {name: {"abi_key": info["abi_key"],
+ "hyprland": info["packages"]["hyprland"]["version"],
+ "packages": {k: v["version"] for k, v in info["packages"].items()},
+ **{k: info[k] for k in ("omarchy_plugin", "omarchy_driver") if k in info}}
+ for name, info in snapshot["channels"].items()}
+ current = {}
+ for name, info in channels.items():
+ current[name] = {}
+ for entry in ordered:
+ if entry["abi_key"] == info["abi_key"]:
+ for ref in entry["plugin"]["refs"]:
+ current[name].setdefault(ref, {"status": entry["status"], "tree": entry["plugin"]["tree"],
+ "checked_at": entry["checked_at"]})
+ return {
+ "schema": SCHEMA,
+ "note": NOTE,
+ "generated_at": now or time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "run_url": run_url,
+ "tracked_packages": snapshot.get("tracked", []),
+ "channels": channels,
+ "upstream": snapshot.get("upstream"),
+ "detection_errors": snapshot.get("errors", {}),
+ "current": current,
+ "entries": ordered,
+ }, fresh
+
+
+def failures(manifest, fresh):
+ """Problems worth a tracking issue: failed builds and Omarchy pins a channel no longer satisfies."""
+ problems = []
+ for entry in fresh:
+ if entry["status"] == "fail":
+ failed = [name for name, check in entry["checks"].items() if check.get("status") == "fail"]
+ problems.append(f"- **Plugin {', '.join(entry['plugin']['refs'])}** (tree `{entry['plugin']['tree'][:12]}`) on "
+ f"Hyprland `{entry['hyprland'].get('package_version')}` ({', '.join(entry['channels'])}): "
+ f"failed {', '.join(failed) or 'setup'}"
+ + (f" ({entry['error']})" if entry.get("error") else ""))
+ for name, channel in sorted(manifest["channels"].items()):
+ plugin = channel.get("omarchy_plugin")
+ if plugin and not plugin.get("installable", True):
+ pins = ", ".join(f"{pkg} pinned {v['pinned']}, channel has {v['channel']}"
+ for pkg, v in plugin["broken_pins"].items())
+ problems.append(f"- **{name}**: Omarchy's `cua-hyprland-plugin {plugin['version']}` no longer installs ({pins}). "
+ "A rebuild against the channel's packages is needed.")
+ return problems
+
+
+ICONS = {"pass": "pass", "build-only": "build only", "fail": "**FAIL**", "unavailable": "n/a"}
+
+
+def matrix(manifest, fresh):
+ lines = [f"# Hyprland plugin requalification, {manifest['generated_at']}", "", NOTE, "",
+ "| Channel | Hyprland | ABI key | Plugin (refs) | Build | CTest | Load | Input smoke | Status |",
+ "| --- | --- | --- | --- | --- | --- | --- | --- | --- |"]
+ by_key = {}
+ for entry in manifest["entries"]:
+ by_key.setdefault(entry["abi_key"], []).append(entry)
+ for name, channel in sorted(manifest["channels"].items()):
+ for entry in by_key.get(channel["abi_key"], []) or [None]:
+ if entry is None:
+ lines.append(f"| {name} | {channel['hyprland']} | `{channel['abi_key']}` | not built | | | | | |")
+ continue
+ checks = entry["checks"]
+ ctest = checks["ctest"]
+ ctest_cell = ICONS.get(ctest.get("status"), ctest.get("status"))
+ if ctest.get("total"):
+ ctest_cell += f" ({ctest['total'] - (ctest.get('failed') or 0)}/{ctest['total']})"
+ lines.append("| " + " | ".join([
+ name, channel["hyprland"], f"`{channel['abi_key']}`",
+ f"{', '.join(entry['plugin']['refs'])} (`{entry['plugin']['tree'][:12]}`)",
+ ICONS.get(checks["build"].get("status"), "?"), ctest_cell,
+ ICONS.get(checks["load"].get("status"), "?"), ICONS.get(checks["smoke"].get("status"), "?"),
+ ICONS.get(entry["status"], entry["status"])]) + " |")
+ lines += ["", "## Header and module hashes", "",
+ "| Hyprland | Binary SHA-256 | Header inventory SHA-256 | GCC | Module SHA-256 | Plugin tree |",
+ "| --- | --- | --- | --- | --- | --- |"]
+ for entry in fresh or manifest["entries"][:10]:
+ hyprland = entry["hyprland"]
+ lines.append(f"| {hyprland.get('package_version')} | `{hyprland.get('sha256', '')}` | "
+ f"`{hyprland.get('headers_sha256', '')}` | {(entry.get('compiler') or {}).get('version', '')} | "
+ f"`{entry['plugin'].get('module_sha256') or ''}` | `{entry['plugin']['tree'][:12]}` |")
+ upstream = manifest.get("upstream")
+ if upstream:
+ state = "ahead of every packaged channel: not yet requalifiable" if upstream.get("ahead_of_packages") else "packaged"
+ lines += ["", f"Upstream Hyprland: [{upstream['tag']}]({upstream.get('url')}) ({state})."]
+ for name, error in sorted(manifest.get("detection_errors", {}).items()):
+ lines.append(f"\nDetection error, {name}: {error}")
+ for name, channel in sorted(manifest["channels"].items()):
+ plugin = channel.get("omarchy_plugin")
+ if plugin:
+ state = "installable" if plugin.get("installable", True) else "NOT installable"
+ lines.append(f"\nOmarchy `cua-hyprland-plugin {plugin['version']}` on {name}: {state}.")
+ return "\n".join(lines) + "\n"
+
+
+def load_records(directory):
+ return [json.loads(path.read_text()) for path in sorted(directory.glob("**/result.json"))
+ if path.parent.name != "session"]
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--snapshot", type=Path, required=True)
+ parser.add_argument("--results", type=Path, required=True, help="directory of downloaded result artifacts")
+ parser.add_argument("--previous", type=Path, help="previous compatibility.json")
+ parser.add_argument("--run-url", default="")
+ parser.add_argument("--out", type=Path, required=True)
+ args = parser.parse_args()
+ previous = json.loads(args.previous.read_text()) if args.previous and args.previous.is_file() else None
+ snapshot = json.loads(args.snapshot.read_text())
+ records = load_records(args.results) if args.results.is_dir() else []
+ manifest, fresh = merge(previous, snapshot, records, args.run_url)
+ args.out.mkdir(parents=True, exist_ok=True)
+ (args.out / "compatibility.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
+ (args.out / "matrix.md").write_text(matrix(manifest, fresh))
+ problems = failures(manifest, fresh)
+ if problems:
+ (args.out / "failures.md").write_text("\n".join(problems) + "\n")
+ if os.environ.get("GITHUB_OUTPUT"):
+ with open(os.environ["GITHUB_OUTPUT"], "a") as handle:
+ handle.write(f"failed={'true' if problems else 'false'}\nbuilt={len(fresh)}\n")
+ print(f"{len(fresh)} new result(s), {len(problems)} problem(s)")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/cua-driver/hyprland-plugin/requalify/qualify.py b/libs/cua-driver/hyprland-plugin/requalify/qualify.py
new file mode 100644
index 0000000000..eb99a33a0b
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/qualify.py
@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Build and requalify one plugin source against one channel's exact Hyprland.
+
+Runs as root inside a disposable Arch container (see the requalify workflow).
+It installs the channel's packages, records their identity and header hashes,
+builds the plugin with the production options against those headers, runs the
+CTest suite, and then hands a headless Hyprland session to headless.py as an
+unprivileged user when a DRM device is present.
+
+The result is CI requalification evidence for one build. It is not native
+certification, and nothing here publishes or installs a package elsewhere.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE.parent / "packaging" / "release"))
+
+import channels # noqa: E402
+
+# The production package's options (packaging/release/profile_verify.py OPTIONS).
+BUILD_OPTIONS = {"CUA_HYPRLAND_INPUT": "ON", "CUA_HYPRLAND_TEST_INPUT": "OFF", "CUA_HYPRLAND_INPUT_TRACE": "OFF"}
+# make: the CMake API probe test configures a nested project with the default generator.
+BUILD_PACKAGES = ("hyprland", "gcc", "cmake", "ninja", "make", "pkgconf", "binutils", "python", "openssl",
+ "libxkbcommon", "xkeyboard-config")
+# The headless session's native Wayland clients and font.
+SESSION_PACKAGES = ("foot", "ttf-dejavu", "mesa")
+USER, UID = "cua", 1000
+
+
+def sha256_file(path):
+ return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def run(command, log=None, check=True, timeout=1800, **kwargs):
+ """Run a command, appending its output to log; return (code, output)."""
+ started = time.monotonic()
+ result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+ timeout=timeout, **kwargs)
+ if log:
+ with open(log, "a") as handle:
+ handle.write(f"$ {' '.join(map(str, command))} ({time.monotonic() - started:.1f}s, exit {result.returncode})\n")
+ handle.write(result.stdout)
+ if check and result.returncode:
+ raise subprocess.CalledProcessError(result.returncode, command, result.stdout)
+ return result.returncode, result.stdout
+
+
+def pacman_conf(channel, with_omarchy):
+ lines = ["[options]", "HoldPkg = pacman glibc", "Architecture = auto", "ParallelDownloads = 5",
+ "DisableSandbox", "SigLevel = Required DatabaseOptional", "LocalFileSigLevel = Optional", ""]
+ for repo, server in channels.CHANNELS[channel]["repos"]:
+ if repo == "omarchy" and not with_omarchy:
+ continue
+ lines += [f"[{repo}]", f"Server = {server}", ""]
+ return "\n".join(lines)
+
+
+def setup_pacman(job, log):
+ with_omarchy = bool(job.get("needs_omarchy_repo"))
+ Path("/etc/pacman.conf").write_text(pacman_conf(job["channel"], with_omarchy))
+ # Drop the bootstrap's Arch databases: pacman's If-Modified-Since would keep
+ # a newer Arch database over an older channel mirror's (rc, stable).
+ for database in Path("/var/lib/pacman/sync").glob("*"):
+ database.unlink()
+ run(["pacman-key", "--init"], log)
+ run(["pacman-key", "--populate", "archlinux"], log)
+ if with_omarchy:
+ # Trust bootstrap over HTTPS from the channel's own repository, as a
+ # fresh Omarchy install does; this build is evidence, not a package.
+ server = dict(channels.CHANNELS[job["channel"]]["repos"])["omarchy"]
+ url = channels.repo_url(server, "omarchy")
+ database = channels.parse_db(channels.fetch(url + "/omarchy.db"))
+ keyring = database["omarchy-keyring"]["filename"]
+ run(["pacman", "-U", "--noconfirm", f"{url}/{keyring}"], log)
+ run(["pacman-key", "--populate", "omarchy"], log)
+ for attempt in range(3):
+ # -yy forces fresh databases; -uu lets an older channel downgrade the bootstrap.
+ code, _ = run(["pacman", "-Syyuu", "--noconfirm", "--needed", *BUILD_PACKAGES, *SESSION_PACKAGES],
+ log, check=False)
+ if code == 0:
+ return
+ time.sleep(10 * (attempt + 1))
+ raise RuntimeError("pacman could not install the channel's packages")
+
+
+def installed(name):
+ return subprocess.check_output(["pacman", "-Q", name], text=True).split()[1]
+
+
+def measure(job):
+ """Identity of the installed compositor, headers, compiler and runtime."""
+ import profile_measure
+ import profile_verify as verify
+ gxx = Path("/usr/bin/g++")
+ macros = subprocess.check_output([str(gxx), "-dM", "-E", "-x", "c++", "-"], input="", text=True)
+ compiler = re.search(r'^#define __VERSION__ "([^"]+)"$', macros, re.MULTILINE)[1]
+ libraries = profile_measure.compositor_libraries()
+ packages = {name: installed(name) for name in channels.TRACKED}
+ expected = job.get("expected_packages") or {}
+ drift = {name: {"detected": version, "installed": packages[name]}
+ for name, version in sorted(expected.items()) if packages.get(name) != version}
+ return {
+ "hyprland": {
+ "package_version": packages["hyprland"],
+ "header_version": verify.run(str(verify.PKGCONF), "--modversion", "hyprland", extra_env=verify.PKGCONF_ENV),
+ "headers_sha256": verify.header_inventory_sha256(),
+ "sha256": sha256_file("/usr/bin/Hyprland"),
+ },
+ "compiler": {"version": compiler, "sha256": sha256_file(gxx)},
+ "tracked_packages": packages,
+ "runtime": {"basename": libraries["libstdc++.so.6"].name,
+ "sha256": sha256_file(libraries["libstdc++.so.6"]),
+ "packages": profile_measure.owner_versions(set(libraries.values()))},
+ "detection_drift": drift,
+ }
+
+
+def build(source, out, header_version):
+ build_dir = out / "build"
+ log = out / "build.log"
+ options = [f"-D{key}={value}" for key, value in BUILD_OPTIONS.items()]
+ code, _ = run(["cmake", "-S", str(source), "-B", str(build_dir), "-G", "Ninja", "-DCMAKE_BUILD_TYPE=Release",
+ "-DCMAKE_CXX_COMPILER=/usr/bin/g++", "-DBUILD_TESTING=ON",
+ f"-DCUA_HYPRLAND_EXPECTED_VERSION={header_version}", *options], log, check=False)
+ if code:
+ return {"status": "fail", "step": "configure", "log": log.name}, None
+ code, _ = run(["cmake", "--build", str(build_dir), "--parallel", str(os.cpu_count() or 2)], log, check=False)
+ module = build_dir / "cua-hyprland-plugin.so"
+ if code or not module.is_file():
+ return {"status": "fail", "step": "compile", "log": log.name}, None
+ return {"status": "pass", "module_sha256": sha256_file(module), "options": BUILD_OPTIONS, "log": log.name}, module
+
+
+def ctest(out):
+ log = out / "ctest.log"
+ code, output = run(["ctest", "--test-dir", str(out / "build"), "--output-on-failure", "--no-tests=error",
+ "--timeout", "120"], log, check=False)
+ # CTest omits the failed count when nothing failed: "100% tests passed out of 20".
+ summary = re.search(r"(\d+)% tests passed(?:, (\d+) tests? failed)? out of (\d+)", output)
+ total = int(summary[3]) if summary else 0
+ failed = int(summary[2] or 0) if summary else None
+ failures = re.findall(r"^\s*\d+ - (\S+) \(", output, re.MULTILINE)
+ return {"status": "pass" if code == 0 and total else "fail", "total": total,
+ "failed": failed, "failures": failures, "log": log.name}
+
+
+def drm_cards():
+ return sorted(str(path) for path in Path("/dev/dri").glob("card*")) if Path("/dev/dri").is_dir() else []
+
+
+def session(module, out):
+ """Load and smoke in a headless Hyprland session as an unprivileged user."""
+ cards = drm_cards()
+ if not cards:
+ reason = "no DRM device in the container (vkms unavailable on this runner)"
+ return {"status": "unavailable", "reason": reason}, {"status": "unavailable", "reason": reason}
+ if subprocess.run(["id", USER], capture_output=True).returncode:
+ run(["useradd", "-m", "-u", str(UID), "-G", "video,input", USER])
+ runtime = Path(f"/run/user/{UID}")
+ runtime.mkdir(parents=True, exist_ok=True)
+ shutil.chown(runtime, USER, USER)
+ runtime.chmod(0o700)
+ for node in Path("/dev/dri").iterdir():
+ node.chmod(0o666)
+ # The workflow mounts the host's /run/udev read-only, so libudev sees the vkms device's properties.
+ session_dir = out / "session"
+ session_dir.mkdir(exist_ok=True)
+ shutil.chown(session_dir, USER, USER)
+ plugin = session_dir / "cua-hyprland-plugin.so"
+ shutil.copy2(module, plugin)
+ env = {"PATH": "/usr/bin", "HOME": f"/home/{USER}", "XDG_RUNTIME_DIR": str(runtime),
+ "LIBSEAT_BACKEND": "noop", "AQ_DRM_DEVICES": cards[0], "LANG": "C.UTF-8"}
+ command = ["runuser", "-u", USER, "--", "env", *[f"{k}={v}" for k, v in env.items()],
+ sys.executable, str(HERE / "headless.py"), "--module", str(plugin), "--out", str(session_dir)]
+ code, _ = run(command, out / "session.log", check=False, timeout=600)
+ result_path = session_dir / "result.json"
+ if not result_path.is_file():
+ failure = {"status": "fail", "reason": f"headless runner exited {code} without a result"}
+ return failure, {"status": "unavailable", "reason": "session did not start"}
+ result = json.loads(result_path.read_text())
+ return result["load"], result["smoke"]
+
+
+def overall(record):
+ build_ok = record["build"]["status"] == "pass" and record.get("ctest", {}).get("status") == "pass"
+ if not build_ok or "fail" in (record["load"]["status"], record["smoke"]["status"]):
+ return "fail"
+ if record["load"]["status"] == "pass" and record["smoke"]["status"] == "pass":
+ return "pass"
+ return "build-only"
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--job", type=Path, required=True, help="one matrix entry (JSON)")
+ parser.add_argument("--source", type=Path, required=True, help="plugin source tree to build")
+ parser.add_argument("--out", type=Path, required=True)
+ parser.add_argument("--skip-session", action="store_true")
+ args = parser.parse_args()
+ job = json.loads(args.job.read_text())
+ args.out.mkdir(parents=True, exist_ok=True)
+ record = {"schema": 1, "job": job, "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
+ unavailable = {"status": "unavailable", "reason": "not reached"}
+ record.update(build={"status": "fail", "step": "setup"}, load=dict(unavailable), smoke=dict(unavailable))
+ try:
+ setup_pacman(job, args.out / "pacman.log")
+ record["measured"] = measure(job)
+ record["build"], module = build(args.source, args.out, record["measured"]["hyprland"]["header_version"])
+ if module:
+ record["ctest"] = ctest(args.out)
+ if args.skip_session:
+ record["load"] = record["smoke"] = {"status": "unavailable", "reason": "session skipped"}
+ else:
+ record["load"], record["smoke"] = session(module, args.out)
+ except Exception as error: # Recorded as a failure of this build, never swallowed.
+ record["error"] = f"{type(error).__name__}: {error}"
+ record["status"] = overall(record)
+ record["finished_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+ (args.out / "result.json").write_text(json.dumps(record, indent=2, sort_keys=True) + "\n")
+ print(json.dumps({k: record[k] for k in ("status", "build", "load", "smoke")}, indent=2))
+ for path in (args.out / "build").glob("**/*"):
+ if path.is_file() and path.suffix in (".o", ".a"):
+ path.unlink()
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/libs/cua-driver/hyprland-plugin/requalify/report_failure.sh b/libs/cua-driver/hyprland-plugin/requalify/report_failure.sh
new file mode 100755
index 0000000000..5280938c74
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/report_failure.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Open or update ONE tracking issue for a failed Hyprland plugin requalification.
+#
+# report_failure.sh <run url> <failures.md> [matrix.md]
+#
+# The issue is keyed by its title and the `hyprland-requalify` label: an open
+# one gets a comment, otherwise a new one is opened. A later passing run does
+# not close it; whoever fixes the cause does. Needs gh with GH_TOKEN
+# (issues: write) and GH_REPO or a checkout. DRY_RUN=1 prints the gh calls.
+set -euo pipefail
+url="${1:?run url}" failures="${2:?failures file}" matrix="${3:-}"
+title="Hyprland plugin requalification failing"
+label=hyprland-requalify
+gh_() { if [ "${DRY_RUN:-0}" = 1 ]; then printf 'gh'; printf ' %q' "$@"; printf '\n'; else gh "$@"; fi; }
+
+body="Requalification run: $url
+
+$(cat "$failures")"
+if [ -n "$matrix" ] && [ -f "$matrix" ]; then
+ body="$body
+
+<details><summary>Matrix</summary>
+
+$(cat "$matrix")
+</details>"
+fi
+
+existing=""
+if [ "${DRY_RUN:-0}" != 1 ]; then
+ existing="$(gh issue list --state open --label "$label" --search "\"$title\" in:title" \
+ --json number,title --jq ".[] | select(.title == \"$title\") | .number" 2>/dev/null | head -1 || true)"
+fi
+if [ -n "$existing" ]; then
+ gh_ issue comment "$existing" --body "$body"
+ echo "commented on #$existing"
+else
+ gh_ label create "$label" --color B60205 --description "Hyprland plugin requalification failures" 2>/dev/null || true
+ gh_ issue create --title "$title" --label "$label" --body "$body
+
+This issue collects failed requalification runs (one issue, a comment per failing run). Refs #4909."
+ echo "opened an issue"
+fi
diff --git a/libs/cua-driver/hyprland-plugin/requalify/test_requalify.py b/libs/cua-driver/hyprland-plugin/requalify/test_requalify.py
new file mode 100644
index 0000000000..5d0659f493
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/requalify/test_requalify.py
@@ -0,0 +1,442 @@
+"""Unit and dry-run tests for the Hyprland plugin requalification automation."""
+
+import io
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import unittest
+from unittest import mock
+import urllib.error
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[3]
+sys.path.insert(0, str(HERE))
+
+import channels # noqa: E402
+import headless # noqa: E402
+import manifest # noqa: E402
+import qualify # noqa: E402
+
+EDGE_PINS = {"hyprland": "0.56.2-4", "aquamarine": "0.15.1-1", "glibc": "2.44-1", "hyprcursor": "0.1.13-7",
+ "hyprgraphics": "0.5.1-4", "hyprlang": "0.6.8-5", "hyprutils": "0.14.2-1", "libgcc": "16.2.1-1",
+ "libstdc++": "16.2.1-1", "libxkbcommon": "1.13.2-1", "wayland": "1.26.0-1"}
+
+
+def desc(name, version, sha="0" * 64, depends=(), filename=None):
+ lines = ["%FILENAME%", filename or f"{name}-{version}-x86_64.pkg.tar.zst", "", "%NAME%", name, "",
+ "%VERSION%", version, "", "%SHA256SUM%", sha, "", "%BUILDDATE%", "1760000000", ""]
+ if depends:
+ lines += ["%DEPENDS%", *depends, ""]
+ return "\n".join(lines) + "\n"
+
+
+def database(packages):
+ """A gzip pacman sync database from {name: (version, sha[, depends])}."""
+ buffer = io.BytesIO()
+ with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
+ for name, spec in packages.items():
+ version, sha = spec[0], spec[1]
+ depends = spec[2] if len(spec) > 2 else ()
+ data = desc(name, version, sha, depends).encode()
+ info = tarfile.TarInfo(f"{name}-{version}/desc")
+ info.size = len(data)
+ archive.addfile(info, io.BytesIO(data))
+ return buffer.getvalue()
+
+
+def tracked(hyprland="0.56.2-4", sha="a" * 64, **overrides):
+ packages = {name: (EDGE_PINS.get(name, "16.2.1-1"), "b" * 64) for name in channels.TRACKED}
+ packages["hyprland"] = (hyprland, sha)
+ packages.update(overrides)
+ return packages
+
+
+def split(packages):
+ core_names = {"glibc", "gcc", "libgcc", "libstdc++"}
+ core = {k: v for k, v in packages.items() if k in core_names}
+ extra = {k: v for k, v in packages.items() if k not in core_names}
+ return core, extra
+
+
+def omarchy_db(plugin_version="0.32.0-3", pins=EDGE_PINS, extra=None):
+ packages = {"cua-hyprland-plugin": (plugin_version, "c" * 64,
+ [f"{k}={v}" for k, v in pins.items()] + ["python>=3.11", "libfoo.so=1-64"]),
+ "cua-driver-bin": ("0.33.4-1", "d" * 64), "omarchy-keyring": ("20251027-1", "e" * 64)}
+ packages.update(extra or {})
+ return database(packages)
+
+
+class FakeMirrors:
+ """Serves databases by URL; any other URL raises like a down mirror."""
+
+ def __init__(self, routes):
+ self.routes = routes
+ self.calls = []
+
+ def __call__(self, url, headers=None):
+ self.calls.append(url)
+ for prefix, data in self.routes.items():
+ if url.startswith(prefix):
+ return data
+ raise urllib.error.URLError(f"no route for {url}")
+
+
+def mirrors(arch=None, edge=None, rc=None, releases=None):
+ arch_core, arch_extra = split(arch or tracked())
+ edge_core, edge_extra = split(edge or tracked())
+ rc_core, rc_extra = split(rc or tracked(hyprland="0.56.2-2", sha="f" * 64))
+ routes = {
+ "https://geo.mirror.pkgbuild.com/core/": database(arch_core),
+ "https://geo.mirror.pkgbuild.com/extra/": database(arch_extra),
+ "https://mirror.omarchy.org/core/": database(edge_core),
+ "https://mirror.omarchy.org/extra/": database(edge_extra),
+ "https://pkgs.omarchy.org/edge/": omarchy_db(),
+ "https://rc-mirror.omarchy.org/core/": database(rc_core),
+ "https://rc-mirror.omarchy.org/extra/": database(rc_extra),
+ "https://pkgs.omarchy.org/rc/": omarchy_db(extra={"cua-hyprland-plugin": ("0.28.2-2", "c" * 64)}),
+ channels.HYPRLAND_RELEASES: json.dumps(releases if releases is not None else [
+ {"tag_name": "v0.56.2", "draft": False, "prerelease": False, "html_url": "u"},
+ {"tag_name": "v0.57.0-rc1", "draft": False, "prerelease": True}]).encode(),
+ }
+ return FakeMirrors(routes)
+
+
+class DatabaseTest(unittest.TestCase):
+ def test_parse_db_reads_version_sha_depends_and_filename(self):
+ parsed = channels.parse_db(database({"hyprland": ("0.56.2-4", "a" * 64, ["aquamarine=0.15.1-1"])}))
+ self.assertEqual(parsed["hyprland"]["version"], "0.56.2-4")
+ self.assertEqual(parsed["hyprland"]["sha256"], "a" * 64)
+ self.assertEqual(parsed["hyprland"]["depends"], ["aquamarine=0.15.1-1"])
+ self.assertEqual(parsed["hyprland"]["filename"], "hyprland-0.56.2-4-x86_64.pkg.tar.zst")
+
+ @unittest.skipUnless(shutil.which("zstd"), "zstd not installed")
+ def test_parse_db_reads_zstd_databases_like_omarchy(self):
+ compressed = subprocess.run(["zstd", "-q", "-c"], input=channels.decompress(
+ subprocess.run(["gzip", "-dc"], input=database({"a": ("1-1", "0" * 64)}), capture_output=True).stdout),
+ capture_output=True, check=True).stdout
+ self.assertTrue(compressed.startswith(channels.ZSTD_MAGIC))
+ self.assertEqual(channels.parse_db(compressed)["a"]["version"], "1-1")
+
+ def test_exact_pins_skip_ranges_and_soname_provides(self):
+ self.assertEqual(channels.exact_pins(["hyprland=0.56.2-4", "python>=3.11", "libfoo.so=1-64", "binutils"]),
+ {"hyprland": "0.56.2-4"})
+
+ def test_header_version_drops_epoch_and_pkgrel(self):
+ self.assertEqual(channels.header_version("0.56.2-4"), "0.56.2")
+ self.assertEqual(channels.header_version("1:0.57.0-1.1"), "0.57.0")
+
+
+class FetchTest(unittest.TestCase):
+ def test_retries_server_errors_with_backoff(self):
+ attempts, sleeps = [], []
+
+ class Response(io.BytesIO):
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc):
+ return False
+
+ def opener(request, timeout):
+ attempts.append(request.full_url)
+ if len(attempts) < 3:
+ raise urllib.error.HTTPError(request.full_url, 503, "busy", {}, None)
+ return Response(b"ok")
+
+ self.assertEqual(channels.fetch("https://x/db", opener=opener, sleep=sleeps.append), b"ok")
+ self.assertEqual(sleeps, [2.0, 4.0])
+
+ def test_does_not_retry_not_found(self):
+ def opener(request, timeout):
+ raise urllib.error.HTTPError(request.full_url, 404, "missing", {}, None)
+
+ sleeps = []
+ with self.assertRaises(urllib.error.HTTPError):
+ channels.fetch("https://x/db", opener=opener, sleep=sleeps.append)
+ self.assertEqual(sleeps, [])
+
+
+class DetectTest(unittest.TestCase):
+ def test_detect_resolves_channels_and_records_a_down_mirror(self):
+ snapshot = channels.detect(fetcher=mirrors())
+ # stable has no route: recorded, not fatal.
+ self.assertIn("omarchy-stable", snapshot["errors"])
+ self.assertEqual(set(snapshot["channels"]), {"arch", "omarchy-edge", "omarchy-rc"})
+ self.assertEqual(snapshot["channels"]["arch"]["abi_key"], snapshot["channels"]["omarchy-edge"]["abi_key"])
+ self.assertNotEqual(snapshot["channels"]["arch"]["abi_key"], snapshot["channels"]["omarchy-rc"]["abi_key"])
+ edge = snapshot["channels"]["omarchy-edge"]
+ self.assertTrue(edge["omarchy_plugin"]["installable"])
+ self.assertEqual(edge["omarchy_driver"]["version"], "0.33.4-1")
+ self.assertEqual(snapshot["upstream"]["version"], "0.56.2")
+
+ def test_same_version_rebuild_is_a_new_build(self):
+ before = channels.detect(["arch"], fetcher=mirrors())["channels"]["arch"]["abi_key"]
+ rebuilt = channels.detect(["arch"], fetcher=mirrors(arch=tracked(sha="9" * 64)))["channels"]["arch"]["abi_key"]
+ self.assertNotEqual(before, rebuilt)
+
+ def test_pkgrel_bump_breaks_omarchy_pins(self):
+ snapshot = channels.detect(["omarchy-edge"], fetcher=mirrors(edge=tracked(hyprland="0.56.2-5")))
+ plugin = snapshot["channels"]["omarchy-edge"]["omarchy_plugin"]
+ self.assertFalse(plugin["installable"])
+ self.assertEqual(plugin["broken_pins"], {"hyprland": {"pinned": "0.56.2-4", "channel": "0.56.2-5"}})
+
+ def test_omarchy_repo_wins_first_in_rc_order(self):
+ rc_override = {"https://pkgs.omarchy.org/rc/": omarchy_db(extra={"hyprland": ("0.56.2-9", "e" * 64)})}
+ fake = mirrors()
+ fake.routes.update(rc_override)
+ rc = channels.detect(["omarchy-rc"], fetcher=fake)["channels"]["omarchy-rc"]
+ self.assertEqual(rc["packages"]["hyprland"]["version"], "0.56.2-9")
+ self.assertTrue(rc["needs_omarchy_repo"])
+
+ def test_missing_tracked_package_is_an_error(self):
+ packages = tracked()
+ del packages["aquamarine"]
+ snapshot = channels.detect(["arch"], fetcher=mirrors(arch=packages))
+ self.assertIn("aquamarine", snapshot["errors"]["arch"])
+
+ def test_upstream_ahead_of_every_package(self):
+ snapshot = channels.detect(["arch"], fetcher=mirrors(releases=[
+ {"tag_name": "v0.57.0", "draft": False, "prerelease": False}]))
+ self.assertTrue(channels.upstream_status(snapshot)["ahead_of_packages"])
+ current = channels.detect(["arch"], fetcher=mirrors())
+ self.assertFalse(channels.upstream_status(current)["ahead_of_packages"])
+
+
+SOURCES = [{"ref": "main", "commit": "1" * 40, "tree": "a" * 40, "driver_version": ""},
+ {"ref": "cua-driver-rs-v0.34.0", "commit": "2" * 40, "tree": "a" * 40, "driver_version": "0.34.0"},
+ {"ref": "cua-driver-rs-v0.32.0", "commit": "3" * 40, "tree": "b" * 40, "driver_version": "0.32.0"}]
+
+
+class PlanTest(unittest.TestCase):
+ def setUp(self):
+ self.snapshot = channels.detect(fetcher=mirrors())
+
+ def test_one_build_per_abi_key_and_tree(self):
+ include = channels.plan(self.snapshot, SOURCES)
+ self.assertEqual(len(include), 4) # 2 ABI keys x 2 distinct trees.
+ main = [j for j in include if j["tree"] == "a" * 40]
+ self.assertTrue(all(j["refs"] == ["main", "cua-driver-rs-v0.34.0"] for j in main))
+ edge = [j for j in include if "omarchy-edge" in j["channels"]][0]
+ self.assertEqual(edge["channel"], "arch") # Shared key, built without the Omarchy repo.
+ self.assertEqual(edge["expected_packages"]["hyprland"], "0.56.2-4")
+
+ def test_finished_combinations_are_skipped_unless_forced(self):
+ key = self.snapshot["channels"]["arch"]["abi_key"]
+ previous = {"entries": [{"abi_key": key, "plugin": {"tree": "a" * 40}, "status": "pass"},
+ {"abi_key": key, "plugin": {"tree": "b" * 40}, "status": "fail"}]}
+ include = channels.plan(self.snapshot, SOURCES, previous)
+ self.assertEqual(len(include), 3) # A failure is retried.
+ self.assertEqual(len(channels.plan(self.snapshot, SOURCES, previous, force=True)), 4)
+
+
[email protected](shutil.which("git"), "git not installed")
+class SourcesTest(unittest.TestCase):
+ def test_main_latest_tag_and_omarchy_packaged_source(self):
+ with tempfile.TemporaryDirectory() as directory:
+ repo = Path(directory)
+ env = dict(os.environ, GIT_AUTHOR_NAME="t", GIT_AUTHOR_EMAIL="t@t", GIT_COMMITTER_NAME="t",
+ GIT_COMMITTER_EMAIL="t@t")
+
+ def git(*args):
+ subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, env=env)
+
+ git("init", "-q")
+ plugin = repo / channels.PLUGIN_PATH
+ plugin.mkdir(parents=True)
+ for version in ("0.32.0", "0.34.0", "0.9.0"):
+ (plugin / "VERSION").write_text(version)
+ git("add", "-A")
+ git("commit", "-qm", version)
+ git("tag", f"cua-driver-rs-v{version}")
+ git("tag", "cua-driver-rs-v0.35.0-rc.1")
+ snapshot = {"channels": {"omarchy-edge": {"omarchy_plugin": {"version": "0.32.0-3"}}}}
+ found = channels.plugin_sources(repo, snapshot)
+ self.assertEqual([s["ref"] for s in found], ["main", "cua-driver-rs-v0.34.0", "cua-driver-rs-v0.32.0"])
+ self.assertEqual(found[1]["driver_version"], "0.34.0")
+ self.assertTrue(all(len(s["tree"]) == 40 for s in found))
+
+ def test_docs_and_tooling_do_not_change_the_source_id(self):
+ with tempfile.TemporaryDirectory() as directory:
+ repo = Path(directory)
+ env = dict(os.environ, GIT_AUTHOR_NAME="t", GIT_AUTHOR_EMAIL="t@t", GIT_COMMITTER_NAME="t",
+ GIT_COMMITTER_EMAIL="t@t")
+
+ def git(*args):
+ return subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True,
+ env=env, text=True).stdout.strip()
+
+ plugin = repo / channels.PLUGIN_PATH
+ (plugin / "src").mkdir(parents=True)
+ git("init", "-q")
+ (plugin / "src" / "plugin.cpp").write_text("1")
+ git("add", "-A")
+ git("commit", "-qm", "a")
+ first = channels.source_id(repo, git("rev-parse", "HEAD"))
+ for name in ("requalify/x.py", "docs/y.md", "README.md"):
+ (plugin / name).parent.mkdir(parents=True, exist_ok=True)
+ (plugin / name).write_text("doc")
+ git("add", "-A")
+ git("commit", "-qm", "b")
+ self.assertEqual(channels.source_id(repo, git("rev-parse", "HEAD")), first)
+ (plugin / "src" / "plugin.cpp").write_text("2")
+ git("commit", "-qam", "c")
+ self.assertNotEqual(channels.source_id(repo, git("rev-parse", "HEAD")), first)
+
+
+class QualifyTest(unittest.TestCase):
+ def test_pacman_conf_keeps_channel_order(self):
+ conf = qualify.pacman_conf("omarchy-rc", with_omarchy=True)
+ self.assertLess(conf.index("[omarchy]"), conf.index("[core]"))
+ self.assertIn("https://rc-mirror.omarchy.org/$repo/os/$arch", conf)
+ self.assertNotIn("[omarchy]", qualify.pacman_conf("omarchy-edge", with_omarchy=False))
+
+ def test_overall_status(self):
+ passing = {"build": {"status": "pass"}, "ctest": {"status": "pass"},
+ "load": {"status": "pass"}, "smoke": {"status": "pass"}}
+ self.assertEqual(qualify.overall(passing), "pass")
+ self.assertEqual(qualify.overall({**passing, "load": {"status": "unavailable"},
+ "smoke": {"status": "unavailable"}}), "build-only")
+ self.assertEqual(qualify.overall({**passing, "smoke": {"status": "fail"}}), "fail")
+ self.assertEqual(qualify.overall({**passing, "ctest": {"status": "fail"}}), "fail")
+ self.assertEqual(qualify.overall({**passing, "build": {"status": "fail"}}), "fail")
+
+ def test_ctest_summary_parsing(self):
+ output = ("The following tests FAILED:\n\t 7 - cua_hyprland_status_test (Failed)\n"
+ "95% tests passed, 1 tests failed out of 20\n")
+ with tempfile.TemporaryDirectory() as directory, \
+ mock.patch.object(qualify, "run", return_value=(8, output)):
+ result = qualify.ctest(Path(directory))
+ self.assertEqual((result["status"], result["total"], result["failed"]), ("fail", 20, 1))
+ self.assertEqual(result["failures"], ["cua_hyprland_status_test"])
+ with tempfile.TemporaryDirectory() as directory, \
+ mock.patch.object(qualify, "run", return_value=(0, "100% tests passed out of 20\n")):
+ result = qualify.ctest(Path(directory))
+ self.assertEqual((result["status"], result["total"], result["failed"]), ("pass", 20, 0))
+
+ def test_no_drm_device_is_unavailable_not_failure(self):
+ with mock.patch.object(qualify, "drm_cards", return_value=[]):
+ load, smoke = qualify.session(Path("/nonexistent.so"), Path("/nonexistent"))
+ self.assertEqual((load["status"], smoke["status"]), ("unavailable", "unavailable"))
+
+
+class InputLaneTest(unittest.TestCase):
+ def test_packets_follow_protocol_v3(self):
+ lane = headless.InputLane.__new__(headless.InputLane)
+ lane.sequence, lane.transcript, sent = 0, [], []
+ lane.request = lambda packet: sent.append(packet) or {"ok": True}
+ lane.target({"pid": 42, "address": "0x55aa"})
+ lane.key({"target": "f" * 32, "revision": 1}, 46)
+ lane.key({"target": "f" * 32, "revision": 2}, 28)
+ self.assertEqual(sent, ["TARGET 42 55aa 2", f"KEY 1 {'f' * 32} 1 46 0", f"KEY 2 {'f' * 32} 2 28 0"])
+
+
+def record(job, status, **checks):
+ base = {"build": {"status": "pass", "module_sha256": "m" * 64, "options": qualify.BUILD_OPTIONS},
+ "ctest": {"status": "pass", "total": 20, "failed": 0}, "load": {"status": "pass"},
+ "smoke": {"status": "pass"}}
+ base.update(checks)
+ return {"job": job, "status": status, "finished_at": "2026-10-09T07:00:00Z",
+ "measured": {"hyprland": {"package_version": job["hyprland"], "header_version": "0.56.2",
+ "sha256": "h" * 64, "headers_sha256": "i" * 64},
+ "compiler": {"version": "16.2.1 20260810"}}, **base}
+
+
+class DryRunTest(unittest.TestCase):
+ """detect -> plan -> (simulated container results) -> manifest -> issue, with no network or Docker."""
+
+ def run_pipeline(self, fake, previous=None, statuses=None):
+ snapshot = channels.detect(fetcher=fake)
+ snapshot["upstream"] = channels.upstream_status(snapshot)
+ include = channels.plan(snapshot, SOURCES, previous)
+ statuses = statuses or {}
+ records = [record(job, statuses.get(job["tree"], "pass"),
+ **({"smoke": {"status": "fail", "reason": "target wrote nothing"}}
+ if statuses.get(job["tree"]) == "fail" else {}))
+ for job in include]
+ return channels, manifest.merge(previous, snapshot, records, "https://run", now="2026-10-09T07:00:00Z")
+
+ def test_all_pass_publishes_a_clean_manifest(self):
+ _, (result, fresh) = self.run_pipeline(mirrors())
+ self.assertEqual(len(fresh), 4)
+ self.assertEqual(manifest.failures(result, fresh), [])
+ edge = result["current"]["omarchy-edge"]
+ self.assertEqual(edge["cua-driver-rs-v0.32.0"]["status"], "pass")
+ self.assertEqual(set(edge), {"main", "cua-driver-rs-v0.34.0", "cua-driver-rs-v0.32.0"})
+ table = manifest.matrix(result, fresh)
+ self.assertIn("| omarchy-edge | 0.56.2-4 |", table)
+ self.assertIn("pass (20/20)", table)
+ json.dumps(result) # Serializable.
+
+ def test_failure_and_broken_pins_open_an_issue(self):
+ fake = mirrors(edge=tracked(hyprland="0.56.2-5"))
+ _, (result, fresh) = self.run_pipeline(fake, statuses={"b" * 40: "fail"})
+ problems = manifest.failures(result, fresh)
+ self.assertTrue(any("cua-driver-rs-v0.32.0" in p and "smoke" in p for p in problems))
+ self.assertTrue(any("omarchy-edge" in p and "no longer installs" in p for p in problems))
+ with tempfile.TemporaryDirectory() as directory:
+ path = Path(directory) / "failures.md"
+ path.write_text("\n".join(problems) + "\n")
+ out = subprocess.run([str(HERE / "report_failure.sh"), "https://run", str(path)], capture_output=True,
+ text=True, env=dict(os.environ, DRY_RUN="1"), check=True).stdout
+ self.assertIn("gh issue create --title Hyprland\\ plugin\\ requalification\\ failing", out)
+ self.assertIn("hyprland-requalify", out)
+
+ def test_second_run_skips_finished_builds_and_keeps_history(self):
+ _, (first, _) = self.run_pipeline(mirrors())
+ snapshot = channels.detect(fetcher=mirrors())
+ self.assertEqual(channels.plan(snapshot, SOURCES, first), [])
+ _, (second, fresh) = self.run_pipeline(mirrors(arch=tracked(sha="9" * 64)), previous=first)
+ self.assertEqual(len(fresh), 2) # Only the rebuilt Arch key.
+ self.assertEqual(len(second["entries"]), 6)
+
+ def test_main_writes_outputs(self):
+ _, (result, _) = self.run_pipeline(mirrors())
+ with tempfile.TemporaryDirectory() as directory:
+ base = Path(directory)
+ snapshot = channels.detect(fetcher=mirrors())
+ (base / "snapshot.json").write_text(json.dumps(snapshot))
+ results = base / "results" / "requalify-result-x"
+ (results / "session").mkdir(parents=True)
+ job = channels.plan(snapshot, SOURCES)[0]
+ (results / "result.json").write_text(json.dumps(record(job, "pass")))
+ (results / "session" / "result.json").write_text("{}")
+ env = dict(os.environ, GITHUB_OUTPUT=str(base / "output"))
+ subprocess.run([sys.executable, str(HERE / "manifest.py"), "--snapshot", str(base / "snapshot.json"),
+ "--results", str(base / "results"), "--out", str(base / "compat")],
+ check=True, env=env, capture_output=True)
+ written = json.loads((base / "compat" / "compatibility.json").read_text())
+ self.assertEqual(len(written["entries"]), 1)
+ self.assertIn("failed=false", (base / "output").read_text())
+ self.assertFalse((base / "compat" / "failures.md").exists())
+
+
+class WorkflowContractTest(unittest.TestCase):
+ def setUp(self):
+ self.workflow = (ROOT / ".github/workflows/nightly-hyprland-plugin-requalify.yml").read_text()
+ self.code = "".join(line for line in self.workflow.splitlines(keepends=True)
+ if not line.lstrip().startswith("#"))
+
+ def test_daily_and_manual(self):
+ self.assertIn(" schedule:\n # Daily", self.workflow)
+ self.assertIn(" workflow_dispatch:", self.workflow)
+
+ def test_never_publishes_packages_or_touches_omarchy(self):
+ for forbidden in ("packages: write", "gh release", "softprops/", "omacom/", "docker push", "makepkg"):
+ self.assertNotIn(forbidden, self.code)
+ pushes = [line.strip() for line in self.code.splitlines() if "push" in line and "git" in line]
+ self.assertEqual(pushes, ['git -C compat-branch push --quiet origin "HEAD:refs/heads/$COMPAT_BRANCH"'])
+
+ def test_pull_requests_never_file_issues_or_push(self):
+ self.assertIn("DRY_RUN: ${{ github.event_name == 'pull_request' && '1' || '0' }}", self.workflow)
+ publish = self.workflow.split("- name: Commit the manifest", 1)[1].split("run:", 1)[0]
+ self.assertIn("github.ref == 'refs/heads/main'", publish)
+ self.assertNotIn("pull_request", publish)
+
+
+if __name__ == "__main__":
+ unittest.main()