@ngocsangairvds/vsaf 4.1.7 → 4.1.9

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

@@ -1,2693 +0,0 @@
-"""Bitbucket client wrapper using atlassian-python-api for consistency."""
-
-from __future__ import annotations
-
-import time
-from itertools import islice
-from typing import TYPE_CHECKING, Any
-
-import requests
-import structlog
-from atlassian import Bitbucket as AtlassianBitbucket
-
-from .errors import (
-    AuthError,
-    ConflictError,
-    NotFoundError,
-    RateLimitError,
-    ResponseError,
-    RetryError,
-    TransportError,
-    VDSClientError,
-)
-
-if TYPE_CHECKING:
-    from .config import BitbucketSettings
-
-
-class BitbucketClient:
-    """Bitbucket client wrapper using atlassian-python-api SDK.
-
-    This class implements the following protocols for dependency injection:
-    - BitbucketRepositoryClient: Repository operations (list_projects, get_project, etc.)
-    - BitbucketBranchClient: Branch and permission operations (get_branches, list_branch_permissions)
-    - BitbucketCodeClient: Code operations (get_content_of_file, get_commits)
-    - BitbucketFullClient: Combined protocol (union of all above)
-
-    The protocols enable type-safe dependency injection and mock implementations for testing.
-    See protocols.py for protocol definitions.
-
-    Example:
-        from vds_bitbucket_orchestrator import BitbucketClient, BitbucketFullClient
-
-        def audit_repo(client: BitbucketFullClient, project: str, repo: str) -> dict:
-            # Type-safe access to all client methods
-            return {
-                "repo": client.get_repository(project, repo),
-                "permissions": client.list_branch_permissions(project, repo),
-                "readme": client.get_content_of_file(project, repo, "README.md"),
-            }
-
-        # BitbucketClient satisfies BitbucketFullClient protocol
-        client = BitbucketClient(settings)
-        result = audit_repo(client, "INS", "insurance-core")
-    """
-
-    def __init__(
-        self,
-        settings: BitbucketSettings,
-        *,
-        timeout: int | None = 30,
-    ) -> None:
-        self._settings = settings
-        self._timeout = timeout or 30
-
-        # Validate credentials
-        settings.require_basic_or_token()
-
-        try:
-            auth_kwargs = settings.get_auth_kwargs()
-            url = settings.get_url()
-
-            if settings.is_cloud_mode:
-                # For Bitbucket Cloud, we need to use the cloud API
-                self._client = AtlassianBitbucket(
-                    url=url, timeout=self._timeout, cloud=True, workspace=settings.cloud_workspace, **auth_kwargs
-                )
-            else:
-                # For Bitbucket Server/Data Center
-                self._client = AtlassianBitbucket(url=url, timeout=self._timeout, **auth_kwargs)
-
-        except Exception as exc:
-            raise TransportError(
-                f"Failed to initialize Bitbucket client: {exc}",
-                context={"mode": settings.mode, "url": settings.get_url()},
-            ) from exc
-
-        self._log = structlog.get_logger(__name__).bind(mode=settings.mode, url=settings.get_url())
-
-        # Store retry settings
-        self._max_retries = settings.max_retries
-        self._retry_backoff_factor = settings.retry_backoff_factor
-
-    def _with_retry(self, operation, operation_name: str):
-        """Execute an operation with retry logic using instance settings."""
-        for attempt in range(self._max_retries + 1):
-            try:
-                result = operation()
-                return result or []
-            except Exception as exc:
-                try:
-                    self._handle_api_error(exc, operation_name)
-                except (TransportError, RateLimitError) as retry_exc:
-                    if attempt == self._max_retries:
-                        self._log.error(
-                            "retry_attempts_exhausted",
-                            operation=operation_name,
-                            attempts=self._max_retries,
-                            final_error=str(retry_exc),
-                        )
-                        raise RetryError(
-                            f"Retry attempts exhausted: {retry_exc}",
-                            context={
-                                "original_error": str(retry_exc),
-                                "operation": operation_name,
-                                "attempts": self._max_retries,
-                            },
-                        ) from retry_exc
-
-                    wait_time = self._retry_backoff_factor * (2**attempt)
-                    self._log.warning(
-                        "retry_attempt",
-                        operation=operation_name,
-                        attempt=attempt + 1,
-                        max_retries=self._max_retries,
-                        wait_time=wait_time,
-                        error=str(retry_exc),
-                    )
-                    time.sleep(wait_time)
-                except VDSClientError:
-                    # Don't retry on client errors (auth, not found, etc.)
-                    raise
-
-    def _handle_api_error(self, error: Exception, operation: str) -> None:
-        """Convert atlassian-python-api errors to our standardized errors."""
-        error_str = str(error).lower()
-        transport_markers = (
-            "timed out",
-            "timeout",
-            "connection error",
-            "connection reset",
-            "connection refused",
-            "name or service not known",
-            "temporary failure in name resolution",
-            "max retries exceeded",
-        )
-
-        if "unauthorized" in error_str or "authentication" in error_str or "401" in error_str:
-            raise AuthError(f"Authentication failed during {operation}", context={"error": str(error)})
-        elif "forbidden" in error_str or "403" in error_str:
-            raise AuthError(f"Access forbidden during {operation}", context={"error": str(error)})
-        elif "not found" in error_str or "404" in error_str:
-            raise NotFoundError(f"Resource not found during {operation}", context={"error": str(error)})
-        elif "rate limit" in error_str or "429" in error_str:
-            raise RateLimitError(f"Rate limited during {operation}", context={"error": str(error)})
-        elif "conflict" in error_str or "409" in error_str:
-            raise ConflictError(f"Conflict during {operation}", context={"error": str(error)})
-        elif "server error" in error_str or "500" in error_str:
-            raise ResponseError(f"Server error during {operation}", context={"error": str(error)})
-        elif any(marker in error_str for marker in transport_markers):
-            raise TransportError(f"Transport error during {operation}: {error}", context={"error": str(error)})
-        else:
-            raise VDSClientError(f"API error during {operation}: {error}", context={"error": str(error)})
-
-    # Project Management
-    def list_projects(self, limit: int = 25) -> list[dict[str, Any]]:
-        """List all projects."""
-        return self._with_retry(lambda: list(self._client.project_list(limit=limit)), "list_projects")
-
-    def get_project(self, project_key: str) -> dict[str, Any]:
-        """Get project information."""
-        try:
-            result = self._client.project(project_key)
-            self._log.debug("project_retrieved", project_key=project_key)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_project {project_key}")
-
-    def create_project(
-        self, key: str, name: str, description: str = "Project created via VDS orchestrator"
-    ) -> dict[str, Any]:
-        """Create a new project."""
-        try:
-            result = self._client.create_project(key, name, description)
-            self._log.info("project_created", key=key, name=name)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_project {key}")
-
-    # Repository Management
-    def list_repositories(self, project_key: str, limit: int = 25) -> list[dict[str, Any]]:
-        """List repositories in a project."""
-        return self._with_retry(
-            lambda: list(self._client.repo_list(project_key, limit=limit)), f"list_repositories {project_key}"
-        )
-
-    def get_repository(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Get repository information."""
-        try:
-            result = self._client.get_repo(project_key, repository_slug)
-            self._log.debug("repository_retrieved", project_key=project_key, repository=repository_slug)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repository {project_key}/{repository_slug}")
-
-    def create_repository(
-        self, project_key: str, repository: str, forkable: bool = False, is_private: bool = True
-    ) -> dict[str, Any]:
-        """Create a new repository."""
-        try:
-            result = self._client.create_repo(project_key, repository, forkable=forkable, is_private=is_private)
-            self._log.info("repository_created", project_key=project_key, repository=repository)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_repository {repository}")
-
-    def update_repository(
-        self, project_key: str, repository_slug: str, description: str | None = None
-    ) -> dict[str, Any]:
-        """Update repository information."""
-        try:
-            result = self._client.update_repo(project_key, repository_slug, description=description or "")
-            self._log.info("repository_updated", project_key=project_key, repository=repository_slug)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"update_repository {repository_slug}")
-
-    def delete_repository(self, project_key: str, repository_slug: str) -> None:
-        """Delete a repository (DANGER!).
-
-        Reference: https://atlassian-python-api.readthedocs.io/bitbucket.html#delete-a-repository-danger
-        """
-        try:
-            self._client.delete_repo(project_key, repository_slug)
-            self._log.warning("repository_deleted", project_key=project_key, repository=repository_slug)
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_repository {repository_slug}")
-
-    def get_repository_labels(self, project_key: str, repository_slug: str) -> list[str]:
-        """Get labels for a repository."""
-        try:
-            result = self._client.get_repo_labels(project_key, repository_slug)
-            self._log.debug("repository_labels_retrieved", project_key=project_key, repository=repository_slug)
-            return result if isinstance(result, list) else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repository_labels {repository_slug}")
-
-    def fork_repository(
-        self,
-        project_key: str,
-        repository_slug: str,
-        new_project_key: str | None = None,
-        new_repository_slug: str | None = None,
-    ) -> dict[str, Any]:
-        """Fork a repository.
-
-        Args:
-            project_key: Source project key
-            repository_slug: Source repository slug
-            new_project_key: Target project key (if forking to new project). If None, forks within same project.
-            new_repository_slug: Target repository slug. If None, uses same name as source.
-        """
-        try:
-            if new_project_key:
-                # Fork to new project
-                if not new_repository_slug:
-                    new_repository_slug = repository_slug
-                result = self._client.fork_repository_new_project(  # type: ignore[attr-defined]
-                    project_key, repository_slug, new_project_key, new_repository_slug
-                )
-                self._log.info(
-                    "repository_forked_to_new_project",
-                    source_project=project_key,
-                    source_repo=repository_slug,
-                    target_project=new_project_key,
-                    target_repo=new_repository_slug,
-                )
-            else:
-                # Fork within same project
-                if not new_repository_slug:
-                    new_repository_slug = f"{repository_slug}-fork"
-                result = self._client.fork_repository(project_key, repository_slug, new_repository_slug)  # type: ignore[attr-defined]
-                self._log.info(
-                    "repository_forked",
-                    project_key=project_key,
-                    source_repo=repository_slug,
-                    target_repo=new_repository_slug,
-                )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"fork_repository {project_key}/{repository_slug}")
-
-    def get_forked_repositories(self, project_key: str, repository_slug: str) -> list[dict[str, Any]]:
-        """Get list of repositories forked from a source repository.
-
-        Note: SDK doesn't have a direct method for this. We use repository list and filter.
-        This may not be perfect but provides a way to discover forks.
-        """
-        try:
-            # List all repositories in the project and filter for forks
-            # Note: This is a workaround - actual fork relationship may need to be checked via repository metadata
-            repos = self.list_repositories(project_key, limit=99999)
-            # Filter repositories that might be forks (this is heuristic-based)
-            # In practice, you may need to check repository origin or fork metadata
-            forks = [repo for repo in repos if repository_slug.lower() in repo.get("slug", "").lower()]
-            self._log.debug(
-                "forked_repositories_retrieved", project_key=project_key, source_repo=repository_slug, count=len(forks)
-            )
-            return forks
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_forked_repositories {project_key}/{repository_slug}")
-
-    def set_repository_label(self, project_key: str, repository_slug: str, label_name: str) -> dict[str, Any]:
-        """Set a label for a repository."""
-        try:
-            result = self._client.set_repo_label(project_key, repository_slug, label_name)
-            self._log.info(
-                "repository_label_set", project_key=project_key, repository=repository_slug, label=label_name
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_repository_label {repository_slug}")
-
-    # Pull Request Management
-    def list_pull_requests(
-        self,
-        project_key: str,
-        repository_slug: str,
-        state: str = "OPEN",
-        order: str = "newest",
-        limit: int = 100,
-        start: int = 0,
-    ) -> list[dict[str, Any]]:
-        """List pull requests.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            state: PR state (OPEN, MERGED, DECLINED)
-            order: Sort order (newest, oldest)
-            limit: Maximum number of PRs to return
-            start: Start index for pagination
-        """
-        return self._with_retry(
-            lambda: list(
-                self._client.get_pull_requests(
-                    project_key, repository_slug, state=state, order=order, limit=limit, start=start
-                )
-            ),
-            f"list_pull_requests {project_key}/{repository_slug}",
-        )
-
-    def create_pull_request(
-        self,
-        source_project: str,
-        source_repo: str,
-        dest_project: str,
-        dest_repo: str,
-        source_branch: str,
-        destination_branch: str,
-        title: str,
-        description: str,
-        reviewers: list[str] | None = None,
-    ) -> dict[str, Any]:
-        """Create a pull request."""
-        try:
-            kwargs = {}
-            if reviewers:
-                kwargs["reviewers"] = reviewers
-
-            result = self._client.open_pull_request(
-                source_project,
-                source_repo,
-                dest_project,
-                dest_repo,
-                source_branch,
-                destination_branch,
-                title,
-                description,
-                **kwargs,
-            )
-            self._log.info("pull_request_created", title=title, source=source_branch, dest=destination_branch)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_pull_request {title}")
-
-    def get_pull_request(self, project_key: str, repository_slug: str, pull_request_id: str) -> dict[str, Any]:
-        """Get a specific pull request."""
-        try:
-            # Get all PRs and find the one matching the ID
-            prs = self._client.get_pull_requests(project_key, repository_slug, limit=1000)
-            for pr in prs:
-                if str(pr.get("id")) == str(pull_request_id):
-                    self._log.debug(
-                        "pull_request_retrieved",
-                        project_key=project_key,
-                        repository=repository_slug,
-                        pr_id=pull_request_id,
-                    )
-                    return pr
-            raise NotFoundError(
-                f"Pull request {pull_request_id} not found",
-                context={"project_key": project_key, "repository_slug": repository_slug},
-            )
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_pull_request {pull_request_id}")
-
-    def add_pull_request_comment(
-        self, project_key: str, repository_slug: str, pull_request_id: str, text: str, parent_id: str | None = None
-    ) -> dict[str, Any]:
-        """Add a comment to a pull request.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            pull_request_id: Pull request ID
-            text: Comment text
-            parent_id: Optional parent comment ID for replies
-        """
-        try:
-            result = self._client.add_pull_request_comment(
-                project_key, repository_slug, pull_request_id, text, parent_id=parent_id
-            )
-            self._log.info(
-                "pull_request_comment_added",
-                project_key=project_key,
-                repository=repository_slug,
-                pr_id=pull_request_id,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"add_pull_request_comment {pull_request_id}")
-
-    def get_pull_request_activities(
-        self, project_key: str, repository_slug: str, pull_request_id: str
-    ) -> list[dict[str, Any]]:
-        """Get pull request activities."""
-        try:
-            result = self._client.get_pull_requests_activities(project_key, repository_slug, pull_request_id)
-            self._log.debug(
-                "pull_request_activities_retrieved",
-                project_key=project_key,
-                repository=repository_slug,
-                pr_id=pull_request_id,
-            )
-            return result if isinstance(result, list) else [result]
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_pull_request_activities {pull_request_id}")
-
-    def get_pull_request_changes(
-        self, project_key: str, repository_slug: str, pull_request_id: str
-    ) -> list[dict[str, Any]]:
-        """Get pull request changes."""
-        try:
-            result = self._client.get_pull_requests_changes(project_key, repository_slug, pull_request_id)
-            self._log.debug(
-                "pull_request_changes_retrieved",
-                project_key=project_key,
-                repository=repository_slug,
-                pr_id=pull_request_id,
-            )
-            return result if isinstance(result, list) else [result]
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_pull_request_changes {pull_request_id}")
-
-    def delete_pull_request(
-        self, project_key: str, repository_slug: str, pull_request_id: str, pull_request_version: int
-    ) -> dict[str, Any]:
-        """Delete a pull request."""
-        try:
-            result = self._client.delete_pull_request(
-                project_key, repository_slug, pull_request_id, pull_request_version
-            )
-            self._log.info(
-                "pull_request_deleted",
-                project_key=project_key,
-                repository=repository_slug,
-                pr_id=pull_request_id,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_pull_request {pull_request_id}")
-
-    def merge_pull_request(self, project_key: str, repository_slug: str, pull_request_id: str) -> dict[str, Any]:
-        """Merge a pull request.
-
-        Note: This method attempts to use merge_pull_request if available in the SDK.
-        If it fails, consider using PR state transitions or activities API.
-        """
-        try:
-            # Try the direct merge method first
-            if hasattr(self._client, "merge_pull_request"):
-                result = self._client.merge_pull_request(project_key, repository_slug, pull_request_id)
-            else:
-                # Fallback: Use PR activities to merge (may require different approach)
-                raise VDSClientError(
-                    "merge_pull_request method not available in SDK. Use PR state transitions or activities API.",
-                    context={"project_key": project_key, "repository_slug": repository_slug, "pr_id": pull_request_id},
-                )
-            self._log.info(
-                "pull_request_merged", project_key=project_key, repository=repository_slug, pr_id=pull_request_id
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"merge_pull_request {pull_request_id}")
-
-    # Pipeline Management (for Bitbucket Cloud)
-    def list_pipelines(self, workspace: str, repository: str, limit: int = 10) -> list[dict[str, Any]]:
-        """List pipelines (Bitbucket Cloud only)."""
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError("Pipelines are only available in Bitbucket Cloud mode")
-
-        return self._with_retry(
-            lambda: list(self._client.get_pipelines(workspace, repository, limit=limit)),
-            f"list_pipelines {workspace}/{repository}",
-        )
-
-    def trigger_pipeline(self, workspace: str, repository: str, branch: str = "master") -> dict[str, Any]:
-        """Trigger a pipeline (Bitbucket Cloud only)."""
-        try:
-            if not self._settings.is_cloud_mode:
-                raise VDSClientError("Pipelines are only available in Bitbucket Cloud mode")
-
-            result = self._client.trigger_pipeline(workspace, repository, branch=branch)
-            self._log.info("pipeline_triggered", workspace=workspace, repository=repository, branch=branch)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"trigger_pipeline {workspace}/{repository}")
-
-    # Branch Management
-    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."""
-        try:
-            result = self._client.get_branches(
-                project_key, repository_slug, filter=filter, limit=limit, details=details
-            )
-            self._log.debug("branches_retrieved", project_key=project_key, repository=repository_slug)
-            return result if isinstance(result, list) else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_branches {project_key}/{repository_slug}")
-
-    def create_branch(
-        self, project_key: str, repository_slug: str, name: str, start_point: str, message: str | None = None
-    ) -> dict[str, Any]:
-        """Create a branch."""
-        try:
-            result = self._client.create_branch(project_key, repository_slug, name, start_point, message or "")
-            self._log.info("branch_created", project_key=project_key, repository=repository_slug, branch=name)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_branch {name}")
-
-    def delete_branch(
-        self, project_key: str, repository_slug: str, name: str, end_point: str | None = None
-    ) -> dict[str, Any]:
-        """Delete a branch."""
-        try:
-            result = self._client.delete_branch(project_key, repository_slug, name, end_point=end_point)
-            self._log.info("branch_deleted", project_key=project_key, repository=repository_slug, branch=name)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_branch {name}")
-
-    # Tag Management
-    def get_tags(
-        self, project_key: str, repository_slug: str, filter: str = "", limit: int = 99999
-    ) -> list[dict[str, Any]]:
-        """Get tags for a repository."""
-        try:
-            result = self._client.get_tags(project_key, repository_slug, filter=filter, limit=limit)
-            self._log.debug("tags_retrieved", project_key=project_key, repository=repository_slug)
-            return result if isinstance(result, list) else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_tags {project_key}/{repository_slug}")
-
-    def set_tag(
-        self,
-        project_key: str,
-        repository_slug: str,
-        tag_name: str,
-        commit_revision: str,
-        description: str | None = None,
-    ) -> dict[str, Any]:
-        """Set a tag."""
-        try:
-            result = self._client.set_tag(
-                project_key, repository_slug, tag_name, commit_revision, description=description
-            )
-            self._log.info("tag_set", project_key=project_key, repository=repository_slug, tag=tag_name)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_tag {tag_name}")
-
-    def delete_tag(self, project_key: str, repository_slug: str, tag_name: str) -> dict[str, Any]:
-        """Delete a tag."""
-        try:
-            result = self._client.delete_tag(project_key, repository_slug, tag_name)
-            self._log.info("tag_deleted", project_key=project_key, repository=repository_slug, tag=tag_name)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_tag {tag_name}")
-
-    # User and Group Management
-    def list_groups(self, group_filter: str | None = None, limit: int = 25) -> list[dict[str, Any]]:
-        """List all available groups.
-
-        Args:
-            group_filter: Optional filter string to search for specific groups
-            limit: Maximum number of groups to return
-        """
-        try:
-            # Use get_groups with optional filter parameter
-            if group_filter:
-                result = list(self._client.get_groups(group_filter=group_filter, limit=limit))
-            else:
-                result = list(self._client.get_groups(limit=limit))
-            self._log.debug("groups_listed", count=len(result) if result else 0, filter=group_filter)
-            return result or []
-        except Exception as exc:
-            self._handle_api_error(exc, "list_groups")
-
-    def list_project_users(
-        self, project_key: str, filter_str: str | None = None, limit: int = 25
-    ) -> list[dict[str, Any]]:
-        """List users in a project.
-
-        Args:
-            project_key: Project key
-            filter_str: Optional filter string to search for specific users
-            limit: Maximum number of users to return
-        """
-        try:
-            result = list(self._client.project_users(project_key, limit=limit, filter_str=filter_str))
-            self._log.debug(
-                "project_users_listed", project_key=project_key, count=len(result) if result else 0, filter=filter_str
-            )
-            return result or []
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_project_users {project_key}")
-
-    def list_project_groups(
-        self, project_key: str, filter_str: str | None = None, limit: int = 25
-    ) -> list[dict[str, Any]]:
-        """List groups in a project.
-
-        Args:
-            project_key: Project key
-            filter_str: Optional filter string to search for specific groups
-            limit: Maximum number of groups to return
-        """
-        try:
-            result = list(self._client.project_groups(project_key, limit=limit, filter_str=filter_str))
-            self._log.debug(
-                "project_groups_listed", project_key=project_key, count=len(result) if result else 0, filter=filter_str
-            )
-            return result or []
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_project_groups {project_key}")
-
-    def grant_user_repository_permissions(
-        self, project_key: str, repository_slug: str, username: str, permission: str
-    ) -> dict[str, Any]:
-        """Grant repository permissions to a user."""
-        try:
-            result = self._client.repo_grant_user_permissions(project_key, repository_slug, username, permission)
-            self._log.info(
-                "user_repository_permissions_granted",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                username=username,
-                permission=permission,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"grant_user_repository_permissions {project_key}/{repository_slug} for {username}"
-            )
-
-    def grant_user_project_permissions(self, project_key: str, username: str, permission: str) -> dict[str, Any]:
-        """Grant project permissions to a user."""
-        try:
-            result = self._client.project_grant_user_permissions(project_key, username, permission)
-            self._log.info(
-                "user_project_permissions_granted", project_key=project_key, username=username, permission=permission
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"grant_user_project_permissions {project_key} for {username}")
-
-    def grant_group_project_permissions(self, project_key: str, group_name: str, permission: str) -> dict[str, Any]:
-        """Grant project permissions to a group."""
-        try:
-            result = self._client.project_grant_group_permissions(project_key, group_name, permission)
-            self._log.info(
-                "group_project_permissions_granted",
-                project_key=project_key,
-                group=group_name,
-                permission=permission,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"grant_group_project_permissions {project_key} for {group_name}")
-
-    def grant_group_repository_permissions(
-        self, project_key: str, repository_slug: str, group: str, permission: str
-    ) -> dict[str, Any]:
-        """Grant repository permissions to a group."""
-        try:
-            result = self._client.repo_grant_group_permissions(project_key, repository_slug, group, permission)
-            self._log.info(
-                "group_repository_permissions_granted",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                group=group,
-                permission=permission,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"grant_group_repository_permissions {project_key}/{repository_slug} for {group}"
-            )
-
-    # Branch Permissions
-    def set_branches_permissions(
-        self,
-        project_key: str,
-        multiple_permissions: bool = False,
-        matcher_type: str | None = None,
-        matcher_value: str | None = None,
-        permission_type: str | None = None,
-        repository_slug: str | None = None,
-        except_users: list[str] | None = None,
-        except_groups: list[str] | None = None,
-        except_access_keys: list[str] | None = None,
-        start: int = 0,
-        limit: int = 25,
-    ) -> dict[str, Any]:
-        """Set branch permissions."""
-        try:
-            result = self._client.set_branches_permissions(
-                project_key,
-                multiple_permissions=multiple_permissions,
-                matcher_type=matcher_type,
-                matcher_value=matcher_value,
-                permission_type=permission_type,
-                repository_slug=repository_slug,
-                except_users=except_users or [],
-                except_groups=except_groups or [],
-                except_access_keys=except_access_keys or [],
-                start=start,
-                limit=limit,
-            )
-            self._log.info(
-                "branch_permissions_set",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                permission_type=permission_type,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_branches_permissions {project_key}")
-
-    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).
-
-        Returns a normalized list of branch restriction objects (payload["values"] when present).
-        """
-
-        def _fetch_permissions() -> list[dict[str, Any]]:
-            settings = self._settings
-            if settings.is_cloud_mode:
-                if not repository_slug:
-                    raise VDSClientError("repository_slug is required for cloud branch permissions list")
-                if not settings.cloud_workspace:
-                    raise VDSClientError("BITBUCKET_CLOUD_WORKSPACE is required for cloud mode")
-
-                # Bitbucket Cloud uses page/pagelen rather than start/limit.
-                page = 1 + (start // max(1, limit))
-                url = (
-                    f"https://api.bitbucket.org/2.0/repositories/"
-                    f"{settings.cloud_workspace}/{repository_slug}/branch-restrictions"
-                )
-                params = {"page": page, "pagelen": limit}
-            else:
-                base_url = settings.get_url().rstrip("/")
-                if repository_slug:
-                    path = f"/rest/branch-permissions/2.0/projects/{project_key}/repos/{repository_slug}/restrictions"
-                else:
-                    path = f"/rest/branch-permissions/2.0/projects/{project_key}/restrictions"
-                url = f"{base_url}{path}"
-                params = {"start": start, "limit": limit}
-
-            headers = {"Accept": "application/json"}
-            auth = None
-
-            if settings.token:
-                headers["Authorization"] = f"Bearer {settings.token}"
-            elif settings.username and settings.password:
-                auth = (settings.username, settings.password)
-
-            try:
-                response = requests.get(
-                    url,
-                    headers=headers,
-                    params=params,
-                    auth=auth,
-                    timeout=self._timeout,
-                )
-            except requests.exceptions.Timeout as exc:
-                raise TransportError(
-                    f"Branch permissions request timed out: {exc}",
-                    context={"url": url, "project_key": project_key, "repo": repository_slug},
-                ) from exc
-            except requests.exceptions.RequestException as exc:
-                raise TransportError(
-                    f"Branch permissions request failed: {exc}",
-                    context={"url": url, "project_key": project_key, "repo": repository_slug},
-                ) from exc
-
-            status = response.status_code
-            try:
-                payload: Any = response.json() if response.content else {}
-            except ValueError:
-                payload = {"raw": response.text}
-
-            if status in (401, 403):
-                raise AuthError(
-                    "Authentication failed while listing branch permissions",
-                    context={"status_code": status, "response": payload},
-                )
-            if status == 404:
-                raise NotFoundError(
-                    "Branch permissions not found",
-                    context={"status_code": status, "response": payload},
-                )
-            if status == 429:
-                raise RateLimitError(
-                    "Rate limited while listing branch permissions",
-                    context={"status_code": status, "response": payload},
-                )
-            if status == 409:
-                raise ConflictError(
-                    "Conflict while listing branch permissions",
-                    context={"status_code": status, "response": payload},
-                )
-            if status >= 500:
-                raise ResponseError(
-                    "Server error while listing branch permissions",
-                    context={"status_code": status, "response": payload},
-                )
-            if status >= 400:
-                raise VDSClientError(
-                    "Failed to list branch permissions",
-                    context={"status_code": status, "response": payload},
-                )
-
-            if isinstance(payload, dict):
-                values = payload.get("values")
-                return values if isinstance(values, list) else []
-            if isinstance(payload, list):
-                return payload
-            return []
-
-        result = self._with_retry(_fetch_permissions, f"list_branch_permissions {project_key}")
-        self._log.debug(
-            "branch_permissions_listed",
-            project_key=project_key,
-            repository_slug=repository_slug,
-            count=len(result),
-        )
-        return result
-
-    def get_branch_permission(
-        self, project_key: str, permission_id: int, repository_slug: str | None = None
-    ) -> dict[str, Any]:
-        """Get a single branch permission by permission ID."""
-        try:
-            result = self._client.get_branch_permission(project_key, permission_id, repository_slug=repository_slug)
-            self._log.debug(
-                "branch_permission_retrieved",
-                project_key=project_key,
-                permission_id=permission_id,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_branch_permission {permission_id}")
-
-    def delete_branch_permission(
-        self, project_key: str, permission_id: int, repository_slug: str | None = None
-    ) -> None:
-        """Delete a single branch permission by permission ID."""
-        try:
-            self._client.delete_branch_permission(project_key, permission_id, repository_slug=repository_slug)
-            self._log.info(
-                "branch_permission_deleted",
-                project_key=project_key,
-                permission_id=permission_id,
-                repository_slug=repository_slug,
-            )
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_branch_permission {permission_id}")
-
-    # Webhook Management (Bitbucket Cloud only)
-    def list_webhooks(
-        self,
-        project_key: str,
-        repository_slug: str,
-        *,
-        event: str | None = None,
-        statistics: bool = False,
-    ) -> list[dict[str, Any]]:
-        """List repository webhooks."""
-        try:
-            result = self._client.get_webhooks(project_key, repository_slug, event=event, statistics=statistics)
-            self._log.debug(
-                "webhooks_listed",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                event=event,
-                statistics=statistics,
-                count=len(result) if isinstance(result, list) else 0,
-            )
-            return result if isinstance(result, list) else [result] if result else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_webhooks {project_key}/{repository_slug}")
-
-    def get_webhook(self, project_key: str, repository_slug: str, webhook_id: int) -> dict[str, Any]:
-        """Retrieve a specific webhook."""
-        try:
-            result = self._client.get_webhook(project_key, repository_slug, webhook_id)
-            self._log.debug(
-                "webhook_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                webhook_id=webhook_id,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_webhook {project_key}/{repository_slug}/{webhook_id}")
-
-    def create_webhook(
-        self,
-        project_key: str,
-        repository_slug: str,
-        name: str,
-        events: list[str],
-        webhook_url: str,
-        *,
-        active: bool = True,
-        secret: str | None = None,
-    ) -> dict[str, Any]:
-        """Create a repository webhook."""
-        try:
-            result = self._client.create_webhook(
-                project_key,
-                repository_slug,
-                name,
-                events,
-                webhook_url,
-                active,
-                secret=secret,
-            )
-            self._log.info(
-                "webhook_created",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                name=name,
-                events=events,
-                active=active,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_webhook {project_key}/{repository_slug}")
-
-    def update_webhook(
-        self,
-        project_key: str,
-        repository_slug: str,
-        webhook_id: int,
-        *,
-        name: str | None = None,
-        events: list[str] | None = None,
-        webhook_url: str | None = None,
-        active: bool | None = None,
-        secret: str | None = None,
-    ) -> dict[str, Any]:
-        """Update a repository webhook."""
-        try:
-            params: dict[str, Any] = {}
-            if name is not None:
-                params["name"] = name
-            if events is not None:
-                params["events"] = events
-            if webhook_url is not None:
-                params["url"] = webhook_url
-            if active is not None:
-                params["active"] = active
-            if secret is not None:
-                params["secret"] = secret
-
-            result = self._client.update_webhook(project_key, repository_slug, webhook_id, **params)
-            self._log.info(
-                "webhook_updated",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                webhook_id=webhook_id,
-                updated_fields=list(params.keys()),
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"update_webhook {project_key}/{repository_slug}/{webhook_id}")
-
-    def delete_webhook(self, project_key: str, repository_slug: str, webhook_id: int) -> None:
-        """Delete a repository webhook."""
-        try:
-            self._client.delete_webhook(project_key, repository_slug, webhook_id)
-            self._log.info(
-                "webhook_deleted",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                webhook_id=webhook_id,
-            )
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_webhook {project_key}/{repository_slug}/{webhook_id}")
-
-    # Conditions-Reviewers Management
-    def get_project_conditions(self, project_key: str) -> list[dict[str, Any]]:
-        """Get all project conditions with reviewers list."""
-        try:
-            result = self._client.get_project_conditions(project_key)
-            self._log.debug("project_conditions_retrieved", project_key=project_key, count=len(result) if result else 0)
-            return result if isinstance(result, list) else [result] if result else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_project_conditions {project_key}")
-
-    def get_project_condition(self, project_key: str, condition_id: int) -> dict[str, Any]:
-        """Get a project condition with reviewers list."""
-        try:
-            result = self._client.get_project_condition(project_key, condition_id)
-            self._log.debug("project_condition_retrieved", project_key=project_key, condition_id=condition_id)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_project_condition {condition_id}")
-
-    def create_project_condition(self, project_key: str, condition: dict[str, Any]) -> dict[str, Any]:
-        """Create project condition with reviewers."""
-        try:
-            result = self._client.create_project_condition(project_key, condition)
-            self._log.info("project_condition_created", project_key=project_key)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_project_condition {project_key}")
-
-    def update_project_condition(
-        self, project_key: str, condition: dict[str, Any], condition_id: int
-    ) -> dict[str, Any]:
-        """Update a project condition with reviewers."""
-        try:
-            result = self._client.update_project_condition(project_key, condition, condition_id)
-            self._log.info("project_condition_updated", project_key=project_key, condition_id=condition_id)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"update_project_condition {condition_id}")
-
-    def delete_project_condition(self, project_key: str, condition_id: int) -> None:
-        """Delete a project condition."""
-        try:
-            self._client.delete_project_condition(project_key, condition_id)
-            self._log.info("project_condition_deleted", project_key=project_key, condition_id=condition_id)
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_project_condition {condition_id}")
-
-    def get_repo_conditions(self, project_key: str, repository_slug: str) -> list[dict[str, Any]]:
-        """Get all repository conditions with reviewers list."""
-        try:
-            result = self._client.get_repo_conditions(project_key, repository_slug)
-            self._log.debug(
-                "repo_conditions_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                count=len(result) if result else 0,
-            )
-            return result if isinstance(result, list) else [result] if result else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repo_conditions {project_key}/{repository_slug}")
-
-    def get_repo_condition(self, project_key: str, repository_slug: str, condition_id: int) -> dict[str, Any]:
-        """Get a repository condition with reviewers list."""
-        try:
-            result = self._client.get_repo_condition(project_key, repository_slug, condition_id)
-            self._log.debug(
-                "repo_condition_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                condition_id=condition_id,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repo_condition {condition_id}")
-
-    def create_repo_condition(
-        self, project_key: str, repository_slug: str, condition: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Create repository condition with reviewers."""
-        try:
-            result = self._client.create_repo_condition(project_key, repository_slug, condition)
-            self._log.info("repo_condition_created", project_key=project_key, repository_slug=repository_slug)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_repo_condition {project_key}/{repository_slug}")
-
-    def update_repo_condition(
-        self, project_key: str, repository_slug: str, condition: dict[str, Any], condition_id: int
-    ) -> dict[str, Any]:
-        """Update a repository condition with reviewers."""
-        try:
-            result = self._client.update_repo_condition(project_key, repository_slug, condition, condition_id)
-            self._log.info(
-                "repo_condition_updated",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                condition_id=condition_id,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"update_repo_condition {condition_id}")
-
-    def delete_repo_condition(self, project_key: str, repository_slug: str, condition_id: int) -> None:
-        """Delete a repository condition."""
-        try:
-            self._client.delete_repo_condition(project_key, repository_slug, condition_id)
-            self._log.info(
-                "repo_condition_deleted",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                condition_id=condition_id,
-            )
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_repo_condition {condition_id}")
-
-    # Code Management
-    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 the file from repository."""
-        try:
-            result = self._client.get_content_of_file(project_key, repository_slug, filename, at=at, markup=markup)
-            self._log.debug(
-                "file_content_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                filename=filename,
-            )
-            # The upstream SDK may return bytes; normalize to text so CLI can write safely.
-            if isinstance(result, bytes):
-                return result.decode("utf-8", errors="replace")
-            return str(result) if result is not None else ""
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_content_of_file {filename}")
-
-    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."""
-        try:
-            result = self._client.get_commits(project_key, repository_slug, hash_oldest, hash_newest, limit=limit)
-            # atlassian-python-api returns a paged iterator; consuming it directly may fetch the
-            # entire history even when `limit` is small. Cap local iteration to the requested limit.
-            if isinstance(result, list):
-                commits_list = result[:limit] if limit and limit > 0 else result
-            elif result:
-                commits_list = list(islice(result, limit)) if limit and limit > 0 else list(result)
-            else:
-                commits_list = []
-            self._log.debug(
-                "commits_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                count=len(commits_list),
-            )
-            return commits_list
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_commits {project_key}/{repository_slug}")
-
-    def get_diff(
-        self, project_key: str, repository_slug: str, path: str, hash_oldest: str, hash_newest: str
-    ) -> dict[str, Any]:
-        """Get diff between two commits."""
-        try:
-            result = self._client.get_diff(project_key, repository_slug, path, hash_oldest, hash_newest)
-            self._log.debug(
-                "diff_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                path=path,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_diff {path}")
-
-    def get_changelog(
-        self, project_key: str, repository_slug: str, ref_from: str, ref_to: str, limit: int = 99999
-    ) -> list[dict[str, Any]]:
-        """Get change log between 2 refs."""
-        try:
-            result = self._client.get_changelog(project_key, repository_slug, ref_from, ref_to, limit=limit)
-            # SDK may return a generator, convert to list first
-            changelog_list = result if isinstance(result, list) else list(result) if result else []
-            self._log.debug(
-                "changelog_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                count=len(changelog_list),
-            )
-            return changelog_list
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_changelog {project_key}/{repository_slug}")
-
-    # Code Insights Operations (Cloud-only)
-    def create_code_insights_report(
-        self,
-        project_key: str,
-        repository_slug: str,
-        commit_id: str,
-        report_key: str,
-        report_title: str,
-        reporter: str,
-        result: str,
-        data: list[dict[str, Any]] | None = None,
-        **report_params: Any,
-    ) -> dict[str, Any]:
-        """Create a Code Insights report.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            commit_id: Commit hash
-            report_key: Unique report key
-            report_title: Report title
-            reporter: Reporter name
-            result: Report result ('PASSED', 'FAILED', 'PENDING')
-            data: Optional report data (list of data items)
-            **report_params: Additional report parameters (e.g., report_type, details, link)
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code Insights is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            params: dict[str, Any] = {
-                "reporter": reporter,
-                "result": result,
-            }
-            if data:
-                params["data"] = data
-            params.update(report_params)
-
-            result_obj = self._client.create_code_insights_report(
-                project_key, repository_slug, commit_id, report_key, report_title, **params
-            )
-            self._log.info(
-                "code_insights_report_created",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit_id=commit_id,
-                report_key=report_key,
-            )
-            return result_obj
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"create_code_insights_report {project_key}/{repository_slug}/{commit_id}/{report_key}"
-            )
-
-    def get_code_insights_report(
-        self, project_key: str, repository_slug: str, commit_id: str, report_key: str
-    ) -> dict[str, Any]:
-        """Get a Code Insights report."""
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code Insights is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            result = self._client.get_code_insights_report(project_key, repository_slug, commit_id, report_key)
-            self._log.debug(
-                "code_insights_report_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit_id=commit_id,
-                report_key=report_key,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"get_code_insights_report {project_key}/{repository_slug}/{commit_id}/{report_key}"
-            )
-
-    def add_code_insights_annotations_to_report(
-        self,
-        project_key: str,
-        repository_slug: str,
-        commit_id: str,
-        report_key: str,
-        annotations: list[dict[str, Any]],
-    ) -> dict[str, Any]:
-        """Add annotations to a Code Insights report."""
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code Insights is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            result = self._client.add_code_insights_annotations_to_report(
-                project_key, repository_slug, commit_id, report_key, annotations
-            )
-            self._log.info(
-                "code_insights_annotations_added",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit_id=commit_id,
-                report_key=report_key,
-                annotation_count=len(annotations),
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"add_code_insights_annotations_to_report {project_key}/{repository_slug}/{commit_id}/{report_key}"
-            )
-
-    def delete_code_insights_report(
-        self, project_key: str, repository_slug: str, commit_id: str, report_key: str
-    ) -> None:
-        """Delete a Code Insights report."""
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code Insights is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            self._client.delete_code_insights_report(project_key, repository_slug, commit_id, report_key)
-            self._log.info(
-                "code_insights_report_deleted",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit_id=commit_id,
-                report_key=report_key,
-            )
-        except Exception as exc:
-            self._handle_api_error(
-                exc, f"delete_code_insights_report {project_key}/{repository_slug}/{commit_id}/{report_key}"
-            )
-
-    # Repository Settings Operations
-    def get_branching_model(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Get branching model configuration."""
-        try:
-            result = self._client.get_branching_model(project_key, repository_slug)
-            self._log.debug(
-                "branching_model_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_branching_model {project_key}/{repository_slug}")
-
-    def set_branching_model(self, project_key: str, repository_slug: str, model: dict[str, Any]) -> dict[str, Any]:
-        """Set branching model configuration."""
-        try:
-            result = self._client.set_branching_model(project_key, repository_slug, model)
-            self._log.info(
-                "branching_model_set",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_branching_model {project_key}/{repository_slug}")
-
-    def enable_branching_model(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Enable branching model."""
-        try:
-            result = self._client.enable_branching_model(project_key, repository_slug)
-            self._log.info(
-                "branching_model_enabled",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"enable_branching_model {project_key}/{repository_slug}")
-
-    def disable_branching_model(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Disable branching model."""
-        try:
-            result = self._client.disable_branching_model(project_key, repository_slug)
-            self._log.info(
-                "branching_model_disabled",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"disable_branching_model {project_key}/{repository_slug}")
-
-    def get_default_branch(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Get default branch."""
-        try:
-            result = self._client.get_default_branch(project_key, repository_slug)
-            self._log.debug(
-                "default_branch_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_default_branch {project_key}/{repository_slug}")
-
-    def set_default_branch(self, project_key: str, repository_slug: str, branch: str) -> dict[str, Any]:
-        """Set default branch."""
-        try:
-            result = self._client.set_default_branch(project_key, repository_slug, branch)
-            self._log.info(
-                "default_branch_set",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                branch=branch,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_default_branch {project_key}/{repository_slug}")
-
-    def get_repo_hook_settings(
-        self,
-        project_key: str,
-        repository_slug: str,
-        start: int = 0,
-        limit: int | None = None,
-        filter_type: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """Get repository hook settings."""
-        try:
-            result = self._client.all_repo_hook_settings(
-                project_key, repository_slug, start=start, limit=limit, filter_type=filter_type
-            )
-            # SDK may return a generator, convert to list first
-            hooks_list = result if isinstance(result, list) else list(result) if result else []
-            self._log.debug(
-                "repo_hook_settings_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                count=len(hooks_list),
-            )
-            return hooks_list
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repo_hook_settings {project_key}/{repository_slug}")
-
-    def enable_repo_hook_settings(self, project_key: str, repository_slug: str, hook_key: str) -> dict[str, Any]:
-        """Enable repository hook."""
-        try:
-            result = self._client.enable_repo_hook_settings(project_key, repository_slug, hook_key)
-            self._log.info(
-                "repo_hook_enabled",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                hook_key=hook_key,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"enable_repo_hook_settings {project_key}/{repository_slug}/{hook_key}")
-
-    def disable_repo_hook_settings(self, project_key: str, repository_slug: str, hook_key: str) -> dict[str, Any]:
-        """Disable repository hook."""
-        try:
-            result = self._client.disable_repo_hook_settings(project_key, repository_slug, hook_key)
-            self._log.info(
-                "repo_hook_disabled",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                hook_key=hook_key,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"disable_repo_hook_settings {project_key}/{repository_slug}/{hook_key}")
-
-    def get_lfs_repo_status(self, project_key: str, repository_slug: str) -> dict[str, Any]:
-        """Get Git LFS repository status."""
-        try:
-            result = self._client.get_lfs_repo_status(project_key, repository_slug)
-            self._log.debug(
-                "lfs_repo_status_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_lfs_repo_status {project_key}/{repository_slug}")
-
-    def set_lfs_repo_status(self, project_key: str, repository_slug: str, enabled: bool) -> dict[str, Any]:
-        """Set Git LFS repository status."""
-        try:
-            result = self._client.set_lfs_repo_status(project_key, repository_slug, enabled)
-            self._log.info(
-                "lfs_repo_status_set",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                enabled=enabled,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"set_lfs_repo_status {project_key}/{repository_slug}")
-
-    # Advanced Code Operations
-    def get_file_list(
-        self,
-        project_key: str,
-        repository_slug: str,
-        sub_folder: str | None = None,
-        query: str | None = None,
-        start: int = 0,
-        limit: int | None = None,
-    ) -> list[dict[str, Any]]:
-        """Get file list from repository.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            sub_folder: Optional subfolder path
-            query: Optional query string for filtering
-            start: Start index for pagination
-            limit: Maximum number of results
-        """
-        try:
-            result = self._client.get_file_list(
-                project_key, repository_slug, sub_folder=sub_folder, query=query, start=start, limit=limit
-            )
-            self._log.debug(
-                "file_list_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                sub_folder=sub_folder,
-                count=len(result) if result else 0,
-            )
-            return result if isinstance(result, list) else [result] if result else []
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_file_list {project_key}/{repository_slug}")
-
-    def get_commit_info(
-        self, project_key: str, repository_slug: str, commit: str, path: str | None = None
-    ) -> dict[str, Any]:
-        """Get commit information.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            commit: Commit hash
-            path: Optional file path
-        """
-        try:
-            result = self._client.get_commit_info(project_key, repository_slug, commit, path=path)
-            self._log.debug(
-                "commit_info_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit=commit,
-                path=path,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_commit_info {project_key}/{repository_slug}/{commit}")
-
-    def get_commit_changes(
-        self,
-        project_key: str,
-        repository_slug: str,
-        commit_id: str | None = None,
-        hash_newest: str | None = None,
-        merges: str = "include",
-    ) -> dict[str, Any]:
-        """Get commit changes.
-
-        Args:
-            project_key: Project key
-            repository_slug: Repository slug
-            commit_id: Commit ID (preferred)
-            hash_newest: Newest commit hash (alternative to commit_id)
-            merges: How to handle merges ('include', 'exclude', 'only')
-        """
-        try:
-            result = self._client.get_commit_changes(
-                project_key, repository_slug, hash_newest=hash_newest, merges=merges, commit_id=commit_id
-            )
-            self._log.debug(
-                "commit_changes_retrieved",
-                project_key=project_key,
-                repository_slug=repository_slug,
-                commit_id=commit_id,
-                hash_newest=hash_newest,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_commit_changes {project_key}/{repository_slug}")
-
-    def search_code(self, team: str, search_query: str, page: int = 1, limit: int = 10) -> dict[str, Any]:
-        """Search code (Cloud-only).
-
-        Args:
-            team: Team/workspace name (Cloud only)
-            search_query: Search query string
-            page: Page number for pagination
-            limit: Maximum number of results per page
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code search is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            result = self._client.search_code(team, search_query, page=page, limit=limit)
-            self._log.debug(
-                "code_search_performed",
-                team=team,
-                search_query=search_query,
-                page=page,
-            )
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"search_code {team}")
-
-    def search_code_advanced(
-        self,
-        team: str,
-        search_query: str,
-        *,
-        page: int = 1,
-        limit: int = 10,
-        repository: str | None = None,
-        **kwargs: Any,
-    ) -> dict[str, Any]:
-        """Advanced code search with additional filters (Cloud-only).
-
-        Args:
-            team: Team/workspace name (Cloud only)
-            search_query: Search query string
-            page: Page number for pagination (default: 1)
-            limit: Maximum number of results per page (default: 10)
-            repository: Optional repository slug to filter by
-            **kwargs: Additional search parameters (if supported by SDK)
-
-        Note: Code search is only available in Bitbucket Cloud. Server/DC instances
-        do not have code search capabilities via the REST API.
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Code search is only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            # SDK search_code may support additional parameters via kwargs
-            result = self._client.search_code(team, search_query, page=page, limit=limit, **kwargs)  # type: ignore[call-arg]
-            self._log.debug(
-                "code_search_advanced_performed",
-                team=team,
-                search_query=search_query,
-                page=page,
-                limit=limit,
-                repository=repository,
-            )
-            # If repository filter is provided, filter results client-side
-            # (SDK may not support repository parameter directly)
-            if repository and isinstance(result, dict) and "values" in result:
-                filtered = [
-                    item for item in result.get("values", []) if item.get("repository", {}).get("slug") == repository
-                ]
-                result["values"] = filtered
-                result["size"] = len(filtered)
-            return result
-        except Exception as exc:
-            self._handle_api_error(exc, f"search_code_advanced {team}")
-
-    def _get_cloud_repository(self, workspace: str, repository_slug: str):
-        """Retrieve a repository object using the cloud API."""
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Repository variable operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            return self._client.cloud.repositories.get(workspace, repository_slug)  # type: ignore[attr-defined]
-        except Exception as exc:
-            self._handle_api_error(exc, f"cloud_repository {workspace}/{repository_slug}")
-
-    # --- Repository Variables (Cloud-only) ---
-    @staticmethod
-    def _variable_to_dict(variable: Any) -> dict[str, Any]:
-        """Convert a repository variable object or dict to a plain dictionary."""
-        data = getattr(variable, "data", None)
-        if callable(data):
-            data = data()
-        if isinstance(data, dict):
-            return dict(data)
-        if isinstance(variable, dict):
-            return dict(variable)
-        return {}
-
-    @staticmethod
-    def _deployment_environment_to_dict(environment: Any) -> dict[str, Any]:
-        """Convert a deployment environment object to a dict."""
-        data = getattr(environment, "data", None)
-        if callable(data):
-            data = data()
-        if isinstance(data, dict):
-            return dict(data)
-        if isinstance(environment, dict):
-            return dict(environment)
-        return {}
-
-    @staticmethod
-    def _issue_to_dict(issue: Any) -> dict[str, Any]:
-        """Convert an issue object to a dict."""
-        data = getattr(issue, "data", None)
-        if callable(data):
-            data = data()
-        if isinstance(data, dict):
-            return dict(data)
-        if isinstance(issue, dict):
-            return dict(issue)
-        return {}
-
-    def _get_pull_request(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pull_request_id: str | int,
-    ):
-        """Retrieve a pull request object."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            return repository.pullrequests.get(pull_request_id)  # type: ignore[attr-defined]
-        except Exception as exc:
-            self._handle_api_error(exc, f"pull_request {workspace}/{repository_slug}/{pull_request_id}")
-
-    def _get_issue(
-        self,
-        workspace: str,
-        repository_slug: str,
-        issue_id: str | int,
-    ):
-        """Retrieve an issue object."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            return repository.issues.get(issue_id)  # type: ignore[attr-defined]
-        except Exception as exc:
-            self._handle_api_error(exc, f"repository_issue {workspace}/{repository_slug}/{issue_id}")
-
-    @staticmethod
-    def _pipeline_to_dict(pipeline: Any) -> dict[str, Any]:
-        """Convert a pipeline object to a plain dictionary."""
-        data = getattr(pipeline, "data", None)
-        if callable(data):
-            data = data()
-        if isinstance(data, dict):
-            return dict(data)
-        if isinstance(pipeline, dict):
-            return dict(pipeline)
-        return {}
-
-    @staticmethod
-    def _pipeline_step_to_dict(step: Any) -> dict[str, Any]:
-        """Convert a pipeline step object to a plain dictionary."""
-        data = getattr(step, "data", None)
-        if callable(data):
-            data = data()
-        if isinstance(data, dict):
-            return dict(data)
-        if isinstance(step, dict):
-            return dict(step)
-        return {}
-
-    def list_repository_variables(self, workspace: str, repository_slug: str) -> list[dict[str, Any]]:
-        """List repository variables."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            variables = [
-                self._variable_to_dict(variable)
-                for variable in repository.repository_variables.each()  # type: ignore[attr-defined]
-            ]
-            self._log.debug(
-                "repo_variables_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                count=len(variables),
-            )
-            return variables
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_repository_variables {workspace}/{repository_slug}")
-
-    def get_repository_variable(self, workspace: str, repository_slug: str, variable_uuid: str) -> dict[str, Any]:
-        """Get a repository variable by UUID."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            variable = repository.repository_variables.get(variable_uuid)  # type: ignore[attr-defined]
-            data = self._variable_to_dict(variable)
-            self._log.debug(
-                "repo_variable_retrieved",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                variable_uuid=variable_uuid,
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_repository_variable {workspace}/{repository_slug}/{variable_uuid}")
-
-    def create_repository_variable(
-        self,
-        workspace: str,
-        repository_slug: str,
-        key: str,
-        value: str,
-        secured: bool = False,
-    ) -> dict[str, Any]:
-        """Create a repository variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            variable = repository.repository_variables.create(key, value, secured)  # type: ignore[attr-defined]
-            data = self._variable_to_dict(variable)
-            self._log.info(
-                "repo_variable_created",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                key=key,
-                secured=secured,
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_repository_variable {workspace}/{repository_slug}")
-
-    def update_repository_variable(
-        self,
-        workspace: str,
-        repository_slug: str,
-        variable_uuid: str,
-        *,
-        key: str | None = None,
-        value: str | None = None,
-        secured: bool | None = None,
-    ) -> dict[str, Any]:
-        """Update a repository variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        update_payload: dict[str, Any] = {}
-        if key is not None:
-            update_payload["key"] = key
-        if value is not None:
-            update_payload["value"] = value
-        if secured is not None:
-            update_payload["secured"] = secured
-        if not update_payload:
-            raise VDSClientError(
-                "Provide at least one of --key/--value/--secured to update repository variable",
-                context={"workspace": workspace, "repository": repository_slug, "variable_uuid": variable_uuid},
-            )
-        try:
-            variable = repository.repository_variables.get(variable_uuid)  # type: ignore[attr-defined]
-            variable.update(**update_payload)  # type: ignore[attr-defined]
-            data = self._variable_to_dict(variable)
-            self._log.info(
-                "repo_variable_updated",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                variable_uuid=variable_uuid,
-                fields=list(update_payload.keys()),
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(exc, f"update_repository_variable {workspace}/{repository_slug}/{variable_uuid}")
-
-    def delete_repository_variable(self, workspace: str, repository_slug: str, variable_uuid: str) -> None:
-        """Delete a repository variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            variable = repository.repository_variables.get(variable_uuid)  # type: ignore[attr-defined]
-            variable.delete()  # type: ignore[attr-defined]
-            self._log.info(
-                "repo_variable_deleted",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                variable_uuid=variable_uuid,
-            )
-        except Exception as exc:
-            self._handle_api_error(exc, f"delete_repository_variable {workspace}/{repository_slug}/{variable_uuid}")
-
-    # --- Deployment Environments (Cloud-only) ---
-    def list_deployment_environments(self, workspace: str, repository_slug: str) -> list[dict[str, Any]]:
-        """List deployment environments."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            environments = [
-                self._deployment_environment_to_dict(env)
-                for env in repository.deployment_environments.each()  # type: ignore[attr-defined]
-            ]
-            self._log.debug(
-                "deployment_environments_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                count=len(environments),
-            )
-            return environments
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_deployment_environments {workspace}/{repository_slug}")
-
-    def get_deployment_environment(self, workspace: str, repository_slug: str, environment_uuid: str) -> dict[str, Any]:
-        """Retrieve a deployment environment."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            environment = repository.deployment_environments.get(environment_uuid)  # type: ignore[attr-defined]
-            data = self._deployment_environment_to_dict(environment)
-            self._log.debug(
-                "deployment_environment_retrieved",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                environment_uuid=environment_uuid,
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_deployment_environment {workspace}/{repository_slug}/{environment_uuid}")
-
-    def list_deployment_environment_variables(
-        self,
-        workspace: str,
-        repository_slug: str,
-        environment_uuid: str,
-        *,
-        pagelen: int = 10,
-    ) -> list[dict[str, Any]]:
-        """List variables for a deployment environment."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            environment = repository.deployment_environments.get(environment_uuid)  # type: ignore[attr-defined]
-            variables = [
-                self._variable_to_dict(variable)
-                for variable in environment.deployment_environment_variables.each(pagelen=pagelen)  # type: ignore[attr-defined]
-            ]
-            self._log.debug(
-                "deployment_env_variables_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                environment_uuid=environment_uuid,
-                count=len(variables),
-            )
-            return variables
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"list_deployment_environment_variables {workspace}/{repository_slug}/{environment_uuid}",
-            )
-
-    def create_deployment_environment_variable(
-        self,
-        workspace: str,
-        repository_slug: str,
-        environment_uuid: str,
-        key: str,
-        value: str,
-        secured: bool = False,
-    ) -> dict[str, Any]:
-        """Create a deployment environment variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            environment = repository.deployment_environments.get(environment_uuid)  # type: ignore[attr-defined]
-            variable = environment.deployment_environment_variables.create(key, value, secured)  # type: ignore[attr-defined]
-            data = self._variable_to_dict(variable)
-            self._log.info(
-                "deployment_env_variable_created",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                environment_uuid=environment_uuid,
-                key=key,
-                secured=secured,
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"create_deployment_environment_variable {workspace}/{repository_slug}/{environment_uuid}",
-            )
-
-    def update_deployment_environment_variable(
-        self,
-        workspace: str,
-        repository_slug: str,
-        environment_uuid: str,
-        variable_uuid: str,
-        *,
-        key: str | None = None,
-        value: str | None = None,
-        secured: bool | None = None,
-    ) -> dict[str, Any]:
-        """Update a deployment environment variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        update_payload: dict[str, Any] = {}
-        if key is not None:
-            update_payload["key"] = key
-        if value is not None:
-            update_payload["value"] = value
-        if secured is not None:
-            update_payload["secured"] = secured
-        if not update_payload:
-            raise VDSClientError(
-                "Provide at least one of --key/--value/--secured to update deployment environment variable",
-                context={
-                    "workspace": workspace,
-                    "repository": repository_slug,
-                    "environment_uuid": environment_uuid,
-                    "variable_uuid": variable_uuid,
-                },
-            )
-        try:
-            environment = repository.deployment_environments.get(environment_uuid)  # type: ignore[attr-defined]
-            variable = environment.deployment_environment_variables.get(variable_uuid)  # type: ignore[attr-defined]
-            variable.update(**update_payload)  # type: ignore[attr-defined]
-            data = self._variable_to_dict(variable)
-            self._log.info(
-                "deployment_env_variable_updated",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                environment_uuid=environment_uuid,
-                variable_uuid=variable_uuid,
-                fields=list(update_payload.keys()),
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"update_deployment_environment_variable {workspace}/{repository_slug}/{environment_uuid}/{variable_uuid}",
-            )
-
-    def delete_deployment_environment_variable(
-        self,
-        workspace: str,
-        repository_slug: str,
-        environment_uuid: str,
-        variable_uuid: str,
-    ) -> None:
-        """Delete a deployment environment variable."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            environment = repository.deployment_environments.get(environment_uuid)  # type: ignore[attr-defined]
-            variable = environment.deployment_environment_variables.get(variable_uuid)  # type: ignore[attr-defined]
-            variable.delete()  # type: ignore[attr-defined]
-            self._log.info(
-                "deployment_env_variable_deleted",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                environment_uuid=environment_uuid,
-                variable_uuid=variable_uuid,
-            )
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"delete_deployment_environment_variable {workspace}/{repository_slug}/{environment_uuid}/{variable_uuid}",
-            )
-
-    # --- Repository Issues (Cloud-only) ---
-    def list_repository_issues(
-        self,
-        workspace: str,
-        repository_slug: str,
-        *,
-        query: str | None = None,
-        sort: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """List repository issues."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            issues = [
-                self._issue_to_dict(issue)
-                for issue in repository.issues.each(q=query, sort=sort)  # type: ignore[attr-defined]
-            ]
-            self._log.debug(
-                "repository_issues_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                count=len(issues),
-                query=query,
-                sort=sort,
-            )
-            return issues
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_repository_issues {workspace}/{repository_slug}")
-
-    def create_repository_issue(
-        self,
-        workspace: str,
-        repository_slug: str,
-        title: str,
-        description: str = "",
-        *,
-        kind: str = "task",
-        priority: str = "major",
-    ) -> dict[str, Any]:
-        """Create an issue."""
-        if not title:
-            raise VDSClientError(
-                "Issue title must not be empty",
-                context={"workspace": workspace, "repository": repository_slug},
-            )
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            issue = repository.issues.create(title, description, kind, priority)  # type: ignore[attr-defined]
-            issue_data = self._issue_to_dict(issue)
-            self._log.info(
-                "repository_issue_created",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                issue_id=issue_data.get("id"),
-                kind=kind,
-                priority=priority,
-            )
-            return issue_data
-        except Exception as exc:
-            self._handle_api_error(exc, f"create_repository_issue {workspace}/{repository_slug}")
-
-    def get_repository_issue(
-        self,
-        workspace: str,
-        repository_slug: str,
-        issue_id: str | int,
-    ) -> dict[str, Any]:
-        """Get a single issue."""
-        issue = self._get_issue(workspace, repository_slug, issue_id)
-        data = self._issue_to_dict(issue)
-        self._log.debug(
-            "repository_issue_retrieved",
-            workspace=workspace,
-            repository_slug=repository_slug,
-            issue_id=issue_id,
-        )
-        return data
-
-    def update_repository_issue(
-        self,
-        workspace: str,
-        repository_slug: str,
-        issue_id: str | int,
-        *,
-        title: str | None = None,
-        description: str | None = None,
-        kind: str | None = None,
-        priority: str | None = None,
-        state: str | None = None,
-    ) -> dict[str, Any]:
-        """Update an issue."""
-        payload: dict[str, Any] = {}
-        if title is not None:
-            payload["title"] = title
-        if kind is not None:
-            payload["kind"] = kind
-        if priority is not None:
-            payload["priority"] = priority
-        if state is not None:
-            payload["state"] = state
-        if description is not None:
-            payload["content"] = {"raw": description}
-        if not payload:
-            raise VDSClientError(
-                "Provide at least one field to update issue",
-                context={
-                    "workspace": workspace,
-                    "repository": repository_slug,
-                    "issue_id": issue_id,
-                },
-            )
-        issue = self._get_issue(workspace, repository_slug, issue_id)
-        try:
-            issue.update(**payload)  # type: ignore[attr-defined]
-            data = self._issue_to_dict(issue)
-            self._log.info(
-                "repository_issue_updated",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                issue_id=issue_id,
-                fields=list(payload.keys()),
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"update_repository_issue {workspace}/{repository_slug}/{issue_id}",
-            )
-
-    def delete_repository_issue(
-        self,
-        workspace: str,
-        repository_slug: str,
-        issue_id: str | int,
-    ) -> None:
-        """Delete an issue."""
-        issue = self._get_issue(workspace, repository_slug, issue_id)
-        try:
-            issue.delete()  # type: ignore[attr-defined]
-            self._log.info(
-                "repository_issue_deleted",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                issue_id=issue_id,
-            )
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"delete_repository_issue {workspace}/{repository_slug}/{issue_id}",
-            )
-
-    # --- Pull Request Blockers (Cloud-only) ---
-    def list_pull_request_blockers(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pull_request_id: str | int,
-        *,
-        query: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """List pull request blockers."""
-        pull_request = self._get_pull_request(workspace, repository_slug, pull_request_id)
-        params = {"q": query} if query else None
-        try:
-            result = pull_request.get("blockers", params=params)  # type: ignore[attr-defined]
-            if isinstance(result, dict) and "values" in result:
-                blockers = result.get("values", [])
-            elif isinstance(result, list):
-                blockers = result
-            else:
-                blockers = [result] if result else []
-            blockers_data = [self._variable_to_dict(blocker) for blocker in blockers]
-            self._log.debug(
-                "pull_request_blockers_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pull_request_id=pull_request_id,
-                count=len(blockers_data),
-                query=query,
-            )
-            return blockers_data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"list_pull_request_blockers {workspace}/{repository_slug}/{pull_request_id}",
-            )
-
-    def add_pull_request_blocker(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pull_request_id: str | int,
-        message: str,
-        *,
-        reason: str | None = None,
-        severity: str | None = None,
-    ) -> dict[str, Any]:
-        """Add a blocker to a pull request."""
-        if not message:
-            raise VDSClientError(
-                "Blocker message must not be empty",
-                context={
-                    "workspace": workspace,
-                    "repository": repository_slug,
-                    "pull_request_id": pull_request_id,
-                },
-            )
-        pull_request = self._get_pull_request(workspace, repository_slug, pull_request_id)
-        payload: dict[str, Any] = {"message": message}
-        if reason:
-            payload["reason"] = reason
-        if severity:
-            payload["severity"] = severity
-        try:
-            blocker = pull_request.post("blockers", payload)  # type: ignore[attr-defined]
-            blocker_data = self._variable_to_dict(blocker)
-            self._log.info(
-                "pull_request_blocker_added",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pull_request_id=pull_request_id,
-                blocker_uuid=blocker_data.get("uuid"),
-            )
-            return blocker_data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"add_pull_request_blocker {workspace}/{repository_slug}/{pull_request_id}",
-            )
-
-    def delete_pull_request_blocker(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pull_request_id: str | int,
-        blocker_uuid: str,
-    ) -> None:
-        """Delete a pull request blocker."""
-        if not blocker_uuid:
-            raise VDSClientError(
-                "Blocker UUID is required",
-                context={
-                    "workspace": workspace,
-                    "repository": repository_slug,
-                    "pull_request_id": pull_request_id,
-                },
-            )
-        pull_request = self._get_pull_request(workspace, repository_slug, pull_request_id)
-        try:
-            pull_request.delete(f"blockers/{blocker_uuid}")  # type: ignore[attr-defined]
-            self._log.info(
-                "pull_request_blocker_deleted",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pull_request_id=pull_request_id,
-                blocker_uuid=blocker_uuid,
-            )
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"delete_pull_request_blocker {workspace}/{repository_slug}/{pull_request_id}/{blocker_uuid}",
-            )
-
-    def _get_pipeline(self, workspace: str, repository_slug: str, pipeline_uuid: str):
-        """Retrieve a pipeline object using the cloud API."""
-        repository = self._get_cloud_repository(workspace, repository_slug)
-        try:
-            return repository.pipelines.get(pipeline_uuid)  # type: ignore[attr-defined]
-        except Exception as exc:
-            self._handle_api_error(exc, f"pipeline {workspace}/{repository_slug}/{pipeline_uuid}")
-
-    def get_pipeline(self, workspace: str, repository_slug: str, pipeline_uuid: str) -> dict[str, Any]:
-        """Get pipeline details."""
-        pipeline = self._get_pipeline(workspace, repository_slug, pipeline_uuid)
-        data = self._pipeline_to_dict(pipeline)
-        self._log.debug(
-            "pipeline_retrieved",
-            workspace=workspace,
-            repository_slug=repository_slug,
-            pipeline_uuid=pipeline_uuid,
-        )
-        return data
-
-    def list_pipeline_steps(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pipeline_uuid: str,
-    ) -> list[dict[str, Any]]:
-        """List steps for a pipeline."""
-        pipeline = self._get_pipeline(workspace, repository_slug, pipeline_uuid)
-        try:
-            steps = [
-                self._pipeline_step_to_dict(step)
-                for step in pipeline.steps()  # type: ignore[attr-defined]
-            ]
-            self._log.debug(
-                "pipeline_steps_listed",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pipeline_uuid=pipeline_uuid,
-                count=len(steps),
-            )
-            return steps
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"list_pipeline_steps {workspace}/{repository_slug}/{pipeline_uuid}",
-            )
-
-    def get_pipeline_step(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pipeline_uuid: str,
-        step_uuid: str,
-    ) -> dict[str, Any]:
-        """Get details for a pipeline step."""
-        pipeline = self._get_pipeline(workspace, repository_slug, pipeline_uuid)
-        try:
-            step = pipeline.step(step_uuid)  # type: ignore[attr-defined]
-            data = self._pipeline_step_to_dict(step)
-            self._log.debug(
-                "pipeline_step_retrieved",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pipeline_uuid=pipeline_uuid,
-                step_uuid=step_uuid,
-            )
-            return data
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"get_pipeline_step {workspace}/{repository_slug}/{pipeline_uuid}/{step_uuid}",
-            )
-
-    def get_pipeline_step_log(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pipeline_uuid: str,
-        step_uuid: str,
-        *,
-        start: int | None = None,
-        end: int | None = None,
-    ) -> dict[str, Any]:
-        """Get log output for a pipeline step."""
-        pipeline = self._get_pipeline(workspace, repository_slug, pipeline_uuid)
-        try:
-            step = pipeline.step(step_uuid)  # type: ignore[attr-defined]
-            result = step.log(start=start, end=end)  # type: ignore[attr-defined]
-            total_size: int | None = None
-            content_bytes: bytes = b""
-            if isinstance(result, tuple):
-                total_size_raw, chunk = result
-                if isinstance(total_size_raw, (bytes, bytearray)):
-                    try:
-                        total_size = int(total_size_raw.decode())
-                    except (ValueError, AttributeError):
-                        total_size = None
-                else:
-                    try:
-                        total_size = int(total_size_raw)
-                    except (ValueError, TypeError):
-                        total_size = None
-                content_bytes = chunk or b""
-            elif isinstance(result, (bytes, bytearray)):
-                content_bytes = bytes(result)
-            elif result is None:
-                content_bytes = b""
-            else:
-                # Unknown type, attempt to convert to bytes
-                try:
-                    content_bytes = bytes(result)
-                except Exception:  # pragma: no cover - defensive
-                    content_bytes = str(result).encode("utf-8", errors="replace")
-
-            content_text = content_bytes.decode("utf-8", errors="replace")
-            size = total_size if total_size is not None else len(content_bytes)
-            payload = {
-                "workspace": workspace,
-                "repository": repository_slug,
-                "pipeline_uuid": pipeline_uuid,
-                "step_uuid": step_uuid,
-                "size": size,
-                "content": content_text,
-                "range_start": start,
-                "range_end": end,
-            }
-            self._log.debug(
-                "pipeline_step_log_retrieved",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pipeline_uuid=pipeline_uuid,
-                step_uuid=step_uuid,
-                size=size,
-            )
-            return payload
-        except Exception as exc:
-            self._handle_api_error(
-                exc,
-                f"get_pipeline_step_log {workspace}/{repository_slug}/{pipeline_uuid}/{step_uuid}",
-            )
-
-    def stop_pipeline(
-        self,
-        workspace: str,
-        repository_slug: str,
-        pipeline_uuid: str,
-    ) -> dict[str, Any]:
-        """Stop a running pipeline."""
-        pipeline = self._get_pipeline(workspace, repository_slug, pipeline_uuid)
-        try:
-            pipeline.stop()  # type: ignore[attr-defined]
-            self._log.info(
-                "pipeline_stopped",
-                workspace=workspace,
-                repository_slug=repository_slug,
-                pipeline_uuid=pipeline_uuid,
-            )
-            return {
-                "workspace": workspace,
-                "repository": repository_slug,
-                "pipeline_uuid": pipeline_uuid,
-                "status": "stopped",
-            }
-        except Exception as exc:
-            self._handle_api_error(exc, f"stop_pipeline {workspace}/{repository_slug}/{pipeline_uuid}")
-
-    # --- Cloud Workspace Operations (Cloud-only) ---
-    def list_workspaces(self) -> list[dict[str, Any]]:
-        """List all workspaces (Cloud-only).
-
-        Returns:
-            List of workspace dictionaries
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            # Access cloud API: cloud.workspaces.each()
-            workspaces = list(self._client.cloud.workspaces.each())  # type: ignore[attr-defined]
-            self._log.debug("workspaces_listed", count=len(workspaces))
-            return workspaces
-        except Exception as exc:
-            self._handle_api_error(exc, "list_workspaces")
-
-    def get_workspace(self, workspace_slug: str) -> dict[str, Any]:
-        """Get workspace by slug (Cloud-only).
-
-        Args:
-            workspace_slug: Workspace slug/identifier
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            # Access cloud API: cloud.workspaces.get(workspace_slug)
-            workspace = self._client.cloud.workspaces.get(workspace_slug)  # type: ignore[attr-defined]
-            self._log.debug("workspace_retrieved", workspace_slug=workspace_slug)
-            return workspace
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_workspace {workspace_slug}")
-
-    def get_workspace_permissions(self, workspace_slug: str) -> list[dict[str, Any]]:
-        """Get workspace permissions (Cloud-only).
-
-        Args:
-            workspace_slug: Workspace slug/identifier
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            workspace = self._client.cloud.workspaces.get(workspace_slug)  # type: ignore[attr-defined]
-            # Access: workplace.permissions.each()
-            permissions = list(workspace.permissions.each())  # type: ignore[attr-defined]
-            self._log.debug("workspace_permissions_retrieved", workspace_slug=workspace_slug, count=len(permissions))
-            return permissions
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_workspace_permissions {workspace_slug}")
-
-    def get_workspace_repository_permissions(
-        self, workspace_slug: str, repo_slug: str | None = None
-    ) -> dict[str, Any] | list[dict[str, Any]]:
-        """Get workspace repository permissions (Cloud-only).
-
-        Args:
-            workspace_slug: Workspace slug/identifier
-            repo_slug: Optional repository slug. If provided, returns permissions for that repo only.
-                      If None, returns all repository permissions.
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            workspace = self._client.cloud.workspaces.get(workspace_slug)  # type: ignore[attr-defined]
-            if repo_slug:
-                # Access: workplace.permissions.repositories(repo_slug)
-                permissions = workspace.permissions.repositories(repo_slug)  # type: ignore[attr-defined]
-            else:
-                # Access: workplace.permissions.repositories()
-                permissions = list(workspace.permissions.repositories())  # type: ignore[attr-defined]
-            self._log.debug(
-                "workspace_repository_permissions_retrieved",
-                workspace_slug=workspace_slug,
-                repo_slug=repo_slug,
-                is_list=repo_slug is None,
-            )
-            return permissions
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_workspace_repository_permissions {workspace_slug}/{repo_slug}")
-
-    def list_workspace_projects(self, workspace_slug: str) -> list[dict[str, Any]]:
-        """List projects in workspace (Cloud-only).
-
-        Args:
-            workspace_slug: Workspace slug/identifier
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            workspace = self._client.cloud.workspaces.get(workspace_slug)  # type: ignore[attr-defined]
-            # Access: workplace.projects.each()
-            projects = list(workspace.projects.each())  # type: ignore[attr-defined]
-            self._log.debug("workspace_projects_listed", workspace_slug=workspace_slug, count=len(projects))
-            return projects
-        except Exception as exc:
-            self._handle_api_error(exc, f"list_workspace_projects {workspace_slug}")
-
-    def get_workspace_project(self, workspace_slug: str, project_key: str) -> dict[str, Any]:
-        """Get project from workspace (Cloud-only).
-
-        Args:
-            workspace_slug: Workspace slug/identifier
-            project_key: Project key
-        """
-        if not self._settings.is_cloud_mode:
-            raise VDSClientError(
-                "Workspace operations are only available in Bitbucket Cloud mode",
-                context={"mode": self._settings.mode},
-            )
-        try:
-            workspace = self._client.cloud.workspaces.get(workspace_slug)  # type: ignore[attr-defined]
-            # Access: workplace.projects.get(project_key)
-            project = workspace.projects.get(project_key)  # type: ignore[attr-defined]
-            self._log.debug("workspace_project_retrieved", workspace_slug=workspace_slug, project_key=project_key)
-            return project
-        except Exception as exc:
-            self._handle_api_error(exc, f"get_workspace_project {workspace_slug}/{project_key}")
-
-    def download_archive(
-        self,
-        project_key: str,
-        repo_slug: str,
-        dest_fd: Any,
-        *,
-        at: str | None = None,
-        format: str = "zip",
-        path: str | None = None,
-        prefix: str | None = None,
-        chunk_size: int = 8192,
-    ) -> None:
-        """Download a repository archive to a file-like object.
-
-        Args:
-            project_key: Bitbucket project key.
-            repo_slug: Repository slug.
-            dest_fd: Writable binary file-like object (e.g. open file or BytesIO).
-            at: Commit/tag/branch reference (optional).
-            format: Archive format — "zip", "tar.gz", "tar", "tgz" (default "zip").
-            path: Limit archive to a specific path prefix (optional).
-            prefix: Custom top-level directory prefix inside the archive (optional).
-            chunk_size: Bytes per read chunk (default 8192).
-        """
-        try:
-            self._client.download_repo_archive(
-                project_key=project_key,
-                repository_slug=repo_slug,
-                dest_fd=dest_fd,
-                at=at,
-                format=format,
-                path=path,
-                prefix=prefix,
-                chunk_size=chunk_size,
-            )
-        except Exception as exc:
-            raise VDSClientError(str(exc)) from exc
-
-    def close(self) -> None:
-        """Close client (cleanup method for compatibility)."""
-        # atlassian-python-api doesn't require explicit cleanup
-        pass
-
-    def __enter__(self) -> BitbucketClient:
-        return self
-
-    def __exit__(self, exc_type, exc, tb) -> None:
-        self.close()
-
-
-__all__ = ["BitbucketClient"]