magicbox-dk 0.0.1__py3-none-any.whl

cli/cleanup.py

@@ -0,0 +1,136 @@
+"""Garbage collection des clones git orphelins d'un profil.
+
+Un clone (``<profil>/repos/<entry_name>``) devient orphelin quand l'entrée
+correspondante est supprimée du profil ou change de mode (git → remote/dev).
+``gc_clones`` raisonne profil par profil : un clone est orphelin si le YAML
+du profil ne le référence plus. ``gc_profile_clones`` couvre ``dk clean`` :
+il purge **tous** les clones du profil (le profil revient à l'état « non
+préparé », un ``dk prepare`` re-clone ce qui est nécessaire).
+
+Pas de GC des globales ``settings.env.connection`` : un endpoint plus
+référencé par aucun profil reste utilisable pour un profil futur — on le
+préserve.
+
+Toute la logique vit dans :class:`CloneGC` ; :func:`gc_clones` et
+:func:`gc_profile_clones` sont des façades pour les call sites historiques.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+import questionary
+import typer
+
+from cli.core.context import MagicboxContext
+from cli.ui import GLYPH_ERR, GLYPH_INFO, GLYPH_OK
+
+
+class CloneGC:
+    """GC des clones git d'un profil (``<profil>/repos/``).
+
+    Pré-bindé sur un ``ctx`` + ``profile_id`` ; expose le listing des clones,
+    la détection des orphelins, et les deux opérations de purge (orphelins
+    seuls vs tous les clones).
+    """
+
+    def __init__(self, ctx: MagicboxContext, profile_id: str) -> None:
+        self.ctx = ctx
+        self.profile_id = profile_id
+
+    def clones(self) -> list[str]:
+        """Noms des dossiers de clone git présents dans le ``repos/`` du profil."""
+        repos = self.ctx.profile_repos_dir(self.profile_id)
+        if not repos.exists():
+            return []
+        # On ne compte que les dépôts git (les .DS_Store et autres sont ignorés).
+        return sorted(
+            d.name for d in repos.iterdir() if d.is_dir() and (d / ".git").exists()
+        )
+
+    def orphans(self) -> list[str]:
+        """Clones présents qu'aucune entrée git du YAML du profil ne référence."""
+        referenced = self.ctx.profile_clone_names(self.profile_id)
+        return [n for n in self.clones() if n not in referenced]
+
+    def _delete(self, names: list[str], *, silent: bool = False) -> list[str]:
+        """Supprime les dossiers de clone ``names`` du ``repos/`` du profil.
+
+        Retourne les noms effectivement supprimés (les échecs ``OSError`` sont
+        rapportés sur stderr et n'interrompent pas la boucle).
+        """
+        repos = self.ctx.profile_repos_dir(self.profile_id)
+        deleted: list[str] = []
+        for name in names:
+            try:
+                shutil.rmtree(repos / name)
+            except OSError as exc:
+                typer.secho(f"  {GLYPH_ERR} {name} : {exc}", fg=typer.colors.RED, err=True)
+                continue
+            if not silent:
+                typer.secho(f"  {GLYPH_OK} clone supprimé : {name}", fg=typer.colors.GREEN)
+            deleted.append(name)
+        return deleted
+
+    @staticmethod
+    def _confirm(count: int) -> bool:
+        """Prompt de confirmation partagé. ``False`` ⇒ conservation (message)."""
+        confirmed = questionary.confirm(
+            f"Supprimer ces {count} clone(s) ?", default=False,
+        ).ask()
+        if not confirmed:
+            typer.echo("Clones conservés.")
+        return bool(confirmed)
+
+    def gc_orphans(self, *, ask: bool = True, silent: bool = False) -> list[str]:
+        """Supprime les clones orphelins. Retourne la liste des noms supprimés."""
+        orphans = self.orphans()
+        if not orphans:
+            return []
+        if not silent:
+            typer.secho(f"\nClones orphelins ({len(orphans)}) :", fg=typer.colors.YELLOW)
+            for n in orphans:
+                typer.echo(f"  {GLYPH_INFO} {n}")
+        if ask and not self._confirm(len(orphans)):
+            return []
+        return self._delete(orphans, silent=silent)
+
+    def gc_all(self, *, ask: bool = True) -> list[str]:
+        """Supprime tous les clones git du profil. Retourne les noms supprimés.
+
+        Pensé pour ``dk clean`` : le profil revient à l'état « non préparé », un
+        ``dk prepare`` re-clonera ce qui est nécessaire.
+        """
+        clones = self.clones()
+        if not clones:
+            typer.echo("  (aucun clone git pour ce profil)")
+            return []
+        typer.secho(f"\nClones git du profil ({len(clones)}) :", fg=typer.colors.YELLOW)
+        for n in clones:
+            typer.echo(f"  {GLYPH_INFO} {n}")
+        if ask and not self._confirm(len(clones)):
+            return []
+        return self._delete(clones)
+
+
+# ── Façades pour les call sites historiques ──────────────────────────────────── #
+
+
+def gc_clones(
+        ctx: MagicboxContext, profile_id: str, *, ask: bool = True, silent: bool = False,
+) -> list[str]:
+    """Supprime les clones orphelins du profil. Retourne la liste des noms supprimés.
+
+    Façade vers :meth:`CloneGC.gc_orphans`.
+    """
+    return CloneGC(ctx, profile_id).gc_orphans(ask=ask, silent=silent)
+
+
+def gc_profile_clones(
+        ctx: MagicboxContext, profile_id: str, *, ask: bool = True,
+) -> list[str]:
+    """Supprime tous les clones git du profil (``<profil>/repos/``).
+
+    Façade vers :meth:`CloneGC.gc_all`.
+    """
+    return CloneGC(ctx, profile_id).gc_all(ask=ask)

cli/commands/_base.py

@@ -0,0 +1,397 @@
+"""Classe de base des commandes ``dk`` — :class:`BaseCommand`.
+
+Chaque commande Typer reste une **fonction fine** (Typer introspecte sa
+signature pour générer ``--help`` / parser les arguments, cf.
+``cli/core/cmd.py``) qui instancie une sous-classe de :class:`BaseCommand` et
+appelle :meth:`~BaseCommand.execute`. La classe porte :
+
+* le **cycle de vie** commun (bootstrap + debug + résolution profil), piloté par
+  des attributs de classe surchargeables (``requires_profile``, ``require_*``,
+  ``requires_init``, ``loads_context``) ;
+* une **frontière d'erreur** unique : :class:`cli.runner.base.CmdError` levé par
+  une commande externe (git/docker en mode ``check=True``) est rendu en panneau
+  d'échec standardisé, sortie déjà masquée des secrets ;
+* des **helpers transverses** : :meth:`fail`, :meth:`confirm`, :meth:`guard_os`,
+  :meth:`check_cmd`. Les panneaux récapitulatifs passent par ``self.steps.panel_*``.
+
+Le rendu de progression (sections, étapes numérotées, items ✓/✗/⚠, panneaux)
+est délégué à :class:`cli.ui.StepReporter` exposé via ``self.steps``.
+"""
+
+from __future__ import annotations
+
+import itertools
+import threading
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Annotated, Any, NoReturn, TypeVar
+
+import questionary
+import typer
+
+from cli.core.cmd import bootstrap, bootstrap_no_profile, resolve_target
+from cli.core.context import MagicboxContext
+from cli.debug import dlog, set_debug, set_verbose
+from cli.runner import process
+from cli.runner.base import CmdError, CmdResult
+from cli.runner.redaction import redact
+from cli.ui import StepReporter
+
+#: Option Typer partagée ``--id <uuid>`` : cible un profil par son UUID plutôt
+#: que par son libellé. Mutuellement exclusive avec l'argument de libellé
+#: (garde-fou dans ``cli.core.cmd.resolve_target``).
+ProfileIdOption = Annotated[
+    str | None,
+    typer.Option("--id", help="Cible le profil par son UUID plutôt que par son libellé."),
+]
+
+
+class BaseCommand(ABC):
+    """Base de toutes les commandes ``dk``.
+
+    Sous-classer, surcharger les attributs de config si besoin, implémenter
+    :meth:`run`, et exposer une entrée Typer :meth:`cli` (héritée telle quelle
+    pour une commande sans argument, redéfinie en ``@staticmethod`` typée
+    sinon). ``cli`` construit l'instance et déclenche :meth:`_dispatch` (le
+    cycle de vie partagé : préambule + ``run`` + frontière ``CmdError``).
+    """
+
+    # ── Config (surchargée par sous-classe) ──────────────────────────────── #
+
+    #: Cible un profil (``bootstrap``) vs aucun profil précis (``bootstrap_no_profile``).
+    requires_profile: bool = True
+    #: Transmis à ``bootstrap`` : le dossier du profil doit exister.
+    require_existing: bool = True
+    #: Transmis à ``bootstrap`` : le profil doit avoir été préparé (``dk prepare``).
+    require_prepared: bool = False
+    #: ``False`` ⇒ ne pas exiger ``dk init`` (cas ``init`` / ``dashboard``).
+    requires_init: bool = True
+    #: ``False`` ⇒ ne charge aucun contexte (cas ``version``).
+    loads_context: bool = True
+    #: ``True`` ⇒ sans cible (ni libellé ni ``--id``) sur TTY, ouvre un picker de
+    #: profil au lieu de retomber sur l'actif. Réservé aux commandes où l'on cible
+    #: volontiers un autre profil que l'actif (``switch``, ``delete``). Les
+    #: commandes « profil courant » (``start``/``edit``/``prepare``…) gardent
+    #: ``False`` (défaut → profil actif, pas de prompt).
+    picks_profile: bool = False
+
+    def __init__(
+            self, profile: str | None = None, *,
+            debug: bool = False, verbose: bool = False,
+            profile_id: str | None = None,
+    ) -> None:
+        self.profile_name = profile
+        #: UUID ciblé via ``--id`` (mutuellement exclusif avec ``profile``).
+        self._id_flag = profile_id
+        self.debug = debug
+        self.verbose = verbose
+        self.ctx: MagicboxContext | None = None
+        self.profile_id: str | None = None
+        self.steps = StepReporter()
+        self.step_status = None  # rich.Status courant pendant une étape spinner
+
+    # ── Point d'entrée Typer + cycle de vie ──────────────────────────────── #
+
+    @classmethod
+    def cli(cls) -> None:
+        """Point d'entrée Typer **par défaut** : commandes sans argument.
+
+        Monté dans ``cli/main.py`` via ``app.command("verbe")(MaCommande.cli)``.
+        Une commande qui prend des arguments/options **redéfinit** ``cli`` en
+        ``@staticmethod`` typée (Typer l'introspecte pour ``--help`` / le parsing)
+        et appelle ``MaCommande(...)._dispatch()``. Les commandes triviales
+        (``version``, ``dashboard``, ``settings``) héritent de ce défaut —
+        ``cls()`` instancie la bonne sous-classe.
+        """
+        cls()._dispatch()
+
+    def _dispatch(self) -> None:
+        """Préambule standard + exécution de :meth:`run`, frontière d'erreur incluse.
+
+        Cycle de vie partagé, appelé par :meth:`cli` une fois l'instance
+        construite. Selon les attributs de config : bootstrap profil, bootstrap
+        sans profil, simple ``MagicboxContext.load`` (sans garde-fou), ou rien.
+        Un :class:`CmdError` remontant de :meth:`run` est rendu en panneau d'échec.
+        """
+        # Verbose déroule le détail des étapes (cf. ``-v/--verbose``) — posé avant
+        # tout pour couvrir aussi le préambule. ``set_debug`` est géré par bootstrap.
+        set_verbose(self.verbose)
+        if self.requires_profile:
+            self.ctx, self.profile_id = bootstrap(
+                self.profile_name,
+                debug=self.debug,
+                require_existing=self.require_existing,
+                require_prepared=self.require_prepared,
+                profile_id=self._id_flag,
+                pick_when_unset=self.picks_profile,
+            )
+            if self.profile_name is not None:
+                dlog(f"profil `{self.profile_name}` → uuid {self.profile_id}")
+        elif self.requires_init:
+            self.ctx = bootstrap_no_profile(debug=self.debug)
+        elif self.loads_context:
+            set_debug(self.debug)
+            self.ctx = MagicboxContext.load()
+        else:
+            set_debug(self.debug)
+
+        try:
+            self.run()
+        except CmdError as exc:
+            # Échec d'une commande externe en mode ``check=True`` (git/docker).
+            # ``exc.output`` est déjà masqué des secrets par le runner.
+            self.steps.panel_err(str(exc), detail=exc.output or None)
+            raise typer.Exit(code=exc.returncode or 1) from exc
+        except KeyboardInterrupt:
+            # Ctrl+C : les ``finally``/context managers ont déjà déroulé (Rich a
+            # restauré le curseur, les viewers le terminal). On tue les éventuels
+            # sous-process encore vivants, puis on indique CLAIREMENT ce qui s'est
+            # passé (l'utilisateur ne doit pas se demander si ça tourne en fond).
+            process.terminate_all(grace=2.0)
+            self.steps.panel_warn("Interrompu", self._interrupt_note())
+            raise typer.Exit(code=130) from None
+
+    @abstractmethod
+    def run(self) -> None:
+        """Logique métier de la commande. ``self.ctx`` / ``self.profile_id`` sont prêts."""
+        ...
+
+    def _interrupt_note(self) -> str | None:
+        """Indication contextuelle affichée après un Ctrl+C (``None`` = aucune).
+
+        Surchargée par les commandes qui peuvent laisser un état partiel (ex.
+        ``start``/``stop`` : conteneurs à moitié lancés/arrêtés) pour dire à
+        l'utilisateur quoi vérifier. Les commandes sans effet de bord renvoient
+        ``None`` (juste « Interrompu »).
+        """
+        return None
+
+    def resolve_target(self) -> str:
+        """Résout le profil ciblé pour une commande à résolution manuelle.
+
+        Pour les commandes ``requires_profile = False`` qui résolvent elles-mêmes
+        le profil (``clean``, ``switch``, ``restart``) : applique la même règle
+        libellé-OU-``--id`` que ``bootstrap``, avec le picker piloté par
+        ``picks_profile``. ``self.ctx`` doit être chargé.
+        """
+        assert self.ctx is not None
+        return resolve_target(
+            self.ctx, self.profile_name, self._id_flag,
+            pick_when_unset=self.picks_profile,
+        )
+
+    # ── Helpers d'erreur ─────────────────────────────────────────────────── #
+
+    def fail(
+            self, message: str, *, code: int = 1, cause: BaseException | None = None,
+    ) -> NoReturn:
+        """Affiche ``message`` en rouge (stderr) puis sort avec ``code``."""
+        typer.secho(message, fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=code) from cause
+
+    def check_cmd(self, result: CmdResult, message: str) -> None:
+        """Sort en erreur si une commande externe (``CmdResult``) a échoué.
+
+        Aligné sur ``cli/runner`` : les méthodes Docker renvoient un
+        :class:`CmdResult` (contrat returncode, jamais d'exception). Sur échec,
+        affiche ``message`` + la sortie capturée **masquée des secrets**.
+        """
+        if result.ok:
+            return
+        output = redact(result.stderr or result.stdout)
+        self.steps.panel_err(message, detail=output or None)
+        raise typer.Exit(code=result.returncode or 1)
+
+    @contextmanager
+    def guard_os(self, error_template: str) -> Iterator[None]:
+        """Convertit une ``OSError`` d'I/O fichier en sortie d'erreur propre.
+
+        ``error_template`` est formaté avec ``exc`` (ex.
+        ``"Suppression impossible : {exc}"``).
+        """
+        try:
+            yield
+        except OSError as exc:
+            self.fail(error_template.format(exc=exc), cause=exc)
+
+    # ── Confirmation interactive ─────────────────────────────────────────── #
+
+    def confirm(self, message: str, *, yes: bool = False, default: bool = False) -> bool:
+        """Demande confirmation (sauf ``yes=True``). ``False`` ⇒ « Annulé. ».
+
+        Retourne ``True`` si l'action peut continuer, ``False`` si l'utilisateur
+        a refusé (un message « Annulé. » est alors affiché). Le flag ``yes``
+        court-circuite la question (``--yes/-y``).
+        """
+        if yes:
+            return True
+        # Suspend le spinner global le temps du prompt (sinon la Live l'écrase).
+        with self.steps.paused():
+            answered = questionary.confirm(message, default=default).ask()
+        if answered:
+            return True
+        typer.echo("Annulé.")
+        return False
+
+
+# ── Système de steps déclaratif ─────────────────────────────────────────────── #
+
+_STEP_ORDER = itertools.count()
+_F = TypeVar("_F", bound=Callable[..., None])
+
+
+@dataclass(frozen=True)
+class _StepDef:
+    """Métadonnées attachées à une méthode décorée :func:`step`."""
+
+    title: str
+    order: int
+    when: Callable[[StepCommand], bool] | None
+    spinner: bool
+    collapse: bool
+
+
+def step(
+        title: str,
+        *,
+        when: Callable[[StepCommand], bool] | None = None,
+        spinner: bool = False,
+        collapse: bool = True,
+) -> Callable[[_F], _F]:
+    """Marque une méthode comme une **étape** d'une :class:`StepCommand`.
+
+    Les étapes s'exécutent dans l'ordre de déclaration, rendues de façon
+    homogène et **collapsible par défaut** (façon ``docker build``) : pendant
+    l'exécution un spinner montre l'activité courante (dernier ``self.ok``/
+    ``info``), et à la fin tout est remplacé par une seule ligne d'outcome
+    ``✓ [i/N] Titre`` (``⚠``/``✗`` selon avertissements/erreurs, qui restent
+    affichés). Avec ``spinner=True``, l'étape est une opération opaque (build,
+    up, down) : spinner animé + outcome auto, sans items.
+
+    ``collapse=False`` : repli sur le rendu déroulant (en-tête + items inline) —
+    pour une étape qui gère son propre affichage live (``rich.Live``) ou imprime
+    en direct (sortie d'un binaire externe). ``--debug`` / sortie non-TTY
+    désactivent aussi le collapse automatiquement.
+
+    ``when`` : prédicat ``(self) -> bool`` évalué avant l'exécution — si faux,
+    l'étape est sautée et exclue de la numérotation (ex. ``--no-build``).
+    """
+
+    def deco(fn: _F) -> _F:
+        fn._stepdef = _StepDef(  # type: ignore[attr-defined]
+            title, next(_STEP_ORDER), when, spinner, collapse,
+        )
+        return fn
+
+    return deco
+
+
+class StepCommand(BaseCommand):
+    """Commande dont la logique est découpée en **étapes** (méthodes :func:`step`).
+
+    Le ``run()`` est fourni : il appelle :meth:`setup` (préparation de l'état
+    partagé porté par ``self``), exécute chaque étape active dans l'ordre de
+    déclaration via ``self.steps`` (numérotation ``[i/N]`` automatique), puis
+    :meth:`finish` (panneau récapitulatif). Les sous-classes n'écrivent que des
+    méthodes : tout le code vit dans la classe.
+    """
+
+    #: Libellé du spinner global de commande (cf. :meth:`cli.ui.StepReporter.command`).
+    command_label: str = "Traitement"
+
+    def setup(self) -> None:
+        """Hook avant les étapes : charge le profil, calcule l'état partagé."""
+
+    def finish(self) -> None:
+        """Hook après les étapes : panneau récapitulatif final (optionnel)."""
+
+    def pump(self, fn: Callable[[], Any], *, interval: float = 0.1) -> Any:
+        """Exécute ``fn()`` en **arrière-plan** tout en gardant le panneau vivant.
+
+        Un travail bloquant sur le thread principal (clone/fetch git, I/O réseau)
+        empêche le spinner et les chronos d'avancer. On délègue donc ``fn`` à un
+        thread daemon et on **pompe** l'affichage depuis le thread courant
+        (``tick`` + ``sleep``) jusqu'à ce qu'il finisse — spinner et chronos
+        restent fluides.
+
+        Gestion d'échec : l'exception levée par ``fn`` est propagée à
+        l'identique (la frontière ``CmdError`` de :meth:`_dispatch` la rend en
+        panneau). Gestion des signaux : au Ctrl+C, on tue les process enfants
+        enregistrés (``process.terminate_all`` — les commandes externes passent
+        toutes par le runner, donc sont enregistrées et killables), on attend
+        brièvement la fin du thread, puis on relève ``KeyboardInterrupt``.
+        """
+        box: dict[str, Any] = {}
+
+        def _target() -> None:
+            try:
+                box["result"] = fn()
+            except BaseException as exc:  # noqa: BLE001 — relayé tel quel au thread principal
+                box["exc"] = exc
+
+        worker = threading.Thread(target=_target, daemon=True)
+        worker.start()
+        try:
+            while worker.is_alive():
+                self.steps.tick()
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            process.terminate_all(grace=1.0)  # kill des enfants → débloque fn
+            worker.join(timeout=2.0)
+            raise
+        worker.join()
+        if "exc" in box:
+            raise box["exc"]
+        return box.get("result")
+
+    def _ordered_steps(self) -> list[tuple[str, _StepDef]]:
+        """Méthodes :func:`step` de la classe, dans l'ordre de déclaration."""
+        defs: dict[str, _StepDef] = {}
+        for klass in type(self).__mro__:
+            for name, attr in vars(klass).items():
+                sdef = getattr(attr, "_stepdef", None)
+                if isinstance(sdef, _StepDef) and name not in defs:
+                    defs[name] = sdef
+        return sorted(defs.items(), key=lambda kv: kv[1].order)
+
+    def active_steps(self) -> list[tuple[str, _StepDef]]:
+        """Étapes à exécuter (``when`` filtré). Appelé après :meth:`setup`."""
+        return [
+            (name, sdef)
+            for name, sdef in self._ordered_steps()
+            if sdef.when is None or sdef.when(self)
+        ]
+
+    def run_active_steps(self, active: list[tuple[str, _StepDef]]) -> None:
+        """Exécute ``active`` dans le panneau **déjà ouvert** (cf. ``self.steps``).
+
+        Extrait de :meth:`run` pour qu'un orchestrateur (``dk restart``) puisse
+        enchaîner les étapes de plusieurs commandes dans **un seul** panneau.
+        """
+        for name, sdef in active:
+            method = getattr(self, name)
+            # ``self.step_status`` expose l'activité de l'étape (progression
+            # build branchée via ``on_progress``, etc.).
+            with self.steps.running_step(
+                    sdef.title, collapse=sdef.collapse, spinner=sdef.spinner,
+            ) as status:
+                self.step_status = status
+                method()
+                self.step_status = None
+
+    def run(self) -> None:
+        # ``setup`` (garde-fous, prompts) tourne AVANT le panneau. Puis un seul
+        # panneau Live (header animé en haut + une ligne par étape qui se coche)
+        # couvre toutes les étapes ; ``finish`` (récap + éventuel ``--attach``)
+        # tourne HORS panneau (rendu final, parfois bloquant comme le suivi logs).
+        self.setup()
+        active = self.active_steps()
+        with self.steps.panel(self.command_label, [sdef.title for _, sdef in active]):
+            self.run_active_steps(active)
+        self.finish()
+
+
+__all__ = ["BaseCommand", "ProfileIdOption", "StepCommand", "step"]