ca-archive/INSTALL.md

Guía de Instalación Rápida - Classic Add-ons Archive v3.0

Para Desarrolladores / Testing Local

Firefox

Opción 1: Carga temporal (recomendado para desarrollo)

1. Abre Firefox
2. Escribe en la barra de direcciones: about:debugging#/runtime/this-firefox
3. Click en "Cargar complemento temporal..."
4. Navega a la carpeta del proyecto y selecciona el archivo manifest.json

La extensión se instalará hasta que cierres Firefox.

Opción 2: Instalación sin firma (Firefox Developer/Nightly)

Firefox normal NO permite instalar extensiones sin firma. Usa una de estas versiones:

1. Firefox Developer Edition o Firefox Nightly:

   • Descarga: https://www.mozilla.org/firefox/developer/
   • Descarga: https://www.mozilla.org/firefox/nightly/

2. Deshabilitar verificación de firma:

   • Escribe en la barra: about:config
   • Acepta el riesgo
   • Busca: xpinstall.signatures.required
   • Cambia a false (doble click)

3. Instalar la extensión:

   # Empaquetar
   cd /home/ale/projects/firefox/ca-archive
   ./build.sh
   
   # O manualmente:
   zip -r ca-archive-3.0.xpi manifest.json background.js content/ skin/ -x "*.git*" -x "*~"
   

4. Arrastra el archivo .xpi a Firefox

⚠️ IMPORTANTE: Firefox normal (Release) NO acepta xpinstall.signatures.required=false. Solo funciona en Developer/Nightly/Unbranded.

Opción 3: Instalación permanente con firma AMO (distribución)

1. Obtener credenciales AMO: https://addons.mozilla.org/developers/addon/api/key/
2. Configurar en private-keys/firefox-amo-credentials.json
3. Firmar: ./build.sh --sign
4. Instalar el .xpi firmado resultante

Chrome / Edge / Brave

⚠️ PROBLEMA CONOCIDO: Manifest v2 deprecado en Chrome

Chrome está migrando a Manifest v3. Esta extensión usa Manifest v2 y puede:

• ✅ Funcionar en Edge/Brave (soporte extendido hasta ~2024-2025)
• ⚠️ Mostrar advertencias en Chrome
• ❌ Dejar de funcionar en Chrome 127+ (junio 2024)

Si Chrome rechaza el manifest:

1. Verifica la versión de Chrome: chrome://settings/help
2. Si es Chrome 127+, necesitas Manifest v3 (aún no implementado)
3. Alternativa temporal: Usa Microsoft Edge o Brave (soportan v2 más tiempo)

Modo desarrollador (sin empaquetar) - Solo Chrome <127:

1. Abre el navegador
2. Ve a: chrome://extensions/ (o edge://extensions/)
3. Activa el interruptor "Modo de desarrollador" (esquina superior derecha)
4. Click en "Cargar extensión sin empaquetar"
5. Selecciona la carpeta: /home/ale/projects/firefox/ca-archive

La extensión quedará instalada permanentemente en modo desarrollo.

Errores comunes en Chrome:

• "Manifest version 2 is deprecated":

  • ⚠️ Solo advertencia (aún funciona)
  • Chrome mostrará recordatorio hasta que migres a v3

• "Manifest version 2 is not supported":

  • ❌ Chrome 127+ bloquea v2 completamente
  • Solución: Usa Firefox, Edge o Brave
  • O espera: Implementación de Manifest v3 (pendiente)

Empaquetar para distribución:

cd /home/ale/projects/firefox/ca-archive

# Construir paquetes sin firmar
./build.sh

# O con firma (requiere configurar claves primero)
./scripts/generate-keys.sh  # Primera vez
./build.sh --sign           # Construir firmado

Para distribución con firma, ver SIGNING.md.

Verificación de Instalación

Después de instalar, deberías ver:

1. ✅ Icono de la extensión en la barra de herramientas
2. ✅ Click en el icono abre la página del catálogo
3. ✅ Mensaje de carga de base de datos (primera vez)
4. ✅ Navegación funcionando (categorías, búsqueda, etc.)

Troubleshooting

La base de datos no carga

Error: "Loading database for the first time. Please wait..."

Solución:

1. Asegúrate de tener la carpeta content/db/ con el archivo SQLite
2. Verifica que el archivo ca-archive-19030501.sqlite exista y no esté corrupto
3. Revisa la consola del navegador (F12 > Console) para errores específicos

El icono no aparece

Solución:

1. Refresca la página about:debugging o chrome://extensions/
2. Verifica que manifest.json tiene el campo browser_action correctamente
3. Revisa que las imágenes en skin/button.png existan

Errores de carga de scripts

Error: "Failed to load script: ..."

Solución:

1. Verifica que todos los archivos JS estén en content/
2. Revisa la política CSP en manifest.json
3. Asegúrate de que db-webext.js se carga antes de ca-archive.js

sql.js no carga

Error: "Could not load SQL engine"

Solución:

1. Verifica conexión a internet (se descarga desde CDN)
2. O descarga sql.js localmente:

   cd content/
   wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js
   wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm
   

3. Actualiza las rutas en content/db-webext.js

web-ext no disponible (para firma)

Solución:

# Instalar dependencias locales (recomendado)
npm install

# O instalación global (alternativa)
npm install -g web-ext

El script build.sh detecta automáticamente web-ext en node_modules/.bin/

Para Usuarios Finales

Instalar desde archivo .xpi/.zip

Firefox:

1. Descarga el archivo .xpi
2. Arrastra y suelta en Firefox
3. Autoriza la instalación

Chrome:

1. Descarga el archivo .zip
2. Descomprime en una carpeta
3. Sigue los pasos de "Modo desarrollador" arriba

Instalar desde stores (cuando esté publicado)

Firefox Add-ons (AMO):

• Visita: https://addons.mozilla.org/firefox/addon/ca-archive/
• Click en "Añadir a Firefox"

Chrome Web Store:

• Visita: [URL de Chrome Web Store]
• Click en "Añadir a Chrome"

Desinstalación

Firefox

1. about:addons > Extensiones
2. Busca "Classic Add-ons Archive"
3. Click en "..." > Eliminar

Chrome

1. chrome://extensions/
2. Busca la extensión
3. Click en "Eliminar"

Archivos Necesarios

Archivos mínimos para que funcione la extensión:

ca-archive/
├── manifest.json          ← REQUERIDO
├── background.js          ← REQUERIDO
├── content/
│   ├── ca-archive.html    ← REQUERIDO
│   ├── ca-archive.js      ← REQUERIDO
│   ├── db-webext.js       ← REQUERIDO
│   ├── db/
│   │   └── ca-archive-19030501.sqlite  ← REQUERIDO
│   ├── addon.js
│   ├── list.js
│   ├── versions.js
│   ├── tcloud.js
│   ├── about.js
│   └── epl.js
└── skin/
    ├── logo.png           ← REQUERIDO
    ├── button.png         ← REQUERIDO
    ├── ca-archive.css     ← REQUERIDO
    └── ...

Siguientes Pasos

Una vez instalada y funcionando:

1. 📖 Lee MIGRATION.md para entender los cambios
2. 🔧 Si eres desarrollador, revisa la arquitectura modernizada
3. 🐛 Reporta bugs en GitHub Issues
4. 🌟 Si te gusta, deja una valoración

Soporte

• 📝 Documentación completa: MIGRATION.md
• 🐛 Reportar problemas: https://github.com/JustOff/ca-archive/issues
• 💬 Discusiones: https://github.com/JustOff/ca-archive/discussions