chore: centralize development and CI verbs in just

.gitattributes

@@ -1,3 +1,9 @@
 *.py linguist-language=python
 *.ipynb linguist-documentation
 .git_archival.txt export-subst
+
+# just refuses to format a CRLF file, so `just just-check` would fail on a Windows
+# checkout with core.autocrlf=true before the contributor has changed anything.
+Justfile text eol=lf
+*/justfile text eol=lf
+packages/*/justfile text eol=lf

.github/workflows/check_changelogs.yml

@@ -24,14 +24,20 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
+
       - name: Check zarr-python changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py
+        run: just check-changelogs
 
       - name: Check zarr-metadata changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-metadata/changes
+        run: just check-changelogs packages/zarr-metadata/changes
 
       - name: Check zarr-indexing changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-indexing/changes
+        run: just check-changelogs packages/zarr-indexing/changes
 
       - name: Check zarr-http-server changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-http-server/changes
+        run: just check-changelogs packages/zarr-http-server/changes

.github/workflows/codspeed.yml

@@ -31,10 +31,19 @@ jobs:
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    # No interpreter is set up in this job on purpose. Benchmarks are only comparable
+    # across runs if the interpreter underneath them does not move: adding a pinned
+    # Python here measured a uniform ~13% slowdown on every benchmark, because hatch
+    # then built the environment on that interpreter instead of the runner's own.
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Run the benchmarks
       uses: CodSpeedHQ/action@373d6868929f444bc08d901fd0eb0ad52a8875ea # v5.2.1
       env:
         ZARR_BENCHMARK_CLEAR_CACHE: '1'
       with:
           mode: walltime
-          run: hatch run test.py3.12-minimal:pytest tests/benchmarks --codspeed
+          run: HATCH_ENV=test.py3.12-minimal just benchmark-codspeed

.github/workflows/docs.yml

@@ -23,18 +23,22 @@ jobs:
         with:
           persist-credentials: false
       - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
-      - run: uv sync --group docs
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
       # Fast source-level guards that need no built site, so they run before the (slower)
       # build for a quick failure: every public export is in the API reference, and no
       # docstring/Markdown carries reStructuredText markup that MkDocs won't render.
-      - run: uv run python ci/check_documented_exports.py docs/api
-      - run: uv run python ci/lint_docs.py
+      - run: just check-doc-exports
+      - run: just lint-docs
       # --strict turns warnings into errors, so a docs code block that fails to execute
       # at build time (e.g. a non-exec python fence disrupting a later exec="true" block)
       # fails CI instead of merging as a silent warning.
-      - run: uv run mkdocs build --strict
+      - run: just docs-build
         env:
           DISABLE_MKDOCS_2_WARNING: "true"
           NO_MKDOCS_2_WARNING: "true"
-      - run: uv run python ci/check_unlinked_types.py
+      - run: just check-doc-links
         continue-on-error: true

.github/workflows/gpu_test.yml

@@ -67,17 +67,24 @@ jobs:
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
+    # Two names for the same environment on purpose: `just setup` builds whatever
+    # HATCH_ENV points at, while `just gpu` reads GPU_HATCH_ENV so that an
+    # ambient HATCH_ENV can never redirect `pytest -m gpu` into a CPU environment.
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: gputest.py${{ matrix.python-version }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
-        HATCH_ENV: gputest.py${{ matrix.python-version }}
+        GPU_HATCH_ENV: gputest.py${{ matrix.python-version }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just gpu
 
     - name: Upload coverage
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0

.github/workflows/hypothesis.yaml

@@ -65,12 +65,16 @@ jobs:
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
     - name: Restore cached hypothesis directory
       id: restore-hypothesis-cache
@@ -89,7 +93,7 @@ jobs:
         PYTEST_ADDOPTS: "--report-log=output-${{ matrix.python-version }}-log.jsonl"
       run: |
         echo "Using Hypothesis profile: $HYPOTHESIS_PROFILE"
-        hatch env run --env "$HATCH_ENV" run-hypothesis
+        just hypothesis
 
     # explicitly save the cache so it gets updated, also do this even if it fails.
     - name: Save cached hypothesis directory

.github/workflows/lint.yml

@@ -30,4 +30,26 @@ jobs:
         uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
-      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
+      # `uvx prek` builds each hook's environment from scratch, so cache them the
+      # way the prek action used to. Keyed on the hook config: a new pinned rev or
+      # a new hook is exactly when the cached environments stop being valid.
+      - name: Cache prek hook environments
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/prek
+          # Justfile is hashed too: prek_version lives there, and a bumped prek
+          # must not restore a store built by the previous one. No restore-keys
+          # fallback for the same reason.
+          key: prek-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml', 'Justfile') }}
+      - name: Lint
+        run: just lint
+      - name: Check justfile formatting
+        # After the linters, and never masking them: this is cosmetic, and a
+        # mis-formatted recipe should not cost someone their ruff/mypy results.
+        if: always()
+        run: just just-check

.github/workflows/test.yml

@@ -69,18 +69,22 @@ jobs:
       uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
         HYPOTHESIS_PROFILE: ci
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just coverage
     - name: Upload coverage
       if: ${{ matrix.dependency-set == 'optional' && matrix.os == 'ubuntu-latest' }}
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
@@ -118,17 +122,21 @@ jobs:
       uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: ${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
         HATCH_ENV: ${{ matrix.dependency-set }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just coverage
     - name: Upload coverage
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
       with:
@@ -153,12 +161,17 @@ jobs:
       uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       run: |
-        hatch run doctest:pip list
+        HATCH_ENV=doctest just setup
     - name: Run Tests
       run: |
-        hatch run doctest:test
+        just doctest
 
   benchmarks:
     name: Benchmark smoke test
@@ -177,11 +190,16 @@ jobs:
       uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Run Benchmarks
       env:
         ZARR_BENCHMARK_CLEAR_CACHE: '1'
       run: |
-        hatch env run --env "test.py3.13-minimal" run-benchmark
+        HATCH_ENV=test.py3.13-minimal just benchmark
 
   test-complete:
     name: Test complete

.github/workflows/zarr-http-server.yml

@@ -53,11 +53,10 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Sync test dependency groups
         # The examples group carries the deps the README examples need, so the
         # test that reads a served array back with a zarr client runs here
@@ -80,11 +79,10 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Run ruff
         run: just lint
 
@@ -106,11 +104,10 @@ jobs:
       - name: Set up Python
         run: uv python install 3.12
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Sync test dependency group
         run: uv sync --group test --python 3.12
       - name: Run mypy
@@ -132,11 +129,10 @@ jobs:
         with:
           enable-cache: true
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Build docs
         run: just docs-check
 

.github/workflows/zarr-indexing.yml

@@ -40,11 +40,10 @@ jobs:
         with:
           enable-cache: true
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
       # The suite imports nothing from `zarr`; it runs against the repo-root
@@ -73,11 +72,10 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Run ruff
         # The ruff version pin lives in packages/zarr-indexing/justfile.
         run: just lint
@@ -102,11 +100,10 @@ jobs:
       - name: Sync test dependency group
         run: uv sync --group test --python 3.12
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Run pyright
         # The pyright invocation lives in packages/zarr-indexing/justfile.
         run: just typecheck
@@ -127,11 +124,10 @@ jobs:
         with:
           enable-cache: true
       - name: Install just
-        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
         with:
-          # Pin the tool, not just the action: without this the action
-          # installs whatever just is newest at run time.
-          just-version: 1.58.0
+          repo: casey/just
+          version: 1.58.0
       - name: Build docs
         # The strict mkdocs build lives in packages/zarr-indexing/justfile.
         run: just docs-check