headquarter/openspec/changes/archive/2026-05-19-smart-git-url-parsing/specs/spec.md

Smart Git URL Parsing Specification

Requirements

Functional Requirements

1. URL Detection: Detect when a provided URL is a browser URL rather than a git clone URL
2. URL Extraction: Extract the base repository URL from browser URLs
3. User Confirmation: Show extracted URL to user and ask for confirmation
4. Flexible Input: Allow users to proceed with original URL if they prefer
5. Multiple Hosts: Support GitHub, GitLab, Bitbucket, and generic git hosts

Non-Functional Requirements

1. Performance: URL parsing should be instant (< 100ms)
2. Accuracy: Should correctly identify 95%+ of browser URLs
3. User Experience: Clear, helpful messages without technical jargon
4. Backward Compatibility: Existing valid git URLs should continue to work

API Specification

POST /git-repositories/parse-url

Parse a URL and determine if it's a valid clone URL or needs correction.

Request Body:

{
  "url": "https://github.com/user/repo/tree/main"
}

Response 200:

{
  "original_url": "https://github.com/user/repo/tree/main",
  "base_url": "https://github.com/user/repo.git",
  "is_valid_clone_url": false,
  "needs_parsing": true,
  "host": "github.com",
  "message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
}

Response 200 (already valid):

{
  "original_url": "https://github.com/user/repo.git",
  "base_url": "https://github.com/user/repo.git",
  "is_valid_clone_url": true,
  "needs_parsing": false,
  "host": "github.com",
  "message": "Valid git repository URL"
}

Enhanced POST /projects/{project_id}/repositories

Enhanced to return suggestions when URL needs parsing.

New 422 Response:

{
  "detail": "The provided URL appears to be a browser URL, not a git clone URL",
  "suggested_url": "https://github.com/user/repo.git",
  "original_url": "https://github.com/user/repo/tree/main",
  "error_code": "URL_NEEDS_PARSING"
}

Request Body (with force flag):

{
  "name": "my-repo",
  "remote_url": "https://github.com/user/repo/tree/main",
  "is_mirror": false,
  "force_original_url": true
}

Data Model

URLParseResult

class URLParseResult:
    original_url: str
    base_url: str | None
    is_valid_clone_url: bool
    needs_parsing: bool
    host: str | None
    message: str
    error_code: str | None

URL Parsing Rules

Supported Hosts

• github.com
• gitlab.com
• bitbucket.org
• Any custom domain with git hosting

GitHub URL Patterns

https://github.com/{owner}/{repo} → valid
https://github.com/{owner}/{repo}.git → valid
https://github.com/{owner}/{repo}/tree/{branch} → extract base
https://github.com/{owner}/{repo}/blob/{branch}/{path} → extract base
https://github.com/{owner}/{repo}/pull/{number} → extract base
https://github.com/{owner}/{repo}/issues/{number} → extract base
https://github.com/{owner}/{repo}/actions → extract base

GitLab URL Patterns

https://gitlab.com/{owner}/{repo} → valid
https://gitlab.com/{owner}/{repo}.git → valid
https://gitlab.com/{owner}/{repo}/-/tree/{branch} → extract base
https://gitlab.com/{owner}/{repo}/-/blob/{branch}/{path} → extract base
https://gitlab.com/{owner}/{repo}/-/merge_requests/{number} → extract base

Bitbucket URL Patterns

https://bitbucket.org/{owner}/{repo} → valid
https://bitbucket.org/{owner}/{repo}.git → valid
https://bitbucket.org/{owner}/{repo}/src/{branch} → extract base

Extraction Algorithm

1. Parse URL components (scheme, netloc, path, query)
2. Remove query parameters entirely
3. Split path by /
4. Remove trailing segments that indicate non-repo paths:
   • tree/*, blob/*, pull/*, issues/*, actions
   • -/tree/*, -/blob/*, -/merge_requests/*
   • src/*
5. Reconstruct URL with remaining path
6. Add .git suffix if missing (for HTTPS URLs)
7. Return extracted URL

Frontend Specification

URL Input Component

• Input field for repository URL
• Real-time validation (debounced 300ms)
• Visual indicators:
  • 🟢 Green border: Valid git URL
  • 🟡 Yellow border: Browser URL detected, suggestion shown
  • 🔴 Red border: Invalid/malformed URL
• Inline suggestion banner below input:

  ⚠️ This looks like a browser URL
  Suggested: https://github.com/user/repo.git
  [Use Suggested] [Keep Original]
  

Confirmation Dialog

Shown when backend returns 422 with suggestion:

┌─────────────────────────────────────┐
│ URL Correction Suggestion            │
├─────────────────────────────────────┤
│                                      │
│ The URL you entered appears to be   │
│ a browser URL, not a git clone URL. │
│                                      │
│ Original:                            │
│ https://github.com/user/repo/tree/main│
│                                      │
│ Suggested repository URL:            │
│ https://github.com/user/repo.git     │
│                                      │
│ [Use Suggested URL]  [Use Original] │
│ [Cancel]                            │
└─────────────────────────────────────┘

Error Codes

Error Code	Description	User Message
URL_NEEDS_PARSING	Browser URL detected	"This looks like a browser URL. Did you mean: {suggested_url}?"
INVALID_URL	Malformed URL	"Please enter a valid URL"
UNSUPPORTED_HOST	Unknown git host	"This git host is not supported"
CLONE_FAILED	Git clone failed	"Failed to clone repository: {error}"
AUTH_REQUIRED	Private repo, need auth	"This repository requires authentication"

Testing Strategy

Unit Tests (URL Parsing)

• Test all GitHub URL patterns
• Test all GitLab URL patterns
• Test all Bitbucket URL patterns
• Test valid URLs pass through unchanged
• Test edge cases (subgroups, nested paths, etc.)

Integration Tests

• Test parse-url endpoint with various URLs
• Test repository creation with browser URL (should suggest correction)
• Test repository creation with force flag
• Test clone operation with corrected URL

Frontend Tests

• Test URL input validation states
• Test suggestion banner display
• Test confirmation dialog flow
• Test acceptance/rejection of suggestions