ahmadrosid/nakama

Browser-Videobeweis für PRs

Ein kurzes, abspielbares Browser-Video aufnehmen, das eine UI-Korrektur belegt, es an die PR-Beschreibung anhängen und den Live-Text überprüfen. Ändere keinen Anwendungscode für die Aufnahme, es sei denn, der Benutzer bittet ausdrücklich darum.

Referenz-PR: PR #723 (/automations expanded long-run scroll).

Voraussetzungen

• gh authentifiziert mit Push-Zugriff auf das Ziel-Repository
• Bun + Repo-Abhängigkeiten im Worktree installiert (bun install)
• Google Chrome (oder Chromium) auf dem Host
• ffmpeg im PATH (für WebM → H.264 MP4)
• Playwright in einem isolierten Verzeichnis unter /tmp (nicht zum Repo hinzufügen):

mkdir -p /tmp/<run>/playwright
cd /tmp/<run>/playwright
npm i playwright
npx playwright install ffmpeg

Ablauf

1. Mit einem Git-Worktree isolieren

Haupt-Checkout sauber halten.

cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b <branch> .worktrees/<slug> origin/main   # oder an den Fix-Branch anhängen
cd .worktrees/<slug>

Nur innerhalb dieses Worktrees arbeiten: Server und Aufnahme.

2. Zuerst Fixtures und UI inspizieren

Bevor Daten erfunden werden:

1. Die zu testende Seite lesen (Labels, Expand-Steuerelemente, Scroll-Container).
2. Vorhandene Test-Fixtures / Fabriken für dasselbe Feature prüfen.
3. Bevorzugt über die öffentliche HTTP-API seeden. Nur dann auf einen einmaligen SQLite-Insert in einem isolierten NAKAMA_CONFIG_DIR zurückgreifen, wenn keine API die benötigte Zeile erstellen kann (z. B. ein abgeschlossener Automatisierungslauf mit großer output).

3. Deterministischen hohen Inhalt seeden

Für Scroll-/Overflow-Nachweise muss das Fixture höher als der Bereich sein.

• Einen eindeutigen oberen Marker nahe dem Anfang setzen: SCROLL_PROOF_MARKER_TOP
• Einen eindeutigen unteren Marker am Ende setzen: SCROLL_PROOF_MARKER_BOTTOM
• Genügend Text verwenden, sodass scrollHeight - clientHeight groß ist (tausende Pixel)

Beispiel für Run-Output:

# SCROLL_PROOF_MARKER_TOP — langer Automatisierungs-Run-Output

## Abschnitt 1
...

## Abschnitt 80
...

# SCROLL_PROOF_MARKER_BOTTOM — Ende des hohen Inhalts

Niemals in die echten ~/.nakama-Daten des Operators seeden. Immer ein frisches NAKAMA_CONFIG_DIR unter /tmp/<run>/ verwenden.

4. Isolierte lokale Server starten

Freie Ports wählen. Nicht den Standard-Stack kapern, wenn bereits etwas auf 4310 / 3000 / 3003 lauscht.

RUN=/tmp/<run>
API_PORT=4330
WEB_PORT=3014
mkdir -p "$RUN/nakama-data" "$RUN/logs"

# Prozesse am Leben halten, nachdem die Shell beendet ist (einfaches nohup ... & stirbt hier)
setsid nohup env NAKAMA_CONFIG_DIR="$RUN/nakama-data" NAKAMA_PORT=$API_PORT \
  bun run apps/server/src/index.ts \
  >"$RUN/logs/server.log" 2>&1 < /dev/null &

setsid nohup env VITE_API_URL="http://127.0.0.1:${API_PORT}" \
  bun run --cwd apps/web dev -- --host 127.0.0.1 --port $WEB_PORT \
  >"$RUN/logs/web.log" 2>&1 < /dev/null &

Warten, bis curl -sf http://127.0.0.1:$API_PORT/health erfolgreich ist und der Web-Ursprung antwortet. Frische Einrichtung: POST /v1/auth/setup, dann Provider / Profil / Automatisierung erstellen (oder Fixtures wiederverwenden) mit Cookie + X-CSRF-Token + X-Org-Id.

5. Mit Playwright aufnehmen (H.264 MP4)

Rekorder nur unter /tmp/<run>/ aufsetzen. Niemals committen.

const browser = await chromium.launch({
  channel: "chrome", // wenn Chrome installiert ist
  headless: false,
  args: ["--disable-gpu"],
});
const context = await browser.newContext({
  viewport: { width: 1440, height: 900 },
  recordVideo: { dir: rawDir, size: { width: 1440, height: 900 } },
});

Regeln:

1. Den tatsächlichen UI-Pfad unter Test steuern (Rollen-/Text-Locators).
2. Bewegung sichtbar machen — Mausrad oder schrittweises Scrollen, kein einzelner unsichtbarer Sprung.
3. Assert, dass sich der Scroll bewegt hat (scrollTop-Delta) und der untere Marker erreichbar wird.
4. page.video()?.path() vor context.close() erfassen.
5. Konvertieren: ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4
6. results.json + Vorher-/Nachher-Screenshots unter artifacts/e2e-<id>/ schreiben.

WebM allein reicht für die GitHub-Wiedergabe nicht. H.264 + yuv420p ausliefern.

6. Video validieren, bevor etwas behauptet wird

ffprobe -v error -show_entries stream=codec_name,width,height \
  -show_entries format=duration -of json out.mp4
# Frühe / späte Frames extrahieren und ansehen
ffmpeg -y -ss 00:00:02 -i out.mp4 -vframes 1 frame-early.png
ffmpeg -y -ss 00:00:08 -i out.mp4 -vframes 1 frame-late.png

Nur bestehen, wenn:

• Codec h264 ist
• Dauer lang genug ist, um die Interaktion zu sehen
• früher Frame den Startzustand zeigt (z. B. oberer Marker / erweiterter Bereich)
• später Frame den Scroll-Fortschritt zeigt (unterer Marker oder fortgeschrittene Abschnitte)
• results.json ein echtes scrollTop-Delta (oder gleichwertige Beweismetrik) meldet

7. In GitHub user-attachments hochladen

Undokumentiert, aber Token-Authentifizierung funktioniert für Bilder/Videos, wenn du Push-Zugriff hast:

TOKEN=$(gh auth token)
REPO_ID=$(gh api repos/<owner>/<repo> --jq .id)
MP4=artifacts/e2e-<id>/<name>.mp4

UPLOAD_JSON=$(curl -sS -X POST \
  "https://uploads.github.com/user-attachments/assets?name=$(basename "$MP4")&repository_id=${REPO_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: video/mp4" \
  -H "Accept: application/vnd.github+json" \
  --data-binary @"${MP4}")

VIDEO_URL=$(printf '%s' "$UPLOAD_JSON" | bun -e 'console.log(JSON.parse(await Bun.stdin.text()).url)')
echo "$VIDEO_URL"  # https://github.com/user-attachments/assets/<uuid>

Die URL speichern. Mit einem HEAD/GET auf das Asset bestätigen, dass ein Video-Content-Typ zurückgegeben wird.

8. PR-Beschreibung aktualisieren

Einen kurzen Browser-Beweis-Abschnitt mit den gezeigten Schritten und der nackten https://github.com/user-attachments/assets/...-URL in einer eigenen Zeile hinzufügen (GitHub bettet den Player ein). Bevorzugt den Text über eine Datei schreiben:

gh api repos/<owner>/<repo>/pulls/<n> --method PATCH --input body.json
# oder: gh pr edit <n> --body-file /tmp/pr-body.md

Dem Rest der Beschreibung folgen nach .agents/skills/adhd-pr-description/SKILL.md.

9. Live-PR-Text überprüfen

gh api repos/<owner>/<repo>/pulls/<n> --jq .body | rg 'user-attachments/assets/<uuid>|Browser proof'

Erst Erfolg melden, wenn dieser Check bestanden ist.

Beispiel: automations expanded-run scroll

1. Worktree auf dem Fix-Branch (oder Docs-only-Branch für dieses Skill).
2. Isolierte API 4330 + Web 3014, frisches NAKAMA_CONFIG_DIR.
3. POST /v1/auth/setup → Provider → Automatisierung Long output digester erstellen.
4. Einen Run einfügen/abschließen, dessen output das lange Markdown mit SCROLL_PROOF_MARKER_TOP / SCROLL_PROOF_MARKER_BOTTOM ist.
5. Playwright: /automations öffnen → Automatisierung auswählen → Expand run → im Detailbereich mit dem Mausrad scrollen, bis der untere Marker sichtbar ist.
6. In H.264 MP4 konvertieren, Frames inspizieren, hochladen, PR-Text patchen, überprüfen.

Aufräumen

1. Die isolierten API-/Web-Listener auf den gewählten Ports beenden.
2. /tmp/<run>/ und Profil artifacts/e2e-<id>/ als lokale Beweise belassen (keine Videos oder Rekorder-Skripte committen).
3. Worktree entfernen, wenn der Branch gemerged oder aufgegeben wurde: git worktree remove .worktrees/<slug>

Ehrlichkeitsregeln

1. Niemals einen Browser-Beweis behaupten, ohne Frames oder ffprobe + Screenshots angesehen zu haben.
2. Niemals eine user-attachments-URL einfügen, die du nicht hochgeladen und aus dem Live-PR-Text erneut abgerufen hast.
3. Niemals einen grünen Unit-Test als Ersatz für das Video behandeln, wenn die Anfrage ein visueller Beweis war.
4. Wenn sich der Scroll nicht bewegt hat, Marker falsch sind oder das MP4 leer/beschädigt ist — sag, dass es fehlgeschlagen ist. Keine Beschönigung.
5. Keinen Anwendungscode ändern, „um das Video einfacher zu machen“, es sei denn, der Benutzer hat nach einer Produktkorrektur gefragt.
6. Das echte Nakama-Konfigurationsverzeichnis des Operators nicht anfassen.