ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(ops): config drift detection, per-resource repair and doctor sweep
Juan Denisf296e1dd61db
diff --git a/backend/app/api/doctor.py b/backend/app/api/doctor.pynew file mode 100644index 00000000..a9ab7f4f--- /dev/null+++ b/backend/app/api/doctor.py@@ -0,0 +1,104 @@+"""REST surface for the doctor sweep + configuration drift.++Mounted at /api/v1/doctor (registered in app/__init__.py). Admin-only.++Contract (the CLI codes against this too):+ GET /drift -> {'report': <last drift report>|null}+ POST /drift/check -> 202 {'job_id'}+ POST /drift/<type>/<id>/repair -> repair result; body must carry+ {'confirm': true} (400 otherwise)+ GET / -> {'report': <last doctor report>|null}+ POST /run -> runs synchronously, {'report': ...}+ POST /repair -> {'results': [...]} for body+ {'items': [{kind, type?, id?, name?}]}+"""+from flask import Blueprint, jsonify, request++from ..middleware.rbac import admin_required+from ..services.doctor_service import DoctorService+from ..services.drift_service import DRIFT_JOB_KIND, DriftService++doctor_bp = Blueprint('doctor', __name__)+++# --------------------------------------------------------------------------- #+# Drift+# --------------------------------------------------------------------------- #++@doctor_bp.route('/drift', methods=['GET'])+@admin_required+def get_drift_report():+ """Last stored drift report (null when no sweep has run yet)."""+ try:+ return jsonify({'report': DriftService.get_last_report()})+ except Exception as exc: # noqa: BLE001 — surface as a clean JSON error+ return jsonify({'error': str(exc)}), 500+++@doctor_bp.route('/drift/check', methods=['POST'])+@admin_required+def run_drift_check():+ """Enqueue a one-off drift sweep job."""+ try:+ from app.jobs.service import JobService+ job = JobService.enqueue(DRIFT_JOB_KIND, payload={}, max_attempts=1)+ return jsonify({'job_id': job.id}), 202+ except Exception as exc: # noqa: BLE001+ return jsonify({'error': str(exc)}), 500+++@doctor_bp.route('/drift/<check_type>/<resource_id>/repair', methods=['POST'])+@admin_required+def repair_drift(check_type, resource_id):+ """Repair one drifted resource. Explicit confirmation required."""+ data = request.get_json(silent=True) or {}+ if data.get('confirm') is not True:+ return jsonify({'error': 'Confirmation required: pass {"confirm": true}.'}), 400+ try:+ rid = int(resource_id) if resource_id.isdigit() else resource_id+ result = DriftService.repair(check_type, rid)+ status = 200 if result.get('success') else 400+ return jsonify(result), status+ except Exception as exc: # noqa: BLE001+ return jsonify({'error': str(exc)}), 500+++# --------------------------------------------------------------------------- #+# Doctor+# --------------------------------------------------------------------------- #++@doctor_bp.route('', methods=['GET'])+@doctor_bp.route('/', methods=['GET'])+@admin_required+def get_doctor_report():+ """Last stored doctor report (null when the doctor has never run)."""+ try:+ return jsonify({'report': DoctorService.get_last_report()})+ except Exception as exc: # noqa: BLE001+ return jsonify({'error': str(exc)}), 500+++@doctor_bp.route('/run', methods=['POST'])+@admin_required+def run_doctor():+ """Run the sweep synchronously (the doctor is interactive; every internal+ probe is time-capped) and return the fresh report."""+ try:+ report = DoctorService.run()+ return jsonify({'report': report})+ except Exception as exc: # noqa: BLE001+ return jsonify({'error': str(exc)}), 500+++@doctor_bp.route('/repair', methods=['POST'])+@admin_required+def repair_items():+ """Batch-repair the explicit items the operator selected."""+ data = request.get_json(silent=True) or {}+ items = data.get('items')+ if not isinstance(items, list) or not items:+ return jsonify({'error': "Body must carry a non-empty 'items' list."}), 400+ try:+ return jsonify({'results': DoctorService.repair(items)})+ except Exception as exc: # noqa: BLE001+ return jsonify({'error': str(exc)}), 500diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.pyindex c502a29f..c0827721 100644--- a/backend/app/notifications/catalog.py+++ b/backend/app/notifications/catalog.py@@ -100,6 +100,14 @@ _CATALOG = {'severity': 'warning','category': 'system',},+ # Daily drift sweep found managed config files that no longer match what+ # the panel would write (see app/services/drift_service.py).+ 'drift.detected': {+ 'title': 'Configuration drift detected ({count})',+ 'template': 'generic',+ 'severity': 'warning',+ 'category': 'system',+ },# Multi-alert monitoring digest (used by the legacy send_all path).'monitoring.alert': {'title': 'ServerKit alert',diff --git a/backend/app/services/compose_env_service.py b/backend/app/services/compose_env_service.pyindex 58f5f94c..7385e547 100644--- a/backend/app/services/compose_env_service.py+++ b/backend/app/services/compose_env_service.py@@ -121,6 +121,71 @@ class ComposeEnvService:"""return str(value).replace('$', '$$')+ @classmethod+ def render_override(cls, project_path, compose_file=None):+ """Compute the override that *should* exist for a project dir, without+ touching disk. Extracted from :meth:`refresh_for_project` so drift+ detection can render the expected file content in-memory.++ Returns ``{'applies': bool, 'path': str|None, 'content': str|None}``:+ ``applies=False`` when this dir isn't a managed compose app (leave it+ alone); ``content=None`` (with ``applies=True``) when no override should+ exist. May raise — :meth:`refresh_for_project` wraps it.+ """+ if not project_path or not os.path.isdir(project_path):+ return {'applies': False, 'path': None, 'content': None}++ app = cls._app_for_project(project_path)+ if app is None:+ # Not a managed app dir (e.g. a proxy stack) — leave it alone.+ return {'applies': False, 'path': None, 'content': None}++ base = cls.find_base_compose(project_path, compose_file)+ if not base:+ return {'applies': False, 'path': None, 'content': None}+ override_path = cls.override_path(project_path)+ base_path = base if os.path.isabs(base) else os.path.join(project_path, base)+ service_names = cls._service_names(base_path)+ if not service_names:+ return {'applies': True, 'path': override_path, 'content': None}++ from app.services.env_service import EnvService+ # Per-service effective env: a variable lands on every service unless+ # it targets a specific one (EnvironmentVariable/SharedVariable+ # .target_service). Local env vars override shared variable groups.+ per_service = EnvService.get_effective_env_for_services(app.id, service_names)++ services_block = {}+ for name in service_names:+ svc_env = (per_service or {}).get(name) or {}+ if not svc_env:+ continue # nothing targeted at this service+ services_block[name] = {+ 'environment': {k: cls._escape(v) for k, v in svc_env.items() if k}+ }++ # Per-app resource limits (task #23): cap the app's primary+ # (first-declared) compose service. mem_limit/cpus apply with plain+ # (non-swarm) docker compose.+ limits = cls._limits_block(app)+ if limits:+ services_block.setdefault(service_names[0], {}).update(limits)++ if not services_block:+ # Nothing to inject → no override should exist.+ return {'applies': True, 'path': override_path, 'content': None}+ override = {'services': services_block}++ header = (+ '# Managed by ServerKit — do not edit.\n'+ '# Injects the app\'s effective environment (shared variable groups\n'+ '# under the app\'s own local env vars) into every compose service,\n'+ '# plus any per-app resource limits on the primary service.\n'+ '# Regenerated on every deploy; delete it and it will be recreated.\n'+ )+ content = header + yaml.safe_dump(override, default_flow_style=False, sort_keys=True)+ return {'applies': True, 'path': override_path, 'content': content}+@classmethoddef refresh_for_project(cls, project_path, compose_file=None):"""Regenerate (or remove) the env override for a project dir.@@ -129,63 +194,16 @@ class ComposeEnvService:Best-effort and fully guarded — never raises."""try:- if not project_path or not os.path.isdir(project_path):+ spec = cls.render_override(project_path, compose_file)+ if not spec['applies']:return None-- app = cls._app_for_project(project_path)- if app is None:- # Not a managed app dir (e.g. a proxy stack) — leave it alone.- return None-- base = cls.find_base_compose(project_path, compose_file)- if not base:- return None- base_path = base if os.path.isabs(base) else os.path.join(project_path, base)- service_names = cls._service_names(base_path)- if not service_names:- cls._remove_override(project_path)- return None-- from app.services.env_service import EnvService- # Per-service effective env: a variable lands on every service unless- # it targets a specific one (EnvironmentVariable/SharedVariable- # .target_service). Local env vars override shared variable groups.- per_service = EnvService.get_effective_env_for_services(app.id, service_names)-- services_block = {}- for name in service_names:- svc_env = (per_service or {}).get(name) or {}- if not svc_env:- continue # nothing targeted at this service- services_block[name] = {- 'environment': {k: cls._escape(v) for k, v in svc_env.items() if k}- }-- # Per-app resource limits (task #23): cap the app's primary- # (first-declared) compose service. mem_limit/cpus apply with plain- # (non-swarm) docker compose.- limits = cls._limits_block(app)- if limits:- services_block.setdefault(service_names[0], {}).update(limits)-- if not services_block:+ if spec['content'] is None:# Nothing to inject → make sure no stale override lingers.cls._remove_override(project_path)return None- override = {'services': services_block}-- override_path = cls.override_path(project_path)- header = (- '# Managed by ServerKit — do not edit.\n'- '# Injects the app\'s effective environment (shared variable groups\n'- '# under the app\'s own local env vars) into every compose service,\n'- '# plus any per-app resource limits on the primary service.\n'- '# Regenerated on every deploy; delete it and it will be recreated.\n'- )- with open(override_path, 'w', encoding='utf-8') as f:- f.write(header)- yaml.safe_dump(override, f, default_flow_style=False, sort_keys=True)- return override_path+ with open(spec['path'], 'w', encoding='utf-8') as f:+ f.write(spec['content'])+ return spec['path']except Exception as e: # pragma: no cover - defensivelogger.warning('compose env overlay refresh failed for %s: %s', project_path, e)return Nonediff --git a/backend/app/services/doctor_service.py b/backend/app/services/doctor_service.pynew file mode 100644index 00000000..983b9ccc--- /dev/null+++ b/backend/app/services/doctor_service.py@@ -0,0 +1,265 @@+"""One-shot "doctor" health sweep + explicit batch repair.++Aggregates the drift report (drift_service) with a handful of cheap host+health probes into a single ``{'checks': [...], 'ran_at': ...}`` report the+Monitoring → Doctor tab renders. Everything is best-effort and bounded — the+doctor is interactive (the API runs it synchronously), so no probe may hang.++Nothing here repairs anything automatically: :meth:`DoctorService.repair`+runs only for the explicit items the operator selected.+"""+import json+import logging+import sys+from datetime import datetime, timedelta++logger = logging.getLogger(__name__)++DOCTOR_JOB_KIND = 'doctor.run'+LAST_REPORT_KEY = 'doctor_last_report'++# Core host services the doctor probes and is allowed to restart on demand.+CORE_SERVICES = ('nginx', 'docker')++CERT_WARN_DAYS = 14+DISK_WARN_FREE_PCT = 10.0+DISK_FAIL_FREE_PCT = 5.0++# Cap for the synchronous probes that shell out (systemctl is-active).+PROBE_TIMEOUT_SECONDS = 10+++def _check(key, title, status, detail, repairable=False, repair_ref=None):+ return {+ 'key': key,+ 'title': title,+ 'status': status, # 'ok' | 'warn' | 'fail'+ 'detail': detail,+ 'repairable': bool(repairable),+ 'repair_ref': repair_ref,+ }+++class DoctorService:+ """Run the health sweep, store the last report, batch-repair on demand."""++ # ------------------------------------------------------------------ #+ # Sub-checks (each best-effort; a probe failure = a 'warn' entry, never+ # an exception out of run()).+ # ------------------------------------------------------------------ #++ @classmethod+ def _drift_checks(cls):+ from app.services.drift_service import DriftService+ checks = []+ try:+ results = DriftService.check_all()+ except Exception as e: # noqa: BLE001+ return [_check('drift', 'Configuration drift', 'warn',+ f'Drift sweep failed: {e}')]+ for r in results:+ key = f"drift.{r['type']}.{r['id']}" if r['id'] is not None else f"drift.{r['type']}"+ title = f"Drift: {r['name']}"+ if r['status'] == 'in_sync':+ checks.append(_check(key, title, 'ok', 'Matches the expected configuration.'))+ elif r['status'] in ('drifted', 'missing'):+ detail = ('Managed file is missing on disk.' if r['status'] == 'missing'+ else 'On-disk file differs from what ServerKit would write.')+ entry = _check(+ key, title, 'warn', detail, repairable=True,+ repair_ref={'kind': 'drift', 'type': r['type'], 'id': r['id']},+ )+ entry['diff'] = r.get('diff')+ checks.append(entry)+ else: # error+ checks.append(_check(key, title, 'warn',+ r.get('detail') or 'Check could not run.'))+ return checks++ @classmethod+ def _service_checks(cls):+ checks = []+ if not sys.platform.startswith('linux'):+ for name in CORE_SERVICES:+ checks.append(_check(f'service.{name}', f'{name} service', 'warn',+ 'unsupported on this host'))+ return checks+ from app.utils.system import ServiceControl+ for name in CORE_SERVICES:+ try:+ active = ServiceControl.is_active(name)+ except Exception as e: # noqa: BLE001+ checks.append(_check(f'service.{name}', f'{name} service', 'warn',+ f'Status probe failed: {e}'))+ continue+ if active:+ checks.append(_check(f'service.{name}', f'{name} service', 'ok', 'Running.'))+ else:+ checks.append(_check(+ f'service.{name}', f'{name} service', 'fail', 'Not running.',+ repairable=True, repair_ref={'kind': 'service', 'name': name},+ ))+ return checks++ @classmethod+ def _cert_check(cls):+ """Nearest tracked certificate expiry (Domain.ssl_expires_at)."""+ try:+ from app.models.domain import Domain+ rows = (Domain.query+ .filter(Domain.ssl_expires_at.isnot(None))+ .order_by(Domain.ssl_expires_at.asc())+ .all())+ except Exception as e: # noqa: BLE001+ return _check('certs.expiry', 'Certificate expiry', 'warn',+ f'Could not read certificate data: {e}')+ if not rows:+ return _check('certs.expiry', 'Certificate expiry', 'ok',+ 'No certificates tracked.')+ now = datetime.utcnow()+ soon = [d for d in rows if d.ssl_expires_at <= now + timedelta(days=CERT_WARN_DAYS)]+ expired = [d for d in soon if d.ssl_expires_at <= now]+ if expired:+ names = ', '.join(d.name for d in expired[:5])+ return _check('certs.expiry', 'Certificate expiry', 'fail',+ f'Expired certificate(s): {names}')+ if soon:+ nearest = soon[0]+ days = max(0, (nearest.ssl_expires_at - now).days)+ return _check('certs.expiry', 'Certificate expiry', 'warn',+ f'{len(soon)} certificate(s) expire within {CERT_WARN_DAYS} days '+ f'(nearest: {nearest.name} in {days}d).')+ nearest = rows[0]+ return _check('certs.expiry', 'Certificate expiry', 'ok',+ f'Nearest expiry: {nearest.name} on '+ f'{nearest.ssl_expires_at.date().isoformat()}.')++ @classmethod+ def _disk_check(cls):+ try:+ import psutil+ usage = psutil.disk_usage('/')+ free_pct = 100.0 - usage.percent+ except Exception as e: # noqa: BLE001+ return _check('disk.headroom', 'Disk headroom', 'warn',+ f'Could not read disk usage: {e}')+ detail = f'{free_pct:.1f}% free on /.'+ if free_pct < DISK_FAIL_FREE_PCT:+ return _check('disk.headroom', 'Disk headroom', 'fail', detail)+ if free_pct < DISK_WARN_FREE_PCT:+ return _check('disk.headroom', 'Disk headroom', 'warn', detail)+ return _check('disk.headroom', 'Disk headroom', 'ok', detail)++ @classmethod+ def _db_check(cls):+ try:+ from sqlalchemy import text+ from app import db+ db.session.execute(text('SELECT 1'))+ return _check('db.reachable', 'Database', 'ok', 'Reachable.')+ except Exception as e: # noqa: BLE001+ return _check('db.reachable', 'Database', 'fail', f'Query failed: {e}')++ # ------------------------------------------------------------------ #+ # Sweep+ # ------------------------------------------------------------------ #++ @classmethod+ def run(cls):+ """Run the full sweep synchronously and store the report.++ Returns ``{'checks': [...], 'ran_at': iso}``.+ """+ checks = []+ checks += cls._drift_checks()+ checks += cls._service_checks()+ checks.append(cls._cert_check())+ checks.append(cls._disk_check())+ checks.append(cls._db_check())+ report = {+ 'checks': checks,+ 'ran_at': datetime.utcnow().isoformat() + 'Z',+ }+ cls.store_report(report)+ return report++ @classmethod+ def store_report(cls, report):+ try:+ from app.services.settings_service import SettingsService+ SettingsService.set(LAST_REPORT_KEY, json.dumps(report))+ except Exception as e: # noqa: BLE001 — storage is best-effort+ logger.warning('could not store doctor report: %s', e)++ @classmethod+ def get_last_report(cls):+ from app.services.settings_service import SettingsService+ raw = SettingsService.get(LAST_REPORT_KEY)+ if not raw:+ return None+ try:+ return json.loads(raw)+ except (TypeError, ValueError):+ return None++ # ------------------------------------------------------------------ #+ # Batch repair (explicit only)+ # ------------------------------------------------------------------ #++ @classmethod+ def repair(cls, items):+ """Repair an explicit list of items.++ ``items``: ``[{'kind': 'drift', 'type': ..., 'id': ...} |+ {'kind': 'service', 'name': ...}]``. Returns per-item results (same+ order), each carrying the input item plus ``success``/detail fields.+ """+ results = []+ for item in items or []:+ kind = (item or {}).get('kind')+ if kind == 'drift':+ from app.services.drift_service import DriftService+ res = DriftService.repair(item.get('type'), item.get('id'))+ results.append({'item': item, **res})+ elif kind == 'service':+ results.append({'item': item, **cls._restart_service(item.get('name'))})+ else:+ results.append({'item': item, 'success': False,+ 'error': f'Unknown repair kind: {kind}'})+ return results++ @classmethod+ def _restart_service(cls, name):+ if name not in CORE_SERVICES:+ return {'success': False, 'error': f'Service not repairable: {name}'}+ if not sys.platform.startswith('linux'):+ return {'success': False, 'error': 'unsupported on this host'}+ try:+ from app.utils.system import ServiceControl+ proc = ServiceControl.restart(name, timeout=60)+ if proc.returncode == 0:+ return {'success': True, 'restarted': name}+ return {'success': False, 'error': (proc.stderr or '').strip()+ or f'systemctl restart {name} failed'}+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': str(e)}++ # ------------------------------------------------------------------ #+ # Job plumbing+ # ------------------------------------------------------------------ #++ @classmethod+ def run_doctor_job(cls, job):+ """Job handler for ``doctor.run`` (background variant of run())."""+ report = cls.run()+ counts = {}+ for c in report['checks']:+ counts[c['status']] = counts.get(c['status'], 0) + 1+ return {'ran_at': report['ran_at'], 'counts': counts}++ @classmethod+ def register_jobs(cls):+ """Register the doctor handler with the job registry.+ Called once at app startup (see app/__init__.py)."""+ from app.jobs import registry+ registry.register(DOCTOR_JOB_KIND, cls.run_doctor_job, replace=True)diff --git a/backend/app/services/drift_service.py b/backend/app/services/drift_service.pynew file mode 100644index 00000000..b2c492c5--- /dev/null+++ b/backend/app/services/drift_service.py@@ -0,0 +1,449 @@+"""Configuration drift detection + explicit per-resource repair.++ServerKit's service layer is imperative: it writes nginx vhosts and compose+override files from DB state and assumes they stay put. This module closes the+loop *gradually*: it re-renders what each managed file **should** contain+(through the exact same renderers the panel uses when writing them), compares+against what is actually on disk, and reports the difference. Nothing here+auto-repairs — :meth:`DriftService.repair` runs only when explicitly invoked+(API / doctor batch), per single resource.++Check framework+---------------+``DRIFT_CHECKS`` maps a resource ``type`` to a small check dict:++ {+ 'type': 'nginx_vhost',+ 'title': 'Nginx vhosts',+ 'supported': fn() -> (bool, reason), # optional platform gate+ 'list_resources': fn() -> [(id, name)],+ 'render_expected': fn(resource_id) -> {path: content|None},+ 'read_actual': fn(paths) -> {path: content|None}, # optional; default+ # reads the files+ 'repair': fn(resource_id) -> {'success', 'wrote', 'reloaded', ...},+ }++``render_expected`` values: a string is the exact content the file must have;+``None`` means the file must NOT exist (e.g. a stale compose override that+should have been removed). An empty dict means nothing applies to this+resource → it reports ``in_sync``.++Platform policy (documented choice): the built-in checks cover Linux server+paths (``/etc/nginx/...``, app roots). On a non-Linux host each built-in check+reports a single ``status='error'`` entry with detail ``'unsupported on this+host'`` — we deliberately do NOT report ``in_sync`` there, because "we couldn't+look" is not "it matches". The gate lives per-check (``supported``) so tests+and future cross-platform checks run anywhere.++Systemd units: the panel *does* template gunicorn units+(``PythonService.create_gunicorn_service``), but their render inputs (worker+count, run-as user, and a point-in-time snapshot of the app's ``.env``) are+not persisted anywhere, so a faithful expected-render is impossible —+re-rendering with today's defaults would flag false drift. The ServerKit+panel/agent units themselves are installer-owned. No systemd drift check is+registered for now.+"""+import difflib+import json+import logging+import os+import sys+from datetime import datetime++logger = logging.getLogger(__name__)++DRIFT_JOB_KIND = 'drift.check'+DRIFT_SCHEDULE_NAME = 'drift-check'+LAST_REPORT_KEY = 'drift_last_report'+DIFF_MAX_LINES = 200++# type -> check dict (see module docstring for the shape).+DRIFT_CHECKS = {}+++def register_check(check):+ """Register (or replace) a drift check. Plugins may add their own."""+ DRIFT_CHECKS[check['type']] = check+ return check+++def _is_linux():+ return sys.platform.startswith('linux')+++def _linux_only():+ if _is_linux():+ return True, None+ return False, 'unsupported on this host'+++def _default_read_actual(paths):+ """Read each path from disk; ``None`` for a file that doesn't exist."""+ actual = {}+ for path in paths:+ try:+ if os.path.exists(path):+ with open(path, 'r', encoding='utf-8', errors='replace') as f:+ actual[path] = f.read()+ else:+ actual[path] = None+ except OSError as e:+ raise RuntimeError(f'cannot read {path}: {e}')+ return actual+++def _unified_diff(path, actual, expected):+ """Unified diff actual → expected for one file, as a list of lines."""+ a = (actual or '').splitlines()+ b = (expected or '').splitlines()+ return list(difflib.unified_diff(+ a, b,+ fromfile=f'{path} (actual)',+ tofile=f'{path} (expected)',+ lineterm='',+ ))+++class DriftService:+ """Detect + repair drift between DB-derived config and files on disk."""++ # ------------------------------------------------------------------ #+ # Detection+ # ------------------------------------------------------------------ #++ @classmethod+ def check_resource(cls, check, resource_id, name):+ """Run one check against one resource. Returns a report entry."""+ entry = {+ 'type': check['type'],+ 'id': resource_id,+ 'name': name,+ 'status': 'in_sync',+ 'diff': None,+ 'checked_at': datetime.utcnow().isoformat() + 'Z',+ }+ try:+ expected = check['render_expected'](resource_id) or {}+ if not expected:+ # Nothing applies to this resource (e.g. app publishes no+ # files) — by definition nothing can have drifted.+ return entry+ reader = check.get('read_actual') or _default_read_actual+ actual = reader(list(expected.keys()))++ diff_lines = []+ statuses = set()+ for path, want in expected.items():+ have = actual.get(path)+ if want is None:+ # File must not exist.+ if have is None:+ statuses.add('in_sync')+ else:+ statuses.add('drifted')+ diff_lines += _unified_diff(path, have, '')+ elif have is None:+ statuses.add('missing')+ diff_lines += _unified_diff(path, '', want)+ elif have == want:+ statuses.add('in_sync')+ else:+ statuses.add('drifted')+ diff_lines += _unified_diff(path, have, want)++ if 'drifted' in statuses:+ entry['status'] = 'drifted'+ elif 'missing' in statuses:+ entry['status'] = 'missing'+ if diff_lines:+ if len(diff_lines) > DIFF_MAX_LINES:+ kept = diff_lines[:DIFF_MAX_LINES]+ kept.append(+ f'... (diff truncated at {DIFF_MAX_LINES} lines)')+ diff_lines = kept+ entry['diff'] = '\n'.join(diff_lines)+ except Exception as e: # noqa: BLE001 — one bad resource must not kill the sweep+ entry['status'] = 'error'+ entry['detail'] = str(e)+ return entry++ @classmethod+ def check_all(cls):+ """Run every registered check against every resource.++ Returns a list of entries ``{type, id, name, status, diff,+ checked_at}`` with ``status`` in+ ``in_sync | drifted | missing | error``.+ """+ results = []+ for check in DRIFT_CHECKS.values():+ supported = check.get('supported')+ if supported:+ ok, reason = supported()+ if not ok:+ results.append({+ 'type': check['type'],+ 'id': None,+ 'name': check.get('title', check['type']),+ 'status': 'error',+ 'diff': None,+ 'detail': reason or 'unsupported on this host',+ 'checked_at': datetime.utcnow().isoformat() + 'Z',+ })+ continue+ try:+ resources = check['list_resources']()+ except Exception as e: # noqa: BLE001+ results.append({+ 'type': check['type'],+ 'id': None,+ 'name': check.get('title', check['type']),+ 'status': 'error',+ 'diff': None,+ 'detail': str(e),+ 'checked_at': datetime.utcnow().isoformat() + 'Z',+ })+ continue+ for resource_id, name in resources:+ results.append(cls.check_resource(check, resource_id, name))+ return results++ # ------------------------------------------------------------------ #+ # Last-report storage+ # ------------------------------------------------------------------ #++ @classmethod+ def build_report(cls):+ results = cls.check_all()+ return {+ 'results': results,+ 'drifted': sum(1 for r in results if r['status'] in ('drifted', 'missing')),+ 'errors': sum(1 for r in results if r['status'] == 'error'),+ 'generated_at': datetime.utcnow().isoformat() + 'Z',+ }++ @classmethod+ def store_report(cls, report):+ from app.services.settings_service import SettingsService+ SettingsService.set(LAST_REPORT_KEY, json.dumps(report))++ @classmethod+ def get_last_report(cls):+ from app.services.settings_service import SettingsService+ raw = SettingsService.get(LAST_REPORT_KEY)+ if not raw:+ return None+ try:+ return json.loads(raw)+ except (TypeError, ValueError):+ return None++ # ------------------------------------------------------------------ #+ # Repair (explicit, per-resource — never automatic)+ # ------------------------------------------------------------------ #++ @classmethod+ def repair(cls, check_type, resource_id):+ """Re-render + rewrite one resource through the panel's normal write+ path (incl. nginx reload / compose up where applicable).++ Returns ``{'success': bool, 'wrote': [paths], 'reloaded': bool}`` (plus+ ``'error'`` on failure). Strictly on-demand.+ """+ check = DRIFT_CHECKS.get(check_type)+ if not check:+ return {'success': False, 'error': f'Unknown drift check type: {check_type}',+ 'wrote': [], 'reloaded': False}+ supported = check.get('supported')+ if supported:+ ok, reason = supported()+ if not ok:+ return {'success': False, 'error': reason or 'unsupported on this host',+ 'wrote': [], 'reloaded': False}+ repair_fn = check.get('repair')+ if not repair_fn:+ return {'success': False, 'error': f'{check_type} is not repairable',+ 'wrote': [], 'reloaded': False}+ try:+ result = repair_fn(resource_id) or {}+ except Exception as e: # noqa: BLE001 — surface as a clean error+ return {'success': False, 'error': str(e), 'wrote': [], 'reloaded': False}+ result.setdefault('success', False)+ result.setdefault('wrote', [])+ result.setdefault('reloaded', False)+ return result++ # ------------------------------------------------------------------ #+ # Job plumbing+ # ------------------------------------------------------------------ #++ @classmethod+ def run_drift_check_job(cls, job):+ """Job handler for ``drift.check``: sweep, store, notify on drift."""+ report = cls.build_report()+ cls.store_report(report)+ if report['drifted'] > 0:+ cls._notify_drift(report)+ return {'drifted': report['drifted'], 'errors': report['errors'],+ 'checked': len(report['results'])}++ @classmethod+ def _notify_drift(cls, report):+ """Best-effort admin notification — never breaks the sweep."""+ try:+ from app.plugins_sdk import notify+ names = [r['name'] for r in report['results']+ if r['status'] in ('drifted', 'missing')]+ summary = ', '.join(names[:5]) + ('…' if len(names) > 5 else '')+ notify.send('drift.detected', to='admins', data={+ 'count': report['drifted'],+ 'resources': names,+ 'message': (+ f"{report['drifted']} managed configuration file(s) no longer match "+ f"what ServerKit expects: {summary}. Review them on "+ 'Monitoring → Doctor and repair the ones you did not change '+ 'on purpose.'),+ })+ except Exception as e: # noqa: BLE001+ logger.debug('drift notification failed: %s', e)++ @classmethod+ def register_jobs(cls):+ """Register the drift sweep handler with the job registry.+ Called once at app startup (see app/__init__.py)."""+ from app.jobs import registry+ registry.register(DRIFT_JOB_KIND, cls.run_drift_check_job, replace=True)+++# --------------------------------------------------------------------------- #+# Built-in checks+# --------------------------------------------------------------------------- #++def _nginx_list_resources():+ """Apps published via host nginx = apps that have Domain rows."""+ from app.models.application import Application+ from app.models.domain import Domain+ rows = (Application.query+ .join(Domain, Domain.application_id == Application.id)+ .distinct()+ .all())+ return [(app.id, app.name) for app in rows]+++def _nginx_render_expected(app_id):+ from app.models.application import Application+ from app.services.nginx_service import NginxService+ from app.services.site_domain_service import SiteDomainService++ app = Application.query.get(app_id)+ if app is None:+ return {}+ kwargs, warning = SiteDomainService.app_vhost_kwargs(app)+ if kwargs is None:+ if warning:+ # App has domains but can't be published via host nginx — there is+ # nothing the panel would have written, so nothing to compare.+ logger.debug('drift: nginx vhost n/a for %s: %s', app.name, warning)+ return {}+ rendered = NginxService.render_site_config(**kwargs)+ if not rendered.get('success'):+ raise RuntimeError(rendered.get('error') or 'vhost render failed')+ path = os.path.join(NginxService.SITES_AVAILABLE, app.name)+ return {path: rendered['config']}+++def _nginx_repair(app_id):+ from app.models.application import Application+ from app.services.nginx_service import NginxService+ from app.services.site_domain_service import SiteDomainService++ app = Application.query.get(app_id)+ if app is None:+ return {'success': False, 'error': f'Application {app_id} not found'}+ res = SiteDomainService.write_app_vhost(app)+ if res.get('warning') and not (res.get('nginx') or {}).get('success'):+ return {'success': False, 'error': res['warning']}+ reload_res = NginxService.reload()+ return {+ 'success': True,+ 'wrote': [os.path.join(NginxService.SITES_AVAILABLE, app.name)],+ 'reloaded': bool(reload_res.get('success')),+ 'warning': res.get('warning') or (None if reload_res.get('success')+ else reload_res.get('error')),+ }+++register_check({+ 'type': 'nginx_vhost',+ 'title': 'Nginx vhosts',+ 'supported': _linux_only,+ 'list_resources': _nginx_list_resources,+ 'render_expected': _nginx_render_expected,+ 'repair': _nginx_repair,+})+++def _compose_list_resources():+ """Managed apps that live in a project dir (candidate compose apps)."""+ from app.models.application import Application+ rows = Application.query.filter(Application.root_path.isnot(None)).all()+ out = []+ for app in rows:+ try:+ from app.services.compose_env_service import ComposeEnvService+ if app.root_path and os.path.isdir(app.root_path) and \+ ComposeEnvService.find_base_compose(app.root_path, app.compose_file):+ out.append((app.id, app.name))+ except Exception: # noqa: BLE001 — skip unreadable roots+ continue+ return out+++def _compose_render_expected(app_id):+ from app.models.application import Application+ from app.services.compose_env_service import ComposeEnvService++ app = Application.query.get(app_id)+ if app is None or not app.root_path:+ return {}+ spec = ComposeEnvService.render_override(app.root_path, app.compose_file)+ if not spec['applies']:+ return {}+ # content None → the override must not exist (stale file = drift).+ return {spec['path']: spec['content']}+++def _compose_repair(app_id):+ from app.models.application import Application+ from app.services.compose_env_service import ComposeEnvService+ from app.services.docker_service import DockerService++ app = Application.query.get(app_id)+ if app is None:+ return {'success': False, 'error': f'Application {app_id} not found'}+ written = ComposeEnvService.refresh_for_project(app.root_path, app.compose_file)+ # Apply the regenerated override the same way a deploy does.+ up = DockerService.compose_up(app.root_path, detach=True,+ compose_file=app.compose_file)+ return {+ 'success': True,+ 'wrote': [written] if written else [],+ 'reloaded': bool(up.get('success')),+ 'warning': None if up.get('success') else up.get('error'),+ }+++register_check({+ 'type': 'compose_override',+ 'title': 'Compose env overrides',+ 'supported': _linux_only,+ 'list_resources': _compose_list_resources,+ 'render_expected': _compose_render_expected,+ 'repair': _compose_repair,+})++# NOTE: no systemd unit check — see the module docstring. The panel-templated+# gunicorn units (PythonService.create_gunicorn_service) render from inputs+# that aren't persisted (workers/user/.env snapshot), so an expected render+# can't be reproduced faithfully; everything else under /etc/systemd/system is+# installer-owned.diff --git a/backend/app/services/nginx_service.py b/backend/app/services/nginx_service.pyindex f278bb2c..f8fb82f6 100644--- a/backend/app/services/nginx_service.py+++ b/backend/app/services/nginx_service.py@@ -305,6 +305,60 @@ location = /wordpress {{}}'''+ # ==================== MICRO-CACHE (task #21) ====================+ # Opt-in per-site micro-cache: a very short (10s) full-page cache in front+ # of proxied/PHP sites, with hard bypasses for anything personalized.+ #+ # Design tradeoff — ONE shared zone/path for every opted-in site: nginx+ # cache zones must be declared statically in the http context, so a zone+ # per site does not scale (and can't be added/removed without touching a+ # global file per site). Consequence: a manual purge is a full-zone wipe+ # that clears cached entries for ALL opted-in sites. That is acceptable+ # because the TTL is only 10 seconds — the purge button exists for the+ # "I need it gone *now*" case, not for cache hygiene. proxy_* and+ # fastcgi_* caches cannot share a keys_zone, hence two zones over one+ # base directory (both wiped together on purge).+ MICROCACHE_CONF_NAME = 'serverkit-microcache.conf'+ MICROCACHE_DIR = '/var/cache/nginx/serverkit-microcache'++ MICROCACHE_ZONE_SNIPPET = '''# ServerKit micro-cache zones (auto-generated; do not edit).+# One shared zone pair serves every site with micro-cache enabled — nginx+# requires cache zones to be declared statically in the http context, so+# per-site zones are not practical. Entries expire after 10s; a manual purge+# wipes the whole directory (all opted-in sites).+proxy_cache_path /var/cache/nginx/serverkit-microcache/proxy levels=1:2 keys_zone=serverkit_microcache:10m max_size=256m inactive=10m use_temp_path=off;+fastcgi_cache_path /var/cache/nginx/serverkit-microcache/fastcgi levels=1:2 keys_zone=serverkit_microcache_php:10m max_size=256m inactive=10m use_temp_path=off;+'''++ # Server-level bypass logic, shared by the proxy and fastcgi variants.+ # Cached responses are never stored/served for: non-GET/HEAD requests,+ # requests with a query string (safer default), session/auth/cart cookies,+ # or admin/login/cart paths.+ MICROCACHE_SKIP_BLOCK = ''' # ServerKit micro-cache bypass (never cache personalized responses)+ set $sk_skip_cache 0;+ if ($request_method !~ ^(GET|HEAD)$) { set $sk_skip_cache 1; }+ if ($query_string != "") { set $sk_skip_cache 1; }+ if ($http_cookie ~* "wordpress_logged_in_|wp-postpass|woocommerce_cart_hash|woocommerce_items_in_cart|comment_author|PHPSESSID|session|auth") { set $sk_skip_cache 1; }+ if ($request_uri ~* "^/(wp-admin|wp-login|admin|login|cart|checkout|my-account)") { set $sk_skip_cache 1; }+'''++ MICROCACHE_PROXY_BLOCK = ''' proxy_cache serverkit_microcache;+ proxy_cache_valid 200 301 10s;+ proxy_cache_use_stale updating error timeout;+ proxy_cache_lock on;+ proxy_no_cache $sk_skip_cache;+ add_header X-SK-Cache $upstream_cache_status;+'''++ MICROCACHE_FASTCGI_BLOCK = ''' fastcgi_cache serverkit_microcache_php;+ fastcgi_cache_valid 200 301 10s;+ fastcgi_cache_use_stale updating error timeout;+ fastcgi_cache_lock on;+ fastcgi_cache_bypass $sk_skip_cache;+ fastcgi_no_cache $sk_skip_cache;+ add_header X-SK-Cache $upstream_cache_status;+'''+PRIVATE_URL_MAIN_CONFIG = '''# ServerKit Private URL Routes# This file is auto-generated. Do not edit manually.# Generated at: {timestamp}@@ -436,15 +490,19 @@ location /p/ {{return config@classmethod- def create_site(cls, name: str, app_type: str, domains: List[str],- root_path: str, port: int = None, php_version: str = '8.2',- ssl_cert: str = None, ssl_key: str = None,- upstream: str = None) -> Dict:- """Create a new site configuration.-- When ``ssl_cert``/``ssl_key`` are given the generated vhost serves HTTPS- (443) from that cert with an HTTP->HTTPS redirect — used to point managed- subdomains at the base-domain wildcard cert.+ def render_site_config(cls, name: str, app_type: str, domains: List[str],+ root_path: str = None, port: int = None,+ php_version: str = '8.2',+ ssl_cert: str = None, ssl_key: str = None,+ upstream: str = None,+ micro_cache: bool = False) -> Dict:+ """Render the vhost config for a site to a string — no side effects.++ This is the exact template pipeline :meth:`create_site` writes to disk;+ it is exposed separately so callers (e.g. drift detection) can compute+ the expected on-disk content without touching the filesystem.+ Returns ``{'success': True, 'config': str}`` or+ ``{'success': False, 'error': msg}``."""if not domains:return {'success': False, 'error': 'At least one domain is required'}@@ -504,9 +562,136 @@ location /p/ {{else:return {'success': False, 'error': f'Unknown app type: {app_type}'}+ if micro_cache:+ # Inject before the SSL wrap so the redirect server block (which+ # also carries a server_name line) never receives cache directives.+ config = cls._with_micro_cache(config, app_type)+if ssl_cert and ssl_key:config = cls._with_ssl(config, domains_str, ssl_cert, ssl_key)+ return {'success': True, 'config': config}++ @classmethod+ def _with_micro_cache(cls, config: str, app_type: str) -> str:+ """Inject the shared-zone micro-cache directives into a rendered vhost.++ fastcgi_cache for PHP-FPM-served sites, proxy_cache for reverse-proxied+ ones; static sites are a no-op (files already come straight off disk).+ Scheme-agnostic — nothing here depends on HTTP vs HTTPS. The referenced+ zones are declared once in conf.d by :meth:`ensure_cache_zone`.+ """+ t = (app_type or '').lower()+ if t in ('php', 'wordpress'):+ anchor = ' include fastcgi_params;\n'+ if anchor not in config:+ return config+ config = config.replace(anchor, anchor + cls.MICROCACHE_FASTCGI_BLOCK, 1)+ elif t in ('flask', 'django', 'python', 'docker', 'remote'):+ # proxy_cache_bypass may only be declared once per location, so+ # fold $sk_skip_cache into the template's existing $http_upgrade+ # bypass instead of adding a duplicate directive.+ anchor = ' proxy_cache_bypass $http_upgrade;\n'+ if anchor not in config:+ return config+ config = config.replace(+ anchor,+ ' proxy_cache_bypass $sk_skip_cache $http_upgrade;\n'+ + cls.MICROCACHE_PROXY_BLOCK,+ 1,+ )+ else:+ return config++ # Server-level $sk_skip_cache logic, right after server_name.+ match = re.search(r'^( server_name [^;]+;\n)', config, re.MULTILINE)+ if match:+ config = config.replace(+ match.group(1), match.group(1) + '\n' + cls.MICROCACHE_SKIP_BLOCK, 1)+ return config++ @classmethod+ def ensure_cache_zone(cls) -> Dict:+ """Write the shared micro-cache zone declaration to conf.d (idempotent).++ The zone must live in the http context, so it is a conf.d snippet+ written once — not part of any per-site vhost. Also pre-creates the+ on-disk cache directories. Skips the write when the snippet on disk+ already matches.+ """+ conf_path = os.path.join(cls.NGINX_CONF_DIR, 'conf.d', cls.MICROCACHE_CONF_NAME)+ try:+ if os.path.isfile(conf_path):+ with open(conf_path, 'r') as f:+ if f.read() == cls.MICROCACHE_ZONE_SNIPPET:+ return {'success': True, 'changed': False, 'path': conf_path,+ 'message': 'Micro-cache zone already configured'}+ run_privileged(['mkdir', '-p',+ os.path.join(cls.MICROCACHE_DIR, 'proxy'),+ os.path.join(cls.MICROCACHE_DIR, 'fastcgi')])+ process = run_privileged(['tee', conf_path], input=cls.MICROCACHE_ZONE_SNIPPET)+ if process.returncode != 0:+ return {'success': False, 'error': process.stderr}+ return {'success': True, 'changed': True, 'path': conf_path,+ 'message': 'Micro-cache zone configured'}+ except Exception as e:+ return {'success': False, 'error': str(e)}++ @classmethod+ def purge_micro_cache(cls) -> Dict:+ """Wipe the shared micro-cache directory contents. Linux-only.++ Full-zone wipe by design (see the tradeoff note at the MICROCACHE_*+ constants): the zone is shared across all opted-in sites, and with a+ 10s TTL a per-site purge buys almost nothing. nginx recreates cache+ entries on demand — no reload needed.+ """+ if os.name == 'nt':+ return {'success': False,+ 'error': 'Micro-cache purge is only available on Linux hosts'}+ try:+ subdirs = [os.path.join(cls.MICROCACHE_DIR, d) for d in ('proxy', 'fastcgi')]+ process = run_privileged(['rm', '-rf'] + subdirs)+ if process.returncode != 0:+ return {'success': False, 'error': process.stderr}+ run_privileged(['mkdir', '-p'] + subdirs)+ return {'success': True, 'message': 'Micro-cache cleared',+ 'note': ('The micro-cache is one shared zone, so purging clears '+ 'cached entries for every site that uses it. Entries '+ 'expire within 10 seconds regardless.')}+ except Exception as e:+ return {'success': False, 'error': str(e)}++ @classmethod+ def create_site(cls, name: str, app_type: str, domains: List[str],+ root_path: str = None, port: int = None, php_version: str = '8.2',+ ssl_cert: str = None, ssl_key: str = None,+ upstream: str = None, micro_cache: bool = False) -> Dict:+ """Create a new site configuration.++ When ``ssl_cert``/``ssl_key`` are given the generated vhost serves HTTPS+ (443) from that cert with an HTTP->HTTPS redirect — used to point managed+ subdomains at the base-domain wildcard cert. ``micro_cache`` opts the+ site into the shared 10s micro-cache (the global zone snippet is+ ensured first, since the vhost references it).+ """+ rendered = cls.render_site_config(+ name, app_type, domains, root_path=root_path, port=port,+ php_version=php_version, ssl_cert=ssl_cert, ssl_key=ssl_key,+ upstream=upstream, micro_cache=micro_cache,+ )+ if not rendered.get('success'):+ return rendered+ config = rendered['config']++ # The vhost references the shared cache zone — declare it (once)+ # before the write so `nginx -t` on the next reload passes.+ if micro_cache:+ zone = cls.ensure_cache_zone()+ if not zone.get('success'):+ return {'success': False,+ 'error': f"micro-cache zone setup failed: {zone.get('error')}"}+# Write config fileconfig_path = os.path.join(cls.SITES_AVAILABLE, name)try:diff --git a/backend/app/services/site_domain_service.py b/backend/app/services/site_domain_service.pyindex 7ad5fa5e..bd55326b 100644--- a/backend/app/services/site_domain_service.py+++ b/backend/app/services/site_domain_service.py@@ -400,7 +400,12 @@ class SiteDomainService:says ``wordpress`` (whose stock template is php-fpm, not a proxy)."""t = (force_type or app.app_type or '').lower()- base = dict(name=app.name, domains=domains, ssl_cert=ssl_cert, ssl_key=ssl_key)+ # micro_cache rides in the shared kwargs so the write path+ # (write_app_vhost -> create_site) and the drift re-render+ # (app_vhost_kwargs -> render_site_config) always agree on it —+ # an enabled cache must never show up as config drift.+ base = dict(name=app.name, domains=domains, ssl_cert=ssl_cert, ssl_key=ssl_key,+ micro_cache=bool(getattr(app, 'micro_cache_enabled', False)))# Reverse-proxy to a local container/app port.if t in ('docker', 'wordpress'):if not app.port:@@ -423,23 +428,21 @@ class SiteDomainService:return None, f"app type '{t}' cannot be published via host nginx."@classmethod- def write_app_vhost(cls, app, force_type=None):- """(Re)write and enable the host-nginx vhost publishing ``app`` at every- one of its Domain rows (``server_name`` = all domains).-- Handles all host-nginx app types: docker/wordpress and- python/flask/django reverse-proxy to the app's port; php/static serve a- filesystem root. Serves a base's wildcard cert when every domain is a- subdomain of that *same* base and its HTTPS is enabled (custom domains- bring their own cert). Best-effort — never raises; returns ``{'nginx',- 'warning'}`` (``nginx`` is ``None`` when nothing was written).+ def app_vhost_kwargs(cls, app, force_type=None):+ """Resolve ``app``'s Domain rows + wildcard-cert choice into the exact+ ``NginxService.create_site(**kwargs)`` call :meth:`write_app_vhost`+ makes. Extracted so drift detection can render the *expected* vhost+ through the same pipeline without writing anything.++ Returns ``(kwargs, warning)`` — ``(None, None)`` when the app has no+ domains (nothing to publish), ``(None, reason)`` when it can't be+ published via host nginx."""from app.models.domain import Domain- from app.services.nginx_service import NginxServicedomains = [d.name for d in Domain.query.filter_by(application_id=app.id).all()]if not domains:- return {'nginx': None, 'warning': None}+ return None, None# Pick a wildcard cert only when all domains sit under one base (whichever# base covers them) and that base has HTTPS set up.@@ -448,9 +451,27 @@ class SiteDomainService:if cover and cls.https_enabled(cover) and all(cls.covering_base(d) == cover for d in domains):ssl_cert, ssl_key = cls.wildcard_cert_paths(cover)- kwargs, reason = cls._vhost_create_kwargs(app, domains, ssl_cert, ssl_key, force_type)+ return cls._vhost_create_kwargs(app, domains, ssl_cert, ssl_key, force_type)++ @classmethod+ def write_app_vhost(cls, app, force_type=None):+ """(Re)write and enable the host-nginx vhost publishing ``app`` at every+ one of its Domain rows (``server_name`` = all domains).++ Handles all host-nginx app types: docker/wordpress and+ python/flask/django reverse-proxy to the app's port; php/static serve a+ filesystem root. Serves a base's wildcard cert when every domain is a+ subdomain of that *same* base and its HTTPS is enabled (custom domains+ bring their own cert). Best-effort — never raises; returns ``{'nginx',+ 'warning'}`` (``nginx`` is ``None`` when nothing was written).+ """+ from app.services.nginx_service import NginxService++ kwargs, reason = cls.app_vhost_kwargs(app, force_type)if reason:return {'nginx': None, 'warning': reason}+ if kwargs is None:+ return {'nginx': None, 'warning': None}try:res = NginxService.create_site(**kwargs)diff --git a/backend/tests/test_drift_doctor.py b/backend/tests/test_drift_doctor.pynew file mode 100644index 00000000..a8aef5a5--- /dev/null+++ b/backend/tests/test_drift_doctor.py@@ -0,0 +1,536 @@+"""Tests for drift detection/repair (drift_service), the doctor sweep+(doctor_service), and the /api/v1/doctor contract."""+import json++import pytest++from app.services import drift_service+from app.services.drift_service import (+ DIFF_MAX_LINES,+ DRIFT_JOB_KIND,+ DriftService,+ LAST_REPORT_KEY as DRIFT_REPORT_KEY,+)+from app.services.doctor_service import (+ DOCTOR_JOB_KIND,+ DoctorService,+ LAST_REPORT_KEY as DOCTOR_REPORT_KEY,+)+++# --------------------------------------------------------------------------- #+# Fake drift check plumbing+# --------------------------------------------------------------------------- #++def make_fake_check(tmp_path, expected_by_id, repaired=None, check_type='fake'):+ """A registry-shaped check whose expected content is table-driven and whose+ 'actual' files live under tmp_path (the default reader reads real files)."""+ def render_expected(rid):+ spec = expected_by_id[rid]+ if isinstance(spec, Exception):+ raise spec+ return {str(tmp_path / path): content for path, content in spec.items()}++ def repair(rid):+ wrote = []+ for path, content in (expected_by_id[rid] or {}).items():+ full = tmp_path / path+ if content is None:+ if full.exists():+ full.unlink()+ else:+ full.write_text(content, encoding='utf-8')+ wrote.append(str(full))+ if repaired is not None:+ repaired.append(rid)+ return {'success': True, 'wrote': wrote, 'reloaded': True}++ return {+ 'type': check_type,+ 'title': 'Fake check',+ 'list_resources': lambda: [(rid, f'res-{rid}') for rid in expected_by_id],+ 'render_expected': render_expected,+ 'repair': repair,+ }+++def fake_registry(monkeypatch):+ """Swap the module registry for an empty one so builtin checks stay out."""+ registry = {}+ monkeypatch.setattr(drift_service, 'DRIFT_CHECKS', registry)+ return registry+++# --------------------------------------------------------------------------- #+# Detection+# --------------------------------------------------------------------------- #++def test_check_all_statuses(app, tmp_path, fake_registry):+ (tmp_path / 'insync.conf').write_text('same\n', encoding='utf-8')+ (tmp_path / 'drifted.conf').write_text('old\n', encoding='utf-8')+ (tmp_path / 'stale.conf').write_text('should not exist\n', encoding='utf-8')++ check = make_fake_check(tmp_path, {+ 'a': {'insync.conf': 'same\n'},+ 'b': {'drifted.conf': 'new\n'},+ 'c': {'missing.conf': 'want\n'},+ 'd': RuntimeError('boom'),+ 'e': {'stale.conf': None}, # file must NOT exist -> drift+ 'f': {}, # nothing applies -> in_sync+ })+ drift_service.register_check(check)++ results = {r['id']: r for r in DriftService.check_all()}++ assert results['a']['status'] == 'in_sync'+ assert results['a']['diff'] is None++ assert results['b']['status'] == 'drifted'+ assert '-old' in results['b']['diff']+ assert '+new' in results['b']['diff']++ assert results['c']['status'] == 'missing'+ assert '+want' in results['c']['diff']++ assert results['d']['status'] == 'error'+ assert 'boom' in results['d']['detail']++ assert results['e']['status'] == 'drifted'+ assert '-should not exist' in results['e']['diff']++ assert results['f']['status'] == 'in_sync'++ for r in results.values():+ assert r['type'] == 'fake'+ assert r['checked_at']+ assert r['name'].startswith('res-')+++def test_diff_is_capped(app, tmp_path, fake_registry):+ (tmp_path / 'big.conf').write_text(+ '\n'.join(f'old-{i}' for i in range(500)), encoding='utf-8')+ check = make_fake_check(tmp_path, {+ 'big': {'big.conf': '\n'.join(f'new-{i}' for i in range(500))},+ })+ drift_service.register_check(check)++ [result] = DriftService.check_all()++ lines = result['diff'].splitlines()+ assert len(lines) == DIFF_MAX_LINES + 1+ assert 'truncated' in lines[-1]+++def test_unsupported_check_reports_clean_error(app, fake_registry):+ drift_service.register_check({+ 'type': 'linuxish',+ 'title': 'Linux-only thing',+ 'supported': lambda: (False, 'unsupported on this host'),+ 'list_resources': lambda: [(1, 'x')],+ 'render_expected': lambda rid: {'/nope': 'x'},+ })++ [result] = DriftService.check_all()++ assert result['status'] == 'error'+ assert result['detail'] == 'unsupported on this host'+ assert result['id'] is None+ assert result['name'] == 'Linux-only thing'+++def test_builtin_checks_are_registered():+ # The real module registry (not the fake one) carries the two builtins.+ assert 'nginx_vhost' in drift_service.DRIFT_CHECKS+ assert 'compose_override' in drift_service.DRIFT_CHECKS+++# --------------------------------------------------------------------------- #+# Repair+# --------------------------------------------------------------------------- #++def test_repair_writes_and_reports(app, tmp_path, fake_registry):+ repaired = []+ check = make_fake_check(tmp_path, {'r1': {'site.conf': 'fixed\n'}},+ repaired=repaired)+ drift_service.register_check(check)++ result = DriftService.repair('fake', 'r1')++ assert result['success'] is True+ assert result['wrote'] == [str(tmp_path / 'site.conf')]+ assert result['reloaded'] is True+ assert repaired == ['r1']+ assert (tmp_path / 'site.conf').read_text(encoding='utf-8') == 'fixed\n'++ # Repaired resource now checks clean.+ [entry] = [r for r in DriftService.check_all() if r['id'] == 'r1']+ assert entry['status'] == 'in_sync'+++def test_repair_unknown_type_and_unrepairable(app, tmp_path, fake_registry):+ unknown = DriftService.repair('nope', 1)+ assert unknown['success'] is False+ assert 'Unknown drift check type' in unknown['error']++ check = make_fake_check(tmp_path, {'r1': {'x': 'y'}})+ del check['repair']+ drift_service.register_check(check)+ result = DriftService.repair('fake', 'r1')+ assert result['success'] is False+ assert 'not repairable' in result['error']+++def test_repair_unsupported_platform(app, fake_registry):+ drift_service.register_check({+ 'type': 'gated',+ 'title': 'Gated',+ 'supported': lambda: (False, 'unsupported on this host'),+ 'list_resources': lambda: [],+ 'render_expected': lambda rid: {},+ 'repair': lambda rid: {'success': True},+ })+ result = DriftService.repair('gated', 1)+ assert result['success'] is False+ assert result['error'] == 'unsupported on this host'+++# --------------------------------------------------------------------------- #+# Job handler + notification+# --------------------------------------------------------------------------- #++class _JobStub:+ def get_payload(self):+ return {}+++def test_drift_job_stores_report_and_notifies(app, tmp_path, fake_registry, monkeypatch):+ from app.services.settings_service import SettingsService+ import app.plugins_sdk as sdk++ (tmp_path / 'drifted.conf').write_text('old\n', encoding='utf-8')+ drift_service.register_check(make_fake_check(tmp_path, {+ 'b': {'drifted.conf': 'new\n'},+ }))++ sent = []+ monkeypatch.setattr(sdk.notify, 'send',+ lambda event, to, data=None, **kw: sent.append((event, to, data)))++ summary = DriftService.run_drift_check_job(_JobStub())++ assert summary == {'drifted': 1, 'errors': 0, 'checked': 1}+ stored = json.loads(SettingsService.get(DRIFT_REPORT_KEY))+ assert stored['drifted'] == 1+ assert stored['results'][0]['status'] == 'drifted'++ assert len(sent) == 1+ event, to, data = sent[0]+ assert event == 'drift.detected'+ assert to == 'admins'+ assert data['count'] == 1+ assert 'res-b' in data['resources']+++def test_drift_job_no_notification_when_clean(app, tmp_path, fake_registry, monkeypatch):+ import app.plugins_sdk as sdk++ (tmp_path / 'insync.conf').write_text('same\n', encoding='utf-8')+ drift_service.register_check(make_fake_check(tmp_path, {+ 'a': {'insync.conf': 'same\n'},+ }))++ sent = []+ monkeypatch.setattr(sdk.notify, 'send',+ lambda *a, **kw: sent.append(a))++ summary = DriftService.run_drift_check_job(_JobStub())++ assert summary['drifted'] == 0+ assert sent == []+++def test_drift_event_in_notification_catalog():+ from app.notifications import catalog+ entry = catalog.get('drift.detected')+ assert entry is not None+ assert entry['severity'] == 'warning'+ assert entry['category'] == 'system'+++def test_register_jobs_registers_handlers(app):+ from app.jobs import registry+ DriftService.register_jobs()+ DoctorService.register_jobs()+ assert registry.get(DRIFT_JOB_KIND) is not None+ assert registry.get(DOCTOR_JOB_KIND) is not None+++# --------------------------------------------------------------------------- #+# Doctor sweep+# --------------------------------------------------------------------------- #++def _fixed_drift_results():+ return [+ {'type': 'fake', 'id': 1, 'name': 'clean-app', 'status': 'in_sync',+ 'diff': None, 'checked_at': 'now'},+ {'type': 'fake', 'id': 2, 'name': 'bad-app', 'status': 'drifted',+ 'diff': '-a\n+b', 'checked_at': 'now'},+ {'type': 'fake', 'id': None, 'name': 'Gated', 'status': 'error',+ 'diff': None, 'detail': 'unsupported on this host', 'checked_at': 'now'},+ ]+++def test_doctor_run_report_shape(app, monkeypatch):+ from app.services.settings_service import SettingsService++ monkeypatch.setattr(DriftService, 'check_all',+ classmethod(lambda cls: _fixed_drift_results()))+ monkeypatch.setattr(DoctorService, '_service_checks', classmethod(lambda cls: [+ {'key': 'service.nginx', 'title': 'nginx service', 'status': 'fail',+ 'detail': 'Not running.', 'repairable': True,+ 'repair_ref': {'kind': 'service', 'name': 'nginx'}},+ ]))++ report = DoctorService.run()++ assert report['ran_at']+ checks = {c['key']: c for c in report['checks']}+ # Drift entries.+ assert checks['drift.fake.1']['status'] == 'ok'+ assert checks['drift.fake.2']['status'] == 'warn'+ assert checks['drift.fake.2']['repairable'] is True+ assert checks['drift.fake.2']['repair_ref'] == {'kind': 'drift', 'type': 'fake', 'id': 2}+ assert checks['drift.fake.2']['diff'] == '-a\n+b'+ assert checks['drift.fake']['status'] == 'warn'+ assert checks['drift.fake']['repairable'] is False+ # Host probes are all present.+ assert checks['service.nginx']['status'] == 'fail'+ for key in ('certs.expiry', 'disk.headroom', 'db.reachable'):+ assert key in checks+ assert checks[key]['status'] in ('ok', 'warn', 'fail')+ assert checks['db.reachable']['status'] == 'ok'+ # Every check carries the full shape.+ for c in report['checks']:+ for field in ('key', 'title', 'status', 'detail', 'repairable', 'repair_ref'):+ assert field in c++ stored = json.loads(SettingsService.get(DOCTOR_REPORT_KEY))+ assert stored['ran_at'] == report['ran_at']+++def test_doctor_cert_check_warns_on_near_expiry(app):+ from datetime import datetime, timedelta+ from werkzeug.security import generate_password_hash+ from app import db+ from app.models import User+ from app.models.application import Application+ from app.models.domain import Domain++ user = User(email='[email protected]', username='certuser',+ password_hash=generate_password_hash('x'),+ role=User.ROLE_ADMIN, is_active=True)+ db.session.add(user)+ db.session.flush()+ site = Application(name='certsite', app_type='static', user_id=user.id)+ db.session.add(site)+ db.session.flush()+ db.session.add(Domain(name='soon.example.com', application_id=site.id,+ ssl_expires_at=datetime.utcnow() + timedelta(days=5)))+ db.session.commit()++ check = DoctorService._cert_check()+ assert check['status'] == 'warn'+ assert 'soon.example.com' in check['detail']+++def test_doctor_batch_repair(app, monkeypatch):+ calls = []+ monkeypatch.setattr(+ DriftService, 'repair',+ classmethod(lambda cls, t, i: calls.append(('drift', t, i)) or+ {'success': True, 'wrote': ['/x'], 'reloaded': True}))+ monkeypatch.setattr(+ DoctorService, '_restart_service',+ classmethod(lambda cls, name: calls.append(('service', name)) or+ {'success': True, 'restarted': name}))++ results = DoctorService.repair([+ {'kind': 'drift', 'type': 'nginx_vhost', 'id': 7},+ {'kind': 'service', 'name': 'nginx'},+ {'kind': 'wat'},+ ])++ assert calls == [('drift', 'nginx_vhost', 7), ('service', 'nginx')]+ assert results[0]['success'] is True and results[0]['wrote'] == ['/x']+ assert results[1]['success'] is True and results[1]['restarted'] == 'nginx'+ assert results[2]['success'] is False+ assert 'Unknown repair kind' in results[2]['error']+++def test_restart_service_rejects_unknown_service(app):+ result = DoctorService._restart_service('sshd')+ assert result['success'] is False+ assert 'not repairable' in result['error']+++# --------------------------------------------------------------------------- #+# API contract+# --------------------------------------------------------------------------- #++def doctor_client(app):+ """Test client with the doctor blueprint mounted (registration in+ app/__init__.py is wired separately)."""+ from app.api.doctor import doctor_bp+ if 'doctor' not in app.blueprints:+ app.register_blueprint(doctor_bp, url_prefix='/api/v1/doctor')+ return app.test_client()+++def viewer_headers(app):+ """A non-admin (viewer) token, to prove admin-only enforcement."""+ from app import db+ from app.models import User+ from flask_jwt_extended import create_access_token+ from werkzeug.security import generate_password_hash++ user = User(+ email='[email protected]', username='vieweruser',+ password_hash=generate_password_hash('testpass'),+ role=User.ROLE_VIEWER, is_active=True,+ )+ db.session.add(user)+ db.session.commit()+ token = create_access_token(identity=user.id)+ return {'Authorization': f'Bearer {token}'}+++def test_api_requires_auth(doctor_client):+ assert doctor_client.get('/api/v1/doctor').status_code == 401+ assert doctor_client.get('/api/v1/doctor/drift').status_code == 401+ assert doctor_client.post('/api/v1/doctor/drift/check').status_code == 401+ assert doctor_client.post('/api/v1/doctor/run').status_code == 401+ assert doctor_client.post('/api/v1/doctor/repair').status_code == 401+++def test_api_requires_admin(doctor_client, viewer_headers):+ resp = doctor_client.get('/api/v1/doctor', headers=viewer_headers)+ assert resp.status_code == 403+ assert 'error' in resp.get_json()+ resp = doctor_client.post('/api/v1/doctor/run', headers=viewer_headers)+ assert resp.status_code == 403+++def test_get_drift_report_null_then_value(doctor_client, auth_headers, app):+ from app.services.settings_service import SettingsService++ resp = doctor_client.get('/api/v1/doctor/drift', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json() == {'report': None}++ report = {'results': [], 'drifted': 0, 'errors': 0, 'generated_at': 'x'}+ SettingsService.set(DRIFT_REPORT_KEY, json.dumps(report))+ resp = doctor_client.get('/api/v1/doctor/drift', headers=auth_headers)+ assert resp.get_json() == {'report': report}+++def test_post_drift_check_enqueues(doctor_client, auth_headers, monkeypatch):+ from app.jobs.service import JobService++ class _FakeJob:+ id = 'job-drift-1'++ enqueued = []++ def _fake_enqueue(kind, payload=None, max_attempts=3, **kwargs):+ enqueued.append((kind, payload, max_attempts))+ return _FakeJob()++ monkeypatch.setattr(JobService, 'enqueue', staticmethod(_fake_enqueue))++ resp = doctor_client.post('/api/v1/doctor/drift/check', headers=auth_headers)++ assert resp.status_code == 202+ assert resp.get_json() == {'job_id': 'job-drift-1'}+ assert enqueued == [(DRIFT_JOB_KIND, {}, 1)]+++def test_drift_repair_requires_confirm(doctor_client, auth_headers):+ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/1/repair',+ headers=auth_headers, json={})+ assert resp.status_code == 400+ assert 'error' in resp.get_json()++ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/1/repair',+ headers=auth_headers, json={'confirm': 'yes'})+ assert resp.status_code == 400+++def test_drift_repair_with_confirm(doctor_client, auth_headers, monkeypatch):+ calls = []+ monkeypatch.setattr(+ DriftService, 'repair',+ classmethod(lambda cls, t, i: calls.append((t, i)) or+ {'success': True, 'wrote': ['/etc/nginx/sites-available/blog'],+ 'reloaded': True}))++ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/7/repair',+ headers=auth_headers, json={'confirm': True})++ assert resp.status_code == 200+ body = resp.get_json()+ assert body['success'] is True+ assert body['wrote'] == ['/etc/nginx/sites-available/blog']+ assert body['reloaded'] is True+ assert calls == [('nginx_vhost', 7)] # numeric ids are cast to int+++def test_get_doctor_report_null_then_value(doctor_client, auth_headers, app):+ from app.services.settings_service import SettingsService++ resp = doctor_client.get('/api/v1/doctor', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json() == {'report': None}++ report = {'checks': [], 'ran_at': 'x'}+ SettingsService.set(DOCTOR_REPORT_KEY, json.dumps(report))+ resp = doctor_client.get('/api/v1/doctor', headers=auth_headers)+ assert resp.get_json() == {'report': report}+++def test_post_run_is_synchronous(doctor_client, auth_headers, monkeypatch):+ fixed = {'checks': [{'key': 'db.reachable', 'title': 'Database',+ 'status': 'ok', 'detail': 'Reachable.',+ 'repairable': False, 'repair_ref': None}],+ 'ran_at': '2026-07-03T00:00:00Z'}+ monkeypatch.setattr(DoctorService, 'run', classmethod(lambda cls: fixed))++ resp = doctor_client.post('/api/v1/doctor/run', headers=auth_headers)++ assert resp.status_code == 200+ assert resp.get_json() == {'report': fixed}+++def test_post_repair_batch(doctor_client, auth_headers, monkeypatch):+ monkeypatch.setattr(+ DoctorService, 'repair',+ classmethod(lambda cls, items: [{'item': i, 'success': True} for i in items]))++ items = [{'kind': 'drift', 'type': 'fake', 'id': 1},+ {'kind': 'service', 'name': 'nginx'}]+ resp = doctor_client.post('/api/v1/doctor/repair',+ headers=auth_headers, json={'items': items})++ assert resp.status_code == 200+ assert resp.get_json() == {'results': [{'item': items[0], 'success': True},+ {'item': items[1], 'success': True}]}+++def test_post_repair_requires_items(doctor_client, auth_headers):+ resp = doctor_client.post('/api/v1/doctor/repair', headers=auth_headers, json={})+ assert resp.status_code == 400+ resp = doctor_client.post('/api/v1/doctor/repair', headers=auth_headers,+ json={'items': []})+ assert resp.status_code == 400diff --git a/frontend/src/components/monitoring/DoctorPanel.jsx b/frontend/src/components/monitoring/DoctorPanel.jsxnew file mode 100644index 00000000..18673de4--- /dev/null+++ b/frontend/src/components/monitoring/DoctorPanel.jsx@@ -0,0 +1,199 @@+import { useEffect, useState } from 'react';+import api from '../../services/api';+import { useToast } from '../../contexts/ToastContext';+import { Button } from '@/components/ui/button';+import {+ Dialog,+ DialogContent,+ DialogDescription,+ DialogTitle,+} from '@/components/ui/dialog';+import { Pill } from '@/components/ds';+import EmptyState from '../EmptyState';+import { ChevronDown, ChevronRight, Stethoscope, Wrench } from 'lucide-react';++const STATUS_TONE = { ok: 'green', warn: 'amber', fail: 'red' };++function formatRanAt(ranAt) {+ if (!ranAt) return null;+ return new Date(ranAt).toLocaleString();+}++const DoctorPanel = () => {+ const toast = useToast();+ const [report, setReport] = useState(null);+ const [loading, setLoading] = useState(true);+ const [running, setRunning] = useState(false);+ const [repairing, setRepairing] = useState(false);+ const [expanded, setExpanded] = useState({});+ // { items: [repair_ref...], title, diff } — pending confirmation.+ const [confirm, setConfirm] = useState(null);++ useEffect(() => {+ let cancelled = false;+ api.getDoctorReport()+ .then((res) => { if (!cancelled) setReport(res.report); })+ .catch(() => { /* no stored report yet — the empty state covers it */ })+ .finally(() => { if (!cancelled) setLoading(false); });+ return () => { cancelled = true; };+ }, []);++ const runDiagnosis = async () => {+ try {+ setRunning(true);+ const res = await api.runDoctor();+ setReport(res.report);+ const bad = (res.report?.checks || []).filter((c) => c.status !== 'ok').length;+ toast[bad > 0 ? 'warning' : 'success'](+ bad > 0 ? `Diagnosis finished — ${bad} finding${bad !== 1 ? 's' : ''}` : 'Diagnosis finished — all clear'+ );+ } catch (err) {+ toast.error(err.message || 'Diagnosis failed');+ } finally {+ setRunning(false);+ }+ };++ const doRepair = async (items) => {+ try {+ setRepairing(true);+ const res = await api.repairDoctorItems(items);+ const failed = (res.results || []).filter((r) => !r.success);+ if (failed.length > 0) {+ toast.error(`${failed.length} repair${failed.length !== 1 ? 's' : ''} failed — ${failed[0].error || 'see report'}`);+ } else {+ toast.success(`Repaired ${items.length} item${items.length !== 1 ? 's' : ''}`);+ }+ // Re-diagnose so the list reflects the new on-disk state.+ const fresh = await api.runDoctor();+ setReport(fresh.report);+ } catch (err) {+ toast.error(err.message || 'Repair failed');+ } finally {+ setRepairing(false);+ setConfirm(null);+ }+ };++ const checks = report?.checks || [];+ const repairable = checks.filter((c) => c.repairable && c.repair_ref);++ const toggleDiff = (key) => {+ setExpanded((cur) => ({ ...cur, [key]: !cur[key] }));+ };++ return (+ <div className="doctor-panel">+ <section className="monitoring-panel">+ <div className="monitoring-panel__header">+ <h3>Server Doctor</h3>+ <div className="doctor-panel__actions">+ {repairable.length > 0 && (+ <Button+ size="sm"+ variant="outline"+ disabled={repairing || running}+ onClick={() => setConfirm({+ items: repairable.map((c) => c.repair_ref),+ title: `Repair all ${repairable.length} repairable items?`,+ diff: null,+ })}+ >+ <Wrench size={14} />+ Repair all ({repairable.length})+ </Button>+ )}+ <Button size="sm" onClick={runDiagnosis} disabled={running || repairing}>+ <Stethoscope size={14} />+ {running ? 'Diagnosing...' : 'Run diagnosis'}+ </Button>+ </div>+ </div>++ <p className="doctor-panel__blurb">+ One sweep across managed configuration drift, core services, certificates,+ disk headroom and the database. Nothing is repaired automatically — every+ fix is a button you press.+ {report?.ran_at && <span className="doctor-panel__ranat"> Last run {formatRanAt(report.ran_at)}.</span>}+ </p>++ {loading ? (+ <EmptyState loading title="Loading last report" />+ ) : checks.length === 0 ? (+ <EmptyState+ icon={Stethoscope}+ title="No diagnosis yet"+ description="Run a diagnosis to check this server's managed configuration and core health."+ />+ ) : (+ <div className="doctor-check-list">+ {checks.map((check) => (+ <article key={check.key} className={`doctor-check doctor-check--${check.status}`}>+ <div className="doctor-check__row">+ <Pill kind={STATUS_TONE[check.status] || 'gray'}>{check.status}</Pill>+ <div className="doctor-check__body">+ <span className="doctor-check__title">{check.title}</span>+ <span className="doctor-check__detail">{check.detail}</span>+ </div>+ {check.diff && (+ <Button+ size="sm"+ variant="ghost"+ className="doctor-check__difftoggle"+ onClick={() => toggleDiff(check.key)}+ >+ {expanded[check.key] ? <ChevronDown size={14} /> : <ChevronRight size={14} />}+ diff+ </Button>+ )}+ {check.repairable && check.repair_ref && (+ <Button+ size="sm"+ variant="outline"+ disabled={repairing || running}+ onClick={() => setConfirm({+ items: [check.repair_ref],+ title: `Repair "${check.title}"?`,+ diff: check.diff || null,+ })}+ >+ <Wrench size={13} />+ Repair+ </Button>+ )}+ </div>+ {check.diff && expanded[check.key] && (+ <pre className="doctor-diff">{check.diff}</pre>+ )}+ </article>+ ))}+ </div>+ )}+ </section>++ <Dialog open={Boolean(confirm)} onOpenChange={(open) => { if (!open) setConfirm(null); }}>+ <DialogContent className="doctor-confirm">+ <DialogTitle>{confirm?.title}</DialogTitle>+ <DialogDescription>+ This rewrites the managed file(s) from ServerKit's configuration and+ reloads the affected service. Manual edits to those files will be lost.+ </DialogDescription>+ {confirm?.diff && (+ <pre className="doctor-diff doctor-diff--modal">{confirm.diff}</pre>+ )}+ <div className="doctor-confirm__actions">+ <Button variant="outline" onClick={() => setConfirm(null)} disabled={repairing}>+ Cancel+ </Button>+ <Button onClick={() => doRepair(confirm.items)} disabled={repairing}>+ <Wrench size={14} />+ {repairing ? 'Repairing...' : 'Repair'}+ </Button>+ </div>+ </DialogContent>+ </Dialog>+ </div>+ );+};++export default DoctorPanel;diff --git a/frontend/src/pages/Monitoring.jsx b/frontend/src/pages/Monitoring.jsxindex 4322131c..c92a4b38 100644--- a/frontend/src/pages/Monitoring.jsx+++ b/frontend/src/pages/Monitoring.jsx@@ -5,6 +5,7 @@ import api from '../services/api';import { formatBytes } from '@/utils/formatBytes';import { useToast } from '../contexts/ToastContext';import EmptyState from '../components/EmptyState';+import DoctorPanel from '../components/monitoring/DoctorPanel';import { Button } from '@/components/ui/button';import { Input } from '@/components/ui/input';import { Label } from '@/components/ui/label';@@ -32,7 +33,7 @@ import {Zap,} from 'lucide-react';-const VALID_TABS = ['overview', 'alerts', 'config', 'thresholds'];+const VALID_TABS = ['overview', 'alerts', 'config', 'thresholds', 'doctor'];const DEFAULT_THRESHOLDS = {cpu_percent: 80,@@ -389,6 +390,7 @@ const Monitoring = () => {<TabsTrigger value="thresholds">Alert Rules</TabsTrigger><TabsTrigger value="config">Delivery</TabsTrigger><TabsTrigger value="alerts">History</TabsTrigger>+ <TabsTrigger value="doctor">Doctor</TabsTrigger></TabsList><TabsContent value="overview">@@ -702,6 +704,10 @@ const Monitoring = () => {)}</section></TabsContent>++ <TabsContent value="doctor">+ <DoctorPanel />+ </TabsContent></Tabs></div>);diff --git a/frontend/src/services/api/doctor.js b/frontend/src/services/api/doctor.jsnew file mode 100644index 00000000..7c691ea3--- /dev/null+++ b/frontend/src/services/api/doctor.js@@ -0,0 +1,32 @@+// Doctor / drift API — health sweep + configuration drift surface+// (Monitoring → Doctor tab). Admin-only endpoints under /api/v1/doctor.++export async function getDoctorReport() {+ return this.request('/doctor');+}++export async function runDoctor() {+ return this.request('/doctor/run', { method: 'POST' });+}++export async function repairDoctorItems(items) {+ return this.request('/doctor/repair', {+ method: 'POST',+ body: JSON.stringify({ items }),+ });+}++export async function getDriftReport() {+ return this.request('/doctor/drift');+}++export async function runDriftCheck() {+ return this.request('/doctor/drift/check', { method: 'POST' });+}++export async function repairDrift(type, id) {+ return this.request(`/doctor/drift/${type}/${id}/repair`, {+ method: 'POST',+ body: JSON.stringify({ confirm: true }),+ });+}diff --git a/frontend/src/styles/pages/_doctor.scss b/frontend/src/styles/pages/_doctor.scssnew file mode 100644index 00000000..90242b71--- /dev/null+++ b/frontend/src/styles/pages/_doctor.scss@@ -0,0 +1,110 @@+// ============================================+// DOCTOR TAB (Monitoring → Doctor)+// One-shot health sweep: check list + drift diffs + explicit repairs.+// NOTE: imported from main.scss (wired by the orchestrator).+// ============================================++.doctor-panel {+ display: grid;+ gap: $space-5;++ &__actions {+ display: flex;+ align-items: center;+ gap: $space-2;+ }++ &__blurb {+ margin: 0 0 $space-4;+ font-size: 12.5px;+ line-height: 1.5;+ color: var(--text-dim);+ max-width: 68ch;+ }++ &__ranat {+ color: var(--text-faint);+ }+}++.doctor-check-list {+ display: grid;+ gap: $space-2;+}++.doctor-check {+ border: 1px solid var(--border-soft);+ border-radius: var(--radius);+ background: var(--surface);+ padding: $space-3 $space-4;++ &--warn {+ border-color: rgba(245, 179, 66, 0.3);+ }++ &--fail {+ border-color: rgba(240, 82, 82, 0.35);+ }++ &__row {+ display: flex;+ align-items: center;+ gap: $space-3;+ }++ &__body {+ display: flex;+ flex-direction: column;+ gap: 2px;+ min-width: 0;+ flex: 1;+ }++ &__title {+ font-size: 13px;+ font-weight: $font-weight-semibold;+ color: var(--text);+ }++ &__detail {+ font-size: 12px;+ color: var(--text-dim);+ overflow-wrap: anywhere;+ }++ // Rendered as a ghost Button — just tighten it to a mono affordance.+ &__difftoggle {+ font-family: var(--mono);+ font-size: 11px;+ color: var(--text-dim);+ }+}++// Unified diff viewer — monospace pre, collapsed by default (toggle-rendered).+.doctor-diff {+ margin: $space-3 0 0;+ padding: $space-3;+ border: 1px solid var(--border-soft);+ border-radius: var(--radius);+ background: var(--surface-2);+ font-family: var(--mono);+ font-size: 11.5px;+ line-height: 1.5;+ color: var(--text-dim);+ max-height: 320px;+ overflow: auto;+ white-space: pre;++ &--modal {+ max-height: 220px;+ }+}++.doctor-confirm {+ &__actions {+ display: flex;+ justify-content: flex-end;+ gap: $space-2;+ margin-top: $space-4;+ }+}