hexastack-cli 0.0.0__py3-none-any.whl

hexastack_cli/infra/autodiscovery.py

@@ -0,0 +1,215 @@
+import inspect
+import re
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from hexastack_cli.adapters.routing import (
+    _to_kebab_case,
+    register_cqrs_command,
+    register_cqrs_query,
+)
+from hexastack_cli.infra.decorators import (
+    _CLI_GROUP_ATTR,
+    _CLI_METADATA_ATTR,
+    CliMetadata,
+    GroupMetadata,
+)
+from hexastack_core.domain import Command, Query
+from hexastack_core.infra.autodiscovery import (
+    DiscoveryVisitor,
+    scan_modules,
+)
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+__all__ = [
+    "autodiscover_cli_commands",
+    "create_cli_visitor",
+]
+
+
+class _SubgroupManager:
+    """Manages creation and nested mounting of Typer subgroups."""
+
+    def __init__(self, root_app: typer.Typer) -> None:
+        self.root_app = root_app
+        self.subgroups: dict[tuple[str, ...], typer.Typer] = {}
+        self.group_docs: dict[tuple[str, ...], str] = {}
+
+    def get_or_create(self, group_parts: list[str]) -> typer.Typer:
+        """Get or create nested subgroup Typer application."""
+        if not group_parts:
+            return self.root_app
+
+        current_app = self.root_app
+        current_path: list[str] = []
+        for part in group_parts:
+            current_path.append(part)
+            key = tuple(current_path)
+            if key not in self.subgroups:
+                help_text = self.group_docs.get(
+                    key, f"{part.title()} management commands"
+                )
+                sub_app = typer.Typer(
+                    name=part,
+                    help=help_text,
+                    no_args_is_help=True,
+                )
+
+                @sub_app.callback()
+                def _sub_cb() -> None:
+                    pass
+
+                current_app.add_typer(sub_app, name=part)
+                self.subgroups[key] = sub_app
+            current_app = self.subgroups[key]
+        return current_app
+
+    def register_group_metadata(self, obj: type[Any]) -> None:
+        """Extract and cache group documentation from @cli_group."""
+        grp_meta: GroupMetadata | None = getattr(obj, _CLI_GROUP_ATTR, None)
+        if grp_meta is not None:
+            parts = _normalize_group_path(grp_meta.name)
+            if parts and grp_meta.help:
+                self.group_docs[tuple(parts)] = grp_meta.help
+
+
+def _normalize_group_path(group: str | Sequence[str] | None) -> list[str]:
+    """Normalize a string or sequence into a list of subcommand group tokens."""
+    if not group:
+        return []
+    if isinstance(group, str):
+        return [part.strip() for part in re.split(r"[./\s]+", group) if part.strip()]
+    return [str(part).strip() for part in group if str(part).strip()]
+
+
+def _register_model_target(
+    target_app: typer.Typer,
+    obj: type[Any],
+    meta: CliMetadata,
+    cmd_name: str,
+    help_text: str | None,
+    pipeline: ExecutionPipeline,
+    console: Console | None,
+) -> None:
+    """Register command or query class on the target Typer app."""
+    if meta.kind == "command" and issubclass(obj, Command):
+        register_cqrs_command(
+            app=target_app,
+            command_cls=obj,
+            pipeline=pipeline,
+            name=cmd_name,
+            positional=meta.positional,
+            help_text=help_text,
+            output_format=meta.output_format,
+            console=console,
+            feature_flag=meta.feature_flag,
+        )
+    elif meta.kind == "query" and issubclass(obj, Query):
+        register_cqrs_query(
+            app=target_app,
+            query_cls=obj,
+            pipeline=pipeline,
+            name=cmd_name,
+            positional=meta.positional,
+            help_text=help_text,
+            output_format=meta.output_format,
+            console=console,
+            feature_flag=meta.feature_flag,
+        )
+
+
+def _resolve_targets(
+    meta: CliMetadata, default_name: str
+) -> list[tuple[list[str], str, str | None]]:
+    """Resolve all (group_parts, cmd_name, help) targets including aliases."""
+    primary_group = _normalize_group_path(meta.group)
+    primary_name = meta.name or default_name
+    targets: list[tuple[list[str], str, str | None]] = [
+        (primary_group, primary_name, meta.help)
+    ]
+
+    for alias in meta.aliases:
+        if alias.startswith("/"):
+            targets.append(([], alias.lstrip("/"), meta.help))
+        elif any(sep in alias for sep in (".", "/", " ")):
+            parts = _normalize_group_path(alias)
+            targets.append((parts[:-1], parts[-1], meta.help))
+        else:
+            targets.append((primary_group, alias, meta.help))
+
+    return targets
+
+
+def autodiscover_cli_commands(
+    app: typer.Typer,
+    packages_or_modules: Sequence[str | ModuleType],
+    pipeline: ExecutionPipeline,
+    console: Console | None = None,
+) -> None:
+    """Scan packages and register discovered CLI commands into a Typer application.
+
+    Args:
+        app: Target Typer application instance.
+        packages_or_modules: Sequence of package names or module objects to inspect.
+        pipeline: Target ExecutionPipeline instance.
+        console: Optional rich Console instance.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    visitor = create_cli_visitor(app=app, pipeline=pipeline, console=console)
+    scan_modules(packages_or_modules, [visitor])
+
+
+def create_cli_visitor(
+    app: typer.Typer,
+    pipeline: ExecutionPipeline,
+    console: Console | None = None,
+) -> DiscoveryVisitor:
+    """Create a DiscoveryVisitor callback for single-pass CLI command and alias registration.
+
+    Notes/Architectural Intent:
+        Inspects discovered classes for @cli_command, @cli_query, and @cli_group metadata,
+        dynamically building nested Typer subcommand trees and mounting intra-group
+        and cross-group command aliases.
+
+    Args:
+        app: Target Typer root application instance.
+        pipeline: ExecutionPipeline instance for command and query dispatching.
+        console: Optional rich Console instance.
+
+    Returns:
+        DiscoveryVisitor callable accepting (member, module).
+
+    Raises:
+        None.
+    """
+    manager = _SubgroupManager(root_app=app)
+
+    def visitor(obj: Any, module: ModuleType) -> None:
+        if not inspect.isclass(obj):
+            return
+
+        manager.register_group_metadata(obj)
+
+        meta: CliMetadata | None = getattr(obj, _CLI_METADATA_ATTR, None)
+        if meta is None:
+            return
+
+        default_name = _to_kebab_case(obj.__name__)
+        targets = _resolve_targets(meta, default_name)
+
+        for group_parts, cmd_name, help_text in targets:
+            target_app = manager.get_or_create(group_parts)
+            _register_model_target(
+                target_app, obj, meta, cmd_name, help_text, pipeline, console
+            )
+
+    return visitor

hexastack_cli/infra/bootstrap.py

@@ -0,0 +1,80 @@
+import typer
+
+from hexastack_cli.infra.config import (
+    HexastackCliConfig,
+    register_cli_config,
+)
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+
+class CliBootstrapper(BootstrapperPort):
+    """Bootstrap extension configuring Hexastack Typer CLI presentation layer.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort for hexastack-cli (order=40), registering 'cli'
+        configuration in Phase 1, creating the Typer application in Phase 2, and registering
+        the single-pass CLI discovery visitor.
+    """
+
+    name: str = "cli"
+    order: int = 40
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Instantiate Typer app, configure presenters, and register discovery visitor.
+
+        Args:
+            context: BootstrapContext containing DI container, configuration, and properties.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        from hexastack_cli.adapters.app import create_cli_app
+        from hexastack_cli.infra.autodiscovery import create_cli_visitor
+
+        cfg = HexastackCliConfig()
+        if context.config is not None:
+            section = context.config.get_section("cli", HexastackCliConfig)
+            if section is not None:
+                cfg = section
+
+        pipeline = context.properties.get("pipeline")
+        if pipeline is None and ExecutionPipeline in context.container:
+            pipeline = context.container.resolve(ExecutionPipeline)
+
+        app = create_cli_app(
+            config=cfg,
+            container=context.container,
+            pipeline=pipeline,
+        )
+
+        if cfg.auto_register_commands and pipeline is not None:
+            visitor = create_cli_visitor(app=app, pipeline=pipeline)
+            context.register_visitor(visitor)
+
+        context.container.add_instance(app, declared_class=typer.Typer)
+        context.properties["cli_app"] = app
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register CLI configuration schema under 'cli'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        register_cli_config(registry)
+
+
+__all__ = [
+    "CliBootstrapper",
+]

hexastack_cli/infra/config.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+@config_section("cli")
+class HexastackCliConfig(BaseModel):
+    """Configuration schema for Hexastack CLI presentation adapter.
+
+    Notes/Architectural Intent:
+        Controls CLI application naming, versioning, Typer rich formatting, error traceback display,
+        and automatic command discovery.
+    """
+
+    app_name: str = Field(default="hexastack")
+    version: str = Field(default="0.1.0")
+    help_text: str = Field(default="Hexastack CLI Application")
+    auto_register_commands: bool = Field(default=True)
+    rich_markup: bool = Field(default=True)
+    show_exceptions: bool = Field(default=False)
+    packages_to_scan: list[str] = Field(default_factory=list)
+
+
+__all__ = [
+    "HexastackCliConfig",
+    "register_cli_config",
+]
+
+
+def register_cli_config(registry: ConfigRegistry) -> None:
+    """Register CLI configuration schema with a ConfigRegistry under 'cli'.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    registry.register_config_section("cli", HexastackCliConfig)

hexastack_cli/infra/decorators.py

@@ -0,0 +1,219 @@
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from hexastack_core.domain import Command, Query
+
+_CLI_METADATA_ATTR = "__hexastack_cli__"
+_CLI_GROUP_ATTR = "__hexastack_cli_group__"
+
+
+@dataclass(frozen=True)
+class CliMetadata:
+    """Metadata describing a CLI command binding for a Command or Query.
+
+    Notes/Architectural Intent:
+        Carries CLI command naming, positional parameter mappings, aliases, help descriptions,
+        optional sub-command group identifications, and feature flag gating for automated terminal routing.
+    """
+
+    kind: Literal["command", "query"]
+    name: str | None = None
+    positional: tuple[str, ...] = field(default_factory=tuple)
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+    help: str | None = None
+    output_format: str | None = None
+    group: str | Sequence[str] | None = None
+    feature_flag: str | None = None
+
+
+@dataclass(frozen=True)
+class GroupMetadata:
+    """Metadata configuring a custom CLI subcommand group title and description.
+
+    Notes/Architectural Intent:
+        Allows domain modules or namespaces to define rich descriptions for CLI command groups.
+    """
+
+    name: str
+    help: str | None = None
+
+
+__all__ = [
+    "cli_command",
+    "cli_group",
+    "cli_query",
+    "CliMetadata",
+    "feature_flag_command",
+    "GroupMetadata",
+]
+
+
+def _normalize_tokens(tokens: Sequence[str] | str | None) -> tuple[str, ...]:
+    """Normalize string or sequence of token strings into an immutable tuple."""
+    if not tokens:
+        return ()
+    if isinstance(tokens, str):
+        return (tokens.strip(),)
+    return tuple(str(t).strip() for t in tokens if str(t).strip())
+
+
+def cli_command[TCommand: Command](
+    name: str | None = None,
+    *,
+    positional: Sequence[str] | str | None = None,
+    aliases: Sequence[str] | str | None = None,
+    help: str | None = None,
+    output_format: str | None = None,
+    group: str | Sequence[str] | None = None,
+    feature_flag: str | None = None,
+) -> Callable[[type[TCommand]], type[TCommand]]:
+    """Decorator marking a Command class for automatic CLI command exposure.
+
+    Args:
+        name: Optional custom CLI command name (defaults to kebab-cased class name).
+        positional: Optional field name or list of field names to treat as positional CLI arguments.
+        aliases: Optional alias or list of aliases (can be intra-group like 'create' or cross-group like 'account.new').
+        help: Optional help text for the command.
+        output_format: Optional presenter output format.
+        group: Optional sub-command group name or nested group path (e.g. 'user', 'user.profile').
+        feature_flag: Optional feature flag key required to execute the command.
+
+    Returns:
+        Decorated Command class with attached CLI metadata.
+
+    Raises:
+        None.
+    """
+
+    def decorator(cls: type[TCommand]) -> type[TCommand]:
+        meta = CliMetadata(
+            kind="command",
+            name=name,
+            positional=_normalize_tokens(positional),
+            aliases=_normalize_tokens(aliases),
+            help=help,
+            output_format=output_format,
+            group=group,
+            feature_flag=feature_flag,
+        )
+        setattr(cls, _CLI_METADATA_ATTR, meta)
+        return cls
+
+    return decorator
+
+
+def cli_group(
+    name: str,
+    *,
+    help: str | None = None,
+) -> Callable[[type], type]:
+    """Decorator configuring custom metadata or documentation for a CLI group.
+
+    Args:
+        name: The group name path (e.g. 'user', 'user.profile').
+        help: Help description displayed for the group in terminal --help.
+
+    Returns:
+        Decorator function attaching GroupMetadata.
+
+    Raises:
+        None.
+    """
+
+    def decorator(cls: type) -> type:
+        meta = GroupMetadata(name=name, help=help)
+        setattr(cls, _CLI_GROUP_ATTR, meta)
+        return cls
+
+    return decorator
+
+
+def cli_query[TQuery: Query](
+    name: str | None = None,
+    *,
+    positional: Sequence[str] | str | None = None,
+    aliases: Sequence[str] | str | None = None,
+    help: str | None = None,
+    output_format: str | None = None,
+    group: str | Sequence[str] | None = None,
+    feature_flag: str | None = None,
+) -> Callable[[type[TQuery]], type[TQuery]]:
+    """Decorator marking a Query class for automatic CLI command exposure.
+
+    Args:
+        name: Optional custom CLI command name (defaults to kebab-cased class name).
+        positional: Optional field name or list of field names to treat as positional CLI arguments.
+        aliases: Optional alias or list of aliases (can be intra-group like 'find' or cross-group like 'search.user').
+        help: Optional help text for the command.
+        output_format: Optional presenter output format.
+        group: Optional sub-command group name or nested group path (e.g. 'user', 'user.profile').
+        feature_flag: Optional feature flag key required to execute the command.
+
+    Returns:
+        Decorated Query class with attached CLI metadata.
+
+    Raises:
+        None.
+    """
+
+    def decorator(cls: type[TQuery]) -> type[TQuery]:
+        meta = CliMetadata(
+            kind="query",
+            name=name,
+            positional=_normalize_tokens(positional),
+            aliases=_normalize_tokens(aliases),
+            help=help,
+            output_format=output_format,
+            group=group,
+            feature_flag=feature_flag,
+        )
+        setattr(cls, _CLI_METADATA_ATTR, meta)
+        return cls
+
+    return decorator
+
+
+def feature_flag_command(
+    flag_key: str,
+    *,
+    default: bool = False,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Wrap a Typer command callable with dynamic feature flag evaluation.
+
+    Notes/Architectural Intent:
+        Evaluates the specified feature flag prior to command execution. If disabled,
+        prints a clean error message and exits with a non-zero status code without crashing.
+
+    Args:
+        flag_key: Unique identifier of the feature flag to check.
+        default: Fallback boolean value if flag is not explicitly configured.
+
+    Returns:
+        Decorator wrapping the target callable.
+    """
+    from functools import wraps
+
+    import typer
+
+    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
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(fn)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            flags: FeatureFlagPort = ConfigFeatureFlagAdapter()
+            eval_ctx = EvaluationContext.from_current_context()
+            if not flags.is_enabled(flag_key, default=default, context=eval_ctx):
+                typer.secho(
+                    f"Error: Command is disabled by feature flag '{flag_key}'.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                raise typer.Exit(code=1)
+            return fn(*args, **kwargs)
+
+        return wrapped
+
+    return decorator

hexastack_cli/testing/__init__.py

@@ -0,0 +1,10 @@
+"""Testing and demo narration utilities for Hexastack CLI applications."""
+
+from hexastack_cli.testing.narrator import CliNarrator, TerminalEvent
+from hexastack_cli.testing.terminal import render_cli_demo_video
+
+__all__ = [
+    "CliNarrator",
+    "render_cli_demo_video",
+    "TerminalEvent",
+]