repo-radar

¿Qué hace repo-radar?

El tablero es un archivo HTML, generado desde GitHub por scripts/dashboard.py. Necesita Python 3.10+, PyYAML y la CLI de GitHub (gh) con sesión iniciada. No utiliza ninguna IA, por lo que puede reconstruirse cada mañana en una GitHub Action de forma gratuita.

Sus pestañas:

Pestaña	Qué muestra
Plan	Solo cuando el repositorio tiene un archivo de plan. Cada parte del sistema como cajas, quién es responsable de cada una, y qué elementos están construidos, en revisión o faltantes. Marca los elementos cuyo PR se ha fusionado o cerrado, y los PR abiertos que no apuntan a ningún elemento.
Pull requests	PRs abiertos ordenados por lo que necesitan: listo para fusionar, necesita revisión, esperando al autor, verificaciones fallando, borrador. "Empezar aquí" selecciona hasta cinco.
Issues	Issues abiertos: nadie los ha tomado todavía, alguien asignado, hay un PR abierto.
Gráfico	Cómo se vinculan los trabajos abiertos: caja del plan → issue → PR, sub-issues, "bloqueado por", PRs construidos sobre ramas de otros PRs.
Hecho	PRs e issues cerrados en los últimos 90 días, bajo la versión que los publicó.

Hay dos formas de configurarlo. Pregunta cuál quiere la persona si no está claro:

Forma	Para	Qué añade, dónde
En un repositorio (init)	Alguien que trabaja en ese repositorio	Una Action diaria en ese repositorio, que genera la página de ese repositorio
Lista de vigilancia (init --watch)	Alguien que sigue varios repositorios, como un manager o un profesor	Una Action diaria en un repositorio propio, que genera una página por repositorio vigilado más una vista general. No se añade nada a los repositorios vigilados

SCRIPT a continuación significa scripts/dashboard.py en la carpeta de esta habilidad, o .github/dashboard/dashboard.py en un repositorio que haya ejecutado init.

El archivo de plan (opcional)

El plan enumera lo que el sistema necesita, lo que GitHub no puede saber: partes para las que nadie ha abierto un issue o PR todavía. El formato completo está al inicio de scripts/dashboard_plan.py, y templates/plan.yaml es un punto de partida. En resumen: grupos de cajas, cada caja una lista de elementos, cada elemento built, simulated, pr (con su número) o missing. Las cajas tienen un owner, o toman el de su grupo. La ubicación predeterminada es docs/plan.yaml; pasa --plan para otra ruta.

Reglas

1. Reportar primero, editar solo cuando se pida. El script nunca edita el plan. Edítalo solo cuando la persona te pida que pongas su pull request en él.
2. Editar solo los elementos de la persona. Deja los elementos de otras personas y la línea as_of en paz. Los pull requests abiertos entonces no editan todas las mismas líneas.
3. No marcar elementos como built a menos que la persona ejecute el reseteo semanal. Una persona lo hace una vez a la semana, después de que el pull request se fusiona. Di "fusionado, listo para el reseteo semanal" en su lugar.
4. Nunca inventar un estado. Un elemento es pr solo cuando un pull request abierto realiza ese trabajo. Cuando no puedas determinar a qué caja pertenece un pull request, pregunta.
5. Nunca confirmar la página HTML en la rama principal. La Action diaria la mantiene en su propia rama dashboard. Una página que construyas manualmente va en una carpeta temporal fuera del repositorio (<directorio temporal> a continuación).

Configurarlo en un repositorio

Pregunta, de una sola vez, antes de escribir nada:

• ¿El equipo quiere un plan? Si es así, ¿dónde (por defecto docs/plan.yaml), y ya existe uno? Cualquier archivo en el formato anterior funciona, por lo que uno existente puede permanecer.
• ¿A qué hora debería reconstruirse? La Action usa UTC; por defecto 11:00 UTC diario.

Luego, desde la carpeta raíz del repositorio:

python SCRIPT init                                   # scripts + Action diaria
python SCRIPT init --with-plan                       # ... y un docs/plan.yaml de inicio
python SCRIPT init --plan ruta/al/plan.yaml          # ... usando un plan existente

init escribe .github/dashboard/ (los scripts) y .github/workflows/dashboard.yml, y se niega a reemplazar archivos que existen. Luego:

1. Construye la página una vez localmente (siguiente sección) y muéstrala, para que la persona la vea funcionar.
2. Si escribiste un plan de inicio, complétalo con la persona: grupos, cajas, responsables y una lista people que mapee cada nombre de responsable con su inicio de sesión de GitHub.
3. Diles qué confirmar (los archivos que escribió init y el plan), y que después de que llegue a la rama predeterminada pueden ejecutarlo de inmediato desde la pestaña Acciones ("Dashboard", luego "Ejecutar flujo de trabajo").
4. Diles cómo verlo cada mañana: git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html, luego abre dashboard.html. Para un repositorio público, pueden activar GitHub Pages para la rama dashboard y obtener una dirección web.

Si la Action falla con "Permiso denegado" al enviar, el repositorio u organización limita lo que las Actions pueden hacer: Configuración → Acciones → General → Permisos de flujo de trabajo, "Lectura y escritura". La persona, no tú, cambia esa configuración.

Configurar una lista de vigilancia (varios repositorios)

Pregunta, de una sola vez: qué repositorios vigilar (como propietario/nombre), si alguno guarda su plan en un lugar diferente a docs/plan.yaml, qué repositorio de ellos debe contener la lista de vigilancia (un repositorio nuevo vacío está bien), y a qué hora reconstruir (UTC).

Antes de escribir nada, construye las páginas una vez para que la persona las vea:

python SCRIPT watch --list <directorio temporal>/watchlist.yaml --out <directorio temporal>/radar

Abre index.html en esa carpeta. Un repositorio que no se puede leer muestra su error en su fila sin detener a los demás: generalmente un error tipográfico en el nombre o un repositorio privado.

Luego, en el repositorio que contendrá la lista:

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

Escribe los repositorios de la persona en watchlist.yaml, luego diles:

1. Qué confirmar (los archivos que escribió init --watch), y que una vez que llegue a la rama predeterminada pueden ejecutarlo de inmediato desde la pestaña Acciones ("Radar", luego "Ejecutar flujo de trabajo").
2. Los repositorios privados necesitan un token. La Action puede leer repositorios públicos y su propio repositorio, nada más. Para vigilar repositorios privados, la persona crea un token de GitHub que pueda leerlos y lo guarda como un secreto llamado RADAR_TOKEN en el repositorio vigilante (Configuración → Secretos y variables → Acciones). Ellos mismos hacen esto; nunca pidas el token ni lo pegues en ningún lado.
3. Cómo verlo cada mañana: mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar, luego abre radar/index.html.

Para añadir o eliminar un repositorio más tarde, edita watchlist.yaml; nada más cambia.

Actualizar una copia de los scripts en un repositorio

init copia los scripts en el repositorio, por lo que un repositorio sigue ejecutando la versión que recibió hasta que alguien la actualice. Cuando la persona pida actualizar repo-radar en un repositorio, o los scripts de esta habilidad sean más nuevos que los del repositorio, ejecuta desde la carpeta raíz del repositorio:

python scripts/dashboard.py update        # copia de esta habilidad, no de .github/dashboard/

Reemplaza solo los scripts en .github/dashboard/ y dice cuáles cambiaron. La Action, la lista de vigilancia y el plan permanecen como la persona los dejó. Luego diles que confirmen .github/dashboard/.

Verlo ahora

python SCRIPT build --out <directorio temporal>/dashboard.html

Ejecútalo dentro del repositorio (o pasa --repo propietario/nombre). Escribe la página en una carpeta temporal fuera del repositorio, para que nunca se confirme, luego muéstrala a la persona. Explica lo que dice en palabras claras, comenzando con la tarjeta "Empezar aquí" y cualquier etiqueta amarilla en la pestaña Plan. Cada cuenta lleva su contexto: "12 de 16 pull requests abiertos necesitan revisión", no "12 necesitan revisión".

Dónde estoy (una persona, contra el plan)

Necesitas dos nombres: el nombre del responsable tal como lo escribe el plan, y el inicio de sesión de GitHub. Si la lista people del plan tiene el inicio de sesión con el que gh ha iniciado sesión, el script encuentra el nombre por sí mismo. De lo contrario pregunta, y pasa --owner "<Nombre>". Pasa --login solo cuando la persona pregunta sobre otra persona.

Ejecútalo dos veces cuando la persona está en una rama de pull request. Main muestra lo que el equipo ve hoy; la rama muestra lo que cambiará este pull request:

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

El informe tiene cuatro tablas:

Tabla	Qué le dice a la persona
Tus cajas	Por cada caja de la que son responsables o tienen un pull request: cuántos elementos están construidos, simulados, en un PR, faltantes
Elementos aún faltantes	Su próximo trabajo, caja por caja
Elementos marcados como pr, verificados contra GitHub	Un PR abierto no necesita nada. Un PR fusionado está listo para el reseteo semanal. Un PR cerrado sin fusionar significa que el elemento debería volver a missing
Tus pull requests abiertos sin elemento en el plan	Trabajo que el plan aún no muestra

Explícalo en este orden: qué está hecho y en revisión; qué pull requests faltan en el plan y a qué caja probablemente pertenece cada uno; cualquier elemento cuyo pull request se cerró sin fusionar; el primer elemento faltante como la próxima tarea probable.

Poner un pull request en el plan (solo cuando se pida)

Trabaja en la rama del pull request de la persona, no en main.

1. Encuentra el número del pull request: gh pr view --json number,title.
2. Encuentra el elemento que construye ese pull request. Lee las cajas de la persona en el plan.
   • Si un elemento ya describe el trabajo, cambia su estado a pr y añade pr: <número>.
   • Si ningún elemento lo hace, añade uno a la caja correcta: {status: pr, pr: <número>, text: "<lo que construye>"}. Mantén text breve y claro. Pregunta a la persona qué caja, cuando no sea obvio.
3. Verifica que el plan aún se carga: python SCRIPT build --out <directorio temporal>/check.html. Se detiene con un mensaje que nombra el error si no.
4. Ejecuta me nuevamente. El pull request debería estar ahora bajo "Elementos marcados como pr", no bajo "sin elemento en el plan".
5. Confirma el archivo de plan en el pull request de la persona.

Reseteo semanal (solo para la persona que lo hace)

Construye la página en main, o ejecuta me --ref origin/main una vez por cada responsable. Luego, en un solo pull request:

• Marca cada elemento cuyo pull request se fusionó como built, o simulated si el trabajo fusionado es un stub, un fake o un esqueleto. La pestaña Plan etiqueta estos como "fusionados".
• Vuelve a poner cada elemento cuyo pull request se cerró sin fusionar a missing.
• Enumera los pull requests abiertos sin elemento (la última sección de la pestaña Plan) en la descripción del pull request, para que sus responsables los coloquen. No adivines sus cajas.
• Establece as_of al commit de main y la fecha contra la que verificaste.

Sin acceso a la red

python SCRIPT fetch --out data.json guarda lo que GitHub dijo; build --data data.json y me --data data.json luego funcionan sin conexión. Las pruebas usan esto.