Add a setup-python-uv composite action and integrate just for CI and development tasks. Add a just recipe to install/uninstall a pre-push hook to run the same recipe locally that runs in CI. Put some dev notes in the README.

Author: pauleveritt

.github/actions/setup-python-uv/action.yml

@@ -0,0 +1,28 @@
+name: Setup Python with uv
+description: Install uv, set up Python, and install project dependencies
+
+runs:
+  using: composite
+  steps:
+    - name: Restore .venv cache
+      uses: actions/cache@v4
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+        restore-keys: |
+          venv-${{ runner.os }}-
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Set up Python 3.14
+      shell: bash
+      run: uv python install
+      # Uses version from .python-version
+
+    - name: Install dependencies
+      shell: bash
+      run: uv sync --frozen

.github/workflows/ci.yml

@@ -4,28 +4,19 @@ on: [push, pull_request]
 
 jobs:
   ci_tests:
-    name: python
+    name: python 3.14
     runs-on: ubuntu-latest
+    timeout-minutes: 30
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.14.0-rc.2
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.14.0-rc.2
+      - name: Setup Python 3.14 and uv
+        uses: ./.github/actions/setup-python-uv
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
+      - name: Install just
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
 
-      - name: Lint
-        run: uv run ruff check
-
-      - name: Check formatting
-        run: uv run ruff format --check
-
-      - name: Type check
-        run: uv run pyright
-
-      - name: Run tests
-        run: uv run pytest -v
+      - name: Run CI checks
+        run: just ci-checks

README.md

@@ -30,6 +30,29 @@ If you have [Astral's `uv`](https://docs.astral.sh/uv/) you can easily try `tdom
 uv run --with tdom --python 3.14 python
 ```
 
+## Development
+
+This project uses [`just`](https://just.systems/) for task automation and [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+### Setup
+
+Install `just` and `uv`, then run:
+
+```bash
+just install
+```
+
+### Common Tasks
+
+```bash
+just              # Show all available tasks
+just test         # Run tests
+just lint         # Check code for issues
+just fmt          # Format code
+just typecheck    # Run type checker
+just ci-checks    # Run all checks (CI pipeline)
+```
+
 ## Usage
 
 `tdom` leverages Python 3.14's

justfile

@@ -1,49 +1,101 @@
-default: lint format_check type_check test
+# Justfile for tdom
+# Requires: just, uv, Python 3.14
+# All tasks use uv to ensure isolated, reproducible runs.
 
-lint:
-    uv run ruff check
+# Default recipe shows help
+default:
+    @just --list
 
-format_check:
-    uv run ruff format --check
+# Print environment info
+info:
+    @echo "Python: $(python --version)"
+    @uv --version
 
-format_docs:
-    npx prettier --write "**/*.md"
+# Install project and dev dependencies
+install:
+    uv sync --all-groups
 
-type_check:
-    uv run pyright
+# Alias for install (better discoverability)
+setup: install
 
-test:
-    uv run pytest
+# Run tests (sequential)
+test *ARGS:
+    uv run pytest {{ ARGS }}
 
-watch:
-    # Watch for changes and run tests.
-    uv run ptw tdom/  
+# Run tests (parallel)
+test-parallel *ARGS:
+    uv run pytest -n auto {{ ARGS }}
 
-build_docs:
-    cd docs && uv run sphinx-build . _build
+# Lint code (check for issues)
+lint *ARGS:
+    uv run ruff check {{ ARGS }} .
 
-clean_docs:
-    rm -rf docs/_build
+# Format code (auto-format)
+fmt *ARGS:
+    uv run ruff format {{ ARGS }} .
 
-build_package:
-    uv build
+# Check formatting without modifying files (for CI)
+fmt-check *ARGS:
+    uv run ruff format --check {{ ARGS }} .
 
-clean_package:
-    rm -rf dist/
+# Lint and auto-fix
+lint-fix:
+    uv run ruff check --fix .
 
-build: build_docs build_package
+# Type checking
+typecheck *ARGS:
+    uv run pyright {{ ARGS }}
 
-clean: clean_docs clean_package
+# Build the documentation site
+docs:
+    uv run sphinx-build -b html docs docs/_build/html
 
-reports:
-    uv run pytest --cov=tdom --cov-report=xml:reports/coverage.xml --cov-report=term --cov-report=html:reports/coverage --junitxml=reports/pytest.xml --html=reports/pytest.html
+# Format markdown files
+fmt-docs:
+    npx prettier --write "**/*.md"
+
+# Watch for changes and run tests
+watch:
+    uv run ptw tdom/
+
+# Build sdist/wheel
+build:
+    uv build
 
-clean_reports:
+# Clean build and cache artifacts
+clean:
+    rm -rf .pytest_cache .ruff_cache .pyright .mypy_cache build dist
+    find docs/_build -mindepth 1 -maxdepth 1 -not -name ".gitkeep" -exec rm -rf {} + || true
     rm -rf reports/
 
+# Run all quality checks with fail-fast behavior
+ci-checks:
+    just install && just lint && just fmt-check && just typecheck && just test-parallel
+
+# Generate reports for badges
+reports:
+    uv run pytest --cov=tdom --cov-report=xml:reports/coverage.xml --cov-report=term --cov-report=html:reports/coverage --junitxml=reports/pytest.xml --html=reports/pytest.html
+
+# Generate badge SVGs from reports
 badges:
     uv run genbadge tests -i reports/pytest.xml -v -o reports/pytest.svg
     uv run genbadge coverage -i reports/coverage.xml -v -o reports/coverage.svg
 
-clean_badges:
-    rm -rf reports/*.svg
+# Enable pre-push hook to run ci-checks before pushing
+enable-pre-push:
+    @echo "Installing pre-push hook..."
+    @echo '#!/bin/sh' > .git/hooks/pre-push
+    @echo '' >> .git/hooks/pre-push
+    @echo '# Run quality checks before push' >> .git/hooks/pre-push
+    @echo 'echo "Running quality checks before push..."' >> .git/hooks/pre-push
+    @echo 'if ! just ci-checks; then' >> .git/hooks/pre-push
+    @echo '    echo "Pre-push check failed! Push aborted."' >> .git/hooks/pre-push
+    @echo '    exit 1' >> .git/hooks/pre-push
+    @echo 'fi' >> .git/hooks/pre-push
+    @chmod +x .git/hooks/pre-push
+    @echo "Pre-push hook installed! Use 'just disable-pre-push' to disable."
+
+# Disable pre-push hook
+disable-pre-push:
+    @chmod -x .git/hooks/pre-push 2>/dev/null || true
+    @echo "Pre-push hook disabled. Use 'just enable-pre-push' to re-enable."