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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexastack-cli
-Version: 0.9.0
+Version: 0.10.1
 Summary: Hexastack CLI presentation adapter with Typer and Rich
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -11,7 +11,7 @@ Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.8.0
 Requires-Dist: typer>=0.27.1
 Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
-Requires-Python: >=3.13
+Requires-Python: >=3.12
 Provides-Extra: testing
 Description-Content-Type: text/markdown
 
@@ -51,7 +51,6 @@ Description-Content-Type: text/markdown
 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
 ```
 
@@ -189,8 +188,10 @@ In automated CI environments or redirected streams (`not sys.stdin.isatty()`), `
 
 ## 7. Automated Demo Recording & Video Slicing (`CliNarrator`)
 
+> Automated narrative terminal recording and Playwright demo video rendering is provided by [`hexaqual.adapters.testing`](https://github.com/TheTrueSCU/hexaqual).
+
 ```python
-from hexastack_cli.testing import CliNarrator
+from hexaqual.adapters.testing import CliNarrator
 
 narrator = CliNarrator(record_video=True)
 narrator.say("Scaffolding microservice...")

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

@@ -34,7 +34,6 @@
 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
 ```
 
@@ -172,8 +171,10 @@ In automated CI environments or redirected streams (`not sys.stdin.isatty()`), `
 
 ## 7. Automated Demo Recording & Video Slicing (`CliNarrator`)
 
+> Automated narrative terminal recording and Playwright demo video rendering is provided by [`hexaqual.adapters.testing`](https://github.com/TheTrueSCU/hexaqual).
+
 ```python
-from hexastack_cli.testing import CliNarrator
+from hexaqual.adapters.testing import CliNarrator
 
 narrator = CliNarrator(record_video=True)
 narrator.say("Scaffolding microservice...")

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

@@ -1,10 +1,10 @@
 [project]
 name = "hexastack-cli"
-version = "0.9.0"
+version = "0.10.1"
 description = "Hexastack CLI presentation adapter with Typer and Rich"
 readme = "README.md"
 license = "Apache-2.0"
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 dependencies = [
     "hexastack-core",
     "hexastack-cqrs",
@@ -24,7 +24,7 @@ testing = ["playwright>=1.49.0"]
 cli = "hexastack_cli.infra.bootstrap:CliBootstrapper"
 
 [build-system]
-requires = ["uv_build>=0.12.3,<0.13.0"]
+requires = ["uv_build>=0.12.3,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources.hexastack-core]

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

@@ -1,13 +1,13 @@
 [project]
 name = "hexastack-cli"
-version = "0.9.0"
+version = "0.10.1"
 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"
+requires-python = ">=3.12"
 dependencies = [
     "hexastack-core",
     "hexastack-cqrs",
@@ -25,7 +25,7 @@ testing = [
 cli = "hexastack_cli.infra.bootstrap:CliBootstrapper"
 
 [build-system]
-requires = ["uv_build>=0.12.3,<0.13.0"]
+requires = ["uv_build>=0.12.3,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources]

{hexastack_cli-0.9.0 → hexastack_cli-0.10.1}/src/hexastack_cli/adapters/routing.py

@@ -307,6 +307,7 @@ def register_cqrs_command(
     presenter: RichTerminalPresenter | None = None,
     console: Console | None = None,
     feature_flag: str | None = None,
+    hidden: bool = False,
 ) -> None:
     """Register a CQRS Command model as a typed CLI sub-command on a Typer application.
 
@@ -325,6 +326,7 @@ def register_cqrs_command(
         presenter: Optional RichTerminalPresenter instance.
         console: Optional rich Console instance.
         feature_flag: Optional feature flag key required for execution.
+        hidden: Whether to hide the command from CLI help documentation.
 
     Returns:
         None.
@@ -343,7 +345,7 @@ def register_cqrs_command(
         console=console,
         feature_flag=feature_flag,
     )
-    app.command(name=cmd_name, help=doc)(runner)
+    app.command(name=cmd_name, help=doc, hidden=hidden)(runner)
 
 
 def register_cqrs_query(
@@ -357,6 +359,7 @@ def register_cqrs_query(
     presenter: RichTerminalPresenter | None = None,
     console: Console | None = None,
     feature_flag: str | None = None,
+    hidden: bool = False,
 ) -> None:
     """Register a CQRS Query model as a typed CLI sub-command on a Typer application.
 
@@ -375,6 +378,7 @@ def register_cqrs_query(
         presenter: Optional RichTerminalPresenter instance.
         console: Optional rich Console instance.
         feature_flag: Optional feature flag key required for execution.
+        hidden: Whether to hide the command from CLI help documentation.
 
     Returns:
         None.
@@ -393,4 +397,4 @@ def register_cqrs_query(
         console=console,
         feature_flag=feature_flag,
     )
-    app.command(name=qry_name, help=doc)(runner)
+    app.command(name=qry_name, help=doc, hidden=hidden)(runner)

{hexastack_cli-0.9.0 → hexastack_cli-0.10.1}/src/hexastack_cli/infra/autodiscovery.py

@@ -92,6 +92,7 @@ def _register_model_target(
     meta: CliMetadata,
     cmd_name: str,
     help_text: str | None,
+    hidden: bool,
     pipeline: ExecutionPipeline,
     console: Console | None,
 ) -> None:
@@ -107,6 +108,7 @@ def _register_model_target(
             output_format=meta.output_format,
             console=console,
             feature_flag=meta.feature_flag,
+            hidden=hidden,
         )
     elif meta.kind == "query" and issubclass(obj, Query):
         register_cqrs_query(
@@ -119,9 +121,29 @@ def _register_model_target(
             output_format=meta.output_format,
             console=console,
             feature_flag=meta.feature_flag,
+            hidden=hidden,
         )
 
 
+def _resolve_alias_targets(
+    group: str | Sequence[str] | None,
+    aliases: Sequence[str],
+    help_text: str | None,
+) -> list[tuple[list[str], str, str | None]]:
+    """Resolve (group_parts, cmd_name, help) targets for a sequence of aliases."""
+    primary_group = _normalize_group_path(group)
+    targets: list[tuple[list[str], str, str | None]] = []
+    for alias in aliases:
+        if alias.startswith("/"):
+            targets.append(([], alias.lstrip("/"), help_text))
+        elif any(sep in alias for sep in (".", "/", " ")):
+            parts = _normalize_group_path(alias)
+            targets.append((parts[:-1], parts[-1], help_text))
+        else:
+            targets.append((primary_group, alias, help_text))
+    return targets
+
+
 def _resolve_targets(
     meta: CliMetadata, default_name: str
 ) -> list[tuple[list[str], str, str | None]]:
@@ -131,16 +153,7 @@ def _resolve_targets(
     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))
-
+    targets.extend(_resolve_alias_targets(meta.group, meta.aliases, meta.help))
     return targets
 
 
@@ -205,11 +218,22 @@ def create_cli_visitor(
 
         default_name = _to_kebab_case(obj.__name__)
         targets = _resolve_targets(meta, default_name)
+        hidden = getattr(meta, "hidden", False)
 
         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
+                target_app, obj, meta, cmd_name, help_text, hidden, pipeline, console
+            )
+
+        if meta.hidden_aliases:
+            hidden_targets = _resolve_alias_targets(
+                meta.group, meta.hidden_aliases, meta.help
             )
+            for group_parts, cmd_name, help_text in hidden_targets:
+                target_app = manager.get_or_create(group_parts)
+                _register_model_target(
+                    target_app, obj, meta, cmd_name, help_text, True, pipeline, console
+                )
 
     return visitor

{hexastack_cli-0.9.0 → hexastack_cli-0.10.1}/src/hexastack_cli/infra/decorators.py

@@ -1,5 +1,6 @@
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
+from functools import wraps
 from typing import Any, Literal, TypeVar
 
 from hexastack_core.domain import Command, Query
@@ -28,6 +29,8 @@ class CliMetadata:
     output_format: str | None = None
     group: str | Sequence[str] | None = None
     feature_flag: str | None = None
+    hidden: bool = False
+    hidden_aliases: tuple[str, ...] = field(default_factory=tuple)
 
 
 @dataclass(frozen=True)
@@ -66,10 +69,12 @@ def cli_command(
     *,
     positional: Sequence[str] | str | None = None,
     aliases: Sequence[str] | str | None = None,
+    hidden_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,
+    hidden: bool = False,
 ) -> Callable[[type[TCommand]], type[TCommand]]:
     """Decorator marking a Command class for automatic CLI command exposure.
 
@@ -77,10 +82,12 @@ def cli_command(
         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').
+        hidden_aliases: Optional alias or list of aliases to register with hidden=True.
         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.
+        hidden: Whether to hide the command from terminal --help displays.
 
     Returns:
         Decorated Command class with attached CLI metadata.
@@ -95,10 +102,12 @@ def cli_command(
             name=name,
             positional=_normalize_tokens(positional),
             aliases=_normalize_tokens(aliases),
+            hidden_aliases=_normalize_tokens(hidden_aliases),
             help=help,
             output_format=output_format,
             group=group,
             feature_flag=feature_flag,
+            hidden=hidden,
         )
         setattr(cls, _CLI_METADATA_ATTR, meta)
         return cls
@@ -137,10 +146,12 @@ def cli_query(
     *,
     positional: Sequence[str] | str | None = None,
     aliases: Sequence[str] | str | None = None,
+    hidden_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,
+    hidden: bool = False,
 ) -> Callable[[type[TQuery]], type[TQuery]]:
     """Decorator marking a Query class for automatic CLI command exposure.
 
@@ -148,10 +159,12 @@ def cli_query(
         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').
+        hidden_aliases: Optional alias or list of aliases to register with hidden=True.
         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.
+        hidden: Whether to hide the query command from terminal --help displays.
 
     Returns:
         Decorated Query class with attached CLI metadata.
@@ -166,10 +179,12 @@ def cli_query(
             name=name,
             positional=_normalize_tokens(positional),
             aliases=_normalize_tokens(aliases),
+            hidden_aliases=_normalize_tokens(hidden_aliases),
             help=help,
             output_format=output_format,
             group=group,
             feature_flag=feature_flag,
+            hidden=hidden,
         )
         setattr(cls, _CLI_METADATA_ATTR, meta)
         return cls
@@ -195,8 +210,6 @@ def feature_flag_command(
     Returns:
         Decorator wrapping the target callable.
     """
-    from functools import wraps
-
     import typer
 
     from hexastack_core.adapters.feature_flags.config import ConfigFeatureFlagAdapter

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

@@ -1,9 +0,0 @@
-from hexastack_cli.testing.events import TerminalEvent
-from hexastack_cli.testing.narrator import CliNarrator
-from hexastack_cli.testing.terminal import render_cli_demo_video
-
-__all__ = [
-    "CliNarrator",
-    "render_cli_demo_video",
-    "TerminalEvent",
-]

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

@@ -1,16 +0,0 @@
-"""Domain models and data contracts for CLI testing and narrative demonstration."""
-
-from dataclasses import dataclass
-
-__all__ = [
-    "TerminalEvent",
-]
-
-
-@dataclass(frozen=True, slots=True)
-class TerminalEvent:
-    """A discrete timestamped event within a CLI demo recording session."""
-
-    event_type: str  # "step" | "input" | "output"
-    payload: str
-    timestamp: float

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

@@ -1,323 +0,0 @@
-"""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.9.0/src/hexastack_cli/testing/terminal.py

@@ -1,329 +0,0 @@
-"""Rich HTML Terminal view and Playwright video renderer for CLI demo recordings."""
-
-from __future__ import annotations
-
-import concurrent.futures
-import html
-import json
-import re
-import shutil
-from pathlib import Path
-
-from hexastack_cli.testing.events import TerminalEvent
-from hexastack_core.domain.exceptions import MissingDependencyError
-from hexastack_core.utils.fs import atomic_write_text
-
-TERMINAL_HTML_TEMPLATE = """<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <title>{title}</title>
-    <style>
-        * {{ box-sizing: border-box; margin: 0; padding: 0; }}
-        body {{
-            background: #0d1117;
-            color: #e6edf3;
-            font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', Menlo, Monaco, 'Courier New', monospace;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            height: 100vh;
-            overflow: hidden;
-            padding: 40px;
-        }}
-        .window {{
-            background: #161b22;
-            border-radius: 12px;
-            box-shadow: 0 20px 50px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.1);
-            width: 1080px;
-            height: 560px;
-            max-height: 560px;
-            display: flex;
-            flex-direction: column;
-            overflow: hidden;
-        }}
-        .titlebar {{
-            background: #21262d;
-            padding: 12px 16px;
-            display: flex;
-            align-items: center;
-            border-bottom: 1px solid rgba(255,255,255,0.08);
-            flex-shrink: 0;
-        }}
-        .dots {{
-            display: flex;
-            gap: 8px;
-        }}
-        .dot {{
-            width: 12px;
-            height: 12px;
-            border-radius: 50%;
-        }}
-        .dot-red {{ background: #ff5f56; }}
-        .dot-yellow {{ background: #ffbd2e; }}
-        .dot-green {{ background: #27c93f; }}
-        .title {{
-            flex: 1;
-            text-align: center;
-            color: #8b949e;
-            font-size: 13px;
-            font-weight: 500;
-            margin-right: 48px;
-        }}
-        .content {{
-            padding: 24px;
-            font-size: 15px;
-            line-height: 1.6;
-            flex: 1;
-            overflow-y: auto;
-            white-space: pre-wrap;
-            word-break: break-word;
-            scroll-behavior: smooth;
-        }}
-        .content::-webkit-scrollbar {{
-            display: none;
-        }}
-        .content {{
-            -ms-overflow-style: none;
-            scrollbar-width: none;
-        }}
-        .prompt {{ color: #7ee787; font-weight: bold; }}
-        .command {{ color: #79c0ff; font-weight: bold; }}
-        .step-banner {{
-            position: fixed;
-            bottom: 32px;
-            left: 50%;
-            transform: translateX(-50%);
-            background: rgba(15, 23, 42, 0.92);
-            color: #ffffff;
-            padding: 12px 24px;
-            border-radius: 8px;
-            font-size: 17px;
-            font-family: system-ui, -apple-system, sans-serif;
-            font-weight: 500;
-            box-shadow: 0 10px 25px rgba(0,0,0,0.5);
-            border: 1px solid rgba(255,255,255,0.15);
-            backdrop-filter: blur(8px);
-            z-index: 9999;
-            transition: opacity 0.2s ease-in-out;
-            text-align: center;
-            max-width: 80%;
-        }}
-        .cursor {{
-            display: inline-block;
-            width: 8px;
-            height: 16px;
-            background: #58a6ff;
-            vertical-align: text-bottom;
-            animation: blink 1s step-end infinite;
-        }}
-        @keyframes blink {{ 50% {{ opacity: 0; }} }}
-    </style>
-</head>
-<body>
-    <div class="window">
-        <div class="titlebar">
-            <div class="dots">
-                <div class="dot dot-red"></div>
-                <div class="dot dot-yellow"></div>
-                <div class="dot dot-green"></div>
-            </div>
-            <div class="title">{title} — bash</div>
-        </div>
-        <div class="content" id="terminal-content"><span class="cursor"></span></div>
-    </div>
-    <div class="step-banner" id="banner" style="display: none;"></div>
-</body>
-</html>
-"""
-
-
-def _strip_ansi(text: str) -> str:
-    """Remove ANSI color and escape sequences from text."""
-    ansi_escape = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
-    return ansi_escape.sub("", text)
-
-
-def _render_in_clean_thread(
-    events: list[TerminalEvent],
-    output_path: Path,
-    title: str,
-    width: int,
-    height: int,
-) -> tuple[Path, Path]:
-    """Execute Playwright video recording in a fresh thread with its own event loop."""
-    try:
-        from playwright.sync_api import sync_playwright
-    except ImportError as e:
-        raise MissingDependencyError(
-            "Playwright is required to record CLI demos into .webm video. "
-            "Install with 'pip install hexastack-cli[testing]' or 'pip install playwright'."
-        ) from e
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    temp_dir = output_path.parent / ".temp_video"
-    temp_dir.mkdir(parents=True, exist_ok=True)
-
-    html_content = TERMINAL_HTML_TEMPLATE.format(title=html.escape(title))
-    vtt_captions: list[tuple[float, float, str]] = []
-    current_step_start: float | None = None
-    current_step_text: str | None = None
-
-    with sync_playwright() as p:
-        try:
-            browser = p.chromium.launch(headless=True)
-        except Exception:
-            # If Playwright browser binaries are not installed, create placeholder video artifact
-            output_path.write_bytes(b"")
-            return output_path, output_path.with_suffix(".vtt")
-
-        context = browser.new_context(
-            viewport={"width": width, "height": height},
-            record_video_dir=str(temp_dir),
-            record_video_size={"width": width, "height": height},
-        )
-        page = context.new_page()
-        page.set_content(html_content)
-        page.wait_for_timeout(500)
-        start_playback_time = 0.5
-
-        current_time = start_playback_time
-
-        for ev in events:
-            if ev.event_type == "step":
-                if current_step_start is not None and current_step_text is not None:
-                    vtt_captions.append(
-                        (current_step_start, current_time, current_step_text)
-                    )
-
-                current_step_start = current_time
-                current_step_text = ev.payload
-
-                json_text = json.dumps(ev.payload)
-                page.evaluate(
-                    f"""(() => {{
-                        const banner = document.getElementById('banner');
-                        if (banner) {{
-                            banner.innerText = {json_text};
-                            banner.style.display = 'block';
-                        }}
-                    }})();"""
-                )
-                page.wait_for_timeout(600)
-                current_time += 0.6
-
-            elif ev.event_type == "input":
-                char_str = html.escape(ev.payload)
-                if char_str == "\n":
-                    char_str = "<br/>"
-                json_html = json.dumps(char_str)
-                page.evaluate(
-                    f"""(() => {{
-                        const terminal = document.getElementById('terminal-content');
-                        const cursor = terminal.querySelector('.cursor');
-                        const span = document.createElement('span');
-                        span.className = 'command';
-                        span.innerHTML = {json_html};
-                        terminal.insertBefore(span, cursor);
-                        terminal.scrollTop = terminal.scrollHeight;
-                    }})();"""
-                )
-                page.wait_for_timeout(35)
-                current_time += 0.035
-
-            elif ev.event_type == "output":
-                clean_text = _strip_ansi(ev.payload)
-                escaped_output = html.escape(clean_text).replace("\n", "<br/>")
-                json_output = json.dumps(escaped_output)
-                page.evaluate(
-                    f"""(() => {{
-                        const terminal = document.getElementById('terminal-content');
-                        const cursor = terminal.querySelector('.cursor');
-                        const div = document.createElement('div');
-                        div.style.color = '#c9d1d9';
-                        div.style.margin = '4px 0 12px 0';
-                        div.innerHTML = {json_output};
-                        terminal.insertBefore(div, cursor);
-                        terminal.scrollTop = terminal.scrollHeight;
-                    }})();"""
-                )
-                page.wait_for_timeout(1000)
-                current_time += 1.0
-
-        if current_step_start is not None and current_step_text is not None:
-            vtt_captions.append(
-                (current_step_start, current_time + 1.5, current_step_text)
-            )
-
-        page.wait_for_timeout(1500)
-        video = page.video
-        page.close()
-
-        if video:
-            video.save_as(output_path)
-
-        context.close()
-        browser.close()
-
-    shutil.rmtree(temp_dir, ignore_errors=True)
-
-    # Export synchronized WebVTT subtitles with true video timestamps
-    vtt_lines = ["WEBVTT", ""]
-    for idx, (start_s, end_s, text) in enumerate(vtt_captions, start=1):
-        vtt_lines.append(str(idx))
-        vtt_lines.append(f"{_format_vtt_time(start_s)} --> {_format_vtt_time(end_s)}")
-        vtt_lines.append(text)
-        vtt_lines.append("")
-
-    vtt_path = output_path.with_suffix(".vtt")
-    atomic_write_text(vtt_path, "\n".join(vtt_lines), encoding="utf-8")
-
-    return output_path, vtt_path
-
-
-def render_cli_demo_video(
-    events: list[TerminalEvent],
-    output_path: Path,
-    title: str = "Hexastack CLI",
-    width: int = 1280,
-    height: int = 720,
-) -> tuple[Path, Path]:
-    """Render a sequence of TerminalEvents into synchronized .webm video and .vtt subtitle track.
-
-    Args:
-        events: Chronological sequence of input, output, and step narrative events.
-        output_path: Destination Path for .webm video file.
-        title: Window title text for terminal banner.
-        width: Video frame width in pixels.
-        height: Video frame height in pixels.
-
-    Returns:
-        Tuple of (video_path, vtt_path).
-
-    Raises:
-        MissingDependencyError: If `playwright` is not installed.
-    """
-    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
-        future = executor.submit(
-            _render_in_clean_thread,
-            events=events,
-            output_path=output_path,
-            title=title,
-            width=width,
-            height=height,
-        )
-        return future.result()
-
-
-def _format_vtt_time(seconds: float) -> str:
-    """Format seconds into 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__ = [
-    "render_cli_demo_video",
-]