feat(tooling): replace tox with just

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,9 +7,9 @@
 ## ✅ Checklist
 <!-- Please check off all required items. For those that don't apply remove them accordingly. -->
 
-- [ ] Ran `tox` checks to avoid unnecessary CI fails:
+- [ ] Ran local quality checks to avoid unnecessary CI fails:
     ```console
-    uvx tox
+    just check
     ```
 - [ ] Considered adding appropriate tests for the changes.
 - [ ] Considered updating the online docs in the [./docs/](/leanEthereum/leanSpec/tree/main/docs/) directory.

.github/workflows/ci.yml

@@ -37,8 +37,13 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
 
-      - name: Run all quality checks via tox
-        run: uvx tox -e all-checks
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
+      - name: Run all quality checks
+        run: just check
 
   test:
     name: Tests - Python ${{ matrix.python-version }} on ${{ matrix.os }}
@@ -63,8 +68,13 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
 
-      - name: Run tests via tox
-        run: uvx tox -e pytest
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
+      - name: Run tests
+        run: just test
 
   coverage-gate:
     name: Coverage gate - Python 3.12
@@ -84,8 +94,13 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
 
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
       - name: Run tests with coverage gate
-        run: uvx tox -e pytest-cov-gate
+        run: just test-cov-gate
 
   fill-tests:
     name: Fill test fixtures - Python 3.14
@@ -105,11 +120,13 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
 
-      - name: Sync dependencies
-        run: uv sync --no-progress
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
 
       - name: Fill test fixtures
-        run: uv run fill --fork=Devnet --clean -n auto
+        run: just fill
 
   interop-tests:
     name: Interop tests - Multi-node consensus
@@ -130,14 +147,12 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
 
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
       - name: Run interop tests
-        run: |
-          uv run pytest tests/interop/ \
-            -v \
-            --no-cov \
-            --timeout=120 \
-            -x \
-            --tb=short \
-            --log-cli-level=INFO
+        run: just interop
         env:
           LEAN_ENV: test

CONTRIBUTING.md

@@ -5,9 +5,10 @@
 1. Fork and clone the repository
 2. Install dependencies: `uv sync`
 3. Make your changes
-4. Run checks: `uvx tox -e all-checks`
-5. Run tests: `uvx tox -e pytest`
-6. Submit a pull request
+4. Install `just`: `uv tool install just-bin`
+5. Run checks: `just check`
+6. Run tests: `just test`
+7. Submit a pull request
 
 ## Pull Request Guidelines
 
@@ -22,7 +23,7 @@
 - **Type hints**: Required for all functions and methods
 - **Docstrings**: Use Google style for public APIs
 - **Line length**: 100 characters (enforced by ruff)
-- **Formatting**: Run `uvx tox -e fix` to auto-format
+- **Formatting**: Run `just fix` to auto-format
 
 ## Adding New Subspecifications
 

Justfile

@@ -0,0 +1,72 @@
+set positional-arguments := true
+
+alias help := default
+
+[default]
+default:
+    @just --list
+
+[group('quality')]
+check: lint typecheck spellcheck mdformat
+
+[group('quality')]
+lint *args:
+    uv run --group lint ruff check --no-fix --show-fixes "$@"
+
+[group('quality')]
+format *args:
+    uv run --group lint ruff format "$@"
+
+[group('quality')]
+fix:
+    uv run --group lint ruff check --fix
+    uv run --group lint ruff format
+    uv run --group docs mdformat docs/
+
+[group('quality')]
+typecheck *args:
+    uv run --group lint ty check "$@"
+
+[group('quality')]
+spellcheck *args:
+    uv run --group lint codespell src tests packages docs README.md CLAUDE.md --skip="*.lock,*.svg,.git,__pycache__,.pytest_cache,tests/lean_spec/snappy/testdata" --ignore-words=.codespell-ignore-words.txt "$@"
+
+[group('quality')]
+mdformat *args:
+    uv run --group docs mdformat --check docs/ "$@"
+
+[group('tests')]
+test *args:
+    uv run --group test pytest tests -n auto --maxprocesses=10 --durations=10 --dist=worksteal "$@"
+
+[group('tests')]
+test-cov *args:
+    uv run --group test pytest --cov --cov-report=html --cov-report=term "$@"
+
+[group('tests')]
+test-cov-gate *args:
+    uv run --group test pytest --cov --cov-report=term-missing --cov-fail-under=80 "$@"
+
+[group('tests')]
+test-consensus *args:
+    uv run --group test pytest -n auto --maxprocesses=10 --durations=10 --dist=worksteal tests/lean_spec/subspecs/containers tests/lean_spec/subspecs/forkchoice tests/lean_spec/subspecs/networking "$@"
+
+[group('tests')]
+fill *args:
+    uv run --group test fill --fork=Devnet --clean -n auto "$@"
+
+[group('tests')]
+apitest server_url *args:
+    uv run --group test apitest "{{server_url}}" "$@"
+
+[group('tests')]
+interop *args:
+    uv run --group test pytest tests/interop/ -v --no-cov --timeout=120 -x --tb=short --log-cli-level=INFO "$@"
+
+[group('docs')]
+docs *args:
+    uv run --group docs mkdocs build "$@"
+
+[group('docs')]
+docs-serve *args:
+    uv run --group docs mkdocs serve "$@"

README.md

@@ -20,6 +20,20 @@ The Lean Ethereum protocol specifications and cryptographic subspecifications.
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ````
 
+#### Installing just
+
+[`just`](https://just.systems/) is the task runner used for common developer
+workflows in this repository.
+
+```bash
+# Recommended cross-platform install
+uv tool install just-bin
+
+# Alternatives
+brew install just
+apt install just
+```
+
 #### Installing Python 3.12+
 
 This project requires Python 3.12 or later and should be installed via `uv`:
@@ -57,8 +71,11 @@ cd leanSpec
 # Install and sync project and dev dependencies, using `uv.lock` versions
 uv sync
 
+# See the available repo tasks
+just
+
 # Run tests to verify setup
-uv run pytest
+just test
 ```
 
 ### Project Structure
@@ -97,7 +114,10 @@ uv sync
 ### Running Tests
 
 ```bash
-# Run all tests from workspace root
+# Run the default test suite
+just test
+
+# Run all tests from workspace root without just
 uv run pytest
 
 # Run tests in parallel, utilizing all available CPU cores
@@ -121,37 +141,51 @@ uv run fill --clean --fork=devnet --scheme=prod
 # Run API conformance tests against an external client implementation
 # Usage: uv run apitest <server-url> [pytest-args]
 uv run apitest http://localhost:5052
+
+# Same API conformance test through the task runner
+just apitest http://localhost:5052
 ```
 
 ### Code Quality
 
 ```bash
+# Run the full quality gate
+just check
+
 # Check code style and errors
-uv run ruff check
+just lint
 
 # Auto-fix issues
-uv run ruff check --fix
+just fix
 
 # Format code
-uv run ruff format
+just format
 
 # Type checking
-uv run ty check
+just typecheck
 ```
 
-### Using Tox for Comprehensive Checks
+### Using just for Common Tasks
 
-You can use `tox` with `uvx`, which:
-* Creates a temporary environment just for `tox`
-* Doesn't require `uv sync` first
-* Uses `tox-uv` for faster dependency installation
+Run `just` with no arguments to see the available recipes. `just` is the
+primary command surface for contributors, while raw `uv run ...` commands remain
+available when you want to invoke tools directly.
 
 ```bash
-# Run specific environment, like "all quality checks" (lint, typecheck, spellcheck)
-uvx tox -e all-checks
+# List available tasks
+just
+
+# Run quality checks
+just check
+
+# Run tests
+just test
+
+# Build documentation
+just docs
 
-# Run all tox environments (all checks + tests + docs)
-uvx tox
+# Generate consensus fixtures
+just fill
 ```
 
 ### Documentation
@@ -210,24 +244,24 @@ def test_withdrawal_amount_above_uint64_max():
 - **uv**: Fast Python package manager - like npm/yarn but for Python
 - **ruff**: Linter and formatter
 - **ty**: Type checker
-- **tox**: Automation tool for running tests across multiple environments (used via `uvx`)
+- **just**: Task runner for repository workflows such as checks, tests, docs, and fixture generation
 - **mkdocs**: Documentation generator - write docs in Markdown, serve them locally
 
 ## Common Commands Reference
 
 | Task                                          | Command                                                |
 |-----------------------------------------------|--------------------------------------------------------|
 | Install and sync project and dev dependencies | `uv sync`                                              |
-| Run tests                                     | `uv run pytest ...`                                    |
-| Format code                                   | `uv run ruff format`                                   |
-| Lint code                                     | `uv run ruff check`                                    |
-| Fix lint errors                               | `uv run ruff check --fix`                              |
-| Type check                                    | `uv run ty check`                                      |
-| Build docs                                    | `uv run mkdocs build`                                  |
-| Serve docs                                    | `uv run mkdocs serve`                                  |
-| Run everything (checks + tests + docs)        | `uvx tox`                                              |
-| Run all quality checks (no tests/docs)        | `uvx tox -e all-checks`                                |
-| Test external client API conformance          | `uv run apitest http://localhost:5052`                 |
+| List repo tasks                               | `just`                                                 |
+| Run quality checks                            | `just check`                                           |
+| Run tests                                     | `just test`                                            |
+| Format code                                   | `just format`                                          |
+| Fix lint and formatting                       | `just fix`                                             |
+| Type check                                    | `just typecheck`                                       |
+| Build docs                                    | `just docs`                                            |
+| Serve docs                                    | `just docs-serve`                                      |
+| Generate consensus fixtures                   | `just fill`                                            |
+| Test external client API conformance          | `just apitest http://localhost:5052`                   |
 | Run consensus node                            | `uv run python -m lean_spec --genesis config.yaml`     |
 | Build Docker test image                       | `docker build -t lean-spec:test .`                     |
 | Build Docker node image                       | `docker build --target node -t lean-spec:node .`       |
@@ -265,7 +299,7 @@ docker run --rm lean-spec:test
 # Run tests in parallel
 docker run --rm lean-spec:test uv run pytest -n auto
 
-# Run the fill command
+# Run the fill command directly
 docker run --rm lean-spec:test uv run fill --clean --fork=devnet
 ```