feat(#91): metrics gear — source-aware, no-HAProxy mode (phases 0-2)

[sarg3nt]

Summary

Lay the foundation for a source-agnostic Metrics gear by introducing the MetricSource concept end-to-end. The page now declares which collector produces each number ("HAProxy: Sessions & Requests", "Host: CPU Load", …) and gracefully degrades on boxes without HAProxy.

This PR lands phases 0-2 of #91. Each phase is independently valuable; together they ship the foundation every later phase (nginx, Apache, Caddy, Docker) builds on.

Phase 0 — Capability manifest plumbing (dashboard side)

• New agent.CapabilitiesCache (5-min TTL, 3s fetch timeout, negative caching) memoises per-box probe tables so gear-page handlers don't fire a fresh agent call on every render.
• Handler-level getBoxCapabilities() + BoxCapabilities accessor with Has / IsAvailable / Entry helpers.
• Reconnect-driven invalidation: handler subscribes to EventTypeServerConnected and drops the cache for that box so a restarted agent's new probe table is reflected immediately rather than at the next TTL boundary.
• New GET /api/{boxID}/capabilities endpoint surfaces the cached manifest to the auth-scoped frontend.
• filterGearsByAgentCapabilities (issue Box gear configuration improvements #71) refactored onto the cache — removes one synchronous agent call per Gears-page render.

Note: the agent's /api/v1/system/capabilities endpoint already shipped under #71. This PR adds the dashboard-side caching + accessor + endpoint the Phase 0 spec calls for.

Phase 1 — Source attribution in the UI

• Chart card titles carry source-prefix badges ("HAProxy: …" or "Host: …") so the reader can tell which collector produced the metric at a glance.
• KPI cards render a small source badge in the upper-right corner; server emits source + source_label on every card.
• "Error Insights" → "HAProxy Error Insights" with explicit copy.

Phase 2 — Graceful no-HAProxy mode

• /api/{boxID}/metrics/summary checks the haproxy capability and only emits HAProxy KPI cards when the gear is available; host KPIs (Memory %, Disk %, Load 1m) are always emitted from system_metrics_history.
• Frontend applyCapabilities() hides [data-source="haproxy"] chart cards + Error Insights when haproxy isn't available; shows an empty-state banner pointing to install / enable.
• Fail-open everywhere — capability fetches that error don't strip the page; the dashboard reverts to "HAProxy assumed present" rather than locking the user out of cards they may need.

What's intentionally not in this PR

• CPU%, uptime, failed-systemd KPIs — the collector doesn't persist these in system_metrics_history today. They'll follow when the collector starts saving them.
• Service detection (nginx, Apache, Caddy, Traefik) — Phase 3 of the issue. Agent-side work; intentionally separate so this PR stays focused.
• Per-source charts (nginx metrics, Caddy metrics, etc.) — Phases 4+ of the issue.
• Cross-source aggregates — Phase 8.

Test plan

• make test — 9 packages pass on gearbox; no regressions on gearbox-agent.
• New unit tests:
  • CapabilitiesCache — TTL caching, refresh past TTL, Invalidate, InvalidateAll, negative caching, nil-safety on BoxCapabilities accessors.
  • avgPositiveSysField + sysSparkline — host-KPI counterparts of the existing stat helpers.
• go vet ./... clean across both modules.
• Manual smoke: /history on light-hugger (HAProxy box) shows HAProxy + Host KPIs and chart titles read "HAProxy: …" / "Host: …".
• Manual smoke: /history on a box without HAProxy (mjolnir?) shows the no-HAProxy banner, hides HAProxy cards and Error Insights, and renders just the Host KPI cards + Host chart cards.
• Manual smoke: reconnecting an agent updates capabilities within seconds (not 5 min).

References

• Closes the Phase 0-2 portion of Metrics gear: source-agnostic dashboard (host + nginx/Apache/Caddy/Docker) #91 (issue tracks the full roadmap through Phase 8).
• Follow-up PR: agent-side discovery (nginx/Apache/Caddy/Traefik) — Phase 3.
• Architecture / phasing doc: docs/research/metrics-source-agnostic.md.

[Copilot]

Pull request overview

This PR adds dashboard-side capability awareness for the Metrics gear so /history can attribute metrics to sources and degrade when HAProxy is unavailable.

Changes:

• Adds cached per-box agent capabilities and exposes them via /api/{boxID}/capabilities.
• Updates Metrics UI with source badges, HAProxy-specific hiding, and no-HAProxy messaging.
• Adds host KPI cards and helper/cache unit tests.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.gitignore	Ignores local config file.
gearbox/cmd/server/main.go	Registers the capabilities API route.
gearbox/internal/framework/agent/capabilities_cache.go	Adds per-box capabilities cache/accessors.
gearbox/internal/framework/agent/capabilities_cache_test.go	Tests capabilities cache behavior.
gearbox/internal/framework/handler/api_capabilities.go	Adds dashboard capabilities API handler.
gearbox/internal/framework/handler/api_metrics_insights.go	Adds source fields, HAProxy gating, and host KPI cards.
gearbox/internal/framework/handler/api_metrics_insights_helpers.go	Adds system-metrics KPI helper functions.
gearbox/internal/framework/handler/api_metrics_insights_test.go	Tests new system-metrics helpers.
gearbox/internal/framework/handler/gears.go	Reuses capabilities cache for gear filtering.
gearbox/internal/framework/handler/handler.go	Wires capabilities cache and reconnect invalidation.
gearbox/internal/framework/templates/pages/history.templ	Adds source UI badges and HAProxy capability-based hiding.

Comments suppressed due to low confidence (4)

gearbox/internal/framework/handler/api_metrics_insights.go:367

• Using avgPositiveSysField for load average drops legitimate zero readings from idle hosts, so a window with samples like 0, 0, 1.0 is reported as 1.0 instead of ~0.33. system_metrics_history stores load_average_1 directly from the agent, where zero is a valid value, unlike the HAProxy response-time buckets this helper mirrors.

	currLoad := avgPositiveSysField(curr, func(s database.SystemMetricsSnapshot) float64 { return s.LoadAverage1 })
	prevLoad := avgPositiveSysField(prev, func(s database.SystemMetricsSnapshot) float64 { return s.LoadAverage1 })

gearbox/internal/framework/handler/api_metrics_insights.go:291

• The function comment says hostKPICards returns a network KPI, but the implementation only builds memory, disk, and load cards. This stale documentation makes it look like a network card is missing from the code when it appears to be intentionally omitted from this phase.

// hostKPICards returns the host-level KPI cards (memory, disk, load,
// network). Computed from the dashboard's system_metrics_history table.

gearbox/internal/framework/templates/pages/history.templ:893

• Capability gating uses the same hidden class that toggleFullscreen() uses for temporary fullscreen state. On a no-HAProxy box, entering and then exiting fullscreen on a host chart will run the existing fullscreen exit path that removes hidden from every other .chart-card, making the HAProxy cards visible again despite the capability result. Use a separate capability-hidden state or reapply capability filtering when leaving fullscreen.

			document.querySelectorAll('[data-source="haproxy"]').forEach(function(el) {
				el.classList.toggle('hidden', !haproxyAvailable);

gearbox/internal/framework/templates/pages/history.templ:214

• This copy says the Error Insights data is reported by HAProxy logs, but the panel is populated from /metrics/error-breakdown, which aggregates the traffic_flows table built from HAProxy traffic/stats data rather than log parsing. That can mislead users about the data source and how to troubleshoot missing rows.

						<h3 class="text-xl font-semibold text-gray-800 dark:text-gray-100">HAProxy Error Insights</h3>
						<p class="text-sm text-gray-500 dark:text-gray-400 mt-0.5">
							Where the 4xx/5xx responses in this window are coming from, as reported by HAProxy logs. Click any row to drill in.