hexastack-cli 0.0.0__py3-none-any.whl

hexastack_cli/__init__.py

@@ -0,0 +1,6 @@
+from hexastack_cli import adapters, infra
+
+__all__ = [
+    "adapters",
+    "infra",
+]

hexastack_cli/adapters/__init__.py

@@ -0,0 +1,13 @@
+from hexastack_cli.adapters.app import create_cli_app
+from hexastack_cli.adapters.presenter import RichTerminalPresenter
+from hexastack_cli.adapters.routing import (
+    register_cqrs_command,
+    register_cqrs_query,
+)
+
+__all__ = [
+    "create_cli_app",
+    "register_cqrs_command",
+    "register_cqrs_query",
+    "RichTerminalPresenter",
+]

hexastack_cli/adapters/app.py

@@ -0,0 +1,77 @@
+import typer
+from rich.console import Console
+from rodi import Container
+
+from hexastack_cli.adapters.presenter import RichTerminalPresenter
+from hexastack_cli.infra.config import HexastackCliConfig
+from hexastack_core.domain import Generic
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+from hexastack_cqrs.infra.registries.presenter import PresenterRegistry
+
+__all__ = [
+    "create_cli_app",
+]
+
+
+def create_cli_app(
+    config: HexastackCliConfig | None = None,
+    container: Container | None = None,
+    pipeline: ExecutionPipeline | None = None,
+    console: Console | None = None,
+) -> typer.Typer:
+    """Factory creating and configuring a Typer CLI application integrated with Hexastack.
+
+    Notes/Architectural Intent:
+        Assembles a Typer CLI instance configured with Rich formatting, binds container
+        and pipeline references, supports top-level --version, ensures multi-command dispatching,
+        and registers terminal presenters into the presenter registry.
+
+    Args:
+        config: Optional HexastackCliConfig instance.
+        container: Optional rodi Container instance.
+        pipeline: Optional ExecutionPipeline instance.
+        console: Optional rich Console instance.
+
+    Returns:
+        Configured Typer application instance.
+
+    Raises:
+        None.
+    """
+    cfg = config or HexastackCliConfig()
+    active_console = console or Console()
+
+    app = typer.Typer(
+        name=cfg.app_name,
+        help=cfg.help_text,
+        rich_markup_mode="rich" if cfg.rich_markup else None,
+        no_args_is_help=True,
+    )
+
+    def _version_callback(value: bool) -> None:
+        if value:
+            active_console.print(f"{cfg.app_name} {cfg.version}")
+            raise typer.Exit()
+
+    # Establish root callback to enforce multi-command structure and handle --version
+    @app.callback()
+    def _main(
+        version: bool | None = typer.Option(
+            None,
+            "--version",
+            "-v",
+            help="Show the application version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ) -> None:
+        pass
+
+    # Register RichTerminalPresenter if presenter registry is present in DI
+    if container is not None and PresenterRegistry in container:
+        pres_reg = container.resolve(PresenterRegistry)
+        terminal_presenter = RichTerminalPresenter(console=active_console)
+        pres_reg.register(Generic, "rich", terminal_presenter)
+        container.add_instance(terminal_presenter, declared_class=RichTerminalPresenter)
+
+    return app

hexastack_cli/adapters/presenter.py

@@ -0,0 +1,137 @@
+import json
+import os
+import sys
+from typing import Any
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from hexastack_core.domain import Generic
+from hexastack_core.ports.presenter import PresenterPort
+
+
+class RichTerminalPresenter(PresenterPort):
+    """Terminal presenter formatting domain models into stylized Rich panels, JSON, or plain text.
+
+    Notes/Architectural Intent:
+        Implements Presenter port for terminal and CI/pipe environments.
+        Supports structured JSON, plain line-oriented text, and interactive Rich tables.
+        Automatically respects NO_COLOR and non-TTY stdout streams.
+    """
+
+    def __init__(
+        self,
+        console: Console | None = None,
+        stderr_console: Console | None = None,
+    ) -> None:
+        """Initialize RichTerminalPresenter with optional stdout and stderr Console instances.
+
+        Args:
+            console: Optional rich.console.Console instance for stdout.
+            stderr_console: Optional rich.console.Console instance for stderr.
+        """
+        no_color = bool(os.environ.get("NO_COLOR"))
+        self._console = console or Console(no_color=no_color, highlight=not no_color)
+        self._stderr = stderr_console or Console(
+            stderr=True, no_color=no_color, highlight=not no_color
+        )
+
+    def _present_json(self, data: Any) -> Any:
+        """Render raw, pipe-friendly JSON to stdout."""
+        json_str = json.dumps(data, indent=2, default=str)
+        sys.stdout.write(json_str + "\n")
+        sys.stdout.flush()
+        return data
+
+    def _present_plain(self, data: Any) -> Any:
+        """Render TSV/newline-delimited text to stdout for Unix pipeline processing."""
+        if isinstance(data, dict):
+            for k, v in data.items():
+                sys.stdout.write(f"{k}\t{v}\n")
+        elif isinstance(data, list):
+            for item in data:
+                sys.stdout.write(f"{item}\n")
+        else:
+            sys.stdout.write(f"{data}\n")
+        sys.stdout.flush()
+        return data
+
+    def _present_table(self, instance: Generic, data: Any) -> Any:
+        """Render colorized Rich table/panel to stdout."""
+        if isinstance(data, dict):
+            table = Table(show_header=True, header_style="bold magenta")
+            table.add_column("Field", style="cyan")
+            table.add_column("Value", style="green")
+            for k, v in data.items():
+                val_str = (
+                    json.dumps(v, indent=2) if isinstance(v, dict | list) else str(v)
+                )
+                table.add_row(str(k), val_str)
+            self._console.print(
+                Panel(table, title=type(instance).__name__, border_style="blue")
+            )
+        elif isinstance(data, list):
+            for item in data:
+                self._console.print(f"[cyan]•[/cyan] {item}")
+        else:
+            self._console.print(f"[bold green]{data}[/bold green]")
+        return data
+
+    def present(
+        self,
+        instance: Generic,
+        format_mode: str | None = None,
+    ) -> Any:
+        """Format and print a domain Generic instance to stdout based on requested format mode.
+
+        Args:
+            instance: Domain Generic or DTO model instance.
+            format_mode: Optional format mode ('table', 'json', 'plain').
+
+        Returns:
+            The presented raw data representation.
+
+        Raises:
+            None.
+        """
+        data = instance.model_dump() if isinstance(instance, BaseModel) else instance
+
+        mode = (format_mode or "table").lower()
+
+        if mode == "json":
+            return self._present_json(data)
+        if mode == "plain":
+            return self._present_plain(data)
+        return self._present_table(instance, data)
+
+    def print_error(self, message: str) -> None:
+        """Print an error message to stderr.
+
+        Args:
+            message: The error message string.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._stderr.print(f"[bold red]Error:[/bold red] {message}")
+
+    def print_exception(self) -> None:
+        """Print a rich formatted traceback to stderr for debugging.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._stderr.print_exception(show_locals=False)
+
+
+__all__ = [
+    "RichTerminalPresenter",
+]

hexastack_cli/adapters/routing.py

@@ -0,0 +1,396 @@
+import asyncio
+import inspect
+import json
+import re
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any, cast
+
+import typer
+from rich.console import Console
+
+from hexastack_cli.adapters.presenter import RichTerminalPresenter
+from hexastack_core.domain import Command, Generic, Query
+from hexastack_core.utils.context import (
+    UserContext,
+    set_correlation_id,
+    set_user_context,
+)
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+__all__ = [
+    "register_cqrs_command",
+    "register_cqrs_query",
+]
+
+
+def _build_control_parameters(
+    model_cls: type[Command] | type[Query],
+    output_format: str | None,
+) -> list[inspect.Parameter]:
+    """Build universal CLI control options (output format, input payload, tracing flags)."""
+    fields = model_cls.model_fields
+    specs: list[tuple[str, str, Any, Any]] = [
+        (
+            "output",
+            "__output_format__",
+            typer.Option(
+                output_format or "table",
+                "--output",
+                "-o",
+                help="Output format: table, json, or plain (CI/pipe friendly).",
+            ),
+            str,
+        ),
+        (
+            "input",
+            "__input__",
+            typer.Option(
+                None,
+                "--input",
+                "-i",
+                help="Input JSON payload string, file path, or '-' for stdin.",
+            ),
+            str | None,
+        ),
+        (
+            "quiet",
+            "__quiet__",
+            typer.Option(
+                False,
+                "--quiet",
+                "-q",
+                help="Quiet mode: suppress decorative terminal output.",
+            ),
+            bool,
+        ),
+        (
+            "debug",
+            "__debug__",
+            typer.Option(
+                False,
+                "--debug",
+                help="Enable debug mode and render formatted error tracebacks.",
+            ),
+            bool,
+        ),
+        (
+            "correlation_id",
+            "__correlation_id__",
+            typer.Option(
+                None,
+                "--correlation-id",
+                help="Explicit correlation ID for request tracing.",
+            ),
+            str | None,
+        ),
+        (
+            "user_id",
+            "__user_id__",
+            typer.Option(
+                None,
+                "--user-id",
+                help="Authenticated user context identifier.",
+            ),
+            str | None,
+        ),
+        (
+            "tenant_id",
+            "__tenant_id__",
+            typer.Option(
+                None,
+                "--tenant-id",
+                help="Tenant isolation identifier for multi-tenancy.",
+            ),
+            str | None,
+        ),
+    ]
+
+    return [
+        inspect.Parameter(
+            name=param_name,
+            kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=default_val,
+            annotation=ann,
+        )
+        for field_name, param_name, default_val, ann in specs
+        if field_name not in fields
+    ]
+
+
+def _build_dynamic_cli_runner(
+    model_cls: type[Command] | type[Query],
+    pipeline: ExecutionPipeline,
+    positional: Sequence[str] | None = None,
+    output_format: str | None = None,
+    presenter: RichTerminalPresenter | None = None,
+    console: Console | None = None,
+    feature_flag: str | None = None,
+) -> Callable[..., None]:
+    """Dynamically construct a typed function whose signature matches model_cls fields and CLI flags for Typer."""
+    active_presenter = presenter or RichTerminalPresenter(console=console)
+    active_console = console or Console()
+    pos_set = set(positional or ())
+
+    def runner(**kwargs: Any) -> None:
+        requested_output = kwargs.pop("__output_format__", output_format)
+        quiet_mode = kwargs.pop("__quiet__", False)
+        debug_mode = kwargs.pop("__debug__", False)
+        correlation_id = kwargs.pop("__correlation_id__", None)
+        user_id = kwargs.pop("__user_id__", None)
+        tenant_id = kwargs.pop("__tenant_id__", None)
+        input_payload = kwargs.pop("__input__", None)
+
+        _setup_cli_context(correlation_id, user_id, tenant_id)
+
+        if feature_flag:
+            from hexastack_core.adapters.feature_flags.config import (
+                ConfigFeatureFlagAdapter,
+            )
+            from hexastack_core.domain.feature_flags import EvaluationContext
+            from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+            flags: FeatureFlagPort = ConfigFeatureFlagAdapter()
+            eval_ctx = EvaluationContext.from_current_context()
+            if not flags.is_enabled(feature_flag, default=False, context=eval_ctx):
+                active_presenter.print_error(
+                    f"Command is disabled by feature flag '{feature_flag}'."
+                )
+                raise typer.Exit(code=1)
+
+        try:
+            field_data = _resolve_cli_input(input_payload)
+            cli_flags = {k: v for k, v in kwargs.items() if v is not None}
+            result = _execute_cli_model(
+                model_cls, pipeline, field_data, cli_flags, requested_output
+            )
+            _present_cli_result(
+                result, requested_output, quiet_mode, active_presenter, active_console
+            )
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            if debug_mode:
+                active_presenter.print_exception()
+            else:
+                active_presenter.print_error(str(exc))
+            raise typer.Exit(code=1) from exc
+
+    pos_params, opt_params = _build_model_parameters(model_cls, pos_set)
+    control_params = _build_control_parameters(model_cls, output_format)
+
+    all_params = pos_params + opt_params + control_params
+    sig = inspect.Signature(parameters=all_params)
+    cast("Any", runner).__signature__ = sig
+    return runner
+
+
+def _build_model_parameters(
+    model_cls: type[Command] | type[Query],
+    pos_set: set[str],
+) -> tuple[list[inspect.Parameter], list[inspect.Parameter]]:
+    """Build positional and keyword parameters matching model_cls fields."""
+    pos_params: list[inspect.Parameter] = []
+    opt_params: list[inspect.Parameter] = []
+
+    for field_name, field_info in model_cls.model_fields.items():
+        annotation = field_info.annotation or str
+        is_pos = field_name in pos_set
+        default = (
+            typer.Argument(None, help=field_info.description)
+            if is_pos
+            else typer.Option(None, help=field_info.description)
+        )
+        param = inspect.Parameter(
+            name=field_name,
+            kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=default,
+            annotation=annotation,
+        )
+        if is_pos:
+            pos_params.append(param)
+        else:
+            opt_params.append(param)
+
+    return pos_params, opt_params
+
+
+def _execute_cli_model(
+    model_cls: type[Command] | type[Query],
+    pipeline: ExecutionPipeline,
+    field_data: dict[str, Any],
+    cli_flags: dict[str, Any],
+    requested_output: str | None,
+) -> Any:
+    """Instantiate and execute CQRS command/query through the pipeline."""
+    payload = dict(field_data)
+    payload.update(cli_flags)
+    instance = model_cls(**payload)
+    result = pipeline.execute(instance, output_format=requested_output)
+    if inspect.iscoroutine(result):
+        result = asyncio.run(result)
+    return result
+
+
+def _present_cli_result(
+    result: Any,
+    requested_output: str | None,
+    quiet_mode: bool,
+    active_presenter: RichTerminalPresenter,
+    active_console: Console,
+) -> None:
+    """Format and write CLI execution results to stdout or terminal presenter."""
+    if result is None:
+        return
+    if isinstance(result, Generic):
+        active_presenter.present(result, format_mode=requested_output)
+    elif not quiet_mode or requested_output in {"json", "plain"}:
+        if requested_output == "json":
+            sys.stdout.write(json.dumps(result, indent=2, default=str) + "\n")
+            sys.stdout.flush()
+        elif requested_output == "plain":
+            sys.stdout.write(f"{result}\n")
+            sys.stdout.flush()
+        elif not quiet_mode:
+            active_console.print(f"[bold green]{result}[/bold green]")
+
+
+def _resolve_cli_input(input_payload: str | None) -> dict[str, Any]:
+    """Parse raw JSON string, file content, or stdin input into a dictionary."""
+    if not input_payload:
+        return {}
+    if input_payload == "-":
+        raw_json = sys.stdin.read()
+    elif Path(input_payload).is_file():
+        with Path(input_payload).open(encoding="utf-8") as f:
+            raw_json = f.read()
+    else:
+        raw_json = input_payload
+    payload_dict = json.loads(raw_json)
+    return payload_dict if isinstance(payload_dict, dict) else {}
+
+
+def _setup_cli_context(
+    correlation_id: str | None,
+    user_id: str | None,
+    tenant_id: str | None,
+) -> None:
+    """Initialize correlation and user context for CLI command execution."""
+    if correlation_id:
+        set_correlation_id(correlation_id)
+    if user_id or tenant_id:
+        set_user_context(
+            UserContext(user_id=user_id or "cli-user", tenant_id=tenant_id)
+        )
+
+
+def _to_kebab_case(name: str) -> str:
+    """Convert PascalCase class name to kebab-case CLI command name."""
+    s = re.sub(r"(.)([A-Z][a-z]+)", r"\1-\2", name)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", s)
+    kebab = s.lower()
+    for suffix in ("-command", "-query", "-cmd", "-qry"):
+        while kebab.endswith(suffix) and len(kebab) > len(suffix):
+            kebab = kebab[: -len(suffix)]
+    return kebab
+
+
+def register_cqrs_command(
+    app: typer.Typer,
+    command_cls: type[Command],
+    pipeline: ExecutionPipeline,
+    name: str | None = None,
+    positional: Sequence[str] | None = None,
+    help_text: str | None = None,
+    output_format: str | None = None,
+    presenter: RichTerminalPresenter | None = None,
+    console: Console | None = None,
+    feature_flag: str | None = None,
+) -> None:
+    """Register a CQRS Command model as a typed CLI sub-command on a Typer application.
+
+    Notes/Architectural Intent:
+        Reflects over Pydantic Command model fields to build dynamic CLI options and arguments,
+        injecting CI-friendly flags (--output, --input, --quiet, --debug, --correlation-id, --user-id, --tenant-id).
+
+    Args:
+        app: Target Typer application instance.
+        command_cls: Pydantic Command model class.
+        pipeline: ExecutionPipeline for dispatching commands.
+        name: Optional custom command name (defaults to kebab-case class name).
+        positional: Optional sequence of field names to map as positional CLI arguments.
+        help_text: Optional command description help string.
+        output_format: Optional presenter format.
+        presenter: Optional RichTerminalPresenter instance.
+        console: Optional rich Console instance.
+        feature_flag: Optional feature flag key required for execution.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    cmd_name = name or _to_kebab_case(command_cls.__name__)
+    doc = help_text or (command_cls.__doc__ or f"Execute {command_cls.__name__}")
+    runner = _build_dynamic_cli_runner(
+        command_cls,
+        pipeline,
+        positional=positional,
+        output_format=output_format,
+        presenter=presenter,
+        console=console,
+        feature_flag=feature_flag,
+    )
+    app.command(name=cmd_name, help=doc)(runner)
+
+
+def register_cqrs_query(
+    app: typer.Typer,
+    query_cls: type[Query],
+    pipeline: ExecutionPipeline,
+    name: str | None = None,
+    positional: Sequence[str] | None = None,
+    help_text: str | None = None,
+    output_format: str | None = None,
+    presenter: RichTerminalPresenter | None = None,
+    console: Console | None = None,
+    feature_flag: str | None = None,
+) -> None:
+    """Register a CQRS Query model as a typed CLI sub-command on a Typer application.
+
+    Notes/Architectural Intent:
+        Reflects over Pydantic Query model fields to build dynamic CLI options and arguments,
+        injecting CI-friendly flags (--output, --input, --quiet, --debug, --correlation-id, --user-id, --tenant-id).
+
+    Args:
+        app: Target Typer application instance.
+        query_cls: Pydantic Query model class.
+        pipeline: ExecutionPipeline for dispatching queries.
+        name: Optional custom query command name (defaults to kebab-case class name).
+        positional: Optional sequence of field names to map as positional CLI arguments.
+        help_text: Optional query description help string.
+        output_format: Optional presenter format.
+        presenter: Optional RichTerminalPresenter instance.
+        console: Optional rich Console instance.
+        feature_flag: Optional feature flag key required for execution.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    qry_name = name or _to_kebab_case(query_cls.__name__)
+    doc = help_text or (query_cls.__doc__ or f"Execute {query_cls.__name__}")
+    runner = _build_dynamic_cli_runner(
+        query_cls,
+        pipeline,
+        positional=positional,
+        output_format=output_format,
+        presenter=presenter,
+        console=console,
+        feature_flag=feature_flag,
+    )
+    app.command(name=qry_name, help=doc)(runner)

hexastack_cli/infra/__init__.py

@@ -0,0 +1,29 @@
+from hexastack_cli.infra.autodiscovery import (
+    autodiscover_cli_commands,
+    create_cli_visitor,
+)
+from hexastack_cli.infra.bootstrap import CliBootstrapper
+from hexastack_cli.infra.config import (
+    HexastackCliConfig,
+    register_cli_config,
+)
+from hexastack_cli.infra.decorators import (
+    CliMetadata,
+    GroupMetadata,
+    cli_command,
+    cli_group,
+    cli_query,
+)
+
+__all__ = [
+    "autodiscover_cli_commands",
+    "cli_command",
+    "cli_group",
+    "cli_query",
+    "CliBootstrapper",
+    "CliMetadata",
+    "create_cli_visitor",
+    "GroupMetadata",
+    "HexastackCliConfig",
+    "register_cli_config",
+]