boban
/
clusev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(wg): SP2 Phase 1 plan — live-status dashboard page 

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat/v1-foundation
boban 2026-06-20 23:26:15 +02:00
parent 19fe1b8915
commit dfdb0ce732
1 changed files with 752 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

752
docs/superpowers/plans/2026-06-20-wireguard-dashboard-p1-status.md Normal file
View File

@ -0,0 +1,752 @@
# 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:poll`s 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`:
```bash
# 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:
```bash
# 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:
```bash
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:
```bash
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**
```bash
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`):
```ini
# 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`):
```ini
# 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**
```bash
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:
```bash
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:
```bash
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" \`):
```bash
&& 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):
```bash
&& systemctl enable --now clusev-wg-collect.timer \
```
Add the two temps to the cleanup `rm -f` line:
```bash
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**
```bash
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
<?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
<?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:
```php
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**
```bash
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
<?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
<?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
<?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
<?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`:
```blade
@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:
```php
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:
```blade
<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):
```php
'nav_wireguard' => 'WireGuard',
```
- [ ] **Step 8: Run the test → passes.** Run: `… php artisan test --filter=WireguardPageTest` → PASS. Pint the new PHP files.
- [ ] **Step 9: Commit**
```bash
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.