@ngocsangairvds/vsaf 3.1.27 → 3.2.1

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

@@ -0,0 +1,119 @@
+"""Shared environment loader for VDS scripts."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from vds_cli_common.paths import get_default_env_paths, get_shared_env_path
+
+DEFAULT_ENV_PATHS = get_default_env_paths()
+
+DEFAULT_AUDIT_ENV_DEFAULTS: tuple[tuple[str, str], ...] = (
+    ("VDS_AUDIT_STATE_DSN", "postgresql://localhost:5432/vds_audit"),
+    ("VDS_AUDIT_LLM__AGENT_RUNTIME_MODE", "pydanticai"),
+    ("VDS_AUDIT_LLM__DSPY_RUNTIME_RETRY_ATTEMPTS", "3"),
+    ("VDS_AUDIT_LLM__DSPY_RUNTIME_RETRY_BACKOFF_SECONDS", "0"),
+)
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if value and value[0] == value[-1] and value[0] in {"'", '"'}:
+            value = value[1:-1]
+        if key:
+            values[key] = value
+    return values
+
+
+def _render_default_env_content(defaults: tuple[tuple[str, str], ...]) -> str:
+    lines = [
+        "# Auto-generated default environment for VDS scripts.",
+        "# Safe defaults only; replace values for your environment as needed.",
+        "",
+    ]
+    for key, value in defaults:
+        lines.append(f"{key}={value}")
+    lines.append("")
+    lines.append("# Optional credentials")
+    lines.append("# ANTHROPIC_API_KEY=")
+    lines.append("# OPENAI_API_KEY=")
+    lines.append("# VDS_USERNAME=")
+    lines.append("# VDS_PASSWORD=")
+    lines.append("# VDS_AUDIT_LANGGRAPH__POSTGRES_DSN=postgresql://user:password@host:5432/database")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def ensure_shared_env(
+    path: Path | None = None,
+    *,
+    defaults: tuple[tuple[str, str], ...] = DEFAULT_AUDIT_ENV_DEFAULTS,
+) -> Path:
+    """Ensure shared env file exists and contains required default keys.
+
+    Existing values are never overwritten.
+    """
+    env_path = path or get_shared_env_path()
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if not env_path.exists():
+        env_path.write_text(_render_default_env_content(defaults), encoding="utf-8")
+        return env_path
+
+    existing = _parse_env_file(env_path)
+    missing = [(key, value) for key, value in defaults if key not in existing]
+    if not missing:
+        return env_path
+
+    with env_path.open("a", encoding="utf-8") as handle:
+        handle.write("\n# Added missing VDS defaults\n")
+        for key, value in missing:
+            handle.write(f"{key}={value}\n")
+    return env_path
+
+
+def load_shared_env(
+    path: Path | None = None,
+    override: bool = False,
+    *,
+    ensure_defaults: bool = True,
+    extra_paths: tuple[Path, ...] | None = None,
+) -> dict[str, str]:
+    """Load VDS env files into os.environ."""
+    primary_path = path or get_shared_env_path()
+    if ensure_defaults:
+        ensure_shared_env(primary_path)
+
+    env_paths = (path,) if path is not None else get_default_env_paths()
+    if extra_paths:
+        env_paths = tuple(env_paths) + tuple(extra_paths)
+    merged: dict[str, str] = {}
+    for env_path in env_paths:
+        for key, value in _parse_env_file(env_path).items():
+            merged.setdefault(key, value)
+    for key, value in merged.items():
+        if override or key not in os.environ:
+            os.environ[key] = value
+    return merged
+
+
+__all__ = [
+    "DEFAULT_AUDIT_ENV_DEFAULTS",
+    "DEFAULT_ENV_PATHS",
+    "ensure_shared_env",
+    "load_shared_env",
+]

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

@@ -0,0 +1,318 @@
+"""Error handling for VDS CLIs.
+
+This module provides:
+- ExitCodes: Standard exit codes for all VDS CLIs
+- ErrorHandler: Unified error handling with suggestions and hints
+
+Usage:
+    from vds_cli_common import ErrorHandler, ExitCodes
+
+    handler = ErrorHandler(output_manager, valid_commands=["search", "count"])
+
+    try:
+        result = operation()
+    except PermissionError:
+        handler.handle_permission_error("Access denied", required_role="admin")
+"""
+
+from __future__ import annotations
+
+import difflib
+from enum import IntEnum
+from typing import TYPE_CHECKING, NoReturn
+
+import typer
+
+from vds_cli_common.paths import get_shared_env_path
+
+if TYPE_CHECKING:
+    from .output import OutputManager
+
+
+class ExitCodes(IntEnum):
+    """Standard exit codes for all VDS CLIs.
+
+    These codes provide consistent exit status across all CLIs,
+    making it easier to handle errors in scripts and automation.
+    """
+
+    SUCCESS = 0
+    """Operation completed successfully."""
+
+    GENERAL_ERROR = 1
+    """Unspecified error occurred."""
+
+    USAGE_ERROR = 2
+    """Invalid arguments or bad command."""
+
+    CONFIG_ERROR = 3
+    """Missing environment variables or bad configuration."""
+
+    AUTH_ERROR = 4
+    """Invalid credentials or expired token."""
+
+    PERMISSION_ERROR = 5
+    """403 Forbidden - insufficient rights."""
+
+    NOT_FOUND_ERROR = 6
+    """404 Not Found - resource doesn't exist."""
+
+    NETWORK_ERROR = 7
+    """Connection failed or timeout."""
+
+    VALIDATION_ERROR = 8
+    """Invalid input data."""
+
+
+class ErrorHandler:
+    """Unified error handling for VDS CLIs.
+
+    Provides:
+    - Consistent error formatting
+    - Typo suggestions for commands
+    - Actionable hints for common errors
+    - Proper exit codes
+
+    Args:
+        output: OutputManager instance for error output
+        valid_commands: List of valid commands for typo suggestions
+    """
+
+    def __init__(
+        self,
+        output: OutputManager,
+        valid_commands: list[str] | None = None,
+    ) -> None:
+        """Initialize ErrorHandler.
+
+        Args:
+            output: OutputManager for error output
+            valid_commands: Optional list of valid commands for suggestions
+        """
+        self.output = output
+        self.valid_commands = valid_commands or []
+
+    def suggest_command(self, typo: str, cutoff: float = 0.6) -> str | None:
+        """Suggest a valid command based on fuzzy matching.
+
+        Args:
+            typo: The mistyped command
+            cutoff: Minimum similarity ratio (0.0 to 1.0)
+
+        Returns:
+            Best matching command or None if no match found
+        """
+        matches = difflib.get_close_matches(
+            typo,
+            self.valid_commands,
+            n=1,
+            cutoff=cutoff,
+        )
+        return matches[0] if matches else None
+
+    def handle_unknown_command(self, command: str) -> NoReturn:
+        """Handle unknown command with suggestion.
+
+        Args:
+            command: The unknown command
+
+        Raises:
+            typer.Exit: Always exits with USAGE_ERROR
+        """
+        suggestion = self.suggest_command(command)
+
+        hint = None
+        if suggestion:
+            hint = f"Did you mean: [cyan]{suggestion}[/cyan]?"
+        elif self.valid_commands:
+            available = ", ".join(self.valid_commands[:5])
+            hint = f"Available commands: {available}"
+
+        self.output.output_error(
+            f"Unknown command: '{command}'",
+            hint=hint,
+        )
+        raise typer.Exit(ExitCodes.USAGE_ERROR)
+
+    def handle_config_error(
+        self,
+        message: str,
+        *,
+        missing_vars: list[str] | None = None,
+        config_path: str | None = None,
+    ) -> NoReturn:
+        """Handle configuration error with guidance.
+
+        Args:
+            message: Error message
+            missing_vars: List of missing environment variable names
+            config_path: Path to configuration file
+
+        Raises:
+            typer.Exit: Always exits with CONFIG_ERROR
+        """
+        resolved_config_path = config_path or str(get_shared_env_path())
+        details: dict[str, str] = {"config_file": resolved_config_path}
+        if missing_vars:
+            details["missing_variables"] = ", ".join(missing_vars)
+
+        self.output.output_error(
+            message,
+            hint=f"Check your configuration at {resolved_config_path}",
+            details=details,
+        )
+        raise typer.Exit(ExitCodes.CONFIG_ERROR)
+
+    def handle_auth_error(
+        self,
+        message: str,
+        *,
+        service: str = "API",
+    ) -> NoReturn:
+        """Handle authentication error.
+
+        Args:
+            message: Error message
+            service: Name of the service (for hint)
+
+        Raises:
+            typer.Exit: Always exits with AUTH_ERROR
+        """
+        self.output.output_error(
+            message,
+            hint=f"Verify your {service} credentials in {get_shared_env_path()}",
+            details={"service": service},
+        )
+        raise typer.Exit(ExitCodes.AUTH_ERROR)
+
+    def handle_permission_error(
+        self,
+        message: str,
+        *,
+        required_role: str | None = None,
+        current_role: str | None = None,
+    ) -> NoReturn:
+        """Handle permission error with role information.
+
+        Args:
+            message: Error message
+            required_role: Role required for the operation
+            current_role: User's current role
+
+        Raises:
+            typer.Exit: Always exits with PERMISSION_ERROR
+        """
+        details: dict[str, str] = {}
+        if required_role:
+            details["required_role"] = required_role
+        if current_role:
+            details["current_role"] = current_role
+
+        hint = "Request elevated access from your administrator"
+        if required_role:
+            hint = f"Required role: {required_role}. Contact admin for access."
+
+        self.output.output_error(message, hint=hint, details=details)
+        raise typer.Exit(ExitCodes.PERMISSION_ERROR)
+
+    def handle_network_error(
+        self,
+        message: str,
+        *,
+        url: str | None = None,
+    ) -> NoReturn:
+        """Handle network/connection error.
+
+        Args:
+            message: Error message
+            url: URL that failed to connect
+
+        Raises:
+            typer.Exit: Always exits with NETWORK_ERROR
+        """
+        hints = [
+            "Check your VPN connection",
+            "Verify the service URL is correct",
+            "Ensure network connectivity",
+        ]
+
+        details: dict[str, str] = {}
+        if url:
+            details["url"] = url
+
+        self.output.output_error(
+            message,
+            hint=" | ".join(hints),
+            details=details,
+        )
+        raise typer.Exit(ExitCodes.NETWORK_ERROR)
+
+    def handle_not_found(
+        self,
+        resource_type: str,
+        resource_id: str,
+    ) -> NoReturn:
+        """Handle resource not found error.
+
+        Args:
+            resource_type: Type of resource (e.g., "Index", "Page")
+            resource_id: ID or name of the resource
+
+        Raises:
+            typer.Exit: Always exits with NOT_FOUND_ERROR
+        """
+        self.output.output_error(
+            f"{resource_type} not found: '{resource_id}'",
+            hint=f"Verify the {resource_type.lower()} exists and you have access",
+        )
+        raise typer.Exit(ExitCodes.NOT_FOUND_ERROR)
+
+    def handle_validation_error(
+        self,
+        message: str,
+        *,
+        field: str | None = None,
+        expected: str | None = None,
+    ) -> NoReturn:
+        """Handle input validation error.
+
+        Args:
+            message: Error message
+            field: Field that failed validation
+            expected: Expected value or format
+
+        Raises:
+            typer.Exit: Always exits with VALIDATION_ERROR
+        """
+        details: dict[str, str] = {}
+        if field:
+            details["field"] = field
+        if expected:
+            details["expected"] = expected
+
+        self.output.output_error(
+            message,
+            hint="Check your input and try again",
+            details=details,
+        )
+        raise typer.Exit(ExitCodes.VALIDATION_ERROR)
+
+    def handle_general_error(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        details: dict[str, str] | None = None,
+    ) -> NoReturn:
+        """Handle general error with optional hint and details.
+
+        Args:
+            message: Error message
+            hint: Optional hint for resolution
+            details: Optional additional details
+
+        Raises:
+            typer.Exit: Always exits with GENERAL_ERROR
+        """
+        self.output.output_error(message, hint=hint, details=details)
+        raise typer.Exit(ExitCodes.GENERAL_ERROR)