🎯 GitBoard - GitHub Kanban TUI

Terminal User Interface para visualizar y gestionar GitHub Projects V2 desde tu terminal

GitBoard es una aplicación TUI (Terminal User Interface) rápida y eficiente que te permite visualizar tus repositorios, proyectos y tableros Kanban de GitHub directamente desde la terminal, optimizada para bajo consumo de memoria.

✨ Características

• 📊 Vista de Kanban: Visualiza todos los items de tus GitHub Projects con información completa
• 🗂️ Gestión de Repositorios: Lista tus repositorios con estadísticas y detalles
• 🌳 Explorador de Código: Visualiza el árbol de archivos de tus repositorios
• 📝 Historial de Commits: Muestra el log de commits en formato de árbol visual
• 🏷️ Información Detallada: Assignees, labels, descripción, fechas y más
• ⚡ Optimizado: Bajo consumo de RAM (~50-80 MB)
• 🎨 Interfaz Intuitiva: Navegación con teclado fácil y rápida

📸 Vista Previa

Panel Principal

┌─────────────────────────────────────────────────────────────┐
│ Repositorios     │ Projects        │ Kanban                 │
├──────────────────┼─────────────────┼────────────────────────┤
│ repo1            │ Project Alpha   │ Estado │ Título │ ...  │
│ repo2            │ Project Beta    │ Todo   │ Fix... │ ...  │
│ repo3            │ Project Gamma   │ Done   │ Add... │ ...  │
└──────────────────┴─────────────────┴────────────────────────┘

Vista de Detalles de Item

• Información completa del issue/PR
• Assignees y colaboradores
• Labels y tags
• Descripción con formato
• Fechas de creación y actualización

Vista de Repositorio

• Branches disponibles
• Árbol de archivos con iconos
• Log de commits con grafo visual

🚀 Instalación

Requisitos

• Python 3.13 o superior
• uv (gestor de paquetes recomendado)

Pasos

1. Clona el repositorio

   git clone https://github.com/tu-usuario/gitboard.git
   cd gitboard

2. Instala las dependencias

   # Con uv (recomendado)
   uv sync
   
   # O con pip
   pip install -r requirements.txt

🔑 Configuración del Token de GitHub

GitBoard requiere un token de acceso personal de GitHub para acceder a tus repositorios y proyectos.

Crear un GitHub Personal Access Token (Classic)

1. Ve a GitHub Settings

   • Accede a github.com
   • Click en tu avatar (esquina superior derecha) → Settings

2. Accede a Developer Settings

   • Baja hasta el final del menú lateral
   • Click en Developer settings

3. Genera un nuevo token

   • Click en Personal access tokens → Tokens (classic)
   • Click en Generate new token → Generate new token (classic)

4. Configura el token

   • Note: Escribe un nombre descriptivo (ej: "GitBoard TUI")
   • Expiration: Selecciona la duración (recomendado: 90 días o No expiration)

5. Selecciona los permisos (scopes) necesarios:

   ✅ Permisos Requeridos:

   ✓ repo                    (Acceso completo a repositorios)
     ✓ repo:status
     ✓ repo_deployment
     ✓ public_repo
     ✓ repo:invite
     ✓ security_events
   
   ✓ read:org                (Leer información de organizaciones)
   
   ✓ read:project            (Leer GitHub Projects)
   

6. Genera y copia el token

   • Click en Generate token al final de la página
   • ⚠️ IMPORTANTE: Copia el token inmediatamente (solo se muestra una vez)

Configurar el Token en GitBoard

1. Crea el archivo de configuración

   cp .env.example .env

2. Edita el archivo .env

   nano .env
   # O usa tu editor preferido

3. Agrega tu token

   GITHUB_TOKEN=ghp_tuTokenAquí1234567890abcdefghijklmn

4. Guarda y cierra el archivo

⚠️ Seguridad: Nunca compartas tu token o lo incluyas en commits. El archivo .env está en .gitignore por defecto.

📖 Uso

Iniciar la aplicación

# Con uv
uv run python app.py

# O directamente
python app.py

Controles de Teclado

Tecla	Acción
q	Salir de la aplicación
r	Recargar datos
i o Enter	Ver información detallada
Tab	Cambiar entre paneles
↑ ↓	Navegar entre items
← →	Navegar entre columnas
Esc	Cerrar ventanas modales

Navegación

1. Panel de Repositorios (izquierda)

   • Lista tus repositorios
   • Presiona i o Enter para ver detalles del repo

2. Panel de Projects (centro)

   • Lista tus GitHub Projects
   • Selecciona uno para ver su Kanban

3. Panel de Kanban (derecha)

   • Muestra todos los items del proyecto
   • Cada fila es un item con su información
   • Presiona i o Enter para ver detalles completos

🔧 Configuración Avanzada

Ajustar Límites de Datos

Puedes modificar los límites de consulta en kanbantui/repository.py:

# Cantidad de items a cargar
def list_repositories(self, per_page: int = 30)  # Repositorios
def list_projects(self, first: int = 20)         # Proyectos
def get_project_kanban(self, ..., item_limit: int = 50)  # Items de Kanban

Optimización de Memoria

GitBoard está optimizado para consumir poca RAM:

• Límites de consulta reducidos
• Limpieza automática de datos al cambiar de vista
• Renderizado eficiente sin estructuras temporales grandes

Consumo típico: 50-80 MB de RAM

🛠️ Tecnologías

• Textual: Framework TUI para Python
• Requests: Cliente HTTP
• GitHub API: GraphQL y REST v3

📝 Estructura del Proyecto

kanbanTUI/
├── app.py                    # Punto de entrada
├── kanbantui/
│   ├── api.py               # Cliente de GitHub API
│   ├── models.py            # Modelos de datos
│   ├── repository.py        # Lógica de negocio
│   └── ui/
│       ├── app.py           # Aplicación principal TUI
│       └── screens.py       # Pantallas modales
├── pyproject.toml           # Configuración del proyecto
├── .env.example             # Plantilla de configuración
└── README.md                # Este archivo

🤝 Contribuir

Las contribuciones son bienvenidas! Si encuentras un bug o tienes una sugerencia:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Textual por el excelente framework TUI
• GitHub por su API completa y bien documentada
• La comunidad de Python

📞 Soporte

Si tienes problemas o preguntas:

1. Revisa la documentación de GitHub API
2. Verifica que tu token tenga los permisos correctos
3. Asegúrate de tener acceso a los proyectos que intentas ver

---

Hecho con ❤️ y ☕ | Optimizado para desarrolladores que viven en la terminal