chore: import upstream snapshot with attribution

scripts/pb_setup.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+PocketBase collection bootstrap script.
+
+Run this once after starting PocketBase for the first time:
+
+    python scripts/pb_setup.py
+
+Requires integrations.pocketbase_url, integrations.pocketbase_admin_email, and
+integrations.pocketbase_admin_password in data/user/settings/integrations.json.
+
+Safe to re-run — existing collections are left untouched.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+# Allow running from project root without installing the package.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from deeptutor.services.config import load_integrations_settings
+
+_INTEGRATIONS = load_integrations_settings()
+POCKETBASE_BASE_URL = str(_INTEGRATIONS["pocketbase_url"]).rstrip("/")
+ADMIN_EMAIL = str(_INTEGRATIONS["pocketbase_admin_email"])
+ADMIN_PASSWORD = str(_INTEGRATIONS["pocketbase_admin_password"])
+
+
+def _require_env():
+    missing = []
+    if not POCKETBASE_BASE_URL:
+        missing.append("integrations.pocketbase_url")
+    if not ADMIN_EMAIL:
+        missing.append("integrations.pocketbase_admin_email")
+    if not ADMIN_PASSWORD:
+        missing.append("integrations.pocketbase_admin_password")
+    if missing:
+        print(f"ERROR: Missing required integration settings: {', '.join(missing)}")
+        print("Set them in data/user/settings/integrations.json before running this script.")
+        sys.exit(1)
+
+
+def _get_client():
+    try:
+        from pocketbase import PocketBase  # type: ignore[import]
+    except ImportError:
+        print("ERROR: pocketbase package not installed.")
+        print("Run: pip install pocketbase")
+        sys.exit(1)
+
+    pb = PocketBase(POCKETBASE_BASE_URL)
+    pb.admins.auth_with_password(ADMIN_EMAIL, ADMIN_PASSWORD)
+    return pb
+
+
+def _existing_collections(pb) -> set[str]:
+    try:
+        collections = pb.collections.get_full_list()
+        return {c.name for c in collections}
+    except Exception:
+        return set()
+
+
+def _create_if_missing(pb, name: str, schema: dict, existing: set[str]):
+    if name in existing:
+        print(f"  skip  {name} (already exists)")
+        return
+    try:
+        pb.collections.create(schema)
+        print(f"  create {name}")
+    except Exception as exc:
+        print(f"  ERROR creating {name}: {exc}")
+
+
+def main():
+    _require_env()
+    print(f"Connecting to PocketBase at {POCKETBASE_BASE_URL} ...")
+    pb = _get_client()
+    print("Authenticated as admin.")
+
+    existing = _existing_collections(pb)
+    print(f"Found {len(existing)} existing collection(s): {sorted(existing) or '(none)'}\n")
+
+    # Access control is enforced in the application layer, not by PocketBase
+    # collection rules: the backend connects with a single admin-authenticated
+    # client (see services/pocketbase_client.py), which bypasses collection
+    # RBAC entirely, so the rules below stay empty by design. Per-user session
+    # isolation is implemented in PocketBaseSessionStore by stamping every
+    # session row with ``user_id`` and filtering every query by the current
+    # user. Do NOT rely on these listRule/viewRule strings for isolation.
+    collections = [
+        # ----------------------------------------------------------------
+        # sessions  (``user_id`` populated + filtered by PocketBaseSessionStore)
+        # ----------------------------------------------------------------
+        {
+            "name": "sessions",
+            "type": "base",
+            "schema": [
+                {"name": "session_id", "type": "text", "required": True},
+                {"name": "user_id", "type": "text", "required": False},
+                {"name": "title", "type": "text", "required": False},
+                {"name": "compressed_summary", "type": "text", "required": False},
+                {"name": "summary_up_to_msg_id", "type": "number", "required": False},
+                {"name": "preferences_json", "type": "json", "required": False},
+                {"name": "capability", "type": "text", "required": False},
+                {"name": "status", "type": "text", "required": False},
+            ],
+            "listRule": "",
+            "viewRule": "",
+            "createRule": "",
+            "updateRule": "",
+            "deleteRule": "",
+        },
+        # ----------------------------------------------------------------
+        # messages
+        # ----------------------------------------------------------------
+        {
+            "name": "messages",
+            "type": "base",
+            "schema": [
+                {"name": "session_id", "type": "text", "required": True},
+                {"name": "role", "type": "text", "required": True},
+                {"name": "content", "type": "text", "required": False},
+                {"name": "capability", "type": "text", "required": False},
+                {"name": "events_json", "type": "json", "required": False},
+                {"name": "attachments_json", "type": "json", "required": False},
+                {"name": "msg_created_at", "type": "number", "required": False},
+            ],
+            "listRule": "",
+            "viewRule": "",
+            "createRule": "",
+            "updateRule": "",
+            "deleteRule": "",
+        },
+        # ----------------------------------------------------------------
+        # turns
+        # ----------------------------------------------------------------
+        {
+            "name": "turns",
+            "type": "base",
+            "schema": [
+                {"name": "turn_id", "type": "text", "required": True},
+                {"name": "session_id", "type": "text", "required": True},
+                {"name": "capability", "type": "text", "required": False},
+                {"name": "status", "type": "text", "required": False},
+                {"name": "error", "type": "text", "required": False},
+                {"name": "turn_created_at", "type": "number", "required": False},
+                {"name": "turn_updated_at", "type": "number", "required": False},
+                {"name": "finished_at", "type": "number", "required": False},
+            ],
+            "listRule": "",
+            "viewRule": "",
+            "createRule": "",
+            "updateRule": "",
+            "deleteRule": "",
+        },
+        # ----------------------------------------------------------------
+        # turn_events
+        # ----------------------------------------------------------------
+        {
+            "name": "turn_events",
+            "type": "base",
+            "schema": [
+                {"name": "turn_id", "type": "text", "required": True},
+                {"name": "session_id", "type": "text", "required": False},
+                {"name": "seq", "type": "number", "required": True},
+                {"name": "type", "type": "text", "required": False},
+                {"name": "source", "type": "text", "required": False},
+                {"name": "stage", "type": "text", "required": False},
+                {"name": "content", "type": "text", "required": False},
+                {"name": "metadata_json", "type": "json", "required": False},
+                {"name": "event_timestamp", "type": "number", "required": False},
+            ],
+            "listRule": "",
+            "viewRule": "",
+            "createRule": "",
+            "updateRule": "",
+            "deleteRule": "",
+        },
+        # ----------------------------------------------------------------
+        # knowledge_bases
+        # ----------------------------------------------------------------
+        {
+            "name": "knowledge_bases",
+            "type": "base",
+            "schema": [
+                {"name": "kb_name", "type": "text", "required": True},
+                {"name": "user_id", "type": "text", "required": False},
+                {"name": "description", "type": "text", "required": False},
+                {"name": "rag_provider", "type": "text", "required": False},
+                {"name": "needs_reindex", "type": "bool", "required": False},
+                {"name": "status", "type": "text", "required": False},
+                {"name": "kb_created_at", "type": "text", "required": False},
+                {
+                    "name": "raw_files",
+                    "type": "file",
+                    "required": False,
+                    "options": {"maxSelect": 99, "maxSize": 52428800},
+                },
+            ],
+            "listRule": "",
+            "viewRule": "",
+            "createRule": "",
+            "updateRule": "",
+            "deleteRule": "",
+        },
+    ]
+
+    print("Creating collections:")
+    for col in collections:
+        _create_if_missing(pb, col["name"], col, existing)
+
+    print("\nDone. PocketBase collections are ready.")
+    print(f"Open the admin panel at {POCKETBASE_BASE_URL}/_/ to view and configure collections.")
+
+
+if __name__ == "__main__":
+    main()