Local PR Review Board

Aplicacao local para cadastrar repositorios GitHub, sincronizar pull requests e executar reviews automatizados em worktrees descartaveis com codex exec.

Status atual

O fluxo principal esta implementado: cadastro de repositorios, clone local, sync de PRs, importacao de comentarios, analise com Codex, publicacao manual de comentarios inline, resposta e resolucao de threads.

Documentacao complementar:

• Visao geral
• Arquitetura
• Layout e UI
• Checklist do projeto

Pre-requisitos

• Node.js 22 LTS ou superior
• npm 10 ou superior
• Git
• GitHub CLI (gh) autenticado localmente
• Codex CLI instalado e autenticado

Verificacoes de ambiente

node --version
npm --version
git --version
gh --version
gh auth status
codex --version

Configuracao

cp .env.example .env

Variaveis principais:

• APP_HOST e APP_PORT: bind local do Express
• SESSION_SECRET: segredo da sessao
• ADMIN_USERNAME e ADMIN_PASSWORD: seed do administrador
• SQLITE_FILENAME: arquivo SQLite
• PROJECTS_ROOT e STORAGE_ROOT: diretorios locais gerenciados pela aplicacao

Instalacao

npm install

Banco de dados

npm run migrate
npm run seed

Execucao em desenvolvimento

npm run dev

Comandos separados:

npm run dev:server
npm run dev:worker
npm run dev:client

Cron local

Exemplo de cron local:

SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
PROJECT_DIR=/path/to/local-pr-review-board

*/10 * * * * cd "$PROJECT_DIR" && npm run sync:prs >> storage/logs/sync-prs.log 2>&1
*/15 * * * * cd "$PROJECT_DIR" && npm run reviews:cron >> storage/logs/reviews-cron.log 2>&1

Comandos operacionais:

npm run sync:prs
npm run reviews:cron

O sync:prs faz:

• recovery de estados expirados
• sync de todos os repositorios configured e ready
• importacao de PRs elegiveis
• importacao de comentarios inline, respostas e resolucoes

O reviews:cron faz:

• lock global para impedir duas execucoes concorrentes
• recovery de locks expirados, review runs travados e worktrees orfaos
• sincronizacao dos PRs elegiveis antes de montar a fila
• execucao sequencial em modo analysis
• persistencia do resultado validado

O reviews:cron nao publica comentarios automaticamente. A publicacao e manual pela interface.

Estrutura

client/   frontend Vue 3 + Vite
server/   backend Express + Knex + SQLite
docs/     instrucoes centrais, schema e modelo de banco
data/     banco SQLite local
projects/ clones e worktrees descartaveis
storage/  logs e artefatos operacionais

Politica de seguranca

• todos os comandos externos devem usar spawn(..., { shell: false })
• o Codex nao publica nada diretamente no GitHub
• reviews so podem ocorrer com repositorio configured = 1
• worktrees sao descartaveis
• markdown renderizado na UI deve ser sanitizado
• o bind padrao e 127.0.0.1

Fluxo funcional previsto

1. login local com sessao
2. cadastro de repositorio e upload opcional de instrucoes
3. enfileiramento de clone assincrono
4. sincronizacao de PRs via gh
5. execucao de reviews pelo cron local com codex exec

Como o Codex analisa

O Codex roda dentro de um worktree descartavel criado a partir do clone local do repositorio, no head_sha exato do PR. Para comparar com a base, o backend atualiza a branch base, informa base_sha no prompt e o Codex pode usar comandos Git locais como git diff <base_sha>...HEAD ou git show <base_sha>:<path>.

Detalhes: Arquitetura - Uso do Repositorio Local pelo Codex.

Diagnostico e manutencao

• GET /api/health: healthcheck simples
• GET /api/diagnostics: status inicial de ferramentas e diretorios
• logs operacionais ficam em storage/logs
• eventos operacionais tambem sao persistidos em audit_logs
• npm run sync:prs e npm run reviews:cron executam recovery basico antes do fluxo principal
• worktrees descartaveis sem review_run ativo sao limpos automaticamente

Limitacoes atuais

• publicacao automatica de comentarios esta desligada por seguranca
• paginacao de comentarios/review threads ainda usa limite de 100 itens por PR
• cobertura de testes ainda pode ser expandida
• ver todo.md para proximos passos