@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/BITBUCKET_API_PRACTICES.md

@@ -1,393 +0,0 @@
-# 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
-./scripts/worktree_uv.sh 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`

package/skills/vds-skill/vds-scripts/bitbucket_orchestrator/EVALUATION_REPORT.md

@@ -1,61 +0,0 @@
-# Bitbucket CLI Evaluation Report
-
-**Date**: 2026-01-28
-**Evaluator**: Antigravity
-**Scope**: `vds-cli bitbucket` vs Official SDK vs Modern Use Cases
-
-## Executive Summary
-
-The `vds-cli bitbucket` implementation is a robust, production-grade wrapper around the `atlassian-python-api` SDK. It exposes approximately **51%** of the SDK's functionality, focusing heavily on developer and platform engineering workflows (Repos, PRs, Permissions, Pipelines).
-
-It outperforms standard "scripting" by providing uniform output (JSON/Markdown), integrated error handling, and cross-platform compatibility via `vds-cli`.
-
-## 1. Feature Comparison
-
-| Feature Category | Official SDK (`atlassian-python-api`) | `vds-cli bitbucket` | Status |
-| :--- | :--- | :--- | :--- |
-| **Repository CRUD** | Create, Get, Update, Delete, Fork | ✅ Fully Supported | Parity |
-| **PR Management** | Create, Diff, Comment, Merge, Decline, Activities | ✅ Fully Supported | Parity (Enhanced with Diff/Markdown) |
-| **Permissions** | Users, Groups, Repo, Project, Branch | ✅ Supported | Parity |
-| **Pipelines** | List, Trigger, Log, Stop, Variables | ✅ Supported (Cloud) | Parity (Cloud) |
-| **Branching** | Create, Delete, Models, Default Branch | ✅ Supported | Parity |
-| **Code Insights** | Reports, Annotations | ✅ Supported (Cloud) | Parity (Cloud) |
-| **Build Status** | Get Commit/Build Statuses (Server/DC) | ❌ **Missing** | **Gap** |
-| **Search** | File Search, Code Search | ✅ Supported | Parity |
-| **Snippets** | CRUD | ❌ Missing | Low Priority |
-| **Admin** | License, System Info, User Management | ❌ Missing | Out of Scope |
-
-## 2. "Modern Use Case" Evaluation
-
-### ✅ Strengths
-- **GitOps Ready**: Full support for creating PRs, managing branch permissions, and configuring webhooks via CLI makes it suitable for CI/CD automation.
-- **Platform Engineering**: Robust permission management (`grant-group-repo`) allows automated onboarding and security compliance enforcement.
-- **Developer Experience**: "Draft" PR support and rich Markdown reporting align with modern code review practices.
-
-### ⚠️ Gaps & Opportunities
-1.  **CI/CD Integration (Server/DC)**:
-    - **Gap**: Lacks `get-build-status` for Bitbucket Server/Data Center. Developers cannot verify if a Jenkins/Bamboo build passed for a specific commit via CLI.
-    - **Impact**: Harder to script "merge if green" logic for Server environments.
-    - **SDK Support**: The `atlassian-python-api` SDK supports this via `get_build_status(commit, key=None, limit=None)`. This method is available in the SDK but not exposed in our CLI.
-
-2.  **Semantic Search**:
-    - **Gap**: Current search is keyword-based. Modern tools (like `grepai` in VDS) use vector search.
-    - **Recommendation**: Integrate `grepai` or similar for "Find code doing X" capabilities.
-
-3.  **Bulk Operations**:
-    - **Gap**: No native `for-each-repo` command.
-    - **Impact**: Updating descriptions or permissions across 50 repos requires external bash looping.
-
-4.  **Auto-Merge Strategies**:
-    - **Gap**: No "Merge when pipeline succeeds" flag/command.
-    - **Impact**: Users must poll for status (which is also missing for Server) and then merge.
-
-## 3. Recommendations
-
-1.  **Implement `commit-status`**: Add a command to retrieve build statuses for a commit (critical for Server/DC CI pipelines). The underlying SDK method `get_build_status` is ready to use.
-2.  **Bulk Operations Pattern**: Document or implement a pattern for applying commands to multiple repositories (e.g., accepting a list of repos from stdin).
-3.  **Semantic Search Integration**: Leverage the existing `grepai-skill` for code search instead of relying solely on Bitbucket's native keyword search.
-
-## 4. Conclusion
-
-The current implementation is **Excellent** for its intended scope. It provides a safer, more structured alternative to direct API calls or `curl` scripts. Addressing the "Build Status" gap for Server/DC would bring it to near-complete parity for DevOps workflows.