Document approved dashboard direction

.gitignore

@@ -9,6 +9,7 @@ samples/small-library/generated/
 *.db
 *.csv
 *.html
+!serato_doctor/webui/*.html
 
 # Never commit personal Serato data
 database V2

README.md

@@ -35,3 +35,14 @@ aggregate diagnostic log.
 
 Serato Doctor never repairs files without an explicit future repair workflow,
 preview, backup, and rollback path.
+
+## Local Web Interface
+
+Launch the responsive, local-only dashboard with:
+
+```shell
+serato-doctor-web
+```
+
+Then open `http://127.0.0.1:8765`. The interface exposes the same read-only health
+analysis and never sends library paths or results to an external service.

ROADMAP.md

@@ -7,7 +7,7 @@
 - [x] Serato crate parser
 - [x] Missing reference CSV report
 - [x] Grouped missing reference report
-- [ ] HTML health dashboard
+- [x] HTML health dashboard
 - [x] Test suite
 - [x] Sample library fixtures
 - [ ] Database V2 read-only parser

docs/design/web-interface.md

@@ -0,0 +1,37 @@
+# Local Web Interface
+
+![Approved Serato Doctor dashboard concept](web-dashboard-concept.png)
+
+The generated concept above is the approved visual direction. The implemented UI
+keeps its hierarchy, palette, safety emphasis, health ring, diagnostic cards, and
+responsive behavior. Product truth takes precedence over mockup copy: a 77.8%
+library is labeled for review rather than described as healthy.
+
+## Problem
+
+The command line is useful for automation but makes the growing diagnostic set
+harder to explore. A visual dashboard lets users test analysis safely and understand
+which findings affect health.
+
+## Architecture
+
+`serato-doctor-web` binds to `127.0.0.1:8765` by default and serves package-owned
+HTML, CSS, and JavaScript with Python's standard library. A same-origin JSON endpoint
+runs the existing read-only parser, scanner, matcher, duplicate detector, crate
+classifier, and health engine. No web framework or external service is required.
+
+The UI clearly labels read-only mode, separates scored health from informational
+diagnostics, and adapts from a full sidebar layout to compact mobile navigation.
+
+## Edge Cases
+
+- Missing or invalid Serato and music directories.
+- Empty libraries with no assessable health score.
+- Large or malformed requests, capped at 64 KiB.
+- HTML injection, avoided by rendering all results through `textContent`.
+- Network exposure, avoided by a loopback-only default binding.
+
+## Verification
+
+Tests exercise the web analysis adapter and static package assets. Browser checks
+cover real form submission, result rendering, error display, and responsive layout.

pyproject.toml

@@ -14,9 +14,13 @@ dev = ["pytest>=8,<9"]
 
 [project.scripts]
 serato-doctor = "serato_doctor.cli:main"
+serato-doctor-web = "serato_doctor.web:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
 [tool.setuptools.packages.find]
 include = ["serato_doctor*"]
+
+[tool.setuptools.package-data]
+"serato_doctor.webui" = ["*.html", "*.css", "*.js"]

serato_doctor/web.py

@@ -0,0 +1,110 @@
+import argparse
+import json
+from dataclasses import asdict
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from pathlib import Path
+from typing import Iterable
+
+from serato_doctor.crate_parser import load_library_crates
+from serato_doctor.health import analyze_health
+from serato_doctor.models.library import Library
+from serato_doctor.scanner import scan_filesystem
+
+
+MAX_REQUEST_BYTES = 64 * 1024
+STATIC_FILES = {
+    "/": ("index.html", "text/html; charset=utf-8"),
+    "/app.css": ("app.css", "text/css; charset=utf-8"),
+    "/app.js": ("app.js", "text/javascript; charset=utf-8"),
+}
+
+
+def analyze_paths(
+    serato: Path, music: Path, reference_roots: Iterable[Path] = ()
+) -> dict:
+    serato = serato.expanduser()
+    music = music.expanduser()
+    reference_roots = tuple(root.expanduser() for root in reference_roots)
+    if not serato.is_dir():
+        raise ValueError(f"Serato folder does not exist: {serato}")
+    if not music.is_dir():
+        raise ValueError(f"Music folder does not exist: {music}")
+
+    crates = load_library_crates(serato, reference_roots)
+    filesystem = scan_filesystem(music)
+    library = Library.from_crates(
+        crates,
+        filesystem.tracks,
+        filesystem.broken_symlinks,
+    )
+    report = analyze_health(library)
+    result = asdict(report)
+    result["score_basis"] = report.score_basis
+    return result
+
+
+class SeratoDoctorHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        asset = STATIC_FILES.get(self.path)
+        if asset is None:
+            self._json_response(404, {"error": "Not found"})
+            return
+        filename, content_type = asset
+        content = (
+            resources.files("serato_doctor.webui")
+            .joinpath(filename)
+            .read_bytes()
+        )
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def do_POST(self) -> None:
+        if self.path != "/api/analyze":
+            self._json_response(404, {"error": "Not found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+            if length <= 0 or length > MAX_REQUEST_BYTES:
+                raise ValueError("Invalid request size")
+            payload = json.loads(self.rfile.read(length))
+            if not isinstance(payload, dict):
+                raise ValueError("Request body must be a JSON object")
+            roots = [Path(value) for value in payload.get("reference_roots", [])]
+            result = analyze_paths(
+                Path(payload["serato"]), Path(payload["music"]), roots
+            )
+        except (KeyError, TypeError, json.JSONDecodeError, ValueError) as error:
+            self._json_response(400, {"error": str(error)})
+            return
+        self._json_response(200, result)
+
+    def _json_response(self, status: int, payload: dict) -> None:
+        content = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="serato-doctor-web")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    server = ThreadingHTTPServer((args.host, args.port), SeratoDoctorHandler)
+    print(f"Serato Doctor web interface: http://{args.host}:{args.port}")
+    print("Press Ctrl+C to stop.")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()

serato_doctor/webui/__init__.py

@@ -0,0 +1 @@
+"""Static assets for the local Serato Doctor web interface."""

serato_doctor/webui/app.js

@@ -0,0 +1,54 @@
+const form = document.querySelector('#analysis-form');
+const button = document.querySelector('#analyze-button');
+const errorBox = document.querySelector('#error-message');
+const results = document.querySelector('#dashboard');
+
+function expandHome(path) {
+  return path.trim();
+}
+
+function render(data) {
+  document.querySelectorAll('[data-field]').forEach((element) => {
+    const value = data[element.dataset.field];
+    element.textContent = value ?? '—';
+  });
+  const score = data.score;
+  document.querySelector('#health-score').textContent = score == null ? '—' : `${score}%`;
+  document.querySelector('#score-ring').style.setProperty('--score', score ?? 0);
+  document.querySelector('#health-message').textContent = score == null
+    ? 'Not enough data yet'
+    : score >= 95 ? 'Looking excellent' : score >= 80 ? 'A few things need attention' : 'Review recommended';
+  document.querySelector('#score-basis').textContent = data.score_basis;
+  document.querySelector('#analysis-time').textContent = `Completed ${new Date().toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'})}`;
+  results.hidden = false;
+  results.scrollIntoView({behavior: 'smooth', block: 'start'});
+}
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  errorBox.hidden = true;
+  button.disabled = true;
+  button.querySelector('span').textContent = 'Analyzing safely…';
+  const roots = document.querySelector('#reference-roots').value
+    .split('\n').map((value) => value.trim()).filter(Boolean);
+  try {
+    const response = await fetch('/api/analyze', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        serato: expandHome(document.querySelector('#serato-path').value),
+        music: expandHome(document.querySelector('#music-path').value),
+        reference_roots: roots,
+      }),
+    });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || 'Analysis failed');
+    render(data);
+  } catch (error) {
+    errorBox.textContent = error.message;
+    errorBox.hidden = false;
+  } finally {
+    button.disabled = false;
+    button.querySelector('span').textContent = 'Analyze library';
+  }
+});

serato_doctor/webui/index.html

@@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="dark">
+  <title>Serato Doctor</title>
+  <link rel="stylesheet" href="/app.css">
+</head>
+<body>
+  <div class="ambient ambient-one"></div>
+  <div class="ambient ambient-two"></div>
+  <div class="shell">
+    <aside class="sidebar">
+      <a class="brand" href="/" aria-label="Serato Doctor home">
+        <span class="brand-mark">SD</span>
+        <span><strong>Serato</strong><small>Doctor</small></span>
+      </a>
+      <nav aria-label="Primary navigation">
+        <a class="nav-item active" href="#dashboard"><span>⌁</span> Dashboard</a>
+        <a class="nav-item" href="#scan"><span>◎</span> New analysis</a>
+        <a class="nav-item" href="#diagnostics"><span>◇</span> Diagnostics</a>
+      </nav>
+      <div class="safety-card">
+        <span class="safety-icon">✓</span>
+        <div><strong>Read-only mode</strong><p>Your library will not be modified.</p></div>
+      </div>
+      <div class="sidebar-foot">Local interface · v0.1</div>
+    </aside>
+
+    <main>
+      <header class="topbar">
+        <div><p class="eyebrow">Library intelligence</p><h1>Good evening.</h1></div>
+        <div class="status-pill"><span></span> Local &amp; private</div>
+      </header>
+
+      <section id="scan" class="scan-panel panel">
+        <div class="panel-copy">
+          <p class="eyebrow">Start here</p>
+          <h2>Analyze your library</h2>
+          <p>Point Serato Doctor at your Serato and music folders. We inspect references, duplicates, smart crates, and symlinks without changing a thing.</p>
+        </div>
+        <form id="analysis-form">
+          <label>Serato folder
+            <input id="serato-path" name="serato" value="~/Music/_Serato_" required>
+          </label>
+          <label>Music folder
+            <input id="music-path" name="music" value="~/Music/Jukebox" required>
+          </label>
+          <label class="wide">Historical reference roots <span>optional · one per line</span>
+            <textarea id="reference-roots" rows="2" placeholder="/Users/old-user/OneDrive/Jukebox"></textarea>
+          </label>
+          <button id="analyze-button" type="submit"><span>Analyze library</span><b>→</b></button>
+        </form>
+        <div id="error-message" class="error" role="alert" hidden></div>
+      </section>
+
+      <section id="dashboard" class="results" aria-live="polite" hidden>
+        <div class="section-heading"><div><p class="eyebrow">Latest analysis</p><h2>Library health</h2></div><span id="analysis-time"></span></div>
+        <div class="hero-grid">
+          <article class="score-card panel">
+            <div class="score-ring" id="score-ring"><div><strong id="health-score">—</strong><span>health</span></div></div>
+            <div><p class="score-label">Reference integrity</p><h3 id="health-message">Ready to analyze</h3><p id="score-basis">We only score evidence we can defend.</p></div>
+          </article>
+          <div class="metrics-grid">
+            <article class="metric panel"><span>Tracks</span><strong data-field="disk_tracks">—</strong><small>audio files found</small></article>
+            <article class="metric panel warning"><span>Broken references</span><strong data-field="missing_references">—</strong><small>static crate entries</small></article>
+            <article class="metric panel"><span>Unused tracks</span><strong data-field="unused_tracks">—</strong><small>not referenced by crates</small></article>
+            <article class="metric panel"><span>Suggested matches</span><strong data-field="suggested_matches">—</strong><small>explainable candidates</small></article>
+          </div>
+        </div>
+
+        <div id="diagnostics" class="diagnostics panel">
+          <div class="section-heading"><div><p class="eyebrow">Full picture</p><h2>Diagnostics</h2></div><span class="read-only-tag">No changes made</span></div>
+          <div class="diagnostic-list">
+            <div><span class="diag-icon violet">◇</span><p><strong>Crates</strong><small><b data-field="static_crates">—</b> static · <b data-field="smart_crates">—</b> smart · <b data-field="dynamic_references_excluded">—</b> dynamic references excluded</small></p></div>
+            <div><span class="diag-icon amber">≋</span><p><strong>Duplicate filenames</strong><small><b data-field="duplicate_filename_groups">—</b> exact groups · <b data-field="duplicate_files">—</b> extra files</small></p></div>
+            <div><span class="diag-icon blue">⌁</span><p><strong>Cloud conflicts</strong><small><b data-field="suspected_cloud_conflict_groups">—</b> suspected groups · <b data-field="suspected_cloud_conflict_files">—</b> extra files</small></p></div>
+            <div><span class="diag-icon red">↗</span><p><strong>Broken symlinks</strong><small><b data-field="broken_symlinks">—</b> unresolved links</small></p></div>
+          </div>
+        </div>
+      </section>
+    </main>
+  </div>
+  <script src="/app.js" defer></script>
+</body>
+</html>

tests/test_web.py

@@ -0,0 +1,35 @@
+import runpy
+from pathlib import Path
+
+import pytest
+
+from serato_doctor.web import STATIC_FILES, analyze_paths
+
+
+def test_web_analysis_uses_production_health_pipeline(tmp_path):
+    generator = runpy.run_path(
+        str(Path(__file__).parents[1] / "samples/small-library/generate.py")
+    )
+    sample = generator["build_sample"](tmp_path / "sample")
+
+    result = analyze_paths(
+        sample / "Serato" / "_Serato_", sample / "Music"
+    )
+
+    assert result["score"] == 77.8
+    assert result["disk_tracks"] == 10
+    assert result["missing_references"] == 2
+    assert result["static_crates"] == 5
+    assert result["smart_crates"] == 2
+
+
+def test_web_analysis_rejects_missing_folders(tmp_path):
+    with pytest.raises(ValueError, match="Serato folder does not exist"):
+        analyze_paths(tmp_path / "missing", tmp_path)
+
+
+def test_web_static_assets_are_declared_and_packaged():
+    asset_root = Path(__file__).parents[1] / "serato_doctor" / "webui"
+
+    assert set(STATIC_FILES) == {"/", "/app.css", "/app.js"}
+    assert all((asset_root / filename).is_file() for filename, _ in STATIC_FILES.values())