Copia de seguridad · migración (Export / Import)

Al trasladar Blyck a otro ordenador (p. ej., portátil con Windows → Mac mini con macOS), si copias manualmente la carpeta userData, los chats apuntan a las rutas absolutas del PC antiguo, los secretos quedan atados al llavero del SO y no se desbloquean, y los binarios dependientes del SO no funcionan.

La copia de seguridad · migración empaqueta (export) y desempaqueta (import) con un solo botón y, al desempaquetar, convierte las rutas automáticamente para que el historial de chats continúe tal cual. Funciona en las 4 direcciones Win↔Mac.

Por qué se rompe la copia manual

Problema	Contenido
Discrepancia de rutas absolutas	El chat apunta a D:\develope\… pero el nuevo PC tiene /Users/…
Secretos dependientes del SO	Las contraseñas de BD/SSH y el token de GitHub están cifrados con el llavero del SO (safeStorage) y no se pueden descifrar en otro PC
Binarios dependientes del SO	python venv, servidores LSP, etc. no funcionan aunque se copien
Caché de regeneración enorme	El índice de búsqueda/embeddings (workspace.sqlite ~226MB) se arrastra entero

Qué se traslada y qué se descarta

🟢 Objetivo de migración (incluido en el bundle)

• chats/ — historial de chats (incluye los mensajes, autocontenido)
• blyck-history.db — historial de cambios (instantánea VACUUM INTO)
• db-history.json · db-snippets.json — historial de consultas BD·snippets
• layout.json · blyck-locale.json · embeddings-settings.json — diseño·idioma·configuración
• connections.json — metadatos de conexión BD/SSH (en el bundle en claro se eliminan los secretos)
• attachments/ · changeSet-snapshots/ — opcional

⚫ Excluido — se regenera en el PC de destino

• workspace.sqlite — índice de búsqueda/embeddings (~226MB). Como en su mayoría deriva del código base, excluirlo entero reduce el bundle de 230MB → unos pocos MB, y en el PC de destino el indexador reindexa automáticamente.
• python-venvs/ · lsp-servers/ — binarios del SO (se regeneran)
• caché de runtime de Electron/Chromium, logs, etc.

Los directorios CLI globales no se migran en ninguna etapa

Los directorios globales como ~/.claude · ~/.codex no son exclusivos de Blyck, sino que los comparten todos los trabajos de ese PC. Sobrescribirlos hace que se pierdan las sesiones existentes del destino y se enreden el índice·el inicio de sesión. La continuidad de la conversación del modelo se gestiona con un fallback de resiembra (el modelo vuelve a leer el historial de pantalla y se pone al día), lo cual es funcionalmente suficiente.

Formato del bundle .blyckbundle

Contenedor ZIP + manifest.json (esquema·versión de la app·SO de origen·raíces de ruta·sha256 por archivo).

backup-YYYY-MM-DD.blyckbundle
├── manifest.json
└── files/                       # espejo de rutas relativas a userData
    ├── chats/index.json, chat_*.json
    ├── blyck-history.db
    ├── db-history.json, db-snippets.json
    ├── layout.json, blyck-locale.json, embeddings-settings.json
    ├── connections.json         # el bundle en claro elimina los secretos
    ├── attachments/**           # opcional
    └── changeSet-snapshots/**   # opcional

Remapeo de rutas — continuar el chat tal cual

Al importar, solo se sustituyen los campos de ruta autoritativos del JSON del chat.

Campo	Remapeo
projectRoot	✅ sustituido
_lastSentProjectRoot	✅ sustituido
extraRoots[]	✅ se sustituye cada elemento
projectRootSftp	❌ inalterado (lo remoto es independiente del PC)
messages[]	❌ inalterado (se conserva el historial)

La regla es la coincidencia del prefijo más largo: si la ruta empieza por la raíz de origen, solo se reemplaza el prefijo por la raíz de destino y se convierten los demás separadores. Las raíces sin mapear se dejan tal cual (el chat se abre pero solo el proyecto queda sin resolver, y el usuario lo reabre).

Entre SO en 4 direcciones (todas las combinaciones Win↔Mac)

remapPath trata por separado el separador de origen (división) y el separador de destino (unión). El separador de origen se detecta automáticamente a partir de la raíz de origen (\/letra de unidad → Win, / → POSIX) y el separador de destino se determina por el SO de destino.

Dirección	Ejemplo de ruta de origen	Ejemplo de resultado
Win→Win	D:\dev\App\src\a.js	E:\work\App\src\a.js
Win→Mac	D:\dev\App\src\a.js	/Users/x/App/src/a.js
Mac→Win	/Users/x/dev/App/src/a.js	D:\work\App\src\a.js
Mac→Mac	/Users/x/dev/App/src/a.js	/Users/y/App/src/a.js

Independiente de la letra de unidad/raíz — al ser sustitución de prefijo, cualquier combinación de raíces como D:\ ↔ /Users/ se resuelve 1:1 según la tabla de mapeo.

Bundle cifrado + secretos incluidos

Al exportar, si especificas una contraseña se cifra el bundle entero.

• Método: AES-256-GCM sobre el bundle completo — el cifrado integrado de ZIP (ZipCrypto) es vulnerable, así que no se usa; tras crear el zip se cifra entero con el crypto nativo de Node (0 dependencias externas). El KDF es scrypt y el cifrado es AES-256-GCM (confidencialidad + integridad).
• Contraseña incorrecta = fallo de verificación del auth tag de GCM → «la contraseña es incorrecta», detectado al instante (sin descifrado parcial, sin alterar los datos).
• Una cabecera en claro (BLYCKENC1) permite determinar de antemano si está cifrado incluso sin contraseña.

Los secretos solo en el bundle cifrado

Solo en el bundle cifrado se pueden incluir las contraseñas de BD/SSH y el token de GitHub. Al exportar, los secretos en claro descifrados con safeStorage se meten en el bundle cifrado y, al importar, se vuelven a cifrar con el safeStorage del SO de destino y se registran, por lo que no hace falta reintroducirlos. En el bundle en claro (sin cifrar) nunca se incluyen (se mantiene el strip de secretos).

Los secretos son independientes de la dirección — descifrar con el safeStorage de Win → bundle cifrado → recifrar con el safeStorage de Mac (y a la inversa), por lo que las 4 direcciones Win↔Mac funcionan.

Flujo de Export

1. Comprobación de detención — si hay un turno ocupado, se rechaza (coherencia de datos)
2. blyck-history.db → una única instantánea con VACUUM INTO (seguro con la app en ejecución)
3. Recopilación de los archivos incluidos + sha256 por archivo
4. Escaneo de chats → se registran las raíces de ruta distintas en manifest.pathRoots
5. Tratamiento de secretos — sin contraseña: strip / con contraseña: incluir secretos en claro
6. Empaquetado ZIP
7. Si hay contraseña, cifrado AES-256-GCM → se registra el *.blyckbundle

Flujo de Import

1. inspect — determina con el magic si está cifrado. Si lo está, solicita la contraseña
2. descifrado — contraseña → scrypt → AES-256-GCM. Si falla el auth tag, se interrumpe (sin alterar los datos)
3. UI de remapeo de rutas — campo de entrada por cada raíz de origen (sugerencia automática del nombre base: D:\develope\Blyck_Web → ~/dev/Blyck_Web)
4. copia de seguridad preventiva — se conservan los chats/·*.db actuales en userData/_pre-import-<ts>/
5. extracción de files/ → se escribe en userData
6. aplicación del remapeo — sustitución del prefijo más largo de projectRoot/_lastSentProjectRoot/extraRoots + normalización de separadores (projectRootSftp·messages inalterados)
7. restauración de secretos — bundle cifrado: recifrado con el safeStorage del SO de destino / bundle en claro: bandera de «requiere reintroducción»
8. sin workspace.sqlite → reindexado automático en la siguiente ejecución
9. aviso de reinicio

Modos — reemplazo vs fusión

Modo	Comportamiento	Uso
reemplazo (replace)	Tras respaldar los chats/·*.db actuales en _pre-import-<ts>, se reemplazan por el bundle	Migrar entero a un nuevo PC
fusión (merge)	Combinar por chat id en una instalación existente (añade sin reemplazar)	Reunir en un solo lugar el trabajo de dos PC

La fusión es segura porque chats/ está en JSON individuales por id, de modo que se combinan sin conflictos.

Salvaguardas

• copia de seguridad automática de los datos actuales antes del import (_pre-import-<ts>)
• compuerta de compatibilidad de esquema/versión de la app del manifest
• verificación de integridad sha256 por archivo
• rechazo del import mientras un chat está ocupado
• confirmación explícita del usuario antes del reemplazo
• contraseña incorrecta del bundle cifrado → interrupción en la etapa de descifrado (sin alterar los datos)
• el bundle en claro no incluye secretos (evita filtraciones)

FAQ

P. ¿El historial de chats se abre tal cual en el nuevo PC? → Sí. Al importar, el remapeo de rutas convierte automáticamente projectRoot, etc., a las rutas del nuevo PC, por lo que el chat y el proyecto continúan tal cual.

P. ¿Tengo que reintroducir las contraseñas de BD/SSH? → Si exportas como bundle cifrado (especificando contraseña), los secretos se incluyen y se vuelven a cifrar para el SO de destino, por lo que no hace falta reintroducirlos. El bundle en claro, por seguridad, omite los secretos, así que sí hay que reintroducirlos.

P. ¿Puedo desempaquetar en Mac un bundle creado en Windows? → Sí. Se admiten las 4 direcciones, incluidas Win→Mac y Mac→Win. Los separadores de ruta (\↔/) y la letra de unidad/raíz se convierten automáticamente.

P. ¿Por qué es tan pequeño el bundle? → El workspace.sqlite (índice de búsqueda) de unos 226MB se puede regenerar a partir del código base, así que se excluye. En el PC de destino el indexador reindexa automáticamente, y el historial de chats en sí se conserva tal cual.

P. ¿Y si olvido la contraseña? → No hay forma de recuperarla. AES-256-GCM no puede descifrarse sin la contraseña, así que guarda con cuidado la contraseña del bundle cifrado.

P. ¿Y si quiero combinar con el trabajo del PC existente? → Usa el modo de fusión. Combina por chat id, añadiendo sin borrar los chats existentes.