# Host Overview Info Section — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an always-visible info section to each host card on `/plugins`, showing owner, managers, agent version/type, last packet timestamp, and effective thresholds; move hbc_version/hbc_type out of the os_info accordion.

**Architecture:** A new `_build_host_info` module-level helper in `http.py` assembles the info dict from the host object and threshold_checker. A new `GET /api/0/hosts/{hostname}/info` closure inside `serve()` calls it and returns JSON. The `plugins.html` template adds a static placeholder div per host; JS fetches the endpoint on first card expand, caches the result, and renders it.

**Tech Stack:** Python/aiohttp (backend), Jinja2 (template), vanilla JS/HTML/CSS (frontend). Tests with pytest and unittest.mock.

---

### Task 1: `_build_host_info` helper — tests first

**Files:**
- Create: `tests/test_http_host_info.py`
- Modify: `hbd/server/http.py` (add module-level helper after `_mask_config_for_api`, around line 128)

- [ ] **Step 1: Write the failing tests**

Create `tests/test_http_host_info.py`:

```python
"""Tests for _build_host_info helper in http.py."""
import pytest
from unittest.mock import MagicMock
from hbd.server.http import _build_host_info


class _FakeConn:
    def __init__(self, lastbeat):
        self.lastbeat = lastbeat


class _FakeHost:
    def __init__(self, name="myhost", owner=None, managers=None,
                 connections=None, os_data=None):
        self.name = name
        self.owner = owner
        self.managers = managers or []
        self.connections = connections or {}
        self._os_data = os_data

    def get_latest_plugin_data(self, plugin_name):
        if plugin_name == "os_info" and self._os_data is not None:
            return (1234567890.0, self._os_data)
        return None


def test_build_host_info_basic_fields():
    host = _FakeHost(owner="alice", managers=["bob", "carol"])
    result = _build_host_info(host)
    assert result["owner"] == "alice"
    assert result["managers"] == ["bob", "carol"]
    assert result["hbc_version"] is None
    assert result["hbc_type"] is None
    assert result["last_packet"] is None
    assert result["thresholds"] is None


def test_build_host_info_no_owner():
    host = _FakeHost()
    result = _build_host_info(host)
    assert result["owner"] is None
    assert result["managers"] == []


def test_build_host_info_reads_hbc_from_os_info():
    host = _FakeHost(os_data={"hbc_version": "5.3.0", "hbc_type": "full"})
    result = _build_host_info(host)
    assert result["hbc_version"] == "5.3.0"
    assert result["hbc_type"] == "full"


def test_build_host_info_hbc_none_when_no_os_info():
    host = _FakeHost(os_data=None)
    result = _build_host_info(host)
    assert result["hbc_version"] is None
    assert result["hbc_type"] is None


def test_build_host_info_last_packet_is_max_lastbeat():
    host = _FakeHost(connections={
        "IPv4": _FakeConn(1000.0),
        "IPv6": _FakeConn(2000.0),
    })
    result = _build_host_info(host)
    assert result["last_packet"] == 2000.0


def test_build_host_info_last_packet_none_when_no_connections():
    host = _FakeHost(connections={})
    result = _build_host_info(host)
    assert result["last_packet"] is None


def test_build_host_info_thresholds_none_without_checker():
    host = _FakeHost()
    result = _build_host_info(host, threshold_checker=None)
    assert result["thresholds"] is None


def test_build_host_info_thresholds_sorted_by_metric():
    from hbd.server.threshold import ThresholdConfig
    tc_cpu = ThresholdConfig("cpu_monitor.cpu_percent", warning=80.0, critical=95.0)
    tc_mem = ThresholdConfig("memory_monitor.memory_percent", warning=85.0, critical=98.0)

    checker = MagicMock()
    checker.get_thresholds_for_host.return_value = {
        "memory_monitor.memory_percent": tc_mem,
        "cpu_monitor.cpu_percent": tc_cpu,
    }

    host = _FakeHost()
    result = _build_host_info(host, threshold_checker=checker)

    assert result["thresholds"] is not None
    assert len(result["thresholds"]) == 2
    assert result["thresholds"][0]["metric"] == "cpu_monitor.cpu_percent"
    assert result["thresholds"][0]["warning"] == 80.0
    assert result["thresholds"][0]["critical"] == 95.0
    assert result["thresholds"][0]["operator"] == ">"
    assert result["thresholds"][1]["metric"] == "memory_monitor.memory_percent"


def test_build_host_info_thresholds_empty_list_when_no_thresholds():
    checker = MagicMock()
    checker.get_thresholds_for_host.return_value = {}
    host = _FakeHost()
    result = _build_host_info(host, threshold_checker=checker)
    assert result["thresholds"] == []


def test_build_host_info_threshold_null_warning_critical():
    from hbd.server.threshold import ThresholdConfig
    tc = ThresholdConfig("rtt.myhost", warning=None, critical=500.0)
    checker = MagicMock()
    checker.get_thresholds_for_host.return_value = {"rtt.myhost": tc}
    host = _FakeHost()
    result = _build_host_info(host, threshold_checker=checker)
    assert result["thresholds"][0]["warning"] is None
    assert result["thresholds"][0]["critical"] == 500.0
```

- [ ] **Step 2: Run tests to confirm they fail**

```bash
pytest tests/test_http_host_info.py -v
```

Expected: `ImportError` or `AttributeError` — `_build_host_info` does not exist yet.

- [ ] **Step 3: Implement `_build_host_info` in `hbd/server/http.py`**

Insert after `_mask_config_for_api` (around line 128, before `def serve(`):

```python
def _build_host_info(host, threshold_checker=None):
    """Assemble the info payload for GET /api/0/hosts/{hostname}/info."""
    hbc_version = None
    hbc_type = None
    latest_os = host.get_latest_plugin_data("os_info")
    if latest_os:
        _, os_data = latest_os
        hbc_version = os_data.get("hbc_version")
        hbc_type = os_data.get("hbc_type")

    last_packet = None
    if host.connections:
        last_packet = max(conn.lastbeat for conn in host.connections.values())

    thresholds = None
    if threshold_checker is not None:
        raw = threshold_checker.get_thresholds_for_host(host.name)
        thresholds = sorted(
            [
                {
                    "metric": tc.metric_path,
                    "warning": tc.warning,
                    "critical": tc.critical,
                    "operator": tc.operator.value,
                }
                for tc in raw.values()
            ],
            key=lambda x: x["metric"],
        )

    return {
        "owner": getattr(host, "owner", None),
        "managers": list(getattr(host, "managers", [])),
        "hbc_version": hbc_version,
        "hbc_type": hbc_type,
        "last_packet": last_packet,
        "thresholds": thresholds,
    }
```

- [ ] **Step 4: Run tests to confirm they pass**

```bash
pytest tests/test_http_host_info.py -v
```

Expected: all 11 tests PASS.

- [ ] **Step 5: Commit**

```bash
git add tests/test_http_host_info.py hbd/server/http.py
git commit -m "feat: add _build_host_info helper for host info endpoint"
```

---

### Task 2: `api_host_info` route handler

**Files:**
- Modify: `hbd/server/http.py`
  - Add `api_host_info` closure inside `serve()` (after `api_host_access_put`, around line 829)
  - Register route (around line 1271)

- [ ] **Step 1: Add `api_host_info` closure inside `serve()`**

Insert after `api_host_access_put` (after line 829, before the comment `# User profile page`):

```python
    # -------------------------------------------------------------------------
    # Host info endpoint
    # -------------------------------------------------------------------------

    async def api_host_info(request):
        """GET /api/0/hosts/{hostname}/info"""
        user, err = _require_auth(request)
        if err:
            return err
        hostname = request.match_info.get("hostname")
        if hostname not in hbdclass.Host.hosts:
            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
        host = hbdclass.Host.hosts[hostname]
        if not _can_view_host(user, host):
            return web.json_response({"error": "Forbidden"}, status=403)
        return web.json_response(_build_host_info(host, threshold_checker=threshold_checker))
```

- [ ] **Step 2: Register the route**

In the route list (around line 1271, after the existing `/api/0/hosts/{hostname}/access` routes):

```python
            web.get("/api/0/hosts/{hostname}/info", api_host_info),
```

- [ ] **Step 3: Verify the full test suite still passes**

```bash
pytest tests/ -q
```

Expected: all tests PASS (no regressions).

- [ ] **Step 4: Smoke-test the endpoint manually** (if a dev server is running)

```bash
curl -s http://localhost:50004/api/0/hosts/<hostname>/info | python3 -m json.tool
```

Expected: JSON with `owner`, `managers`, `hbc_version`, `hbc_type`, `last_packet`, `thresholds` keys.

- [ ] **Step 5: Commit**

```bash
git add hbd/server/http.py
git commit -m "feat: add GET /api/0/hosts/{hostname}/info endpoint"
```

---

### Task 3: Info section HTML and CSS in `plugins.html`

**Files:**
- Modify: `hbd/server/templates/plugins.html`

- [ ] **Step 1: Add CSS for the info section**

In the `<style>` block (find the closing `</style>` tag around line 391 and insert before it):

```css
    /* ── Host info section ──────────────────────────────────────────────────── */
    .host-info-section {
      padding: 12px 16px;
      background: #fafafa;
      border-bottom: 1px solid #e0e0e0;
      font-size: 0.85em;
    }
    .info-meta {
      display: grid;
      grid-template-columns: max-content 1fr;
      gap: 3px 14px;
      margin-bottom: 10px;
    }
    .info-label { font-weight: 600; color: #555; white-space: nowrap; }
    .info-value { color: #222; }
    .info-thresholds-title {
      font-weight: 600;
      color: #555;
      margin-bottom: 6px;
    }
    .info-note { color: #888; font-style: italic; }
    .info-loading { color: #bbb; font-style: italic; }
```

- [ ] **Step 2: Add info section placeholder to each host card**

Inside the host loop, at the very start of `.host-body` (before the `{% set plugin_order %}` line, around line 438):

```html
          <div class="host-body">
            <div class="host-info-section" id="info-{{ host.name }}">
              <div class="info-loading">Loading…</div>
            </div>
```

The existing `{% set plugin_order %}` line and everything after stays unchanged. Only add the two new lines between `<div class="host-body">` and `{% set plugin_order %}`.

- [ ] **Step 3: Verify the page still renders without JS errors**

Start the dev server and open `/plugins` in a browser. Expand any host card — you should see the "Loading…" italic line above the plugin accordions (it will not be replaced yet, that comes in Task 4).

- [ ] **Step 4: Commit**

```bash
git add hbd/server/templates/plugins.html
git commit -m "feat: add host info section placeholder and CSS to plugins.html"
```

---

### Task 4: JS — `infoCache`, `fetchHostInfo`, `renderInfoSection`

**Files:**
- Modify: `hbd/server/templates/plugins.html` (JS `<script>` block)

- [ ] **Step 1: Add `infoCache` constant**

After the `pluginCache` declaration (after `const pluginCache = {};`, around line 489), add:

```javascript
      // infoCache[hostname] = info data object from /api/0/hosts/{hostname}/info
      const infoCache = {};
```

- [ ] **Step 2: Add `fetchHostInfo` function**

After the existing `fetchPlugin` function (around line 522, before `fetchHostGlance`), add:

```javascript
      async function fetchHostInfo(hostname) {
        const r = await fetch(`/api/0/hosts/${encodeURIComponent(hostname)}/info`);
        if (!r.ok) throw new Error(`HTTP ${r.status}`);
        return r.json();
      }
```

- [ ] **Step 3: Add `renderInfoSection` function**

After `fetchHostInfo` (before `fetchHostGlance`), add:

```javascript
      function renderInfoSection(hostname, data) {
        const el = document.getElementById(`info-${hostname}`);
        if (!el) return;

        const owner    = data.owner ? escHtml(data.owner) : '—';
        const managers = data.managers && data.managers.length
          ? data.managers.map(escHtml).join(', ') : '—';
        const hbcVer  = data.hbc_version ? escHtml(String(data.hbc_version)) : '—';
        const hbcType = data.hbc_type    ? escHtml(String(data.hbc_type))    : '—';
        const lastPkt = data.last_packet
          ? new Date(data.last_packet * 1000).toLocaleString() : '—';

        let html = `<div class="info-meta">
          <span class="info-label">Owner</span><span class="info-value">${owner}</span>
          <span class="info-label">Managers</span><span class="info-value">${managers}</span>
          <span class="info-label">Agent Version</span><span class="info-value">${hbcVer}</span>
          <span class="info-label">Agent Type</span><span class="info-value">${hbcType}</span>
          <span class="info-label">Last Packet</span><span class="info-value">${lastPkt}</span>
        </div>`;

        if (data.thresholds === null) {
          html += `<div class="info-note">Threshold alerting not configured.</div>`;
        } else if (data.thresholds.length === 0) {
          html += `<div class="info-note">No thresholds defined.</div>`;
        } else {
          html += `<div class="info-thresholds-title">Effective Thresholds</div>
            <table class="data-table"><thead><tr>
              <th>Metric</th><th>Op</th><th>Warning</th><th>Critical</th>
            </tr></thead><tbody>`;
          for (const t of data.thresholds) {
            const w = t.warning  !== null && t.warning  !== undefined ? t.warning  : '—';
            const c = t.critical !== null && t.critical !== undefined ? t.critical : '—';
            html += `<tr>
              <td class="key">${escHtml(t.metric)}</td>
              <td>${escHtml(t.operator)}</td>
              <td>${w}</td>
              <td>${c}</td>
            </tr>`;
          }
          html += `</tbody></table>`;
        }

        el.innerHTML = html;
      }
```

- [ ] **Step 4: Commit**

```bash
git add hbd/server/templates/plugins.html
git commit -m "feat: add fetchHostInfo and renderInfoSection JS functions"
```

---

### Task 5: Wire `fetchHostInfo` into `toggleHost`

**Files:**
- Modify: `hbd/server/templates/plugins.html` (the `toggleHost` function, around line 643)

- [ ] **Step 1: Replace `toggleHost` with the updated version**

Find the existing `toggleHost` function:

```javascript
      function toggleHost(hostname) {
        const card = document.querySelector(`.host-card[data-hostname="${hostname}"]`);
        const wasCollapsed = card.classList.contains('collapsed');
        card.classList.toggle('collapsed');
        if (wasCollapsed && !pluginCache[hostname]) {
          fetchHostGlance(hostname);
        }
      }
```

Replace with:

```javascript
      function toggleHost(hostname) {
        const card = document.querySelector(`.host-card[data-hostname="${hostname}"]`);
        const wasCollapsed = card.classList.contains('collapsed');
        card.classList.toggle('collapsed');
        if (wasCollapsed) {
          if (!pluginCache[hostname]) {
            fetchHostGlance(hostname);
          }
          if (!infoCache[hostname]) {
            const infoEl = document.getElementById(`info-${hostname}`);
            if (infoEl) infoEl.innerHTML = '<div class="info-loading">Loading…</div>';
            fetchHostInfo(hostname).then(data => {
              infoCache[hostname] = data;
              renderInfoSection(hostname, data);
            }).catch(() => {
              const el = document.getElementById(`info-${hostname}`);
              if (el) el.innerHTML = '<div class="info-loading">Could not load host info.</div>';
            });
          }
        }
      }
```

- [ ] **Step 2: Test in browser**

Open `/plugins`, expand a host card. Verify:
- The info section appears above the plugin accordions.
- Owner, managers (or "—"), agent version, agent type, last packet render correctly.
- Threshold table renders (or the appropriate "not configured" / "none defined" message).
- Collapsing and re-expanding does not re-fetch (no second network request).

- [ ] **Step 3: Commit**

```bash
git add hbd/server/templates/plugins.html
git commit -m "feat: fetch and render host info section on card expand"
```

---

### Task 6: Remove `hbc_version` and `hbc_type` from `renderOsInfoTable`

**Files:**
- Modify: `hbd/server/templates/plugins.html` (the `renderOsInfoTable` function, around line 794)

- [ ] **Step 1: Update `renderOsInfoTable`**

Find the existing function:

```javascript
      function renderOsInfoTable(d) {
        const ORDER = ['distro_pretty_name','system','release','version','machine',
                       'processor','architecture','node','python_version',
                       'python_implementation','hbc_version',
                       'distro_name','distro_version','distro_id','distro_version_id'];
        const shown = new Set(ORDER);
        const keys = [...ORDER, ...Object.keys(d).filter(k => !shown.has(k) && !SKIP_FIELDS.has(k))];
```

Replace with:

```javascript
      function renderOsInfoTable(d) {
        const ORDER = ['distro_pretty_name','system','release','version','machine',
                       'processor','architecture','node','python_version',
                       'python_implementation',
                       'distro_name','distro_version','distro_id','distro_version_id'];
        const INFO_FIELDS = new Set(['hbc_version', 'hbc_type']);
        const shown = new Set(ORDER);
        const keys = [...ORDER, ...Object.keys(d).filter(k => !shown.has(k) && !SKIP_FIELDS.has(k) && !INFO_FIELDS.has(k))];
```

- [ ] **Step 2: Verify in browser**

Expand a host card, then expand the "Os Info" accordion. Confirm:
- `hbc_version` no longer appears in the os_info table.
- `hbc_type` no longer appears in the os_info table.
- Both values are shown correctly in the info section at the top.

- [ ] **Step 3: Run the full test suite**

```bash
pytest tests/ -q
```

Expected: all tests PASS.

- [ ] **Step 4: Commit**

```bash
git add hbd/server/templates/plugins.html
git commit -m "feat: move hbc_version and hbc_type out of os_info into host info section"
```