WizardMerge/.github/issues/06-multi-platform-support.md

title, labels, assignees, milestone

title	labels	assignees	milestone
Phase 2.5: Multi-Platform Support (Bitbucket, Azure DevOps, Gitea/Forgejo)	enhancement phase-2 git-platforms medium-priority		Phase 2 - Intelligence & Usability

Overview

Extend PR/MR conflict resolution to support additional Git platforms beyond GitHub and GitLab. Implement an extensible platform pattern that makes it easy to add new platforms in the future.

Related Roadmap Section

Phase 2.5 - Additional Platform Support

Current Status

✅ Implemented:

• GitHub (GitHub API v3)
• GitLab (GitLab API)

🔜 To Implement:

• Bitbucket (Cloud and Server)
• Azure DevOps (Cloud and Server)
• Gitea/Forgejo

Platforms to Support

1. Bitbucket

Bitbucket Cloud

• API: Bitbucket Cloud REST API 2.0
• URL Pattern: https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}
• Authentication:
  • App passwords
  • OAuth 2.0
• API Endpoints:
  • GET /2.0/repositories/{workspace}/{repo}/pullrequests/{number}
  • GET /2.0/repositories/{workspace}/{repo}/src/{commit}/{path}
  • GET /2.0/repositories/{workspace}/{repo}/diff/{spec}

Bitbucket Server (Self-Hosted)

• API: Bitbucket Server REST API 1.0
• URL Pattern: https://{server}/projects/{project}/repos/{repo}/pull-requests/{number}
• Authentication: Personal Access Tokens, HTTP Basic Auth
• API Endpoints:
  • GET /rest/api/1.0/projects/{project}/repos/{repo}/pull-requests/{number}
  • GET /rest/api/1.0/projects/{project}/repos/{repo}/browse/{path}?at={ref}

Implementation Priority: HIGH

2. Azure DevOps

Azure DevOps Cloud

• API: Azure DevOps REST API 6.0
• URL Pattern: https://dev.azure.com/{organization}/{project}/_git/{repo}/pullrequest/{number}
• Authentication: Personal Access Tokens (PAT)
• API Endpoints:
  • GET /{organization}/{project}/_apis/git/repositories/{repo}/pullrequests/{number}
  • GET /{organization}/{project}/_apis/git/repositories/{repo}/items?path={path}&version={ref}

Azure DevOps Server (On-Premises)

• API: Same as cloud
• URL Pattern: https://{server}/{organization}/{project}/_git/{repo}/pullrequest/{number}
• Authentication: PAT, NTLM, Kerberos

Implementation Priority: HIGH (widely used in enterprise)

3. Gitea / Forgejo

• API: Gitea/Forgejo API (OpenAPI compatible)
• URL Pattern: https://{server}/{owner}/{repo}/pulls/{number}
• Authentication: Access tokens
• API Endpoints:
  • GET /api/v1/repos/{owner}/{repo}/pulls/{number}
  • GET /api/v1/repos/{owner}/{repo}/contents/{path}?ref={ref}
• Note: Forgejo is a fork of Gitea with compatible API

Implementation Priority: MEDIUM (growing community adoption)

Extensible Platform Pattern

Design Goals

1. Easy to add new platforms - Minimal code changes
2. Abstract common operations - Unified interface
3. Platform-specific customization - Handle API differences
4. Configuration-driven - Define platforms via config
5. Plugin system - External platform implementations

Abstract Interface

// Abstract Git platform API
class GitPlatformAPI {
public:
  virtual ~GitPlatformAPI() = default;
  
  // Core operations
  virtual PullRequest fetch_pr_info(
    const std::string& owner,
    const std::string& repo,
    const std::string& pr_number,
    const std::string& token
  ) = 0;
  
  virtual std::string fetch_file_content(
    const std::string& owner,
    const std::string& repo,
    const std::string& file_path,
    const std::string& ref,
    const std::string& token
  ) = 0;
  
  // Optional operations
  virtual bool create_comment(
    const std::string& owner,
    const std::string& repo,
    const std::string& pr_number,
    const std::string& comment,
    const std::string& token
  ) { return false; }
  
  virtual bool update_pr_status(
    const std::string& owner,
    const std::string& repo,
    const std::string& pr_number,
    const std::string& status,
    const std::string& token
  ) { return false; }
  
  // Metadata
  virtual std::string platform_name() const = 0;
  virtual std::string api_base_url() const = 0;
};

Platform Registry

class GitPlatformRegistry {
public:
  // Register a platform implementation
  void register_platform(
    const std::string& name,
    std::unique_ptr<GitPlatformAPI> api
  );
  
  // Detect platform from URL
  GitPlatform detect_platform(const std::string& url);
  
  // Get platform implementation
  GitPlatformAPI* get_platform(GitPlatform platform);
  
  // Parse PR URL (delegates to platform)
  PRInfo parse_pr_url(const std::string& url);
};

Platform Detection

struct URLPattern {
  std::string pattern;      // Regex pattern
  GitPlatform platform;     // Platform enum
  std::vector<std::string> capture_groups;  // owner, repo, pr_number, etc.
};

class PlatformDetector {
  std::vector<URLPattern> patterns;
  
  GitPlatform detect(const std::string& url) {
    for (const auto& pattern : patterns) {
      if (std::regex_match(url, pattern.pattern)) {
        return pattern.platform;
      }
    }
    return GitPlatform::Unknown;
  }
};

Configuration-Based Platform Definitions

# platforms.yml
platforms:
  - name: bitbucket_cloud
    url_pattern: "(?:https?://)?bitbucket\\.org/([^/]+)/([^/]+)/pull-requests/(\\d+)"
    api_base_url: "https://api.bitbucket.org/2.0"
    auth_type: bearer_token
    endpoints:
      pr_info: "/repositories/{owner}/{repo}/pullrequests/{number}"
      file_content: "/repositories/{owner}/{repo}/src/{ref}/{path}"
    field_mappings:
      base_ref: "destination.branch.name"
      head_ref: "source.branch.name"
  
  - name: azure_devops
    url_pattern: "https://dev\\.azure\\.com/([^/]+)/([^/]+)/_git/([^/]+)/pullrequest/(\\d+)"
    api_base_url: "https://dev.azure.com/{organization}/{project}/_apis"
    auth_type: basic_auth
    endpoints:
      pr_info: "/git/repositories/{repo}/pullrequests/{number}?api-version=6.0"
      file_content: "/git/repositories/{repo}/items?path={path}&version={ref}&api-version=6.0"

Implementation Steps

1. Refactor Existing Code (1 week)

• Extract GitHub implementation to GitHubAPI class
• Extract GitLab implementation to GitLabAPI class
• Create GitPlatformAPI interface
• Create GitPlatformRegistry
• Update PRController to use registry

2. Implement Bitbucket Support (1.5 weeks)

• Create BitbucketCloudAPI class

• Implement PR info fetching

• Implement file content fetching

• Handle authentication (App passwords)

• Add URL pattern to detector

• Unit tests

• Integration tests with Bitbucket API

• Create BitbucketServerAPI class (separate from Cloud)

• Handle different API structure

• Test with Bitbucket Server instance

3. Implement Azure DevOps Support (1.5 weeks)

• Create AzureDevOpsAPI class
• Implement PR info fetching
• Implement file content fetching
• Handle PAT authentication
• Add URL pattern to detector
• Handle both Cloud and Server versions
• Unit tests
• Integration tests

4. Implement Gitea/Forgejo Support (1 week)

• Create GiteaAPI class
• Implement PR info fetching
• Implement file content fetching
• Handle token authentication
• Add URL pattern to detector
• Unit tests
• Integration tests

5. Configuration System (1 week)

• Design YAML schema for platform definitions
• Implement YAML parser
• Create ConfigBasedPlatform class
• Support dynamic platform loading
• Documentation for adding custom platforms

6. Testing & Documentation (1 week)

• Comprehensive unit tests for all platforms
• Integration tests with real APIs (use test repos)
• Update README.md with examples for all platforms
• Create platform implementation guide
• API documentation

Example Usage

Bitbucket Cloud

# CLI
./wizardmerge-cli-frontend pr-resolve \
  --url https://bitbucket.org/myworkspace/myrepo/pull-requests/42 \
  --token <app_password>

# Or with environment variable
export BITBUCKET_TOKEN=<app_password>
./wizardmerge-cli-frontend pr-resolve \
  --url https://bitbucket.org/myworkspace/myrepo/pull-requests/42

# HTTP API
curl -X POST http://localhost:8080/api/pr/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "pr_url": "https://bitbucket.org/myworkspace/myrepo/pull-requests/42",
    "api_token": "<app_password>"
  }'

Azure DevOps

# CLI
./wizardmerge-cli-frontend pr-resolve \
  --url https://dev.azure.com/myorg/myproject/_git/myrepo/pullrequest/123 \
  --token <pat>

# HTTP API
curl -X POST http://localhost:8080/api/pr/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "pr_url": "https://dev.azure.com/myorg/myproject/_git/myrepo/pullrequest/123",
    "api_token": "<pat>"
  }'

Gitea

# CLI
./wizardmerge-cli-frontend pr-resolve \
  --url https://gitea.mycompany.com/owner/repo/pulls/5 \
  --token <access_token>

Platform Implementation Guide

For future contributors who want to add a new platform:

Step 1: Create Platform API Class

class MyPlatformAPI : public GitPlatformAPI {
public:
  PullRequest fetch_pr_info(...) override {
    // 1. Build API URL
    std::string url = api_base_url + "/pr/endpoint";
    
    // 2. Make HTTP request with auth
    auto response = http_client.get(url, headers);
    
    // 3. Parse JSON response
    Json::Value root = parse_json(response.body);
    
    // 4. Map to PullRequest structure
    PullRequest pr;
    pr.base_ref = root["target_branch"].asString();
    pr.head_ref = root["source_branch"].asString();
    // ... map other fields
    
    return pr;
  }
  
  std::string fetch_file_content(...) override {
    // Similar pattern
  }
  
  std::string platform_name() const override { return "MyPlatform"; }
};

Step 2: Add URL Pattern

// In git_platform_client.cpp
std::regex myplatform_regex(
  R"((?:https?://)?myplatform\.com/([^/]+)/([^/]+)/pr/(\\d+))"
);

if (std::regex_match(pr_url, match, myplatform_regex)) {
  platform = GitPlatform::MyPlatform;
  // Extract owner, repo, pr_number from match groups
}

Step 3: Register in Registry

// In main() or init()
platform_registry.register_platform(
  "myplatform",
  std::make_unique<MyPlatformAPI>()
);

Step 4: Add Tests

TEST(MyPlatformAPITest, FetchPRInfo) {
  MyPlatformAPI api;
  auto pr = api.fetch_pr_info("owner", "repo", "123", "token");
  ASSERT_EQ(pr.number, "123");
  ASSERT_FALSE(pr.base_ref.empty());
}

Acceptance Criteria

• Bitbucket Cloud support working
• Bitbucket Server support working
• Azure DevOps Cloud support working
• Azure DevOps Server support working
• Gitea/Forgejo support working
• Platform registry implemented
• URL detection automatic
• Configuration-based platforms supported
• All platforms tested with real APIs
• Documentation complete
• Implementation guide available

Priority

MEDIUM-HIGH - Important for enterprise adoption and wider user base.

Estimated Effort

6-8 weeks total

Dependencies

• PR resolution feature ✅
• Git CLI integration ✅

Related Issues

• #TBD (Phase 2 tracking)
• #TBD (API improvements)

Success Metrics

• Support 5+ major Git platforms
• <5% error rate for each platform
• Easy to add new platforms (<1 day of work)
• 90% user satisfaction across platforms