ahmadrosid/nakama

Prova em vídeo no navegador para PRs

Grave um vídeo curto e reproduzível no navegador que comprove uma correção de UI, anexe-o à descrição do PR e verifique o corpo ao vivo. Não altere o código da aplicação para a gravação, a menos que o usuário peça explicitamente.

Referência: PR #723 (rolagem expandida longa em /automations).

Pré-requisitos

• gh autenticado com acesso de push ao repositório alvo
• Bun + dependências do repositório instaladas na worktree (bun install)
• Google Chrome (ou Chromium) no host
• ffmpeg no PATH (para conversão webm → H.264 MP4)
• Playwright em um diretório isolado em /tmp (não o adicione ao repositório):

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

Processo

1. Isole com uma worktree git

Mantenha o checkout principal limpo.

cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b <branch> .worktrees/<slug> origin/main   # ou anexe ao branch de correção
cd .worktrees/<slug>

Trabalhe apenas dentro dessa worktree para servidores e gravação.

2. Inspecione fixtures e UI primeiro

Antes de inventar dados:

1. Leia a página sob teste (rótulos, controles de expansão, contêineres de rolagem).
2. Verifique fixtures / fábricas de teste existentes para a mesma funcionalidade.
3. Prefira semear via API HTTP pública. Recorra a uma inserção SQLite única em um NAKAMA_CONFIG_DIR isolado apenas quando nenhuma API puder criar a linha necessária (ex.: uma execução de automação concluída com output enorme).

3. Semee conteúdo longo determinístico

Para provas de rolagem / overflow, a fixture deve ser mais alta que o painel.

• Coloque um marcador superior único perto do início: SCROLL_PROOF_MARKER_TOP
• Coloque um marcador inferior único no final: SCROLL_PROOF_MARKER_BOTTOM
• Use texto do corpo suficiente para que scrollHeight - clientHeight seja grande (milhares de px)

Exemplo de formato para saída de execução:

# SCROLL_PROOF_MARKER_TOP — saída longa de execução de automação

## Seção 1
...

## Seção 80
...

# SCROLL_PROOF_MARKER_BOTTOM — fim do conteúdo longo

Nunca semeie nos dados reais do ~/.nakama do operador. Use sempre um NAKAMA_CONFIG_DIR novo em /tmp/<run>/.

4. Inicie servidores locais isolados

Escolha portas livres. Não roube a pilha padrão se algo já escutar em 4310 / 3000 / 3003.

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

# Mantenha processos vivos após o shell sair (plain nohup ... & morre aqui)
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 &

Aguarde até que curl -sf http://127.0.0.1:$API_PORT/health tenha sucesso e a origem web responda. Setup inicial: POST /v1/auth/setup, depois crie provedor / perfil / automação (ou reutilize fixtures) com Cookie + X-CSRF-Token + X-Org-Id.

5. Grave com Playwright (H.264 MP4)

Crie o gravador sob /tmp/<run>/ apenas. Nunca o commite.

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

Regras:

1. Dirija o caminho real da UI sob teste (localizadores de texto/papel).
2. Torne o movimento visível — rolagem de roda do mouse ou rolagem passo a passo, não apenas um salto invisível único.
3. Afirme que a rolagem moveu (delta scrollTop) e que o marcador inferior se torna alcançável.
4. Capture page.video()?.path() antes de context.close().
5. Converta: ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4
6. Escreva results.json + capturas de tela antes/depois em artifacts/e2e-<id>/.

Apenas WebM não é suficiente para reprodução no GitHub. Envie H.264 + yuv420p.

6. Valide o vídeo antes de afirmar qualquer coisa

ffprobe -v error -show_entries stream=codec_name,width,height \
  -show_entries format=duration -of json out.mp4
# Extraia quadros iniciais / finais e veja-os
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

Passe apenas se:

• codec for h264
• duração for suficiente para ver a interação
• quadro inicial mostrar o estado inicial (ex.: marcador superior / painel expandido)
• quadro final mostrar progresso da rolagem (marcador inferior ou seções avançadas)
• results.json relatar um delta scrollTop real (ou métrica de prova equivalente)

7. Faça upload para os anexos de usuário do GitHub

Não documentado, mas a autenticação por token funciona para imagens/vídeo quando você tem acesso de push:

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>

Salve a URL. Confirme que um HEAD/GET no ativo retorna um tipo de conteúdo de vídeo.

8. Atualize a descrição do PR

Adicione uma seção curta Prova no navegador com os passos mostrados e a URL https://github.com/user-attachments/assets/... em sua própria linha (o GitHub incorpora o player). Prefira escrever o corpo via um arquivo:

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

Siga .agents/skills/adhd-pr-description/SKILL.md para o restante do corpo.

9. Verifique o corpo do PR ao vivo

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

Não relate sucesso até que esta verificação passe.

Exemplo: rolagem expandida de execução de automação

1. Worktree no branch de correção (ou branch só de documentação para esta skill).
2. API isolada 4330 + web 3014, NAKAMA_CONFIG_DIR novo.
3. POST /v1/auth/setup → provedor → crie automação Long output digester.
4. Insira/complete uma execução cujo output seja o markdown longo com SCROLL_PROOF_MARKER_TOP / SCROLL_PROOF_MARKER_BOTTOM.
5. Playwright: abra /automations → selecione a automação → Expandir execução → role o painel de detalhes até que o marcador inferior esteja visível.
6. Converta para H.264 MP4, inspecione quadros, faça upload, atualize o corpo do PR, verifique.

Limpeza

1. Mate os listeners isolados da API/web nas portas que você escolheu.
2. Deixe /tmp/<run>/ e o perfil artifacts/e2e-<id>/ como evidência local (não commite vídeos ou scripts do gravador).
3. Remova a worktree quando o branch for mesclado ou abandonado: git worktree remove .worktrees/<slug>

Regras de honestidade

1. Nunca afirme prova no navegador sem assistir aos quadros ou ffprobe + capturas de tela.
2. Nunca cole uma URL user-attachments que você não enviou e reobteve do corpo ao vivo do PR.
3. Nunca trate um teste unitário verde como substituto do vídeo quando a solicitação foi por prova visual.
4. Se a rolagem não se moveu, os marcadores estão errados ou o MP4 está vazio/corrompido — diga que falhou. Não suavize.
5. Não modifique o código da aplicação "para facilitar o vídeo" a menos que o usuário tenha pedido uma correção de produto.
6. Não toque no diretório de configuração real do Nakama do operador.