justfile-keeper

Justfile Keeper

Skill pour créer et maintenir des justfile impeccables. Pensée d'abord pour des projets Python sous Windows, mais cross-platform.

Principe directeur

Lire avant d'écrire. Modifier sans détruire. Ne jamais dupliquer.

C'est non-négociable. Les pires erreurs des agents AI sur les justfiles ne viennent pas d'ignorance de la syntaxe — elles viennent d'une réécriture imprudente qui efface des recettes utiles, ajoute des doublons, ou casse le style établi.

Quand utiliser cette skill

Utilise cette skill dès que :

• L'utilisateur veut créer un justfile from scratch
• L'utilisateur veut ajouter, modifier ou supprimer une recette dans un justfile existant
• L'utilisateur signale un justfile qui plante (multi-ligne, interpolation, shell Windows)
• L'utilisateur veut auditer son justfile (qualité, doublons, cohérence)
• L'utilisateur configure just avec Cursor/VS Code

Si un fichier nommé justfile, Justfile, .justfile, *.just est dans le projet — lis-le avant de répondre.

---

Discipline obligatoire (avant TOUT changement)

Règle 1 — READ FIRST

Si un justfile existe, lire le fichier en entier avant toute autre action. Pas de head, pas de grep partiel : view complet ou cat complet. Cette lecture sert à construire l'inventaire de la règle 2.

Règle 2 — INVENTAIRE

Avant d'ajouter quoi que ce soit, dresse mentalement (ou explicitement si demandé) :

• La liste des noms de recettes existantes
• Les alias déclarés (alias t := test)
• Les variables déclarées (name := "...", python := "...")
• Les paramètres globaux (set shell, set windows-shell, set dotenv-load, set export, set positional-arguments)
• La convention de nommage (kebab-case ? snake_case ? mixte ?)
• Le style d'indentation (tabs ou 4 espaces — verrouille-toi sur ce que le fichier utilise déjà)
• La présence de shebangs dans les recettes (#!/usr/bin/env pwsh, etc.)

Règle 3 — ÉDITION CHIRURGICALE

• Toujours utiliser str_replace pour modifier un justfile existant. Jamais de create_file qui écrase tout.
• Si la modif est trop large pour str_replace, faire plusieurs str_replace consécutifs plutôt qu'une réécriture complète.
• Préserver les commentaires existants, l'ordre des recettes, les blocs vides intentionnels.

Règle 4 — ANTI-DOUBLON

Avant d'ajouter une recette X :

1. La recette X existe déjà ? → Demander : modifier l'existante ou la remplacer ?
2. Une recette synonyme existe-t-elle ? (build vs compile, test vs tests, fmt vs format, lint vs check) → Signaler à l'utilisateur avant d'ajouter.
3. Aligner sur la convention existante. Si le fichier a test, ne pas créer tests. Si fmt, ne pas créer format.

Règle 5 — PRÉSERVER LE STYLE

Adopter ce que l'auteur a déjà choisi :

• Indentation (tabs vs 4 espaces vs 2 espaces)
• Quotes ('simple' vs "double" — just les traite différemment ; voir references/syntax-reference.md)
• Style des commentaires (# blabla au-dessus, à droite, ou aucun)
• Recipes silencieuses (@) ou pas
• Présence/absence de set au début

---

Workflows

Mode CREATE — Nouveau justfile

1. Identifier le contexte du projet :

   • Langage principal (Python, JS/TS, Vue, etc.)
   • OS cible (Windows seul, multi-plateforme, Linux seul)
   • Outils utilisés (ruff, pytest, mypy, pre-commit, uv, pip-tools, pandoc, etc.)
   • Présence d'un pyproject.toml, package.json, Cargo.toml

2. Choisir un template de base depuis templates/ :

   • templates/python-base.justfile — Python générique (venv, lint, test, type-check)
   • templates/python-fastapi.justfile — Python avec serveur dev (uvicorn, hot-reload)
   • templates/python-publishing.justfile — Pipeline de publication (markdown → docx → PDF) pour le workflow Fantasy Vixens / Ludomancien
   • templates/multi-platform.justfile — Squelette avec set windows-shell, attributs [unix]/[windows], variables os_family()-aware

3. Adapter le template au projet réel : ne pas copier-coller aveugle, supprimer les recettes non pertinentes.

4. Vérifier avec la checklist d'audit (Mode AUDIT, étape de validation).

Mode AUDIT — Justfile existant à diagnostiquer

Suivre cette checklist dans l'ordre. Pour chaque item, lire le passage pertinent de references/ai-agent-errors.md si nécessaire.

#	Vérification	Si problème →
1	set shell ou set windows-shell présent et cohérent avec l'OS cible ?	Voir references/windows-shell.md
2	Chaque recette multi-ligne a-t-elle un shebang OU se passe sans état partagé entre lignes ?	Voir references/ai-agent-errors.md §2
3	Toutes les {{var}} sont-elles des variables just (pas des $VAR shell mal placés) ?	Voir references/ai-agent-errors.md §3
4	Pas de doublons de recettes (même nom, ou synonymes évidents) ?	Voir Règle 4 ci-dessus
5	Attributs ([private], [group()], [confirm], [unix], [windows], [no-cd]) sur la ligne juste au-dessus de la recette, sans @ mélangé ?	Voir references/syntax-reference.md §Attributs
6	Paramètres avec défauts en quotes simples (arg='val') ? Variadiques (+files, *files) corrects ?	Voir references/syntax-reference.md §Paramètres
7	Pas de .PHONY:, pas de $(VAR) style make, pas de \t imposé ?	Voir references/ai-agent-errors.md §1
8	Une recette default ou _default ou help qui liste les recettes (@just --list) ?	Recommandé, pas obligatoire
9	Variables Python venv-aware si projet Python multi-plateforme ?	Voir references/windows-shell.md §Venv portable
10	set dotenv-load := true si le projet a un .env ? set export := true si les variables doivent passer au shell ?	Voir references/syntax-reference.md §Settings

Produire un rapport d'audit structuré : pour chaque problème détecté, donner ligne, diagnostic, correctif proposé. Ne pas appliquer les correctifs sans confirmation de l'utilisateur, sauf demande explicite.

Mode MODIFY — Ajout/modification ciblée

1. Appliquer la Discipline obligatoire (lire, inventorier).
2. Identifier précisément la zone à modifier (recette, variable, settings).
3. Proposer le diff avant d'écrire (sauf si l'utilisateur demande explicitement d'aller direct).
4. str_replace pour appliquer.
5. Vérifier : la recette ajoutée respecte-t-elle le style ? Pas de doublon ? Indentation cohérente ?

---

Les 5 erreurs critiques à ne jamais commettre

Détails complets dans references/ai-agent-errors.md. Résumé exécutif :

1. Recette multi-ligne sans shebang qui dépend d'un état entre lignes

MAUVAIS :

build:
    cd src
    python -m build      # ❌ on n'est plus dans src/ ici, chaque ligne = nouveau shell
    cp dist/* ../release/

BON (shebang qui force un seul shell) :

build:
    #!/usr/bin/env pwsh
    Set-Location src
    python -m build
    Copy-Item dist/* ../release/

OU (chaîner avec && sur une seule ligne logique) :

build:
    cd src && python -m build && cp dist/* ../release/

2. Confondre {{var}} (just) et $VAR (shell)

{{var}} est interpolé par just au moment du parsing. $VAR est lu par le shell à l'exécution. Ils ne sont PAS interchangeables.

MAUVAIS :

release version:
    git tag $version           # ❌ $version est vide pour le shell
    echo "Released {{ VERSION }}"  # ❌ VERSION pas défini côté just

BON :

release version:
    git tag {{version}}
    echo "Released {{version}}"

3. Réécriture totale d'un justfile existant

Jamais. Toujours str_replace. Voir Règle 3 ci-dessus.

4. Shell Windows non configuré → recette qui marche en CI Linux mais explose en local

# Ajouter en haut du justfile pour Windows :
set windows-shell := ["pwsh.exe", "-NoLogo", "-Command"]
# OU si pwsh pas installé :
set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]

Détails : references/windows-shell.md.

5. Doublons et alias non déclarés

Si l'utilisateur veut t comme raccourci de test :

MAUVAIS : créer une seconde recette t: qui fait la même chose.

BON :

alias t := test

test:
    pytest

---

Ressources bundled

references/

À consulter selon le besoin :

• references/syntax-reference.md — Cheat sheet complet de la syntaxe just (variables, paramètres, attributs, settings, conditionnels, imports/modules, fonctions built-in). Consulter quand tu écris une nouvelle construction et que tu n'es pas certain à 100% de la syntaxe.
• references/ai-agent-errors.md — Top 20 des erreurs typiques d'agents AI sur les justfiles, avec diagnostic et correctif. Consulter en mode AUDIT.
• references/windows-shell.md — Spécificités Windows : choix de shell (cmd vs powershell vs pwsh vs Git Bash), activation venv portable, séparateurs de chemin, attributs [windows]/[unix]/[macos]/[linux]. Consulter dès qu'il y a Windows dans la cible.
• references/editor-integration.md — Intégration Cursor/VS Code : extension recommandée, association de fichiers, lint, snippets, intégration tasks.json si l'utilisateur veut bouton-cliquer dans l'IDE.

templates/

Squelettes réutilisables. Adapter, ne pas copier aveugle :

• templates/python-base.justfile — Projet Python standard : venv, ruff, pytest, mypy, build, clean. Variables venv-aware Windows/Unix.
• templates/python-fastapi.justfile — Étend python-base avec dev (uvicorn hot-reload), migrate, seed.
• templates/python-publishing.justfile — Pipeline éditorial markdown → docx → PDF (Pandoc, Affinity Publisher, ElevenLabs). Adapté au workflow Fantasy Vixens / Ludomancien.
• templates/multi-platform.justfile — Squelette générique avec set windows-shell, attributs [windows]/[unix], variables os_family()-aware.

---

Checklist finale avant de remettre un justfile

Avant de dire "c'est fait", vérifier :

• Lecture initiale faite si fichier existant
• Aucune recette dupliquée (vérifier les synonymes aussi)
• Indentation cohérente dans tout le fichier
• Shell Windows configuré si projet Windows
• Recettes multi-lignes : shebang OU chaînage && OU pas d'état partagé
• Variables {{var}} correctement utilisées, pas de confusion avec $VAR
• set dotenv-load si .env présent dans le projet
• Recette default ou help qui liste les recettes (UX)
• Aucun .PHONY, $(VAR), ou autre vestige Make
• Test mental : la commande just (sans argument) fait quoi ? La commande just <recipe> la plus utilisée fonctionne-t-elle sous Windows ?

Si tout est ✅, remettre le justfile. Sinon, corriger en suivant la Discipline obligatoire.