provisioning/provisioning-outreach

Fork 0

Jesús Pérez 3666748bd9

outreach: clean-start baseline — public reach surface (constellation materialization)

2026-07-09 21:58:36 +01:00

11 KiB

Raw Permalink Blame History

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

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

Posibles Causas y Soluciones

A. Versión de Nushell Incorrecta

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

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

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

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

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

Soluciones

A. Puerto Ocupado

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

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

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

# Corregir permisos si necesario
chmod -R 755 dist/

D. Python No Disponible

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

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

Diagnóstico y Soluciones

A. Configuración Demasiado Conservadora

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

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

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

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

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

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

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

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

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

Soluciones

A. Archivos No Existen

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

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

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

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

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

Soluciones

A. Script No Ejecutable

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

# Verificar permisos
ls -la dist/deploy.sh

B. Variables de Entorno No Configuradas

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

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

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

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

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

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

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

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

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

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

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

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!

11 KiB Raw Permalink Blame History

Troubleshooting Guide - Build System Provisioning

🆘 Problemas Más Comunes

1. ❌ Build Falla

Síntomas

Posibles Causas y Soluciones

2. 🌐 Servidor No Inicia

Síntomas

Soluciones

3. 📄 Archivos Muy Grandes

Síntomas

Diagnóstico y Soluciones

4. 🎨 Animaciones Rotas

Síntomas

Diagnóstico y Soluciones

5. 🔧 File Watching No Funciona

Síntomas

Soluciones

6. 📦 Deploy Falla

Síntomas

Soluciones

🔍 Herramientas de Diagnóstico

Verificación Rápida del Sistema

Logging Verbose para Debug

Test de Conectividad

📋 Checklist de Troubleshooting

Antes de Reportar Bug

Información para Bug Report

🚨 Problemas Críticos y Recovery

Corrupción de Archivos Fuente

Build System Completamente Roto

Recovery de Emergency

📞 Recursos de Ayuda

Documentación

Comandos de Ayuda Útiles

Debugging Avanzado

11 KiB

Raw Permalink Blame History