napkinstack 0.1.0__py3-none-any.whl

napkinstack/fitness/manifests.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""
+Fitness function 1 — Validation des manifests.
+
+Vérifie que chaque module déclare ce qu'il doit déclarer et que son état de
+cycle de vie est cohérent (docs/os/02-modules.md §6, docs/os/07-gouvernance.md §3).
+
+Contrôles :
+  M1  chaque module possède un MANIFEST.yaml
+  M2  champs obligatoires présents
+  M3  valeurs de lifecycle / criticality valides
+  M4  responsabilité en UNE phrase (pas de "et" coordonnant deux capacités)
+  M5  module Déprécié → removal_date obligatoire et non dépassée
+  M6  contrat deprecated → removal_date obligatoire et non dépassée
+  M7  verbes standards déclarés (check / test au minimum)
+  M8  runbook obligatoire si criticality >= eleve
+  M9  enveloppe de fichiers complète (AGENTS.md, README.md, tests/)
+
+Usage :  nstack manifests [--root RACINE]
+Sortie :  0 si tout passe, 1 sinon. Chaque échec explique la règle violée.
+"""
+
+from __future__ import annotations
+import sys
+import datetime
+from pathlib import Path
+
+import yaml
+
+LIFECYCLES = {"Proposé", "Actif", "Maintenance", "Déprécié", "Retiré"}
+CRITICALITIES = {"prototype", "standard", "eleve", "critique"}
+REQUIRED_FIELDS = ["name", "responsibility", "owner", "lifecycle", "criticality"]
+REQUIRED_COMMANDS = ["check", "test"]
+MODULE_DIRS = ["modules", "services", "apps", "packages", "contracts", "platform"]
+MODULE_BASES = ["modules", "services", "apps", "packages"]  # bases dont chaque dossier est un module
+SECTIONS = {"module": dict, "provides": list, "consumes": list, "data": dict,
+            "commands": dict, "docs": dict, "dependencies": list}
+TYPES = {dict: "dictionnaire", list: "liste"}
+
+failures: list[str] = []
+warnings: list[str] = []
+
+
+def fail(module: str, rule: str, message: str) -> None:
+    failures.append(f"[{rule}] {module}\n      {message}")
+
+
+def warn(module: str, rule: str, message: str) -> None:
+    warnings.append(f"[{rule}] {module}\n      {message}")
+
+
+def find_manifests(root: Path) -> list[Path]:
+    found = []
+    for base in MODULE_DIRS:
+        d = root / base
+        if not d.is_dir():
+            continue
+        for manifest in sorted(d.glob("*/MANIFEST.yaml")):
+            found.append(manifest)
+        direct = d / "MANIFEST.yaml"
+        if direct.is_file():
+            found.append(direct)
+    return found
+
+
+def find_orphans(root: Path) -> list[Path]:
+    """Dossiers de module sans MANIFEST.yaml (M1)."""
+    return [enfant for base in MODULE_BASES if (root / base).is_dir()
+            for enfant in sorted((root / base).iterdir())
+            if enfant.is_dir() and not enfant.name.startswith(".") and not (enfant / "MANIFEST.yaml").is_file()]
+
+
+def parse_date(value) -> datetime.date | None:
+    if isinstance(value, datetime.date):
+        return value
+    try:
+        return datetime.date.fromisoformat(str(value))
+    except ValueError:
+        return None
+
+
+def check_manifest(path: Path, today: datetime.date) -> None:
+    rel = path.parent.name
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        fail(rel, "M2", f"MANIFEST.yaml illisible : {exc}")
+        return
+    if not isinstance(data, dict):
+        fail(rel, "M2", "MANIFEST.yaml doit être un dictionnaire YAML (sections module, commands, docs…).")
+        return
+    for section, attendu in SECTIONS.items():
+        if data.get(section) is not None and not isinstance(data[section], attendu):
+            fail(rel, "M2", f"section {section} : {TYPES[attendu]} attendu, "
+                            f"{type(data[section]).__name__} trouvé.")
+            data[section] = attendu()
+
+    mod = data.get("module") or {}
+
+    # M2 — champs obligatoires
+    for field in REQUIRED_FIELDS:
+        if not mod.get(field):
+            fail(rel, "M2", f"champ obligatoire manquant : module.{field}")
+
+    # M3 — valeurs valides
+    lifecycle = mod.get("lifecycle")
+    if lifecycle and lifecycle not in LIFECYCLES:
+        fail(rel, "M3", f"lifecycle invalide : '{lifecycle}'. Attendu : {sorted(LIFECYCLES)}")
+    criticality = mod.get("criticality")
+    if criticality and criticality not in CRITICALITIES:
+        fail(rel, "M3", f"criticality invalide : '{criticality}'. Attendu : {sorted(CRITICALITIES)}")
+
+    # M4 — responsabilité en une phrase
+    resp = (mod.get("responsibility") or "").strip()
+    if resp:
+        if resp.count(".") > 1:
+            warn(rel, "M4", "responsabilité en plusieurs phrases : le module fait-il deux choses ?")
+        if " et " in resp.lower() and len(resp.split()) > 12:
+            warn(rel, "M4", f"responsabilité contient 'et' : capacité cohérente ? → \"{resp}\"")
+
+    # M5 — dépréciation du module
+    if lifecycle == "Déprécié":
+        dep = mod.get("deprecation")
+        dep = dep if isinstance(dep, dict) else {}
+        removal = parse_date(dep.get("removal_date"))
+        if not removal:
+            fail(rel, "M5", "module Déprécié sans module.deprecation.removal_date valide (AAAA-MM-JJ)")
+        elif removal < today:
+            fail(rel, "M5", f"date de retrait dépassée ({removal}). État intermédiaire permanent — "
+                            "retirer le module ou superséder la décision.")
+
+    # M6 — dépréciation des contrats produits
+    for provided in data.get("provides") or []:
+        if not isinstance(provided, dict):
+            fail(rel, "M2", "entrée de provides : dictionnaire attendu (contract, version, stability).")
+            continue
+        if provided.get("stability") == "deprecated":
+            name = f"{provided.get('contract')}@{provided.get('version')}"
+            removal = parse_date(provided.get("removal_date"))
+            if not removal:
+                fail(rel, "M6", f"contrat déprécié {name} sans removal_date")
+            elif removal < today:
+                fail(rel, "M6", f"contrat {name} : date de retrait dépassée ({removal}). "
+                                "Terminer la contraction (docs/os/03-contrats.md §4).")
+
+    # M7 — verbes standards
+    commands = data.get("commands") or {}
+    for verb in REQUIRED_COMMANDS:
+        if not commands.get(verb):
+            fail(rel, "M7", f"verbe standard manquant : commands.{verb} "
+                            "(docs/os/09-plateforme.md §2)")
+
+    # M8 — runbook si criticité élevée
+    if criticality in {"eleve", "critique"}:
+        runbook = (data.get("docs") or {}).get("runbook")
+        if not runbook or not (path.parent / runbook).is_file():
+            fail(rel, "M8", f"criticality={criticality} exige un runbook existant "
+                            "(docs/os/08-qualite.md §7)")
+
+    # M9 — enveloppe de fichiers
+    for expected in ["AGENTS.md", "README.md"]:
+        if not (path.parent / expected).is_file():
+            fail(rel, "M9", f"fichier d'enveloppe manquant : {expected}")
+    if not (path.parent / "tests").is_dir() and criticality != "prototype":
+        fail(rel, "M9", "dossier tests/ absent")
+
+
+def run(root: Path) -> int:
+    failures.clear()
+    warnings.clear()
+    today = datetime.date.today()
+    manifests = find_manifests(root)
+    orphans = find_orphans(root)
+    if not manifests and not orphans:
+        print("Aucun MANIFEST.yaml trouvé. Rien à valider.")
+        return 0
+    for orphan in orphans:
+        fail(orphan.name, "M1", f"{orphan.relative_to(root)}/ n'a pas de MANIFEST.yaml. "
+                                "Action : le créer, ou créer le module avec nstack new-module.")
+
+    for manifest in manifests:
+        check_manifest(manifest, today)
+
+    print(f"Manifests analysés : {len(manifests)}")
+    for w in warnings:
+        print(f"  AVERTISSEMENT {w}")
+    for f in failures:
+        print(f"  ÉCHEC {f}")
+
+    if failures:
+        print(f"\n{len(failures)} violation(s). Voir docs/os/02-modules.md et docs/os/07-gouvernance.md.")
+        return 1
+    print("Manifests : conformes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run(Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()))

napkinstack/fitness/pr_scope.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Fitness function 3 — Périmètre et taille de la PR.
+#
+#   P1  une PR = un module            → BLOQUANT  (docs/os/02-modules.md §7)
+#   P2  budget de revue respecté      → AVERTISSEMENT (docs/os/05-workflow.md §4)
+#
+# Le label `cross-module` lève P1. Le label `hors-budget` documente P2.
+# Les deux sont volontairement visibles : ils rendent l'exception comptable
+# (docs/os/10-mesure.md §3).
+#
+# Usage local :  nstack pr-scope [--base BASE] [--root RACINE]   (base par défaut : origin/main)
+# En CI      :   PR_LABELS="cross-module,bug" bash src/napkinstack/fitness/pr_scope.sh "$BASE_SHA"
+
+set -uo pipefail
+
+BASE="${1:-origin/main}"
+LABELS="${PR_LABELS:-}"
+MAX_LINES="${MAX_LINES:-400}"
+MAX_FILES="${MAX_FILES:-15}"
+
+if ! git rev-parse --verify "$BASE" >/dev/null 2>&1; then
+  echo "Base '$BASE' introuvable — check ignoré."
+  exit 0
+fi
+
+CHANGED=$(git diff --name-only "$BASE"...HEAD)
+[ -z "$CHANGED" ] && { echo "Aucun fichier modifié."; exit 0; }
+
+# Modules touchés (modules/, services/, apps/, packages/)
+MODULES=$(echo "$CHANGED" \
+  | grep -E '^(modules|services|apps|packages)/[^/]+/' \
+  | cut -d/ -f1-2 | sort -u)
+COUNT=$(echo "$MODULES" | grep -c . || true)
+
+echo "Fichiers modifiés : $(echo "$CHANGED" | wc -l | tr -d ' ')"
+echo "Modules touchés   : $COUNT"
+[ "$COUNT" -gt 0 ] && echo "$MODULES" | sed 's/^/  - /'
+
+STATUS=0
+
+# --- P1 : une PR = un module ---------------------------------------------
+if [ "$COUNT" -gt 1 ]; then
+  if echo "$LABELS" | grep -q 'cross-module'; then
+    echo
+    echo "AVERTISSEMENT [P1] PR cross-module autorisée par label."
+    echo "  Comptée comme exception. Un taux qui monte = frontière qui se dégrade."
+  else
+    echo
+    echo "ÉCHEC [P1] Cette PR touche $COUNT modules."
+    echo "  Une PR = un module (docs/os/02-modules.md §7)."
+    echo "  Un changement de contrat se fait en séquence expand/contract,"
+    echo "  jamais en une PR unique (docs/os/03-contrats.md §4)."
+    echo "  Si l'exception est justifiée : ajouter le label 'cross-module'."
+    STATUS=1
+  fi
+fi
+
+# --- P2 : budget de revue ------------------------------------------------
+STATS=$(git diff --numstat "$BASE"...HEAD \
+  | grep -vE '(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|go\.sum|uv\.lock|\.generated\.|/generated/)' \
+  || true)
+LINES=$(echo "$STATS" | awk '{ a += $1 + $2 } END { print a+0 }')
+FILES=$(echo "$STATS" | grep -c . || true)
+
+echo
+echo "Budget de revue : ${LINES}/${MAX_LINES} lignes, ${FILES}/${MAX_FILES} fichiers"
+
+if [ "$LINES" -gt "$MAX_LINES" ] || [ "$FILES" -gt "$MAX_FILES" ]; then
+  if echo "$LABELS" | grep -q 'hors-budget'; then
+    echo "AVERTISSEMENT [P2] Hors budget, justifié par label."
+  else
+    echo "AVERTISSEMENT [P2] Hors budget de revue."
+    echo "  Le débit du projet est le débit de VÉRIFICATION, pas de génération."
+    echo "  Redécouper, ou ajouter le label 'hors-budget' avec justification"
+    echo "  (génération, migration mécanique, renommage massif)."
+  fi
+fi
+
+exit $STATUS

napkinstack/modules.py

@@ -0,0 +1,132 @@
+"""
+Modules d'un projet : création (nstack new-module) et verbes standards (nstack bootstrap,
+check, test, run), sans stack imposée (PRODUCT.md P1, PDR-0001 R5).
+
+Chaque verbe exécute la commande déclarée dans la section `commands` du MANIFEST.yaml du
+module, depuis son dossier, par le shell du système. NapkinStack ne suppose jamais un
+Makefile, un package.json ni rien d'autre : le projet déclare, nstack exécute. Conventions
+reprises de Nx (`nx test <projet>`) et de moon (`moon run projet:tâche`).
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from napkinstack.fitness.manifests import find_manifests
+
+GABARIT = Path(__file__).resolve().parent / "templates" / "module"
+NOM = re.compile(r"[a-z][a-z0-9-]*")
+EQUIPE = re.compile(r"[A-Za-z0-9-]+/[A-Za-z0-9._-]+")  # même règle que copier.yml
+FACULTATIFS = {"bootstrap"}  # absent : rien à préparer
+
+RUNBOOK = """# Runbook — {nom}
+
+> Obligatoire pour criticality={criticite} (docs/os/08-qualite.md §7).
+> Un runbook vide fait échouer la CI. À remplir avant la mise en production.
+
+## Alertes et réponses
+| Alerte | Signification | Première action |
+|---|---|---|
+| | | |
+
+## Rollback
+<Procédure testée, pas supposée.>
+
+## Vérification post-déploiement
+<Ce qu'on regarde, et pendant combien de temps.>
+
+## Dépendances et dégradation
+<Que se passe-t-il si chaque dépendance est indisponible ?>
+"""
+
+
+def nouveau(root: Path, nom: str, owner: str, criticite: str) -> int:
+    if not NOM.fullmatch(nom):
+        print(f"ÉCHEC [new-module] nom '{nom}' invalide : kebab-case attendu, par exemple facturation.")
+        return 1
+    if not EQUIPE.fullmatch(owner):
+        print(f"ÉCHEC [new-module] owner '{owner}' invalide : une équipe GitHub organisation/équipe, "
+              "par exemple acme/facturation (CODEOWNERS, docs/os/07-gouvernance.md §7).")
+        return 1
+    dossier = root / "modules" / nom
+    if dossier.exists():
+        print(f"ÉCHEC [new-module] modules/{nom} existe déjà.")
+        return 1
+
+    shutil.copytree(GABARIT, dossier)
+    valeurs = {"{{MODULE_NAME}}": nom, "{{OWNER}}": owner, "{{CRITICALITY}}": criticite}
+    for fichier in (f for f in dossier.rglob("*") if f.is_file()):
+        texte = fichier.read_text(encoding="utf-8")
+        for marque, valeur in valeurs.items():
+            texte = texte.replace(marque, valeur)
+        fichier.write_text(texte, encoding="utf-8")
+
+    runbook = criticite in {"eleve", "critique"}
+    if runbook:
+        (dossier / "docs").mkdir(exist_ok=True)
+        (dossier / "docs" / "runbook.md").write_text(RUNBOOK.format(nom=nom, criticite=criticite),
+                                                      encoding="utf-8")
+        manifest = dossier / "MANIFEST.yaml"
+        manifest.write_text(re.sub(r"^( *)# runbook:", r"\1runbook:",
+                                   manifest.read_text(encoding="utf-8"), flags=re.M), encoding="utf-8")
+
+    codeowners = root / ".github" / "CODEOWNERS"
+    ligne = f"/modules/{nom}/"
+    if codeowners.is_file():
+        contenu = codeowners.read_text(encoding="utf-8")
+        if not any(existante.split()[:1] == [ligne] for existante in contenu.splitlines()):
+            codeowners.write_text(contenu.rstrip("\n") + f"\n{ligne:<31}@{owner}\n", encoding="utf-8")
+    else:
+        print(f"AVERTISSEMENT : .github/CODEOWNERS absent ; y ajouter « {ligne} @{owner} ».")
+
+    print(f"Module créé : modules/{nom} (owner {owner}, criticité {criticite})"
+          + (", runbook à remplir" if runbook else "") + ".")
+    print("\nÉtapes suivantes :")
+    print("  1. ADR de création dans docs/adr/ : capacité, frontière, alternatives")
+    print("  2. MANIFEST.yaml : responsabilité en UNE phrase, puis les commandes check et test de la stack")
+    print(f"  3. modules/{nom}/AGENTS.md : le spécifique du module, jamais le kernel")
+    print(f"  4. nstack fitness, puis nstack check {nom} et nstack test {nom}")
+    return 0
+
+
+def _modules(root: Path) -> dict[str, Path]:
+    """Nom → dossier, pour chaque MANIFEST.yaml que reconnaissent les fitness functions."""
+    return {manifest.parent.name: manifest.parent for manifest in find_manifests(root)}
+
+
+def verbe(root: Path, verbe: str, nom: str | None) -> int:
+    connus = _modules(root)
+    if nom is not None and nom not in connus:
+        print(f"ÉCHEC [{verbe}] module '{nom}' introuvable dans {root} : aucun MANIFEST.yaml à ce nom.\n"
+              f"      Modules connus : {', '.join(connus) or 'aucun'}.")
+        return 1
+    cibles = [nom] if nom is not None else list(connus)
+    if not cibles:
+        print(f"Aucun module dans {root} : rien à exécuter.")
+        return 0
+    for cible in cibles:
+        manifest = connus[cible] / "MANIFEST.yaml"
+        try:
+            commandes = (yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}).get("commands") or {}
+        except yaml.YAMLError as erreur:
+            print(f"ÉCHEC [{verbe}] {manifest} illisible : {erreur}\n      Action : nstack manifests.")
+            return 1
+        commande = commandes.get(verbe)
+        if not commande:
+            if verbe in FACULTATIFS:
+                print(f"→ {cible} : {verbe} non déclaré, rien à préparer.")
+                continue
+            print(f"ÉCHEC [{verbe}] module '{cible}' : commands.{verbe} non déclarée dans {manifest}.\n"
+                  "      Action : y déclarer la commande de la stack du module (docs/os/09-plateforme.md §2).")
+            return 1
+        print(f"→ {cible} : {commande}", flush=True)
+        code = subprocess.run(commande, shell=True, cwd=connus[cible]).returncode
+        if code:
+            print(f"ÉCHEC [{verbe}] module '{cible}' : `{commande}` sort en {code}.")
+            return code
+    return 0

napkinstack/project.py

@@ -0,0 +1,170 @@
+"""
+Création et mise à jour d'un projet (PDR-0001), par Copier (ADR-0001).
+
+Copier est piloté par son API, jamais en mode « unsafe ». Ses refus arrivent avant toute
+modification et sont traduits en messages qui nomment la règle, l'endroit et l'action (P6).
+
+Une mise à jour part d'un état commité et pose la version cible, fusionnée avec les
+adaptations du projet, sur la branche nstack/update-<version>. Un conflit n'est jamais
+commité : il reste marqué dans le fichier pour l'équipe, et le hook check-merge-conflict
+comme la CI refusent tout marqueur restant.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from napkinstack import __version__
+
+SOURCE = "https://github.com/NapkinStack/engineering-os.git"
+ANSWERS = ".copier-answers.yml"
+DOWNGRADE = re.compile(r"You are downgrading from (\S+) to (\S+)\.")
+
+
+def default_ref() -> str:
+    """Le squelette de la version du moteur : ils montent ensemble (PDR-0001 R2)."""
+    return f"v{__version__}"
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+
+
+def _answers(root: Path) -> dict:
+    return yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
+
+
+def _explain(exc: Exception, command: str, where: Path, source: str, ref: str) -> str:
+    """Traduit un refus de Copier (P6)."""
+    from copier.errors import UnsafeTemplateError
+
+    text = str(exc).strip()
+    action = "      Action : "
+    if isinstance(exc, UnsafeTemplateError):
+        return (f"ÉCHEC [{command}] Le gabarit {source} exécute du code ({text.splitlines()[0]}) : "
+                f"refusé (ADR-0001).\n{action}vérifier --source ; NapkinStack n'active jamais ces fonctions.")
+    if text.startswith("Validation error for question '"):
+        question, _, detail = text.removeprefix("Validation error for question '").partition("': ")
+        return (f"ÉCHEC [{command}] Réponse refusée pour {question} : {detail.strip()}\n"
+                f"{action}relancer avec une valeur conforme.")
+    if text.startswith("Destination repository is dirty"):
+        return (f"ÉCHEC [{command}] Arbre de travail modifié dans {where} : une mise à jour part d'un "
+                f"état commité (PDR-0001).\n{action}commiter ou remiser (git stash), puis relancer.")
+    if match := DOWNGRADE.search(text):
+        return (f"ÉCHEC [{command}] Version cible {match[2]} antérieure à celle du projet ({match[1]}) : "
+                f"pas de retour arrière (PDR-0001).\n{action}utiliser nstack {match[1]} ou plus récent.")
+    if text.startswith("Updating is only supported in git-tracked subprojects"):
+        return (f"ÉCHEC [{command}] {where} n'est pas un dépôt git : la fusion s'appuie sur "
+                f"l'historique.\n{action}git init, commit, puis relancer.")
+    if text.startswith("Cannot update: version from last update not detected"):
+        return (f"ÉCHEC [{command}] Le projet ne vient pas d'une version publiée (_commit de {ANSWERS}) : "
+                f"aucune base de fusion.\n{action}créer le projet depuis un tag vX.Y.Z.")
+    if isinstance(exc, OSError) or text == "Local template must be a directory.":
+        detail = [line.split("|", 1)[-1].strip() for line in text.splitlines() if line.strip()][-1]
+        return (f"ÉCHEC [{command}] Gabarit {source} en version {ref} inaccessible : {detail}\n"
+                f"{action}vérifier --source et --ref (tag vX.Y.Z), et l'accès au réseau.")
+    return f"ÉCHEC [{command}] Copier : {text}"
+
+
+def init(destination: Path, answers: dict[str, str | None], source: str, ref: str) -> int:
+    import copier
+    from copier.errors import CopierError
+
+    from napkinstack.doctor import CHECKLIST
+
+    destination = destination.resolve()
+    if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
+        print(f"ÉCHEC [init] {destination} n'est pas vide : nstack init crée un projet neuf.\n"
+              "      Action : choisir un dossier absent ou vide.")
+        return 1
+    data = {question: value for question, value in answers.items() if value is not None}
+    try:
+        copier.run_copy(source, destination, data=data, vcs_ref=ref, quiet=True, unsafe=False)
+    except (CopierError, ValueError, OSError) as exc:
+        print(_explain(exc, "init", destination, source, ref))
+        return 1
+
+    created = _answers(destination)
+    version = created.get("_commit", ref)
+    for args in (("init", "--quiet", "--initial-branch=main"), ("add", "--all"),
+                 ("commit", "--quiet", "--message", f"Création du projet, NapkinStack {version}")):
+        result = _git(destination, *args)
+        if result.returncode:
+            print(f"ÉCHEC [init] Projet généré dans {destination}, mais `git {args[0]}` a échoué :\n"
+                  f"      {result.stderr.strip()}\n"
+                  "      Action : corriger (identité : git config user.name et user.email), "
+                  "puis git add --all && git commit.")
+            return 1
+
+    print(f"Projet créé dans {destination}, NapkinStack {version}, commit initial sur main.")
+    print("\nÉtapes suivantes :")
+    print(f"  1. cd {destination} && pre-commit install")
+    print(f"  2. Créer le dépôt GitHub {created.get('github_repo')}, y pousser main, puis appliquer "
+          "ces réglages :")
+    for _, reglage, _ in CHECKLIST:
+        print(f"     - [ ] {reglage}")
+    print("  3. Vérifier le poste et GitHub, en lecture seule : nstack doctor (jeton : voir le README)")
+    return 0
+
+
+def update(root: Path, ref: str) -> int:
+    import copier
+    from copier.errors import CopierError
+
+    if not (root / ANSWERS).is_file():
+        print(f"ÉCHEC [update] {ANSWERS} introuvable dans {root} : ce dossier n'est pas un projet "
+              "créé par nstack init.\n      Action : lancer la commande à la racine du projet, "
+              "ou préciser --root.")
+        return 1
+    previous = str(_answers(root).get("_commit"))
+    if previous == ref:
+        print(f"Déjà à jour : NapkinStack {ref}.")
+        return 0
+    branch = f"nstack/update-{ref}"
+    if _git(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}").returncode == 0:
+        print(f"ÉCHEC [update] La branche {branch} existe déjà dans {root}.\n"
+              "      Action : la fusionner ou la supprimer (git branch -D), puis relancer.")
+        return 1
+    try:
+        copier.run_update(root, vcs_ref=ref, overwrite=True, skip_answered=True, defaults=True,
+                          conflict="inline", quiet=True, unsafe=False)
+    except (CopierError, ValueError, OSError) as exc:
+        print(_explain(exc, "update", root, str(_answers(root).get("_src_path")), ref))
+        return 1
+
+    if not _git(root, "status", "--porcelain").stdout.strip():
+        print(f"Déjà à jour : rien ne change entre NapkinStack {previous} et {ref}.")
+        return 0
+    current = str(_answers(root).get("_commit"))
+    switch = _git(root, "switch", "--create", branch)
+    if switch.returncode:
+        print(f"ÉCHEC [update] Branche {branch} impossible à créer : {switch.stderr.strip()}\n"
+              "      Action : les changements restent dans l'arbre de travail ; créer la branche "
+              "à la main, puis commiter.")
+        return 1
+    conflicts = _git(root, "diff", "--name-only", "--diff-filter=U").stdout.splitlines()
+    if conflicts:
+        print(f"ÉCHEC [update] NapkinStack {previous} → {current} : conflits avec les adaptations "
+              f"du projet, marqués sur la branche {branch} dans :")
+        for path in conflicts:
+            print(f"  - {path}")
+        print("      Action : dans chaque fichier, garder la bonne version entre <<<<<<< et >>>>>>>, "
+              "puis git add --all && git commit.\n      Le hook check-merge-conflict et la CI "
+              "refusent tout marqueur restant.")
+        return 1
+    for args in (("add", "--all"), ("commit", "--quiet", "--message", f"NapkinStack {previous} → {current}")):
+        result = _git(root, *args)
+        if result.returncode:
+            print(f"ÉCHEC [update] Mise à jour posée sur {branch}, mais `git {args[0]}` a échoué :\n"
+                  f"      {(result.stdout + result.stderr).strip()}\n"
+                  "      Action : corriger, puis git add --all && git commit.")
+            return 1
+
+    print(f"Branche {branch} : NapkinStack {previous} → {current}, fusionné avec les adaptations "
+          "du projet.")
+    print(f"\nÉtape suivante : git push -u origin {branch}, puis ouvrir la PR ; la CI la valide.")
+    return 0