ca-archive/TROUBLESHOOTING.md

# Guía de Solución de Problemas (Troubleshooting)

Esta guía te ayudará a resolver problemas comunes al usar Classic Add-ons Archive v3.0.

## ⚠️ Problemas Actuales Conocidos (2026)

### 🦊 Firefox: No instala sin firma
**Problema:** Firefox Release NO permite instalar extensiones sin firmar, incluso cambiando `xpinstall.signatures.required=false`.

**Solución rápida:**
- ✅ Usa **Firefox Developer Edition** o **Nightly** (permiten deshabilitar firma)
- ✅ O carga como complemento temporal: `about:debugging` > "Cargar complemento temporal"
- ✅ O firma con AMO: `./build.sh --sign` (requiere credenciales AMO)

[Ver solución detallada](#firefox-add-on-could-not-be-installed-because-it-is-not-signed-sin-poder-deshabilitar-firma)

### 🎨 Chrome: Manifest no compatible
**Problema:** Chrome 127+ (junio 2024) bloqueó Manifest v2. Esta extensión usa v2.

**Solución rápida:**
- ✅ Usa **Firefox** (mejor opción, soporte v2 indefinido)
- ✅ O usa **Microsoft Edge** / **Brave** (soporte v2 hasta ~2025-2026)
- ❌ Chrome ya no soporta Manifest v2 (requiere migración a v3, no disponible aún)

[Ver solución detallada](#chrome-manifest-version-2-is-deprecated-o-not-supported)

---

## 📋 Índice Completo

1. [Problemas de Instalación](#problemas-de-instalación)
2. [Problemas con la Base de Datos](#problemas-con-la-base-de-datos)
3. [Problemas de Navegación](#problemas-de-navegación)
4. [Problemas de Rendimiento](#problemas-de-rendimiento)
5. [Errores en la Consola](#errores-en-la-consola)
6. [Incompatibilidades](#incompatibilidades)
7. [Obtener Ayuda](#obtener-ayuda)

---

## Problemas de Instalación

### El icono de la extensión no aparece

**Síntomas:**
- No veo el icono en la barra de herramientas

**Soluciones:**

1. **Recargar la extensión:**
   - Firefox: `about:debugging` > Click en "Recargar"
   - Chrome: `chrome://extensions/` > Click en el icono de recargar ↻

2. **Verificar que está habilitada:**
   - Firefox: `about:addons` > Extensiones > Buscar "Classic Add-ons Archive"
   - Chrome: `chrome://extensions/` > Buscar la extensión y verificar que el toggle está activado

3. **Verificar manifest.json:**
   ```bash
   cat manifest.json | grep -A 5 browser_action
   ```
   Debe existir la sección `browser_action` con iconos válidos.

### Error al cargar la extensión

**Error:** "There was an error during installation"

**Causas comunes:**
- `manifest.json` inválido
- Archivos requeridos faltantes
- Permisos incorrectos

**Soluciones:**

1. **Validar el manifest:**
   ```bash
   # Instalar web-ext si no lo tienes
   npm install -g web-ext
   
   # Validar
   web-ext lint
   ```

2. **Verificar archivos requeridos:**
   ```bash
   ls -la manifest.json background.js
   ls -la content/ca-archive.html content/ca-archive.js content/db-webext.js
   ls -la skin/logo.png skin/button.png
   ```

3. **Verificar sintaxis JSON:**
   - Usar herramienta online: https://jsonlint.com/
   - O con python:
   ```bash
   python3 -m json.tool manifest.json > /dev/null
   ```

### Firefox: "This add-on could not be installed because it appears to be corrupt"

**Solución:**

1. Reconstruir el paquete:
   ```bash
   ./build.sh
   ```

2. Verificar integridad:
   ```bash
   unzip -t dist/ca-archive-3.0.0.xpi
   ```

3. Si persiste, cargar sin empaquetar:
   - `about:debugging` > Cargar complemento temporal
   - Seleccionar `manifest.json` directamente

### Firefox: "Add-on could not be installed because it is not signed" (sin poder deshabilitar firma)

**Problema:** Firefox Release NO permite deshabilitar la verificación de firma desde Firefox 48+.

**Causa:** 
- `xpinstall.signatures.required=false` NO funciona en Firefox Release
- Solo funciona en versiones Developer/Nightly/ESR Unbranded

**Soluciones:**

1. **Usar Firefox Developer Edition (RECOMENDADO):**
   ```bash
   # Descargar desde:
   # https://www.mozilla.org/firefox/developer/
   
   # Luego en about:config:
   xpinstall.signatures.required = false
   ```

2. **Usar Firefox Nightly:**
   ```bash
   # Descargar desde:
   # https://www.mozilla.org/firefox/nightly/
   
   # Luego en about:config:
   xpinstall.signatures.required = false
   ```

3. **Firmar en Mozilla AMO (para distribución):**
   ```bash
   # 1. Obtener credenciales:
   # https://addons.mozilla.org/developers/addon/api/key/
   
   # 2. Configurar en:
   # private-keys/firefox-amo-credentials.json
   
   # 3. Firmar:
   ./build.sh --sign
   ```

4. **Carga temporal (limpia al cerrar Firefox):**
   - `about:debugging#/runtime/this-firefox`
   - Click "Cargar complemento temporal"
   - Seleccionar `manifest.json`
   - ⚠️ Se desinstala al cerrar Firefox

### Chrome: "Manifest version 2 is deprecated" o "not supported"

**Problema:** Chrome está deprecando/bloqueando Manifest v2.

**Estado actual (febrero 2026):**
- Chrome 127+ (junio 2024): v2 deshabilitado para nuevas extensiones
- Chrome 136+ (2025): v2 puede estar completamente bloqueado
- Edge/Brave: Soporte extendido hasta 2025-2026

**Soluciones:**

1. **Verificar versión de Chrome:**
   ```
   chrome://settings/help
   ```

2. **Si Chrome < 127 (solo advertencia):**
   - ✅ La extensión funciona normalmente
   - Ignora la advertencia de deprecación
   - Instala en modo desarrollador normalmente

3. **Si Chrome >= 127 (error de bloqueo):**
   
   **Opción A: Usar navegador compatible (RECOMENDADO)**
   - Microsoft Edge: `edge://extensions/`
   - Brave: `brave://extensions/`
   - Ambos soportan Manifest v2 hasta ~2025-2026
   
   **Opción B: Usar Firefox**
   - Firefox soporta Manifest v2 indefinidamente
   - Mejor compatibilidad con esta extensión
   
   **Opción C: Esperar Manifest v3 (no disponible aún)**
   - Estado: No implementado en esta extensión
   - Requiere reescritura significativa:
     - Service workers en lugar de background scripts
     - Eliminar `webRequestBlocking`
     - Eliminar `'unsafe-eval'` (conflicto con sql.js)
   - Timeline: TBD

4. **Workaround temporal (solo Chrome <140):**
   
   Algunos flags experimentales pueden ayudar:
   ```
   chrome://flags/#enable-mv2-extension-deprecation-warnings
   ```
   Cambiar a "Disabled" (solo retrasa advertencias, no evita bloqueo)

**⚠️ IMPORTANTE:** 
- Manifest v3 tiene limitaciones que dificultan esta extensión
- sql.js requiere `'unsafe-eval'` (prohibido en v3)
- Posibles soluciones v3: migrar a IndexedDB en lugar de sql.js

### Chrome: "Could not load manifest"

**Error completo:** `"manifest_version" key must be 3...`

**Causa:** Chrome 127+ bloqueando Manifest v2

**Solución:** Ver sección anterior "Manifest version 2 is deprecated"

---

## Problemas con la Base de Datos

### "Loading database for the first time" se queda cargando

**Síntomas:**
- Mensaje de carga de DB sin terminar
- Página en blanco

**Causas:**
- Base de datos muy grande
- Falta archivo SQLite
- Error de red (si carga desde CDN)

**Soluciones:**

1. **Verificar que existe el archivo DB:**
   ```bash
   ls -lh content/db/*.sqlite
   ```

2. **Verificar tamaño de la DB:**
   ```bash
   du -h content/db/*.sqlite
   ```
   Si es >50MB, puede tardar en el primer acceso.

3. **Revisar la consola del navegador** (`F12` > Console):
   - Buscar errores relacionados con fetch o sql.js

4. **Limpiar storage y reintentar:**
   ```javascript
   // En la consola del navegador
   browser.storage.local.clear()
   // o en Chrome:
   chrome.storage.local.clear()
   ```

5. **Verificar permisos del archivo:**
   ```bash
   chmod 644 content/db/*.sqlite
   ```

### Error: "Could not load SQL engine"

**Causa:** sql.js no se pudo cargar

**Soluciones:**

1. **Verificar conexión a internet** (si usa CDN)

2. **Descargar sql.js localmente:**
   ```bash
   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. **Actualizar rutas en `db-webext.js`:**
   ```javascript
   // Cambiar:
   locateFile: file => `https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/${file}`
   
   // Por:
   locateFile: file => browser.runtime.getURL(`content/${file}`)
   ```

4. **Agregar archivos a `web_accessible_resources` en manifest.json:**
   ```json
   "web_accessible_resources": [
     "content/*.wasm",
     "content/sql-wasm.js"
   ]
   ```

### Error: "Database has just been updated, not ready or corrupted!"

**Causa:** Archivo SQLite corrupto o inaccesible

**Soluciones:**

1. **Verificar integridad de la DB:**
   ```bash
   sqlite3 content/db/ca-archive-*.sqlite "PRAGMA integrity_check;"
   ```
   Debe retornar "ok"

2. **Re-descargar la base de datos:**
   - Si tienes repositorio Git: `git checkout content/db/*.sqlite`
   - O descargar manualmente desde releases

3. **Permisos de lectura:**
   ```bash
   chmod 644 content/db/*.sqlite
   ```

---

## Problemas de Navegación

### Los enlaces no funcionan

**Síntomas:**
- Click en categoría/addon no hace nada
- URL no cambia
- Página en blanco

**Soluciones:**

1. **Verificar hash routing:**
   - La URL debe ser: `moz-extension://[id]/content/ca-archive.html#list`
   - No debe ser: `caa:list` (eso es legacy)

2. **Revisar consola JavaScript** (`F12`):
   - Buscar errores en `ca-archive.js`

3. **Verificar que los módulos se cargan:**
   ```javascript
   // En la consola del navegador
   console.log(typeof List, typeof Addon, typeof DB);
   // Debe mostrar los tipos de objeto/function
   ```

4. **Limpiar caché del navegador:**
   - Firefox: `Ctrl+Shift+Del` > Marcar "Caché"
   - Chrome: `Ctrl+Shift+Del` > "Cached images and files"

### Búsqueda no funciona

**Síntomas:**
- Campo de búsqueda no responde
- No muestra resultados

**Soluciones:**

1. **Verificar que la DB está cargada:**
   - Debe haber completado la carga inicial
   - Revisar que no hay mensajes de error en consola

2. **Verificar el formulario:**
   ```html
   <form id="search" action="#list">
   ```
   Debe tener `action="#list"` (no `caa:list`)

3. **Probar búsqueda directa:**
   - Navegar manualmente a: `#list?q=tu-búsqueda`

---

## Problemas de Rendimiento

### La extensión es lenta

**Síntomas:**
- Navegación lenta entre páginas
- La UI se congela
- Alta uso de CPU/RAM

**Causas:**
- Base de datos muy grande en memoria
- Consultas SQL no optimizadas
- Demasiados addons en listado

**Soluciones:**

1. **Verificar uso de memoria:**
   - Firefox: `about:performance`
   - Chrome: `chrome://process-internals/`

2. **Reducir resultados por página:**
   - Editar módulos que hacen consultas (list.js, addon.js)
   - Agregar límite LIMIT a queries SQL

3. **Considerar IndexedDB en lugar de sql.js:**
   - sql.js carga toda la DB en RAM
   - IndexedDB maneja datos en disco de forma nativa

4. **Cerrar otras extensiones:**
   - Conflictos con otras extensiones pueden causar lentitud

### Carga inicial muy lenta (>30 segundos)

**Causa:** Base de datos grande descargándose por primera vez

**Soluciones:**

1. **Paciencia:** Primera carga es normal que tarde
   - DB de ~50MB puede tardar 30-60s en redes lentas

2. **Verificar progreso:**
   - Abrir Network tab (`F12` > Network)
   - Buscar descarga del archivo .sqlite

3. **Pre-cargar la DB:**
   - Copiar manualmente a storage:
   ```javascript
   // Demasiado complejo, mejor esperar carga natural
   ```

4. **Usar conexión más rápida** para primera instalación

---

## Errores en la Consola

### "ReferenceError: DB is not defined"

**Causa:** `db-webext.js` no se cargó antes de `ca-archive.js`

**Solución:**

Verificar orden en `ca-archive.html`:
```html
<!-- CORRECTO: -->
<script src="db-webext.js"></script>
<script src="ca-archive.js"></script>

<!-- INCORRECTO: -->
<script src="ca-archive.js"></script>
<script src="db-webext.js"></script>
```

### "Failed to load script: versions.js"

**Causa:** Módulo no existe o ruta incorrecta

**Soluciones:**

1. **Verificar que existe:**
   ```bash
   ls -la content/versions.js
   ```

2. **Verificar permisos:**
   ```bash
   chmod 644 content/*.js
   ```

3. **Verificar en web_accessible_resources** (manifest.json):
   ```json
   "web_accessible_resources": [
     "content/*.js"
   ]
   ```

### "Unsafe attempt to load URL"

**Causa:** Violación de Content Security Policy

**Solución:**

Actualizar CSP en manifest.json:
```json
"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'"
```

**Nota:** `'unsafe-eval'` es necesario para sql.js (WebAssembly).

### "TypeError: Cannot read property 'openDB' of undefined"

**Causa:** Variable `DB` no está definida globalmente

**Solución:**

En `db-webext.js`, verificar al final:
```javascript
if (typeof window !== "undefined") {
  window.DB = DB;
}
```

---

## Incompatibilidades

### No funciona en Firefox 56 o inferior

**Explicación:**
- v3.0 requiere Firefox 57+ (WebExtensions puras)
- Firefox 56 y anteriores usan sistema legacy

**Solución:**
- Usar la versión 2.x para Firefox ≤56
- O actualizar Firefox a versión moderna

### No funciona en Pale Moon / Basilisk

**Explicación:**
- Estos navegadores no soportan WebExtensions completas
- Usan sistema legacy de Firefox

**Solución:**
- Usar la versión 2.x legacy
- No hay planes de portar v3 a estos navegadores

### Problemas en Chrome con storage

**Error:** "QUOTA_BYTES quota exceeded"

**Causa:** Base de datos muy grande para storage.local de Chrome (límite 10MB)

**Solución:**

1. **Ya incluido:** Permiso `unlimitedStorage` en manifest.json

2. **Verificar que está presente:**
   ```json
   "permissions": [
     "unlimitedStorage"
   ]
   ```

3. **Si sigue fallando:** Considerar:
   - Comprimir la DB
   - Usar chunks para storage
   - Usar IndexedDB nativa

---

## Obtener Ayuda

Si ninguna solución funciona:

### 1. Recopilar información

**Información del sistema:**
- Navegador y versión: `about:support` (Firefox) o `chrome://version/` (Chrome)
- Versión de la extensión: Ver manifest.json
- Sistema operativo

**Logs:**
```javascript
// En consola del navegador (F12)
console.log("Extension ID:", browser.runtime.id);
console.log("Extension URL:", browser.runtime.getURL(""));

// En consola de background script
// (about:debugging > Inspeccionar)
// Copiar todos los console.log relevantes
```

**Errores:**
- Captura de pantalla de errores en consola
- Texto completo de mensajes de error

### 2. Verificar problemas conocidos

- GitHub Issues: https://github.com/JustOff/ca-archive/issues
- Buscar error específico

### 3. Reportar bug

Si no existe issue similar, crear uno nuevo:

**Plantilla:**

```markdown
## Descripción del problema
[Describe qué está fallando]

## Pasos para reproducir
1. [Primer paso]
2. [Segundo paso]
3. [...]

## Comportamiento esperado
[Qué debería pasar]

## Comportamiento actual
[Qué está pasando]

## Entorno
- Navegador: [Firefox 100 / Chrome 105]
- SO: [Linux / Windows / macOS]
- Versión extensión: [3.0.0]

## Logs
```
[Pegar logs de consola aquí]
```

## Capturas
[Adjuntar screenshots si aplica]
```

### 4. Contacto

- GitHub Issues: https://github.com/JustOff/ca-archive/issues
- Discusiones: https://github.com/JustOff/ca-archive/discussions
- Email: [Especificar si aplica]

---

## Debugging Avanzado

### Habilitar logging detallado

En `background.js`, agregar al inicio:
```javascript
const DEBUG = true;

function log(...args) {
  if (DEBUG) console.log("[CA Archive]", ...args);
}
```

Luego usar `log()` en lugar de `console.log()`.

### Inspeccionar storage

```javascript
// Firefox
browser.storage.local.get(null).then(console.log);

// Chrome
chrome.storage.local.get(null, console.log);
```

### Ejecutar queries SQL manualmente

```javascript
// En consola de ca-archive.html
if (DB.db) {
  const results = DB.execute("SELECT COUNT(*) FROM addons");
  console.log(results);
}
```

### Profiling de rendimiento

1. Abrir DevTools (`F12`)
2. Ir a tab "Performance" / "Rendimiento"
3. Click en "Record" / "Grabar"
4. Realizar acción lenta
5. Stop y analizar flamegraph

---

## Recursos Adicionales

- [Documentación Mozilla WebExtensions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions)
- [Chrome Extensions API](https://developer.chrome.com/docs/extensions/reference/)
- [Chrome Manifest v2 to v3 Migration](https://developer.chrome.com/docs/extensions/develop/migrate)
- [sql.js Documentation](https://sql.js.org/)
- [Debugging WebExtensions (Firefox)](https://extensionworkshop.com/documentation/develop/debugging/)
- [Debugging Chrome Extensions](https://developer.chrome.com/docs/extensions/mv2/tut_debugging/)
- [Firefox Developer Edition Download](https://www.mozilla.org/firefox/developer/)
- [AMO Signing API](https://addons-server.readthedocs.io/en/latest/topics/api/signing.html)

---

**¿Solucionaste tu problema?** ¡Considera contribuir esta solución a la documentación!

**¿Problema diferente?** Abre un issue en GitHub: https://github.com/JustOff/ca-archive/issues