refactor(ci): ♻️ make the justfile the single source of build commands

[robertodr]

🤖 AI text below 🤖

Summary

The workflows kept their own copies of commands a developer also runs: five dependency installs, four uv sync spellings, the build-info dump, the sanitizer option sets, the MPI oversubscription variables, the CTest label filters, the rank loop, a 70-line find_package consumer heredoc, and a second set of link-checker flags. They drifted, and a failing lane could not be reproduced locally without transcribing YAML. This makes the justfile the single source of truth for commands; workflows choose matrices, environment and artifacts. No library code changes.

Changes

• .github/actions/setup: installs just and uv (cache keyed per build configuration) and the system packages. Replaces the dependency block in eight jobs.
• tools/packages/{apt,apt-mpi,brew,brew-mpi}.txt: the package lists as data, read by the action and by .devcontainer/Dockerfile (which installs just itself, so it can share the data but not a recipe). The compiler package is derived from CXX, so a matrix lane carries no list of its own.
• just build *ARGS is the only uv sync for the package, spelled once in the uv_sync variable. just info replaces the build-info heredoc.
• monoprop_ENABLE_MPI is now the only MPI switch: C++ build, mpi4py build requirement, mpi runtime extra, and the MPI packages CI installs. Serial builds drop the extra, since import mpi4py.MPI raises with no runtime.
• Test legs as recipes: test-py, test-cpp, test-cpp-mpi, test-py-mpi, plus test-cpp-asan, test-py-asan, sanitizer-reports, test-cpp-tsan. test, test-wide and test-mpi are build bodies with dependencies on those legs.
• build_dir follows SKBUILD_CMAKE_BUILD_TYPE, so a sanitizer or coverage tree is found through the environment that built it. The two oversubscription variables are exported once instead of four times.
• cpp/tests/find_package_smoke/ is a tracked standalone project, run by just test-find-package, replacing the consumer program test.yml wrote inline. It compiles the in-tree link_export_probe source, so the exercised consumer and the in-tree probe cannot drift, and it links only monoprop::monoprop, as a downstream user does.
• The link checker's options live in .lychee.postbuild.toml, read by both just check-doc-links and the docs workflow. The recipe's --index-files turned out to be the wrong half of that drift: it made lychee demand an index inside the asset directory the export writes beside each page instead of falling back to the page.
• tools/check-workflow-commands.py, a prek hook, fails any workflow step whose run: block invokes the build, test, coverage or packaging tools directly. Version probes are exempt; the deliberate exceptions carry a reason and are keyed by step name, so an entry matching no step is itself an error.
• Two behavior changes: the legs run --no-sync, so a test run cannot silently rebuild a differently configured wheel; and the serial Python leg drops -m "not mpi", which pytest-mpi already skips without --with-mpi (what CI relied on).
• One drive-by fix: the setup action used mapfile and ${var,,}, neither of which exists in the bash 3.2 the macOS runners ship.
• Docs updated in step: AGENTS.md, README.md, cpp/tests/README.md, docs/content/docs/{building,testing,how-to-contribute}.mdx, including a stale reference to a just test-mpi-matrix recipe that never existed.

qa-analysis.yml's clang-tidy invocation and deploy.yml's packaging commands are deliberately left in the workflows, as recorded exceptions.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable

AI/LLM disclosure

• I used the following tool to help write this PR description: Pi (claude-opus-5)
• I used the following tool to generate or modify code: Pi (claude-opus-5)

[github-actions]

Docs preview: https://pr-326.monoprop-docs.pages.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (89a9603) to head (e9f4ac9).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #326   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[diagonal-hamiltonian]

Approve, but needs a comment sweep

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud