ca-archive/README-v3.md

Classic Add-ons Archive v3.0 - WebExtensions Edition

🎉 Nueva versión modernizada

Esta es la versión 3.0 de Classic Add-ons Archive, completamente reescrita usando WebExtensions para ser compatible con navegadores modernos.

✨ Características principales

• 📦 93,598 versiones de 19,450 extensiones clásicas de Firefox
• 🔍 Búsqueda y navegación por categorías
• 📊 Ordenamiento por popularidad, valoración, fecha, etc.
• 💾 Base de datos SQLite embebida
• 🌐 Compatible con Firefox 57+, Chrome 80+, Edge, Brave, Vivaldi

🆕 Novedades de la versión 3.0

• ✅ Compatible con Firefox Quantum (57+) y Chrome
• ✅ Usa APIs modernas de WebExtensions
• ✅ Ya no requiere Firefox legacy
• ✅ Navegación mejorada con hash routing
• ✅ Base de datos en memoria con sql.js
• ✅ Sin dependencias de XPCOM/XUL

🚀 Instalación rápida

Para usuarios

Firefox:

# Descargar release
# Ir a about:debugging
# Cargar extensión temporal > seleccionar manifest.json

Chrome/Edge/Brave:

# Ir a chrome://extensions/
# Activar "Modo de desarrollador"
# "Cargar extensión sin empaquetar" > seleccionar carpeta

Documentación completa: INSTALL.md

Para desarrolladores

# Clonar repositorio
git clone https://github.com/JustOff/ca-archive.git
cd ca-archive

# (Opcional) Instalar web-ext para testing
npm install

# Generar claves de firma
./scripts/generate-keys.sh

# Probar en Firefox
npm run start:firefox

# O probar en Chrome
npm run start:chrome

# Construir paquetes sin firmar
./build.sh

# Construir y firmar
./build.sh --sign           # Ambos navegadores
./build.sh --sign-firefox   # Solo Firefox
./build.sh --sign-chrome    # Solo Chrome

# Usando npm
npm run build              # Sin firmar
npm run build:sign         # Con firma
npm run keys:generate      # Generar claves

Más información sobre firma: Ver SIGNING.md

📁 Estructura del proyecto

ca-archive/
├── manifest.json          # Manifiesto WebExtensions v2
├── background.js          # Script de fondo
├── package.json          # Scripts de build (opcional)
│
├── content/              # Scripts y páginas de contenido
│   ├── ca-archive.html   # Página principal de la extensión
│   ├── ca-archive.js     # Router y controlador principal
│   ├── db-webext.js      # Wrapper de base de datos (sql.js)
│   ├── db.js             # [Legacy] No usado en v3
│   ├── addon.js          # Vista de detalle de addon
│   ├── list.js           # Vista de listado
│   ├── versions.js       # Vista de versiones
│   ├── tcloud.js         # Nube de tags
│   ├── about.js          # Página "Acerca de"
│   ├── epl.js            # EULA/Privacy/License
│   └── db/
│       └── ca-archive-*.sqlite  # Base de datos SQLite
│
├── skin/                 # Assets visuales
│   ├── ca-archive.css    # Estilos principales
│   ├── button.css        # [Legacy] No usado en v3
│   ├── logo.png          # Logo de la extensión
│   ├── button.png        # Icono del botón
│   └── ...               # Otros assets
│
├── MIGRATION.md          # Guía de migración desde v2
├── INSTALL.md            # Guía de instalación
├── README-v3.md          # Este archivo
│
└── [Legacy - no usados en v3]
    ├── install.rdf
    ├── chrome.manifest
    ├── bootstrap.js
    └── update.xml

🔄 Migración desde v2 (Legacy)

Si vienes de la versión 2.x (XUL/XPCOM), lee la Guía de Migración que explica:

• ❌ Qué dejó de funcionar
• ✅ Cómo se reemplazó cada funcionalidad
• 🔧 Cambios en la arquitectura
• 📊 Tabla de compatibilidad de navegadores

Resumen rápido de cambios

Aspecto	v2 (Legacy)	v3 (WebExtensions)
Manifest	install.rdf	manifest.json
Protocolo	caa:	hash routing (#)
APIs	Components/XPCOM	WebExtensions APIs
Base de datos	mozIStorageService	sql.js
Navegadores	Firefox ≤56	Firefox 57+, Chrome 80+

🛠️ Desarrollo

Requisitos

• Node.js 16+ (opcional, para herramientas de build)
• Firefox Developer Edition o Chrome
• Editor de código (VS Code recomendado)
• OpenSSL (para firma de extensiones)

Setup

# Instalar dependencias de desarrollo
npm install

# Generar claves de firma (primera vez)
./scripts/generate-keys.sh

# Lint
npm run lint

# Testing local
npm run start:firefox  # Abre Firefox con la extensión
# o
npm run start:chrome   # Abre Chrome con la extensión

Nota: web-ext se instala automáticamente como dependencia local del proyecto.

Testing manual

1. Hacer cambios en el código
2. En about:debugging (Firefox) o chrome://extensions/ (Chrome), click en "Recargar"
3. Abrir la extensión y verificar cambios
4. Revisar console (F12) para errores

Build para distribución

# Firefox (.xpi)
npm run build:firefox
# Output: dist/ca-archive-3.0.0.zip (renombrar a .xpi)

# Chrome (.zip)
npm run build:chrome
# Output: dist/ca-archive-3.0-chrome.zip

# Ambos con el script bash
./build.sh

# Con firma (requiere claves configuradas)
./build.sh --sign
npm run build:sign

📝 Documentación de firma: Ver SIGNING.md para instrucciones completas sobre:

• Generación de claves privadas
• Configuración de credenciales AMO (Firefox)
• Firma para Firefox y Chrome
• Distribución en stores oficiales

🐛 Debugging

Abrir consola de la extensión

Firefox:

1. about:debugging > Este Firefox
2. Click en "Inspeccionar" en la extensión

Chrome:

1. chrome://extensions/
2. Click en "Inspeccionar vistas: background page"

Logs útiles

// En background.js
console.log("Background script:", message);

// En content scripts
console.log("Content script:", message);

// Errores de base de datos
// Revisar consola de la página ca-archive.html

📝 Notas técnicas

Base de datos SQLite

• Tamaño: ~50MB (comprimido: ~15MB)
• Engine: sql.js (SQLite compilado a WebAssembly)
• Storage: browser.storage.local (primera carga)
• Límite: Chrome 10MB (usa unlimitedStorage permission)

Permisos requeridos

• storage - Cachear base de datos
• unlimitedStorage - DB grande (>10MB)
• tabs - Abrir tabs del catálogo
• webRequest + webRequestBlocking - Modificar headers de descarga
• <all_urls> - Interceptar requests a web.archive.org

Políticas de seguridad

"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'"

• 'unsafe-eval' - Requerido por sql.js (usa WebAssembly)
• Todos los scripts deben estar en el paquete (no CDN inline)

🤝 Contribuir

¡Las contribuciones son bienvenidas!

Áreas de mejora

• Migrar a Manifest V3 (cuando Firefox tenga mejor soporte)
• Optimizar carga de base de datos (chunks, compresión)
• Modo oscuro (dark mode)
• Búsqueda con índices full-text
• Favoritos/bookmarks sincronizados
• Mejoras de UI/UX

Proceso

1. Fork del repositorio
2. Crear branch: git checkout -b feature/mi-mejora
3. Commit: git commit -am 'Añadir nueva característica'
4. Push: git push origin feature/mi-mejora
5. Crear Pull Request

📄 Licencia

Mozilla Public License 2.0 (MPL-2.0)

• ✅ Uso comercial
• ✅ Modificación
• ✅ Distribución
• ✅ Uso privado
• ⚠️ Divulgar fuente si se modifica

Ver LICENSE para más detalles.

Atribuciones

• Diseño original: Mozilla AMO (CC-BY-SA-3.0)
• Datos: Dominio público / respectivos autores
• sql.js: MIT License
• Logos y marcas: Propiedad de sus respectivos dueños

👥 Autores

• Off JustOff - Autor original - JustOff
• Migración a WebExtensions v3.0 - 2026

🔗 Enlaces

• 🏠 Sitio web
• 📦 Releases
• 🐛 Issues
• 💬 Discusiones
• 📖 Documentación

⭐ Agradecimientos

• Mozilla y la comunidad AMO
• Wayback Machine (Internet Archive)
• Zetamex Network (hosting)
• Todos los desarrolladores de extensiones clásicas

---

¿Te gusta el proyecto? Dale una ⭐ en GitHub!

¿Encontraste un bug? Repórtalo aquí

¿Tienes preguntas? Pregunta en Discusiones