Entornos de Desarrollo con Nix

¿Qué hace Entornos de Desarrollo con Nix?

Crea y mantiene entornos de desarrollo de proyectos utilizando Nix flakes, nixpkgs unstable, devenv y direnv. Mantén la interfaz pública del flake pequeña y coloca los detalles específicos del shell en archivos Nix separados.

Contrato de interacción

Trata la configuración de Nix como una política ejecutable del proyecto. No la modifiques ni la actives implícitamente.

1. Inspecciona el repositorio y explica primero los cambios propuestos.
2. Solicita una aprobación explícita antes de crear, editar, renombrar o eliminar archivos. Agrupa las ediciones relacionadas en una sola solicitud clara.
3. Después de que las ediciones sean aprobadas y completadas, propón comandos de validación y solicita una aprobación separada antes de ejecutar cualquiera de ellos.
4. No ejecutes direnv allow sin mencionarlo por su nombre y recibir aprobación. Autoriza la evaluación automática de la configuración del proyecto.

Si el usuario rechaza cualquiera de las aprobaciones, proporciona solo el plan o los comandos y detente en ese límite.

Valores predeterminados y alcance

• Exige un flake para trabajo nuevo. Usa nixpkgs/nixos-unstable a menos que el proyecto ya fije una revisión diferente y el usuario solicite cambiarlo.
• Soporta todos los lenguajes. Agrega paquetes de lenguaje, formateadores, linters, servicios y variables de entorno solo cuando el proyecto los necesite.
• Prefiere nix develop y devShells.<system>.default como la interfaz portátil.
• Usa devenv por sus módulos declarativos, servicios, scripts, pruebas y ganchos de git cuando se necesiten esas características. No crees definiciones duplicadas tanto en un mkShell raw como en devenv sin explicar cuál es la autoritaria.
• Integra direnv a través de un .envrc verificado en el repositorio solo cuando se solicite o cuando el proyecto ya lo use. Preserva las configuraciones de entorno solo locales del usuario.
• Nunca reemplaces ni elimines un shell.nix, flake.nix, .envrc, devenv.nix, lockfile o configuración de CI existente simplemente porque se prefiera un diseño más nuevo.

Inspeccionar antes de proponer cambios

Busca, como mínimo:

• flake.nix, flake.lock, shell.nix, default.nix y el directorio nix/
• devenv.nix, devenv.yaml y .envrc
• Manifiestos y lockfiles de lenguaje, configuración de formateador/linter, ejecutores de tareas y flujos de trabajo de CI
• Documentación del proyecto que mencione comandos de configuración o plataformas soportadas

Lee las expresiones Nix existentes antes de proponer un diseño. Determina si el proyecto ya tiene un flake, qué sistemas soporta, cómo están fijadas las dependencias, si devenv está instalado o configurado, y si direnv está intencionalmente excluido.

Cuando un comando sea útil para el descubrimiento, prefiere comandos de solo lectura como nix flake metadata o nix flake show. Solicita permiso antes de ejecutarlos si la ejecución de comandos no ha sido aprobada previamente por el usuario.

Diseño de archivos

Para un repositorio nuevo o con poca configuración, propón este diseño a menos que la convención establecida del repositorio sea mejor:

.
├── flake.nix
├── flake.lock
├── devenv.nix              # módulos y servicios específicos de devenv, cuando se use
├── .envrc                  # punto de entrada de direnv, cuando se use
└── nix/
    └── devshell.nix        # paquetes, variables y ganchos del shell

flake.nix debe contener inputs, la plomería de sistemas soportados y los outputs exportados. Coloca los argumentos de mkShell, listas de paquetes, variables de entorno y ganchos del shell en nix/devshell.nix. Usa archivos más enfocados bajo nix/ cuando el shell crezca sustancialmente, por ejemplo nix/packages.nix o nix/hooks.nix.

No uses shell.nix para configuraciones nuevas. Si ya existe uno, consérvalo a menos que el usuario apruebe explícitamente un plan de migración. Durante una migración, explica las implicaciones de compatibilidad para los usuarios que aún ejecutan nix-shell.

Flujo de trabajo de diseño

1. Indica la situación actual

Resume los archivos existentes relevantes, las herramientas del proyecto detectadas y cualquier incertidumbre. Si los requisitos están incompletos, haz preguntas específicas como:

• ¿Qué plataformas deben ser soportadas (por ejemplo, solo Linux o Linux y macOS)?
• ¿Qué comandos del proyecto deberían funcionar dentro del shell?
• ¿Se requieren servicios locales como bases de datos?
• ¿Debería devenv ser dueño del entorno, o debería agregar funcionalidades alrededor de un devShell?

2. Propón una implementación

Describe exactamente qué archivos se agregarán o cambiarán y por qué. Incluye si flake.lock cambiará, si se creará o editará .envrc, y qué fuente es dueña de cada dependencia.

Para un flake de propósito general nuevo, usa una estrategia explícita de sistemas soportados y expón devShells.<system>.default. Importa la expresión del shell separada en lugar de colocar todo el cuerpo de mkShell en flake.nix. Mantén el conjunto de paquetes inicial mínimo: no agregues cadenas de herramientas de lenguaje arbitrarias solo para que la plantilla parezca completa.

Si el usuario solicita devenv, selecciona una integración compatible con la configuración de devenv instalada/fijada por versión. Mantén las declaraciones de devenv en devenv.nix (o archivos enfocados que importe). Deja claro si los usuarios entran con nix develop, devenv shell o ambos, y asegúrate de que los puntos de entrada documentados no diverjan silenciosamente.

Para direnv, usa la convención existente del proyecto. Un .envrc basado en flake generalmente depende del soporte de nix-direnv; un .envrc basado en devenv depende de la integración apropiada de devenv. No escribas un punto de entrada cuya extensión de direnv requerida no haya sido identificada.

Trata estos como hechos separados: si nix-direnv está instalado, si está integrado con el direnv de este usuario, y si el .envrc de este proyecto se evalúa correctamente. No uses direnv stdlib (o la ausencia de use flake en su salida) como una verificación de instalación: refleja la biblioteca estándar disponible para esa invocación y no es autoritativa para la configuración declarativa de NixOS o Home Manager. En particular, un resultado vacío de direnv stdlib | grep -F 'use flake' no es evidencia de que nix-direnv esté ausente.

Cuando el descubrimiento esté aprobado, inspecciona la evidencia relevante sin exagerar lo que prueba:

• En NixOS o con configuración de Home Manager disponible, busca programs.direnv.enable = true y programs.direnv.nix-direnv.enable = true (o la configuración de módulo equivalente). Informa esto como configuración declarativa, no como prueba de que el shell activo lo ha cargado.
• Verifica si nix-direnv y direnv están disponibles en el entorno actual e inspecciona el direnvrc aplicable o la configuración de direnv generada cuando sea accesible. Informa un ejecutable no disponible o un archivo de integración faltante como una observación del entorno actual, no como una afirmación sobre la configuración declarativa del usuario.
• Lee el .envrc del proyecto para identificar su extensión requerida. Usa direnv status para inspeccionar su estado actual de autorización/carga. No infieras que un punto de entrada use flake funciona hasta que haya sido evaluado en ese proyecto.

Solo después de la aprobación explícita, autoriza y prueba un .envrc del proyecto. Menciona que direnv allow cambia el estado de confianza; luego ejecuta direnv reload o direnv exec . <comando-inocuo> para ejercitar la configuración. Si no se puede realizar la evaluación, di que la integración no está verificada en lugar de declarar que nix-direnv no está instalado.

3. Obtén aprobación para editar

Usa una solicitud de confirmación concisa similar a:

Agregaré nix/devshell.nix, actualizaré flake.nix para exportar el shell de desarrollo predeterminado, agregaré/actualizaré devenv.nix y .envrc, y generaré/actualizaré flake.lock si la resolución de dependencias lo requiere. ¿Puedo hacer estas ediciones?

Espera una respuesta afirmativa. Si el trabajo propuesto difiere del plan aprobado, pregunta nuevamente antes de hacer las ediciones adicionales.

4. Edita con cuidado

Preserva el formato y las convenciones de nombres locales. Mantén los comentarios enfocados en restricciones no obvias en lugar de repetir la sintaxis de Nix. Fija los inputs del flake a través de flake.lock; no sustituyas URLs flotantes por un archivo de bloqueo.

Al agregar un paquete al shell, prefiere el paquete proporcionado por el pkgs fijado del proyecto. Evita paquetes no libres, concesiones de paquetes inseguros, cachés binarias o configuración de sustituto a menos que el usuario lo solicite y apruebe explícitamente.

5. Propón validación y obtén aprobación separada

Después de las ediciones, enumera solo los comandos relevantes, explica su propósito y solicita aprobación. Selecciona entre:

nix flake check
nix flake show
nix develop --command <comando-de-verificación-del-proyecto-o-versión-de-herramienta>
devenv test
devenv shell -- <comando-de-verificación-del-proyecto-o-versión-de-herramienta>
direnv allow

Usa un comando inocuo para la verificación de entrada al shell cuando sea posible, como --version de una herramienta requerida o el modo de verificación de un formateador del proyecto. Explica el acceso a la red esperado, las compilaciones, descargas o actualizaciones del lockfile antes de comandos que puedan causarlos. Nunca ejecutes nix flake update, recolección de basura amplia, eliminación de almacenamiento o comandos que cambien el perfil a menos que el usuario lo solicite explícitamente.

6. Informa el resultado

Indica los archivos cambiados, los comandos de entrada, los resultados de validación y cualquier paso manual restante. Por ejemplo, identifica si el usuario debe ejecutar nix develop, devenv shell y/o direnv allow después de revisar .envrc.

Principios de solución de problemas

• Reproduce e inspecciona el error real antes de cambiar fijaciones o agregar anulaciones.
• Distingue fallos de evaluación, atributos faltantes, problemas de soporte de plataforma, fallos de compilación y problemas de dependencias en tiempo de ejecución.
• Verifica el input fijado y el atributo del paquete antes de asumir que un paquete inestable existe o tiene el nombre esperado.
• Prefiere una corrección pequeña y documentada sobre cambios globales en la configuración de Nix.
• Cuando un cambio pueda afectar la reproducibilidad o a todos los contribuyentes, presenta alternativas y solicita aprobación antes de editar.

Criterios de finalización

Considera la tarea completa solo cuando la configuración sea modular, el punto de entrada declarado esté documentado en la respuesta final, las verificaciones solicitadas hayan pasado o su resultado esté claramente informado, y cada edición y comando de validación haya sido precedido por la aprobación requerida.