hexastack-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{hexastack_cli-0.8.0 → hexastack_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexastack-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: Hexastack CLI presentation adapter with Typer and Rich
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -37,9 +37,11 @@ Description-Content-Type: text/markdown
 
 - **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.
 
 ---
 
@@ -48,7 +50,8 @@ Description-Content-Type: text/markdown
 ```
 hexastack_cli/
 ├── domain/          # CliContext, OutputFormat enum
-├── adapters/        # Rich presenters, Typer command runners
+├── 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
 ```
 
@@ -56,7 +59,7 @@ hexastack_cli/
 
 | Category | Exports |
 |---|---|
-| **Application Factory** | `create_cli_app`, `CliBootstrapper` (order=30) |
+| **Application Factory & Typo Tolerance** | `create_cli_app`, `TyperSuggest`, `SuggestGroup`, `SuggestCommand`, `CliBootstrapper` (order=40) |
 | **Decorators** | `@cli_command`, `@cli_query`, `@cli_group`, `@feature_flag_command` |
 | **Presenters** | `RichTerminalPresenter`, `ConsolePresenter`, `TablePresenter`, `JsonPresenter` |
 | **Testing & Demo Narration** | `CliNarrator`, `TerminalEvent` |
@@ -148,3 +151,57 @@ cli_query("status", aliases=["st", "health"], help="Check status of a service")(
 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:
+
+```python
+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()
+```
+
+```bash
+$ 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`)
+
+```python
+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")
+```

{hexastack_cli-0.8.0 → hexastack_cli-0.9.0}/README.md

@@ -20,9 +20,11 @@
 
 - **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.
 
 ---
 
@@ -31,7 +33,8 @@
 ```
 hexastack_cli/
 ├── domain/          # CliContext, OutputFormat enum
-├── adapters/        # Rich presenters, Typer command runners
+├── 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
 ```
 
@@ -39,7 +42,7 @@ hexastack_cli/
 
 | Category | Exports |
 |---|---|
-| **Application Factory** | `create_cli_app`, `CliBootstrapper` (order=30) |
+| **Application Factory & Typo Tolerance** | `create_cli_app`, `TyperSuggest`, `SuggestGroup`, `SuggestCommand`, `CliBootstrapper` (order=40) |
 | **Decorators** | `@cli_command`, `@cli_query`, `@cli_group`, `@feature_flag_command` |
 | **Presenters** | `RichTerminalPresenter`, `ConsolePresenter`, `TablePresenter`, `JsonPresenter` |
 | **Testing & Demo Narration** | `CliNarrator`, `TerminalEvent` |
@@ -131,3 +134,57 @@ cli_query("status", aliases=["st", "health"], help="Check status of a service")(
 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:
+
+```python
+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()
+```
+
+```bash
+$ 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`)
+
+```python
+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")
+```

{hexastack_cli-0.8.0 → hexastack_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "Hexastack CLI presentation adapter with Typer and Rich"
 readme = "README.md"
 license = "Apache-2.0"

{hexastack_cli-0.8.0 → hexastack_cli-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "Hexastack CLI presentation adapter with Typer and Rich"
 readme = "README.md"
 license = "Apache-2.0"

hexastack_cli-0.9.0/src/hexastack_cli/adapters/__init__.py

@@ -0,0 +1,25 @@
+from hexastack_cli.adapters.presenter import RichTerminalPresenter
+from hexastack_cli.adapters.routing import (
+    register_cqrs_command,
+    register_cqrs_query,
+)
+from hexastack_cli.adapters.suggest import (
+    SuggestCommand,
+    SuggestGroup,
+    SuggestOptionParser,
+    TyperSuggest,
+    find_closest_match,
+    is_interactive,
+)
+
+__all__ = [
+    "find_closest_match",
+    "is_interactive",
+    "register_cqrs_command",
+    "register_cqrs_query",
+    "RichTerminalPresenter",
+    "SuggestCommand",
+    "SuggestGroup",
+    "SuggestOptionParser",
+    "TyperSuggest",
+]

hexastack_cli-0.9.0/src/hexastack_cli/adapters/suggest.py

@@ -0,0 +1,417 @@
+import difflib
+import os
+import re
+import sys
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+import typer
+import typer.core
+
+if TYPE_CHECKING:
+    from typer._click import exceptions as click_exceptions
+    from typer._click.parser import _OptionParser, _ParsingState
+else:
+    try:
+        import typer._click.exceptions as click_exceptions
+        from typer._click.parser import _OptionParser, _ParsingState
+    except ImportError:
+        import click.exceptions as click_exceptions
+        from click.parser import _OptionParser, _ParsingState
+
+__all__ = [
+    "find_closest_match",
+    "is_interactive",
+    "SuggestCommand",
+    "SuggestGroup",
+    "SuggestOptionParser",
+    "TyperSuggest",
+]
+
+_NUMERIC_ARG_RE = re.compile(r"^-[0-9]+(\.[0-9]+)?$")
+
+
+def is_interactive(ctx: Any | None = None) -> bool:
+    """Determine whether the current execution context is interactive.
+
+    Notes/Architectural Intent:
+        Evaluates environment flags (e.g. HEXASTACK_CLI_INTERACTIVE), context metadata,
+        and TTY status to strictly prevent hanging prompts in non-interactive CI pipelines.
+
+    Args:
+        ctx: Optional Click or Typer execution context.
+
+    Returns:
+        True if running in an interactive TTY session or forced interactively, False otherwise.
+
+    Raises:
+        None.
+    """
+    if os.environ.get("HEXASTACK_CLI_INTERACTIVE", "").lower() in ("1", "true", "yes"):
+        return True
+    if ctx is not None and getattr(ctx, "meta", {}).get("force_interactive"):
+        return True
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def find_closest_match(
+    token: str,
+    candidates: Sequence[str],
+    cutoff: float = 0.6,
+) -> str | None:
+    """Find the closest matching string candidate using difflib sequence matching.
+
+    Notes/Architectural Intent:
+        Performs direct string distance matching, followed by leading-dash stripped
+        normalization to forgivingly reconcile CLI flag and subcommand typos.
+
+    Args:
+        token: Target string token to match.
+        candidates: Sequence of valid candidate strings.
+        cutoff: Minimum similarity ratio required for a match (defaults to 0.6).
+
+    Returns:
+        Closest matching candidate string, or None if no match meets the cutoff.
+
+    Raises:
+        None.
+    """
+    matches = difflib.get_close_matches(token, candidates, n=1, cutoff=cutoff)
+    if matches:
+        return matches[0]
+
+    clean_token = token.lstrip("-")
+    norm_candidates = {c.lstrip("-"): c for c in candidates}
+    norm_matches = difflib.get_close_matches(
+        clean_token, list(norm_candidates.keys()), n=1, cutoff=cutoff
+    )
+    if norm_matches:
+        return norm_candidates[norm_matches[0]]
+
+    return None
+
+
+def _substitute_flag_token(
+    args: Sequence[str],
+    target_opt: str,
+    replacement_opt: str,
+) -> list[str]:
+    """Substitute an unrecognized option flag token with its corrected candidate.
+
+    Notes/Architectural Intent:
+        Preserves parameter assignments using '=' syntax (e.g. '--prt=8080' ->
+        '--port=8080') while substituting exact option tokens.
+
+    Args:
+        args: Sequence of CLI argument tokens.
+        target_opt: Unrecognized option token to replace.
+        replacement_opt: Corrected replacement option token.
+
+    Returns:
+        New list of argument tokens with the target option replaced.
+
+    Raises:
+        None.
+    """
+    updated: list[str] = []
+    prefix = f"{target_opt}="
+    for token in args:
+        if token == target_opt:
+            updated.append(replacement_opt)
+        elif token.startswith(prefix):
+            val = token[len(prefix) :]
+            updated.append(f"{replacement_opt}={val}")
+        else:
+            updated.append(token)
+    return updated
+
+
+def _extract_option_candidates(params: Sequence[Any]) -> list[str]:
+    """Extract all available option flags from a collection of command parameters.
+
+    Notes/Architectural Intent:
+        Aggregates both primary option names and secondary negation flags
+        (e.g. '--verbose' and '--no-verbose') across all command parameters.
+
+    Args:
+        params: Sequence of Click/Typer Parameter instances.
+
+    Returns:
+        List of all registered option flag strings.
+
+    Raises:
+        None.
+    """
+    candidates: list[str] = []
+    for param in params:
+        opts = getattr(param, "opts", [])
+        sec_opts = getattr(param, "secondary_opts", [])
+        candidates.extend(opts)
+        candidates.extend(sec_opts)
+    return candidates
+
+
+class SuggestOptionParser(_OptionParser):
+    """Custom Click option parser providing immunity for negative numbers and '--' delimiter.
+
+    Notes/Architectural Intent:
+        Intercepts option token evaluation to prevent negative numbers (e.g. -42, -0.5)
+        from being erroneously parsed as unrecognized short options, preserving
+        their positional argument semantics. Also ensures bare '--' strictly halts
+        option parsing.
+    """
+
+    def _process_args_for_options(self, state: _ParsingState) -> None:
+        while state.rargs:
+            arg = state.rargs.pop(0)
+            arglen = len(arg)
+            if arg == "--":
+                return
+            if _NUMERIC_ARG_RE.match(arg):
+                if self.allow_interspersed_args:
+                    state.largs.append(arg)
+                else:
+                    state.rargs.insert(0, arg)
+                    return
+            elif arg[:1] in self._opt_prefixes and arglen > 1:
+                self._process_opts(arg, state)
+            elif self.allow_interspersed_args:
+                state.largs.append(arg)
+            else:
+                state.rargs.insert(0, arg)
+                return
+
+
+def _parse_args_with_suggestions(
+    command: Any,
+    ctx: Any,
+    args: list[str],
+    super_parse: Callable[[Any, list[str]], list[str]],
+) -> list[str]:
+    """Parse CLI arguments intercepting unrecognized option errors to offer suggestions.
+
+    Notes/Architectural Intent:
+        Wraps command option parsing to catch NoSuchOption, query closest flag matches,
+        and either prompt interactively for confirmation or emit standard Click code 2
+        errors in non-interactive CI contexts. Preserves args copy against Click in-place mutation.
+
+    Args:
+        command: Command or Group instance providing parameters.
+        ctx: Click/Typer context.
+        args: List of argument strings.
+        super_parse: Bound parse_args method from superclass.
+
+    Returns:
+        Remaining arguments after option parsing.
+
+    Raises:
+        UsageError: When an option typo is encountered in non-interactive mode.
+        Abort: When interactive prompt is declined.
+    """
+    current_args = list(args)
+    while True:
+        args_copy = list(current_args)
+        try:
+            return super_parse(ctx, args_copy)
+        except click_exceptions.NoSuchOption as exc:
+            opt = getattr(exc, "option_name", None)
+            if not opt:
+                raise
+            candidates = _extract_option_candidates(command.get_params(ctx))
+            match = find_closest_match(opt, candidates)
+            if not match:
+                raise
+
+            if is_interactive(ctx):
+                confirmed = typer.confirm(
+                    f"Unrecognized option '{opt}'. Did you mean '{match}'?",
+                    default=False,
+                )
+                if not confirmed:
+                    raise typer.Abort from exc
+                current_args = _substitute_flag_token(current_args, opt, match)
+                continue
+            raise click_exceptions.UsageError(
+                f"No such option: {opt}. Did you mean '{match}'?",
+                ctx=ctx,
+            ) from exc
+
+
+class SuggestCommand(typer.core.TyperCommand):
+    """TyperCommand with automatic typo tolerance for options and negative number immunity.
+
+    Notes/Architectural Intent:
+        Inherits from TyperCommand to provide typo correction for leaf commands
+        and subcommands in TyperSuggest applications.
+    """
+
+    def make_parser(self, ctx: Any) -> SuggestOptionParser:
+        """Create a SuggestOptionParser instance populated with command parameters.
+
+        Args:
+            ctx: Click/Typer context.
+
+        Returns:
+            Configured SuggestOptionParser instance.
+
+        Raises:
+            None.
+        """
+        parser = SuggestOptionParser(ctx)
+        for param in self.get_params(ctx):
+            param.add_to_parser(parser, ctx)
+        return parser
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        """Parse arguments with typo detection and suggestions for options.
+
+        Args:
+            ctx: Click/Typer context.
+            args: Command-line arguments.
+
+        Returns:
+            Remaining positional arguments after option processing.
+
+        Raises:
+            UsageError: When an unrecognized option is encountered in non-interactive mode.
+            Abort: When the user declines the correction prompt in interactive mode.
+        """
+        return _parse_args_with_suggestions(self, ctx, args, super().parse_args)
+
+
+class SuggestGroup(typer.core.TyperGroup):
+    """TyperGroup with automatic typo tolerance for subcommands, options, and negative numbers.
+
+    Notes/Architectural Intent:
+        Overrides resolve_command to intercept unknown subcommands and suggest
+        closest matches, supporting both interactive confirmation prompts and
+        non-interactive CI error reporting. Defaults command_class to SuggestCommand.
+    """
+
+    command_class: type[typer.core.TyperCommand] = SuggestCommand
+
+    def make_parser(self, ctx: Any) -> SuggestOptionParser:
+        """Create a SuggestOptionParser instance populated with group parameters.
+
+        Args:
+            ctx: Click/Typer context.
+
+        Returns:
+            Configured SuggestOptionParser instance.
+
+        Raises:
+            None.
+        """
+        parser = SuggestOptionParser(ctx)
+        for param in self.get_params(ctx):
+            param.add_to_parser(parser, ctx)
+        return parser
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        """Parse arguments with typo detection and suggestions for options.
+
+        Args:
+            ctx: Click/Typer context.
+            args: Command-line arguments.
+
+        Returns:
+            Remaining positional arguments after option processing.
+
+        Raises:
+            UsageError: When an unrecognized option is encountered in non-interactive mode.
+            Abort: When the user declines the correction prompt in interactive mode.
+        """
+        return _parse_args_with_suggestions(self, ctx, args, super().parse_args)
+
+    def resolve_command(
+        self,
+        ctx: Any,
+        args: list[str],
+    ) -> tuple[str | None, Any | None, list[str]]:
+        """Resolve subcommand with typo tolerance and interactive prompting.
+
+        Args:
+            ctx: Click/Typer execution context.
+            args: CLI arguments remaining to be processed.
+
+        Returns:
+            Tuple of (command_name, command_instance, remaining_args).
+
+        Raises:
+            UsageError: When an unrecognized subcommand is encountered in non-interactive mode.
+            Abort: When user declines correction prompt in interactive mode.
+        """
+        if not args:
+            return super().resolve_command(ctx, args)
+        cmd_name = str(args[0])
+        if cmd_name.startswith("-"):
+            return super().resolve_command(ctx, args)
+
+        cmd = self.get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd_name, cmd, args[1:]
+
+        candidates = list(self.commands.keys())
+        match = find_closest_match(cmd_name, candidates)
+        if match:
+            if is_interactive(ctx):
+                confirmed = typer.confirm(
+                    f"Unrecognized command '{cmd_name}'. Did you mean '{match}'?",
+                    default=False,
+                )
+                if confirmed:
+                    return match, self.get_command(ctx, match), args[1:]
+                raise typer.Abort
+            raise click_exceptions.UsageError(
+                f"No such command '{cmd_name}'. Did you mean '{match}'?",
+                ctx=ctx,
+            )
+
+        return super().resolve_command(ctx, args)
+
+
+class TyperSuggest(typer.Typer):
+    """Drop-in replacement for typer.Typer with typo tolerance and suggestion capabilities.
+
+    Notes/Architectural Intent:
+        Defaults group class to SuggestGroup and command class to SuggestCommand,
+        ensuring all subcommands and flags are protected by forgiving string-distance
+        matching, numeric negative argument immunity, and non-interactive CI safety.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize TyperSuggest configuring SuggestGroup as default group class.
+
+        Args:
+            *args: Positional arguments forwarded to typer.Typer.
+            **kwargs: Keyword arguments forwarded to typer.Typer.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        kwargs.setdefault("cls", SuggestGroup)
+        super().__init__(*args, **kwargs)
+
+    def command(self, *args: Any, cls: Any = None, **kwargs: Any) -> Any:
+        """Register a command defaulting cls to SuggestCommand.
+
+        Args:
+            *args: Positional arguments forwarded to typer.Typer.command.
+            cls: Optional command class (defaults to SuggestCommand).
+            **kwargs: Keyword arguments forwarded to typer.Typer.command.
+
+        Returns:
+            Decorator registering the command callback.
+
+        Raises:
+            None.
+        """
+        if cls is None:
+            cls = SuggestCommand
+        return super().command(*args, cls=cls, **kwargs)

{hexastack_cli-0.8.0 → hexastack_cli-0.9.0}/src/hexastack_cli/infra/app.py

@@ -3,6 +3,7 @@ from rich.console import Console
 from rodi import Container
 
 from hexastack_cli.adapters.presenter import RichTerminalPresenter
+from hexastack_cli.adapters.suggest import TyperSuggest
 from hexastack_cli.infra.config import HexastackCliConfig
 from hexastack_core.domain import Generic
 from hexastack_cqrs.infra.pipeline import ExecutionPipeline
@@ -41,7 +42,7 @@ def create_cli_app(
     cfg = config or HexastackCliConfig()
     active_console = console or Console()
 
-    app = typer.Typer(
+    app = TyperSuggest(
         name=cfg.app_name,
         help=cfg.help_text,
         rich_markup_mode="rich" if cfg.rich_markup else None,

hexastack_cli-0.9.0/src/hexastack_cli/testing/narrator.py

@@ -0,0 +1,323 @@
+"""Feature demo narrator and Playwright terminal video recorder for CLI commands."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+
+from typer.testing import CliRunner, Result
+
+from hexastack_cli.testing.events import TerminalEvent
+from hexastack_core.utils.fs import atomic_write_text
+
+
+class CliNarrator:
+    """Orchestrates structured narrative CLI execution, step recording, and video rendering.
+
+    Notes/Architectural Intent:
+        1. In standard CI/unit test mode, runs instantly with zero delay via in-memory CliRunner.
+        2. In demo recording mode (`RECORD_DEMO=1`), captures keystrokes, output tokens, and narrative steps,
+           and directly renders a fixed-window, auto-scrolling .webm video via Playwright.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        output_name: str | None = None,
+        output_dir: Path | None = None,
+        width: int = 100,
+        height: int = 24,
+        bin_name: str | None = None,
+    ) -> None:
+        """Initialize CLI narrator attached to a Typer or Click application.
+
+        Args:
+            app: Target Typer application instance.
+            output_name: Base filename (without extension) for saving recordings.
+            output_dir: Target output directory for generated demo artifacts.
+            width: Terminal column width.
+            height: Terminal row height.
+            bin_name: Display binary name for recorded command lines (defaults to app name or 'hexastack').
+
+        Notes/Architectural Intent:
+            Configurable bin_name allows narrating commands from across the hexa- family of tools
+            (e.g., hexaflow, hexaqual, hq) with accurate terminal prompts in generated demo videos.
+        """
+        self.app = app
+        self.output_name = output_name
+        self.output_dir = output_dir or Path("docs/assets/demos")
+        self.width = width
+        self.height = height
+        app_name = getattr(getattr(app, "info", None), "name", None)
+        self.bin_name = bin_name or app_name or "hexastack"
+        self.record_mode = os.environ.get("RECORD_DEMO") in ("1", "true", "True")
+        self.runner = CliRunner()
+        self.start_time: float = time.time()
+        self.events: list[TerminalEvent] = []
+        self.captions: list[tuple[float, float, str]] = []
+        self._current_step_start: float | None = None
+        self._current_step_text: str | None = None
+        self._segment_count: int = 0
+        self.segments: dict[str, dict[str, Path]] = {}
+
+    def step(self, title: str, *, record: bool = True) -> None:
+        """Mark a new narrative step in the CLI demo recording.
+
+        Args:
+            title: Human-readable narrative explanation shown in subtitle banner.
+            record: Whether to emit the step subtitle and recording marker (defaults to True).
+        """
+        if not record:
+            return
+
+        now = time.time() - self.start_time
+        if self._current_step_start is not None and self._current_step_text is not None:
+            self.captions.append(
+                (self._current_step_start, now, self._current_step_text)
+            )
+
+        self._current_step_start = now
+        self._current_step_text = title
+
+        if self.record_mode:
+            self.events.append(
+                TerminalEvent(event_type="step", payload=title, timestamp=now)
+            )
+
+    def run_command(
+        self,
+        args: list[str],
+        env: dict[str, str] | None = None,
+        input: str | None = None,
+        record: bool = True,
+    ) -> Result:
+        """Execute a CLI command within the active Typer application.
+
+        Args:
+            args: Command-line argument strings.
+            env: Optional environment variables.
+            input: Optional stdin input string.
+            record: Whether to record this command invocation and output (defaults to True).
+
+        Returns:
+            CliRunner Result containing exit code, stdout, and stderr.
+        """
+        cmd_str = f"{self.bin_name} {' '.join(args)}"
+
+        if self.record_mode and record:
+            # 1. Record input command string
+            now = time.time() - self.start_time
+            self.events.append(
+                TerminalEvent(
+                    event_type="input",
+                    payload=f"$ {cmd_str}\n",
+                    timestamp=now,
+                )
+            )
+
+        # Execute command in-memory
+        # If an event loop is running in the active thread, offload execution to a thread pool
+        # to ensure commands invoking asyncio.run() (e.g. Hexaflow simulate/run) succeed without RuntimeError.
+        try:
+            asyncio.get_running_loop()
+            is_loop_running = True
+        except RuntimeError:
+            is_loop_running = False
+
+        if is_loop_running:
+            with ThreadPoolExecutor(max_workers=1) as pool:
+                res = pool.submit(
+                    self.runner.invoke, self.app, args, input=input, env=env
+                ).result()
+        else:
+            res = self.runner.invoke(self.app, args, input=input, env=env)
+
+        if self.record_mode and record:
+            # 2. Record command output text
+            now = time.time() - self.start_time
+            output_text = res.stdout if res.stdout else ""
+            if output_text:
+                self.events.append(
+                    TerminalEvent(
+                        event_type="output",
+                        payload=output_text,
+                        timestamp=now,
+                    )
+                )
+
+        return res
+
+    def checkpoint_segment(self, name: str | None = None) -> dict[str, Path]:
+        """Flush the current recording segment to video and subtitle artifacts.
+
+        Slices recorded terminal events and narration captions since the last checkpoint,
+        renders the segment video (.webm) and WebVTT subtitle track (.vtt), and resets
+        the segment event buffer while preserving the underlying execution state
+        (Typer application context, filesystem, and databases).
+
+        Args:
+            name: Suffix or name for this segment (e.g. 'part1-scaffolding'). If omitted,
+                defaults to 'segment-<N>'.
+
+        Returns:
+            Dictionary containing paths to generated segment artifacts ('webm', 'vtt').
+
+        Notes/Architectural Intent:
+            Enables dogfooding multi-step tutorials (e.g. Hexaflow stages) to produce digestible
+            micro-demo videos per stage without incurring the overhead of running separate,
+            disconnected test harnesses.
+        """
+        self._segment_count += 1
+        if name:
+            segment_name = (
+                f"{self.output_name}-{name}"
+                if self.output_name and not name.startswith(f"{self.output_name}-")
+                else name
+            )
+        else:
+            base = self.output_name or "cli-demo"
+            segment_name = f"{base}-segment-{self._segment_count}"
+
+        if not self.record_mode:
+            self.events = []
+            self.captions = []
+            self.start_time = time.time()
+            self._current_step_start = None
+            self._current_step_text = None
+            return {}
+
+        now = time.time() - self.start_time
+        if self._current_step_start is not None and self._current_step_text is not None:
+            self.captions.append(
+                (self._current_step_start, now, self._current_step_text)
+            )
+
+        out_dir = self.output_dir
+        out_dir.mkdir(parents=True, exist_ok=True)
+        artifacts: dict[str, Path] = {}
+
+        # 1. Normalize segment event timestamps so the segment video begins at 0.0s
+        if self.events:
+            base_ts = self.events[0].timestamp
+            segment_events = [
+                TerminalEvent(
+                    event_type=e.event_type,
+                    payload=e.payload,
+                    timestamp=max(0.0, e.timestamp - base_ts),
+                )
+                for e in self.events
+            ]
+        else:
+            segment_events = []
+
+        # 2. Render segment video and true-timing VTT via Playwright Rich Terminal
+        from hexastack_cli.testing.terminal import render_cli_demo_video
+
+        video_path = out_dir / f"{segment_name}.webm"
+        video_file, vtt_file = render_cli_demo_video(
+            events=segment_events,
+            output_path=video_path,
+            title=f"{self.bin_name} CLI — {segment_name}",
+        )
+        artifacts["webm"] = video_file
+        artifacts["vtt"] = vtt_file
+        self.segments[segment_name] = artifacts
+
+        # 3. Reset segment event buffer and start time for the next segment
+        self.events = []
+        self.captions = []
+        self.start_time = time.time()
+        self._current_step_start = None
+        self._current_step_text = None
+
+        return artifacts
+
+    def finish(self) -> dict[str, Path]:
+        """Finalize the recording and render video and caption artifacts.
+
+        Returns:
+            Dictionary containing paths to generated artifact files (e.g. 'webm', 'vtt').
+        """
+        if not self.record_mode:
+            return {}
+
+        if self.events:
+            if self._segment_count > 0:
+                self.checkpoint_segment("final")
+                all_artifacts: dict[str, Path] = {}
+                for seg_name, arts in self.segments.items():
+                    for k, v in arts.items():
+                        all_artifacts[f"{seg_name}_{k}"] = v
+                if self.segments:
+                    latest_seg = list(self.segments.values())[-1]
+                    all_artifacts.update(latest_seg)
+                return all_artifacts
+
+            now = time.time() - self.start_time
+            if (
+                self._current_step_start is not None
+                and self._current_step_text is not None
+            ):
+                self.captions.append(
+                    (self._current_step_start, now, self._current_step_text)
+                )
+
+            out_dir = self.output_dir
+            out_dir.mkdir(parents=True, exist_ok=True)
+            base_name = self.output_name or "cli-demo"
+            artifacts: dict[str, Path] = {}
+
+            # 1. Export WebVTT (.vtt) synchronized narration subtitles
+            vtt_lines = ["WEBVTT", ""]
+            for idx, (start_s, end_s, text) in enumerate(self.captions, start=1):
+                vtt_lines.append(str(idx))
+                vtt_lines.append(
+                    f"{self._format_vtt_time(start_s)} --> {self._format_vtt_time(end_s)}"
+                )
+                vtt_lines.append(text)
+                vtt_lines.append("")
+
+            vtt_path = out_dir / f"{base_name}.vtt"
+            atomic_write_text(vtt_path, "\n".join(vtt_lines), encoding="utf-8")
+            artifacts["vtt"] = vtt_path
+
+            # 2. Render directly to .webm video via Playwright Rich Terminal
+            from hexastack_cli.testing.terminal import render_cli_demo_video
+
+            video_path = out_dir / f"{base_name}.webm"
+            render_cli_demo_video(
+                events=self.events,
+                output_path=video_path,
+                title=f"{self.bin_name} CLI — {base_name}",
+            )
+            artifacts["webm"] = video_path
+
+            return artifacts
+
+        all_artifacts: dict[str, Path] = {}
+        for seg_name, arts in self.segments.items():
+            for k, v in arts.items():
+                all_artifacts[f"{seg_name}_{k}"] = v
+        if self.segments:
+            latest_seg = list(self.segments.values())[-1]
+            all_artifacts.update(latest_seg)
+        return all_artifacts
+
+    @staticmethod
+    def _format_vtt_time(seconds: float) -> str:
+        """Format seconds float into standard WebVTT timestamp (HH:MM:SS.mmm)."""
+        hrs = int(seconds // 3600)
+        mins = int((seconds % 3600) // 60)
+        secs = int(seconds % 60)
+        millis = int(round((seconds - int(seconds)) * 1000))
+        return f"{hrs:02d}:{mins:02d}:{secs:02d}.{millis:03d}"
+
+
+__all__ = [
+    "CliNarrator",
+    "TerminalEvent",
+]

hexastack_cli-0.8.0/src/hexastack_cli/adapters/__init__.py

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

hexastack_cli-0.8.0/src/hexastack_cli/testing/narrator.py

@@ -1,188 +0,0 @@
-"""Feature demo narrator and Playwright terminal video recorder for CLI commands."""
-
-from __future__ import annotations
-
-import os
-import time
-from pathlib import Path
-from typing import Any
-
-from typer.testing import CliRunner, Result
-
-from hexastack_cli.testing.events import TerminalEvent
-from hexastack_core.utils.fs import atomic_write_text
-
-
-class CliNarrator:
-    """Orchestrates structured narrative CLI execution, step recording, and video rendering.
-
-    Notes/Architectural Intent:
-        1. In standard CI/unit test mode, runs instantly with zero delay via in-memory CliRunner.
-        2. In demo recording mode (`RECORD_DEMO=1`), captures keystrokes, output tokens, and narrative steps,
-           and directly renders a fixed-window, auto-scrolling .webm video via Playwright.
-    """
-
-    def __init__(
-        self,
-        app: Any,
-        output_name: str | None = None,
-        output_dir: Path | None = None,
-        width: int = 100,
-        height: int = 24,
-    ) -> None:
-        """Initialize CLI narrator attached to a Typer or Click application.
-
-        Args:
-            app: Target Typer application instance.
-            output_name: Base filename (without extension) for saving recordings.
-            output_dir: Target output directory for generated demo artifacts.
-            width: Terminal column width.
-            height: Terminal row height.
-        """
-        self.app = app
-        self.output_name = output_name
-        self.output_dir = output_dir or Path("docs/assets/demos")
-        self.width = width
-        self.height = height
-        self.record_mode = os.environ.get("RECORD_DEMO") in ("1", "true", "True")
-        self.runner = CliRunner()
-        self.start_time: float = time.time()
-        self.events: list[TerminalEvent] = []
-        self.captions: list[tuple[float, float, str]] = []
-        self._current_step_start: float | None = None
-        self._current_step_text: str | None = None
-
-    def step(self, title: str, *, record: bool = True) -> None:
-        """Mark a new narrative step in the CLI demo recording.
-
-        Args:
-            title: Human-readable narrative explanation shown in subtitle banner.
-            record: Whether to emit the step subtitle and recording marker (defaults to True).
-        """
-        if not record:
-            return
-
-        now = time.time() - self.start_time
-        if self._current_step_start is not None and self._current_step_text is not None:
-            self.captions.append(
-                (self._current_step_start, now, self._current_step_text)
-            )
-
-        self._current_step_start = now
-        self._current_step_text = title
-
-        if self.record_mode:
-            self.events.append(
-                TerminalEvent(event_type="step", payload=title, timestamp=now)
-            )
-
-    def run_command(
-        self,
-        args: list[str],
-        env: dict[str, str] | None = None,
-        input: str | None = None,
-        record: bool = True,
-    ) -> Result:
-        """Execute a CLI command within the active Typer application.
-
-        Args:
-            args: Command-line argument strings.
-            env: Optional environment variables.
-            input: Optional stdin input string.
-            record: Whether to record this command invocation and output (defaults to True).
-
-        Returns:
-            CliRunner Result containing exit code, stdout, and stderr.
-        """
-        cmd_str = f"hexastack {' '.join(args)}"
-
-        if self.record_mode and record:
-            # 1. Record input command string
-            now = time.time() - self.start_time
-            self.events.append(
-                TerminalEvent(
-                    event_type="input",
-                    payload=f"$ {cmd_str}\n",
-                    timestamp=now,
-                )
-            )
-
-        # Execute command in-memory
-        res = self.runner.invoke(self.app, args, input=input, env=env)
-
-        if self.record_mode and record:
-            # 2. Record command output text
-            now = time.time() - self.start_time
-            output_text = res.stdout if res.stdout else ""
-            if output_text:
-                self.events.append(
-                    TerminalEvent(
-                        event_type="output",
-                        payload=output_text,
-                        timestamp=now,
-                    )
-                )
-
-        return res
-
-    def finish(self) -> dict[str, Path]:
-        """Finalize the recording and render video and caption artifacts.
-
-        Returns:
-            Dictionary containing paths to generated artifact files (e.g. 'webm', 'vtt').
-        """
-        if not self.record_mode:
-            return {}
-
-        now = time.time() - self.start_time
-        if self._current_step_start is not None and self._current_step_text is not None:
-            self.captions.append(
-                (self._current_step_start, now, self._current_step_text)
-            )
-
-        out_dir = self.output_dir
-        out_dir.mkdir(parents=True, exist_ok=True)
-        base_name = self.output_name or "cli-demo"
-        artifacts: dict[str, Path] = {}
-
-        # 1. Export WebVTT (.vtt) synchronized narration subtitles
-        vtt_lines = ["WEBVTT", ""]
-        for idx, (start_s, end_s, text) in enumerate(self.captions, start=1):
-            vtt_lines.append(str(idx))
-            vtt_lines.append(
-                f"{self._format_vtt_time(start_s)} --> {self._format_vtt_time(end_s)}"
-            )
-            vtt_lines.append(text)
-            vtt_lines.append("")
-
-        vtt_path = out_dir / f"{base_name}.vtt"
-        atomic_write_text(vtt_path, "\n".join(vtt_lines), encoding="utf-8")
-        artifacts["vtt"] = vtt_path
-
-        # 2. Render directly to .webm video via Playwright Rich Terminal
-        from hexastack_cli.testing.terminal import render_cli_demo_video
-
-        video_path = out_dir / f"{base_name}.webm"
-        render_cli_demo_video(
-            events=self.events,
-            output_path=video_path,
-            title=f"Hexastack CLI — {base_name}",
-        )
-        artifacts["webm"] = video_path
-
-        return artifacts
-
-    @staticmethod
-    def _format_vtt_time(seconds: float) -> str:
-        """Format seconds float into standard WebVTT timestamp (HH:MM:SS.mmm)."""
-        hrs = int(seconds // 3600)
-        mins = int((seconds % 3600) // 60)
-        secs = int(seconds % 60)
-        millis = int(round((seconds - int(seconds)) * 1000))
-        return f"{hrs:02d}:{mins:02d}:{secs:02d}.{millis:03d}"
-
-
-__all__ = [
-    "CliNarrator",
-    "TerminalEvent",
-]