feat(webui): system-health dashboard (Closes #639)
Phase 1 child of the Web Console epic #631. Adds the operator-facing system-health dashboard on top of the read-only system-health API landed by #634, so runtime problems are visible on a surface instead of being discovered late through failed LLM sessions. - webui/system_health_views.py (new): renders the SystemHealthSnapshot as readiness, stale-runtime parity, version/uptime, dependency, MCP namespace, probe-error, and recovery cards. - webui/app.py: GET /system-health, sharing load_system_health() with the JSON API so page and API cannot disagree. ?deep=1 behaves as on the API. - webui/layout.py: nav entry and health card/badge styles. - tests/test_webui_system_health_dashboard.py (new, 26 cases). - docs/webui-local-dev.md: route, field authority, and redaction split. Readiness honesty is preserved from the API: ready and readiness_complete render separately, a probe that did not run is listed under "Not probed" rather than counted healthy, and mutation safety is never claimed when the runtime is stale or parity is indeterminate. Redaction is split by field kind. Free text (probe details, reasons, probe errors) passes through system_health.redact. Structured fields (commit SHAs, probe names, statuses, timestamps) are HTML-escaped only: redact's opaque-token rule matches any run of 32 or more characters, so routing a 40-character git SHA through it rendered "[redacted]" and blanked the parity evidence the page exists to show. Non-goals honored: no restart or reload controls (Phase 2, #642), no manual process-kill guidance (#630). Read-only throughout. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,307 @@
|
||||
"""HTML views for the system-health dashboard (#639).
|
||||
|
||||
Renders the read-only :class:`~webui.system_health.SystemHealthSnapshot`
|
||||
produced by the Phase 1 system-health API (#634). The page offers no restart,
|
||||
reload, or process-kill control: those are Phase 2 work, and manual process
|
||||
kills are the contamination path #630 exists to prevent.
|
||||
|
||||
Every free-text field passes through :func:`webui.system_health.redact` before
|
||||
it reaches HTML, so a probe detail that captured a token or a credentialed URL
|
||||
cannot leak through the dashboard even though the API redacts it already.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import html
|
||||
|
||||
from webui.system_health import (
|
||||
STATUS_DEGRADED,
|
||||
STATUS_DOWN,
|
||||
STATUS_OK,
|
||||
STATUS_SKIPPED,
|
||||
STATUS_UNPROVEN,
|
||||
DependencyProbe,
|
||||
SystemHealthSnapshot,
|
||||
redact,
|
||||
)
|
||||
|
||||
_STATUS_BADGE_CLASS = {
|
||||
STATUS_OK: "badge-health-ok",
|
||||
STATUS_DEGRADED: "badge-health-degraded",
|
||||
STATUS_DOWN: "badge-health-down",
|
||||
STATUS_SKIPPED: "badge-health-skipped",
|
||||
STATUS_UNPROVEN: "badge-health-unproven",
|
||||
}
|
||||
|
||||
|
||||
def _safe(value: object) -> str:
|
||||
"""Escape free text for HTML after redacting anything secret-shaped.
|
||||
|
||||
Use this for every value that can carry arbitrary text — probe details,
|
||||
reasons, probe errors — because those are where a credential could ride
|
||||
along.
|
||||
"""
|
||||
return html.escape(redact(str(value)))
|
||||
|
||||
|
||||
def _esc(value: object) -> str:
|
||||
"""Escape a structured field for HTML without redacting it.
|
||||
|
||||
Commit SHAs, probe names, statuses, and timestamps are enumerated or
|
||||
machine-generated, never credential-bearing. They must not go through
|
||||
:func:`redact`: its opaque-token rule matches any 32-plus-character run,
|
||||
so a 40-character git SHA would render as ``[redacted]`` and the parity
|
||||
view — the one thing an operator reads this page for — would be blank.
|
||||
"""
|
||||
return html.escape(str(value))
|
||||
|
||||
|
||||
def _status_badge(status: str) -> str:
|
||||
css = _STATUS_BADGE_CLASS.get(status, "badge-health-unproven")
|
||||
return f'<span class="badge {css}">{_esc(status)}</span>'
|
||||
|
||||
|
||||
def _reason_list(reasons: tuple[str, ...], *, empty: str) -> str:
|
||||
if not reasons:
|
||||
return f"<p class='muted'>{html.escape(empty)}</p>"
|
||||
items = "".join(f"<li>{_safe(reason)}</li>" for reason in reasons)
|
||||
return f"<ul class='reasons'>{items}</ul>"
|
||||
|
||||
|
||||
def _readiness_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
"""Overall readiness.
|
||||
|
||||
``ready`` and ``readiness_complete`` are shown separately on purpose: a
|
||||
snapshot whose required probes never ran is not the same as one that ran
|
||||
them and passed, and collapsing the two would render an unproven green.
|
||||
"""
|
||||
if snapshot.ready and snapshot.readiness_complete:
|
||||
headline = "Ready"
|
||||
elif snapshot.ready:
|
||||
headline = "Ready (incomplete evidence)"
|
||||
else:
|
||||
headline = "Not ready"
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
f"<h3>Readiness {_status_badge(snapshot.status)}</h3>"
|
||||
f"<p class='health-headline'>{html.escape(headline)}</p>"
|
||||
"<table class='detail'>"
|
||||
f"<tr><th>Service</th><td><code>{_esc(snapshot.service)}</code></td></tr>"
|
||||
f"<tr><th>Mode</th><td>{_esc(snapshot.mode)}</td></tr>"
|
||||
f"<tr><th>Ready</th><td>{_esc(snapshot.ready)}</td></tr>"
|
||||
"<tr><th>Readiness evidence complete</th>"
|
||||
f"<td>{_esc(snapshot.readiness_complete)}</td></tr>"
|
||||
"<tr><th>Deep probes requested</th>"
|
||||
f"<td>{_esc(snapshot.deep_probes_requested)}</td></tr>"
|
||||
f"<tr><th>Observed at</th><td><code>{_esc(snapshot.timestamp)}</code></td></tr>"
|
||||
"</table>"
|
||||
"<h4>Readiness reasons</h4>"
|
||||
f"{_reason_list(snapshot.readiness_reasons, empty='No readiness objections recorded.')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _version_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
version = snapshot.version
|
||||
uptime_hours = snapshot.uptime_seconds / 3600.0
|
||||
known = (
|
||||
"resolved"
|
||||
if version.known
|
||||
else "unresolved — version fields could not be read from the checkout"
|
||||
)
|
||||
schema = version.control_plane_schema_version
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Version and uptime</h3>"
|
||||
"<table class='detail'>"
|
||||
f"<tr><th>Git SHA</th><td><code>{_esc(version.git_sha or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Git describe</th>"
|
||||
f"<td><code>{_esc(version.git_describe or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Control-plane schema</th>"
|
||||
f"<td>{_esc(schema if schema is not None else 'unknown')}</td></tr>"
|
||||
f"<tr><th>Python</th><td><code>{_esc(version.python_version)}</code></td></tr>"
|
||||
f"<tr><th>Version status</th><td>{html.escape(known)}</td></tr>"
|
||||
f"<tr><th>Started at</th><td><code>{_esc(snapshot.started_at)}</code></td></tr>"
|
||||
"<tr><th>Uptime</th>"
|
||||
f"<td>{snapshot.uptime_seconds:.3f}s ({uptime_hours:.2f}h)</td></tr>"
|
||||
"</table>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _dependency_rows(probes: tuple[DependencyProbe, ...]) -> str:
|
||||
if not probes:
|
||||
return "<p class='muted'>No dependency probes were reported.</p>"
|
||||
rows = []
|
||||
for probe in probes:
|
||||
latency = (
|
||||
f"{probe.latency_ms:.1f} ms" if probe.latency_ms is not None else "n/a"
|
||||
)
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><code>{_esc(probe.name)}</code></td>"
|
||||
f"<td>{_esc(probe.kind)}</td>"
|
||||
f"<td>{_status_badge(probe.status)}</td>"
|
||||
f"<td>{_esc('required' if probe.required else 'optional')}</td>"
|
||||
f"<td>{html.escape(latency)}</td>"
|
||||
f"<td>{_safe(probe.detail)}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
return (
|
||||
"<table class='registry'><thead><tr>"
|
||||
"<th>Dependency</th><th>Kind</th><th>Status</th><th>Requirement</th>"
|
||||
"<th>Latency</th><th>Detail</th>"
|
||||
"</tr></thead><tbody>"
|
||||
f"{''.join(rows)}</tbody></table>"
|
||||
)
|
||||
|
||||
|
||||
def _dependency_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
degraded = [probe for probe in snapshot.dependencies if probe.ran and not probe.healthy]
|
||||
not_run = [probe for probe in snapshot.dependencies if not probe.ran]
|
||||
|
||||
banner = ""
|
||||
if degraded:
|
||||
names = ", ".join(sorted(probe.name for probe in degraded))
|
||||
banner += (
|
||||
"<div class='stub health-degraded'><p><strong>Degraded dependencies:</strong> "
|
||||
f"{_esc(names)}</p></div>"
|
||||
)
|
||||
if not_run:
|
||||
names = ", ".join(sorted(probe.name for probe in not_run))
|
||||
banner += (
|
||||
"<div class='stub'><p><strong>Not probed:</strong> "
|
||||
f"{_esc(names)} — these contribute no evidence and are not counted "
|
||||
"as healthy.</p></div>"
|
||||
)
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Dependencies</h3>"
|
||||
f"{banner}"
|
||||
f"{_dependency_rows(snapshot.dependencies)}"
|
||||
"<p class='muted'>Details are redacted at the API boundary and again "
|
||||
"before rendering; credentials are never displayed.</p>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _namespace_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
if not snapshot.mcp_namespaces:
|
||||
body = "<p class='muted'>No MCP namespaces are declared.</p>"
|
||||
else:
|
||||
rows = []
|
||||
for entry in snapshot.mcp_namespaces:
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><code>{_esc(entry.get('namespace'))}</code></td>"
|
||||
f"<td><code>{_esc(entry.get('required_tool'))}</code></td>"
|
||||
f"<td>{_status_badge(str(entry.get('status') or STATUS_UNPROVEN))}</td>"
|
||||
f"<td>{_esc(entry.get('ide_namespace_proven'))}</td>"
|
||||
f"<td>{_safe(entry.get('reason'))}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
body = (
|
||||
"<table class='registry'><thead><tr>"
|
||||
"<th>Namespace</th><th>Required tool</th><th>Status</th>"
|
||||
"<th>IDE-proven</th><th>Reason</th>"
|
||||
"</tr></thead><tbody>"
|
||||
f"{''.join(rows)}</tbody></table>"
|
||||
)
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>MCP namespaces</h3>"
|
||||
f"{body}"
|
||||
"<p class='muted'>The web process runs outside the IDE-managed MCP "
|
||||
"client, so namespace health is reported as unproven rather than "
|
||||
"guessed (#543).</p>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _stale_runtime_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
stale = snapshot.stale_runtime
|
||||
if stale.stale:
|
||||
warning = (
|
||||
"<div class='stub health-stale'><p><strong>Stale runtime:</strong> "
|
||||
"the running code, the checkout, and the remote-tracking commit "
|
||||
"disagree. Capability gates may be evaluating obsolete code — "
|
||||
"do not treat this runtime as mutation-safe.</p></div>"
|
||||
)
|
||||
elif not stale.determinable:
|
||||
warning = (
|
||||
"<div class='stub health-stale'><p><strong>Staleness "
|
||||
"indeterminate:</strong> parity could not be proven, so this "
|
||||
"runtime is not reported as mutation-safe.</p></div>"
|
||||
)
|
||||
else:
|
||||
warning = ""
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Stale-runtime parity</h3>"
|
||||
f"{warning}"
|
||||
"<table class='detail'>"
|
||||
"<tr><th>Daemon head</th>"
|
||||
f"<td><code>{_esc(stale.daemon_head or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Checkout head</th>"
|
||||
f"<td><code>{_esc(stale.checkout_head or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Remote head</th>"
|
||||
f"<td><code>{_esc(stale.remote_head or 'unknown')}</code></td></tr>"
|
||||
f"<tr><th>Stale</th><td>{_esc(stale.stale)}</td></tr>"
|
||||
f"<tr><th>Determinable</th><td>{_esc(stale.determinable)}</td></tr>"
|
||||
f"<tr><th>Mutation safe</th><td>{_esc(stale.mutation_safe)}</td></tr>"
|
||||
"</table>"
|
||||
f"{_reason_list(stale.reasons, empty='Runtime, checkout, and remote agree.')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _probe_error_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
if not snapshot.probe_errors:
|
||||
return ""
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Probe errors</h3>"
|
||||
f"{_reason_list(snapshot.probe_errors, empty='')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _recovery_card() -> str:
|
||||
"""Sanctioned recovery pointers only — never a manual process kill (#630)."""
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Recovery</h3>"
|
||||
"<p class='muted'>This dashboard is read-only. Restart and reload "
|
||||
"controls arrive in Phase 2 (#642); until then recovery runs through "
|
||||
"the sanctioned client reconnect / operator restart path.</p>"
|
||||
"<ul class='reasons'>"
|
||||
"<li><a href='/runtime'>Runtime and session view</a> — active profile, "
|
||||
"workflow hashes, and shell health.</li>"
|
||||
"<li>Reconnect the MCP client from the IDE, then re-run the blocked "
|
||||
"cycle. Never kill the daemon process manually: unmanaged kills are "
|
||||
"recorded as runtime contamination (#630).</li>"
|
||||
"<li>See <code>docs/webui-local-dev.md</code> for the documented "
|
||||
"recovery sequence.</li>"
|
||||
"</ul>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def render_system_health_page(snapshot: SystemHealthSnapshot) -> str:
|
||||
"""Render the full system-health dashboard body."""
|
||||
return (
|
||||
"<h2>System health</h2>"
|
||||
"<p class='meta'>Read-only view of the Phase 1 system-health API "
|
||||
"(<code>/api/v1/system/health</code>). Reload this page to refresh; "
|
||||
"nothing here polls or mutates on your behalf.</p>"
|
||||
f"{_readiness_card(snapshot)}"
|
||||
f"{_stale_runtime_card(snapshot)}"
|
||||
f"{_version_card(snapshot)}"
|
||||
f"{_dependency_card(snapshot)}"
|
||||
f"{_namespace_card(snapshot)}"
|
||||
f"{_probe_error_card(snapshot)}"
|
||||
f"{_recovery_card()}"
|
||||
)
|
||||
Reference in New Issue
Block a user