Haz cambios pequeños en una app que funciona sobre un servicio local en segundo plano (daemon)

## Antes de programar, lee los documentos de diseño y aprende qué hace cada carpeta Mantén los cambios pequeños, ajústate a la arquitectura a la que apunta actualmente el repositorio y prefiere los límites documentados de daemon/API antes que el comportamiento heredado de una implementación más antigua que está siendo reemplazada. Aprende la estructura por rol, no por nombre de archivo: - El backend contiene el cliente de línea de comandos, el daemon HTTP de loopback, los servicios, el almacenamiento en base de datos embebida, la lógica de ciclo de vida y de recolección (reaper), los adaptadores de runtime y de espacio de trabajo, y sus pruebas. - El front end de escritorio o web es un supervisor ligero y una superficie de interfaz conectada al daemon mediante un cliente tipado generado. No traslades lógica del daemon a él. - El directorio de documentación contiene las notas actuales de arquitectura y de estado. Léelas antes de cambiar el comportamiento del ciclo de vida, del cliente, del agente, del almacenamiento o del daemon. - Un directorio de pruebas separado contiene los recursos externos de smoke y de extremo a extremo, incluidas las comprobaciones en contenedor de instalación limpia. - Las definiciones del flujo de trabajo de CI son la referencia de lo que debe pasar. Reproduce esos comandos localmente cuando sea posible. Lee en este orden antes de un cambio no trivial: el README de inicio rápido, el índice de la documentación, el documento de arquitectura (modelo mental, distribución de paquetes, límites de ciclo de vida/sesión/servicio y reglas estructurales), el documento de estado (qué está publicado hoy en la rama principal frente a qué sigue en curso) y el documento del cliente (la forma que se pretende que tenga). Si el repositorio además incluye archivos puntero de compatibilidad para otras herramientas de agentes, trátalos como redirecciones a la única guía canónica y no como conjuntos de reglas separados. Localiza los puntos de entrada por responsabilidad en lugar de buscar a ciegas: las implementaciones de comandos, los controladores HTTP y los DTO, los límites de lectura/escritura de los servicios, el vocabulario del dominio, los contratos de puertos, las consultas y migraciones de la base de datos, y el código generado de base de datos viven cada uno en su propio paquete. Sigue los patrones de comandos y de pruebas cercanos antes de introducir un estilo nuevo. ## Ejecuta las comprobaciones del proyecto y mira en pantalla los cambios visuales Usa los comandos agregados del propio repositorio en lugar de inventar comandos improvisados. Desde la raíz del repositorio, estos suelen abarcar: lint (las pruebas del backend más una versión fijada del linter), la comprobación de tipos del front end, la regeneración del código de acceso a la base de datos a partir de las consultas y el esquema, la regeneración de la especificación de la API y de los tipos del front end, y un ejecutor local de flujos de trabajo que valida las definiciones de CI (lo cual puede requerir un socket de contenedor). Las comprobaciones a nivel de componente siguen valiendo la pena ejecutarlas directamente mientras iteras: build, test, test con detección de carreras (race), análisis estático (vet) y arranque del servicio para el backend; comprobación de tipos y build para el front end. Cuando un cambio sea visible en la interfaz, renderízalo de verdad dentro de la sesión con el comando de vista previa del proyecto y observa el resultado. No te limites a describir cómo debería verse el cambio. ## Indica la app de escritorio con actualización automática como única forma de instalar Cuando un proyecto tiene más de una vía de instalación, solo una es canónica, y la guía debe apuntar allí. - La compilación de escritorio con actualización automática publicada mediante releases es la vía de instalación canónica. Dirige primero a los usuarios allí. - Un canal heredado de gestor de paquetes puede seguir funcionando aunque ya no se recomiende. Si se ha publicado una versión final y el paquete está congelado, no recibe más actualizaciones. Sigue siendo una vía de entrada solo para los usuarios que ya tienen el comando en su PATH, donde lanzarlo descarga y abre la compilación canónica. - No añadas funcionalidades, documentación ni flujos que traten un canal heredado congelado como la forma prevista de instalar el producto. ## Cambia solo lo que pide la tarea y respeta la división actual del código - Mantén cada cambio directamente ligado a la tarea. Evita la limpieza de paso, los renombrados amplios, el ruido de formateo, las abstracciones especulativas y las refactorizaciones arquitectónicas salvo que la tarea las pida explícitamente. - Respeta los límites de paquete existentes. El código del cliente llama a las rutas HTTP del daemon a través de los helpers compartidos del cliente; no debe abrir la base de datos, ni lanzar runtimes, ni llamar directamente a los adaptadores. - Mantén cada comando en su archivo de comandos correspondiente y pruébalo con pruebas de tabla al estilo de las pruebas de comandos vecinas. - Replica los DTO de petición y de respuesta en el lado del cliente en lugar de importar los paquetes de controladores del servidor dentro del código del cliente, salvo que esa dependencia ya esté establecida en el paquete. - Devuelve los errores de uso mediante el tipo dedicado de error de uso, de modo que el mal uso por parte del cliente termine con su propio código de estado (por ejemplo, 2), mientras que los fallos de runtime y del daemon terminen con el código de fallo general (por ejemplo, 1). - Conserva los sobres de error de la API y los IDs de petición al exponer errores del daemon, en lugar de aplanarlos en cadenas simples. - Pasa un contexto de cancelación/plazo como primer argumento de cualquier función que realice E/S o trabajo bloqueante. - No añadas abstracciones para casos de uso puntuales. Introduce un helper solo cuando elimine duplicación entre puntos de llamada reales. - Las pruebas deben cubrir el comportamiento visible para el usuario y el límite que se está cambiando: el camino feliz, la validación y los argumentos faltantes, los sobres de error del daemon y cualquier ruta de confirmación destructiva. ## No cambies ni añadas accesos de red al daemon - El listener principal del daemon permanece enlazado a la dirección de loopback y permanece sin autenticación. No cambies su host de enlace y no le añadas autenticación. - El daemon puede ejecutar un segundo listener opcional que se enlace a todas las interfaces para el acceso desde la red local, pero solo mientras esté habilitado explícitamente, solo detrás del middleware de autenticación por contraseña bearer y sirviendo únicamente la API de la aplicación. Ese listener nunca debe servir las rutas de control restringidas a loopback, como el apagado, la telemetría y el control remoto. - Cuando dicho listener sea en texto plano y esté pensado únicamente para una red doméstica de confianza, esa es una decisión deliberada y documentada, registrada en un registro de decisión de arquitectura. Lee ese registro antes de tocarlo. - No añadas ningún otro enlace expuesto a la red. - El cliente de línea de comandos sigue siendo un cliente ligero. No traslades comportamiento antiguo dentro del proceso que eluda las rutas HTTP del daemon. ## Protege los datos guardados y no edites a mano el código de base de datos generado - No almacenes estado derivado ni orientado a la presentación. Deriva el estado a partir de hechos duraderos (estado de actividad, indicador de terminación, hechos de pull request/comprobación/comentario) en el momento de lectura del servicio. - No trates un sondeo de runtime fallido o desconocido como prueba de que una sesión está muerta. - No fuerces el borrado de worktrees registrados que aún tengan cambios sin confirmar. - No modifiques migraciones que ya se hayan fusionado. Añade una migración nueva en su lugar. - No edites a mano el código generado de base de datos. Cambia las consultas o las migraciones y vuelve a ejecutar el generador. - Los eventos de cambio fluyen desde los triggers de la base de datos hacia el registro de cambios. No añadas una vía paralela y manual de emisión de cambios desde los métodos del store, salvo que la arquitectura cambie explícitamente. - Vigila la desincronización entre los artefactos generados de la API y los DTO escritos a mano. Las formas de respuesta de los controladores viven en un único archivo de DTO, y las pruebas pueden verificar la compatibilidad de protocolo entre el cliente y las capas HTTP. - No añadas llamadas de red a las pruebas salvo que el paquete ya tenga un patrón de integración o de extremo a extremo para ellas. Prefiere servidores de prueba en proceso, fakes y dependencias inyectadas. - No confirmes en el repositorio el estado local de ejecución, los datos del daemon, los worktrees temporales, las salidas de compilación ni las credenciales. - Mantén todo el estado de la aplicación bajo el único directorio de estado dedicado, sobrescribible mediante las variables de entorno documentadas. El directorio de datos del daemon, el archivo del proceso en ejecución, los worktrees y los datos de usuario del shell de escritorio (caché del navegador, cookies, almacenamiento local y de sesión, volcados de fallos) deben resolverse todos dentro de él. Nunca leas ni escribas en la ubicación predeterminada de datos de aplicación del sistema operativo. El punto de entrada de escritorio fija la ruta de datos de usuario del shell a ese directorio; no elimines esa sobrescritura ni dependas de la ruta predeterminada. ## Cambia la API en los archivos escritos a mano y vuelve a generar su descripción La API del daemon es code-first. La especificación OpenAPI y los tipos del front end son artefactos generados, así que edita el origen y regenera en lugar de editar las salidas. - Edita el archivo de DTO que define las formas de petición y respuesta. - Edita el registro de operaciones del constructor de la especificación, añadiendo una entrada de nombre de esquema para cualquier tipo recién nombrado. - Regenera con el comando agregado de API del repositorio, que ejecuta en secuencia la generación de la especificación y la generación de tipos. - Verifica con las pruebas del paquete HTTP del servidor; cubren la desincronización de la especificación y la paridad entre rutas y especificación. No cubren los tipos generados del front end, que comprueba un job de CI de desincronización aparte. - Confirma en el repositorio la especificación generada y los tipos generados del front end junto con los cambios del origen. CI regenera ambos y falla si las versiones confirmadas están desactualizadas. - Los DTO del cliente replicados a mano siguen siendo un límite manual deliberado y no se generan. ## Usa una sola solicitud de cambio (pull request) por tema - Crea la rama a partir de la rama principal salvo que estés continuando explícitamente un pull request existente. - Mantén un solo asunto por pull request. Si te piden un trabajo distinto, crea una rama y un pull request separados. - Usa prefijos de mensaje de commit convencionales como feat, fix, docs, test y chore. - Explica en el cuerpo del pull request las omisiones intencionadas, especialmente cuando una implementación predecesora admitía más comportamiento del que admite el dominio de la reescritura actual. - Ejecuta primero las pruebas relevantes más acotadas y después los comandos del repositorio y de CI que correspondan al área que tocaste.