arclith-cli 0.20.0__tar.gz → 0.21.0__tar.gz

{arclith_cli-0.20.0 → arclith_cli-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arclith-cli
-Version: 0.20.0
+Version: 0.21.0
 Summary: CLI scaffolding tool for arclith — hexagonal architecture framework
 Author-email: Killian KOPP <killiankopp@gmail.com>
 License:                                  Apache License
@@ -186,7 +186,7 @@ License:                                  Apache License
 License-File: LICENSE
 Keywords: arclith,cli,ddd,hexagonal-architecture,scaffold
 Requires-Python: >=3.13
-Requires-Dist: arclith>=0.23.0
+Requires-Dist: arclith>=0.24.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
@@ -252,7 +252,10 @@ template est régénéré côté CLI pour appliquer le contrat `runtime/docker-i
 
 ### `add-entity` — Ajouter une entité métier
 
-Crée uniquement le fichier minimal d'une entité dans `src/<package>/domain/models/`.
+Crée un squelette minimal et guidé dans `src/<package>/domain/models/`. Le fichier
+signale où déclarer les champs et invariants, rappelle les champs déjà fournis par
+`Entity` et renvoie vers les guides Arclith et Pydantic. L'exemple `Field(...)`
+reste commenté, donc aucun import inutilisé n'est ajouté.
 
 ```bash
 cd my-recipe-service
@@ -265,21 +268,41 @@ Fichier généré :
 src/<package>/domain/models/shopping_item.py
 ```
 
-La commande ne génère aucun CRUD, aucun port repository, aucun adapter et aucun endpoint. Elle pose seulement le point d'ancrage du modèle métier ; le développeur complète ensuite les champs et invariants de l'entité.
+La commande ne génère aucun CRUD, aucun port repository, aucun adapter et aucun
+endpoint. Elle pose seulement le point d'ancrage du modèle métier ; le
+développeur complète ensuite les champs et invariants de l'entité.
 
 ---
 
 ### `add-usecase` — Ajouter un cas d'usage
 
-Crée le port inbound minimal dans `src/<package>/domain/ports/inbound/`, puis le fichier minimal du
-cas d'usage dans `src/<package>/application/use_cases/`.
+Crée un port inbound guidé dans `src/<package>/domain/ports/inbound/`, puis le
+cas d'usage dans `src/<package>/application/use_cases/`. Sans option de liaison,
+la commande interactive propose les entités détectées par analyse AST, la
+création d'une nouvelle entité ou un cas d'usage transverse.
 
 ```bash
 cd my-recipe-service
+
+# Mode interactif : choisir une entité détectée, en créer une ou rester transverse
 arclith-cli add-usecase PlanShoppingList
-arclith-cli add-usecase find-by-name
+
+# Modes directs, complets pour les agents et la CI
+arclith-cli add-usecase CreateTodo --entity Todo
+arclith-cli add-usecase CreateRecipe --new-entity Recipe
+arclith-cli add-usecase RunMaintenance --no-entity
 ```
 
+| Option | Effet |
+|---|---|
+| `--entity Todo` | lie le use case à une entité détectée et échoue si elle est absente |
+| `--new-entity Todo` | crée l'entité si nécessaire, puis génère le use case lié |
+| `--no-entity` | génère un `Command`, un `Result` et un use case transverse sans repository |
+
+Ces options sont mutuellement exclusives. `--new-entity` réutilise une entité
+valide déjà présente, mais refuse un fichier homonyme qui ne déclare pas la
+classe `Entity` attendue.
+
 Fichier généré :
 
 ```text
@@ -287,9 +310,17 @@ src/<package>/domain/ports/inbound/plan_shopping_list.py
 src/<package>/application/use_cases/plan_shopping_list.py
 ```
 
-Le nom peut être fourni en PascalCase, snake_case ou kebab-case. Le suffixe `UseCase` est normalisé : `PlanShoppingListUseCase` et `plan-shopping-list-use-case` génèrent tous les deux `PlanShoppingListUseCase`.
-
-Comme `add-entity`, cette commande ne câble pas FastAPI, FastMCP, LangGraph, un repository ou un service. Les adapters se branchent ensuite explicitement avec `add-adapter` et devraient dépendre du port inbound généré.
+Le nom peut être fourni en PascalCase, snake_case ou kebab-case. Le suffixe
+`UseCase` est normalisé : `PlanShoppingListUseCase` et
+`plan-shopping-list-use-case` génèrent tous les deux
+`PlanShoppingListUseCase`.
+
+Pour une entité principale, le squelette injecte explicitement
+`Repository[Entity]` et type `execute` avec un `Command` Pydantic et l'entité en
+retour. Le mode transverse génère plutôt un `Command` et un `Result` Pydantic,
+sans repository implicite. Aucun mode ne câble FastAPI, FastMCP ou LangGraph.
+Les exemples complets et les règles de séparation sont dans le
+[deep dive du scaffold CLI](https://karned-rekipe.github.io/arclith/deep-dives/cli-scaffold/).
 
 ---
 

{arclith_cli-0.20.0 → arclith_cli-0.21.0}/README.md

@@ -58,7 +58,10 @@ template est régénéré côté CLI pour appliquer le contrat `runtime/docker-i
 
 ### `add-entity` — Ajouter une entité métier
 
-Crée uniquement le fichier minimal d'une entité dans `src/<package>/domain/models/`.
+Crée un squelette minimal et guidé dans `src/<package>/domain/models/`. Le fichier
+signale où déclarer les champs et invariants, rappelle les champs déjà fournis par
+`Entity` et renvoie vers les guides Arclith et Pydantic. L'exemple `Field(...)`
+reste commenté, donc aucun import inutilisé n'est ajouté.
 
 ```bash
 cd my-recipe-service
@@ -71,21 +74,41 @@ Fichier généré :
 src/<package>/domain/models/shopping_item.py
 ```
 
-La commande ne génère aucun CRUD, aucun port repository, aucun adapter et aucun endpoint. Elle pose seulement le point d'ancrage du modèle métier ; le développeur complète ensuite les champs et invariants de l'entité.
+La commande ne génère aucun CRUD, aucun port repository, aucun adapter et aucun
+endpoint. Elle pose seulement le point d'ancrage du modèle métier ; le
+développeur complète ensuite les champs et invariants de l'entité.
 
 ---
 
 ### `add-usecase` — Ajouter un cas d'usage
 
-Crée le port inbound minimal dans `src/<package>/domain/ports/inbound/`, puis le fichier minimal du
-cas d'usage dans `src/<package>/application/use_cases/`.
+Crée un port inbound guidé dans `src/<package>/domain/ports/inbound/`, puis le
+cas d'usage dans `src/<package>/application/use_cases/`. Sans option de liaison,
+la commande interactive propose les entités détectées par analyse AST, la
+création d'une nouvelle entité ou un cas d'usage transverse.
 
 ```bash
 cd my-recipe-service
+
+# Mode interactif : choisir une entité détectée, en créer une ou rester transverse
 arclith-cli add-usecase PlanShoppingList
-arclith-cli add-usecase find-by-name
+
+# Modes directs, complets pour les agents et la CI
+arclith-cli add-usecase CreateTodo --entity Todo
+arclith-cli add-usecase CreateRecipe --new-entity Recipe
+arclith-cli add-usecase RunMaintenance --no-entity
 ```
 
+| Option | Effet |
+|---|---|
+| `--entity Todo` | lie le use case à une entité détectée et échoue si elle est absente |
+| `--new-entity Todo` | crée l'entité si nécessaire, puis génère le use case lié |
+| `--no-entity` | génère un `Command`, un `Result` et un use case transverse sans repository |
+
+Ces options sont mutuellement exclusives. `--new-entity` réutilise une entité
+valide déjà présente, mais refuse un fichier homonyme qui ne déclare pas la
+classe `Entity` attendue.
+
 Fichier généré :
 
 ```text
@@ -93,9 +116,17 @@ src/<package>/domain/ports/inbound/plan_shopping_list.py
 src/<package>/application/use_cases/plan_shopping_list.py
 ```
 
-Le nom peut être fourni en PascalCase, snake_case ou kebab-case. Le suffixe `UseCase` est normalisé : `PlanShoppingListUseCase` et `plan-shopping-list-use-case` génèrent tous les deux `PlanShoppingListUseCase`.
-
-Comme `add-entity`, cette commande ne câble pas FastAPI, FastMCP, LangGraph, un repository ou un service. Les adapters se branchent ensuite explicitement avec `add-adapter` et devraient dépendre du port inbound généré.
+Le nom peut être fourni en PascalCase, snake_case ou kebab-case. Le suffixe
+`UseCase` est normalisé : `PlanShoppingListUseCase` et
+`plan-shopping-list-use-case` génèrent tous les deux
+`PlanShoppingListUseCase`.
+
+Pour une entité principale, le squelette injecte explicitement
+`Repository[Entity]` et type `execute` avec un `Command` Pydantic et l'entité en
+retour. Le mode transverse génère plutôt un `Command` et un `Result` Pydantic,
+sans repository implicite. Aucun mode ne câble FastAPI, FastMCP ou LangGraph.
+Les exemples complets et les règles de séparation sont dans le
+[deep dive du scaffold CLI](https://karned-rekipe.github.io/arclith/deep-dives/cli-scaffold/).
 
 ---
 

arclith_cli-0.21.0/arclith_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.21.0"

{arclith_cli-0.20.0 → arclith_cli-0.21.0}/arclith_cli/catalogs/persistence.py

@@ -11,7 +11,9 @@ from arclith_cli.catalogs.repository_facets import (
     MARIADB_FACETS,
     MEMORY_FACETS,
     MONGODB_FACETS,
-    POSTGRESQL_FACETS,
+)
+from arclith_cli.catalogs.repository_postgresql import (
+    POSTGRESQL_REPOSITORY_ADAPTER,
 )
 
 REPOSITORY_CAPABILITY = CapabilitySpec(
@@ -154,86 +156,7 @@ multitenant: false
             ),
             facets=MARIADB_FACETS,
         ),
-        AdapterSpec(
-            name="postgresql",
-            capability="repository",
-            layer="outbound",
-            description="Repository PostgreSQL async optionnel, pilote par SQLAlchemy et asyncpg, avec payload JSONB generique.",
-            config_path="config/adapters/outbound/postgresql.yaml",
-            config_template="""\
-url: null   # à mapper via config/secrets.yaml ou resolver env/vault si vous fournissez une URL complète
-host: {host}
-port: {port}
-database: {database}
-user: {user}
-password: null   # à mapper via config/secrets.yaml ou resolver env/vault
-schema: {schema}
-driver: {driver}
-table_prefix: "{table_prefix}"
-multitenant: {multitenant}
-""",
-            secret_mappings=(
-                SecretMappingSpec(
-                    field_path="adapters.postgresql.url",
-                    secret_key="POSTGRESQL_URL",
-                ),
-                SecretMappingSpec(
-                    field_path="adapters.postgresql.password",
-                    secret_key="POSTGRESQL_PASSWORD",
-                ),
-            ),
-            parameters=(
-                ParameterSpec(
-                    name="host",
-                    kind="string",
-                    prompt="host",
-                    default="127.0.0.1",
-                ),
-                ParameterSpec(
-                    name="port",
-                    kind="string",
-                    prompt="port",
-                    default="5432",
-                ),
-                ParameterSpec(
-                    name="database",
-                    kind="string",
-                    prompt="database",
-                    default_from_project_name=True,
-                ),
-                ParameterSpec(
-                    name="user",
-                    kind="string",
-                    prompt="user",
-                    default="app",
-                ),
-                ParameterSpec(
-                    name="schema",
-                    kind="string",
-                    prompt="schema",
-                    default="public",
-                ),
-                ParameterSpec(
-                    name="driver",
-                    kind="string",
-                    prompt="driver",
-                    default="asyncpg",
-                ),
-                ParameterSpec(
-                    name="table_prefix",
-                    kind="string",
-                    prompt="table_prefix",
-                    default="",
-                ),
-                ParameterSpec(
-                    name="multitenant",
-                    kind="boolean",
-                    prompt="multitenant",
-                    default=False,
-                ),
-            ),
-            facets=POSTGRESQL_FACETS,
-        ),
+        POSTGRESQL_REPOSITORY_ADAPTER,
     ),
 )
 

{arclith_cli-0.20.0 → arclith_cli-0.21.0}/arclith_cli/catalogs/repository_facets.py

@@ -77,11 +77,11 @@ POSTGRESQL_FACETS = AdapterFacets(
     schema_strategy="json_table",
     recommended_for=(
         "services nécessitant un SQL serveur robuste",
-        "état partagé multi-process avec payload JSONB",
+        "payload JSONB par défaut ou colonnes typées explicitement mappées",
     ),
     limits=(
-        "entité stockée comme payload JSONB générique",
-        "pas de relations, joins ou migrations métier via le port",
+        "le mapping structuré est opt-in et fourni par l'application",
+        "pas de relations, joins ou migrations automatiques via le port",
     ),
 )
 

arclith_cli-0.21.0/arclith_cli/catalogs/repository_postgresql.py

@@ -0,0 +1,107 @@
+from arclith_cli.capability_models import (
+    AdapterSpec,
+    ParameterSpec,
+    SecretMappingSpec,
+)
+from arclith_cli.catalogs.repository_facets import POSTGRESQL_FACETS
+
+POSTGRESQL_REPOSITORY_ADAPTER = AdapterSpec(
+    name="postgresql",
+    capability="repository",
+    layer="outbound",
+    description=(
+        "Repository PostgreSQL async optionnel avec JSONB par défaut ou "
+        "mapping structuré explicite."
+    ),
+    config_path="config/adapters/outbound/postgresql.yaml",
+    config_template="""\
+url: null   # à mapper via config/secrets.yaml ou resolver env/vault si vous fournissez une URL complète
+host: {host}
+port: {port}
+database: {database}
+user: {user}
+password: null   # à mapper via config/secrets.yaml ou resolver env/vault
+schema: {schema}
+driver: {driver}
+table_prefix: "{table_prefix}"
+mapping_strategy: {mapping_strategy}
+auto_create_schema: {auto_create_schema}
+multitenant: {multitenant}
+""",
+    secret_mappings=(
+        SecretMappingSpec(
+            field_path="adapters.postgresql.url",
+            secret_key="POSTGRESQL_URL",
+        ),
+        SecretMappingSpec(
+            field_path="adapters.postgresql.password",
+            secret_key="POSTGRESQL_PASSWORD",
+        ),
+    ),
+    parameters=(
+        ParameterSpec(
+            name="host",
+            kind="string",
+            prompt="host",
+            default="127.0.0.1",
+        ),
+        ParameterSpec(
+            name="port",
+            kind="string",
+            prompt="port",
+            default="5432",
+        ),
+        ParameterSpec(
+            name="database",
+            kind="string",
+            prompt="database",
+            default_from_project_name=True,
+        ),
+        ParameterSpec(
+            name="user",
+            kind="string",
+            prompt="user",
+            default="app",
+        ),
+        ParameterSpec(
+            name="schema",
+            kind="string",
+            prompt="schema",
+            default="public",
+        ),
+        ParameterSpec(
+            name="driver",
+            kind="string",
+            prompt="driver",
+            default="asyncpg",
+        ),
+        ParameterSpec(
+            name="table_prefix",
+            kind="string",
+            prompt="table_prefix",
+            default="",
+        ),
+        ParameterSpec(
+            name="mapping_strategy",
+            kind="string",
+            prompt="mapping_strategy",
+            default="generic_json",
+            choices=("generic_json", "structured"),
+        ),
+        ParameterSpec(
+            name="auto_create_schema",
+            kind="boolean",
+            prompt="auto_create_schema",
+            default=True,
+        ),
+        ParameterSpec(
+            name="multitenant",
+            kind="boolean",
+            prompt="multitenant",
+            default=False,
+        ),
+    ),
+    facets=POSTGRESQL_FACETS,
+)
+
+__all__ = ["POSTGRESQL_REPOSITORY_ADAPTER"]

{arclith_cli-0.20.0 → arclith_cli-0.21.0}/arclith_cli/core_scaffold.py

@@ -7,37 +7,21 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
+from .entity_scanner import EntityInfo, scan_entities
 from .project_paths import ProjectPaths, detect_project_paths
 from .rename import EntityNames
+from .scaffold_templates import (
+    render_entity_inbound_port_template,
+    render_entity_template,
+    render_entity_use_case_template,
+    render_transverse_inbound_port_template,
+    render_transverse_use_case_template,
+)
 
 console = Console()
 
 _NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_\-]*$")
 
-_ENTITY_TEMPLATE = """from arclith.domain.models.entity import Entity
-
-
-class {class_name}(Entity):
-    pass
-"""
-
-_INBOUND_PORT_TEMPLATE = """from abc import ABC, abstractmethod
-
-
-class {class_name}Port(ABC):
-    @abstractmethod
-    async def execute(self) -> None:
-        raise NotImplementedError
-"""
-
-_USE_CASE_TEMPLATE = """from {inbound_port_module} import {class_name}Port
-
-
-class {class_name}UseCase({class_name}Port):
-    async def execute(self) -> None:
-        raise NotImplementedError("Implement {class_name}UseCase.execute")
-"""
-
 _INTENT_INTERPRETER_TEMPLATE = """class {class_name}Interpreter:
     async def interpret(self, prompt: str) -> None:
         raise NotImplementedError("Implement {class_name}Interpreter.interpret")
@@ -55,7 +39,9 @@ class UseCaseNames:
         pascal = _strip_pascal_suffix(names.pascal)
         snake = _strip_snake_suffix(names.snake)
         if not pascal or not snake:
-            console.print(f"[red]✗[/red] Nom de cas d'usage invalide : [bold]{raw}[/bold].")
+            console.print(
+                f"[red]✗[/red] Nom de cas d'usage invalide : [bold]{raw}[/bold]."
+            )
             raise typer.Exit(1)
         return cls(pascal=pascal, snake=snake)
 
@@ -71,7 +57,9 @@ class IntentInterpreterNames:
         pascal = _strip_pascal_intent_interpreter_suffix(names.pascal)
         snake = _strip_snake_intent_interpreter_suffix(names.snake)
         if not pascal or not snake:
-            console.print(f"[red]✗[/red] Nom d'interpréteur d'intention invalide : [bold]{raw}[/bold].")
+            console.print(
+                f"[red]✗[/red] Nom d'interpréteur d'intention invalide : [bold]{raw}[/bold]."
+            )
             raise typer.Exit(1)
         return cls(pascal=pascal, snake=snake)
 
@@ -88,7 +76,9 @@ def add_entity_cmd(*, project_dir: Path | None = None, entity_name: str) -> Path
     _assert_missing(entity_file, project_dir)
 
     _ensure_package_dirs(paths, "domain", "models")
-    entity_file.write_text(_ENTITY_TEMPLATE.format(class_name=names.pascal), encoding="utf-8")
+    entity_file.write_text(
+        render_entity_template(class_name=names.pascal), encoding="utf-8"
+    )
     console.print(
         f"[green]✓[/green] Entité {names.pascal} créée : "
         f"[bold]{entity_file.relative_to(project_dir)}[/bold]"
@@ -96,7 +86,13 @@ def add_entity_cmd(*, project_dir: Path | None = None, entity_name: str) -> Path
     return entity_file
 
 
-def add_usecase_cmd(*, project_dir: Path | None = None, usecase_name: str) -> Path:
+def add_usecase_cmd(
+    *,
+    project_dir: Path | None = None,
+    usecase_name: str,
+    entity_name: str | None = None,
+    new_entity_name: str | None = None,
+) -> Path:
     project_dir = project_dir or Path.cwd()
     usecase_name = usecase_name.strip()
     _assert_project_root(project_dir, command="add-usecase")
@@ -108,17 +104,43 @@ def add_usecase_cmd(*, project_dir: Path | None = None, usecase_name: str) -> Pa
     inbound_port_file = paths.inbound_ports / f"{names.snake}.py"
     _assert_missing(usecase_file, project_dir)
     _assert_missing(inbound_port_file, project_dir)
+    entity = _resolve_usecase_entity(
+        project_dir=project_dir,
+        paths=paths,
+        entity_name=entity_name,
+        new_entity_name=new_entity_name,
+    )
 
     _ensure_package_dirs(paths, "domain", "ports", "inbound")
     _ensure_package_dirs(paths, "application", "use_cases")
-    inbound_port_file.write_text(_INBOUND_PORT_TEMPLATE.format(class_name=names.pascal), encoding="utf-8")
-    usecase_file.write_text(
-        _USE_CASE_TEMPLATE.format(
+    inbound_port_module = paths.import_path("domain", "ports", "inbound", names.snake)
+    if entity is None:
+        inbound_port_content = render_transverse_inbound_port_template(
+            class_name=names.pascal
+        )
+        usecase_content = render_transverse_use_case_template(
             class_name=names.pascal,
-            inbound_port_module=paths.import_path("domain", "ports", "inbound", names.snake),
-        ),
-        encoding="utf-8",
-    )
+            inbound_port_module=inbound_port_module,
+        )
+    else:
+        entity_module = paths.import_path(
+            "domain",
+            "models",
+            entity.file_path.stem,
+        )
+        inbound_port_content = render_entity_inbound_port_template(
+            class_name=names.pascal,
+            entity_class=entity.pascal,
+            entity_module=entity_module,
+        )
+        usecase_content = render_entity_use_case_template(
+            class_name=names.pascal,
+            entity_class=entity.pascal,
+            entity_module=entity_module,
+            inbound_port_module=inbound_port_module,
+        )
+    inbound_port_file.write_text(inbound_port_content, encoding="utf-8")
+    usecase_file.write_text(usecase_content, encoding="utf-8")
     console.print(
         f"[green]✓[/green] Port inbound {names.pascal}Port créé : "
         f"[bold]{inbound_port_file.relative_to(project_dir)}[/bold]"
@@ -127,10 +149,93 @@ def add_usecase_cmd(*, project_dir: Path | None = None, usecase_name: str) -> Pa
         f"[green]✓[/green] Cas d'usage {names.pascal}UseCase créé : "
         f"[bold]{usecase_file.relative_to(project_dir)}[/bold]"
     )
+    if entity is not None:
+        console.print(
+            f"[green]✓[/green] Entité principale : [bold]{entity.pascal}[/bold]"
+        )
     return usecase_file
 
 
-def add_intent_interpreter_cmd(*, project_dir: Path | None = None, intent_name: str) -> Path:
+def _resolve_usecase_entity(
+    *,
+    project_dir: Path,
+    paths: ProjectPaths,
+    entity_name: str | None,
+    new_entity_name: str | None,
+) -> EntityInfo | None:
+    if entity_name is not None and new_entity_name is not None:
+        console.print(
+            "[red]✗[/red] Une seule entité peut être choisie : "
+            "utilisez [bold]entity_name[/bold] ou [bold]new_entity_name[/bold]."
+        )
+        raise typer.Exit(1)
+    if entity_name is not None:
+        return _require_existing_entity(project_dir, entity_name)
+    if new_entity_name is None:
+        return None
+
+    raw_name = new_entity_name.strip()
+    _assert_valid_name(raw_name, label="entité")
+    names = EntityNames.from_input(raw_name)
+    existing_entity = _find_entity(project_dir, names.pascal)
+    if existing_entity is not None:
+        return existing_entity
+
+    expected_file = paths.domain_models / f"{names.snake}.py"
+    if expected_file.exists():
+        console.print(
+            f"[red]✗[/red] Le fichier [bold]{expected_file.relative_to(project_dir)}[/bold] "
+            f"existe mais ne déclare pas [bold]class {names.pascal}(Entity)[/bold]."
+        )
+        raise typer.Exit(1)
+
+    add_entity_cmd(project_dir=project_dir, entity_name=raw_name)
+    created_entity = _find_entity(project_dir, names.pascal)
+    if (
+        created_entity is None
+    ):  # pragma: no cover - defensive check after our own template
+        console.print(
+            f"[red]✗[/red] Impossible de détecter l'entité créée {names.pascal}."
+        )
+        raise typer.Exit(1)
+    return created_entity
+
+
+def _require_existing_entity(project_dir: Path, raw_name: str) -> EntityInfo:
+    normalized_name = raw_name.strip()
+    _assert_valid_name(normalized_name, label="entité")
+    names = EntityNames.from_input(normalized_name)
+    entities = scan_entities(project_dir)
+    entity = next(
+        (item for item in entities if item.pascal == names.pascal),
+        None,
+    )
+    if entity is not None:
+        return entity
+
+    detected = ", ".join(item.pascal for item in entities) or "aucune"
+    console.print(
+        f"[red]✗[/red] Entité introuvable : [bold]{names.pascal}[/bold]. "
+        f"Entités détectées : {detected}. Utilisez [bold]--new-entity {names.pascal}[/bold] "
+        "pour la créer."
+    )
+    raise typer.Exit(1)
+
+
+def _find_entity(project_dir: Path, pascal_name: str) -> EntityInfo | None:
+    return next(
+        (
+            entity
+            for entity in scan_entities(project_dir)
+            if entity.pascal == pascal_name
+        ),
+        None,
+    )
+
+
+def add_intent_interpreter_cmd(
+    *, project_dir: Path | None = None, intent_name: str
+) -> Path:
     project_dir = project_dir or Path.cwd()
     intent_name = intent_name.strip()
     _assert_project_root(project_dir, command="add-intent-interpreter")
@@ -142,7 +247,9 @@ def add_intent_interpreter_cmd(*, project_dir: Path | None = None, intent_name:
     _assert_missing(intent_file, project_dir)
 
     _ensure_package_dirs(paths, "application", "intent_interpreters")
-    intent_file.write_text(_INTENT_INTERPRETER_TEMPLATE.format(class_name=names.pascal), encoding="utf-8")
+    intent_file.write_text(
+        _INTENT_INTERPRETER_TEMPLATE.format(class_name=names.pascal), encoding="utf-8"
+    )
     console.print(
         f"[green]✓[/green] Interpréteur d'intention {names.pascal}Interpreter créé : "
         f"[bold]{intent_file.relative_to(project_dir)}[/bold]"
@@ -152,7 +259,9 @@ def add_intent_interpreter_cmd(*, project_dir: Path | None = None, intent_name:
 
 def _assert_project_root(project_dir: Path, *, command: str) -> None:
     if not project_dir.exists() or not project_dir.is_dir():
-        console.print(f"[red]✗[/red] Répertoire introuvable : [bold]{project_dir}[/bold].")
+        console.print(
+            f"[red]✗[/red] Répertoire introuvable : [bold]{project_dir}[/bold]."
+        )
         raise typer.Exit(1)
 
     has_project_marker = (
@@ -185,7 +294,9 @@ def _assert_missing(path: Path, project_dir: Path) -> None:
     if not path.exists():
         return
 
-    console.print(f"[red]✗[/red] Le fichier existe déjà : [bold]{path.relative_to(project_dir)}[/bold].")
+    console.print(
+        f"[red]✗[/red] Le fichier existe déjà : [bold]{path.relative_to(project_dir)}[/bold]."
+    )
     raise typer.Exit(1)
 
 
@@ -193,7 +304,11 @@ def _ensure_package_dirs(paths: ProjectPaths, *relative_parts: str) -> None:
     target_dir = paths.package_root.joinpath(*relative_parts)
     target_dir.mkdir(parents=True, exist_ok=True)
 
-    stop_at = paths.package_root.parent if paths.package_name is not None else paths.package_root
+    stop_at = (
+        paths.package_root.parent
+        if paths.package_name is not None
+        else paths.package_root
+    )
     init_dirs = [target_dir]
     for parent in target_dir.parents:
         if parent == stop_at: