Handoff: VSCode Extension — Git Clone Support

From: S254 (Git Operations UI/UX) For: Next session working on vitto-vscode-extension Priority: Medium — enables the "GitHub-like clone experience" devs expect

Context

S254 set up the server infrastructure for cloning platform repos from Hetzner:

• SSH clone: [email protected]:platforms/{space}/{universe} — works, tested
• HTTPS clone: https://sandbox.gograb.space/git-http/{space}/{universe} — configured via NGINX + fcgiwrap + git-http-backend
• Auth: SSH key-based (git user) for SSH; HTTP Basic (username: platform, password: API key) for HTTPS
• Backend endpoint: GET /git/repos/:space/:universe/clone-urls returns both URLs
• Frontend: GitOperationsApiService.getCloneUrls(space, universe) — already available

The web UI now shows a "Clone" dropdown in the git-graph header with SSH/HTTPS URLs and copy buttons. But the real leverage is in the IDE — one-click clone from VSCode.

What to Build

1. "Clone Platform Repository" Command

Register a VSCode command: vitto.clonePlatformRepo

Flow:

1. User invokes from command palette or sidebar
2. Extension calls backend to get available repos (or uses current workspace context for space/universe)
3. Shows QuickPick with repo list (if multiple) or auto-selects (if in studio context)
4. Fetches clone URLs via GET /sandbox-api/git/repos/:space/:universe/clone-urls
5. Shows QuickPick: "SSH" or "HTTPS"
6. Calls vscode.commands.executeCommand('git.clone', selectedUrl) — this opens VSCode's native clone flow with the URL pre-filled
7. User picks a local folder, VSCode clones and opens

2. Sidebar Button (Vitto Panel)

In the Vitto sidebar panel, when the user has an active universe context:

• Show a "Clone Repository" button under the universe info
• One-click: skips the QuickPick repo selection, goes straight to SSH/HTTPS choice

3. Clone URL in Status Bar

When the extension detects the current workspace is inside a cloned platform repo:

• Show the repo name in the status bar
• Click opens a QuickPick with: "Copy SSH URL", "Copy HTTPS URL", "Open in GoGrab Studio"

Key Files

API Endpoint

GET /sandbox-api/git/repos/:space/:universe/clone-urls
Headers: X-API-Key: {from .env or extension settings}

Response:
{
  "ssh": "[email protected]:platforms/chrome-space-1/conejo",
  "https": "https://sandbox.gograb.space/git-http/chrome-space-1/conejo",
  "repoPath": "chrome-space-1/conejo"
}

Server Setup (Already Done)

• AX42-U (sandbox.gograb.space):

  • git user created with git-shell
  • SSH authorized_keys at /home/git/.ssh/authorized_keys
  • Repos symlinked: /home/git/platforms -> /data/platforms
  • NGINX /git-http/ location configured with fcgiwrap + git-http-backend
  • HTTP Basic auth via /etc/nginx/.git-htpasswd
  • All new repos auto-configured with receive.denyCurrentBranch=updateInstead and update-server-info

• Adding new developer SSH keys: SSH into AX42-U as root, append to /home/git/.ssh/authorized_keys

Routing Constraint (Critical)

The extension currently only talks to ai-api (backend-ai-api, port 3001). The clone-urls endpoint lives on sandbox-orchestrator (Hetzner). The extension should NOT know about infrastructure topology.

Recommended approach: Add a proxy route on ai-api that forwards git clone-url requests to the orchestrator. The extension stays single-backend — one URL, ai-api proxies what it needs.

Extension → ai-api:3001/git/clone-urls/:space/:universe → sandbox-orchestrator/git/repos/:space/:universe/clone-urls

This follows the same pattern as RemoteGitProviderService on backend-api, which already proxies git calls to the orchestrator. The ai-api controller just needs a thin forwarding endpoint.

Do NOT: Add a sandboxUrl config to the extension, or have it talk directly to the orchestrator. That leaks infrastructure details into client config.

Edge Cases

• No repo yet: The universe hasn't had a platform generated → clone-urls returns 404 → show "Generate a platform first"
• Repo deleted: Same as above
• SSH key not configured: SSH clone will fail with permission denied → show helpful error with link to docs on adding SSH keys
• HTTPS auth: The API key is needed as HTTP password. The extension should store it in VSCode's SecretStorage, not in settings.json
• Multiple Hetzner servers: Currently repos are on AX42-U only. If repos move to AX102-U, the clone URLs will automatically reflect this (derived from PLATFORM_GIT_SERVER_URL)

Testing

1. Generate a platform for a universe
2. Verify curl -H "X-API-Key: ..." https://sandbox.gograb.space/git/repos/{space}/{universe}/clone-urls returns URLs
3. Test SSH clone: git clone [email protected]:platforms/{space}/{universe} /tmp/test
4. Test HTTPS clone: git clone https://platform:{API_KEY}@sandbox.gograb.space/git-http/{space}/{universe} /tmp/test
5. Test push: make a change, commit, git push origin develop