feat: add plugin module

Author: daxartio

docs/plugin-protocol.md

@@ -600,6 +600,70 @@ Request from plugin:
 
 Supported `level` values are `info`, `warning`, and `error`.
 
+### Plugin-Initiated Entity Updates
+
+Plugins may request changes to SportOrg entities using the same per-type update
+methods used by host notifications:
+
+- `sportorg.race.update`
+- `sportorg.result.update`
+- `sportorg.person.update`
+- `sportorg.group.update`
+- `sportorg.organization.update`
+- `sportorg.course.update`
+- `sportorg.entity.update`
+
+The request `params` use the common update envelope from the Entity Updates
+section. `operation` may be `created`, `updated`, `deleted`, or `snapshot`.
+For `deleted`, `entity` must include at least `object` and `id`.
+
+Request from plugin:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "plugin-3",
+  "method": "sportorg.person.update",
+  "params": {
+    "operation": "updated",
+    "race_id": "37a31618-47d0-4120-a11c-2d113df839a0",
+    "entity": {
+      "object": "Person",
+      "id": "bb280db8-dce1-4245-9e65-b4e8b234e7db",
+      "name": "John",
+      "surname": "Smith",
+      "middle_name": "",
+      "card_number": 123456,
+      "bib": 101,
+      "birth_date": "1990-01-01",
+      "group_id": "6245b064-cc9f-4fa7-a80f-ec34a730973e",
+      "organization_id": "a90ac671-ea03-4187-b380-4d2305ec6b8b"
+    }
+  }
+}
+```
+
+Response from SportOrg:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "plugin-3",
+  "result": {
+    "updated": true,
+    "operation": "updated",
+    "object": "Person",
+    "id": "bb280db8-dce1-4245-9e65-b4e8b234e7db"
+  }
+}
+```
+
+The method-specific update must match `entity.object`; for example
+`sportorg.result.update` accepts `Result`, `ResultManual`,
+`ResultSportident`, `ResultSFR`, `ResultSportiduino`, `ResultRfidImpinj`,
+`ResultSrpid`, and `ResultHuichang`. `sportorg.entity.update` is the generic
+fallback for future entity types.
+
 ## Settings Persistence
 
 SportOrg keeps plugin settings in the host configuration store under the plugin

plugin-example/plugin_example/__init__.py

@@ -0,0 +1 @@
+__all__ = []

plugin-example/plugin_example/__main__.py

@@ -0,0 +1,239 @@
+import json
+import sys
+from typing import Any, Dict
+
+PLUGIN_INFO = {
+    "id": "sportorg.example.python",
+    "name": "Python Example Plugin",
+    "version": "0.1.0",
+}
+
+
+class ExamplePlugin:
+    def __init__(self) -> None:
+        self.settings: Dict[str, Any] = {
+            "auto_publish": False,
+            "executions": 0,
+        }
+        self.race: Dict[str, Any] = {}
+        self.update_counts = {
+            "race": 0,
+            "result": 0,
+            "person": 0,
+            "group": 0,
+            "organization": 0,
+            "course": 0,
+            "entity": 0,
+        }
+
+    def handle_request(self, message: Dict[str, Any]) -> None:
+        method = str(message.get("method", ""))
+        request_id = message.get("id")
+        params = message.get("params", {})
+        if not isinstance(params, dict):
+            self.write_error(request_id, -32602, "Invalid params")
+            return
+
+        if method == "plugin.initialize":
+            plugin_settings = (
+                params.get("settings", {}).get("plugin", {})
+                if isinstance(params.get("settings", {}), dict)
+                else {}
+            )
+            if isinstance(plugin_settings, dict):
+                self.settings.update(plugin_settings)
+            race = params.get("race", {})
+            if isinstance(race, dict):
+                self.race = race
+            self.write_result(
+                request_id,
+                {
+                    "plugin": PLUGIN_INFO,
+                    "capabilities": {
+                        "menu": True,
+                        "race_updates": True,
+                        "result_updates": True,
+                        "person_updates": True,
+                        "group_updates": True,
+                        "organization_updates": True,
+                        "course_updates": True,
+                        "settings": True,
+                    },
+                    "settings": self.settings,
+                },
+            )
+            return
+
+        if method == "plugin.menu.get":
+            self.write_result(
+                request_id,
+                {
+                    "items": [
+                        {
+                            "id": "show_summary",
+                            "label": "Show plugin summary",
+                            "tooltip": "Show how many updates the example plugin received",
+                            "enabled": True,
+                            "visible": True,
+                            "group": "Example",
+                            "order": 100,
+                        },
+                        {
+                            "id": "toggle_auto_publish",
+                            "label": self._toggle_label(),
+                            "enabled": True,
+                            "visible": True,
+                            "group": "Example",
+                            "order": 200,
+                        },
+                        {
+                            "id": "update_race_description",
+                            "label": "Update race description",
+                            "enabled": bool(self.race),
+                            "visible": True,
+                            "group": "Example",
+                            "order": 300,
+                        },
+                    ]
+                },
+            )
+            return
+
+        if method == "plugin.menu.execute":
+            action_id = str(params.get("id", ""))
+            if action_id == "show_summary":
+                self.settings["executions"] = (
+                    int(self.settings.get("executions", 0)) + 1
+                )
+                self.write_result(
+                    request_id,
+                    {
+                        "status": "ok",
+                        "message": self._summary_message(),
+                        "settings": self.settings,
+                    },
+                )
+                return
+
+            if action_id == "toggle_auto_publish":
+                self.settings["auto_publish"] = not bool(
+                    self.settings.get("auto_publish", False)
+                )
+                self.write_result(
+                    request_id,
+                    {
+                        "status": "ok",
+                        "message": self._toggle_label(),
+                        "settings": self.settings,
+                    },
+                )
+                return
+
+            if action_id == "update_race_description":
+                self.send_race_description_update()
+                self.write_result(
+                    request_id,
+                    {
+                        "status": "ok",
+                        "message": "Race update sent from example plugin",
+                    },
+                )
+                return
+
+            self.write_error(request_id, -32601, "Unknown menu action")
+            return
+
+        self.write_error(request_id, -32601, "Method not found")
+
+    def handle_notification(self, message: Dict[str, Any]) -> None:
+        method = str(message.get("method", ""))
+        if method == "plugin.shutdown":
+            raise SystemExit(0)
+
+        prefix = "sportorg."
+        suffix = ".update"
+        if method.startswith(prefix) and method.endswith(suffix):
+            entity_name = method[len(prefix) : -len(suffix)]
+            if entity_name in self.update_counts:
+                self.update_counts[entity_name] += 1
+
+    def write_result(self, request_id: Any, result: Dict[str, Any]) -> None:
+        self.write_message({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    def write_error(self, request_id: Any, code: int, message: str) -> None:
+        self.write_message(
+            {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "error": {
+                    "code": code,
+                    "message": message,
+                },
+            }
+        )
+
+    def write_message(self, message: Dict[str, Any]) -> None:
+        sys.stdout.write(json.dumps(message, ensure_ascii=False) + "\n")
+        sys.stdout.flush()
+
+    def send_race_description_update(self) -> None:
+        if not self.race:
+            return
+
+        race_entity = dict(self.race)
+        race_data = dict(race_entity.get("data", {}))
+        race_data["description"] = "Updated by Python Example Plugin"
+        race_entity["data"] = race_data
+        self.write_message(
+            {
+                "jsonrpc": "2.0",
+                "method": "sportorg.race.update",
+                "params": {
+                    "operation": "updated",
+                    "race_id": race_entity.get("id", ""),
+                    "entity": race_entity,
+                },
+            }
+        )
+
+    def _summary_message(self) -> str:
+        parts = [
+            "{}={}".format(key, value)
+            for key, value in sorted(self.update_counts.items())
+            if value
+        ]
+        if not parts:
+            return "Example plugin is connected; no updates received yet"
+        return "Example plugin updates: {}".format(", ".join(parts))
+
+    def _toggle_label(self) -> str:
+        if bool(self.settings.get("auto_publish", False)):
+            return "Disable auto publish"
+        return "Enable auto publish"
+
+
+def main() -> None:
+    plugin = ExamplePlugin()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError as exc:
+            sys.stderr.write("Invalid JSON: {}\n".format(exc))
+            sys.stderr.flush()
+            continue
+
+        if not isinstance(message, dict):
+            continue
+
+        if "id" in message and "method" in message:
+            plugin.handle_request(message)
+        elif "method" in message:
+            plugin.handle_notification(message)
+
+
+if __name__ == "__main__":
+    main()

plugin-example/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "sportorg-plugin-example"
+version = "0.1.0"
+description = "Example SportOrg stdio JSON-RPC plugin"
+requires-python = ">=3.8"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["plugin_example"]