@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/protocols.py

@@ -1,244 +0,0 @@
-"""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__ = [
-    "BitbucketBranchClient",
-    "BitbucketCodeClient",
-    "BitbucketFullClient",
-    "BitbucketRepositoryClient",
-]

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/src/vds_bitbucket_orchestrator/repo_ops.py

@@ -1,325 +0,0 @@
-"""Repository clone and archive operations (git subprocess + REST archive)."""
-
-from __future__ import annotations
-
-import re
-import shutil
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-from urllib.parse import urlparse
-
-import structlog
-
-if TYPE_CHECKING:
-    from .client import BitbucketClient
-
-log = structlog.get_logger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Data models
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class RepoRef:
-    """Parsed repository reference."""
-
-    project_key: str
-    repo_slug: str
-    source_format: str  # "shorthand" | "browse_url" | "clone_url" | "ssh_url"
-
-
-@dataclass(frozen=True)
-class CloneResult:
-    """Result of a clone/pull operation."""
-
-    path: Path
-    operation: str  # "clone" | "pull" | "reclone"
-    branch: str
-    ref: RepoRef
-
-
-@dataclass(frozen=True)
-class ArchiveResult:
-    """Result of an archive operation."""
-
-    archive_path: Path
-    format: str  # "zip" | "tar.gz" | "tar" | "tgz"
-    size_bytes: int
-    method: str  # "rest_api" | "local_zip"
-    ref: RepoRef
-
-
-# ---------------------------------------------------------------------------
-# URL Parsing
-# ---------------------------------------------------------------------------
-
-# Pattern 1: PROJECT/repo (shorthand — no scheme, single slash)
-_RE_SHORTHAND = re.compile(r"^([A-Za-z0-9_-]+)/([A-Za-z0-9._-]+)$")
-
-# Pattern 2: http(s)://host/projects/PROJECT/repos/REPO/browse[?...]
-_RE_BROWSE = re.compile(r"/projects/([^/]+)/repos/([^/]+)")
-
-# Pattern 3: http(s)://host/scm/PROJECT/REPO.git
-_RE_CLONE = re.compile(r"/scm/([^/]+)/([^/]+?)(?:\.git)?$")
-
-# Pattern 4: ssh://git@host[:port]/PROJECT/REPO.git
-_RE_SSH = re.compile(r"ssh://[^/]+/([^/]+)/([^/]+?)(?:\.git)?$")
-
-
-def parse_repo_identifier(identifier: str) -> RepoRef:
-    """Parse a repository identifier into a RepoRef.
-
-    Accepts:
-      - PROJECT/repo (shorthand)
-      - http(s)://host/projects/PROJECT/repos/REPO/browse
-      - http(s)://host/scm/PROJECT/REPO.git
-      - ssh://git@host[:port]/PROJECT/REPO.git
-    """
-    cleaned = identifier.strip()
-
-    m = _RE_SHORTHAND.match(cleaned)
-    if m:
-        return RepoRef(project_key=m.group(1), repo_slug=m.group(2), source_format="shorthand")
-
-    for pattern, fmt in [
-        (_RE_BROWSE, "browse_url"),
-        (_RE_CLONE, "clone_url"),
-        (_RE_SSH, "ssh_url"),
-    ]:
-        m = pattern.search(cleaned)
-        if m:
-            return RepoRef(project_key=m.group(1), repo_slug=m.group(2), source_format=fmt)
-
-    msg = (
-        f"Cannot parse repository identifier: {identifier!r}\n"
-        "Expected formats:\n"
-        "  PROJECT/repo\n"
-        "  http://host/projects/PROJECT/repos/REPO/browse\n"
-        "  http://host/scm/PROJECT/REPO.git\n"
-        "  ssh://git@host/PROJECT/REPO.git"
-    )
-    raise ValueError(msg)
-
-
-def build_clone_url(
-    ref: RepoRef,
-    server_url: str,
-    username: str | None = None,
-    token: str | None = None,
-) -> str:
-    """Build an authenticated git clone URL from a RepoRef and server settings."""
-    parsed = urlparse(server_url)
-    scheme = parsed.scheme or "http"
-    host = parsed.netloc or parsed.path
-
-    if token:
-        auth = f"x-token-auth:{token}"
-    elif username:
-        auth = username
-    else:
-        auth = None
-
-    if auth:
-        return f"{scheme}://{auth}@{host}/scm/{ref.project_key}/{ref.repo_slug}.git"
-    return f"{scheme}://{host}/scm/{ref.project_key}/{ref.repo_slug}.git"
-
-
-def default_clone_dir(ref: RepoRef, cache_root: Path) -> Path:
-    """Return the standard VDS cache path for a cloned repo."""
-    return cache_root / "repos" / f"{ref.project_key}-project" / ref.repo_slug
-
-
-# ---------------------------------------------------------------------------
-# Clone
-# ---------------------------------------------------------------------------
-
-
-def clone_repo(
-    ref: RepoRef,
-    clone_url: str,
-    target_dir: Path,
-    *,
-    branch: str | None = None,
-    shallow: bool = False,
-    force_reclone: bool = False,
-) -> CloneResult:
-    """Clone or pull a repository.
-
-    - If target exists and has .git: ``git pull --ff-only``
-    - If ``force_reclone``: remove and re-clone
-    - Otherwise: fresh ``git clone``
-    """
-    target = Path(target_dir)
-
-    if force_reclone and target.exists():
-        shutil.rmtree(target)
-        log.info("reclone_removed_existing", path=str(target))
-
-    if target.exists() and (target / ".git").is_dir():
-        cmd = ["git", "-C", str(target), "pull", "--ff-only"]
-        result = subprocess.run(cmd, capture_output=True, text=True, check=False)
-        if result.returncode != 0:
-            log.error("git_pull_failed", stderr=result.stderr.strip())
-            raise RuntimeError(f"git pull failed: {result.stderr.strip()}")
-        log.info("pull_complete", path=str(target))
-        return CloneResult(
-            path=target,
-            operation="pull",
-            branch=branch or "HEAD",
-            ref=ref,
-        )
-
-    target.parent.mkdir(parents=True, exist_ok=True)
-    cmd = ["git", "clone"]
-    if branch:
-        cmd += ["--branch", branch]
-    if shallow:
-        cmd += ["--depth", "1"]
-    cmd += [clone_url, str(target)]
-
-    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
-    if result.returncode != 0:
-        # Clean up partial clone
-        if target.exists():
-            shutil.rmtree(target, ignore_errors=True)
-        log.error("git_clone_failed", stderr=result.stderr.strip())
-        raise RuntimeError(f"git clone failed: {result.stderr.strip()}")
-
-    log.info("clone_complete", path=str(target), shallow=shallow)
-    return CloneResult(
-        path=target,
-        operation="reclone" if force_reclone else "clone",
-        branch=branch or "HEAD",
-        ref=ref,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Archive
-# ---------------------------------------------------------------------------
-
-
-def download_rest_archive(
-    client: BitbucketClient,
-    ref: RepoRef,
-    output_path: Path,
-    *,
-    format: str = "zip",
-    at: str | None = None,
-    path: str | None = None,
-) -> ArchiveResult | None:
-    """Try Bitbucket Server REST archive endpoint.
-
-    Returns an ArchiveResult on success, or None if the endpoint is not
-    available (e.g. Bitbucket Server < 5.1).
-    """
-    try:
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_path, "wb") as fd:
-            client.download_archive(
-                ref.project_key,
-                ref.repo_slug,
-                fd,
-                at=at,
-                format=format,
-                path=path,
-            )
-        size = output_path.stat().st_size
-        if size == 0:
-            output_path.unlink(missing_ok=True)
-            log.warning("rest_archive_empty", project=ref.project_key, repo=ref.repo_slug)
-            return None
-        log.info("rest_archive_downloaded", path=str(output_path), size_bytes=size)
-        return ArchiveResult(
-            archive_path=output_path,
-            format=format,
-            size_bytes=size,
-            method="rest_api",
-            ref=ref,
-        )
-    except Exception:
-        log.warning(
-            "rest_archive_failed_falling_back",
-            project=ref.project_key,
-            repo=ref.repo_slug,
-            exc_info=True,
-        )
-        output_path.unlink(missing_ok=True)
-        return None
-
-
-def _zip_directory(source_dir: Path, output_path: Path, *, include_git: bool) -> int:
-    """Create a zip archive of a directory, optionally excluding .git/."""
-    import zipfile
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
-        for file_path in sorted(source_dir.rglob("*")):
-            if not include_git and ".git" in file_path.parts:
-                continue
-            if file_path.is_file():
-                arcname = file_path.relative_to(source_dir.parent)
-                zf.write(file_path, arcname)
-    return output_path.stat().st_size
-
-
-def _targz_directory(source_dir: Path, output_path: Path, *, include_git: bool) -> int:
-    """Create a tar.gz archive of a directory."""
-    import tarfile
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-
-    def _filter(tarinfo: tarfile.TarInfo) -> tarfile.TarInfo | None:
-        if not include_git and "/.git/" in f"/{tarinfo.name}/":
-            return None
-        return tarinfo
-
-    with tarfile.open(output_path, "w:gz") as tf:
-        tf.add(source_dir, arcname=source_dir.name, filter=_filter)
-    return output_path.stat().st_size
-
-
-def archive_repo(
-    ref: RepoRef,
-    client: BitbucketClient,
-    clone_url: str,
-    cache_root: Path,
-    output_path: Path,
-    *,
-    format: str = "zip",
-    at: str | None = None,
-    path: str | None = None,
-    include_git: bool = False,
-) -> ArchiveResult:
-    """Archive a repo: REST-first, fallback to clone+zip.
-
-    When ``include_git`` is True, the REST path is skipped because REST
-    archives never include ``.git/``.
-    """
-    # Path A: REST archive (unless include_git requested)
-    if not include_git:
-        rest_result = download_rest_archive(client, ref, output_path, format=format, at=at, path=path)
-        if rest_result is not None:
-            return rest_result
-
-    # Path B: Clone + local archive
-    clone_dir = default_clone_dir(ref, cache_root)
-    clone_repo(ref, clone_url, clone_dir, branch=at)
-
-    if format in ("tar.gz", "tgz"):
-        size = _targz_directory(clone_dir, output_path, include_git=include_git)
-    else:
-        size = _zip_directory(clone_dir, output_path, include_git=include_git)
-
-    log.info("local_archive_created", path=str(output_path), size_bytes=size, format=format)
-    return ArchiveResult(
-        archive_path=output_path,
-        format=format,
-        size_bytes=size,
-        method="local_zip",
-        ref=ref,
-    )

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/tests/__init__.py

@@ -1,8 +0,0 @@
-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))

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/tests/conftest.py

@@ -1,65 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-from vds_bitbucket_orchestrator.config import BitbucketSettings
-
-
-def clear_runtime_env(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Clear runtime environment variables for testing."""
-    for key in (
-        "VDS_USERNAME",
-        "VDS_PASSWORD",
-        "BITBUCKET_TOKEN",
-        "BITBUCKET_BASE_URL",
-        "BITBUCKET_CLOUD_WORKSPACE",
-        "BITBUCKET_MODE",
-    ):
-        monkeypatch.delenv(key, raising=False)
-
-
-def write_env(tmp_path: Path, content: str) -> Path:
-    """Write a temporary .env file for testing."""
-    env_path = tmp_path / ".env"
-    env_path.write_text(content)
-    return env_path
-
-
-@pytest.fixture
-def mock_bitbucket_settings() -> BitbucketSettings:
-    """Create mock Bitbucket settings for testing."""
-    return BitbucketSettings(
-        VDS_USERNAME="test_user",
-        VDS_PASSWORD="test_pass",
-        BITBUCKET_TOKEN="test_token",
-        BITBUCKET_BASE_URL="https://bitbucket.test.com",
-        BITBUCKET_MODE="server",
-    )
-
-
-@pytest.fixture
-def sample_project_response() -> dict[str, object]:
-    """Sample Bitbucket project response."""
-    return {
-        "key": "TEST",
-        "name": "Test Project",
-        "description": "A test project",
-        "type": "NORMAL",
-        "public": False,
-        "links": {"self": {"href": "https://bitbucket.test.com/projects/TEST"}},
-    }
-
-
-@pytest.fixture
-def sample_repository_response() -> dict[str, object]:
-    """Sample Bitbucket repository response."""
-    return {
-        "slug": "test-repo",
-        "name": "Test Repository",
-        "description": "A test repository",
-        "scm": "git",
-        "state": "AVAILABLE",
-        "public": False,
-        "links": {"self": {"href": "https://bitbucket.test.com/projects/TEST/repos/test-repo"}},
-    }