repo-radar

O que repo-radar faz?

O dashboard é um único arquivo HTML, extraído do GitHub por scripts/dashboard.py. Ele precisa de Python 3.10+, PyYAML e a CLI do GitHub (gh), autenticada. Nada nele chama uma IA, então pode ser reconstruído todas as manhãs em uma GitHub Action gratuitamente.

Suas abas:

Aba	O que mostra
Plano	Apenas quando o repositório tem um arquivo de plano. Cada parte do sistema como caixas, quem é o dono e quais itens estão construídos, em revisão ou faltando. Sinaliza itens cujo PR foi mesclado ou fechado, e PRs abertos que nenhum item referencia.
Pull requests	PRs abertos organizados pelo que precisam: pronto para mesclar, precisa de revisão, aguardando autor, checks falhando, rascunho. "Comece por aqui" seleciona até cinco.
Issues	Issues abertas: ninguém atribuído ainda, alguém atribuído, um PR está aberto.
Gráfico	Como o trabalho aberto se conecta: caixa do plano → issue → PR, sub-issues, "bloqueado por", PRs construídos sobre branches de outros PRs.
Concluído	PRs e issues fechados nos últimos 90 dias, sob a release que os enviou.

Há duas formas de configurar. Pergunte qual a pessoa deseja se não estiver claro:

Modo	Para	O que adiciona, onde
Em um repositório (init)	Alguém trabalhando naquele repositório	Uma Action diária naquele repositório, construindo a página do repositório
Lista de monitoramento (init --watch)	Alguém monitorando vários repositórios, como um gerente ou professor	Uma Action diária em um repositório próprio, construindo uma página por repositório monitorado mais uma visão geral. Nada é adicionado aos repositórios monitorados

SCRIPT abaixo significa scripts/dashboard.py na pasta desta skill, ou .github/dashboard/dashboard.py em um repositório que executou init.

O arquivo de plano (opcional)

O plano lista o que o sistema precisa, que o GitHub não pode saber: partes para as quais ninguém abriu uma issue ou PR ainda. O formato completo está no topo de scripts/dashboard_plan.py, e templates/plan.yaml é um ponto de partida. Em resumo: grupos de caixas, cada caixa uma lista de itens, cada item built, simulated, pr (com seu número) ou missing. Caixas têm um owner, ou assumem o do grupo. O local padrão é docs/plan.yaml; passe --plan para outro caminho.

Regras

1. Relate primeiro, edite apenas quando solicitado. O script nunca edita o plano. Edite-o apenas quando a pessoa pedir para colocar seu pull request nele.
2. Edite apenas os itens da própria pessoa. Deixe itens de outras pessoas e a linha as_of em paz. Pull requests abertos não devem editar as mesmas linhas.
3. Não marque itens como built a menos que a pessoa execute a atualização semanal. Uma pessoa faz isso uma vez por semana, depois que o pull request for mesclado. Diga "mesclado, pronto para a atualização semanal" em vez disso.
4. Nunca invente um status. Um item é pr apenas quando um pull request aberto realiza aquele trabalho. Quando você não conseguir dizer a qual caixa um pull request pertence, pergunte.
5. Nunca faça commit da página HTML no branch principal. A Action diária a mantém em seu próprio branch dashboard. Uma página construída manualmente vai para uma pasta temporária fora do repositório (<diretório temporário> abaixo).

Configurar em um repositório

Pergunte, de uma vez, antes de escrever qualquer coisa:

• A equipe quer um plano? Se sim, onde (padrão docs/plan.yaml), e já existe um? Qualquer arquivo no formato acima funciona, então um existente pode permanecer.
• A que horas deve ser reconstruído? A Action usa UTC; padrão 11:00 UTC diariamente.

Então, a partir da pasta raiz do repositório:

python SCRIPT init                                   # scripts + Action diária
python SCRIPT init --with-plan                       # ... e um docs/plan.yaml inicial
python SCRIPT init --plan caminho/para/plan.yaml     # ... usando um plano existente

init escreve .github/dashboard/ (os scripts) e .github/workflows/dashboard.yml, e se recusa a substituir arquivos que existem. Depois:

1. Construa a página uma vez localmente (próxima seção) e mostre-a, para que a pessoa veja funcionando.
2. Se você escreveu um plano inicial, preencha-o com a pessoa: grupos, caixas, donos e uma lista people mapeando cada nome de dono ao seu login do GitHub.
3. Diga a eles o que commitar (os arquivos que init escreveu, e o plano), e que depois de chegar ao branch padrão eles podem executá-lo imediatamente da aba Actions ("Dashboard", depois "Run workflow").
4. Diga a eles como visualizá-lo todas as manhãs: git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html, então abra dashboard.html. Para um repositório público, eles podem em vez disso ativar o GitHub Pages para o branch dashboard e obter um endereço web.

Se a Action falhar com "Permission denied" no push, o repositório ou organização limita o que as Actions podem fazer: Settings → Actions → General → Workflow permissions, "Read and write". A pessoa, não você, altera essa configuração.

Configurar uma lista de monitoramento (vários repositórios)

Pergunte, de uma vez: quais repositórios monitorar (como proprietário/nome), se algum mantém seu plano em um local diferente de docs/plan.yaml, qual repositório deles deve conter a lista de monitoramento (um novo repositório vazio é suficiente), e a que horas reconstruir (UTC).

Antes de escrever qualquer coisa, construa as páginas uma vez para que a pessoa as veja:

python SCRIPT watch --list <diretório temporário>/watchlist.yaml --out <diretório temporário>/radar

Abra index.html nessa pasta. Um repositório que não pode ser lido mostra seu erro na sua linha em vez de parar os outros: geralmente um erro de digitação no nome, ou um repositório privado.

Então, no repositório que conterá a lista:

python SCRIPT init --watch            # scripts, watchlist.yaml e .github/workflows/radar.yml

Escreva os repositórios da pessoa em watchlist.yaml, depois diga a eles:

1. O que commitar (os arquivos que init --watch escreveu), e que uma vez que chegue ao branch padrão eles podem executá-lo imediatamente da aba Actions ("Radar", depois "Run workflow").
2. Repositórios privados precisam de um token. A Action pode ler repositórios públicos e seu próprio repositório, nada mais. Para monitorar repositórios privados, a pessoa cria um token do GitHub que possa lê-los, e o salva como um segredo chamado RADAR_TOKEN no repositório de monitoramento (Settings → Secrets and variables → Actions). Eles fazem isso sozinhos; nunca peça pelo token ou cole em lugar nenhum.
3. Como visualizá-lo todas as manhãs: mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar, então abra radar/index.html.

Para adicionar ou remover um repositório depois, edite watchlist.yaml; nada mais muda.

Atualizar a cópia dos scripts em um repositório

init copia os scripts para o repositório, então um repositório continua executando a versão que recebeu até que alguém a atualize. Quando a pessoa pedir para atualizar o repo-radar em um repositório, ou os scripts desta skill forem mais novos que os do repositório, execute a partir da pasta raiz do repositório:

python scripts/dashboard.py update        # cópia desta skill, não de .github/dashboard/

Ele substitui apenas os scripts em .github/dashboard/ e informa quais mudaram. A Action, a lista de monitoramento e o plano permanecem como a pessoa os deixou. Então diga a eles para commitar .github/dashboard/.

Visualizar agora

python SCRIPT build --out <diretório temporário>/dashboard.html

Execute dentro do repositório (ou passe --repo proprietário/nome). Escreva a página em uma pasta temporária fora do repositório, para que nunca seja commitada, e então mostre-a para a pessoa. Explique o que ela diz em palavras simples, começando pelo cartão "Comece por aqui" e quaisquer tags amarelas na aba Plano. Cada contagem carrega seu contexto: "12 de 16 pull requests abertos precisam de revisão", não "12 precisam de revisão".

Onde estou (uma pessoa, contra o plano)

Você precisa de dois nomes: o nome do dono como o plano o escreve, e o login do GitHub. Se a lista people do plano tem o login com o qual gh está autenticado, o script encontra o nome sozinho. Caso contrário, pergunte, e passe --owner "<Nome>". Passe --login apenas quando a pessoa perguntar sobre outra pessoa.

Execute duas vezes quando a pessoa estiver em um branch de pull request. Main mostra o que a equipe vê hoje; o branch mostra o que este pull request mudará:

git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me

O relatório tem quatro tabelas:

Tabela	O que diz para a pessoa
Suas caixas	Para cada caixa da qual são donos ou têm um pull request: quantos itens estão construídos, simulados, em um PR, faltando
Itens ainda faltando	Seu próximo trabalho, caixa por caixa
Itens marcados como pr, verificados contra o GitHub	Um PR aberto não precisa de nada. Um PR mesclado está pronto para a atualização semanal. Um PR fechado não mesclado significa que o item deve voltar para missing
Seus pull requests abertos sem item no plano	Trabalho que o plano ainda não mostra

Explique nesta ordem: o que está concluído e em revisão; quais pull requests o plano está perdendo, e a qual caixa cada um provavelmente pertence; qualquer item cujo pull request fechou sem mesclar; o primeiro item faltando como a provável próxima tarefa.

Colocar um pull request no plano (apenas quando solicitado)

Trabalhe no branch do pull request da pessoa, não no main.

1. Encontre o número do pull request: gh pr view --json number,title.
2. Encontre o item que aquele pull request constrói. Leia as caixas da pessoa no plano.
   • Se um item já descreve o trabalho, mude seu status para pr e adicione pr: <número>.
   • Se nenhum item fizer isso, adicione um à caixa certa: {status: pr, pr: <número>, text: "<o que constrói>"}. Mantenha text curto e simples. Pergunte à pessoa qual caixa, quando não for óbvio.
3. Verifique se o plano ainda carrega: python SCRIPT build --out <diretório temporário>/check.html. Ele para com uma mensagem nomeando o erro se não.
4. Execute me novamente. O pull request agora deve estar em "Itens marcados como pr", não em "sem item no plano".
5. Faça commit do arquivo de plano no pull request da pessoa.

Atualização semanal (apenas para a pessoa que a faz)

Construa a página no main, ou execute me --ref origin/main uma vez para cada dono. Então, em um pull request:

• Marque cada item cujo pull request foi mesclado como built, ou simulated se o trabalho mesclado é um esboço, falso ou esqueleto. A aba Plano marca estes como "mesclado".
• Defina cada item cujo pull request fechou sem mesclar de volta para missing.
• Liste os pull requests abertos sem item (a última seção da aba Plano) na descrição do pull request, para que seus donos os coloquem. Não adivinhe suas caixas.
• Defina as_of para o commit e data do main que você verificou.

Sem acesso à rede

python SCRIPT fetch --out data.json salva o que o GitHub disse; build --data data.json e me --data data.json então funcionam offline. Testes usam isso.