@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/config.py

@@ -0,0 +1,171 @@
+"""Strongly-typed Bitbucket settings using pydantic-settings (consistent with VDS orchestrators)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_PROJECT_ROOT = Path(__file__).resolve().parents[3]
+_SCRIPTS_DIR = _PROJECT_ROOT.parent
+
+DEFAULT_ENV_PATHS = (
+    Path.home() / ".vds" / ".env",
+    _SCRIPTS_DIR / ".env",
+)
+
+_REQUIRED_KEYS: tuple[str, ...] = (
+    "VDS_USERNAME",
+    "VDS_PASSWORD",
+    "BITBUCKET_TOKEN",
+)
+
+_OPTIONAL_KEYS: tuple[str, ...] = (
+    "BITBUCKET_BASE_URL",
+    "BITBUCKET_CLOUD_WORKSPACE",
+    "BITBUCKET_MODE",
+    "BITBUCKET_MAX_RETRIES",
+    "BITBUCKET_RETRY_BACKOFF",
+)
+
+
+class SettingsError(RuntimeError):
+    """Raised when the environment configuration cannot be loaded."""
+
+
+class BitbucketSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=None, env_prefix="", case_sensitive=True, populate_by_name=True)
+
+    username: str | None = Field(default=None, alias="VDS_USERNAME")
+    password: str | None = Field(default=None, alias="VDS_PASSWORD")
+
+    # Bitbucket Server/DC URL (for on-premise installations)
+    base_url: str = Field(default="http://bitbucket.digital.vn", alias="BITBUCKET_BASE_URL")
+
+    # Bitbucket Cloud workspace (for cloud.bitbucket.com)
+    cloud_workspace: str | None = Field(default=None, alias="BITBUCKET_CLOUD_WORKSPACE")
+
+    # Optional: Personal Access Token for Bitbucket Cloud or Server
+    token: str | None = Field(default=None, alias="BITBUCKET_TOKEN")
+
+    # Default mode: 'cloud' or 'server'
+    mode: str = Field(default="server", alias="BITBUCKET_MODE")
+
+    # Retry configuration
+    max_retries: int = Field(default=3, alias="BITBUCKET_MAX_RETRIES")
+    retry_backoff_factor: float = Field(default=1.0, alias="BITBUCKET_RETRY_BACKOFF")
+
+    def require_basic_or_token(self) -> None:
+        if not ((self.username and self.password) or self.token):
+            raise ValueError("Missing credentials: set VDS_USERNAME/VDS_PASSWORD or BITBUCKET_TOKEN")
+
+    @property
+    def is_cloud_mode(self) -> bool:
+        return self.mode.lower() == "cloud"
+
+    @property
+    def is_server_mode(self) -> bool:
+        return self.mode.lower() == "server"
+
+    def get_url(self) -> str:
+        """Get appropriate URL based on mode."""
+        if self.is_cloud_mode:
+            if not self.cloud_workspace:
+                raise ValueError("BITBUCKET_CLOUD_WORKSPACE is required for cloud mode")
+            return f"https://api.bitbucket.org/workspace/{self.cloud_workspace}"
+        return str(self.base_url)
+
+    def get_auth_kwargs(self) -> dict[str, str]:
+        """Get authentication kwargs for atlassian-python-api."""
+        if self.token:
+            return {"token": self.token}
+        elif self.username and self.password:
+            return {"username": self.username, "password": self.password}
+        else:
+            raise ValueError("No valid authentication credentials available")
+
+
+@dataclass(frozen=True)
+class EnvSnapshot:
+    """A snapshot of relevant environment variables."""
+
+    values: Mapping[str, str]
+    source: Path | str | None
+
+
+def _parse_env_file(env_path: Path) -> dict[str, str]:
+    if not env_path.exists():
+        return {}
+
+    result: dict[str, str] = {}
+    for raw_line in env_path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, raw_value = line.split("=", 1)
+        key = key.strip()
+        value = raw_value.strip().strip('"').strip("'")
+        if key:
+            result[key] = value
+    return result
+
+
+def _merge_env_sources(*snapshots: EnvSnapshot) -> dict[str, str]:
+    merged: dict[str, str] = {}
+    for snapshot in snapshots:
+        merged.update(snapshot.values)
+    return merged
+
+
+def _filter_keys(source: Mapping[str, str]) -> dict[str, str]:
+    relevant_keys = set(_REQUIRED_KEYS + _OPTIONAL_KEYS)
+    return {key: value for key, value in source.items() if key in relevant_keys}
+
+
+def _resolve_env_paths(env_path: Path | None) -> Iterable[Path]:
+    if env_path is not None:
+        return (env_path,)
+    return DEFAULT_ENV_PATHS
+
+
+def load_settings(
+    *,
+    env_path: Path | None = None,
+    overrides: Mapping[str, str] | None = None,
+    strict: bool = False,
+) -> BitbucketSettings:
+    """Load orchestrator settings from the environment and optional .env file."""
+
+    snapshots = []
+    for candidate in _resolve_env_paths(env_path):
+        snapshots.append(
+            EnvSnapshot(
+                values=_filter_keys(_parse_env_file(candidate)), source=candidate if candidate.exists() else None
+            )
+        )
+
+    snapshots.append(EnvSnapshot(values=_filter_keys(os.environ), source="os.environ"))
+
+    if overrides:
+        snapshots.append(EnvSnapshot(values=_filter_keys(overrides), source="overrides"))
+
+    merged = _merge_env_sources(*snapshots)
+
+    try:
+        settings = BitbucketSettings.model_validate(merged)
+    except Exception as exc:
+        raise SettingsError(str(exc)) from exc
+
+    if strict:
+        settings.require_basic_or_token()
+
+    return settings
+
+
+__all__ = ["BitbucketSettings", "SettingsError", "load_settings", "DEFAULT_ENV_PATHS"]

package/tools/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/errors.py

@@ -0,0 +1,67 @@
+"""Bitbucket-specific error types (consistent with VDS orchestrators)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class BitbucketClientError(RuntimeError):
+    """Base class for Bitbucket client errors."""
+
+    def __init__(self, message: str, *, context: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.context = context or {}
+
+
+class BitbucketAuthError(BitbucketClientError):
+    """Raised when authentication fails (401/403)."""
+
+    pass
+
+
+class BitbucketRateLimitedError(BitbucketClientError):
+    """Raised when rate limited by Bitbucket (429)."""
+
+    def __init__(
+        self, message: str, *, retry_after: float | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.retry_after = retry_after
+
+
+class BitbucketNotFoundError(BitbucketClientError):
+    """Raised when a resource is not found (404)."""
+
+    pass
+
+
+class BitbucketConflictError(BitbucketClientError):
+    """Raised when there's a conflict (409)."""
+
+    pass
+
+
+class BitbucketResponseError(BitbucketClientError):
+    """Raised for other HTTP errors (4xx/5xx)."""
+
+    def __init__(
+        self, message: str, *, status_code: int | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.status_code = status_code
+
+
+class BitbucketTransportError(BitbucketClientError):
+    """Raised for network/transport issues."""
+
+    pass
+
+
+class BitbucketRetryError(BitbucketClientError):
+    """Raised when retry attempts are exhausted."""
+
+    def __init__(
+        self, message: str, *, attempts: int | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.attempts = attempts

package/tools/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/factory.py

@@ -0,0 +1,185 @@
+"""Factory functions for creating Bitbucket clients with automatic credential loading.
+
+This module provides convenient factory functions that automatically load credentials
+from the shared VDS environment loader (`vds_cli_common.env`), simplifying client instantiation.
+
+Usage:
+    from vds_bitbucket_orchestrator import create_client, create_async_client
+
+    # Create a sync client with auto-loaded credentials
+    client = create_client()
+
+    # Create a sync client with explicit mode
+    client = create_client(mode="cloud")
+
+    # Create an async client for non-blocking operations
+    async_client = create_async_client()
+
+References:
+    - FR-21.2.2: Factory functions that load credentials from the shared VDS env file automatically
+    - FR-21.2.3: AsyncBitbucketClient using asyncio.to_thread()
+    - TSK-223: Factory functions for Bitbucket
+    - TSK-225: Async Bitbucket wrapper
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from vds_cli_common.paths import get_shared_env_path
+
+from .async_client import AsyncBitbucketClient
+from .client import BitbucketClient
+from .config import load_settings
+
+# Default path for the shared VDS environment file
+DEFAULT_VDS_ENV_PATH = get_shared_env_path()
+
+
+def create_client(
+    *,
+    mode: Literal["server", "cloud"] | None = None,
+    env_path: Path | None = None,
+    timeout: int | None = 30,
+    strict: bool = True,
+) -> BitbucketClient:
+    """Create a Bitbucket client with auto-loaded credentials from the shared VDS env file.
+
+    This factory function simplifies client creation by automatically loading
+    credentials from the standard VDS environment file location.
+
+    Args:
+        mode: Bitbucket mode - 'server' (default) for Bitbucket Server/DC,
+              'cloud' for Bitbucket Cloud. If None, uses value from env file
+              or defaults to 'server'.
+        env_path: Optional custom path to .env file. Defaults to the shared VDS env path.
+        timeout: HTTP timeout in seconds (default: 30).
+        strict: If True (default), validates that credentials are present.
+                Set to False to allow creating client without validation.
+
+    Returns:
+        BitbucketClient: Configured Bitbucket client instance.
+
+    Raises:
+        ValueError: If strict=True and credentials are missing.
+        SettingsError: If environment configuration cannot be loaded.
+
+    Example:
+        # Simple usage with defaults (server mode, shared VDS env path)
+        client = create_client()
+
+        # Cloud mode
+        client = create_client(mode="cloud")
+
+        # Custom env file
+        client = create_client(env_path=Path("/custom/path/.env"))
+
+        # Non-strict mode (for testing)
+        client = create_client(strict=False)
+
+    Note:
+        The client implements BitbucketFullClient protocol, enabling type-safe
+        dependency injection:
+
+            def audit_repo(client: BitbucketFullClient, project: str, repo: str):
+                return client.get_repository(project, repo)
+
+            client = create_client()
+            result = audit_repo(client, "INS", "insurance-core")
+    """
+    # Build overrides dict for mode if specified
+    overrides: dict[str, str] | None = None
+    if mode is not None:
+        overrides = {"BITBUCKET_MODE": mode}
+
+    # Load settings from env file with optional overrides
+    settings = load_settings(
+        env_path=env_path or DEFAULT_VDS_ENV_PATH,
+        overrides=overrides,
+        strict=strict,
+    )
+
+    # Create and return the client
+    return BitbucketClient(settings, timeout=timeout)
+
+
+def create_async_client(
+    *,
+    mode: Literal["server", "cloud"] | None = None,
+    env_path: Path | None = None,
+    timeout: int | None = 30,
+    strict: bool = True,
+) -> AsyncBitbucketClient:
+    """Create an async Bitbucket client with auto-loaded credentials from the shared VDS env file.
+
+    This factory function creates an AsyncBitbucketClient that wraps the synchronous
+    BitbucketClient methods using asyncio.to_thread() for non-blocking execution.
+
+    Args:
+        mode: Bitbucket mode - 'server' (default) for Bitbucket Server/DC,
+              'cloud' for Bitbucket Cloud. If None, uses value from env file
+              or defaults to 'server'.
+        env_path: Optional custom path to .env file. Defaults to the shared VDS env path.
+        timeout: HTTP timeout in seconds (default: 30).
+        strict: If True (default), validates that credentials are present.
+                Set to False to allow creating client without validation.
+
+    Returns:
+        AsyncBitbucketClient: Async Bitbucket client instance.
+
+    Raises:
+        ValueError: If strict=True and credentials are missing.
+        SettingsError: If environment configuration cannot be loaded.
+
+    Example:
+        import asyncio
+        from vds_bitbucket_orchestrator import create_async_client
+
+        async def audit_repos():
+            client = create_async_client()
+
+            # Non-blocking API calls
+            repos = await client.list_repositories("INS")
+
+            # Concurrent API calls
+            repo_info, branches = await asyncio.gather(
+                client.get_repository("INS", "insurance-core"),
+                client.get_branches("INS", "insurance-core"),
+            )
+            return repos, repo_info, branches
+
+        # Run the async function
+        result = asyncio.run(audit_repos())
+
+    Note:
+        The AsyncBitbucketClient implements the same protocols as BitbucketClient:
+        - BitbucketRepositoryClient
+        - BitbucketBranchClient
+        - BitbucketCodeClient
+        - BitbucketFullClient
+
+        The underlying HTTP calls are synchronous but run in a thread pool,
+        preventing them from blocking the async event loop.
+    """
+    # Build overrides dict for mode if specified
+    overrides: dict[str, str] | None = None
+    if mode is not None:
+        overrides = {"BITBUCKET_MODE": mode}
+
+    # Load settings from env file with optional overrides
+    settings = load_settings(
+        env_path=env_path or DEFAULT_VDS_ENV_PATH,
+        overrides=overrides,
+        strict=strict,
+    )
+
+    # Create and return the async client
+    return AsyncBitbucketClient(settings, timeout=timeout)
+
+
+__all__ = [
+    "create_client",
+    "create_async_client",
+    "DEFAULT_VDS_ENV_PATH",
+]

package/tools/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/protocols.py

@@ -0,0 +1,244 @@
+"""Protocol interfaces for Bitbucket client dependency injection and testability.
+
+This module defines Protocol classes that enable:
+- Dependency injection for testing with mock implementations
+- Type-safe interfaces for different Bitbucket API capabilities
+- Separation of concerns between repository, branch, and code operations
+
+Usage:
+    from vds_bitbucket_orchestrator.protocols import (
+        BitbucketRepositoryClient,
+        BitbucketBranchClient,
+        BitbucketCodeClient,
+        BitbucketFullClient,
+    )
+
+    def audit_repository(client: BitbucketRepositoryClient, project_key: str) -> dict:
+        repos = client.list_repositories(project_key)
+        return {"repositories": repos}
+
+References:
+    - FR-21.2.1: Protocol classes for dependency injection and testability
+    - TSK-222: Protocol interfaces for Bitbucket
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class BitbucketRepositoryClient(Protocol):
+    """Protocol for Bitbucket repository operations.
+
+    This protocol defines the interface for repository-related operations
+    including listing, getting, creating, and managing repositories.
+
+    Implementations:
+        - BitbucketClient: Full implementation using atlassian-python-api
+        - Mock implementations for testing
+    """
+
+    def list_projects(self, limit: int = 25) -> list[dict[str, Any]]:
+        """List all projects.
+
+        Args:
+            limit: Maximum number of projects to return (default: 25)
+
+        Returns:
+            List of project dictionaries with keys like 'key', 'name', 'description'
+        """
+        ...
+
+    def get_project(self, project_key: str) -> dict[str, Any]:
+        """Get project information.
+
+        Args:
+            project_key: The project key (e.g., 'INS', 'LEP')
+
+        Returns:
+            Project dictionary with metadata
+        """
+        ...
+
+    def list_repositories(self, project_key: str, limit: int = 25) -> list[dict[str, Any]]:
+        """List repositories in a project.
+
+        Args:
+            project_key: The project key
+            limit: Maximum number of repositories to return (default: 25)
+
+        Returns:
+            List of repository dictionaries with keys like 'slug', 'name', 'description'
+        """
+        ...
+
+    def get_repository(self, project_key: str, repository_slug: str) -> dict[str, Any]:
+        """Get repository information.
+
+        Args:
+            project_key: The project key
+            repository_slug: The repository slug
+
+        Returns:
+            Repository dictionary with metadata
+        """
+        ...
+
+
+@runtime_checkable
+class BitbucketBranchClient(Protocol):
+    """Protocol for Bitbucket branch and permission operations.
+
+    This protocol defines the interface for branch-related operations
+    including listing branches, managing permissions, and branch restrictions.
+
+    Implementations:
+        - BitbucketClient: Full implementation using atlassian-python-api
+        - Mock implementations for testing
+    """
+
+    def get_branches(
+        self,
+        project_key: str,
+        repository_slug: str,
+        filter: str = "",
+        limit: int = 99999,
+        details: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Get branches from a repository.
+
+        Args:
+            project_key: The project key
+            repository_slug: The repository slug
+            filter: Optional filter string for branch names
+            limit: Maximum number of branches to return (default: 99999)
+            details: Whether to include branch details (default: True)
+
+        Returns:
+            List of branch dictionaries with metadata
+        """
+        ...
+
+    def list_branch_permissions(
+        self,
+        project_key: str,
+        repository_slug: str | None = None,
+        start: int = 0,
+        limit: int = 25,
+    ) -> list[dict[str, Any]]:
+        """List branch permissions (server and cloud).
+
+        Args:
+            project_key: The project key
+            repository_slug: Optional repository slug (required for cloud mode)
+            start: Start index for pagination (default: 0)
+            limit: Maximum number of permissions to return (default: 25)
+
+        Returns:
+            Normalized list of branch restriction objects
+        """
+        ...
+
+
+@runtime_checkable
+class BitbucketCodeClient(Protocol):
+    """Protocol for Bitbucket code and commit operations.
+
+    This protocol defines the interface for code-related operations
+    including file content retrieval and commit history.
+
+    Implementations:
+        - BitbucketClient: Full implementation using atlassian-python-api
+        - Mock implementations for testing
+
+    Note:
+        Method names match the atlassian-python-api SDK:
+        - get_content_of_file() (not get_file_content)
+        - get_commits() (not list_commits)
+    """
+
+    def get_content_of_file(
+        self,
+        project_key: str,
+        repository_slug: str,
+        filename: str,
+        at: str | None = None,
+        markup: str | None = None,
+    ) -> str:
+        """Get raw content of a file from repository.
+
+        Args:
+            project_key: The project key
+            repository_slug: The repository slug
+            filename: Path to the file in the repository
+            at: Optional commit hash, branch, or tag to retrieve file at
+            markup: Optional markup format for rendering
+
+        Returns:
+            File content as string
+        """
+        ...
+
+    def get_commits(
+        self,
+        project_key: str,
+        repository_slug: str,
+        hash_oldest: str | None = None,
+        hash_newest: str | None = None,
+        limit: int = 99999,
+    ) -> list[dict[str, Any]]:
+        """Get commit list from repository.
+
+        Args:
+            project_key: The project key
+            repository_slug: The repository slug
+            hash_oldest: Optional oldest commit hash to start from
+            hash_newest: Optional newest commit hash to end at
+            limit: Maximum number of commits to return (default: 99999)
+
+        Returns:
+            List of commit dictionaries with metadata
+        """
+        ...
+
+
+@runtime_checkable
+class BitbucketFullClient(BitbucketRepositoryClient, BitbucketBranchClient, BitbucketCodeClient, Protocol):
+    """Combined protocol for full Bitbucket client capabilities.
+
+    This protocol is a union of all Bitbucket client protocols:
+    - BitbucketRepositoryClient: Repository operations
+    - BitbucketBranchClient: Branch and permission operations
+    - BitbucketCodeClient: Code and commit operations
+
+    Use this protocol when you need access to all Bitbucket capabilities.
+    For more focused interfaces, use the individual protocols.
+
+    Implementations:
+        - BitbucketClient: Full implementation using atlassian-python-api
+
+    Example:
+        def full_audit(client: BitbucketFullClient, project_key: str, repo_slug: str):
+            # Repository operations
+            repo = client.get_repository(project_key, repo_slug)
+
+            # Branch operations
+            permissions = client.list_branch_permissions(project_key, repo_slug)
+
+            # Code operations
+            readme = client.get_content_of_file(project_key, repo_slug, "README.md")
+            commits = client.get_commits(project_key, repo_slug, limit=10)
+
+            return {"repo": repo, "permissions": permissions, "readme": readme, "commits": commits}
+    """
+
+    pass
+
+
+__all__ = [
+    "BitbucketRepositoryClient",
+    "BitbucketBranchClient",
+    "BitbucketCodeClient",
+    "BitbucketFullClient",
+]

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

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SRC_PATH = Path(__file__).resolve().parents[1] / "src"
+if str(SRC_PATH) not in sys.path:
+    sys.path.insert(0, str(SRC_PATH))