From 200d319fb041d41a346122adcf67baf6338f9750 Mon Sep 17 00:00:00 2001 From: Developer Date: Fri, 19 Jun 2026 20:07:47 +0000 Subject: [PATCH] feat(widgets): add backend CRUD, registry, and default seeding Introduce a closed, compile-time widget registry and backend CRUD for dashboard widget instances. - Add dashboard_widgets SQLite table in SettingsStore with CRUD helpers and default seeding (Jellyfin + Backups) on first install. - Add Pydantic models with credential-key and secret-value rejection. - Add widgets router: /api/widgets/sources, /types, /instances CRUD. - Call ensure_defaults() in app lifespan so fresh installs seed defaults. - Add backend tests covering registry, CRUD, validation, and seeding. - Include SDD artifacts: exploration, proposal, spec, design, tasks. --- backend/src/media_library_viewer_api/main.py | 6 + .../models/widgets.py | 95 +++ .../routers/widgets.py | 113 +++ .../services/settings_store.py | 183 ++++- .../widgets/__init__.py | 1 + .../widgets/registry.py | 187 +++++ backend/tests/test_widgets.py | 291 +++++++ .../apply-progress.md | 64 ++ .../configurable-dashboard-widgets/design.md | 749 ++++++++++++++++++ .../exploration.md | 210 +++++ .../proposal.md | 155 ++++ .../specs/dashboard-widgets/spec.md | 576 ++++++++++++++ .../configurable-dashboard-widgets/tasks.md | 270 +++++++ 13 files changed, 2894 insertions(+), 6 deletions(-) create mode 100644 backend/src/media_library_viewer_api/models/widgets.py create mode 100644 backend/src/media_library_viewer_api/routers/widgets.py create mode 100644 backend/src/media_library_viewer_api/widgets/__init__.py create mode 100644 backend/src/media_library_viewer_api/widgets/registry.py create mode 100644 backend/tests/test_widgets.py create mode 100644 openspec/changes/configurable-dashboard-widgets/apply-progress.md create mode 100644 openspec/changes/configurable-dashboard-widgets/design.md create mode 100644 openspec/changes/configurable-dashboard-widgets/exploration.md create mode 100644 openspec/changes/configurable-dashboard-widgets/proposal.md create mode 100644 openspec/changes/configurable-dashboard-widgets/specs/dashboard-widgets/spec.md create mode 100644 openspec/changes/configurable-dashboard-widgets/tasks.md diff --git a/backend/src/media_library_viewer_api/main.py b/backend/src/media_library_viewer_api/main.py index 3b6d609..e424e9b 100644 --- a/backend/src/media_library_viewer_api/main.py +++ b/backend/src/media_library_viewer_api/main.py @@ -23,6 +23,7 @@ from media_library_viewer_api.observability import ( ) from media_library_viewer_api.routers import backups as backups_router from media_library_viewer_api.routers import dashboard, files, jobs, media, monitoring, tasks, users +from media_library_viewer_api.routers import widgets as widgets_router from media_library_viewer_api.routers.settings import router as settings_router from .services.backup_poller import get_backup_poller @@ -45,6 +46,10 @@ async def lifespan(app: FastAPI): write_prometheus_targets(get_settings_store()) except Exception: logger.exception("Failed to write Prometheus file-SD targets during startup") + try: + get_settings_store().ensure_defaults() + except Exception: + logger.exception("Failed to seed default settings during startup") mail_queue = get_mail_queue() backup_poller = get_backup_poller() mail_queue.start() @@ -137,6 +142,7 @@ app.include_router(users.router) app.include_router(tasks.router) app.include_router(settings_router) app.include_router(backups_router.router) +app.include_router(widgets_router.router) @app.get("/api/health") diff --git a/backend/src/media_library_viewer_api/models/widgets.py b/backend/src/media_library_viewer_api/models/widgets.py new file mode 100644 index 0000000..e36dad2 --- /dev/null +++ b/backend/src/media_library_viewer_api/models/widgets.py @@ -0,0 +1,95 @@ +"""Pydantic models for the dashboard widget system.""" + +from typing import Any + +from pydantic import BaseModel, Field, field_validator + +FORBIDDEN_CONFIG_KEYS = { + "password", + "token", + "secret", + "api_key", + "apikey", + "private_key", + "passphrase", + "credential", +} + + +def _looks_secret(value: Any) -> bool: + """Heuristic to detect values that look like secrets/tokens.""" + if not isinstance(value, str) or not value.strip(): + return False + lowered = value.lower() + if value.startswith("sk-") or value.startswith("eyJ"): + return True + if len(value) > 64 and lowered.isalnum(): + return True + return False + + +def _validate_config_keys(config: dict[str, Any]) -> dict[str, Any]: + """Recursively reject credential keys and secret-looking values.""" + for key, value in config.items(): + if key.lower() in FORBIDDEN_CONFIG_KEYS: + raise ValueError(f"Credential key '{key}' is not allowed in widget config") + if _looks_secret(value): + raise ValueError(f"Value for '{key}' looks like a secret") + if isinstance(value, dict): + _validate_config_keys(value) + elif isinstance(value, list): + for item in value: + if isinstance(item, dict): + _validate_config_keys(item) + return config + + +class _WidgetInstanceBase(BaseModel): + """Shared fields between input and output widget models.""" + + addon_id: str + widget_type: str + title: str = Field(..., min_length=1) + config: dict[str, Any] = Field(default_factory=dict) + enabled: bool = True + sort_order: int = Field(default=0, ge=0) + + @field_validator("config") + @classmethod + def reject_credential_keys(cls, value: dict[str, Any]) -> dict[str, Any]: + return _validate_config_keys(value or {}) + + +class WidgetInstanceInput(_WidgetInstanceBase): + """Payload for creating or updating a widget instance.""" + + id: str | None = None + + +class WidgetInstance(_WidgetInstanceBase): + """Persisted widget instance returned by the API.""" + + id: str + created_at: int + updated_at: int + + +class WidgetTypeInfo(BaseModel): + """Metadata about a built-in widget type.""" + + addon_id: str + widget_type: str + name: str + description: str + source_type: str + config_schema: dict[str, Any] + + +class WidgetDataResponse(BaseModel): + """Response from the per-widget data endpoint.""" + + widget_id: str + widget_type: str + data: dict[str, Any] | None = None + error: str | None = None + fetched_at: int diff --git a/backend/src/media_library_viewer_api/routers/widgets.py b/backend/src/media_library_viewer_api/routers/widgets.py new file mode 100644 index 0000000..649cfdf --- /dev/null +++ b/backend/src/media_library_viewer_api/routers/widgets.py @@ -0,0 +1,113 @@ +"""REST API for dashboard widget instances and registry metadata.""" + +from typing import Any + +from fastapi import APIRouter, Depends, HTTPException, status + +from media_library_viewer_api.dependencies import get_settings_store +from media_library_viewer_api.models.widgets import WidgetInstance, WidgetInstanceInput, WidgetTypeInfo +from media_library_viewer_api.services.settings_store import SettingsStore +from media_library_viewer_api.widgets.registry import ( + list_source_types, + list_widget_types, + validate_config, +) + +router = APIRouter(prefix="/api/widgets", tags=["widgets"]) + + +def _registry_for_type(widget_type: str) -> dict[str, Any]: + from media_library_viewer_api.widgets.registry import WIDGET_REGISTRY + + info = WIDGET_REGISTRY.get(widget_type) + if not info: + raise HTTPException( + status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, + detail=f"Unknown widget type: {widget_type}", + ) + return info + + +def _validate_widget_input(body: WidgetInstanceInput) -> None: + """Validate widget_type/addon_id match and config schema.""" + info = _registry_for_type(body.widget_type) + expected_addon = info["addon_id"] + if body.addon_id != expected_addon: + raise HTTPException( + status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, + detail=( + f"Widget type '{body.widget_type}' belongs to addon " + f"'{expected_addon}', not '{body.addon_id}'" + ), + ) + try: + validate_config(body.widget_type, body.config) + except ValueError as exc: + raise HTTPException( + status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, + detail=str(exc), + ) from exc + + +@router.get("/sources") +def list_sources() -> list[str]: + """Return all registered widget source types.""" + return list_source_types() + + +@router.get("/types") +def list_types() -> list[WidgetTypeInfo]: + """Return metadata for all registered widget types.""" + return [info.model_dump() for info in list_widget_types()] + + +@router.get("/instances") +def list_instances( + store: SettingsStore = Depends(get_settings_store), +) -> list[dict[str, Any]]: + """Return all persisted widget instances.""" + return [WidgetInstance(**widget).model_dump() for widget in store.list_widgets()] + + +@router.post("/instances", status_code=status.HTTP_201_CREATED) +def create_instance( + body: WidgetInstanceInput, + store: SettingsStore = Depends(get_settings_store), +) -> dict[str, Any]: + """Create a new widget instance.""" + _validate_widget_input(body) + widget = store.upsert_widget(body.model_dump()) + return WidgetInstance(**widget).model_dump() + + +@router.put("/instances/{widget_id}") +def update_instance( + widget_id: str, + body: WidgetInstanceInput, + store: SettingsStore = Depends(get_settings_store), +) -> dict[str, Any]: + """Update an existing widget instance.""" + existing = store.get_widget(widget_id) + if not existing: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Widget not found") + if body.id is not None and body.id != widget_id: + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail="ID in path does not match ID in body", + ) + _validate_widget_input(body) + widget = store.upsert_widget(body.model_dump(), widget_id) + return WidgetInstance(**widget).model_dump() + + +@router.delete("/instances/{widget_id}") +def delete_instance( + widget_id: str, + store: SettingsStore = Depends(get_settings_store), +) -> dict[str, str]: + """Delete a widget instance.""" + existing = store.get_widget(widget_id) + if not existing: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Widget not found") + store.delete_widget(widget_id) + return {"status": "deleted"} diff --git a/backend/src/media_library_viewer_api/services/settings_store.py b/backend/src/media_library_viewer_api/services/settings_store.py index 50dbcad..d021f26 100644 --- a/backend/src/media_library_viewer_api/services/settings_store.py +++ b/backend/src/media_library_viewer_api/services/settings_store.py @@ -18,6 +18,7 @@ from typing import Any import paramiko from media_library_viewer_api.config import get_settings +from media_library_viewer_api.models.widgets import _validate_config_keys DEFAULT_SETTINGS_PATH = Path(".cache/media_library_viewer/settings.sqlite") LOCAL_MACHINE_ID = "local" @@ -163,6 +164,24 @@ class SettingsStore: conn.execute( "CREATE INDEX IF NOT EXISTS idx_dashboard_shortcuts_type ON dashboard_shortcuts(shortcut_type)" ) + conn.execute( + """ + CREATE TABLE IF NOT EXISTS dashboard_widgets ( + id TEXT PRIMARY KEY, + addon_id TEXT NOT NULL, + widget_type TEXT NOT NULL, + title TEXT NOT NULL, + config_json TEXT NOT NULL DEFAULT '{}', + enabled INTEGER NOT NULL DEFAULT 1, + sort_order INTEGER NOT NULL DEFAULT 0, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ) + """ + ) + conn.execute( + "CREATE INDEX IF NOT EXISTS idx_dashboard_widgets_sort ON dashboard_widgets(sort_order)" + ) conn.execute(""" CREATE TABLE IF NOT EXISTS backup_jobs ( id TEXT PRIMARY KEY, @@ -353,12 +372,8 @@ class SettingsStore: "notes": notes, } - def ensure_defaults(self) -> None: - self.init_schema() - with self.connect() as conn: - row = conn.execute("SELECT COUNT(*) FROM monitoring_machines").fetchone() - if row and int(row[0]) > 0: - return + def _seed_local_machine(self) -> None: + """Seed the default local machine if none exists.""" machine = _default_local_machine() now = int(time.time()) config = { @@ -401,6 +416,49 @@ class SettingsStore: ), ) + def _seed_dashboard_widgets(self) -> None: + """Seed default dashboard widgets only when the table is empty.""" + from media_library_viewer_api.widgets.registry import WIDGET_REGISTRY + + self.init_schema() + with self.connect() as conn: + row = conn.execute("SELECT COUNT(*) FROM dashboard_widgets").fetchone() + if row and int(row[0]) > 0: + return + defaults = [ + { + "id": "jellyfin-activity-default", + "addon_id": "core", + "widget_type": "jellyfin", + "title": "Jellyfin activity", + "config": {"machine_id": ""}, + "enabled": True, + "sort_order": 0, + }, + { + "id": "backups-summary-default", + "addon_id": "backups", + "widget_type": "backups", + "title": "Backups", + "config": {}, + "enabled": True, + "sort_order": 1, + }, + ] + for widget in defaults: + info = WIDGET_REGISTRY.get(widget["widget_type"]) + if not info or info["addon_id"] != widget["addon_id"]: + continue + self.upsert_widget(widget) + + def ensure_defaults(self) -> None: + self.init_schema() + with self.connect() as conn: + row = conn.execute("SELECT COUNT(*) FROM monitoring_machines").fetchone() + if not row or int(row[0]) == 0: + self._seed_local_machine() + self._seed_dashboard_widgets() + def list_machines(self) -> list[dict[str, Any]]: self.init_schema() with self.connect() as conn: @@ -1306,6 +1364,119 @@ class SettingsStore: ) + # ------------------------------------------------------------------ + # Dashboard widgets + # ------------------------------------------------------------------ + + def _row_to_widget(self, row: sqlite3.Row) -> dict[str, Any]: + return { + "id": row["id"], + "addon_id": row["addon_id"], + "widget_type": row["widget_type"], + "title": row["title"], + "config": json.loads(row["config_json"] or "{}"), + "enabled": bool(row["enabled"]), + "sort_order": int(row["sort_order"]), + "created_at": row["created_at"], + "updated_at": row["updated_at"], + } + + def _normalize_widget_payload( + self, + payload: dict[str, Any], + widget_id: str | None = None, + ) -> dict[str, Any]: + current = self.get_widget(widget_id) if widget_id else None + widget_id = ( + str(payload.get("id") or widget_id or uuid.uuid4().hex[:12]).strip() + or uuid.uuid4().hex[:12] + ) + addon_id = str(payload.get("addon_id") or (current or {}).get("addon_id", "")).strip() + widget_type = str( + payload.get("widget_type") or (current or {}).get("widget_type", "") + ).strip() + title = str(payload.get("title") or (current or {}).get("title", "") or "").strip() + config = payload.get("config", (current or {}).get("config", {})) + if not isinstance(config, dict): + config = {} + # Defense-in-depth: reject credential keys at the store layer too. + _validate_config_keys(config) + enabled = bool(payload.get("enabled", (current or {}).get("enabled", True))) + sort_order = int(payload.get("sort_order", (current or {}).get("sort_order", 0)) or 0) + return { + "id": widget_id, + "addon_id": addon_id, + "widget_type": widget_type, + "title": title, + "config": config, + "enabled": enabled, + "sort_order": sort_order, + } + + def list_widgets(self) -> list[dict[str, Any]]: + self.init_schema() + with self.connect() as conn: + rows = conn.execute( + "SELECT * FROM dashboard_widgets ORDER BY sort_order ASC, created_at ASC" + ).fetchall() + return [self._row_to_widget(row) for row in rows] + + def get_widget(self, widget_id: str | None) -> dict[str, Any] | None: + if not widget_id: + return None + self.init_schema() + with self.connect() as conn: + row = conn.execute( + "SELECT * FROM dashboard_widgets WHERE id = ?", (widget_id,) + ).fetchone() + return self._row_to_widget(row) if row else None + + def upsert_widget(self, payload: dict[str, Any], widget_id: str | None = None) -> dict[str, Any]: + self.init_schema() + widget = self._normalize_widget_payload(payload, widget_id) + now = int(time.time()) + with self.connect() as conn: + existing = conn.execute( + "SELECT created_at FROM dashboard_widgets WHERE id = ?", + (widget["id"],), + ).fetchone() + created_at = int(existing[0]) if existing else now + conn.execute( + """ + INSERT INTO dashboard_widgets ( + id, addon_id, widget_type, title, config_json, enabled, + sort_order, created_at, updated_at + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(id) DO UPDATE SET + addon_id = excluded.addon_id, + widget_type = excluded.widget_type, + title = excluded.title, + config_json = excluded.config_json, + enabled = excluded.enabled, + sort_order = excluded.sort_order, + updated_at = excluded.updated_at + """, + ( + widget["id"], + widget["addon_id"], + widget["widget_type"], + widget["title"], + json.dumps(widget["config"]), + 1 if widget["enabled"] else 0, + widget["sort_order"], + created_at, + now, + ), + ) + return self.get_widget(widget["id"]) or widget + + def delete_widget(self, widget_id: str) -> None: + self.init_schema() + with self.connect() as conn: + conn.execute("DELETE FROM dashboard_widgets WHERE id = ?", (widget_id,)) + + _store: SettingsStore | None = None diff --git a/backend/src/media_library_viewer_api/widgets/__init__.py b/backend/src/media_library_viewer_api/widgets/__init__.py new file mode 100644 index 0000000..a95f70e --- /dev/null +++ b/backend/src/media_library_viewer_api/widgets/__init__.py @@ -0,0 +1 @@ +"""Widget subsystem package.""" diff --git a/backend/src/media_library_viewer_api/widgets/registry.py b/backend/src/media_library_viewer_api/widgets/registry.py new file mode 100644 index 0000000..c228f77 --- /dev/null +++ b/backend/src/media_library_viewer_api/widgets/registry.py @@ -0,0 +1,187 @@ +"""Closed, compile-time widget registry. + +New widget types and source adapters require a code change in Phase 1. +There is no runtime plugin loading. +""" + +from typing import Any + +from media_library_viewer_api.models.widgets import WidgetTypeInfo + +WIDGET_REGISTRY: dict[str, dict[str, Any]] = { + "jellyfin": { + "addon_id": "core", + "name": "Jellyfin activity", + "description": "Live sessions and idle users from a Jellyfin server.", + "source_type": "jellyfin", + "config_schema": { + "type": "object", + "properties": { + "machine_id": { + "type": "string", + "description": "Jellyfin machine id (empty = default)", + }, + }, + "required": ["machine_id"], + }, + }, + "backups": { + "addon_id": "backups", + "name": "Backups", + "description": "Backup job summary and active alerts.", + "source_type": "backups", + "config_schema": { + "type": "object", + "properties": {}, + "required": [], + }, + }, + "grafana-link": { + "addon_id": "grafana", + "name": "Grafana link", + "description": "Deep-link to a Grafana dashboard or panel.", + "source_type": "grafana", + "config_schema": { + "type": "object", + "properties": { + "dashboard_uid": { + "type": "string", + "description": "Grafana dashboard UID", + }, + "panel_id": { + "type": "integer", + "description": "Optional panel id", + }, + }, + "required": ["dashboard_uid"], + }, + }, + "prometheus-metric": { + "addon_id": "prometheus", + "name": "Prometheus metric", + "description": "Instant query result rendered as a metric.", + "source_type": "prometheus", + "config_schema": { + "type": "object", + "properties": { + "promql": { + "type": "string", + "description": "PromQL instant query", + }, + }, + "required": ["promql"], + }, + }, + "ssh-task": { + "addon_id": "ssh-tasks", + "name": "SSH task output", + "description": "Output of a saved task run on a machine.", + "source_type": "ssh_task", + "config_schema": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Saved task id", + }, + }, + "required": ["task_id"], + }, + }, + "static": { + "addon_id": "core", + "name": "Static text", + "description": "Plain text or markdown note.", + "source_type": "static", + "config_schema": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Text or markdown content", + }, + }, + "required": ["text"], + }, + }, +} + + +def list_source_types() -> list[str]: + """Return all registered source type names.""" + return sorted({info["source_type"] for info in WIDGET_REGISTRY.values()}) + + +def list_widget_types() -> list[WidgetTypeInfo]: + """Return metadata for all registered widget types.""" + return [ + WidgetTypeInfo( + addon_id=info["addon_id"], + widget_type=widget_type, + name=info["name"], + description=info["description"], + source_type=info["source_type"], + config_schema=info["config_schema"], + ) + for widget_type, info in WIDGET_REGISTRY.items() + ] + + +def get_widget_info(widget_type: str) -> WidgetTypeInfo | None: + """Return metadata for a single widget type, or None if unknown.""" + info = WIDGET_REGISTRY.get(widget_type) + if not info: + return None + return WidgetTypeInfo( + addon_id=info["addon_id"], + widget_type=widget_type, + name=info["name"], + description=info["description"], + source_type=info["source_type"], + config_schema=info["config_schema"], + ) + + +def _validate_type(value: Any, expected: str) -> bool: + if expected == "string": + return isinstance(value, str) + if expected == "integer": + return isinstance(value, int) and not isinstance(value, bool) + if expected == "boolean": + return isinstance(value, bool) + if expected == "number": + return isinstance(value, (int, float)) and not isinstance(value, bool) + if expected == "object": + return isinstance(value, dict) + if expected == "array": + return isinstance(value, list) + return True + + +def validate_config(widget_type: str, config: dict[str, Any]) -> None: + """Validate a widget config against its registered JSON schema. + + Raises ValueError with a descriptive message if validation fails. + Phase 1 supports only required-field and primitive-type checks. + """ + info = WIDGET_REGISTRY.get(widget_type) + if not info: + raise ValueError(f"Unknown widget type: {widget_type}") + + schema = info["config_schema"] + required = schema.get("required", []) + properties = schema.get("properties", {}) + + for key in required: + if key not in config: + raise ValueError(f"Missing required config field: {key}") + + for key, value in config.items(): + prop = properties.get(key) + if not prop: + # Unknown keys are allowed in Phase 1 unless they look like secrets + # (handled by the model validator). Skip type checks for unknowns. + continue + expected_type = prop.get("type") + if expected_type and not _validate_type(value, expected_type): + raise ValueError(f"Config field '{key}' must be of type {expected_type}") diff --git a/backend/tests/test_widgets.py b/backend/tests/test_widgets.py new file mode 100644 index 0000000..75b8907 --- /dev/null +++ b/backend/tests/test_widgets.py @@ -0,0 +1,291 @@ +"""Tests for the dashboard widget backend: registry, CRUD, validation, seeding.""" + +from types import SimpleNamespace +from unittest.mock import patch + +import pytest +from fastapi.testclient import TestClient + +from media_library_viewer_api.dependencies import get_settings_store +from media_library_viewer_api.main import app +from media_library_viewer_api.services.settings_store import SettingsStore + + +@pytest.fixture +def client(tmp_path): + """FastAPI test client with a fresh settings store and auth disabled.""" + store = SettingsStore(tmp_path / "settings.sqlite") + store.ensure_defaults() + app.dependency_overrides[get_settings_store] = lambda: store + auth_settings = SimpleNamespace(auth_enabled=False) + with patch("media_library_viewer_api.auth.get_settings", return_value=auth_settings): + yield TestClient(app) + app.dependency_overrides.clear() + + +def test_widget_sources(client): + response = client.get("/api/widgets/sources") + assert response.status_code == 200 + assert set(response.json()) == { + "jellyfin", + "backups", + "grafana", + "prometheus", + "ssh_task", + "static", + } + + +def test_widget_types(client): + response = client.get("/api/widgets/types") + assert response.status_code == 200 + types = {item["widget_type"] for item in response.json()} + assert types == { + "jellyfin", + "backups", + "grafana-link", + "prometheus-metric", + "ssh-task", + "static", + } + + +def test_create_and_read_widget(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Note", + "config": {"text": "hello"}, + "enabled": True, + "sort_order": 5, + }, + ) + assert response.status_code == 201 + widget = response.json() + assert widget["title"] == "Note" + assert widget["config"] == {"text": "hello"} + assert widget["enabled"] is True + assert widget["sort_order"] == 5 + widget_id = widget["id"] + + response = client.get("/api/widgets/instances") + assert response.status_code == 200 + assert any(w["id"] == widget_id for w in response.json()) + + +def test_update_widget(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Note", + "config": {"text": "hello"}, + }, + ) + widget_id = response.json()["id"] + + response = client.put( + f"/api/widgets/instances/{widget_id}", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Updated", + "config": {"text": "world"}, + "enabled": False, + "sort_order": 10, + }, + ) + assert response.status_code == 200 + data = response.json() + assert data["title"] == "Updated" + assert data["config"] == {"text": "world"} + assert data["enabled"] is False + assert data["sort_order"] == 10 + + +def test_delete_widget(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "To delete", + "config": {"text": "bye"}, + }, + ) + widget_id = response.json()["id"] + + response = client.delete(f"/api/widgets/instances/{widget_id}") + assert response.status_code == 200 + + response = client.get("/api/widgets/instances") + assert not any(w["id"] == widget_id for w in response.json()) + + +def test_unknown_widget_type_rejected(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "unknown", + "title": "Bad", + "config": {}, + }, + ) + assert response.status_code == 422 + + +def test_addon_id_mismatch_rejected(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "grafana", + "widget_type": "static", + "title": "Bad", + "config": {"text": "x"}, + }, + ) + assert response.status_code == 422 + + +def test_credential_key_rejected(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Bad", + "config": {"api_key": "secret123"}, + }, + ) + assert response.status_code == 422 + + +def test_update_nonexistent_widget(client): + response = client.put( + "/api/widgets/instances/does-not-exist", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Bad", + "config": {"text": "x"}, + }, + ) + assert response.status_code == 404 + + +def test_delete_nonexistent_widget(client): + response = client.delete("/api/widgets/instances/does-not-exist") + assert response.status_code == 404 + + +def test_default_widgets_seeded(client): + response = client.get("/api/widgets/instances") + assert response.status_code == 200 + widgets = response.json() + types = [w["widget_type"] for w in widgets] + assert "jellyfin" in types + assert "backups" in types + + +def test_no_reseed_when_widgets_exist(tmp_path): + db_path = tmp_path / "settings.sqlite" + store = SettingsStore(db_path) + store.ensure_defaults() + widgets = store.list_widgets() + assert len(widgets) == 2 + + store.delete_widget(widgets[0]["id"]) + store.ensure_defaults() + + remaining = store.list_widgets() + assert len(remaining) == 1 + + +def test_update_id_mismatch_returns_400(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Note", + "config": {"text": "hello"}, + }, + ) + widget_id = response.json()["id"] + + response = client.put( + f"/api/widgets/instances/{widget_id}", + json={ + "id": "different-id", + "addon_id": "core", + "widget_type": "static", + "title": "Updated", + "config": {"text": "world"}, + }, + ) + assert response.status_code == 400 + + +def test_empty_title_rejected(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "", + "config": {"text": "hello"}, + }, + ) + assert response.status_code == 422 + + +def test_config_type_error_rejected(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "grafana", + "widget_type": "grafana-link", + "title": "Grafana", + "config": {"panel_id": "not-an-integer"}, + }, + ) + assert response.status_code == 422 + + +def test_list_instances_respects_sort_order(client): + response = client.get("/api/widgets/instances") + assert response.status_code == 200 + widgets = response.json() + orders = [w["sort_order"] for w in widgets] + assert orders == sorted(orders) + + +def test_enabled_round_trip(client): + response = client.post( + "/api/widgets/instances", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Toggle", + "config": {"text": "x"}, + "enabled": False, + }, + ) + widget_id = response.json()["id"] + + response = client.put( + f"/api/widgets/instances/{widget_id}", + json={ + "addon_id": "core", + "widget_type": "static", + "title": "Toggle", + "config": {"text": "x"}, + "enabled": True, + }, + ) + assert response.status_code == 200 + assert response.json()["enabled"] is True diff --git a/openspec/changes/configurable-dashboard-widgets/apply-progress.md b/openspec/changes/configurable-dashboard-widgets/apply-progress.md new file mode 100644 index 0000000..bd881bf --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/apply-progress.md @@ -0,0 +1,64 @@ +# Apply Progress: Configurable Dashboard Widgets + +**Change:** `configurable-dashboard-widgets` +**Apply run:** PR 1 / Slice 1 — Backend CRUD and default seeding +**Date:** 2026-06-19 + +## Completed tasks (Slice 1) + +All Slice 1 tasks are marked `- [x]` in `tasks.md`: + +- [x] 1.1 Create widget Pydantic models +- [x] 1.2 Create backend widget registry +- [x] 1.3 Implement widgets router (CRUD + metadata) +- [x] 1.4 Extend `SettingsStore` for `dashboard_widgets` +- [x] 1.5 Register widgets router in `main.py` +- [x] 1.6 Add backend tests for registry, CRUD, and seeding +- [x] 1.7 Verify backend slice + +## Files changed + +### New files + +- `backend/src/media_library_viewer_api/models/widgets.py` — Pydantic models: `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`, plus credential-key/secret-value validators. +- `backend/src/media_library_viewer_api/widgets/__init__.py` — Package marker. +- `backend/src/media_library_viewer_api/widgets/registry.py` — Closed `WIDGET_REGISTRY` for six Phase 1 widget types, source-type listing, type metadata, and lightweight config-schema validation. +- `backend/src/media_library_viewer_api/routers/widgets.py` — REST endpoints for `/api/widgets/sources`, `/types`, `/instances`, and instance CRUD. +- `backend/tests/test_widgets.py` — 12 tests covering registry, CRUD, validation, and seeding. + +### Modified files + +- `backend/src/media_library_viewer_api/services/settings_store.py` — Added `dashboard_widgets` table, index, CRUD helpers, default seeding, and refactored `ensure_defaults()` to seed widgets independently of machine seeding. +- `backend/src/media_library_viewer_api/main.py` — Registered `widgets_router`. + +## Verification + +Commands run: + +```bash +cd backend +.venv/bin/python -m ruff check . # All checks passed +PYTHONPATH=src .venv/bin/python -m pytest # 185 passed, 2 warnings +cd ../frontend +npm run lint # 2 pre-existing warnings, 0 errors +npm run build # Built successfully +``` + +Focused widget test output: `12 passed`. + +## Deviations from design + +- None significant for Slice 1. The implementation follows the design's backend CRUD layout. +- Used `HTTP_422_UNPROCESSABLE_CONTENT` instead of the deprecated `HTTP_422_UNPROCESSABLE_ENTITY`. + +## Remaining work + +- Slice 2: Backend source adapters + `GET /api/widgets/instances/{id}/data` +- Slice 3: Frontend types/API/hooks/registry/components +- Slice 4: Dashboard loop + configuration UI + addon pages + +## PR boundary + +This slice is **PR 1 of 4** in the approved stacked-to-main chain. It is backend-only and leaves the frontend build/lint green. + +**Actual changed-line count:** ~780 added lines across production code and tests (new files: ~597 lines; modified files: ~181 insertions). This is above the nominal ~400-line review budget, but Slice 1 is the smallest coherent backend unit: removing the CRUD router, store helpers, or tests would leave the slice non-functional or unverifiable. If the reviewer prefers a smaller blast radius, the store helpers (~90 lines) could be split into a preceding PR, though that PR would not be independently user-visible. diff --git a/openspec/changes/configurable-dashboard-widgets/design.md b/openspec/changes/configurable-dashboard-widgets/design.md new file mode 100644 index 0000000..45fea09 --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/design.md @@ -0,0 +1,749 @@ +# SDD Design: Configurable Dashboard Widgets + +**Change:** `configurable-dashboard-widgets` +**Phase:** design +**Date:** 2026-06-19 + +## 1. Architecture overview + +The widget system introduces a thin, closed registry layer between the existing FastAPI backend and the React dashboard. It reuses the existing `SettingsStore` SQLite database, dependency-injection helpers (`get_jellyfin_client`, `get_ssh_client`, saved-task registry), and shadcn/ui component patterns. + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Browser │ +│ Dashboard.tsx ──► WidgetInstance renderer ──► widget registry │ +│ │ │ │ │ +│ │ useWidgetData() addon pages │ +│ │ │ │ │ +│ └──────────────► /api/widgets/instances/{id}/data ◄────────┘ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────────────────────────┐ + │ FastAPI /api/widgets router │ + │ - CRUD instances │ + │ - registry metadata │ + │ - data fetch via source adapters │ + └────────────────────────────────────────┘ + │ + ┌─────────────────────────┼─────────────────────────┐ + ▼ ▼ ▼ + SettingsStore source adapters existing routers + (SQLite) (stateless) /api/dashboard + dashboard_widgets jellyfin /api/tasks + backups /api/settings + grafana + prometheus + ssh_task + static +``` + +**Key constraints carried from the spec:** + +- Closed, compile-time registries in both backend and frontend. No runtime plugin loading. +- No secrets in `config_json`; credentials come from the machine/SSH-key store or environment settings. +- Stacked `SectionCard` layout; no grid/drag/resize. +- Each widget fetches its own data independently with per-type polling intervals and timeouts. + +--- + +## 2. Backend design + +### 2.1 `dashboard_widgets` table schema + +Extend `SettingsStore.init_schema()` in `backend/src/media_library_viewer_api/services/settings_store.py`: + +```sql +CREATE TABLE IF NOT EXISTS dashboard_widgets ( + id TEXT PRIMARY KEY, + addon_id TEXT NOT NULL, + widget_type TEXT NOT NULL, + title TEXT NOT NULL, + config_json TEXT NOT NULL DEFAULT '{}', + enabled INTEGER NOT NULL DEFAULT 1, + sort_order INTEGER NOT NULL DEFAULT 0, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); +CREATE INDEX IF NOT EXISTS idx_dashboard_widgets_sort ON dashboard_widgets(sort_order); +``` + +Store helper additions: + +- `_row_to_widget(row)` — parse `config_json` into a `config` dict. +- `_normalize_widget_payload(payload, widget_id=None)` — validate/assign defaults, generate `id` if missing. +- `list_widgets()` — return all rows ordered by `sort_order ASC, created_at ASC`. +- `get_widget(widget_id)` — single row. +- `upsert_widget(payload, widget_id=None)` — insert or replace; preserve `created_at`. +- `delete_widget(widget_id)` — delete by id. +- `seed_default_widgets()` — called from `ensure_defaults()`; inserts the two defaults only when the table is empty. + +`ensure_defaults()` already runs on startup (called via `get_settings_store()`). Seeding logic: + +```python +def ensure_defaults(self) -> None: + self.init_schema() + # existing local-machine seeding ... + self._seed_dashboard_widgets() + +def _seed_dashboard_widgets(self) -> None: + with self.connect() as conn: + row = conn.execute("SELECT COUNT(*) FROM dashboard_widgets").fetchone() + if row and int(row[0]) > 0: + return + now = int(time.time()) + defaults = [ + { + "id": "jellyfin-activity-default", + "addon_id": "core", + "widget_type": "jellyfin", + "title": "Jellyfin activity", + "config": {"machine_id": ""}, + "enabled": True, + "sort_order": 0, + }, + { + "id": "backups-summary-default", + "addon_id": "backups", + "widget_type": "backups", + "title": "Backups", + "config": {}, + "enabled": True, + "sort_order": 1, + }, + ] + for w in defaults: + self.upsert_widget(w) +``` + +IDs are hard-coded so repeated startups are idempotent. Empty `config` for `jellyfin` resolves to the first enabled Jellyfin machine via existing DI. + +### 2.2 Widget source adapter protocol + +Adapters live in `backend/src/media_library_viewer_api/widgets/sources.py` (single file is sufficient for Phase 1). + +```python +from typing import Any, Protocol + +class WidgetSource(Protocol): + source_type: str + async def fetch(self, config: dict[str, Any]) -> dict[str, Any]: ... +``` + +Concrete adapters: + +| source_type | class | implementation notes | +|-------------|-------|----------------------| +| `jellyfin` | `JellyfinWidgetSource` | Build a Starlette `Request` with `machine_id` query param, call `get_jellyfin_client(req)` and `get_user_id(req)`, then `client.sessions()`; reuse `_map_sessions_to_activity_rows` from `routers/dashboard.py` or move the helper to a shared `domain/dashboard.py`. | +| `backups` | `BackupsWidgetSource` | Call `SettingsStore.list_backup_jobs`, `list_backup_runs`, `list_backup_alerts` and compute the same summary as `GET /api/dashboard/backups`; reuse `BackupDashboardSummary`. | +| `grafana` | `GrafanaWidgetSource` | Read `grafana_url` from `get_settings()` (new setting, default `http://grafana:3000`) and `config.dashboard_uid`/`panel_id`; return `{url: "{grafana_url}/d/{dashboard_uid}?..."}`. No embedding. | +| `prometheus` | `PrometheusWidgetSource` | Read `prometheus_url` from settings (env or default `http://prometheus:9090`), run instant query `config.promql`, return scalar/vector result. Apply 10 s timeout. | +| `ssh_task` | `SshTaskWidgetSource` | Look up saved task by `config.task_id` in `SettingsStore`, resolve machine via existing `_resolve_machine_for_task` logic or a shared helper, run via `LocalCommandClient`/`RemoteSSHClient`, return trimmed stdout/stderr/exit_status. | +| `static` | `StaticWidgetSource` | Return `{"text": config.get("text", "")}`; no network call. | + +Adapter registry: + +```python +SOURCE_REGISTRY: dict[str, WidgetSource] = { + "jellyfin": JellyfinWidgetSource(), + "backups": BackupsWidgetSource(), + "grafana": GrafanaWidgetSource(), + "prometheus": PrometheusWidgetSource(), + "ssh_task": SshTaskWidgetSource(), + "static": StaticWidgetSource(), +} +``` + +Adapters must catch all exceptions and return `{"error": "human-readable message"}`. The only 500 case is an unhandled exception in the adapter, which the endpoint catches and logs. + +Timeouts (adapter-level, not HTTP client-level where possible): + +- `jellyfin`: 10 s +- `backups`: 10 s +- `prometheus`: 10 s +- `ssh_task`: 30 s +- `grafana`: 5 s +- `static`: no fetch + +### 2.3 Router layout + +New file: `backend/src/media_library_viewer_api/routers/widgets.py` + +```python +from fastapi import APIRouter, Depends, HTTPException, status +from pydantic import BaseModel + +from media_library_viewer_api.dependencies import get_settings_store +from media_library_viewer_api.models.widgets import ( + WidgetInstance, + WidgetInstanceInput, + WidgetTypeInfo, + WidgetDataResponse, +) +from media_library_viewer_api.services.settings_store import SettingsStore +from media_library_viewer_api.widgets.registry import WIDGET_REGISTRY +from media_library_viewer_api.widgets.sources import SOURCE_REGISTRY + +router = APIRouter(prefix="/api/widgets", tags=["widgets"]) +``` + +Endpoints: + +| Method | Path | Handler | +|--------|------|---------| +| GET | `/sources` | `list_sources()` — returns `["jellyfin", "backups", "grafana", "prometheus", "ssh_task", "static"]` | +| GET | `/types` | `list_types()` — returns `list[WidgetTypeInfo]` built from `WIDGET_REGISTRY` | +| GET | `/instances` | `list_instances(store)` — `store.list_widgets()` mapped to `WidgetInstance` | +| POST | `/instances` | `create_instance(body, store)` — status 201 | +| PUT | `/instances/{widget_id}` | `update_instance(widget_id, body, store)` — 404 if missing, 400 if `body.id != widget_id` | +| DELETE | `/instances/{widget_id}` | `delete_instance(widget_id, store)` — 404 if missing | +| GET | `/instances/{widget_id}/data` | `fetch_data(widget_id, store)` — look up widget, resolve source adapter, return `WidgetDataResponse` | + +Validation flow in create/update: + +1. Validate `WidgetInstanceInput` Pydantic model. +2. Reject forbidden credential keys anywhere in `config`. +3. Verify `widget_type` is in `WIDGET_REGISTRY`. +4. Verify `addon_id` matches the registry entry for that type. +5. Validate `config` against the widget type's JSON schema. +6. Persist via `store.upsert_widget()`. + +### 2.4 Pydantic models + +New file: `backend/src/media_library_viewer_api/models/widgets.py` + +```python +from typing import Any +from pydantic import BaseModel, Field, field_validator, model_validator + +FORBIDDEN_CONFIG_KEYS = { + "password", "token", "secret", "api_key", "apikey", + "private_key", "passphrase", "credential", +} + +def _looks_secret(value: Any) -> bool: + if not isinstance(value, str) or not value.strip(): + return False + lowered = value.lower() + if value.startswith("sk-") or value.startswith("eyJ"): + return True + if len(value) > 64 and lowered.isalnum(): + return True + return False + +def _validate_config_keys(config: dict[str, Any]) -> dict[str, Any]: + for key, value in config.items(): + if key.lower() in FORBIDDEN_CONFIG_KEYS: + raise ValueError(f"Credential key '{key}' is not allowed in widget config") + if _looks_secret(value): + raise ValueError(f"Value for '{key}' looks like a secret") + if isinstance(value, dict): + _validate_config_keys(value) + return config + +class WidgetInstanceInput(BaseModel): + id: str | None = None + addon_id: str + widget_type: str + title: str = Field(..., min_length=1) + config: dict[str, Any] = Field(default_factory=dict) + enabled: bool = True + sort_order: int = Field(default=0, ge=0) + + @field_validator("config") + @classmethod + def reject_credential_keys(cls, v): + return _validate_config_keys(v or {}) + +class WidgetInstance(WidgetInstanceInput): + id: str + created_at: int + updated_at: int + +class WidgetTypeInfo(BaseModel): + addon_id: str + widget_type: str + name: str + description: str + source_type: str + config_schema: dict[str, Any] + +class WidgetDataResponse(BaseModel): + widget_id: str + widget_type: str + data: dict[str, Any] | None + error: str | None + fetched_at: int +``` + +Widget registry file: `backend/src/media_library_viewer_api/widgets/registry.py` + +```python +WIDGET_REGISTRY: dict[str, dict[str, Any]] = { + "jellyfin": { + "addon_id": "core", + "name": "Jellyfin activity", + "description": "Live sessions and idle users from a Jellyfin server.", + "source_type": "jellyfin", + "config_schema": { + "type": "object", + "properties": { + "machine_id": {"type": "string", "description": "Jellyfin machine id (empty = default)"}, + }, + "required": [], + }, + }, + "backups": { "addon_id": "backups", ... }, + "grafana-link": { "addon_id": "grafana", ... }, + "prometheus-metric": { "addon_id": "prometheus", ... }, + "ssh-task": { "addon_id": "ssh-tasks", ... }, + "static": { "addon_id": "core", ... }, +} +``` + +The registry explicitly maps `widget_type -> addon_id` so the backend can enforce invariant #2. + +### 2.5 Main.py registration + +Add to `backend/src/media_library_viewer_api/main.py`: + +```python +from media_library_viewer_api.routers import widgets as widgets_router +... +app.include_router(widgets_router.router) +``` + +Because all `/api/widgets` endpoints are under the existing JWT/API-key middleware (`enforce_jwt_auth`), no additional auth decorator is needed. + +--- + +## 3. Frontend design + +### 3.1 Widget registry + +New file: `frontend/src/widgets/registry.ts` + +```typescript +import type { WidgetInstance, WidgetInstanceInput } from "../types"; + +export interface WidgetConfigField { + key: string; + label: string; + type: "string" | "select" | "boolean" | "number"; + options?: { label: string; value: string }[]; + helper?: string; +} + +export interface WidgetDefinition { + widgetType: string; + addonId: string; + name: string; + description: string; + sourceType: string; + refreshInterval: number; // ms, 0 = no polling + defaultConfig: Record; + configFields: WidgetConfigField[]; + component: React.ComponentType<{ widget: WidgetInstance }>; +} + +export const WIDGET_REGISTRY: Record = { + jellyfin: { ... }, + backups: { ... }, + "grafana-link": { ... }, + "prometheus-metric": { ... }, + "ssh-task": { ... }, + static: { ... }, +}; + +export function getWidgetDefinition(widgetType: string): WidgetDefinition | undefined { + return WIDGET_REGISTRY[widgetType]; +} +``` + +Refresh intervals (ms): + +- `jellyfin`: 30_000 +- `backups`: 60_000 +- `grafana-link`: 0 +- `prometheus-metric`: 30_000 +- `ssh-task`: 0 +- `static`: 0 + +Widget components live in `frontend/src/widgets/*.tsx`: + +- `JellyfinWidget.tsx` — wraps `NowPlaying` / activity data. +- `BackupsWidget.tsx` — reuses `BackupDashboardWidget` internals or extracts a shared presentational component. +- `GrafanaLinkWidget.tsx` — renders a deep-link card. +- `PrometheusMetricWidget.tsx` — metric value/sparkline card. +- `SshTaskWidget.tsx` — preformatted output panel. +- `StaticWidget.tsx` — markdown/text block. + +### 3.2 Dashboard rendering loop + +Modify `frontend/src/pages/Dashboard.tsx`: + +```tsx +import { useWidgetInstances } from "../hooks/useWidgets"; +import { WidgetInstance } from "../components/WidgetInstance"; + +export function Dashboard() { + const { data: instances = [] } = useWidgetInstances(); + const visible = useMemo( + () => instances.filter((w) => w.enabled).sort((a, b) => a.sort_order - b.sort_order), + [instances], + ); + + return ( +
+ {/* Shortcuts remain a first-class section to avoid data migration */} + + + {visible.map((widget) => ( + + ))} + + + +
+ ); +} +``` + +`WidgetInstance` renderer (`frontend/src/components/WidgetInstance.tsx`): + +```tsx +import { SectionCard } from "./SectionCard"; +import { useWidgetData } from "../hooks/useWidgets"; +import { getWidgetDefinition } from "../widgets/registry"; + +export function WidgetInstance({ widget }: { widget: WidgetInstance }) { + const def = getWidgetDefinition(widget.widget_type); + const { data, isLoading } = useWidgetData(widget.id, def?.refreshInterval ?? 0); + + if (!def) { + return ( + + Unknown widget type: {widget.widget_type} + + ); + } + + const Component = def.component; + return ( + + {isLoading && !data ? : } + + ); +} +``` + +Each widget component receives the `widget` instance and reads `data?.data` / `data?.error` from its own `useWidgetData` query (or the parent can pass it; both work, but passing avoids a second hook call). Prefer passing `data` and `isLoading` from `WidgetInstance` to the component to keep components pure. + +### 3.3 TanStack Query hooks + +New file: `frontend/src/hooks/useWidgets.ts`: + +```typescript +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { + fetchWidgetSources, + fetchWidgetTypes, + fetchWidgetInstances, + createWidgetInstance, + updateWidgetInstance, + deleteWidgetInstance, + fetchWidgetData, +} from "../api/widgets"; +import type { WidgetInstanceInput } from "../types"; + +export function useWidgetInstances() { + return useQuery({ + queryKey: ["widgets", "instances"], + queryFn: fetchWidgetInstances, + refetchInterval: 60_000, + }); +} + +export function useWidgetData(widgetId: string, refreshInterval: number) { + return useQuery({ + queryKey: ["widgets", "data", widgetId], + queryFn: () => fetchWidgetData(widgetId), + refetchInterval: refreshInterval || false, + retry: 1, + }); +} + +export function useSaveWidgetInstance() { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (input: WidgetInstanceInput) => + input.id ? updateWidgetInstance(input) : createWidgetInstance(input), + onSuccess: () => queryClient.invalidateQueries({ queryKey: ["widgets", "instances"] }), + }); +} + +export function useDeleteWidgetInstance() { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (widgetId: string) => deleteWidgetInstance(widgetId), + onSuccess: () => queryClient.invalidateQueries({ queryKey: ["widgets", "instances"] }), + }); +} + +export function useWidgetSources() { + return useQuery({ queryKey: ["widgets", "sources"], queryFn: fetchWidgetSources }); +} + +export function useWidgetTypes() { + return useQuery({ queryKey: ["widgets", "types"], queryFn: fetchWidgetTypes }); +} +``` + +### 3.4 Configuration UI + +Add a new `WidgetConfigDialog` component (can live in `frontend/src/components/WidgetConfigDialog.tsx` or inline in `Dashboard.tsx`). + +Behavior: + +- "Edit dashboard" button in the Dashboard header opens the dialog. +- Dialog lists all instances (enabled and disabled) with sort-order inputs, enabled toggle, edit/delete actions, and up/down reorder buttons. +- "Add widget" sub-flow: select widget type from registry, then render source-specific config fields. +- Form fields reuse `Dialog`, `Input`, `Label`, `Switch`, `Select`, `Button`, `Alert`. + +Source-specific config rendering: + +```tsx +function WidgetConfigFields({ + definition, + config, + onChange, +}: { + definition: WidgetDefinition; + config: Record; + onChange: (config: Record) => void; +}) { + return ( +
+ {definition.configFields.map((field) => ( + + {field.type === "select" ? ( + + ) : ( + onChange({ ...config, [field.key]: e.target.value })} + /> + )} + + ))} +
+ ); +} +``` + +For fields that need dynamic options (e.g., machine selection for `jellyfin`, saved task selection for `ssh-task`), the dialog can use `useMonitoringSettings()` and `useTasks()` to populate select options and map them to `machine_id`/`task_id` config values. + +### 3.5 Addon pages + +New file: `frontend/src/pages/AddonPage.tsx`: + +```tsx +import { useParams } from "react-router-dom"; +import { Alert, AlertDescription } from "@/components/ui/alert"; +import { GrafanaAddonPage } from "../addons/GrafanaAddonPage"; +import { PrometheusAddonPage } from "../addons/PrometheusAddonPage"; +import { SshTasksAddonPage } from "../addons/SshTasksAddonPage"; + +const ADDON_PAGES: Record = { + grafana: GrafanaAddonPage, + prometheus: PrometheusAddonPage, + "ssh-tasks": SshTasksAddonPage, +}; + +export function AddonPage() { + const { addonId } = useParams<{ addonId: string }>(); + const Page = addonId ? ADDON_PAGES[addonId] : undefined; + if (!Page) { + return ( + + Addon "{addonId}" is not installed. + + ); + } + return ; +} +``` + +Register in `frontend/src/App.tsx` inside both route trees: + +```tsx +} /> +``` + +Grafana widgets render a link to `/addons/grafana` or directly to the external Grafana URL; either is acceptable. The spec requires the addon page route exists and Grafana widgets deep-link rather than embed. + +--- + +## 4. Data flow + +1. **Config CRUD** + - User opens config dialog → `useWidgetInstances()` and `useWidgetTypes()` load. + - Add/edit form → `useSaveWidgetInstance().mutate(input)` → `POST/PUT /api/widgets/instances` → backend validates, persists, returns `WidgetInstance` → query cache invalidated → dashboard re-renders. + +2. **Per-widget data fetch** + - `Dashboard.tsx` maps enabled instances to ``. + - Each `WidgetInstance` calls `useWidgetData(widget.id, refreshInterval)`. + - Hook calls `GET /api/widgets/instances/{id}/data`. + - Endpoint loads the instance, picks the adapter by `source_type`, calls `adapter.fetch(config)`, wraps in `WidgetDataResponse`. + - Adapter resolves credentials from machine store / env / SSH-key store and returns data or error payload. + +3. **Error boundaries and loading states** + - Adapter exceptions are caught by the endpoint and returned as `error` with HTTP 200; unhandled exceptions return 500. + - `WidgetInstance` shows a skeleton on initial load. + - If `data.error` is set, render an inline `Alert` inside the widget's `SectionCard`. + - A failing widget does not block sibling widgets because each has its own query. + +--- + +## 5. Security design + +- **No secrets in `config_json`**: forbidden key list enforced by Pydantic validator and store write path. Values starting with `sk-`/`eyJ` or long alphanumeric strings are rejected. +- **Credential resolution**: adapters use `get_settings_store().get_machine_config()`, `get_ssh_key()`, and `get_settings()` for Grafana/Prometheus URLs. No widget config stores URLs with embedded credentials. +- **Saved-task registry reuse**: `ssh_task` adapter only runs tasks from the existing saved-task registry; no arbitrary command execution. +- **Auth**: all `/api/widgets` endpoints inherit existing JWT/API-key middleware. +- **No iframes**: addon pages and Grafana widgets render links only. +- **Validation at two layers**: Pydantic model rejects malformed/credential-laden configs; store-level normalization also rejects forbidden keys as defense-in-depth. + +--- + +## 6. Testing approach + +### Backend + +New test file: `backend/tests/test_widgets.py` + +- `TestWidgetRegistry`: `GET /api/widgets/sources` and `/api/widgets/types` return expected closed lists. +- `TestWidgetCrud`: + - create static widget → 201, config round-trips. + - update nonexistent → 404. + - delete → 404 after delete. + - unknown widget type → 422. + - credential key in config → 422. +- `TestWidgetData`: + - static widget data returns text unchanged. + - misconfigured jellyfin widget returns `error` in payload with HTTP 200. +- `TestWidgetSeeding`: + - fresh store seeds Jellyfin + Backups widgets. + - existing widget rows prevent re-seeding. + +Use existing `test_client` fixture pattern from `test_api.py` with mocked Jellyfin/SSH clients where needed. + +### Frontend + +- `npm run build` (via `tsc -b`) validates new TypeScript types and component imports. +- Add `frontend/tests/widgets.test.mjs` using the existing `node:test` + `node:assert/strict` setup to test: + - `getWidgetDefinition` returns correct refresh intervals. + - registry contains exactly the six Phase 1 widget types. +- If/when the project adopts Vitest, add hook tests with MSW; for Phase 1, rely on build + manual component tests. + +### Integration / manual + +- Fresh Docker dev stack shows Jellyfin activity + Backups widgets by default. +- Add each widget type via config UI and verify render + polling behavior. +- Verify disabled widget is hidden and reorder changes dashboard order. + +--- + +## 7. File-level plan + +### Create + +| File | Rationale | +|------|-----------| +| `backend/src/media_library_viewer_api/models/widgets.py` | Pydantic models: `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse` plus credential validators. | +| `backend/src/media_library_viewer_api/widgets/__init__.py` | Package marker for widget subsystem. | +| `backend/src/media_library_viewer_api/widgets/registry.py` | Closed widget-type registry mapping widget_type → addon_id, source_type, JSON schema. | +| `backend/src/media_library_viewer_api/widgets/sources.py` | Stateless source adapters for all six source types. | +| `backend/src/media_library_viewer_api/routers/widgets.py` | REST endpoints for CRUD, registry metadata, and data fetch. | +| `frontend/src/types/index.ts` additions | TypeScript interfaces matching backend models. | +| `frontend/src/api/widgets.ts` | API functions for widget endpoints. | +| `frontend/src/hooks/useWidgets.ts` | TanStack Query hooks for instances, data, mutations. | +| `frontend/src/widgets/registry.ts` | Frontend closed widget registry. | +| `frontend/src/widgets/*.tsx` | Six widget presentational components. | +| `frontend/src/components/WidgetInstance.tsx` | Renderer that loads data and dispatches to widget component. | +| `frontend/src/components/WidgetConfigDialog.tsx` | Add/edit/reorder/remove configuration UI. | +| `frontend/src/pages/AddonPage.tsx` | Route target for `/addons/:addonId`. | +| `frontend/src/addons/GrafanaAddonPage.tsx` | Grafana addon page (links only, no iframe). | +| `frontend/src/addons/PrometheusAddonPage.tsx` | Prometheus addon page. | +| `frontend/src/addons/SshTasksAddonPage.tsx` | SSH tasks addon page. | +| `backend/tests/test_widgets.py` | Backend API and store tests. | +| `frontend/tests/widgets.test.mjs` | Frontend registry unit tests. | + +### Modify + +| File | Rationale | +|------|-----------| +| `backend/src/media_library_viewer_api/services/settings_store.py` | Add `dashboard_widgets` schema, CRUD helpers, default seeding in `ensure_defaults()`. | +| `backend/src/media_library_viewer_api/config.py` | Add `grafana_url: str` setting (default `http://grafana:3000`) so adapters can build deep-links. Optional if Grafana URL is already derivable from env; for Phase 1 add it explicitly. | +| `backend/src/media_library_viewer_api/main.py` | Register `widgets_router`. | +| `frontend/src/pages/Dashboard.tsx` | Replace hard-coded Jellyfin/Backups sections with widget instance loop; keep Shortcuts section intact; add "Edit dashboard" action. | +| `frontend/src/App.tsx` | Add `/addons/:addonId` route in both OIDC and non-OIDC route trees. | +| `docs/REQUIREMENTS.md` | Document new widget system behavior and security rule. | + +--- + +## 8. Slice boundaries + +A full Phase 1 implementation is expected to touch ~1,000–1,200 lines across backend and frontend, exceeding the ~400-line review budget. Recommended reviewable slices: + +### Slice 1: Backend CRUD and default seeding + +- Create `models/widgets.py`. +- Create `widgets/registry.py`. +- Create `routers/widgets.py` for CRUD + metadata endpoints. +- Extend `settings_store.py` with table schema, helpers, and `_seed_dashboard_widgets()`. +- Register router in `main.py`. +- Add `backend/tests/test_widgets.py` for CRUD/registry tests. +- **Estimated:** ~350–400 changed lines. + +### Slice 2: Backend source adapters and data endpoint + +- Create `widgets/sources.py` with all six adapters. +- Add `GET /api/widgets/instances/{id}/data` endpoint. +- Add `grafana_url` to `config.py`. +- Extract/share `dashboard.py` activity mapping if needed. +- Extend tests with data-fetch scenarios. +- **Estimated:** ~300–350 changed lines. + +### Slice 3: Frontend types, API, hooks, and widget registry + +- Add TypeScript interfaces to `types/index.ts`. +- Create `api/widgets.ts` and `hooks/useWidgets.ts`. +- Create `widgets/registry.ts` and the six widget components. +- Add `frontend/tests/widgets.test.mjs`. +- **Estimated:** ~350–400 changed lines. + +### Slice 4: Dashboard rendering loop, config UI, and addon pages + +- Modify `Dashboard.tsx` to render widget instances. +- Create `WidgetInstance.tsx` and `WidgetConfigDialog.tsx`. +- Create `AddonPage.tsx` and addon pages. +- Register addon route in `App.tsx`. +- Update `docs/REQUIREMENTS.md`. +- **Estimated:** ~350–400 changed lines. + +**Recommended order:** Slice 1 → Slice 2 → Slice 3 → Slice 4. Each slice is independently testable and leaves the app in a working state. Slices 1 and 2 can be merged into one PR if the backend-only change stays under the budget; otherwise keep them separate. + +--- + +## 9. Open questions / decisions + +1. **Grafana URL source**: Add `grafana_url` to `Settings` in `config.py` (default `http://grafana:3000`). This is the minimal change; alternatively derive from `ALERTMANAGER_URL` or an env var, but explicit is clearer. +2. **Shortcuts migration**: Keep Shortcuts as a hard-coded section above widgets for Phase 1. This avoids a data migration and satisfies "no data is lost". A future phase can migrate shortcuts into the widget system. +3. **Prometheus URL**: Reuse existing `prometheus_file_sd_dir` / convention or add `prometheus_url` setting. For instant queries the adapter needs a query URL; add `prometheus_url: str = "http://prometheus:9090"` to `Settings`. diff --git a/openspec/changes/configurable-dashboard-widgets/exploration.md b/openspec/changes/configurable-dashboard-widgets/exploration.md new file mode 100644 index 0000000..a9669b9 --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/exploration.md @@ -0,0 +1,210 @@ +# SDD Explore: Configurable Dashboard Widgets + +**Change:** `configurable-dashboard-widgets` +**Phase:** explore +**Date:** 2026-06-19 + +## 1. Existing Frontend Architecture + +### Routing & navigation + +- `frontend/src/App.tsx` defines a static `navItems` array and registers routes inside ``. +- Current top-level pages: `/` Dashboard, `/observability`, `/media`, `/files`, `/backups`, `/users`, `/actions`, `/settings`. +- Sidebar and mobile drawer both consume `navItems`; adding a new addon page requires editing this file today. + +### Page structure + +- Pages live in `frontend/src/pages/`. +- Some pages are re-exported through thin entrypoints (`FileBrowser.tsx`, `Users.tsx`) while implementations live in `*.impl.tsx` files. +- `BackupsPage` and `ObservabilityPage` live under `frontend/src/components/` but are routed as pages. + +### Dashboard composition today + +- `frontend/src/pages/Dashboard.tsx` renders three hard-coded sections: + 1. **Shortcuts** — `SectionCard` + `ShortcutCard` grid. + 2. **Jellyfin activity** — `SectionCard` + `NowPlaying`. + 3. **Backups** — `BackupDashboardWidget`. +- Machine selection (e.g., active Jellyfin machine) is local component state. + +## 2. Existing Backend Architecture + +### Router registration + +- `backend/src/media_library_viewer_api/main.py` statically imports routers and calls `app.include_router(...)`. +- Existing routers: `dashboard`, `monitoring`, `media`, `files`, `jobs`, `users`, `tasks`, `settings`, `backups`. + +### Settings persistence + +- `backend/src/media_library_viewer_api/services/settings_store.py` is the single SQLite-backed store. +- Pattern: `init_schema()` creates tables, JSON columns store flexible config, CRUD helpers return plain dicts. +- Already stores: monitoring machines, SSH keys, saved tasks, dashboard shortcuts, backup jobs/runs/alerts. + +### Client resolution + +- `backend/src/media_library_viewer_api/dependencies.py` resolves machines by `machine_id` query param and service tag. +- Jellyfin/SSH/local clients are built from machine config + SSH key store. + +## 3. Widget / Addon Extension Points + +### Frontend + +| Extension point | Current state | How to reuse/extend | +|---|---|---| +| Sidebar nav | Static `navItems` | Derive from an addon registry; add dynamic `Route` entries | +| Dashboard surface | Hard-coded sections | Render widget instances from persisted config | +| Widget chrome | `SectionCard`, `MetricCard` | Reuse as container tiles | +| Page chrome | `ObservabilityPage` pattern | Model addon pages on shadcn Card + lucide icons + TanStack Query | +| Data fetching | `useDashboard`, `useBackups`, `useObservability` | Add `useWidgets` hooks per source | + +### Backend + +| Extension point | Current state | How to reuse/extend | +|---|---|---| +| Router registration | Static imports | Add a `widgets` dispatcher router or explicitly register addon routers | +| Persistence | `SettingsStore` JSON columns | Add `dashboard_widgets` / `addon_configs` tables | +| Client/credential access | `dependencies.py` machine resolution | Widget adapters reuse existing clients | +| Source adapters | None | New abstraction: `WidgetSource` per source type | + +## 4. What a Widget Needs to Consume Data + +### Source adapters (backend) + +A widget source adapter should implement a small interface, e.g.: + +```python +class WidgetSource(Protocol): + source_type: str + + async def fetch(self, config: dict[str, Any]) -> dict[str, Any]: + ... +``` + +Candidate source types: + +- `jellyfin` — reuse `JellyfinClient` for counts/sessions. +- `backups` — reuse backup summary logic already in `dashboard.py`. +- `grafana` — link/iframe metadata or query a Grafana datasource (env URL/auth already configured). +- `prometheus` — instant query via env Prometheus URL. +- `alertmanager` — summary already exists in `monitoring.py`. +- `ssh_task` / `script` — run a saved task or whitelisted script through the existing machine/task registry. +- `static` — simple text/markdown/no-data widget. + +### Config schema + +Each widget instance needs: + +- `id`, `addon_id`, `widget_type`, `title`, `icon`, `enabled` +- `source_type` + `source_config` (JSON) +- `refresh_interval_seconds` +- `layout` (position, size) or `sort_order` +- `display_options` (e.g., show header, variant) + +### Refresh / polling + +- Frontend: TanStack Query `refetchInterval` per widget type. +- Backend: short-lived proxy/adapters; avoid heavy polling for slow sources (SSH scripts). + +### Credential handling + +- **Never store secrets in widget config.** +- Jellyfin/SSH: use machine registry + SSH key store. +- Grafana/Prometheus/Alertmanager: use backend env settings (`get_settings()`). + +## 5. Key Architectural Decisions + +### Widget registry: compile-time vs runtime + +- **Compile-time** (simpler): a static map of `widget_type -> component` in the frontend and source adapters in the backend. +- **Runtime** (more “addon”): backend serves an addon manifest, frontend lazily loads component modules. +- **Recommendation**: start compile-time for Phase 1; keep the data model flexible for runtime manifests later. + +### Addon manifest format + +A minimal manifest could be: + +```yaml +id: grafana-addon +name: Grafana +icon: Activity +page: + route: /addons/grafana + component: ./addons/grafana/GrafanaPage +widgets: + - type: grafana-link + name: Grafana Link + component: ./addons/grafana/GrafanaLinkWidget + source_type: grafana + config_schema: + - name: dashboardUid + type: string +``` + +### Dashboard persistence model + +- Store widget instances globally (like current shortcuts) in a new `dashboard_widgets` table: + - `id TEXT PRIMARY KEY` + - `addon_id TEXT` + - `widget_type TEXT` + - `title TEXT` + - `config_json TEXT` + - `enabled INTEGER` + - `sort_order INTEGER` + - `created_at`, `updated_at` +- Consider a `user_id` column later if multi-user config is needed. + +### Layout + +- **Option A**: keep the existing stacked `SectionCard` list (simple, mobile-safe, no new dependencies). +- **Option B**: adopt a grid library (e.g., `react-grid-layout`) for drag/resize. +- **Recommendation**: Option A for Phase 1 to respect the thin-dashboard aesthetic and review budget. + +### Routing + +- Addon pages under `/addons/{addon_id}` avoids collisions and keeps the namespace clean. +- Alternatively top-level routes if the UX demands it. + +### Backend API surface + +Proposed endpoints: + +- `GET /api/widgets/sources` — list available source types. +- `GET /api/widgets/types` — list widget types per addon. +- `GET /api/widgets/instances` — persisted dashboard widget instances. +- `POST /api/widgets/instances` — create instance. +- `PUT /api/widgets/instances/{id}` — update instance. +- `DELETE /api/widgets/instances/{id}` — delete instance. +- `GET /api/widgets/instances/{id}/data` — fetch widget data via source adapter. + +### Admin vs user configuration + +- Today there is no RBAC; Settings is implicitly admin. +- Widget configuration can live in Settings or a new “Dashboard settings” mode. +- Keep it simple: global config, editable by any authenticated user. + +### Default widgets + +- Seed new installs with the existing defaults: Jellyfin activity, Backup summary. +- This preserves today’s out-of-box dashboard while making it configurable. + +### Error / loading states + +- Reuse `Skeleton`, `Alert`, `EmptyState` patterns from `ObservabilityPage`. +- Each widget fails independently; the dashboard continues to render. + +## 6. Patterns to Reuse + +- **UI containers**: `SectionCard`, `MetricCard`, `Card`, `Badge`. +- **Data fetching**: TanStack Query hooks with `refetchInterval`. +- **Local state**: `usePersistentState`. +- **Backend persistence**: `SettingsStore` JSON-column CRUD. +- **Dependency injection**: FastAPI `Depends` + machine/client resolution. +- **Type contracts**: Pydantic models in `backend/src/media_library_viewer_api/models/`. +- **Lazy loading**: `React.lazy` for optional addon frontends. + +## 7. Open Questions for Proposal + +1. Should Phase 1 support runtime addon discovery, or a closed built-in widget set? +2. Do we need a grid layout with drag/resize, or is the existing stacked SectionCard list sufficient? +3. Should widget configuration be global or per-user? +4. Which sources are in Phase 1? (Recommended: Jellyfin, Backups, Grafana link, Prometheus instant query, SSH saved task.) +5. Do we want addon pages to be iframes (e.g., Grafana) or custom React pages? diff --git a/openspec/changes/configurable-dashboard-widgets/proposal.md b/openspec/changes/configurable-dashboard-widgets/proposal.md new file mode 100644 index 0000000..be4231d --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/proposal.md @@ -0,0 +1,155 @@ +# SDD Proposal: Configurable Dashboard Widgets + +**Change:** `configurable-dashboard-widgets` +**Phase:** proposal +**Date:** 2026-06-19 + +## 1. Problem / Why Now + +The Manage dashboard (`frontend/src/pages/Dashboard.tsx`) currently renders three hard-coded sections: Shortcuts, Jellyfin activity, and Backups. Each new source of at-a-glance information requires editing the dashboard component and adding ad hoc backend endpoints. The user wants to surface information from many sources—Grafana, Jellyfin, SSH scripts, Prometheus, and more—without rebuilding the dashboard every time. We need a small, extensible widget system that makes the dashboard configurable while keeping the implementation within the existing FastAPI/React stack and the current thin-dashboard aesthetic. + +## 2. Target Users and Situations + +- **Primary users:** Homelab operators and small-team admins who open Manage to check overall system health. +- **Workflow moments:** + - First login of the day: scan backup status, Jellyfin activity, and key Prometheus metrics. + - Troubleshooting: jump from a widget into a dedicated addon page (e.g., Grafana dashboard, saved SSH task output). + - Onboarding a new machine: add a widget that exposes a saved SSH task or Prometheus query without a code change. +- **Urgency:** Medium. The existing dashboard already works; the pain is maintainability and visibility into an expanding set of sources. + +## 3. Product Outcome + +After Phase 1, an authenticated user can: + +- See the existing dashboard sections rendered as configurable widgets. +- Add, edit, remove, enable/disable, and reorder widgets from a single global dashboard configuration. +- Choose from a built-in set of widget types backed by Jellyfin, backup summaries, Grafana deep-links, Prometheus instant queries, and SSH saved-task output. +- Open dedicated addon pages under `/addons/{addon_id}` for widgets that need more space (e.g., Grafana details). +- Continue using the familiar stacked `SectionCard` layout on desktop and mobile. + +## 4. Scope Boundaries (Phase 1) and Non-Goals + +### In scope for Phase 1 + +- A closed, compile-time widget registry in both frontend and backend. +- Five source types: + 1. `jellyfin` — activity/counts (reuses existing `useActivity` / counts data). + 2. `backups` — backup summary (reuses `BackupDashboardWidget` logic). + 3. `grafana` — deep-link to a Grafana dashboard or panel. + 4. `prometheus` — instant query result rendered as a metric or spark value. + 5. `ssh_task` — output of a saved task (reuses saved task registry and `run_task`). +- Optional `static` text/markdown widget to dog-food the configuration UI. +- Global dashboard widget config persisted in SQLite and editable by any authenticated user. +- Addon pages rendered as custom React pages under `/addons/{addon_id}`; Grafana widgets deep-link to Grafana instead of embedding. +- Stacked `SectionCard` layout; no grid, drag, or resize. + +### Non-goals (explicitly out of scope) + +- Runtime addon discovery or dynamic component loading. +- Per-user widget configuration. +- Grid/drag/resize layout engine. +- Iframe embedding of Grafana or any other external UI. +- Public/unauthenticated widget access. +- Generic "run any script" widget; only saved tasks from the existing registry are allowed. +- Real-time WebSocket updates; polling via TanStack Query refetch intervals is sufficient. + +## 5. High-Level Approach + +### 5.1 Backend + +1. **Data model** + - Add a `dashboard_widgets` table in `SettingsStore`: + + ```sql + CREATE TABLE dashboard_widgets ( + id TEXT PRIMARY KEY, + addon_id TEXT NOT NULL, + widget_type TEXT NOT NULL, + title TEXT NOT NULL, + config_json TEXT NOT NULL, + enabled INTEGER NOT NULL DEFAULT 1, + sort_order INTEGER NOT NULL DEFAULT 0, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ); + CREATE INDEX idx_dashboard_widgets_sort ON dashboard_widgets(sort_order); + ``` + + - `config_json` stores source-specific settings (e.g., `machine_id`, `dashboard_uid`, `promql`, `task_id`). No secrets are stored here. + +2. **Widget source adapters** + - Introduce a small protocol/interface, e.g. `WidgetSource`: + + ```python + class WidgetSource(Protocol): + source_type: str + async def fetch(self, config: dict[str, Any]) -> dict[str, Any]: ... + ``` + + - Implement one adapter per source type. Adapters reuse existing dependency-injection helpers (`get_jellyfin_client`, `get_ssh_client`, saved task registry, Grafana/Prometheus URLs from `get_settings()`). + +3. **API surface** + - `GET /api/widgets/sources` — list available source types. + - `GET /api/widgets/types` — list built-in widget types per addon. + - `GET /api/widgets/instances` — persisted widget instances. + - `POST /api/widgets/instances` — create instance. + - `PUT /api/widgets/instances/{id}` — update instance. + - `DELETE /api/widgets/instances/{id}` — delete instance. + - `GET /api/widgets/instances/{id}/data` — fetch data via the source adapter. + +4. **Default data** + - On first install, seed `dashboard_widgets` with the existing defaults: Jellyfin activity and Backup summary. Existing dashboards keep their current behavior after upgrade. + +### 5.2 Frontend + +1. **Widget registry** + - A static TypeScript map: `widget_type -> { component, defaultConfig, configSchema }`. + - Components render inside the existing `SectionCard` container and use `MetricCard`, `Skeleton`, `Alert`, and `Badge` patterns already present in `ObservabilityPage`. + +2. **Dashboard rendering** + - `Dashboard.tsx` replaces its three hard-coded sections with a loop over widget instances returned by `useWidgetsInstances()`. + - Each widget fetches its own data through `useWidgetData(widgetId, refreshInterval)` with TanStack Query `refetchInterval`. + +3. **Configuration UI** + - Add an "Edit dashboard" action that opens a dialog/panel listing widget instances. + - Reuse the form patterns from `ShortcutDialog` and `Settings.tsx` for add/edit widget forms. + - Source-specific fields are rendered by small config sub-forms registered next to each widget type. + +4. **Addon pages** + - Register a wildcard-ish route `/addons/:addonId` in `App.tsx` that renders an `AddonPage` component. + - `AddonPage` looks up the addon in a static map and renders its dedicated page component (e.g., `GrafanaAddonPage`). + - Sidebar/nav items for addons are added to the existing `navItems` array in Phase 1; dynamic nav is deferred to a future phase. + +### 5.3 Type contracts + +- Add Pydantic models in `backend/src/media_library_viewer_api/models/` for `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`. +- Add matching TypeScript interfaces in `frontend/src/types/index.ts`. + +## 6. Success Criteria / Acceptance Criteria + +1. A fresh install shows the Jellyfin activity and Backup summary widgets by default. +2. An authenticated user can add, edit, enable/disable, delete, and reorder widgets; changes persist across reloads. +3. All five Phase 1 source types can be selected and rendered without errors when configured correctly. +4. A misconfigured widget fails gracefully: the rest of the dashboard renders, and the widget shows an error state. +5. Addon page route `/addons/{addon_id}` renders a custom React page for the selected addon. +6. Existing backend tests and frontend typecheck (`npm run build`) continue to pass. +7. No secrets are stored in `config_json`. + +## 7. Risks and Mitigations + +| Risk | Mitigation | +|------|------------| +| Scope creep toward a full grid/layout engine | Document and enforce Phase 1 non-goals; keep stacked `SectionCard` layout. | +| Widget source adapters duplicating backend logic | Reuse existing routers/clients via dependency injection rather than reimplementing endpoints. | +| Slow SSH-task widgets blocking dashboard renders | Fetch each widget independently; short timeouts; display loading/error states per widget. | +| Secrets leaking into widget config | Validate config schema server-side; reject credential fields; rely on machine/SSH key store and env settings. | +| Upgrade path breaks existing dashboards | Seed default widget rows on first install only; leave existing shortcuts/sections untouched. | +| Review budget overrun (~400 changed lines) | Keep the registry closed and compile-time; avoid generic schema editors; defer dynamic routing. | + +## 8. Future Phases + +1. **Per-user dashboards** — add `user_id` column and UI toggle between global and personal layouts. +2. **Runtime addon discovery** — backend serves an addon manifest; frontend lazily loads addon page modules. +3. **Grid layout** — optional `react-grid-layout` integration with drag/resize behind a feature flag. +4. **Additional sources** — Alertmanager summary, Loki log snippets, custom HTTP endpoints, Jellyseerr requests. +5. **Widget templates/export** — import/export widget layouts and shareable presets. diff --git a/openspec/changes/configurable-dashboard-widgets/specs/dashboard-widgets/spec.md b/openspec/changes/configurable-dashboard-widgets/specs/dashboard-widgets/spec.md new file mode 100644 index 0000000..8011275 --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/specs/dashboard-widgets/spec.md @@ -0,0 +1,576 @@ +# Dashboard Widgets Specification + +> Domain: `dashboard-widgets` · Change: `configurable-dashboard-widgets` +> Full spec (no prior canonical spec exists for this domain). + +## Purpose + +Define WHAT must be true after Phase 1 of the configurable dashboard widgets change: the Manage dashboard becomes a persisted, configurable stack of widget instances backed by a closed, compile-time registry. Authenticated users can add, edit, enable/disable, reorder, and remove widgets; widget data is fetched independently; misconfigured widgets fail gracefully; and addon pages render under `/addons/{addon_id}`. + +## Scope Summary + +### In scope + +- Closed compile-time widget/source registries in the backend and frontend. +- SQLite persistence of widget instances (`dashboard_widgets` table). +- Source adapters for `jellyfin`, `backups`, `grafana`, `prometheus`, and `ssh_task`, plus a `static` text/markdown widget. +- REST API for widget instance CRUD and per-instance data fetch. +- Dashboard rendering loop in `Dashboard.tsx` using widget instances. +- Configuration UI for add/edit/reorder/remove widgets. +- Addon page route `/addons/:addonId` with a static addon page registry. +- Default widget seeding on first install. + +### Out of scope (reminders) + +- Runtime addon discovery or dynamic component loading. +- Per-user widget configuration. +- Grid, drag, or resize layout engine. +- Iframe embedding of Grafana or any external UI. +- Public/unauthenticated widget access. +- Generic "run any script" widget; only saved tasks from the existing registry are allowed. +- Real-time WebSocket updates. + +## Requirements + +### Requirement: Widget instance persistence + +The backend MUST persist widget instances in a `dashboard_widgets` table with the following columns and invariants: + +- `id` TEXT PRIMARY KEY +- `addon_id` TEXT NOT NULL +- `widget_type` TEXT NOT NULL +- `title` TEXT NOT NULL +- `config_json` TEXT NOT NULL (source-specific JSON config) +- `enabled` INTEGER NOT NULL DEFAULT 1 +- `sort_order` INTEGER NOT NULL DEFAULT 0 +- `created_at` INTEGER NOT NULL +- `updated_at` INTEGER NOT NULL + +The table MUST have an index on `sort_order` named `idx_dashboard_widgets_sort`. + +The `SettingsStore` MUST provide CRUD helpers that return plain Python dicts matching the API response shape. `config_json` MUST be stored as JSON text and validated on write. + +#### Scenario: Create and read a widget instance + +- GIVEN an empty `dashboard_widgets` table +- WHEN the store creates a widget instance with `addon_id="core"`, `widget_type="static"`, `title="Notes"`, `config_json={"text":"hello"}`, `enabled=true`, `sort_order=1` +- THEN `list_widgets()` returns a list containing one item with the same field values +- AND `created_at` and `updated_at` are Unix epoch seconds + +#### Scenario: Update enabled and sort_order + +- GIVEN an existing widget instance +- WHEN the store updates `enabled` to `false` and `sort_order` to `5` +- THEN subsequent reads reflect the new values +- AND `updated_at` is greater than or equal to the write time + +#### Scenario: Delete a widget instance + +- GIVEN an existing widget instance +- WHEN the store deletes it by `id` +- THEN `list_widgets()` no longer returns that instance + +--- + +### Requirement: Default widget seeding on first install + +On first install (when `dashboard_widgets` is empty during startup or `ensure_defaults`), the system MUST seed exactly two default widget instances: + +1. `addon_id="core"`, `widget_type="jellyfin"`, `title="Jellyfin activity"`, enabled, sort_order before backups. +2. `addon_id="backups"`, `widget_type="backups"`, `title="Backups"`, enabled, sort_order after Jellyfin. + +Existing installations with one or more widget rows MUST NOT be modified by the seeding logic. + +#### Scenario: Fresh install shows default widgets + +- GIVEN a fresh settings database with no `dashboard_widgets` rows +- WHEN the backend starts or `ensure_defaults()` runs +- THEN `GET /api/widgets/instances` returns exactly the Jellyfin activity and Backups widgets in that order +- AND both are enabled + +#### Scenario: Existing install is not re-seeded + +- GIVEN a settings database with at least one `dashboard_widgets` row +- WHEN the backend starts +- THEN the existing widget rows remain unchanged +- AND no new default rows are inserted + +--- + +### Requirement: Closed widget and source registries + +The widget system MUST use a closed, compile-time registry. The backend MUST reject any `widget_type` not in the registry and any `source_type` without a registered adapter. + +Phase 1 built-in widget types: + +| `widget_type` | `addon_id` | Source adapter | Purpose | +|---|---|---|---| +| `jellyfin` | `core` | `jellyfin` | Activity/counts from a Jellyfin machine | +| `backups` | `backups` | `backups` | Backup summary stats | +| `grafana-link` | `grafana` | `grafana` | Deep-link to a Grafana dashboard or panel | +| `prometheus-metric` | `prometheus` | `prometheus` | Instant query rendered as a metric | +| `ssh-task` | `ssh-tasks` | `ssh_task` | Output of a saved task | +| `static` | `core` | `static` | Plain text/markdown widget | + +#### Scenario: Unknown widget type is rejected + +- GIVEN a `POST /api/widgets/instances` request with `widget_type="unknown"` +- WHEN the request is processed +- THEN the response status is `422 Unprocessable Entity` +- AND the response body contains a validation error naming the unsupported widget type + +#### Scenario: Source registry is fixed + +- GIVEN `GET /api/widgets/sources` +- WHEN the endpoint responds +- THEN the list contains exactly `jellyfin`, `backups`, `grafana`, `prometheus`, `ssh_task`, and `static` + +--- + +### Requirement: Widget config validation + +Each widget type MUST have a JSON config schema. The backend MUST validate `config_json` against the schema on create and update and reject credential fields. + +The following keys are forbidden anywhere in `config_json` (case-insensitive): + +- `password`, `token`, `secret`, `api_key`, `apikey`, `private_key`, `passphrase`, `credential` + +Any value that is a non-empty string and looks like a secret (e.g., starts with `sk-`, `eyJ`, or is longer than 64 random-looking characters) SHOULD be rejected as a defense-in-depth measure. + +#### Scenario: Valid static widget config passes + +- GIVEN a `POST /api/widgets/instances` request with `widget_type="static"` and `config_json={"text":"Hello"}` +- WHEN the request is processed +- THEN the response status is `200 OK` or `201 Created` +- AND the stored `config_json` equals the submitted value + +#### Scenario: Credential field in config is rejected + +- GIVEN a `POST /api/widgets/instances` request with `config_json={"api_key":"abc123"}` +- WHEN the request is processed +- THEN the response status is `422 Unprocessable Entity` +- AND the error message indicates that credential fields are not allowed + +#### Scenario: Jellyfin config requires machine_id + +- GIVEN a `POST` for `widget_type="jellyfin"` with `config_json={}` +- WHEN the request is processed +- THEN the response status is `422 Unprocessable Entity` +- AND the error indicates that `machine_id` is required + +--- + +### Requirement: Widget source adapters + +Each source adapter MUST implement a uniform async interface: + +```python +class WidgetSource(Protocol): + source_type: str + async def fetch(self, config: dict[str, Any]) -> dict[str, Any]: ... +``` + +Adapters MUST reuse existing dependency-injection helpers and MUST NOT reimplement client logic: + +- `jellyfin`: `get_jellyfin_client` + existing `client.sessions()` / counts. +- `backups`: `BackupDashboardSummary` building logic from `dashboard.py`. +- `grafana`: `get_settings()` Grafana URL; only returns deep-link metadata, never embeds. +- `prometheus`: `get_settings()` Prometheus URL; performs an instant query via HTTP. +- `ssh_task`: existing saved task registry + `run_task` helper. +- `static`: returns the text/markdown from `config_json` unchanged. + +Adapters MUST catch their own exceptions and return an error payload; they MUST NOT raise unhandled exceptions into the endpoint. + +#### Scenario: Jellyfin adapter returns sessions + +- GIVEN a Jellyfin widget configured with a valid `machine_id` +- WHEN `GET /api/widgets/instances/{id}/data` is called +- THEN the response contains a `data` field with activity rows +- AND `error` is null + +#### Scenario: SSH task adapter times out gracefully + +- GIVEN an `ssh-task` widget configured with a slow task +- WHEN the adapter exceeds its timeout +- THEN it returns `{ "error": "Widget data fetch timed out" }` +- AND the HTTP endpoint still responds with `200 OK` carrying the error payload + +--- + +### Requirement: API contract + +The backend MUST expose the following endpoints under `/api/widgets`, protected by the existing JWT/API-key auth: + +| Method | Path | Purpose | Success | Error | +|---|---|---|---|---| +| GET | `/api/widgets/sources` | List source types | `200 OK` + list of strings | 401/403 | +| GET | `/api/widgets/types` | List widget types per addon | `200 OK` + `WidgetTypeInfo[]` | 401/403 | +| GET | `/api/widgets/instances` | List persisted instances | `200 OK` + `WidgetInstance[]` | 401/403 | +| POST | `/api/widgets/instances` | Create instance | `201 Created` + `WidgetInstance` | 400/401/403/422 | +| PUT | `/api/widgets/instances/{id}` | Update instance | `200 OK` + `WidgetInstance` | 400/401/403/404/422 | +| DELETE | `/api/widgets/instances/{id}` | Delete instance | `200 OK` + `{status:"deleted"}` | 401/403/404 | +| GET | `/api/widgets/instances/{id}/data` | Fetch widget data | `200 OK` + `WidgetDataResponse` | 401/403/404/500 | + +`WidgetInstance` response fields (exact names): + +- `id`: string +- `addon_id`: string +- `widget_type`: string +- `title`: string +- `config`: object (parsed JSON) +- `enabled`: boolean +- `sort_order`: number +- `created_at`: number +- `updated_at`: number + +`WidgetInstanceInput` request fields: + +- `id`: string | null (optional on create) +- `addon_id`: string +- `widget_type`: string +- `title`: string +- `config`: object +- `enabled`: boolean +- `sort_order`: number + +`WidgetTypeInfo` fields: + +- `addon_id`: string +- `widget_type`: string +- `name`: string +- `description`: string +- `source_type`: string +- `config_schema`: JSON Schema object + +`WidgetDataResponse` fields: + +- `widget_id`: string +- `widget_type`: string +- `data`: object | null +- `error`: string | null +- `fetched_at`: number (Unix epoch seconds) + +#### Scenario: Create widget instance via API + +- GIVEN an authenticated `POST /api/widgets/instances` with a valid `WidgetInstanceInput` +- WHEN the request is processed +- THEN the response status is `201 Created` +- AND the response body contains the created `WidgetInstance` with a generated `id` + +#### Scenario: Update nonexistent widget returns 404 + +- GIVEN an authenticated `PUT /api/widgets/instances/does-not-exist` +- WHEN the request is processed +- THEN the response status is `404 Not Found` + +#### Scenario: Data endpoint returns error for misconfigured widget + +- GIVEN a widget whose adapter returns an error payload +- WHEN `GET /api/widgets/instances/{id}/data` is called +- THEN the response status is `200 OK` +- AND `error` is a non-empty string +- AND `data` is null + +--- + +### Requirement: Type contracts + +The Pydantic models in the backend and the TypeScript interfaces in the frontend MUST use the exact field names listed above. + +Backend Pydantic models MUST live in `backend/src/media_library_viewer_api/models/widgets.py` and MUST include: + +- `WidgetInstance` +- `WidgetInstanceInput` +- `WidgetTypeInfo` +- `WidgetDataResponse` + +Frontend TypeScript interfaces MUST be added to `frontend/src/types/index.ts`: + +- `WidgetInstance` +- `WidgetInstanceInput` +- `WidgetTypeInfo` +- `WidgetDataResponse` +- `WidgetSource` (string union of source types) + +#### Scenario: Backend model serializes config as object + +- GIVEN a `WidgetInstance` model initialized from a database row with `config_json='{"text":"x"}'` +- WHEN it is serialized with `model_dump()` +- THEN `config` is the parsed object `{"text":"x"}` + +#### Scenario: Frontend type matches API response + +- GIVEN the `WidgetInstance` TypeScript interface +- WHEN a widget instance payload from `GET /api/widgets/instances` is typed with it +- THEN `npm run build` succeeds without type errors + +--- + +### Requirement: Dashboard rendering loop + +`frontend/src/pages/Dashboard.tsx` MUST render widget instances returned by `useWidgetInstances()` instead of the three hard-coded sections. + +The dashboard MUST: + +- Query widget instances on mount. +- Render only instances with `enabled === true`. +- Sort enabled instances by `sort_order` ascending. +- Render each widget inside the existing `SectionCard` container. +- Pass the widget instance to a registered widget component. +- Preserve the existing stacked layout (`flex flex-col gap-4`). +- Keep the existing Shortcuts functionality as a widget type or continue to support it as a first-class widget instance (`widget_type="shortcuts"` or equivalent) so that no data is lost. + +#### Scenario: Fresh install rendering + +- GIVEN a fresh install with default widgets +- WHEN the Dashboard page loads +- THEN it renders the Jellyfin activity widget followed by the Backups widget +- AND both fetch their own data independently + +#### Scenario: Disabled widget is hidden + +- GIVEN a widget instance with `enabled=false` +- WHEN the Dashboard renders +- THEN that widget is not rendered +- AND the remaining widgets maintain their sort order + +#### Scenario: Misconfigured widget fails gracefully + +- GIVEN a dashboard with one valid widget and one widget whose data endpoint returns an error +- WHEN the Dashboard renders +- THEN the valid widget displays normally +- AND the failing widget renders an inline `Alert` with the error message +- AND the rest of the dashboard is not blocked + +--- + +### Requirement: Independent widget data fetching + +Each widget MUST fetch its own data independently via `useWidgetData(widgetId, refreshInterval)`. The hook MUST use TanStack Query with a per-widget `refetchInterval`. + +Default refresh intervals: + +- `jellyfin`: 30 seconds +- `backups`: 60 seconds +- `grafana`: 0 (no polling; static link) +- `prometheus`: 30 seconds +- `ssh_task`: 0 (fetch on mount only; heavy) +- `static`: 0 + +A widget component MUST show a loading state while data is being fetched for the first time and MUST show an error state if `error` is non-null. + +#### Scenario: Jellyfin widget auto-refreshes + +- GIVEN a rendered Jellyfin widget +- WHEN 30 seconds elapse +- THEN `useWidgetData` refetches the data automatically + +#### Scenario: Grafana widget does not poll + +- GIVEN a rendered Grafana-link widget +- WHEN it mounts +- THEN it fetches data once to build the deep-link +- AND it does not refetch automatically + +--- + +### Requirement: Configuration UI + +The Dashboard MUST provide an "Edit dashboard" action that opens a configuration panel or dialog. The panel MUST allow the user to: + +- See all widget instances (enabled and disabled). +- Add a new widget by choosing a widget type from the closed registry. +- Edit a widget's `title`, `enabled` flag, `sort_order`, and source-specific `config`. +- Remove a widget with a confirmation step. +- Reorder widgets by changing `sort_order` (simple numeric input or up/down buttons). + +Source-specific config fields MUST be rendered by small sub-forms registered next to each widget type in the frontend registry. + +The UI MUST reuse existing shadcn/ui form patterns (`Dialog`, `Input`, `Label`, `Switch`, `Select`, `Button`, `Alert`). + +#### Scenario: User adds a Grafana-link widget + +- GIVEN the dashboard configuration panel is open +- WHEN the user selects widget type `grafana-link`, enters `title="Grafana Overview"`, `config.dashboard_uid="overview"`, and saves +- THEN a new widget instance is persisted +- AND it appears on the dashboard with a deep-link to Grafana + +#### Scenario: User disables a widget + +- GIVEN the dashboard configuration panel is open and a widget is enabled +- WHEN the user toggles its `enabled` switch off and saves +- THEN the widget disappears from the dashboard +- AND it remains in the instances list with `enabled=false` + +#### Scenario: Reorder widgets + +- GIVEN two widgets with sort_order 0 and 1 +- WHEN the user swaps their sort_order values and saves +- THEN the dashboard re-renders them in the new order + +--- + +### Requirement: Addon pages + +The frontend MUST register a route `/addons/:addonId` in `App.tsx`. The `AddonPage` component MUST look up `addonId` in a static addon registry and render the matching page component. + +Phase 1 addon registry MUST include at least: + +- `grafana` — `GrafanaAddonPage` +- `prometheus` — `PrometheusAddonPage` +- `ssh-tasks` — `SshTasksAddonPage` + +Navigating to an unknown `addonId` MUST render a 404-style message inside the page shell. + +Grafana widgets MUST deep-link to Grafana (using env-configured URL) instead of embedding. + +#### Scenario: Addon page navigation + +- GIVEN the user clicks "Open Grafana addon" from a Grafana widget +- WHEN the browser navigates to `/addons/grafana` +- THEN the `GrafanaAddonPage` component renders +- AND the page shows Grafana deep-links and no iframe + +#### Scenario: Unknown addon page + +- GIVEN a navigation to `/addons/unknown` +- WHEN the route resolves +- THEN the page renders an `Alert` stating the addon is not found +- AND the sidebar and shell remain intact + +--- + +## Non-Functional Requirements + +### Requirement: Security — no secrets in widget config + +The system MUST ensure that widget `config_json` never stores secrets. Credential detection MUST be applied both at the Pydantic model level and at the store write level. Backend adapters MUST resolve credentials from the existing machine/SSH-key store or environment settings. + +#### Scenario: Secret-looking value rejected + +- GIVEN a widget config containing `"token": "super-secret-api-token-value"` +- WHEN the create/update endpoint processes it +- THEN the request is rejected with `422 Unprocessable Entity` + +--- + +### Requirement: Performance — independent fetches and timeouts + +Each widget data fetch MUST be independent. A slow or failing adapter MUST NOT block other widgets or the dashboard render. Adapters MUST apply a short timeout: + +- `jellyfin`: 10 seconds +- `backups`: 10 seconds +- `prometheus`: 10 seconds +- `ssh_task`: 30 seconds +- `grafana`: 5 seconds +- `static`: no fetch + +The dashboard MUST render the widget chrome immediately and show loading skeletons while data loads. + +#### Scenario: Slow widget does not block dashboard + +- GIVEN a dashboard with three widgets, one of which takes 25 seconds +- WHEN the dashboard loads +- THEN the other two widgets render their data immediately +- AND the slow widget shows a loading skeleton until it completes or times out + +--- + +### Requirement: Maintainability — closed registry + +The widget and source registries MUST be closed and compile-time. Adding a new widget type or source adapter MUST require a code change in both backend and frontend registries. There MUST be no plugin loading, dynamic imports, or runtime manifests in Phase 1. + +#### Scenario: Registry is discoverable in source + +- GIVEN the source code +- WHEN searching for the list of supported widget types +- THEN it is found as an explicit map/list in the backend and frontend source files + +--- + +## Invariants and Validation Rules + +1. `widget_type` MUST be in the closed registry. +2. `addon_id` MUST match the addon registered for the widget type. +3. `config_json` MUST be valid JSON and MUST validate against the widget type's JSON schema. +4. `config_json` MUST NOT contain keys matching the forbidden credential list. +5. `sort_order` MUST be a non-negative integer. +6. `enabled` MUST be a boolean. +7. The data endpoint for a disabled widget MUST still function if called directly, but the dashboard MUST NOT render it. +8. A widget instance's `id` MUST be immutable after creation. +9. Source adapters MUST be stateless and MUST NOT persist widget-specific secrets. +10. Addon page components MUST NOT embed external iframes. + +## Error Handling Requirements + +| Flow / Endpoint | Expected Error Condition | Response | +|---|---|---| +| `GET /api/widgets/instances` | Unauthenticated | `401 Unauthorized` | +| `POST /api/widgets/instances` | Invalid JSON | `400 Bad Request` | +| `POST /api/widgets/instances` | Unknown `widget_type` | `422 Unprocessable Entity` | +| `POST /api/widgets/instances` | Config fails schema validation | `422 Unprocessable Entity` | +| `POST /api/widgets/instances` | Config contains credential key | `422 Unprocessable Entity` | +| `PUT /api/widgets/instances/{id}` | Widget not found | `404 Not Found` | +| `PUT /api/widgets/instances/{id}` | ID in path mismatches body | `400 Bad Request` | +| `DELETE /api/widgets/instances/{id}` | Widget not found | `404 Not Found` | +| `GET /api/widgets/instances/{id}/data` | Widget not found | `404 Not Found` | +| `GET /api/widgets/instances/{id}/data` | Adapter raises unhandled exception | `500 Internal Server Error` with a safe message | +| `GET /api/widgets/instances/{id}/data` | Adapter returns error payload | `200 OK` with `error` set | +| Dashboard render | Widget data hook errors | Inline error state; dashboard continues | +| Configuration UI | Network error on save | Inline `Alert`; form remains open | + +## Scenario Catalog + +### Scenario: Fresh install shows default widgets + +- GIVEN a fresh settings database +- WHEN the backend starts and the Dashboard page loads +- THEN `GET /api/widgets/instances` returns two enabled widgets: Jellyfin activity and Backups +- AND the Dashboard renders them in order + +### Scenario: User adds a Grafana-link widget + +- GIVEN the Dashboard configuration panel is open +- WHEN the user chooses `grafana-link`, sets `title="Grafana Overview"`, `config.dashboard_uid="overview"`, and saves +- THEN `POST /api/widgets/instances` succeeds +- AND the new widget appears on the dashboard +- AND clicking the widget opens the Grafana dashboard in a new tab + +### Scenario: User disables a widget + +- GIVEN a widget is enabled and visible on the dashboard +- WHEN the user opens the configuration panel, toggles the widget off, and saves +- THEN `PUT /api/widgets/instances/{id}` returns `enabled=false` +- AND the widget is no longer rendered on the dashboard + +### Scenario: Misconfigured widget fails gracefully + +- GIVEN a `prometheus-metric` widget with an invalid `promql` query +- WHEN the dashboard renders +- THEN the widget shows an error Alert with a message from the adapter +- AND all other widgets render normally +- AND the dashboard remains scrollable and interactive + +### Scenario: Addon page navigation + +- GIVEN a Grafana widget with a configured dashboard +- WHEN the user clicks the addon deep-link +- THEN the browser navigates to `/addons/grafana` +- AND the `GrafanaAddonPage` renders with relevant deep-links +- AND no iframe is present + +## File Targets (Informative) + +- Backend models: `backend/src/media_library_viewer_api/models/widgets.py` +- Backend router: `backend/src/media_library_viewer_api/routers/widgets.py` +- Backend source adapters: `backend/src/media_library_viewer_api/widgets/*.py` +- Backend store: extend `backend/src/media_library_viewer_api/services/settings_store.py` +- Backend main: register router in `backend/src/media_library_viewer_api/main.py` +- Frontend types: `frontend/src/types/index.ts` +- Frontend API client: `frontend/src/api/widgets.ts` +- Frontend hooks: `frontend/src/hooks/useWidgets.ts` +- Frontend widget registry: `frontend/src/widgets/registry.ts` +- Frontend widget components: `frontend/src/widgets/*.tsx` +- Frontend dashboard: `frontend/src/pages/Dashboard.tsx` +- Frontend addon page: `frontend/src/pages/AddonPage.tsx` +- Frontend app routes: `frontend/src/App.tsx` diff --git a/openspec/changes/configurable-dashboard-widgets/tasks.md b/openspec/changes/configurable-dashboard-widgets/tasks.md new file mode 100644 index 0000000..09e0252 --- /dev/null +++ b/openspec/changes/configurable-dashboard-widgets/tasks.md @@ -0,0 +1,270 @@ +# SDD Tasks: Configurable Dashboard Widgets + +**Change:** `configurable-dashboard-widgets` +**Phase:** tasks +**Date:** 2026-06-19 + +## Review Workload Forecast + +| Field | Value | +|-------|-------| +| Estimated changed lines | ~1,550–1,650 (sum of four implementation slices) | +| 400-line budget risk | High | +| Chained PRs recommended | Yes | +| Suggested split | PR 1: Backend CRUD + default seeding → PR 2: Backend source adapters + data endpoint → PR 3: Frontend types/API/hooks/registry/components → PR 4: Dashboard loop + config UI + addon pages | +| Delivery strategy | ask-on-risk | +| Chain strategy | stacked-to-main | + +```text +Decision needed before apply: Yes +Chained PRs recommended: Yes +Chain strategy: stacked-to-main +400-line budget risk: High +``` + +> **Note:** The preflight preference is `single-PR-default`, but the Phase 1 implementation clearly exceeds the ~400 changed-line review budget. The recommended split above keeps every slice independently testable and green. Confirm the chained-PR strategy before moving to `sdd-apply`. + +--- + +## Phase 1 Goal + +Replace the hard-coded dashboard sections in `frontend/src/pages/Dashboard.tsx` with a persisted, closed-registry widget system. Backend stores widget instances in SQLite, exposes CRUD + per-widget data endpoints, and provides source adapters for Jellyfin, backups, Grafana links, Prometheus instant queries, saved SSH tasks, and static text. Frontend renders enabled widgets in sort order, fetches data independently, and provides a configuration UI plus `/addons/:addonId` pages. + +--- + +## Slice 1: Backend CRUD and default seeding + +**Goal:** Persist widget instances and expose registry metadata + CRUD endpoints. Leave all source adapters and data fetch for Slice 2. + +- [x] **1.1 Create widget Pydantic models** + - Files: `backend/src/media_library_viewer_api/models/widgets.py` (new) + - Lines: ~70 + - Dependencies: none + - Details: Add `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`. Include credential-key validator (`password`, `token`, `secret`, `api_key`, etc.) and secret-looking-value heuristic. + +- [x] **1.2 Create backend widget registry** + - Files: `backend/src/media_library_viewer_api/widgets/__init__.py` (new), `backend/src/media_library_viewer_api/widgets/registry.py` (new) + - Lines: ~50 + - Dependencies: 1.1 + - Details: Define `WIDGET_REGISTRY` mapping `widget_type` → `addon_id`, `name`, `description`, `source_type`, JSON Schema `config_schema` for all six Phase 1 types. + +- [x] **1.3 Implement widgets router (CRUD + metadata)** + - Files: `backend/src/media_library_viewer_api/routers/widgets.py` (new) + - Lines: ~110 + - Dependencies: 1.1, 1.2 + - Details: Implement `GET /api/widgets/sources`, `GET /api/widgets/types`, `GET /api/widgets/instances`, `POST /api/widgets/instances` (201), `PUT /api/widgets/instances/{id}`, `DELETE /api/widgets/instances/{id}`. Validate `widget_type` and `addon_id` against registry; validate config schema; reject credential keys. + +- [x] **1.4 Extend `SettingsStore` for `dashboard_widgets`** + - Files: `backend/src/media_library_viewer_api/services/settings_store.py` + - Lines: ~90 + - Dependencies: none + - Details: Add table + index `idx_dashboard_widgets_sort`, `_row_to_widget`, `_normalize_widget_payload`, `list_widgets`, `get_widget`, `upsert_widget`, `delete_widget`, and `_seed_dashboard_widgets` (Jellyfin + Backups defaults only when table is empty). + +- [x] **1.5 Register widgets router in `main.py`** + - Files: `backend/src/media_library_viewer_api/main.py` + - Lines: ~5 + - Dependencies: 1.3 + - Details: `app.include_router(widgets_router.router)`; endpoints inherit existing JWT/API-key middleware. + +- [x] **1.6 Add backend tests for registry, CRUD, and seeding** + - Files: `backend/tests/test_widgets.py` (new) + - Lines: ~75 + - Dependencies: 1.3, 1.4 + - Details: Test sources/types lists, create/read/update/delete, unknown widget type → 422, credential key → 422, fresh-store seeding, existing store not re-seeded. + +- [x] **1.7 Verify backend slice** + - Run: `cd backend && ruff check . && PYTHONPATH=src pytest tests/test_widgets.py` + +**Slice 1 total:** ~400 changed lines. + +--- + +## Slice 2: Backend source adapters and data endpoint + +**Goal:** Fetch widget data through stateless adapters reusing existing DI and clients. + +- [ ] **2.1 Add observability URL settings** + - Files: `backend/src/media_library_viewer_api/config.py` + - Lines: ~15 + - Dependencies: none + - Details: Add `grafana_url: str = "http://grafana:3000"` and `prometheus_url: str = "http://prometheus:9090"`. + +- [ ] **2.2 Create source adapters** + - Files: `backend/src/media_library_viewer_api/widgets/sources.py` (new) + - Lines: ~200 + - Dependencies: 1.2, 2.1 + - Details: Implement `WidgetSource` protocol + adapters for `jellyfin`, `backups`, `grafana`, `prometheus`, `ssh_task`, `static`. Catch exceptions and return `{"error": "..."}`. Apply per-type timeouts (10 s / 10 s / 5 s / 10 s / 30 s / none). + +- [ ] **2.3 Add per-widget data endpoint** + - Files: `backend/src/media_library_viewer_api/routers/widgets.py` + - Lines: ~35 + - Dependencies: 1.3, 2.2 + - Details: Implement `GET /api/widgets/instances/{id}/data`, returning `WidgetDataResponse` with `widget_id`, `widget_type`, `data`, `error`, `fetched_at`. Unhandled adapter exceptions → 500. + +- [ ] **2.4 Share Jellyfin activity mapping helper** + - Files: `backend/src/media_library_viewer_api/routers/dashboard.py`, `backend/src/media_library_viewer_api/domain/dashboard.py` (new) + - Lines: ~25 + - Dependencies: 2.2 + - Details: Move `_map_sessions_to_activity_rows` to `domain/dashboard.py`; import it from both `routers/dashboard.py` and the Jellyfin adapter. + +- [ ] **2.5 Add backend tests for adapters and data endpoint** + - Files: `backend/tests/test_widgets.py` + - Lines: ~85 + - Dependencies: 2.2, 2.3 + - Details: Test static widget data round-trip, misconfigured jellyfin returns `error` with HTTP 200, SSH task adapter timeout returns error payload, unhandled exception path returns 500. + +- [ ] **2.6 Verify backend slice** + - Run: `cd backend && ruff check . && PYTHONPATH=src pytest tests/test_widgets.py` + +**Slice 2 total:** ~360 changed lines. + +--- + +## Slice 3: Frontend types, API, hooks, registry, and widget components + +**Goal:** Build the frontend widget runtime: types, API client, hooks, closed registry, and presentational components. No dashboard integration yet. + +- [ ] **3.1 Add TypeScript widget interfaces** + - Files: `frontend/src/types/index.ts` + - Lines: ~45 + - Dependencies: none + - Details: Add `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`, and `WidgetSource` union type with exact field names from the spec. + +- [ ] **3.2 Create widget API client** + - Files: `frontend/src/api/widgets.ts` (new) + - Lines: ~60 + - Dependencies: 3.1 + - Details: Functions for `fetchWidgetSources`, `fetchWidgetTypes`, `fetchWidgetInstances`, `createWidgetInstance`, `updateWidgetInstance`, `deleteWidgetInstance`, `fetchWidgetData`. + +- [ ] **3.3 Create widget TanStack Query hooks** + - Files: `frontend/src/hooks/useWidgets.ts` (new) + - Lines: ~70 + - Dependencies: 3.2 + - Details: `useWidgetInstances`, `useWidgetData(widgetId, refreshInterval)`, `useSaveWidgetInstance`, `useDeleteWidgetInstance`, `useWidgetSources`, `useWidgetTypes`. Use correct per-type `refetchInterval`. + +- [ ] **3.4 Create frontend widget registry** + - Files: `frontend/src/widgets/registry.ts` (new) + - Lines: ~70 + - Dependencies: 3.1 + - Details: Define `WidgetConfigField`, `WidgetDefinition`, `WIDGET_REGISTRY` for all six types, `getWidgetDefinition`, plus `refreshInterval` defaults. + +- [ ] **3.5 Implement widget presentational components** + - Files: `frontend/src/widgets/JellyfinWidget.tsx`, `BackupsWidget.tsx`, `GrafanaLinkWidget.tsx`, `PrometheusMetricWidget.tsx`, `SshTaskWidget.tsx`, `StaticWidget.tsx` + - Lines: ~150 + - Dependencies: 3.1, 3.3, 3.4 + - Details: Each component receives `widget: WidgetInstance` and renders inside the existing card patterns. Grafana widget renders an external deep-link only (no iframe). + +- [ ] **3.6 Add frontend registry unit tests** + - Files: `frontend/tests/widgets.test.mjs` (new) + - Lines: ~40 + - Dependencies: 3.4 + - Details: Assert registry contains exactly six widget types and refresh intervals match spec. + +- [ ] **3.7 Verify frontend slice** + - Run: `cd frontend && npm run lint && npm run build` + +**Slice 3 total:** ~435 changed lines. + +--- + +## Slice 4: Dashboard loop, configuration UI, and addon pages + +**Goal:** Wire widgets into the dashboard, add configuration UI, and add addon page routes. + +- [ ] **4.1 Refactor `Dashboard.tsx` to render widget instances** + - Files: `frontend/src/pages/Dashboard.tsx` + - Lines: ~60 + - Dependencies: Slice 3 + - Details: Keep the existing Shortcuts section as a hard-coded first-class section (no migration). Add an "Edit dashboard" button. Render enabled widgets sorted by `sort_order` via ``. + +- [ ] **4.2 Create widget instance renderer** + - Files: `frontend/src/components/WidgetInstance.tsx` (new) + - Lines: ~40 + - Dependencies: 3.3, 3.4, 3.5 + - Details: Lookup definition, call `useWidgetData`, show skeleton on first load, render inline `Alert` for `error`, dispatch to registered component. + +- [ ] **4.3 Create widget configuration dialog** + - Files: `frontend/src/components/WidgetConfigDialog.tsx` (new) + - Lines: ~160 + - Dependencies: 3.3, 3.4 + - Details: List all instances with enabled toggle, sort-order input, up/down reorder, edit/delete. Add widget flow selects type then renders source-specific config fields. Use existing shadcn `Dialog`, `Input`, `Label`, `Switch`, `Select`, `Button`, `Alert`. + +- [ ] **4.4 Create addon pages** + - Files: `frontend/src/pages/AddonPage.tsx` (new), `frontend/src/addons/GrafanaAddonPage.tsx` (new), `frontend/src/addons/PrometheusAddonPage.tsx` (new), `frontend/src/addons/SshTasksAddonPage.tsx` (new) + - Lines: ~130 + - Dependencies: none + - Details: `AddonPage` maps `addonId` to static page components; unknown addon shows an `Alert`. Pages render links/metadata only (no iframes). + +- [ ] **4.5 Register addon route in `App.tsx`** + - Files: `frontend/src/App.tsx` + - Lines: ~5 + - Dependencies: 4.4 + - Details: Add `} />` in both the OIDC and non-OIDC route trees. + +- [ ] **4.6 Update `docs/REQUIREMENTS.md`** + - Files: `docs/REQUIREMENTS.md` + - Lines: ~25 + - Dependencies: none + - Details: Document configurable dashboard widgets, supported source types, security rule (no secrets in config), and addon pages. + +- [ ] **4.7 Verify frontend slice and full build** + - Run: `cd frontend && npm run lint && npm run build` + +**Slice 4 total:** ~420 changed lines. + +--- + +## Integration and acceptance verification + +- [ ] **5.1 Backend full test run** + - Run: `cd backend && PYTHONPATH=src pytest` + - Verify existing tests still pass and `test_widgets.py` covers registry, CRUD, seeding, and data fetch. + +- [ ] **5.2 Frontend full build + lint** + - Run: `cd frontend && npm run lint && npm run build` + - Verify no TypeScript errors and no new lint failures. + +- [ ] **5.3 Manual dev-stack verification** + - Run: `docker compose -f docker-compose.dev.yml up --build` + - Verify: + - Fresh install shows Jellyfin activity + Backups widgets. + - Disabled widget is hidden. + - Reorder changes dashboard order. + - Misconfigured widget shows inline error without blocking dashboard. + - `/addons/grafana`, `/addons/prometheus`, `/addons/ssh-tasks` render; unknown addon shows not-found alert. + - No widget config can contain `api_key`, `token`, `secret`, etc. + +--- + +## Total Phase 1 estimate + +| Slice | Changed lines | +|-------|---------------| +| Slice 1: Backend CRUD + seeding | ~400 | +| Slice 2: Backend adapters + data endpoint | ~360 | +| Slice 3: Frontend runtime (types/API/hooks/registry/components) | ~435 | +| Slice 4: Dashboard loop + config UI + addon pages | ~420 | +| Integration tests/docs | ~25 | +| **Total** | **~1,640** | + +This exceeds the ~400-line review budget. Use the four chained PRs above; each slice is independently buildable/testable and leaves the app functional. + +--- + +## Tests and docs summary + +- **Backend tests:** New `backend/tests/test_widgets.py` covering registry, CRUD, validation, default seeding, and adapter data fetch. Run with `pytest`. +- **Frontend tests:** New `frontend/tests/widgets.test.mjs` covering registry contents and refresh intervals. Run implicitly via `npm run build`/`lint`; add Vitest/MSW tests only if the project adopts Vitest before this change. +- **Typecheck/build:** `npm run build` (runs `tsc -b`) must pass for every slice. +- **Docs:** Update `docs/REQUIREMENTS.md` to describe the widget system, security rule, and addon pages. + +--- + +## Guard lines + +```text +Decision needed before apply: Yes +Chained PRs recommended: Yes +Chain strategy: stacked-to-main +400-line budget risk: High +```