Modificar una extensión para varios navegadores sin filtrar secretos ni romper los datos guardados

## Identificar primero la capa afectada de la extensión y sus reglas locales Antes de modificar el código, identifica la capa afectada: lógica en segundo plano, interfaz de usuario, utilidades compartidas, declaraciones del navegador, herramientas de compilación, pruebas o actualizaciones del estado almacenado. Lee antes de editar las instrucciones específicas de la capa más cercana; los archivos de automatización del flujo de trabajo suelen tener conexiones adicionales y reglas para la cola de fusiones. Usa el entorno de ejecución administrado por el repositorio y el envoltorio del gestor de paquetes. Mantén la configuración en el archivo de entorno local designado, nunca en código fuente bajo seguimiento. Prefiere el lenguaje tipado actual para cada archivo de implementación nuevo; los archivos antiguos sin tipos pueden permanecer hasta que un cambio solicitado justifique su conversión. Usa el formateador asignado a cada familia de archivos. El formateador de código se ocupa de los archivos tipados y de componentes, mientras que el de datos estructurados se ocupa de los datos de paquetes y configuración. Antes de la entrega, ejecuta el formateo de los archivos modificados, los tipos estáticos, el lint y las comprobaciones de dependencias circulares. Mantén las funciones centradas, reduce el anidamiento con retornos anticipados, elimina la lógica repetida solo cuando la extracción aclare la propiedad y no dejes registros de depuración ni código comentado. ## Guardar los secretos en local y regenerar las políticas al cambiar dependencias Trata las credenciales de API, los puntos de conexión de supervisión, las contraseñas de prueba y el material de firma como secretos locales. Proporciona marcadores de posición documentados, pero nunca registres valores reales en el repositorio ni incluyas estados confidenciales en los registros de diagnóstico. Cada adición, actualización o eliminación de una dependencia supone un cambio en la cadena de suministro. Completa toda la secuencia: 1. Actualiza la declaración del paquete y el archivo de bloqueo. 2. Elimina los duplicados del archivo de bloqueo mediante el comando compatible. 3. Vuelve a calcular la lista de paquetes autorizados para ejecutar scripts de instalación. 4. Regenera las políticas de capacidades que restringen el acceso de las dependencias a las API del anfitrión. 5. Regenera la atribución de terceros. 6. Compila y prueba con la política de seguridad de producción activada. Incluye en la misma revisión todos los cambios generados de políticas y atribuciones. Puede usarse una compilación de desarrollo sin políticas para iterar con rapidez, pero nunca sustituye a la compilación final protegida. Regenera las políticas dependientes de la plataforma en la plataforma de destino, en lugar de debilitarlas para que la compilación pase. ## Diseñar los controladores de fondo con estado declarado y acciones del dominio Usa controladores para la lógica de negocio en segundo plano y la comunicación mediante mensajes entre subsistemas. Para cada propiedad almacenada, declara si es anónima, si es segura para instantáneas de diagnóstico o registros de estado, si es persistente y si la consume la interfaz. Sigue estas reglas de estado: - Exporta una fábrica de estado predeterminado que devuelva un objeto nuevo, nunca un objeto predeterminado mutable y compartido. - Recibe las dependencias del constructor mediante un único objeto de opciones con nombre, en lugar de argumentos posicionales. - Modela acciones del dominio como añadir, eliminar, aprobar o rechazar; evita los establecedores genéricos de campos. - Almacena solo el estado esencial y deriva los recuentos, indicadores y proyecciones mediante selectores exportados. - Valida las entradas de las acciones antes de actualizar el estado. - Implementa la limpieza del ciclo de vida para temporizadores, suscripciones, escuchas y canales de mensajes, y después delega en la limpieza del controlador padre. Mantén sincronizados el código fuente, los tipos, las pruebas ubicadas junto al controlador, el registro y los selectores afectados. Un cambio en la estructura del estado también requiere un paso de actualización numerado. ## Colocar el código en la capa que lo posee y actualizar los archivos vinculados Coloca los componentes reutilizables de la interfaz junto con sus estilos, tipos, pruebas, historias, documentación y exportación pública. Coloca los componentes exclusivos de una página en la capa de la página, los auxiliares exclusivos del segundo plano con el código de segundo plano y las utilidades, constantes y tipos realmente compartidos en módulos compartidos. Cuando cambie el comportamiento, inspecciona los archivos acoplados directamente: - Los cambios en controladores pueden requerir pruebas, tipos, registro y actualizaciones de estado. - Los cambios en propiedades de componentes pueden requerir pruebas, historias, estilos, documentación y exportaciones. - Los cambios en el estado global pueden requerir selectores y componentes que los consuman. - Los cambios en la compilación o en declaraciones del navegador pueden requerir accesorios específicos del destino y cobertura de extremo a extremo. No copies lógica compartida solo para evitar elegir un propietario. Muévela a la capa común de menor alcance, usa la inyección de dependencias cuando sea necesario y resuelve las importaciones circulares en vez de aceptar una lista ampliada de excepciones. ## Compilar y probar por separado cada navegador e indicador de función Mantén una ruta de compilación y prueba distinta para cada generación compatible de declaraciones del navegador. Ten en cuenta diferencias como páginas persistentes en segundo plano frente a trabajadores de servicio, modelos de permisos y disponibilidad de espacios de nombres. Usa la abstracción de API para múltiples navegadores en el código compartido. Aísla las diferencias inevitables entre destinos en una pequeña capa de compatibilidad, en vez de dispersar condiciones por las funciones. Los indicadores de funciones deben ser entradas de compilación explícitas: - Usa la configuración local documentada para un desarrollo repetible. - Usa sustituciones del entorno mediante un solo comando para experimentos aislados. - Usa una sustitución local de la declaración únicamente en escenarios de prueba de indicadores remotos. - Compila y prueba la misma combinación de destino e indicadores que se entregará. Si el usuario no indica un navegador, usa el destino predeterminado documentado del proyecto. Cuando la solicitud indique un destino, elige los comandos correspondientes de desarrollo, producción y extremo a extremo, en vez de suponer compatibilidad a partir de otra compilación. ## Crear componentes de interfaz y optimizar solo después de medir Usa componentes funcionales y hooks, desestructura las propiedades en el límite, mantén local el estado que solo sea local y usa la capa de estado compartido únicamente para datos que atraviesen varias funciones. Para asegurar la corrección y el rendimiento del renderizado: - Usa identificadores estables del dominio como claves de las listas dinámicas, nunca las posiciones de la matriz. - Calcula los valores de visualización derivados durante el renderizado, en lugar de copiarlos al estado mediante un efecto. - Memoriza las operaciones costosas de ordenación, filtrado o agregación solo cuando el trabajo repetido sea significativo. - Estabiliza las devoluciones de llamada que se pasan a hijos memorizados cuando los cambios de referencia provoquen nuevos renderizados. - Define fuera del componente los objetos y estilos verdaderamente estáticos. - Considera la virtualización de listas grandes después de medir el coste del renderizado. Copia antes de ordenar cuando las entradas sean inmutables. Analiza primero los componentes que se rendericen con frecuencia o cuyo cálculo sea costoso; no añadas memorización a componentes simples que rara vez se rendericen sin contar con pruebas. ## Reproducir el error con una prueba fallida, corregirlo y volver a probar Para un defecto, añade primero una prueba centrada que reproduzca el fallo, ejecútala y confirma que falla, implementa la corrección mínima, confirma que pasa y después ejecuta la cobertura relacionada directamente. Coloca las pruebas unitarias junto al código fuente y prueba el comportamiento mediante interfaces públicas, no mediante métodos privados. Usa pruebas de integración para los límites entre subsistemas. Usa pruebas de extremo a extremo para flujos de trabajo reales del navegador y compila primero el artefacto de prueba dedicado. Durante la iteración puede aceptarse una compilación más rápida sin protección; la verificación final debe usar la política de seguridad de producción y el destino de navegador solicitado. Cuando se solicite explícitamente una verificación visual: 1. Inicia el entorno real de prueba de la extensión. 2. Inspecciona la pantalla actual antes de actuar. 3. Recorre el flujo del usuario con los controles del navegador. 4. Obtén una captura de pantalla o una descripción de la pantalla final como prueba. 5. Limpia la sesión de prueba incluso después de un fallo. Si la herramienta visual necesaria no está disponible, informa de esa limitación y no afirmes que se verificó visualmente basándote solo en la inspección del código. Revisa los cambios de instantáneas antes de aceptarlos; actualiza una instantánea solo cuando el cambio de comportamiento sea intencionado. ## Escribir una actualización numerada cuando cambie la forma de los datos guardados Crea una actualización numerada cada vez que cambie la estructura del estado persistente. Genérala mediante la herramienta del repositorio para mantener coherentes el orden y el registro. Una actualización debe: - Aceptar correctamente entradas antiguas, incompletas y parcialmente dañadas. - Clonar la entrada y devolver un objeto de estado nuevo, en vez de mutar el valor de quien realiza la llamada. - Transformar solo el intervalo de versiones y las propiedades que le correspondan. - Registrar explícitamente la versión de destino. - Conservar los datos de usuario no relacionados. Prueba estados antiguos representativos, campos ausentes, valores opcionales mal formados, expectativas de idempotencia y el resultado nuevo exacto. Ejecuta tanto la prueba de actualización como las pruebas del controlador o de la función que consuman el estado actualizado. ## Clasificar los errores y corregirlos sin desactivar las comprobaciones Lee el primer error que permita actuar antes de modificar el entorno. Clasifícalo como fallo de formato, tipo, dependencia, política de capacidades, compilación del navegador, datos de prueba, artefacto obsoleto, puerto o importación circular, y luego ejecuta el diagnóstico más acotado para esa clase. Cuando una prueba que antes pasaba falle tras el cambio, determina si la implementación sufrió una regresión o si el comportamiento esperado cambió de forma intencionada. Actualiza la prueba solo en el segundo caso y documenta el motivo del comportamiento. Para fallos de extremo a extremo, comprueba que exista la compilación de prueba correcta y actual, usa la salida de depuración y deja el navegador en ejecución únicamente durante una inspección activa. Para fallos de políticas, regenera la política a partir de las dependencias declaradas y del acceso al anfitrión; no desactives permanentemente su aplicación. Elimina cachés, resultados de compilación, paquetes instalados, datos del navegador o instantáneas solo después de determinar el destino exacto y confirmar que sea seguro regenerarlos. No uses una limpieza amplia como primer paso para resolver problemas. ## Hacer commits, pushes y solicitudes de revisión solo cuando se pidan No modifiques la configuración del repositorio ni ejecutes comandos destructivos de control de versiones. No hagas stage, commit ni push, ni abras una solicitud de revisión a menos que el usuario haya pedido explícitamente esa acción concreta. Cuando exista autorización: - Incluye en el stage solo los archivos que pertenezcan al cambio solicitado. - Formatea y prueba la superficie modificada antes de hacer commit. - Usa la convención estructurada de commits del repositorio. - Haz push únicamente cuando se haya solicitado. - Abre una solicitud de revisión en borrador, salvo que el usuario solicite explícitamente el estado listo. - Sigue la plantilla de revisión y oculta por completo las secciones que no correspondan. Las secciones de pruebas manuales deben describir acciones humanas y resultados visibles, no comandos automatizados de lint o de pruebas. Incluye pruebas del antes y el después para cambios visibles de la interfaz, explica las decisiones que no sean obvias, enlaza el trabajo relacionado e identifica las notas de cambios orientadas al usuario cuando sean necesarias. Durante la revisión, responde a los comentarios y añade commits de seguimiento en lugar de reescribir el historial revisado. Antes de la fusión, exige conversaciones resueltas, aprobaciones, automatización correcta y el título de squash que espere el repositorio. Termina con una lista de comprobación proporcional: formateo de los archivos modificados, tipos, dependencias circulares, pruebas centradas, compilaciones afectadas, archivos relacionados, documentación, políticas de capacidades de producción cuando cambien las dependencias y pruebas visuales reales cuando se soliciten.