hexastack-cli 0.1.0__tar.gz

hexastack_cli-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: hexastack-cli
+Version: 0.1.0
+Summary: Hexastack CLI presentation adapter with Typer and Rich
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: rich>=13.8.0
+Requires-Dist: typer>=0.27.1
+Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
+Requires-Python: >=3.13
+Provides-Extra: testing
+Description-Content-Type: text/markdown
+
+![hexastack-cli](../../docs/assets/static/logos/packages/hexastack_cli.png)
+
+# hexastack-cli
+
+> Typer and Rich presentation adapter for Hexastack: nested commands, aliases, piped outputs, and CQRS dispatching.
+
+[![PyPI: hexastack-cli](https://img.shields.io/pypi/v/hexastack-cli.svg)](https://pypi.org/project/hexastack-cli/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_cli)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-cli` turns Hexastack CQRS commands and queries into intuitive, modern CLI applications:
+
+- **Nested Command Hierarchies**: Nest subcommands naturally (`app user create`, `app db migrate`) using `@cli_group`.
+- **Command Aliases**: Register multiple aliases for the same action (`app user new == app user create`).
+- **Feature Flag Gating**: Gate CLI commands dynamically with `@feature_flag_command(...)` and `@cli_command(..., feature_flag=...)`.
+- **Rich Formatted & CI-Friendly Output**: Beautiful tables, panels, and spinners for interactive terminals; clean text/JSON streaming for CI/CD pipelines.
+- **Direct CQRS Dispatching**: Declaratively expose domain commands (`@cli_command`) and queries (`@cli_query`) with automatic parameter parsing and validation.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_cli/
+├── domain/          # CliContext, OutputFormat enum
+├── adapters/        # create_cli_app, Rich presenters, Typer command runners
+└── infra/           # CliBootstrapper (order=30), @cli_command, @cli_query, @cli_group, @feature_flag_command
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Application Factory** | `create_cli_app`, `CliBootstrapper` (order=30) |
+| **Decorators** | `@cli_command`, `@cli_query`, `@cli_group`, `@feature_flag_command` |
+| **Presenters** | `RichTerminalPresenter`, `ConsolePresenter`, `TablePresenter`, `JsonPresenter` |
+| **Testing & Demo Narration** | `CliNarrator`, `TerminalEvent` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph UserInvocation ["CLI Invocations"]
+        INV["Terminal Commands & Scripts"]
+    end
+
+    subgraph CliLayer ["hexastack-cli"]
+        TYPER["Typer Application (Nested Groups & Aliases)"]
+        RICH["Rich Presenters (Tables, Panels, JSON)"]
+        SCAN["CLI Decorator Scanner (@cli_command, @cli_query)"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph Kernel ["hexastack-core"]
+        DI["rodi.Container"]
+    end
+
+    INV --> TYPER
+    TYPER --> SCAN
+    SCAN -->|dispatches to| CBUS
+    SCAN -->|dispatches to| QBUS
+    SCAN --> RICH
+
+    TYPER -. resolves buses from DI .-> DI
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Core kernel, DI container, and ports.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `typer>=0.27.1`: CLI command parser and shell completion.
+- `rich>=15.0.0`: Terminal formatting, tables, and colors.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **CQRS Integration**: Dispatches CLI argument payloads directly into the application's command and query buses.
+- **Umbrella CLI**: Consumed by the `hexastack` umbrella package to power diagnostic commands (`hexastack info`, `hexastack inspect registry`, `hexastack demo ping`).
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-cli
+
+# Via umbrella package
+pip install "hexastack[cli]"
+```
+
+---
+
+## 5. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_cli.infra.decorators import cli_query, cli_group
+
+
+@dataclass(frozen=True)
+class CheckStatusQuery(Query):
+    service_name: str
+
+
+@query_handler(CheckStatusQuery)
+class CheckStatusHandler:
+    def __call__(self, qry: CheckStatusQuery) -> dict:
+        return {"service": qry.service_name, "status": "ONLINE"}
+
+
+# Expose query as a CLI command
+cli_query("status", aliases=["st", "health"], help="Check status of a service")(
+    CheckStatusQuery
+)
+
+runtime = bootstrap(packages_to_scan=[__name__])
+cli_app = runtime.get("cli_app")
+```

hexastack_cli-0.1.0/README.md

@@ -0,0 +1,129 @@
+![hexastack-cli](../../docs/assets/static/logos/packages/hexastack_cli.png)
+
+# hexastack-cli
+
+> Typer and Rich presentation adapter for Hexastack: nested commands, aliases, piped outputs, and CQRS dispatching.
+
+[![PyPI: hexastack-cli](https://img.shields.io/pypi/v/hexastack-cli.svg)](https://pypi.org/project/hexastack-cli/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_cli)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-cli` turns Hexastack CQRS commands and queries into intuitive, modern CLI applications:
+
+- **Nested Command Hierarchies**: Nest subcommands naturally (`app user create`, `app db migrate`) using `@cli_group`.
+- **Command Aliases**: Register multiple aliases for the same action (`app user new == app user create`).
+- **Feature Flag Gating**: Gate CLI commands dynamically with `@feature_flag_command(...)` and `@cli_command(..., feature_flag=...)`.
+- **Rich Formatted & CI-Friendly Output**: Beautiful tables, panels, and spinners for interactive terminals; clean text/JSON streaming for CI/CD pipelines.
+- **Direct CQRS Dispatching**: Declaratively expose domain commands (`@cli_command`) and queries (`@cli_query`) with automatic parameter parsing and validation.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_cli/
+├── domain/          # CliContext, OutputFormat enum
+├── adapters/        # create_cli_app, Rich presenters, Typer command runners
+└── infra/           # CliBootstrapper (order=30), @cli_command, @cli_query, @cli_group, @feature_flag_command
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Application Factory** | `create_cli_app`, `CliBootstrapper` (order=30) |
+| **Decorators** | `@cli_command`, `@cli_query`, `@cli_group`, `@feature_flag_command` |
+| **Presenters** | `RichTerminalPresenter`, `ConsolePresenter`, `TablePresenter`, `JsonPresenter` |
+| **Testing & Demo Narration** | `CliNarrator`, `TerminalEvent` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph UserInvocation ["CLI Invocations"]
+        INV["Terminal Commands & Scripts"]
+    end
+
+    subgraph CliLayer ["hexastack-cli"]
+        TYPER["Typer Application (Nested Groups & Aliases)"]
+        RICH["Rich Presenters (Tables, Panels, JSON)"]
+        SCAN["CLI Decorator Scanner (@cli_command, @cli_query)"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph Kernel ["hexastack-core"]
+        DI["rodi.Container"]
+    end
+
+    INV --> TYPER
+    TYPER --> SCAN
+    SCAN -->|dispatches to| CBUS
+    SCAN -->|dispatches to| QBUS
+    SCAN --> RICH
+
+    TYPER -. resolves buses from DI .-> DI
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Core kernel, DI container, and ports.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `typer>=0.27.1`: CLI command parser and shell completion.
+- `rich>=15.0.0`: Terminal formatting, tables, and colors.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **CQRS Integration**: Dispatches CLI argument payloads directly into the application's command and query buses.
+- **Umbrella CLI**: Consumed by the `hexastack` umbrella package to power diagnostic commands (`hexastack info`, `hexastack inspect registry`, `hexastack demo ping`).
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-cli
+
+# Via umbrella package
+pip install "hexastack[cli]"
+```
+
+---
+
+## 5. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_cli.infra.decorators import cli_query, cli_group
+
+
+@dataclass(frozen=True)
+class CheckStatusQuery(Query):
+    service_name: str
+
+
+@query_handler(CheckStatusQuery)
+class CheckStatusHandler:
+    def __call__(self, qry: CheckStatusQuery) -> dict:
+        return {"service": qry.service_name, "status": "ONLINE"}
+
+
+# Expose query as a CLI command
+cli_query("status", aliases=["st", "health"], help="Check status of a service")(
+    CheckStatusQuery
+)
+
+runtime = bootstrap(packages_to_scan=[__name__])
+cli_app = runtime.get("cli_app")
+```

hexastack_cli-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "hexastack-cli"
+version = "0.1.0"
+description = "Hexastack CLI presentation adapter with Typer and Rich"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "rich>=13.8.0",
+    "typer>=0.27.1",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+testing = ["playwright>=1.49.0"]
+
+[project.entry-points."hexastack.bootstrappers"]
+cli = "hexastack_cli.infra.bootstrap:CliBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_cli"]

hexastack_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "hexastack-cli"
+version = "0.1.0"
+description = "Hexastack CLI presentation adapter with Typer and Rich"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "rich>=13.8.0",
+    "typer>=0.27.1",
+]
+
+[project.optional-dependencies]
+testing = [
+    "playwright>=1.49.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+cli = "hexastack_cli.infra.bootstrap:CliBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_cli"]

hexastack_cli-0.1.0/src/hexastack_cli/__init__.py

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

hexastack_cli-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]