diff --git a/.gitignore b/.gitignore index 9c4908d..a97f31f 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ samples/small-library/generated/ *.db *.csv *.html +!serato_doctor/webui/*.html # Never commit personal Serato data database V2 diff --git a/README.md b/README.md index 0212d77..aa0dd3c 100644 --- a/README.md +++ b/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. diff --git a/ROADMAP.md b/ROADMAP.md index 4c0fa46..4761c91 100644 --- a/ROADMAP.md +++ b/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 diff --git a/docs/design/web-interface.md b/docs/design/web-interface.md new file mode 100644 index 0000000..d39a474 --- /dev/null +++ b/docs/design/web-interface.md @@ -0,0 +1,30 @@ +# Local Web Interface + +## 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. diff --git a/pyproject.toml b/pyproject.toml index 5ec7c93..5e90afc 100644 --- a/pyproject.toml +++ b/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"] diff --git a/serato_doctor/web.py b/serato_doctor/web.py new file mode 100644 index 0000000..739939a --- /dev/null +++ b/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() diff --git a/serato_doctor/webui/__init__.py b/serato_doctor/webui/__init__.py new file mode 100644 index 0000000..36d1869 --- /dev/null +++ b/serato_doctor/webui/__init__.py @@ -0,0 +1 @@ +"""Static assets for the local Serato Doctor web interface.""" diff --git a/serato_doctor/webui/app.css b/serato_doctor/webui/app.css new file mode 100644 index 0000000..7b289c8 --- /dev/null +++ b/serato_doctor/webui/app.css @@ -0,0 +1 @@ +:root{--bg:#090b10;--panel:rgba(22,25,34,.86);--panel-2:#171a23;--line:rgba(255,255,255,.08);--text:#f4f5f7;--muted:#9298a7;--violet:#9b87f5;--cyan:#66d9e8;--amber:#f5b94c;--red:#f17878;--radius:22px;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:var(--text);background:var(--bg)}*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;min-height:100vh;background:radial-gradient(circle at 75% -10%,rgba(98,79,181,.16),transparent 32%),var(--bg)}.ambient{position:fixed;border-radius:999px;filter:blur(90px);pointer-events:none;opacity:.16}.ambient-one{width:420px;height:420px;background:#674ce0;top:10%;right:5%}.ambient-two{width:320px;height:320px;background:#1b8a9b;bottom:0;left:20%}.shell{display:grid;grid-template-columns:250px 1fr;min-height:100vh}.sidebar{position:sticky;top:0;height:100vh;padding:28px 22px;border-right:1px solid var(--line);background:rgba(10,12,17,.72);backdrop-filter:blur(24px);display:flex;flex-direction:column;z-index:2}.brand{display:flex;align-items:center;gap:12px;color:var(--text);text-decoration:none;margin:0 8px 42px}.brand-mark{display:grid;place-items:center;width:42px;height:42px;border-radius:13px;background:linear-gradient(145deg,var(--violet),#6651ce);font-weight:800;letter-spacing:-1px;box-shadow:0 10px 30px rgba(126,103,235,.28)}.brand strong,.brand small{display:block}.brand small{color:var(--muted);letter-spacing:.14em;text-transform:uppercase;font-size:9px;margin-top:2px}.sidebar nav{display:grid;gap:8px}.nav-item{padding:12px 14px;border-radius:12px;color:var(--muted);text-decoration:none;font-size:14px;display:flex;gap:11px;align-items:center}.nav-item:hover,.nav-item.active{color:var(--text);background:rgba(255,255,255,.06)}.nav-item.active{box-shadow:inset 2px 0 var(--violet)}.safety-card{margin-top:auto;display:flex;gap:10px;padding:14px;border:1px solid rgba(102,217,232,.18);border-radius:16px;background:rgba(31,79,87,.18)}.safety-icon{display:grid;place-items:center;width:25px;height:25px;border-radius:50%;background:rgba(102,217,232,.16);color:var(--cyan);font-weight:700;flex:0 0 auto}.safety-card strong{font-size:12px}.safety-card p{font-size:11px;color:var(--muted);line-height:1.45;margin:4px 0 0}.sidebar-foot{font-size:10px;color:#656b79;margin:18px 10px 0}.shell main{padding:36px clamp(24px,5vw,72px) 70px;max-width:1500px;width:100%;margin:0 auto}.topbar{display:flex;align-items:center;justify-content:space-between;margin-bottom:32px}.eyebrow{text-transform:uppercase;letter-spacing:.16em;color:var(--violet);font-size:10px;font-weight:750;margin:0 0 7px}.topbar h1{font-size:clamp(26px,4vw,38px);letter-spacing:-.04em;margin:0}.status-pill,.read-only-tag{font-size:11px;color:#b7bdc9;border:1px solid var(--line);border-radius:999px;padding:9px 12px;background:rgba(255,255,255,.03)}.status-pill span{display:inline-block;width:7px;height:7px;border-radius:50%;background:#54d49a;margin-right:7px;box-shadow:0 0 12px #54d49a}.panel{background:linear-gradient(145deg,rgba(28,31,42,.93),rgba(18,21,29,.88));border:1px solid var(--line);border-radius:var(--radius);box-shadow:0 24px 80px rgba(0,0,0,.2)}.scan-panel{padding:clamp(24px,4vw,40px);display:grid;grid-template-columns:minmax(220px,.7fr) minmax(360px,1.3fr);gap:42px;align-items:center}.panel-copy h2,.section-heading h2{font-size:24px;letter-spacing:-.03em;margin:0 0 11px}.panel-copy>p:last-child{color:var(--muted);line-height:1.65;font-size:13px;max-width:440px}.scan-panel form{display:grid;grid-template-columns:1fr 1fr;gap:14px}.scan-panel label{font-size:11px;color:#c7cad2;font-weight:650}.scan-panel label span{color:#696f7e;font-weight:400}.scan-panel input,.scan-panel textarea{display:block;width:100%;margin-top:7px;border:1px solid var(--line);background:rgba(6,8,12,.56);color:var(--text);padding:12px 13px;border-radius:11px;outline:none;font:inherit;font-size:12px;resize:vertical}.scan-panel input:focus,.scan-panel textarea:focus{border-color:rgba(155,135,245,.7);box-shadow:0 0 0 3px rgba(155,135,245,.08)}.wide{grid-column:1/-1}.scan-panel button{grid-column:1/-1;border:0;border-radius:12px;padding:13px 16px;background:linear-gradient(135deg,#a08cf5,#7763dc);color:#fff;font:inherit;font-size:13px;font-weight:750;display:flex;justify-content:space-between;cursor:pointer;box-shadow:0 12px 30px rgba(115,91,213,.25)}.scan-panel button:hover{filter:brightness(1.08);transform:translateY(-1px)}.scan-panel button:disabled{opacity:.6;cursor:wait}.error{grid-column:1/-1;margin-top:14px;padding:12px 14px;color:#ffc5c5;background:rgba(160,48,48,.18);border:1px solid rgba(241,120,120,.25);border-radius:12px;font-size:12px}.results{margin-top:42px}.section-heading{display:flex;align-items:flex-end;justify-content:space-between;margin:0 2px 18px}.section-heading h2{margin:0}.section-heading>span{color:var(--muted);font-size:11px}.hero-grid{display:grid;grid-template-columns:1fr 1.35fr;gap:18px}.score-card{padding:28px;display:flex;gap:25px;align-items:center}.score-ring{--score:0;display:grid;place-items:center;flex:0 0 auto;width:140px;height:140px;border-radius:50%;background:conic-gradient(var(--violet) calc(var(--score)*1%),rgba(255,255,255,.06) 0);position:relative}.score-ring:before{content:"";position:absolute;inset:9px;border-radius:50%;background:#151821}.score-ring>div{position:relative;text-align:center}.score-ring strong{font-size:28px;letter-spacing:-.05em;display:block}.score-ring span{font-size:10px;text-transform:uppercase;letter-spacing:.13em;color:var(--muted)}.score-label{color:var(--violet);font-size:11px;font-weight:700;margin:0 0 7px}.score-card h3{font-size:20px;margin:0 0 7px}.score-card p:last-child{font-size:11px;color:var(--muted);line-height:1.5;margin:0}.metrics-grid{display:grid;grid-template-columns:1fr 1fr;gap:12px}.metric{padding:20px}.metric span{display:block;font-size:11px;color:var(--muted)}.metric strong{font-size:28px;letter-spacing:-.04em;display:block;margin:9px 0 2px}.metric small{font-size:10px;color:#656b79}.metric.warning strong{color:var(--amber)}.diagnostics{margin-top:18px;padding:25px}.diagnostic-list{display:grid;grid-template-columns:1fr 1fr;gap:10px}.diagnostic-list>div{display:flex;gap:13px;align-items:center;padding:14px;border-radius:14px;background:rgba(255,255,255,.025);border:1px solid rgba(255,255,255,.045)}.diag-icon{display:grid;place-items:center;width:34px;height:34px;border-radius:10px;flex:0 0 auto}.diag-icon.violet{color:var(--violet);background:rgba(155,135,245,.11)}.diag-icon.amber{color:var(--amber);background:rgba(245,185,76,.1)}.diag-icon.blue{color:var(--cyan);background:rgba(102,217,232,.1)}.diag-icon.red{color:var(--red);background:rgba(241,120,120,.1)}.diagnostic-list p{margin:0}.diagnostic-list strong{display:block;font-size:12px}.diagnostic-list small{display:block;color:var(--muted);font-size:10px;margin-top:5px}.diagnostic-list b{color:#cdd1d9;font-weight:650}@media(max-width:980px){.shell{grid-template-columns:82px 1fr}.sidebar{padding:25px 13px}.brand{margin-left:6px}.brand>span:last-child,.nav-item:not(.active){font-size:0}.nav-item{justify-content:center}.nav-item span{font-size:17px}.safety-card div,.sidebar-foot{display:none}.safety-card{padding:12px;justify-content:center}.scan-panel{grid-template-columns:1fr}.hero-grid{grid-template-columns:1fr}}@media(max-width:680px){.shell{display:block}.sidebar{position:static;width:100%;height:auto;flex-direction:row;align-items:center;padding:14px 18px}.brand{margin:0 auto 0 0}.brand>span:last-child{display:block}.sidebar nav{display:flex}.nav-item{padding:10px}.nav-item:not(.active),.safety-card,.sidebar-foot{display:none}.shell main{padding:24px 16px 50px}.topbar{margin-bottom:22px}.status-pill{display:none}.scan-panel{padding:22px;gap:20px}.scan-panel form{grid-template-columns:1fr}.scan-panel label,.wide,.scan-panel button{grid-column:1}.hero-grid{grid-template-columns:1fr}.score-card{flex-direction:column;text-align:center}.metrics-grid,.diagnostic-list{grid-template-columns:1fr 1fr}.section-heading{align-items:flex-start}}@media(max-width:440px){.metrics-grid,.diagnostic-list{grid-template-columns:1fr}.score-ring{width:126px;height:126px}} diff --git a/serato_doctor/webui/app.js b/serato_doctor/webui/app.js new file mode 100644 index 0000000..be52602 --- /dev/null +++ b/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'; + } +}); diff --git a/serato_doctor/webui/index.html b/serato_doctor/webui/index.html new file mode 100644 index 0000000..8c69585 --- /dev/null +++ b/serato_doctor/webui/index.html @@ -0,0 +1,87 @@ + + + + + + + Serato Doctor + + + +
+
+
+ + +
+
+

Library intelligence

Good evening.

+
Local & private
+
+ +
+
+

Start here

+

Analyze your library

+

Point Serato Doctor at your Serato and music folders. We inspect references, duplicates, smart crates, and symlinks without changing a thing.

+
+
+ + + + +
+ +
+ + +
+
+ + + diff --git a/tests/test_web.py b/tests/test_web.py new file mode 100644 index 0000000..2205933 --- /dev/null +++ b/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())