# 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

| 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`.

```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"
```

| 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.

```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
```

| 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.

```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)
```

| 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.

```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
```

| 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.

```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"
```

| 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.

```bash
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.

```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

| 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`.

```bash
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).
