@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/bitbucket_orchestrator/ARCHITECTURE_ANALYSIS.md

@@ -0,0 +1,258 @@
+# Bitbucket Orchestrator Architecture Analysis
+
+## Overview
+
+This document verifies that there is **no duplicate logic** in the Bitbucket-related code across the VDS scripts
+ecosystem. All Bitbucket operations follow a clean, single-source-of-truth architecture.
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User/Agent Interface                     │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+         ┌───────────┴───────────┐
+         │                       │
+    ┌────▼────┐            ┌─────▼─────┐
+    │ VDS CLI │            │ MCP Server │
+    └────┬────┘            └─────┬─────┘
+         │                       │
+         │  Routes to            │  Calls VDS CLI
+         │                       │
+    ┌────▼───────────────────────▼────┐
+    │   Bitbucket Orchestrator         │
+    │   (Single Source of Truth)      │
+    └────┬────────────────────────────┘
+         │
+    ┌────▼────┐
+    │  SDK    │
+    │ (atlassian-python-api) │
+    └─────────┘
+```
+
+## Single Source of Truth
+
+### 1. Bitbucket Client (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/client.py`)
+
+**Status**: ✅ **ONLY** place that directly uses `AtlassianBitbucket` SDK
+
+```python
+from atlassian import Bitbucket as AtlassianBitbucket
+
+class BitbucketClient:
+    """Bitbucket client wrapper using atlassian-python-api SDK."""
+    def __init__(self, settings: BitbucketSettings):
+        # Only place that creates AtlassianBitbucket instance
+        self._client = AtlassianBitbucket(...)
+```
+
+**Verification**:
+
+- ✅ Only file that imports `AtlassianBitbucket`
+- ✅ All Bitbucket API calls go through this client
+- ✅ All error handling centralized here
+- ✅ All retry logic centralized here
+
+### 2. Configuration Loading (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/config.py`)
+
+**Status**: ✅ **ONLY** place that loads Bitbucket settings
+
+```python
+def load_settings(...) -> BitbucketSettings:
+    """Load orchestrator settings from the environment."""
+    # Only place that creates BitbucketSettings
+```
+
+**Verification**:
+
+- ✅ Only file that defines `BitbucketSettings`
+- ✅ Only file that implements `load_settings()` for Bitbucket
+- ✅ Consistent with other orchestrators (JIRA, Confluence)
+
+### 3. Client Factory (`bitbucket_orchestrator/src/vds_bitbucket_orchestrator/cli.py`)
+
+**Status**: ✅ **ONLY** place that builds BitbucketClient instances
+
+```python
+def _build_client(settings: BitbucketSettings) -> BitbucketClient:
+    """Build and return a configured BitbucketClient."""
+    return BitbucketClient(settings)
+```
+
+**Verification**:
+
+- ✅ Single factory function for client creation
+- ✅ Used consistently across all CLI commands
+- ✅ No duplicate client initialization logic
+
+## Integration Points (No Duplication)
+
+### 1. VDS CLI Router (`vds_cli/src/vds_cli/router.py`)
+
+**Status**: ✅ **NO** Bitbucket logic, only routing
+
+```python
+ORCHESTRATORS = {
+    "bitbucket": {
+        "module": "vds_bitbucket_orchestrator.cli",
+        "path": "bitbucket_orchestrator",
+    },
+}
+
+def run_orchestrator(service: str, args: list[str], script_dir: Path) -> int:
+    """Run orchestrator via uv."""
+    # Simply routes to orchestrator, no Bitbucket-specific logic
+```
+
+**Verification**:
+
+- ✅ No Bitbucket API calls
+- ✅ No Bitbucket client creation
+- ✅ No Bitbucket configuration loading
+- ✅ Pure routing logic only
+
+### 2. VDS CLI Main (`vds_cli/src/vds_cli/cli.py`)
+
+**Status**: ✅ **NO** Bitbucket logic, only command registration
+
+```python
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def bitbucket(ctx: typer.Context) -> None:
+    """Bitbucket operations."""
+    _run_service("bitbucket", list(ctx.args))  # Routes to orchestrator
+```
+
+**Verification**:
+
+- ✅ No Bitbucket API calls
+- ✅ No Bitbucket client creation
+- ✅ No Bitbucket configuration loading
+- ✅ Pure command registration only
+
+### 3. MCP Server Tools (`mcp_server/src/vds_mcp_server/tools/bitbucket_tools.py`)
+
+**Status**: ✅ **NO** direct Bitbucket API calls, uses VDS CLI
+
+```python
+def register_bitbucket_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register Bitbucket tools with MCP server."""
+    
+    @mcp.tool()
+    async def bitbucket_list_projects() -> str:
+        # Uses VDS CLI, not direct API calls
+        result = await execute_cli("bitbucket", "projects")
+```
+
+**Verification**:
+
+- ✅ No direct `AtlassianBitbucket` usage
+- ✅ No direct `BitbucketClient` usage
+- ✅ No direct `BitbucketSettings` usage
+- ✅ Uses VDS CLI as abstraction layer
+- ✅ Proper separation of concerns
+
+### 4. Git Orchestrator (`git_orchestrator/src/vds_git_orchestrator/orchestrator.py`)
+
+**Status**: ✅ **NO** Bitbucket-specific code
+
+**Verification**:
+
+- ✅ No Bitbucket imports
+- ✅ No Bitbucket API calls
+- ✅ Only Git operations (uses Bitbucket as Git remote, not API)
+- ✅ References `VDS_BITBUCKET_HTTP_BASE` for Git URL construction only
+
+## Method Mapping Verification
+
+All Bitbucket operations map to a single implementation:
+
+| Operation | Implementation Location | Duplicates? | |-----------|------------------------|-------------| |
+`create_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | | `get_repository()` |
+`bitbucket_orchestrator/client.py` | ❌ None | | `update_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | |
+`delete_repository()` | `bitbucket_orchestrator/client.py` | ❌ None | | `fork_repository()` |
+`bitbucket_orchestrator/client.py` | ❌ None | | `list_repositories()` | `bitbucket_orchestrator/client.py` | ❌ None | |
+`create_pull_request()` | `bitbucket_orchestrator/client.py` | ❌ None | | All other operations |
+`bitbucket_orchestrator/client.py` | ❌ None |
+
+## Configuration Verification
+
+All Bitbucket configuration loading maps to a single implementation:
+
+| Configuration | Implementation Location | Duplicates? | |---------------|------------------------|-------------| |
+`BitbucketSettings` | `bitbucket_orchestrator/config.py` | ❌ None | | `load_settings()` |
+`bitbucket_orchestrator/config.py` | ❌ None | | Environment variable parsing | `bitbucket_orchestrator/config.py` | ❌
+None |
+
+## Client Initialization Verification
+
+All Bitbucket client creation maps to a single implementation:
+
+| Initialization | Implementation Location | Duplicates? | |----------------|------------------------|-------------| |
+`BitbucketClient.__init__()` | `bitbucket_orchestrator/client.py` | ❌ None | | `_build_client()` |
+`bitbucket_orchestrator/cli.py` | ❌ None | | SDK client creation | `bitbucket_orchestrator/client.py` | ❌ None |
+
+## Test Coverage Verification
+
+All tests use the same client initialization pattern:
+
+```python
+# All tests use this pattern - no duplication
+@patch("vds_bitbucket_orchestrator.client.AtlassianBitbucket")
+def test_something(mock_bitbucket_class: Mock, mock_settings: BitbucketSettings):
+    client = BitbucketClient(mock_settings)
+    # Test implementation
+```
+
+**Verification**:
+
+- ✅ All tests mock `AtlassianBitbucket` at the same location
+- ✅ All tests use `BitbucketClient` from same module
+- ✅ All tests use `BitbucketSettings` from same module
+- ✅ No duplicate test setup logic
+
+## Summary
+
+### ✅ No Duplication Found
+
+1. **Single SDK Usage**: Only `bitbucket_orchestrator/client.py` uses `AtlassianBitbucket`
+1. **Single Configuration**: Only `bitbucket_orchestrator/config.py` handles settings
+1. **Single Client Factory**: Only `bitbucket_orchestrator/cli.py` has `_build_client()`
+1. **Clean Integration**: VDS CLI and MCP Server use orchestrator, don't duplicate logic
+1. **Consistent Patterns**: All components follow the same architecture
+
+### Architecture Benefits
+
+1. **Maintainability**: Changes to Bitbucket logic only need to be made in one place
+1. **Consistency**: All consumers get the same behavior
+1. **Testability**: Single point to mock for testing
+1. **Error Handling**: Centralized error handling and retry logic
+1. **Documentation**: Single source of truth for API practices
+
+### Verification Commands
+
+```bash
+# Verify only one place imports AtlassianBitbucket
+grep -r "from atlassian import Bitbucket\|AtlassianBitbucket" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/client.py
+
+# Verify only one place defines BitbucketSettings
+grep -r "class BitbucketSettings" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/config.py
+
+# Verify only one place has _build_client for Bitbucket
+grep -r "def _build_client.*Bitbucket" docs-nttc/scripts/
+# Result: Only bitbucket_orchestrator/cli.py
+```
+
+## Conclusion
+
+✅ **No duplicate logic found**. The Bitbucket orchestrator follows a clean, single-source-of-truth architecture with
+proper separation of concerns:
+
+- **Orchestrator**: Implements all Bitbucket logic
+- **VDS CLI**: Routes commands to orchestrator
+- **MCP Server**: Uses VDS CLI as abstraction layer
+- **Git Orchestrator**: Uses Bitbucket as Git remote only, no API calls
+
+All components work together without duplication, ensuring maintainability and consistency.

package/tools/vds-scripts/bitbucket_orchestrator/BITBUCKET_API_PRACTICES.md

@@ -0,0 +1,393 @@
+# Bitbucket API Practices - VDS Orchestrator
+
+This document outlines the practices used in the VDS Bitbucket Orchestrator, aligned with the
+[Atlassian Python API documentation](https://atlassian-python-api.readthedocs.io/bitbucket.html).
+
+## Implementation Approach
+
+### 1. SDK Usage
+
+We use the `atlassian-python-api` SDK (v4.0.7) as the **exclusive** method for all Bitbucket operations. This ensures:
+
+- ✅ Consistent API interactions across all operations
+- ✅ Automatic handling of Server/DC vs Cloud mode differences
+- ✅ Built-in retry logic and error handling
+- ✅ Type safety and validation
+
+**Reference**: [Atlassian Python API - BitBucket module](https://atlassian-python-api.readthedocs.io/bitbucket.html)
+
+### 2. Method Mapping
+
+Our client wrapper maps directly to SDK methods:
+
+| SDK Method | Our Wrapper | Documentation Reference | |------------|-------------|-------------------------| |
+`create_repo()` | `create_repository()` |
+[Create repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#create-a-new-repository) | | `get_repo()`
+| `get_repository()` |
+[Get repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-single-repository) | | `update_repo()` |
+`update_repository()` |
+[Update repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#update-single-repository) | |
+`fork_repository()` | `fork_repository()` |
+[Fork repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#fork-repo-inside-same-project) | |
+`fork_repository_new_project()` | `fork_repository()` |
+[Fork to new project](https://atlassian-python-api.readthedocs.io/bitbucket.html#fork-repo-to-new-project) | |
+`get_repo_labels()` | `get_repository_labels()` |
+[Get labels](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-labels-for-a-single-repository) | |
+`set_repo_label()` | `set_repository_label()` |
+[Set label](https://atlassian-python-api.readthedocs.io/bitbucket.html#set-label-for-a-single-repository) |
+
+### 3. Repository Management
+
+#### Create Repository
+
+```python
+# SDK method (from documentation)
+bitbucket.create_repo(project_key, repository, forkable=False, is_private=True)
+
+# Our implementation
+client.create_repository(
+    project_key="INSURANCE",
+    repository="vds-ai-memory",
+    forkable=False,
+    is_private=True
+)
+```
+
+**Reference**: [Create repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#create-a-new-repository)
+
+#### Get Repository
+
+```python
+# SDK method
+bitbucket.get_repo(project_key, repository_slug)
+
+# Our implementation
+client.get_repository(project_key="INSURANCE", repository_slug="vds-ai-memory")
+```
+
+**Reference**: [Get repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-single-repository)
+
+#### Update Repository
+
+```python
+# SDK method
+bitbucket.update_repo(project_key, repository_slug, description="Repo description")
+
+# Our implementation
+client.update_repository(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    description="Updated description"
+)
+```
+
+**Reference**: [Update repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#update-single-repository)
+
+#### Delete Repository
+
+```python
+# SDK method (DANGER!)
+bitbucket.delete_repo(project_key, repository_slug)
+
+# Our implementation
+client.delete_repository(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory"
+)
+```
+
+**⚠️ Warning**: This operation is irreversible. Use with extreme caution.
+
+**Reference**:
+[Delete repository](https://atlassian-python-api.readthedocs.io/bitbucket.html#delete-a-repository-danger)
+
+#### Fork Repository
+
+```python
+# SDK method - Fork within same project
+bitbucket.fork_repository(project_key, repository_slug, new_repository_slug)
+
+# SDK method - Fork to new project
+bitbucket.fork_repository_new_project(
+    project_key, repository_slug, new_project_key, new_repository_slug
+)
+
+# Our implementation (handles both cases)
+client.fork_repository(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    new_project_key="LEP",  # Optional - if None, forks within same project
+    new_repository_slug="vds-ai-memory-fork"
+)
+```
+
+**Reference**:
+
+- [Fork within same project](https://atlassian-python-api.readthedocs.io/bitbucket.html#fork-repo-inside-same-project)
+- [Fork to new project](https://atlassian-python-api.readthedocs.io/bitbucket.html#fork-repo-to-new-project)
+
+### 4. Project Management
+
+#### List Projects
+
+```python
+# SDK method
+bitbucket.project_list()
+
+# Our implementation
+client.list_projects(limit=50)
+```
+
+**Reference**: [Project list](https://atlassian-python-api.readthedocs.io/bitbucket.html#project-list)
+
+#### Create Project
+
+```python
+# SDK method
+bitbucket.create_project(key, name, description="My pretty project")
+
+# Our implementation
+client.create_project(
+    key="INSURANCE",
+    name="Insurance Platform",
+    description="Digital Insurance Platform"
+)
+```
+
+**Reference**: [Create project](https://atlassian-python-api.readthedocs.io/bitbucket.html#create-project)
+
+### 5. Pull Request Management
+
+#### List Pull Requests
+
+```python
+# SDK method
+bitbucket.get_pull_requests(project, repository, state='OPEN', order='newest', limit=100)
+
+# Our implementation
+client.list_pull_requests(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    state="OPEN",
+    order="newest",
+    limit=100
+)
+```
+
+**Reference**: [Get pull requests](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-pull-requests)
+
+#### Create Pull Request
+
+```python
+# SDK method
+bitbucket.open_pull_request(
+    source_project, source_repo, dest_project, dest_repo,
+    source_branch, destination_branch, title, description
+)
+
+# Our implementation
+client.create_pull_request(
+    source_project="INSURANCE",
+    source_repo="vds-ai-memory",
+    dest_project="INSURANCE",
+    dest_repo="vds-ai-memory",
+    source_branch="feature/new-feature",
+    destination_branch="main",
+    title="Add new feature",
+    description="Description of changes"
+)
+```
+
+**Reference**:
+[Create pull request](https://atlassian-python-api.readthedocs.io/bitbucket.html#create-a-new-pull-request-between-two-branches)
+
+### 6. Permission Management
+
+#### Grant Repository Permissions
+
+```python
+# SDK method - User permissions
+bitbucket.repo_grant_user_permissions(project_key, repo_key, username, permission)
+
+# SDK method - Group permissions
+bitbucket.repo_grant_group_permissions(project_key, repo_key, groupname, permission)
+
+# Our implementation
+client.grant_user_repository_permissions(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    username="developer",
+    permission="REPO_WRITE"
+)
+
+client.grant_group_repository_permissions(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    group_name="developers",
+    permission="REPO_READ"
+)
+```
+
+**Reference**:
+
+- [Grant user permissions](https://atlassian-python-api.readthedocs.io/bitbucket.html#grant-repository-permission-to-an-specific-user)
+- [Grant group permissions](https://atlassian-python-api.readthedocs.io/bitbucket.html#grant-repository-permission-to-an-specific-group)
+
+### 7. Code Operations
+
+#### Get Commits
+
+```python
+# SDK method
+bitbucket.get_commits(project, repository, hash_oldest, hash_newest, limit=99999)
+
+# Our implementation
+client.get_commits(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    from_hash="abc123",
+    to_hash="def456",
+    limit=50
+)
+```
+
+**Reference**: [Get commit list](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-commit-list-from-repo)
+
+#### Get Diff
+
+```python
+# SDK method
+bitbucket.get_diff(project, repository, path, hash_oldest, hash_newest)
+
+# Our implementation
+client.get_diff(
+    project_key="INSURANCE",
+    repository_slug="vds-ai-memory",
+    file_path="app/main.py",
+    from_hash="abc123",
+    to_hash="def456"
+)
+```
+
+**Reference**: [Get diff](https://atlassian-python-api.readthedocs.io/bitbucket.html#get-diff)
+
+### 8. Error Handling
+
+Our implementation wraps SDK methods with comprehensive error handling:
+
+```python
+def create_repository(self, project_key: str, repository: str, ...):
+    """Create a new repository."""
+    try:
+        result = self._client.create_repo(project_key, repository, ...)
+        self._log.info("repository_created", ...)
+        return result
+    except Exception as exc:
+        self._handle_api_error(exc, f"create_repository {repository}")
+```
+
+**Benefits**:
+
+- ✅ Consistent error types across all operations
+- ✅ Structured logging for debugging
+- ✅ Context preservation in error messages
+- ✅ Automatic retry for transient errors
+
+### 9. Cloud vs Server/DC Mode
+
+The SDK automatically handles differences between Bitbucket Cloud and Server/DC:
+
+```python
+# Our implementation detects mode automatically
+if settings.is_cloud_mode:
+    self._client = AtlassianBitbucket(
+        url=url, timeout=self._timeout, cloud=True,
+        workspace=settings.cloud_workspace, **auth_kwargs
+    )
+else:
+    self._client = AtlassianBitbucket(
+        url=url, timeout=self._timeout, **auth_kwargs
+    )
+```
+
+**Reference**: The SDK handles mode differences automatically based on URL and configuration.
+
+### 10. Retry Logic
+
+We implement exponential backoff for transient errors:
+
+```python
+@retry_with_backoff(max_retries=3, backoff_factor=1.0)
+def create_repository(self, ...):
+    # Automatically retries on transport/rate limit errors
+    ...
+```
+
+**Benefits**:
+
+- ✅ Handles rate limiting gracefully
+- ✅ Retries transient network errors
+- ✅ Prevents unnecessary failures
+
+## CLI Usage Examples
+
+### Create Repository
+
+```bash
+# Using VDS CLI
+uv run --project vds_cli vds-cli bitbucket repositories INSURANCE
+
+# Or using orchestrator directly
+cd vds-scripts/bitbucket_orchestrator
+uv run --project bitbucket_orchestrator python -m vds_bitbucket_orchestrator.cli repositories INSURANCE
+```
+
+### Create Repository via Python
+
+```python
+from vds_bitbucket_orchestrator.client import BitbucketClient
+from vds_bitbucket_orchestrator.config import load_settings
+
+settings = load_settings(strict=True)
+client = BitbucketClient(settings)
+
+# Create repository (as we did for vds-ai-memory)
+result = client.create_repository(
+    project_key="INSURANCE",
+    repository="vds-ai-memory",
+    forkable=False,
+    is_private=True
+)
+```
+
+## Best Practices
+
+1. **Always use the SDK methods**: Never make direct HTTP calls
+1. **Use our wrapper**: Provides consistent error handling and logging
+1. **Handle errors properly**: Use try/except with our error types
+1. **Log operations**: All operations are automatically logged
+1. **Respect rate limits**: Retry logic handles this automatically
+1. **Check mode**: Cloud vs Server/DC differences are handled automatically
+
+## Verification
+
+To verify our implementation matches the SDK:
+
+```bash
+# Check available SDK methods
+cd vds-scripts/bitbucket_orchestrator
+uv run --project bitbucket_orchestrator python -c "
+from atlassian import Bitbucket
+import inspect
+methods = [m for m in dir(Bitbucket) if 'repo' in m.lower() and not m.startswith('_')]
+print('\n'.join(sorted(methods)))
+"
+```
+
+## References
+
+- **Official Documentation**:
+  [Atlassian Python API - BitBucket module](https://atlassian-python-api.readthedocs.io/bitbucket.html)
+- **VDS Orchestrator**: `vds-scripts/bitbucket_orchestrator/`
+- **CLI Usage**: `vds-scripts/bitbucket_orchestrator/README.md`
+- **Repository**: `http://bitbucket.digital.vn/scm/insurance/vds-scripts.git`