docs: complete Jellyfin migration, archive jellyfin-service-registry

Slice 3 (final) of jellyfin-service-registry. Documents the completed migration and archives the SDD change. - docs/REQUIREMENTS.md: marked the machine-level Jellyfin follow-up resolved; added a decision-log entry (Jellyfin no longer a machine service, dead media_root/path_prefix removed; global config + path_utils retained for Jellyfin->SSH path resolution). - CHANGELOG.md: struck through the old follow-up note; added a Follow-up #2 section describing the machine field + service removal. - Archived openspec/changes/jellyfin-service-registry (no active SDD changes remain). Backend ruff clean / 239 tests pass; frontend 0 lint errors / build clean / 72 tests pass.
2026-06-24 14:56:25 +00:00
parent fd12e921fd
commit 6919158012
17 changed files with 43 additions and 22 deletions
@@ -0,0 +1,21 @@
+# openspec/changes/jellyfin-service-registry (index)
+dir: openspec/changes/jellyfin-service-registry
+
+## role
+Documentation and planning package for migrating Jellyfin service configuration from machine-level settings to a service-registry model.
+## parent
+index: openspec/changes/.pi-map.index.md
+map: openspec/changes/.pi-map.md
+## children
+-
+## files
+- design.md
+- proposal.md
+- tasks.md
+## links
+index: openspec/changes/jellyfin-service-registry/.pi-map.index.md
+map: openspec/changes/jellyfin-service-registry/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,21 @@
+# openspec/changes/jellyfin-service-registry
+dir: openspec/changes/jellyfin-service-registry
+
+index: openspec/changes/jellyfin-service-registry/.pi-map.index.md
+
+## role
+Documentation and planning package for migrating Jellyfin service configuration from machine-level settings to a service-registry model.
+## files
+- design.md | Design document for completing the migration of Jellyfin service configuration from machine-level settings to service-registry instances, involving removal of legacy media_root and path_prefix fields across backend, frontend, and docs. | dep: integrations/jellyfin.py, integrations/jellyseerr.py, dependencies.py, settings_store.py, path_utils.py, routers/files.py, types/index.ts, Settings.tsx, docs/REQUIREMENTS.md, CHANGELOG.md
+- proposal.md | Proposes completing a migration of Jellyfin configuration from machine-level settings to a service registry, removing dead fields and legacy UI elements.
+- tasks.md | Defines a task checklist for completing the migration of Jellyfin from machine-level configuration to a service registry, including backend/frontend cleanup and documentation updates. | dep: backend/src/media_library_viewer_api/services/settings_store.py, backend/src/media_library_viewer_api/path_utils.py, backend/tests, frontend/src/types/index.ts, frontend/src/pages/Settings.tsx, frontend/src/pages/__tests__/Settings.test.tsx, docs/REQUIREMENTS.md, CHANGELOG.md
+## arch
+OpenSpec change-proposal structure consisting of three coordinated documents (design, proposal, tasks) that define the rationale, technical approach, and implementation checklist for a cross-stack refactoring effort.
+## tags
+py, settings, backend, frontend, src, jellyfin, service, md
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,50 @@
+# Design — Jellyfin service-registry migration (completion)
+
+**Change:** `jellyfin-service-registry`
+**Phase:** design
+**Date:** 2026-06-23
+
+## Current state
+
+- Jellyfin/Jellyseerr service definitions exist in `integrations/jellyfin.py` and `integrations/jellyseerr.py`.
+- `dependencies.py` resolves Jellyfin clients from service records via `jellyfin_service_id`.
+- Frontend pages already select Jellyfin services via `useServiceInstances("jellyfin")`.
+- `settings_store.py` still defaults machine `services` to `["monitoring", "files", "jellyfin"]` and persists `media_root` / `path_prefix`.
+- `MonitoringMachine` / `MonitoringMachineInput` types still include `media_root` and `path_prefix`.
+- `Settings.tsx` still renders `media_root` and `path_prefix` inputs and lists `jellyfin` as a service option.
+- `path_utils.py` still has path-mapping helpers, but the callers in `files.py` no longer depend on machine-level `media_root`/`path_prefix`.
+
+## Target state
+
+### Backend
+
+- `DEFAULT_SERVICES` becomes `["monitoring", "files"]`.
+- `settings_store.py` drops `media_root` and `path_prefix` from `_normalize_machine_payload`, `_row_to_machine`, the machine table schema, and default seeding.
+- Add `DROP TABLE IF EXISTS ...` or `ALTER TABLE DROP COLUMN` cleanup as needed for existing databases (SQLite has limited `DROP COLUMN` support; prefer table rebuild or leave harmless columns).
+- `path_utils.py` is reviewed; if no callers remain, delete the module. If callers remain, ensure they do not reference machine fields.
+- `routers/files.py` confirmed to not read machine `media_root`/`path_prefix`.
+- Tests updated to remove `media_root`/`path_prefix` from fixtures.
+
+### Frontend
+
+- Remove `media_root` and `path_prefix` from `MonitoringMachine` and `MonitoringMachineInput` in `types/index.ts`.
+- Remove `jellyfin` from the machine services multi-select in `Settings.tsx`.
+- Remove `media_root` and `path_prefix` inputs from the machine editor.
+- Update `emptyMachine()` to not include these fields.
+- Update tests/fixtures.
+
+### Docs
+
+- `docs/REQUIREMENTS.md` — update the machine config description to remove Jellyfin/path-prefix fields.
+- `CHANGELOG.md` — breaking note about removed machine fields.
+
+## Slices
+
+1. **Backend cleanup** — `settings_store.py`, `config.py` (if any env vars), `path_utils.py`, tests.
+2. **Frontend cleanup** — types, `Settings.tsx`, tests.
+3. **Docs + changelog**.
+
+## Risks
+
+- Existing DB rows may have `media_root`/`path_prefix` values; dropping columns is safe but irreversible. Backups recommended.
+- `path_utils.py` may still be referenced by archive code; verify only live code is affected.
@@ -0,0 +1,41 @@
+# Proposal — Jellyfin service-registry migration (completion)
+
+**Change:** `jellyfin-service-registry`
+**Phase:** proposal
+**Date:** 2026-06-23
+
+## Problem
+
+The service-registry foundation already moved Jellyfin/Jellyseerr resolution into `dependencies.py` (`get_jellyfin_client`, `get_jellyseerr_client`, `get_user_id`) using `jellyfin_service_id`. The frontend `Applications`, `Media`, and `Users` pages already consume `useServiceInstances("jellyfin")`.
+
+However, the **machine-level config still carries legacy Jellyfin DNA** that is now dead or misleading:
+
+- `DEFAULT_SERVICES = ["monitoring", "files", "jellyfin"]` in `settings_store.py` auto-tags every local machine as a Jellyfin source.
+- The Settings machine editor still exposes `services` multi-select that can include `jellyfin`, even though Jellyfin is selected via the Services page, not via a machine.
+- `MonitoringMachine` types still carry `media_root` and `path_prefix` fields whose original purpose was Jellyfin→SSH path mapping, but the path-mapping logic in `path_utils.py` now operates independently and those fields are no longer read by the media/file flows.
+- Documentation still describes machine-level Jellyfin fields in places.
+
+This creates UI confusion (two places to think about Jellyfin) and stale surface area.
+
+## Goal
+
+Cleanly complete the Jellyfin migration onto the service registry:
+
+1. Remove Jellyfin from the machine `services` taxonomy entirely.
+2. Remove dead `media_root` / `path_prefix` machine fields from backend, frontend types, Settings form, and tests.
+3. Update path-resolution helpers to rely only on the Jellyfin service config (or explicit path-prefix settings on the service record if needed), not on machine fields.
+4. Update docs and changelog.
+
+## Non-goals
+
+- Do NOT change how Jellyfin/Jellyseerr clients are resolved in `dependencies.py` — that is already correct.
+- Do NOT remove the `jellyfin` / `jellyseerr` service definitions.
+- Do NOT add new service types or widgets in this change.
+
+## Acceptance
+
+- `grep -R "media_root\|path_prefix" backend/src frontend/src` returns only `path_utils.py` and its tests (if those helpers remain) or nothing (if the helpers are removed).
+- `jellyfin` no longer appears in machine `services` options in the Settings UI.
+- `DEFAULT_SERVICES` no longer includes `jellyfin`.
+- Backend and frontend test suites remain green.
+- Docs/CHANGELOG explain the final migration.
@@ -0,0 +1,86 @@
+# Tasks — Jellyfin service-registry migration (completion)
+
+**Change:** `jellyfin-service-registry`
+**Phase:** tasks
+**Date:** 2026-06-23
+
+## Review workload forecast
+
+| Field | Value |
+|-------|-------|
+| Estimated changed lines | ~250–350 |
+| Chained PRs recommended | No (single PR) |
+| Chain strategy | n/a |
+
+## Slice 1: Backend cleanup
+
+**Goal:** Remove Jellyfin and dead path-mapping fields from machine config.
+
+- [ ] **1.1 Drop `jellyfin` from default machine services**
+  - Files: `backend/src/media_library_viewer_api/services/settings_store.py`
+  - Lines: ~5
+  - Details: Change `DEFAULT_SERVICES = ["monitoring", "files", "jellyfin"]` to `["monitoring", "files"]`. Update all fallback/default service lists.
+
+- [ ] **1.2 Remove `media_root` and `path_prefix` machine fields**
+  - Files: `backend/src/media_library_viewer_api/services/settings_store.py`
+  - Lines: ~40
+  - Details: Remove from machine table schema (if present), `_normalize_machine_payload`, `_row_to_machine`, default seeding, and any serialization helpers.
+
+- [ ] **1.3 Review/delete `path_utils.py`**
+  - Files: `backend/src/media_library_viewer_api/path_utils.py`, `backend/tests/test_path_utils.py`
+  - Lines: ~-120 if deleted, else ~10 to confirm callers
+  - Details: Check if any live router still imports the helpers. If not, delete module and tests.
+
+- [ ] **1.4 Update backend tests**
+  - Files: `backend/tests/test_api.py`, `backend/tests/test_widgets.py`, others as needed
+  - Lines: ~20
+  - Details: Remove `media_root`/`path_prefix` from machine fixtures.
+
+- [ ] **1.5 Verify backend**
+  - Run: `cd backend && .venv/bin/ruff check . && PYTHONPATH=src .venv/bin/python -m pytest`
+
+## Slice 2: Frontend cleanup
+
+**Goal:** Remove dead machine fields and the Jellyfin service option from Settings.
+
+- [ ] **2.1 Update types**
+  - Files: `frontend/src/types/index.ts`
+  - Lines: ~10
+  - Details: Remove `media_root` and `path_prefix` from `MonitoringMachine` and `MonitoringMachineInput`.
+
+- [ ] **2.2 Update Settings form**
+  - Files: `frontend/src/pages/Settings.tsx`
+  - Lines: ~60
+  - Details: Remove `media_root` and `path_prefix` inputs, remove `jellyfin` from the services multi-select options, update `emptyMachine()` and edit reset logic.
+
+- [ ] **2.3 Update frontend tests**
+  - Files: `frontend/src/pages/__tests__/Settings.test.tsx` if it exists, or other fixtures
+  - Lines: ~15
+  - Details: Remove fields from mock machines.
+
+- [ ] **2.4 Verify frontend**
+  - Run: `cd frontend && npm run lint && npm run build && npm run test`
+
+## Slice 3: Docs + changelog
+
+**Goal:** Document the completed migration and removed fields.
+
+- [ ] **3.1 Update REQUIREMENTS.md**
+  - Files: `docs/REQUIREMENTS.md`
+  - Lines: ~10
+  - Details: Remove references to machine-level `media_root`/`path_prefix` and Jellyfin service tagging.
+
+- [ ] **3.2 Update CHANGELOG.md**
+  - Files: `CHANGELOG.md`
+  - Lines: ~10
+  - Details: Add a breaking/changed note: machine config no longer includes `media_root`, `path_prefix`, or `jellyfin` in `services`; Jellyfin is configured exclusively via Services.
+
+- [ ] **3.3 Commit**
+  - Commit message: `refactor(settings): complete Jellyfin migration onto service registry`
+
+## Acceptance
+
+- `grep -R "media_root\|path_prefix" backend/src frontend/src` returns only `path_utils.py` and tests if retained, or nothing if deleted.
+- `jellyfin` is not offered as a machine service in the Settings UI.
+- Backend `pytest` and frontend `npm run lint/build/test` all pass.
+- Docs and changelog updated.