forge-mvc-admin 1.0.0rc1__py3-none-any.whl

forge_mvc_admin/__init__.py

@@ -0,0 +1,46 @@
+# pyright: strict
+"""forge-mvc-admin — Opt-in de back-office applicatif Forge.
+
+Couche châssis (couche 1 de l'architecture hybride, voir la roadmap de cadrage
+section 7) : ce paquet porte le contrat d'une ressource administrable
+(`AdminResource`) et le registre explicite (`AdminRegistry`) que les vues
+consommeront. Les vues, les actions et la sécurité HTTP viendront par les
+tickets `ADMIN-*` suivants.
+
+Voir `docs/roadmap/forge-admin-roadmap.md`.
+"""
+from forge_mvc_admin.exceptions import (
+    AdminError,
+    AdminRegistryError,
+    AdminResourceError,
+)
+from forge_mvc_admin.http import AdminController, register_admin_routes
+from forge_mvc_admin.registry import AdminRegistry, registry
+from forge_mvc_admin.resources import AdminResource
+
+__version__ = "1.0.0rc1"
+
+__all__ = [
+    "AdminResource",
+    "AdminRegistry",
+    "registry",
+    "AdminController",
+    "register_admin_routes",
+    "AdminError",
+    "AdminResourceError",
+    "AdminRegistryError",
+]
+
+# Enregistre les templates embarqués (templates/admin/…) auprès du cœur (ADR-046),
+# de sorte que `render("admin/…")` les résolve. Dégradation gracieuse si le cœur
+# ou jinja2 ne sont pas présents (ex. analyse statique du paquet hors runtime).
+try:
+    from jinja2 import PackageLoader as _PackageLoader
+
+    from core.mvc.controller.registry import (
+        register_jinja_template_loader as _register_loader,
+    )
+
+    _register_loader(_PackageLoader("forge_mvc_admin", "templates"))
+except ImportError:
+    pass

forge_mvc_admin/cli/__init__.py

@@ -0,0 +1,2 @@
+# pyright: strict
+"""Commandes CLI de Forge Admin (dispatchées par `forge` quand le paquet est installé)."""

forge_mvc_admin/cli/doctor.py

@@ -0,0 +1,215 @@
+# pyright: strict
+"""Commande ``forge admin:doctor`` — ADMIN-DOCTOR-001.
+
+Rapproche les ressources admin déclarées (objets ``AdminResource`` enregistrés
+par ``mvc/admin/resources.py`` du projet) du contrat d'entité réel lu sur disque
+(``mvc/entities/<snake>/<snake>.json``).
+
+Lecture seule : aucune connexion base. La commande lit les déclarations et les
+contrats, puis signale les écarts. Sévérité : ``fail`` seulement quand la
+déclaration ne charge pas ; tout écart au contrat est un ``warn`` (le contrat
+peut être en retard sur la base, et l'admin interroge la table directement).
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from forge_mvc_admin.exceptions import AdminResourceError
+from forge_mvc_admin.registry import registry
+from forge_mvc_admin.resources import AdminResource
+
+__all__ = ["CheckResult", "reconcile", "run_all", "main"]
+
+_TAGS = {"ok": "[OK]  ", "warn": "[WARN]", "fail": "[FAIL]", "skip": "[SKIP]"}
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    status: Literal["ok", "warn", "fail", "skip"]
+    label: str
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class _EntityContract:
+    table: str
+    columns: frozenset[str]
+    pk: str | None
+
+
+def _check_package() -> CheckResult:
+    try:
+        import forge_mvc_admin
+    except Exception as exc:  # pragma: no cover - le paquet est importé pour arriver ici
+        return CheckResult("fail", "paquet", f"import impossible : {exc}")
+    version = getattr(forge_mvc_admin, "__version__", None)
+    if not version:
+        return CheckResult("warn", "paquet", "importable mais sans __version__")
+    return CheckResult("ok", "paquet", f"forge-mvc-admin {version}")
+
+
+def _load_entity_contracts(root: Path) -> dict[str, _EntityContract]:
+    """Lit les contrats d'entité du projet, indexés par nom d'entité.
+
+    Lecture directe du JSON (lenient) : une colonne vaut ``column`` si présent,
+    sinon le nom logique du champ.
+    """
+    contracts: dict[str, _EntityContract] = {}
+    entities_dir = root / "mvc" / "entities"
+    if not entities_dir.is_dir():
+        return contracts
+    for json_path in sorted(entities_dir.glob("*/*.json")):
+        try:
+            raw = json.loads(json_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        if not isinstance(raw, dict):
+            continue
+        data = cast("dict[str, Any]", raw)
+        name = data.get("name") or data.get("entity")
+        table = data.get("table")
+        if not isinstance(name, str) or not isinstance(table, str):
+            continue
+        columns: set[str] = set()
+        pk: str | None = None
+        fields = data.get("fields")
+        if isinstance(fields, list):
+            for raw_field in cast("list[Any]", fields):
+                if not isinstance(raw_field, dict):
+                    continue
+                field = cast("dict[str, Any]", raw_field)
+                column = field.get("column") or field.get("name")
+                if isinstance(column, str):
+                    columns.add(column)
+                    if field.get("primary_key"):
+                        pk = column
+        contracts[name] = _EntityContract(table=table, columns=frozenset(columns), pk=pk)
+    return contracts
+
+
+def reconcile(resource: AdminResource, contracts: dict[str, _EntityContract]) -> list[CheckResult]:
+    """Rapproche une ressource d'un contrat d'entité. Écarts = `warn`."""
+    label = f"ressource '{resource.slug}'"
+    contract = contracts.get(resource.entity)
+    if contract is None:
+        return [
+            CheckResult(
+                "warn",
+                label,
+                f"entité {resource.entity!r} introuvable dans mvc/entities — "
+                "vérification impossible (la table est interrogée directement)",
+            )
+        ]
+
+    issues: list[CheckResult] = []
+    if contract.table != resource.table:
+        issues.append(
+            CheckResult(
+                "warn",
+                label,
+                f"table déclarée {resource.table!r} ≠ contrat {contract.table!r}",
+            )
+        )
+
+    checked = [
+        ("list_fields", resource.list_fields),
+        ("form_fields", resource.form_fields),
+    ]
+    for kind, names in checked:
+        for column in names:
+            if column not in contract.columns:
+                issues.append(
+                    CheckResult("warn", label, f"{kind} : colonne {column!r} absente du contrat")
+                )
+
+    order_by = resource.order_by or (resource.list_fields[0] if resource.list_fields else "")
+    if order_by and order_by not in contract.columns:
+        issues.append(CheckResult("warn", label, f"order_by : colonne {order_by!r} absente du contrat"))
+
+    if resource.pk not in contract.columns:
+        issues.append(CheckResult("warn", label, f"clé primaire {resource.pk!r} absente du contrat"))
+
+    if not issues:
+        return [CheckResult("ok", label, f"conforme au contrat {resource.entity}")]
+    return issues
+
+
+def _load_declared_resources(root: Path) -> tuple[list[AdminResource], CheckResult | None]:
+    """Importe ``mvc/admin/resources.py`` pour peupler le registre, puis le lit.
+
+    Repart d'un registre vide pour refléter exactement le module du projet, et
+    nettoie ``sys.path`` après import. Retourne ``(ressources, None)`` ou
+    ``([], CheckResult)`` décrivant l'empêchement (skip/fail).
+    """
+    module_file = root / "mvc" / "admin" / "resources.py"
+    if not module_file.is_file():
+        return [], CheckResult(
+            "skip", "ressources admin", "mvc/admin/resources.py absent — lance forge admin:init"
+        )
+
+    registry.clear()
+    root_str = str(root)
+    added = root_str not in sys.path
+    if added:
+        sys.path.insert(0, root_str)
+    for module_name in ("mvc.admin.resources", "mvc.admin", "mvc"):
+        sys.modules.pop(module_name, None)
+    try:
+        importlib.import_module("mvc.admin.resources")
+    except AdminResourceError as exc:
+        return [], CheckResult("fail", "ressources admin", f"déclaration invalide : {exc}")
+    except Exception as exc:
+        return [], CheckResult("fail", "ressources admin", f"import impossible : {exc}")
+    finally:
+        if added:
+            try:
+                sys.path.remove(root_str)
+            except ValueError:
+                pass
+
+    return list(registry.all()), None
+
+
+def run_all(root: Path) -> list[CheckResult]:
+    results: list[CheckResult] = [_check_package()]
+    resources, problem = _load_declared_resources(root)
+    if problem is not None:
+        results.append(problem)
+        return results
+    if not resources:
+        results.append(CheckResult("warn", "ressources admin", "aucune ressource déclarée (registre vide)"))
+        return results
+    results.append(CheckResult("ok", "ressources admin", f"{len(resources)} ressource(s) déclarée(s)"))
+    contracts = _load_entity_contracts(root)
+    for resource in resources:
+        results.extend(reconcile(resource, contracts))
+    return results
+
+
+def print_report(results: list[CheckResult]) -> None:
+    for result in results:
+        tag = _TAGS.get(result.status, "[????]")
+        line = f"{tag} {result.label}"
+        if result.detail:
+            line += f" — {result.detail}"
+        print(line)
+    warns = sum(1 for r in results if r.status == "warn")
+    fails = sum(1 for r in results if r.status == "fail")
+    print()
+    print(f"{warns} avertissement(s), {fails} erreur(s).")
+
+
+def has_failures(results: list[CheckResult]) -> bool:
+    return any(r.status == "fail" for r in results)
+
+
+def main(args: list[str] | None = None) -> int:
+    """Point d'entrée appelé par ``forge.py`` pour ``forge admin:doctor``."""
+    results = run_all(Path.cwd())
+    print_report(results)
+    return 1 if has_failures(results) else 0

forge_mvc_admin/cli/init.py

@@ -0,0 +1,124 @@
+# pyright: strict
+"""Commande ``forge admin:init`` — ADMIN-INIT-COMMAND-001.
+
+Prépare la structure ``mvc/admin/`` d'un projet Forge pour le back-office. À ce
+stade du châssis, la commande crée :
+
+- ``mvc/admin/__init__.py`` ;
+- ``mvc/admin/resources.py`` : fichier où l'application déclare ses ressources
+  administrables (``AdminResource`` enregistrées dans le registre).
+
+Volontairement scoped (mirror ``video:init`` / ``iot:init``) :
+
+- idempotente : un fichier déjà présent à l'identique n'est pas réécrit ;
+- jamais d'écrasement silencieux : un fichier présent au contenu différent
+  provoque un ``WARN`` et n'est pas touché (charte §9) ;
+- pas de choix interactif ; pas de génération de vues ni de templates, qui
+  viendront avec les tickets de dashboard et de rendu.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "STATUS_OK",
+    "STATUS_INFO",
+    "STATUS_WARN",
+    "STATUS_ERROR",
+    "ADMIN_INIT_PY",
+    "ADMIN_RESOURCES_PY",
+    "init_admin",
+    "main",
+]
+
+STATUS_OK = "[OK]"
+STATUS_INFO = "[INFO]"
+STATUS_WARN = "[WARN]"
+STATUS_ERROR = "[ERREUR]"
+
+ADMIN_INIT_PY = '''\
+"""Back-office Forge Admin du projet.
+
+Les ressources administrables sont déclarées dans ``resources.py``.
+"""
+'''
+
+ADMIN_RESOURCES_PY = '''\
+"""Ressources administrables du projet (Forge Admin).
+
+Déclarez ici les entités à administrer en enregistrant des ``AdminResource``
+dans le registre. Adaptez l'exemple à vos entités, puis décommentez-le.
+
+    from forge_mvc_admin import AdminResource, registry
+
+    registry.register(AdminResource(
+        entity="Article",
+        slug="articles",
+        label="Article",
+        plural_label="Articles",
+        list_fields=("title", "published_at"),
+        form_fields=("title", "body"),
+        table="articles",
+    ))
+"""
+'''
+
+
+def _write_if_new(target: Path, content: str) -> str:
+    """Écrit `content` si le fichier est absent. N'écrase jamais.
+
+    Retourne ``"created"``, ``"identical"`` ou ``"different"``.
+    """
+    if target.exists():
+        if target.read_text(encoding="utf-8") == content:
+            return "identical"
+        return "different"
+    target.write_text(content, encoding="utf-8")
+    return "created"
+
+
+def init_admin(project_root: Path) -> int:
+    """Crée la structure ``mvc/admin/`` sous ``project_root``.
+
+    Returns
+    -------
+    0
+        Succès, y compris en relecture idempotente.
+    1
+        Le dossier ``mvc/`` est absent (ce n'est pas un projet Forge).
+    """
+    mvc_dir = project_root / "mvc"
+    if not mvc_dir.is_dir():
+        print(f"{STATUS_ERROR} Ce dossier ne ressemble pas à un projet Forge.")
+        print(
+            "Conseil : lance cette commande à la racine du projet "
+            "(dossier mvc/ attendu)."
+        )
+        return 1
+
+    admin_dir = mvc_dir / "admin"
+    if not admin_dir.exists():
+        admin_dir.mkdir(parents=True)
+        print(f"{STATUS_INFO} Dossier mvc/admin/ créé.")
+
+    files: list[tuple[str, Path, str]] = [
+        ("mvc/admin/__init__.py", admin_dir / "__init__.py", ADMIN_INIT_PY),
+        ("mvc/admin/resources.py", admin_dir / "resources.py", ADMIN_RESOURCES_PY),
+    ]
+    for label, target, content in files:
+        status = _write_if_new(target, content)
+        if status == "created":
+            print(f"{STATUS_OK} Créé : {label}")
+        elif status == "identical":
+            print(f"{STATUS_OK} Déjà présent (identique) : {label}")
+        else:
+            print(f"{STATUS_WARN} {label} existe et diffère — aucune modification.")
+
+    print()
+    print(f"{STATUS_INFO} Déclarez vos ressources dans mvc/admin/resources.py.")
+    return 0
+
+
+def main(args: list[str] | None = None) -> int:
+    """Point d'entrée appelé par ``forge.py`` pour ``forge admin:init``."""
+    return init_admin(Path.cwd())

forge_mvc_admin/exceptions.py

@@ -0,0 +1,19 @@
+# pyright: strict
+"""Exceptions de Forge Admin.
+
+Toutes héritent de `ValueError` (convention des opt-ins Forge), via une base
+commune `AdminError` qui permet d'attraper l'ensemble en un seul `except`.
+"""
+from __future__ import annotations
+
+
+class AdminError(ValueError):
+    """Base de toutes les erreurs Forge Admin."""
+
+
+class AdminResourceError(AdminError):
+    """Contrat de ressource admin invalide."""
+
+
+class AdminRegistryError(AdminError):
+    """Opération invalide sur le registre des ressources admin."""