@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/vds_cli_common/README.md

@@ -0,0 +1,190 @@
+# VDS CLI Common
+
+Shared CLI infrastructure for VDS orchestrator CLIs.
+
+## Overview
+
+`vds-cli-common` provides a unified set of building blocks for creating consistent CLI applications across the VDS ecosystem. It standardizes output formatting, error handling, shell completions, and testing patterns.
+
+## Features
+
+- **CLIContext**: Dataclass for passing CLI state (verbosity, output format, color settings)
+- **OutputManager**: Rich-based output formatting with JSON/table/text modes
+- **ErrorHandler**: Consistent error handling with exit codes
+- **Version Callback**: Factory for `--version` flags
+- **Completers**: Shell completion helpers for common patterns
+- **Testing Fixtures**: pytest fixtures for CLI testing
+
+## Installation
+
+```bash
+# Add as dependency in pyproject.toml
+dependencies = [
+    "vds-cli-common @ file:///${PROJECT_ROOT}/../vds_cli_common",
+]
+
+# Or install directly
+uv add ../vds_cli_common
+```
+
+## Quick Start
+
+```python
+from vds_cli_common import CLIContext, OutputManager, ExitCodes, create_version_callback
+
+# Create context with CLI options
+ctx = CLIContext(verbose=True, output_format="json", no_color=False)
+
+# Use OutputManager for consistent output
+output = OutputManager(ctx)
+output.success("Operation completed")
+output.print_json({"key": "value"})
+
+# Handle errors consistently
+from vds_cli_common import ErrorHandler
+handler = ErrorHandler(ctx)
+handler.handle_error(some_exception)
+```
+
+## Modules
+
+### `context`
+
+```python
+from vds_cli_common import CLIContext
+
+ctx = CLIContext(
+    verbose=False,      # Enable verbose output
+    debug=False,        # Enable debug output
+    quiet=False,        # Suppress non-essential output
+    output_format="text",  # text, json, table
+    no_color=False,     # Disable colored output
+)
+```
+
+### `output`
+
+```python
+from vds_cli_common import OutputManager
+
+output = OutputManager(ctx)
+output.info("Information message")
+output.success("Success message")
+output.warning("Warning message")
+output.error("Error message")
+output.debug("Debug message")  # Only shown if ctx.debug=True
+output.verbose("Verbose message")  # Only shown if ctx.verbose=True
+
+# Structured output
+output.print_json(data)
+output.print_table(rows, columns=["Name", "Value"])
+```
+
+### `errors`
+
+```python
+from vds_cli_common import ErrorHandler, ExitCodes, CLIError
+
+# Standard exit codes
+ExitCodes.SUCCESS  # 0
+ExitCodes.GENERAL_ERROR  # 1
+ExitCodes.CONFIG_ERROR  # 2
+ExitCodes.AUTH_ERROR  # 3
+ExitCodes.NETWORK_ERROR  # 4
+ExitCodes.NOT_FOUND  # 5
+ExitCodes.VALIDATION_ERROR  # 6
+
+# Custom CLI errors
+raise CLIError("Something went wrong", exit_code=ExitCodes.VALIDATION_ERROR)
+
+# Error handler
+handler = ErrorHandler(ctx)
+exit_code = handler.handle_error(exception)
+```
+
+### `version`
+
+```python
+from vds_cli_common import create_version_callback
+import typer
+
+app = typer.Typer()
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", "-V",
+        callback=create_version_callback("my-cli", "1.0.0"),
+        is_eager=True,
+    ),
+):
+    pass
+```
+
+### `completers`
+
+```python
+from vds_cli_common import complete_from_list, complete_path, complete_choice
+
+# Static list completion
+@app.command()
+def cmd(
+    project: str = typer.Option(
+        ..., 
+        autocompletion=complete_from_list(["lep", "insurance", "saving"]),
+    ),
+):
+    pass
+
+# Path completion
+@app.command()
+def cmd(
+    file: str = typer.Option(..., autocompletion=complete_path()),
+):
+    pass
+```
+
+### `testing`
+
+```python
+import pytest
+from vds_cli_common.testing import cli_runner, captured_output, mock_context
+
+def test_my_command(cli_runner):
+    result = cli_runner.invoke(app, ["my-command"])
+    assert result.exit_code == 0
+
+def test_output(captured_output):
+    output = OutputManager(mock_context())
+    output.success("Done")
+    assert "Done" in captured_output.getvalue()
+```
+
+## Development
+
+```bash
+cd WHO-project/vds-scripts/vds_cli_common
+
+# Install with dev dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=vds_cli_common --cov-report=term-missing
+
+# Lint
+uv run ruff check src tests
+uv run ruff format src tests
+```
+
+## Requirements
+
+- Python >= 3.11
+- typer>=0.24.1
+- rich>=14.3.3
+
+## License
+
+MIT

package/tools/vds-scripts/vds_cli_common/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "vds-cli-common"
+version = "0.1.0"
+description = "Shared CLI infrastructure for VDS orchestrator CLIs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "VDS Team" }]
+keywords = ["cli", "typer", "rich", "vds"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.24.1",
+    "rich>=14.3.3",
+    "platformdirs>=4.5.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vds_cli_common"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+    "PTH",    # flake8-use-pathlib
+    "ERA",    # eradicate (commented code)
+    "PL",     # Pylint
+    "RUF",    # Ruff-specific
+]
+ignore = [
+    "PLR0913",  # Too many arguments
+    "PLR2004",  # Magic value comparison
+    "PLC0415",  # Allow lazy imports for performance (Rich imports are heavy)
+    "ARG002",   # Allow unused arguments in interface/stub methods
+    "TC003",    # Allow runtime imports of typing constructs
+    "RUF001",   # Allow Unicode symbols (ℹ for info icon)
+    "SIM117",   # Allow nested with statements for clarity
+    "F841",     # Allow unused variables in test setup
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["vds_cli_common"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src/vds_cli_common"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@abstractmethod",
+]
+fail_under = 90

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

@@ -0,0 +1,34 @@
+"""Shared infrastructure for VDS CLI packages.
+
+This package provides reusable components for building consistent CLIs:
+- CLIContext: TTY detection, color control, output mode management
+- OutputManager: Unified output with spinners, progress bars, tables
+- ErrorHandler: Consistent error formatting with suggestions
+- ExitCodes: Standard exit codes for all CLIs
+- create_version_callback: Factory for --version flag handlers
+"""
+
+from vds_cli_common.context import CLIContext
+from vds_cli_common.env import DEFAULT_ENV_PATHS, load_shared_env
+from vds_cli_common.errors import ErrorHandler, ExitCodes
+from vds_cli_common.output import NullProgress, OutputManager
+from vds_cli_common.paths import get_shared_env_path, get_vds_cache_root, get_vds_config_root, get_vds_log_root
+from vds_cli_common.version import create_version_callback
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CLIContext",
+    "DEFAULT_ENV_PATHS",
+    "ErrorHandler",
+    "ExitCodes",
+    "NullProgress",
+    "OutputManager",
+    "__version__",
+    "create_version_callback",
+    "get_shared_env_path",
+    "get_vds_cache_root",
+    "get_vds_config_root",
+    "get_vds_log_root",
+    "load_shared_env",
+]

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

@@ -0,0 +1,139 @@
+"""Common completers for VDS CLIs.
+
+This module provides shell completion functions for common arguments
+used across VDS orchestrator CLIs.
+
+Usage:
+    from vds_cli_common.completers import complete_index, complete_project
+
+    @app.command()
+    def search(
+        index: str = typer.Option(
+            "*",
+            "--index", "-i",
+            help="Index pattern",
+            autocompletion=complete_index,
+        ),
+    ):
+        pass
+"""
+
+from __future__ import annotations
+
+
+def complete_index(incomplete: str) -> list[str]:
+    """Provide common Elasticsearch index pattern suggestions.
+
+    Returns common index patterns that match the incomplete input.
+    This is static completion - doesn't query Elasticsearch for performance.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching index patterns
+    """
+    common_patterns = [
+        "logs-*",
+        "metrics-*",
+        "traces-*",
+        "filebeat-*",
+        "metricbeat-*",
+        "apm-*",
+        ".kibana*",
+        "otel-logs-*",
+        "*",
+    ]
+    return [p for p in common_patterns if p.startswith(incomplete)]
+
+
+def complete_time_field(incomplete: str) -> list[str]:
+    """Provide common time field suggestions.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching time field names
+    """
+    common_fields = [
+        "@timestamp",
+        "timestamp",
+        "time",
+        "created_at",
+        "updated_at",
+        "event.created",
+        "event_time",
+    ]
+    return [f for f in common_fields if f.startswith(incomplete)]
+
+
+def complete_project(incomplete: str) -> list[str]:
+    """Provide VDS project name suggestions.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching project names
+    """
+    projects = [
+        "lep",
+        "insurance",
+        "saving",
+        "ekyc",
+    ]
+    return [p for p in projects if p.startswith(incomplete.lower())]
+
+
+def complete_server(incomplete: str) -> list[str]:
+    """Provide Confluence server suggestions.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching server names
+    """
+    servers = [
+        "internal",
+        "external",
+    ]
+    return [s for s in servers if s.startswith(incomplete.lower())]
+
+
+def complete_output_format(incomplete: str) -> list[str]:
+    """Provide output format suggestions.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching output formats
+    """
+    formats = [
+        "json",
+        "table",
+        "csv",
+        "yaml",
+    ]
+    return [f for f in formats if f.startswith(incomplete.lower())]
+
+
+def complete_log_level(incomplete: str) -> list[str]:
+    """Provide log level suggestions.
+
+    Args:
+        incomplete: The partial input to complete
+
+    Returns:
+        List of matching log levels
+    """
+    levels = [
+        "DEBUG",
+        "INFO",
+        "WARNING",
+        "ERROR",
+        "CRITICAL",
+    ]
+    return [lvl for lvl in levels if lvl.startswith(incomplete.upper())]

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

@@ -0,0 +1,201 @@
+"""CLI Context for unified state management across VDS CLIs.
+
+This module provides CLIContext, a dataclass that handles:
+- TTY detection for adaptive output
+- Color control (flags, env vars, TTY detection)
+- Quiet mode for suppressing non-essential output
+- JSON-only mode for machine-readable output
+
+Usage:
+    @app.callback()
+    def callback(
+        ctx: typer.Context,
+        json_only: bool = typer.Option(False, "--json-only", "-j"),
+        quiet: bool = typer.Option(False, "--quiet", "-q"),
+        no_color: bool = typer.Option(False, "--no-color"),
+        color: bool = typer.Option(False, "--color"),
+    ):
+        cli_ctx = CLIContext.from_options(
+            json_only=json_only,
+            quiet=quiet,
+            no_color=no_color,
+            force_color=color,
+        )
+        ctx.obj = {"cli_ctx": cli_ctx}
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import typer
+    from rich.console import Console
+
+
+@dataclass
+class CLIContext:
+    """Unified CLI context for all VDS orchestrator CLIs.
+
+    Handles TTY detection, color preferences, output mode, and quiet mode
+    consistently across all CLIs.
+
+    Attributes:
+        json_only: Output clean JSON only (existing behavior)
+        structured_logs: Emit JSON logs to stderr
+        is_tty: Whether stdout is an interactive terminal
+        no_color: Disable colors explicitly
+        force_color: Force colors even in non-TTY
+        quiet: Suppress progress and non-essential output
+        no_input: Disable interactive prompts
+    """
+
+    # Core flags
+    json_only: bool = False
+    quiet: bool = False
+    structured_logs: bool = False
+    no_input: bool = False
+
+    # Color control
+    no_color: bool = False
+    force_color: bool = False
+
+    # Computed properties (set during initialization)
+    _is_tty: bool = field(default=False, init=False)
+    _console: Console | None = field(default=None, init=False, repr=False)
+    _err_console: Console | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Detect TTY after initialization."""
+        self._is_tty = sys.stdout.isatty()
+
+    @classmethod
+    def from_options(
+        cls,
+        *,
+        json_only: bool = False,
+        quiet: bool = False,
+        structured_logs: bool = False,
+        no_input: bool = False,
+        no_color: bool = False,
+        force_color: bool = False,
+    ) -> CLIContext:
+        """Factory method to create CLIContext from CLI options."""
+        return cls(
+            json_only=json_only,
+            quiet=quiet,
+            structured_logs=structured_logs,
+            no_input=no_input,
+            no_color=no_color,
+            force_color=force_color,
+        )
+
+    @classmethod
+    def from_typer_context(cls, ctx: typer.Context) -> CLIContext:  # type: ignore[name-defined]
+        """Get CLIContext from Typer context, or create default.
+
+        Args:
+            ctx: Typer context object
+
+        Returns:
+            CLIContext from ctx.obj if available, else default CLIContext
+        """
+        if ctx.obj is not None:
+            if isinstance(ctx.obj, CLIContext):
+                return ctx.obj
+            if isinstance(ctx.obj, dict) and "cli_ctx" in ctx.obj:
+                cli_ctx = ctx.obj["cli_ctx"]
+                if isinstance(cli_ctx, CLIContext):
+                    return cli_ctx
+        return cls()
+
+    @property
+    def is_tty(self) -> bool:
+        """Whether stdout is an interactive terminal."""
+        return self._is_tty
+
+    @property
+    def use_color(self) -> bool:
+        """Determine if colors should be used.
+
+        Precedence (highest to lowest):
+        1. --no-color flag (disables)
+        2. --color flag (enables)
+        3. FORCE_COLOR env var (enables)
+        4. NO_COLOR env var (disables)
+        5. TTY detection (enables if TTY)
+        6. json_only mode (disables)
+        """
+        # json_only always disables color
+        if self.json_only:
+            return False
+
+        # CLI flags have highest precedence
+        if self.no_color:
+            return False
+        if self.force_color:
+            return True
+
+        # Environment variables
+        if os.environ.get("FORCE_COLOR"):
+            return True
+        if os.environ.get("NO_COLOR"):
+            return False
+
+        # Default to TTY detection
+        return self._is_tty
+
+    @property
+    def use_rich_output(self) -> bool:
+        """Whether to use Rich formatting (tables, panels, etc).
+
+        Disabled when:
+        - json_only mode is active
+        - stdout is not a TTY (piped output)
+        """
+        if self.json_only:
+            return False
+        return self._is_tty
+
+    @property
+    def use_spinner(self) -> bool:
+        """Whether to show spinners for long operations."""
+        return self.use_rich_output and not self.quiet
+
+    @property
+    def use_progress(self) -> bool:
+        """Whether to show progress bars for batch operations."""
+        return self.use_rich_output and not self.quiet
+
+    @property
+    def show_hints(self) -> bool:
+        """Whether to show hints and suggestions."""
+        return not self.json_only and not self.quiet
+
+    @property
+    def console(self) -> Console:
+        """Get the stdout console with appropriate settings."""
+        if self._console is None:
+            from rich.console import Console
+
+            self._console = Console(
+                force_terminal=self.force_color if self.force_color else None,
+                no_color=not self.use_color,
+            )
+        return self._console
+
+    @property
+    def err_console(self) -> Console:
+        """Get the stderr console with appropriate settings."""
+        if self._err_console is None:
+            from rich.console import Console
+
+            self._err_console = Console(
+                stderr=True,
+                force_terminal=self.force_color if self.force_color else None,
+                no_color=not self.use_color,
+            )
+        return self._err_console