goromal/agent-skills

Cette machine exécute NixOS ; toute la configuration système réside dans le dépôt anixpkgs, cloné dans ~/sources/anixpkgs (canonique) et éventuellement dans un autre chemin (par exemple /data/andrew/dev/claude/sources/anixpkgs). Les arbres courants se déploient via leur configuration flake ; anix-upgrade conserve le chemin basé sur les canaux pour les arbres plus anciens.

Workflow

1. Éditer le module Nix ou le script Python/shell concerné sous pkgs/.
2. Stager les nouveaux fichiers — git-cc (utilisé par anix-upgrade) ne copie que les fichiers suivis par Git (git ls-files). Utilisez git add pour les nouveaux fichiers d'abord, sinon ils seront silencieusement absents de la construction.
3. Déployer via l'API locale anix-upgrade-ui (recommandée), en streaming jusqu'à la fin :

   upgrade_host="$(hostname).local"
   curl -si "http://${upgrade_host}/anix-upgrade/api/v1/run" -X POST \
     -H 'Content-Type: application/json' \
     -d '{"source": "/path/to/anixpkgs", "local": true}'
   # 202 → {"run_id": "<uuid>", "started": true} ;  409 → déjà en cours
   curl -N "http://${upgrade_host}/anix-upgrade/api/v1/stream/<run_id>"
   # se termine par [UPGRADE SUCCESSFUL] ou [UPGRADE FAILED (exit N)], puis [DONE]
   

   Utilisez le nom d'hôte .local de la machine, pas localhost : nginx expose cette route uniquement sur l'hôte virtuel spécifique à la machine. Solution de repli en CLI (uniquement si l'API est inaccessible) : anix-upgrade --local -s /path/to/anixpkgs.
4. Tester le résultat sur cette machine avant de commiter.

"local": true est obligatoire lorsque la modification touche un paquet de service ou un module NixOS — sans cela, anix-upgrade laisse dependencies.nix avec local-build = false, donc les valeurs par défaut de cfg.package du module se résolvent en binaire de la publication et la modification ne prend pas effet silencieusement.

Pièges importants

• Les modules NixOS doivent être importés au bon endroit (par exemple, la liste d'imports de pc-base.nix) — ajouter un fichier ne suffit pas.
• Les nouvelles options doivent être déclarées dans pkgs/nixos/components/opts.nix et assignées dans pc-base.nix avant d'être utilisées dans des composants comme base-dev-pkgs.nix.
• Les serveurs MCP s'enregistrent par utilisateur via claude mcp add -s user ... ; le script claude-setup (dans base-dev-pkgs.nix) gère cela et doit être réexécuté après avoir ajouté un serveur.

Déploiement sur d'autres machines / Référence API

La même API s'exécute sur chaque machine hébergeant anix-upgrade-ui : http://<hostname>.local/anix-upgrade/api/v1/ (pas d'authentification). Champs du corps de run (tous optionnels) : version, commit, branch, source (chemin local), local, boot — mêmes sémantiques que les drapeaux anix-upgrade. Utilisez -si pour afficher les en-têtes de réponse (certains proxies suppriment les corps JSON -s).

Pour une machine distante, poussez d'abord et passez commit (un hachage complet), pas branch — les tarballs de branche sont mis en cache sur le CDN et peuvent être obsolètes pendant des minutes même avec --tarball-ttl 0 ; un hachage de commit utilise fetchGit adressé par contenu et contourne le CDN :

curl -si -X POST http://<hostname>.local/anix-upgrade/api/v1/run \
  -H 'Content-Type: application/json' \
  -d "{\"commit\": \"$(git rev-parse HEAD)\", \"local\": true}"

Surveiller une exécution (run_id renvoie 404 dès qu'une exécution plus récente commence, donc récupérez les logs avant de relancer) :

curl -s  .../api/v1/status/<run_id> | jq .   # statut : running|success|failed
curl -N  .../api/v1/stream/<run_id>          # SSE : rejoue les 512 Ko derniers, puis en direct
curl -o upgrade.log .../api/v1/log/<run_id>  # log complet

Les exécutions apparaissent dans l'interface navigateur à http://<hostname>.local/anix-upgrade/ avec un badge via API ; une seule exécution par machine à la fois (l'API et l'interface manuelle se bloquent mutuellement).