@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/vds_cli_common/src/vds_cli_common/output.py

@@ -0,0 +1,284 @@
+"""Output Manager for unified CLI output across VDS CLIs.
+
+This module provides OutputManager, a class that handles:
+- JSON output (compact/pretty based on mode)
+- Rich tables, panels, and formatted output
+- Spinners for long-running operations
+- Progress bars for batch operations
+- Error messages with hints
+
+Usage:
+    ctx = CLIContext.from_options(json_only=False)
+    out = OutputManager(ctx)
+
+    with out.spinner("Connecting..."):
+        result = client.ping()
+
+    out.output_json({"status": "ok"})
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from rich.progress import Progress
+    from rich.table import Table
+
+    from .context import CLIContext
+
+
+class NullProgress:
+    """No-op progress bar for non-TTY environments."""
+
+    def add_task(self, description: str, total: float = 100.0, **kwargs: Any) -> int:
+        """Add a task (no-op)."""
+        return 0
+
+    def update(self, task_id: int, advance: float = 1.0, **kwargs: Any) -> None:
+        """Update task progress (no-op)."""
+
+    def __enter__(self) -> NullProgress:
+        """Enter context."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context."""
+
+
+class OutputManager:
+    """Unified output manager for VDS CLIs.
+
+    Handles all output operations with context-aware formatting:
+    - JSON output (always clean, parseable)
+    - Rich tables (TTY only)
+    - Spinners (TTY only, respects quiet mode)
+    - Progress bars (TTY only, respects quiet mode)
+    - Error messages (always shown, styled for TTY)
+    - Success/info/warning messages (respects quiet mode)
+
+    Args:
+        ctx: CLIContext instance for output settings
+    """
+
+    def __init__(self, ctx: CLIContext) -> None:
+        """Initialize OutputManager with CLI context."""
+
+        self.ctx: CLIContext = ctx
+        self._console = ctx.console
+        self._err_console = ctx.err_console
+
+    def output_json(self, data: dict[str, Any] | list[Any], pretty: bool = True) -> None:
+        """Output data as JSON to stdout.
+
+        In json_only mode, always outputs compact JSON.
+        Otherwise, outputs pretty-printed JSON or uses Rich JSON highlighting.
+
+        Args:
+            data: Data to output as JSON
+            pretty: Whether to pretty-print (ignored in json_only mode)
+        """
+        if self.ctx.json_only:
+            # Compact JSON for piping/parsing
+            print(json.dumps(data, default=str, ensure_ascii=False))
+        elif pretty and self.ctx.use_rich_output:
+            # Pretty JSON with syntax highlighting
+            from rich.json import JSON
+
+            self._console.print(JSON.from_data(data))
+        elif pretty:
+            print(json.dumps(data, indent=2, default=str, ensure_ascii=False))
+        else:
+            print(json.dumps(data, default=str, ensure_ascii=False))
+
+    def output_error(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Output error message to stderr.
+
+        In json_only mode, outputs JSON error object.
+        Otherwise, outputs styled error with optional hint.
+
+        Args:
+            message: Error message
+            hint: Optional hint for resolution
+            details: Optional additional details
+        """
+        if self.ctx.json_only:
+            error_obj: dict[str, Any] = {"error": True, "message": message}
+            if hint:
+                error_obj["hint"] = hint
+            if details:
+                error_obj["details"] = details
+            print(json.dumps(error_obj), file=sys.stderr)
+        else:
+            self._err_console.print(f"[bold red]✗ Error:[/bold red] {message}")
+            if hint:
+                self._err_console.print(f"[yellow]  💡 Hint:[/yellow] {hint}")
+            if details:
+                for key, value in details.items():
+                    self._err_console.print(f"[dim]  {key}:[/dim] {value}")
+
+    def output_success(self, message: str) -> None:
+        """Output success message (suppressed in quiet/json mode).
+
+        Args:
+            message: Success message to display
+        """
+        if self.ctx.show_hints:
+            self._console.print(f"[bold green]✓[/bold green] {message}")
+
+    def output_warning(self, message: str) -> None:
+        """Output warning message (suppressed in quiet/json mode).
+
+        Args:
+            message: Warning message to display
+        """
+        if self.ctx.show_hints:
+            self._console.print(f"[bold yellow]⚠[/bold yellow] {message}")
+
+    def output_info(self, message: str) -> None:
+        """Output info message (suppressed in quiet/json mode).
+
+        Args:
+            message: Info message to display
+        """
+        if self.ctx.show_hints:
+            self._console.print(f"[blue]ℹ[/blue] {message}")
+
+    def suggest_next(self, commands: list[str]) -> None:
+        """Suggest next commands to run (suppressed in quiet/json mode).
+
+        Args:
+            commands: List of suggested commands
+        """
+        if self.ctx.show_hints and commands:
+            suggestions = ", ".join(f"[cyan]{cmd}[/cyan]" for cmd in commands)
+            self._console.print(f"\n[dim]Try next:[/dim] {suggestions}")
+
+    @contextmanager
+    def spinner(self, message: str) -> Iterator[None]:
+        """Show a spinner while executing a block.
+
+        The spinner is only shown when:
+        - stdout is a TTY
+        - not in json_only mode
+        - not in quiet mode
+
+        Args:
+            message: Message to display with spinner
+
+        Yields:
+            None
+        """
+        if not self.ctx.use_spinner:
+            yield
+            return
+
+        with self._err_console.status(f"[bold green]{message}", spinner="dots"):
+            yield
+
+    @contextmanager
+    def progress(
+        self,
+        description: str,
+        total: float = 100.0,
+    ) -> Iterator[Progress | NullProgress]:
+        """Create a progress bar context.
+
+        Returns NullProgress if progress should be hidden.
+
+        Args:
+            description: Description of the progress
+            total: Total number of steps
+
+        Yields:
+            Progress bar instance (or NullProgress if hidden)
+        """
+        if not self.ctx.use_progress:
+            yield NullProgress()
+            return
+
+        from rich.progress import (
+            BarColumn,
+            MofNCompleteColumn,
+            Progress,
+            SpinnerColumn,
+            TaskProgressColumn,
+            TextColumn,
+            TimeElapsedColumn,
+            TimeRemainingColumn,
+        )
+
+        progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[bold blue]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            TimeRemainingColumn(),
+            console=self._err_console,
+            transient=True,
+        )
+
+        with progress:
+            yield progress
+
+    def table(
+        self,
+        title: str | None = None,
+        columns: list[str] | None = None,
+        rows: list[list[Any]] | None = None,
+    ) -> Table | None:
+        """Create and optionally populate a Rich table for output.
+
+        Returns None if tables should not be used (json_only or not TTY).
+
+        Args:
+            title: Optional table title
+            columns: Optional list of column names
+            rows: Optional list of row data
+
+        Returns:
+            Rich Table instance or None if tables shouldn't be used
+        """
+        if not self.ctx.use_rich_output:
+            return None
+
+        from rich.table import Table
+
+        table = Table(title=title)
+        if columns:
+            for col in columns:
+                table.add_column(col)
+        if rows:
+            for row in rows:
+                table.add_row(*[str(cell) for cell in row])
+        return table
+
+    def print(self, *args: Any, **kwargs: Any) -> None:
+        """Print to console (respects color settings).
+
+        Args:
+            *args: Arguments to print
+            **kwargs: Keyword arguments for console.print
+        """
+        self._console.print(*args, **kwargs)
+
+    def print_err(self, *args: Any, **kwargs: Any) -> None:
+        """Print to stderr (respects color settings).
+
+        Args:
+            *args: Arguments to print
+            **kwargs: Keyword arguments for console.print
+        """
+        self._err_console.print(*args, **kwargs)

package/tools/vds-scripts/vds_cli_common/src/vds_cli_common/paths.py

@@ -0,0 +1,78 @@
+"""Path and configuration helpers for VDS scripts."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP_NAME = "vds"
+APP_AUTHOR = "VDS"
+_PROJECT_ROOT = Path(__file__).resolve().parents[3]
+_SCRIPTS_DIR = _PROJECT_ROOT.parent
+
+
+def _default_vds_home() -> Path:
+    return Path.home() / ".vds"
+
+
+def _optional_override(env_key: str) -> Path | None:
+    raw = (os.getenv(env_key) or "").strip()
+    if not raw:
+        return None
+    return Path(raw).expanduser().resolve()
+
+
+def get_vds_config_root() -> Path:
+    override = _optional_override("VDS_CONFIG_DIR")
+    if override is not None:
+        return override
+    return _default_vds_home()
+
+
+def get_vds_cache_root() -> Path:
+    override = _optional_override("VDS_CACHE_DIR")
+    if override is not None:
+        return override
+    return get_vds_config_root() / "cache"
+
+
+def get_vds_data_root() -> Path:
+    override = _optional_override("VDS_DATA_DIR")
+    if override is not None:
+        return override
+    return get_vds_config_root() / "data"
+
+
+def get_vds_log_root() -> Path:
+    override = _optional_override("VDS_LOG_DIR")
+    if override is not None:
+        return override
+    return get_vds_config_root() / "logs"
+
+
+def get_shared_env_path() -> Path:
+    override = _optional_override("VDS_ENV_FILE")
+    if override is not None:
+        return override
+    return get_vds_config_root() / ".env"
+
+
+def get_scripts_dir() -> Path:
+    return _SCRIPTS_DIR
+
+
+def get_default_env_paths() -> tuple[Path, ...]:
+    return (get_shared_env_path(),)
+
+
+__all__ = [
+    "APP_AUTHOR",
+    "APP_NAME",
+    "get_default_env_paths",
+    "get_scripts_dir",
+    "get_shared_env_path",
+    "get_vds_cache_root",
+    "get_vds_config_root",
+    "get_vds_data_root",
+    "get_vds_log_root",
+]

package/tools/vds-scripts/vds_cli_common/src/vds_cli_common/testing.py

@@ -0,0 +1,213 @@
+"""Test fixtures and helpers for VDS CLI testing.
+
+This module provides pytest fixtures and helper functions for testing
+CLI components with TTY mocking, output capture, and environment control.
+
+Usage:
+    from vds_cli_common.testing import mock_tty, mock_pipe, create_test_context
+
+    def test_tty_detection(mock_tty):
+        ctx = CLIContext()
+        assert ctx.is_tty is True
+
+    def test_pipe_mode(mock_pipe):
+        ctx = CLIContext()
+        assert ctx.is_tty is False
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+if TYPE_CHECKING:
+    from .context import CLIContext
+    from .output import OutputManager
+
+
+@contextmanager
+def mock_tty() -> Iterator[None]:
+    """Context manager to mock stdout as a TTY.
+
+    Usage:
+        with mock_tty():
+            ctx = CLIContext()
+            assert ctx.is_tty is True
+
+    Yields:
+        None
+    """
+    with patch.object(sys.stdout, "isatty", return_value=True):
+        yield
+
+
+@contextmanager
+def mock_pipe() -> Iterator[None]:
+    """Context manager to mock stdout as a pipe (non-TTY).
+
+    Usage:
+        with mock_pipe():
+            ctx = CLIContext()
+            assert ctx.is_tty is False
+
+    Yields:
+        None
+    """
+    with patch.object(sys.stdout, "isatty", return_value=False):
+        yield
+
+
+@contextmanager
+def mock_no_color_env() -> Iterator[None]:
+    """Context manager to mock NO_COLOR environment variable.
+
+    Usage:
+        with mock_no_color_env():
+            ctx = CLIContext()
+            assert ctx.use_color is False
+
+    Yields:
+        None
+    """
+    with patch.dict(os.environ, {"NO_COLOR": "1"}):
+        yield
+
+
+@contextmanager
+def mock_force_color_env() -> Iterator[None]:
+    """Context manager to mock FORCE_COLOR environment variable.
+
+    Usage:
+        with mock_force_color_env():
+            ctx = CLIContext()
+            assert ctx.use_color is True
+
+    Yields:
+        None
+    """
+    with patch.dict(os.environ, {"FORCE_COLOR": "1"}):
+        yield
+
+
+@contextmanager
+def capture_output() -> Iterator[dict[str, list[str]]]:
+    """Context manager to capture stdout and stderr for testing.
+
+    Usage:
+        with capture_output() as captured:
+            print("Hello")
+        assert "Hello" in captured["stdout"][0]
+
+    Yields:
+        Dictionary with "stdout" and "stderr" lists
+    """
+    captured: dict[str, list[str]] = {"stdout": [], "stderr": []}
+
+    original_stdout_write = sys.stdout.write
+    original_stderr_write = sys.stderr.write
+
+    def mock_stdout_write(text: str) -> int:
+        if text.strip():  # Skip empty/whitespace-only
+            captured["stdout"].append(text)
+        return len(text)
+
+    def mock_stderr_write(text: str) -> int:
+        if text.strip():  # Skip empty/whitespace-only
+            captured["stderr"].append(text)
+        return len(text)
+
+    with patch.object(sys.stdout, "write", mock_stdout_write), patch.object(sys.stderr, "write", mock_stderr_write):
+        yield captured
+
+
+def create_test_context(
+    *,
+    json_only: bool = False,
+    quiet: bool = False,
+    no_color: bool = False,
+    force_color: bool = False,
+    is_tty: bool = True,
+) -> CLIContext:
+    """Create a CLIContext for testing with specified settings.
+
+    Args:
+        json_only: Enable JSON-only mode
+        quiet: Enable quiet mode
+        no_color: Disable colors
+        force_color: Force colors
+        is_tty: Mock TTY detection result
+
+    Returns:
+        Configured CLIContext instance
+    """
+    from .context import CLIContext
+
+    with patch.object(sys.stdout, "isatty", return_value=is_tty):
+        return CLIContext.from_options(
+            json_only=json_only,
+            quiet=quiet,
+            no_color=no_color,
+            force_color=force_color,
+        )
+
+
+def create_test_output(ctx: CLIContext | None = None) -> OutputManager:
+    """Create an OutputManager for testing.
+
+    Args:
+        ctx: Optional CLIContext (creates default if not provided)
+
+    Returns:
+        Configured OutputManager instance
+    """
+    from .output import OutputManager
+
+    if ctx is None:
+        ctx = create_test_context()
+    return OutputManager(ctx)
+
+
+# Pytest fixtures (can be used directly or as reference)
+def pytest_fixtures() -> str:
+    """Return pytest fixture definitions for copy-paste into conftest.py.
+
+    Returns:
+        String containing pytest fixture code
+    """
+    return '''
+import pytest
+from vds_cli_common.testing import (
+    mock_tty as _mock_tty,
+    mock_pipe as _mock_pipe,
+    mock_no_color_env as _mock_no_color_env,
+    mock_force_color_env as _mock_force_color_env,
+)
+
+@pytest.fixture
+def mock_tty():
+    """Mock stdout as a TTY."""
+    with _mock_tty():
+        yield
+
+@pytest.fixture
+def mock_pipe():
+    """Mock stdout as a pipe (non-TTY)."""
+    with _mock_pipe():
+        yield
+
+@pytest.fixture
+def mock_no_color_env():
+    """Mock NO_COLOR environment variable."""
+    with _mock_no_color_env():
+        yield
+
+@pytest.fixture
+def mock_force_color_env():
+    """Mock FORCE_COLOR environment variable."""
+    with _mock_force_color_env():
+        yield
+'''

package/tools/vds-scripts/vds_cli_common/src/vds_cli_common/version.py

@@ -0,0 +1,85 @@
+"""Version callback factory for VDS CLIs.
+
+This module provides a factory function for creating --version flag callbacks
+that work consistently across all VDS CLIs.
+
+Usage:
+    from vds_cli_common import create_version_callback
+
+    version_callback = create_version_callback("vds-elastic-orchestrator")
+
+    @app.callback()
+    def main(
+        version: bool = typer.Option(
+            False,
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit",
+        ),
+    ):
+        pass
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from collections.abc import Callable
+
+import typer
+
+
+def create_version_callback(package_name: str) -> Callable[[bool], None]:
+    """Create a version callback for a package.
+
+    The callback prints the package version and exits when --version is provided.
+
+    Args:
+        package_name: The package name to look up version for
+
+    Returns:
+        A callback function suitable for typer.Option
+
+    Example:
+        version_callback = create_version_callback("vds-elastic-orchestrator")
+
+        @app.callback()
+        def main(
+            version: bool = typer.Option(
+                False,
+                "--version",
+                "-V",
+                callback=version_callback,
+                is_eager=True,
+                help="Show version and exit",
+            ),
+        ):
+            pass
+    """
+
+    def callback(value: bool) -> None:
+        if value:
+            try:
+                version = importlib.metadata.version(package_name)
+            except importlib.metadata.PackageNotFoundError:
+                version = "unknown"
+            typer.echo(f"{package_name} {version}")
+            raise typer.Exit(0)
+
+    return callback
+
+
+def get_package_version(package_name: str) -> str:
+    """Get the version of an installed package.
+
+    Args:
+        package_name: The package name to look up
+
+    Returns:
+        Version string or "unknown" if not found
+    """
+    try:
+        return importlib.metadata.version(package_name)
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"

package/tools/vds-scripts/vds_cli_common/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for vds_cli_common package."""