From 772fb2ab4fbc44b193c36bd16c7eb052dcbe618a Mon Sep 17 00:00:00 2001
From: Mathieu Tarral <mathieu.tarral@protonmail.com>
Date: Sun, 23 Aug 2026 09:30:42 +0200
Subject: [PATCH] fix: pin setuptools<81 so `runner` works on a fresh install

`pip install oswatcher-plugins` followed by `runner --help` crashed with
ModuleNotFoundError: No module named 'pkg_resources' on any clean Python
3.12 environment.

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
that was added to prevent this exact failure had gone stale. stopit 1.1.2
is the latest release and still carries the import, so pinning is the
available fix.

This is the first command a new contributor runs: CONTRIBUTING.md names
writing a plugin as the lowest-friction way to contribute and routes here.

Also corrects the README usage line, which documented the arguments in the
wrong order and against a branch name. The real signature is
`runner COMMIT_HASH PLUGIN_TYPE_STR`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNgjQ6o613ULuMRGhLnyUU
---
 README.md      | 10 +++++++---
 poetry.lock    |  2 +-
 pyproject.toml |  8 +++++---
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index c39238b..905b3ec 100644
--- a/README.md
+++ b/README.md
@@ -20,14 +20,18 @@ pip install oswatcher-plugins
 
 ## Usage
 
-Plugins are run via the `runner` CLI against a [neogit](https://github.com/OSWatcher/neogit) branch:
+Plugins are run via the `runner` CLI against a single [neogit](https://github.com/OSWatcher/neogit) commit:
 
 ```bash
-runner <plugin_name> <branch_name>
+runner <commit_hash> <plugin_name>
 # example:
-runner symbols Windows_10_21H2
+runner 930b7dc140b50b00c192a9ae7f97174823deb378 SYMBOLS
 ```
 
+Available plugins: `FILETYPE`, `SYMBOLS`, `WINREG`, `SYSCALLS`, `LINUX_SYMBOLS`
+(the name is case-insensitive). Use `runner --help` for the full option list,
+including `--force` to rerun a plugin that has already been executed on the commit.
+
 ## Requirements
 
 - Python 3.11+
diff --git a/poetry.lock b/poetry.lock
index 0720cb8..6c78158 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1926,4 +1926,4 @@ files = [
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.11"
-content-hash = "6ce9b4b2f1491e1106e5bffc6b04fc422a50496db8442401b1c4740d364ea25f"
+content-hash = "727653a4583763327f9bcb38bfc287c8d057606582f4d7646c212f6e0bc72bbf"
diff --git a/pyproject.toml b/pyproject.toml
index 58ff01c..70714ce 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -35,10 +35,12 @@ regipy = "^4.1.1"
 jsonschema = "^4.21.1"
 pypeln = "^0.4.9"
 requests = "^2.31"
-# setuptools required for pkg_resources compatibility
-# pypeln -> stopit -> pkg_resources (may be missing in some virtual environments)
+# setuptools pinned <81 for pkg_resources availability.
+# pypeln -> stopit imports pkg_resources at module load, and setuptools 81
+# removed it, so an unpinned setuptools breaks `runner` on a fresh install.
+# stopit 1.1.2 is the latest release and still carries the import.
 # See: https://github.com/glenfant/stopit/issues/32
-setuptools = "*"
+setuptools = "<81"
 gitpython = "^3.1.0"