merge: testing → main (reconcile 2-week divergence)

decnet/cli/realism.py

@@ -0,0 +1,111 @@
+"""``decnet realism ...`` — content-engine maintenance commands.
+
+After stage 5 of the realism migration, this is the only remaining
+CLI surface from the realism library / former emailgen.  ``decnet
+realism run`` does not exist (the orchestrator runs the unified
+worker via ``decnet orchestrate``); the only sub-command is
+``import-personas``, which validates + installs the host-wide global
+persona pool consumed by fleet (MACVLAN/IPVLAN) and SWARM-shard
+deckies.
+
+Topology personas live on ``Topology.email_personas`` and are
+managed via the dashboard or the topology API; this command does
+not touch them.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from .gating import _require_master_mode
+from .utils import console, log
+
+
+def register(app: typer.Typer) -> None:
+    realism_app = typer.Typer(
+        name="realism",
+        help=(
+            "Maintain the realism content engine (persona pool import, "
+            "future content-class tuning)."
+        ),
+    )
+    app.add_typer(realism_app, name="realism")
+
+    @realism_app.command("import-personas")
+    def realism_import_personas(
+        path: Path = typer.Argument(
+            ..., exists=True, file_okay=True, dir_okay=False, readable=True,
+            help="JSON file containing a list of EmailPersona objects",
+        ),
+        output: Optional[Path] = typer.Option(
+            None, "--output", "-o",
+            help=(
+                "Override the destination path.  Defaults to the canonical "
+                "global pool (DECNET_REALISM_PERSONAS, /etc/decnet/"
+                "email_personas.json, or ~/.decnet/email_personas.json)."
+            ),
+        ),
+    ) -> None:
+        """Validate + install a personas JSON file as the global pool.
+
+        Use this when deploying with IMAP/POP3 services on fleet
+        (MACVLAN/IPVLAN) or SWARM-shard mail deckies — those have no
+        parent topology row, so they read this host-wide list.
+        MazeNET topology mail deckies use ``Topology.email_personas``
+        instead and this command does not touch them.
+        """
+        _require_master_mode("realism import-personas")
+        from decnet.realism import personas_pool as global_pool
+        from decnet.realism.personas import parse_personas
+
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            console.print(f"[red]Cannot read {path}:[/] {exc}")
+            raise typer.Exit(code=1) from exc
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            console.print(f"[red]Invalid JSON in {path}:[/] {exc}")
+            raise typer.Exit(code=1) from exc
+        if not isinstance(payload, list):
+            console.print(
+                f"[red]{path} must contain a JSON list of personas, "
+                f"got {type(payload).__name__}[/]"
+            )
+            raise typer.Exit(code=1)
+
+        personas = parse_personas(payload)
+        if not personas:
+            console.print(
+                f"[red]No valid personas in {path}.[/] "
+                "Check the schema (name, email, role, tone, mannerisms)."
+            )
+            raise typer.Exit(code=1)
+        if len(personas) < 2:
+            console.print(
+                f"[yellow]Warning: only {len(personas)} valid persona(s) — "
+                "the worker requires at least 2 to send mail; importing "
+                "anyway in case more are added later.[/]"
+            )
+
+        dest = output or global_pool.resolve_path()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(
+            json.dumps(
+                [p.model_dump(exclude_none=False) for p in personas],
+                indent=2,
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+        global_pool.reset_cache()
+        console.print(
+            f"[green]Imported {len(personas)} personas to[/] {dest}"
+        )
+        if path != dest:
+            log.info("realism import-personas src=%s dest=%s", path, dest)