s-gitkit 0.1.0__tar.gz

s_gitkit-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+*.cover
+
+# Ruff
+.ruff_cache/
+
+# Lock files (optional, uncomment if you want to commit them)
+# uv.lock

s_gitkit-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,32 @@
+stages:
+  - test
+  - publish
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip
+    - .venv/
+
+before_script:
+  - python -m pip install --upgrade pip
+  - python -m pip install uv
+  - uv sync --extra dev
+
+test:
+  stage: test
+  image: python:3.11
+  script:
+    - uv run pytest -q --cov=gitkit --cov-report=term-missing
+    - uv run ruff check gitkit
+
+publish:
+  stage: publish
+  image: python:3.11
+  only:
+    - tags
+  script:
+    - uv build
+    - uv publish

s_gitkit-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# Агенты и разработка s-gitkit
+
+## Архитектура
+
+gitkit — это миниатюрный, самостоятельный кит (зависит только от httpx, stamina и stdlib).
+
+```
+gitkit
+  ├── types.py         — GitRepoRef, GitTreeEntry, GitProvider Protocol
+  ├── errors.py        — GitProviderError, UnsupportedGitHostError
+  ├── github_provider.py  — GitHubProvider (github.com + GHE)
+  ├── gitlab_provider.py  — GitLabProvider (gitlab.com + self-hosted)
+  ├── factory.py        — GitProviderFactory + parse/detect функции
+  └── __init__.py       — public API
+```
+
+## Разработка
+
+```bash
+# Установка зависимостей
+uv sync --extra dev
+
+# Тесты
+uv run pytest tests/ -q
+
+# Линтинг
+uv run ruff check gitkit
+uv run ruff format gitkit
+
+# Построение
+uv build
+
+# Публикация
+uv publish
+```
+
+## Дизайн
+
+- **Protocol-based** — `GitProvider` — это Protocol, не abstract base class. Новый провайдер просто реализует интерфейс.
+- **Retry-встроен** — Все API-запросы используют tenacity с exponential backoff (3 попытки).
+- **No coupling** — Не зависит от librarykit (хотя librarykit может использовать gitkit).
+- **Read-only** — Интерфейс только для чтения (list_tags, resolve_tag, fetch_file, fetch_tree, clone_url).
+
+## Изменение версии
+
+В `pyproject.toml` обновить версию (patching 0.1.x, не минорные скачки на ранней стадии).
+
+## Когда добавлять новых провайдеров
+
+Если нужна поддержка новой платформы (напр. Gitea, Forgejo):
+
+1. Создать `gitkit/gitea_provider.py` (реализует `GitProvider` Protocol)
+2. Добавить логику в `factory.detect_provider()`
+3. Добавить тесты в `tests/test_providers.py`
+4. Обновить `README.md` с примером
+
+Дизайн Protocol гарантирует, что новый провайдер автоматически работает везде, где использован `GitProvider`.

s_gitkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] — 2026-07-07
+
+### Added
+
+- Initial release
+- `GitProvider` Protocol — read-only интерфейс для git-хостингов
+- `GitHubProvider` — реализация для GitHub (github.com и GitHub Enterprise)
+- `GitLabProvider` — реализация для GitLab (gitlab.com и self-hosted)
+- `GitProviderFactory` — фабрика с автоматическим выбором провайдера
+- URL парсинг (https и scp-like форматы)
+- Retry-политика с exponential backoff
+- Полная асинхронная поддержка
+
+### Supported Platforms
+
+- Python 3.11+
+- GitHub (github.com, GitHub Enterprise)
+- GitLab (gitlab.com, self-hosted)

s_gitkit-0.1.0/DETAILS.txt

@@ -0,0 +1,43 @@
+# s-gitkit: git-хостинг абстракция (GitHub/GitLab read-layer)
+
+## Структура
+
+gitkit/ — основной пакет
+├── __init__.py — public API (GitProvider, GitRepoRef, GitTreeEntry, GitHubProvider, GitLabProvider, GitProviderFactory)
+├── types.py — Protocol GitProvider и data-классы GitRepoRef, GitTreeEntry
+├── errors.py — GitProviderError, UnsupportedGitHostError
+├── github_provider.py — GitHubProvider (github.com, GitHub Enterprise)
+├── gitlab_provider.py — GitLabProvider (gitlab.com, self-hosted)
+└── factory.py — GitProviderFactory + parse_repo_ref, detect_provider
+
+tests/ — 25 тестов
+├── test_factory.py — парсинг URL, выбор провайдера
+└── test_providers.py — GitHub и GitLab провайдеры (мокированные HTTP)
+
+Документация:
+- README.md — установка, quick start, примеры self-hosted
+- CHANGELOG.md — история версий
+- AGENTS.md — архитектура, разработка
+- LICENSE — MIT
+- pyproject.toml — конфиг проекта
+- .gitlab-ci.yml — CI/CD
+- .gitignore — исключения Git
+
+## Ключевые характеристики
+
+✓ Никаких зависимостей от skills_hub_backend — полностью самостоятельный
+✓ Легковесные зависимости: только httpx, stamina (и stdlib)
+✓ Protocol-based design — легко добавлять новых провайдеров (Gitea, Forgejo и т.д.)
+✓ Встроенная retry-политика (tenacity, 3 попытки, exponential backoff)
+✓ Поддержка всех форм git URL (https, scp-like)
+✓ Self-hosted GitLab + GitHub Enterprise готовы к работе
+✓ 100% асинхронный код (async/await)
+✓ Fully type-hinted (py311+)
+
+## Проверки выполнены
+
+✓ Import OK: python -c 'import gitkit; print(gitkit.__version__)'
+✓ 0 импортов skills_hub_backend
+✓ 0 утечек личной информации (_storage, C:, @gmail, Slug, навык)
+✓ 25 тестов прошли успешно
+✓ Структура соответствует эталону librarykit

s_gitkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_gitkit-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: s-gitkit
+Version: 0.1.0
+Summary: Git-хостинг абстракция: GitHub/GitLab read-layer (provider pattern для любых репозиториев + фабрика)
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: stamina>=24.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gitkit
+
+**Git-хостинг абстракция: GitHub/GitLab read-layer.**
+
+Единая интерфейс для работы с произвольными git-репозиториями на GitHub, GitLab и self-hosted GitLab инстансах. Provider pattern позволяет добавить новых провайдеров.
+
+## Возможности
+
+- **GitProvider Protocol** — read-only операции (list_tags, resolve_tag, fetch_file, fetch_tree, clone_url)
+- **GitHubProvider** — поддержка github.com и GitHub Enterprise
+- **GitLabProvider** — поддержка gitlab.com и self-hosted GitLab
+- **GitProviderFactory** — автоматический выбор провайдера по URL
+- **Парсинг URL** — поддержка https и scp-like git URL-ов
+- **Retry-политика** — автоматический retry с exponential backoff (3 попытки)
+
+## Установка
+
+```bash
+uv add s-gitkit
+```
+
+Имя пакета для импорта — `gitkit`.
+
+## Быстрый старт
+
+```python
+import gitkit
+
+# Автоматический выбор провайдера по URL
+factory = gitkit.GitProviderFactory()
+provider, repo = factory.create(
+    "https://github.com/owner/repo.git",
+    token="ghp_xxx"  # опционально
+)
+
+# Работа с репозиторием
+tags = await provider.list_tags(repo=repo)
+sha = await provider.resolve_tag(repo=repo, tag="v1.0.0")
+content = await provider.fetch_file(repo=repo, ref="main", path="README.md")
+tree = await provider.fetch_tree(repo=repo, ref="main")
+
+# Clone URL
+clone = provider.clone_url(repo=repo)
+```
+
+## Self-hosted GitLab
+
+Для поддержки self-hosted GitLab инстансов передайте хосты при создании фабрики:
+
+```python
+factory = gitkit.GitProviderFactory(
+    self_hosted_hosts=["git.example.com", "gitlab.company.org"]
+)
+provider, repo = factory.create(
+    "https://git.example.com/group/project.git",
+    token="glpat_xxx"
+)
+```
+
+## GitHub Enterprise
+
+Для GitHub Enterprise используйте `github_base_url`:
+
+```python
+factory = gitkit.GitProviderFactory(
+    github_base_url="https://github.enterprise.com/api/v3"
+)
+```
+
+## Разработка
+
+```bash
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check gitkit
+```
+
+## Лицензия
+
+MIT © 2026 Dmitry.

s_gitkit-0.1.0/README.md

@@ -0,0 +1,80 @@
+# gitkit
+
+**Git-хостинг абстракция: GitHub/GitLab read-layer.**
+
+Единая интерфейс для работы с произвольными git-репозиториями на GitHub, GitLab и self-hosted GitLab инстансах. Provider pattern позволяет добавить новых провайдеров.
+
+## Возможности
+
+- **GitProvider Protocol** — read-only операции (list_tags, resolve_tag, fetch_file, fetch_tree, clone_url)
+- **GitHubProvider** — поддержка github.com и GitHub Enterprise
+- **GitLabProvider** — поддержка gitlab.com и self-hosted GitLab
+- **GitProviderFactory** — автоматический выбор провайдера по URL
+- **Парсинг URL** — поддержка https и scp-like git URL-ов
+- **Retry-политика** — автоматический retry с exponential backoff (3 попытки)
+
+## Установка
+
+```bash
+uv add s-gitkit
+```
+
+Имя пакета для импорта — `gitkit`.
+
+## Быстрый старт
+
+```python
+import gitkit
+
+# Автоматический выбор провайдера по URL
+factory = gitkit.GitProviderFactory()
+provider, repo = factory.create(
+    "https://github.com/owner/repo.git",
+    token="ghp_xxx"  # опционально
+)
+
+# Работа с репозиторием
+tags = await provider.list_tags(repo=repo)
+sha = await provider.resolve_tag(repo=repo, tag="v1.0.0")
+content = await provider.fetch_file(repo=repo, ref="main", path="README.md")
+tree = await provider.fetch_tree(repo=repo, ref="main")
+
+# Clone URL
+clone = provider.clone_url(repo=repo)
+```
+
+## Self-hosted GitLab
+
+Для поддержки self-hosted GitLab инстансов передайте хосты при создании фабрики:
+
+```python
+factory = gitkit.GitProviderFactory(
+    self_hosted_hosts=["git.example.com", "gitlab.company.org"]
+)
+provider, repo = factory.create(
+    "https://git.example.com/group/project.git",
+    token="glpat_xxx"
+)
+```
+
+## GitHub Enterprise
+
+Для GitHub Enterprise используйте `github_base_url`:
+
+```python
+factory = gitkit.GitProviderFactory(
+    github_base_url="https://github.enterprise.com/api/v3"
+)
+```
+
+## Разработка
+
+```bash
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check gitkit
+```
+
+## Лицензия
+
+MIT © 2026 Dmitry.

s_gitkit-0.1.0/gitkit/__init__.py

@@ -0,0 +1,35 @@
+"""Git-хостинг абстракция: GitHub/GitLab read-layer.
+
+Единая абстракция над git-хостингами (GitHub, GitLab, self-hosted GitLab):
+- GitProvider Protocol (read-only: list_tags, resolve_tag, fetch_file, fetch_tree, clone_url)
+- GitRepoRef (распарсенная ссылка на репо: host/owner/name)
+- GitHubProvider, GitLabProvider (конкретные реализации)
+- GitProviderFactory (фабрика с поддержкой self-hosted)
+- Набор исключений (GitProviderError, UnsupportedGitHostError)
+"""
+from __future__ import annotations
+
+from gitkit.errors import GitProviderError, UnsupportedGitHostError
+from gitkit.factory import GitProviderFactory, detect_provider, parse_repo_ref
+from gitkit.github_provider import GitHubProvider
+from gitkit.gitlab_provider import GitLabProvider
+from gitkit.types import GitProvider, GitRepoRef, GitTreeEntry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Типы и интерфейсы
+    "GitRepoRef",
+    "GitTreeEntry",
+    "GitProvider",
+    # Исключения
+    "GitProviderError",
+    "UnsupportedGitHostError",
+    # Провайдеры
+    "GitHubProvider",
+    "GitLabProvider",
+    # Фабрика
+    "GitProviderFactory",
+    "parse_repo_ref",
+    "detect_provider",
+]

s_gitkit-0.1.0/gitkit/errors.py

@@ -0,0 +1,10 @@
+"""Исключения git-провайдеров."""
+from __future__ import annotations
+
+
+class GitProviderError(RuntimeError):
+    """Базовая ошибка провайдера (сетевые/API-сбои уровня абстракции)."""
+
+
+class UnsupportedGitHostError(GitProviderError):
+    """Host не поддерживается (не github.com / не известный GitLab-хост)."""

s_gitkit-0.1.0/gitkit/factory.py

@@ -0,0 +1,153 @@
+"""Парсинг repo URL + выбор провайдера по host.
+
+`parse_repo_ref` понимает обе формы git-URL:
+- https://host/owner/.../name(.git)
+- scp-like: git@host:owner/.../name(.git)
+
+`detect_provider` выбирает GitHubProvider (github.com) или GitLabProvider
+(gitlab.com + переданные self_hosted_hosts).
+"""
+from __future__ import annotations
+
+import re
+import urllib.parse
+
+import httpx
+
+from gitkit.errors import GitProviderError, UnsupportedGitHostError
+from gitkit.github_provider import GitHubProvider
+from gitkit.gitlab_provider import GitLabProvider
+from gitkit.types import GitProvider, GitRepoRef
+
+_GITHUB_HOST = "github.com"
+_GITLAB_HOST = "gitlab.com"
+
+# git@host:owner/.../name(.git)
+_SCP_RE = re.compile(r"^(?:[\w.+-]+@)?(?P<host>[\w.-]+):(?P<path>.+)$")
+
+
+def parse_repo_ref(repo_url: str) -> GitRepoRef:
+    """Распарсить http(s) или scp-like git URL в GitRepoRef.
+
+    `owner` сохраняет промежуточные подгруппы (для GitLab), `name` — последний
+    сегмент пути без суффикса `.git`.
+    """
+    raw = repo_url.strip()
+    if not raw:
+        raise GitProviderError("Пустой repo URL")
+
+    host: str
+    path: str
+
+    if raw.startswith(("http://", "https://", "git://", "ssh://")):
+        parsed = urllib.parse.urlparse(raw)
+        host = (parsed.hostname or "").lower()
+        path = parsed.path
+    else:
+        scp = _SCP_RE.match(raw)
+        if not scp:
+            raise GitProviderError(f"Не удалось распарсить repo URL: {repo_url!r}")
+        host = scp.group("host").lower()
+        path = scp.group("path")
+
+    if not host:
+        raise GitProviderError(f"В URL не найден host: {repo_url!r}")
+
+    segments = [s for s in path.strip("/").split("/") if s]
+    if len(segments) < 2:
+        raise GitProviderError(
+            f"URL должен содержать owner и name: {repo_url!r}"
+        )
+
+    name = segments[-1]
+    if name.endswith(".git"):
+        name = name[: -len(".git")]
+    owner = "/".join(segments[:-1])
+    if not name:
+        raise GitProviderError(f"Пустое имя репозитория: {repo_url!r}")
+
+    return GitRepoRef(raw_url=raw, host=host, owner=owner, name=name)
+
+
+_GITHUB_API_BASE = "https://api.github.com"
+
+
+def detect_provider(
+    repo_url: str,
+    *,
+    token: str | None = None,
+    http_client: httpx.AsyncClient | None = None,
+    self_hosted_hosts: list[str] | None = None,
+    github_base_url: str = _GITHUB_API_BASE,
+) -> tuple[GitProvider, GitRepoRef]:
+    """Выбрать провайдер по host распарсенного URL.
+
+    - github.com → GitHubProvider (с заданным ``github_base_url`` — для GHE)
+    - gitlab.com и любой host из self_hosted_hosts → GitLabProvider
+    - иначе → UnsupportedGitHostError
+    """
+    repo = parse_repo_ref(repo_url)
+    host = repo.host.lower()
+    gitlab_hosts = {_GITLAB_HOST, *(h.lower() for h in (self_hosted_hosts or []))}
+
+    provider: GitProvider
+    if host == _GITHUB_HOST:
+        provider = GitHubProvider(
+            host=host,
+            base_url=github_base_url,
+            token=token,
+            http_client=http_client,
+        )
+    elif host in gitlab_hosts:
+        provider = GitLabProvider(
+            host=host,
+            base_url=f"https://{host}",
+            token=token,
+            http_client=http_client,
+        )
+    else:
+        raise UnsupportedGitHostError(
+            f"Неподдерживаемый git-host: {host!r} "
+            "(ожидается github.com, gitlab.com или self-hosted GitLab из конфига)"
+        )
+
+    return provider, repo
+
+
+class GitProviderFactory:
+    """Конфиг-связанная фабрика провайдеров.
+
+    Держит настройки окружения (self-hosted GitLab-хосты, GitHub base_url) и
+    отдаёт ``detect_provider`` уже с ними. Токен передаётся per-call.
+    """
+
+    def __init__(
+        self,
+        *,
+        self_hosted_hosts: list[str] | None = None,
+        github_base_url: str = _GITHUB_API_BASE,
+    ) -> None:
+        self._self_hosted_hosts = list(self_hosted_hosts or [])
+        self._github_base_url = github_base_url
+
+    def parse(self, repo_url: str) -> GitRepoRef:
+        """Распарсить URL в ``GitRepoRef`` без конструирования провайдера.
+
+        Нужно, чтобы резолвер выбрал токен по host ДО создания провайдера.
+        """
+        return parse_repo_ref(repo_url)
+
+    def create(
+        self,
+        repo_url: str,
+        *,
+        token: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> tuple[GitProvider, GitRepoRef]:
+        return detect_provider(
+            repo_url,
+            token=token,
+            http_client=http_client,
+            self_hosted_hosts=self._self_hosted_hosts,
+            github_base_url=self._github_base_url,
+        )

s_gitkit-0.1.0/gitkit/github_provider.py

@@ -0,0 +1,144 @@
+"""GitHubProvider — read-слой над GitHub REST API (api.github.com).
+
+Реализует `GitProvider` для произвольного репозитория github.com.
+Auth опционален: с токеном — `Authorization: Bearer <token>`, без — аноним
+(подходит для публичных репо, но с rate-limit'ом).
+"""
+from __future__ import annotations
+
+import base64
+import urllib.parse
+
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from gitkit.errors import GitProviderError
+from gitkit.types import GitRepoRef, GitTreeEntry
+
+_API_VERSION = "2022-11-28"
+
+
+def _retry() -> AsyncRetrying:
+    return AsyncRetrying(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=8),
+        retry=retry_if_exception_type(httpx.TransportError),
+        reraise=True,
+    )
+
+
+def _headers(token: str | None) -> dict[str, str]:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": _API_VERSION,
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+class GitHubProvider:
+    """Read-only провайдер для github.com."""
+
+    def __init__(
+        self,
+        *,
+        host: str = "github.com",
+        base_url: str = "https://api.github.com",
+        token: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.host = host
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=30.0, headers=_headers(token)
+        )
+
+    async def close(self) -> None:
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+
+    def _repo_base(self, repo: GitRepoRef) -> str:
+        return f"{self._base_url}/repos/{repo.owner}/{repo.name}"
+
+    async def _get(
+        self, url: str, *, headers: dict[str, str] | None = None
+    ) -> httpx.Response:
+        resp: httpx.Response | None = None
+        async for attempt in _retry():
+            with attempt:
+                resp = await self._client.get(url, headers=headers)
+        assert resp is not None  # _retry reraises; resp set on success
+        return resp
+
+    async def list_tags(self, *, repo: GitRepoRef) -> list[str]:
+        url = f"{self._repo_base(repo)}/tags?per_page=100"
+        resp = await self._get(url)
+        resp.raise_for_status()
+        return [t["name"] for t in resp.json()]
+
+    async def resolve_tag(self, *, repo: GitRepoRef, tag: str) -> str:
+        encoded_tag = urllib.parse.quote(tag, safe="")
+        url = f"{self._repo_base(repo)}/git/ref/tags/{encoded_tag}"
+        resp = await self._get(url)
+        if resp.status_code == 404:
+            # Аннотированный тег или прямой коммит/ветка — fallback на /commits.
+            commits_url = f"{self._repo_base(repo)}/commits/{encoded_tag}"
+            resp = await self._get(commits_url)
+            resp.raise_for_status()
+            return resp.json()["sha"]
+        resp.raise_for_status()
+        data = resp.json()
+        obj = data["object"]
+        if obj.get("type") == "tag":
+            # Аннотированный тег → разыменовать tag-object до коммита.
+            tag_resp = await self._get(obj["url"])
+            tag_resp.raise_for_status()
+            return tag_resp.json()["object"]["sha"]
+        return obj["sha"]
+
+    async def fetch_file(self, *, repo: GitRepoRef, ref: str, path: str) -> bytes:
+        encoded_path = urllib.parse.quote(path.lstrip("/"), safe="/")
+        encoded_ref = urllib.parse.quote(ref, safe="")
+        url = f"{self._repo_base(repo)}/contents/{encoded_path}?ref={encoded_ref}"
+        # Accept: raw → тело ответа = сырое содержимое файла.
+        resp = await self._get(url, headers={"Accept": "application/vnd.github.raw"})
+        resp.raise_for_status()
+        ctype = resp.headers.get("content-type", "")
+        if "application/json" in ctype:
+            # Сервер вернул JSON-метаданные (raw не применился) → decode base64.
+            data = resp.json()
+            if data.get("encoding") == "base64":
+                return base64.b64decode(data["content"])
+            raise GitProviderError(
+                f"Неожиданный формат contents-ответа для {path!r}"
+            )
+        return resp.content
+
+    async def fetch_tree(self, *, repo: GitRepoRef, ref: str) -> list[GitTreeEntry]:
+        encoded_ref = urllib.parse.quote(ref, safe="")
+        url = f"{self._repo_base(repo)}/git/trees/{encoded_ref}?recursive=1"
+        resp = await self._get(url)
+        resp.raise_for_status()
+        data = resp.json()
+        entries: list[GitTreeEntry] = []
+        for node in data.get("tree", []):
+            node_type = "tree" if node.get("type") == "tree" else "blob"
+            entries.append(
+                GitTreeEntry(
+                    path=node["path"],
+                    type=node_type,
+                    size=node.get("size"),
+                )
+            )
+        return entries
+
+    def clone_url(self, *, repo: GitRepoRef) -> str:
+        return f"https://{self.host}/{repo.owner}/{repo.name}.git"

s_gitkit-0.1.0/gitkit/gitlab_provider.py

@@ -0,0 +1,122 @@
+"""GitLabProvider — read-слой над GitLab REST API v4.
+
+Реализует `GitProvider` для произвольного репозитория на gitlab.com или на
+self-hosted GitLab. Project id = url-encoded `"{owner}/{name}"` (owner может
+содержать подгруппы). Auth — header `PRIVATE-TOKEN` (как для gitlab.com).
+"""
+from __future__ import annotations
+
+import urllib.parse
+
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from gitkit.types import GitRepoRef, GitTreeEntry
+
+_TREE_MAX_PAGES = 100  # защита от бесконечного цикла пагинации
+
+
+def _retry() -> AsyncRetrying:
+    return AsyncRetrying(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=8),
+        retry=retry_if_exception_type(httpx.TransportError),
+        reraise=True,
+    )
+
+
+class GitLabProvider:
+    """Read-only провайдер для gitlab.com / self-hosted GitLab."""
+
+    def __init__(
+        self,
+        *,
+        host: str = "gitlab.com",
+        base_url: str = "https://gitlab.com",
+        token: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.host = host
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._owns_client = http_client is None
+        headers = {"PRIVATE-TOKEN": token} if token else {}
+        self._client = http_client or httpx.AsyncClient(
+            timeout=30.0, headers=headers
+        )
+
+    async def close(self) -> None:
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+
+    def _project_id(self, repo: GitRepoRef) -> str:
+        return urllib.parse.quote(f"{repo.owner}/{repo.name}", safe="")
+
+    def _project_base(self, repo: GitRepoRef) -> str:
+        return f"{self._base_url}/api/v4/projects/{self._project_id(repo)}"
+
+    async def _get(self, url: str) -> httpx.Response:
+        resp: httpx.Response | None = None
+        async for attempt in _retry():
+            with attempt:
+                resp = await self._client.get(url)
+        assert resp is not None  # _retry reraises; resp set on success
+        return resp
+
+    async def list_tags(self, *, repo: GitRepoRef) -> list[str]:
+        url = f"{self._project_base(repo)}/repository/tags?per_page=100"
+        resp = await self._get(url)
+        resp.raise_for_status()
+        return [t["name"] for t in resp.json()]
+
+    async def resolve_tag(self, *, repo: GitRepoRef, tag: str) -> str:
+        encoded_tag = urllib.parse.quote(tag, safe="")
+        url = f"{self._project_base(repo)}/repository/commits/{encoded_tag}"
+        resp = await self._get(url)
+        resp.raise_for_status()
+        return resp.json()["id"]
+
+    async def fetch_file(self, *, repo: GitRepoRef, ref: str, path: str) -> bytes:
+        encoded_path = urllib.parse.quote(path.lstrip("/"), safe="")
+        encoded_ref = urllib.parse.quote(ref, safe="")
+        url = (
+            f"{self._project_base(repo)}/repository/files/"
+            f"{encoded_path}/raw?ref={encoded_ref}"
+        )
+        resp = await self._get(url)
+        resp.raise_for_status()
+        return resp.content
+
+    async def fetch_tree(self, *, repo: GitRepoRef, ref: str) -> list[GitTreeEntry]:
+        entries: list[GitTreeEntry] = []
+        page = 1
+        while page <= _TREE_MAX_PAGES:
+            encoded_ref = urllib.parse.quote(ref, safe="")
+            url = (
+                f"{self._project_base(repo)}/repository/tree"
+                f"?recursive=true&per_page=100&ref={encoded_ref}&page={page}"
+            )
+            resp = await self._get(url)
+            resp.raise_for_status()
+            for node in resp.json():
+                node_type = "tree" if node.get("type") == "tree" else "blob"
+                entries.append(
+                    GitTreeEntry(
+                        path=node["path"],
+                        type=node_type,
+                        size=None,  # GitLab tree API не отдаёт размер
+                    )
+                )
+            next_page = resp.headers.get("x-next-page", "")
+            if not next_page:
+                break
+            page = int(next_page)
+        return entries
+
+    def clone_url(self, *, repo: GitRepoRef) -> str:
+        return f"{self._base_url}/{repo.owner}/{repo.name}.git"

s_gitkit-0.1.0/gitkit/types.py

@@ -0,0 +1,53 @@
+"""Типы и Protocol для git-провайдеров."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class GitRepoRef:
+    """Ссылка на внешний git-репозиторий, распарсенная из URL.
+
+    `owner` для GitLab может содержать подгруппы (`group/subgroup`).
+    `raw_url` сохраняет исходный URL как был передан (для логов/трейсинга).
+    """
+
+    raw_url: str
+    host: str
+    owner: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class GitTreeEntry:
+    """Запись дерева репозитория для указанного ref."""
+
+    path: str
+    type: str  # "blob" | "tree"
+    size: int | None
+
+
+class GitProvider(Protocol):
+    """Read-only абстракция над git-хостингом (GitHub / GitLab).
+
+    Интерфейс провайдера для работы с произвольным внешним репозиторием.
+    Поддерживает list_tags, resolve_tag, fetch_file, fetch_tree и clone_url.
+    """
+
+    host: str
+
+    async def list_tags(self, *, repo: GitRepoRef) -> list[str]:
+        """Возвращает имена тегов репозитория (newest first, как отдаёт API)."""
+
+    async def resolve_tag(self, *, repo: GitRepoRef, tag: str) -> str:
+        """Возвращает commit SHA, на который указывает тег."""
+
+    async def fetch_file(self, *, repo: GitRepoRef, ref: str, path: str) -> bytes:
+        """Возвращает сырое содержимое файла по ref."""
+
+    async def fetch_tree(self, *, repo: GitRepoRef, ref: str) -> list[GitTreeEntry]:
+        """Возвращает рекурсивное дерево файлов/каталогов для ref."""
+
+    def clone_url(self, *, repo: GitRepoRef) -> str:
+        """Детерминированный https clone URL (с суффиксом .git)."""

s_gitkit-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "s-gitkit"
+version = "0.1.0"
+description = "Git-хостинг абстракция: GitHub/GitLab read-layer (provider pattern для любых репозиториев + фабрика)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Dmitry" }]
+# Core dependencies: только httpx (для git API) + retry-слой (stamina).
+# Всё остальное — stdlib. Никаких зависимостей от librarykit (обратное направление возможно).
+dependencies = [
+    "httpx>=0.27",
+    "stamina>=24.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["gitkit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["."]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "SIM", "RUF"]
+ignore = ["RUF002", "RUF003", "RUF022"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]

s_gitkit-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for gitkit."""

s_gitkit-0.1.0/tests/test_factory.py

@@ -0,0 +1,149 @@
+"""Tests for URL parsing and provider factory."""
+import pytest
+
+from gitkit import (
+    GitProviderError,
+    GitProviderFactory,
+    GitHubProvider,
+    GitLabProvider,
+    UnsupportedGitHostError,
+    parse_repo_ref,
+)
+
+
+class TestParseRepoRef:
+    """Test URL parsing."""
+
+    def test_parse_https_github(self):
+        """Parse HTTPS GitHub URL."""
+        ref = parse_repo_ref("https://github.com/owner/repo.git")
+        assert ref.host == "github.com"
+        assert ref.owner == "owner"
+        assert ref.name == "repo"
+
+    def test_parse_https_gitlab_subgroup(self):
+        """Parse GitLab URL with subgroups."""
+        ref = parse_repo_ref("https://gitlab.com/group/subgroup/project.git")
+        assert ref.host == "gitlab.com"
+        assert ref.owner == "group/subgroup"
+        assert ref.name == "project"
+
+    def test_parse_scp_github(self):
+        """Parse SCP-style GitHub URL."""
+        ref = parse_repo_ref("git@github.com:owner/repo.git")
+        assert ref.host == "github.com"
+        assert ref.owner == "owner"
+        assert ref.name == "repo"
+
+    def test_parse_scp_gitlab(self):
+        """Parse SCP-style GitLab URL."""
+        ref = parse_repo_ref("git@gitlab.com:group/project.git")
+        assert ref.host == "gitlab.com"
+        assert ref.owner == "group"
+        assert ref.name == "project"
+
+    def test_parse_https_no_git_suffix(self):
+        """Parse HTTPS URL without .git suffix."""
+        ref = parse_repo_ref("https://github.com/owner/repo")
+        assert ref.host == "github.com"
+        assert ref.owner == "owner"
+        assert ref.name == "repo"
+
+    def test_parse_empty_url(self):
+        """Raise error on empty URL."""
+        with pytest.raises(GitProviderError, match="Пустой repo URL"):
+            parse_repo_ref("")
+
+    def test_parse_invalid_url(self):
+        """Raise error on invalid URL format."""
+        with pytest.raises(GitProviderError, match="Не удалось распарсить"):
+            parse_repo_ref("not-a-valid-url!@#$")
+
+    def test_parse_missing_owner(self):
+        """Raise error when URL has insufficient segments."""
+        with pytest.raises(GitProviderError, match="owner и name"):
+            parse_repo_ref("https://github.com/")
+
+    def test_parse_case_insensitive_host(self):
+        """Host should be lowercase."""
+        ref = parse_repo_ref("https://GitHub.Com/owner/repo")
+        assert ref.host == "github.com"
+
+
+class TestDetectProvider:
+    """Test provider detection."""
+
+    def test_github_provider_for_github_com(self):
+        """Detect GitHub provider for github.com."""
+        from gitkit.factory import detect_provider
+
+        provider, ref = detect_provider("https://github.com/owner/repo")
+        assert isinstance(provider, GitHubProvider)
+        assert ref.host == "github.com"
+
+    def test_gitlab_provider_for_gitlab_com(self):
+        """Detect GitLab provider for gitlab.com."""
+        from gitkit.factory import detect_provider
+
+        provider, ref = detect_provider("https://gitlab.com/group/project")
+        assert isinstance(provider, GitLabProvider)
+        assert ref.host == "gitlab.com"
+
+    def test_unsupported_host(self):
+        """Raise error for unsupported host."""
+        from gitkit.factory import detect_provider
+
+        with pytest.raises(UnsupportedGitHostError, match="Неподдерживаемый"):
+            detect_provider("https://gitea.example.com/owner/repo")
+
+    def test_self_hosted_gitlab(self):
+        """Detect GitLab provider for self-hosted instance."""
+        from gitkit.factory import detect_provider
+
+        provider, ref = detect_provider(
+            "https://git.example.com/group/project",
+            self_hosted_hosts=["git.example.com"],
+        )
+        assert isinstance(provider, GitLabProvider)
+        assert ref.host == "git.example.com"
+
+
+class TestGitProviderFactory:
+    """Test factory class."""
+
+    def test_factory_parse(self):
+        """Factory can parse URLs."""
+        factory = GitProviderFactory()
+        ref = factory.parse("https://github.com/owner/repo")
+        assert ref.host == "github.com"
+        assert ref.owner == "owner"
+        assert ref.name == "repo"
+
+    def test_factory_create_github(self):
+        """Factory creates GitHub provider."""
+        factory = GitProviderFactory()
+        provider, ref = factory.create("https://github.com/owner/repo")
+        assert isinstance(provider, GitHubProvider)
+        assert ref.host == "github.com"
+
+    def test_factory_create_gitlab(self):
+        """Factory creates GitLab provider."""
+        factory = GitProviderFactory()
+        provider, ref = factory.create("https://gitlab.com/group/project")
+        assert isinstance(provider, GitLabProvider)
+        assert ref.host == "gitlab.com"
+
+    def test_factory_with_self_hosted(self):
+        """Factory with self-hosted GitLab configuration."""
+        factory = GitProviderFactory(self_hosted_hosts=["git.example.com"])
+        provider, ref = factory.create("https://git.example.com/group/project")
+        assert isinstance(provider, GitLabProvider)
+        assert ref.host == "git.example.com"
+
+    def test_factory_with_custom_github_url(self):
+        """Factory with custom GitHub base URL."""
+        factory = GitProviderFactory(
+            github_base_url="https://github.enterprise.com/api/v3"
+        )
+        provider, ref = factory.create("https://github.com/owner/repo")
+        assert isinstance(provider, GitHubProvider)

s_gitkit-0.1.0/tests/test_providers.py

@@ -0,0 +1,179 @@
+"""Tests for GitHub and GitLab providers."""
+import pytest
+import respx
+import httpx
+
+from gitkit import GitHubProvider, GitLabProvider, GitRepoRef
+
+
+class TestGitHubProvider:
+    """Tests for GitHubProvider."""
+
+    @pytest.mark.asyncio
+    async def test_list_tags(self):
+        """Test listing tags from GitHub."""
+        provider = GitHubProvider()
+        repo = GitRepoRef(
+            raw_url="https://github.com/owner/repo",
+            host="github.com",
+            owner="owner",
+            name="repo",
+        )
+
+        with respx.mock:
+            respx.get(
+                "https://api.github.com/repos/owner/repo/tags?per_page=100"
+            ).mock(
+                return_value=httpx.Response(
+                    200,
+                    json=[
+                        {"name": "v1.0.0"},
+                        {"name": "v0.9.0"},
+                    ],
+                )
+            )
+
+            tags = await provider.list_tags(repo=repo)
+            assert tags == ["v1.0.0", "v0.9.0"]
+
+        await provider.close()
+
+    @pytest.mark.asyncio
+    async def test_resolve_tag(self):
+        """Test resolving tag to commit SHA."""
+        provider = GitHubProvider()
+        repo = GitRepoRef(
+            raw_url="https://github.com/owner/repo",
+            host="github.com",
+            owner="owner",
+            name="repo",
+        )
+
+        with respx.mock:
+            respx.get(
+                "https://api.github.com/repos/owner/repo/git/ref/tags/v1.0.0"
+            ).mock(
+                return_value=httpx.Response(
+                    200,
+                    json={
+                        "object": {
+                            "type": "commit",
+                            "sha": "abc123def456",
+                        }
+                    },
+                )
+            )
+
+            sha = await provider.resolve_tag(repo=repo, tag="v1.0.0")
+            assert sha == "abc123def456"
+
+        await provider.close()
+
+    @pytest.mark.asyncio
+    async def test_clone_url(self):
+        """Test clone URL generation."""
+        provider = GitHubProvider()
+        repo = GitRepoRef(
+            raw_url="https://github.com/owner/repo",
+            host="github.com",
+            owner="owner",
+            name="repo",
+        )
+
+        url = provider.clone_url(repo=repo)
+        assert url == "https://github.com/owner/repo.git"
+
+        await provider.close()
+
+
+class TestGitLabProvider:
+    """Tests for GitLabProvider."""
+
+    @pytest.mark.asyncio
+    async def test_list_tags(self):
+        """Test listing tags from GitLab."""
+        provider = GitLabProvider()
+        repo = GitRepoRef(
+            raw_url="https://gitlab.com/group/project",
+            host="gitlab.com",
+            owner="group",
+            name="project",
+        )
+
+        with respx.mock:
+            respx.get(
+                "https://gitlab.com/api/v4/projects/group%2Fproject/repository/tags?per_page=100"
+            ).mock(
+                return_value=httpx.Response(
+                    200,
+                    json=[
+                        {"name": "v1.0.0"},
+                        {"name": "v0.9.0"},
+                    ],
+                )
+            )
+
+            tags = await provider.list_tags(repo=repo)
+            assert tags == ["v1.0.0", "v0.9.0"]
+
+        await provider.close()
+
+    @pytest.mark.asyncio
+    async def test_resolve_tag(self):
+        """Test resolving tag to commit SHA."""
+        provider = GitLabProvider()
+        repo = GitRepoRef(
+            raw_url="https://gitlab.com/group/project",
+            host="gitlab.com",
+            owner="group",
+            name="project",
+        )
+
+        with respx.mock:
+            respx.get(
+                "https://gitlab.com/api/v4/projects/group%2Fproject/repository/commits/v1.0.0"
+            ).mock(
+                return_value=httpx.Response(
+                    200,
+                    json={"id": "abc123def456"},
+                )
+            )
+
+            sha = await provider.resolve_tag(repo=repo, tag="v1.0.0")
+            assert sha == "abc123def456"
+
+        await provider.close()
+
+    @pytest.mark.asyncio
+    async def test_clone_url(self):
+        """Test clone URL generation."""
+        provider = GitLabProvider()
+        repo = GitRepoRef(
+            raw_url="https://gitlab.com/group/project",
+            host="gitlab.com",
+            owner="group",
+            name="project",
+        )
+
+        url = provider.clone_url(repo=repo)
+        assert url == "https://gitlab.com/group/project.git"
+
+        await provider.close()
+
+    @pytest.mark.asyncio
+    async def test_self_hosted(self):
+        """Test self-hosted GitLab provider."""
+        provider = GitLabProvider(
+            host="git.example.com", base_url="https://git.example.com"
+        )
+        repo = GitRepoRef(
+            raw_url="https://git.example.com/group/project",
+            host="git.example.com",
+            owner="group",
+            name="project",
+        )
+
+        url = provider.clone_url(repo=repo)
+        assert url == "https://git.example.com/group/project.git"
+
+        await provider.close()