hexastack-cli

Typer and Rich presentation adapter for Hexastack: nested commands, aliases, piped outputs, and CQRS dispatching.

Part of the Hexastack Framework · Governed by Hexaqual.

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).
• Typo Tolerance & Suggestions (TyperSuggest): Drop-in replacement for typer.Typer that intercepts unrecognized subcommands or flags, computes closest matches via Levenshtein distance, prompts interactively for confirmation, and exits cleanly in CI/non-interactive pipelines.
• 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.
• Automated Demo Narration & Slicing (CliNarrator): Headless terminal recording generating asciinema streams, high-resolution .webm videos, chapterized .checkpoint_segment() flushes, and synchronized .vtt subtitles.

2. Package Anatomy & Key Components

hexastack_cli/
├── domain/          # CliContext, OutputFormat enum
├── adapters/        # Rich presenters, Typer command runners, TyperSuggest
├── testing/         # CliNarrator, TerminalEvent (demo video & VTT recorder)
└── infra/           # create_cli_app, CliBootstrapper (order=40), @cli_command, @cli_query, @cli_group, @feature_flag_command

Key Exports

3. Monorepo & Sibling Relationships

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

# Standalone install
pip install hexastack-cli

# Via umbrella package
pip install "hexastack[cli]"

5. Quickstart Example

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")

6. Standalone Typo-Tolerant CLI (TyperSuggest)

TyperSuggest is a drop-in replacement for typer.Typer. It intercepts mistyped commands and options, presenting suggestions and interactive confirmations without throwing cryptic syntax errors:

from hexastack_cli.adapters import TyperSuggest

app = TyperSuggest(help="My Resilient Service CLI")


@app.command()
def deploy(environment: str = "staging", force: bool = False):
    print(f"Deploying to {environment} (force={force})")


if __name__ == "__main__":
    app()

$ python cli.py deply
Unrecognized command 'deply'. Did you mean 'deploy'? [y/N]: y
Deploying to staging (force=False)

$ python cli.py deploy --frc
Unrecognized option '--frc'. Did you mean '--force'? [y/N]: y
Deploying to staging (force=True)

In automated CI environments or redirected streams (not sys.stdin.isatty()), TyperSuggest prints the suggested correction to stderr and exits cleanly with error code 2 without hanging.

7. Automated Demo Recording & Video Slicing (CliNarrator)

from hexastack_cli.testing import CliNarrator

narrator = CliNarrator(record_video=True)
narrator.say("Scaffolding microservice...")
narrator.run("hexastack new web-api billing-service")

# Flush Chapter 1 video & VTT segment
narrator.checkpoint_segment("ch01-scaffolding")

narrator.say("Applying SQLite database migrations...")
narrator.run("hexastack db migrate")

# Flush Chapter 2 video & VTT segment
narrator.checkpoint_segment("ch02-migrations")