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.

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

cargo install pandora-kit

Desarrolladores (compila desde código)

git clone https://gitlab.com/SpicyDogWings/hefesto
cd hefesto
./dev-install.sh

---

Subcomandos

Comando	Descripción	Salida
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.

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"

Flag	Default	Descripción
-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.

# 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

Flag	Default	Descripción
-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.

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)

Flag	Default	Descripción
-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.

# 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

Flag	Default	Descripción
-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.

pan log info "Iniciando compilación"
pan log error "Falló la conexión"
pan log warn "Archivo no encontrado"
pan log debug "x = 42"

Nivel	Color	Uso
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.

NAME=$(pan input -p "Tu nombre")
EMAIL=$(pan input -p "Email" -v "user@example.com")

Flag	Default	Descripción
-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.

# 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

| Flag | Default | Descripción |
|------|---------|-------------|
| `-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:**

| Modo | Enter | Space | `o` en dir |
|------|-------|-------|------------|
| (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.

Flag	Default	Descripción
-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.

pan update
pan update --force          # Re-instalar aunque sea la misma versión

---

Controles globales

Teclado

Tecla	confirm	choose	filter	spin	input	file	menu
↑ / 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).