Shangshui0302/some-NixOS-skills

Desarrollo de Paquetes Nix

LEY DE HIERRO: NO CAMBIE UNA EXPRESIÓN DE PAQUETE HASTA QUE SE HAYAN REGISTRADO LAS INTERFACES OBJETIVO DE NIXPKGS Y LA EVIDENCIA DE LA FUENTE O VERSIÓN ASCENDENTE; UNA CONSTRUCCIÓN SIN DICHA EVIDENCIA NO ES UN RESULTADO DE EMPAQUETADO REPRODUCIBLE.

Banderas rojas — regrese al paso de evidencia si aparece alguna:

• Un builder fue seleccionado únicamente por un archivo marcador o por memoria.
• Un canal flotante, resultado de registro o URL "latest" es la única evidencia de fuente.
• Se adivina un hash, wrapper, entrada de escritorio o dependencia en tiempo de ejecución.
• nix develop tiene éxito pero la derivación, el diseño de salida o el ejecutable no se construyeron.
• Una construcción seca exitosa se reporta como una prueba de implementación o de tiempo de ejecución en vivo.

Límite de alcance

Esta skill posee la expresión del paquete, sus entradas de construcción, contrato de salida e integración de flake u overlay orientada al paquete. Trate los módulos de NixOS/Home Manager como consumidores: inspeccione su interfaz de paquete y realice una construcción seca cuando estén en alcance, pero deje la configuración del sistema y la activación a nixos-ecosystem.

Cuando la solicitud tenga como objetivo el proceso de mantenimiento ascendente de NixOS/nixpkgs —como clasificar una actualización o fallo, adoptar un paquete, verificar dependientes afectados o preparar un PR de nixpkgs— use nixpkgs-maintainer. Si ambos están involucrados, esta skill proporciona evidencia de derivación y la skill de mantenedor posee el flujo de trabajo ascendente.

Lista de verificación de progreso

Copie esta lista de verificación en las notas de trabajo y márquela a medida que avanza la tarea:

• Paso 0: Cargar la política del repositorio y definir el alcance ⚠️ REQUERIDO
  • Encuentre AGENTS.md, reglas de contribución, archivos sucios, consumidores del paquete y el comportamiento observable solicitado.
  • Clasifique la tarea como agregar, actualizar, reparar o revisar.
  • Identifique si la expresión se encuentra en un repositorio de paquetes, archivo independiente, flake, overlay o árbol de nixpkgs.
• Paso 1: Pasar la puerta de frescura ⛔ BLOQUEANTE
  • Registre la revisión de nixpkgs objetivo de flake.lock, una entrada de repositorio de paquetes fijada o el checkout de nixpkgs; indique el fallback cuando no exista ninguno.
  • Inspeccione la interfaz de builder/ayudante bloqueada y compárela con la documentación oficial actual.
  • Reporte la deriva y el impacto de migración; nunca aplique silenciosamente una API más nueva a un bloqueo más antiguo.
• Paso 2: Recopilar evidencia de fuente y paquete ⚠️ REQUERIDO
  • Busque en el árbol objetivo, la entrada relevante de nixpkgs, overlays y ayudantes existentes un paquete o implementación existentes.
  • Verifique la etiqueta/commit ascendente, comandos de construcción, CI, licencia, plataforma, artefacto, nombre del ejecutable y diseño de instalación.
  • Elija la ruta más estrecha: fuente, ELF preconstruido, AppImage, Electron/ASAR, datos, fuente/tema o plugin.
• Paso 3: Presentar el plan mínimo ⚠️ REQUERIDO para ediciones no triviales
  • Indique archivos, dependencias, riesgos, comandos de verificación y lo que permanecerá sin verificar.
  • Pregunte antes de ediciones destructivas, instalación, activación del sistema, commit, push o creación de PR.
• Paso 4: Implementar la derivación más pequeña
  • Fije pname, version, fuente/revisión y hashes SRI; use pname/version de manera consistente en URLs y nombres de archivo.
  • Use el builder más estrecho de nixpkgs y las fases predeterminadas; las fases personalizadas deben ejecutar sus hooks correspondientes.
  • Separe herramientas de construcción, bibliotecas de enlace/tiempo de ejecución, herramientas de prueba y comandos proporcionados por wrappers.
  • Complete la integración GUI como una unidad: wrapper, entrada de escritorio, icono, Exec y flags de tiempo de ejecución.
  • Preserve o exponga la superficie de paquete existente del objetivo —salida de flake, overlay o atributo de paquete— solo cuando esté en alcance.
• Paso 5: Verificar en capas ⚠️ REQUERIDO
  • Parsear, evaluar/verificar, construir, inspeccionar la salida del almacén y ejecutar una prueba de humo segura.
  • Ejecutar la construcción seca del sistema solo cuando el paquete esté integrado en NixOS/Home Manager.
  • Mantenga separados los estados de construcción, humo, construcción seca y post-activación/en vivo.
• Paso 6: Reportar y mantener
  • Reporte evidencia, archivos cambiados, hashes, verificaciones, bloqueadores y el siguiente paso manual exacto.
  • Para actualizaciones, vuelva a verificar el changelog, lockfiles, licencia, diseño del artefacto y todos los hashes.
  • Agregue un script de actualización solo después de que la ruta de actualización esté probada como estable y determinista.

Puerta de frescura

Cargue references/freshness-and-evidence.md antes de seleccionar un builder o escribir un nuevo hash. Use gh para investigaciones de GitHub. Prefiera la fuente nixpkgs bloqueada para hechos de API, y use la documentación oficial actual de Nixpkgs/nix.dev para detectar cambios de proceso. Cuando no estén de acuerdo, pausa y explique si el cambio es compatible con el bloqueo, requiere una actualización del bloqueo o debe permanecer como una excepción documentada.

Enrutamiento de builder e implementación

Cargue solo la sección relevante de references/builder-routing.md después del paso de evidencia. No agregue un conjunto amplio de dependencias para ocultar una falla de fase desconocida. Prefiera una construcción fuente cuando sea mantenible; use un binario de versión o AppImage solo cuando la ruta fuente ascendente no esté disponible o sea materialmente menos confiable.

Para buildPhase, checkPhase o installPhase personalizadas, preserve los correspondientes runHook preX y runHook postX. Para código nativo preconstruido, registre la procedencia e inspeccione la arquitectura, intérprete, bibliotecas NEEDED y licencias de componentes empaquetados.

Validación

Cargue references/validation.md para la matriz de tipos de paquete y las comprobaciones de salida. Adapte las siguientes comprobaciones a la superficie del paquete objetivo:

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # when the target exposes a flake
nix build path:.#pname -L --no-link --print-out-paths  # use the target output name
git diff --check

Si el paquete está conectado a una configuración de NixOS/Home Manager, ejecute también:

nixos-rebuild dry-build --flake path:.

Use scripts/validate-skill.py para verificar este repositorio de skill en sí mismo. Es un lint determinista, no un sustituto de la construcción del paquete objetivo.

Cuando el usuario pida "ejecutar validación" sin nombrar un consumidor, predetermine a evaluación del paquete, construcción, inspección de salida y una prueba de humo segura. Agregue una construcción seca de NixOS/Home Manager u otro consumidor solo cuando ese consumidor esté en alcance.

Actualizaciones y mantenimiento de frescura

Cargue references/update-policy.md para actualizaciones repetidas. Fije las entradas de fuente y documentación, haga explícitas las comprobaciones de actualización y mantenga el trabajo automático como solo lectura de manera predeterminada. Un trabajo automatizado puede abrir un cambio de actualización revisable después de que las comprobaciones hayan pasado; no debe reescribir silenciosamente una skill, cambiar un sistema, hacer commit o push.

Cuatro formas concretas de solicitud

Cargue references/examples.md cuando la solicitud sea ambigua. Las formas compatibles son: agregar un paquete a un repositorio de paquetes, expresión independiente, flake u overlay; actualizar una derivación existente y refrescar hashes de fuente/dependencia; reparar un paquete preconstruido/AppImage, Electron, fuente/tema o plugin; e integrar un paquete a través de un flake u overlay existente para un consumidor.

Anti-patrones

• No use el éxito de nix develop como prueba de que nix build funciona.
• No elija un builder solo de Cargo.toml, package.json o una dependencia adivinada.
• No obtenga dependencias en línea durante una construcción en entorno aislado (cargo fetch, npm install, pip install y similares).
• No use URLs de fuente flotantes, ramas mutables, hashes de estilo antiguo o literales de versión duplicados en una expresión.
• No oculte bibliotecas faltantes con autoPatchelfIgnoreMissingDeps, un wrapper FHS predeterminado o una lista buildInputs sobredimensionada.
• No afirme que el comportamiento de escritorio, IPC, reproducción, Wayland o compositor fue probado cuando solo la derivación se construyó.
• No trate las comprobaciones de expresión de paquete como integración de nixpkgs o revisión de PR; use nixpkgs-maintainer para ese flujo de trabajo ascendente.
• No ejecute nixos-rebuild switch, haga commit, push, elimine archivos o cree un PR sin autorización explícita.

Formato de entrega

Devuelva un informe de evidencia compacto:

1. Alcance y ruta — repositorio/superficie pública objetivo, tipo de tarea, tipo de paquete y por qué se eligió este builder.
2. Evidencia — revisión/API bloqueada de nixpkgs, revisión/artefacto/licencia ascendente y hashes relevantes.
3. Cambios — expresión del paquete, superficie de flake u overlay, consumidores y documentación.
4. Verificación — parseo, verificación de flake, construcción, salida/humo, construcción seca y estado en vivo por separado.
5. Acción siguiente — comando manual exacto o decisión del usuario aún requerida.

Nunca llame a un paquete "terminado" mientras falte una comprobación requerida; etiquete el bloqueador y el siguiente experimento más pequeño en su lugar.