boban
/
clusev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
clusev/docs/superpowers/plans/2026-06-20-wireguard-dashbo...

32 KiB
Raw Blame History

WireGuard dashboard — Phase 1 (live status) 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: A read-only /wireguard dashboard page showing live WireGuard status — gate state, server info, and connected peers (handshake, endpoint, rx/tx) — fed by a periodic host collector through the ./run bridge.

Architecture: A new clusev-wg.sh collect subcommand (run by a systemd .timer every 5 s) writes run/wg-status.json. A PHP WgStatus reader parses + validates that file; a full-page Livewire component renders it and wire:polls every 5 s. No writes, no DB, no chart (those are P2–P4). Container never touches the host — same constraint as SP1.

Tech Stack: bash + wg/iptables/systemctl (host), systemd .timer/.service, Laravel 13 + Livewire 3, Tailwind v4 tokens, Pint, shellcheck. Spec: docs/superpowers/specs/2026-06-20-wireguard-dashboard-sp2-design.md (§0 Bridge 1, §1, §2).

Run tooling (R8): tests docker compose --project-directory /home/nexxo/clusev exec -T -u 1002:1002 app sh -lc 'mkdir -p /tmp/views-test && VIEW_COMPILED_PATH=/tmp/views-test php artisan test --filter=<X>'; Pint … vendor/bin/pint <files>; shellcheck docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable <script>. Commit on feat/v1-foundation; do not push until the release task.

File Structure

  • docker/wg/clusev-wg.sh (modify) — gains a collect subcommand + a RUN_DIR derivation (project root from the script location, override via $CLUSEV_DIR). Writes run/wg-status.json atomically; no secrets in it.
  • docker/wg/clusev-wg-collect.service + docker/wg/clusev-wg-collect.timer (new) — periodic collector (oneshot every 5 s).
  • install.sh (modify) — render + enable the collect timer inside install_host_watchers().
  • app/Services/WgStatus.php (new) — reads + validates run/wg-status.json → a typed array; the single source for both the page and the route. One responsibility: parse the status file.
  • routes/web.php (modify) — GET /wg-status.json (auth-gated; has peer names/endpoints) using WgStatus.
  • app/Livewire/Wireguard/Index.php + resources/views/livewire/wireguard/index.blade.php (new) — the page.
  • resources/views/components/sidebar.blade.php (modify) — nav entry; lang/{de,en}/shell.php — nav_wireguard.
  • lang/{de,en}/wireguard.php (new) — page strings (identical keys, R9/R16).
  • Tests: tests/Feature/WgStatusTest.php, tests/Feature/WireguardPageTest.php.

Task 1: clusev-wg.sh collect subcommand

Files: Modify docker/wg/clusev-wg.sh

  • Step 1: Add the RUN_DIR derivation near the other constants (after the PANEL_PORTS="80,443" line). It resolves the project root from the script's own location (docker/wg/clusev-wg.sh → ../..), overridable by the systemd unit's $CLUSEV_DIR:
# Project root (for the run/ bridge dir). The collect timer sets CLUSEV_DIR; otherwise derive it
# from this script's location (docker/wg/clusev-wg.sh -> ../..).
SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
CLUSEV_DIR="${CLUSEV_DIR:-$(cd "${SELF_DIR}/../.." && pwd)}"
RUN_DIR="${CLUSEV_DIR}/run"
  • Step 2: Add the cmd_collect function (place it just before the usage() function). It emits run/wg-status.json atomically and never errors:
# Emit run/wg-status.json (atomic temp+mv). Public, NO secrets. If WG isn't configured, emits
# {"configured":false}. Run every few seconds by clusev-wg-collect.timer; the dashboard reads it.
cmd_collect() {
  mkdir -p "$RUN_DIR" 2>/dev/null || true
  local now tmp dest
  now="$(date +%s 2>/dev/null || echo 0)"
  dest="${RUN_DIR}/wg-status.json"
  tmp="$(mktemp "${RUN_DIR}/.wg-status.XXXXXX" 2>/dev/null)" || tmp="${RUN_DIR}/.wg-status.tmp"

  if [ ! -f "$WG_CONF" ]; then
    printf '{"at":%s,"configured":false}\n' "$now" > "$tmp"
    mv -f "$tmp" "$dest" 2>/dev/null || { rm -f "$tmp"; return 0; }
    chmod 644 "$dest" 2>/dev/null || true
    return 0
  fi

  # shellcheck disable=SC1090
  [ -f "$WG_ENV" ] && . "$WG_ENV"
  local gate_marker=false gate_chain=false wgq
  [ -f "$GATE_MARKER" ] && gate_marker=true
  iptables -nL "$GATE_CHAIN" >/dev/null 2>&1 && gate_chain=true
  wgq="$(systemctl is-active "wg-quick@${WG_IF}" 2>/dev/null || echo inactive)"

  # Peers from `wg show wg0 dump`, named via the wg0.conf `# clusev-peer:` comments. Peer names are
  # valid_name-restricted and pubkeys/endpoints are from safe charsets, so the values are JSON-safe.
  local peers_json
  peers_json="$({ wg show "$WG_IF" dump 2>/dev/null || true; } | awk -v conf="$WG_CONF" '
    BEGIN {
      name=""
      while ((getline line < conf) > 0) {
        if (line ~ /^# clusev-peer:/) { sub(/^# clusev-peer:[ \t]*/,"",line); name=line }
        else if (name != "" && line ~ /^PublicKey[ \t]*=/) { p=line; sub(/^PublicKey[ \t]*=[ \t]*/,"",p); names[p]=name; name="" }
      }
      close(conf); out=""; first=1
    }
    NR==1 { next }   # interface line
    {
      pk=$1; endp=$3; hs=$5+0; rx=$6+0; tx=$7+0
      if (endp=="(none)") endp=""
      nm=(pk in names)?names[pk]:""
      rec="{\"name\":\"" nm "\",\"pubkey\":\"" pk "\",\"endpoint\":\"" endp "\",\"latest_handshake\":" hs ",\"rx\":" rx ",\"tx\":" tx "}"
      if (first) { out=rec; first=0 } else { out=out "," rec }
    }
    END { printf "[%s]", out }
  ')"
  [ -n "$peers_json" ] || peers_json="[]"

  printf '{"at":%s,"configured":true,"gate":{"marker":%s,"chain":%s},"wg_quick":"%s","server":{"subnet":"%s","server_ip":"%s","port":%s,"endpoint":"%s","pubkey":"%s"},"peers":%s}\n' \
    "$now" "$gate_marker" "$gate_chain" "$wgq" \
    "${WG_SUBNET:-}" "${WG_SERVER_IP:-}" "${WG_PORT:-0}" "${WG_ENDPOINT:-}" "${WG_SERVER_PUBKEY:-}" \
    "$peers_json" > "$tmp"
  mv -f "$tmp" "$dest" 2>/dev/null || { rm -f "$tmp"; return 0; }
  chmod 644 "$dest" 2>/dev/null || true
}
  • Step 3: Add the dispatch arm. In the case "$cmd" switch, add after the gate-apply) arm:
  collect)     cmd_collect ;;   # called by clusev-wg-collect.timer (root not required: read-only)
  • Step 4: bash -n + shellcheck

Run: bash -n docker/wg/clusev-wg.sh → exit 0. Run: docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable docker/wg/clusev-wg.sh → clean apart from the existing # shellcheck disable=SC1090 lines.

  • Step 5: Smoke collect (safe — read-only, no WG on this host). It must produce a configured:false file without error:
CLUSEV_DIR="$PWD" bash docker/wg/clusev-wg.sh collect; echo "exit=$?"; cat run/wg-status.json; rm -f run/wg-status.json

Expected: exit=0 and {"at":<number>,"configured":false} (no /etc/wireguard/wg0.conf on the dev host). Then remove the test artifact.

  • Step 6: Commit
git add docker/wg/clusev-wg.sh
git commit -m "feat(wg): clusev-wg.sh collect — emit run/wg-status.json for the dashboard"

Task 2: collect timer + service units

Files: Create docker/wg/clusev-wg-collect.service, docker/wg/clusev-wg-collect.timer

  • Step 1: Write the service (docker/wg/clusev-wg-collect.service):
# Clusev WireGuard status collector — oneshot (HOST-side). Run every few seconds by the paired
# .timer; writes run/wg-status.json (no secrets) which the dashboard reads. Cheap: `wg show` is
# instant and an unconfigured host exits immediately. install.sh rewrites the /home/nexxo/clusev paths.
[Unit]
Description=Clusev WireGuard status collector
After=network.target

[Service]
Type=oneshot
User=root
Environment=CLUSEV_DIR=/home/nexxo/clusev
WorkingDirectory=/home/nexxo/clusev
ExecStart=/home/nexxo/clusev/docker/wg/clusev-wg.sh collect
  • Step 2: Write the timer (docker/wg/clusev-wg-collect.timer):
# Fires clusev-wg-collect.service every 5 s (after a 10 s boot delay). The dashboard treats a
# wg-status.json older than ~20 s as "collector offline".
[Unit]
Description=Clusev WireGuard status collector — periodic trigger

[Timer]
OnBootSec=10s
OnUnitActiveSec=5s
AccuracySec=1s
Unit=clusev-wg-collect.service

[Install]
WantedBy=timers.target

  • Step 3: Verify systemd-analyze verify docker/wg/clusev-wg-collect.timer docker/wg/clusev-wg-collect.service 2>&1 — no key/section errors (ExecStart-not-found is fine; path rendered at install). If systemd-analyze is absent, eyeball that the [Unit]/[Timer]/[Install] and [Unit]/[Service] sections + directives match the sibling units in docker/restart-sentinel/.

  • Step 4: Commit

git add docker/wg/clusev-wg-collect.service docker/wg/clusev-wg-collect.timer
git commit -m "feat(wg): clusev-wg-collect timer+service — 5s status collection"

Task 3: install.sh — render + enable the collect timer

Files: Modify install.sh (install_host_watchers())

  • Step 1: Render + enable the timer. In install_host_watchers(), mirror the gate-unit handling. After the line local tmp_gate; tmp_gate="$(mktemp)" add:
  local tmp_csvc tmp_ctimer; tmp_csvc="$(mktemp)"; tmp_ctimer="$(mktemp)"

After the gate sed line (sed "s#/home/nexxo/clusev#${proj}#g" "docker/wg/clusev-wg-gate.service" > "$tmp_gate") add:

  sed "s#/home/nexxo/clusev#${proj}#g" "docker/wg/clusev-wg-collect.service" > "$tmp_csvc"
  sed "s#/home/nexxo/clusev#${proj}#g" "docker/wg/clusev-wg-collect.timer"   > "$tmp_ctimer"

In the if install … && systemctl …; then chain, add the two installs after the gate install line (&& install -m 0644 "$tmp_gate" "${dst}/clusev-wg-gate.service" \):

     && install -m 0644 "$tmp_csvc"   "${dst}/clusev-wg-collect.service" \
     && install -m 0644 "$tmp_ctimer" "${dst}/clusev-wg-collect.timer" \

and add the enable+start after the gate enable line (&& systemctl enable clusev-wg-gate.service \) — the collector is safe to start now (read-only, emits configured:false until WG is set up):

     && systemctl enable --now clusev-wg-collect.timer \

Add the two temps to the cleanup rm -f line:

  rm -f "$tmp_path" "$tmp_svc" "$tmp_upath" "$tmp_usvc" "$tmp_gate" "$tmp_csvc" "$tmp_ctimer"

  • Step 2: Verify. bash -n install.sh → exit 0. shellcheck install.sh → no NEW findings vs the committed version (capture the baseline first: git show HEAD:install.sh > /tmp/i.sh; docker run --rm -v /tmp:/mnt -w /mnt koalaman/shellcheck:stable i.sh). Eyeball: daemon-reload still runs after all installs; the timer enable is among the enables.

  • Step 3: Commit

git add install.sh
git commit -m "feat(wg): install + enable the WireGuard status collector timer"

Task 4: WgStatus reader service + /wg-status.json route

Files: Create app/Services/WgStatus.php; Modify routes/web.php; Test tests/Feature/WgStatusTest.php

  • Step 1: Write the failing test (tests/Feature/WgStatusTest.php):
<?php

namespace Tests\Feature;

use App\Models\User;
use App\Services\WgStatus;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class WgStatusTest extends TestCase
{
    use RefreshDatabase;

    private string $file;

    protected function setUp(): void
    {
        parent::setUp();
        $dir = storage_path('app/restart-signal');
        @mkdir($dir, 0775, true);
        $this->file = $dir.'/wg-status.json';
        @unlink($this->file);
    }

    protected function tearDown(): void
    {
        @unlink($this->file);
        parent::tearDown();
    }

    public function test_absent_file_reads_as_unconfigured(): void
    {
        $s = app(WgStatus::class)->read();
        $this->assertFalse($s['configured']);
        $this->assertTrue($s['stale']);
    }

    public function test_parses_a_configured_status_with_peers(): void
    {
        file_put_contents($this->file, json_encode([
            'at' => time(),
            'configured' => true,
            'gate' => ['marker' => true, 'chain' => true],
            'wg_quick' => 'active',
            'server' => ['subnet' => '10.99.0.0/24', 'server_ip' => '10.99.0.1', 'port' => 51820, 'endpoint' => '1.2.3.4:51820', 'pubkey' => 'srvpub'],
            'peers' => [
                ['name' => 'laptop', 'pubkey' => 'p1', 'endpoint' => '5.6.7.8:41820', 'latest_handshake' => time(), 'rx' => 100, 'tx' => 200],
                ['name' => 'phone', 'pubkey' => 'p2', 'endpoint' => '', 'latest_handshake' => 0, 'rx' => 0, 'tx' => 0],
            ],
        ]));

        $s = app(WgStatus::class)->read();
        $this->assertTrue($s['configured']);
        $this->assertFalse($s['stale']);
        $this->assertTrue($s['gate']['marker']);
        $this->assertSame(51820, $s['server']['port']);
        $this->assertCount(2, $s['peers']);
        $this->assertTrue($s['peers'][0]['online']);   // fresh handshake
        $this->assertFalse($s['peers'][1]['online']);  // handshake 0
    }

    public function test_stale_when_at_is_old(): void
    {
        file_put_contents($this->file, json_encode(['at' => time() - 999, 'configured' => true, 'peers' => []]));
        $this->assertTrue(app(WgStatus::class)->read()['stale']);
    }

    public function test_route_requires_auth_and_returns_status(): void
    {
        $this->get('/wg-status.json')->assertRedirect('/login'); // gated

        file_put_contents($this->file, json_encode(['at' => time(), 'configured' => false]));
        $this->actingAs(User::factory()->create(['must_change_password' => false]))
            ->getJson('/wg-status.json')->assertOk()->assertJson(['configured' => false]);
    }
}
  • Step 2: Run it → fails (WgStatus + route missing).

Run: … php artisan test --filter=WgStatusTest Expected: FAIL (class not found / route 404).

  • Step 3: Write app/Services/WgStatus.php:
<?php

namespace App\Services;

/**
 * Reads + validates the host-written status file run/wg-status.json (bind-mounted to
 * storage/app/restart-signal). Single source for the WireGuard page + the /wg-status.json route.
 * Contains NO secrets — the collector never writes a private key.
 */
class WgStatus
{
    /** Status older than this (seconds) means the host collector is offline. */
    private const STALE_AFTER = 20;

    /** A peer with a handshake within this many seconds is considered online. */
    private const ONLINE_WITHIN = 180;

    private function path(): string
    {
        return storage_path('app/restart-signal/wg-status.json');
    }

    /**
     * @return array{configured:bool, at:int, stale:bool, gate?:array, wg_quick?:string, server?:array, peers?:array}
     */
    public function read(): array
    {
        $path = $this->path();
        $data = is_file($path) ? json_decode((string) @file_get_contents($path), true) : null;

        if (! is_array($data)) {
            return ['configured' => false, 'at' => 0, 'stale' => true];
        }

        $at = (int) ($data['at'] ?? 0);
        $stale = $at < (time() - self::STALE_AFTER);

        if (empty($data['configured'])) {
            return ['configured' => false, 'at' => $at, 'stale' => $stale];
        }

        $peers = [];
        foreach ((array) ($data['peers'] ?? []) as $p) {
            if (! is_array($p)) {
                continue;
            }
            $hs = (int) ($p['latest_handshake'] ?? 0);
            $peers[] = [
                'name' => (string) ($p['name'] ?? ''),
                'pubkey' => (string) ($p['pubkey'] ?? ''),
                'endpoint' => (string) ($p['endpoint'] ?? ''),
                'latest_handshake' => $hs,
                'rx' => (int) ($p['rx'] ?? 0),
                'tx' => (int) ($p['tx'] ?? 0),
                'online' => $hs > (time() - self::ONLINE_WITHIN),
            ];
        }

        return [
            'configured' => true,
            'at' => $at,
            'stale' => $stale,
            'gate' => [
                'marker' => (bool) ($data['gate']['marker'] ?? false),
                'chain' => (bool) ($data['gate']['chain'] ?? false),
            ],
            'wg_quick' => (string) ($data['wg_quick'] ?? 'inactive'),
            'server' => [
                'subnet' => (string) ($data['server']['subnet'] ?? ''),
                'server_ip' => (string) ($data['server']['server_ip'] ?? ''),
                'port' => (int) ($data['server']['port'] ?? 0),
                'endpoint' => (string) ($data['server']['endpoint'] ?? ''),
                'pubkey' => (string) ($data['server']['pubkey'] ?? ''),
            ],
            'peers' => $peers,
        ];
    }
}
  • Step 4: Add the route. In routes/web.php, inside the EnsureSecurityOnboarded panel group (next to the other authed routes — it carries peer names/endpoints, so it is NOT public like /version.json), add:
        Route::get('/wg-status.json', fn (\App\Services\WgStatus $wg) => response()->json($wg->read()))->name('wg.status');
  • Step 5: Run the test → passes.

Run: … php artisan test --filter=WgStatusTest → PASS. Pint app/Services/WgStatus.php tests/Feature/WgStatusTest.php.

  • Step 6: Commit
git add app/Services/WgStatus.php routes/web.php tests/Feature/WgStatusTest.php
git commit -m "feat(wg): WgStatus reader + auth-gated /wg-status.json route"

Task 5: the /wireguard page

Files: Create app/Livewire/Wireguard/Index.php, resources/views/livewire/wireguard/index.blade.php, lang/de/wireguard.php, lang/en/wireguard.php; Modify routes/web.php, resources/views/components/sidebar.blade.php, lang/de/shell.php, lang/en/shell.php; Test tests/Feature/WireguardPageTest.php

  • Step 1: Write the failing test (tests/Feature/WireguardPageTest.php):
<?php

namespace Tests\Feature;

use App\Livewire\Wireguard\Index;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Livewire\Livewire;
use Tests\TestCase;

class WireguardPageTest extends TestCase
{
    use RefreshDatabase;

    private string $file;

    protected function setUp(): void
    {
        parent::setUp();
        $dir = storage_path('app/restart-signal');
        @mkdir($dir, 0775, true);
        $this->file = $dir.'/wg-status.json';
        @unlink($this->file);
        $this->actingAs(User::factory()->create(['must_change_password' => false]));
    }

    protected function tearDown(): void
    {
        @unlink($this->file);
        parent::tearDown();
    }

    public function test_renders_unconfigured_state(): void
    {
        Livewire::test(Index::class)
            ->assertOk()
            ->assertViewHas('status', fn ($s) => $s['configured'] === false)
            ->assertSee(__('wireguard.not_configured_title'));
    }

    public function test_renders_peers_when_configured(): void
    {
        file_put_contents($this->file, json_encode([
            'at' => time(), 'configured' => true,
            'gate' => ['marker' => true, 'chain' => true], 'wg_quick' => 'active',
            'server' => ['subnet' => '10.99.0.0/24', 'server_ip' => '10.99.0.1', 'port' => 51820, 'endpoint' => '1.2.3.4:51820', 'pubkey' => 'srvpub'],
            'peers' => [['name' => 'laptop', 'pubkey' => 'p1', 'endpoint' => '5.6.7.8:41820', 'latest_handshake' => time(), 'rx' => 100, 'tx' => 200]],
        ]));

        Livewire::test(Index::class)
            ->assertOk()
            ->assertViewHas('status', fn ($s) => $s['configured'] === true && count($s['peers']) === 1)
            ->assertSee('laptop')
            ->assertSee('10.99.0.0/24');
    }
}

  • Step 2: Run it → fails (component + view + lang missing).

  • Step 3: Write the component (app/Livewire/Wireguard/Index.php):

<?php

namespace App\Livewire\Wireguard;

use App\Services\WgStatus;
use Livewire\Attributes\Layout;
use Livewire\Component;

/**
 * WireGuard dashboard — live status (read-only, Phase 1). Renders the host-collected
 * run/wg-status.json (via WgStatus) and wire:polls every 5s. No writes here (P3/P4).
 */
#[Layout('layouts.app')]
class Index extends Component
{
    public function render(WgStatus $wg)
    {
        return view('livewire.wireguard.index', [
            'status' => $wg->read(),
        ])->title(__('wireguard.title'));
    }
}
  • Step 4: Write the lang files. lang/de/wireguard.php:
<?php

return [
    'title' => 'WireGuard — Clusev',
    'eyebrow' => 'Netzwerk',
    'heading' => 'WireGuard',
    'subtitle' => 'Tunnel-Zugang zum Panel — Live-Status.',

    // Not-configured empty state
    'not_configured_title' => 'WireGuard ist nicht eingerichtet',
    'not_configured_body' => 'Auf dem Host einrichten: per SSH „sudo clusev wg setup". Danach erscheint hier der Live-Status.',

    // Collector
    'stale' => 'Status veraltet — der Host-Collector antwortet nicht. Läuft der Stack?',

    // Gate
    'gate' => 'Gate (Panel-Sperre)',
    'gate_on' => 'aktiv — Panel nur über den Tunnel',
    'gate_off' => 'aus — Panel öffentlich erreichbar',
    'gate_escape' => 'Notausgang per SSH: „clusev wg down".',

    // Server card
    'server_title' => 'Server',
    'subnet' => 'Subnetz',
    'server_ip' => 'Server-IP',
    'port' => 'Port',
    'endpoint' => 'Endpoint',
    'server_key' => 'Server-Schlüssel',
    'service' => 'Dienst',

    // Peers
    'peers_title' => 'Peers',
    'peers_count' => ':count Peer|:count Peers',
    'no_peers' => 'Noch keine Peers — per SSH „clusev wg add-peer <name>".',
    'online' => 'online',
    'offline' => 'offline',
    'last_handshake' => 'letzter Handshake',
    'never' => 'nie',
    'transfer' => 'Übertragung',
    'down_up' => '↓ :rx · ↑ :tx',
];

lang/en/wireguard.php (identical keys, R9/R16):

<?php

return [
    'title' => 'WireGuard — Clusev',
    'eyebrow' => 'Network',
    'heading' => 'WireGuard',
    'subtitle' => 'Tunnel access to the panel — live status.',

    'not_configured_title' => 'WireGuard is not set up',
    'not_configured_body' => 'Set it up on the host: over SSH run "sudo clusev wg setup". The live status appears here afterwards.',

    'stale' => 'Status is stale — the host collector is not responding. Is the stack running?',

    'gate' => 'Gate (panel lock)',
    'gate_on' => 'on — panel only via the tunnel',
    'gate_off' => 'off — panel publicly reachable',
    'gate_escape' => 'Escape over SSH: "clusev wg down".',

    'server_title' => 'Server',
    'subnet' => 'Subnet',
    'server_ip' => 'Server IP',
    'port' => 'Port',
    'endpoint' => 'Endpoint',
    'server_key' => 'Server key',
    'service' => 'Service',

    'peers_title' => 'Peers',
    'peers_count' => ':count peer|:count peers',
    'no_peers' => 'No peers yet — over SSH run "clusev wg add-peer <name>".',
    'online' => 'online',
    'offline' => 'offline',
    'last_handshake' => 'last handshake',
    'never' => 'never',
    'transfer' => 'Transfer',
    'down_up' => '↓ :rx · ↑ :tx',
];
  • Step 5: Write the view (resources/views/livewire/wireguard/index.blade.php). Token utilities only (R3), no inline style (R4), responsive (R7), DE/EN via __(), no emoji except the ↓/↑ glyphs which are text arrows (allowed — not status emoji), reuse x-panel/x-badge/x-status-dot:
@php
    $fmtBytes = function (int $n): string {
        $u = ['B', 'KB', 'MB', 'GB', 'TB'];
        $i = 0;
        $v = (float) $n;
        while ($v >= 1024 && $i < count($u) - 1) { $v /= 1024; $i++; }
        return ($i === 0 ? (string) $n : number_format($v, 1)).' '.$u[$i];
    };
    $ago = function (int $ts): string {
        if ($ts <= 0) return __('wireguard.never');
        $d = max(0, time() - $ts);
        if ($d < 60) return $d.'s';
        if ($d < 3600) return intdiv($d, 60).'m';
        if ($d < 86400) return intdiv($d, 3600).'h';
        return intdiv($d, 86400).'d';
    };
@endphp

<div class="space-y-5" wire:poll.5s>
    {{-- Header --}}
    <div>
        <p class="font-mono text-[11px] uppercase tracking-[0.2em] text-accent-text">{{ __('wireguard.eyebrow') }}</p>
        <h2 class="mt-0.5 font-display text-xl font-semibold text-ink sm:text-2xl">{{ __('wireguard.heading') }}</h2>
        <p class="mt-1 text-sm text-ink-3">{{ __('wireguard.subtitle') }}</p>
    </div>

    @if (! $status['configured'])
        {{-- Not-configured empty state --}}
        <x-panel :title="__('wireguard.not_configured_title')">
            <p class="text-sm leading-relaxed text-ink-2">{{ __('wireguard.not_configured_body') }}</p>
            <pre class="mt-3 overflow-x-auto rounded-md border border-line bg-void px-3 py-2.5 font-mono text-[11px] text-ink-2">sudo clusev wg setup</pre>
        </x-panel>
    @else
        @if ($status['stale'])
            <div class="flex items-center gap-2 rounded-lg border border-warning/30 bg-warning/10 px-4 py-3">
                <x-icon name="alert" class="h-4 w-4 shrink-0 text-warning" />
                <span class="text-sm text-ink-2">{{ __('wireguard.stale') }}</span>
            </div>
        @endif

        <div class="grid grid-cols-1 gap-5 lg:grid-cols-[minmax(0,1fr)_320px]">
            {{-- Peers --}}
            <x-panel :title="__('wireguard.peers_title')" :subtitle="trans_choice('wireguard.peers_count', count($status['peers']), ['count' => count($status['peers'])])" :padded="false">
                <div class="divide-y divide-line">
                    @forelse ($status['peers'] as $peer)
                        <div class="flex flex-wrap items-center gap-x-4 gap-y-2 px-4 py-3.5 sm:px-5" wire:key="peer-{{ $peer['pubkey'] }}">
                            <span class="inline-flex items-center gap-2">
                                <x-status-dot :status="$peer['online'] ? 'online' : 'offline'" />
                                <span class="font-mono text-sm font-semibold text-ink">{{ $peer['name'] !== '' ? $peer['name'] : Str::limit($peer['pubkey'], 10, '…') }}</span>
                            </span>
                            <span class="font-mono text-[11px] text-ink-4">{{ $peer['online'] ? __('wireguard.online') : __('wireguard.offline') }}</span>
                            <span class="ml-auto font-mono text-[11px] text-ink-3">{{ __('wireguard.last_handshake') }}: {{ $ago($peer['latest_handshake']) }}</span>
                            <span class="w-full font-mono text-[11px] text-ink-3">
                                {{ $peer['endpoint'] !== '' ? $peer['endpoint'] : '—' }}
                                <span class="ml-2 text-ink-4">{{ __('wireguard.down_up', ['rx' => $fmtBytes($peer['rx']), 'tx' => $fmtBytes($peer['tx'])]) }}</span>
                            </span>
                        </div>
                    @empty
                        <p class="px-4 py-4 font-mono text-[11px] text-ink-3 sm:px-5">{{ __('wireguard.no_peers') }}</p>
                    @endforelse
                </div>
            </x-panel>

            {{-- Aside: gate + server --}}
            <div class="space-y-5">
                <x-panel :title="__('wireguard.gate')">
                    @if ($status['gate']['marker'] && $status['gate']['chain'])
                        <x-badge tone="cyan">{{ __('wireguard.gate_on') }}</x-badge>
                    @else
                        <x-badge tone="neutral">{{ __('wireguard.gate_off') }}</x-badge>
                    @endif
                    <p class="mt-2 font-mono text-[11px] text-ink-4">{{ __('wireguard.gate_escape') }}</p>
                </x-panel>

                <x-panel :title="__('wireguard.server_title')" :padded="false">
                    <dl class="space-y-2 px-4 py-4 font-mono text-[11px] sm:px-5">
                        <div class="flex items-center justify-between gap-3"><dt class="text-ink-4">{{ __('wireguard.subnet') }}</dt><dd class="text-ink-2">{{ $status['server']['subnet'] ?: '—' }}</dd></div>
                        <div class="flex items-center justify-between gap-3"><dt class="text-ink-4">{{ __('wireguard.server_ip') }}</dt><dd class="text-ink-2">{{ $status['server']['server_ip'] ?: '—' }}</dd></div>
                        <div class="flex items-center justify-between gap-3"><dt class="text-ink-4">{{ __('wireguard.port') }}</dt><dd class="text-ink-2">{{ $status['server']['port'] ?: '—' }}</dd></div>
                        <div class="flex items-center justify-between gap-3"><dt class="text-ink-4">{{ __('wireguard.endpoint') }}</dt><dd class="truncate text-ink-2">{{ $status['server']['endpoint'] ?: '—' }}</dd></div>
                        <div class="flex items-center justify-between gap-3"><dt class="text-ink-4">{{ __('wireguard.service') }}</dt><dd class="text-ink-2">{{ $status['wg_quick'] }}</dd></div>
                    </dl>
                </x-panel>
            </div>
        </div>
    @endif
</div>
  • Step 6: Add the route. In routes/web.php, in the onboarded panel group (near /system), add:
        Route::get('/wireguard', Wireguard\Index::class)->name('wireguard');

and ensure the use App\Livewire\Wireguard; import is present at the top (add it alphabetically near the other App\Livewire\* imports).

  • Step 7: Add the sidebar nav + shell lang. In resources/views/components/sidebar.blade.php, in the Fleet group, after the Audit nav item, add:
        <x-nav-item icon="lock" href="/wireguard" :active="request()->is('wireguard*')">{{ __('shell.nav_wireguard') }}</x-nav-item>

In lang/de/shell.php and lang/en/shell.php, add (both files, identical key):

    'nav_wireguard' => 'WireGuard',

  • Step 8: Run the test → passes. Run: … php artisan test --filter=WireguardPageTest → PASS. Pint the new PHP files.

  • Step 9: Commit

git add app/Livewire/Wireguard/ resources/views/livewire/wireguard/ lang/de/wireguard.php lang/en/wireguard.php routes/web.php resources/views/components/sidebar.blade.php lang/de/shell.php lang/en/shell.php tests/Feature/WireguardPageTest.php
git commit -m "feat(wg): /wireguard live-status page (read-only) + nav (DE/EN)"

Task 6: verify + release

  • Step 1: shellcheck + Pint + full suite. shellcheck docker/wg/clusev-wg.sh install.sh docker/clusev/clusev → clean. Pint --dirty clean. … php artisan test → all pass.

  • Step 2: R12 browser-verify /wireguard (login via the gkonrad temp-password + puppeteer flow, CLAUDE.md R12). Because the dev host runs no collector, FIRST stub a populated status file so the configured state renders, then also test the unconfigured state by removing it:

    • Stub: write a populated storage/app/restart-signal/wg-status.json (a configured payload with 1–2 peers, fresh at), load /wireguard at 1280 + 375 → HTTP 200, peers + gate + server render, zero console errors, no leaked tokens; screenshot.
    • Then rm the file, reload → the "not configured" empty state renders 200, no errors.
    • Switch locale to EN, reload → EN strings. Restore the gkonrad password + remove the stub file afterwards.

  • Step 3: Release. Bump config/clusev.php to 0.9.34; CHANGELOG entry under ## [0.9.34] (Hinzugefügt: WireGuard-Dashboard — Live-Status (read-only); host-side collector; weitere Phasen folgen). Commit chore: release 0.9.34, tag v0.9.34, push branch + tag (token from /home/nexxo/.env.gitea, sanitised).

Self-Review

Spec coverage (P1 scope = spec §0 Bridge 1 + §1 + §2):

  • Collector subcommand + status JSON shape → Task 1. ✓
  • .timer/.service periodic collection → Task 2. ✓
  • install.sh render+enable → Task 3. ✓
  • /wg-status.json route (auth-gated, whitelisted) → Task 4. ✓
  • WgStatus reader (single source) → Task 4. ✓
  • /wireguard page: gate badge + escape caveat, server card, peer list (online/handshake/endpoint/rx-tx), empty + stale states, wire:poll, sidebar nav, DE/EN → Task 5. ✓
  • R12 + release → Task 6. ✓
  • Out of P1 (deferred, per spec phases): write-bridge, peer add/remove, settings, history graph, chart lib. Not in this plan — correct.

Placeholder scan: none — every step has concrete code/commands.

Type/name consistency: WgStatus::read() returns the same array shape consumed by the route (Task 4), the component render() (Task 5), and asserted by both tests. The status JSON keys written by cmd_collect (Task 1: at/configured/gate{marker,chain}/wg_quick/server{subnet,server_ip,port,endpoint,pubkey}/peers[{name,pubkey,endpoint,latest_handshake,rx,tx}]) match exactly what WgStatus::read() parses (Task 4) and the view renders (Task 5). cmd_collect/RUN_DIR (Task 1) referenced consistently by the units (Task 2) + install (Task 3). nav_wireguard/wireguard.* lang keys used in the view exist in both lang files.

Note (carried from spec): the dev stack runs no collector, so P1's live state is only exercised in tests + the R12 stub; the real collector runs on the deployed host (verify there after clusev update). This mirrors the SP1 host-script reality.