Shangshui0302/some-NixOS-skills

Développement de paquets Nix

LOI DE FER : NE PAS MODIFIER UNE EXPRESSION DE PAQUET TANT QUE LES INTERFACES CIBLES DE NIXPKGS ET LES PREUVES DE SOURCE AMONT / DE VERSION NE SONT PAS ENREGISTRÉES ; UNE CONSTRUCTION SANS CES PREUVES N'EST PAS UN RÉSULTAT D'EMPAQUETAGE REPRODUCTIBLE.

Signaux d'alerte – revenir à l'étape de preuve si l'un d'eux apparaît :

• Un builder a été sélectionné à partir d'un seul fichier de marqueur ou de la mémoire uniquement.
• Un canal flottant, un résultat de registre ou une URL « latest » est la seule preuve de source.
• Un hachage, un wrapper, une entrée de bureau ou une dépendance d'exécution est deviné.
• nix develop réussit mais la dérivation, la disposition des sorties ou l'exécutable n'ont pas été construits.
• Une construction à sec réussie est rapportée comme un test de déploiement ou d'exécution en direct.

Limite du périmètre

Cette compétence possède l'expression du paquet, ses entrées de construction, son contrat de sortie et son intégration flake ou overlay côté paquet. Traiter les modules NixOS/Home Manager comme des consommateurs : inspecter leur interface de paquet et les construire à sec lorsqu'ils sont dans le périmètre, mais laisser la configuration système et l'activation à nixos-ecosystem.

Lorsque la demande cible le processus de maintenance amont NixOS/nixpkgs – comme classifier une mise à jour ou une panne, adopter un paquet, vérifier les dépendants affectés ou préparer une PR nixpkgs – utiliser nixpkgs-maintainer. Si les deux sont impliqués, cette compétence fournit les preuves de dérivation et la compétence de maintenance possède le workflow amont.

Liste de progression

Copier cette liste dans les notes de travail et la cocher au fur et à mesure de l'avancement :

• Étape 0 : Charger la politique du dépôt et définir le périmètre ⚠️ REQUIS
  • Trouver AGENTS.md, les règles de contribution, les fichiers sales, les consommateurs de paquets et le comportement observable demandé.
  • Classifier la tâche comme ajout, mise à niveau, réparation ou révision.
  • Identifier si l'expression vit dans un dépôt de paquets, un fichier autonome, un flake, un overlay ou un arbre nixpkgs.
• Étape 1 : Passer le portail de fraîcheur ⛔ BLOQUANT
  • Enregistrer la révision nixpkgs cible depuis flake.lock, une entrée de dépôt de paquets épinglée ou le checkout nixpkgs ; indiquer le repli lorsqu'aucun n'existe.
  • Inspecter l'interface verrouillée du builder/helper et la comparer avec la documentation officielle actuelle.
  • Signaler la dérive et l'impact de migration ; ne jamais appliquer silencieusement une API plus récente à un verrou plus ancien.
• Étape 2 : Rassembler les preuves de source et de paquet ⚠️ REQUIS
  • Rechercher dans l'arbre cible, l'entrée nixpkgs pertinente, les overlays et les helpers existants pour un paquet ou une implémentation existante.
  • Vérifier le tag/commit amont, les commandes de construction, le CI, la licence, la plateforme, l'artefact, le nom de l'exécutable et la disposition d'installation.
  • Choisir la route la plus étroite : source, ELF préconstruit, AppImage, Electron/ASAR, données, police/thème ou plugin.
• Étape 3 : Présenter le plan minimal ⚠️ REQUIS pour les modifications non triviales
  • Indiquer les fichiers, dépendances, risques, commandes de vérification et ce qui restera non vérifié.
  • Demander avant les modifications destructrices, l'installation, l'activation système, le commit, le push ou la création d'une PR.
• Étape 4 : Implémenter la plus petite dérivation
  • Épingler pname, version, source/révision et hachages SRI ; utiliser pname/version de manière cohérente dans les URL et les noms de fichiers.
  • Utiliser le builder nixpkgs le plus étroit et les phases par défaut ; les phases personnalisées doivent exécuter leurs hooks correspondants.
  • Séparer les outils de construction, les bibliothèques de lien/exécution, les outils de test et les commandes fournies par le wrapper.
  • Compléter l'intégration GUI comme une unité : wrapper, entrée de bureau, icône, Exec et drapeaux d'exécution.
  • Préserver ou exposer la surface de paquet existante de la cible — sortie flake, overlay ou attribut de paquet — uniquement lorsqu'elle est dans le périmètre.
• Étape 5 : Vérifier par couches ⚠️ REQUIS
  • Analyser, évaluer/vérifier, construire, inspecter la sortie du store et exécuter un test de fumée sûr.
  • Exécuter une construction à sec système uniquement lorsque le paquet est intégré dans NixOS/Home Manager.
  • Garder les statuts de construction, de fumée, de construction à sec et post-activation/en direct séparés.
• Étape 6 : Rapporter et maintenir
  • Rapporter les preuves, les fichiers modifiés, les hachages, les vérifications, les bloqueurs et l'étape manuelle suivante exacte.
  • Pour les mises à niveau, revérifier le journal des modifications, les lockfiles, la licence, la disposition des artefacts et tous les hachages.
  • Ajouter un script de mise à jour uniquement après que le chemin de mise à jour est prouvé stable et déterministe.

Portail de fraîcheur

Charger references/freshness-and-evidence.md avant de sélectionner un builder ou d'écrire un nouveau hachage. Utiliser gh pour les investigations GitHub. Préférer la source nixpkgs verrouillée pour les faits d'API, et utiliser la documentation officielle actuelle Nixpkgs/nix.dev pour détecter les changements de processus. En cas de désaccord, marquer une pause et expliquer si le changement est compatible avec le verrou, nécessite une mise à jour du verrou, ou doit rester une exception documentée.

Routage du builder et de l'implémentation

Charger uniquement la section pertinente de references/builder-routing.md après l'étape de preuve. Ne pas ajouter un large ensemble de dépendances pour cacher un échec de phase inconnu. Préférer une construction source lorsqu'elle est maintenable ; utiliser un binaire de version ou AppImage uniquement lorsque la route source amont est indisponible ou sensiblement moins fiable.

Pour les buildPhase, checkPhase ou installPhase personnalisées, préserver les runHook preX et runHook postX correspondants. Pour le code natif préconstruit, enregistrer la provenance et inspecter l'architecture, l'interpréteur, les bibliothèques NEEDED et les licences des composants regroupés.

Validation

Charger references/validation.md pour la matrice de types de paquets et les vérifications de sortie. Adapter les vérifications suivantes à la surface de paquet de la cible :

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # lorsque la cible expose un flake
nix build path:.#pname -L --no-link --print-out-paths  # utiliser le nom de sortie de la cible
git diff --check

Si le paquet est intégré dans une configuration NixOS/Home Manager, exécuter également :

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

Utiliser scripts/validate-skill.py pour vérifier ce dépôt de compétence lui-même. C'est un lint déterministe, pas un substitut à la construction du paquet cible.

Lorsque l'utilisateur demande « exécuter la validation » sans nommer un consommateur, par défaut évaluation de paquet, construction, inspection de sortie et un test de fumée sûr. Ajouter une construction à sec NixOS/Home Manager ou autre consommateur uniquement lorsque ce consommateur est dans le périmètre.

Mises à jour et maintenance de fraîcheur

Charger references/update-policy.md pour les mises à jour répétées. Épingler les entrées de source et de documentation, rendre les vérifications de mise à jour explicites et garder le travail automatique en lecture seule par défaut. Une tâche automatisée peut ouvrir une modification de mise à jour révisable après la réussite des vérifications ; elle ne doit pas réécrire silencieusement une compétence, changer un système, commiter ou pousser.

Quatre formes de demande concrètes

Charger references/examples.md lorsque la demande est ambiguë. Les formes supportées sont : ajouter un paquet à un dépôt de paquets, expression autonome, flake ou overlay ; mettre à niveau une dérivation existante et rafraîchir les hachages source/dépendance ; réparer un paquet préconstruit/AppImage, Electron, police/thème ou plugin ; et intégrer un paquet via un flake ou overlay existant pour un consommateur.

Anti-patrons

• Ne pas utiliser le succès de nix develop comme preuve que nix build fonctionne.
• Ne pas choisir un builder à partir de Cargo.toml, package.json ou d'une seule dépendance devinée.
• Ne pas récupérer de dépendances en ligne pendant une construction en bac à sable (cargo fetch, npm install, pip install, etc.).
• Ne pas utiliser d'URL flottantes, de branches mutables, de hachages à l'ancienne ou de littéraux de version dupliqués dans une expression.
• Ne pas cacher les bibliothèques manquantes avec autoPatchelfIgnoreMissingDeps, un wrapper FHS par défaut ou une liste buildInputs surdimensionnée.
• Ne pas prétendre que le comportement bureau, IPC, lecture, Wayland ou compositeur a été testé alors que seule la dérivation a été construite.
• Ne pas traiter les vérifications d'expression de paquet comme une intégration nixpkgs ou une révision de PR ; utiliser nixpkgs-maintainer pour ce workflow amont.
• Ne pas exécuter nixos-rebuild switch, commiter, pousser, supprimer des fichiers ou créer une PR sans autorisation explicite.

Format de livraison

Retourner un rapport de preuves compact :

1. Périmètre et route — dépôt cible / surface publique, type de tâche, type de paquet et pourquoi ce builder a été choisi.
2. Preuves — révision nixpkgs/API verrouillée, révision/artefact/licence amont et hachages pertinents.
3. Modifications — expression de paquet, surface flake ou overlay, consommateurs et documentation.
4. Vérification — analyse, vérification flake, construction, sortie/fumée, construction à sec et statut en direct séparément.
5. Action suivante — commande manuelle exacte ou décision utilisateur encore nécessaire.

Ne jamais déclarer un paquet « terminé » alors qu'une vérification requise est manquante ; étiqueter le bloqueur et la plus petite expérience suivante à la place.