Mantenimiento de compilación y plataforma

Esta página explica cómo mantener Meratyn sano con el tiempo: actualizaciones de dependencias, los espejos de compatibilidad que los bumps silenciosos pueden romper, las verificaciones que todo cambio debe pasar y las políticas específicas de plataforma que el shell de escritorio aplica en ejecución.

Mantenimiento de dependencias

Un único bun.lock en la raíz conecta todos los workspaces JavaScript (apps/*, packages/*, services/*), así que una sola entrada de Bun cubre todo el árbol JS. Los ecosistemas Python y Rust tienen sus propios manifiestos y lockfiles.

Dependabot abre PRs semanales agrupados para cada ecosistema (.github/dependabot.yml):

Las correcciones de seguridad siempre llegan en PRs propios e inmediatamente accionables; los bumps rutinarios minor/patch se agrupan en un PR por ecosistema. El job audit de CI ejecuta bun audit --audit-level=high (bloqueante) más un pip-audit no bloqueante del entorno backend resuelto.

Al revisar un PR de dependencias:

1. Ejecuta la verificación local completa (bun run ci) antes de mezclar — varias librerías tienen espejos o contrates fijados por comportamiento, y la suite detecta la deriva (ver la siguiente sección).
2. Refresca el lockfile del sidecar cuando services/server/pyproject.toml cambie: uv lock --project services/server. El lock está versionado porque los instaladores de escritorio lanzan el sidecar con uv run --frozen desde un directorio de recursos de solo lectura; un lock desactualizado falla en el paso de CI “Check the bundled sidecar lockfile is in sync”, y uno ausente falla en el escritorio del usuario con un código de salida 2 opaco.
3. Revisa los contratos de opciones del plugin Tauri descritos bajo Transporte nativo del sidecar en Windows cuando @tauri-apps/plugin-http se actualice.

Espejos de compatibilidad protegidos

Algunas librerías externas exponen constantes o nombres de clase de los que Meratyn depende pero que no exporta. Las copias viven en nuestro código y deben revisarse cada vez que el paquete externo se mueva (incluidos los PRs de Dependabot). Cada una tiene un test que falla en CI cuando el espejo diverge, así que ejecutar la suite frontend tras un bump suele bastar:

Verificaciones

Todo cambio debería pasar la verificación local completa:

bun run ci

Esto ejecuta lint, la build web, los type checks de los workspaces, la suite frontend con cobertura, el type check del worker, la cobertura del backend y un chequeo de Rust del crate Tauri.

• Los pisos de cobertura son un trinquete: test:frontend:coverage falla por debajo de 78% líneas / 78% ramas / 63% funciones, y test:backend:coverage falla por debajo de 55%. Cuando la cobertura suba cómodamente por encima de un piso, súbelo para fijar la ganancia.
• La corrida de cobertura del backend necesita pytest-cov; instalar el extra test (pip install -e "services/server[test]") habilita los tests de motores opcionales (geopandas/rasterio/sedona/httpx) que de otro modo se saltan.
• .pre-commit-config.yaml incluye un hook local bun-build que compila toda la app; delimita su alcance a los archivos cambiados con pre-commit run --files <rutas>.
• Los tests de humo de Playwright viven en e2e/ y corren contra la build web con bun run test:e2e.

Compatibilidad de plataforma

El resto de esta página documenta políticas específicas de plataforma que el shell de escritorio aplica en ejecución. Son parte de la superficie de mantenimiento: cuando una dependencia de la cadena (WebKitGTK, WebView2, plugins de Tauri) cambia, relee la sección correspondiente antes de publicar.

Frontera del artefacto redistribuible

La build web de Meratyn solo expone los nombres VITE_ listados en apps/mappview/vite.config.ts. Los nombres desconocidos se eliminan antes de que Vite resuelva el entorno de cliente explícito (sus valores de proceso se blanquean primero). Las builds de embed (MAPPVIEW_EMBED=1), las builds de Tauri y cualquier build con MAPPVIEW_STRIP_CREDENTIALS=1 blanquean las credenciales de proveedores para que una clave de la máquina de compilación no entre en un wheel o instalador de escritorio. Los usuarios proveen sus propias claves en ejecución en Configuración → Variables de entorno.

La frontera se aplica dos veces:

• scripts/scan-credentials.ts escanea los JavaScript, CSS, HTML, JSON, mapas y archivos de texto emitidos buscando formas de tokens de proveedores, asignaciones de entorno de credenciales y URLs con userinfo. Redacta las coincidencias en los diagnósticos.
• python/hatch_build.py ejecuta el mismo escaneo en cada build de wheel/sdist, incluso cuando python/src/mappview/static/app ya contiene una build vieja.

El escáner comparte sus definiciones mediante scripts/credential-patterns.json. El único token permitido es el token público Ion de CesiumJS, propiedad del vendor; refresca su hash solo después de confirmar que una actualización de dependencia sigue incluyendo ese token y que identifica a CesiumJS. No permitas claves de Meratyn, de proveedores ni del operador.

Gestión WebKitGTK/NVIDIA en Linux

Al arrancar, el shell de escritorio elige una política de compatibilidad según la versión de WebKitGTK y el renderer NVIDIA activo:

Un valor explícito de WEBKIT_DISABLE_DMABUF_RENDERER o WEBKIT_DMABUF_RENDERER_FORCE_SHM siempre gana. CI cubre la matriz de política pura; las combinaciones reales de driver/WebKit siguen siendo específicas de cada distribución, así que una ventana en blanco o caídas de fotogramas deben reproducirse con los paquetes WebKitGTK y NVIDIA de la distribución antes de cambiar los valores por defecto.

CPU Linux sin AVX

En Linux x86, el trampolín de tier-up de WebAssembly de JavaScriptCore puede ejecutar instrucciones AVX sin verificar la CPU. Una máquina sin AVX puede por tanto perder el proceso web de WebKit con SIGILL en cuanto DuckDB-WASM o Whitebox se calientan, dejando una ventana de escritorio en blanco. Al arrancar, Meratyn verifica el bit de feature en ejecución y, solo cuando AVX está ausente, fija ambas opciones antes de que WebKit arranque:

JSC_useWasmOSR=false
JSC_useBBQTierUpChecks=false

Las opciones son un par todo-o-nada: dejar cualquiera de las dos activa alcanza el trampolín inseguro. Un valor explícito interpretado como activado (true, yes, 1, o un valor desconocido) en cualquiera de las dos es una exclusión voluntaria y deja ambas intactas; un valor explícito de desactivado (false, no, 0, sin distinguir mayúsculas) se preserva mientras el par faltante se completa. WebAssembly sigue compilándose en modo baseline, así que esto preserva la funcionalidad con un costo de rendimiento acotado. arm64 y las CPU con AVX no cambian. La decisión pura y la matriz de valores de JavaScriptCore viven en los tests de Rust de Tauri; no reemplaces esta verificación de feature en ejecución por una lista de modelos o fechas de CPU.

Transporte nativo del sidecar en Windows

Windows WebView2 puede rechazar el sidecar de procesamiento local por políticas de CORS de navegador y Local Network Access. El bootstrap de escritorio instala por eso el fetch HTTP nativo de Tauri en Windows antes de montar la app. Solo el origen loopback exacto http://127.0.0.1:8765/* pasa por ese cliente; valores personalizados de VITE_SIDECAR_URL y despliegues de mismo origen /sidecar mantienen el fetch del navegador. La capability Tauri correspondiente está en apps/mappview/src-tauri/capabilities/default.json.

Dos opciones del plugin son invariantes de seguridad y conectividad, no meras elecciones de tipo:

• maxRedirections: 0 evita que el X-MappView-Token por lanzamiento se reenvíe a otro host mediante una redirección.
• proxy: { all: { url: "http://127.0.0.1:8765", noProxy: "*" } } desactiva la búsqueda de proxy de sistema de reqwest y excluye todos los hosts del proxy provisto, manteniendo el tráfico loopback directo incluso en máquinas con proxy corporativo.

Los nombres de las opciones se derivan del tipo fetch de @tauri-apps/plugin-http y los tests del adaptador fijan los valores exactos. Cuando ese plugin se actualice, revisa también el comportamiento de reqwest/hyper-util además de los nombres verificados por el compilador: ni la semántica de redirección ni la de proxy están garantizadas por las declaraciones de TypeScript.