fix: pin setuptools<81 so runner works on a fresh install

[Wenzel]

A cold-start audit found that the first command a new contributor runs crashes.

The bug

$ pip install oswatcher-plugins   # succeeds, 0.14.1
$ runner --help
  File ".../stopit/__init__.py", line 10, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

Reproduced on a clean Python 3.12 venv.

pypeln pulls in stopit, which imports pkg_resources at module load purely to populate __version__. setuptools 81 removed pkg_resources, and the existing setuptools = "*" constraint resolved to 84, so the dependency added to prevent this exact failure had gone stale.

This matters more than a normal packaging nit: CONTRIBUTING.md names writing a plugin as "the lowest-friction way in" and routes newcomers straight here.

The fix

setuptools = "<81", which is what setuptools' own deprecation warning recommends.

Considered and rejected: upgrading stopit (1.1.2 is the latest release and still carries the import; upstream looks abandoned), and dropping pypeln (used in symbols.py for pl.process.map parallelism, so removing it is a behaviour-changing refactor of the highest-value plugin and does not belong in an install fix).

Also in this PR

The README documented runner <plugin_name> <branch_name>. The real signature is runner COMMIT_HASH PLUGIN_TYPE_STR, so the arguments were in the wrong order and it takes a commit hash, not a branch. Corrected, with the available plugin names and a pointer to --force.

Verification

Built the wheel, installed it into a fresh venv, and ran the command that previously crashed:

$ pip install dist/oswatcher_plugins-0.14.1-py3-none-any.whl
$ pip show setuptools | grep Version
Version: 80.10.2
$ runner --help
Usage: runner [OPTIONS] COMMIT_HASH PLUGIN_TYPE_STR

Known remaining issue

stopit still emits a UserWarning about pkg_resources on every invocation. Cosmetic and out of scope here; the real resolution is dropping pypeln, which deserves its own PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FNgjQ6o613ULuMRGhLnyUU