mic-core 0.1.0__py3-none-any.whl

mic/_lazy.py

@@ -0,0 +1,80 @@
+"""Lazy package re-exports (PEP 562) — keeps ``import mic.X`` cheap and
+import-safe even when the optional extra for X isn't installed.
+
+Problem
+-------
+A package ``__init__.py`` that eagerly does
+``from mic.X.submodule import Symbol`` forces ``import mic.X`` to import
+``submodule`` at package-load time. If that submodule imports an optional
+dependency at module top-level (``import prometheus_client``,
+``import httpx``, ``import grpc``, …), then ``import mic.X`` **crashes**
+for anyone who ran ``pip install mic-struct`` without the ``[X]`` extra —
+even if they only wanted a stdlib-only symbol from another submodule.
+
+Fix
+---
+Defer the submodule import to first attribute access via PEP 562
+``__getattr__``. ``import mic.X`` only runs ``__init__.py`` itself; the
+heavy submodule loads when (and only when) a symbol from it is used.
+If the optional dependency is missing at that point, the ``ImportError``
+is re-raised with a clear ``pip install 'mic-struct[X]'`` hint.
+
+This keeps the established "Philosophy B" of the codebase consistent:
+*importing a package never fails for a missing optional dependency —
+only actually using the dependency-backed symbol does.*
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from typing import Any
+
+#: Une entrée d'export lazy : ``(chemin du sous-module, nom de l'extra | None)``.
+#: ``extra=None`` = sous-module sans dépendance optionnelle (stdlib only) —
+#: le lazy reste utile pour ne pas charger inutilement, mais pas de
+#: message "install extra" à émettre.
+LazyExport = tuple[str, str | None]
+
+
+def make_lazy_getattr(
+    *,
+    package: str,
+    exports: dict[str, LazyExport],
+    fallback: Callable[[str], Any] | None = None,
+) -> Callable[[str], Any]:
+    """Construit un ``__getattr__`` PEP 562 pour un ``__init__.py`` de package.
+
+    Args:
+        package: le ``__name__`` du package (pour les messages d'erreur).
+        exports: ``{symbole: (sous-module, extra | None)}``. Le sous-module
+            est importé à la demande au premier accès du symbole.
+        fallback: handler optionnel essayé quand le nom n'est **pas** dans
+            ``exports`` (ex: alias deprecated). Doit lever ``AttributeError``
+            s'il ne sait pas résoudre — sinon la vraie ``AttributeError``
+            Python serait masquée.
+
+    Returns:
+        Une fonction ``__getattr__(name) -> Any`` à assigner au niveau
+        module dans le ``__init__.py`` du package.
+    """
+
+    def __getattr__(name: str) -> Any:
+        entry = exports.get(name)
+        if entry is None:
+            if fallback is not None:
+                return fallback(name)
+            raise AttributeError(f"module {package!r} has no attribute {name!r}")
+        module_path, extra = entry
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            if extra is not None:
+                raise ImportError(
+                    f"{package}.{name} requires the optional [{extra}] extra. "
+                    f"Install it with: pip install 'mic-struct[{extra}]'"
+                ) from exc
+            raise
+        return getattr(module, name)
+
+    return __getattr__

mic/auth/__init__.py

@@ -0,0 +1,39 @@
+"""Service-to-service auth — JWT HS256 audience-bound.
+
+- Émetteur signe avec un secret partagé (HS256)
+- Audience-bound (chaque token est destiné à UN service)
+- Double-key support pour rotation zéro-downtime : le verifier accepte
+  N et N-1 pendant la fenêtre de transition.
+
+Import lazy (PEP 562) : ``import mic.auth`` ne charge PAS ``pyjwt``.
+Les symboles tirent ``service_auth`` (donc ``jwt``) au premier accès —
+si l'extra ``[auth]`` n'est pas installé, l'erreur est claire. Cf.
+:mod:`mic._lazy`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mic._lazy import LazyExport, make_lazy_getattr
+
+if TYPE_CHECKING:  # pragma: no cover — résolution de types only, pas de coût runtime
+    from mic.auth.service_auth import (
+        ServiceAuthClaims,
+        ServiceAuthSigner,
+        ServiceAuthVerifier,
+    )
+
+_EXPORTS: dict[str, LazyExport] = {
+    "ServiceAuthClaims": ("mic.auth.service_auth", "auth"),
+    "ServiceAuthSigner": ("mic.auth.service_auth", "auth"),
+    "ServiceAuthVerifier": ("mic.auth.service_auth", "auth"),
+}
+
+__getattr__ = make_lazy_getattr(package=__name__, exports=_EXPORTS)
+
+__all__ = [
+    "ServiceAuthClaims",
+    "ServiceAuthSigner",
+    "ServiceAuthVerifier",
+]

mic/auth/service_auth.py

@@ -0,0 +1,317 @@
+"""ServiceAuthSigner + ServiceAuthVerifier — JWT HS256 audience-bound.
+
+Convention (cf. ``service_auth_convention`` mémoire +
+``runbooks/RUNBOOK_SECRETS_ROTATION.md`` sentinel) :
+
+- Algorithme : HS256 uniquement (pas RS256 ; les services partagent
+  un secret commun gardé en OpenBao).
+- Claims standard : ``iss`` (émetteur), ``aud`` (destinataire),
+  ``iat``, ``exp``, ``sub`` optionnel.
+- Double-key : ``ServiceAuthVerifier`` accepte une liste ordonnée
+  de secrets (``current`` puis ``previous``) pour permettre une
+  rotation sans downtime — cf. RUNBOOK_SECRETS_ROTATION.md procédure
+  générique étape 2-3.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+
+from mic.contracts import StrictSchema
+from mic.model.errors import DomainError
+
+_ALGORITHM = "HS256"
+
+_logger = logging.getLogger(__name__)
+
+#: Claims standard que ``ServiceAuthSigner.sign`` met lui-même —
+#: les overrider via ``extra_claims`` permettrait à un caller de forger
+#: un ``aud`` arbitraire, faussement étendre ``exp``, falsifier ``iss``,
+#: etc. On refuse explicitement (cf. ``sign(extra_claims=...)``).
+_RESERVED_CLAIMS: frozenset[str] = frozenset({"iss", "aud", "iat", "exp", "sub", "jti", "nbf"})
+
+# Message constant retourné dans tous les DomainError de verify. On NE
+# leak PAS les détails PyJWT (str(last_error)) au caller — un attacker
+# peut sinon distinguer "signature valide mais expirée" (= il a un
+# secret valide juste périmé) vs "signature invalide" (= mauvais secret),
+# oracle particulièrement utile pendant les fenêtres de rotation. Les
+# détails (exc_info + issuer whitelist) sont loggés côté serveur via
+# ``_logger.warning(..., exc_info=True)`` pour la diagnose ops.
+_GENERIC_VERIFY_FAILURE_MESSAGE = "Token verification failed"
+
+
+class ServiceAuthClaims(StrictSchema):
+    """Claims canoniques exposés par un service token.
+
+    ``jti`` (RFC 7519 §4.1.7) est exposé optionnellement : il est
+    automatiquement injecté par :meth:`ServiceAuthSigner.sign` depuis
+    cette version, mais reste ``None`` quand on vérifie un token
+    émis par une version antérieure ou par un autre service qui ne
+    le propage pas. C'est OK : ``jti`` est une RECOMMENDED claim, pas
+    un REQUIRED claim — l'absence n'est pas une erreur de validation.
+
+    Pour les consommateurs qui font de la révocation per-token
+    (typiquement via :class:`mic.cache.RevokeBlacklist.revoke_jti`),
+    vérifier ``claims.jti is not None`` avant de l'utiliser : un
+    ``None`` signale qu'on ne peut pas révoquer ce token
+    spécifiquement, seulement via la voie per-subject (revoke-epoch).
+
+    ``extra`` porte les claims additionnels embedés par le signer via
+    ``ServiceAuthSigner.sign(extra_claims=...)``. Use case : un service
+    qui propage ``profile_id`` aux côtés du ``sub`` standard pour
+    éviter un lookup DB aval. Dictionnaire vide quand le token n'embed
+    aucun claim non-standard. Les valeurs sont opaques pour mic — le
+    consumer décide leur sémantique.
+    """
+
+    iss: str
+    aud: str
+    iat: int
+    exp: int
+    sub: str | None = None
+    jti: str | None = None
+    # Pydantic copie le default per-instance via Field — ``RUF012`` ne
+    # s'applique pas aux BaseModel. ``noqa`` cosmétique mais explicite.
+    extra: dict[str, Any] = {}  # noqa: RUF012
+
+
+class ServiceAuthSigner:
+    """Signe des JWT HS256 audience-bound.
+
+    Une instance par couple (issuer, secret). L'audience est passée
+    à chaque appel ``sign()`` puisque le même service appelle souvent
+    plusieurs destinataires.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        issuer: str,
+        token_ttl_seconds: int = 3600,
+    ) -> None:
+        if not secret:
+            raise ValueError("ServiceAuthSigner.secret must be a non-empty string")
+        if not issuer:
+            raise ValueError("ServiceAuthSigner.issuer must be a non-empty string")
+        if token_ttl_seconds <= 0:
+            raise ValueError("ServiceAuthSigner.token_ttl_seconds must be > 0")
+        self._secret = secret
+        self._issuer = issuer
+        self._token_ttl = token_ttl_seconds
+
+    def sign(
+        self,
+        *,
+        audience: str,
+        subject: str | None = None,
+        jti: str | None = None,
+        extra_claims: dict[str, Any] | None = None,
+    ) -> str:
+        """Build a Bearer JWT signed with the configured secret.
+
+        Returns the encoded JWT string (no "Bearer " prefix — the
+        client adds it).
+
+        Args:
+            audience: ``aud`` claim — destinataire attendu (un service
+                par token).
+            subject: ``sub`` claim — identité propagée (typiquement
+                user_id ou email pour les tokens user-side).
+            jti: ``jti`` claim (RFC 7519 §4.1.7) — identifiant unique
+                du token. **Auto-généré** via ``uuid.uuid4().hex`` (128
+                bits d'entropie) si ``None``, ce qui est le cas standard.
+                Override uniquement pour les tests qui ont besoin de
+                jtis déterministes, ou pour les use cases avancés
+                (ex. propager un trace-id en jti). Si fourni, doit être
+                non-vide.
+            extra_claims: claims additionnels à embedder dans le JWT.
+                Use case typique : propager une identité applicative
+                secondaire (``profile_id``, ``tenant_id``, ``role``)
+                aux côtés du ``sub`` standard pour éviter un lookup DB
+                aval. Les claims standard (``iss``, ``aud``, ``iat``,
+                ``exp``, ``sub``, ``jti``) ne peuvent PAS être
+                overridées via ce paramètre — un override silencieux
+                permettrait à un caller de forger un ``aud`` arbitraire
+                ou de faussement étendre l'``exp``. Une tentative lève
+                ``ValueError``.
+
+        Le ``jti`` permet aux consumers de faire de la révocation
+        per-token via :class:`mic.cache.RevokeBlacklist` (``revoke_jti``,
+        ``is_jti_revoked``) — usage typique : logout-single-device en
+        ajoutant l'ancien ``jti`` à la blacklist à TTL = lifetime
+        restant du token.
+        """
+        if not audience:
+            raise ValueError("ServiceAuthSigner.sign(audience=...) must be non-empty")
+        if jti is not None and not jti:
+            raise ValueError("ServiceAuthSigner.sign(jti=...) must be non-empty when provided")
+        if extra_claims is not None:
+            reserved = _RESERVED_CLAIMS & extra_claims.keys()
+            if reserved:
+                raise ValueError(
+                    f"ServiceAuthSigner.sign(extra_claims=...) cannot override "
+                    f"reserved claim(s): {sorted(reserved)}"
+                )
+        now = datetime.now(UTC)
+        payload: dict[str, Any] = {
+            "iss": self._issuer,
+            "aud": audience,
+            "iat": int(now.timestamp()),
+            "exp": int((now + timedelta(seconds=self._token_ttl)).timestamp()),
+            "jti": jti if jti is not None else uuid.uuid4().hex,
+        }
+        if subject is not None:
+            payload["sub"] = subject
+        if extra_claims:
+            payload.update(extra_claims)
+        return jwt.encode(payload, self._secret, algorithm=_ALGORITHM)
+
+
+class ServiceAuthVerifier:
+    """Vérifie les JWT HS256 destinés à ce service.
+
+    Supporte la rotation à zéro-downtime via une **liste ordonnée**
+    de secrets : le verifier essaye le ``current`` d'abord, puis les
+    ``previous`` un par un. Tant qu'au moins un secret valide
+    correspond ET que les claims passent (audience, issuer, expiration),
+    le token est accepté.
+
+    L'``audience`` attendue est fixe par instance (= app name de ce
+    service). Les ``allowed_issuers`` est la liste des émetteurs
+    légitimes (whitelist).
+    """
+
+    def __init__(
+        self,
+        *,
+        secrets: tuple[str, ...],
+        audience: str,
+        allowed_issuers: tuple[str, ...],
+        leeway_seconds: int = 30,
+    ) -> None:
+        # leeway 30s par défaut = tolérance NTP-skew typique entre 2
+        # services. Sans ça, une dérive d'1s entre signer et verifier
+        # rejette le token (``iat`` dans le futur OU ``exp`` expirée).
+        # 30s = compromis : couvre 99 % des skews observés en cluster
+        # sans ouvrir une fenêtre de replay critique.
+        if not secrets:
+            raise ValueError("ServiceAuthVerifier.secrets must be non-empty tuple")
+        if any(not s for s in secrets):
+            raise ValueError("ServiceAuthVerifier.secrets must not contain empty strings")
+        if not audience:
+            raise ValueError("ServiceAuthVerifier.audience must be non-empty")
+        if not allowed_issuers:
+            raise ValueError("ServiceAuthVerifier.allowed_issuers must be non-empty tuple")
+        if leeway_seconds < 0:
+            raise ValueError("ServiceAuthVerifier.leeway_seconds must be >= 0")
+        self._secrets = secrets
+        self._audience = audience
+        self._allowed_issuers = set(allowed_issuers)
+        self._leeway = leeway_seconds
+
+    def verify(self, token: str) -> ServiceAuthClaims:
+        """Vérifie le token et retourne les claims parsés.
+
+        Raises ``DomainError`` (code ``service_auth.invalid_*``) si :
+
+        - signature ne match aucun secret (current ou previous)
+        - exp dépassée (au-delà du leeway)
+        - aud != self.audience
+        - iss not in allowed_issuers
+        - structure du token invalide
+
+        **Timing-safe iteration** : tous les secrets de la
+        liste sont essayés systématiquement, sans early break sur le
+        premier match. Sans ça, un attacker qui mesure la latence à la
+        μs peut deviner la **position** du secret valide (``current``
+        vs ``previous``) → side-channel mineur mais réel pendant la
+        fenêtre de rotation. Coût : 1 HMAC supplémentaire par requête
+        (≪ 1 μs) — négligeable.
+        """
+        if not token:
+            raise DomainError(
+                code="service_auth.invalid_token",
+                message="Empty token",
+            )
+
+        payload: dict[str, Any] | None = None
+        last_error: jwt.PyJWTError | None = None
+        for secret in self._secrets:
+            try:
+                candidate = jwt.decode(
+                    token,
+                    secret,
+                    algorithms=[_ALGORITHM],
+                    audience=self._audience,
+                    leeway=self._leeway,
+                    options={"require": ["iss", "aud", "iat", "exp"]},
+                )
+            except jwt.PyJWTError as exc:
+                last_error = exc
+                continue
+            # Garde le PREMIER payload valide trouvé, mais on continue
+            # d'itérer pour ne pas leak la position via timing.
+            if payload is None:
+                payload = candidate
+
+        if payload is None:
+            # Toutes les secrets ont échoué. On retourne au caller un
+            # ``code`` catégorisé (contrat public — utile pour l'UX :
+            # ``expired`` vs ``invalid_signature``) mais **aucun message
+            # détaillé ni stacktrace** : ce serait un oracle pour
+            # l'attacker (cf. constante ``_GENERIC_VERIFY_FAILURE_MESSAGE``).
+            # La cause précise (str(last_error)) est loggée côté serveur
+            # pour la diagnose ops.
+            code = _classify_error(last_error)
+            _logger.warning(
+                "ServiceAuthVerifier: token verification failed (code=%s)",
+                code,
+                exc_info=last_error,
+            )
+            raise DomainError(code=code, message=_GENERIC_VERIFY_FAILURE_MESSAGE)
+
+        issuer = payload.get("iss")
+        if issuer not in self._allowed_issuers:
+            # Ne pas leaker ``self._allowed_issuers`` au caller — c'est
+            # de la recon précieuse (liste des services internes connus).
+            # On garde le ``code`` précis pour le caller légitime, et
+            # on log la valeur reçue + la whitelist server-side.
+            _logger.warning(
+                "ServiceAuthVerifier: issuer rejected (received=%r, allowed=%s)",
+                issuer,
+                sorted(self._allowed_issuers),
+            )
+            raise DomainError(
+                code="service_auth.invalid_issuer",
+                message=_GENERIC_VERIFY_FAILURE_MESSAGE,
+            )
+
+        # Sépare les claims standard (typés sur ServiceAuthClaims) des
+        # claims additionnels embedés via ``ServiceAuthSigner.sign(
+        # extra_claims=...)``. Les non-standard atterrissent dans
+        # ``extra``, opaques pour mic mais accessibles au consumer.
+        standard_claims = {"iss", "aud", "iat", "exp", "sub", "jti"}
+        normalized: dict[str, Any] = {k: v for k, v in payload.items() if k in standard_claims}
+        normalized["extra"] = {k: v for k, v in payload.items() if k not in standard_claims}
+        return ServiceAuthClaims.model_validate(normalized)
+
+
+def _classify_error(error: jwt.PyJWTError | None) -> str:
+    """Mapping fin des erreurs PyJWT vers code DomainError."""
+    if isinstance(error, jwt.ExpiredSignatureError):
+        return "service_auth.expired"
+    if isinstance(error, jwt.InvalidAudienceError):
+        return "service_auth.invalid_audience"
+    if isinstance(error, jwt.InvalidSignatureError):
+        return "service_auth.invalid_signature"
+    if isinstance(error, jwt.MissingRequiredClaimError):
+        return "service_auth.missing_claim"
+    if isinstance(error, jwt.DecodeError):
+        return "service_auth.malformed"
+    return "service_auth.invalid_token"

mic/cli/__init__.py

@@ -0,0 +1,24 @@
+"""CLI canon — argparse stdlib + ``CliCommandSpec`` builder.
+
+Cf. R12 dans ``CONTRIBUTING.md`` :
+
+- Tout service avec opérations opérateur (drain, requeue,
+  reindex, query, replay, …) doit livrer un CLI via cette brique.
+- Framework imposé : ``argparse`` stdlib (pas de Click/Typer).
+- 1 fichier ``frameworks/cli/<groupe>_commands.py`` par bounded
+  context, chaque commande exposée via un ``CliCommandSpec``.
+
+L'extra ``mic-struct[cli]`` existe pour cohérence — ``mic.cli`` n'a
+aucune dépendance externe (stdlib only).
+"""
+
+from __future__ import annotations
+
+from mic.cli.builder import build_parser, dispatch
+from mic.cli.spec import CliCommandSpec
+
+__all__ = [
+    "CliCommandSpec",
+    "build_parser",
+    "dispatch",
+]

mic/cli/builder.py

@@ -0,0 +1,176 @@
+"""Builder ``ArgumentParser`` racine + dispatch robuste.
+
+Convention :
+
+    parser = build_parser(
+        prog="my-service",
+        description="My service operator CLI.",
+        version="1.2.3",                  # optional → ajoute --version
+        verbose=True,                     # optional → ajoute -v/--verbose
+        commands=(
+            CliCommandSpec(name="health", run=health_command),
+            CliCommandSpec(
+                name="drain-once",
+                run=drain_command,
+                build_args=lambda p: p.add_argument(
+                    "--batch-size", type=int, default=10
+                ),
+            ),
+        ),
+    )
+
+    if __name__ == "__main__":
+        sys.exit(dispatch(parser, sys.argv[1:]))
+
+``dispatch`` traite les conditions shell standard :
+
+- ``KeyboardInterrupt`` (Ctrl-C) → exit ``130`` (= ``128 + SIGINT``)
+- ``BrokenPipeError`` (pipe fermé en aval, ex. ``cmd | head``) → exit ``0``
+- ``SystemExit(code)`` (argparse error, sys.exit, ...) → propagé tel quel
+- Toute autre exception → propagée (laissée au caller pour traceback)
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Iterable, Sequence
+
+from mic.cli.spec import CliCommandSpec
+
+#: Code shell standard quand un process est interrompu par SIGINT.
+#: 128 + signal_number (SIGINT=2). Cf. POSIX advisory.
+_EXIT_SIGINT = 130
+
+#: Seuil ``-vv``+ (count ≥ ce seuil → DEBUG, sinon INFO).
+_VERBOSE_DEBUG_THRESHOLD = 2
+
+
+def build_parser(
+    *,
+    prog: str,
+    description: str,
+    commands: Iterable[CliCommandSpec],
+    version: str | None = None,
+    verbose: bool = False,
+) -> argparse.ArgumentParser:
+    """Construit un ``ArgumentParser`` racine avec un sub-parser par
+    ``CliCommandSpec``.
+
+    Args:
+        prog: nom du programme (affiché dans ``--help``).
+        description: description courte (affichée dans ``--help`` racine).
+        commands: les ``CliCommandSpec`` à exposer (≥ 1).
+        version: si fourni, ajoute ``--version`` qui imprime ``f"{prog}
+            {version}"`` puis exit 0.
+        verbose: si True, ajoute le flag global ``-v/--verbose`` (action
+            ``count``, accumulable : ``-v``, ``-vv``, ``-vvv``).
+            Disponible dans tous les sub-commands via ``args.verbose``
+            (int ≥ 0). Le runner choisit comment l'interpréter (souvent
+            ``WARNING/INFO/DEBUG`` selon le count).
+
+    Lève ``ValueError`` si :
+
+    - ``commands`` est vide (= CLI inutilisable) ;
+    - deux specs ont le même ``name`` (collision sub-command) ;
+    - un alias collisionne avec un nom déjà pris.
+    """
+    specs = tuple(commands)
+    if not specs:
+        raise ValueError("build_parser(commands=...) must contain at least one CliCommandSpec")
+
+    seen: set[str] = set()
+    for spec in specs:
+        if spec.name in seen:
+            raise ValueError(f"duplicate CLI command name: {spec.name!r}")
+        seen.add(spec.name)
+        for alias in spec.aliases:
+            if alias in seen:
+                raise ValueError(
+                    f"CLI alias {alias!r} (on command {spec.name!r}) collides with "
+                    f"an existing name or alias"
+                )
+            seen.add(alias)
+
+    parser = argparse.ArgumentParser(prog=prog, description=description)
+    if version is not None:
+        parser.add_argument(
+            "--version",
+            action="version",
+            version=f"{prog} {version}",
+        )
+    if verbose:
+        parser.add_argument(
+            "-v",
+            "--verbose",
+            action="count",
+            default=0,
+            help="Increase verbosity (-v, -vv, -vvv for WARNING/INFO/DEBUG).",
+        )
+
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    for spec in specs:
+        sub_parser = sub.add_parser(
+            spec.name,
+            help=spec.resolved_help(),
+            aliases=list(spec.aliases),
+        )
+        if spec.build_args is not None:
+            spec.build_args(sub_parser)
+        sub_parser.set_defaults(_mic_run=spec.run)
+
+    return parser
+
+
+def dispatch(parser: argparse.ArgumentParser, argv: Sequence[str] | None = None) -> int:
+    """Parse ``argv`` puis exécute la commande sélectionnée.
+
+    Codes de sortie :
+
+    - ``0`` = succès (le runner a retourné 0 OU pipe cassé en aval)
+    - ``130`` = ``KeyboardInterrupt`` (Ctrl-C, convention shell SIGINT)
+    - ce que retourne le ``run`` de la commande pour les autres cas
+
+    Les ``SystemExit`` (argparse errors, ``sys.exit(N)`` dans un runner)
+    sont laissés se propager — le caller décide. ``KeyboardInterrupt``
+    et ``BrokenPipeError`` sont catchés explicitement parce qu'ils sont
+    *normaux* en CLI (Ctrl-C, ``cmd | head``) et ne devraient pas
+    afficher de traceback.
+    """
+    args = parser.parse_args(argv)
+    runner = getattr(args, "_mic_run", None)
+    if runner is None:  # pragma: no cover — argparse ``required=True`` empêche
+        parser.error("no command specified")
+
+    if getattr(args, "verbose", 0):
+        _configure_logging_from_verbose(args.verbose)
+
+    try:
+        return int(runner(args))
+    except KeyboardInterrupt:
+        return _EXIT_SIGINT
+    except BrokenPipeError:
+        # ``cmd | head`` ferme le pipe → on sort silencieusement comme
+        # le ferait n'importe quel utilitaire Unix bien élevé.
+        return 0
+
+
+def _configure_logging_from_verbose(level_count: int) -> None:
+    """Map ``-v`` count → niveau logging stdlib.
+
+    Convention :
+    - ``-v``    → INFO
+    - ``-vv``+  → DEBUG
+    - 0         → WARNING (default Python ; on n'override pas si non demandé)
+    """
+    if level_count >= _VERBOSE_DEBUG_THRESHOLD:
+        log_level = logging.DEBUG
+    else:
+        log_level = logging.INFO
+    logging.basicConfig(
+        stream=sys.stderr,
+        level=log_level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )