From dbb17bd77496847b774b02c2efab22beb4a5df71 Mon Sep 17 00:00:00 2001
From: Lacky1234union <rogachevegorushka@yandex.ru>
Date: Thu, 15 Oct 2026 19:10:30 +0300
Subject: [PATCH] =?UTF-8?q?feat(bot):=20=D0=9A=D0=BE=D0=BC=D0=BC=D0=B8?=
 =?UTF-8?q?=D1=82=20=E2=80=94=20=D0=BD=D0=B0=D0=B2=D0=B8=D0=B3=D0=B0=D1=86?=
 =?UTF-8?q?=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=B4=D0=B5=D1=80=D0=B5=D0=B2?=
 =?UTF-8?q?=D1=83=20=D1=80=D0=B5=D0=BF=D0=BE=D0=B7=D0=B8=D1=82=D0=BE=D1=80?=
 =?UTF-8?q?=D0=B8=D1=8F=20=D0=B7=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=BE=D0=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- UploadsRepo: локальный клон, fetch не чаще fetch_interval, ls-tree -z (пробелы/кириллица),
  cat-file, последний коммит по пути; git без shell, ssh с -F /dev/null (без конфига хоста)
- «📝 Коммит»: папки/файлы с размерами, ⬆️ Вверх, страницы по 20, карточка файла
  с последним коммитом, «👁 Показать» (<pre> или документом); в кнопках только индексы
- ключ для контейнера: GIT_SSH_KEY_B64 → временный файл 0600 (смонтированный файл хоста
  контейнерному uid не прочитать); volume /data для клона
- тесты на настоящем bare-репозитории во временной папке

Refs #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .env.example              |   4 +-
 Dockerfile                |   2 +
 app/bot/routers/commit.py | 207 ++++++++++++++++++++++++++++++++++++++
 app/bot/routers/common.py |   4 +-
 app/config.py             |  17 ++++
 app/main.py               |   8 +-
 app/repo/__init__.py      |   0
 app/repo/git.py           | 163 ++++++++++++++++++++++++++++++
 app/texts.py              |  24 +++++
 config/texts.yaml         |  26 +++++
 docker-compose.yml        |   4 +
 tests/bot/test_commit.py  | 103 +++++++++++++++++++
 tests/bot/test_common.py  |   7 +-
 tests/bot/test_members.py |   5 +-
 tests/conftest.py         |  45 ++++++++-
 tests/repo/__init__.py    |   0
 tests/repo/test_git.py    |  85 ++++++++++++++++
 17 files changed, 692 insertions(+), 12 deletions(-)
 create mode 100644 app/bot/routers/commit.py
 create mode 100644 app/repo/__init__.py
 create mode 100644 app/repo/git.py
 create mode 100644 tests/bot/test_commit.py
 create mode 100644 tests/repo/__init__.py
 create mode 100644 tests/repo/test_git.py

diff --git a/.env.example b/.env.example
index e4b4d1e..4d8eb43 100644
--- a/.env.example
+++ b/.env.example
@@ -19,7 +19,9 @@ SOURCECRAFT_UPLOADS_REPO=rogachevegorushka/tgit-uploads
 # --- Git: коммиты в репозиторий загрузок (#7, #9) ---
 GIT_SSH_KEY_PATH=              # путь к приватному deploy-ключу бота (монтируется read-only);
                                # публичная часть — deploy key с правом записи в tgit-uploads
-UPLOADS_GIT_URL=git@ssh.sourcecraft.dev:rogachevegorushka/tgit-uploads.git
+GIT_SSH_KEY_B64=                # (secret) для Docker: тот же ключ в base64 — base64 -w0 ~/.ssh/tgit_bot_ed25519
+GIT_UPLOADS_URL=git@ssh.sourcecraft.dev:rogachevegorushka/tgit-uploads.git
+# GIT_CLONE_DIR=data/uploads   # локальный клон репозитория загрузок (в Docker — volume /data/uploads)
 
 # --- LLM (#17) ---
 LLM_PROVIDER=mock              # mock | openai_compat
diff --git a/Dockerfile b/Dockerfile
index 012be5e..d8452e7 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -19,6 +19,8 @@ ENV PATH="/opt/venv/bin:$PATH" PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
 COPY --from=build /opt/venv /opt/venv
 WORKDIR /srv/tgit
 COPY config ./config
+# /data: the uploads repo clone (named volume inherits this ownership)
+RUN install -d -o tgit -g tgit /data
 USER tgit
 # Liveness: the bot touches a heartbeat file while its event loop runs (app/health.py)
 HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=3 CMD ["python", "-m", "app.health"]
diff --git a/app/bot/routers/commit.py b/app/bot/routers/commit.py
new file mode 100644
index 0000000..7864a17
--- /dev/null
+++ b/app/bot/routers/commit.py
@@ -0,0 +1,207 @@
+"""«📝 Коммит»: browsing the uploads repo tree with buttons (SPEC C-1…C-4). Changes and push — #26, #9."""
+
+import html
+import logging
+from enum import StrEnum
+from typing import Any
+
+from aiogram import F, Router
+from aiogram.enums import ParseMode
+from aiogram.filters.callback_data import CallbackData
+from aiogram.fsm.context import FSMContext
+from aiogram.types import BufferedInputFile, CallbackQuery, InlineKeyboardMarkup, Message
+from aiogram.utils.keyboard import InlineKeyboardBuilder
+
+from app.bot.menu import Nav, NavAction
+from app.repo.git import Entry, GitError, UploadsRepo
+from app.texts import Texts
+
+log = logging.getLogger(__name__)
+
+PAGE_SIZE = 20
+INLINE_VIEW_LIMIT = 3500  # chars; Telegram caps a message at 4096 and <pre> markup takes some
+
+
+class Act(StrEnum):
+    OPEN = "o"
+    UP = "u"
+    PAGE = "p"
+    VIEW = "v"
+    TO_DIR = "b"
+    REPLACE = "r"
+    DELETE = "d"
+    NEW_FILE = "f"
+    NEW_DIR = "n"
+
+
+class CommitCb(CallbackData, prefix="c"):
+    # Only an action and a small index: paths never go into callback_data (64-byte limit, ARCHITECTURE §2.1)
+    a: Act
+    i: int = 0
+
+
+def human_size(n: int) -> str:
+    size = float(n)
+    for unit in ("Б", "КБ", "МБ"):
+        if size < 1024 or unit == "МБ":
+            return f"{size:.0f} {unit}" if unit == "Б" else f"{size:.1f} {unit}"
+        size /= 1024
+    raise AssertionError("unreachable")
+
+
+def parent(path: str) -> str:
+    return path.rsplit("/", 1)[0] if "/" in path else ""
+
+
+def render_dir(texts: Texts, path: str, entries: list[Entry], page: int) -> tuple[str, InlineKeyboardMarkup]:
+    t = texts.commit
+    pages = max(1, -(-len(entries) // PAGE_SIZE))
+    page = min(max(page, 0), pages - 1)
+    lines = [t.title.format(path=path)]
+    if not entries:
+        lines.append(t.empty)
+    elif pages > 1:
+        lines.append(t.page.format(page=page + 1, pages=pages))
+
+    kb = InlineKeyboardBuilder()
+    start = page * PAGE_SIZE
+    for index, e in enumerate(entries[start : start + PAGE_SIZE], start=start):
+        label = (
+            t.dir_button.format(name=e.name)
+            if e.kind == "dir"
+            else t.file_button.format(name=e.name, size=human_size(e.size))
+        )
+        kb.button(text=label, callback_data=CommitCb(a=Act.OPEN, i=index))
+    sizes = [1] * min(PAGE_SIZE, max(0, len(entries) - start))
+
+    paging: list[tuple[str, CommitCb]] = []
+    if page > 0:
+        paging.append((t.prev, CommitCb(a=Act.PAGE, i=page - 1)))
+    if page < pages - 1:
+        paging.append((t.next, CommitCb(a=Act.PAGE, i=page + 1)))
+    for text, cb in paging:
+        kb.button(text=text, callback_data=cb)
+    if paging:
+        sizes.append(len(paging))
+
+    kb.button(text=t.new_file, callback_data=CommitCb(a=Act.NEW_FILE))
+    kb.button(text=t.new_dir, callback_data=CommitCb(a=Act.NEW_DIR))
+    sizes.append(2)
+    if path:
+        kb.button(text=t.up, callback_data=CommitCb(a=Act.UP))
+        sizes.append(1)
+    kb.button(text=texts.menu.back, callback_data=Nav(action=NavAction.BACK))
+    kb.button(text=texts.menu.cancel, callback_data=Nav(action=NavAction.CANCEL))
+    sizes.append(2)
+    kb.adjust(*sizes)
+    return "\n".join(lines), kb.as_markup()
+
+
+def file_keyboard(texts: Texts) -> InlineKeyboardMarkup:
+    t = texts.commit
+    kb = InlineKeyboardBuilder()
+    kb.button(text=t.view, callback_data=CommitCb(a=Act.VIEW))
+    kb.button(text=t.replace, callback_data=CommitCb(a=Act.REPLACE))
+    kb.button(text=t.delete, callback_data=CommitCb(a=Act.DELETE))
+    kb.button(text=t.to_dir, callback_data=CommitCb(a=Act.TO_DIR))
+    kb.adjust(1, 2, 1)
+    return kb.as_markup()
+
+
+def build_router(texts: Texts, repo: UploadsRepo) -> Router:
+    router = Router(name="commit")
+    t = texts.commit
+
+    async def show_dir(message: Message, state: FSMContext, path: str, page: int, *, edit: bool) -> None:
+        entries = await repo.list_dir(path)
+        await state.update_data(
+            commit_path=path,
+            commit_page=page,
+            commit_entries=[[e.path, e.kind, e.size] for e in entries],
+            commit_file=None,
+        )
+        text, kb = render_dir(texts, path, entries, page)
+        if edit:
+            await message.edit_text(text, reply_markup=kb)
+        else:
+            await message.answer(text, reply_markup=kb)
+
+    @router.message(F.text == texts.menu.commit)
+    async def open_commit(message: Message, state: FSMContext) -> None:
+        await state.clear()
+        try:
+            await repo.refresh()
+            await show_dir(message, state, "", 0, edit=False)
+        except GitError:
+            log.exception("uploads repo unavailable")
+            await message.answer(t.unavailable)
+
+    @router.callback_query(CommitCb.filter())
+    async def on_action(query: CallbackQuery, callback_data: CommitCb, state: FSMContext) -> None:
+        if not isinstance(query.message, Message):
+            await query.answer()
+            return
+        msg = query.message
+        data: dict[str, Any] = await state.get_data()
+        path: str = data.get("commit_path", "")
+        entries: list[list[Any]] = data.get("commit_entries", [])
+        try:
+            match callback_data.a:
+                case Act.OPEN:
+                    if not 0 <= callback_data.i < len(entries):
+                        await query.answer()  # stale button from an older screen
+                        return
+                    target, kind, size = entries[callback_data.i]
+                    if kind == "dir":
+                        await repo.refresh()
+                        await show_dir(msg, state, target, 0, edit=True)
+                    else:
+                        await state.update_data(commit_file=target)
+                        await msg.edit_text(await file_card(target, size), reply_markup=file_keyboard(texts))
+                case Act.UP:
+                    await show_dir(msg, state, parent(path), 0, edit=True)
+                case Act.PAGE:
+                    await state.update_data(commit_page=callback_data.i)
+                    real = [Entry(p, k, s) for p, k, s in entries]
+                    text, kb = render_dir(texts, path, real, callback_data.i)
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.TO_DIR:
+                    await show_dir(msg, state, path, data.get("commit_page", 0), edit=True)
+                case Act.VIEW:
+                    file_path = data.get("commit_file")
+                    if file_path:
+                        await send_file(msg, file_path)
+                case Act.REPLACE | Act.DELETE | Act.NEW_FILE | Act.NEW_DIR:
+                    await query.answer(t.soon, show_alert=True)
+                    return
+        except GitError:
+            log.exception("uploads repo unavailable")
+            await query.answer(t.unavailable, show_alert=True)
+            return
+        await query.answer()
+
+    async def file_card(path: str, size: int) -> str:
+        card = t.file_card.format(path=path, size=human_size(size))
+        info = await repo.last_commit(path)
+        tail = (
+            t.last_commit.format(
+                sha=info.sha[:7], author=info.author, date=info.date.strftime("%d.%m.%Y %H:%M"), subject=info.subject
+            )
+            if info
+            else t.no_commits
+        )
+        return f"{card}\n{tail}"
+
+    async def send_file(msg: Message, path: str) -> None:
+        content = await repo.read(path)
+        name = path.rsplit("/", 1)[-1]
+        try:
+            text = content.decode("utf-8")
+        except UnicodeDecodeError:
+            text = None
+        if text is not None and "\0" not in text and len(text) <= INLINE_VIEW_LIMIT:
+            await msg.answer(f"<b>/{html.escape(path)}</b>\n<pre>{html.escape(text)}</pre>", parse_mode=ParseMode.HTML)
+        else:
+            await msg.answer_document(BufferedInputFile(content, name), caption=t.sent_as_file)
+
+    return router
diff --git a/app/bot/routers/common.py b/app/bot/routers/common.py
index aa960d5..809fc1a 100644
--- a/app/bot/routers/common.py
+++ b/app/bot/routers/common.py
@@ -16,7 +16,6 @@ def build_router(texts: Texts, access: AccessService) -> Router:
     router = Router(name="common")
     sections = section_by_button(texts)
     section_text = {
-        Section.COMMIT: texts.section.commit,
         Section.STATUS: texts.section.status,
         Section.LOGS: texts.section.logs,
         Section.ALERTS: texts.section.alerts,
@@ -49,7 +48,8 @@ def build_router(texts: Texts, access: AccessService) -> Router:
     async def help_(message: Message) -> None:
         await message.answer(texts.help.text)
 
-    @router.message(F.text.in_({k for k, v in sections.items() if v is not Section.MEMBERS}))
+    # Sections with their own routers (members, commit) are matched there first
+    @router.message(F.text.in_({k for k, v in sections.items() if v in section_text}))
     async def open_section(message: Message, state: FSMContext) -> None:
         await state.clear()
         await message.answer(section_text[sections[message.text or ""]], reply_markup=section_nav(texts))
diff --git a/app/config.py b/app/config.py
index e0c6ecc..0f0fe45 100644
--- a/app/config.py
+++ b/app/config.py
@@ -64,6 +64,22 @@ class SourceCraftSettings(BaseSettings):
     max_attempts: int = Field(default=5, ge=1)
 
 
+class GitSettings(BaseSettings):
+    model_config = SettingsConfigDict(**_ENV, env_prefix="GIT_")
+
+    # The bot's own deploy key with write access to tgit-uploads only (#7)
+    uploads_url: str = "git@ssh.sourcecraft.dev:rogachevegorushka/tgit-uploads.git"
+    ssh_key_path: Path | None = None
+    # Alternative for containers: the private key itself, base64 — a mounted host file is unreadable for the
+    # container user (uid 10001 vs the owner's 0600). Written to a private temp file at startup.
+    ssh_key_b64: SecretStr | None = None
+    branch: str = "main"
+    clone_dir: Path = Path("data/uploads")
+    # Browsing re-fetches at most this often; a push always fetches first (#9)
+    fetch_interval: float = Field(default=10.0, ge=0)
+    timeout: float = Field(default=60.0, gt=0)
+
+
 class RuntimeSettings(BaseSettings):
     model_config = _ENV
 
@@ -84,4 +100,5 @@ class Settings(BaseSettings):
     database: DatabaseSettings = Field(default_factory=DatabaseSettings)
     llm: LLMSettings = Field(default_factory=LLMSettings)
     sourcecraft: SourceCraftSettings = Field(default_factory=SourceCraftSettings)
+    git: GitSettings = Field(default_factory=GitSettings)
     runtime: RuntimeSettings = Field(default_factory=RuntimeSettings)
diff --git a/app/main.py b/app/main.py
index 9b1ed17..1be8a8e 100644
--- a/app/main.py
+++ b/app/main.py
@@ -10,25 +10,27 @@ from app import __version__
 from app.access.service import AccessService
 from app.bot.fsm import make_storage
 from app.bot.middlewares.access import AccessMiddleware
-from app.bot.routers import common, members
+from app.bot.routers import commit, common, members
 from app.config import Settings
 from app.db.maintenance import cleanup_loop
 from app.db.migrate import upgrade
 from app.db.session import SessionMaker, make_engine, make_sessionmaker
 from app.health import heartbeat
 from app.logs_setup import setup_logging
+from app.repo.git import UploadsRepo
 from app.texts import Texts, load_texts
 
 log = logging.getLogger("tgit")
 
 
-def build_dispatcher(texts: Texts, sessions: SessionMaker, access: AccessService) -> Dispatcher:
+def build_dispatcher(texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo) -> Dispatcher:
     dp = Dispatcher(storage=make_storage(sessions))
     gate = AccessMiddleware(access, texts)
     # Outer middleware: runs before filters, so nothing — not even a stale button — reaches a handler unchecked.
     dp.message.outer_middleware(gate)
     dp.callback_query.outer_middleware(gate)
     dp.include_router(members.build_router(texts, access))
+    dp.include_router(commit.build_router(texts, repo))
     dp.include_router(common.build_router(texts, access))
     return dp
 
@@ -40,7 +42,7 @@ async def run(settings: Settings) -> None:
     sessions = make_sessionmaker(engine)
     access = AccessService(sessions, settings.access)
     await access.bootstrap_admins()
-    dp = build_dispatcher(texts, sessions, access)
+    dp = build_dispatcher(texts, sessions, access, UploadsRepo(settings.git))
     rt = settings.runtime
     background = [
         asyncio.create_task(heartbeat(rt.heartbeat_file, rt.heartbeat_interval)),
diff --git a/app/repo/__init__.py b/app/repo/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/app/repo/git.py b/app/repo/git.py
new file mode 100644
index 0000000..38de956
--- /dev/null
+++ b/app/repo/git.py
@@ -0,0 +1,163 @@
+"""Local clone of the uploads repo and read-only queries against `origin/<branch>` (ARCHITECTURE §2.3).
+
+git runs as a subprocess with an argument list — never through a shell — and with the bot's own deploy key.
+"""
+
+import asyncio
+import base64
+import logging
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+from app.config import GitSettings
+
+log = logging.getLogger(__name__)
+
+EntryKind = Literal["dir", "file"]
+
+
+class GitError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Entry:
+    path: str  # repo-relative, "/"-separated
+    kind: EntryKind
+    size: int  # bytes; 0 for directories
+
+    @property
+    def name(self) -> str:
+        return self.path.rsplit("/", 1)[-1]
+
+
+@dataclass(frozen=True)
+class CommitInfo:
+    sha: str
+    author: str
+    date: datetime
+    subject: str
+
+
+class UploadsRepo:
+    def __init__(self, settings: GitSettings) -> None:
+        self._s = settings
+        self._dir = settings.clone_dir
+        self._lock = asyncio.Lock()
+        self._fetched_at: float | None = None
+        self._key_path = self._materialize_key()
+
+    @property
+    def ref(self) -> str:
+        return f"origin/{self._s.branch}"
+
+    @property
+    def path(self) -> Path:
+        return self._dir
+
+    def _materialize_key(self) -> Path | None:
+        if self._s.ssh_key_b64 is None:
+            return self._s.ssh_key_path
+        key = base64.b64decode(self._s.ssh_key_b64.get_secret_value())
+        fd, name = tempfile.mkstemp(prefix="tgit-ssh-")  # created 0600, owned by the bot's user
+        with os.fdopen(fd, "wb") as f:
+            f.write(key if key.endswith(b"\n") else key + b"\n")
+        return Path(name)
+
+    def _env(self) -> dict[str, str]:
+        env = {k: v for k, v in os.environ.items() if k in ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR")}
+        env["GIT_TERMINAL_PROMPT"] = "0"
+        if self._key_path is not None:
+            known_hosts = self._dir.parent / "known_hosts"
+            env["GIT_SSH_COMMAND"] = (
+                # -F /dev/null: ignore the host's ~/.ssh/config — otherwise a personal key configured there for the
+                # same host gets offered too and silently masks a broken deploy key (happened in #7).
+                f"ssh -F /dev/null -i {self._key_path} -o IdentitiesOnly=yes -o BatchMode=yes "
+                f"-o StrictHostKeyChecking=accept-new -o UserKnownHostsFile={known_hosts}"
+            )
+        return env
+
+    async def git(self, *args: str, cwd: Path | None = None) -> bytes:
+        proc = await asyncio.create_subprocess_exec(
+            "git",
+            *args,
+            cwd=cwd or self._dir,
+            env=self._env(),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            out, err = await asyncio.wait_for(proc.communicate(), timeout=self._s.timeout)
+        except TimeoutError:
+            proc.kill()
+            await proc.wait()
+            raise GitError(f"git {args[0]}: timeout") from None
+        if proc.returncode != 0:
+            raise GitError(f"git {args[0]}: {err.decode(errors='replace').strip()[-500:]}")
+        return out
+
+    async def ensure(self) -> None:
+        """Clone on first use; afterwards just make sure the clone is there."""
+        async with self._lock:
+            if (self._dir / ".git").is_dir():
+                return
+            self._dir.parent.mkdir(parents=True, exist_ok=True)
+            log.info("cloning uploads repo into %s", self._dir)
+            await self.git(
+                "clone", "--branch", self._s.branch, self._s.uploads_url, str(self._dir), cwd=self._dir.parent
+            )
+            self._fetched_at = time.monotonic()
+
+    async def refresh(self, force: bool = False) -> None:
+        """git fetch, but not more often than fetch_interval unless forced."""
+        await self.ensure()
+        async with self._lock:
+            now = time.monotonic()
+            if not force and self._fetched_at is not None and now - self._fetched_at < self._s.fetch_interval:
+                return
+            await self.git("fetch", "--prune", "origin")
+            self._fetched_at = now
+
+    async def head(self) -> str:
+        return (await self.git("rev-parse", self.ref)).decode().strip()
+
+    async def list_dir(self, path: str = "") -> list[Entry]:
+        """Directories first, then files, each alphabetically."""
+        spec = f"{self.ref}:{path}" if path else self.ref
+        try:
+            out = await self.git("ls-tree", "-z", "-l", spec)
+        except GitError as e:
+            raise GitError(f"no such directory: /{path}") from e
+        entries: list[Entry] = []
+        for record in out.split(b"\0"):
+            if not record:
+                continue
+            meta, name = record.split(b"\t", 1)
+            _mode, kind, _obj, size = meta.split()
+            full = f"{path}/{name.decode()}" if path else name.decode()
+            if kind == b"tree":
+                entries.append(Entry(full, "dir", 0))
+            elif kind == b"blob":
+                entries.append(Entry(full, "file", int(size)))
+        return sorted(entries, key=lambda e: (e.kind != "dir", e.name.lower()))
+
+    async def read(self, path: str) -> bytes:
+        return await self.git("cat-file", "blob", f"{self.ref}:{path}")
+
+    async def size(self, path: str) -> int | None:
+        try:
+            return int((await self.git("cat-file", "-s", f"{self.ref}:{path}")).decode().strip())
+        except GitError:
+            return None
+
+    async def last_commit(self, path: str) -> CommitInfo | None:
+        out = await self.git("log", "-1", "--format=%H%x00%an%x00%aI%x00%s", self.ref, "--", path)
+        if not out.strip():
+            return None
+        sha, author, date, subject = out.decode().rstrip("\n").split("\0", 3)
+        return CommitInfo(sha=sha, author=author, date=datetime.fromisoformat(date), subject=subject)
diff --git a/app/texts.py b/app/texts.py
index 2494222..e1c0724 100644
--- a/app/texts.py
+++ b/app/texts.py
@@ -54,12 +54,36 @@ class MembersTexts(_Strict):
     invite_caption: str
 
 
+class CommitTexts(_Strict):
+    title: str
+    empty: str
+    page: str
+    up: str
+    prev: str
+    next: str
+    dir_button: str
+    file_button: str
+    new_file: str
+    new_dir: str
+    file_card: str
+    last_commit: str
+    no_commits: str
+    view: str
+    replace: str
+    delete: str
+    to_dir: str
+    soon: str
+    unavailable: str
+    sent_as_file: str
+
+
 class Texts(_Strict):
     menu: MenuTexts
     start: StartTexts
     help: HelpTexts
     section: SectionTexts
     members: MembersTexts
+    commit: CommitTexts
 
 
 def load_texts(config_dir: Path) -> Texts:
diff --git a/config/texts.yaml b/config/texts.yaml
index 96984b1..9ff6a6b 100644
--- a/config/texts.yaml
+++ b/config/texts.yaml
@@ -52,3 +52,29 @@ members:
     {link}
 
     Одноразовое, действует до {expires} UTC.
+
+commit:
+  title: "📝 Коммит · /{path}"
+  empty: "Папка пуста."
+  page: "Стр. {page} из {pages}"
+  up: "⬆️ Вверх"
+  prev: "◀️"
+  next: "▶️"
+  dir_button: "📁 {name}"
+  file_button: "📄 {name} · {size}"
+  new_file: "➕ Новый файл"
+  new_dir: "📁 Новая папка"
+  file_card: |-
+    📄 /{path}
+    Размер: {size}
+  last_commit: |-
+    Последний коммит: {sha} · {author} · {date}
+    {subject}
+  no_commits: "Коммитов по файлу нет."
+  view: "👁 Показать"
+  replace: "✏️ Заменить"
+  delete: "🗑 Удалить"
+  to_dir: "⬅️ К папке"
+  soon: "Будет в следующей версии."
+  unavailable: "Репозиторий загрузок недоступен, попробуйте через минуту."
+  sent_as_file: "Файл большой или бинарный — отправил документом."
diff --git a/docker-compose.yml b/docker-compose.yml
index 34dc5ff..3639ecc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,6 +5,9 @@ services:
     env_file: .env
     environment:
       DATABASE_URL: postgresql+asyncpg://tgit:${POSTGRES_PASSWORD:-tgit}@postgres:5432/tgit
+      GIT_CLONE_DIR: /data/uploads
+    volumes:
+      - uploads:/data
     depends_on:
       postgres:
         condition: service_healthy
@@ -37,3 +40,4 @@ services:
 
 volumes:
   pgdata:
+  uploads:
diff --git a/tests/bot/test_commit.py b/tests/bot/test_commit.py
new file mode 100644
index 0000000..43f8096
--- /dev/null
+++ b/tests/bot/test_commit.py
@@ -0,0 +1,103 @@
+import pytest
+from aiogram.methods import AnswerCallbackQuery, EditMessageText, SendDocument, SendMessage
+from aiogram.types import InlineKeyboardMarkup
+
+from app.access.service import AccessService
+from app.bot.routers.commit import Act, CommitCb, human_size
+from app.db.session import SessionMaker
+from app.main import build_dispatcher
+from app.repo.git import UploadsRepo
+from app.texts import Texts
+from tests.conftest import ADMIN
+from tests.fakes import TgClient
+
+
+@pytest.fixture
+def tg(texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo) -> TgClient:
+    return TgClient(build_dispatcher(texts, sessions, access, repo))
+
+
+def labels(markup: object) -> list[str]:
+    assert isinstance(markup, InlineKeyboardMarkup)
+    return [b.text for row in markup.inline_keyboard for b in row]
+
+
+def cb(action: Act, i: int = 0) -> str:
+    return CommitCb(a=action, i=i).pack()
+
+
+async def test_root_listing(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+
+    [reply] = tg.session.sent(SendMessage)
+    assert reply.text == texts.commit.title.format(path="")
+    got = labels(reply.reply_markup)
+    assert got[:4] == ["📁 docs", "📁 many", "📁 services", "📄 README.md · 10 Б"]
+    assert texts.commit.up not in got  # already at the root
+
+
+async def test_open_dir_then_file_card_then_back(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.OPEN, 2))  # services
+    await tg.press(ADMIN, cb(Act.OPEN, 0))  # services/hello
+    await tg.press(ADMIN, cb(Act.OPEN, 0))  # services/hello/main.py
+
+    hello_dir, hello_sub, card = tg.session.sent(EditMessageText)
+    assert hello_dir.text == texts.commit.title.format(path="services")
+    assert texts.commit.up in labels(hello_dir.reply_markup)
+    assert hello_sub.text == texts.commit.title.format(path="services/hello")
+    assert card.text.startswith("📄 /services/hello/main.py") and "init" in card.text
+    assert labels(card.reply_markup) == [
+        texts.commit.view,
+        texts.commit.replace,
+        texts.commit.delete,
+        texts.commit.to_dir,
+    ]
+
+    await tg.press(ADMIN, cb(Act.TO_DIR))
+    await tg.press(ADMIN, cb(Act.UP))
+    *_, back_to_dir, up = tg.session.sent(EditMessageText)
+    assert back_to_dir.text == texts.commit.title.format(path="services/hello")
+    assert up.text == texts.commit.title.format(path="services")
+
+
+async def test_view_text_inline_and_binary_as_document(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.OPEN, 0))  # docs
+    await tg.press(ADMIN, cb(Act.OPEN, 1))  # мои заметки.md
+    await tg.press(ADMIN, cb(Act.VIEW))
+    await tg.press(ADMIN, cb(Act.TO_DIR))
+    await tg.press(ADMIN, cb(Act.OPEN, 0))  # logo.bin
+    await tg.press(ADMIN, cb(Act.VIEW))
+
+    inline = [m for m in tg.session.sent(SendMessage) if m.parse_mode == "HTML"]
+    assert len(inline) == 1 and "<pre>привет\n</pre>" in inline[0].text
+    [doc] = tg.session.sent(SendDocument)
+    assert doc.caption == texts.commit.sent_as_file
+
+
+async def test_pagination(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.OPEN, 1))  # many: 25 files
+    await tg.press(ADMIN, cb(Act.PAGE, 1))
+
+    first, second = tg.session.sent(EditMessageText)
+    assert texts.commit.page.format(page=1, pages=2) in first.text
+    assert labels(first.reply_markup)[0].startswith("📄 f00.txt") and texts.commit.next in labels(first.reply_markup)
+    assert labels(second.reply_markup)[0].startswith("📄 f20.txt") and texts.commit.prev in labels(second.reply_markup)
+
+
+async def test_unfinished_actions_and_stale_buttons(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.press(ADMIN, cb(Act.OPEN, 99))
+
+    soon, stale = tg.session.sent(AnswerCallbackQuery)
+    assert soon.text == texts.commit.soon and soon.show_alert
+    assert stale.text is None
+    assert tg.session.sent(EditMessageText) == []
+
+
+@pytest.mark.parametrize(("n", "text"), [(10, "10 Б"), (2048, "2.0 КБ"), (5 * 1024 * 1024, "5.0 МБ")])
+def test_human_size(n: int, text: str) -> None:
+    assert human_size(n) == text
diff --git a/tests/bot/test_common.py b/tests/bot/test_common.py
index 2ca8df1..1ceb285 100644
--- a/tests/bot/test_common.py
+++ b/tests/bot/test_common.py
@@ -6,14 +6,15 @@ from app.access.service import AccessService
 from app.bot.menu import Nav, NavAction
 from app.db.session import SessionMaker
 from app.main import build_dispatcher
+from app.repo.git import UploadsRepo
 from app.texts import Texts
 from tests.conftest import ADMIN, OUTSIDER
 from tests.fakes import TgClient
 
 
 @pytest.fixture
-def tg(texts: Texts, sessions: SessionMaker, access: AccessService) -> TgClient:
-    return TgClient(build_dispatcher(texts, sessions, access))
+def tg(texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo) -> TgClient:
+    return TgClient(build_dispatcher(texts, sessions, access, repo))
 
 
 def buttons(markup: ReplyKeyboardMarkup) -> list[str]:
@@ -45,7 +46,7 @@ async def test_outsider_stale_button_is_swallowed(tg: TgClient) -> None:
     assert len(tg.session.sent(AnswerCallbackQuery)) == 1
 
 
-@pytest.mark.parametrize("section", ["commit", "status", "logs", "alerts"])
+@pytest.mark.parametrize("section", ["status", "logs", "alerts"])
 async def test_menu_button_opens_section_with_nav(tg: TgClient, texts: Texts, section: str) -> None:
     await tg.send(ADMIN, getattr(texts.menu, section))
 
diff --git a/tests/bot/test_members.py b/tests/bot/test_members.py
index 5e5cfd5..7daef29 100644
--- a/tests/bot/test_members.py
+++ b/tests/bot/test_members.py
@@ -8,6 +8,7 @@ from app.access.service import AccessService
 from app.bot.routers.members import MembersAction, MembersCb
 from app.db.session import SessionMaker
 from app.main import build_dispatcher
+from app.repo.git import UploadsRepo
 from app.texts import Texts
 from tests.conftest import ADMIN
 from tests.fakes import TgClient
@@ -16,8 +17,8 @@ NEWBIE = 3003
 
 
 @pytest.fixture
-def tg(texts: Texts, sessions: SessionMaker, access: AccessService) -> TgClient:
-    return TgClient(build_dispatcher(texts, sessions, access))
+def tg(texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo) -> TgClient:
+    return TgClient(build_dispatcher(texts, sessions, access, repo))
 
 
 async def invite_token(tg: TgClient) -> str:
diff --git a/tests/conftest.py b/tests/conftest.py
index 856c49d..7b57b81 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,3 +1,4 @@
+import subprocess
 from collections.abc import AsyncIterator
 from pathlib import Path
 
@@ -5,9 +6,10 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncEngine
 
 from app.access.service import AccessService
-from app.config import AccessSettings, RuntimeSettings, Settings, TelegramSettings
+from app.config import AccessSettings, GitSettings, RuntimeSettings, Settings, TelegramSettings
 from app.db.migrate import upgrade
 from app.db.session import SessionMaker, make_engine, make_sessionmaker
+from app.repo.git import UploadsRepo
 from app.texts import Texts, load_texts
 
 ROOT = Path(__file__).resolve().parent.parent
@@ -48,3 +50,44 @@ async def access(sessions: SessionMaker, settings: Settings) -> AccessService:
     service = AccessService(sessions, settings.access)
     await service.bootstrap_admins()
     return service
+
+
+def git(cwd: Path, *args: str) -> str:
+    env = {
+        "GIT_AUTHOR_NAME": "Тест",
+        "GIT_AUTHOR_EMAIL": "t@t",
+        "GIT_COMMITTER_NAME": "Тест",
+        "GIT_COMMITTER_EMAIL": "t@t",
+        "PATH": "/usr/bin:/bin",
+        "HOME": str(cwd),
+    }
+    return subprocess.run(["git", *args], cwd=cwd, env=env, check=True, capture_output=True, text=True).stdout
+
+
+@pytest.fixture
+def remote(tmp_path: Path) -> Path:
+    """A bare 'SourceCraft' repo: services/hello, a file with a space and Cyrillic, a binary, 25 files in one dir."""
+    work = tmp_path / "seed"
+    work.mkdir()
+    git(work, "init", "-q", "-b", "main")
+    (work / "services" / "hello").mkdir(parents=True)
+    (work / "services" / "hello" / "main.py").write_text("print('hello')\n", encoding="utf-8")
+    (work / "README.md").write_text("# uploads\n", encoding="utf-8")
+    git(work, "add", "-A")
+    git(work, "commit", "-q", "-m", "init")
+    (work / "docs").mkdir()
+    (work / "docs" / "мои заметки.md").write_text("привет\n", encoding="utf-8")
+    (work / "docs" / "logo.bin").write_bytes(b"\x00\x01\x02binary")
+    (work / "many").mkdir()
+    for i in range(25):
+        (work / "many" / f"f{i:02}.txt").write_text(str(i), encoding="utf-8")
+    git(work, "add", "-A")
+    git(work, "commit", "-q", "-m", "docs and many")
+    bare = tmp_path / "remote.git"
+    git(tmp_path, "clone", "-q", "--bare", str(work), str(bare))
+    return bare
+
+
+@pytest.fixture
+def repo(remote: Path, tmp_path: Path) -> UploadsRepo:
+    return UploadsRepo(GitSettings(uploads_url=str(remote), clone_dir=tmp_path / "clone", fetch_interval=0))
diff --git a/tests/repo/__init__.py b/tests/repo/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/repo/test_git.py b/tests/repo/test_git.py
new file mode 100644
index 0000000..98a0be4
--- /dev/null
+++ b/tests/repo/test_git.py
@@ -0,0 +1,85 @@
+from pathlib import Path
+
+import pytest
+
+from app.repo.git import GitError, UploadsRepo
+from tests.conftest import git
+
+
+async def test_clone_and_list_root_dirs_first(repo: UploadsRepo) -> None:
+    await repo.refresh()
+
+    entries = await repo.list_dir()
+    assert [(e.name, e.kind) for e in entries] == [
+        ("docs", "dir"),
+        ("many", "dir"),
+        ("services", "dir"),
+        ("README.md", "file"),
+    ]
+    assert entries[-1].size == len("# uploads\n")
+
+
+async def test_unicode_and_spaces_in_names(repo: UploadsRepo) -> None:
+    await repo.refresh()
+
+    names = [e.path for e in await repo.list_dir("docs")]
+    assert names == ["docs/logo.bin", "docs/мои заметки.md"]
+    assert (await repo.read("docs/мои заметки.md")).decode() == "привет\n"
+
+
+async def test_last_commit_per_path(repo: UploadsRepo) -> None:
+    await repo.refresh()
+
+    hello = await repo.last_commit("services/hello/main.py")
+    docs = await repo.last_commit("docs/logo.bin")
+    assert hello is not None and hello.subject == "init" and hello.author == "Тест"
+    assert docs is not None and docs.subject == "docs and many" and len(docs.sha) == 40
+
+
+async def test_missing_dir_is_an_error(repo: UploadsRepo) -> None:
+    await repo.refresh()
+    with pytest.raises(GitError, match="no such directory"):
+        await repo.list_dir("nope")
+
+
+async def test_refresh_sees_new_commits_and_respects_interval(repo: UploadsRepo, remote: Path, tmp_path: Path) -> None:
+    await repo.refresh()
+    before = await repo.head()
+
+    other = tmp_path / "other"
+    git(tmp_path, "clone", "-q", str(remote), str(other))
+    (other / "new.txt").write_text("x", encoding="utf-8")
+    git(other, "add", "-A")
+    git(other, "commit", "-q", "-m", "new")
+    git(other, "push", "-q", "origin", "main")
+
+    await repo.refresh()
+    assert await repo.head() != before
+    assert "new.txt" in [e.name for e in await repo.list_dir()]
+
+
+async def test_fetch_is_throttled(remote: Path, tmp_path: Path) -> None:
+    from app.config import GitSettings
+
+    throttled = UploadsRepo(GitSettings(uploads_url=str(remote), clone_dir=tmp_path / "c2", fetch_interval=3600))
+    await throttled.refresh()
+    head = await throttled.head()
+    other = tmp_path / "o2"
+    git(tmp_path, "clone", "-q", str(remote), str(other))
+    (other / "x.txt").write_text("x", encoding="utf-8")
+    git(other, "add", "-A")
+    git(other, "commit", "-q", "-m", "x")
+    git(other, "push", "-q", "origin", "main")
+
+    await throttled.refresh()
+    assert await throttled.head() == head  # within the interval: no fetch
+    await throttled.refresh(force=True)
+    assert await throttled.head() != head
+
+
+async def test_unreachable_remote(tmp_path: Path) -> None:
+    from app.config import GitSettings
+
+    broken = UploadsRepo(GitSettings(uploads_url=str(tmp_path / "missing.git"), clone_dir=tmp_path / "c3"))
+    with pytest.raises(GitError, match="clone"):
+        await broken.refresh()