# Pandora
**CLI toolkit con popups TUI interactivos para shell scripts y flujos de terminal.**
Cada subcomando abre una interfaz en el terminal, el usuario interactúa con teclado o ratón, y el resultado se imprime en stdout con un código de salida. Ideal para integración en scripts donde necesitas input visual sin dependencias web.
```bash
pan confirm -m "¿Eliminar archivo?" && rm archivo
TARGET=$(pan choose -t "Entorno" dev staging prod)
pan spin -t "Compilando" -- cargo build --release
```
---
## Instalación
### Desde crates.io
```bash
cargo install pandora-kit
```
### Desarrolladores (compila desde código)
```bash
git clone https://gitlab.com/SpicyDogWings/hefesto
cd hefesto
./dev-install.sh
```
---
## Subcomandos
| `confirm` | Popup de confirmación sí/no | exit 0 / 1 |
| `choose` | Selector de una lista de ítems | ítems en stdout |
| `filter` | Selector con búsqueda por texto en tiempo real | ítems en stdout |
| `spin` | Spinner animado mientras se ejecuta un comando | exit del comando |
| `log` | Línea de log formateada y coloreada | texto a stdout |
| `input` | Captura de texto libre | texto a stdout |
| `file` | Explorador interactivo de archivos | paths en stdout |
| `menu` | Menú jerárquico desde JSON o formato plano | path en stdout |
| `update` | Auto-actualización desde crates.io | mensajes en stdout |
---
### `confirm` — Confirmación
Popup compacto con título, mensaje, y dos botones. Variantes de color: `success`, `warning`, `danger`, `none`.
```bash
pan confirm -m "¿Eliminar archivo?" -v danger && rm archivo
if pan confirm -m "¿Proceder?"; then
make deploy
fi
pan confirm -t "Atención" -m "¿Continuar?" -y "Sí" -n "No"
```
| `-m` | `"¿Deseas continuar?"` | Mensaje del cuerpo |
| `-t` | `"Confirmación"` | Título del popup |
| `-v` | `"warning"` | Variante de color |
| `-y` | `"Confirmar"` | Texto del botón confirmar |
| `-n` | `"Cancelar"` | Texto del botón cancelar |
| `-W` | `0` (auto) | Ancho del popup |
| `-H` | `0` (auto) | Alto del popup |
---
### `choose` — Selección de lista
Selector de ítems con soporte single y multi-select. Los ítems se pasan como argumentos posicionales.
```bash
# Single
ENV=$(pan choose dev staging prod)
# Multi
pan choose -m apple orange banana grape
# Con límite de selección
pan choose -m -M 3 opcion1 opcion2 opcion3 opcion4
# Tamaño explícito
pan choose -W 60 -H 15 -t "Archivos" a.txt b.txt c.txt
```
| `-t` | `"Seleccionar"` | Título |
| `-m` | off | Multi-select con Space |
| `-M` | ilimitado | Máximo de selecciones (con `--multi`) |
| `-W` | `0` (auto) | Ancho |
| `-H` | `0` (auto) | Alto |
Salida: cada ítem seleccionado en una línea de stdout.
---
### `filter` — Selección con búsqueda
Igual que `choose` pero con un campo de texto integrado para filtrar los ítems en tiempo real.
```bash
pan filter ubuntu debian fedora arch opensuse
pan filter -m -t "Lenguajes" rust go python javascript typescript
pan filter -W 50 -H 20 $(ls *.txt)
```
| `-t` | `"Filtrar"` | Título |
| `-m` | off | Multi-select |
| `-M` | ilimitado | Máximo de selecciones |
| `-W` | `0` (auto) | Ancho |
| `-H` | `0` (auto) | Alto |
---
### `spin` — Spinner con comando
Ejecuta un comando mientras muestra un spinner animado y opcionalmente su salida en tiempo real.
```bash
# Comando simple
pan spin -t "Instalando" -c "npm install"
# Multi-word con --
pan spin -t "Compilando" -- cargo build --release
# Salida en tiempo real
pan spin -t "Descargando" -v -- curl -O https://example.com/bigfile
# Esperar confirmación al terminar
pan spin -t "Actualizando" -w -c "apt upgrade -y"
# Animación personalizada
pan spin -t "Cargando" -a bounce
# Mostrar logs al finalizar
pan spin -t "Backup" -l -- tar -czf backup.tar.gz ./data
```
| `-t` | `"Procesando..."` | Título |
| `-c` | — | Comando a ejecutar (string) |
| `--` | — | Separador para comandos multi-palabra |
| `-v` | off | Mostrar salida en tiempo real |
| `-l` | off | Mostrar logs en stdout al finalizar |
| `-w` | off | Esperar Enter antes de cerrar |
| `-a` | `"dots"` | Animación: dots, line, dots2, bounce, pulse, arrows, square, clock |
| `-W` | `0` (auto) | Ancho |
| `-H` | `0` (auto) | Alto |
El spinner muestra ✓ (verde) si el comando sale con 0, ✗ (rojo) en caso contrario. Exit code = el del comando ejecutado.
> **⚠️** Los comandos interactivos (que piden password o confirmación) **no funcionan** con `pandora spin` porque el comando se ejecuta con pipes cerrados.
---
### `log` — Log coloreado
Imprime una línea de log con timestamp, nivel y mensaje coloreado.
```bash
pan log info "Iniciando compilación"
pan log error "Falló la conexión"
pan log warn "Archivo no encontrado"
pan log debug "x = 42"
```
| `info` | Cyan | Información general |
| `warn` | Amarillo | Advertencias |
| `error` | Rojo | Errores |
| `debug` | Gris | Depuración |
---
### `input` — Entrada de texto
Popup para capturar texto del usuario. Soporta edición básica, placeholder, y valor inicial.
```bash
NAME=$(pan input -p "Tu nombre")
EMAIL=$(pan input -p "Email" -v "user@example.com")
```
| `-p` | `"Input"` | Mensaje / título |
| `-v` | `""` | Valor inicial |
| `-W` | `0` (auto) | Ancho |
Exit 0 → imprime el texto. Exit 1 → cancelado.
---
### `file` — Explorador de archivos
Navegación por directorios con iconos (`📁`/`📄`), filtro por texto, selección simple o múltiple.
```bash
# Navegar y seleccionar archivo
pan file
# Desde un directorio específico
pan file /home/user/Documents
# Seleccionar directorio (Enter = cwd actual, Space = subdirectorio)
pan file -d
# Multi-select de archivos
pan file -m
| `-d` | off | Modo selección de directorios |
| `-m` | off | Multi-select |
| `-M` | ilimitado | Máximo de selecciones |
| `-W` | `0` (auto) | Ancho |
**Comportamiento según flags:**
| (ninguno) | archivo → selecciona, dir → entra | — | entra al dir |
| `--dirs` | selecciona el dir actual | selecciona el dir bajo el cursor | entra al dir |
| `--multi` | confirma toggled | toggle archivos | entra al dir |
| `--multi --dirs` | confirma toggled | toggle directorios | entra al dir |
---
### `menu` — Menú jerárquico
Menú en árbol con ramas expandibles/colapsables. Soporta entrada JSON (con ids) o formato plano (paths separados por `/`).
```bash
# Archivo JSON (auto-detectado)
pan menu menu.json
# Formato plano (paths por línea)
printf 'Archivo/Nuevo/Documento\nArchivo/Abrir\n' | pan menu
# Archivo plano
pan menu menu.txt
# Tamaño explícito
pan menu menu.json -W 60 -H 20 -t "Proyectos"
**Formato JSON:**
```json
[
{ "id": 1, "text": "Archivo", "children": [
{ "id": 2, "text": "Nuevo", "children": [
{ "id": 3, "text": "Documento" }
]},
{ "id": 4, "text": "Abrir" }
]}
]
```
**Formato plano (una ruta por línea):**
```
Archivo/Nuevo/Documento
Archivo/Abrir
Editar/Deshacer
```
Salida: ruta completa desde la raíz, segmentos unidos por `/`. Ej: `Archivo/Nuevo/Documento`.
| `-f` | `auto` | Formato: auto, json, plano |
| `-t` | `"Menú"` | Título |
| `-W` | `0` (auto) | Ancho |
| `-H` | `0` (auto) | Alto |
### `update` — Auto-actualización
Actualiza pandora a la última versión mediante `cargo install pandora-kit`.
```bash
pan update
pan update --force # Re-instalar aunque sea la misma versión
```
---
## Controles globales
### Teclado
| `↑` / `k` | — | ↑ | ↑ | ↑ (verbose) | — | ↑ | ↑ |
| `↓` / `j` | — | ↓ | ↓ | ↓ (verbose) | — | ↓ | ↓ |
| `Enter` | Confirmar | Confirmar | Confirmar | — | Confirmar | Seleccionar / entrar | Expandir / seleccionar |
| `Esc` | Cancelar | Cancelar | Cancelar | Salir | Cancelar | Salir / cerrar filtro | Cancelar |
| `Space` | — | Toggle (multi) | Toggle (multi) | — | — | Toggle / seleccionar dir | Expandir |
| `←` / `Backspace` | — | — | — | — | ← cursor | Dir padre | Colapsar |
| `→` | — | — | — | — | → cursor | — | Expandir |
| `/` | — | — | — | — | — | Activar filtro | — |
| `Tab` | — | ↓ | ↓ | — | — | — | ↓ |
| `Shift+Tab` | — | ↑ | ↑ | — | — | — | ↑ |
| `g` `g` | — | Primer item | — | Primer línea (verbose) | — | Primer item | Primer item |
| `G` | — | Último item | — | Última línea (verbose) | — | Último item | Último item |
| `o` | — | — | — | — | — | Entrar directorio | — |
| `y` / `Y` | Sí | — | — | — | — | — | — |
| `n` / `N` | No | — | — | — | — | — | — |
| `q` | — | — | — | Salir | Cancelar | — | Cancelar |
| `Home` / `End` | — | — | Cursor filtro | — | Inicio / Fin | — | — |
| `Ctrl`+`c` | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ |
### Ratón
Todos los popups con borde o barra de título se pueden **arrastrar** con el ratón.
- **Click en botón** (`confirm`): confirma o cancela.
- **Click en ítem** (`choose`, `filter`, `menu`): selecciona/togglea.
- **Drag en borde o título**: mueve el popup.
---
## Plataforma
Solo **Linux x86_64**. Requiere un terminal que soporte modo raw (cualquier terminal moderna).