chore: centralize development and CI verbs in just

[d-v-b]

Adds a justfile with package lifecycle verbs. Pretty much #4096 minus the removal of hatch.

Would appreciate feedback from other devs, since this (hopefully) simplifies our dev environment.

🤖 AI text below 🤖

Development commands currently live in Hatch scripts, workflow YAML, and contributor instructions. This draft makes the root Justfile the command interface: just test, just coverage, just benchmark, just docs-check, just lint, just build, and changelog/lock helpers define the operations used locally and by root CI.

Hatch continues to manage Python environments and dependencies. HATCH_ENV=test.py3.13-minimal just coverage, for example, selects an environment while the recipe defines the command. The Hatch script tables are removed; contributor instructions, root workflows, Read the Docs, and the type-check hook now call just. Root recipes just zarr-metadata, just zarr-indexing, and just zarr-http-server delegate to the existing package justfiles, preserving their working directories and command definitions.

Attribution

This extracts the Justfile portions of Max Jones's commits 98dcde719834bcd6fc010ffc4b07be5ae02fc2e4 and 693f694e50b9ae4cd7c6b0d93238b9ee9f8f6865 from #4096, preserving attribution in two commits, then adapts them to current main without taking the Hatch-removal changes. Hatch stays.

Design notes worth review

• Tool versions are pinned, including prek. prek_version := "0.5.3" in the Justfile, so uvx prek@… cannot float onto a new release mid-week. The lint workflow caches prek hook environments (~/.cache/prek) to replace the caching the prek action used to provide.
• just gpu reads GPU_HATCH_ENV, not HATCH_ENV. A recipe that defaulted through env("HATCH_ENV", "gputest.py3.12") would silently honour a CPU test environment exported in the caller's shell and run pytest -m gpu against an env built without the gpu feature. The separate name makes that unrepresentable.
• The mypy pre-commit hook keeps its direct uv run --frozen mypy entry rather than routing through just typecheck, so just does not become a prerequisite for committing in an existing clone.
• just hooks-install installs prek as a persistent uv tool, not via uvx. prek writes a hook shim into .git/hooks that hard-codes the binary path it was installed from; under uvx that path is a uv cache archive entry, which disappears on the next uv cache prune.
• The release and nightly-wheel jobs still call hatch build directly. just build is a pure alias, and it is not worth adding a package fetch to the path that publishes artifacts.
• just just-check covers all four justfiles, root plus packages/*/justfile.

Validation

CI on the fork (d-v-b#339) is green on this branch, including the jobs these changes touch:

Job	Result
Lint	pass, 57s — uvx prek@0.5.3 run --all-files, all hooks pass; prek cache saved 50.9 MB for subsequent runs
Check changelog entries	pass — all four checks in 220 ms total, no environment build
Build wheel on ubuntu-latest / Test distribution artifacts	pass
Check docs, doctests	pass
Test matrix incl. os=windows-latest, macOS, min_deps	pass

Locally: quoted pytest filters survive the recipes (just test -k 'array and resize' deselects correctly); package delegation runs with the package directory as its working directory; just --fmt --check passes on all four justfiles and fails when one is unformatted; XML/JUnit and HTML coverage reports generate; the sdist includes Justfile and ci/.

A note on the CodSpeed run

An earlier revision added actions/setup-python to codspeed.yml, so that the job's pip install rust-just would have an interpreter. That also changed which interpreter Hatch built test.py3.12-minimal on, replacing the runner's own Python with /opt/hostedtoolcache/Python/3.12.5/arm64. CodSpeed reported it as a 12.97% degradation across 26 benchmarks, spread only from -12.76% to -13.99% across slice indexing, sharded Morton indexing, three array shapes and two store types — and flagged "different runtime environments detected". Nothing in this branch touches src/, tests/benchmarks/ or packages/, so a 1.2-point spread over unrelated benchmarks is an interpreter swap, not a regression.

That step is gone. just is now installed with extractions/setup-just, matching the three package workflows, so the benchmark job sets up no interpreter of its own and Hatch resolves the same Python the baseline used. The benchmarks need a re-run (re-apply the benchmark label — the workflow triggers on labeled, not on push) before the comparison means anything; the numbers on the earlier run should not be acknowledged as a regression.

Still not exercised: gpu_test needs the self-hosted GPU runner, so the GPU_HATCH_ENV change is unverified in CI, and the Read the Docs build is only reasoned about, not run.

Filed as a draft for review of the command interface and the CI transition.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-metadata | 🛠️ Build #34615178 | 📁 Comparing ea82101 against latest (f2ab3d5)

  🔍 Preview build  

No files changed.

[read-the-docs-community]

Documentation build overview

📚 zarr-indexing | 🛠️ Build #34615177 | 📁 Comparing ea82101 against latest (f2ab3d5)

  🔍 Preview build  

No files changed.

[codspeed]

Merging this PR will not alter performance

✅ 113 untouched benchmarks
⏩ 37 skipped benchmarks¹

---

_{Comparing d-v-b:codex/justfile-verbs (7014615) with main (ba883a5)²}

Footnotes

1. 37 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (20f82f1) during the generation of this report, so ba883a5 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[d-v-b]

perf regression reported in the benchmark was a false alarm due to using a different (slower) runner for the benchmark job

[maxrjones]

I've been using just for other projects and quite like it. I support these changes, especially if it makes the development more ergonomic for other devs.

[ilan-gold]

I like this quite a bit more :) just is great, thanks for pushing us on this @maxrjones.

Why not make the hatch env an argument to the just alongside the option of an env variable?

For CI, the variable makes sense, but locally, I would think setting an env variable on the same lien as running just coverage or something is odd