From ca693219bf9a92fd78d7777b541ed736f84e4af6 Mon Sep 17 00:00:00 2001 From: boban Date: Fri, 19 Jun 2026 22:06:08 +0200 Subject: [PATCH] docs(plan): implementation plan for the in-panel help page Co-Authored-By: Claude Opus 4.8 (1M context) --- .../superpowers/plans/2026-06-19-help-page.md | 459 ++++++++++++++++++ 1 file changed, 459 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-19-help-page.md diff --git a/docs/superpowers/plans/2026-06-19-help-page.md b/docs/superpowers/plans/2026-06-19-help-page.md new file mode 100644 index 0000000..173c060 --- /dev/null +++ b/docs/superpowers/plans/2026-06-19-help-page.md @@ -0,0 +1,459 @@ +# Hilfe-Seite 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:** Eine bilinguale In-Panel-Hilfe-Seite unter `/help` mit linker Themen-Navigation, die alle Einstellungen erklärt — inkl. generischer Reverse-Proxy-Anleitung und dem 2FA-Zugangspfad-Hinweis. + +**Architecture:** Full-Page-Livewire-Komponente `App\Livewire\Help\Index` (App-Layout, hinter Auth + Onboarding). Kurze Strings in `lang/{de,en}/help.php`; lange Texte als Blade-Partials je Sprache unter `resources/views/livewire/help/content/{de,en}/.blade.php`, nach `app()->getLocale()` eingebunden (Fallback `de`). Kein State außer `$topic`. + +**Tech Stack:** Laravel 13, Livewire 3 (class-based), Tailwind v4 `@theme`-Tokens, bestehende Blade-Komponenten (`x-nav-item`, `x-panel`, `x-icon`). + +**Konventionen (hart):** Route-Pfad englisch (R13); sichtbare Texte DE+EN, kein Emoji (R9/R16); nur `@theme`-Token-Utilities, keine Inline-Styles (R4/R3); Container-Tooling (R8); Browser-Verify (R12) + Codex (R15) vor „fertig". + +Spec: `docs/superpowers/specs/2026-06-19-help-page-design.md` (Abschnitt 4 = verbindliche Inhalte). + +--- + +## Task 1: Gerüst + Thema „overview" + Tests (TDD) + +**Files:** +- Create: `app/Livewire/Help/Index.php` +- Create: `resources/views/livewire/help/index.blade.php` +- Create: `resources/views/livewire/help/content/de/overview.blade.php` +- Create: `resources/views/livewire/help/content/en/overview.blade.php` +- Create: `lang/de/help.php`, `lang/en/help.php` +- Modify: `routes/web.php` (Route + Import) +- Modify: `resources/views/components/sidebar.blade.php` (Nav-Eintrag nach Zeile 36) +- Modify: `lang/de/shell.php`, `lang/en/shell.php` (`nav_help`) +- Modify: `resources/views/components/command-palette.blade.php` (chords + `$nav`) +- Modify: `resources/js/app.js` (`CMDK_GO` + `h`) +- Test: `tests/Feature/HelpPageTest.php` + +- [ ] **Step 1: Failing test** + +`tests/Feature/HelpPageTest.php`: +```php +actingAs(User::factory()->create(['must_change_password' => false])); + } + + public function test_help_route_loads_for_an_authenticated_admin(): void + { + $this->actAsAdmin(); + $this->get('/help')->assertOk(); + } + + public function test_default_topic_is_overview(): void + { + $this->actAsAdmin(); + Livewire::test(Index::class) + ->assertSet('topic', 'overview') + ->assertSee(__('help.topic_overview')); + } + + public function test_unknown_topic_falls_back_to_overview(): void + { + $this->actAsAdmin(); + Livewire::test(Index::class, ['topic' => 'bogus'])->assertSet('topic', 'overview'); + } +} +``` + +- [ ] **Step 2: Run — expect FAIL** + +Run: `docker compose exec -T -u app app php artisan test --filter=HelpPageTest` +Expected: FAIL (class `App\Livewire\Help\Index` not found). + +- [ ] **Step 3: Component** + +`app/Livewire/Help/Index.php`: +```php +.blade.php. + */ +#[Layout('layouts.app')] +class Index extends Component +{ + /** Help topics in display order. Keys are also the content-partial filenames. */ + private const TOPICS = [ + 'overview', 'domain-tls', 'security', 'updates', + 'servers', 'sessions', 'email', 'audit', 'recovery', + ]; + + public string $topic = 'overview'; + + public function mount(?string $topic = null): void + { + if ($topic !== null && in_array($topic, self::TOPICS, true)) { + $this->topic = $topic; + } + } + + public function render() + { + $labels = [ + 'overview' => __('help.topic_overview'), + 'domain-tls' => __('help.topic_domain_tls'), + 'security' => __('help.topic_security'), + 'updates' => __('help.topic_updates'), + 'servers' => __('help.topic_servers'), + 'sessions' => __('help.topic_sessions'), + 'email' => __('help.topic_email'), + 'audit' => __('help.topic_audit'), + 'recovery' => __('help.topic_recovery'), + ]; + + $topics = array_map(fn (string $key): array => ['key' => $key, 'label' => $labels[$key]], self::TOPICS); + + return view('livewire.help.index', ['topics' => $topics])->title(__('help.title')); + } +} +``` + +- [ ] **Step 4: Chrome lang files** + +`lang/de/help.php`: +```php + 'Hilfe — Clusev', + 'eyebrow' => 'Hilfe', + 'heading' => 'Hilfe & Dokumentation', + 'subtitle' => 'Einstellungen und Abläufe erklärt.', + + 'topic_overview' => 'Überblick', + 'topic_domain_tls' => 'Domain, TLS & Reverse-Proxy', + 'topic_security' => 'Sicherheit & 2FA', + 'topic_updates' => 'Updates & Versionen', + 'topic_servers' => 'Server & SSH', + 'topic_sessions' => 'Sitzungen & Benutzer', + 'topic_email' => 'E-Mail (SMTP)', + 'topic_audit' => 'Audit-Log', + 'topic_recovery' => 'Konto-Wiederherstellung', +]; +``` + +`lang/en/help.php` (same keys, English values): +```php + 'Help — Clusev', + 'eyebrow' => 'Help', + 'heading' => 'Help & documentation', + 'subtitle' => 'Settings and procedures explained.', + + 'topic_overview' => 'Overview', + 'topic_domain_tls' => 'Domain, TLS & reverse proxy', + 'topic_security' => 'Security & 2FA', + 'topic_updates' => 'Updates & versions', + 'topic_servers' => 'Servers & SSH', + 'topic_sessions' => 'Sessions & users', + 'topic_email' => 'Email (SMTP)', + 'topic_audit' => 'Audit log', + 'topic_recovery' => 'Account recovery', +]; +``` + +- [ ] **Step 5: Index view** + +`resources/views/livewire/help/index.blade.php`: +```blade +@php + $locale = in_array(app()->getLocale(), ['de', 'en'], true) ? app()->getLocale() : 'de'; + $partial = 'livewire.help.content.'.$locale.'.'.$topic; + if (! view()->exists($partial)) { + $partial = 'livewire.help.content.de.'.$topic; + } +@endphp + +
+
+

{{ __('help.eyebrow') }}

+

{{ __('help.heading') }}

+

{{ __('help.subtitle') }}

+
+ +
+ {{-- Topic nav --}} + + + {{-- Content --}} +
+ @include($partial) +
+
+
+``` + +- [ ] **Step 6: overview partials (de + en)** + +`resources/views/livewire/help/content/de/overview.blade.php` — short, real prose. Cover: was Clusev ist (Fleet-Control über SSH); Erst-Login `admin@clusev.local` / `clusev` (sofort ändern, Zwangswechsel); Bare-IP vs. Domain; wo man was findet (Server, Dienste, Dateien, Audit, Einstellungen, System, Version, Hilfe). Use `

`, `

`, ``. NO emoji, NO inline styles. + +`resources/views/livewire/help/content/en/overview.blade.php` — same content, English. + +- [ ] **Step 7: Route + import** + +`routes/web.php`: add import near the other `use App\Livewire\...;` lines: +```php +use App\Livewire\Help; +``` +Inside the `EnsureSecurityOnboarded` group, after the `/versions` route: +```php +Route::get('/help', Help\Index::class)->name('help'); +``` + +- [ ] **Step 8: Sidebar nav** + +`resources/views/components/sidebar.blade.php` — after the `/versions` `x-nav-item` (line 36), add: +```blade +{{ __('shell.nav_help') }} +``` +If `x-icon` has no `help-circle` case, add it to `resources/views/components/icon.blade.php` with the Lucide path: +```blade +@case('help-circle') + + @break +``` +(Match the existing `@case`/`@break` structure + the component's stroke attributes.) + +- [ ] **Step 9: shell lang + cmdk** + +`lang/de/shell.php`: add `'nav_help' => 'Hilfe',`. `lang/en/shell.php`: add `'nav_help' => 'Help',`. + +`resources/views/components/command-palette.blade.php`: +- In `$chords` (after `['g v', __('shell.nav_versions')],`): add `['g h', __('shell.nav_help')],` +- In `$nav` (after the versions entry): add `['label' => __('shell.nav_help'), 'href' => '/help', 'hint' => 'g h'],` + +`resources/js/app.js` line ~256 `CMDK_GO`: add `h: '/help'` to the map: +```js +const CMDK_GO = { d: '/', s: '/servers', i: '/services', f: '/files', l: '/audit', e: '/settings', y: '/system', v: '/versions', h: '/help' }; +``` + +- [ ] **Step 10: Run — expect PASS** + +Run: `docker compose exec -T -u app app php artisan test --filter=HelpPageTest` +Expected: PASS (3 tests). + +- [ ] **Step 11: Pint + commit** + +```bash +docker compose exec -T -u app app ./vendor/bin/pint app/Livewire/Help/Index.php tests/Feature/HelpPageTest.php +git add app/Livewire/Help routes/web.php resources/views/livewire/help resources/views/components/sidebar.blade.php resources/views/components/command-palette.blade.php resources/views/components/icon.blade.php resources/js/app.js lang/de/help.php lang/en/help.php lang/de/shell.php lang/en/shell.php tests/Feature/HelpPageTest.php +git commit -m "feat(help): in-panel help page scaffold + overview topic" +``` + +--- + +## Task 2: Thema „domain-tls" (Reverse-Proxy-Anleitung) + +**Files:** +- Create: `resources/views/livewire/help/content/de/domain-tls.blade.php` +- Create: `resources/views/livewire/help/content/en/domain-tls.blade.php` +- Test: `tests/Feature/HelpPageTest.php` (add a test) + +- [ ] **Step 1: Failing test** — add to `HelpPageTest`: +```php + public function test_domain_tls_topic_has_the_reverse_proxy_guide(): void + { + $this->actAsAdmin(); + Livewire::test(Index::class) + ->set('topic', 'domain-tls') + ->assertSee('X-Forwarded-Proto') + ->assertSee('TRUSTED_PROXY_CIDR') + ->assertDontSee('Zoraxy'); // generic — no product names + } +``` + +- [ ] **Step 2: Run — expect FAIL** (`view [livewire.help.content.de.domain-tls] not found`). +Run: `docker compose exec -T -u app app php artisan test --filter=HelpPageTest` + +- [ ] **Step 3: Write the partials (de + en)** + +Content per spec §4a — three modes (Bare-IP / eingebautes TLS / externer Proxy) then the **generic step-by-step** proxy guide. MUST contain the literal tokens `X-Forwarded-Proto` and `TRUSTED_PROXY_CIDR`; MUST NOT contain `Zoraxy` (use „Proxy Manager"). Steps verbatim: +1. Im Panel: System → Domain → TLS „Externer Reverse-Proxy" → speichern → Stack neu starten. +2. Im Proxy Manager: Domain = `panel.`; Ziel = `http://:80` (HTTP); Host-Header + `X-Forwarded-Proto: https` weiterreichen; WebSocket aktivieren (`/app/*`, `/apps/*`). +3. `.env`: `TRUSTED_PROXY_CIDR` = Proxy-Adresse → Secure-Cookie + echte IP im Audit; danach `sudo ./update.sh`. +4. Firewall: HTTP-Port nur vom Proxy erreichbar. +5. In diesem Modus stellt Clusev kein Zertifikat aus. +Use `

`, `

`, `

    `/`
      `, and a `
      ` for the proxy fields/CLI. @theme tokens only.
+
+- [ ] **Step 4: Run — expect PASS.** `docker compose exec -T -u app app php artisan test --filter=HelpPageTest`
+
+- [ ] **Step 5: Commit**
+```bash
+git add resources/views/livewire/help/content tests/Feature/HelpPageTest.php
+git commit -m "feat(help): domain-tls topic with the reverse-proxy setup guide"
+```
+
+---
+
+## Task 3: Thema „security" (2FA-Zugangspfade + Extensions)
+
+**Files:**
+- Create: `resources/views/livewire/help/content/de/security.blade.php`
+- Create: `resources/views/livewire/help/content/en/security.blade.php`
+- Test: `tests/Feature/HelpPageTest.php`
+
+- [ ] **Step 1: Failing test** — add:
+```php
+    public function test_security_topic_explains_the_2fa_access_paths(): void
+    {
+        $this->actAsAdmin();
+        Livewire::test(Index::class)
+            ->set('topic', 'security')
+            ->assertSee('Backup-Code')
+            ->assertSee('TOTP');
+    }
+```
+
+- [ ] **Step 2: Run — expect FAIL.**
+
+- [ ] **Step 3: Write the partials (de + en)** — content per spec §4b + §4c:
+  - TOTP / Security-Keys (YubiKey) / Backup-Codes erklären.
+  - **Security-Key nur über die HTTPS-Domain** (WebAuthn braucht sicheren Kontext + Domain als rpId); über **Bare-IP/HTTP** kein Security-Key → **Backup-Code** nötig.
+  - **TOTP funktioniert überall** (auch Bare-IP/HTTP), braucht keinen Backup-Code für den IP-Pfad.
+  - Empfehlung: reiner Security-Key-Nutzer → Backup-Codes aufbewahren.
+  - Passwort-Manager-Extensions (Bitwarden/Kaspersky) können die Registrierung abfangen → in der Extension Passkey-Übernahme deaktivieren oder ohne Extension registrieren (privates Fenster).
+  Must contain literal `Backup-Code` and `TOTP`.
+
+- [ ] **Step 4: Run — expect PASS.**
+
+- [ ] **Step 5: Commit**
+```bash
+git add resources/views/livewire/help/content tests/Feature/HelpPageTest.php
+git commit -m "feat(help): security topic — 2FA access paths + extension note"
+```
+
+---
+
+## Task 4: Restliche Themen (updates, servers, sessions, email, audit, recovery)
+
+**Files:**
+- Create: `resources/views/livewire/help/content/{de,en}/{updates,servers,sessions,email,audit,recovery}.blade.php` (12 Partials)
+- Test: `tests/Feature/HelpPageTest.php`
+
+- [ ] **Step 1: Failing test** — assert every topic renders without falling back (a marker string per topic). Add:
+```php
+    /** @dataProvider topicProvider */
+    public function test_each_topic_renders_its_own_partial(string $topic, string $marker): void
+    {
+        $this->actAsAdmin();
+        Livewire::test(Index::class)->set('topic', $topic)->assertSee($marker);
+    }
+
+    public static function topicProvider(): array
+    {
+        return [
+            ['updates', 'update.sh'],
+            ['servers', 'SSH'],
+            ['sessions', 'Sitzung'],
+            ['email', 'SMTP'],
+            ['audit', 'Audit'],
+            ['recovery', 'clusev:reset-admin'],
+        ];
+    }
+```
+
+- [ ] **Step 2: Run — expect FAIL** (missing partials).
+
+- [ ] **Step 3: Write the 12 partials (de + en)** — each short + accurate:
+  - `updates`: Auto-Check, „Jetzt aktualisieren"-Knopf, CLI `sudo ./update.sh`, Build+Migrate beim Update. (marker `update.sh`)
+  - `servers`: Server hinzufügen, SSH-Credential-Vault, Hardening, SSH-Key-Provisioning. (marker `SSH`)
+  - `sessions`: aktive Sitzungen sehen/widerrufen, weitere Admins, Audit-Attribution. (marker `Sitzung`/`Session` — DE uses `Sitzung`)
+  - `email`: SMTP konfigurieren (Settings → E-Mail) + Testmail. (marker `SMTP`)
+  - `audit`: was protokolliert wird + Retention. (marker `Audit`)
+  - `recovery`: Forgot-Password (E-Mail-Link / 2FA-Proof), Bare-IP-Recovery, `clusev:reset-admin`. (marker `clusev:reset-admin`)
+  Same markup conventions (h3/p/ul/pre), @theme tokens, no emoji. EN partials mirror DE (the marker strings are language-neutral tokens, so the EN test passes too).
+
+- [ ] **Step 4: Run — expect PASS** (full HelpPageTest green).
+
+- [ ] **Step 5: Run full suite + Pint**
+```bash
+docker compose exec -T -u app app ./vendor/bin/pint
+docker compose exec -T -u app app php artisan test
+```
+Expected: all green.
+
+- [ ] **Step 6: Commit**
+```bash
+git add resources/views/livewire/help/content tests/Feature/HelpPageTest.php
+git commit -m "feat(help): remaining topics (updates, servers, sessions, email, audit, recovery)"
+```
+
+---
+
+## Task 5: Browser-Verify (R12), Codex (R15), Release
+
+**Files:** Modify `config/clusev.php` (version), `CHANGELOG.md`.
+
+- [ ] **Step 1: R12 browser-verify on the domain** — temp admin (create + delete after, do not touch the real account), headless Chrome via the puppeteer docker image against `https://panel.test.bave.dev/help`:
+  - HTTP 200, no console errors, no leaked `{{ }}`/`help.`/`shell.` tokens.
+  - Click two topic-nav buttons (`domain-tls`, `security`) → content swaps.
+  - Toggle DE/EN → content language changes (the partial locale switches).
+  - Check at 375 / 768 / 1280 widths.
+
+- [ ] **Step 2: Codex review** — run `/codex:review` over the diff; fix until no errors / no security issues.
+
+- [ ] **Step 3: Version + CHANGELOG** — bump `config/clusev.php` version; add a `### Hinzugefügt` entry: „In-Panel-Hilfe-Seite (`/help`) mit Themen-Navigation; erklärt alle Einstellungen, die Reverse-Proxy-Einrichtung und die 2FA-Zugangspfade (Security-Key nur über HTTPS-Domain, Backup-Code über Bare-IP, TOTP überall). Zoraxy-Produktname aus dem TLS-Hinweis entfernt."
+
+- [ ] **Step 4: Commit, tag, push** (token from `/home/nexxo/.env.gitea`, output sanitized):
+```bash
+git add config/clusev.php CHANGELOG.md
+git commit -m "chore(release): vX.Y.Z — in-panel help page"
+git tag -a vX.Y.Z -m "Clusev vX.Y.Z — Hilfe-Seite"
+TOKEN="$(grep -E '^GIT_ACCESS_TOKEN=' /home/nexxo/.env.gitea | cut -d= -f2- | tr -d '\r\n')"
+git push "https://boban:${TOKEN}@git.bave.dev/boban/clusev.git" feat/v1-foundation --follow-tags 2>&1 | sed -E 's#https://[^@]*@#https://@#g; s/[0-9a-f]{40,}//g'
+```
+
+- [ ] **Step 5: Deploy to VM + final verify** — `sudo ./update.sh` on the VM; confirm `/help` renders over the domain (R12 spot-check).
+
+---
+
+## Self-Review (Plan vs. Spec)
+
+- **Spec §1 Platzierung** → Task 1 (route, sidebar, cmdk, layout). ✓
+- **Spec §2 Aufbau** → Task 1 (component `$topic`, index view, topic nav). ✓
+- **Spec §3 zweisprachig** → Task 1 (lang chrome + per-locale partials + fallback). ✓
+- **Spec §4a Proxy-Anleitung** → Task 2 (must-have tokens, no product name). ✓
+- **Spec §4b 2FA-Pfade** → Task 3 (Backup-Code/TOTP markers). ✓
+- **Spec §4c Extensions** → Task 3. ✓
+- **Spec §5 Logik klein** → Task 1 component (pure display). ✓
+- **Spec §6 Dateistruktur** → all 18 partials across Tasks 1–4. ✓
+- **Spec §7 Test/Verify** → Tasks 1–4 (Livewire tests) + Task 5 (R12/Codex/Release). ✓
+- **Spec §8 YAGNI** → no search/markdown engine; static partials only. ✓
+
+Type/name consistency: topic keys identical in `TOPICS`, labels map, partial filenames, and tests (`overview`, `domain-tls`, `security`, `updates`, `servers`, `sessions`, `email`, `audit`, `recovery`). `$set('topic', …)` matches the public `$topic` prop.