Add plugin helper with agent skill for updating plugins

src/plugin_helper/userdata.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import tarfile
+from datetime import datetime, timezone
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+
+from .fsutil import sha256_file
+from .state import backups_dir
+
+
+def backup_userdata(instance: str, instance_path: Path, state_root: Path) -> dict[str, Any]:
+    source = instance_path / "UserData"
+    if not source.is_dir():
+        raise FileNotFoundError(f"UserData directory not found: {source}")
+
+    created_at = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    destination = backups_dir(state_root, instance) / f"userdata-{created_at}.tar.gz"
+    files: list[dict[str, Any]] = []
+    total_size = 0
+    for path in sorted(item for item in source.rglob("*") if item.is_file()):
+        rel = path.relative_to(instance_path).as_posix()
+        size = path.stat().st_size
+        total_size += size
+        files.append({"path": rel, "size": size, "sha256": sha256_file(path)})
+
+    manifest = {
+        "createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "instance": instance,
+        "source": str(source),
+        "fileCount": len(files),
+        "totalSize": total_size,
+        "files": files,
+    }
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(destination, "w:gz") as archive:
+        archive.add(source, arcname="UserData")
+        with NamedTemporaryFile("w", encoding="utf-8", suffix=".json") as handle:
+            json.dump(manifest, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            archive.add(handle.name, arcname="manifest.json")
+    return {"archive": str(destination), "manifest": manifest}