provisioning-outreach/presentations/rust-laspalmas-250926/auroraframe/docs/troubleshooting.md

# Troubleshooting Guide - Build System Provisioning

Guía completa para resolver problemas comunes del sistema de build del poster Provisioning.

## 🆘 Problemas Más Comunes

### 1. ❌ Build Falla

#### Síntomas

```rust
bash
nu scripts/dev.nu build
# Error: command not found / syntax error
```

#### Posibles Causas y Soluciones

**A. Versión de Nushell Incorrecta**

```nushell
bash
# Verificar versión
nu --version
# Debe ser 0.105.2 o superior

# Si es menor, actualizar:
# - Usando cargo: cargo install nu
# - Usando homebrew: brew install nushell
# - Desde releases: https://github.com/nushell/nushell/releases
```

**B. Archivos de Configuración Corruptos**

```toml
bash
# Verificar configuración
nu -c "open config/build.config.nu"

# Si da error, regenerar configuración:
cp config/build.config.nu config/build.config.nu.backup
# Luego recrear manualmente o desde template
```

**C. Dependencias Missing**

```rust
bash
# Verificar que todos los scripts existen
ls scripts/
# Debe mostrar: build.nu, dev.nu, prod.nu, optimize-*.nu, utils.nu

# Verificar permisos
chmod +x scripts/*.nu
```

**D. Working Directory Incorrecto**

```rust
bash
# Verificar que estás en directorio correcto
pwd
# Debe terminar en .../poster/

# Verificar estructura
ls
# Debe mostrar: src/, scripts/, config/, docs/
```

---

### 2. 🌐 Servidor No Inicia

#### Síntomas

```rust
bash
nu scripts/dev.nu --port 3000
# Error: port in use / server won't start
```

#### Soluciones

**A. Puerto Ocupado**

```rust
bash
# Verificar qué usa el puerto
lsof -i :3000
# O en Linux: netstat -tlnp | grep 3000

# Matar proceso que usa el puerto
kill -9 <PID>

# O usar puerto diferente
nu scripts/dev.nu --port 8080
```

**B. Firewall Bloqueando**

```rust
bash
# macOS: verificar firewall
sudo pfctl -sr | grep 3000

# Linux: verificar iptables
sudo iptables -L | grep 3000

# Permitir puerto temporalmente
# macOS: System Preferences → Security → Firewall
# Linux: sudo ufw allow 3000
```

**C. Permisos Insuficientes**

```rust
bash
# Verificar permisos del directorio dist
ls -la dist/

# Corregir permisos si necesario
chmod -R 755 dist/
```

**D. Python No Disponible**

```rust
bash
# El servidor usa Python, verificar instalación
python3 --version
# O: python --version

# Si no está instalado:
# macOS: brew install python3
# Linux: sudo apt install python3
# Windows: descargar desde python.org
```

---

### 3. 📄 Archivos Muy Grandes

#### Síntomas

```rust
bash
nu scripts/prod.nu --analyze
# Total size: 150KB+ (debería ser ~70KB)
```

#### Diagnóstico y Soluciones

**A. Configuración Demasiado Conservadora**

```toml
bash
# Verificar configuración actual
grep -A 10 "inline_css_max_size" config/build.config.nu
grep -A 5 "svg_precision" config/build.config.nu

# Hacer más agresiva
# Editar config/build.config.nu:
export const config = {
    inline_css_max_size: 5120,     # 5KB en lugar de 10KB
    svg_precision: 1,              # Menos precisión = menor tamaño
    critical_css_modules: 1,       # Menos CSS inline
    css_minify: true,              # Asegurar minificación
    svg_optimize: true             # Asegurar optimización SVG
}
```

**B. SVGs Sin Optimizar**

```rust
bash
# Verificar tamaños SVG
du -h src/assets/svg/*.svg

# Si son muy grandes (>20KB), optimizar manualmente:
# Instalar SVGO: npm install -g svgo
# svgo src/assets/svg/symbols.svg

# O ajustar precisión en config
svg_precision: 0  # Mínima precisión
```

**C. CSS Sin Minificar**

```rust
bash
# Verificar que minificación está habilitada
grep "css_minify" config/build.config.nu

# Verificar resultado
head -10 dist/assets/css/main.min.css
# Debe ser una línea compacta, no con espacios
```

**D. Archivos Duplicados**

```rust
bash
# Verificar que no hay duplicados
find dist/ -name "*.css" | wc -l
# Debe ser 1

find dist/ -name "*.svg" | wc -l
# Debe ser 2-3 máximo

# Limpiar y rebuild si hay duplicados
nu scripts/dev.nu clean
nu scripts/prod.nu
```

---

### 4. 🎨 Animaciones Rotas

#### Síntomas

- Logo no gira
- Texto sin gradiente
- Línea progresiva no aparece

#### Diagnóstico y Soluciones

**A. SVG Animado Movido a Archivo Externo**

```rust
bash
# Las animaciones CSS/SVG DEBEN estar inline en HTML
# Verificar que symbols.svg está embebido:
grep -A 5 "symbol.*logo-black" src/index.html

# Si no está, el build movió incorrectamente el SVG
# Los SVGs animados deben permanecer inline
```

**B. CSS Crítico Muy Limitado**

```rust
bash
# Animaciones necesitan estar en CSS crítico
# Editar config/build.config.nu:
critical_css_modules: 3,  # Incluir módulo de animaciones

# O ajustar threshold
inline_css_max_size: 15360,  # 15KB para incluir más CSS
```

**C. Minificación Rompió CSS**

```rust
bash
# Verificar CSS minificado
head -10 dist/assets/css/main.min.css

# Si las animaciones se ven incorrectas, debug:
# Deshabilitar minificación temporalmente
# Editar config/build.config.nu:
css_minify: false

# Rebuild y verificar
nu scripts/dev.nu build
```

**D. JavaScript Deshabilitado/Faltante**

```rust
bash
# El poster no debería necesitar JS
# Verificar que no hay dependencias JS accidentales:
grep -r "script" src/index.html
grep -r "javascript" src/

# Si hay JS, eliminar o hacer opcional
```

---

### 5. 🔧 File Watching No Funciona

#### Síntomas

```rust
bash
nu scripts/dev.nu --watch
# No detecta cambios en archivos
```

#### Soluciones

**A. Archivos No Existen**

```rust
bash
# Verificar que archivos watched existen
ls src/index.html
ls src/assets/css/modules/*.css
ls src/assets/svg/*.svg

# Crear archivos faltantes si necesario
touch src/assets/css/main.css
```

**B. Permisos de Lectura**

```rust
bash
# Verificar permisos
ls -la src/
ls -la src/assets/css/modules/

# Corregir permisos
chmod -R 644 src/
chmod 755 src/ src/assets/ src/assets/css/ src/assets/css/modules/
```

**C. Demasiados Archivos**

```rust
bash
# Verificar número de archivos watched
find src/ -name "*.css" -o -name "*.html" -o -name "*.svg" | wc -l

# Si son muchos (>50), puede haber límites del sistema
# Reducir scope de watching o aumentar límites:
ulimit -n 1024
```

**D. Editor Locks**

```rust
bash
# Algunos editores crean locks temporales
# Verificar archivos temporales
find src/ -name "*.tmp" -o -name "*~" -o -name "*.swp"

# Limpiar archivos temporales
find src/ -name "*.tmp" -delete
find src/ -name "*~" -delete
find src/ -name "*.swp" -delete
```

---

### 6. 📦 Deploy Falla

#### Síntomas

```rust
bash
./dist/deploy.sh
# Permission denied / connection failed
```

#### Soluciones

**A. Script No Ejecutable**

```rust
bash
# Hacer script ejecutable
chmod +x dist/deploy.sh

# Verificar permisos
ls -la dist/deploy.sh
```

**B. Variables de Entorno No Configuradas**

```toml
bash
# Verificar variables
echo $DEPLOY_HOST
echo $DEPLOY_PATH
echo $DEPLOY_USER

# Configurar si están vacías
export DEPLOY_HOST="tu-servidor.com"
export DEPLOY_PATH="/var/www/provisioning-poster"
export DEPLOY_USER="deploy"

# O editar script directamente
nano dist/deploy.sh
```

**C. SSH Keys/Permisos**

```rust
bash
# Verificar conexión SSH
ssh $DEPLOY_USER@$DEPLOY_HOST

# Si falla, configurar SSH keys
ssh-keygen -t rsa
ssh-copy-id $DEPLOY_USER@$DEPLOY_HOST
```

**D. Directorio Destino No Existe**

```rust
bash
# Crear directorio en servidor
ssh $DEPLOY_USER@$DEPLOY_HOST "mkdir -p $DEPLOY_PATH"

# Verificar permisos de escritura
ssh $DEPLOY_USER@$DEPLOY_HOST "touch $DEPLOY_PATH/test.txt && rm $DEPLOY_PATH/test.txt"
```

---

## 🔍 Herramientas de Diagnóstico

### Verificación Rápida del Sistema

```rust
bash
#!/usr/bin/env nu
# diagnosis.nu - Script de diagnóstico rápido

# Verificar prerequisitos
echo "=== DIAGNÓSTICO RÁPIDO ==="

echo "1. Nushell version:"
nu --version

echo "2. Directorio actual:"
pwd

echo "3. Estructura de archivos:"
ls

echo "4. Scripts disponibles:"
ls scripts/

echo "5. Configuración:"
try { open config/build.config.nu | get config } catch { "Error leyendo config" }

echo "6. Espacio en disco:"
df -h .

echo "7. Permisos:"
ls -la scripts/dev.nu

echo "=== FIN DIAGNÓSTICO ==="
```

### Logging Verbose para Debug

```rust
bash
# Debug build completo
nu scripts/dev.nu build --verbose 2>&1 | tee build-debug.log

# Debug servidor
nu scripts/dev.nu --verbose --port 8080 2>&1 | tee server-debug.log

# Analizar logs
grep -i error build-debug.log
grep -i warning build-debug.log
```

### Test de Conectividad

```rust
bash
# Test de puertos
nc -zv localhost 8080
nc -zv localhost 3000

# Test de archivos servidos
curl -I http://localhost:8080/index.html
curl -I http://localhost:8080/assets/css/main.min.css
```

---

## 📋 Checklist de Troubleshooting

### Antes de Reportar Bug

- [ ] Verificar versión Nushell (≥0.105.2)
- [ ] Confirmar directorio correcto (poster/)
- [ ] Revisar permisos de archivos
- [ ] Probar con puerto diferente
- [ ] Limpiar build cache (`nu scripts/dev.nu clean`)
- [ ] Revisar logs con --verbose
- [ ] Verificar espacio en disco suficiente

### Información para Bug Report

```rust
bash
# Recopilar información del sistema
echo "Nushell: $(nu --version)"
echo "OS: $(uname -a)"
echo "PWD: $(pwd)"
echo "Config: $(open config/build.config.nu | get config)"
echo "Files: $(ls)"
echo "Disk space: $(df -h .)"
```

---

## 🚨 Problemas Críticos y Recovery

### Corrupción de Archivos Fuente

```rust
bash
# Backup automático (ejecutar regularmente)
tar -czf backup-$(date +%Y%m%d).tar.gz src/ config/

# Recovery desde backup
tar -xzf backup-YYYYMMDD.tar.gz

# O recovery desde git (si está en control de versiones)
git checkout HEAD -- src/ config/
```

### Build System Completamente Roto

```rust
bash
# Reset completo del sistema
rm -rf dist/ node_modules/ .cache/

# Verificar integridad de scripts
ls -la scripts/
md5sum scripts/*.nu  # O shasum en macOS

# Re-download scripts si necesario
# (desde repository o backup)
```

### Recovery de Emergency

```rust
bash
# Versión mínima de servidor HTTP sin build system
cd src/
python3 -m http.server 8080

# Acceder a http://localhost:8080
# Funcionalidad reducida pero poster visible
```

---

## 📞 Recursos de Ayuda

### Documentación

- **Nushell Book**: <https://www.nushell.sh/book/>
- **Build System README**: ../README.md
- **Interactive Guide**: docs/howto/interactive-guide.html

### Comandos de Ayuda Útiles

```rust
bash
# Ayuda del sistema
nu scripts/dev.nu help
nu scripts/prod.nu help

# Ayuda de Nushell
nu --help
help commands

# Manual de funciones específicas
help open
help glob
help ls
```

### Debugging Avanzado

```rust
bash
# Modo debug de Nushell
nu --debug scripts/dev.nu build

# Profiling de performance
time nu scripts/prod.nu

# Trace de system calls (Linux/macOS)
strace -e trace=file nu scripts/dev.nu build  # Linux
dtruss -f nu scripts/dev.nu build            # macOS
```

¡Con esta guía deberías poder resolver la mayoría de problemas del sistema de build!