Set-OPS-Public/scripts/runbooks.py

#!/usr/bin/env python3
"""Les runbooks de construction : l'ordre des gestes, et la garde qui l'empeche de mentir.

CE QUE CE MODULE RESOUT (2026-09-20). Le Makefile porte 132 cibles documentees. Elles
disent chacune ce qu'elle fait, aucune ne dit DANS QUEL ORDRE ni POURQUOI MAINTENANT.
Un exploitant qui decouvre un site n'a donc aucun moyen de savoir que `site-creer` vient
avant `forge-amorcer`, que le premier passage s'arrete sur une forge vide, ni que rien
n'est « pret » avant `valider`. Cette connaissance vit dans les documents, en prose, et
la console ne la porte pas : elle offre des boutons sans sequence.

CE QUI EST DECLARE ICI, ET CE QUI NE L'EST PAS. `docs/runbooks-construction.yml` declare
l'ORDRE, la NATURE (mesure / ecriture / destructif), la PORTEE et le POURQUOI de chaque
geste. Il ne recopie JAMAIS le libelle d'une cible : celui-ci est lu dans le Makefile au
moment de servir. Une seconde liste qui recopierait la premiere prendrait du retard sur
elle — c'est arrive quatre fois dans ce depot en une seule journee, et la regle qui en
est sortie est d'ecrire la garde EN MEME TEMPS que la seconde liste.

LA GARDE, C'EST `verifier()`. Elle refuse quatre etats :

  - une etape qui vise une cible que le Makefile n'a pas (le registre a pris du retard) ;
  - une cible documentee que nul runbook ne porte et que nul motif n'exempte (la console
    cacherait un pouvoir que le moteur possede) ;
  - une cible a la fois portee et exemptee (deux verites, aucune) ;
  - une valeur hors vocabulaire : nature, portee, ou variable inconnue du catalogue.

P83 rejoue cette garde. Sans elle, ce fichier deviendrait une carte perimee — et une
carte perimee est pire que pas de carte, parce qu'on la suit.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

import yaml

RACINE = Path(__file__).resolve().parent.parent
REGISTRE = RACINE / "docs/runbooks-construction.yml"

# Le vocabulaire ferme du registre. Une valeur hors de ces ensembles est refusee : mieux
# vaut un registre qui bloque qu'une console qui interprete une nature qu'elle ignore.
NATURES = {
    # `mesure` n'ecrit rien et peut etre rejouee sans consequence. La console la propose
    # toujours, meme quand l'etape precedente a echoue : mesurer pour comprendre est
    # exactement ce qu'on fait apres un echec.
    "mesure",
    # `ecriture` change l'etat du monde. La console exige que l'etape precedente ait
    # reussi, sinon on batit sur un terrain qu'on n'a pas verifie.
    "ecriture",
    # `destructif` detruit. La console exige une confirmation ecrite, en plus de la
    # variable CONFIRMER que la cible reclame deja d'elle-meme.
    "destructif",
}

# La portee, au sens de `contexte()` dans la console : ce que la MACHINE porte.
#   tenant  — un ecosysteme est monte (`instance/`), on a sa voute : on configure.
#   site    — une fabric est montee (`underlay.yml`) : on materialise.
#   poste   — les deux, l'atelier du mainteneur.
#   toute   — ni l'un ni l'autre n'est requis (verifications du depot lui-meme).
PORTEES = {"tenant", "site", "poste", "toute"}

MOTIF_CIBLE = re.compile(r"^([a-z0-9][a-z0-9_-]*):[^#\n]*##\s*(.+?)\s*$", re.MULTILINE)


def cibles_du_makefile(racine: Path = RACINE) -> dict[str, str]:
    """Les cibles DOCUMENTEES du Makefile, avec leur libelle — la source unique.

    Une cible sans `##` est un detail d'implementation (`_instance-requise`,
    `ansible-runtime`) : elle n'est pas offerte a l'exploitant, donc elle n'est pas
    attendue dans un runbook.
    """
    texte = (racine / "Makefile").read_text(encoding="utf-8")
    return {nom: aide for nom, aide in MOTIF_CIBLE.findall(texte)}


def cibles_qui_exigent_confirmation(racine: Path = RACINE) -> set[str]:
    """Les cibles dont la RECETTE teste `CONFIRMER`.

    POURQUOI LIRE LA RECETTE ET NON LE REGISTRE. Comparer `nature` a `fixes`
    ne compare que deux champs ecrits par la meme main : le meme mensonge
    repasse en EFFACANT la ligne `fixes`. La recette, elle, ne ment pas — elle
    refuse, et c'est ce refus que l'exploitant rencontre.

    Une recette va de sa ligne de cible jusqu'a la prochaine ligne non
    indentee ; une ligne vide ne l'interrompt pas.
    """
    texte = (racine / "Makefile").read_text(encoding="utf-8")
    exigent: set[str] = set()
    etat: dict = {"cible": "", "recette": []}

    def _clore() -> None:
        if etat["cible"] and "CONFIRMER" in "\n".join(etat["recette"]):
            exigent.add(etat["cible"])

    for ligne in texte.splitlines():
        debut = re.match(r"^([A-Za-z0-9_.-]+):", ligne)
        if debut:
            _clore()
            etat["cible"], etat["recette"] = debut.group(1), []
        elif etat["cible"] and (ligne.startswith("\t") or ligne.startswith("    ")):
            etat["recette"].append(ligne)
        elif ligne.strip():
            _clore()
            etat["cible"], etat["recette"] = "", []
    _clore()
    return exigent


def charger(chemin: Path = REGISTRE) -> dict:
    """Le registre brut, tel qu'il est ecrit. Aucune jointure, aucune validation."""
    if not chemin.is_file():
        raise FileNotFoundError(f"Registre des runbooks introuvable : {chemin}")
    data = yaml.safe_load(chemin.read_text(encoding="utf-8")) or {}
    if not isinstance(data, dict):
        raise ValueError(f"{chemin} ne contient pas une table YAML.")
    return data


def assembler(racine: Path = RACINE, chemin: Path | None = None) -> list[dict]:
    """Les runbooks, joints au Makefile — la forme que la console sert.

    Le libelle de chaque etape vient d'`aide`, lue dans le Makefile a CET instant. Le
    registre n'en porte pas de copie, donc il ne peut pas en porter une perimee.
    """
    data = charger(chemin or REGISTRE)
    aides = cibles_du_makefile(racine)
    catalogue = data.get("variables", {}) or {}
    sortie = []
    for rb in data.get("runbooks", []) or []:
        etapes = []
        for etape in rb.get("etapes", []) or []:
            cible = etape.get("cible", "")
            etapes.append({
                "cible": cible,
                # LE LIBELLE N'EST PAS DANS LE REGISTRE. Il est lu ici, chaque fois.
                "libelle": aides.get(cible, ""),
                # LA PORTEE SE PESE A L'ETAPE, PAS AU RUNBOOK (2026-09-20, mesure sur la
                # console de TechnoLibre). Une seule etape qui materialise faisait basculer
                # toute la sequence en `poste`, et un locataire ne pouvait plus deployer
                # SA PROPRE flotte — exactement son metier. Le runbook donne le defaut ;
                # l'etape qui exige davantage le declare.
                "portee": etape.get("portee", rb.get("portee", "toute")),
                "nature": etape.get("nature", "mesure"),
                "pourquoi": etape.get("pourquoi", ""),
                "duree": etape.get("duree", ""),
                "variables": [
                    {"nom": v, **(catalogue.get(v, {}) or {})}
                    for v in (etape.get("variables", []) or [])
                ],
                "fixes": etape.get("fixes", {}) or {},
                "facultative": bool(etape.get("facultative", False)),
            })
        sortie.append({
            "id": rb.get("id", ""),
            "titre": rb.get("titre", ""),
            "portee": rb.get("portee", "toute"),
            "but": rb.get("but", ""),
            "doc": rb.get("doc", ""),
            "etapes": etapes,
        })
    return sortie


def etape_declaree(runbook_id: str, cible: str, racine: Path = RACINE,
                   index: int | None = None) -> dict | None:
    """L'etape declaree, ou None — LE point de controle du serveur.

    La console ne lance JAMAIS ce que le navigateur lui nomme : elle lance ce que le
    registre declare a cette place-la. Un navigateur qui reclamerait `raser` dans un
    runbook de mesure n'obtient rien, et c'est le seul verrou qui compte.

    L'INDEX COMPTE PARCE QU'UNE CIBLE PEUT REVENIR. « Le premier jour d'un site » lance
    `site-deployer-tout` DEUX fois — le premier passage s'arrete sur la forge vide, le
    second doit finir a zero echec. Chercher par nom seul confondrait les deux places.
    Quand l'appelant donne un index, la cible doit s'y trouver : sinon la page et le
    registre ne parlent pas de la meme chose, et on ne lance rien.
    """
    for rb in assembler(racine):
        if rb["id"] != runbook_id:
            continue
        etapes = rb["etapes"]
        if index is not None:
            if not (0 <= index < len(etapes)) or etapes[index]["cible"] != cible:
                return None
            return {**etapes[index], "runbook": rb["titre"],
                    "portee_runbook": rb["portee"]}
        for etape in etapes:
            if etape["cible"] == cible:
                return {**etape, "runbook": rb["titre"],
                        "portee_runbook": rb["portee"]}
    return None


def verifier(racine: Path = RACINE, chemin: Path | None = None) -> list[str]:
    """La garde. Rend la liste des ecarts — vide quand le registre dit vrai."""
    data = charger(chemin or REGISTRE)
    aides = cibles_du_makefile(racine)
    catalogue = data.get("variables", {}) or {}
    hors = data.get("hors_assistant", {}) or {}
    exigent = cibles_qui_exigent_confirmation(racine)
    ecarts: list[str] = []
    portees_vues: dict[str, set[str]] = {}

    vues: set[str] = set()
    ids: set[str] = set()
    for rb in data.get("runbooks", []) or []:
        rid = rb.get("id", "")
        if not rid:
            ecarts.append("Un runbook n'a pas d'identifiant.")
            continue
        if rid in ids:
            ecarts.append(f"{rid} : deux runbooks portent cet identifiant.")
        ids.add(rid)
        if rb.get("portee") not in PORTEES:
            ecarts.append(f"{rid} : portee « {rb.get('portee')} » hors vocabulaire "
                          f"({', '.join(sorted(PORTEES))}).")
        if not rb.get("but"):
            ecarts.append(f"{rid} : aucun but declare — un runbook sans but ne se choisit pas.")
        if not (rb.get("etapes") or []):
            ecarts.append(f"{rid} : aucune etape.")
        for etape in rb.get("etapes", []) or []:
            cible = etape.get("cible", "")
            if cible not in aides:
                ecarts.append(f"{rid} → {cible} : le Makefile ne porte pas cette cible "
                              f"(registre en retard, ou cible renommee).")
            vues.add(cible)
            portees_vues.setdefault(cible, set()).add(rb.get("portee", ""))
            if "portee" in etape and etape["portee"] not in PORTEES:
                ecarts.append(f"{rid} → {cible} : portee d'etape « {etape['portee']} » hors "
                              f"vocabulaire ({', '.join(sorted(PORTEES))}).")
            if etape.get("nature") not in NATURES:
                ecarts.append(f"{rid} → {cible} : nature « {etape.get('nature')} » hors "
                              f"vocabulaire ({', '.join(sorted(NATURES))}).")
            # LA RECETTE TRANCHE, DANS LES DEUX SENS. Ce que la cible EXIGE
            # se lit dans son Makefile ; ce que le registre PROMET se lit dans
            # `fixes`. Comparer le registre a lui-meme laissait passer le meme
            # mensonge ecrit dans l'autre sens — il suffisait d'effacer
            # `fixes`, et trois cibles le portaient ainsi : un assistant les
            # lancait sans confirmation, et sortait en 2.
            declare = "CONFIRMER" in (etape.get("fixes") or {})
            if cible in exigent and not declare:
                ecarts.append(f"{rid} → {cible} : la recette refuse sans CONFIRMER "
                              f"et le registre ne le declare pas. Un assistant la "
                              f"lancerait telle quelle, et sortirait en 2.")
            if declare and cible not in exigent:
                ecarts.append(f"{rid} → {cible} : le registre declare CONFIRMER que "
                              f"la recette n'exige pas. Une confirmation de plus "
                              f"s'apprend a cliquer sans lire.")
            # UNE MESURE QUI AGIT N'EN EST PAS UNE : une cible qui refuse sans
            # confirmation TOUCHE au systeme, quel que soit le fait qu'elle en
            # rapporte ensuite.
            if etape.get("nature") == "mesure" and (declare or cible in exigent):
                ecarts.append(f"{rid} → {cible} : declaree « mesure » alors qu'elle "
                              f"exige CONFIRMER. Une mesure qui demande "
                              f"confirmation agit.")
            if not etape.get("pourquoi"):
                ecarts.append(f"{rid} → {cible} : aucun « pourquoi ». Une etape qui ne dit "
                              f"pas pourquoi elle est la se fait sauter.")
            for v in etape.get("variables", []) or []:
                if v not in catalogue:
                    ecarts.append(f"{rid} → {cible} : la variable {v} n'est pas au "
                                  f"catalogue — la console ne saurait pas quoi demander.")

    # LA COUVERTURE, DANS LES DEUX SENS.
    for cible in sorted(set(aides) - vues - set(hors)):
        ecarts.append(f"{cible} : cible documentee que nul runbook ne porte et que nul "
                      f"motif n'exempte. La console cacherait un pouvoir du moteur.")
    for cible in sorted(vues & set(hors)):
        ecarts.append(f"{cible} : portee par un runbook ET declaree hors assistant — "
                      f"deux verites, aucune.")
    for cible in sorted(set(hors) - set(aides)):
        ecarts.append(f"{cible} : exemptee alors que le Makefile ne la porte pas "
                      f"(exemption devenue sans objet).")
    for cible, motif in sorted(hors.items()):
        if not str(motif or "").strip():
            ecarts.append(f"{cible} : exemptee sans motif. Une exemption muette est un oubli.")
    return ecarts


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("action", choices=("verifier", "lister", "couverture"),
                        nargs="?", default="verifier")
    # POURQUOI UN --json. Le registre est la seule source qui dise la NATURE
    # d'une etape et la confirmation qu'elle exige. Un outil tiers qui veut
    # n'offrir que ce qui ne detruit pas doit donc le lire — et sans drapeau,
    # il n'a le choix qu'entre analyser un arbre fait pour l'oeil humain, qui
    # derive au premier changement de mise en page, et importer ce module,
    # ce qui le lie a nos noms internes. Les deux se paient plus tard.
    parser.add_argument("--json", action="store_true",
                        help="Rend le registre assemble en JSON (avec "
                             "« lister »), pour un outil tiers.")
    args = parser.parse_args()
    # RENDRE LA PROSE HUMAINE A QUI DEMANDE DU JSON est pire qu'un refus :
    # l'appelant lit une reponse qu'il croit analysable, et ne s'en apercoit
    # qu'au premier caractere inattendu.
    if args.json and args.action != "lister":
        parser.error("--json n'existe qu'avec « lister ».")

    if args.action == "verifier":
        ecarts = verifier()
        if ecarts:
            print(f"Registre des runbooks : {len(ecarts)} ecart(s).\n")
            for e in ecarts:
                print(f"  - {e}")
            return 1
        rbs = assembler()
        etapes = sum(len(r["etapes"]) for r in rbs)
        print(f"Registre des runbooks : {len(rbs)} runbooks, {etapes} etapes, "
              f"{len(cibles_du_makefile())} cibles documentees, aucun ecart.")
        return 0

    if args.action == "lister":
        if args.json:
            # Sortie NUE, sans en-tete ni resume : un appelant la lit d'un
            # bloc. `ensure_ascii=False` garde les accents du registre.
            print(json.dumps(assembler(), ensure_ascii=False))
            return 0
        for rb in assembler():
            print(f"\n{rb['id']}  [{rb['portee']}]  {rb['titre']}")
            print(f"  {rb['but']}")
            for i, e in enumerate(rb["etapes"], 1):
                marque = {"mesure": " ", "ecriture": "*", "destructif": "!"}[e["nature"]]
                var = (" " + " ".join(f"{v['nom']}=…" for v in e["variables"])) if e["variables"] else ""
                sup = "" if e["portee"] == rb["portee"] else f"  [{e['portee']}]"
                print(f"   {marque} {i:2}. make {e['cible']}{var}{sup}")
                print(f"        {e['libelle']}")
        return 0

    # couverture
    aides = cibles_du_makefile()
    data = charger()
    vues = {e.get("cible") for rb in data.get("runbooks", []) or []
            for e in rb.get("etapes", []) or []}
    hors = set(data.get("hors_assistant", {}) or {})
    print(f"cibles documentees : {len(aides)}")
    print(f"  portees par un runbook : {len(vues & set(aides))}")
    print(f"  hors assistant (motivees) : {len(hors & set(aides))}")
    print(f"  ni l'un ni l'autre : {len(set(aides) - vues - hors)}")
    for c in sorted(set(aides) - vues - hors):
        print(f"    - {c}  ({aides[c]})")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())