Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

36.8 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""
Git Repository Accessor.

Fetches git repositories and zip archives of codebases to local directories.
This is the DataAccessor layer extracted from CodeRepositoryParser.
"""

import asyncio
import contextlib
import os
import shutil
import signal
import stat
import tempfile
import urllib.request
import zipfile
from pathlib import Path, PurePosixPath
from typing import Optional, Tuple, Union
from urllib.parse import quote, urlparse

from openviking.parse.network import (
    ParserNetworkContext,
    ParserNetworkOperation,
    open_parser_url,
    overlay_parser_subprocess_env,
)
from openviking.parse.temp import get_parser_download_temp_dir
from openviking.utils import (
    is_github_url,
    is_gitlab_url,
    parse_code_hosting_url,
    parse_git_repo_url,
)
from openviking.utils.code_hosting_utils import (
    is_git_repo_url,
    validate_git_ssh_uri,
)
from openviking.utils.git_auth import (
    build_git_http_auth_env,
    is_git_https_url,
    parse_git_http_auth_config,
    raise_git_auth_error,
)
from openviking_cli.utils.logger import get_logger

from .base import DataAccessor, LocalResource, SourceType

logger = get_logger(__name__)


class GitAccessor(DataAccessor):
    """
    Accessor for Git repositories and code archives.

    Supports:
    - Git SSH URLs: [email protected]:org/repo.git
    - Git HTTP/HTTPS URLs: https://github.com/org/repo.git
    - GitHub/GitLab repository pages: https://github.com/org/repo
    - Local ZIP files (containing code repositories)
    """

    PRIORITY = 80  # Higher than generic HTTP, lower than specific services
    # Upper bound for reaping the git process tree after cancellation. The
    # tree is SIGKILLed as a group, so this only guards pathological reap
    # delays and must stay short to avoid pinning the caller's slot.
    CANCEL_REAP_TIMEOUT = 1.0

    @property
    def priority(self) -> int:
        return self.PRIORITY

    def can_handle(self, source: Union[str, Path], **kwargs) -> bool:
        """
        Check if this accessor can handle the source.

        Handles:
        - git@ SSH URLs
        - git://, ssh:// URLs
        - Configured code-hosting repository URLs (http/https)
        - Local paths ending with .git (NOT .zip - those go to ZipParser)
        """
        source_str = str(source)

        # Git protocol URLs
        if source_str.startswith(("git@", "git://", "ssh://")):
            try:
                if source_str.startswith("git@"):
                    validate_git_ssh_uri(source_str)
                return is_git_repo_url(source_str)
            except ValueError:
                return False

        # HTTP/HTTPS URLs to code hosting repos
        if source_str.startswith(("http://", "https://")):
            return is_git_repo_url(source_str)

        # Local .git files (NOT .zip - .zip goes to ZipParser via LocalAccessor)
        if isinstance(source, Path):
            path = source
        else:
            path = Path(source_str)

        suffix = path.suffix.lower()
        return suffix == ".git"

    async def access(self, source: Union[str, Path], **kwargs) -> LocalResource:
        """
        Fetch the git repository or code archive to a local directory.

        Args:
            source: Repository URL (git/http) or local zip path
            **kwargs: Additional arguments (branch, commit, etc.)

        Returns:
            LocalResource pointing to the local directory
        """
        source_str = str(source)
        temp_local_dir = None
        branch = kwargs.get("branch") or kwargs.get("ref")
        commit = kwargs.get("commit")
        if commit:
            branch = None
        auth_config = parse_git_http_auth_config(kwargs.get("auth_config"), source_str)
        git_env = None
        used_git_clone = False
        # Exact immutable revision fetched. Branch tracking resolves this from
        # the remote/local HEAD; commit-only imports use the supplied commit.
        resolved_sha: Optional[str] = None

        try:
            # Create local temp directory (non-blocking)
            temp_local_dir = await asyncio.to_thread(
                tempfile.mkdtemp,
                prefix="ov_git_",
                dir=get_parser_download_temp_dir(),
            )
            logger.info(f"[GitAccessor] Created local temp dir for git: {temp_local_dir}")

            # Fetch content (Clone or Extract)
            repo_name = "repository"
            local_dir = Path(temp_local_dir)

            if source_str.startswith("git@"):
                # git@ SSH URL
                repo_name = await self._git_clone(
                    source_str,
                    temp_local_dir,
                    branch=branch,
                    commit=commit,
                    env=git_env,
                )
                used_git_clone = True
            elif source_str.startswith(("http://", "https://", "git://", "ssh://")):
                repo_url, branch, commit = self._parse_repo_source(source_str, **kwargs)
                github_token = None
                if auth_config is not None:
                    git_env = build_git_http_auth_env(auth_config, repo_url)
                elif self._is_github_url(repo_url):
                    github_token = kwargs.get("github_token") or os.environ.get("GITHUB_TOKEN")
                    if github_token and is_git_https_url(repo_url):
                        github_auth = parse_git_http_auth_config(
                            {"token": github_token},
                            repo_url,
                        )
                        assert github_auth is not None
                        git_env = build_git_http_auth_env(github_auth, repo_url)
                if commit:
                    resolved_sha = commit
                else:
                    # Watch refresh / add_resource first round pass the revision
                    # they already resolved (scheduler probe or preflight) here.
                    # Without a hint the ref is fetched by its moving branch name
                    # and no exact-revision checkpoint is recorded; this accessor
                    # never issues its own ls-remote.
                    resolved_sha = kwargs.get("git_head_sha_hint") or None
                # Fetch an immutable per-SHA archive when resolved; fall back to
                # the moving branch/commit name only when no revision was supplied.
                download_ref = resolved_sha or commit or branch
                if self._is_github_url(repo_url) and auth_config is None:
                    # Try GitHub ZIP API first, fall back to git clone
                    try:
                        local_dir, repo_name = await self._github_zip_download(
                            repo_url,
                            download_ref,
                            temp_local_dir,
                            github_token=github_token,
                        )
                    except Exception as zip_exc:
                        logger.warning(
                            f"[GitAccessor] GitHub ZIP download failed, falling back to git clone: {zip_exc}"
                        )

                        # Clean up any partial content before cloning
                        def _cleanup():
                            for p in Path(temp_local_dir).iterdir():
                                if p.is_file():
                                    p.unlink(missing_ok=True)
                                elif p.is_dir():
                                    shutil.rmtree(p, ignore_errors=True)

                        await asyncio.to_thread(_cleanup)
                        repo_name = await self._git_clone(
                            repo_url,
                            temp_local_dir,
                            branch=branch,
                            commit=commit,
                            env=git_env,
                        )
                        used_git_clone = True
                elif self._can_use_gitlab_zip(repo_url) and auth_config is None:
                    # Try GitLab ZIP API first, fall back to git clone
                    try:
                        local_dir, repo_name = await self._gitlab_zip_download(
                            repo_url, download_ref, temp_local_dir
                        )
                    except Exception as zip_exc:
                        logger.warning(
                            f"[GitAccessor] GitLab ZIP download failed, falling back to git clone: {zip_exc}"
                        )

                        # Clean up any partial content before cloning
                        def _cleanup():
                            for p in Path(temp_local_dir).iterdir():
                                if p.is_file():
                                    p.unlink(missing_ok=True)
                                elif p.is_dir():
                                    shutil.rmtree(p, ignore_errors=True)

                        await asyncio.to_thread(_cleanup)
                        repo_name = await self._git_clone(
                            repo_url,
                            temp_local_dir,
                            branch=branch,
                            commit=commit,
                            env=git_env,
                        )
                        used_git_clone = True
                else:
                    # Other configured code-hosting URLs: use git clone
                    repo_name = await self._git_clone(
                        repo_url,
                        temp_local_dir,
                        branch=branch,
                        commit=commit,
                        env=git_env,
                    )
                    used_git_clone = True
            else:
                raise ValueError(f"Unsupported source for GitAccessor: {source}")

            if commit:
                # A commit-only import is already pinned to an immutable revision.
                # Keep the supplied value as the checkpoint without another probe.
                resolved_sha = commit
            elif used_git_clone:
                # The clone fallback preserves the historical branch/commit
                # behavior. Record the revision that was actually checked out,
                # rather than the SHA probed before cloning.
                resolved_sha = await self._resolve_local_head(temp_local_dir, git_env)

            # Build metadata
            # repo_name is in "org/repo" format (e.g. "volcengine/OpenViking")
            # This is extracted via parse_code_hosting_url() from the original URL
            meta = {"repo_name": repo_name, "_cleanup_path": temp_local_dir}
            if branch:
                meta["repo_ref"] = branch
            if commit:
                meta["repo_commit"] = commit
            if resolved_sha:
                # Exact revision fetched; the watch layer persists this as its
                # source checkpoint.
                meta["resolved_head_sha"] = resolved_sha

            return LocalResource(
                path=local_dir,
                source_type=SourceType.GIT,
                original_source=source_str,  # Full original URL (critical for TreeBuilder!)
                meta=meta,
                is_temporary=True,
            )

        except BaseException as e:
            if not isinstance(e, asyncio.CancelledError):
                logger.error(
                    f"[GitAccessor] Failed to access git repository {source}: {e}",
                    exc_info=True,
                )
            # Clean up on error
            if temp_local_dir and os.path.exists(temp_local_dir):
                try:
                    shutil.rmtree(temp_local_dir, ignore_errors=True)
                except Exception:
                    pass
            raise

    def _parse_repo_source(self, source: str, **kwargs) -> Tuple[str, Optional[str], Optional[str]]:
        """Parse repository source URL to extract branch/commit info."""
        branch = kwargs.get("branch") or kwargs.get("ref")
        commit = kwargs.get("commit")
        parsed_source = parse_git_repo_url(source)
        if parsed_source is None:
            if source.startswith(("git@", "http://", "https://", "git://", "ssh://")):
                raise ValueError(f"Unsupported Git repository URL: {source}")
            if commit:
                branch = None
            return source, branch, commit

        commit = commit or parsed_source.commit
        branch = None if commit else branch or parsed_source.branch
        return parsed_source.clone_url, branch, commit

    @staticmethod
    def _resolve_probe_target(
        source: str, **kwargs
    ) -> Optional[Tuple[str, Optional[str], Optional[str]]]:
        """Resolve (clone_url, branch, commit) for a watch probe.

        Mirrors ``_parse_repo_source`` but returns None for non-git sources
        instead of raising, so callers can fall back to a full refresh.
        """
        branch = kwargs.get("branch") or kwargs.get("ref")
        commit = kwargs.get("commit")
        parsed_source = parse_git_repo_url(source)
        if parsed_source is None:
            if source.startswith(("git@", "http://", "https://", "git://", "ssh://")):
                if commit:
                    branch = None
                return source, branch, commit
            return None
        commit = commit or parsed_source.commit
        branch = None if commit else branch or parsed_source.branch
        return parsed_source.clone_url, branch, commit

    @staticmethod
    def _parse_ls_remote_ref(stdout: str, ref: str) -> Optional[str]:
        """Extract the SHA advertised for *ref* from ``git ls-remote`` output."""
        for line in stdout.splitlines():
            parts = line.split("\t", 1)
            if len(parts) == 2 and parts[1].strip() == ref:
                return parts[0].strip() or None
        return None

    async def probe_git_remote_head(
        self, source: Union[str, Path], **kwargs
    ) -> Optional[Tuple[str, str]]:
        """Resolve the watched git revision without downloading repository content.

        Branch watches return the remotely advertised ``(ref, head_sha)``.
        Commit-only watches return an empty ref and the supplied commit locally.
        Raises on branch probe failures so callers can apply a fail-open policy.
        """
        source_str = str(source)
        resolved = self._resolve_probe_target(source_str, **kwargs)
        if resolved is None:
            return None
        repo_url, branch, commit = resolved
        if commit:
            # The supplied commit is already an immutable revision. Return it
            # directly so callers can compare checkpoints without ls-remote.
            return "", commit

        auth_config = parse_git_http_auth_config(kwargs.get("auth_config"), source_str)
        env = build_git_http_auth_env(auth_config, repo_url) if auth_config is not None else None
        env = overlay_parser_subprocess_env(
            ParserNetworkContext(ParserNetworkOperation.GIT_COMMAND, repo_url),
            env,
        )
        return await self._git_ls_remote_head(repo_url, branch, env)

    def _normalize_repo_url(self, url: str) -> str:
        """Normalize a validated repository URL to a cloneable base form."""
        parsed_source = parse_git_repo_url(url)
        if parsed_source is not None:
            return parsed_source.clone_url
        if not url.startswith(("git@", "http://", "https://", "git://", "ssh://")):
            return url
        raise ValueError(f"Unsupported Git repository URL: {url}")

    def _get_repo_name(self, url: str) -> str:
        """Get repository name with organization for GitHub/GitLab URLs.

        Returns repo name in "org/repo" format (e.g. "volcengine/OpenViking")
        when possible. This is important for the final root_uri in VikingFS.

        Example:
          - Input: "https://github.com/volcengine/OpenViking"
          - Returns: "volcengine/OpenViking"
        """
        # First try to parse as code hosting URL
        parsed_org_repo = parse_code_hosting_url(url)
        if parsed_org_repo:
            return parsed_org_repo

        # Fallback for other URLs
        name_source = url
        if url.startswith(("http://", "https://", "git://", "ssh://")):
            name_source = urlparse(url).path.rstrip("/")
        elif ":" in url and not url.startswith("file://"):
            name_source = url.split(":", 1)[1]

        # Original logic for non-GitHub/GitLab URLs
        name = name_source.rstrip("/").split("/")[-1]
        if name.endswith(".git"):
            name = name[:-4]
        name = "".join(c if c.isalnum() or c in "-_" else "_" for c in name)
        return name or "repository"

    async def _run_git(
        self,
        args: list[str],
        cwd: Optional[str] = None,
        env: Optional[dict[str, str]] = None,
    ) -> str:
        """Run a git command."""
        process_kwargs = {
            "cwd": cwd,
            "stdout": asyncio.subprocess.PIPE,
            "stderr": asyncio.subprocess.PIPE,
        }
        if env is not None:
            process_kwargs["env"] = env
        if os.name == "posix":
            # Detach git into a fresh session/process group so that remote
            # helpers (http/ssh) and other descendants can be signalled
            # together on timeout/cancellation instead of being orphaned
            # while they still hold our stdout/stderr pipes.
            process_kwargs["start_new_session"] = True
        proc = await asyncio.create_subprocess_exec(*args, **process_kwargs)
        try:
            stdout, stderr = await proc.communicate()
        except BaseException:
            await self._terminate_git_process(proc)
            raise
        if proc.returncode != 0:
            raise_git_auth_error(stderr)
            error_msg = stderr.decode().strip()
            user_msg = "Git command failed."
            if "Could not resolve hostname" in error_msg:
                user_msg = (
                    "Git command failed: could not resolve hostname. Check the URL or your network."
                )
            if env is None:
                logger.warning(f"[GitAccessor] {user_msg} Details: {error_msg}")
            else:
                # An authenticated remote controls parts of stderr and may echo
                # the request's Authorization header. Keep credentialed failures
                # out of logs as well as argv and raised exceptions.
                logger.warning(f"[GitAccessor] {user_msg}")
            raise RuntimeError(user_msg)
        return stdout.decode().strip()

    async def _terminate_git_process(self, proc: asyncio.subprocess.Process) -> None:
        """Best-effort termination of the whole git process tree.

        Git spawns remote helpers (http/ssh) which inherit the stdout/stderr
        pipes. Killing only the direct git child leaves those descendants
        alive and holding the pipes open, so ``communicate()``/``wait()`` may
        block long after cancellation. On POSIX git runs in its own process
        group (see ``start_new_session``), so signal the entire group.
        """
        if os.name == "posix":
            try:
                os.killpg(proc.pid, signal.SIGKILL)
            except ProcessLookupError:
                pass
        else:
            # Non-POSIX platforms have no process-group signal primitive;
            # fall back to the direct child.
            with contextlib.suppress(ProcessLookupError):
                proc.kill()

        # Reaping itself must be bounded: shield protects the reap from a
        # second cancellation, while wait_for guarantees cleanup cannot pin
        # the caller's execution slot indefinitely. CancelledError derives
        # from BaseException and is deliberately not suppressed.
        with contextlib.suppress(Exception):
            await asyncio.wait_for(
                asyncio.shield(proc.wait()),
                timeout=self.CANCEL_REAP_TIMEOUT,
            )

    async def _has_commit(
        self,
        repo_dir: str,
        commit: str,
        env: Optional[dict[str, str]] = None,
    ) -> bool:
        """Check if a commit exists in the repository."""
        try:
            await self._run_git(
                ["git", "-C", repo_dir, "rev-parse", "--verify", commit],
                env=env,
            )
            return True
        except RuntimeError:
            return False

    @staticmethod
    def _is_github_url(url: str) -> bool:
        """Return True for github.com URLs (supports ZIP archive API)."""
        return is_github_url(url)

    @staticmethod
    def _is_gitlab_url(url: str) -> bool:
        """Return True for gitlab.com URLs (supports ZIP archive API)."""
        return is_gitlab_url(url)

    def _can_use_gitlab_zip(self, url: str) -> bool:
        """Return True when the URL fits the two-segment GitLab ZIP helper."""
        if not self._is_gitlab_url(url):
            return False
        path_parts = [p for p in urlparse(url).path.split("/") if p]
        return len(path_parts) == 2

    async def _git_clone(
        self,
        url: str,
        target_dir: str,
        branch: Optional[str] = None,
        commit: Optional[str] = None,
        env: Optional[dict[str, str]] = None,
    ) -> str:
        """Clone a git repository into target_dir; return the repo name."""
        name = self._get_repo_name(url)
        logger.info(f"[GitAccessor] Cloning {url} to {target_dir}...")
        if commit:
            branch = None
        network_env = overlay_parser_subprocess_env(
            ParserNetworkContext(ParserNetworkOperation.GIT_COMMAND, url),
            env,
        )

        clone_args = [
            "git",
            "clone",
            "--depth",
            "1",
            "--no-recurse-submodules",
        ]
        if branch and not commit:
            clone_args.extend(["--branch", branch])
        clone_args.extend([url, target_dir])
        await self._run_git(clone_args, env=network_env)

        if commit:
            try:
                await self._run_git(
                    ["git", "-C", target_dir, "fetch", "origin", commit],
                    env=network_env,
                )
            except RuntimeError:
                try:
                    await self._run_git(
                        ["git", "-C", target_dir, "fetch", "--all", "--tags", "--prune"],
                        env=network_env,
                    )
                except RuntimeError:
                    pass
                ok = await self._has_commit(target_dir, commit, env=env)
                if not ok:
                    try:
                        await self._run_git(
                            ["git", "-C", target_dir, "fetch", "--unshallow", "origin"],
                            env=network_env,
                        )
                    except RuntimeError:
                        pass
                ok = await self._has_commit(target_dir, commit, env=env)
                if not ok:
                    await self._run_git(
                        [
                            "git",
                            "-C",
                            target_dir,
                            "fetch",
                            "origin",
                            "+refs/heads/*:refs/remotes/origin/*",
                        ],
                        env=network_env,
                    )
                    ok = await self._has_commit(target_dir, commit, env=env)
                    if not ok:
                        raise RuntimeError(f"Failed to fetch commit {commit} from {url}")
            await self._run_git(
                ["git", "-C", target_dir, "checkout", commit],
                env=env,
            )

        # Add .git_source_repo marker file with original URL (for consistency)
        def _write_marker():
            marker_file = Path(target_dir) / ".git_source_repo"
            marker_file.write_text(url, encoding="utf-8")

        await asyncio.to_thread(_write_marker)

        return name

    async def _resolve_local_head(
        self,
        repo_dir: str,
        env: Optional[dict[str, str]] = None,
    ) -> Optional[str]:
        """Return the revision actually checked out by git clone."""
        try:
            head_sha = await self._run_git(
                ["git", "-C", repo_dir, "rev-parse", "HEAD"],
                env=env,
            )
        except Exception as exc:
            logger.warning(
                f"[GitAccessor] failed to resolve cloned repository HEAD: {exc}; "
                "continuing without an exact-revision checkpoint"
            )
            return None
        return head_sha.strip() or None

    async def _git_ls_remote_head(
        self,
        url: str,
        branch: Optional[str],
        env: Optional[dict[str, str]] = None,
    ) -> Tuple[str, str]:
        """Probe a remote for the tip SHA of *branch* (or HEAD if branch is None).

        Returns ``(ref, sha)`` where ref is the fully qualified ref advertised by
        the remote. Uses ``ls-remote`` only (no content download) so the cost is
        a single network round-trip.
        """
        if branch:
            ref = branch if branch.startswith("refs/") else f"refs/heads/{branch}"
            args = ["git", "ls-remote", "--heads", url, ref]
        else:
            # Track the remote's default branch via HEAD, which every server
            # advertises; no --symref dependency.
            ref = "HEAD"
            args = ["git", "ls-remote", url, "HEAD"]
        stdout = await self._run_git(args, env=env)
        sha = self._parse_ls_remote_ref(stdout, ref)
        if sha is None:
            raise RuntimeError(f"git ls-remote did not advertise {ref} for {url}")
        return ref, sha

    async def _github_zip_download(
        self,
        repo_url: str,
        branch: Optional[str],
        target_dir: str,
        *,
        github_token: Optional[str] = None,
    ) -> Tuple[Path, str]:
        """Download a GitHub repo as a ZIP archive and extract it."""
        repo_name = self._get_repo_name(repo_url)

        # Build archive URL from owner/repo path components.
        parsed = urlparse(repo_url)
        path_parts = [p for p in parsed.path.split("/") if p]
        owner = path_parts[0]
        repo_raw = path_parts[1]
        # Strip .git suffix for the archive URL
        repo_slug = repo_raw[:-4] if repo_raw.endswith(".git") else repo_raw

        ref = quote(branch or "HEAD", safe="/")
        zip_url = f"https://github.com/{owner}/{repo_slug}/archive/{ref}.zip"

        logger.info(f"[GitAccessor] Downloading GitHub ZIP: {zip_url}")

        zip_path = os.path.join(target_dir, "_archive.zip")
        extract_dir = os.path.join(target_dir, "_extracted")
        os.makedirs(extract_dir, exist_ok=True)

        github_token = github_token or os.environ.get("GITHUB_TOKEN")

        # Download (blocking HTTP; run in thread pool)
        def _download() -> None:
            headers = {"User-Agent": "OpenViking"}
            if github_token:
                headers["Authorization"] = f"token {github_token}"

            req = urllib.request.Request(zip_url, headers=headers)
            context = ParserNetworkContext(ParserNetworkOperation.GIT_ARCHIVE, zip_url)
            with open_parser_url(context, req, timeout=1800) as resp, open(zip_path, "wb") as f:
                shutil.copyfileobj(resp, f)

        try:
            await asyncio.to_thread(_download)
        except Exception as exc:
            raise RuntimeError(f"Failed to download GitHub ZIP {zip_url}: {exc}")

        # Safe extraction with Zip Slip validation (non-blocking)
        def _extract_zip():
            target = Path(extract_dir).resolve()
            with zipfile.ZipFile(zip_path, "r") as zf:
                for info in zf.infolist():
                    mode = info.external_attr >> 16
                    if info.is_dir() or stat.S_ISDIR(mode):
                        continue
                    if stat.S_ISLNK(mode):
                        logger.warning(
                            f"[GitAccessor] Skipping symlink entry in GitHub ZIP: {info.filename}"
                        )
                        continue
                    raw = info.filename.replace("\\", "/")
                    raw_parts = [p for p in raw.split("/") if p]
                    if ".." in raw_parts:
                        raise ValueError(f"Zip Slip detected in GitHub archive: {info.filename!r}")
                    if PurePosixPath(raw).is_absolute():
                        raise ValueError(f"Zip Slip detected in GitHub archive: {info.filename!r}")
                    extracted = Path(zf.extract(info, extract_dir)).resolve()
                    if not extracted.is_relative_to(target):
                        extracted.unlink(missing_ok=True)
                        raise ValueError(f"Zip Slip detected in GitHub archive: {info.filename!r}")

        await asyncio.to_thread(_extract_zip)

        # Remove downloaded archive to free disk space (non-blocking)
        def _cleanup_archive():
            try:
                os.unlink(zip_path)
            except OSError:
                pass

        await asyncio.to_thread(_cleanup_archive)

        # GitHub ZIPs have a single top-level directory (non-blocking)
        def _find_content_dir() -> Path:
            top_level = [d for d in Path(extract_dir).iterdir() if d.is_dir()]
            return top_level[0] if len(top_level) == 1 else Path(extract_dir)

        content_dir = await asyncio.to_thread(_find_content_dir)

        # Add .git_source_repo marker file with original URL
        def _write_marker():
            marker_file = content_dir / ".git_source_repo"
            marker_file.write_text(repo_url, encoding="utf-8")

        await asyncio.to_thread(_write_marker)

        logger.info(f"[GitAccessor] GitHub ZIP extracted to {content_dir} ({repo_name})")
        return content_dir, repo_name

    async def _gitlab_zip_download(
        self,
        repo_url: str,
        branch: Optional[str],
        target_dir: str,
    ) -> Tuple[Path, str]:
        """Download a GitLab repo as a ZIP archive and extract it."""
        repo_name = self._get_repo_name(repo_url)

        # Build archive URL from owner/repo path components.
        # GitLab archive URL format: https://gitlab.com/{owner}/{repo}/-/archive/{ref}/{repo}-{ref}.zip
        parsed = urlparse(repo_url)
        path_parts = [p for p in parsed.path.split("/") if p]
        owner = path_parts[0]
        repo_raw = path_parts[1]
        # Strip .git suffix for the archive URL
        repo_slug = repo_raw[:-4] if repo_raw.endswith(".git") else repo_raw

        ref = branch or "HEAD"
        # GitLab uses the format: /{owner}/{repo}/-/archive/{ref}/{repo}-{ref}.zip
        zip_url = f"{parsed.scheme}://{parsed.netloc}/{owner}/{repo_slug}/-/archive/{ref}/{repo_slug}-{ref}.zip"

        logger.info(f"[GitAccessor] Downloading GitLab ZIP: {zip_url}")

        zip_path = os.path.join(target_dir, "_archive.zip")
        extract_dir = os.path.join(target_dir, "_extracted")
        os.makedirs(extract_dir, exist_ok=True)

        # Download (blocking HTTP; run in thread pool)
        def _download() -> None:
            headers = {"User-Agent": "OpenViking"}

            req = urllib.request.Request(zip_url, headers=headers)
            context = ParserNetworkContext(ParserNetworkOperation.GIT_ARCHIVE, zip_url)
            with open_parser_url(context, req, timeout=1800) as resp, open(zip_path, "wb") as f:
                shutil.copyfileobj(resp, f)

        try:
            await asyncio.to_thread(_download)
        except Exception as exc:
            raise RuntimeError(f"Failed to download GitLab ZIP {zip_url}: {exc}")

        # Safe extraction with Zip Slip validation (non-blocking)
        def _extract_zip():
            target = Path(extract_dir).resolve()
            with zipfile.ZipFile(zip_path, "r") as zf:
                for info in zf.infolist():
                    mode = info.external_attr >> 16
                    if info.is_dir() or stat.S_ISDIR(mode):
                        continue
                    if stat.S_ISLNK(mode):
                        logger.warning(
                            f"[GitAccessor] Skipping symlink entry in GitLab ZIP: {info.filename}"
                        )
                        continue
                    raw = info.filename.replace("\\", "/")
                    raw_parts = [p for p in raw.split("/") if p]
                    if ".." in raw_parts:
                        raise ValueError(f"Zip Slip detected in GitLab archive: {info.filename!r}")
                    if PurePosixPath(raw).is_absolute():
                        raise ValueError(f"Zip Slip detected in GitLab archive: {info.filename!r}")
                    extracted = Path(zf.extract(info, extract_dir)).resolve()
                    if not extracted.is_relative_to(target):
                        extracted.unlink(missing_ok=True)
                        raise ValueError(f"Zip Slip detected in GitLab archive: {info.filename!r}")

        await asyncio.to_thread(_extract_zip)

        # Remove downloaded archive to free disk space (non-blocking)
        def _cleanup_archive():
            try:
                os.unlink(zip_path)
            except OSError:
                pass

        await asyncio.to_thread(_cleanup_archive)

        # GitLab ZIPs have a single top-level directory: {repo}-{ref}/ (non-blocking)
        def _find_content_dir() -> Path:
            top_level = [d for d in Path(extract_dir).iterdir() if d.is_dir()]
            return top_level[0] if len(top_level) == 1 else Path(extract_dir)

        content_dir = await asyncio.to_thread(_find_content_dir)

        # Add .git_source_repo marker file with original URL
        def _write_marker():
            marker_file = content_dir / ".git_source_repo"
            marker_file.write_text(repo_url, encoding="utf-8")

        await asyncio.to_thread(_write_marker)

        logger.info(f"[GitAccessor] GitLab ZIP extracted to {content_dir} ({repo_name})")
        return content_dir, repo_name

    async def _extract_zip(self, zip_path: str, target_dir: str) -> str:
        """Extract a local zip file into target_dir."""
        if zip_path.startswith(("http://", "https://")):
            raise NotImplementedError("Zip URL download not yet implemented in GitAccessor")

        path = Path(zip_path)
        name = path.stem

        # Extract zip file (non-blocking)
        def _extract_zip_sync():
            with zipfile.ZipFile(zip_path, "r") as zip_ref:
                target = Path(target_dir).resolve()
                for info in zip_ref.infolist():
                    mode = info.external_attr >> 16
                    # Skip directory entries
                    if info.is_dir() or stat.S_ISDIR(mode):
                        continue
                    # Skip symlink entries
                    if stat.S_ISLNK(mode):
                        logger.warning(
                            f"[GitAccessor] Skipping symlink entry in zip: {info.filename}"
                        )
                        continue
                    # Reject entries with suspicious raw path components
                    raw = info.filename.replace("\\", "/")
                    raw_parts = [p for p in raw.split("/") if p]
                    if ".." in raw_parts:
                        raise ValueError(
                            f"Zip Slip detected: entry {info.filename!r} contains '..'"
                        )
                    if PurePosixPath(raw).is_absolute() or (len(raw) >= 2 and raw[1] == ":"):
                        raise ValueError(
                            f"Zip Slip detected: entry {info.filename!r} is an absolute path"
                        )
                    # Normalize and verify
                    arcname = info.filename.replace("/", os.sep)
                    if os.path.altsep:
                        arcname = arcname.replace(os.path.altsep, os.sep)
                    arcname = os.path.splitdrive(arcname)[1]
                    arcname = os.sep.join(
                        p for p in arcname.split(os.sep) if p not in ("", ".", "..")
                    )
                    if not arcname:
                        continue
                    member_path = (Path(target_dir) / arcname).resolve()
                    if not member_path.is_relative_to(target):
                        raise ValueError(
                            f"Zip Slip detected: entry {info.filename!r} escapes target directory"
                        )
                    # Extract and verify
                    extracted = Path(zip_ref.extract(info, target_dir)).resolve()
                    if not extracted.is_relative_to(target):
                        # Best-effort cleanup
                        try:
                            extracted.unlink(missing_ok=True)
                        except OSError as cleanup_err:
                            logger.warning(
                                f"[GitAccessor] Failed to clean up escaped file {extracted}: {cleanup_err}"
                            )
                        raise ValueError(
                            f"Zip Slip detected: entry {info.filename!r} escapes target directory"
                        )

        await asyncio.to_thread(_extract_zip_sync)

        return name